openxiangda 2.31.3 → 2.31.4

package/documentation/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,8 +276,8 @@ 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', properties: {
     ticketNo: { type: 'string' }, locationName: { type: 'string' },
@@ -287,6 +291,10 @@ 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: '地点' },
@@ -298,7 +306,9 @@ const enroll = {
 
 两个 `capability` 必须在 `authz.capabilities` 中声明为 `kind: 'backend'`，再授予相应角色。`supportOperations` 和 `inputLookups` 引用同一应用中的操作 code；被引用操作必须声明 `visibility: 'support'`、`risk: 'read'` 且使用 GET。`inputLookups` 的键必须存在于任务的 `requestSchema.properties`。示例问法最多 12 条、别名最多 20 条、辅助操作最多 12 个、字段绑定最多 32 个；运行时辅助查询仍应分页、有界，并返回业务标签与稳定引用。
 
-`resultCard` 是已完成任务的只读结果卡片：只允许引用 `responseSchema.properties` 中明确声明的顶层字符串、数字或布尔字段，最多 8 项；不渲染任意 HTML/JS。应用须确保这些字段可向当前用户显示。平台助手已支持按应用声明自动执行普通写任务；待补信息表单、自定义 React 卡片 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 一起发布，不能另建手工目录。
 

package/documentation/declarations-cheatsheet.md

@@ -58,6 +58,7 @@
 | 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'` |

package/documentation/getting-started.md

@@ -68,10 +68,10 @@ MCP 服务随项目根包一起安装，AI 客户端的 stdio 连接仍需配置
 以下命令的版本占位符由随包资料替换为该根包的精确版本。网站源码阅读者应先确认要使用的发行版本。
 
 ```bash
-pnpm dlx openxiangda@2.31.3 skill install --force
-pnpm dlx openxiangda@2.31.3 auth status --base-url <平台地址> --json
-pnpm dlx openxiangda@2.31.3 login --cwd my-app --base-url https://platform.example.com
-pnpm dlx openxiangda@2.31.3 create my-app --base-url https://platform.example.com
+pnpm dlx openxiangda@2.31.4 skill install --force
+pnpm dlx openxiangda@2.31.4 auth status --base-url <平台地址> --json
+pnpm dlx openxiangda@2.31.4 login --cwd my-app --base-url https://platform.example.com
+pnpm dlx openxiangda@2.31.4 create my-app --base-url https://platform.example.com
 cd my-app
 pnpm openxiangda context --json
 pnpm openxiangda dev
@@ -174,9 +174,9 @@ MCP 的 `docs_read` 可以读取本说明，当前没有独立的源码操作 MC
 无需本地工作区，使用本 Skill 随包精确版本或已安装的对应 CLI：
 
 ```bash
-pnpm dlx openxiangda@2.31.3 auth status --base-url <平台> --json
-pnpm dlx openxiangda@2.31.3 source resolve <仓库URL> --base-url <平台> --json
-pnpm dlx openxiangda@2.31.3 source clone <仓库URL> <新目录> --base-url <平台> --json
+pnpm dlx openxiangda@2.31.4 auth status --base-url <平台> --json
+pnpm dlx openxiangda@2.31.4 source resolve <仓库URL> --base-url <平台> --json
+pnpm dlx openxiangda@2.31.4 source clone <仓库URL> <新目录> --base-url <平台> --json
 ```
 
 登录缺失或站点不匹配时，先按该平台执行 login。resolve 根据平台已经登记的绑定返回

package/documentation/manifest.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": "openxiangda.documentation/v1",
-  "version": "2.31.3",
+  "version": "2.31.4",
   "topics": [
     {
       "id": "getting-started",
       "title": "安装与开始开发",
       "file": "getting-started.md",
-      "sha256": "9ae7dda856616e44a6c95bb886258a7d1b00f874dbaadff912b27101d5cc3ed0"
+      "sha256": "1b07231474bab2b4686c851f877b4750d10d4a364998dda7ea20c2937eabad7e"
     },
     {
       "id": "product-design",
@@ -36,7 +36,7 @@
       "id": "declarations-cheatsheet",
       "title": "声明速查：一次写对 config",
       "file": "declarations-cheatsheet.md",
-      "sha256": "86c2f4c0d3f47fa0632b5d0aca96c4e2f91d619c44419ce7af8558de97af42dd"
+      "sha256": "6fc9ed4bcf30891f436aa2f0af477f4eb5cf834d6bf8c4775345b93207487bbb"
     },
     {
       "id": "application-foundation",
@@ -90,7 +90,7 @@
       "id": "backend",
       "title": "按需后端与业务动作",
       "file": "backend.md",
-      "sha256": "c134558dcf38562bb86b3ad3fda9788e306b87aa3bcddde37eba78af1db58f2c"
+      "sha256": "95c0d7da24b08936a809ad042e12c36273873c2052772e2bd6754e8c6d365222"
     },
     {
       "id": "decimal-reservations",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "2.31.3",
+  "version": "2.31.4",
   "description": "OpenXiangda 2.0 的统一命令、应用 SDK、MCP 与中文 AI 技能资料。",
   "type": "module",
   "main": "./dist/index.js",
@@ -60,13 +60,13 @@
     "antd-mobile": "5.42.3",
     "dayjs": "1.11.18",
     "docx-preview": "0.3.7",
-    "openxiangda-cli": "2.6.5",
-    "openxiangda-contracts": "2.30.1",
-    "openxiangda-devkit-core": "2.33.1",
+    "openxiangda-cli": "2.6.6",
+    "openxiangda-contracts": "2.31.0",
+    "openxiangda-devkit-core": "2.34.0",
     "openxiangda-legacy": "npm:openxiangda@1.0.269",
-    "openxiangda-mcp": "2.0.55",
-    "openxiangda-nest": "2.7.8",
-    "openxiangda-skill-kit": "2.3.29",
+    "openxiangda-mcp": "2.0.56",
+    "openxiangda-nest": "2.7.9",
+    "openxiangda-skill-kit": "2.3.30",
     "xlsx": "https://github.com/1377385356/openxiangda/releases/download/vendor-mirror/xlsx-0.20.3.tgz"
   },
   "peerDependencies": {
@@ -132,35 +132,36 @@
   },
   "openxiangdaRelease": {
     "schemaVersion": "openxiangda.release-notes/v1",
-    "version": "2.31.3",
+    "version": "2.31.4",
     "status": "reviewed",
-    "title": "OpenXiangda 2.31.3：业务 Agent 结果卡片声明",
-    "summary": "应用任务可以声明已完成操作的只读结果卡片。编译器把展示字段限制在响应 Schema 的顶层标量属性，并将声明随应用版本发布。",
+    "title": "OpenXiangda 2.31.4：业务 Agent 标准填写卡片声明",
+    "summary": "应用任务可以声明有界填写卡片；平台助手在缺少信息或业务选项有歧义时让用户续填，并将提交绑定到已发布的固定业务能力。",
     "newFeatures": [
-      "backend.operations[].ai.agent.resultCard 支持标题和最多 8 个结果字段，并校验字段引用、类型及边界。",
-      "开发文档、速查表与 AI Skill 同步给出结果卡片示例和接入规则。"
+      "backend.operations[].ai.agent.inputCard 支持短文本、多行文本和只读选项，编译器检查必填字段、控件类型、选项响应 Schema 和执行策略。",
+      "开发文档、声明速查表与 AI Skill 同步说明填写卡片、辅助查询和业务 handler 的接入规则。"
     ],
     "fixes": [],
     "affectedUsers": [
-      "需要在平台助手会话中展示预约、报修等业务回执的 OpenXiangda 2.0 应用开发者。"
+      "需要让普通用户在平台助手会话中补齐报修、预约等业务参数的 OpenXiangda 2.0 应用开发者。"
     ],
     "upgradeSteps": [
-      "升级 openxiangda 并更新锁文件；在业务操作的 responseSchema.properties 中声明可展示的标量字段，再可选配置 agent.resultCard。",
-      "在预发验证完整业务结果、字段缺失和刷新恢复；卡片展示需要配套平台服务端与前端版本。"
+      "升级 openxiangda 并更新锁文件；先实现有权限和幂等保障的业务操作，再为同一操作声明包含全部必填字段的 agent.inputCard。",
+      "选择控件绑定同应用只读辅助操作，响应明确声明最多 20 项的 items[{value,label}]；在预发验证刷新续填、重复提交、权限拒绝和真实业务回读。",
+      "平台服务端、Worker、数据库迁移和会话前端需要配套发布后，填写卡片才会在对话中出现。"
     ],
     "knownLimitations": [
-      "本版只定义已完成业务操作的只读结果卡片；待补信息表单、持久 Interaction 与应用自定义 React Host 尚未发布。",
-      "结果卡片不改变应用权限、业务执行或既有 MCP Facade 的确认协议。"
+      "首版只有平台标准控件；应用自定义 React 卡片 Host/SDK 是后续独立单元。",
+      "填写卡片只适用于已显式开放、免通用二次确认的普通写任务；破坏性和外部动作仍需独立确认协议。"
     ],
     "issues": [],
     "compatibility": {
       "node": ">=24",
       "workspaceGenerations": "v2",
-      "platform": "结果卡片呈现需要配套平台 Agent 回执投影和会话前端。",
+      "platform": "填写和续接需要配套 Agent Interaction 服务、Worker、SQL 迁移与 SSE 前端。",
       "v1": "独立 V1 引擎和工作区不受影响。"
     },
-    "sha256": "56e36516118cda6a6d2d4029dc25e593a1b4e76198279cf27cf9e58bf8dc392e",
-    "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.31.3"
+    "sha256": "d025a3b8411a27ab3259f1b3272ff551b3856c9d121f4cb3bdfda9a821760b83",
+    "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.31.4"
   },
   "scripts": {
     "build": "node ../../scripts/prune-package-dist.mjs && tsc -p tsconfig.json && node scripts/copy-assets.mjs",

package/releases/2.31.4.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.31.4",
+  "status": "reviewed",
+  "title": "OpenXiangda 2.31.4：业务 Agent 标准填写卡片声明",
+  "summary": "应用任务可以声明有界填写卡片；平台助手在缺少信息或业务选项有歧义时让用户续填，并将提交绑定到已发布的固定业务能力。",
+  "newFeatures": [
+    "backend.operations[].ai.agent.inputCard 支持短文本、多行文本和只读选项，编译器检查必填字段、控件类型、选项响应 Schema 和执行策略。",
+    "开发文档、声明速查表与 AI Skill 同步说明填写卡片、辅助查询和业务 handler 的接入规则。"
+  ],
+  "fixes": [],
+  "affectedUsers": [
+    "需要让普通用户在平台助手会话中补齐报修、预约等业务参数的 OpenXiangda 2.0 应用开发者。"
+  ],
+  "upgradeSteps": [
+    "升级 openxiangda 并更新锁文件；先实现有权限和幂等保障的业务操作，再为同一操作声明包含全部必填字段的 agent.inputCard。",
+    "选择控件绑定同应用只读辅助操作，响应明确声明最多 20 项的 items[{value,label}]；在预发验证刷新续填、重复提交、权限拒绝和真实业务回读。",
+    "平台服务端、Worker、数据库迁移和会话前端需要配套发布后，填写卡片才会在对话中出现。"
+  ],
+  "knownLimitations": [
+    "首版只有平台标准控件；应用自定义 React 卡片 Host/SDK 是后续独立单元。",
+    "填写卡片只适用于已显式开放、免通用二次确认的普通写任务；破坏性和外部动作仍需独立确认协议。"
+  ],
+  "issues": [],
+  "compatibility": {
+    "node": ">=24",
+    "workspaceGenerations": "v2",
+    "platform": "填写和续接需要配套 Agent Interaction 服务、Worker、SQL 迁移与 SSE 前端。",
+    "v1": "独立 V1 引擎和工作区不受影响。"
+  },
+  "sha256": "d025a3b8411a27ab3259f1b3272ff551b3856c9d121f4cb3bdfda9a821760b83",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.31.4"
+}

package/skills/manifest.json

@@ -4,7 +4,7 @@
     {
       "name": "openxiangda-v2",
       "description": "使用 OpenXiangda 2.0 从模糊业务想法、已有资料或具体变更出发，通过对话发现模块、完成详细产品设计，由当前 AI Agent 按需用 Image 2.5 等图片能力形成视觉参考，直接实现真实页面并在浏览器修正，再检查和交付应用；维护 1.x 应用时使用对应的 1.x 技能。",
-      "sha256": "b47a0088e786fa535c93743c7c063ef0524c1b25f2988e91d2dba12d04e86172"
+      "sha256": "4b481cdf01aff0a8c77e4ad7b56fdfb5cda52a7d5127df4493eb4be872138aa7"
     }
   ]
 }

package/skills/openxiangda-v2/SKILL.md

@@ -40,10 +40,10 @@ AI 接到新应用、页面或改版任务时，在同一个 OpenXiangda 工作
 未创建工作区时使用本 Skill 随根包发布的精确版本：
 
 ```bash
-pnpm dlx openxiangda@2.31.3 auth status --cwd <应用目录> --base-url <平台地址> --json
-pnpm dlx openxiangda@2.31.3 login --cwd <应用目录> --base-url <平台地址>
-pnpm dlx openxiangda@2.31.3 create <应用目录> --base-url <同一平台地址>
-pnpm dlx openxiangda@2.31.3 skill install --force
+pnpm dlx openxiangda@2.31.4 auth status --cwd <应用目录> --base-url <平台地址> --json
+pnpm dlx openxiangda@2.31.4 login --cwd <应用目录> --base-url <平台地址>
+pnpm dlx openxiangda@2.31.4 create <应用目录> --base-url <同一平台地址>
+pnpm dlx openxiangda@2.31.4 skill install --force
 ```
 
 创建前把产品要求的目标平台明确带入命令，不从旧登录态推断站点。已有工作区从原绑定恢复，平台不一致时先解决登录与目标，不改 link 文件跨站创建。

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,8 +276,8 @@ 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', properties: {
     ticketNo: { type: 'string' }, locationName: { type: 'string' },
@@ -287,6 +291,10 @@ 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: '地点' },
@@ -298,7 +306,9 @@ const enroll = {
 
 两个 `capability` 必须在 `authz.capabilities` 中声明为 `kind: 'backend'`，再授予相应角色。`supportOperations` 和 `inputLookups` 引用同一应用中的操作 code；被引用操作必须声明 `visibility: 'support'`、`risk: 'read'` 且使用 GET。`inputLookups` 的键必须存在于任务的 `requestSchema.properties`。示例问法最多 12 条、别名最多 20 条、辅助操作最多 12 个、字段绑定最多 32 个；运行时辅助查询仍应分页、有界，并返回业务标签与稳定引用。
 
-`resultCard` 是已完成任务的只读结果卡片：只允许引用 `responseSchema.properties` 中明确声明的顶层字符串、数字或布尔字段，最多 8 项；不渲染任意 HTML/JS。应用须确保这些字段可向当前用户显示。平台助手已支持按应用声明自动执行普通写任务；待补信息表单、自定义 React 卡片 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 一起发布，不能另建手工目录。
 

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

@@ -58,6 +58,7 @@
 | 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'` |

package/skills/openxiangda-v2/references/getting-started.md

@@ -68,10 +68,10 @@ MCP 服务随项目根包一起安装，AI 客户端的 stdio 连接仍需配置
 以下命令的版本占位符由随包资料替换为该根包的精确版本。网站源码阅读者应先确认要使用的发行版本。
 
 ```bash
-pnpm dlx openxiangda@2.31.3 skill install --force
-pnpm dlx openxiangda@2.31.3 auth status --base-url <平台地址> --json
-pnpm dlx openxiangda@2.31.3 login --cwd my-app --base-url https://platform.example.com
-pnpm dlx openxiangda@2.31.3 create my-app --base-url https://platform.example.com
+pnpm dlx openxiangda@2.31.4 skill install --force
+pnpm dlx openxiangda@2.31.4 auth status --base-url <平台地址> --json
+pnpm dlx openxiangda@2.31.4 login --cwd my-app --base-url https://platform.example.com
+pnpm dlx openxiangda@2.31.4 create my-app --base-url https://platform.example.com
 cd my-app
 pnpm openxiangda context --json
 pnpm openxiangda dev
@@ -174,9 +174,9 @@ MCP 的 `docs_read` 可以读取本说明，当前没有独立的源码操作 MC
 无需本地工作区，使用本 Skill 随包精确版本或已安装的对应 CLI：
 
 ```bash
-pnpm dlx openxiangda@2.31.3 auth status --base-url <平台> --json
-pnpm dlx openxiangda@2.31.3 source resolve <仓库URL> --base-url <平台> --json
-pnpm dlx openxiangda@2.31.3 source clone <仓库URL> <新目录> --base-url <平台> --json
+pnpm dlx openxiangda@2.31.4 auth status --base-url <平台> --json
+pnpm dlx openxiangda@2.31.4 source resolve <仓库URL> --base-url <平台> --json
+pnpm dlx openxiangda@2.31.4 source clone <仓库URL> <新目录> --base-url <平台> --json
 ```
 
 登录缺失或站点不匹配时，先按该平台执行 login。resolve 根据平台已经登记的绑定返回