@maxiaochao/pi-toolkit 0.11.20 → 0.11.21

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2026-10-15 - v0.11.21
+
+- simplify Agent Team to config-driven orchestration with persistent investigation records and optional extra review
+
 ## 2026-10-14 - v0.11.20
 
 - herdr-subagents v0.5.3: allow optional Pi-native tool exposure while inheriting Pi defaults when unset
@@ -40,6 +44,8 @@
 
 ## Unreleased
 
+- Agent Team: make the main agent responsible for config-driven dispatch, result collection, and investigation records; use configured role charters as the single source of truth and make role rotation, extra replication, and open attack rounds optional.
+- Keep release-routing test fixtures independent of changes since the latest root release tag.
 - OpenAI Account Pool: restore `●本会话` after successful requests and failover across fresh command contexts; status and preference commands no longer reinstall the session provider.
 - Scope child and root release checks to their owned code, and run Herdr tests or the real Agent smoke only when Herdr is the target or changed since the previous root release.
 - OpenAI Account Pool: keep deterministic account priority and show it as `★首选`, separately from the session-local `●本会话` account; automatic mode uses account order rather than random selection.

package/README.md

@@ -76,7 +76,7 @@ bash scripts/install.sh
 | `html-artifact` | Build self-contained HTML explainers and diagrams |
 | `pdlog` | Decompress and inspect Pudu `.pdlog` files |
 | `herdr` | Control Herdr workspaces, tabs, panes, and agents |
-| `agent-team` | Run tool-agnostic, cross-vendor adversarial review with independent concurrent agents |
+| `agent-team` | Let the main agent dispatch concurrent analysis using configured models and roles, collect results, and maintain investigation records; run extra review rounds as needed |
 | `tapd` | Investigate and operate on TAPD items with workspace, evidence, and safe-download guardrails |
 
 Package-specific skills, such as `pi-worktree`, are documented by their child package.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.11.20",
+  "version": "0.11.21",
   "description": "Personal pi coding agent toolkit: scheduler, /btw, /cache_export, apply_patch, browser automation, and bundled theme/skills.",
   "type": "module",
   "workspaces": [

package/packages/herdr-subagents/README.md

@@ -12,6 +12,18 @@ https://github.com/user-attachments/assets/8ddf3ae6-a11a-492b-9cae-d9496ba65b67
 
 The reproducible source recording is retained as [`docs/demo.webm`](docs/demo.webm).
 
+## Requirements and install
+
+Run Pi inside a Herdr workspace, then install the standalone package:
+
+```bash
+pi install npm:@maxiaochao/pi-herdr-subagents
+```
+
+Update it with `pi update npm:@maxiaochao/pi-herdr-subagents`. The full `@maxiaochao/pi-toolkit` package already bundles this extension, so install the toolkit or this standalone package, not both.
+
+The tools and command are registered only when Pi is running inside Herdr with a workspace ID. If they are unavailable after entering Herdr, use `/reload` or restart Pi there.
+
 ## Execution contract
 
 `herdr_subagents` accepts an ordered, non-empty `tasks` array.
@@ -85,16 +97,228 @@ Records are stored under:
 
 The orchestrator is the only writer of `run.json`, `task.json`, and promoted `report.json`. The child only writes its attempt-scoped result and report.
 
-## Control and UI
+## Tools and UI
+
+### `herdr_subagents`
+
+Starts one ordered batch and waits until every task reaches a terminal state. Its parameters are:
+
+| Field | Required | Default | Purpose |
+| --- | --- | --- | --- |
+| `tasks` | Yes | — | Non-empty ordered task array. |
+| `label` | No | `"batch"` | Short Herdr run-tab label, at most 48 characters. |
+| `concurrency` | No | `defaultConcurrency` | Maximum number of simultaneously active read-only tasks. It is capped by `maxConcurrency`. |
+| `tasks[].name` | Yes | — | Short pane/task name, at most 48 characters. |
+| `tasks[].prompt` | Yes | — | Self-contained task instructions. |
+| `tasks[].agent` | No | `"worker"` | Effective Persona name. |
+| `tasks[].model` | No | Persona/default model | Model override for this task. |
+
+A batch containing a write-capable Persona must explicitly or effectively use `concurrency: 1`; an unsafe parallel request is rejected.
+
+### `herdr_subagents_control`
+
+| Action | `runId` | Purpose |
+| --- | --- | --- |
+| `list` | Not accepted | List effective Personas, resolved options, and diagnostics. |
+| `status` | Required | Show one run and its task states. |
+| `history` | Not accepted | List durable project-local run history. |
+| `cancel` | Required | Cancel an active run. |
+| `cleanup` | Required | Remove one archived run. |
+
+Settled tasks are immutable. Follow-up work starts a new task or run; there is no resume/respond lifecycle.
+
+### Slash command
+
+`/herdr-subagents` supports:
+
+| Command | Purpose |
+| --- | --- |
+| `active` | Show the current run. This is also the default with no argument. |
+| `history` | Show project-local history. |
+| `focus <task-number>` | Focus a running task pane. |
+| `agents` | Show effective Persona source, access, model, thinking, tools, skills, and extensions. |
+| `models` | List authenticated Pi models. |
+| `settings` | Show effective settings, their sources, and configuration diagnostics. |
+
+## Configuration and Personas
+
+Settings and Persona definitions are separate:
+
+| Scope | Settings file | Persona directory |
+| --- | --- | --- |
+| Project | `<project>/.pi/herdr-subagents.json` | `<project>/.pi/herdr-subagents/agents/*.md` |
+| Global | `~/.pi/agent/herdr-subagents.json` | `~/.pi/agent/herdr-subagents/agents/*.md` |
+| Package | Built-in defaults | Installed package `agents/*.md` |
+
+For JSON settings, project fields override global fields, which override built-in defaults. `personas` entries merge by Persona name and then by field; array values replace lower-precedence arrays rather than appending to them.
+
+Persona Markdown uses whole-definition replacement instead of field merging. A same-name definition is selected in this order:
+
+1. project Persona
+2. global Persona
+3. package Persona
+
+### Complete settings reference
+
+These are all supported top-level fields in `herdr-subagents.json`:
+
+| Option | Accepted value | Built-in default | Purpose |
+| --- | --- | --- | --- |
+| `exposure` | `"model-only"` or `"direct"` | Unset (inherit Pi; currently `direct`) | Controls whether the two tools may be called only by the top-level model or also by nested tools such as Codemode. |
+| `defaultConcurrency` | Positive integer | `1` | Concurrency used when a call omits `concurrency`; capped to `maxConcurrency`. |
+| `maxConcurrency` | Positive integer | `4` | Hard ceiling for requested/default read-only concurrency. It does not make write-capable batches safe. |
+| `stalledWarningSeconds` | Positive integer | `300` | Emit a warning after a child runs this long. This is not a timeout and does not stop it. |
+| `defaultModel` | Non-empty Pi model ID, normally `provider/model` | Unset | Fallback child model. If unset, the parent model is inherited. |
+| `defaultThinking` | Non-empty Pi thinking value | Unset | Fallback thinking level below Persona-specific settings. Typical Pi values are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`; model support varies. |
+| `personas` | Object keyed by an existing Persona name | `{}` | Per-Persona overrides. It cannot create a Persona without a matching Markdown definition. |
+
+Each `personas.<name>` object supports:
+
+| Option | Accepted value | Purpose |
+| --- | --- | --- |
+| `model` | Non-empty Pi model ID | Override the model from Persona Markdown and `defaultModel`. |
+| `thinking` | Non-empty Pi thinking value | Override Persona Markdown and `defaultThinking`. |
+| `skills` | Array of non-empty strings | Replace the lower-precedence explicit skill list. Use `[]` to clear it. |
+| `extensions` | Array of non-empty Pi source strings | Replace the lower-precedence extension-source list. Use `[]` to clear it. |
+
+JSON overrides cannot change a Persona's `name`, `description`, `access`, `tools`, or system prompt; those belong in its Markdown definition.
+
+Invalid known values are ignored and reported by `/herdr-subagents settings` or the control tool's `list` action. If `defaultConcurrency` exceeds `maxConcurrency`, the effective default is reduced to the maximum. Model IDs, thinking compatibility, skills, and extension sources are ultimately resolved by child Pi.
+
+### Exposure
+
+Use the restrictive mode when only direct model calls should be allowed:
+
+```json
+{
+  "exposure": "model-only"
+}
+```
+
+- `model-only`: the top-level model may call the tools, but Codemode scripts and other tools cannot invoke them as nested tools.
+- `direct`: allow both top-level and nested calls explicitly.
+- omitted: do not set an exposure during registration; inherit Pi's default behavior.
+
+`exposure` is read once when the extension registers. After changing it, use `/reload` or restart Pi. Other settings and Persona files are re-read at the start of each new tool call; they do not modify an already running task.
+
+### Complete global example
+
+Save this as `~/.pi/agent/herdr-subagents.json`. Model IDs, skills, and extension sources are illustrative and must exist in your Pi environment.
+
+```json
+{
+  "exposure": "model-only",
+  "defaultConcurrency": 2,
+  "maxConcurrency": 4,
+  "stalledWarningSeconds": 300,
+  "defaultModel": "anthropic/claude-sonnet-4-5",
+  "defaultThinking": "medium",
+  "personas": {
+    "explorer": {
+      "model": "anthropic/claude-haiku-4-5",
+      "thinking": "low",
+      "skills": ["code-search"],
+      "extensions": ["~/.pi/agent/extensions/provider-routing.ts"]
+    },
+    "reviewer": {
+      "thinking": "high",
+      "skills": ["code-review"],
+      "extensions": []
+    }
+  }
+}
+```
+
+A project can override only what differs in `.pi/herdr-subagents.json`:
+
+```json
+{
+  "defaultConcurrency": 3,
+  "stalledWarningSeconds": 600,
+  "personas": {
+    "explorer": {
+      "model": "openai/gpt-5.2",
+      "skills": []
+    },
+    "reviewer": {
+      "extensions": ["npm:@example/pi-review-tools@1.0.0"]
+    }
+  }
+}
+```
+
+Here the project keeps global `maxConcurrency`, `defaultModel`, and `defaultThinking`; replaces the explorer model and skill list; and replaces the reviewer extension list. It does not append arrays.
+
+### Built-in Personas
+
+None of the bundled Personas pins a model, thinking level, skill, or optional extension. Those values come from configuration or parent-session inheritance.
+
+| Persona | Access | Built-in tools | Intended use |
+| --- | --- | --- | --- |
+| `worker` | `write` | `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`, `codemode` | One focused implementation or other file-changing task. |
+| `explorer` | `read` | `read`, `bash`, `grep`, `find`, `ls`, `codemode` | Fast codebase investigation without file changes. |
+| `analyst` | `read` | `read`, `bash`, `grep`, `find`, `ls`, `codemode` | Neutral analysis where the task prompt supplies the role and evaluation method. |
+| `reviewer` | `read` | `read`, `bash`, `grep`, `find`, `ls`, `codemode` | Correctness and maintainability review with actionable evidence. |
+
+`access` is a scheduling declaration: any `write` Persona requires serial execution. It is not by itself a sandbox. For a custom read-only Persona, also omit write-capable tools and load only trusted extensions.
+
+### Custom Persona example
+
+Save the following as `.pi/herdr-subagents/agents/security-reviewer.md` (or in the global Persona directory):
+
+```md
+---
+name: security-reviewer
+description: Read-only reviewer for security risks
+access: read
+model: anthropic/claude-sonnet-4-5
+thinking: high
+tools: read, bash, grep, find, ls, codemode
+skills: security-review, code-review
+extensions: ~/.pi/agent/extensions/provider-routing.ts
+---
+
+Review the assigned scope without modifying files. Separate confirmed vulnerabilities from hypotheses and cite concrete evidence.
+```
+
+The Markdown body is the child system prompt. Frontmatter is intentionally a small single-line format, not full YAML:
+
+| Field | Accepted value | Required/default | Purpose |
+| --- | --- | --- | --- |
+| `name` | Non-empty string | Required | Identifier used by `tasks[].agent`; unique within one directory. |
+| `description` | Non-empty string | Required | Description shown by Persona listings. |
+| `access` | `read` or `write` | `write` | Scheduling safety declaration. |
+| `model` | Non-empty Pi model ID | Unset | Persona model default. |
+| `thinking` | Non-empty Pi thinking value | Unset | Persona thinking default. |
+| `tools` | Non-empty comma-separated list, optionally `[bracketed]` | Pi child defaults | Built-in-tool allowlist. Supported names: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`, `powershell`, `codemode`. `subagent_report` is always added. |
+| `skills` | Comma-separated list, optionally `[bracketed]` | None | Explicit child skills; normal automatic skill discovery is disabled. |
+| `extensions` | One source or a comma-separated list; `[]` clears | None | Additional Pi extension/package sources loaded into the child. |
+
+Relative extension paths resolve from the project root. `~` resolves to the home directory. Pi-native local, `npm:`, `git:`, and `builtin:` sources are accepted. Children always load the required report extension and Codemode; configured sources are additional. Pi packages may provide resources beyond extensions, so load only trusted code and pin versions/refs when reproducibility matters.
+
+### Effective option precedence
+
+The child model is selected in this order:
+
+1. `tasks[].model`
+2. project `personas.<name>.model`
+3. global `personas.<name>.model`
+4. effective Persona Markdown `model`
+5. effective `defaultModel` (project, then global)
+6. parent Pi model
 
-`herdr_subagents_control` supports `list`, `status`, `history`, `cancel`, and `cleanup`. Follow-up work is a new task or run; settled tasks are never revived.
+Thinking is selected in this order:
 
-When `exposure` is absent, both tools omit the registration field and inherit Pi's default exposure. Set `"exposure": "model-only"` to keep explicit top-level model calls while excluding Codemode scripts and other nested tools, or `"exposure": "direct"` to request Pi's direct-and-nested behavior explicitly. Exposure is read when the extension loads, so use `/reload` or restart Pi after changing it.
+1. project `personas.<name>.thinking`
+2. global `personas.<name>.thinking`
+3. effective Persona Markdown `thinking`
+4. effective `defaultThinking` (project, then global)
+5. parent thinking when the child also inherits the parent model
 
-Use `/herdr-subagents focus <task-number>` to focus a running pane. `/herdr-subagents active`, `history`, `agents`, `models`, and `settings` provide compact inspection.
+There is no task-level thinking override. `skills` and `extensions` use project Persona JSON, then global Persona JSON, then effective Persona Markdown. Each winning list replaces the whole lower-precedence list.
 
-## Personas and settings
+Use `/herdr-subagents agents`, `/herdr-subagents models`, and `/herdr-subagents settings` to inspect the result before starting work.
 
-Bundled personas are `worker`, `explorer`, `analyst`, and `reviewer`. Project personas can be added under `.pi/agents/` using the same frontmatter format as the bundled files. Access is declared as `read` or `write` and drives concurrency safety.
+## Development and tests
 
-Settings are read from `~/.pi/agent/herdr-subagents.json` and the project-level `.pi/herdr-subagents.json`, with the project value taking precedence. Optional `exposure` accepts Pi's `model-only` or `direct`; omitting it delegates to Pi. `defaultConcurrency`, `maxConcurrency`, and `stalledWarningSeconds` remain supported.
+See [TESTING.md](TESTING.md) for deterministic tests, extension loading, packaging, and real Herdr smoke requirements.

package/skills/agent-team/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: agent-team
-description: 以对抗评审的方式让不同厂商的模型交叉验证同一个结论，当前会话担任管理者。Use when the user asks for 对抗评审 / 交叉验证, or when a costly decision or long evidence chain warrants independent red-teaming.
+description: 多模型协作分析：主 Agent 按配置的模型和角色调度独立子代理，汇总结果并维护调查档案。用于用户要求多模型分析或对抗评审，或高代价决策需要独立复核时。
 ---
 
-当前会话是**管理者**，不是转述人：自己也承担一份实证工作，并对每一轮的裁决负责。每轮并发启动三个相互独立的子代理，统一收集结果后由管理者裁决。子代理不需要常驻；跨轮连续性来自持久调查档案和逻辑成员身份，而不是聊天记忆。
+当前会话是**主 Agent**，负责核心调度：按配置中的模型和角色启动独立子代理，分派用户问题，收集结果并维护调查档案。主 Agent 根据结果决定直接回答、补充核验或继续下一轮。子代理不需要常驻；跨轮连续性来自持久调查档案和逻辑成员身份，而不是聊天记忆。
 
 ## 何时值得开
 
-用户明确要求组队时开启；模型也可在结论会驱动高代价动作（改内核、下线设备、向客户定责），或证据链已经长到单模型容易自我确认时主动开启。查一个事实、读一份文件用不上。
+用户明确要求多模型分析或对抗评审时开启；主 Agent 也可在结论会驱动高代价动作（改内核、下线设备、向客户定责）时主动开启。查一个事实、读一份文件用不上。
 
 ## 1. 建立调查档案
 
@@ -19,46 +19,42 @@ description: 以对抗评审的方式让不同厂商的模型交叉验证同一
 ├── FINDINGS-stageN.md    # 当前唯一事实源；新阶段整体取代旧阶段
 ├── LEDGER.md             # 只增不改的 N/X 记录
 └── rounds/
-    └── N.md              # 本轮角色映射和可证伪攻击点
+    └── N.md              # 本轮成员、模型、角色和分派问题
 ```
 
-`BRIEF.md` 只记录稳定背景。`FINDINGS-stageN.md` 必含机制链、编号发现、已推翻清单和未闭合点。`LEDGER.md` 中发现按 `N1, N2…` 追加，被推翻的结论按 `X1, X2…` 追加并写明推翻者。只有管理者能更新这三个权威文件；子代理只提交候选证据。
+`BRIEF.md` 只记录稳定背景。`FINDINGS-stageN.md` 记录当前问题、编号发现及证据、已推翻结论和待处理项。`LEDGER.md` 中发现按 `N1, N2…` 追加，被推翻的结论按 `X1, X2…` 追加并写明推翻者。只有主 Agent 能更新这三个权威文件；子代理只提交结果和候选证据。
 
 ## 2. 配置成员与角色
 
-名单在同目录的 `models.json`。三个逻辑成员必须来自不同模型厂商，并显式使用各自的 `model`；不能依赖父会话或环境默认模型。启动后核对并在本轮记录中写下每个任务实际生效的模型；无法确认、与名单不符或三个成员落到同一厂商时，本轮无效。
+读取本 skill 同目录的 [models.json](models.json)：`members` 是成员与模型的唯一配置来源，`roles` 是角色职责的唯一配置来源。默认将两个数组按顺序一一对应；配置为空或数量不匹配时，报告配置问题后再启动。
 
-三个成员使用相同的中性只读执行约束，方法角色由每轮任务动态赋予：
+按配置成员数并发启动子代理，显式传入各自的 `model`，并将对应角色的 `charter` 放入任务。成员使用相同的中性只读执行约束。启动后核对并在本轮记录中写下每个任务实际生效的模型；无法确认或与配置不符时，该成员结果无效并报告原因。
 
-- `auditor`：审源码、规范和提交，只接受可定位的直接证据。
-- `replicator`：绕开管理者的脚本和口径，从原始数据独立复算。
-- `adversary`：攻击前提和方法学，查样本敏感性、一对多计数和阴性对照。
-
-模型与角色不得永久绑定。首轮可以按 `models.json` 顺序分配三个角色；后续根据争议轮换或交叉复核，使模型差异和角色差异能够被区分。每轮在 `rounds/N.md` 写明成员、模型、角色、输入文件和攻击点。
+每轮在 `rounds/N.md` 写明成员、模型、角色、输入文件和分派问题。默认沿用角色映射；需要交叉复核时可轮换，并记录新的映射。
 
 ## 3. 交底与通信
 
-拓扑是星型，管理者是唯一消息路由。成员在同一轮中独立作答，在提交前不得看到其他成员本轮答案。需要逻辑成员 A 反驳逻辑成员 B 的上一轮结论时，由管理者在新任务中引用 B 的原话和证据位置；不能假定新实例记得上一轮聊天。
+拓扑是星型，主 Agent 是唯一消息路由。成员在同一轮中独立作答，在提交前不得看到其他成员本轮答案。需要逻辑成员 A 复核逻辑成员 B 的上一轮结论时，由主 Agent 在新任务中引用 B 的原话和证据位置；不能假定新实例记得上一轮聊天。
 
-下行只给短任务和文件指针：每个成员阅读 `BRIEF.md`、最新 `FINDINGS-stageN.md`、`LEDGER.md` 和本轮文件。不得要求它重新梳理已经确认的全部背景。上行结果必须能归属到轮次和成员，并包含证据位置；长结果写入持久文件，不能依赖截断的终端文本。
+下行给用户问题、角色职责、具体任务和文件指针：每个成员阅读 `BRIEF.md`、最新 `FINDINGS-stageN.md`、`LEDGER.md` 和本轮文件，使用档案恢复背景。上行结果必须能归属到轮次和成员，并包含结论、证据位置和未解决问题；长结果写入持久文件，不能依赖截断的终端文本。
 
 ## 4. 回合
 
-一轮 = 记录受保护文件和工作树初始状态 → 写本轮任务 → 三个成员并发独立调查 → 管理者收齐结果 → 检查子代理未修改项目或权威文件 → 核验证据并裁决 → 更新 FINDINGS 和 LEDGER → 决定下一轮。
+一轮 = 记录受保护文件和工作树初始状态 → 写本轮任务 → 配置成员并发独立分析 → 主 Agent 收齐结果或失败报告 → 检查子代理未修改项目或权威文件 → 汇总并核验关键证据 → 更新 FINDINGS 和 LEDGER → 决定收尾或继续。
 
-每个成员必须收到具体到能证伪的攻击点，例如“查 `adbconnection.cc`，确认该错误日志与被销毁的 fd 是否 1:1”，而不是“看看有没有问题”。子代理结束后即可释放；下一轮通过调查档案恢复事实状态，并重新创建独立任务。
+每个成员收到范围明确、可检查结果的任务。例如“查 `adbconnection.cc`，确认该错误日志与被销毁的 fd 是否 1:1”。只有存在需要补证、复核或继续处理的问题时才开下一轮，并写明目标；子代理结束后即可释放。
 
 ## 5. 纪律
 
 - **独立性**：同轮答案不得互相可见；成员之间不直接通信。
 - **只读完整性**：只读是协议约束，不假定执行环境构成沙箱。每轮结束后比较初始状态；发现子代理修改项目或权威文件时，该成员结果无效并显式报告污染范围。
-- **retraction**：管理者被驳倒时，在下一轮开头明确写“我错了，更正为……”，并追加对应 X。
-- **replication**：任何承载结论的数字至少由两个不同模型独立计算；对不上先查口径再查代码。
-- **control**：任何“异常”指标必须配阴性样本才进入 FINDINGS。
-- **grading**：每条结论标注 `源码读取 / 实测 / 推断` 和置信度；推断不能与实测并列陈述。
-- **裁决**：成员冲突时管理者必须判定谁对并说明证据，不能多数投票或折中平均。
+- **更正**：结论被推翻时，明确记录更正及依据，并追加对应 X。
+- **证据**：区分直接证据、实测、推断和未知；结论附证据位置。
+- **分歧**：根据证据说明支持、推翻或未决；未决项写明缺失证据，不以多数投票或折中平均替代核验。
 - **缺席视角**：成员失败或额度耗尽时，明确记录缺失的模型和方法角色，不能把不完整轮次当成完整评审。
 
-## 6. 收尾
+## 6. 按需核验与收尾
+
+主 Agent 根据问题需要选择角色轮换、跨模型独立复算、阴性对照或开放攻击。开放攻击时，由各成员自行选择其认为最强的反证方向。这些是补充核验手段，不是每次分析的必经步骤；任务仍须遵循所分配角色的 `charter`。
 
-收尾前必须进行一轮**开放攻击**：三个方法角色各自选择其认为最强的攻击点，不能只回答管理者预设的窄问题。只有完整开放攻击轮没有产生任何被管理者接受并记入 X 的新反证时才算收敛。最终文档单列未闭合点、缺失视角，以及每一个需要人或设备批准才能执行的动作。
+当用户问题已有足够证据支持的回答，或剩余问题受缺失输入、工具或权限阻塞时，可以收尾。最终回答汇总结论及依据，单列未解决问题、失败或缺席成员，以及需要人或设备批准的动作；受阻停止时明确说明限制，不宣称已经收敛。