页面
- 作者仓库星标 15
- 许可证 BSD-3-Clause (see repo LICENSE)
- 作者仓库 agilab
- 领域
- 通用
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 94 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @ThalesGroup · BSD-3-Clause (see repo LICENSE)
- 上下文用量评级
- 中等消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- Node.js · Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 读取环境变量
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# 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"`.
章节与文件索引
按说明文件中的顺序排列。
应用程序页面与应用程序边界
应用程序参数表单和侧边栏控件
会话状态规则(避免常见崩溃)
推荐图案
项目范围的状态模型
文件/命令 -> src/agilab/main_page.py · src/agilab/pages/*.py · src/agilab/apps-pages/*/src/*/*.py · app_args_form.py · apps-pages · agi_env.streamlit_args.render_form · st.sidebar · render_form(defaults_model, container=st.sidebar)
内容校验值 -> 61d722069ce2
当前原文的自动摘译,尚未人工审校。
应用程序页面与应用程序边界
默认情况下,将
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"。将相同的规则应用于切换、文本输入、密码/身份验证字段、调度程序/工作人员字段以及类似的每个项目控件。为持久设置保留一个明确的事实来源。