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 格式（非线性候选路由）

```markdown
---
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 轮无响应转空转停止）。