页面

其他 社区

技能解读

当前原文的自动摘译,尚未人工审校。

应用程序页面与应用程序边界

默认情况下,将 apps-pages 视为与应用程序无关的分析 sidecar。页面应检查所选活动应用程序中的工件、清单、指标或设置;它不应该拥有域工作流程。在将 Streamlit 表面推广为应用程序页面之前,请检查它是否生成自己的数据集、训练模型、运行优化器、拥有证据

应用程序参数表单和侧边栏控件

自定义 app_args_form.py 视图是应用程序 UI,而不是应用程序页面。当应用程序需要 ORCHESTRATE 中的持久执行字段时,请使用它们。对于紧凑的应用程序特定控件,请将agi_env.streamlit_args.render_form与显式容器一起使用,例如st.sidebar:render_form(defaults_model, container=st.sidebar)。

会话状态规则(避免常见崩溃)

创建具有 key="k" 的小部件后,切勿分配 st.session_state["k"] = …。在小部件之前更喜欢st.session_state.setdefault("k", default)。或者使用小部件返回值并单独计算派生状态。不要同时预置 st.session_state[key] 并传递同一键控小部件的小部件默认值/值/索引。选择一个初始化源:

推荐图案

使用页面顶部的setdefault初始化默认值。渲染小部件。从小部件读取值,计算派生状态,存储在不同的键下。

项目范围的状态模型

如果页面可以在一个 Streamlit 会话中的项目/应用程序之间切换,则属于特定项目的任何持久小部件状态都必须使用项目范围的键。更喜欢像f"cluster_pool__{app_name}"这样的图案,而不是"cluster_pool"。将相同的规则应用于切换、文本输入、密码/身份验证字段、调度程序/工作人员字段以及类似的每个项目控件。为持久设置保留一个明确的事实来源。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
通用
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
94 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@ThalesGroup · BSD-3-Clause (see repo LICENSE)
上下文用量评级
中等消耗
接入复杂程度
需手动接入
是否需要外部接口密钥
不需要
兼容的系统
macOS · Linux · Windows
运行环境要求
Node.js · Python
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 命令执行
  • 读取环境变量
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# Streamlit Pages Skill (AGILAB)

Use this skill when editing:
- `src/agilab/main_page.py`
- `src/agilab/pages/*.py`
- `src/agilab/apps-pages/*/src/*/*.py`
- custom `app_args_form.py` views in AGILAB-managed app repos

## Apps-Pages Versus Apps Boundary

- Treat `apps-pages` as app-agnostic analysis sidecars by default. A page should
  inspect artifacts, manifests, metrics, or settings from the selected active
  app; it should not own the domain workflow.
- Before promoting a Streamlit surface as an apps-page, check whether it
  generates its own dataset, trains a model, runs an optimizer, owns evidence
  generation, or encodes project-specific semantics. If yes, it is probably an
  app project with a companion analysis page, not a generic page bundle.
- If a self-contained teaching surface must stay under `apps-pages` for
  packaging or launch reasons, document it as an explicit opt-in playground or
  exception. Do not describe it as a generic app-agnostic view.
- Prefer the split architecture when the surface has both execution and review
  concerns: the app owns reproducible execution and artifact/evidence export;
  the page reads those artifacts and renders the analysis.
- AGILAB app projects do not always need workers. Use a workerless app template
  for local/UI prototypes, notebook-derived tools, explainers, and reports that
  can write artifacts from the manager process. Use a worker template only when
  the app needs AGILAB Install/Execute worker deployment, Dask, worker-specific
  dependencies, or a distributed task plan.

## App Args Forms And Sidebar Controls

- Custom `app_args_form.py` views are app UI, not apps-pages. Use them when an
  app needs persisted execution fields in ORCHESTRATE.
- For compact app-specific controls, use `agi_env.streamlit_args.render_form`
  with an explicit container such as `st.sidebar`:
  `render_form(defaults_model, container=st.sidebar)`.
- Keep the capability generic in `agi_env.streamlit_args`; do not hard-code a
  project name or page bundle just because one app wants sidebar controls.
- If a Streamlit surface owns training, optimization, generated data, or
  evidence export, make it an app project first. Keep any app-owned standalone
  Streamlit surface under that app project unless a separate generic analysis
  page reads only exported artifacts.
- For an app-owned Streamlit surface that should appear as the app's primary
  ANALYSIS experience, declare `[app_surface]` in the app's `app_settings.toml`
  with a project-local entrypoint such as `pytorch_playground/app_surface.py`.
  Use `[pages] restrict_to_view_module = true` for app-surface-first projects;
  an empty or missing `pages.view_module` may be migrated to the virtual
  `view_app_ui` launcher so the app surface is selected and visible in the
  ANALYSIS sidebar. Do not create a generic `apps-pages/view_<app>` bridge for
  this.
- Treat `view_app_ui` as an internal route key, not a user-facing label. Sidebar
  links for app surfaces should use `[app_surface].title`, route through the app
  surface renderer, and avoid exposing duplicate `view_app_ui` bridge links.
- Keep the standard ANALYSIS view multiselect usable for app-surface projects:
  `view_app_ui` may be the default selected sidebar launcher, but users must
  still be able to add other installed analysis views through the same existing
  selector instead of a custom "additional views" control.
- Render an ANALYSIS sidebar launcher from one place per page route. If the main
  page persists selected views after rendering controls, do not also render the
  same project label or app-surface link before the main-page body; add a
  regression assertion that the compact project caption and app-surface link
  appear exactly once.

## Session State Rules (Avoid Common Crashes)

- Never assign `st.session_state["k"] = …` **after** a widget with `key="k"` was created.
  - Prefer `st.session_state.setdefault("k", default)` before the widget.
  - Or use widget return values and compute derived state separately.
- Do not both pre-seed `st.session_state[key]` and pass a widget default/value/index for
  the same keyed widget. Pick one source of initialization:
  - use the widget default and leave `st.session_state` untouched before creation, or
  - pre-seed `st.session_state` before creation and omit the widget default.
  This avoids Streamlit warnings such as "created with a default value but also had its
  value set via the Session State API".
  Shared widget wrappers should drop their default argument when the key already
  exists in session state.

- If you need to “reset” a widget value:
  - Use a different key (versioned key pattern), or
  - Gate the reset behind a rerun and only mutate state before widget creation.
- When Streamlit raises a duplicate-widget ID error, check whether the page or
  app surface is being rendered twice before only adding widget keys. Add stable
  keys for repeated controls, but fix duplicate entrypoint execution at the
  source.

## Recommended Pattern

1. Initialize defaults with `setdefault` at the top of the page.
2. Render widgets.
3. Read values from widgets, compute derived state, store under *different* keys.

## Project-Scoped State Models

- If a page can switch between projects/apps in one Streamlit session, any persisted widget state that belongs to a specific project must use project-scoped keys.
  - Prefer patterns like `f"cluster_pool__{app_name}"`, not `"cluster_pool"`.
  - Apply the same rule to toggles, text inputs, password/auth fields, scheduler/worker fields, and similar per-project controls.
- Keep one clear source of truth for persisted settings.
  - File-backed or workspace-backed `app_settings` should hydrate widget keys on page init and after project switches.
  - Do not let a stale widget key silently override freshly loaded settings just because it already exists in `st.session_state`.
- On project change:
  - compute any preservation/override decision before popping tracking keys from `st.session_state`
  - then clear the old project's widget keys explicitly
  - then rehydrate the new project's widget state from persisted settings
- Treat `app_settings["cluster"]`, `app_settings["args"]`, or equivalent persisted payloads as the serializable config contract.
  - Widget keys are UI transport, not a second config layer.

## Page Bootstrap And Path Drift

- At page start, resolve the active app and apps root from the current launch context first:
  explicit CLI args, current source checkout, and packaged runtime location. Only then consult
  persisted user settings.
- Do not let stale persisted state override the current launch root:
  - `~/.agilab/.env`
  - `~/.local/share/agilab/.agilab-path`
  - a previous `st.session_state["env"]`
  - a previous `active_app` or `APPS_PATH`
- If the launch context says the page is running from source, UI readiness cards such as
  ORCHESTRATE `Manager env` must point at the source app path, not `$HOME/agi-space`.
- When the resolved app root changes, rebuild or realign the session `env` object before
  rendering headers, buttons, or action state. Rendering first and repairing later leaves
  stale paths visible to users and can make action buttons operate on the wrong project.
- Add regressions for both cold sessions and warm sessions with stale `st.session_state`
  when touching page bootstrap, sidebar project selection, or ORCHESTRATE header state.

## Derived Preview Metrics

- Treat previews as read-only explanations, not as another persisted config source.
- Compute any preview metric from the same backend helper used by the runtime or exported summary artifact.
- If a preview depends on existing generated files, label it explicitly as a previous-run value (for example, `Last generated ...`) rather than implying it reflects the current unsaved inputs.
- When both are available, show the distinction clearly:
  - current preview from present inputs
  - last generated metric from persisted output
- Do not write preview-only values back into `app_settings.toml` unless they are real app args.

## Cross-Page UX and KPI Headers

- Keep sidebar text short and action-oriented. Remove labels that only restate the active
  project/page or explain obvious scope such as "actions below apply to this project".
- Keep shared page chrome minimal. Do not add global active-project labels,
  chips, or badges above page controls; the selected project belongs in the
  selector, the sidebar, or an explicitly opened context expander.
- Before reusing or renaming a visible action label, compare its meaning across
  PROJECT, ORCHESTRATE, WORKFLOW, ANALYSIS, SETTINGS, sidebars, and robot click
  labels. Avoid same-label/different-contract collisions; scope labels by
  object and layer, for example `Install agi-app` for package/catalog install
  and `Deploy workers` for manager/worker environment deployment.
- Preserve stable lower-level API names when product copy changes. In
  ORCHESTRATE, `Deploy workers` can correctly call `AGI.install`: the API
  prepares manager and worker runtime environments and reuses an already-ready
  local manager environment rather than forcing a reinstall.
- For visible-label cleanup, search every render path before closing the task:
  page files, `main_page.py`, `page_bootstrap.py`, `workflow_ui.py`,
  `page_project_selector.py`, lazy-import wrappers, CSS class names, and tests.
  Add or update a negative regression assertion for removed text so tests do
  not encode newly introduced clutter as expected behavior.
- Prefer page headers with a few read-only KPI cards over status banners that say
  `ready`, `not set`, or `missing` without useful context.
- Use the same visual semantics across pages:
  - green only for verified positive values
  - amber for incomplete, missing, or no-evidence-yet values
  - neutral for identity or purely informational values
- Do not color a value green just because it is present when the value means "no run",
  "not configured", or "no artifact discovered".
- Use product-facing labels instead of internal implementation terms:
  - `Workflow graph` instead of `DAG shape`
  - `Stages` and `dependencies` for project workflow instead of graph-only jargon such as nodes and edges
  - `Plan`, `steps`, `outputs`, `Creates`, and `Uses` for multi-app workplans
    before technical DAG, artifact, node, or edge wording
  - hide generated graphs behind an explicit `Show graph` control when the
    graph can be too small to read
  - `Project name` when the widget selects a project
- Derived header values must be computed locally from existing evidence when possible.
  For example, count ORCHESTRATE runs from `run_*.log` files under the app run
  environment instead of adding another persisted setting.
- When a page references a machine-readable evidence file such as
  `run_manifest.json`, `evidence_graph.json`, `workflow_run_manifest.json`,
  `notebook_export_manifest.json`, or a dry-run report, do not stop at showing
  the file path. Render a compact human inspection surface for the contents:
  status, counts, schema, key rows, validation issues, and artifact links. Keep
  the raw path visible for audit/replay.
- When a generic page has no app-specific semantic data, show an honest fallback such
  as execution stages, output files, or discovered dataframes rather than inventing a
  domain-specific metric.
- Keep one navigation surface per action. If a page already exposes compact sidebar
  launch links, do not duplicate the same action as in-page sidecar cards, repeated
  `Open` buttons, or another selector unless the second surface adds a distinct
  workflow stage.
- For lightweight page routing, prefer compact Markdown/HTML links with encoded
  query parameters such as `current_page` over a selectbox plus `Open` button when
  the user only needs to jump to a target. Add a tiny helper to construct and test
  the encoded URL instead of inlining query-string formatting in the render block.
- Treat legacy “default view” UI as configuration debt when a project already has a
  selected view list. Persist the selected list in `pages.view_module`; remove stale
  `default_view`/`default_views` values only when that behavior is intentionally
  replaced by the new launcher model.
- With `st.navigation`, `st.switch_page` targets must be the main app file or an
  exact file under `pages/` relative to the Streamlit entrypoint. Do not hard-code
  stale numeric filenames such as `pages/3_WORKFLOW.py`; route through central
  page constants and add a focused test when a wizard button or deep link opens
  another page.
- For wizard/deep-link actions that need the destination page to open a drawer,
  selector, upload area, or run action, set a non-widget intent key before
  navigation and consume it once on the destination page. Clear the intent before
  rerunning so the link cannot recursively navigate or keep the app in a loading
  loop.
- Update focused page tests when changing visible labels, header cards, or sidebar
  structure. Grep old wording before closing the task so stale copy does not survive in
  tests, docs, or screenshots.
- When replacing a single-item action with a batch action, keep button labels compact
  unless the extra word is needed to prevent misuse. Put selection semantics in the
  selector label/help text and assert the exact end-user button labels in focused page
  tests so stale wording such as `Update selected` or `Remove selected` cannot survive
  after a product copy decision.

## First-Proof Onboarding UX

- Treat the first-proof panel as a new-user wizard, not as an expert shortcut
  list. Every visible action must state whether it runs the built-in demo,
  imports AGILAB's included notebook, or uploads the user's own notebook.
- Do not hide packaged sample assets behind vague labels such as `example
  notebook` when the user cannot know where that file is. Prefer explicit copy
  such as `Create from built-in notebook`, say that no file needs to be found
  or uploaded, and show the project that will be created.
- Keep first-proof alternatives simple: the built-in demo lane should expose
  install, run, and analysis actions; the notebook lane should expose the
  included sample. Keep local notebook upload in PROJECT Create instead of
  adding another direct uploader to the ABOUT wizard.
- When changing first-proof labels, update ABOUT tests, PROJECT notebook-import
  tests, newcomer docs, and stale-wording greps in the same change.

## App-Specific Page Defaults

- Prefer app-declared defaults in `app_settings.toml` over page-level hardcoded paths.
- For apps-pages, use `pages.<page_name>` for app-specific defaults that should be portable across apps and machines.
- Remember that versioned app seeds and workspace settings are different:
  - `src/.../app_settings.toml` is only the seed.
  - mutable user/HF settings can live under `~/.agilab/apps/<app>/app_settings.toml`.
  - if a bug is caused by a stale default already persisted in the workspace, changing only the seed will not fix existing deployments.
- When changing app analysis defaults, add a narrow migration for the stale workspace value when needed.
  - Scope migrations to the affected app and legacy value.
  - Preserve custom user defaults when the legacy value is absent.
  - Write the migrated config before widgets/options are built.
- For app/page visibility, prefer explicit exclusions over global restrictions when the app should still see generic pages.
  - Example: for `flight_project`, exclude `view_maps_network` while keeping generic views such as `view_maps`, `view_maps_3d`, and `view_barycentric` available.
  - Avoid setting a broad `restrict_to_view_module` unless hiding every undeclared generic view is the intended product behavior.
- For `view_maps_network`, supported defaults now include:
  - `dataset_base_choice`
  - `dataset_custom_base`
  - `dataset_subpath`
  - `default_traj_globs`
  - `default_allocation_globs`
  - `default_baseline_globs`
  - `cloudmap_sat_path`
  - `cloudmap_ivdl_path`
- Keep persisted `view_maps_network` state for user choices, but put repo/app conventions under `pages.view_maps_network`.

## DAG And Worker-Type UI

- For generic ORCHESTRATE/WORKFLOW page behavior that depends on whether an app is
  DAG-based, use `AgiEnv.base_worker_cls` first. `AgiEnv` already populates this
  from worker source inspection, so page code should not import app worker classes
  just to decide which controls to show.
- Treat `DagWorker`, known DAG-derived workers such as `Sb3TrainerWorker`, and
  custom `*Dag*Worker` base names as DAG-capable for UI decisions.
- Keep name-token fallbacks narrow and explicit for planning-only or synthetic apps
  that intentionally have no DAG worker base yet, such as multi-app DAG draft/demo
  projects.
- Reuse one helper for DAG detection across sidebars, execute controls, and
  distribution/workplan rendering. Do not leave page-local string checks such as
  `endswith("dag-worker")`; they drift from the `AgiEnv` contract and silently fail
  for real base names like `DagWorker`.
- DAG-only planning projects should expose run/workflow actions, not dataframe
  load/export/delete controls, unless the app has an explicit dataframe artifact
  contract.

## Rerun API

- Do not use `st.experimental_rerun()`; use `st.rerun()`.

## Diagnostics Rendering

- Render long diagnostics and tracebacks as code blocks, not message-box text:
  - `st.error("Short actionable summary.")`
  - `st.caption("Full diagnostic")`
  - `st.code(diagnostic_text, language="text")`
- Do not embed Markdown code fences inside `st.error()` or `st.code()`.
- Do not pass `traceback.format_exc()` directly to `st.error()`; Streamlit message
  boxes collapse readability and can flatten newlines.
- If a diagnostic arrives as a single long line, format a display-only copy with
  line breaks or wrapping before passing it to `st.code`; keep the original
  exception/message unchanged for logs and assertions that depend on exact text.
- Add a focused helper test for display formatting and keep the repository scan
  guard in `test/test_streamlit_diagnostic_rendering.py` green when touching
  diagnostic rendering paths.

## Action Results and Runtime Logs

- Do not classify a page action as failed only because stderr is non-empty.
  AGILAB runtime helpers, package managers, and subprocess wrappers may write
  normal progress or warnings to stderr.
- Treat action success/failure as a typed result contract first:
  - subprocess return code or raised exception
  - `ActionResult.status`
  - explicit fatal markers in logs such as tracebacks, non-zero exit status,
    missing imports, or worker/build failure phrases
- Keep log classifiers narrow. Avoid broad predicates such as `"failed" in line`
  unless the surrounding phrase is part of a known fatal contract; benign warnings
  can contain words like `failed`.
- Apply the same action-result semantics to sibling workflow actions. If INSTALL
  and RUN already use typed results or fatal-log heuristics, do not leave CHECK,
  DISTRIBUTE, LOAD, EXPORT, or service actions on older `stderr == failure` rules.
- Add a regression with a realistic noisy stderr log for any action whose runtime
  can emit progress on stderr. The regression should prove benign stderr stays
  successful and a concrete fatal marker still fails.

## WORKFLOW Assistant UX

- Default generated dataframe work to a safe-action mode: the model returns a
  versioned JSON action contract, AGILAB validates it, and the UI displays the
  deterministic pandas code derived from that contract.
- Keep raw Python generation as an explicit advanced choice with clear wording.
  Do not imply a container or VM is required for the normal safe-action path.
- Persist the generation mode and action contract beside the saved stage so a
  reopened `lab_stages.toml` explains whether code came from safe actions or
  raw Python.
- When generation fails validation, keep the existing stage code intact and show
  the contract error; do not silently replace it with partial or arbitrary code.

## Long-Running Action Timers

- For long async actions such as ORCHESTRATE install/run/serve, render a live
  elapsed-time placeholder before awaiting the subprocess or background task.
- Prefer `asyncio.create_task(...)`, yield once with `await asyncio.sleep(0)`,
  then poll at a short fixed interval and update the placeholder until the task
  is done. Do not depend only on log callbacks; quiet processes still need a
  visible timer.
- Keep the final duration visible after completion and record it in action
  history when that history is user-facing evidence.
- Store timer values under non-widget session-state keys such as
  `last_run_elapsed_seconds` and `last_run_elapsed_label`; never mutate a key
  already owned by a rendered widget.
- Add focused tests for both the formatting helper and the action path that
  records the elapsed label, without requiring a real long-running process.

## Key Hygiene

- Every widget must have a stable, unique key.
- Prefer namespaced keys: `f\"{page_id}:df_files\"`, not `"df_files"`.

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。