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

把技能文件夹当成知识库来管理 — CodeGraph 对未来 Harness 优化的价值评估

📅 2026-06-24 · 🛠 CodeGraph CLI (local) · 📂 ~/.hermes/skills/

技能目录 (SKILL.md)

139

已索引文件

2,823

知识图谱节点

6,702

关系边

7.32

索引体积 (MB)

3.3s

索引耗时

📑 目录

研究背景与方法
技能文件夹全景：900 个文件的知识资产
CodeGraph 索引结果：代码层的知识图谱
关键发现一：last30days 的「中心化枢纽」架构
关键发现二：submit() 的影响分析 — 27 个符号的涟漪效应
关键发现三：跨技能代码复用网络
关键发现四：渲染引擎的复杂度热点
Harness 优化推演：技能即知识库的管理范式
结论与建议

一、研究背景与方法

Hermes Agent 的技能系统 (~/.hermes/skills/) 是一个混合知识库：既包含 Markdown 格式的 Harness Engineering 理论文档（原则、模式、检查清单），也包含 Python/Shell 脚本形式的可执行工具。本研究使用 CodeGraph — 一个基于 tree-sitter 的语义代码智能平台 — 对技能文件夹进行完整的知识图谱构建与分析。

CodeGraph 核心能力：

基于 tree-sitter 解析 AST，提取函数/类/变量/导入等符号节点
自动推断调用关系、继承关系、引用关系，构建有向图
支持 explore（语义探索）、callers（调用者分析）、impact（影响分析）、affected（变更影响范围）等高级查询
SQLite + FTS5 全文搜索，本地运行，无数据外泄

研究方法：

对 ~/.hermes/skills/ 执行 codegraph init -i 全量索引
通过 codegraph status 获取全局统计
对高扇入符号（如 submit()）执行 callers 和 impact 分析
对关键子系统（render 引擎、pipeline 架构）执行语义搜索
结合 Harness Engineering 框架进行优化推演

二、技能文件夹全景：900 个文件的知识资产

技能目录总计 900 个文件，分布在 93 个技能子目录中：

文件类型	数量	占比	角色
Markdown (.md)	569	63.2%	知识文档：原则、模式、检查清单、章节
Python (.py)	132	14.7%	可执行脚本：数据处理、API 调用、渲染
Shell (.sh)	14	1.6%	部署脚本：Cloudflare Pages、环境配置
YAML (.yaml)	4	0.4%	配置文件
其他（模板、数据等）	181	20.1%	HTML 模板、JSON 数据、图片等

Python 脚本分布热力图

技能目录	.py 文件数	复杂度	说明
`last30days/scripts/`	66	极高	完整的深度研究引擎：pipeline、渲染、多源聚合
`creative/comfyui/`	16	高	ComfyUI 工作流执行器 + 批量处理
`book-to-skill/scripts/`	14	高	书籍提取器：HTML/EPUB/PDF 解析链
`productivity/`	11	中	Google Workspace、PowerPoint、OCR 工具
`red-teaming/godmode/`	4	中	越狱测试脚本
`creative/pixel-art/`	4	低	像素艺术生成
其他 12 个技能	17	低	单文件工具脚本

三、CodeGraph 索引结果：代码层的知识图谱

$ codegraph init -i
◆ Scanning files — 139 found
◆ Parsing code — done
◆ Resolving refs — done
● 2,823 nodes, 6,702 edges in 3.3s

节点类型分布

节点类型	数量	占比	含义
function	1,233	43.7%	函数定义 — 知识图谱的核心实体
import	692	24.5%	导入声明 — 模块依赖关系
variable	498	17.6%	变量声明 — 配置常量与状态
method	196	6.9%	类方法 — 面向对象结构
file	135	4.8%	文件节点 — 模块级入口
class	66	2.3%	类定义 — 核心抽象
constant	3	0.1%	常量声明

图谱密度指标： 6,702 条边 / 2,823 个节点 = 平均度 4.75。这说明代码模块之间存在密集的调用与引用关系，绝非松散的独立脚本集合。

四、关键发现一：last30days 的「中心化枢纽」架构

last30days 技能包含 66 个 Python 文件，占全部索引文件的 47.5%。CodeGraph 揭示了一个高度模块化的内部架构：

last30days/scripts/lib/ — 核心引擎模块图 ┌─────────────┐ ┌──────────────┐ ┌──────────────┐ │ pipeline.py │───▶│ render.py │───▶│ html_render │ │ (主编排器) │ │ (文本渲染) │ │ (HTML渲染) │ └──────┬──────┘ └──────────────┘ └──────────────┘ │ ├──▶ reddit.py ├──▶ hackernews.py ├──▶ reddit_keyless.py ├──▶ github.py ├──▶ reddit_listing.py ├──▶ polymarket.py ├──▶ reddit_rss.py ├──▶ youtube_yt.py ├──▶ bird_x.py ├──▶ tiktok.py ├──▶ competitors.py ├──▶ providers.py └──▶ fanout.py └──▶ resolve.py 辅助模块: schema.py, categories.py, dedupe.py, env.py, http.py, relevance.py, signals.py, snippet.py, skill_meta.py, planner.py

pipeline.py 是整个系统的中枢，它编排了 15+ 个数据源模块的并行采集、相关性过滤和渲染输出。这是一个完整的 ETL 引擎，而非简单的脚本。

五、关键发现二：submit() 的影响分析 — 27 个符号的涟漪效应

CodeGraph 的 impact 分析揭示了 ComfyRunner.submit() 方法的惊人影响范围：

⚠️ 变更 submit() 将影响 27 个符号，横跨 5 个独立技能：

creative/comfyui/ — 工作流执行、健康检查、批量处理
last30days/ — 12 个数据源模块（reddit、github、hackernews、polymarket、youtube、tiktok…）
red-teaming/godmode/ — 越狱竞赛脚本

这意味着 submit() 实际上是一个跨技能的 HTTP 请求基础设施，被多个技能的 HTTP 客户端复用。从 Harness Engineering 视角看，这是一个典型的「隐式共享依赖」— 任何对该函数的修改都需要跨技能回归测试。

受影响技能	受影响函数数	风险等级
last30days/scripts/lib/	17	高
creative/comfyui/scripts/	5	中
red-teaming/godmode/scripts/	2	低
其他（resolve.py 等）	3	低

六、关键发现三：跨技能代码复用网络

CodeGraph 的调用者分析揭示了一个此前未被显式记录的跨技能复用网络：

66 个类定义揭示了领域建模深度

类名	所在技能	领域角色
`ComfyRunner`	creative/comfyui	ComfyUI API 客户端
`WorkflowRunError`	creative/comfyui	工作流错误处理
`ReasoningClient`	last30days	推理模型客户端
`GeminiClient`	last30days	Gemini API 客户端
`OpenAIClient`	last30days	OpenAI API 客户端
`XAIClient`	last30days	xAI/Grok API 客户端
`OpenAIAuth`	last30days	认证管理
`HTTPError`	last30days	HTTP 错误处理
`_HTMLTextExtractor`	book-to-skill	HTML 解析器
`ExtractionError`	book-to-skill	提取错误处理
`HTTPResponse`	creative/comfyui	HTTP 响应封装
`_StripSensitiveOnRedirectSession`	creative/comfyui	安全重定向处理

这些类定义表明技能系统已经超越了「简单脚本」阶段，进入了领域建模层次 — 有完整的错误处理、认证管理、多 Provider 客户端抽象。这正是 Harness Engineering 中「制度资产化」的体现。

七、关键发现四：渲染引擎的复杂度热点

对 render 关键词的语义搜索返回了 10+ 个渲染函数，揭示了 last30days 的输出层是一个高度分化的渲染引擎：

函数	位置	功能
`render_compact`	render.py:95	紧凑型文本报告
`render_for_html`	render.py:190	HTML 报告生成
`render_for_html_comparison`	render.py:222	对比型 HTML 报告
`render_comparison_multi`	render.py:574	多实体对比报告
`render_comparison_multi_context`	render.py:754	多实体上下文对比
`render_full`	render.py:788	完整报告
`render_context`	render.py:932	上下文渲染
`render_html`	html_render.py:346	HTML 渲染引擎
`render_html_comparison`	html_render.py:366	HTML 对比渲染
`_render_badge`	render.py:48	徽章组件

复杂度信号： 仅渲染层就有 10+ 个变体函数，说明输出格式的多样化需求正在驱动代码膨胀。这是 Harness Engineering 中「上下文治理」需要关注的热点 — 如果未来需要新增输出格式（如 PDF、PPTX），渲染层将成为变更的高风险区域。

八、Harness 优化推演：技能即知识库的管理范式

基于 CodeGraph 的分析结果，结合 Harness Engineering 的框架，推演以下优化方向：

1. 技能依赖图谱化 — 从「文件目录」到「知识图谱」

当前技能管理是基于文件系统的扁平目录结构。CodeGraph 证明了技能之间存在密集的隐式依赖（2,823 节点、6,702 边）。建议：

构建技能级知识图谱：将 CodeGraph 索引作为技能管理的元数据层，每次 codegraph sync 后自动更新
技能影响分析：修改任何技能前，先用 codegraph impact 评估涟漪范围
技能健康仪表盘：定期运行 codegraph status 输出节点/边统计，监控图谱增长趋势

2. 共享基础设施显式化 — 解决「隐式复用」风险

submit() 的 27 个下游符号暴露了一个架构问题：关键基础设施函数被散布在技能脚本中，没有统一的版本管理和变更通知。建议：

抽取 lib/common/：将 submit()、HTTPResponse、HTTPError 等跨技能复用的基础设施抽取为共享库
语义版本标记：在共享函数中添加版本注释，下游技能声明所需版本范围
变更广播机制：修改共享函数时，自动通知所有下游技能的维护者（或通过 Curator 自动标记）

3. 技能复杂度治理 — 分级管理策略

CodeGraph 揭示了技能之间的巨大复杂度差异（last30days 有 66 个 .py 文件 vs 大多数技能只有 1 个）。建议采用分级治理：

复杂度等级	文件数	管理策略	示例
L1 简单	1-3 个 .py	直接维护，无需额外治理	find-nearby, academic-research
L2 中等	4-10 个 .py	定期 impact 分析，关注跨技能依赖	godmode, powerpoint, pixel-art
L3 复杂	11-20 个 .py	需要架构文档 + 测试覆盖	comfyui, book-to-skill, productivity
L4 极高	20+ 个 .py	独立子项目管理 + CI/CD + 代码评审	last30days (66 files)

4. Harness Engineering 知识图谱化 — 理论到实践的闭环

技能文件夹中的 Markdown 文档（569 个 .md 文件）是 Harness Engineering 的理论资产，而 Python 脚本（132 个 .py 文件）是实践资产。CodeGraph 目前只能索引代码层，但两者之间的映射关系是高价值目标：

理论层 (569 .md) 实践层 (132 .py) ┌─────────────────────┐ ┌─────────────────────┐ │ harness-engineering │──映射──▶ │ last30days/pipeline │ │ · 五层架构 │ │ · 实际编排实现 │ │ · Query Loop │ │ · 数据采集循环 │ │ · 十条原则 │──映射──▶ │ creative/comfyui │ │ · 工具权限分级 │ │ · 权限控制实践 │ │ verification-gate │──映射──▶ │ book-to-skill │ │ · 验证门控 │ │ · 验证脚本实现 │ │ compression-monitor │──映射──▶ │ last30days/render │ │ · 上下文治理 │ │ · 输出预算管理 │ └─────────────────────┘ └─────────────────────┘

未来如果能构建「理论-实践双向索引」，就能实现：给定一个 Harness 原则，自动定位所有实现该原则的技能脚本；给定一个脚本，自动关联它体现的 Harness 原则。这将是技能管理从文件系统升级到知识图谱的关键一步。

九、结论与建议

核心结论：CodeGraph 对 Hermes 技能知识库的分析揭示了三个关键洞察：

技能不是孤立脚本，而是密集耦合的代码网络 — 2,823 个节点、6,702 条边证明技能之间存在大量隐式依赖
关键基础设施函数（如 submit()）的影响范围远超预期 — 27 个符号横跨 5 个技能，任何修改都需要跨技能回归测试
技能复杂度分层管理是必要的 — last30days 的 66 个文件已经是一个完整的子项目，需要独立治理

优先级	行动	工具/方法	预期收益
P0	将 `submit()` 等共享函数抽取为显式公共库	CodeGraph impact 分析定位所有调用者	消除隐式耦合，降低变更风险
P0	为 last30days 建立独立的 CI/CD 流程	66 个 .py 文件需要自动化测试	保护最复杂的技能子系统
P1	定期运行 `codegraph sync` 保持索引更新	cron job 或 file watcher	实时掌握技能图谱变化
P1	构建技能复杂度分级看板	CodeGraph status + 脚本统计	分级治理，资源聚焦
P2	探索理论-实践双向索引	Markdown ↔ Python 映射关系	Harness 知识图谱化
P2	渲染引擎重构（10+ 变体函数合并）	策略模式 + 模板引擎	降低输出层复杂度

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

一、研究背景与方法

二、技能文件夹全景：900 个文件的知识资产

Python 脚本分布热力图

三、CodeGraph 索引结果：代码层的知识图谱

节点类型分布

四、关键发现一：last30days 的「中心化枢纽」架构

五、关键发现二：submit() 的影响分析 — 27 个符号的涟漪效应

六、关键发现三：跨技能代码复用网络

66 个类定义揭示了领域建模深度

七、关键发现四：渲染引擎的复杂度热点

八、Harness 优化推演：技能即知识库的管理范式

1. 技能依赖图谱化 — 从「文件目录」到「知识图谱」

2. 共享基础设施显式化 — 解决「隐式复用」风险

3. 技能复杂度治理 — 分级管理策略

4. Harness Engineering 知识图谱化 — 理论到实践的闭环

九、结论与建议

推荐行动项