openxiangda-skill-kit 2.3.89 → 2.3.92

package/package.json

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

package/skills/openxiangda-v2/SKILL.md

@@ -77,6 +77,7 @@ pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ skill install --force
 | 热点读取、抢票、排队、名额预占与原结果恢复 | [缓存、排队与配额](references/managed-concurrency.md) |
 | 报名按钮、表单排队、短确认页、预占倒计时与前端恢复 | [并发前端接入](references/managed-concurrency-frontend.md)：按六种形式选择；仅使用已导出的 API，区分待实现封装 |
 | 管理成员或查看有效流程参数 | [应用管理](references/administration.md) |
+| 高水位/死信、正式环境缺密钥、通知未发送或收件人错误 | [AI 应用自助操作](references/application-operations.md)；先读 `admin operations --json` 或 MCP `application_operations`，在已有授权范围内直接执行，沿用当前平台账号，无需人工打开管理页 |
 | 检查、部署、生产发布与故障恢复 | [验收](references/testing.md)、[交付](references/delivery.md) |
 | 需求记录与版本升级 | [全流程记录](references/appspec.md)、[升级](references/upgrading.md) |
 | 选择 CLI/MCP 操作 | [命令](references/cli.md)、[MCP](references/mcp.md) |

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

@@ -1,5 +1,8 @@
 # 应用管理与有效配置
 
+事件高水位、正式环境缺凭据或消息未发送时，开发者AI直接读取[应用自助操作](application-operations.md)
+并使用 `admin operations` / MCP `application_operations` 发现和执行已有管理能力，无需人工管理页面。
+
 平台的应用管理控制台维护应用成员、角色授权和流程运行参数。应用自身声明的 `/admin` 业务菜单展示业务页面，两者职责不同。可见入口和可执行操作以当前用户与目标环境返回结果为准。
 
 角色成员的范围维度也支持模型字段的 `userCandidates.scope` 引用，不要求为审批人职责增加无关的数据读写策略。目录 `scopeDimensions[].applicability.candidateFields` 返回字段所在的资源、数据修订、字段、角色与操作；当前环境及仍在办理的历史流程所引用的字段均可贡献范围适用性。实例完成或发起命令取消后，旧字段不再单独贡献适用性。配置成员的范围不会自动授予数据读写、菜单或应用管理权限；实际选人与提交仍核验范围、操作、成员有效期及账号状态。

package/skills/openxiangda-v2/references/application-operations.md

@@ -0,0 +1,150 @@
+# AI 应用运行自助操作
+
+开发者 AI 使用当前平台账号和工作区绑定直接完成事件、环境凭据和消息中心维护。
+用户已授权的诊断及修复无需再让用户点击管理页面。平台仍核验已有应用管理权限；
+首次账号登录沿用原认证流程，开发者身份不自动获得管理员权限。
+
+## 发现和执行 {#discovery}
+
+```bash
+pnpm openxiangda context --json
+pnpm openxiangda admin context --environment production --json
+pnpm openxiangda admin operations --json
+pnpm openxiangda docs application-operations
+printf '%s' '{}' | pnpm openxiangda admin execute events.status --environment production --input - --json
+```
+
+`admin operations` 读取本地目录，每项给出 `operation/inputSchema/effect/permission/recovery`。
+`admin execute <operation> --environment <test|production> --input <file|-> --json` 直接执行。
+输入文件或标准输入只放目录中的 **input** 对象，最多32KiB，不放密码。
+执行必须明确环境；test映射平台preproduction。应用、站点和身份来自当前工作区及会话，
+拒绝任意路径、自报appCode、tenantId、actor和environmentKey。
+
+MCP先调用 `application_operations`，再调用 `application_operation`：
+
+```json
+{"operation":"events.status","environment":"production","input":{}}
+```
+
+CLI与MCP共用输入Schema、服务和平台错误。成功结果在 `data.result`，环境在 `data.environment`。
+配置与恢复在已授权范围内直接执行；health访问外部健康接口并保存元信息。
+操作目录不证明远端接口已部署或当前用户有权，执行结果由平台决定。
+
+## 事件高水位与指定恢复 {#events}
+
+遇到 `EVENT_V2_BACKPRESSURE_HIGH_WATER` 先读 `events.status` 的admission：采样新鲜度、
+触发条件、当前值、阈值、恢复条件和消费者健康。再用 `events.subscriptions`、
+`events.deliveries`、`events.journal`、`events.audit` 定位订阅、原事实及投递。
+分页默认20/最大100，按服务器cursor继续，不无限遍历历史。
+按原requestId或commandId核对事务，见[部署与诊断](delivery.md)。未观测到、超时或503
+不能证明未提交，不换键重建业务数据。
+
+Native记录事件才能使用 `ordering:record`。订阅错误先修正应用声明并正常部署，
+再用 `events.replay` 恢复指定原deliveryId：
+
+```json
+{
+  "deliveryId":"11111111-1111-4111-8111-111111111111",
+  "reason":"原订阅配置已修复并部署，恢复该投递",
+  "idempotencyKey":"event-recovery:original-operation-id",
+  "useCurrentSubscription":true
+}
+```
+
+示例UUID换成实际查询结果。false使用原订阅规格，必须显式选择。
+平台核对类型、过滤和排序事实，只恢复该订阅投递并保留历史审计，不重建会员。
+未知结果先查投递/审计，保留同键同请求。低于阈值且取得新鲜采样后自动恢复写入；
+没有清队列或提高容量阈值的应用操作。验证单笔事务回执及列表后再继续授权导入。
+
+## 环境凭据复用 {#secrets}
+
+遇到 `APPLICATION_V2_SECRET_NOT_CONFIGURED`，分别在test及production执行 `secrets.list`。
+只返回名称、状态、revision、hasValue和有效期等元信息。来源用途已经验证且有效时，
+在目标production执行 `secrets.copy`，首次正式部署前也可操作，无需询问或读取明文：
+
+```json
+{
+  "sourceEnvironment":"test",
+  "reason":"正式环境复用已验证的集成凭据",
+  "idempotencyKey":"secret-copy:original-operation-id",
+  "secrets":[{"name":"integration-client-secret","sourceRevision":3,"expectedRevision":0}]
+}
+```
+
+名称和修订取自两侧实时列表；目标不存在用0，覆盖用目标实际revision。最多50个唯一名称，
+同应用跨环境原子复制，任一冲突拒绝整批。目标拥有独立加密版本，来源轮换不自动覆盖。
+未知结果保留原键和完整请求，先回读，必要时显式同键重试。确认的409先刷新两侧基准、
+核对后形成新操作，不能只递增revision强行覆盖。
+随后执行 `deploy --environment production --from <成功测试运行ID> --dry-run`。
+环境变量注入需新部署才读取目标版本；动态Secret服务沿用原读取规则。
+工具不会自动复制所有项；测试凭据是否适用于真实生产由已确认的集成用途决定。
+
+## 通知渠道与默认路由 {#channels}
+
+先读 `notifications.diagnostics/channels/rules`。缺少标准模板/规则时执行
+`notifications.bootstrap` 再回读。已有健康渠道可直接选默认，不必重新配置或获取密码。
+新增/更新分别用 `notifications.configure-external-http` 和 `notifications.configure-dingtalk-oa`。
+完整参数见目录inputSchema；新渠道revision用0，更新用实时revision。配置只接受Secret引用，
+不接受token、明文clientSecret或收件身份。External HTTP支持HMAC、OAuth2客户端凭据和mTLS。
+正式启用沿用服务器 `confirmProduction:true`，表示该请求明确选择正式环境，无需管理页。
+
+以下仅演示结构，真实providerCode、baseUrl、identityRealm、功能和Secret引用来自已授权集成，
+不能直接把示例地址发送到生产：
+
+```json
+{
+  "bindingCode":"organization.default","expectedRevision":0,"status":"active","confirmProduction":true,
+  "config":{
+    "schemaVersion":"openxiangda.notification.external-http-channel/v2",
+    "providerCode":"organization","baseUrl":"https://notify.example.com","identityRealm":"organization",
+    "auth":{"mode":"HMAC_SHA256","keyId":"primary","secretRef":"notification-hmac"},
+    "callback":{"enabled":false,"maxSkewSeconds":300,"actionTokenTtlMinutes":60},
+    "features":{"interactiveActions":false,"readReceipt":false,"todoSemantics":true},
+    "requestTimeoutMs":10000
+  }
+}
+```
+
+配置后执行 `notifications.test`：
+
+```json
+{"bindingCode":"organization.default","channel":"external-http"}
+```
+
+这是协议/凭据健康检查，不发实际收件通知。随后执行 `notifications.set-default`：
+
+```json
+{"bindingCode":"organization.default","expectedRevision":2,"expectedBindingRevision":1}
+```
+
+两个revision分别来自workflow.standard规则和渠道。冲突先回读核对。默认只影响当前环境
+的标准工作流通知；自定义规则仍由原owner维护。正式隐式路由不选Fake，Fake成功只证明模拟。
+
+## 原通知失败与恢复 {#notification-recovery}
+
+`notifications.messages` 按correlationId或recipientUserId查原消息，默认20/最大100；
+`notifications.message` 传原messageId，读取recipients/deliveries/attempts/审计。
+平台受理、渠道发送、已读和待办关闭分别核对，不能把受理当成老师已经收到。
+
+| 证据 | AI下一步 |
+| --- | --- |
+| 凭据缺失/禁用/过期 | secrets.list核对；用途合适时secrets.copy，随后test |
+| 默认未设置或规则缺少 | rules/channels核对，必要时bootstrap，再set-default |
+| 通道协议或联通失败 | 核对原集成接口、鉴权引用和功能，configure修正后test |
+| RECIPIENT_CHANNEL_IDENTITY_NOT_FOUND | 核对目标平台用户及identityRealm对应外部账号；由现有身份目录/消息服务owner维护映射，不创建虚假老师身份 |
+| 共享队列、数据库或网络故障 | 保存requestId、环境、消息/投递ID及状态证据，交给平台基础设施owner |
+| 403权限不足 | 由应用管理员授予已有管理权限，不获取服务器root或密码替代 |
+| 404新接口不存在 | 核对工具及平台版本，升级对应能力，不用临时SQL绕过 |
+
+修复后查 `notifications.dead-letters`，可按messageId限定。确认原任务仍有效且授权包括
+实际通知恢复，再执行 `notifications.replay`，只传指定deadLetterId。这可能真正发送通知。
+平台保留原消息、目标和审计；不重建通知或批量恢复历史待办。
+网络中断后查询原死信/消息；已恢复后的404不能当成未执行，不自动连续重放。
+已投递或被新修订取代的消息遵守服务器原有规则。
+
+## 升级与验收 {#verification}
+
+已有项目使用精确锁定版本；升级后运行 `skill install --workspace <应用目录> --force` 并
+重启MCP。应用AI不需要本地平台、数据库、Docker或学校服务器账号。
+先做只读诊断、无实际收件人的健康测试及CAS拒绝验证，再验收单笔回执/落库/实际投递。
+不要用批量导入或历史群发测试恢复。首次会话授权、权限委托和外部身份owner边界沿用原合同。

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

@@ -172,7 +172,7 @@ ADR 状态支持 `proposed`、`accepted`、`superseded`、`rejected`；按真实
 
 ### 按 ID 读取
 
-`context` / `workspace_context` 默认返回总纲、相关变更索引、阶段缺口和下一步。`spec context` / `appspec_context` 的 context v4 默认只返回总纲正文及有界索引，按稳定 ID 加载相关能力、变更、ADR 和 DES-* 设计正文及 documents 传递引用。product/experience/design/reviews 的单层 Markdown 也进入当前资料与原测试提交读取；非 Markdown 原型只引用不执行。当前资料最多 128 文件、2 MiB，正文上下文最多 256 KiB，超出时明确诊断。
+`context` / `workspace_context` 默认返回总纲、相关变更索引、阶段缺口和下一步。`spec context` / `appspec_context` 的 context v4 默认只返回总纲正文及有界索引，按稳定 ID 加载相关能力、变更、ADR 和 DES-* 设计正文及 documents 传递引用。product/experience/design/reviews 的单层 Markdown 也进入当前资料与原测试提交读取；非 Markdown 原型只引用不执行。当前资料最多 512 文件、2 MiB，正文上下文最多 256 KiB，超出时明确诊断。较大的应用可保留各批次的产品、架构、变更与评审，不需要删除历史来容纳新模块；增加文件数量不放宽字节或上下文预算。
 
 历史与当前资料独立预算，每页 50 条，使用 `--history-offset 50` 或 MCP `historyOffset` 翻页。历史索引仅读取头部，稳定历史 ID 可直接读取页外正文；归档增加不会挤掉当前资料。索引读取上限为 256 个年份目录、10 万个记录名和 5 秒，达到预算给出提示，文件不会删除。`workspaceDigest` 对应当前资料与实时契约，分页不改变它；`selectionDigest` 对应选中的具体正文与契约。
 

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

@@ -7,7 +7,7 @@
 | `pnpm openxiangda auth` | 只读 | 只读核验指定平台授权，不登录或刷新会话 |
 | `pnpm openxiangda context` | 只读 | 只读查看工作区、版本与平台绑定 |
 | `pnpm openxiangda docs` | 只读 | 按主题和章节读取当前版本中文资料 |
-| `pnpm openxiangda admin` | 只读 | 只读查看应用管理能力和流程节点运行配置 |
+| `pnpm openxiangda admin` | 远端变更 | 查看管理能力、自助操作契约，或按明确环境执行事件、密钥及通知操作 |
 | `pnpm openxiangda create` | 远端变更 | 创建、绑定并初始化应用 |
 | `pnpm openxiangda source` | 远端变更 | 配置应用源码仓库、查看状态或提交推送 |
 | `pnpm openxiangda dev` | 本地写入 | 连接平台测试数据启动本地 Web，按需启动 Nest |

package/skills/openxiangda-v2/references/field-components.md

@@ -334,6 +334,13 @@ ISO instant）与 `minuteStep`（1 到 60 且整除 60）。设置步长后只
 
 ### 子表提交行数
 
+单个子表 `maxRows` 最多500。同一模型下所有子表的声明上限合计默认最多500；
+历史快照加行程、多种材料等场景可在模型上显式声明 `ownedRowLimit: 550` 或
+`ownedRowLimit: 1000`，最多1000。此限额随模型编译到Native资源，不由提交请求指定。
+扩展声明需要平台支持 `data.aggregate-owned-subtable-capacity`；旧平台在激活前拒绝。
+标准表单、任务补填、具名初建和级联删除共用该限额与原子事务。完整替换最多2016个
+操作，但一次事务/草稿/任务值仍限2MiB；超额或最后行版本冲突整笔失败，不自动裁剪或分批写。
+
 `subtable.minRows`为可选整数，默认0，不能超过`maxRows`（默认20）；恰好一行可用
 `minRows: 1, maxRows: 1`。它约束父表提交的owned计划，独立子表写权限仍应关闭。
 普通新建即使省略表也检查；编辑只检查本次提交的表。任务草稿/保存允许不足，

package/skills/openxiangda-v2/references/managed-concurrency-frontend.md

@@ -246,6 +246,6 @@ permit 的 ManagedCommandGate 仍只用于 admitted 短确认，不用于 durabl
 
 ### 入口等待与身份加载连续性
 
-平台启用入口排队时，SDK 的当前用户读取只对明确的入口繁忙响应接续等待：HTTP 429、`CONCURRENCY_BOOTSTRAP_BUSY`、可重试以及有效的等待状态与 `remainingMs`。第一次有效回执固定等待截止，后续回执只能缩短，最长不超过首次读取开始后的三十分钟。按平台排队提示每 2–15 秒查询，加最多 20% 抖动；不会因普通繁忙或网络错误无限延长。普通身份读取仍使用五分钟恢复预算；权限拒绝、版本变化、入口过期和满额终止恢复。单次读取、投影和网络失败的限制保持独立。
+平台启用入口排队时，SDK 的当前用户读取只对明确的入口繁忙响应接续等待：HTTP 429、`CONCURRENCY_BOOTSTRAP_BUSY`、可重试以及有效的等待状态与 `remainingMs`。第一次有效回执固定等待截止，后续回执只能缩短，最长不超过首次读取开始后的三十分钟。查询至少间隔 2 秒，尊重更长的服务端提示，再加最多 20% 抖动；例如 60 秒提示实际等待 60–72 秒，不提前压成 15 秒。若提示达到剩余等待预算，保留最后响应并停止，不能提前查询或刷新截止。不会因普通繁忙或网络错误无限延长。普通身份读取仍使用五分钟恢复预算；权限拒绝、版本变化、入口过期和满额终止恢复。单次读取、投影和网络失败的限制保持独立。
 
 该行为只读取平台身份，不替应用发起或重放报名，也不改变已经受理命令的原始请求键与结果截止。上线容量需在使用该 SDK 的实际应用制品上重新验证。