gx-code-agent 0.0.0-stage → 0.1.1

package/src/application/applyWorkflow.js

@@ -0,0 +1,138 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { mergeKeepBlocks, stripKeepBlockContents } from "../domain/keepBlocks.js";
+import { InitTransaction, createBackupRoot, pruneBackups } from "../store/backupStore.js";
+import { readJson, readText, writeJson, writeText } from "../store/localStore.js";
+
+/**
+ * 计算文件生成层骨架的 SHA-256。
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+function skeletonHash(content) {
+  return createHash("sha256").update(stripKeepBlockContents(content)).digest("hex");
+}
+
+/**
+ * apply 前预检：识别上次 apply 之后生成层骨架被手改的文件。
+ *
+ * @param {{ dir: string, manifest: object, previous: object | null, force: boolean, dryRun: boolean, io: object }} input
+ * @returns {{ checked: number, drifted: string[], unverified: string[] }}
+ */
+function preflight({ dir, manifest, previous, force, dryRun, io }) {
+  const previousHashes = previous && typeof previous === "object" && previous.fileHashes
+    && typeof previous.fileHashes === "object" ? previous.fileHashes : {};
+  const drifted = [];
+  const unverified = [];
+  let checked = 0;
+  for (const entry of manifest.files) {
+    if (!entry || typeof entry.path !== "string" || typeof entry.sha256 !== "string") {
+      continue;
+    }
+    const target = path.join(dir, entry.path);
+    if (!fs.existsSync(target)) {
+      continue;
+    }
+    checked += 1;
+    const actual = skeletonHash(readText(target));
+    if (actual === entry.sha256) {
+      continue;
+    }
+    const previousHash = previousHashes[entry.path];
+    if (previousHash) {
+      if (actual !== previousHash) {
+        drifted.push(entry.path);
+      }
+    } else {
+      unverified.push(entry.path);
+    }
+  }
+  const preview = (items) => `${items.slice(0, 10).join(", ")}${items.length > 10 ? ` 等 ${items.length} 个` : ""}`;
+  if (drifted.length > 0) {
+    const message = `检测到 ${drifted.length} 个生成层文件在最近一次 apply 后被修改：${preview(drifted)}`;
+    if (!force && !dryRun) {
+      throw new Error(`${message}。请先执行 gx verify 确认漂移；如确认要覆盖生成层，请使用 gx apply --force`);
+    }
+    io.stderr?.write?.(`[warn] ${message}${force ? "，已使用 --force 覆盖" : ""}\n`);
+  }
+  if (unverified.length > 0) {
+    io.stderr?.write?.(`[warn] ${unverified.length} 个文件缺少上次 apply 指纹，无法判断是否手改：${preview(unverified)}\n`);
+  }
+  return { checked, drifted, unverified };
+}
+
+/**
+ * 将 .gx/generated 中的文件应用到项目，并保留自定义块。
+ *
+ * @param {Record<string, unknown>} args
+ * @param {{ stdout: NodeJS.WriteStream, stderr?: NodeJS.WriteStream }} io
+ * @returns {Promise<Record<string, unknown>>}
+ */
+export async function runApply(args, io = { stdout: process.stdout, stderr: process.stderr }) {
+  const dir = path.resolve(String(args.dir || process.cwd()));
+  const manifestFile = path.join(dir, ".gx", "manifest.json");
+  const manifest = readJson(manifestFile, null);
+  if (!manifest || !Array.isArray(manifest.files)) {
+    throw new Error("未找到 .gx/manifest.json，请先执行 gx pull");
+  }
+  const appliedFile = path.join(dir, ".gx", "applied.json");
+  const previous = readJson(appliedFile, null);
+  const dryRun = Boolean(args["dry-run"]);
+  const force = Boolean(args.force);
+  const preflightResult = preflight({ dir, manifest, previous, force, dryRun, io });
+  const transaction = new InitTransaction(dir, createBackupRoot(dir));
+  const fileHashes = {};
+  let applied = 0;
+
+  try {
+    for (const entry of manifest.files) {
+      const generatedFile = path.join(dir, ".gx", "generated", entry.path);
+      if (!fs.existsSync(generatedFile)) {
+        throw new Error(`缺少生成文件：${generatedFile}`);
+      }
+      const generated = readText(generatedFile);
+      const actual = createHash("sha256").update(stripKeepBlockContents(generated)).digest("hex");
+      if (actual !== entry.sha256) {
+        throw new Error(`生成文件校验失败：${entry.path}，请重新 gx pull`);
+      }
+      const target = path.join(dir, entry.path);
+      const existing = fs.existsSync(target) ? readText(target) : "";
+      const merged = mergeKeepBlocks(existing, generated);
+      if (dryRun) {
+        io.stdout.write(`[dry-run] apply ${entry.path}\n`);
+      } else {
+        transaction.record(target);
+        writeText(target, merged);
+        fileHashes[entry.path] = entry.sha256;
+      }
+      applied += 1;
+    }
+    if (!dryRun) {
+      writeJson(appliedFile, {
+        planId: manifest.planId,
+        metadataVersion: manifest.metadataVersion,
+        appliedAt: new Date().toISOString(),
+        fileCount: applied,
+        fileHashes,
+        preflight: {
+          checked: preflightResult.checked,
+          drifted: preflightResult.drifted,
+          unverified: preflightResult.unverified
+        }
+      });
+      pruneBackups(dir);
+    }
+    io.stdout.write(`${dryRun ? "[dry-run] " : ""}已应用 ${applied} 个文件\n`);
+    return {
+      status: dryRun ? "planned" : "applied",
+      fileCount: applied,
+      preflight: preflightResult
+    };
+  } catch (error) {
+    transaction.rollback();
+    throw error;
+  }
+}

package/src/application/auditCommand.js

@@ -0,0 +1,130 @@
+import path from "node:path";
+
+import { McpHttpClient } from "../adapters/platform/mcpClient.js";
+import { readJson, writeJson } from "../store/localStore.js";
+import { auditWorkflow } from "./auditWorkflow.js";
+import { scanWorkflow } from "./scanWorkflow.js";
+import { verifyWorkflow } from "./verifyWorkflow.js";
+
+/**
+ * 把 CLI 本地编译结果合并进 audit_alignment 的覆盖度。
+ *
+ * @param {object | null} alignment
+ * @param {object | null} compilation
+ * @returns {object | null}
+ */
+export function mergeLocalCompilation(alignment, compilation) {
+  if (!alignment || !compilation) {
+    return alignment;
+  }
+  const coverage = alignment.coverage && typeof alignment.coverage === "object" ? alignment.coverage : {};
+  const facets = coverage.facets && typeof coverage.facets === "object" ? coverage.facets : {};
+  return {
+    ...alignment,
+    coverage: {
+      ...coverage,
+      facets: {
+        ...facets,
+        compilation: compilation.available
+          ? {
+            available: true,
+            success: compilation.success,
+            reason: compilation.success ? null : `javac 失败，退出码 ${compilation.exitCode}`
+          }
+          : { available: false, reason: compilation.reason }
+      }
+    }
+  };
+}
+
+/**
+ * 执行 gx audit：上报扩展点、调用 audit_alignment、合并 Unknown。
+ *
+ * @param {Record<string, unknown>} args
+ * @param {{ stdout: NodeJS.WriteStream, stderr: NodeJS.WriteStream }} io
+ * @returns {Promise<Record<string, unknown>>}
+ */
+export async function runAudit(args, io = { stdout: process.stdout, stderr: process.stderr }) {
+  const dir = path.resolve(String(args.dir || process.cwd()));
+  const config = readJson(path.join(dir, ".gx", "config.json"), {});
+  const planId = String(args.plan || config.planId || "");
+  const url = String(args.url || config.mcpUrl || "http://127.0.0.1:4013/mcp");
+  const token = String(args.token || process.env.GX_API_TOKEN || "");
+  const sourceDirs = typeof args["source-dir"] === "string"
+    ? args["source-dir"].split(",").map((item) => item.trim()).filter(Boolean)
+    : undefined;
+  const scan = scanWorkflow({ dir, sourceDirs, compile: Boolean(args.compile), classpath: typeof args.classpath === "string" ? args.classpath : undefined });
+  const verify = verifyWorkflow({ dir });
+  const manifest = readJson(path.join(dir, ".gx", "manifest.json"), null);
+  const warnings = [];
+
+  if (!planId || !token) {
+    const local = auditWorkflow({ dir });
+    const result = {
+      ok: local.unknowns.length === 0,
+      status: "local-only",
+      planId: planId || null,
+      alignment: null,
+      unknowns: local.unknowns,
+      coverage: local.coverage,
+      warnings: [planId ? "缺少 API Token，未调用 audit_alignment" : "未配置 planId，未调用 audit_alignment"]
+    };
+    writeJson(path.join(dir, ".gx", "audit.json"), result);
+    io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return result;
+  }
+
+  const client = new McpHttpClient({ url, token });
+  let report = null;
+  try {
+    if (!args["no-report"]) {
+      try {
+        report = await client.callTool("record_ext_points", {
+          planId,
+          methods: scan.extPoints,
+          replace: true
+        });
+        writeJson(path.join(dir, ".gx", "ext-points.json"), {
+          planId,
+          reportedAt: new Date().toISOString(),
+          extPoints: scan.extPoints,
+          unannotatedMethods: scan.unannotatedMethods,
+          report
+        });
+      } catch (error) {
+        warnings.push(`record_ext_points 失败：${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+
+    const alignment = await client.callTool("audit_alignment", {
+      planId,
+      manifest,
+      unannotatedMethods: scan.unannotatedMethods,
+      driftedFiles: verify.drifted,
+      missingFiles: verify.missing,
+      extraFiles: verify.extra
+    });
+    const mergedAlignment = mergeLocalCompilation(alignment, scan.compilation);
+
+    let platformUnknowns;
+    try {
+      const page = await client.callTool("list_unknowns", { planId, limit: 100 });
+      platformUnknowns = Array.isArray(page?.items) ? page.items : undefined;
+    } catch (error) {
+      warnings.push(`list_unknowns 失败：${error instanceof Error ? error.message : String(error)}`);
+    }
+    const local = auditWorkflow({ dir, platformUnknowns });
+    const result = {
+      ...mergedAlignment,
+      status: mergedAlignment?.ok ? "aligned" : "drifted",
+      report,
+      unknowns: local.unknowns,
+      warnings: [...(alignment?.warnings ?? []), ...warnings]
+    };
+    writeJson(path.join(dir, ".gx", "audit.json"), result);
+    io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return result;
+  } finally {
+    await client.close();
+  }
+}

package/src/application/auditWorkflow.js

@@ -0,0 +1,41 @@
+import path from "node:path";
+
+import { readJson } from "../store/localStore.js";
+
+/**
+ * 合并本地与平台的 Unknown。
+ *
+ * @param {{ dir: string, platformUnknowns?: object[] }} input
+ * @returns {{ unknowns: object[], coverage: object }}
+ */
+export function auditWorkflow({ dir, platformUnknowns }) {
+  const localFile = path.join(dir, ".gx", "unknowns.json");
+  const local = readJson(localFile, { unknowns: [] });
+  const localUnknowns = Array.isArray(local) ? local : Array.isArray(local.unknowns) ? local.unknowns : [];
+
+  const merged = new Map();
+  for (const unknown of localUnknowns) {
+    if (unknown && typeof unknown.unknownId === "string") {
+      merged.set(unknown.unknownId, unknown);
+    }
+  }
+  const platformList = Array.isArray(platformUnknowns) ? platformUnknowns : [];
+  for (const unknown of platformList) {
+    if (unknown && typeof unknown.unknownId === "string") {
+      merged.set(unknown.unknownId, unknown);
+    }
+  }
+
+  return {
+    unknowns: [...merged.values()].sort((left, right) => left.unknownId.localeCompare(right.unknownId)),
+    coverage: {
+      status: "partial",
+      facets: {
+        local_unknowns: { available: true },
+        platform_unknowns: Array.isArray(platformUnknowns)
+          ? { available: true }
+          : { available: false, reason: "未提供平台 Unknown 列表" }
+      }
+    }
+  };
+}

package/src/application/chunksCommand.js

@@ -0,0 +1,87 @@
+import path from "node:path";
+
+import { McpHttpClient } from "../adapters/platform/mcpClient.js";
+import { buildChunks } from "../domain/chunker.js";
+import { readJson, writeJson } from "../store/localStore.js";
+
+/**
+ * 生成代码切片，并可选上报 record_code_chunks。
+ *
+ * @param {Record<string, unknown>} args
+ * @param {{ stdout: NodeJS.WriteStream, stderr: NodeJS.WriteStream }} io
+ * @returns {Promise<Record<string, unknown>>}
+ */
+export async function runChunks(args, io = { stdout: process.stdout, stderr: process.stderr }) {
+  const dir = path.resolve(String(args.dir || process.cwd()));
+  const config = readJson(path.join(dir, ".gx", "config.json"), {});
+  const planId = String(args.plan || config.planId || "");
+  const url = String(args.url || config.mcpUrl || "http://127.0.0.1:4013/mcp");
+  const token = String(args.token || process.env.GX_API_TOKEN || "");
+  const sourceDirs = typeof args["source-dir"] === "string"
+    ? args["source-dir"].split(",").map((item) => item.trim()).filter(Boolean)
+    : undefined;
+  const built = buildChunks({ dir, planId, projectId: planId, sourceDirs });
+  const local = {
+    generatedAt: new Date().toISOString(),
+    planId,
+    filesScanned: built.filesScanned,
+    chunkCount: built.chunks.length,
+    chunks: built.chunks,
+    coverage: built.coverage
+  };
+  writeJson(path.join(dir, ".gx", "chunks.json"), local);
+
+  const explicitReport = Boolean(args.report);
+  const autoReport = !args["no-report"] && Boolean(planId && token);
+  const shouldReport = explicitReport || autoReport;
+  if (!shouldReport) {
+    const result = {
+      planId,
+      filesScanned: built.filesScanned,
+      chunkCount: built.chunks.length,
+      coverage: built.coverage,
+      report: {
+        status: "skipped",
+        reason: !planId ? "未配置 planId" : !token ? "缺少 API Token" : "使用 --no-report 跳过"
+      }
+    };
+    io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return result;
+  }
+  if (!planId || !token) {
+    throw new Error("gx chunks --report 需要 planId 与 API Token");
+  }
+
+  const chunks = args["no-content"] ? built.chunks.map(({ content, ...rest }) => ({ ...rest, content: null })) : built.chunks;
+  const client = new McpHttpClient({ url, token });
+  try {
+    const report = await client.callTool("record_code_chunks", { planId, chunks, replace: true });
+    const result = {
+      planId,
+      filesScanned: built.filesScanned,
+      chunkCount: built.chunks.length,
+      coverage: built.coverage,
+      report: { status: "reported", ...report }
+    };
+    io.stdout.write(`已上报 ${report.accepted ?? 0} 个切片，拒绝 ${report.rejected?.length ?? 0} 个\n`);
+    for (const rejected of report.rejected ?? []) {
+      io.stderr.write(`[warn] ${rejected.path}: ${rejected.reason}\n`);
+    }
+    io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return result;
+  } catch (error) {
+    if (explicitReport) {
+      throw error;
+    }
+    io.stderr.write(`[warn] record_code_chunks 上报失败：${error.message}\n`);
+    return {
+      planId,
+      filesScanned: built.filesScanned,
+      chunkCount: built.chunks.length,
+      coverage: built.coverage,
+      report: { status: "failed", reason: error.message }
+    };
+  } finally {
+    await client.close();
+  }
+}

package/src/application/errors.js

@@ -0,0 +1,27 @@
+/**
+ * 需要用户批准但当前无法交互时抛出。
+ */
+export class ApprovalRequiredError extends Error {
+  /**
+   * @param {string} message
+   */
+  constructor(message) {
+    super(message);
+    this.name = "ApprovalRequiredError";
+    this.exitCode = 2;
+  }
+}
+
+/**
+ * 参数或用法错误。
+ */
+export class UsageError extends Error {
+  /**
+   * @param {string} message
+   */
+  constructor(message) {
+    super(message);
+    this.name = "UsageError";
+    this.exitCode = 1;
+  }
+}

package/src/application/evalSearchCommand.js

@@ -0,0 +1,148 @@
+import path from "node:path";
+
+import { McpHttpClient } from "../adapters/platform/mcpClient.js";
+import { readJson, writeJson } from "../store/localStore.js";
+
+function normalize(value) {
+  return String(value ?? "").replace(/\\/gu, "/");
+}
+
+/**
+ * 判断命中是否满足期望。
+ *
+ * @param {object} hit
+ * @param {object[]} expectedAny
+ * @returns {boolean}
+ */
+export function matchesExpected(hit, expectedAny) {
+  if (!Array.isArray(expectedAny)) {
+    return false;
+  }
+  return expectedAny.some((expected) => {
+    if (!expected || typeof expected !== "object") {
+      return false;
+    }
+    if (expected.path && normalize(hit.path) === normalize(expected.path)) {
+      return true;
+    }
+    if (expected.pathSuffix && normalize(hit.path).endsWith(normalize(expected.pathSuffix))) {
+      return true;
+    }
+    if (expected.signature && String(hit.signature ?? "") === String(expected.signature)) {
+      return true;
+    }
+    return false;
+  });
+}
+
+/**
+ * 计算检索评测指标。
+ *
+ * @param {object[]} cases
+ * @param {Record<string, { hits?: object[], latencyMs?: number, embedding?: boolean }>} results
+ * @param {number} defaultLimit
+ * @returns {object}
+ */
+export function scoreCases(cases, results, defaultLimit = 5) {
+  let hitCount = 0;
+  let reciprocalRank = 0;
+  let latencySum = 0;
+  let embeddingCount = 0;
+  const details = [];
+  for (const item of cases) {
+    const limit = Number.isFinite(item.limit) && item.limit > 0 ? item.limit : defaultLimit;
+    const result = results[item.id] ?? {};
+    const hits = Array.isArray(result.hits) ? result.hits.slice(0, limit) : [];
+    const index = hits.findIndex((hit) => matchesExpected(hit, item.expectedAny));
+    const hit = index >= 0;
+    if (hit) {
+      hitCount += 1;
+      reciprocalRank += 1 / (index + 1);
+    }
+    const latencyMs = Number(result.latencyMs) || 0;
+    latencySum += latencyMs;
+    if (result.embedding) {
+      embeddingCount += 1;
+    }
+    details.push({
+      id: item.id,
+      query: item.query,
+      tags: item.tags ?? [],
+      hit,
+      rank: hit ? index + 1 : null,
+      latencyMs,
+      embedding: Boolean(result.embedding),
+      topHits: hits.slice(0, 3).map((hitItem) => ({
+        signature: hitItem.signature,
+        path: hitItem.path,
+        score: hitItem.score
+      }))
+    });
+  }
+  const total = cases.length;
+  return {
+    total,
+    hitCount,
+    missCount: total - hitCount,
+    hitRate: total === 0 ? 0 : Number((hitCount / total).toFixed(4)),
+    mrr: total === 0 ? 0 : Number((reciprocalRank / total).toFixed(4)),
+    avgLatencyMs: total === 0 ? 0 : Math.round(latencySum / total),
+    embeddingAvailableCount: embeddingCount,
+    details
+  };
+}
+
+/**
+ * 执行 search_code 评测。
+ *
+ * @param {Record<string, unknown>} args
+ * @param {{ stdout: NodeJS.WriteStream, stderr: NodeJS.WriteStream }} io
+ * @returns {Promise<object>}
+ */
+export async function runEvalSearch(args, io = { stdout: process.stdout, stderr: process.stderr }) {
+  const dir = path.resolve(String(args.dir || process.cwd()));
+  const datasetPath = path.resolve(dir, String(args.dataset || "eval/code-search-eval.json"));
+  const dataset = readJson(datasetPath, null);
+  if (!dataset || !Array.isArray(dataset.cases)) {
+    throw new Error(`评测集格式不合法：${datasetPath}`);
+  }
+  const planId = String(args.plan || dataset.planId || "");
+  const url = String(args.url || "http://127.0.0.1:4013/mcp");
+  const token = String(args.token || process.env.GX_API_TOKEN || "");
+  if (!planId || !token) {
+    throw new Error("eval-search 需要 planId（--plan 或数据集 planId）与 API Token");
+  }
+  const limit = args.limit ? Number(args.limit) : 5;
+  const client = new McpHttpClient({ url, token });
+  const results = {};
+  try {
+    for (const item of dataset.cases) {
+      const started = performance.now();
+      const response = await client.callTool("search_code", {
+        planId,
+        query: item.query,
+        tags: item.tags && !item.tags.includes("keyword") && !item.tags.includes("semantic") ? item.tags : undefined,
+        limit: Number.isFinite(item.limit) && item.limit > 0 ? item.limit : limit
+      });
+      results[item.id] = {
+        hits: response.hits ?? [],
+        latencyMs: Math.round(performance.now() - started),
+        embedding: response.coverage?.facets?.embedding?.available === true
+      };
+    }
+  } finally {
+    await client.close();
+  }
+  const summary = scoreCases(dataset.cases, results, limit);
+  const output = {
+    generatedAt: new Date().toISOString(),
+    planId,
+    dataset: path.relative(dir, datasetPath).split(path.sep).join("/"),
+    limit,
+    ...summary
+  };
+  const outPath = path.join(dir, String(args.out || ".gx/eval-search.json"));
+  writeJson(outPath, output);
+  io.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+  return output;
+}