OpenClaw-Capacities：为AI助手打造轻量级知识库查询工具

作者：CSDN博客
1. 项目概述：一个为AI助手打造的轻量级知识库查询工具

如果你和我一样，日常重度依赖像 Capacities 这样的知识管理工具来整理笔记、项目和联系人，同时又希望能在与 AI 助手（比如 OpenClaw）对话时，快速定位并跳转到这些内容，那么这个项目就是为你准备的。  OpenClaw-Capacities  本质上是一个“桥梁”技能，它让 AI 助手具备了实时查询你的 Capacities 知识库、智能识别内容类型、并一键生成深度链接的能力。
想象一下这个场景：你在和 AI 助手讨论一个项目，随口说了一句“帮我找一下上周和客户开会的纪要”。通常，你需要手动打开 Capacities，在搜索框里输入关键词，再从结果列表中筛选。而有了这个技能，AI 助手能直接理解你的意图，调用 Capacities 的公开 API 进行查找，并立刻返回一个  capacities://  协议的链接。你点击链接，就能直接跳转到 Capacities 应用里对应的会议记录页面。整个过程无缝衔接，极大地减少了上下文切换的成本。
这个项目的核心价值在于“精准”和“快速”。它不试图复制一个完整的本地知识库，也不做复杂的语义搜索或关系推理——这些在当前 Capacities 公开 API 的限制下既不现实，也容易变得笨重。相反，它聚焦于一个非常具体且高频的需求： 通过标题或关键词，快速找到正确的对象并打开它 。这种“小而美”的设计哲学，使得它部署简单、运行稳定，并且能立刻融入你的工作流。
2. 核心设计思路：在现有API边界内做精做透

在动手搭建或使用任何工具前，理解其设计边界至关重要。这能帮你建立合理的预期，知道它能做什么，更重要的是，知道它不能做什么，从而避免后续的失望和误用。
2.1 能力边界与设计取舍

Capacities 的公开 API 目前提供的能力是明确的，但也是有限的。  OpenClaw-Capacities  技能的设计完全基于这些可靠、稳定的现有接口，没有使用任何非公开或实验性的功能。这确保了技能的长期可用性和可维护性。
它能做的（核心功能）：

智能对象查找 ：基于你提供的搜索词（如“恢复协议笔记”），调用 Capacities 的  /lookup  接口进行匹配。 类型感知 ：技能会预先同步并缓存你空间的结构信息（通过  /space-info  接口）。这样，它就知道你的空间里有哪些对象类型，比如  Note  、  Person  、  Meeting  、  Project  ，以及你自定义的类型。当你的查询中隐含了类型（如“找关于XX的 笔记 ”），它能优先返回该类型的结果。 意图感知排序 ：这不是简单的关键词匹配。例如，查询“Find my notes on recovery protocols”，技能会识别出“notes on”这个类型提示，在返回结果时，会优先排序  Note  、  Reference  这类对象，而将  Tag  对象排在后面，即使后者的标题匹配度可能更高。 生成深度链接 ：对于每个匹配结果，技能会生成一个  capacities://  协议的链接。这是 Capacities 应用支持的私有 URL 方案，点击后能直接在 Capacities 桌面端或移动端打开对应的对象页面。 清晰的反馈 ：如果明确请求的类型没有找到（比如你找“张三这个人”，但空间里没有叫“张三”的  Person  对象），它会明确告知你，并可能提供其他相关类型（如标题含“张三”的笔记）作为备选。

它不能做的（当前限制）：

全文内容搜索 ：它无法搜索笔记的正文内容。查找完全基于对象的 标题 。如果你的关键信息藏在正文里而没体现在标题中，它将无法找到。 读取对象属性和关系 ：API 不提供通过 ID 获取对象完整详情（包括自定义属性、关联的其他对象）的接口。因此，技能无法回答“这个项目关联了哪些人？”或“这份笔记里提到的关键日期是什么？”这类需要深入对象内部的问题。 图谱遍历与反向查询 ：由于无法读取关系，技能自然不能进行图谱式的遍历查询，例如“找出所有引用了我某篇笔记的其他笔记”。 本地全量镜像 ：技能仅缓存结构元数据和可选的查询结果（用于提升速度），并不会在本地保存你所有的笔记内容。它不是一个离线知识库。

设计心得 ：在集成第三方服务时，一个常见的陷阱是“过度设计”——试图用有限的API去模拟一个完整的产品功能，结果代码变得复杂脆弱。  OpenClaw-Capacities  选择了相反的道路： 深度利用好一个核心接口（  /lookup  ），并围绕它构建类型识别和链接生成这两层增值服务 。这种“单点突破”的策略，让技能保持轻量、响应快，且非常可靠。

2.2 技术架构与工作流程解析

理解了能力边界，我们再拆解一下它是如何工作的。整个流程可以概括为“一缓一查一连”。
1. 结构同步与缓存（初始化阶段） 这是技能智能化的基础。首次运行或定期执行时，脚本会调用  GET /v1/space-info  接口。这个接口返回你整个空间的结构蓝图，包括所有定义的对象类型（Object Types）及其属性。技能将这些信息缓存在本地的一个 JSON 文件（例如  ~/.openclaw/workspace/skills/capacities-lookup/.cache/structures.json  ）中。

为什么缓存这个？

原文地址：https://blog.csdn.net/weixin_28695537/article/details/161062867