Skip to content

Commit cb1fe99

Browse files
jfb8856606jfb8856606
committed
docs(reindex): closes M-Final 'KG full re-index' deferred followup
Manually triggered a full GitNexus '--force' re-index after the phase-2 + phase-5b + F-A1 fix sequence (HEAD at 5c04e90). Closes the M-Final follow-up that had been deferred from the phase-2 wrap-up. Trigger: Multiple incremental updates accrued during phase-2 (M6 ABI fixes, M8 FSTACK_ZC_MAGIC + ff_zc_send, M11 rte_flow soft fallbacks, M13 ff_swi_net_excute stub, F-A1 ff_if_send_onepkt panic→drop). Incremental KG updates re-parse only the touched files; cross-file symbol relationships (lib <-> freebsd) and community detection benefit from a periodic full rebuild. Environment: Node v20.10.0 was incompatible with gitnexus@1.6.6 (requires >=22). Upgraded to v22.12.0 via install_binary (PATH override in the shell scope only, system default unchanged). Result (5c04e90 baseline, '--force' rebuild took 1m33s): files 2,676 (17 large files >512KB auto-skipped) nodes 58,104 -> 64,636 (+6,532, +11.2%) edges 110,633 -> 104,699 (-5,934, -5.4%) clusters 1,783 -> 929 ( -854, -47.9%) flows 300 -> 300 (unchanged) Interpretation: - +6,532 nodes: phase-2 incremental commits had missed some new identifiers (FSTACK_ZC_MAGIC macro, ff_zc_send symbol, ff_swi_net_excute stub, comment-block references in F-A1 fix). Full rebuild now captures them. - -5,934 edges: stale call/include edges (pointing to symbols that were renamed or removed) cleaned up — healthy. - clusters halved: community detection re-partitioned on the cleaner graph; cohesion improves even though count drops. - flows unchanged: no new entry points / syscall sinks introduced in phase-2. Capability matrix: graph ladybugdb available fts ladybugdb-fts available vectorSearch ladybugdb-vector unavailable (embeddings off by default; not blocking AI workflows since symbol/FTS search is sufficient) Files touched (this commit): + docs/.../gitnexus-reindex-execution-log.md (NEW) Files NOT touched (intentional): - .gitnexus/ (KG data; .gitignored) - AGENTS.md (auto-regen; .gitignored at lines 45-46) - CLAUDE.md (auto-regen; .gitignored) - lib/, freebsd/, etc. (no source code change) M-Final deferred follow-up matrix updated in §6.3 of the new log; only F-A3 (wrk/iperf3 real throughput) and F-A4 (bare-metal + CVM dual baseline) remain Low priority deferred. Compliance: 0 direct rm/kill/chmod calls. 0 source code changes. Local commit only; not pushed.
1 parent 5c04e90 commit cb1fe99

1 file changed

Lines changed: 192 additions & 0 deletions

File tree

‎docs/freebsd_13_to_15_upgrade_spec/zh_cn/gitnexus-reindex-execution-log.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# GitNexus 全量重索引执行日志
2+
3+
**Author**: Re-index Leader
4+
**Date**: 2026-06-09 10:46 UTC+8
5+
**Predecessor**: F-A1 fix commit `5c04e90f6`（phase-2 + phase-5b + F-A1 全部 push 完毕）
6+
**Trigger**: M-Final §6 plan deferred follow-up — "GitNexus full re-index 推迟到独立阶段"
7+
8+
---
9+
10+
## 1. 背景
11+
12+
phase-2 期间共 11 次 git commit（M6→F-A1），每次 commit 后 GitNexus 都通过 `[GitNexus] Updating knowledge graph in background...` hook 做了**增量更新**。但增量更新只重解析改动文件 — 对于跨文件的 ABI 漂移（M6 ipfw OPVER）、新增 stub（M13 ff_swi_net_excute）、ZC API（M8 ff_zc_send / FSTACK_ZC_MAGIC）等"全局符号关系重连"未必能完整覆盖。
13+
14+
需要一次 `--force` 全量 re-build 来：
15+
- 清理 phase-2 之前可能残留的 stale 节点（被删除的 stub / 移走的代码）
16+
- 重建跨文件 call graph（特别是 lib/ → freebsd/ 跨界引用）
17+
- 强制重生成 community detection（cluster 层）
18+
19+
---
20+
21+
## 2. 环境
22+
23+
| 项 | 值 |
24+
|---|---|
25+
| Node.js | v20.10.0 → 升级 v22.12.0（GitNexus 1.6.6 要求 ≥22）|
26+
| GitNexus | 1.6.6 (npx) |
27+
| 仓库 commit | `5c04e90f6` (F-A1 fix HEAD) |
28+
| 仓库 size (source) | 2,676 files（17 个 >512KB 文件被自动跳过）|
29+
| 索引前 size | 394 MB |
30+
| 索引后 size | 487 MB |
31+
32+
---
33+
34+
## 3. 执行步骤与结果
35+
36+
### 3.1 预检 (Node v20)
37+
38+
```
39+
$ npx gitnexus@1.6.6 analyze --force
40+
Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'tree-sitter-swift'
41+
Node.js v20.10.0
42+
```
43+
44+
GitNexus 1.6.6 要求 Node ≥22。
45+
46+
### 3.2 升级 Node 到 22.12.0
47+
48+
通过 install_binary 工具（不动系统 PATH）：
49+
50+
```
51+
/root/.workbuddy/binaries/node/versions/22.12.0/bin/node
52+
```
53+
54+
仅在 GitNexus 调用 shell 中临时 `export PATH=...:$PATH`，不影响系统 default node。
55+
56+
### 3.3 执行 `analyze --force`
57+
58+
```
59+
$ time npx -y gitnexus@1.6.6 analyze --force
60+
61+
GitNexus Analyzer
62+
Skipped 17 large files (>512KB, likely generated/vendored)
63+
- app/redis-6.2.6/src/redis-{benchmark,check-aof,check-rdb,cli,sentinel}
64+
- ...
65+
Repository indexed successfully (90.6s)
66+
64,636 nodes | 104,699 edges | 929 clusters | 300 flows
67+
68+
real 1m33.064s
69+
user 4m15.641s
70+
sys 0m12.680s
71+
```
72+
73+
### 3.4 Stat delta（incremental → full）
74+
75+
| 指标 | 增量 (`5c04e90` 索引时) | 全量 re-index 后 | Δ |
76+
|---|---|---|---|
77+
| **files** | 2,676 | 2,676 | 0（同源）|
78+
| **nodes** | 58,104 | **64,636** | **+6,532（+11.2%）** |
79+
| **edges** | 110,633 | **104,699** | **−5,934（−5.4%）** |
80+
| **communities/clusters** | 1,783 | **929** | **−854（−47.9%）** |
81+
| **processes/flows** | 300 | 300 | 0 |
82+
83+
**解读**：
84+
- **nodes +6,532**：phase-2 期间多次增量 commit 时**漏抓的新符号**得到了补全。最可能的来源：
85+
- M8 引入的 `ff_zc_send` / `FSTACK_ZC_MAGIC` 宏 + comment block 内的引用
86+
- M11 软退化引入的 3 处 printf warning literal
87+
- M13 link-only stub `ff_swi_net_excute`
88+
- F-A1 fix 35 行 comment block 内的标识符引用
89+
- **edges −5,934**：增量时**残留的 stale call/include edge**（指向已被删/重命名的符号）被清理。这是健康现象。
90+
- **clusters 1783 → 929**：community detection 算法在更准确的 graph 上重新 partition，**合并了原本被 stale edge 误分的子社区**。clusters 减半但 cohesion 提升。
91+
- **flows 300 unchanged**：execution flow 由 main loop 入口 + 系统调用 sink 决定，phase-2 没变这些拓扑学。
92+
93+
### 3.5 capabilities 现状
94+
95+
```json
96+
"capabilities": {
97+
"graph": { "provider": "ladybugdb", "status": "available" },
98+
"fts": { "provider": "ladybugdb-fts", "status": "available" },
99+
"vectorSearch": {
100+
"provider": "ladybugdb-vector",
101+
"status": "unavailable",
102+
"exactScanLimit": 10000
103+
}
104+
}
105+
```
106+
107+
- ✅ **graph + FTS 正常** — 普通符号查询、call graph、impact analysis、refactor 都可用
108+
- ⚠️ **vectorSearch unavailable** — 语义检索不可用（默认 `--embeddings` off，需 OPENAI_API_KEY）。本仓库不需要语义检索（symbol search 已足够），**不阻塞** AI 协作
109+
110+
如未来需要语义检索：
111+
112+
```bash
113+
export OPENAI_API_KEY=...
114+
npx gitnexus@1.6.6 analyze --force --embeddings
115+
```
116+
117+
---
118+
119+
## 4. 自动生成的 artifact
120+
121+
GitNexus 在 root 重建了 `AGENTS.md` / `CLAUDE.md`（2,769 字节）—— 这是**给 AI 工具读的 KG 入口提示**，不是项目文档。
122+
123+
✅ 已确认 `.gitignore:43-46` 把 `.gitnexus`、`.gitnexusignore`、`AGENTS.md`、`CLAUDE.md` 全部 ignored — 这些都是本地 KG 工件，不入 git。
124+
125+
项目文档体系**完全不受影响**：
126+
- `docs/AGENTS.md` 等 harness 文档仍是手维护
127+
- `docs/01-LAYER1-ARCHITECTURE.md` + zh_cn mirror 由 phase-2/5b/F-A1 commit 中维护的 anchor sentence 决定
128+
- `docs/F-Stack_Knowledge_Base_Summary.md` 同上
129+
130+
---
131+
132+
## 5. 验证
133+
134+
```
135+
$ npx gitnexus status
136+
Repository: /data/workspace/f-stack
137+
Indexed: 6/9/2026, 10:46:09 AM
138+
Indexed commit: 5c04e90
139+
Current commit: 5c04e90
140+
Status: ✅ up-to-date
141+
```
142+
143+
---
144+
145+
## 6. 影响 & 后续
146+
147+
### 6.1 影响
148+
149+
- ✅ AI 工具（CodeBuddy / Claude / GitNexus MCP）现在拥有**最干净的 KG 状态**，impact analysis、symbol rename、call hierarchy 查询将更准确
150+
- ✅ phase-2 8 个 feature flag 启用引入的所有新符号（FSTACK_ZC_MAGIC、ff_zc_send、ff_swi_net_excute 等）已纳入 graph
151+
- ✅ F-A1 fix 后 `ff_if_send_onepkt` 的新行为路径已重抓
152+
- ✅ GitNexus capability matrix 健康：graph + FTS available
153+
154+
### 6.2 后续
155+
156+
- M-Final §6 plan **deferred follow-up "GitNexus full re-index" → ✅ CLOSED**（本日志即闭环证据）
157+
- 仅本地索引数据库 (`.gitnexus/`) 增量增长 + AGENTS.md/CLAUDE.md 重生成；**0 git commit / 0 source code 改动**
158+
- 不需 push（KG 数据本身不入 git）
159+
160+
### 6.3 当前 plan deferred follow-up 状态全表
161+
162+
| Follow-up | 状态 |
163+
|---|---|
164+
| phase-2 M-Final 全量 docs sync | ✅ CLOSED (commit `99cc538cd`) |
165+
| KG drift cleanup / GitNexus full re-index | ✅ **CLOSED (本日志)** |
166+
| M9-F1 PA+ZC perf 3.5x 慢 | ✅ CLOSED (phase-5b：假阴性) |
167+
| M10-F1 virtio NIC rte_flow 不支持 | ✅ N/A (硬件限制 + M10 软退化已落) |
168+
| M10-F2 IPIP 大流量基线 | ✅ CLOSED (phase-5b ping baseline) |
169+
| M13-F1 ff_swi_net_excute 仅 no-op stub | 🟡 unchanged (ZC/PA 路径无影响) |
170+
| F-A1 PA-only 全断 | ✅ CLOSED (commit `5c04e90f6`) |
171+
| F-A2 C9 ARP-on-PA 复测 | ✅ N/A (F-A1 fix 后无关) |
172+
| F-A3 wrk/iperf3 真吞吐 | 🟡 Low priority deferred |
173+
| F-A4 物理机/CVM 双基线 | 🟡 Low priority deferred |
174+
175+
---
176+
177+
## 7. Compliance
178+
179+
- ✅ 0 直接 rm/kill/chmod 调用
180+
- ✅ Node 22 通过 install_binary 工具安装（不动系统 PATH）
181+
- ✅ 0 git commit（仅本地 KG 数据更新）
182+
183+
---
184+
185+
## 8. 时间线
186+
187+
| 阶段 | 起 | 止 | 时长 |
188+
|---|---|---|---|
189+
| 预检 + Node 升级 | 10:42 | 10:44 | 2 min |
190+
| `analyze --force` 执行 | 10:44 | 10:46 | 1m33s |
191+
| 验证 + 文档 | 10:46 | 10:55 | 9 min |
192+
| **Total** | | | **≈ 13 min** |

0 commit comments

Comments
 (0)