@yss123/cage-cli 0.3.1 → 0.3.2

package/templates/blank/docs/examples/purchase-admin/README.md

@@ -2,4 +2,4 @@
 
 本目录只供阅读，不参与应用编译、注册、运行或迁移。当前应用的真实领域入口是项目根目录 packages/domain/src/index.ts。
 
-按 [采购范例导读](../../ai/purchase-example.md) 阅读；导读中的范例路径在本目录下查找。需要可运行的完整采购项目时，重新使用 create-cage-app --template purchase 创建新目录，不要直接把整套业务导入空白项目。
+按 [采购范例导读](../../development/examples/purchase-example.md) 阅读；导读中的范例路径在本目录下查找。需要可运行的完整采购项目时，重新使用 create-cage-app --template purchase 创建新目录，不要直接把整套业务导入空白项目。

package/templates/blank/package.json

@@ -11,9 +11,9 @@
     "build:app": "pnpm --filter @app/domain build && pnpm --filter @app/api build && pnpm --filter @app/web build"
   },
   "devDependencies": {
-    "@yss123/cage-cli": "0.3.1",
-    "@yss123/cage-testkit": "0.3.1",
-    "@yss123/cage-lint": "0.3.1",
+    "@yss123/cage-cli": "0.3.2",
+    "@yss123/cage-testkit": "0.3.2",
+    "@yss123/cage-lint": "0.3.2",
     "@types/node": "^24.3.0",
     "typescript": "~5.9.3",
     "vitest": "^4.1.12",

package/templates/blank/packages/contracts/package.json

@@ -10,7 +10,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@yss123/cage-client": "0.3.1",
+    "@yss123/cage-client": "0.3.2",
     "zod": "^4.1.5"
   }
 }

package/templates/blank/packages/domain/package.json

@@ -14,11 +14,11 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@yss123/cage-kernel": "0.3.1",
-    "@yss123/cage-admin": "0.3.1",
-    "@yss123/cage-approval": "0.3.1",
-    "@yss123/cage-connectors": "0.3.1",
-    "@yss123/cage-ai": "0.3.1",
+    "@yss123/cage-kernel": "0.3.2",
+    "@yss123/cage-admin": "0.3.2",
+    "@yss123/cage-approval": "0.3.2",
+    "@yss123/cage-connectors": "0.3.2",
+    "@yss123/cage-ai": "0.3.2",
     "zod": "^4.1.5"
   }
 }

package/templates/app/docs/ai/README.md

@@ -1,103 +0,0 @@
-# 业务开发指南（给 Codex 等编程工具）
-
-这是 `create-cage-app` 产物自带的业务开发资料。目标是让 Codex 等编程工具只读当前项目，就能增加业务对象、操作、审批、报表和页面。先读根目录 `AGENTS.md`，再按任务定位本页资料；无需另行克隆 Cage 框架仓库。
-
-## 先认识当前应用
-
-| 目录 | 开发业务时放什么 |
-| --- | --- |
-| `packages/domain/src/modules/<业务>` | 按业务集中聚合、命令、事件、审批、查询与任务；跨模块反应放 workflows，外部协议放 integrations |
-| `packages/contracts/src/aggregates`、`queries` | 按聚合目录生成 API 与类型；通过根 @app/contracts 使用，通过 gen 更新 |
-| `apps/api/src` | API 与 worker 的薄启动入口；普通业务不在这里写路由 |
-| `apps/web/src/app`、`modules`、`shared` | 应用组合 / 业务页面与交互 / 无具体业务归属的共用代码 |
-| `db/migrations` | 生成后审查的迁移；更新已有数据库中的表 |
-| `.env` / `.env.example` | 本机配置 / 不含真实凭证的配置说明 |
-| `docs/ai`、`docs/errors` | 业务开发方法与错误排查 |
-
-下文路径均相对**应用根目录**，即生成项目的 `package.json` 所在目录。框架包使用 `@yss123/cage-*`，作为依赖安装；当前项目不应复制或重新实现这些包。框架维护者在源码仓库读本页时，应用根目录为 `examples/purchase-admin`。
-
-创建时可选 `blank`（空白业务项目）或 `purchase`（采购示例项目）。空白项目只有组织基础模型，新增客户业务写入根目录的 `packages/domain/src`；采购参考源码放在 `docs/examples/purchase-admin`，不参与注册、编译或建表。阅读本指南中的采购路径时，空白项目在该参考目录下查找，采购项目直接在应用根目录查找。先读本项目 AGENTS.md 的模板说明，不能把参考代码误当成已运行的业务。
-
-## 推荐阅读顺序
-
-| 顺序 | 资料 | 读完应能回答 |
-| --- | --- | --- |
-| 1 | [架构与执行模型](architecture.md) | 聚合是什么？为什么写入必须走命令？数据库由谁连接？ |
-| 2 | [工程目录与代码组织](project-structure.md) | 新业务放哪里？页面如何拆分？哪些依赖会被门禁阻止？ |
-| 3 | [原语与最小业务](primitives.md) | 如何新增字段、CRUD 命令、读依赖、事件和查询？ |
-| 编码必读 | [详细中文注释规范](commenting.md) | 如何说明文件职责、API、字段、关键流程、权限/事务与失败边界，并同步维护注释？ |
-| 开发前 | [本体查询与 AI 上下文](ontology-context.md) | 按需求查哪些代码？为什么关联？候选、证据与子图边界怎么判断？ |
-| 开发与排错 | [能力发现与状态诊断](diagnostics.md) | 公开 API 有什么？注册/契约/进程哪里过期？如何查执行时间线和授权拒绝？ |
-| 按需 | [对象关系](relations.md) | 如何在 fields 中声明一对一、一对多、多对多，修改关联并分页读取？ |
-| 复杂审批 | [审批流转、并行与流程时效](approvals.md) | 如何声明 AND 并行与汇合，按字段选人、候选领取、转办/委派/加签，并使用框架节点时限、站内提醒、催办和已读？ |
-| 前端必读 | [业务路由与浏览器验收](routing.md) | 列表/详情如何获得独立 URL？登录回跳、404、/admin 和部署回退怎样验收？ |
-| 原生 AI | [智能助理与 AI 审批](intelligence.md) | 如何启用后端、配置三态审核、生成工具、传入页面快照和接入 SDK？ |
-| 4 | [标准采购范例导读](purchase-example.md) | 一次提交如何进入审批、锁库存、推 ERP、释放资源？ |
-| 5 | [开发步骤](workflow.md) | 改哪个文件？运行哪些命令？检查结果在哪里？ |
-| 6 | [业务任务配方](recipes.md) | 如何从采购演示换成自己的业务？常见需求如何交给 AI？ |
-| 7 | [业务页导入导出](transfers.md) | 如何提交任务、准备 CSV、查询状态、下载和展示报告？ |
-| 8 | [排错方法](troubleshooting.md)、[错误码册](../errors/README.md) | 如何区分配置、权限、业务失败和异步死信？ |
-| 按需 | [文件字段与断点续传](files.md) | 私有上传、分片恢复、命令绑定、下载授权和存储部署 |
-
-第一次先读架构、目录规范和原语，再沿范例读代码。接到业务需求后先运行 `pnpm exec cage context "需求关键词"`，确认候选入口，再按源码位置阅读对应实现。
-
-框架源码与脚手架应用都要求详细中文注释。新建或修改代码时按[注释规范](commenting.md)同步说明文件职责与调用链、导出 API/类型字段、组件/hooks 和关键流程的“做什么、为什么、怎么做、边界”；修改既有行为时连同相关上下游说明一起更新。注释属于交付内容，不能用“代码自解释”免除，也不能以逐行翻译或注释字数代替质量。
-
-不确定框架支持什么时先用 `pnpm exec cage capabilities 关键词 --format json` 查看当前版本公开签名；功能未生效时用 `pnpm exec cage doctor` 区分注册、生成、构建、迁移、授权和实际进程。未检查项为 `unknown`，不能作为验证通过。
-
-遇到 AI 审批、业务助理、随页助理、模型管理、性格或 Responses 需求，先读[原生智能化指南](intelligence.md)。这些是框架可选能力：后端循环、工具、会话与偏好记忆、HTTP 和 SDK 由框架提供；应用配置声明、策略、授权、页面快照及界面。入口不要求每次加载整份本体或全部指南，按本次任务读取相关章节即可。
-
-## 按任务找入口
-
-| 用户需求 | 优先修改 | 需要一起考虑 |
-| --- | --- | --- |
-| 增加业务对象、字段 | `packages/domain/src/modules/<业务>` | 模块公开入口、范围字段、不变量、契约、迁移、角色授权、图谱中文名 |
-| 增加对象关联 | `fields` 的 ref / hasMany / manyToMany；见[关系指南](relations.md) | 归属命令、双侧权限与范围、目标分页、迁移；纯关联不手写中间表聚合 |
-| 增加操作按钮 | 领域命令 + `apps/web/src/modules/<业务>` | 状态迁移、调用身份、错误展示、提交幂等键 |
-| 增加列表、详情或新页面 | 模块 pages + app 路由表 | URL、查询条件、深链接、刷新、前进后退、登录回跳；见[路由指南](routing.md) |
-| 增加报表 | 所属领域模块 `queries.ts` | `reads`、`safe.*`、参数化、调用人 read 权限 |
-| 修改审批顺序/条件/并行/选人 | 所属领域模块 `approvals.ts` | `parallel/branch` 的 AND 汇合与完整 currentSteps、`routable`、`approver.field` 的 UUID/数组、角色/负责人数据、同租户 active 用户及结论命令约束；见[任务流转](approvals.md) |
-| 候选领取、转办、委派和前后加签 | 人工 `step` 的 `assignment/actions` + 客户端任务接口 | 候选规则与权限实时检查、waiting 依赖、任务 revision、旧实例快照、系统迁移；Admin/采购已有领取、释放、归还，采购还提供协作名录选人、转办/委派/三种加签及分页人工历史 |
-| 节点时限、流程提醒与申请人催办 | `step.sla`、`route.reminders` + 导出的 `approvalOperations()` | 自然分钟、逐节点开启计时、同实例共享催办冷却；并行催办携带 expectedSteps；沿用框架 Admin 申请/提醒页或 SDK，见[流程时效](approvals.md) |
-| AI 预审、退回修改、转人工 | 现有 `step` 的 `kind: 'ai'` + `approval` 绑定 | 策略、取证字段/查询、`automatedBy` 角色、结论命令及 `handoff`；见[智能化指南](intelligence.md) |
-| 业务助理、随页悬浮窗 | domain 导出 `ai()`；页面接 `useAssistant` 与 `useAiPageContext` | 业务权限、页面快照、流式 Markdown、写入确认；界面由应用实现 |
-| 模型动态配置、Responses、性格 | `managedModel` 与框架 Admin 页面 | 部署加密密钥、管理权限、实际网关能力、性格仅影响表达 |
-| 取消后释放占用 | `workflows/<相关业务>.ts` + 领域事件/命令 | 所有离开持有状态的路径、同事务/异步选择 |
-| 接 ERP 或其他系统 | `integrations/<系统名>.ts` | schema、密钥名、白名单、幂等、回调验签、重试 |
-| 业务页导入/导出 | 业务前端调用已有接口 | 任务状态、worker、权限、导入目标命令；不固定到系统管理页 |
-| 文件上传/业务附件 | file/files 字段 + 用户命令 + 客户端上传任务 | 断点续传、当前权限、命令绑定、私有存储及清理；见[文件指南](files.md) |
-| 新业务没出现在图或 API | domain 统一入口 | 顶层 `export const`、导出名唯一、入口 re-export |
-| 框架无法表达业务 | 先核对公开导出与范例 | 说明能力缺口；不要编造 API 或把业务分支塞进内核 |
-
-## 三份协作材料各管什么
-
-- **AGENTS.md** 是工作入口：必守边界、目录、顺序和验证要求。`<!-- cage:begin ... -->` 到 `<!-- cage:end -->` 为框架托管区，`cage sync` 更新它；项目自己的规则放在外面。
-- **标准范例** 是可运行证据：采购模板包含完整运行链路，空白模板保留离线参考源码。按需学习其中模式，客户业务仍写在本项目自己的 domain 和页面中。
-- **错误码册** 是诊断索引：按真实错误码查位置、触发原因、修复步骤和正反例；不要靠放开权限或关闭门禁“修好”报错。
-
-`docs/ai` 与 `docs/errors` 已放入分发模板，创建项目时一起复制，可离线阅读。框架仓库中的标准范例使用根目录的规范文档，资料位置由应用 AGENTS.md 指明。
-
-## 当前实现边界
-
-以下区分可避免 agent 把方案中的愿景写成不存在的功能。
-
-| 已有能力 | 使用边界 |
-| --- | --- |
-| 真实 PostgreSQL 连接、分账号、表结构迁移 | 连接已有数据库；`init` 不建库；不会自动识别并接管任意历史表 |
-| 聚合/命令、能力与范围、掩码、审计、outbox、worker | handler 不做数据库/网络 IO；生产角色不会自动拿到新能力 |
-| fields 中的 ref / hasMany / manyToMany | hasMany 为只读反查；manyToMany 自动中间表并随主对象事务写入，公开读取独立分页；双向集合不会自动互为镜像 |
-| 本体抽取、中文检索/节点/路径/AI 上下文、图规则、图谱、生成、影响分析与门禁 | 上下文注明证据、源码和覆盖边界；名称与测试匹配是候选线索，不能证明任意 JS 正确；跳过用例仍需补足 |
-| 有界集合 reactionEach、显式步骤 order | 稳定唯一键排序后串行调用目标命令；同事务整体回滚，异步链按 outbox 恢复；不是并行写表接口 |
-| capabilities、doctor、timeline、explain、snapshot | 实际运行诊断需要受控会话与权限；未取得的证据为 unknown，授权解释不执行 handler |
-| 代码审批路由与任务流转 | 顺序/条件、`parallel/branch` 结构化 AND 分支与汇合、any/all、字段选人、候选领取/释放、转办、单层委派归还、前后/并行必签和动作历史；候选池仅支持 any，追加票全部必签。条件和依赖随提交冻结，currentStep 仅为最小活动索引；尚无任意连线/循环/OR 网关、岗位/代理规则、通用恢复、任意 JS 选人或在途迁移，见[任务流转](approvals.md) |
-| 审批时限、站内提醒与催办 | 人工节点按实际开启时间计算自然分钟 SLA，worker 持久投递临期/超时提醒；申请人可按完整活动集合催办，同实例共享冷却，接收人可标已读。旧快照不自动获得政策；尚无工作日历、自动升级、抄送或邮件/短信通知 |
-| 审批界面与 SDK | Admin/采购待办可领取、释放、归还受托任务并查看等待加签；采购另有协作名录选人器、转办/委派/三种加签及分页人工历史，view 查询参数保留视图。启用运营后通用 Admin 提供我的申请、催办和流程提醒；页面仍需应用启用、真实授权与浏览器验收。AI 助理目前只查询本人待办及提交决定，无人员管理写工具 |
-| 原生 AI 审批与领域助理 | 现有 `step` 支持 `kind: 'ai'`；三态审核、自动工具、会话及偏好记忆可复用；需显式启用、授权并做模型质量验收 |
-| Admin 模型与性格、助理 SDK | 动态模型连接和性格管理；Chat Completions / Responses 兼容性以实际服务为准；SDK 提供流式状态与页面快照，悬浮窗和 Markdown 由应用实现 |
-| 连接器 fake、出站、入站验签、同步记录 | fake 不等于真实 ERP 联调，也不等于完整请求录制/回放平台 |
-| 异步 CSV 导入/导出接口与客户端任务查询 | 界面由业务项目决定；导出结果不是可直接回导的命令输入模板 |
-| 私有文件字段、流式分片上传、暂停与续传、范围下载 | 默认本地存储，提供对象存储适配接口；尚无内置 S3/OSS、签名直传、病毒扫描及文件共享 |
-| 组织模型、系统管理界面 | 暂无移动部门（改上级）的完整支持、菜单配置页 |
-| 库存锁采购范例 | 演示资源生命周期；不是仓库级并发库存扣减、退货或 ERP 撤销补偿系统 |
-
-文档与实现冲突时，以当前代码和检查结果为依据，指出冲突并修正文档；不要默默扩展公开 API。规划、代码存在、构建通过、真实联调通过是不同状态，交付时分别说明。

package/templates/blank/docs/ai/README.md

@@ -1,103 +0,0 @@
-# 业务开发指南（给 Codex 等编程工具）
-
-这是 `create-cage-app` 产物自带的业务开发资料。目标是让 Codex 等编程工具只读当前项目，就能增加业务对象、操作、审批、报表和页面。先读根目录 `AGENTS.md`，再按任务定位本页资料；无需另行克隆 Cage 框架仓库。
-
-## 先认识当前应用
-
-| 目录 | 开发业务时放什么 |
-| --- | --- |
-| `packages/domain/src/modules/<业务>` | 按业务集中聚合、命令、事件、审批、查询与任务；跨模块反应放 workflows，外部协议放 integrations |
-| `packages/contracts/src/aggregates`、`queries` | 按聚合目录生成 API 与类型；通过根 @app/contracts 使用，通过 gen 更新 |
-| `apps/api/src` | API 与 worker 的薄启动入口；普通业务不在这里写路由 |
-| `apps/web/src/app`、`modules`、`shared` | 应用组合 / 业务页面与交互 / 无具体业务归属的共用代码 |
-| `db/migrations` | 生成后审查的迁移；更新已有数据库中的表 |
-| `.env` / `.env.example` | 本机配置 / 不含真实凭证的配置说明 |
-| `docs/ai`、`docs/errors` | 业务开发方法与错误排查 |
-
-下文路径均相对**应用根目录**，即生成项目的 `package.json` 所在目录。框架包使用 `@yss123/cage-*`，作为依赖安装；当前项目不应复制或重新实现这些包。框架维护者在源码仓库读本页时，应用根目录为 `examples/purchase-admin`。
-
-创建时可选 `blank`（空白业务项目）或 `purchase`（采购示例项目）。空白项目只有组织基础模型，新增客户业务写入根目录的 `packages/domain/src`；采购参考源码放在 `docs/examples/purchase-admin`，不参与注册、编译或建表。阅读本指南中的采购路径时，空白项目在该参考目录下查找，采购项目直接在应用根目录查找。先读本项目 AGENTS.md 的模板说明，不能把参考代码误当成已运行的业务。
-
-## 推荐阅读顺序
-
-| 顺序 | 资料 | 读完应能回答 |
-| --- | --- | --- |
-| 1 | [架构与执行模型](architecture.md) | 聚合是什么？为什么写入必须走命令？数据库由谁连接？ |
-| 2 | [工程目录与代码组织](project-structure.md) | 新业务放哪里？页面如何拆分？哪些依赖会被门禁阻止？ |
-| 3 | [原语与最小业务](primitives.md) | 如何新增字段、CRUD 命令、读依赖、事件和查询？ |
-| 编码必读 | [详细中文注释规范](commenting.md) | 如何说明文件职责、API、字段、关键流程、权限/事务与失败边界，并同步维护注释？ |
-| 开发前 | [本体查询与 AI 上下文](ontology-context.md) | 按需求查哪些代码？为什么关联？候选、证据与子图边界怎么判断？ |
-| 开发与排错 | [能力发现与状态诊断](diagnostics.md) | 公开 API 有什么？注册/契约/进程哪里过期？如何查执行时间线和授权拒绝？ |
-| 按需 | [对象关系](relations.md) | 如何在 fields 中声明一对一、一对多、多对多，修改关联并分页读取？ |
-| 复杂审批 | [审批流转、并行与流程时效](approvals.md) | 如何声明 AND 并行与汇合，按字段选人、候选领取、转办/委派/加签，并使用框架节点时限、站内提醒、催办和已读？ |
-| 前端必读 | [业务路由与浏览器验收](routing.md) | 列表/详情如何获得独立 URL？登录回跳、404、/admin 和部署回退怎样验收？ |
-| 原生 AI | [智能助理与 AI 审批](intelligence.md) | 如何启用后端、配置三态审核、生成工具、传入页面快照和接入 SDK？ |
-| 4 | [标准采购范例导读](purchase-example.md) | 一次提交如何进入审批、锁库存、推 ERP、释放资源？ |
-| 5 | [开发步骤](workflow.md) | 改哪个文件？运行哪些命令？检查结果在哪里？ |
-| 6 | [业务任务配方](recipes.md) | 如何从采购演示换成自己的业务？常见需求如何交给 AI？ |
-| 7 | [业务页导入导出](transfers.md) | 如何提交任务、准备 CSV、查询状态、下载和展示报告？ |
-| 8 | [排错方法](troubleshooting.md)、[错误码册](../errors/README.md) | 如何区分配置、权限、业务失败和异步死信？ |
-| 按需 | [文件字段与断点续传](files.md) | 私有上传、分片恢复、命令绑定、下载授权和存储部署 |
-
-第一次先读架构、目录规范和原语，再沿范例读代码。接到业务需求后先运行 `pnpm exec cage context "需求关键词"`，确认候选入口，再按源码位置阅读对应实现。
-
-框架源码与脚手架应用都要求详细中文注释。新建或修改代码时按[注释规范](commenting.md)同步说明文件职责与调用链、导出 API/类型字段、组件/hooks 和关键流程的“做什么、为什么、怎么做、边界”；修改既有行为时连同相关上下游说明一起更新。注释属于交付内容，不能用“代码自解释”免除，也不能以逐行翻译或注释字数代替质量。
-
-不确定框架支持什么时先用 `pnpm exec cage capabilities 关键词 --format json` 查看当前版本公开签名；功能未生效时用 `pnpm exec cage doctor` 区分注册、生成、构建、迁移、授权和实际进程。未检查项为 `unknown`，不能作为验证通过。
-
-遇到 AI 审批、业务助理、随页助理、模型管理、性格或 Responses 需求，先读[原生智能化指南](intelligence.md)。这些是框架可选能力：后端循环、工具、会话与偏好记忆、HTTP 和 SDK 由框架提供；应用配置声明、策略、授权、页面快照及界面。入口不要求每次加载整份本体或全部指南，按本次任务读取相关章节即可。
-
-## 按任务找入口
-
-| 用户需求 | 优先修改 | 需要一起考虑 |
-| --- | --- | --- |
-| 增加业务对象、字段 | `packages/domain/src/modules/<业务>` | 模块公开入口、范围字段、不变量、契约、迁移、角色授权、图谱中文名 |
-| 增加对象关联 | `fields` 的 ref / hasMany / manyToMany；见[关系指南](relations.md) | 归属命令、双侧权限与范围、目标分页、迁移；纯关联不手写中间表聚合 |
-| 增加操作按钮 | 领域命令 + `apps/web/src/modules/<业务>` | 状态迁移、调用身份、错误展示、提交幂等键 |
-| 增加列表、详情或新页面 | 模块 pages + app 路由表 | URL、查询条件、深链接、刷新、前进后退、登录回跳；见[路由指南](routing.md) |
-| 增加报表 | 所属领域模块 `queries.ts` | `reads`、`safe.*`、参数化、调用人 read 权限 |
-| 修改审批顺序/条件/并行/选人 | 所属领域模块 `approvals.ts` | `parallel/branch` 的 AND 汇合与完整 currentSteps、`routable`、`approver.field` 的 UUID/数组、角色/负责人数据、同租户 active 用户及结论命令约束；见[任务流转](approvals.md) |
-| 候选领取、转办、委派和前后加签 | 人工 `step` 的 `assignment/actions` + 客户端任务接口 | 候选规则与权限实时检查、waiting 依赖、任务 revision、旧实例快照、系统迁移；Admin/采购已有领取、释放、归还，采购还提供协作名录选人、转办/委派/三种加签及分页人工历史 |
-| 节点时限、流程提醒与申请人催办 | `step.sla`、`route.reminders` + 导出的 `approvalOperations()` | 自然分钟、逐节点开启计时、同实例共享催办冷却；并行催办携带 expectedSteps；沿用框架 Admin 申请/提醒页或 SDK，见[流程时效](approvals.md) |
-| AI 预审、退回修改、转人工 | 现有 `step` 的 `kind: 'ai'` + `approval` 绑定 | 策略、取证字段/查询、`automatedBy` 角色、结论命令及 `handoff`；见[智能化指南](intelligence.md) |
-| 业务助理、随页悬浮窗 | domain 导出 `ai()`；页面接 `useAssistant` 与 `useAiPageContext` | 业务权限、页面快照、流式 Markdown、写入确认；界面由应用实现 |
-| 模型动态配置、Responses、性格 | `managedModel` 与框架 Admin 页面 | 部署加密密钥、管理权限、实际网关能力、性格仅影响表达 |
-| 取消后释放占用 | `workflows/<相关业务>.ts` + 领域事件/命令 | 所有离开持有状态的路径、同事务/异步选择 |
-| 接 ERP 或其他系统 | `integrations/<系统名>.ts` | schema、密钥名、白名单、幂等、回调验签、重试 |
-| 业务页导入/导出 | 业务前端调用已有接口 | 任务状态、worker、权限、导入目标命令；不固定到系统管理页 |
-| 文件上传/业务附件 | file/files 字段 + 用户命令 + 客户端上传任务 | 断点续传、当前权限、命令绑定、私有存储及清理；见[文件指南](files.md) |
-| 新业务没出现在图或 API | domain 统一入口 | 顶层 `export const`、导出名唯一、入口 re-export |
-| 框架无法表达业务 | 先核对公开导出与范例 | 说明能力缺口；不要编造 API 或把业务分支塞进内核 |
-
-## 三份协作材料各管什么
-
-- **AGENTS.md** 是工作入口：必守边界、目录、顺序和验证要求。`<!-- cage:begin ... -->` 到 `<!-- cage:end -->` 为框架托管区，`cage sync` 更新它；项目自己的规则放在外面。
-- **标准范例** 是可运行证据：采购模板包含完整运行链路，空白模板保留离线参考源码。按需学习其中模式，客户业务仍写在本项目自己的 domain 和页面中。
-- **错误码册** 是诊断索引：按真实错误码查位置、触发原因、修复步骤和正反例；不要靠放开权限或关闭门禁“修好”报错。
-
-`docs/ai` 与 `docs/errors` 已放入分发模板，创建项目时一起复制，可离线阅读。框架仓库中的标准范例使用根目录的规范文档，资料位置由应用 AGENTS.md 指明。
-
-## 当前实现边界
-
-以下区分可避免 agent 把方案中的愿景写成不存在的功能。
-
-| 已有能力 | 使用边界 |
-| --- | --- |
-| 真实 PostgreSQL 连接、分账号、表结构迁移 | 连接已有数据库；`init` 不建库；不会自动识别并接管任意历史表 |
-| 聚合/命令、能力与范围、掩码、审计、outbox、worker | handler 不做数据库/网络 IO；生产角色不会自动拿到新能力 |
-| fields 中的 ref / hasMany / manyToMany | hasMany 为只读反查；manyToMany 自动中间表并随主对象事务写入，公开读取独立分页；双向集合不会自动互为镜像 |
-| 本体抽取、中文检索/节点/路径/AI 上下文、图规则、图谱、生成、影响分析与门禁 | 上下文注明证据、源码和覆盖边界；名称与测试匹配是候选线索，不能证明任意 JS 正确；跳过用例仍需补足 |
-| 有界集合 reactionEach、显式步骤 order | 稳定唯一键排序后串行调用目标命令；同事务整体回滚，异步链按 outbox 恢复；不是并行写表接口 |
-| capabilities、doctor、timeline、explain、snapshot | 实际运行诊断需要受控会话与权限；未取得的证据为 unknown，授权解释不执行 handler |
-| 代码审批路由与任务流转 | 顺序/条件、`parallel/branch` 结构化 AND 分支与汇合、any/all、字段选人、候选领取/释放、转办、单层委派归还、前后/并行必签和动作历史；候选池仅支持 any，追加票全部必签。条件和依赖随提交冻结，currentStep 仅为最小活动索引；尚无任意连线/循环/OR 网关、岗位/代理规则、通用恢复、任意 JS 选人或在途迁移，见[任务流转](approvals.md) |
-| 审批时限、站内提醒与催办 | 人工节点按实际开启时间计算自然分钟 SLA，worker 持久投递临期/超时提醒；申请人可按完整活动集合催办，同实例共享冷却，接收人可标已读。旧快照不自动获得政策；尚无工作日历、自动升级、抄送或邮件/短信通知 |
-| 审批界面与 SDK | Admin/采购待办可领取、释放、归还受托任务并查看等待加签；采购另有协作名录选人器、转办/委派/三种加签及分页人工历史，view 查询参数保留视图。启用运营后通用 Admin 提供我的申请、催办和流程提醒；页面仍需应用启用、真实授权与浏览器验收。AI 助理目前只查询本人待办及提交决定，无人员管理写工具 |
-| 原生 AI 审批与领域助理 | 现有 `step` 支持 `kind: 'ai'`；三态审核、自动工具、会话及偏好记忆可复用；需显式启用、授权并做模型质量验收 |
-| Admin 模型与性格、助理 SDK | 动态模型连接和性格管理；Chat Completions / Responses 兼容性以实际服务为准；SDK 提供流式状态与页面快照，悬浮窗和 Markdown 由应用实现 |
-| 连接器 fake、出站、入站验签、同步记录 | fake 不等于真实 ERP 联调，也不等于完整请求录制/回放平台 |
-| 异步 CSV 导入/导出接口与客户端任务查询 | 界面由业务项目决定；导出结果不是可直接回导的命令输入模板 |
-| 私有文件字段、流式分片上传、暂停与续传、范围下载 | 默认本地存储，提供对象存储适配接口；尚无内置 S3/OSS、签名直传、病毒扫描及文件共享 |
-| 组织模型、系统管理界面 | 暂无移动部门（改上级）的完整支持、菜单配置页 |
-| 库存锁采购范例 | 演示资源生命周期；不是仓库级并发库存扣减、退货或 ERP 撤销补偿系统 |
-
-文档与实现冲突时，以当前代码和检查结果为依据，指出冲突并修正文档；不要默默扩展公开 API。规划、代码存在、构建通过、真实联调通过是不同状态，交付时分别说明。