personal-bot 0.2.3 → 0.2.4

package/CONTEXT.md

@@ -39,6 +39,10 @@ _避免_：用工作区表示单个会话或真实账户。
 
 **Personal Bot 启用**：Pi 按原生配置加载 Personal Bot 扩展。没有独立的工作区就绪状态；资料和外部服务是否准备好不影响加载，也不证明某项能力可用或已获执行许可。
 
+**配套插件**：与 Personal Bot 配合提供附加能力、可独立安装的组件。其依赖的外部服务不属于插件本体，安装插件不代表服务已准备好。
+
+**配套插件清单**：维护者为 Personal Bot 安装提供的候选插件集合，用户从中选择本次需要的插件。清单不等同于工作区实际安装内容；移出清单不表示卸载已有插件。
+
 ## 任务管理
 
 **Task Conductor**：主会话通过原生 MCP 使用的独立任务系统，拥有周期、重复流程、DAG 和持久执行状态，不经 pbot 专家转发。taskId 标识任务定义，runId 标识一次执行，节点 ID 标识 DAG 节点，三者不能互换，也不与 pbot 子会话的 agentId 或工作周期 cycleId 混用。

package/README.md

@@ -10,9 +10,32 @@ The model handles analysis, coordination, and native tools. Personal Bot adds wo
 
 ## 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 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
@@ -105,7 +135,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.4**. 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.
 
 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 +158,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.
+`npm test` includes smoke and E2E tests and generates `dist/` for test imports and `lib/` for the installation CLI. 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

@@ -10,25 +10,55 @@
 
 ## 安装
 
-需要 Linux、Node.js 22.19+，以及已配置模型和认证的 Pi。Python 计算需要 Python 3.11+。当前开发与测试使用 Pi 1.4.0，其他宿主版本需另行验证。
+安装器支持 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
@@ -103,7 +133,7 @@ Personal Bot 不在工作区内保存私有启用状态。Pi 配置仍由 Pi 管
 
 ## 更新与历史数据
 
-当前版本为 **0.2.3**。不维护工作区格式、初始化状态或升级机制。插件更新使用 Pi 原生包管理；本地安装则更新来源源码，依赖变化后执行 `npm ci --ignore-scripts`，再重载或重启 Pi。更换版本前先停止活动子会话；不同兼容线的子会话不能直接恢复。
+当前版本为 **0.2.4**。不维护工作区格式、初始化状态或升级机制。插件更新使用 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 +154,7 @@ npm test
 git diff --check
 ```
 
-`npm test` 包含冒烟和 E2E 测试，并生成测试用 `dist/`；运行时直接加载源码。包内容可用 `npm pack --dry-run` 检查。测试分组与限制见[验证](docs/validation.md)。
+`npm test` 包含冒烟和 E2E 测试，并生成测试用 `dist/` 与发布用 CLI `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

@@ -12,6 +12,7 @@
 | [文件存储](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 本地验证与剩余验收见验证。
 

package/docs/installation-design.md

@@ -0,0 +1,224 @@
+# npx 安装与升级设计
+
+状态：方案已确认并实现。命令需使用包含该实现的发布包；当前源码可先执行 `npm run build:cli`，再运行 `node bin/pbot.mjs setup`。验证结果与剩余验收见[验证](validation.md)。
+
+目标是在 Linux 和 macOS 上，通过一个交互式入口安装或升级 Pi、为一个工作区安装 Personal Bot 和选定的配套插件，再启动 Pi 执行 `/pbot init`。Personal Bot 的运行主体仍是 Pi 扩展；安装命令只负责环境准备和启动。
+
+## 命令与分发
+
+npm 包继续使用 `personal-bot`，增加名为 `pbot` 的可执行入口。npm 上的 `pbot` 已属于其他项目，包名与命令名无需一致。
+
+```bash
+npx personal-bot@latest setup
+npx personal-bot@latest setup --workspace ~/pbot-workspace
+```
+
+首次安装和后续升级使用同一个 `setup` 子命令。无子命令时显示帮助；`--workspace` 省略目录选择，但仍保留插件选择和安装计划确认。首版是终端交互流程，重定向输入时明确提示需要交互终端，不猜测选择或启动模型。
+
+需要长期使用短命令时，用户可另行安装：
+
+```bash
+npm install -g personal-bot@latest
+pbot setup
+```
+
+npx 不自动全局安装自身。全局安装只提供命令入口，不向 Pi 注册全局 pbot 扩展。`pbot setup` 使用全局安装的安装器版本；更新此入口使用 npm，或直接运行 `npx personal-bot@latest setup` 获取最新安装器。工作区中的 pbot 扩展与全局命令副本分别更新。
+
+首版只提供 `setup`、帮助和版本信息。以后按实际需求增加子命令。
+
+## 范围与所有者
+
+| 对象 | 范围与责任 |
+| --- | --- |
+| Node.js/npm | 运行 npx 的前提；最低 Node.js 22.19，目标软件有更高要求时提示先升级 |
+| Pi 主程序 | 当前用户共用一份；首次通过 npm 安装，已有安装沿用原生升级机制 |
+| pbot 扩展 | 所选工作区必装；已有自定义来源可选择保留 |
+| 配套插件 | 维护者提供候选清单，用户选择；安装到所选工作区 |
+| tmux | 独立专家与团队协作的强依赖；缺失时通过已有系统包管理器安装 |
+| 基础 Python | 检查 Python 3.11+、venv 和 ensurepip；缺失时提供指引 |
+| 共享 Python venv | pbot 加载时按现有逻辑准备，安装器不维护另一份环境 |
+| 工作区资料 | 启动 Pi 后交给 `/pbot init` 补建；已有内容按现有命令规则保留 |
+| 模型、认证、项目信任 | 使用 Pi 原生流程与已有配置 |
+| 插件依赖的外部服务 | 由插件自己的使用与配置流程处理 |
+
+安装器每次处理一个目录。目录选择支持当前目录、输入已有目录和创建新目录，不建立工作区列表、注册表、格式版本或启用标记。新目录可由安装器创建；其中的资料目录和资料文件由 pbot 创建。Pi 原生包管理仍可创建 `.pi/settings.json` 及其安装目录。
+
+升级共享 Pi 会影响其他工作区后续启动。更换 pbot 版本前遵循现有规则，停止活动子会话；安装器不代替用户强行终止任务。已有资料、历史记录、源码和备份保留。
+
+## 交互流程
+
+```mermaid
+flowchart TD
+    A[运行 setup] --> B[检查平台、Node/npm 和基础 Python]
+    B --> C[选择或创建工作区]
+    C --> D[读取原生安装状态与来源]
+    D --> E[选择插件与自定义来源的处理方式]
+    E --> F[展示安装计划并确认]
+    F --> G[补装 tmux，安装或升级 Pi]
+    G --> H[安装或升级工作区 pbot]
+    H --> I[逐项处理选中的配套插件]
+    I --> J[核对实际版本与安装结果]
+    J --> K[选择是否启动 Pi，默认启动]
+    K --> L[Pi 原生信任与扩展加载]
+    L --> M[执行 /pbot init，保留交互会话]
+```
+
+基础 Python 不满足要求时，在软件变更前说明缺项并结束本次 setup。tmux 安装、Pi 或 pbot 处理失败时，不继续启动 Pi。插件失败可继续处理其他插件，汇总后让用户选择是否先进入 Pi。
+
+安装计划展示工作区绝对路径、Pi 的真实路径和安装来源、当前版本、目标版本、选中的插件、保留的自定义来源，以及需要执行的系统软件安装。用户完成一次计划确认后执行所列操作；系统提权与 Pi 信任仍使用各自原生交互。若没有 Pi、但已有原生插件声明，安装器先展示 Pi 目标版本并确认安装 Pi，再使用其原生接口读取已有来源，继续插件选择和计划确认；不猜测 Git 缓存或把已有配置当作空白。
+
+执行结果分别说明已完成、保留、跳过和失败。退出安装阶段时不把“包安装成功”写成“模型、Python 计算或外部服务已可用”。
+
+## 插件清单
+
+pbot 本体作为固定必需项，不混入可选插件清单。首版候选为：
+
+| 插件 | 来源 | 首次安装默认值 | 安装后的边界 |
+| --- | --- | --- | --- |
+| Task Conductor | `npm:task-conductor-plugin` | 勾选 | 安装接入插件；服务、setup 和 MCP 接入另行完成 |
+| Pi Web Access | `npm:pi-web-access` | 勾选 | 安装搜索与内容获取插件；复用插件默认行为及已有配置 |
+
+维护者通过一份随包发布的静态清单调整候选项，位置为 `resources/installer/plugins.json`：
+
+```json
+[
+  {
+    "id": "task-conductor",
+    "label": "Task Conductor",
+    "description": "周期任务、流程和 DAG 的接入与使用引导",
+    "source": "npm:task-conductor-plugin",
+    "defaultSelected": true
+  },
+  {
+    "id": "web-access",
+    "label": "Pi Web Access",
+    "description": "网页搜索与内容获取",
+    "source": "npm:pi-web-access",
+    "defaultSelected": true
+  }
+]
+```
+
+清单只保存选择所需的元数据，不包含脚本、安装钩子、运行状态或插件专用执行逻辑。普通 npm Pi 插件只需增加清单项。安装器不提供插件市场、动态发现或用户维护清单的入口。
+
+首次安装 pbot 时，两项默认勾选。已有 pbot 时，按当前实际安装情况预选；后来新增的候选不会自动加入。取消勾选已安装插件表示本次不处理，不卸载也不禁用。移出维护者清单的插件不再由安装器安装或升级，已有副本保留。
+
+安装状态从 Pi 原生配置和实际包中取得，不另外持久化“安装器管理过哪些插件”。无法读取配置时报告错误，不当作全新工作区。
+
+## 版本、来源与作用域
+
+Pi、pbot 和选中的普通 npm 插件各自采用最新稳定版，不维护经过配套验证的固定版本组合。安装时显示当前版本和实际目标版本，结束后核对真正安装的版本。网络查询失败不能解释成“已经最新”；包版本可用也不证明整个组合已通过功能验收。
+
+| 已有状态 | setup 的行为 |
+| --- | --- |
+| 没有 Pi | 使用 npm 安装官方 `@earendil-works/pi-coding-agent`，核对可执行路径和版本 |
+| 已有持久安装的 Pi | 调用其原生 `pi update`；不支持自动更新时给出原安装方式的指引 |
+| 缺少工作区 pbot 或选中的插件 | 使用 Pi 原生本地安装 |
+| 普通 npm 来源 | 对所选工作区安装最新稳定版并核对结果 |
+| 本地源码、Git、固定版本或自定义版本范围 | 展示“保留”与“切换到 npm 最新稳定版”，默认保留 |
+| 清单外或本次未选中的插件 | 保持其原生声明，本次不安排升级或卸载 |
+| 配置损坏、来源无法辨认或存在未解决的重复加载 | 说明冲突，停止受影响项，不自动重置配置 |
+
+“保留”表示继续使用原有来源，不宣称它已升级到最新。选择切换后，只处理已明确选定的原声明与目标声明；保留源码目录和历史数据。不能在当前工作区内完成替换时，给出 Pi 原生操作指引，避免通过修改用户级声明影响其他工作区。
+
+所有插件变更显式限定所选工作区。Pi 1.5 的 `pi update <source>` 会同时匹配用户级和工作区配置，且不支持 `--local`，因此不直接用它实现本安装器的工作区插件升级。普通 npm 包通过以下形式交给 Pi 安装：
+
+```bash
+pi install --local npm:personal-bot@latest
+pi install --local npm:task-conductor-plugin@latest
+pi install --local npm:pi-web-access@latest
+```
+
+上述命令在所选工作区执行，并按实际选择逐项调用。`latest` 用于请求当前稳定标签，保留用户已有的资源过滤配置。首次用工作区声明覆盖同身份的全局 npm 包时，将原有资源过滤继承到工作区，全局声明保持不变。必要的来源切换使用原生设置机制，不重建整个 settings 文件。底层包管理器可能重新解析共享依赖，因此验收应检查已有声明与资源过滤保持正确，不能承诺安装目录中所有依赖文件完全不变。
+
+同一个 npm 包同时存在于用户级与工作区时，遵循 Pi 的原生覆盖规则，不更新用户级副本。本地源码、Git 与 npm 是不同身份，切换时必须核对有效加载来源，避免同时加载两份。
+
+安装器必须区分真实 Pi 安装与 npx 临时缓存内的可执行文件；后者不能作为已经安装了持久 Pi 的证据。npm 全局目录不可写或 PATH 无法解析目标程序时，显示明确修复指引，不隐式迁移已有安装或覆盖无关命令。
+
+## 系统依赖
+
+tmux 存在且可执行时直接复用；缺失时使用机器已有的受支持包管理器。系统包版本遵循发行版仓库，不由 pbot 维护另一套 tmux 版本。
+
+| 平台 | 自动补装渠道 |
+| --- | --- |
+| macOS | 已安装的 Homebrew |
+| Linux | 显式适配的 apt、dnf、pacman、zypper、apk |
+
+适配器只执行安装 tmux 所需的命令；不安装包管理器、不添加软件源、不顺带升级系统。需要权限时交给终端原生提权。不存在支持的包管理器或安装失败时，保留已完成步骤，提示手动完成后重跑 setup。
+
+Python 检查沿用 pbot 的解释器选择方式：优先 PATH 中的 `python3`，其次 `python`，确认版本和创建 venv 所需能力。安装器不改系统 Python，不创建共享 venv。pbot 加载后使用现有共享锁、锁定依赖和失败重试逻辑准备环境。失败由 pbot 显示，可继续使用其他能力并按既有方式重试；不改成新的工作区启用条件。
+
+## 启动与初始化
+
+完成安装阶段后提供“立即启动 Pi”，默认选择启动。启动时将子进程 cwd 设为所选工作区，继承终端，不试图修改父终端目录。
+
+正常启动语义为在该目录运行：
+
+```bash
+pi "/pbot init"
+```
+
+Pi 先处理项目信任和扩展加载，再分发启动输入。pbot 命令成功注册时，`/pbot init` 直接执行命令处理器，不需要模型认证或模型调用。初始化完成后留在同一 Pi 交互会话，登录与模型选择交给 Pi。重复 setup 后仍使用同一命令补齐缺失资料，保留已有内容。
+
+Pi 可能把未知斜杠输入继续交给模型。本次启动显式加载一个小型引导扩展，仅拦截未被命令处理的 `/pbot init`，提示 pbot 未加载并终止该输入。Pi 原生命令分发先于 input 事件，因此正常情况仍由原有命令负责。引导扩展不创建资料、不安装软件、不取得信任或登录凭据，也不持久注册。未识别到初始化命令时请求 Pi 关闭；引导文件缺失时不启动 Pi，引导加载错误使用原生启动错误处理。
+
+初始化与 Python 准备分别报告结果。安装器不通过等待固定时间、模拟键盘、分析提示文案或发送模型请求判断成功。用户选择暂不启动时，给出进入该目录并执行初始化的命令，不报告初始化已完成。
+
+## 模块与发布
+
+继续采用现有顶层分层：
+
+| 位置 | 责任 |
+| --- | --- |
+| `src/extension/setup-cli.ts` | CLI 参数、依赖装配、流程入口和退出状态 |
+| `src/services/installation/` | 安装计划、选择规则、执行顺序和结果汇总 |
+| `src/integrations/installation/` | Pi/npm、系统包管理器、环境探测和子进程启动 |
+| `src/ui/setup.ts` | 目录输入、多选、计划确认和进度展示 |
+| `resources/installer/plugins.json` | 维护者提供的配套插件清单 |
+| `src/extension/setup-guard.ts` | 本次 Pi 启动的初始化输入保护，随 CLI 编译发布 |
+| `tests/installation/` | 安装计划、作用域、路径、真实进程与失败恢复验证 |
+
+服务只接收普通数据和窄能力。CLI 不加载主扩展、创建 agent 会话或依赖预先安装的 Pi SDK。不同系统包管理器采用显式的少量适配，不引入动态插件执行框架。
+
+`package.json#bin.pbot` 指向 `bin/pbot.mjs`，再转交 `lib/extension/setup-cli.js`。`npm run build:cli` 使用现有 TypeScript 编译器和独立 tsconfig.cli.json 生成 lib，包括安装入口、原生 Pi 桥接和启动保护。扩展仍由 Pi 加载源码，dist 仍仅用于测试。npm test 的构建和 prepack 都生成 CLI；消费者无需运行构建脚本。
+
+Pi 宿主包继续作为 optional peer，不捆绑进 CLI，npx 不自动安装这些宿主依赖。CLI 入口不导入宿主；安装检查子进程在发现真实 Pi 后动态使用其公开 SDK，仅读取包配置或完成用户选择的本地来源声明替换，不创建会话、不读取认证、不启动扩展。
+
+行为变更时同步维护中英文 README、技术设计、脚本说明、发布与验证文档，区分安装辅助命令与 Pi 中的 `/pbot` 命令。版本遵循现有发布流程，不增加存储或工作区版本计数。
+
+## 失败、取消与重试
+
+| 情况 | 结果 |
+| --- | --- |
+| Pi、pbot、tmux 或必要环境检查失败 | 停止依赖步骤，不启动 Pi，显示修复与重试方式 |
+| 可选插件失败 | 继续其他独立插件，汇总后询问是否先使用 Pi |
+| 下载或安装中断 | 保留已完成步骤；下次重新探测原生状态，不假定原操作已完成 |
+| 用户取消 | 停止后续动作，保留已完成安装与已有资料 |
+| Pi 启动失败或 pbot 未加载 | 明确区分安装结果与启动失败，不发送模型请求代替初始化 |
+| pbot 初始化或 Python 准备失败 | 由 pbot 的原有命令和状态报告，不宣称环境全部就绪 |
+
+不同包管理器不构成一个事务，不自动整体回滚，也不删除环境来重试。setup 每次重新构建计划，不建立持久执行日志或安装完成标记。进程结束时保留本次安装的失败状态；可选插件失败后选择进入 Pi，也不把该安装项改成成功。
+
+## 验收
+
+实现依据包括仓库代码、Pi 文档与包管理实现，以及 npm 包元数据。具体已执行检查和外部验收缺口见[验证](validation.md)。
+
+实现至少验证以下行为：
+
+| 场景 | 验收重点 |
+| --- | --- |
+| 全新环境与 npx | 不需要预装 Pi；入口能独立运行；不会把 npx 缓存中的 peer 当作真实宿主 |
+| Linux 与 macOS | 真实环境中的 Pi/npm 路径、tmux 安装、交互终端和进程交接 |
+| 目录选择 | 当前、已有、新建、包含空格及非 ASCII 的目录；所有操作使用所选 cwd |
+| 首次安装与重复运行 | pbot 必装、默认插件、已安装预选、新候选不自动加入、再次执行正确重试 |
+| 作用域与原生配置 | 同名用户级/工作区包、资源过滤、禁用资源、无关插件与损坏配置 |
+| 自定义来源 | 本地源码、Git、固定版本的保留与显式切换；无重复加载，不删除源码 |
+| 最新版本 | 当前版本、registry 目标与实际结果一致；查询失败和目标环境不满足时不报成功 |
+| 部分失败与取消 | 依赖步骤停止、独立插件继续、重跑重新探测、不自动卸载或整体回滚 |
+| 初始化交接 | 无模型认证也能执行 `/pbot init`；拒绝信任或扩展缺失时不落入模型输入；初始化后保留 TUI |
+| 数据保留 | 已有 `AGENTS.md`、资料、历史记录和备份保持原有内容 |
+| 打包与两种入口 | tarball 中入口和资源完整；npx 与全局 `pbot setup` 均可运行 |
+
+测试使用实际本地文件、进程、打包产物和 Pi SDK，不使用假模型、模拟包管理器或个人凭据。测试安装目录、配置与缓存使用独立临时位置。系统包安装、联网 npm 分发与完整 TUI 在专门的 Linux/macOS 验收环境进行，不修改开发者现有环境来代替验收。
+
+实现提交前执行 `npm run check`、`npm test`、`git diff --check` 和 `npm pack --dry-run`。本地检查不证明未来任意最新版本组合、外部服务或模型任务可用，发布记录应写明实际验收版本与剩余缺口。

package/docs/release.md

@@ -1,6 +1,6 @@
 # npm 发布
 
-发布配置以 package.json 为准：包名 personal-bot，registry 为 npmjs，稳定版本使用 latest。包包含 Pi 扩展源码与资源，消费者由 Pi 直接加载。
+发布配置以 package.json 为准：包名 personal-bot，registry 为 npmjs，稳定版本使用 latest。包包含 Pi 扩展源码、资源和预构建的安装 CLI。扩展由 Pi 加载；npx 与全局 pbot 命令由 Node 直接运行。
 
 ## 首次配置
 
@@ -38,7 +38,7 @@ npm pack --dry-run
 npm pack
 ```
 
-核对包清单包含 src、resources、Python 锁文件、setup 脚本和 npm-shrinkwrap.json，排除 dist、node_modules、凭据与运行数据。Pi 宿主包保持 peerDependencies。
+prepack 先检查再构建 CLI。核对包清单包含 bin、lib、src、resources、Python 锁文件、setup 脚本和 npm-shrinkwrap.json，排除 dist、node_modules、凭据与运行数据。Pi 宿主包保持 optional peerDependencies，避免 npx 安装入口隐式下载宿主。另在独立 npm cache/prefix 中验证 tarball 的 npm exec 与全局 pbot --version，检查未额外安装 Pi SDK。
 
 在独立 Pi 配置和临时工作区验收安装；加载扩展会准备用户级 Python 环境，因此验收同时使用独立用户数据目录。
 

package/docs/technical-design.md

@@ -16,7 +16,7 @@ Pi 命令、工具与事件
           integrations
 ```
 
-src/pbot.ts 装配依赖并注册入口。
+src/pbot.ts 装配扩展依赖并注册入口。src/extension/setup-cli.ts 装配独立安装命令；`pbot setup` 通过原生 npm/Pi 准备一个工作区，再启动 Pi 执行 `/pbot init`。安装器的顺序、来源保留与失败恢复由 services/installation 管理，接入层调用实际宿主的包管理接口，不创建模型会话。详见[安装与升级](installation-design.md)。
 
 | 目录 | 责任 |
 | --- | --- |
@@ -99,6 +99,6 @@ WorkspaceInstance 在当前进程激活 PATH、VIRTUAL_ENV 和 Python 路径变
 
 工具提供 outputSchema，由 Pi 纳入 pbot namespace；codemode 按工具契约组合调用。原生 CLI/MCP 与可选 Task Conductor 的接入和授权见[工具与执行](capability-design.md)。
 
-包以 TypeScript 源码分发，由 Pi 加载；dist 仅供测试导入。发布版本以 package.json 为准，包内组件共用该版本。子会话兼容线在 1.0 前按次版本、1.0 起按主版本判断，跨线会话不能直接恢复。
+扩展以 TypeScript 源码分发，由 Pi 加载；dist 仅供测试导入。安装 CLI 使用现有 TypeScript 工具链单独生成 lib，由 bin/pbot.mjs 启动，消费者无需编译或预装 Pi。宿主 peer 标记 optional，避免 npx 自动安装 Pi；安装检查子进程在发现真实宿主后使用该宿主的 SDK 读取配置和切换来源声明。发布版本以 package.json 为准，包内组件共用该版本。子会话兼容线在 1.0 前按次版本、1.0 起按主版本判断，跨线会话不能直接恢复。
 
 开发验证见[验证](validation.md)，分发流程见[npm 发布](release.md)。

package/docs/validation.md

@@ -9,11 +9,12 @@ git diff --check
 npm pack --dry-run
 ```
 
-npm test 先构建 dist，再串行执行 Node 测试。测试使用真实本地文件、进程、计算与 Pi 1.4.0 SDK。Pi 开发依赖与相关传递组件统一锁定 1.4.0；宿主提供的包仍按 Pi 要求声明为 peer，不增加运行时副本。
+npm test 先构建测试导入 dist 和安装 CLI 的 lib，再串行执行 Node 测试。测试使用真实本地文件、进程、计算与 Pi 1.4.0 SDK。Pi 开发依赖与相关传递组件统一锁定 1.4.0；宿主提供的包声明为 optional peer，不增加运行时副本。发布包包含 bin/lib，扩展仍由 Pi 加载 src，dist 不进入发布包。
 
 | 范围 | 检查内容 |
 | --- | --- |
 | 领域与基础模块 | 工具契约、状态转换、版本兼容、原子保存和非法路径 |
+| tests/installation/ | 真实子进程、Pi 原生配置、来源与资源过滤保留、过期计划、CLI 打包入口、无模型认证时的初始化分发与拦截 |
 | tests/smoke/ | 实际 tarball 加载、资料准备、独立 Python setup 脚本 |
 | tests/e2e/ | Pi SDK/RPC 命令与工具、确认、持久化、重启和 Bash 环境继承 |
 | 专家协作 | 真实 tmux/Pi 进程、无任务待命、原 inbox、消息顺序、分支归属、通知领取和异常退出 |
@@ -32,6 +33,19 @@ npm test 先构建 dist，再串行执行 Node 测试。测试使用真实本地
 
 Node 测试不下载第三方 Python 依赖；原生库集成验证见 [Python 说明](../python/README.md)。
 
+## 安装器验收（2026-11-03）
+
+本次实现完成以下验证。安装验收使用临时工作区与独立的用户目录、npm cache/prefix，不使用个人凭据或模型请求：
+
+- Linux、Node 24.15.0、npm 11.19.1、Pi SDK 1.4.0：`npm ci --ignore-scripts`、`npm run check`、`npm test` 全部通过，99 项测试无跳过；`npm pack --dry-run` 通过。
+- macOS、Node 24.22.2、npm 11.19.1：17 项安装测试通过；实际 tarball 的全局安装与 npm exec 均可执行 `pbot --version`，两种安装都未下载 Pi SDK。现有 Pi 1.5.0 managed launcher 与实际安装根目录的识别通过。
+- Linux 真实终端：从无 Pi 的独立 prefix 安装 Pi 1.5.0，再通过 Pi 安装 registry 的 pbot 0.2.3；重复运行、原生项目信任确认和不启动 Pi 的选择均成功。另将临时 Pi 安装为 1.4.0，确认 setup 通过原生 `pi update` 升级至 1.5.0。工作区仅有 `npm:personal-bot@latest` 声明，未选插件未安装，未直接创建 AGENTS.md。
+- 全局 npm 资源过滤的真实终端验收：工作区声明继承 `extensions: []` 和 `skills: []`，全局配置原文未变化，未启用被禁用的资源。
+- 本次打包的 pbot 与 Pi 1.5.0 SDK 完成 `/pbot init` 分发，创建资料且不调用模型；没有 pbot 时，保护扩展拦截未分发输入。共享 Python 环境使用真实的不可用临时目录，验证失败提示和资料初始化的独立性，不作为 Python 依赖安装成功的证据。
+- 系统 Python 缺少 ensurepip 时，真实 CLI 在安装软件前退出。正向终端验收使用已存在的 Python 3.13.13，没有更改系统 Python。服务器原有 npm 12.0.2 的 `npm ci` 未接受仓库 shrinkwrap，本次仓库回归使用临时安装的 npm 11.19.1，未更换服务器 npm。
+
+仍需验收 Homebrew/各 Linux 包管理器的提权与 tmux 实际安装、macOS 完整安装交互、Pi TUI 登录及模型选择、配套插件的外部服务与模型调用。同一工作区不应并发运行多个安装器；各原生包管理器不提供跨组件事务。全局 Git/本地来源与工作区 npm 来源发生身份冲突时，安装器保留现状并要求先用 Pi 原生配置调整加载范围，不自动移除全局来源。
+
 ## 已批准的真实模型冒烟（0.1.3）
 
 2026-10-28 在 Linux、Node.js 24.15.0、tmux 3.3a、Pi 1.1.0 下验收当时的 0.1.3 源码。0.2.0 改用原生会话位置及开发依赖升级至 Pi 1.4.0 后均未追加真实模型冒烟，以下结果不作为新布局或新宿主版本的模型验收。主会话与两个独立子进程均使用 openai-codex/gpt-6-astra、low 思考级别；复用同一对成员，roundRobin 和 parallel 各运行一轮。这是同型号多 agent 验收，不是异构模型组合验收。
@@ -64,7 +78,7 @@ Node 测试不下载第三方 Python 依赖；原生库集成验证见 [Python
 | Task Conductor | 实际多节点产物、至少两轮周期任务、Pi 关闭或重载后的查询与防重复提交 |
 | CLI/MCP | 认证、发现、重连、动态工具、取消与业务结果 |
 | TUI/RPC | 人工 attach、焦点、批准、查看器、长时间运行和会话导航 |
-| npm 分发 | 全新依赖安装、Pi 安装加载、OIDC 发布与公开 registry |
+| npm 分发 | 包含安装器的新版本 OIDC 发布、公开 registry 的 npx 入口与用户环境反馈 |
 | 平台与存储 | macOS 整体验收、断电持久性与文件系统差异 |
 
 研究与资料方法使用真实任务资料验收，重点检查来源追溯、口径一致、缺失数据处理、历史前提复核、产物引用和结项依据。知识沉淀需检查是否提炼方法与口径，以及后续任务能否据此重新取数。探索任务应区分实验失败与假设被否定。

package/lib/common/package-source.js

@@ -0,0 +1,16 @@
+import { prerelease, satisfies, valid } from "semver";
+export function npmName(source) {
+    return /^npm:((?:@[a-z0-9._-]+\/)?[a-z0-9._-]+)(?:@[^\s]+)?$/.exec(source)?.[1];
+}
+export function ordinaryNpm(source) {
+    const name = npmName(source);
+    return name !== undefined && (source === `npm:${name}` || source === `npm:${name}@latest`);
+}
+export function checkStableVersion(version, nodeRange) {
+    if (!valid(version) || prerelease(version))
+        throw new Error(`latest 不是稳定版本：${version}`);
+    if (nodeRange && !satisfies(process.versions.node, nodeRange)) {
+        throw new Error(`目标版本要求 Node.js ${nodeRange}，当前为 ${process.versions.node}。请先升级 Node.js。`);
+    }
+    return version;
+}