openxiangda-skill-kit 2.3.28 → 2.3.30

package/package.json

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

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

@@ -261,7 +261,11 @@ const locations = {
   code: 'reservation.locations', method: 'GET', path: '/api/reservations/locations',
   capability: 'app:visitor-app:reservation:locations',
   requestSchema: { type: 'object', properties: { keyword: { type: 'string' } } },
-  responseSchema: { type: 'object' },
+  responseSchema: { type: 'object', additionalProperties: false, required: ['items', 'nextCursor'], properties: {
+    items: { type: 'array', maxItems: 20, items: { type: 'object', additionalProperties: false,
+      required: ['value', 'label'], properties: { value: { type: 'string' }, label: { type: 'string' } } } },
+    nextCursor: { type: ['string', 'null'] },
+  } },
   ai: {
     name: '查找可预约地点', description: '按名称搜索当前用户可选择的地点',
     risk: 'read', resources: ['reservations'], sideEffects: [],
@@ -272,10 +276,12 @@ const enroll = {
   code: 'reservation.enroll', method: 'POST', path: '/api/reservations/enroll',
   capability: 'app:visitor-app:reservation:enroll',
   requestSchema: {
-    type: 'object', required: ['location'],
-    properties: { location: { type: 'string' } },
+    type: 'object', required: ['location', 'purpose'],
+    properties: { location: { type: 'string' }, purpose: { type: 'string' } },
   },
-  responseSchema: { type: 'object' },
+  responseSchema: { type: 'object', properties: {
+    ticketNo: { type: 'string' }, locationName: { type: 'string' },
+  } },
   ai: {
     name: '发起访客预约', description: '校验访客信息、地点与时间后创建预约',
     risk: 'write', resources: ['reservations'], sideEffects: ['创建访客预约'],
@@ -285,6 +291,14 @@ const enroll = {
       aliases: ['发起邀约'],
       supportOperations: ['reservation.locations'],
       inputLookups: { location: 'reservation.locations' },
+      inputCard: { title: '补全访客预约', submitLabel: '发起预约', fields: [
+        { path: 'location', label: '预约地点', control: 'select', help: '搜索地点名称后选择' },
+        { path: 'purpose', label: '来访事由', control: 'textarea' },
+      ] },
+      resultCard: { title: '预约已提交', fields: [
+        { path: 'ticketNo', label: '预约单号' },
+        { path: 'locationName', label: '地点' },
+      ] },
     },
   },
 };
@@ -292,7 +306,11 @@ 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 的写入确认协议。
+`inputCard` 是平台标准填写卡片，只能用于 `customAction` 任务。字段必须是同一请求 Schema 的顶层字符串，所有必填字段必须包含在卡片中；首版控件为 `text`、`textarea`、`select`，最多 12 项。`select` 必须绑定 `inputLookups`，辅助 GET 操作接受可选 `keyword`，返回最多 20 项 `{items:[{value,label}],nextCursor:null|string}`。`label` 面向用户，`value` 是稳定引用，业务 handler 仍须校验该引用。模型只创建等待卡并预填已确定的值；刷新后从会话快照恢复，提交后平台以当前用户身份和固定任务创建后台 Run，不再次请求模型。提交检查权限、AppVersion/目录摘要、完整请求 Schema 和幂等键；旧卡、权限撤销、版本变化和未知结果均不能静默重放。
+
+`resultCard` 是已完成任务的只读结果卡片：只允许引用 `responseSchema.properties` 中明确声明的顶层字符串、数字或布尔字段，最多 8 项；不渲染任意 HTML/JS。应用须确保这些字段可向当前用户显示。自定义 React 卡片 Host/SDK 尚属独立后续单元。本声明不改变既有 MCP Facade 的写入确认协议。
+
+业务规则必须在后端操作中验证；提示词、卡片预填和前端校验不能取代权限与业务校验。完整输入、缺失输入、同名地点、权限不足、重复提交和结果未知都应有应用测试与回执核对。任务声明随 AppVersion 的 AI Catalog 一起发布，不能另建手工目录。
 
 宿主（平台 AI 网关）用该目录装配 MCP Facade，应用不自己实现协议：
 

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

@@ -58,6 +58,8 @@
 | 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.inputCard: { title: '补全报修', fields: [{ path: 'location', label: '地点', control: 'select' }, { path: 'description', label: '故障描述', control: 'textarea' }] }`；包含全部请求必填字段，单选字段绑定只读 `inputLookups`，辅助操作响应须为有界 `items[{value,label}]` |
+| 任务完成后显示业务结果卡片 | `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'` |