From c079b8ab6605985c211ed3f81de0712e7091a58f Mon Sep 17 00:00:00 2001 From: phamnazage-jpg Date: Wed, 3 Jun 2026 14:24:12 +0800 Subject: [PATCH] docs(understand-anything): record 2026-06-03 offline graph refresh + script + skill --- docs/2026-06-03-CODEGRAPH-INTEGRATION.md | 92 +++++++++++++++++++++--- 1 file changed, 84 insertions(+), 8 deletions(-) diff --git a/docs/2026-06-03-CODEGRAPH-INTEGRATION.md b/docs/2026-06-03-CODEGRAPH-INTEGRATION.md index e2e139e8..20af2065 100644 --- a/docs/2026-06-03-CODEGRAPH-INTEGRATION.md +++ b/docs/2026-06-03-CODEGRAPH-INTEGRATION.md @@ -4,13 +4,14 @@ ## 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 重构 | +| 指标 | 状态 | +| ---------------------------------------------------- | ------------------------------------------------------------------- | +| 工作区级 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） | ## 1. 工作区级入口 @@ -118,7 +119,82 @@ OMP_NO_UPDATE_NOTIFIER=1 omp -p --cwd /home/long/project/sub2api-cn-relay-manage OMP quota 恢复后请补一次实测并把结果记到本文件第 4 节。 -## 8. 后续维护 +## 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/ + +# 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//.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`。 + +## 9. 后续维护 - 本项目新增/重构时： 1. 在 `docs/EXECUTION_BOARD.md` 加条目