cs-bots 0.1.1 → 0.7.5

package/docs/01-/346/236/266/346/236/204/346/226/207/346/241/243.md

@@ -0,0 +1,364 @@
+# cs-bots 架构总览（改造07 · 分层架构 + 改造08 · 人机分治）
+
+> 版本：v0.7.3（改造07 分层 + 改造08 需求1–5）
+> 日期：2026-11-09
+> 状态：已实现，1108 项测试全通过（`bash test/run-all.sh` exit 0）
+
+---
+
+## 1. 一句话
+
+**cs-bots 是一个跑在 DeepSeek Harness 上的多智能体协作平台。改造07 把它从「扁平的页签集合」升级为「分层架构」：上层是人类协作层，下层是 AI 基础设施层，两者通过穿透入口显式连接。**
+
+---
+
+## 2. 分层架构总览
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    上层：人类协作层                            │
+│                                                              │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐        │
+│  │ 工作台    │ │ 团队     │ │ 记忆     │ │ 技能库    │        │
+│  │          │ │          │ │          │ │          │        │
+│  │ 任务看板  │ │ Bot 档案  │ │ 事实偏好  │ │ 技能     │        │
+│  │ PDCA复盘 │ │ 团队     │ │ 纪律要求  │ │ 工作流   │        │
+│  │ 待办便签  │ │ 房间     │ │ 提示词   │ │          │        │
+│  │ 成果     │ │ 成果     │ │          │ │          │        │
+│  └──────────┘ └──────────┘ └──────────┘ └──────────┘        │
+│                                                              │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │              人类操作界面（适合人看、人点）              │   │
+│  └──────────────────────────────────────────────────────┘   │
+└──────────────────────┬──────────────────────────────────────┘
+                       │ 顶部「⚙ 穿透」入口（显式，不隐藏）
+                       ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    下层：AI 基础设施层                          │
+│                                                              │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐        │
+│  │ 注册表    │ │ 唤醒桥    │ │ 存储     │ │ 路由     │        │
+│  │ Bot      │ │ Dispatcher│ │ Store    │ │ Routing  │        │
+│  │ 任务板    │ │          │ │ jsonl    │ │ T0-T3   │        │
+│  │ 团队     │ │ 事件流    │ │ 快照     │ │ free/paid│        │
+│  └──────────┘ └──────────┘ └──────────┘ └──────────┘        │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐                    │
+│  │ 验证     │ │ 建议     │ │ 订阅     │                    │
+│  │ Verify   │ │ Suggest  │ │ Subscription│                  │
+│  │ 验收证据  │ │ 确认制   │ │ 扇出     │                    │
+│  └──────────┘ └──────────┘ └──────────┘                    │
+│                                                              │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │         AI 智能体调用接口（机器友好、可审计）          │   │
+│  │   41 个 bot_* 工具 + HTTP API                          │   │
+│  └──────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 3. 分层原则（为什么这样分）
+
+### 3.1 上层调用下层，下层不反向调用上层
+
+- 上层的 UI 组件通过 HTTP API 获取数据
+- 下层的域服务通过 `tools.js` 暴露给模型
+- 两者互不感知对方的内部结构
+
+### 3.2 穿透是显式的，不是隐式的
+
+- 正常页面只显示上层
+- 下层通过顶部「⚙ 穿透」按钮显式进入
+- 穿透面板是**只读 + 有限操作**，不暴露全部底层能力
+
+### 3.3 保持「绝不静默失败」
+
+- 所有模块的所有操作都有明确返回值
+- 失败时返回人话 + 下一步建议
+- 所有操作落盘，可审计
+
+---
+
+## 4. 功能归属：哪些进上层，哪些进下层
+
+### 4.1 上层（人类协作层）—— 6 个页签
+
+| 页签 | 包含功能 | 人类视角 |
+|---|---|---|
+| **工作台** | 任务看板、PDCA 复盘、待办、便签、成果 | 人建任务、看进度、验收 |
+| **团队** | Bot 档案、团队列表、房间群聊 | 人管 Bot、看谁在干什么、进房间讨论 |
+| **记忆** | 事实与偏好、纪律与要求、提示词 | 人看 AI 记住了什么、改 AI 的行为准则 |
+| **技能库** | 技能、工作流 | 人看 AI 会什么、按什么步骤做 |
+| **数据** | 文件浏览、PDCA 测量指标 | 人看数据、看效率 |
+| **设置** | 平台参数、权限、安全 | 人配平台 |
+
+### 4.2 下层（AI 基础设施层）—— 7 个区块
+
+| 区块 | 包含功能 | 人类穿透后能做什么 |
+|---|---|---|
+| **注册表** | Bot 注册表、任务板事件流、团队注册 | 查看 Bot 生命周期、任务 CAS 历史 |
+| **唤醒桥** | Dispatcher 队列、去重表、背压状态 | 查看唤醒日志、手动触发唤醒、强制 flush |
+| **存储** | jsonl 事件流、快照、原子写、幂等集 | 查看存储健康、坏行统计、手动 replay |
+| **路由** | 复杂度路由 T0-T3、免费/付费策略 | 查看路由规则、查看路由决策日志 |
+| **验证** | 验收证据、退出码、测试结果 | 查看验收记录、手动重跑验收 |
+| **建议** | 建议确认队列、纪律提议 | 采纳/驳回建议 |
+| **订阅** | 任务订阅、房间扇出 | 查看订阅关系、订阅/取消订阅 |
+
+---
+
+## 5. 借鉴 Super-agent 的三项能力
+
+改造07 从官方 Super-agent 原型（`deepseek-ai/dsh-superagent-prototype`，研究原型，非正式产品）借鉴了三项能力：
+
+### 5.1 借鉴 3：Subscription 扇出（`src/subscription.js`）
+
+- 任务可订阅房间，房间后续消息自动到达任务（作为上下文）
+- **只加上下文，不改任务状态、不授予开工权力**
+- 幂等：同一 (taskId, roomId) 重复订阅返回既有记录
+- 滚动窗口：默认保留最近 20 条消息
+- 实现：`src/subscription.js` + API 端点 + 3 个新工具
+
+### 5.2 借鉴 4：工单阶段机（`src/stage.js`）
+
+- 8 个执行阶段，自上而下首个命中
+- 4 个 `person/*` 阶段需要人动手（强调色）
+- 纯函数、无副作用、不落盘
+- 实现：`src/stage.js` + API 附 `stageInfo` + 前端徽章
+
+### 5.3 借鉴 5：prepare command（`src/roster.js` + `src/api.js`）
+
+- Bot 可设开工准备命令（如 `git worktree add ...`）
+- claim 前先跑，失败则不认领（绝不产生半成品）
+- 安全边界：白名单 + execFile + 硬超时
+- 实现：`roster.setPrepareCommand` + API 集成 + `runPrepareCommand`
+
+---
+
+## 6. 技术栈
+
+| 层 | 技术 |
+|---|---|
+| 后端运行时 | Node.js ≥22.5，ESM，零第三方运行时依赖 |
+| HTTP API | 宿主 `webServer.register`（前缀路由 `/cs-bots/api`） |
+| 前端 | React 18，宿主模块加载器 `window.__ModuleLoader__.load` |
+| 模型工具 | 宿主 `tools.register`，41 个 `bot_*` 工具 |
+| 持久化 | JSONL 事件流 + 原子快照，SQLite 不引入 |
+| 安全 | 会话鉴权围栏 + 同源校验 + 受保护区 + CSRF 防护 |
+
+---
+
+## 7. 状态目录结构
+
+```
+$DSH_HOME/cs-bots/
+├── board.jsonl           任务板事件流（真相源）
+├── board.snap.json       任务板快照
+├── roster.jsonl          Bot 注册表事件流
+├── roster.snap.json      Bot 注册表快照
+├── wakes.jsonl           唤醒审计
+├── rooms/<roomId>/
+│   ├── log.jsonl         房间消息日志（永不截断）
+│   └── bodies/*.txt      长正文旁路
+├── memory.jsonl          记忆事件流
+├── memory.snap.json      记忆快照
+├── memory-fts.db         FTS5 检索索引
+├── discipline.jsonl      纪律事件流
+├── todo.jsonl            待办事件流
+├── prompts.jsonl         提示词库
+├── suggestions.jsonl     建议确认队列
+├── reviewer.jsonl        自审调度
+├── cycle.jsonl           PDCA 复盘事件流
+├── cycle.snap.json       PDCA 快照
+├── metrics.jsonl         指标记录
+├── subscription.jsonl    任务订阅事件流（改造07 新增）
+├── subscription.snap.json 任务订阅快照
+├── stage.json            阶段机（不落盘，纯派生，改造07 新增）
+├── scratch/<scope>.md    便签
+└── library-skill-dirs.json 技能来源目录
+```
+
+---
+
+## 8. 模块地图
+
+### 8.1 上层（人类协作层）
+
+```
+src/client.js          前端：6 页签 + 穿透面板 + 人类操作界面
+src/api.js             后端 HTTP API：/cs-bots/api/*
+```
+
+### 8.2 下层（AI 基础设施层）
+
+```
+src/board.js           任务板（CAS + 租约 + WIP + 验收 + 复杂度路由）
+src/dispatcher.js      唤醒桥（定向、去重、节流、背压、TTL）
+src/roster.js          Bot 注册表（持久 Bot + 独立 cwd + prepare command）
+src/teams.js           团队管理
+src/room.js            房间群聊（长消息旁路）
+src/memory.js          分层记忆 L0-L5 + FTS5 检索
+src/discipline.js      分级纪律（全局/工作区/房间/Bot）
+src/suggest.js         建议确认制
+src/cycle.js           PDCA 复盘（planned→doing→checking→acting→done）
+src/reviewer.js        自审调度
+src/verify.js          验收验证
+src/metrics.js         指标记录与聚合
+src/todo.js            待办（四轨 + 四象限）
+src/scratch.js         便签
+src/prompts.js         提示词库
+src/registry.js        技能库
+src/stage.js           工单阶段机（改造07 新增，纯派生）
+src/subscription.js    任务订阅 + 房间扇出（改造07 新增）
+src/routing/           复杂度路由
+src/store.js           存储原语（jsonl + 快照 + 幂等集 + 原子写）
+src/kernel.js          宿主桥（唯一可引用宿主包的文件）
+src/tools.js           41 个模型工具
+src/index.js           装配入口
+```
+
+---
+
+## 9. 改造前后对比
+
+| 维度 | 改造前（v0.6.x） | 改造后（v0.7.0） |
+|---|---|---|
+| 页签结构 | 10 个扁平页签 | 6 个上层页签 + 穿透面板 |
+| 任务状态 | 5 个粗粒度值 | 5 状态 + 8 阶段（派生） |
+| 房间→任务 | 无连接 | Subscription 扇出 |
+| Bot 开工 | 无准备步骤 | prepare command |
+| 底层可见性 | 无（黑盒） | 穿透面板（7 区块） |
+| 工具数 | 38 个 | 41 个 |
+| 测试数 | 949 项 | 1036 项 |
+
+---
+
+## 10. 设计原则（贯穿全部模块）
+
+1. **绝不静默失败**：所有失败都有明确返回值 + 落盘证据
+2. **事件流是真相源**：先落盘，再改内存，最后写快照
+3. **CAS 优先**：任何变更都要带 `expectedRev`
+4. **纯增量**：改造07 所有改动都是纯增量，不改动既有契约
+5. **零第三方运行时依赖**：只用 node 内置 + 宿主包
+6. **分层不隔层**：上层调用下层，下层不反向调用上层
+
+---
+
+## 11. 关键事实核对
+
+| 事实 | 来源 | 核对日期 |
+|---|---|---|
+| Super-agent 是研究原型，非官方产品 | `deepseek-ai/dsh-superagent-prototype` README | 2026-11-08 |
+| Agent Teams `maxMembers` 默认 8 | `dsh-experimental-agent-team` README | 2026-11-08 |
+| 改造07 借鉴 Super-agent 的 3/4/5 项能力 | 用户指定 | 2026-11-08 |
+| cs-bots 零第三方运行时依赖 | cs-bots README + package.json | 2026-11-08 |
+| 改造07 工具数 41 个 | `src/tools.js` 的 `TOOL_NAMES` | 2026-11-08 |
+| 改造07 测试数 1036 项 | `bash test/run-all.sh` | 2026-11-08 |
+| 改造09 准入闸 + Mandate 授权留痕 + WIP 并发槽位 + 结构化 Report | 用户指定 | 2026-11-09 |
+| 当前测试数 1108 项 | `bash test/run-all.sh` | 2026-11-09 |
+
+---
+
+*架构文档完。详细接口见《详细设计文档》。*
+
+---
+
+## 改造08 · 需求 1–5（2026-11-09）
+
+> 这一节的每一条都对应你原话里的一条要求，写完当天就上了线（0.7.3 已部署重启，启动图校验 PASS）。
+
+### 需求1 · 任务页只展示人建的任务，智能体任务单独一页
+
+| | 改前 | 改后 |
+|---|---|---|
+| 「我的任务」页 | 人和智能体的任务混在一起 | 只显示 `source=human`（你自建的任务） |
+| 智能体任务 | 混在同一个列表里翻 | 单独的「智能体任务」页签，按状态分类 |
+
+- 后端 `GET /tasks?source=human|ai` 早已支持（`src/board.js` 里 `source` 字段），这次是**前端把它用起来**。
+- 「我的任务」页保留「只看需要我处理的」开关；「智能体任务」页不显示这个开关（智能体的活不需要你逐条盯）。
+
+### 需求2 · 派活后能追踪进度、看到产出物、看到对话
+
+这一条挖到了一个**真 bug**，不是你操作的问题：
+
+> `eventsToMessages` 只读 `ev.content`，而官方会话事件是 `{ type, seq, time, data }`，
+> 内容在 `data.content` / `data.message.content` 里；`tool/call`、`tool/result` 是顶层事件。
+> 结果：**对任何真实会话都恒定返回 0 条** —— 所以你看到的就是「没有对话内容可看」。
+
+实测同一个真实会话（4795 个事件）：
+
+| | 修前 | 修后 |
+|---|---|---|
+| 对话片段总数 | **0** | **2625** |
+| 你的发言 | 0 | 110 |
+| 执行者正文 | 0 | 74 |
+| 思维链 | 0 | 465 |
+| 工具调用 | 0 | 1306 |
+| 工具结果 | 0 | 670 |
+
+新增/变更：
+
+- 后端 `GET /tasks/conversation?id=&limit=` —— 只读打开执行者会话（`persistence.open(id,'read')`，不抢所有权），返回 `{ bot, sessionId, messages[], total, truncated, available }`。
+- 前端任务详情新增**任务对话**面板：显示执行者身份、消息条数；默认只给正文（手机不被思维链淹没），点「看全部」才展开工具调用与思维链；「去对话」直接打开它的会话，宿主不支持就复制会话 ID 兜底。
+- 无执行者时是**空态**（「还没有执行者」+ 下一步），不是报错。
+- 产出物空态改成说清「为什么现在没有」：未完成时正常；已完成却没带证据时提示可以重开补交。
+
+### 需求3 · 团队页只显示你建的团队，负责人有标识，成员可选
+
+- 团队页只拉 `GET /teams?type=big`（后端 `type` 字段保留不动，只是 UI 不再暴露「大小团队」概念）。
+- 负责人带 `👑 负责人` 标识，成员列表里负责人加 `👑 ` 前缀；移出负责人会明确警告「移出后团队将没有负责人」。
+- 建团队时负责人用下拉选择，成员用勾选组（可多选，支持新建 Bot 后再来选）。
+- 「看房间」→ 跳房间页并**按团队名定向筛选**：房间页顶部出现「筛选房间：包含「X」→ N 个房间」和「✕ 清筛选」。
+- 你要的「穿透房间看子团队工作内容」：房间页本来就是超级管理员视角，所有房间都能进、都能看长正文（`withBody=1` 一次取回），筛选只是在大列表里做定向。
+
+### 需求4 · PDCA 人机分治（这条改动最大）
+
+你的原话：「pdca 是对用户长任务进行复盘跟进的，人类主导；智能体的 pdca 流程你优化一下」。
+
+结论是**两种周期，两套纪律**：
+
+| | `kind=human`（你的） | `kind=agent`（智能体的） |
+|---|---|---|
+| 谁主导 | **你** | 智能体自己 |
+| 用途 | 跟长任务、防漂移 | 定期批量归纳、自我提升 |
+| 阶段纪律 | 计划→执行→检查→改进→完成，**五步不可跳** | 复盘可**一次性提交**，提交即自动闭环 |
+| UI 位置 | 「📋 我的任务周期」（主区） | 「🤖 智能体归纳周期」（折叠在下方） |
+| 复盘后 | 留在「改进」等你显式推进到完成 | 自动 → 完成（`autoClosed: true`） |
+| 产出 | 经验教训 + 标准化建议 | 同左，但**只进建议队列**，你采纳才落库 |
+
+为什么 agent 允许一次性提交：让它假装走 `planned→doing` 是对事实的虚构。你要的是「结论 + 可采纳的标准」，不是看它表演流程。
+
+**「定期」怎么落地**：`reviewer` 只做被动回合计数（每回合 +1，到阈值就 `due`），它不自己起定时器（宿主生命周期不可控）。所以：
+
+1. 周期页读 `GET /review/status`，把到期会话列出来（当前线上实测 3 个会话到期，共 111 回合）；
+2. 你点「让它归纳」→ `POST /review/urge` 唤醒它，并给它明确三步指令（开 `kind=agent` 周期 → 一次性复盘 → 建议进队列）；
+3. 归纳出的纪律**不会自动改自己**，走 `bot_suggestion_propose`，你采纳才生效。
+
+这条暗道是被故意堵死的：智能体不能自己给自己立规矩。
+
+### 需求5 · 表述更正
+
+任务详情 5W 区：
+
+- 「谁建的」：`source=human` → **用户**；智能体分发 → 显示 Bot 名。
+- 「来源」：`source=human` → **用户自建**；否则 → 智能体分发。
+
+不再把「`ui`」这种平台伪身份暴露给你看。
+
+### 验证证据（可核查）
+
+```
+test/kernel-conversation.test.mjs   8 项  ✅
+test/client-anchor.test.mjs        39 项  ✅
+全套 node --test test/*.test.mjs  → 1108 / 1108 pass, 0 fail
+bash test/run-all.sh              → ✅ 全部通过（exit 0）
+dsh-plugins.sh precheck           → OK cs-bots -> src/client.js
+dsh web 重启                      → 启动图端到端校验 PASS
+
+线上实测（http://150.158.175.241/）
+GET /cs-bots/api/tasks/conversation?id=t-29   → ok=true（无对话时如实 0 条）
+GET /cs-bots/api/review/status                → sessions=24, due=true, dueSessions=3
+GET /cs-bots/api/cycles?kind=human            → 只返回 human 周期
+GET /cs-bots/api/cycles?kind=agent            → items=[]（尚无 agent 周期）
+GET /cs-bots/api/teams?type=big               → 1 个团队（Myfree改造，leadId 有值）
+下发 bundle（362 KB）                          → 含 TaskConversationPanel / roomFilter / 让它归纳
+```

package/docs/02-/351/234/200/346/261/202/350/247/204/346/240/274/344/271/246.md

@@ -0,0 +1,284 @@
+# cs-bots 改造07 + 改造08（需求1–5）需求规格书
+
+> 版本：v0.7.3（改造07 分层 + 改造08 需求1–5）
+> 日期：2026-11-09
+> 状态：已实现
+
+---
+
+## 1. 背景与目标
+
+### 1.1 改造前的问题
+
+cs-bots v0.6.x 有 10 个扁平页签，所有功能平铺在一起，人和 AI 的能力边界不分。用户提出三个核心诉求：
+
+1. **分层**：把「人用的功能」和「AI 用的底层工具」分开
+2. **穿透**：正常只看人用的，需要时能进底层查看/管理
+3. **借鉴**：借鉴 DSH Super-agent 的三项能力（不借鉴 Source 外部事件驱动、不借鉴 Eval 准入模型）
+
+### 1.2 改造目标
+
+| 目标 | 验收标准 |
+|---|---|
+| G1 分层架构 | 6 个上层页签 + 7 个下层区块，职责清晰 |
+| G2 穿透入口 | 顶部「⚙ 穿透」按钮，点开可见 7 个区块，每区块可展开详情 |
+| G3 借鉴3 Subscription | 任务可订阅房间，房间消息自动作为上下文到达任务 |
+| G4 借鉴4 阶段机 | 任务带 8 阶段派生信息，`needsPerson` 正确标识「该人动手」 |
+| G5 借鉴5 prepare | Bot 可设准备命令，claim 前执行，失败不认领 |
+| G6 文档交付 | 架构、需求规格、详设、操作手册四份文档 |
+| G7 质量门禁 | 全部既有测试通过 + 新增测试覆盖新能力 |
+
+### 1.3 明确不做的事
+
+| 不做 | 原因 |
+|---|---|
+| 不借鉴 Source（外部事件驱动建任务） | 用户明确不要 |
+| 不借鉴 Eval（准入模型/gate+assessment） | 用户明确不要 |
+| 不引入第三方运行时依赖 | 保持零依赖纪律 |
+| 不改动既有 38 个工具的契约 | 纯增量原则 |
+
+---
+
+## 2. 功能需求
+
+### FR-1：分层导航
+
+**描述**：把 10 个扁平页签重组为 6 个上层页签。
+
+| 需求 | 说明 |
+|---|---|
+| FR-1.1 | 页签为：工作台、团队、记忆、技能库、数据、设置 |
+| FR-1.2 | 工作台含：协作看板、复盘周期、我的待办、便签、成果 |
+| FR-1.3 | 团队含：Bot 档案、团队、房间 |
+| FR-1.4 | 记忆含：事实与偏好、纪律与要求、提示词 |
+| FR-1.5 | 技能库含：技能、工作流 |
+| FR-1.6 | 数据含：文件浏览、PDCA 测量 |
+| FR-1.7 | 旧页签 id（tasks/bots/rooms/teams/artifacts）通过 `safeGoTab` 自动映射到新页签，向后兼容 |
+
+**验收**：页面只剩 6 个页签；旧 `onGoto('tasks')` 等调用仍能正确跳转。
+
+### FR-2：穿透面板
+
+**描述**：顶部「⚙ 穿透」按钮打开右侧抽屉，显示 7 个下层区块。
+
+| 需求 | 说明 |
+|---|---|
+| FR-2.1 | 区块为：注册表、唤醒桥、存储、路由、验证、建议、订阅 |
+| FR-2.2 | 每区块显示 label + description + stats 概览 |
+| FR-2.3 | 点击区块展开详情（GET `/deepdive/block/:id`） |
+| FR-2.4 | 支持的区块操作：唤醒桥 flush、存储 replay |
+| FR-2.5 | 未知区块返回 404 + 可读原因；不支持的操作返回 400 |
+| FR-2.6 | 所有操作有明确返回值（成功/失败 + 人话） |
+
+**验收**：`GET /deepdive/blocks` 返回 7 个区块；`POST /deepdive/op {block:'store',op:'replay'}` 成功。
+
+### FR-3：Subscription 扇出（借鉴 Super-agent）
+
+**描述**：任务可订阅房间，房间后续消息自动作为上下文到达任务。
+
+| 需求 | 说明 |
+|---|---|
+| FR-3.1 | `subscribe(taskId, roomId, note?, by)` 创建订阅，幂等 |
+| FR-3.2 | `unsubscribe(id, expectedRev?, by)` 取消订阅（终态） |
+| FR-3.3 | `fanout(roomId, message, wake?)` 把消息扇出给订阅该房间的活任务 |
+| FR-3.4 | 扇出**只加上下文，不改任务状态、不授予开工权力** |
+| FR-3.5 | 上下文滚动窗口，默认保留最近 20 条（`fanoutKeep`） |
+| FR-3.6 | 每条上下文文本截断到 2000 字符（防爆炸） |
+| FR-3.7 | 扇出默认**不唤醒** owner（`wakeOnFanout:false`） |
+| FR-3.8 | 房间发消息后（POST `/rooms/post`）自动触发扇出 |
+| FR-3.9 | CAS：unsubscribe 带 `expectedRev` 不匹配即抛错 |
+
+**验收**：订阅后发房间消息，任务 `context` 增加；取消订阅后不再增加。
+
+### FR-4：工单阶段机（借鉴 Super-agent）
+
+**描述**：任务带 8 个执行阶段的派生信息。
+
+| 需求 | 说明 |
+|---|---|
+| FR-4.1 | 8 阶段：person/delivery、person/answer、person/review、person/blocked、person/failed、working/queued、idle、working |
+| FR-4.2 | 判定自上而下首个命中（顺序即优先级） |
+| FR-4.3 | 投递失败最高优先级 |
+| FR-4.4 | 4 个 `person/*` 阶段 `needsPerson=true` |
+| FR-4.5 | 纯函数，不落盘，不修改入参 |
+| FR-4.6 | `GET /tasks` 每条任务带 `stageInfo`，响应带 `stageSummary` |
+| FR-4.7 | `GET /tasks/detail` 和 `GET /tasks/summary` 带 `stageInfo` |
+| FR-4.8 | 前端任务卡片显示阶段徽章，person 阶段用强调色 |
+
+**验收**：新建任务显示「排队中」；完成未验收显示「等你验收」。
+
+### FR-5：prepare command（借鉴 Super-agent）
+
+**描述**：Bot 可设开工准备命令。
+
+| 需求 | 说明 |
+|---|---|
+| FR-5.1 | Bot 注册表新增 `prepareCommand` 字段（可选） |
+| FR-5.2 | 创建时带 `prepareCommand` 落盘 |
+| FR-5.3 | `setPrepareCommand(id, prepareCommand, expectedRev, byId)` 设置/清除 |
+| FR-5.4 | claim 前先执行 prepare；失败则不认领，任务保持原状 |
+| FR-5.5 | 安全边界：命令首段必须在 `CMD_WHITELIST` 内 |
+| FR-5.6 | 用 execFile 传参数组，不经 shell（无注入面） |
+| FR-5.7 | 硬超时 10 分钟 |
+| FR-5.8 | cwd 固定为 Bot 工作目录 |
+| FR-5.9 | `prepare_command_set` 动作写入事件流（可审计） |
+
+**验收**：设 prepare 后派活，prepare 成功则 claim 成功，失败则返回 `PREPARE_FAILED`。
+
+---
+
+## 3. 非功能需求
+
+| 编号 | 需求 | 验收 |
+|---|---|---|
+| NFR-1 | 零第三方运行时依赖 | `bash test/ci-zero-dep.sh` 通过 |
+| NFR-2 | 全部既有测试通过 | 1108 项测试 0 失败 |
+| NFR-3 | 零 `window.prompt/confirm/alert` | CI 检查 5 通过 |
+| NFR-4 | 所有失败可读 | 每个错误有 code + 人话 |
+| NFR-5 | 移动端可用 | 页签横向滚动、穿透面板全屏抽屉 |
+| NFR-6 | 向后兼容 | 旧页签 id 自动映射 |
+
+---
+
+## 4. 约束
+
+| 约束 | 说明 |
+|---|---|
+| C-1 | 不改动既有 38 个工具的契约 |
+| C-2 | 新增工具走 `bot_` 前缀 |
+| C-3 | 新增模块走独立文件，复用 `store.js` |
+| C-4 | 事件流是真相源，先落盘再改内存 |
+| C-5 | 所有变更带 CAS |
+| C-6 | 单一入口 `bash test/run-all.sh` 判定交付 |
+
+---
+
+## 5. 交付物清单
+
+| 交付物 | 路径 | 状态 |
+|---|---|---|
+| 架构文档 | `docs/01-架构文档.md` | ✅ |
+| 需求规格书 | `docs/02-需求规格书.md` | ✅ |
+| 详细设计文档 | `docs/03-详细设计.md` | ⏳ |
+| 用户操作手册 | `docs/04-操作手册.md` | ⏳ |
+| 实现代码 | `src/stage.js`、`src/subscription.js` 等 | ✅ |
+| 测试 | `test/stage.test.mjs`、`test/subscription.test.mjs` 等 | ✅ |
+
+---
+
+## 6. 需求追溯矩阵
+
+| 需求 | 实现文件 | 测试 |
+|---|---|---|
+| FR-1 分层导航 | `src/client.js` TABS | `test/client.test.mjs` B1 |
+| FR-2 穿透面板 | `src/api.js` deepdive、`src/client.js` DeepDivePanel | `test/api.test.mjs` 改造07 穿透×8 |
+| FR-3 Subscription | `src/subscription.js` | `test/subscription.test.mjs` ×17 |
+| FR-4 阶段机 | `src/stage.js` | `test/stage.test.mjs` ×30 |
+| FR-5 prepare | `src/roster.js`、`src/api.js` | `test/roster.test.mjs` 改造07 prepare×8 |
+| NFR-1 零依赖 | - | `test/ci-zero-dep.sh` |
+
+---
+
+*需求规格书完。*
+---
+
+## 改造08 · 需求 1–5（2026-11-09）
+
+> 这一节的每一条都对应你原话里的一条要求，写完当天就上了线（0.7.3 已部署重启，启动图校验 PASS）。
+
+### 需求1 · 任务页只展示人建的任务，智能体任务单独一页
+
+| | 改前 | 改后 |
+|---|---|---|
+| 「我的任务」页 | 人和智能体的任务混在一起 | 只显示 `source=human`（你自建的任务） |
+| 智能体任务 | 混在同一个列表里翻 | 单独的「智能体任务」页签，按状态分类 |
+
+- 后端 `GET /tasks?source=human|ai` 早已支持（`src/board.js` 里 `source` 字段），这次是**前端把它用起来**。
+- 「我的任务」页保留「只看需要我处理的」开关；「智能体任务」页不显示这个开关（智能体的活不需要你逐条盯）。
+
+### 需求2 · 派活后能追踪进度、看到产出物、看到对话
+
+这一条挖到了一个**真 bug**，不是你操作的问题：
+
+> `eventsToMessages` 只读 `ev.content`，而官方会话事件是 `{ type, seq, time, data }`，
+> 内容在 `data.content` / `data.message.content` 里；`tool/call`、`tool/result` 是顶层事件。
+> 结果：**对任何真实会话都恒定返回 0 条** —— 所以你看到的就是「没有对话内容可看」。
+
+实测同一个真实会话（4795 个事件）：
+
+| | 修前 | 修后 |
+|---|---|---|
+| 对话片段总数 | **0** | **2625** |
+| 你的发言 | 0 | 110 |
+| 执行者正文 | 0 | 74 |
+| 思维链 | 0 | 465 |
+| 工具调用 | 0 | 1306 |
+| 工具结果 | 0 | 670 |
+
+新增/变更：
+
+- 后端 `GET /tasks/conversation?id=&limit=` —— 只读打开执行者会话（`persistence.open(id,'read')`，不抢所有权），返回 `{ bot, sessionId, messages[], total, truncated, available }`。
+- 前端任务详情新增**任务对话**面板：显示执行者身份、消息条数；默认只给正文（手机不被思维链淹没），点「看全部」才展开工具调用与思维链；「去对话」直接打开它的会话，宿主不支持就复制会话 ID 兜底。
+- 无执行者时是**空态**（「还没有执行者」+ 下一步），不是报错。
+- 产出物空态改成说清「为什么现在没有」：未完成时正常；已完成却没带证据时提示可以重开补交。
+
+### 需求3 · 团队页只显示你建的团队，负责人有标识，成员可选
+
+- 团队页只拉 `GET /teams?type=big`（后端 `type` 字段保留不动，只是 UI 不再暴露「大小团队」概念）。
+- 负责人带 `👑 负责人` 标识，成员列表里负责人加 `👑 ` 前缀；移出负责人会明确警告「移出后团队将没有负责人」。
+- 建团队时负责人用下拉选择，成员用勾选组（可多选，支持新建 Bot 后再来选）。
+- 「看房间」→ 跳房间页并**按团队名定向筛选**：房间页顶部出现「筛选房间：包含「X」→ N 个房间」和「✕ 清筛选」。
+- 你要的「穿透房间看子团队工作内容」：房间页本来就是超级管理员视角，所有房间都能进、都能看长正文（`withBody=1` 一次取回），筛选只是在大列表里做定向。
+
+### 需求4 · PDCA 人机分治（这条改动最大）
+
+你的原话：「pdca 是对用户长任务进行复盘跟进的，人类主导；智能体的 pdca 流程你优化一下」。
+
+结论是**两种周期，两套纪律**：
+
+| | `kind=human`（你的） | `kind=agent`（智能体的） |
+|---|---|---|
+| 谁主导 | **你** | 智能体自己 |
+| 用途 | 跟长任务、防漂移 | 定期批量归纳、自我提升 |
+| 阶段纪律 | 计划→执行→检查→改进→完成，**五步不可跳** | 复盘可**一次性提交**，提交即自动闭环 |
+| UI 位置 | 「📋 我的任务周期」（主区） | 「🤖 智能体归纳周期」（折叠在下方） |
+| 复盘后 | 留在「改进」等你显式推进到完成 | 自动 → 完成（`autoClosed: true`） |
+| 产出 | 经验教训 + 标准化建议 | 同左，但**只进建议队列**，你采纳才落库 |
+
+为什么 agent 允许一次性提交：让它假装走 `planned→doing` 是对事实的虚构。你要的是「结论 + 可采纳的标准」，不是看它表演流程。
+
+**「定期」怎么落地**：`reviewer` 只做被动回合计数（每回合 +1，到阈值就 `due`），它不自己起定时器（宿主生命周期不可控）。所以：
+
+1. 周期页读 `GET /review/status`，把到期会话列出来（当前线上实测 3 个会话到期，共 111 回合）；
+2. 你点「让它归纳」→ `POST /review/urge` 唤醒它，并给它明确三步指令（开 `kind=agent` 周期 → 一次性复盘 → 建议进队列）；
+3. 归纳出的纪律**不会自动改自己**，走 `bot_suggestion_propose`，你采纳才生效。
+
+这条暗道是被故意堵死的：智能体不能自己给自己立规矩。
+
+### 需求5 · 表述更正
+
+任务详情 5W 区：
+
+- 「谁建的」：`source=human` → **用户**；智能体分发 → 显示 Bot 名。
+- 「来源」：`source=human` → **用户自建**；否则 → 智能体分发。
+
+不再把「`ui`」这种平台伪身份暴露给你看。
+
+### 验证证据（可核查）
+
+```
+test/kernel-conversation.test.mjs   8 项  ✅
+test/client-anchor.test.mjs        39 项  ✅
+全套 node --test test/*.test.mjs  → 1108 / 1108 pass, 0 fail
+bash test/run-all.sh              → ✅ 全部通过（exit 0）
+dsh-plugins.sh precheck           → OK cs-bots -> src/client.js
+dsh web 重启                      → 启动图端到端校验 PASS
+
+线上实测（http://150.158.175.241/）
+GET /cs-bots/api/tasks/conversation?id=t-29   → ok=true（无对话时如实 0 条）
+GET /cs-bots/api/review/status                → sessions=24, due=true, dueSessions=3
+GET /cs-bots/api/cycles?kind=human            → 只返回 human 周期
+GET /cs-bots/api/cycles?kind=agent            → items=[]（尚无 agent 周期）
+GET /cs-bots/api/teams?type=big               → 1 个团队（Myfree改造，leadId 有值）
+下发 bundle（362 KB）                          → 含 TaskConversationPanel / roomFilter / 让它归纳
+```