WPS知识库官方技能从v1到v2的架构变化：从MCP到CLI
Lv.2潜力创作者
一、架构体系变革（核心差异）
维度 | v1.0.0（旧版） | v2.0.1（新版） | 影响说明 |
交互方式 | MCP 协议（Model Context Protocol） | CLI 命令行工具（kwiki-cli kwiki <tool>） | 从 Agent MCP 调用变更为 shell 命令执行，不依赖 mcporter |
调用示例 | mcporter call "kwiki.list_knowledge_view" | kwiki-cli kwiki knowledge-view-list | 命令形态完全不同 |
参数传递 | MCP JSON-RPC 参数体 | Flag 标志（--kuid, --name 等） | 从结构化 JSON 变为命令行 flag，更直观 |
依赖服务 | mcporter（MCP 注册中心） | kwiki-cli 二进制 + npm 包 | 旧版强依赖 mcporter 环境，新版为独立 CLI 工具 |
输出格式 | MCP 返回 JSON | --format json|pretty 控制 | 新版更灵活，支持人类可读的 pretty 格式 |
二、鉴权与认证
维度 | v1.0.0 | v2.0.1 |
Token 获取 | bash scripts/get-token.sh（OAuth 设备码 + 浏览器） | kwiki-cli auth login（设备码 + 浏览器） |
Token 存储 | mcporter 配置中 | OS keyring（优先）→ 环境变量 X_KWIKI_AUTH（降级） |
多账号 | 不支持 | 支持 --account <name>，对应 X_KWIKI_AUTH_<UPPER> |
Token 保活 | 内置心跳（每 5 分钟） | 无内置保活 |
环境变量 | 禁止写入环境变量 | 原生支持 X_KWIKI_AUTH 环境变量 |
兜底方案 | 手动引导用户访问网页 | keyring 不可用时自动降级为环境变量 |
关键变化：新版彻底抛弃 mcporter 作为 Token 存储中介，鉴权链路从 Agent → mcporter → API 简化为 Agent → CLI（keyring/env）→ API。
三、ID 体系与参数简化
维度 | v1.0.0 | v2.0.1 |
核心 ID | drive_id 为主，kuid 为辅 | kuid 统一为主，drive_id 仅用于 file-move 和 file-upload |
个人知识库 | 通过 drive_id 定位 | 0s_<数字> 格式 kuid，后缀与 drive_id 可互推 |
企业知识库 | 通过 drive_id 定位 | 0s 开头纯 ID，禁止解析为 drive_id |
文件节点 | 使用 file_id / link_id | 统一使用 kuid（0l 开头） |
参数文档 | 需查 api_references.md | CLI flag 自带文档，--help 可查 |
关键变化：ID 体系大幅简化，大部分操作只需 kuid，不再区分 drive_id、file_id、link_id。
四、工具能力对比
工具映射表
功能 | v1.0.0 MCP 工具名 | v2.0.1 CLI 子命令 | 变化 |
知识库列表 | list_knowledge_view | knowledge-view-list | 更名，新增分页参数 |
知识库详情 | get_knowledge_view | knowledge-view-get | 更名，支持 kuid/name 查询 |
创建知识库 | create_knowledge_view | knowledge-view-create | 更名，参数简化 |
修改配置 | update_knowledge_view | knowledge-view-update | 新增封面参数 |
关闭知识库 | close_knowledge_view | knowledge-view-close | 更名 |
智能问答 | 无 | knowledge-view-ask | 新增，支持联网/深度思考/SSE |
分享链接 | 无 | knowledge-view-share-link | 新增 |
文件列表 | list_file | file-list | 更名 |
创建文件 | create_file | file-create | 更名，doc_type 更丰富 |
删除文件 | delete_file | file-delete | 更名 |
重命名 | rename_file | file-rename | 更名 |
下载文件 | download_file | file-download | 更名，新增 file_base64 |
格式转换 | convert_file | file-convert | 更名 |
移动文件 | move_file | file-move | 更名 |
导入云文档 | import_file | file-import | 更名 |
上传文件 | upload_file | file-upload | 更名 |
版本自检 | MCP 调用 kwiki.get_skill | skill-update | 新增，CLI 内置自动更新 |
认证管理 | scripts/get-token.sh | auth login/status/logout | 新增 CLI 级认证命令 |
新增能力
智能问答：SSE 流式输出，CLI 默认聚合为完整 JSON，支持 --stream 透传原始行
分享链接：获取知识库外部分享链接
联网搜索 + 深度思考：问答时可选开启
Skill 自动更新：skill-update 检测并更新 SKILL.md
Dry-run 预览：高风险写操作加 --dry-run 预览不执行
移除的能力
MCP 服务注册（scripts/setup.sh）
Token 保活心跳
api_references.md 独立文档
get-token.sh 脚本
五、文件结构与交付物
文件 | v1.0.0 | v2.0.1 |
SKILL.md | 主技能文档 | 主技能文档（全面重写） |
references/workflow.md | 工作流参考 | 工作流参考（全面重写，适配 CLI） |
references/api_references.md | API 参数参考 | 已移除 |
scripts/get-token.sh | Token 获取脚本 | 已移除 |
scripts/setup.sh | MCP 安装脚本 | 已移除 |
install.js | 无 | 新增：一键安装脚本 |
kwiki-cli.json | 无 | 新增：AI 安装清单 |
外部依赖 | mcporter + MCP 服务 | kwiki-cli 二进制（npm install -g） |
六、升级迁移要点
安装方式：旧版依赖 mcporter，新版需 node install.js 安装 CLI 二进制
Token 迁移：旧版 Token 在 mcporter 配置中，新版在 OS keyring 或环境变量 X_KWIKI_AUTH
命令迁移：所有 MCP 调用替换为 kwiki-cli kwiki <tool> [flags]
ID 使用变化：从 drive_id 改为 kuid，注意 0s（知识库）和 0l（文件/文件夹）
不再依赖 mcporter：新版为独立 CLI，无需 MCP 环境
七、总结
对比项 | v1.0.0 | v2.0.1 |
架构 | MCP 协议 + mcporter | CLI 二进制独立工具 |
复杂度 | 依赖多（mcporter + MCP 服务） | 单二进制，零依赖 |
易用性 | 需要 MCP 客户端环境 | 终端直接使用，CI/CD 友好 |
功能覆盖 | 基础 CRUD | 完整 CRUD + 智能问答 + 分享 + 自更新 |
鉴权 | mcporter 配置存储 | OS keyring + 环境变量 |
多账号 | 不支持 | 支持 |
版本管理 | 手动检查 | CLI 内置 skill-update 自动更新 |
适用场景 | MCP 原生 Agent | 终端、CI、脚本、任意 Agent |
v2.0.1 从 MCP 协议依赖的 Agent 内部工具，重构为独立分发的 CLI 命令行工具 kwiki-cli，功能更完整、部署更简单、适用场景更广。
