cs-bots 0.1.1 → 0.7.5

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

@@ -0,0 +1,569 @@
+# cs-bots 改造07 + 改造08（需求1–5）用户操作手册
+
+> 版本：v0.7.3（改造07 分层 + 改造08 需求1–5）
+> 日期：2026-11-09
+> 适用对象：使用 cs-bots 协作平台的人（不是 AI）
+
+---
+
+## 1. 这份手册解决什么问题
+
+看完这份手册，你会知道：
+
+- 界面长什么样（6 个页签 + 穿透入口）
+- 每个页签能干什么
+- 什么时候该点「穿透」
+- 怎么用新加的三项能力（订阅、阶段、准备命令）
+
+---
+
+## 2. 界面总览
+
+### 2.1 顶部导航
+
+```
+┌─────────────────────────────────────────────────────┐
+│  cs-bots                          [⚙ 穿透]          │
+├─────────────────────────────────────────────────────┤
+│  [工作台] [团队] [记忆] [技能库] [数据] [设置]        │
+│  ─────────────────────────────────────────────────  │
+│                                                      │
+│                  （页面内容）                          │
+│                                                      │
+└─────────────────────────────────────────────────────┘
+```
+
+**只有 6 个页签**，比以前的 10 个清爽。右边那个「⚙ 穿透」是进底层工具的入口。
+
+### 2.2 每个页签的第一印象
+
+| 页签 | 一句话 |
+|---|---|
+| **工作台** | 要做的活都在这——看板、复盘、待办、便签、成果 |
+| **团队** | 谁来做——Bot 档案、团队、讨论的房间 |
+| **记忆** | AI 该知道什么——事实偏好、纪律要求、提示词 |
+| **技能库** | 怎么做——技能、工作流 |
+| **数据** | 看数据——文件浏览、PDCA 测量 |
+| **设置** | 平台怎么跑 |
+
+---
+
+## 3. 工作台（最常用的页签）
+
+### 3.1 协作看板
+
+打开工作台默认就是看板：
+
+```
+┌─────────────┬─────────────┬─────────────┬─────────────┐
+│   待办      │   进行中     │   已完成     │   已受阻     │
+├─────────────┼─────────────┼─────────────┼─────────────┤
+│ ┌─────────┐ │ ┌─────────┐ │             │             │
+│ │ 实现登录 │ │ │ 重构后台 │ │             │             │
+│ │ 排队中   │ │ │ 正在干   │ │             │             │
+│ │ ▓▓░░░░  │ │ │ ▓▓▓▓▓░  │ │             │             │
+│ │ Bot-A    │ │ │ Bot-B    │ │             │             │
+│ └─────────┘ │ └─────────┘ │             │             │
+└─────────────┴─────────────┴─────────────┴─────────────┘
+```
+
+**卡片上你会看到**：
+- 标题
+- **阶段徽章**（改造07 新增）
+- 进度条
+- 谁在做
+
+### 3.2 阶段徽章是什么意思
+
+这是改造07 最重要的改进。以前你只知道任务「在进行中」，现在能看出**卡在谁身上**：
+
+| 徽章 | 意思 | 你该做什么 |
+|---|---|---|
+| 🟠 **投递失败** | 消息发不到执行者 | 点穿透 → 唤醒桥 → 手动 flush |
+| 🟠 **等你回答** | 执行者提了问题 | 打开任务详情回答问题 |
+| 🟠 **等你验收** | 交付物做好了 | 打开任务详情验收 |
+| 🟠 **受阻等你** | 执行者卡住了 | 打开任务详情看原因 |
+| 🟠 **失败等你** | 执行者报错了 | 打开任务详情看错误 |
+| ⚪ **排队中** | 还没人接活 | 派活给某个 Bot |
+| ⚪ **空闲等触发** | 这轮干完了，等新消息 | 补充说明或等新触发 |
+| ⚫ **正在干** | 执行者正在推进 | 不用管 |
+
+**橙色 = 需要你动手**。看到橙色徽章，就点进去。
+
+### 3.3 点开任务卡片
+
+点任意卡片，右侧滑出任务详情：
+
+```
+┌────────────────────────────────────┐
+│  实现登录                         × │
+├────────────────────────────────────┤
+│  谁建的    张三                     │
+│  来源      人建的                   │
+│  优先级    5（一般）                │
+│  截止      2026-11-10               │
+│  状态      [进行中]                 │
+│  执行阶段  [等你验收] 需要你处理     │ ← 改造07
+│  任务编号  t-1                      │
+│  谁在做    Bot-A                    │
+│  进度      ▓▓▓▓▓▓▓░░░ 70%          │
+│  ...                                │
+│                                     │
+│  可以做什么                         │
+│  [完成] [有问题] [取消]              │
+└────────────────────────────────────┘
+```
+
+**「执行阶段」这一行是改造07 新加的**，鼠标停在徽章上会显示具体原因。
+
+### 3.4 复盘周期（PDCA）
+
+子页签「复盘周期」：
+
+- 每个周期显示阶段进度条（planned → doing → checking → acting → done）
+- **不许跳步**：想直接从 planned 到 done 会报错
+- 复盘时可以记录教训，系统会提议把教训存进记忆（要你点「采纳」才生效）
+
+### 3.5 我的待办
+
+四轨待办：
+- **生活**：家里的事
+- **工作**：公司的事
+- **项目**：本项目的事
+- **每日**：今天必须做完的
+
+每个待办可以标四象限（重要/紧急）。
+
+### 3.6 便签
+
+随手记。单文件原子写，不会丢。
+
+### 3.7 成果
+
+交付物列表，可以预览。文件可以点开看内容。
+
+---
+
+## 4. 团队
+
+### 4.1 Bot 档案
+
+每个 Bot 一张卡片：
+
+```
+┌──────────────────────────────────┐
+│  🤖 Bot-A            [空闲]       │
+│  开发工程师                       │
+│  /home/ubuntu/ws/bot-a            │
+│  记忆 12 条 · 纪律 3 条            │
+│  [派任务] [发消息] [档案]          │
+└──────────────────────────────────┘
+```
+
+**点「档案」能看到**：
+- 身份、经验、技能、预制记忆
+- **准备命令**（改造07 新增）
+
+### 4.2 准备命令怎么用（改造07 新增）
+
+准备命令是「Bot 开工前先跑一遍的命令」。
+
+**什么时候用**：
+- Bot 需要 `git worktree` 建独立工作区
+- Bot 需要先 `pnpm install` 装依赖
+- Bot 需要先拉最新代码
+
+**怎么设**：
+1. 团队 → Bot 档案 → 点某个 Bot 的「档案」
+2. 找到「准备命令」字段
+3. 填命令，比如：`git worktree add ../my-task main`
+4. 保存
+
+**会发生什么**：
+- 下次派活给这个 Bot 时，系统先跑这条命令
+- 跑成功 → 任务正常认领
+- 跑失败 → 任务**不会被认领**，返回错误原因
+- 这样不会出现「认领了但环境没准备好」的半成品
+
+**安全限制**（系统自动检查）：
+- 命令第一个词必须是安全的：`bash` / `node` / `npm` / `pnpm` / `npx` / `git` / `ls` / `test` / `python3`
+- 不能写 shell 语法（`&&`、`|`、`>` 都不行）
+- 最多跑 10 分钟
+
+### 4.3 团队
+
+团队列表。每个团队显示：
+- 成员
+- 任务数
+- 健康度
+- 团队记忆（L2，全队可见）
+
+### 4.4 房间
+
+群聊列表。点进去能聊天。
+
+**房间消息气泡上有个「⇢ 建任务」按钮**（鼠标移上去才显示）——可以直接把一条消息变成任务。
+
+---
+
+## 5. 记忆
+
+### 5.1 事实与偏好
+
+AI 记住的事情，按层分组：
+
+| 层 | 含义 | 谁能改 |
+|---|---|---|
+| L0 人格 | AI 是谁 | **只有人能改** |
+| L1 用户偏好 | 你的偏好 | AI 提议 + 人采纳 |
+| L2 团队全局 | 团队规矩 | 主 Bot / 房间管理员 |
+| L3 项目 key | 这个项目的关键事实 | 任何成员（限本项目） |
+| L4 任务笔记 | 某个任务的记录 | 按需查 |
+| L5 日札 | 每天记的 | 按需查 |
+
+### 5.2 纪律与要求
+
+分级纪律：全局 / 工作区 / 房间 / Bot。
+
+可以看「我实际要遵守哪些」——系统会合并层、去重、按优先级排序。
+
+### 5.3 提示词
+
+模板列表。模板里有 `{{date}}` / `{{time}}` 会自动替换成当前日期时间。
+
+---
+
+## 6. 技能库
+
+### 6.1 技能
+
+AI 会什么。来源分四种：
+- 自建
+- 用户级
+- 项目级
+- 系统自带
+
+可以导入目录。
+
+### 6.2 工作流
+
+按什么步骤做。每个工作流显示名称、描述、步骤数。
+
+---
+
+## 7. 数据
+
+### 7.1 文件浏览
+
+状态目录的文件树，点开能看内容。
+
+### 7.2 PDCA 测量
+
+指标聚合：
+- 按类型计数
+- 求和
+- 首末时间
+
+用来看「团队效率怎么样」。
+
+---
+
+## 8. 设置
+
+平台参数：
+- 记忆自审间隔
+- 每 Bot WIP 上限
+- 各种超时
+- **CS-BOTS 专用工作区**（新建 Bot 的默认目录）
+
+---
+
+## 9. 穿透面板（改造07 核心新功能）
+
+### 9.1 什么时候该点「⚙ 穿透」
+
+**平常不用点。** 只在下面这些情况点：
+
+| 情况 | 进哪个区块 | 干什么 |
+|---|---|---|
+| 任务不动，怀疑没唤醒 | 唤醒桥 | 看唤醒日志，手动 flush |
+| 怀疑数据坏了 | 存储 | 看文件健康，手动 replay |
+| 想确认 Bot 注册对不对 | 注册表 | 看 Bot 生命周期 |
+| 想确认路由走没走对 | 路由 | 看规则和决策日志 |
+| 想确认验收证据 | 验证 | 看验收记录 |
+| 想处理 AI 提的建议 | 建议 | 采纳/驳回 |
+| 想让任务自动接住房间讨论 | 订阅 | 订阅房间、看订阅关系、取消订阅 |
+
+### 9.2 怎么用
+
+1. 点右上角「⚙ 穿透」
+2. 右侧滑出抽屉，显示 7 个区块：
+
+```
+┌────────────────────────────────────┐
+│  底层工具                        × │
+├────────────────────────────────────┤
+│  ┌─ 注册表 ──────────────────────┐  │
+│  │ Bot 注册表 / 任务板 / 团队注册  │  │
+│  │ bots: 5  states: {...}         │  │
+│  └───────────────────────────────┘  │
+│  ┌─ 唤醒桥 ──────────────────────┐  │
+│  │ total: 120 sent: 118 failed: 2 │  │
+│  └───────────────────────────────┘  │
+│  ┌─ 存储 ────────────────────────┐  │
+│  │ files: 12 total: 14            │  │
+│  └───────────────────────────────┘  │
+│  ...                                │
+└────────────────────────────────────┘
+```
+
+3. 点某个区块 → 展开详情
+4. 有操作按钮的直接点（比如「强制投递队列」）
+
+### 9.3 两个最常用的操作
+
+**操作一：强制投递队列（唤醒桥）**
+
+场景：任务显示「投递失败」，你确认会话是活的。
+
+1. 穿透 → 唤醒桥 → 展开
+2. 点「强制投递队列」
+3. 看到「已强制投递：sent=N, failed=M」
+
+**操作二：重建内存态（存储）**
+
+场景：怀疑内存和磁盘不一致。
+
+1. 穿透 → 存储 → 展开
+2. 点「重建内存态（replay）」
+3. 看到 replay 结果
+
+⚠️ **replay 会重建内存态，正在跑的任务可能受影响**——用前确认没有重要任务在跑。
+
+---
+
+## 10. 任务订阅（改造07 新增）
+
+### 10.1 这是什么
+
+任务可以「订阅」一个房间，房间里的后续消息会**自动**到达这个任务——不用你每次都去 @ Bot 补一句「刚才房间说了什么」。
+
+### 10.2 怎么订阅
+
+1. 打开任务详情
+2. 找到「订阅」区块
+3. 选一个房间
+4. 点「订阅」
+
+### 10.3 订阅后会发生什么
+
+- 房间里有人说话，任务自动收到（作为上下文）
+- **不会改变任务状态**
+- **不会打扰执行者**（默认不唤醒）
+- 每个任务最多保留最近 20 条上下文
+
+### 10.4 怎么取消
+
+任务详情 → 订阅区块 → 点订阅记录旁的「取消」。
+
+⚠️ 取消是终态，不能恢复，需要的话重新订阅。
+
+---
+
+## 11. 常见场景快查
+
+### 场景 1：任务卡住了
+
+```
+1. 看卡片阶段徽章是什么
+2. 橙色 → 点进去，按徽章含义处理（见 3.2 表）
+3. 灰色「排队中」→ 派活
+4. 还是不动 → 穿透 → 唤醒桥 → 强制投递
+```
+
+### 场景 2：Bot 派活了但没反应
+
+```
+1. 穿透 → 唤醒桥 → 看日志
+2. 如果 failed 且原因是 agent-not-live：
+   - 团队 → Bot 档案 → 点「启动会话」
+   - 或穿透 → 注册表 → 重启全部 Bot 会话
+3. 再派一次活
+```
+
+### 场景 3：想看看 AI 记住了什么
+
+```
+记忆 → 事实与偏好 → 按层看
+```
+
+### 场景 4：想让 AI 开工前先准备环境
+
+```
+团队 → Bot 档案 → 档案 → 准备命令 → 填命令 → 保存
+```
+
+### 场景 5：讨论里说的东西希望相关任务知道
+
+```
+1. 打开任务详情
+2. 订阅区块 → 选讨论所在房间 → 订阅
+3. 之后房间里说的话，任务自动收到
+```
+
+### 场景 6：怀疑数据有问题
+
+```
+穿透 → 存储 → 看文件列表和大小
+→ 有问题就点「重建内存态（replay）」
+```
+
+---
+
+## 12. 术语表
+
+| 词 | 意思 |
+|---|---|
+| **Bot** | 一个独立的 AI 助手，有自己的工作目录和记忆 |
+| **任务** | 一件要做的事 |
+| **阶段** | 任务的执行状态（排队中/正在干/等你验收……） |
+| **房间** | 多人群聊的地方 |
+| **订阅** | 任务订阅房间，房间消息自动到达任务 |
+| **穿透** | 进底层工具看/管 |
+| **唤醒** | 告诉一个 Bot「有活要干」 |
+| **租约** | Bot 领任务时的「占用凭证」，过期会自动回收 |
+| **WIP** | 同时在做的任务数上限 |
+| **PDCA** | 计划-执行-检查-改进的复盘循环 |
+| **复现** | 重新生成一份内存状态（replay） |
+| **冷却** | 防止短时间内重复唤醒的机制 |
+
+---
+
+## 13. 常见问题
+
+**Q：为什么只剩 6 个页签了？**
+A：改造07 做了分层。所有功能还在，只是重新归组了。
+
+**Q：以前的链接还能用吗？**
+A：能。旧页签 id 会自动映射到新页签。
+
+**Q：阶段徽章和状态徽章有什么区别？**
+A：状态是「任务还在不在做」（5 个值），阶段是「卡在谁身上」（8 个值，更细）。
+
+**Q：订阅会打扰执行者吗？**
+A：默认不会。上下文到达不等于要打扰，除非你显式要求唤醒。
+
+**Q：准备命令失败会怎样？**
+A：任务不会被认领，你会看到失败原因。修好命令再派一次即可。
+
+**Q：穿透面板能改数据吗？**
+A：只能做有限操作（flush、replay）。不能直接改数据——那是危险的。
+
+**Q：手机上能用吗？**
+A：能。页签横向滚动，穿透面板是全屏抽屉。
+
+---
+
+*操作手册完。*
+---
+
+## 改造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 / 让它归纳
+```