kcode-pi 0.1.0 → 0.1.2

package/src/harness/state.ts

@@ -0,0 +1,117 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import type { ActiveRun, KdPhase } from "./types.ts";
+import { PHASE_ARTIFACTS, isKdPhase, nextPhase } from "./types.ts";
+import { activeRunPath, kdDir, 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";
+
+export function readActiveRun(cwd: string): ActiveRun | undefined {
+	const path = activeRunPath(cwd);
+	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 ??= {};
+		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;
+	} catch {
+		return undefined;
+	}
+}
+
+export function writeActiveRun(cwd: string, run: ActiveRun): void {
+	mkdirSync(kdDir(cwd), { recursive: true });
+	mkdirSync(runsDir(cwd), { recursive: true });
+	writeFileSync(activeRunPath(cwd), `${JSON.stringify(run, null, 2)}\n`, "utf8");
+}
+
+export function createActiveRun(cwd: string, goal: string, productInput?: string, version?: string): ActiveRun {
+	const profile = resolveProductProfile(productInput ?? goal);
+	const run: ActiveRun = {
+		id: createRunId(goal),
+		phase: "discuss",
+		cwd,
+		product: profile.product,
+		version,
+		profile,
+		risk: "unknown",
+		artifacts: {},
+		gate: {
+			passed: false,
+			reason: "CONTEXT.md and product profile are required before moving to spec",
+			checkedAt: new Date().toISOString(),
+		},
+	};
+
+	ensureRunDirectories(cwd, run);
+	writeArtifact(cwd, run, "discuss", defaultArtifactContent("discuss", goal, profile));
+	run.gate = inspectGate(cwd, run);
+	writeActiveRun(cwd, run);
+	return run;
+}
+
+export function updateProductProfile(cwd: string, run: ActiveRun, productInput: string, version?: string): ActiveRun {
+	const profile = resolveProductProfile(productInput);
+	run.product = profile.product;
+	run.profile = profile;
+	if (version !== undefined) run.version = version;
+	run.gate = inspectGate(cwd, run);
+	writeActiveRun(cwd, run);
+	return run;
+}
+
+export function ensurePhaseArtifact(cwd: string, run: ActiveRun, phase: KdPhase): string {
+	const path = ensureArtifact(cwd, run, phase, defaultArtifactContent(phase));
+	run.artifacts[phase] = PHASE_ARTIFACTS[phase];
+	run.gate = inspectGate(cwd, run);
+	writeActiveRun(cwd, run);
+	return path;
+}
+
+export function updatePhaseArtifact(cwd: string, run: ActiveRun, phase: KdPhase, content: string): string {
+	const path = writeArtifact(cwd, run, phase, content);
+	run.gate = inspectGate(cwd, run);
+	writeActiveRun(cwd, run);
+	return path;
+}
+
+export function advanceRun(cwd: string, run: ActiveRun, requestedPhase?: KdPhase): { run: ActiveRun; message: string } {
+	const target = requestedPhase ?? nextPhase(run.phase);
+	if (!target) {
+		return { run, message: `Run is already at final phase: ${run.phase}` };
+	}
+
+	const gate = canEnterPhase(cwd, run, target);
+	if (!gate.passed) {
+		run.gate = gate;
+		writeActiveRun(cwd, run);
+		return { run, message: gate.reason ?? `Cannot enter ${target}` };
+	}
+
+	run.phase = target;
+	ensurePhaseArtifact(cwd, run, target);
+	run.gate = inspectGate(cwd, run);
+	writeActiveRun(cwd, run);
+	return { run, message: `Advanced Kingdee run to phase: ${target}` };
+}
+
+export function refreshGate(cwd: string, run: ActiveRun): ActiveRun {
+	run.gate = inspectGate(cwd, run);
+	writeActiveRun(cwd, run);
+	return run;
+}
+
+function createRunId(goal: string): string {
+	const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\..+/, "").replace("T", "-");
+	const slug = goal
+		.toLowerCase()
+		.replace(/[^a-z0-9\u4e00-\u9fa5]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.slice(0, 40);
+	return slug ? `${stamp}-${slug}` : stamp;
+}

package/src/harness/types.ts

@@ -0,0 +1,42 @@
+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 interface GateResult {
+	passed: boolean;
+	reason?: string;
+	checkedAt: string;
+}
+
+export interface ActiveRun {
+	id: string;
+	phase: KdPhase;
+	cwd: string;
+	product?: KdProduct;
+	version?: string;
+	profile?: ProductProfile;
+	risk?: KdRisk;
+	artifacts: Record<string, string>;
+	gate: GateResult;
+}
+
+export const PHASE_ORDER: KdPhase[] = ["discuss", "spec", "plan", "execute", "verify", "ship"];
+
+export const PHASE_ARTIFACTS: Record<KdPhase, string> = {
+	discuss: "CONTEXT.md",
+	spec: "SPEC.md",
+	plan: "PLAN.md",
+	execute: "EXECUTION.md",
+	verify: "VERIFY.md",
+	ship: "SHIP.md",
+};
+
+export function isKdPhase(value: string): value is KdPhase {
+	return (PHASE_ORDER as readonly string[]).includes(value);
+}
+
+export function nextPhase(phase: KdPhase): KdPhase | undefined {
+	const index = PHASE_ORDER.indexOf(phase);
+	return index >= 0 ? PHASE_ORDER[index + 1] : undefined;
+}

package/src/knowledge/format.ts

@@ -0,0 +1,48 @@
+import { relative } from "node:path";
+import type { SearchResult, TableSchema } from "./types.ts";
+
+export function formatSearchResults(query: string, results: SearchResult[], basePath: string): string {
+	if (results.length === 0) {
+		return `No Kingdee knowledge results found for "${query}".`;
+	}
+
+	const lines = [`Kingdee knowledge results for "${query}":`, ""];
+	for (let i = 0; i < results.length; i++) {
+		const result = results[i];
+		lines.push(`[${i + 1}] ${result.section.heading}`);
+		lines.push(`Source: ${relative(basePath, result.file.path)}:${result.section.lineStart + 1}`);
+		lines.push(`Score: ${result.score.toFixed(2)}`);
+		lines.push(result.highlights[0] || result.section.content.trim().split("\n").slice(0, 5).join("\n"));
+		lines.push("");
+	}
+	return lines.join("\n").trim();
+}
+
+export function formatTableSchema(tableName: string, schema: TableSchema | undefined): string {
+	if (!schema) {
+		return `No table schema found for "${tableName}".`;
+	}
+
+	const lines = [
+		`Table: ${schema.name} (${tableName.toUpperCase()})`,
+		`Module: ${schema.module || "unknown"}`,
+		`Description: ${schema.description || "none"}`,
+		"",
+		"Fields:",
+	];
+
+	for (const field of schema.fields) {
+		const nullable = field.nullable ? "nullable" : "required";
+		lines.push(`- ${field.name} ${field.type} ${nullable} - ${field.description}`);
+	}
+
+	if (schema.relatedTables.length > 0) {
+		lines.push("", "Related tables:");
+		for (const related of schema.relatedTables) {
+			lines.push(`- ${related.table}: ${related.relation} - ${related.description}`);
+		}
+	}
+
+	return lines.join("\n");
+}
+

package/src/knowledge/loader.ts

@@ -0,0 +1,147 @@
+import { basename, extname, join } from "node:path";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import type { KnowledgeBase, KnowledgeFile, KnowledgeScope, KnowledgeSection, TableSchema } from "./types.ts";
+
+interface CacheEntry {
+	mtime: number;
+	knowledge: KnowledgeBase;
+}
+
+const cache = new Map<string, CacheEntry>();
+
+export function loadKnowledge(scope: KnowledgeScope, basePath: string): KnowledgeBase {
+	const cacheKey = `${basePath}:${scope}`;
+	const cached = cache.get(cacheKey);
+	if (cached && !isCacheStale(basePath, cached.mtime)) {
+		return cached.knowledge;
+	}
+
+	const commonPath = join(basePath, "common");
+	const editionPath = join(basePath, scope);
+	const knowledge: KnowledgeBase = {
+		common: loadDirectory(commonPath),
+		edition: loadDirectory(editionPath),
+		tables: loadTables(editionPath),
+	};
+
+	cache.set(cacheKey, { mtime: Date.now(), knowledge });
+	return knowledge;
+}
+
+function loadDirectory(dirPath: string): KnowledgeFile[] {
+	if (!existsSync(dirPath)) return [];
+
+	const files: KnowledgeFile[] = [];
+	for (const entry of readdirSync(dirPath)) {
+		const filePath = join(dirPath, entry);
+		const stat = statSync(filePath);
+		if (!stat.isFile()) continue;
+
+		const ext = extname(entry).toLowerCase();
+		if (ext !== ".md") continue;
+
+		const file = parseMarkdown(filePath, readFileSync(filePath, "utf8"), stat.mtime.toISOString());
+		files.push(file);
+	}
+	return files;
+}
+
+function parseMarkdown(filePath: string, content: string, lastModified: string): KnowledgeFile {
+	const lines = content.split("\n");
+	const sections: KnowledgeSection[] = [];
+	const tags: string[] = [];
+	let currentSection: Partial<KnowledgeSection> | undefined;
+	let title = "";
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i].replace(/\r$/, "");
+		const headingMatch = line.match(/^(#{1,6})\s+(.+)$/);
+
+		if (headingMatch) {
+			if (currentSection) {
+				currentSection.lineEnd = i - 1;
+				sections.push(currentSection as KnowledgeSection);
+			}
+
+			const level = headingMatch[1].length;
+			const heading = headingMatch[2].trim();
+			if (level === 1 && !title) title = heading;
+			if (level <= 2) tags.push(heading);
+
+			currentSection = {
+				heading,
+				level,
+				content: "",
+				lineStart: i,
+				lineEnd: i,
+			};
+		} else if (currentSection) {
+			currentSection.content = `${currentSection.content ?? ""}${line}\n`;
+		}
+	}
+
+	if (currentSection) {
+		currentSection.lineEnd = lines.length - 1;
+		sections.push(currentSection as KnowledgeSection);
+	}
+
+	const fileName = basename(filePath, ".md");
+	tags.push(fileName);
+
+	return {
+		path: filePath,
+		title: title || fileName,
+		type: "markdown",
+		sections,
+		tags: [...new Set(tags)],
+		lastModified,
+	};
+}
+
+function loadTables(editionPath: string): Map<string, TableSchema> {
+	const tables = new Map<string, TableSchema>();
+	const tablesPath = join(editionPath, "tables.json");
+	if (!existsSync(tablesPath)) return tables;
+
+	const data = JSON.parse(readFileSync(tablesPath, "utf8")) as Record<string, unknown>;
+	for (const [tableName, tableData] of Object.entries(data)) {
+		const table = tableData as {
+			name?: string;
+			module?: string;
+			description?: string;
+			fields?: Array<{ name?: string; type?: string; nullable?: boolean; description?: string }>;
+			relatedTables?: Array<{ table?: string; relation?: string; description?: string }>;
+		};
+
+		tables.set(tableName.toUpperCase(), {
+			name: table.name || tableName,
+			module: table.module || "",
+			description: table.description || "",
+			fields: (table.fields || []).map((field) => ({
+				name: field.name || "",
+				type: field.type || "",
+				nullable: field.nullable ?? true,
+				description: field.description || "",
+			})),
+			relatedTables: (table.relatedTables || []).map((related) => ({
+				table: related.table || "",
+				relation: related.relation || "",
+				description: related.description || "",
+			})),
+		});
+	}
+
+	return tables;
+}
+
+function isCacheStale(knowledgePath: string, cachedMtime: number): boolean {
+	try {
+		return statSync(knowledgePath).mtimeMs > cachedMtime;
+	} catch {
+		return true;
+	}
+}
+
+export function clearKnowledgeCache(): void {
+	cache.clear();
+}

package/src/knowledge/search.ts

@@ -0,0 +1,118 @@
+import type { Edition, KnowledgeFile, KnowledgeScope, KnowledgeSection, SearchOptions, SearchResult, TableSchema } from "./types.ts";
+import { loadKnowledge } from "./loader.ts";
+
+export function searchKnowledge(query: string, options: SearchOptions = {}, basePath: string): SearchResult[] {
+	if (!query.trim()) return [];
+
+	const { tags, edition, scope, scopes, topK = 10, minScore = 0 } = options;
+	const targetScopes = normalizeScopes(scopes ?? [scope ?? edition ?? "flagship"]);
+	const results: SearchResult[] = [];
+
+	const seenFiles = new Set<string>();
+	for (const targetScope of targetScopes) {
+		const knowledge = loadKnowledge(targetScope, basePath);
+		for (const file of [...knowledge.common, ...knowledge.edition]) {
+			if (seenFiles.has(file.path)) continue;
+			seenFiles.add(file.path);
+			results.push(...searchFile(file, query, tags));
+		}
+	}
+
+	return results
+		.filter((result) => result.score >= minScore)
+		.sort((a, b) => b.score - a.score)
+		.slice(0, topK);
+}
+
+export function findTableSchema(tableName: string, edition: Edition, basePath: string): TableSchema | undefined {
+	const knowledge = loadKnowledge(edition, basePath);
+	return knowledge.tables.get(tableName.toUpperCase());
+}
+
+function normalizeScopes(scopes: KnowledgeScope[]): KnowledgeScope[] {
+	return [...new Set(scopes)];
+}
+
+function searchFile(file: KnowledgeFile, query: string, tags?: string[]): SearchResult[] {
+	if (tags?.length) {
+		const hasTag = tags.some((tag) => file.tags.some((fileTag) => fileTag.toLowerCase().includes(tag.toLowerCase())));
+		if (!hasTag) return [];
+	}
+
+	const queryTokens = tokenize(query);
+	const results: SearchResult[] = [];
+
+	for (const section of file.sections) {
+		const score = calculateScore(queryTokens, section, file);
+		if (score <= 0) continue;
+
+		results.push({
+			file,
+			section,
+			score,
+			highlights: highlightMatches(section.content, query),
+		});
+	}
+
+	return results;
+}
+
+export function tokenize(text: string): string[] {
+	return text
+		.toLowerCase()
+		.replace(/[^\w\u4e00-\u9fff]/g, " ")
+		.split(/\s+/)
+		.filter(Boolean);
+}
+
+function calculateScore(queryTokens: string[], section: KnowledgeSection, file: KnowledgeFile): number {
+	let score = 0;
+	const headingLower = section.heading.toLowerCase();
+	const contentLower = section.content.toLowerCase();
+	const titleLower = file.title.toLowerCase();
+	const fullQuery = queryTokens.join(" ");
+
+	if (fullQuery && titleLower.includes(fullQuery)) score += 5;
+	if (fullQuery && headingLower.includes(fullQuery)) score += 5;
+	if (fullQuery && contentLower.includes(fullQuery)) score += 5;
+
+	for (let i = 0; i < queryTokens.length; i++) {
+		const token = queryTokens[i];
+		const positionWeight = 1 + 1 / (i + 1);
+		if (titleLower.includes(token)) score += 3 * positionWeight;
+		if (headingLower.includes(token)) score += 2 * positionWeight;
+		if (contentLower.includes(token)) {
+			const matchCount = contentLower.split(token).length - 1;
+			score += (1 + Math.min(matchCount * 0.2, 2)) * positionWeight;
+		}
+	}
+
+	return score;
+}
+
+function highlightMatches(content: string, query: string): string[] {
+	const highlights: string[] = [];
+	const queryTokens = tokenize(query);
+	const lines = content.split("\n");
+	const matchedLines: number[] = [];
+
+	for (let i = 0; i < lines.length; i++) {
+		const lineLower = lines[i].toLowerCase();
+		if (queryTokens.some((token) => lineLower.includes(token))) {
+			matchedLines.push(i);
+		}
+	}
+
+	const visited = new Set<number>();
+	for (const lineIdx of matchedLines) {
+		if (visited.has(lineIdx)) continue;
+		const start = Math.max(0, lineIdx - 2);
+		const end = Math.min(lines.length - 1, lineIdx + 2);
+		for (let i = start; i <= end; i++) visited.add(i);
+
+		const context = lines.slice(start, end + 1).join("\n").trim();
+		if (context) highlights.push(context);
+	}
+
+	return highlights.slice(0, 3);
+}

package/src/knowledge/types.ts

@@ -0,0 +1,64 @@
+export type KnowledgeScope = "enterprise" | "flagship" | "cosmic" | "xinghan" | "cangqiong";
+export type Edition = Extract<KnowledgeScope, "enterprise" | "flagship">;
+
+export type KnowledgeFileType = "markdown" | "json";
+
+export interface KnowledgeFile {
+	path: string;
+	title: string;
+	type: KnowledgeFileType;
+	sections: KnowledgeSection[];
+	tags: string[];
+	lastModified: string;
+}
+
+export interface KnowledgeSection {
+	heading: string;
+	level: number;
+	content: string;
+	lineStart: number;
+	lineEnd: number;
+}
+
+export interface TableSchema {
+	name: string;
+	module: string;
+	description: string;
+	fields: FieldDefinition[];
+	relatedTables: RelatedTable[];
+}
+
+export interface FieldDefinition {
+	name: string;
+	type: string;
+	nullable: boolean;
+	description: string;
+}
+
+export interface RelatedTable {
+	table: string;
+	relation: string;
+	description: string;
+}
+
+export interface KnowledgeBase {
+	common: KnowledgeFile[];
+	edition: KnowledgeFile[];
+	tables: Map<string, TableSchema>;
+}
+
+export interface SearchResult {
+	file: KnowledgeFile;
+	section: KnowledgeSection;
+	score: number;
+	highlights: string[];
+}
+
+export interface SearchOptions {
+	tags?: string[];
+	edition?: Edition;
+	scope?: KnowledgeScope;
+	scopes?: KnowledgeScope[];
+	topK?: number;
+	minScore?: number;
+}