pi-legion 0.16.0 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONTRIBUTING.md +58 -0
- package/README.md +313 -640
- package/agents/advisor.md +7 -5
- package/agents/centurion.md +53 -0
- package/agents/designer.md +33 -33
- package/agents/planner.md +1 -2
- package/agents/prototype.md +2 -2
- package/agents/reviewer.md +67 -31
- package/agents/scout.md +6 -2
- package/agents/worker.md +12 -3
- package/docs/contracts/esc-abort-v1.md +131 -0
- package/docs/contracts/esc-cascade-v2.md +100 -0
- package/docs/design.md +44 -25
- package/docs/legion-v2-contract.md +461 -0
- package/docs/legion-v2-delivery.md +62 -0
- package/docs/retire-hardening-contract.md +125 -0
- package/docs/subagents-teams.md +76 -0
- package/docs/tui-viewer-contract.md +276 -0
- package/docs/vexillatio-contract.md +162 -0
- package/index.ts +1462 -286
- package/package.json +12 -9
- package/skills/pi-legion/SKILL.md +74 -96
- package/src/agents/agents.ts +6 -11
- package/src/agents/overrides.ts +2 -1
- package/src/agents/paths.ts +1 -1
- package/src/agents/settings.ts +268 -20
- package/src/api.ts +47 -48
- package/src/{herdr → backends/legacy}/client.ts +14 -69
- package/src/{shared → backends/legacy}/cursor-chat.ts +2 -2
- package/src/{herdr → backends/legacy}/runner.ts +22 -9
- package/src/backends/legacy/types.ts +138 -0
- package/src/extension/auto-doctor.ts +144 -0
- package/src/extension/budget.ts +2 -2
- package/src/extension/child-guard.ts +214 -201
- package/src/extension/event-bus.ts +263 -0
- package/src/extension/legion-commands.ts +719 -0
- package/src/extension/legion-doctor.ts +888 -0
- package/src/extension/legion-stop.ts +150 -0
- package/src/extension/legion-tools.ts +816 -0
- package/src/extension/notify.ts +24 -19
- package/src/extension/playbook.ts +20 -89
- package/src/extension/recycle.ts +2 -7
- package/src/extension/runtime.ts +655 -105
- package/src/extension/scout-guard.ts +483 -0
- package/src/extension/slash.ts +89 -438
- package/src/extension/spawn-hints.ts +79 -0
- package/src/extension/summary.ts +17 -58
- package/src/legion/budget.ts +165 -0
- package/src/legion/db.ts +242 -0
- package/src/legion/events.ts +150 -0
- package/src/legion/mail.ts +412 -0
- package/src/legion/nodes.ts +461 -0
- package/src/legion/rebuild.ts +533 -0
- package/src/legion/state-machine.ts +313 -0
- package/src/legion/usage.ts +101 -0
- package/src/runs/acceptance.ts +82 -25
- package/src/runs/args.ts +51 -5
- package/src/runs/hygiene.ts +335 -0
- package/src/runs/orchestrator.ts +790 -1683
- package/src/runs/owner.ts +61 -0
- package/src/runs/provision.ts +135 -0
- package/src/runs/store.ts +44 -17
- package/src/runs/verify-queue.ts +195 -0
- package/src/shared/name.ts +29 -0
- package/src/shared/output-cap.ts +57 -0
- package/src/shared/progress.ts +57 -135
- package/src/shared/session.ts +243 -171
- package/src/shared/types.ts +107 -208
- package/src/supervisor/child-memory.ts +140 -0
- package/src/supervisor/proc-tree.ts +103 -0
- package/src/supervisor/rpc-supervisor.ts +1033 -0
- package/src/supervisor/types.ts +153 -0
- package/src/supervisor/ui-proxy.ts +226 -0
- package/src/tui/chat-items.ts +330 -0
- package/src/tui/live-overlay.ts +874 -0
- package/src/tui/status.ts +553 -27
- package/src/tui/tree-view.ts +808 -0
- package/src/tui/viz/canvas.ts +119 -0
- package/src/tui/viz/layout.ts +111 -0
- package/src/tui/viz/model.ts +123 -0
- package/src/tui/viz/palette.ts +188 -0
- package/src/tui/viz/panels.ts +530 -0
- package/src/tui/viz/railway.ts +313 -0
- package/src/tui/viz/rate.ts +211 -0
- package/src/tui/viz/view.ts +228 -0
- package/src/extension/parent-label.ts +0 -115
- package/src/profiles/classify.ts +0 -375
- package/src/profiles/profiles.ts +0 -730
- package/src/runs/layout.ts +0 -258
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
# 契约:retire 链加固(SIGKILL 升级 + 后代清场)
|
|
2
|
+
|
|
3
|
+
状态:FROZEN-1(2026-10-12,主会话冻结)
|
|
4
|
+
触发事故:2026-10-12 两个孤儿 `node --test` 进程(PPID=1)持续 110% CPU 各烧 4h20m,SIGTERM 无效,最终需人工 SIGKILL。根因:retire 链止步于 SIGTERM→RETIRE_FAILED,且孙进程(子 pi 经 bash 工具 `detached:true` 派生的测试进程)不在任何击杀范围内,父死后 reparent 到 init 泄露。
|
|
5
|
+
|
|
6
|
+
主契约关联:`docs/legion-v2-contract.md` §3.2 表行 + 修订日志 REV-16。
|
|
7
|
+
|
|
8
|
+
## 0. 侦察已定事实(HEAD 96098c2,worker 直接引用,勿重查)
|
|
9
|
+
|
|
10
|
+
- retire 链现状:`src/supervisor/rpc-supervisor.ts:750-819` `retireChild` = closeInput(:783) → waitForExit(retireTimeoutMs=5s) → `process?.kill("SIGTERM")`(:787) → waitForExit(signalTimeoutMs=1s)(:805) → 仍活则 `throw RETIRE_FAILED`(:807-812)。**无 SIGKILL,无孙进程处理。**
|
|
11
|
+
- `waitForExit` 定义 :832-850,timer 未 unref。`closeInput` :821-830。
|
|
12
|
+
- `RpcSupervisorOptions`(:66-76):`clientFactory? / uiProxy? / retireTimeoutMs?(5000) / signalTimeoutMs?(1000)`,常量 :78-79。
|
|
13
|
+
- `RpcProcessHandle`(`src/supervisor/types.ts:69-90`):`pid?: number`、`stdin`、`exitCode`、`signalCode`、`once/on/off("exit")`、`kill(signal?)`。`kill` 是 `RpcProcessHandle` 自身方法(单 pid 语义),本契约不改它。
|
|
14
|
+
- SDK spawn 硬编码:`spawn("node", [cliPath, ...args], { cwd, env, stdio:["pipe","pipe","pipe"] })`,**无 detached 选项、无任何进程组开关**(rpc-client.js:42-46)。因此子 pi 与 supervisor 同进程组,`kill(-child.pid)` 会误杀宿主自己——**禁止对子 pi 自身 pid 做组击杀**。
|
|
15
|
+
- 子 pi 的 bash 工具孙进程是 `detached:true`(自成会话/进程组),父死后拿不到信号——必须靠 /proc 祖先链在子 pi 存活时枚举。
|
|
16
|
+
- 测试 harness:`test/unit/supervisor.test.ts:191-209`,`FakeRpcProcess`(:36-94,`pid = 10_000 + clients.length`,`kill(signal)` 未忽略则立即 exit,`signals` 数组记录全部信号)、`FakeRpcClient`(:96-158,`stop()` 内部 `process.kill("SIGTERM")`)。`retireTimeoutMs/signalTimeoutMs` 在 harness 里压到 100/100。**无 fake timers,全真实定时器。**
|
|
17
|
+
- 现有硬约束测试:`:287`(graceful retire 后 `signals` deepEqual `[]`)、`:353`(子进程无视 SIGTERM → RETIRE_FAILED + 可重试 + 信号序列硬编码)、`:430`(client 隐藏 process 时 retire 仍 resolve waiter)。retire 行为回归面 = `test/unit/supervisor.test.ts` 唯一(live 测试默认 skip)。
|
|
18
|
+
|
|
19
|
+
## 1. 冻结语义:retire 四级递进 + 后代清场
|
|
20
|
+
|
|
21
|
+
```
|
|
22
|
+
retire(name, {graceful}) 流程(retireChild 内,frozen):
|
|
23
|
+
1. 早退:!isAlive → 原样保留(:750-786 路径),无枚举无清场(子已死,祖先链已断)
|
|
24
|
+
2. 枚举:child.process?.pid 存在 → descendants = enumerateDescendants(pid);否则 [](null-process 分支无 pid,不清场)
|
|
25
|
+
3. graceful 时 closeInput → waitForExit(retireTimeoutMs) 【不变】
|
|
26
|
+
4. SIGTERM:process?.kill("SIGTERM");!process 时 client.stop() 兜底【不变】→ waitForExit(signalTimeoutMs)
|
|
27
|
+
5. SIGKILL 升级(新):仍 alive → process?.kill("SIGKILL") → waitForExit(killTimeoutMs)
|
|
28
|
+
6. 后代清场(新):sweepDescendants(descendants) —— 无论子已退出还是杀不动,都执行
|
|
29
|
+
7. 仍 alive → throw RETIRE_FAILED(重试语义保留:retirePromise 失败后清除,可再次 retire)
|
|
30
|
+
8. 收尾 state=retired 等原逻辑不变
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
- `killTimeoutMs` 新 option,默认 `DEFAULT_KILL_TIMEOUT_MS = 1_000`。
|
|
34
|
+
- SIGTERM 升 SIGKILL 语义变化:原「无视 SIGTERM → RETIRE_FAILED + 子仍活」改为「无视 SIGTERM → 吃到 SIGKILL → 退出」;**只有连 SIGKILL 都无效(仅 fake 场景)才 RETIRE_FAILED**,重试语义不变。
|
|
35
|
+
- graceful:false 语义不变:跳过 stdin close,直接从 SIGTERM 起。
|
|
36
|
+
|
|
37
|
+
## 2. 后代枚举(新模块 `src/supervisor/proc-tree.ts`)
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
// types.ts 新增(supervisor 契约类型)
|
|
41
|
+
export interface DescendantInfo { pid: number; pgid: number }
|
|
42
|
+
|
|
43
|
+
// proc-tree.ts 导出(frozen API)
|
|
44
|
+
export function parseProcStatLine(line: string): { pid: number; ppid: number; pgid: number } | null;
|
|
45
|
+
export function enumerateDescendants(rootPid: number): DescendantInfo[];
|
|
46
|
+
export function currentPgid(): number | null;
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
- `parseProcStatLine`:解析 `/proc/<pid>/stat` 单行。**陷阱:comm 字段可含空格与括号,必须 `lastIndexOf(")")` 后切分**;之后空格分隔:`[0]=state [1]=ppid [2]=pgrp`。解析失败/非有限数 → null。
|
|
50
|
+
- `enumerateDescendants(rootPid)`:扫 `/proc/*/stat` 建 pid→ppid 全表 → 反向 BFS 收集 rootPid 的全部后代(**不含 rootPid**),返回 `{pid, pgid}` 列表(遇到读失败/条目消失的 pid 跳过)。**非 Linux(无 /proc)或 win32 → 返回 []**。**空结果或 rootPid 不存在 → []**。
|
|
51
|
+
- `currentPgid()`:读 `/proc/self/stat` 取 pgrp;非 POSIX / 失败 → null。
|
|
52
|
+
- 纯同步函数,不做任何信号操作。
|
|
53
|
+
|
|
54
|
+
## 3. 清场算法(frozen)
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
sweepDescendants(descendants: DescendantInfo[]): Promise<void>
|
|
58
|
+
if empty → 立即 return(不做任何等待)
|
|
59
|
+
ownPgid = currentPgid()
|
|
60
|
+
pgids = unique(descendants.pgid) 中排除 ownPgid 与负数/非法值,保持枚举遭遇顺序
|
|
61
|
+
pids = unique(descendants.pid),保持枚举遭遇顺序
|
|
62
|
+
TERM 相:对每个 g in pgids → signalProcess(-g, "SIGTERM");再对每个 p in pids → signalProcess(p, "SIGTERM")
|
|
63
|
+
等待 signalTimeoutMs(setTimeout,timer.unref())
|
|
64
|
+
KILL 相:同样顺序 pgids → (-g, "SIGKILL"),pids → (p, "SIGKILL"),无条件执行(幂等,ESRCH 由 signalProcess 吸收)
|
|
65
|
+
全程不得抛出(signalProcess 返回 boolean;seam 抛错也 catch 继续)
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
**安全红线**:
|
|
69
|
+
- **绝不组击杀 ownPgid**(会杀掉 supervisor 宿主自己)。pgid === ownPgid 的后代只做单 pid 击杀。
|
|
70
|
+
- **绝不组击杀子 pi 自身 pid**(子与宿主同组,见 §0)。
|
|
71
|
+
- `signalProcess` 默认实现:`try { process.kill(target, signal); return true } catch { return false }`(ESRCH/EPERM 全部 → false,静默)。
|
|
72
|
+
- 已接受的残余风险(文档化即可,不要求处理):枚举与清场之间 pid 复用误杀(窗口=retire 时长秒级,与 SDK killProcessTree 同等假设);子 pi 异常崩溃(非 retire 路径)时祖先链已断,枚举不可能——该残留归主机 watchdog(明确不做,见 §6)。
|
|
73
|
+
|
|
74
|
+
## 4. 注入缝(可测试性,frozen)
|
|
75
|
+
|
|
76
|
+
`RpcSupervisorOptions` 新增:
|
|
77
|
+
```ts
|
|
78
|
+
killTimeoutMs?: number; // 默认 1_000
|
|
79
|
+
enumerateDescendants?: (rootPid: number) => DescendantInfo[]; // 默认 proc-tree 实现
|
|
80
|
+
signalProcess?: (target: number, signal: NodeJS.Signals) => boolean; // 默认 process.kill+catch
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
**测试安全强制项**:`test/unit/supervisor.test.ts` 的 `harness()` 必须默认注入 `enumerateDescendants: () => []`。原因:FakeRpcProcess 的 pid 是 10000+ 递增的假 pid,若走默认 /proc 枚举器,一旦撞上系统真实 pid 会把真实进程的后代杀掉。清场专项测试自行覆盖注入;**禁止任何 supervisor 单测让默认枚举器接触 FakeRpcProcess 的假 pid**。proc-tree 的真实行为由 `test/unit/proc-tree.test.ts` 用真实进程验证(本测试进程 `process.pid` 为 root,spawn 真实 `sleep`/`sh` 后代断言被枚举到;parser 边界用 `parseProcStatLine` 直接喂 fixture 字符串测)。
|
|
84
|
+
|
|
85
|
+
## 5. 文件归属(worker 全权,其他文件禁碰)
|
|
86
|
+
|
|
87
|
+
| 文件 | 动作 |
|
|
88
|
+
|---|---|
|
|
89
|
+
| `src/supervisor/types.ts` | +`DescendantInfo`、3 个新 option 类型 |
|
|
90
|
+
| `src/supervisor/proc-tree.ts` | 新建(§2 API) |
|
|
91
|
+
| `src/supervisor/rpc-supervisor.ts` | retireChild 四级链 + sweepDescendants + 新 option 接线 + `waitForExit` timer `.unref?.()` |
|
|
92
|
+
| `test/unit/supervisor.test.ts` | harness 默认缝 + `:353` 用例重写 + 新用例(见 §7) |
|
|
93
|
+
| `test/unit/proc-tree.test.ts` | 新建(真实进程枚举 + parser fixture) |
|
|
94
|
+
|
|
95
|
+
不碰:`src/runs/*`、SDK、`handleProcessExit`、`rollbackSpawn`、`disposeRecord`、live 测试、其他一切。
|
|
96
|
+
|
|
97
|
+
## 6. 明确不做
|
|
98
|
+
|
|
99
|
+
- 主机级 watchdog(孤儿进程定期清扫)——后续独立方案。
|
|
100
|
+
- `package.json` 测试 `--test-timeout` ——独立方案。
|
|
101
|
+
- handleProcessExit 崩溃路径的常驻后代登记簿(需常驻枚举,watchdog 范畴)。
|
|
102
|
+
- SDK/RpcClient spawn 改造(detached/setsid)——SDK 硬编码无注入口,收益/风险比差,否决。
|
|
103
|
+
- null-process 分支(client 隐藏 process):行为保持逐字节不变(`:430` 用例是守卫)。
|
|
104
|
+
|
|
105
|
+
## 7. 验收清单
|
|
106
|
+
|
|
107
|
+
命令(注意:本环境 `npx` 被拦截,用 `npm run typecheck` / `node_modules/.bin/tsc`):
|
|
108
|
+
1. `npm run typecheck` → 0 错误。
|
|
109
|
+
2. `npm test` 全绿(含既有 `:287`、`:430`、`:353-重写` 与全部新用例)。
|
|
110
|
+
|
|
111
|
+
新/改用例(frozen 名称):
|
|
112
|
+
- 「retire resolving timeout is retryable after a child ignores SIGTERM and SIGKILL」:ignoredSignals={SIGTERM,SIGKILL} → reject RETIRE_FAILED,signals=["SIGTERM","SIGKILL"],isAlive=true;随后解除 SIGTERM 忽略 → 二次 retire 成功,signals=["SIGTERM","SIGKILL","SIGTERM"],isAlive=false。(重写自 :353)
|
|
113
|
+
- 「SIGKILL escalation retires a child that ignores SIGTERM」:仅忽略 SIGTERM → retire(graceful:false) 正常 resolve,signals=["SIGTERM","SIGKILL"],isAlive=false。
|
|
114
|
+
- 「retire sweeps enumerated descendants with SIGTERM then SIGKILL」:注入枚举器返回 `[{pid:4242,pgid:4242},{pid:5150,pgid:4242}]` + 记录器 signalProcess → 断言调用序列恰为 `(-4242,TERM),(4242,TERM),(5150,TERM)` → 宽限 → `(-4242,KILL),(4242,KILL),(5150,KILL)`。
|
|
115
|
+
- 「descendant sweep never signals the supervisor's own process group」:注入枚举器返回 `[{pid:777, pgid: <currentPgid()>}]` → 断言只有 `(777,TERM),(777,KILL)`,绝无负数目标。
|
|
116
|
+
- 「retire completes without sweep when no descendants」:harness 默认 `()=>[]` → signalProcess 记录器零调用,retire 正常完成。
|
|
117
|
+
- `proc-tree.test.ts`:a) 真实 spawn `sleep 300`(含一层 `sh -c` 中间进程)后代能被 `enumerateDescendants(process.pid)` 枚举到且 pgid 正确;b) rootPid 不存在(如 999999999)→ [];c) `parseProcStatLine` 对含空格/括号 comm 的 fixture 行解析正确,垃圾行 → null。
|
|
118
|
+
|
|
119
|
+
其余验收锚点:`:287` graceful 生命周期用例的 `signals == []` 断言必须继续成立(清场零目标);`:430` null-process 用例行为不变;retire 失败重试语义不变。
|
|
120
|
+
|
|
121
|
+
## 8. 提交要求
|
|
122
|
+
|
|
123
|
+
- 分支:`retire-hardening`;conventional commit(如 `feat(supervisor): escalate retire to SIGKILL and sweep descendant processes`)。
|
|
124
|
+
- 自报 verdict JSON(含 typecheck/test 结果与全部用例名单)。
|
|
125
|
+
- 契约矛盾 = 正确拒绝:引用条款号停下报告,禁止自行解释。
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# Team configuration examples
|
|
2
|
+
|
|
3
|
+
`subagents.teams` maps team names to an ordered roster. A member can be a role
|
|
4
|
+
name string or an object with an `agent` name and per-member overrides. The
|
|
5
|
+
examples below mirror the four local practice teams; replace every model
|
|
6
|
+
placeholder with an ID available from your provider. No provider-specific
|
|
7
|
+
model is required by these templates.
|
|
8
|
+
|
|
9
|
+
```json
|
|
10
|
+
{
|
|
11
|
+
"subagents": {
|
|
12
|
+
"teams": {
|
|
13
|
+
"fe-premium": {
|
|
14
|
+
"description": "Frontend · complex projects",
|
|
15
|
+
"members": [
|
|
16
|
+
{ "agent": "scout", "model": "your-provider/strong-model", "thinking": "high" },
|
|
17
|
+
{ "agent": "prototype", "model": "your-provider/strong-model", "thinking": "high" },
|
|
18
|
+
{ "agent": "planner", "model": "your-provider/strong-model", "thinking": "max" },
|
|
19
|
+
{ "agent": "worker", "model": "your-provider/strong-model", "thinking": "max" },
|
|
20
|
+
{ "agent": "reviewer", "model": "your-provider/strong-model", "thinking": "xhigh" },
|
|
21
|
+
{ "agent": "designer", "model": "your-provider/strong-model", "thinking": "xhigh" },
|
|
22
|
+
{ "agent": "advisor", "model": "your-provider/strong-model", "thinking": "xhigh" },
|
|
23
|
+
"centurion"
|
|
24
|
+
]
|
|
25
|
+
},
|
|
26
|
+
"fe-value": {
|
|
27
|
+
"description": "Frontend · standard projects",
|
|
28
|
+
"members": [
|
|
29
|
+
{ "agent": "scout", "model": "your-provider/value-model", "thinking": "high" },
|
|
30
|
+
{ "agent": "prototype", "model": "your-provider/value-model", "thinking": "high" },
|
|
31
|
+
{ "agent": "planner", "model": "your-provider/strong-model", "thinking": "max" },
|
|
32
|
+
{ "agent": "worker", "model": "your-provider/value-model", "thinking": "xhigh" },
|
|
33
|
+
{ "agent": "reviewer", "model": "your-provider/value-model", "thinking": "max" },
|
|
34
|
+
{ "agent": "designer", "model": "your-provider/strong-model", "thinking": "xhigh" },
|
|
35
|
+
{ "agent": "advisor", "model": "your-provider/strong-model", "thinking": "xhigh" },
|
|
36
|
+
"centurion"
|
|
37
|
+
]
|
|
38
|
+
},
|
|
39
|
+
"be-premium": {
|
|
40
|
+
"description": "Backend · complex projects",
|
|
41
|
+
"members": [
|
|
42
|
+
{ "agent": "scout", "model": "your-provider/strong-model", "thinking": "high" },
|
|
43
|
+
{ "agent": "planner", "model": "your-provider/strong-model", "thinking": "max" },
|
|
44
|
+
{ "agent": "worker", "model": "your-provider/strong-model", "thinking": "max" },
|
|
45
|
+
{ "agent": "reviewer", "model": "your-provider/strong-model", "thinking": "xhigh" },
|
|
46
|
+
{ "agent": "advisor", "model": "your-provider/strong-model", "thinking": "xhigh" },
|
|
47
|
+
"centurion"
|
|
48
|
+
]
|
|
49
|
+
},
|
|
50
|
+
"be-value": {
|
|
51
|
+
"description": "Backend · standard projects",
|
|
52
|
+
"members": [
|
|
53
|
+
{ "agent": "scout", "model": "your-provider/value-model", "thinking": "high" },
|
|
54
|
+
{ "agent": "planner", "model": "your-provider/strong-model", "thinking": "xhigh" },
|
|
55
|
+
{ "agent": "worker", "model": "your-provider/value-model", "thinking": "xhigh" },
|
|
56
|
+
{ "agent": "reviewer", "model": "your-provider/value-model", "thinking": "max" },
|
|
57
|
+
{ "agent": "advisor", "model": "your-provider/strong-model", "thinking": "xhigh" },
|
|
58
|
+
"centurion"
|
|
59
|
+
]
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Each team's `description` and `members` shape follows
|
|
67
|
+
`subagents.teams.<name>`. Member objects apply their own `model` and
|
|
68
|
+
`thinking` values to that role in this team; those values override the same
|
|
69
|
+
fields in the role card's frontmatter. Omitted member override fields continue
|
|
70
|
+
to use the role card/configuration defaults. The string `"centurion"` is a
|
|
71
|
+
plain roster entry with no member-level override.
|
|
72
|
+
|
|
73
|
+
To make one team the settings default, add a sibling `"team": "be-value"`
|
|
74
|
+
under `"subagents"`. `PI_SUBAGENTS_TEAM` takes precedence over that configured
|
|
75
|
+
`subagents.team` value when selecting the team. See the README's [Team
|
|
76
|
+
配置](../README.md#team-配置) section for the selection and override semantics.
|
|
@@ -0,0 +1,276 @@
|
|
|
1
|
+
# pi-legion 3.0 冻结契约:TUI-first 上下文查看器(渲染对齐主上下文 + pi 1.x 升级)
|
|
2
|
+
|
|
3
|
+
> 状态:**FROZEN**(2026-10-13 冻结;修订必须走 §10 流程)
|
|
4
|
+
> 依据:`r-e2d7e116` 三路 scout 侦察(pi 1.1.0 渲染面 / pi-legion 数据流 / session 官方 API),110+ 带行号事实;关键 API 签名由主会话实测冻结于 §2a。
|
|
5
|
+
> 背景:Pi CLI 1.0.0+ 以 TUI 为默认运行模式。本次决策:pi-legion 查看器**只支持 TUI 模式**,宿主依赖升到 **pi 1.x**,查看器渲染复用 pi 主上下文的消息组件。
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. 目标与非目标
|
|
10
|
+
|
|
11
|
+
### 目标
|
|
12
|
+
|
|
13
|
+
1. `/legion` 树视图点开 agent(或 `/legion <name>`)打开的实时浮窗,从「纯文本 activity 行」升级为**渲染真实会话消息**,视觉与 pi 主上下文一致(用户消息块、assistant markdown、工具调用块、thinking、颜色主题)。
|
|
14
|
+
2. 渲染组件与主题直接复用 pi 主程序公开导出:`UserMessageComponent` / `AssistantMessageComponent` / `ToolExecutionComponent` / `getMarkdownTheme()`(pi `dist/index.js:41-44`,注释原文 "UI components for extensions"——官方公开 API,非私有依赖)。
|
|
15
|
+
3. 行为配置复用主配置:`pi.getSettings()` 读 `outputPad` / `hideThinkingBlock` / `codeBlockIndent` / `showImages` / `imageWidthCells`;主题经 `globalThis[Symbol.for("@earendil-works/pi-coding-agent:theme")]` 单例自动与宿主一致(扩展虚拟模块与宿主同实例,scout 实测确认)。
|
|
16
|
+
4. 查看器数据源改用 pi 官方 session API:`parseSessionEntries` + `sessionEntryToContextMessages`(均导出于 pi 主入口);turn 计数与验收判定链仍走 `src/shared/session.ts`(见 §7 明确不做)。
|
|
17
|
+
5. 快捷键对齐 pi 的 TUI 惯例(`app.tools.expand`=ctrl+o / pgup/pgdn / esc / j/k),`app.*` 键位经 `KeybindingsManager.matches(data, id)` 判定,尊重用户自定义键位。
|
|
18
|
+
6. 依赖升级:devDeps `@earendil-works/{pi-coding-agent,pi-tui,pi-agent-core}` `^0.85.1` → `^1.0.0`;补上直接 import 所需的 `@earendil-works/pi-ai` devDep(`AgentMessage` 等类型来自该包)。
|
|
19
|
+
|
|
20
|
+
### 非目标
|
|
21
|
+
|
|
22
|
+
- 不改 RPC supervisor / orchestrator / child 启动链的**运行时行为**(RPC 数据通道维持现状;仅允许 §7 定义的机械 type-compat 修复)。
|
|
23
|
+
- 不改 `src/shared/session.ts` 的 TurnRecord 判定链(Orchestrator/acceptance/usage 依赖)。
|
|
24
|
+
- 不做「历史全局搜索 / 会话导出 / 复制消息」等浮窗不需要的能力。
|
|
25
|
+
- 不动 legacy herdr 归档代码(`src/backends/legacy/`)。
|
|
26
|
+
- 不新增 DB schema 字段(nodes 表结构不变)。
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## 2. 决策记录(ADR)
|
|
31
|
+
|
|
32
|
+
| # | 决策 | 理由 |
|
|
33
|
+
|---|---|---|
|
|
34
|
+
| T1 | 查看器只支持 TUI 模式(`ctx.mode === "tui"` guard) | pi 1.0+ TUI 为默认模式;RPC/json/print 模式下 `ctx.ui.custom()` 返回 undefined,现有 `!ctx.hasUI` guard 在 RPC 下会漏(pi docs `rpc-extension-ui.md` Limitations:RPC 下 `hasUI` 为 true 但 `custom()` 返回 undefined)。非 TUI 模式退化行为:提示一次 warning。 |
|
|
35
|
+
| T2 | 渲染组件直接 import pi-coding-agent 导出 | 官方为扩展准备的公开 API;`notice-renderer.ts:18` 已有先例(import `MessageRenderer`/`Theme`)。 |
|
|
36
|
+
| T3 | 主题经 `getMarkdownTheme()` 获取;禁止在扩展运行期代码调 `initTheme()` | 宿主已初始化全局单例;扩展调用会覆盖宿主状态。单元测试进程无宿主,测试文件内允许(且需要)`initTheme("dark")` 兜底。 |
|
|
37
|
+
| T4 | 数据源 = session jsonl 官方解析 + fileSize cursor 增量机制 | 打开时全量 parse 建组件;活跃期间沿用 cursor 机制(`legion-commands.ts:215-241` 的 `readSessionDelta` 语义),250ms 轮询增量。 |
|
|
38
|
+
| T5 | toolResult 按 toolCallId 回填进 `ToolExecutionComponent`,不单独建组件 | 对齐主程序行为(pi `interactive-mode.js:3286-3294`)。 |
|
|
39
|
+
| T6 | `system` 消息跳过;thinking 块按主程序规则折叠/展开 | pi `interactive-mode.js:3179-3180`。 |
|
|
40
|
+
| T7 | 流式 assistant 文本由 RPC `text_delta` 驱动 `AssistantMessageComponent.updateContent()`;每 250ms tick 磁盘增量并入 | 中途 kill 留下的 torn line 靠 cursor 回退(计数回退不推进游标)兜住。 |
|
|
41
|
+
| T8 | 查看器数据结构用结构化 `ChatItem[]`,非 `string[]` | 组件方案前置。`getState()` 需保留可测试的状态视图(见 §3.4)。 |
|
|
42
|
+
| T9 | 浮窗内 `app.tools.expand`(ctrl+o)经 keybindingsManager 判定;其余滚动/关闭键用 pi-tui 原生键硬编码 | `app.*` 是 pi 应用级键位可被用户自定义;j/k/pgup/esc 是 pi-tui 原生键。树视图键位维持现状不动。 |
|
|
43
|
+
| T10 | 依赖 caret 升级 `^1.0.0` + 重新生成 lockfile + `npm install` | worktree 无 node_modules 是历史遗留;typecheck/test 需要真实 .d.ts。npm registry pi-coding-agent 与 pi-tui 最新均为 1.1.0(主会话实测)。 |
|
|
44
|
+
| T11 | `ToolExecutionComponent` 的 `ui` 传 `ctx.ui.custom` 工厂第一参数(真实 TUI 实例);`cwd` 传 `node.worktreePath ?? ctx.cwd`;`toolDefinition` 传 undefined | 查看器无工具注册表上下文;undefined 走 fallback 渲染(scout 实测确认可渲染)。 |
|
|
45
|
+
| T12 | **[REV-2] 活跃节点(有 active job)打开浮窗时同样轮询磁盘增量;RPC text_delta 流与磁盘轮询并行**。去重机制:磁盘增量中的 assistant 消息落地时收回(retract)流式组件,避免同一条消息双重渲染;若流式文本领先已落盘消息(属于未落盘后续内容),在增量 append 后重建流式组件显示余量 | REV-1 时代的互斥("RPC 流缺位时才轮询")导致活跃节点的结构化消息(user / assistant+toolCall / toolResult)无任何路径进入 viewer——正是用户需求"支持动态渲染"要修复的缺口。旧行为的回归断言(`legion-integration.test.ts` "active text-delta sessions do not duplicate session-file activity")随之改写为:磁盘增量动态出现 + 不与流式文本重复。 |
|
|
46
|
+
| T13 | **[REV-3] 流式去重的"包含"判定用子串而非前缀**:`diskText.includes(streamingText)` 即视为已包含(收回不重建,无余量);仅当流式严格领先(`streamingText.startsWith(diskText)`)时取余量重建;两者均不成立才全量重建(防御分支) | REV-2 三分支的前缀语义在中途打开/clamp 截断场景下失真:viewer 订阅前的 delta 丢失(打开时消息已流到一半)与 `clampStreamingText` 截头,使 streamingText 只是落盘消息的尾部子串,双向 startsWith 均为 false,落入"无前缀"分支 → 落盘全文与陈旧尾巴永久双重渲染且跨消息复合(reviewer 探针验证)。子串判定容忍丢失头部的流式文本:最坏情况只丢一小截陈旧尾巴的视觉,不会永久重复。 |
|
|
47
|
+
| T14 | **[REV-4] finalize-then-disk 去重**:`finishStreaming()` 固化流式文本时记录 `finalizedAssistantText`;`acceptBackfill` 增量中 assistant 文本包含该记录时,克隆消息置空 text part(保留 thinking/toolCall part)再 append;`chat-items.ts` 对"渲染 content 为空且无 toolCall"的 assistant 跳过建组件;消费后清空记录 | 粗事件(`agent_settled`/`tool_execution_start`/`turn_start`)触发 finishStreaming 后流式文本固化成普通组件并脱离去重追踪;若落盘增量在之后才被轮询抓到,同文本消息会再 append 一份 → 永久双渲染(reviewer-1 探针验证,旧谓词下同样存在,非 REV-3 引入)。带 toolCall 的落盘消息不能整条跳过(会丢工具块),故只置空文本 part 保留 toolCall 渲染。 |
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## 2a. 冻结的 API 签名(实测自 pi 1.1.0 dist;worker 不得偏离)
|
|
52
|
+
|
|
53
|
+
所有符号来自 `@earendil-works/pi-coding-agent`(主入口)与 `@earendil-works/pi-tui`。扩展运行期由 pi 的 jiti 虚拟模块映射到宿主 dist(同一模块实例),无需安装即可 import;typecheck/test 需要 devDeps 存在(T10)。
|
|
54
|
+
|
|
55
|
+
```ts
|
|
56
|
+
// @earendil-works/pi-coding-agent —— 消息组件(主上下文同款)
|
|
57
|
+
import {
|
|
58
|
+
UserMessageComponent, // new (text: string, markdownTheme?, outputPad?, markdownTransformers?)
|
|
59
|
+
AssistantMessageComponent, // new (message?: AssistantMessage, hideThinkingBlock?, markdownTheme?,
|
|
60
|
+
// hiddenThinkingLabel?, outputPad?, markdownTransformers?)
|
|
61
|
+
// .updateContent(message, isStreaming?)
|
|
62
|
+
ToolExecutionComponent, // new (toolName, toolCallId, args, options?{showImages,imageWidthCells,outputPad},
|
|
63
|
+
// toolDefinition?(undefined), ui: TUI, cwd: string)
|
|
64
|
+
// .updateResult({content:[{type,text?,data?,mimeType?}], details?, isError,
|
|
65
|
+
// durationMs?}, isPartial?)
|
|
66
|
+
// .markExecutionStarted(), .setArgsComplete(), .setExpanded(bool)
|
|
67
|
+
getMarkdownTheme, // () => MarkdownTheme —— 宿主已 initTheme,运行期直接调用
|
|
68
|
+
parseSessionEntries, // (content: string) => FileEntry[](v1/v2 旧版本行需先过 migrateSessionEntries)
|
|
69
|
+
migrateSessionEntries, // (entries: FileEntry[]) => void(原地迁移到当前版本)
|
|
70
|
+
sessionEntryToContextMessages, // (entry: SessionEntry) => AgentMessage[]
|
|
71
|
+
} from "@earendil-works/pi-coding-agent";
|
|
72
|
+
|
|
73
|
+
// 消息类型 —— REV-1 修正(2026-10-13,worker-0 上报:pi-ai@1.1.0 不导出 AgentMessage):
|
|
74
|
+
// AgentMessage 定义在 @earendil-works/pi-agent-core/dist/types.d.ts:322
|
|
75
|
+
// (= Message | CustomAgentMessages[...],Message 及 AssistantMessage 等成员类型来自 pi-ai)
|
|
76
|
+
import type { AgentMessage } from "@earendil-works/pi-agent-core";
|
|
77
|
+
import type {
|
|
78
|
+
AssistantMessage, ThinkingContent,
|
|
79
|
+
} from "@earendil-works/pi-ai";
|
|
80
|
+
|
|
81
|
+
// @earendil-works/pi-tui
|
|
82
|
+
import {
|
|
83
|
+
Container, // addChild/removeChild/clear/invalidate/render
|
|
84
|
+
Spacer, Key, matchesKey, visibleWidth, truncateToWidth,
|
|
85
|
+
stripTerminalSequences, truncateToVisualLines,
|
|
86
|
+
type Component, type TUI, type TuiMouseEvent, type OverlayHandle,
|
|
87
|
+
} from "@earendil-works/pi-tui";
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
注意:`pi.getSettings()` 是 `ExtensionAPI` 的方法(pi `dist/core/extensions/types.d.ts:1262`),不是独立导出函数。`markdownTransformers` 参数:主程序的 `registerMarkdownTransformer` 注册的 transformer **不会**自动作用于自建组件实例,查看器传 `undefined` 即主程序无 transformer 时的默认行为。
|
|
91
|
+
|
|
92
|
+
### 组件配方(照抄 pi `interactive-mode.js:3145-3300` 的 dispatch)
|
|
93
|
+
|
|
94
|
+
| role / entry | 组件与调用 |
|
|
95
|
+
|---|---|
|
|
96
|
+
| user | `Spacer(1)` → `new UserMessageComponent(text, mdTheme, outputPad)`。text = 文本 content part 拼接(`UserMessage.content` 可为 string 或 parts)。skill-invocation 块不解析,文本原样渲染。 |
|
|
97
|
+
| assistant | `new AssistantMessageComponent(msg, hideThinkingBlock, mdTheme, "Thinking...", outputPad)`。**msg 需克隆:content 只留 text/thinking part**(toolCall part 会另建工具组件;实测 content 含 toolCall 时该组件 render 返回空数组)。 |
|
|
98
|
+
| assistant.content 中 `type === "toolCall"` | `new ToolExecutionComponent(name, id, args, {showImages, imageWidthCells, outputPad}, undefined, tui, cwd)` |
|
|
99
|
+
| toolResult | 不建组件;按 `toolCallId` 找到对应 ToolExecutionComponent 回填 `updateResult({content, isError, durationMs?})` |
|
|
100
|
+
| system / thinking_level_change / model_change / usage / label / session_info / custom(条目)/ context_edit / compaction / branch_summary / custom_message | 不渲染;遇到这些类型跳过不炸 |
|
|
101
|
+
|
|
102
|
+
### 数据流(全量 + 增量)
|
|
103
|
+
|
|
104
|
+
```text
|
|
105
|
+
打开浮窗:
|
|
106
|
+
sessionFile → fs.readFileSync → parseSessionEntries(text)
|
|
107
|
+
→ [migrateSessionEntries 若含旧版本行] → 过滤 type === "message"
|
|
108
|
+
→ sessionEntryToContextMessages(entry) → AgentMessage[]
|
|
109
|
+
→ dispatch 建 ChatItem[] → 渲染
|
|
110
|
+
增量 (250ms poll, 仅 RPC 流缺位时):
|
|
111
|
+
statSync().size > cursor.fileSize 时 re-read 全文件 → parse
|
|
112
|
+
→ 与已渲染 message 数比对 → 只把新增 AgentMessage 追加为 ChatItem
|
|
113
|
+
→ 计数回退(并发半写)时不推进游标,本 tick 丢弃,下 tick 重试
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
简单方案定案:增量即「全量 re-parse + 计数 diff」,与现有 `readSessionDelta` 的 fileSize cursor 语义一致;子会话文件通常在数十 KB~几 MB 量级,re-parse 成本可接受,规避半行 JSON 边界处理。
|
|
117
|
+
|
|
118
|
+
### theme / 设置传递链(冻结)
|
|
119
|
+
|
|
120
|
+
```text
|
|
121
|
+
ctx.ui.custom((tui, theme, keybindings, done) => ...)
|
|
122
|
+
→ mdTheme = getMarkdownTheme() // 借宿主单例;单测进程内 initTheme("dark") 兜底
|
|
123
|
+
→ settings = pi.getSettings() // outputPad / hideThinkingBlock / codeBlockIndent / showImages / imageWidthCells
|
|
124
|
+
→ hideThinkingBlock = settings.hideThinkingBlock ?? false
|
|
125
|
+
→ outputPad = settings.outputPad ?? 1
|
|
126
|
+
→ keybindings // 工厂第三参数,KeybindingsManager.matches(data, "app.tools.expand")
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
worker 实现时如发现签名与实际不符(例如 `getSettings()` 返回形状不同),按 §10 契约矛盾流程上报,不得自行更换方案。
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## 3. 查看器架构(V3 context viewer)
|
|
134
|
+
|
|
135
|
+
### 3.1 组件树
|
|
136
|
+
|
|
137
|
+
```text
|
|
138
|
+
LegionContextViewer (Component) ← ctx.ui.custom(factory, { overlay: true })
|
|
139
|
+
├─ header: `● name (role) · model · turn N · elapsed · status`(主题化标签行,语义沿用现有 header)
|
|
140
|
+
└─ 滚动视口(自管分页,参照 tree-view.ts:66-68 的 layout-leaf 约束)
|
|
141
|
+
└─ Container
|
|
142
|
+
├─ Spacer(1) + UserMessageComponent(...)
|
|
143
|
+
├─ AssistantMessageComponent(...)
|
|
144
|
+
├─ ToolExecutionComponent(...)
|
|
145
|
+
└─ …(ChatItem 流)
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
### 3.2 ChatItem 数据模型(新增 `src/tui/chat-items.ts`)
|
|
149
|
+
|
|
150
|
+
```ts
|
|
151
|
+
import type { AssistantMessage, AgentMessage } from "@earendil-works/pi-ai";
|
|
152
|
+
import type { UserMessageComponent } from "@earendil-works/pi-coding-agent";
|
|
153
|
+
// (组件类是值导入;上面仅示意类型关系,实际 import 形式由 worker定,保持类型正确即可)
|
|
154
|
+
|
|
155
|
+
export type ChatItem =
|
|
156
|
+
| { kind: "user"; component: UserMessageComponent }
|
|
157
|
+
| { kind: "assistant"; component: AssistantMessageComponent }
|
|
158
|
+
| { kind: "tool"; component: ToolExecutionComponent; toolCallId: string };
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
### 3.3 快捷键规范(TUI-first,冻结)
|
|
162
|
+
|
|
163
|
+
浮窗(context viewer)消费以下输入;树视图键位**维持现状不动**(o/enter/click 打开浮窗、j/k 移动、`/` 搜索等,用户肌肉记忆):
|
|
164
|
+
|
|
165
|
+
| 键 | 判定方式 | 浮窗行为 |
|
|
166
|
+
|---|---|---|
|
|
167
|
+
| esc | `matchesKey(data, Key.escape)` | 关闭浮窗 |
|
|
168
|
+
| ctrl+o | `keybindingsManager.matches(data, "app.tools.expand")` | 切换全部工具块展开状态(`ToolExecutionComponent.setExpanded()`) |
|
|
169
|
+
| j / down | `matchesKey` | 向下滚动一行 |
|
|
170
|
+
| k / up | `matchesKey` | 向上滚动一行 |
|
|
171
|
+
| pgdn / pgup | `matchesKey(data, Key.pageDown/pageUp)` | 页滚(页大小 = 视口高度) |
|
|
172
|
+
| g / G | `matchesKey` | 滚到底部 / 顶部(vim 惯例) |
|
|
173
|
+
| 流式期间 | — | follow-end:新内容到达自动滚到底(用户手动上滚后暂停 follow,滚到底恢复) |
|
|
174
|
+
|
|
175
|
+
### 3.4 状态与可测试性
|
|
176
|
+
|
|
177
|
+
- `getState()` 至少暴露:`nodeId` / `open` / `turn` / `status` / 结构化 items 计数或派生的纯文本行视图(供既有测试断言改造使用)。具体形状 worker 定,测试随之适配,但**订阅/退订/backfill 游标/互斥**的既有测试意图必须保留(§4.2 U2/U7)。
|
|
178
|
+
- 生命周期语义不变:`createLiveOverlay.open(nodeId)` 每次新建组件、close/dispose 精确退订一次(现有 `live-overlay.ts` 行为,测试覆盖)。
|
|
179
|
+
|
|
180
|
+
### 3.5 Fast path(不炸约束)
|
|
181
|
+
|
|
182
|
+
- 无 sessionFile 的节点:显示 header + "No session yet.",不炸不白屏。
|
|
183
|
+
- 孤儿 toolResult(toolCall 组件尚不存在):存 pending map,组件创建时回填。
|
|
184
|
+
- torn line / 计数回退:cursor 不推进,本 tick 丢弃(T7)。
|
|
185
|
+
- 旧版本 session 行(v1/v2):`migrateSessionEntries` 迁移后照常渲染。
|
|
186
|
+
|
|
187
|
+
---
|
|
188
|
+
|
|
189
|
+
## 4. 文件归属与验收
|
|
190
|
+
|
|
191
|
+
### 4.1 文件所有权(本次交付为单 worker 两阶段,见 §5)
|
|
192
|
+
|
|
193
|
+
| 阶段 | 文件 | 语义 |
|
|
194
|
+
|---|---|---|
|
|
195
|
+
| A | `package.json`(devDeps 升级 + pi-ai devDep)、`package-lock.json` | 依赖基线 |
|
|
196
|
+
| A | 任意文件(**仅机械 type-compat**,逐条报告) | 1.x 类型表面所需的非行为修复 |
|
|
197
|
+
| B | `src/tui/live-overlay.ts`(重写为查看器)、`src/tui/chat-items.ts`(新)、`src/tui/message-factory.ts`(新,可选合并入 chat-items) | 查看器核心 |
|
|
198
|
+
| B | `src/extension/legion-commands.ts` | 接线:`treeForLiveSource.backfill` 改造 + `openLiveOverlay` 换新查看器 + TUI guard(T1) |
|
|
199
|
+
| B | `test/unit/legion-live-overlay.test.ts`、`test/unit/legion-integration.test.ts`(仅 §4.2 U7 授权的断言适配) | 测试适配 |
|
|
200
|
+
| B | `docs/tui-viewer-contract.md` | 本契约(若有 REV 修订) |
|
|
201
|
+
|
|
202
|
+
**禁改**:`src/supervisor/**`、`src/legion/**`、`src/runs/**`(阶段 A 的机械 type-compat 除外,逐条报告且不得改行为)、`src/extension/runtime.ts`、`src/extension/notice-renderer.ts`、`docs/legion-v2-contract.md`、`README.md`、`agents/`、`skills/`、`test/unit/legion-tree-view.test.ts`、`test/unit/legion-schema-sentinel.test.ts`。
|
|
203
|
+
|
|
204
|
+
### 4.2 验收清单(可机器判定)
|
|
205
|
+
|
|
206
|
+
- **U1** `npm run typecheck` 通过(pi 1.x .d.ts 下)。
|
|
207
|
+
- **U2** `npm test`(unit)全绿;live-overlay 既有 5 测试的**意图**保留(订阅/退订/换节点/游标/关闭停轮询),断言可适配新结构。
|
|
208
|
+
- **U3** `npm run test:integration` 全绿。
|
|
209
|
+
- **U4** cursor 回退保护:模拟文件计数回退(并发半写),游标不推进、不重放旧消息(新增测试)。
|
|
210
|
+
- **U5** 全量渲染冒烟:假 session(user/assistant/toolCall/toolResult 混合)→ render 输出含用户消息底色 ANSI、markdown 代码高亮 ANSI、工具块标题行(新增测试)。
|
|
211
|
+
- **U6** 快捷键冒烟:ctrl+o 切换工具块展开(render 输出变化)、pgdn 滚动、esc 关闭(新增测试)。
|
|
212
|
+
- **U6a** `test/unit/legion-tree-view.test.ts` 全绿且其覆盖的源文件零改动。
|
|
213
|
+
- **U7** `legion-integration.test.ts:717-725` 的 backfill 行断言允许适配为全量渲染语义(打开时渲染全部 turn,契约 T4);除此之外该文件仅允许为组件流改造所必需的断言修改。
|
|
214
|
+
- **U7a** [REV-2 改写] 激活节点打开浮窗时磁盘轮询照常工作:RPC text_delta 流活跃期间,session 文件新落盘的结构化消息必须动态出现在 viewer,且不与流式文本重复渲染(收回/重建去重)。原 "active text-delta sessions do not duplicate session-file activity" 断言改写为 "动态出现 + 无重复"(`legion-integration.test.ts` 对应用例)。
|
|
215
|
+
- **U7c** [REV-2 新增] 流式收回去重:磁盘增量落地某 assistant 消息后,流式组件被收回;若 streamingText 领先该消息(未落盘余量),流式组件重建显示余量(`legion-live-overlay.test.ts` 新用例)。
|
|
216
|
+
- **U7b** `legion-schema-sentinel.test.ts` 不受影响(预期全绿)。
|
|
217
|
+
- **U8** `npm run test:all`(typecheck + unit + integration)全绿。
|
|
218
|
+
- **U9**(人工,主会话收官)真实宿主打开 `/legion` 点开 agent,浮窗视觉对齐主上下文。
|
|
219
|
+
|
|
220
|
+
---
|
|
221
|
+
|
|
222
|
+
## 5. 里程碑划分
|
|
223
|
+
|
|
224
|
+
| # | 内容 | 执行者 | 依赖 |
|
|
225
|
+
|---|---|---|---|
|
|
226
|
+
| M1 | 契约落库 commit | 主会话 | — |
|
|
227
|
+
| M2 | 阶段 A:依赖升级基线绿;阶段 B:查看器重写 + 接线 + 测试适配(单 worker,A 完成自检后才进 B) | W1(worker) | M1 |
|
|
228
|
+
| M3 | 主会话验证:test:all 全绿 + 真实宿主人工冒烟(U9) | 主会话 | M2 |
|
|
229
|
+
| M4 | reviewer 对抗式审查(正确性/回归/测试覆盖)→ findings → steer 原 worker 修复 → 复审 → 合并 | reviewer + W1 | M3 |
|
|
230
|
+
|
|
231
|
+
单 worker 两阶段的原因:阶段 B 的 typecheck 依赖阶段 A 装出的 1.x 依赖;`package.json` 与 `live-overlay.ts` 归属同一 worker 避免跨分支冲突。
|
|
232
|
+
|
|
233
|
+
---
|
|
234
|
+
|
|
235
|
+
## 6. 人工验收样例(主会话 M3 使用)
|
|
236
|
+
|
|
237
|
+
1. 打开一个活跃 scout:assistant 流式文字带 markdown 渲染(标题色、代码高亮)。
|
|
238
|
+
2. 工具调用块:pending/success/error 状态色;ctrl+o 展开显示 args/result,可再收起。
|
|
239
|
+
3. 用户消息块:底色、padding 与主上下文相同。
|
|
240
|
+
4. thinking 块折叠为 "Thinking..."(`hideThinkingBlock=true` 时)。
|
|
241
|
+
5. 生成期间浮窗 follow-end;手动上滚后暂停,滚到底恢复。
|
|
242
|
+
6. 无 sessionFile 的节点降级行不炸。
|
|
243
|
+
|
|
244
|
+
---
|
|
245
|
+
|
|
246
|
+
## 7. 明确不做(防蔓延)
|
|
247
|
+
|
|
248
|
+
- 不给 tree-view 新增键位/交互。
|
|
249
|
+
- 不做浮窗内「回复/steer」输入框(subagent 交互仍走 subagent 工具)。
|
|
250
|
+
- 不做浮窗搜索。
|
|
251
|
+
- 不改 RPC supervisor / orchestrator 的运行时行为。**例外**:阶段 A 允许 1.x 类型表面变化所需的机械 type-compat 修复(不改行为、逐条报告);若发现 RpcClient API 语义级变化(机械修复无法满足),停下按 §10 上报。
|
|
252
|
+
- 不做主会话级 `system` prompt 的渲染、不做 compaction/branch_summary 视图。
|
|
253
|
+
|
|
254
|
+
---
|
|
255
|
+
|
|
256
|
+
## 8. 既有测试意图对照
|
|
257
|
+
|
|
258
|
+
| 测试文件 | 意图保留 | 断言适配 |
|
|
259
|
+
|---|---|---|
|
|
260
|
+
| `legion-live-overlay.test.ts` | 生命周期/订阅/退订/backfill 游标/关闭停轮询 | 适配新结构 |
|
|
261
|
+
| `legion-integration.test.ts` | 双通道互斥、stored/process 去重、树入口 | U7 授权范围内的适配 |
|
|
262
|
+
| `legion-tree-view.test.ts` | 树键位/OSC8 | 不动 |
|
|
263
|
+
| `legion-schema-sentinel.test.ts` | DB schema 契约 | 不动 |
|
|
264
|
+
|
|
265
|
+
---
|
|
266
|
+
|
|
267
|
+
## 9. 契约修订记录(REV)
|
|
268
|
+
|
|
269
|
+
- **REV-1**(2026-10-13,触发者 worker-0):§2a 消息类型 import 修正——`AgentMessage` 来自 `@earendil-works/pi-agent-core`(`dist/types.d.ts:322`)而非 pi-ai(pi-ai@1.1.0 不导出该类型);`AssistantMessage`/`ThinkingContent` 等成员类型仍来自 pi-ai。机械缺口,直接修订。
|
|
270
|
+
- **REV-2**(2026-10-20,触发者主会话,用户新需求):T12 互斥解除——用户反馈活跃节点上下文展示不支持动态渲染;根因是 RPC feed 订阅成功时磁盘轮询被关闭,结构化消息无路径进入 viewer。改为双通道并行 + 流式组件收回去重(chat-items.ts 新增 `retractStreamingItem()`)。U7a/U7c 同步改写/新增。涉及文件:`src/extension/legion-commands.ts`(订阅时始终挂 pollBackfill)、`src/tui/live-overlay.ts`(acceptBackfill 增量收回/重建流式组件)、`src/tui/chat-items.ts`(新增收回能力)、两测试文件。
|
|
271
|
+
- **REV-3**(2026-10-20,触发者 reviewer(对抗审查 F1):三分支去重的包含判定从前缀放宽为子串):REV-2 的「无前缀 → 全量重建」分支在真实主线路径(viewer 中途打开、clampStreamingText 截头)下产生永久性双重渲染且跨消息复合(探针验证:尾部子串场景落盘全文与陈旧尾巴同时渲染不消失)。T13 新增固化语义:`diskText.includes(streamingText)` → 已包含(收回不重建);`streamingText.startsWith(diskText)` → 余量重建;否则防御性全量重建。U7c 补齐三分支用例 + 中途打开 + clamp 截断场景。
|
|
272
|
+
- **REV-4**(2026-10-20,触发者 reviewer-1(增量复审 minor):finalize-then-disk 双重渲染窗口):粗事件(agent_settled/tool_execution_start/turn_start)先于轮询抓到落盘增量到达时,已固化的流式组件与同文本落盘消息双渲染(探针验证新旧谓词下均存在,REV-2 遗留非 REV-3 引入;窗口 ≤250ms 但每次 turn 结束常见)。T14 新增固化语义:finishStreaming 记录 finalizedAssistantText;acceptBackfill 增量 assistant 文本包含该记录时克隆置空 text part(保留 thinking/toolCall)再 append;chat-items 对空 content 且无 toolCall 的 assistant 跳过建组件;消费后清记录。U7c 追加 settle-先-落盘用例。
|
|
273
|
+
|
|
274
|
+
## 10. 修订规则
|
|
275
|
+
|
|
276
|
+
worker 发现契约矛盾:停下上报(不要自行解释)。主会话核事实 → ①机械缺口直接修契约落 REV-x(日期/条款/原因/触发者)+ commit;②语义歧义派 advisor 裁决,裁决落 REV 后重派。
|