ai-tools/workbuddy_skills/lexiang-kb-uploader/SKILL.md

name, description, agent_created

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

# 将 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 等用文件上传（作为附件存储）