@yss123/cage-cli 0.2.0 → 0.3.1

package/templates/blank/docs/ai/purchase-example.md

@@ -11,9 +11,11 @@
 | `packages/domain/src/index.ts` | 哪些声明真正被注册 | 保留组织模型，导出新增业务，避免导出名冲突 |
 | `packages/domain/src/modules/inventory/inventory.ts` | 最简字段、创建命令、资源锁聚合 | scope.none 不等于无需授权；创建与释放都是命令 |
 | `packages/domain/src/modules/purchase/purchase-order.ts` | 单据生命周期、金额、明细、约束、事件 | 哪些字段由输入提供，哪些由内核维护；每个状态的允许操作 |
+| `packages/domain/src/modules/purchase/approval-members.ts` | 采购协作名录与公开业务姓名 | 名录读权限与系统用户资料分离；成员身份不授予审批权限 |
 | `packages/domain/src/workflows/purchase-inventory.ts` | 同事务建锁、异步释放 | acquires/releases 的配对及 map 返回 null 的原因 |
-| `packages/domain/src/modules/purchase/approvals.ts` | 启动/取消审批、条件步骤与选人 | routable、部门负责人、角色 code、结论命令 |
+| `packages/domain/src/modules/purchase/approvals.ts` | 启动/取消审批、专业会签、财务候选与任务动作 | routable、部门负责人、字段选人、候选领取、结论命令 |
 | `packages/domain/src/integrations/erp.ts` | 出站推单、成功回写、入站回调 | 白名单、secret 名、schema、幂等与 HMAC |
+| `packages/domain/src/integrations/intelligence.ts` | 消费框架托管模型和本体助理 | Admin 配置连接，通用工具由框架生成 |
 | `packages/domain/src/modules/purchase/queries.ts` | 按状态汇总 | reads、安全视图、命名参数 |
 | `packages/domain/src/modules/purchase/jobs.ts` | 过期草稿取消 | reads/calls 和 job 调用身份 |
 | `apps/api/src/main.ts`、`apps/api/src/worker.ts` | 如何启动框架与 worker | 保持薄装配，fake 只用于相应环境 |
@@ -27,8 +29,13 @@
 ```text
 采购员新建 → draft
   → submit → pending_approval + OrderSubmitted（同事务提交）
-  → worker 消费事件 → 按 poRoute 创建经理待办
-  → 经理审批；金额 > 50000 时还有财务步骤
+  → worker 消费事件 → AI 材料预审
+      → 材料不足：returnForChanges → draft，补充用途后重新提交、从头审核
+      → 疑难材料：在本节点创建人工接管待办
+      → 材料清楚：通过本节点，创建经理待办
+  → 部门经理审批
+  → 申请启用专业复核时：所选专业人员全部会签
+  → 金额 > 50000 时：财务共享候选任务，由 finance 成员领取后处理
   → 流程完成 → 调用 approve
       → 职责分离、额度、库存检查
       → approved + OrderApproved
@@ -41,11 +48,12 @@
 
 submit 返回成功只表示单据和事件已提交，不表示待办、ERP 或其他异步工作已经完成。worker 未运行时，单据可以已经处于待审批，但没有待办。
 
-### 为什么分三个聚合
+### 为什么分开单据、库存与协作名录
 
 - `PurchaseOrder` 管单据、审批结论和采购状态。
 - `Inventory` 是物料台账，提供库存检查的数据。
 - `InventoryLock` 记录某张订单的资源占用，使用订单 id 作为锁 id，让释放目标明确。
+- `ApprovalMember` 保存采购参与者可读取的公开业务姓名和专业说明。它引用真实用户，但不开放 `User.name` 等系统用户资料，也不代替角色授权。
 
 审批通过和建锁放在同一事务，是为了避免“单据已批准却没拿到资源”。ERP 网络请求放到 outbox，是因为远端调用无法与本地 PostgreSQL 共同回滚。
 
@@ -67,15 +75,35 @@ submit 返回成功只表示单据和事件已提交，不表示待办、ERP 或
 
 | 对象 | 配置要点 |
 | --- | --- |
-| 采购员 | 创建/查看/提交/取消采购单等所需能力，所属部门，以及采购单数据范围 |
-| 经理 | `PurchaseOrder.read/approve/reject`，适当数据范围，`approve` 的 `ceiling` 额度参数 |
+| 采购员 | 创建/查看/提交/取消采购单等所需能力，所属部门，以及采购单数据范围；配置专业复核需 `PurchaseOrder.setReviewers` 和 `ApprovalMember.read` |
+| 智能助理使用人 | 显式授予 `Sys.ai.use`；编辑用途还需 `PurchaseOrder.explainPurpose` |
+| 模型管理者 | `Sys.ai.models.manage`；在 `/admin/#/models` 配置并启用 `main`，部署主密钥见[智能能力指南](intelligence.md) |
+| 助理性格管理者 | `Sys.ai.personalities.manage`；在 `/admin/#/personalities` 编辑预设、自定义性格、设置默认并试聊 |
+| AI 预审角色 | 创建 code 为 `purchase_ai_reviewer` 的角色，授予 `PurchaseOrder.read/returnForChanges` 及覆盖申请范围的数据权限；本例 AI 仅预审，不执行最终 approve |
+| 经理 | `PurchaseOrder.read/approve/reject/returnForChanges`，适当数据范围，`approve` 的 `ceiling` 额度参数 |
+| 专业协作人 | 真实账号及同样的审批能力、范围、额度；由名录管理员通过 `ApprovalMember.create` 登记公开业务姓名、专业说明；需要在任务中选人时授予 `ApprovalMember.read` |
+| 名录管理员 | 显式授予 `ApprovalMember.create/update/retire/read`；登记、更新资料或退役不修改用户角色，不自动给采购参与者授予 `User.read` |
 | 部门 | 将采购员所属部门的负责人设为经理；不能为空 |
-| 财务 | 角色 **code** 为 `finance`，给实际用户分配；配置审批所需权限、范围及额度 |
+| 财务 | 角色 **code** 为 `finance`，给至少两位实际用户分配以体验共享候选池；配置审批所需权限、范围及足够额度；领取后才能处理 |
 | 库存台账 | 预先登记与采购明细相同的 sku，数量满足演示检查 |
 | 连接器环境 | fake 阶段使用 worker 注册的 fake；真实环境另配 host 对应密钥及回调签名密钥 |
 
 经理与提单人必须是不同用户。配置“负责人”决定选谁；配置角色能力与范围决定此人能否完成结论命令，两者都需要。金额 **大于** 50,000 才追加财务步骤，恰好 50,000 不满足 gt 条件。
 
+专业复核默认关闭，兼容旧单据的空字段；开启后需选择 1–5 位不同且非提单人的有效名录成员。`setReviewers` 只允许编辑草稿；创建可暂存未选完整的草稿，但 `submit` 会重新核对名单，拒绝保存后退役的成员。名录退役不修改已经提交的名单快照，也不撤销在途任务；账号停用和实际审批权限继续由审批引擎核验。名录的用户引用不能换绑，已退役记录保留且不支持重新启用。
+
+`ApprovalMember` 使用 `scope.none()`，没有部门或本人字段。名录管理员和需要选人的采购参与者都必须显式获得该聚合的 `all` 数据范围；仅授予 `ApprovalMember.read` 仍看不到成员，草稿的专业名单校验也会因读范围不足拒绝。这里的 `all` 始终受当前租户隔离，不要求也不授予 `User.read`。
+
+经理、专业会签和财务节点均显式启用转办、委派与前置/后置/并行加签，节点政策随每次提交保存。转办交接处理责任；委派处理完成后归还原审批人；加签增加必须完成的签署任务，前置签署完成前原任务等待，后置签署在原任务通过后才开放。任务动作和决定都应携带页面当前 `revision`，冲突后刷新待办，不自动重试旧决定。AI 人工接管继续采用 AI 节点自身政策，不能因为后续经理节点启用动作而越权操作。
+
+逐项体验时用不同采购单分别记录：普通经理审批、专业双人会签、恰好 50,000 元跳过财务、超过 50,000 元财务领取/释放/再领取、转办、委派归还、三种加签，以及退回重提和申请人取消。每一步同时查看采购状态、当前可操作/等待任务及动作历史；专业会签只通过一人或必签尚未完成时采购单应仍待审批，最终通过才产生库存锁。浏览器验收需切换真实账号进行，自动测试通过不能替代页面验证。
+
+可分别准备“采购办公用品”、说明实际使用场景的完整用途、含“紧急采购”的用途，体验退回、通过本节点和转人工。真实模型的判定应按实际样例验收；故障默认转人工，不能当作正常审查通过。详情页显示历史理由、修改建议及审核轮次；用途编辑框的未保存内容会经 SDK 一起传给助理，服务端重新核对当前单据与权限。
+
+拥有 `Sys.ai.use` 的用户在所有业务页面右下角都有助理入口，点击打开悬浮对话窗，收起后继续执行当前任务。工作台、采购列表/详情、库存和待办分别提供页面语义；列表带筛选与可见记录，详情带单据引用和未保存用途。应用壳只挂载一个 `AssistantScope`，业务页面通过 `AssistantPage` 注册上下文，所以站内切页保留对话，但下一条消息使用新页面的快照。不同页面拥有独立的 `AiPageContext` 身份，旧任务要求补充页面时不能提交新页面代替。登录页和独立的 `/admin/` 不挂载业务助理。
+
+悬浮窗的“相处方式”选择器消费框架 `useAssistant` 的性格目录和切换接口。默认跟随 Admin 设置，也可为当前会话选择其他已启用性格；切换不清空对话，旧回复保留生成时的性格名称。采购范例没有单独的性格表或 Prompt 拼接逻辑，AI 审批继续使用原节点策略。
+
 ## 页面如何使用框架
 
 采购页和库存页通过 `@app/contracts` 获取方法、快照类型和查询 hooks。命令成功后刷新相应列表；失败时按 code/domainCode 展示原因。只有允许 user 调用的命令才生成页面方法，因此审批通过应使用待办接口。

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

@@ -4,6 +4,8 @@
 
 本页用于把用户的业务描述转成 Cage 项目的可执行修改。按需要读对应配方即可，不需要修改框架内部。
 
+需要 AI 审批、业务助理、随页聊天、模型管理或性格配置时，先用 `cage capabilities` 查框架能力，再按[原生智能化指南](intelligence.md)接入。普通业务建模仍按下文声明聚合和命令；接入已有框架服务无需另建一套通用后端。
+
 ## 先把需求落到一张业务表
 
 开始编码前，从用户需求或现有业务中确定以下信息。能从上下文确认的直接使用；真正缺失且影响实现的再询问，不要为技术细节反复让用户确认。
@@ -22,7 +24,7 @@
 
 按[最小便笺业务](primitives.md)新增 `packages/domain/src/modules/<业务>/<对象>.ts`：字段、范围、不变量、create/update/archive 命令。采用唯一的导出名和必要的 `name` 覆盖，避免 index 的 `export *` 丢失重名符号。
 
-从模块 index 到 domain 入口导出后运行 check/gen，审查迁移，再在 `apps/web/src/modules/<业务>` 使用生成 contracts 做列表、表单和操作按钮，经模块公开入口接入 app。最后给角色授权并补图谱中文名。完整归属规则见[目录规范](project-structure.md)。不要手写增删改查路由、ORM 实体与 repository，也不要复制框架鉴权代码。
+从模块 index 到 domain 入口导出后运行 check/gen，审查迁移，再在 `apps/web/src/modules/<业务>` 使用生成 contracts 做列表、详情、表单和操作按钮，经模块公开入口注册到 app 路由。列表和详情都有独立 URL，筛选/分页进入 query，按[浏览器配方](routing.md)检查导航。最后给角色授权并补图谱中文名。完整归属规则见[目录规范](project-structure.md)。不要手写后端增删改查路由、ORM 实体与 repository，也不要复制框架鉴权代码。
 
 完成标准：授权用户能创建和修改，范围外数据不可见，归档后的允许行为符合业务要求，生成契约和迁移一致。没有审批需求时不必添加审批；没有外部系统时不必添加连接器。
 
@@ -40,7 +42,13 @@
 4. 配置实际部门负责人、角色或指定用户；给审批人配置能力、范围和额度。
 5. 页面通过待办接口操作。通过后需占用资源时用反应调用资源命令，按业务一致性选择同事务。
 
-完成标准：提交生成待办、正确的人审批、越权和自审批拒绝、取消能结束待办、资源配对完整。任意流程设计器、动态 JS 选人、转签/加签不属于当前现成能力，需要明确扩展范围。
+完成标准：提交生成待办、正确的人审批、越权和自审批拒绝、取消能结束待办、资源配对完整。转办、委派归还和当前节点并行必签见[审批任务流转](approvals.md)，须显式启用政策并传任务版本。任意流程设计器、动态 JS 选人、前后加签和指定节点退回仍需明确扩展范围。
+
+## 加入 AI 审批或随页助理
+
+先检查 domain 是否已经导出 `ai()`，再按需求修改已有声明或启用一次。AI 审批配置在业务模块的现有 `step` 内，填写 `kind: 'ai'`、审核策略、取证字段/查询与 `handoff`，由 `approval` 绑定自动执行角色和结论命令。业务助理使用框架生成的工具，前端通过 `useAssistant` 与 `useAiPageContext` 接入当前页面；悬浮窗、Markdown 和确认交互由应用实现。
+
+模型地址、协议和密钥通过 `managedModel` 对应的 Admin 配置管理，性格也使用框架现有管理页。先完成系统迁移和必要授权，按[智能化指南](intelligence.md)的接入顺序、SDK 示例和验收步骤验证。分别说明框架支持、应用已启用和真实联调结果；空白模板中的参考代码不参与运行。
 
 ## 增加报表或复杂列表
 

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

@@ -0,0 +1,86 @@
+# 业务前端路由与浏览器验收
+
+[返回学习入口](README.md) · [工程目录](project-structure.md) · [开发步骤](workflow.md)
+
+多页面业务默认使用 React Router 的 BrowserRouter。列表、详情、报表等可独立访问的页面必须有 URL；在 app 中统一组合路由和工作台布局，页面从模块 index.ts 导出。useState 用于弹窗、未提交表单和按钮忙碌状态。筛选、分页和需要分享的选项使用 useSearchParams。
+
+本页对应后续开发版本的模板改进；已发布的 0.2.0 项目需要按本页迁入路由实现，不能只升级依赖就认为旧页面已完成改造。框架包无需维护客户的页面地址。
+
+## 模板中的可运行示例
+
+| 页面 | 空白模板 | 采购模板 |
+| --- | --- | --- |
+| 登录 | `/login` | `/login` |
+| 工作台 | `/workspace` | `/workspace` |
+| 列表 | `/directory/users?page=2` | `/procurement/orders?status=draft&page=2` |
+| 详情 | `/directory/users/:id` | `/procurement/orders/:id` |
+| 其他业务 | 按实际需求新增 | `/inventory`、`/approvals` |
+| 404 | 未匹配页面显示“页面不存在” | 同左 |
+
+`:id` 替换成真实记录 ID。空白模板的成员目录读取已有 User 组织模型，不注册额外业务、演示表或虚假数据；列表与详情均需要 User.read，数据范围由安全接口落实。采购待办的 businessKey 由 app 映射成采购详情链接，审批模块不直接导入采购模块。
+
+在应用根目录运行 pnpm dev 后访问终端打印的 Web 地址。先在系统管理配置真实账号与权限，再从列表复制某条记录的详情 URL，用于刷新和新标签页测试。
+
+## 新增一项业务页面
+
+1. 在 `apps/web/src/modules/<业务>/pages` 编写列表、详情和表单，从模块 index.ts 导出。详情用 useParams 读取 ID，再用生成的 use对象(id) 获取记录；不要求先打开列表，也不从组件状态或上一页传来的对象直接认定记录存在。
+2. 在 `apps/web/src/app/app.tsx` 注册列表与详情 Route。放在已有会话守卫和 WorkspaceLayout 之下，使页面通过 Outlet 渲染。新增实际页面时扩展路由表；不要再添加 tab/page useState 来选择整页。
+3. 导航使用 Link / NavLink；完整页面地址可收藏、复制或新标签页打开。列表筛选和分页通过 useSearchParams 更新，刷新和前进后退恢复相应查询。
+4. 需要 read 能力的页面用共享 RequireCapability 提供直接访问时的提示；服务端返回 FORBIDDEN 时显示权限提示，NOT_FOUND 显示“记录不存在，或不在当前可访问范围”。401 由会话回调进入登录。不要把 403 当成登录失效，也不要通过放宽读权限解决页面导航问题。
+5. 用下面的浏览器配方验收，并报告通过、跳过与未执行。构建和 cage verify 通过，只证明其各自检查范围，不能据此宣称路由体验正确。
+
+```tsx
+// app 中的组合片段：页面通过所属模块的 index.ts 导出。
+<Route element={<WorkspaceLayout onLogout={onLogout} />}>
+  <Route path="procurement/orders" element={<PurchaseOrdersPage />} />
+  <Route path="procurement/orders/:id" element={<PurchaseOrderDetailPage />} />
+</Route>
+```
+
+片段只展示路由与布局关系。实际代码参考本模板 app.tsx，保留会话守卫、页面 props 和能力提示。`cage/no-manual-routes` 限制手写后端业务 HTTP 路由，不禁止 React Router；前端导航不会生成能力或授予数据访问权。
+
+## 登录后返回原地址
+
+应用启动先 loadMe 恢复会话。未登录访问详情时，守卫使用 replace 导航到 `/login?returnTo=编码后的原路径`，包含 query 和 hash。登录完成再次 replace 回原页面，避免浏览器后退反复落入登录页。
+
+`shared/lib/navigation.ts` 的 loginReturnTo 只接受应用内页面，排除外站、登录循环及 API/admin 等服务端入口；不要直接把用户提供的任意 returnTo 交给 location.href。网络错误显示重试界面并保留地址，只有 UNAUTHENTICATED 才要求重新登录。运行中会话过期同样保存当前 URL，并清除上一账号的查询缓存。
+
+前端路由守卫只改善导航与提示。请求仍由 Cage HTTP 和内核检查会话、能力、租户、数据范围与掩码；直接请求接口必须得到相同约束。
+
+## 与系统管理及部署共存
+
+| 路径 | 所有者 |
+| --- | --- |
+| `/login`、`/workspace`、客户业务页面 | React Router |
+| `/admin`、`/admin/` 及其脚本/样式 | Cage 系统管理 |
+| `/api/`、`/auth/`、`/hooks/` | Cage HTTP 接口 |
+| `/assets/` | Vite 构建资源 |
+
+进入 `/admin/` 使用普通 `<a href="/admin/">`，让浏览器请求独立管理入口；应用内部页面使用 Link。不要在 React 中注册覆盖 /admin 或 /auth 的页面。Vite 配置已代理 API、认证与管理请求，开发环境支持业务深链接刷新。
+
+生产可选两种部署方式：
+
+- **Cage 托管 Web**：API 启动时提供 webDir，标准入口读取 WEB_DIR；将其设置为 apps/web/dist 的绝对路径。模板 Dockerfile 已复制构建产物并设置 WEB_DIR=/app/web。浏览器 GET/HEAD 页面请求可回退到 index.html，React 决定详情或 404；API、管理和丢失资源返回各自错误，不应变成业务首页。
+- **Nginx 托管 Web**：参考项目 `deploy/nginx.conf`，将 root 指向真实 dist，将 API/admin/auth/hooks 代理到 Cage；业务页面使用 try_files 回退到 index.html，/assets/ 缺失时直接 404。示例按 Nginx 与 API 在同一主机、API 端口 3000 编写；按部署拓扑修改上游。仅复制 dist 到没有 SPA 回退的静态服务器会导致详情刷新 404。
+
+上线前用实际反向代理地址验收深链接。Vite 开发环境成功，不代表 Nginx、CDN 或生产容器已配置正确。
+
+## 浏览器验收配方
+
+准备一条有权读取的真实记录和两个测试账号：有 read 能力及范围的账号、没有该能力的账号。测试账号和记录在独立验收环境准备，不修改生产角色。
+
+| 操作 | 预期结果 |
+| --- | --- |
+| 复制列表中某条详情 URL，在新标签页粘贴 | 直接加载对应记录，无需先访问列表 |
+| 在详情页刷新 | URL 和记录保持一致 |
+| 列表 → 详情 → 另一页面，再点浏览器后退、前进 | 地址、页面内容与导航高亮同步变化 |
+| 改变列表筛选/分页，复制地址或刷新 | 条件与列表恢复，不返回工作台或第一页 |
+| 未登录打开带 query/hash 的详情 URL | 进入登录；成功后回到原 URL，保留 query/hash |
+| 在业务页使测试会话过期，再触发读取 | 进入登录；重新登录后回到原页面，旧账号缓存不残留 |
+| 无 read 能力账号直接访问有效详情地址 | 显示权限提示，直接请求 API 仍为 403 |
+| 有 read 能力但记录位于范围外 | 显示记录不可用，直接请求 API 为 404，不泄露记录是否存在 |
+| 访问不存在的业务路径 | 显示应用 404，并有返回工作台入口 |
+| 访问 /admin/，以及缺失的 API/JS/CSS | 管理入口独立可用；缺失接口或资源不返回业务 index.html |
+| 在实际部署地址重复深链接和刷新步骤 | 正常加载，浏览器控制台无脚本 MIME 错误 |
+
+验收记录写明模板、地址、操作和结果。模拟 API 的浏览器检查可以证明导航行为；真实权限、范围和数据库链路需要相应集成验收，二者分别报告。

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

@@ -4,6 +4,8 @@
 
 先保留完整诊断的 code、源码位置、reason/fix、requestId 或 outboxId。检查所在阶段，再修复原因；不要通过改业务状态、给全局权限、注释约束或禁用 lint 消除现象。
 
+先执行 `pnpm exec cage doctor` 查看各阶段证据；异步动作按 requestId/outboxId/业务对象用 `cage timeline` 关联实际执行记录。能力、范围、调用身份或额度不清楚时，有权诊断的管理员可使用 `cage explain`，不会执行目标命令。完整参数与权限见[诊断指南](diagnostics.md)。
+
 ## 按现象定位
 
 | 现象 | 先查什么 | 常见原因 |
@@ -15,6 +17,9 @@
 | 详情 404 | 记录 id、租户和数据范围 | 不存在或在范围外；不能仅凭 404 断言被删除 |
 | 列表为空 | read 能力、范围与相应字段 | 默认本人范围、无 owner 字段或部门不匹配 |
 | 电话看不到明文 | sensitive 标注、unmask 能力 | 默认掩码是正常安全行为 |
+| 有明文能力但读取报 CAGE-AUDIT-001 | requestId、审计库可用性与权限 | 可靠审计未成功，框架拒绝交付结果 |
+| 生产服务拒绝启动 | CAGE-ENV-002/003、Cookie 密钥与 bootstrap 参数 | 关键配置不合格，或试图在日常启动时隐式初始化 |
+| 任务时间线有 CAGE-WORKER-002 | API/worker 版本、注册指纹和消费者清单 | 旧进程或必要消费者缺失，不能把 done 当作已执行 |
 | 提交成功但无待办 | worker、outbox/死信、审批路由 | 未投递、缺审批人、没有匹配的绑定/路由 |
 | 已批准但 ERP 单号未回写 | worker、同步记录、死信、环境/fake | 密钥/白名单/响应错误，或异步还未完成 |
 | 已取消但锁未释放 | 释放事件、反应、死信 | 先前消息阻塞、map 条件不匹配或遗漏释放 |

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

@@ -1,6 +1,6 @@
 # 开发步骤与交付要求
 
-[返回学习入口](README.md) · [范例导读](purchase-example.md)
+[返回学习入口](README.md) · [范例导读](purchase-example.md) · [详细中文注释](commenting.md)
 
 本页命令在**应用根目录**执行，除非注明“框架根目录”。使用项目安装的 CLI：`pnpm exec cage ...`。项目脚本可简写为 `pnpm gen / pnpm migrate / pnpm dev / pnpm verify`；不要假定机器已全局安装 cage。
 
@@ -18,39 +18,44 @@ pnpm build:app
 pnpm gen
 # 审查 db/migrations 中的迁移草稿，再执行：
 pnpm migrate
+# 迁移后显式初始化组织，目标是新的受限凭据文件；父目录需存在。
+pnpm exec cage bootstrap --credentials-file .cage/admin-credentials.json
 pnpm dev
 ```
 
 `init` 自动创建独立账号与随机密码，填写 APP/READ/MIGRATE 连接和 Cookie 密钥，成功后删除文件中的管理员连接。三个连接使用同一数据库。已有 Cage 集群账号时复用原连接，不能重置其他应用的账号密码。生产环境可由平台直接提供账号连接，不必执行本地 init。
 
+`bootstrap` 独立初始化组织，不自动授予业务能力。管理员凭据只进入新的受限文件，不进入服务控制台；已有用户时不重置。交付后移除凭据文件。日常 API 启动不初始化组织；生产缺少合格 Cookie 密钥会拒绝启动。具体文件权限与诊断用法见[能力发现与状态诊断](diagnostics.md)。
+
 `.env.example` 是配置说明，`.env` 是本机私密配置，二者不混用。CLI 自动加载应用 `.env`，部署环境同名变量优先。API 和 worker 启动需重启后读取变更；不要输出整个 `.env` 排障。
 
 框架仓库首次先在根目录 `pnpm install`、`pnpm build`，再进入 `examples/purchase-admin` 配置。`dev` 不自动执行迁移；生成新迁移后要审查并显式运行 migrate。
 
 ## 做一项业务修改
 
-1. 读 AGENTS.md 和[目录规范](project-structure.md)，确认需求落在领域模块、前端模块、组织配置还是框架。先 `pnpm exec cage context "需求关键词"`，按需 `graph search/inspect/path` 定位，确认候选入口后阅读对应源码、范例与测试；证据和边界见[本体上下文指南](ontology-context.md)。发现能力缺口先说明，不编造 API。
-2. 涉及已存在业务含义变化时，**修改前**保存基线。已有 Git 可用提交，也可保存独立本体图文件。
-3. 在所属领域模块写字段、状态、不变量和命令输入；再实现 handler、事件、查询与审批。跨模块反应放 workflows，第三方协议放 integrations。从模块 index 到 domain 总入口逐层导出，避免跨文件 export 名冲突。
+1. 读 AGENTS.md、[目录规范](project-structure.md)和[详细中文注释规范](commenting.md)，确认需求落在领域模块、前端模块、组织配置还是框架。先 `pnpm exec cage context "需求关键词"`，按需 `graph search/inspect/path` 定位，确认候选入口后阅读对应源码、范例与测试；证据和边界见[本体上下文指南](ontology-context.md)。发现能力缺口先说明，不编造 API。
+2. 涉及已存在业务含义变化时，**修改前**运行 `pnpm exec cage snapshot save before-change` 保存命名基线；也可使用真实 Git 提交或独立本体图文件。
+3. 在所属领域模块写字段、状态、不变量和命令输入；再实现 handler、事件、查询与审批。跨模块反应放 workflows，第三方协议放 integrations。从模块 index 到 domain 总入口逐层导出，避免跨文件 export 名冲突。同步编写详细中文注释：文件职责与调用链、导出声明及输入字段、权限/状态/reads/事件/事务、关键步骤和失败边界；涉及已有行为时补齐受影响的上下游说明。
 4. `pnpm exec cage check` 检查声明和图规则；`pnpm gen` 更新契约与迁移草稿。聚合和命令填写中文 `description`，需要覆盖时补 `cage.config.json` 的 `graph.labels`（如 `aggregate:Note`、`command:Note.archive`、`capability:Note.export`）。这些名称同时用于图谱和 `/admin` 授权界面；修改后重启 API。不重命名实际能力点来实现翻译。在图谱确认连接与资源生命周期。
 5. 审查数据库变更，特别是非空字段、数据回填、删列和索引。已执行的迁移不可改写。需要落库时显式 `pnpm migrate`。
-6. 页面和表单放 `apps/web/src/modules/<业务>`，从模块公开入口接入 app 导航；依赖生成 contracts，处理失败结果。新增能力由管理员授权，页面按钮可用 `useCan` 控制。
-7. 补足重要业务反例并运行相关验证。提交源声明、契约和审查过的迁移，报告跳过及未执行项。
+6. 页面和表单放 `apps/web/src/modules/<业务>`，从模块公开入口接入 app 的 URL 路由；依赖生成 contracts，处理失败结果。列表、详情等多页面使用 React Router，筛选和分页进入 URL；组件状态只管理页面内临时交互。新增能力由管理员授权，页面按钮可用 `useCan` 控制。按[路由与浏览器验收](routing.md)检查直达、刷新、前进后退和登录回跳。
+7. 补足重要业务反例并运行相关验证；测试解释夹具目的、所保护的规则和覆盖边界。按注释规范审查本次 diff，核对页面、组件/hooks、类型字段、脚本副作用和恢复流程的说明是否完整准确。提交源声明、契约和审查过的迁移，报告跳过及未执行项。
 
 ### 如何保存和比较基线
 
 ```powershell
-# 修改前执行，避免后续 gen/analyze 覆盖唯一的旧图。
-pnpm exec cage analyze
-Copy-Item .cage/ontology.json .cage/before-change.json
+# 修改前执行；同名快照不会覆盖。
+pnpm exec cage snapshot save before-change
 # 修改 domain 后执行：
-pnpm exec cage impact --base-file .cage/before-change.json
+pnpm exec cage impact --snapshot before-change
 # 或与真实可用的 Git 提交比较；下面的 main 应按仓库实际情况替换。
 pnpm exec cage impact --base main
 ```
 
 基线文件要保留到验收结束。影响分析用于找到相关命令、约束、审批、查询和候选测试，不能当作不需验证的证明。没有 Git 提交时不要为了让命令成功而擅自创建/推送远端。
 
+`context` 和图谱查询只返回查询结果，不更新当前图文件或命名基线；`analyze/gen` 更新当前图。快照来源时间、版本与图指纹随报告保存。
+
 ## 常见需求的具体改法
 
 | 需求 | 做法 | 必查项 |
@@ -82,6 +87,8 @@ if (!result.ok) {
 
 对自定义 HTTP 协议能力使用 `@yss123/cage-client`；它负责会话、CSRF 和类型化结果。需让多个提交共享幂等键时，按当前客户端接口显式传递同一次业务操作的 key，并在页面阻止重复进行中的提交。生成契约的方法签名以 `packages/contracts/src` 为准，不假设每个命令方法都支持自定义 options。
 
+生成方法最后的请求选项支持 `signal/timeoutMs/idempotencyKey`。底层返回 `CageResult`；`useCageCommand` 成功返回业务数据、失败抛出 `CageCommandError`，因此 mutation 的 `isSuccess` 表示业务成功。退出、401、切换账号时订阅 `client.subscribe` 取消用户查询并清除应用缓存，范例 `apps/web/src/app/use-session.ts` 展示了接法。
+
 ### 导入和导出属于业务页面
 
 框架提供通用异步接口与任务查询，页面放在哪里由具体业务决定。
@@ -98,6 +105,9 @@ CSV 编码、限制、SDK 与完整接口见本项目自带的[业务页导入
 | 命令 | 用途 | 主要输出 |
 | --- | --- | --- |
 | `pnpm exec cage analyze` | 抽取显式声明与源码位置 | `.cage/ontology.json` |
+| `pnpm exec cage capabilities 关键词 --format json` | 查询当前安装版本的公开能力 | 公开签名、声明位置和学习入口 |
+| `pnpm exec cage doctor` | 统一核对注册、生成、构建及可用运行证据 | pass / fail / unknown 与下一步；见[诊断指南](diagnostics.md) |
+| `pnpm exec cage snapshot save 名称` | 保存不可覆盖的命名基线 | `.cage/snapshots`；配合 `impact --snapshot 名称` |
 | `pnpm exec cage check` | 静态检查、注册表与图规则 | 终端 `code/at/reason/fix` |
 | `pnpm exec cage graph` | 启动中文本体图谱 | 默认 `http://127.0.0.1:15418`，按终端地址访问 |
 | `pnpm exec cage context "需求或节点"` | 开发前取得相关子图、原因、源码与候选验证 | 默认终端 Markdown；`--format json --out .cage/context.json` 保存结构化报告 |
@@ -117,8 +127,10 @@ CSV 编码、限制、SDK 与完整接口见本项目自带的[业务页导入
 ## 验证要与改动匹配
 
 - 文档、文案、可逆的小改动：检查链接、格式、资料分发；不需要重复运行全套数据库测试。
+- 所有源码变更：按[注释交付清单](commenting.md#交付前逐项核对)人工核对中文职责、接口与关键流程说明；静态检查不能替代注释准确性检查。仅补注释时不新增复述实现的测试、不改写已执行迁移。
 - 命令/约束/反应变化：针对成功路径及真正的风险增加用例，如越权拒绝、额度边界、资源释放、同事务回滚。不要写只复述实现的测试。
 - 领域结构变化：check、gen、生成一致性、类型检查；有数据库影响时在独立测试库验证迁移和读写。
+- 页面或导航变化：构建后按[浏览器配方](routing.md)实际操作，包含深链接、新标签页、刷新、前进后退、登录回跳、无权限和 404。check/verify 不自动执行浏览器验收；未操作时明确报告未执行，不能写“页面功能完整”。
 - 发布前：按项目要求执行完整 verify/build/test，核对分发包。没有执行的项目明确写出原因。
 
 测试使用真实 PostgreSQL。`CAGE_TEST_DATABASE_URL` 供独立测试集群使用，测试工具会准备角色和临时数据库；不要指向业务/生产集群。没有设置时 testkit 可使用内嵌的真实 PostgreSQL，这与 dev 的固定已有库流程不同。
@@ -133,7 +145,8 @@ CSV 编码、限制、SDK 与完整接口见本项目自带的[业务页导入
 先用 cage context 查询现有业务，必要时 graph inspect/path，确认候选与关系后阅读实现。
 说明字段、状态、能力与范围、事件/资源的影响，再修改 domain、生成契约和迁移草稿、接入业务页面。
 使用真实公开 API；不要手写业务路由、直接写表或新增本地数据库生命周期命令。
+按 docs/ai/commenting.md 给新建和修改代码写详细中文注释，覆盖职责、API/字段、步骤、原因和边界，同步修正相关上下游说明。
 按改动运行必要检查，报告通过/跳过/未执行项和需要的管理员配置。
 ```
 
-交付说明至少包含行为变化、源文件、生成物/迁移、角色授权需求、验证结果，以及尚未做的真实外部联调。遇到错误先修复根因；不把待办未生成、任务已接受或 fake 成功写成业务全部完成。
+交付说明至少包含行为变化、源文件、生成物/迁移、角色授权需求、详细中文注释覆盖的主要职责与边界、验证结果，以及尚未做的真实外部联调。注释未覆盖项如实说明，不能用聊天中的解释代替源码注释。遇到错误先修复根因；不把待办未生成、任务已接受或 fake 成功写成业务全部完成。

package/templates/blank/docs/errors/CAGE-AI-001.md

@@ -0,0 +1,61 @@
+# CAGE-AI-001：智能运行时声明无效
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：领域声明 / 模型与运行预算配置。
+
+模型引用未配置、重复启用 AI 运行时，或上下文预算、重试、并发、超时、队列参数非法。
+
+## 修复步骤
+
+1. 在 domain 顶层导出一个 ai({ models, assistant }) 声明，审批 step 的 model 引用同名模型。
+2. 预算与并发为正整数；maxModelRetries 为 0 至 8，context.maxTools 最多 128（包含通用工具）。并发最多 32，单次运行 timeoutMs 最多 300000。API 与 worker 使用相同声明和模型配置。
+
+## 正例
+
+```text
+ai({ models: { main: provider }, assistant: { model: 'main', limits: { maxSteps: 8 } } })
+```
+
+## 反例
+
+```text
+ai({ models: {}, assistant: { model: 'missing', limits: { maxSteps: 0 } } })
+```
+
+## 修复后验证
+
+重跑 cage check、迁移与相关测试，再以真实角色验证助理和审批；fake 成功不代表真实模型联调完成。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/ai/src/index.ts:54`
+- `packages/ai/src/index.ts:61`
+- `packages/ai/src/index.ts:74`
+- `packages/ai/src/index.ts:82`
+- `packages/ai/src/index.ts:86`
+- `packages/ai/src/index.ts:88`
+- `packages/ai/src/index.ts:89`
+- `packages/ai/src/index.ts:90`
+- `packages/ai/src/index.ts:92`
+- `packages/ai/src/index.ts:94`
+- `packages/ai/src/index.ts:96`
+- `packages/ai/src/index.ts:126`
+- `packages/ai/src/index.ts:133`
+- `packages/ai/src/index.ts:135`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  /**
+   * 校验扩展唯一性与审批模型引用，无效配置以 CAGE-AI-001 拒绝。
+   */
+  validate(registry: Registry): void;
+}
+```

package/templates/blank/docs/errors/CAGE-APPR-001.md

@@ -1,4 +1,4 @@
-# CAGE-APPR-001：可路由字段不存在
+# CAGE-APPR-001：审批字段声明无效
 
 [返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
 
@@ -8,11 +8,12 @@
 
 阶段：声明、图规则或 worker。
 
-approval.routable 引用了所属聚合没有声明的字段。
+approval.routable 引用了不存在字段，或 approver.field 指向未声明、隐藏、未进入 routable 的字段。
 
 ## 修复步骤
 
-1. 先在聚合声明实际字段，再将需要给审批路由的字段放入 routable；不要把任意输入直接交给流程。
+1. 先在聚合声明实际字段，再将需要给审批路由的非隐藏字段放入 routable；不要把任意输入直接交给流程。
+2. 字段选人值应为 UUID 或非空 UUID 数组，见 docs/ai/approvals.md；字段公开并不自动授予审批能力。
 
 ## 正例
 
@@ -34,14 +35,17 @@ routable: ['managerName'] // 聚合没有该字段
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/primitives/flow.ts:134`
+- `packages/approval/src/route.ts:215`
+- `packages/approval/src/route.ts:220`
+- `packages/approval/src/route.ts:229`
+- `packages/kernel/src/primitives/flow.ts:245`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
-  for (const f of def.routable) {
-    if (!(f in agg.fields)) throw declError('CAGE-APPR-001', `可路由字段 ${agg.name}.${f} 不存在`);
-  }
-  for (const c of [def.onApproved, def.onRejected]) {
-    if (c.agg !== agg) throw declError('CAGE-APPR-002', `审批结论命令必须属于 ${agg.name}`);
+      if (reminders && (!routeBinding?.routable.includes(reminders.requesterField) || !routeBinding.agg.fields[reminders.requesterField] || routeBinding.agg.fields[reminders.requesterField].isHidden))
+        throw declError('CAGE-APPR-001', `申请人字段 ${reminders.requesterField} 必须存在、可公开且进入 routable`);
+      for (const node of declaredSteps) {
+        const selector = node.kind === 'ai' ? node.handoff : node.approver;
+        // 新字段选择器必须能从 routable 快照取值；不追溯改变历史部门选人的声明校验行为。
 ```

package/templates/blank/docs/errors/CAGE-APPR-002.md

@@ -34,12 +34,12 @@ PurchaseOrder 的审批绑定使用 approvePurchaseOrder 命令
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/primitives/flow.ts:137`
+- `packages/kernel/src/primitives/flow.ts:248`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
-  for (const c of [def.onApproved, def.onRejected]) {
+  for (const c of [def.onApproved, def.onRejected, ...(def.onReturned ? [def.onReturned] : [])]) {
     if (c.agg !== agg) throw declError('CAGE-APPR-002', `审批结论命令必须属于 ${agg.name}`);
     if (!c.invokedBy.includes('process')) {
       throw declError('CAGE-APPR-003', `审批结论命令必须声明 invokedBy: 'process'`);

package/templates/blank/docs/errors/CAGE-APPR-003.md

@@ -34,7 +34,7 @@ invokedBy: 'user' // 用作审批结论
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/primitives/flow.ts:139`
+- `packages/kernel/src/primitives/flow.ts:250`
 
 实现片段（位置随框架版本更新）：
 

package/templates/blank/docs/errors/CAGE-APPR-004.md

@@ -34,14 +34,14 @@ approval(..., { process: 'po-approval', ... }) 与 route('po-approval', ...)
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/approval/src/bridge.ts:8`
+- `packages/approval/src/bridge.ts:14`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
   const binding = k.registry.approvalByProcess(r.process);
   if (!binding) throw new Error(`[CAGE-APPR-004] 没有流程 ${r.process} 的审批绑定`);
-  const cmd = r.outcome === 'approved' ? binding.a.onApproved : binding.a.onRejected;
-  const ctx = k.processCtx({
-    process: r.process,
+  const cmd = r.outcome === 'approved' ? binding.a.onApproved : r.outcome === 'returned' ? binding.a.onReturned : binding.a.onRejected;
+  if (!cmd) throw new Error('[CAGE-APPR-006] 审批未绑定退回修改命令');
+  let ctx: Ctx;
 ```

package/templates/blank/docs/errors/CAGE-APPR-005.md

@@ -34,14 +34,14 @@ route('采购审批', nodes)
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/approval/src/route.ts:96`
+- `packages/approval/src/route.ts:176`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
-export function route(process: string, nodes: RouteNode[]): Route {
+export function route(process: string, nodes: RouteNode[], options: { reminders?: ApprovalReminderPolicy } = {}): Route {
   if (!/^[a-z][a-z0-9-]*$/.test(process)) throw declError('CAGE-APPR-005', `流程名 ${process} 必须是小写短横线`);
   if (nodes.length === 0) throw declError('CAGE-APPR-006', `流程 ${process} 至少需要一个步骤`);
-  const fields = new Set<string>();
-  for (const n of nodes) {
+  const inspection = inspectRoute(nodes);
+  const fields = new Set<string>(inspection.fields);
 ```

package/templates/blank/docs/errors/CAGE-APPR-006.md

@@ -1,4 +1,4 @@
-# CAGE-APPR-006：流程没有步骤
+# CAGE-APPR-006：审批步骤配置无效
 
 [返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
 
@@ -8,11 +8,13 @@
 
 阶段：声明、图规则或 worker。
 
-route 接收了空步骤数组。
+route 没有步骤、展开后为空，或人工 actions/assignment、候选池与 all 组合、AI 步骤必填配置或预算不合法。
 
 ## 修复步骤
 
 1. 声明至少一个实际审批步骤，并检查条件后能否形成预期流程。
+2. candidate 只支持 any；逐人会签用默认 direct。actions 只接受 transfer/delegate/addSign 布尔值。
+3. AI 步骤需模型、要求、上下文字段、接管规则及正整数预算，并绑定 AI 运行时、退回命令和自动角色。
 
 ## 正例
 
@@ -34,14 +36,33 @@ route('po-approval', [])
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/approval/src/route.ts:97`
+- `packages/approval/src/bridge.ts:16`
+- `packages/approval/src/deadlines.ts:34`
+- `packages/approval/src/deadlines.ts:41`
+- `packages/approval/src/engine.ts:75`
+- `packages/approval/src/execution.ts:40`
+- `packages/approval/src/execution.ts:42`
+- `packages/approval/src/execution.ts:47`
+- `packages/approval/src/execution.ts:49`
+- `packages/approval/src/execution.ts:54`
+- `packages/approval/src/execution.ts:55`
+- `packages/approval/src/execution.ts:88`
+- `packages/approval/src/operations.ts:375`
+- `packages/approval/src/route.ts:109`
+- `packages/approval/src/route.ts:111`
+- `packages/approval/src/route.ts:115`
+- `packages/approval/src/route.ts:117`
+- `packages/approval/src/route.ts:177`
+- `packages/approval/src/route.ts:213`
+- `packages/approval/src/route.ts:224`
+- `packages/approval/src/route.ts:226`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
-  if (!/^[a-z][a-z0-9-]*$/.test(process)) throw declError('CAGE-APPR-005', `流程名 ${process} 必须是小写短横线`);
-  if (nodes.length === 0) throw declError('CAGE-APPR-006', `流程 ${process} 至少需要一个步骤`);
-  const fields = new Set<string>();
-  for (const n of nodes) {
-    const steps = n.kind === 'step' ? [n] : n.steps;
+  const cmd = r.outcome === 'approved' ? binding.a.onApproved : r.outcome === 'returned' ? binding.a.onReturned : binding.a.onRejected;
+  if (!cmd) throw new Error('[CAGE-APPR-006] 审批未绑定退回修改命令');
+  let ctx: Ctx;
+  if (r.lastApprover) {
+    // 待办决定已持有事务连接时复用它；同实例并发排队不能耗尽池后让锁持有者再等新连接。
 ```

package/templates/blank/docs/errors/CAGE-APPR-007.md

@@ -8,14 +8,15 @@
 
 阶段：声明、图规则或 worker。
 
-worker 启动或推进审批步骤时，选人器没有找到人。
+worker 启动或推进审批步骤时选人器没有找到人，或字段选人/候选节点中存在非当前租户启用账号。
 
 ## 修复步骤
 
 1. 先看本项目 approvals.ts：deptLeader 读取单据部门的负责人；role 使用角色 code；user 使用实际用户 UUID。
 2. 在 /admin 设置单据所属部门的负责人，或创建对应 code 的角色并分配实际用户。给用户经理角色，并不等于设置了部门负责人。
-3. 再核对审批人的结论能力、数据范围、ceiling 额度和职责分离。选中审批人不等于允许完成审批。
-4. 若 OrderSubmitted 已入死信，修复后在 /admin 按 outboxId 重放，确认待办生成；原提交已成功时不重复提交或 SQL 改回草稿。
+3. field 使用提交时保存的 routable 人员字段；检查 UUID 对应账号是否全部在当前租户且 active。不能删掉不合格人员后默认为审批通过；字段快照错误需按业务撤回/重提修正。
+4. 再核对审批人的结论能力、数据范围、ceiling 额度和职责分离。选中审批人不等于允许完成审批。
+5. 若 OrderSubmitted 已入死信，修复后在 /admin 按 outboxId 重放，确认待办生成；原提交已成功时不重复提交或 SQL 改回草稿。
 
 ## 正例
 
@@ -37,14 +38,15 @@ deptLeader('deptId')：给该部门设置负责人；role('finance')：给实际
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/approval/src/engine.ts:64`
+- `packages/approval/src/engine.ts:87`
+- `packages/approval/src/engine.ts:94`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
     if (who.length === 0) {
-      throw new Error(`[CAGE-APPR-007] 流程 ${this.route.process} 第 ${index + 1} 步「${s.title}」找不到审批人，请在 /admin 配置部门负责人或角色`);
+      throw new Error(`[CAGE-APPR-007] 流程 ${this.route.process} 第 ${index + 1} 步「${title}」找不到审批人，请在 /admin 配置部门负责人或角色`);
     }
-    for (const assignee of new Set(who)) {
-      await tx.insertInto('flow.approval_task').values({ instance_id: instanceId, tenant_id: tenantId, step: index, title: s.title, assignee }).execute();
+    if (selector.kind === 'field' || assignment === 'candidate') {
+      // 新字段/候选声明不允许创建指向停用或其他租户账号的票；整批拒绝，不静默减少会签人数。
 ```