personal-bot 0.2.3 → 0.2.5

package/CONTEXT.md

@@ -20,11 +20,13 @@
 
 **工作区记忆**：跨会话查找、使用和修正所属资料的能力。正文只维护一份；保留的知识不证明当前事实、软件可用性或操作授权。
 
+**历史消息树（history）**：由问答原文、分层摘要、父子关系及来源引用组成的历史资料，供两个宿主共同检索。各宿主维护自己来源的历史；它不包含完整工具日志、推理或图片二进制，也不用于恢复另一宿主的会话。
+
 **项目资料维护**：根据已有工作结果与证据，整理和更新当前任务、直接关联资料及进行中任务的资料，由助手判断相关内容是否更新完整。可由用户主动发起，或由助手在正常交互中识别更新需要。
 
 **能力提供方（provider）**：通过 CLI 或 MCP 提供数据查询、计算或业务操作的外部系统。它不同于 `src/services/` 中的业务服务。
 
-**原生接入**：复用 CLI 的命令与认证，或使用 Pi 原生 MCP 配置、工具发现与调用。Personal Bot 不保存另一套操作目录或逐工具权限。
+**原生接入**：复用 CLI 的命令与认证，或使用当前宿主原生的 MCP 配置、工具发现与调用。Personal Bot 不保存另一套操作目录或逐工具权限。
 
 **受控变更**：经精确准备、必要复核和用户授权后执行的业务状态改变。交易是其中一类，不代表全部变更。
 
@@ -34,10 +36,14 @@
 
 **调用约定**：原生操作的输入、结果与执行要求，按当前版本的帮助或协议定义核对。
 
-**工作区**：组织学习资料、长期事务、项目、能力接入与执行记录的工作范围。用途可以组合；投资任务可覆盖多个市场。用户资料可以共享，应用状态独立保存。
+**工作区**：组织学习资料、长期事务、项目、能力接入与执行记录的工作范围，用途可以组合，投资任务可覆盖多个市场。业务约定、用户资料和历史消息树可以跨宿主使用，原生会话与运行状态独立保存。
 _避免_：用工作区表示单个会话或真实账户。
 
-**Personal Bot 启用**：Pi 按原生配置加载 Personal Bot 扩展。没有独立的工作区就绪状态；资料和外部服务是否准备好不影响加载，也不证明某项能力可用或已获执行许可。
+**Personal Bot 启用**：当前宿主按原生配置加载 Personal Bot 扩展。没有独立的工作区就绪状态；资料和外部服务是否准备好不影响加载，也不证明某项能力可用或已获执行许可。
+
+**配套插件**：与 Personal Bot 配合提供附加能力、可独立安装的组件。其依赖的外部服务不属于插件本体，安装插件不代表服务已准备好。
+
+**配套插件清单**：维护者为 Personal Bot 安装提供的候选插件集合，用户从中选择本次需要的插件。清单不等同于工作区实际安装内容；移出清单不表示卸载已有插件。
 
 ## 任务管理
 
@@ -49,21 +55,21 @@ _避免_：用工作区表示单个会话或真实账户。
 
 **协调者**：协助用户学习和积累知识、推进任务与项目、开展研究并支持决策的主助手，负责方案建议、专家协作和已授权操作的结果跟踪。
 
-**通用专家（general-purpose）**：pbot 唯一可委派类型，在独立子会话中完成研究、分析、计算或独立复核，按任务选择专业方法。start 使用新上下文，send 可继续既有上下文；独立复核须新建会话。通用职责不表示可以超出委派范围或绕过用户授权。
+**通用专家（general-purpose）**：pbot 唯一可委派类型，在具有独立上下文和任务归属的子会话中完成研究、分析、计算或独立复核，按任务选择专业方法。start 使用新上下文，send 可继续既有上下文；独立复核须新建会话，通用职责不扩大委派范围或用户授权。
 
 **独立复核者**：在新会话或独立任务节点中核验具体方案的事实与约束，给出通过、拒绝或无法确认结论的助手，不是另一个可委派的 pbot 角色类型。
 
 **专家协作**：保留独立委派与团队工作。协调者组织和验收，团队成员可直接交换原文；轮流讨论或并行轮次由代码安排，不依赖协调者模型逐条转述。它不规定固定研究流程，不替代用户授权，也不承载 Task Conductor 的持久调度。
 
-**团队（team）**：同一父会话中的固定成员和公共记录，以 teamId 标识。成员仍有各自的私人 Pi 上下文；团队关闭不销毁成员或清除记忆。
+**团队（team）**：同一父会话中的固定成员和公共记录，以 teamId 标识。成员仍有各自的私人会话上下文；团队关闭不销毁成员或清除记忆。
 
 **团队批次（team run）**：以 runId 标识的一批有限轮次，采用 roundRobin 或 parallel。后者同轮并行、轮间汇合；结束不代表业务完成，暂停或恢复不自动重跑旧请求。该 runId 与 Task Conductor 的 runId 分属不同系统。
 
 **专家职责**：通用专家 general-purpose 的工作范围与交付责任，不是子会话实例标识。工作区仅 coordinator.md 和 general-purpose.md 的职责补充会被加载。
 
-**子会话（agent）**：由 start 创建的独立 Pi 会话，以 agentId 标识；新布局中它也是原生 session ID，对话文件由 Pi 管理。工作结束后可用 send 继续对话；停止后用 resume 携新要求显式恢复，不重放旧工作。它绑定父会话与创建分支，不是持久任务调度器。
+**子会话（agent）**：由 start 创建、以 agentId 标识的独立专家会话，绑定父会话与创建分支，归属创建它的宿主。工作结束后可用 send 继续对话；停止后用 resume 携新要求显式恢复，不重放旧工作，也不跨宿主接管。
 
-**工作周期（cycle）**：子会话从开始处理到本轮结束的一次活动，以 cycleId 标识。一个周期可处理多条消息；进程空闲不代表上轮工作成功。
+**工作周期（cycle）**：子会话从开始处理到本轮结束的一次活动，以 cycleId 标识。一个周期可处理多条消息；空闲状态不代表上轮工作成功。
 
 **消息请求（request）**：父侧提交的一条子会话消息，以 requestId 标识。入队或接收不证明模型已阅读或任务已完成。
 

package/README.md

@@ -4,15 +4,38 @@ English | [简体中文](README.zh-CN.md)
 
 **A personal assistant connecting knowledge, research, and action.**
 
-Personal Bot is currently a workspace-scoped [Pi](https://pi.dev) extension for learning, project work, research, and decision support, including investment analysis and explicitly authorized operations.
+Personal Bot provides a workspace-scoped [Pi](https://pi.dev) extension and a native Web integration for a fixed dsh release. It supports learning, project work, research, decision support, investment analysis, and explicitly authorized operations. See the [dsh guide](docs/dsh.md) for its usage and acceptance limits.
 
 The model handles analysis, coordination, and native tools. Personal Bot adds workspace materials, specialist collaboration, and Python environment preparation. It does not create a second main agent or start tasks or trades automatically.
 
 ## Install
 
-Requirements: Linux, Node.js 22.19+, and Pi with a configured model and authentication. Python computation requires Python 3.11+. Development and local tests currently use Pi 1.4.0; other host versions need separate validation. Native MCP and the optional Task Conductor integration require Pi 1.4.0+.
+The Pi installer supports Linux and macOS. It requires Node.js 22.19+, npm, and Python 3.11+ with venv/ensurepip. Run in an interactive terminal:
 
-From your workspace root:
+```bash
+npx personal-bot@latest setup
+# Or select the workspace directly
+npx personal-bot@latest setup --workspace ~/pbot-workspace
+```
+
+The wizard selects an existing or new directory, installs or updates the shared Pi executable, and installs pbot in that workspace. It offers `task-conductor-plugin` and `pi-web-access`, both selected by default on the first installation. Later runs preselect existing packages. Each normal npm package updates to its latest stable version. Local sources, Git sources, and pinned versions are kept unless you choose to switch. Deselecting a plugin or removing it from the maintained catalog does not uninstall it.
+
+Missing tmux is installed through an existing Homebrew or supported Linux package manager. Missing Python prerequisites produce repair instructions. pbot prepares its shared Python venv on startup. After installation, the wizard offers to start Pi and run `/pbot init`; the existing command owns workspace material creation. Pi handles project trust, login, and model selection. Installation does not call a model.
+
+For a persistent short command, install the package separately:
+
+```bash
+npm install -g personal-bot@latest
+pbot setup
+```
+
+This global npm installation provides the command; it does not register a global Pi extension. `pbot setup` uses the globally installed installer version. Update it with npm, or use `npx personal-bot@latest setup` for the latest installer. The npx command does not install itself globally.
+
+A core failure stops startup. An optional plugin failure allows the other plugins to proceed and is reported before you choose whether to start Pi. Completed steps remain in place; fix the cause and rerun setup. There is no automatic rollback across package managers. See the [installation design](docs/installation-design.md) for scope and recovery rules.
+
+### Install directly with Pi
+
+If Pi is already installed, run from your workspace root:
 
 ```bash
 pi install --local npm:personal-bot
@@ -21,16 +44,23 @@ pi
 
 `--local` saves the package declaration in the project's `.pi/settings.json`. Review and grant project trust when Pi prompts you, and start Pi from the workspace root. Loading Personal Bot enables its roles, skills, tools, and shared Python environment preparation. There is no separate activation switch.
 
-Avoid a global installation unless you want Personal Bot in every Pi session. Use Pi package management or `pi config` to adjust an existing installation's scope. Do not load both the npm and source installations.
+Use `pi install` without `--local` only when you want the extension in every Pi session. Use Pi package management or `pi config` to adjust an existing installation's scope. Do not load both the npm and source installations. The existing development and test baseline is Pi 1.4.0; installer acceptance limits are recorded in [validation](docs/validation.md).
 
 ### Install from source
 
-For development:
+To try the installer from source:
 
 ```bash
 git clone https://github.com/realqiyan/personal-bot.git
 cd personal-bot
 npm ci --ignore-scripts
+npm run build:cli
+node bin/pbot.mjs setup
+```
+
+To load only the source extension:
+
+```bash
 cd /path/to/workspace
 pi install --local /absolute/path/to/personal-bot
 pi
@@ -38,6 +68,12 @@ pi
 
 Replace the example paths with your actual paths. A local installation loads the source directory directly, so keep that directory and its dependencies available.
 
+### Use with dsh
+
+The integration targets `@deepseek-ai/dsh@0.2.2-rc.1` and requires Node.js 24.9+. Build a tarball from the current source with normal `npm pack`, create a separate `pbot` Web profile, and install it with `dsh plugin --profile pbot add <tarball>`. Follow the [dsh guide](docs/dsh.md); `pbot setup` remains the Pi installer.
+
+The bare `/pbot` action opens workspace, specialist, team, and history management. Specialists use native Agent/Session instances in the server process. Refreshing a page does not stop accepted work. Both hosts query the saved history archives while each maintains its own source. Models, authentication, and MCP remain under native host configuration. Real model workflows and the latest Linux checks remain subject to the [validation record](docs/validation.md).
+
 ### Optional: Task Conductor
 
 For scheduled tasks, recurring workflows, or DAGs, install `task-conductor-plugin`. This integration package is distinct from the `task-conductor` service and is not required for Personal Bot. It requires Pi 1.4.0+ with native MCP support and npm.
@@ -62,10 +98,11 @@ Keep goals, markets, preferences, and working agreements in ordinary documents.
 
 ## Daily use
 
-Describe the task directly: organize project materials, compare research findings, delegate an independent review, or run calculations. No fixed workflow is required.
+Describe the task directly: organize project materials, compare research findings, delegate an independent review, or run calculations. No fixed workflow is required. The command table and process details below describe Pi; see the [dsh guide](docs/dsh.md) for its Web interface and commands.
 
 | Command | Purpose |
 | --- | --- |
+| `/pbot` | Open the workspace menu |
 | `/pbot init` | Create missing material directories and root `AGENTS.md` |
 | `/pbot status` | Show workspace path, Personal Bot version, and Python environment status |
 | `/pbot history [text]` | Search historical exchanges and summaries; read originals and navigate their parents and children |
@@ -94,7 +131,7 @@ Personal Bot maintains no separate provider-call ledger or result wrapper. Nativ
 | `AGENTS.md` | Material navigation and working agreements |
 | `areas/`, `projects/` | Long-term goals, task definitions, conclusions, and deliverables |
 | `knowledge/` | Reusable concepts, methods, and analysis definitions |
-| `.pi/pbot/history/` | Saved exchanges, summaries, and node links that can travel with the workspace |
+| `.pi/pbot/history/`, `.dsh/pbot/history/` | Saved exchanges, summaries, and node links, maintained by source and queried together |
 | `providers/` | Provider guides, coverage gaps, and validation evidence |
 | `scratch/` | Temporary scripts, query and calculation data, downloads, and runtime environments |
 | `agents/`, `.agents/skills/` | Workspace additions to coordinator/general-purpose roles and workspace skills |
@@ -105,7 +142,7 @@ Personal Bot stores no private activation state in the workspace. Pi owns its co
 
 ## Updates and historical data
 
-Current release: **0.2.3**. Personal Bot maintains no workspace format, initialization state, or workspace upgrade mechanism. Update the plugin through Pi package management. For a local installation, update the source, run `npm ci --ignore-scripts` if dependencies changed, then reload or restart Pi.
+Current release: **0.2.5**. Personal Bot maintains no workspace format, initialization state, or workspace upgrade mechanism. Update the plugin through its native host package manager. For a local Pi installation, update the source, run `npm ci --ignore-scripts` if dependencies changed, then reload or restart Pi.
 
 Stop active sub-sessions before changing versions. Sub-session compatibility follows the minor version before 1.0 and the major version from 1.0 onward. Sessions from another compatibility line cannot be resumed directly.
 
@@ -128,7 +165,7 @@ npm test
 git diff --check
 ```
 
-`npm test` includes smoke and E2E tests and generates `dist/` for test imports. Runtime loading uses source files directly. Inspect package contents with `npm pack --dry-run`. See [validation](docs/validation.md) for test groups and limits.
+Full development and acceptance for both hosts require Linux and Node.js 24.9+. `npm test` includes smoke and E2E tests and generates `dist/` for tests and `lib/` for the CLI and dsh Host/Web entries. Pi still loads the extension source directly. Inspect package contents with `npm pack --dry-run`. See [validation](docs/validation.md) for test groups and limits.
 
 The README is available in English and Simplified Chinese. Detailed design documents and bundled guides are currently primarily in Chinese.
 

package/README.zh-CN.md

@@ -4,31 +4,61 @@
 
 **个人助手，连接知识、研究与行动。**
 
-当前基于 Pi 实现，提供按工作区加载的扩展，用于学习、项目推进、研究与决策支持，也支持投资分析与已授权业务。
+提供 Pi 工作区扩展和固定版 dsh 原生 Web 接入，用于学习、项目推进、研究与决策支持，也支持投资分析与已授权业务。dsh 的使用和当前验收范围见[专门说明](docs/dsh.md)。
 
 定位为可信模型驱动的个人助手。模型负责分析、协调与原生工具使用；pbot 提供资料入口、专家协作和 Python 环境准备。不另建主 Agent，不自动开展任务或交易。
 
 ## 安装
 
-需要 Linux、Node.js 22.19+，以及已配置模型和认证的 Pi。Python 计算需要 Python 3.11+。当前开发与测试使用 Pi 1.4.0，其他宿主版本需另行验证。
+下面的安装器面向 Pi，支持 Linux 和 macOS，需要 Node.js 22.19+、npm、Python 3.11+ 及 venv/ensurepip。在终端运行：
 
-从目标工作区根目录安装 npm 包并启动：
+```bash
+npx personal-bot@latest setup
+# 也可直接指定工作区
+npx personal-bot@latest setup --workspace ~/pbot-workspace
+```
+
+向导支持选择当前目录、已有目录或新建目录，安装或升级当前用户共用的 Pi，并在所选工作区安装 pbot。配套插件 `task-conductor-plugin`、`pi-web-access` 首次默认勾选，可取消；重复运行时按已有安装预选。各组件独立更新到最新稳定版，本地源码、Git 和固定版本默认保留，可显式切换。取消勾选或从维护者清单移除插件不会卸载已有安装。
+
+缺少 tmux 时使用已有的 Homebrew 或受支持的 Linux 包管理器安装。基础 Python 不满足要求时先给出修复指引；共享 venv 在 pbot 加载后自动准备。完成后默认提供启动 Pi，并执行 `/pbot init`，资料文件仍由原有命令补建。Pi 原生处理项目信任、登录和模型选择，安装本身不调用模型。
+
+需要长期使用短命令时，可另行安装：
+
+```bash
+npm install -g personal-bot@latest
+pbot setup
+```
+
+这里的全局 npm 安装只提供 `pbot` 命令，不向 Pi 注册全局扩展。`pbot setup` 使用全局安装的安装器版本；用 npm 更新它，或继续使用 `npx personal-bot@latest setup` 获取最新安装器。安装器不自动全局安装自己。
+
+核心步骤失败时停止启动，可选插件失败时继续处理其他项并汇总。成功步骤保留，修复后重跑同一命令；不自动整体回滚。工作区作用域、版本选择和边界见[安装与升级](docs/installation-design.md)。
+
+### 直接使用 Pi 安装
+
+已有 Pi 时，也可从目标工作区根目录安装并启动：
 
 ```bash
 pi install --local npm:personal-bot
 pi
 ```
 
-`--local` 将包声明保存在项目 `.pi/settings.json`。按 Pi 提示确认项目信任，每次从工作区根目录启动。Pi 加载 Personal Bot 就会启用角色、技能、工具及共享 Python 环境准备；没有第二个启用开关。不要全局安装，除非希望所有 Pi 会话都启用 Personal Bot。已有全局安装请用 Pi 原生包管理或 `pi config` 调整加载范围。
+`--local` 将包声明保存在项目 `.pi/settings.json`。按 Pi 提示确认项目信任，每次从工作区根目录启动。Pi 加载 Personal Bot 就会启用角色、技能、工具及共享 Python 环境准备；没有第二个启用开关。除非希望所有 Pi 会话都启用 Personal Bot，否则不要用省略 `--local` 的 `pi install` 注册全局扩展。已有全局安装请用 Pi 原生包管理或 `pi config` 调整加载范围。开发与原有测试基线为 Pi 1.4.0，安装器验收范围见[验证](docs/validation.md)。
 
 ### 从源码安装
 
-开发时可改用本地源码：
+开发时可改用本地源码；试用源码中的安装器先构建 CLI：
 
 ```bash
 git clone https://github.com/realqiyan/personal-bot.git
 cd personal-bot
 npm ci --ignore-scripts
+npm run build:cli
+node bin/pbot.mjs setup
+```
+
+若只需将源码作为 Pi 扩展加载：
+
+```bash
 cd /path/to/workspace
 pi install --local /absolute/path/to/personal-bot
 pi
@@ -36,6 +66,12 @@ pi
 
 将示例路径换成实际路径。本地安装直接加载来源目录，请保留源码和依赖。不要同时加载源码与 npm 两个来源。
 
+### 使用 dsh
+
+dsh 接入固定为 `@deepseek-ai/dsh@0.2.2-rc.1`，使用 Node.js 24.9+。从当前源码正常 `npm pack` 后，按[dsh 使用说明](docs/dsh.md)建立独立 `pbot` Web profile，并通过 `dsh plugin --profile pbot add <tarball>` 安装。`pbot setup` 不配置 dsh。
+
+Web 的裸 `/pbot` 打开工作区、专家、团队和历史管理页。专家使用同进程的原生 Agent/Session；页面刷新不停止已接纳工作。两种宿主共同读取历史归档，各自维护自己的来源，模型、认证和 MCP 配置分别由原生宿主管理。真实模型与最新 Linux 验收仍见[验证记录](docs/validation.md)。
+
 ### 可选安装 Task Conductor
 
 需要周期任务、重复流程或 DAG 时，安装接入包 `task-conductor-plugin`。它不是服务包 `task-conductor`，也不是启用 pbot 的前提。该接入方式需要 Pi 1.4.0+ 的原生 MCP 和 npm。
@@ -60,10 +96,11 @@ pi install --local npm:task-conductor-plugin
 
 ## 日常使用
 
-直接向助手说明任务，例如整理项目资料、比较研究结论、委派独立复核或运行计算。无需手动编排固定流程。
+直接向助手说明任务，例如整理项目资料、比较研究结论、委派独立复核或运行计算。无需手动编排固定流程。以下命令表与进程说明面向 Pi；dsh 的命令和 Web 操作见[专门说明](docs/dsh.md)。
 
 | 命令 | 用途 |
 | --- | --- |
+| `/pbot` | 打开工作区菜单 |
 | `/pbot init` | 可选地补建资料目录和缺失的根 `AGENTS.md` |
 | `/pbot status` | 查看工作区路径、Personal Bot 版本和 Python 环境状态 |
 | `/pbot history [关键词]` | 搜索历史问答与分层摘要，查看原文和上下层节点 |
@@ -92,7 +129,7 @@ pi install --local npm:task-conductor-plugin
 | `AGENTS.md` | 资料导航与工作约定 |
 | `areas/`、`projects/` | 长期目标、任务定义、结论与交付物 |
 | `knowledge/` | 可复用的概念、方法与口径 |
-| `.pi/pbot/history/` | 可随工作区分享的问答原文、摘要与节点关系 |
+| `.pi/pbot/history/`、`.dsh/pbot/history/` | 按来源保存、可共同查询的问答原文、摘要与节点关系 |
 | `providers/` | 提供方手册、覆盖缺口与验证依据 |
 | `scratch/` | 临时脚本、查询与计算数据、下载及运行环境 |
 | `agents/`、`.agents/skills/` | coordinator/general-purpose 职责补充与工作区技能 |
@@ -103,7 +140,7 @@ Personal Bot 不在工作区内保存私有启用状态。Pi 配置仍由 Pi 管
 
 ## 更新与历史数据
 
-当前版本为 **0.2.3**。不维护工作区格式、初始化状态或升级机制。插件更新使用 Pi 原生包管理；本地安装则更新来源源码，依赖变化后执行 `npm ci --ignore-scripts`，再重载或重启 Pi。更换版本前先停止活动子会话；不同兼容线的子会话不能直接恢复。
+当前版本为 **0.2.5**。不维护工作区格式、初始化状态或升级机制。插件更新使用对应宿主的原生包管理；Pi 本地安装则更新来源源码，依赖变化后执行 `npm ci --ignore-scripts`，再重载或重启 Pi。更换版本前先停止活动子会话；不同兼容线的子会话不能直接恢复。
 
 子会话 JSONL 由 Pi 保存在原生 sessions 目录或原生配置指定的位置；`pbot/subagents/` 只保存控制记录与会话引用，团队公共记录保存在 `pbot/teams/`。0.2.0 不兼容旧会话位置，不迁移或删除 0.1.x 历史；旧记录不进入当前列表或后台调度。先在旧版停止活动成员，更新后重新创建 agent。共享 Python 环境使用用户级 `pbot/python/.venv`，具体系统路径见 [Python 说明](python/README.md)。不自动导入其他应用的会话、配置或环境，也不修改其数据。MCP 连接与 CLI 环境按原生方式显式配置；用户资料、历史证据和备份原样保留。
 
@@ -124,7 +161,7 @@ npm test
 git diff --check
 ```
 
-`npm test` 包含冒烟和 E2E 测试，并生成测试用 `dist/`；运行时直接加载源码。包内容可用 `npm pack --dry-run` 检查。测试分组与限制见[验证](docs/validation.md)。
+双宿主完整开发与验收使用 Linux、Node.js 24.9+。`npm test` 包含冒烟和 E2E 测试，并生成测试用 `dist/` 及 CLI、dsh Host/Web 的 `lib/`；Pi 扩展运行时仍直接加载源码。包内容可用 `npm pack --dry-run` 检查。测试分组与限制见[验证](docs/validation.md)。
 
 - [开发文档索引](docs/README.md)：架构、工具、专家协作、存储与验证。
 - [npm 发布](docs/release.md)：配置、授权、发布与安装验收。

package/bin/pbot.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from "../lib/extension/setup-cli.js";
+process.exitCode = await main(process.argv.slice(2));

package/docs/README.md

@@ -6,14 +6,17 @@
 | --- | --- |
 | [架构原则](architecture-guidelines.md) | 模块划分、依赖和开发方法 |
 | [技术设计](technical-design.md) | 系统组成、生命周期与资源加载 |
+| [界面设计](interaction-design.md) | Pi TUI 与 dsh GUI |
+| [dsh 使用](dsh.md) | 固定版本、原生 profile 安装、Web 管理与宿主差异 |
 | [工具与执行](capability-design.md) | CLI/MCP 接入、授权和结果核验 |
 | [专家协作](agent-collaboration.md) | 子会话工具、通信、通知和生命周期 |
 | [历史对话](history.md) | 自动收录、连续摘要树、全文查询与原文展开 |
 | [文件存储](file-storage.md) | 数据位置、写入规则和历史保留 |
 | [验证](validation.md) | 本地测试、真实模型冒烟结果与剩余验收 |
 | [npm 发布](release.md) | 发布配置、授权、操作与验收 |
+| [安装与升级](installation-design.md) | npx setup、工作区选择、插件安装、初始化与失败恢复 |
 
-增量设计与范围取舍见 [Subagent 升级方案](subagent-upgrade-proposal.md)。团队策略在 0.1.3 实现，0.2.0 将子会话对话交给 Pi 原生存储，不迁移旧历史。当前用法见专家协作；0.1.3 的真实模型冒烟、0.2.0 本地验证与剩余验收见验证。
+双宿主范围见[dsh 接入方案](dsh-support-proposal.md)，执行与验收进度见[实施记录](dsh-implementation-plan.md)。既有子会话范围取舍见 [Subagent 升级方案](subagent-upgrade-proposal.md)。团队策略在 0.1.3 实现，0.2.0 将子会话对话交给 Pi 原生存储，不迁移旧历史。当前用法见专家协作；0.1.3 的真实模型冒烟、0.2.0 本地验证与剩余验收见验证。
 
 Python 环境与库许可见 [python/README.md](../python/README.md)。模型使用的方法维护在 resources/skills，运行时职责维护在 resources/agents。
 

package/docs/agent-collaboration.md

@@ -1,6 +1,6 @@
 # 专家协作
 
-Personal Bot 保留独立工作和团队工作。成员仍由 tmux 和独立 Pi 进程运行，各自保留原生 JSONL 上下文。主模型负责组织与验收，成员原文由代码同步，不需要主模型逐条转述。
+Personal Bot 保留独立工作和团队工作。Pi 成员由 tmux 和独立进程运行；dsh 成员使用同进程的独立 Agent/Session。各自保留原生上下文，不跨宿主恢复。主模型负责组织与验收，成员原文由代码同步，不需要主模型逐条转述。
 
 ## 独立工作
 
@@ -14,21 +14,31 @@ Personal Bot 保留独立工作和团队工作。成员仍由 tmux 和独立 Pi
 | stop | 请求停止，保留历史 |
 | resume | 用新 message 重启已停止子会话，不重放旧工作 |
 
-每个父会话最多 50 个存活进程，包括待命进程。启动异步返回，不提供 wait。无任务 start 不请求模型，也不产生工作完成通知；停止未接过任务的进程不伪造失败周期。
+每个父会话最多 50 个存活或启动、释放中的专家，包括待命实例。启动预约也占用限额。启动异步返回，不提供 wait。无任务 start 不请求模型，也不产生工作完成通知；停止未接过任务的进程不伪造失败周期。
 
-start 支持 noExtensions、noSkills、noPromptTemplates 和 noContextFiles。noExtensions 默认 true，显式保留子入口及 Pi 内置 MCP、codemode、工具搜索；设为 false 时按 Pi 规则发现其他扩展。tools 遵循 Pi 原生选择。子入口只增加 pbot_team_message，不提供 pbot_agent 或 pbot_team 管理能力。
+Pi 的 start 支持 noExtensions、noSkills、noPromptTemplates 和 noContextFiles。noExtensions 默认 true，显式保留子入口及 Pi 内置 MCP、codemode、工具搜索；设为 false 时按 Pi 规则发现其他扩展。tools 遵循 Pi 原生选择。子入口只增加 pbot_team_message，不提供 pbot_agent 或 pbot_team 管理能力。
 
-初始 files 相对工作区根目录解析。子入口在每份附件前标出绝对来源路径，保留 Pi 原生 read 的文本、图像及截断提示；未读完的附件由成员沿该路径续读。message 与 prompts 合并为一次输入，不继承父聊天历史。
+以下附件、进程模型与 TUI 说明面向 Pi；dsh 的差异见下一节。初始 files 相对工作区根目录解析。子入口在每份附件前标出绝对来源路径，保留 Pi 原生 read 的文本、图像及截断提示；未读完的附件由成员沿该路径续读。message 与 prompts 合并为一次输入，不继承父聊天历史。
 
 初始模型与思考级别默认继承主会话；恢复时交由 Pi 使用保存的原生模型配置，不重新传入初始模型选项。模型不可用或缺少认证时仍遵循 Pi 的原生回退与错误行为。子会话从自己的 cwd 和 Pi agent dir 取得原生配置与认证，不继承父进程临时注册的模型或 MCP。环境与授权规则见[工具与执行](capability-design.md)。
 
-## 原生会话与恢复入口
+## dsh 专家
+
+dsh 使用原生 provider/model/reasoning effort，拒绝 Pi 专属扩展、提示模板和上下文文件开关。tools 使用原生能力名，noSkills 控制技能；专家不拥有协调者管理工具。只在模型选择仍与父一致时继承父 effort。恢复保留原生选择，不用新父默认值覆盖旧会话。
+
+服务器文件由原生附件存储保留内容，图片使用原生准入；Web 人工对话还接受本机文件与图片。人工对话先成功暂停所属团队，再进入原生 inbox；队列接纳、实际进入、模型消费和完成分别记录，未来排队输入不提前改变此前回答的归因。
+
+每个专家绑定父身份与 generation。启动、校验与释放在短控制锁外等待，预约期间的停止会取消启动；旧代次不能释放新实例。原生 registry 中由其他实例持有的 Agent 不能被替换或假称释放。正常完成要求请求实际消费、持久的正常 stop 和非空最终答复；空闲、工具文本、截断或缺失结束标记都不代表成功。
+
+`/pbot` Web 管理页提供人工对话、完整原生记录、停止和携新要求恢复。离页不停止已接纳工作；父 Agent 或组件关闭会暂停安排并释放其拥有的专家。重新打开页面不会恢复或重放旧工作。详情见[dsh 使用](dsh.md)。
+
+## Pi 原生会话与恢复入口
 
 新建 agent 的 agentId 也是 Pi session ID。对话由 Pi 保存在原生 sessions 目录或其原生配置指定的位置，按子进程 cwd 归组；pbot 只保存控制记录和文件引用。无任务待命不伪造对话，也可能尚无 JSONL 文件。首次输入前固定路径，之后恢复只打开这个文件；文件缺失或不匹配时不新建空白替代。具体规则见[文件存储](file-storage.md)。
 
 有对话后，成员会出现在相应项目的 `pi --resume` / `/resume` 列表，并支持 Pi 原生导出。`pi --continue` 可能选中最近活跃的子会话，不保证选中主会话；需要主会话时从列表中明确选择。
 
-`/pbot agents` 的“进入 TUI”连接运行中的成员；成员已停止时，加载原会话并启动待命进程，不入队新要求、不调用模型、不重放旧工作。尚无对话文件的空会话仍以原 agentId 待命。运行中不另开进程同时写同一 JSONL。停止后从原生列表打开属于普通 Pi 对话，不恢复 pbot 成员身份或团队资格；模型工具 `pbot_agent resume` 仍用于携新要求继续工作。
+`/pbot agents` 的“进入会话”连接运行中的成员；成员已停止时，“打开原会话”加载原会话并启动待命进程，不入队新要求、不调用模型、不重放旧工作。尚无对话文件的空会话仍以原 agentId 待命。运行中不另开进程同时写同一 JSONL。停止后从原生列表打开属于普通 Pi 对话，不恢复 pbot 成员身份或团队资格；模型工具 `pbot_agent resume` 仍用于携新要求继续工作。
 
 ## 团队与两种策略
 
@@ -71,7 +81,7 @@ run 要求全部成员空闲、无未消费的私人输入，并已加载可用
 
 ## 原文、上下文与公开范围
 
-团队公共记录独立于各自私人会话。新团队请求通过原有 inbox 投递；before_agent_start 注入已署名的公共原文，运行中在 turn_end 安全边界追加消息，不请求额外 continuation。空闲成员在下一次团队请求时取得信息，私人工作不自动注入新群消息。
+团队公共记录独立于各自私人会话。Pi 通过原 inbox 投递，在 before_agent_start 和 turn_end 的安全边界注入已署名的公共原文，不请求额外 continuation。dsh 使用原生 inbox 和 pre-step；团队领取先获得原生 maintenance 准入，人工输入待处理或当前步骤已有人工消息时不追加团队背景。空闲成员在下一次团队请求时取得信息，私人工作不自动注入新群消息。
 
 成员任务、团队背景、自动注入的公共消息和批次通知使用 Markdown 文档。团队背景按共同目标和成员职责分节，保留身份与轮次；本批次要求仅在成员任务输入中给出，避免在系统简报中重复。公共消息按 seq 分节，列出作者、回复关系与来源，正文放入保留原文的代码区块，包含代码围栏的正文也不会破坏区块边界。成员原文中的 JSON 保留原样。
 
@@ -87,7 +97,7 @@ read 的文本结果也使用 Markdown，同时保留工具的结构化结果。
 | --- | --- |
 | agentId | 持续上下文 |
 | requestId | 一条父侧输入；团队关联另存，不改变旧 AgentMessage |
-| cycleId | 从工作开始到 agent_settled 的周期，包含内部多次 agent_start、工具与自动恢复 |
+| cycleId | 一次受管工作周期；Pi 以 agent_settled 收尾，dsh 以持久 turn/end 收尾，另行核对消费与最终答复 |
 | teamId / runId | 团队 / 一批有限轮次，不与 Task Conductor 的标识混用 |
 | seq | 团队内公共消息顺序 |
 
@@ -101,14 +111,16 @@ read 的文本结果也使用 Markdown，同时保留工具的结构化结果。
 
 主 agent 收到的独立子会话结果通知，以及 pbot_agent、pbot_team 和 pbot_team_message 的文本结果均使用 Markdown。列表、状态、工作周期和报告分节展示，报告保留原文；通知中的报告最多展示 2000 字符，完整内容通过 read 分页读取。工具的 structuredContent、details 与 read 收据保持原有契约。
 
-独立周期的 read 结果进入当前分支后领取该周期通知，包括只读取部分正文的情况。nextOffset 非空时，以同一 agentId、返回的 cycle.cycleId 和 nextOffset 续读，避免默认最新周期发生变化；status 不领取通知。团队关联周期不重复发个人完成通知；主模型只收到批次结束、暂停和收尾状态。普通 post 不唤醒主模型。团队通知按 teamId/runId/状态去重，UI 或工具 read 不领取模型通知。
+Pi 独立周期的 read 结果进入当前分支后领取该周期通知，包括只读取部分正文的情况。dsh 以持久化的上下文消费或成功模型 read 领取；PTC 内层 read 还需根调用成功，排队仅防重，不视为已消费。人工管理页不领取模型通知。nextOffset 非空时，以同一 agentId、返回的 cycle.cycleId 和 nextOffset 续读，避免默认最新周期发生变化；status 不领取通知。团队关联周期不重复发个人完成通知；主模型只收到批次结束、暂停和收尾状态。普通 post 不唤醒主模型。团队通知按 teamId/runId/状态去重，UI 或工具 read 不领取模型通知。
 
 团队与成员均绑定父 session/分支。失去归属时暂停新安排，不向当前主分支投递结果。fork 不接管旧团队；返回原分支不会自动恢复旧批次。公共记录与外部工作不会随树导航回滚。
 
 | 事件 | 行为 |
 | --- | --- |
 | 独立周期完成 | 保持 idle，可继续对话 |
-| 主 reload | 保留子进程，但暂停团队；可补交付已完成结果，不续排旧批次 |
+| Pi 主 reload | 保留子进程，但暂停团队；可补交付已完成结果，不续排旧批次 |
+| dsh 页面关闭、刷新、重连 | 已接纳工作继续归服务端，查看不恢复旧任务 |
+| dsh 父 Agent 释放、组件停用或卸载 | 暂停安排，取消预约并等待自己的专家资源释放；后续须显式恢复 |
 | 主中断 | 暂停团队新增安排，已领取工作默认收尾 |
 | 主退出或切换 session | 先暂停团队，再按原有约 5 秒宽限清理子进程 |
 | 成员 stop/异常退出/代次变化 | 暂停依赖它的批次，保留记录，不自动 resume |
@@ -120,12 +132,14 @@ pause 返回时可能仍有在途请求。unresolved 区分排队、已接收、
 
 ## UI 与验证边界
 
-/pbot agents 提供状态列表、进入子 TUI、补充要求、重命名和停止，不再提供单独的报告查看或恢复并继续菜单。报告仍可通过 pbot_agent read 获取。/pbot teams 提供团队状态、公共记录分页、post、新批次、pause、close，以及相同的成员菜单。无 TUI 时通过同样的结构化工具使用，不支持 attach。
+dsh 的 Web、原生 Remote、附件、长记录、冷读与恢复，以及真实模型验收缺口见[实施记录](dsh-implementation-plan.md)。下面保留 Pi 的 TUI 使用规则。
+
+`/pbot` 打开工作区菜单。`/pbot agents` 提供专家列表、详情、会话入口、补充要求、重命名和停止；`/pbot teams` 提供团队状态、公共消息、批次及成员入口。长记录使用只读阅读页。完整报告仍通过 `pbot_agent read` 获取；非 TUI 模式保留结构化输出。
 
 后台扫描遇到短暂的 `.control` 锁竞争时，在下一次扫描重试；连续至少 5 秒仍无法取得锁，包括主会话中断后暂停团队仍被锁阻塞的情况，会保留 UI 错误并通知模型。暂停未成功时，通知明确说明暂停尚未确认。报告或控制记录读取失败也会通知模型。同一持续故障在当前分支去重；恢复要求升级时补发一次通知。主会话中断期间延后投递，恢复输入后再通知。
 
 通知按实际服务状态说明恢复方式：锁释放后自动恢复扫描；可恢复的读取错误先排障，修复后由后台重试；团队服务或协作存储已停用时，修复文件仍不能恢复当前实例，须请用户在当前 Pi 会话执行 `/reload`。重载前不反复调用 pbot_team，可通过 pbot_agent list/status/read 核对仍可读取的成员状态与报告；重载后再用 pbot_team status/read 核对团队。成功扫描后清除故障状态。通知不重发任务、不删除锁，命令和工具的错误仍直接返回。
 
-选择成员后，操作菜单的“进入 TUI”选项直接标明返回快捷键，选中后立即进入，不再二次确认。团队成员入口使用相同流程。默认 tmux 绑定下，普通终端按 Ctrl+B 后按 d 脱离子会话；主会话已在 tmux 中时，按 Ctrl+B 后按小写 l 切回上一个会话。自定义绑定以自己的 tmux 配置为准。返回不会停止成员，不要用 /exit 代替返回。
+进入成员前提示返回快捷键，团队成员使用相同入口。默认 tmux 绑定下，普通终端按 Ctrl+B 后按 d 脱离；主会话已在 tmux 中时，按 Ctrl+B 后按小写 l 切回。自定义绑定以自己的配置为准。返回不停止成员，不要用 /exit 代替。
 
 Pi 1.4.0 的本地 SDK、实际无认证 Pi/tmux 进程、文件并发与恢复测试已覆盖基础契约。未使用假模型或模拟 provider。2026-10-28 在 0.1.3 上的真实模型双成员冒烟已通过两种策略的单轮通信、原文引用与主通知；0.2.0 的原生存储调整及 Pi 1.4.0 升级仅做本地 SDK/无认证进程验证，未追加真实模型调用；异构模型、多轮讨论、长期使用与交互 TUI 尚未验收，详见[验证](validation.md)。单轮通过不证明一般协作质量或外部操作恰好一次。

package/docs/architecture-guidelines.md

@@ -8,7 +8,7 @@
 
 ## 复用宿主
 
-Pi 负责主会话、模型配置、工具、UI、资源发现与会话恢复。Personal Bot 补充资料准备、专家协作和 Python 环境。
+各宿主负责自己的主会话、模型配置、工具、UI、资源发现与会话恢复。Pi 和 dsh 分别加载，共享业务服务与资料；不构建通用 Host 平台。Personal Bot 补充资料准备、专家协作和 Python 环境。
 
 角色定义职责，技能描述专业方法，代码实现需要确定执行的规则。优先使用原生 CLI/MCP，执行权限由实际凭据、外部服务和运行环境约束。
 
@@ -26,7 +26,7 @@ Pi 负责主会话、模型配置、工具、UI、资源发现与会话恢复。
 
 ## 验证行为
 
-测试业务契约和具体失败风险，使用真实本地文件、进程、计算和 Pi SDK。测试不依赖假模型、模拟 provider、个人凭据或真实交易，也不以文案和实现结构作为行为断言。
+测试业务契约和具体失败风险，使用真实本地文件、进程、计算和各宿主 SDK。测试不依赖假模型、模拟 provider、个人凭据或真实交易，也不以文案和实现结构作为行为断言。
 
 本地测试与外部验收分别记录，范围见[验证](validation.md)。
 

package/docs/capability-design.md

@@ -1,13 +1,13 @@
 # 工具与执行
 
-Personal Bot 使用 Pi 原生工具与配置。接入方法见[接入技能](../resources/skills/provider-connections/SKILL.md)。
+Personal Bot 使用当前 Pi 或 dsh 宿主的原生工具与配置。接入方法见[接入技能](../resources/skills/provider-connections/SKILL.md)。
 
 ## 责任划分
 
 | 内容 | 所有者 |
 | --- | --- |
 | CLI 参数、校验、认证 | 原生命令、help 与 profile |
-| MCP 连接、认证、发现、schema 与结果 | Pi 原生 MCP |
+| MCP 连接、认证、发现、schema 与结果 | 所属宿主的原生 MCP |
 | 数据口径、项目约定与使用经验 | providers/<id>/GUIDE.md |
 | 任务范围、业务判断与必要确认 | 用户与模型 |
 | 账户权限、额度与强制批准 | 外部服务或执行环境 |
@@ -22,11 +22,13 @@ Pi 处理信任、认证与工具暴露。使用 /mcp 查看连接、工具和
 
 子会话按自己的 cwd 和 Pi agent dir 加载配置。需要工作区项目 MCP 时，以工作区根目录作为 cwd，在命令中切换计算目录。父进程临时注册的连接不会自动转移到子进程。
 
+dsh 使用其固定版本的原生 MCP 组件和 profile 配置，模型与认证也由 dsh 管理。不得将上述 Pi 命令、配置目录或安装包声明直接用于 dsh，也不自动同步两套配置。同进程专家遵循 dsh 的原生作用域与工具可见性；不模拟 Pi 子进程的扩展开关。
+
 ## 授权与结果
 
 模型按用户请求和委派范围行动。研究、查询和接入不包含交易、转账或账本修改的授权。独立复核、用户授权和成果验收分别判断。
 
-Bash、Python、MCP 和扩展拥有其实际账户与凭据权限。文件确认与工具选择是防误操作措施，不是执行隔离；硬性限制使用只读凭据、服务端控制或受限环境。
+Bash、Python、MCP 和扩展拥有其实际账户与凭据权限。dsh 的原生 write、edit、apply_patch 检查原工作区，主会话越界要求一次原生批准，专家越界拒绝；整份 patch 和确认后的路径身份都需有效。文件确认与工具选择是防误操作措施，不是执行隔离；硬性限制使用只读凭据、服务端控制或受限环境。
 
 工具保留原生结果与错误格式，任务按需保存证据。业务完成需核对实际结果，不能只看退出码或协议成功。取消、超时和断连后，先查询原生状态与业务标识，再决定后续操作；聊天或子会话恢复不自动重发可能已执行的操作。
 
@@ -36,7 +38,7 @@ Task Conductor 通过原生 MCP 提供周期任务、重复流程和 DAG，独
 
 提交任务时明确输入、cwd、工具与认证前提、输出和完成条件；周期任务还需明确频率、时区、授权范围及每轮数据时点。项目资料保存必要的 taskId、runId、节点 ID 和证据，实时状态向 Task Conductor 查询。
 
-pbot 子会话绑定父会话，Task Conductor 可在 Pi 关闭后继续。两者分别查询和停止；取消当前 run 与停止未来周期也是两个操作。
+pbot 子会话绑定父会话，Task Conductor 可在所属宿主会话关闭后继续。两者分别查询和停止；取消当前 run 与停止未来周期也是两个操作。
 
 外部节点需单独配置工具、技能、Python 环境和认证，不自动继承主会话能力。需要人工确认的业务不安排无人值守执行。提交结果不明时先按原标识查询，避免重复创建。