personal-bot 0.0.0-stage → 0.1.0

package/CONTEXT.md

@@ -0,0 +1,90 @@
+# Personal Bot 领域术语
+
+用于学习与知识积累、任务与项目推进、研究与决策支持。投资是专业应用领域，相关术语保留其投资含义。
+
+## 研究与接入
+
+**项目**：围绕有明确完成条件的任务保存的目标、过程、证据和结论。研究项目还保存相关假设和实验。
+
+**长期事务**：持续维护的目标、已确认约束、决策依据和复盘，可以引用多个项目。
+
+**长期投资事务**：持续维护的投资目标、已确认约束、决策依据和复盘，可以引用多个研究项目。
+
+**回测实验**：在明确历史数据、策略规则与交易假设下进行的一次检验。结果只适用于记录的条件。
+
+**交易机会分析**：结合目标、市场与持仓约束比较候选行动。等待与证据不足也是有效结论。
+
+**专业方法**：开展学习、任务、研究或复核时使用的方法、判断依据和适用条件，不是所有任务必须经过的固定阶段。
+
+**投资偏好**：用户对风险、仓位、收益、持有期限等事项的个人要求。它补充和约束专业判断，不是助手开展分析或提出方案的前置条件。
+
+**工作区记忆**：跨会话查找、使用和修正所属资料的能力。正文只维护一份；保留的知识不证明当前事实、软件可用性或操作授权。
+
+**项目资料维护**：根据已有工作结果与证据，整理和更新当前任务、直接关联资料及进行中任务的资料，由助手判断相关内容是否更新完整。可由用户主动发起，或由助手在正常交互中识别更新需要。
+
+**能力提供方（provider）**：通过 CLI 或 MCP 提供数据查询、计算或业务操作的外部系统。它不同于 `src/services/` 中的业务服务。
+
+**原生接入**：复用 CLI 的命令与认证，或使用 Pi 原生 MCP 配置、工具发现与调用。Personal Bot 不保存另一套操作目录或逐工具权限。
+
+**受控变更**：经精确准备、必要复核和用户授权后执行的业务状态改变。交易是其中一类，不代表全部变更。
+
+**接入知识**：对具体能力提供方的接口、调用方法、数据含义、限制及已验证事实的理解。知识不证明当前可用性，也不授予操作权限。
+
+**能力提供方使用手册**：汇集一个能力提供方的接入知识、资料依据和验证记录的文档。
+
+**调用约定**：原生操作的输入、结果与执行要求，按当前版本的帮助或协议定义核对。
+
+**工作区**：组织学习资料、长期事务、项目、能力接入与执行记录的工作范围。用途可以组合；投资任务可覆盖多个市场。用户资料可以共享，应用状态独立保存。
+_避免_：用工作区表示单个会话或真实账户。
+
+**Personal Bot 启用**：Pi 按原生配置加载 Personal Bot 扩展。没有独立的工作区就绪状态；资料和外部服务是否准备好不影响加载，也不证明某项能力可用或已获执行许可。
+
+## 任务管理
+
+**Agent Task**：主会话通过原生 MCP 使用的独立任务系统，拥有周期、重复流程、DAG 和持久执行状态，不经 pbot 专家转发。taskId 标识任务定义，runId 标识一次执行，节点 ID 标识 DAG 节点，三者不能互换，也不与 pbot 子会话的 agentId 或工作周期 cycleId 混用。
+
+**定时任务**：由 Agent Task 按获授权的频率和时区触发的任务。每轮明确数据来源、期间与时点；文档记录周期不代表已经设置调度，任务本身不授予交易执行许可。取消当前执行与停止未来周期是不同操作。
+
+## 角色与执行
+
+**协调者**：协助用户学习和积累知识、推进任务与项目、开展研究并支持决策的主助手，负责方案建议、专家协作和已授权操作的结果跟踪。
+
+**通用专家（general-purpose）**：pbot 唯一可委派类型，在独立子会话中完成研究、分析、计算或独立复核，按任务选择专业方法。start 使用新上下文，send 可继续既有上下文；独立复核须新建会话。通用职责不表示可以超出委派范围或绕过用户授权。
+
+**独立复核者**：在新会话或独立任务节点中核验具体方案的事实与约束，给出通过、拒绝或无法确认结论的助手，不是另一个可委派的 pbot 角色类型。
+
+**专家协作**：由协调者按需委派独立子会话，并汇集结论、依据与缺口。它不规定固定研究流程，不替代用户授权，也不承载 Agent Task 的持久调度。
+
+**专家职责**：通用专家 general-purpose 的工作范围与交付责任，不是子会话实例标识。工作区仅 coordinator.md 和 general-purpose.md 的职责补充会被加载。
+
+**子会话（agent）**：由 start 创建的独立 Pi 会话，以 agentId 标识。工作结束后可用 send 继续对话；停止后用 resume 携新要求显式恢复，不重放旧工作。它绑定父会话与创建分支，不是持久任务调度器。
+
+**工作周期（cycle）**：子会话从开始处理到本轮结束的一次活动，以 cycleId 标识。一个周期可处理多条消息；进程空闲不代表上轮工作成功。
+
+**消息请求（request）**：父侧提交的一条子会话消息，以 requestId 标识。入队或接收不证明模型已阅读或任务已完成。
+
+**专家交付**：专家为本次委派提供的报告、证据与产物引用；用户指令明确要求修改资料时，也可包含相应的资料修改。
+
+**独立复核**：由新通用专家会话或独立 Agent Task 节点，根据原始依据核验具体方案，可覆盖多个操作。不能用 send 或 steer 把原分析会话改称独立复核。它属于方案层面的工作约定，不是单次工具调用的程序门槛，也不替代用户授权；任务协调器验收不等于专业复核。
+
+**候选合约**：参与本次比较的具体期权合约，尚不表示可交易。
+
+**交易方案**：包含对象、方向、数量、价格条件及约束的具体行动建议。
+
+**交易复核**：对具体方案的规则、数据、持仓、计算和订单约束进行独立核验。复核通过不代表用户授权。
+_避免_：将批准与授权混用。
+
+**复核证据**：本次核验的规则、数据、计算和订单依据，包含来源与时间。
+
+**用户授权**：用户请求或明确确认的业务范围与条件。工具可用、研究请求和复核通过不自动授权业务变更。
+
+**执行意图**：包含目标、参数和约束的具体操作准备，不表示已获许可或已发送。
+_避免_：用订单指尚未发送的意图。
+
+**执行尝试**：一次操作进入执行阶段的事实，不证明外部能力提供方已收到或执行。
+
+**执行回执**：外部工具返回的结果，不必然证明成功或成交。
+
+**未知执行义务**：调用可能已生效但结果无法确定的待核对事项，不自动阻塞其他调用，也不授予重发许可。后续操作仍须符合当前任务授权；不能从未知结果推断没有副作用。
+
+**人工结案**：用户核对外部事实后记录处理结论，结束该未知义务的核对事项，不授权重发操作。

package/README.md

@@ -1,3 +1,114 @@
-# Temporary Holding Version
+# Personal Bot
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**个人助手，连接知识、研究与行动。**
+
+当前基于 Pi 实现，提供按工作区加载的扩展，用于学习、项目推进、研究与决策支持，也支持投资分析与已授权业务。
+
+定位为可信模型驱动的个人助手。模型负责分析、协调与原生工具使用；pbot 提供资料入口、专家协作和 Python 环境准备。不另建主 Agent，不自动开展任务或交易。
+
+## 安装
+
+需要 Linux、Node.js 22.19+，以及已配置模型和认证的 Pi。Python 计算需要 Python 3.11+。当前开发与测试使用 Pi 1.1.0，其他宿主版本需另行验证。
+
+先在源码目录安装依赖：
+
+```bash
+cd ~/gitsrc/personal-bot
+npm ci --ignore-scripts
+```
+
+再从目标工作区根目录安装并启动：
+
+```bash
+pi install --local ~/gitsrc/personal-bot
+pi
+```
+
+`--local` 将包声明保存在项目 `.pi/settings.json`。按 Pi 提示确认项目信任，每次从工作区根目录启动。Pi 加载 Personal Bot 就会启用角色、技能、工具及共享 Python 环境准备；没有第二个启用开关。不要全局安装，除非希望所有 Pi 会话都启用 Personal Bot。已有全局安装请用 Pi 原生包管理或 `pi config` 调整加载范围。npm 发布完成后也可从工作区根目录执行 `pi install --local npm:personal-bot`；发布状态须以 npmjs 为准，不要同时加载源码与 npm 两个来源。
+
+源码位于其他目录时，将安装命令中的路径换成实际绝对路径。本地安装直接加载来源目录，请保留源码和依赖。
+
+### 可选安装 Agent Task
+
+需要周期任务、重复流程或 DAG 时，安装接入包 `@realqiyan/agent-task-plugin`。它不是服务包 `@realqiyan/agent-task`，也不是启用 pbot 的前提。该接入方式需要 Pi 1.4.0+ 的原生 MCP 和 npm。
+
+先用 `pi list` 检查是否已经安装；已安装但技能不可见时，检查资源是否启用并重载，不要重复安装。新安装请审阅[官方接入说明](https://github.com/realqiyan/agent-task/blob/master/docs/host-integrations.md)，从工作区根目录执行：
+
+```bash
+pi install --local npm:@realqiyan/agent-task-plugin
+```
+
+然后在 Pi 中执行 `/reload`，再调用 `/skill:using-agent-task`。插件自带技能会在你确认后引导服务安装、`agent-task setup` 和原生 MCP 接入；插件安装本身不安装服务。凭据留在自己的终端或私有文件中，不发到聊天里。
+
+`--local` 只限定插件的加载范围，不隔离服务数据；MCP 注册范围另行选择，保留已有连接，不重复注册。连接完成后用 `/mcp` 或 `pi mcp list` 检查实际工具，并按技能执行只读验证，不为安装验收创建模型任务。连接成功不证明模型认证或业务交付成功。
+
+## 可选资料准备
+
+加载 Personal Bot 后可直接使用，无需初始化。需要标准资料布局时执行 `/pbot init`：只创建缺失的资料目录和根 `AGENTS.md`，不覆盖已有文件，不触发模型任务，也不要求完成确认或重载才能启用。
+
+目标、市场、偏好和工作约定保存在普通资料中，可直接请助手整理。需要接入外部工具时提供 CLI/MCP 名称、用途、官方文档或配置位置，不提供凭据值。
+
+## 日常使用
+
+直接向助手说明任务，例如整理项目资料、比较研究结论、委派独立复核或运行计算。无需手动编排固定流程。
+
+| 命令 | 用途 |
+| --- | --- |
+| `/pbot init` | 可选地补建资料目录和缺失的根 `AGENTS.md` |
+| `/pbot status` | 查看工作区路径、Personal Bot 版本和 Python 环境状态 |
+| `/pbot agents` | 查看专家执行；TUI 中可阅读报告、会话及停止任务 |
+| `/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)。
+- **研究与分析**：可要求“综合这些资料并说明证据冲突”“核验这份分析的口径与计算”或“找出先要验证的关键假设”。助手按需使用[研究证据技能](resources/skills/research-evidence/SKILL.md)和[分析核验技能](resources/skills/analysis-validation/SKILL.md)，依据本次用途判断结论与限制。
+- **独立子会话**：包内提供 tmux 与独立 Pi 会话，需系统安装 tmux。`pbot_agent start` 立即返回；完成后自动通知。支持模型/目录/文件/工具与资源选项、send、follow-up、rename、status、read、stop 和显式 resume，没有前后台参数或 wait。`/pbot agents` 展示正在工作的 agent，可进入子 TUI。主 reload 保持运行，退出或切换会话停止并保留历史。子会话也使用原生 CLI/MCP，按委派范围工作。详见[专家协作](docs/agent-collaboration.md)。
+- **周期与持久任务**：主会话通过原生 MCP 直接使用可选的 Agent Task，处理周期、重复流程和 DAG；使用其 `using-agent-task` 技能与实际工具契约。安装与接入见[可选安装引导](#可选安装-agent-task)。缺失不影响普通 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 --continue` 或 `pi --resume`；不要因恢复会话而重发可能已产生副作用的操作。
+
+不维护独立 provider 调用账本或结果包装。工具结果及大结果处理由原生工具负责，正式证据按任务保存。结果不明时先查询原生状态；进程崩溃后不保证保存完整结果。
+
+## 工作区资料
+
+| 位置 | 用途 |
+| --- | --- |
+| `AGENTS.md` | 资料导航与工作约定 |
+| `areas/`、`projects/` | 长期目标、任务定义、结论与证据 |
+| `knowledge/` | 可复用知识 |
+| `providers/` | 提供方手册、覆盖缺口与验证依据 |
+| `scratch/` | 临时计算与可重建产物 |
+| `agents/`、`.agents/skills/` | coordinator/general-purpose 职责补充与工作区技能 |
+
+Personal Bot 不在工作区内保存私有启用状态。Pi 配置仍由 Pi 管理，配置变更后按原生要求执行 `/reload`。复制工作区前停止旧实例；不支持多机同时写入同步目录。存储布局与复制边界见[文件存储](docs/file-storage.md)。
+
+## 更新与历史数据
+
+当前版本为 **0.1.0**。不维护工作区格式、初始化状态或升级机制。插件更新使用 Pi 原生包管理；本地安装则更新来源源码，依赖变化后执行 `npm ci --ignore-scripts`，再重载或重启 Pi。更换版本前先停止活动子会话；不同兼容线的子会话不能直接恢复。
+
+子会话数据保存在当前 Pi agent dir 的 `pbot/subagents/`；共享 Python 环境使用用户级 `pbot/python/.venv`，具体系统路径见 [Python 说明](python/README.md)。不自动导入其他应用的会话、配置或环境，也不修改其数据。MCP 连接与 CLI 环境按原生方式显式配置；用户资料、历史证据和备份原样保留。
+
+## 信任与风险
+
+- Personal Bot 不提供逐工具权限或统一审批。CLI、MCP、Bash、Python 和扩展拥有其实际账户与凭据权限，不是沙箱。需要硬限制时使用只读凭据、服务端控制或受限环境。
+- 工具可用不等于用户授权。研究、接入与验证不授权交易、转账或账本修改。
+- 协议成功不证明业务完成。取消、超时和会话恢复不撤销外部副作用；可能已发送的操作先核对原生状态，不自动重发。
+- Agent Task 节点不自动继承主会话的工具、环境和技能。用户未授权或原生服务要求人工确认的业务，不安排无人值守执行。
+
+完整边界见[原生工具与执行边界](docs/capability-design.md)。真实模型、外部服务和完整 TUI/RPC 交互仍需获准环境验收，本地测试不证明实盘可用。
+
+## 开发与文档
+
+```bash
+npm run check
+npm test
+git diff --check
+```
+
+`npm test` 包含冒烟和 E2E 测试，并生成测试用 `dist/`；运行时直接加载源码。包内容可用 `npm pack --dry-run` 检查。测试分组与限制见[验证](docs/validation.md)。
+
+- [开发文档索引](docs/README.md)：架构、工具、专家协作、存储与验证。
+- [npm 发布](docs/release.md)：配置、授权、发布与安装验收。
+- [领域术语](CONTEXT.md) · [Python 环境、原生库与许可](python/README.md)。

package/docs/README.md

@@ -0,0 +1,17 @@
+# 开发文档
+
+使用与安装见[项目 README](../README.md)。
+
+| 文档 | 内容 |
+| --- | --- |
+| [架构原则](architecture-guidelines.md) | 模块划分、依赖和开发方法 |
+| [技术设计](technical-design.md) | 系统组成、生命周期与资源加载 |
+| [工具与执行](capability-design.md) | CLI/MCP 接入、授权和结果核验 |
+| [专家协作](agent-collaboration.md) | 子会话工具、通信、通知和生命周期 |
+| [文件存储](file-storage.md) | 数据位置、写入规则和历史保留 |
+| [验证](validation.md) | 本地测试范围与待验收行为 |
+| [npm 发布](release.md) | 发布配置、授权、操作与验收 |
+
+Python 环境与库许可见 [python/README.md](../python/README.md)。模型使用的方法维护在 resources/skills，运行时职责维护在 resources/agents。
+
+每个主题维护一份当前说明，总览通过链接引用。版本以 package.json 为准；历史设计查 Git 记录，临时排查过程不进入设计文档。

package/docs/agent-collaboration.md

@@ -0,0 +1,73 @@
+# 专家协作
+
+Personal Bot 通过 tmux 和独立 Pi 进程运行子会话，使用原生 JSONL 上下文和包内子入口。启动立即返回，工作结束后通知主会话。用户通过 /pbot agents 查看活动、进入子 TUI 或停止工作。
+
+## 工具接口
+
+| pbot_agent action | 行为 |
+| --- | --- |
+| start | 用 message、prompts 或 files 新建上下文，可指定 name/provider/model/thinking/cwd/tools |
+| send | 向 agentId 发送 message；delivery 默认为 steer，followUp 排队 |
+| rename | 修改名称，agentId 保持不变 |
+| status/list | 查询状态或当前父会话的子会话 |
+| read | 按 agentId、可选 cycleId 和 offset/limit 读取报告 |
+| stop | 请求停止，保留历史 |
+| resume | 用新 message 重启已停止子会话 |
+
+每个父会话最多保留 50 个存活进程，包括空闲进程。达到上限后需先停止一个会话。所有启动均异步，不提供 wait。
+
+start 支持 noExtensions、noSkills、noPromptTemplates 和 noContextFiles。noExtensions 默认 true，显式保留子入口及 Pi 内置 MCP、codemode、工具搜索；设为 false 时按 Pi 规则发现其他扩展。子入口不装配递归委派工具，tools 按 Pi 原生规则选择。
+
+## 上下文
+
+初始模型与思考级别默认继承主会话，可显式覆盖；恢复时采用子会话保存的模型配置。认证来自子进程可见的 Pi 配置，父进程临时注册的模型可能不可用。
+
+子入口按原工作区路径加载专家职责、公共约定和技能。pbot_environment 提供工作区、cwd、资源根目录与 Python 状态。子会话不继承完整父聊天，委派应明确目标、依据、约束和交付要求。
+
+默认交回报告与产物引用；修改正式资料需要相应授权。多个助手同时工作时划分文件责任。独立复核使用新会话，而不是继续追问原分析者。
+
+子会话直接使用原生 CLI/MCP，配置与授权规则见[工具与执行](capability-design.md)。基础 write/edit 拒绝需要确认的工作区外写入；其他执行能力仍使用实际账户权限。
+
+## 消息与周期
+
+| 标识 | 含义 |
+| --- | --- |
+| agentId | 持续上下文 |
+| requestId | 父侧发送的消息 |
+| cycleId | 一次 agent_start 到 agent_settled 的活动 |
+
+忙碌时补充消息和自动 follow-up 可属于同一周期。消息按序号消费，已接收或代次不匹配的消息不重投；接收标记不等于模型已阅读。
+
+完成根据 agent_settled 与当前周期的新回答判定。失败、取消、无回答和进程死亡分别报告。进程 state/activity 与 cycle.state 分开，idle 只表示当前空闲。历史报告引用固定叶节点，后续对话不覆盖旧报告。
+
+工具返回身份、名称、cwd、时间、owned、进程活动、周期、消息和分页结果。启动代次、分支锚点、报告叶节点和初始选项保存在内部记录。read 的通知领取信息保存在 details。
+
+记录布局与写入责任见[文件存储](file-storage.md)。父侧只有确认旧进程退出后，才可在 resume 前补存旧代次的中断事件。
+
+## 通知与归属
+
+后台扫描状态并合并完成、失败、取消和异常退出通知，交付摘要与报告引用。主模型忙碌时在公开边界交付，空闲时触发处理。人工子 TUI 发起的工作同样标明来源并通知。
+
+通知按 agentId/cycleId 去重。父会话中持久化的通知或有效 read 收据表示领取；UI 查看不领取，运行中 read 不领取未来结果。崩溃可能影响通知交付，但通知重试不重跑任务。
+
+子会话绑定父 session 与创建时的分支锚点。当前分支包含锚点时，主模型才能控制会话或接收结果；其他分支只能看到归属限制，fork 不接管旧子会话。
+
+## UI 与生命周期
+
+主 TUI 展示 starting、busy、stopping 的会话、名称、活动与耗时；空闲会话保留在 /pbot agents 列表。进入子 TUI 不转移控制权，人工输入与父侧消息使用 Pi 队列。
+
+子入口保持同一个会话文件，空闲时可在文件内导航，已完成周期的引用不变。无 UI/RPC 模式通过结构化工具和通知使用子会话，不支持 attach。
+
+| 事件 | 行为 |
+| --- | --- |
+| 一轮完成 | 保持 idle，可继续对话 |
+| 主 reload | 子进程继续，新实例重新关联 |
+| 主普通输入、结束本轮、树导航 | 子进程继续；通知检查分支归属 |
+| 用户中断 | 暂停主侧自动推进与批准，下一次普通输入恢复 |
+| 主退出或切换 session | 请求清理，约 5 秒后终止仍未退出的进程 |
+| 恢复主 session | 重建历史和待通知结果，不自动启动工作 |
+| stop | 取消并清理子会话工具和连接 |
+| resume | 使用新代次和新要求，旧 inbox 与中断工具不重放 |
+| 异常崩溃 | 发现死亡进程后标记中断，保留历史 |
+
+停止或恢复不回滚外部副作用。用量与完整过程保存在各自的 Pi 原生会话中。测试和待验收行为见[验证](validation.md)。

package/docs/architecture-guidelines.md

@@ -0,0 +1,37 @@
+# 架构原则
+
+## 按责任划分
+
+按业务含义和变化原因组织模块。共同变化的内容放在一起，每条规则和每份状态有明确的所有者。
+
+保留顶层分层，在层内按领域聚合。工具契约与执行适配放在一起；服务负责业务决定和状态转换；存储负责可靠保存；接入层处理宿主协议；UI 展示数据并返回用户选择。共享目录只放多个领域实际共用的逻辑。
+
+## 复用宿主
+
+Pi 负责主会话、模型配置、工具、UI、资源发现与会话恢复。Personal Bot 补充资料准备、专家协作和 Python 环境。
+
+角色定义职责，技能描述专业方法，代码实现需要确定执行的规则。优先使用原生 CLI/MCP，执行权限由实际凭据、外部服务和运行环境约束。
+
+## 保持单向依赖
+
+服务接收普通数据与窄能力，宿主细节留在接入层。命令与工具调用同一服务。依赖边界与循环由 dependency-cruiser 检查，具体分层见[技术设计](technical-design.md)。
+
+资源的创建、状态变更和释放由同一责任主体管理。工具绑定工作区实例，实例关闭后旧调用失效。
+
+## 控制复杂度
+
+围绕已确认的需求实现最简单的方案。只有出现实际协议差异或复用需求时才引入策略和抽象。删除无用代码，避免转发层、重复状态和通用平台化。
+
+局部需求反复牵动无关模块时，先调整责任划分。已有资料与历史记录保留原样；恢复操作遵循[工具与执行](capability-design.md)中的副作用规则。
+
+## 验证行为
+
+测试业务契约和具体失败风险，使用真实本地文件、进程、计算和 Pi SDK。测试不依赖假模型、模拟 provider、个人凭据或真实交易，也不以文案和实现结构作为行为断言。
+
+本地测试与外部验收分别记录，范围见[验证](validation.md)。
+
+## 维护文档
+
+文档组织见[索引](README.md)。使用方法、行为或接口变化时更新所属主题；内部重构只更新受影响的设计说明。
+
+描述当前规则及必要理由，使用短句和一致术语。运行时提示词与开发文档分开维护，避免把开发细节加入模型上下文。

package/docs/capability-design.md

@@ -0,0 +1,43 @@
+# 工具与执行
+
+Personal Bot 使用 Pi 原生工具与配置。接入方法见[接入技能](../resources/skills/provider-connections/SKILL.md)。
+
+## 责任划分
+
+| 内容 | 所有者 |
+| --- | --- |
+| CLI 参数、校验、认证 | 原生命令、help 与 profile |
+| MCP 连接、认证、发现、schema 与结果 | Pi 原生 MCP |
+| 数据口径、项目约定与使用经验 | providers/<id>/GUIDE.md |
+| 任务范围、业务判断与必要确认 | 用户与模型 |
+| 账户权限、额度与强制批准 | 外部服务或执行环境 |
+
+工作区手册是当前使用入口，只保留必要信息；更新时合并重复内容并替换过时说明，历史证据通过项目引用追溯。接口定义以当前工具为准。
+
+## CLI 与 MCP
+
+CLI 通过 Bash 使用。新增 MCP 默认仅接入当前项目：从工作区根目录执行 `pi mcp add --local <server> ...`，写入项目 `.pi/mcp.json`；删除项目连接也显式使用 `--local`。第三方 setup 或接入向导同样核对项目范围，不接受其全局默认值。只有用户明确要求跨项目使用时才修改当前 Pi agent dir 的 `mcp.json`，已有用户级连接不自动迁移或删除。
+
+Pi 处理信任、认证与工具暴露。使用 /mcp 查看连接、工具和配置来源，确认新增连接来自当前项目；配置变更后按 Pi 要求重载。项目配置使用原生认证或环境变量引用，不保存凭据值。
+
+子会话按自己的 cwd 和 Pi agent dir 加载配置。需要工作区项目 MCP 时，以工作区根目录作为 cwd，在命令中切换计算目录。父进程临时注册的连接不会自动转移到子进程。
+
+## 授权与结果
+
+模型按用户请求和委派范围行动。研究、查询和接入不包含交易、转账或账本修改的授权。独立复核、用户授权和成果验收分别判断。
+
+Bash、Python、MCP 和扩展拥有其实际账户与凭据权限。文件确认与工具选择是防误操作措施，不是执行隔离；硬性限制使用只读凭据、服务端控制或受限环境。
+
+工具保留原生结果与错误格式，任务按需保存证据。业务完成需核对实际结果，不能只看退出码或协议成功。取消、超时和断连后，先查询原生状态与业务标识，再决定后续操作；聊天或子会话恢复不自动重发可能已执行的操作。
+
+## 可选 Agent Task
+
+Agent Task 通过原生 MCP 提供周期任务、重复流程和 DAG，独立管理任务定义与运行状态。安装入口见[项目 README](../README.md#可选安装-agent-task)，具体操作由其 using-agent-task 技能和实际工具契约说明。
+
+提交任务时明确输入、cwd、工具与认证前提、输出和完成条件；周期任务还需明确频率、时区、授权范围及每轮数据时点。项目资料保存必要的 taskId、runId、节点 ID 和证据，实时状态向 Agent Task 查询。
+
+pbot 子会话绑定父会话，Agent Task 可在 Pi 关闭后继续。两者分别查询和停止；取消当前 run 与停止未来周期也是两个操作。
+
+外部节点需单独配置工具、技能、Python 环境和认证，不自动继承主会话能力。需要人工确认的业务不安排无人值守执行。提交结果不明时先按原标识查询，避免重复创建。
+
+外部工具与真实任务的验收范围见[验证](validation.md)。

package/docs/file-storage.md

@@ -0,0 +1,40 @@
+# 文件存储
+
+## 数据位置
+
+| 位置 | 内容与所有者 |
+| --- | --- |
+| 工作区 AGENTS.md、areas/、projects/、knowledge/ 等 | 用户资料、任务定义与证据 |
+| 工作区 providers/<id>/GUIDE.md | 提供方使用说明 |
+| 工作区 .pi/settings.json、.pi/mcp.json | Pi 原生项目配置 |
+| 当前 Pi agent dir 的 pbot/subagents/ | Personal Bot 子会话记录 |
+| 用户级 pbot/python/.venv | 共享 Python 环境 |
+
+Pi 管理主会话与配置。Personal Bot 的工作区资料是普通文件，没有私有启用状态或工作区格式版本。详细目录用途见[项目 README](../README.md#工作区资料)，Python 路径见 [Python 说明](../python/README.md)。
+
+## 资料准备
+
+`/pbot init` 创建缺失的资料目录与根 AGENTS.md。已有文档保持不变；目录冲突或符号链接时报错，已创建资料保留，再次执行可继续补缺。
+
+## 子会话保存
+
+每个 agentId 对应一个目录：
+
+| 文件或记录 | 内容 |
+| --- | --- |
+| descriptor | 工作区、父 session 与分支锚点 |
+| launch | 启动代次、名称、消息序号与停止要求 |
+| inbox | 父侧消息 |
+| status | 子侧活动与接收标记 |
+| completions | 周期结果引用 |
+| session.jsonl | Pi 原生对话 |
+
+父侧写控制记录，子侧写状态和完成事件，交付收据进入父 Pi 会话。通信顺序与恢复规则见[专家协作](agent-collaboration.md)。
+
+atomic-json 校验完整对象，写入并同步临时文件后原子发布；拒绝目录别名、越界和特殊文件，createOnly 保证不覆盖已有目标。短控制操作使用目录锁。处理崩溃遗留锁前须停止相关 Pi 进程。
+
+## 历史与复制
+
+加载、资料准备和重载保留已有资料、历史记录及备份。扩展只管理自己的子会话与 Python 环境，不自动导入或转换其他应用数据。
+
+复制工作区前停止旧实例。复制资料不会转移用户级会话、运行进程、环境或认证；不支持多机同时写入同步目录。原子文件发布不保证外部操作恰好一次，相关验证范围见[验证](validation.md)。

package/docs/release.md

@@ -0,0 +1,96 @@
+# npm 发布
+
+发布配置以 package.json 为准：包名 personal-bot，registry 为 npmjs，稳定版本使用 latest。包包含 Pi 扩展源码与资源，消费者由 Pi 直接加载。
+
+## 首次配置
+
+发布前完成以下配置：
+
+| 位置 | 配置 |
+| --- | --- |
+| npm | 确认包名与发布账号权限 |
+| package.json | 补充许可证、对应许可文件及实际 repository 地址 |
+| GitHub 仓库 | 确认默认分支；ci.yml 默认监听 main/master |
+| GitHub Environment | 创建 npm，配置审核人，部署来源限制为 v* tag |
+| GitHub ruleset | 限制发布 tag 的创建、修改和删除 |
+| npm Trusted Publisher | 填入实际 GitHub owner/repository、publish.yml 和 Environment npm |
+
+Trusted Publisher 使用 GitHub OIDC，无需保存 NPM_TOKEN。首次包创建与授权条件见 [npm 官方说明](https://docs.npmjs.com/trusted-publishers/)。需要先创建包时，由维护者完成首次本机发布，再配置 Trusted Publisher。
+
+provenance 所用 repository 元数据须与实际公开仓库匹配。若改为 scoped 包名，同步修改包与锁文件、工作流中的包名和 tarball 名、安装说明。第三方 Python 库许可见 [Python 说明](../python/README.md)。
+
+## 准备候选包
+
+使用 Linux、Node.js 22.19+ 和 Python 3.11+。更新版本：
+
+```bash
+npm version <新版本> --no-git-tag-version --ignore-scripts
+```
+
+同步 README 的版本说明，执行：
+
+```bash
+npm ci --ignore-scripts
+npm run check
+npm test
+git diff --check
+npm pack --dry-run
+npm pack
+```
+
+核对包清单包含 src、resources、Python 锁文件、setup 脚本和 npm-shrinkwrap.json，排除 dist、node_modules、凭据与运行数据。Pi 宿主包保持 peerDependencies。
+
+在独立 Pi 配置和临时工作区验收安装；加载扩展会准备用户级 Python 环境，因此验收同时使用独立用户数据目录。
+
+## GitHub 发布
+
+[CI](../.github/workflows/ci.yml) 在 Node 22.19.0/24.x 执行检查和测试，再生成候选 tarball。[发布工作流](../.github/workflows/publish.yml)要求：
+
+- tag 为 v<稳定版本>，包与锁文件版本一致。
+- 提交已进入远端默认分支。
+- 目标 npm 版本不存在，registry 返回明确 404。
+- 通过 npm Environment 中配置的审核。
+
+将审核后的提交推送到默认分支，再推送对应 tag：
+
+```bash
+VERSION=$(node -p "require('./package.json').version")
+git tag "v$VERSION"
+git push origin "v$VERSION"
+```
+
+发布作业下载本次 CI 的同一 tarball，使用 OIDC 和 provenance 上传，跳过包脚本，然后查询公开版本与 latest。普通分支推送只运行 CI；已推送的发布 tag 保持不变。预发布版本不适用此流程。
+
+## 本机发布
+
+维护者完成候选检查，在自己的终端登录并核对账号：
+
+```bash
+npm login --registry=https://registry.npmjs.org
+npm whoami --registry=https://registry.npmjs.org
+npm view personal-bot versions --json --registry=https://registry.npmjs.org
+```
+
+确认目标版本未占用后，发布已检查的 tarball：
+
+```bash
+VERSION=$(node -p "require('./package.json').version")
+npm publish "./personal-bot-$VERSION.tgz" --ignore-scripts \
+  --access public --tag latest --registry=https://registry.npmjs.org
+```
+
+首次包不存在可返回 E404；认证或网络错误需先处理。本机发布通过 npm 官方登录和 2FA 完成，不提供 GitHub provenance。凭据与验证码留在维护者终端，不进入聊天、Git 或日志。
+
+## 发布后验收
+
+```bash
+VERSION=$(node -p "require('./package.json').version")
+npm view "personal-bot@$VERSION" version --registry=https://registry.npmjs.org
+npm view personal-bot dist-tags --json --registry=https://registry.npmjs.org
+```
+
+在独立 Pi 配置和临时工作区执行 `pi install --local npm:personal-bot`，核对安装版本、扩展加载、技能发现和 /pbot status。
+
+上传结果不明时先查询 registry。若上传完成但后续查询失败，手动运行 Publish npm，选择原版本 tag 并保持 verify_only=true。该模式重新执行检查与 registry 查询，不上传；目标版本已不是 latest 时会失败。
+
+已发布版本不可覆盖。问题修复由维护者选择新版本、弃用说明或 dist-tag 调整。当前远端发布和全新安装仍待验收，范围见[验证](validation.md)。

package/docs/technical-design.md

@@ -0,0 +1,80 @@
+# 技术设计
+
+Personal Bot 是按工作区加载的 Pi 扩展。模型负责分析、协调和工具使用；扩展负责资料准备、专家会话和共享 Python 环境。安装与命令见[项目 README](../README.md)。
+
+## 模块与依赖
+
+```text
+Pi 命令、工具与事件
+         ↓
+ tools / extension / ui
+         ↓
+      services
+      ↙      ↘
+ storage   窄能力约定
+               ↑
+          integrations
+```
+
+src/pbot.ts 装配依赖并注册入口。
+
+| 目录 | 责任 |
+| --- | --- |
+| src/tools/ | 输入、输出、schema、执行适配和工具列表 |
+| src/services/ | 业务规则、状态变更和操作顺序，按 agents、workspace 聚合 |
+| src/model/ | 数据类 |
+| src/integrations/ | Pi 会话、Python 环境激活与进程执行 |
+| src/storage/ | 原子 JSON 与子会话文件 |
+| src/extension/ | 命令、事件和资源生命周期 |
+| src/ui/ | 确认队列、对话框和专家展示 |
+| src/common/ | JSON、校验、文件、包路径和版本辅助逻辑 |
+| resources/ | 角色、技能、提示词、模板和参考资料 |
+
+服务不依赖 Pi SDK、工具或 UI。共享进程执行可直接使用，其他宿主能力通过窄接口传入。接入层可引用服务类型；命令和工具通过服务执行状态变更。数据类在进入 JSON、存储和工具结果前转为普通数据。
+
+| 主体 | 管理内容 |
+| --- | --- |
+| prepareWorkspace | 补建资料目录与根 AGENTS.md |
+| PythonEnvironmentService | venv 准备、依赖检查、状态与取消等待 |
+| AgentService | 子进程、消息、周期与交付资格 |
+| WorkspaceInstance | 工作区资源及环境激活的生命周期 |
+
+## 加载与关闭
+
+Pi 原生配置决定扩展加载范围，启动目录作为工作区根目录。session_start 创建实例、提供工具与技能，并准备共享 Python 环境。加载本身不开展模型任务。
+
+`/pbot init` 可选地补建资料，已有文件保持不变。`/pbot status` 展示路径、版本和 Python 状态；模型通过每轮 pbot_environment 取得工作区、cwd、资源根目录和进程环境信息。
+
+主 reload 保留子进程并重新关联；退出或切换会话时清理子进程、取消环境准备并恢复本实例持有的环境变量。关闭操作幂等。子会话的分支归属、通知和恢复规则见[专家协作](agent-collaboration.md)。
+
+## 资源加载
+
+| 资源 | 用途与加载方式 |
+| --- | --- |
+| resources/prompts/workspace.md | 主会话与专家的公共约定 |
+| resources/agents/、工作区 agents/ | coordinator、general-purpose 及同名工作区补充 |
+| resources/skills/ | 通过 resources_discover 提供；专家同时发现工作区技能 |
+| resources/references/ | 按需读取的操作参考 |
+| resources/templates/workspace-agents.md | 补建根资料入口的模板 |
+
+主会话通过 before_agent_start 增加提示词 section，同时保留 Pi 原生 AGENTS.md 加载。资源在使用时读取，缺失时报错；提示词更新后通过 /reload 或重启加载。
+
+公共约定负责工作区与执行边界，角色负责职责与验收，技能提供专业方法与必要的本地操作约定，工具定义参数与结果语义。工作区资料保存目标、偏好、任务定义和证据，布局见[文件存储](file-storage.md)。
+
+## Python 环境
+
+所有工作区共用当前用户的 venv。PythonEnvironmentService 调用 scripts/setup-python.py，按 python/requirements.lock 创建或对齐依赖，完成 pip check、库导入和基础计算检查后标记就绪。安装仅使用 wheel。
+
+共享锁串行化跨进程 setup，同一服务合并重叠请求。失败或取消时保留环境并报告状态，其他扩展功能继续可用；可通过 `/pbot python setup` 重试。
+
+WorkspaceInstance 在当前进程激活 PATH、VIRTUAL_ENV 和 Python 路径变量，供主会话与专家的 Bash 继承。关闭时恢复仍由本实例持有的变量。环境更新会影响其他工作区，更新前应停止相关脚本。
+
+计算通过原生 Bash 和第三方库 API 执行，使用项目自身的目录、输入和输出约定。路径、安装条件与许可见 [Python 说明](../python/README.md)。
+
+## 工具与分发
+
+工具提供 outputSchema，由 Pi 纳入 pbot namespace；codemode 按工具契约组合调用。原生 CLI/MCP 与可选 Agent Task 的接入和授权见[工具与执行](capability-design.md)。
+
+包以 TypeScript 源码分发，由 Pi 加载；dist 仅供测试导入。发布版本以 package.json 为准，包内组件共用该版本。子会话兼容线在 1.0 前按次版本、1.0 起按主版本判断，跨线会话不能直接恢复。
+
+开发验证见[验证](validation.md)，分发流程见[npm 发布](release.md)。

package/docs/validation.md

@@ -0,0 +1,40 @@
+# 验证
+
+## 本地检查
+
+```bash
+npm run check
+npm test
+git diff --check
+npm pack --dry-run
+```
+
+npm test 先构建 dist，再串行执行 Node 测试。测试使用真实本地文件、进程、计算与 Pi SDK。
+
+| 范围 | 检查内容 |
+| --- | --- |
+| 领域与基础模块 | 工具契约、状态转换、版本兼容、原子保存和非法路径 |
+| tests/smoke/ | 实际 tarball 加载、资料准备、独立 Python setup 脚本 |
+| tests/e2e/ | Pi SDK/RPC 命令与工具、确认、持久化、重启和 Bash 环境继承 |
+| 专家协作 | 真实 tmux/Pi 进程、消息顺序、分支归属、通知领取和异常退出 |
+
+冒烟与 E2E 可分别运行 npm run test:smoke 和 npm run test:e2e。驱动直接提交工具输入，不生成模型响应。打包冒烟复用本地已安装依赖。
+
+Node 测试不下载第三方 Python 依赖；原生库集成验证见 [Python 说明](../python/README.md)。
+
+## 外部验收
+
+以下行为需要获准环境，尚不能由本地测试确认：
+
+| 范围 | 验收重点 |
+| --- | --- |
+| 真实模型与专家 | 委派交付、运行中 steer/follow-up、独立复核、通知推进和实际用量 |
+| Agent Task | 实际多节点产物、至少两轮周期任务、Pi 关闭或重载后的查询与防重复提交 |
+| CLI/MCP | 认证、发现、重连、动态工具、取消与业务结果 |
+| TUI/RPC | 人工 attach、焦点、批准、查看器、长时间运行和会话导航 |
+| npm 分发 | 全新依赖安装、Pi 安装加载、OIDC 发布与公开 registry |
+| 平台与存储 | macOS 整体验收、断电持久性与文件系统差异 |
+
+研究与资料方法使用真实任务资料验收，重点检查来源追溯、口径一致、缺失数据处理、历史前提复核、产物引用和结项依据。探索任务应区分实验失败与假设被否定。
+
+记录验收环境、实际结果、证据位置与剩余缺口。连接可用、资源可见或格式正确只证明相应技术环节，不代表模型完成了业务任务。