@ia-ccun/code-agent-cli 0.0.52-beta.3 → 0.0.52-beta.5

package/config/agent/extensions/aicode-grillMe.ts

@@ -0,0 +1,198 @@
+/**
+ * @author: xujianjiang
+ * /grill-me 扩展 — 确定性设计访谈，无情质问计划的每个细节，直到达成共识
+ *
+ * 功能说明：
+ * - 启动一个设计访谈会话，AI 无情地质问用户的计划
+ * - 逐个问题推进，每个问题提供推荐答案
+ * - 如果问题可通过代码库探索回答，则先探索代码库
+ * - 记录每个问答回合到状态文件
+ * - 最终将结果导出为 Markdown 文件
+ *
+ * 使用方法：
+ *   /grill-me [plan]    启动访谈，传入计划描述
+ *   grill_record_turn   记录一个问答回合（工具）
+ *   grill_save_results  保存结果为 Markdown（工具）
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+interface GrillTurn {
+  question: string;
+  recommendedAnswer: string;
+  userAnswer?: string;
+  decisionStatus: "resolved" | "open" | "needs-codebase-check";
+  notes?: string;
+}
+
+interface GrillState {
+  createdAt: string;
+  updatedAt: string;
+  projectDir: string;
+  plan: string;
+  turns: GrillTurn[];
+}
+
+const RecordTurnParams = Type.Object({
+  question: Type.String({ description: "The exact question asked, one question only." }),
+  recommendedAnswer: Type.String({ description: "The assistant's recommended answer to the question." }),
+  userAnswer: Type.Optional(Type.String({ description: "The user's answer, if already provided." })),
+  decisionStatus: Type.Union([
+    Type.Literal("resolved"),
+    Type.Literal("open"),
+    Type.Literal("needs-codebase-check"),
+  ]),
+  notes: Type.Optional(Type.String({ description: "Short rationale, dependency, or follow-up notes." })),
+});
+
+const SaveResultsParams = Type.Object({
+  path: Type.Optional(Type.String({ description: "Relative output path. Defaults to GRILL-ME.md." })),
+  summary: Type.Optional(Type.String({ description: "Optional current shared-understanding summary." })),
+  agreedDecisions: Type.Optional(Type.Array(Type.String())),
+  openRisks: Type.Optional(Type.Array(Type.String())),
+  nextDecisionNeeded: Type.Optional(Type.String({ description: "Which decision is blocking progress next." })),
+});
+
+function stateDir(cwd: string): string {
+  return join(cwd, ".aicode-cli", "grill-me");
+}
+
+function statePath(cwd: string): string {
+  return join(stateDir(cwd), "state.json");
+}
+
+async function readState(cwd: string): Promise<GrillState | undefined> {
+  try {
+    return JSON.parse(await readFile(statePath(cwd), "utf8")) as GrillState;
+  } catch {
+    return undefined;
+  }
+}
+
+async function writeState(cwd: string, state: GrillState): Promise<void> {
+  await mkdir(stateDir(cwd), { recursive: true });
+  await writeFile(statePath(cwd), JSON.stringify(state, null, 2) + "\n", "utf8");
+}
+
+function renderMarkdown(
+  state: GrillState,
+  extra: { summary?: string; agreedDecisions?: string[]; openRisks?: string[]; nextDecisionNeeded?: string },
+): string {
+  const lines: string[] = [];
+  lines.push("# Grill Me Results", "");
+  lines.push(`Generated: ${new Date().toISOString()}`, "");
+  lines.push("## Plan", "", state.plan.trim() || "_(none recorded)_", "");
+  if (extra.summary?.trim()) {
+    lines.push("## Shared Understanding", "", extra.summary.trim(), "");
+  }
+  lines.push("## Questions and Answers", "");
+  if (state.turns.length === 0) {
+    lines.push("_(No turns recorded.)", "");
+  } else {
+    state.turns.forEach((turn, index) => {
+      lines.push(`### ${index + 1}. ${turn.question}`, "");
+      lines.push(`**Recommended answer:** ${turn.recommendedAnswer || "_(none)_"}`, "");
+      lines.push(`**User answer:** ${turn.userAnswer || "_(not recorded)_"}`, "");
+      lines.push(`**Status:** ${turn.decisionStatus}`, "");
+      if (turn.notes?.trim()) lines.push(`**Notes:** ${turn.notes.trim()}`, "");
+    });
+  }
+  if (extra.agreedDecisions?.length) {
+    lines.push("## Agreed Decisions", "", ...extra.agreedDecisions.map((d) => `- ${d}`), "");
+  }
+  if (extra.openRisks?.length) {
+    lines.push("## Open Risks", "", ...extra.openRisks.map((r) => `- ${r}`), "");
+  }
+  if (extra.nextDecisionNeeded?.trim()) {
+    lines.push("## Next Decision Needed", "", extra.nextDecisionNeeded.trim(), "");
+  }
+  return lines.join("\n");
+}
+
+function safeOutputPath(cwd: string, input?: string): string {
+  const requested = input?.trim() || "GRILL-ME.md";
+  const absolute = resolve(cwd, requested);
+  const root = resolve(cwd);
+  if (absolute !== root && !absolute.startsWith(root + "/")) {
+    throw new Error(`Refusing to write outside project directory: ${requested}`);
+  }
+  return absolute;
+}
+
+export default function grillMeExtension(pi: ExtensionAPI) {
+  pi.registerCommand("grill-me", {
+    description: "Start a deterministic design interview and save results to Markdown",
+    handler: async (args, ctx) => {
+      const plan = args.trim() || "(No plan supplied yet. Ask the user to paste or describe the plan first.)";
+      const state: GrillState = {
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+        projectDir: ctx.cwd,
+        plan,
+        turns: [],
+      };
+      await writeState(ctx.cwd, state);
+      ctx.ui.notify(`Grill session initialized: ${statePath(ctx.cwd)}`, "info");
+
+      pi.sendUserMessage(
+        `开始 /grill-me 访谈，计划如下：\n\n${plan}\n\n规则：\n- 无情地质问这个计划的每个细节，直到我们达成共识。\n- 沿着设计树的每个分支推进，逐个解决决策之间的依赖关系。\n- 每次只问一个问题。\n- 对每个问题，提供你的推荐答案，用户可以使用A B C 的方式快速选择。\n- 如果问题可以通过探索代码库来回答，则先探索代码库而不是直接提问。\n- 每个问答决策被捕获后，使用 grill_record_turn 记录。\n- 当达成足够共识或我要求停止/保存时，使用 grill_save_results 将结果保存为项目目录中的 .aicode-cli文件夹下的 Markdown 文件。`,
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "grill_record_turn",
+    label: "Grill Record Turn",
+    description: "Record one /grill-me question, recommended answer, user answer, and decision status in project state.",
+    promptSnippet: "Record structured progress for an active /grill-me design interview",
+    promptGuidelines: [
+      "Use grill_record_turn after each /grill-me interview question is answered or resolved from codebase exploration.",
+      "Do not use grill_record_turn for more than one question at a time.",
+    ],
+    parameters: RecordTurnParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const state = (await readState(ctx.cwd)) ?? {
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+        projectDir: ctx.cwd,
+        plan: "(state was created by grill_record_turn; no plan recorded)",
+        turns: [],
+      };
+      state.turns.push(params as GrillTurn);
+      state.updatedAt = new Date().toISOString();
+      await writeState(ctx.cwd, state);
+      return {
+        content: [{ type: "text", text: `Recorded grill turn #${state.turns.length}` }],
+        details: { path: statePath(ctx.cwd), count: state.turns.length },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "grill_save_results",
+    label: "Grill Save Results",
+    description: "Save the active /grill-me interview state as a Markdown file inside the project directory.",
+    promptSnippet: "Save /grill-me interview decisions and risks to Markdown in the project directory",
+    promptGuidelines: ["Use grill_save_results when the /grill-me interview is complete or the user asks to save/stop."],
+    parameters: SaveResultsParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const state = await readState(ctx.cwd);
+      if (!state) {
+        return {
+          content: [{ type: "text", text: "No active /grill-me state found. Run /grill-me first." }],
+          isError: true,
+          details: { path: statePath(ctx.cwd) },
+        };
+      }
+      const outputPath = safeOutputPath(ctx.cwd, params.path);
+      await writeFile(outputPath, renderMarkdown(state, params), "utf8");
+      return {
+        content: [{ type: "text", text: `Saved grill results to ${outputPath}` }],
+        details: { path: outputPath, turns: state.turns.length },
+      };
+    },
+  });
+}