openxiangda 2.31.1 → 2.31.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/documentation/backend.md +11 -2
  2. package/documentation/declarations-cheatsheet.md +2 -0
  3. package/documentation/getting-started.md +7 -7
  4. package/documentation/manifest.json +4 -4
  5. package/package.json +20 -26
  6. package/releases/2.31.2.json +34 -0
  7. package/releases/2.31.3.json +32 -0
  8. package/skills/manifest.json +1 -1
  9. package/skills/openxiangda-v2/SKILL.md +4 -4
  10. package/skills/openxiangda-v2/references/backend.md +11 -2
  11. package/skills/openxiangda-v2/references/declarations-cheatsheet.md +2 -0
  12. package/skills/openxiangda-v2/references/getting-started.md +7 -7
package/documentation/backend.md CHANGED
@@ -248,6 +248,7 @@ operations: [{
248
248
  `read` 等价于 `method: 'GET'`，DELETE 方法只能是 `destructive` 或 `external`；`resources`
249
249
  引用 1–16 个已声明资源；`sideEffects` 最多 20 条——只读必须为零，写操作至少一条具体副作用；
250
250
  `concurrency` 可选 `none | revision`，`timeoutMs` 限 100–30000。
251
+ 普通 `write` 操作可显式声明 `confirmation: 'none'`：用户明确要求办理、输入齐全且无歧义时，平台 Agent 可直接调用并返回真实回执，不生成统一预览。省略时仍为 `required`；`destructive` 和 `external` 必须为 `required`，只读必须为 `none`。免二次确认不取消当前用户授权、AppVersion 绑定、输入校验、幂等键及应用业务校验。需要用户补齐字段、消除歧义或应用业务规则要求确认时，Agent 仍应先询问。
251
252
 
252
253
  ### 面向普通用户的 Agent 任务
253
254
 
@@ -274,7 +275,9 @@ const enroll = {
274
275
  type: 'object', required: ['location'],
275
276
  properties: { location: { type: 'string' } },
276
277
  },
277
- responseSchema: { type: 'object' },
278
+ responseSchema: { type: 'object', properties: {
279
+ ticketNo: { type: 'string' }, locationName: { type: 'string' },
280
+ } },
278
281
  ai: {
279
282
  name: '发起访客预约', description: '校验访客信息、地点与时间后创建预约',
280
283
  risk: 'write', resources: ['reservations'], sideEffects: ['创建访客预约'],
@@ -284,6 +287,10 @@ const enroll = {
284
287
  aliases: ['发起邀约'],
285
288
  supportOperations: ['reservation.locations'],
286
289
  inputLookups: { location: 'reservation.locations' },
290
+ resultCard: { title: '预约已提交', fields: [
291
+ { path: 'ticketNo', label: '预约单号' },
292
+ { path: 'locationName', label: '地点' },
293
+ ] },
287
294
  },
288
295
  },
289
296
  };
@@ -291,7 +298,9 @@ const enroll = {
291
298
 
292
299
  两个 `capability` 必须在 `authz.capabilities` 中声明为 `kind: 'backend'`，再授予相应角色。`supportOperations` 和 `inputLookups` 引用同一应用中的操作 code；被引用操作必须声明 `visibility: 'support'`、`risk: 'read'` 且使用 GET。`inputLookups` 的键必须存在于任务的 `requestSchema.properties`。示例问法最多 12 条、别名最多 20 条、辅助操作最多 12 个、字段绑定最多 32 个；运行时辅助查询仍应分页、有界，并返回业务标签与稳定引用。
293
300
 
294
- 业务规则必须在后端操作中验证；提示词、卡片预填和前端校验不能取代权限与业务校验。完整输入、缺失输入、同名地点、权限不足、重复提交和结果未知都应有应用测试与回执核对。任务声明随 AppVersion 的 AI Catalog 一起发布，不能另建手工目录。交互卡片与自动执行仅在平台 Agent Host 支持后启用；本声明本身不改变现有 MCP Facade 的写入确认协议。
301
+ `resultCard` 是已完成任务的只读结果卡片：只允许引用 `responseSchema.properties` 中明确声明的顶层字符串、数字或布尔字段，最多 8 项；不渲染任意 HTML/JS。应用须确保这些字段可向当前用户显示。平台助手已支持按应用声明自动执行普通写任务；待补信息表单、自定义 React 卡片 Host 仍按平台批次实现。本声明不改变既有 MCP Facade 的写入确认协议。
302
+
303
+ 业务规则必须在后端操作中验证；提示词、卡片预填和前端校验不能取代权限与业务校验。完整输入、缺失输入、同名地点、权限不足、重复提交和结果未知都应有应用测试与回执核对。任务声明随 AppVersion 的 AI Catalog 一起发布，不能另建手工目录。
295
304
 
296
305
  宿主（平台 AI 网关）用该目录装配 MCP Facade，应用不自己实现协议：
297
306
 
package/documentation/declarations-cheatsheet.md CHANGED
@@ -54,9 +54,11 @@
54
54
  | 规则 | 正确片段 |
55
55
  | --- | --- |
56
56
  | 写操作的 `ai.sideEffects` 至少一条具体副作用 | `ai: { name: '受理派单', ..., risk: 'write', sideEffects: ['更新报修单状态为处理中', '写入一条派工记录'] }` |
57
+ | 普通写任务允许按应用规则免二次确认；破坏性及外部动作仍须确认 | `ai: { ..., risk: 'write', confirmation: 'none' }`；省略时为 `required`，平台仍强制幂等和权限校验 |
57
58
  | GET 操作的 `ai.risk` 只能是 `read`；写操作不能是 `read` | `risk: 'read'` ↔ `method: 'GET'` |
58
59
  | 面向普通用户的 Agent 只发现显式声明的业务任务；底层 CRUD 不会自动成为任务 | `ai.agent: { visibility: 'task', examples: ['帮我发起报修'], aliases: ['提交报修'] }` |
59
60
  | 任务输入需要地点、人员等业务选择时，绑定同应用的只读辅助操作，用户不填内部编码 | `agent: { visibility: 'task', supportOperations: ['repair.locations'], inputLookups: { location: 'repair.locations' } }`；被引用的 GET 操作须有 `agent: { visibility: 'support' }`，`location` 须是请求 Schema 字段 |
61
+ | 任务完成后显示业务结果卡片 | `agent.resultCard: { title: '报修已提交', fields: [{ path: 'ticketNo', label: '单号' }] }`；`ticketNo` 必须是该操作响应 Schema 中的顶层标量字段，最多 8 项 |
60
62
  | controller 路由必须绑定 `@OpenXiangdaOperation(appOperations.<code>)`，普通 CRUD 不写 controller | check 门禁会拒绝未绑定路由 |
61
63
  | 事务守卫 `errorCode` 必须匹配 `^OPENXIANGDA_[A-Z0-9_]{1,96}$` | `errorCode: 'OPENXIANGDA_REPAIR_REQUEST_NOT_PENDING'` |
62
64
 
package/documentation/getting-started.md CHANGED
@@ -68,10 +68,10 @@ MCP 服务随项目根包一起安装，AI 客户端的 stdio 连接仍需配置
68
68
  以下命令的版本占位符由随包资料替换为该根包的精确版本。网站源码阅读者应先确认要使用的发行版本。
69
69
 
70
70
  ```bash
71
- pnpm dlx openxiangda@2.31.1 skill install --force
72
- pnpm dlx openxiangda@2.31.1 auth status --base-url <平台地址> --json
73
- pnpm dlx openxiangda@2.31.1 login --cwd my-app --base-url https://platform.example.com
74
- pnpm dlx openxiangda@2.31.1 create my-app --base-url https://platform.example.com
71
+ pnpm dlx openxiangda@2.31.3 skill install --force
72
+ pnpm dlx openxiangda@2.31.3 auth status --base-url <平台地址> --json
73
+ pnpm dlx openxiangda@2.31.3 login --cwd my-app --base-url https://platform.example.com
74
+ pnpm dlx openxiangda@2.31.3 create my-app --base-url https://platform.example.com
75
75
  cd my-app
76
76
  pnpm openxiangda context --json
77
77
  pnpm openxiangda dev
@@ -174,9 +174,9 @@ MCP 的 `docs_read` 可以读取本说明，当前没有独立的源码操作 MC
174
174
  无需本地工作区，使用本 Skill 随包精确版本或已安装的对应 CLI：
175
175
 
176
176
  ```bash
177
- pnpm dlx openxiangda@2.31.1 auth status --base-url <平台> --json
178
- pnpm dlx openxiangda@2.31.1 source resolve <仓库URL> --base-url <平台> --json
179
- pnpm dlx openxiangda@2.31.1 source clone <仓库URL> <新目录> --base-url <平台> --json
177
+ pnpm dlx openxiangda@2.31.3 auth status --base-url <平台> --json
178
+ pnpm dlx openxiangda@2.31.3 source resolve <仓库URL> --base-url <平台> --json
179
+ pnpm dlx openxiangda@2.31.3 source clone <仓库URL> <新目录> --base-url <平台> --json
180
180
  ```
181
181
 
182
182
  登录缺失或站点不匹配时，先按该平台执行 login。resolve 根据平台已经登记的绑定返回
package/documentation/manifest.json CHANGED
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "schemaVersion": "openxiangda.documentation/v1",
3
- "version": "2.31.1",
3
+ "version": "2.31.3",
4
4
  "topics": [
5
5
  {
6
6
  "id": "getting-started",
7
7
  "title": "安装与开始开发",
8
8
  "file": "getting-started.md",
9
- "sha256": "108af379386c6802d4b775e2f3d0f08fe71b7109e8d365548299b2fb1cf55b9d"
9
+ "sha256": "9ae7dda856616e44a6c95bb886258a7d1b00f874dbaadff912b27101d5cc3ed0"
10
10
  },
11
11
  {
12
12
  "id": "product-design",
@@ -36,7 +36,7 @@
36
36
  "id": "declarations-cheatsheet",
37
37
  "title": "声明速查：一次写对 config",
38
38
  "file": "declarations-cheatsheet.md",
39
- "sha256": "17357e46cfea90ecb9752d33bc378e2c901df6260aca0981ea5710ec82dbbd4e"
39
+ "sha256": "86c2f4c0d3f47fa0632b5d0aca96c4e2f91d619c44419ce7af8558de97af42dd"
40
40
  },
41
41
  {
42
42
  "id": "application-foundation",
@@ -90,7 +90,7 @@
90
90
  "id": "backend",
91
91
  "title": "按需后端与业务动作",
92
92
  "file": "backend.md",
93
- "sha256": "12312dd666b8a7991282acf78a839c7af336aefa007a08645f5e30b18e67b8b4"
93
+ "sha256": "c134558dcf38562bb86b3ad3fda9788e306b87aa3bcddde37eba78af1db58f2c"
94
94
  },
95
95
  {
96
96
  "id": "decimal-reservations",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "openxiangda",
3
- "version": "2.31.1",
3
+ "version": "2.31.3",
4
4
  "description": "OpenXiangda 2.0 的统一命令、应用 SDK、MCP 与中文 AI 技能资料。",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -60,13 +60,13 @@
60
60
  "antd-mobile": "5.42.3",
61
61
  "dayjs": "1.11.18",
62
62
  "docx-preview": "0.3.7",
63
- "openxiangda-cli": "2.6.3",
64
- "openxiangda-contracts": "2.29.0",
65
- "openxiangda-devkit-core": "2.32.0",
63
+ "openxiangda-cli": "2.6.5",
64
+ "openxiangda-contracts": "2.30.1",
65
+ "openxiangda-devkit-core": "2.33.1",
66
66
  "openxiangda-legacy": "npm:openxiangda@1.0.269",
67
- "openxiangda-mcp": "2.0.53",
68
- "openxiangda-nest": "2.7.6",
69
- "openxiangda-skill-kit": "2.3.27",
67
+ "openxiangda-mcp": "2.0.55",
68
+ "openxiangda-nest": "2.7.8",
69
+ "openxiangda-skill-kit": "2.3.29",
70
70
  "xlsx": "https://github.com/1377385356/openxiangda/releases/download/vendor-mirror/xlsx-0.20.3.tgz"
71
71
  },
72
72
  "peerDependencies": {
@@ -132,41 +132,35 @@
132
132
  },
133
133
  "openxiangdaRelease": {
134
134
  "schemaVersion": "openxiangda.release-notes/v1",
135
- "version": "2.31.1",
135
+ "version": "2.31.3",
136
136
  "status": "reviewed",
137
- "title": "OpenXiangda 2.31.1：应用业务 Agent 任务声明",
138
- "summary": "应用可以在现有 AI 操作上显式声明面向普通用户的业务任务、常见问法、只读辅助能力和输入字段查询绑定。编译器把这些信息并入同一个 AppVersion AI Catalog，平台按当前用户权限发现和执行。",
137
+ "title": "OpenXiangda 2.31.3：业务 Agent 结果卡片声明",
138
+ "summary": "应用任务可以声明已完成操作的只读结果卡片。编译器把展示字段限制在响应 Schema 的顶层标量属性，并将声明随应用版本发布。",
139
139
  "newFeatures": [
140
- "ai.agent.visibility 区分可独立办理的 task 与任务引用的只读 support；未声明的底层 CRUD 不自动成为普通用户任务。",
141
- "任务可以声明 examples、aliases、supportOperations 和 inputLookups；编译器校验辅助操作只读、引用闭合和请求字段存在。",
142
- "docs/backend.md、声明速查和 OpenXiangda 2.0 Skill 提供接入流程及访客预约示例。",
143
- "并发能力前端指南覆盖热点读取、申请、排队、预占确认与原结果恢复，并标明已提供 API 和待实现封装。"
140
+ "backend.operations[].ai.agent.resultCard 支持标题和最多 8 个结果字段，并校验字段引用、类型及边界。",
141
+ "开发文档、速查表与 AI Skill 同步给出结果卡片示例和接入规则。"
144
142
  ],
145
143
  "fixes": [],
146
144
  "affectedUsers": [
147
- "希望把业务操作接入平台助手或应用 Agent 的 OpenXiangda 2.0 应用开发者。",
148
- "需要实现缓存、排队或限额场景前端的应用开发者。"
145
+ "需要在平台助手会话中展示预约、报修等业务回执的 OpenXiangda 2.0 应用开发者。"
149
146
  ],
150
147
  "upgradeSteps": [
151
- "升级到 openxiangda@2.31.1 并更新锁文件，先实现完整业务操作、授权和只读辅助查询，再按 docs/backend.md 声明 ai.agent。",
152
- "在测试环境运行 check 与完整输入、缺失输入、同名对象、权限不足和重复提交场景；发布应用版本后核对 AI Catalog 摘要与当前环境 Head。",
153
- "平台服务端须部署支持显式业务任务发现的版本；npm 包发布本身不会升级平台或自动公开旧应用操作。",
154
- "并发前端接入按 docs/managed-concurrency-frontend.md 选择模式，先核对已导出的 API 与目标平台能力。"
148
+ "升级 openxiangda 并更新锁文件；在业务操作的 responseSchema.properties 中声明可展示的标量字段，再可选配置 agent.resultCard。",
149
+ "在预发验证完整业务结果、字段缺失和刷新恢复；卡片展示需要配套平台服务端与前端版本。"
155
150
  ],
156
151
  "knownLimitations": [
157
- "本次包仅增加业务任务元数据与编译校验；交互卡片资源、持久 Interaction 和 MCP Apps Host 由后续平台与应用批次交付。",
158
- "现有独立 MCP Facade 的写入预览与确认协议保持原样；平台自有 Agent 的自动写入由平台执行层和权限边界负责。",
159
- "旧应用的底层 CRUD 不会自动转换为普通用户任务，需应用维护者完成业务语义与辅助能力接入。"
152
+ "本版只定义已完成业务操作的只读结果卡片；待补信息表单、持久 Interaction 与应用自定义 React Host 尚未发布。",
153
+ "结果卡片不改变应用权限、业务执行或既有 MCP Facade 的确认协议。"
160
154
  ],
161
155
  "issues": [],
162
156
  "compatibility": {
163
157
  "node": ">=24",
164
158
  "workspaceGenerations": "v2",
165
- "platform": "平台业务 Agent 任务发现需配套部署支持 ai.agent 元数据的服务端版本。",
159
+ "platform": "结果卡片呈现需要配套平台 Agent 回执投影和会话前端。",
166
160
  "v1": "独立 V1 引擎和工作区不受影响。"
167
161
  },
168
- "sha256": "37c61ac4c9b17a8ca688cc9e1f38f4ed106754a7342e1a6aa9b2095e954a5118",
169
- "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.31.1"
162
+ "sha256": "56e36516118cda6a6d2d4029dc25e593a1b4e76198279cf27cf9e58bf8dc392e",
163
+ "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.31.3"
170
164
  },
171
165
  "scripts": {
172
166
  "build": "node ../../scripts/prune-package-dist.mjs && tsc -p tsconfig.json && node scripts/copy-assets.mjs",
package/releases/2.31.2.json ADDED
@@ -0,0 +1,34 @@
1
+ {
2
+ "schemaVersion": "openxiangda.release-notes/v1",
3
+ "version": "2.31.2",
4
+ "status": "reviewed",
5
+ "title": "OpenXiangda 2.31.2：普通业务任务可自动执行写入",
6
+ "summary": "应用可为普通业务写任务显式声明免通用二次确认。用户明确要求办理且信息完整时，平台 Agent 可直接执行并返回回执；权限、版本绑定与幂等仍由平台和应用校验。",
7
+ "newFeatures": [
8
+ "backend.operations[].ai.confirmation 支持普通 write 显式选择 none；省略时仍为 required。",
9
+ "编译器、Catalog 契约、应用开发指南及 Skill 同步说明确认策略。"
10
+ ],
11
+ "fixes": [],
12
+ "affectedUsers": [
13
+ "开发预约、报修等普通业务 Agent 写任务的 OpenXiangda 2.0 应用开发者。"
14
+ ],
15
+ "upgradeSteps": [
16
+ "升级到 openxiangda@2.31.2 并更新锁文件，在业务操作的 ai 声明中按需显式设置 confirmation: 'none'。",
17
+ "在预发验证完整输入、缺失输入、对象歧义、无权访问和同一幂等键重放，再发布应用版本并核对 Catalog 与环境 Head。",
18
+ "平台 Agent 执行层须支持受管直接执行；npm 包发布本身不更新平台。"
19
+ ],
20
+ "knownLimitations": [
21
+ "免确认仅适用于普通 write；destructive 和 external 继续要求确认，read 不确认。",
22
+ "独立 MCP Facade 的预览/确认协议未在本轮改变。",
23
+ "交互卡片资源与持久 Interaction 仍需后续批次交付。"
24
+ ],
25
+ "issues": [],
26
+ "compatibility": {
27
+ "node": ">=24",
28
+ "workspaceGenerations": "v2",
29
+ "platform": "需配套支持业务 Agent 受管直接执行的服务端版本。",
30
+ "v1": "独立 V1 引擎和工作区不受影响。"
31
+ },
32
+ "sha256": "be6fa650ee197a3949c17aec11af97e833e70a1d8461992c3e25063c238cff1e",
33
+ "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.31.2"
34
+ }
package/releases/2.31.3.json ADDED
@@ -0,0 +1,32 @@
1
+ {
2
+ "schemaVersion": "openxiangda.release-notes/v1",
3
+ "version": "2.31.3",
4
+ "status": "reviewed",
5
+ "title": "OpenXiangda 2.31.3：业务 Agent 结果卡片声明",
6
+ "summary": "应用任务可以声明已完成操作的只读结果卡片。编译器把展示字段限制在响应 Schema 的顶层标量属性，并将声明随应用版本发布。",
7
+ "newFeatures": [
8
+ "backend.operations[].ai.agent.resultCard 支持标题和最多 8 个结果字段，并校验字段引用、类型及边界。",
9
+ "开发文档、速查表与 AI Skill 同步给出结果卡片示例和接入规则。"
10
+ ],
11
+ "fixes": [],
12
+ "affectedUsers": [
13
+ "需要在平台助手会话中展示预约、报修等业务回执的 OpenXiangda 2.0 应用开发者。"
14
+ ],
15
+ "upgradeSteps": [
16
+ "升级 openxiangda 并更新锁文件；在业务操作的 responseSchema.properties 中声明可展示的标量字段，再可选配置 agent.resultCard。",
17
+ "在预发验证完整业务结果、字段缺失和刷新恢复；卡片展示需要配套平台服务端与前端版本。"
18
+ ],
19
+ "knownLimitations": [
20
+ "本版只定义已完成业务操作的只读结果卡片；待补信息表单、持久 Interaction 与应用自定义 React Host 尚未发布。",
21
+ "结果卡片不改变应用权限、业务执行或既有 MCP Facade 的确认协议。"
22
+ ],
23
+ "issues": [],
24
+ "compatibility": {
25
+ "node": ">=24",
26
+ "workspaceGenerations": "v2",
27
+ "platform": "结果卡片呈现需要配套平台 Agent 回执投影和会话前端。",
28
+ "v1": "独立 V1 引擎和工作区不受影响。"
29
+ },
30
+ "sha256": "56e36516118cda6a6d2d4029dc25e593a1b4e76198279cf27cf9e58bf8dc392e",
31
+ "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.31.3"
32
+ }
package/skills/manifest.json CHANGED
@@ -4,7 +4,7 @@
4
4
  {
5
5
  "name": "openxiangda-v2",
6
6
  "description": "使用 OpenXiangda 2.0 从模糊业务想法、已有资料或具体变更出发，通过对话发现模块、完成详细产品设计，由当前 AI Agent 按需用 Image 2.5 等图片能力形成视觉参考，直接实现真实页面并在浏览器修正，再检查和交付应用；维护 1.x 应用时使用对应的 1.x 技能。",
7
- "sha256": "a53fab63a4033b8dca5de456f17d7cc55542f95bfb14460e551377649d04ca18"
7
+ "sha256": "b47a0088e786fa535c93743c7c063ef0524c1b25f2988e91d2dba12d04e86172"
8
8
  }
9
9
  ]
10
10
  }
package/skills/openxiangda-v2/SKILL.md CHANGED
@@ -40,10 +40,10 @@ AI 接到新应用、页面或改版任务时，在同一个 OpenXiangda 工作
40
40
  未创建工作区时使用本 Skill 随根包发布的精确版本：
41
41
 
42
42
  ```bash
43
- pnpm dlx openxiangda@2.31.1 auth status --cwd <应用目录> --base-url <平台地址> --json
44
- pnpm dlx openxiangda@2.31.1 login --cwd <应用目录> --base-url <平台地址>
45
- pnpm dlx openxiangda@2.31.1 create <应用目录> --base-url <同一平台地址>
46
- pnpm dlx openxiangda@2.31.1 skill install --force
43
+ pnpm dlx openxiangda@2.31.3 auth status --cwd <应用目录> --base-url <平台地址> --json
44
+ pnpm dlx openxiangda@2.31.3 login --cwd <应用目录> --base-url <平台地址>
45
+ pnpm dlx openxiangda@2.31.3 create <应用目录> --base-url <同一平台地址>
46
+ pnpm dlx openxiangda@2.31.3 skill install --force
47
47
  ```
48
48
 
49
49
  创建前把产品要求的目标平台明确带入命令，不从旧登录态推断站点。已有工作区从原绑定恢复，平台不一致时先解决登录与目标，不改 link 文件跨站创建。
package/skills/openxiangda-v2/references/backend.md CHANGED
@@ -248,6 +248,7 @@ operations: [{
248
248
  `read` 等价于 `method: 'GET'`，DELETE 方法只能是 `destructive` 或 `external`；`resources`
249
249
  引用 1–16 个已声明资源；`sideEffects` 最多 20 条——只读必须为零，写操作至少一条具体副作用；
250
250
  `concurrency` 可选 `none | revision`，`timeoutMs` 限 100–30000。
251
+ 普通 `write` 操作可显式声明 `confirmation: 'none'`：用户明确要求办理、输入齐全且无歧义时，平台 Agent 可直接调用并返回真实回执，不生成统一预览。省略时仍为 `required`；`destructive` 和 `external` 必须为 `required`，只读必须为 `none`。免二次确认不取消当前用户授权、AppVersion 绑定、输入校验、幂等键及应用业务校验。需要用户补齐字段、消除歧义或应用业务规则要求确认时，Agent 仍应先询问。
251
252
 
252
253
  ### 面向普通用户的 Agent 任务
253
254
 
@@ -274,7 +275,9 @@ const enroll = {
274
275
  type: 'object', required: ['location'],
275
276
  properties: { location: { type: 'string' } },
276
277
  },
277
- responseSchema: { type: 'object' },
278
+ responseSchema: { type: 'object', properties: {
279
+ ticketNo: { type: 'string' }, locationName: { type: 'string' },
280
+ } },
278
281
  ai: {
279
282
  name: '发起访客预约', description: '校验访客信息、地点与时间后创建预约',
280
283
  risk: 'write', resources: ['reservations'], sideEffects: ['创建访客预约'],
@@ -284,6 +287,10 @@ const enroll = {
284
287
  aliases: ['发起邀约'],
285
288
  supportOperations: ['reservation.locations'],
286
289
  inputLookups: { location: 'reservation.locations' },
290
+ resultCard: { title: '预约已提交', fields: [
291
+ { path: 'ticketNo', label: '预约单号' },
292
+ { path: 'locationName', label: '地点' },
293
+ ] },
287
294
  },
288
295
  },
289
296
  };
@@ -291,7 +298,9 @@ const enroll = {
291
298
 
292
299
  两个 `capability` 必须在 `authz.capabilities` 中声明为 `kind: 'backend'`，再授予相应角色。`supportOperations` 和 `inputLookups` 引用同一应用中的操作 code；被引用操作必须声明 `visibility: 'support'`、`risk: 'read'` 且使用 GET。`inputLookups` 的键必须存在于任务的 `requestSchema.properties`。示例问法最多 12 条、别名最多 20 条、辅助操作最多 12 个、字段绑定最多 32 个；运行时辅助查询仍应分页、有界，并返回业务标签与稳定引用。
293
300
 
294
- 业务规则必须在后端操作中验证；提示词、卡片预填和前端校验不能取代权限与业务校验。完整输入、缺失输入、同名地点、权限不足、重复提交和结果未知都应有应用测试与回执核对。任务声明随 AppVersion 的 AI Catalog 一起发布，不能另建手工目录。交互卡片与自动执行仅在平台 Agent Host 支持后启用；本声明本身不改变现有 MCP Facade 的写入确认协议。
301
+ `resultCard` 是已完成任务的只读结果卡片：只允许引用 `responseSchema.properties` 中明确声明的顶层字符串、数字或布尔字段，最多 8 项；不渲染任意 HTML/JS。应用须确保这些字段可向当前用户显示。平台助手已支持按应用声明自动执行普通写任务；待补信息表单、自定义 React 卡片 Host 仍按平台批次实现。本声明不改变既有 MCP Facade 的写入确认协议。
302
+
303
+ 业务规则必须在后端操作中验证；提示词、卡片预填和前端校验不能取代权限与业务校验。完整输入、缺失输入、同名地点、权限不足、重复提交和结果未知都应有应用测试与回执核对。任务声明随 AppVersion 的 AI Catalog 一起发布，不能另建手工目录。
295
304
 
296
305
  宿主（平台 AI 网关）用该目录装配 MCP Facade，应用不自己实现协议：
297
306
 
package/skills/openxiangda-v2/references/declarations-cheatsheet.md CHANGED
@@ -54,9 +54,11 @@
54
54
  | 规则 | 正确片段 |
55
55
  | --- | --- |
56
56
  | 写操作的 `ai.sideEffects` 至少一条具体副作用 | `ai: { name: '受理派单', ..., risk: 'write', sideEffects: ['更新报修单状态为处理中', '写入一条派工记录'] }` |
57
+ | 普通写任务允许按应用规则免二次确认；破坏性及外部动作仍须确认 | `ai: { ..., risk: 'write', confirmation: 'none' }`；省略时为 `required`，平台仍强制幂等和权限校验 |
57
58
  | GET 操作的 `ai.risk` 只能是 `read`；写操作不能是 `read` | `risk: 'read'` ↔ `method: 'GET'` |
58
59
  | 面向普通用户的 Agent 只发现显式声明的业务任务；底层 CRUD 不会自动成为任务 | `ai.agent: { visibility: 'task', examples: ['帮我发起报修'], aliases: ['提交报修'] }` |
59
60
  | 任务输入需要地点、人员等业务选择时，绑定同应用的只读辅助操作，用户不填内部编码 | `agent: { visibility: 'task', supportOperations: ['repair.locations'], inputLookups: { location: 'repair.locations' } }`；被引用的 GET 操作须有 `agent: { visibility: 'support' }`，`location` 须是请求 Schema 字段 |
61
+ | 任务完成后显示业务结果卡片 | `agent.resultCard: { title: '报修已提交', fields: [{ path: 'ticketNo', label: '单号' }] }`；`ticketNo` 必须是该操作响应 Schema 中的顶层标量字段，最多 8 项 |
60
62
  | controller 路由必须绑定 `@OpenXiangdaOperation(appOperations.<code>)`，普通 CRUD 不写 controller | check 门禁会拒绝未绑定路由 |
61
63
  | 事务守卫 `errorCode` 必须匹配 `^OPENXIANGDA_[A-Z0-9_]{1,96}$` | `errorCode: 'OPENXIANGDA_REPAIR_REQUEST_NOT_PENDING'` |
62
64
 
package/skills/openxiangda-v2/references/getting-started.md CHANGED
@@ -68,10 +68,10 @@ MCP 服务随项目根包一起安装，AI 客户端的 stdio 连接仍需配置
68
68
  以下命令的版本占位符由随包资料替换为该根包的精确版本。网站源码阅读者应先确认要使用的发行版本。
69
69
 
70
70
  ```bash
71
- pnpm dlx openxiangda@2.31.1 skill install --force
72
- pnpm dlx openxiangda@2.31.1 auth status --base-url <平台地址> --json
73
- pnpm dlx openxiangda@2.31.1 login --cwd my-app --base-url https://platform.example.com
74
- pnpm dlx openxiangda@2.31.1 create my-app --base-url https://platform.example.com
71
+ pnpm dlx openxiangda@2.31.3 skill install --force
72
+ pnpm dlx openxiangda@2.31.3 auth status --base-url <平台地址> --json
73
+ pnpm dlx openxiangda@2.31.3 login --cwd my-app --base-url https://platform.example.com
74
+ pnpm dlx openxiangda@2.31.3 create my-app --base-url https://platform.example.com
75
75
  cd my-app
76
76
  pnpm openxiangda context --json
77
77
  pnpm openxiangda dev
@@ -174,9 +174,9 @@ MCP 的 `docs_read` 可以读取本说明，当前没有独立的源码操作 MC
174
174
  无需本地工作区，使用本 Skill 随包精确版本或已安装的对应 CLI：
175
175
 
176
176
  ```bash
177
- pnpm dlx openxiangda@2.31.1 auth status --base-url <平台> --json
178
- pnpm dlx openxiangda@2.31.1 source resolve <仓库URL> --base-url <平台> --json
179
- pnpm dlx openxiangda@2.31.1 source clone <仓库URL> <新目录> --base-url <平台> --json
177
+ pnpm dlx openxiangda@2.31.3 auth status --base-url <平台> --json
178
+ pnpm dlx openxiangda@2.31.3 source resolve <仓库URL> --base-url <平台> --json
179
+ pnpm dlx openxiangda@2.31.3 source clone <仓库URL> <新目录> --base-url <平台> --json
180
180
  ```
181
181
 
182
182
  登录缺失或站点不匹配时，先按该平台执行 login。resolve 根据平台已经登记的绑定返回