kcode-pi 0.1.8 → 0.1.9

package/README.md

@@ -274,6 +274,9 @@ kcode start --provider openai --model gpt-4o
 /kd-start [--product product] [--version version] <goal>
 /kd-product <product> [--version version]
 /kd-status
+/kd-runs
+/kd-switch <run-id>
+/kd-finish
 /kd-gate
 /kd-advance [phase]
 /kd-artifact [phase] [content]
@@ -310,12 +313,30 @@ discuss -> spec -> plan -> execute -> verify -> ship
 
 KCode 会把金蝶开发需求纳入 Harness 工作流。你可以直接输入自然语言需求；如果当前项目还没有 active run，KCode 会自动创建 run 并进入 `discuss` 阶段，而不是直接生成代码。
 
+一个功能点对应一个 run。每个 run 都有独立阶段、计划、执行记录和证据；做另一个功能点时，不要复用上一个功能点的阶段。
+
+```text
+/kd-start 实现采购订单保存校验
+/kd-finish
+/kd-start 实现采购订单列表字段展示
+```
+
+查看和切换当前项目里的功能点 run：
+
+```text
+/kd-runs
+/kd-switch <run-id>
+```
+
+如果当前 active run 处于 `execute` 或 `verify`，但你提出的是另一个需求，KCode 会要求先创建新 run 或切换 run，避免把新需求塞进旧功能点的 `PLAN.md` 和阶段门禁。
+
 每次进入 Harness 时，KCode 会附带 `.pi/kd/PROJECT_CONTEXT.md`。这份上下文不会替代计划阶段的实际文件检查，但会让 Agent 在暂停、恢复、重新打开终端后仍知道当前项目的源码根、模块线索和禁止猜路径规则。
 
 每个需求 run 的设计和执行文档会落到本地：
 
 ```text
 .pi/kd/active-run.json
+.pi/kd/runs/<run-id>/RUN.json
 .pi/kd/runs/<run-id>/CONTEXT.md
 .pi/kd/runs/<run-id>/SPEC.md
 .pi/kd/runs/<run-id>/PLAN.md
@@ -325,7 +346,7 @@ KCode 会把金蝶开发需求纳入 Harness 工作流。你可以直接输入
 .pi/kd/runs/<run-id>/evidence/
 ```
 
-下次重新 `kcode start` 时，KCode 会读取当前项目的 active run、项目常驻上下文和已生成的阶段文档，再继续当前阶段。
+下次重新 `kcode start` 时，KCode 会读取当前项目的 active run、项目常驻上下文和已生成的阶段文档，再继续当前功能点的当前阶段。已完成或暂停的功能点仍保留在 `.pi/kd/runs/<run-id>/`，可用 `/kd-runs` 查看，用 `/kd-switch <run-id>` 切回。
 
 阶段含义：
 
@@ -388,7 +409,17 @@ ship     汇总变更、验证证据、风险和后续事项
 
 如果 LLM 跳过步骤、没有记录 evidence，或只是口头声明完成，KCode 不允许进入 `verify`。
 
-结构化问题也会进入门禁。Agent 需要确认产品、目标单据、插件位置、高风险 SQL 或方案选择时，会使用 `kd_question` 记录问题；未回答的阻断问题会阻止进入下一阶段。用户回复后，Agent 会记录答案；也可以手动执行：
+结构化问题也会进入门禁。Agent 需要确认产品、目标单据、插件位置、高风险 SQL 或方案选择时，会使用 `kd_question` 记录问题；未回答的阻断问题会阻止进入下一阶段。
+
+`kd_question` 一次只允许问一个当前最阻塞的问题，不能把多个问题打包成编号清单。比如应先问：
+
+```text
+采购入库单 Form ID 是否为 pur_receivebill？
+```
+
+得到回答后，再继续问触发时机、库存条件、弹窗内容或插件位置。
+
+在 `kcode start` 的交互式 TUI 中，`kd_question` 会弹出 KCode Question 选择/输入对话，并在用户选择或输入后自动记录答案。非交互模式或 UI 不可用时，问题会显示在对话里，用户直接回复；Agent 读取回复后再记录答案。也可以手动执行：
 
 ```text
 /kd-answer Q-001 采购订单
@@ -399,6 +430,7 @@ ship     汇总变更、验证证据、风险和后续事项
 ```text
 .pi/kd/active-run.json
 .pi/kd/runs/<run-id>/
+.pi/kd/runs/<run-id>/RUN.json
 ```
 
 ## 内置金蝶工具

package/extensions/kingdee-harness.ts

@@ -1,5 +1,5 @@
 import { Type } from "@earendil-works/pi-ai";
-import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { formatStatus } from "../src/harness/format.ts";
 import { PHASE_ORDER, isKdPhase, type KdPhase } from "../src/harness/types.ts";
 import {
@@ -8,8 +8,11 @@ import {
 	answerQuestion,
 	createActiveRun,
 	ensurePhaseArtifact,
+	finishActiveRun,
+	listRuns,
 	readActiveRun,
 	refreshGate,
+	switchActiveRun,
 	updateProductProfile,
 	updatePhaseArtifact,
 } from "../src/harness/state.ts";
@@ -105,6 +108,9 @@ function workflowPromptForRun(cwd: string, run: NonNullable<ReturnType<typeof re
 		"KCode 本次工作流本地文档：",
 		memory,
 		"",
+		`当前 active run 只属于这个功能点：${run.goal ?? run.id}。如果用户提出的是另一个功能点或无关新需求，必须停止沿用当前阶段，要求用户运行 /kd-start <新需求> 创建新 run，或 /kd-switch <run-id> 切换已有 run。`,
+		"需要用户确认时，kd_question 一次只能问一个当前最阻塞的问题；不要把 FormId、触发时机、库存条件、弹窗内容、插件位置等打包成清单。选项最多 3 个；交互模式下会弹出选择/输入对话并自动记录答案。",
+		"",
 		phaseGuidance[run.phase],
 		"必须先理解当前业务项目已有目录、模块、包名、基类和本地封装，再决定文件位置和实现方式。",
 		"路径规则：在 Windows 工作区内，优先使用项目相对路径；如需绝对路径必须使用 `D:\\...` 这类 Windows 路径，禁止把路径改写成 `/mnt/d/...`、`/d/...` 等 WSL/MSYS 风格路径。",
@@ -164,14 +170,14 @@ const kdQuestionTool = defineTool({
 	name: "kd_question",
 	label: "KD Question",
 	description:
-		"Create, answer, or list structured Kingdee Harness questions. Open blocking questions stop phase advancement until answered.",
+		"Create, answer, or list structured Kingdee Harness questions. Ask exactly one short blocking question at a time; do not batch a checklist.",
 	parameters: Type.Object({
 		action: Type.Optional(Type.String({ description: "ask, answer, or list. Defaults to ask." })),
 		id: Type.Optional(Type.String({ description: "Question id when action=answer, for example Q-001." })),
-		question: Type.Optional(Type.String({ description: "Question to ask when action=ask." })),
+		question: Type.Optional(Type.String({ description: "One short question to ask when action=ask. No numbered lists or multiple questions." })),
 		answer: Type.Optional(Type.String({ description: "User answer when action=answer." })),
 		reason: Type.Optional(Type.String({ description: "Why this question blocks or matters." })),
-		choices: Type.Optional(Type.Array(Type.String(), { description: "Optional concrete choices for the user." })),
+		choices: Type.Optional(Type.Array(Type.String(), { description: "Optional concrete choices for the user, maximum 3 short labels." })),
 		blocking: Type.Optional(Type.Boolean({ description: "Whether the question blocks phase advancement. Defaults to true." })),
 	}),
 
@@ -224,6 +230,26 @@ const kdQuestionTool = defineTool({
 				details: { error: "missing-question" },
 			};
 		}
+		const batchProblem = questionBatchProblem(params.question, params.choices);
+		if (batchProblem) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: [
+							batchProblem,
+							"",
+							"kd_question 一次只登记一个当前最阻塞的问题。",
+							"请先问第一个必须确认的问题，例如：",
+							"kd_question action=ask question=\"采购入库单 Form ID 是否为 pur_receivebill？\" choices=[\"是\", \"不是\"]",
+							"",
+							"注意：Pi 当前不会弹出表单；问题会显示在对话里，用户在对话中回答后再用 kd_question action=answer 记录。",
+						].join("\n"),
+					},
+				],
+				details: { error: "batched-question" },
+			};
+		}
 
 		const question = addQuestion(ctx.cwd, run, {
 			question: params.question,
@@ -232,8 +258,20 @@ const kdQuestionTool = defineTool({
 			blocking: params.blocking,
 		});
 		appendQuestionEventToArtifact(ctx.cwd, run, formatQuestionArtifactLines(question));
-		const text = formatQuestionCard(question);
-		return { content: [{ type: "text", text }], details: { question, gate: readActiveRun(ctx.cwd)?.gate } };
+		const interactiveAnswer = await askQuestionInteractively(ctx, question.question, question.choices);
+		if (interactiveAnswer) {
+			const answered = answerQuestion(ctx.cwd, run, question.id, interactiveAnswer);
+			if (answered) {
+				appendQuestionEventToArtifact(ctx.cwd, run, [`- Answered ${answered.id}: ${answered.answer}`]);
+				return {
+					content: [{ type: "text", text: `User answered ${answered.id}: ${answered.answer}` }],
+					details: { question: answered, gate: readActiveRun(ctx.cwd)?.gate, answered: true },
+				};
+			}
+		}
+
+		const text = `${formatQuestionCard(question)}\n\nInteractive answer was not provided; keep this question open until the user answers.`;
+		return { content: [{ type: "text", text }], details: { question, gate: readActiveRun(ctx.cwd)?.gate, answered: false } };
 	},
 });
 
@@ -286,6 +324,14 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	pi.registerCommand("kd-runs", {
+		description: "List Kingdee harness runs for this project",
+		handler: async (_args, ctx) => {
+			const active = readActiveRun(ctx.cwd);
+			ctx.ui.notify(formatRuns(listRuns(ctx.cwd), active?.id), "info");
+		},
+	});
+
 	pi.registerCommand("kd-gate", {
 		description: "Refresh and show the active Kingdee harness gate",
 		handler: async (_args, ctx) => {
@@ -314,6 +360,39 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	pi.registerCommand("kd-switch", {
+		description: "Switch active Kingdee harness run: /kd-switch <run-id>",
+		handler: async (args, ctx) => {
+			const id = args.trim();
+			if (!id) {
+				ctx.ui.notify("Usage: /kd-switch <run-id>", "error");
+				return;
+			}
+
+			const run = switchActiveRun(ctx.cwd, id);
+			if (!run) {
+				ctx.ui.notify(`Kingdee harness run not found: ${id}. Use /kd-runs to list runs.`, "error");
+				return;
+			}
+
+			ctx.ui.notify(`Switched active Kingdee harness run: ${run.id} (${run.phase})`, "info");
+		},
+	});
+
+	pi.registerCommand("kd-finish", {
+		description: "Mark the active Kingdee harness run as done and clear active run",
+		handler: async (_args, ctx) => {
+			const run = requireRun(ctx.cwd);
+			if (!run) {
+				ctx.ui.notify("No active Kingdee harness run. Use /kd-start <goal>.", "error");
+				return;
+			}
+
+			const finished = finishActiveRun(ctx.cwd, run);
+			ctx.ui.notify(`Finished Kingdee harness run: ${finished.id}. Start the next feature with /kd-start <goal>.`, "info");
+		},
+	});
+
 	pi.registerCommand("kd-product", {
 		description: "Set the active Kingdee product profile: /kd-product <flagship|cosmic|xinghan|cangqiong|enterprise> [--version version]",
 		handler: async (args, ctx) => {
@@ -411,6 +490,20 @@ function formatQuestions(run: NonNullable<ReturnType<typeof readActiveRun>>): st
 	return questions.map(formatQuestionCard).join("\n\n");
 }
 
+function formatRuns(runs: NonNullable<ReturnType<typeof readActiveRun>>[], activeId?: string): string {
+	if (runs.length === 0) return "No Kingdee harness runs in this project. Start one with /kd-start <goal>.";
+	return runs
+		.map((run) =>
+			[
+				`${run.id === activeId ? "*" : "-"} ${run.id}`,
+				`  Goal: ${run.goal ?? "unknown"}`,
+				`  Status: ${run.status ?? "active"} | Phase: ${run.phase} | Product: ${run.profile?.product ?? run.product ?? "unknown"}`,
+				`  Updated: ${run.updatedAt ?? "unknown"}`,
+			].join("\n"),
+		)
+		.join("\n\n");
+}
+
 function formatQuestionCard(question: NonNullable<NonNullable<ReturnType<typeof readActiveRun>>["questions"]>[number]): string {
 	const lines = [
 		`Question ${question.id} [${question.status}${question.blocking ? ", blocking" : ""}]`,
@@ -419,11 +512,49 @@ function formatQuestionCard(question: NonNullable<NonNullable<ReturnType<typeof
 		question.reason ? `Reason: ${question.reason}` : undefined,
 		question.choices?.length ? `Choices: ${question.choices.join(" | ")}` : undefined,
 		question.answer ? `Answer: ${question.answer}` : undefined,
-		question.status === "open" ? `Reply with the answer, then record it using kd_question action=answer id=${question.id} answer=<answer>.` : undefined,
+		question.status === "open"
+			? `Answer the dialog if available, or reply in chat and record it using kd_question action=answer id=${question.id} answer=<answer>.`
+			: undefined,
 	];
 	return lines.filter(Boolean).join("\n");
 }
 
+async function askQuestionInteractively(
+	ctx: ExtensionContext,
+	question: string,
+	choices: string[] | undefined,
+): Promise<string | undefined> {
+	if (!ctx.hasUI) return undefined;
+
+	const normalizedChoices = choices?.map((choice) => choice.trim()).filter(Boolean) ?? [];
+	try {
+		if (normalizedChoices.length === 0) {
+			return (await ctx.ui.input("KCode Question", question))?.trim() || undefined;
+		}
+
+		const customChoice = "其他，自定义输入";
+		const selected = await ctx.ui.select("KCode Question", [...normalizedChoices, customChoice]);
+		if (!selected) return undefined;
+		if (selected !== customChoice) return selected;
+		return (await ctx.ui.input("KCode Question", question))?.trim() || undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function questionBatchProblem(question: string, choices?: string[]): string | undefined {
+	const text = question.trim();
+	const numberedItems = text.split(/\r?\n/).filter((line) => /^\s*(\d+[\.\)、)]|[-*]\s+)/.test(line)).length;
+	if (numberedItems >= 2) return "kd_question rejected a batched checklist question.";
+	if ((text.match(/[?？]/g) ?? []).length > 1) return "kd_question rejected multiple questions in one prompt.";
+	if (text.length > 220) return "kd_question rejected an overlong question. Ask only the smallest blocking question first.";
+	if ((choices?.length ?? 0) > 3) return "kd_question rejected too many choices. Provide at most 3 concise choices.";
+	if (choices?.some((choice) => choice.length > 40 || /[\r\n?？]/.test(choice))) {
+		return "kd_question rejected complex choices. Choices must be short labels, not nested questions.";
+	}
+	return undefined;
+}
+
 function formatQuestionArtifactLines(question: NonNullable<NonNullable<ReturnType<typeof readActiveRun>>["questions"]>[number]): string[] {
 	return [
 		`- ${question.id} [${question.blocking ? "blocking" : "non-blocking"}] ${question.question}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kcode-pi",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Kingdee-specific package and harness for Pi Coding Agent",
   "type": "module",
   "private": false,

package/skills/kd-discuss/SKILL.md

@@ -20,5 +20,6 @@ Rules:
 - Do not propose implementation before the context is clear.
 - Do not invent SDK APIs, table names, or lifecycle methods.
 - If the product/version, tech stack, or target object is unknown, mark it as an open question.
+- Ask unresolved questions one at a time. When using `kd_question`, ask only the single most blocking question and use at most 3 short choices; never submit a numbered checklist of questions.
 - Never apply enterprise C# rules to Java products, or Java/Cosmic plugin rules to enterprise C#.
 - Keep context concise; detailed design belongs in `SPEC.md`.

package/skills/kd-spec/SKILL.md

@@ -20,5 +20,4 @@ Rules:
 - Separate confirmed facts from assumptions.
 - Mark every API/table assumption as requiring lookup with `kd_search` or `kd_table`.
 - Do not edit product code in this phase.
-- If acceptance criteria are vague, ask targeted questions or state explicit assumptions.
-
+- If acceptance criteria are vague, ask targeted questions one at a time or state explicit assumptions. When using `kd_question`, ask only the single most blocking question and use at most 3 short choices; never submit a numbered checklist of questions.

package/src/harness/format.ts

@@ -15,6 +15,8 @@ export function formatStatus(cwd: string, run: ActiveRun | undefined): string {
 
 	return [
 		`Run: ${refreshed.id}`,
+		refreshed.goal ? `Goal: ${refreshed.goal}` : undefined,
+		`Status: ${refreshed.status ?? "active"}`,
 		`Phase: ${refreshed.phase}`,
 		`Next: ${next}`,
 		`Product: ${formatProductProfile(refreshed.profile)}`,

package/src/harness/paths.ts

@@ -17,7 +17,11 @@ export function runRoot(cwd: string, run: ActiveRun): string {
 	return join(runsDir(cwd), run.id);
 }
 
+export function runStatePath(cwd: string, runOrId: ActiveRun | string): string {
+	const id = typeof runOrId === "string" ? runOrId : runOrId.id;
+	return join(runsDir(cwd), id, "RUN.json");
+}
+
 export function runArtifactPath(cwd: string, run: ActiveRun, artifactName: string): string {
 	return join(runRoot(cwd, run), artifactName);
 }
-

package/src/harness/state.ts

@@ -1,7 +1,7 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import type { ActiveRun, KdPhase, KdQuestion } from "./types.ts";
 import { PHASE_ARTIFACTS, isKdPhase, nextPhase } from "./types.ts";
-import { activeRunPath, kdDir, runsDir } from "./paths.ts";
+import { activeRunPath, kdDir, runStatePath, runsDir } from "./paths.ts";
 import { defaultArtifactContent, ensureArtifact, ensureRunDirectories, writeArtifact } from "./artifacts.ts";
 import { canEnterPhase, inspectGate } from "./gates.ts";
 import { profileForProduct, resolveProductProfile } from "../product/profile.ts";
@@ -11,15 +11,9 @@ export function readActiveRun(cwd: string): ActiveRun | undefined {
 	if (!existsSync(path)) return undefined;
 
 	try {
-		const parsed = JSON.parse(readFileSync(path, "utf8")) as ActiveRun;
-		if (!parsed.id || !isKdPhase(parsed.phase)) return undefined;
-		parsed.artifacts ??= {};
-		parsed.questions ??= [];
-		const legacyEdition = (parsed as ActiveRun & { edition?: string }).edition;
-		parsed.profile = parsed.profile ?? profileForProduct(parsed.product ?? resolveProductProfile(legacyEdition).product);
-		parsed.product = parsed.profile.product;
-		parsed.gate ??= { passed: false, checkedAt: new Date().toISOString() };
-		return parsed;
+		const active = hydrateRun(JSON.parse(readFileSync(path, "utf8")) as ActiveRun);
+		if (!active) return undefined;
+		return readRun(cwd, active.id) ?? active;
 	} catch {
 		return undefined;
 	}
@@ -28,15 +22,60 @@ export function readActiveRun(cwd: string): ActiveRun | undefined {
 export function writeActiveRun(cwd: string, run: ActiveRun): void {
 	mkdirSync(kdDir(cwd), { recursive: true });
 	mkdirSync(runsDir(cwd), { recursive: true });
+	run.status = "active";
+	run.updatedAt = new Date().toISOString();
+	writeRunState(cwd, run);
 	writeFileSync(activeRunPath(cwd), `${JSON.stringify(run, null, 2)}\n`, "utf8");
 }
 
+export function readRun(cwd: string, id: string): ActiveRun | undefined {
+	const path = runStatePath(cwd, id);
+	if (!existsSync(path)) return undefined;
+	try {
+		return hydrateRun(JSON.parse(readFileSync(path, "utf8")) as ActiveRun);
+	} catch {
+		return undefined;
+	}
+}
+
+export function listRuns(cwd: string): ActiveRun[] {
+	const root = runsDir(cwd);
+	if (!existsSync(root)) return [];
+	return readdirSync(root, { withFileTypes: true })
+		.filter((entry) => entry.isDirectory())
+		.map((entry) => readRun(cwd, entry.name))
+		.filter((run): run is ActiveRun => Boolean(run))
+		.sort((a, b) => (b.updatedAt ?? b.createdAt ?? b.id).localeCompare(a.updatedAt ?? a.createdAt ?? a.id));
+}
+
+export function switchActiveRun(cwd: string, id: string): ActiveRun | undefined {
+	const run = readRun(cwd, id);
+	if (!run) return undefined;
+	writeActiveRun(cwd, run);
+	return readActiveRun(cwd);
+}
+
+export function finishActiveRun(cwd: string, run: ActiveRun): ActiveRun {
+	run.status = "done";
+	run.updatedAt = new Date().toISOString();
+	run.gate = inspectGate(cwd, run);
+	writeRunState(cwd, run);
+	const activePath = activeRunPath(cwd);
+	if (existsSync(activePath)) unlinkSync(activePath);
+	return run;
+}
+
 export function createActiveRun(cwd: string, goal: string, productInput?: string, version?: string): ActiveRun {
 	const profile = resolveProductProfile(productInput ?? goal);
+	const now = new Date().toISOString();
 	const run: ActiveRun = {
 		id: createRunId(goal),
+		goal,
 		phase: "discuss",
 		cwd,
+		status: "active",
+		createdAt: now,
+		updatedAt: now,
 		product: profile.product,
 		version,
 		profile,
@@ -145,6 +184,26 @@ export function refreshGate(cwd: string, run: ActiveRun): ActiveRun {
 	return run;
 }
 
+function writeRunState(cwd: string, run: ActiveRun): void {
+	mkdirSync(runsDir(cwd), { recursive: true });
+	ensureRunDirectories(cwd, run);
+	writeFileSync(runStatePath(cwd, run), `${JSON.stringify(run, null, 2)}\n`, "utf8");
+}
+
+function hydrateRun(parsed: ActiveRun): ActiveRun | undefined {
+	if (!parsed.id || !isKdPhase(parsed.phase)) return undefined;
+	parsed.artifacts ??= {};
+	parsed.questions ??= [];
+	parsed.status ??= "active";
+	parsed.createdAt ??= parsed.updatedAt;
+	parsed.updatedAt ??= parsed.createdAt;
+	const legacyEdition = (parsed as ActiveRun & { edition?: string }).edition;
+	parsed.profile = parsed.profile ?? profileForProduct(parsed.product ?? resolveProductProfile(legacyEdition).product);
+	parsed.product = parsed.profile.product;
+	parsed.gate ??= { passed: false, checkedAt: new Date().toISOString() };
+	return parsed;
+}
+
 function createRunId(goal: string): string {
 	const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\..+/, "").replace("T", "-");
 	const slug = goal

package/src/harness/types.ts

@@ -2,6 +2,7 @@ import type { KdProduct, ProductProfile } from "../product/profile.ts";
 
 export type KdPhase = "discuss" | "spec" | "plan" | "execute" | "verify" | "ship";
 export type KdRisk = "unknown" | "low" | "medium" | "high";
+export type KdRunStatus = "active" | "paused" | "done";
 
 export interface GateResult {
 	passed: boolean;
@@ -24,8 +25,12 @@ export interface KdQuestion {
 
 export interface ActiveRun {
 	id: string;
+	goal?: string;
 	phase: KdPhase;
 	cwd: string;
+	status?: KdRunStatus;
+	createdAt?: string;
+	updatedAt?: string;
 	product?: KdProduct;
 	version?: string;
 	profile?: ProductProfile;