openxiangda 2.66.2 → 2.67.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/dist/agent.d.ts +6 -0
  2. package/dist/agent.d.ts.map +1 -0
  3. package/dist/agent.js +4 -0
  4. package/dist/agent.js.map +1 -0
  5. package/dist/browser/admin-shell.d.ts +1 -1
  6. package/dist/browser/agent-client.d.ts +16 -0
  7. package/dist/browser/agent-client.d.ts.map +1 -0
  8. package/dist/browser/agent-client.js +54 -0
  9. package/dist/browser/agent-client.js.map +1 -0
  10. package/dist/browser/agent-conversation.d.ts +71 -0
  11. package/dist/browser/agent-conversation.d.ts.map +1 -0
  12. package/dist/browser/agent-conversation.js +391 -0
  13. package/dist/browser/agent-conversation.js.map +1 -0
  14. package/dist/browser/agent-hooks.d.ts +31 -0
  15. package/dist/browser/agent-hooks.d.ts.map +1 -0
  16. package/dist/browser/agent-hooks.js +62 -0
  17. package/dist/browser/agent-hooks.js.map +1 -0
  18. package/dist/browser/agent-protocol.d.ts +131 -0
  19. package/dist/browser/agent-protocol.d.ts.map +1 -0
  20. package/dist/browser/agent-protocol.js +2 -0
  21. package/dist/browser/agent-protocol.js.map +1 -0
  22. package/dist/browser/agent-stream.d.ts +7 -0
  23. package/dist/browser/agent-stream.d.ts.map +1 -0
  24. package/dist/browser/agent-stream.js +83 -0
  25. package/dist/browser/agent-stream.js.map +1 -0
  26. package/dist/browser/components/resource/SurfaceFields.d.ts +1 -1
  27. package/dist/browser/components/resource/useResourceFormDrafts.d.ts.map +1 -1
  28. package/dist/browser/components/workflow/StandardWorkflowPages.d.ts +1 -1
  29. package/dist/browser/mobile.d.ts +2 -2
  30. package/dist/browser/platform-client.d.ts +3 -0
  31. package/dist/browser/platform-client.d.ts.map +1 -1
  32. package/dist/browser/platform-client.js +88 -0
  33. package/dist/browser/platform-client.js.map +1 -1
  34. package/dist/browser/runtime-capabilities.d.ts +5 -0
  35. package/dist/browser/runtime-capabilities.d.ts.map +1 -0
  36. package/dist/browser/runtime-capabilities.js +4 -0
  37. package/dist/browser/runtime-capabilities.js.map +1 -0
  38. package/dist/browser/runtime.d.ts.map +1 -1
  39. package/dist/browser/runtime.js +2 -4
  40. package/dist/browser/runtime.js.map +1 -1
  41. package/dist/browser/standard-user-surfaces.d.ts +1 -1
  42. package/documentation/application-agents.md +72 -0
  43. package/documentation/application-operations.md +35 -0
  44. package/documentation/appspec.md +4 -0
  45. package/documentation/getting-started.md +7 -7
  46. package/documentation/manifest.json +11 -5
  47. package/documentation/reference/mcp.md +111 -0
  48. package/package.json +26 -17
  49. package/releases/2.63.0.json +45 -0
  50. package/releases/2.63.1.json +46 -0
  51. package/releases/2.66.0.json +29 -0
  52. package/releases/2.66.1.json +29 -0
  53. package/releases/2.67.0.json +33 -0
  54. package/releases/2.67.1.json +35 -0
  55. package/releases/2.67.2.json +34 -0
  56. package/skills/manifest.json +1 -1
  57. package/skills/openxiangda-v2/SKILL.md +5 -4
  58. package/skills/openxiangda-v2/references/application-agents.md +72 -0
  59. package/skills/openxiangda-v2/references/application-operations.md +35 -0
  60. package/skills/openxiangda-v2/references/appspec.md +4 -0
  61. package/skills/openxiangda-v2/references/getting-started.md +7 -7
  62. package/skills/openxiangda-v2/references/mcp.md +111 -0
@@ -0,0 +1,29 @@
1
+ {
2
+ "schemaVersion": "openxiangda.release-notes/v1",
3
+ "version": "2.66.0",
4
+ "status": "reviewed",
5
+ "title": "受限事件后台事务能力",
6
+ "summary": "复用平台事件投递租约及持久回执,支持定时消费者以显式资源与字段授权执行 Native 事务。",
7
+ "newFeatures": [
8
+ "事件消费者支持受限查询、冻结事务、原键提交与回执恢复;平台统一执行并验证事件租约。"
9
+ ],
10
+ "fixes": [
11
+ "迟到消费者只能释放自身租约,不能覆盖新消费者处理权。"
12
+ ],
13
+ "affectedUsers": [
14
+ "需要定时业务事务的 OpenXiangda V2 应用开发者与平台维护者。"
15
+ ],
16
+ "upgradeSteps": [
17
+ "配对升级 SDK、CLI、共享契约和平台服务;为事件订阅显式声明 worker-effect 资源、字段及容量。"
18
+ ],
19
+ "knownLimitations": [
20
+ "投递至少一次,业务事务依赖原幂等意图去重;不允许工作流拥有的资源写入或任意业务身份冒用。"
21
+ ],
22
+ "compatibility": {
23
+ "node": ">=24",
24
+ "pnpm": "10.15.1"
25
+ },
26
+ "issues": [],
27
+ "sha256": "48c557ed1f5420f31b352721b05fc769d2f728c84102da0705eca9553844532a",
28
+ "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.66.0"
29
+ }
@@ -0,0 +1,29 @@
1
+ {
2
+ "schemaVersion": "openxiangda.release-notes/v1",
3
+ "version": "2.66.1",
4
+ "status": "reviewed",
5
+ "title": "事件 worker-effect SDK 导出修复",
6
+ "summary": "保持 2.66.0 worker-effect 能力,并修复根包 Nest 入口导出缺失。",
7
+ "newFeatures": [
8
+ "事件消费者支持受限查询、冻结事务、原键提交与回执恢复;平台统一执行并验证事件租约。"
9
+ ],
10
+ "fixes": [
11
+ "公开 Nest 入口补充导出事件 worker-effect 服务。"
12
+ ],
13
+ "affectedUsers": [
14
+ "需要定时业务事务的 OpenXiangda V2 应用开发者与平台维护者。"
15
+ ],
16
+ "upgradeSteps": [
17
+ "配对升级 SDK、CLI、共享契约和平台服务;为事件订阅显式声明 worker-effect 资源、字段及容量。"
18
+ ],
19
+ "knownLimitations": [
20
+ "投递至少一次,业务事务依赖原幂等意图去重;不允许工作流拥有的资源写入或任意业务身份冒用。"
21
+ ],
22
+ "compatibility": {
23
+ "node": ">=24",
24
+ "pnpm": "10.15.1"
25
+ },
26
+ "issues": [],
27
+ "sha256": "bf5cc01bff98c34817ba998f822f74561f8d4d44da121229b5e585654cba13c0",
28
+ "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.66.1"
29
+ }
@@ -0,0 +1,33 @@
1
+ {
2
+ "schemaVersion": "openxiangda.release-notes/v1",
3
+ "version": "2.67.0",
4
+ "status": "reviewed",
5
+ "title": "应用Agent接口与事件worker声明修复",
6
+ "summary": "新增作用域内应用Agent客户端,并补齐事件worker编译上下文及节点条件配置契约。",
7
+ "newFeatures": [
8
+ "公开openxiangda/agent客户端与hooks,沿用平台当前身份和持久游标,未知写入不自动重放。"
9
+ ],
10
+ "fixes": [
11
+ "worker-effect编译传入显式emitEventTypes与实际工作流subject,避免合法声明被误拒绝。",
12
+ "配置类型公开worker-effect执行声明,避免应用使用类型绕过。",
13
+ "共享节点人员配置支持完整条件规则与权威来源边界。"
14
+ ],
15
+ "affectedUsers": [
16
+ "OpenXiangda V2应用开发者和平台维护者"
17
+ ],
18
+ "upgradeSteps": [
19
+ "按同批版本升级工具链,重新生成并检查应用契约。",
20
+ "配套升级平台共享契约后验证TEST,真实角色验收独立执行。"
21
+ ],
22
+ "knownLimitations": [
23
+ "事件至少一次投递,依赖原业务意图和平台回执去重。",
24
+ "工具链发布不代表学校平台部署或应用业务验收完成。"
25
+ ],
26
+ "compatibility": {
27
+ "node": ">=24",
28
+ "pnpm": "10.15.1"
29
+ },
30
+ "issues": [],
31
+ "sha256": "535f00f729995cc1f8ce0925c3ddbd5976e1ed6283ef60d2888955ae95393d02",
32
+ "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.67.0"
33
+ }
@@ -0,0 +1,35 @@
1
+ {
2
+ "schemaVersion": "openxiangda.release-notes/v1",
3
+ "version": "2.67.1",
4
+ "status": "reviewed",
5
+ "title": "应用Agent及worker声明与发行恢复修复",
6
+ "summary": "新增作用域内应用Agent客户端,并补齐事件worker编译上下文及节点条件配置契约。",
7
+ "newFeatures": [
8
+ "公开openxiangda/agent客户端与hooks,沿用平台当前身份和持久游标,未知写入不自动重放。"
9
+ ],
10
+ "fixes": [
11
+ "worker-effect编译传入显式emitEventTypes与实际工作流subject,避免合法声明被误拒绝。",
12
+ "配置类型公开worker-effect执行声明,避免应用使用类型绕过。",
13
+ "共享节点人员配置支持完整条件规则与权威来源边界。",
14
+ "声明warning保持警告,真正错误仍阻断,避免正确应用被误拒绝。",
15
+ "Git worktree发行计划、验证与发布共用冻结制品、回执和进程锁;发现旧私有回执时先恢复原状态。"
16
+ ],
17
+ "affectedUsers": [
18
+ "OpenXiangda V2应用开发者和平台维护者"
19
+ ],
20
+ "upgradeSteps": [
21
+ "按同批版本升级工具链,重新生成并检查应用契约。",
22
+ "配套升级平台共享契约后验证TEST,真实角色验收独立执行。"
23
+ ],
24
+ "knownLimitations": [
25
+ "事件至少一次投递,依赖原业务意图和平台回执去重。",
26
+ "工具链发布不代表学校平台部署或应用业务验收完成。"
27
+ ],
28
+ "compatibility": {
29
+ "node": ">=24",
30
+ "pnpm": "10.15.1"
31
+ },
32
+ "issues": [],
33
+ "sha256": "cab78d0c354ccfe6373966f884c475e4e50e0096a5cbe9763fce2a761ba99e99",
34
+ "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.67.1"
35
+ }
@@ -0,0 +1,34 @@
1
+ {
2
+ "schemaVersion": "openxiangda.release-notes/v1",
3
+ "version": "2.67.2",
4
+ "status": "reviewed",
5
+ "title": "读取范围能力交集与开发诊断修复",
6
+ "summary": "所选读取范围严格收窄当前身份能力,并补充原执行健康、托管文件语义及设计资料预算诊断。",
7
+ "newFeatures": [
8
+ "应用自助操作提供原执行健康和托管文件语义观察,沿用当前身份与原请求。"
9
+ ],
10
+ "fixes": [
11
+ "Perspective读取能力与当前身份能力取交集,避免有限角色选择其他角色的完整管理投影。",
12
+ "AppSpec记录实际读取字节和省略原因,保留现有确认及部署门禁,不将超预算资料误判为不存在。",
13
+ "工作区加载及封包的声明warning不再误当error阻断,真实错误继续拒绝。",
14
+ "发行元数据读取保留有界并发和原渠道状态;CLI模板与根SDK版本配套。"
15
+ ],
16
+ "affectedUsers": [
17
+ "使用多角色读取范围的V2应用开发者及平台维护者"
18
+ ],
19
+ "upgradeSteps": [
20
+ "通过官方精确根包版本安装整组工具链,检查当前平台兼容性后重新部署TEST。",
21
+ "使用有限角色、兼任角色及撤销授权场景核对页面投影;实际业务验收独立于发包。"
22
+ ],
23
+ "knownLimitations": [
24
+ "源码回归不证明学校身份同步、通知通道、定时任务或完整迁移已验收。",
25
+ "读取范围不改变写入和业务动作授权,Native后端继续独立执行字段与行权限。"
26
+ ],
27
+ "compatibility": {
28
+ "node": ">=24",
29
+ "pnpm": "10.15.1"
30
+ },
31
+ "issues": [],
32
+ "sha256": "a6d7741c59762468ee23815832c0d707166bc60ca7913dabd4f945d6cf84ac20",
33
+ "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.67.2"
34
+ }
@@ -4,7 +4,7 @@
4
4
  {
5
5
  "name": "openxiangda-v2",
6
6
  "description": "使用 OpenXiangda 2.0 从模糊业务想法、已有资料或具体变更出发,通过对话发现模块、完成详细产品设计,由当前 AI Agent 按需用 Image 2.5 等图片能力形成视觉参考,直接实现真实页面并在浏览器修正,再检查和交付应用;维护 1.x 应用时使用对应的 1.x 技能。",
7
- "sha256": "bcb6d93ae6a05e79cd9c5ff2bcdd05784b6a919a6dc2c9ec4103d3323d2daf7f"
7
+ "sha256": "dc52170ff2eef697cbc4aa429bfc41ef137324f720dd2cbc7df0f8b8659470e8"
8
8
  }
9
9
  ]
10
10
  }
@@ -40,10 +40,10 @@ AI 接到新应用、页面或改版任务时,在同一个 OpenXiangda 工作
40
40
  未创建工作区时使用本 Skill 随根包发布的精确版本:
41
41
 
42
42
  ```bash
43
- pnpm dlx openxiangda@2.66.2 auth status --cwd <应用目录> --base-url <平台地址> --json
44
- pnpm dlx openxiangda@2.66.2 login --cwd <应用目录> --base-url <平台地址>
45
- pnpm dlx openxiangda@2.66.2 create <应用目录> --base-url <同一平台地址>
46
- pnpm dlx openxiangda@2.66.2 skill install --force
43
+ pnpm dlx openxiangda@2.67.2 auth status --cwd <应用目录> --base-url <平台地址> --json
44
+ pnpm dlx openxiangda@2.67.2 login --cwd <应用目录> --base-url <平台地址>
45
+ pnpm dlx openxiangda@2.67.2 create <应用目录> --base-url <同一平台地址>
46
+ pnpm dlx openxiangda@2.67.2 skill install --force
47
47
  ```
48
48
 
49
49
  创建前把产品要求的目标平台明确带入命令,不从旧登录态推断站点。已有工作区从原绑定恢复,平台不一致时先解决登录与目标,不改 link 文件跨站创建。
@@ -73,6 +73,7 @@ pnpm dlx openxiangda@2.66.2 skill install --force
73
73
  | 自定义事务、校验或外部集成 | [按需后端](references/backend.md) |
74
74
  | 向平台业务 Agent 开放任务、辅助查询和字段绑定 | [Agent 任务接入](references/backend.md#面向普通用户的-agent-任务);先完成业务操作、权限和规则,再声明 `ai.agent` |
75
75
  | 为业务 Agent 提供自定义填写/结果卡片 | [Agent 卡片](references/agent-cards.md);声明同版本资源、使用隔离 SDK,保留平台标准卡片降级 |
76
+ | 应用内置助手、会话、断线恢复与未知结果核对 | [应用助手](references/application-agents.md);复用当前用户身份,写入不自动重放,客户端验证与真实业务验收分开 |
76
77
  | 主子额度、审批占用释放、撤回修订重提 | [精确金额占用](references/decimal-reservations.md) |
77
78
  | 热点读取、抢票、排队、名额预占与原结果恢复 | [缓存、排队与配额](references/managed-concurrency.md) |
78
79
  | 报名按钮、表单排队、短确认页、预占倒计时与前端恢复 | [并发前端接入](references/managed-concurrency-frontend.md):按六种形式选择;仅使用已导出的 API,区分待实现封装 |
@@ -0,0 +1,72 @@
1
+ # 应用内置助手
2
+
3
+ 应用助手的定义属于应用源码,随 AppVersion 激活和回滚;模型连接、配额和运行开关由平台维护。它不是租户平台助手,也不替代应用自己的后台。布局和卡片使用应用源码,登录、权限与命令仍由平台拥有。
4
+
5
+ 本专题对应新增的 `openxiangda/agent` 源码能力。使用前核对实际安装版本的公开导出和平台配对能力;本轮开发没有执行 npm 发布。可复制助手模板、`agent eval`、真实模型与真实角色的访客验收尚未闭合,不能据此声明应用助手已经交付。
6
+
7
+ ## 接入
8
+
9
+ 在现有应用路由与 RuntimeBoundary 内使用 hooks,不新增 router、登录存储、平台代理或业务数据库:
10
+
11
+ ```tsx
12
+ import { useAgents, useAgentConversation } from 'openxiangda/agent';
13
+
14
+ export function ApplicationAssistant() {
15
+ const catalog = useAgents();
16
+ const assistant = useAgentConversation('assistant');
17
+ const busy = Boolean(assistant.pending || assistant.snapshot?.conversation.activeRunId);
18
+ // 使用 catalog.agents 中该助手的 name/purpose/starters/available/reason。
19
+ // 展示 assistant.snapshot.messages,content 是完整文本,不是 token delta。
20
+ // 用户主动点击才调用 newConversation/send;挂载和 reload 只读恢复。
21
+ return <div>
22
+ {catalog.error && <p role="alert">暂时无法获取助手</p>}
23
+ {assistant.pending?.state === 'unknown' && <p role="alert">原请求结果尚不确定,请先核对,不要重复提交。</p>}
24
+ <button disabled={busy} onClick={() => void assistant.send('今天有哪些来访').catch(() => {})}>查询今日来访</button>
25
+ <button onClick={() => void assistant.recover().catch(() => {})}>核对原请求</button>
26
+ </div>;
27
+ }
28
+ ```
29
+
30
+ 助手声明及任务编译规则见源码架构记录和配置类型 `defineApplicationAgent`。客户端不接受 appCode、environmentKey、actor、provider、baseUrl 或 API key;它使用当前已登录用户和角色并集,绑定 RuntimeBoundary 的身份及环境。退出或身份变化时销毁旧请求、流和可见快照。
31
+
32
+ 不使用 React hooks 的现有应用组件可调用 `createApplicationAgentClient()`,随后 `client.agents()`、`client.conversations(agentCode)`、`client.conversation(agentCode)`。观察器 `subscribe/snapshot` 可供自定义组件使用;离开时 `client.dispose()`。不能在匿名页面或未建立 RuntimeBoundary 身份时创建客户端。
33
+
34
+ ## 写入与卡片
35
+
36
+ 用户主动操作时客户端生成 UUID,填写/确认携带原卡片 revision。同一观察器只允许一项待处理写入。以下调用不绕过服务端的能力、记录修订与当前角色检查:
37
+
38
+ ```ts
39
+ await assistant.submitInteraction(card.id, card.revision, {
40
+ visitorName: '张伟',
41
+ count: 2,
42
+ needsParking: false,
43
+ company: null, // 显式清空;未触及字段直接省略。
44
+ });
45
+ await assistant.confirm(confirmation.id, confirmation.revision);
46
+ await assistant.cancelInteraction(card.id);
47
+ await assistant.cancel(run.id);
48
+ await assistant.reconcile(tool.id); // 只读核对业务执行所有者的原回执。
49
+ // 仅供平台允许的人工核实人员;服务器仍验证权限并保留人工来源:
50
+ await assistant.resolveManually(tool.id, 'not_executed', '已核对业务系统,没有对应记录');
51
+ ```
52
+
53
+ 卡片编辑和候选查询必须复用公开 Field Kit 与字段自己的 lookup。headless 客户端不把 reference/user/date/number 转成字符串,不合并旧 partialInput,不定义第二套候选权威。确认是独立明确按钮,不应绑定到自动回复或隐藏脚本。
54
+
55
+ ## 结果不确定与只读恢复
56
+
57
+ - 断网、408、5xx 或丢失响应后保留 `pending.state = unknown`,不自动重放,也不静默生成新键。
58
+ - `recover()` 查询原创建 requestId 或当前会话快照。没有找到原结果不等于未执行,继续阻止新写。
59
+ - 快照/事件读回同一请求关联后,`lastResolution.disposition = acknowledged` 仅表示平台已处理这项请求,不代表业务成功。业务执行成功仍要看业务工具回执,并实际读回记录。
60
+ - 另一请求推进卡片状态/修订时,旧意图只能标记 `closed`,不能宣称本次提交成功。
61
+ - `still_unknown` 不是失败、更不是成功。应用只提供核对和已有权限下的人工核实入口,不自动执行原业务写入。
62
+ - sessionStorage 只保存当前身份、应用、环境作用域的会话指针和原请求/卡片 ID,不保存文本、字段值、凭据或模型连接。存储不可用时 `persistence = memory`;刷新后应从历史和平台回执核对,不能假装仍有完整恢复证据。
63
+
64
+ ## 流和页面生命周期
65
+
66
+ 应用只收到 `conversation/run/message/tool/interaction.updated` 五类中性更新。消息按 ID 替换完整文本;不解析平台引擎通知。游标使用安全整数 durable seq,重复帧去重,缺失序列先重新读取一致快照。
67
+
68
+ 断线后初次连接之外最多三次只读续接,失败后显示 `stream = disconnected`,由用户刷新观察器。idle/heartbeat 只是传输控制帧,不是业务成功。frame 与剩余 buffer 各限制 2 MiB。卸载、退出、身份变化会中止 fetch 和 reader,不增加平台流额度。
69
+
70
+ ## 验收不能混用
71
+
72
+ SDK 单测、类型与 affected gates 证明客户端契约,不证明可用的业务应用。交付仍需已激活的测试 AppVersion、已启用 worker 和真实模型连接、真实角色拒绝、PC/移动浏览器、断线恢复及实际业务记录读回。Connected dev 使用已激活测试版本的助手;未激活的本地 overlay 不属于 worker 定义。
@@ -30,6 +30,41 @@ CLI与MCP共用输入Schema、服务和平台错误。成功结果在 `data.resu
30
30
  配置与恢复在已授权范围内直接执行;health访问外部健康接口并保存元信息。
31
31
  操作目录不证明远端接口已部署或当前用户有权,执行结果由平台决定。
32
32
 
33
+ ## 原执行健康 {#execution-health}
34
+
35
+ 从 `admin operations` 发现 `diagnostics.execution-health`,输入只提供原 kind 和 UUID:
36
+
37
+ ```bash
38
+ printf '%s' '{"kind":"event-delivery","id":"<原投递UUID>"}' | \
39
+ pnpm openxiangda admin execute diagnostics.execution-health --environment test --input - --json
40
+ ```
41
+
42
+ kind 为 timer、date-trigger、event-delivery 或 legacy-schedule;legacy-schedule只接受production,V1工作区仍由原V1引擎维护。按当前工作区 appCode 和原登录身份的应用管理权限只读查询,不传tenant、任意URL或恢复动作。
43
+
44
+ `admission`、`due`、`claim` 分别表示当前准入、原周期和claim;暂停可能仍有有效旧claim,未来/夜间周期不是卡住。lease过期或 `needs_review` 先核对原owner、退出证明与效果回执,不重放旧周期。timer当前按原事务行锁调度,预留lease字段不会被解释为executor空闲。缺记录/超时/schema缺失明确为未知,HTTP200只是诊断响应。
45
+
46
+ 目标平台需要提供此受管诊断路由;404先核对平台版本,不创建业务shim或替代执行。原requestId/commandId/DeploymentRun/fileId诊断继续用于原操作读回;健康投影不替代业务验收。
47
+
48
+ ## TEST 文件语义观察 {#semantic-audit}
49
+
50
+ 原平台管理员从目录发现 `diagnostics.semantic-audit`;只接受test。以下input的版本、Head修订、resourceCode均取自当前应用的实际TEST目标:
51
+
52
+ ```json
53
+ {
54
+ "requirementId":"native.file-value.v2-envelope",
55
+ "resourceCode":"records",
56
+ "expectedAppVersionId":"11111111-1111-4111-8111-111111111111",
57
+ "expectedHeadRevision":1,
58
+ "limit":50
59
+ }
60
+ ```
61
+
62
+ 把input交给 `admin execute diagnostics.semantic-audit --environment test --input <文件> --json`,或通过原MCP `application_operation`。版本/Head变化先刷新目标;不递增修订猜测当前状态。最多100行、32个file/image字段、单行文件值投影16KiB、20个原因样本。分页用原nextCursor传afterRecordId;后续页不冒充同一完整资源快照,工具不自动无限扫描。
63
+
64
+ `satisfied`、`violations`、`incomplete`、`unknown`分别描述本次快照;报告始终 `admission: observe-only`。即使complete且satisfied也不是激活许可;dataLogicalRevisionId是定义版本,dataRevision明确为空。报告没有文件名、正文或原错误正文。signature.file遵循自身Omit协议,不误当file/image数组。
65
+
66
+ 此观察不证明文件存在/下载授权或历史权限/流程兼容,不自动转换或删除。需修复时交原repair owner评审精确before-image和目标;生产不在此入口范围。404仍先核对实际平台能力;旧SDK版本不能仅凭本文认定已安装该新操作。
67
+
33
68
  ## 事件高水位与指定恢复 {#events}
34
69
 
35
70
  遇到 `EVENT_V2_BACKPRESSURE_HIGH_WATER` 先读 `events.status` 的admission:采样新鲜度、
@@ -139,6 +139,10 @@ MCP `appspec_verify` 读取同一报告与运行事实。`spec verify` 根据当
139
139
 
140
140
  ## 新任务找回上下文
141
141
 
142
+ 读取时核对 `documentReadback` 的实际文件字节、读取字节、全文/历史索引模式和不可用原因;最多128条,`total`/`unavailable`/`truncated`明确其覆盖范围。单文件上限256KiB,正文上下文上限256KiB,按UTF-8字节计。`contextBudget.requestedContentBytes` 是预算前请求正文总量,`omitted` 每项包含实际字节及 `context-budget` 原因。
143
+
144
+ 超限、格式错误、符号链接或读取期间变化表示文件不可用;selector会提示在已成功读取的文档中无法解析,不能据此删除、重建文档或补造确认。真实不存在仍保留原not-found。先按相对路径处理原因,保留稳定ID/确认;相关正文过多时用稳定ID选择或拆分当前总纲,历史索引不是全文。81,602字节的普通资料在当前单文件预算内,不应套用旧64KiB限制。
145
+
142
146
  ### 架构决定的编号与创建
143
147
 
144
148
  需要长期引用的决定写入 `appspec/decisions/` 下的 Markdown。ADR 的 `id` 格式是 `ADR-` 加**恰好四位数字**,可选 `-` 分隔的大写字母或数字后缀,例如 `ADR-0001`、`ADR-0001-DATA-OWNER`;`ADR-001` 不合法。文件名建议与 ID 一致,引用使用元数据中的 ID。当前没有独立的 ADR 创建命令,可以手工创建,随后用 `spec context <ID>` 和 `spec check` 核对。
@@ -68,10 +68,10 @@ MCP 服务随项目根包一起安装,AI 客户端的 stdio 连接仍需配置
68
68
  以下命令的版本占位符由随包资料替换为该根包的精确版本。网站源码阅读者应先确认要使用的发行版本。
69
69
 
70
70
  ```bash
71
- pnpm dlx openxiangda@2.66.2 skill install --force
72
- pnpm dlx openxiangda@2.66.2 auth status --base-url <平台地址> --json
73
- pnpm dlx openxiangda@2.66.2 login --cwd my-app --base-url https://platform.example.com
74
- pnpm dlx openxiangda@2.66.2 create my-app --base-url https://platform.example.com
71
+ pnpm dlx openxiangda@2.67.2 skill install --force
72
+ pnpm dlx openxiangda@2.67.2 auth status --base-url <平台地址> --json
73
+ pnpm dlx openxiangda@2.67.2 login --cwd my-app --base-url https://platform.example.com
74
+ pnpm dlx openxiangda@2.67.2 create my-app --base-url https://platform.example.com
75
75
  cd my-app
76
76
  pnpm openxiangda context --json
77
77
  pnpm openxiangda dev
@@ -206,9 +206,9 @@ MCP 的 `docs_read` 可以读取本说明,当前没有独立的源码操作 MC
206
206
  无需本地工作区,使用本 Skill 随包精确版本或已安装的对应 CLI:
207
207
 
208
208
  ```bash
209
- pnpm dlx openxiangda@2.66.2 auth status --base-url <平台> --json
210
- pnpm dlx openxiangda@2.66.2 source resolve <仓库URL> --base-url <平台> --json
211
- pnpm dlx openxiangda@2.66.2 source clone <仓库URL> <新目录> --base-url <平台> --json
209
+ pnpm dlx openxiangda@2.67.2 auth status --base-url <平台> --json
210
+ pnpm dlx openxiangda@2.67.2 source resolve <仓库URL> --base-url <平台> --json
211
+ pnpm dlx openxiangda@2.67.2 source clone <仓库URL> <新目录> --base-url <平台> --json
212
212
  ```
213
213
 
214
214
  登录缺失或站点不匹配时,先按该平台执行 login。resolve 根据平台已经登记的绑定返回
@@ -288,6 +288,117 @@ MCP 使用项目锁定的根包;在客户端配置下列 stdio 启动参数,
288
288
  {
289
289
  "type": "object",
290
290
  "oneOf": [
291
+ {
292
+ "type": "object",
293
+ "additionalProperties": false,
294
+ "properties": {
295
+ "operation": {
296
+ "const": "diagnostics.semantic-audit",
297
+ "description": "绑定当前TEST版本和Head的文件值语义审计;仅观察,不修复或授予激活许可"
298
+ },
299
+ "environment": {
300
+ "type": "string",
301
+ "enum": [
302
+ "test"
303
+ ]
304
+ },
305
+ "input": {
306
+ "type": "object",
307
+ "additionalProperties": false,
308
+ "properties": {
309
+ "requirementId": {
310
+ "const": "native.file-value.v2-envelope"
311
+ },
312
+ "resourceCode": {
313
+ "type": "string",
314
+ "minLength": 1,
315
+ "maxLength": 128,
316
+ "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
317
+ },
318
+ "expectedAppVersionId": {
319
+ "type": "string",
320
+ "minLength": 1,
321
+ "maxLength": 36,
322
+ "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
323
+ },
324
+ "expectedHeadRevision": {
325
+ "type": "integer",
326
+ "minimum": 1,
327
+ "maximum": 9007199254740991
328
+ },
329
+ "afterRecordId": {
330
+ "type": "string",
331
+ "minLength": 1,
332
+ "maxLength": 36,
333
+ "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
334
+ },
335
+ "limit": {
336
+ "type": "integer",
337
+ "minimum": 1,
338
+ "maximum": 100
339
+ }
340
+ },
341
+ "required": [
342
+ "requirementId",
343
+ "resourceCode",
344
+ "expectedAppVersionId",
345
+ "expectedHeadRevision"
346
+ ]
347
+ }
348
+ },
349
+ "required": [
350
+ "operation",
351
+ "environment",
352
+ "input"
353
+ ]
354
+ },
355
+ {
356
+ "type": "object",
357
+ "additionalProperties": false,
358
+ "properties": {
359
+ "operation": {
360
+ "const": "diagnostics.execution-health",
361
+ "description": "按原ID核对未来计划、暂停、claim和租约;不恢复或重放"
362
+ },
363
+ "environment": {
364
+ "type": "string",
365
+ "enum": [
366
+ "test",
367
+ "production"
368
+ ]
369
+ },
370
+ "input": {
371
+ "type": "object",
372
+ "additionalProperties": false,
373
+ "properties": {
374
+ "kind": {
375
+ "type": "string",
376
+ "enum": [
377
+ "legacy-schedule",
378
+ "timer",
379
+ "date-trigger",
380
+ "event-delivery"
381
+ ]
382
+ },
383
+ "id": {
384
+ "type": "string",
385
+ "minLength": 1,
386
+ "maxLength": 36,
387
+ "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
388
+ }
389
+ },
390
+ "required": [
391
+ "kind",
392
+ "id"
393
+ ]
394
+ }
395
+ },
396
+ "required": [
397
+ "operation",
398
+ "environment",
399
+ "input"
400
+ ]
401
+ },
291
402
  {
292
403
  "type": "object",
293
404
  "additionalProperties": false,