personal-bot 0.1.1 → 0.2.0

package/CONTEXT.md

@@ -53,11 +53,15 @@ _避免_：用工作区表示单个会话或真实账户。
 
 **独立复核者**：在新会话或独立任务节点中核验具体方案的事实与约束，给出通过、拒绝或无法确认结论的助手，不是另一个可委派的 pbot 角色类型。
 
-**专家协作**：由协调者按需委派独立子会话，并汇集结论、依据与缺口。它不规定固定研究流程，不替代用户授权，也不承载 Task Conductor 的持久调度。
+**专家协作**：保留独立委派与团队工作。协调者组织和验收，团队成员可直接交换原文；轮流讨论或并行轮次由代码安排，不依赖协调者模型逐条转述。它不规定固定研究流程，不替代用户授权，也不承载 Task Conductor 的持久调度。
+
+**团队（team）**：同一父会话中的固定成员和公共记录，以 teamId 标识。成员仍有各自的私人 Pi 上下文；团队关闭不销毁成员或清除记忆。
+
+**团队批次（team run）**：以 runId 标识的一批有限轮次，采用 roundRobin 或 parallel。后者同轮并行、轮间汇合；结束不代表业务完成，暂停或恢复不自动重跑旧请求。该 runId 与 Task Conductor 的 runId 分属不同系统。
 
 **专家职责**：通用专家 general-purpose 的工作范围与交付责任，不是子会话实例标识。工作区仅 coordinator.md 和 general-purpose.md 的职责补充会被加载。
 
-**子会话（agent）**：由 start 创建的独立 Pi 会话，以 agentId 标识。工作结束后可用 send 继续对话；停止后用 resume 携新要求显式恢复，不重放旧工作。它绑定父会话与创建分支，不是持久任务调度器。
+**子会话（agent）**：由 start 创建的独立 Pi 会话，以 agentId 标识；新布局中它也是原生 session ID，对话文件由 Pi 管理。工作结束后可用 send 继续对话；停止后用 resume 携新要求显式恢复，不重放旧工作。它绑定父会话与创建分支，不是持久任务调度器。
 
 **工作周期（cycle）**：子会话从开始处理到本轮结束的一次活动，以 cycleId 标识。一个周期可处理多条消息；进程空闲不代表上轮工作成功。
 

package/README.md

@@ -1,107 +1,121 @@
 # 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.4.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.
 
-### 可选安装 Task Conductor
+### Optional: Task Conductor
 
-需要周期任务、重复流程或 DAG 时，安装接入包 `task-conductor-plugin`。它不是服务包 `task-conductor`，也不是启用 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/task-conductor/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:task-conductor-plugin
 ```
 
-然后在 Pi 中执行 `/reload`，再调用 `/skill:using-task-conductor`。插件自带技能会在你确认后引导服务安装、`task-conductor 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.
 
-已有旧版接入包时，先用 `pi list` 核对来源和作用域，审阅官方升级说明后显式移除旧包声明，再安装新包，不同时加载两份。接入包与服务分别更新；服务升级前核对活动任务、停服并备份，按上游说明处理原生 MCP 连接，不自动迁移配置或删除历史数据。
+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 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 |
 
-- **原生工具**：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)更新当前任务及实际受影响的资料；整体整理按用户指定范围进行。当前说明按主题合并更新，保留结论、条件和任务定义；历史证据与重要决策保持可追溯。整理或结项时归集成果并清理范围内无用的临时产物，保留正式资料、历史记录与备份。
+- **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; 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).
+- **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 durable task 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`；不要因恢复会话而重发可能已产生副作用的操作。
+Main and child transcripts use Pi's native session storage. Use `pi --resume` to select a chat explicitly; `pi --continue` may select the most recently active child. Enter managed children through `/pbot agents`; stopped children reopen their saved session idle, without calling a model. Use `pbot_agent resume` to restart with a new instruction. Never open a second writer for a running child's session file. 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.1**。不维护工作区格式、初始化状态或升级机制。插件更新使用 Pi 原生包管理；本地安装则更新来源源码，依赖变化后执行 `npm ci --ignore-scripts`，再重载或重启 Pi。更换版本前先停止活动子会话；不同兼容线的子会话不能直接恢复。
+Current release: **0.2.0**. 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.
 
-## 信任与风险
+Pi stores child JSONL transcripts in its native session directory or the location selected by native configuration. In the current Pi agent directory, `pbot/subagents/` holds only control records and session references; `pbot/teams/` holds public team records. Version 0.2.0 does not support the old session location. It does not migrate or delete 0.1.x history, and excludes old records from current lists and background scheduling. Stop active children with the old version before updating, then create new agents. 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 和扩展拥有其实际账户与凭据权限，不是沙箱。需要硬限制时使用只读凭据、服务端控制或受限环境。
-- 工具可用不等于用户授权。研究、接入与验证不授权交易、转账或账本修改。
-- 协议成功不证明业务完成。取消、超时和会话恢复不撤销外部副作用；可能已发送的操作先核对原生状态，不自动重发。
-- Task Conductor 节点不自动继承主会话的工具、环境和技能。用户未授权或原生服务要求人工确认的业务，不安排无人值守执行。
+## 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
@@ -109,8 +123,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,126 @@
+# Personal Bot
+
+[English](README.md) | 简体中文
+
+**个人助手，连接知识、研究与行动。**
+
+当前基于 Pi 实现，提供按工作区加载的扩展，用于学习、项目推进、研究与决策支持，也支持投资分析与已授权业务。
+
+定位为可信模型驱动的个人助手。模型负责分析、协调与原生工具使用；pbot 提供资料入口、专家协作和 Python 环境准备。不另建主 Agent，不自动开展任务或交易。
+
+## 安装
+
+需要 Linux、Node.js 22.19+，以及已配置模型和认证的 Pi。Python 计算需要 Python 3.11+。当前开发与测试使用 Pi 1.4.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` | 查看专家状态；进入会话、补充要求、重命名或停止任务 |
+| `/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)。
+- **研究与分析**：可要求“综合这些资料并说明证据冲突”“核验这份分析的口径与计算”或“找出先要验证的关键假设”。助手按需使用[研究证据技能](resources/skills/research-evidence/SKILL.md)和[分析核验技能](resources/skills/analysis-validation/SKILL.md)，依据本次用途判断结论与限制。
+- **独立子会话**：包内提供 tmux 与独立 Pi 会话，需系统安装 tmux。`pbot_agent start` 立即返回；省略 message/prompts/files 时只创建待命进程，不调用模型。工作完成后自动通知。支持模型/目录/文件/工具与资源选项、send、follow-up、rename、status、read、stop 和显式 resume，没有前后台参数或 wait。`/pbot agents` 展示正在工作的 agent，可进入子 TUI。主 reload 保持运行，退出或切换会话停止并保留历史。子会话也使用原生 CLI/MCP，按委派范围工作。详见[专家协作](docs/agent-collaboration.md)。
+- **团队协作**：`pbot_team` 将已有 agent 组成固定团队，支持 roundRobin 轮流讨论和 parallel 并行轮次。成员通过 `pbot_team_message` 直接交换原文，普通 post 不唤醒模型。运行中的团队占用成员；先暂停并收尾，再切换私人工作。reload 暂停团队，不重放旧请求。首版不包含动态 ask/返回唤醒，详见[专家协作](docs/agent-collaboration.md)。
+- **周期与持久任务**：主会话通过原生 MCP 直接使用可选的 Task Conductor，处理周期、重复流程和 DAG；使用其 `using-task-conductor` 技能与实际工具契约。安装与接入见[可选安装引导](#可选安装-task-conductor)。缺失不影响普通 pbot 功能，但不能执行调度。pbot 不另建持久任务调度器或转发层。外部任务与子会话分别查询和停止，取消本轮不等于停止未来周期，关闭 Pi 也不代表外部任务已停止。
+- **Python 环境**：所有工作区共用当前用户的独立 venv。Personal Bot 加载后自动创建环境或安装锁定依赖，成功后在当前 Pi 进程激活；主会话与专家通过 Bash 使用 `python` 或 `python3`。环境异常时提醒，修复后用 `/pbot python setup` 重试。系统 Python、外部终端、已有脚本和历史结果不变。共享依赖更新会影响其他工作区；更换插件版本或手工重试前应停止相关脚本。详见 [Python 说明](python/README.md)与[计算参考](resources/references/compute.md)。
+- **资料维护**：可要求“整理当前项目资料”“按上次口径重做报告”或“检查交付并结项”。助手按[项目整理与维护技能](resources/skills/project-maintenance/SKILL.md)更新当前任务及实际受影响的资料；整体整理按用户指定范围进行。当前说明按主题合并更新，保留结论、条件和任务定义；历史证据与重要决策保持可追溯。整理或结项时归集成果并清理范围内无用的临时产物，保留正式资料、历史记录与备份。
+
+主会话和子会话对话都使用 Pi 原生存储。聊天恢复可用 `pi --resume` 明确选择；`pi --continue` 可能选中最近活跃的子会话。受管子会话可从 `/pbot agents` 进入，已停止时加载原会话并待命，不调用模型；`pbot_agent resume` 用于携新要求继续工作。运行中不要另开进程写同一会话文件；不要因恢复而重发可能已产生副作用的操作。
+
+不维护独立 provider 调用账本或结果包装。工具结果及大结果处理由原生工具负责，正式证据按任务保存。结果不明时先查询原生状态；进程崩溃后不保证保存完整结果。
+
+## 工作区资料
+
+| 位置 | 用途 |
+| --- | --- |
+| `AGENTS.md` | 资料导航与工作约定 |
+| `areas/`、`projects/` | 长期目标、任务定义、结论与证据 |
+| `knowledge/` | 可复用知识 |
+| `providers/` | 提供方手册、覆盖缺口与验证依据 |
+| `scratch/` | 临时计算与可重建产物 |
+| `agents/`、`.agents/skills/` | coordinator/general-purpose 职责补充与工作区技能 |
+
+Personal Bot 不在工作区内保存私有启用状态。Pi 配置仍由 Pi 管理，配置变更后按原生要求执行 `/reload`。复制工作区前停止旧实例；不支持多机同时写入同步目录。存储布局与复制边界见[文件存储](docs/file-storage.md)。
+
+## 更新与历史数据
+
+当前版本为 **0.2.0**。不维护工作区格式、初始化状态或升级机制。插件更新使用 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 环境按原生方式显式配置；用户资料、历史证据和备份原样保留。
+
+## 信任与风险
+
+- 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/README.md

@@ -9,9 +9,11 @@
 | [工具与执行](capability-design.md) | CLI/MCP 接入、授权和结果核验 |
 | [专家协作](agent-collaboration.md) | 子会话工具、通信、通知和生命周期 |
 | [文件存储](file-storage.md) | 数据位置、写入规则和历史保留 |
-| [验证](validation.md) | 本地测试范围与待验收行为 |
+| [验证](validation.md) | 本地测试、真实模型冒烟结果与剩余验收 |
 | [npm 发布](release.md) | 发布配置、授权、操作与验收 |
 
+增量设计与范围取舍见 [Subagent 升级方案](subagent-upgrade-proposal.md)。团队策略在 0.1.3 实现，0.2.0 将子会话对话交给 Pi 原生存储，不迁移旧历史。当前用法见专家协作；0.1.3 的真实模型冒烟、0.2.0 本地验证与剩余验收见验证。
+
 Python 环境与库许可见 [python/README.md](../python/README.md)。模型使用的方法维护在 resources/skills，运行时职责维护在 resources/agents。
 
 每个主题维护一份当前说明，总览通过链接引用。版本以 package.json 为准；历史设计查 Git 记录，临时排查过程不进入设计文档。

package/docs/agent-collaboration.md

@@ -1,73 +1,127 @@
 # 专家协作
 
-Personal Bot 通过 tmux 和独立 Pi 进程运行子会话，使用原生 JSONL 上下文和包内子入口。启动立即返回，工作结束后通知主会话。用户通过 /pbot agents 查看活动、进入子 TUI 或停止工作。
+Personal Bot 保留独立工作和团队工作。成员仍由 tmux 和独立 Pi 进程运行，各自保留原生 JSONL 上下文。主模型负责组织与验收，成员原文由代码同步，不需要主模型逐条转述。
 
-## 工具接口
+## 独立工作
 
 | pbot_agent action | 行为 |
 | --- | --- |
-| start | 用 message、prompts 或 files 新建上下文，可指定 name/provider/model/thinking/cwd/tools |
-| send | 向 agentId 发送 message；delivery 默认为 steer，followUp 排队 |
+| start | 新建上下文，可指定 name/provider/model/thinking/cwd/tools；有 message/prompts/files 时执行初始工作，否则只启动待命进程 |
+| send | 向 agentId 发送 message；delivery 默认为 steer，followUp 排到当前工作之后 |
 | rename | 修改名称，agentId 保持不变 |
 | status/list | 查询状态或当前父会话的子会话 |
 | read | 按 agentId、可选 cycleId 和 offset/limit 读取报告 |
 | stop | 请求停止，保留历史 |
-| resume | 用新 message 重启已停止子会话 |
+| resume | 用新 message 重启已停止子会话，不重放旧工作 |
 
-每个父会话最多保留 50 个存活进程，包括空闲进程。达到上限后需先停止一个会话。所有启动均异步，不提供 wait。
+每个父会话最多 50 个存活进程，包括待命进程。启动异步返回，不提供 wait。无任务 start 不请求模型，也不产生工作完成通知；停止未接过任务的进程不伪造失败周期。
 
-start 支持 noExtensions、noSkills、noPromptTemplates 和 noContextFiles。noExtensions 默认 true，显式保留子入口及 Pi 内置 MCP、codemode、工具搜索；设为 false 时按 Pi 规则发现其他扩展。子入口不装配递归委派工具，tools 按 Pi 原生规则选择。
+start 支持 noExtensions、noSkills、noPromptTemplates 和 noContextFiles。noExtensions 默认 true，显式保留子入口及 Pi 内置 MCP、codemode、工具搜索；设为 false 时按 Pi 规则发现其他扩展。tools 遵循 Pi 原生选择。子入口只增加 pbot_team_message，不提供 pbot_agent 或 pbot_team 管理能力。
 
-## 上下文
+初始模型与思考级别默认继承主会话；恢复时交由 Pi 使用保存的原生模型配置，不重新传入初始模型选项。模型不可用或缺少认证时仍遵循 Pi 的原生回退与错误行为。子会话从自己的 cwd 和 Pi agent dir 取得原生配置与认证，不继承父进程临时注册的模型或 MCP。环境与授权规则见[工具与执行](capability-design.md)。
 
-初始模型与思考级别默认继承主会话，可显式覆盖；恢复时采用子会话保存的模型配置。认证来自子进程可见的 Pi 配置，父进程临时注册的模型可能不可用。
+## 原生会话与恢复入口
 
-子入口按原工作区路径加载专家职责、公共约定和技能。pbot_environment 提供工作区、cwd、资源根目录与 Python 状态。子会话不继承完整父聊天，委派应明确目标、依据、约束和交付要求。
+新建 agent 的 agentId 也是 Pi session ID。对话由 Pi 保存在原生 sessions 目录或其原生配置指定的位置，按子进程 cwd 归组；pbot 只保存控制记录和文件引用。无任务待命不伪造对话，也可能尚无 JSONL 文件。首次输入前固定路径，之后恢复只打开这个文件；文件缺失或不匹配时不新建空白替代。具体规则见[文件存储](file-storage.md)。
 
-默认交回报告与产物引用；修改正式资料需要相应授权。多个助手同时工作时划分文件责任。独立复核使用新会话，而不是继续追问原分析者。
+有对话后，成员会出现在相应项目的 `pi --resume` / `/resume` 列表，并支持 Pi 原生导出。`pi --continue` 可能选中最近活跃的子会话，不保证选中主会话；需要主会话时从列表中明确选择。
 
-子会话直接使用原生 CLI/MCP，配置与授权规则见[工具与执行](capability-design.md)。基础 write/edit 拒绝需要确认的工作区外写入；其他执行能力仍使用实际账户权限。
+`/pbot agents` 的“进入 TUI”连接运行中的成员；成员已停止时，加载原会话并启动待命进程，不入队新要求、不调用模型、不重放旧工作。尚无对话文件的空会话仍以原 agentId 待命。运行中不另开进程同时写同一 JSONL。停止后从原生列表打开属于普通 Pi 对话，不恢复 pbot 成员身份或团队资格；模型工具 `pbot_agent resume` 仍用于携新要求继续工作。
 
-## 消息与周期
+## 团队与两种策略
 
-| 标识 | 含义 |
+一个团队固定一组成员，限于同一工作区、同一父 session 的可操作分支。一个 agent 最多属于一个未关闭团队。加入团队不创建新进程，关闭团队也不停止成员；换人时关闭旧团队，再用原 agent 创建新团队。
+
+| mode | 执行规则 |
 | --- | --- |
-| agentId | 持续上下文 |
-| requestId | 父侧发送的消息 |
-| cycleId | 一次 agent_start 到 agent_settled 的活动 |
+| roundRobin | 按成员顺序发言；上一位完成且原文保存后，才安排下一位；并发固定为 1 |
+| parallel | 同轮成员按并发上限工作，可直接 post/read；本轮所有答复保存后再进入下一轮 |
+
+默认 2 轮、15 分钟。轮数为 1–10；parallel 默认并发为成员数与 2 的较小值，可调到 1–成员数。期限可设 1–86400 秒。总发言请求数不超过成员数乘轮数，普通 post 不增加请求。
+
+这是有界并行轮次，不是任意点名唤醒的自由 swarm。首版不提供 ask、自动返回处理、热增减成员、跨团队私信或任务 DAG。轮内研究、实现、计算与审查方法由角色和技能决定。
+
+### 工具
+
+| pbot_team action | 行为 |
+| --- | --- |
+| create | name、brief、members[{agentId, role}]；仅建团队，不启动模型 |
+| list/status | 查看归属、成员、当前批次、activeCount 及 unresolved 请求 |
+| read | afterSeq/limit 读取公共记录；单条长消息用 seq/offset/limit |
+| run | teamId、instruction、mode，可选 rounds/maxConcurrent/timeoutSeconds；开展新批次 |
+| pause | 停止新增安排和领取，已领取请求继续收尾 |
+| close | 已暂停或结束且没有在途工作时关闭，保留历史；不阻塞等待 |
+
+run 要求全部成员空闲、无未消费的私人输入，并已加载可用的团队入口与通信工具。条件不满足时返回原因，不在后台等待成员就绪。team-ready 标记仅表示接入能力，不证明模型认证或业务能力可用。
+
+主会话与成员通过 pbot_team_message read/post 通信。post 参数为 teamId、text、可选 replyTo，正文最多 24000 字符；不允许指定 sender。成员 post 必须属于其当前团队工作，主会话可在暂停时补充信息。所有发言公开，没有私密 to 信箱。
+
+### 使用顺序
+
+1. 用 pbot_agent start 创建待命成员，或选择已有空闲成员。
+2. 用 pbot_team create 指定成员、职责与共同目标。
+3. 确认成员就绪，再 run，例如：
+   `{ action: "run", teamId: "...", instruction: "分别核对证据，下一轮回应分歧", mode: "parallel", rounds: 2, maxConcurrent: 2 }`。
+4. 主会话不逐条转发消息。批次结束或暂停后，用 read 核对成员原文及实际产物。
+5. 继续讨论须显式 run 新批次。需要私人工作时，先 pause 并等待 activeCount 为 0；必要时 stop 成员，再 send/resume。
+
+运行中的团队占用全部成员，已领取但尚未收尾的请求也占用对应成员。私人 steer/followUp 均返回 TEAM_BUSY，不另建私人等待队列。其他未被占用的 agent 可以同时独立工作。
 
-忙碌时补充消息和自动 follow-up 可属于同一周期。消息按序号消费，已接收或代次不匹配的消息不重投；接收标记不等于模型已阅读。
+## 原文、上下文与公开范围
 
-完成根据 agent_settled 与当前周期的新回答判定。失败、取消、无回答和进程死亡分别报告。进程 state/activity 与 cycle.state 分开，idle 只表示当前空闲。历史报告引用固定叶节点，后续对话不覆盖旧报告。
+团队公共记录独立于各自私人会话。新团队请求通过原有 inbox 投递；before_agent_start 注入已署名的公共原文，运行中在 turn_end 安全边界追加消息，不请求额外 continuation。空闲成员在下一次团队请求时取得信息，私人工作不自动注入新群消息。
 
-工具返回身份、名称、cwd、时间、owned、进程活动、周期、消息和分页结果。启动代次、分支锚点、报告叶节点和初始选项保存在内部记录。read 的通知领取信息保存在 details。
+成员任务、团队背景、自动注入的公共消息和批次通知使用 Markdown 文档。团队背景按共同目标、成员职责和本批次要求分节；公共消息按 seq 分节，列出作者、回复关系与来源，正文放入保留原文的代码区块，包含代码围栏的正文也不会破坏区块边界。成员原文中的 JSON 保留原样。
 
-记录布局与写入责任见[文件存储](file-storage.md)。父侧只有确认旧进程退出后，才可在 resume 前补存旧代次的中断事件。
+read 的文本结果也使用 Markdown，同时保留工具的结构化结果。nextOffset 非空表示该条正文未读完，用同一 teamId、seq 和 offset 续读；nextAfterSeq 用于后续消息。自动注入按实际 Markdown 长度限制上下文，并用 remainingFromSeq 标明未包含的消息，从 afterSeq: remainingFromSeq - 1 继续读取。不能将展示片段当作完整记录。Pi 压缩不删除公共记录。
 
-## 通知与归属
+只自动公开本次团队请求正常结束后的最终答复，不广播完整历史、推理或原始工具输出。人工输入混入周期时标记 mixed 并暂停团队，不自动公开混合答复；此前显式 post 的内容保留。成员信息与人工子会话输入都不扩大原用户授权。
 
-后台扫描状态并合并完成、失败、取消和异常退出通知，交付摘要与报告引用。主模型忙碌时在公开边界交付，空闲时触发处理。人工子 TUI 发起的工作同样标明来源并通知。
+共享上下文不是保密隔离。成员可能已经知道私人资料；暂停、关闭或创建另一团队不会清除其记忆。需要独立复核或保密边界时使用新 agent。Bash、MCP 和扩展也不是宿主沙箱。
 
-通知按 agentId/cycleId 去重。父会话中持久化的通知或有效 read 收据表示领取；UI 查看不领取，运行中 read 不领取未来结果。崩溃可能影响通知交付，但通知重试不重跑任务。
+## 周期与保存
 
-子会话绑定父 session 与创建时的分支锚点。当前分支包含锚点时，主模型才能控制会话或接收结果；其他分支只能看到归属限制，fork 不接管旧子会话。
+| 标识 | 含义 |
+| --- | --- |
+| agentId | 持续上下文 |
+| requestId | 一条父侧输入；团队关联另存，不改变旧 AgentMessage |
+| cycleId | 从工作开始到 agent_settled 的周期，包含内部多次 agent_start、工具与自动恢复 |
+| teamId / runId | 团队 / 一批有限轮次，不与 Task Conductor 的标识混用 |
+| seq | 团队内公共消息顺序 |
+
+接收、执行完成、公开答复和业务验收是不同事实。函数返回、accepted、custom entry 或 UI 查看都不证明模型已理解。idle 不表示上轮成功，finished 不表示任务通过验收或达成共识。
+
+历史报告使用固定叶节点；后续工作不覆盖旧报告。团队先保存 requestId 关联，再写原 inbox；同 ID 不重复增加序号。普通锁竞争仅重试当前进程中已知尚未发布的输入，reload 丢弃这份临时等待，不自动补发。I/O 错误使当前文件实例停止后续写入与投递。
+
+存储责任与位置见[文件存储](file-storage.md)。0.2.0 保留现有控制字段，但不兼容旧会话位置。0.1.x 记录原地保留，不迁移或接管；先在旧版停止成员，再更新并新建 agent。
+
+## 通知、归属与生命周期
 
-## UI 与生命周期
+主 agent 收到的独立子会话结果通知，以及 pbot_agent、pbot_team 和 pbot_team_message 的文本结果均使用 Markdown。列表、状态、工作周期和报告分节展示，报告保留原文；通知中的报告最多展示 2000 字符，完整内容通过 read 分页读取。工具的 structuredContent、details 与 read 收据保持原有契约。
 
-主 TUI 展示 starting、busy、stopping 的会话、名称、活动与耗时；空闲会话保留在 /pbot agents 列表。进入子 TUI 不转移控制权，人工输入与父侧消息使用 Pi 队列。
+独立周期保留原有自动通知与 read 收据。团队关联周期不重复发个人完成通知；主模型只收到批次结束、暂停和收尾状态。普通 post 不唤醒主模型。团队通知按 teamId/runId/状态去重，UI 或工具 read 不领取模型通知。
 
-子入口保持同一个会话文件，空闲时可在文件内导航，已完成周期的引用不变。无 UI/RPC 模式通过结构化工具和通知使用子会话，不支持 attach。
+团队与成员均绑定父 session/分支。失去归属时暂停新安排，不向当前主分支投递结果。fork 不接管旧团队；返回原分支不会自动恢复旧批次。公共记录与外部工作不会随树导航回滚。
 
 | 事件 | 行为 |
 | --- | --- |
-| 一轮完成 | 保持 idle，可继续对话 |
-| 主 reload | 子进程继续，新实例重新关联 |
-| 主普通输入、结束本轮、树导航 | 子进程继续；通知检查分支归属 |
-| 用户中断 | 暂停主侧自动推进与批准，下一次普通输入恢复 |
-| 主退出或切换 session | 请求清理，约 5 秒后终止仍未退出的进程 |
-| 恢复主 session | 重建历史和待通知结果，不自动启动工作 |
-| stop | 取消并清理子会话工具和连接 |
-| resume | 使用新代次和新要求，旧 inbox 与中断工具不重放 |
-| 异常崩溃 | 发现死亡进程后标记中断，保留历史 |
-
-停止或恢复不回滚外部副作用。用量与完整过程保存在各自的 Pi 原生会话中。测试和待验收行为见[验证](validation.md)。
+| 独立周期完成 | 保持 idle，可继续对话 |
+| 主 reload | 保留子进程，但暂停团队；可补交付已完成结果，不续排旧批次 |
+| 主中断 | 暂停团队新增安排，已领取工作默认收尾 |
+| 主退出或切换 session | 先暂停团队，再按原有约 5 秒宽限清理子进程 |
+| 成员 stop/异常退出/代次变化 | 暂停依赖它的批次，保留记录，不自动 resume |
+| 子 reload | 暂停团队；未完成周期或仅有领取标记的请求记为 interrupted，不重跑 |
+| 到达期限 | 停止新安排和领取；子入口尽力中断自身未被人工接管的团队工作 |
+| 恢复主 session | 恢复记录与通知，不自动启动旧工作 |
+
+pause 返回时可能仍有在途请求。unresolved 区分排队、已接收、未公开、未知结果与中断等状态；只有进程确已停止或请求已经结束，才能解除在途占用。结果未知时查原生报告和外部状态，不能将新批次视为重试许可。中断不保证撤销已发生的外部副作用。
+
+## UI 与验证边界
+
+/pbot agents 提供状态列表、进入子 TUI、补充要求、重命名和停止，不再提供单独的报告查看或恢复并继续菜单。报告仍可通过 pbot_agent read 获取。/pbot teams 提供团队状态、公共记录分页、post、新批次、pause、close，以及相同的成员菜单。无 TUI 时通过同样的结构化工具使用，不支持 attach。
+
+后台扫描遇到短暂的 `.control` 锁竞争时，在下一次扫描重试，不立即显示错误；连续至少 5 秒仍无法取得锁时显示错误。扫描成功后清除旧错误提示。此等待不自动删除锁，也不重跑旧任务；命令和工具的锁冲突仍直接报告。
+
+选择成员后，操作菜单的“进入 TUI”选项直接标明返回快捷键，选中后立即进入，不再二次确认。团队成员入口使用相同流程。默认 tmux 绑定下，普通终端按 Ctrl+B 后按 d 脱离子会话；主会话已在 tmux 中时，按 Ctrl+B 后按小写 l 切回上一个会话。自定义绑定以自己的 tmux 配置为准。返回不会停止成员，不要用 /exit 代替返回。
+
+Pi 1.4.0 的本地 SDK、实际无认证 Pi/tmux 进程、文件并发与恢复测试已覆盖基础契约。未使用假模型或模拟 provider。2026-10-28 在 0.1.3 上的真实模型双成员冒烟已通过两种策略的单轮通信、原文引用与主通知；0.2.0 的原生存储调整及 Pi 1.4.0 升级仅做本地 SDK/无认证进程验证，未追加真实模型调用；异构模型、多轮讨论、长期使用与交互 TUI 尚未验收，详见[验证](validation.md)。单轮通过不证明一般协作质量或外部操作恰好一次。