lexiang

腾讯乐享知识库 API 集成技能（lexiang）用于通过开放接口管理企业级知识管理平台腾讯乐享中的内容。

用途

适用于需要通过 API 管理乐享知识库内容的场景，包括创建/查询/编辑文档、搜索知识、管理团队权限、知识库迁移等内容管理任务。

数据模型

Team（团队）：顶级组织单元，一个团队下可以有多个知识库（Space）
Space（知识库）：知识的容器，属于某个团队，包含多个条目（Entry），有 root_entry_id 作为根节点
Entry（条目/知识）：知识库中的内容单元，可以是页面（page）、文件夹（folder）或文件（file），支持树形结构（parent_id）
File（文件）：附件类型的条目，如 PDF、Word、图片等层级关系：Team -> Space -> Entry（树形结构，root_entry_id 为根）

主要能力

查询知识：获取团队列表、知识库列表、知识列表、文档内容（HTML 格式）
创建文档：支持上传 Markdown 文件（file 类型，不可在线编辑）、Markdown 转在线文档（page 类型，可在线编辑）、块接口手动构建三种方式
在线文档块接口：创建/编辑块内容，支持标题、段落、列表、代码块、引用块、分隔线等
AI 搜索与问答：提供 AI 搜索和 AI 问答接口，问答支持 research 参数启用专业研究模式
文件上传、通讯录管理、任务管理、自定义属性设置、知识库跨库迁移等

使用方式

凭证配置：需要 LEXIANG_APP_KEY（应用 Key）、LEXIANG_APP_SECRET（应用 Secret）、LEXIANG_STAFF_ID（员工身份标识，写操作必需）。凭证加载优先级为：缓存的有效 Token（~/.config/lexiang/token，2 小时有效期）、环境变量、openclaw.json、credentials 文件、交互式引导。初始化：执行 scripts/init.sh 脚本自动处理凭证加载和 Token 获取，之后可使用 $LEXIANG_TOKEN 和 $LEXIANG_STAFF_ID。Token 有效期 2 小时，获取频率限制 20次/10分钟。 API 调用：读操作使用 Authorization Bearer 请求头，写操作额外需要 x-staff-id 请求头。创建知识节点使用 JSON:API 规范格式，通过 relationships 指定所属知识库和父节点。 URL 解析：使用 scripts/parse_url.sh 解析乐享链接，获取资源类型、ID、知识库 ID、团队 ID 等信息。 Markdown 转页面：使用 scripts/md_to_page.py 将 Markdown 解析为 blocks 写入在线文档，支持自动分批提交、失败重试、引用块转 callout 等特性。

适用场景

通过 API 创建、查询、编辑乐享知识库文档
批量导入 Markdown 内容到在线文档
使用 AI 搜索和问答检索企业知识
管理团队、知识库与知识节点权限
知识库跨库迁移（文件夹结构 + 文件 + 在线文档）
为知识条目设置自定义属性，便于按类型过滤检索

限制

频率限制：大部分接口 3000次/分钟；Token 获取 20次/10分钟
权限要求：需在 AppKey 的授权范围内
image 块不支持通过 API 创建，Markdown 中的图片引用会被忽略
quote（引用块）不在 API 支持的 block_type 列表中，需转换为 callout 模拟
不支持嵌套的类型：h1-h5、code、image、attachment、video、divider、mermaid、plantuml
file 类型条目创建后名称无法通过 API 修改，需在上传时使用正确文件名
POST blocks/descendant 是追加语义而非覆盖，更新页面前需先清空已有块
生成知识库链接必须使用 lexiangla.com 域名加 company_from 参数，否则链接无法打开

常见错误排查

缺少 x-staff-id：写操作需添加 -H "x-staff-id: $LEXIANG_STAFF_ID"
entry_type 值无效：创建文件夹需使用 folder（不是 directory）
content_type 不能为空：需添加 ?content_type=html
列表内容为空：无序列表用 bulleted，有序列表用 numbered
file name 缺少后缀：需添加 .md、.png 等后缀
属性设置静默失败：value 数组需传选项显示文本而非 key
页面内容出现重复：更新前需先清空已有块
嵌套块跑到页面开头：不要在 payload 顶层传 children 参数