在 HarmonyOS 项目里接入 @wps/wps_sdk 时，真正卡住进度的往往不是「会不会写 OpenFileRequest」，而是接入准备阶段的一组高频疑问：凭据怎么和包名对应、换 HAR 后为何还报 1013、注册成功前能不能打开、激活序列号该写在哪、为什么打开后只能预览。本文按「申请 → 注册 → 打开」把这些问题收成可执行的排查顺序，字段语义以官方对接文档为准。

一、疑问先落到调用链，而不是口头口径

WPS Open SDK 鸿蒙版以 HAR 交付，对外入口是单例 WPSApi。业务能打开文档之前，至少要满足：

阶段	必须完成	常见失败表现
交付物	HAR + appKey/appSecret 与包名匹配	安装后仍 1013
注册	registerApp 返回 OK	sendRequest 直接抛异常
打开	沙箱路径 + OpenFileRequest	ResultCode.ERROR / 只读

把「常见疑问」映射到阶段，联调才不会在群里反复问同一句「为什么打不开」。建议冷启动完成注册，业务按钮在 wpsReady 前禁用。

二、凭据、包名与 HAR：三件套必须成对

接入凭据与三方应用 bundleName 绑定。调试包、正式包、渠道包若包名不同，须分别申请，不能指望「同一套 key 到处跑」。换包名后继续用旧凭据，典型结果是 ResultCode.ERROR_CODE_AUTH_FAILURE（1013）。

HAR 也要与申请时约定的凭据形态一致。联调绿、上架红时，优先核对：

1. 当前安装包的 bundleName 是否与申请邮件一致
2. 工程依赖的 HAR 是否被旧缓存污染（换包后 clean）
3. Release 构建是否误用了 Debug flavor 的密钥

import { WPSApi, RegisterAppRequest, ResultCode } from '@wps/wps_sdk';

let wpsReady = false;

async function ensureRegistered(ctx: UIAbilityContext): Promise<void> {
  if (wpsReady) return;
  const result = await WPSApi.sendRequest(
    new RegisterAppRequest(ctx, APP_KEY, APP_SECRET)
  );
  if (result.code === ResultCode.ERROR_CODE_AUTH_FAILURE) {
    throw new Error(`1013 auth: ${result.msg ?? ''}`);
  }
  if (result.code !== ResultCode.OK) {
    throw new Error(`register failed: ${result.code} ${result.msg ?? ''}`);
  }
  // 若凭据形态要求激活序列号，在 OK 后注入（见下一节）
  wpsReady = true;
}

日志建议保留 code、msg、当前 bundleName 后缀；不要打印完整 secret。密钥用构建注入，勿提交公开仓库。

三、激活序列号：注册成功后全局设，不要每次打开塞

部分接入场景除 appKey/appSecret 外，还会拿到 WPS 激活序列号。对接文档推荐在 registerApp 成功回调或 ResultCode.OK 之后调用 WPSApi.setWpsFileToken(token)，一次设置，后续 OpenFileRequest 自动携带。

不推荐在每次构造 OpenFileRequest 时写入 wpsToken：容易漏设、难审计，也会让「注册问题」和「打开问题」缠在一起。是否需要序列号，以当前 HAR / 凭据约定为准，不要用设备上的 WPS 图标外观去猜。

async function ensureRegisteredWithToken(
  ctx: UIAbilityContext,
  activationSn?: string
): Promise<void> {
  await ensureRegistered(ctx);
  if (activationSn) {
    WPSApi.setWpsFileToken(activationSn);
  }
}

序列号申请渠道通常与 SDK 凭据不同，项目排期里要拆成两项，避免「HAR 到了、序列号还在商务流程」导致假失败。

四、打开层默认行为：只读、沙箱、未注册即发请求

三个最容易被当成「SDK 坏了」的默认语义：

现象	优先解释	处理
能打开不能改	enableEdit 未设或为 false	显式 true
路径报 ERROR	外部 URI 权限不足	先拷贝到 filesDir
Promise 抛异常	注册未完成就 sendRequest	try/catch + ensureRegistered

async function openEditable(ctx: UIAbilityContext, sandboxPath: string) {
  await ensureRegisteredWithToken(ctx, ACTIVATION_SN_OR_EMPTY);
  const req = new OpenFileRequest(ctx, sandboxPath);
  req.enableEdit = true;
  try {
    const result = await WPSApi.sendRequest(req);
    if (result.code !== ResultCode.OK) {
      console.error(`open ${result.code}: ${result.msg}`);
    }
    return result;
  } catch (e) {
    // 未注册完成时常见：进入 catch，而不是 result.code
    console.error('sendRequest rejected', e);
    throw e;
  }
}

预览入口与编辑入口应共用同一打开函数，只差布尔参数，避免两套 new OpenFileRequest 漂移。关闭回传、水印、extraOptions 属于后续叠加项：先绿「可编辑打开」，再叠策略与回传。

五、联调清单：把疑问变成对表项

把群里反复出现的问题固化成清单，新人合入会稳很多：

1. 申请材料含应用名、Bundle 包名、用途；包名变更已重新申请
2. HAR 集成后 clean；依赖树只有一份 @wps/wps_sdk
3. 冷启动 registerApp OK；1013 时核对 key/secret/包名/HAR
4. 需要序列号时，在注册 OK 后 setWpsFileToken，全仓搜索确认无散落 wpsToken
5. 文件入沙箱 → enableEdit = true → sendRequest 包 try/catch
6. 正式包包名再跑一遍注册与打开，避免「本地绿、上架红」

日志字段	用途
code / msg	区分 1013 与 ERROR
bundleName 后缀	核对凭据绑定
enableEdit	解释只读投诉
是否已 setWpsFileToken	解释部分凭据形态下打不开

六、工程习惯：Facade 收口，页面只关心三种态

页面层不要直接散落 RegisterAppRequest / OpenFileRequest。建议 Facade 返回业务可读状态：「未就绪」「已打开」「可重试失败」。上传、归档模块订阅结果，而不是在打开按钮回调里假设一定成功。

Code Review 固定看四项：是否绕开 ensureRegistered、是否打印 secret、是否外部路径直传、是否把策略参数一次堆满导致无法归因。换 HAR 后 clean；Token 全局设置；Release 关闭敏感日志。

七、小结

接入期「常见疑问」大多可以收敛到三件事：凭据与包名成对、注册时序正确、打开默认值理解到位。把申请、注册、打开拆成清单，用 ensureRegistered + 沙箱路径 + 显式 enableEdit 打底，再叠加水印、管控与回传，联调会从猜原因变成对表排查。字段与错误码以官方对接文档为准；周五用正式包包名再验注册与可编辑打开各一次。

坚持两周后，1013 与「只能预览」类工单通常会明显下降。注释写清「注册完成前禁止 sendRequest」「序列号只在注册成功后注入」，比口头说「参考 Demo」更耐看。细节更新时先改 Facade，再改页面。

---

基于 WPS Open SDK 鸿蒙版对接实践整理，仅供开发者参考。
官方对接文档：https://365.kdocs.cn/l/clQl5cek2NoT