Lexiang

腾讯乐享知识库 API

腾讯乐享知识库是企业级知识管理平台，提供知识库、团队协作、文档管理、AI助手等功能。

数据模型

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

层级关系：Team -> Space -> Entry（树形结构，root_entry_id 为根）

URL 规则

生成知识库链接时，必须使用 lexiangla.com 域名 + company_from 参数，否则链接无法打开。

禁止使用的格式：

• https://csig.lexiangla.com/pages/{id}（缺少 company_from，无法打开）
• https://lexiang.tencent.com/wiki/{id}（内部地址，外部无法访问）

正确的链接格式：

company_from 参数是企业标识，不同企业值不同。可从用户之前分享的乐享链接中提取，或在首次使用时询问用户。

优先使用 API 响应中的 links 字段；如果 API 未返回完整链接，根据上述规则拼接（不要忘记 company_from 参数）。

凭证配置

所需凭证

凭证加载优先级

1. 缓存的有效 Token（~/.config/lexiang/token，2 小时有效期内直接复用，无需 app_key）
2. 环境变量（LEXIANG_APP_KEY / LEXIANG_APP_SECRET）
3. openclaw.json（~/.openclaw/openclaw.json 的 skills.entries.lexiang.env 字段）
4. credentials 文件（~/.config/lexiang/credentials，JSON 格式）
5. 交互式引导（stdin 可用时自动引导用户输入，验证后持久化保存到 credentials 文件）

初始化（加载凭证 + 获取 Token）

执行 scripts/init.sh 脚本自动处理凭证加载和 Token 获取：

source scripts/init.sh
# 之后可使用 $LEXIANG_TOKEN 和 $LEXIANG_STAFF_ID

首次使用时，如果没有任何已配置的凭证，脚本会自动引导用户在终端中输入 App Key、App Secret 和 Staff ID，验证通过后自动保存到 ~/.config/lexiang/credentials，后续无需重复输入。

非交互式环境（如 CI/CD），脚本会输出清晰的配置提示和格式示例，方便用户手动创建配置文件。

Token 有效期 2 小时，获取频率限制 20次/10分钟。脚本会自动缓存到 ~/.config/lexiang/token。

手动配置 credentials 文件

mkdir -p ~/.config/lexiang
cat > ~/.config/lexiang/credentials << 'EOF'
{
  "app_key": "your_app_key",
  "app_secret": "your_app_secret",
  "staff_id": "your_staff_id"
}
EOF
chmod 600 ~/.config/lexiang/credentials

API 调用基础

请求头

# 读操作
-H "Authorization: Bearer $LEXIANG_TOKEN"
-H "Content-Type: application/json; charset=utf-8"

# 写操作（额外需要）
-H "x-staff-id: $LEXIANG_STAFF_ID"

需要 x-staff-id 的接口

所有写操作（创建/更新/删除）、AI 搜索/问答、权限设置

创建知识节点的格式

使用 JSON:API 规范格式，通过 relationships 指定所属知识库和父节点：

{
  "data": {
    "type": "kb_entry",
    "attributes": {"entry_type": "page", "name": "标题"},
    "relationships": {
      "space": {"data": {"type": "kb_space", "id": "SPACE_ID"}},
      "parent_entry": {"data": {"type": "kb_entry", "id": "PARENT_ID"}}
    }
  }
}

通用限制

• 频率限制：大部分接口 3000次/分钟
• 权限要求：需在 AppKey 的授权范围内

核心工作流

1. 解析乐享 URL

当用户提供乐享链接时，可通过 scripts/parse_url.sh 自动解析并获取 API 所需的详细信息：

source scripts/init.sh
source scripts/parse_url.sh "https://lexiangla.com/spaces/{space_id}?company_from=xxx"
# 之后可使用以下环境变量：
# $LEXIANG_PARSED_TYPE       - 资源类型: space / entry / team
# $LEXIANG_PARSED_ID         - 资源 ID
# $LEXIANG_PARSED_SPACE_ID   - 知识库 ID
# $LEXIANG_PARSED_TEAM_ID    - 团队 ID
# $LEXIANG_PARSED_NAME       - 资源名称
# $LEXIANG_PARSED_ROOT_ENTRY_ID - 根节点 ID

支持的 URL 格式：

对于 entry 类型 URL，脚本会通过 parent 链向上查找 root entry，再通过 team → spaces 反查知识库。查找结果自动缓存到 ~/.config/lexiang/space_cache.json。

2. 查询知识

# 获取团队列表
curl "https://lxapi.lexiangla.com/cgi-bin/v1/kb/teams?limit=20" \
  -H "Authorization: Bearer $LEXIANG_TOKEN"

# 获取知识库列表
curl "https://lxapi.lexiangla.com/cgi-bin/v1/kb/spaces?team_id={team_id}&limit=20" \
  -H "Authorization: Bearer $LEXIANG_TOKEN"

# 获取知识列表
curl "https://lxapi.lexiangla.com/cgi-bin/v1/kb/entries?space_id={space_id}&limit=20" \
  -H "Authorization: Bearer $LEXIANG_TOKEN"

# 获取文档内容（HTML 格式）
curl "https://lxapi.lexiangla.com/cgi-bin/v1/kb/entries/{entry_id}/content?content_type=html" \
  -H "Authorization: Bearer $LEXIANG_TOKEN"

3. 创建文档

三种方式对比：

方式 A：上传 Markdown 文件（创建为 file 类型，不可在线编辑）

source scripts/init.sh
bash scripts/upload_file.sh ./document.md SPACE_ID [PARENT_ENTRY_ID]

方式 B：Markdown → 在线文档（创建为 page 类型，可在线编辑）⭐ 推荐

使用 scripts/md_to_page.py 脚本，自动将 Markdown 解析为 blocks 写入在线文档：

source scripts/init.sh

# 创建新 page 并写入
python3 scripts/md_to_page.py ./document.md --space-id SPACE_ID --parent-id PARENT_ID --name "文档标题"

# 写入已有 page
python3 scripts/md_to_page.py ./document.md --entry-id ENTRY_ID

# 追加模式（不清空已有内容）
python3 scripts/md_to_page.py ./document.md --entry-id ENTRY_ID --append

脚本特性：

• 自动解析标题、段落、列表、代码块、引用块、分隔线等
• 引用块(>)自动转为 callout 高亮块（API 不支持 quote，改用 callout 模拟）
• 内联样式：加粗、斜体、行内代码、链接
• 自动分批提交（每批 ≤20 个顶层块），避免请求过大
• 失败自动逐块重试
• 更新已有页面时默认先清空再写入（非 --append 模式），避免内容重复

注意：image 块不支持通过 API 创建，Markdown 中的图片引用会被忽略。如需图片，请在在线文档中手动插入。

4. AI 搜索与问答

# AI 搜索
curl -X POST "https://lxapi.lexiangla.com/cgi-bin/v1/ai/search" \
  -H "Authorization: Bearer $LEXIANG_TOKEN" \
  -H "x-staff-id: $LEXIANG_STAFF_ID" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"query": "搜索关键词"}'

# AI 问答（research=true 使用专业研究模式）
curl -X POST "https://lxapi.lexiangla.com/cgi-bin/v1/ai/qa" \
  -H "Authorization: Bearer $LEXIANG_TOKEN" \
  -H "x-staff-id: $LEXIANG_STAFF_ID" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"query": "问题内容", "research": false}'

使用块接口的关键注意事项

对于需要使用在线文档块接口的场景，注意以下要点（详细示例见 references/api-blocks.md）：

1. 新建文档不传 parent_block_id：直接插入内容到页面根节点
2. 列表块字段名不同于类型名：bulleted_list 用 bulleted 字段，numbered_list 用 numbered 字段
3. 标题块字段需匹配：h1 用 heading1，h2 用 heading2，不是 text
4. 嵌套块的 children 和 block_id 只在块自身声明，不要放到 payload 顶层：嵌套块（callout/table/toggle 等）通过块自身的 block_id + children 字段建立父子关系。不要在 payload 顶层传 children 参数——payload 顶层的 children 会让 API 将这些块提升为页面根的第一批子节点，打乱 descendant 数组中的顺序，导致嵌套块跑到页面开头（而非按文档中的实际位置渲染）
5. quote 不在 API 支持列表中：API 的合法 block_type 不包含 quote。Markdown 引用块（>）应转换为 callout（高亮块）模拟。scripts/md_to_page.py 已自动处理此转换
6. 不支持嵌套的类型：h1-h5、code、image、attachment、video、divider、mermaid、plantuml
7. image 块不支持通过 API 创建：blocks API 不支持 image block_type，暂无法通过 API 在文档中插入图片。上传含图片引用的 MD 文件时，本地图片路径将保持原样（待 API 支持后更新）
8. 文件夹类型用 folder：创建文件夹时 entry_type 必须使用 folder（不是 directory）
9. file 类型 name 必须带后缀：如 文档标题.md、image.png
10. 块数较多时必须分批提交：建议每批 ≤ 20 个顶层块。scripts/md_to_page.py 已内置分批逻辑
11. descendant 接口是追加语义，不是覆盖：POST blocks/descendant 会在页面末尾追加新块，不会清除已有内容。更新已有页面时必须先获取所有块 ID 并逐个删除（DELETE blocks/{block_id}），否则每次写入都会产生重复内容。scripts/md_to_page.py 在非 --append 模式下已内置清空逻辑

常见错误排查

经验案例

知识库跨库迁移

场景：将一个知识库（Space）的全部内容（文件夹结构 + 文件 + 在线文档）迁移到另一个知识库。

核心挑战：乐享 API 没有原生的 move/copy 接口，必须手动遍历 → 重建目录 → 下载/上传。

迁移流程：

1. 遍历源知识库目录结构：GET /kb/entries?space_id=SOURCE&limit=50，逐层获取 folder 和子条目
2. 在目标知识库创建同名文件夹：POST /kb/entries，entry_type: "folder"
3. 按条目类型分别处理：
   • file 类型：从 data.links.download 获取下载链接 → 下载到本地 → 通过三步上传流程（获取凭证 → 上传 COS → 创建条目）重新上传到目标文件夹
   • page 类型：通过 content API 获取 HTML → 解析为 blocks → 写入目标页面

踩坑记录：

HTML → Blocks 转换要点：

乐享在线文档的 HTML 使用 lx-* 类名标识块类型（如 <p class="lx-p">、<h2 class="lx-h2">）。转换时：

• 段落（p）→ {"block_type": "p", "text": {"elements": [...]}}
• 标题（h1-h5）→ {"block_type": "h2", "heading2": {"elements": [...]}}（注意字段名是 heading{N} 不是 text）
• 内联样式通过 <b>/<i>/<u>/<span style="..."> 映射到 text_style
• 空段落可跳过不写入
• 块数较多时分批写入（建议每批 ≤ 20 个块）

自定义属性设置

场景：为知识条目设置自定义属性（如"内容性质"、"内容来源"），便于 Agent 按类型过滤检索。

正确的 API 调用方式：

# 获取条目当前属性值
curl "https://lxapi.lexiangla.com/cgi-bin/v1/kb/entries/{entry_id}/properties/values" \
  -H "Authorization: Bearer $LEXIANG_TOKEN"

# 设置属性值（必须使用 JSON:API 格式）
curl -X PUT "https://lxapi.lexiangla.com/cgi-bin/v1/kb/entries/{entry_id}/properties/values" \
  -H "Authorization: Bearer $LEXIANG_TOKEN" \
  -H "x-staff-id: $LEXIANG_STAFF_ID" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"data":{"type":"kb_entry","attributes":{"属性ID":{"value":["选项显示文本"]}}}}'

踩坑记录：

在线文档更新导致内容重复（严重）

场景：使用 md_to_page.py --entry-id 更新已有在线文档时，页面内容出现 2~4 倍的重复。

根因分析：

Blocks API 的 POST /kb/page/entries/{id}/blocks/descendant 是追加语义——它不会覆盖已有内容，而是在页面末尾追加新块。脚本最初没有清空逻辑，每次运行都会向已有页面追加完整内容。再加上首次写入部分失败后重试，最终导致页面累积了 580 个块（正常应为 ~147 个）。

问题暴露的时间线：

1. 第一次写入：部分块因 quote 类型不被支持而失败 → 修复后重试
2. 第二次写入：全部成功，但此时内容已是两份
3. 后续调试中又触发了几次写入 → 内容膨胀到 4 倍

修复措施：

1. md_to_page.py 新增 clear_page_blocks()：非 --append 模式下，写入前先删除页面所有已有根块
2. 使用并行删除（ThreadPoolExecutor(max_workers=10)）+ 多轮循环，确保大量块也能在合理时间内清空
3. API 返回格式与预期不同（踩坑见下表）

踩坑记录：

核心教训：

对远程 API 的操作必须是幂等的。写入内容前，如果不是追加模式，必须先确认目标是否为空——不能假设 API 会自动覆盖。这类问题在本地文件操作中不会出现（write 默认覆盖），但在 API 场景中极其常见。

首次集成新 API 时，必须验证：该接口是"覆盖"还是"追加"语义？失败重试是否会产生副作用？

API 参数的语义不能想当然。descendant 请求体中的 children 参数看似用于声明嵌套块关系，但实际含义是"指定页面根节点的第一级子块"——它会改变块的渲染位置。嵌套块（callout/table）的父子关系应该只在块自身声明（block_id + children），不需要也不应该在 payload 顶层重复声明。遇到 API 行为不符合预期时，先做小规模对照实验（传/不传某参数），再应用到完整数据。

详细 API 参考

按需查阅以下参考文件获取完整的接口文档：

HTTP 错误码