@heybox/hb-sdk-protocol 0.8.1 → 0.8.2-alpha.2

package/src/payloads.ts

@@ -1,5 +1,5 @@
-/** 当前用户信息与登录能力支持的完整 scope 目录。 */
-export const USER_INFO_AUTHORIZATION_SCOPES = ['identity', 'profile'] as const;
+/** 当前用户信息与登录能力支持的完整 scope 目录（canonical 顺序）。 */
+export const USER_INFO_AUTHORIZATION_SCOPES = ['identity', 'profile', 'steam_account'] as const;
 
 /** 用户信息授权 scope。 */
 export type UserInfoAuthorizationScope = (typeof USER_INFO_AUTHORIZATION_SCOPES)[number];
@@ -13,98 +13,256 @@ export interface LoginResult {
   scopes: LoginScope[];
 }
 
-/** 用户资料授权状态。 */
+/**
+ * 单个用户信息 scope 对当前小程序的授权状态。
+ *
+ * @remarks
+ * - `not_required`：Host 判定该 scope 无需单独征得用户同意。
+ * - `not_requested`：当前授权上下文尚未申请或授予该 scope。
+ * - `granted`：当前小程序可以读取该 scope 对应的资料。
+ * - `denied`：用户拒绝过该 scope，或该 scope 已被撤销。
+ *
+ * 该状态描述用户授权，不代表 `package.json#heybox.permissions` 的声明或平台审批结果。
+ * 当前 Runtime 成功执行 `user.getInfo()` 时会静默授予 `identity` 与 `profile`，因此两项均为
+ * `granted`；其余状态仍保留在公共协议中，供兼容 Host 和授权状态事件使用。
+ */
 export type UserInfoAuthorizationStatus = 'not_required' | 'not_requested' | 'granted' | 'denied';
 
-type CanonicalUserInfoAuthorization = Record<UserInfoAuthorizationScope, UserInfoAuthorizationStatus>;
-
-/** 当前小程序对 canonical 用户信息 scope 的授权状态。 */
-export interface UserInfoAuthorization extends CanonicalUserInfoAuthorization {}
+/**
+ * 当前小程序对 canonical 用户信息 scope 的授权状态。
+ *
+ * @remarks
+ * 该对象固定包含 `identity` 与 `profile`，新能力版本还可能包含可选的 `steam_account`。
+ * `steam_account` 已授权不代表当前一定已绑定 Steam，只有
+ * {@link AuthorizedUserInfo.steam_id} 存在才表示当前有主绑定。该对象只反映用户授权层；开发者仍需
+ * 在 Manifest 中声明 `userInfo` / `steamLibrary`，两层门禁不能互相替代。
+ */
+export interface UserInfoAuthorization {
+  /**
+   * 隔离身份授权状态；控制 `AuthorizedUserInfo.app_user_id` 是否可向当前小程序披露。
+   */
+  identity: UserInfoAuthorizationStatus;
+  /**
+   * 公开资料授权状态；控制 `AuthorizedUserInfo.profile` 中昵称和头像是否可披露。
+   */
+  profile: UserInfoAuthorizationStatus;
+  /** Steam 账号授权状态；legacy Runtime/Version 可能缺失该键。 */
+  steam_account?: UserInfoAuthorizationStatus;
+}
 
 /**
  * 已获准向当前小程序披露的用户资料。
  *
  * @remarks
- * 未开通网络权限且当前黑盒 APP 用户已登录时，Runtime 会隐式授予 `identity` 与
- * `profile`，静默建立或读取隔离身份，并由 `user.getInfo()` 返回该对象。撤销授权后
- * 旧身份失效，调用方应停止使用并清理本地缓存；再次调用 `user.getInfo()` 会静默建立
- * 新的隔离身份。
+ * 当前黑盒 APP 用户已登录时，Runtime 会隐式授予 `identity` 与 `profile`，静默建立或
+ * 读取隔离身份，并由 `user.getInfo()` 返回该对象。此过程只要求 Manifest 声明
+ * `userInfo`，不要求公开 `network` 权限，也不会返回授权码或创建开发者服务端会话。
+ *
+ * 撤销授权后旧身份失效；调用方应停止使用旧值，并清理本地缓存与开发者服务端会话。
+ * 再次调用 `user.getInfo()` 会按当前账号重新建立隔离身份，不能假定新旧 `app_user_id`
+ * 相同。
+ *
+ * @see [auth.login](/reference/sdk/auth/login) 获取供开发者服务端换票的一次性授权码。
+ * @see [user.revokeAuthorization](/reference/sdk/user/revokeAuthorization) 撤销当前小程序的用户授权。
  */
 export interface AuthorizedUserInfo {
   /**
-   * 当前黑盒用户在当前小程序内稳定且不可逆的关联标识。
+   * 当前用户在当前小程序与当前授权有效期内稳定的隔离标识；不是黑盒用户 ID 或登录凭据。
    *
    * @remarks
-   * 同一用户在不同小程序中的值不同。它不是黑盒用户 ID、登录凭据或主站私有接口凭据，
-   * 只应作为当前小程序自己的业务关联键使用。示例：
+   * 该值在当前授权有效期内可作为“当前用户 × 当前小程序”的稳定关联键；同一用户在不同
+   * 小程序中的值不同，授权撤销后旧值失效。它不是黑盒用户 ID、登录凭据或主站私有接口凭据。
+   * 示例：
    * `au_1_x7K9mQ2pL4vN8cR3tY6wB1zD5fH`。调用方必须把完整值视为不透明字符串，
-   * 不应解析格式或依赖固定长度。
+   * 不应解析格式、依赖固定长度或尝试跨小程序关联用户。
    */
   app_user_id: string;
-  /** `profile` 已授权时返回昵称与头像；当前 Heybox Runtime 在无网络模式下隐式授予该 scope。 */
-  profile: { nickname: string; avatar: string } | null;
+  /**
+   * `profile` 获准披露时返回公开资料：`nickname` 是展示昵称，`avatar` 是头像资源字符串；
+   * 未获准披露时为 `null`。
+   *
+   * @remarks
+   * 当前 Runtime 的静默读取会授予 `profile`；资料读取暂时失败时仍可能返回对象，但
+   * `nickname` 或 `avatar` 为空字符串。它们只适合展示，不应作为登录态、授权状态、
+   * 唯一用户标识或鉴权依据。
+   */
+  profile: {
+    /** 当前小黑盒账号的公开展示昵称；空字符串表示本次未取得可展示昵称。 */
+    nickname: string;
+    /** 当前小黑盒账号的公开头像资源字符串；空字符串表示本次未取得可展示头像。 */
+    avatar: string;
+  } | null;
+  /**
+   * `steam_account` 已授权且当前已绑定 Steam 时返回 canonical SteamID64。
+   *
+   * @remarks
+   * 始终表示为 string，禁止作为 JSON number 使用；未绑定时省略该字段，不返回空字符串或
+   * `null`。只返回主绑定 SteamID64，不包含 Steam 昵称、头像、好友码、公开状态或绑定来源。
+   */
+  steam_id?: string;
 }
 
 /**
  * 当前黑盒 APP 登录态、授权状态和已获准披露的用户资料。
  *
  * @remarks
- * 未登录时 `isHeyboxAppLoggedIn` 为 `false`，授权状态和用户资料均为 `null`。
- * 当前 Heybox Runtime 在无网络模式且已登录时会隐式授予 `identity` 与 `profile`，
- * 静默建立身份并返回 `userInfo`；Host 在已登录但身份暂不可用时仍可返回 `null`，
- * 调用方必须进行空值判断。
+ * 以 `isHeyboxAppLoggedIn` 作为判别字段处理返回值：
+ *
+ * - `false`：当前 Host 没有已登录的小黑盒账号，`authorization` 与 `userInfo` 固定为 `null`。
+ *   这是正常业务分支，不会抛出登录错误。
+ * - `true` 且 `userInfo` 非空：`authorization` 固定包含 `identity`、`profile` 两项状态；
+ *   `userInfo` 包含当前小程序隔离的 `app_user_id`，而 `profile` 仍需独立判空。
+ * - `true` 且 `userInfo` 为 `null`：公共协议为兼容 Host 保留的“已登录但资料未披露/不可用”分支。
+ *   当前 Runtime 成功读取隔离身份时返回非空对象，但调用方仍应按类型处理该分支。
+ *
+ * `user.getInfo()` 不返回 `code`、token、cookie 或黑盒用户 ID。需要建立开发者服务端会话时，
+ * 应在可信用户操作中调用 `auth.login()`，再把一次性 `code` 交给开发者自己的服务端。
+ *
+ * @see [auth.login](/reference/sdk/auth/login)
+ * @see [user.revokeAuthorization](/reference/sdk/user/revokeAuthorization)
  */
 export type MiniProgramUserInfoResult =
-  | { isHeyboxAppLoggedIn: false; authorization: null; userInfo: null }
-  | { isHeyboxAppLoggedIn: true; authorization: UserInfoAuthorization; userInfo: AuthorizedUserInfo | null };
+  | {
+      /** `false` 是未登录分支的稳定判别值。 */
+      isHeyboxAppLoggedIn: false;
+      /** 未登录时没有当前小程序的用户授权上下文。 */
+      authorization: null;
+      /** 未登录时不会披露隔离身份或公开资料。 */
+      userInfo: null;
+    }
+  | {
+      /** `true` 表示 Host 当前有已登录的小黑盒账号，不等同于开发者服务端已建立会话。 */
+      isHeyboxAppLoggedIn: true;
+      /** 当前小程序的用户授权状态；与 Manifest 权限声明是两层独立门禁。 */
+      authorization: UserInfoAuthorization;
+      /** 已获准披露的隔离身份与公开资料；兼容 Host 可能返回 `null`。 */
+      userInfo: AuthorizedUserInfo | null;
+    };
+/** `user.getInfo` 不接收入参，也不能由页面指定小程序或用户身份。 */
 export type GetUserInfoPayload = void;
+/** `user.getInfo` 的判别联合返回值；先判断 `isHeyboxAppLoggedIn`，再判断 `userInfo`。 */
 export type GetUserInfoResult = MiniProgramUserInfoResult;
+/**
+ * `user.revokeAuthorization` 不接受 wire payload。
+ *
+ * @remarks
+ * 小程序 ID、当前小黑盒用户和可信手势状态由 Host 注入；发送任何非 `undefined` payload
+ * 都会返回 `INVALID_PARAMS`。该 method 无需 Manifest 权限，但仍要求当前用户已登录且调用
+ * 来自可信用户操作。
+ *
+ * @see [App-facing user.revokeAuthorization](/reference/sdk/user/revokeAuthorization)
+ */
 export type RevokeAuthorizationPayload = void;
+/**
+ * 撤销成功后的 wire 结果为 `undefined`。
+ *
+ * @remarks
+ * 成功后 Runtime 会使缓存的用户授权和隔离身份失效，并发布
+ * `user_info_authorization_change`；业务持久化数据和开发者服务端会话不在该结果的清理范围内。
+ */
 export type RevokeAuthorizationResult = void;
+/**
+ * Steam 游戏库排序维度：`weeks` 按最近两周时长，`all` 按累计时长，`achieved` 按成就数。
+ */
 export type SteamGameListSort = 'weeks' | 'all' | 'achieved';
+/** `user.getSteamGameList` 的 wire 请求对象；字段校验和默认值由 Host Runtime 执行。 */
 interface GetSteamGameListRequest {
+  /** trim 后的非空 Steam ID；省略时使用当前用户的默认绑定账号。 */
   steamId?: string;
+  /** 正整数页大小，默认 `20`，大于 `100` 时收窄为 `100`。 */
   limit?: number;
+  /** 非负整数 offset，默认 `0`。 */
   offset?: number;
+  /** 排序维度，默认 `weeks`。 */
   sort?: SteamGameListSort;
+  /** trim 后最多保留前 100 个 UTF-16 code unit；空值会被省略。 */
   q?: string;
+  /** 是否包含隐藏游戏，默认 `false`；仅接受 boolean。 */
   includeHidden?: boolean;
 }
+/**
+ * `user.getSteamGameList` 的可选 wire payload；`undefined` 使用全部默认查询值。
+ *
+ * @remarks
+ * Host 会拒绝未知字段、数字字符串和用 `0` / `1` 代替 boolean 的值。该 method 要求
+ * `steamLibrary` 权限，但不要求公开 `network` 权限或可信用户手势。
+ *
+ * @see [App-facing user.getSteamGameList](/reference/sdk/user/getSteamGameList)
+ */
 export type GetSteamGameListPayload = GetSteamGameListRequest | undefined;
+/**
+ * Steam 游戏价格 wire 结果。所有字段都可省略，且协议不携带币种或最小货币单位。
+ */
 export type SteamGamePrice = {
+  /** 当前售价的非空展示文本。 */
   current?: string;
+  /** 原价的非空展示文本。 */
   initial?: string;
+  /** 服务端原始折扣数值；协议不承诺比例、百分比或取值范围。 */
   discount?: number;
+  /** 服务端最低价数值；币种和缩放单位不属于本协议。 */
   lowestPrice?: number;
+  /** 截止时间展示文本，不保证可解析为日期。 */
   deadlineDate?: string;
+  /** 服务端原始折扣截止时间数值；协议不承诺单位或时钟来源。 */
   deadlineTimestamp?: number;
 };
+/**
+ * 经过 Host Runtime 规范化的 Steam 游戏条目；无效必填字段会导致整条记录被移除。
+ */
 export interface SteamGameListItem {
+  /** 小黑盒游戏目录 ID。 */
   appid: number;
+  /** Steam App ID；缺失时由 Host 回退为 `appid`。 */
   steamAppid: number;
+  /** trim 后的非空名称。 */
   name: string;
+  /** 非空封面或主图 URL 字符串。 */
   image?: string;
+  /** 非空 Steam 图标 URL 字符串。 */
   icon?: string;
+  /** 服务端原始累计游玩时长数值；协议不承诺单位。 */
   playtimeForever?: number;
+  /** 服务端原始最近游玩时长数值；协议不承诺单位。 */
   playtime2Weeks?: number;
+  /** 非空标签列表；没有有效标签时省略。 */
   tags?: string[];
+  /** 至少有一个可用价格字段时存在。 */
   price?: SteamGamePrice;
 }
+/** Steam 游戏库的 offset 分页结果。 */
 export interface SteamGameListData {
+  /** 当前页通过规范化校验的游戏条目。 */
   gameList: SteamGameListItem[];
+  /** 服务端游戏总数；缺失或无效时省略。 */
   total?: number;
+  /** 有 `total` 时按 `nextOffset < total` 计算，否则按本页是否达到有效 `limit` 推断。 */
   hasMore: boolean;
+  /** `请求 offset + gameList.length`；下一页应直接复用该值。 */
   nextOffset: number;
+  /** 服务端对结果是否属于当前用户本人的标记；不可识别时省略。 */
   isMe?: boolean;
 }
+/**
+ * `user.getSteamGameList` 的判别联合结果。
+ *
+ * @remarks
+ * - `isLogin: false`：未登录，`isBound` 固定为 `false`，`data` 固定为 `null`。
+ * - `isLogin: true, isBound: false`：已登录但未绑定 Steam，`data` 固定为 `null`。
+ * - 两者均为 `true`：`data` 固定为 {@link SteamGameListData}，其中 `gameList` 可以为空。
+ */
 export type GetSteamGameListResult =
   | { isLogin: false; isBound: false; data: null }
   | { isLogin: true; isBound: false; data: null }
   | { isLogin: true; isBound: true; data: SteamGameListData };
 
+/** 公开分享渠道；Host 可以只支持其中一部分，值区分大小写。 */
 export type MiniProgramShareChannel = 'wechatSession' | 'wechatTimeline' | 'qqFriend' | 'qzone' | 'weibo';
+/** 社区发帖页的可编辑分区与话题预置。 */
 export interface MiniProgramSharePostOptions {
+  /** 正安全整数或 trim 后非空字符串；Runtime 转为字符串并去重。 */
   topicIds?: (string | number)[];
+  /** trim 后非空且不以 `#` 开头或结尾的字符串；Runtime 去重。 */
   topics?: string[];
 }
 export interface MiniProgramScreenshotRect {
@@ -113,14 +271,31 @@ export interface MiniProgramScreenshotRect {
   width: number;
   height: number;
 }
+/**
+ * `share.showShareMenu` 的 wire payload；落地页由 Runtime 固定生成，不接受 `url` 字段。
+ */
 export type ShowShareMenuPayload = {
+  /** trim 后必须非空；原字符串会交给 Host。 */
   title: string;
+  /** trim 后必须非空；原字符串会交给 Host。 */
   desc: string;
+  /** 经 Runtime 校验并编码到固定分享 URL 的 JSON-compatible 状态。 */
   extra?: unknown;
+  /** 可解析的绝对 HTTP(S) 缩略图 URL。 */
   imageUrl?: string;
+  /** 可选站外渠道；不能与有效社区 `post` 同时使用。 */
   channel?: MiniProgramShareChannel;
+  /**
+   * 可编辑社区预置；`null` 等同省略。普通分享最多保留一个分区，开发态严格拒绝无效项，
+   * 生产态过滤无效项并在与 `channel` 冲突时省略 `post`。
+   */
   post?: MiniProgramSharePostOptions | null;
 };
+/**
+ * Host 分享面板返回的不透明值。
+ *
+ * @remarks 可能是 `undefined` 或任意对象；不能依赖结构或真假值判断用户分享结果。
+ */
 export type ShowShareMenuResult = unknown;
 export type CopyLinkPayload = { extra?: unknown } | undefined;
 export type CopyLinkResult = string;
@@ -413,29 +588,96 @@ export interface SetClipboardPayload {
 }
 export type SetClipboardResult = void;
 
+/**
+ * `navigation.close` 的无参 wire payload。
+ *
+ * @remarks
+ * App-facing API 发送 `undefined`。Host Runtime 为兼容协议也接受空普通对象，但非空对象、
+ * 数组或其他值会返回 `INVALID_PARAMS`；payload 不能携带强制关闭、原因或窗口标识。
+ *
+ * @see [App-facing navigation.close](/reference/sdk/navigation/close)
+ */
 export type ClosePayload = void;
+/**
+ * Host 接受关闭请求后的 wire 结果为 `undefined`。
+ *
+ * @remarks
+ * 该结果不保证 iframe 在响应抵达后继续存活，也不包含最终关闭状态。Host 销毁环境时会尽力
+ * 派发 `unload`；关键持久化不能依赖 Promise 后续语句或 `unload` 回调。
+ */
 export type CloseResult = void;
+/**
+ * `navigation.reload` 的无参 wire payload。
+ *
+ * @remarks
+ * App-facing API 发送 `undefined`。Host Runtime 为兼容协议也接受空普通对象，但非空对象、
+ * 数组或其他值会返回 `INVALID_PARAMS`；payload 不能指定缓存策略、目标 URL 或 reload 模式。
+ *
+ * @see [App-facing navigation.reload](/reference/sdk/navigation/reload)
+ */
 export type ReloadPayload = void;
+/**
+ * Host 接受 reload 请求后的 wire 结果为 `undefined`。
+ *
+ * @remarks
+ * 该结果不包含新页面加载状态或新 SDK 实例。旧页面内存、监听和 pending 请求不会跨 reload
+ * 保留；关键持久化不能依赖 Promise 后续语句或 `unload` 回调。
+ */
 export type ReloadResult = void;
+/** 允许打开的 App 页面目标白名单；不包含任意 URL、scheme 或内部路由。 */
 export type MiniProgramAppPageTarget = 'game_detail' | 'user_detail' | 'post_detail';
+/** 游戏平台类型：PC、主机或移动游戏。 */
 export type MiniProgramGameDetailGameType = 'pc' | 'console' | 'mobile';
+/** 游戏详情首屏：详情主页或百科页。 */
 export type MiniProgramGameDetailPage = 'game' | 'wiki';
+/** 打开游戏详情页的规范化 wire payload。 */
 export type OpenGameDetailAppPagePayload = {
+  /** 固定判别值。 */
   target: 'game_detail';
+  /** trim 后的非空游戏 app ID 字符串。 */
   appId: string;
+  /** 只允许 `pc`、`console`、`mobile`。 */
   gameType: MiniProgramGameDetailGameType;
+  /** 可选首屏，只允许 `game` 或 `wiki`。 */
   page?: MiniProgramGameDetailPage;
+  /** trim 后的非空来源标识。 */
   hSrc?: string;
+  /** trim 后的非空 SKU ID 字符串。 */
   skuId?: string;
 };
-export type OpenUserDetailAppPagePayload = { target: 'user_detail'; userId: string };
+/** 打开用户详情页的规范化 wire payload。 */
+export type OpenUserDetailAppPagePayload = {
+  /** 固定判别值。 */
+  target: 'user_detail';
+  /** trim 后的非空 `heybox_id` 字符串。 */
+  userId: string;
+};
+/** 打开帖子详情页的规范化 wire payload。 */
 export type OpenPostDetailAppPagePayload = {
+  /** 固定判别值。 */
   target: 'post_detail';
+  /** trim 后的非空帖子 ID 字符串。 */
   linkId: string;
+  /** 可选的非空根评论 ID 字符串。 */
   rootCommentId?: string;
+  /** 可选的非空目标评论 ID 字符串。 */
   commentId?: string;
 };
+/**
+ * `navigation.openAppPage` 的判别联合 wire payload。
+ *
+ * @remarks
+ * Runtime 只读取上述白名单字段并构造固定 Host 路由；额外 URL、path、scheme 或窗口字段
+ * 不会透传。移动端 Host 支持三个目标，当前 PC Host 只支持 `game_detail` 且只消费 `appId`。
+ *
+ * @see [App-facing navigation.openAppPage](/reference/sdk/navigation/openAppPage)
+ */
 export type OpenAppPagePayload = OpenGameDetailAppPagePayload | OpenUserDetailAppPagePayload | OpenPostDetailAppPagePayload;
+/**
+ * Host 接收参数并发起受控路由后的结果为 `undefined`。
+ *
+ * @remarks 不表示目标页加载完成，也不返回目标页数据、关闭结果或回调值。
+ */
 export type OpenAppPageResult = void;
 
 export type LeaderboardOrder = 'asc' | 'desc';
@@ -483,9 +725,38 @@ export interface GetLeaderboardInfoResult {
   rankLimit: number;
 }
 
-/** 受管桌面程序可选能力。 */
+/**
+ * 当前 Companion 产物声明并由 Host 确认的可选能力。
+ *
+ * @remarks
+ * - `stdio`：启动后的 Session 可以读写原始 stdin/stdout/stderr 字节流。
+ * - `attachments`：Session 可以按 opaque ID 打开 Host 衰减为只读的受控附件。
+ * - `notifications`：Session 可以请求 Host 展示固定类别的系统通知。
+ *
+ * 能力出现在 {@link CompanionInfo.capabilities} 只描述当前产物合同，不表示已经准备完成、
+ * 已经启动或当前 Host 一定能成功执行每次操作。启动后仍应按 `CompanionSession` 对应可选
+ * 属性是否存在进行分支。
+ */
 export type CompanionCapability = 'stdio' | 'attachments' | 'notifications';
+
+/**
+ * 当前 Host 为 Companion 选择的目标制品。
+ *
+ * @remarks
+ * V1 仅支持 Windows x64 与 macOS arm64。该值是当前运行 Host 选中的一个 target，不是
+ * Manifest 声明的全部 target 列表；当前平台没有匹配制品时 `companion.getInfo()` 会拒绝，
+ * 不会返回猜测值。
+ */
 export type CompanionTarget = 'windows-x64' | 'macos-arm64';
+
+/**
+ * Host 对当前 Companion 制品给出的签名检查状态。
+ *
+ * @remarks
+ * `unsigned` 表示未签名，`valid` 表示 Host 已确认签名有效，`invalid` 表示签名校验失败，
+ * `unknown` 表示 Host 尚不能确认。该字段用于展示和诊断，不会替代准备完整性校验、Host
+ * 授权或操作系统安全策略；本地开发制品可以是 `unsigned`。
+ */
 export type CompanionSignatureStatus = 'unsigned' | 'valid' | 'invalid' | 'unknown';
 
 /** Companion alias 的跨构建、Runtime 与 Host 规范。 */
@@ -520,36 +791,185 @@ export const COMPANION_ERROR_CODES = [
 ] as const;
 export type CompanionErrorCode = (typeof COMPANION_ERROR_CODES)[number];
 
+/**
+ * Host 针对当前小程序版本与当前平台确认的 Companion 描述快照。
+ *
+ * @remarks
+ * Runtime 会校验字段、去重并冻结 `capabilities`，再返回冻结对象；页面不应修改或缓存为
+ * 跨版本事实。该结构刻意不包含准备 `state`、进度、`preparedAt`、Session ID、PID、物理
+ * 路径、下载 URL、SHA-256、entrypoint 或单独的 Companion 版本号。
+ *
+ * 准备状态通过 `companion.getPreparationStatus()` 查询。Companion 随当前小程序审核版本、
+ * 精确预览版本或本地开发快照绑定；`source` 只说明来源类别，不提供版本号，也不能用于
+ * 比较版本新旧。
+ *
+ * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/sdk/companion/getInfo.html | companion.getInfo}
+ * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/sdk/companion/getPreparationStatus.html | companion.getPreparationStatus}
+ */
 export interface CompanionInfo {
+  /**
+   * 规范 alias；必须与请求值及 `package.json#heybox.companions` 中的 key 完全一致。
+   */
   alias: string;
+  /**
+   * Host 确认的用户可见名称，只用于展示；不要把它当作稳定标识、文件名或版本号。
+   */
   displayName: string;
+  /** 当前 Host 选中的目标制品；不是项目声明的全部 target。 */
   target: CompanionTarget;
+  /**
+   * 当前产物声明且 Host 确认的去重能力列表；可能为空，不代表产物已准备或已启动。
+   */
   capabilities: readonly CompanionCapability[];
+  /** 当前压缩归档大小，单位字节；是大于等于 `0` 的安全整数，不是解压后磁盘占用。 */
   archiveBytes: number;
+  /** Host 对当前制品给出的签名检查状态；不能替代完整性校验或系统安全判断。 */
   signatureStatus: CompanionSignatureStatus;
-  /** Host 确认的产物来源；旧 Host 缺省时来源未知。 */
+  /**
+   * Host 确认的产物来源。
+   *
+   * @remarks
+   * `local-dev` 是当前 `hb-sdk dev` 绑定的本地快照；`preview` 是精确审核前预览版本；
+   * `released` 是已发布版本。旧 Host 缺省时为 `undefined`，只表示来源未知，不应回退为
+   * `released`。不要根据 alias、displayName、签名状态或页面 URL 自行推断来源。
+   */
   source?: 'local-dev' | 'preview' | 'released';
 }
 
+/**
+ * Host 最近一次 Companion 准备失败的公开摘要。
+ *
+ * @remarks
+ * Runtime 只保留稳定领域错误码、规范化文案和重试建议；原生路径、下载地址、堆栈和其他
+ * Host 诊断信息不会下发。该摘要描述最近一次准备，不代表当前正在自动重试。
+ */
 export interface CompanionErrorSummary {
+  /** 稳定的 Companion 领域错误码；业务分支应比较该字段，不要比较 `message`。 */
   code: CompanionErrorCode;
+  /** Runtime 根据错误码生成的安全展示文案；不承诺保留 Host 原始 message。 */
   message: string;
+  /**
+   * Host 对“以新的可信用户操作再次调用 `prepare()` 是否可能成功”的建议。
+   *
+   * `true` 不会触发自动重试，也不绕过权限、授权、完整性或手势要求；调用方仍应采用
+   * 有界重试。`false` 表示不应原样循环重试，通常需要修改产物、配置或环境。
+   */
   retryable: boolean;
 }
 
+/**
+ * Host 持有的 Companion 准备操作的最近进度快照。
+ *
+ * @remarks
+ * 三个阶段的计数都是非负安全整数。Runtime 只保证同一进度对象内当前值不大于已知总量，
+ * 不定义 verifying/extracting 与下载字节之间的换算，也不保证不同阶段的 total 相同；进度
+ * 只能用于展示当前阶段，不能作为归档完整性证据。
+ */
 export type CompanionPrepareProgress =
-  | { phase: 'downloading'; loaded: number; total?: number }
-  | { phase: 'verifying'; processed: number; total: number }
-  | { phase: 'extracting'; processed: number; total: number };
+  | {
+      /** 下载阶段判别值。 */
+      phase: 'downloading';
+      /** Host 已下载的非负安全整数计数。 */
+      loaded: number;
+      /** Host 已知总量；未知时省略，存在时为不小于 `loaded` 的非负安全整数。 */
+      total?: number;
+    }
+  | {
+      /** 校验阶段判别值。 */
+      phase: 'verifying';
+      /** Host 已校验的非负安全整数计数，且不大于 `total`。 */
+      processed: number;
+      /** 当前校验阶段的非负安全整数总量。 */
+      total: number;
+    }
+  | {
+      /** 解压阶段判别值。 */
+      phase: 'extracting';
+      /** Host 已处理的非负安全整数计数，且不大于 `total`。 */
+      processed: number;
+      /** 当前解压阶段的非负安全整数总量。 */
+      total: number;
+    };
 
+/**
+ * 当前小程序版本、当前平台与指定 alias 对应的 Host 准备状态快照。
+ *
+ * @remarks
+ * 这是以 `state` 为判别字段的四态联合，Runtime 会冻结返回对象及嵌套的 `progress` 或
+ * `error`。它描述 Host 持久状态，不等同于某个页面中 `prepare()` Promise 的状态，也不会
+ * 随后台操作自动变化；需要最新值时重新调用 `companion.getPreparationStatus()`。
+ *
+ * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/sdk/companion/getPreparationStatus.html | companion.getPreparationStatus}
+ */
 export type CompanionPreparationStatus =
-  | { state: 'not-prepared' }
-  | { state: 'preparing'; progress: CompanionPrepareProgress }
-  | { state: 'ready'; preparedAt: number }
-  | { state: 'failed'; error: CompanionErrorSummary };
+  | {
+      /** 当前版本与 target 尚无已原子提交的本地产物，也没有在途准备。 */
+      state: 'not-prepared';
+    }
+  | {
+      /** Host 正在下载、校验或解压；页面 reload 或隐藏不会自动取消该操作。 */
+      state: 'preparing';
+      /** 查询时 Host 保存的最近进度；这是快照，不是持续订阅。 */
+      progress: CompanionPrepareProgress;
+    }
+  | {
+      /** 当前版本产物已原子提交，可以由新的可信用户操作调用 `launch()`。 */
+      state: 'ready';
+      /**
+       * Host 提供的非负安全整数准备完成时间戳。
+       *
+       * 协议不公开时钟来源、时区或过期语义；只适合展示和诊断，不应用于授权、版本比较
+       * 或判断产物仍然有效。
+       */
+      preparedAt: number;
+    }
+  | {
+      /** 最近一次准备已失败，当前没有可由该状态直接启动的新产物。 */
+      state: 'failed';
+      /** 经过 Runtime 脱敏和规范化的失败摘要。 */
+      error: CompanionErrorSummary;
+    };
 
+/**
+ * Host 归一化后的 Companion 进程终止原因。
+ *
+ * @remarks
+ * - `exited`：进程自行退出并提供 exit code；不表示 code 必然为 `0`。
+ * - `terminated`：Host 报告进程已被显式终止。
+ * - `crashed`：Host 把终态归类为异常崩溃。
+ * - `host-shutdown`：Host 或其进程监管环境关闭。
+ * - `permission-revoked`：Companion 权限撤销导致 Session 终止。
+ * - `output-limit`：Host 的输出上限导致 Session 终止。
+ *
+ * 该枚举描述 Host 确认的终态，不包含 controller ownership 转移；后者不会结束进程。
+ */
 export type CompanionExitReason = 'exited' | 'terminated' | 'crashed' | 'host-shutdown' | 'permission-revoked' | 'output-limit';
-export type CompanionExit = { reason: 'exited'; exitCode: number } | { reason: Exclude<CompanionExitReason, 'exited'>; exitCode?: number };
+
+/**
+ * Companion Session 的一次性退出结果。
+ *
+ * @remarks
+ * 这是以 `reason` 判别的只读语义结果。Runtime 只接受上方固定 reason，并要求所有出现的
+ * `exitCode` 都是 safe integer；非法 Host 事件会被丢弃，不会进入 SDK Session。
+ * `reason: 'exited'` 必须携带 `exitCode`，其余 Host 终止原因可携带或省略。exit code 的正负、
+ * 具体编号和成功含义由 Companion 与目标操作系统决定，SDK 不把它转换为 HTTP 状态、信号或错误码。
+ *
+ * @see [CompanionSession.waitForExit()](/reference/symbols/root/interfaces/CompanionSession#waitforexit)
+ * @see [CompanionSession.onExit()](/reference/symbols/root/interfaces/CompanionSession#onexit)
+ */
+export type CompanionExit =
+  | {
+      /** 进程自行退出；该分支始终提供一个 safe-integer `exitCode`。 */
+      reason: 'exited';
+      /** Companion / 操作系统提供的进程退出码；调用方应按自己的进程合同解释。 */
+      exitCode: number;
+    }
+  | {
+      /** Host 确认的非普通退出原因；不会取值 `exited`。 */
+      reason: Exclude<CompanionExitReason, 'exited'>;
+      /** Host 可提供的 safe-integer 进程退出码；缺失时不要自行填充 `0` 或其他哨兵值。 */
+      exitCode?: number;
+    };
 
 /** 活动 Session 的 wire 快照；不包含路径、PID 或原生句柄。 */
 export interface CompanionSessionSnapshot {