Harness 诊断报告

技能 = 能力语义 + 知识内容 + 代码实现
       (Semantic)  (Knowledge)  (Execution)

用户意图 → [语义层] → [知识层] → [执行层]
  (Why/When)   (What)      (How)

📊 模块依赖图

🔥 耦合热点识别

高扇入符号（改动风险大）

符号	位置	调用者数	影响半径	风险等级
compute_hash	llm_wiki/wiki_tool.py:85	6	12符号/3文件	🔴 高
ingest	llm_wiki/wiki_tool.py:199	4	6符号/2文件	🟠 中高
parse_skill_md	skill-creator/utils.py:8	3	3文件	🟡 中
run_eval	skill-creator/run_eval.py:239	3	7符号/2文件	🟡 中

影响半径详情

compute_hash 影响链（12符号）

wiki_tool.py
  ├─ compute_hash:85
  ├─ generate_wiki_page:140
  └─ ingest:199

auto_linkage.py
  ├─ scan_research_files:36
  ├─ sync_all:92
  └─ main:123

wiki_auto_ingest.py
  ├─ scan_for_new_files:77
  ├─ check_new_files:133
  ├─ run_auto_ingest:148
  └─ get_status:227

run_eval 影响链（7符号）

run_eval.py
  ├─ run_eval:239
  └─ main:316

run_loop.py
  ├─ run_loop:101
  ├─ main:370
  └─ import scripts.run_eval:29

孤立模块（完全独立，无跨模块依赖）

模块	文件数	符号数	独立性评分
kami	2	101	⭐⭐⭐⭐⭐ 5/5
disk-cleaner	1	25	⭐⭐⭐⭐⭐ 5/5
tools/sysclean	1	23	⭐⭐⭐⭐⭐ 5/5
openJiuwen-DeepSearch	5	~80	⭐⭐⭐⭐ 4/5

📈 架构健康度评估

模块独立性矩阵

模块	内部耦合	外部依赖	独立性	健康度
llm_wiki	高（3文件紧密耦合）	无	2/5	🟠 需重构
skill-creator	中（共享utils）	无	3/5	🟡 可优化
openJiuwen-DeepSearch	低（main调用convert）	外部包	4/5	✅ 良好
kami	无	无	5/5	✅ 优秀
disk-cleaner	无	无	5/5	✅ 优秀
tools/sysclean	无	无	5/5	✅ 优秀

关键发现

1. llm_wiki 模块耦合过紧 - wiki_tool.py 是单点故障，被 2 个文件直接依赖；compute_hash 影响半径过大（12符号）
2. skill-creator 模块耦合适中 - utils.py 被 3 个文件使用，但职责清晰；run_eval 是核心函数，影响范围可控
3. 其他模块独立性优秀 - kami、disk-cleaner、sysclean 完全独立；openJiuwen-DeepSearch 内部耦合低

🎯 重构优先级

优先级	模块	行动	预期收益
P1	llm_wiki	抽取 compute_hash 到独立 utils	降低影响半径 50%
P2	llm_wiki	拆分 wiki_tool.py 为 core + api	降低单点故障风险
P3	skill-creator	监控 utils.py 膨胀	预防耦合恶化
P4	其他	保持现状	无

🎯 核心结论

1. 三层架构是技能管理的必然方向

技能不是"文档 + 代码"的简单组合，而是三元组：

技能 = 能力语义 + 知识内容 + 代码实现
       (Semantic)  (Knowledge)  (Execution)

2. 语义层是架构演进的关键缺失

语义层的核心价值：

1. 解耦（关键价值）- 避免 LLM Wiki 和 CodeGraph 直接耦合，语义层作为"翻译层"，隔离变化
2. 映射 - 用户自然语言意图 → 技能能力 → 代码实现；代码变更 → 技能影响 → 知识影响
3. 发现 - 基于语义相似度发现可复用技能，识别能力重叠和技能缺口
4. 评估 - 评估技能的语义完整性和执行可靠性，量化技能质量（当前 42 项检查就是语义评估的雏形）

3. 当前 Harness 系统健康度评估

总体评分：58/100

维度	评分	权重	加权分
代码层健康度	72/100	50%	36
语义层健康度	44/100	50%	22
总分			58

---

🏗️ 语义层实体模型设计

核心实体

实体	说明	示例
Skill	技能本体，一等公民	harness-diagnosis
Capability	可组合的功能单元	"代码依赖分析"、"语义完整性评估"
Interface	API/工具绑定	codegraph query、wiki_query
Contract	输入输出规范、前置/后置条件	输入：技能名称；输出：依赖图谱
Evidence	测试用例、性能指标、使用记录	42项检查得分、调用次数

语义层元数据示例

skill:
  name: harness-diagnosis
  capabilities:
    - name: 代码依赖分析
      description: 分析模块间的符号级依赖关系
      interfaces:
        - tool: codegraph
          commands: [query, callers, callees, impact]
    - name: 语义完整性评估
      description: 评估 SKILL.md 的结构完整性
      interfaces:
        - tool: analyze_skills_semantic.py
  contracts:
    input:
      - type: skill_name
        required: true
      - type: workspace_path
        required: true
    output:
      - type: dependency_graph
        format: markdown
      - type: health_score
        format: json
    preconditions:
      - CodeGraph 索引已构建
      - SKILL.md 文件存在
    postconditions:
      - 生成 harness_full_report.md
      - 生成 skills_semantic_report.json
  evidence:
    test_cases: 0
    performance_metrics:
      avg_execution_time: 15min
      success_rate: 100%
    usage_count: 3

---

📈 改进路线图（重构版）

Phase 0: 语义层设计（1-2周）⚡ 新增

优先级	行动	产出	预期收益
P0	设计语义层数据模型	skills_ontology_schema.json	统一语义描述标准
P0	构建轻量级语义索引原型	skills_ontology.json	支持语义搜索和映射
P0	重新审视 42 项检查清单	映射到实体模型	区分语义完整性 vs 代码健康度

Phase 1: 语义元数据补充（2-3天）

优先级	行动	影响技能	预期提升
P1	为所有技能补充 ## Capabilities	11 个技能	+15分
P1	为所有技能补充 ## Contracts	11 个技能	+10分
P1	为所有技能补充 ## Evidence	11 个技能	+10分

Phase 2: 代码层优化（3-5天）

优先级	行动	影响技能	预期提升
P2	抽取 compute_hash 到独立 utils	llm_wiki	+5分
P2	拆分 wiki_tool.py 为 core + api	llm_wiki	+5分
P2	为有脚本的技能补充 requirements.txt	6 个技能	+5分

Phase 3: 语义索引构建（1个月）

优先级	行动	产出	预期收益
P3	使用向量数据库存储技能语义向量	FAISS/Chroma 索引	支持语义相似度匹配
P3	建立 Skill ↔ Capability ↔ Code 映射	关系图谱	支持影响分析
P3	实现语义搜索 API	/api/skills/search	支持自然语言查询

Phase 4: 标准本体对齐（3个月）

优先级	行动	标准	预期收益
P4	采用 SKOS 描述技能分类	W3C SKOS	统一标签体系
P4	采用 OWL-S 定义能力接口	OWL-S	标准化服务描述
P4	采用 RSD 对齐行业标准	Rich Skill Descriptor	跨平台互操作

---

🎯 预期改进效果

阶段	当前评分	目标评分	提升	关键产出
Phase 0 完成	58	65	+7	语义层数据模型 + 原型
Phase 1 完成	65	85	+20	完整语义元数据
Phase 2 完成	85	90	+5	代码层优化
Phase 3 完成	90	95	+5	语义索引 + 搜索 API
Phase 4 完成	95	98	+3	标准本体对齐

---

🔑 关键洞察

1. 语义层是技能管理的核心

技能不是"文档 + 代码"的简单组合。技能是三元组：

• 能力语义（语义层）：决定技能能否被正确发现、组合
• 知识内容（知识层）：决定技能的理解深度
• 代码实现（执行层）：决定技能的执行能力

2. 当前 42 项检查清单是语义评估的雏形

当前的 42 项检查清单实际上已经在做语义层评估，但缺乏统一的实体模型。应该：

• 将检查项映射到语义层的实体模型
• 区分"语义完整性"和"代码健康度"
• 建立量化的语义质量评分体系

3. 三层架构是架构演进的必然方向

从"修补缺失"升级为"构建语义层"，这是架构演进的必然方向，不是可选项。

---

📋 下一步建议

立即行动（本周）

1. 暂停 Phase 1 的 SKILL.md 补充工作 - 先设计语义层的数据模型，再决定需要补充哪些元数据
2. 优先构建语义层原型 - 用现有 SKILL.md + CodeGraph 数据，建立一个轻量级的 skills_ontology.json 作为起点
3. 重新审视 42 项检查清单 - 将检查项映射到语义层的实体模型，区分"语义完整性"和"代码健康度"

短期行动（1-2周）

1. 设计语义层数据模型 - 定义 Skill、Capability、Interface、Contract、Evidence 的 JSON Schema
2. 构建轻量级语义索引 - 使用向量数据库（FAISS/Chroma）存储技能语义向量
3. 实现语义搜索 API - 支持自然语言查询技能，基于语义相似度推荐技能

中期行动（1个月）

1. 补充完整语义元数据 - 为所有技能补充 Capabilities、Contracts、Evidence
2. 优化代码层 - 抽取 compute_hash 到独立 utils，拆分 wiki_tool.py 为 core + api

长期行动（3个月）

1. 采用标准本体 - SKOS（标签体系）、OWL-S（服务描述）、RSD（Rich Skill Descriptor）
2. 实现跨平台互操作 - 支持与其他 Agent 平台的技能交换，建立技能市场生态

---

🚀 结语

Harness Engineering X AI 本体论的研究表明：语义层是技能管理的核心，是架构演进的必然方向。

通过构建三层架构（语义层 → 知识层 → 执行层），我们可以：

• 解耦 LLM Wiki 和 CodeGraph
• 建立意图 → 能力 → 实现的映射链
• 基于语义相似度发现可复用技能
• 量化技能质量，支持持续改进

最终目标：构建一个语义完整、代码健康、知识丰富的技能管理系统，支持 Agent 的持续演进和优化。