【Agent Harness实战】我用 JSON-LD 给 AI 造了个“技能黄页”(Skill Graph)，然后整个系统开挂了

我用 JSON-LD 给 AI 造了个“技能黄页”，然后整个系统开挂了

之前聊了为什么选 JSON-LD 做数据总线、怎么把 CPU 缓存架构抄进记忆系统、以及 Oxigraph 和 Qdrant 这对黄金搭档。

今天来填一个更大的坑——Skill 系统。这东西是所有 AI Agent 框架都在做的事，但我的做法可能和大家想的不太一样：我不用 Markdown 写技能，我用 JSON-LD 建了一个“技能图谱”。

一、为什么不用 Markdown 写 Skill？

市面上主流的做法是：一个 SKILL.md 文件，里面写清楚这个技能是干什么的、怎么用、参数有哪些。简单直接，人人能上手。

但这个方案有三个致命的痛点：

痛点一：名字打架。 小明的 Skill 参数叫 input_file，小红的叫 source_url，小黑的叫 data_path。表面三个名字，业务上都是“数据来源地址”。AI 调用时得记住每个人的命名习惯，一旦记错，整个流程炸掉。

痛点二：找不到技能。 你有 50 个 Skill，AI 要找一个“能处理时间序列预测”的技能。它只能靠文件名和描述去猜。运气好能碰到，运气不好就在列表里迷失。

痛点三：技能之间没有“社交关系”。 A 技能依赖 B 技能，C 技能和 D 技能经常一起用，E 技能是 F 技能的升级版……这些关系在 Markdown 里全靠自然语言描述，AI 不一定能理解，系统更是完全不知道。

简单说：Markdown 是给人看的，不是给机器“理解”的。

二、JSON-LD 怎么解决这些问题？

我的做法是：把每个 Skill 定义成一个 JSON-LD 节点，然后让这些节点互相链接，形成一张“技能图谱”。

一个 Skill 长这样（简化版）：

{
  "@context": "https://agent-harness.os/",
  "@id": "skill:python-data-analysis",
  "@type": "skill:AtomicSkill",
  "skill:name": "Python 数据分析",
  "skill:5W2H": {
    "what": "使用 Pandas 进行数据清洗和统计分析",
    "why": "为业务决策提供数据洞察",
    "who": {"@id": "role:data-analyst"},
    "when": {"triggerCondition": "任务涉及结构化数据分析"},
    "where": {"targetStack": ["Python", "Pandas", "NumPy"]},
    "how": "数据加载 → 清洗 → 探索 → 统计 → 可视化",
    "howMuch": {"avgTokenCost": 3500, "avgDuration": "PT5M"}
  },
  "skill:links": [
    {"@type": "skill:PrerequisiteLink", "skill:target": "skill:python-sandbox"},
    {"@type": "skill:RelatedLink", "skill:target": "skill:data-visualization"},
    {"@type": "skill:AlternativeLink", "skill:target": "skill:r-analysis"}
  ]
}

这带来了三个质变：

第一，名字再也不打架了。 JSON-LD 的 @context 会把所有变体映射到统一的 IRI。不管你的参数叫 input_file 还是 source_url，到了系统里都是同一个语义 IRI。这就是鸭子类型——走起来像鸭子、叫起来像鸭子，那你就是鸭子。

第二，技能能被“发现”了。 每个 Skill 自带 5W2H 元数据——做什么、为什么、谁用、何时用、在哪用、怎么用、花多少资源。Agent 接到任务后，SA 会根据任务的 5W2H 去图谱里匹配最合适的 Skill，而不是靠猜。

第三，技能有了“社交关系”。 六种链接类型：前置依赖、组合关系、关联推荐、替代方案、扩展增强、泛化特例。Agent 可以沿着链接在图里漫游——“我需要 JWT 认证” → 发现前置依赖（Rust 基础）→ 发现相关技能（中间件集成）→ 发现替代方案（OAuth2）。这不是“调用一个技能”，这是“理解一个领域”。

三、MOC：给技能图谱装个“目录”

Skill 多了以后，需要一个导航系统。我引入了 MOC（Map of Content） 节点：

MOC: 数据科学
├── 数据清洗 (5 个 Skill)
├── 统计分析 (8 个 Skill)
├── 机器学习 (12 个 Skill)
└── 可视化 (4 个 Skill)

SA 接到新任务，先扫描 MOC 找相关领域，再深入具体 Skill。就像图书馆的索引卡片柜，先找到“历史”那个抽屉，再翻里面的卡片。

四、技能图谱 + 知识图谱 = 全局智能

技能图谱存的是“怎么做”（How/Process），知识图谱存的是“是什么”（What/Concept）。

但这俩不是隔离的——它们是连在一起的。

比如：技能 skill:rust-jwt-auth 会链接到知识图谱里的 entity:JWT 概念节点，而 entity:JWT 又链接着 memory:session-042/block-017（那次讨论 JWT 的对话记忆）、task:auth-project（用到 JWT 的那个项目）。

这意味着：Agent 调用一个 Skill 时，不只是拿到一段操作指南，而是能顺藤摸瓜，把这个技能相关的历史经验、过往任务、相关知识全部调出来。

五、生态问题怎么破？自动转换！

聊到这里，你可能会问：“JSON-LD 听着很牛，但谁会写啊？社区里全是 Markdown 的 Skill！”

问得好。答案很简单：自动转换。

流马内置了一个 SkillCreator，你把 Markdown 格式的 Skill 文件丢给它，它调用 LLM 自动解析，提取 5W2H、识别参数、推断依赖关系，然后生成标准的 JSON-LD Skill 节点。

MCP 工具也能自动同步。 流马的 MCPIntegration 模块会扫描所有已连接的 MCP 工具，把它们自动包装成 Skill 节点，存进技能图谱。

也就是说：生态不是问题，转换一下就行。你继续用 Markdown 写，我来帮你升维成 JSON-LD。

六、技能还能“自进化”？

流马还有一个 BootstrapEngine（自举学习引擎），能从运行时经验中自动学习新技能。

比如 DA 在某个任务里发现了一套好用的操作模式，AA 在复盘时把这段经验提取出来，BootstrapEngine 自动生成一个新的 Skill 节点，挂载到相关 MOC 下，链接到被参考的原 Skill。

这意味着技能图谱不是死的，是活的。系统用得越多，技能越丰富、越精准。

七、安全和冲突：不给坏人留后门

技能图谱有三个安全机制：

信任等级：每个 Skill 有一个信任等级（沙箱/已验证/系统内置），等级不够的 Skill 执行时有额外限制。
数字签名：所有 Skill 定义都有 Ed25519 签名，篡改过的 Skill 直接拒收。
冲突检测：能检测六种冲突——资源冲突、依赖冲突、权限冲突、语义冲突、时序冲突、版本冲突。当你同时选了 skill:jwt-auth 和 skill:session-auth，系统会提示“这俩架构冲突，二选一”。

八、架构收益总结

能力	Markdown Skill	JSON-LD 技能图谱
名字冲突	手动协调	`@context` 自动映射，零冲突
技能发现	靠文件名和描述猜	5W2H 匹配 + 向量检索
技能关系	自然语言描述	6 种语义链接，可遍历
渐进加载	全量加载	MOC 导航 + 五级投影，按需拉取
知识关联	无	与知识图谱桥接，顺藤摸瓜
生态兼容	原生 Markdown	自动转换 Markdown + MCP 同步
自进化	无	自举学习，越用越强
安全校验	靠人审查	签名 + 信任等级 + 冲突检测

九、最后说句人话

Markdown Skill 就像一本菜谱——翻到“鱼香肉丝”那一页，照着做。但如果菜谱里写“加入适量盐”，AI 就会懵。

JSON-LD 技能图谱，是把菜谱升级成了“智能厨房系统”——每道菜有精确的配料表、步骤分解、关联菜谱推荐、还有历史翻车记录。AI 不再是照着字念，而是真正理解了这个厨房。

我这套系统叫 Gliding Horse（流马），所有代码都在 GitHub 上：https://github.com/doiito/gliding_horse

之前还写过为什么选 JSON-LD、为什么抄 CPU 缓存架构、Oxigraph + Qdrant 怎么配合、以及丰田生产方式怎么用。感兴趣可以去翻翻。今天这篇是“技能图谱封神之路”，希望能帮你理解为什么我这么执着于 JSON-LD。

posted @ 2026-06-15 07:41 doiito 阅读(1) 评论(0) 收藏举报

刷新页面返回顶部