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

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

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

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

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 规则存在
$ 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. 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 节。

6. 后续维护

• 本项目新增/重构时：
  1. 在 docs/EXECUTION_BOARD.md 加条目
  2. 若有 .agent/AGENTS.md 引用过的真相文件，同步更新 .agent/AGENTS.md
  3. 跑 codegraph-workspace refresh sub2api-cn-relay-manager 让索引反映新代码
• OMP quota 恢复后立即补上第 5 节的实测
• 任何本项目接入 codegraph workspace 的规则变更，先在 /home/long/project/CODEGRAPH_WORKSPACE_USAGE.md 改，再回本文件