腾讯乐享知识库 Lexiang Knowledge Base

用于访问乐享知识库平台的专用 skill。当用户明确提到「乐享」「lexiang」「知识库」「知识」「文档」等关键词，或用户提供的链接 host 为 lexiangla.com，应优先调用本 skill。本 skill 支持：获取文档内容与元数据、搜索文档内容、查询知识库与目录结构、创建/编辑/移动文档、管理标签与评论、上传文件及维护附件等知识库操作能力。

# 乐享 MCP 服务

> **触发场景**：当用户明确提到「**乐享**」「**lexiang**」「**知识**」「**文档**」，或提供 `lexiangla.com` 链接，或给出 `space_id`、`entry_id`、`team_id`、`/spaces/`、`/pages/` 等乐享标识时，应使用本服务。
>
> **优先级**：处理乐享相关操作时，**优先使用本 Skill 提供的能力**，而非直接调用 MCP。本 Skill 封装了最佳实践和完整的使用说明。
>
> 需要调用 MCP 时，请以 MCP 服务端返回的最新的 schema 为准。

---

> **⛔ 必读（调用前必须理解）：**
>
> 1. 本服务**直接暴露所有业务工具**（如 `team_list_teams`、`search_kb_search` 等），可直接调用
> 2. 调用前先确认工具参数定义，**以 MCP 返回的 schema 为准**
> 3. 不确定参数时，使用 `get_tool_schema(tool_name="xxx")` 获取最新定义

---

## 🔑 AccessToken 生命周期管理

### 阶段 1：未配置 Token

当调用 MCP 连接失败或无认证信息时：

1. 告知用户需要获取乐享 MCP 的 access_token
2. 引导用户打开 `https://lexiangla.com/mcp` 获取配置信息
3. 用户获取后，帮助完成 mcp.json 配置（参见「快速开始」）

### 阶段 2：Token 即将过期

当 MCP 返回正常结果但附带过期预警信息时：

1. **先正常返回本次结果**
2. 在结果末尾附加提醒，引导用户续期：

```
⚠️ 您的乐享访问令牌即将过期。请打开以下链接自动续期（需已登录）：
https://lexiangla.com/mcp?action=renew&company_from={company_from}
```

### 阶段 3：Token 已过期（401 响应）

当 MCP 返回 401 未授权时：

1. **不要反复重试**
2. 引导用户重新创建会话：

```
🔒 您的乐享访问令牌已过期。请打开以下链接创建新会话：
https://lexiangla.com/mcp?action=recreate&company_from={company_from}
创建后请将新的 access_token 提供给我进行更新。
```

### 租户隔离规则

- `company_from` 和 `access_token` **必须属于同一租户**，不同租户的 token 不能混用
- OAuth 不支持跨租户授权
- 续期或重建 token 时，URL 中的 `company_from` 必须与当前配置一致
- 如果用户切换了企业/租户，必须重新获取对应租户的 token

---

## 📊 数据模型

### 核心概念

| 概念                | 说明                                                                                      |
| ------------------- | ----------------------------------------------------------------------------------------- |
| **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 规则

**域名固定为** `https://lexiangla.com`——即 `{domain}` = `https://lexiangla.com`

> ⛔ **`company_from` 不是子域名，只能作为 URL 查询参数使用！**
>
> ❌ 错误：`https://km.lexiangla.com/pages/xxx`（把 company_from 当子域名）
> ❌ 错误：`https://abc.lexiangla.com/pages/xxx`
> ✅ 正确：`https://lexiangla.com/pages/xxx?company_from=km`
> ✅ 正确：`https://lexiangla.com/pages/xxx`（无 company_from 时）

**链接拼接规则：**

```
https://lexiangla.com/pages/{entry_id}?company_from={company_from}
```

如果没有 `company_from`，直接使用 `https://lexiangla.com/pages/{entry_id}`（不加查询参数）。

**`company_from` 获取方式**（按优先级）：
1. MCP 连接 URL 中的 `company_from` 查询参数（如 `mcp?company_from=km` 中的 `km`）
2. 环境变量 `COMPANY_FROM`
3. 用户提供的 URL 中已有的 `company_from` 查询参数
4. 如果均不可用，省略该参数

> **⛔ 严禁使用 `mcp.lexiang-app.com` 拼接任何用户可访问的链接！** 该域名仅用于 MCP 接口调用，不是用户访问地址。
> **⛔ 严禁将 `company_from` 拼接为子域名！** `company_from` 只能作为 URL 查询参数（`?company_from=xxx`），不能拼成 `https://{company_from}.lexiangla.com`。

| 资源     | URL 格式                        |
| -------- | ------------------------------- |
| 团队首页 | `{domain}/t/{team_id}/spaces`   |
| 知识库   | `{domain}/spaces/{space_id}`    |
| 知识条目 | `{domain}/pages/{entry_id}`     |

### URL 解析规则

当用户提供链接时，从 URL 路径中提取 ID（**忽略查询参数**）：

| URL 路径                      | 提取方式                                    |
| ----------------------------- | ------------------------------------------- |
| `/spaces/{space_id}`          | 取 `spaces/` 后面的部分作为 `space_id`      |
| `/pages/{entry_id}`           | 取 `pages/` 后面的部分作为 `entry_id`       |
| `/t/{team_id}/spaces`         | 取 `t/` 后面的部分作为 `team_id`            |

---

## 🛡️ 写入操作安全规则

> **核心原则**：写入、修改、删除操作 **必须基于用户明确提供的目标信息**，禁止 Agent 自行选择或猜测目标。

### 🚫 绝对禁止

1. 禁止遍历团队/知识库列表后自行选择写入目标
2. 禁止根据名称"看起来合适"就决定写入
3. 禁止在未确认时执行写入

### ✅ 允许写入的条件（满足之一即可）

| 条件 | 示例 |
| ---- | ---- |
| 用户提供了明确 URL | `"写到这里：https://lexiangla.com/spaces/xxx"` |
| 用户提供了明确 ID | `"写入 space_id 为 xxx 的知识库"` |
| 用户指定名称 + Agent 回显确认 | Agent 搜到后展示详情，用户确认 |

### 写入操作涉及的工具

`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` 等只读操作可正常执行。

---

## 🔍 工具发现与调用

本服务**直接暴露所有业务工具**，可直接调用（如 `team_list_teams()`、`search_kb_search(keyword="xxx")`）。

同时提供以下辅助元工具，帮助发现和理解工具：

| 元工具                 | 用途                                           |
| ---------------------- | ---------------------------------------------- |
| `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="关键词") → 找到工具名
```

> 大多数常用工具已在本 Skill 中列出，可直接使用；遇到新工具或不确定的参数时，再用 `get_tool_schema` 查询。

---

## 🚀 快速开始

### 获取配置参数

访问：https://lexiangla.com/mcp

登录后获取：
- **company_from**：你的企业标识
- **access_token**：访问令牌（格式 `lxmcp_xxx`）

### 配置方式

#### 方式1：自动配置（推荐）

请阅读 `setup.md` 中的步骤说明，按指引完成配置。

#### 方式2：环境变量

```bash
export COMPANY_FROM="your_company"
export LEXIANG_TOKEN="lxmcp_YOUR_TOKEN_HERE"
```

#### 方式3：直接修改 mcp.json

编辑 `mcp.json`，将 `${COMPANY_FROM}` 和 `${LEXIANG_TOKEN}` 替换为实际值。

### mcp.json 配置模板

```json
{
    "mcpServers": {
        "lexiang": {
            "enabled": true,
            "url": "https://mcp.lexiang-app.com/mcp?company_from=${COMPANY_FROM}",
            "transportType": "streamable-http",
            "headers": {
                "Authorization": "Bearer ${LEXIANG_TOKEN}"
            }
        }
    }
}
```

### 安装后验证

配置完成后，**立即调用** `whoami()` 进行连通性检查并获取用户身份信息：

1. 调用 `whoami()`
2. **成功**（返回用户信息）→ 向用户展示欢迎消息：

```
✅ 乐享 MCP 连接成功！

👤 当前用户：{用户姓名}
🏢 绑定乐享：{企业/租户名称}

🎉 配置已就绪，你现在可以这样使用乐享知识库：

💡 试试这样提问：
• "看看我最近访问的知识库有什么更新"
• "我要记录今天的工作内容，为我创建一个乐享文档并拟写一个模版"
• "搜索关于 XXX 的知识文档"
• "帮我总结一下这个知识库的内容：{知识库链接}"
```

> 根据 `whoami` 返回的实际字段灵活调整展示内容。

3. **401 错误** → token 无效或已过期，引导用户重新获取（参见「AccessToken 生命周期管理」）
4. **连接超时/其他错误** → 检查 mcp.json 配置是否正确

### 遇到问题？

| 问题 | 解决方案 |
|------|----------|
| 连接无响应 | 确认 mcp.json 中 URL 包含 `company_from` 且格式正确 |
| 401 未授权 | token 过期或租户不匹配，参见「AccessToken 生命周期管理」 |
| 参数报错 | 执行 `get_tool_schema(tool_name="xxx")` 获取最新参数定义 |

---

## 🎯 意图识别与澄清

### 明确使用本 Skill 的场景

1. **关键词触发**：用户提到「乐享」「lexiang」「知识库」「知识」「文档」
2. **链接触发**：用户提供的链接 host 为 `lexiangla.com`
3. **上下文延续**：用户之前已明确使用乐享，后续操作默认继续

### 🛡️ 写入安全提醒

- ❌ 禁止遍历团队/知识库列表后自行选择写入目标
- ✅ 用户提供了 URL / ID / 精确名称 + 确认后方可写入
- ✅ 写入目标不明确时（如"帮我写到乐享""执行吧"但未指定知识库），需要求用户提供具体写入位置
- ✅ 读取操作（搜索、浏览、查看）不受此限制

---

## 工具概述

本 MCP 服务提供以下工具，**可直接调用**。参数不确定时以 `get_tool_schema` 返回为准。

### 📚 知识库管理
- `entry_create_entry` — 创建文档/文件夹
- `entry_import_content` — 导入 Markdown/HTML 创建新文档（⚠️ 仅新建）
- `entry_import_content_to_entry` — 导入内容到已有页面（支持覆盖/追加）
- `entry_list_latest_entries` — 获取最近更新条目
- `entry_rename_entry` — 重命名条目

### 📎 文件管理
- `file_apply_upload` — 申请文件上传（返回 upload_url 和 session_id）
- `file_commit_upload` — 确认上传完成

### 🧩 Block 操作
- `block_convert_content_to_blocks` — Markdown/HTML 转 Block 结构
- `block_create_block_descendant` — 创建 Block 结构
- `block_update_block` — 单块更新
- `block_update_blocks` — 批量更新
- `block_move_blocks` — 移动 Block
- `block_delete_block_children` — 删除子节点
- `block_delete_block` — 删除指定 Block（含子孙）
- `block_describe_block` — 获取单个 Block 详情
- `block_list_block_children` — 读取 Block 内容

### 🔍 搜索与发现
- `search_kb_search` — 关键词搜索
- `search_kb_embedding_search` — 语义向量搜索
- `team_list_teams` — 获取团队列表
- `team_d