Metadata

name: 2Ryun-skill
description: Use when the user wants to import documents, build a knowledge base, search structured knowledge, generate web pages from content, or publish them. Use when the user mentions 2Ryun, 第二现实, knowledge base, 知识库, 文档管理, 知识图谱, 网页, 发布. 2Ryun is an AI-era knowledge/content platform where knowledge extraction from documents happens automatically once enabled — the agent's role is to decide which documents should enter the knowledge base and which should not.

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

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

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

核心机制：自动知识提取

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

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

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

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

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

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

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

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

能力一：文档管理底座

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

场景 1.1：创建 / 导入文档

从文本内容创建：

curl -X POST https://www.2ryun.com/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.com/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.com/restapi/documents?page=1&pageSize=20" \
  -H "Authorization: Bearer $API_KEY"
# 搜索
curl "https://www.2ryun.com/restapi/documents/search?q=关键词" \
  -H "Authorization: Bearer $API_KEY"
# 获取单篇
curl "https://www.2ryun.com/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.com/restapi/wiki/search?q=查询词&max_results=10" \
  -H "Authorization: Bearer $API_KEY"

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

场景 2.2：查看知识图谱

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

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

场景 2.3：查看知识库状态

# 条目列表
curl "https://www.2ryun.com/restapi/wiki/entries?limit=100" -H "Authorization: Bearer $API_KEY"
# 统计
curl "https://www.2ryun.com/restapi/wiki/stats" -H "Authorization: Bearer $API_KEY"
# 哪些文档已提取
curl "https://www.2ryun.com/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：单篇文档生成网页

获取文档：GET /restapi/documents/:id
选择模板：先获取可用模板列表，根据内容类型选择最合适的：
```
curl "https://www.2ryun.com/restapi/gen-html/templates" -H "Authorization: Bearer $API_KEY"
```
返回模板名和描述。LLM 根据文档内容判断：长文博客→article-magazine，技术文档→documentation，产品介绍→landing-page。不要硬编码模板，始终从接口获取并根据内容匹配。

生成：

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

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

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

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

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

场景 3.4：聊天式编辑网页

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

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

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

多文件上传

curl -X POST https://www.2ryun.com/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。

错误处理

状态码	含义	Agent 行为
200	成功	—
400	参数错误	检查请求体，修正后重试一次
401	API Key 无效或缺失	提示用户检查 Key 是否正确，或去设置页重新生成
402	积分/配额不足	告知用户，引导到 `/pricing` 升级，不要重试
407	Key 权限不足	返回 `INSUFFICIENT_SCOPE`，提示用户去设置页为 Key 勾选所需模块权限（documents/wiki/gen-html/note/attachments）
404	资源不存在	确认 ID 是否正确
429	请求过于频繁	等待 `Retry-After` 秒后重试，或降低请求频率
500	服务端错误	等待 3 秒后重试一次，仍失败则告知用户稍后再试

快速参考

任务	端点	说明
创建文档	`POST /restapi/documents/create`	`setting.wikiAutoExtract` 决定是否入知识库
导入文件	`POST /restapi/documents/import`	自动转换格式，导入为文档
搜索知识	`GET /restapi/wiki/search?q=...`	语义搜索
创建笔记	`POST /restapi/note/create`	轻量记录，不提取知识库
查询积分	`GET /restapi/users/quota`	积分、配额、有效期
生成网页	`POST /restapi/gen-html/generate`	30-120s
聊天编辑	`POST /restapi/gen-html/generations/:id/chat`	对话式编辑网页
发布	`POST /restapi/gen-html/generations/:id/publish`	获取公开 URL
上传素材	`POST /restapi/attachments/upload`	图片/视频/文档，返回可访问 URL

重要细节

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

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

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

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

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

重要规则

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

2Ryun Skill

安装技能