gx-code-agent 0.1.1 → 0.1.2

package/README.md

@@ -12,8 +12,8 @@ GX 高代码平台的伴生 CLI。M0 阶段提供 `gx init`：一次性完成 MC
 
 ```bash
 # 主 CLI
-npm i -g gx-code-agent@0.1.1
-npx --yes gx-code-agent@0.1.1 --help
+npm i -g gx-code-agent@0.1.2
+npx --yes gx-code-agent@0.1.2 --help
 
 # 独立本地 MCP 启动器
 npx --yes gx-mcp-local
@@ -86,6 +86,7 @@ gx verify [--dir <path>] [--manifest <path>] [--strict]
 gx scan   [--dir <path>] [--compile] [--report|--no-report] [--source-dir a,b]
 gx audit  [--dir <path>] [--compile] [--report|--no-report] [--strict]
 gx chunks [--dir <path>] [--source-dir a,b] [--report|--no-report] [--no-content] [--strict]
+gx doctor [--dir <path>] [--url <url>] [--token <token>] [--skip-mcp] [--skip-local] [--json] [--strict]
 gx version
 gx help
 ```
@@ -99,6 +100,31 @@ gx help
 - 非交互模式写入必须带 `--yes`，否则退出码 2。
 - 不支持的客户端会直接报错，不会猜测格式。
 
+## 诊断：gx doctor
+
+```bash
+# 人类可读
+gx doctor
+
+# 只输出 JSON（供 CI / 脚本）
+gx doctor --json
+
+# 离线环境跳过远端 MCP / 本地 MCP
+gx doctor --skip-mcp --skip-local
+```
+
+检查项：
+
+- Node.js 版本（>= 18）；
+- JDK / javac 版本（AST 与 `--compile` 需要 JDK 9+，推荐 17）；
+- `GX_API_TOKEN` 是否存在、格式是否为 `gxmcp_` + 43 位；
+- `.gx/config.json` 的 planId/templateId；
+- `.gx/manifest.json` 是否存在及文件数；
+- 远端 MCP：`ping` / `tools/list` / `get_current_user`；
+- `gx-local` 本地 stdio MCP 是否能启动并返回工具列表。
+
+失败项会给出修复提示；`--strict` 时 warn 也视为失败。退出码：存在 fail（或 strict+warn）为 1。
+
 ## M3：拉取 / 应用 / 校验
 
 ```bash
@@ -235,7 +261,7 @@ CI 变量：
 
 | 变量 | 说明 |
 |---|---|
-| `GX_AGENT_VERSION` | 固定 CLI 版本，默认 `0.1.1` |
+| `GX_AGENT_VERSION` | 固定 CLI 版本，默认 `0.1.2` |
 | `NPM_REGISTRY` | npm registry；默认 `https://registry.npmjs.org/` |
 | `GX_API_TOKEN` / `GX_PLAN_ID` | MCP 鉴权与方案范围 |
 
@@ -251,7 +277,7 @@ CI 变量：
 node --test
 ```
 
-当前：CLI `39/39`；平台侧 Java MCP `80/80`。
+当前：CLI `44/44`；平台侧 Java MCP `80/80`。
 
 ## 当前进度与后续
 
@@ -265,12 +291,13 @@ node --test
 - P7：审计 compilation facet 合并、向量重建、审计保留、pgVector 健康检查
 - P8：Java AST chunker、混合检索评测集、本地 stdio MCP（`gx-mcp-local`）
 - CLI-02：`gx init` 支持 `--with-local`、timeout、项目绑定、连接自检、`.gx/.gitignore`、`--check`
+- CLI-03：`gx doctor` 诊断 Node/JDK/Token/配置/manifest/MCP/`gx-local`，支持 `--json`
 
 待办：
 
 - `gx context` / `gx push` / `gx adopt`
 - Agent 外壳（本地 stdio MCP 已提供基础版）
-- 公共 npm 发布（发布准备已完成，待 2FA OTP 或 Bypass 2FA granular token）
+- 公共 npm 已发布 `gx-code-agent@0.1.2` 与 `gx-mcp-local@0.1.2`
 
 ## 与主平台的关系
 

package/bin/gx.js

@@ -8,6 +8,7 @@ import { parseArgs, usage } from "../src/adapters/cli/args.js";
 import { runApply } from "../src/application/applyWorkflow.js";
 import { runAudit } from "../src/application/auditCommand.js";
 import { runChunks } from "../src/application/chunksCommand.js";
+import { runDoctor } from "../src/application/doctorCommand.js";
 import { runEvalSearch } from "../src/application/evalSearchCommand.js";
 import { runInit } from "../src/application/initWorkflow.js";
 import { runPull } from "../src/application/pullWorkflow.js";
@@ -85,6 +86,13 @@ async function main() {
     }
     return;
   }
+  if (command === "doctor") {
+    const result = await runDoctor(args);
+    if (!result.ok) {
+      process.exitCode = 1;
+    }
+    return;
+  }
 
   usage();
   process.exitCode = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gx-code-agent",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "GX 高代码平台伴生 CLI：注册 MCP、注入平台规范、校验生成物、本地 stdio MCP",
   "type": "module",
   "bin": {

package/src/adapters/cli/args.js

@@ -1,7 +1,7 @@
 import { UsageError } from "../../application/errors.js";
 
 export function usage() {
-  console.log(`gx-code-agent 0.1.1
+  console.log(`gx-code-agent 0.1.2
 
 用法:
   gx init [选项]
@@ -35,6 +35,7 @@ export function usage() {
   gx audit     上报扩展点并调用 audit_alignment，合并本地/平台 Unknown
   gx chunks    生成 Java/Vue 代码切片并上报 record_code_chunks
   gx eval-search 用评测集计算 search_code 的 HitRate/MRR
+  gx doctor    诊断 Node/JDK/Token/配置/manifest/MCP/gx-local
 
 gx pull 选项:
   --plan <planId> --template <templateId> [--model-ids a,b] [--url <url>] [--token <token>] [--dry-run]
@@ -56,6 +57,16 @@ gx chunks 选项:
   --no-report     只生成本地 .gx/chunks.json
   --no-content    上报时不上传切片内容（仅元数据）
 
+gx doctor 选项:
+  --dir <path>          项目目录，默认当前目录
+  --url <url>           MCP 地址，默认读取 .gx/config.json 或 http://127.0.0.1:4013/mcp
+  --token <token>       临时指定 Token；默认读取 GX_API_TOKEN
+  --token-env <name>    Token 环境变量名，默认 GX_API_TOKEN
+  --skip-mcp            跳过远端 MCP 检查
+  --skip-local          跳过 gx-local 检查
+  --json                输出 JSON
+  --strict              warn 也视为失败
+
 示例:
   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
@@ -79,7 +90,7 @@ export function parseArgs(argv) {
       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)) {
+    if (["help", "dry-run", "force", "embed-token", "yes", "strict", "compile", "report", "no-report", "json", "no-content", "check", "with-local", "skip-verify", "skip-mcp", "skip-local"].includes(key)) {
       args[key] = true;
       continue;
     }

package/src/adapters/platform/mcpClient.js

@@ -17,7 +17,7 @@ export class McpHttpClient {
     this.url = options.url;
     this.token = options.token;
     this.clientName = options.clientName ?? "gx-code-agent";
-    this.clientVersion = options.clientVersion ?? "0.1.1";
+    this.clientVersion = options.clientVersion ?? "0.1.2";
     this.protocolVersion = options.protocolVersion ?? "2025-06-18";
     this.timeoutMs = Number.isFinite(options.timeoutMs) && options.timeoutMs > 0 ? options.timeoutMs : 30000;
     this.sessionId = null;

package/src/application/doctorCommand.js

@@ -0,0 +1,381 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { McpHttpClient } from "../adapters/platform/mcpClient.js";
+import { readJson } from "../store/localStore.js";
+
+const STDIO_BIN = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../bin/gx-stdio-mcp.js");
+const TOKEN_PATTERN = /^gxmcp_[A-Za-z0-9_-]{43}$/;
+
+/**
+ * 校验 GX MCP API Token 格式。
+ *
+ * @param {string | undefined} token
+ * @returns {{ status: "ok"|"warn"|"fail", message: string, fix?: string }}
+ */
+export function validateToken(token) {
+  if (!token) {
+    return {
+      status: "warn",
+      message: "未设置 GX_API_TOKEN",
+      fix: "在终端 export GX_API_TOKEN='gxmcp_...' 或写入 ~/.zshrc；见 README『快速开始』"
+    };
+  }
+  if (TOKEN_PATTERN.test(token)) {
+    return {
+      status: "ok",
+      message: `格式正确（gxmcp_ + 43 位，共 ${token.length} 字符）`
+    };
+  }
+  return {
+    status: "fail",
+    message: `格式不正确（长度 ${token.length}，应以 gxmcp_ 开头并共 49 字符）`,
+    fix: "重新创建 Token，见 README『快速开始』与 plan/MCPServer/opencode-integration.md 2.4"
+  };
+}
+
+/**
+ * 解析 Node 主版本。
+ *
+ * @param {string} version
+ * @returns {number}
+ */
+export function parseNodeMajor(version) {
+  return Number(String(version).replace(/^v/u, "").split(".")[0]) || 0;
+}
+
+/**
+ * 从 java -version / javac -version 输出中解析主版本。
+ *
+ * @param {string} output
+ * @returns {number}
+ */
+export function parseJavaMajor(output) {
+  const value = String(output ?? "");
+  const quoted = /version\s+"(\d+)(?:\.(\d+))?/u.exec(value);
+  if (quoted) {
+    const major = Number(quoted[1]);
+    return major === 1 ? Number(quoted[2]) : major;
+  }
+  const plain = /(?:javac|openjdk|java)\s+(\d+)(?:\.(\d+))?/iu.exec(value);
+  if (plain) {
+    const major = Number(plain[1]);
+    return major === 1 ? Number(plain[2]) : major;
+  }
+  return 0;
+}
+
+/**
+ * 执行命令并合并 stdout/stderr。
+ *
+ * @param {string} command
+ * @param {string[]} args
+ * @returns {{ ok: boolean, output: string, error?: string }}
+ */
+function commandVersion(command, args) {
+  const result = spawnSync(command, args, {
+    encoding: "utf8",
+    timeout: 5000,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
+  if (result.error) {
+    return { ok: false, output, error: result.error.message };
+  }
+  return { ok: result.status === 0, output, error: result.status === 0 ? undefined : `exit ${result.status}` };
+}
+
+/**
+ * 查找 java/javac 命令。
+ *
+ * @returns {{ java: string, javac: string, home?: string }}
+ */
+function javaCommands() {
+  const home = process.env.JAVA_HOME;
+  if (home) {
+    return {
+      home,
+      java: path.join(home, "bin", "java"),
+      javac: path.join(home, "bin", "javac")
+    };
+  }
+  return { java: "java", javac: "javac" };
+}
+
+/**
+ * 检查本地 stdio MCP。
+ *
+ * @returns {{ status: "ok"|"warn"|"fail", message: string, tools?: string[] }}
+ */
+function checkLocalMcp() {
+  if (!fs.existsSync(STDIO_BIN)) {
+    return { status: "fail", message: `找不到 ${STDIO_BIN}` };
+  }
+  const input = [
+    '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"gx-doctor","version":"1"}}}',
+    '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}',
+    ""
+  ].join("\n");
+  const result = spawnSync(process.execPath, [STDIO_BIN], {
+    input,
+    encoding: "utf8",
+    timeout: 5000
+  });
+  if (result.error) {
+    return { status: "warn", message: `gx-local 启动失败：${result.error.message}` };
+  }
+  if (result.status !== 0) {
+    return { status: "warn", message: `gx-local 退出码 ${result.status}` };
+  }
+  const messages = `${result.stdout ?? ""}`
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+  const tools = messages.find((message) => message.id === 2)?.result?.tools ?? [];
+  if (!Array.isArray(tools) || tools.length === 0) {
+    return { status: "warn", message: "gx-local 未返回 tools/list" };
+  }
+  return {
+    status: "ok",
+    message: `gx-local 可用（${tools.length} 个工具）`,
+    tools: tools.map((item) => item.name).filter(Boolean)
+  };
+}
+
+/**
+ * 检查远端 MCP 连接。
+ *
+ * @param {string} url
+ * @param {string | undefined} token
+ * @returns {Promise<{ status: "ok"|"warn"|"fail"|"skip", message: string, details?: Record<string, unknown> }>}
+ */
+async function checkRemoteMcp(url, token) {
+  if (!token) {
+    return { status: "skip", message: "未提供 Token，跳过远端 MCP 检查" };
+  }
+  const client = new McpHttpClient({
+    url,
+    token,
+    clientName: "gx-doctor",
+    timeoutMs: 5000
+  });
+  try {
+    await client.initialize();
+    const tools = await client.listTools();
+    const ping = await client.callTool("ping", { client: "gx doctor" });
+    let user = null;
+    try {
+      user = await client.callTool("get_current_user", {});
+    }
+    catch {
+      user = null;
+    }
+    return {
+      status: "ok",
+      message: `MCP 可用（协议 ${client.protocolVersion}，工具 ${tools.length} 个）`,
+      details: { protocolVersion: client.protocolVersion, toolCount: tools.length, ping, user }
+    };
+  }
+  catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const httpStatus = Number(/MCP HTTP (\d+)/u.exec(message)?.[1] ?? 0);
+    return {
+      status: "fail",
+      message: httpStatus === 401 ? "MCP 返回 401，Token 无效/过期/已吊销" : `MCP 连接失败：${message}`,
+      details: { httpStatus }
+    };
+  }
+  finally {
+    await client.close().catch(() => {});
+  }
+}
+
+/**
+ * 执行 gx doctor。
+ *
+ * @param {Record<string, unknown>} args
+ * @param {{ stdout: NodeJS.WriteStream, stderr: NodeJS.WriteStream }} [io]
+ * @returns {Promise<Record<string, unknown>>}
+ */
+export async function runDoctor(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 url = String(args.url || config.mcpUrl || "http://127.0.0.1:4013/mcp");
+  const tokenEnv = String(args["token-env"] || "GX_API_TOKEN");
+  const token = typeof args.token === "string" ? args.token : process.env[tokenEnv];
+  const skipMcp = Boolean(args["skip-mcp"]);
+  const skipLocal = Boolean(args["skip-local"]);
+  const strict = Boolean(args.strict);
+  const checks = [];
+
+  const nodeMajor = parseNodeMajor(process.version);
+  checks.push({
+    id: "node",
+    label: "Node.js",
+    status: nodeMajor >= 18 ? "ok" : "fail",
+    message: `${process.version}${nodeMajor >= 18 ? "" : "（需要 >= 18）"}`,
+    ...(nodeMajor >= 18 ? {} : { fix: "升级 Node.js 到 18 或更高版本" })
+  });
+
+  const java = javaCommands();
+  const javaResult = commandVersion(java.java, ["-version"]);
+  const javacResult = commandVersion(java.javac, ["-version"]);
+  const javaMajor = parseJavaMajor(javaResult.output);
+  const javacMajor = parseJavaMajor(javacResult.output);
+  const jdkStatus = javaResult.ok && javacResult.ok && javaMajor >= 9 ? "ok" : "warn";
+  checks.push({
+    id: "jdk",
+    label: "JDK",
+    status: jdkStatus,
+    message: javaResult.ok ? (javaResult.output.split(/\r?\n/u)[0] || `Java ${javaMajor}`) : `java 不可用：${javaResult.error}`,
+    ...(jdkStatus === "ok" ? {} : { fix: "安装 JDK 17，并设置 JAVA_HOME；见 README 环境要求" })
+  });
+  checks.push({
+    id: "javac",
+    label: "javac",
+    status: javacResult.ok && javacMajor >= 9 ? "ok" : "warn",
+    message: javacResult.ok ? javacResult.output.split(/\r?\n/u)[0] : `javac 不可用：${javacResult.error}`,
+    ...(javacResult.ok && javacMajor >= 9 ? {} : { fix: "安装 JDK 17；gx scan --compile 需要 javac" })
+  });
+
+  const tokenCheck = validateToken(token);
+  checks.push({
+    id: "token",
+    label: "GX_API_TOKEN",
+    status: tokenCheck.status,
+    message: tokenCheck.message,
+    ...(tokenCheck.fix ? { fix: tokenCheck.fix } : {})
+  });
+
+  const configPath = path.join(dir, ".gx", "config.json");
+  if (!fs.existsSync(configPath)) {
+    checks.push({
+      id: "config",
+      label: ".gx/config.json",
+      status: "warn",
+      message: "未找到；请先执行 gx init",
+      fix: "gx init --client opencode --plan <planId> --yes"
+    });
+  }
+  else {
+    checks.push({
+      id: "config",
+      label: ".gx/config.json",
+      status: config.planId || config.templateId ? "ok" : "warn",
+      message: `planId=${config.planId ?? "-"}, templateId=${config.templateId ?? "-"}`,
+      ...(config.planId || config.templateId ? {} : { fix: "gx init --plan <planId> --template <templateId> --yes" })
+    });
+  }
+
+  const manifestPath = path.join(dir, ".gx", "manifest.json");
+  if (!fs.existsSync(manifestPath)) {
+    checks.push({
+      id: "manifest",
+      label: ".gx/manifest.json",
+      status: "warn",
+      message: "未找到；请先执行 gx pull",
+      fix: "gx pull --plan <planId> --template <templateId>"
+    });
+  }
+  else {
+    try {
+      const manifest = readJson(manifestPath, {});
+      const fileCount = Array.isArray(manifest.files) ? manifest.files.length : 0;
+      checks.push({
+        id: "manifest",
+        label: ".gx/manifest.json",
+        status: "ok",
+        message: `${fileCount} 个文件，metadataVersion=${manifest.metadataVersion ?? "-"}`
+      });
+    }
+    catch (error) {
+      checks.push({
+        id: "manifest",
+        label: ".gx/manifest.json",
+        status: "fail",
+        message: error instanceof Error ? error.message : String(error),
+        fix: "重新执行 gx pull，不要手工修改 manifest"
+      });
+    }
+  }
+
+  if (skipMcp) {
+    checks.push({ id: "mcp", label: "MCP", status: "skip", message: "使用 --skip-mcp 跳过" });
+  }
+  else {
+    const mcp = await checkRemoteMcp(url, token);
+    checks.push({
+      id: "mcp",
+      label: "MCP",
+      status: mcp.status,
+      message: mcp.message,
+      ...(mcp.details ? { details: mcp.details } : {}),
+      ...(mcp.status === "fail" ? { fix: "检查 MCP 地址、Token、网络；见 plan/MCPServer/opencode-integration.md 第 6 节" } : {})
+    });
+  }
+
+  if (skipLocal) {
+    checks.push({ id: "local", label: "gx-local", status: "skip", message: "使用 --skip-local 跳过" });
+  }
+  else {
+    const local = checkLocalMcp();
+    checks.push({
+      id: "local",
+      label: "gx-local",
+      status: local.status,
+      message: local.message,
+      ...(local.tools ? { details: { tools: local.tools } } : {}),
+      ...(local.status === "fail" ? { fix: "重新安装 gx-code-agent，或检查包内 bin/gx-stdio-mcp.js" } : {})
+    });
+  }
+
+  const summary = {
+    ok: checks.filter((item) => item.status === "ok").length,
+    warn: checks.filter((item) => item.status === "warn").length,
+    fail: checks.filter((item) => item.status === "fail").length,
+    skip: checks.filter((item) => item.status === "skip").length
+  };
+  const ok = strict ? summary.fail === 0 && summary.warn === 0 : summary.fail === 0;
+  const report = {
+    ok,
+    generatedAt: new Date().toISOString(),
+    dir,
+    url,
+    checks,
+    summary
+  };
+
+  if (args.json) {
+    io.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return report;
+  }
+
+  io.stdout.write(`GX Doctor\n`);
+  io.stdout.write(`- 目录: ${dir}\n`);
+  io.stdout.write(`- MCP: ${url}\n\n`);
+  for (const item of checks) {
+    const marker = item.status === "ok" ? "OK" : item.status.toUpperCase();
+    io.stdout.write(`[${marker}] ${item.label}: ${item.message}\n`);
+    if (item.fix) {
+      io.stdout.write(`       修复: ${item.fix}\n`);
+    }
+  }
+  io.stdout.write(`\n汇总: ok=${summary.ok}, warn=${summary.warn}, fail=${summary.fail}, skip=${summary.skip}\n`);
+  if (!ok) {
+    io.stdout.write("结果: 未通过\n");
+  }
+  else {
+    io.stdout.write("结果: 通过\n");
+  }
+  return report;
+}