dsh-bot-team 1.1.0 → 1.3.0

package/README.md

@@ -1,200 +1,250 @@
-# Bot Team（M1–M4 + v0.5–v0.8.1 内部迭代 + v1.1 i18n/PDF）
+# Bot Team
 
-在 DSH Web GUI 里做多 Agent 群聊与单聊：每个 Bot 自动拥有一个单聊窗口；创建群/话题 → 从全局 Bot 库拉入多个 Bot → 在群里 @ 某个 Bot 派活、多 @ 并行回复、查看流式输出。群聊可以放进自定义分组、拖动排序，单聊 / 群聊 / 每个分组都能展开或收起。
+> 把 DeepSeek Harness 变成一间「Bot 公司」：每个 Bot 都是真实的 Agent，有独立会话、模型、人格和全套工具。你可以像用 IM 一样单聊、拉群、`@` 派活、评审、讨论、建任务。
 
-每个 Bot 是**真实的 DSH Agent**（独立持久 Session），可以单独设置：
+`版本 1.3.0` · `MIT` · `DSH 0.2.1-rc.x` · `npm dsh-bot-team`
 
-- **模型**：provider / model / reasoning effort / maxTokens（创建时 `agentOptions`，resume 时复传）；
-- **头像**：按名称生成机器人面具、点「随机生成」换配色/表情、选 10 个 SVG 插画之一，或自定义上传（浏览器裁成 256×256，存为 data URL）；
-- **人格与工作规范**：`<botsDir>/<botId>/BOT.md`（一个文件写「你是谁」+「你怎么做事」，在页面内编辑，下一轮生效；旧版 SOUL.md/AGENT.md 仍可读取）；
-- **工具**：所有 Bot 统一为全能力 Bot——文件读写、搜索、联网、命令执行、Skill；不提供只读版或按角色裁剪工具的版本。session 沙箱为 `workspace-write`，范围受群/单聊工作目录限制。
+![Bot Team 首次使用欢迎页：创建 Bot、创建群聊与快速上手（深色）](<https://raw.githubusercontent.com/shper/dsh-bot-team/main/docs/assets/home-dark.png>)
 
-群、分组、Bot、成员、消息都保存在插件自己的 storage domain `bot_team`（`$DSH_HOME/storages/bot_team/`），不污染会话日志。单聊也是 group 记录（`kind: "direct"`），由 Host 自动创建与清理。
+*当前客户端的真实 React 浏览器截图，使用隔离的模拟 API 数据。*
 
-插件文件数据默认在 `$DSH_HOME/dsh-bot-team/`：
+## 这是什么
 
-| 路径 | 用途 |
+Bot Team 是 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）的侧栏插件。常见的「多 Agent」是在一次对话里临时开几个子 Agent，聊完即散；Bot Team 把 Bot 做成长期存在的同事：
+
+- 每个 Bot 有名字、头像、独立的 provider / model / reasoning effort / maxTokens，以及独立 Session 记忆；
+- 人格与工作规范写在 `BOT.md`，改完下一轮生效；
+- 单聊是它的工位，群聊是会议室，任务工具管理工单，评审和讨论组织协作流程；
+- 所有 Bot 统一为全能力 Bot：读写文件、搜索、联网、执行命令、Skill；不提供只读版或按角色裁剪工具的版本（`workspace-write` 沙箱，范围受群/单聊工作目录限制）；
+- 每个 Bot 都有持久会话，点「查看会话」可在完整历史页面查看所有轮次与执行记录。
+
+## 功能
+
+### 对话
+
+| 能力 | 说明 |
+|---|---|
+| 单聊 | 每个 Bot 自动拥有一个单聊窗口，不需要 `@`，记忆与群聊相互独立 |
+| 群聊 | 群 / 话题、成员管理、`@` 派活、多 `@` 并行回复 |
+| 流式 | 实时流式输出、停止、失败重试、断线补齐 |
+| 消息 | 引用回复（群聊回复 Bot 时自动 `@` 原作者）、右键菜单、同作者消息合并、时间分隔、新消息分隔线、回到底部 |
+| 输入 | 左下角 **+** 打开 DSH 风格分组命令菜单（文件 / 文件夹 / 技能 / 提及 / 停止 / 导出 / 设置）；键入 `/` 选择 Skill；文件存入 DSH 附件库，Bot 拿到只读路径 |
+| 项目 | **+ → 文件夹** 引入本地项目，单聊和群聊均可用；Bot 在原目录检索、修改和运行任务，输入框支持更换或移除项目 |
+| 导出 | 群聊导出 Markdown / HTML / PDF（PDF 文本可选中、A4 分页、页脚页码） |
+
+### 组织与界面
+
+- **首次使用引导**：欢迎页以 **创建 Bot** 为主入口、**创建群聊** 为次入口；**快速上手** 提供三步引导，创建成功后直接进入新 Bot 单聊或新群；
+- 欢迎页及侧栏 **开始使用** 仅在没有 Bot 且没有群聊时显示；存在任一即隐藏，已有数据时不能返回欢迎页；删除全部 Bot 和群聊后恢复；欢迎页不显示右侧 Bot 库；
+- 单聊、群聊、未分组和自定义分组都能展开 / 收起，群与分组支持拖动排序；
+- 左侧栏从 232px 收起成 68px 图标栏，底部 **Bot 管理 / 设置** 上下排列；欢迎页随可用宽度调整卡片布局，窄屏通过导航按钮展开侧栏；
+- 深浅色跟随 DSH（light / dark / system），使用 `--bt-*` token，切换即时生效；
+- 账号头像、群头像（随机配色 / 10 个 SVG 插画 / 上传）、Bot 头像（按名字生成机器人面具）；
+- **设置 → 关于** 提供异步版本检测、兼容更新入口与更新说明；插件启动后自动检查 npm，发现兼容更新时在 **设置** 入口显示小圆点。检测失败不影响聊天；
+- **设置 → 数据存储** 集中显示数据、人格文件、单聊和群聊默认工作目录。
+- **中文 / English 界面**跟随 DSH 的 **设置 → General → Language** 即时切换；宿主生成的讨论/评审/审批事件消息也会随语言切换，Bot 消息、群名、Bot 名等用户内容保持不变。
+
+### 协作
+
+以下讨论与辩论扩展已纳入 **1.3.0 源码版本**。加载本地目录中的新代码，需要在插件管理中 **disable → enable** 重新加载 Host，再刷新现有页面。完整流程与接口见[讨论与辩论](<https://github.com/shper/dsh-bot-team/blob/main/docs/%E8%AE%A8%E8%AE%BA%E4%B8%8E%E8%BE%A9%E8%AE%BA.md>)。
+
+- **评审**：让另一个 Bot 评审一条消息，返回「通过 / 需修改」结论徽标，可一键「让作者修改」；
+- **多成员讨论**：结构化讨论至少 2 人，界面提供快速 2 轮、标准 3 轮、深入 5 轮及自定义 2–20 轮，按观点、质询、收敛推进，穿插小结并可选最终总结；经典讨论支持 1–20 轮，旧工具调用默认 2 轮；
+- **1v1 辩论**：正反方各 1 人，可另选独立裁判；双方开篇、交替先手的交叉问答、总结陈词，再由裁判裁决。无裁判不生成胜负；
+- **过程控制**：查看阶段与发言者，暂停、继续、重试失败步骤、提前收束、停止，或补充材料与同群历史消息引用；
+- **任务管理（模型工具/API）**：创建任务并设置描述、验收标准、指派与评审者；派发 → 交付 → 评审 → 验收；支持优先级、DAG 依赖、环检测、验收后自动解锁、批量派发、队列与中断。群聊右侧的任务面板和「新建任务」入口已移除，任务能力仍可通过模型工具与 HTTP action 使用；
+- **审批**：Bot 需要越界或升权时，聊天区域显示待处理审批卡片，可直接在 Bot Team 中允许一次或拒绝。
+
+### 模型工具
+
+当前工作区在普通会话里提供 10 个群聊工具；Bot 成员禁用写入编排工具以防递归，仍可读取群与任务列表：
+
+```
+bot_team_list          bot_team_create_group        bot_team_send         bot_team_review
+bot_team_discuss       bot_team_debate              bot_team_discussion_control
+bot_team_task_create   bot_team_task_list           bot_team_task_update
+```
+
+## 安装
+
+前置：DeepSeek Harness `0.2.1-rc.x`（桌面版或 CLI profile 均可）。
+
+### 桌面版
+
+1. 左侧栏 **插件 / Plugins** → **添加插件**；
+2. 填 `dsh-bot-team@1.3.0`（也可以填本地目录绝对路径或 Git 地址）；
+3. 安装完成后启用；如果之前启用过，对该 bundle **disable → enable**（或完整重启 DSH）；
+4. 刷新页面，左侧栏出现 **Bot Team** 图标。
+
+### CLI
+
+```sh
+dsh plugin --profile <profile> add dsh-bot-team@1.3.0
+```
+
+安装后同样要重新加载 Host 模块（disable→enable 或重启）。
+
+> `1.3.0` 是当前源码版本；npm 上的公开发行版需按 [发布指南](https://github.com/shper/dsh-bot-team/blob/main/docs/%E5%8F%91%E5%B8%83%E6%8C%87%E5%8D%97.md) 执行 `npm publish`。在发布前安装本机源码，请用本地目录路径。
+
+### 从源码
+
+```sh
+git clone https://github.com/shper/dsh-bot-team.git
+cd dsh-bot-team
+npm install
+```
+
+在插件页把 `/path/to/dsh-bot-team` 作为本地目录添加；或让 Agent 执行 `plugin_manager` 的 `install_bundle`，`target` 填这个绝对路径。改完代码需要 disable→enable 或重启，才会加载新的 Host 模块。
+
+> 仓库根目录就是插件目录。从源码安装时先运行 `npm install`，安装 PDF 字体子集化所需的 `fontkit` 依赖。
+
+### 兼容性
+
+`engines.dsh` 为 `^0.2.1-rc.3`，安装在运行中的 DSH 版本上校验（含预发布版本）。DSH 升级到 0.3 后需要先跑一遍回归、再放宽范围并发新版本；用户被拦时可用 exact-version exemption，但会有风险提示。
+
+## 快速开始
+
+打开 **Bot Team**，没有 Bot 且没有群聊时会看到「开始使用」欢迎页。主按钮 **创建 Bot** 是推荐的第一步，也可以从次入口 **创建群聊** 开始；欢迎页右上角 **快速上手** 可查看以下三步：
+
+1. **先认识一位 Bot**：点 **创建 Bot**，起名、选模型、填写 `BOT.md` 人格（可插入 9 套现成人格模板）。创建成功后自动打开它的单聊，直接发消息即可，无需 `@`。
+2. **为共同的目标，建一个群**：点侧栏「群聊」右侧 **+**，保存后进入新群，再用右侧「+ 添加」邀请 Bot；同一 Bot 可以参与多个群。
+3. **用 @ 邀请它们参与**：在群输入框里用 `@Bot名` 派活，多个 `@` 会并行回复并实时流式显示；随后可以发起评审或多轮讨论。
+
+创建 Bot 或群聊后进入相应会话，欢迎页与侧栏 **开始使用** 隐藏，已有数据时不能返回欢迎页；删除全部 Bot 和群聊后恢复。取消创建会留在欢迎页。首页不显示右侧 Bot 库，全局 Bot 管理可从侧栏底部打开。欢迎页与引导支持中文 / English、light / dark 主题，并随可用宽度调整布局，窄屏可通过导航按钮访问侧栏。
+
+任务可通过 `bot_team_task_create` / `bot_team_task_list` / `bot_team_task_update` 或 HTTP action 管理；群聊侧栏已移除任务面板。
+
+<details>
+<summary>浅色欢迎页（当前实现）</summary>
+
+![Bot Team 首次使用欢迎页（浅色）](<https://raw.githubusercontent.com/shper/dsh-bot-team/main/docs/assets/home-light.png>)
+
+同样来自当前客户端的真实 React 浏览器渲染，API 使用隔离的模拟数据。
+
+</details>
+
+## 它是怎么工作的
+
+| 层 | 做法 |
 |---|---|
-| `bots/<botId>/BOT.md` | Bot 人格与工作规范（旧版 SOUL.md/AGENT.md 仍兼容读取） |
-| `direct/<botId>/` | 该 Bot 单聊的工作目录 |
-| `groups/<groupId>/` | 该群聊的工作目录 |
-
-群/单聊记录里的 `workspaceCwd` 可以覆盖默认值；留空即使用上表目录。从旧版本升级时，Host 首次启动会把 `$DSH_HOME/bot-team/bots` 和仍指向 `$DSH_HOME/bot-team/` 的工作目录迁到新位置；v0.8.0 短暂使用的 `<dataDir>/<botId>` 单聊目录也会被折进 `direct/<botId>`。对应群记录会一并改写，用户自己指定的外部工作目录不动。迁移后 Bot 的旧 session cwd 与新工作目录不一致，首次回复时会为该成员新建 session（群消息历史保留，旧 session 文件不删除）。
-
-## 使用
-
-1. 左侧栏点击 **Bot Team** 图标，打开整页工作台；工作台左侧是「对话」栏：**单聊在上、群聊在下**，群聊可放进自定义分组。点头部按钮可把侧栏收起成图标栏（详情见第 25 条）。
-2. 「群聊」右侧的 **+** 创建群/话题；「单聊」右侧的 **+** 创建 Bot。**新建 Bot 后会自动创建并打开它的单聊窗口**，不需要先建群。
-3. 群聊里右侧「+ 添加」把 Bot 拉入；没有 Bot 时点「+ 新建 Bot」创建（可同时选头像/上传图片、写 BOT.md 人格与工作规范，`插入模板` 里有 9 套现成人格可选）。
-4. 群聊输入框里用 `@` 选择成员后发送；被 @ 的 Bot 会并行开始回复，输出实时流式显示。单聊里**不需要 @**，每条消息都会直接发给该 Bot。输入框左下角 **+** 打开与 DSH 一致的分组命令菜单（文件 / 技能 / 提及 / 停止 / 导出 / 设置）；直接键入 `/` 也能选择 Skill（`/skill-name` 会在该轮加载对应 Skill 指令）。消息按作者分组，悬停或右键可回复/复制/评审，支持引用原消息与「回到底部 / N 条新消息」。
-5. 输入框底部「停止」可中断当前群所有进行中的回复。
-6. **模型工具**：在任意普通会话里也能用 `bot_team_list` / `bot_team_create_group` / `bot_team_send` / `bot_team_review` / `bot_team_discuss` 操作群聊（Bot 成员自身被 deny，防递归）。
-7. **更多**：评审（结论徽标 + 让作者修改）、多轮讨论（进度/总结/停止）、Markdown（表格/删除线/代码块）、历史上翻、群导出 Markdown/HTML、成员「查看会话」、群 workspace 与 token 用量。
-8. **硬化**：按群配额/限流（`maxTurnsPerHour`、`dailyTokenBudget`）、所有 Bot 统一 workspace-write 沙箱（受群工作目录限制）、domain schema 迁移（meta/schema）、`GET /api/bot-team.health`。
-9. **任务板（v0.5）**：右栏「+ 新建任务」（标题/描述/验收标准/指派/评审者）→ 派发 → Bot 交付 → 请评审（verdict 自动流转）/验收通过/要求修改 →「让作者修改」再交付；消息上显示任务状态标记。
-10. **任务模型工具 + 依赖/优先级（v0.5.1）**：`bot_team_task_create/list/update` 可在普通会话里建任务、派发、评审、验收；任务支持 `priority`（排序/展示）与 `dependsOn`（DAG 依赖、环检测、未验收阻塞派发、验收后自动解锁）；UI 支持优先级 chip、依赖多选、任务编辑。
-11. **任务队列 + 一键派发（v0.5.2）**：任务面板显示「执行中 / 排队」并支持一键派发所有就绪任务（按优先级入队、受 `maxParallelTurns` 限制）；排队中的任务显示「排队中」；`autoDispatchReady`（默认关）可在依赖解锁后自动派发。
-12. **全局 Bot 管理（v0.5.4）**：左侧栏底部「Bot 管理」按钮打开「Bot 管理（全局）」，查看全部 Bot 的名称/模型/所属群，支持新建、编辑、删除（删除前提示会从群中移出）。
-13. **任务面板简化（v0.5.3）**：面板只保留「派发 / 中断 / 执行流」——进行中可**中断**（abort 当前 Bot turn）；点「执行流」直接打开该任务 Bot 的 DSH 会话查看完整执行过程。新建任务精简为标题/描述/验收标准/指派。评审/验收/编辑/一键派发等能力保留在模型工具与 HTTP action 中。
-14. **UI 美化（v0.5.5）**：统一字体/间距/圆角与配色；侧栏与右栏浅灰分层、群选中态淡蓝高亮、按钮白底细边+悬浮反馈、消息气泡圆角卡片、输入框/弹窗/滚动条统一。
-15. **Bot 弹窗重构 + 单文件人格（v0.5.6）**：新建/编辑 Bot 改为分组表单、等宽栅格、粘性头尾与单一 `BOT.md` 编辑器（插入模板 / 字数 / 下一轮生效提示）；旧 `SOUL.md`+`AGENT.md` 自动合并读取，保存时写为 `BOT.md`。
-16. **全能力 Bot（v0.5.7）**：去掉「角色与权限」字段与执行型开关；所有 Bot 统一挂载 `bot-team-tools`、workspace-write，可直接读写文件、搜索、联网、执行命令。旧 talk/review Bot 通过 schema v5 自动升级为全能力。
-17. **Bot 审批流（v0.5.8）**：默认审批策略 `ask`；Bot 需要越界/升权时，群时间线出现「审批请求」卡片，点「去审批」打开该 Bot 的 DSH 会话选择允许一次/拒绝，结果同步回群。`botApprovalPolicy: never` 可关闭。
-18. **Bot 头像（v0.5.9）**：默认按名称生成机器人面具，可点「随机生成」换配色/表情，或从 10 个本地 SVG 插画（星球/火箭/云朵/闪电/叶子/火焰/星星/月亮/海浪/花朵）中选一个，或上传自定义图片。消息、成员卡、Bot 库、@ 选择器、审批卡片统一显示。
-19. **群聊信息流（v0.6）**：微信/飞书式气泡与头像、同作者分组、今天/昨天时间分隔、悬停操作、引用回复与点击定位、复制、新消息分隔线与回到底部、加载历史保持滚动位置、群头部状态与「···」菜单、输入框 @ 选择器键盘操作；Bot 模型与 token 用量默认隐藏，悬停回复时显示。详见 `docs/v0.6-群聊信息流-变更记录.md`。
-20. **账号头像（v0.6）**：自己的消息优先显示 DSH 登录账号的头像和昵称；未登录、无头像或图片加载失败时回退渐变字母。
-21. **群头像（v0.6.1）**：新建/编辑群可随机配色、选 10 个 SVG 插画或上传自定义图片；群列表与聊天顶部同步显示。
-22. **深浅色主题（v0.6.2）**：跟随 DSH 的 light / dark / system；页面、气泡、面板和弹窗使用 `--bt-*` token，切换时即时生效，无需刷新。
-23. **人格模板库（v0.6.3）**：`插入模板` 改为模板菜单，内置 9 套人格（通用助手 / 代码实现 / 代码评审 / 需求分析 / 技术调研 / 测试 / 文档 / 批判质疑 / 数据分析），每套带一句话说明；空内容直接填入，已有内容追加，末尾是旧模板时自动替换；Esc 或点空白关闭。详见 `docs/v0.6.3-人格模板库-变更记录.md`。
-24. **消息右键菜单（v0.6.4）**：在消息上点右键弹出操作菜单——回复 / 复制文本 / 复制为引用（Markdown 引用块）/ 定位原消息 / 评审 / 让作者修改 / 重试；位置跟随光标并自动避开视口边缘，方向键切换、Esc 或点空白关闭；选中文字或右键链接时保留浏览器原生菜单。详见 `docs/v0.6.4-消息右键菜单-变更记录.md`。
-25. **左侧群栏收起（v0.6.5）**：左侧栏头部新增「收起侧栏」按钮，264px 收到 68px 后只显示群头像与图标按钮（群名/时间/预览隐藏，悬停显示群名与最后消息），消息区获得更多宽度；底部 Bot 管理/设置变为图标，键盘可达；偏好存浏览器 `localStorage`，刷新与切走再回来保持。详见 `docs/v0.6.5-侧栏收起-变更记录.md`。
-26. **单聊 + 群聊分组 + 右侧面板收起（v0.7）**：每个 Bot 自动拥有一个单聊（创建 Bot 后直接打开，侧栏「单聊」区固定在群聊上方）；单聊无需 @，复用完整的时间线/流式/停止/导出与独立会话记忆。群聊可放进自定义分组、分组与群都支持拖动/菜单自定义排序；「单聊」「群聊」「未分组」和每个自定义分组都能展开/收起（状态存浏览器）。聊天右上角的右侧面板按钮和面板头的「»」都能收起/展开成员/任务/单聊信息面板，偏好同样存浏览器。详见 `docs/v0.7-单聊与分组-变更记录.md`。
-27. **设置 / 关于（v0.7）**：左侧栏「设置」弹窗改为模块导航（消息设置 / 关于）；原有显示设置整体移入「消息设置」，「关于」显示插件说明、版本号、包名、开发者与数据位置；版本/包名/开发者由 Host 读取 `package.json` 下发。
-28. **插件改名与数据目录（v0.8）**：包名与 Client 模块 id 统一为 `dsh-bot-team`，bundle 行仍为 `bot-team`；插件数据根目录迁到 `$DSH_HOME/dsh-bot-team/`，首次启动自动迁移旧 `$DSH_HOME/bot-team/`。
-29. **单聊目录分层（v0.8.1）**：单聊工作目录改为 `<dataDir>/direct/<botId>/`，与群聊的 `groups/<groupId>/` 分层；启动迁移自动折叠 v0.8.0 的 `<dataDir>/<botId>/`。
-30. **输入框 + 命令菜单与 Skill（v1.1）**：左下角 **+** 改为与 DSH 一致的全宽分组命令菜单（「添加」/「指令」，图标 + 中文名 + 英文别名 + 右侧说明，↑↓/Tab/Enter/Esc 操作）。**文件** 把本地文件存入 DSH 附件库（Bot 拿到只读路径，消息气泡显示附件卡）；**技能** 打开 Skill 选择器；群聊还可 **提及成员**；**指令** 组提供停止回复、导出 Markdown/HTML 与消息设置。输入框直接键入 `/` 也会打开 Skill 选择器。Bot 预设新增 `skill-filesystem` + `tool-skill`，选中的 `/skill-name` 由 DSH 原生 gesture 在当前轮注入完整 Skill 指令。详见 `../docs/输入框文件与Skill-变更记录.md`。
-31. **回复自动 @（v1.1）**：群聊信息流里回复 Bot 消息时，输入框自动带上该 Bot 的 `@` 并加入显式 mention；切换回复对象会替换上一个自动 @（只动自动插入的前缀，不改用户正文），单聊和回复人类消息不插入。这样回复不会因为缺少 `@` 而没有 Bot 回应。
-32. **中英双语（v1.1）**：界面跟随 DSH 的 **设置 → General → Language** 即时切换 zh/en；按钮、菜单、弹窗、空态、提示与宿主生成的讨论/评审/审批事件消息都会翻译，Bot 消息、群名、Bot 名、人格正文等用户内容保持原文。实现走 DSH 的 `ctx.locale` 服务（注册 `botTeam` 字典 + 渲染时查表），内容值按子树加保护，避免把名为「设置」的群错误翻译。
-33. **导出 PDF（v1.1）**：群聊「···」菜单与输入框「指令」菜单新增「导出 PDF」；Host 用系统 CJK 字体 + `fontkit` 子集生成 PDF 1.7（文本可选中/搜索、A4 分页、页眉页脚页码），无需浏览器打印对话框。字体自动发现（macOS Hiragino Sans GB / Arial Unicode，Windows 微软雅黑/宋体，Linux 文泉驿等；无嵌入许可的字体自动跳过）；可用 `pdfFontPath` 指定。详见 `../docs/v1.1-i18n与PDF-变更记录.md`。
-
-
-## 设置（消息设置 / 关于）
-
-左侧栏底部 **Bot 管理** 旁的 **设置** 打开 Bot Team 设置，无需先选择群。弹窗改为左侧模块导航 + 右侧内容，模块为 **消息设置** 和 **关于**；导航支持 ↑/↓/Home/End 切换，选中项有高亮和焦点环。
-
-**消息设置**（原有显示设置整体移入这里）：
-
-- **模型名称 / 输入 Token / 输出 Token / 平均回复速度** 可各自选择 **悬停显示 / 常驻显示 / 隐藏**，默认全部悬停显示。
-- 悬停模式也支持消息内部的键盘焦点；无悬停能力的触屏设备自动显示。隐藏模式完全移除对应字段，不影响正文、轮次、评审、停止/错误状态。
-- 弹窗提供即时示例预览、恢复默认、取消和保存。只有 **保存设置** 会应用到所有群聊；保存失败时保留草稿并显示错误。
-- 偏好存于当前 DSH 配置的 storage domain `bot_team` → `meta` → `chat-display-settings`，不依赖浏览器端口，刷新、切换群和重启后保留。有群 SSE 连接的其他页面也会同步设置；重连时通过 `hello` 获取最新值。
-- Token 沿用最近一次模型上报的用量，**不是本轮多次模型调用的累计量**；缺失数据不伪装成 0。
-- 速度为最近一次成功模型请求的输出 Token / 耗时，显示 `tok/s`。Host 用单调时钟测量请求流开始到响应提交，并验证同一 attempt 的结束帧；包含请求等待、思考、网络与本地提交开销，不包含排队、Agent 初始化、工具/审批等待或重试退避，**不是纯解码速度**。缺少计时/用量的历史消息、未完成/失败/停止的回复不显示速度，不按消息时间戳补算。
-
-**关于**：
-
-- 插件说明和功能特性（单聊自动创建、群聊分组与拖拽排序、展开/收起、BOT.md 人格、任务与评审）。
-- **版本号 / 包名 / 开发者** 来自插件 `package.json`，由 Host bootstrap 的 `plugin` 字段下发；当前为 `1.1.0` / `dsh-bot-team` / `shper`。
-- 数据与人格文件位置：`$DSH_HOME/storages/bot_team`、`$DSH_HOME/dsh-bot-team/bots/<botId>/BOT.md`；单聊 / 群聊工作目录在 `$DSH_HOME/dsh-bot-team/direct/<botId>/` 与 `$DSH_HOME/dsh-bot-team/groups/<groupId>/`。
-
-![设置 · 消息设置](<../docs/assets/v0.7-settings-light.png>)
-
-![设置 · 关于（深色）](<../docs/assets/v0.7-settings-about-dark.png>)
-
-更新涉及 Host 和 Client：重新启用插件（或重启 DSH），然后刷新现有 GUI 页面。普通浏览器刷新不能单独加载新的 Host 模块。**v0.8 改名例外：profile 的 bundle 名已从 `@local/bot-team` 换成 `dsh-bot-team`，必须完整重启 DSH；只做 disable→enable 或刷新页面会找不到旧模块。**
-
-## 数据与配置
-
-`cordis.patch.yml` 的 `config`：
+| Bot | `ctx.agents.create/resume` 创建真实 Agent 与持久 Session；`meta.origin='subagent'` 让它不出现在侧栏 |
+| 群消息 | 群消息转成 `UserMessage` 走 `agent.followup()`；`session/event` 与 `agent/assistant-stream` 驱动消息与流式 |
+| 人格 | `ctx.systemPrompt.section/context`（agent 作用域）注入 `BOT.md` 与群上下文 |
+| 工具 | `ctx.agentPresets.mount` 挂载「全能力」preset；`ctx.tools.restrict` 防止 Bot 递归调用 Team 工具 |
+| 数据 | storage domain 内部标识 `bot_team`，实际目录 `storages/dsh-bot-team`（群 / 单聊 / 分组 / Bot / 成员 / 消息 / 讨论 / 任务），不写会话日志 |
+| 页面 | 单文件 `client.js` 通过 `window.__ModuleLoader__.load` 注册到 `main` 与 `sidebar.panellist` 槽位 |
+| 通道 | `/api/bot-team.*`（bootstrap / messages / events(SSE) / action / file / health），全部在登录态栅栏内 |
+
+> 升级 DSH 后按 [升级检查清单](https://github.com/shper/dsh-bot-team/blob/main/docs/%E5%8D%87%E7%BA%A7%E6%A3%80%E6%9F%A5%E6%B8%85%E5%8D%95.md) 逐项验证。
+
+## 配置
+
+`cordis.patch.yml` 的 `config` 可在 profile 的 patch 层覆盖：
 
 | 字段 | 默认 | 说明 |
 |---|---|---|
 | `dataDir` | `$DSH_HOME/dsh-bot-team` | 插件数据根目录（人格与工作目录） |
-| `botsDir` | `<dataDir>/bots` | BOT.md（兼容旧 SOUL.md/AGENT.md）存放目录 |
-| `defaultCwd` | Host 进程 cwd | 旧记录没有 `workspaceCwd` 时的兜底；新建群/单聊不再使用 |
-| `migrateLegacyLayout` | true | 首次启动迁移 `$DSH_HOME/bot-team` 旧布局 |
+| `botsDir` | `<dataDir>/bots` | `BOT.md` 存放目录 |
 | `maxParallelTurns` | 3 | 群级并行回复上限 |
 | `maxContextMessages` | 40 | 单轮注入的历史消息上限 |
-| `turnTimeoutMs` | 300000 | 单轮超时 |
-| `smokeTest` | false | 激活时跑端到端冒烟/恢复检查（仅验证用；已关闭） |
 | `enableModelTools` | true | 是否向普通会话暴露 `bot_team_*` 工具 |
-| `toolWaitTimeoutMs` | 180000 | 模型工具等待 Bot 回复/讨论的默认超时 |
-| `maxTurnsPerHour` | 120 | 每群每小时 Bot 回复轮数上限 |
 | `dailyTokenBudget` | 5000000 | 每群每日 token 上限 |
-| `botSandbox` | true | 是否把 Bot session 显式设为 `workspace-write` 沙箱 |
-| `botApprovalPolicy` | ask | `ask`：越界/升权时在群时间线出现审批卡片，去 Bot 会话完成授权；`never`：无头模式，直接拒绝所有需审批操作 |
-| `pdfFontPath` | 空 | 可选：指定 PDF 导出的 CJK TrueType/TTC 字体文件；空则按平台自动发现 |
+| `botSandbox` | true | Bot session 是否显式设为 `workspace-write` |
+| `botApprovalPolicy` | ask | `ask`：越界时在群里出现审批卡片；`never`：无头模式直接拒绝 |
 
-HTTP 通道（全部在 `/api` 登录态栅栏内）：
+Bot 回复不再按小时限制轮数，旧配置中的小时轮数上限会被忽略。每群每日 token 预算仍由 `dailyTokenBudget` 控制，按 Host 本地时间零点重置；并行上限、单 Bot 串行及讨论轮数等调度规则保持不变。
 
-- `GET /api/bot-team.bootstrap`
-- `GET /api/bot-team.messages?groupId=…`
-- `GET /api/bot-team.events?groupId=…`（SSE）
-- `POST /api/bot-team.action`（`group.create` / `group.reorder` / `folder.create` / `folder.update` / `folder.delete` / `folder.reorder` / `direct.open` / `bot.create` / `member.add` / `message.post` / `message.stop` / `persona.write` / `settings.chatDisplay.update` …）
-- `GET|PUT /api/bot-team.file`（`kind=bot`；兼容 `soul` / `agent`）
-- `POST /api/bot-team.upload?name=…&groupId=…`（原始字节；返回 `attachmentId` / `name` / `bytes`）
-- `GET /api/bot-team.skills?groupId=…&memberId=…`（当前工作区中 `userInvocable` 的 Skill；首次调用会准备一个 Bot 会话读取其工作区）
-- `GET /api/bot-team.export.pdf?groupId=…&lang=zh|en`（返回 PDF，`Content-Disposition` 下载；无 CJK 字体时 501）
+完整字段、HTTP action 与工具参数见 [插件配置与接口](https://github.com/shper/dsh-bot-team/blob/main/docs/%E9%85%8D%E7%BD%AE%E4%B8%8E%E6%8E%A5%E5%8F%A3.md)。
 
-## 安装
+## 数据与隐私
 
-这是一个标准 DSH bundle：`package.json` 的 `dsh.bundle.patch` 指向 `cordis.patch.yml`，`dsh.client` + `exports["./client"]` 提供 Web 端界面，`exports["./locale/*.json"]` / `exports["./icon"]` 提供插件管理页的标题、描述与图标。npm 包名：`dsh-bot-team`。
+| 路径 | 内容 |
+|---|---|
+| `$DSH_HOME/storages/dsh-bot-team/` | 群、单聊、分组、Bot、成员、消息、任务、讨论 |
+| `$DSH_HOME/dsh-bot-team/bots/<botId>/BOT.md` | 人格与工作规范 |
+| `$DSH_HOME/dsh-bot-team/groups/<groupId>/` | 群聊工作目录 |
+| `$DSH_HOME/dsh-bot-team/direct/<botId>/` | 单聊工作目录 |
 
-**桌面版（当前 GUI）**：左侧栏 **插件 / Plugins** 页 → 添加插件，填 `dsh-bot-team@<版本>`（或本地绝对路径、Git 地址）；装好后对 `bot-team` 行 disable → enable，或完整重启 DSH；浏览器刷新页面。
+- 启动时自动把旧的 `storages/bot_team/` 实体目录迁到 `storages/dsh-bot-team/`，旧路径保留为兼容目录链接；已有记录和后续写入均位于新目录。使用自定义 JSON 存储根目录时，在该根目录下做同样迁移。
+- 插件不向任何第三方服务上传数据；Bot 的模型请求走你在 DSH 里配置的 provider。
+- Bot 默认拥有 `workspace-write` 的文件与命令能力，范围受工作目录限制。把它们指向敏感目录之前，请先确认这是你想要的。
 
-**CLI / 其他 profile**：
+## 仓库结构
 
-```sh
-dsh plugin --profile <profile> add dsh-bot-team@1.1.0
+```
+host/              服务、存储、Agent 与协作逻辑
+locale/            中英文本
+test/              回归测试与测试辅助
+docs/              使用、接口、发布与升级文档
+  assets/          文档使用的截图
+index.js           Host 入口
+client.js          Web 客户端
+cordis.patch.yml   插件与 Bot 工具预设
+package.json       包元数据、依赖与验证命令
+README.md          项目入口与开发说明
+CHANGELOG.md       各版本修改记录
+LICENSE            MIT 许可证
 ```
 
-> `1.1.0` 是当前源码版本；若 npm 上尚未发布，请用本地目录或 Git 地址安装（发布见 `../docs/发布指南.md`）。
+仓库根目录同时是 npm 包根目录；开发、测试与打包命令均在这里运行。安装已有源码时直接选择包含 `package.json` 的仓库目录。
 
-该命令安装包，并把新 bundle 追加到 profile 的 `dsh.profile.bundles`。升级用 remove → add；桌面版插件页在提供 **Update** 时可直接更新，否则也是移除后重装。装完必须重新加载 Host 模块：只刷新页面不会加载新的 Host 代码。
+## 开发
+
+宿主侧是普通 ESM，不 import 任何 `@deepseek-ai/*` 包；客户端是单文件 `client.js`，React 来自平台模块表。PDF 导出用 `fontkit` 读取并子集化系统 CJK 字体（唯一运行时依赖）；其余测试不依赖第三方包、不调用真实模型、不访问个人数据。
 
-**Git 直装**（不经过 npm）：
+在仓库根目录运行：
 
 ```sh
-git+https://github.com/shper/dsh-bot-team.git#<40 位 commit>&path:/bot-team
+npm install          # 安装唯一运行时依赖 fontkit（PDF 字体子集）
+npm run check        # node --check：index.js / client.js / host/*.js
+npm test             # 隔离回归测试；部分 PDF 用例按系统字体条件运行或跳过
+npm pack --dry-run   # 查看真正会被发布的文件
 ```
 
-**兼容性**：`engines.dsh` 为 `^0.2.1-rc.3`，安装前按运行中的 DSH 版本校验（含预发布版本）；DSH 升级到 0.3 后需先回归、再放宽 range 并发新版本。被拦时可用 exact-version exemption，但会提示风险。
+发布前自检，以及 npm / Git / 插件市场索引三条发布路线见 [https://github.com/shper/dsh-bot-team/blob/main/docs/%E5%8F%91%E5%B8%83%E6%8C%87%E5%8D%97.md](docs/发布指南.md)。
 
-发布流程（npm / Git / 插件市场索引、检查清单与已知风险）见 [docs/发布指南.md](https://github.com/shper/dsh-bot-team/blob/main/docs/%E5%8F%91%E5%B8%83%E6%8C%87%E5%8D%97.md)。
+## 已知限制
 
-## 开发
+- 分组只有一层；展开 / 收起是浏览器本地偏好，不跨设备同步；
+- 同一群只允许一个未结束的讨论或辩论；`paused` 仍占用该位置，阻止新流程、`/new` 和切换项目。停止后若原生执行尚忙，会保留 `stopping`，需要等待并重新检查；
+- 讨论视角、正反方和裁判是临时提示，仍复用成员的原会话；不保证角色或立场之间的记忆隔离；
+- 任务队列是 Engine 内存态，重启后排队标记丢失（任务仍为进行中）；
+- Markdown 渲染较轻量：无语法高亮，图片未支持；
+- PDF 使用系统 CJK 字体（macOS 优先 Hiragino Sans GB / Arial Unicode（宋体等无嵌入许可的字体自动跳过）；Windows/Linux 用常见中文字体）；没有 CJK 字体时导出返回 501，可用 `pdfFontPath` 指定字体文件；PDF 为轻量排版（无图片/头像、链接不可点击、emoji 可能缺字），正文文本可选中与搜索；
+- 语言只覆盖界面与宿主事件消息；Bot 的回复、群名/Bot 名、人格模板正文、部分宿主错误仍按原语言显示；
+- Bot 的操作边界由群/单聊工作目录、`botSandbox` 与审批策略共同约束。
 
-宿主侧是普通 ESM（`index.js` + `host/*.js`，不 import 任何 `@deepseek-ai/*` 包）；客户端是单文件 `client.js`（`window.__ModuleLoader__.load` 工厂，React 来自平台模块表）。
+## 文档
 
-安装/更新：`plugin_manager install_bundle` 之后，改代码需对 `bot-team` 行 `disable → enable`（或重启 DSH）才会加载新的 Host 模块；v0.8 改名后旧行名失效，必须完整重启 DSH。
+- [版本变更记录](CHANGELOG.md)
+- [完整功能、HTTP 通道与配置](https://github.com/shper/dsh-bot-team/blob/main/docs/%E9%85%8D%E7%BD%AE%E4%B8%8E%E6%8E%A5%E5%8F%A3.md)
+- [使用指南](https://github.com/shper/dsh-bot-team/blob/main/docs/%E4%BD%BF%E7%94%A8%E6%8C%87%E5%8D%97.md)
+- [讨论与辩论：流程、工具、API 与恢复边界](<https://github.com/shper/dsh-bot-team/blob/main/docs/%E8%AE%A8%E8%AE%BA%E4%B8%8E%E8%BE%A9%E8%AE%BA.md>)（1.3.0 源码版本）
+- [发布指南](https://github.com/shper/dsh-bot-team/blob/main/docs/%E5%8F%91%E5%B8%83%E6%8C%87%E5%8D%97.md)
+- [升级检查清单](https://github.com/shper/dsh-bot-team/blob/main/docs/%E5%8D%87%E7%BA%A7%E6%A3%80%E6%9F%A5%E6%B8%85%E5%8D%95.md)
+- [消息执行过程](https://github.com/shper/dsh-bot-team/blob/main/docs/%E6%B6%88%E6%81%AF%E6%89%A7%E8%A1%8C%E8%BF%87%E7%A8%8B.md)
+- [后台会话与完整日志](https://github.com/shper/dsh-bot-team/blob/main/docs/%E5%8E%9F%E7%94%9F%E4%BC%9A%E8%AF%9D%E4%B8%8E%E5%AE%8C%E6%95%B4%E6%97%A5%E5%BF%97.md)
+- [新建会话：数据模型与接口](https://github.com/shper/dsh-bot-team/blob/main/docs/%E6%96%B0%E5%BB%BA%E4%BC%9A%E8%AF%9D.md)
 
-发布前自检（在 `bot-team/` 目录）：
+当前源码版本为 `1.3.0`；各版本修改见 [CHANGELOG](CHANGELOG.md)，详细提交与历史验收记录可通过 Git 历史查阅。临时预览、调研副本和一次性工具不纳入维护目录。
 
-```sh
-npm install            # 安装唯一运行时依赖 fontkit（PDF 字体子集）
-npm run check          # node --check：index.js / client.js / host/*.js
-npm test               # 134 条隔离回归测试（133 通过 + 1 条按字体条件跳过）
-npm pack --dry-run     # 查看真正会被发布的文件
-```
+## License
+
+MIT © [shper](https://github.com/shper)
 
-`npm publish` 会通过 `prepublishOnly` 自动跑 `check` + `test`。
+## English
 
-### 隔离回归测试
+**Bot Team** is a DeepSeek Harness plugin for long-lived agent colleagues. Every bot is a real DSH agent with its own persistent session, model, `BOT.md` persona and full toolset (files, search, web, commands inside a `workspace-write` sandbox). Each bot gets a direct chat; groups support `@mention` dispatch, parallel streaming replies, peer review and multi-round discussions. Task tools and HTTP APIs support priorities, dependencies, review/acceptance and a dispatch queue; the group sidebar task panel and its creation entry have been removed. Data lives in the `bot_team` storage domain and `$DSH_HOME/dsh-bot-team/`; group conversations never pollute session logs.
 
-在工作区根目录运行（无需第三方依赖，不调用真实模型、不访问个人历史/凭据）：
+Source version **1.3.0** adds structured discussions, 1v1 debates with an optional independent judge, and pause/resume/retry/finish/stop/context controls. Existing discuss tool calls still default to classic two-round discussions. Reload the local plugin Host with disable → enable, then refresh the page; see the [discussion and debate guide](<https://github.com/shper/dsh-bot-team/blob/main/docs/%E8%AE%A8%E8%AE%BA%E4%B8%8E%E8%BE%A9%E8%AE%BA.md>).
+
+Version **1.2.1** fixes execution history loading and live token totals. **Open full session** now opens a separate read-only history page with an explicit return button; returning preserves the original execution entry, chat draft and scroll position. Member and sidebar session entries use the same history reader, including saved sessions from earlier replies. The hourly reply limit has been removed; daily token budgets remain in effect.
 
 ```sh
-node --test bot-team/test/*.test.js
-node --check bot-team/client.js
+# Desktop: Plugins → Add plugin → dsh-bot-team@1.3.0, then reload
+dsh plugin --profile <profile> add dsh-bot-team@1.3.0
 ```
 
-覆盖设置校验、持久化/失败处理、重启读取、HTTP/SSE 同步、设置弹窗模块（消息设置 / 关于）与插件元数据、全部 81 种字段模式组合、弹窗保存/取消/重试、流式气泡回归、消息右键菜单（动作生成/禁用态/引用复制/视口定位/菜单渲染/页面集成）、左侧群栏收起/展开（图标模式/键盘/localStorage 降级）、单聊与分组的侧栏模型/折叠/拖放计算/右侧面板折叠/旧 Host 降级、Host 侧单聊自动创建与 @ 语义/分组 CRUD/排序/schema v6 迁移、真实 Service 启动/路由/工具注册、DSH 风格 + 命令菜单与文件/Skill 选择器（分组结构、触发串、模糊排序、大小格式化、附件卡片渲染）、附件上传/引用归一化/消息持久化/Bot prompt 只读路径/Skill 按 agent scope 过滤、英文界面与内容保护（字典完整性/占位符/系统消息/语言切换）、PDF 字体子集/分页/ToUnicode/路由，以及最新请求速度的重试/工具/中断边界。Client 测试使用 VM 与轻量 React stub，验证组件结构与事件逻辑，不替代真实浏览器的布局、焦点和深浅色视觉验收。
-
-## 已知限制
+`1.3.0` is the current source version; these npm installation examples apply once that version is published. Use a local directory to install the source before publication.
 
-- Markdown 为轻量渲染（无语法高亮；已支持表格/删除线，图片未支持）。
-- 讨论仅固定轮次（无 AI 主持人、同一群同时只允许一个讨论）。
-- 讨论中的单条消息不支持重试（请重新发起讨论）。
-- 审批默认 `ask`：Bot 越界/升权时会在群时间线出现「审批请求」卡片，点「去审批」打开该 Bot 的 DSH 会话选择「允许一次 / 拒绝」；无人处理时会等到本轮超时。`botApprovalPolicy: never` 可切回严格的自动拒绝模式。
-- Bot 的操作边界由群/单聊工作目录、`botSandbox` 与审批策略共同约束。
-- 语言只覆盖界面与宿主事件消息；Bot 回复、群名/Bot 名、人格模板正文与部分宿主错误保持原语言。
-- PDF 依赖系统 CJK 字体；无字体时返回 501（可用 `pdfFontPath` 指定）。PDF 为轻量排版：无图片/头像、链接不可点击、emoji 可能缺字；正文可选中/搜索。
-
-- 导出 HTML 为轻量 Markdown 转换（无表格/图片）。
-- 任务板：优先级只影响排序/展示（不抢占调度）；依赖仅支持「全部 accepted」；无任务删除/排期/工时。
-- 队列为 Engine 内存态（重启后排队标记丢失，任务仍 in_progress）；一键派发无独立持久队列。
-- 任务面板 UI 只暴露「派发 / 中断 / 执行流」；评审/验收/编辑/一键派发需通过模型工具或 HTTP action。
-- 单聊固定一对一（一个 Bot），不能加成员、不能删除；删除 Bot 时会连同单聊与单聊消息一起删除。单聊不参与模型工具 `bot_team_list`，也不会进入群聊分组；评审、讨论、任务板等群聊专属流程在单聊中禁用（Host 拒绝）。
-- 分组只支持一层（不能嵌套）；分组删除后群会回到「未分组」，不会被删除。
-- 分组/群的自定义排序保存在 Host；「展开/收起」是浏览器本地偏好，不跟随账号同步。
-- 左侧栏收起为图标栏时不显示分组标题，只按单聊 → 群聊的顺序展示头像与分隔线。
-- 右侧面板的展开/收起是浏览器本地偏好；`≤1100px` 时右侧面板本来就自动隐藏，右上角的切换按钮也一并隐藏。没有选中会话时（右侧显示 Bot 库）不提供收起。
-- v0.7 同时改了 Host：升级后必须重新加载 Host 模块（disable→enable 或重启 DSH）再刷新页面；只刷新页面会看到「Host 仍是旧版本」提示。
-- 输入框附件是**通用文件**：单文件 ≤32 MB、每条消息 ≤10 个；图片/二进制不会作为视觉输入送给模型，Bot 只能通过只读路径读取。附件存入 `$DSH_HOME/attachments/v1`，不随消息或群删除，也不会自动回收。
-- Skill 选择器读取的是 Bot 工作区的 `userInvocable` Skill；首次打开会准备一个 Bot 会话，可能稍慢。Host 未重新加载时，Bot 预设还没有 `skill-filesystem` / `tool-skill`，`/skill-name` 不会加载对应指令。
-- 本次同时改了 Host 路由（`upload` / `skills`）与 Bot 预设：建议**完整重启 DSH** 让 bundle patch 重新应用，再刷新页面；只 disable→enable 插件不保证刷新预设。
-- **v1.1 升级提示**：新增 `/api/bot-team.export.pdf` 路由与 `fontkit` 依赖，必须重新加载 Host（disable→enable 或重启 DSH）再刷新页面；从源码 link 安装时先在 `bot-team/` 执行 `npm install`。
-
-## 下一阶段
-
-v1.1 已完成 M5 的「完整 i18n（zh/en）」与「导出 PDF」；剩余：可选的 per-Bot 权限分级（只读 / 全能力）、多进程配额账本、持久任务队列 / 优先级抢占、PDF 图片与可点击链接。
+Requires DSH `0.2.1-rc.x`. The UI follows DSH's zh/en language setting, and group timelines export to Markdown, HTML, or a paginated PDF with selectable text. MIT licensed.