@yss123/cage-cli 0.3.1 → 0.4.0

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/app/docs/ai/recipes.md

@@ -1,89 +0,0 @@
-# 业务任务配方
-
-[返回学习入口](README.md) · [原语示例](primitives.md) · [开发步骤](workflow.md)
-
-本页用于把用户的业务描述转成 Cage 项目的可执行修改。按需要读对应配方即可，不需要修改框架内部。
-
-需要 AI 审批、业务助理、随页聊天、模型管理或性格配置时，先用 `cage capabilities` 查框架能力，再按[原生智能化指南](intelligence.md)接入。普通业务建模仍按下文声明聚合和命令；接入已有框架服务无需另建一套通用后端。
-
-## 先把需求落到一张业务表
-
-开始编码前，从用户需求或现有业务中确定以下信息。能从上下文确认的直接使用；真正缺失且影响实现的再询问，不要为技术细节反复让用户确认。
-
-| 业务问题 | 落到什么声明 | 例如 |
-| --- | --- | --- |
-| 管理什么对象？有哪些字段？ | aggregate、字段与 Zod 输入 | 报销单：金额、事由、部门、提单人、明细 |
-| 有哪些阶段？谁能做什么？ | states、command、invokedBy | 草稿可编辑、提交后审批、完成后不可撤回 |
-| 数据属于谁/哪个部门？ | 范围字段 + 角色数据范围 | 申请人看本人，经理看部门及下级 |
-| 每次操作有什么硬规则？ | constraints、invariants、fail | 提单人不可审批、额度上限、金额必须为正 |
-| 成功后还要发生什么？ | event、reaction、approval、outbound | 启动审批、登记额度占用、推送财务系统 |
-| 取消/失败要撤销什么？ | cancelOn、释放命令、补偿流程 | 取消待办、释放占用、远端撤销或人工补偿 |
-| 页面需要看什么？ | 生成的 list/get、query、业务页面 | 分页、详情、按状态汇总、导出与导入 |
-
-## 新增一个普通管理对象
-
-按[最小便笺业务](primitives.md)新增 `packages/domain/src/modules/<业务>/<对象>.ts`：字段、范围、不变量、create/update/archive 命令。采用唯一的导出名和必要的 `name` 覆盖，避免 index 的 `export *` 丢失重名符号。
-
-从模块 index 到 domain 入口导出后运行 check/gen，审查迁移，再在 `apps/web/src/modules/<业务>` 使用生成 contracts 做列表、详情、表单和操作按钮，经模块公开入口注册到 app 路由。列表和详情都有独立 URL，筛选/分页进入 query，按[浏览器配方](routing.md)检查导航。最后给角色授权并补图谱中文名。完整归属规则见[目录规范](project-structure.md)。不要手写后端增删改查路由、ORM 实体与 repository，也不要复制框架鉴权代码。
-
-完成标准：授权用户能创建和修改，范围外数据不可见，归档后的允许行为符合业务要求，生成契约和迁移一致。没有审批需求时不必添加审批；没有外部系统时不必添加连接器。
-
-## 增加一对多或多对多
-
-参考[对象关系](relations.md)，在聚合的同一个 fields 中添加 `hasMany/manyToMany`。纯关联交给框架生成中间表；关系本身有职位、状态等业务属性时再建立有意义的聚合。hasMany 反查目标上的 ref，修改归属执行子对象命令；manyToMany 用所属对象的命令返回 ID 数组。
-
-生成后前端通过 `对象.related.字段(id, params)` 或 `use对象Related字段` 分页读取，不从普通 get 响应猜测已加载关联。给角色配置两侧 read 能力与范围；添加成员时也检查目标可见性。修改关系执行版本检查，不能把当前一页当作完整集合替换。不要创建新的业务连接池、ORM 中间实体或手写关系路由。
-
-## 给业务单据加审批
-
-1. 为单据补草稿、待审批、通过、驳回等真实状态及命令；提交时发事件。
-2. 通过/驳回使用 process 命令，根据业务添加职责分离、额度等约束。
-3. 添加 approval 绑定和 route；只将需要的字段放进 routable，取消命令发事件并配置 cancelOn。
-4. 配置实际部门负责人、角色或指定用户；给审批人配置能力、范围和额度。
-5. 页面通过待办接口操作。通过后需占用资源时用反应调用资源命令，按业务一致性选择同事务。
-
-完成标准：提交生成待办、正确的人审批、越权和自审批拒绝、取消能结束待办、资源配对完整。转办、委派归还和当前节点并行必签见[审批任务流转](approvals.md)，须显式启用政策并传任务版本。任意流程设计器、动态 JS 选人、前后加签和指定节点退回仍需明确扩展范围。
-
-## 加入 AI 审批或随页助理
-
-先检查 domain 是否已经导出 `ai()`，再按需求修改已有声明或启用一次。AI 审批配置在业务模块的现有 `step` 内，填写 `kind: 'ai'`、审核策略、取证字段/查询与 `handoff`，由 `approval` 绑定自动执行角色和结论命令。业务助理使用框架生成的工具，前端通过 `useAssistant` 与 `useAiPageContext` 接入当前页面；悬浮窗、Markdown 和确认交互由应用实现。
-
-模型地址、协议和密钥通过 `managedModel` 对应的 Admin 配置管理，性格也使用框架现有管理页。先完成系统迁移和必要授权，按[智能化指南](intelligence.md)的接入顺序、SDK 示例和验收步骤验证。分别说明框架支持、应用已启用和真实联调结果；空白模板中的参考代码不参与运行。
-
-## 增加报表或复杂列表
-
-普通分页和详情先使用生成的 list/get；汇总、联表等需求再添加 query。写清 reads、输入 schema，选择参数化 SQL 或 build；只查对应 safe 视图，不为“报表方便”切到管理员连接。
-
-重新生成后使用 `queries.你的查询()` 或生成 hook。检查真实调用人的 read 能力和数据范围；管理员能看到结果不能证明普通用户的报表正确。
-
-## 接入外部系统
-
-沿 `packages/domain/src/integrations/erp.ts` 的结构声明 host、密钥名、操作 schema、outbound 和 inbound。远端成功后的字段回写也走 external 命令。先用 fake 完成本地链路，再在测试环境做真实联调。
-
-明确重复请求如何识别、哪些错误重试、回执晚到怎么办、取消后如何补偿。不要假设本地事务可以回滚已经提交给第三方的写入。
-
-## 增加导入或导出
-
-在客户实际需要的业务页调用客户端/生成契约，展示任务进行中、完成和失败。导入映射到用户可调用的命令，准备与该命令输入匹配的 CSV；不要生成直接写业务表的上传接口。
-
-明确逐行还是整批原子模式、失败报告如何呈现、任务过期如何处理。任务提交成功不能立即标成导入/导出完成，worker 与下载时授权也是链路的一部分。完整方法、CSV 例子与协议见[业务页导入导出](transfers.md)。
-
-## 由采购演示换成客户业务
-
-空白模板不需要清理采购业务，直接从 `packages/domain/src` 新增自己的声明和页面；参考源码在 `docs/examples/purchase-admin`，不在运行入口中。下面的替换步骤只适用于采购模板。
-
-建议先保留运行薄壳和一条可验证的演示链路，新增真实业务并接通页面，再移除不需要的演示引用。清理时沿领域导出、反应、审批、连接器、查询、任务、页面和 graph.labels 一起检查，避免残留仍在运行的自动任务。
-
-组织模型仍从 `@yss123/cage-admin/domain` 导出。已执行迁移作为历史保留，新表/删表通过新迁移表达；需要保存旧数据时先制定迁移方案，不能只把整个 migrations 文件夹删除。
-
-## 给编程工具的任务模板
-
-```text
-阅读当前项目 AGENTS.md，按 docs/ai/README.md 找到本次需求对应的原语和标准范例。
-遵守 docs/ai/project-structure.md：领域和前端按业务建 modules，app 组合页面，shared 只放通用代码，不平铺 src 或堆进 main.tsx。
-业务：……；角色与数据范围：……；状态与允许动作：……；审批/外部系统/资源占用：……。
-先列出需要修改的 domain、页面、契约、迁移和授权，再直接完成实现。
-使用当前公开 API；对无法表达的需求说明具体缺口，不编造方法。
-生成文件通过 cage gen 更新，数据库使用已有 .env 配置，按改动完成必要验证。
-交付时说明用户如何体验、管理员需配置什么，以及通过/跳过/未执行的检查。
-```

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。规划、代码存在、构建通过、真实联调通过是不同状态，交付时分别说明。

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

@@ -1,89 +0,0 @@
-# 业务任务配方
-
-[返回学习入口](README.md) · [原语示例](primitives.md) · [开发步骤](workflow.md)
-
-本页用于把用户的业务描述转成 Cage 项目的可执行修改。按需要读对应配方即可，不需要修改框架内部。
-
-需要 AI 审批、业务助理、随页聊天、模型管理或性格配置时，先用 `cage capabilities` 查框架能力，再按[原生智能化指南](intelligence.md)接入。普通业务建模仍按下文声明聚合和命令；接入已有框架服务无需另建一套通用后端。
-
-## 先把需求落到一张业务表
-
-开始编码前，从用户需求或现有业务中确定以下信息。能从上下文确认的直接使用；真正缺失且影响实现的再询问，不要为技术细节反复让用户确认。
-
-| 业务问题 | 落到什么声明 | 例如 |
-| --- | --- | --- |
-| 管理什么对象？有哪些字段？ | aggregate、字段与 Zod 输入 | 报销单：金额、事由、部门、提单人、明细 |
-| 有哪些阶段？谁能做什么？ | states、command、invokedBy | 草稿可编辑、提交后审批、完成后不可撤回 |
-| 数据属于谁/哪个部门？ | 范围字段 + 角色数据范围 | 申请人看本人，经理看部门及下级 |
-| 每次操作有什么硬规则？ | constraints、invariants、fail | 提单人不可审批、额度上限、金额必须为正 |
-| 成功后还要发生什么？ | event、reaction、approval、outbound | 启动审批、登记额度占用、推送财务系统 |
-| 取消/失败要撤销什么？ | cancelOn、释放命令、补偿流程 | 取消待办、释放占用、远端撤销或人工补偿 |
-| 页面需要看什么？ | 生成的 list/get、query、业务页面 | 分页、详情、按状态汇总、导出与导入 |
-
-## 新增一个普通管理对象
-
-按[最小便笺业务](primitives.md)新增 `packages/domain/src/modules/<业务>/<对象>.ts`：字段、范围、不变量、create/update/archive 命令。采用唯一的导出名和必要的 `name` 覆盖，避免 index 的 `export *` 丢失重名符号。
-
-从模块 index 到 domain 入口导出后运行 check/gen，审查迁移，再在 `apps/web/src/modules/<业务>` 使用生成 contracts 做列表、详情、表单和操作按钮，经模块公开入口注册到 app 路由。列表和详情都有独立 URL，筛选/分页进入 query，按[浏览器配方](routing.md)检查导航。最后给角色授权并补图谱中文名。完整归属规则见[目录规范](project-structure.md)。不要手写后端增删改查路由、ORM 实体与 repository，也不要复制框架鉴权代码。
-
-完成标准：授权用户能创建和修改，范围外数据不可见，归档后的允许行为符合业务要求，生成契约和迁移一致。没有审批需求时不必添加审批；没有外部系统时不必添加连接器。
-
-## 增加一对多或多对多
-
-参考[对象关系](relations.md)，在聚合的同一个 fields 中添加 `hasMany/manyToMany`。纯关联交给框架生成中间表；关系本身有职位、状态等业务属性时再建立有意义的聚合。hasMany 反查目标上的 ref，修改归属执行子对象命令；manyToMany 用所属对象的命令返回 ID 数组。
-
-生成后前端通过 `对象.related.字段(id, params)` 或 `use对象Related字段` 分页读取，不从普通 get 响应猜测已加载关联。给角色配置两侧 read 能力与范围；添加成员时也检查目标可见性。修改关系执行版本检查，不能把当前一页当作完整集合替换。不要创建新的业务连接池、ORM 中间实体或手写关系路由。
-
-## 给业务单据加审批
-
-1. 为单据补草稿、待审批、通过、驳回等真实状态及命令；提交时发事件。
-2. 通过/驳回使用 process 命令，根据业务添加职责分离、额度等约束。
-3. 添加 approval 绑定和 route；只将需要的字段放进 routable，取消命令发事件并配置 cancelOn。
-4. 配置实际部门负责人、角色或指定用户；给审批人配置能力、范围和额度。
-5. 页面通过待办接口操作。通过后需占用资源时用反应调用资源命令，按业务一致性选择同事务。
-
-完成标准：提交生成待办、正确的人审批、越权和自审批拒绝、取消能结束待办、资源配对完整。转办、委派归还和当前节点并行必签见[审批任务流转](approvals.md)，须显式启用政策并传任务版本。任意流程设计器、动态 JS 选人、前后加签和指定节点退回仍需明确扩展范围。
-
-## 加入 AI 审批或随页助理
-
-先检查 domain 是否已经导出 `ai()`，再按需求修改已有声明或启用一次。AI 审批配置在业务模块的现有 `step` 内，填写 `kind: 'ai'`、审核策略、取证字段/查询与 `handoff`，由 `approval` 绑定自动执行角色和结论命令。业务助理使用框架生成的工具，前端通过 `useAssistant` 与 `useAiPageContext` 接入当前页面；悬浮窗、Markdown 和确认交互由应用实现。
-
-模型地址、协议和密钥通过 `managedModel` 对应的 Admin 配置管理，性格也使用框架现有管理页。先完成系统迁移和必要授权，按[智能化指南](intelligence.md)的接入顺序、SDK 示例和验收步骤验证。分别说明框架支持、应用已启用和真实联调结果；空白模板中的参考代码不参与运行。
-
-## 增加报表或复杂列表
-
-普通分页和详情先使用生成的 list/get；汇总、联表等需求再添加 query。写清 reads、输入 schema，选择参数化 SQL 或 build；只查对应 safe 视图，不为“报表方便”切到管理员连接。
-
-重新生成后使用 `queries.你的查询()` 或生成 hook。检查真实调用人的 read 能力和数据范围；管理员能看到结果不能证明普通用户的报表正确。
-
-## 接入外部系统
-
-沿 `packages/domain/src/integrations/erp.ts` 的结构声明 host、密钥名、操作 schema、outbound 和 inbound。远端成功后的字段回写也走 external 命令。先用 fake 完成本地链路，再在测试环境做真实联调。
-
-明确重复请求如何识别、哪些错误重试、回执晚到怎么办、取消后如何补偿。不要假设本地事务可以回滚已经提交给第三方的写入。
-
-## 增加导入或导出
-
-在客户实际需要的业务页调用客户端/生成契约，展示任务进行中、完成和失败。导入映射到用户可调用的命令，准备与该命令输入匹配的 CSV；不要生成直接写业务表的上传接口。
-
-明确逐行还是整批原子模式、失败报告如何呈现、任务过期如何处理。任务提交成功不能立即标成导入/导出完成，worker 与下载时授权也是链路的一部分。完整方法、CSV 例子与协议见[业务页导入导出](transfers.md)。
-
-## 由采购演示换成客户业务
-
-空白模板不需要清理采购业务，直接从 `packages/domain/src` 新增自己的声明和页面；参考源码在 `docs/examples/purchase-admin`，不在运行入口中。下面的替换步骤只适用于采购模板。
-
-建议先保留运行薄壳和一条可验证的演示链路，新增真实业务并接通页面，再移除不需要的演示引用。清理时沿领域导出、反应、审批、连接器、查询、任务、页面和 graph.labels 一起检查，避免残留仍在运行的自动任务。
-
-组织模型仍从 `@yss123/cage-admin/domain` 导出。已执行迁移作为历史保留，新表/删表通过新迁移表达；需要保存旧数据时先制定迁移方案，不能只把整个 migrations 文件夹删除。
-
-## 给编程工具的任务模板
-
-```text
-阅读当前项目 AGENTS.md，按 docs/ai/README.md 找到本次需求对应的原语和标准范例。
-遵守 docs/ai/project-structure.md：领域和前端按业务建 modules，app 组合页面，shared 只放通用代码，不平铺 src 或堆进 main.tsx。
-业务：……；角色与数据范围：……；状态与允许动作：……；审批/外部系统/资源占用：……。
-先列出需要修改的 domain、页面、契约、迁移和授权，再直接完成实现。
-使用当前公开 API；对无法表达的需求说明具体缺口，不编造方法。
-生成文件通过 cage gen 更新，数据库使用已有 .env 配置，按改动完成必要验证。
-交付时说明用户如何体验、管理员需配置什么，以及通过/跳过/未执行的检查。
-```