| name | okp-import |
| version | 1.6.0 |
| description | 将领域知识清洗并导入 Open Knowledge Protocol。面向各领域 owner 的 agent：读 domain README → 查重 → 蒸馏 → 校验 → 写入。 |
| metadata | {"requires":{"bins":["okp"]},"cliHelp":"okp --help"} |
okp-import — 知识导入 Skill
CRITICAL — 开始前 MUST 确认 okp CLI 已安装并可连接 API：
npm install -g @markbangwu/okp
okp domains
权限模型
admin > host > writer > reader
- admin：全局管理员，可读写任意 domain，无需加入成员表。
- host：每个 domain 有且只有一个 host，由 domain 创建者自动获得。负责管理 domain README、成员和邀请码。host 不可转让。
- writer：domain 写入者。可通过 invitation 获得。可写入概念，不能管理成员和邀请码。
- reader：所有已认证用户的默认权限。可读取全部 domain，无需加入成员表。
所有 domain 均开放读取，没有私有 domain 这个概念。
新建 domain → 自动成为 host
写 README 即创建 domain，创建者自动成为该 domain 唯一 host：
okp domain <domain> --set readme.md
返回 201 即创建成功，创建者已持有 host 角色。
获得 writer 权限
若 put / batch / domain --set 返回 403（write access denied）：
- 让该 domain 的 host/admin 生成邀请码：
okp invite create <domain> --expires-hours 72 --max-uses 1
- 当前用户接受：
okp invite accept OKP-XXXX-XXXX
- 确认成员身份：
okp invite members <domain>
邀请码只能授予 writer，不能获得 host 或 admin。
邀请码是短码，不是链接路由。门户右上角「邀请」也可输入同一邀请码。
工作流（严格按顺序）
Step 1: 读 domain README
每个 domain 有自己的 README，定义了 frontmatter 字段规范。必须先读。
okp domain <domain>
okp domains
okp domains -q <keyword>
如果是新 domain，先写 README 再导入（写 README 即定义 domain，之后 okp domains 立即可见）：
okp domain <domain> --set readme.md
README 格式（YAML frontmatter 定义 schema）：
---
fields:
sender:
type: string
required: true
description: 飞书发送者用户名
group:
type: string
required: true
description: 来源飞书群
platform:
type: enum
required: false
enum: [bilibili, douyin, xiaohongshu, github, youtube]
date:
type: string
required: false
description: 发布日期 YYYY-MM-DD
---
# feishu-social
飞书社媒分享数据...
## How to contribute
每条 concept 的 frontmatter 必须包含 sender 和 group。
Step 2: 查重（search-before-insert）
okp search "<title>" --domain <domain> --type <type>
- 命中语义相近的结果 → 判断是否同一概念 → 是则用已有 id 更新，否则改 title 区分
Step 3: 蒸馏 concept JSON
关键字段：
{
"id": "feishu-social/Link/太离谱了居然可以在自己画的虚拟世界游玩",
"domain": "feishu-social",
"type": "Link",
"title": "太离谱了！居然可以在自己画的虚拟世界游玩！",
"description": "一句话摘要，不超过 500 字符",
"tags": ["AI视频", "虚拟世界"],
"body": "markdown 正文",
"frontmatter": {
"sender": "寇佳新",
"group": "the World Builders",
"platform": "bilibili",
"date": "2026-07-06",
"url": "https://b23.tv/zyhaEno",
"likes": "225",
"views": "6357"
},
"provenance": {
"source": "feishu-sync",
"agent": "okp-import/1.6",
"raw_ref": "https://..."
}
}
frontmatter 按 domain README 的 schema 填写。required 字段不能缺省，否则写入返回 422。
Step 4: 写入
okp put <id> -f concept.json
okp batch concepts.ndjson
put 与 batch 行为一致：
- 新写入 / 内容有变更 → 落库后自动进入可检索索引（异步，通常数秒内）
- 内容未变的幂等重导 → 跳过写入；若该条此前未建好索引，服务端会补上
- 不要再找单独的「建索引 / embed」命令——没有，也不需要
常见失败：
| 状态 | 含义 | 处理 |
|---|
| 403 | 无 domain 写权限 | 联系 host/admin 生成邀请码，再 okp invite accept <code> |
| 422 | frontmatter/校验失败 | 按 fix 补字段或改写 |
| 401 | token 无效/过期 | 检查 OKP_API_TOKEN / sandbox execution token |
422 的 fix 常见项：
frontmatter.<field> 是必填字段 → 补填该字段疑似重复 → 用 okp search 确认是否已有provenance.source 为空 → 填数据来源
Step 5: 验证
写入返回成功后稍等片刻再搜（大批量导入可多等几秒）：
okp sample --domain <domain> --limit 3
okp search "<title 关键词>" --domain <domain> --limit 5
okp search --domain <domain> --sort date:desc --limit 5
okp get <id>
若刚写入的 concept 暂时搜不到：再等几秒重试 okp search / okp get；不要重写一遍，除非内容本身要改。
id 命名规范
{domain}/{type}/{slug} # slug 用 kebab-case，避免中文和空格
provenance 必填字段
| 字段 | 说明 |
|---|
source | 数据来源，如 feishu-sync、manual、fandom-crawl |
agent | 写入方，如 okp-import/1.6 |
raw_ref | 原始数据 URL 或路径 |
邀请相关 CLI（host/admin）
okp invite create <domain> [--expires-hours 72] [--max-uses 1]
okp invite list <domain>
okp invite revoke <domain> <invite-id>
okp invite accept <code>
okp invite members <domain>
- create 时明文 code 只显示一次
- list 不返回明文 code
- 邀请角色固定为
writer
不在本 skill 范围
- 知识搜索 → okp-search
- domain README 维护之外的门户 UI 操作
- 数据爬取 → 各 domain 自己的数据管道
