@maxiaochao/pi-toolkit 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2026-09-24 - v0.8.0
+
+- add the agent-team skill: cross-vendor adversarial review in herdr panes, with the model roster in skills/agent-team/models.json
+
+## 2026-09-24 - v0.7.2
+
+- bundle the calldiff skill (copied verbatim from tanishqkancharla/calldiff, MIT, pinned to a main commit since upstream has no release tags) for call-stack diffs across git commits; the previous v0.7.1 tarball was briefly unavailable on the registry right after publish and is now served normally
+
 ## 2026-09-24 - v0.7.1
 
 - bundle the herdr skill (copied verbatim from herdrdev/herdr v0.9.1, Apache-2.0) for driving the Herdr terminal multiplexer from inside a pane; move the tapd CLI skill from .claude/skills into skills/ so it ships with the package

package/README.md

@@ -89,6 +89,8 @@ The bundled `herdr` skill (copied verbatim from [herdrdev/herdr](https://github.
 
 The bundled `tapd` skill documents the third-party `tapd` CLI ([studyzy/tapd-ai-cli](https://github.com/studyzy/tapd-ai-cli)) for TAPD: requirements, defects, tasks, iterations, wikis, comments, attachments, timesheets, and workflow status maps, including the `--filter` advanced query syntax. It is the CLI's own command reference, so refresh the file with `tapd skill init` when the CLI changes.
 
+The bundled `calldiff` skill (copied verbatim from [tanishqkancharla/calldiff](https://github.com/tanishqkancharla/calldiff), MIT, pinned to a `main` commit because upstream has no release tags) teaches call-stack diffs across git commits: `diff` shows which callees appeared, disappeared, or moved under an entrypoint, `tree` prints one call tree, and `reach` finds call paths between two symbols, all with `--entry`/`--file` entrypoint selection, `--locs` source locations, and `--format json` for agents.
+
 ## Tiny Subagent
 
 The tiny subagent is a separate npm package. Install it independently when you want the `tiny_subagents` tool:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Personal pi coding agent toolkit: /todos, /btw, /cache_export extensions, browser automation, and bundled theme/skills.",
   "type": "module",
   "keywords": [

package/skills/agent-team/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: agent-team
+description: 以对抗评审的方式让不同厂商的模型交叉验证同一个结论，当前会话担任管理者。Use when the user asks for 对抗评审 / 交叉验证, or wants a long-running investigation red-teamed by independent agents.
+disable-model-invocation: true
+---
+
+当前会话是**管理者**，不是转述人：自己也承担一份实证工作，并对每一轮的裁决负责。队员是长驻的 herdr pane，不是一次性 subagent —— 它们要能被反复追问、被点名互相反驳。
+
+herdr 的完整 CLI 语义在 `herdr --skill`，本文只写这套协作协议。
+
+## 何时值得开
+
+只在用户要求组队时开，它会在用户的终端里真的分屏。值得开的条件：结论会驱动一个代价高的动作（改内核、下线设备、向客户定责），或者证据链已经长到单模型会自我确认。查一个事实、读一份文件用不上。
+
+## 1. 建队
+
+**必须跨厂商。** 同厂同代模型共享盲区，三个一起点头等于一个点头。
+
+名单在同目录的 `models.json`，先读它，照里面的 `model` 字段写命令；用户指定了别的模型就用用户的。每个成员有 `name` / `model` / `role` / `charter`，`defaults` 里是共用的 `kind` 与 `thinking`。
+
+```bash
+herdr pane split --current --direction right --cwd "$PWD" --no-focus
+herdr agent start <name> --kind pi --pane <pane> -- --model <model> --thinking <thinking>
+echo <pane> > /tmp/pane_<name>
+```
+
+pane id 落盘，后面所有广播脚本都从这里取。开完把该成员的 `charter` 作为第一条 prompt 发过去，立常设职责。`herdr agent list` 确认都是 idle 再开工。
+
+## 2. 分角色：互不重叠的攻击面
+
+每个 pane 领一个**方法论上互斥**的职责：`auditor` 审源码、`replicator` 复算数据、`adversary` 攻方法学。具体措辞是 `models.json` 里各自的 `charter`，改职责改那里。
+
+## 3. 交底与通信
+
+herdr 没有邮箱，只有 `agent prompt`（往别人输入框塞文字）和 `agent read`（把别人屏幕刮下来）。拓扑是星型，管理者是唯一的路由：跨 pane 的话全部由管理者转述，把 A 的原话引进 B 的下一条 prompt（「opus 说你这个计数可能一对多，用数据回应」）。
+
+```
+                  管理者（本会话）
+              唯一写 FINDINGS 的人
+                │      │      │
+   下行：消息  │      │      │   herdr agent prompt
+   （短指针）  ▼      ▼      ▼
+              ┌────┐ ┌──────┐ ┌──────┐
+              │ sol│ │ grok │ │ opus │   彼此不相连
+              └──┬──┘ └──┬───┘ └──┬───┘
+                 │        │        │
+   上行：文件     └───────┴───────┘
+                          ▼
+              /tmp/<轮次>-<name>.md ← 管理者从磁盘读
+```
+
+技术上任何 pane 都能 prompt 任何 pane，让它们直连有四个代价：管理者看不见这次交换，ledger 就缺一环；对正在 working 的 agent 发 prompt 会被拒（`agent_blocked`）或插进它当前那一轮；没有投递回执；而且两两串供会让它们彼此收敛，恰好毁掉跨厂商独立性这唯一的价值来源。
+
+下行只发短指针，正文留在文件里：长文本经终端会被折断或触发意外快捷键。上行走文件：队员把结论写 `/tmp/<轮次>-<name>.md`，终端只回一行路径，管理者从磁盘读。`agent read` 是终端截图，会截断、会按宽度折行、会混进 TUI 边框，拿它收长输出必丢内容；只用它确认回执和状态。
+
+基准文档 `FINDINGS-stageN.md` 是**唯一事实源**，只有管理者写，新版本整体取代旧版本而不是打补丁。必含四块：机制链、编号发现、已推翻清单、未闭合点。
+
+```bash
+MSG='【N17】读 /tmp/FINDINGS-stage4.md 全文。本轮你的攻击点：……。结论写 /tmp/N17-<你的名字>.md，终端只回一行路径。'
+for a in sol grok opus; do herdr agent prompt "$a" "$MSG"; done
+for a in sol grok opus; do herdr agent wait "$a" --until idle --timeout 900000; done
+```
+
+## 4. 回合
+
+一轮 = 广播 → 各自独立干 → 管理者从磁盘收文件 → 裁决 → 更新文档 → 再广播。
+
+每轮广播里给每个 pane 一个**具体到能证伪的攻击点**（「查 ART 的 adbconnection.cc，确认这条错误日志与被销毁的 fd 是不是 1:1」），而不是「你看看有没有问题」。
+
+## 5. 纪律
+
+- **ledger**：发现按 `N1, N2…` 只增不改；每一条被推翻的结论进 `X1, X2…` 清单，写明是谁推翻的。这份 X 清单是最终交付里最有价值的部分。
+- **retraction 要公开**：管理者被驳倒时，在下一次广播开头显式写「我错了，更正为……」。管理者一旦开始维护自己的结论，pane 就会停止攻击，整个队伍塌成回音室。
+- **replication**：任何承载结论的数字至少两方独立算。对不上先查口径再查代码。
+- **control**：任何「异常」指标必须配阴性样本才进文档。拿不出对照的指标只是一个数。
+- **grading**：每条结论标注 `源码读取 / 实测 / 推断` 和置信度。推断不能和实测并列陈述。
+- **裁决**：两个 pane 冲突时判出谁对，并说明依据。把冲突的结论平均掉会同时丢掉两边的信息。
+
+## 6. 收尾
+
+收敛判据：完整一轮广播后没有任何 pane 能产出新的 X。
+
+最终文档必须单列**未闭合点**，以及**每一个需要人或设备批准才能执行的动作**。
+
+用完 `herdr pane close <pane_id>` 关掉，pane 不会自己退出。
+
+## 故障
+
+- pane 额度耗尽：降级为剩余 pane 继续，并在文档里记下缺失的是哪个视角。
+- agent 卡在 blocked：`herdr agent read <name> --source visible` 看它在等什么，多半是在等一个确认。
+- 广播后无人响应：`herdr agent list` 核对 pane 是否还活着，pane id 会随布局变化。

package/skills/agent-team/models.json

@@ -0,0 +1,26 @@
+{
+  "defaults": {
+    "kind": "pi",
+    "thinking": "high"
+  },
+  "members": [
+    {
+      "name": "sol",
+      "model": "pudu/gpt-5.6-sol",
+      "role": "auditor",
+      "charter": "只接受能逐行引用的源码、规范、commit，输出必须带 文件:行号。负责把「机制上可能」变成「代码里确实如此」；查不到就说查不到，不要用常识补。"
+    },
+    {
+      "name": "grok",
+      "model": "pudu/grok-4.6",
+      "role": "replicator",
+      "charter": "拿原始数据和口径，不看管理者的脚本，独立重算同一个指标，只报自己的数和差异。数对不上就是一次发现，先查口径再查代码。"
+    },
+    {
+      "name": "opus",
+      "model": "pudu/claude-opus-5",
+      "role": "adversary",
+      "charter": "攻前提和方法学，不攻结论。指出指标对样本组成的敏感性、计数的一对多、缺失的阴性对照。附议没有价值，找不到问题就说明理由。"
+    }
+  ]
+}

package/skills/calldiff/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tanishq Kancharla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/calldiff/NOTICE

@@ -0,0 +1,19 @@
+calldiff Skill
+
+This directory is copied verbatim from the calldiff repository:
+https://github.com/tanishqkancharla/calldiff
+skills/calldiff/SKILL.md at commit 2086f6e4e9ed3c410bba7c94ca3dde77791b1956 (main)
+
+The upstream repository is licensed under the MIT License. A copy of that
+license is included in LICENSE.
+
+Upstream publishes no release tags, so this file is pinned to a main commit
+instead of a tag. The CLI can also write its own copy with `calldiff skills
+add` (to ~/.agents/skills/calldiff/SKILL.md), but that generated file is terser
+than the committed one — it leaves the --entry/--file descriptions empty and
+says 22 languages — so pi-toolkit ships the committed file.
+
+To refresh, copy skills/calldiff/SKILL.md and LICENSE from a newer upstream
+commit and update the commit above. The bundled commands were smoke-tested
+against calldiff 0.5.0 (`diff`, `tree`, `reach`, `--entry`, `--file`,
+`--maxDepth`/`--max-depth`, `--locs`, `--format json`).

package/skills/calldiff/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: calldiff
+description: Diff call stacks across git commits — like git diff, but for who-calls-whom. Shows which callees appeared, disappeared, or moved under an entrypoint across 23 languages (diff, tree, and reach). Use for agentic code review when call flow changed and line diffs bury the shape of the change.
+requires_bin: calldiff
+command: calldiff
+---
+
+# calldiff diff
+
+Diff call stacks between two git trees
+
+## Arguments
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `from` | `string` | no | Before ref (default: HEAD) |
+| `to` | `string` | no | After ref (default: working tree) |
+| `paths` | `array` | no | Limit to these path prefixes |
+
+## Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--entry` | `unknown` |  | Entrypoint symbol(s): functionName or ClassName.method |
+| `--file` | `unknown` |  | Entrypoint file(s): indexed source path; expands to that file's exports |
+| `--maxDepth` | `number` | `12` | Max call-tree depth |
+| `--locs` | `boolean` | `false` | Show call-site source locations (file:line) |
+| `--from` | `string` |  | Left / "before" tree |
+| `--to` | `string` |  | Right / "after" tree |
+
+## Examples
+
+```sh
+# HEAD vs working tree
+calldiff diff
+
+# One ref vs working tree
+calldiff diff main
+
+# Two commits / branches
+calldiff diff abc123 def456
+
+# Force entrypoints
+calldiff diff main feature --entry createAgentSession
+
+# File expands to that file's exports
+calldiff diff main feature --file src/routes.ts
+```
+
+> Semantics match git diff: no refs → HEAD vs worktree; one ref → that vs worktree; two refs → compare those trees.
+
+---
+
+# calldiff reach
+
+Find all call paths from an entrypoint to a target symbol
+
+## Arguments
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `ref` | `string` | no | Git ref (default: working tree) |
+| `paths` | `array` | no | Limit to these path prefixes |
+
+## Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--entry` | `unknown` |  | Entrypoint symbol(s): functionName or ClassName.method |
+| `--file` | `unknown` |  | Entrypoint file(s): indexed source path; expands to that file's exports |
+| `--to` | `string` |  | Target symbol to reach (functionName or ClassName.method) |
+| `--maxDepth` | `number` | `12` | Max call-tree depth |
+| `--locs` | `boolean` | `false` | Show call-site source locations (file:line) |
+
+## Examples
+
+```sh
+# Paths in the working tree
+calldiff reach --entry runCheckout --to sendEmail
+
+# Paths at a commit, limited to a directory
+calldiff reach HEAD examples/checkout --entry runCheckout --to sendEmail
+
+# Paths from every export in a file
+calldiff reach --file packages/api/src/flow.ts --to notify
+```
+
+---
+
+# calldiff tree
+
+View a call tree (no diff) for one or more entrypoints
+
+## Arguments
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `ref` | `string` | no | Git ref (default: working tree) |
+| `paths` | `array` | no | Limit to these path prefixes |
+
+## Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--entry` | `unknown` |  | Entrypoint symbol(s): functionName or ClassName.method |
+| `--file` | `unknown` |  | Entrypoint file(s): indexed source path; expands to that file's exports |
+| `--maxDepth` | `number` | `12` | Max call-tree depth |
+| `--locs` | `boolean` | `false` | Show call-site source locations (file:line) |
+
+## Examples
+
+```sh
+# Tree from working tree
+calldiff tree --entry createAgentSession
+
+# Tree from a commit
+calldiff tree HEAD --entry PiService.createAgentSession
+
+# Every export in a file
+calldiff tree --file packages/api/src/routes.ts
+```