| name | lexiang-base |
| description | 乐享知识库基础规则与数据模型。当需要了解乐享的数据结构、URL规则、写入安全规则、工具发现方式时读取本文档。通常由其他子模块引用，不直接触发。 |
乐享 MCP 基础知识
本文档为所有子模块的共享基础层，包含数据模型、URL 规则、安全约束、工具发现等通用知识。
⛔ 必读（调用前必须理解）
- 本服务直接暴露所有业务工具（如
team_list_teams、search_kb_search 等），可直接调用
- 调用前先确认工具参数定义，以 MCP 返回的 schema 为准
- 不确定参数时，使用
get_tool_schema(tool_name="xxx") 获取最新定义
📊 数据模型
核心概念
| 概念 | 说明 |
|---|
| Team（团队） | 顶级组织单元，一个团队下可以有多个知识库(Space) |
| Space（知识库） | 知识的容器，属于某个团队，包含多个条目(Entry)，有 root_entry_id 作为根节点 |
| Entry（条目） | 知识库中的内容单元，可以是页面(page)、文件夹(folder)或文件(file)，支持树形结构(parent_id) |
| File（文件） | 附件类型的条目，如 PDF、Word、图片等 |
层级关系
Team → Space → Entry（树形结构，root_entry_id 为根）
├── page（页面）
├── folder（文件夹）
└── file（文件）
URL 规则
{domain} = whoami() 返回的 company.company_domain（如 https://csig.lexiangla.com 或 https://lexiangla.com）
⛔ 严禁使用 MCP endpoint 拼接任何用户可访问的链接！ MCP 域名仅用于接口调用，不是用户访问地址。
⛔ 严禁将 company_from 拼接为子域名！ company_from 只能作为 URL 查询参数（?company_from=xxx）。
| 资源 | URL 格式 |
|---|
| 团队首页 | {domain}/t/{team_id}/spaces |
| 知识库 | {domain}/spaces/{space_id} |
| 知识条目 | {domain}/pages/{entry_id} |
链接生成步骤（所有操作通用）：
- 取
whoami() 返回的 company.company_domain 作为 {domain}
- 判断
{domain} 是否为顶级域名（不含三级前缀，如 lexiangla.com）：
- 是：使用
{domain}/pages/{entry_id}?company_from={company_from}
{company_from} 优先取 mcp.json url 中的 company_from 参数- 若无，取
whoami() 返回的 company.code ← 此时已调用过 whoami，直接取该值，不能省略
- 否（如
csig.lexiangla.com）：使用 {domain}/pages/{entry_id}，无需追加参数
{domain} 类型 | 链接格式 | 示例 |
|---|
包含三级域名（如 csig.lexiangla.com） | {domain}/pages/{entry_id} | https://csig.lexiangla.com/pages/abc |
顶级域名（如 lexiangla.com） | {domain}/pages/{entry_id}?company_from={company_from} | https://lexiangla.com/pages/abc?company_from=csig |
URL 解析规则
当用户提供链接时，从 URL 路径中提取 ID（忽略查询参数）：
| URL 路径 | 提取方式 |
|---|
/spaces/{space_id} | 取 spaces/ 后面的部分作为 space_id |
/pages/{entry_id} | 取 pages/ 后面的部分作为 entry_id |
/t/{team_id}/spaces | 取 t/ 后面的部分作为 team_id |
🛡️ 写入操作安全规则
核心原则：写入、修改、删除操作 必须基于用户明确提供的目标信息，禁止 Agent 自行选择或猜测目标。
🚫 绝对禁止
- 禁止遍历团队/知识库列表后自行选择写入目标
- 禁止根据名称"看起来合适"就决定写入
- 禁止在未确认时执行写入
✅ 允许写入的条件（满足之一即可）
| 条件 | 示例 |
|---|
| 用户提供了明确 URL | "写到这里：https://lexiangla.com/spaces/xxx" |
| 用户提供了明确 ID | "写入 space_id 为 xxx 的知识库" |
| 用户指定名称 + Agent 回显确认 | Agent 搜到后展示详情，用户确认 |
用户要求保存到个人知识库且 whoami 返回了个人知识库 | "保存到我的知识库" → 自动写入个人知识库 |
写入 vs 读取工具分类
写入操作（需满足安全规则）：
entry_create_entry、entry_import_content、entry_import_content_to_entry、block_update_block、block_update_blocks、block_create_block_descendant、block_delete_block、block_delete_block_children、block_move_blocks、entry_rename_entry、entry_move_entry、file_apply_upload、file_commit_upload、file_create_hyperlink
只读操作（不受安全规则限制，可直接执行）：
team_list_teams、team_describe_team、team_list_frequent_teams、space_list_spaces、space_describe_space、entry_list_children、block_list_block_children、search_kb_search、search_kb_embedding_search、space_list_recently_spaces、entry_list_latest_entries、entry_describe_ai_parse_content、file_describe_file、file_download_file、whoami
🔍 工具发现与调用
本服务直接暴露所有业务工具，可直接调用。同时提供以下辅助元工具：
| 元工具 | 用途 |
|---|
list_tool_categories | 列出所有工具分类及其工具列表 |
search_tools | 按关键词或分类搜索工具 |
get_tool_schema | 获取具体工具的完整参数定义 |
标准工作流：
1. 直接调用已知工具：team_list_teams()、search_kb_search(keyword="xxx") 等
2. 不确定参数时：get_tool_schema(tool_name="xxx") → 获取参数定义
3. 不确定工具名时：search_tools(query="关键词") → 找到工具名
🧩 Block 结构规则
🍃 叶子节点（不能有 children）
| 类型 | 说明 |
|---|
h1 ~ h5 | 标题块 |
code | 代码块 |
image | 图片块 |
divider | 分割线 |
mermaid | Mermaid 图表 |
plantuml | PlantUML 图表 |
attachment | 附件块 |
video | 视频块 |
📦 容器节点（必须指定 children）
| 类型 | children 内容 |
|---|
callout | 必须，内容块 |
toggle | 必须，折叠内容 |
table | 必须，table_cell |
table_cell | 必须，内容块 |
column_list | 必须，column |
column | 必须，内容块 |
可选 children 节点
p、bulleted_list、numbered_list、task 可嵌套子内容，children 为可选。
重要：标题与内容的平级关系
标题和其下的内容应该是平级的，通过顶层 children 的顺序来体现文档结构：
{
"children": ["h2_1", "para_1", "para_2", "h2_2", "para_3"],
"descendant": [
{"block_id": "h2_1", "block_type": "h2", "heading2": {...}},
{"block_id": "para_1", "block_type": "p", "text": {...}},
{"block_id": "para_2", "block_type": "p", "text": {...
...
...
📝 内容读取工具选择
| 工具 | 返回内容 | 用途 |
|---|
entry_describe_entry | 条目元信息（ID、名称、类型、创建时间等） | 获取基本信息、后续操作前确认 |
entry_describe_ai_parse_content | 条目正文内容 | 读取实际内容进行摘要/分析/处理 |
entry_describe_entry 不包含正文内容。需要阅读/总结/分析文档时，必须使用 entry_describe_ai_parse_content。
⚙️ 通用优化技巧
_mcp_fields 字段筛选
所有工具均支持 _mcp_fields 参数，只返回需要的字段，减少 token 消耗：
# 只获取条目 ID 和名称
entry_list_children(parent_id="xxx", _mcp_fields="entries.id,entries.name")
# 只获取搜索结果的标题和链接
search_kb_search(keyword="xxx", _mcp_fields="items.target_id,items.title,items.target_type")
📚 文档模板参考
写入文档前，先确定文档类型，按对应大纲组织内容：
| 类型 | 适用场景 | 核心结构 |
|---|
| 推广文案型 | 功能推广、工具介绍 | callout(价值) → 痛点 → 方案 → 对比 → 上手 |
| 技术文档型 | API 文档、开发指南 | 概述 → 快速开始 → 详细说明(参数表) → 示例 |
| 操作指南型 | 使用教程、配置指南 | callout(目标) → 前置准备 → 操作步骤 → 验证 |
Callout 语义映射：
| 语义 | 类型 | 配色 |
|---|
| 核心/重要/价值 | primary | #E3F2FD |
| 提示/建议/tips | tip | #FFF3E0 |
| 成功/完成 | success | #E8F5E9 |
| 警告/注意/风险 | warning | #FFF8E1 |
| 错误/禁止/危险 | error | #FFEBEE |
完整模板见 references/doc-templates.md
📎 辅助资源索引
参考文档（references/）
| 文档 | 说明 |
|---|
references/block-schema.md | Block 类型完整字段定义 |
references/mcp-examples.md | 复杂 Block 结构示例 |
references/markdown-to-block.md | Markdown 转 Block 指南 |
references/block-update.md | 批量更新 Block 方法 |
references/content-reorganize.md | 文档结构重组方案 |
references/folder-sync.md | 文件夹同步方案 |
references/markdown-import.md | Markdown 导入详解 |
references/common-errors.md | 常见错误排查（高频错误速查表） |
references/doc-templates.md | 文档类型与大纲模板 |
references/theme-config.md | 主题配色配置 |
辅助脚本（scripts/）
| 脚本 | 说明 |
|---|
scripts/upload-files.py | 批量文件上传（支持单文件/文件夹/并行） |
scripts/sync-folder.ts | 文件夹增量同步 |
upload-files.py 用法：
python scripts/upload-files.py --files doc.md --entry-id <parent_entry_id>
python scripts/upload-files.py --folder ./docs --entry-id <parent_entry_id> --parallel 5
python scripts/upload-files.py --folder ./docs --entry-id <entry_id> --output plan.json --dry-run
❓ 常见问题
Q: 如何选择 Markdown 导入方式？
file_apply_upload → PUT → file_commit_upload：保留原始文件格式，支持版本管理，适合文档归档entry_import_content：转换为 Block 结构，可在线编辑，适合协作场景
Q: Block ID 如何管理？
客户端传入的 block_id 是临时标识，用于在单次调用中建立块间关系。服务端返回实际 ID 映射，后续更新操作使用服务端返回的 ID。
Q: 表格单元格如何排序？
children 数组按从左到右、从上到下顺序排列。例如 2×2 表格：[row1_col1, row1_col2, row2_col1, row2_col2]
更多错误排查见 references/common-errors.md
