218 lines
8.9 KiB
Markdown
218 lines
8.9 KiB
Markdown
---
|
||
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 等用文件上传（作为附件存储）
|