docs(understand-anything): record 2026-06-03 offline graph refresh + script + skill
This commit is contained in:
phamnazage-jpg
@@ -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/<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`。
|
||||
|
||||
## 9. 后续维护
|
||||
|
||||
- 本项目新增/重构时：
|
||||
1. 在 `docs/EXECUTION_BOARD.md` 加条目
|
||||
|
||||
Reference in New Issue
Block a user