# Okp Import

> 将领域知识清洗并导入 Open Knowledge Protocol。面向各领域 owner 的 agent：读 domain README → 查重 → 蒸馏 → 校验 → 写入。

- **Type:** Skill
- **Install:** `agentstack add skill-talesofai-okp-okp-import`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [talesofai](https://agentstack.voostack.com/s/talesofai)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [talesofai](https://github.com/talesofai)
- **Source:** https://github.com/talesofai/okp/tree/main/skills/okp-import
- **Website:** https://cohub.live/koujiaxin/real-canvas/w/okp

## Install

```sh
agentstack add skill-talesofai-okp-okp-import
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# okp-import — 知识导入 Skill

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

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

## 权限模型

`public: admin/host > writer > reader`

`private: host > writer > reader`

- **admin**：全局管理员，可管理公开 domain。对 private domain 没有任何旁路权限，必须接受 reader/writer 邀请后才能读取或写入，且仍不能管理 private domain。
- **host**：每个 domain 有且只有一个 host，由 domain 创建者自动获得。负责管理 domain README、成员和邀请码。host 不可转让。
- **writer**：domain 写入者。可通过 invitation 获得。可写入概念，不能管理成员和邀请码。
- **reader**：公开 domain 的默认只读权限；在 private domain 中必须通过邀请显式获得。

domain 默认公开。创建者可选择 private；private domain 不会向非成员出现在 domains、search、sample、links 或 export 中。

### 新建 domain → 自动成为 host

写 README 即创建 domain，创建者自动成为该 domain 唯一 host：

```bash
okp domain  --set readme.md
```

返回 201 即创建成功，创建者已持有 host 角色。

创建 private domain：

```bash
okp domain  --set readme.md --visibility private
```

### 获得 writer 权限

若 `put` / `batch` / `domain --set` 返回 403（write access denied）：

1. 让该 domain 的 host（公开 domain 也可由 admin）生成邀请码：
   ```bash
   okp invite create  --expires-hours 72 --max-uses 1
   ```
2. 当前用户接受：
   ```bash
   okp invite accept OKP-XXXX-XXXX
   ```
3. 确认成员身份：
   ```bash
   okp invite members 
   ```

公开 domain 邀请码授予 `writer`。private domain 可邀请 `reader` 或 `writer`，不能授予 `host` 或 `admin`：

```bash
okp invite create  --role reader
okp invite create  --role writer
```
邀请码是短码，不是链接路由。门户右上角「邀请」也可输入同一邀请码。

## 工作流（严格按顺序）

### Step 1: 读 domain README

每个 domain 有自己的 README，定义了 frontmatter 字段规范。**必须先读。**

```bash
okp domain           # 打印 README（含 schema 定义）
okp domains                  # 查看所有 domain
okp domains -q      # 模糊搜索领域名
```

如果是新 domain，先写 README 再导入（写 README 即定义 domain，之后 `okp domains` 立即可见）：

```bash
okp domain  --set readme.md
```

README 格式（YAML frontmatter 定义 schema）：

```markdown
---
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）

```bash
okp search "" --domain  --type 
```

- 命中语义相近的结果 → 判断是否同一概念 → 是则用已有 id 更新，否则改 title 区分

### Step 3: 蒸馏 concept JSON

关键字段：

```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: 写入

```bash
# 单个
okp put  -f concept.json

# 批量（NDJSON，每行一个 concept）
okp batch concepts.ndjson
```

`put` 与 `batch` 行为一致：
- 新写入 / 内容有变更 → 落库后自动进入可检索索引（异步，通常数秒内）
- 内容未变的幂等重导 → 跳过写入；若该条此前未建好索引，服务端会补上
- **不要**再找单独的「建索引 / embed」命令——没有，也不需要

常见失败：

| 状态 | 含义 | 处理 |
|---|---|---|
| 403 | 无 domain 写权限 | 联系 host/admin 生成邀请码，再 `okp invite accept ` |
| 422 | frontmatter/校验失败 | 按 `fix` 补字段或改写 |
| 401 | token 无效/过期 | 检查 `OKP_API_TOKEN` / sandbox execution token |

422 的 `fix` 常见项：
- `frontmatter. 是必填字段` → 补填该字段
- `疑似重复` → 用 `okp search` 确认是否已有
- `provenance.source 为空` → 填数据来源

### Step 5: 验证

写入返回成功后稍等片刻再搜（大批量导入可多等几秒）：

```bash
okp sample --domain  --limit 3     # 随机抽样确认数据结构
okp search "" --domain  --limit 5
okp search --domain  --sort date:desc --limit 5   # 时序类看最新
okp get                                # 确认单条完整
```

若刚写入的 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）

```bash
okp invite create  [--expires-hours 72] [--max-uses 1]
okp invite list 
okp invite revoke  
okp invite accept 
okp invite members 
```

- create 时明文 code 只显示一次
- list 不返回明文 code
- 公开 domain 的邀请角色固定为 `writer`
- private domain 的邀请角色可以是 `reader` 或 `writer`

## 删除

```bash
# writer/host 可删除有写权限 domain 中的 concept；公开 domain 的 admin 也可删除
okp delete  --yes

# private domain 只有 host 可删除；公开 domain 的 host/admin 可删除
okp domain  --delete --yes
```

domain 删除会永久清理该 domain 的 concepts、links、revisions、members 和 invites。

## 不在本 skill 范围

- 知识搜索 → okp-search
- domain README 维护之外的门户 UI 操作
- 数据爬取 → 各 domain 自己的数据管道

## Source & license

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

- **Author:** [talesofai](https://github.com/talesofai)
- **Source:** [talesofai/okp](https://github.com/talesofai/okp)
- **License:** MIT
- **Homepage:** https://cohub.live/koujiaxin/real-canvas/w/okp

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-talesofai-okp-okp-import
- Seller: https://agentstack.voostack.com/s/talesofai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.