金山文档 Skill 架构升级：从 mcporter 到 kdocs-cli

金山文档 Skill 迎来了一次跨越式版本迭代。这并非简单的功能补丁，而是一次从底层架构到上层接口的全面重构。核心变化在于：工具调用方式从依赖 MCP 中间层 mcporter，迁移到专用的独立命令行工具 kdocs-cli。对于每一位使用金山文档 Skill 的开发者而言，理解这次升级的设计逻辑与实际差异，是顺利完成迁移、充分发挥新版能力的前提。

本文将从架构演进、安装部署、认证机制、调用范式、功能扩展、参考文档体系、版本管理七个维度展开深度对比，帮助你建立完整的认知框架。

架构演进：MCP 中间层 vs 原生 CLI

旧版的技术栈建立在 MCP（Model Context Protocol）协议之上。所有工具调用必须经过 mcporter 这个中间层代理转发，链路为 Agent → mcporter call → MCP 服务端 → 金山文档 API。这种架构的优势在于协议通用性强，任何支持 MCP 的客户端（Cursor、Claude Code 等）都能接入。但代价也很明显：mcporter 本身是一个通用的 MCP 管理工具，并非为金山文档量身定制，在参数传递、错误诊断、版本同步等环节存在天然的摩擦成本。

新版彻底抛弃了 mcporter 依赖，改为预编译的原生二进制工具 kdocs-cli。调用链路简化为 Agent → kdocs-cli → 金山文档 API，少了一层转发开销。更关键的是，kdocs-cli 作为专用工具，能够内置金山文档特有的逻辑：自动 SHA256 校验下载文件、内置 JSON 自动修复引擎处理跨平台引号问题、统一的 --silent/--compact/--verbose 输出控制、内置 upgrade 自升级与回滚机制。这些能力在通用中间层上难以实现，或需要大量额外配置。

从文件数量也能直观反映架构复杂度的变化。旧版 Skill 包仅含 22 个文件，1 个安装脚本（setup.sh）；新版膨胀至 74 个文件，提供三套安装脚本（setup.sh、setup.ps1、setup.cjs），分别覆盖 Linux、Windows 和 Node.js 环境。

安装部署：三平台原生支持

旧版的安装流程相对单一，主要通过 bash scripts/setup.sh 完成脚本自动化注册，将金山文档作为 MCP 服务注册到 mcporter 配置中。Windows 用户如果没有 Git Bash 或 WSL，还需要手动配置 mcporter，体验并不友好。Token 获取依赖 get-token 系列脚本（get-token.sh、get-token.js、get-token.ps1），三套脚本分别对应三种运行环境，维护成本高且容易因环境差异报错。

新版采用预编译二进制分发，安装过程大幅简化。运行 PowerShell 安装脚本后，工具会自动检测 CPU 架构（amd64 或 arm64），从 CDN 下载对应平台的 zip 包，进行 SHA256 完整性校验，解压后放入本地目录（Windows 为 %LOCALAPPDATA%\kdocs-cli\），并自动将安装路径追加到用户 PATH 环境变量。整个过程无需 Node.js、无需 Go 运行时、无需 mcporter。升级同样简单，kdocs-cli upgrade 一条命令即可完成自升级，旧版本自动备份到 ~/.kdocs-cli/backup/ 目录，支持 --rollback 回滚。

认证机制：系统密钥链取代环境变量

认证方式的升级是此次迭代中最具安全价值的变化。

旧版将 Token 存储在 mcporter 的 kdocs 配置中，通过 HTTP Header 的 Authorization 字段传递。虽然比裸环境变量安全，但本质上仍是一个文本配置文件中的明文存储。Token 过期后需要运行 get-token 脚本重新获取，脚本还会尝试自动打开浏览器进行 OAuth 登录。

新版引入了系统密钥链概念。kdocs-cli auth set-token 将 Token 加密保存到操作系统的原生凭据存储中，而非明文配置文件。同时提供了 kdocs-cli auth status 诊断命令，能够检测 Token 来源（环境变量、密钥链或命令行参数）、密钥链可用性、进程级与用户级注册表一致性等多维度状态。Token 含特殊字符时，支持 stdin 管道模式传入，避免 Shell 转义问题。

对于旧版用户，如果环境中仍残留 KINGSOFT_DOCS_TOKEN 环境变量，新版能自动识别并发出迁移建议，但不会擅自删除，保持向后兼容。

调用范式：四种参数输入方式

旧版通过 mcporter call 传递参数，工具名按首个点号拆分服务名与动作名。数组或对象参数必须使用 --args 传递 JSON 字符串，不同 Shell 环境的引号处理规则不同——bash 用单引号包裹即可，PowerShell 的单引号会吞掉内部双引号，需要反斜杠转义。这种差异经常导致跨平台脚本难以通用。

新版直接调用 kdocs-cli，服务名与动作名以空格分隔传递，完全消除了点号拆分问题。参数输入提供了四种方式，覆盖不同使用场景：key=value 键值对方式最为简洁，适合简单参数；JSON 字符串适合数组或对象参数；stdin 管道适合脚本集成和复杂嵌套参数；@文件引用适合超长参数或可复用配置。尤其值得一提的是，CLI 内置了 JSON 自动修复引擎，能处理 PowerShell 引号吞没等问题，降低了跨平台调用心智负担。

在输出控制方面，新版提供了 --compact（紧凑 JSON）、--silent（仅输出 data 字段）、--verbose（输出请求详情到 stderr）三个全局选项，方便调试与日志管理。旧版则依赖 mcporter 的默认输出格式，缺乏灵活控制。

功能扩展：新增能力全景

新版在保留旧版全部功能的基础上，新增了三个重要能力方向。

第一，wpp.execute 原子能力引擎。旧版对演示文稿的操作相对有限，仅支持主题字体与配色切换、下载导出等基础功能。新版通过 wpp.execute 工具引入了 JSAPI 执行机制，支持幻灯片增删、复制粘贴、获取数量等页面级操作，以及矩形、圆形、三角形、圆角矩形等形状插入能力。所有命令统一通过 command + param 参数传递，返回标准化的 ok/message/data 结构。虽然当前功能清单仍在扩展中，但这个引擎架构意味着未来可以持续添加新的原子能力而不影响现有接口。

第二，wps.core_execute 在线文字原子能力。这是一个全新的模块，当前已上线三个子模块：文档内容（段落读写、查找替换）、段落格式（对齐、缩进、行间距）、字符格式（字体样式、高亮色），并且规划了样式、表格、图片、书签、目录、页眉页脚、批注等 16 个后续模块。这意味着在线 Word 文档将逐步获得接近桌面端的精细操作能力。

第三，copy_file 和 check_file_name 两个实用工具。copy_file 支持将文件复制到指定目录（可跨盘），解决了旧版只能移动不能复制的痛点。check_file_name 用于在创建文件前检查目标目录下是否已存在同名文件，避免重复创建。

参考文档体系：从扁平到分层

旧版的参考文档采用扁平结构，所有文件直接放在 references 目录下，总数 10 个。工作流文档集中在一个 workflows 子目录中，共计 6 个。

新版将参考文档彻底重构为分层模块化结构。API 参考被拆分为 manage_file、manage_label、manage_other、manage_share、manage_star、read、use、write 八个子文件，按操作类别组织。各产品线有了独立子目录：otl 下拆分为 block_query、block_insert、block_update、block_delete、insert_content、convert 等细粒度文档；dbsheet 拆分为 data_table、field、record、view 四个维度；sheet 拆分为 data 和 worksheet；wpp 新增 execute、export、jsapi、slide、theme 五个文件；kwiki 为每个操作建立了独立文档。此外新增了 file-locating-guide、file-reading-guide、file-writing-guide 三个操作指南文件，以及 tool-combos 工具组合速查。工作流从 6 个扩展到 11 个，新增了 web-scrape、search-read-report、periodic-read-summary、precise-search-analysis、smart-classify 五个场景。

这种分层结构使开发者能够精准定位所需文档，而非在一个大文件中翻找。74 个文件的组织方式本身就是一种 API 导航。

版本管理：内置自检与自升级

旧版的版本管理较为被动：手动运行 mcporter call 检查远端版本，发现差异后按 instruction 中的链接下载替换。整个流程没有自动化，依赖用户主动触发。

新版构建了完整的三步自检流程：首先运行 kdocs-cli version 确认 CLI 已安装；然后 kdocs-cli upgrade --check 检查远端最新版本；最后从 SKILL.md 的 frontmatter 读取版本号，与 CLI 版本对比确认是否同步。Skill 版本落后时，通过 kdocs-cli call check_skill_update 获取下载链接和变更说明，按指引替换即可。

升级过程支持 -y 参数跳过确认直接升级，--rollback 一键回滚。旧版本自动备份，升级失败时可以快速恢复，消除了版本迁移的风险顾虑。

迁移建议

如果你正在使用旧版，迁移步骤可以概括为三步。第一步，运行新版 setup.ps1 安装 kdocs-cli 二进制文件，它会被安装到系统 PATH 中。第二步，将 Token 从 mcporter 迁移到系统密钥链，运行 kdocs-cli auth set-token 命令，CLI 会自动验证 Token 有效性。第三步，将代码中的 mcporter call kdocs 替换为 kdocs-cli，参数格式从 --args JSON 改为四种新方式之一。注意工具名的写法变化：旧版的 otl.insert_content 在新版中变为 otl insert-content（点号变空格，驼峰变短横线）。

整个迁移过程的核心收益在于：消除了 mcporter 这个外部依赖，降低了工具链复杂度；认证安全性从配置文件明文提升到系统密钥链加密；跨平台兼容性从三套脚本适配简化为统一二进制分发；功能覆盖面从基础文档操作扩展到演示文稿和文字文档的原子级控制。对于重度依赖金山文档 API 自动化的场景，这是一次值得投入的升级。