WPS KnowledgeBase Skill 使用指南

WPS KnowledgeBase Skill 提供WPS个人知识库操作能力，支持知识文档的创建、查询、读取、编辑与协作。

触发规则与优先级

> ⚠️ 本节为最高优先级规则，Agent 在处理任何用户请求时必须首先检查本节。

关键词触发

当用户的 prompt 中出现以下任一关键词，且操作目标是知识库时，必须使用本 Skill（WPS KnowledgeBase）处理：

⛔ 首次阅读此skill.md，或者距上次阅读超12小时，必做项：版本自检（MANDATORY — 在执行任何用户操作之前）

> 本 Skill 被触发后、执行用户请求之前，Agent 必须先完成版本自检。跳过此步骤直接执行操作视为违规。每天使用 SKILL 前进行一次更新检查，按照如下的步骤执行:

Step 1 — 读取本文件头部 frontmatter 的 version 字段，记为 LOCAL_VERSION。

Step 2 — 调用 MCP 工具获取远端最新版本：

kwiki.get_skill version=latest skill_name=kwiki

Step 3 — 比较 LOCAL_VERSION 与返回值中的 version 字段：

• 相同 → 版本最新，继续执行用户请求。
• LOCAL_VERSION 落后 → 按返回值中 instruction 字段的指引完成升级（升级时需保留旧版 mcporter 配置中的 Token，并将其迁移到新版本配置中），或将最新版信息告知用户。升级完成前不得执行其他操作。
• MCP 调用失败（网络异常、服务未注册等） → 告知用户版本自检失败，仍可继续执行操作，但提醒可能不是最新版本。

MCP 服务配置

本 Skill 通过 MCP 协议提供服务，不限定特定客户端，可在任何支持 MCP 的 Agent 中运行（如 OpenClaw、Cursor、Claude Code 等）。

所有操作必须且只能通过 MCP 工具调用完成。

验证 MCP 可用：

kwiki.list_knowledge_view

返回 code: 0 即 MCP 服务正常。

自动化注册（mcporter 环境）：运行 bash scripts/setup.sh 即可完成 MCP 服务注册。首次使用时会自动拉起授权（调用 scripts/get-token.sh）；若检测到 Token 过期，setup.sh 也会自动重新获取。未检测到 mcporter 时会尝试通过 npm install -g mcporter 自动安装。

scripts/setup.sh 会自动完成：

1. 从 SKILL.md frontmatter 提取 version 版本号
2. 若未安装 mcporter，自动通过 npm 全局安装
3. 若 X_KWIKI_AUTH 环境变量为空，自动调用 scripts/get-token.sh 获取（Token 直接写入 mcporter）
4. 注册 mcporter 时携带 X-Kwiki-Auth 和 X-Skill-Version 两个 header，用于服务端鉴权和版本追踪
5. 验证连通性（mcporter list kwiki）
6. 启动 Token 保活进程（每 5 分钟心跳续期）

手动配置（其他 MCP 客户端）：在客户端 MCP 配置中添加知识库服务：

建议在请求 header 中添加 X-Skill-Version 以便追踪版本。

> ⛔ 严禁绕过 MCP：当 MCP 工具不可用时，Agent 不得自行构造 HTTP 请求、手动模拟 MCP JSON-RPC 协议、或通过 curl/Python 直接调用 API 来替代 MCP 调用。正确做法是引导用户修复 MCP 环境后再继续操作。

认证配置

Token 获取

# 登录获取 Token（自动打开浏览器，等待回调）
cd <skill目录> && bash scripts/get-token.sh

备用方式：Windows 用户需通过 Git Bash 或 WSL 执行（bash scripts/get-token.sh）。

> ⚠️ Token 未设置或已过期时，所有工具调用将返回鉴权失败。
> 🔒 Token 安全：不得将 Token 明文值展示给用户或写入不安全位置。
> 🛡️ 避免改动系统环境：默认不会执行 npm install -g 这类全局安装命令；只有你明确加上参数时，才会自动安装 mcporter（bash: --auto-install-mcporter）。

手动获取 Token（登录脚本失败时的兜底方案）

当 scripts/get-token.sh 因环境问题执行失败时，引导用户手动获取：

1. 用户在浏览器访问 https://www.kdocs.cn/kmwiki （需已登录 WPS 账号）
2. 点击页面右上角导航栏「🦞龙虾入口」→ 复制 Token
3. 用户将 Token 提供给 Agent
4. Agent 将 Token 写入 mcporter（<VERSION> 从 SKILL.md frontmatter 的 version 字段读取）：

mcporter config remove kwiki 2>/dev/null;
mcporter config add kwiki "https://zhishi.wps.cn/personalwiki/kwiki_mcp/mcp" \
  --header "X-Kwiki-Auth=<Token>" \
  --header "X-Skill-Version=<VERSION>" \
  --transport http --scope home

> 收到用户 Token 后直接注册到 mcporter，禁止回显 Token 明文。注册后调用任意只读工具验证（code: 0 即成功）。

Token 获取流程（Agent 行为规范）

当需要获取 Token 时，Agent 必须按以下步骤自动化完成，禁止中断会话让用户手动操作：

1. 执行脚本：cd <skill目录> && bash scripts/get-token.sh。脚本内部包含最长 5 分钟等待，调用 shell 工具时超时参数须设置为 300000 毫秒以上
2. 告知用户：同一回复内告知"正在获取授权，请在浏览器完成 WPS 登录"
3. 验证 Token：脚本完成后调用任意只读工具验证

> ⛔ 严禁 Agent 自行构造登录 URL 或回调地址。授权码生成、回调 URL 拼接、Token 交换等所有步骤均由 get-token.sh 内部完成。Agent 只能通过执行 bash scripts/get-token.sh 获取 Token。自行构造会导致回调路径错误，用户登录后无法换取 Token。

操作限制

以下为具体可判定的约束，违反将导致调用失败或数据异常：

1. 禁止泄露凭据：不得将 X_KWIKI_AUTH 的值以明文形式出现在对话、日志、命令输出、代码注释或任何文件中。执行 shell 命令时必须使用变量引用（$X_KWIKI_AUTH），禁止将凭据值直接拼接到命令字符串里
2. 工具调用: 当工具名包含 . 时，务必使用引号包裹工具名以确保正常调用
3. 链接输出规范（强制）: MCP 接口返回的 url 字段是相对路径（如 /l/xxx?source=kmwiki 或 /wiki/l/xxx），Agent 在拼接完整链接时必须使用 https://www.kdocs.cn 作为域名，严禁使用 zhishi.wps.cn 或任何其他域名。拼接规则：https://www.kdocs.cn + data.url 原值。若需手动构造，格式为 https://www.kdocs.cn/wiki/l/${kuid}。
4. mcporter 参数传递格式（关键）: 通过 mcporter call 调用 kwiki 工具时，必须使用 --args 传递 JSON 参数，严禁使用 --json。--json 会导致 MCP 服务端无法正确解析参数，所有字段回退为默认值。正确示例：
   mcporter call "kwiki.tool_name" --args '{"param1":"value1","param2":"value2"}'
   也可使用命名参数格式：
   mcporter call "kwiki.tool_name" param1="value1" param2="value2"
5. 禁止自行构造授权流程：Token 获取只能通过执行 bash scripts/get-token.sh 完成。Agent 不得手动调用 /skills_hub/code/generate、拼接回调 URL、构造登录链接或调用 /skills_hub/access_token/exchange。自行构造会导致回调路径错误，用户登录后无法换取 Token。
6. 严格区分标识符（强制）：WPS API 包含多种 ID 体系。调用接口返回的 kuid、file_id 和 link_id 具有不同用途，严禁在下游调用中混用（如将 kuid 作为 file_id 传入）。参数映射规范必须以 api_references.md 为准。

文件上传注意事项

upload_file 通过 HTTP POST multipart/form-data 直传本地文件。支持 curl 和 Python requests 两种调用方式。

详细参数、curl / Python 调用示例见 references/api_references.md 中 upload_file 一节。

能力范围

支持的操作

> ⚠️ 以下为本 Skill 全部支持的操作。用户请求的操作若不在此表中，Agent 必须明确告知用户当前 Skill 不支持该操作，并让用户决定是否另寻方案。不得尝试搜索代码库寻找替代方案。

完整参数、示例与返回值见 references/api_references.md。

操作守护规则

操作前检查

交付验证

> 原则：不信任操作返回的成功状态。用独立的读取请求验证实际结果。

不可逆操作保护

幂等性与重试

错误速查表

> ⛔ 强制规则：命中下方任一错误条目时，必须立即按「处理方式」向用户提示，禁止尝试其他接口绕过或反复重试。

常见工作流

详细工作流文档见 references/workflow.md，包含完整的工具调用链和决策逻辑。

工具组合速查

各文档类型详细参考

> ⚠️ Agent 行为约束：当你需要调用本 Skill 的工具，但不清楚具体的入参 JSON Schema 或完整操作步骤时，严禁自行捏造参数。你必须先使用文件读取工具（如 read_file）读取以下参考文档：