personal-bot 0.1.2 → 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

@@ -10,7 +10,7 @@ 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.1.0; other host versions need separate validation. Native MCP and the optional Task Conductor integration require Pi 1.4.0+.
+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:
 
@@ -68,18 +68,20 @@ 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 agents` | Inspect specialist runs; read reports and sessions or stop tasks in the TUI |
+| `/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).
 - **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.
+- **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.
 
-Resume chats with Pi's native `pi --continue` or `pi --resume`. Do not resend a potentially side-effecting operation merely because a session resumed.
+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.
 
 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.
 
@@ -98,11 +100,11 @@ Personal Bot stores no private activation state in the workspace. Pi owns its co
 
 ## Updates and historical data
 
-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.
+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.
 
 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.
+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.
 
 ## Trust and risks
 

package/README.zh-CN.md

@@ -10,7 +10,7 @@
 
 ## 安装
 
-需要 Linux、Node.js 22.19+，以及已配置模型和认证的 Pi。Python 计算需要 Python 3.11+。当前开发与测试使用 Pi 1.1.0，其他宿主版本需另行验证。
+需要 Linux、Node.js 22.19+，以及已配置模型和认证的 Pi。Python 计算需要 Python 3.11+。当前开发与测试使用 Pi 1.4.0，其他宿主版本需另行验证。
 
 从目标工作区根目录安装 npm 包并启动：
 
@@ -66,18 +66,20 @@ pi install --local npm:task-conductor-plugin
 | --- | --- |
 | `/pbot init` | 可选地补建资料目录和缺失的根 `AGENTS.md` |
 | `/pbot status` | 查看工作区路径、Personal Bot 版本和 Python 环境状态 |
-| `/pbot agents` | 查看专家执行；TUI 中可阅读报告、会话及停止任务 |
+| `/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` 立即返回；完成后自动通知。支持模型/目录/文件/工具与资源选项、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 也不代表外部任务已停止。
+- **独立子会话**：包内提供 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 --continue` 或 `pi --resume`；不要因恢复会话而重发可能已产生副作用的操作。
+主会话和子会话对话都使用 Pi 原生存储。聊天恢复可用 `pi --resume` 明确选择；`pi --continue` 可能选中最近活跃的子会话。受管子会话可从 `/pbot agents` 进入，已停止时加载原会话并待命，不调用模型；`pbot_agent resume` 用于携新要求继续工作。运行中不要另开进程写同一会话文件；不要因恢复而重发可能已产生副作用的操作。
 
 不维护独立 provider 调用账本或结果包装。工具结果及大结果处理由原生工具负责，正式证据按任务保存。结果不明时先查询原生状态；进程崩溃后不保证保存完整结果。
 
@@ -96,9 +98,9 @@ Personal Bot 不在工作区内保存私有启用状态。Pi 配置仍由 Pi 管
 
 ## 更新与历史数据
 
-当前版本为 **0.1.2**。不维护工作区格式、初始化状态或升级机制。插件更新使用 Pi 原生包管理；本地安装则更新来源源码，依赖变化后执行 `npm ci --ignore-scripts`，再重载或重启 Pi。更换版本前先停止活动子会话；不同兼容线的子会话不能直接恢复。
+当前版本为 **0.2.0**。不维护工作区格式、初始化状态或升级机制。插件更新使用 Pi 原生包管理；本地安装则更新来源源码，依赖变化后执行 `npm ci --ignore-scripts`，再重载或重启 Pi。更换版本前先停止活动子会话；不同兼容线的子会话不能直接恢复。
 
-子会话数据保存在当前 Pi agent dir 的 `pbot/subagents/`；共享 Python 环境使用用户级 `pbot/python/.venv`，具体系统路径见 [Python 说明](python/README.md)。不自动导入其他应用的会话、配置或环境，也不修改其数据。MCP 连接与 CLI 环境按原生方式显式配置；用户资料、历史证据和备份原样保留。
+子会话 JSONL 由 Pi 保存在原生 sessions 目录或原生配置指定的位置；`pbot/subagents/` 只保存控制记录与会话引用，团队公共记录保存在 `pbot/teams/`。0.2.0 不兼容旧会话位置，不迁移或删除 0.1.x 历史；旧记录不进入当前列表或后台调度。先在旧版停止活动成员，更新后重新创建 agent。共享 Python 环境使用用户级 `pbot/python/.venv`，具体系统路径见 [Python 说明](python/README.md)。不自动导入其他应用的会话、配置或环境，也不修改其数据。MCP 连接与 CLI 环境按原生方式显式配置；用户资料、历史证据和备份原样保留。
 
 ## 信任与风险
 

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)。单轮通过不证明一般协作质量或外部操作恰好一次。

package/docs/file-storage.md

@@ -7,10 +7,12 @@
 | 工作区 AGENTS.md、areas/、projects/、knowledge/ 等 | 用户资料、任务定义与证据 |
 | 工作区 providers/<id>/GUIDE.md | 提供方使用说明 |
 | 工作区 .pi/settings.json、.pi/mcp.json | Pi 原生项目配置 |
-| 当前 Pi agent dir 的 pbot/subagents/ | Personal Bot 子会话记录 |
+| Pi 原生 sessions/ 或原生配置指定的目录 | 主会话与子会话的 JSONL 对话，由 Pi 管理 |
+| 当前 Pi agent dir 的 pbot/subagents/ | Personal Bot 子进程控制记录与原生会话引用 |
+| 当前 Pi agent dir 的 pbot/teams/ | 团队资料、批次与公共原文 |
 | 用户级 pbot/python/.venv | 共享 Python 环境 |
 
-Pi 管理主会话与配置。Personal Bot 的工作区资料是普通文件，没有私有启用状态或工作区格式版本。详细目录用途见[项目 README](../README.md#工作区资料)，Python 路径见 [Python 说明](../python/README.md)。
+Pi 管理主会话、子会话对话与配置。Personal Bot 的工作区资料是普通文件，没有私有启用状态或工作区格式版本。详细目录用途见[项目 README](../README.md#工作区资料)，Python 路径见 [Python 说明](../python/README.md)。
 
 ## 资料准备
 
@@ -27,14 +29,33 @@ Pi 管理主会话与配置。Personal Bot 的工作区资料是普通文件，
 | inbox | 父侧消息 |
 | status | 子侧活动与接收标记 |
 | completions | 周期结果引用 |
-| session.jsonl | Pi 原生对话 |
+| session-ref.json | 原生会话文件的绝对路径；首次输入前为 null，不保存对话副本 |
+| team-ready.json | 子入口当前 generation 的团队接入/工具就绪标记，不是存储版本 |
 
-父侧写控制记录，子侧写状态和完成事件，交付收据进入父 Pi 会话。通信顺序与恢复规则见[专家协作](agent-collaboration.md)。
+父侧写控制记录，子侧写状态、会话引用和完成事件，交付收据进入父 Pi 会话。通信顺序与恢复规则见[专家协作](agent-collaboration.md)。
+
+新 agent 以 agentId 作为原生 session ID，通过 `--session-id` 由 Pi 创建。默认文件位于当前 Pi agent dir 的 `sessions/<Pi 编码的 cwd>/<时间戳>_<sessionId>.jsonl`；遵循子进程的原生环境变量与 settings，不自行编码目录或生成文件名。父会话一次性的 `--session-dir` 参数不会自动传给子进程。
+
+Pi 对没有用户或助手消息的会话延迟落盘。`session-ref.json` 初始为 `{ "file": null }`；子入口在领取请求或接受人工输入前固定 Pi 返回的实际路径，已存在的原生文件在载入时固定引用。固定后不清空、不改指向；它是恢复定位信息，不是输入已落盘、模型已读或执行完成的证明。
+
+恢复已绑定会话使用 `--session <绝对路径>`，不根据最近会话或当前目录设置重新选择。文件缺失、非法记录、身份或 cwd 不匹配时拒绝恢复；引用已固定但输入尚未落盘的崩溃窗口也不创建空白替代。只有从未交付输入的待命会话可以重新由 Pi 创建。报告使用 Pi 原生解析器和内存树按固定叶节点只读提取，不写入或迁移 JSONL。
 
 atomic-json 校验完整对象，写入并同步临时文件后原子发布；拒绝目录别名、越界和特殊文件，createOnly 保证不覆盖已有目标。短控制操作使用目录锁。处理崩溃遗留锁前须停止相关 Pi 进程。
 
+## 团队保存
+
+每个 teamId 对应 teams/<teamId>/team.json。单文件保存固定成员、批次、请求关联和公共消息；不使用事件日志、快照或迁移计数。每批次保存成员的原有 generation，用于拒绝旧代次请求。
+
+TeamFiles 与 AgentFiles 共用 subagents/.control 短目录锁。读改写在锁内重新读取；不在锁内等待模型、认证或进程退出。post 顺序追加消息，operationId 按入口身份与工具调用 ID 去重；完成答复按 requestId 去重。请求关联先于原 inbox 文件发布，两次保存不冒充跨文件事务。
+
+I/O 失败后当前文件实例停止后续写入，不能因下一次读取成功就重发。恢复时暂停团队；已领取但结果不明的请求保留未知事实，不重跑。仅有领取标记或未完成周期的子 reload 记录为 interrupted，不伪造成功。旧进程确认停止后，resume 在更换 generation 前也封存这些未知请求，避免新状态把它们误当作未领取。已完成但尚未公开的报告可补交付。
+
+关闭团队不删除消息或 agent。既有 descriptor、launch、inbox、status、completions 字段不变；新增引用文件不包含存储版本计数。团队与独立通知分别记录在父 Pi 原生分支；查看公共记录不是模型已读收据。
+
 ## 历史与复制
 
+0.2.0 使用新的子会话兼容线。0.1.x 的控制记录、团队记录和独立目录中的 session.jsonl 原地保留，不导入、不迁移、不自动恢复；当前列表与后台扫描不接管旧兼容线。更新前先用旧版停止活动成员，更新后重新 start。
+
 加载、资料准备和重载保留已有资料、历史记录及备份。扩展只管理自己的子会话与 Python 环境，不自动导入或转换其他应用数据。
 
 复制工作区前停止旧实例。复制资料不会转移用户级会话、运行进程、环境或认证；不支持多机同时写入同步目录。原子文件发布不保证外部操作恰好一次，相关验证范围见[验证](validation.md)。