personal-bot 0.2.3 → 0.2.5

package/docs/file-storage.md

@@ -9,11 +9,13 @@
 | 工作区 .pi/settings.json、.pi/mcp.json | Pi 原生项目配置 |
 | Pi 原生 sessions/ 或原生配置指定的目录 | 主会话与子会话的 JSONL 对话，由 Pi 管理 |
 | 当前 Pi agent dir 的 pbot/subagents/ | Personal Bot 子进程控制记录与原生会话引用 |
-| 当前 Pi agent dir 的 pbot/teams/ | 团队资料、批次与公共原文 |
-| 工作区 .pi/pbot/history/ | 问答原文、摘要、节点关系与来源引用；可随工作区分享 |
+| 当前 Pi agent dir 的 pbot/teams/ | Pi 团队资料、批次与公共原文 |
+| dsh 原生会话存储 | dsh 主会话与专家的原生事件，由 dsh 管理 |
+| dsh home 的 pbot/subagents/、pbot/teams/ | dsh 专家控制记录、原生 ID 引用与团队公共记录 |
+| 工作区 .pi/pbot/history/、.dsh/pbot/history/ | 按来源保存的问答、摘要、节点关系；双方共同查询 |
 | 用户级 pbot/python/.venv | 共享 Python 环境 |
 
-Pi 管理主会话、子会话对话与配置。Personal Bot 的工作区资料是普通文件，没有私有启用状态或工作区格式版本。详细目录用途见[项目 README](../README.md#工作区资料)，Python 路径见 [Python 说明](../python/README.md)。
+各宿主管理自己的主会话、专家对话与原生配置，不跨宿主恢复或接管。Personal Bot 的工作区资料是普通文件，没有私有启用状态或工作区格式版本。详细目录用途见[项目 README](../README.zh-CN.md#工作区资料)，Python 路径见 [Python 说明](../python/README.md)。
 
 ## 资料准备
 
@@ -30,10 +32,11 @@ Pi 管理主会话、子会话对话与配置。Personal Bot 的工作区资料
 | inbox | 父侧消息 |
 | status | 子侧活动与接收标记 |
 | completions | 周期结果引用 |
-| session-ref.json | 原生会话文件的绝对路径；首次输入前为 null，不保存对话副本 |
+| session-ref.json | Pi 原生会话文件的绝对路径；首次输入前为 null，不保存对话副本 |
+| native-session.json | dsh 原生 Session ID；不把 ID 当成 Pi 文件路径 |
 | team-ready.json | 子入口当前 generation 的团队接入/工具就绪标记，不是存储版本 |
 
-父侧写控制记录，子侧写状态、会话引用和完成事件，交付收据进入父 Pi 会话。通信顺序与恢复规则见[专家协作](agent-collaboration.md)。
+父侧写控制记录，子侧写状态、会话引用和完成事件，交付收据进入所属宿主的父会话；只读页面不写入收据。通信顺序与恢复规则见[专家协作](agent-collaboration.md)。
 
 新 agent 以 agentId 作为原生 session ID，通过 `--session-id` 由 Pi 创建。默认文件位于当前 Pi agent dir 的 `sessions/<Pi 编码的 cwd>/<时间戳>_<sessionId>.jsonl`；遵循子进程的原生环境变量与 settings，不自行编码目录或生成文件名。父会话一次性的 `--session-dir` 参数不会自动传给子进程。
 
@@ -41,7 +44,9 @@ Pi 对没有用户或助手消息的会话延迟落盘。`session-ref.json` 初
 
 恢复已绑定会话使用 `--session <绝对路径>`，不根据最近会话或当前目录设置重新选择。文件缺失、非法记录、身份或 cwd 不匹配时拒绝恢复；引用已固定但输入尚未落盘的崩溃窗口也不创建空白替代。只有从未交付输入的待命会话可以重新由 Pi 创建。报告使用 Pi 原生解析器和内存树按固定叶节点只读提取，不写入或迁移 JSONL。
 
-atomic-json 校验完整对象，写入并同步临时文件后原子发布；拒绝目录别名、越界和特殊文件，createOnly 保证不覆盖已有目标。短控制操作使用目录锁。处理崩溃遗留锁前须停止相关 Pi 进程。
+dsh 先 flush 父会话，再创建专家并持久化空会话。公开 Session API 负责存储，pbot 只保存原生 ID。恢复前冷读核对宿主、工作区、父身份、原生身份和占用；清除旧 inbox 后只接纳新代次要求。报告定位到固定 `turn/end` 序号，后续轮次不改变原报告；冷读不启动 Agent。
+
+atomic-json 校验完整对象，写入并同步临时文件后原子发布；拒绝目录别名、越界和特殊文件，createOnly 保证不覆盖已有目标。短控制操作使用目录锁。处理崩溃遗留锁前须停止相关宿主执行实例。
 
 ## 团队保存
 
@@ -51,11 +56,11 @@ TeamFiles 与 AgentFiles 共用 subagents/.control 短目录锁。读改写在
 
 I/O 失败后当前文件实例停止后续写入，不能因下一次读取成功就重发。恢复时暂停团队；已领取但结果不明的请求保留未知事实，不重跑。仅有领取标记或未完成周期的子 reload 记录为 interrupted，不伪造成功。旧进程确认停止后，resume 在更换 generation 前也封存这些未知请求，避免新状态把它们误当作未领取。已完成但尚未公开的报告可补交付。
 
-关闭团队不删除消息或 agent。既有 descriptor、launch、inbox、status、completions 字段不变；新增引用文件不包含存储版本计数。团队与独立通知分别记录在父 Pi 原生分支；查看公共记录不是模型已读收据。
+关闭团队不删除消息或 agent。既有 descriptor、launch、inbox、status、completions 字段不变；新增引用文件不包含存储版本计数。团队与独立通知分别记录在父原生会话及相应分支；查看公共记录不是模型已读收据。
 
 ## 历史索引
 
-历史存档按原生 session ID 关联会话，保存在工作区 `.pi/pbot/history/`，包含问答文本、来源消息 ID、分支内的四叉摘要与父子关系，复用原子 JSON 写入。来源只记录原生会话 ID 和消息 ID，不保存文件路径；原始会话不可用时仍可查询已存档内容。复制到不同目录或机器后仍可读取，重新发现原生会话时复用原节点。加载时复制用户级旧目录中当前工作区缺少的记录，旧副本保留。已有工作区存档在加载时移除旧 file 字段，保留正文、摘要和节点关系。读取原生文件不迁移或重写历史，不另建工作区格式或版本计数。范围与查询见[历史对话](history.md)。
+历史存档按原生 session ID 关联会话，分别保存在工作区 `.pi/pbot/history/` 与 `.dsh/pbot/history/`，各自只写本来源，包含问答文本、来源消息 ID、分支内的四叉摘要与父子关系，复用原子 JSON 写入。来源只记录原生会话 ID 和消息 ID，不保存文件路径；原始会话不可用时仍可查询已存档内容。复制到不同目录或机器后仍可读取，重新发现原生会话时复用原节点。Pi 保留旧归档处理：复制用户级旧目录中当前工作区缺少的记录，旧副本保留，并在已有 Pi 归档中移除旧 file 字段；dsh 不执行该导入或清理。两种来源均保留正文、摘要和节点关系。读取原生文件不迁移或重写历史，不另建工作区格式或版本计数。范围与查询见[历史对话](history.md)。
 
 ## 历史与复制
 
@@ -63,4 +68,4 @@ I/O 失败后当前文件实例停止后续写入，不能因下一次读取成
 
 加载、资料准备和重载保留已有资料、历史记录及备份。扩展管理自己的子会话、历史存档与 Python 环境，不自动导入或转换其他应用数据。
 
-复制工作区前停止旧实例。包含 `.pi/pbot/history/` 的副本会带上问答与摘要，但不会转移用户级原生会话、运行进程、环境或认证；不支持多机同时写入同步目录。原子文件发布不保证外部操作恰好一次，相关验证范围见[验证](validation.md)。
+复制工作区前停止旧实例。包含两种 history 目录的副本会带上问答与摘要，但不会转移用户级原生会话、运行进程、环境或认证；不支持多机同时写入同步目录。原子文件发布不保证外部操作恰好一次，相关验证范围见[验证](validation.md)。

package/docs/history.md

@@ -1,40 +1,51 @@
 # 历史对话
 
-`/pbot history [关键词]` 查询当前工作区的 Pi 历史。留空列出最近会话，选择后可查看正文、父节点和子节点；正文查看器中的修改不保存。无需 `/name`。也可以直接请 agent 查找某件事，agent 使用 `pbot_history`。
+`pbot_history` 共同查询当前工作区的 Pi 与 dsh 问答归档。Pi 的人工入口为 `/pbot history [关键词]`；dsh 使用 `/pbot` 的历史页，或 `/pbot history {"action":"search",…}`。无需给会话命名。原生会话由所属宿主管理，不跨宿主接管或恢复。
 
 ## 查询
 
 | 操作 | 参数与行为 |
 | --- | --- |
-| search | query 是不区分大小写的连续文本，搜索问答原文和所有已生成摘要；省略 query 列会话。sessionId、from、to 限定会话和相交的时间范围，日期按 ISO 解析；offset/limit 分页，默认 20、最多 50 条 |
-| read | id 是搜索或导航返回的节点 ID；offset/limit 读取正文，默认 12000、最多 24000 个 UTF-16 单元；childrenOffset 分页子节点，每页 20 个 |
+| search | query 是不区分大小写的连续文本，搜索问答原文和已生成摘要；省略 query 列会话。host 可选 pi/dsh，sessionId、from、to 限定会话与相交时间范围，日期按 ISO 解析；offset/limit 分页，默认 20、最多 50 条 |
+| read | id 是搜索或导航返回的节点 ID；host 指定来源。offset/limit 读取正文，默认 12000、最多 24000 个 UTF-16 单元；childrenOffset 分页子节点，每页 20 个 |
 
-返回的 nextOffset、nextChildrenOffset 非空时可继续读取。parents/children 提供节点 ID 与预览；共享前缀可能有多个父节点。source 给出原始 sessionId 和消息 entryIds，摘要的消息 ID 是覆盖范围的首尾。来源不保存文件路径；原始会话不可用时，已保存的问答仍可直接读取。ready=false 表示摘要尚未生成；completed=false 表示内容包含未完成的问答。
+返回的 nextOffset、nextChildrenOffset 非空时可继续读取。parents/children 提供来源、节点 ID 与预览；共享前缀可能有多个父节点。source 给出 host、原始 sessionId 和消息 entryIds，摘要的消息 ID 是覆盖范围的首尾。来源不保存文件路径；原生会话不可用时，已保存的问答仍可直接读取。ready=false 表示摘要尚未生成；completed=false 表示内容包含未完成的问答。
 
-查询不调用模型，不恢复会话或重放旧任务。摘要命中是检索线索，重要结论要展开到问答原文核对。全文搜索依赖词语重合，忘记原词时 agent 可以换几组词查询。不同层级的命中分别返回。
+查询只刷新当前宿主的原生索引，并读取另一来源的现成归档；不调用模型，不恢复会话或重放任务。跨来源 ID 发生歧义时必须指定 host。摘要命中是检索线索，重要结论仍要展开到问答原文核对。全文搜索依赖词语重合，忘记原词时可以换词查询。不同层级的命中分别返回。
 
-## 收录与整理
+## 原生收录
 
-加载、查询和交互结束时，通过 Pi SDK 发现当前工作区会话，读取当前会话目录、原生默认目录、当前会话以及该工作区受管子会话的原生引用，按 sessionId 关联已有存档。不在发现范围内的原生会话，可通过 Pi 打开对应会话并加载 pbot 重新关联。存档不保存目录或文件路径。不会导入其他宿主或旧版 pbot 私有会话布局。Pi 分配文件名后，到首条消息写入前，文件可以不存在；扫描静默跳过这类尚未落盘的会话。
+Pi 通过 SDK 读取当前会话目录、原生默认目录、当前会话，以及本工作区受管专家的原生引用，按 sessionId 关联已有归档。不在发现范围的会话可通过 Pi 打开并加载 pbot 重新关联。Pi 分配文件名后、首条消息落盘前，文件可以不存在；扫描静默跳过这种空会话。不会扫描旧版 pbot 私有会话布局。
 
-原生 JSONL 只读解析。用户输入到无工具调用的最终答复组成问答；回答前的补充输入保留在同一问答。工具调用、工具结果和推理不进入问答。中断或未答记录标为未完成。历史记录缺少完整交互边界时按原生消息顺序重建，不推测隐藏的操作结果。
+dsh 通过公开 SessionQuery 冷读本工作区根会话与按父关系关联的专家；专家 cwd 不同仍按父归属收录，同目录但属于其他工作区父会话的专家不混入。普通 fork 可以收录。读取不创建 Agent、不恢复会话、不修改原生记录，也不从私有请求日志推断对话。
 
-每条原生分支独立分组，每四个连续节点形成一个摘要，再逐层合并。共同前缀复用节点，摘要不会跨分支合并。会话根节点只做目录，不生成全局摘要；不足四个的尾部节点仍可查询。连续区间与渐进合并的设计参考 [pi-optchat](https://github.com/jonaslsaa/pi-optchat)，实现与提示词由 pbot 自行维护。
+用户输入到有效最终答复组成问答，回答前的人工补充输入保留在同一问答。dsh 的协调者委派输入也保留来源；通知和团队背景不会被当作新的用户问题。工具调用、工具结果和推理不进入问答。中断、截断、缺少正常结束或尚未回答的记录保留为未完成。dsh 必须有持久化的正常 stop 才能确认完成；工具文本和 idle 状态不代替最终回答。
 
-主交互正常结束后，在空闲阶段使用当时的 Pi 模型和原生认证串行生成摘要，也补齐已发现的历史。新输入、会话切换或关闭会取消工作；失败节点保留待处理状态，下次正常交互结束再试。加载和查询只收录原文，不启动摘要模型。原文先可查询，已有摘要在追加历史时复用。源文件缺失时继续使用工作区存档；权限、解析等其他读取错误会列出警告，已保存的内容仍可查询。
+完整工具、错误和审批记录留在原生会话。dsh 管理页的专家记录支持冷读、事件分页、正文与原始 JSON；history 不替代它。Pi 的原生 JSONL 同样只读解析，不改写或迁移。
 
-摘要有额外模型调用。超长输入分段概括后再合并，原文完整保留；摘要失败不妨碍原文查询。后台摘要用量目前不计入 Pi 主会话的用量统计。Pi 原生上下文、压缩和会话恢复继续由宿主管理。
+## 摘要与取消
 
-## 存储与实现
+每条分支独立分组，每四个连续节点形成一个摘要，再逐层合并。共同前缀复用节点，不跨分支汇总；会话根只做目录，不生成全局摘要。不足四个的尾部节点仍可查询。连续区间与渐进合并参考 [pi-optchat](https://github.com/jonaslsaa/pi-optchat)，实现与提示词由 pbot 维护。
 
-工作区内的 `.pi/pbot/history/<id>.json` 保存问答原文、来源消息 ID、节点关系和摘要。来源只保存原生 session ID 与消息 ID，不保存文件路径。目录本身确定工作区归属，不要求新机器的目录名与原机器一致。
+正常主交互结束后，在空闲阶段使用当前宿主选择的模型与原生认证，串行补齐本来源已发现的摘要。Pi 使用自己的交互结束事件；dsh 在同一工作区的所有已绑定父 Agent 空闲、无待输入时安排原生 LLM 调用，不创建额外 Agent 或主聊天消息。查询和页面重连只收录原文，不触发摘要。
 
-复制工作区时包含 `.pi/pbot/history/`，即可在另一台机器搜索和展开已有问答与摘要，继续补齐待生成摘要；原机器的 JSONL 路径不是查询前提。重新发现同一原生会话时复用原节点和摘要。这里分享的是已提取的问答与摘要，Pi 原生 `/resume` 仍需要对应 JSONL；工具日志和图片二进制不在这个存档内。
+新人工输入、下一模型步骤、所属资源关闭或 Pi 会话切换会取消当前整理。失败保留待处理内容与警告，下次正常交互结束再试。超长输入分段概括再合并，完整原文保留；摘要失败不妨碍原文查询。来源扫描错误与摘要错误分别保留，刷新成功不会掩盖尚未修复的摘要失败。
 
-加载时把当前 Pi agent dir 中旧 `pbot/history/` 下属于当前工作区、且尚未存在于新目录的记录复制过来，保留旧副本，不覆盖新存档。后续收录与摘要写入工作区目录。已有工作区存档在加载时移除旧 file 字段，保留问答、摘要及节点 ID；即使原始会话已不可用，也会完成字段清理。原生 JSONL 不改写，也不移动。
+摘要产生额外模型调用，不纳入主聊天的使用量承诺。原生上下文、压缩、模型路由和认证继续由宿主管理。真实摘要质量和实际请求取消仍需获准模型环境验收。
 
-这些文件是可共享的历史资料。原生 JSONL 可读时可以重新提取问答并生成摘要；原始文件已不可用时，删除工作区存档会失去这份历史。
+## 存储与并发
 
-服务位于 services/history，负责分组、查询和摘要队列；integrations/pi/history 负责原生发现、问答提取和模型调用；storage/history-files 复用原子 JSON 写入。命令与工具调用同一服务。首版全文扫描，不维护数据库或向量索引；不保证多个 Pi 进程同时整理同一工作区时只产生一次摘要调用。
+| 来源 | 工作区归档 | 写入者 |
+| --- | --- | --- |
+| Pi | `.pi/pbot/history/<id>.json` | Pi 收录与整理自己的原生会话 |
+| dsh | `.dsh/pbot/history/<id>.json` | dsh 收录与整理自己的原生会话 |
 
-本地测试覆盖原文保留、工具过滤、分支分组、全层搜索、分页与重载复用，以及空会话、旧目录复制、跨目录复制、旧路径清理、原始文件缺失和按会话 ID 重新关联。真实摘要质量、按大意回溯的成功率、大历史性能和完整人工浏览尚需验收，见[验证](validation.md)。
+归档保存问答文本、来源 ID、节点关系与摘要。Pi 既有节点 ID 保持不变；新 dsh 根节点带 `dsh-` 前缀。目录决定工作区与来源，不要求复制后的绝对路径相同。复制时包含两种归档即可查询现成内容；原生恢复仍需各宿主自己的会话数据，工具日志和附件二进制不在归档内。
+
+Pi 保留既有旧索引处理：将当前 Pi agent dir 中旧 `pbot/history/` 下属于本工作区且尚未存在的记录复制到工作区，保留旧副本，不覆盖新归档；移除已有 Pi 归档中的旧 file 字段时保留正文、摘要和节点 ID。失败的旧目录读取可在后续刷新重试。dsh 不导入这些旧 Pi 记录，也不清理或回写 Pi 归档。
+
+每个来源有独立的短写锁。原生扫描和模型调用在锁外进行，提交时重读最新归档；过时扫描不能覆盖后来保存的原文，过时摘要不能覆盖变更后的子节点或已提交摘要。一个来源损坏时，另一来源仍可查询并附带警告。不保证多个进程同时整理时只调用一次模型。
+
+服务位于 `services/history`，负责分组、查询、摘要队列与提交规则；`integrations/pi/history` 和 `integrations/dsh/history` 负责各自原生投影，`storage/history-files` 负责校验、短锁与原子文件发布。命令和工具调用同一服务。首版仍使用全文扫描，不增加数据库或向量索引。
+
+这些归档是用户历史资料。原生数据还在时可以重新提取；原生数据已不可用时，删除归档会失去这份历史。复制前停止原工作区的活动写入，不支持多机同时写同步目录。真实模型、长历史性能和平台验收边界见[验证](validation.md)。

package/docs/installation-design.md

@@ -0,0 +1,226 @@
+# npx 安装与升级设计
+
+本页的独立 `pbot setup` 面向 Pi。dsh 固定版使用原生 Web profile 与插件安装流程，见[dsh 使用说明](dsh.md)；不增加配置同步、安装登记或工作区升级机制。
+
+状态：方案已确认并实现。命令需使用包含该实现的发布包；当前源码可先执行 `npm run build:cli`，再运行 `node bin/pbot.mjs setup`。验证结果与剩余验收见[验证](validation.md)。
+
+目标是在 Linux 和 macOS 上，通过一个交互式入口安装或升级 Pi、为一个工作区安装 Personal Bot 和选定的配套插件，再启动 Pi 执行 `/pbot init`。这里的安装路径服务于 Pi 扩展；安装命令只负责环境准备和启动。
+
+## 命令与分发
+
+npm 包继续使用 `personal-bot`，增加名为 `pbot` 的可执行入口。npm 上的 `pbot` 已属于其他项目，包名与命令名无需一致。
+
+```bash
+npx personal-bot@latest setup
+npx personal-bot@latest setup --workspace ~/pbot-workspace
+```
+
+首次安装和后续升级使用同一个 `setup` 子命令。无子命令时显示帮助；`--workspace` 省略目录选择，但仍保留插件选择和安装计划确认。首版是终端交互流程，重定向输入时明确提示需要交互终端，不猜测选择或启动模型。
+
+需要长期使用短命令时，用户可另行安装：
+
+```bash
+npm install -g personal-bot@latest
+pbot setup
+```
+
+npx 不自动全局安装自身。全局安装只提供命令入口，不向 Pi 注册全局 pbot 扩展。`pbot setup` 使用全局安装的安装器版本；更新此入口使用 npm，或直接运行 `npx personal-bot@latest setup` 获取最新安装器。工作区中的 pbot 扩展与全局命令副本分别更新。
+
+首版只提供 `setup`、帮助和版本信息。以后按实际需求增加子命令。
+
+## 范围与所有者
+
+| 对象 | 范围与责任 |
+| --- | --- |
+| Node.js/npm | 运行 npx 的前提；最低 Node.js 22.19，目标软件有更高要求时提示先升级 |
+| Pi 主程序 | 当前用户共用一份；首次通过 npm 安装，已有安装沿用原生升级机制 |
+| pbot 扩展 | 所选工作区必装；已有自定义来源可选择保留 |
+| 配套插件 | 维护者提供候选清单，用户选择；安装到所选工作区 |
+| tmux | 独立专家与团队协作的强依赖；缺失时通过已有系统包管理器安装 |
+| 基础 Python | 检查 Python 3.11+、venv 和 ensurepip；缺失时提供指引 |
+| 共享 Python venv | pbot 加载时按现有逻辑准备，安装器不维护另一份环境 |
+| 工作区资料 | 启动 Pi 后交给 `/pbot init` 补建；已有内容按现有命令规则保留 |
+| 模型、认证、项目信任 | 使用 Pi 原生流程与已有配置 |
+| 插件依赖的外部服务 | 由插件自己的使用与配置流程处理 |
+
+安装器每次处理一个目录。目录选择支持当前目录、输入已有目录和创建新目录，不建立工作区列表、注册表、格式版本或启用标记。新目录可由安装器创建；其中的资料目录和资料文件由 pbot 创建。Pi 原生包管理仍可创建 `.pi/settings.json` 及其安装目录。
+
+升级共享 Pi 会影响其他工作区后续启动。更换 pbot 版本前遵循现有规则，停止活动子会话；安装器不代替用户强行终止任务。已有资料、历史记录、源码和备份保留。
+
+## 交互流程
+
+```mermaid
+flowchart TD
+    A[运行 setup] --> B[检查平台、Node/npm 和基础 Python]
+    B --> C[选择或创建工作区]
+    C --> D[读取原生安装状态与来源]
+    D --> E[选择插件与自定义来源的处理方式]
+    E --> F[展示安装计划并确认]
+    F --> G[补装 tmux，安装或升级 Pi]
+    G --> H[安装或升级工作区 pbot]
+    H --> I[逐项处理选中的配套插件]
+    I --> J[核对实际版本与安装结果]
+    J --> K[选择是否启动 Pi，默认启动]
+    K --> L[Pi 原生信任与扩展加载]
+    L --> M[执行 /pbot init，保留交互会话]
+```
+
+基础 Python 不满足要求时，在软件变更前说明缺项并结束本次 setup。tmux 安装、Pi 或 pbot 处理失败时，不继续启动 Pi。插件失败可继续处理其他插件，汇总后让用户选择是否先进入 Pi。
+
+安装计划展示工作区绝对路径、Pi 的真实路径和安装来源、当前版本、目标版本、选中的插件、保留的自定义来源，以及需要执行的系统软件安装。用户完成一次计划确认后执行所列操作；系统提权与 Pi 信任仍使用各自原生交互。若没有 Pi、但已有原生插件声明，安装器先展示 Pi 目标版本并确认安装 Pi，再使用其原生接口读取已有来源，继续插件选择和计划确认；不猜测 Git 缓存或把已有配置当作空白。
+
+执行结果分别说明已完成、保留、跳过和失败。退出安装阶段时不把“包安装成功”写成“模型、Python 计算或外部服务已可用”。
+
+## 插件清单
+
+pbot 本体作为固定必需项，不混入可选插件清单。首版候选为：
+
+| 插件 | 来源 | 首次安装默认值 | 安装后的边界 |
+| --- | --- | --- | --- |
+| Task Conductor | `npm:task-conductor-plugin` | 勾选 | 安装接入插件；服务、setup 和 MCP 接入另行完成 |
+| Pi Web Access | `npm:pi-web-access` | 勾选 | 安装搜索与内容获取插件；复用插件默认行为及已有配置 |
+
+维护者通过一份随包发布的静态清单调整候选项，位置为 `resources/installer/plugins.json`：
+
+```json
+[
+  {
+    "id": "task-conductor",
+    "label": "Task Conductor",
+    "description": "周期任务、流程和 DAG 的接入与使用引导",
+    "source": "npm:task-conductor-plugin",
+    "defaultSelected": true
+  },
+  {
+    "id": "web-access",
+    "label": "Pi Web Access",
+    "description": "网页搜索与内容获取",
+    "source": "npm:pi-web-access",
+    "defaultSelected": true
+  }
+]
+```
+
+清单只保存选择所需的元数据，不包含脚本、安装钩子、运行状态或插件专用执行逻辑。普通 npm Pi 插件只需增加清单项。安装器不提供插件市场、动态发现或用户维护清单的入口。
+
+首次安装 pbot 时，两项默认勾选。已有 pbot 时，按当前实际安装情况预选；后来新增的候选不会自动加入。取消勾选已安装插件表示本次不处理，不卸载也不禁用。移出维护者清单的插件不再由安装器安装或升级，已有副本保留。
+
+安装状态从 Pi 原生配置和实际包中取得，不另外持久化“安装器管理过哪些插件”。无法读取配置时报告错误，不当作全新工作区。
+
+## 版本、来源与作用域
+
+Pi、pbot 和选中的普通 npm 插件各自采用最新稳定版，不维护经过配套验证的固定版本组合。安装时显示当前版本和实际目标版本，结束后核对真正安装的版本。网络查询失败不能解释成“已经最新”；包版本可用也不证明整个组合已通过功能验收。
+
+| 已有状态 | setup 的行为 |
+| --- | --- |
+| 没有 Pi | 使用 npm 安装官方 `@earendil-works/pi-coding-agent`，核对可执行路径和版本 |
+| 已有持久安装的 Pi | 调用其原生 `pi update`；不支持自动更新时给出原安装方式的指引 |
+| 缺少工作区 pbot 或选中的插件 | 使用 Pi 原生本地安装 |
+| 普通 npm 来源 | 对所选工作区安装最新稳定版并核对结果 |
+| 本地源码、Git、固定版本或自定义版本范围 | 展示“保留”与“切换到 npm 最新稳定版”，默认保留 |
+| 清单外或本次未选中的插件 | 保持其原生声明，本次不安排升级或卸载 |
+| 配置损坏、来源无法辨认或存在未解决的重复加载 | 说明冲突，停止受影响项，不自动重置配置 |
+
+“保留”表示继续使用原有来源，不宣称它已升级到最新。选择切换后，只处理已明确选定的原声明与目标声明；保留源码目录和历史数据。不能在当前工作区内完成替换时，给出 Pi 原生操作指引，避免通过修改用户级声明影响其他工作区。
+
+所有插件变更显式限定所选工作区。Pi 1.5 的 `pi update <source>` 会同时匹配用户级和工作区配置，且不支持 `--local`，因此不直接用它实现本安装器的工作区插件升级。普通 npm 包通过以下形式交给 Pi 安装：
+
+```bash
+pi install --local npm:personal-bot@latest
+pi install --local npm:task-conductor-plugin@latest
+pi install --local npm:pi-web-access@latest
+```
+
+上述命令在所选工作区执行，并按实际选择逐项调用。`latest` 用于请求当前稳定标签，保留用户已有的资源过滤配置。首次用工作区声明覆盖同身份的全局 npm 包时，将原有资源过滤继承到工作区，全局声明保持不变。必要的来源切换使用原生设置机制，不重建整个 settings 文件。底层包管理器可能重新解析共享依赖，因此验收应检查已有声明与资源过滤保持正确，不能承诺安装目录中所有依赖文件完全不变。
+
+同一个 npm 包同时存在于用户级与工作区时，遵循 Pi 的原生覆盖规则，不更新用户级副本。本地源码、Git 与 npm 是不同身份，切换时必须核对有效加载来源，避免同时加载两份。
+
+安装器必须区分真实 Pi 安装与 npx 临时缓存内的可执行文件；后者不能作为已经安装了持久 Pi 的证据。npm 全局目录不可写或 PATH 无法解析目标程序时，显示明确修复指引，不隐式迁移已有安装或覆盖无关命令。
+
+## 系统依赖
+
+tmux 存在且可执行时直接复用；缺失时使用机器已有的受支持包管理器。系统包版本遵循发行版仓库，不由 pbot 维护另一套 tmux 版本。
+
+| 平台 | 自动补装渠道 |
+| --- | --- |
+| macOS | 已安装的 Homebrew |
+| Linux | 显式适配的 apt、dnf、pacman、zypper、apk |
+
+适配器只执行安装 tmux 所需的命令；不安装包管理器、不添加软件源、不顺带升级系统。需要权限时交给终端原生提权。不存在支持的包管理器或安装失败时，保留已完成步骤，提示手动完成后重跑 setup。
+
+Python 检查沿用 pbot 的解释器选择方式：优先 PATH 中的 `python3`，其次 `python`，确认版本和创建 venv 所需能力。安装器不改系统 Python，不创建共享 venv。pbot 加载后使用现有共享锁、锁定依赖和失败重试逻辑准备环境。失败由 pbot 显示，可继续使用其他能力并按既有方式重试；不改成新的工作区启用条件。
+
+## 启动与初始化
+
+完成安装阶段后提供“立即启动 Pi”，默认选择启动。启动时将子进程 cwd 设为所选工作区，继承终端，不试图修改父终端目录。
+
+正常启动语义为在该目录运行：
+
+```bash
+pi "/pbot init"
+```
+
+Pi 先处理项目信任和扩展加载，再分发启动输入。pbot 命令成功注册时，`/pbot init` 直接执行命令处理器，不需要模型认证或模型调用。初始化完成后留在同一 Pi 交互会话，登录与模型选择交给 Pi。重复 setup 后仍使用同一命令补齐缺失资料，保留已有内容。
+
+Pi 可能把未知斜杠输入继续交给模型。本次启动显式加载一个小型引导扩展，仅拦截未被命令处理的 `/pbot init`，提示 pbot 未加载并终止该输入。Pi 原生命令分发先于 input 事件，因此正常情况仍由原有命令负责。引导扩展不创建资料、不安装软件、不取得信任或登录凭据，也不持久注册。未识别到初始化命令时请求 Pi 关闭；引导文件缺失时不启动 Pi，引导加载错误使用原生启动错误处理。
+
+初始化与 Python 准备分别报告结果。安装器不通过等待固定时间、模拟键盘、分析提示文案或发送模型请求判断成功。用户选择暂不启动时，给出进入该目录并执行初始化的命令，不报告初始化已完成。
+
+## 模块与发布
+
+继续采用现有顶层分层：
+
+| 位置 | 责任 |
+| --- | --- |
+| `src/extension/setup-cli.ts` | CLI 参数、依赖装配、流程入口和退出状态 |
+| `src/services/installation/` | 安装计划、选择规则、执行顺序和结果汇总 |
+| `src/integrations/installation/` | Pi/npm、系统包管理器、环境探测和子进程启动 |
+| `src/ui/setup.ts` | 目录输入、多选、计划确认和进度展示 |
+| `resources/installer/plugins.json` | 维护者提供的配套插件清单 |
+| `src/extension/setup-guard.ts` | 本次 Pi 启动的初始化输入保护，随 CLI 编译发布 |
+| `tests/installation/` | 安装计划、作用域、路径、真实进程与失败恢复验证 |
+
+服务只接收普通数据和窄能力。CLI 不加载主扩展、创建 agent 会话或依赖预先安装的 Pi SDK。不同系统包管理器采用显式的少量适配，不引入动态插件执行框架。
+
+`package.json#bin.pbot` 指向 `bin/pbot.mjs`，再转交 `lib/extension/setup-cli.js`。`npm run build:cli` 使用现有 TypeScript 编译器和独立 tsconfig.cli.json 生成 lib，包括安装入口、原生 Pi 桥接和启动保护。扩展仍由 Pi 加载源码，dist 仍仅用于测试。npm test 的构建和 prepack 都生成 CLI；消费者无需运行构建脚本。
+
+Pi 宿主包继续作为 optional peer，不捆绑进 CLI，npx 不自动安装这些宿主依赖。CLI 入口不导入宿主；安装检查子进程在发现真实 Pi 后动态使用其公开 SDK，仅读取包配置或完成用户选择的本地来源声明替换，不创建会话、不读取认证、不启动扩展。
+
+行为变更时同步维护中英文 README、技术设计、脚本说明、发布与验证文档，区分安装辅助命令与 Pi 中的 `/pbot` 命令。版本遵循现有发布流程，不增加存储或工作区版本计数。
+
+## 失败、取消与重试
+
+| 情况 | 结果 |
+| --- | --- |
+| Pi、pbot、tmux 或必要环境检查失败 | 停止依赖步骤，不启动 Pi，显示修复与重试方式 |
+| 可选插件失败 | 继续其他独立插件，汇总后询问是否先使用 Pi |
+| 下载或安装中断 | 保留已完成步骤；下次重新探测原生状态，不假定原操作已完成 |
+| 用户取消 | 停止后续动作，保留已完成安装与已有资料 |
+| Pi 启动失败或 pbot 未加载 | 明确区分安装结果与启动失败，不发送模型请求代替初始化 |
+| pbot 初始化或 Python 准备失败 | 由 pbot 的原有命令和状态报告，不宣称环境全部就绪 |
+
+不同包管理器不构成一个事务，不自动整体回滚，也不删除环境来重试。setup 每次重新构建计划，不建立持久执行日志或安装完成标记。进程结束时保留本次安装的失败状态；可选插件失败后选择进入 Pi，也不把该安装项改成成功。
+
+## 验收
+
+实现依据包括仓库代码、Pi 文档与包管理实现，以及 npm 包元数据。具体已执行检查和外部验收缺口见[验证](validation.md)。
+
+实现至少验证以下行为：
+
+| 场景 | 验收重点 |
+| --- | --- |
+| 全新环境与 npx | 不需要预装 Pi；入口能独立运行；不会把 npx 缓存中的 peer 当作真实宿主 |
+| Linux 与 macOS | 真实环境中的 Pi/npm 路径、tmux 安装、交互终端和进程交接 |
+| 目录选择 | 当前、已有、新建、包含空格及非 ASCII 的目录；所有操作使用所选 cwd |
+| 首次安装与重复运行 | pbot 必装、默认插件、已安装预选、新候选不自动加入、再次执行正确重试 |
+| 作用域与原生配置 | 同名用户级/工作区包、资源过滤、禁用资源、无关插件与损坏配置 |
+| 自定义来源 | 本地源码、Git、固定版本的保留与显式切换；无重复加载，不删除源码 |
+| 最新版本 | 当前版本、registry 目标与实际结果一致；查询失败和目标环境不满足时不报成功 |
+| 部分失败与取消 | 依赖步骤停止、独立插件继续、重跑重新探测、不自动卸载或整体回滚 |
+| 初始化交接 | 无模型认证也能执行 `/pbot init`；拒绝信任或扩展缺失时不落入模型输入；初始化后保留 TUI |
+| 数据保留 | 已有 `AGENTS.md`、资料、历史记录和备份保持原有内容 |
+| 打包与两种入口 | tarball 中入口和资源完整；npx 与全局 `pbot setup` 均可运行 |
+
+测试使用实际本地文件、进程、打包产物和 Pi SDK，不使用假模型、模拟包管理器或个人凭据。测试安装目录、配置与缓存使用独立临时位置。系统包安装、联网 npm 分发与完整 TUI 在专门的 Linux/macOS 验收环境进行，不修改开发者现有环境来代替验收。
+
+实现提交前执行 `npm run check`、`npm test`、`git diff --check` 和 `npm pack --dry-run`。本地检查不证明未来任意最新版本组合、外部服务或模型任务可用，发布记录应写明实际验收版本与剩余缺口。

package/docs/interaction-design.md

@@ -0,0 +1,13 @@
+# 界面设计
+
+风格简洁，标签和说明尽量短。常用状态与操作直接可见，高级配置和原始数据按需展开。两端共享业务规则，分别使用宿主主题与原生能力。
+
+## Pi TUI
+
+`/pbot` 打开菜单，原有子命令仍可直接使用。菜单支持键盘选择和长列表滚动；状态、历史及公共消息使用只读阅读页。专家仍通过 tmux 进入原生会话。后台提示最多显示四位专家。
+
+## dsh GUI
+
+工作台分工作区、专家、团队、历史四页。宽窗口使用侧边导航，窄窗口使用顶部导航与单列布局。专家列表支持筛选；表单、记录和高级设置分开呈现。查询与提交显示各自结果，不把任务排队当作完成。
+
+轮询保留表单草稿、输入焦点和分页。关闭取消查询及未接纳上传；已接纳操作归服务端。查看页面不恢复专家、不领取模型通知。

package/docs/release.md

@@ -1,6 +1,6 @@
 # npm 发布
 
-发布配置以 package.json 为准：包名 personal-bot，registry 为 npmjs，稳定版本使用 latest。包包含 Pi 扩展源码与资源，消费者由 Pi 直接加载。
+发布配置以 package.json 为准：包名 personal-bot，registry 为 npmjs，稳定版本使用 latest。包包含 Pi 扩展源码、资源和预构建的安装 CLI。扩展由 Pi 加载；npx 与全局 pbot 命令由 Node 直接运行。
 
 ## 首次配置
 
@@ -21,7 +21,7 @@ provenance 所用 repository 元数据须与实际公开仓库匹配。若改为
 
 ## 准备候选包
 
-使用 Linux、Node.js 22.19+ 和 Python 3.11+。更新版本：
+使用 Linux、Node.js 24.9+ 和 Python 3.11+ 准备发布包。Pi 与独立 CLI 的消费者检查仍使用 Node.js 22.19.0。更新版本：
 
 ```bash
 npm version <新版本> --no-git-tag-version --ignore-scripts
@@ -38,13 +38,13 @@ npm pack --dry-run
 npm pack
 ```
 
-核对包清单包含 src、resources、Python 锁文件、setup 脚本和 npm-shrinkwrap.json，排除 dist、node_modules、凭据与运行数据。Pi 宿主包保持 peerDependencies。
+prepack 先检查再构建 CLI。核对包清单包含 bin、lib、src、resources、Python 锁文件、setup 脚本和 npm-shrinkwrap.json，排除 dist、node_modules、凭据与运行数据。Pi 宿主包保持 optional peerDependencies，避免 npx 安装入口隐式下载宿主。另在独立 npm cache/prefix 中验证 tarball 的 npm exec 与全局 pbot --version，检查未额外安装 Pi SDK。
 
 在独立 Pi 配置和临时工作区验收安装；加载扩展会准备用户级 Python 环境，因此验收同时使用独立用户数据目录。
 
 ## GitHub 发布
 
-[CI](../.github/workflows/ci.yml) 在 Node 22.19.0/24.x 执行检查和测试，再生成候选 tarball。[发布工作流](../.github/workflows/publish.yml)要求：
+[CI](../.github/workflows/ci.yml) 在 Node 24.x 安装完整开发依赖、执行检查和测试，再生成候选 tarball；独立 Node 22.19.0 作业安装同一 tarball，检查 CLI 不隐式安装宿主 SDK，再显式安装锁定的 Pi SDK，验证扩展、工具、技能和资料初始化。消费者检查不安装 dsh 开发依赖，不调用模型。[发布工作流](../.github/workflows/publish.yml)要求：
 
 - tag 为 v<稳定版本>，包与锁文件版本一致。
 - 提交已进入远端默认分支。
@@ -59,7 +59,7 @@ git tag "v$VERSION"
 git push origin "v$VERSION"
 ```
 
-发布作业下载本次 CI 的同一 tarball，使用 OIDC 和 provenance 上传，跳过包脚本，然后查询公开版本与 latest。npm 可能在上传成功后继续处理包，查询最多执行 20 次，失败后间隔 15 秒；只重试只读查询，不重试上传。普通分支推送只运行 CI；已推送的发布 tag 保持不变。预发布版本不适用此流程。
+发布作业下载本次 CI 的同一 tarball，使用 OIDC 和 provenance 上传，跳过包脚本，然后查询公开版本与 latest。npm 可能在上传成功后继续处理包，查询最多执行 20 次，失败后间隔 15 秒；只重试只读查询，不重试上传。普通分支推送只运行 CI；已发布到 npm 的版本及对应 tag 保持不变。只有 registry 明确返回该版本 404、此前未执行上传，并经维护者同意时，才可在修复和检查后将失败发布的 tag 更新到修复提交，继续发布同一版本；更新前再次核对 registry，并用远端旧 tag 对象限定推送，避免覆盖并发修改。预发布版本不适用此流程。
 
 ## 本机发布
 

package/docs/technical-design.md

@@ -1,11 +1,11 @@
 # 技术设计
 
-Personal Bot 是按工作区加载的 Pi 扩展。模型负责分析、协调和工具使用；扩展负责资料准备、专家会话和共享 Python 环境。安装与命令见[项目 README](../README.md)。
+Personal Bot 提供按工作区加载的 Pi 扩展和固定版 dsh Host/Web 接入。模型负责分析、协调和工具使用；扩展负责资料准备、专家会话和共享 Python 环境。安装与命令见[项目 README](../README.md)。
 
 ## 模块与依赖
 
 ```text
-Pi 命令、工具与事件
+Pi / dsh 命令、工具、事件与原生 Remote
          ↓
  tools / extension / ui
          ↓
@@ -16,39 +16,43 @@ Pi 命令、工具与事件
           integrations
 ```
 
-src/pbot.ts 装配依赖并注册入口。
+src/pbot.ts 装配 Pi 入口，src/dsh.ts 装配 dsh Host，src/ui/dsh/index.ts 装配 Web 客户端；共享业务服务，不引入通用 Host 平台。src/extension/setup-cli.ts 装配独立安装命令；`pbot setup` 通过原生 npm/Pi 准备一个工作区，再启动 Pi 执行 `/pbot init`。安装器的顺序、来源保留与失败恢复由 services/installation 管理，接入层调用实际宿主的包管理接口，不创建模型会话。详见[安装与升级](installation-design.md)。
 
 | 目录 | 责任 |
 | --- | --- |
 | src/tools/ | 输入、输出、schema、执行适配和工具列表 |
 | src/services/ | 业务规则、状态变更和操作顺序，按 agents、workspace 聚合 |
 | src/model/ | 数据类 |
-| src/integrations/ | Pi 会话、Python 环境激活与进程执行 |
+| src/integrations/ | Pi/dsh 原生会话、Python 环境激活与进程执行 |
 | src/storage/ | 原子 JSON、子会话与团队文件 |
 | src/extension/ | 命令、事件和资源生命周期 |
 | src/ui/ | 确认队列、对话框和专家展示 |
 | src/common/ | JSON、校验、文件、包路径和版本辅助逻辑 |
 | resources/ | 角色、技能、提示词、模板和参考资料 |
 
-服务不依赖 Pi SDK、工具或 UI。共享进程执行可直接使用，其他宿主能力通过窄接口传入。接入层可引用服务类型；命令和工具通过服务执行状态变更。数据类在进入 JSON、存储和工具结果前转为普通数据。
+服务不依赖 Pi/dsh SDK、工具或 UI。共享进程执行可直接使用，其他宿主能力通过窄接口传入。接入层可引用服务类型；命令和工具通过服务执行状态变更。数据类在进入 JSON、存储和工具结果前转为普通数据。
 
 | 主体 | 管理内容 |
 | --- | --- |
 | prepareWorkspace | 补建资料目录与根 AGENTS.md |
 | PythonEnvironmentService | venv 准备、依赖检查、状态与取消等待 |
-| AgentService | 子进程、inbox、周期与交付资格；拒绝向被团队占用的成员发送私人任务 |
+| AgentService / AgentRun | 原生专家实例、启动预约、代次、inbox、领取/进入/消费/完成与交付资格；拒绝向被团队占用的成员发送私人任务 |
 | TeamService | 固定成员、公共消息、有限轮次、团队占用与暂停规则 |
-| HistoryService | 原生会话的问答索引、四叉摘要、全文查询与串行摘要队列 |
-| WorkspaceInstance | 工作区资源及环境激活的生命周期 |
+| HistoryService | 双来源问答索引、四叉摘要、查询、来源写锁与过期提交拒绝 |
+| WorkspaceInstance / DshWorkspaces | 各宿主工作区及资源生命周期；dsh 按父会话装配，并按工作区共享历史整理 |
 
 ## 加载与关闭
 
 Pi 原生配置决定扩展加载范围，启动目录作为工作区根目录。session_start 创建实例、提供工具与技能，并准备共享 Python 环境。加载本身不开展模型任务。
 
+Pi 的 `/pbot` 打开原生菜单，状态与长记录使用只读阅读页；dsh 使用独立工作台。见[界面设计](interaction-design.md)。
+
 `/pbot init` 可选地补建资料，已有文件保持不变。`/pbot status` 展示路径、版本和 Python 状态；模型通过每轮 pbot_environment 取得工作区、cwd、资源根目录和进程环境信息。
 
 主 reload 保留子进程并重新关联，但暂停团队，不继续安排旧批次；退出或切换会话时清理子进程、取消环境准备并恢复本实例持有的环境变量。关闭操作幂等。子会话的分支归属、通知和恢复规则见[专家协作](agent-collaboration.md)。
 
+dsh 只为原生 registry 中的根 Agent 建立协调者工作区，绑定其原始 cwd。专家使用同进程独立 Agent/Session；组件或所属父 Agent 关闭时取消预约、暂停安排并等待自己拥有的执行资源释放。打开页面、轮询、重连不恢复专家或启动模型，已接纳工作不归浏览器生命周期所有。原生存在但由其他实例持有的专家不能替换或假称已释放。
+
 ## 资源加载
 
 | 资源 | 用途与加载方式 |
@@ -59,13 +63,15 @@ Pi 原生配置决定扩展加载范围，启动目录作为工作区根目录
 | resources/references/ | 按需读取的操作参考 |
 | resources/templates/workspace-agents.md | 补建根资料入口的模板 |
 
-主会话通过 before_agent_start 增加提示词 section，同时保留 Pi 原生 AGENTS.md 加载。资源在使用时读取，缺失时报错；提示词更新后通过 /reload 或重启加载。
+主会话通过 before_agent_start 增加提示词 section，同时保留 Pi 原生 AGENTS.md 加载。资源在使用时读取，缺失时报错；提示词更新后按宿主原生机制重载。dsh 使用原生 systemPrompt 与 FileSystemSkillProvider，发现包内技能及工作区 `.agents/skills`，不增加另一套工具或技能注册平台。
 
-公共约定负责工作区与执行边界，角色负责职责与验收，技能提供专业方法与必要的本地操作约定，工具定义参数与结果语义。委派资料修改依据原任务授权及明确的文件责任，诊断环境问题不要求再次授权。工具按 action 校验必填与允许字段，返回具体参数错误；status 不读取报告正文。附件组装由 integrations/pi/agent-input 保留绝对来源及 Pi 原生读取结果。资料保存由模型按公共约定与维护技能处理，沉淀方法、口径与结论，可再次查询的数据按需获取。布局见[文件存储](file-storage.md)。
+公共约定负责工作区与执行边界，角色负责职责与验收，技能提供专业方法与必要的本地操作约定，工具定义参数与结果语义。委派资料修改依据原任务授权及明确的文件责任，诊断环境问题不要求再次授权。工具按 action 校验必填与允许字段，返回具体参数错误；status 不读取报告正文。Pi 附件组装保留绝对来源及原生读取结果；dsh 使用原生文件存储与图片准入，Web 通用文件走原生 Session 上传凭证，命令图片使用原生编码图片输入。资料保存由模型按公共约定与维护技能处理，沉淀方法、口径与结论，可再次查询的数据按需获取。布局见[文件存储](file-storage.md)。
 
 ## 历史查询
 
-历史服务只读提取原生会话，按分支将连续问答每四个节点逐层汇总，问答、摘要、父子关系与原文引用保存在工作区 .pi/pbot/history/。原生 session ID 关联会话，来源只保存会话 ID 与消息 ID；文件路径由 Pi 接入层在扫描时取得，不写入存档。原生文件缺失时保留已存档内容，支持随工作区复制。pbot_history 与 /pbot history 调用同一服务。加载和查询只收录；agent_settled 后使用当前模型串行补齐摘要，复用实例取消信号让新输入优先。实现与限制见[历史对话](history.md)。
+Pi 维护 `.pi/pbot/history/`，dsh 维护 `.dsh/pbot/history/`；两者共同查询既有归档，只收录和整理自己的原生来源。来源保存 host、会话 ID 与消息位置，不保存原生路径。Pi 保留既有 ID、摘要与旧归档处理，dsh 使用独立根 ID，不跨来源写入。
+
+扫描与模型调用在短写锁外，提交时重读，拒绝过期原文或摘要覆盖。查询不调用模型；正常主交互结束后才在空闲阶段整理，新人工输入优先取消。dsh 使用原生 LLM 路由，不创建额外 Agent，也不写主聊天。原生会话缺失时保留现成归档，单个来源损坏不阻断另一来源。实现与限制见[历史对话](history.md)。
 
 ## 原生子会话存储
 
@@ -77,28 +83,36 @@ PiAgents 使用 `--session-id <agentId>` 启动新的原生会话，让 Pi 按
 
 会话文件移出控制目录改变恢复契约，因此版本为 0.2.0，旧兼容线不进入当前列表或后台调度；不导入、迁移或删除旧记录。既有控制字段、团队调度及完成叶节点关联保持不变。
 
+dsh 的 `native-session.json` 只保存原生 Session ID，不把它写入 Pi 路径字段。先持久化父会话，再创建并持久化空专家；冷读、恢复校验和固定 `dsh:<turn/end seq>` 报告均使用公开 Session API。恢复保留原生模型选择，清除旧 inbox，只接纳新代次的新请求。双方不接管对方的会话。
+
 ## 团队接入
 
 团队采用独立 team.json，不改动旧 AgentMessage、AgentCycle 等持久结构。TeamService 接收普通成员状态与完成记录，安排 roundRobin 或 parallel 轮次；AgentService 再校验并写入原 inbox。父侧原扫描器收集固定叶节点报告并公开原文，不调用主模型转述，不另建执行器或事件总线。
 
-团队关联先保存，再发布输入。跨文件窗口采用保守恢复：不自动重发旧请求，只补交付可核对的完成记录。主/子工具显式注册，子入口只有公共 read/post。Pi 的上下文注入和通知边界分别位于 subagent-entry、agent-events 与 integrations/pi/team-context，服务不持有 Pi ctx。
+团队关联先保存，再发布输入。跨文件窗口采用保守恢复：不自动重发旧请求，只补交付可核对的完成记录。主/子工具显式注册，子入口只有公共 read/post。Pi 的上下文注入和通知边界分别位于 subagent-entry、agent-events 与 integrations/pi/team-context，服务不持有宿主 ctx。dsh 在原生 pre-step 安全边界注入团队上下文，以持久事件区分领取、进入、消费与正常最终答复；团队投递先取得原生 maintenance 准入，不能把公开 idle 当作独占许可。
 
 模型可读的团队任务、背景、公共原文和批次通知使用 Markdown；公共消息 read 复用同一原文渲染。主 agent 收到的独立子会话结果通知，以及 agent/team 工具的列表、状态和报告文本也使用 Markdown。common/markdown 提供字段与原文区块渲染，tools/result 只为这些工具显式选择 Markdown 文本。上下文预算计入实际 Markdown、原文围栏与分页字段。工具 structuredContent、原生 custom message 的去重 details 和控制文件继续使用原有结构化字段，运行时不解析 Markdown 来识别团队或请求。
 
+## dsh 人工管理
+
+原生 `/pbot` 命令与模型工具调用同一业务动作。四个共享 Remote 描述符提供 snapshot、expert、team、history 查询，Host 注册，Client 原生 `$mount`；不增加 HTTP 服务。查询核对已加载的根父会话及领域归属；完整专家记录只读分页，不代替模型 read 领取通知。
+
+Web 拥有草稿、上传和查询；接纳后的命令归服务端。命令不重复记录私人输入正文，人工对话要求团队暂停成功后才进入 inbox。原生工具成功读取或上下文实际消费才确认通知；PTC 内层 read 还要求根调用成功，页面读取不确认。
+
 ## Python 环境
 
 所有工作区共用当前用户的 venv。PythonEnvironmentService 调用 scripts/setup-python.py，按 python/requirements.lock 创建或对齐依赖，完成 pip check、库导入和基础计算检查后标记就绪。安装仅使用 wheel。
 
 共享锁串行化跨进程 setup，同一服务合并重叠请求。失败或取消时保留环境并报告状态，其他扩展功能继续可用；可通过 `/pbot python setup` 重试。
 
-WorkspaceInstance 在当前进程激活 PATH、VIRTUAL_ENV 和 Python 路径变量，供主会话与专家的 Bash 继承。关闭时恢复仍由本实例持有的变量。环境更新会影响其他工作区，更新前应停止相关脚本。
+各宿主装配在当前进程激活 PATH、VIRTUAL_ENV 和 Python 路径变量，供主会话与专家的 Bash 继承；同一 dsh 进程内的工作区共用准备与激活生命周期。关闭时恢复仍由本实例持有的变量。环境更新会影响其他工作区，更新前应停止相关脚本。
 
 计算通过原生 Bash 和第三方库 API 执行，使用项目自身的目录、输入和输出约定。路径、安装条件与许可见 [Python 说明](../python/README.md)。
 
 ## 工具与分发
 
-工具提供 outputSchema，由 Pi 纳入 pbot namespace；codemode 按工具契约组合调用。原生 CLI/MCP 与可选 Task Conductor 的接入和授权见[工具与执行](capability-design.md)。
+Pi 将工具纳入 pbot namespace，codemode 按契约组合；dsh 注册原生工具，并在固定版可表达的 schema 之外继续校验完整领域契约。原生 CLI/MCP 与可选 Task Conductor 的接入和授权见[工具与执行](capability-design.md)。
 
-包以 TypeScript 源码分发，由 Pi 加载；dist 仅供测试导入。发布版本以 package.json 为准，包内组件共用该版本。子会话兼容线在 1.0 前按次版本、1.0 起按主版本判断，跨线会话不能直接恢复。
+扩展以 TypeScript 源码分发，由 Pi 加载；dist 仅供测试导入。安装 CLI 使用现有 TypeScript 工具链单独生成 lib，由 bin/pbot.mjs 启动，消费者无需编译或预装 Pi。dsh Host 与 Web 也编译到 lib，客户端由原生包根 Loader 发现；Pi 的入口仍由包清单明确指向 src。宿主 SDK 均为 optional peer，不捆绑另一份运行时；TypeBox 是共享契约所需的包自身运行时依赖。Pi/CLI 保持 Node.js 22.19+，dsh 与完整开发使用 Node.js 24.9+。安装检查子进程在发现真实宿主后使用该宿主的 SDK 读取配置和切换来源声明。发布版本以 package.json 为准，包内组件共用该版本。子会话兼容线在 1.0 前按次版本、1.0 起按主版本判断，跨线会话不能直接恢复。
 
 开发验证见[验证](validation.md)，分发流程见[npm 发布](release.md)。