# 工作流（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 格式（草案，实施时可微调）

```markdown
---
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 菜单人工激活为一期必须）。