gx-code-agent 0.0.0-stage → 0.1.1

package/contracts/code-chunk.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gx.local/contracts/code-chunk.schema.json",
+  "title": "GX Code Chunk",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["chunkId", "projectId", "planId", "path", "startLine", "endLine", "granularity", "signature", "layer", "annotations", "frameworkTags", "contentHash", "embedding"],
+  "properties": {
+    "chunkId": { "type": "string", "pattern": "^ck_[a-f0-9]{32}$" },
+    "projectId": { "type": "string", "minLength": 1 },
+    "planId": { "type": "string", "minLength": 1 },
+    "modelId": { "type": ["string", "null"] },
+    "path": { "type": "string", "minLength": 1 },
+    "startLine": { "type": "integer", "minimum": 1 },
+    "endLine": { "type": "integer", "minimum": 1 },
+    "granularity": { "type": "string", "enum": ["file", "class", "method"] },
+    "signature": { "type": "string" },
+    "className": { "type": ["string", "null"] },
+    "methodName": { "type": ["string", "null"] },
+    "layer": { "type": "string" },
+    "annotations": { "type": "array", "items": { "type": "string" } },
+    "frameworkTags": { "type": "array", "items": { "type": "string" } },
+    "intent": { "type": ["string", "null"] },
+    "contentHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "content": { "type": ["string", "null"] },
+    "embedding": { "type": ["array", "null"], "items": { "type": "number" } }
+  }
+}

package/contracts/evidence.schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gx.local/contracts/evidence.schema.json",
+  "title": "GX Evidence",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "evidenceId",
+    "subject",
+    "producer",
+    "operation",
+    "parameters",
+    "normalizedResult",
+    "confidence",
+    "authority",
+    "locations",
+    "coverage",
+    "limitations",
+    "evidenceLinks",
+    "createdAt"
+  ],
+  "properties": {
+    "evidenceId": {
+      "type": "string",
+      "pattern": "^ev_[a-f0-9]{64}$"
+    },
+    "subject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "id", "name", "digest"],
+      "properties": {
+        "kind": {
+          "enum": ["plan", "model", "field", "relation", "index", "generated-file", "extension-file"]
+        },
+        "id": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "path": { "type": "string" },
+        "digest": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["sha256"],
+          "properties": {
+            "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+          }
+        }
+      }
+    },
+    "producer": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "name", "version"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 }
+      }
+    },
+    "operation": { "type": "string", "minLength": 1 },
+    "parameters": { "type": "object" },
+    "normalizedResult": { "type": "object" },
+    "confidence": { "enum": ["observed", "derived", "inferred"] },
+    "authority": {
+      "enum": ["platform-metadata", "generated-code", "extension-code", "cli-scan", "analyst-inference"]
+    },
+    "locations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "path"],
+        "properties": {
+          "kind": { "enum": ["metadata-path", "file"] },
+          "path": { "type": "string", "minLength": 1 },
+          "line": { "type": "integer", "minimum": 1 }
+        }
+      }
+    },
+    "coverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "facets"],
+      "properties": {
+        "status": { "enum": ["complete", "partial", "unknown"] },
+        "facets": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["available"],
+            "properties": {
+              "available": { "type": "boolean" },
+              "reason": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "limitations": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "evidenceLinks": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^ev_[a-f0-9]{64}$" }
+    },
+    "createdAt": { "type": "string", "format": "date-time" }
+  }
+}

package/contracts/examples/alignment.example.json

@@ -0,0 +1,26 @@
+{
+  "planId": "plan-1",
+  "ok": true,
+  "extPointCount": 1,
+  "drift": {
+    "planId": "plan-1",
+    "manifestVersion": 2,
+    "currentVersion": 2,
+    "drifted": [],
+    "missing": [],
+    "extra": [],
+    "reason": null
+  },
+  "missingAnnotations": [],
+  "staleReferences": [],
+  "todos": [],
+  "coverage": {
+    "status": "partial",
+    "facets": {
+      "manifest": { "available": true, "reason": null },
+      "ext_points": { "available": true, "reason": null },
+      "file_hashes": { "available": true, "reason": null },
+      "compilation": { "available": false, "reason": "未执行编译" }
+    }
+  }
+}

package/contracts/examples/code-chunk.example.json

@@ -0,0 +1,20 @@
+{
+  "chunkId": "ck_0123456789abcdef0123456789abcdef",
+  "projectId": "plan-1",
+  "planId": "plan-1",
+  "modelId": null,
+  "path": "src/main/java/demo/OrderService.java",
+  "startLine": 5,
+  "endLine": 9,
+  "granularity": "method",
+  "signature": "OrderService.save()",
+  "className": "OrderService",
+  "methodName": "save",
+  "layer": "service",
+  "annotations": ["Transactional"],
+  "frameworkTags": ["java", "spring"],
+  "intent": "保存订单",
+  "contentHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "content": "public void save(Order order) {}",
+  "embedding": null
+}

package/contracts/examples/evidence.add-field.json

@@ -0,0 +1,49 @@
+{
+  "evidenceId": "ev_119633fc59ff39cb8a96b4680127f08fb97c8ea509a432bdd6761d3fcf0e2a52",
+  "subject": {
+    "kind": "field",
+    "id": "order.amount",
+    "name": "amount",
+    "path": "Plan/Order/amount",
+    "digest": {
+      "sha256": "0000000000000000000000000000000000000000000000000000000000000000"
+    }
+  },
+  "producer": {
+    "id": "gx-mcp",
+    "name": "gx-code-mcp",
+    "version": "1.0.0"
+  },
+  "operation": "add_entity_field",
+  "parameters": {
+    "planId": "plan-1",
+    "modelId": "order",
+    "fieldName": "approvalAmount"
+  },
+  "normalizedResult": {
+    "applied": true,
+    "fieldType": "Long"
+  },
+  "confidence": "observed",
+  "authority": "platform-metadata",
+  "locations": [
+    {
+      "kind": "metadata-path",
+      "path": "Plan/Order/approvalAmount"
+    }
+  ],
+  "coverage": {
+    "status": "complete",
+    "facets": {
+      "metadata": {
+        "available": true
+      },
+      "validation": {
+        "available": true
+      }
+    }
+  },
+  "limitations": [],
+  "evidenceLinks": [],
+  "createdAt": "2026-10-24T10:00:00Z"
+}

package/contracts/examples/evidence.verify-manifest.json

@@ -0,0 +1,52 @@
+{
+  "evidenceId": "ev_c0605367905a6430118cdcc79529c0c8b5dde809d8a2c533d4cda7d2a9e48710",
+  "subject": {
+    "kind": "generated-file",
+    "id": "order",
+    "name": "Order.java",
+    "path": "src/main/java/gx/cn01/order/pojo/entity/Order.java",
+    "digest": {
+      "sha256": "0000000000000000000000000000000000000000000000000000000000000000"
+    }
+  },
+  "producer": {
+    "id": "gx-code-agent",
+    "name": "gx-code-agent",
+    "version": "0.1.0"
+  },
+  "operation": "verify_manifest",
+  "parameters": {
+    "manifestPath": ".gx/manifest.json"
+  },
+  "normalizedResult": {
+    "drifted": [],
+    "missing": [],
+    "extra": []
+  },
+  "confidence": "observed",
+  "authority": "cli-scan",
+  "locations": [
+    {
+      "kind": "file",
+      "path": "src/main/java/gx/cn01/order/pojo/entity/Order.java",
+      "line": 1
+    }
+  ],
+  "coverage": {
+    "status": "partial",
+    "facets": {
+      "generated_files": {
+        "available": true
+      },
+      "compilation": {
+        "available": false,
+        "reason": "未执行 mvn compile"
+      }
+    }
+  },
+  "limitations": [
+    "未执行编译，编译级引用关系未验证"
+  ],
+  "evidenceLinks": [],
+  "createdAt": "2026-10-24T10:05:00Z"
+}

package/contracts/examples/ext-method.example.json

@@ -0,0 +1,14 @@
+{
+  "entity": "Order",
+  "intent": "金额大于 10 万时进入二级审批",
+  "triggers": [
+    "BEFORE_SAVE"
+  ],
+  "class": "OrderApprovalHook",
+  "method": "checkApproval",
+  "codeHash": "f40e1d51669e8cd0e5cb5912c17c9808985836f4ce6254f5db5048025537792b",
+  "fields": [
+    "amount",
+    "status"
+  ]
+}

package/contracts/examples/manifest.example.json

@@ -0,0 +1,13 @@
+{
+  "planId": "plan-1",
+  "metadataVersion": 47,
+  "generatedAt": "2026-10-24T10:00:00Z",
+  "files": [
+    {
+      "path": "src/main/java/gx/cn01/order/pojo/entity/Order.java",
+      "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+      "generated": true
+    }
+  ],
+  "manifestHash": "c4219e4e668a9f5e40201bfcf787f44dad71f99f5c737c2da6093433a78947aa"
+}

package/contracts/examples/unknown.extension-coverage.json

@@ -0,0 +1,29 @@
+{
+  "unknownId": "unk_addbb8e48aba64fd5cbc21d77822d37362e2b237e4edc349a542d3e953ad69e1",
+  "revision": 1,
+  "question": "Order 扩展层是否仍引用已删除字段 amount？",
+  "domain": "metadata-drift",
+  "status": "open",
+  "severity": "high",
+  "scope": {
+    "planId": "plan-1",
+    "modelId": "order",
+    "fieldId": "amount"
+  },
+  "requiredConfidence": "observed",
+  "requiredAuthority": "cli-scan",
+  "supportingEvidenceIds": [
+    "ev_c0605367905a6430118cdcc79529c0c8b5dde809d8a2c533d4cda7d2a9e48710"
+  ],
+  "contradictingEvidenceIds": [],
+  "recommendedProbes": [
+    {
+      "operation": "gx scan",
+      "rationale": "重新扫描扩展层引用"
+    }
+  ],
+  "resolution": null,
+  "mutationEvidenceIds": [
+    "ev_c0605367905a6430118cdcc79529c0c8b5dde809d8a2c533d4cda7d2a9e48710"
+  ]
+}

package/contracts/ext-method.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gx.local/contracts/ext-method.schema.json",
+  "title": "GX ExtMethod Declaration",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "entity",
+    "intent",
+    "triggers",
+    "class",
+    "method",
+    "codeHash"
+  ],
+  "properties": {
+    "entity": {
+      "type": "string",
+      "minLength": 1
+    },
+    "intent": {
+      "type": "string",
+      "minLength": 1
+    },
+    "triggers": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "class": {
+      "type": "string",
+      "minLength": 1
+    },
+    "method": {
+      "type": "string",
+      "minLength": 1
+    },
+    "codeHash": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "fields": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "file": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  }
+}

package/contracts/manifest.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gx.local/contracts/manifest.schema.json",
+  "title": "GX Generation Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["planId", "metadataVersion", "generatedAt", "files", "manifestHash"],
+  "properties": {
+    "planId": { "type": "string", "minLength": 1 },
+    "metadataVersion": { "type": "integer", "minimum": 1 },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "files": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "sha256", "generated"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+          "generated": { "type": "boolean" }
+        }
+      }
+    },
+    "manifestHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+  }
+}

package/contracts/unknown.schema.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gx.local/contracts/unknown.schema.json",
+  "title": "GX Residual Unknown",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "unknownId",
+    "revision",
+    "question",
+    "domain",
+    "status",
+    "severity",
+    "scope",
+    "requiredConfidence",
+    "requiredAuthority",
+    "supportingEvidenceIds",
+    "contradictingEvidenceIds",
+    "recommendedProbes",
+    "resolution",
+    "mutationEvidenceIds"
+  ],
+  "properties": {
+    "unknownId": {
+      "type": "string",
+      "pattern": "^unk_[a-f0-9]{64}$"
+    },
+    "revision": { "type": "integer", "minimum": 1 },
+    "question": { "type": "string", "minLength": 1 },
+    "domain": {
+      "enum": ["metadata-drift", "extension-coverage", "generated-drift", "migration"]
+    },
+    "status": {
+      "enum": ["open", "investigating", "blocked", "contradicted", "resolved"]
+    },
+    "severity": { "enum": ["low", "medium", "high", "critical"] },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["planId"],
+      "properties": {
+        "planId": { "type": "string", "minLength": 1 },
+        "modelId": { "type": "string" },
+        "fieldId": { "type": "string" },
+        "filePath": { "type": "string" }
+      }
+    },
+    "requiredConfidence": { "enum": ["observed", "derived", "inferred"] },
+    "requiredAuthority": {
+      "enum": ["platform-metadata", "generated-code", "extension-code", "cli-scan", "analyst-inference"]
+    },
+    "supportingEvidenceIds": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^ev_[a-f0-9]{64}$" }
+    },
+    "contradictingEvidenceIds": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^ev_[a-f0-9]{64}$" }
+    },
+    "recommendedProbes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["operation", "rationale"],
+        "properties": {
+          "operation": { "type": "string", "minLength": 1 },
+          "rationale": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "resolution": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["disposition", "rationale", "evidenceIds"],
+          "properties": {
+            "disposition": { "enum": ["verified", "withdrawn", "out-of-scope"] },
+            "rationale": { "type": "string", "minLength": 1 },
+            "evidenceIds": {
+              "type": "array",
+              "items": { "type": "string", "pattern": "^ev_[a-f0-9]{64}$" }
+            }
+          }
+        }
+      ]
+    },
+    "mutationEvidenceIds": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^ev_[a-f0-9]{64}$" }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "status": { "const": "resolved" } },
+        "required": ["status"]
+      },
+      "then": {
+        "properties": {
+          "resolution": { "type": "object" }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": { "status": { "const": "contradicted" } },
+        "required": ["status"]
+      },
+      "then": {
+        "properties": {
+          "contradictingEvidenceIds": { "type": "array", "minItems": 1 }
+        }
+      }
+    }
+  ]
+}

package/eval/README.md

@@ -0,0 +1,52 @@
+# 代码检索评测集
+
+`code-search-eval.json` 用于评估平台 `search_code` 的混合检索质量。
+
+## 用法
+
+```bash
+GX_API_TOKEN=gxmcp_xxx gx eval-search \
+  --plan <planId> \
+  --dataset eval/code-search-eval.json \
+  --limit 5 \
+  --out .gx/eval-search.json
+```
+
+指标：
+
+- `HitRate@K`：前 K 条命中期望文件/签名的比例；
+- `MRR`：首个正确命中的平均倒数排名；
+- `avgLatencyMs`：平均检索延迟；
+- `embeddingAvailableCount`：语义检索实际启用的 query 数。
+
+## 数据集格式
+
+```json
+{
+  "planId": "1187804490695311360",
+  "cases": [
+    {
+      "id": "c01",
+      "query": "故障",
+      "tags": ["keyword"],
+      "expectedAny": [
+        { "path": "defaultService/src/main/java/.../WkMalfunctionController.java" },
+        { "pathSuffix": "wkProjectTreeLeftMenu.vue" },
+        { "signature": "WkMalfunctionHook.fillDefaultName()" }
+      ]
+    }
+  ]
+}
+```
+
+`expectedAny` 任一项命中即算正确。
+
+## wk1 基线（2026-10-25）
+
+- 14 条 query
+- HitRate@5：`1.0`
+- MRR：`0.9524`
+- 平均延迟：`835ms`
+- 语义检索可用：`14/14`
+
+其他项目建议复制本文件并按自身模块补充 query 与期望。