SayClaw SOLO — AI 协作平台技术方案
从「AI 聊天」到「AI 做事」
融合 Manus Agent 调度架构 + Trae SOLO 交互范式，为企业打造 AI 工单协作平台
版本：v2.0 · 最后更新：2026-03-10
一、背景与动机
1.1 当前模式的痛点
SayClaw 目前是聊天模式 — 用户和 AI 对话，AI 实时回复。
| 问题 | 具体表现 |
|---|---|
| 任务混在对话里 | A 任务聊到一半插入 B，上下文断裂，翻聊天才能找到之前做到哪 |
| 状态不可见 | "上次那个做到哪了？" — 没有进度条、没有状态机、没有产出物管理 |
| 无法断点续执行 | 换窗口/重启实例/网络断开 → 从零开始 |
| 产出物散落 | 文件、报告、代码混在聊天消息里，找不到、下不了 |
| 简单问题太重 | 问个天气也走完整对话流，杀鸡用牛刀 |
| 复杂任务太轻 | 写份竞品分析报告也只是"一轮对话"，没有规划、没有验收、没有协作 |
| 无法审计 | 谁提的需求、AI 怎么做的、花了多少钱、质量如何 — 全靠翻聊天记录 |
1.2 行业参考
| 产品 | 模式 | 优点 | 局限 |
|---|---|---|---|
| Manus | 5-Phase Agent 调度（Plan → todo.md → Agent Loop → Re-plan → 交付） | 执行架构严谨，3 层存储分离，CP 质量门禁 | 无前端交互，纯后台自动执行 |
| Trae SOLO | IDE 内 AI 主导开发（Plan 模式 / Spec 模式 + Agent 团队） | 双复杂度模式，多 Agent 协作，实时预览 | 面向开发者，桌面端 IDE |
1.3 SayClaw SOLO 的定位
取 Manus 的执行架构 + Trae 的交互范式，面向企业非技术用户。
Manus 的"大脑"（调度 + 存储 + 质量门禁）
+
Trae 的"手脚"（双模式 + Agent 团队 + 实时工作区）
+
SayClaw 的"身份"（企业级 + Web/移动端 + 多人协作 + 审计合规）
=
SayClaw SOLO
二、核心设计理念
2.1 三个不等式
聊天 ≠ 做事 → 对话是手段，不是目的
AI 回复 ≠ 任务完成 → 工具调用成功 ≠ 目标达成（Manus CP3）
一个 AI ≠ 最优解 → 专业分工，多 Agent 协作
2.2 一个统一入口，三条智能路径
用户只需要做一件事：用自然语言说出想做什么。
AI 自动判断复杂度，路由到最合适的模式：
用户输入
│
┌─────┼─────┐
▼ ▼ ▼
问答 简单任务 复杂任务
│ │ │
▼ ▼ ▼
💬 聊天 ⚡ 快速 📋 项目
模式 模式 模式
| 路径 | 触发条件 | 对标 | 体验 |
|---|---|---|---|
| 💬 聊天模式 | 问答、闲聊、单轮查询 | 现有 WebChat | 直接回复，无流程 |
| ⚡ 快速模式 | 1-3 步可完成的明确任务 | Trae Plan | 秒级启动，自动执行，轻量进度 |
| 📋 项目模式 | 4 步以上、需要规划的复杂任务 | Trae Spec + Manus 5-Phase | 三件套文档 + Agent 团队 + 实时工作区 |
用户也可以手动指定：
/quick 翻译这段话→ 强制快速模式/project 从零搭建后台系统→ 强制项目模式
三、产品设计
3.1 统一首页
┌──────────────────────────────────────────────────────────┐
│ SayClaw SOLO 🔔 通知 👤 账户 │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ 💡 告诉我你想做什么... │ │
│ │ │ │
│ └──────────────────────────────────────────────────┘ │
│ 📎 附件 🎤 语音 /quick /project [→] │
│ │
│ ── 进行中 ───────────────────────────────────────── │
│ ┌────────────────────────────────────────────────────┐ │
│ │ ⚡ 翻译产品手册（日→中） 🔄 执行中 │ │
│ │ ████████░░ 80% · Step 4/5 · 2min │ │
│ └────────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ 📋 Q1 竞品分析报告 ⏸ 需确认 │ │
│ │ AI 有问题需要你决定 [去确认 →] │ │
│ └────────────────────────────────────────────────────┘ │
│ │
│ ── 最近完成 ─────────────────────────────────────── │
│ ┌────────────────────────────────────────────────────┐ │
│ │ ⚡ 客户邮件草稿 ✅ · 280 tok · 昨天 │ │
│ └────────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ 📋 Q4 销售分析报告 ✅ · 1.2k tok · 3天前 │ │
│ │ 📄 3 个产出物 [查看] │ │
│ └────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘
3.2 快速模式（⚡）
设计原则：3 秒内开始执行，无需确认。
适用场景：翻译、摘要、格式转换、简单查询、单文件处理。
用户：翻译这段话成日语 [粘贴文本]
│
▼ AI 判断：1 步任务，快速模式
│
┌──────────────────────────────────────────────────────────┐
│ ⚡ 中→日翻译 🔄 执行中 │
│ │
│ 📋 翻译 832 字中文文本为日语 │
│ ████████████████████░ 90% │
│ │
│ ── 结果 ─────────────────────────────────────── │
│ ┌──────────────────────────────────────────────┐ │
│ │ [日语翻译结果，实时流式输出] │ │
│ │ ... │ │
│ └──────────────────────────────────────────────┘ │
│ │
│ [📋 复制] [🔄 重做] [📝 修改要求] [💾 保存为文件] │
│ │
│ 💰 128 tok · $0.01 · ⏱ 12s │
└──────────────────────────────────────────────────────────┘
多步快速模式（2-3 步）：
用户：帮我把这个 Excel 里的数据生成一个柱状图
│
▼ AI 判断：3 步任务，快速模式
│
┌──────────────────────────────────────────────────────────┐
│ ⚡ Excel 数据可视化 🔄 执行中 │
│ │
│ ✅ 1. 读取 Excel 数据 3s │
│ 🔄 2. 分析数据结构，选择图表类型 进行中... │
│ ⏳ 3. 生成柱状图 待执行 │
│ │
│ ── 实时预览 ─────────────────────────────────── │
│ ┌──────────────────────────────────────────────┐ │
│ │ 📊 [图表实时渲染中...] │ │
│ └──────────────────────────────────────────────┘ │
│ │
│ [📥 下载图片] [📊 下载 Excel] [🔄 换图表类型] │
└──────────────────────────────────────────────────────────┘
3.3 项目模式（📋）
设计原则：先规划再执行，过程可见可控。
适用场景：竞品分析、方案撰写、数据分析报告、多步骤研究。
Phase 1: 需求理解 → 三件套生成
用户：帮我做一份 2026 Q1 竞品分析报告，对比我们和竞品 A、B、C
│
▼ AI 判断：复杂任务，项目模式
│
┌──────────────────────────────────────────────────────────┐
│ 📋 新建项目 │
│ │
│ AI 正在分析你的需求，生成执行方案... │
│ │
│ ┌─ 📋 spec.md — 需求说明 ──────────────────────────┐ │
│ │ │ │
│ │ ## 目标 │ │
│ │ 制作 2026 Q1 竞品分析报告 │ │
│ │ │ │
│ │ ## 范围 │ │
│ │ - 功能对比（≥10 项维度） │ │
│ │ - 定价对比（各套餐/版本） │ │
│ │ - 市场表现（评分、下载量、口碑） │ │
│ │ │ │
│ │ ## 竞品 │ │
│ │ - 竞品 A: [产品名] │ │
│ │ - 竞品 B: [产品名] │ │
│ │ - 竞品 C: [产品名] │ │
│ │ │ │
│ │ ## 产出物 │ │
│ │ - PDF 分析报告（含图表） │ │
│ │ - Excel 功能对比表 │ │
│ │ │ │
│ │ [✏️ 编辑] │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ ┌─ 📝 tasks.md — 任务清单 ─────────────────────────┐ │
│ │ │ │
│ │ - [ ] 1. 搜索竞品公开信息和定价 🔍 分析Agent │ │
│ │ - [ ] 2. 整理功能对比矩阵 🔍 分析Agent │ │
│ │ - [ ] 3. 获取市场评分数据 🔍 分析Agent │ │
│ │ - [ ] 4. 撰写分析报告 + 图表 📝 写作Agent │ │
│ │ - [ ] 5. 排版输出 PDF 🎨 设计Agent │ │
│ │ │ │
│ │ [✏️ 编辑] [+ 添加步骤] │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ ┌─ ✅ checklist.md — 验收清单 ─────────────────────┐ │
│ │ │ │
│ │ - [ ] 三家竞品信息完整（功能+价格+评分） │ │
│ │ - [ ] 对比表 ≥ 10 项功能维度 │ │
│ │ - [ ] 图表 ≥ 3 个（雷达图/价格对比/评分趋势） │ │
│ │ - [ ] 所有数据标注来源 │ │
│ │ - [ ] PDF 格式规范，可直接呈报 │ │
│ │ │ │
│ │ [✏️ 编辑] [+ 添加检查项] │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ 📊 预估：⏱ 10-15 min · 💰 ~$0.08 · 📄 2 个产出物 │
│ 🤖 将使用：分析Agent + 写作Agent + 设计Agent │
│ │
│ 你可以直接编辑上面的文档，或告诉我需要修改什么。 │
│ │
│ [✅ 确认执行] [💬 我想修改...] [❌ 取消] │
└──────────────────────────────────────────────────────────┘
Phase 2: 执行 → 实时工作区
确认后进入执行阶段，界面切换为双栏实时工作区：
┌──────────────────────────────────────────────────────────────┐
│ 📋 Q1 竞品分析报告 🔄 执行中 ⏱ 8min │
│ │
│ ┌─ 任务流 ─────────────┐ ┌─ 实时工作区 ──────────────────┐│
│ │ │ │ ││
│ │ ✅ 1. 搜索竞品信息 │ │ Tab: [📊 预览] [📁 文件] [📋 日志]││
│ │ 🔍 分析Agent · 2min│ │ ││
│ │ → 已获取 3 家产品页 │ │ ┌──────────────────────────┐ ││
│ │ │ │ │ │ ││
│ │ ✅ 2. 功能对比矩阵 │ │ │ 竞品功能对比表（实时生成） │ ││
│ │ 🔍 分析Agent · 3min│ │ │ │ ││
│ │ → 12 项维度 │ │ │ 功能 我们 A B C │ ││
│ │ │ │ │ SSO ✅ ✅ ❌ ✅ │ ││
│ │ 🔄 3. 市场评分数据 │ │ │ API ✅ ✅ ✅ ❌ │ ││
│ │ 🔍 分析Agent │ │ │ RBAC ✅ ❌ ✅ ✅ │ ││
│ │ → 正在汇总 G2 数据 │ │ │ SSO ✅ ✅ ❌ ✅ │ ││
│ │ │ │ │ ... │ ││
│ │ ⏳ 4. 撰写分析报告 │ │ │ │ ││
│ │ 📝 写作Agent │ │ └──────────────────────────┘ ││
│ │ │ │ ││
│ │ ⏳ 5. 排版输出 PDF │ │ ✅ 验收清单 (2/5 通过) ││
│ │ 🎨 设计Agent │ │ ✅ 三家竞品信息完整 ││
│ │ │ │ ✅ 对比表 12 项 (≥10) ││
│ │ ── AI 消息 ──────── │ │ ⏳ 图表 ≥ 3 个 ││
│ │ │ │ ⏳ 数据标注来源 ││
│ │ 🤖 竞品 C 在中国区 │ │ ⏳ PDF 格式规范 ││
│ │ 没有公开定价，怎么处理？│ │ ││
│ │ │ │ ││
│ │ [标记未公开] │ │ ││
│ │ [跳过竞品C] │ │ ││
│ │ [我来提供] │ │ ││
│ │ │ │ ││
│ │ ── 产出物 ──────── │ │ ││
│ │ 📊 对比表.xlsx ✅ │ │ ││
│ │ 📄 报告.pdf 🔄 │ │ ││
│ └───────────────────────┘ └────────────────────────────────┘│
│ │
│ [追加说明...] 💰 338tok · $0.02 · 8min│
│ [⏸ 暂停] [❌ 取消] │
└──────────────────────────────────────────────────────────────┘
Phase 3: 完成 → 交付
┌──────────────────────────────────────────────────────────────┐
│ 📋 Q1 竞品分析报告 ✅ 已完成 │
│ │
│ ┌─ 执行摘要 ────────────────────────────────────────────┐ │
│ │ │ │
│ │ ⏱ 耗时 12 min · 💰 $0.08 · 🔢 1,250 tokens │ │
│ │ 🤖 3 个 Agent 参与（分析 + 写作 + 设计） │ │
│ │ 📊 5/5 步骤完成 · ✅ 5/5 验收通过 │ │
│ │ │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ 产出物 ──────────────────────────────────────────────┐ │
│ │ │ │
│ │ 📊 竞品功能对比表.xlsx 42KB [预览] [下载] │ │
│ │ 📄 Q1竞品分析报告.pdf 1.2MB [预览] [下载] │ │
│ │ 📈 市场趋势图.png 180KB [预览] [下载] │ │
│ │ │ │
│ │ [📦 全部下载] │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ 验收清单 ────────────────────────────────────────────┐ │
│ │ ✅ 三家竞品信息完整（功能+价格+评分） │ │
│ │ ✅ 对比表 12 项功能维度（≥10 ✓） │ │
│ │ ✅ 图表 4 个（雷达图/价格对比/评分趋势/功能覆盖） │ │
│ │ ✅ 所有数据标注来源 │ │
│ │ ✅ PDF 格式规范，可直接呈报 │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ [🔄 基于此结果继续迭代] [📤 分享] [🗂 归档] │
└──────────────────────────────────────────────────────────────┘
3.4 三件套文档系统
借鉴 Trae SOLO Coder 的 Spec 模式，项目模式的核心是三件套文档：
| 文档 | 对标 | 作用 | 可编辑 | 生命周期 |
|---|---|---|---|---|
| spec.md | Trae spec.md / Manus Event Stream | 需求说明，"做什么" | ✅ 用户 + AI | 确认后冻结，Re-plan 时创建新版本 |
| tasks.md | Trae tasks.md / Manus todo.md | 任务清单，"怎么做" | ✅ 用户 + AI | 执行过程中持续更新状态 |
| checklist.md | Trae checklist.md / Manus CP3 | 验收标准，"做到什么程度" | ✅ 用户 + AI | 每步完成后自动勾选 |
为什么是三个文档而不是一个 Plan？
分离关注点：
spec.md → 不可变的需求记录（为什么做、做什么）
Re-plan 时旧 spec 不丢，可审计"为什么改了"
tasks.md → 可变的执行状态（做到哪了）
Agent 每轮只需读这个，轻量
崩溃重启后读 tasks.md 就能断点续执行
checklist → 独立的质量标准（做得好不好）
不会因为 Plan 改了就偷偷降低验收标准
四、Agent 团队
4.1 为什么需要多 Agent
单 Agent 做所有事 = 一个人包揽搜索、分析、写作、设计、排版。
Trae SOLO Coder 的思路：主控 Agent 调用子 Agent（UI Designer、Backend Architect 等）。
SayClaw 的独特优势：我们有真实的 OC 实例集群，每个实例可以是不同角色。
4.2 角色体系
┌─────────────────────────────────────────────────────────┐
│ Agent 角色体系 │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ 🎯 调度 Agent (Orchestrator) │ │
│ │ 分析需求 → 生成三件套 → 分配任务 │ │
│ │ ≈ Manus Orchestrator │ │
│ └──────────────────────┬───────────────────────────┘ │
│ │ │
│ ┌───────────────┼───────────────┐ │
│ ▼ ▼ ▼ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ 🔍 分析 Agent│ │ 📝 写作 Agent│ │ 🎨 设计 Agent│ │
│ │ │ │ │ │ │ │
│ │ 搜索 │ │ 报告撰写 │ │ 排版美化 │ │
│ │ 数据清洗 │ │ 文案生成 │ │ 图表制作 │ │
│ │ 信息整理 │ │ 翻译 │ │ PDF 输出 │ │
│ │ Excel 处理 │ │ 摘要提炼 │ │ PPT 制作 │ │
│ └────────────┘ └────────────┘ └────────────┘ │
│ │ │ │ │
│ └───────────────┼───────────────┘ │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ 🔍 审核 Agent (Quality Gate) │ │
│ │ 对照 checklist.md 逐项验收 │ │
│ │ ≈ Manus CP3 │ │
│ └──────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
4.3 实例 → 角色映射
每个 OC 实例通过配置文件定义角色：
# SOUL.md — 分析 Agent
你是 SayClaw 分析专家。
你的职责是搜索信息、分析数据、整理对比。
你擅长 Web 搜索、Excel 数据处理、统计分析。
你的产出物：结构化数据、对比表、分析图表。
你不做写作和排版，那是其他 Agent 的事。
# Skills
- web_search
- data_analysis
- excel_processing
管理后台可以配置 Agent 角色：
┌─────────────────────────────────────────────────────┐
│ Agent 团队管理 [+ 新建角色] │
│ │
│ 角色 实例 模型 状态 │
│ 🎯 调度 jp-3-01 opus-4-6 🟢 在线 │
│ 🔍 分析 jp-3-02 opus-4-6 🟢 在线 │
│ 📝 写作 jp-3-03 gpt-5.2-pro 🟢 在线 │
│ 🎨 设计 jp-3-04 opus-4-6 🟢 在线 │
│ 🔍 审核 jp-3-05 opus-4-6 ⚪ 待命 │
│ │
│ [配置角色] [分配实例] [调整模型] │
└─────────────────────────────────────────────────────┘
4.4 Agent 协作流程
调度 Agent: "Step 1-3 需要搜索和分析，分配给 分析Agent"
│
├──→ 分析 Agent (WS)
│ Step 1: web_search 竞品信息 → 产出 raw_data.json
│ Step 2: 整理对比矩阵 → 产出 comparison.xlsx
│ Step 3: 获取评分数据 → 产出 ratings.json
│ 回报: "Step 1-3 完成，3 个中间产出物"
│
调度 Agent: "Step 4 需要写作，分配给 写作Agent，带上中间产出物"
│
├──→ 写作 Agent (WS)
│ 读取 comparison.xlsx + ratings.json
│ Step 4: 撰写分析报告 → 产出 report.md
│ 回报: "Step 4 完成"
│
调度 Agent: "Step 5 需要设计，分配给 设计Agent"
│
├──→ 设计 Agent (WS)
│ 读取 report.md + comparison.xlsx
│ Step 5: 排版 + 图表 → 产出 report.pdf
│ 回报: "Step 5 完成"
│
调度 Agent: "全部完成，交给 审核Agent 验收"
│
└──→ 审核 Agent
对照 checklist.md 逐项检查
✅ 5/5 通过 → 标记完成
(或 ❌ 不通过 → 触发 Re-plan)
五、执行架构（对齐 Manus 5-Phase）
5.1 完整执行流程
Phase 1: 需求接入 & 上下文组装
─────────────────────────────
用户输入 (自然语言 + 附件)
│
▼
AI 路由判断
→ 聊天? 快速模式? 项目模式?
│
▼ (项目模式)
组装上下文
+ 用户历史偏好
+ 相关领域知识 (Knowledge)
+ 附件内容解析
│
▼
Phase 2: 规划 & 确认
─────────────────────────────
调度 Agent (Planner LLM)
│
├─→ 生成 spec.md (需求说明)
├─→ 生成 tasks.md (任务清单)
└─→ 生成 checklist.md (验收标准)
│
▼
┌─ CP1: Plan 质量校验 ──────────────────────────┐
│ │
│ 自动校验 (规则引擎 + LLM Review): │
│ ◆ 步骤是否完整，有无明显遗漏 │
│ ◆ 步骤间依赖是否合理，有无循环 │
│ ◆ 每步是否可执行，粒度是否合适 │
│ ◆ checklist 是否覆盖 spec 的所有关键需求 │
│ │
│ ✓ 通过 → 展示给用户确认 │
│ ✗ 不通过 → Planner 重新规划 │
└────────────────────────────────────────────────┘
│
▼
用户确认
[确认执行] → Phase 3
[修改] → 用户编辑 or 对话修改 → 重新 CP1
[取消] → 结束
│
▼
Phase 3: Agent 执行
─────────────────────────────
调度 Agent 按 tasks.md 逐步分发
│
▼
┌─ Agent Loop (每步) ────────────────────────────┐
│ │
│ 1. tasks.md: 标记当前 Step → IN_PROGRESS │
│ 2. 调度 Agent 分配给对应角色 Agent │
│ 3. 角色 Agent 执行: │
│ 组装 Prompt (上下文 + 工具列表) │
│ LLM 决策 → 选择工具 + 参数 │
│ 执行工具 → 结果写入 Artifacts │
│ (单工具调用模式，每轮重新决策) │
│ 4. Step 完成 → CP3 验收 │
│ │
│ ┌─ CP3: Step 验收 ──────────────────────────┐ │
│ │ 对照 checklist.md 相关项 │ │
│ │ ✅ 通过 → tasks.md 打勾，进入下一步 │ │
│ │ △ 部分达成 → 标记 PARTIAL，继续执行 │ │
│ │ ❌ 未达成 → 重试 (最多 3 次) │ │
│ │ ⏸ 需人工 → 暂停，发送结构化问题给用户 │ │
│ └──────────────────────────────────────────┘ │
│ │
│ 5. WS 实时推送进度给前端 │
│ 6. 中间产出物存入 Artifacts，供后续 Step 读取 │
│ │
└────────────────────────────────────────────────┘
│
▼ (如果失败)
Phase 4: 异常处理 & Re-plan
─────────────────────────────
├─ 自动重试 (网络超时等临时错误)
├─ 换工具/换策略重试
├─ 增量 Re-plan:
│ 读取失败原因 + 当前 tasks.md 状态 + 已有产出物
│ Planner 追加/修改步骤 (不推翻已完成的)
│ spec.md 版本号 +1
│ 重新进入 Phase 3
└─ 人工介入:
暂停执行，发送结构化问题给用户
用户回复后恢复
│
▼
Phase 5: 交付
─────────────────────────────
├─ 审核 Agent 对照 checklist.md 全量验收
├─ 生成执行摘要 (耗时/费用/Agent 参与/token 用量)
├─ 打包产出物
├─ 标记 ticket.status = done
└─ 通知用户 (WS + Telegram + 邮件)
5.2 三层存储
| 层 | 载体 | 特性 | 映射 |
|---|---|---|---|
| 意图层 | ticket_events 表 + spec.md 版本 | 只写不改 | Manus Event Stream |
| 状态层 | ticket_steps 表 + tasks.md | 可读写 | Manus todo.md |
| 产出层 | ticket_artifacts 表 + 文件存储 | Step 间传递 | Manus 文件系统 |
断点续执行原理：
Agent 崩溃/断开
│
▼
调度 Agent 检测 WS 断开
│
▼
读取 ticket_steps (status != 'done')
读取 ticket_artifacts (已有产出物)
│
▼
重新分配 Agent 实例
│
▼
从第一个 pending/failed 的 Step 继续执行
已完成的 Step 和产出物完整保留
六、数据库设计
6.1 ER 图
users (已有)
│
├── 1:N ──→ tickets ──────────────────────────────┐
│ │ │
│ ├── 1:N ──→ ticket_steps │
│ │ │ │
│ │ └── 1:N ──→ step_tool_calls
│ │ │
│ ├── 1:N ──→ ticket_messages │
│ ├── 1:N ──→ ticket_artifacts │
│ ├── 1:N ──→ ticket_events │
│ └── 1:3 ──→ ticket_docs │
│ (spec/tasks/checklist) │
│ │
└── N:M ──→ user_instances (已有) │
│ │
└──→ agent_roles ───────────────────┘
(OC 实例角色定义)
6.2 核心表结构
-- ============================================
-- 工单主表
-- ============================================
CREATE TABLE tickets (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
ticket_no VARCHAR(20) NOT NULL UNIQUE COMMENT '工单编号 T-20260310-042',
user_id VARCHAR(36) NOT NULL,
-- 模式
mode ENUM('quick','project') NOT NULL DEFAULT 'quick'
COMMENT '快速模式 / 项目模式',
-- 需求
title VARCHAR(200) NOT NULL COMMENT 'AI 提取的标题',
description TEXT NOT NULL COMMENT '用户原始输入',
-- 状态
status ENUM('planning','pending','running','paused','done','failed','cancelled')
NOT NULL DEFAULT 'planning',
progress TINYINT DEFAULT 0 COMMENT '0-100',
pause_reason TEXT DEFAULT NULL,
-- 计划版本（Re-plan 时递增）
plan_version INT DEFAULT 1,
-- Agent 分配
orchestrator_instance_id VARCHAR(64) DEFAULT NULL COMMENT '调度 Agent 实例',
-- 统计
total_steps INT DEFAULT 0,
completed_steps INT DEFAULT 0,
total_tokens INT DEFAULT 0,
cost_usd DECIMAL(10,6) DEFAULT 0,
agents_used INT DEFAULT 0 COMMENT '参与的 Agent 数',
-- 预估
estimated_minutes INT DEFAULT NULL,
estimated_cost DECIMAL(10,4) DEFAULT NULL,
-- 时间
confirmed_at DATETIME(3) DEFAULT NULL,
started_at DATETIME(3) DEFAULT NULL,
completed_at DATETIME(3) DEFAULT NULL,
created_at DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3),
updated_at DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
INDEX idx_user_status (user_id, status),
INDEX idx_created (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
-- ============================================
-- 三件套文档
-- ============================================
CREATE TABLE ticket_docs (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
ticket_id BIGINT NOT NULL,
doc_type ENUM('spec','tasks','checklist') NOT NULL,
version INT NOT NULL DEFAULT 1,
content MEDIUMTEXT NOT NULL COMMENT 'Markdown 内容',
created_at DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3),
updated_at DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
UNIQUE KEY uk_ticket_doc_ver (ticket_id, doc_type, version),
FOREIGN KEY (ticket_id) REFERENCES tickets(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
COMMENT='工单三件套文档 (spec/tasks/checklist)';
-- ============================================
-- 执行步骤
-- ============================================
CREATE TABLE ticket_steps (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
ticket_id BIGINT NOT NULL,
seq INT NOT NULL COMMENT '步骤序号',
description VARCHAR(500) NOT NULL COMMENT '步骤描述（用户可见）',
assigned_role VARCHAR(50) DEFAULT NULL COMMENT 'Agent 角色: analyst / writer / designer',
assigned_instance VARCHAR(64) DEFAULT NULL COMMENT '执行实例 ID',
depends_on JSON DEFAULT NULL COMMENT '依赖步骤 [1, 2]',
status ENUM('pending','running','done','failed','skipped','partial')
NOT NULL DEFAULT 'pending',
output_summary TEXT DEFAULT NULL COMMENT '结果摘要（用户可见）',
error_message TEXT DEFAULT NULL,
retry_count INT DEFAULT 0,
tokens_used INT DEFAULT 0,
cost_usd DECIMAL(10,6) DEFAULT 0,
duration_sec INT DEFAULT 0,
started_at DATETIME(3) DEFAULT NULL,
completed_at DATETIME(3) DEFAULT NULL,
created_at DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3),
INDEX idx_ticket_seq (ticket_id, seq),
FOREIGN KEY (ticket_id) REFERENCES tickets(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
-- ============================================
-- 工具调用记录（审计用）
-- ============================================
CREATE TABLE step_tool_calls (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
step_id BIGINT NOT NULL,
ticket_id BIGINT NOT NULL,
tool_name VARCHAR(100) NOT NULL COMMENT 'web_search / file_write / ...',
input_json JSON DEFAULT NULL COMMENT '工具输入参数',
output_summary TEXT DEFAULT NULL COMMENT '工具输出摘要',
success TINYINT(1) DEFAULT 1,
duration_ms INT DEFAULT 0,
created_at DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3),
INDEX idx_step (step_id),
FOREIGN KEY (step_id) REFERENCES ticket_steps(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
COMMENT='Step 内工具调用审计';
-- ============================================
-- 消息流（AI ↔ 用户交互）
-- ============================================
CREATE TABLE ticket_messages (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
ticket_id BIGINT NOT NULL,
step_id BIGINT DEFAULT NULL,
role ENUM('user','assistant','system') NOT NULL,
content TEXT NOT NULL,
message_type ENUM('text','confirmation','file','action_result')
DEFAULT 'text',
options_json JSON DEFAULT NULL COMMENT '结构化选项',
selected_option VARCHAR(100) DEFAULT NULL COMMENT '用户选择',
created_at DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3),
INDEX idx_ticket (ticket_id),
FOREIGN KEY (ticket_id) REFERENCES tickets(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
-- ============================================
-- 产出物
-- ============================================
CREATE TABLE ticket_artifacts (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
ticket_id BIGINT NOT NULL,
step_id BIGINT DEFAULT NULL,
name VARCHAR(200) NOT NULL COMMENT '文件名',
file_path VARCHAR(500) NOT NULL,
mime_type VARCHAR(100) DEFAULT NULL,
file_size BIGINT DEFAULT 0,
is_final TINYINT(1) DEFAULT 0 COMMENT '1=最终产出物, 0=中间产出物',
preview_text TEXT DEFAULT NULL COMMENT '文本预览',
created_at DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3),
INDEX idx_ticket (ticket_id),
FOREIGN KEY (ticket_id) REFERENCES tickets(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
-- ============================================
-- 事件流（只写审计）
-- ============================================
CREATE TABLE ticket_events (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
ticket_id BIGINT NOT NULL,
step_id BIGINT DEFAULT NULL,
event_type VARCHAR(50) NOT NULL,
-- ticket_created / plan_generated / plan_confirmed / plan_modified
-- step_assigned / step_started / step_completed / step_failed
-- agent_switched / replan_triggered
-- confirmation_sent / user_replied
-- artifact_created / ticket_completed / ticket_failed
actor VARCHAR(50) NOT NULL COMMENT 'user / agent:<role> / system',
payload_json JSON DEFAULT NULL,
created_at DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3),
INDEX idx_ticket_time (ticket_id, created_at),
INDEX idx_type (event_type)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
COMMENT='工单事件流（只写，审计用）';
-- ============================================
-- Agent 角色定义
-- ============================================
CREATE TABLE agent_roles (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
role_name VARCHAR(50) NOT NULL UNIQUE COMMENT 'analyst / writer / designer / reviewer',
display_name VARCHAR(100) NOT NULL COMMENT '🔍 分析师',
description TEXT DEFAULT NULL,
instance_id VARCHAR(64) DEFAULT NULL COMMENT '绑定的 OC 实例',
model_name VARCHAR(100) DEFAULT NULL COMMENT '使用的模型',
soul_md TEXT DEFAULT NULL COMMENT 'SOUL.md 内容',
skills_json JSON DEFAULT NULL COMMENT '可用 Skills 列表',
is_active TINYINT(1) DEFAULT 1,
created_at DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3),
updated_at DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
COMMENT='Agent 角色定义';
6.3 与现有表的关系
| 现有表 | 处理方式 |
|---|---|
chat_messages | 保留，聊天模式继续使用 |
user_instances | 保留，快速模式自动选实例 |
oneapi.logs | Step 完成时聚合 token 数据写入 ticket_steps |
oc_instances | 新增 agent_role_id 字段关联角色 |
七、API 设计
7.1 Portal API
# ── 统一入口 ──
POST /api/v1/me/solo/submit 提交需求（AI 自动路由模式）
# ── 工单 CRUD ──
GET /api/v1/me/tickets 工单列表（状态/模式筛选、分页）
GET /api/v1/me/tickets/:id 工单详情（含 steps + docs + artifacts）
PUT /api/v1/me/tickets/:id 更新工单（追加说明）
DELETE /api/v1/me/tickets/:id 取消工单
# ── 三件套文档 ──
GET /api/v1/me/tickets/:id/docs/:type 获取文档 (spec/tasks/checklist)
PUT /api/v1/me/tickets/:id/docs/:type 编辑文档
GET /api/v1/me/tickets/:id/docs/:type/versions 文档版本历史
# ── 工单操作 ──
POST /api/v1/me/tickets/:id/confirm 确认执行
POST /api/v1/me/tickets/:id/pause 暂停
POST /api/v1/me/tickets/:id/resume 恢复
POST /api/v1/me/tickets/:id/retry 重试
POST /api/v1/me/tickets/:id/reply 回复 AI 确认请求
# ── 产出物 ──
GET /api/v1/me/tickets/:id/artifacts 列表
GET /api/v1/me/tickets/:id/artifacts/:aid/download 下载
GET /api/v1/me/tickets/:id/artifacts/:aid/preview 预览
# ── 实时推送 ──
WS /api/v1/me/tickets/:id/ws 进度、消息、产出物实时推送
7.2 WebSocket 协议
// ── 进度更新 ──
{
"type": "step_update",
"ticket_id": 42,
"step": {
"seq": 3,
"status": "running",
"assigned_role": "analyst",
"output_summary": "正在汇总 G2 评分数据..."
},
"progress": 60
}
// ── 需要确认 ──
{
"type": "confirmation_required",
"ticket_id": 42,
"step_seq": 3,
"message": "竞品 C 在中国区没有公开定价，要怎么处理？",
"options": [
{"label": "标记为"未公开"", "value": "mark_unavailable", "style": "primary"},
{"label": "跳过竞品 C", "value": "skip", "style": "default"},
{"label": "我来提供价格", "value": "user_input", "style": "default"}
]
}
// ── 产出物就绪 ──
{
"type": "artifact_ready",
"ticket_id": 42,
"artifact": {
"id": 15,
"name": "竞品对比表.xlsx",
"is_final": false,
"preview_url": "/api/v1/me/tickets/42/artifacts/15/preview"
}
}
// ── 验收更新 ──
{
"type": "checklist_update",
"ticket_id": 42,
"checklist": [
{"item": "三家竞品信息完整", "passed": true},
{"item": "对比表 ≥ 10 项维度", "passed": true},
{"item": "图表 ≥ 3 个", "passed": false},
{"item": "数据标注来源", "passed": false},
{"item": "PDF 格式规范", "passed": false}
],
"passed": 2,
"total": 5
}
// ── 工单完成 ──
{
"type": "ticket_completed",
"ticket_id": 42,
"summary": {
"total_tokens": 1250,
"cost_usd": 0.08,
"duration_minutes": 12,
"agents_used": 3,
"artifacts_count": 3,
"checklist_passed": 5,
"checklist_total": 5
}
}
7.3 Admin API
# ── 全局监控 ──
GET /api/v1/admin/tickets 全局工单列表
GET /api/v1/admin/tickets/stats 统计看板（按日/周/月、按状态/用户/Agent）
GET /api/v1/admin/tickets/:id 工单详情（含完整事件流）
POST /api/v1/admin/tickets/:id/kill 强制终止
# ── Agent 管理 ──
GET /api/v1/admin/agent-roles 角色列表
POST /api/v1/admin/agent-roles 创建角色
PUT /api/v1/admin/agent-roles/:id 编辑角色
GET /api/v1/admin/agent-roles/stats 角色使用统计
八、OC 实例改造
8.1 双模式支持
| 模式 | 触发方式 | 行为 |
|---|---|---|
| Chat 模式（现有） | WS 普通消息 | 对话式交互 |
| Ticket 模式（新增） | WS ticket.execute | 按 Plan 逐步执行，回报进度 |
8.2 Ticket 模式 WS 协议
// ── Gateway → OC 实例：下发任务 ──
{
"type": "ticket.execute",
"ticket_id": 42,
"step": {
"seq": 1,
"description": "搜索竞品 A/B/C 的公开产品信息和定价",
"checklist_items": ["三家竞品信息完整（功能+价格+评分）"]
},
"context": {
"spec": "... spec.md 内容 ...",
"previous_artifacts": [
{"name": "data.json", "url": "/artifacts/12/download"}
]
}
}
// ── OC 实例 → Gateway：进度回报 ──
{
"type": "ticket.step_progress",
"ticket_id": 42,
"step_seq": 1,
"message": "已获取竞品 A 产品页面，正在搜索竞品 B...",
"tokens_used": 64
}
// ── OC 实例 → Gateway：Step 完成 ──
{
"type": "ticket.step_done",
"ticket_id": 42,
"step_seq": 1,
"output_summary": "已获取 A/B/C 三家产品页面、定价和功能列表",
"artifacts": [
{"name": "raw_data.json", "content_base64": "..."}
],
"tokens_used": 128
}
// ── OC 实例 → Gateway：需要用户确认 ──
{
"type": "ticket.need_confirmation",
"ticket_id": 42,
"step_seq": 3,
"message": "竞品 C 在中国区没有公开定价",
"options": [
{"label": "标记为"未公开"", "value": "mark_unavailable"},
{"label": "跳过竞品 C", "value": "skip"}
]
}
8.3 断点续执行
OC 实例崩溃 / WS 断开
│
▼
Gateway 检测连接断开 (heartbeat timeout)
│
▼
查询 ticket_steps WHERE status IN ('running', 'pending')
查询 ticket_artifacts WHERE ticket_id = ?
│
▼
选择同角色的可用 OC 实例（或等待实例恢复）
│
▼
重新下发未完成的 Step
附带已有的中间产出物 URL
│
▼
Agent 从断点继续执行
九、与聊天模式的共存
9.1 渐进式迁移
Phase A (当前) Phase B (MVP) Phase C (完整)
───────────── ───────────── ─────────────
┌────────────┐ ┌────────────┐ ┌────────────┐
│ Chat │ │ 统一输入框 │ │ 统一输入框 │
│ (唯一入口) │ │ ┌────────┐ │ │ ┌────────┐ │
└────────────┘ │ │AI 路由 │ │ │ │AI 路由 │ │
│ └────┬───┘ │ │ └────┬───┘ │
│ ┌────┼────┐│ │ ┌────┼────┐│
│ ▼ ▼ ▼│ │ ▼ ▼ ▼│
│ 💬 ⚡ 📋 │ │ 💬 ⚡ 📋 │
│ Chat Quick Proj│ │ Chat Quick Proj│
└────────────┘ │ (轻量) (主力) (完整)│
└────────────┘
Phase B (MVP)：
- 保留现有 Chat
- 新增快速模式（简单任务直接执行）
- 新增项目模式（三件套 + 单 Agent 执行，暂不做多 Agent）
Phase C (完整)：
- 统一入口 + AI 智能路由
- 多 Agent 团队协作
- 完整的实时工作区
- Admin Agent 管理后台
9.2 智能路由判断逻辑
def route_input(user_input, attachments):
# 用户手动指定
if user_input.startswith('/quick'):
return 'quick'
if user_input.startswith('/project'):
return 'project'
# AI 判断
analysis = llm_analyze(user_input, attachments)
if analysis.is_question or analysis.is_chat:
return 'chat' # → 聊天模式
if analysis.estimated_steps <= 3 and not analysis.needs_file_output:
return 'quick' # → 快速模式
return 'project' # → 项目模式
十、竞品差异化
| 维度 | Trae SOLO | Manus | SayClaw SOLO |
|---|---|---|---|
| 平台 | 桌面 IDE | 网页 | Web + Telegram + 移动端 |
| 目标用户 | 开发者 | 个人 | 企业团队 |
| Agent 实现 | 单进程多角色 | 单 Agent | 真实多实例集群 |
| 多人协作 | 单人 | 单人 | 多人 + 权限 + 审批 |
| 审计合规 | Git 历史 | Event Stream | 完整事件审计 + SQL 查询 |
| 通知渠道 | IDE 内 | 无 | Telegram / 企微 / 钉钉 / 邮件 |
| 计费模式 | 月订阅 | 按次 | 按 token + 按实例 + 企业套餐 |
| 部署方式 | SaaS | SaaS | 私有化 / SaaS 双模式 |
| 三件套文档 | ✅ (文件系统) | ❌ | ✅ (DB + 版本管理) |
| 质量门禁 | 用户确认 | CP1-CP3 | CP1-CP3 + 用户确认 |
| 断点续执行 | IDE 保存 | todo.md | DB 状态 + Agent 重连 |
十一、执行计划
MVP (Phase B) — 预估 2 周
| # | 任务 | 优先级 | 预估 | 备注 |
|---|---|---|---|---|
| 1 | 创建 8 张数据库表 | P0 | 2h | tickets + docs + steps + tool_calls + messages + artifacts + events + agent_roles |
| 2 | Portal API: 统一提交 + AI 路由 | P0 | 1d | /me/solo/submit，判断 chat/quick/project |
| 3 | Portal API: 工单 CRUD | P0 | 1d | 列表/详情/更新/取消 |
| 4 | Portal API: 快速模式执行 | P0 | 1.5d | 提交 → 自动执行 → 流式返回结果 |
| 5 | Portal API: 三件套生成 + 编辑 | P0 | 1d | Planner 生成 spec/tasks/checklist |
| 6 | Portal API: 确认/暂停/恢复 + WS | P0 | 1.5d | WebSocket 进度推送 |
| 7 | 前端: 统一首页 | P0 | 1d | 输入框 + 任务列表 |
| 8 | 前端: 快速模式 UI | P0 | 0.5d | 轻量进度 + 结果展示 |
| 9 | 前端: 项目模式 — 三件套确认页 | P0 | 1d | spec/tasks/checklist 编辑+确认 |
| 10 | 前端: 项目模式 — 实时工作区 | P0 | 2d | 双栏（任务流 + 预览/文件/日志） |
| 11 | OC 实例: Ticket 模式协议 | P1 | 2d | WS 协议扩展 |
| 12 | 产出物上传/下载/预览 | P1 | 0.5d | |
| 13 | 测试 + 部署 | P0 | 1d |
后续迭代
| 版本 | 功能 |
|---|---|
| v1.1 | 多 Agent 团队协作（调度 + 角色分配 + 中间产出物传递） |
| v1.2 | 断点续执行、Re-plan、Agent 角色管理后台 |
| v1.3 | 验收清单自动勾选（CP3 质量门禁） |
| v2.0 | 工单模板（常用任务一键创建）、Telegram 工单操作 |
| v2.1 | 多人协作（工单分配、评论、@提及、审批流） |
| v3.0 | 企业知识库接入（Knowledge + Datasource，≈ Manus Phase 1） |
十二、风险与对策
| 风险 | 影响 | 对策 |
|---|---|---|
| OC 框架不支持 Ticket 模式 | 无法逐步执行 Plan | MVP 用 Chat 模式模拟：把每个 Step 转为 prompt 下发，解析回复 |
| 三件套质量不稳定 | 用户不信任，每次都要大幅修改 | CP1 自动校验 + Planner 模型用最强的（opus） |
| 多 Agent 通信延迟 | 总耗时增加 | MVP 先用单 Agent，v1.1 再引入多 Agent |
| 用户不习惯新模式 | 继续只用 Chat | 统一入口 + AI 智能路由，无感切换 |
| 长任务 WS 断开 | 前端看不到进度 | 断线重连 + 轮询 fallback + 关键节点 Telegram 通知 |
| 产出物存储空间 | 磁盘满 | 定期清理 + 30 天自动归档 + 大文件 OSS |
| Agent 角色设计不合理 | 分工低效 | 先少后多，从 2-3 个通用角色开始，按需细化 |
附录：一句话总结
SayClaw SOLO = Manus 的大脑 + Trae 的交互 + 企业级的身份
用户说一句话，AI 自动判断走聊天/快速/项目模式。 简单的秒级完成，复杂的先规划再执行。 每一步可视可控，卡住时 AI 主动问你。 多 Agent 分工协作，专业的事交给专业的 Agent。 全过程审计可追溯，产出物统一管理可下载。