openxiangda-skill-kit 2.3.27 → 2.3.29

package/package.json

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

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

@@ -248,6 +248,7 @@ operations: [{
 `read` 等价于 `method: 'GET'`，DELETE 方法只能是 `destructive` 或 `external`；`resources`
 引用 1–16 个已声明资源；`sideEffects` 最多 20 条——只读必须为零，写操作至少一条具体副作用；
 `concurrency` 可选 `none | revision`，`timeoutMs` 限 100–30000。
+普通 `write` 操作可显式声明 `confirmation: 'none'`：用户明确要求办理、输入齐全且无歧义时，平台 Agent 可直接调用并返回真实回执，不生成统一预览。省略时仍为 `required`；`destructive` 和 `external` 必须为 `required`，只读必须为 `none`。免二次确认不取消当前用户授权、AppVersion 绑定、输入校验、幂等键及应用业务校验。需要用户补齐字段、消除歧义或应用业务规则要求确认时，Agent 仍应先询问。
 
 ### 面向普通用户的 Agent 任务
 
@@ -274,7 +275,9 @@ const enroll = {
     type: 'object', required: ['location'],
     properties: { location: { type: 'string' } },
   },
-  responseSchema: { type: 'object' },
+  responseSchema: { type: 'object', properties: {
+    ticketNo: { type: 'string' }, locationName: { type: 'string' },
+  } },
   ai: {
     name: '发起访客预约', description: '校验访客信息、地点与时间后创建预约',
     risk: 'write', resources: ['reservations'], sideEffects: ['创建访客预约'],
@@ -284,6 +287,10 @@ const enroll = {
       aliases: ['发起邀约'],
       supportOperations: ['reservation.locations'],
       inputLookups: { location: 'reservation.locations' },
+      resultCard: { title: '预约已提交', fields: [
+        { path: 'ticketNo', label: '预约单号' },
+        { path: 'locationName', label: '地点' },
+      ] },
     },
   },
 };
@@ -291,7 +298,9 @@ const enroll = {
 
 两个 `capability` 必须在 `authz.capabilities` 中声明为 `kind: 'backend'`，再授予相应角色。`supportOperations` 和 `inputLookups` 引用同一应用中的操作 code；被引用操作必须声明 `visibility: 'support'`、`risk: 'read'` 且使用 GET。`inputLookups` 的键必须存在于任务的 `requestSchema.properties`。示例问法最多 12 条、别名最多 20 条、辅助操作最多 12 个、字段绑定最多 32 个；运行时辅助查询仍应分页、有界，并返回业务标签与稳定引用。
 
-业务规则必须在后端操作中验证；提示词、卡片预填和前端校验不能取代权限与业务校验。完整输入、缺失输入、同名地点、权限不足、重复提交和结果未知都应有应用测试与回执核对。任务声明随 AppVersion 的 AI Catalog 一起发布，不能另建手工目录。交互卡片与自动执行仅在平台 Agent Host 支持后启用；本声明本身不改变现有 MCP Facade 的写入确认协议。
+`resultCard` 是已完成任务的只读结果卡片：只允许引用 `responseSchema.properties` 中明确声明的顶层字符串、数字或布尔字段，最多 8 项；不渲染任意 HTML/JS。应用须确保这些字段可向当前用户显示。平台助手已支持按应用声明自动执行普通写任务；待补信息表单、自定义 React 卡片 Host 仍按平台批次实现。本声明不改变既有 MCP Facade 的写入确认协议。
+
+业务规则必须在后端操作中验证；提示词、卡片预填和前端校验不能取代权限与业务校验。完整输入、缺失输入、同名地点、权限不足、重复提交和结果未知都应有应用测试与回执核对。任务声明随 AppVersion 的 AI Catalog 一起发布，不能另建手工目录。
 
 宿主（平台 AI 网关）用该目录装配 MCP Facade，应用不自己实现协议：
 

package/skills/openxiangda-v2/references/declarations-cheatsheet.md

@@ -54,9 +54,11 @@
 | 规则 | 正确片段 |
 | --- | --- |
 | 写操作的 `ai.sideEffects` 至少一条具体副作用 | `ai: { name: '受理派单', ..., risk: 'write', sideEffects: ['更新报修单状态为处理中', '写入一条派工记录'] }` |
+| 普通写任务允许按应用规则免二次确认；破坏性及外部动作仍须确认 | `ai: { ..., risk: 'write', confirmation: 'none' }`；省略时为 `required`，平台仍强制幂等和权限校验 |
 | GET 操作的 `ai.risk` 只能是 `read`；写操作不能是 `read` | `risk: 'read'` ↔ `method: 'GET'` |
 | 面向普通用户的 Agent 只发现显式声明的业务任务；底层 CRUD 不会自动成为任务 | `ai.agent: { visibility: 'task', examples: ['帮我发起报修'], aliases: ['提交报修'] }` |
 | 任务输入需要地点、人员等业务选择时，绑定同应用的只读辅助操作，用户不填内部编码 | `agent: { visibility: 'task', supportOperations: ['repair.locations'], inputLookups: { location: 'repair.locations' } }`；被引用的 GET 操作须有 `agent: { visibility: 'support' }`，`location` 须是请求 Schema 字段 |
+| 任务完成后显示业务结果卡片 | `agent.resultCard: { title: '报修已提交', fields: [{ path: 'ticketNo', label: '单号' }] }`；`ticketNo` 必须是该操作响应 Schema 中的顶层标量字段，最多 8 项 |
 | controller 路由必须绑定 `@OpenXiangdaOperation(appOperations.<code>)`，普通 CRUD 不写 controller | check 门禁会拒绝未绑定路由 |
 | 事务守卫 `errorCode` 必须匹配 `^OPENXIANGDA_[A-Z0-9_]{1,96}$` | `errorCode: 'OPENXIANGDA_REPAIR_REQUEST_NOT_PENDING'` |