cs-bots 0.1.1 → 0.7.5

package/docs/ARCHITECTURE.md

@@ -0,0 +1,277 @@
+# cs-bots 设计架构（v0.6 历史快照 · **勿引用**）
+
+> ⚠️ **本文已过期，不要当作现状依据**（2026-11-09 标注）。
+>
+> 它是 **2026-11-06 的 v0.6 快照**，且自相矛盾：§1 写「38 个 bot_* 工具」、
+> §8 又写「28 模型工具 / 93 HTTP 端点 / 24 源文件 / 656 用例」。
+>
+> **当前实测（2026-11-09，v0.7.3）**：
+>
+> | 项 | 本文写的 | 实际 |
+> |---|---|---|
+> | 模型工具 `bot_*` | 38 / 28（自相矛盾） | **41** |
+> | HTTP 端点 | 114 / 93（自相矛盾） | **156** |
+> | 源文件 | 24 | **34**（含 `src/routing/`） |
+> | 源码行数 | 24,736 | **37,774** |
+> | 测试文件 | 30 | **59** |
+> | 测试用例 | 656 | **1,163** |
+>
+> 现状以 `docs/01-架构文档.md`、`docs/03-详细设计.md` 与实测为准。
+> 本文件保留是为了追溯 v0.6 的设计意图（分层思路本身仍然成立）。
+
+---
+
+## 0. 一句话定位
+
+**cs-bots = 装在 DSH 里的自足多智能体协作平台。** 装上它，你就有了：
+跨会话任务板、可维护的 Bot 注册表（每个 Bot 独立工作目录）、房间群聊、
+分层记忆与纪律、以及一套「AI 该怎么做事」的资产库。
+
+**它不是**记忆进化的插件替代品，也不依赖任何其他插件。
+
+---
+
+## 1. 四层结构（严格分层，禁止跨层调用）
+
+```
+┌─ L4 模型面   src/tools.js        38 个 bot_* 工具（模型能调什么）
+├─ L3 页面面   src/client.js       Web UI（10 页签 / 人话文案）
+│              src/api.js          114 个 HTTP 端点（页面数据面）
+├─ L2 领域面   board/roster/room/memory/discipline/todo/scratch/
+│              prompts/suggest/reviewer/library/dispatcher（16 个服务）
+└─ L1 内核面   kernel.js（宿主适配唯一出口） store.js（原子写/JSONL 回放）
+               registry.js  settings.js  fence.js  compat.js
+```
+
+**分层铁律**
+1. **L1 是唯一宿主耦合点**。`kernel.js` 是 `src/` 里唯一允许真实 import
+   `@deepseek-ai/*` 的文件（CI 检查 1 机械强制）。
+2. **L2 不知道 L3/L4 存在**。域服务是纯对象，不 import api/client/tools。
+3. **L3 的 api 与 client 互不 import**。api 只产出 JSON；client 只消费 JSON。
+4. **L4 不写业务逻辑**。工具层是薄适配：取服务 → 调方法 → 统一包装成
+   `{ok:true,...}` / `{ok:false, reason, ...}`。
+
+---
+
+## 2. 三条不可协商的设计原则
+
+### 原则 1 · 零第三方运行时依赖
+- `package.json` 的 `dependencies` **必须不存在或为空**；
+- 只允许 `node:*` 内置 + DSH 自带官方包（随 DSH 安装，不算第三方）；
+- 生态里的任何插件（含 `dsh-memory-evolve`）**一律不许 import**；
+- 由 `test/ci-zero-dep.sh` 5 项检查机械强制（禁依赖、禁插件 id、覆盖行必须列全 config、
+  禁 `window.prompt/confirm`）。
+
+**为什么**：新机器只装本插件就能跑。一旦 import 别的插件，安装顺序、版本、
+对方重构都会变成你的故障源。
+
+### 原则 2 · 绝不静默失败
+- 写失败**必须抛错**并从内存回滚（不允许「只改内存不落盘」）；
+- 快照写失败降级为 `warn` + 计数器，但**事件流必须已落盘**；
+- 回放跳过坏行**必须计数并 warn**，不静默丢数据；
+- 缺服务的工具返回**可读失败**（`memory-unavailable`），不抛崩、不假装成功。
+
+**依据（真实事故）**：`my-free-model` 曾因 `costOfCall` 里 `catch { return 0 }`
+把 ReferenceError 吞成 0 元，导致全站费用恒为 0 潜伏 4 天。
+
+### 原则 3 · 事件流是真相源
+```
+写入：append(jsonl) → 更新内存 → 写快照（失败只 warn）
+启动：读 jsonl 回放 → jsonl 为空才回落 snapshot → 都空 = 空态
+```
+- 快照是**派生缓存**，不是真相源；
+- 回放只接受 `rev` 递增事件（同 rev 重放幂等，容忍重复投递）；
+- **只追加，绝不改写历史**。彻底删除（`memory.purge`）也只在流里追加一条
+  `after:null` 墓碑，而不是抹掉旧行 —— 否则「谁在什么时候删了什么」永久丢失。
+
+---
+
+## 3. 领域服务清单（16 个）
+
+| # | 服务 | 文件 | 一句话 | 持久化 |
+|---|---|---|---|---|
+| 1 | `board` 任务板 | `board.js` | 跨会话任务：依赖 DAG、CAS 状态机、验收 | `board.jsonl` + `.snap.json` |
+| 2 | `roster` Bot 注册表 | `roster.js` | 持久 Bot，**独立 cwd = 写入边界**；档案/技能/记忆 | `roster.jsonl` + 档案文件 |
+| 3 | `room` 房间 | `room.js` | 群聊消息流 + `seq` 游标 + 长正文旁路 + 角色/归档 | `rooms/<id>/log.jsonl` |
+| 4 | `memory` 分层记忆 | `memory.js` | L0–L5、注入、FTS5 检索、按项目隔离、彻底删除 | `memory.jsonl` + FTS5 |
+| 5 | `dispatcher` 唤醒桥 | `dispatcher.js` | 定向唤醒 + `dedupKey` 去重 + 节流 | `wakes.jsonl` |
+| 6 | `library` 资产库 | `library.js` | 技能/工作流；来源分层、启停、导入导出、目录扫描 | `library.jsonl` |
+| 7 | `discipline` 分级纪律 | `discipline.js` | 全局/工作区/房间/Bot 四级，合并去重 + 预算裁剪 | `discipline.jsonl` |
+| 8 | `todo` 四轨待办 | `todo.js` | 生活/工作/项目/每日 + 四象限 + 智能视图 | `todo.jsonl` |
+| 9 | `scratch` 便签 | `scratch.js` | 单文件随手记，原子写 | `scratch/<scope>.md` |
+| 10 | `prompts` 提示词库 | `prompts.js` | 模板 CRUD + 注入轨（每 N 回合/次数/立即） | `prompts.jsonl` |
+| 11 | `suggest` 建议确认队列 | `suggest.js` | 模型只能提议，人点采纳才落库 | `suggestions.jsonl` |
+| 12 | `reviewer` 自审调度 | `reviewer.js` | 每 N 回合提醒模型做记忆自检（纯计数，不越权写库） | `reviewer.jsonl` |
+| 13 | `metrics` 测量 | `metrics.js` | PDCA 的 Check 数据面：周期/吞吐/驳回率等指标 | `metrics.jsonl` + `.snap.json` |
+| 14 | `verify` 验收证据 | `verify.js` | PDCA 的 Check 证据自动化：文件/命令/测试声明式检查 | `verify.jsonl` + `.snap.json` |
+| 15 | `cycle` 复盘与标准化 | `cycle.js` | PDCA 的 Act：planned→doing→checking→acting→done，不许跳步 | `cycle.jsonl` + `.snap.json` |
+| 16 | `teams` 大/小团队 | `teams.js` | Lead 聚合管理：big（人建稳定结构）/ small（智能体自建临时小组） | `teams.jsonl` + `.snap.json` |
+
+### 「建议确认制」是记忆安全的核心机制
+```
+模型想记住 X  →  suggest.propose(kind, layer, payload, reason)   [只入队]
+                        ↓
+              人 在「记忆 → 事实与偏好」看到红条，点「采纳」
+                        ↓
+              api.applySuggestion()（同步）真正写入 memory/library/discipline
+```
+- `accept` 的 `apply` 回调**必须是同步的**：返回 Promise 会在真正落库前就标记
+  accepted（假采纳），因此 `suggest.js` 显式拒绝异步 apply（`SUGGEST_ASYNC_APPLY`）。
+- apply 抛错 → 该条**保持 pending** + 记 `lastError` 落盘 + 抛给调用方，可修复后重试。
+- 这是模型修改长期记忆的**唯一合法途径**。
+
+---
+
+## 4. 页面层信息架构（10 页签，与原架构一致）
+
+**判据（新增功能先过这一关）**
+> 新能力若没有独立生命周期、不需要多人/多 Bot 共同引用、不产生可点进去的详情，
+> **不许新开页签**，只能作为既有页签内的子视图。
+
+| 主页签 | 子视图 | 一句人话 | 对应服务 |
+|---|---|---|---|
+| **任务** | 协作看板 / 我的待办 / 便签 | 要做的活 | board + todo + scratch |
+| **Bot** | — | 谁来做 | roster |
+| **房间** | — | 在哪商量 | room |
+| **记忆** | 事实与偏好 / 纪律与要求 / 提示词 | AI 该知道什么 | memory + discipline + prompts |
+| **技能库** | — | 怎么做 | library(skills) |
+| **工作流库** | — | 按什么步骤做 | library(workflows) |
+| **设置** | — | 平台怎么跑 | settings + reviewer + 诊断 |
+
+**为什么这样分**（详见 `docs/adr/ADR-001`）：
+- 页签只有两种：**协作对象**（多个、有生命周期、要点进去）与**配置资产**（配一次、多处引用）；
+- 待办/便签/纪律/提示词都不是对象，是既有对象的**视图或属性** ⇒ 只能做子视图；
+- 记忆是高频浏览的**对象**（要增删改查），所以放顶层而不是塞进设置。
+
+**三种粒度是一条漏斗**：便签（想到就记）→ 待办（决定要做）→ 任务（决定交给谁做）。
+待办条目上的「派下去」就是这个漏斗的收口（`POST /todos/promote`，幂等）。
+
+### UI 文案纪律（人类视角，不是程序员视角）
+| 禁止出现 | 改为 |
+|---|---|
+| `L0/L3`、`rev`、`cwd`、`CAS`、`jsonl` | 人格/项目记忆、第 N 版、工作目录、版本冲突、事件流 |
+| 裸错误码 | 一句人话 + 怎么修 |
+| 无引导的空列表 | 空态说明「这里是什么、下一步点什么」 |
+| `window.confirm` | 站内 `ConfirmModal`（沙箱里 confirm 被静默屏蔽） |
+| 破坏性操作无后果说明 | 明确写「会怎样、能不能恢复」 |
+
+---
+
+## 5. 权限与安全
+
+### API 认证围栏（`fence.js`）
+公网暴露的 API 必须有门。判定顺序：
+1. `Origin` 与 `Host` 不同源 → **403**（防 CSRF）；
+2. 宿主 `connection` 服务可用 → 交它做**真实会话校验**（401/403）；
+3. 宿主校验缺失 → **拒绝一切经代理请求**（fail-closed），非代理直连/测试替身放行。
+
+**为什么第 3 条不是一律拒绝**：测试用假 req/res 直接调 handler，没有 socket；
+一律拒绝会逼人关掉围栏 —— 那才是真隐患。区分「经代理」与「非经代理」是准确边界。
+
+实测：`curl -X POST /cs-bots/api/fs/mkdir`（无 cookie）→ **401**，目录未创建；
+带浏览器同款会话 cookie → **200**。
+
+### 超级管理员
+`OWNER='user'` 在 api 层代表「人」。房间归档/删除/角色/踢人、Bot 档案写入、
+记忆 L0 修改等，Bot 侧的 `byId` 永远不等于 `user`，因此天然无法自我提权。
+
+### 受保护区
+`dirbrowse.js` 有 `DIR_PROTECTED` 白名单：状态目录、`~/.ssh`、`~/.dsh` 等不可被
+`fs/mkdir|rename` 触碰（实测 P0 曾可写入 `~/.dsh/cs-bots/PWN-PROOF`，已修）。
+
+---
+
+## 6. 关键实现模式（照抄即可，勿另起炉灶）
+
+### 6.1 事件流 + 快照
+```js
+commit(id, action, by, at, before, after) {
+  appendJsonl(file, event)        // 1. 真相源，失败即抛（不允许只改内存）
+  entries.set(id, clone(after))   // 2. 内存
+  events.push(event)              // 3. 审计
+  indexUpsert(after)              // 4. 派生索引
+  writeJsonAtomic(snap, snapshot()) // 5. 快照，失败只 warn + 计数
+}
+```
+原子写：`tmp-<pid>-<rand>` → `fsync` → `rename` → `fsync(dir)`。
+
+### 6.2 CAS 并发
+所有可变对象带 `rev`；更新必须带 `expectedRev`，不匹配抛 `*_REV_CONFLICT`。
+**绝不静默覆盖**。缺 `expectedRev` 时按模块契约：必填的抛 `MISSING_EXPECTED_REV`。
+
+| 服务 | 变更入口的 `expectedRev` | 冲突错误码 |
+|---|---|---|
+| `room` | **可选**（不传即不拦，兼容 §3.2 冻结签名）：`update` / `join` / `leave` / `archiveRoom` / `unarchiveRoom` / `removeRoom` / `setMemberRole` / `kickMember` | `ROOM_REV_CONFLICT` |
+| `memory` | **必填**（`update`/`remove`）：`update` / `remove`；**可选**：`archive` / `purge` / `restore` | `MEMORY_CAS_CONFLICT` |
+| `todo` | **必填**：`updateTodo` / `removeTodo` | `TODO_REV_CONFLICT` |
+| `roster` | **必填**：`rename` / `setCwd` / `setProfile` / `addProfileMemory` / `linkSkills` / `claim` / `release` / `heartbeat`；**无 CAS**：`retire`（签名无该参数，但拒绝重复退役） | `ROSTER_REV_CONFLICT` |
+
+每次成功变更后，四个服务都调用 `store.appendAudit(stateDir, {ts,actor,action,target,before,after})`
+（软用：拿不到/写失败只 `warn` 一次 + 计入 `diagnostics.auditWriteFailures`，绝不阻断主流程）。
+
+### 6.3 错误码
+`<DOMAIN>_<KIND>`：`MEMORY_CAS_CONFLICT` / `TODO_CWD_REQUIRED` / `ROOM_NOT_EMPTY` /
+`LIB_BAD_DIR` / `SUGGEST_ASYNC_APPLY` / `REVIEW_BAD_INTERVAL` …
+错误对象同时带 `code`（机器读）与中文 `reason`（人读）。API 层把 `code` 一并返回。
+
+### 6.4 降级
+`apply()` 绝不抛：任一服务装配失败只 `warn` 并把 `services[key] = undefined`；
+`GET /status` 如实上报 16 个服务的 `available`，缺哪个页面就显示降级，不假装正常。
+
+---
+
+## 7. 目录与数据布局
+
+```
+~/.dsh/cs-bots/
+├── board.jsonl / board.snap.json
+├── roster.jsonl / roster.snap.json
+├── memory.jsonl / memory.snap.json / memory-fts.db
+├── discipline.jsonl / discipline.snap.json
+├── todo.jsonl / todo.snap.json
+├── prompts.jsonl / prompts.snap.json
+├── suggestions.jsonl / suggestions.snap.json
+├── reviewer.jsonl
+├── library.jsonl / library-skill-dirs.json
+├── wakes.jsonl
+├── scratch/<scope>.md
+└── rooms/<roomId>/{log.jsonl,bodies/*.txt}
+```
+
+每条 Bot 的档案落在**它自己的 cwd**（写作边界）：
+`<cwd>/AGENTS.md`（受管区块）+ `<cwd>/.agents/skills/*/SKILL.md`。
+
+---
+
+## 8. 接口规模（**v0.6 时的实测，已过期**）
+
+> ⚠️ 下表是 2026-11-06 的数字，**不是现在的**。当前数字见本文件开头。
+
+| 层 | 数量（v0.6） | 说明 |
+|---|---|---|
+| HTTP 端点 | 93 | `src/api.js`，全部经围栏 |
+| 模型工具 | 28 | 前缀 `bot_`，避免与其他插件撞名 |
+| 域服务 | 12 | 见 §3 |
+| 源文件 | 24 | `src/*.js`，合计 24,736 行 |
+| 测试文件 | 30 | 656 用例全绿（v0.6 时） |
+
+---
+
+## 9. 开发与验收
+
+```bash
+bash test/run-all.sh      # 单入口：零依赖 CI + 全部单测；任一失败退出码非 0
+bash test/ci-zero-dep.sh  # 只跑零依赖 CI（5 项）
+bash install.sh --channel npm   # 装 + 自检（exit=2 表示装了但自检不过）
+```
+
+**交付验收口径**：只认证据 —— 文件存在、退出码、真实输出。不接受「我完成了」。
+
+**已知环境坑**
+1. `~/.dsh/profiles/web/node_modules/cs-bots` 是**真实拷贝**（不是 symlink）⇒
+   改源码后必须 `rsync` + `sudo systemctl restart dsh-web.service` 才生效；
+   而 `cs-guard`/`cs-myfree` 是 symlink，改完即生效。
+2. 重启会杀掉当前会话的 cgroup ⇒ 重启+验证脚本必须用
+   `sudo systemd-run --unit=... --collect` 独立单元运行，日志写独立文件。
+3. bundle 层序：本插件必须排在 `agent-team-profile` **之后**，否则
+   `maxMembers` 覆盖会在目标行不存在时被静默跳过（`install.sh` 会检测并重排）。

package/docs/adr/ADR-001-/351/241/265/347/255/276/347/273/223/346/236/204/345/233/236/345/210/260/344/270/203/351/241/265.md

@@ -0,0 +1,70 @@
+# ADR-001 · 页签结构回到 7 个（能力增长，页签不增长）
+
+- 状态：已采纳（2026-11-05）
+- 决策人：主管（用户）提问 + Lead 分析
+- 影响面：`src/client.js` 的 `TABS`、全部页面文案
+
+## 背景
+
+v0.1.1 的原架构是 **7 个页签**：任务 / Bot / 房间 / 记忆 / 技能库 / 工作流库 / 设置。
+
+v2 为对齐「记忆进化」的能力（`ANALYSIS-memory-evolve-parity.md`），补齐了
+待办、便签、纪律、提示词四块能力，并**各开了一个页签**，页签变成 11 个：
+
+```
+任务 · 待办 · Bot · 房间 · 纪律 · 记忆 · 便签 · 提示词 · 技能库 · 工作流库 · 设置
+```
+
+主管质疑：**「待办和便签为什么单列 UI，是仿照记忆进化吗？和任务的关系是什么。」**
+这个质疑命中了真问题。
+
+## 分析：原架构的页签只有两种
+
+| 类型 | 判据 | 例 |
+|---|---|---|
+| **协作对象** | 你有多个；每个有生命周期；需要点进去看详情；会被别的对象引用 | 任务、Bot、房间 |
+| **配置资产** | 配置一次；被多处引用；不需要"逐个点进去操作" | 技能库、工作流库、设置 |
+
+对照后发现，v2 新增的四个页签**两类都不属于**：
+
+- **待办** = 任务的个人视图（同一件事的两种粒度，不是两种对象）
+- **便签** = 一次性草稿（没有生命周期，甚至不算对象）
+- **纪律** = AI 的规矩（记忆的同族：AI 该知道什么）
+- **提示词** = AI 的指令模板（同上）
+
+**根因**：把「能力对等」误当成「页面也对等」——memory-evolve 有独立页面，
+这边就也各开一个。但页面结构应对齐**本平台的领域模型**，不是对齐别的插件的页面。
+
+## 决策
+
+**新增能力一律不新开页签**，只能作为既有页签内的子视图。页签数回到 **7**：
+
+| 主页签 | 子视图 | 一句人话 |
+|---|---|---|
+| 任务 | 协作看板 / 我的待办 / 便签 | 要做的活 |
+| Bot | — | 谁来做 |
+| 房间 | — | 在哪商量 |
+| 记忆 | 事实与偏好 / 纪律与要求 / 提示词 | AI 该知道什么 |
+| 技能库 | — | 怎么做 |
+| 工作流库 | — | 按什么步骤做 |
+| 设置 | — | 平台怎么跑 |
+
+## 对主管两个具体建议的回应
+
+1. **「待办/便签融合到任务栏」→ 采纳**。理由：三者是**一条漏斗**——
+   便签（想到就记）→ 待办（决定要做）→ 任务（决定交给谁做）。
+   并且补了 **`POST /todos/promote`**（待办「派下去」按钮）把漏斗收口，
+   否则只是换了个位置，没解决"两种东西并存"的困惑。
+
+2. **「记忆/纪律/提示词融合到一个设置页」→ 采纳分组，但不放进设置**。
+   理由：**记忆是高频操作的对象**（要增删改查、要归档、要按项目切），
+   塞进设置页会让最常用的功能多点两层。改为在顶层**记忆**页下做三个子视图，
+   分组逻辑正是主管说的那个分组（AI 该知道什么），只是不叫"设置"。
+
+## 后果
+
+- 页签数 7，与 v0.1.1 原架构一致；新增能力全部落子视图。
+- 新增代码判据（写进 ARCHITECTURE.md §4）：
+  > 新能力若没有独立生命周期、不需要多人/多 Bot 共同引用、不产生可点进去的详情，
+  > 不许新开页签。
+- 代价：子视图多一次点击才能到「便签」；用「一条漏斗」的心智抵消。

package/docs/steps/step-01-/345/216/237/346/236/266/346/236/204/345/244/215/345/216/237/344/270/216IA/350/257/212/346/226/255.md

@@ -0,0 +1,80 @@
+# Step 01 · 原架构复原与信息架构（IA）诊断
+
+> 存档目的：后续所有改动都以「原架构」为准绳。本文件锁定原架构的事实，以及
+> 为什么会出现「待办/便签单列」这种越界，避免重复讨论。
+
+## 1. 原架构（事实，来自 README + git 历史，不是回忆）
+
+**领域层 = 5 个协作对象/服务**（`src/` 一一对应）：
+
+| 域服务 | 文件 | 职责 | 持久化 |
+|---|---|---|---|
+| `board` 任务板 | `board.js` | 跨会话任务：依赖 DAG、CAS 状态机、验收 | `board.jsonl` + `.snap.json` |
+| `roster` Bot 注册表 | `roster.js` | 持久 Bot，**独立 cwd = 写入边界** | `roster.jsonl` + `.snap.json` |
+| `room` 房间群聊 | `room.js` | 消息流 + `seq` 游标 + 长正文旁路 | `rooms/<id>/log.jsonl` |
+| `memory` 分层记忆 | `memory.js` | L0–L5、注入、检索 | `memory.jsonl` + FTS5 |
+| `dispatcher` 唤醒桥 | `dispatcher.js` | 定向唤醒 + `dedupKey` 去重 | `wakes.jsonl` |
+
+**页面层 = 7 个页签**（v0.1.1 之前）：
+
+`任务` / `Bot` / `房间` / `记忆` / `技能库` / `工作流库` / `设置`
+
+**页签与域的映射关系只有两种**：
+1. **协作对象**（任务、Bot、房间）——你有多个、每个有生命周期、需要点进去看详情；
+2. **配置资产**（技能库、工作流库、设置）——你配置一次、被多对象引用。
+
+**三条原始设计原则**（README「设计要点」+ 代码注释）：
+1. **独立工作目录**：持久 Bot 走 `ctx.agents.create({meta:{cwd}})`，因为官方
+   `spawn_teammate` 无 `cwd` 字段、子会话强制继承父 cwd，而 cwd 同时是 fs 写入边界。
+2. **自建而非寄生**：官方任务板 `TeamId=SessionId`（每会话一块）、roster 是
+   flat immutable（无改名/删除/复用）⇒ 跨会话任务板与可维护 Bot 注册表必须自建。
+3. **零第三方运行时依赖**：`test/ci-zero-dep.sh` 机械强制（5 项检查）。
+   生态里任何插件（含 `dsh-memory-evolve`）都**不许 import**。
+
+## 2. 越界是怎么发生的
+
+v2 按 `ANALYSIS-memory-evolve-parity.md` 补齐「记忆进化」对等能力时，
+**把"能力对等"误当成"页面也对等"**：memory-evolve 有独立页面，于是这边也各开一个页签。
+
+结果页签从 **7 → 11**：
+
+```
+任务 · 待办 · Bot · 房间 · 纪律 · 记忆 · 便签 · 提示词 · 技能库 · 工作流库 · 设置
+```
+
+**这违反了原架构的第 1 条映射规则**：待办、便签、纪律、提示词都不是「有生命周期的协作对象」，
+它们是**某个既有对象的属性/视图**：
+
+- 待办 = 任务的**个人视图**（同一件事的两种粒度）；
+- 便签 = 个人的**临时草稿**（不是对象，是一次性的）；
+- 纪律 = AI 的**规矩**（和记忆同一心智：AI 该知道什么）；
+- 提示词 = AI 的**指令模板**（同上）。
+
+**判据（以后新增功能都用它自查）**：
+> 新能力若没有独立生命周期、不需要多人/多 Bot 共同引用、不产生可点进去的详情，
+> 就**不许新开页签**，只能作为既有页签内的子视图。
+
+## 3. 结论：回到 7 个页签（不是新增，是归位）
+
+| 主页签 | 子视图 | 归并为一句人话 |
+|---|---|---|
+| **任务** | 看板 / 我的待办 / 便签 | 「要做的活」 |
+| **Bot** | （不变） | 「谁来做」 |
+| **房间** | （不变） | 「在哪商量」 |
+| **记忆** | 记忆 / 纪律 / 提示词 | 「AI 该知道什么」 |
+| **技能库** | （不变） | 「怎么做」 |
+| **工作流库** | （不变） | 「按什么步骤做」 |
+| **设置** | （不变，新增自审间隔） | 「平台怎么跑」 |
+
+页签数 **回到 7**，与 v0.1.1 原架构一致；新增能力全部落在子视图里。
+
+## 4. 与「任务」的关系（用户直接问的那个问题）
+
+不是同一件事，但**必须在同一个页面里**：
+
+- `board` 任务：**协作单元**。有依赖 DAG、CAS 状态、验收人、可被 Bot 领取。跨会话可见。
+- `todo` 待办：**个人备忘**。四轨（生活/工作/本项目/每日）+ 四象限 + 截止日。不参与协作。
+- `scratch` 便签：**临时草稿**。一个文件，随手写，不整理。
+
+关系是**漏斗的上游到下游**：便签（想到就记）→ 待办（决定要做）→ 任务（决定交给谁做）。
+所以同页不同视图，并在待办条目上提供「升级为任务」的入口（后续增量）。

package/docs/steps/step-02-/351/241/265/347/255/276/346/224/266/346/225/233/344/270/216/345/215/207/347/272/247/351/200/232/351/201/223.md

@@ -0,0 +1,51 @@
+# Step 02 · 页签收敛（11 → 7）与「待办 → 任务」升级通道
+
+## 1. 代码层实现（`src/client.js`）
+
+### 页签结构改为「主页签 + 子视图」
+```js
+TABS = [
+  { id:'tasks',  label:'任务', subs:[
+      {id:'board',    label:'协作看板', Comp:TasksTab},
+      {id:'todo',     label:'我的待办', Comp:TodoTab},
+      {id:'scratch',  label:'便签',     Comp:ScratchTab} ] },
+  { id:'bots',     label:'Bot' },
+  { id:'rooms',    label:'房间' },
+  { id:'memory',   label:'记忆', subs:[
+      {id:'facts',    label:'事实与偏好', Comp:MemoryTab},
+      {id:'rules',    label:'纪律与要求', Comp:DisciplineTab},
+      {id:'prompts',  label:'提示词',     Comp:PromptsTab} ] },
+  { id:'skills',   label:'技能库' },
+  { id:'workflows',label:'工作流库' },
+  { id:'settings', label:'设置' },
+]
+```
+- `viewsOf(tab)`：单页页签返回 `[自身]`；`subs.length > 1` 才渲染子页签行。
+- 切主页签时 `setView(null)`，避免「停在任务/便签，切到记忆还是便签」的串位 bug。
+- ErrorBoundary 的 `tab` 名带上子视图（`记忆/纪律与要求`），出错时能定位到具体子页。
+
+**结果：页签数 7，与 v0.1.1 原架构一致。**
+
+## 2. 「待办 → 任务」升级通道（新增，不是搬位置）
+
+原架构里没有这条通道，直接把待办塞进任务页只会是「换了个位置」。真正的关系是
+**漏斗上下游**：便签（想到就记）→ 待办（决定要做）→ 任务（决定交给谁做）。
+所以补了服务端一步：
+
+`POST /todos/promote { id, expectedRev?, priority?, by? }`
+1. 取待办 → 用第一行做任务标题、全文做描述、截止日转 `dueAt`；
+2. `board.create({ sourceSeq: 'todo:<id>' })` —— **幂等**，连点两次只产生一个任务；
+3. 待办状态 `pending → doing`（不再出现在「要关注」里被重复安排）；
+4. 返回 `{ task, todo }`。
+
+### 实测（真跑，非自述）
+```
+建待办: td-5fc328e7 状态= pending
+升级#1: 200 | task= 把发布流程写成脚本 | 待办状态= doing
+升级#2 幂等: 200 | 同一任务= true
+任务总数: 1 （应为 1）
+```
+
+## 3. UI 文案（人话）
+- 待办页标题「我的待办」，说明里点明「要交给 Bot 或别人做的，点「派下去」就会出现在「协作看板」里」；
+- 按钮叫 **「派下去」** 而不是「升级为任务」——用户心智里这是"派活"，不是"改类型"。

package/docs/steps/step-03-/346/236/266/346/236/204/350/265/204/346/226/231/346/210/220/346/226/207.md

@@ -0,0 +1,16 @@
+# Step 03 · 架构资料成文
+
+产出：
+- `docs/ARCHITECTURE.md`（245 行）——唯一架构真相源：四层结构、三条原则、12 域服务、
+  7 页签 IA、权限、实现模式、数据布局、实测数字、开发验收
+- `docs/adr/ADR-001-页签结构回到七页.md`——页签收敛的决策记录（背景/分析/决策/后果）
+- `docs/steps/step-01..03`——每步存档，避免重复劳动
+
+实测数字（写入文档，均可复核）：
+| 指标 | 值 | 复核命令 |
+|---|---|---|
+| HTTP 端点 | 93 | `grep -oE "path === '[^']+'" src/api.js \| sort -u \| wc -l` |
+| 模型工具 | 27 | `grep -cE "    name: 'bot_" src/tools.js` |
+| 域服务 | 12 | `GET /cs-bots/api/status` → `services` |
+| 源文件 | 24 / 24,736 行 | `wc -l src/*.js` |
+| 测试 | 30 文件 / 656 用例全绿 | `bash test/run-all.sh` |

package/docs/steps/step-04-/344/270/212/347/272/277/344/270/216/351/252/214/350/257/201.md

@@ -0,0 +1,46 @@
+# Step 04 · 上线与线上验证（只认证据）
+
+## 1. 部署动作（安装副本是真实拷贝，必须 rsync + 重启）
+```bash
+rsync -a --delete src/ ~/.dsh/profiles/web/node_modules/cs-bots/src/
+cp -f package.json README.md ~/.dsh/profiles/web/node_modules/cs-bots/
+rsync -a docs/ ~/.dsh/profiles/web/node_modules/cs-bots/docs/
+diff -rq src <副本>/src   # → 无输出 = 一致
+sudo systemd-run --unit=csbots-v3-restart --collect /bin/bash restart-verify-v3.sh
+```
+**为什么用 systemd-run 独立单元**：重启 dsh-web 会连带杀掉发起者的 cgroup，
+脚本自身被清理、日志断在 restart 那一行（前两次踩过）。
+
+重启实测：
+```
+旧 MainPID: 1059257
+restart 返回: 0
+就绪: 第 1 次探测 active=active
+新 MainPID: 1156272  更换=YES
+```
+
+## 2. 线上验证结果（逐项，可复跑）
+
+| 检查 | 结果 |
+|---|---|
+| 服务状态 | `active`，MainPID 已更换 |
+| 域服务装配 | **12/12 就绪**：roster, board, dispatcher, room, memory, library, discipline, todo, scratch, prompts, suggest, reviewer |
+| 鉴权围栏 | 无 cookie 的 `POST /fs/mkdir` → **401**，目录未创建 |
+| 带会话访问 | `GET /status` → **200** |
+| `POST /memory/purge` | 存在（空参返回 `MEMORY_MISSING_FIELD` 校验错误，不是 404） |
+| `POST /todos/promote` | **200**，`task.subject=「V3-线上验证：写发布脚本」` |
+| 页面加载的客户端 bundle | `HTTP=200`，**191,958 字节** |
+| bundle 内页签结构 | 实测为 7 个页签 + `subs`，`id:'todos'` 顶层页签 **0 处** |
+| 新 UI 关键字 | 协作看板 / 我的待办 / 事实与偏好 / 纪律与要求 / csb-subtabs / 派下去 / 来源目录 / 分类管理 / 记忆自审 —— 全部命中 |
+
+> 客户端 bundle 地址形如 `/plugins/??cs-bots/client.js&rev=<hash>`；
+> 重启后 `rev` 变化，浏览器刷新即拿到新版（不需要清缓存）。
+
+## 3. 测试数据已清理
+线上验证产生的待办（`td-58b2af70`）与任务（`t-20`）均已删除，未留残留。
+
+## 4. 全量测试
+```
+bash test/run-all.sh  → 656 tests / 656 pass / 0 fail
+bash test/ci-zero-dep.sh → CI PASS（5 项机械检查）
+```

package/docs//344/272/244/344/273/230/350/257/264/346/230/216-v0.2.0.md

@@ -0,0 +1,95 @@
+# cs-bots v0.2.0 · 交付说明
+
+日期：2026-11-05 ｜ 状态：已上线并线上验证
+
+---
+
+## 一、这一版回答了你问的那个问题
+
+> **「待办和便签为什么单列 UI，是仿照记忆进化吗？和任务的关系是什么。」**
+
+**是，也不是。** 事实经过：v2 补齐「记忆进化」的对等能力时，把**能力对等**
+误当成了**页面也对等**——memory-evolve 有独立页面，这边就也各开一个页签，
+于是页签从 7 涨到 11。这是**越界**，不是设计。
+
+**原架构的页签只有两种**：
+1. **协作对象**（任务 / Bot / 房间）——你有多个、有生命周期、要点进去看详情；
+2. **配置资产**（技能库 / 工作流库 / 设置）——配一次、被多处引用。
+
+待办、便签、纪律、提示词**两类都不属于**：它们是既有对象的视图或属性。
+
+**与任务的关系**：三者是一条**漏斗**——
+便签（想到就记）→ 待办（决定要做）→ 任务（决定交给谁做）。
+
+---
+
+## 二、做了什么
+
+### 1. 页签从 11 收敛回 7（与原架构一致）
+
+| 页签 | 子视图 | 一句人话 |
+|---|---|---|
+| 任务 | 协作看板 / 我的待办 / 便签 | 要做的活 |
+| Bot | — | 谁来做 |
+| 房间 | — | 在哪商量 |
+| 记忆 | 事实与偏好 / 纪律与要求 / 提示词 | AI 该知道什么 |
+| 技能库 | — | 怎么做 |
+| 工作流库 | — | 按什么步骤做 |
+| 设置 | — | 平台怎么跑 |
+
+### 2. 不只是搬位置：补了「漏斗收口」
+待办条目新增按钮 **「派下去」** → `POST /todos/promote`：
+把待办变成协作看板上的正式任务（第一行做标题、全文做描述、截止日转 dueAt），
+并把待办标成"进行中"，避免被重复安排。**幂等**（`sourceSeq=todo:<id>`，连点两次只出一个任务）。
+
+### 3. 记忆补上真删除（原来只有归档）
+- `remove` 现在诚实地叫**软删除**：进归档区、显示「已删除（可恢复）」、可恢复；
+- 新增 `purge`（**彻底删除**）：内存 + 快照 + 重启后都不存在，不可恢复；
+  事件流只留一条 `after:null` 墓碑记录"谁在何时删了什么"，审计不丢、内容不留。
+- 归档区里删过的条目会明确标注，并给「彻底删除」按钮（强确认 + 后果说明）。
+
+### 4. UI 补齐（人类视角）
+技能来源目录管理、提示词分类管理、记忆自审间隔设置、Bot 档案「从记忆库导入」、
+项目记忆切换与「归到当前项目」。
+
+---
+
+## 三、验收证据（不是自述）
+
+| 指标 | 值 | 复核方式 |
+|---|---|---|
+| 单元测试 | **656 / 656 通过** | `bash test/run-all.sh` |
+| 零依赖 CI | **PASS（5 项）** | `bash test/ci-zero-dep.sh` |
+| 线上域服务 | **12/12 就绪** | `GET /cs-bots/api/status` |
+| 线上页签结构 | 7 个页签 + 子视图，无独立待办页签 | 抓取实际下发的 client bundle |
+| 线上 promote | 200，任务 `t-20` 已建（验证后已清理） | `POST /todos/promote` |
+| 鉴权围栏 | 无会话 → 401，目录未创建 | `POST /fs/mkdir` |
+| HTTP 端点 / 工具 / 服务 | 93 / 27 / 12 | 代码扫描 + `/status` |
+
+---
+
+## 四、设计资料清单
+
+| 文件 | 内容 |
+|---|---|
+| `docs/ARCHITECTURE.md` | **唯一架构真相源**：四层结构、三条原则、12 域服务、7 页签 IA、权限、实现模式、数据布局、验收口径 |
+| `docs/adr/ADR-001-页签结构回到七页.md` | 页签收敛的决策记录（背景/分析/决策/后果/判据） |
+| `docs/steps/step-01~04` | 每步存档：原架构复原 → 页签收敛与升级通道 → 资料成文 → 上线验证 |
+| `README.md` | 对外说明：安装、27 个工具、7 页签、安全 |
+| `docs/ANALYSIS-memory-evolve-parity.md` | 与记忆进化的能力对等分析（旧，保留） |
+| `DESIGN-v2.md` | v2 详细设计（旧，保留；与 ARCHITECTURE.md 冲突时以后者为准） |
+
+---
+
+## 五、以后新增功能的判据（写进架构文档，防止再长回去）
+
+> 新能力若**没有独立生命周期**、**不需要多人/多 Bot 共同引用**、
+> **不产生可点进去的详情** —— 就**不许新开页签**，只能做既有页签内的子视图。
+
+---
+
+## 六、遗留与建议
+
+1. **发布**：`package.json` 已升 0.2.0。发布需经「插件发布管理员」角色，尚未执行。
+2. **待办→任务的反向同步**：任务完成后暂不回写待办状态（单向）。需要的话下一步补。
+3. **旧文档**：`DESIGN-v2.md` 与本文有重叠，建议后续合并进 `ARCHITECTURE.md` 后删除。