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 菜单） 人工激活 + AI 工具 activate_workflow 自主激活
阶段边界	显式化：AI 调阶段汇报工具声明阶段完成（期间汇报触发审核与推进；无后续阶段时该汇报即停止信号）
阶段模型	非线性：阶段间为候选路由集（结构约束候选、AI 自主选择、审核把关），非纯线性
可视化编辑	拖拽画布编辑器（类似 ComfyUI 流程图）纳入设计范围，编辑对象是 WORKFLOW.md 的阶段拓扑
与目标模式关系	不互斥：工作流可以是目标模式中的一个小步骤；目标模式后续将重做，本期不考虑两者冲突
审核配置	独立：workflow_review.json（走 resolve_deploy_config 回退链）+ frontmatter review_mode 自声明
前后端通信	轮询（复用 task 轮询 session_data 快照链路，不新增 websocket 通道）
状态隔离	对话级状态，多对话可同时激活不同工作流，进度互不串扰
硬校验	不做步骤级硬校验；归档时只做结构校验（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/ 只放内置示例种子，双源合并。
• 归档工具 create_workflow：校验 → shutil.move → 已存在拒绝覆盖（复用 archive_skill_directory 模式）。
• 运行时状态：{workspace.data_dir}/workflow_states/<conversation_id>.json（对话级，对齐已修复的 goal 对话级方案）。

4. WORKFLOW.md 格式（非线性候选路由）

---
name: code-review-pipeline
description: 代码评审标准流程
review_mode: active          # 审核智能体是否可调用只读 run_command 取证
max_stage_rounds: 20         # 单阶段最大轮数，防死循环
entry: explore               # 入口阶段
stages:
  - id: explore
    name: 代码探索
    goal: 理解改动范围与相关模块
    review: false
    next: [review]           # 候选路由集：AI 汇报时从中选择下一站
  - id: review
    name: 逐项评审
    goal: 按 checklist 评审每个文件
    review: true             # 阶段汇报先触发审核
    review_prompt: 检查是否遗漏边界条件和安全问题
    next: [report, explore]  # 审核通过后可进报告，也可回探索补充
  - id: report
    name: 输出报告
    goal: 生成结构化评审报告
    review: true
    next: []                 # 空 = 终点，汇报即触发整体结束
end_conditions: 报告落盘且审核通过
---

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

• 路由语义：next 是候选集（结构约束）；AI 在阶段汇报工具中传 next_stage_id 自主选择；审核智能体可否决路由选择（打回时附带建议去向）。
• 结构校验（归档时）：name/description/entry/stages 齐全、id 唯一、next 引用存在、entry 可达终点。
• position 字段（可选）仅记录画布坐标，供可视化编辑器使用，不影响执行。

5. 运行时机制（复用现有引擎 + 显式阶段边界）

主路径：阶段汇报工具驱动

对话激活工作流 → 注入入口阶段上下文（goal + 工作方式 + 候选路由）
     ↓
主智能体正常跑（现有引擎不变，自由调工具、跑 scripts/）
     ↓
AI 调 report_workflow_stage(summary, next_stage_id?)  ← 阶段边界显式声明
     ↓
当前阶段 review=true？──否──→ 校验 next_stage_id 在候选集 → 推进，注入新阶段上下文
     │是
     ↓
WorkflowReviewAgent 审核（active 模式可只读取证）
     ├─ pass → 推进（next 为空 → 整体结束审核 → done，停止）
     └─ retry → 工具结果返回整改反馈，本阶段继续

兜底：无 tool_calls 拦截（降级为提醒）

主循环 if not tool_calls: 分支仍保留工作流检查，但语义降为提醒：工作流活跃且当前阶段有产出却未汇报时，注入「你还有进行中的工作流阶段 X，请用阶段汇报工具汇报或继续推进」提示并 continue 一轮；连续提醒无响应则按空转保护停止。阶段推进的主路径永远是显式汇报。

其他

• 结束三种：汇报至终点点（done）、撞边界（max_stage_rounds / 空转）、用户取消（slash 菜单或 deactivate）。
• 压缩维持：状态落盘 + handle_task_with_sender 入口重注入当前阶段上下文（对齐 goal 重注入模式）。
• 编排模块：新增 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）；配置 resolve_deploy_config("workflow_review.json")。
• 与目标模式并存：不互斥；目标模式后续重做时统一考虑两者关系。

6. 通信与前端

• 轮询链路（现成）：sender 事件 → session_data 快照 → REST 轮询透传 → 前端 taskPolling/lifecycle.ts case 消费。
  • 新增事件：workflow_progress / workflow_review_progress / workflow_completed / workflow_stopped，快照自带 conversation_id（对齐 goal 修复后的过滤机制）。
• 激活：slash 菜单新增 workflows 模式（数据 GET /api/workflows）；POST /api/workflow/activate|deactivate。
• 进度展示：仿 goal 进度组件——当前阶段名 · 已完成阶段列表 · 审核状态 · 轮数。
• 状态 API：GET /api/workflow/status?conversation_id= 供轮询/刷新恢复。

7. 可视化拖拽编辑器（设计讨论中）

• 技术选型：Vue Flow（项目为 Vue 3，React Flow 的 Vue 移植，API 同构）。
• 编辑对象：WORKFLOW.md frontmatter 的 stages 拓扑；节点 = 阶段，边 = next 候选路由；position 仅存坐标，与执行解耦。
• 与 AI 生成协同：AI create_workflow 生成归档 → 画布打开可视化/微调；画布编辑 → 序列化回 WORKFLOW.md。
• 页面形态与一期范围：待定（见 §9）。

8. 新增工具与文件清单

项	类型	说明
create_workflow	AI 工具	生成并校验归档（仿 create_skill）
read_workflow	AI 工具	读工作流定义（仿 read_skill）
activate_workflow / deactivate_workflow	AI 工具	开启/退出当前对话的工作流
report_workflow_stage	AI 工具	阶段汇报：期间汇报触发审核推进；无后续阶段时即停止信号
report_workflow_stage_status	审核智能体内部工具	pass/retry/complete（仿 report_goal_status）
modules/workflows_manager.py	模块	校验/归档/目录合并（仿 skills_manager）
modules/workflow_state_manager.py	模块	对话级状态落盘（对齐 goal_state_manager 对话级方案）
modules/workflow_review_agent.py	模块	阶段/整体审核
server/workflow_flow.py	模块	编排：激活/注入/汇报处理/推进/兜底提醒
server/tasks/workflows.py	REST API	列表/激活/状态/画布读写
prompts/workflow.txt	提示词	工作流上下文模板

9. 待确认

• 可视化编辑器页面形态：独立路由页面（如 /workflows 库 + 编辑器）还是对话内弹层/抽屉？
• 编辑器一期范围：完整拖拽编辑（增删节点/连线/改参数/保存）还是先做只读可视化 + 文本编辑？
• 兜底提醒的容忍轮数（建议连续 2 轮无响应转空转停止）。