@nathan33/nao-skill 0.18.3 → 0.18.4
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.
|
@@ -37,6 +37,13 @@ description: pi-intercom 多会话协作协议（常驻引用）
|
|
|
37
37
|
显式指定时由 `NAO_MODEL_WHITELIST` 在**命令行入口解析阶段**即校验，
|
|
38
38
|
不命中直接 `die`，无部分拉起；PM 只需如实转达用户 `-m` 指定。
|
|
39
39
|
|
|
40
|
+
## 会话内子代理（授权与回执归属）
|
|
41
|
+
|
|
42
|
+
- **授权**：角色可在自身 turn 内用 pi-subagents 起**会话内子代理**（scout / researcher / oracle / reviewer / evidence-auditor 等）。默认**只读**；需要写入时须 `worktree: true` 隔离并指定**单一集成者**（父角色），同一 cwd 禁多写。子代理既**不属**舰队会话身份模型 —— 边界与 `status`/`close` 处置**见上文「子代理会话不属舰队会话身份模型」**，此处不重复。
|
|
43
|
+
- **回执归属（硬性）**：子代理的 run 结果**只是证据，不等于回执**；`[编号] done(lite|full)` **只能由父角色**在自行核对后经 intercom `send` 发出（PM 只认父角色 done）。父角色不得把子代理输出直接转贴为回执。
|
|
44
|
+
- **子代理禁令**：子代理**不得以舰队角色名义回执**、**不得发送 `done` 形态消息**、**不得直发 PM**；需决策/阻塞/授权走 `contact_supervisor`（进程内 native 通道，无需 pi-intercom；父侧对应用 `subagent_supervisor`）。
|
|
45
|
+
- **证据格式**：子代理产物须含**命令 + exit code + 例数/文件数（或断言数）+ 路径**，供父角色写入回执「测试」栏；无证据的「完成」不算证据。注入文本见 `@.agents/templates/pi-subagents/intercom-bridge.md`（安装说明见同目录 `README.md`）。
|
|
46
|
+
|
|
40
47
|
## 开工前自检（派发闸门）
|
|
41
48
|
|
|
42
49
|
派发前跑一次：
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# nao 版子代理桥指令（`intercomBridge.instructionFile`）安装说明
|
|
2
|
+
|
|
3
|
+
本目录是 nao 舰队对「会话内子代理」的口径模板，供 pi-subagents 的 `intercomBridge.instructionFile` 使用。模板只做一件事：把**回执归属 / 身份禁令 / 证据格式**三条 nao 语义注入子代理。协议侧对应条款见 `@.agents/common/intercom-protocol.md`「会话内子代理（授权与回执归属）」。
|
|
4
|
+
|
|
5
|
+
- **本批不写任何用户配置文件**：下面步骤由使用者自行执行；本仓不修改 `~/.pi/...`。
|
|
6
|
+
- **零敏感值 / 零绝对家目录路径**：本目录内所有文档只用 `~/...` 或 `$HOME/...` 形式。
|
|
7
|
+
|
|
8
|
+
## 一、安装（两条命令 + 一段配置）
|
|
9
|
+
|
|
10
|
+
1. 把模板复制到 pi-subagents 的配置目录（目录不存在时先建）：
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
mkdir -p ~/.pi/agent/extensions/subagent
|
|
14
|
+
cp <本仓>/.agents/templates/pi-subagents/intercom-bridge.md \
|
|
15
|
+
~/.pi/agent/extensions/subagent/nao-intercom-bridge.md
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
2. 在用户级配置 `~/.pi/agent/extensions/subagent/config.json` 中启用（**相对**路径，不写绝对家目录）：
|
|
19
|
+
|
|
20
|
+
```json
|
|
21
|
+
{
|
|
22
|
+
"intercomBridge": {
|
|
23
|
+
"mode": "always",
|
|
24
|
+
"instructionFile": "nao-intercom-bridge.md",
|
|
25
|
+
"resultDelivery": false
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
- `instructionFile` 的相对路径从 `~/.pi/agent/extensions/subagent/` 解析，因此与模板放在同一目录即可。
|
|
31
|
+
- `mode` 取值 `off` / `always` / `fork-only`；nao 场景用 `always`（每次子代理都注入）。
|
|
32
|
+
- `resultDelivery` 保持 `false`：nao 不需要外部监听者 ack 结果。
|
|
33
|
+
|
|
34
|
+
3. 生效检查：在 pi 会话内运行 `/subagents-doctor`，确认 `bridge: active` 且指令来自上述文件。
|
|
35
|
+
|
|
36
|
+
## 二、为什么不用 `{orchestratorTarget}` 占位符
|
|
37
|
+
|
|
38
|
+
pi-subagents 的默认模板支持一个「父会话目标」占位符，但 nao 版**刻意不使用**它：
|
|
39
|
+
|
|
40
|
+
- 父会话目标由 `contact_supervisor` 在子代理运行时**自行解析**（native 通道，不依赖 pi-intercom）；把父会话名写进模板反而会把启动契约摘要绑到具体父会话上，父会话一变就可能让启动前置校验失败。
|
|
41
|
+
- 目标名写死还会带来「换个 PM 会话名就失效」的可移植性问题。
|
|
42
|
+
- 因此本模板只写「用 `contact_supervisor` 回父角色」，不出现任何目标占位符。
|
|
43
|
+
|
|
44
|
+
## 三、已知行为与排障
|
|
45
|
+
|
|
46
|
+
- **已知低危行为（本批只记录，不调整）**：pi-subagents 0.78 的默认控制通知通道包含 `intercom`，长跑的会话内子代理偶尔会向父会话**本地注入**一条 control 消息。该消息**不经 broker、不会出现在 `intercom list`**，只占一点父会话上下文。nao 暂不改用户配置里的通知通道；如噪音明显，可在用户配置中收紧通知通道。
|
|
47
|
+
- **模板未生效 / 仍看到默认文案**：确认 `config.json` 的键名与 `mode`；确认文件已复制到 `~/.pi/agent/extensions/subagent/` 且文件名与 `instructionFile` 完全一致。
|
|
48
|
+
- **排障入口**：`/subagents-doctor` 会显示桥是否 active、当前 mode 与目标解析结果；先看它，再怀疑配置。
|
|
49
|
+
- **子代理仍直发 PM / 发 `done`**：这属于越权，说明注入未生效或子代理由外部工具另配了 intercom；父角色仍只认自己的 `done`，不采信子代理消息。
|
|
50
|
+
|
|
51
|
+
## 四、口径归属（唯一事实分工）
|
|
52
|
+
|
|
53
|
+
- **语义**（授权 / 回执归属 / 身份禁令 / 证据格式）在 `.agents/common/intercom-protocol.md`。
|
|
54
|
+
- **注入文本**在本文件的同目录 `intercom-bridge.md`。
|
|
55
|
+
- **安装步骤**在本文件。
|
|
56
|
+
- 机械探针对应 `tests/t4/cases/16-intercom-bridge.sh`（校验模板条款齐备、无目标占位符、配置样例接受/拒绝与协议小节四条齐备）。
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# nao 会话内子代理协作口径
|
|
2
|
+
|
|
3
|
+
你正在作为**会话内子代理**运行：为父角色（nao 舰队角色会话）执行一次有界的调研 / 评审 / 侦察 / 实现工作，并把结果交回父角色。以下三条为硬性口径。
|
|
4
|
+
|
|
5
|
+
## 一、回执归属（硬性）
|
|
6
|
+
|
|
7
|
+
- 子代理的 run 结果只是证据，不等于回执。终态回执 `[编号] done(lite|full)` 只能由父角色在自行核对后经 intercom 发出。
|
|
8
|
+
- PM 只认父角色发出的 `done`。你不得代替父角色回执，也不得把「我完成了」当作对 PM 的交付。
|
|
9
|
+
|
|
10
|
+
## 二、身份与消息禁令（硬性）
|
|
11
|
+
|
|
12
|
+
- 不得以舰队角色名义回执：不得以任一舰队角色（`pm` / `arch-designer` / `rd-fe` / `rd-be` / `qa` / `rd-infra`）的名义说话或回执。
|
|
13
|
+
- 不得发送 `done` 形态的消息；不得直接向 PM 发送任何消息。
|
|
14
|
+
- 需要决策、被阻塞、需要授权或确认范围：用 `contact_supervisor({ reason: "need_decision", message: "<问题>" })` 回父角色；有实质进展或计划变更：用 `contact_supervisor({ reason: "progress_update", message: "UPDATE: <摘要>" })`。
|
|
15
|
+
- `contact_supervisor` 是进程内 native 通道（不依赖 pi-intercom），它会自动解析父会话目标，因此本指令不需要、也不会写死父会话名。
|
|
16
|
+
|
|
17
|
+
## 三、证据格式（硬性）
|
|
18
|
+
|
|
19
|
+
- 最终产物必须给出可供父角色写入回执「测试」栏的精确证据：**命令 + exit code + 例数/文件数（或断言数）+ 路径**。
|
|
20
|
+
- 示例：`bash tests/t4/run.sh` exit=0 · 16/16 PASS · 日志路径 `tests/t4/…`。
|
|
21
|
+
- 没有证据的「完成 / 通过」视为未完成；父角色会据此打回，而不是转成回执。
|
|
22
|
+
|
|
23
|
+
## 四、边界
|
|
24
|
+
|
|
25
|
+
- 你这份注入指令只约束「怎么把结果交回父角色」；任务范围、验收口径、是否允许写入均以父角色本次派发的任务文本为准。
|
|
26
|
+
- 不新建任务状态源：nao 的唯一状态源是 `docs/tasks-state.md`，由 PM / 父角色维护，你不写它。
|
package/README.md
CHANGED
|
@@ -24,7 +24,7 @@ nao-skills 是一套 **角色卡 + 协作规矩 + 小工具**。装上以后，
|
|
|
24
24
|
|
|
25
25
|
```bash
|
|
26
26
|
cd 你的项目
|
|
27
|
-
pi install --local npm:@nathan33/nao-skill@0.18.
|
|
27
|
+
pi install --local npm:@nathan33/nao-skill@0.18.4 # 声明 pin + 把机制包物化到项目内 .pi/npm
|
|
28
28
|
npx @nathan33/nao-skill init # 写入转发 shim + 生成 AGENTS.md
|
|
29
29
|
```
|
|
30
30
|
|