# 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
```