@ghyper9023/pi-dev-workflow 0.6.3 → 0.8.0

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@ghyper9023/pi-dev-workflow",
-  "version": "0.6.3",
+  "version": "0.8.0",
   "keywords": [
     "pi-package"
   ],
-  "description": "Developer workflow toolkit for pi: git agents, code review, Karpathy guidelines, themes",
+  "description": "Developer workflow toolkit for pi: git commands, code review, Karpathy guidelines, themes",
   "homepage": "https://github.com/cherish-ltt/pi-dev-workflow#readme",
   "bugs": {
     "url": "https://github.com/cherish-ltt/pi-dev-workflow/issues"

package/prompts/APPEND_SYSTEM.md

@@ -1,59 +1,73 @@
-# 必须严格遵守 - 全局适用
-
-## 一、职责定义
-
-- **技术准确优先于迎合用户信念**。专注事实和解决问题，提供直接、客观的技术信息，避免不必要的夸张、赞美或情感认同。
-- 避免过度认同（如“你说得完全对”）。
-- **绝不给出时间预估**（不说“几分钟”“大约5分钟”“2-3周，我们以后在做”等）。
-- **默认不使用 emoji**，除非用户明确要求。
-- 输出在命令行显示，回答应**简短精炼**。
-
-## 二、核心行为约束
-
-### 1. 不要多管闲事
-- 不添加未要求的功能、不重构、不做“改进”。修复一个 bug 不需要清理周边代码。
-
-### 2. 不要过度设计
-- 不为不可能发生的场景添加错误处理、回退或校验。信任内部代码和框架保证。只在系统边界（用户输入、外部API）校验。
-
-### 3. 不要提前抽象
-- 不为一次性操作创建 helper、utility 或抽象层。不为假想的未来需求设计。**三行重复代码也好过一个过早出现的抽象**。
-
-### 4. 不要乱建文件
-- 除非绝对必要，**不创建新文件**。始终优先修改现有文件。
-- **绝不主动创建文档文件（\*.md）或 README**。
-
-### 5. 不改没读过的代码
-- 绝不提议修改没读过的代码。必须先阅读和理解再修改。
-
-### 6. 默认不写注释
-- 只在“为什么这样做”不显然时写注释（隐藏约束、微妙不变量、特定 bug 规避）。
-- 不解释代码“做了什么”——用良好命名的标识符表达。
-- 不在注释里引用当前任务、修复内容或调用方。
-- 不删除现有注释，除非删除其描述的代码。
-
-### 7. 如实汇报，不粉饰
-- 测试失败就说失败，带上相关输出。
-- 若未运行验证步骤，明确说明，不暗示成功。
-- 输出显示失败时，绝不声称“所有测试通过”。
-- 不压制或简化失败检查来制造表面绿色。
-- 不把未完成或损坏的工作说成已完成。
-
-## 三、动态语言配置
-
-- **始终使用用户(user-prompt)的语言回复**。所有解释、注释、与用户的交流都使用该语言。
-- 技术术语和代码标识符保持原样。
-- 未能清楚了解到用户(user-prompt)的语言时，默认使用简体中文+英文专业名词
-
-## 四、task完成
-
-- 默认情况下，使用简洁的语言总结任务
-- 如果用户有具体的要求，在任务完后按用户要求输出内容
-- 在完成task后绝不主动commit或push，但可以在任务总结末尾提醒用户(非处于子代理时)：
-    1. review刚才的改动(输入/skill:review-html或1)
-    2. 提交commit，自动message(输入/git-commit或2)
-    3. 提交commit，自动message，并push(输入/git-commit-push或3)
-
-## 五、核心理念
-
-> **高效达成请求结果，不过度工程。无范围蔓延。只实现直接要求的内容。无假想设计，无必要抽象，默认无注释。不为不可能条件加校验。无时间预估。无 emoji。无过度认同。准确、客观、简洁。始终牢记自己的身份和职责。**
+## Global Agent Rules
+
+### Language
+默认用简体中文回复；用户明确指定其他语种时再切换语言。
+默认不使用 emoji，除非用户明确要求。
+回答应简短精炼且足够说明情况。
+
+### 思考过程
+**严格遵循：**审题 → 思考 → 汇总 → 验证 → 讨教 → 最终：
+1.审题：独立且清晰的确认用户意图，用自己的话重述你认为用户的目标是什么，以及用户试图解决的问题是什么。
+2.思考：独立的探索真实数据，分析事情(真实代码/数据/文档/现状)的实际价值。
+3.汇总：整合分析结果，区分事实、推断、假设；聚焦真正影响结果的关键因素。
+4.验证：假设当前正是用户目标完成时候的状态，但用户表示不满意，深入分析哪里没有做到位，把方案补全。
+5.讨教：遇到不确定、专业、时效性或陌生问题时，主动检索网络、官方文档、知识库、成熟案例，进行外部校验。
+6.最终：完成以上流程后再作答；**先结论，后依据**，优先给出最小闭环、可执行方案。明确不确定性，禁止编造。
+
+### Working Style
+像高绩效资深工程师一样工作：直接、克制、执行优先。
+技术准确优先于迎合用户信念。专注事实和解决问题，提供直接、客观的技术信息，避免不必要的夸张、赞美或情感认同。
+绝不给出时间预估，例如“几分钟”“大约 5 分钟”“2-3 周”“下次”等。
+先给结论或结果，再补必要上下文。
+能合理假设就继续，不为低风险细节反复确认。
+不加无关功能，不做顺手重构，不给泛泛建议代替落地执行。
+优先选择简单、可维护、可上线的方案。
+不添加未要求的功能、不重构、不做“改进”。修复一个 bug 不需要清理周边代码。
+不提前抽象：不为一次性操作创建 helper、utility 或抽象层，不为假想的未来需求设计。
+
+### Coding Standards
+写低复杂度代码，保证易读、易调试、易修改。
+避免过度设计、重抽象、额外分层、大依赖、炫技写法和隐式行为。
+保持 API 小而清晰，行为显式，命名明确，控制流平坦，优先早返回。
+默认不写注释。只在“为什么这样做”不显然时写注释，例如隐藏约束、微妙不变量、特定 bug 规避。
+注释只解释意图、边界和取舍，不复述代码字面意思。
+不在注释里引用当前任务、修复内容或调用方。
+不删除现有注释，除非删除其描述的代码。
+
+### Debug Policy
+先追根因，不做只压症状的补丁。
+让错误显式暴露；不要靠静默兜底、伪成功、吞异常或隐藏默认值掩盖问题。
+如果问题来自重复逻辑、双重真值、共享状态或跨模块行为，按结构性问题处理，不叠补丁。
+如实汇报，不粉饰。
+测试失败就说失败，带上相关输出。
+若未运行验证步骤，明确说明，不暗示成功。
+输出显示失败时，绝不声称“所有测试通过”。
+不压制或简化失败检查来制造表面绿色。
+不把未完成或损坏的工作说成已完成。
+
+### Execution Rules
+多步任务在调用工具前，先用 1 到 2 句说明要做什么和第一步。
+先读相关文件和真实上下文，再修改。
+绝不提议修改没读过的代码。必须先阅读和理解再修改。
+改动保持最小闭环，但该删的死代码、冗余分支和重复逻辑要一起清掉。
+有匹配的 skill 就先读 `SKILL.md` 并按它执行。
+任务完成后默认用简洁语言总结任务；如果用户有具体要求，按用户要求输出。
+任务完成后绝不主动 commit 或 push。但可在任务总结末尾提醒用户：是否需要帮忙提交/push等操作。
+任何 Git 操作都使用标准规范执行。
+git commit 操作保持分批提交，避免一次性提交过多代码或多个任务内容合并在一个内提交。
+
+### Validation
+改完先做最相关的验证：优先针对性测试，再类型 /lint/build，最后最小冒烟。
+能跑就跑；不能跑就明确说明原因，不把静态阅读包装成运行时验证。
+查看项目中的CI,`.pre-commit-check.yaml`等内容(如有)，完成相关验证。
+
+### Stop Rule
+每完成一个关键步骤就判断一次：是否已经能基于足够证据回答用户的核心请求。
+如果可以，就停止，不继续为了 “更完整” 而扩写或过度搜索。
+
+### 核心理念
+高效达成请求结果，不过度工程。无范围蔓延。只实现直接要求的内容。无假想设计，无必要抽象，默认无注释。不为不可能条件加校验。无时间预估。无 emoji。无过度认同。准确、客观、简洁。始终牢记自己的身份和职责。
+
+**除用户明确要求执行特定操作外，默认严格遵循以上规范，在最终返回前确认已经遵守了[思考过程]的完整流程:审题->思考->汇总->验证->讨教->最终**
+**除用户明确要求执行特定操作外，默认严格遵循以上规范，在最终返回前确认已经遵守了[思考过程]的完整流程:审题->思考->汇总->验证->讨教->最终**
+**除用户明确要求执行特定操作外，默认严格遵循以上规范，在最终返回前确认已经遵守了[思考过程]的完整流程:审题->思考->汇总->验证->讨教->最终**

package/skills/review-html/SKILL.md

@@ -10,7 +10,7 @@ description: review 代码并输出交互式 HTML 报告。适用于代码审查
 
 ## 硬性输出要求
 
-**不要输出任何 Markdown 格式（包括代码块标记 ` ```html ` 等）**  
+**不要输出任何 Markdown 格式（包括代码块标记 ` ```html ` 等）**
 **直接从 `<!DOCTYPE html>` 开始输出一个完整的、自包含的 HTML 文档。**
 **使用中文+英文专业名词**
 

package/tests/test-no-subagents.mjs

@@ -0,0 +1,264 @@
+/**
+ * test-no-subagents.mjs — 结构性回归断言
+ *
+ * Run: node tests/test-no-subagents.mjs
+ *
+ * 覆盖：
+ *   1. 子代理基础设施已删除
+ *   2. dev 命令：4 个命令、参数即任务、意图识别复用 pre-check、不再绑定 Grill/PRD
+ *   3. 自动审查检测独立为 review-detect.ts
+ *   4. git 命令直接执行，不再委派给子代理
+ *   5. /grill 与 /prd 是独立命令
+ *   6. UI 组件与输出目录约定
+ *   7. /dev-pre-check 意图校验（confirmIntent 为共享实现）
+ *   8. notify 调用使用合法类型（info / warning / error）
+ *   9. 当前版本的 RELEASE 说明覆盖该版本区间内的全部 commit
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, "..");
+
+// ── Helpers ──────────────────────────────────────────────────
+
+let pass = 0;
+let fail = 0;
+
+function assert(condition, msg) {
+	if (condition) {
+		pass++;
+		console.log(`  ✅ ${msg}`);
+	} else {
+		fail++;
+		console.error(`  ❌ ${msg}`);
+	}
+}
+
+function assertNotExists(rel, msg) {
+	assert(!fs.existsSync(path.resolve(ROOT, rel)), msg);
+}
+
+function assertExists(rel, msg) {
+	assert(fs.existsSync(path.resolve(ROOT, rel)), msg);
+}
+
+function assertIncludes(rel, substr, msg) {
+	const src = fs.readFileSync(path.resolve(ROOT, rel), "utf-8");
+	assert(src.includes(substr), msg);
+}
+
+function assertNotIncludes(rel, substr, msg) {
+	const src = fs.readFileSync(path.resolve(ROOT, rel), "utf-8");
+	assert(!src.includes(substr), msg);
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  1. 子代理基础设施已删除
+// ═══════════════════════════════════════════════════════════════
+
+console.log("📋 子代理基础设施\n");
+
+assertNotExists("extensions/sub-agents.ts", "extensions/sub-agents.ts 已删除");
+assertNotExists("extensions/workflow-engine.ts", "extensions/workflow-engine.ts 已删除");
+assertExists("extensions/session-utils.ts", "extensions/session-utils.ts 提供共享的等待/会话工具");
+assertNotExists("agents/", "agents/ 目录已删除");
+assertNotExists(".doc/AGENT-FRONTMATTER-REFERENCE.md", "AGENT-FRONTMATTER-REFERENCE.md 已删除");
+
+// ═══════════════════════════════════════════════════════════════
+//  2. dev 命令：4 个命令，参数即任务，意图识别复用 pre-check
+// ═══════════════════════════════════════════════════════════════
+
+console.log("\n📋 dev-prompts.ts\n");
+
+assertNotIncludes("extensions/dev-prompts.ts", "./sub-agents", "不再引入 sub-agents");
+assertNotIncludes("extensions/dev-prompts.ts", "./workflow-engine", "不再引入 workflow-engine");
+assertNotIncludes("extensions/dev-prompts.ts", "./grill-me-agent", "不再绑定 Grill/PRD 运行时");
+assertNotIncludes("extensions/dev-prompts.ts", "runGrillPhase", "不再触发 Grill 追问");
+assertNotIncludes("extensions/dev-prompts.ts", "runPRDPhase", "不再触发 PRD 生成");
+assertNotIncludes("extensions/dev-prompts.ts", "WizardQuestion", "向导式提问已移除");
+assertIncludes("extensions/dev-prompts.ts", 'import { confirmIntent } from "./pre-check"', "意图识别复用 pre-check");
+assertIncludes("extensions/dev-prompts.ts", "uiTaskArg(ctx, args", "任务原文来自命令参数，缺省才弹输入框");
+assertIncludes("extensions/dev-prompts.ts", "detectProjectDefaults", "默认验收标准来自项目探测");
+assertIncludes("extensions/dev-prompts.ts", "defaultAcceptanceItems", "默认验收标准按条目生成");
+assertIncludes("extensions/dev-prompts.ts", "## 身份与职责", "提示词包含身份与职责段");
+assertIncludes("extensions/dev-prompts.ts", "## 已确认的任务意图", "提示词携带已确认的意图");
+assertIncludes("extensions/dev-prompts.ts", "## 验收标准", "提示词包含默认验收标准段");
+assertIncludes("extensions/dev-prompts.ts", "pi.sendUserMessage(prompt", "组装后的提示词直接发送给当前代理");
+
+for (const cmd of ["dev-feat", "dev-fix", "dev-refactor", "dev-test"]) {
+	assertIncludes("extensions/dev-prompts.ts", `registerDev(pi, "${cmd}"`, `注册 /${cmd}`);
+}
+
+for (const cmd of ["dev-doc", "dev-perf", "dev-style", "dev-security", "dev-chore", "dev-explain", "dev-compare"]) {
+	assertNotIncludes("extensions/dev-prompts.ts", `"${cmd}"`, `/${cmd} 已移除`);
+}
+
+// ═══════════════════════════════════════════════════════════════
+//  3. 自动审查检测独立为 review-detect.ts
+// ═══════════════════════════════════════════════════════════════
+
+console.log("\n📋 review-detect.ts\n");
+
+assertExists("extensions/review-detect.ts", "自动审查检测独立成扩展");
+assertNotIncludes("extensions/review-detect.ts", "./sub-agents", "不再引入 sub-agents");
+assertIncludes("extensions/review-detect.ts", 'pi.on("input"', "拦截带审查意图的输入");
+assertIncludes("extensions/review-detect.ts", 'event.source === "extension"', "过滤扩展注入消息，防止递归");
+assertIncludes("extensions/review-detect.ts", "expandPromptTemplates: true", "skill 命令展开执行");
+assertIncludes("extensions/review-detect.ts", '"pi-review"', "自动审查仍查找 pi-review/ 输出目录");
+
+// ═══════════════════════════════════════════════════════════════
+//  4. Git 命令直接执行，不再委派给子代理
+// ═══════════════════════════════════════════════════════════════
+
+console.log("\n📋 git-commands.ts\n");
+
+assertNotIncludes("extensions/git-commands.ts", "./sub-agents", "不再引入 sub-agents");
+assertNotIncludes("extensions/git-commands.ts", "spawnSubagent", "不再 spawn 子进程");
+assertIncludes("extensions/git-commands.ts", "分批提交", "空消息时交由主代理分批提交");
+assertIncludes("extensions/git-commands.ts", "pi.exec(\"git\"", "通过 pi.exec 直接执行 git");
+assertIncludes("extensions/git-commands.ts", "git-commit", "保留 /git-commit 命令");
+assertIncludes("extensions/git-commands.ts", "git-push", "保留 /git-push 命令");
+assertIncludes("extensions/git-commands.ts", "git-commit-push", "保留 /git-commit-push 命令");
+
+// ═══════════════════════════════════════════════════════════════
+//  5. Grill / PRD 是独立命令，运行在当前代理中
+// ═══════════════════════════════════════════════════════════════
+
+console.log("\n📋 grill-me-agent.ts\n");
+
+assertNotIncludes("extensions/grill-me-agent.ts", "./sub-agents", "不再引入 sub-agents");
+assertNotIncludes("extensions/grill-me-agent.ts", "spawnSubagent", "不再 spawn 子进程");
+assertNotIncludes("extensions/grill-me-agent.ts", "recoverFromBackup", "断点恢复随向导一并移除");
+assertIncludes("extensions/grill-me-agent.ts", 'registerCommand("grill"', "注册独立 /grill 命令");
+assertIncludes("extensions/grill-me-agent.ts", 'registerCommand("prd"', "注册独立 /prd 命令");
+assertIncludes("extensions/grill-me-agent.ts", "pollFor", "轮询等待当前代理产物后读取结果");
+assertIncludes("extensions/grill-me-agent.ts", "GRILL_ANSWERS_DIRNAME = \"answers\"", "保留 answers 子目录");
+assertIncludes("extensions/grill-me-agent.ts", "GRILL_QUESTIONS_DIRNAME = \"questions\"", "保留 questions 子目录");
+
+// ═══════════════════════════════════════════════════════════════
+//  6. UI 组件与输出目录约定
+// ═══════════════════════════════════════════════════════════════
+
+console.log("\n📋 输出目录与 UI 组件\n");
+
+const reviewSkill = fs.readFileSync(path.resolve(ROOT, "skills/review-html/SKILL.md"), "utf-8");
+assert(reviewSkill.includes(".pi-dev-output/pi-review/html/"), "review-html 仍写入 pi-review/html/");
+
+assertIncludes("extensions/session-utils.ts", "detectProjectDefaults", "项目探测（语言/测试/lint/pre-commit/CI）");
+assertIncludes("extensions/session-utils.ts", "defaultAcceptanceItems", "生成默认验收标准条目");
+assertIncludes("extensions/ui-helpers.ts", "export function uiSelect", "保留 uiSelect");
+assertIncludes("extensions/ui-helpers.ts", "export function uiConfirm", "保留 uiConfirm");
+assertIncludes("extensions/ui-helpers.ts", "export function uiInput", "保留 uiInput");
+assertIncludes("extensions/ui-helpers.ts", "export async function uiTaskArg", "命令参数与输入框二选一取任务文本");
+assertNotIncludes("extensions/ui-helpers.ts", "updateWorkflowWidget", "移除工作流 widget");
+assertNotIncludes("extensions/ui-helpers.ts", "sendWorkflowResult", "移除工作流结果消息");
+assertNotIncludes("extensions/ui-helpers.ts", "WorkflowStepWidgetState", "移除工作流状态类型");
+
+// ═══════════════════════════════════════════════════════════════
+//  7. /dev-pre-check 独立意图校验扩展
+// ═══════════════════════════════════════════════════════════════
+
+console.log("\n📋 pre-check.ts\n");
+
+assertExists("extensions/pre-check.ts", "提供独立的 pre-check 扩展");
+assertIncludes("extensions/pre-check.ts", 'registerCommand("dev-pre-check"', "注册 /dev-pre-check 命令");
+assertIncludes("extensions/pre-check.ts", "export async function confirmIntent", "导出共享的意图确认循环");
+assertIncludes("extensions/pre-check.ts", "用自己的话重述你认为用户的目标是什么，以及用户试图解决的问题是什么", "固定指令：用自己的话重述目标与问题");
+assertIncludes("extensions/pre-check.ts", "[pre-check] 任务意图校验：只复述，不执行", "意图校验提示词声明只复述不执行");
+assertIncludes("extensions/pre-check.ts", "禁止修改、创建、删除任何文件", "约束禁止任何实质改动");
+assertIncludes("extensions/pre-check.ts", "pi.sendUserMessage(buildExecutionPrompt", "确认通过后才发送执行提示词");
+assertIncludes("extensions/pre-check.ts", "buildExecutionPrompt(originalPrompt: string, intent: string)", "执行提示词携带已确认的意图复述");
+assertIncludes("extensions/pre-check.ts", "ctx.isIdle()", "以代理空闲作为复述完成信号之一");
+assertIncludes("extensions/pre-check.ts", "pollFor", "轮询等待复述产物");
+assertNotIncludes("extensions/pre-check.ts", "./dev-prompts", "不依赖 /dev-* 命令实现");
+assertNotIncludes("extensions/pre-check.ts", "./grill-me-agent", "不依赖 Grill/PRD 运行时");
+assertNotIncludes("extensions/dev-prompts.ts", "dev-pre-check", "dev-prompts 不注册覆盖 pre-check 的命令");
+
+// ═══════════════════════════════════════════════════════════════
+//  8. notify 调用使用合法类型
+// ═══════════════════════════════════════════════════════════════
+
+console.log("\n📋 notify 类型\n");
+
+const NOTIFY_TYPES = ["info", "warning", "error"];
+const badNotify = [];
+for (const file of fs.readdirSync(path.resolve(ROOT, "extensions"))) {
+	if (!file.endsWith(".ts")) continue;
+	const lines = fs.readFileSync(path.resolve(ROOT, "extensions", file), "utf-8").split("\n");
+	for (const line of lines) {
+		const matched = line.match(/\.notify\(.*,\s*"([^"]+)"\s*\)/);
+		if (matched && !NOTIFY_TYPES.includes(matched[1])) badNotify.push(`${file} → ${matched[1]}`);
+	}
+}
+assert(
+	badNotify.length === 0,
+	badNotify.length === 0 ? "所有 notify 调用使用合法类型（info / warning / error）" : `非法 notify 类型: ${badNotify.join(", ")}`,
+);
+
+// ═══════════════════════════════════════════════════════════════
+//  9. 版本说明覆盖该版本全部 commit
+// ═══════════════════════════════════════════════════════════════
+
+console.log("\n📋 版本说明\n");
+
+function git(args) {
+	return execFileSync("git", args, { cwd: ROOT, encoding: "utf-8" }).trim();
+}
+
+const version = JSON.parse(fs.readFileSync(path.resolve(ROOT, "package.json"), "utf-8")).version;
+const releaseDoc = `.version/RELEASE-v${version}.md`;
+assertExists(releaseDoc, `存在 ${releaseDoc}`);
+
+const docText = fs.readFileSync(path.resolve(ROOT, releaseDoc), "utf-8");
+const listed = docText
+	.split("\n")
+	.map((line) => line.match(/^[0-9a-f]{7,40}\b/)?.[0])
+	.filter(Boolean);
+assert(listed.length > 0, "Commit History 至少列出一条 commit");
+
+const unknown = listed.filter((h) => {
+	try {
+		git(["rev-parse", "--verify", "--quiet", `${h}^{commit}`]);
+		return false;
+	} catch {
+		return true;
+	}
+});
+assert(unknown.length === 0, `列出的 commit 都真实存在（${unknown.join(", ") || "无缺失"}）`);
+
+// 以文档中最新的一条 commit 作为覆盖终点，避免把后续版本的提交算进本版本
+const tip = listed.reduce((a, b) =>
+	Number(git(["rev-list", "--count", a])) >= Number(git(["rev-list", "--count", b])) ? a : b,
+);
+const prevTag = git(["tag", "--merged", tip, "--sort=-v:refname"])
+	.split("\n")
+	.find((tag) => tag && tag !== `v${version}`);
+assert(Boolean(prevTag), `找到上一版本 tag（${prevTag}）`);
+
+const range = git(["log", "--format=%h", `${prevTag}..${tip}`]).split("\n").filter(Boolean);
+const missing = range.filter((h) => !listed.some((l) => h.startsWith(l) || l.startsWith(h)));
+assert(
+	missing.length === 0,
+	missing.length === 0
+		? `${releaseDoc} 覆盖 ${prevTag}..${tip} 全部 ${range.length} 个 commit`
+		: `${releaseDoc} 缺少 ${missing.length} 个 commit: ${missing.join(", ")}`,
+);
+
+// ═══════════════════════════════════════════════════════════════
+//  Summary
+// ═══════════════════════════════════════════════════════════════
+
+console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+console.log(`结果: ${pass} 通过, ${fail} 失败, 共 ${pass + fail} 个测试`);
+console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+
+if (fail > 0) {
+	console.error("\n⚠️  部分测试未通过");
+	process.exit(1);
+} else {
+	console.log("\n✅ 所有测试通过");
+}

package/.doc/AGENT-FRONTMATTER-REFERENCE.md

@@ -1,198 +0,0 @@
-# Agent Frontmatter 配置参考
-
-所有子代理的行为通过其 `.md` 文件的 YAML frontmatter 配置。  
-每个字段对应 `spawnSubagent()` 构造的 pi CLI 参数。
-
----
-
-## 完整字段一览
-
-```yaml
----
-name: <string>            # 必填 — agent 标识名
-description: <string>     # 必填 — agent 描述
-tools: <csv>              # 工具白名单（逗号分隔）
-thinking: <string>        # 推理等级
-session: <boolean>        # 是否保存 session
-session-dir: <string>     # session 存储目录（默认 .pi-dev-output/pi-subagent-sessions/）
-no-context: <boolean>     # 是否跳过 AGENTS.md/CLAUDE.md
-no-extensions: <boolean>  # 是否禁用扩展加载
-mode: <string>            # 输出模式
-extra-args: <string>      # 额外 CLI 参数（空格分隔）
----
-```
-
----
-
-## 字段详解
-
-### `name` — Agent 标识名
-
-- **必填** ✓
-- **类型**: `string`
-- **作用**: 作为 `subagent` tool 的 `agent` 参数值、日志标识、session 文件名前缀
-- **示例**: `planner`, `git-agent`, `review-agent`
-
-### `description` — Agent 描述
-
-- **必填** ✓
-- **类型**: `string`
-- **作用**: 在工具描述中展示，帮助 LLM 理解该 agent 的用途
-
-### `tools` — 工具白名单
-
-- **类型**: 逗号分隔的字符串
-- **作用**: 对应 `--tools` CLI 参数
-- **参数范围**: pi 内置工具名（可用 `pi --help` 查看），如 `read`, `bash`, `write`, `find`, `ls`, `grep`, `edit` 等
-- **默认值**: 不传 `--tools` 则所有内置工具可用
-- **示例**: `tools: read, bash, write, find, ls, grep`
-
-### `thinking` — 推理等级
-
-- **类型**: 字符串
-- **作用**: 对应 `--thinking` CLI 参数
-- **参数范围**:
-
-| 值 | 说明 | 延迟影响 | Token 影响 |
-|----|------|---------|-----------|
-| `off` | 关闭推理（纯执行） | 基准 | 基准 |
-| `low` | 少量推理 | +20~40% | +30~50% |
-| `medium` | 中等推理 | +50~100% | +50~80% |
-| `high` | 深度推理 | +100~300% | +100~200% |
-| `xhigh` | 极限推理 | +200~500% | +200~400% |
-
-- **建议**:
-  - `off` — git 操作、按计划写代码、机械精简
-  - `low` — 计划制定、代码审查、设计评审、PRD 编写
-  - `medium` — 复杂架构分析、跨模块重构
-  - `high` — 安全审计、深层 Bug 追踪
-  - `xhigh` — 极其复杂的跨领域分析
-
-### `session` — Session 持久化
-
-- **类型**: 布尔值
-- **作用**: 对应 `--no-session` / `--session` CLI 参数
-- **参数范围**: `true` | `false`
-- **`false`** (默认): 子代理运行结束后不保留交互记录，性能最优
-- **`true`**: 保存完整交互记录，便于调试/查看子代理的思考过程
-
-当 `session: true` 时：
-  - 自动生成 session 名: `{ISO时间戳}_{agent名称}`
-  - 默认存储路径: `.pi-dev-output/pi-subagent-sessions/`
-  - 可通过 `session-dir` 自定义路径
-
-### `session-dir` — Session 存储目录
-
-- **类型**: 字符串（路径）
-- **作用**: 对应 `--session-dir` CLI 参数
-- **仅在 `session: true` 时生效**
-- **默认值**: `.pi-dev-output/pi-subagent-sessions/`
-- **示例**: `session-dir: /tmp/my-sessions`
-
-### `no-context` — 项目上下文文件
-
-- **类型**: 布尔值
-- **作用**: 对应 `-nc` CLI 参数
-- **参数范围**: `true` | `false`
-
-| 值 | 行为 | 适用场景 |
-|----|------|---------|
-| `true` (默认) | 跳过 AGENTS.md / CLAUDE.md | git 操作、纯执行场景 |
-| `false` | 加载 AGENTS.md / CLAUDE.md | 需要项目上下文的 agent（架构分析、代码审查） |
-
-### `no-extensions` — 扩展加载
-
-- **类型**: 布尔值
-- **作用**: 对应 `-ne` CLI 参数
-- **参数范围**: `true` | `false`
-
-| 值 | 行为 | 适用场景 |
-|----|------|---------|
-| `true` (默认) | 禁用所有扩展，启动更快 | git 操作（仅需 bash） |
-| `false` | 加载扩展（MCP 工具、Skill 文件等） | 需要 MCP/Skill 的 agent（计划、审查、文档） |
-
-### `mode` — 输出模式
-
-- **类型**: 字符串
-- **作用**: 对应 `--mode` CLI 参数
-- **参数范围**: `json` | `text`
-
-| 值 | 行为 | 适用场景 |
-|----|------|---------|
-| `json` (默认) | JSON 结构化输出，workflow-engine 可解析 | 工作流 agent（planner/worker/reviewer/trimmer/docWriter） |
-| `text` | 自然文本输出 | LLM 直接调用的场景 |
-
-**注意**: 工作流引擎依赖 `extractFinalOutput()` 解析 JSON 输出，工作流 agent 必须使用 `mode: json`。
-
-### `extra-args` — 额外 CLI 参数
-
-- **类型**: 字符串（空格分隔多个参数）
-- **作用**: 在所有标准参数之后追加，优先级最高
-- **用途**: 传递 pi CLI 的其他参数，如 `--verbose`, `--color always`, `--max-tokens 4096` 等
-- **示例**: `extra-args: --verbose --max-tokens 4096`
-
----
-
-## 原始 CLI 参数映射表
-
-以下是对应关系：**原始硬编码参数 → 配置位置**
-
-| 原始参数 | 含义 | 配置方式 |
-|---------|------|---------|
-| `-p` | 非交互模式 | **始终启用**，不可配置 |
-| `--no-session` | 不保存会话 | frontmatter `session: false` 或 `argsOverride.session = false` |
-| `-nc` | 禁用上下文文件 | frontmatter `no-context: true` 或 `argsOverride.noContext = true` |
-| `-ne` | 禁用扩展发现 | frontmatter `no-extensions: true` 或 `argsOverride.noExtensions = true` |
-| `--mode json` | JSON 结构化输出 | frontmatter `mode: json` 或 `argsOverride.mode = "json"` |
-| `--thinking off` | 关闭深度思考 | frontmatter `thinking: off` 或 `argsOverride.thinkingLevel = "off"` |
-| `--tools ...` | 工具白名单 | frontmatter `tools: read, bash, ...` 或 `argsOverride.tools = [...]` |
-
-**优先级**: `argsOverride` (调用方) > frontmatter > 硬编码默认值
-
----
-
-## Agent 配置速查表
-
-| Agent | thinking | session | no-context | no-extensions | mode | 适用场景 |
-|-------|----------|---------|------------|---------------|------|---------|
-| **git-agent** | off | false | **true** ✅ | **true** ✅ | json | 纯 git 命令，最小开销 |
-| **planner** | low | false | **false** 🔓 | **false** 🔓 | json | 需 MCP/Skill 分析代码结构 |
-| **worker** | off | false | **false** 🔓 | **false** 🔓 | json | 按计划写代码，可调用 MCP |
-| **reviewer** | low | false | **false** 🔓 | **false** 🔓 | json | 需 Skill 审查代码 |
-| **trimmer** | off | false | **false** 🔓 | **false** 🔓 | json | 精简代码，可用 MCP |
-| **docWriter** | off | false | **false** 🔓 | **false** 🔓 | json | 更新文档，可读代码库 |
-| **review-agent** | low | false | **false** 🔓 | **false** 🔓 | json | HTML 审查报告 |
-| **dev-*-grill-agent** | low | false | **false** 🔓 | **false** 🔓 | json | 设计评审追问 |
-| **dev-prd-agent** | low | false | **false** 🔓 | **false** 🔓 | json | PRD 合成 |
-
-> ✅ `true` = 禁用 / 🔓 `false` = 开启
-
----
-
-## `argsOverride`（调用方覆写）参考
-
-`spawnSubagent()` 第 7 个参数，TypeScript 接口:
-
-```typescript
-interface SubagentArgs {
-  thinkingLevel?: string;    // "off" | "low" | "medium" | "high" | "xhigh"
-  session?: boolean;         // true/false
-  sessionDir?: string;       // 自定义 session 路径
-  noContext?: boolean;       // true/false
-  noExtensions?: boolean;    // true/false
-  mode?: string;             // "json" | "text"
-  tools?: string[];          // 工具白名单数组
-  appendSystemPrompt?: string; // 额外 system prompt
-  extraArgs?: string[];      // 原始 CLI 参数
-}
-```
-
-示例（workflow-engine 中覆写）:
-
-```typescript
-const result = await spawnSubagent(agent, task, cwd, signal, timeout, onProgress, {
-  thinkingLevel: "medium",    // 临时提升推理等级
-  session: true,              // 调试时保存 session
-  noExtensions: false,        // 临时开启 MCP
-});
-```