okp-search

# okp-search — 知识搜索 Skill **CRITICAL — 开始前 MUST 确认 okp CLI 已安装并可连接 API：** ```bash 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 ```bash okp domains # 列出所有领域 okp domains -q <keyword> # 按名称模糊找领域 ``` 返回字段：`domain`、`concept_count`、`has_readme`、`visibility`。 `concept_count=0` 表示已定义 README 但还没有 concept。 private domain 在未获邀请前不会出现在列表、搜索、sample、links 或 export 结果中。 ### Step 2: 读 domain README（必做） 每个 domain 的 README 定义了：数据是什么、有哪些 type、frontmatter 有哪些可过滤字段、怎么搜。 ```bash okp domain <domain> ``` **禁止跳过 README 直接瞎搜。** 不同 domain 的字段和用法不同，参数要以 README 为准。 ### Step 3: 不熟悉时先 sample ```bash okp sample --domain <domain> --limit 5 ``` 看几条真实数据，确认 title / tags / frontmatter 长什么样，再决定怎么搜。 ### Step 4: 按 README 做精确搜索 根据 README 里的 schema 和 How to use，选择合适的组合： ```bash # 列出某个 domain 的 concept（无 query 即按 domain 浏览；默认 limit 50） okp search --domain <domain> okp search --domain <domain> --limit 100 okp search --domain <domain> --limit 50 --offset 50 # 结构过滤（domain / type / tag 等） okp search --domain <domain> --type <type> okp search --domain <domain> --tag <tag> # frontmatter 过滤（字段名以 README 为准） 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： ```bash okp get <id> ``` **禁止**批量拉取 body。 ### Step 6: 沿关系导航 ```bash okp links <id> ``` 返回 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 <id>` 获取。** ## 不在本 skill 范围 - 知识导入 / 写权限 / 邀请码 → okp-import - domain README 维护 → `okp domain <domain> --set readme.md` - OKF bundle 导出到本地 → `okp export <domain> --out <dir>`