personal-bot 0.1.0 → 0.1.2

package/CONTEXT.md

@@ -41,9 +41,9 @@ _避免_：用工作区表示单个会话或真实账户。
 
 ## 任务管理
 
-**Agent Task**：主会话通过原生 MCP 使用的独立任务系统，拥有周期、重复流程、DAG 和持久执行状态，不经 pbot 专家转发。taskId 标识任务定义，runId 标识一次执行，节点 ID 标识 DAG 节点，三者不能互换，也不与 pbot 子会话的 agentId 或工作周期 cycleId 混用。
+**Task Conductor**：主会话通过原生 MCP 使用的独立任务系统，拥有周期、重复流程、DAG 和持久执行状态，不经 pbot 专家转发。taskId 标识任务定义，runId 标识一次执行，节点 ID 标识 DAG 节点，三者不能互换，也不与 pbot 子会话的 agentId 或工作周期 cycleId 混用。
 
-**定时任务**：由 Agent Task 按获授权的频率和时区触发的任务。每轮明确数据来源、期间与时点；文档记录周期不代表已经设置调度，任务本身不授予交易执行许可。取消当前执行与停止未来周期是不同操作。
+**定时任务**：由 Task Conductor 按获授权的频率和时区触发的任务。每轮明确数据来源、期间与时点；文档记录周期不代表已经设置调度，任务本身不授予交易执行许可。取消当前执行与停止未来周期是不同操作。
 
 ## 角色与执行
 
@@ -53,7 +53,7 @@ _避免_：用工作区表示单个会话或真实账户。
 
 **独立复核者**：在新会话或独立任务节点中核验具体方案的事实与约束，给出通过、拒绝或无法确认结论的助手，不是另一个可委派的 pbot 角色类型。
 
-**专家协作**：由协调者按需委派独立子会话，并汇集结论、依据与缺口。它不规定固定研究流程，不替代用户授权，也不承载 Agent Task 的持久调度。
+**专家协作**：由协调者按需委派独立子会话，并汇集结论、依据与缺口。它不规定固定研究流程，不替代用户授权，也不承载 Task Conductor 的持久调度。
 
 **专家职责**：通用专家 general-purpose 的工作范围与交付责任，不是子会话实例标识。工作区仅 coordinator.md 和 general-purpose.md 的职责补充会被加载。
 
@@ -65,7 +65,7 @@ _避免_：用工作区表示单个会话或真实账户。
 
 **专家交付**：专家为本次委派提供的报告、证据与产物引用；用户指令明确要求修改资料时，也可包含相应的资料修改。
 
-**独立复核**：由新通用专家会话或独立 Agent Task 节点，根据原始依据核验具体方案，可覆盖多个操作。不能用 send 或 steer 把原分析会话改称独立复核。它属于方案层面的工作约定，不是单次工具调用的程序门槛，也不替代用户授权；任务协调器验收不等于专业复核。
+**独立复核**：由新通用专家会话或独立 Task Conductor 节点，根据原始依据核验具体方案，可覆盖多个操作。不能用 send 或 steer 把原分析会话改称独立复核。它属于方案层面的工作约定，不是单次工具调用的程序门槛，也不替代用户授权；任务协调器验收不等于专业复核。
 
 **候选合约**：参与本次比较的具体期权合约，尚不表示可交易。
 

package/README.md

@@ -1,105 +1,119 @@
 # Personal Bot
 
-**个人助手，连接知识、研究与行动。**
+English | [简体中文](README.zh-CN.md)
 
-当前基于 Pi 实现，提供按工作区加载的扩展，用于学习、项目推进、研究与决策支持，也支持投资分析与已授权业务。
+**A personal assistant connecting knowledge, research, and action.**
 
-定位为可信模型驱动的个人助手。模型负责分析、协调与原生工具使用；pbot 提供资料入口、专家协作和 Python 环境准备。不另建主 Agent，不自动开展任务或交易。
+Personal Bot is currently a workspace-scoped [Pi](https://pi.dev) extension for learning, project work, research, and decision support, including investment analysis and explicitly authorized operations.
 
-## 安装
+The model handles analysis, coordination, and native tools. Personal Bot adds workspace materials, specialist collaboration, and Python environment preparation. It does not create a second main agent or start tasks or trades automatically.
 
-需要 Linux、Node.js 22.19+，以及已配置模型和认证的 Pi。Python 计算需要 Python 3.11+。当前开发与测试使用 Pi 1.1.0，其他宿主版本需另行验证。
+## 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.1.0; other host versions need separate validation. Native MCP and the optional Task Conductor integration require Pi 1.4.0+.
+
+From your workspace root:
 
 ```bash
-cd ~/gitsrc/personal-bot
-npm ci --ignore-scripts
+pi install --local npm:personal-bot
+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.
+
+### Install from source
+
+For development:
 
 ```bash
-pi install --local ~/gitsrc/personal-bot
+git clone https://github.com/realqiyan/personal-bot.git
+cd personal-bot
+npm ci --ignore-scripts
+cd /path/to/workspace
+pi install --local /absolute/path/to/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 两个来源。
-
-源码位于其他目录时，将安装命令中的路径换成实际绝对路径。本地安装直接加载来源目录，请保留源码和依赖。
+Replace the example paths with your actual paths. A local installation loads the source directory directly, so keep that directory and its dependencies available.
 
-### 可选安装 Agent Task
+### Optional: Task Conductor
 
-需要周期任务、重复流程或 DAG 时，安装接入包 `@realqiyan/agent-task-plugin`。它不是服务包 `@realqiyan/agent-task`，也不是启用 pbot 的前提。该接入方式需要 Pi 1.4.0+ 的原生 MCP 和 npm。
+For scheduled tasks, recurring workflows, or DAGs, install `task-conductor-plugin`. This integration package is distinct from the `task-conductor` service and is not required for Personal Bot. It requires Pi 1.4.0+ with native MCP support and npm.
 
-先用 `pi list` 检查是否已经安装；已安装但技能不可见时，检查资源是否启用并重载，不要重复安装。新安装请审阅[官方接入说明](https://github.com/realqiyan/agent-task/blob/master/docs/host-integrations.md)，从工作区根目录执行：
+Check `pi list` first. If the package is already installed but its skill is missing, check resource configuration and reload rather than installing it again. Review the [upstream integration guide](https://github.com/realqiyan/task-conductor/blob/master/docs/host-integrations.md), then run from the workspace root:
 
 ```bash
-pi install --local npm:@realqiyan/agent-task-plugin
+pi install --local npm:task-conductor-plugin
 ```
 
-然后在 Pi 中执行 `/reload`，再调用 `/skill:using-agent-task`。插件自带技能会在你确认后引导服务安装、`agent-task setup` 和原生 MCP 接入；插件安装本身不安装服务。凭据留在自己的终端或私有文件中，不发到聊天里。
+In Pi, run `/reload`, then `/skill:using-task-conductor`. With your confirmation, the skill guides service installation, `task-conductor setup`, and native MCP configuration. Installing the plugin alone does not install the service. Keep credentials in your terminal or private files, not in chat.
+
+For an older integration package, check its source and scope with `pi list`, review upstream upgrade instructions, and explicitly remove the old declaration before installing its replacement. Update the plugin and service separately. Before a service upgrade, check active tasks, stop the service, and back up its data. Follow upstream MCP instructions; do not automatically migrate configuration or delete history.
 
-`--local` 只限定插件的加载范围，不隔离服务数据；MCP 注册范围另行选择，保留已有连接，不重复注册。连接完成后用 `/mcp` 或 `pi mcp list` 检查实际工具，并按技能执行只读验证，不为安装验收创建模型任务。连接成功不证明模型认证或业务交付成功。
+`--local` limits plugin loading, not service data access. Choose MCP configuration scope separately, and keep existing connections without duplicate registration. Use `/mcp` or `pi mcp list` to check actual tools, then follow the skill's read-only validation steps. Do not create model tasks just to test installation. A working connection does not prove model authentication or task delivery.
 
-## 可选资料准备
+## Optional workspace preparation
 
-加载 Personal Bot 后可直接使用，无需初始化。需要标准资料布局时执行 `/pbot init`：只创建缺失的资料目录和根 `AGENTS.md`，不覆盖已有文件，不触发模型任务，也不要求完成确认或重载才能启用。
+Personal Bot works without initialization. Run `/pbot init` only if you want the standard material layout. It creates missing material directories and a missing root `AGENTS.md`; it does not overwrite files or start model tasks. Activation does not depend on confirmation or reload after initialization.
 
-目标、市场、偏好和工作约定保存在普通资料中，可直接请助手整理。需要接入外部工具时提供 CLI/MCP 名称、用途、官方文档或配置位置，不提供凭据值。
+Keep goals, markets, preferences, and working agreements in ordinary documents. Ask the assistant to organize them as needed. For external tools, provide the CLI/MCP name, purpose, official documentation, or configuration location—not credential values.
 
-## 日常使用
+## Daily use
 
-直接向助手说明任务，例如整理项目资料、比较研究结论、委派独立复核或运行计算。无需手动编排固定流程。
+Describe the task directly: organize project materials, compare research findings, delegate an independent review, or run calculations. No fixed workflow is required.
 
-| 命令 | 用途 |
+| Command | Purpose |
 | --- | --- |
-| `/pbot init` | 可选地补建资料目录和缺失的根 `AGENTS.md` |
-| `/pbot status` | 查看工作区路径、Personal Bot 版本和 Python 环境状态 |
-| `/pbot agents` | 查看专家执行；TUI 中可阅读报告、会话及停止任务 |
-| `/pbot python setup` | 手工重试共享 venv 的准备并激活，无需指定路径 |
-| `/reload` | Pi 原生命令，重载插件与资源 |
+| `/pbot init` | Create missing material directories and root `AGENTS.md` |
+| `/pbot status` | Show workspace path, Personal Bot version, and Python environment status |
+| `/pbot agents` | Inspect specialist runs; read reports and sessions or stop tasks in the TUI |
+| `/pbot python setup` | Retry shared venv preparation and activation; no path argument needed |
+| `/reload` | Pi's native command to reload extensions and resources |
 
-- **原生工具**：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)更新当前任务及实际受影响的资料；整体整理按用户指定范围进行。当前说明按主题合并更新，保留结论、条件和任务定义；历史证据与重要决策保持可追溯。整理或结项时归集成果并清理范围内无用的临时产物，保留正式资料、历史记录与备份。
+- **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).
+- **Research and analysis:** Ask the assistant to synthesize evidence, explain conflicts, check calculations and definitions, or identify assumptions to validate first. It uses the [research evidence](resources/skills/research-evidence/SKILL.md) and [analysis validation](resources/skills/analysis-validation/SKILL.md) skills as needed, with conclusions and limitations tied to the task.
+- **Independent sub-sessions:** Personal Bot supports tmux and independent Pi sessions; install tmux on the system to use them. `pbot_agent start` returns immediately and 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).
+- **Scheduled and durable tasks:** The main session uses optional Task Conductor directly through native MCP, its `using-task-conductor` skill, and actual tool contracts. Without it, ordinary Personal Bot features still work, but scheduling is unavailable. Personal Bot adds no scheduler or forwarding layer. Query and stop external tasks separately from sub-sessions. Cancelling the current run does not stop future recurrences, and closing Pi does not imply that external tasks stopped.
+- **Python:** All workspaces share one dedicated venv for the current user. Loading Personal Bot creates or updates it with locked dependencies and activates it in the current Pi process. Main and specialist sessions use `python` or `python3` through Bash. Failures are reported; fix the cause and retry with `/pbot python setup`. System Python, external terminals, existing scripts, and historical results are not changed. Shared dependency updates affect other workspaces, so stop relevant scripts before changing plugin versions or retrying setup. See the [Python guide](python/README.md) and [computation reference](resources/references/compute.md).
+- **Material maintenance:** Ask to organize project materials, reproduce a report using its previous definitions, or review delivery and close a task. The [project maintenance skill](resources/skills/project-maintenance/SKILL.md) updates the current task and affected materials within your requested scope. Current guidance is consolidated by topic; conclusions, conditions, task definitions, historical evidence, and important decisions remain traceable. Cleanup removes unnecessary temporary outputs within scope, not formal materials, history, or backups.
 
-聊天恢复使用 Pi 原生 `pi --continue` 或 `pi --resume`；不要因恢复会话而重发可能已产生副作用的操作。
+Resume chats with Pi's native `pi --continue` or `pi --resume`. Do not resend a potentially side-effecting operation merely because a session resumed.
 
-不维护独立 provider 调用账本或结果包装。工具结果及大结果处理由原生工具负责，正式证据按任务保存。结果不明时先查询原生状态；进程崩溃后不保证保存完整结果。
+Personal Bot maintains no separate provider-call ledger or result wrapper. Native tools own their results and large-output handling; save formal evidence with the task. If an outcome is unclear, query native status first. Complete result retention is not guaranteed after a process crash.
 
-## 工作区资料
+## Workspace materials
 
-| 位置 | 用途 |
+| Location | Purpose |
 | --- | --- |
-| `AGENTS.md` | 资料导航与工作约定 |
-| `areas/`、`projects/` | 长期目标、任务定义、结论与证据 |
-| `knowledge/` | 可复用知识 |
-| `providers/` | 提供方手册、覆盖缺口与验证依据 |
-| `scratch/` | 临时计算与可重建产物 |
-| `agents/`、`.agents/skills/` | coordinator/general-purpose 职责补充与工作区技能 |
+| `AGENTS.md` | Material navigation and working agreements |
+| `areas/`, `projects/` | Long-term goals, task definitions, conclusions, and evidence |
+| `knowledge/` | Reusable knowledge |
+| `providers/` | Provider guides, coverage gaps, and validation evidence |
+| `scratch/` | Temporary calculations and reproducible outputs |
+| `agents/`, `.agents/skills/` | Workspace additions to coordinator/general-purpose roles and workspace skills |
 
-Personal Bot 不在工作区内保存私有启用状态。Pi 配置仍由 Pi 管理，配置变更后按原生要求执行 `/reload`。复制工作区前停止旧实例；不支持多机同时写入同步目录。存储布局与复制边界见[文件存储](docs/file-storage.md)。
+Personal Bot stores no private activation state in the workspace. Pi owns its configuration; reload when required by Pi. Stop the old instance before copying a workspace. Concurrent writes from multiple machines to a synchronized directory are not supported. See [file storage](docs/file-storage.md) for storage and copying boundaries.
 
-## 更新与历史数据
+## Updates and historical data
 
-当前版本为 **0.1.0**。不维护工作区格式、初始化状态或升级机制。插件更新使用 Pi 原生包管理；本地安装则更新来源源码，依赖变化后执行 `npm ci --ignore-scripts`，再重载或重启 Pi。更换版本前先停止活动子会话；不同兼容线的子会话不能直接恢复。
+Current release: **0.1.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.
 
-子会话数据保存在当前 Pi agent dir 的 `pbot/subagents/`；共享 Python 环境使用用户级 `pbot/python/.venv`，具体系统路径见 [Python 说明](python/README.md)。不自动导入其他应用的会话、配置或环境，也不修改其数据。MCP 连接与 CLI 环境按原生方式显式配置；用户资料、历史证据和备份原样保留。
+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.
 
-## 信任与风险
+Sub-session data lives under `pbot/subagents/` in the current Pi agent directory. The shared Python environment uses the user-level `pbot/python/.venv`; see the [Python guide](python/README.md) for exact system paths. Personal Bot does not import other applications' sessions, configuration, or environments, or modify their data. Configure MCP and CLI environments explicitly through native mechanisms. Preserve user materials, historical evidence, and backups.
 
-- Personal Bot 不提供逐工具权限或统一审批。CLI、MCP、Bash、Python 和扩展拥有其实际账户与凭据权限，不是沙箱。需要硬限制时使用只读凭据、服务端控制或受限环境。
-- 工具可用不等于用户授权。研究、接入与验证不授权交易、转账或账本修改。
-- 协议成功不证明业务完成。取消、超时和会话恢复不撤销外部副作用；可能已发送的操作先核对原生状态，不自动重发。
-- Agent Task 节点不自动继承主会话的工具、环境和技能。用户未授权或原生服务要求人工确认的业务，不安排无人值守执行。
+## Trust and risks
 
-完整边界见[原生工具与执行边界](docs/capability-design.md)。真实模型、外部服务和完整 TUI/RPC 交互仍需获准环境验收，本地测试不证明实盘可用。
+- Personal Bot provides no per-tool permission system or unified approval gate. CLI, MCP, Bash, Python, and extensions have the permissions of their actual accounts and credentials. They are not sandboxed. Use read-only credentials, service-side controls, or a restricted environment for hard limits.
+- Tool availability is not user authorization. Research, connection setup, and validation do not authorize trades, transfers, or ledger changes.
+- Protocol success does not prove business completion. Cancellation, timeout, and session recovery do not undo external side effects. Check native status before retrying an operation that may have been sent.
+- Task Conductor nodes do not automatically inherit the main session's tools, environment, or skills. Do not schedule unattended operations without user authorization or when the native service requires human confirmation.
 
-## 开发与文档
+See [native tools and execution boundaries](docs/capability-design.md). Real models, external services, and full TUI/RPC interactions still require an approved acceptance environment. Local tests do not prove readiness for live trading.
+
+## Development and documentation
 
 ```bash
 npm run check
@@ -107,8 +121,10 @@ npm test
 git diff --check
 ```
 
-`npm test` 包含冒烟和 E2E 测试，并生成测试用 `dist/`；运行时直接加载源码。包内容可用 `npm pack --dry-run` 检查。测试分组与限制见[验证](docs/validation.md)。
+`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.
+
+The README is available in English and Simplified Chinese. Detailed design documents and bundled guides are currently primarily in Chinese.
 
-- [开发文档索引](docs/README.md)：架构、工具、专家协作、存储与验证。
-- [npm 发布](docs/release.md)：配置、授权、发布与安装验收。
-- [领域术语](CONTEXT.md) · [Python 环境、原生库与许可](python/README.md)。
+- [Development documentation](docs/README.md): architecture, tools, collaboration, storage, and validation.
+- [npm releases](docs/release.md): configuration, authorization, publishing, and installation acceptance.
+- [Domain terminology](CONTEXT.md) · [Python environment, native libraries, and licenses](python/README.md).

package/README.zh-CN.md

@@ -0,0 +1,124 @@
+# Personal Bot
+
+[English](README.md) | 简体中文
+
+**个人助手，连接知识、研究与行动。**
+
+当前基于 Pi 实现，提供按工作区加载的扩展，用于学习、项目推进、研究与决策支持，也支持投资分析与已授权业务。
+
+定位为可信模型驱动的个人助手。模型负责分析、协调与原生工具使用；pbot 提供资料入口、专家协作和 Python 环境准备。不另建主 Agent，不自动开展任务或交易。
+
+## 安装
+
+需要 Linux、Node.js 22.19+，以及已配置模型和认证的 Pi。Python 计算需要 Python 3.11+。当前开发与测试使用 Pi 1.1.0，其他宿主版本需另行验证。
+
+从目标工作区根目录安装 npm 包并启动：
+
+```bash
+pi install --local npm:personal-bot
+pi
+```
+
+`--local` 将包声明保存在项目 `.pi/settings.json`。按 Pi 提示确认项目信任，每次从工作区根目录启动。Pi 加载 Personal Bot 就会启用角色、技能、工具及共享 Python 环境准备；没有第二个启用开关。不要全局安装，除非希望所有 Pi 会话都启用 Personal Bot。已有全局安装请用 Pi 原生包管理或 `pi config` 调整加载范围。
+
+### 从源码安装
+
+开发时可改用本地源码：
+
+```bash
+git clone https://github.com/realqiyan/personal-bot.git
+cd personal-bot
+npm ci --ignore-scripts
+cd /path/to/workspace
+pi install --local /absolute/path/to/personal-bot
+pi
+```
+
+将示例路径换成实际路径。本地安装直接加载来源目录，请保留源码和依赖。不要同时加载源码与 npm 两个来源。
+
+### 可选安装 Task Conductor
+
+需要周期任务、重复流程或 DAG 时，安装接入包 `task-conductor-plugin`。它不是服务包 `task-conductor`，也不是启用 pbot 的前提。该接入方式需要 Pi 1.4.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
+```
+
+然后在 Pi 中执行 `/reload`，再调用 `/skill:using-task-conductor`。插件自带技能会在你确认后引导服务安装、`task-conductor setup` 和原生 MCP 接入；插件安装本身不安装服务。凭据留在自己的终端或私有文件中，不发到聊天里。
+
+已有旧版接入包时，先用 `pi list` 核对来源和作用域，审阅官方升级说明后显式移除旧包声明，再安装新包，不同时加载两份。接入包与服务分别更新；服务升级前核对活动任务、停服并备份，按上游说明处理原生 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 直接使用可选的 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 --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.2**。不维护工作区格式、初始化状态或升级机制。插件更新使用 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 和扩展拥有其实际账户与凭据权限，不是沙箱。需要硬限制时使用只读凭据、服务端控制或受限环境。
+- 工具可用不等于用户授权。研究、接入与验证不授权交易、转账或账本修改。
+- 协议成功不证明业务完成。取消、超时和会话恢复不撤销外部副作用；可能已发送的操作先核对原生状态，不自动重发。
+- Task Conductor 节点不自动继承主会话的工具、环境和技能。用户未授权或原生服务要求人工确认的业务，不安排无人值守执行。
+
+完整边界见[原生工具与执行边界](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/capability-design.md

@@ -30,13 +30,13 @@ Bash、Python、MCP 和扩展拥有其实际账户与凭据权限。文件确认
 
 工具保留原生结果与错误格式，任务按需保存证据。业务完成需核对实际结果，不能只看退出码或协议成功。取消、超时和断连后，先查询原生状态与业务标识，再决定后续操作；聊天或子会话恢复不自动重发可能已执行的操作。
 
-## 可选 Agent Task
+## 可选 Task Conductor
 
-Agent Task 通过原生 MCP 提供周期任务、重复流程和 DAG，独立管理任务定义与运行状态。安装入口见[项目 README](../README.md#可选安装-agent-task)，具体操作由其 using-agent-task 技能和实际工具契约说明。
+Task Conductor 通过原生 MCP 提供周期任务、重复流程和 DAG，独立管理任务定义与运行状态。安装入口见[项目 README](../README.md#可选安装-task-conductor)，具体操作由其 using-task-conductor 技能和实际工具契约说明。
 
-提交任务时明确输入、cwd、工具与认证前提、输出和完成条件；周期任务还需明确频率、时区、授权范围及每轮数据时点。项目资料保存必要的 taskId、runId、节点 ID 和证据，实时状态向 Agent Task 查询。
+提交任务时明确输入、cwd、工具与认证前提、输出和完成条件；周期任务还需明确频率、时区、授权范围及每轮数据时点。项目资料保存必要的 taskId、runId、节点 ID 和证据，实时状态向 Task Conductor 查询。
 
-pbot 子会话绑定父会话，Agent Task 可在 Pi 关闭后继续。两者分别查询和停止；取消当前 run 与停止未来周期也是两个操作。
+pbot 子会话绑定父会话，Task Conductor 可在 Pi 关闭后继续。两者分别查询和停止；取消当前 run 与停止未来周期也是两个操作。
 
 外部节点需单独配置工具、技能、Python 环境和认证，不自动继承主会话能力。需要人工确认的业务不安排无人值守执行。提交结果不明时先按原标识查询，避免重复创建。
 

package/docs/release.md

@@ -27,7 +27,7 @@ provenance 所用 repository 元数据须与实际公开仓库匹配。若改为
 npm version <新版本> --no-git-tag-version --ignore-scripts
 ```
 
-同步 README 的版本说明，执行：
+同步 `README.md`（默认英文）和 `README.zh-CN.md` 的版本与使用说明，执行：
 
 ```bash
 npm ci --ignore-scripts

package/docs/technical-design.md

@@ -73,7 +73,7 @@ WorkspaceInstance 在当前进程激活 PATH、VIRTUAL_ENV 和 Python 路径变
 
 ## 工具与分发
 
-工具提供 outputSchema，由 Pi 纳入 pbot namespace；codemode 按工具契约组合调用。原生 CLI/MCP 与可选 Agent Task 的接入和授权见[工具与执行](capability-design.md)。
+工具提供 outputSchema，由 Pi 纳入 pbot namespace；codemode 按工具契约组合调用。原生 CLI/MCP 与可选 Task Conductor 的接入和授权见[工具与执行](capability-design.md)。
 
 包以 TypeScript 源码分发，由 Pi 加载；dist 仅供测试导入。发布版本以 package.json 为准，包内组件共用该版本。子会话兼容线在 1.0 前按次版本、1.0 起按主版本判断，跨线会话不能直接恢复。
 

package/docs/validation.md

@@ -29,7 +29,7 @@ Node 测试不下载第三方 Python 依赖；原生库集成验证见 [Python
 | 范围 | 验收重点 |
 | --- | --- |
 | 真实模型与专家 | 委派交付、运行中 steer/follow-up、独立复核、通知推进和实际用量 |
-| Agent Task | 实际多节点产物、至少两轮周期任务、Pi 关闭或重载后的查询与防重复提交 |
+| Task Conductor | 实际多节点产物、至少两轮周期任务、Pi 关闭或重载后的查询与防重复提交 |
 | CLI/MCP | 认证、发现、重连、动态工具、取消与业务结果 |
 | TUI/RPC | 人工 attach、焦点、批准、查看器、长时间运行和会话导航 |
 | npm 分发 | 全新依赖安装、Pi 安装加载、OIDC 发布与公开 registry |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "personal-bot",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/realqiyan/personal-bot.git"
@@ -31,6 +31,7 @@
     "python/requirements.lock",
     "python/README.md",
     "README.md",
+    "README.zh-CN.md",
     "CONTEXT.md",
     "docs"
   ],

package/resources/agents/coordinator.md

@@ -6,7 +6,7 @@
 
 - 普通问答和不需要独立上下文的工作直接完成。
 - 独立协助或核验使用 pbot_agent。委派提供目标、交付要求、资料依据和约束，不依赖专家知道父会话历史。
-- 周期、重复流程、DAG 或需在当前 Pi 退出后继续的任务，先读包内 `references/agent-task.md`，再按 using-agent-task 技能使用原生任务能力。缺少该能力只阻塞依赖它的部分。
+- 周期、重复流程、DAG 或需在当前 Pi 退出后继续的任务，先读包内 `references/task-conductor.md`，再按 using-task-conductor 技能使用原生任务能力。缺少该能力只阻塞依赖它的部分。
 
 ## 委派与验收
 

package/resources/references/{agent-task.md → task-conductor.md}

@@ -1,18 +1,18 @@
-# 原生 Agent Task
+# 原生 Task Conductor
 
 主会话需要周期、重复流程、DAG 或离开当前 Pi 后继续执行时使用本文。普通独立协助使用 pbot_agent。
 
 ## 准备能力
 
-先通过 Pi 原生工具发现查找 Agent Task，并加载 using-agent-task 技能，以实际 MCP schema 为准。工具未直接显示不等于未安装；技能可用时，按技能处理连接或排障。
+先通过 Pi 原生工具发现查找 Task Conductor，并加载 using-task-conductor 技能，以实际 MCP schema 为准。工具未直接显示不等于未安装；技能可用时，按技能处理连接或排障。
 
-技能缺失时，用 `pi list` 检查插件及资源启用状态。确未安装则说明需要 Pi 1.4.0+，经用户同意后使用工作区安装命令：
+技能缺失时，用 `pi list` 检查插件及资源启用状态。已有旧版接入包时，先审阅官方升级说明，确认来源和作用域后显式替换旧包声明，不同时加载两份；服务更新与 MCP 配置另行核对，保留任务历史。确未安装则说明需要 Pi 1.4.0+，经用户同意后使用工作区安装命令：
 
 ```bash
-pi install --local npm:@realqiyan/agent-task-plugin
+pi install --local npm:task-conductor-plugin
 ```
 
-重载后通过 `/skill:using-agent-task` 处理服务安装、setup 与原生 MCP 接入。复用已有原生连接，不在聊天中索取凭据值。插件可见不证明服务已连接，执行器 ready 不证明模型认证和执行成功。
+重载后通过 `/skill:using-task-conductor` 处理服务安装、setup 与原生 MCP 接入。复用已有原生连接，不在聊天中索取凭据值。插件可见不证明服务已连接，执行器 ready 不证明模型认证和执行成功。
 
 能力不可用时说明依赖它的工作受阻，继续其他已授权工作；不以循环等待或后台子会话替代持久调度。
 
@@ -26,6 +26,6 @@ pi install --local npm:@realqiyan/agent-task-plugin
 
 ## 核对与保存
 
-任务定义、执行和节点分别用 taskId、runId 和节点 ID 标识。提交响应不明时先查原标识，不换标识重复创建。实时状态查询 Agent Task；项目资料只保存必要定义、标识和有时点的结果依据。
+任务定义、执行和节点分别用 taskId、runId 和节点 ID 标识。提交响应不明时先查原标识，不换标识重复创建。实时状态查询 Task Conductor；项目资料只保存必要定义、标识和有时点的结果依据。
 
-取消当前执行与停止未来周期分别操作，并查询确认。pbot_agent stop 或 Pi 关闭不停止 Agent Task。报告已设置调度须有实际提交结果；报告本轮成功须核对本轮产物与完成条件。
+取消当前执行与停止未来周期分别操作，并查询确认。pbot_agent stop 或 Pi 关闭不停止 Task Conductor。报告已设置调度须有实际提交结果；报告本轮成功须核对本轮产物与完成条件。