Okp Search

okp-search — 知识搜索 Skill

CRITICAL — 开始前 MUST 确认 okp CLI 已安装并可连接 API：

npm install -g @markbangwu/okp
okp domains   # 确认 API 可达

何时使用

• agent 需要查找知识（角色、画风、操作手册、社媒分享等）。
• 回答用户问题时需要检索 Open Knowledge Protocol 中的结构化知识。
• 遍历概念之间的关系（通过 links）。

读权限

公开 domain 对所有已认证用户可读。private domain 只对显式受邀的 reader / writer 和创建者 host 可见；全局 admin 也没有读取旁路，必须先接受邀请。 写入权限见 okp-import；本 skill 只读。

检索循环（严格按此顺序）

Step 1: 确定 domain

okp domains              # 列出所有领域
okp domains -q  # 按名称模糊找领域

返回字段：domain、concept_count、has_readme、visibility。 concept_count=0 表示已定义 README 但还没有 concept。

private domain 在未获邀请前不会出现在列表、搜索、sample、links 或 export 结果中。

Step 2: 读 domain README（必做）

每个 domain 的 README 定义了：数据是什么、有哪些 type、frontmatter 有哪些可过滤字段、怎么搜。

okp domain 

禁止跳过 README 直接瞎搜。 不同 domain 的字段和用法不同，参数要以 README 为准。

Step 3: 不熟悉时先 sample

okp sample --domain  --limit 5

看几条真实数据，确认 title / tags / frontmatter 长什么样，再决定怎么搜。

Step 4: 按 README 做精确搜索

根据 README 里的 schema 和 How to use，选择合适的组合：

# 列出某个 domain 的 concept（无 query 即按 domain 浏览；默认 limit 50）
okp search --domain 
okp search --domain  --limit 100
okp search --domain  --limit 50 --offset 50

# 结构过滤（domain / type / tag 等）
okp search --domain  --type 
okp search --domain  --tag 

# frontmatter 过滤（字段名以 README 为准）
okp search --domain  --filter =
okp search --domain  --filter = --sort date:desc

# 文本 / 语义查询
okp search "" --domain 
okp search "" --domain  --type 

原则：

• 要浏览某 domain 下有哪些 concept → okp search --domain （可加 --limit / --offset 分页）
• 知道具体实体名 → 文本查询
• 知道结构化字段（谁发的、哪个群、哪个 wiki）→ --filter，比纯文本更准
• 多字段可叠加，均为 AND
• 时序类数据用 README 推荐的 --sort
• 精确字符/子串命中优先；语义结果作为补充（实现细节对用户透明，不必在回答里展开）

Step 5: Light list → 精读

搜索和 sample 返回摘要列表（id、title、description、tags、frontmatter）。 不要直接把列表当正文用。 选 1–3 个最相关的再 get：

okp get 

禁止批量拉取 body。

Step 6: 沿关系导航

okp links 

返回 outgoing（引用了谁）和 backlinks（谁引用了它）。

Step 7: 不满意时改写

1. 再读一遍 domain README，确认字段用对了
2. 换 query 措辞（全名 / 简称 / 中英文）
3. 放宽或收紧 type / tag / filter
4. 换 domain 或用 sample 重新摸底

常用 flag 参考

| flag | 作用 | |---|---| | --domain / -d | 限定领域 | | --type / -t | 限定类型 | | --tag | 限定标签（可重复） | | --filter key=val | 按 frontmatter 字段过滤（字段以 README 为准） | | --sort | 排序，如 date:desc、updated_at:asc、title:asc | | --limit / -n | 返回数量 |

结果字段

| 字段 | 说明 | |---|---| | id | 路径式 ID：domain/type/slug | | domain / type | 领域和类型 | | title / description | 标题和摘要 | | tags | 标签 | | frontmatter | 扩展字段（因 domain 而异） |

完整正文只通过 okp get 获取。

不在本 skill 范围

• 知识导入 / 写权限 / 邀请码 → okp-import
• domain README 维护 → okp domain --set readme.md
• OKF bundle 导出到本地 → okp export --out

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: talesofai
• Source: talesofai/okp
• License: MIT
• Homepage: https://cohub.live/koujiaxin/real-canvas/w/okp

Install and usage instructions live in the source repository linked above.