gx-code-agent 0.0.0-stage → 0.1.0

package/eval/code-search-eval.json

@@ -0,0 +1,216 @@
+{
+  "planId": "1187804490695311360",
+  "description": "wk1 真实方案 M5 混合检索评测集（关键词 + 语义 + 标签）",
+  "cases": [
+    {
+      "id": "c01",
+      "query": "故障",
+      "tags": [
+        "keyword"
+      ],
+      "expectedAny": [
+        {
+          "path": "defaultService/src/main/java/gx/cn01/demo1/controller/WkMalfunctionController.java"
+        }
+      ]
+    },
+    {
+      "id": "c02",
+      "query": "故障开始时间",
+      "tags": [
+        "keyword"
+      ],
+      "expectedAny": [
+        {
+          "path": "defaultService/src/main/java/gx/cn01/demo1/pojo/po/WkMalfunctionPO.java"
+        },
+        {
+          "path": "defaultService/src/main/java/gx/cn01/demo1/pojo/dto/WkMalfunctionDTO.java"
+        },
+        {
+          "path": "defaultService/src/main/java/gx/cn01/demo1/pojo/vo/WkMalfunctionVO.java"
+        }
+      ]
+    },
+    {
+      "id": "c03",
+      "query": "传感器",
+      "tags": [
+        "keyword"
+      ],
+      "expectedAny": [
+        {
+          "path": "defaultService/src/main/java/gx/cn01/demo1/controller/WkSensorMappingController.java"
+        },
+        {
+          "path": "defaultService/src/main/java/gx/cn01/demo1/controller/WkProcSensorRealtimeController.java"
+        }
+      ]
+    },
+    {
+      "id": "c04",
+      "query": "项目",
+      "tags": [
+        "keyword"
+      ],
+      "expectedAny": [
+        {
+          "path": "defaultService/src/main/java/gx/cn01/demo1/pojo/po/WkProjectPO.java"
+        },
+        {
+          "pathSuffix": "wkProjectTreeLeftMenu.vue"
+        },
+        {
+          "path": "defaultService/src/main/java/gx/cn01/demo1/controller/WkProjectController.java"
+        }
+      ]
+    },
+    {
+      "id": "c05",
+      "query": "MQTT 指令",
+      "tags": [
+        "keyword"
+      ],
+      "expectedAny": [
+        {
+          "path": "defaultService/src/main/java/gx/cn01/demo1/controller/WkMqttCommandController.java"
+        }
+      ]
+    },
+    {
+      "id": "c06",
+      "query": "浇筑体",
+      "tags": [
+        "keyword"
+      ],
+      "expectedAny": [
+        {
+          "path": "defaultService/src/main/java/gx/cn01/demo1/controller/WkPouringBodyController.java"
+        },
+        {
+          "path": "defaultService/src/main/java/gx/cn01/demo1/pojo/po/WkPouringBodyPO.java"
+        }
+      ]
+    },
+    {
+      "id": "c07",
+      "query": "水温",
+      "tags": [
+        "keyword"
+      ],
+      "expectedAny": [
+        {
+          "path": "defaultService/src/main/java/gx/cn01/demo1/controller/WkCalcWaterCoolController.java"
+        }
+      ]
+    },
+    {
+      "id": "c08",
+      "query": "管路",
+      "tags": [
+        "keyword"
+      ],
+      "expectedAny": [
+        {
+          "path": "defaultService/src/main/java/gx/cn01/demo1/controller/WkPipeController.java"
+        },
+        {
+          "path": "defaultService/src/main/java/gx/cn01/demo1/controller/WkCalcWaterCoolController.java"
+        }
+      ]
+    },
+    {
+      "id": "c09",
+      "query": "报错之前设置默认值",
+      "tags": [
+        "semantic"
+      ],
+      "expectedAny": [
+        {
+          "signature": "WkMalfunctionHook.fillDefaultName()"
+        },
+        {
+          "path": "src/main/java/demo/WkMalfunctionHook.java"
+        }
+      ]
+    },
+    {
+      "id": "c10",
+      "query": "3D 管道配置",
+      "tags": [
+        "keyword"
+      ],
+      "expectedAny": [
+        {
+          "path": "defaultService/src/main/java/gx/cn01/demo1/controller/WkPipe3dConfigController.java"
+        },
+        {
+          "path": "defaultService/src/main/java/gx/cn01/demo1/service/impl/WkPipe3dConfigServiceImpl.java"
+        }
+      ]
+    },
+    {
+      "id": "c11",
+      "query": "实时温度",
+      "tags": [
+        "keyword"
+      ],
+      "expectedAny": [
+        {
+          "path": "defaultService/src/main/java/gx/cn01/demo1/controller/WkProcSensorRealtimeController.java"
+        }
+      ]
+    },
+    {
+      "id": "c12",
+      "query": "开孔",
+      "tags": [
+        "keyword"
+      ],
+      "expectedAny": [
+        {
+          "path": "defaultService/src/main/java/gx/cn01/demo1/controller/WkProcOpeningController.java"
+        },
+        {
+          "path": "defaultService/src/main/java/gx/cn01/demo1/pojo/dto/WkProcOpeningDTO.java"
+        },
+        {
+          "path": "defaultService/src/main/java/gx/cn01/demo1/service/impl/WkProcOpeningServiceImpl.java"
+        }
+      ]
+    },
+    {
+      "id": "c13",
+      "query": "分页查询",
+      "tags": [
+        "keyword"
+      ],
+      "expectedAny": [
+        {
+          "path": "defaultService/src/main/java/gx/cn01/demo1/controller/WkProcLayerDiffController.java"
+        },
+        {
+          "path": "defaultService/src/main/java/gx/cn01/demo1/controller/WkPipe3dSegmentController.java"
+        },
+        {
+          "path": "defaultService/src/main/java/gx/cn01/demo1/controller/WkProcPipeDiffController.java"
+        }
+      ]
+    },
+    {
+      "id": "c14",
+      "query": "树形左侧菜单",
+      "tags": [
+        "keyword"
+      ],
+      "expectedAny": [
+        {
+          "pathSuffix": "wkMalfunctionTreeLeftMenu.vue"
+        },
+        {
+          "pathSuffix": "wkProjectTreeLeftMenu.vue"
+        }
+      ]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "gx-code-agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "GX 高代码平台伴生 CLI：注册 MCP、注入平台规范、校验生成物、本地 stdio MCP",
+  "type": "module",
+  "bin": {
+    "gx": "bin/gx.js",
+    "gx-mcp-local": "bin/gx-stdio-mcp.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "contracts",
+    "eval",
+    "templates",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "test:contracts": "node --test test/contracts.test.js",
+    "pack:check": "npm pack --dry-run && npm pack ./packages/gx-mcp-local --dry-run",
+    "publish:check": "npm test && npm pack --dry-run && npm pack ./packages/gx-mcp-local --dry-run",
+    "prepublishOnly": "npm test",
+    "publish:public": "node script/publish-public.mjs",
+    "publish:public:otp": "node script/publish-public.mjs"
+  },
+  "devDependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/src/adapters/cli/args.js

@@ -0,0 +1,94 @@
+import { UsageError } from "../../application/errors.js";
+
+export function usage() {
+  console.log(`gx-code-agent 0.1.0
+
+用法:
+  gx init [选项]
+
+选项:
+  --client <opencode|claude|cline>  客户端类型，默认 opencode
+  --url <url>                      MCP Server 地址，默认 http://127.0.0.1:4013/mcp
+  --token <token>                  API Token；也可使用环境变量 GX_API_TOKEN
+  --token-env <name>               写入配置的环境变量名，默认 GX_API_TOKEN
+  --embed-token                    将明文 Token 写入配置（默认写环境变量引用，更安全）
+  --plan <planId>                  可选，记录到 .gx/config.json 并写入 AGENTS.md
+  --template <templateId>          可选，记录到 .gx/config.json 并写入 AGENTS.md
+  --generated-dir <dir>            可选，写入 AGENTS.md 的生成层目录
+  --dir <path>                     目标项目目录，默认当前目录
+  --yes                            非交互模式确认写入；未提供且无 TTY 时退出码 2
+  --dry-run                        只打印将要写入的内容与 diff，不落盘
+  --check                          只检查配置与连接，不写入；需要更新时退出码 1
+  --with-local                     同时注册本地 stdio MCP gx-local
+  --opencode-format <legacy|v2>    OpenCode 配置格式，默认 legacy
+  --timeout <ms>                   OpenCode 远端 MCP 超时，默认 180000
+  --skip-verify                    跳过 init 后的 ping/tools/list 连接检查
+  --force                          gx apply 时覆盖已手改的生成层
+  --help                           显示帮助
+
+命令:
+  gx init      注册 MCP + 注入平台规范
+  gx pull      从平台拉取生成文件到 .gx/generated 与 .gx/manifest.json
+  gx apply     将 .gx/generated 应用到项目并保留自定义块
+  gx verify    校验项目文件与 .gx/manifest.json 是否一致
+  gx scan      解析 @ExtMethod；配置了 planId + Token 时上报 record_ext_points
+  gx audit     上报扩展点并调用 audit_alignment，合并本地/平台 Unknown
+  gx chunks    生成 Java/Vue 代码切片并上报 record_code_chunks
+  gx eval-search 用评测集计算 search_code 的 HitRate/MRR
+
+gx pull 选项:
+  --plan <planId> --template <templateId> [--model-ids a,b] [--url <url>] [--token <token>] [--dry-run]
+
+gx scan / gx audit 选项:
+  --plan <planId> --url <url> --token <token> [--source-dir src/main/java] [--compile]
+  --report        强制上报；即使未配置 Token 也报错（scan）
+  --classpath     编译 classpath，多个用系统分隔符（macOS/Linux 为 :）
+  --no-report     只做本地扫描/对账，不调用 MCP
+  --strict        存在待办或覆盖不完整时退出码 1
+
+gx eval-search 选项:
+  --dataset <path>  评测集路径，默认 eval/code-search-eval.json
+  --plan <planId> --url <url> --token <token> [--limit 5] [--out .gx/eval-search.json]
+
+gx chunks 选项:
+  --plan <planId> --url <url> --token <token> [--source-dir src/main/java,src]
+  --report        强制上报；未配置 Token 时报错
+  --no-report     只生成本地 .gx/chunks.json
+  --no-content    上报时不上传切片内容（仅元数据）
+
+示例:
+  GX_API_TOKEN=gxmcp_xxx gx init --client opencode --yes
+  gx init --client claude --token gxmcp_xxx --embed-token --yes --url https://example.com/code/mcp
+  gx pull --plan plan-1 --template tpl-1
+  gx apply --dry-run
+`);
+}
+
+/**
+ * 解析 CLI 参数。
+ *
+ * @param {string[]} argv
+ * @returns {Record<string, unknown> & { _: string[] }}
+ */
+export function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const item = argv[i];
+    if (!item.startsWith("--")) {
+      args._.push(item);
+      continue;
+    }
+    const key = item.slice(2);
+    if (["help", "dry-run", "force", "embed-token", "yes", "strict", "compile", "report", "no-report", "json", "no-content", "check", "with-local", "skip-verify"].includes(key)) {
+      args[key] = true;
+      continue;
+    }
+    const value = argv[i + 1];
+    if (!value || value.startsWith("--")) {
+      throw new UsageError(`参数 --${key} 缺少值`);
+    }
+    args[key] = value;
+    i += 1;
+  }
+  return args;
+}

package/src/adapters/cli/output.js

@@ -0,0 +1,66 @@
+/**
+ * 生成简单的行级 unified diff。
+ *
+ * 对超大文件退化为“整文件替换”提示，避免 O(n*m) 内存膨胀。
+ *
+ * @param {string} before
+ * @param {string} after
+ * @param {string} [label]
+ * @returns {string}
+ */
+export function lineDiff(before, after, label = "") {
+  if (before === after) {
+    return "";
+  }
+  const a = before.split("\n");
+  const b = after.split("\n");
+  if (a.length * b.length > 1_000_000) {
+    return `${label}\n[diff 省略] 文件较大，内容将被整体替换。\n`;
+  }
+
+  const dp = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+  for (let i = a.length - 1; i >= 0; i -= 1) {
+    for (let j = b.length - 1; j >= 0; j -= 1) {
+      dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+    }
+  }
+
+  const lines = [];
+  let i = 0;
+  let j = 0;
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) {
+      lines.push(`  ${a[i]}`);
+      i += 1;
+      j += 1;
+    } else if (dp[i + 1][j] >= dp[i][j + 1]) {
+      lines.push(`- ${a[i]}`);
+      i += 1;
+    } else {
+      lines.push(`+ ${b[j]}`);
+      j += 1;
+    }
+  }
+  while (i < a.length) {
+    lines.push(`- ${a[i]}`);
+    i += 1;
+  }
+  while (j < b.length) {
+    lines.push(`+ ${b[j]}`);
+    j += 1;
+  }
+  return `${label}\n${lines.join("\n")}\n`;
+}
+
+/**
+ * 打印 dry-run 计划。
+ *
+ * @param {{ path: string, before: string | null, after: string }[]} plan
+ */
+export function printPlan(plan) {
+  for (const item of plan) {
+    const action = item.before === null ? "create" : "update";
+    console.log(`\n[dry-run] ${action} ${item.path}`);
+    console.log(lineDiff(item.before ?? "", item.after, item.path));
+  }
+}

package/src/adapters/platform/mcpClient.js

@@ -0,0 +1,202 @@
+/**
+ * 最小 MCP Streamable HTTP 客户端。
+ *
+ * 支持 initialize -> notifications/initialized -> tools/call，兼容 JSON 与 SSE 响应。
+ */
+export class McpHttpClient {
+  /**
+   * @param {{ url: string, token: string, clientName?: string, clientVersion?: string, protocolVersion?: string, timeoutMs?: number }} options
+   */
+  constructor(options) {
+    if (!options.url) {
+      throw new Error("MCP URL 不能为空");
+    }
+    if (!options.token) {
+      throw new Error("MCP Token 不能为空");
+    }
+    this.url = options.url;
+    this.token = options.token;
+    this.clientName = options.clientName ?? "gx-code-agent";
+    this.clientVersion = options.clientVersion ?? "0.1.0";
+    this.protocolVersion = options.protocolVersion ?? "2025-06-18";
+    this.timeoutMs = Number.isFinite(options.timeoutMs) && options.timeoutMs > 0 ? options.timeoutMs : 30000;
+    this.sessionId = null;
+    this.initialized = false;
+    this.nextId = 1;
+  }
+
+  async initialize() {
+    if (this.initialized) {
+      return this;
+    }
+    const response = await this.#send({
+      jsonrpc: "2.0",
+      id: this.nextId++,
+      method: "initialize",
+      params: {
+        protocolVersion: this.protocolVersion,
+        capabilities: {},
+        clientInfo: { name: this.clientName, version: this.clientVersion }
+      }
+    });
+    const result = response?.result ?? {};
+    this.protocolVersion = result.protocolVersion ?? this.protocolVersion;
+    await this.#send({
+      jsonrpc: "2.0",
+      method: "notifications/initialized",
+      params: {}
+    }, true);
+    this.initialized = true;
+    return this;
+  }
+
+  /**
+   * @param {string} name
+   * @param {Record<string, unknown>} args
+   * @returns {Promise<any>}
+   */
+  /**
+   * 获取工具列表。
+   *
+   * @returns {Promise<any[]>}
+   */
+  async listTools() {
+    await this.initialize();
+    const response = await this.#send({
+      jsonrpc: "2.0",
+      id: this.nextId++,
+      method: "tools/list",
+      params: {}
+    });
+    if (response?.error) {
+      throw new Error(`MCP tools/list 失败: ${response.error.message ?? JSON.stringify(response.error)}`);
+    }
+    return response?.result?.tools ?? [];
+  }
+
+  async callTool(name, args) {
+    await this.initialize();
+    const response = await this.#send({
+      jsonrpc: "2.0",
+      id: this.nextId++,
+      method: "tools/call",
+      params: { name, arguments: args }
+    });
+    if (response?.error) {
+      throw new Error(`MCP 调用失败: ${response.error.message ?? JSON.stringify(response.error)}`);
+    }
+    const result = response?.result;
+    if (result?.structuredContent !== undefined && result.structuredContent !== null) {
+      return result.structuredContent;
+    }
+    const text = result?.content?.find?.((item) => item.type === "text")?.text;
+    if (text) {
+      try {
+        return JSON.parse(text);
+      } catch {
+        return text;
+      }
+    }
+    return result;
+  }
+
+  async close() {
+    if (!this.sessionId) {
+      return;
+    }
+    try {
+      await fetch(this.url, {
+        method: "DELETE",
+        headers: this.#headers(),
+        signal: this.#signal(),
+      });
+    } catch {
+      // 关闭失败不影响主流程
+    } finally {
+      this.sessionId = null;
+      this.initialized = false;
+    }
+  }
+
+  #signal() {
+    return typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(this.timeoutMs) : undefined;
+  }
+
+  #headers() {
+    const headers = {
+      "Content-Type": "application/json",
+      "Accept": "application/json, text/event-stream",
+      "Authorization": `Bearer ${this.token}`
+    };
+    if (this.sessionId) {
+      headers["Mcp-Session-Id"] = this.sessionId;
+      headers["MCP-Protocol-Version"] = this.protocolVersion;
+    }
+    return headers;
+  }
+
+  async #send(payload, notification = false) {
+    const response = await fetch(this.url, {
+      method: "POST",
+      headers: this.#headers(),
+      body: JSON.stringify(payload),
+      signal: this.#signal()
+    });
+    const sessionId = response.headers.get("mcp-session-id");
+    if (sessionId) {
+      this.sessionId = sessionId;
+    }
+    if (notification) {
+      return null;
+    }
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(`MCP HTTP ${response.status}: ${body.slice(0, 500)}`);
+    }
+    if (response.status === 202 || response.status === 204) {
+      return null;
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.includes("text/event-stream")) {
+      const text = await response.text();
+      const messages = parseSsePayload(text);
+      return messages.find((message) => message?.id === payload.id) ?? messages[0] ?? null;
+    }
+    return response.json();
+  }
+}
+
+/**
+ * 解析 SSE 响应中的 JSON-RPC 消息。
+ *
+ * @param {string} text
+ * @returns {any[]}
+ */
+export function parseSsePayload(text) {
+  const messages = [];
+  let dataLines = [];
+  const flush = () => {
+    if (dataLines.length === 0) {
+      return;
+    }
+    const data = dataLines.join("\n");
+    dataLines = [];
+    if (!data.trim()) {
+      return;
+    }
+    try {
+      messages.push(JSON.parse(data));
+    } catch {
+      // 忽略非 JSON 事件
+    }
+  };
+  for (const line of text.split(/\r?\n/u)) {
+    if (line.startsWith("data:")) {
+      dataLines.push(line.slice(5).trimStart());
+    } else if (line.trim() === "") {
+      flush();
+    }
+  }
+  flush();
+  return messages;
+}