@ghyper9023/pi-dev-workflow 0.6.3 → 0.8.0

package/extensions/pre-check.ts

@@ -0,0 +1,190 @@
+/**
+ * Pre-Check Extension
+ *
+ * 提供 `/dev-pre-check` 命令：在真正执行任务前插入一道「意图校验」闸门。
+ *
+ * 流程：
+ *   1. 取用户原始 prompt（命令参数，缺省则弹输入框）
+ *   2. 组合提示词 =「用户原始 prompt」+ 固定的「用自己的话重述目标与问题」指令，
+ *      并把本轮任务意图改成「只做意图理解，不产生任何实质改动」
+ *   3. 等待代理给出复述（代理空闲 + 本轮新增的 assistant 文本）
+ *   4. 用户确认意图：正确 → 开始真正的工作；不正确 → 补充说明后重新复述；取消 → 结束
+ *   5. 确认正确后，把「原始 prompt + 已确认的意图复述」投递给代理开始执行
+ *
+ * confirmIntent() 是上述 2-4 步的通用实现，/dev-feat 等 dev 命令同样复用：
+ * 它们把已确认的意图接进自己组装的提示词，而不是另造一套意图识别。
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { uiInput, uiSelect } from "./ui-helpers";
+import { pollFor, getLastAssistantTextAfter } from "./session-utils";
+
+// ── 提示词组装 ────────────────────────────────────────────────
+
+/** 固定的「意图复述」指令，与用户原始 prompt 组合成意图校验提示词。 */
+const RESTATE_INSTRUCTION = [
+	"## 你的任务",
+	"用自己的话重述你认为用户的目标是什么，以及用户试图解决的问题是什么。",
+	"",
+	"## 硬性约束（最高优先级）",
+	"- 本轮只做意图理解与复述，不执行任何实质工作。",
+	"- 禁止修改、创建、删除任何文件；禁止运行任何有副作用的命令。",
+	"- 禁止调用写入类工具（如 write、edit，以及 bash 中的写操作）；只允许只读探查（如 read、grep）。",
+	"- 禁止输出代码、补丁、diff、实施计划、解决方案或改进建议。",
+	"- 不要反问用户、不要请求确认、不要给出下一步行动。",
+	"- 若原始 prompt 存在歧义或信息缺口，在「不确定之处」中明确指出，但不要替用户做决定。",
+	"",
+	"## 输出格式（严格遵循）",
+	"### 1. 用户的目标",
+	"（用自己的话，2-4 句）",
+	"",
+	"### 2. 用户试图解决的问题",
+	"（用自己的话，2-4 句）",
+	"",
+	"### 3. 不确定之处",
+	"（逐条列出，无则写「无」）",
+	"",
+	"### 4. 一句话概括",
+	"（一句话说清「用户想让我做什么」）",
+	"",
+	"复述完成后立即停止，等待用户确认意图。",
+].join("\n");
+
+/** 组装意图校验提示词：原始 prompt + 固定复述指令（+ 历史修正说明）。 */
+export function buildPreCheckPrompt(originalPrompt: string, corrections: string[]): string {
+	const lines: string[] = [
+		"[pre-check] 任务意图校验：只复述，不执行",
+		"",
+		"## 用户原始 prompt（原文）",
+		originalPrompt,
+		"",
+		RESTATE_INSTRUCTION,
+	];
+
+	if (corrections.length > 0) {
+		lines.push(
+			"",
+			"## 用户对上一次复述的修正（必须吸收）",
+			...corrections.map((c, i) => `${i + 1}. ${c}`),
+		);
+	}
+
+	return lines.join("\n");
+}
+
+/** 组装确认后的执行提示词：原始 prompt + 已确认的意图复述。 */
+export function buildExecutionPrompt(originalPrompt: string, intent: string): string {
+	return [
+		"[execute] 意图已确认，开始执行",
+		"",
+		"## 用户原始 prompt（原文，权威需求）",
+		originalPrompt,
+		"",
+		"## 已由用户确认的任务意图",
+		intent,
+		"",
+		"## 要求",
+		"- 现在开始执行用户原始 prompt 描述的工作。",
+		"- 以上已确认意图是本任务的权威前提；与你的理解冲突时，以该意图为准。",
+		"- 执行前若仍需澄清，先向我提问，不要臆测。",
+	].join("\n");
+}
+
+// ── 意图确认循环 ─────────────────────────────────────────────
+
+const PRE_CHECK_TIMEOUT_MS = 5 * 60_000;
+
+/**
+ * 复述 → 确认 →（必要时）修正 的意图确认循环。
+ * 返回已确认的意图复述；用户取消或始终未取到复述时返回 undefined。
+ */
+export async function confirmIntent(
+	task: string,
+	ctx: ExtensionCommandContext,
+	pi: ExtensionAPI,
+): Promise<string | undefined> {
+	const corrections: string[] = [];
+
+	for (;;) {
+		ctx.ui.notify("正在让代理复述任务意图（只分析，不执行）...", "info");
+		const sentAt = Date.now();
+		pi.sendUserMessage(buildPreCheckPrompt(task, corrections), { deliverAs: "followUp" });
+
+		// 完成标志：代理空闲且本轮产生了新的 assistant 文本。
+		// 不依赖 waitForIdle —— 它可能在 followUp 触发的新 turn 开始前就返回。
+		const intent = await pollFor(
+			() => (ctx.isIdle() ? getLastAssistantTextAfter(ctx, sentAt) || undefined : undefined),
+			PRE_CHECK_TIMEOUT_MS,
+		);
+
+		if (!intent) {
+			const retry = await uiSelect(ctx, "未获取到代理的意图复述", ["重试", "取消"]);
+			if (retry === "重试") continue;
+			return undefined;
+		}
+
+		const decision = await uiSelect(ctx, "意图确认：以上复述是否准确反映你的目标？", [
+			"是 — 意图正确，开始执行",
+			"否 — 意图不正确，我要补充说明后重新分析",
+			"取消",
+		]);
+
+		if (!decision || decision === "取消") return undefined;
+		if (decision.startsWith("是")) return intent;
+
+		const fix = await uiInput(
+			ctx,
+			"补充/修正说明",
+			"说明哪里理解错了、遗漏了什么",
+			false,
+		);
+		if (fix === undefined) return undefined;
+		corrections.push(fix.trim() || "（用户未提供具体说明，请重新检查复述）");
+	}
+}
+
+// ── 流程 ─────────────────────────────────────────────────────
+
+async function runPreCheck(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	args: string,
+): Promise<void> {
+	if (!ctx.hasUI) {
+		ctx.ui.notify("/dev-pre-check 需要交互式界面才能确认意图", "error");
+		return;
+	}
+
+	let originalPrompt = args.trim();
+	if (!originalPrompt) {
+		const input = await uiInput(
+			ctx,
+			"待校验的需求（原始 prompt）",
+			"输入你希望 AI 先复述确认的需求原文",
+			true,
+		);
+		if (input === undefined) return;
+		originalPrompt = input.trim();
+		if (!originalPrompt) return;
+	}
+
+	const intent = await confirmIntent(originalPrompt, ctx, pi);
+	if (!intent) {
+		ctx.ui.notify("已取消，未执行任何改动", "info");
+		return;
+	}
+
+	pi.sendUserMessage(buildExecutionPrompt(originalPrompt, intent), { deliverAs: "followUp" });
+	ctx.ui.notify("意图已确认，开始执行", "info");
+}
+
+// ── Extension ────────────────────────────────────────────────
+
+export default function (pi: ExtensionAPI) {
+	pi.registerCommand("dev-pre-check", {
+		description: "(pre-check) 先让 AI 复述任务意图并确认，确认正确后再开始真正的工作",
+		handler: async (args, ctx) => {
+			await runPreCheck(pi, ctx, args);
+		},
+	});
+}

package/extensions/review-detect.ts

@@ -0,0 +1,123 @@
+/**
+ * Review Detection Extension
+ *
+ * 拦截带审查意图的输入，交给 review-html skill 在当前代理中执行：
+ *   - 直接输入 `/skill:review-html` → 立即审查
+ *   - 输入同时命中「审查意图」与「代码对象」关键词 → 弹选单让用户确认
+ *
+ * 审查报告由 review-html skill 写入 .pi-dev-output/pi-review/html/，
+ * 这里以报告文件出现作为完成标志（不使用 waitForIdle：它可能在 followUp
+ * 触发的新 turn 开始前就返回，导致误报完成）。
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { uiSelect } from "./ui-helpers";
+
+/** Find the newest HTML review file generated after `afterMs`（忽略先前遗留的旧报告）。 */
+function findNewestReviewHtml(cwd: string, afterMs: number): string {
+	const candidates = [
+		path.join(cwd, ".pi-dev-output", "pi-review", "html"),
+		path.join(cwd, "pi-review"),
+		path.join(cwd, ".pi-dev-output", "pi-review"),
+	];
+
+	for (const reviewDir of candidates) {
+		try {
+			if (fs.existsSync(reviewDir)) {
+				const files = fs.readdirSync(reviewDir)
+					.filter(f => f.endsWith(".html"))
+					.map(f => ({
+						name: f,
+						mtime: fs.statSync(path.join(reviewDir, f)).mtimeMs,
+					}))
+					.filter(f => f.mtime > afterMs)
+					.sort((a, b) => b.mtime - a.mtime);
+				if (files.length > 0) {
+					const rel = path.relative(cwd, reviewDir);
+					return rel + "/" + files[0].name;
+				}
+			}
+		} catch {
+			// ignore fs errors
+		}
+	}
+
+	return "";
+}
+
+/** Run a code review in the current agent and report the result. */
+async function runReview(task: string, ctx: ExtensionContext, pi: ExtensionAPI): Promise<string | undefined> {
+	const startTime = Date.now();
+	ctx.ui.notify("🤖 正在运行代码审查，请稍候...", "info");
+
+	pi.sendUserMessage(`/skill:review-html\n\n${task}`, {
+		deliverAs: "followUp",
+		expandPromptTemplates: true,
+	});
+
+	// 以“报告文件生成为完成标志”进行轮询；不使用 waitForIdle，
+	// 避免其在 sendUserMessage 触发的新 turn 开始前立即返回，导致误报“已完成”。
+	const deadline = Date.now() + 10 * 60_000;
+	let filePath = "";
+	while (Date.now() < deadline) {
+		filePath = findNewestReviewHtml(ctx.cwd, startTime);
+		if (filePath) break;
+		await new Promise((r) => setTimeout(r, 2_000));
+	}
+
+	const dur = ((Date.now() - startTime) / 1000).toFixed(1);
+	if (filePath) {
+		ctx.ui.notify(`📄 审查报告已生成: ${filePath} (${dur}s)`, "info");
+	} else {
+		ctx.ui.notify(`⚠️ 审查未生成报告 (${dur}s)，请查看当前代理的回复或稍后重试`, "warning");
+	}
+	return filePath;
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.on("input", async (event, ctx) => {
+		if (!ctx.hasUI) return { action: "continue" };
+		// 扩展注入的消息（sendUserMessage，source 为 "extension"）不重入本处理器，避免无限递归
+		if (event.source === "extension") return { action: "continue" };
+
+		const text = event.text.trim().toLowerCase();
+
+		// Detect review-html skill invocation or explicit review request.
+		const isReviewSkill = text.startsWith("/skill:review-html");
+		const hasReviewIntent = text.includes("review") ||
+			text.includes("审查") || text.includes("审阅") || text.includes("review-html");
+		const hasCodeTarget = text.includes("code") || text.includes("代码") ||
+			text.includes("diff") || text.includes("commit") ||
+			text.includes("html") || text.includes("report") || text.includes("报告") ||
+			text.includes("本次改动") || text.includes("这次改动");
+		const isReviewRequest = !isReviewSkill && hasReviewIntent && hasCodeTarget;
+
+		if (!isReviewSkill && !isReviewRequest) return { action: "continue" };
+
+		// ── Skill invocation: run review directly ─────────────────
+		if (isReviewSkill) {
+			await runReview(event.text, ctx, pi);
+			return { action: "handled" };
+		}
+
+		// ── Review intent: let the user choose ────────────────────
+		const mode = await uiSelect(
+			ctx,
+			"🔍 检测到审查意图",
+			[
+				"1. 开始审查（阻塞，等待结果）",
+				"2. 不是审查（放行给主代理）",
+			],
+		);
+
+		if (!mode || mode.startsWith("2")) {
+			return { action: "continue" };
+		}
+
+		await runReview(event.text, ctx, pi);
+
+		return { action: "handled" };
+	});
+}

package/extensions/session-utils.ts

@@ -0,0 +1,168 @@
+/**
+ * session-utils.ts — 跨扩展共享的会话与等待工具
+ *
+ * 职责：
+ *   1. pollFor() — 轮询等待当前代理的产物（文件/文本）出现，带超时
+ *   2. getLastAssistantTextAfter() — 提取指定时间点之后最后一条 assistant 文本
+ *
+ * 供 git-commands.ts / grill-me-agent.ts / dev-prompts.ts 等扩展共享使用。
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/** 项目基础信息，用于生成默认验收标准与默认字段。 */
+export interface ProjectDefaults {
+	language: string;
+	testCmd: string;
+	lintCmd: string;
+	packageManager: string;
+	hasPreCommit: boolean;
+	hasCI: boolean;
+}
+
+function safeReaddir(dir: string): string[] {
+	try {
+		return fs.readdirSync(dir);
+	} catch {
+		return [];
+	}
+}
+
+const SKIP_DIRS = new Set([".git", "node_modules", "dist", "build", "coverage", ".pi-dev-output"]);
+
+/** 浅层递归收集文件扩展名（深度 2），用于语言推断。 */
+function scanExtensions(cwd: string, depth: number): string[] {
+	const exts = new Set<string>();
+	const walk = (dir: string, d: number): void => {
+		if (d > depth) return;
+		for (const name of safeReaddir(dir)) {
+			const full = path.join(dir, name);
+			let stat: fs.Stats | undefined;
+			try {
+				stat = fs.statSync(full);
+			} catch {
+				continue;
+			}
+			if (stat.isDirectory()) {
+				if (!SKIP_DIRS.has(name)) walk(full, d + 1);
+			} else {
+				const m = name.match(/\.([a-z0-9]+)$/i);
+				if (m) exts.add(m[1]!.toLowerCase());
+			}
+		}
+	};
+	walk(cwd, depth);
+	return [...exts];
+}
+
+/** 探测当前项目的语言/测试/lint 命令与工程规范（pre-commit、CI）。 */
+export function detectProjectDefaults(cwd: string): ProjectDefaults {
+	const d: ProjectDefaults = {
+		language: "",
+		testCmd: "",
+		lintCmd: "",
+		packageManager: "npm",
+		hasPreCommit: false,
+		hasCI: false,
+	};
+		try {
+		const pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf-8"));
+		const scripts = pkg.scripts ?? {};
+		const rawTest = scripts.test ?? "";
+		d.testCmd = /no test specified/.test(rawTest) ? "" : rawTest;
+		d.lintCmd = scripts.lint ?? scripts["lint:fix"] ?? scripts.format ?? "";
+		const pm = pkg.packageManager ?? "";
+		d.packageManager = /pnpm/.test(pm) ? "pnpm" : /yarn/.test(pm) ? "yarn" : "npm";
+		const meta = [pkg.name ?? "", Object.keys(pkg.dependencies ?? {}), Object.keys(pkg.devDependencies ?? {})].flat().join(" ").toLowerCase();
+		if (fs.existsSync(path.join(cwd, "tsconfig.json")) || /typescript|tsx/.test(meta)) d.language = "TypeScript";
+		else if (/javascript|next|react|vue|node|nest/.test(meta)) d.language = "JavaScript";
+	} catch { /* 非 Node 项目 */ }
+	if (!d.language) {
+		const files = safeReaddir(cwd);
+		const exts = scanExtensions(cwd, 2);
+		if (fs.existsSync(path.join(cwd, "Cargo.toml"))) d.language = "Rust";
+		else if (fs.existsSync(path.join(cwd, "go.mod"))) d.language = "Go";
+		else if (fs.existsSync(path.join(cwd, "pyproject.toml")) || fs.existsSync(path.join(cwd, "requirements.txt"))) d.language = "Python";
+		else if (fs.existsSync(path.join(cwd, "pom.xml")) || fs.existsSync(path.join(cwd, "build.gradle"))) d.language = "Java";
+		else if (files.some((f) => f.endsWith(".csproj"))) d.language = "C#";
+		else if (exts.includes("rs")) d.language = "Rust";
+		else if (exts.includes("go")) d.language = "Go";
+		else if (exts.includes("py")) d.language = "Python";
+		else if (exts.includes("ts") || exts.includes("tsx")) d.language = "TypeScript";
+		else if (exts.some((e) => ["js", "mjs", "cjs", "jsx"].includes(e))) d.language = "JavaScript";
+	}
+	d.hasPreCommit = fs.existsSync(path.join(cwd, ".pre-commit-config.yaml")) || fs.existsSync(path.join(cwd, ".pre-commit-config.yml"));
+	d.hasCI = safeReaddir(path.join(cwd, ".github", "workflows")).some((f) => /\.ya?ml$/.test(f));
+	return d;
+}
+
+/** 根据项目探测结果生成常规验收标准条目（测试 + lint + pre-commit + CI）。 */
+export function defaultAcceptanceItems(d: ProjectDefaults): string[] {
+	const items: string[] = [];
+	if (d.testCmd) items.push(`运行 ${d.testCmd} 确认全部测试通过、无回归`);
+	else items.push(`按 ${d.language || "项目"} 的常规测试方式编写并运行测试，确认核心逻辑正确、无回归`);
+	if (d.lintCmd) items.push(`运行 ${d.lintCmd} 符合代码规范`);
+	if (d.hasPreCommit) items.push("通过本地 pre-commit 钩子检查");
+	if (d.hasCI) items.push("通过 CI 检查");
+	return items;
+}
+
+/**
+ * 轮询直到回调返回非空/非 undefined，或超时。
+ * 用于替代 "sendUserMessage 后再 waitForIdle" 的不可靠时序：
+ * waitForIdle 可能在消息触发的新 turn 开始前立即返回，导致误判完成。
+ */
+export async function pollFor<T>(poll: () => T | undefined | null, timeoutMs: number, intervalMs = 2_000): Promise<T | undefined> {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		const value = poll();
+		if (value !== undefined && value !== null && value !== "") return value;
+		await new Promise((r) => setTimeout(r, intervalMs));
+	}
+	return undefined;
+}
+
+/**
+ * Extract the most recent assistant message text that arrived after a given moment.
+ * Used as fallback when the agent did not write the expected file.
+ */
+export function getLastAssistantTextAfter(ctx: ExtensionCommandContext, afterMs: number): string {
+	try {
+		const entries = ctx.sessionManager.getEntries();
+		let text = "";
+		for (const entry of entries) {
+			if (entry.type !== "message" || entry.message?.role !== "assistant") continue;
+			const ts = new Date(entry.timestamp).getTime();
+			if (ts > afterMs) {
+				text = extractMessageText(entry.message.content) || text;
+			}
+		}
+		return text;
+	} catch {
+		return "";
+	}
+}
+
+function extractMessageText(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (Array.isArray(content)) {
+		return content
+			.map((part) => {
+				if (typeof part === "string") return part;
+				if (part && typeof part === "object" && "type" in part && part.type === "text") {
+					return (part as { text: string }).text;
+				}
+				return "";
+			})
+			.join("\n");
+	}
+	return "";
+}
+
+// ── Extension factory (required by pi extension loader) ─────
+
+export default function (_pi: ExtensionAPI) {
+	// session-utils is a helper module, imported by other extensions.
+}