kcode-pi 0.1.0 → 0.1.2

package/dist/cli/kcode.js

@@ -1,10 +1,11 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 const packageRoot = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
 const require = createRequire(import.meta.url);
+const packageName = readPackageName(packageRoot) ?? "kcode-pi";
 export function runKcodeCli(args, cwd = process.cwd()) {
     const command = args[0] ?? "help";
     switch (command) {
@@ -26,16 +27,14 @@ export function initProject(cwd) {
     const settingsPath = projectSettingsPath(cwd);
     const settings = readSettings(settingsPath);
     const kcodePackage = normalizePath(packageRoot);
-    const packages = settings.packages ?? [];
-    if (!packages.includes(kcodePackage)) {
-        packages.unshift(kcodePackage);
-    }
+    const packages = (settings.packages ?? []).filter((pkg) => !isSameKcodePackage(pkg, kcodePackage));
+    packages.unshift(kcodePackage);
     settings.packages = packages;
     mkdirSync(dirname(settingsPath), { recursive: true });
     writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
     return {
         exitCode: 0,
-        output: [`已更新项目级 Pi 配置：${settingsPath}`, `已加入 KCode package：${kcodePackage}`].join("\n"),
+        output: [`已更新项目级 Pi 配置：${settingsPath}`, `已保留当前 KCode package：${kcodePackage}`].join("\n"),
     };
 }
 export function doctor(cwd) {
@@ -107,6 +106,27 @@ function readSettings(path) {
 function normalizePath(path) {
     return resolve(path);
 }
+function isSameKcodePackage(candidate, currentPackage) {
+    const normalized = normalizePath(candidate);
+    if (normalized === currentPackage)
+        return true;
+    const candidateName = readPackageName(normalized) ?? packageNameFromPath(normalized);
+    return candidateName === packageName;
+}
+function readPackageName(packagePath) {
+    try {
+        const packageJson = JSON.parse(readFileSync(join(packagePath, "package.json"), "utf8"));
+        return packageJson.name;
+    }
+    catch {
+        return undefined;
+    }
+}
+function packageNameFromPath(path) {
+    const name = basename(path);
+    const scope = basename(dirname(path));
+    return scope.startsWith("@") ? `${scope}/${name}` : name;
+}
 function bundledPiCliPath() {
     const directPath = join(packageRoot, "node_modules", "@earendil-works", "pi-coding-agent", "dist", "cli.js");
     if (existsSync(directPath))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kcode-pi",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Kingdee-specific package and harness for Pi Coding Agent",
   "type": "module",
   "private": false,
@@ -11,6 +11,7 @@
   "types": "./dist/cli/kcode.d.ts",
   "files": [
     "dist",
+    "src",
     "extensions",
     "skills",
     "prompts",

package/src/cli/kcode.ts

@@ -0,0 +1,219 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+
+export interface KcodeCliResult {
+	exitCode: number;
+	output: string;
+}
+
+interface PiSettings {
+	packages?: string[];
+	[key: string]: unknown;
+}
+
+const packageRoot = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+const require = createRequire(import.meta.url);
+const packageName = readPackageName(packageRoot) ?? "kcode-pi";
+
+export interface PiCliCommand {
+	command: string;
+	args: string[];
+	source: "bundled" | "global";
+	displayPath: string;
+}
+
+export function runKcodeCli(args: string[], cwd = process.cwd()): KcodeCliResult {
+	const command = args[0] ?? "help";
+
+	switch (command) {
+		case "init":
+			return initProject(cwd);
+		case "doctor":
+			return doctor(cwd);
+		case "start":
+			return start(cwd, args.slice(1));
+		case "help":
+		case "--help":
+		case "-h":
+			return { exitCode: 0, output: helpText() };
+		default:
+			return { exitCode: 1, output: `未知命令：${command}\n\n${helpText()}` };
+	}
+}
+
+export function initProject(cwd: string): KcodeCliResult {
+	const settingsPath = projectSettingsPath(cwd);
+	const settings = readSettings(settingsPath);
+	const kcodePackage = normalizePath(packageRoot);
+	const packages = (settings.packages ?? []).filter((pkg) => !isSameKcodePackage(pkg, kcodePackage));
+
+	packages.unshift(kcodePackage);
+
+	settings.packages = packages;
+	mkdirSync(dirname(settingsPath), { recursive: true });
+	writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+
+	return {
+		exitCode: 0,
+		output: [`已更新项目级 Pi 配置：${settingsPath}`, `已保留当前 KCode package：${kcodePackage}`].join("\n"),
+	};
+}
+
+export function doctor(cwd: string): KcodeCliResult {
+	const lines: string[] = [];
+	const node = spawnSync("node", ["--version"], { encoding: "utf8" });
+	const piCli = resolvePiCliCommand(["--version"]);
+	const pi = piCli ? spawnSync(piCli.command, piCli.args, { encoding: "utf8" }) : undefined;
+	const settingsPath = projectSettingsPath(cwd);
+
+	lines.push(`Node：${node.status === 0 ? node.stdout.trim() : "未找到"}`);
+	lines.push(`Pi CLI：${formatPiCliStatus(piCli, pi)}`);
+	lines.push(`KCode package：${packageRoot}`);
+	lines.push(`项目配置：${existsSync(settingsPath) ? settingsPath : "未创建，请先运行 kcode init"}`);
+
+	if (existsSync(settingsPath)) {
+		const settings = readSettings(settingsPath);
+		const hasKcode = (settings.packages ?? []).includes(normalizePath(packageRoot));
+		lines.push(`KCode package 已登记：${hasKcode ? "是" : "否"}`);
+	}
+
+	return {
+		exitCode: pi?.status === 0 ? 0 : 1,
+		output: lines.join("\n"),
+	};
+}
+
+export function start(cwd: string, piArgs: string[]): KcodeCliResult {
+	const init = initProject(cwd);
+	const piCli = resolvePiCliCommand(piArgs);
+
+	if (!piCli) {
+		return {
+			exitCode: 1,
+			output: `${init.output}\n未找到随包 Pi CLI 或全局 pi 命令。请重新安装 kcode-cli 后再运行 kcode start。`,
+		};
+	}
+
+	const pi = spawnSync(piCli.command, piCli.args, { cwd, stdio: "inherit", shell: false });
+
+	if (pi.error || pi.status === null) {
+		return {
+			exitCode: 1,
+			output: `${init.output}\nPi CLI 启动失败：${pi.error?.message ?? piCli.displayPath}`,
+		};
+	}
+
+	return {
+		exitCode: pi.status,
+		output: init.output,
+	};
+}
+
+export function resolvePiCliCommand(piArgs: string[] = []): PiCliCommand | undefined {
+	const bundledPi = bundledPiCliPath();
+
+	if (bundledPi) {
+		return {
+			command: process.execPath,
+			args: [bundledPi, ...piArgs],
+			source: "bundled",
+			displayPath: bundledPi,
+		};
+	}
+
+	return {
+		command: "pi",
+		args: piArgs,
+		source: "global",
+		displayPath: "pi",
+	};
+}
+
+function projectSettingsPath(cwd: string): string {
+	return join(cwd, ".pi", "settings.json");
+}
+
+function readSettings(path: string): PiSettings {
+	if (!existsSync(path)) return {};
+	return JSON.parse(readFileSync(path, "utf8")) as PiSettings;
+}
+
+function normalizePath(path: string): string {
+	return resolve(path);
+}
+
+function isSameKcodePackage(candidate: string, currentPackage: string): boolean {
+	const normalized = normalizePath(candidate);
+	if (normalized === currentPackage) return true;
+
+	const candidateName = readPackageName(normalized) ?? packageNameFromPath(normalized);
+	return candidateName === packageName;
+}
+
+function readPackageName(packagePath: string): string | undefined {
+	try {
+		const packageJson = JSON.parse(readFileSync(join(packagePath, "package.json"), "utf8")) as { name?: string };
+		return packageJson.name;
+	} catch {
+		return undefined;
+	}
+}
+
+function packageNameFromPath(path: string): string | undefined {
+	const name = basename(path);
+	const scope = basename(dirname(path));
+	return scope.startsWith("@") ? `${scope}/${name}` : name;
+}
+
+function bundledPiCliPath(): string | undefined {
+	const directPath = join(packageRoot, "node_modules", "@earendil-works", "pi-coding-agent", "dist", "cli.js");
+	if (existsSync(directPath)) return directPath;
+
+	try {
+		const mainPath = require.resolve("@earendil-works/pi-coding-agent");
+		const packageDir = dirname(dirname(mainPath));
+		const cliPath = join(packageDir, "dist", "cli.js");
+		return existsSync(cliPath) ? cliPath : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function formatPiCliStatus(
+	piCli: PiCliCommand | undefined,
+	result: ReturnType<typeof spawnSync> | undefined,
+): string {
+	if (!piCli || result?.status !== 0) {
+		return "未找到";
+	}
+
+	const version = result.stdout?.toString().trim() || result.stderr?.toString().trim() || piCliPackageVersion(piCli) || "可用";
+	const source = piCli.source === "bundled" ? "随包" : "全局";
+	return `${version}（${source}：${piCli.displayPath}）`;
+}
+
+function piCliPackageVersion(piCli: PiCliCommand): string | undefined {
+	if (piCli.source !== "bundled") return undefined;
+
+	try {
+		const packageJsonPath = join(dirname(dirname(piCli.displayPath)), "package.json");
+		const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8")) as { version?: string };
+		return packageJson.version;
+	} catch {
+		return undefined;
+	}
+}
+
+function helpText(): string {
+	return [
+		"KCode 企业入口",
+		"",
+		"用法：",
+		"  kcode init      初始化当前项目的 .pi/settings.json",
+		"  kcode doctor    检查 Node、随包 Pi CLI、KCode package 和项目级配置",
+		"  kcode start     初始化项目配置后启动 KCode 工作环境",
+	].join("\n");
+}

package/src/cli/main.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { runKcodeCli } from "./kcode.js";
+
+const result = runKcodeCli(process.argv.slice(2));
+
+if (result.output) {
+	console.log(result.output);
+}
+
+process.exitCode = result.exitCode;

package/src/harness/artifacts.ts

@@ -0,0 +1,94 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import type { ActiveRun, KdPhase } from "./types.ts";
+import { PHASE_ARTIFACTS } from "./types.ts";
+import { runArtifactPath, runRoot } from "./paths.ts";
+import type { ProductProfile } from "../product/profile.ts";
+
+export function ensureRunDirectories(cwd: string, run: ActiveRun): void {
+	mkdirSync(runRoot(cwd, run), { recursive: true });
+	mkdirSync(runArtifactPath(cwd, run, "evidence"), { recursive: true });
+}
+
+export function artifactExists(cwd: string, run: ActiveRun, artifactName: string): boolean {
+	return existsSync(runArtifactPath(cwd, run, artifactName));
+}
+
+export function phaseArtifactPath(cwd: string, run: ActiveRun, phase: KdPhase): string {
+	return runArtifactPath(cwd, run, PHASE_ARTIFACTS[phase]);
+}
+
+export function readArtifact(cwd: string, run: ActiveRun, phase: KdPhase): string | undefined {
+	const path = phaseArtifactPath(cwd, run, phase);
+	return existsSync(path) ? readFileSync(path, "utf8") : undefined;
+}
+
+export function writeArtifact(cwd: string, run: ActiveRun, phase: KdPhase, content: string): string {
+	ensureRunDirectories(cwd, run);
+	const path = phaseArtifactPath(cwd, run, phase);
+	writeFileSync(path, content.endsWith("\n") ? content : `${content}\n`, "utf8");
+	run.artifacts[phase] = PHASE_ARTIFACTS[phase];
+	return path;
+}
+
+export function ensureArtifact(cwd: string, run: ActiveRun, phase: KdPhase, content: string): string {
+	const existing = readArtifact(cwd, run, phase);
+	if (existing !== undefined) return phaseArtifactPath(cwd, run, phase);
+	return writeArtifact(cwd, run, phase, content);
+}
+
+export function defaultArtifactContent(phase: KdPhase, goal?: string, profile?: ProductProfile): string {
+	switch (phase) {
+		case "discuss":
+			return [
+				"# Context",
+				"",
+				`- Goal: ${goal ?? "unknown"}`,
+				`- Product: ${profile?.product ?? "unknown"}`,
+				"- Version: unknown",
+				`- Tech stack: ${profile?.techStack ?? "unknown"}`,
+				`- Language: ${profile?.language ?? "unknown"}`,
+				"- Plugin type: unknown",
+				"- Target bill/entity/form: unknown",
+				"- Out of scope: unknown",
+				"- Open questions:",
+				"  - Confirm Kingdee product/version, tech stack, plugin type, and target object.",
+				"",
+			].join("\n");
+		case "spec":
+			return [
+				"# Spec",
+				"",
+				"## Acceptance Criteria",
+				"",
+				"## Lifecycle / Extension Point",
+				"",
+				"## Data Objects and Fields",
+				"",
+				"## Exceptions and Performance",
+				"",
+				"## Assumptions",
+				"",
+			].join("\n");
+		case "plan":
+			return [
+				"# Plan",
+				"",
+				"## Files to Inspect",
+				"",
+				"## Files to Edit",
+				"",
+				"## Required Kingdee Lookups",
+				"",
+				"## Validation Commands",
+				"",
+				"## Rollback / Containment",
+				"",
+			].join("\n");
+		case "execute":
+			return ["# Execution", "", "## Completed Steps", "", "## Changed Files", "", "## Deviations", ""].join("\n");
+		case "verify":
+			return ["# Verify", "", "## Commands", "", "## Evidence", "", "## Residual Risk", ""].join("\n");
+		case "ship":
+			return ["# Ship", "", "## Summary", "", "## Verification Evidence", "", "## Risks", "", "## Follow-ups", ""].join("\n");
+	}
+}

package/src/harness/format.ts

@@ -0,0 +1,30 @@
+import { join } from "node:path";
+import type { ActiveRun } from "./types.ts";
+import { nextPhase } from "./types.ts";
+import { runsDir } from "./paths.ts";
+import { refreshGate } from "./state.ts";
+import { formatProductProfile } from "../product/profile.ts";
+
+export function formatStatus(cwd: string, run: ActiveRun | undefined): string {
+	if (!run) {
+		return ["No active Kingdee harness run.", "", "Start one with:", "/kd-start <goal>"].join("\n");
+	}
+
+	const refreshed = refreshGate(cwd, run);
+	const next = nextPhase(refreshed.phase) ?? "done";
+
+	return [
+		`Run: ${refreshed.id}`,
+		`Phase: ${refreshed.phase}`,
+		`Next: ${next}`,
+		`Product: ${formatProductProfile(refreshed.profile)}`,
+		`Version: ${refreshed.version ?? "unselected"}`,
+		`Risk: ${refreshed.risk ?? "unknown"}`,
+		`Gate: ${refreshed.gate.passed ? "pass" : "blocked"}`,
+		refreshed.gate.reason ? `Reason: ${refreshed.gate.reason}` : undefined,
+		"",
+		`Run directory: ${join(runsDir(cwd), refreshed.id)}`,
+	]
+		.filter(Boolean)
+		.join("\n");
+}

package/src/harness/gates.ts

@@ -0,0 +1,136 @@
+import type { ActiveRun, GateResult, KdPhase } from "./types.ts";
+import { PHASE_ARTIFACTS, PHASE_ORDER } from "./types.ts";
+import { artifactExists, readArtifact } from "./artifacts.ts";
+import { isKnownProduct } from "../product/profile.ts";
+
+const REQUIRED_MARKERS: Partial<Record<KdPhase, string[]>> = {
+	plan: ["## Validation Commands"],
+	verify: ["## Evidence"],
+	ship: ["## Verification Evidence"],
+};
+
+const COSMIC_CONFIG_EVIDENCE = "evidence/cosmic-config.txt";
+const COSMIC_METADATA_EVIDENCE = "evidence/cosmic-metadata.json";
+const COSMIC_API_EVIDENCE = "evidence/cosmic-api.txt";
+const KSQL_LINT_EVIDENCE = "evidence/ksql-lint.txt";
+
+export function inspectGate(cwd: string, run: ActiveRun): GateResult {
+	const currentIndex = PHASE_ORDER.indexOf(run.phase);
+	const missing: string[] = [];
+
+	for (let i = 0; i <= currentIndex; i++) {
+		const phase = PHASE_ORDER[i];
+		const artifact = PHASE_ARTIFACTS[phase];
+		if (!artifactExists(cwd, run, artifact)) missing.push(artifact);
+	}
+
+	const markerProblem = inspectMarkers(cwd, run, run.phase);
+	const evidenceProblem = inspectEvidence(cwd, run, run.phase);
+	const reasonParts = [];
+	if (missing.length > 0) reasonParts.push(`缺少必需产物：${[...new Set(missing)].join(", ")}`);
+	if (markerProblem) reasonParts.push(markerProblem);
+	if (evidenceProblem) reasonParts.push(evidenceProblem);
+
+	return {
+		passed: reasonParts.length === 0,
+		reason: reasonParts.length > 0 ? reasonParts.join("; ") : undefined,
+		checkedAt: new Date().toISOString(),
+	};
+}
+
+export function canEnterPhase(cwd: string, run: ActiveRun, target: KdPhase): GateResult {
+	const targetIndex = PHASE_ORDER.indexOf(target);
+	const missing: string[] = [];
+	const reasonParts: string[] = [];
+
+	if (target !== "discuss" && !isKnownProduct(run.profile?.product ?? run.product)) {
+		reasonParts.push("不能离开 discuss：产品画像未知。请使用 /kd-product <flagship|cosmic|xinghan|cangqiong|enterprise>。");
+	}
+
+	for (let i = 0; i < targetIndex; i++) {
+		const phase = PHASE_ORDER[i];
+		const artifact = PHASE_ARTIFACTS[phase];
+		if (!artifactExists(cwd, run, artifact)) missing.push(artifact);
+	}
+
+	if (target === "execute" && !artifactExists(cwd, run, PHASE_ARTIFACTS.plan)) {
+		missing.push(PHASE_ARTIFACTS.plan);
+	}
+
+	missing.push(...missingEvidenceForPhase(cwd, run, target));
+
+	if (target === "ship" && !artifactExists(cwd, run, PHASE_ARTIFACTS.verify)) {
+		missing.push(PHASE_ARTIFACTS.verify);
+	}
+
+	if (missing.length > 0) reasonParts.push(`不能进入 ${target}：缺少 ${[...new Set(missing)].join(", ")}`);
+	const reason = reasonParts.length > 0 ? reasonParts.join("; ") : undefined;
+	return {
+		passed: !reason,
+		reason,
+		checkedAt: new Date().toISOString(),
+	};
+}
+
+function inspectMarkers(cwd: string, run: ActiveRun, phase: KdPhase): string | undefined {
+	const markers = REQUIRED_MARKERS[phase];
+	if (!markers?.length) return undefined;
+
+	const content = readArtifact(cwd, run, phase);
+	if (!content) return undefined;
+
+	const missing = markers.filter((marker) => !content.includes(marker));
+	if (missing.length === 0) return undefined;
+	return `${PHASE_ARTIFACTS[phase]} 缺少必需章节：${missing.join(", ")}`;
+}
+
+function inspectEvidence(cwd: string, run: ActiveRun, phase: KdPhase): string | undefined {
+	const missing = missingEvidenceForPhase(cwd, run, phase);
+	if (missing.length === 0) return undefined;
+	return `缺少必需的官方证据：${missing.join(", ")}`;
+}
+
+function isCosmicRun(run: ActiveRun): boolean {
+	return run.profile?.platform === "cosmic";
+}
+
+function missingEvidenceForPhase(cwd: string, run: ActiveRun, phase: KdPhase): string[] {
+	return requiredEvidenceForPhase(cwd, run, phase).filter((artifact) => !artifactExists(cwd, run, artifact));
+}
+
+function requiredEvidenceForPhase(cwd: string, run: ActiveRun, phase: KdPhase): string[] {
+	if (!isCosmicRun(run)) return [];
+
+	const required = new Set<string>();
+	const phaseIndex = PHASE_ORDER.indexOf(phase);
+
+	if (phaseIndex >= PHASE_ORDER.indexOf("execute")) {
+		required.add(COSMIC_CONFIG_EVIDENCE);
+		if (planHasMetadataRequirement(cwd, run)) required.add(COSMIC_METADATA_EVIDENCE);
+		if (planHasApiRequirement(cwd, run)) required.add(COSMIC_API_EVIDENCE);
+	}
+
+	if (phaseIndex >= PHASE_ORDER.indexOf("ship") && runHasKsqlDelivery(cwd, run)) {
+		required.add(COSMIC_METADATA_EVIDENCE);
+		required.add(KSQL_LINT_EVIDENCE);
+	}
+
+	return [...required];
+}
+
+function planHasMetadataRequirement(cwd: string, run: ActiveRun): boolean {
+	const plan = readArtifact(cwd, run, "plan") ?? "";
+	return /kd_cosmic_metadata|cosmic-metadata|metadata evidence|元数据|字段验证|字段确认|字段元数据/i.test(plan);
+}
+
+function planHasApiRequirement(cwd: string, run: ActiveRun): boolean {
+	const plan = readArtifact(cwd, run, "plan") ?? "";
+	return /kd_cosmic_api|cosmic-api|api signature|method signature|sdk.*签名|方法签名|接口签名/i.test(plan);
+}
+
+function runHasKsqlDelivery(cwd: string, run: ActiveRun): boolean {
+	const text = ["spec", "plan", "verify"]
+		.map((phase) => readArtifact(cwd, run, phase as KdPhase) ?? "")
+		.join("\n");
+	return /kd_ksql_lint|kd-ksql|\bksql\b|数据修复|批量更新|字段回填|备份语句|回滚语句/i.test(text);
+}

package/src/harness/paths.ts

@@ -0,0 +1,23 @@
+import { join } from "node:path";
+import type { ActiveRun } from "./types.ts";
+
+export function kdDir(cwd: string): string {
+	return join(cwd, ".pi", "kd");
+}
+
+export function activeRunPath(cwd: string): string {
+	return join(kdDir(cwd), "active-run.json");
+}
+
+export function runsDir(cwd: string): string {
+	return join(kdDir(cwd), "runs");
+}
+
+export function runRoot(cwd: string, run: ActiveRun): string {
+	return join(runsDir(cwd), run.id);
+}
+
+export function runArtifactPath(cwd: string, run: ActiveRun, artifactName: string): string {
+	return join(runRoot(cwd, run), artifactName);
+}
+