personal-bot 0.2.2 → 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
@@ -68,12 +98,14 @@ Describe the task directly: organize project materials, compare research finding
 | --- | --- |
 | `/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 |
 | `/pbot agents` | Inspect specialists; enter sessions, send instructions, rename, or stop tasks |
 | `/pbot teams` | Inspect teams and public messages; start rounds, pause, close, or open members |
 | `/pbot python setup` | Retry shared venv preparation and activation; no path argument needed |
 | `/reload` | Pi's native command to reload extensions and resources |
 
 - **Native tools:** Use CLI commands through Bash with their current help. Keep concise provider guides and evidence references. Configure MCP for the current project by default: run `pi mcp add --local <server> ...` from the workspace root to write `.pi/mcp.json`, then inspect the configuration source with `/mcp`. Change user-level configuration only when cross-project use is explicitly requested. No Personal Bot registration, parameter binding, or permission table is needed. See the [connection skill](resources/skills/provider-connections/SKILL.md).
+- **History:** No session naming is required. Browse with `/pbot history`, or ask the assistant to look something up. `pbot_history` searches originals and summaries and follows parent/child references. Groups of four consecutive exchanges form a summary tree. Originals are searchable first; after a main interaction ends, the current Pi model builds pending summaries one at a time, including older discovered sessions. This makes extra model calls. New input cancels this work; a later idle period resumes it. Loading and searching make no model calls. Exchanges and summaries are stored in the workspace at `.pi/pbot/history/` and remain searchable when copied to another machine. Existing user-level indexes are copied into the workspace, keeping the old copies. See [history](docs/history.md).
 - **Research and analysis:** Ask the assistant to synthesize evidence, explain conflicts, check calculations and definitions, or identify assumptions to validate first.
 - **Independent sub-sessions:** Personal Bot supports tmux and independent Pi sessions; install tmux on the system to use them. `pbot_agent start` returns immediately; without a message, prompts, or files it creates an idle process without calling a model. Task completion produces a notification. Options cover models, directories, files, tools, and resources. Operations include send, follow-up, rename, status, read, stop, and explicit resume; there is no foreground/background flag or wait operation. `/pbot agents` shows active agents and can open their TUI. Main-session reload preserves running agents; exit or session switching stops them and retains history. Sub-sessions use native CLI/MCP within their delegated scope. See [specialist collaboration](docs/agent-collaboration.md).
 - **Teams:** `pbot_team` groups existing agents for `roundRobin` discussion or `parallel` rounds. Members exchange original messages through `pbot_team_message`; ordinary posts do not wake models. A running team reserves its members. Pause and drain in-flight work before private messages; reload pauses teams without replaying requests. The first release uses fixed membership and bounded rounds, not dynamic ask/reply wake-ups. See [specialist collaboration](docs/agent-collaboration.md).
@@ -92,6 +124,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 |
 | `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 |
@@ -102,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.2**. 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.
 
@@ -125,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
@@ -66,12 +96,14 @@ pi install --local npm:task-conductor-plugin
 | --- | --- |
 | `/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)。
@@ -90,6 +122,7 @@ pi install --local npm:task-conductor-plugin
 | `AGENTS.md` | 资料导航与工作约定 |
 | `areas/`、`projects/` | 长期目标、任务定义、结论与交付物 |
 | `knowledge/` | 可复用的概念、方法与口径 |
+| `.pi/pbot/history/` | 可随工作区分享的问答原文、摘要与节点关系 |
 | `providers/` | 提供方手册、覆盖缺口与验证依据 |
 | `scratch/` | 临时脚本、查询与计算数据、下载及运行环境 |
 | `agents/`、`.agents/skills/` | coordinator/general-purpose 职责补充与工作区技能 |
@@ -100,7 +133,7 @@ Personal Bot 不在工作区内保存私有启用状态。Pi 配置仍由 Pi 管
 
 ## 更新与历史数据
 
-当前版本为 **0.2.2**。不维护工作区格式、初始化状态或升级机制。插件更新使用 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 环境按原生方式显式配置；用户资料、历史证据和备份原样保留。
 
@@ -121,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

@@ -8,9 +8,11 @@
 | [技术设计](technical-design.md) | 系统组成、生命周期与资源加载 |
 | [工具与执行](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 本地验证与剩余验收见验证。
 

package/docs/file-storage.md

@@ -10,6 +10,7 @@
 | Pi 原生 sessions/ 或原生配置指定的目录 | 主会话与子会话的 JSONL 对话，由 Pi 管理 |
 | 当前 Pi agent dir 的 pbot/subagents/ | Personal Bot 子进程控制记录与原生会话引用 |
 | 当前 Pi agent dir 的 pbot/teams/ | 团队资料、批次与公共原文 |
+| 工作区 .pi/pbot/history/ | 问答原文、摘要、节点关系与来源引用；可随工作区分享 |
 | 用户级 pbot/python/.venv | 共享 Python 环境 |
 
 Pi 管理主会话、子会话对话与配置。Personal Bot 的工作区资料是普通文件，没有私有启用状态或工作区格式版本。详细目录用途见[项目 README](../README.md#工作区资料)，Python 路径见 [Python 说明](../python/README.md)。
@@ -52,10 +53,14 @@ I/O 失败后当前文件实例停止后续写入，不能因下一次读取成
 
 关闭团队不删除消息或 agent。既有 descriptor、launch、inbox、status、completions 字段不变；新增引用文件不包含存储版本计数。团队与独立通知分别记录在父 Pi 原生分支；查看公共记录不是模型已读收据。
 
+## 历史索引
+
+历史存档按原生 session ID 关联会话，保存在工作区 `.pi/pbot/history/`，包含问答文本、来源消息 ID、分支内的四叉摘要与父子关系，复用原子 JSON 写入。来源只记录原生会话 ID 和消息 ID，不保存文件路径；原始会话不可用时仍可查询已存档内容。复制到不同目录或机器后仍可读取，重新发现原生会话时复用原节点。加载时复制用户级旧目录中当前工作区缺少的记录，旧副本保留。已有工作区存档在加载时移除旧 file 字段，保留正文、摘要和节点关系。读取原生文件不迁移或重写历史，不另建工作区格式或版本计数。范围与查询见[历史对话](history.md)。
+
 ## 历史与复制
 
 0.2.0 使用新的子会话兼容线。0.1.x 的控制记录、团队记录和独立目录中的 session.jsonl 原地保留，不导入、不迁移、不自动恢复；当前列表与后台扫描不接管旧兼容线。更新前先用旧版停止活动成员，更新后重新 start。
 
-加载、资料准备和重载保留已有资料、历史记录及备份。扩展只管理自己的子会话与 Python 环境，不自动导入或转换其他应用数据。
+加载、资料准备和重载保留已有资料、历史记录及备份。扩展管理自己的子会话、历史存档与 Python 环境，不自动导入或转换其他应用数据。
 
-复制工作区前停止旧实例。复制资料不会转移用户级会话、运行进程、环境或认证；不支持多机同时写入同步目录。原子文件发布不保证外部操作恰好一次，相关验证范围见[验证](validation.md)。
+复制工作区前停止旧实例。包含 `.pi/pbot/history/` 的副本会带上问答与摘要，但不会转移用户级原生会话、运行进程、环境或认证；不支持多机同时写入同步目录。原子文件发布不保证外部操作恰好一次，相关验证范围见[验证](validation.md)。

package/docs/history.md

@@ -0,0 +1,40 @@
+# 历史对话
+
+`/pbot history [关键词]` 查询当前工作区的 Pi 历史。留空列出最近会话，选择后可查看正文、父节点和子节点；正文查看器中的修改不保存。无需 `/name`。也可以直接请 agent 查找某件事，agent 使用 `pbot_history`。
+
+## 查询
+
+| 操作 | 参数与行为 |
+| --- | --- |
+| search | query 是不区分大小写的连续文本，搜索问答原文和所有已生成摘要；省略 query 列会话。sessionId、from、to 限定会话和相交的时间范围，日期按 ISO 解析；offset/limit 分页，默认 20、最多 50 条 |
+| read | id 是搜索或导航返回的节点 ID；offset/limit 读取正文，默认 12000、最多 24000 个 UTF-16 单元；childrenOffset 分页子节点，每页 20 个 |
+
+返回的 nextOffset、nextChildrenOffset 非空时可继续读取。parents/children 提供节点 ID 与预览；共享前缀可能有多个父节点。source 给出原始 sessionId 和消息 entryIds，摘要的消息 ID 是覆盖范围的首尾。来源不保存文件路径；原始会话不可用时，已保存的问答仍可直接读取。ready=false 表示摘要尚未生成；completed=false 表示内容包含未完成的问答。
+
+查询不调用模型，不恢复会话或重放旧任务。摘要命中是检索线索，重要结论要展开到问答原文核对。全文搜索依赖词语重合，忘记原词时 agent 可以换几组词查询。不同层级的命中分别返回。
+
+## 收录与整理
+
+加载、查询和交互结束时，通过 Pi SDK 发现当前工作区会话，读取当前会话目录、原生默认目录、当前会话以及该工作区受管子会话的原生引用，按 sessionId 关联已有存档。不在发现范围内的原生会话，可通过 Pi 打开对应会话并加载 pbot 重新关联。存档不保存目录或文件路径。不会导入其他宿主或旧版 pbot 私有会话布局。Pi 分配文件名后，到首条消息写入前，文件可以不存在；扫描静默跳过这类尚未落盘的会话。
+
+原生 JSONL 只读解析。用户输入到无工具调用的最终答复组成问答；回答前的补充输入保留在同一问答。工具调用、工具结果和推理不进入问答。中断或未答记录标为未完成。历史记录缺少完整交互边界时按原生消息顺序重建，不推测隐藏的操作结果。
+
+每条原生分支独立分组，每四个连续节点形成一个摘要，再逐层合并。共同前缀复用节点，摘要不会跨分支合并。会话根节点只做目录，不生成全局摘要；不足四个的尾部节点仍可查询。连续区间与渐进合并的设计参考 [pi-optchat](https://github.com/jonaslsaa/pi-optchat)，实现与提示词由 pbot 自行维护。
+
+主交互正常结束后，在空闲阶段使用当时的 Pi 模型和原生认证串行生成摘要，也补齐已发现的历史。新输入、会话切换或关闭会取消工作；失败节点保留待处理状态，下次正常交互结束再试。加载和查询只收录原文，不启动摘要模型。原文先可查询，已有摘要在追加历史时复用。源文件缺失时继续使用工作区存档；权限、解析等其他读取错误会列出警告，已保存的内容仍可查询。
+
+摘要有额外模型调用。超长输入分段概括后再合并，原文完整保留；摘要失败不妨碍原文查询。后台摘要用量目前不计入 Pi 主会话的用量统计。Pi 原生上下文、压缩和会话恢复继续由宿主管理。
+
+## 存储与实现
+
+工作区内的 `.pi/pbot/history/<id>.json` 保存问答原文、来源消息 ID、节点关系和摘要。来源只保存原生 session ID 与消息 ID，不保存文件路径。目录本身确定工作区归属，不要求新机器的目录名与原机器一致。
+
+复制工作区时包含 `.pi/pbot/history/`，即可在另一台机器搜索和展开已有问答与摘要，继续补齐待生成摘要；原机器的 JSONL 路径不是查询前提。重新发现同一原生会话时复用原节点和摘要。这里分享的是已提取的问答与摘要，Pi 原生 `/resume` 仍需要对应 JSONL；工具日志和图片二进制不在这个存档内。
+
+加载时把当前 Pi agent dir 中旧 `pbot/history/` 下属于当前工作区、且尚未存在于新目录的记录复制过来，保留旧副本，不覆盖新存档。后续收录与摘要写入工作区目录。已有工作区存档在加载时移除旧 file 字段，保留问答、摘要及节点 ID；即使原始会话已不可用，也会完成字段清理。原生 JSONL 不改写，也不移动。
+
+这些文件是可共享的历史资料。原生 JSONL 可读时可以重新提取问答并生成摘要；原始文件已不可用时，删除工作区存档会失去这份历史。
+
+服务位于 services/history，负责分组、查询和摘要队列；integrations/pi/history 负责原生发现、问答提取和模型调用；storage/history-files 复用原子 JSON 写入。命令与工具调用同一服务。首版全文扫描，不维护数据库或向量索引；不保证多个 Pi 进程同时整理同一工作区时只产生一次摘要调用。
+
+本地测试覆盖原文保留、工具过滤、分支分组、全层搜索、分页与重载复用，以及空会话、旧目录复制、跨目录复制、旧路径清理、原始文件缺失和按会话 ID 重新关联。真实摘要质量、按大意回溯的成功率、大历史性能和完整人工浏览尚需验收，见[验证](validation.md)。

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)。
 
 | 目录 | 责任 |
 | --- | --- |
@@ -38,6 +38,7 @@ src/pbot.ts 装配依赖并注册入口。
 | PythonEnvironmentService | venv 准备、依赖检查、状态与取消等待 |
 | AgentService | 子进程、inbox、周期与交付资格；拒绝向被团队占用的成员发送私人任务 |
 | TeamService | 固定成员、公共消息、有限轮次、团队占用与暂停规则 |
+| HistoryService | 原生会话的问答索引、四叉摘要、全文查询与串行摘要队列 |
 | WorkspaceInstance | 工作区资源及环境激活的生命周期 |
 
 ## 加载与关闭
@@ -62,6 +63,10 @@ Pi 原生配置决定扩展加载范围，启动目录作为工作区根目录
 
 公共约定负责工作区与执行边界，角色负责职责与验收，技能提供专业方法与必要的本地操作约定，工具定义参数与结果语义。委派资料修改依据原任务授权及明确的文件责任，诊断环境问题不要求再次授权。工具按 action 校验必填与允许字段，返回具体参数错误；status 不读取报告正文。附件组装由 integrations/pi/agent-input 保留绝对来源及 Pi 原生读取结果。资料保存由模型按公共约定与维护技能处理，沉淀方法、口径与结论，可再次查询的数据按需获取。布局见[文件存储](file-storage.md)。
 
+## 历史查询
+
+历史服务只读提取原生会话，按分支将连续问答每四个节点逐层汇总，问答、摘要、父子关系与原文引用保存在工作区 .pi/pbot/history/。原生 session ID 关联会话，来源只保存会话 ID 与消息 ID；文件路径由 Pi 接入层在扫描时取得，不写入存档。原生文件缺失时保留已存档内容，支持随工作区复制。pbot_history 与 /pbot history 调用同一服务。加载和查询只收录；agent_settled 后使用当前模型串行补齐摘要，复用实例取消信号让新输入优先。实现与限制见[历史对话](history.md)。
+
 ## 原生子会话存储
 
 PiAgents 使用 `--session-id <agentId>` 启动新的原生会话，让 Pi 按子进程 cwd、环境变量和 settings 决定目录与文件名。AgentFiles 只保存 `session-ref.json`，初始路径为 null。子入口在首次输入前固定实际路径；已落盘会话在载入时绑定。Pi 延迟保存空会话，pbot 不写占位 JSONL 或伪造消息。
@@ -94,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)。