openxiangda 2.66.0 → 2.67.1

package/dist/nest.js

@@ -4,7 +4,7 @@
  * Applications receive only current-user-union, Perspective read projection,
  * application-principal, Data API, runtime, event and bounded operation APIs.
  */
-export { bootstrapOpenXiangdaApplication, OpenXiangdaModule, OpenXiangdaAuthzGuard, RequireCapability, OpenXiangdaOperation, CurrentPrincipal, CurrentUser, CurrentPerspective, currentUserFromVerifiedContext, currentUserFromPrincipal, CurrentApplicationPrincipal, OpenXiangdaDataApiService, OpenXiangdaBusinessDataApiService, OpenXiangdaBusinessDirectoryService, OpenXiangdaBusinessProcessService, OpenXiangdaWorkflowService, WorkflowAssigneeProvider, OpenXiangdaBusinessNotificationService, OpenXiangdaNotificationService, OpenXiangdaTodoService, OpenXiangdaLoggerService, OpenXiangdaPlatformError, OpenXiangdaApplicationDataApiService, OpenXiangdaApplicationCredentials, OpenXiangdaRuntimeLeaseService, OpenXiangdaRuntimeSecrets, OpenXiangdaStandardOperations, OpenXiangdaEventContext, OpenXiangdaEventHandler, OpenXiangdaManagedCommandHandler, OpenXiangdaEventRegistry, OpenXiangdaEventRetryableError, OpenXiangdaEventDeterministicError, eventSigningSecretsFromEnvironment, assertValidTimeInterval, databaseNowAssertion, idempotentTransaction, createDataTransaction, diagnoseDataTransaction, DataTransactionBuildError, bindOpenXiangdaResources, } from 'openxiangda-nest';
+export { bootstrapOpenXiangdaApplication, OpenXiangdaModule, OpenXiangdaAuthzGuard, RequireCapability, OpenXiangdaOperation, CurrentPrincipal, CurrentUser, CurrentPerspective, currentUserFromVerifiedContext, currentUserFromPrincipal, CurrentApplicationPrincipal, OpenXiangdaDataApiService, OpenXiangdaBusinessDataApiService, OpenXiangdaBusinessDirectoryService, OpenXiangdaBusinessProcessService, OpenXiangdaWorkflowService, WorkflowAssigneeProvider, OpenXiangdaBusinessNotificationService, OpenXiangdaNotificationService, OpenXiangdaTodoService, OpenXiangdaLoggerService, OpenXiangdaPlatformError, OpenXiangdaApplicationDataApiService, OpenXiangdaApplicationCredentials, OpenXiangdaRuntimeLeaseService, OpenXiangdaRuntimeSecrets, OpenXiangdaStandardOperations, OpenXiangdaEventContext, OpenXiangdaEventHandler, OpenXiangdaManagedCommandHandler, OpenXiangdaEventRegistry, OpenXiangdaEventRetryableError, OpenXiangdaEventDeterministicError, eventSigningSecretsFromEnvironment, assertValidTimeInterval, databaseNowAssertion, idempotentTransaction, createDataTransaction, diagnoseDataTransaction, DataTransactionBuildError, bindOpenXiangdaResources, OpenXiangdaEventWorkerEffectService, } from 'openxiangda-nest';
 export { OPENXIANGDA_NOTIFICATION_BUSINESS_SEND_V2, OPENXIANGDA_NOTIFICATION_EVENT_SEND_V2, } from 'openxiangda-contracts';
 export { optionSnapshot, userSnapshot, departmentSnapshot, resourceSnapshot, isIdempotencyConflict, } from 'openxiangda-nest';
 //# sourceMappingURL=nest.js.map

package/dist/nest.js.map

@@ -1 +1 @@
-{"version":3,"file":"nest.js","sourceRoot":"","sources":["../src/nest.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,+BAA+B,EAC/B,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,WAAW,EACX,kBAAkB,EAClB,8BAA8B,EAC9B,wBAAwB,EACxB,2BAA2B,EAC3B,yBAAyB,EACzB,iCAAiC,EACjC,mCAAmC,EACnC,iCAAiC,EACjC,0BAA0B,EAC1B,wBAAwB,EACxB,sCAAsC,EACtC,8BAA8B,EAC9B,sBAAsB,EACtB,wBAAwB,EACxB,wBAAwB,EACxB,oCAAoC,EACpC,iCAAiC,EACjC,8BAA8B,EAC9B,yBAAyB,EACzB,6BAA6B,EAC7B,uBAAuB,EACvB,uBAAuB,EACvB,gCAAgC,EAChC,wBAAwB,EACxB,8BAA8B,EAC9B,kCAAkC,EAClC,kCAAkC,EAClC,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,uBAAuB,EACvB,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,kBAAkB,CAAC;AAyC1B,OAAO,EACL,yCAAyC,EACzC,sCAAsC,GACvC,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"nest.js","sourceRoot":"","sources":["../src/nest.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,+BAA+B,EAC/B,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,WAAW,EACX,kBAAkB,EAClB,8BAA8B,EAC9B,wBAAwB,EACxB,2BAA2B,EAC3B,yBAAyB,EACzB,iCAAiC,EACjC,mCAAmC,EACnC,iCAAiC,EACjC,0BAA0B,EAC1B,wBAAwB,EACxB,sCAAsC,EACtC,8BAA8B,EAC9B,sBAAsB,EACtB,wBAAwB,EACxB,wBAAwB,EACxB,oCAAoC,EACpC,iCAAiC,EACjC,8BAA8B,EAC9B,yBAAyB,EACzB,6BAA6B,EAC7B,uBAAuB,EACvB,uBAAuB,EACvB,gCAAgC,EAChC,wBAAwB,EACxB,8BAA8B,EAC9B,kCAAkC,EAClC,kCAAkC,EAClC,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,uBAAuB,EACvB,yBAAyB,EACzB,wBAAwB,EACxB,mCAAmC,GACpC,MAAM,kBAAkB,CAAC;AAyC1B,OAAO,EACL,yCAAyC,EACzC,sCAAsC,GACvC,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC"}

package/documentation/AGENTS.md

@@ -15,7 +15,7 @@
 - 无账号表单或外部公开数据读取都读取 `docs public-access`：使用 `frontend.publicAccess` 和专用客户端；提交策略声明 `create` 时必须启用 `draft`，只读公开目录使用 `public.list`/`public.read` 与 `publicRecordFields`，附件/图片/富文本按平台托管 URL 读取，子表必须声明 `publicSubtableFields`，不创建 guest 角色、不传 draft id、不调用普通 Data API。标准审批、通知和后端均按需启用。
 - 日常使用 dev 和聚焦测试。只验证时使用 check；授权部署时直接 deploy，它已包含检查、测试和构建。生产必须指定成功测试运行并复用同一版本。
 - deploy 默认持续反馈并跟踪平台结果；观察中断用 status <运行ID> --watch 继续，保留原运行，不重新构建。平台部署成功后仍需真实角色业务验收。
-- 开发开始先同步远端默认主分支；同一工作区只有一个写者。发布前将本轮源码、生成契约与记录合入并推送主分支，从干净且同步的主分支冻结候选；任务分支已推送不等于已合入主线。不要覆盖其他会话改动或自动合并所有分支。
+- 开发开始按项目约定同步绑定仓库，同一工作区只有一个写者；完成后提交推送本轮源码、生成契约与记录。应用 TEST 发布使用当前工作区，允许任务分支和未提交修改，source push 或主线整合不作为 TEST 前置。生产晋级复用成功测试版本，并核对原源码主线包含和真实验收；按 docs delivery 执行。不要覆盖其他会话改动或自动合并所有分支。
 - 默认读取 AppSpec 当前规格、设计索引、活动变更和阶段缺口。新应用先用自然语言对话主动发现模块，完成本期 PRD、旅程、逐页交互、视觉/原型、权限与架构设计及实际确认，形成内容摘要绑定的评审基线后再制定实施计划和实现业务；参见 docs product-design 和 docs interaction-patterns。既有应用仅修订受影响设计，不把 AI 建议写成用户确认。总纲保存长期规则，本轮变更关联需求、任务、源码与 AC 验收；测试发布前完成设计与计划，生产晋级前保存绑定原测试运行及包摘要的实际验收报告。更新当前规则、验证与发布结果和交接后归档；不得编造确认或通过结果。
 - 根据变化风险记录业务意图。无行为变化引用已有记录；已有授权和已确认意图不重复向用户请求机械确认。真实角色和浏览器验收与本地测试分别记录。
 - 失败保留错误码、指针和原候选；查询平台状态后使用允许的恢复操作，不自动重放未知结果。

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.0 skill install --force
-pnpm dlx openxiangda@2.66.0 auth status --base-url <平台地址> --json
-pnpm dlx openxiangda@2.66.0 login --cwd my-app --base-url https://platform.example.com
-pnpm dlx openxiangda@2.66.0 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
@@ -180,7 +180,8 @@ pnpm openxiangda source push -m "完成本轮应用开发"
 | 换电脑或初始化中断 | 在应用目录执行 `pnpm openxiangda source setup`；已有提交及未提交修改会保留 |
 | 从个人远端迁入 | 明确迁入后运行 `source setup --import`，原远端保留为 `external-source` |
 | 本轮修改完成 | 检查差异后运行 `source push -m "AppSpec: <本轮变更ID> 变更说明"`；多个任务共享目录时先精确提交本轮文件，再不带 `-m` 推送 |
-| 准备部署 | 先把本轮提交合入并推送远端默认分支，再从干净且同步的主分支执行 `deploy` |
+| 测试部署 | 当前工作区直接执行 `deploy`，允许分支及未提交修改；提交推送不作为 TEST 前置 |
+| 生产晋级 | 按 `docs delivery` 复用成功测试运行；核对原源码主线包含和绑定原版本的实际验收 |
 
 新仓库默认使用 `main`；导入时，尚无默认分支的空仓库会采用当前分支（例如 `master`）。
 已有远端默认分支不会因在任务分支运行 setup 而改变。源码操作使用 CLI/终端；
@@ -194,7 +195,7 @@ MCP 的 `docs_read` 可以读取本说明，当前没有独立的源码操作 MC
 | 403 / 应用管理权限不足 | 核对当前平台账号及应用管理员资格；由已有应用管理员添加权限 |
 | `APPLICATION_SOURCE_PROVIDER_UNAVAILABLE` / `APPLICATION_SOURCE_PROVIDER_FAILED` | 保留原应用和目录，待 Git 服务恢复后重试同一操作 |
 | 推送被拒绝或主线已前进 | 先 fetch 并查看差异，按项目规则合并解决冲突后重试，不强推覆盖 |
-| `APPLICATION_SOURCE_COMMIT_NOT_PUSHED` | 在绑定仓库推送原提交，核对 source status 和远端 SHA 后重试部署 |
+| `APPLICATION_SOURCE_COMMIT_NOT_PUSHED` | 核对操作和平台版本；当前 TEST 发布不要求先推送。生产晋级核对绑定原测试版本的源码主线事实，保留原版本并按交付说明处理 |
 
 应用创建人和新增应用管理员拥有对应仓库管理权限，不需要另行维护 Git 角色。
 本期不自动同步权限撤销或删除。不要向应用开发者索要 Forgejo 平台管理员 Token；
@@ -205,9 +206,9 @@ MCP 的 `docs_read` 可以读取本说明，当前没有独立的源码操作 MC
 无需本地工作区，使用本 Skill 随包精确版本或已安装的对应 CLI：
 
 ```bash
-pnpm dlx openxiangda@2.66.0 auth status --base-url <平台> --json
-pnpm dlx openxiangda@2.66.0 source resolve <仓库URL> --base-url <平台> --json
-pnpm dlx openxiangda@2.66.0 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.0",
+  "version": "2.67.1",
   "topics": [
     {
       "id": "getting-started",
       "title": "安装与开始开发",
       "file": "getting-started.md",
-      "sha256": "01a83324fbd3e7aed970244f3df70e73c721d52df927b4a948562dfad7ea5fd7"
+      "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.0",
+  "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.0",
-    "openxiangda-contracts": "2.83.0",
-    "openxiangda-devkit-core": "2.63.0",
+    "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.5",
-    "openxiangda-nest": "2.19.0",
-    "openxiangda-skill-kit": "2.3.106",
+    "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.0",
+    "version": "2.67.1",
     "status": "reviewed",
-    "title": "受限事件后台事务能力",
-    "summary": "复用平台事件投递租约及持久回执，支持定时消费者以显式资源与字段授权执行 Native 事务。",
+    "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": "48c557ed1f5420f31b352721b05fc769d2f728c84102da0705eca9553844532a",
-    "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.66.0"
+    "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.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.66.2.json

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

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

package/skills/openxiangda-v2/SKILL.md

@@ -40,10 +40,10 @@ AI 接到新应用、页面或改版任务时，在同一个 OpenXiangda 工作
 未创建工作区时使用本 Skill 随根包发布的精确版本：
 
 ```bash
-pnpm dlx openxiangda@2.66.0 auth status --cwd <应用目录> --base-url <平台地址> --json
-pnpm dlx openxiangda@2.66.0 login --cwd <应用目录> --base-url <平台地址>
-pnpm dlx openxiangda@2.66.0 create <应用目录> --base-url <同一平台地址>
-pnpm dlx openxiangda@2.66.0 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.0 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，区分待实现封装 |
@@ -110,7 +111,7 @@ pnpm exec openxiangda --mcp-stdio --cwd <workspace>
 
 ## 完成与失败
 
-开发开始先同步绑定仓库的远端默认主分支。开发完成包括源码、生成契约与必要记录的提交、推送和主线整合；发布从干净且同步的主分支冻结候选。任务分支已推送不代表进入主线。同一工作区保持一个写者，不覆盖其他会话未提交内容。日常 dev/check 可验证未提交源码。
+开发开始按项目约定同步绑定仓库，完成后提交推送源码、生成契约与必要记录。同一工作区保持一个写者，不覆盖其他会话未提交内容。应用 TEST 发布使用当前工作区，允许任务分支和未提交修改，source push 或主线整合不作为 TEST 前置；生产晋级复用成功测试版本，并核对原源码的权威主线包含及真实验收。详见[交付](references/delivery.md)。
 
 平台启用源码托管时，create 自动建仓并首次推送。后续每轮开发完成使用 `pnpm openxiangda source push -m "变更说明"` 提交并推送；已有提交可省略 `-m`。新电脑或初始化中断使用 `source setup`，迁入外部仓库使用 `source setup --import` 并保留原远端。凭据只存入系统凭据管理器，不手写进 URL 或项目文件；冲突按正常 Git 合并处理，不强推覆盖。
 

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.0 skill install --force
-pnpm dlx openxiangda@2.66.0 auth status --base-url <平台地址> --json
-pnpm dlx openxiangda@2.66.0 login --cwd my-app --base-url https://platform.example.com
-pnpm dlx openxiangda@2.66.0 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
@@ -180,7 +180,8 @@ pnpm openxiangda source push -m "完成本轮应用开发"
 | 换电脑或初始化中断 | 在应用目录执行 `pnpm openxiangda source setup`；已有提交及未提交修改会保留 |
 | 从个人远端迁入 | 明确迁入后运行 `source setup --import`，原远端保留为 `external-source` |
 | 本轮修改完成 | 检查差异后运行 `source push -m "AppSpec: <本轮变更ID> 变更说明"`；多个任务共享目录时先精确提交本轮文件，再不带 `-m` 推送 |
-| 准备部署 | 先把本轮提交合入并推送远端默认分支，再从干净且同步的主分支执行 `deploy` |
+| 测试部署 | 当前工作区直接执行 `deploy`，允许分支及未提交修改；提交推送不作为 TEST 前置 |
+| 生产晋级 | 按 `docs delivery` 复用成功测试运行；核对原源码主线包含和绑定原版本的实际验收 |
 
 新仓库默认使用 `main`；导入时，尚无默认分支的空仓库会采用当前分支（例如 `master`）。
 已有远端默认分支不会因在任务分支运行 setup 而改变。源码操作使用 CLI/终端；
@@ -194,7 +195,7 @@ MCP 的 `docs_read` 可以读取本说明，当前没有独立的源码操作 MC
 | 403 / 应用管理权限不足 | 核对当前平台账号及应用管理员资格；由已有应用管理员添加权限 |
 | `APPLICATION_SOURCE_PROVIDER_UNAVAILABLE` / `APPLICATION_SOURCE_PROVIDER_FAILED` | 保留原应用和目录，待 Git 服务恢复后重试同一操作 |
 | 推送被拒绝或主线已前进 | 先 fetch 并查看差异，按项目规则合并解决冲突后重试，不强推覆盖 |
-| `APPLICATION_SOURCE_COMMIT_NOT_PUSHED` | 在绑定仓库推送原提交，核对 source status 和远端 SHA 后重试部署 |
+| `APPLICATION_SOURCE_COMMIT_NOT_PUSHED` | 核对操作和平台版本；当前 TEST 发布不要求先推送。生产晋级核对绑定原测试版本的源码主线事实，保留原版本并按交付说明处理 |
 
 应用创建人和新增应用管理员拥有对应仓库管理权限，不需要另行维护 Git 角色。
 本期不自动同步权限撤销或删除。不要向应用开发者索要 Forgejo 平台管理员 Token；
@@ -205,9 +206,9 @@ MCP 的 `docs_read` 可以读取本说明，当前没有独立的源码操作 MC
 无需本地工作区，使用本 Skill 随包精确版本或已安装的对应 CLI：
 
 ```bash
-pnpm dlx openxiangda@2.66.0 auth status --base-url <平台> --json
-pnpm dlx openxiangda@2.66.0 source resolve <仓库URL> --base-url <平台> --json
-pnpm dlx openxiangda@2.66.0 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 根据平台已经登记的绑定返回