personal-bot 0.2.3 → 0.2.5

package/docs/dsh-implementation-plan.md

@@ -0,0 +1,158 @@
+# dsh 双宿主实施技术方案
+
+状态：双宿主实现及本机 SDK、分发、Web 和桌面验证已完成；最新 Linux 全量与成功模型工作流待验收。产品边界见[双宿主方案](dsh-support-proposal.md)，最新结果见[验证](validation.md)。
+
+## 目标与完成条件
+
+在同一个 `personal-bot` npm 包中保留 Pi 入口，增加 dsh 服务端和 Web 客户端入口。两端共用资料、业务规则和历史查询；各自管理原生会话、模型、认证、配置与执行生命周期。dsh 固定使用 `0.2.2-rc.1`，开发和完整验证使用 Linux、Node.js 24.9.0 以上。
+
+交付必须覆盖专家、团队、通知、history、共享 Python、资源、文件确认及人工管理。接入验证和部分功能可作为实施里程碑，不能被表述为完整支持。先验证真实接口，再调整共享服务，避免以假定 API 建立大范围改动。
+
+## 模块与依赖
+
+| 模块 | 实施职责 |
+| --- | --- |
+| `src/pbot.ts` | 保留 Pi 装配及加载方式 |
+| `src/dsh.ts` | dsh Cordis 插件入口，显式声明依赖与配置，装配服务端资源 |
+| `src/integrations/dsh/` | 原生 Agent/Session、持久化、模型、历史、附件及事件转换 |
+| `src/extension/dsh/` | 父会话实例、原生命令、Remote、调度、通知及资源释放 |
+| `src/services/agents/` | 专家准入、归属、代次、请求、周期、团队占用与恢复规则 |
+| `src/services/history/` | 来源隔离、归档查询与摘要提交协调 |
+| `src/tools/{agents,teams,history}/` | 普通数据与 JSON Schema、输入校验、业务处理及分别注册的宿主适配 |
+| `src/ui/dsh/` | Web 管理界面，只保存选择、草稿和订阅；不拥有执行资源 |
+| `src/storage/` | 沿用控制记录与原子写入；原生会话位置由接入层解释 |
+| `scripts/` 与包清单 | 服务端 ESM、客户端单 bundle、bundle patch、可选 peer 与 tarball 验证 |
+
+服务不得导入 Cordis、Pi 或 dsh SDK。工具、命令与 Remote 使用同一业务服务。Pi 加载链不能引入 dsh 或浏览器运行时。依赖检查覆盖新增目录及双宿主边界，不新建通用宿主框架。
+
+## 专家与异步边界
+
+现有 `AgentHost` 的同步创建、恢复校验和报告读取需要支持 dsh 原生异步接口。保留同步的本地状态查询；异步操作在共享服务中显式等待，调用方逐层传播，不把 Promise 放入同步文件锁。
+
+创建与恢复分为以下步骤：
+
+1. 核对实例、工作区、父会话、兼容线与模型选项。
+2. 在短控制锁内完成同一父会话的 50 个存活/启动中专家限额准入，保存新 generation 和启动状态。
+3. 锁外创建或恢复原生 Agent，在 setup 中安装资源及监听器。恢复时校验原生身份、cwd 和父级，清除旧 native inbox。
+4. 使用 `SessionStore.flush` 等公开持久化屏障确认空会话已落盘。屏障缺失或失败时不能宣布 start 成功。
+5. 再核对 generation、stop 和实例；过期则释放原生句柄。通过后才接纳本 generation 的新要求。
+
+Pi 继续保留原始 `session-ref.json`、路径与 leaf。dsh 使用独立的原生 Session 引用及持久位置，不给 Pi 文件字段填入 Session ID。业务层只传递引用，不解析 SDK 事件。
+
+从 `extension/subagent-entry.ts` 提取两端实际需要的领取、周期、人工输入归因和中断规则。原生事件转换为请求消费、周期开始、结束原因及固定位置等普通数据。成功判定要求已消费请求、有效轮次结束和非空最终答复；idle 不是成功凭据。
+
+stop 先保存停止意图，再取消和释放句柄；释放未完成时保留占用与 stopping 状态。恢复只执行新要求，不自动重放旧 generation 或旧团队批次。只读查看不恢复执行。
+
+## 生命周期、团队与通知
+
+服务端组件持有进程级 Python 激活；工作区持有共用历史整理器；父 Session 持有专家、团队和调度器；专家持有 AgentHandle。页面只观察这些资源。使用服务端实例信号承接已接受的工作，不能让浏览器断连信号取消已接受任务。
+
+团队继续使用现有算法。主会话 send 遵循 `TEAM_BUSY`；专家直接人工输入归为 interactive，混合周期为 mixed，暂停团队且不自动公开混合答复。公共原文注入下一安全边界，普通 post 不开启模型轮次。
+
+通知按 agent/cycle 或 team/run/状态去重。模型领取报告与 UI 浏览分开。异步回调核对实例和 generation；父 Session 关闭或执行组件卸载后，旧工具与 Remote 调用失效。
+
+## History
+
+Pi 只维护 `.pi/pbot/history/`，dsh 只维护 `.dsh/pbot/history/`，两端查询双方归档。来源由归档目录确定，关联键为 host 与 sessionId，不重写旧 Pi 节点。新 dsh 根 ID 使用 `dsh-<uuid>`。
+
+`search` 增加可选 host 筛选；结果、导航和 read source 带来源。原有正文、关系分页和 Pi ID 语义保留。dsh 接入仅通过公开 Session query/persistence 读原生日志，不扫描另一宿主的原生记录，也不触发 Pi 旧归档导入。
+
+摘要只在本宿主正常交互结束后安排。查询和重连不得调用模型。模型调用在短写锁外；提交前重读归档并核对原文和子节点，丢弃过期结果。dsh 使用原生 LLM 接口，复用当前模型和认证，不写入主聊天。完整工具日志由专家视图读取，不能用问答归档替代。
+
+## Web 与安装
+
+原生命令提供 `/pbot init`、`status`、`python setup` 及专家、团队、history 入口。Web 模块通过 dsh 原生 Remote 查询和操作同一服务，提供专家完整记录、直接对话、停止/恢复，团队操作与 history 展开。查询路径不得隐式激活 Agent。
+
+bundle patch 基于原生 Web profile，声明默认 pbot 组合、服务端插件和客户端依赖。固定版客户端发现只接受包根 Loader 名称，因此 `personal-bot` 包根导出作为 dsh 服务端入口的别名，bundle 使用包根名称加载；`personal-bot/dsh` 独立入口仍保留，Pi 继续显式加载源码入口。客户端遵守固定版本 module loader 格式；外部复用 Cordis、React 和原生 UI。宿主包为可选 peer，开发依赖固定版本，不在发布产物打包第二份 SDK。TypeBox 由本包作为共享契约库提供运行时依赖；dsh 不提供它，不能继续依靠 Pi 的安装间接供应。固定版 dsh 的输出 schema 只支持结构约束和 `oneOf`，因此协作工具保留完整生产端校验，并向宿主提供去除 TypeBox 元数据、采用互斥分支的结构 schema。
+
+安装使用原生插件流程。`--from-default-profile` 仅用于首次创建，不作为升级命令。Pi 安装 CLI 不扩展为 dsh 配置管理器。`prepack` 生成 CLI、dsh 服务端和 Web 产物；`dist` 仍只用于测试。
+
+## 实施里程碑
+
+| 阶段 | 改动与验收 | 当前状态 |
+| --- | --- | --- |
+| A 固定版接入 | 隔离 home、真实插件加载、空 Agent flush/冷恢复、setup 清旧 inbox、只读查询、Remote/客户端加载、Bash 环境继承 | 已通过下列接入验证 |
+| B 公共边界 | 异步 AgentHost、原生引用、运行规则与工具契约提取；Pi 完整回归、既有持久契约保留 | 已通过 Linux 回归 |
+| C dsh 业务 | 专家、团队、通知、资源、文件确认、多会话与 Python 生命周期 | 核心接入和本地验证通过；完整工作流待验收 |
+| D History 与 Web | 来源查询与写隔离、原生历史及摘要、完整人工管理与重连 | 进行中 |
+| E 分发与验收 | tarball 双宿主加载、CLI 独立运行、文档更新、Linux 全量检查和真实 Web 验收 | 本机全量、双宿主 tarball 与 Web 通过；最新 Linux 和真实模型工作流未完成 |
+
+阶段 A 在临时目录安装固定发布包，不使用个人认证或工作区配置。使用真实 SDK 和 Session API 构造本地记录，不使用 mock、stub、假模型或模拟 provider。SDK 行为验证与最终插件行为测试分开记录；仅保留能覆盖实际正确性风险的测试。
+
+完整检查为 `npm run check`、`npm test`、`git diff --check`、`npm pack --dry-run`。真实模型调用只在已批准环境进行；缺少环境时明确记录相应验收缺口，不能以无模型测试替代。
+
+## 接入验证记录
+
+- 固定发布包的真实 Cordis、AgentLoop、JSONL persistence 和内存 query：空专家经 flush 后可被独立进程读取；冷恢复保留身份；恢复 setup 清除旧 inbox 后没有开启旧轮次；错误归属或缺失记录不会激活或替换会话。
+- 使用原生 Session API 写入轮次记录，验证报告固定到持久的 `turn/end`，后续对话及 Agent 释放不改变旧报告。
+- 原生 Bash 在 spawn 时读取进程 venv，两个工作区保留各自 cwd，禁用 user site，环境恢复通过。原生命令的两个父会话分别绑定工作区；关闭一个不影响另一个；卸载插件后旧 handler 失效。
+- Linux Node.js 24.15.0 的初始完整检查通过：`npm ci --ignore-scripts`、`npm run check`、`npm test`，103 项测试通过。之后新增的固定报告及工作区生命周期测试已在本地通过；最终 Linux 全量检查仍须重跑。
+- npm tarball 经原生插件命令安装到隔离 `pbot` profile；真实 Chrome 打开 Web，选择临时工作区，展开 `/pbot` 菜单、执行 status 和 init、刷新后再次查询，工作区和父会话身份保持一致，没有 pageerror。客户端需要同时声明 `remote` 与 `remote.commands` 注入。包根发现规则及 Remote 依赖问题已修正。
+- Web 测试中的 Python 目录刻意包含无关数据，原生 setup 如实返回错误且没有覆盖该数据。该测试不证明完整 Python 依赖安装成功；真实计算环境测试由既有 Python 验证及原生 Bash 测试覆盖。
+
+这些结果只证明接入与无模型生命周期边界。专家完整工作流、执行中页面断开/组件关闭、团队、history、文件确认与模型结果仍在后续阶段验收。
+
+公共边界回归已完成两轮 Linux 全量检查，108 项测试全部通过。`AgentHost` 的创建、校验、报告读取和释放支持异步；启动预约计入限额，恢复校验期间停止不会更换 generation 或写入新输入，关闭等待实际释放。`AgentRun` 统一保存领取、消费、周期与人工输入归因，并封存结果未知的旧领取；Pi 原有文件引用和完成记录格式保留。专家/团队动作处理及公共原文格式化已拆离 Pi 适配。异步扫描发现的会话树事件等待问题已修正，通知恢复与故障升级的原有测试通过。
+
+阶段 C 已接入每个父会话的专家与团队服务、原生工具、角色与技能提供方、附件保存和服务端调度。请求先保存领取，再按原生 inbox 进入轮次、`user/message` 消费及持久 `turn/end` 分别记录；原生领取本身不满足成功条件。人工输入在领取时归入对应周期，在消费后才能支持成功判定；等待未来轮次的人工输入不会把此前的答复误标为 mixed。
+
+当前实现状态见下列阶段 D 记录。阶段 C 检查点的 `npm run check`、构建、差异检查与 19 项定向测试曾全部通过。新增真实原生工具测试验证原工作区固定、归属拒绝、空专家不启轮次、显式恢复与原模型选项保留、缺失 provider 的真实失败、团队有限批次失败暂停且不发布失败答复。真实 Agent maintenance 中运行原生 Bash，验证关闭一个父会话等待其进程退出且另一父会话继续，组件卸载等待剩余进程退出。未安装模型适配器，没有伪造模型回答。创建专家也先 flush 父会话，冷恢复测试因此使用原生 resume 恢复既有父身份。
+
+完成通知复用共同的团队/个人选择和格式规则。dsh 以已提交的 `user/message` 或成功模型工具结果确认领取；PTC 内层 read 还须外层调用成功。原生 inbox 中的排队通知只防止重复提交，不冒充消费。没有正常交互的冷加载和只读查看不会唤醒模型；实际接纳通知或新的人工输入才重新允许自动跟进，失败准入不形成自动重试循环。主会话中断先暂停团队，后台仍核对在途工作；暂停与报告读取故障分别报告。Pi 的三项通知故障与恢复测试通过；测试临时工作目录规范化，避免 macOS 的 `/var` 符号链接造成无效工作区 fixture。
+
+原生 `write`、`edit`、`apply_patch` 已接入文件规则。整份 patch 的源与移动目标先检查，执行前重核 cwd 和目标身份；专家工作区外直接拒绝，主会话使用原生一次批准。真实文件测试覆盖内部修改、符号链接外逃、move 和混合补丁拒绝，以及原生 `rejected`/`unavailable` 审计。真实附件服务验证二进制文件跨块保存后原字节可读、图片准入、原路径删除后附件仍可读，以及目录、取消和图片数量上限拒绝。图片总字节与数量在批量载入期间按宿主限额检查。
+
+阶段 C 检查点仍缺最新 Linux 回归：服务器 SSH 不可达，本机没有 Docker、Colima、Lima 或 Podman，先前 C1 安装未取得成功退出证据。当时浏览器产物只到阶段 A；后续审批、资源与管理验收结果见下文。
+
+阶段 D 的 history 服务和原生工具已接入。两个来源可共同搜索、分别维护；Pi 旧 ID、摘要、关系、分页和旧归档导入继续保留，dsh 不清理或导入 Pi 归档。公开 Session query 读取当前工作区及关联专家，按父级归属纳入不同 cwd 的专家，不把别的工作区专家因 cwd 相同而混入。普通 fork 保留为自身的原生会话；`isSeeded` 是 fork 标记，不是应排除的模板标记。人工 steering、未结束或截断答复保留为原文，工具记录仍由完整原生视图提供。
+
+每个工作区共享一个服务端整理器，正常主交互结束后安排，其他父会话尚在交互或有待输入时不启动；新人工输入和下一原生 step 会取消整理。原生 `llm.prepareCall` 与 `stream` 复用当前模型及认证，采用宿主声明的最低 reasoning effort，单独处理纯文本且不写主聊天。摘要和扫描均在短写锁外准备，提交时重读；原文或子节点变化时放弃旧结果，已经保存的摘要优先。失败保留待整理节点并暴露警告，查询不会调用模型。
+
+本地类型、依赖检查（121 个模块、497 条依赖）、构建、差异检查和 28 项定向组合已通过，覆盖 AgentRun、Pi 通知、全部 dsh 测试及 history。新增测试使用真实 Session、双来源归档和两个 Node 进程；FIFO 仅承载真实 SDK JSONL，用操作系统读写屏障验证慢扫描不能覆盖另一进程的新索引，没有替代来源或模型。测试还覆盖同一原生 ID 的来源区分、来源损坏隔离、旧 Pi 身份与摘要、冷读不激活、取消查询不取消后续刷新、过期摘要拒绝、实际缺失提供方的失败，以及同工作区关闭一个父会话后继续查询。随后补充未加载索引状态区分，相关 10 项 history/工作区回归及检查、构建和差异检查再次通过。
+
+同时收紧了两项原生边界：最终答复需要持久流的 `stop` 标记，工具调用文本和 token 截断不满足成功条件；团队投递使用原生 maintenance 的空闲准入，避免把其公开的 `idle` 状态当作真正空闲。真实 Bash maintenance 验证团队要求在维护结束前没有进入 inbox。外部原生句柄占用也计入存活，恢复被拒绝且 generation 不变；当前组件不能假称已释放别的执行实例。组件卸载会撤销其挂在父会话上的 effect，释放历史缓存。
+
+Web 管理已接入固定版公开的 `TypertRemoteService`、`Remote` 和 Typert 注册接口。四个查询描述符由 Host 与 Client 共用，Host 按组件注册，Client 通过原生 `$mount` 挂载；没有私有 HTTP 或额外类型编译框架。读取、轮询和完整原生记录使用查询方法；原生命令会追加 `command/run`/`command/done`，不能拿它反复轮询页面。原生记录按事件分页，正文与完整事件都能继续读取长内容，停止后的专家仍可冷读。人工写操作复用命令、工具的业务动作，命令不重复记录私人输入正文。
+
+`/pbot` 的裸调用打开工作区、专家、团队和历史管理页；带参数的原生命令支持 `agent`、`chat`、`team`、`post`、`history`、`records`。页面保存自己的表单与选择，只取消查询，已经接纳的执行归服务端所有。人工对话支持服务器文件及原生输入框已准入附件，先成功暂停所属团队再进入 inbox；人工输入待进入时停止追加团队上下文。原生 registry 的根归属用于识别协调者，不只依靠可选的 origin 标签。改变 provider 或 model 时，不再把父会话的 reasoning effort 带到另一模型。
+
+新增真实 SDK 管理测试覆盖只读查询不写主会话、不启动空专家、完整记录分页、停止后冷读、父归属、未标注 origin 的原生子 Agent、组件卸载后的失效、暂停锁失败时不接纳人工消息，以及实际缺失 provider 的失败。该测试没有模拟模型。
+
+本机全量回归发现测试环境只隔离 XDG 路径，不符合 macOS Python 按 HOME 定位的规则，并有临时目录 `/var` 别名与 `/private/var` 不一致的问题。已停止首次全量运行；核查个人 Python 环境元数据，未发现首次全量日志创建之后修改的文件或目录条目，没有删除或回滚。此前本机测试不能作为完整 Python 环境隔离的证据。测试现在使用临时 HOME，让真实脚本以 `--check` 确定环境位置，再放入无关数据；真实 Python 仍用于解释器与计算检查。32 项定向回归通过，随后全量为 120/122，余下两项是旧 fixture 固定 Linux 路径和 `/usr/bin/python3` 的假设。修正后相关 E2E/包检查 4 项通过，随后本机完整 `npm run check`、`npm test` 和 `git diff --check` 通过，122/122 项测试成功。该结果不替代 Linux 验收。
+
+正常 `prepack` 生成的 tarball 已通过原生插件命令装入新的隔离 Web profile，并使用真实 Chrome 验证四个 Remote 的实际传输。管理页新增本机附件选择：通用文件使用原生 `fileUpload` 的 Session 凭证，图片按原生命令的编码图片契约准入；不发送任意附件引用，也不实现私有上传路由。32 个附件的数量限制与取消由实际输入路径检查。上传期间保留新编辑的草稿，关闭视图取消尚未接纳的上传，已接纳命令继续属于服务端。
+
+本轮浏览器验收通过：
+
+- 创建无任务专家；轮询保留人工草稿，不发管理写命令。
+- 上传 524,305 字节文件与 1×1 图片，原生专家记录保留相应文件长度、图像引用和完整人工文本；长 JSON 事件可分段重组。
+- 创建两个固定成员的团队，发布 20,000 字符公共消息；翻到后续正文后轮询保留页码与草稿。
+- 真实缺失 provider 使批次暂停，没有伪造提供方或成功模型答复。
+- 停止后的专家可冷读，显式新任务恢复成功接纳；history 可以检索失败交互并读取原文。
+- 页面刷新前后父身份一致，专家保持存活；全流程观察到恰好 9 次管理写命令，查询与轮询未追加写命令；`pageerror` 为空。
+
+文件确认也通过实际原生 Web 审批：仅有的一次允许产生 `allowed-once` 并写入测试目录中的目标；等待期间改变符号链接后，即使允许也拒绝执行，两个原文件不变；真实信号取消产生 `cancelled`，目标未创建。验证命令只存在于临时 profile，使用公开 Session API 打开审计轮次并直接执行原生工具，没有生成模型响应。证据位于 `/tmp/pbot-dsh-web-D/upload/`、`/tmp/pbot-dsh-web-D/file-proof/` 和 `/tmp/pbot-dsh-browser/`，临时文件可能被清理。
+
+固定版原生默认工作区使用操作系统 Documents 查询，macOS 上不会随测试 HOME 自动改变。测试 profile 已配置 `documentsDirectory`，并通过真实目录选择器选入临时工作区；pbot 的准备、专家、团队及 history 写入验收均在该目录内完成。
+
+接入基线的本机检查已通过：`npm run check`、`npm test`、`git diff --check` 退出码 0，122/122 无跳过，测试耗时约 54.1 秒，覆盖附件与资源新增逻辑。依赖边界为 130 个模块、532 条依赖。专家不再显示无法调用的父 history 工具；真实 SDK 验证 noSkills、工具限制、包内技能读取及工作区技能隔离。Web 状态刷新也丢弃过期响应，避免旧查询覆盖新状态。
+
+正常 `npm pack --dry-run` 与 prepack 打包通过。实际 tarball 在独立消费者中只安装包自身运行时依赖，没有 Pi/dsh SDK 副本；Node.js 22.19.0 下独立 CLI、Pi 四工具与技能加载、资料初始化、空专家查询通过。固定版 dsh 原生安装最终运行代码后，附件、长记录、团队、history、冷读、恢复与刷新再次通过，观察到 9 次管理写命令，轮询未增加写命令，浏览器错误为空。证据：`/tmp/pbot-dsh-docs/check-E-final.*`、`/tmp/pbot-dsh-final/`。
+
+真实 Web 停用插件会移除命令并释放专家，重新启用后保持停止且可冷读；关闭管理页不停止专家。完整浏览器进程关闭后再打开，原父身份与两个专家的存活状态保持。资料准备可重复执行并保留文件。证据：`/tmp/pbot-dsh-web-D/unload-verified.json` 和 `/tmp/pbot-dsh-final/reconnect.json`。
+
+本机桌面应用 0.2.2-rc.1（内置 Node.js 24.21.0）也完成实际验收：独立 Electron userData、DSH_HOME、HOME 与 Documents 目录，通过原生插件 UI 安装 tarball、启用并执行完整管理流程。附件、长记录、团队失败暂停、history、恢复与刷新通过，10 次管理写命令且页面错误为空；32 MiB 上传在关闭面板后取消，没有提交 chat 或追加 inbox。完整退出应用会停止专家，重开及插件重新启用均不自动恢复。临时登录 Shell 的 PATH 提供 Python 3.12 后，应用真实安装锁定依赖并达到 ready，pip check 和 5 项原生库测试通过。隔离实例模型选择器显示 `No models available`；原日常应用进程保持运行，测试进程已退出。详见[桌面验收记录](validation.md#macos-桌面应用实测)，证据在 `/tmp/pbot-dsh-desktop-test/`。
+
+后台模型整理成功、输入优先取消真实模型请求、成功专家/团队协作、模型实际使用资源与团队上下文，以及最新 Linux 全量仍未验收。SSH 最后重试仍超时；无模型检查和旧版 Pi 冒烟不能替代本次真实提供方工作流。
+
+## 优先核查的风险
+
+| 风险 | 验证与处理 |
+| --- | --- |
+| 空会话延迟落盘 | 真实创建、公开 flush、释放、冷读取与恢复；不插入假消息促使落盘 |
+| 恢复自动消费旧 inbox | 在 setup 中清除旧输入，验证发布前顺序；只接受新 generation |
+| 服务端所有权与页面生命周期耦合 | 两个父会话、断开观察、组件卸载分别验证 |
+| 同进程专家无法强杀 | 验证协作取消及 dispose；阻塞时保持真实状态和占用 |
+| 客户端发布格式或依赖解析不匹配 | 使用真实 tarball 在隔离 Web profile 加载，检查 Remote 与原生 UI |
+| Pi 既有存储被异步改动破坏 | 先完成 Pi 回归，再接入 dsh；原始数据不迁移 |
+| 固定预发布包缺少必要公开能力 | 保存可复现证据与具体影响，报告需重审的决定，不静默改版本或缩减范围 |

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)。