openxiangda 2.66.2 → 2.67.1

package/documentation/application-agents.md

@@ -0,0 +1,72 @@
+# 应用内置助手
+
+应用助手的定义属于应用源码，随 AppVersion 激活和回滚；模型连接、配额和运行开关由平台维护。它不是租户平台助手，也不替代应用自己的后台。布局和卡片使用应用源码，登录、权限与命令仍由平台拥有。
+
+本专题对应新增的 `openxiangda/agent` 源码能力。使用前核对实际安装版本的公开导出和平台配对能力；本轮开发没有执行 npm 发布。可复制助手模板、`agent eval`、真实模型与真实角色的访客验收尚未闭合，不能据此声明应用助手已经交付。
+
+## 接入
+
+在现有应用路由与 RuntimeBoundary 内使用 hooks，不新增 router、登录存储、平台代理或业务数据库：
+
+```tsx
+import { useAgents, useAgentConversation } from 'openxiangda/agent';
+
+export function ApplicationAssistant() {
+  const catalog = useAgents();
+  const assistant = useAgentConversation('assistant');
+  const busy = Boolean(assistant.pending || assistant.snapshot?.conversation.activeRunId);
+  // 使用 catalog.agents 中该助手的 name/purpose/starters/available/reason。
+  // 展示 assistant.snapshot.messages，content 是完整文本，不是 token delta。
+  // 用户主动点击才调用 newConversation/send；挂载和 reload 只读恢复。
+  return <div>
+    {catalog.error && <p role="alert">暂时无法获取助手</p>}
+    {assistant.pending?.state === 'unknown' && <p role="alert">原请求结果尚不确定，请先核对，不要重复提交。</p>}
+    <button disabled={busy} onClick={() => void assistant.send('今天有哪些来访').catch(() => {})}>查询今日来访</button>
+    <button onClick={() => void assistant.recover().catch(() => {})}>核对原请求</button>
+  </div>;
+}
+```
+
+助手声明及任务编译规则见源码架构记录和配置类型 `defineApplicationAgent`。客户端不接受 appCode、environmentKey、actor、provider、baseUrl 或 API key；它使用当前已登录用户和角色并集，绑定 RuntimeBoundary 的身份及环境。退出或身份变化时销毁旧请求、流和可见快照。
+
+不使用 React hooks 的现有应用组件可调用 `createApplicationAgentClient()`，随后 `client.agents()`、`client.conversations(agentCode)`、`client.conversation(agentCode)`。观察器 `subscribe/snapshot` 可供自定义组件使用；离开时 `client.dispose()`。不能在匿名页面或未建立 RuntimeBoundary 身份时创建客户端。
+
+## 写入与卡片
+
+用户主动操作时客户端生成 UUID，填写/确认携带原卡片 revision。同一观察器只允许一项待处理写入。以下调用不绕过服务端的能力、记录修订与当前角色检查：
+
+```ts
+await assistant.submitInteraction(card.id, card.revision, {
+  visitorName: '张伟',
+  count: 2,
+  needsParking: false,
+  company: null, // 显式清空；未触及字段直接省略。
+});
+await assistant.confirm(confirmation.id, confirmation.revision);
+await assistant.cancelInteraction(card.id);
+await assistant.cancel(run.id);
+await assistant.reconcile(tool.id); // 只读核对业务执行所有者的原回执。
+// 仅供平台允许的人工核实人员；服务器仍验证权限并保留人工来源：
+await assistant.resolveManually(tool.id, 'not_executed', '已核对业务系统，没有对应记录');
+```
+
+卡片编辑和候选查询必须复用公开 Field Kit 与字段自己的 lookup。headless 客户端不把 reference/user/date/number 转成字符串，不合并旧 partialInput，不定义第二套候选权威。确认是独立明确按钮，不应绑定到自动回复或隐藏脚本。
+
+## 结果不确定与只读恢复
+
+- 断网、408、5xx 或丢失响应后保留 `pending.state = unknown`，不自动重放，也不静默生成新键。
+- `recover()` 查询原创建 requestId 或当前会话快照。没有找到原结果不等于未执行，继续阻止新写。
+- 快照/事件读回同一请求关联后，`lastResolution.disposition = acknowledged` 仅表示平台已处理这项请求，不代表业务成功。业务执行成功仍要看业务工具回执，并实际读回记录。
+- 另一请求推进卡片状态/修订时，旧意图只能标记 `closed`，不能宣称本次提交成功。
+- `still_unknown` 不是失败、更不是成功。应用只提供核对和已有权限下的人工核实入口，不自动执行原业务写入。
+- sessionStorage 只保存当前身份、应用、环境作用域的会话指针和原请求/卡片 ID，不保存文本、字段值、凭据或模型连接。存储不可用时 `persistence = memory`；刷新后应从历史和平台回执核对，不能假装仍有完整恢复证据。
+
+## 流和页面生命周期
+
+应用只收到 `conversation/run/message/tool/interaction.updated` 五类中性更新。消息按 ID 替换完整文本；不解析平台引擎通知。游标使用安全整数 durable seq，重复帧去重，缺失序列先重新读取一致快照。
+
+断线后初次连接之外最多三次只读续接，失败后显示 `stream = disconnected`，由用户刷新观察器。idle/heartbeat 只是传输控制帧，不是业务成功。frame 与剩余 buffer 各限制 2 MiB。卸载、退出、身份变化会中止 fetch 和 reader，不增加平台流额度。
+
+## 验收不能混用
+
+SDK 单测、类型与 affected gates 证明客户端契约，不证明可用的业务应用。交付仍需已激活的测试 AppVersion、已启用 worker 和真实模型连接、真实角色拒绝、PC/移动浏览器、断线恢复及实际业务记录读回。Connected dev 使用已激活测试版本的助手；未激活的本地 overlay 不属于 worker 定义。

package/documentation/getting-started.md

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

package/documentation/manifest.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": "openxiangda.documentation/v1",
-  "version": "2.66.2",
+  "version": "2.67.1",
   "topics": [
     {
       "id": "getting-started",
       "title": "安装与开始开发",
       "file": "getting-started.md",
-      "sha256": "bbdfdd1435d655230451a63c5fcfed10d1937e53d7f87c0ff02cc92d748d754a"
+      "sha256": "9c67e9b8af67d65d515208f07614104d4a05b694921a75dcade93be3fd783846"
     },
     {
       "id": "product-design",
@@ -104,6 +104,12 @@
       "file": "agent-cards.md",
       "sha256": "e31ec54d319502b47b8f60196e42eba40be61b41e024aee0ae2cc62a78fb79fc"
     },
+    {
+      "id": "application-agents",
+      "title": "应用内置助手与安全恢复",
+      "file": "application-agents.md",
+      "sha256": "b64cd32aa23a146101affc70f9d26f30cb80f161edfd5c72157fe93fbdabb1d3"
+    },
     {
       "id": "decimal-reservations",
       "title": "主子记录精确金额占用",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "2.66.2",
+  "version": "2.67.1",
   "description": "OpenXiangda 2.0 的统一命令、应用 SDK、MCP 与中文 AI 技能资料。",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,6 +38,10 @@
       "types": "./dist/agent-card.d.ts",
       "import": "./dist/agent-card.js"
     },
+    "./agent": {
+      "types": "./dist/agent.d.ts",
+      "import": "./dist/agent.js"
+    },
     "./react/styles.css": "./dist/browser/styles.css",
     "./mobile": {
       "types": "./dist/mobile.d.ts",
@@ -91,13 +95,13 @@
     "dayjs": "1.11.18",
     "docx-preview": "0.3.7",
     "elkjs": "0.12.0",
-    "openxiangda-cli": "2.10.2",
-    "openxiangda-contracts": "2.84.0",
-    "openxiangda-devkit-core": "2.63.1",
+    "openxiangda-cli": "2.10.4",
+    "openxiangda-contracts": "2.85.0",
+    "openxiangda-devkit-core": "2.63.3",
     "openxiangda-legacy": "npm:openxiangda@1.0.269",
-    "openxiangda-mcp": "2.2.6",
-    "openxiangda-nest": "2.19.1",
-    "openxiangda-skill-kit": "2.3.108",
+    "openxiangda-mcp": "2.2.8",
+    "openxiangda-nest": "2.19.2",
+    "openxiangda-skill-kit": "2.3.110",
     "xlsx": "https://github.com/1377385356/openxiangda/releases/download/vendor-mirror/xlsx-0.20.3.tgz"
   },
   "peerDependencies": {
@@ -163,32 +167,38 @@
   },
   "openxiangdaRelease": {
     "schemaVersion": "openxiangda.release-notes/v1",
-    "version": "2.66.2",
+    "version": "2.67.1",
     "status": "reviewed",
-    "title": "工具链事实契约兼容修复",
-    "summary": "保持现有 worker-effect 能力，并修复工作区工具链事实的公开契约。",
+    "title": "应用Agent及worker声明与发行恢复修复",
+    "summary": "新增作用域内应用Agent客户端，并补齐事件worker编译上下文及节点条件配置契约。",
     "newFeatures": [
-      "事件消费者支持受限查询、冻结事务、原键提交与回执恢复；平台统一执行并验证事件租约。"
+      "公开openxiangda/agent客户端与hooks，沿用平台当前身份和持久游标，未知写入不自动重放。"
     ],
     "fixes": [
-      "允许工作区上下文返回已安装工具链事实。"
+      "worker-effect编译传入显式emitEventTypes与实际工作流subject，避免合法声明被误拒绝。",
+      "配置类型公开worker-effect执行声明，避免应用使用类型绕过。",
+      "共享节点人员配置支持完整条件规则与权威来源边界。",
+      "声明warning保持警告，真正错误仍阻断，避免正确应用被误拒绝。",
+      "Git worktree发行计划、验证与发布共用冻结制品、回执和进程锁；发现旧私有回执时先恢复原状态。"
     ],
     "affectedUsers": [
-      "需要定时业务事务的 OpenXiangda V2 应用开发者与平台维护者。"
+      "OpenXiangda V2应用开发者和平台维护者"
     ],
     "upgradeSteps": [
-      "配对升级 SDK、CLI、共享契约和平台服务；为事件订阅显式声明 worker-effect 资源、字段及容量。"
+      "按同批版本升级工具链，重新生成并检查应用契约。",
+      "配套升级平台共享契约后验证TEST，真实角色验收独立执行。"
     ],
     "knownLimitations": [
-      "投递至少一次，业务事务依赖原幂等意图去重；不允许工作流拥有的资源写入或任意业务身份冒用。"
+      "事件至少一次投递，依赖原业务意图和平台回执去重。",
+      "工具链发布不代表学校平台部署或应用业务验收完成。"
     ],
     "compatibility": {
       "node": ">=24",
       "pnpm": "10.15.1"
     },
     "issues": [],
-    "sha256": "f597de89ed6ca7b7270427f35e2d9078576f1ee3ec06f961cd09b65e5298ebb8",
-    "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.66.2"
+    "sha256": "cab78d0c354ccfe6373966f884c475e4e50e0096a5cbe9763fce2a761ba99e99",
+    "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.67.1"
   },
   "scripts": {
     "build": "node ../../scripts/prune-package-dist.mjs && tsc -p tsconfig.json && node scripts/copy-assets.mjs",

package/releases/2.63.0.json

@@ -0,0 +1,45 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.63.0",
+  "status": "reviewed",
+  "title": "Workflow design, handling nodes and editable application templates",
+  "summary": "Publish the reviewed mainline workflow designer and handling capabilities, shared-record Save, structured parallel branches and guarded workflow source synchronisation. Add editable templates, resource reference read/update contexts and read-only AI command reconciliation. The platform must use the same public contracts 2.79.0 pure compiler as the SDK.",
+  "newFeatures": [
+    "Canonical workflow designer definitions, target/variable catalogs, administration, proposals and instance adoption share the same pure validation rules.",
+    "Independent handling and correction nodes support explicit completion actions, opinion requirements, shared-record Save, return policies, durable reminders, platform notifications and supervisor-chain assignments.",
+    "Paired parallel/join nodes have bounded disjoint branches, branch-scoped position proofs and publication validation while retaining immutable task-entry authority.",
+    "Workflow source export/import, read-only version registration plans and environment synchronisation use digest and target-head guards and preserve prepared version history.",
+    "Editable application templates cover administration, PC, mobile and login frames, with shared resource-page controllers, source digests and composition validation.",
+    "Resource reference filtering has an independent read intent; ordinary edits supply saved-record id/revision and actual edits for authoritative server-side merge.",
+    "AI reconciliation binds a read-only GET/read operation to the original command receipt instead of replaying a business mutation."
+  ],
+  "fixes": [
+    "Give the new workflow pure-rule APIs a fresh public contracts version so platforms need not privately add exports under an already published semver.",
+    "Correct canvas branch selection, outline hierarchy and approval action presentation while retaining permissions, CAS, idempotency and unknown-result recovery.",
+    "Export standard resource query, cascade and address helpers from shared contracts so browser and platform consumers use the same query semantics."
+  ],
+  "affectedUsers": [
+    "OpenXiangda V2 platforms and applications using workflow design, independent handling, shared Save, reminders, notifications or instance adoption.",
+    "V2 workspaces using editable template composition, resource reference fields or read-only AI result reconciliation."
+  ],
+  "upgradeSteps": [
+    "Deploy a platform matching the actual contracts 2.79.0 native validator first. Server contracts must come from the official published tarball with verified SRI.",
+    "Upgrade the complete workspace distribution to public openxiangda 2.63.0, install the lockfile and refresh project documentation and MCP sessions.",
+    "Preserve application, record, task, workflow-version and idempotency identities. Run normal check/deploy preflight against the actual platform capabilities and validator digest.",
+    "Verify workflow design, shared Save, handling completion, return paths, notification recipients and reference reads/updates with real roles before environment promotion."
+  ],
+  "knownLimitations": [
+    "New reference contexts and workflow contracts require the matching platform to be deployed first; declaring a different digest does not establish compatibility.",
+    "Template appearance and package regressions do not replace real-role, notification, instance-adoption and business-data acceptance.",
+    "The separate event-receipt lease-ownership and worker-effect candidates are not included in this public release."
+  ],
+  "compatibility": {
+    "generation": "v2",
+    "node": ">=24",
+    "platform": "contracts 2.79.0 exact native validator and matching workflow/resource contexts",
+    "v1": "Independent 1.x maintenance distribution is unchanged"
+  },
+  "issues": [],
+  "sha256": "ef4279a6f846a604d68dbd1adc2473203ffef4287e2dc74b51aa17727a7397b5",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.63.0"
+}

package/releases/2.63.1.json

@@ -0,0 +1,46 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.63.1",
+  "status": "reviewed",
+  "title": "流程设计、独立办理与公开契约配套发行",
+  "summary": "正式发行已评审的流程设计、办理节点、共享数据保存、结构化并行、提醒通知和流程源码同步能力，提供可编辑应用模板、资源引用读取上下文及只读 AI 回执核对，同时修复首次导入前的源基线比较和配置写入边界。公开 SDK 与 contracts 2.79.1 使用同一冻结分发。",
+  "newFeatures": [
+    "流程设计、变量和目标目录、管理员配置、设计提案及历史实例接管共用规范定义与纯校验规则。",
+    "独立办理与补正节点支持明确完成动作、意见要求、共享数据保存、退回策略、持久提醒、平台通知和主管链规则。",
+    "结构化 parallel/join 节点支持有界独立分支、分支位置证明及发布校验，保留任务进入时的权威事实。",
+    "流程源码导出、导入、版本注册和环境同步使用源摘要及目标版本守卫，保留准备版本历史。",
+    "可编辑模板覆盖后台、PC、移动端和登录外观，资源页控制器、来源摘要及组合校验共用标准边界。",
+    "资源引用筛选使用独立读取意图；普通关联编辑提供记录 id/revision 和实际编辑上下文，由平台合并权威绑定。",
+    "AI 核对通过只读 GET/read 查询原幂等键的提交回执，不重新执行业务命令。"
+  ],
+  "fixes": [
+    "首次导入前按目标应用声明比较流程源状态，忽略其他环境观察，复用规范摘要、校验源锁并将写入限定于应用导出的配置。",
+    "并行分支卡片居中且条件开关保持单行，审批布局继续保留权限、CAS、幂等和未知结果恢复。",
+    "新增流程规则使用正式公开 contracts 新版本，不在已公开旧版本号下私有添加 API。",
+    "封包清单正确检查 template/list 命令，参考候选仓库支持显式任务代理访问官方上游。"
+  ],
+  "affectedUsers": [
+    "使用流程设计、独立办理、共享保存、提醒通知、流程源同步或历史实例接管的 OpenXiangda 2.0 平台和应用。",
+    "使用可编辑模板、资源引用字段或只读 AI 结果核对的 2.0 工作区。"
+  ],
+  "upgradeSteps": [
+    "先部署与 contracts 2.79.1 实际纯规则摘要一致的平台；服务器使用官方公开 tarball 并核对 SRI。",
+    "完整工作区分发升级到 openxiangda 2.63.1，按锁文件安装并刷新资料及 MCP 连接。",
+    "保留原应用、数据、任务、流程版本和幂等标识，正常 check/deploy 核对实际能力与 validatorDigest。",
+    "按真实角色验证设计、保存、办理完成、退回、通知收件人及关联字段读写，再执行原晋级流程。"
+  ],
+  "knownLimitations": [
+    "新增读取上下文和流程契约需要配套平台先升级，修改摘要不能代替真实兼容性。",
+    "包测试和模板外观不代替真实角色、通知、实例接管及业务数据读回验收。",
+    "事件回执租约对象归属和 Worker 原子效果仍为独立 PLT-040 候选，本次不包含未整合改动。"
+  ],
+  "compatibility": {
+    "generation": "v2",
+    "node": ">=24",
+    "platform": "contracts 2.79.1 exact native validator and matching workflow/resource contexts",
+    "v1": "独立 1.x 维护分发不变"
+  },
+  "issues": [],
+  "sha256": "364565fc1ab2b4a1db89328b684ca7f5d1b261ad882e00e5da7c1687e5be7861",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.63.1"
+}

package/releases/2.66.0.json

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.66.0",
+  "status": "reviewed",
+  "title": "受限事件后台事务能力",
+  "summary": "复用平台事件投递租约及持久回执，支持定时消费者以显式资源与字段授权执行 Native 事务。",
+  "newFeatures": [
+    "事件消费者支持受限查询、冻结事务、原键提交与回执恢复；平台统一执行并验证事件租约。"
+  ],
+  "fixes": [
+    "迟到消费者只能释放自身租约，不能覆盖新消费者处理权。"
+  ],
+  "affectedUsers": [
+    "需要定时业务事务的 OpenXiangda V2 应用开发者与平台维护者。"
+  ],
+  "upgradeSteps": [
+    "配对升级 SDK、CLI、共享契约和平台服务；为事件订阅显式声明 worker-effect 资源、字段及容量。"
+  ],
+  "knownLimitations": [
+    "投递至少一次，业务事务依赖原幂等意图去重；不允许工作流拥有的资源写入或任意业务身份冒用。"
+  ],
+  "compatibility": {
+    "node": ">=24",
+    "pnpm": "10.15.1"
+  },
+  "issues": [],
+  "sha256": "48c557ed1f5420f31b352721b05fc769d2f728c84102da0705eca9553844532a",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.66.0"
+}

package/releases/2.66.1.json

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.66.1",
+  "status": "reviewed",
+  "title": "事件 worker-effect SDK 导出修复",
+  "summary": "保持 2.66.0 worker-effect 能力，并修复根包 Nest 入口导出缺失。",
+  "newFeatures": [
+    "事件消费者支持受限查询、冻结事务、原键提交与回执恢复；平台统一执行并验证事件租约。"
+  ],
+  "fixes": [
+    "公开 Nest 入口补充导出事件 worker-effect 服务。"
+  ],
+  "affectedUsers": [
+    "需要定时业务事务的 OpenXiangda V2 应用开发者与平台维护者。"
+  ],
+  "upgradeSteps": [
+    "配对升级 SDK、CLI、共享契约和平台服务；为事件订阅显式声明 worker-effect 资源、字段及容量。"
+  ],
+  "knownLimitations": [
+    "投递至少一次，业务事务依赖原幂等意图去重；不允许工作流拥有的资源写入或任意业务身份冒用。"
+  ],
+  "compatibility": {
+    "node": ">=24",
+    "pnpm": "10.15.1"
+  },
+  "issues": [],
+  "sha256": "bf5cc01bff98c34817ba998f822f74561f8d4d44da121229b5e585654cba13c0",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.66.1"
+}

package/releases/2.67.0.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.67.0",
+  "status": "reviewed",
+  "title": "应用Agent接口与事件worker声明修复",
+  "summary": "新增作用域内应用Agent客户端，并补齐事件worker编译上下文及节点条件配置契约。",
+  "newFeatures": [
+    "公开openxiangda/agent客户端与hooks，沿用平台当前身份和持久游标，未知写入不自动重放。"
+  ],
+  "fixes": [
+    "worker-effect编译传入显式emitEventTypes与实际工作流subject，避免合法声明被误拒绝。",
+    "配置类型公开worker-effect执行声明，避免应用使用类型绕过。",
+    "共享节点人员配置支持完整条件规则与权威来源边界。"
+  ],
+  "affectedUsers": [
+    "OpenXiangda V2应用开发者和平台维护者"
+  ],
+  "upgradeSteps": [
+    "按同批版本升级工具链，重新生成并检查应用契约。",
+    "配套升级平台共享契约后验证TEST，真实角色验收独立执行。"
+  ],
+  "knownLimitations": [
+    "事件至少一次投递，依赖原业务意图和平台回执去重。",
+    "工具链发布不代表学校平台部署或应用业务验收完成。"
+  ],
+  "compatibility": {
+    "node": ">=24",
+    "pnpm": "10.15.1"
+  },
+  "issues": [],
+  "sha256": "535f00f729995cc1f8ce0925c3ddbd5976e1ed6283ef60d2888955ae95393d02",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.67.0"
+}

package/releases/2.67.1.json

@@ -0,0 +1,35 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.67.1",
+  "status": "reviewed",
+  "title": "应用Agent及worker声明与发行恢复修复",
+  "summary": "新增作用域内应用Agent客户端，并补齐事件worker编译上下文及节点条件配置契约。",
+  "newFeatures": [
+    "公开openxiangda/agent客户端与hooks，沿用平台当前身份和持久游标，未知写入不自动重放。"
+  ],
+  "fixes": [
+    "worker-effect编译传入显式emitEventTypes与实际工作流subject，避免合法声明被误拒绝。",
+    "配置类型公开worker-effect执行声明，避免应用使用类型绕过。",
+    "共享节点人员配置支持完整条件规则与权威来源边界。",
+    "声明warning保持警告，真正错误仍阻断，避免正确应用被误拒绝。",
+    "Git worktree发行计划、验证与发布共用冻结制品、回执和进程锁；发现旧私有回执时先恢复原状态。"
+  ],
+  "affectedUsers": [
+    "OpenXiangda V2应用开发者和平台维护者"
+  ],
+  "upgradeSteps": [
+    "按同批版本升级工具链，重新生成并检查应用契约。",
+    "配套升级平台共享契约后验证TEST，真实角色验收独立执行。"
+  ],
+  "knownLimitations": [
+    "事件至少一次投递，依赖原业务意图和平台回执去重。",
+    "工具链发布不代表学校平台部署或应用业务验收完成。"
+  ],
+  "compatibility": {
+    "node": ">=24",
+    "pnpm": "10.15.1"
+  },
+  "issues": [],
+  "sha256": "cab78d0c354ccfe6373966f884c475e4e50e0096a5cbe9763fce2a761ba99e99",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.67.1"
+}

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": "bcb6d93ae6a05e79cd9c5ff2bcdd05784b6a919a6dc2c9ec4103d3323d2daf7f"
+      "sha256": "51a121930a814af65f0902f9dbfd240ef2194131cf40a7f6bcbd3129ac4bfb4e"
     }
   ]
 }

package/skills/openxiangda-v2/SKILL.md

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

package/skills/openxiangda-v2/references/application-agents.md

@@ -0,0 +1,72 @@
+# 应用内置助手
+
+应用助手的定义属于应用源码，随 AppVersion 激活和回滚；模型连接、配额和运行开关由平台维护。它不是租户平台助手，也不替代应用自己的后台。布局和卡片使用应用源码，登录、权限与命令仍由平台拥有。
+
+本专题对应新增的 `openxiangda/agent` 源码能力。使用前核对实际安装版本的公开导出和平台配对能力；本轮开发没有执行 npm 发布。可复制助手模板、`agent eval`、真实模型与真实角色的访客验收尚未闭合，不能据此声明应用助手已经交付。
+
+## 接入
+
+在现有应用路由与 RuntimeBoundary 内使用 hooks，不新增 router、登录存储、平台代理或业务数据库：
+
+```tsx
+import { useAgents, useAgentConversation } from 'openxiangda/agent';
+
+export function ApplicationAssistant() {
+  const catalog = useAgents();
+  const assistant = useAgentConversation('assistant');
+  const busy = Boolean(assistant.pending || assistant.snapshot?.conversation.activeRunId);
+  // 使用 catalog.agents 中该助手的 name/purpose/starters/available/reason。
+  // 展示 assistant.snapshot.messages，content 是完整文本，不是 token delta。
+  // 用户主动点击才调用 newConversation/send；挂载和 reload 只读恢复。
+  return <div>
+    {catalog.error && <p role="alert">暂时无法获取助手</p>}
+    {assistant.pending?.state === 'unknown' && <p role="alert">原请求结果尚不确定，请先核对，不要重复提交。</p>}
+    <button disabled={busy} onClick={() => void assistant.send('今天有哪些来访').catch(() => {})}>查询今日来访</button>
+    <button onClick={() => void assistant.recover().catch(() => {})}>核对原请求</button>
+  </div>;
+}
+```
+
+助手声明及任务编译规则见源码架构记录和配置类型 `defineApplicationAgent`。客户端不接受 appCode、environmentKey、actor、provider、baseUrl 或 API key；它使用当前已登录用户和角色并集，绑定 RuntimeBoundary 的身份及环境。退出或身份变化时销毁旧请求、流和可见快照。
+
+不使用 React hooks 的现有应用组件可调用 `createApplicationAgentClient()`，随后 `client.agents()`、`client.conversations(agentCode)`、`client.conversation(agentCode)`。观察器 `subscribe/snapshot` 可供自定义组件使用；离开时 `client.dispose()`。不能在匿名页面或未建立 RuntimeBoundary 身份时创建客户端。
+
+## 写入与卡片
+
+用户主动操作时客户端生成 UUID，填写/确认携带原卡片 revision。同一观察器只允许一项待处理写入。以下调用不绕过服务端的能力、记录修订与当前角色检查：
+
+```ts
+await assistant.submitInteraction(card.id, card.revision, {
+  visitorName: '张伟',
+  count: 2,
+  needsParking: false,
+  company: null, // 显式清空；未触及字段直接省略。
+});
+await assistant.confirm(confirmation.id, confirmation.revision);
+await assistant.cancelInteraction(card.id);
+await assistant.cancel(run.id);
+await assistant.reconcile(tool.id); // 只读核对业务执行所有者的原回执。
+// 仅供平台允许的人工核实人员；服务器仍验证权限并保留人工来源：
+await assistant.resolveManually(tool.id, 'not_executed', '已核对业务系统，没有对应记录');
+```
+
+卡片编辑和候选查询必须复用公开 Field Kit 与字段自己的 lookup。headless 客户端不把 reference/user/date/number 转成字符串，不合并旧 partialInput，不定义第二套候选权威。确认是独立明确按钮，不应绑定到自动回复或隐藏脚本。
+
+## 结果不确定与只读恢复
+
+- 断网、408、5xx 或丢失响应后保留 `pending.state = unknown`，不自动重放，也不静默生成新键。
+- `recover()` 查询原创建 requestId 或当前会话快照。没有找到原结果不等于未执行，继续阻止新写。
+- 快照/事件读回同一请求关联后，`lastResolution.disposition = acknowledged` 仅表示平台已处理这项请求，不代表业务成功。业务执行成功仍要看业务工具回执，并实际读回记录。
+- 另一请求推进卡片状态/修订时，旧意图只能标记 `closed`，不能宣称本次提交成功。
+- `still_unknown` 不是失败、更不是成功。应用只提供核对和已有权限下的人工核实入口，不自动执行原业务写入。
+- sessionStorage 只保存当前身份、应用、环境作用域的会话指针和原请求/卡片 ID，不保存文本、字段值、凭据或模型连接。存储不可用时 `persistence = memory`；刷新后应从历史和平台回执核对，不能假装仍有完整恢复证据。
+
+## 流和页面生命周期
+
+应用只收到 `conversation/run/message/tool/interaction.updated` 五类中性更新。消息按 ID 替换完整文本；不解析平台引擎通知。游标使用安全整数 durable seq，重复帧去重，缺失序列先重新读取一致快照。
+
+断线后初次连接之外最多三次只读续接，失败后显示 `stream = disconnected`，由用户刷新观察器。idle/heartbeat 只是传输控制帧，不是业务成功。frame 与剩余 buffer 各限制 2 MiB。卸载、退出、身份变化会中止 fetch 和 reader，不增加平台流额度。
+
+## 验收不能混用
+
+SDK 单测、类型与 affected gates 证明客户端契约，不证明可用的业务应用。交付仍需已激活的测试 AppVersion、已启用 worker 和真实模型连接、真实角色拒绝、PC/移动浏览器、断线恢复及实际业务记录读回。Connected dev 使用已激活测试版本的助手；未激活的本地 overlay 不属于 worker 定义。

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

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