@yss123/cage-cli 0.3.2 → 0.4.0

package/templates/app/docs/errors/CAGE-ONTOLOGY-001.md

@@ -0,0 +1,52 @@
+# CAGE-ONTOLOGY-001：本体节点缺少结构化业务名称
+
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：check / gen / verify / 图谱与上下文诊断。
+
+当前项目可定位的聚合、字段、状态、命令、事件、查询或任务没有非空业务名称，图谱只能回退机器标识。默认警告，graph.naming 为 required 时作为门禁错误。
+
+## 修复步骤
+
+1. 按 reason 的完整节点 key 定位声明。字段和状态的位置指向所属聚合，继续在其中查找成员；无本地源码位置的依赖节点不在本检查范围。
+2. 对象、命令、查询和任务填写 description；事件在第三个参数填写 description；字段用 .describe(...) 或关系选项 description；每个状态都在 states 的 labels 中命名。旧声明可用 graph.labels 的完整 key 覆盖显示。
+3. 普通注释与前端 statusLabel 不会自动进入本体。名称用用户的业务用语，不为翻译改表名、状态值或能力点；详见 docs/development/guides/ontology-modeling.md。
+4. 补齐后重跑 check 并查看 graph/context；完整性不验证语言、名称质量或任意业务关系，仍按已明确规则验证外键方向、基数、状态迁移及真实触发链。
+
+## 正例
+
+```text
+states('active', 'archived', { terminal: ['archived'], labels: { active: '使用中', archived: '已归档' } })
+```
+
+## 反例
+
+```text
+states('active', 'archived', { terminal: ['archived'] }) // 只在页面或注释中翻译状态，没有结构化名称
+```
+
+## 修复后验证
+
+重跑 cage check，再在 graph/context 中按业务用语核对名称；对象关系与运行行为仍需独立业务用例验证。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/ontology-names.ts:27`
+- `packages/cli/src/ontology-names.ts:42`
+- `packages/cli/src/sync.ts:42`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+ * @param presentation 与图谱同一次抽取产生的名称，配置短标题优先于声明文案。
+ * @returns 每个缺名节点一条 CAGE-ONTOLOGY-001；不推断语言、不从注释或前端反推业务名称。
+ */
+export function checkOntologyNames(cfg: CageConfig, graph: Ontology, presentation: GraphPresentation): Finding[] {
+  const aggregates = new Map(graph.nodes.filter(node => node.kind === 'aggregate').map(node => [node.id, node]));
+```

package/templates/app/docs/errors/CAGE-STATE-003.md

@@ -12,7 +12,7 @@
 
 ## 修复步骤
 
-1. 状态标识使用 pending_approval 等，中文名称通过页面/graph.labels 显示。
+1. 状态标识使用 pending_approval 等，业务名称在 states 的 labels 中填写，graph.labels 可覆盖显示；页面文案和普通注释不会自动进入本体。
 
 ## 正例
 

package/templates/app/docs/errors/CAGE-SYNC-001.md

@@ -34,9 +34,9 @@ sync --check 发现框架规则需更新，或 begin/end 标记缺失一边、
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/sync.ts:66`
 - `packages/cli/src/sync.ts:73`
-- `packages/cli/src/sync.ts:84`
+- `packages/cli/src/sync.ts:80`
+- `packages/cli/src/sync.ts:91`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -8,6 +8,12 @@
 
 每页包含触发阶段、具体原因、修复步骤、正反例、验证方法与当前版实现位置。例子为局部说明，不能替代完整业务输入。
 
+## 本体业务名称
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-ONTOLOGY-001](CAGE-ONTOLOGY-001.md) | 本体节点缺少结构化业务名称 |
+
 ## 智能运行时
 
 | 诊断码 | 含义 |
@@ -181,7 +187,7 @@
 
 | 诊断码 | 含义 |
 | --- | --- |
-| [CAGE-GRANT-001](CAGE-GRANT-001.md) | 授予超出自己的能力或额度 |
+| [CAGE-GRANT-001](CAGE-GRANT-001.md) | 授予超出自己的能力或参数 |
 | [CAGE-GRANT-002](CAGE-GRANT-002.md) | 授予超出自己的数据范围 |
 | [CAGE-GRANT-003](CAGE-GRANT-003.md) | 能力不在代码目录中 |
 

package/templates/app/docs/errors/runtime.md

@@ -13,7 +13,7 @@
 | NOT_FOUND | 404 | 记录不存在或超出范围 | 用当前用户检查 id/租户/范围，不泄漏范围外数据 |
 | INVALID_INPUT | 400 | Zod/协议输入错误、外键或检查约束等 | 按输入 schema 修正字段和格式，不直接扩大 schema |
 | INVALID_TRANSITION | 409 | 当前状态不允许该命令 | 刷新记录，按真实生命周期显示允许操作 |
-| CONSTRAINT_VIOLATED | 403 | 职责分离、额度、二次认证、防提权等拒绝 | 看约束原因，调整业务操作或由有权管理员配置；不删除约束 |
+| CONSTRAINT_VIOLATED | 403 | 职责分离、二次认证、防提权等拒绝 | 看约束原因，调整业务操作或由有权管理员配置；不删除约束 |
 | INVARIANT_VIOLATED | 409 | 命令结果不满足聚合不变量 | 修正输入或 handler，保持合法结果 |
 | CONFLICT | 409 | 版本、唯一性、数据库串行化/死锁等冲突 | 看 detail、重新读取再决定是否重试；不要盲目重复创建 |
 | DOMAIN_ERROR | 422 | handler 返回 fail | 读取 domainCode，展示业务文案和必要 detail |

package/templates/app/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.2",
-    "@yss123/cage-testkit": "0.3.2",
-    "@yss123/cage-lint": "0.3.2",
+    "@yss123/cage-cli": "0.4.0",
+    "@yss123/cage-testkit": "0.4.0",
+    "@yss123/cage-lint": "0.4.0",
     "@types/node": "^24.3.0",
     "typescript": "~5.9.3",
     "vitest": "^4.1.12",

package/templates/app/packages/contracts/package.json

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

package/templates/app/packages/contracts/src/aggregates/role/index.ts

@@ -31,7 +31,7 @@ export const RoleInputs = {
 };
 
 /** Role.archive 可能返回的错误码 */
-export type RoleArchiveError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+export type RoleArchiveError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
 /** Role.create 可能返回的错误码 */
 export type RoleCreateError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT';
 /** Role.grantCapability 可能返回的错误码 */
@@ -39,7 +39,7 @@ export type RoleGrantCapabilityError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOM
 /** Role.rename 可能返回的错误码 */
 export type RoleRenameError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
 /** Role.revokeCapability 可能返回的错误码 */
-export type RoleRevokeCapabilityError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+export type RoleRevokeCapabilityError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
 /** Role.setScope 可能返回的错误码 */
 export type RoleSetScopeError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
 

package/templates/app/packages/contracts/src/aggregates/user/index.ts

@@ -38,11 +38,11 @@ export type UserAssignRolesError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_
 /** User.create 可能返回的错误码 */
 export type UserCreateError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT';
 /** User.disable 可能返回的错误码 */
-export type UserDisableError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+export type UserDisableError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
 /** User.enable 可能返回的错误码 */
-export type UserEnableError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+export type UserEnableError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
 /** User.setPassword 可能返回的错误码 */
-export type UserSetPasswordError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+export type UserSetPasswordError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
 /** User.update 可能返回的错误码 */
 export type UserUpdateError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
 

package/templates/app/packages/domain/package.json

@@ -14,11 +14,11 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@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",
+    "@yss123/cage-kernel": "0.4.0",
+    "@yss123/cage-admin": "0.4.0",
+    "@yss123/cage-approval": "0.4.0",
+    "@yss123/cage-connectors": "0.4.0",
+    "@yss123/cage-ai": "0.4.0",
     "zod": "^4.1.5"
   }
 }

package/templates/app/packages/domain/src/modules/purchase/approval-members.ts

@@ -1,7 +1,7 @@
 /**
  * 采购协作名录：由业务管理员登记可参与采购复核的账号、公开业务姓名和专业领域，供草稿选人及任务操作使用。
  * 聚合通过标准命令维护，浏览器读取 safe.approval_member；名录与 sys.user 的私密资料、角色授权分离。
- * 名录在同租户内向具 ApprovalMember.read 且显式获 all 范围的采购参与者公开；加入名录不授予审批权限、范围或额度。
+ * 名录在同租户内向具 ApprovalMember.read 且显式获 all 范围的采购参与者公开；加入名录不授予审批权限或范围。
  */
 import { aggregate, command, ref, scope, states, text } from '@yss123/cage-kernel';
 import { z } from 'zod';

package/templates/app/packages/domain/src/modules/purchase/approvals.ts

@@ -1,7 +1,7 @@
 /**
  * 采购实际审批路由：AI 预审、部门审核、可选专业会签和大额财务候选受理，共用一个采购流程实例。
  * 人工节点显式开放转办、委派和前后/并行加签；步骤/政策随提交保存，旧实例保持自己的快照。
- * 路由只决定任务分配与签序，最终结论仍执行领域命令的职责分离、额度与库存约束。
+ * 路由只决定任务分配与签序，最终结论仍执行领域命令的职责分离与库存约束。
  */
 import { approval } from '@yss123/cage-kernel';
 import { approver, eq, gt, route, step, when } from '@yss123/cage-approval';
@@ -28,7 +28,7 @@ export const poApproval = approval(PurchaseOrder, {
  * needsSpecialistReview=true 才增加专业会签，名单来自提交快照且全部人必须通过；金额严格大于 50000 元才增加财务节点。
  * AI 只读取 reason/amount/items，pass 仅推进到经理，return 回到草稿，manual 在当前节点交部门负责人。
  * 模型失败同样转人工，最多四轮/五次工具调用/120 秒；不以失败兜底为自动批准。
- * 财务共享一项未分配任务，finance 当前成员须先领取；所有人工动作仍需真实命令能力、范围、额度和职责分离。
+ * 财务共享一项未分配任务，finance 当前成员须先领取；所有人工动作仍需真实命令能力、范围和职责分离。
  * AI 人工接管保持原节点规则；经理、专业和财务才开放三项管理动作，新实例自动保存允许的加签位置。
  */
 export const poRoute = route('po-approval', [

package/templates/app/packages/domain/src/modules/purchase/intelligence.test.ts

@@ -25,7 +25,7 @@ beforeAll(async () => {
   env = await createTestEnv({ domain: { ...purchase, intelligence }, migrations: readMigrations(fileURLToPath(new URL('../../../../../db/migrations/', import.meta.url))) });
   buyer = await env.user({ caps: ['PurchaseOrder.read', 'PurchaseOrder.create', 'PurchaseOrder.explainPurpose', 'PurchaseOrder.submit', 'PurchaseOrder.setReviewers', 'ApprovalMember.read'],
     scopes: { ApprovalMember: 'all' } });
-  reviewer = await env.user({ caps: ['PurchaseOrder.read', 'PurchaseOrder.approve', 'PurchaseOrder.returnForChanges'], scopes: { PurchaseOrder: 'dept' }, params: { 'PurchaseOrder.approve': { ceiling: 50000 } } });
+  reviewer = await env.user({ caps: ['PurchaseOrder.read', 'PurchaseOrder.approve', 'PurchaseOrder.returnForChanges'], scopes: { PurchaseOrder: 'dept' } });
   await env.kernel.execute('Dept.update', { id: env.rootDeptId, leaderId: reviewer.id }, env.system());
   await env.kernel.execute('Inventory.create', { sku: 'AI-01', available: 100 }, env.system());
   const role = await env.kernel.execute('Role.create', { code: 'purchase_ai_reviewer', name: '材料预审角色' }, env.system());
@@ -39,12 +39,12 @@ beforeAll(async () => {
 afterAll(() => env?.close());
 
 /**
- * 通过组织和业务命令登记同部门协作人；10 万元额度只供本隔离库验证大额流程，名录本身不授予能力。
+ * 通过组织和业务命令登记同部门协作人；名录本身不授予能力。
  * 专业和财务共享这些真实审批能力，财务候选身份由额外的 finance 角色单独赋予。
  */
 async function collaborator(specialty: string) {
   const user = await env.user({ caps: ['PurchaseOrder.read', 'PurchaseOrder.approve', 'PurchaseOrder.reject', 'PurchaseOrder.returnForChanges'],
-    scopes: { PurchaseOrder: 'dept' }, params: { 'PurchaseOrder.approve': { ceiling: 100000 } } });
+    scopes: { PurchaseOrder: 'dept' } });
   await env.kernel.execute('ApprovalMember.create', { userId: user.id, displayName: specialty, specialty }, env.system());
   return user;
 }
@@ -145,7 +145,7 @@ it('经理后开启所选专业人员 all 会签，全部通过才批准并锁
   expect((await env.query('select status from core.inventory_lock where id=$1', [order.id]))[0].status).toBe('held');
 });
 
-/** gt 阈值必须保持严格大于；恰好 5 万元时经理的同额 ceiling 足够，不创建财务候选任务。 */
+/** gt 阈值必须保持严格大于；恰好 5 万元时不创建财务候选任务。 */
 it('恰好 50000 元经理通过后直接批准，不产生财务候选待办', async () => {
   decision = 'pass'; const order = await submit({ amount: '50000.00' });
   await approveBy(reviewer, order.id);

package/templates/app/packages/domain/src/modules/purchase/purchase-order.test.ts

@@ -12,7 +12,7 @@ let buyer: TestUser;
 let manager: TestUser;
 /**
  * 夹具通过真实命令建立部门负责人和库存，不绕过领域规则直接造业务行。
- * 申请人和经理能力分开，经理额度限定为 50000，确保后续断言真的经过职责分离与额度分支。
+ * 申请人和经理能力分开，以验证职责分离、业务批准和库存联动。
  */
 beforeAll(async () => {
   env = await createTestEnv({
@@ -24,19 +24,18 @@ beforeAll(async () => {
   });
   manager = await env.user({
     caps: ['PurchaseOrder.approve'],
-    params: { 'PurchaseOrder.approve': { ceiling: 50000 } },
   });
   await env.kernel.execute('Dept.update', { id: env.rootDeptId, leaderId: manager.id }, env.system());
   await env.kernel.execute('Inventory.create', { sku: 'A-01', available: 100 }, env.system());
 });
 afterAll(() => env?.close());
 
-/** 创建并提交一张 1200 元、两件 A-01 的采购单；只推进领域状态，不在此助手中消费 outbox。 */
-async function submitted() {
+/** 创建并提交两件 A-01 的采购单；金额默认 1200 元，不在此助手中消费 outbox。 */
+async function submitted(amount = '1200.00') {
   const ctx = await buyer.ctx();
   const order = await env.kernel.execute(
     'PurchaseOrder.create',
-    { amount: '1200.00', items: [{ sku: 'A-01', qty: 2 }] },
+    { amount, items: [{ sku: 'A-01', qty: 2 }] },
     ctx,
   );
   return env.kernel.execute('PurchaseOrder.submit', { id: order.id }, ctx);
@@ -126,21 +125,15 @@ it.each(['cancelled', 'received'] as const)(
   },
 );
 
-/** 低额度反例检查硬约束阻止批准，且同事务反应没有留下半成功的占用记录。 */
-it('审批额度不够时保留待审批状态，不创建库存锁', async () => {
-  const order = await submitted();
-  const lowLimit = await env.user({
-    caps: ['PurchaseOrder.approve'],
-    params: { 'PurchaseOrder.approve': { ceiling: 500 } },
-  });
+/** 领域命令不按角色金额限制批准；更大金额的额外步骤由采购流程声明负责。 */
+it('有批准能力的经理不需要额度参数即可执行大额采购结论', async () => {
+  const order = await submitted('60000.00');
   const process = env.kernel.processCtx({
     process: 'po-approval',
     tenantId: env.tenantId,
-    onBehalfOf: lowLimit.id,
+    onBehalfOf: manager.id,
     capabilities: ['PurchaseOrder.approve'],
   });
-  expect((await env.callAs(process, 'PurchaseOrder.approve', { id: order.id })).code).toBe(
-    'CONSTRAINT_VIOLATED',
-  );
-  expect(await env.query('select id from core.inventory_lock where id = $1', [order.id])).toHaveLength(0);
+  await env.kernel.execute('PurchaseOrder.approve', { id: order.id }, process);
+  expect((await env.query('select status from core.inventory_lock where id = $1', [order.id]))[0].status).toBe('held');
 });

package/templates/app/packages/domain/src/modules/purchase/purchase-order.ts

@@ -1,12 +1,11 @@
 /**
  * 采购单声明集中列出申请材料、专业复核名单、状态、范围、命令和事件，由 API、worker 和生成器统一消费。
  * 草稿可编辑专业复核名单，提交重新核对协作名录；handler 仅读取声明依赖，数据库写入、版本与审计由内核完成。
- * 审批结论仍以 process 命令执行职责分离、额度和库存检查；选入名录或路由不授予权限。
+ * 审批结论仍以 process 命令执行职责分离和库存检查；选入名录或路由不授予权限。
  */
 import {
   aggregate,
   bool,
-  ceiling,
   command,
   emit,
   event,
@@ -127,7 +126,7 @@ export const create = command(PurchaseOrder, {
 /**
  * 在 draft 中调整本单专业复核需求和名单；需要 PurchaseOrder.setReviewers，不能直接修改待审批快照。
  * 输入保存前核对 1–5 位不同且非提单人的 active 名录成员；关闭时用 false/[]，失败整次回滚。
- * 提交还会重新查询名录，以拒绝保存后退役的成员；名录不授予对单据的读取、批准能力或额度。
+ * 提交还会重新查询名录，以拒绝保存后退役的成员；名录不授予对单据的读取或批准能力。
  */
 export const setReviewers = command(PurchaseOrder, {
   name: 'setReviewers', description: '设置采购单专业复核需求和人员', from: 'draft', to: null,
@@ -179,7 +178,7 @@ export const submit = command(PurchaseOrder, {
 });
 
 /**
- * 审批终结命令必须同时满足创建人与审批人分离、当前角色额度，以及声明的库存只读检查。
+ * 审批终结命令必须同时满足创建人与审批人分离，以及声明的库存只读检查。
  * stock 是 reads 绑定的受范围约束仓储；找不到 SKU 或登记数量不足时返回 STOCK_SHORT 并回滚。
  * 该检查不扣减 available；真正占用由 OrderApproved 的同事务反应创建 InventoryLock。
  * 范例展示资源配对，不实现多订单累计扣减、仓库出入库或价格核算。
@@ -188,7 +187,7 @@ export const approve = command(PurchaseOrder, {
   from: 'pending_approval',
   to: 'approved',
   invokedBy: 'process',
-  constraints: [sod.notSameAs('createdBy'), ceiling('amount')],
+  constraints: [sod.notSameAs('createdBy')],
   reads: { stock: Inventory },
   emits: [OrderApproved],
   handler: async (o, _input, { stock }) => {

package/templates/app/packages/domain/src/workflows/purchase-process.ts

@@ -18,7 +18,7 @@ export const purchaseLifecycle = businessProcess('purchase-lifecycle', {
     approval: { title: '采购审批', description: 'AI 先核查材料；通过后部门经理审批，金额超过五万元时增加财务审批。疑难材料由本步骤转人工。', actor: 'AI、部门经理、财务', kind: 'decision', action: poApproval },
     returned: { title: '退回修改', description: '材料不足退回草稿，保留本轮审核理由。', actor: '审批流程', action: returnForChanges },
     revise: { title: '补充采购用途', description: '依据建议补充用途，再次提交后从 AI 预审开始。', actor: '申请人', action: explainPurpose },
-    approved: { title: '批准并锁定库存', description: '审批结论通过权限、额度和库存校验后，同事务锁定所需库存。', actor: '审批流程与系统', action: approve,
+    approved: { title: '批准并锁定库存', description: '审批结论通过权限和库存校验后，同事务锁定所需库存。', actor: '审批流程与系统', action: approve,
       related: [{ object: InventoryLock, label: '同事务锁库存', via: acquireLock }] },
     received: { title: '确认收货', description: '接收外部收货通知并更新采购单，异步释放库存锁。', actor: '外部系统与系统', kind: 'end', action: markReceived,
       related: [{ object: InventoryLock, label: '收货后释放占用', via: releaseLock }] },

package/templates/blank/.agents/skills/cage-development/SKILL.md

@@ -6,5 +6,5 @@ description: 使用 Cage 框架开发、修改和排查业务应用。适用于
 <!-- 由 scripts/sync-agent-skill.ts 生成；教学正文只在 docs/development 维护。 -->
 
 加载本技能后，先阅读[完整框架开发方法](../../../docs/development/skills/cage-development/SKILL.md)，再根据其中的任务选择表读取相关专题。
-正文包含 Cage 运行模型、与用户澄清业务并选择方案的方法、真实接入、排错与验收；不要只凭本入口的摘要开始编写业务。
+正文规定先理解需求、提出疑问与建议、查证框架，再说明实现映射、编码和验收；不要只凭本入口的摘要开始编写业务。
 当前项目的业务要求与 AGENTS.md 仍适用，框架维护任务遵守仓库的包边界。

package/templates/blank/AGENTS.md

@@ -10,14 +10,14 @@
 
 本节位于托管区之外，cage sync 会保留。下面的托管区提供框架工作方法。
 
-<!-- cage:begin v0.3.2 -->
+<!-- cage:begin v0.4.0 -->
 ## Cage 业务开发约定（框架托管）
 
 ### 学习与任务入口
 
 本项目使用 `@yss123/cage-*`，业务写在本项目。先读项目说明指定的教材；独立项目默认入口是 `docs/development/README.md`。
 
-开始 Cage 业务开发或排错时，加载 `docs/development/skills/cage-development/SKILL.md`。它讲清运行模型、业务澄清、能力选择、实施与验收方法；首次学习配合 `docs/development/getting-started/first-feature.md`。已熟悉时只读受影响专题，普通样式/文案改动无需重走业务建模。
+开始 Cage 业务开发或排错时，加载 `docs/development/skills/cage-development/SKILL.md`，统一按“理解需求 → 澄清 → 查证能力 → 说明实现映射 → 编码 → 验收”工作。首次学习配合 `docs/development/getting-started/first-feature.md`；已熟悉时只读受影响专题，普通样式/文案改动无需重走业务建模。
 
 支持 Agent Skills 的工具可发现 `.agents/skills/cage-development`；其他工具直接读取上述 Markdown，使用相同流程。教材随框架版本分发，均为本地文件，不需要额外服务、模型或索引。框架仓库范例使用项目说明指定的规范教材位置。
 
@@ -28,13 +28,13 @@
 - 角色、能力、数据范围、调用身份与业务约束分别建模。前端 can() 只影响显示，新增能力不自动授给生产角色；审批选人不授予能力。
 - 页面依赖生成契约及客户端。表单、弹窗等临时状态留在前端；正式业务数据和流程结果通过服务端读写。实际记录不能用模拟仓储或固定统计替代。
 
-### 实现与排错
+### 编码前的依据
 
-1. 阅读需求、文档和现有实现后，按 `docs/development/guides/business-collaboration.md` 主动提出疑点、可行选项、影响与推荐理由，让用户选择业务规则；沿用已明确的选择与授权，等待回答时推进独立部分，可选建议不阻塞已明确任务。再把确定的规则映射到聚合、命令、归属/范围、后续行为与验收，沿已有模块修改。具体选择看 `docs/development/guides/recipes.md`，目录归属看 `docs/development/reference/project-structure.md`。
-2. 不熟悉的 API 先按手册任务目录定位，用本地文件搜索查术语，再执行 `pnpm exec cage capabilities 符号 --format json` 核对当前版本签名；`cage context "业务关键词"` 定位当前应用。未命中不代表不支持，不发明方法或返回字段。
-3. 涉及已有领域含义变化，先 `pnpm exec cage snapshot save before-change` 保存本体基线，或使用真实 Git 基线。修改声明与导出，运行 check/gen，审查契约和迁移草稿。生成物不手改，已执行迁移不可改写。
-4. 页面使用真实契约，处理业务失败、版本冲突、会话与缓存；多页面使用独立 URL，列表筛选/分页进入查询参数。按 `docs/development/guides/routing.md` 验收深链接、刷新、登录回跳和无权限行为。
-5. 出错保留 code/at/reason/fix，查 `docs/errors/README.md` 与 `docs/development/tools/troubleshooting.md`；从真实调用逐层定位。不得放宽权限、删约束或关闭门禁来掩盖问题。
+业务疑点按 `docs/development/guides/business-collaboration.md` 提出选项、影响和推荐，让用户选择；沿用已明确的规则与授权。API 和当前行为由 agent 查证，普通技术方案自行决定；等待业务答案时推进独立部分。
+
+写代码前按 Skill 简述“已确认规则 → 已查证的 Cage 能力 → 修改位置 → 验收结果”，具体设计见 `docs/development/guides/recipes.md`。能力与签名查 `cage capabilities`，现有业务查 `cage context` 并阅读源码。未知规则和能力缺口不能靠猜测、编造 API 或复制示例填补；已明确的部分直接实施，不另设技术方案批准。
+
+涉及领域建模先读 `docs/development/guides/ontology-modeling.md`：说明对象含义、关系方向/基数、状态及动作前后结果，再写真实声明。聚合/字段/命令等填写结构化描述，每个状态填写 labels；中文注释和前端文案不会自动成为本体名称。处理本次声明的 CAGE-ONTOLOGY-001，并按业务例子核对关系和触发链；名称完整不能证明业务正确。自然语言、文档、表格和原型都是输入，不能由模板或页面布局代替业务判断。
 
 遇到原生 AI、AI 审批或随页助理，先读 `docs/development/guides/intelligence.md`，核对已有能力及应用启用状态。审批、文件、关系、数据传输等专题由 Skill 按需引导，不重建框架已有运行时。
 
@@ -42,12 +42,15 @@
 
 - 所有手写代码遵守 `docs/development/reference/commenting.md`：文件职责与调用链、导出 API/字段、复杂分支的中文说明，写清做什么、为什么、怎样完成及实际边界；随代码更新。生成物注释从生成器维护。
 - domain 按 modules/workflows/integrations/shared 组织，Web 按 app/modules/shared 组织。模块通过 index.ts 公开入口组合，前端不导入 domain、数据库或内核运行时；不关闭 modular 目录门禁。
+- 领域含义修改前保留本体或真实 Git 基线；修改声明后运行 check/gen，审查契约和迁移草稿。生成物不手改，已执行迁移不可改写；具体命令见 `docs/development/getting-started/workflow.md`。
+- 页面处理业务失败、版本冲突、会话与缓存；多页面使用独立 URL，筛选/分页进入查询参数，按 `docs/development/guides/routing.md` 实际验收。
 - 新项目启动步骤见 `docs/development/getting-started/workflow.md`。使用已有 PostgreSQL 和项目 .env；init 准备账号，migrate 更新结构，bootstrap 显式初始化组织，dev 启动进程。普通业务不新增连接池或管理 Docker。
 - 不输出或提交 .env、数据库密码、Cookie 密钥及初始化凭据。API 与 worker 使用一致的 domain，修改配置后按实际需要重启。
+- 出错保留 code/at/reason/fix，查 `docs/errors/README.md` 与 `docs/development/tools/troubleshooting.md`；不得放宽权限、删约束或关闭门禁来掩盖问题。
 
 ### 完成依据
 
-验证与改动匹配。check/gen/typecheck/build 证明各自检查范围；业务读写还需独立读取结果，权限需直接请求验证，审批需待办与结论，文件需实际内容，异步需任务终态，页面需浏览器操作。
+对照编码前的业务规则逐项验收，验证与改动匹配。check/gen/typecheck/build 证明各自检查范围；业务读写还需独立读取结果，权限需直接请求验证，审批需待办与结论，文件需实际内容，异步需任务终态，页面需浏览器操作。
 
 `pnpm verify` 汇总门禁；`verify --skip-tests` 不代表完整通过。诊断用 `cage doctor`、`timeline`、`explain`，具体前提见 `docs/development/tools/diagnostics.md`。交付分别说明通过、跳过、未执行及剩余配置；文档和可逆小改动不反复执行全量数据库回归。
 <!-- cage:end -->

package/templates/blank/apps/api/package.json

@@ -10,6 +10,6 @@
   },
   "dependencies": {
     "@app/domain": "workspace:*",
-    "@yss123/cage-http": "0.3.2"
+    "@yss123/cage-http": "0.4.0"
   }
 }

package/templates/blank/apps/web/package.json

@@ -8,9 +8,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@ant-design/icons": "^6.3.4",
     "@app/contracts": "workspace:*",
     "@tanstack/react-query": "^5.87.1",
-    "@yss123/cage-client": "0.3.2",
+    "@yss123/cage-client": "0.4.0",
+    "antd": "^6.7.0",
     "react": "^19.1.1",
     "react-dom": "^19.1.1",
     "react-markdown": "^10.1.0",

package/templates/blank/apps/web/src/app/styles/global.css

@@ -23,11 +23,11 @@ body {
   margin: 0;
   min-width: 1024px;
 }
-button,
+button:not(.ant-btn),
 input {
   font: inherit;
 }
-button,
+button:not(.ant-btn),
 a {
   -webkit-tap-highlight-color: transparent;
 }
@@ -39,16 +39,17 @@ button,
 .primary {
   cursor: pointer;
 }
-button:disabled {
+button:not(.ant-btn):disabled {
   cursor: wait;
   opacity: 0.65;
 }
-button:focus-visible,
+button:not(.ant-btn):focus-visible,
 a:focus-visible {
   outline: 3px solid #91bca2;
   outline-offset: 4px;
 }
-button {
+/* 原生按钮规则服务于模板现有的 DOM 控件，不覆盖新增的 Ant Design Button。 */
+button:not(.ant-btn) {
   transition:
     background 0.18s ease,
     border-color 0.18s ease;

package/templates/blank/apps/web/src/main.tsx

@@ -1,18 +1,29 @@
 /**
- * 空白业务应用的浏览器启动入口，创建共享 QueryClient 并挂载 app 路由。
- * 新增业务页面使用同一 Provider 内的生成查询 hooks；此处只装配前端，不注册领域或连接数据库。
- * 全局样式由入口加载，会话失效与账号切换时的查询清理由 useSession 负责。
+ * 空白业务应用的浏览器启动入口，装配 Ant Design 中文主题、共享 QueryClient 并挂载 app 路由。
+ * 新增页面使用同一组 Provider 内的 UI 上下文和生成查询 hooks；入口不注册领域或连接数据库。
+ * AntD reset 与全局样式由入口加载，会话失效和账号切换时的查询清理由 useSession 负责。
  */
-// 浏览器入口只负责挂载和全局 Provider。QueryClient 让新增模块可直接使用生成查询 hooks。
+// 浏览器入口只负责挂载 React、Ant Design 与查询 Provider，让新增模块使用统一 UI 和缓存上下文。
 import { createRoot } from 'react-dom/client';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { App as AntdApp, ConfigProvider } from 'antd';
+import zhCN from 'antd/locale/zh_CN';
 import { App } from './app/app';
+import 'antd/dist/reset.css';
 import './app/styles/global.css';
 
 const queryClient = new QueryClient();
 
+/**
+ * ConfigProvider 为组件提供简体中文文案和共享主题；AntdApp 提供上下文反馈方法。
+ * QueryClientProvider 承载生成查询 hooks 的缓存；三个 Provider 覆盖应用的全部路由。
+ */
 createRoot(document.getElementById('root')!).render(
-  <QueryClientProvider client={queryClient}>
-    <App />
-  </QueryClientProvider>,
+  <ConfigProvider locale={zhCN} theme={{ token: { colorPrimary: '#173e35', borderRadius: 4 } }}>
+    <AntdApp>
+      <QueryClientProvider client={queryClient}>
+        <App />
+      </QueryClientProvider>
+    </AntdApp>
+  </ConfigProvider>,
 );

package/templates/blank/cage.config.json

@@ -5,6 +5,7 @@
   "typecheck": ["packages/domain", "packages/contracts", "apps/api", "apps/web"],
   "graph": {
     "title": "业务应用图谱",
+    "naming": "required",
     "labels": {
       "aggregate:Dept": "部门",
       "aggregate:User": "用户",

package/templates/blank/docs/README.md

@@ -1,11 +1,13 @@
 # 本地框架文档
 
-从 [框架学习入口](development/README.md) 或 [Cage 开发 Skill](development/skills/cage-development/SKILL.md) 开始。
+编程 agent 先读项目 [AGENTS.md](../AGENTS.md)，按 [Cage 开发 Skill](development/skills/cage-development/SKILL.md) 理解需求、澄清、查证能力、说明实现映射，再编码与验收。
 
-- `development/getting-started`：运行模型、完整入门课和开发步骤。
-- `development/guides`：[业务澄清与共同设计](development/guides/business-collaboration.md)、能力选择与各专题接入。
+[任务导航](development/README.md) 说明各类文档的分工，按本次需要选择资料：
+
+- `development/getting-started`：运行模型、完整业务链和操作命令。
+- `development/guides`：[业务澄清](development/guides/business-collaboration.md)、[能力选择与实现映射](development/guides/recipes.md)、各专题接入。
 - `development/reference`：原语与工程规范。
 - `development/tools`：诊断、本体查询和排错。
 - `development/examples`：教学源码与采购导读。
-- `development/skills`：框架开发方法。
+- `development/skills`：唯一的 agent 工作流程。
 - [错误码册](errors/README.md)：按实际错误定位原因。