@yss123/cage-cli 0.3.1 → 0.4.0

package/templates/app/CLAUDE.md

@@ -0,0 +1,6 @@
+<!-- 由 scripts/sync-agent-skill.ts 生成；共享同一套框架教材。 -->
+# Cage 开发入口
+
+先读本目录 [AGENTS.md](AGENTS.md) 的项目说明和约定。
+进行 Cage 业务开发或排错时，阅读[框架开发 Skill](docs/development/skills/cage-development/SKILL.md)，按任务选择章节并完成对应验证。
+这是框架维护的通用教学流程；具体业务以用户需求和项目约定为准。

package/templates/app/README.md

@@ -4,9 +4,9 @@
 
 ## 让 AI 在本项目开发业务
 
-把本目录交给 Codex 等编程工具时，先让它读 [AGENTS.md](AGENTS.md)，再按[业务开发指南](docs/ai/README.md)和[任务配方](docs/ai/recipes.md)实现需求。普通业务不需要修改框架源码。
+把本目录交给 Codex 等编程工具时，先让它读 [AGENTS.md](AGENTS.md)，再按[业务开发指南](docs/development/README.md)和[任务配方](docs/development/guides/recipes.md)实现需求。普通业务不需要修改框架源码。
 
-[采购全链路导读](docs/ai/purchase-example.md)说明每个文件和异步步骤；[原语与最小业务](docs/ai/primitives.md)提供可添加的普通管理对象；[错误码册](docs/errors/README.md)用于按码修复。脚手架会将这些资料放入生成项目本地的 `docs/ai` 与 `docs/errors`，无需再次克隆框架。
+[采购全链路导读](docs/development/examples/purchase-example.md)说明每个文件和异步步骤；[原语与最小业务](docs/development/reference/primitives.md)提供可添加的普通管理对象；[错误码册](docs/errors/README.md)用于按码修复。脚手架会将这些资料放入生成项目本地的 `docs/development` 与 `docs/errors`，无需再次克隆框架。
 
 ## 启动
 
@@ -54,15 +54,15 @@ pnpm dev
 
 ## 体验完整采购流程
 
-前端使用 React Router：工作台 `/workspace`，采购列表 `/procurement/orders`，单据详情 `/procurement/orders/:id`，审批 `/approvals`，库存 `/inventory`，登录 `/login`。单号和审批待办可直接打开详情；刷新、前进后退和登录回跳保留页面地址。新增页面与部署按[路由和浏览器验收指南](docs/ai/routing.md)执行；Nginx 示例见 [deploy/nginx.conf](deploy/nginx.conf)。
+前端使用 React Router：工作台 `/workspace`，采购列表 `/procurement/orders`，单据详情 `/procurement/orders/:id`，审批 `/approvals`，库存 `/inventory`，登录 `/login`。单号和审批待办可直接打开详情；刷新、前进后退和登录回跳保留页面地址。新增页面与部署按[路由和浏览器验收指南](docs/development/guides/routing.md)执行；Nginx 示例见 [deploy/nginx.conf](deploy/nginx.conf)。
 
 1. 管理员在“库存台账”登记 `A-01` 等物料。
-2. 进入 `/admin/` 创建采购员、经理，分别分配采购命令和审批能力；经理的 `PurchaseOrder.approve` 参数配置 `ceiling`。
+2. 进入 `/admin/` 创建采购员、经理，分别分配采购命令、审批能力和所需数据范围。
 3. 把经理设为采购员所在部门的负责人。提单人与审批人必须不同。
 4. 为需要选人的采购参与者授予 `ApprovalMember.read` 与该聚合 `all` 范围，通过 `ApprovalMember.create` 登记审批协作人的公开业务姓名与专业领域；名录不授予实际审批能力。
 5. 采购员新建采购单，可开启专业复核并选择 1–5 人；草稿使用 `PurchaseOrder.setReviewers` 调整名单，提交时重新校验。worker 先执行 AI 材料预审；未配置模型或模型失败时按声明转人工接管。
 6. AI 预审/人工接管之后进入经理节点；启用专业复核时，经理后由所选人员全部会签。经理、专业和财务节点开放转办、委派归还和前置/后置/并行加签。
-7. 超过 50,000 元的采购继续进入财务共享候选池，需另建 code 为 `finance` 的角色并给实际用户配置权限、范围和额度；财务必须先领取，恰好 50,000 元跳过该步骤。
+7. 超过 50,000 元的采购继续进入财务共享候选池，需另建 code 为 `finance` 的角色并给实际用户配置权限和范围；财务必须先领取，恰好 50,000 元跳过该步骤。
 8. 全部必签完成后，最终审批命令同事务生成库存锁；worker 调用 fake ERP 并回写单号。取消单据或收到 ERP 收货回调后异步释放锁；回调需要 `ERP_WEBHOOK_SECRET` 对原始 JSON 的 HMAC-SHA256 签名。
 
 `Inventory.available` 是演示台账数量。本例验证库存锁生命周期，尚未实现仓库级的并发扣减、实物库存及退货核算。
@@ -87,6 +87,6 @@ pnpm dev
 - `apps/api/src`：API 和 worker 的薄启动入口。
 - `apps/web/src/app`、`modules`、`shared`：应用组合、业务页面、共享基础组件；`main.tsx` 只挂载。
 
-新增业务先读[工程目录与代码组织](docs/ai/project-structure.md)，不要继续在 src 根目录平铺文件。模板已启用模块目录门禁，`cage check` 和 `verify` 会指出目录与依赖越界。
+新增业务先读[工程目录与代码组织](docs/development/reference/project-structure.md)，不要继续在 src 根目录平铺文件。模板已启用模块目录门禁，`cage check` 和 `verify` 会指出目录与依赖越界。
 
 先运行 `pnpm cage gen` 再提交契约和迁移草稿；`pnpm cage verify` 检查完整工具链。派生测试遇到无法推断的业务输入会显示跳过，`purchase-order.test.ts` 另外准备真实业务数据覆盖成功审批和约束反例。

package/templates/app/apps/api/package.json

@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@app/domain": "workspace:*",
-    "@yss123/cage-http": "0.3.1",
-    "@yss123/cage-connectors": "0.3.1"
+    "@yss123/cage-http": "0.4.0",
+    "@yss123/cage-connectors": "0.4.0"
   }
 }

package/templates/app/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.1",
+    "@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/app/apps/web/src/app/styles/global.css

@@ -19,16 +19,17 @@
 body {
   margin: 0;
 }
-button,
+button:not(.ant-btn),
 input {
   font: inherit;
 }
-button,
+button:not(.ant-btn),
 a,
 input {
   outline-offset: 4px;
 }
-button {
+/* 原生按钮规则服务于范例中现有的手写 DOM 控件，不覆盖新增的 Ant Design Button。 */
+button:not(.ant-btn) {
   border: 1px solid var(--line);
   background: #fff;
   color: var(--green);
@@ -37,10 +38,10 @@ button {
   cursor: pointer;
   transition: background 0.15s;
 }
-button:hover {
+button:not(.ant-btn):hover {
   background: #edf2e8;
 }
-button:disabled {
+button:not(.ant-btn):disabled {
   opacity: 0.45;
   cursor: default;
 }
@@ -295,7 +296,7 @@ header {
   gap: 7px;
   flex-wrap: wrap;
 }
-.filters button {
+.filters button:not(.ant-btn) {
   border: 0;
   background: none;
   font-size: 12px;
@@ -305,7 +306,7 @@ header {
   background: #edf3e6;
   color: var(--green);
 }
-.toolbar > button {
+.toolbar > button:not(.ant-btn) {
   font-size: 11px;
 }
 /**
@@ -373,7 +374,7 @@ tr:last-child td {
   display: flex;
   gap: 7px;
 }
-.actions button {
+.actions button:not(.ant-btn) {
   font-size: 11px;
   padding: 6px 9px;
 }
@@ -386,7 +387,7 @@ tr:last-child td {
   font-size: 11px;
   color: var(--muted);
 }
-.pagination button {
+.pagination button:not(.ant-btn) {
   font-size: 11px;
   margin-left: 7px;
 }
@@ -442,7 +443,7 @@ tr:last-child td {
   font-size: 12px;
   margin-bottom: 20px;
 }
-.notice button {
+.notice button:not(.ant-btn) {
   background: transparent;
   border: 0;
 }
@@ -459,7 +460,7 @@ tr:last-child td {
   align-items: end;
   padding: 22px;
 }
-.stock-form button {
+.stock-form button:not(.ant-btn) {
   margin-bottom: 18px;
 }
 label {

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

@@ -1,18 +1,29 @@
 /**
- * 采购 Web 的浏览器启动入口：创建共享查询缓存，将应用路由挂到 root DOM 节点。
- * 契约客户端负责网络与会话协议，页面只在 Provider 内消费 hooks；这里不注册领域或启动后端。
- * 全局样式在此加载，账号切换时的缓存清理由 useSession 和应用壳负责。
+ * 采购 Web 的浏览器启动入口：装配 Ant Design 中文主题、共享查询缓存并挂载应用路由。
+ * 页面通过 Provider 消费 UI 上下文、生成契约客户端和查询 hooks；入口不注册领域或启动后端。
+ * AntD reset 与业务全局样式在此加载，账号切换时的缓存清理由 useSession 和应用壳负责。
  */
-// 唯一浏览器启动入口：挂载 React、全局 Provider 和样式；业务从 app 组合进入。
+// 唯一浏览器启动入口：挂载 React、Ant Design 与查询 Provider；业务从 app 组合进入。
 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 为 message、modal、notification 等反馈 API 提供上下文。
+ * 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/app/apps/web/src/shared/lib/error-message.ts

@@ -16,7 +16,7 @@ export function errorMessage(r: Extract<CageResult<unknown, string>, { ok: false
     INVALID_INPUT: '请检查填写内容',
     CONFLICT: '数据或任务已更新，请刷新后重试',
     UNAUTHENTICATED: '登录已过期',
-    CONSTRAINT_VIOLATED: '未满足审批条件，请检查审批人或额度',
+    CONSTRAINT_VIOLATED: '未满足业务条件，请检查操作人及具体原因',
     STOCK_SHORT: '库存不足',
     REVIEWERS_REQUIRED: '请为专业会签选择 1–5 位协作人',
     REVIEWERS_NOT_REQUIRED: '取消专业会签时请清空复核人员',

package/templates/app/apps/web/src/shared/ui/approval-member-picker.tsx

@@ -46,6 +46,6 @@ export function ApprovalMemberPicker({ value, onChange, max = 5, exclude = [], d
     {query.data && entries.length === 0 && <p className="muted">当前页没有匹配人员，请调整筛选或联系名录维护人。</p>}
     {(query.data?.total ?? 0) > 200 && <div className="actions"><button type="button" disabled={page === 1} onClick={() => setPage(page - 1)}>上一页</button>
       <span>第 {page} 页</span><button type="button" disabled={page * 200 >= query.data!.total} onClick={() => setPage(page + 1)}>下一页</button></div>}
-    <small className="muted">名录只提供选人信息，处理权限、数据范围和最终额度仍以服务端校验为准。</small>
+    <small className="muted">名录只提供选人信息，处理权限和数据范围仍以服务端校验为准。</small>
   </fieldset>;
 }

package/templates/app/cage.config.json

@@ -5,6 +5,7 @@
   "typecheck": ["packages/domain", "packages/contracts", "apps/api", "apps/web"],
   "graph": {
     "title": "采购业务图谱",
+    "naming": "required",
     "labels": {
       "module:purchase": "采购管理",
       "module:inventory": "库存管理",
@@ -125,7 +126,7 @@
       "state:Role.archived": "已停用",
       "field:Role.code": "角色编码",
       "field:Role.name": "角色名称",
-      "field:Role.capabilities": "能力点与额度",
+      "field:Role.capabilities": "能力点",
       "field:Role.scopes": "数据访问范围",
       "capability:Role.read": "查看角色",
       "capability:Role.export": "导出角色",

package/templates/app/docs/README.md

@@ -0,0 +1,13 @@
+# 本地框架文档
+
+编程 agent 先读项目 [AGENTS.md](../AGENTS.md)，按 [Cage 开发 Skill](development/skills/cage-development/SKILL.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`：唯一的 agent 工作流程。
+- [错误码册](errors/README.md)：按实际错误定位原因。

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

@@ -0,0 +1,80 @@
+# Cage 框架学习入口
+
+本目录面向使用 Cage 编写业务的 agent，帮助 agent 理解需求、查证框架并完成真实实现。先读项目 AGENTS.md，再按 [cage-development Skill](skills/cage-development/SKILL.md) 工作；本页只负责按任务定位资料。教材由框架维护，随脚手架分发，读取无需额外服务、模型或向量索引。
+
+工作主线：**理解需求 → 提出疑问与建议 → 核对现有业务和框架能力 → 说明实现映射 → 编码 → 按规则验收**。明确的规则直接采用，技术事实自行查证，需要用户决定的业务取舍再交给用户选择。
+
+模型接入、智能助理和 AI 审批属于框架的原生 AI 能力，具体接入见[原生 AI 专题](guides/intelligence.md)。
+
+## 按当前阶段阅读
+
+| 你现在需要什么 | 从哪里开始 | 应得到什么 |
+| --- | --- | --- |
+| 第一次使用 Cage | [Skill 的运行模型](skills/cage-development/SKILL.md#先建立正确的运行模型) → [第一条完整业务链](getting-started/first-feature.md) | 理解声明、导出、生成、授权、契约与持久读写如何连接 |
+| 用户描述或文档不清楚 | [业务澄清与共同设计](guides/business-collaboration.md) | 主动提出疑问、可行选项与建议，与用户选择业务规则，再落实到实现和验收 |
+| 把需求转成设计 | [业务设计与能力选择](guides/recipes.md) → [编码前的映射](skills/cage-development/SKILL.md#4-写代码前说明实现映射) | 业务规则、查证过的能力、修改位置和验收例子一一对应 |
+| 表达对象、状态和关系的业务含义 | [本体建模](guides/ontology-modeling.md) → [对象关系](guides/relations.md) | 名称写入真实声明，关系有正确方向、基数及执行依据，图谱能用业务用语阅读 |
+| AI 生成 React 页面与选择组件 | [前端组件指南](guides/frontend-ui.md) → [路由](guides/routing.md) | 生成可维护的真实 TSX 页面，使用 Ant Design 组合 UI，并按 Cage 契约读写 |
+| 实现或修改功能 | [Skill 的实施流程](skills/cage-development/SKILL.md#5-沿一条真实链路实施再扩展) → [开发步骤](getting-started/workflow.md) | 沿实际调用链完成受影响的功能，并取得验证证据 |
+| 已有功能不正常 | [排错方法](tools/troubleshooting.md) → [诊断工具](tools/diagnostics.md) / [错误码册](../errors/README.md) | 找到第一个失败边界，修复原因并复验 |
+| 查询一个能力的用法 | 下方专题表，必要时本地搜索术语 | 找到当前任务的 API、接入前提与限制 |
+
+已经熟悉框架时不必每次重读课程。不要将所有专题一次加载，也不要把参考业务注册到客户应用。
+
+## 各类文件的责任
+
+| 文件 | 负责什么 |
+| --- | --- |
+| 项目 AGENTS.md | 项目入口、代码与环境约束；项目业务约定保留在框架托管区外 |
+| [Skill](skills/cage-development/SKILL.md) | agent 的工作顺序、判断依据及何时与用户互动 |
+| [业务澄清](guides/business-collaboration.md) | 如何发现疑点、比较方案、保留并落实用户选择 |
+| [能力选择](guides/recipes.md) | 业务规则如何映射到 Cage，包含编码前的映射示例 |
+| [本体建模](guides/ontology-modeling.md) | 业务含义、结构化名称、对象关系和触发链写在哪里，以及怎样检查和验收 |
+| [开发步骤](getting-started/workflow.md) | 已确定设计的修改、生成、迁移和验证命令 |
+| 其他专题、参考与源码 | 当前能力用法、前提与边界，按需阅读；示例业务不成为当前需求 |
+
+## 按资料用途查找
+
+| 目录 | 内容与入口 |
+| --- | --- |
+| `getting-started/` 入门 | [运行模型](getting-started/architecture.md)、[完整入门课](getting-started/first-feature.md)、[开发步骤](getting-started/workflow.md) |
+| `guides/` 专题指南 | [业务澄清](guides/business-collaboration.md)、[能力选择](guides/recipes.md)、[本体建模](guides/ontology-modeling.md)、[前端组件](guides/frontend-ui.md)、[审批](guides/approvals.md)、[文件](guides/files.md)、[关系](guides/relations.md)、[路由](guides/routing.md)、[数据传输](guides/transfers.md)、[原生 AI](guides/intelligence.md) |
+| `reference/` 参考规范 | [原语](reference/primitives.md)、[目录组织](reference/project-structure.md)、[中文注释](reference/commenting.md) |
+| `tools/` 工具与排错 | [诊断](tools/diagnostics.md)、[本体上下文](tools/ontology-context.md)、[排错方法](tools/troubleshooting.md) |
+| `examples/` 教学示例 | [便笺源码](examples/note/note.ts)、[采购导读](examples/purchase-example.md)；按入门课与导读阅读，源码不自动注册 |
+| `skills/` agent 开发流程 | [cage-development](skills/cage-development/SKILL.md)，按任务加载上述教材 |
+
+查明确符号可用 `rg -n "术语或符号" docs/development docs/errors`，没有 rg 时使用 agent 的本地文件搜索。用 `pnpm exec cage capabilities 符号 --format json` 核对已安装版本公开签名，用 `pnpm exec cage context "业务关键词" --format json` 定位当前应用。候选命中不能代替阅读上下文，未命中也不能证明框架不支持。
+
+## 确认代码与资料的位置
+
+本指南的业务路径和命令默认相对应用根目录。应用的 `packages/domain/src` 定义业务，`packages/contracts/src` 是生成契约，`apps/web/src` 是界面，`apps/api/src` 是薄启动入口，`db/migrations` 保存审查过的迁移。
+
+空白模板只启用组织基础；`docs/examples/purchase-admin` 是离线采购参考源码，不参与注册、编译或迁移。采购模板直接在业务目录包含该范例。框架仓库的应用根目录是 `examples/purchase-admin`，规范教材位于仓库 `docs/development`，以应用 AGENTS.md 的说明为准。
+
+`docs/development` 是框架教学内容的唯一手写来源；Skills 发现入口和模板副本由同步脚本生成。用户的业务约定保留在项目已有业务文档或 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 选人或在途迁移，见[任务流转](guides/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/development/examples/note/note-detail-page.tsx

@@ -0,0 +1,106 @@
+/**
+ * 入门课详情页，从 URL 的 id 独立读取便笺并通过契约修改或归档。
+ * 由 app 组合到 /notes/:id；query 缓存与退出清理由现有应用会话层管理。
+ * 每次写入传服务端记录版本；冲突后刷新而不自动覆盖，归档后仅展示结果。
+ */
+import { useRef, useState } from 'react';
+import { Link, useParams } from 'react-router-dom';
+import { note, useNote } from '@app/contracts';
+import { useCan } from '@yss123/cage-client';
+
+/** 加载独立详情；标题草稿为 null 时显示服务端标题，空字符串仍表示用户正在编辑。 */
+export function NoteDetailPage() {
+  const { id = '' } = useParams();
+  const query = useNote(id);
+  const canUpdate = useCan('Note.update');
+  const canArchive = useCan('Note.archive');
+  const [draft, setDraft] = useState<{ id: string; title: string } | null>(null);
+  const [error, setError] = useState('');
+  const [saving, setSaving] = useState(false);
+  const submitting = useRef(false);
+  const record = query.data;
+  const title = draft?.id === id ? draft.title : (record?.title ?? '');
+
+  /**
+   * 保存或归档当前记录，使用读取版本防止覆盖并发变更；失败保留草稿，成功后清除草稿并读取。
+   * 冲突刷新后要求用户核对再提交；按钮禁用与引用锁限制本页同时提交，不替代内核检查。
+   */
+  async function save(action: 'update' | 'archive') {
+    if (!record || submitting.current) return;
+    submitting.current = true;
+    setSaving(true);
+    setError('');
+    try {
+      const result =
+        action === 'update'
+          ? await note.update(record.id, { title }, record.version)
+          : await note.archive(record.id, record.version);
+      if (!result.ok) {
+        setError(
+          result.code === 'CONFLICT'
+            ? '记录已变化，请核对最新数据和当前草稿后再提交。'
+            : `操作失败：${result.code}`,
+        );
+        if (result.code === 'CONFLICT') await query.refetch();
+        return;
+      }
+      setDraft(null);
+      await query.refetch();
+    } catch {
+      setError('请求未完成，请重新读取记录确认结果。');
+    } finally {
+      submitting.current = false;
+      setSaving(false);
+    }
+  }
+
+  return (
+    <section>
+      <Link to="/notes">返回列表</Link>
+      {query.isPending && <p role="status">正在加载…</p>}
+      {query.isError && (
+        <p role="alert">
+          无法读取记录：可能不存在、会话失效或不在可见范围。
+          <button onClick={() => void query.refetch()}>重试</button>
+        </p>
+      )}
+      {record && (
+        <>
+          <h1>{record.title}</h1>
+          <p>
+            状态：{record.status}；版本：{record.version}
+          </p>
+          {record.status === 'active' && (
+            <>
+              {canUpdate && (
+                <form
+                  onSubmit={(event) => {
+                    event.preventDefault();
+                    void save('update');
+                  }}
+                >
+                  <label>
+                    标题
+                    <input
+                      value={title}
+                      required
+                      maxLength={120}
+                      onChange={(event) => setDraft({ id, title: event.target.value })}
+                    />
+                  </label>
+                  <button disabled={saving || !title.trim()}>保存</button>
+                </form>
+              )}
+              {canArchive && (
+                <button disabled={saving} onClick={() => void save('archive')}>
+                  归档
+                </button>
+              )}
+            </>
+          )}
+        </>
+      )}
+      {error && <p role="alert">{error}</p>}
+    </section>
+  );
+}

package/templates/app/docs/development/examples/note/note.ts

@@ -0,0 +1,71 @@
+/**
+ * 框架入门课的部门便笺声明，由学习者放入应用领域模块后从 domain 入口导出。
+ * 聚合维护标题、归属和状态；命令仅描述业务变化，实际权限、事务与持久化由内核执行。
+ * 本文件作为教材分发，不自动注册到空白应用；不存在文件、审批或外部 IO 副作用。
+ */
+import { aggregate, command, ref, scope, states, text } from '@yss123/cage-kernel';
+import { z } from 'zod';
+
+/**
+ * 部门便笺以标题和生命周期为一致性边界，通过部门与创建人字段支持安全读取。
+ * 声明被 domain 导出后参与注册和生成；实际可见范围取决于角色授权，本声明不授予权限。
+ * 所有命令结果均须满足非空标题不变量，归档保留记录并关闭修改入口。
+ */
+export const Note = aggregate('Note', {
+  description: '部门便笺',
+  fields: {
+    /** 标题最多 120 字符；命令先去除两端空白，不变量拒绝空白标题。 */
+    title: text(120).describe('便笺标题'),
+    /** 内核新建时按当前主体填充的部门，用于服务端范围过滤。 */
+    deptId: ref('Dept').describe('所属部门'),
+    /** 内核新建时记录的创建人，可用于本人范围；不接受客户端指定。 */
+    createdBy: ref('User').describe('创建人'),
+  },
+  // 机器状态用于命令和存储，业务名供图谱与上下文读取；普通注释不会替代 labels。
+  states: states('active', 'archived', {
+    terminal: ['archived'],
+    labels: { active: '使用中', archived: '已归档' },
+  }),
+  scope: scope.deptSubtree('deptId'),
+  invariants: { titleNotBlank: (record) => record.title.trim().length > 0 },
+});
+
+/**
+ * 创建 active 便笺，输入只有去除两端空白后的标题，草稿直接作为业务结果返回。
+ * 内核填写归属并执行 Note.create 授权、审计及事务；空标题、无能力或不合格范围会拒绝写入。
+ * 不发布额外业务事件，也不接受客户端指定归属字段。
+ */
+export const createNote = command(Note, {
+  name: 'create',
+  description: '创建便笺',
+  from: 'new',
+  to: 'active',
+  input: z.object({ title: z.string().trim().min(1).max(120) }),
+  handler: (draft) => draft,
+});
+
+/**
+ * 修改 active 便笺标题；id 用于内核按范围锁定记录，页面另传已读取的 expectedVersion。
+ * to: null 保留状态，返回值只包含标题变化；归档或版本冲突由内核拒绝，handler 不直接写库。
+ */
+export const updateNote = command(Note, {
+  name: 'update',
+  description: '修改便笺标题',
+  from: 'active',
+  to: null,
+  input: z.object({ id: z.string().uuid(), title: z.string().trim().min(1).max(120) }),
+  handler: (_draft, input) => ({ title: input.title }),
+});
+
+/**
+ * 归档 active 便笺，输入沿用已有对象命令的默认 id，返回草稿以保留标题与归属。
+ * 内核检查 Note.archive、范围与版本，再设置 archived；已有归档记录的修改和重复归档会拒绝。
+ * 本动作不删除历史记录，不发布需 worker 处理的业务事件。
+ */
+export const archiveNote = command(Note, {
+  name: 'archive',
+  description: '归档便笺',
+  from: 'active',
+  to: 'archived',
+  handler: (draft) => draft,
+});

package/templates/app/docs/development/examples/note/notes-page.tsx

@@ -0,0 +1,87 @@
+/**
+ * 入门课的便笺列表与创建页面，通过生成契约读写服务端记录，不维护本地业务仓储。
+ * 由 app 路由在已登录且具备 Note.read 的页面内挂载；服务端仍执行全部权限与范围判断。
+ * 表单状态只保留未提交标题，失败不清空；创建成功后重新查询列表，详情使用独立 URL。
+ */
+import { useRef, useState, type FormEvent } from 'react';
+import { Link } from 'react-router-dom';
+import { note, useNoteList } from '@app/contracts';
+import { useCan } from '@yss123/cage-client';
+
+/** 显示当前主体可见的第一页便笺并提供创建入口；分页扩展应按路由规范放入 URL 参数。 */
+export function NotesPage() {
+  const query = useNoteList();
+  const canCreate = useCan('Note.create');
+  const [title, setTitle] = useState('');
+  const [error, setError] = useState('');
+  const [saving, setSaving] = useState(false);
+  const submitting = useRef(false);
+
+  /**
+   * 提交一次创建，立即锁住重复点击；业务失败保留输入，成功后从安全接口重新读取。
+   * 此锁只限制当前页面的并发点击，不承诺跨刷新重试去重；业务需恢复同次请求时另保存幂等键。
+   */
+  async function create(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    if (submitting.current) return;
+    submitting.current = true;
+    setSaving(true);
+    setError('');
+    try {
+      const result = await note.create({ title });
+      if (!result.ok) {
+        setError(`创建失败：${result.code}`);
+        return;
+      }
+      setTitle('');
+      await query.refetch();
+    } catch {
+      setError('请求未完成，请重新读取列表确认结果后再决定是否重试。');
+    } finally {
+      submitting.current = false;
+      setSaving(false);
+    }
+  }
+
+  return (
+    <section>
+      <h1>部门便笺</h1>
+      {canCreate && (
+        <form onSubmit={create}>
+          <label>
+            标题
+            <input
+              value={title}
+              maxLength={120}
+              required
+              onChange={(event) => setTitle(event.target.value)}
+            />
+          </label>
+          <button disabled={saving || !title.trim()}>{saving ? '正在保存…' : '创建'}</button>
+        </form>
+      )}
+      {error && <p role="alert">{error}</p>}
+      {query.isPending && <p role="status">正在加载…</p>}
+      {query.isError && (
+        <p role="alert">
+          读取失败，请检查会话和读取权限。<button onClick={() => void query.refetch()}>重试</button>
+        </p>
+      )}
+      {query.data && (
+        <>
+          <p>
+            共 {query.data.total} 条，当前显示 {query.data.items.length} 条。
+          </p>
+          <ul>
+            {query.data.items.map((record) => (
+              <li key={record.id}>
+                <Link to={`/notes/${encodeURIComponent(record.id)}`}>{record.title}</Link>（{record.status}）
+              </li>
+            ))}
+          </ul>
+          {query.data.items.length === 0 && <p>当前可见范围内没有便笺。</p>}
+        </>
+      )}
+    </section>
+  );
+}