在 HarmonyOS 上落地 WPS 文档二开时，统一版 SDK 把专业版与个人版的调用面收敛到同一组 TypeScript API，但厂商侧仍要在工程里回答一批「看起来简单、答错就要返工」的问题：旧专业版项目要不要整体迁移？C 端应用能否复用 B 端 HAR？注册、Token、不落地各管什么？本文不按文档目录复述，而是按架构决策 → 运行时分支 → 联调排错 组织 FAQ，并给出可放进 init 模块的示例代码。
背景：为什么 FAQ 比参数表更重要
参数表解决「字段是什么」，FAQ 解决「我们项目该不该用」。统一版发布后，不少团队把「API 统一」理解成「凭据通用」「HAR 通用」「WPS 客户端通用」------四者里只有 API 层面对齐，其余三项仍须按 ToB/ToC 分别配置。售前若承诺「一套包打天下」，研发阶段就会集中爆发 1013、ERROR 与「能打开不能编辑」类问题。把 FAQ 前置到技术评审，比上线后补文档便宜得多。建议在立项时由研发牵头过一遍：产品形态（政企内网 vs 应用商店）、合规要求（是否不落地）、目标 WPS 客户端版本，再决定申请哪套 HAR。售前材料里避免出现「统一版=一套凭据通用」这类表述，可减少后期扯皮。
统一版关系与个人版 WPS 要不要专业版
统一版是能力扩容 ，不是下架专业版。原 ToB 场景的打开、编辑、水印、关闭回传、不落地等能力保留；新增的是对 WPS 个人版客户端 的 ToC 支持。已有专业版代码的迁移成本主要在：核对 HAR 是否为统一版交付包（仍须专业版渠道申请）、确认 setWpsFileToken 仍在注册 OK 回调中执行、新增 SdkConstants.isPersonalSdk() 分支以兼容未来双版本打包。
个人版（ToC）不需要 先装专业版 WPS。ToC 链路是：个人版 HAR + 个人版凭据 + 用户设备上的 WPS 个人版。注册 OK 后即可 OpenFileRequest，无 激活序列号环节。把 ToB 的 Token 逻辑带进 ToC 不会提高成功率，反而增加配置噪音。排错时先用 isPersonalSdk() 确认分支，再查沙箱路径与 enableEdit。
共用代码、不落地与个人版能力边界
业务层可共用，配置层须分叉。 推荐抽象三层：依赖（专业版 HAR vs 个人版 HAR）、注册后（ToB setWpsFileToken vs ToC 跳过）、不落地（enableLocalization 仅 ToB 生效）。打开文档的 enableEdit、wpsTransferType、水印等可在共用函数里构造，仅初始化路径不同。
个人版侧最显著缺失是文档不落地 及其连带策略：专业版默认不落地，并会强制关闭部分云文档、分享、打印相关 extraOptions；个人版侧该开关不生效。若产品强依赖不落地合规，必须走 ToB 全链路，不能「ToC HAR + 期望不落地」。其余本地打开、编辑、水印、关窗回传在统一版中均存在，差异在客户端版本与 HAR 匹配。
typescript
import { common } from '@kit.AbilityKit';
import {
WPSApi, RegisterAppRequest, ResultCode, SdkConstants,
} from '@wps/wps_sdk';
let ready = false;
export async function bootWps(ctx: common.UIAbilityContext): Promise<void> {
const res = await WPSApi.sendRequest(new RegisterAppRequest(ctx, KEY, SECRET));
if (res.code === ResultCode.ERROR_CODE_AUTH_FAILURE) {
throw new Error('凭据或包名不匹配');
}
if (res.code !== ResultCode.OK) {
throw new Error(res.msg ?? 'registerApp 失败');
}
if (!SdkConstants.isPersonalSdk()) {
WPSApi.setWpsFileToken(SN);
}
ready = true;
}
export function assertWpsReady() {
if (!ready) throw new Error('WPS 尚未完成注册');
}UI 在 ready 前禁用「打开文档」，可避免未注册异常。打开函数开头调用 assertWpsReady()，比在每个页面散落 if 更易维护。
凭据申请与联调误区清单
申请维度：包名 + 版本类型（ToB/ToC） 。凭据与 bundleName 绑定，内测/生产包名不同则凭据不通用。激活序列号（ToB）与 appKey/appSecret 分开管理；序列号只通过 setWpsFileToken 注入，不要塞在 OpenFileRequest.wpsToken 里。集成顺序固定：HAR → registerApp →（ToB）Token → 沙箱路径 → open。
常见误区五条，建议写入 onboarding：
- 只
.then不.catch：未注册时抛异常，不进result.code - OK + 空 data 当回传成功 ：未开
wpsTransferType时正常 - content URI 直传 OpenFileRequest：须先落沙箱
- enableEdit 默认只读 ：显式
true才能编辑 - 混用 HAR：1013 或打开失败的高频根因
政企多包名场景可在 Application 启动时打印当前 bundleName 与凭据环境标识（勿打明文 secret），便于测试同学对照申请邮件。HarmonyOS 上 WPS 与应用生命周期不同步，测试「关闭文档窗口」与「切回应用」要分开验证回传逻辑。
若产品同时规划 ToB 与 ToC 两条产品线，不建议在单包内通过运行时切换 HAR------鸿蒙侧依赖在编译期确定，更稳妥的做法是拆 flavor 或拆应用，各用各的凭据与 HAR。联调阶段可维护一份「版本对照表」：当前包名、HAR 文件名、是否个人版、是否已注入 Token、测试机 WPS 版本号，每周例会过一遍，能避免大量重复性排错会议。
小结
HarmonyOS WPS 二开的 FAQ 本质上是版本与配置边界 问题，而非 API 数量问题。统一版的价值在于减少 if (platform) 式分裂，而不是取消 ToB/ToC 配置。选型、申请、注册、打开四条链路上各答对一题，整体联调周期会短很多。把 bootWps 与 assertWpsReady 固化为基础模块，业务页面只关心「已注册 / 可打开 / 回传就绪」三种状态即可。后续若接入水印、修订模式或不落地组合，建议在已稳定注册打开链路之后再叠功能，便于定位新增参数带来的 ERROR。
阅读建议：已了解鸿蒙 Ability 与 Promise 基础。
官方对接文档：365.kdocs.cn/l/clQl5cek2...
技术交流 QQ 群：628436767