| name | okp-search |
| version | 1.6.0 |
| description | 在 Open Knowledge Protocol 中搜索和导航知识。面向消费 agent：先读 domain README → 按 schema 精确过滤/搜索 → light list → 精读少数 → 沿 links 导航。 |
| metadata | {"requires":{"bins":["okp"]},"cliHelp":"okp search --help"} |
okp-search — 知识搜索 Skill
CRITICAL — 开始前 MUST 确认 okp CLI 已安装并可连接 API：
npm install -g @markbangwu/okp
okp domains
何时使用
- agent 需要查找知识（角色、画风、操作手册、社媒分享等）。
- 回答用户问题时需要检索 Open Knowledge Protocol 中的结构化知识。
- 遍历概念之间的关系（通过 links）。
读权限
所有已认证用户均可读取全部 domain，无需加入成员表。搜索/浏览不要求任何 domain 角色。
写入权限见 okp-import；本 skill 只读。
检索循环（严格按此顺序）
Step 1: 确定 domain
okp domains
okp domains -q <keyword>
返回字段：domain、concept_count、has_readme。
concept_count=0 表示已定义 README 但还没有 concept。
Step 2: 读 domain README（必做）
每个 domain 的 README 定义了：数据是什么、有哪些 type、frontmatter 有哪些可过滤字段、怎么搜。
okp domain <domain>
禁止跳过 README 直接瞎搜。 不同 domain 的字段和用法不同，参数要以 README 为准。
Step 3: 不熟悉时先 sample
okp sample --domain <domain> --limit 5
看几条真实数据，确认 title / tags / frontmatter 长什么样，再决定怎么搜。
Step 4: 按 README 做精确搜索
根据 README 里的 schema 和 How to use，选择合适的组合：
okp search --domain <domain>
okp search --domain <domain> --limit 100
okp search --domain <domain> --limit 50 --offset 50
okp search --domain <domain> --type <type>
okp search --domain <domain> --tag <tag>
okp search --domain <domain> --filter <field>=<value>
okp search --domain <domain> --filter <field>=<value> --sort date:desc
okp search "<query>" --domain <domain>
okp search "<query>" --domain <domain> --type <type>
原则：
- 要浏览某 domain 下有哪些 concept →
okp search --domain <domain>（可加 --limit / --offset 分页）
- 知道具体实体名 → 文本查询
- 知道结构化字段（谁发的、哪个群、哪个 wiki）→
--filter，比纯文本更准
- 多字段可叠加，均为 AND
- 时序类数据用 README 推荐的
--sort
- 精确字符/子串命中优先；语义结果作为补充（实现细节对用户透明，不必在回答里展开）
Step 5: Light list → 精读
搜索和 sample 返回摘要列表（id、title、description、tags、frontmatter）。
不要直接把列表当正文用。 选 1–3 个最相关的再 get：
okp get <id>
禁止批量拉取 body。
Step 6: 沿关系导航
okp links <id>
返回 outgoing（引用了谁）和 backlinks（谁引用了它）。
Step 7: 不满意时改写
- 再读一遍 domain README，确认字段用对了
- 换 query 措辞（全名 / 简称 / 中英文）
- 放宽或收紧 type / tag / filter
- 换 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 <id> 获取。
不在本 skill 范围
- 知识导入 / 写权限 / 邀请码 → okp-import
- domain README 维护 →
okp domain <domain> --set readme.md
- OKF bundle 导出 →
okp export <domain>
