personal-bot 0.2.8 → 0.2.10

package/README.zh-CN.md

@@ -2,15 +2,25 @@
 
 [English](README.md) | 简体中文
 
-**个人助手，连接知识、研究与行动。**
+**连接知识、研究与行动的个人助手。**
 
-提供 Pi 工作区扩展和 dsh 原生 Web 接入，用于学习、项目推进、研究与决策支持，也支持投资分析与已授权业务。dsh 的安装、命令和当前验收范围见[专门说明](docs/dsh.md)。
+Personal Bot 提供按工作区加载的 [Pi](https://pi.dev) 扩展和原生 dsh Web 接入，支持资料整理、项目推进、研究分析、专家协作和已授权的业务操作。模型负责分析与协调，插件提供资料目录、专家会话、历史查询和共享 Python 环境。
 
-定位为可信模型驱动的个人助手。模型负责分析、协调与原生工具使用；pbot 提供资料入口、专家协作和 Python 环境准备。不另建主 Agent，不自动开展任务或交易。
+## 工作区启用
+
+安装后，从目标工作区打开 Pi 或 dsh，执行 `/pbot init` 初始化并启用。Pi 和 dsh 共用该命令创建的 `.pbot/config.json`：
+
+```json
+{ "enabled": true }
+```
+
+文件缺失或设为 false 时，Personal Bot 保持未启用，不加载包内技能和提示词，并引导执行 `init`。Pi 状态栏和 dsh 工作区页显示启动状态；`/pbot status` 随时可用。手工修改配置后，Pi 执行 `/reload`，dsh 重启宿主。规则见[工作区配置](docs/workspace-configuration.md)。
 
 ## 安装
 
-下面的安装器面向 Pi，支持 Linux 和 macOS，需要 Node.js 22.19+、npm、Python 3.11+ 及 venv/ensurepip。在终端运行：
+### Pi 安装向导
+
+支持 Linux 和 macOS，需要 Node.js 22.19+、npm，以及 Python 3.11+ 和 venv/ensurepip。在交互终端运行：
 
 ```bash
 npx personal-bot@latest setup
@@ -18,185 +28,132 @@ npx personal-bot@latest setup
 npx personal-bot@latest setup --workspace ~/pbot-workspace
 ```
 
-向导支持选择当前目录、已有目录或新建目录，安装或升级当前用户共用的 Pi，并在所选工作区安装 pbot。配套插件 `task-conductor-plugin`、`pi-web-access` 首次默认勾选，可取消；重复运行时按已有安装预选。各组件独立更新到最新稳定版，本地源码、Git 和固定版本默认保留，可显式切换。取消勾选或从维护者清单移除插件不会卸载已有安装。
+向导选择或创建目录，安装或更新 Pi，再为该工作区安装 Personal Bot。首次默认勾选 Task Conductor 和 Pi Web Access；后续按已有安装预选。普通 npm 来源更新到最新稳定版，本地、Git 和固定版本默认保留，可选择切换。取消勾选会保留已有插件。
 
-缺少 tmux 时使用已有的 Homebrew 或受支持的 Linux 包管理器安装。基础 Python 不满足要求时先给出修复指引；共享 venv 在 pbot 加载后自动准备。完成后默认提供启动 Pi，并执行 `/pbot init`，资料文件仍由原有命令补建。Pi 原生处理项目信任、登录和模型选择，安装本身不调用模型。
+缺少 tmux 时使用已有 Homebrew 或受支持的 Linux 包管理器安装。Python 前置条件缺失时给出修复说明。安装完成后可启动 Pi 并执行 `/pbot init`；项目信任、登录和模型选择按 Pi 提示操作。
 
-需要长期使用短命令时，可另行安装：
+需要固定短命令时，可全局安装 CLI：
 
 ```bash
 npm install -g personal-bot@latest
 pbot setup
 ```
 
-这里的全局 npm 安装只提供 `pbot` 命令，不向 Pi 注册全局扩展。`pbot setup` 使用全局安装的安装器版本；用 npm 更新它，或继续使用 `npx personal-bot@latest setup` 获取最新安装器。安装器不自动全局安装自己。
-
-核心步骤失败时停止启动。已配置的 Git 或本地目录来源缺失、或无法识别包名时，setup 保留声明并停止，须先通过 Pi 修复来源；已有独立单文件扩展仍可使用。可选插件失败时继续处理其他项并汇总。成功步骤保留，修复后重跑同一命令；不自动整体回滚。工作区作用域、版本选择和边界见[安装与升级](docs/installation-design.md)。
+此命令副本通过 npm 更新，工作区扩展由 Pi 管理。安装失败后修复原因并重跑，已完成步骤与现有资料保留；可选插件失败时仍可选择进入 Pi。
 
-### 直接使用 Pi 安装
+### 已有 Pi
 
-已有 Pi 时，也可从目标工作区根目录安装并启动：
+从工作区根目录执行：
 
 ```bash
 pi install --local npm:personal-bot
 pi
 ```
 
-`--local` 将包声明保存在项目 `.pi/settings.json`。按 Pi 提示确认项目信任，每次从工作区根目录启动。Pi 加载 Personal Bot 就会启用角色、技能、工具及共享 Python 环境准备；没有第二个启用开关。除非希望所有 Pi 会话都启用 Personal Bot，否则不要用省略 `--local` 的 `pi install` 注册全局扩展。已有全局安装请用 Pi 原生包管理或 `pi config` 调整加载范围。开发与测试基线为 Pi 1.5.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
-```
-
-将示例路径换成实际路径。本地安装直接加载来源目录，请保留源码和依赖。不要同时加载源码与 npm 两个来源。
+`--local` 将安装声明保存在项目 `.pi/settings.json`。启动后在聊天框执行 `/pbot init`。全局安装可让同一份扩展服务多个显式启用的工作区。已有来源通过 `pi list` 或 `pi config` 管理，同一包保留一个有效来源。
 
-### 使用 dsh
+### dsh
 
-使用最新版 dsh，需要 Node.js 24.9+（若新版声明更高要求，以新版为准）、npm、pnpm 和 Python 3.11+。`pbot setup` 面向 Pi，dsh 使用原生 profile 和插件管理。在终端执行：
+需要 Node.js 24.9+、npm、pnpm 和 Python 3.11+；新版本的要求以 dsh `engines` 为准。使用原生 profile 和插件管理器安装：
 
 ```bash
 npm install -g @deepseek-ai/dsh@latest pnpm@latest
-dsh --version
-pnpm --version
-# 仅首次创建：此命令会覆盖已有同名 profile。
+# 仅首次创建；该参数会覆盖已有同名 profile
 dsh --profile pbot --from-default-profile web --dump-config
 dsh plugin --profile pbot add personal-bot@latest
 dsh --profile pbot
 ```
 
-最后一条命令启动 Web 服务，通常会自动打开浏览器。在页面中选择工作区和主会话，通过 dsh 原生设置配置模型与认证。在聊天输入框执行 `/pbot` 打开工作区、专家、团队和历史四页；`/pbot status` 检查工作区与 Python 环境；`/pbot init` 可选地补建缺失资料目录。加载插件和这些检查不调用模型。
+在浏览器中选择工作区和主会话，配置模型与认证，执行 `/pbot init` 初始化并启用。聊天输入框的 `/pbot` 打开管理界面，`/pbot status` 查看状态。
 
-以后启动只需 `dsh --profile pbot`。停止活动专家和服务后，分别更新宿主与插件：
+以后直接运行 `dsh --profile pbot`。停止活动专家和服务后更新插件：
 
 ```bash
-npm install -g @deepseek-ai/dsh@latest
 dsh plugin --profile pbot update personal-bot --latest
-dsh plugin --profile pbot list personal-bot --depth 0
-dsh --profile pbot
 ```
 
-更新时不要重复 `--from-default-profile`。使用桌面应用时，在原生“插件”页面安装和管理 `personal-bot@latest`；npm CLI 的 `pbot` profile 与应用的 `desktop` profile 分开。
-
-[完整中文指南](docs/dsh.md)（[English](docs/dsh.en.md)）包含启动参数、插件查询与移除、源码打包、全部 `/pbot` 子命令、JSON 参数及示例。专家使用同进程的原生 Agent/Session，页面刷新不停止已接纳工作。Pi 和 dsh 共同查询历史归档，各自管理会话、模型、认证与 MCP。已验证的 dsh 基线为 `0.2.2-rc.1`；`latest` 会变化，不代表未来版本已经通过验收，详见[验证记录](docs/validation.md)。
-
-### 可选安装 Task Conductor
-
-需要周期任务、重复流程或 DAG 时，使用可选接入包 `task-conductor-plugin` 及其共享的 `using-task-conductor` 技能。插件与 `task-conductor` 服务分别安装；服务初始化、连接设置和更新按[上游接入说明](https://github.com/realqiyan/task-conductor/blob/master/docs/host-integrations.md)操作。
+桌面应用通过原生“插件”页面安装 `personal-bot@latest`，使用独立的 desktop profile。完整终端参数、更新步骤与聊天命令见 [dsh 指南](docs/dsh.md)。
 
-**Pi：** 先用 `pi list` 检查已有安装及资源设置。使用已发布的 Pi 接入时，从工作区根目录执行：
+### 从源码使用
 
 ```bash
-pi install --local npm:task-conductor-plugin
-```
-
-使用未发布插件改动时，改为 `pi install --local /absolute/path/to/task-conductor/plugin`，只启用一个来源。在 Pi 内执行 `/reload`，再调用 `/skill:using-task-conductor`。技能提供服务安装、`task-conductor setup` 和 Pi 原生 MCP 注册方法。`--local` 限定插件加载范围；MCP 作用域另行选择，复用已有连接。
-
-**dsh：** 原生 Host 接入包含于尚未发布的 Task Conductor `0.1.6` 候选版本。发布前从该源码构建插件和配套服务，再将插件 tarball 安装到已有 Web profile：
-
-```bash
-cd /absolute/path/to/task-conductor
-npm run pack:plugin
-dsh plugin --profile pbot add /absolute/path/to/task-conductor/task-conductor-plugin-<version>.tgz
-dsh plugin --profile pbot list task-conductor-plugin --depth 0
+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
 ```
 
-使用打包命令输出的实际 tarball 路径。重启 `dsh --profile pbot`，打开主会话并调用 `/using-task-conductor`。插件通过原生文件系统技能发现提供共享技能，为每个根主会话创建使用该会话工作目录的原生 MCP 连接。工具保留 `mcp__task-conductor__executor_list` 等名称，避免另加重复的手工连接。桌面应用在原生“插件”页安装同一 tarball，profile 与 CLI 分开。配套本地服务的构建和设置见 [dsh Task Conductor 指南](docs/dsh.md#task-conductor)。
-
-服务仍使用独立的协调模型配置及 `pi-durable` 运行时，以 dsh 为宿主不需要安装 Pi 交互 CLI。需要同时用 dsh 执行任务节点时，通过 Task Conductor 管理员 CLI 或 Web，将 dsh 的规范绝对可执行路径注册为自定义执行端 `dsh-acp`，参数为 `["--profile", "acp"]`。具体操作见上游技能的[自定义 ACP 说明](https://github.com/realqiyan/task-conductor/blob/master/plugin/skills/using-task-conductor/references/custom-acp.md)；`dsh` 不是内置执行端 ID。节点使用自己的 dsh profile、认证、工具和环境。
+只加载 Pi 源码扩展时，在工作区执行 `pi install --local /absolute/path/to/personal-bot`，并保留该目录和依赖。dsh 的源码打包安装见[专门说明](docs/dsh.md#从源码安装)。
 
-通知回到提交任务的持久宿主会话；恢复原会话可接收待处理事件。关闭 Pi 或 dsh 不停止服务任务。插件与服务分别更新，按上游说明检查活动工作、停服并备份数据。凭据留在终端或私有文件中。连接检查沿用技能的原生工具发现与只读调用；它们不证明模型执行或任务交付已经成功。
+### 可选安装 Task Conductor
 
-## 可选资料准备
+周期任务、重复流程、DAG 和宿主退出后继续执行的任务使用 `task-conductor-plugin`。插件与配套服务分别安装，服务准备和配置遵循[上游接入指南](https://github.com/realqiyan/task-conductor/blob/master/docs/host-integrations.md)。
 
-加载 Personal Bot 后可直接使用，无需初始化。需要标准资料布局时执行 `/pbot init`：只创建缺失的资料目录和根 `AGENTS.md`，不覆盖已有文件，不触发模型任务。在 Pi 中，新建的 `AGENTS.md` 经 `/reload` 或下次启动后进入原生上下文；包内目录用途说明在首次任务即可使用。
+Pi 用户从工作区运行 `pi install --local npm:task-conductor-plugin`，重载后读取 `/skill:using-task-conductor`。dsh 用户按 [Task Conductor 接入说明](docs/dsh.md#task-conductor)安装，在主会话读取 `/using-task-conductor`。
 
-目标、市场、偏好和工作约定保存在普通资料中，可直接请助手整理。需要接入外部工具时提供 CLI/MCP 名称、用途、官方文档或配置位置，不提供凭据值。
+任务通知回到提交任务的原会话。关闭 Pi 或 dsh 后，服务任务继续运行；当前执行和未来周期分别查询、停止。
 
 ## 日常使用
 
-直接向助手说明任务，例如整理项目资料、比较研究结论、委派独立复核或运行计算。无需手动编排固定流程。以下命令表与进程说明面向 Pi；dsh 的命令和 Web 操作见[专门说明](docs/dsh.md)。
+直接说明任务，例如整理资料、比较研究结论、委派复核或运行计算。以下命令面向 Pi，dsh 命令见其指南。
 
 | 命令 | 用途 |
 | --- | --- |
 | `/pbot` | 打开工作区菜单 |
-| `/pbot init` | 可选地补建资料目录和缺失的根 `AGENTS.md` |
-| `/pbot status` | 查看工作区路径、Personal Bot 版本和 Python 环境状态 |
-| `/pbot history [关键词]` | 搜索历史问答与分层摘要，查看原文和上下层节点 |
-| `/pbot agents` | 查看专家状态；进入会话、补充要求、重命名或停止任务 |
-| `/pbot teams` | 查看团队与公共消息，开展轮次、暂停、关闭或进入成员 |
-| `/pbot python setup` | 手工重试共享 venv 的准备并激活，无需指定路径 |
-| `/reload` | Pi 原生命令，重载插件与资源 |
-
-- **原生工具**：CLI 通过 Bash 使用原生命令与当前 help，手册只保留当前使用所需的信息和证据引用；MCP 默认只接入当前项目，从工作区根目录执行 `pi mcp add --local <server> ...`，保存到 `.pi/mcp.json`，通过 `/mcp` 核对配置来源。只有明确要求跨项目使用时才修改用户级配置。不需要 Personal Bot 注册、参数绑定或权限表。方法见[接入技能](resources/skills/provider-connections/SKILL.md)。
-- **历史回溯**：无需命名会话。用 `/pbot history` 浏览，或直接请助手查找；`pbot_history` 搜索原文和各层摘要，沿父子节点展开。连续问答每四个节点逐层汇总，原文先可查询，摘要在主交互结束后使用当前 Pi 模型串行补齐，有额外模型调用。新输入会取消整理，后续继续。加载与查询不调用模型。问答与摘要保存在工作区 `.pi/pbot/history/`，随工作区复制后仍能查询；旧用户级索引会复制过来并保留旧副本。详见[历史对话](docs/history.md)。
-- **研究与分析**：可要求“综合这些资料并说明证据冲突”“核验这份分析的口径与计算”或“找出先要验证的关键假设”。
-- **独立子会话**：包内提供 tmux 与独立 Pi 会话，需系统安装 tmux。`pbot_agent start` 立即返回；省略 message/prompts/files 时只创建待命进程，不调用模型。工作完成后自动通知。支持模型/目录/文件/工具与资源选项、send、follow-up、rename、status、read、stop 和显式 resume，没有前后台参数或 wait。`/pbot agents` 展示正在工作的 agent，可进入子 TUI。主 reload 保持运行，退出或切换会话停止并保留历史。子会话也使用原生 CLI/MCP，按委派范围工作。详见[专家协作](docs/agent-collaboration.md)。
-- **团队协作**：`pbot_team` 将已有 agent 组成固定团队，支持 roundRobin 轮流讨论和 parallel 并行轮次。成员通过 `pbot_team_message` 直接交换原文，普通 post 不唤醒模型。运行中的团队占用成员；先暂停并收尾，再切换私人工作。reload 暂停团队，不重放旧请求。首版不包含动态 ask/返回唤醒，详见[专家协作](docs/agent-collaboration.md)。
-- **周期与持久任务**：主会话通过原生 MCP 直接使用可选的 Task Conductor，处理周期、重复流程和 DAG；使用其 `using-task-conductor` 技能与实际工具契约。安装与接入见[可选安装引导](#可选安装-task-conductor)。缺失不影响普通 pbot 功能，但不能执行调度。pbot 不另建持久任务调度器或转发层。外部任务与子会话分别查询和停止，取消本轮不等于停止未来周期，关闭 Pi 或 dsh 也不代表外部任务已停止。
-- **Python 环境**：所有工作区共用当前用户的独立 venv。Personal Bot 加载后自动创建环境或安装锁定依赖，成功后在当前 Pi 进程激活；主会话与专家通过 Bash 使用 `python` 或 `python3`。环境异常时提醒，修复后用 `/pbot python setup` 重试。系统 Python、外部终端、已有脚本和历史结果不变。共享依赖更新会影响其他工作区；更换插件版本或手工重试前应停止相关脚本。详见 [Python 说明](python/README.md)与[计算参考](resources/references/compute.md)。
-- **资料维护**：可要求“整理当前项目资料”“按上次口径重做报告”或“检查交付并结项”。助手按[项目整理与维护技能](resources/skills/project-maintenance/SKILL.md)更新当前任务及实际受影响的资料；整体整理按用户指定范围进行。当前说明按主题合并更新，从项目结论中提炼可复用的方法与口径；来源与重要决策保持可追溯。整理或结项时归集成果并清理范围内无用的临时产物，保留正式资料、历史记录与备份。
-
-主会话和子会话对话都使用 Pi 原生存储。聊天恢复可用 `pi --resume` 明确选择；`pi --continue` 可能选中最近活跃的子会话。受管子会话可从 `/pbot agents` 进入，已停止时加载原会话并待命，不调用模型；`pbot_agent resume` 用于携新要求继续工作。运行中不要另开进程写同一会话文件；不要因恢复而重发可能已产生副作用的操作。
-
-不维护独立 provider 调用账本或结果包装。工具结果及大结果处理由原生工具负责，项目结论引用相关来源与结果。结果不明时先查询原生状态；进程崩溃后不保证保存完整结果。
+| `/pbot init` | 启用工作区，补建资料目录与缺失的根 `AGENTS.md` |
+| `/pbot status` | 查看启用状态、工作区、版本和 Python 状态 |
+| `/pbot history [关键词]` | 搜索历史问答与摘要，展开原文 |
+| `/pbot agents` | 查看、进入、重命名、停止专家，或补充要求 |
+| `/pbot teams` | 查看团队与公共消息，开始轮次、暂停或关闭 |
+| `/pbot python setup` | 重试共享 Python 环境准备 |
+| `/reload` | Pi 原生命令，重载扩展与资源 |
+
+- **初始化与资料准备**：`/pbot init` 补建资料并启用工作区，保留已有资料与其他配置字段。Pi 首次启用时自动重载；已启动时补建的根 AGENTS 经 `/reload` 加载。
+- **原生工具**：CLI 通过 Bash 使用，MCP 使用宿主配置。Pi 新增项目连接时执行 `pi mcp add --local <server> ...`，通过 `/mcp` 查看来源。接入方法见[技能](resources/skills/provider-connections/SKILL.md)。
+- **历史回溯**：Pi 与 dsh 共同查询工作区归档。原文先可查询，主交互结束后用当前模型补齐摘要，会产生额外模型调用；新输入优先取消整理。详见[历史对话](docs/history.md)。
+- **专家与团队**：可独立委派、持续对话，或组织轮流讨论和并行轮次。Pi 专家需要 tmux；dsh 使用原生会话。团队运行时占用成员，切换私人工作前先暂停并等待在途工作结束。详见[专家协作](docs/agent-collaboration.md)。
+- **Python**：所有已启用工作区共用当前用户的一份 venv，启用后自动准备并在宿主进程激活，通过 Bash 使用 `python` 或 `python3`。更新依赖前停止使用该环境的脚本。路径、排障与许可见 [Python 说明](python/README.md)。
+- **资料维护**：可请助手整理项目、按既有口径重做分析或检查交付。按[维护技能](resources/skills/project-maintenance/SKILL.md)更新当前说明、提炼方法，保留正式资料、历史与备份。
+
+Pi 主会话恢复用 `pi --resume` 明确选择；`pi --continue` 可能选中最近活跃的子会话。受管专家从 `/pbot agents` 进入，停止后打开原会话会保持待命，携新要求继续时使用 resume。运行中的会话只保留一个写入进程。
 
 ## 工作区资料
 
 | 位置 | 用途 |
 | --- | --- |
+| `.pbot/config.json` | Pi/dsh 共用的工作区启用与配置 |
 | `AGENTS.md` | 资料导航与工作约定 |
-| `areas/`、`projects/` | 长期目标、任务定义、结论与交付物 |
+| `areas/`、`projects/` | 长期目标、任务、结论与交付物 |
 | `knowledge/` | 可复用的概念、方法与口径 |
-| `.pi/pbot/history/`、`.dsh/pbot/history/` | 按来源保存、可共同查询的问答原文、摘要与节点关系 |
-| `providers/` | 提供方手册、覆盖缺口与验证依据 |
-| `scratch/` | 临时脚本、查询与计算数据、下载及运行环境 |
-| `agents/`、`.agents/skills/` | coordinator/general-purpose 职责补充与工作区技能 |
-
-可再次查询的数据在使用时按保存的口径获取。
-
-Personal Bot 不在工作区内保存私有启用状态。Pi 配置仍由 Pi 管理，配置变更后按原生要求执行 `/reload`。复制工作区前停止旧实例；不支持多机同时写入同步目录。存储布局与复制边界见[文件存储](docs/file-storage.md)。
+| `.pbot/history/` | Pi/dsh 问答原文、摘要与节点关系 |
+| `providers/` | 外部工具的使用说明、数据口径与来源 |
+| `scratch/` | 临时脚本、计算数据、下载与运行环境 |
+| `agents/`、`.agents/skills/` | 职责补充与工作区技能 |
 
-## 更新与历史数据
+已有布局与工作约定优先。可再次查询的数据在需要时按记录的口径获取。复制工作区前停止旧实例的写入，不支持多机同时写同步目录。详细位置与保留规则见[文件存储](docs/file-storage.md)。
 
-当前版本为 **0.2.8**。不维护工作区格式、初始化状态或升级机制。插件更新使用对应宿主的原生包管理；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 环境按原生方式显式配置；用户资料、历史证据和备份原样保留。
+当前版本为 **0.2.10**。通过宿主原生包管理更新；本地 Pi 来源更新源码，依赖变化后运行 `npm ci --ignore-scripts`，再重载或重启。更换版本前停止活动专家；不同兼容线的专家需重新创建，旧资料、历史和备份保留。
 
-## 信任与风险
+操作按用户请求、已有约定和必要确认执行。Bash、Python、MCP 和扩展使用实际账户与凭据权限；硬限制应由只读凭据、服务端控制或受限环境提供。交易、转账和账本修改需要相应授权。取消、超时或断连后，先查原生状态再决定是否重试，避免重复执行。
 
-- Personal Bot 不提供逐工具权限或统一审批。CLI、MCP、Bash、Python 和扩展拥有其实际账户与凭据权限，不是沙箱。需要硬限制时使用只读凭据、服务端控制或受限环境。
-- 工具可用不等于用户授权。研究、接入与验证不授权交易、转账或账本修改。
-- 协议成功不证明业务完成。取消、超时和会话恢复不撤销外部副作用；可能已发送的操作先核对原生状态，不自动重发。
-- Task Conductor 节点不自动继承主会话的工具、环境和技能。用户未授权或原生服务要求人工确认的业务，不安排无人值守执行。
-
-完整边界见[原生工具与执行边界](docs/capability-design.md)。真实模型、外部服务和完整 TUI/RPC 交互仍需获准环境验收，本地测试不证明实盘可用。
+Task Conductor 节点单独配置工具、环境、技能与认证；需要人工确认的业务保留人工交互。具体规则见[工具与执行](docs/capability-design.md)。
 
 ## 开发与文档
 
+双宿主开发使用 Linux、Node.js 24.9+。安装锁定依赖后运行：
+
 ```bash
 npm run check
 npm test
 git diff --check
+npm pack --dry-run
 ```
 
-双宿主完整开发与验收使用 Linux、Node.js 24.9+。`npm test` 包含冒烟和 E2E 测试，并生成测试用 `dist/` 及 CLI、dsh Host/Web 的 `lib/`；Pi 扩展运行时仍直接加载源码。包内容可用 `npm pack --dry-run` 检查。测试分组与限制见[验证](docs/validation.md)。
+`npm test` 包含冒烟与 E2E 测试，并生成测试用 `dist/` 和发布用 `lib/`。Pi 运行时加载源码。
 
-- [开发文档索引](docs/README.md)：架构、工具、专家协作、存储与验证。
-- [npm 发布](docs/release.md)：配置、授权、发布与安装验收。
-- [领域术语](CONTEXT.md) · [Python 环境、原生库与许可](python/README.md)。
+- [文档索引](docs/README.md)：当前架构、使用与开发说明。
+- [npm 发布](docs/release.md)：候选检查、发布配置与操作。
+- [领域术语](CONTEXT.md)。

package/docs/README.md

@@ -1,25 +1,28 @@
-# 开发文档
+# 文档索引
 
-使用与安装见[项目 README](../README.md)。
+## 使用
+
+- [项目介绍与安装](../README.zh-CN.md) / [English](../README.md)
+- [dsh 使用](dsh.md)：profile、插件、Web 管理与聊天命令
+- [工作区配置](workspace-configuration.md)：Pi/dsh 共用配置、启用范围与重载
+- [专家协作](agent-collaboration.md)：独立委派、团队、通知与恢复
+- [历史对话](history.md)：查询、摘要与归档
+- [Python 环境](../python/README.md)：准备、排障、计算库与许可
+- [领域术语](../CONTEXT.md)
+
+## 开发
 
 | 文档 | 内容 |
 | --- | --- |
-| [架构原则](architecture-guidelines.md) | 模块划分、依赖和开发方法 |
-| [技术设计](technical-design.md) | 系统组成、生命周期与资源加载 |
-| [模型指令编写原则](model-instruction-guidelines.md) | 提示、角色、技能与工具说明的取舍、表达、加载和验证要求 |
-| [模型上下文](model-context.md) | 主会话、专家与摘要入口的内容、加载时机和验证边界 |
+| [架构原则](architecture-guidelines.md) | 模块划分、依赖与开发方法 |
+| [技术设计](technical-design.md) | 系统组成、生命周期与分发 |
+| [模型指令编写原则](model-instruction-guidelines.md) | 提示、角色、技能与工具说明的取舍 |
+| [模型上下文](model-context.md) | 内容来源、加载时机与更新 |
 | [界面设计](interaction-design.md) | Pi TUI 与 dsh GUI |
-| [dsh 使用（中文）](dsh.md) / [English](dsh.en.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、工作区选择、插件安装、初始化与失败恢复 |
-
-双宿主范围见[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。
+| [工具与执行](capability-design.md) | CLI/MCP、操作范围与外部任务 |
+| [文件存储](file-storage.md) | 数据位置、写入规则与历史保留 |
+| [安装器设计](installation-design.md) | setup 的计划、来源、作用域与失败恢复 |
+| [npm 发布](release.md) | 候选检查、发布配置与操作 |
+| [维护脚本](../scripts/README.md) | 构建与安装包检查 |
 
-每个主题维护当前说明，总览通过链接引用；提供中英文版本时同步维护命令、参数和限制。版本以 package.json 为准；历史设计查 Git 记录，临时排查过程不进入设计文档。
+根目录 README 保留中英文版本，其他主题各维护一份当前说明。测试结果放在任务、PR 或 CI 输出中，历史方案与变更过程通过 Git 查询。

package/docs/agent-collaboration.md

@@ -28,7 +28,7 @@ dsh 使用原生 provider/model/reasoning effort，拒绝 Pi 专属扩展、提
 
 服务器文件由原生附件存储保留内容，图片使用原生准入；Web 人工对话还接受本机文件与图片。人工对话先成功暂停所属团队，再进入原生 inbox；队列接纳、实际进入、模型消费和完成分别记录，未来排队输入不提前改变此前回答的归因。
 
-每个专家绑定父身份与 generation。启动、校验与释放在短控制锁外等待，预约期间的停止会取消启动；旧代次不能释放新实例。原生 registry 中由其他实例持有的 Agent 不能被替换或假称释放。正常完成要求请求实际消费、持久的正常 stop 和非空最终答复；空闲、工具文本、截断或缺失结束标记都不代表成功。
+每个专家绑定父身份与 generation。启动、校验与释放在短控制锁外等待，预约期间的停止会取消启动；旧代次不能释放新实例。原生 registry 中由其他实例持有的 Agent 不能被替换或假称释放。正常完成要求请求实际消费、持久的正常 stop 和非空最终答复。
 
 `/pbot` Web 管理页提供人工对话、完整原生记录、停止和携新要求恢复。离页不停止已接纳工作；父 Agent 或组件关闭会暂停安排并释放其拥有的专家。重新打开页面不会恢复或重放旧工作。详情见[dsh 使用](dsh.md)。
 
@@ -51,7 +51,7 @@ dsh 使用原生 provider/model/reasoning effort，拒绝 Pi 专属扩展、提
 
 默认 2 轮、15 分钟。轮数为 1–10；parallel 默认并发为成员数与 2 的较小值，可调到 1–成员数。期限可设 1–86400 秒。总发言请求数不超过成员数乘轮数，普通 post 不增加请求。
 
-这是有界并行轮次，不是任意点名唤醒的自由 swarm。首版不提供 ask、自动返回处理、热增减成员、跨团队私信或任务 DAG。轮内研究、实现、计算与审查方法由角色和技能决定。
+团队采用固定成员与有限轮次；轮内研究、实现、计算与审查方法由角色和技能决定。
 
 ### 工具
 
@@ -64,7 +64,7 @@ dsh 使用原生 provider/model/reasoning effort，拒绝 Pi 专属扩展、提
 | pause | 停止新增安排和领取，已领取请求继续收尾 |
 | close | 已暂停或结束且没有在途工作时关闭，保留历史；不阻塞等待 |
 
-run 要求全部成员空闲、无未消费的私人输入，并已加载可用的团队入口与通信工具。条件不满足时返回原因，不在后台等待成员就绪。team-ready 标记仅表示接入能力，不证明模型认证或业务能力可用。
+run 要求全部成员空闲、无未消费的私人输入，并已加载可用的团队入口与通信工具。条件不满足时返回原因，不在后台等待成员就绪。
 
 主会话与成员通过 pbot_team_message read/post 通信。post 参数为 teamId、text、可选 replyTo，正文最多 24000 字符；不允许指定 sender。成员 post 必须属于其当前团队工作，主会话可在暂停时补充信息。所有发言公开，没有私密 to 信箱。
 
@@ -85,7 +85,7 @@ run 要求全部成员空闲、无未消费的私人输入，并已加载可用
 
 成员任务、团队背景、自动注入的公共消息和批次通知使用 Markdown 文档。普通专家只加载公共约定与专家职责；处理团队任务时才补充共同目标、成员职责、身份、轮次及团队操作说明。本批次要求仅在成员任务输入中给出，避免重复。公共消息按 seq 分节，列出作者、回复关系与来源，正文放入保留原文的代码区块，包含代码围栏的正文也不会破坏区块边界。成员原文中的 JSON 保留原样。
 
-read 的文本结果也使用 Markdown，同时保留工具的结构化结果。nextOffset 非空表示该条正文未读完，用同一 teamId、seq 和 offset 续读；nextAfterSeq 用于后续消息。自动注入按实际 Markdown 长度限制上下文，并用 remainingFromSeq 标明未包含的消息，从 afterSeq: remainingFromSeq - 1 继续读取。不能将展示片段当作完整记录。Pi 压缩不删除公共记录。
+read 的文本结果也使用 Markdown，同时保留工具的结构化结果。nextOffset 非空表示该条正文未读完，用同一 teamId、seq 和 offset 续读；nextAfterSeq 用于后续消息。自动注入按实际 Markdown 长度限制上下文，并用 remainingFromSeq 标明未包含的消息，从 afterSeq: remainingFromSeq - 1 继续读取。Pi 压缩不删除公共记录。
 
 只自动公开本次团队请求正常结束后的最终答复，不广播完整历史、推理或原始工具输出。人工输入混入周期时标记 mixed 并暂停团队，不自动公开混合答复；此前显式 post 的内容保留。成员信息与人工子会话输入都不扩大原用户授权。
 
@@ -101,7 +101,7 @@ read 的文本结果也使用 Markdown，同时保留工具的结构化结果。
 | teamId / runId | 团队 / 一批有限轮次，不与 Task Conductor 的标识混用 |
 | seq | 团队内公共消息顺序 |
 
-接收、执行完成、公开答复和业务验收是不同事实。函数返回、accepted、custom entry 或 UI 查看都不证明模型已理解。idle 不表示上轮成功，finished 不表示任务通过验收或达成共识。
+请求按接纳、消费和完成记录状态。工作结果通过对应 cycle 的报告读取；团队批次状态用于控制轮次安排。
 
 历史报告使用固定叶节点；后续工作不覆盖旧报告。团队先保存 requestId 关联，再写原 inbox；同 ID 不重复增加序号。普通锁竞争仅重试当前进程中已知尚未发布的输入，reload 丢弃这份临时等待，不自动补发。I/O 错误使当前文件实例停止后续写入与投递。
 
@@ -118,7 +118,7 @@ Pi 独立周期的 read 结果进入当前分支后领取该周期通知，包
 | 事件 | 行为 |
 | --- | --- |
 | 独立周期完成 | 保持 idle，可继续对话 |
-| Pi 主 reload | 保留子进程，但暂停团队；可补交付已完成结果，不续排旧批次 |
+| Pi 主 reload | 工作区仍启用时保留子进程并暂停团队；配置关闭或无效时停止所属专家；不续排旧批次 |
 | dsh 页面关闭、刷新、重连 | 已接纳工作继续归服务端，查看不恢复旧任务 |
 | dsh 父 Agent 释放、组件停用或卸载 | 暂停安排，取消预约并等待自己的专家资源释放；后续须显式恢复 |
 | 主中断 | 暂停团队新增安排，已领取工作默认收尾 |
@@ -128,18 +128,16 @@ Pi 独立周期的 read 结果进入当前分支后领取该周期通知，包
 | 到达期限 | 停止新安排和领取；子入口尽力中断自身未被人工接管的团队工作 |
 | 恢复主 session | 恢复记录与通知，不自动启动旧工作 |
 
-pause 返回时可能仍有在途请求。unresolved 区分排队、已接收、未公开、未知结果与中断等状态；只有进程确已停止或请求已经结束，才能解除在途占用。结果未知时查原生报告和外部状态，不能将新批次视为重试许可。中断不保证撤销已发生的外部副作用。
+pause 返回时可能仍有在途请求。unresolved 区分排队、已接收、未公开、未知结果与中断等状态；只有进程确已停止或请求已经结束，才能解除在途占用。结果未知时先查原生报告和外部状态，避免重复执行。
 
-## UI 与验证边界
+## 界面与故障恢复
 
-dsh 的 Web、原生 Remote、附件、长记录、冷读与恢复，以及真实模型验收缺口见[实施记录](dsh-implementation-plan.md)。下面保留 Pi 的 TUI 使用规则。
+dsh 的管理界面与命令见[dsh 使用说明](dsh.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 核对团队。完整扫描成功且待暂停、待入队操作不再受阻后清除故障状态。当前实例中已恢复的故障若曾在当前分支通知，会补发一次关联的恢复消息；中断期间延后投递，成员结果优先交付。未投递的故障不补发恢复消息，重载不追认旧实例的恢复。恢复只确认自动跟进扫描可用，不代表任务完成。通知不重发任务、不删除锁，命令和工具的错误仍直接返回。
+通知按实际服务状态说明恢复方式：锁释放后自动恢复扫描；可恢复的读取错误先排障，修复后由后台重试；团队服务或协作存储已停用时，修复文件仍不能恢复当前实例，须请用户在当前 Pi 会话执行 `/reload`。重载前不反复调用 pbot_team，可通过 pbot_agent list/status/read 核对仍可读取的成员状态与报告；重载后再用 pbot_team status/read 核对团队。完整扫描成功且待暂停、待入队操作不再受阻后清除故障状态。当前实例中已恢复的故障若曾在当前分支通知，会补发一次关联的恢复消息；中断期间延后投递，成员结果优先交付。未投递的故障不补发恢复消息，重载不追认旧实例的恢复。通知不重发任务、不删除锁，命令和工具的错误仍直接返回。
 
 进入成员前提示返回快捷键，团队成员使用相同入口。默认 tmux 绑定下，普通终端按 Ctrl+B 后按 d 脱离；主会话已在 tmux 中时，按 Ctrl+B 后按小写 l 切回。自定义绑定以自己的配置为准。返回不停止成员，不要用 /exit 代替。
-
-Pi 1.5.0 的本地 SDK、实际无认证 Pi/tmux 进程、文件并发与恢复测试已覆盖基础契约。未使用假模型或模拟 provider。2026-10-28 在 0.1.3 上的真实模型双成员冒烟已通过两种策略的单轮通信、原文引用与主通知；0.2.0 的原生存储调整及后续 Pi 升级未追加真实模型调用。Pi 1.4.0 已完成 `/pbot` 菜单、只读状态页、历史入口和窗口缩放的真实终端验收；Pi 1.5.0 的人工 TUI 回归、专家 attach 与运行中人工交互，以及异构模型、多轮讨论和长期使用仍待验收，详见[验证](validation.md)。单轮通过不证明一般协作质量或外部操作恰好一次。

package/docs/architecture-guidelines.md

@@ -28,10 +28,10 @@
 
 测试业务契约和具体失败风险，使用真实本地文件、进程、计算和各宿主 SDK。测试不依赖假模型、模拟 provider、个人凭据或真实交易，也不以文案和实现结构作为行为断言。
 
-本地测试与外部验收分别记录，范围见[验证](validation.md)。
+测试结果在本次任务、PR 或 CI 输出中说明，写清实际检查与影响判断的未决问题。
 
 ## 维护文档
 
-文档组织见[索引](README.md)。使用方法、行为或接口变化时更新所属主题；内部重构只更新受影响的设计说明。
+文档组织见[索引](README.md)。按读者需要维护当前说明，变更时直接修订所属主题。用户指南保留操作所需内容，开发细节放在相应设计文档。删除重复解释、过时方案与排查流水，历史通过 Git 查询。
 
 描述当前规则及必要理由，使用短句和一致术语。运行时提示词与开发文档分开维护，避免把开发细节加入模型上下文。

package/docs/capability-design.md

@@ -34,18 +34,10 @@ Bash、Python、MCP 和扩展拥有其实际账户与凭据权限。dsh 的原
 
 ## 可选 Task Conductor
 
-Task Conductor 通过原生 MCP 提供周期任务、重复流程和 DAG，独立管理任务定义与运行状态。Pi 和 dsh 使用同一接入包及 `using-task-conductor` 技能，分别由自己的原生机制加载。安装入口见[项目 README](../README.zh-CN.md#可选安装-task-conductor)；dsh 接入包含于 Task Conductor `0.1.6` 候选版本，发布前使用源码与配套本地 tarball，具体步骤见 [dsh 指南](dsh.md#task-conductor)。
+Task Conductor 通过原生 MCP 提供周期任务、重复流程和 DAG，独立管理任务定义与运行状态。两种宿主使用 `task-conductor-plugin` 和 `using-task-conductor` 技能。安装见[项目 README](../README.zh-CN.md#可选安装-task-conductor)，服务配置见[上游接入指南](https://github.com/realqiyan/task-conductor/blob/master/docs/host-integrations.md)。
 
-dsh 接入由 Task Conductor 插件的原生 Host 入口、包导出和 bundle patch 装配，共享技能通过原生 SkillFilesystem 提供。插件为每个根 Agent 建立独立的原生 MCP 连接，stdio 使用该会话 cwd；工具保留 `mcp__task-conductor__<tool>` 命名。Personal Bot 只提供按需参考入口，不增加包装工具、私有 MCP 客户端或安装平台，`pbot setup` 仍面向 Pi。
+Personal Bot 提供按需参考入口，工具调用、连接和通知由 Task Conductor 插件与宿主管理。通知绑定提交任务的原生持久会话，恢复原会话后继续接收。
 
-通知 origin 绑定 dsh 原生持久 Session。插件轮询服务事件，将通知送入原会话，在确认原生接收并 flush 持久记录后才向服务 ack；恢复同一会话可继续领取。页面查询和另一主会话不代替原会话接收，宿主关闭不撤销服务中的任务。
+提交任务时明确输入、工作目录、工具与认证前提、输出；周期任务还需频率、时区、执行范围与每轮数据时点。项目资料保存任务定义、taskId、runId、节点 ID 和结果位置，实时状态向服务查询。
 
-服务内部协调者继续使用 `pi-durable`，独立配置模型与认证；dsh 宿主不要求 Pi 交互 CLI。dsh 节点通过已有自定义 ACP 注册机制接入，管理员 CLI/Web 注册规范绝对程序路径与 `["--profile", "acp"]`，ID 为 `dsh-acp`；不预留新的内置 `dsh`。该节点的 profile、工具与环境由执行端管理，不从主会话复制。
-
-提交任务时明确输入、cwd、工具与认证前提和输出；周期任务还需明确频率、时区、执行范围及每轮数据时点。项目资料保存任务定义、taskId、runId、节点 ID 和结果位置，实时状态向 Task Conductor 查询。
-
-pbot 子会话绑定父会话，Task Conductor 可在所属宿主会话关闭后继续。两者分别查询和停止；取消当前 run 与停止未来周期也是两个操作。
-
-外部节点需单独配置工具、技能、Python 环境和认证，不自动继承主会话能力。需要人工确认的业务不安排无人值守执行。提交结果不明时先按原标识查询，避免重复创建。
-
-外部工具与真实任务的验收范围见[验证](validation.md)。
+服务任务可在宿主关闭后继续。pbot 专家、外部任务、当前 run 和未来周期分别查询、停止。外部节点单独配置工具、技能、Python 与认证；需要人工确认的业务保留人工交互。提交结果不明时按原标识查询，避免重复创建。