personal-bot 0.2.6 → 0.2.9

package/README.zh-CN.md

@@ -2,15 +2,15 @@
 
 [English](README.md) | 简体中文
 
-**个人助手，连接知识、研究与行动。**
+**连接知识、研究与行动的个人助手。**
 
-提供 Pi 工作区扩展和固定版 dsh 原生 Web 接入，用于学习、项目推进、研究与决策支持，也支持投资分析与已授权业务。dsh 的使用和当前验收范围见[专门说明](docs/dsh.md)。
-
-定位为可信模型驱动的个人助手。模型负责分析、协调与原生工具使用；pbot 提供资料入口、专家协作和 Python 环境准备。不另建主 Agent，不自动开展任务或交易。
+Personal Bot 提供按工作区加载的 [Pi](https://pi.dev) 扩展和原生 dsh Web 接入，支持资料整理、项目推进、研究分析、专家协作和已授权的业务操作。模型负责分析与协调，插件提供资料目录、专家会话、历史查询和共享 Python 环境。
 
 ## 安装
 
-下面的安装器面向 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,151 +18,131 @@ 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` 获取最新安装器。安装器不自动全局安装自己。
+此命令副本通过 npm 更新，工作区扩展由 Pi 管理。安装失败后修复原因并重跑，已完成步骤与现有资料保留；可选插件失败时仍可选择进入 Pi。
 
-核心步骤失败时停止启动，可选插件失败时继续处理其他项并汇总。成功步骤保留，修复后重跑同一命令；不自动整体回滚。工作区作用域、版本选择和边界见[安装与升级](docs/installation-design.md)。
+### 已有 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)。
+`--local` 将声明保存在项目 `.pi/settings.json`。每次从工作区根目录启动；加载即启用角色、技能、工具与 Python 环境准备。需要所有 Pi 会话都启用时才使用全局扩展安装。已有来源通过 `pi list` 或 `pi config` 管理，同一包保留一个有效来源。
 
-### 从源码安装
+### dsh
 
-开发时可改用本地源码；试用源码中的安装器先构建 CLI：
+需要 Node.js 24.9+、npm、pnpm 和 Python 3.11+；新版本的要求以 dsh `engines` 为准。使用原生 profile 和插件管理器安装：
 
 ```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
+npm install -g @deepseek-ai/dsh@latest pnpm@latest
+# 仅首次创建；该参数会覆盖已有同名 profile
+dsh --profile pbot --from-default-profile web --dump-config
+dsh plugin --profile pbot add personal-bot@latest
+dsh --profile pbot
 ```
 
-若只需将源码作为 Pi 扩展加载：
+在浏览器中选择工作区和主会话，配置模型与认证。聊天输入框的 `/pbot` 打开管理界面，`/pbot status` 查看状态，`/pbot init` 补建资料。
+
+以后直接运行 `dsh --profile pbot`。停止活动专家和服务后更新插件：
 
 ```bash
-cd /path/to/workspace
-pi install --local /absolute/path/to/personal-bot
-pi
+dsh plugin --profile pbot update personal-bot --latest
 ```
 
-将示例路径换成实际路径。本地安装直接加载来源目录，请保留源码和依赖。不要同时加载源码与 npm 两个来源。
-
-### 使用 dsh
+桌面应用通过原生“插件”页面安装 `personal-bot@latest`，使用独立的 desktop profile。完整终端参数、更新步骤与聊天命令见 [dsh 指南](docs/dsh.md)（[English](docs/dsh.en.md)）。
 
-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.5.0 基线使用原生 MCP 和 npm 接入。
-
-先用 `pi list` 检查是否已经安装；已安装但技能不可见时，检查资源是否启用并重载，不要重复安装。新安装请审阅[官方接入说明](https://github.com/realqiyan/task-conductor/blob/master/docs/host-integrations.md)，从工作区根目录执行：
+### 从源码使用
 
 ```bash
-pi install --local npm:task-conductor-plugin
+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 中执行 `/reload`，再调用 `/skill:using-task-conductor`。插件自带技能会在你确认后引导服务安装、`task-conductor setup` 和原生 MCP 接入；插件安装本身不安装服务。凭据留在自己的终端或私有文件中，不发到聊天里。
+只加载 Pi 源码扩展时，在工作区执行 `pi install --local /absolute/path/to/personal-bot`，并保留该目录和依赖。dsh 的源码打包安装见[专门说明](docs/dsh.md#从源码安装)。
 
-已有旧版接入包时，先用 `pi list` 核对来源和作用域，审阅官方升级说明后显式移除旧包声明，再安装新包，不同时加载两份。接入包与服务分别更新；服务升级前核对活动任务、停服并备份，按上游说明处理原生 MCP 连接，不自动迁移配置或删除历史数据。
-
-`--local` 只限定插件的加载范围，不隔离服务数据；MCP 注册范围另行选择，保留已有连接，不重复注册。连接完成后用 `/mcp` 或 `pi mcp list` 检查实际工具，并按技能执行只读验证，不为安装验收创建模型任务。连接成功不证明模型认证或业务交付成功。
+### 可选安装 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 用户从工作区运行 `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 也不代表外部任务已停止。
-- **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。运行中的会话只保留一个写入进程。
 
 ## 工作区资料
 
 | 位置 | 用途 |
 | --- | --- |
 | `AGENTS.md` | 资料导航与工作约定 |
-| `areas/`、`projects/` | 长期目标、任务定义、结论与交付物 |
+| `areas/`、`projects/` | 长期目标、任务、结论与交付物 |
 | `knowledge/` | 可复用的概念、方法与口径 |
-| `.pi/pbot/history/`、`.dsh/pbot/history/` | 按来源保存、可共同查询的问答原文、摘要与节点关系 |
-| `providers/` | 提供方手册、覆盖缺口与验证依据 |
-| `scratch/` | 临时脚本、查询与计算数据、下载及运行环境 |
-| `agents/`、`.agents/skills/` | coordinator/general-purpose 职责补充与工作区技能 |
-
-可再次查询的数据在使用时按保存的口径获取。
+| `.pi/pbot/history/`、`.dsh/pbot/history/` | 问答原文、摘要与节点关系 |
+| `providers/` | 外部工具的使用说明、数据口径与来源 |
+| `scratch/` | 临时脚本、计算数据、下载与运行环境 |
+| `agents/`、`.agents/skills/` | 职责补充与工作区技能 |
 
-Personal Bot 不在工作区内保存私有启用状态。Pi 配置仍由 Pi 管理，配置变更后按原生要求执行 `/reload`。复制工作区前停止旧实例；不支持多机同时写入同步目录。存储布局与复制边界见[文件存储](docs/file-storage.md)。
+已有布局与工作约定优先。可再次查询的数据在需要时按记录的口径获取。复制工作区前停止旧实例的写入，不支持多机同时写同步目录。详细位置与保留规则见[文件存储](docs/file-storage.md)。
 
-## 更新与历史数据
+## 更新与操作范围
 
-当前版本为 **0.2.6**。不维护工作区格式、初始化状态或升级机制。插件更新使用对应宿主的原生包管理；Pi 本地安装则更新来源源码，依赖变化后执行 `npm ci --ignore-scripts`，再重载或重启 Pi。更换版本前先停止活动子会话；不同兼容线的子会话不能直接恢复。
+当前版本为 **0.2.9**。通过宿主原生包管理更新；本地 Pi 来源更新源码，依赖变化后运行 `npm ci --ignore-scripts`，再重载或重启。更换版本前停止活动专家；不同兼容线的专家需重新创建，旧资料、历史和备份保留。
 
-子会话 JSONL 由 Pi 保存在原生 sessions 目录或原生配置指定的位置；`pbot/subagents/` 只保存控制记录与会话引用，团队公共记录保存在 `pbot/teams/`。0.2.0 不兼容旧会话位置，不迁移或删除 0.1.x 历史；旧记录不进入当前列表或后台调度。先在旧版停止活动成员，更新后重新创建 agent。共享 Python 环境使用用户级 `pbot/python/.venv`，具体系统路径见 [Python 说明](python/README.md)。不自动导入其他应用的会话、配置或环境，也不修改其数据。MCP 连接与 CLI 环境按原生方式显式配置；用户资料、历史证据和备份原样保留。
+操作按用户请求、已有约定和必要确认执行。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,23 +1,27 @@
-# 开发文档
+# 文档索引
 
-使用与安装见[项目 README](../README.md)。
+## 使用
+
+- [项目介绍与安装](../README.zh-CN.md) / [English](../README.md)
+- [dsh 使用](dsh.md) / [English](dsh.en.md)：profile、插件、Web 管理与聊天命令
+- [专家协作](agent-collaboration.md)：独立委派、团队、通知与恢复
+- [历史对话](history.md)：查询、摘要与归档
+- [Python 环境](../python/README.md)：准备、排障、计算库与许可
+- [领域术语](../CONTEXT.md)
+
+## 开发
 
 | 文档 | 内容 |
 | --- | --- |
-| [架构原则](architecture-guidelines.md) | 模块划分、依赖和开发方法 |
-| [技术设计](technical-design.md) | 系统组成、生命周期与资源加载 |
+| [架构原则](architecture-guidelines.md) | 模块划分、依赖与开发方法 |
+| [技术设计](technical-design.md) | 系统组成、生命周期与分发 |
+| [模型指令编写原则](model-instruction-guidelines.md) | 提示、角色、技能与工具说明的取舍 |
+| [模型上下文](model-context.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、工作区选择、插件安装、初始化与失败恢复 |
-
-双宿主范围见[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 记录，临时排查过程不进入设计文档。
+每个主题维护一份当前说明，中英文指南同步维护。测试结果放在任务、PR 或 CI 输出中，历史方案与变更过程通过 Git 查询。

package/docs/agent-collaboration.md

@@ -24,11 +24,11 @@ Pi 的 start 支持 noExtensions、noSkills、noPromptTemplates 和 noContextFil
 
 ## dsh 专家
 
-dsh 使用原生 provider/model/reasoning effort，拒绝 Pi 专属扩展、提示模板和上下文文件开关。tools 使用原生能力名，noSkills 控制技能；专家不拥有协调者管理工具。只在模型选择仍与父一致时继承父 effort。恢复保留原生选择，不用新父默认值覆盖旧会话。
+dsh 使用原生 provider/model/reasoning effort，拒绝 Pi 专属扩展、提示模板和上下文文件开关。创建与恢复时通过原生 composeFrom 应用父 preset，保留其文件工具、AGENTS 和技能发现；tools 使用原生能力名，专家排除协调管理及递归委派工具。noSkills 关闭模型技能目录和 skill 工具，用户显式技能手势仍按宿主处理。只在模型选择仍与父一致时继承父 effort。恢复保留原生选择，不用新父默认值覆盖旧会话。
 
 服务器文件由原生附件存储保留内容，图片使用原生准入；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 信箱。
 
@@ -83,9 +83,9 @@ run 要求全部成员空闲、无未消费的私人输入，并已加载可用
 
 团队公共记录独立于各自私人会话。Pi 通过原 inbox 投递，在 before_agent_start 和 turn_end 的安全边界注入已署名的公共原文，不请求额外 continuation。dsh 使用原生 inbox 和 pre-step；团队领取先获得原生 maintenance 准入，人工输入待处理或当前步骤已有人工消息时不追加团队背景。空闲成员在下一次团队请求时取得信息，私人工作不自动注入新群消息。
 
-成员任务、团队背景、自动注入的公共消息和批次通知使用 Markdown 文档。团队背景按共同目标和成员职责分节，保留身份与轮次；本批次要求仅在成员任务输入中给出，避免在系统简报中重复。公共消息按 seq 分节，列出作者、回复关系与来源，正文放入保留原文的代码区块，包含代码围栏的正文也不会破坏区块边界。成员原文中的 JSON 保留原样。
+成员任务、团队背景、自动注入的公共消息和批次通知使用 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 错误使当前文件实例停止后续写入与投递。
 
@@ -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 1.4.0 升级仅做本地 SDK/无认证进程验证，未追加真实模型调用；异构模型、多轮讨论、长期使用与交互 TUI 尚未验收，详见[验证](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

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