agent-Specialization/docs/workflow_feature_plan.md

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

状态：设计定稿（2026-08-21）。工作流库页与可视化编辑器已实现；本文档是运行时实施的最终依据。 调研依据：workflow_research/ 三份报告（外部产品 / 范式要素 / 代码挂载点）。 历史说明：本文档前身是 2026-08-18 的讨论稿；当时「审核作为阶段属性」「兜底提醒轮询」「整体结束审核」等设想已在定稿中推翻，以本文档为准。

1. 功能定义与核心理念

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

三条核心理念（定稿）：

1. 结构在边上，自主在节点内——画布拓扑（节点 + 路由）是结构约束；阶段内主智能体完全自主（自由调工具、跑脚本）。外部调研（LangGraph / Dify / CrewAI / n8n）一致验证的范式。
2. 工作流是智能体的辅助流程，不是宿主——任何工作流异常/终态都不得掐断智能体工作。所有退出/失败/超限统一为柔性通知：摘牌（改状态）+ 一条 user 消息，处置权交回模型与用户。
3. 对话级持续状态——工作流状态不随单次任务结束、模型停止输出、用户按停止按钮而结束。模型停下后用户可自由穿插讨论，说「继续」即接着推进。

2. 已拍板决策（定稿汇总）

决策点	结论
运行方式	不做独立模式/特殊 URL/新对话类型；在普通对话中激活
激活入口	slash 菜单人工激活（仅智能体空闲可用）+ AI 工具 activate_workflow 自主激活
同时激活数	一个对话同时只有一个工作流处于激活；重复激活同工作流幂等返回进度，激活另一个被拒绝
审核建模	独立 review 节点（菱形，一等公民），非阶段属性；要结束审核就在 end 前显式放 review 节点
结束节点语义	end 即终点，汇报到 end 即 completed；无隐藏的整体结束审核
分支节点语义	单出线 = 并线器（自动穿过，无需决策）；多出线 = AI 决策点（等 choose_workflow_branch）
审核异常	视为驳回（计入 reject_counts），工具返回中含「请告知用户」
maxRejects 撞限	工作流 failed；经工具返回告知（模型已在场），不另发 user 消息
max_stage_rounds 撞限	不停工作流、不停智能体；注入 user 消息让模型立刻停下、告知用户、询问是否继续
deactivate（用户/模型/撞限）	一律柔性通知退出，见 §4.7
兜底提醒轮询	取消。模型停止输出即停止，工作流挂起不断，期间可与用户讨论
停止任务联动	不做（不仿 stop_goal_user_cancel）
版本快照	激活时把 WORKFLOW.md 复制进状态目录；运行期一切读取只读快照，库文件被改不影响运行中实例
前后端通信	轮询（复用 task 轮询 session_data 快照链路）+ 统一通知池轮询器（user 消息）
状态隔离	对话级状态目录，多对话互不惊扰
硬校验	不做步骤级硬校验；保存时做结构校验（对齐前后端 validate）

3. 数据模型与存储（已实现）

3.1 节点模型（对齐 static/src/components/workflow/workflowModel.ts）

五种节点，串行边界（无并行语义）：

kind	形态	语义
start	胶囊	入口，右 1 出，恰好 1 个
end	胶囊	终点，左 n 入，至少 1 个
stage	矩形	AI 执行阶段：goal + instructions + next（单值，显式连接）
review	菱形	审核把关：prompt（审核关注点）+ next（通过路由）+ rejectTo（驳回路由）+ maxRejects（连续驳回上限，超限 failed）
branch	虚线矩形	分线/并线器：next[] 路由数组，每条带 condition（自然语言，AI 决策依据；多出线必填）

所有路径显式化（next 为 null 校验不通过）；position 仅画布坐标，与执行解耦。

3.2 工作流库（已实现）

• WORKFLOW.md = YAML frontmatter（上述结构）+ markdown 正文（工作方式/验证方式/结束方式）
• 双源合并：源码树 workflows/（内置种子）+ 运行态用户库（host：~/.astrion/astrion/host/workflows/）
• 模块：modules/workflow_manager.py（CRUD + 校验 + camelCase↔snake_case）
• REST：server/workflow_page.py（/workflows、/workflow/<name> 页面 + /api/workflows CRUD）

3.3 运行时状态目录（待实现）

{workspace.data_dir}/workflow_states/<conversation_id>/
├── state.json       # 运行状态
└── WORKFLOW.md      # 激活时刻的原样快照

state.json schema：

{
  "workflow_name": "code-review-pipeline",
  "status": "active | completed | stopped | failed",
  "exit_reason": "user | model | max_rejects | round_limit_ack …",
  "current_node_id": "review-target-stage",
  "stage_rounds": 3,
  "round_limit_notified": false,
  "stage_start_msg_index": 142,
  "reject_counts": {"review-gate": 1},
  "history": [
    {"node_id": "explore", "kind": "stage", "summary": "…", "rounds": 5, "completed_at": 169…},
    {"node_id": "review-gate", "kind": "review", "decision": "reject", "message": "…", "at": 169…}
  ],
  "pending_notices": [
    {"type": "deactivated_by_user", "message": "完整文本", "created_at": 169…}
  ],
  "started_at": 169…
}

要点：

• current_node_id 只停 stage / branch / end——review 是瞬态节点：汇报时同步审完直接走到下一站，review 只作为 history 记录。状态机与前端进度展示因此大幅简化。
• stage_start_msg_index（消息游标）：进入阶段时记录 conversation_history 长度，审核 payload 截取增量作为阶段工作痕迹（§4.5）。
• pending_notices：柔性通知池（§4.7），落盘持久，取出即清除。

4. 运行时机制（待实现）

4.1 上下文注入：目录常存，详情跟走

信息	载体	时机
全景目录（工作流名/描述/正文三段/全部节点一句话清单/当前位置）	system 段（不冻结，每次 build_messages 现生成）	激活期间恒在，压缩免疫
当前节点详情（stage 的 goal + instructions 全文）	工具返回（tool 消息进历史）	激活时、每次推进时
迷失自查	get_workflow_status 工具	模型主动调

注意：主循环单次任务内 messages 只构建一次，阶段推进后同一任务后续迭代的 system 段会滞后。实施时二选一：推进时在工具 handler 内同步刷新 messages 中的工作流段；或 system 段注明「以最新工具返回/状态查询为准」。首选前者。

4.2 激活（两路入口，共享 build_activation_text()）

AI 自主激活：activate_workflow(name) 工具 → 加载定义 → 复制快照 → 初始化 state → 工具返回全景 + 入口阶段详情。重复激活规则：同工作流幂等返回当前进度；不同工作流拒绝（提示先退出）。

slash 菜单激活（REST）：

POST /api/workflow/activate {conversation_id, name}
  → 检查该对话无运行中主任务（门闸/terminal 状态），忙则 409「智能体运行中，无法激活」
  → 复制 WORKFLOW.md 快照 + 初始化 state
  → 构造完整 user 消息（含全景 + 入口详情 + 「请开始执行」），走正常消息链路：
    持久化 + 广播 + metadata 齐全（正常 user 消息参数一个不少，
    另打 auto_message_type: "workflow_activate" 标记供前端识别样式）
  → 创建主任务过门闸 → 模型收到消息直接开干（无需再调 activate_workflow）

4.3 阶段推进矩阵（核心）

report_workflow_stage(summary) 仅在当前节点为 stage 时可调。引擎读当前 stage 的 next，按目标类型分派：

下一节点	引擎动作	工具返回
stage	直接推进	「已记录完成。下一阶段「X」：goal + instructions」
review	同步 await 审核智能体（§4.5）	通过 → 「审核通过。下一阶段「X」…」；驳回 → reject_counts+1，回到 rejectTo：「审核未通过，意见：…。你已回到阶段「Y」整改」
branch（多出线）	不推进，停在 branch 等选择	「前方分支点：→ A（条件：…）→ B（条件：…）。请调 choose_workflow_branch」
branch（单出线）	自动穿过（并线器无需决策）	同 stage
end	status=completed	「工作流已完成。请输出总结后结束」（模型随后自然停止）

choose_workflow_branch(target_node_id)：仅当前停在 branch 时可调；校验 target 在候选路由集；推进后返回新阶段详情。

技术可行性已验证：handle_tool_call 为 async（tools_execution.py L960），submit_plan 已证明工具可长阻塞等待外部事件——审核在工具内同步 await 成立。

4.4 审核智能体

modules/workflow_review_agent.py（fork goal_review_agent.py），内部工具 report_workflow_review(decision: pass|reject, message)（仿 report_goal_status：唯一结论出口 + 强制工具调用重试）。配置统一走个人空间「审核智能体」页（modules/review_agent_config.py::resolve_review_agent_config，模型复用子智能体模型库）；review_mode: active 时注入只读 run_command 取证。

payload 构建（核心：让审核看证据而非听汇报）：

【工作流】{name}：{description}
【本次审核把关】{review 节点名}
审核关注点：{review.prompt}

【被审核阶段】{stage 名}
阶段目标：{stage.goal}
阶段要求：{stage.instructions}

【阶段执行痕迹】（消息游标 stage_start_msg_index 截取的对话增量，截断控长）
1. run_command: git diff --stat → …
2. read_file: server/chat.py L120-180 → …

【主智能体阶段汇报】{summary}

【历史审核意见】（若是重审，带上前几次驳回意见）

4.5 审核结果与边界

• pass → 推进到 review.next（若为 branch 多出线 → 停在 branch 等选择，返回分支菜单）。
• reject → reject_counts[node]+1 → 回到 review.rejectTo（stage 或 branch），工具返回带审核意见。
• 审核异常/超时 → 视为驳回（计入计数），返回中含「审核服务可能异常，请告知用户」。
• 撞 maxRejects → status=failed（exit_reason=max_rejects），工具返回「连续驳回超限，工作流已终止，请告知用户」。模型在场同轮闭环，不另发 user 消息。

4.6 max_stage_rounds 撞限（柔性询问）

• stage_rounds 跨任务累计：主循环每轮迭代 +1（挂点在主循环层，不在工具循环内——遵守注入时序铁律），进入新阶段清零。
• 撞限 → 注入 inline user 消息（inject_runtime_user_message(inline=True)，下轮模型即看到）： 「工作流阶段「X」已进行 N 轮，达到上限。请立刻停下当前工作，告知用户已超过 N 轮，并询问是否还要继续。」
• 工作流不停：status 保持 active，原地挂起等用户发话。
• 防重复：撞限后 round_limit_notified=true。
• 清零时机：下一条真实用户消息到达、新任务开始时清零（视作用户已知情交互）；之后若再跑 X 轮会再次询问——每超 X 轮问一次。

4.7 柔性退出与通知池

模型自主 deactivate / completed：工具返回同轮闭环，不需要 user 消息；前端 UI 走进度事件。

用户 slash deactivate（REST，随时可用，不做空闲检查——摘牌不打断正在跑的任务）：

• 智能体运行中 → 事件入 pending_notices；在 execute_tool_calls 末尾统一消费点注入 inline 通知（与 process_sub_agent_updates 同位置；遵守「循环内收集 → 循环后注入」铁律），模型下轮看到。
• 智能体空闲 → REST 直接派发：预占主任务门闸 → 完整 user 消息（持久化+广播+metadata 齐全）→ 创建主任务。与 slash activate 共用派发函数。
• 兜底：运行中模型在通知被消费前就停了 → 任务结尾轮询器 spawn 条件兜住（见下）。

通知池 = 统一完成通知轮询器的第三路（poll_completion_notifications，2026-06 实施、2026-08 门闸化），不新造轮子。改动点（均在 server/chat_flow_task_main.py）：

1. _collect_pending_completion_notices：增加 workflow 一路（与子智能体、后台命令按时间混排）。
2. needs_completion_poll（L2478 附近）：扩展条件 or _has_pending_workflow_notices(...)——否则无后台任务时工作流通知产生后轮询器不 spawn。
3. 轮询器主体零改动（门闸预占、批量预写+末条触发、新任务续轮询全复用）。

通知消息 metadata 新增 message_source: "workflow"（未识别时回落 "user"）。

摘牌后的工具行为：stopped/failed 后模型再调 report_workflow_stage / choose_workflow_branch → 返回 success:false + 「工作流已退出（原因），如需重新开始请重新激活」——返回错误但不炸任务。

4.8 与 goal 模式叠加

不互斥。工作流活跃时主循环尾部 no-tool-calls 分支不做任何工作流拦截（兜底提醒已取消）；goal 审核照常。

5. 工具清单

主智能体（5 个）

工具	参数	行为/返回
activate_workflow	name	加载+快照+初始化；返回全景目录+入口阶段详情。同工作流幂等；不同工作流拒绝
report_workflow_stage	summary	阶段汇报核心状态机，返回按 §4.3 矩阵分派
choose_workflow_branch	target_node_id	分支选择；校验候选集；返回新阶段详情
get_workflow_status	—	返回当前节点/已走路径/各阶段轮数/审核历史（迷失自查+用户问进度）
deactivate_workflow	reason	柔性退出：摘牌+工具返回确认（模型自主退出无需 user 消息）

审核智能体内部（1 个）

工具	参数	说明
report_workflow_review	decision: pass|reject, message	唯一结论出口，仿 report_goal_status

REST（3 个）

• POST /api/workflow/activate：仅智能体空闲（409 检查）；快照+初始化+派发完整 user 消息任务
• POST /api/workflow/deactivate：随时可用；忙入通知池、闲直发任务
• GET /api/workflow/status?conversation_id=：轮询/刷新恢复

6. 通信与前端

• 轮询事件（sender → session_data 快照 → REST 轮询，对齐 goal 链路）：workflow_progress（推进/驳回）/ workflow_review_progress（审核进行中）/ workflow_completed / workflow_stopped / workflow_failed。快照自带 conversation_id。
• slash 菜单：新增 workflows 模式，数据用现成 GET /api/workflows。
• 进度展示：仿 goal 进度组件——当前阶段名 · 已走路径 · 审核状态 · 轮数。
• 刷新恢复：GET /api/workflow/status。

7. 已实现部分清单（编辑器期）

• modules/workflow_manager.py、server/workflow_page.py
• static/src/components/workflow/：workflowModel.ts（模型/校验/dagre 自动排版）、WorkflowLibraryView.vue、WorkflowEditorView.vue、四种节点组件
• workflows/ 四个内置示例（code-review-pipeline / bug-fix-triage / feature-development / research-report）

8. 实施清单（文件级，按依赖顺序）

1. modules/workflow_state_manager.py（新增）：状态目录读写、快照复制、计数、通知池、消息游标。
2. modules/workflow_review_agent.py（新增，fork goal_review_agent）+ prompts/workflow_review_agent.txt（配置后改为统一审核智能体设置，见 modules/review_agent_config.py）。
3. server/workflow_flow.py（新增）：编排——build_activation_text、system 段构建、推进矩阵、审核调用、通知文本构造、状态查询。
4. 工具注册：core/main_terminal_parts/tools_definition/ 新增 5 个定义；tools_execution.py 注册 handler。
5. system 段注入：core/main_terminal_parts/context/messages.py 追加工作流段（不冻结）+ 推进时刷新机制。
6. 主循环挂点（server/chat_flow_task_main.py）：stage_rounds 计数与撞限注入；needs_completion_poll 扩展；_collect_pending_completion_notices 加 workflow 路；工具循环末尾消费工作流通知。
7. REST：server/tasks/workflows.py（新增）：activate / deactivate / status。
8. 前端：slash 菜单 workflows 模式、进度组件、轮询事件消费（taskPolling/lifecycle.ts）、刷新恢复。
9. 验证：python3 -m py_compile 改动文件 + python -m pytest test/test_server_refactor_smoke.py -q。

9. 硬约束（实施必须遵守）

• 单写者/门闸：所有工作流逻辑发生在主任务内部（工具执行 + 主循环层），不新增主任务入口；REST 派发走门闸预占（AGENTS.md §12）。
• 注入时序铁律：工具循环内禁止直接 inject_runtime_user_message——一律「循环内收集 → 循环后注入」（记忆 runtime_injected_message_convention）。
• 运行期注入标记：注入的 user 消息必须走 inject_runtime_user_message（自动带 runtime_injected 等标记），否则刷新恢复重建会重复显示。
• 不掐断智能体：任何工作流路径不得 raise/return 导致主任务异常终止；柔性优先。