agent-progress-visualizer

Agent 进度可视化工具

此技能用于为 UI/UX Agent Skill System 项目创建并维护面向用户的进度控制面板。它会将规范任务计划状态转换为通俗易懂的 HTML，供非技术用户查看。

它不会执行项目任务，也不负责维护规范状态。在规划之前，project-request.json 和 workflow-log.jsonl 仅作为启动信息来源。规划完成后，TASK-PLAN.md 将成为事实来源。

运行模式

• bootstrap：系统接受重要的用户请求后，立即创建首个可见的进度界面，无需等待 TASK-PLAN.md。
• init：TASK-PLAN.md 创建后，根据任务计划生成首个进度状态和进度界面，或替换现有内容。
• update：任务计划、报告、制品、反馈或 wiki 发生变化后，重新生成状态和 HTML。
• review：检查现有进度界面是否存在事实来源偏差、虚假状态、隐私泄露或令人困惑的文案。
• feedback-gate：展示用户的决定和评论，然后将其交由 design-feedback-collector 处理。
• developer-view：显示技术任务 ID、技能路由、依赖关系和制品路径，不更改面向客户的文案。

必需工作流

1. 阅读 references/data-source-contract.md。
2. 阅读 references/decision-framework.md。
3. 阅读 references/safety-boundaries.md。
4. 在 bootstrap 模式下，不要等待 TASK-PLAN.md。立即创建 project-request.json、追加写入 workflow-log.jsonl、构建精简的 progress-state.json、渲染 agent-progress-screen.html，并在浏览器中打开它。在本地项目实现中，使用 bootstrap_progress_screen.py --open-browser。
5. 启动界面创建后，将流程转交给 task-plan-v2-orchestrator，以创建规范的 TASK-PLAN.md。
6. 在 init 或 update 模式下，查找规范的 TASK-PLAN.md。如果不存在规范任务计划且尚未运行 bootstrap，先运行 bootstrap，然后将流程转交给 task-plan-v2-orchestrator。
7. 根据规范任务计划中的字段、报告、制品、反馈状态和经过脱敏处理的 wiki 决策，构建或更新 progress-state.json。
8. 如果存在已声明的旅程，则从旅程注册表中纳入 journey_alignment，并将跳过、返工或阻塞决策交由 workflow-compliance-supervisor 处理。
9. 将 agent-progress-screen.html 渲染为派生视图。不要只编辑 HTML 而不更改状态。
10. 在任务计划派生的 init 模式下，渲染 HTML 后立即在浏览器中打开。在本地项目实现中，将 --open-browser 传递给 render_progress_screen.py。在 update 模式下，只有用户提出要求或正在查看时才打开。
11. 对于用户的选择、评论、批准或拒绝，将持久化记录交由 design-feedback-collector 处理。
12. 对于跨多个会话的大型项目，完成脱敏后，将已接受的决策交由 project-wiki-manager 处理。
13. 在宣称进度界面已就绪之前，验证其一致性。

事实来源规则

• 在 bootstrap 模式下，project-request.json 和 workflow-log.jsonl 是临时启动信息来源。
• 规划完成后，TASK-PLAN.md 是规范来源。
• progress-state.json 是派生的机器可读状态。
• agent-progress-screen.html 是派生的可视化层。
• 如果 Markdown、JSON 和 HTML 内容不一致，应先修正 Markdown 或生成器，再重新生成。
• 仅保存在浏览器 localStorage 或剪贴板中的状态，不能作为决策的唯一记录。

生成内容

默认本地制品：

project-request.json
TASK-PLAN.md
progress-state.json
agent-progress-screen.html
workflow-log.jsonl
feedback/progress-feedback-register.schema.json
reports/progress-validation-summary.txt

如果项目需要在生成器就绪前准备初始状态，请使用 assets/progress-state.template.json。

人类语言规则

• 客户模式显示“正在收集搜索查询”，而不是 serp-keyword-harvester。
• 客户模式显示“等待您选择”，而不是 required_approvals。
• 开发者模式可以显示任务 ID、技能路由、依赖项和产物路径。
• 绝不显示机密、令牌、恢复码、Cookie、.env 值、私人截图或私人 URL。

验证

使用本地项目实现时，优先执行以下检查：

python3 "$UIUX_SKILL_SYSTEM_ROOT/scripts/bootstrap_progress_screen.py" --project-root "$PROJECT_ROOT" --project-title "$PROJECT_TITLE" --user-request "$USER_REQUEST" --journey-registry "$UIUX_SKILL_SYSTEM_ROOT/data/journey-registry.json" --declared-journey new-premium-site --open-browser
python3 "$UIUX_SKILL_SYSTEM_ROOT/scripts/check_bootstrap_progress.py" --project-root "$PROJECT_ROOT"
python3 "$UIUX_SKILL_SYSTEM_ROOT/scripts/generate_progress_state.py" --task-plan "$UIUX_SKILL_SYSTEM_ROOT/TASK-PLAN.md" --out "$UIUX_SKILL_SYSTEM_ROOT/progress-state.json"
python3 "$UIUX_SKILL_SYSTEM_ROOT/scripts/render_progress_screen.py" --state "$UIUX_SKILL_SYSTEM_ROOT/progress-state.json" --out "$UIUX_SKILL_SYSTEM_ROOT/agent-progress-screen.html"
python3 "$UIUX_SKILL_SYSTEM_ROOT/scripts/check_progress_consistency.py" --task-plan "$UIUX_SKILL_SYSTEM_ROOT/TASK-PLAN.md" --state "$UIUX_SKILL_SYSTEM_ROOT/progress-state.json" --html "$UIUX_SKILL_SYSTEM_ROOT/agent-progress-screen.html"
python3 "$UIUX_SKILL_SYSTEM_ROOT/scripts/validate_workflow_compliance.py" --fixtures
python3 "$UIUX_SKILL_SYSTEM_ROOT/scripts/no_secret_scan.py" "$UIUX_SKILL_SYSTEM_ROOT"

首次创建面向用户的项目进度页面时，如果 TASK-PLAN.md 尚不存在，请通过打开浏览器来引导初始化：

python3 "$UIUX_SKILL_SYSTEM_ROOT/scripts/bootstrap_progress_screen.py" --project-root "$PROJECT_ROOT" --project-title "$PROJECT_TITLE" --user-request "$USER_REQUEST" --open-browser

TASK-PLAN.md 创建后，请将引导初始化状态替换为基于任务计划生成的状态：

python3 "$UIUX_SKILL_SYSTEM_ROOT/scripts/render_progress_screen.py" --state "$PROJECT_ROOT/progress-state.json" --out "$PROJECT_ROOT/agent-progress-screen.html" --open-browser

技能包检查：

python3 $CODEX_HOME/skills/.system/skill-creator/scripts/quick_validate.py $CODEX_HOME/skills/agent-progress-visualizer
python3 $CODEX_HOME/skills/senior-skill-architect/scripts/lint_production_skill.py $CODEX_HOME/skills/agent-progress-visualizer

交接格式

Progress mode:
Bootstrap request:
Canonical task plan:
Generated state:
Generated HTML:
User gates:
Feedback artifact:
Wiki sync:
Checks run:
Skipped checks:
Next owner: