personal-bot 0.2.4 → 0.2.6

package/docs/dsh-support-proposal.md

@@ -0,0 +1,314 @@
+# Pi 与 dsh 双宿主支持方案
+
+状态：Q1–Q13 已确认，设计树已收敛。用户已授权编写技术方案并开始执行；实施步骤与进度见[实施技术方案](dsh-implementation-plan.md)。
+
+目标：保留 Pi 的现有能力，同时在 dsh Web 中提供完整的 Personal Bot。复用业务服务和资料，只适配宿主实际不同的注册、执行、存储引用、生命周期和界面。
+
+## 已确认决策
+
+| 决策 | 内容 |
+| --- | --- |
+| Q1 能力范围 | 覆盖全部现有能力，包括资料、角色与技能、Python、独立专家、团队、history 和人工管理 |
+| Q2 首个入口 | 以 dsh Web 为使用与验收入口 |
+| Q3 会话归属 | 原生会话由创建它的宿主管理，不跨宿主接管或恢复 |
+| Q4 安装 | 使用 dsh 原生插件安装；首版不扩展 `pbot setup` 的 dsh 安装流程 |
+| Q5 配置共享 | 业务约定、用户偏好、角色补充、专业方法和提供方手册共用文件；模型、认证、插件加载和 MCP 连接分别原生管理 |
+| Q6 历史共享 | 两端共同查询问答、摘要和关系；各自收录和生成自己来源的摘要，保留旧 Pi 归档和节点身份 |
+| Q7 生命周期 | 页面切换、刷新和关闭浏览器不主动停止已授权工作；服务端资源关闭时清理执行，重启不自动重放旧任务 |
+| Q8 版本基线 | 固定 `@deepseek-ai/dsh@0.2.2-rc.1`；dsh 路径要求 Node.js ≥24.9.0 |
+| Q9 专家执行 | dsh 在同一服务进程内创建独立原生 Agent / Session；Pi 保留独立进程和 tmux |
+| Q10 加载范围 | 从原生 Web 模板创建独立 `pbot` profile，可承载多个工作区 |
+| Q11 兼容标准 | 业务操作含义一致；模型、思考强度和资源选项按宿主原生能力表达，不支持的输入明确拒绝 |
+| Q12 人工操作 | `/pbot` 配合原生菜单和轻量管理界面；人工操作调用同一业务服务 |
+| Q13 分发 | 一个 npm 包和统一版本，分别提供 Pi 入口、dsh 服务端入口及 Web 客户端模块 |
+
+设计树没有剩余的用户选项。下文把上述决定落实为实现边界和验收条件；运行验证仍是实施阶段的工作，不把静态核查视为通过验收。
+
+```text
+保留 Pi，同时支持 dsh
+├─ 业务能力完整
+│  ├─ 资料、职责、专业方法共用
+│  ├─ 专家与团队规则共用，执行按宿主适配
+│  ├─ Python 用户 venv 共用，激活生命周期分别管理
+│  └─ 工具含义一致，原生选项分别校验
+├─ dsh Web 入口
+│  ├─ 独立 pbot profile
+│  ├─ 命令、专家、团队、history 视图
+│  └─ 服务端执行独立于页面观察
+├─ 资料与历史共享
+│  ├─ history 共同查询，各自写入
+│  ├─ 原生配置与会话分别管理
+│  └─ 旧 Pi 记录保留，不迁移或接管
+└─ 单包分发
+   ├─ Pi 源码入口
+   ├─ dsh 服务端与客户端构建产物
+   └─ 原生安装，固定版本验收
+```
+
+## 架构与最小改动
+
+继续保留 `tools / services / model / integrations / storage / extension / ui` 顶层分层。按责任划分代码，不新增通用 Host 平台、动态插件发现、配置同步框架或第二套模型循环。
+
+```mermaid
+flowchart TD
+  Pi[Pi 命令与工具] --> PiEntry[Pi 入口与事件适配]
+  Web[dsh Web 管理界面] --> Remote[dsh 原生命令与 Remote]
+  Dsh[dsh 模型工具] --> DshEntry[dsh 入口与事件适配]
+  Remote --> Services[共享业务服务]
+  PiEntry --> Services
+  DshEntry --> Services
+  Services --> Storage[pbot 控制记录与历史归档]
+  Services --> Capabilities[专家执行与历史读取的窄能力]
+  Capabilities --> PiNative[Pi SDK 与独立进程]
+  Capabilities --> DshNative[dsh Agent 与 Session API]
+```
+
+| 部分 | 现状 | 必要改动 |
+| --- | --- | --- |
+| 入口 | `src/pbot.ts` 装配 Pi | 保留该入口，新增 `src/dsh.ts`；分别明确注册，不按运行环境猜测宿主 |
+| 工具 | 各领域 `contract.ts`、`tool.ts` 含 Pi 类型及注册 | 共享普通数据、JSON Schema、action 校验和业务处理；Pi/dsh 执行适配仍放在相应工具领域内，服务不接收宿主 context |
+| 专家服务 | `AgentService` 不导入 Pi，但 `AgentHost` 为同步操作且显式传会话文件 | 将创建、恢复、原生验证和报告读取改为必要的异步边界；会话文件或原生 ID 的解析归接入层 |
+| 专家运行规则 | `extension/subagent-entry.ts` 含领取、周期、人工输入归因和中断记录 | 将两端需要的状态规则提取到 `services/agents/`；Pi 事件、SDK 消息和 dsh 事件分别转换为普通输入，避免复制一套状态机 |
+| 团队与通知 | `TeamService` 管理轮次，父侧事件文件连接扫描与通知 | 保留团队算法；共享调度及通知选择规则，宿主分别负责触发、写入原生上下文和读取领取记录 |
+| 历史 | `HistorySource` 已隔离 Pi 提取；服务按单一 sessionId 关联 | 增加来源身份及读写范围，复用分组、搜索和分页；新增 `integrations/dsh/history.ts` |
+| 生命周期 | Pi `Lifecycle` 只有一个 active 实例，实例持有 Python 激活 | 保留 Pi 行为；在 `extension/dsh/` 按父会话管理实例，按工作区共享历史服务，按服务进程持有 Python 激活 |
+| UI | Pi 命令与 TUI 直接连接 | 保留 Pi UI；新增 `ui/dsh/` 客户端模块，`extension/dsh/` 提供实际需要的领域 Remote 接口 |
+| 接入 | Pi 原生调用集中在 `integrations/pi/` | 新增 `integrations/dsh/`，处理 Agent、Session、模型选择、附件和原生事件 |
+| 分发 | Pi 加载源码，安装 CLI 使用 `lib`，`dist` 仅供测试 | 增加 dsh 服务端和客户端构建，以及 bundle patch；更新依赖边界检查，防止 Pi 加载链引入 dsh/浏览器依赖 |
+
+工作区准备、Python 依赖准备、团队轮次算法和文件授权规则继续复用。现有 Pi 文件不做无关搬迁。`model` 只承载普通数据，不导入任一宿主 SDK；已有 `AgentHost`、`HistorySource` 是扩展点，不为其他假想宿主增加接口。
+
+## 全部能力映射
+
+| 能力 | dsh 落点 | 保留的行为 |
+| --- | --- | --- |
+| 工作区资料 | `/pbot init` 调用 `prepareWorkspace` | 补建资料，保留已有文件；加载不等于初始化，不创建启用状态 |
+| 状态 | `/pbot status` 与会话上下文 | 展示工作区、cwd、版本和 Python 状态，区分当前目录与资料所属工作区 |
+| 协调者与专家职责 | 原生 system prompt section/context | 共用公共约定及 `coordinator.md`、`general-purpose.md`；加载同名工作区补充 |
+| 技能与参考 | 原生 skill filesystem provider 的附加资源目录 | 共用专业方法正文，按需加载；宿主操作指南分别提供 |
+| 原生工具 | dsh tools、Bash、文件与附件 API | 保留原生结果和取消语义；不新增计算工具或泛化调用代理 |
+| 外部 CLI/MCP | CLI 自有配置；dsh 原生 MCP 插件与配置 | 不复制 Pi 认证或连接声明，不建立私有 MCP 客户端；可选 Task Conductor 继续直接接入主会话 |
+| 共享 Python | 现有准备服务和用户 venv；服务端组件持有激活 | 自动准备、失败可见、显式重试；不改变系统 Python，项目构建使用其声明的环境 |
+| `pbot_agent` | 同进程独立 Agent / Session | `start/send/rename/status/list/read/stop/resume` 全部保留；无任务 start 待命，不调用模型 |
+| 初始附件 | dsh 原生文件读取与附件能力 | 文件按工作区解析，保留绝对来源、图像、截断和续读信息；不继承父聊天 |
+| 专家人工进入 | pbot 专家视图和服务端操作 | 浏览原生内容、直接对话、补充要求、重命名、停止和显式恢复；只看历史不恢复专家 |
+| `pbot_team` | 现有 `TeamService` | `create/list/status/read/run/pause/close`、固定成员、有限轮次、roundRobin/parallel 和期限保留 |
+| `pbot_team_message` | 主/子会话显式注册的 read/post | 署名与来源由服务确定，公共原文直接交换，普通 post 不额外唤醒模型 |
+| 完成报告与通知 | 原生持久事件、固定结束位置和 pbot 领取记录 | 不以 idle 判成功；旧报告不被后续答复替换；团队周期不重复发个人完成通知 |
+| `pbot_history` | 两种来源归档共同查询 | search/read、正文和关系分页、四叉摘要、来源引用及未完成状态保留 |
+| 文件确认 | 原生 `tools/pre-execute` 与 approval | 主会话工作区外 write/edit 需要确认；专家直接拒绝同类越界修改，保持当前范围 |
+| 多会话 | 按确切父 Session 绑定实例 | 切换页面不释放后台工作；fork 不接管原会话的专家或团队 |
+| 安装与客户端 | 原生 profile/bundle/client 模块 | 单包发布；未来客户端可复用服务端业务接口，首版以 Web 验收 |
+
+“能力完整”以业务行为和结果核对，不要求界面控件或启动参数逐字相同。Pi 的 `noExtensions`、`noPromptTemplates` 等参数没有 dsh 对应含义时不出现在 dsh 契约中；误传时报错。模型、思考强度、工具和资源选择由接入层按固定宿主版本校验，不维护 pbot 模型目录。
+
+## 工作区、资源与配置
+
+普通资料共用工作区内的 `AGENTS.md`、`agents/`、项目、知识及 `providers/` 手册。专业方法使用同一份包内正文或工作区 `.agents/skills/`，各宿主按自己的资源机制发现。Pi 专属命令从公共方法中分离到宿主指南，避免 dsh 会话收到不可执行的 Pi 操作步骤。
+
+dsh bundle 为独立 profile 配置默认的 pbot 会话组合，复用必要的原生文件、Bash、技能、模型和 Web 能力。专家组合复用原生基础能力，加入 general-purpose 职责和团队通信，排除 pbot 管理工具及递归委派。不会以 dsh 同名 subagent 或团队功能替换 pbot 业务。
+
+每个父会话在创建或加载时固定规范工作区根目录。后续改变执行 cwd 不转移资料或团队归属，也不修改进程全局 cwd。子会话的 cwd 可不同于资料工作区；原生工具和 MCP 的实际配置作用域按该宿主说明处理，不能声称它继承了另一宿主或另一会话的临时配置。
+
+0.2.2-rc.1 已发布的 MCP 接入是 `@deepseek-ai/dsh-mcp-client`：每个服务器一条原生配置，支持 stdio 和 Streamable HTTP，并通过原生作用域暴露工具。使用该版接口及配置管理，不照搬后续主干的 `mcp-manager` 说明。默认不增加任何外部服务器，也不导入旧配置或凭据。
+
+## 专家执行、报告与团队
+
+### 创建与投递
+
+使用 `ctx.agents.create({ sessionId, parentAgent, meta, agentOptions, setup })` 创建专家。`agentId` 对应本宿主的原生 session ID；元数据记录 cwd、直接父会话和子会话来源，运行时也校验父级归属。setup 在发布 Agent 前安装职责、工具、上下文和监听器，创建完成后才接收新工作。
+
+dsh 持久层允许空会话延迟落盘。首次 start 对外确认成功前，使用公开的原生持久化屏障确保该会话可在进程重启后读取，不通过伪造用户或助手消息促使落盘。pbot 完成记录也只能在对应原生结束位置确认持久化后发布；写入失败保留故障状态，不宣布交付完成。
+
+父会话最多 50 个存活专家，含待命与正在启动的实例。并发 start/resume 必须串行完成同一父会话的限额准入，并按专家 ID 排除重复创建和恢复。异步原生操作不能直接放入现有同步 `.control` 回调：先在短锁内保存准入结果和 generation，再执行原生调用，完成后重新检查实例、generation、stop 和归属；失效时释放新句柄，不发布可用状态。
+
+pbot inbox 继续保存请求及团队关联。当前运行组件领取当前 generation 的请求，再调用原生 `steer` 或 `followup`；原生消息携带可核对的请求身份。原生 inbox 负责模型步骤边界，pbot 记录负责工作请求及业务状态。接收、领取、实际消费和成功交付分别记录，不因入队回执宣称完成。
+
+### 周期与固定报告
+
+使用实际消费记录、持久轮次结束原因和最终 assistant 答复判定周期结果。0.2.2-rc.1 的 `foldConsumedWork` 可辅助区分已消费工作与未执行即取消的输入；它不能替代 pbot 的逐请求关联。`whenIdle()`、`agent/status` 或临时 claimed 事件本身都不是成功证明。
+
+完成记录固定原生结束位置。Pi 继续使用原有 leaf；dsh 将原生持久事件位置编码为接入层解释的固定引用。共享服务不解析事件序号或 Pi 消息结构。读取旧周期时只读取对应结束位置内的最终答复；后续对话、取消、模型错误和空闲都不能覆盖旧报告。
+
+父侧输入保留 `parent` 来源，专家视图中的直接人工对话保留 `interactive` 来源；同周期混合则为 `mixed`。协调者的 send/steer 继续受 `TEAM_BUSY` 约束。直接人工介入团队周期时，沿用当前 mixed 规则：暂停团队，不自动公开混合答复，已显式 post 的公共内容保留。这项规则在共享业务运行逻辑中执行，不能由浏览器自行判断。
+
+### 团队与通知
+
+复用当前固定成员、轮次、并发、期限、领取、暂停及关闭规则。仍先保存团队请求关联，再发布输入。崩溃窗口内无法确认是否执行的请求保留为未知或中断，不自动重发。
+
+团队原文在模型下一安全边界加入原生上下文；注入不应独立开启额外轮次。消息分页、原文保真和上下文预算沿用现有规则。正常完成的团队报告自动公开，普通 post 不增加工作请求。
+
+父会话的结果通知通过原生持久消息或事件记录交付身份。按 agent/cycle、team/run/状态去重；模型 read 的领取与 UI 浏览分开，status 不领取报告。后台扫描错误仍按可重试、需修复、需重新加载区分；重连后查询状态，不能只依赖客户端临时通知。
+
+### 停止与恢复
+
+stop 保持非阻塞的操作语义：先记录停止要求，再取消该专家的输入和执行，等待拥有的 `AgentHandle.dispose()` 完成。只有真实释放或有结束证据后才能解除在途占用。dsh 同进程内不能像 Pi 子进程一样强杀单个 Agent；取消或释放受阻时保持 stopping/故障状态并报告，不能假称已停止。
+
+resume 只针对本宿主、同一工作区和原父会话拥有的停止记录。先验证原生 session 身份与 cwd，再准备新 generation；在恢复 setup 阶段核对并清除旧原生待处理输入，随后才允许新要求进入。旧 pbot generation 的输入不再领取，旧团队批次不续排。缺失、损坏、被其他写者占用或身份不符时明确失败，不新建空白会话代替历史。
+
+加载旧记录和浏览历史不恢复执行。Pi 的“进入已停止 TUI 后待命”行为保留；dsh 专家视图可以直接读停止会话，只有显式恢复并提出新要求才启动其执行。
+
+## 生命周期与共享资源
+
+| 作用域 | 所有者与资源 |
+| --- | --- |
+| dsh 服务进程中的 pbot 组件 | Python 准备与激活、原生注册和按工作区复用的历史服务 |
+| 规范工作区 | 历史归档读取、收录和摘要写入协调；不同父会话不各建一个竞争的整理器 |
+| 父 Session | 专家及团队业务实例、调度与通知、实例关闭信号 |
+| 专家 | 原生 AgentHandle、会话观察、当前 generation 和周期 |
+| 浏览器视图 | 选择、草稿和观察订阅；不持有服务端执行生命周期 |
+
+| 事件 | dsh 行为 |
+| --- | --- |
+| 导航、刷新、关闭浏览器 | 释放客户端观察，已接纳工作继续 |
+| 主会话停止当前回答 | 按主中断规则暂停团队新安排，已领取工作按实际取消和完成状态收尾；不等同于关闭父会话 |
+| 显式终止父会话或释放所属实例 | 暂停团队、取消输入、释放所属专家和观察；其他父会话继续 |
+| fork | 新父 Session 不继承原专家或团队操作权 |
+| 客户端模块热重载 | 重建界面和订阅，查询服务端状态 |
+| pbot 执行组件卸载/重载或 Agent 工厂卸载 | 停止所属专家，保留记录；再次加载不自动继续旧任务 |
+| dsh 服务退出或异常终止 | 原生持久层及控制记录保留；下次加载核对中断状态，恢复需新要求 |
+
+服务端接纳工作后，执行使用所属实例的信号，不继续借用浏览器请求的存活期。尚未接纳的变更可取消；断连后结果不明时先查询，不自动重复提交。所有旧工具、Remote 调用和异步回调都需检查实例与 generation，防止卸载后继续写入。
+
+Python 沿用当前用户的一份 venv 和跨进程 setup 锁。独立 profile 的服务端组件统一准备并激活，单个会话关闭不恢复进程环境。发布包的本地 Bash 使用 `bash -c`，经 subprocess 在启动时读取当前进程环境，保留 PATH/VIRTUAL_ENV；这与用于配置值的不可变 launch environment 是不同路径。实际解释器、依赖、cwd 及多会话释放仍须运行验证。
+
+激活影响该服务进程后续启动的本地子进程。项目构建和测试继续使用项目声明的环境；准备失败报告未就绪，其他能力可用，`/pbot python setup` 可重试。最后由拥有激活的组件恢复仍归它持有的环境值。不会通过仅允许 `DSH_*` 的 `shellEnv` 注入 PATH，也不新增 shell 执行器。
+
+## 存储与跨宿主 history
+
+### 专家与团队
+
+Pi 继续使用原有用户目录、控制记录、`session-ref.json` 及原生会话位置。现有子会话持久契约在当前兼容线内保持不变，不添加存储版本计数器，不迁移、导入或删除旧记录。
+
+dsh 的控制记录放在原生解析出的 DSH home 下 `pbot/subagents/`，与 Pi 目录分开；团队沿用现有相邻目录布局。descriptor、generation、inbox、cycle、团队关联等业务记录尽量共用现有格式。原生引用由宿主接入管理：Pi 保留绝对文件引用，dsh 独立保存其原生 Session 身份，不把 ID 填进 Pi 的文件字段，也不写占位 JSONL。
+
+原生会话正文由宿主持有。pbot 读取 dsh session query/persistence API，不依赖其私有目录或 JSONL 布局；只读访问不迁移、修复或写回原生日志。需要宿主迁移的记录报告诊断，已有归档仍可读。dsh 子会话使用明确的父级来源，避免停止后被普通会话路由静默接管；pbot 不伪造内置 subagent 管理器的专属 descriptor。
+
+### 归档与查询
+
+| 位置 | 内容与写入者 |
+| --- | --- |
+| 工作区 `.pi/pbot/history/` | 现有 Pi 问答、摘要和节点；由 Pi 维护 |
+| 工作区 `.dsh/pbot/history/` | dsh 问答、摘要和节点；由 dsh 维护 |
+| 两端查询 | 读取上述两种归档，结果标注来源；不扫描另一宿主原生会话或替它生成摘要 |
+
+新目录只保存历史资料，不表示工作区启用状态，也不是需要升级的工作区格式。复制两处归档即可保留共同查询能力；原生恢复仍需要本宿主记录。
+
+来源在查询与内存索引中明确为 Pi/dsh，关联键为来源与 sessionId。来源可由归档目录确定，不为标注来源重写旧 Pi 记录。旧 Pi 节点 ID 保持可用；新 dsh 归档根 ID 使用 `dsh-<uuid>`，其节点沿用现有分层标识规则。`pbot_history search` 增加可选 `host: "pi" | "dsh"`，省略时查询双方；命中节点、导航节点及 read 的 source 返回 host。原有 sessionId、entryIds、分页字段和 Pi 节点 ID 保持含义，按来源与 sessionId 联合筛选避免同名 ID 误关联。
+
+收录保留问答原文、补充输入、未完成状态、分层摘要、父子关系与原始消息引用。工具日志、推理和图片二进制不进入 history。专家人工视图读取完整原生记录，不能用 history 归档替代它。dsh 的持久事件序号由历史接入层转换为稳定消息引用，原生 fork 的历史按实际边界提取，不猜测隐藏结果。
+
+收录和摘要只写当前宿主目录。查询刷新双方归档，但不启动模型。主交互正常结束后的空闲阶段，以发起整理的本宿主模型补齐摘要；新输入优先取消相应摘要工作。加载、打开历史视图和恢复网络都不自动启动摘要调用。
+
+dsh 摘要接入使用原生 `llm.prepareCall` / stream，以当前模型选择和认证执行独立的纯文本调用，不新建专家或写入主会话对话。复用现有摘要方法、分段预算及失败保留规则；只在得到有效终止状态与非空正文后保存摘要。摘要是额外模型调用，其实际用量和质量在模型验收中记录。
+
+同一进程对同一工作区复用整理器；扫描和摘要提交使用按来源分开的短写锁。模型调用在锁外进行，写回时读取最新记录并核对摘要输入对应的原文与子节点，过期结果丢弃，避免整份旧记录覆盖新增问答。多进程下不承诺摘要调用恰好一次。源缺失时保留归档；单一来源不可读时报告来源明确的警告，并尽量提供另一来源的可读内容。
+
+此次不新增旧布局导入流程。现有 Pi 对自身历史的兼容读取行为保持原范围，dsh 不触发 Pi 的旧目录复制或字段清理。
+
+## Web 人工管理与客户端复用
+
+`/pbot` 服务端命令直接调用业务服务，不需要模型解释命令。客户端通过 `commandUi.decorate` 等原生机制提供菜单和必要视图：
+
+- 专家：状态列表、原生会话记录、直接输入、协调者补充要求、重命名、停止及显式恢复。工具调用和错误记录可核对，长内容分页；只读查看不领取模型通知。
+- 团队：状态、公共原文分页、post、新批次、pause、close，以及所属专家入口。
+- history：两种来源的会话与节点搜索、正文分页、父子展开；查看器不修改归档。
+- 工作区：init、status 和 python setup；异步操作展示真实状态和失败原因。
+
+底层创建的 pbot 专家不会自动出现在 dsh 内置 subagent 管理器中。该版本普通 Session 控制 API 会拒绝父级拥有的专家，内置 subagent 历史地址又要求其专属身份投影。因此完整人工入口是 pbot 视图，通过原生查询读取内容，通过 pbot 业务入口操作；不承诺直接使用普通聊天输入框接管专家。
+
+浏览器和服务端之间只增加上述领域操作需要的查询、操作与状态观察接口。使用 dsh 原生 Remote 注册、传输、访问控制和重连机制；身份解析后仍由服务核对工作区、父会话及 generation。只读接口使用不激活 Agent 的读取路径；不能为方便获取 context 而自动恢复停止会话。不会再启动 pbot HTTP 服务或提供任意工具调用代理。
+
+文件确认沿用当前职责：主会话的原生 write/edit 在解析实际路径后调用现有文件授权逻辑，dsh 字段为 `file_path`；专家越界修改直接拒绝。模型工具执行中的确认可使用原生 approval，其 API 要求开放轮次；确有确认需求的人工命令使用客户端交互。取消或缺少回答不能视为同意。这些机制不构成 Bash、Python 或扩展的宿主隔离。
+
+独立 profile 是服务端组合边界。未来客户端若复用 dsh Web 组合，可复用客户端模块；使用其他界面时可接入同一服务端领域接口。`dsh-sdk-client` 是另一种进程托管方式：它通过 stdio 启动运行时，`close()` 会关闭该进程。要求客户端关闭后工作继续时，应连接独立常驻服务。具体 Desktop 或自建客户端的安装、托管和体验留待其需求确定，本次不额外建设客户端框架。
+
+## 分发与原生安装
+
+保留 `personal-bot` 一个包和统一版本。Pi 保留 `pi.extensions` 的源码入口，独立安装 CLI 保留现有预构建入口。新增 `personal-bot/dsh` 服务端导出、`./client` 浏览器导出和 `dsh.bundle.patch` 声明；`dsh.client.platform` 为 `web`。
+
+dsh 服务端产物使用 ESM。浏览器产物按 0.2.2-rc.1 的客户端 module loader 格式构建，明确列出外部模块和依赖；复用宿主的 Cordis、React 与原生 UI 模块。首版使用一个客户端 bundle，构建不能依赖开发机旁边的 dsh monorepo。宿主 SDK 声明为可选 peer，开发与验收依赖锁定版本，不在插件内打包另一份运行时。
+
+完整双宿主开发和 CI 使用 Linux、Node.js ≥24.9.0。包的 Pi 消费路径及安装 CLI 保留 Node.js ≥22.19.0 的要求；dsh 入口声明并检查自己的兼容范围。`prepack` 生成 CLI、dsh 服务端和客户端产物，`dist` 仍不进入发布包。此次不预先指定 Personal Bot 发布版本，不改变已有兼容线规则。
+
+以下是实施完成后的安装示例，当前尚无含这些入口的已验收发布包：
+
+```bash
+# 环境已具备符合要求的 Node.js；安装固定 dsh 基线。
+npm install -g @deepseek-ai/dsh@0.2.2-rc.1
+
+# 仅在 pbot profile 尚不存在时执行；创建 Web 组合并输出配置，不启动服务。
+dsh --profile pbot --from-default-profile web --dump-config
+
+# 安装本次构建好的 tarball；文件名按实际版本替换。
+dsh plugin --profile pbot add /absolute/path/to/personal-bot-VERSION.tgz
+
+# 查看组合后配置，再从目标工作区启动。
+dsh --profile pbot --dump-config
+cd /absolute/path/to/workspace
+dsh --profile pbot
+```
+
+`--from-default-profile` 会替换同名自定义 profile，不能作为重复安装或升级命令。已有 profile 只使用原生插件管理更新包，保留用户层配置。配置 dump 不启动 Agent，但会准备 profile 文件，不能将其描述为完全无写入操作。
+
+bundle 只组合所需原生插件、默认 pbot 会话组合、服务端接入和客户端依赖。原生 patch 替换 config 时需提供完整目标值，不能假设深度合并。模型和认证仍通过 dsh 原生方式配置；`pbot setup` 不接管这套流程。
+
+## 实施顺序与验收
+
+以下顺序已获用户授权。第一步先验证已选宿主接口能承载方案，再扩大共享服务改动。
+
+1. **接入验证**：在隔离的 dsh home 和临时工作区安装预构建插件，验证原生命令、客户端加载、无任务 Agent 创建/释放、只读会话查询、恢复 setup 清理旧 inbox，以及原生 Bash 的 venv 继承。使用真实 SDK，不配置模型凭据。
+2. **提取必要公共逻辑**：抽离工具业务契约、专家运行状态规则与原生会话引用；Pi 使用新的窄边界但保持行为和持久记录。执行 Pi 回归，避免与 dsh 实现同时失去参照。
+3. **完成 dsh 业务接入**：实现专家、团队、通知、文件确认、资源及多会话生命周期；旧请求不自动重放。
+4. **完成共同 history 与 Web 管理**：增加来源、独立写入、共享查询和管理视图；验证并发及断连后的状态恢复。
+5. **打包与双宿主验收**：真实 tarball 分别加载，完成下列条件，并更新当前设计、使用及验证文档。
+
+| 验证层次 | 关键场景 | 证据边界 |
+| --- | --- | --- |
+| 本地业务与存储 | 真实文件验证归属、限额、代次、短锁、损坏记录、固定报告、旧 Pi 格式、跨来源重名 sessionId、节点与分页 | 不测试文案，不使用 mock/stub、假模型或模拟 provider |
+| 真实宿主无模型接入 | Pi 现有 SDK/tmux 回归；dsh 创建待命专家、scope 工具、角色资源、原生命令、释放、历史构造/读取、无认证失败和冷恢复 | 原生持久记录可通过实际 Session API 构造测试资料，不伪造模型运行成功 |
+| Python | 已获准准备的环境中，以原生 Bash 读取解释器、cwd、依赖并执行基础计算；两个工作区共享且关闭一方不撤销另一方环境 | 准备失败路径和依赖成功路径分别记录，测试不得误改日常用户 venv |
+| Web 人工验收 | 专家完整内容和分页、直接对话、停止/恢复、团队操作、history 展开、文件确认、两标签页及重连 | 必须验证真实客户端，不能用工具注册成功代替界面可用 |
+| 已授权模型验收 | 初始附件、steer/followUp、固定周期报告、两种团队策略、多轮原文、mixed 规则、通知领取和摘要质量 | 使用批准环境，记录模型、用量与剩余缺口，不使用真实交易或个人凭据做自动测试 |
+| 分发 | Linux 全量检查、实际 tarball 的 Pi/dsh 加载、独立 CLI、peer 去重、Node 版本边界和原生 profile 安装 | 安装成功不证明模型、MCP 或业务结果成功 |
+
+实现提交前执行 `npm run check`、`npm test`、`git diff --check` 和 `npm pack --dry-run`。只新增覆盖实际风险的行为测试，不为文档、提示词或模块外形写测试。
+
+必须通过的跨功能场景：
+
+- 同时打开工作区 A、B，A 的专家运行时切换到 B 或关闭浏览器，A 继续；关闭 B 不释放 A 的 Python 激活或历史服务。
+- 主会话 fork 后无法控制原专家；服务重启只展示原记录，查看记录不触发模型，resume 只执行新要求。
+- 无任务专家经历服务重启后仍可按同一身份显式恢复；空会话持久化及报告发布前的 flush 失败均不得产生虚假的成功记录。
+- 原生 inbox 已入队但 pbot 尚未确认、pbot 已领取但原生结果缺失两种崩溃窗口，都不自动补发。
+- 团队暂停仍有在途成员时，私人 send 不越过占用；直接人工介入按 mixed 规则处理，公共消息不泄露混合答复。
+- 后续专家答复不改变前一 cycle 的 read 结果；status 可在报告读取失败时继续展示可读状态。
+- Pi 与 dsh 同时维护同一工作区时，各自只写本来源；另一宿主不可用或原生文件丢失时，已有归档仍可查询。
+- 安装 dsh 支持后，Pi 的 TUI、进程模型、reload 保留子进程、存储引用及 standalone CLI 均通过既有回归。
+
+## 已核查依据与实际限制
+
+设计阶段下载了 0.2.2-rc.1 的相关 npm 发布包，并检查公开类型、README 和编译代码；这些静态核查不构成运行验收。实施阶段的运行结果记录在[实施技术方案](dsh-implementation-plan.md)中。
+
+| 已核查接口 | 设计依据 |
+| --- | --- |
+| Agent create/resume、parentAgent、setup、dispose | 支持同进程独立上下文、待命、发布前组合和归属；卸载拥有者会释放 Agent |
+| Inbox.clear、steer、followup、inject、持久轮次和 foldConsumedWork | 可实现显式恢复和报告关联；运行期仍须验证取消与崩溃窗口 |
+| Session query 与 persistence | 支持只读历史访问；不依赖私有磁盘布局 |
+| Commands、tools scope/restrict、tools/pre-execute | 支持模型工具、无模型人工命令及原有文件确认范围 |
+| System prompt、skill filesystem、原生 preset | 支持共享职责与方法，原生组合需在首次步骤前完成 |
+| Client modules、command UI、Remote 与普通会话 ownership 检查 | 支持配套 Web 模块；pbot 专家需要自己的人工入口 |
+| Bash local、subprocess、home paths | 支持现有 venv 激活方向和原生用户目录解析，仍需实际进程验证 |
+| 发布版 CLI 与 MCP client | 支持原生 profile/bundle 安装和分别管理 MCP 配置 |
+
+主要限制是所选 dsh 版本仍为预发布版本，以及同进程运行共享故障范围。专家无法跨执行组件重载继续运行；协作取消不能保证强制终止单个 Agent。客户端 bundle、Remote、scope 组合和恢复顺序必须在第一阶段真实验证；若固定版本的公开接口无法实现已确认能力，应报告具体阻碍并重审受影响的决定，不私自换版本、降级范围或依赖私有日志格式。
+
+历史共享是已提取资料的共享，不等于跨宿主恢复。多进程摘要调用和外部业务执行均不承诺恰好一次。Bash、Python、MCP 与扩展使用实际环境权限，不宣称宿主隔离。未来具体 Desktop 载体不属于本次 Web 验收结果。
+
+发布包优先于滚动文档和主干。此前 npm 的 `next` 指向本基线，不以标签名称推导稳定性。补充主干资料固定在 `fcc0ad462172522aaf5c93a7b2e01f6b9f0b0159`，与发布接口不同时以发布包为准。
+
+来源：
+
+- [dsh 插件开发](https://deepseek-harness.github.io/deepseek-harness/develop/basic/)、[打包与安装](https://deepseek-harness.github.io/deepseek-harness/develop/basic/publish)
+- 固定版本发布内容：[CLI](https://unpkg.com/@deepseek-ai/dsh@0.2.2-rc.1/README.zh.md)、[Agent](https://unpkg.com/@deepseek-ai/dsh-agent@0.2.2-rc.1/README.zh.md)、[Session Controller](https://unpkg.com/@deepseek-ai/dsh-api-session-controller@0.2.2-rc.1/README.zh.md)
+- 固定版本发布内容：[客户端模块](https://unpkg.com/@deepseek-ai/dsh-client-modules@0.2.2-rc.1/README.zh.md)、[命令 UI](https://unpkg.com/@deepseek-ai/dsh-client-ui-commands@0.2.2-rc.1/README.zh.md)、[MCP Client](https://unpkg.com/@deepseek-ai/dsh-mcp-client@0.2.2-rc.1/README.zh.md)、[SDK Client](https://unpkg.com/@deepseek-ai/dsh-sdk-client@0.2.2-rc.1/README.zh.md)
+- 项目当前行为：[技术设计](technical-design.md)、[专家协作](agent-collaboration.md)、[历史对话](history.md)、[工具与执行](capability-design.md)、[验证](validation.md)

package/docs/dsh.md

@@ -0,0 +1,103 @@
+# dsh 使用说明
+
+Personal Bot 的 dsh 接入固定为 `@deepseek-ai/dsh@0.2.2-rc.1`，首个界面是原生 Web。它与 Pi 共用资料、角色、方法、Python 环境及协作规则，分别使用各自的原生会话、模型配置和认证。
+
+当前代码已接入专家、团队、历史查询和管理界面。实际通过的检查与尚未完成的真实模型、Linux 验收见[实施记录](dsh-implementation-plan.md)和[验证](validation.md)；预发布宿主的接口可能变化，不应直接换成其他版本。
+
+## 在桌面应用中验证
+
+本机检查的 `DeepSeek Harness.app` 为 `0.2.2-rc.1`，其内置运行时使用 Web 基础插件与独立的 `desktop` profile。可以从应用的“插件 → 添加插件”输入本地 `.tgz` 安装包的绝对路径安装，再启用 personal-bot；不必另行安装或启动 dsh CLI。请使用本次源码构建的包，既有 npm 发布版不包含本次未发布改动。
+
+安装后选择一个测试工作区和主会话，输入 `/pbot` 并选择管理入口，应看到工作区、专家、团队、历史四个页签。先验证状态、资料准备和无任务专家，再通过应用原生设置选择模型，验证附件、实际专家回答及一轮团队协作。历史摘要可在至少四次正常完成的主会话问答后检查。
+
+已在 macOS 的实际桌面应用 `0.2.2-rc.1` 中通过原生插件页面安装、启用，并验证四个管理页签、附件、完整记录、团队失败暂停、history 查询与界面刷新。应用自带 Node.js 24.21.0；隔离环境中的 Python 锁定依赖安装及 5 项原生库集成测试也通过。成功模型回答、协作与摘要仍需有可用模型的环境，详见[验证记录](validation.md)。
+
+关闭管理面板只关闭视图，并取消尚未接纳的上传；已接纳专家保持存活。此次实测完全退出桌面应用会关闭后端并停止专家，重开后保留记录且不自动恢复。停用再启用插件具有相同的显式恢复要求。CLI 的独立 `pbot` profile 与应用的 `desktop` profile 分开，不会因为已在 CLI 测试 profile 安装而自动出现在应用中。
+
+## 安装与启动（CLI + 浏览器）
+
+Pi 消费路径和独立 `pbot` CLI 保留 Node.js 22.19+；dsh、双宿主开发和完整验收使用 Node.js 24.9+，目标验收环境为 Linux。计算使用 Python 3.11+。桌面应用会读取登录 Shell 环境，应确保所需 Python 在该环境的 PATH 中可见；终端进程的 PATH 不一定就是应用后端最终使用的 PATH。`pbot setup` 仍是 Pi 安装器，dsh 使用自己的插件与 profile 流程。
+
+下面从当前源码生成安装包，不依赖 npm 上的既有版本已经包含 dsh 接入：
+
+```bash
+npm ci --ignore-scripts
+npm pack
+npm install -g @deepseek-ai/dsh@0.2.2-rc.1 pnpm@10.20.0
+```
+
+仅在第一次创建独立的 `pbot` profile 时运行：
+
+```bash
+dsh --profile pbot --from-default-profile web --dump-config
+```
+
+将下面的 tarball 路径换成实际构建产物，再安装并启动：
+
+```bash
+dsh plugin --profile pbot add /absolute/path/to/personal-bot-<version>.tgz
+dsh --profile pbot
+```
+
+更新包仍使用原生插件命令，不再执行 `--from-default-profile`，以免重建已有 profile。模型、认证、插件和 MCP 由该 profile 的原生设置管理；pbot 不复制 Pi 配置，也不接管 Pi 会话。安装和打开页面不启动模型任务。
+
+在 Web 中选择工作区，再打开主会话。一个 profile 可以管理多个工作区。pbot 绑定主会话建立时的根目录；之后改变原生工作目录只影响相对路径解析，不改变资料、历史与文件规则的根目录。
+
+固定版默认工作区使用宿主账户的系统 Documents 目录。需要指定目录时使用原生工作区选择器；测试部署可在原生 `workspace-controller` 配置中设置 `documentsDirectory`。只设置 `HOME` 或改变启动 cwd 不等于改变系统 Documents 策略。
+
+## 管理入口
+
+在原生输入框选择不带参数的 `/pbot`，打开四个页签：
+
+| 页签 | 操作 |
+| --- | --- |
+| 工作区 | 查看来源、目录、模型、Python 和历史整理状态；准备资料或重试 Python |
+| 专家 | 创建、重命名、停止、显式恢复；人工对话、附件和完整原生记录 |
+| 团队 | 固定成员与职责、有限轮次、暂停、关闭、公共原文和长消息分页 |
+| 历史 | 按 Pi/dsh 来源与时间查询，读取问答及摘要，沿父子节点导航 |
+
+宽窗口使用侧边导航，窄窗口使用顶部导航。专家可按名称或状态筛选；高级设置和原生事件按需展开。草稿与附件按专家保留，团队草稿分别保留。
+
+`/pbot init` 只补建缺失的资料目录和根 `AGENTS.md`。已有资料保持不变；没有工作区启用文件，也不要求初始化后才能使用。
+
+页面查询通过原生 Remote；它不会启动专家、接管旧执行实例、领取模型通知或生成摘要。原生命令本身保留宿主审计记录。轮询保留当前表单草稿与长记录页；关闭、刷新或切换页面不停止已经接纳的工作。连接中断导致操作结果不明确时，先重新查看状态与记录，再决定后续动作。
+
+## 专家与附件
+
+省略初始任务与附件时，只创建待命专家。每个父会话最多 50 个存活或正在启动、释放的专家。dsh 专家是同进程中的独立原生 Agent/Session，无需 tmux，也不继承父聊天历史。
+
+模型默认继承父会话的原生选择。`thinking` 使用 dsh 的 reasoning effort ID；改变 provider 或 model 时，不自动带入另一模型的 effort。`tools` 使用当前原生工具名称，`noSkills` 控制技能；Pi 专属的 `noExtensions`、`noPromptTemplates`、`noContextFiles` 明确拒绝。
+
+初始任务可以指定服务器文件路径。人工对话还可从本机选择文件与图片，单次最多 32 个附件；一次选择服务器路径或本机附件。通用文件使用原生上传与持久文件引用，PNG/JPEG/WebP/GIF 图片接受原生图像准入，数量和字节上限由宿主控制。路径不是“模型已经读过文件”的证据。
+
+人工对话先暂停所属团队，再通过原生 steer 或 follow-up 进入专家。暂停失败时不接纳私人输入。人工输入与团队输入混合的周期不会自动公开；已经显式发布的公共消息保留。共享专家上下文不是保密隔离，需要独立背景时创建新专家。
+
+原生记录按事件分页，正文与原始 JSON 都可继续读取长内容。停止后仍能冷读记录；恢复必须给出新任务，不重放旧 inbox。工具结果、错误与审批记录保留在原生会话中，history 不能代替这些记录。
+
+## 团队和生命周期
+
+团队仍使用 `pbot_team` 与 `pbot_team_message`：固定成员、roundRobin 或 parallel、有界轮数、并发上限与期限。成员就绪只表示接入可用，不证明模型认证或业务能力。普通公共发言不唤醒模型；正常完成的纯团队答复才自动公开。完整规则见[专家协作](agent-collaboration.md)。
+
+服务端资源决定执行生命周期。关闭或卸载 pbot 组件、释放所属父 Agent 会暂停安排并释放它拥有的专家；重新打开页面或加载组件只读取记录，需要明确恢复才继续工作。浏览器关闭与服务端父 Agent 释放是不同事件。
+
+主会话修改原工作区外文件时，通过原生审批请求一次允许。专家的原生 write、edit、apply_patch 不允许修改原工作区外文件；整份 patch 在执行前检查源和移动目标，并在确认后复核路径身份。这些规则不隔离 Bash、Python、MCP 或其他扩展。
+
+## 命令与模型工具
+
+带参数时 `/pbot` 使用原生命令执行；管理页写操作与这些命令共用服务：
+
+```text
+/pbot status
+/pbot init
+/pbot python setup
+/pbot agent {"action":"start","name":"核对专家"}
+/pbot chat {"agentId":"…","text":"核对这些资料","delivery":"steer"}
+/pbot team {"action":"list"}
+/pbot post {"teamId":"…","text":"向全体成员公开的信息"}
+/pbot history {"action":"search","host":"dsh","query":"研究口径"}
+/pbot records {"agentId":"…"}
+```
+
+模型使用 `pbot_agent`、`pbot_team`、`pbot_team_message`、`pbot_history`。参数按本宿主契约校验，不把 Pi 参数改名后继续传给 dsh。原生 CLI/MCP 的可用性与用户授权、实际执行成功分别判断。
+
+Pi 维护 `.pi/pbot/history/`，dsh 维护 `.dsh/pbot/history/`。两者共同查询已有归档，只更新和整理自己的来源。查询不调用模型；正常主交互结束后的空闲阶段才使用该宿主当前模型补齐摘要，新人工输入优先取消整理。详见[历史对话](history.md)。

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

@@ -1,8 +1,10 @@
 # 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`。Personal Bot 的运行主体仍是 Pi 扩展；安装命令只负责环境准备和启动。
+目标是在 Linux 和 macOS 上，通过一个交互式入口安装或升级 Pi、为一个工作区安装 Personal Bot 和选定的配套插件，再启动 Pi 执行 `/pbot init`。这里的安装路径服务于 Pi 扩展；安装命令只负责环境准备和启动。
 
 ## 命令与分发