d6a0261a47
§9 of codegraph-integration note now documents the 2026-06-03 15:20 upgrade: - enrich defaults to callWithFallback() chain (current model → fallback_providers) - skips codex_responses transport providers automatically - resolves __default._providerModel to endpoint-served name (not user alias) - strips <think>...</think> blocks before JSON.parse - explicit --provider still supported (skip chain, useful for fast mode) Verified on 5 git repos (contract management / gongju / llm-intelligence / user-system / supply-intelligence) — 13/13 OK, 0 fallback rotation needed, all from minimax-m3/MiniMax-M3 (current agent model). Docs-only commit; sibling subagent's parallel code changes are NOT included.
289 lines
17 KiB
Markdown
289 lines
17 KiB
Markdown
# 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）
|
||
|
||
```bash
|
||
# 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`）：
|
||
|
||
```python
|
||
'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` 后应该用：
|
||
|
||
```bash
|
||
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 本次刷新结果
|
||
|
||
```bash
|
||
$ ~/.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 怎么用
|
||
|
||
```bash
|
||
# 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）
|
||
|
||
```bash
|
||
# 跑 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`
|
||
|
||
### 恢复
|
||
|
||
```bash
|
||
cp <repo>/.understand-anything/knowledge-graph.json.bak-2026-06-03 \
|
||
<repo>/.understand-anything/knowledge-graph.json
|
||
```
|