openxiangda-skill-kit 2.3.16 → 2.3.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.3.16",
+  "version": "2.3.18",
   "description": "OpenXiangda 2.0 中文 AI 技能的校验、分发与安装。",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
     "README.md"
   ],
   "dependencies": {
-    "openxiangda-devkit-core": "2.22.0"
+    "openxiangda-devkit-core": "2.24.0"
   },
   "devDependencies": {
     "tsx": "4.23.12",

package/skills/openxiangda-v2/references/backend.md

@@ -41,6 +41,15 @@ SDK 继承当前环境与身份，平台沿用发起人或既有超级管理员
 `items/nextCursor`，分页与多次流程的选择规则见[前端](frontend.md)。找回后使用原
 `receipt/poll/surface`；查询不重放提交、不生成第二份命令状态。
 
+连 commandId 都没收到时，用同一动作的 `businessProcess.resolveOriginal({ workflowCode,
+ idempotencyKey })` 查询原操作。此能力需要 `business-process.original-resolution` 1.0.0。
+`committed` 才有可信回执；`not_observed` 可能仍在提交，不能据此生成新键或宣称回滚。
+前端可用 `resolveBusinessProcessOriginal`（`openxiangda/react`），传原 workflowCode、
+operationCode、idempotencyKey；SDK 绑定当前环境并核验返回关联。Named Action 如果业务无需
+审批，没有流程回执并不代表业务没写入，应沿该动作自身回执诊断。
+标准 PC/移动发起页在响应未知时保留原操作定位信息，刷新可继续查询；同一页面、原身份和
+版本内可手动重试冻结的标准输入，绝不自动重发或悄悄换键。
+
 自定义表单页若先用 `createResourceFormDraftClient` 保存认证草稿，并由 Named Action
 提交业务记录和流程，则在同一次 `OpenXiangdaBusinessProcessService.commit` 中传入
 `formDraft: { resourceCode, id, expectedRevision, mode, recordId?, viewCode? }`。草稿必须
@@ -101,21 +110,28 @@ data: {
 
 ### 幂等冲突复核 {#idempotency-recovery}
 
-同一 `idempotencyKey` 要求内容指纹一致。update 事务携带 `expectedRevision`，重试时 revision 已前进会触发 409 `OPENXIANGDA_NATIVE_DATA_IDEMPOTENCY_CONFLICT`。捕获后回读当前状态确认效果已生效，按幂等结果返回；不要换新键重试：
+同一 `idempotencyKey` 要求内容指纹一致。冻结首次请求的 operations、guards、expectedRevision、主体、环境和版本上下文；重试不能重新计算这些值。平台原回执的 `replayed` 才是重放成功证据。业务记录已经变化，本身不会导致原请求的幂等内容冲突；重新读取 revision 并改变请求才会。
+
+`isIdempotencyConflict(error)` 只识别 409 `OPENXIANGDA_NATIVE_DATA_IDEMPOTENCY_CONFLICT`，不证明首次请求已成功。保留原操作并核对原回执；结果不明时显示“结果待确认”，不能把当前记录状态拼成伪造的成功回执，也不能换新键重试。部署 Head 改变时先恢复原上下文，不把同一键发送到另一版本当作原请求恢复。
+
+### 使用生成类型绑定资源 {#typed-resources}
+
+工具生成的共享契约导出 `ResourceTypes`；使用项目锁定版本的 `pnpm openxiangda check` 验证接入。三种 Nest 数据服务均保留原主体；当前用户业务优先用当前用户服务，具名业务动作使用业务服务。
 
 ```ts
-import { isIdempotencyConflict } from 'openxiangda/nest';
-
-try {
-  result = await this.data.transaction(idempotentTransaction(key, operations, guards));
-} catch (error) {
-  if (isIdempotencyConflict(error) && alreadyApplied(await this.data.get(...))) {
-    return { idempotencyKey: key, replayed: true, ...currentState };
-  }
-  throw error;
-}
+import type { ResourceTypes } from '@app/contracts';
+
+const resources = this.data.resources<ResourceTypes>();
+const requests = resources('repair-requests');
+const record = await requests.get(input.id);
+return requests.update(record.data.id, {
+  expectedRevision: record.data.revision,
+  data: { assignedTechnician: userSnapshot(input.technicianId) },
+});
 ```
 
+资源名、写入字段、引用形状和 query 的字段/排序键会在 TypeScript 检查时验证；示例字段须由自己的模型声明。get/create/update/delete 保留 `data` 信封，revision 位于 `record.data.revision`。query 返回分页的 `items`。字段权限可能隐藏业务字段，所以读取类型保留这些字段可缺失的事实；应用必须按权限和必需字段做有意义的提示。该包装不会自动重试、修改 revision 或提升权限。运行时仍由平台校验所有输入。
+
 事务守卫的 `errorCode` 必须匹配 `^OPENXIANGDA_[A-Z0-9_]{1,96}$`，例如 `OPENXIANGDA_REPAIR_REQUEST_NOT_PENDING`。
 
 ## 在同一事务中引用前序 create 生成的 id {#transaction-references}
@@ -161,8 +177,21 @@ platformAccess: { roleAssertions: { roleCodes: ['technician'] } }
 ```
 
 `technician` 必须存在于本应用 `authz.roles`，最多声明 20 个角色。应用管理员身份
-不自动代表维修角色。人员候选可以使用已有且已委托管理范围的成员查询；这项声明
-本身不授予成员管理或人员目录权限。
+不自动代表维修角色。经办人使用请求作用域 `OpenXiangdaBusinessDirectoryService` 查询
+本动作声明的候选，无需成员管理权：
+
+```ts
+const page = await businessDirectory.assignmentCandidates({
+  roleCode: 'technician', keyword: input.keyword, limit: 20,
+  ...(input.cursor ? { cursor: input.cursor } : {}),
+});
+// page.items 仅有 value/label；下一页沿用同一关键词和 page.nextCursor。
+```
+
+这项可选能力需要目标平台 `directory.assignment-candidates` 1.0.0。环境由 SDK 绑定，
+禁止传入任意环境或账号。平台只返回生效、未过期、正常且未锁定的成员，验证账号与正式
+账号隔离。游标绑定环境 Head、调用者、动作和角色，收到上下文变化错误后清空游标重新查询。
+候选结果只用于选人；提交时仍使用下面的事务条件，不能凭查询结果绕过重新核验。
 
 在 `OpenXiangdaBusinessDataApiService` 的同一次事务中表达业务状态与目标角色：
 

package/skills/openxiangda-v2/references/testing.md

@@ -64,6 +64,21 @@ pnpm openxiangda accept --plan .openxiangda/acceptance-plan.json --json
 
 记录源码/包版本、AppVersion、环境、角色、预期及实际结果、必要请求标识。区分本地检查、分发安装、部署激活与业务验收。某项未执行时说明原因，不将其写成通过。
 
+## 复制请求诊断 {#request-diagnostics}
+
+标准浏览器请求错误保留服务端 requestId，文件导出及权限读取重试耗尽也使用同一错误类型。自定义页面通过公开入口读取固定格式诊断：
+
+```ts
+import { platformRequestDiagnostic } from 'openxiangda/react';
+
+function supportDetails(error: unknown) {
+  const diagnostic = platformRequestDiagnostic(error);
+  return diagnostic ? JSON.stringify(diagnostic, null, 2) : null;
+}
+```
+
+将这段结果放入当前操作的错误详情，附应用版本和原 operationId/DeploymentRun；不要复制 Cookie、令牌、完整请求正文或原始响应。诊断包含错误码、请求路径（无 query）、方法、站点内应用/环境、观测时间和合法 requestId。网络未收到响应时 requestId 为 null，不能编造关联标识。该信息不等于提交结果：写入未知时查询原操作，保留原键与原输入；不要自动换键再写。Nest SDK 的平台错误已有 `request` 上下文，平台管理仍通过授权范围内的日志/支持通道检索。
+
 ## 并发执行
 
 同一工作区的公共 check 和测试 deploy 共享本地互斥锁，前一个命令结束后才能启动下一个。出现 WORKSPACE_OPERATION_BUSY 时等待当前进程完成；异常退出时先确认锁中进程已经退出，再移除提示中的锁文件。锁只保护工具执行，不阻止编辑器修改源码；检查和部署期间应暂停其他写入。平台部署状态仍以 status/logs 为准。

package/skills/openxiangda-v2/references/upgrading.md

@@ -20,6 +20,18 @@
 
 ## 更新项目 {#upgrade}
 
+按实际启用的功能核对要求，不把浏览器文案、局部错误提示等更新当成平台升级理由：
+
+| 变化 | 平台条件 | 应用验证 |
+| --- | --- | --- |
+| ResourceTypes 和 Nest 类型绑定 | 复用现有 Data API；不新增服务端模型协议 | 运行生成与类型检查，确认隐藏字段可缺失及 revision 来源 |
+| 浏览器安全诊断、安装错误提示 | 复用现有响应及请求头 | 模拟只读失败、导出失败、网络中断，确认没有重复写入 |
+| 原流程提交结果恢复 | 可选 `business-process.original-resolution` 1.0.0 | 原幂等键查询、刷新恢复、授权拒绝，未知不能转换为未提交 |
+| 业务角色候选 | 可选 `directory.assignment-candidates` 1.0.0 | 当前动作声明的角色、目标环境、过期/锁定账号、提交再校验 |
+| 预检一次汇总 | 已协商的 configuration-compatibility 与共享 validator 摘要一致 | 同时缺能力/密钥/登录提供方时一次报告；成功结果仍按闭合协议校验 |
+
+平台能力声明、共享校验摘要、根包精确依赖及发布说明共同构成兼容依据。版本号大小、某次 Pod Ready 或历史工单“已发布”不能替代当前目标能力读回。未启用新增可选能力的旧应用继续使用原协议；不承诺未经回归验证的任意旧版本组合。
+
 更新项目的精确根包依赖并安装，提交相应锁文件；不要使用 latest、alpha 或范围版本代替明确版本。运行统一 check，处理实际契约变化，再在测试环境验证后晋级。
 
 执行 `pnpm openxiangda skill install --workspace . --force`，通过新版本根包安装 Skill；已有项目使用项目安装模式时会刷新 AGENTS 的平台管理段，并保留管理段外的自定义说明。没有可识别管理段的旧 AGENTS 不会被整份替换；先审阅工具输出的候选内容，再合并需要的规则。