2Ryun — AI 时代知识/内容底座

2Ryun（第二现实）为 AI Agent 提供文档管理、知识库、网页生成、笔记等能力。所有操作通过 REST API 调用（Authorization: Bearer <key> 鉴权，Key 从 2Ryun 设置页获取，格式为 sk- 前缀 + 多段随机字符）。

API 技术文档: 2ryun-api-spec-cn.md — 完整 endpoint、参数、返回格式。

国内站版：本 Skill 面向国内站 www.2ryun.wiki。海外用户请使用 2ryun.com 版（2Ryun-skill）。

核心机制：自动知识提取

提取和组织是 2Ryun 自动完成的，Agent 不需要手动调用 extract/organize API。 Agent 只需要：

1. 创建文档时通过 setting.wikiAutoExtract 决定是否让这篇文档进入知识库
2. 写入后 2Ryun 自动在后台完成提取、去重、关联

判断标准：哪些文档该进入知识库

✅ 适合进入知识库（"wikiAutoExtract": true）：

• 用户原创的文档、笔记、研究
• 从外部导入的参考资料、报告、论文
• 包含用户自己的观点、数据、经验的内容
• 任何"新知识"——用户提供的不存在于已有知识库中的信息

❌ 不适合进入知识库（"wikiAutoExtract": false，或不设置）：

• 从知识库检索内容生成的报告、总结（没有新知识点，只是已有知识的重组）
• AI 生成的草稿、临时内容
• 会议记录草稿、待整理的随手笔记
• 任何"已有知识的衍生品"——会浪费 AI 算力和 token

核心原则：如果一个文档是根据知识库中的知识生成的，它就不应该再被提取回知识库。只有包含新信息的文档才值得进入。

能力一：文档管理底座

积累和管理文档，并决定哪些进入知识库。

场景 1.1：创建 / 导入文档

从文本内容创建：

curl -X POST https://www.2ryun.wiki/restapi/documents/create \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "title": "文档标题",
    "content": "Markdown 正文",
    "tags": ["标签1"],
    "setting": {"wikiAutoExtract": true}
  }'

"wikiAutoExtract": true 表示这篇文档应进入知识库。如果是衍生内容则设为 false。

⚠️ 提取需要时间：文档创建后，2Ryun 在后台异步提取和组织知识，不会立即出现在知识库中。单篇文档通常 1-3 分钟，批量可能更长。如果创建后立刻搜索，可能查不到刚入库的内容。告知用户稍等片刻再查询。

从文件导入：

curl -X POST https://www.2ryun.wiki/restapi/documents/import \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@/path/to/file.pdf" -F "title=文档标题"

导入的文档默认自动提取。支持 pdf、docx、xlsx、pptx、md、txt、html。

场景 1.2：检索文档

# 列表
curl "https://www.2ryun.wiki/restapi/documents?page=1&pageSize=20" \
  -H "Authorization: Bearer $API_KEY"
# 搜索
curl "https://www.2ryun.wiki/restapi/documents/search?q=关键词" \
  -H "Authorization: Bearer $API_KEY"
# 获取单篇
curl "https://www.2ryun.wiki/restapi/documents/:id" -H "Authorization: Bearer $API_KEY"

场景 1.3：更新 / 删除

• PUT /restapi/documents/update/:id -d '{"title":"...","content":"..."}'
• DELETE /restapi/documents/delete/:id

能力二：使用结构化知识库

知识库在文档创建时自动构建（提取→组织→关联）。Agent 只需查询和使用。

场景 2.1：搜索知识库

用户说："帮我查一下 XX 相关的知识" / "我的知识库里有什么关于 XX 的"

curl "https://www.2ryun.wiki/restapi/wiki/search?q=查询词&max_results=10" \
  -H "Authorization: Bearer $API_KEY"

返回语义相似的知识条目，按相关度排序。用于回答问题、查找背景信息、辅助写作。

场景 2.2：查看知识图谱

# 可视化用（节点+边）
curl "https://www.2ryun.wiki/restapi/wiki/graph?root_id=xxx" -H "Authorization: Bearer $API_KEY"
# 带元数据
curl "https://www.2ryun.wiki/restapi/wiki/graph/data?max_nodes=100" -H "Authorization: Bearer $API_KEY"

用于了解知识结构、发现关联、识别知识空白。

场景 2.3：查看知识库状态

# 条目列表
curl "https://www.2ryun.wiki/restapi/wiki/entries?limit=100" -H "Authorization: Bearer $API_KEY"
# 统计
curl "https://www.2ryun.wiki/restapi/wiki/stats" -H "Authorization: Bearer $API_KEY"
# 哪些文档已提取
curl "https://www.2ryun.wiki/restapi/wiki/extracted-status?content_ids=id1,id2" \
  -H "Authorization: Bearer $API_KEY"

场景 2.4：手动提取（仅在需要时）

当用户明确要求重新提取或手动控制时：

• POST /restapi/wiki/extract — 单篇提取
• POST /restapi/wiki/extract-batch — 批量提取
• POST /restapi/wiki/organize — 手动整理

大多数情况下不需要调用这些，因为文档创建时已自动触发。

能力三：可视化发布

将内容和知识转化为精美网页并发布。

场景 3.1：单篇文档生成网页

1. 获取文档：GET /restapi/documents/:id
2. 选择模板：先获取可用模板列表，根据内容类型选择最合适的：

   curl "https://www.2ryun.wiki/restapi/gen-html/templates" -H "Authorization: Bearer $API_KEY"
   

   返回模板名和描述。LLM 根据文档内容判断：长文博客→article-magazine，技术文档→documentation，产品介绍→landing-page。不要硬编码模板，始终从接口获取并根据内容匹配。
3. 生成：

   curl -X POST https://www.2ryun.wiki/restapi/gen-html/generate \
     -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
     -d '{"content":"Markdown 内容","title":"页面标题","template":"选定的模板名"}'
   

4. 发布：POST /restapi/gen-html/generations/GEN_ID/publish
5. URL：https://www.2ryun.wiki/restapi/gen-html/public/GEN_ID

场景 3.2：知识搜索 + 生成网页报告

1. 搜索：GET /restapi/wiki/search?q=主题&max_results=10
2. 汇总搜索结果为一篇 Markdown 报告
3. 生成网页：POST /restapi/gen-html/generate
4. 发布

注意：生成的报告是新文档，但内容来源于已有知识库，不应设置 wikiAutoExtract: true。

场景 3.4：聊天式编辑网页

已生成的网页可以通过对话方式继续编辑：

curl -X POST https://www.2ryun.wiki/restapi/gen-html/generations/GEN_ID/chat \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"feedback": "把标题改成红色，字号加大到 48px"}'

支持选中页面的某个局部区域进行针对性编辑，传入选中区域的 HTML：

curl -X POST https://www.2ryun.wiki/restapi/gen-html/generations/GEN_ID/chat \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"feedback": "把这段改成蓝色背景", "selected_html": "<div>...</div>"}'

能力四：轻量级笔记

笔记（Note）比文档更轻量，不提取知识库，适合日常记录、随手记、灵感备忘。

创建笔记

curl -X POST https://www.2ryun.wiki/restapi/note/create \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"title": "会议备忘", "content": "Markdown 正文"}'

列表 / 搜索 / 更新 / 删除

• GET /restapi/note?page=1&pageSize=20 — 笔记列表
• GET /restapi/note/:id — 获取单篇
• PUT /restapi/note/update/:id -d '{"title":"...","content":"..."}' — 更新
• DELETE /restapi/note/delete/:id — 删除

笔记 vs 文档：笔记不进入知识库，没有 wikiAutoExtract 设置。适合临时内容、随手记、灵感备忘。需要长期保存并进入知识库的内容用文档。

能力五：素材上传（图片 / 视频）

上传图片、视频等素材文件，返回可直接访问的 URL。

上传单个文件

curl -X POST https://www.2ryun.wiki/restapi/attachments/upload \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@/path/to/image.png" \
  -F "folderId=可选，素材文件夹ID"

返回 JSON 的 file.path 即文件路径，完整访问 URL = https://www.2ryun.wiki/<path>（无需 API Key，可直接用于 <img> / <video>）。

多文件上传

curl -X POST https://www.2ryun.wiki/restapi/attachments/upload/multiple \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@a.png" -F "file=@b.mp4"

一次最多 10 个文件。

列表 / 下载 / 删除

• GET /restapi/attachments?type=image — 列表（type: image/video/audio/document，支持分页、关键词、文件夹）
• GET /restapi/attachments/file/:id — 下载文件
• DELETE /restapi/attachments/:id — 删除

支持格式：图片（png/jpg/jpeg/gif/svg/webp）、视频（mp4/webm）、音频、文档等，单文件上限 20MB。

错误处理

快速参考

重要细节

URL 编码：查询参数中包含中文等非 ASCII 字符时，必须 URL 编码。curl 使用 --data-urlencode，编程语言使用 encodeURIComponent / urlencode。

# ✅ 正确 — curl 自动编码
curl --get "https://www.2ryun.wiki/restapi/wiki/search" \
  --data-urlencode "q=迪赞文化" \
  -H "Authorization: Bearer $API_KEY"

# ❌ 错误 — 中文直接拼接
curl "https://www.2ryun.wiki/restapi/wiki/search?q=迪赞文化"

文档树：创建文档时，rootId 和 parentId 必须同时存在才能准确构建文档树：

• 根文档（一级文档）：rootId 和 parentId 设为同一个值（都等于根文档自己的 ID）
• 子文档：rootId 指向根文档，parentId 指向直接父文档
• 不传这两个字段则创建独立文档（不属于任何树）

重要规则

1. 先问 API Key：用户需要从 2Ryun 设置页的「API Keys」标签创建
2. 判断是否入知识库：创建文档前想清楚——这是新知识还是已有知识的衍生品？
3. 衍生内容不入库：从知识库检索生成的内容，设 wikiAutoExtract: false
4. 笔记不提取：笔记没有 wikiAutoExtract 选项，天生不进知识库。临时记录、灵感备忘用笔记
5. 不需要手动提取：2Ryun 自动完成，Agent 只需正确设置 setting
6. 始终给出最终 URL：发布后把链接给用户
7. 402 积分不足：告知用户，引导到 /pricing，不重试
8. 出错不重试超过 1 次：400 修正后可重试一次，401/402/407 不重试，429 等待后重试，500 等待 3s 后重试一次