openxiangda 2.31.4 → 2.31.6

package/dist/agent-card.d.ts

@@ -0,0 +1,34 @@
+/** Browser-only bridge for an application card inside the platform's isolated iframe. */
+export declare const AGENT_CARD_PROTOCOL = "openxiangda.agent-card/v1";
+export interface AgentCardField {
+    path: string;
+    label: string;
+    control: 'text' | 'textarea' | 'select';
+    help?: string;
+}
+export interface AgentCardState {
+    mode: 'input' | 'result';
+    title: string;
+    appName: string;
+    fields?: AgentCardField[];
+    partialInput?: Record<string, string>;
+    resultFields?: {
+        label: string;
+        value: string;
+    }[];
+    status?: string;
+}
+export declare function connectAgentCard(onState: (state: AgentCardState) => void): {
+    options: (field: string, keyword?: string) => Promise<{
+        items: {
+            value: string;
+            label: string;
+        }[];
+    }>;
+    submit: (input: Record<string, string>) => Promise<{
+        accepted: boolean;
+    }>;
+    resize: () => void;
+    disconnect: () => void;
+};
+//# sourceMappingURL=agent-card.d.ts.map

package/dist/agent-card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-card.d.ts","sourceRoot":"","sources":["../src/agent-card.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,eAAO,MAAM,mBAAmB,8BAA8B,CAAC;AAE/D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,QAAQ,CAAC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,cAAc,EAAE,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,YAAY,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAiBD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI;qBAoDpD,MAAM,uBAA6D,OAAO,CAAC;QAAE,KAAK,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KAAE,CAAC;oBAC1H,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAqC,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC;;;EAY5G"}

package/dist/agent-card.js

@@ -0,0 +1,85 @@
+/** Browser-only bridge for an application card inside the platform's isolated iframe. */
+export const AGENT_CARD_PROTOCOL = 'openxiangda.agent-card/v1';
+function isMessage(value) {
+    return Boolean(value && typeof value === 'object' &&
+        value.protocol === AGENT_CARD_PROTOCOL);
+}
+export function connectAgentCard(onState) {
+    if (window.parent === window)
+        throw new Error('AGENT_CARD_HOST_REQUIRED');
+    let instanceId = '';
+    let mode = '';
+    let sequence = 0;
+    const pending = new Map();
+    const send = (message) => window.parent.postMessage(message, '*');
+    const resize = () => {
+        if (!instanceId)
+            return;
+        send({ protocol: AGENT_CARD_PROTOCOL, type: 'resize', instanceId,
+            payload: { height: Math.ceil(document.documentElement.scrollHeight) } });
+    };
+    const onMessage = (event) => {
+        if (event.source !== window.parent || !isMessage(event.data))
+            return;
+        const message = event.data;
+        if (message.type === 'state') {
+            if (!message.instanceId || (instanceId && message.instanceId !== instanceId))
+                return;
+            const state = message.payload;
+            if (!state || !['input', 'result'].includes(state.mode))
+                return;
+            instanceId = message.instanceId;
+            mode = state.mode;
+            onState(state);
+            requestAnimationFrame(resize);
+            return;
+        }
+        if (message.type !== 'response' || message.instanceId !== instanceId || !message.requestId)
+            return;
+        const task = pending.get(message.requestId);
+        if (!task)
+            return;
+        pending.delete(message.requestId);
+        window.clearTimeout(task.timer);
+        if (message.error)
+            task.reject(new Error(message.error));
+        else
+            task.resolve(message.payload);
+    };
+    window.addEventListener('message', onMessage);
+    const observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(resize);
+    observer?.observe(document.documentElement);
+    send({ protocol: AGENT_CARD_PROTOCOL, type: 'ready' });
+    const request = (method, payload) => {
+        if (!instanceId)
+            return Promise.reject(new Error('AGENT_CARD_NOT_READY'));
+        if (method === 'submit' && mode !== 'input')
+            return Promise.reject(new Error('AGENT_CARD_READ_ONLY'));
+        if (pending.size >= 4)
+            return Promise.reject(new Error('AGENT_CARD_BUSY'));
+        const requestId = `${Date.now().toString(36)}-${++sequence}`;
+        return new Promise((resolve, reject) => {
+            const timer = window.setTimeout(() => {
+                pending.delete(requestId);
+                reject(new Error('AGENT_CARD_TIMEOUT'));
+            }, 15000);
+            pending.set(requestId, { resolve, reject, timer });
+            send({ protocol: AGENT_CARD_PROTOCOL, type: 'request', instanceId, requestId, method, payload });
+        });
+    };
+    return {
+        options: (field, keyword = '') => request('options', { field, keyword }),
+        submit: (input) => request('submit', { input }),
+        resize,
+        disconnect: () => {
+            window.removeEventListener('message', onMessage);
+            observer?.disconnect();
+            for (const task of pending.values()) {
+                window.clearTimeout(task.timer);
+                task.reject(new Error('AGENT_CARD_DISCONNECTED'));
+            }
+            pending.clear();
+        },
+    };
+}
+//# sourceMappingURL=agent-card.js.map

package/dist/agent-card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-card.js","sourceRoot":"","sources":["../src/agent-card.ts"],"names":[],"mappings":"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"}

package/documentation/agent-cards.md

@@ -0,0 +1,54 @@
+# 应用 Agent 自定义卡片
+
+应用先定义完整业务 operation、当前用户权限、只读参数查询和结果字段，再按需为 `ai.agent.inputCard` 或 `resultCard` 加 `resource`。例如两种卡片都使用同一个脚本：
+
+```ts
+inputCard: { title: '补全报修', resource: 'agent-cards/repair.js', fields: [
+  { path: 'locationId', label: '报修地点', control: 'select' },
+  { path: 'description', label: '故障描述', control: 'textarea' },
+] },
+resultCard: { title: '报修已提交', resource: 'agent-cards/repair.js', fields: [
+  { path: 'ticketNo', label: '单号' }, { path: 'locationName', label: '地点' },
+] },
+```
+
+`resource` 只能是 `agent-cards/*.js` 的相对路径，不能写外部 URL、整站入口或自由 HTML。应用前端构建必须将相同路径放入 `dist/`，`openxiangda deploy` 会核验它确实进入发布包。资源随前端制品摘要与环境 Head 固定，发布/回滚时和业务声明一起切换。标准卡片声明仍是必需的可靠回退路径。
+
+卡片脚本用 `openxiangda/agent-card` 的 `connectAgentCard` SDK 与平台通信：
+
+```tsx
+import { connectAgentCard, type AgentCardState } from 'openxiangda/agent-card';
+
+const bridge = connectAgentCard((state: AgentCardState) => {
+  if (state.mode === 'result') {
+    // 只读展示 state.resultFields。不能调用 submit。
+    return;
+  }
+  // 显示 state.fields、state.partialInput；select 预填仅是搜索线索。
+});
+
+const found = await bridge.options('locationId', '教学楼');
+// 展示 found.items[].label；用户明确选择后提交对应 value。
+await bridge.submit({ locationId: found.items[0].value, description: '空调不制冷' });
+// 卸载时 bridge.disconnect()。
+```
+
+例如使用 Vite 的独立 lib 配置打包成单文件 IIFE，不复用应用 Shell：
+
+```ts
+// apps/web/vite.agent-card.config.ts
+import { defineConfig } from 'vite';
+export default defineConfig({
+  // lib 模式打包 React/Ant Design 时，确保浏览器沙箱内不残留 Node 的 process。
+  define: { 'process.env.NODE_ENV': JSON.stringify('production') },
+  build: { outDir: 'dist', emptyOutDir: false, cssCodeSplit: false,
+    lib: { entry: 'src/agent-card.tsx', name: 'OpenXiangdaRepairCard', formats: ['iife'], fileName: () => 'agent-cards/repair.js' },
+  },
+});
+```
+
+在普通前端构建之后运行 `vite build --config vite.agent-card.config.ts`。产物须小于 2 MiB；构建通过后还须在 `sandbox="allow-scripts"`、无同源权限和 Host CSP 的 iframe 中运行一次真实浏览器测试，确认没有 `process is not defined` 等异常，且能完成 `ready/state/options/submit` 消息往返。卡片样式可由脚本注入在自己的 iframe 内，不应依赖应用全局 CSS、路由、Cookie、登录或平台页面的 DOM。Host 使用无同源权限的 sandbox 和 CSP，只开放 `options` 与 `submit`；SDK 的请求先由 Host 检查卡片实例、声明字段、候选值，再由 Agent 服务端重验用户、应用权限、AppVersion、请求 Schema、Interaction revision 和幂等键。业务 handler 必须再次校验地点等稳定引用。结果卡只收到声明字段的只读投影。
+
+卡片在 8 秒内无法握手、资源缺失或版本变化时，平台显示标准卡片。卡片消息不会修改 Codex 原生 SSE 文本流。这个桥采用与 MCP Apps 相同的资源/宿主调用思路，但首版不是官方 MCP Apps 线级协议；不要在应用里自行实现新工具网关或把 UI 脚本注入平台主页面。
+
+预发验收至少包括：模糊地点出现两个中文候选、明确选中后提交、刷新恢复、双击/双标签只写一次、只读/非成员拒绝、资源缺失降级、结果卡与业务单号回读。普通问答成功或本地构建通过不能替代这些证据。

package/documentation/backend.md

@@ -308,7 +308,7 @@ const enroll = {
 
 `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 的写入确认协议。
+`resultCard` 是已完成任务的只读结果卡片：只允许引用 `responseSchema.properties` 中明确声明的顶层字符串、数字或布尔字段，最多 8 项。应用须确保这些字段可向当前用户显示。填写卡与结果卡可选声明 `resource: 'agent-cards/repair.js'` 使用隔离的应用自定义 UI；未声明或加载失败时保留标准卡片。资源必须是同一前端制品中的单文件 IIFE，`deploy` 会拒绝声明了却未打包的资源。开发 SDK、构建配置和 Host 消息边界见 [应用 Agent 卡片](agent-cards.md)。本声明不改变既有 MCP Facade 的写入确认协议。
 
 业务规则必须在后端操作中验证；提示词、卡片预填和前端校验不能取代权限与业务校验。完整输入、缺失输入、同名地点、权限不足、重复提交和结果未知都应有应用测试与回执核对。任务声明随 AppVersion 的 AI Catalog 一起发布，不能另建手工目录。
 

package/documentation/declarations-cheatsheet.md

@@ -60,6 +60,7 @@
 | 任务输入需要地点、人员等业务选择时，绑定同应用的只读辅助操作，用户不填内部编码 | `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 项 |
+| 应用自定义卡片必须随同一版本发布 | `inputCard` / `resultCard` 可加 `resource: 'agent-cards/repair.js'`；将单文件 IIFE 放进前端 `dist/agent-cards/`，平台隔离加载、失败回退标准卡，详见 `docs agent-cards` |
 | 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.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
+pnpm dlx openxiangda@2.31.6 skill install --force
+pnpm dlx openxiangda@2.31.6 auth status --base-url <平台地址> --json
+pnpm dlx openxiangda@2.31.6 login --cwd my-app --base-url https://platform.example.com
+pnpm dlx openxiangda@2.31.6 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.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
+pnpm dlx openxiangda@2.31.6 auth status --base-url <平台> --json
+pnpm dlx openxiangda@2.31.6 source resolve <仓库URL> --base-url <平台> --json
+pnpm dlx openxiangda@2.31.6 source clone <仓库URL> <新目录> --base-url <平台> --json
 ```
 
 登录缺失或站点不匹配时，先按该平台执行 login。resolve 根据平台已经登记的绑定返回

package/documentation/manifest.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": "openxiangda.documentation/v1",
-  "version": "2.31.4",
+  "version": "2.31.6",
   "topics": [
     {
       "id": "getting-started",
       "title": "安装与开始开发",
       "file": "getting-started.md",
-      "sha256": "1b07231474bab2b4686c851f877b4750d10d4a364998dda7ea20c2937eabad7e"
+      "sha256": "882550d61063b8a6685c4cc2734fb510da651e0e006ec4571f16bd709731a580"
     },
     {
       "id": "product-design",
@@ -36,7 +36,7 @@
       "id": "declarations-cheatsheet",
       "title": "声明速查：一次写对 config",
       "file": "declarations-cheatsheet.md",
-      "sha256": "6fc9ed4bcf30891f436aa2f0af477f4eb5cf834d6bf8c4775345b93207487bbb"
+      "sha256": "726d9e992c16531aef0ee2e8510729d3dd4f2b1320104e39bba9744181946330"
     },
     {
       "id": "application-foundation",
@@ -90,7 +90,13 @@
       "id": "backend",
       "title": "按需后端与业务动作",
       "file": "backend.md",
-      "sha256": "95c0d7da24b08936a809ad042e12c36273873c2052772e2bd6754e8c6d365222"
+      "sha256": "9c76b1fdea29d27a5f52ab057ce621857064a8e5e2ec84ea482d78651dabaa19"
+    },
+    {
+      "id": "agent-cards",
+      "title": "应用 Agent 自定义卡片",
+      "file": "agent-cards.md",
+      "sha256": "e31ec54d319502b47b8f60196e42eba40be61b41e024aee0ae2cc62a78fb79fc"
     },
     {
       "id": "decimal-reservations",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "2.31.4",
+  "version": "2.31.6",
   "description": "OpenXiangda 2.0 的统一命令、应用 SDK、MCP 与中文 AI 技能资料。",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,6 +26,10 @@
       "types": "./dist/react.d.ts",
       "import": "./dist/react.js"
     },
+    "./agent-card": {
+      "types": "./dist/agent-card.d.ts",
+      "import": "./dist/agent-card.js"
+    },
     "./react/styles.css": "./dist/browser/styles.css",
     "./mobile": {
       "types": "./dist/mobile.d.ts",
@@ -60,13 +64,13 @@
     "antd-mobile": "5.42.3",
     "dayjs": "1.11.18",
     "docx-preview": "0.3.7",
-    "openxiangda-cli": "2.6.6",
-    "openxiangda-contracts": "2.31.0",
-    "openxiangda-devkit-core": "2.34.0",
+    "openxiangda-cli": "2.6.8",
+    "openxiangda-contracts": "2.31.1",
+    "openxiangda-devkit-core": "2.34.1",
     "openxiangda-legacy": "npm:openxiangda@1.0.269",
-    "openxiangda-mcp": "2.0.56",
-    "openxiangda-nest": "2.7.9",
-    "openxiangda-skill-kit": "2.3.30",
+    "openxiangda-mcp": "2.0.57",
+    "openxiangda-nest": "2.7.10",
+    "openxiangda-skill-kit": "2.3.32",
     "xlsx": "https://github.com/1377385356/openxiangda/releases/download/vendor-mirror/xlsx-0.20.3.tgz"
   },
   "peerDependencies": {
@@ -132,36 +136,32 @@
   },
   "openxiangdaRelease": {
     "schemaVersion": "openxiangda.release-notes/v1",
-    "version": "2.31.4",
+    "version": "2.31.6",
     "status": "reviewed",
-    "title": "OpenXiangda 2.31.4：业务 Agent 标准填写卡片声明",
-    "summary": "应用任务可以声明有界填写卡片；平台助手在缺少信息或业务选项有歧义时让用户续填，并将提交绑定到已发布的固定业务能力。",
-    "newFeatures": [
-      "backend.operations[].ai.agent.inputCard 支持短文本、多行文本和只读选项，编译器检查必填字段、控件类型、选项响应 Schema 和执行策略。",
-      "开发文档、声明速查表与 AI Skill 同步说明填写卡片、辅助查询和业务 handler 的接入规则。"
+    "title": "OpenXiangda 2.31.6：补充 Agent 卡片浏览器构建规范",
+    "summary": "明确自定义 Agent 卡片的浏览器独立运行要求，防止脚本构建成功但在隔离 iframe 中无法显示。",
+    "newFeatures": [],
+    "fixes": [
+      "Vite 单文件 IIFE 示例明确替换 process.env.NODE_ENV，并要求在无同源 sandbox 与 CSP 下验证卡片握手和提交消息。"
     ],
-    "fixes": [],
     "affectedUsers": [
-      "需要让普通用户在平台助手会话中补齐报修、预约等业务参数的 OpenXiangda 2.0 应用开发者。"
+      "开发应用 Agent 自定义卡片的 OpenXiangda 2.0 应用开发者。"
     ],
     "upgradeSteps": [
-      "升级 openxiangda 并更新锁文件；先实现有权限和幂等保障的业务操作，再为同一操作声明包含全部必填字段的 agent.inputCard。",
-      "选择控件绑定同应用只读辅助操作，响应明确声明最多 20 项的 items[{value,label}]；在预发验证刷新续填、重复提交、权限拒绝和真实业务回读。",
-      "平台服务端、Worker、数据库迁移和会话前端需要配套发布后，填写卡片才会在对话中出现。"
+      "在卡片专用 Vite 配置中加入示例的生产环境替换，重新构建并在隔离浏览器 iframe 中验收。"
     ],
     "knownLimitations": [
-      "首版只有平台标准控件；应用自定义 React 卡片 Host/SDK 是后续独立单元。",
-      "填写卡片只适用于已显式开放、免通用二次确认的普通写任务；破坏性和外部动作仍需独立确认协议。"
+      "本版只补充构建文档；卡片消息桥仍为平台限定协议。"
     ],
     "issues": [],
     "compatibility": {
       "node": ">=24",
       "workspaceGenerations": "v2",
-      "platform": "填写和续接需要配套 Agent Interaction 服务、Worker、SQL 迁移与 SSE 前端。",
+      "platform": "沿用已发布的 Agent Center 卡片资源解析服务和 iframe Host。",
       "v1": "独立 V1 引擎和工作区不受影响。"
     },
-    "sha256": "d025a3b8411a27ab3259f1b3272ff551b3856c9d121f4cb3bdfda9a821760b83",
-    "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.31.4"
+    "sha256": "3e1ffae9d677ad5c0c5e70030f34067bdc76c5751afe7045a77b51d40f641cad",
+    "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.31.6"
   },
   "scripts": {
     "build": "node ../../scripts/prune-package-dist.mjs && tsc -p tsconfig.json && node scripts/copy-assets.mjs",

package/releases/2.31.5.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.31.5",
+  "status": "reviewed",
+  "title": "OpenXiangda 2.31.5：应用 Agent 自定义卡片",
+  "summary": "应用可以把填写卡和结果卡的自定义脚本随同一发布版本交付，由平台在隔离卡片 Host 中展示。",
+  "newFeatures": [
+    "ai.agent.inputCard 和 resultCard 可声明受限的 agent-cards/*.js 资源；发布时核验脚本进入同一前端制品。",
+    "openxiangda/agent-card SDK 提供状态接收、只读选项查询、固定任务提交和尺寸同步；中文开发资料与 Skill 给出构建和验收示例。"
+  ],
+  "fixes": [],
+  "affectedUsers": [
+    "需要在平台业务 Agent 中展示应用自有填写或结果布局的 OpenXiangda 2.0 应用开发者。"
+  ],
+  "upgradeSteps": [
+    "升级 openxiangda 并更新锁文件；保留标准 inputCard/resultCard 字段声明作为资源失败时的回退。",
+    "将使用 SDK 的卡片构建为单文件 IIFE 放入前端 dist/agent-cards/，配置对应 resource，然后运行 check 与预发 deploy。",
+    "确认平台已发布配套 Agent 卡片资源端点与隔离 Host；在预发验证歧义选择、刷新、重复提交、权限拒绝与业务回读。"
+  ],
+  "knownLimitations": [
+    "首版消息桥是平台限定协议，不宣称与官方 MCP Apps 线级兼容；卡片只支持已声明的选项查询和固定提交。",
+    "结果卡只收到已声明的标量字段；复杂列表、附件和额外工具调用仍需后续独立契约。"
+  ],
+  "issues": [],
+  "compatibility": {
+    "node": ">=24",
+    "workspaceGenerations": "v2",
+    "platform": "自定义卡片需要配套 Agent Center 资源解析服务和无同源 iframe Host。",
+    "v1": "独立 V1 引擎和工作区不受影响。"
+  },
+  "sha256": "b674dd23dcb5fc9e00a7af758f01291295c78b8b6756b43d5f678ba79e4df345",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.31.5"
+}

package/releases/2.31.6.json

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.31.6",
+  "status": "reviewed",
+  "title": "OpenXiangda 2.31.6：补充 Agent 卡片浏览器构建规范",
+  "summary": "明确自定义 Agent 卡片的浏览器独立运行要求，防止脚本构建成功但在隔离 iframe 中无法显示。",
+  "newFeatures": [],
+  "fixes": [
+    "Vite 单文件 IIFE 示例明确替换 process.env.NODE_ENV，并要求在无同源 sandbox 与 CSP 下验证卡片握手和提交消息。"
+  ],
+  "affectedUsers": [
+    "开发应用 Agent 自定义卡片的 OpenXiangda 2.0 应用开发者。"
+  ],
+  "upgradeSteps": [
+    "在卡片专用 Vite 配置中加入示例的生产环境替换，重新构建并在隔离浏览器 iframe 中验收。"
+  ],
+  "knownLimitations": [
+    "本版只补充构建文档；卡片消息桥仍为平台限定协议。"
+  ],
+  "issues": [],
+  "compatibility": {
+    "node": ">=24",
+    "workspaceGenerations": "v2",
+    "platform": "沿用已发布的 Agent Center 卡片资源解析服务和 iframe Host。",
+    "v1": "独立 V1 引擎和工作区不受影响。"
+  },
+  "sha256": "3e1ffae9d677ad5c0c5e70030f34067bdc76c5751afe7045a77b51d40f641cad",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.31.6"
+}

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": "4b481cdf01aff0a8c77e4ad7b56fdfb5cda52a7d5127df4493eb4be872138aa7"
+      "sha256": "5b2475f3e5431b5a862399f4b0eb485f0533ac71e73d85d669b1f2d83b65029b"
     }
   ]
 }

package/skills/openxiangda-v2/SKILL.md

@@ -40,10 +40,10 @@ AI 接到新应用、页面或改版任务时，在同一个 OpenXiangda 工作
 未创建工作区时使用本 Skill 随根包发布的精确版本：
 
 ```bash
-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
+pnpm dlx openxiangda@2.31.6 auth status --cwd <应用目录> --base-url <平台地址> --json
+pnpm dlx openxiangda@2.31.6 login --cwd <应用目录> --base-url <平台地址>
+pnpm dlx openxiangda@2.31.6 create <应用目录> --base-url <同一平台地址>
+pnpm dlx openxiangda@2.31.6 skill install --force
 ```
 
 创建前把产品要求的目标平台明确带入命令，不从旧登录态推断站点。已有工作区从原绑定恢复，平台不一致时先解决登录与目标，不改 link 文件跨站创建。
@@ -72,6 +72,7 @@ pnpm dlx openxiangda@2.31.4 skill install --force
 | 审批、待办、消息或事件 | [工作流与通知](references/workflow-events.md) |
 | 自定义事务、校验或外部集成 | [按需后端](references/backend.md) |
 | 向平台业务 Agent 开放任务、辅助查询和字段绑定 | [Agent 任务接入](references/backend.md#面向普通用户的-agent-任务)；先完成业务操作、权限和规则，再声明 `ai.agent` |
+| 为业务 Agent 提供自定义填写/结果卡片 | [Agent 卡片](references/agent-cards.md)；声明同版本资源、使用隔离 SDK，保留平台标准卡片降级 |
 | 主子额度、审批占用释放、撤回修订重提 | [精确金额占用](references/decimal-reservations.md) |
 | 热点读取、抢票、排队、名额预占与原结果恢复 | [缓存、排队与配额](references/managed-concurrency.md) |
 | 报名按钮、表单排队、短确认页、预占倒计时与前端恢复 | [并发前端接入](references/managed-concurrency-frontend.md)：按六种形式选择；仅使用已导出的 API，区分待实现封装 |

package/skills/openxiangda-v2/references/agent-cards.md

@@ -0,0 +1,54 @@
+# 应用 Agent 自定义卡片
+
+应用先定义完整业务 operation、当前用户权限、只读参数查询和结果字段，再按需为 `ai.agent.inputCard` 或 `resultCard` 加 `resource`。例如两种卡片都使用同一个脚本：
+
+```ts
+inputCard: { title: '补全报修', resource: 'agent-cards/repair.js', fields: [
+  { path: 'locationId', label: '报修地点', control: 'select' },
+  { path: 'description', label: '故障描述', control: 'textarea' },
+] },
+resultCard: { title: '报修已提交', resource: 'agent-cards/repair.js', fields: [
+  { path: 'ticketNo', label: '单号' }, { path: 'locationName', label: '地点' },
+] },
+```
+
+`resource` 只能是 `agent-cards/*.js` 的相对路径，不能写外部 URL、整站入口或自由 HTML。应用前端构建必须将相同路径放入 `dist/`，`openxiangda deploy` 会核验它确实进入发布包。资源随前端制品摘要与环境 Head 固定，发布/回滚时和业务声明一起切换。标准卡片声明仍是必需的可靠回退路径。
+
+卡片脚本用 `openxiangda/agent-card` 的 `connectAgentCard` SDK 与平台通信：
+
+```tsx
+import { connectAgentCard, type AgentCardState } from 'openxiangda/agent-card';
+
+const bridge = connectAgentCard((state: AgentCardState) => {
+  if (state.mode === 'result') {
+    // 只读展示 state.resultFields。不能调用 submit。
+    return;
+  }
+  // 显示 state.fields、state.partialInput；select 预填仅是搜索线索。
+});
+
+const found = await bridge.options('locationId', '教学楼');
+// 展示 found.items[].label；用户明确选择后提交对应 value。
+await bridge.submit({ locationId: found.items[0].value, description: '空调不制冷' });
+// 卸载时 bridge.disconnect()。
+```
+
+例如使用 Vite 的独立 lib 配置打包成单文件 IIFE，不复用应用 Shell：
+
+```ts
+// apps/web/vite.agent-card.config.ts
+import { defineConfig } from 'vite';
+export default defineConfig({
+  // lib 模式打包 React/Ant Design 时，确保浏览器沙箱内不残留 Node 的 process。
+  define: { 'process.env.NODE_ENV': JSON.stringify('production') },
+  build: { outDir: 'dist', emptyOutDir: false, cssCodeSplit: false,
+    lib: { entry: 'src/agent-card.tsx', name: 'OpenXiangdaRepairCard', formats: ['iife'], fileName: () => 'agent-cards/repair.js' },
+  },
+});
+```
+
+在普通前端构建之后运行 `vite build --config vite.agent-card.config.ts`。产物须小于 2 MiB；构建通过后还须在 `sandbox="allow-scripts"`、无同源权限和 Host CSP 的 iframe 中运行一次真实浏览器测试，确认没有 `process is not defined` 等异常，且能完成 `ready/state/options/submit` 消息往返。卡片样式可由脚本注入在自己的 iframe 内，不应依赖应用全局 CSS、路由、Cookie、登录或平台页面的 DOM。Host 使用无同源权限的 sandbox 和 CSP，只开放 `options` 与 `submit`；SDK 的请求先由 Host 检查卡片实例、声明字段、候选值，再由 Agent 服务端重验用户、应用权限、AppVersion、请求 Schema、Interaction revision 和幂等键。业务 handler 必须再次校验地点等稳定引用。结果卡只收到声明字段的只读投影。
+
+卡片在 8 秒内无法握手、资源缺失或版本变化时，平台显示标准卡片。卡片消息不会修改 Codex 原生 SSE 文本流。这个桥采用与 MCP Apps 相同的资源/宿主调用思路，但首版不是官方 MCP Apps 线级协议；不要在应用里自行实现新工具网关或把 UI 脚本注入平台主页面。
+
+预发验收至少包括：模糊地点出现两个中文候选、明确选中后提交、刷新恢复、双击/双标签只写一次、只读/非成员拒绝、资源缺失降级、结果卡与业务单号回读。普通问答成功或本地构建通过不能替代这些证据。

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

@@ -308,7 +308,7 @@ const enroll = {
 
 `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 的写入确认协议。
+`resultCard` 是已完成任务的只读结果卡片：只允许引用 `responseSchema.properties` 中明确声明的顶层字符串、数字或布尔字段，最多 8 项。应用须确保这些字段可向当前用户显示。填写卡与结果卡可选声明 `resource: 'agent-cards/repair.js'` 使用隔离的应用自定义 UI；未声明或加载失败时保留标准卡片。资源必须是同一前端制品中的单文件 IIFE，`deploy` 会拒绝声明了却未打包的资源。开发 SDK、构建配置和 Host 消息边界见 [应用 Agent 卡片](agent-cards.md)。本声明不改变既有 MCP Facade 的写入确认协议。
 
 业务规则必须在后端操作中验证；提示词、卡片预填和前端校验不能取代权限与业务校验。完整输入、缺失输入、同名地点、权限不足、重复提交和结果未知都应有应用测试与回执核对。任务声明随 AppVersion 的 AI Catalog 一起发布，不能另建手工目录。
 

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

@@ -60,6 +60,7 @@
 | 任务输入需要地点、人员等业务选择时，绑定同应用的只读辅助操作，用户不填内部编码 | `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 项 |
+| 应用自定义卡片必须随同一版本发布 | `inputCard` / `resultCard` 可加 `resource: 'agent-cards/repair.js'`；将单文件 IIFE 放进前端 `dist/agent-cards/`，平台隔离加载、失败回退标准卡，详见 `docs agent-cards` |
 | 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.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
+pnpm dlx openxiangda@2.31.6 skill install --force
+pnpm dlx openxiangda@2.31.6 auth status --base-url <平台地址> --json
+pnpm dlx openxiangda@2.31.6 login --cwd my-app --base-url https://platform.example.com
+pnpm dlx openxiangda@2.31.6 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.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
+pnpm dlx openxiangda@2.31.6 auth status --base-url <平台> --json
+pnpm dlx openxiangda@2.31.6 source resolve <仓库URL> --base-url <平台> --json
+pnpm dlx openxiangda@2.31.6 source clone <仓库URL> <新目录> --base-url <平台> --json
 ```
 
 登录缺失或站点不匹配时，先按该平台执行 login。resolve 根据平台已经登记的绑定返回