@zhushanwen/pi-subagent-workflow 8.7.0 → 8.8.1

package/README.md

@@ -4,7 +4,7 @@ Pi 的 subagent + workflow 合并包：任务委派 + 多 agent 编排（chain /
 
 ## 内置 Agents
 
-按「读/写 × 视角」正交切分，9 个角色零重叠：
+按「读/写 × 视角」正交切分，10 个角色零重叠（C1 起随 `@zhushanwen/subagent-core` 的 `agents/` 资产分发，`<available_subagents>` 的 `<location>` 指向 core 包目录）：
 
 | Agent | 角色 | 读/写 |
 |-------|------|-------|
@@ -12,6 +12,7 @@ Pi 的 subagent + workflow 合并包：任务委派 + 多 agent 编排（chain /
 | `planner` | 复杂任务拆解为有序实施计划（合并需求澄清） | 只读产文档 |
 | `coder` | 代码实现、修改、测试（唯一改代码的角色） | 可改 |
 | `reviewer` | 代码审查与需求验收（含 git diff） | 只读 |
+| `doc-reviewer` | 文档审查（四遍方法论，事实锚点核实；spec / 设计文档） | 只读 |
 | `debugger` | 运行时故障诊断，钉根因 | 只读* |
 | `analyst` | 深度项目分析，产出给人读的报告 | 只读 |
 | `researcher` | 外部资料调研（依赖 tavily skill） | 只读 |
@@ -30,19 +31,12 @@ Pi 的 subagent + workflow 合并包：任务委派 + 多 agent 编排（chain /
 
 ## Orchestrator 协调器模式
 
-主 agent 禁用 bash / read / write / edit 等执行工具，只保留协调类工具，被迫作为纯协调器：拆解任务 → 委派 subagent → 汇总结果。orchestrator agent 自身也可递归委派子 orchestrator，实现分层任务拆解（深度受 `Depth: N/10` 护栏保护）。
+orchestrator 是纯协调器角色：拆解任务 → 委派 subagent → 汇总结果，自身不做执行类工作。orchestrator agent 自身也可递归委派子 orchestrator，实现分层任务拆解（深度受 `Depth: N/10` 护栏保护）。
 
-可用工具 5 个：`todo`、`goal_control`、`workflow`、`subagent`、`ask_user`（`ask_user` 由 `@zhushanwen/pi-ask-user` 提供，未安装时 orchestrator 遇歧义会明示停止而非猜测）。
-
-### 启动命令
+**工具约束变化（C1/D-5）**：内置模板不再携带 `tools:` frontmatter 白名单，subagent 不再以 `--tools` 白名单启动——工具约束回归宿主默认工具面，orchestrator 靠角色职责（职责边界段）约束自身只做协调。想要白名单的用户在 `<workspace>/.agents/agents/` 放同名 `.md` 覆写（project 级源稳定遮蔽内置，是唯一逃生门），或沿用 pi CLI 的 `--tools` 白名单（临时验证）：
 
 ```bash
-# 方式一：CLI 工具白名单（临时验证最快）
 pi --tools todo,goal_control,workflow,subagent,ask_user
-
-# 方式二：白名单 + 注入 orchestrator 的 system prompt（推荐，主进程也具备协调器视角）
-pi --tools todo,goal_control,workflow,subagent,ask_user \
-   --append-system-prompt "$(cat ~/.pi/agent/npm/node_modules/@zhushanwen/pi-subagent-workflow/agents/orchestrator.md)"
 ```
 
 > **依赖**：需先安装本包及相关扩展
@@ -59,7 +53,7 @@ pi --tools todo,goal_control,workflow,subagent,ask_user \
 
 ## Workflow 生命周期（one-shot）
 
-Workflow run 是一次性执行，状态机两态：`running → done`（`done` 唯一终态，reason 区分 completed / aborted / failed / budget_limited / time_limited）。`workflow` tool 仅 3 个 action：`run` / `status` / `abort`。
+Workflow run 是一次性执行，状态机两态：`running → done`（`done` 唯一终态，reason 区分 completed / aborted / failed / budget_limited / time_limited）。`workflow` tool 仅 3 个 action：`run` / `status` / `abort`。run 的 `name` 接受 `<available_workflows>` 列出的 workflow 名（内置 chain / parallel / map-reduce / scatter-gather / review-fix-loop 或已保存脚本）或 `.js` 绝对路径。
 
 Runs are one-shot: there is no pause/resume — to stop a run early use abort; for a fresh result start a new run.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "8.7.0",
+  "version": "8.8.1",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",
@@ -19,7 +19,6 @@
   },
   "files": [
     "index.ts",
-    "agents/",
     "skills/",
     "scripts/",
     "relay/",
@@ -51,24 +50,22 @@
     ],
     "skills": [
       "./skills"
-    ],
-    "agents": [
-      "./agents"
     ]
   },
   "dependencies": {
-    "@xyz-agent/session-delivery": "0.3.0",
-    "@zhushanwen/pi-extension-logger": "0.3.0",
-    "@xyz-agent/extension-protocol": "0.7.0",
-    "@zhushanwen/subagent-core": "0.2.0"
+    "@xyz-agent/extension-protocol": "0.8.1",
+    "@xyz-agent/session-delivery": "0.3.1",
+    "@zhushanwen/pi-ext-guards": "0.2.1",
+    "@zhushanwen/pi-extension-logger": "0.4.1",
+    "@zhushanwen/subagent-core": "0.5.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.4",
     "@earendil-works/pi-coding-agent": "^0.84.4",
     "@earendil-works/pi-tui": "^0.84.4",
     "typebox": "*",
-    "@zhushanwen/pi-pending-notifications": "0.5.0",
-    "@zhushanwen/pi-structured-output": "5.1.0"
+    "@zhushanwen/pi-pending-notifications": "0.5.3",
+    "@zhushanwen/pi-structured-output": "5.1.3"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {

package/skills/workflow-script-format/SKILL.md

@@ -39,13 +39,22 @@ This is enforced by `lintScript`:
 
 ## Required: Meta Declaration
 
-Every script MUST declare `meta` at the top level:
+Every script MUST declare its metadata as a `/* @pi-meta */` YAML block comment at the top level — NOT a `const meta` variable:
 
 ```javascript
-const meta = { name: 'workflow-name', description: '...', phases: ['phase1', 'phase2'] };
+/* @pi-meta
+name: workflow-name
+description: One-line description of what the workflow does
+phases: ['phase1', 'phase2']
+*/
 ```
 
-`name` must match the filename stem. `phases` is for display only.
+- `name` must match the filename stem. `phases` is for display only.
+- Optional fields: `parameters` (JSON Schema for `$ARGS`) and `usage` (markdown).
+- The YAML body starts on the line after `/* @pi-meta`; the closing `*/` must sit alone at column 0.
+- `generate` round-trip-validates the YAML and reports line/col on error (common pitfall: patternProperties regex must use double backslash `\\d`, not `\d`).
+
+> **Legacy `const meta = { ... }` (transition only):** `generate` still accepts a legacy top-level `const meta` during the transition window, but the core discovery chain does NOT recognize it (no legacy fallback) — such scripts stay invisible to discovery and get no metadata injection. Always use `/* @pi-meta */` for new scripts.
 
 ## [MANDATORY] Display: description + phase
 
@@ -59,11 +68,11 @@ TUI `/workflows` 视图按**运行时 `phase()` 调用**分组（非 `meta.phase
 ### Minimal 示例（三者齐备）
 
 ```javascript
-const meta = {
-  name: 'review-fix',
-  description: 'review then fix',
-  phases: ['review', 'fix'],
-};
+/* @pi-meta
+name: review-fix
+description: review then fix
+phases: ['review', 'fix']
+*/
 
 phase('review');
 const r = await agent({ prompt: 'review diff', description: 'review-diff' });
@@ -79,11 +88,17 @@ return { done: true };
 // ❌ agent() 无 description → TUI 显示 unnamed agent
 await agent({ prompt: 'review diff' });
 
-// ❌ meta.phases 用对象数组 → 引擎忽略，全部归入 (unnamed)
-const meta = { name: 'x', phases: [{ title: 'review' }, { title: 'fix' }] };
+// ❌ phases 用对象数组 → 引擎忽略，全部归入 (unnamed)
+/* @pi-meta
+name: x
+phases: [{ title: 'review' }, { title: 'fix' }]
+*/
 
 // ❌ 声明了 phases 但从不 phase() 调用 → 运行时分组失效
-const meta = { name: 'x', phases: ['review', 'fix'] };
+/* @pi-meta
+name: x
+phases: ['review', 'fix']
+*/
 // ... 直接 await agent(...) 从不调 phase('review') / phase('fix')
 ```
 
@@ -201,7 +216,7 @@ const results = await parallel(
 );
 ```
 
-> 内置通用编排 workflow（chain / parallel / scatter-gather / map-reduce，可直接 `workflow run`，用 `agent()` 自包含实现）见 `extensions/universal/subagent-workflow/workflows/`。本段教 `workflow()` 嵌套 API，workflows 目录是开箱即用的通用编排工具（用 `agent()` 而非 `workflow()` 嵌套）。
+> 内置通用编排 workflow（chain / parallel / scatter-gather / map-reduce / review-fix-loop，可直接 `workflow run`，用 `agent()` 自包含实现）见 `extensions/universal/subagent-workflow/workflows/`。本段教 `workflow()` 嵌套 API，workflows 目录是开箱即用的通用编排工具（用 `agent()` 而非 `workflow()` 嵌套）。
 
 ### Other globals
 
@@ -249,7 +264,11 @@ agent({ prompt: '...', description: 'review-business-logic' });
 ## Complete Example
 
 ```javascript
-const meta = { name: 'review-fix-loop', description: 'Loop: review → fix → commit until clean', phases: ['review-fix'] };
+/* @pi-meta
+name: review-fix-loop
+description: "Loop: review → fix → commit until clean"
+phases: ['review-fix']
+*/
 
 const MAX_ROUNDS = 10;
 let round = 0;

package/src/host/__tests__/pi-host.test.ts

@@ -12,7 +12,9 @@
 // mock 返回 {count: n} 形状直接验证「适配读 .count」；session-delivery mock
 // 验证 createDelivery 透传（参数 + 返回句柄）。
 
-import { join } from "node:path";
+import { join, dirname } from "node:path";
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
@@ -72,17 +74,36 @@ describe("createPiHostServices.discoveryRoots（与现推导逐项一致）", ()
     vi.mocked(getAgentDir).mockReturnValue(AGENT_DIR);
   }
 
-  it("agents 三根：顺序与 source 标签 = user-pi → npm → npm-dev", () => {
+  it("agents 四根：user-pi → npm → npm-dev → core 包父目录（C5⑥，source npm 追加末位）", () => {
     stubAgentDir();
     const roots = createPiHostServices().discoveryRoots?.().agents;
 
+    // 期望的 core 注入根用与 pi-host.ts 相同的锚点解析（./workflows/* 子入口在
+    // workspace 与 npm dist 双形态同径；探针证据见 probe-c5.md P1/P3）
+    const require = createRequire(import.meta.url);
+    const anchor = require.resolve("@zhushanwen/subagent-core/workflows/README.md");
+    const coreParent = dirname(dirname(dirname(anchor)));
+
     expect(roots).toEqual([
       { dir: join(AGENT_DIR, "agents"), source: "user-pi" },
       { dir: join(AGENT_DIR, "npm", "node_modules"), source: "npm" },
       { dir: join(AGENT_DIR, "extensions"), source: "npm-dev" },
+      // C5⑥：core 包一级父目录（npm 槽语义：一级子项 = 包目录，无 pi manifest 扫
+      // agents/ 约定目录）；追加在既有 npm 根之后——同标签靠后者胜（新版遮蔽旧残留）
+      { dir: coreParent, source: "npm" },
     ]);
   });
 
+  it("agents 第 4 根指向 core 包的父目录（其下 subagent-core/agents/ 存在 10 内置角色）", () => {
+    stubAgentDir();
+    const roots = createPiHostServices().discoveryRoots?.().agents;
+    const coreRoot = roots?.[3];
+
+    expect(coreRoot?.source).toBe("npm");
+    // 便捷断言：core 包根（注入 dir 的子目录）下 agents/ 真实存在
+    expect(existsSync(join(coreRoot!.dir, "subagent-core", "agents"))).toBe(true);
+  });
+
   it("workflows 三根：与 agents 同构，末级目录名切换为 workflows", () => {
     stubAgentDir();
     const roots = createPiHostServices().discoveryRoots?.().workflows;

package/src/host/pi-host.ts

@@ -16,7 +16,9 @@
 //     buildScanTargets、orchestration/skill-discovery.ts resolveSkillPath 的现推导
 //     逐项一致（user-pi / npm / npm-dev 字面即现 ResourceSource 标签）。
 //     project/workspace 根不在壳侧提供——core 消费方按 workspaceRoot 自行推导
-//     （u0-data-discovery 波次接注入消费）。
+//     （u0-data-discovery 波次接注入消费）。C5⑥ 起 agents kind 追加第 4 根：
+//     core 包一级父目录（source "npm"）——core agents/ 资产进 pi 发现面，见
+//     corePackageNpmRoot 注释。
 //   - countActiveFromEntries 适配：pi 侧真函数返回 CountActiveResult 对象，core
 //     端口契约是 number（core 消费面只读 .count，notify-ports.ts 契约注释）——
 //     foundation 单元登记给本单元的适配责任。
@@ -25,23 +27,63 @@
 //     是结构超集成员，多不碍兼容）——结构兼容由本注入点 typecheck 守护，上游签名
 //     漂移即红（notify-ports.ts「闭包红线」段）。
 
-import { join } from "node:path";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
 
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 import { countActiveFromEntries } from "@zhushanwen/pi-pending-notifications";
 import { createDelivery } from "@xyz-agent/session-delivery";
 
-import type { DiscoveryRoot, HostServices } from "@zhushanwen/subagent-core/core/host-services.ts";
-import type { LogLevel } from "@zhushanwen/subagent-core/core/logger.ts";
-import type { NotifyDomainPorts } from "@zhushanwen/subagent-core/core/notify-ports.ts";
+import type { DiscoveryRoot, HostServices } from "@zhushanwen/subagent-core";
+import type { LogLevel } from "@zhushanwen/subagent-core";
+import type { NotifyDomainPorts } from "@zhushanwen/subagent-core";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
+
+/**
+ * core 包（@zhushanwen/subagent-core）agents/ 资产进 pi 发现面的注入根（C5⑥，
+ * convergence §5.4 检查点 2；探针证据 docs/design/subagent-core-convergence.probe-c5.md）。
+ *
+ * 解析锚点 = `@zhushanwen/subagent-core/workflows/README.md`：`./workflows/*` 子入口
+ * 在 workspace TS 直引与 npm dist 两种发布形态下同径（publishConfig 保留该子入口），
+ * README.md 是两形态都必在的资产文件。core 包根 = 锚点上两级；npm 槽注入其一级
+ * 父目录——npm 槽语义：dir 下一级子项 = 包目录，core 无 pi manifest → 扫 agents/
+ * 约定目录命中 10 内置角色。
+ *
+ * 布局覆盖（探针 P2-P5 实测）：dev workspace（core 在仓库 packages/ 下）与发布态
+ * 嵌套布局（core 在本包 node_modules 内）下这是唯一命中通路；发布态平铺布局
+ * （core 与本包同层）下既有 npm 根已命中，本注入是幂等兜底（重复发现被 core
+ * realpath 去重吸收）。
+ *
+ * 每次调用现解析（不 memo）：发现调用点稀疏（session_start + 缓存 miss），解析
+ * 成本可忽略；失败（异常布局/解析器不可用）降级为不注入并 warn——绝不因资产
+ * 接线失败阻断发现主链。
+ */
+function corePackageNpmRoot(): string | undefined {
+  try {
+    // createRequire 锚定本模块（jiti 加载器下 import.meta.url 可用；不可用则随
+    // catch 降级）。require.resolve 沿 pi-sw 自身的依赖解析链——workspace 与发布态
+    // 都从本包出发命中 core。
+    const require = createRequire(import.meta.url);
+    const anchor = require.resolve("@zhushanwen/subagent-core/workflows/README.md");
+    return dirname(dirname(dirname(anchor)));
+  } catch (err) {
+    // getLogger 惰性调用（catch 是冷路径——测试环境对 pi-extension-logger 的
+    // module-level mock 可能返回 undefined，模块级持有会在 import 期踩 undefined）
+    getLogger("pi-host").warn(
+      "[pi-host] core 包 agents/ 注入根解析失败——10 内置角色可能不可发现",
+      { reason: toErrorMessage(err) },
+    );
+    return undefined;
+  }
+}
 
 /** agents/workflows 共享的 agentDir 派生根（末级目录名由 kind 决定）。
  *  顺序与 source 标签逐项对齐 resource-discovery.ts buildScanTargets 的
  *  user-pi → npm → npm-dev 段（根列表按优先级低→高排列，D2 语义边界）。 */
 function agentDirKindRoots(kind: "agents" | "workflows"): DiscoveryRoot[] {
   const agentDir = getAgentDir();
-  return [
+  const roots: DiscoveryRoot[] = [
     // 1. user .pi/agent/<kind>/
     { dir: join(agentDir, kind), source: "user-pi" },
     // 2. npm global: agentDir/npm/node_modules/*/<pkg>/
@@ -49,6 +91,19 @@ function agentDirKindRoots(kind: "agents" | "workflows"): DiscoveryRoot[] {
     // 3. npm dev symlink: agentDir/extensions/*/<pkg>/
     { dir: join(agentDir, "extensions"), source: "npm-dev" },
   ];
+  // 4. core 包根（C5⑥，仅 agents kind）：追加在既有 npm 根之后——同标签多根依注入
+  //    序扫描 + last-writer-wins，core（随本包依赖分发的新模板）遮蔽同 agentDir 内
+  //    旧版残留副本；序位仍在 user 级之上、npm-dev/project 级之下（红线 1）。
+  //    workflows kind 刻意不注入：<available_workflows> 的 <location> 是 CA2 快照
+  //    不豁免面（红线 8 豁免仅限 10 内置 agent 角色路径前缀），注入会翻转内置
+  //    workflow 的胜出路径。
+  if (kind === "agents") {
+    const coreNpmRoot = corePackageNpmRoot();
+    if (coreNpmRoot !== undefined) {
+      roots.push({ dir: coreNpmRoot, source: "npm" });
+    }
+  }
+  return roots;
 }
 
 /** skills 的 agentDir 派生根。对齐 skill-discovery.ts resolveSkillPath 的两处