sub2api-cn-relay-manager/docs/2026-06-03-CODEGRAPH-INTEGRATION.md

CodeGraph Workspace 接入说明（2026-06-03）

本文档记录本项目如何接入 /home/long/project 工作区级 codegraph 搜索基础设施。

0. 状态摘要（2026-06-03 rollout 完成）

指标	状态
工作区级 codegraph 契约	✅ /home/long/project/CODEGRAPH_WORKSPACE_USAGE.md
已索引 repo	16/16
有项目级 OMP 规则	16/16（之前 8/16 → 全部补齐）
codegraph-workspace wrapper bug 修复	✅ 2026-06-03 patch
本项目（sub2api-cn-relay-manager）.agent/AGENTS.md	✅ 158 行，反映 frontend 重构
本项目 understand-anything graph	✅ 离线刷新 2026-06-03（4048 nodes / 2256 edges / 0 schema issues）
工作区级 understand-anything graph 刷新	✅ 16/16 repo 全部 0 schema fatal（15 batch + sub2api-cn-relay-manager 单独）

1. 工作区级入口

所有 agent 共用的 codegraph 使用契约在：

/home/long/project/CODEGRAPH_WORKSPACE_USAGE.md

那份文档是工作区根元文档（不在 git 仓库里），包含 16 个 repo 的索引清单、查询路由规则、各 agent 入口、验证方法、能力边界。

2. 本项目对 codegraph workspace 的贡献

资源	状态	位置
CodeGraph 索引	✅	~/.codegraph/projects.json 含 sub2api-cn-relay-manager
OMP 项目规则	✅	<repo>/.agent/AGENTS.md（158 行，2026-06-03 更新）
工作区 usage 文档	✅（已贡献）	/home/long/project/CODEGRAPH_WORKSPACE_USAGE.md
wrapper 修复	✅（已 patch）	/home/long/.local/bin/codegraph-workspace（备份 .bak-2026-06-03）

3. 本项目对其他 agent 的入口信号

其他 agent 第一次进到 /home/long/project/sub2api-cn-relay-manager 时，应该按以下顺序加载上下文：

1. 仓库根 AGENTS.md（60 行）— 项目硬约束 + 质量门禁
2. docs/EXECUTION_BOARD.md — 当前任务执行板
3. 本文件（docs/2026-06-03-CODEGRAPH-INTEGRATION.md）— 工作区搜索层接入说明
4. <repo>/.agent/AGENTS.md（OMP 专用）— OMP / oh-my-pi 项目级补充规则
5. ~/.codegraph/projects.json — 工作区索引状态
6. /home/long/project/CODEGRAPH_WORKSPACE_USAGE.md — 工作区使用契约

4. 实际验证（2026-06-03）

# 1. 索引存在
$ grep '"sub2api-cn-relay-manager"' ~/.codegraph/projects.json
# 命中

# 2. 项目级 OMP 规则存在（不在仓库根 .gitignore 内）
$ ls -l /home/long/project/sub2api-cn-relay-manager/.agent/AGENTS.md
-rw-rw-r-- 1 long long 9604  6月  3 13:26 AGENTS.md

# 3. codegraph-workspace 能查到本次 frontend 重构的产物
$ /home/long/.local/bin/codegraph-workspace search sub2api-cn-relay-manager 'portal.css'
=== sub2api-cn-relay-manager :: /home/long/project/sub2api-cn-relay-manager ===
/home/long/project/sub2api-cn-relay-manager/docs/EXECUTION_BOARD.md
/home/long/project/sub2api-cn-relay-manager/deploy/tksea-portal/admin-batch-import.html
... (命中 deploy/tksea-portal/portal.css 等新文件)

$ /home/long/.local/bin/codegraph-workspace search sub2api-cn-relay-manager 'Sub2ApiPortal'
=== sub2api-cn-relay-manager :: /home/long/project/sub2api-cn-relay-manager ===
/home/long/project/sub2api-cn-relay-manager/docs/2026-06-03-FRONTEND-DESIGN-SYSTEM-RUNBOOK.md
/home/long/project/sub2api-cn-relay-manager/docs/EXECUTION_BOARD.md
... (命中 deploy/tksea-portal/portal.js 与 runbook 引用)

# 4. def 对 inline JS function 的能力边界（实测）
$ /home/long/.local/bin/codegraph-workspace def sub2api-cn-relay-manager 'refreshAdminSession'
===  Finding definitions of: refreshAdminSession
(空，因为 refreshAdminSession 在 HTML inline <script> 里)
# → 印证 skill 文档：inline JS function 走 search_files fallback，而不是 def

5. 2026-06-03 rollout 实测（其他 7 个 repo 的接入）

Repo	AGENTS.md 行数	codegraph-workspace 命中关键字	状态
ai-customer-service	75	IMPLEMENTATION_PLAN ✓	✅
contract management	95	OpenSpec ✓	✅（路径含空格）
shenyi	87	WARP.md ✓	✅（用户主力项目）
sub2api	95	国产模型 ✓	✅（上游 mirror）
sub2api-official-fresh	90	CLA.md ✓	✅（宿主参考，不改源码）
supply-intelligence	65	POLLER_RUNTIME_BOUNDARY ✓	✅
tokens-reef	73	MERGE_GUIDE ✓	✅（tksea pham 命名空间）

codegraph-workspace list 最终结果：16 AGENTS / 0 missing。

6. wrapper 修复（2026-06-03）

codegraph-workspace 第 29 行原来只检查 <repo>/AGENTS.md 仓库根存在性，但 OMP 实际读的是 <repo>/.agent/AGENTS.md。已 patch（备份在 codegraph-workspace.bak-2026-06-03）：

'has_agents': (p / 'AGENTS.md').exists() or (p / '.agent' / 'AGENTS.md').exists(),

效果：list 输出的 AGENTS 标志现在准确反映 OMP 实际可读到的规则文件。

⚠️ 重装或升级 codegraph-workspace 时必须重做这个 patch。详见 ~/.hermes/skills/software-development/codegraph-workspace-operations/SKILL.md 的 Pitfalls 节。

7. OMP 可发现性 — 当前限制

按 codegraph-workspace-operations skill 的标准做法，新写 .agent/AGENTS.md 后应该用：

OMP_NO_UPDATE_NOTIFIER=1 omp -p --cwd /home/long/project/sub2api-cn-relay-manager \
  "show me your current project rules"

本机当前实测（2026-06-03）: OMP 返回 403 余额不足，验证不可用。

代替证据：

1. 物理文件存在（ls -l .agent/AGENTS.md）
2. ~/.codegraph/projects.json has_agents: true
3. codegraph-workspace search 能命中项目内容

OMP quota 恢复后请补一次实测并把结果记到本文件第 4 节。

8. understand-anything 离线接入（2026-06-03）

本节记录本项目如何用 understand-anything-offline 脚本刷新 .understand-anything/knowledge-graph.json，不依赖任何 LLM（quota 欠费时唯一可用路径）。

8.1 为什么需要离线版本

/understand --full 走 Claude Code / OMP / OpenCode 调 LLM 增强 graph（生成 summary / tags / tour）。本机 OMP / Claude Code 均 403 余额不足，zhipu 5 分钟无响应 — 完整 pipeline 跑不了。

但 understand-anything 的 core 包（packages/core/dist/index.js）的 GraphBuilder + TreeSitterPlugin + 12 个 bundled parsers（md/yaml/json/html/css/sql/...）都是纯本地 — 离线也能跑。

8.2 本次刷新结果

$ ~/.local/bin/understand-anything-offline /home/long/project/sub2api-cn-relay-manager
[offline] project: sub2api-cn-relay-manager
[offline] tree-sitter ready (typescript, javascript, python, go, rust, java, ruby, php, c, cpp, csharp)
[offline] walking repo...
[offline] found 1792 files (after ignore filter)
[offline] processed: 565 code, 1227 non-code, 0 errors
[offline] built: 4048 nodes, 2256 edges
[offline] backing up existing graph to .bak-2026-06-03
[offline] wrote .understand-anything/knowledge-graph.json
[offline] done.

指标	旧 graph（2026-06-01 LLM-driven）	新 graph（2026-06-03 离线）	变化
Nodes	1678	4048	+2.4x
Edges	1678	2256	+34%
Node types	6 (concept/config/document/file/service/table)	6 (class/config/document/file/function/schema)	改了类目
File size	1.34MB	2.12MB	+58%
Schema issues	(unknown)	0	✅
反映 commits	仅 2026-06-01 之前	全部 28 commits / 9573 行新代码	✅
备份	(无)	.bak-2026-06-03	✅

关键验证（13/13 通过）：portal.css / portal.js / admin-common.css / admin/index.html / admin/providers.html / admin/accounts.html / admin-batch-import.html / prometheus-rules.yml / grafana-dashboard.json / metrics.go / errs/common.go / frontend design runbook / codegraph integration note 全部在 graph 里。

8.3 怎么用

# 1. 单 repo
~/.local/bin/understand-anything-offline /home/long/project/<repo>

# 2. 批量
for repo in sub2api-cn-relay-manager ai-ops llm-intelligence; do
  ~/.local/bin/understand-anything-offline /home/long/project/$repo
done

# 3. 验证
node -e "
import('/home/long/.understand-anything/repo/understand-anything-plugin/packages/core/dist/index.js').then(({validateGraph}) => {
  const g = JSON.parse(require('fs').readFileSync('/home/long/project/<repo>/.understand-anything/knowledge-graph.json', 'utf8'));
  const r = validateGraph(g);
  console.log('issues:', r.issues?.length || 0);
});
"

8.4 已知限制

• summary / tags / tour 字段是 placeholder "(no summary — offline mode, no LLM)" — 不像 /understand --full 那样有 LLM 生成的智能摘要
• node type 类目偏窄（6 种 vs LLM-driven 的更多）— concept / service / table 等类目在离线模式下不会出现
• import 边稀疏 — addImportEdge 路径解析对 Go 内部 import 不太准
• portal.js 0 functions — tree-sitter JS parser 对 window.Sub2ApiPortal = { ... } 模式不识别顶层方法
• .understand-anything/ 在 .gitignore — graph 是 runtime artifact 不进 git，跟 .agent/AGENTS.md 一致

8.5 Quota 恢复后的迁移路径

1. 跑 claude -p "/understand --full" --cwd /home/long/project/sub2api-cn-relay-manager 生成 LLM-enriched graph
2. 备份当前离线 graph: cp .understand-anything/knowledge-graph.json .bak-2026-06-03-offline
3. LLM graph 会覆盖 knowledge-graph.json，但 nodes 数量通常少于离线 graph（LLM 会 consolidate / filter）
4. 如果需要，用离线 graph 作为 baseline，LLM graph 作为 enrichment — 可以写一个 merge 脚本

详见 ~/.hermes/skills/software-development/understand-anything-offline/SKILL.md。

8.6 工作区级 batch 刷新（2026-06-03 14:28-14:29）

# 跑 15 个 repo（含 sub2api-cn-relay-manager 单独跑过）
~/.local/bin/understand-anything-offline-batch
# 67 秒，15/15 成功

维度	值
总文件数	55,628
总 nodes	332,980
总 edges	280,478
总 graph 磁盘占用	169MB
Schema fatal	0
自动备份	每 repo .bak-2026-06-03（旧 6月1日 LLM-driven graph）

batch 跳过（无 .git）：1024-smart-admin / 开源项目评估 / ai-customer-service-lijiaoqiao-snapshot-2026-05-08 / bridge / gongju / hermes-agent-evolution / quant-trading（其中 bridge 保留 6月1日 旧 graph，0 fatal）

详见 ~/.hermes/docs/2026-06-03-UNDERSTAND-ANYTHING-BATCH.md（完整 batch report）。

9. 后续维护

• 本项目新增/重构时：
  1. 在 docs/EXECUTION_BOARD.md 加条目
  2. 若有 .agent/AGENTS.md 引用过的真相文件，同步更新 .agent/AGENTS.md
  3. 跑 codegraph-workspace refresh sub2api-cn-relay-manager 让索引反映新代码
• OMP quota 恢复后立即补上第 7 节的实测
• 任何本项目接入 codegraph workspace 的规则变更，先在 /home/long/project/CODEGRAPH_WORKSPACE_USAGE.md 改，再回本文件
• 如果 codegraph-workspace wrapper 被重装或升级，必须重做第 6 节的 patch（备份 .bak-2026-06-03 可作参考）
• 任何本项目接入 codegraph workspace 的规则变更，先在 /home/long/project/CODEGRAPH_WORKSPACE_USAGE.md 改，再回本文件

9. understand-anything LLM enrichment (online, 2026-06-03 14:53-15:02)

状态

• 16/16 git repo + gongju 跑通 LLM enrich
• 总计 ~360 个 file 节点 patch 了 summary / tags / complexity
• set-and-forget 模式：callWithFallback 自动跟 agent 当前模型 + 撞 quota 自动转 fallback_providers 链

9.1 set-and-forget 升级 (15:20-15:25)

新行为：enrich 默认走 fallback chain

1. 当前 agent 模型 (minimax-m3/MiniMax-M3) — 来自 model: 段
2. openai-zhongzhuan/gpt-5.4 — fallback_providers: 第一项
3. a7m-kimi/kimi-k2.6 — 第二项
4. deepseek-official/deepseek-chat — 最后兜底

跳过 transport: codex_responses 的 provider（openai-zhongzhuan）— 该 transport 走 /v1/responses 端点，与 /v1/chat/completions 不兼容。

__default._providerModel 解析：优先用 provider 的 default_model 字段（端点真实可用的 model name），不是 user-config default: 别名。例如 minimax-m3 provider 的 default_model: MiniMax-M3 在 mimimax.cn/v1/chat/completions 端点上对应 grok-4.20-reasoning，__default._providerModel 正确解析为后者。

Strip <think>...</think> 块：minimax-m3/MiniMax-M3 输出含 thinking 块会污染 JSON 解析 — 自动 regex 移除。

显式 --provider 不走 fallback 链：单 provider 调用，方便调试和稳定输出。

用法对比

场景	命令	行为
set-and-forget（默认）	understand-anything-enrich <repo>	fallback chain (minimax-m3 → gpt-5.4 → kimi-k2.6 → deepseek)
强制当前模型	understand-anything-enrich <repo> --provider minimax-m3	不 fallback
大 repo 快跑	understand-anything-enrich <repo> --provider deepseek-official --model deepseek-chat	1.3s/file
批处理默认	understand-anything-enrich-batch <ws>	每个 repo 走 fallback chain
批处理快跑	understand-anything-enrich-batch <ws> --provider deepseek-official	整个 batch 用 deepseek

工具

• ~/.local/bin/understand-anything-enrich (9.1 KB Node ESM, v2)
• ~/.local/bin/ua-provider-config.mjs (5.3 KB, 加 callWithFallback)
• ~/.local/bin/understand-anything-enrich-batch (2.7 KB bash wrapper)
• ~/.hermes/skills/software-development/understand-anything-enrich/SKILL.md (skill, 8 pitfalls + cheat sheet)

验证

• 抽检 sub2api-cn-relay-manager / gongju / contract management / llm-intelligence / user-system / supply-intelligence — Dockerfile / .env.example / hooks summary 全部准确
• quality 合理：complex=complex 给 simplify-ignore.sh（多 file 引用），simple 给 .env.example（10 行）
• 5/5 跑通 fallback chain，0 失败（minimax-m3 当前模型直接出活）
• big repo (新api/公文助手/区块链商城/立交桥) 仍 5000-50000 placeholder — honest trade-off，360 LLM 调用 7 分钟可接受

完整报告

详见 ~/.hermes/docs/2026-06-03-UNDERSTAND-ANYTHING-ENRICH-BATCH.md

恢复

cp <repo>/.understand-anything/knowledge-graph.json.bak-2026-06-03 \
   <repo>/.understand-anything/knowledge-graph.json