cs-bots 0.1.0 → 0.7.4

package/docs//346/223/215/344/275/234/346/211/213/345/206/214-v1.md

@@ -0,0 +1,509 @@
+# cs-bots 操作手册 v1
+
+> 版本：0.7.0（2026-11-06，Asia/Shanghai）
+> 适用：DSH Web（profile `web`）里的「协作平台」面板
+> 本手册只讲**怎么做**；架构与设计理由见 `docs/ARCHITECTURE.md`、`DESIGN-v2.md`、`design/CONTRACT-bots03.md`。
+
+---
+
+## 0. 三十秒上手
+
+页面左侧栏点「◈ 协作平台」，进入后顶部有 9 个页签：
+
+```
+任务   Bot   房间   成果   记忆   技能库   工作流库   数据   设置
+```
+
+| 我想… | 去哪个页签 | 关键动作 |
+|---|---|---|
+| 派活给 Bot | 任务 → 协作看板 | 输入标题回车 → 指派负责人 |
+| 看 Bot 干到哪了 | 任务 → 协作看板 | 点卡片看进度条/依赖链 |
+| 验收成果 | 成果 | 点卡片 → 回任务详情验收 |
+| 和 Bot 群聊 | 房间 | 点房间 → 左栏说话 |
+| 让 Bot 记住规矩 | 记忆 → 纪律与要求 | 新建纪律（可按房间/Bot 收窄） |
+| 看后台存了什么 | 数据 | 选文件 → 看原始行 |
+| 加一个 Bot | Bot | 新建（选目录/预设） |
+
+---
+
+## 1. 任务板（人是发包方）
+
+### 1.1 发布任务
+
+1. 打开 **任务 → 协作看板**
+2. 在顶部输入框写「要做什么」，**回车**或点「创建任务」
+3. 点「更多字段」可展开三个字段：
+   - **描述**：写清目标与验收标准（推荐格式见 §1.6）
+   - **优先级**：数字，越大越靠前；≥8 视为「紧急」
+   - **负责人**：从 Bot 下拉里选（不选 = 待领取）
+4. 创建成功任务出现在列表，状态「待办」
+
+> 默认只显示「需要你管的」任务（卡住 / 高优先 / 逾期 / 待验收 / 你建的）。
+> 想看全部（含 AI 自己派发的），点 **「看全部任务」**。
+
+### 1.2 两种视图
+
+| 视图 | 用途 | 怎么切 |
+|---|---|---|
+| 列表 | 快速扫状态，适合少量任务 | 顶部「列表」 |
+| 看板（Kanban） | 看流转，4 列 = 待办 / 进行中 / 已完成 / 已终止 | 顶部「看板」 |
+
+看板卡片上直接显示：标题、负责人、进度条、优先级、前置任务数。
+
+### 1.3 筛选
+
+- **状态下拉**：全部 / 待办 / 进行中 / 已完成 / 已终止
+- **负责人下拉**：只看某个 Bot 的活
+- **关键词框**：本地匹配标题与描述（大小写不敏感）
+- 「只看需要我管的 / 看全部任务」是一级开关，和其它筛选叠加
+
+### 1.4 打开任务详情（抽屉）
+
+点任意任务卡片，右侧滑出详情。里面能看到：
+
+| 区块 | 内容 |
+|---|---|
+| 基本信息 | 谁建的、来源（人建 / 智能体派发）、优先级、截止、状态、任务编号 |
+| 谁在做 / 进度 | 负责人 + **进度条**（可编辑，见下） |
+| 在哪做 | `writeScopes`（允许改动的文件前缀） |
+| 完成前必须先 | `blockedBy` 前置任务 |
+| 交付物 | `artifacts`（产出物证据清单） |
+| 验收结果 | 通过 / 打回 + 验收人 |
+| 依赖链 | 上游（前置递归）+ 下游（谁在等它），来自 `GET /tasks/graph` |
+| 可以做什么 | 领取 / 重开 / 终止 |
+| 高级：租约 | 当前占用到期时间 + 延长 5 分钟 |
+| 审计流 | 最近 40 条操作事件（动作 / 版本 / 操作者 / 时间） |
+
+### 1.5 改任务进度
+
+详情里「进度」行右侧有数字输入：
+
+1. 填 0–100 的整数
+2. 点「保存进度」→ 走 `POST /tasks/update`，`action:'edit'`，带 `expectedRev`
+3. 冲突（别人刚改过）会提示「刷新一下再操作」，不会静默覆盖
+
+### 1.6 写一条好任务（目标 + 标准）
+
+```
+目标：实现登录接口 POST /auth/login
+标准：
+- 用户名/密码错误返回 401 + {"error":"invalid_credentials"}
+- 成功返回 200 + {"token":"..."}，token 有效期 24h
+- 单测覆盖成功/失败/限流三条路径
+边界：只改 src/auth/**，别动数据库 schema
+```
+
+把这段贴进「描述」，验收时对着「标准」逐条查 —— 这就是 `artifacts` + `acceptance` 的用法。
+
+### 1.7 领取 / 终止 / 重开
+
+| 动作 | 按钮 | 效果 | 可撤销 |
+|---|---|---|---|
+| 领取 | 「我来管（领取）」 | status → in_progress，占 5 分钟租约 | 可 release |
+| 终止 | 「终止任务」→ 填原因 → 确认 | status → blocked，原因进 `blockedReason` | 可「重新打开」 |
+| 重开 | 「重新打开」 | blocked → pending | — |
+| 延长 | 「延长 5 分钟」 | 租约续期（长任务要隔一会儿点） | — |
+
+> 租约到期后任务会被自动回收回 pending（`POST /tasks/expire-leases`），
+> 防止 Bot 崩溃后任务永久卡在一个死掉的负责人身上。
+
+### 1.8 指派与唤醒
+
+- 在任务详情/任务页把负责人设成某个 Bot 的 `sessionId`
+- 后端 `POST /tasks/assign` 会做两件事：把 `byId` 作为 claim 的 owner + `dispatcher.notify` 定向唤醒
+- 唤醒用 `dedupKey = task-assigned:<taskId>:<rev>`，**同任务同版本只唤一次**，不会唤醒风暴
+
+---
+
+### 1.9 从 Bot 页派活（一步到位）
+
+打开 **Bot** 页签，卡片上三个按钮：
+
+| 按钮 | 做什么 | 背后发生的事 |
+|---|---|---|
+| **派任务** | 弹窗填「要做什么 + 目标/标准 + 优先级」 | `POST /tasks` 建任务 → **立即** `POST /tasks/assign`（ownerId = 该 Bot 的 sessionId）→ 定向唤醒 |
+| **发消息** | 弹窗直接跟这个 Bot 说话 | `POST /bots/message`（`reason=room-message`）→ 唤醒它新开一个回合 |
+| 去对话 | 跳到它的会话页面 | `uiWorkspace.openSession` |
+
+派活结果**必然显示**：`sent`（已唤醒）/ `skipped`（去重命中）/ `failed（原因：…）`。
+如果任务是建好了但派活失败，会明确显示「任务 t-x 已建，但派活失败：<原因>」——不会假装成功。
+
+> 从 **任务** 页创建时填了「负责人」也一样：创建成功即自动 `assign` 并唤醒，不必再手动领取。
+
+### 1.10 补充说明与「目标锚」（长任务不失真）
+
+长任务最常见的失败不是「做错」，而是**做着做着目标漂了**。本平台的解法是把目标**锚定**：
+
+- 任务创建时填的 **标题 + 目标/标准** 就是**目标锚原文**，之后**永不覆盖**；
+- 后续所有口头补充都进 **补充说明**（append-only），是「追加项」，不是「改写项」；
+- 每次唤醒 Bot，投递的文案都**完整带上目标原文 + 全部补充说明**，而不是只说一句「有新消息」。
+
+**怎么用**：任务详情 → 「补充说明」框 → 写一段 → 「发送给执行者」。
+
+- 任务有负责人 → `POST /tasks/note`，落 `task-notes.jsonl`，并唤醒执行者（文案 = 全量锚定 + 新增这条）
+- 任务没派活 → 按钮变成「保存补充（未派活，暂不唤醒）」，只存档（`wake:false`）
+- 补充历史在下方按时间列出，**重复点不会覆盖前一条**（append-only）
+
+任务详情还能看到「目标锚（只读）」区块：标题大字 + 目标原文 + 边界 `writeScopes` + 前置 `blockedBy`，
+顶部小字写着「目标来自创建时原文 · 补充说明只追加不覆盖」。
+
+**复制派发文案**：详情里「复制派发文案」会调 `GET /tasks/brief` 复制整段锚定文案，
+你可以粘到任何会话/群里，让不在平台上的执行者也拿到同一份目标原文。
+
+### 1.10.1 任务可以改：纠错 / 优化 / 转长任务 / 换负责人
+
+**已完成不是终点。** 任务详情里，「可以做什么」之后有「变更」区（已完成任务默认展开）：
+
+| 我要… | 点哪个 | 发生什么 |
+|---|---|---|
+| 交付有错，重新做 | **重开（纠错/继续做）** | 状态回到待办；**上一轮交付物先存档**（重开不会丢证据） |
+| 已有结果但想优化 | **派生优化单** | 原任务保持已完成；新建一张 `【优化】/【修复】/【变更】` 开头的新任务，幂等（同理由连点不重复建） |
+| 这事比想象的大 | **转为长任务** | 标记为长任务 + 阶段清单；之后**每次唤醒都会带上阶段清单**，按序推进不跳步 |
+| 派错人了 | 「执行者」旁的 **换负责人** | 释放原租约 → 换人 → 自动唤醒新负责人 |
+
+**三条使用规则**：
+
+1. **变更说明必填** —— 没有理由的变更不许进历史（这是你事后复盘唯一的依据）。
+2. 变更历史在区块下方，逐条 `[时间] 动作 — 说明（by）`。
+3. 换负责人时若任务已完成 → 会被拦下并提示「先重开或派生优化单」——
+   因为「换人继续做」本质上就是「重开」，不该偷偷改掉已验收的完成状态。
+
+**长任务的阶段清单示例**（转长任务时填 `phases`，不填给默认三阶段）：
+
+```
+阶段（长任务，按序推进，不得跳步）：
+1. 范围与验收标准确认
+2. 执行与自测
+3. 交付与复盘
+```
+
+这段会自动进「目标锚」文案，所以 Bot 每次被唤醒都能看到自己在哪一阶段。
+
+### 1.11 跳转到对话 / 从对话建任务
+
+| 从哪里 | 动作 | 效果 |
+|---|---|---|
+| 任务详情 | **去对话** | ownerId 对应的 Bot → `openSession` 直接跳到它的会话；不是本平台 Bot 时提示「无法跳转」并给复制 ID |
+| 房间消息 | **⇢ 建任务**（hover 出现） | 预填标题（正文首行截 80）+ 描述（全文 + 出处），带幂等键 `room:<roomId>:<seq>`，**同一条消息重复点不会建出第二个任务** |
+
+这样就形成闭环：**讨论（房间）→ 承诺（任务）→ 执行（Bot 会话）→ 证据（成果）→ 验收（任务详情）**。
+
+## 2. 成果（产出物证据）
+
+### 2.1 成果从哪来
+
+任务完成时必须带 `artifacts`（**非空**，后端强制校验）：
+
+```json
+POST /cs-bots/api/tasks/update
+{
+  "id": "t-12", "expectedRev": 4, "action": "complete",
+  "byId": "bot-a",
+  "artifacts": ["src/auth/login.js", "test/auth/login.test.mjs",
+                {"file": "CHANGELOG.md", "sha": "a1b2c3d"}]
+}
+```
+
+`artifacts` 支持字符串或对象（对象在页面上显示为单行 JSON）。
+
+### 2.2 看成果
+
+**成果** 页签：
+
+- 顶部：关键词（搜任务标题 + 产出物路径）、负责人下拉、状态下拉
+- 列表卡片：任务标题、状态徽标、负责人、是否已验收、任务编号、完成时间、产出物标签
+- 点卡片 → 打开该任务详情（可继续验收）
+
+### 2.3 验收
+
+1. 任务详情里看「交付物」是否对得上「标准」
+2. 走 `POST /tasks/accept`，`result: "pass" | "reject"`
+3. `pass` 要求任务已是 `completed` 且 `artifacts` 非空；`reject` 会把产出物作废（在事件流 `before` 里留档）
+
+---
+
+## 3. 房间（群聊）
+
+### 3.1 建房间
+
+1. 打开 **房间**
+2. 输入房间名 → 「创建房间」
+3. 创建后自动进入该房间
+
+### 3.2 拉 Bot 进来
+
+右侧「成员管理」勾选 Bot：
+
+- 勾上 → `POST /rooms/join`
+- 取消 → `POST /rooms/leave`
+- 角色：管理员 / 成员 / 旁听（`POST /rooms/member-role`）
+- 踢人：`POST /rooms/kick`
+
+### 3.3 聊天
+
+- 输入框说话，**回车**发送
+- 自己发的消息靠右（浅底），Bot 的靠左
+- 每条显示：发送者、`#seq`、时间戳
+- 正文里 `@某个Bot` 会高亮（前端渲染，不额外请求）
+- 长消息（>300 字）显示前 300 字 + 「看全文」按钮（Modal 展示）
+- **历史分页**：默认显示最近 50 条，上方「加载更早的 50 条」按钮每次 +50
+
+### 3.4 自动唤醒
+
+发言后，接口会自动唤醒房间内**除自己以外**的成员：
+
+- 受房间设置 `allowBotAutoPost` 控制（关掉就不唤醒）
+- `dedupKey = room-msg:<messageId>:<target>`，天然幂等
+- 唤醒失败不影响消息已落盘（只降级不抛）
+
+### 3.5 房间设置
+
+右侧「编辑设置」可改：
+
+| 项 | 说明 |
+|---|---|
+| 名称 / 用途 / 公告 | 基本信息 |
+| 模式 | 管理员模式（只有 adminId 能发）/ 自由发言 |
+| 允许 Bot 自主发言 | 发言后是否自动唤醒 |
+| 单轮最多几个 Bot 发言 | `maxBotsPerRound`，1–20 |
+| 允许 relay 中继 | 是否允许 Bot 之间接力 |
+
+归档 / 恢复 / 删除：房间卡片右侧按钮。删除需要二次确认（有消息时必须 `force`）。
+
+---
+
+### 3.6 和「任务板」的关系
+
+房间是**讨论**，任务板是**承诺**（区别见 §7）。两者之间的桥：
+
+- 消息气泡 hover → **⇢ 建任务**：把一条讨论变成一张工单（带幂等键，重复点不会重复建）
+- 任务详情 → **去对话**：从工单跳回这个 Bot 的会话继续聊
+- 任务详情 → **补充说明**：把聊出来的新约束追加进任务，并唤醒执行者
+
+## 4. 数据（只读浏览）
+
+### 4.1 为什么没有 SQLite
+
+cs-bots 的硬约束是**零第三方依赖**（新机器只装本插件就能跑）。
+存储方案是：
+
+```
+~/.dsh/cs-bots/
+├── board.jsonl          任务事件流（真相源，append-only）
+├── board.snap.json      任务快照（加速启动恢复）
+├── roster.jsonl          Bot 注册表事件流
+├── memory.jsonl          记忆事件流
+├── rooms/<roomId>/log.jsonl       房间消息日志
+├── rooms/<roomId>/events.jsonl    房间事件流
+└── settings.json         设置
+```
+
+**事件流是真相源，快照只是缓存**：快照坏了也能从 jsonl 完整重建。
+
+### 4.2 怎么用「数据」页
+
+1. 打开 **数据**
+2. 左列是 `stateDir` 直属的 `.jsonl` / `.json`，显示字节数、行数、修改时间
+3. 点一个文件 → 右侧按 50 行/页显示原始行
+4. 坏 JSON 行仍显示原文，标红「JSON 解析失败」（不整页崩）
+5. 子目录：顶部输入 `rooms` / `scratch` 可切子目录
+
+### 4.3 安全边界
+
+- 文件名 / 子目录走后端白名单：`^[A-Za-z0-9._-]+$`，且拒绝 `..`
+- 非法输入 → **400**，绝不读任意路径
+- **只读**：这一页没有任何写接口；写入一律走域服务 + CAS
+
+### 4.4 备份与恢复
+
+```bash
+# 备份（推荐每天一次，或大改前）
+cp -r ~/.dsh/cs-bots ~/.dsh/cs-bots.bak-$(date +%Y%m%d-%H%M)
+
+# 恢复（先停 DSH，再替换目录）
+# 程序内也有 API：store.backupState / store.restoreState（需 confirm:true）
+```
+
+---
+
+## 5. Bot（注册表与档案）
+
+### 5.1 新建 Bot
+
+**Bot → 新建**，必须填：
+
+- **名称**：唯一，大小写不敏感
+- **工作目录**：绝对路径，且**不得在 `~/.dsh` 内**（写入边界）
+- 预设 / 模型 / 权限（read-only / workspace-write / full）
+
+> 两个 Bot 可以共享同一目录，但会互相覆盖文件 —— 页面会提示「同目录共享」。
+
+### 5.2 管理动作
+
+| 动作 | 说明 | 可逆 |
+|---|---|---|
+| 改名 | 旧名立即释放 | 可 |
+| 退役 | 终态；名字与目录可被复用 | 需重建 |
+| 换目录 | `setCwd` | 可 |
+| 认领/释放 | 租约（防并发） | 可 |
+
+### 5.3 Bot 档案（五分区）
+
+点 Bot 卡片打开档案抽屉：
+
+| 分区 | 写入落点 |
+|---|---|
+| 身份（岗位名 / 人格 / 红线） | `AGENTS.md` 受管区块 |
+| 经验 | `AGENTS.md` |
+| 技能 | `bot.profile.skills` + skill 文件 |
+| 预制记忆 | 记忆服务（带 `botId`），建 Bot 时自动同步 |
+| 纪律 | `disciplineIds` 关联 |
+
+---
+
+## 6. 记忆 / 纪律 / 待办 / 便签 / 提示词 / 技能库 / 工作流库
+
+| 页签 | 一句话 | 关键点 |
+|---|---|---|
+| 记忆 → 事实与偏好 | 分层记忆 L0–L5 | L0 人格只有人能动；支持全文搜索、归档区、改/删 |
+| 记忆 → 纪律与要求 | 分级纪律 | 层级 global→workspace→room→bot，越具体越优先；可设 token 预算裁剪 |
+| 记忆 → 提示词 | 指令模板 | 支持分类、启用/停用、变量占位 |
+| 任务 → 我的待办 | 个人备忘 | 轨道 life/work/project/daily，四象限 |
+| 任务 → 便签 | 随手记 | 按 scope 隔离，不参与自动整理 |
+| 技能库 | 技能 CRUD + 导入 | 支持从 `.agents/skills` 扫描、导出 markdown |
+| 工作流库 | 步骤模板 | 任务详情可引用 |
+| 设置 | 平台参数 | 存 `settings.json`，**改完要重启 DSH** |
+
+---
+
+## 7. 人 → Bot 派活 vs Bot ↔ Bot 沟通
+
+这是本平台最容易被混淆的一点，对照表：
+
+| 维度 | 人 → Bot 派任务（任务板） | Bot ↔ Bot 沟通（房间） |
+|---|---|---|
+| **载体** | Task（`board` 域） | Message（`room` 域） |
+| **本质** | 正式工单 | 非正式对话 |
+| **有状态吗** | 有：pending / in_progress / completed / blocked / deleted | 无：纯消息流 |
+| **有版本吗** | 有：`rev` + CAS，冲突必抛 | 无（seq 单调递增） |
+| **要证据吗** | 要：complete 必须带 `artifacts` | 不要 |
+| **要验收吗** | 要：accept pass/reject | 不要 |
+| **有租约吗** | 有：防负责人崩溃后永久占用 | 无 |
+| **有依赖吗** | 有：`blockedBy` 构成 DAG | 无 |
+| **谁会被通知** | 被指派者（dedupKey 幂等） | 房间内除发送者外的全部成员 |
+| **典型用途** | 「把这个接口做了，交单测和 CHANGELOG」 | 「这个接口的参数应该用 snake_case 还是 camelCase？」 |
+
+**两者怎么衔接**
+
+1. 房间聊出来的结论 → 人去任务板建任务（对话 → 工单）
+2. 任务完成后 → Bot 把结果发到房间（工单 → 对话）
+3. 任务「完成前必须先」可以填另一个任务 → 形成主任务流程（依赖图里能看见）
+
+**一句话**：任务是**承诺**，房间是**讨论**。承诺要有证据和验收，讨论不需要。
+
+---
+
+## 8. 人的查看与管理能力总表
+
+| 我要做什么 | 路径 | 端点 |
+|---|---|---|
+| 发任务 | 任务 → 输入框 | `POST /tasks` |
+| 改任务字段 | 任务详情 → 进度/编辑 | `POST /tasks/update` (`action:'edit'`) |
+| 指派 | 任务 → 负责人 | `POST /tasks/assign` |
+| 终止 | 任务详情 → 终止任务 | `POST /tasks/abort` |
+| 验收 | 任务详情 → 验收 | `POST /tasks/accept` |
+| 看依赖全图 | 任务详情 → 依赖链 | `GET /tasks/graph?id=` |
+| 看全部依赖 | — | `GET /tasks/graph` |
+| 看成果 | 成果页签 | `GET /artifacts` |
+| 看后台数据 | 数据页签 | `GET /data/files`、`GET /data/rows` |
+| 建房/改房/归档/删房 | 房间 | `POST /rooms`、`/rooms/update`、`/rooms/archive`、`/rooms/remove` |
+| 拉人/踢人/改角色 | 房间 → 成员管理 | `/rooms/join`、`/rooms/kick`、`/rooms/member-role` |
+| 发言 | 房间 → 输入框 | `POST /rooms/post` |
+| 看历史 | 房间 → 上滑/加载更早 | `GET /rooms/messages?roomId=&withBody=1` |
+| 看长正文 | 消息「看全文」 | `GET /rooms/body?roomId=&messageId=` |
+| 建/改/退役 Bot | Bot 页签 | `POST /roster`、`PATCH /roster` |
+| 改档案 | Bot 卡片 → 档案 | `PATCH /roster/profile` |
+| 记忆 CRUD | 记忆页签 | `/memory`、`/memory/detail`、`/memory/update`、`/memory/remove` |
+| 纪律 CRUD | 记忆 → 纪律 | `/discipline/*` |
+| **从 Bot 页派活** | Bot 卡片 → **派任务** | `POST /tasks` + `POST /tasks/assign` |
+| **跟 Bot 说话** | Bot 卡片 → **发消息** | `POST /bots/message` |
+| **追加补充说明** | 任务详情 → 补充说明 → 发送 | `POST /tasks/note` |
+| **看补充历史** | 任务详情 → 补充历史 | `GET /tasks/notes?id=` |
+| **看/复制目标锚文案** | 任务详情 → 复制派发文案 | `GET /tasks/brief?id=` |
+| **跳到 Bot 会话** | 任务详情 / Bot 卡片 → 去对话 | 宿主 `uiWorkspace.openSession` |
+| **房间消息转任务** | 房间消息 hover → ⇢ 建任务 | `POST /tasks`（`sourceSeq=room:<id>:<seq>`） |
+| **启动某个 Bot 会话** | Bot 卡片 → 启动会话；或唤醒失败提示里 | `POST /bots/revive` |
+| **一键启动全部 Bot 会话** | Bot 页头 → 全部启动 | `POST /bots/revive`（`{all:true}`） |
+| **重试唤醒** | 唤醒失败提示 → 重试唤醒 | `POST /tasks/wake`（`force` 缺省换新键，不会被幂等吞掉） |
+| **重开已完成任务（纠错）** | 任务详情 → 变更 → 重开 | `POST /tasks/evolve`（`mode:'reopen'`） |
+| **派生优化单** | 任务详情 → 变更 → 派生优化单 | `POST /tasks/evolve`（`mode:'followup'`） |
+| **转长任务（带阶段）** | 任务详情 → 变更 → 转为长任务 | `POST /tasks/evolve`（`mode:'longrun'`） |
+| **看变更历史 / 上一轮交付物** | 任务详情 → 变更区下方 | `GET /tasks/changes?id=` |
+| **换负责人** | 任务详情 → 执行者旁「换负责人」 | `POST /tasks/reassign` |
+| 系统体检 | 设置 → 底部 | `GET /status` |
+
+---
+
+## 9. 故障排查
+
+| 现象 | 原因 | 处置 |
+|---|---|---|
+| 页面有页签但全空 | 域服务未装配（状态目录不可写） | 看 `GET /status` 的 `services.*.available`；检查 `~/.dsh/cs-bots` 权限 |
+| 改了源码页面没变 | client bundle 是**启动时快照** | 必须重启 DSH Web（见 §10） |
+| 「进度必须 0-100」 | 输入越界 | 填整数 |
+| 操作报「刷新一下再操作」 | CAS：别人刚改过 | 点「刷新」重试 |
+| 操作报「租约被占用」 | 另一个 Bot 正在做 | 等它完成或租约过期 |
+| 操作报「前置任务没做完」 | `blockedBy` 未完成 | 打开详情看前置任务 |
+| 数据页显示「目录不可读」 | 目录权限 | `ls -la ~/.dsh/cs-bots` |
+| 成果页为空 | 没有任务带 `artifacts` | 任务完成时要传 `artifacts` |
+| **派活后提示「该 Bot 会话当时没在运行」** | 重启 dsh-web 后宿主没把旧会话加载进 live 注册表（懒加载），投递必然 `agent-not-live` | 点提示里的「**启动该 Bot 会话**」→ 再点「**重试唤醒**」；或去 Bot 页点「**全部启动**」一次性拉起所有会话。0.6.1 起派活/发言/补充会**自动**先复活会话，正常情况下不会再看到这条 |
+| 重启后想批量恢复 | 同上 | Bot 页页头「**全部启动**」→ 显示「复活 N 个 / 已在线 M 个 / 失败 K 个（原因）」 |
+| 「去对话」说负责人不是本平台的 Bot | 旧版只看 `ownerId`（租约持有者，可能是 `ui`），没看 `assignee` | 0.7.0 已修：按 `assignee → ownerId` 解析并过滤 `ui` 等伪身份；若仍提示，说明该任务确实没派给注册 Bot，去 Bot 页复制会话 ID 重派 |
+| 想改已完成的任务 | — | 任务详情 → 变更区：重开（纠错）/ 派生优化单（优化）/ 转长任务 |
+| 任务莫名回到「待办」 | 租约到期被自动回收（负责人从未确认，通常因为会话没起来） | 先「全部启动」，再重新派活 |
+
+---
+
+## 10. 升级与重启（重要）
+
+cs-bots 的 `web/profile` 里装的是 **tarball**（不是 link），所以：
+
+```bash
+# 1) 在源码目录打包
+cd /home/ubuntu/output2026/butlers/dev/cs-bots
+npm pack                     # 产出 cs-bots-0.5.0.tgz
+
+# 2) 更新 profile 依赖指向新 tarball
+#    编辑 ~/.dsh/profiles/web/package.json 里的 "cs-bots": "file:.../cs-bots-0.5.0.tgz"
+
+# 3) 安装 + 自检
+bash install.sh --profile web
+
+# 4) 重启（页面才会拿到新 client bundle）
+bash /home/ubuntu/output2026/butlers/dev/restart-by-kill.sh
+# 或：kill 主进程，systemd Restart=always 自动拉起
+
+# 5) 自检
+curl -s http://127.0.0.1:3080/cs-bots/api/status | head -c 300
+```
+
+> **不重启 = 看不到改动**。2026-11-05 曾因「编辑到一半重启」导致整批 client bundle 加载失败，
+> 所以：**改代码和重启不要并行**，改完 `node --check` 通过再重启。
+
+---
+
+## 11. 测试与验收
+
+```bash
+cd /home/ubuntu/output2026/butlers/dev/cs-bots
+bash test/run-all.sh     # 零依赖 CI + 全部单测，只认这一个退出码
+node --check src/client.js src/api.js
+```
+
+当前基线：**909 个测试全通过（exit 0）**。
+覆盖面（按改造批次）：
+- 改造03（13 个）：`/artifacts`、`/data/files`、`/data/rows`、`/tasks/graph` —— 含目录穿越拒绝、坏 JSON 不崩、依赖闭包正确性
+- 改造04（20+25 个）：`/tasks/brief`、`/tasks/note`、`/tasks/notes`、`/bots/message` + 前端锚定面板/弹窗/幂等键
+  + **`/tasks/source` 来源跳转**（room/todo/evolve/none/unparsed 五类 kind、跨页签定位到消息）
+- 改造05（16+11 个）：`ensureLive` 三态、投递前自动复活、`/bots/revive`（单+批量）、`/tasks/wake`（force 换键）
+- 改造06（15+16+8 个）：`/tasks/evolve` 三模式 + 快照、`/tasks/reassign`、`/tasks/changes`、负责人解析回归

package/docs//350/277/201/347/247/273/346/226/271/346/241/210-v1.md

@@ -0,0 +1,64 @@
+# cs-bots 存量任务迁移方案 v1
+
+> 日期：2026-11-05（Asia/Shanghai）
+> 适用：把老会话/旧 Bot/旧任务板的数据迁移到 cs-bots 0.4.0+。
+
+## 1. 数据源识别
+
+| 老数据 | 位置 | 形态 |
+|---|---|---|
+| 旧任务板（agent-team） | `~/.dsh/storages/agent-team/boards/*.json` | JSON，字段 subject/status/owner/rev |
+| 旧 Bot 注册 | `~/.dsh/storages/agent-team/members/*.json` | JSON |
+| 旧房间 | `~/.dsh/storages/agent-team/rooms/*.json` | JSON |
+| 旧记忆 | `~/.dsh/memories/projects/<cwd>/KEY.md` | Markdown 条目 |
+| 旧便签 | `~/.dsh/storages/scratch/*.md` | Markdown |
+
+cs-bots 新数据：`~/.dsh/storages/cs-bots/`（boards/rooms/roster/tasks），schema 见 `src/board.js` / `src/room.js` / `src/roster.js`。
+
+## 2. 映射规则
+
+### 任务（board）
+- `subject` → `subject`（必填，空则跳过并记日志）
+- `status` 映射：`todo`→`pending`，`doing`→`in_progress`，`done`→`completed`，`blocked`→`blocked`
+- `owner` → `assignee`（若 roster 中存在同名 Bot，否则置 null 并记 orphan）
+- `priority` 缺省 0；`labels` 缺省 []
+- `rev` 不迁移，新板从 1 起新 rev
+- 旧任务 id 加前缀 `legacy-` 避免冲突
+
+### Bot（roster）
+- `name` → `name`（重名加 `-legacy-N`）
+- `cwd` 必须是绝对路径且不在 DSH_HOME 内；旧 cwd 无效则跳过并报错
+- `label/instructions` 原样复制
+
+### 房间
+- `name`、`members`（按 session id 映射，找不到的成员丢弃并记日志）
+- 旧消息**不迁移**（schema 差异大，仅保留房间壳）
+
+### 记忆
+- 不自动迁移条目；提供 `cs-bots memory import --from <old KEY.md>` 命令，按条目追加到新 KEY.md，带 `legacy:` 标签
+
+## 3. 幂等
+
+- 迁移脚本写入 `~/.dsh/storages/cs-bots/migration-log.jsonl`，记录 `{sourceId, targetId, ts, status}`。
+- 重跑时：若 sourceId 已在 log 中且 targetId 仍存在 → 跳过；targetId 不存在 → 重新迁移。
+- 提供 `--dry-run` 只输出将要迁移的条目，不写入。
+
+## 4. 回滚
+
+- 迁移前自动备份整个 `~/.dsh/storages/cs-bots/` 到 `~/.dsh/storages/cs-bots.bak-<ts>/`。
+- 回滚命令：`cs-bots migrate rollback --ts <ts>`，恢复备份目录（先校验备份完整性）。
+- 旧数据**永不删除**，迁移只读。
+
+## 5. 验收
+
+- 迁移后 `task list` 数量 = 老板数量（允许 orphan 被跳过，但必须在 log 中记录原因）
+- 每个迁移任务 rev=1，status 映射正确
+- 重跑迁移 log 显示全部 skip，无重复条目
+- `--dry-run` 不改变任何文件（校验 mtime 不变）
+- 回滚后 cs-bots 数据恢复到迁移前状态（diff 无差异）
+
+## 6. 风险
+
+- 旧 cwd 失效（单位/家里双机）→ 迁移时 Bot 跳过，需人工修正
+- 旧消息不迁移 → 用户需知悉
+- 旧 rev 丢失 → CAS 语义从 1 重新开始，不影响新操作

package/docs//351/225/277/346/234/237/350/256/260/345/277/206/346/226/271/346/241/210-v1.md

@@ -0,0 +1,85 @@
+# cs-bots 长期记忆方案 v1（Bot 新建任务 / 跨会话交接 / 上下文防膨胀）
+
+> 日期：2026-11-05（Asia/Shanghai）
+> 问题：Bot 在单一对话里反复推进任务，上下文越来越长，最终超限，任务流畅性被打断。
+> 目标：让「任务」脱离「单一对话」，落到分层记忆 + 任务笔记，任何 Bot/会话都能接手，上下文按需召回而非全量常驻。
+
+## 1. 根因定位
+
+| 症状 | 根因 | 证据 |
+|---|---|---|
+| 单对话上下文超长 | 任务的全部讨论都留在同一条会话消息流里，每轮全量重放 | client.js 消息流无摘要 |
+| 换会话就忘 | 任务状态只在 board.jsonl 里，讨论细节在旧会话，无结构化抽取 | src/board.js 只有事件流 |
+| L4 任务笔记无人用 | L4 设计上「按需 recall」，但没有任务 id → L4 的绑定机制 | src/memory.js 无 taskId 字段 |
+| 上下文注入无预算 | `contextFor` 有 tokenBudget，但任务笔记没进 L4 召回路径 | memory.js:2144 |
+
+## 2. 方案：任务笔记（L4 task note）绑定 board task
+
+### 2.1 数据模型
+- 新增 `src/tasknote.js`（或扩展 memory.js 加 `addTaskNote`）：
+  - `taskId`：关联 board 任务 id
+  - `layer: 'L4'`
+  - `content`：本轮/本步的决策、结论、下一步
+  - `rev`：CAS 版本（防并发覆盖）
+  - `cwd`：任务工作目录（L4 本就按 cwd 隔离）
+  - `phase`：`plan | doing | block | done`
+  - `tags`：`['task:<id>']` 便于检索
+
+### 2.2 写入时机（Bot 侧纪律）
+1. 每次 claim 任务后，写一条 `phase=plan` 笔记：目标 + 计划步骤
+2. 每完成一个子步骤，写一条 `phase=doing` 笔记：结果 + 剩余
+3. 遇到阻塞，写 `phase=block` 笔记：阻塞原因 + 需要谁/什么
+4. 完成前写 `phase=done` 笔记：验收结果 + 可复用经验
+
+### 2.3 召回路径（避免常驻膨胀）
+- L4 **不进入 `contextFor` 常驻注入**（现有设计，保持）。
+- 提供 `bot_memory_search(query, layers:['L4'], cwd)` 按需召回。
+- 提供新的 `bot_task_notes(taskId)` 工具：按 taskId 拉取该任务的全部 L4 笔记（倒序，限 20 条）。
+- 接手任务时：先 `bot_task_get` 看任务 → 再 `bot_task_notes(taskId)` 看历史笔记 → 再开工。
+
+### 2.4 上下文预算纪律
+- 每个 Bot 会话启动时，只注入 `contextFor(layers:['L0','L1','L2','L3'], cwd, tokenBudget: <window/4>)`。
+- 任务细节不进常驻；需要时用 search/notes 按需取。
+- 单任务笔记上限：每条 ≤ 600 码点（memory.add 自动切分）；单任务笔记总数上限 50，超出按 `phase=done` 优先归档。
+
+## 3. 跨会话交接流程（lead → worker → reviewer）
+
+```
+1. lead 创建任务（bot_task_create）
+2. lead 写 L4 plan 笔记（bot_memory_add layer=L4, tags=['task:<id>'], content=计划）
+3. lead claim + wake worker（bot_wake reason=task-assigned, taskId）
+4. worker 收到 → bot_task_notes(taskId) 读计划 → 开工
+5. worker 每步写 L4 doing 笔记
+6. worker complete（bot_task_update action=complete, artifacts=[...]）
+7. reviewer 读 artifacts + L4 done 笔记 → 验收
+8. 不通过 → bot_task_update reopen + 写 L4 block 笔记
+```
+
+## 4. 防止「单一对话上下文超长」的三条硬规则
+
+1. **任务不落地不接新活**：claim 前必须写 plan 笔记；没有 plan 笔记的任务视为未就绪。
+2. **会话不背任务史**：每轮结束前，把本轮关键结论写 L4 笔记；下轮从笔记 + board 恢复，不依赖旧消息。
+3. **长会话自动降级**：当单会话消息数 > N（建议 40 条）或 token 估算 > 窗口 60%，提示 lead 把剩余工作拆新任务 + 新会话，旧会话只保留笔记。
+
+## 5. 落点文件
+
+| 文件 | 改动 |
+|---|---|
+| `src/memory.js` | `add()` 支持 `taskId` 字段；新增 `notesForTask(taskId)` 方法 |
+| `src/tools.js` | 新增 `bot_task_notes` 工具；`bot_memory_add` 参数加 `taskId` |
+| `src/board.js` | 无需改（task id 已存在） |
+| `docs/长期记忆方案-v1.md` | 本文件 |
+
+## 6. 验收
+
+- `memory.add({layer:'L4', taskId, content})` 返回 entry 带 taskId
+- `memory.notesForTask(taskId)` 返回该任务全部 L4 笔记，倒序
+- `bot_task_notes` 工具在无 memory 服务时返回可读失败
+- 跨会话：worker 会话能仅凭 notes + board 恢复任务，不读旧会话消息
+- 笔记总数超上限时按 done 优先归档，不静默丢弃
+
+## 7. 风险
+
+- L4 笔记写太多也会膨胀 → 用上限 + 归档控制
+- taskId 与 board 任务生命周期不一致（任务删除后笔记残留）→ notesForTask 对已删除任务仍返回笔记（保留证据），但标记 `task:deleted`
+- 零依赖纪律：不引第三方，纯用现有 memory.js 能力

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "cs-bots",
-  "version": "0.1.0",
+  "version": "0.7.4",
   "type": "module",
-  "description": "cs-bots — DSH 多智能体协作平台：跨会话任务板 / 房间群聊 / 分层记忆 / Bot 注册表（独立工作目录），零第三方运行时依赖",
+  "description": "DSH 多智能体协作平台：跨会话任务板、房间群聊、分层记忆与纪律、待办便签、可独立工作目录的 Bot 注册表（零第三方依赖）",
   "main": "src/index.js",
   "exports": {
     ".": "./src/index.js",
@@ -11,6 +11,8 @@
   },
   "files": [
     "src",
+    "docs",
+    "CHANGELOG.md",
     "cordis.patch.yml",
     "cordis.patch.agent-team.yml",
     "install.sh",