cs-bots 0.1.1 → 0.7.5

package/docs/03-/350/257/246/347/273/206/350/256/276/350/256/241.md

@@ -0,0 +1,567 @@
+# cs-bots 改造07 + 改造08（需求1–5）详细设计文档
+
+> 版本：v0.7.3（改造07 分层 + 改造08 需求1–5）
+> 日期：2026-11-09
+> 状态：已实现，1108 项测试全通过（`bash test/run-all.sh` exit 0）
+
+---
+
+## 1. 文档定位
+
+本文档是**实现级**设计，回答「每个模块的具体接口、数据结构、错误码、边界条件」。架构层面的分层原则见《架构文档》。
+
+---
+
+## 2. 模块一：StageService（工单阶段机）
+
+### 2.1 设计动机
+
+现有任务状态只有 5 个粗粒度值，回答不了「此刻卡在谁身上」。实测痛点：任务显示 in_progress 十几小时纹丝不动，人不知道为什么——是 Bot 在跑？在排队？在等人回答？还是投递失败没人知道？
+
+借 Super-agent 的 stage table 把「在做」切成 8 个可判定阶段，其中 5 个是「等人」阶段，人一眼看出该谁动手。
+
+### 2.2 数据结构
+
+```js
+// 阶段枚举（值即稳定 id，不可改名）
+export const STAGES = Object.freeze({
+  PERSON_DELIVERY: 'person/delivery',
+  PERSON_ANSWER:   'person/answer',
+  PERSON_REVIEW:   'person/review',
+  PERSON_BLOCKED:  'person/blocked',
+  PERSON_FAILED:   'person/failed',
+  WORKING_QUEUED:  'working/queued',
+  IDLE:            'idle',
+  WORKING:         'working',
+})
+
+// 判定优先级（自上而下首个命中）
+export const STAGE_ORDER = [PERSON_DELIVERY, PERSON_ANSWER, PERSON_REVIEW,
+                            PERSON_BLOCKED, PERSON_FAILED, WORKING_QUEUED,
+                            IDLE, WORKING]
+
+// 人类标签（界面直接展示）
+export const STAGE_LABEL = {
+  'person/delivery': '投递失败',
+  'person/answer':   '等你回答',
+  'person/review':   '等你验收',
+  'person/blocked':  '受阻等你',
+  'person/failed':   '失败等你',
+  'working/queued':  '排队中',
+  'idle':            '空闲等触发',
+  'working':         '正在干',
+}
+
+// 语义分组（前端配色 + needsPerson 判定）
+export const STAGE_GROUP = {
+  'person/delivery': 'person',
+  'person/answer':   'person',
+  'person/review':   'person',
+  'person/blocked':  'person',
+  'person/failed':   'person',
+  'working/queued':  'working',
+  'idle':            'idle',
+  'working':         'working',
+}
+```
+
+### 2.3 核心函数
+
+```js
+/**
+ * 判定任务执行阶段（纯函数，不修改入参，不落盘）
+ * @param {object} task board 的 Task 形状
+ * @returns {{ stage, label, group, needsPerson, reason }}
+ */
+export function deriveStage(task)
+```
+
+**判定流程（自上而下首个命中）**：
+
+| 顺序 | 条件 | 阶段 | 人话 |
+|---|---|---|---|
+| 0 | `status==='deleted'` | idle | 已删除（终态） |
+| 0 | `status==='completed' && accepted!==true` | person/review | 已完成，等验收 |
+| 0 | `status==='completed' && accepted===true` | idle | 已完成且验收 |
+| 1 | `delivery.error` 非空 | person/delivery | 投递失败：xxx |
+| 2 | `latestReport.attention` 非空 | person/answer | 执行者提了问题 |
+| 3 | `latestReport.state==='blocked'` | person/blocked | 执行者报告受阻 |
+| 4 | `latestReport.state==='failed'` | person/failed | 执行者报告失败 |
+| 5 | `latestReport.state==='ready'` | person/review | 交付物就绪 |
+| 6 | 无 owner 且无未过期 lease | working/queued | 尚未被认领 |
+| 7 | `latestReport.state==='waiting'` | idle | 本轮已交付 |
+| 8 | 兜底 | working | 正在推进 |
+
+**报告形状的宽容性**：`latestReport` 支持三种历史形状：
+- 字符串：`'ready'`
+- 对象：`{ state: 'ready' }`
+- 对象：`{ status: 'ready' }`
+
+### 2.4 批量与统计
+
+```js
+/** 批量派生，不修改原数组 */
+export function attachStages(tasks)  // → [{ ...task, stageInfo }]
+
+/** 按语义分组计数（排除 deleted） */
+export function stageSummary(tasks)  // → { person, working, idle, total }
+```
+
+### 2.5 错误码
+
+| 码 | 场景 |
+|---|---|
+| 无 | 阶段机不抛错（纯函数，输入非法时保守落到 working/queued） |
+
+---
+
+## 3. 模块二：SubscriptionService（任务订阅扇出）
+
+### 3.1 设计动机
+
+房间里的讨论在推进，但相关任务看不到——人只好手动补一句「刚才房间说……」。借 Super-agent 的 Subscription 解决：订阅后，房间后续消息自动到达任务，不需要再 @。
+
+### 3.2 数据结构
+
+```js
+/** Subscription 记录 */
+{
+  id: 'sub-1',              // 订阅 id
+  rev: 1,                   // CAS 版本
+  taskId: 't-1',            // 任务
+  roomId: 'room-a',         // 房间
+  state: 'active',          // active | dropped
+  context: [                // 滚动上下文窗口
+    { from, seq, text, at, messageId }
+  ],
+  fanoutCount: 0,           // 累计扇出次数
+  note: '为什么订阅',        // 可选
+  createdAt, createdBy,
+  updatedAt, updatedBy,
+  droppedAt, droppedBy,     // dropped 时有
+}
+```
+
+### 3.3 核心接口
+
+```js
+/**
+ * 订阅（幂等：同一 taskId+roomId 已有活订阅时返回既有记录）
+ * @param {{ taskId, roomId, note?, by, now? }} input
+ */
+subscribe(input) → Subscription
+
+/**
+ * 取消订阅（终态：active → dropped，不可逆）
+ * @param {{ id, expectedRev?, by, now? }} input
+ */
+unsubscribe(input) → Subscription
+
+/**
+ * 扇出：把房间消息送达所有订阅该房间的活任务
+ * @param {{ roomId, message, wake?, by?, now? }} input
+ * @returns {{ fanned, woke, failed, details }}
+ */
+fanout(input) → Promise<result>
+
+/** 列表（按 taskId/roomId/state 过滤） */
+list(query) → Subscription[]
+
+/** 某任务的订阅（任务详情用） */
+listByTask(taskId) → Subscription[]
+
+/** 某房间的订阅者任务 id（房间页用） */
+subscribersOf(roomId) → string[]
+
+/** 统计 */
+stats() → { total, active, dropped, byState, fanouts, wakeFailures, events }
+
+/** 从事件流重建 */
+replay() → { from, events, bad }
+```
+
+### 3.4 配置项
+
+| 配置 | 默认 | 说明 |
+|---|---|---|
+| `fanoutKeep` | 20 | 每个任务保留的上下文条目上限 |
+| `wakeOnFanout` | false | 扇出后是否唤醒 owner |
+| `stateDir` | kernel.stateDir() | 状态目录 |
+
+### 3.5 扇出逻辑
+
+```
+for each active subscription of roomId:
+  1. 构造 context entry（text 截断 2000 字符）
+  2. context = [...old, entry]，若超 fanoutKeep 则 slice(-fanoutKeep)
+  3. fanoutCount++
+  4. commit('fanout') —— 先落盘
+  5. 若 shouldWake：
+     a. 找 task.ownerId
+     b. kernel.followup(ctx, ownerId, text)
+     c. 成功 woke++，失败 failed++
+```
+
+### 3.6 错误码
+
+| 码 | 场景 |
+|---|---|
+| `SUBSCRIPTION_ERROR` | 通用 |
+| `SUBSCRIPTION_BAD_FIELD` | 字段类型/缺失 |
+| `SUBSCRIPTION_NOT_FOUND` | 订阅不存在 |
+| `SUBSCRIPTION_REV_CONFLICT` | CAS 冲突 |
+| `SUBSCRIPTION_ALREADY_DROPPED` | 已 dropped 再取消 |
+| `SUBSCRIPTION_APPEND_FAILED` | 落盘失败 |
+| `SUBSCRIPTION_NO_STATE_DIR` | 无状态目录 |
+
+### 3.7 与 Super-agent 的差异
+
+| 维度 | Super-agent | cs-bots |
+|---|---|---|
+| 订阅主体 | Ticket ↔ Thread | Task ↔ Room |
+| 扇出后果 | 消息作为上下文 Input | 消息作为任务上下文，可选唤醒 |
+| 授权影响 | 只加 context 不加 authority | 同 |
+| 生成方式 | 模型/人订阅 | 人/模型订阅 |
+
+---
+
+## 4. 模块三：prepare command
+
+### 4.1 设计动机
+
+Bot 开工前常需要准备环境（拉代码、建 worktree、装依赖）。借 Super-agent 的 prepare command。
+
+### 4.2 数据结构
+
+Bot 记录新增字段：
+
+```js
+{
+  // ...既有字段
+  prepareCommand: 'git worktree add ../x main',  // 可选
+  prepareCommandSetAt: 1730000000000,
+  prepareCommandSetBy: 'lead',
+}
+```
+
+### 4.3 接口
+
+```js
+// roster.js
+setPrepareCommand({ id, prepareCommand, expectedRev, byId, now? }) → Bot
+// 传空字符串/null = 清除（三字段一起清）
+
+// api.js（内部 helper）
+runPrepareCommand(bot, { timeoutMs? }) → Promise<{
+  ok, skipped?, command?, cwd?, exitCode?, stdout?, stderr?, error?
+}>
+```
+
+### 4.4 claim 时执行流程（POST /tasks/assign）
+
+```
+1. 读 Bot（roster.get(ownerId)）
+2. 若 bot.prepareCommand 非空：
+   a. prepare = await runPrepareCommand(bot)
+   b. 若 !prepare.ok：
+      - 不 claim（任务保持原状）
+      - 返回 { ok:false, code:'PREPARE_FAILED', prepare, reason }
+      - return
+3. claim 任务（board.update action:'claim'）
+4. 唤醒 owner（dispatcher.notify）
+```
+
+### 4.5 安全边界
+
+| 措施 | 说明 |
+|---|---|
+| 白名单 | 首段必须在 `CMD_WHITELIST`：bash/node/npm/pnpm/npx/git/ls/test/python3 |
+| 无 shell | `execFile(cmd, args)` 传参数组，不做 shell 展开 |
+| 硬超时 | 默认 10 分钟（`timeout` 参数） |
+| cwd 固定 | Bot 工作目录（写入边界） |
+| 参数切分 | 只按空白切分，不做引号/管道/重定向 |
+
+### 4.6 错误码
+
+| 码 | 场景 |
+|---|---|
+| `prepare-command-not-allowed:xxx` | 首段不在白名单 |
+| `bot-cwd-missing` | Bot 无 cwd |
+| `timeout` | 超时 |
+| `PREPARE_FAILED`（API） | 准备失败，未认领 |
+
+---
+
+## 5. 模块四：穿透面板（DeepDive）
+
+### 5.1 设计动机
+
+下层是 AI 的基础设施，人不该天天看，但排查问题时必须能进。穿透是**显式入口**：顶部「⚙ 穿透」，不是隐藏的。
+
+### 5.2 API 端点
+
+```js
+// GET /deepdive/blocks
+// 返回 7 个区块：registry / wake / store / routing / verify / suggest / subscription
+{
+  ok: true,
+  blocks: [
+    { id, label, description, stats: {...} }
+  ]
+}
+
+// GET /deepdive/block/:id
+{
+  ok: true,
+  block: 'registry',
+  data: { bots: [...] },          // 区块内容（形状因区块而异）
+  operations: [                    // 可执行操作
+    { id: 'revive', label: '...', body: {} }
+  ]
+}
+
+// POST /deepdive/op
+// body: { block, op, ...opBody }
+{ ok: true, text: '已强制投递：sent=3, failed=0', result: {...} }
+```
+
+### 5.3 七个区块
+
+| 区块 | stats 内容 | 可执行操作 |
+|---|---|---|
+| registry | bots 数量、各状态计数 | — |
+| wake | total/sent/skipped/failed/pending | flush |
+| store | 存在的文件数/总数 | replay |
+| routing | tiers、default | — |
+| verify | verify 服务 stats | — |
+| suggest | suggest 服务 stats | — |
+| subscription | 订阅 stats | — |
+
+### 5.4 前端组件
+
+```js
+function DeepDivePanel({ onClose }) {
+  // useDeepDive() → GET /deepdive/blocks
+  // openBlock(id) → GET /deepdive/block/:id
+  // doOp(block, op, body) → POST /deepdive/op
+}
+```
+
+渲染结构：
+```
+Drawer(底层工具)
+├── 每个区块：Card(label + description + stats + 展开箭头)
+└── 展开时：区块详情（data 字段逐个渲染 + operations 按钮）
+```
+
+### 5.5 错误处理
+
+| 场景 | 处理 |
+|---|---|
+| 区块加载失败 | 显示 `穿透面板加载失败：<原因>` |
+| 区块详情失败 | 显示错误 |
+| 操作失败 | 显示人话 + 原因 |
+| 未知区块 | 404 + `未知区块: xxx` |
+| 不支持的操作 | 400 + `不支持的操作：block/op` |
+
+---
+
+## 6. 模块五：分层导航
+
+### 6.1 TABS 结构
+
+```js
+const TABS = [
+  { id: 'workspace', label: '工作台', subs: [board, cycles, todo, scratch, artifacts] },
+  { id: 'team',      label: '团队',   subs: [bots, teams, rooms] },
+  { id: 'memory',    label: '记忆',   subs: [facts, rules, prompts] },
+  { id: 'skills',    label: '技能库', subs: [skills, workflows] },
+  { id: 'data',      label: '数据',   subs: [files, metrics] },
+  { id: 'settings',  label: '设置',   Comp: SettingsBody },
+]
+```
+
+### 6.2 向后兼容映射
+
+```js
+const safeGoTab = (id, opts) => {
+  const mapped = ({
+    tasks: 'workspace', bots: 'team', rooms: 'team',
+    teams: 'team', artifacts: 'workspace',
+  })[id] ?? id
+  goTab(mapped, opts)
+}
+```
+
+### 6.3 locate 传参
+
+只有「团队 → 房间」子视图接收 `locate`（跨页签定位）：
+
+```js
+locate: current.id === 'team' && activeView.id === 'rooms' ? locate : undefined
+```
+
+---
+
+## 7. 前端视觉规范
+
+### 7.1 阶段徽章样式
+
+```css
+.csb-stage                /* 基础：19px 高，圆角 5px，10.5px 字 */
+.csb-stage-person         /* 需人动手：警告色 + 9% 底色 + 加粗 */
+.csb-stage-working        /* 机器推进：常规色 */
+.csb-stage-idle           /* 空闲：弱化色，opacity .8 */
+```
+
+使用位置：
+- 任务卡片（看板视图）：阶段徽章 + 「需你处理」标记
+- 任务详情抽屉：执行阶段行（徽章 + 原因 title）
+
+### 7.2 移动端适配
+
+| 元素 | 适配 |
+|---|---|
+| 页签 | `overflow-x:auto` 横向滚动 |
+| 子页签 | 横向滚动 |
+| 穿透面板 | `Drawer` 全屏抽屉（宽度 min(660px, 100%)） |
+| 任务卡片 | 响应式 flex 布局 |
+| 房间分栏 | `@media(max-width:900px)` 转纵向 |
+
+---
+
+## 8. 测试覆盖
+
+| 测试文件 | 用例数 | 覆盖 |
+|---|---|---|
+| `test/stage.test.mjs` | 30 | 阶段判定全路径、优先级、宽容性、纯函数性 |
+| `test/subscription.test.mjs` | 17 | 订阅/幂等/扇出/滚动窗口/CAS/replay |
+| `test/api.test.mjs` | 37 | 穿透面板 8 项、订阅 4 项、阶段 3 项 |
+| `test/roster.test.mjs` | 30 | prepare command 8 项 |
+| `test/client.test.mjs` | 13 | 6 页签 + 穿透入口渲染 |
+| 其余既有测试 | 909 | 全部回归 |
+| **合计** | **1036** | **0 失败** |
+
+---
+
+## 9. 实现清单
+
+| 文件 | 改动类型 | 行数 |
+|---|---|---|
+| `src/stage.js` | 新增 | +302 |
+| `src/subscription.js` | 新增 | +497 |
+| `src/roster.js` | 修改 | +44 |
+| `src/api.js` | 修改 | +304 |
+| `src/client.js` | 修改 | +245 |
+| `src/tools.js` | 修改 | +97 |
+| `src/index.js` | 修改 | +10 |
+| `test/stage.test.mjs` | 新增 | +330 |
+| `test/subscription.test.mjs` | 新增 | +226 |
+| `test/api.test.mjs` | 修改 | +150 |
+| `test/roster.test.mjs` | 修改 | +75 |
+
+---
+
+*详细设计文档完。*
+---
+
+## 改造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 / 让它归纳
+```