🔬 CodeGraph × Hermes Skills 知识库深度分析

研究问题：将 Hermes skills 文件夹当成知识库来管理，CodeGraph 代码图谱对未来 Harness 优化是否存在有益作用？
分析日期：2026-06-24
工具版本：CodeGraph (latest) · Hermes Agent · tree-sitter AST parser
分析对象：~/.hermes/skills/（60+ 技能目录 · 714 文件 · 含 Harness Engineering 16 章知识体系）

1. CodeGraph 是什么——核心能力概览

CodeGraph 是一个语义代码智能平台，通过 tree-sitter 将源代码解析为 AST，提取符号（函数、类、方法）和关系（调用、导入、继承），存储到本地 SQLite 知识图谱中，并通过 MCP 协议暴露给 AI Agent。

核心架构

AI Agent (Hermes / Claude Code / Cursor)
  │
  │  MCP 协议调用
  ▼
CodeGraph MCP Server
  │  explore · search · callers · callees · impact · node
  ▼
SQLite 知识图谱
  symbols · edges · files · FTS5 全文搜索

MCP 工具集

技术特点

• 100% 本地：无数据外传、无 API 密钥、纯 SQLite
• 20+ 语言支持：TypeScript/JavaScript/Python/Go/Rust/Java/C#/PHP/Ruby/Swift/Kotlin 等
• 框架感知路由：识别 Django/Flask/FastAPI/Express/NestJS 等 17 种框架的 URL 路由
• 自动同步：FSEvents/inotify 原生文件监听 + 2 秒防抖 + 增量重建
• 跨语言桥接：Swift ↔ ObjC / React Native legacy + TurboModules / Expo Modules

2. 实测：对 skills 文件夹的索引结果

对 ~/.hermes/skills/ 执行 codegraph init -i，3.3 秒完成索引：

$ cd ~/.hermes/skills && codegraph init -i
  ◆ Scanning files — 139 found
  ◆ Parsing code — done
  ◆ Resolving refs — done
  ● 2,823 nodes, 6,702 edges in 3.3s

索引统计

索引查询示例

Impact 分析——修改 submit() 函数的爆炸半径：

$ codegraph impact "submit" --depth 1
Impact of changing "submit" — 27 affected symbols:

creative/comfyui/scripts/run_workflow.py
  method      submit:173
  function    main:565

creative/comfyui/scripts/health_check.py
  function    smoke_test:103

last30days/scripts/lib/bird_x.py
  function    search_handles:346

last30days/scripts/lib/pipeline.py
  function    run:175
  function    _retry_thin_sources:743
...（共 27 个受影响的符号，横跨 5 个技能目录）

符号搜索——render 相关函数：

$ codegraph query "render" --kind function --limit 15
function    render_full          last30days/scripts/lib/render.py:788
function    render_html          last30days/scripts/lib/html_render.py:346
function    render_context       last30days/scripts/lib/render.py:932
function    render_compact       last30days/scripts/lib/render.py:95
function    render_for_html      last30days/scripts/lib/render.py:190
function    render_comparison_multi  last30days/scripts/lib/render.py:574
...（共 15 个 render 系列函数）

3. 关键发现：80% 的知识内容被完全忽略

这意味着什么？

Harness Engineering 技能的全部核心价值都在 Markdown 中：

• 16 章知识体系（chapters/ch01–ch16.md）—— 未索引
• 15 个架构模式（patterns.md）—— 未索引
• 十条原则检查清单（cheatsheet.md）—— 未索引
• 概念间交叉引用（主题索引表）—— 未索引
• 融合审计方法论（fusion-audit-methodology.md）—— 未索引
• Hermes CAR 评估基线（hermes-car-baseline.md）—— 未索引
• Harness 设计实践（hermes-harness-design-practice.md）—— 未索引
• 术语表（glossary.md）—— 未索引

CodeGraph 看不到：

• "Query Loop" 和 "Compact 语义底座" 之间的概念依赖
• "五层 Harness 架构" 被哪些章节引用
• "十条原则" 和 "最终六问" 之间的逻辑映射关系
• harness-engineering 和 auto-compact-configuration 两个技能之间的知识重叠

4. 有益部分：脚本执行层的代码图谱

4.1 脚本间依赖可视化

CodeGraph 的 impact 分析揭示了一个重要发现：

last30days/scripts/lib/pipeline.py
  → calls submit() from comfyui (跨技能复用！)
  → calls query() from academic-research/search_arxiv.py
  → imports from 14+ sibling modules

Harness 优化点：last30days 技能的脚本生态已经形成了一个紧密耦合的子图，任何改动 submit() 函数的行为会影响 27 个下游符号。这正是 Harness Engineering 里"影响分析"的核心。

4.2 发现跨技能复用模式

submit() 被 5 个不同技能的脚本调用（comfyui、last30days、bird_x、competitors、github）。

4.3 测试覆盖率盲区

CodeGraph 对每个 blast radius 节点都标注了 ⚠️ no covering tests found。skills 脚本目前零测试覆盖，这对 Harness 的"验证门控"（verification-gate）是一个真实的缺口。

5. 无益部分：知识内容层完全缺失

6. 如果要让知识图谱对 Harness 产生系统性价值

需要的不是 CodeGraph（代码图谱），而是一个 Markdown-native 的知识图谱方案：

方案 A：LLM Wiki（已有基础设施）

你已经在用的 LLM Wiki (nashsu/llm_wiki) 天然支持 Markdown 知识图谱：

• App: v0.4.23 MacOS 桌面应用
• API: http://127.0.0.1:19828/api/v1
• 当前 AIOps 项目：64 节点 / 189 边知识图谱
• 支持概念间关系抽取、语义搜索、图谱可视化

建议：创建一个 "Harness Engineering" 项目，将 skills/ 下的 Markdown 知识全部导入。

方案 B：定制 SKILL.md frontmatter 解析器

编写一个轻量级解析器，从 SKILL.md 的 YAML frontmatter 中提取：

related_skills: [llm-wiki-api, persistence-strategy, verification-gate, ...]
tags: [harness, prompt-engineering, query-loop, ...]
metadata.hermes.category: devops
metadata.hermes.related_skills: [...]

构建技能间的关系图，输出为 JSON 或 SQLite，供 curator 和 Agent 查询。

方案 C：混合架构（推荐）

┌─────────────────────────────────────────┐
│          Harness Knowledge Hub          │
│                                         │
│  ┌─────────────┐   ┌────────────────┐   │
│  │ CodeGraph   │   │ LLM Wiki /     │   │
│  │ (脚本层)     │   │ Markdown 图谱  │   │
│  │             │   │ (知识层)        │   │
│  │ 132 个 .py  │   │ 568 个 .md    │   │
│  │ 2,823 nodes │   │ 概念 + 原则    │   │
│  │ 调用/导入图  │   │ + 章节关系     │   │
│  └──────┬──────┘   └───────┬────────┘   │
│         │                  │            │
│         └────────┬─────────┘            │
│                  ▼                      │
│        Unified Query Layer             │
│   "改 verification-gate 原则会影响     │
│    哪些脚本和哪些章节？"                 │
└─────────────────────────────────────────┘

7. 结论：分层评估与建议路线

对 Harness 优化的实际价值

建议行动路线

1. 短期（立即可做）：保持 CodeGraph 索引 skills/ 文件夹，用于脚本层治理。定期运行 codegraph impact 分析高扇入函数，推动测试覆盖。
2. 中期（1-2 周）：在 LLM Wiki 中创建 "Harness Engineering" 项目，导入 568 个 Markdown 文件，构建概念间知识图谱。
3. 长期（框架层面）：设计混合查询层——当 Agent 问"改 verification-gate 原则会影响什么"时，同时查询脚本依赖（CodeGraph）和概念引用（LLM Wiki），返回完整影响报告。