agent-Specialization/docs/workflow_feature_plan.md

工作流（Workflow）功能设计方案

状态：设计已讨论定稿（2026-08-18），待实施。 调研依据：workflow_research/external_products/agentic_workflow_research.md（外部产品）、workflow_research/code_mount_points/code_mount_points.md（代码挂载点）。

1. 功能定义

用户把「一套既定流程：工作方式 → 验证方式 → 结束方式」存为一个工作流（workflow），之后在任何普通对话中激活它，让主智能体复用现有循环与执行引擎按流程推进；阶段结束/整体结束时可由审核智能体软审核。

核心原则（来自外部调研共识）：结构在边上，自主在节点内——工作流只约束阶段顺序与进出契约，阶段内主智能体完全自主（自由调工具、跑脚本）。

2. 已拍板的设计决策

决策点	结论
运行方式	不做独立模式/特殊 URL/新对话类型，只能在正常对话中激活
激活入口	/ 菜单（slash 菜单），新增 workflows 模式选择要激活的工作流（仿 skills 模式）
前后端通信	轮询（复用 task 轮询 session_data 快照链路，不新增 websocket 通道）
状态隔离	对话级状态，多对话可同时激活不同工作流，进度互不串扰
审核机制	复用审核智能体架构（goal_review_agent.py 模式），审核智能体可调用只读 run_command 取证
硬校验	不做步骤级硬校验；只做归档时结构校验（frontmatter 合法、阶段 id 唯一等）
存储形态	工作流文件夹 = WORKFLOW.md（frontmatter 结构 + 自然语言正文）+ scripts/（已验证脚本）+ references/（可选），与 skill 对齐

3. 存储与落盘位置

模式	用户工作流库	说明
host	~/.astrion/astrion/host/workflows/	统一，不按用户拆（对齐 CUSTOM_SKILLS_DIR）
docker/web	users/<user>/personal/workflows/	每用户私有，多项目共享（对齐 infer_private_skills_dir）

• 源码树 workflows/ 只放内置示例种子，双源合并（对齐 agentskills/ + CUSTOM_SKILLS_DIR）。
• 归档工具 create_workflow：校验 → shutil.move → 已存在拒绝覆盖（复用 archive_skill_directory 模式）。
• 运行时状态：{workspace.data_dir}/workflow_states/<conversation_id>.json（对话级，压缩 handoff 点处理 key 迁移）。

4. WORKFLOW.md 格式（草案，实施时可微调）

---
name: code-review-pipeline
description: 代码评审标准流程
review_mode: active          # 审核智能体是否可调用只读 run_command 取证
max_stage_rounds: 20         # 单阶段最大轮数，防死循环
stages:
  - id: explore
    name: 代码探索
    goal: 理解改动范围与相关模块
    review: false
  - id: review
    name: 逐项评审
    goal: 按 checklist 评审每个文件
    review: true
    review_prompt: 检查是否遗漏边界条件和安全问题
  - id: report
    name: 输出报告
    goal: 生成结构化评审报告
    review: true
end_conditions: 报告落盘且审核通过
---

# 工作方式 / 验证方式 / 结束方式（自然语言正文，随阶段上下文注入）

• 阶段默认线性推进；on_pass / on_fail 可跳转指定阶段（一期线性+有限跳转，不做完整 DAG）。
• 结构校验在归档时做（name/description/stages 存在、id 唯一、跳转目标存在）；内容质量交给审核智能体。

5. 运行时机制（全部复用现有引擎）

• 主循环不新增：复用 process_message_task 门闸 + handle_task_with_sender 迭代。
• 拦截点：server/chat_flow_task_main.py 的 if not tool_calls: 分支，与 goal 分支平排新增 workflow 分支：
  • 当前阶段 review=false → 推进下一阶段，注入新阶段上下文，continue 主循环
  • review=true → WorkflowReviewAgent 审核 → pass 推进 / retry 则 inject_runtime_user_message 续命
  • 最后阶段通过 → 整体结束审核 → mark_done
  • 边界保护：max_stage_rounds、空转保护（仿 REASON_IDLE_NO_TOOL）、用户取消
• 压缩维持：状态落盘 + handle_task_with_sender 入口检查活跃状态并重注入当前阶段上下文（对齐 goal 的 inject_goal_prompt 重注入模式）。
• 编排模块：新增 server/workflow_flow.py（仿 server/goal_flow.py），减少对主循环侵入。
• 审核智能体：新增 modules/workflow_review_agent.py（fork goal_review_agent.py），内部工具 report_workflow_stage_status（pass/retry/complete），active 模式注入只读 run_command；配置走 resolve_deploy_config("workflow_review.json") 回退链。

6. 通信与前端

• 轮询链路（现成）：sender 事件 → session_data 快照（server/tasks/models.py L763 模式）→ REST 轮询透传（server/tasks/api.py L269 模式）→ 前端 taskPolling/lifecycle.ts case 消费。
  • 新增事件：workflow_progress / workflow_review_progress / workflow_completed / workflow_stopped。
  • socket 事件 data 必须带 conversation_id，前端按当前对话过滤，保证多对话不串。
• 激活：InputComposer.vue slash 菜单新增 workflows 模式（数据 GET /api/workflows），root 菜单加「工作流」入口；激活/退出走 REST（POST /api/workflow/activate|deactivate）。
• 进度展示：仿 goal 进度组件——当前阶段 x/N · 阶段名 · 审核状态 · 轮数。
• 状态 API：GET /api/workflow/status?conversation_id= 供轮询/刷新恢复。

7. 新增工具与文件清单

项	类型	参照
create_workflow	AI 工具（生成并归档）	create_skill
read_workflow	AI 工具（读定义）	read_skill
report_workflow_stage_status	审核智能体内部工具	report_goal_status
modules/workflows_manager.py	校验/归档/目录合并	modules/skills_manager.py
modules/workflow_state_manager.py	对话级状态落盘	modules/goal_state_manager.py
server/workflow_flow.py	编排（启动/注入/审核/推进）	server/goal_flow.py
prompts/workflow.txt	提示词模板	prompts/ 现有模板
server/tasks/workflows.py	REST API（列表/激活/状态）	server/tasks/skills.py

8. 分期

• 一期（本次）：格式 + 归档工具 + 提示词注入 + 阶段状态机与审核 + 轮询进度 + slash 菜单激活 + 对话级状态隔离。
• 二期：拖拽画布编辑器（React Flow），本质是 stages frontmatter 的可视化编辑器（坐标只作视觉）。
• 三期：分支/DAG、并行阶段、子工作流嵌套。

9. 待确认（实施前如需变更再讨论）

• 工作流与目标模式是否互斥激活（建议互斥，避免双「防停止」机制叠加）。
• activate_workflow/deactivate_workflow 是否做成 AI 工具（slash 菜单人工激活为一期必须）。