---
name: lexiang-kb-uploader
description: 乐享知识库（lexiang）上传技能——查找/新建知识库、创建文件夹目录、导入Markdown为在线页面、上传文件附件的完整工作流。当用户要求"传到知识库""上传到乐享""把文件放到知识库""在乐享建个目录""传页面到乐享"等涉及乐享知识库文件操作时触发。
agent_created: true
---

# 乐享知识库上传技能（Lexiang KB Uploader）

## 用途

将本地文件上传到乐享知识库（lexiang），支持四种操作：
1. **查找/新建知识库**——定位个人知识库或团队知识库
2. **创建文件夹目录**——在知识库中建立层级结构
3. **导入页面**——将 Markdown/HTML 内容创建为可在线阅读的页面
4. **上传文件附件**——将任意文件（txt/pdf/docx/zip等）作为附件上传

## 触发场景

- "把文件传到我的知识库"
- "上传到乐享"
- "在知识库里建个目录/文件夹"
- "把这些md文件导成在线页面"
- "把txt文件传到乐享"

## 前置条件

- 乐享知识库 connector 已连接（lexiang: connected）
- 如未连接，引导用户到 connector 管理页面开启

---

## 第一步：查找或新建知识库

### 1.1 获取身份信息与个人知识库

调用 `mcp__lexiang__whoami`（通过 ToolSearch 加载后用 DeferExecuteTool 执行）：
- 返回当前用户信息，其中 `personal_space` 包含个人知识库的 `id` 和 `root_entry_id`
- **root_entry_id 是后续创建文件夹/页面的父节点ID**

### 1.2 查找团队知识库

调用 `mcp__lexiang__team_list_teams` 获取用户所属团队列表，每个团队下有多个知识库。

调用 `mcp__lexiang__space_list_spaces` 获取指定团队下的知识库列表。

### 1.3 新建知识库

如果用户需要新建一个知识库（而非使用个人知识库），在乐享网页端操作更便捷。告知用户访问 `https://lexiangla.com` 在相应团队下创建。

> 个人知识库默认存在，无需新建。`whoami` 返回的 `personal_space` 即为个人知识库。

---

## 第二步：创建文件夹目录

调用 `mcp__lexiang__entry_create_entry`，参数：
- `entry_type`: `"folder"`
- `name`: 文件夹名称
- `parent_entry_id`: 父节点ID（个人知识库根目录用 whoami 返回的 `root_entry_id`，或已创建的文件夹ID）

可嵌套创建：先建父文件夹，拿到返回的 `entry.id`，再以它为 `parent_entry_id` 建子文件夹。

### 示例：创建两级目录

```
1. 创建父文件夹"项目资料"
   parent_entry_id = root_entry_id（个人知识库根节点）
   → 返回 entry.id = "xxx"

2. 创建子文件夹"文档"
   parent_entry_id = "xxx"（上一步返回的ID）
   → 返回 entry.id = "yyy"
```

---

## 第三步：导入页面（Markdown/HTML → 在线页面）

适用于 `.md`、`.html` 文件，或纯文本内容。导入后生成可在线阅读、搜索的页面。

### 单个文件导入

调用 `mcp__lexiang__entry_import_content`，参数：
- `content`: Markdown 或 HTML 原文（**直接传入原文，不要拆分**，接口无长度限制）
- `content_type`: `"markdown"` 或 `"html"`
- `name`: 页面标题
- `parent_id`: 父文件夹 entry_id
- `space_id`: 知识库ID（**必填**，否则报 `parent entry not belong to space` 错误）

> **space_id 获取方式**：个人知识库的 space_id 在 whoami 返回的 `personal_space.id` 中；团队知识库的 space_id 在 space_list_spaces 返回值中。

### 批量导入

当有多个 Markdown 文件需要导入时，推荐用 Agent 工具在后台并行处理：
- 对每个文件：Read 读取内容 → DeferExecuteTool 调用 entry_import_content
- 每个文件导入完再做下一个，避免并发冲突

### 访问链接格式

导入成功后返回 `entry.id`，访问链接为：`https://mcp.lexiang-app.com/pages/{entry_id}`

---

## 第四步：上传文件附件

适用于 `.txt`、`.pdf`、`.docx`、`.zip`、`.mp4` 等任意文件类型。文件以附件形式存储，不转为在线页面。

### 完整上传流程（3步，缺一不可）

#### 第1步：申请上传凭证

调用 `mcp__lexiang__file_apply_upload`，参数：
- `name`: 文件名（含扩展名）
- `mime_type`: 文件MIME类型（如 `text/plain`、`application/pdf`、`application/zip`）
- `size`: 文件大小（字节数，用 `wc -c < "文件路径"` 或 `stat --printf="%s" "文件路径"` 获取）
- `parent_entry_id`: 父文件夹 entry_id
- `upload_type`: `"PRE_SIGNED_URL"`

返回值中需要提取：
- `session_id`：用于第3步
- `upload_url`：用于第2步的 HTTP PUT 地址

#### 第2步：HTTP PUT 上传文件内容

用 Bash 工具执行 curl 命令，将文件内容 PUT 到第1步返回的 `upload_url`：

```bash
# 将 upload_url 存入临时文件（避免特殊字符导致shell解析错误）
echo '<upload_url>' > /tmp/url.txt

# 上传文件（注意 Content-Type 要与第1步的 mime_type 一致）
curl -s -o /dev/null -w "%{http_code}" \
  -X PUT \
  -H "Content-Type: text/plain" \
  -T "本地文件路径" \
  "$(cat /tmp/url.txt)"
```

**返回 200 表示成功。**

#### ⚠️ 常见坑（必读）

1. **Content-Type 必须匹配**：curl 默认发送 `application/x-www-form-urlencoded`，如果 mime_type 是 `text/plain`，必须显式加 `-H "Content-Type: text/plain"`，否则 COS 会返回 403。

2. **URL 含特殊字符**：预签名 URL 包含查询参数（`?`、`&`、`=`），直接写在命令行会被 shell 解析。**解决方案**：将 URL 存入临时文件，用 `"$(cat /tmp/url.txt)"` 读取。

3. **文件名含中文/特殊字符**：文件路径必须用双引号包裹，如 `"E:/路径/文件名.txt"`。

4. **清理临时文件**：上传完成后删除临时 URL 文件。

#### 第3步：确认上传

调用 `mcp__lexiang__file_commit_upload`，参数：
- `session_id`: 第1步返回的 session_id

返回 entry 对象，访问链接：`https://mcp.lexiang-app.com/pages/{entry_id}`

### 批量上传

当有大量文件（如 10+ 个）需要上传时，推荐用 Agent 工具在后台处理：
- 对每个文件重复上述3步
- 用脚本自动化（先循环 apply_upload，再循环 PUT，再循环 commit）

### 更新已有文件

如需替换已上传的文件内容（而非新建）：
- `file_id`: 填已有文件的 file_id（通过 `mcp__lexiang__entry_describe_entry` 获取，返回的 `target_id` 即为 file_id）
- `parent_entry_id`: **填当前文件条目自己的 entry_id**（不是父节点！）

---

## 完整工作流示例

场景：将本地 `资料/` 目录（含 md 文件和 txt 文件）上传到个人知识库。

```
1. whoami → 获取 personal_space.id（space_id）和 root_entry_id
2. entry_create_entry → 创建文件夹"资料"（parent=root_entry_id）→ 得到 folder_id
3. entry_create_entry → 在"资料"下创建子文件夹"文档"和"附件"
4. 对每个 .md 文件：
   Read 文件内容 → entry_import_content（parent=文档文件夹ID, space_id=space_id）
5. 对每个 .txt 文件：
   file_apply_upload → curl PUT → file_commit_upload
6. present_files 呈交知识库访问链接
```

---

## 工具速查

| 操作 | 工具名 | 关键参数 |
|------|--------|----------|
| 获取身份/个人库 | `mcp__lexiang__whoami` | 无 |
| 列出团队 | `mcp__lexiang__team_list_teams` | 无 |
| 列出知识库 | `mcp__lexiang__space_list_spaces` | team_id（可选） |
| 获取知识库详情 | `mcp__lexiang__space_describe_space` | space_id |
| 获取个人知识库 | `mcp__lexiang__space_describe_personal_space` | 无 |
| 创建文件夹/条目 | `mcp__lexiang__entry_create_entry` | entry_type, name, parent_entry_id |
| 导入页面 | `mcp__lexiang__entry_import_content` | content, content_type, name, parent_id, space_id |
| 列出子节点 | `mcp__lexiang__entry_list_children` | entry_id |
| 获取条目详情 | `mcp__lexiang__entry_describe_entry` | entry_id |
| 申请文件上传 | `mcp__lexiang__file_apply_upload` | name, mime_type, size, parent_entry_id, upload_type |
| 确认文件上传 | `mcp__lexiang__file_commit_upload` | session_id |
| 搜索知识 | `mcp__lexiang__lexiang_search` | query, type |

> 所有 `mcp__lexiang__` 开头的工具都是 deferred tools，需要先用 ToolSearch 加载 schema，再用 DeferExecuteTool 调用。

---

## 注意事项

- **space_id 必填**：导入页面时如果不传 space_id 会报 `parent entry not belong to space` 错误
- **文件上传3步缺一不可**：apply_upload → HTTP PUT → commit_upload，少任何一步都无法完成
- **Content-Type 匹配**：HTTP PUT 时必须设置与 apply_upload 中 mime_type 一致的 Content-Type header
- **URL 特殊字符**：预签名 URL 含查询参数，不能直接写在命令行，用临时文件中转
- **个人知识库 vs 团队知识库**：个人知识库通过 whoami 获取，团队知识库通过 team_list_teams → space_list_spaces 获取
- **导入 vs 上传的选择**：md/html 文件优先用 import_content 导入为页面（可在线阅读搜索）；txt/pdf/docx/zip 等用文件上传（作为附件存储）