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

package/types/payloads.d.ts

@@ -12,44 +12,81 @@ export interface LoginResult {
     expiresIn: number;
     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';
 /**
  * 当前小程序对 canonical 用户信息 scope 的授权状态。
  *
  * @remarks
- * `steam_account` 是可选键：新能力版本的 Runtime 必定返回，legacy Runtime/Version 可以
- * 缺失。已授权不代表当前一定已绑定 Steam，只有 {@link AuthorizedUserInfo.steam_id}
- * 存在才表示当前有主绑定。
+ * 该对象固定包含 `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` 是展示昵称，`avatar` 是头像资源字符串；
+     * 未获准披露时为 `null`。
+     *
+     * @remarks
+     * 当前 Runtime 的静默读取会授予 `profile`；资料读取暂时失败时仍可能返回对象，但
+     * `nickname` 或 `avatar` 为空字符串。它们只适合展示，不应作为登录态、授权状态、
+     * 唯一用户标识或鉴权依据。
+     */
     profile: {
+        /** 当前小黑盒账号的公开展示昵称；空字符串表示本次未取得可展示昵称。 */
         nickname: string;
+        /** 当前小黑盒账号的公开头像资源字符串；空字符串表示本次未取得可展示头像。 */
         avatar: string;
     } | null;
     /**
@@ -65,60 +102,149 @@ export interface AuthorizedUserInfo {
  * 当前黑盒 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 = {
+    /** `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;
@@ -132,9 +258,13 @@ export type GetSteamGameListResult = {
     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 {
@@ -143,14 +273,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;
@@ -407,32 +554,96 @@ export interface SetClipboardPayload {
     text: string;
 }
 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;
 };
+/** 打开用户详情页的规范化 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';
 export interface LeaderboardEntry {
@@ -478,61 +689,205 @@ export interface GetLeaderboardInfoResult {
     order: LeaderboardOrder;
     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 规范。 */
 export declare const COMPANION_ALIAS_PATTERN: RegExp;
 /** Companion Host 可跨 bridge 保留的稳定领域错误码。 */
 export declare const COMPANION_ERROR_CODES: readonly ["COMPANION_UNSUPPORTED", "COMPANION_PREVIEW_UNSUPPORTED", "COMPANION_NOT_DECLARED", "COMPANION_TARGET_UNSUPPORTED", "COMPANION_NOT_PREPARED", "COMPANION_PREPARATION_CANCELLED", "COMPANION_DOWNLOAD_FAILED", "COMPANION_DESCRIPTOR_UNAVAILABLE", "COMPANION_ARCHIVE_INVALID", "COMPANION_INTEGRITY_FAILED", "COMPANION_ENTRYPOINT_INVALID", "COMPANION_USER_CANCELLED", "COMPANION_ELEVATION_DENIED", "COMPANION_OS_BLOCKED", "COMPANION_LAUNCH_FAILED", "COMPANION_SESSION_VERSION_MISMATCH", "COMPANION_SESSION_OWNERSHIP_LOST", "COMPANION_SESSION_EXITED", "COMPANION_PIPE_CLOSED", "COMPANION_OUTPUT_LIMIT", "COMPANION_PROCESS_CRASHED", "COMPANION_ATTACHMENT_NOT_FOUND", "COMPANION_NOTIFICATION_UNAVAILABLE", "COMPANION_TERMINATE_FAILED"];
 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';
+    /** 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 = {
+    /** 当前版本与 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';
+/**
+ * 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 或原生句柄。 */