gx-code-agent

GX 高代码平台的伴生 CLI。M0 阶段提供 gx init：一次性完成 MCP Server 注册与平台规范注入。

环境要求

• Node.js 18+

安装

从公共 npm 安装（推荐）

# 主 CLI
npm i -g [email protected]
npx --yes [email protected] --help

# 独立本地 MCP 启动器
npx --yes gx-mcp-local

包名、版本与发布流程见 RELEASE.md。公共 npm 发布若遇到 2FA/E403，使用 npm run publish:public -- --otp=<验证码> 或 granular token（需 Bypass 2FA）。

本地开发

cd gx-code-agent
npm ci
npm link

或直接：

node bin/gx.js --help

快速开始

export GX_API_TOKEN=gxmcp_xxx
gx init --client opencode \
  --url http://127.0.0.1:4013/mcp \
  --plan <planId> --template <templateId> \
  --with-local --yes

初始化会做以下事情：

1. 写入客户端 MCP 配置（OpenCode / Claude / Cline）；
2. 写入 timeout，避免 generate_code / search_code 过大会话超时；
3. 把平台规范 + 项目绑定（planId/templateId/生成层目录）注入 AGENTS.md / CLAUDE.md，带标记块，重复执行不会重复追加；
4. 可选地把 planId/templateId 写入 .gx/config.json；
5. 可选注册本地 stdio MCP gx-local（--with-local）；
6. 写入 .gx/.gitignore，忽略 backup/、generated/ 等本地文件；
7. 写入前把已存在的配置文件备份到 .gx/backup/<timestamp>/，并保留最近 5 次；
8. 初始化后调用 ping、tools/list、get_current_user，输出连接状态、工具数量和 Token scopes（可用 --skip-verify 跳过）。

默认写入的是环境变量引用（如 Bearer {env:GX_API_TOKEN}），不会把明文 Token 落盘。只有显式加 --embed-token 才会写入明文，此时请勿提交对应配置文件。

配置格式：

• 默认 --opencode-format legacy：写 mcp.gx-code，兼容 OpenCode 1.x / 2.x；
• --opencode-format v2：写 mcp.servers.gx-code，使用 2.x 原生格式与对象 timeout；
• --timeout <ms>：远端 MCP 超时，默认 180000。

支持的客户端

| 客户端 | 写入文件 | 说明 | |---|---|---| | opencode | opencode.json | mcp.gx-code，type: remote，oauth: false | | claude | .mcp.json | mcpServers.gx-code，type: http | | cline | .gx/cline-mcp-settings.json | 生成片段，需合并到 Cline 的 MCP 设置 |

命令

gx init [--client opencode|claude|cline] [--url <url>] [--token <token>] \
        [--token-env <name>] [--embed-token] [--plan <planId>] [--template <templateId>] \
        [--generated-dir <dir>] [--dir <path>] [--with-local] \
        [--opencode-format legacy|v2] [--timeout <ms>] \
        [--check] [--skip-verify] [--yes] [--dry-run]
gx pull  --plan <planId> --template <templateId> [--model-ids a,b] [--url <url>] [--token <token>] [--dry-run]
gx apply [--dir <path>] [--dry-run] [--force]
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 context --task "<任务描述>" [--plan <planId>] [--model-ids a,b] [--limit 5] \
           [--out .gx/context.md|-] [--offline] [--json] [--strict]
gx sync [--dir <path>] [--plan <planId>] [--source-dir a,b] [--compile] \
        [--classpath <cp>] [--no-report] [--no-content] [--json] [--strict]
gx adopt [--dir <path>] [--source-dir a,b] [--compile] [--classpath <cp>] \
         [--out .gx/adopt.md|-] [--json] [--strict]
gx version
gx help

• Token 优先取 --token，其次取环境变量（默认 GX_API_TOKEN，可用 --token-env 改名）。
• 默认写入环境变量引用；--embed-token 才会写入明文。
• --dry-run 只打印将写入的内容与 diff，不落盘。
• --check 只检查配置与连接，不写入；配置需要更新时退出码 1。检查时请带上与初始化相同的 --client/--with-local/--opencode-format 选项，否则会报告差异。
• --with-local 同时注册 gx-local 本地 stdio MCP。
• --skip-verify 跳过初始化后的连接检查（CI / 离线环境使用）。
• 非交互模式写入必须带 --yes，否则退出码 2。
• 不支持的客户端会直接报错，不会猜测格式。

诊断：gx doctor

# 人类可读
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。

任务上下文：gx context

# 在线：调用平台 get_task_context，生成本地 Markdown
export GX_API_TOKEN=gxmcp_xxx
gx context --task "为 Order 增加大额订单审批" --plan <planId>

# 离线：只使用 .gx/config.json、manifest、扩展点、切片
gx context --task "订单审批金额" --offline

# 输出到 stdout
gx context --task "订单审批" --offline --out -

# 机器可读摘要
gx context --task "订单审批" --offline --json

输出默认写入 .gx/context.md，包含：

• 模型摘要、关系、扩展点、扩展文件；
• 代码命中（在线来自 search_code，离线来自 .gx/chunks.json 关键词匹配）；
• 平台规范快照；
• 最近审计；
• 本地 manifest / 扩展点 / 切片 / 对账状态；
• 覆盖范围、限制与建议步骤。

在线失败时默认回退离线模式并提示；--strict 下直接报错。

一键同步：gx sync

gx sync 按顺序执行：

1. gx scan：扫描 @ExtMethod，有 Token 时上报扩展点；
2. gx audit：复用本次 scan 结果，调用 audit_alignment，合并本地/平台 Unknown；
3. gx chunks：生成本地切片，有 Token 时上报 record_code_chunks。

# 有 Token：scan 上报扩展点 → audit 对账 → chunks 上报切片
export GX_API_TOKEN=gxmcp_xxx
gx sync --plan <planId> --source-dir src/main/java

# 离线 / CI：只做本地扫描、对账、切片
gx sync --no-report --source-dir src/main/java

# 编译级引用检查
gx sync --compile --classpath target/classes --source-dir src/main/java

# 机器可读摘要
gx sync --no-report --json

说明：

• audit 复用 scan 结果，不会重复上报 record_ext_points；
• --no-report 时 scan/audit/chunks 都不写平台；
• --strict 时 audit 待办、缺注解、切片拒绝都视为失败；
• 退出码：任一步失败或 audit 未通过为 1。

存量归位：gx adopt

gx adopt 只做仓库侧盘点，不自动修改生成层、不自动迁移自定义块。

# 生成报告
gx adopt --source-dir src/main/java

# 输出到 stdout
gx adopt --source-dir src/main/java --out -

# 机器可读
gx adopt --source-dir src/main/java --json

# CI：存在未登记/漂移/缺失/缺注解时退出码 1
gx adopt --source-dir src/main/java --strict

报告写入：

• .gx/adopt.json
• .gx/adopt.md

检查内容：

• manifest 中的生成文件与带 @generated GX-CODE / [CN01-GENERATED] 标记的文件；
• 生成文件中的 [CN01-*] 自定义块；
• manifest 漂移、缺失、未登记生成文件；
• 扩展点与缺 @ExtMethod 的公开方法；
• 扩展文件清单与人工复核建议。

边界：数据库 Schema → 平台元数据的反向同步在平台侧执行；CLI 不直接连接数据库，也不会自动覆盖生成层。

M3：拉取 / 应用 / 校验

# 1. 从平台拉取生成结果（Token 只放环境变量，不落盘）
export GX_API_TOKEN=gxmcp_xxx
gx pull --plan plan-1 --template tpl-1

# 2. 预览 apply
gx apply --dry-run

# 3. 应用；保留块内的用户代码不会被覆盖
gx apply

# 4. 已确认生成层被手改，强制覆盖
gx apply --force

# 4. CI 使用严格模式：manifest 缺失或漂移都会失败
gx verify --strict

gx pull 会写入：

• .gx/generated/<path>：平台返回的生成文件
• .gx/manifest.json：文件 sha256 与 metadataVersion
• .gx/pull.json：本次拉取信息

gx verify 只校验生成骨架；保留块内部内容归用户所有，不参与漂移判断。

gx apply 会先做预检：如果目标文件的生成骨架在最近一次 apply 后被修改，默认拒绝覆盖并提示使用 gx apply --force。首次 apply 没有历史指纹时会给出警告，但仍允许执行。

M4：扩展点与对账

扩展层公开方法使用平台注解：

@ExtMethod(entity = "Order", intent = "大额订单二级审批",
           triggers = {"BEFORE_SAVE"}, fields = {"amount"})
public void checkApproval(Order order) { ... }

# 解析 @ExtMethod；配置了 planId + Token 时自动上报 record_ext_points
gx scan

# AST 扫描 + 编译扩展层（JDK 9+；推荐 JDK 17，可用 JAVA_HOME/JAVAC 指定）
gx scan --compile --classpath pig-upms/gx-util-api/target/classes

# 只扫描不上报
gx scan --no-report

# 上报扩展点、校验 manifest、调用 audit_alignment，输出待办清单
gx audit
gx audit --strict   # 有待办时退出码 1

# 精简 CI 示例：失败即阻断
gx audit --no-report --strict

gx scan 优先使用 JDK Compiler Tree API（AST）识别公开方法与 @ExtMethod；JDK 不可用时自动回退正则，并在 coverage.facets.ast_scan 中标记。--compile 通过 javac 校验类型引用，未解析的类型会写入 compilation.errors 并让 --strict 失败。

gx audit 输出三类待办：

1. MISSING_EXT_METHOD：扩展层公开方法缺少 @ExtMethod；
2. STALE_EXT_REFERENCE：已上报扩展点引用了已删除/不存在的实体或字段（@ExtMethod.fields）；
3. FILE_DRIFTED / FILE_MISSING / MANIFEST_*：manifest 与工作区不一致。

扫描结果写入 .gx/ext-points.json，对账结果写入 .gx/audit.json；共享契约见 contracts/alignment.schema.json。

M5：代码切片与检索

# 本地生成 Java/Vue 方法级/类级切片，写入 .gx/chunks.json
gx chunks --no-report

# 生成并上报 record_code_chunks（配置 planId + GX_API_TOKEN）
gx chunks

# 数据敏感环境：只上报元数据，不上传切片内容
gx chunks --no-content

Java 切片优先使用 JDK Compiler Tree API（AST）生成类/方法边界、行号与注解；JDK 不可用时自动回退正则。coverage.facets.chunking.engine 会标记 ast 或 regex。

平台侧使用 search_code 做“关键词 + AST 标签 + pgvector 语义”混合检索（layer、granularity、annotations、frameworkTags）。CLI 上报时 embedding 可为空，平台会按切片内容自动向量化并写入 pgvector；未配置 EmbeddingModel 时自动降级为关键词检索。

检索评测

gx eval-search --plan <planId> \
  --dataset eval/code-search-eval.json \
  --limit 5 --out .gx/eval-search.json

输出 HitRate、MRR、平均延迟与每条 query 的命中排名。评测集位于 eval/code-search-eval.json，可按项目复制扩展。

本地 stdio MCP

gx-mcp-local 提供不依赖平台的本地 MCP 工具：

• local_verify_manifest：校验工作区与 .gx/manifest.json；
• local_scan_ext_points：扫描 @ExtMethod、缺注解方法与编译结果；
• local_config：读取 .gx/config.json 与 manifest/applied/chunks 等状态；
• local_chunks：本地预览代码切片，不写文件、不上报、不做 Embedding；
• local_audit：本地 verify + scan + Unknown 汇总，不调用平台。

本地工具全部只读，不替代平台 HTTP MCP；实现说明见 gx-cloud-frp/plan/MCPServer/cli-07-local-mcp-plan.md。

OpenCode / Claude Code 本地配置示例：

{
  "mcp": {
    "gx-local": {
      "type": "local",
      "command": ["npx", "gx-mcp-local"],
      "enabled": true
    }
  }
}

也可直接用 node bin/gx-stdio-mcp.js 启动（JSON-RPC over stdio）。

npx gx-mcp-local 使用独立包 gx-mcp-local，它会调用已安装的 gx-code-agent； 未发布或离线时请使用 node /absolute/path/gx-code-agent/bin/gx-stdio-mcp.js。

CI

• GitLab：ci/gitlab-ci-gx-verify.yml
• GitHub Actions：ci/github-actions-gx-verify.yml

CI 默认执行：

1. gx verify --strict：阻断生成层漂移；
2. gx scan --no-report：输出 gx-scan.json artifact；
3. 配置 GX_API_TOKEN（可选 GX_PLAN_ID）后执行 gx audit --no-report --strict，阻断缺注解/失效引用/manifest 漂移。

CI 变量：

| 变量 | 说明 | |---|---| | GX_AGENT_VERSION | 固定 CLI 版本，默认 0.1.6 | | NPM_REGISTRY | npm registry；默认 https://registry.npmjs.org/ | | GX_API_TOKEN / GX_PLAN_ID | MCP 鉴权与方案范围 |

发布流水线：

• GitHub Actions：.github/workflows/publish.yml
• GitLab：ci/gitlab-ci-publish.yml
• 发布步骤、公共 npm 登录与双包发布见 RELEASE.md。

验证

node --test

当前：CLI 53/53；平台侧 Java MCP 80/80。

当前进度与后续

已完成：

• M3：gx pull / gx apply / gx verify
• M4：@ExtMethod / gx scan / gx audit / record_ext_points / audit_alignment
• M5：gx chunks / record_code_chunks / search_code（关键词 + AST 标签 + pgvector 语义）
• P5：apply 漂移预检、AST 扫描、编译级引用验证
• P6：真实方案 wk1 完成 pull/apply/verify/scan/audit/chunks/search 全链路验收（2146 切片、语义检索通过）
• 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
• CLI-04：gx context 生成 .gx/context.md，在线 get_task_context + 离线本地兜底
• CLI-05：gx sync 编排 scan → audit → chunks，替代独立 gx push
• CLI-06：gx adopt 存量项目归位盘点，输出 .gx/adopt.md / .gx/adopt.json
• CLI-07：本地 stdio MCP 扩展为 5 个只读工具（config/chunks/audit 已补齐）

待办：

• gx context / gx push / gx adopt
• Agent 外壳（本地 stdio MCP 已提供基础版）
• 公共 npm 已发布 [email protected] 与 [email protected]

与主平台的关系

MCP Server 运行在 gx-cloud-frp/pig-code-biz，本仓库只负责开发者侧的注册、校验与代码文件操作。平台保证结构元数据唯一事实源；本 CLI 负责开发者仓库侧的文件级校验。