@yss123/cage-cli 0.3.1 → 0.4.0

package/dist/sync.js

@@ -8,130 +8,54 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { abs } from './config.js';
 import { VERSION } from './version.js';
-/** 当前 CLI 版本对应的项目协作说明；这是分发给 agent 的文档，不是运行时业务配置。 */
+/**
+ * 当前 CLI 版本的项目约束与资料入口，由 create/sync/upgrade 写入 AGENTS 托管区。
+ * 工作顺序由唯一 Skill 正文维护，这里保留必须遵守的边界和编码前的理解要求，
+ * 避免另写一套实施流程；该文本只指导 agent，不启用服务、不改变授权或数据库。
+ */
 export const managedBlock = `<!-- cage:begin v${VERSION} -->
 ## Cage 业务开发约定（框架托管）
 
-### 先读，再按需求改业务
-
-本项目由 create-cage-app 创建。框架来自 \`@yss123/cage-*\` 依赖，业务写在本项目；不需要克隆框架仓库，也不要复制框架内部实现。
-
-先读项目说明指定的学习资料，默认入口为 \`docs/ai/README.md\`。第一次读 \`architecture.md\`、\`project-structure.md\` 和 \`primitives.md\`；具体任务读 \`recipes.md\`，采购全链路读 \`purchase-example.md\`，错误查 \`docs/errors/README.md\` 和 \`docs/ai/troubleshooting.md\`。资料相对该学习目录，项目说明可指定源码仓库中的规范资料位置。
-
-### 详细中文注释（每次开发必须遵守）
-
-所有新增和维护的手写源码都必须写详细中文注释，先读学习目录中的 \`commenting.md\`（独立项目为 \`docs/ai/commenting.md\`）。注释是交付内容，不能以“代码自解释”或“保持简洁”为由省略。
-
-- 每个文件开头说明模块职责、谁调用它、主要调用链和责任边界；纯导出入口也说明如何组合模块。
-- 导出函数、类、组件、hooks、接口和业务声明使用 JSDoc，写清用途、参数含义、返回结果、主要步骤、前置条件、失败行为和副作用；复杂内部函数同样说明。参数类型已表达的语法无需重复，业务单位、空值、默认行为与约束必须解释。
-- 领域代码说明字段和状态的业务意义、命令调用身份与权限/范围、reads 依赖、事件用途、事务与异步边界、幂等/重试及资源释放；只写实际声明和实现已有的保证。
-- 页面说明 URL/查询参数、数据来源、临时状态、加载/空态/失败/无权限、提交后的刷新、会话与订阅清理；复杂分支、计算、顺序、并发和缓存规则在附近解释原因与过程。
-- 测试说明场景、前置条件、动作、断言和所防止的回归；脚本说明输入、读写路径、执行顺序、外部副作用与退出条件。注释不含密钥、凭据或个人数据。
-- 注释同时回答“做什么、为什么、如何完成、有哪些边界”，不能只有一句标题，也不能机械逐行翻译、凑字数或批量粘贴空泛模板。代码变更时同步更新注释，交付前逐文件核对。
-- 生成契约的注释由生成器维护，不手改生成物；已执行/已发布迁移不能改写。仅补注释时不得顺便重构或改变逻辑、接口、配置值和运行文案。
-
-### 原生 AI 能力入口
-
-遇到以下需求，先读 \`docs/ai/intelligence.md\`，用 \`pnpm exec cage capabilities "关键词" --format json\` 核对当前安装版本的公开 API，再检查本项目 domain 导出和页面接入。关键词可直接使用下表需求名称；未命中时缩短关键词或查公开符号，不能据此断言能力不存在。
-
-| 需求 | 框架入口与应用职责 |
-| --- | --- |
-| AI审批 / 智能审批 | 现有 \`step\` 使用 \`kind: 'ai'\`，支持 pass 通过、return 退回修改、manual 转人工；应用声明策略、结论命令、自动执行角色及接管人 |
-| 业务助理 / 本体助理 | 导出 \`ai({ models, assistant })\`；框架提供执行循环、按领域声明生成的工具、会话、偏好记忆和 HTTP；应用配置授权及界面 |
-| 页面上下文 / 随页助理 | \`useAssistant(client.ai, page)\` 配合 \`useAiPageContext\` / \`AiPageContext\`；应用上报页面、对象、选中项和草稿，服务端重读并校验业务事实 |
-| 模型管理 / Responses | \`managedModel\` 接入 Admin 动态配置，支持 Chat Completions / Responses；应用配置部署加密密钥并显式授权管理者 |
-| 性格 / 流式输出 | Admin 管理性格，SDK 提供选择、增量文字与执行进度；应用实现悬浮窗、Markdown 和确认卡片 |
-| 上下文预算 | \`ai({ context: ... })\` 的配置形状见 \`AiContextOptions\`；框架按预算选择完整工具或发现模式，历史和本体按需读取 |
-
-前端只使用客户端、协议与契约；后端循环、通用工具和记忆使用框架实现。页面快照和性格不授予权限。分别核对**框架支持**（公开导出）、**项目已启用**（domain 导出、迁移、模型、权限、worker、SDK）和**实际验证通过**（真实角色与模型联调）；空白模板的参考代码不表示已启用。具体接入顺序和验收步骤见该指南，不必将整份指南塞入每次任务上下文。
-
-### 业务代码放在哪里
-
-| 位置 | 职责 |
-| --- | --- |
-| \`packages/domain/src/modules/<业务>\` | 同业务聚合、状态、命令、事件、审批、查询、任务；模块 index.ts 公开导出 |
-| \`packages/domain/src/workflows\`、\`integrations\` | 跨模块反应 / 第三方协议与映射；不堆到全局 reactions.ts、queries.ts |
-| \`packages/domain/src/index.ts\` | 统一导出全部业务及组织模型；没导出的声明不会注册 |
-| \`packages/contracts/src/aggregates/<聚合>\`、\`queries\` | 生成协议；根 index.ts 提供 @app/contracts 公共入口，只用 cage gen 更新 |
-| \`apps/api/src\` | API/worker 薄启动入口，普通业务不手写 HTTP 路由 |
-| \`apps/web/src/app\` | 会话、URL 路由、布局、模块组合；main.tsx 只挂载和装配 Provider |
-| \`apps/web/src/modules/<业务>\` | 页面、表单、专用 hooks/API/样式；从模块 index.ts 暴露页面 |
-| \`apps/web/src/shared\` | 跨模块复用且不绑定业务的 UI、hooks、纯辅助函数 |
-| \`db/migrations\` | 审查过的结构迁移，作用于已配置的数据库 |
-| \`cage.config.json\` | 项目路径、检查配置、graph.labels 中文图谱名称 |
-| \`.env\` | 本机真实连接和密钥；不提交、不输出完整内容 |
-
-新增业务不得继续平铺在 src 根目录。前端模块只依赖自己和 shared，由 app 通过公开入口组合；shared 不反向依赖业务。领域模块间确有读取依赖时走目标模块 index.ts；跨模块反应写 workflows。小模块不创建空层级，已有独立职责再拆文件。完整命名、目录树和示例见 \`docs/ai/project-structure.md\`。新模板启用 \`structure: modular\`，check/verify 检查目录和导入边界，遇到 CAGE-STRUCT 错误按职责修正。
-
-### 实现一项需求的顺序
-
-1. 先运行 \`pnpm exec cage context "需求关键词"\`；按需 \`graph search\` 查候选、\`graph inspect\` 查完整节点、\`graph path\` 看关系路径。确认中文匹配入口后按源码位置阅读实现；候选和子图不是全部依赖，具体条件不能凭连线推断。完整用法见 \`docs/ai/ontology-context.md\`。从用户需求确定字段、状态/动作、角色/范围、约束与后续动作；能由业务声明表达的不改框架。
-2. 已有业务含义变化时，修改前用 \`pnpm exec cage snapshot save before-change\` 保存不可覆盖的命名基线；或使用真实 Git 提交/独立本体图文件。
-3. 先声明 aggregate/states/command/constraints/event，再写 handler、reaction/query/approval/connector，最后接业务页面。声明使用模块顶层 \`export const\`，从 domain 入口导出，跨文件导出名保持唯一。
-4. 运行 \`pnpm exec cage check\` 和 \`pnpm gen\`，审查 contracts 和迁移草稿。按需运行 \`pnpm exec cage impact --snapshot before-change\`，补中文图谱名。
-5. 页面使用生成方法并处理 code/domainCode；列表、详情等多页面注册到 React Router，Link/NavLink 导航，筛选/分页进入 URL。组件状态用于弹窗和表单等临时交互。新增能力由管理员授权。数据库结构变化审查后显式 \`pnpm migrate\`，dev 不代办迁移。
-6. 按 \`commenting.md\` 逐文件检查详细中文注释与实现一致，再按改动运行必要验证；交付时说明体验步骤、授权配置、迁移、注释覆盖，以及通过/跳过/未执行项。
-
-### 必守边界
-
-- 聚合定义对象字段、状态、范围字段与不变量；命令是业务写入口。handler 只计算业务变化和读取 reads 中的依赖，不直接操作数据库、网络或文件。
-- 对象关系统一放在 fields：ref 为外键，hasMany 为只读反查，manyToMany 自动生成中间表并随所属对象命令提交。前端用生成的 related 方法分页读取；不手写纯中间表聚合，不把单页结果当完整集合替换。完整例子见 docs/ai/relations.md。
-- command 的 input 使用 Zod；已有记录输入必须含 id。from/to 表达状态迁移；\`to: null\` 只适用于已有记录并保留状态，不能靠 handler 改 status 绕过状态机。
-- 写入、审计、版本、幂等和事务交给内核；不要在业务项目重建 repository、连接池或权限流水线。
-- 自定义查询声明 reads，二选一使用 sql/build，只读 \`safe.*\`；值参数化。不得拼接 SQL、查询基表绕过范围或硬编码密钥。
-- scope 描述范围字段，角色数据决定实际范围；\`scope.none()\` 不代表所有人可访问。\`can/useCan\` 只控制按钮，后端负责授权。
-- 前端从 \`@app/contracts\` 导入生成 API/类型，按需使用 \`@yss123/cage-client\`；不导入 domain、内核或数据库包。
-- 多页面业务必须有独立 URL，不用 useState/tab 模拟整页导航；详情从 URL 取 ID 并独立加载。前端路由集中在 app，页面从模块公开入口接入 Outlet。登录后保留原路径/query/hash，401 回登录，403 展示权限提示；/admin/ 使用普通链接进入独立系统管理。前端路由不替代后端授权。实现、SPA 部署回退和浏览器配方见 docs/ai/routing.md。
-- 跨聚合写入通过 reaction 调用命令。\`tx: 'same'\` 共同提交/回滚，默认 outbox 异步执行。资源 acquires/releases 是图规则标签，实际占用/释放仍由命令完成；离开持有状态要检查每条释放路径。
-- 批量调用同一命令使用 reactionEach，声明 maxItems、唯一排序字段 orderBy、items 和 map；稳定键排序后串行执行。步骤依赖用 order，同事件同事务分组不得混用有序/无序或重复顺序。保持同事务回滚边界，见 docs/ai/primitives.md。
-- 审批通过 approval + route 配置，结论是 process 命令；选中审批人不等于已具备能力、范围和额度。parallel(title, ...branch(...)) 声明结构化 AND：分支同时开始，内部顺序独立，全部活动分支完成后汇合；when 支持嵌套并仍按提交快照求值，声明有深度/数量边界，不支持任意跳转。currentSteps 表示当前活动节点集合，兼容字段 currentStep 只是最小活动索引，不能据此隐藏其他分支。人工节点 assignment: 'candidate' 开放候选领取/释放，approver.field 从 routable 字段选人；actions 开放转办、委派归还和前后/并行必签。任务操作与决定携带 revision，waiting 任务只能查看。approvalOperations() 为框架通用时效运行时：step.sla 配置自然分钟节点总时限，route.reminders 配置申请人催办；迁移并运行 worker 后提供持久站内提醒、已读与 Admin 通用页面，不自动批准或授予权限。政策、SDK 和边界见 docs/ai/approvals.md。第三方 IO 通过连接器，回调验签后调用 external 命令。
-- job 的读取与调用必须列入 reads/calls。业务导入/导出放在需要的业务页面调用通用任务接口，202 只代表任务已接受；worker 必须运行。
-- 已部署事件只做兼容扩展；新增字段设为 optional，不兼容含义用新事件。已执行/已发布迁移不能改写，结构更新新增迁移。
-- 不手改生成物，不关闭门禁掩盖错误，不因方便自动授予生产角色新能力。unsafe 必须写明 reason/owner，不能替代普通业务声明。
-- 按前述详细中文注释规范完成文件、API、业务声明和关键流程说明；避免无业务价值的防御分支和静默兜底。维护脚本用 TypeScript，不新增 .mjs。
-
-### 最小命令形状
-
-\`\`\`ts
-// 片段：Order 为已导出的聚合，OrderSubmitted 为事件，业务校验按需求添加。
-/**
- * 将草稿订单提交审批：只有 draft 可进入 pending_approval。
- * 入口使用 Order.submit 能力，真实授权、范围、状态和版本由内核检查；声明本身不自动授予权限。
- * handler 返回草稿供后续校验和持久化，OrderSubmitted 随命令事务登记，后续由已配置消费者处理。
- * 失败不会提交这次业务变更；事件已登记也不代表后续审批已经完成。
- */
-export const submitOrder = command(Order, {
-  name: 'submit',
-  from: 'draft',
-  to: 'pending_approval',
-  emits: [OrderSubmitted],
-  handler: (draft) => draft,
-});
-\`\`\`
-
-完整可添加的普通管理对象见 \`docs/ai/primitives.md\` 的 Note；采购模板的审批、资源、第三方示例在 \`packages/domain/src\`，空白模板的参考源码在 \`docs/examples/purchase-admin\`。先读本项目 AGENTS.md 中的模板说明，区分运行代码与参考资料。API 以当前包公开导出和生成契约为准，不发明不存在的配置和方法。
-
-### 启动、验证与排错
-
-在项目根目录执行：首次 \`pnpm install\`，复制并编辑 .env.example，仅提供已有库管理员连接后 \`pnpm exec cage init\`；再 \`pnpm build:app\`、\`pnpm gen\`，审查后 \`pnpm migrate\`；用 \`pnpm exec cage bootstrap --credentials-file .cage/admin-credentials.json\` 显式初始化组织，最后 \`pnpm dev\`。已有配置不能覆盖，凭据文件必须是新受限文件且父目录存在。
-
-init 只准备账号/schema/授权并填写三个连接，不创建数据库；APP/READ/MIGRATE 指向同一个库。已有集群账号复用原密码，日常启动不用管理员。普通项目不新增 Docker 生命周期命令。
-
-API 日常启动不初始化组织、不输出管理员密码；生产缺少合格 Cookie 密钥会拒绝启动。bootstrap 不自动授予业务能力。\`/healthz\` 只表示存活，\`/readyz\` 检查必要依赖。首阶段 API 与 worker 同版本部署，查看实际注册指纹和消费者心跳。
-
-- \`pnpm exec cage graph\`：浏览器图谱，默认端口 15418，以终端为准。
-- \`pnpm exec cage context command:对象.命令 --format json --out .cage/context.json\`：按完整 key 取精简上下文；默认 Markdown，可用 --depth/--limit 调整范围。CLI 每次重新抽取；Web“复制 AI 上下文”使用当前页面快照，改代码后先刷新图谱。
-- \`graph inspect/path\` 有歧义时复制候选完整 key；path 默认沿箭头，--direction both 的逆向遍历不表示执行方向。报告中的测试/前端文件是候选，须核对；context 与图谱查询不覆盖当前图或命名快照。
-- \`pnpm exec cage capabilities 关键词 --format json\`：查当前安装版本公开签名；\`cage doctor\`：区分注册、生成、构建、迁移、授权与实际进程证据，unknown 不能当作通过。\`cage timeline/explain\` 关联实际异步证据与解释授权，参数和权限见 docs/ai/diagnostics.md。
-- 生成方法支持 signal/timeoutMs/idempotencyKey 请求选项。底层 CageResult 与 mutation 行为有区别：useCageCommand 失败抛 CageCommandError，成功才返回业务数据。订阅 client.subscribe 在退出、401、切换账号时取消查询并清除应用缓存。
-- \`pnpm exec cage gen --check\`：生成一致性；\`pnpm exec cage sync --check\`：本托管区一致性。
-- \`pnpm exec cage test --only project\`：业务测试；\`pnpm verify\`：类型、依赖、lint、图规则、生成、托管区、预算和测试。
-- \`pnpm exec cage verify --skip-tests\` 表示不完整门禁；派生测试跳过不能当作通过。测试连接只用独立测试集群。
-- 重要业务改动验证成功路径及有风险的反例；文档或可逆的小改动不反复跑全量数据库测试。
-- 修改页面/导航后实际验收深链接、刷新、前进后退、登录回跳、无权限和 404；生产再查 SPA 回退。check/verify 不自动完成浏览器验收，未执行要明确报告。见 docs/ai/routing.md。
-- CLI 报错先看 code/at/reason/fix，再查错误码册；HTTP 错误查 runtime.md。异步失败先看 worker、同步记录和死信，修复后重放，不能直接 SQL 改状态。
-
-框架托管区由 cage sync 更新；项目独有的业务规则写在标记之外，避免升级覆盖。
+### 学习与任务入口
+
+本项目使用 \`@yss123/cage-*\`，业务写在本项目。先读项目说明指定的教材；独立项目默认入口是 \`docs/development/README.md\`。
+
+开始 Cage 业务开发或排错时，加载 \`docs/development/skills/cage-development/SKILL.md\`，统一按“理解需求 → 澄清 → 查证能力 → 说明实现映射 → 编码 → 验收”工作。首次学习配合 \`docs/development/getting-started/first-feature.md\`；已熟悉时只读受影响专题，普通样式/文案改动无需重走业务建模。
+
+支持 Agent Skills 的工具可发现 \`.agents/skills/cage-development\`；其他工具直接读取上述 Markdown，使用相同流程。教材随框架版本分发，均为本地文件，不需要额外服务、模型或索引。框架仓库范例使用项目说明指定的规范教材位置。
+
+### 框架执行什么
+
+- 业务声明从 domain 总入口导出，框架据此构建注册表、能力、HTTP 接口、本体图、契约与迁移草稿；只有文件而未导出不会生效。
+- 命令是业务写入口；handler 描述变化与显式 reads，内核处理授权、状态、范围、版本、事务、审计及 outbox。读侧通过生成契约或 query 的安全视图，外部 IO 通过连接器。
+- 角色、能力、数据范围、调用身份与业务约束分别建模。前端 can() 只影响显示，新增能力不自动授给生产角色；审批选人不授予能力。
+- 页面依赖生成契约及客户端。表单、弹窗等临时状态留在前端；正式业务数据和流程结果通过服务端读写。实际记录不能用模拟仓储或固定统计替代。
+
+### 编码前的依据
+
+业务疑点按 \`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 按需引导，不重建框架已有运行时。
+
+### 代码与环境边界
+
+- 所有手写代码遵守 \`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 证明各自检查范围；业务读写还需独立读取结果，权限需直接请求验证，审批需待办与结论，文件需实际内容，异步需任务终态，页面需浏览器操作。
+
+\`pnpm verify\` 汇总门禁；\`verify --skip-tests\` 不代表完整通过。诊断用 \`cage doctor\`、\`timeline\`、\`explain\`，具体前提见 \`docs/development/tools/diagnostics.md\`。交付分别说明通过、跳过、未执行及剩余配置；文档和可逆小改动不反复执行全量数据库回归。
 <!-- cage:end -->`;
 /**
  * 将现有文档中的唯一托管区替换为目标版本，返回完整文本而不写文件。

package/dist/sync.js.map

@@ -1 +1 @@
-{"version":3,"file":"sync.js","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,GAAG,EAAmB,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,oDAAoD;AACpD,MAAM,CAAC,MAAM,YAAY,GAAG,oBAAoB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA2HrC,CAAC;AAEnB;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,MAAM,GAAG,YAAY;IACrE,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,2BAA2B,CAAC,CAAC,CAAC;IAClE,MAAM,IAAI,GAAG,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC,CAAC;IACzD,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM;QAAE,OAAO,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACrE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,KAAM,EAAE,CAAC;QAClF,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAM,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AACxG,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,IAAI,CAAC,GAAe,EAAE,KAAK,GAAG,KAAK;IACjD,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IACnC,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAClE,MAAM,KAAK,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,KAAK,KAAK,MAAM;QAAE,OAAO,EAAE,CAAC;IAChC,IAAI,KAAK;QACP,OAAO;YACL;gBACE,IAAI,EAAE,eAAe;gBACrB,EAAE,EAAE,WAAW;gBACf,MAAM,EAAE,WAAW;gBACnB,GAAG,EAAE,wBAAwB;aAC9B;SACF,CAAC;IACJ,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,aAAa,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC3B,OAAO,EAAE,CAAC;AACZ,CAAC"}
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,GAAG,EAAmB,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,oBAAoB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA2CrC,CAAC;AAEnB;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,MAAM,GAAG,YAAY;IACrE,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,2BAA2B,CAAC,CAAC,CAAC;IAClE,MAAM,IAAI,GAAG,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC,CAAC;IACzD,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM;QAAE,OAAO,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACrE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,KAAM,EAAE,CAAC;QAClF,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAM,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AACxG,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,IAAI,CAAC,GAAe,EAAE,KAAK,GAAG,KAAK;IACjD,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IACnC,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAClE,MAAM,KAAK,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,KAAK,KAAK,MAAM;QAAE,OAAO,EAAE,CAAC;IAChC,IAAI,KAAK;QACP,OAAO;YACL;gBACE,IAAI,EAAE,eAAe;gBACrB,EAAE,EAAE,WAAW;gBACf,MAAM,EAAE,WAAW;gBACnB,GAAG,EAAE,wBAAwB;aAC9B;SACF,CAAC;IACJ,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,aAAa,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC3B,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/graph-ui/app.js

@@ -952,9 +952,10 @@ function renderInspector() {
             ? node.attrs.from.map(stateName).join('、')
             : stateName(String(node.attrs.from)));
         row('目标状态', node.attrs.to ? stateName(String(node.attrs.to)) : '保持当前状态');
+        // 调用身份不等于具体触发来源；只有审批绑定关系才能证明某命令承接审批结论。
         const actors = {
             user: '用户',
-            process: '审批流程',
+            process: '内部流程',
             external: '外部系统',
             job: '定时任务',
             reaction: '事件反应',
@@ -1081,7 +1082,7 @@ function detailValue(key, value) {
     return ['kind', 'sensitive'].includes(key) ? (types[String(value)] ?? String(value)) : String(value);
 }
 /**
- * 将约束中文解释委托共享业务规则，保证技术详情和业务地图用同一字段/额度口径。
+ * 将约束中文解释委托共享业务规则，保证技术详情和业务地图使用同一字段口径。
  */
 function constraintLabel(name, aggregateId) {
     return businessConstraintLabel(name, aggregateId, snapshot.presentation.labels);

package/graph-ui/business.js

@@ -258,7 +258,7 @@ export function renderBusiness(host, model, snapshot, actions) {
         host.append(objects, h('p', 'business-scene-description', block.description ||
             (block.processes.length
                 ? '选择完整业务流程，沿主线查看阶段、分支与关联。'
-                : '按业务对象查看完整生命周期；人工、审批与外部通知分别标明。')));
+                : '按业务对象查看完整生命周期；允许的操作及其调用身份分别标明。')));
         if (journeys.length) {
             const grid = h('div', 'business-flow-grid business-journeys');
             for (const journey of journeys) {
@@ -332,8 +332,15 @@ export function renderBusiness(host, model, snapshot, actions) {
         }
         host.append(controls, h('p', 'business-process-legend', '绿色箭头：业务走向　·　棕色箭头：展开的其他分支　·　虚线：涉及的业务对象'));
     }
-    else if (lifecycle)
+    else if (lifecycle) {
         host.append(h('p', 'business-process-legend', '根据真实状态迁移整理，展示允许的操作；具体执行条件请点击查看。'));
+        // 标签缺失只影响阅读，不等于状态不存在；保留原标识，并把补充文案的原因单独说明。
+        // 按真实对象归属统计，避免把其他对象的同名状态算入当前生命周期。
+        const unnamed = model.nodes.filter((node) => node.kind === 'state' && businessOwner(model, node)?.key === flow.key &&
+            !labels[node.key] && !node.attrs.title && !node.attrs.description);
+        if (unnamed.length)
+            host.append(h('p', 'source-note', `${unnamed.length} 个状态尚未配置业务名称，当前显示原始标识。`));
+    }
     const steps = flattenBusinessSteps(root);
     const approvals = new Map(steps.flatMap((step) => {
         const flow = approvalFlowForStep(model, step, labels);
@@ -480,9 +487,10 @@ export function renderBusiness(host, model, snapshot, actions) {
             section('什么时候执行', `${selected.label}${selected.note ? `。${selected.note}` : ''}`);
         if (node.kind === 'command') {
             const rules = section('执行条件');
+            // process 是调用身份，不能仅凭这个值声称操作一定由审批触发。
             const actors = {
                 user: '用户',
-                process: '审批流程',
+                process: '内部流程',
                 external: '外部系统',
                 job: '定时任务',
                 reaction: '自动处理',

package/graph-ui/graph-business.js

@@ -155,19 +155,18 @@ export function businessBlocks(model, labels = {}, showSystem = false) {
         });
     return [...blocks.values()].sort((a, b) => Number(a.system) - Number(b.system) || b.flows.length - a.flows.length || a.id.localeCompare(b.id));
 }
-/** 业务页面缺少文案时明确提示补充，不用程序标识替代业务名称。完整本体仍保留标识。 */
 /**
- * 优先使用中文覆盖与声明文案，缺失时明确显示待命名。
+ * 按显示覆盖、声明标题、描述、原始标识的顺序选择业务阅读名称。
+ * 与完整本体共用名称规则，避免缺少文案时把不同状态或操作变成同一个“待命名”节点；
+ * 不从标识或源码注释猜测业务含义，新建入口仍使用业务阅读专用文案。
  * @param node 展示节点。
- * @param labels 中文标签映射。
- * @returns 阅读标题，不改实际标识。
+ * @param labels 声明文案与 graph.labels 合并后的显示映射。
+ * @returns 阅读标题，不修改节点、实际标识或业务规则，也不执行 IO。
  */
 export function businessLabel(node, labels = {}) {
     if (node.kind === 'entry')
         return '新建业务';
-    if (labels[node.key] || node.attrs.title || node.attrs.description)
-        return nodeLabel(node, labels);
-    return `待命名${{ aggregate: '业务对象', command: '操作', state: '状态', process: '流程', stage: '阶段', event: '业务结果', reaction: '自动处理', approval: '审批', inbound: '外部通知', outbound: '外部同步', query: '查询', job: '定时处理' }[node.kind] ?? '声明'}`;
+    return nodeLabel(node, labels);
 }
 /**
  * 优先返回板块显式流程并保持源码顺序；没有流程规格时返回有状态迁移的对象供生命周期阅读。
@@ -252,8 +251,10 @@ export function traceBusinessLifecycle(model, object, labels) {
         const repeated = seen.has(node.key);
         const action = via[0];
         const actor = (action?.attrs.invokedBy ?? []);
+        // invokedBy 只声明允许的调用身份，process 本身不能证明存在审批绑定。
+        // 生命周期沿状态迁移展示操作；具体审批通过/驳回语义由触发链中的 binds 关系解释。
         const label = action
-            ? `${actor.includes('user') ? '人工' : actor.includes('external') ? '外部通知' : actor.includes('process') ? '审批结论' : '业务操作'} · ${businessLabel(action, labels)}`
+            ? `${actor.includes('user') ? '人工' : actor.includes('external') ? '外部通知' : actor.includes('process') ? '内部流程' : '业务操作'} · ${businessLabel(action, labels)}`
             : '生命周期起点';
         const step = {
             id: repeated ? `${parent}>${node.key}` : node.key,
@@ -365,21 +366,23 @@ export function flattenBusinessSteps(root) {
     return [root, ...root.children.flatMap(flattenBusinessSteps)];
 }
 /**
- * 把命令 from/to 转成中文状态摘要。
+ * 把命令 from/to 转成状态迁移摘要，供操作卡片、流程节点和详情复用。
+ * 优先读取所属聚合的状态显示名，缺失时保留当前命令内可区分的状态标识；
+ * 不从状态标识推测中文含义，也不把多个无标签状态合并成同一占位词。
  * @param node 非命令返回空字符串。
- * @param labels 状态名称覆盖。
- * @returns 允许起始状态与目标，to=null 描述保持当前状态。
+ * @param labels 状态声明标签与 graph.labels 合并后的显示映射。
+ * @returns 允许起始状态与目标，to=null 描述保持当前状态；不修改节点或执行命令。
  */
 export function businessStateSummary(node, labels) {
     if (node.kind !== 'command')
         return '';
     const owner = node.id.slice(0, node.id.lastIndexOf('.'));
-    const name = (s) => (s === 'new' ? '新建' : (labels[`state:${owner}.${s}`] ?? '待命名状态'));
+    const name = (s) => (s === 'new' ? '新建' : (labels[`state:${owner}.${s}`] || s));
     const from = (Array.isArray(node.attrs.from) ? node.attrs.from : [node.attrs.from]);
     return `${from.filter(Boolean).map(name).join(' / ')} → ${node.attrs.to == null ? '保持当前状态' : name(String(node.attrs.to))}`;
 }
 /**
- * 把已知约束名翻译为业务提示，并解析额度与职责分离字段。
+ * 把已知约束名翻译为业务提示，并解析职责分离字段。
  * @param name 内核约束标识。
  * @param owner 所属聚合 ID。
  * @param labels 字段中文标签。
@@ -387,9 +390,6 @@ export function businessStateSummary(node, labels) {
  */
 export function businessConstraintLabel(name, owner, labels) {
     const field = (id) => labels[`field:${owner}.${id}`] ?? id;
-    const ceiling = /^ceiling\((.+)\)$/.exec(name);
-    if (ceiling)
-        return `${field(ceiling[1])}不超过审批额度`;
     const sod = /^sod\.notSameAs\((.+)\)$/.exec(name);
     if (sod)
         return `审批人与${field(sod[1])}不同`;

package/graph-ui/graph-relations.js

@@ -111,11 +111,9 @@ export function explainEdge(edge, model, labels = {}) {
                 return result('映射外发字段', '外部同步数据', `“${a}”的 fields 声明包含“${b}”对应的字段名；抽取器将它关联到发出事件的聚合中同名字段。`, '用于核对外发字段范围和字段变更的同步影响；具体取值及转换由事件载荷与 map 函数决定。', [`${from.id}.fields 包含 ${field}`, `同名聚合字段：${to.id}`]);
             if (as.startsWith('约束 ')) {
                 const rule = as.slice(3);
-                const purpose = rule.startsWith('ceiling(')
-                    ? `用于校验“${b}”是否超出调用人的审批额度。`
-                    : rule.startsWith('sod.notSameAs(')
-                        ? `用于校验调用人与“${b}”记录的人不同，避免同一人完成需要分离的职责。`
-                        : `该约束读取“${b}”执行命令前的业务检查；字段变更时应一起复核约束。`;
+                const purpose = rule.startsWith('sod.notSameAs(')
+                    ? `用于校验调用人与“${b}”记录的人不同，避免同一人完成需要分离的职责。`
+                    : `该约束读取“${b}”执行命令前的业务检查；字段变更时应一起复核约束。`;
                 return result('执行约束检查', '命令校验依赖', `“${a}”声明的约束 ${rule} 使用“${b}”。`, purpose, [
                     `${from.id}.constraints → ${rule}`,
                     `约束 fields 包含 ${field}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yss123/cage-cli",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "cage 命令行：init、gen、check、graph、context、impact、test、verify、budget、sync、upgrade、dev、migrate",
   "type": "module",
   "bin": {
@@ -31,11 +31,11 @@
     "typescript": "~5.9.3",
     "vitest": "^4.1.12",
     "zod": "^4.1.5",
-    "@yss123/cage-ontology": "0.3.1",
-    "@yss123/cage-admin": "0.3.1",
-    "@yss123/cage-lint": "0.3.1",
-    "@yss123/cage-kernel": "0.3.1",
-    "@yss123/cage-testkit": "0.3.1"
+    "@yss123/cage-admin": "0.4.0",
+    "@yss123/cage-kernel": "0.4.0",
+    "@yss123/cage-ontology": "0.4.0",
+    "@yss123/cage-lint": "0.4.0",
+    "@yss123/cage-testkit": "0.4.0"
   },
   "devDependencies": {
     "@types/pg": "^8.15.5"

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

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

package/templates/app/AGENTS.md

@@ -2,7 +2,7 @@
 
 这是 create-cage-app 生成的业务项目，当前包含采购演示，可逐步替换成客户业务。业务源码在本项目，框架通过 @yss123/cage-* 依赖提供。
 
-先读 [业务开发指南](docs/ai/README.md)，按需求查 [任务配方](docs/ai/recipes.md)、[完整采购范例](docs/ai/purchase-example.md) 和 [错误码册](docs/errors/README.md)。这些资料就在项目内，无需克隆框架仓库。
+先读 [业务开发指南](docs/development/README.md)，按需求查 [任务配方](docs/development/guides/recipes.md)、[完整采购范例](docs/development/examples/purchase-example.md) 和 [错误码册](docs/errors/README.md)。这些资料就在项目内，无需克隆框架仓库。
 
 ## 项目自己的业务约定
 
@@ -10,127 +10,47 @@
 
 本节位于托管区之外，cage sync 会保留。下面的托管区提供框架工作方法。
 
-<!-- cage:begin v0.3.1 -->
+<!-- cage:begin v0.4.0 -->
 ## Cage 业务开发约定（框架托管）
 
-### 先读，再按需求改业务
-
-本项目由 create-cage-app 创建。框架来自 `@yss123/cage-*` 依赖，业务写在本项目；不需要克隆框架仓库，也不要复制框架内部实现。
-
-先读项目说明指定的学习资料，默认入口为 `docs/ai/README.md`。第一次读 `architecture.md`、`project-structure.md` 和 `primitives.md`；具体任务读 `recipes.md`，采购全链路读 `purchase-example.md`，错误查 `docs/errors/README.md` 和 `docs/ai/troubleshooting.md`。资料相对该学习目录，项目说明可指定源码仓库中的规范资料位置。
-
-### 详细中文注释（每次开发必须遵守）
-
-所有新增和维护的手写源码都必须写详细中文注释，先读学习目录中的 `commenting.md`（独立项目为 `docs/ai/commenting.md`）。注释是交付内容，不能以“代码自解释”或“保持简洁”为由省略。
-
-- 每个文件开头说明模块职责、谁调用它、主要调用链和责任边界；纯导出入口也说明如何组合模块。
-- 导出函数、类、组件、hooks、接口和业务声明使用 JSDoc，写清用途、参数含义、返回结果、主要步骤、前置条件、失败行为和副作用；复杂内部函数同样说明。参数类型已表达的语法无需重复，业务单位、空值、默认行为与约束必须解释。
-- 领域代码说明字段和状态的业务意义、命令调用身份与权限/范围、reads 依赖、事件用途、事务与异步边界、幂等/重试及资源释放；只写实际声明和实现已有的保证。
-- 页面说明 URL/查询参数、数据来源、临时状态、加载/空态/失败/无权限、提交后的刷新、会话与订阅清理；复杂分支、计算、顺序、并发和缓存规则在附近解释原因与过程。
-- 测试说明场景、前置条件、动作、断言和所防止的回归；脚本说明输入、读写路径、执行顺序、外部副作用与退出条件。注释不含密钥、凭据或个人数据。
-- 注释同时回答“做什么、为什么、如何完成、有哪些边界”，不能只有一句标题，也不能机械逐行翻译、凑字数或批量粘贴空泛模板。代码变更时同步更新注释，交付前逐文件核对。
-- 生成契约的注释由生成器维护，不手改生成物；已执行/已发布迁移不能改写。仅补注释时不得顺便重构或改变逻辑、接口、配置值和运行文案。
-
-### 原生 AI 能力入口
-
-遇到以下需求，先读 `docs/ai/intelligence.md`，用 `pnpm exec cage capabilities "关键词" --format json` 核对当前安装版本的公开 API，再检查本项目 domain 导出和页面接入。关键词可直接使用下表需求名称；未命中时缩短关键词或查公开符号，不能据此断言能力不存在。
-
-| 需求 | 框架入口与应用职责 |
-| --- | --- |
-| AI审批 / 智能审批 | 现有 `step` 使用 `kind: 'ai'`，支持 pass 通过、return 退回修改、manual 转人工；应用声明策略、结论命令、自动执行角色及接管人 |
-| 业务助理 / 本体助理 | 导出 `ai({ models, assistant })`；框架提供执行循环、按领域声明生成的工具、会话、偏好记忆和 HTTP；应用配置授权及界面 |
-| 页面上下文 / 随页助理 | `useAssistant(client.ai, page)` 配合 `useAiPageContext` / `AiPageContext`；应用上报页面、对象、选中项和草稿，服务端重读并校验业务事实 |
-| 模型管理 / Responses | `managedModel` 接入 Admin 动态配置，支持 Chat Completions / Responses；应用配置部署加密密钥并显式授权管理者 |
-| 性格 / 流式输出 | Admin 管理性格，SDK 提供选择、增量文字与执行进度；应用实现悬浮窗、Markdown 和确认卡片 |
-| 上下文预算 | `ai({ context: ... })` 的配置形状见 `AiContextOptions`；框架按预算选择完整工具或发现模式，历史和本体按需读取 |
-
-前端只使用客户端、协议与契约；后端循环、通用工具和记忆使用框架实现。页面快照和性格不授予权限。分别核对**框架支持**（公开导出）、**项目已启用**（domain 导出、迁移、模型、权限、worker、SDK）和**实际验证通过**（真实角色与模型联调）；空白模板的参考代码不表示已启用。具体接入顺序和验收步骤见该指南，不必将整份指南塞入每次任务上下文。
-
-### 业务代码放在哪里
-
-| 位置 | 职责 |
-| --- | --- |
-| `packages/domain/src/modules/<业务>` | 同业务聚合、状态、命令、事件、审批、查询、任务；模块 index.ts 公开导出 |
-| `packages/domain/src/workflows`、`integrations` | 跨模块反应 / 第三方协议与映射；不堆到全局 reactions.ts、queries.ts |
-| `packages/domain/src/index.ts` | 统一导出全部业务及组织模型；没导出的声明不会注册 |
-| `packages/contracts/src/aggregates/<聚合>`、`queries` | 生成协议；根 index.ts 提供 @app/contracts 公共入口，只用 cage gen 更新 |
-| `apps/api/src` | API/worker 薄启动入口，普通业务不手写 HTTP 路由 |
-| `apps/web/src/app` | 会话、URL 路由、布局、模块组合；main.tsx 只挂载和装配 Provider |
-| `apps/web/src/modules/<业务>` | 页面、表单、专用 hooks/API/样式；从模块 index.ts 暴露页面 |
-| `apps/web/src/shared` | 跨模块复用且不绑定业务的 UI、hooks、纯辅助函数 |
-| `db/migrations` | 审查过的结构迁移，作用于已配置的数据库 |
-| `cage.config.json` | 项目路径、检查配置、graph.labels 中文图谱名称 |
-| `.env` | 本机真实连接和密钥；不提交、不输出完整内容 |
-
-新增业务不得继续平铺在 src 根目录。前端模块只依赖自己和 shared，由 app 通过公开入口组合；shared 不反向依赖业务。领域模块间确有读取依赖时走目标模块 index.ts；跨模块反应写 workflows。小模块不创建空层级，已有独立职责再拆文件。完整命名、目录树和示例见 `docs/ai/project-structure.md`。新模板启用 `structure: modular`，check/verify 检查目录和导入边界，遇到 CAGE-STRUCT 错误按职责修正。
-
-### 实现一项需求的顺序
-
-1. 先运行 `pnpm exec cage context "需求关键词"`；按需 `graph search` 查候选、`graph inspect` 查完整节点、`graph path` 看关系路径。确认中文匹配入口后按源码位置阅读实现；候选和子图不是全部依赖，具体条件不能凭连线推断。完整用法见 `docs/ai/ontology-context.md`。从用户需求确定字段、状态/动作、角色/范围、约束与后续动作；能由业务声明表达的不改框架。
-2. 已有业务含义变化时，修改前用 `pnpm exec cage snapshot save before-change` 保存不可覆盖的命名基线；或使用真实 Git 提交/独立本体图文件。
-3. 先声明 aggregate/states/command/constraints/event，再写 handler、reaction/query/approval/connector，最后接业务页面。声明使用模块顶层 `export const`，从 domain 入口导出，跨文件导出名保持唯一。
-4. 运行 `pnpm exec cage check` 和 `pnpm gen`，审查 contracts 和迁移草稿。按需运行 `pnpm exec cage impact --snapshot before-change`，补中文图谱名。
-5. 页面使用生成方法并处理 code/domainCode；列表、详情等多页面注册到 React Router，Link/NavLink 导航，筛选/分页进入 URL。组件状态用于弹窗和表单等临时交互。新增能力由管理员授权。数据库结构变化审查后显式 `pnpm migrate`，dev 不代办迁移。
-6. 按 `commenting.md` 逐文件检查详细中文注释与实现一致，再按改动运行必要验证；交付时说明体验步骤、授权配置、迁移、注释覆盖，以及通过/跳过/未执行项。
-
-### 必守边界
-
-- 聚合定义对象字段、状态、范围字段与不变量；命令是业务写入口。handler 只计算业务变化和读取 reads 中的依赖，不直接操作数据库、网络或文件。
-- 对象关系统一放在 fields：ref 为外键，hasMany 为只读反查，manyToMany 自动生成中间表并随所属对象命令提交。前端用生成的 related 方法分页读取；不手写纯中间表聚合，不把单页结果当完整集合替换。完整例子见 docs/ai/relations.md。
-- command 的 input 使用 Zod；已有记录输入必须含 id。from/to 表达状态迁移；`to: null` 只适用于已有记录并保留状态，不能靠 handler 改 status 绕过状态机。
-- 写入、审计、版本、幂等和事务交给内核；不要在业务项目重建 repository、连接池或权限流水线。
-- 自定义查询声明 reads，二选一使用 sql/build，只读 `safe.*`；值参数化。不得拼接 SQL、查询基表绕过范围或硬编码密钥。
-- scope 描述范围字段，角色数据决定实际范围；`scope.none()` 不代表所有人可访问。`can/useCan` 只控制按钮，后端负责授权。
-- 前端从 `@app/contracts` 导入生成 API/类型，按需使用 `@yss123/cage-client`；不导入 domain、内核或数据库包。
-- 多页面业务必须有独立 URL，不用 useState/tab 模拟整页导航；详情从 URL 取 ID 并独立加载。前端路由集中在 app，页面从模块公开入口接入 Outlet。登录后保留原路径/query/hash，401 回登录，403 展示权限提示；/admin/ 使用普通链接进入独立系统管理。前端路由不替代后端授权。实现、SPA 部署回退和浏览器配方见 docs/ai/routing.md。
-- 跨聚合写入通过 reaction 调用命令。`tx: 'same'` 共同提交/回滚，默认 outbox 异步执行。资源 acquires/releases 是图规则标签，实际占用/释放仍由命令完成；离开持有状态要检查每条释放路径。
-- 批量调用同一命令使用 reactionEach，声明 maxItems、唯一排序字段 orderBy、items 和 map；稳定键排序后串行执行。步骤依赖用 order，同事件同事务分组不得混用有序/无序或重复顺序。保持同事务回滚边界，见 docs/ai/primitives.md。
-- 审批通过 approval + route 配置，结论是 process 命令；选中审批人不等于已具备能力、范围和额度。parallel(title, ...branch(...)) 声明结构化 AND：分支同时开始，内部顺序独立，全部活动分支完成后汇合；when 支持嵌套并仍按提交快照求值，声明有深度/数量边界，不支持任意跳转。currentSteps 表示当前活动节点集合，兼容字段 currentStep 只是最小活动索引，不能据此隐藏其他分支。人工节点 assignment: 'candidate' 开放候选领取/释放，approver.field 从 routable 字段选人；actions 开放转办、委派归还和前后/并行必签。任务操作与决定携带 revision，waiting 任务只能查看。approvalOperations() 为框架通用时效运行时：step.sla 配置自然分钟节点总时限，route.reminders 配置申请人催办；迁移并运行 worker 后提供持久站内提醒、已读与 Admin 通用页面，不自动批准或授予权限。政策、SDK 和边界见 docs/ai/approvals.md。第三方 IO 通过连接器，回调验签后调用 external 命令。
-- job 的读取与调用必须列入 reads/calls。业务导入/导出放在需要的业务页面调用通用任务接口，202 只代表任务已接受；worker 必须运行。
-- 已部署事件只做兼容扩展；新增字段设为 optional，不兼容含义用新事件。已执行/已发布迁移不能改写，结构更新新增迁移。
-- 不手改生成物，不关闭门禁掩盖错误，不因方便自动授予生产角色新能力。unsafe 必须写明 reason/owner，不能替代普通业务声明。
-- 按前述详细中文注释规范完成文件、API、业务声明和关键流程说明；避免无业务价值的防御分支和静默兜底。维护脚本用 TypeScript，不新增 .mjs。
-
-### 最小命令形状
-
-```ts
-// 片段：Order 为已导出的聚合，OrderSubmitted 为事件，业务校验按需求添加。
-/**
- * 将草稿订单提交审批：只有 draft 可进入 pending_approval。
- * 入口使用 Order.submit 能力，真实授权、范围、状态和版本由内核检查；声明本身不自动授予权限。
- * handler 返回草稿供后续校验和持久化，OrderSubmitted 随命令事务登记，后续由已配置消费者处理。
- * 失败不会提交这次业务变更；事件已登记也不代表后续审批已经完成。
- */
-export const submitOrder = command(Order, {
-  name: 'submit',
-  from: 'draft',
-  to: 'pending_approval',
-  emits: [OrderSubmitted],
-  handler: (draft) => draft,
-});
-```
-
-完整可添加的普通管理对象见 `docs/ai/primitives.md` 的 Note；采购模板的审批、资源、第三方示例在 `packages/domain/src`，空白模板的参考源码在 `docs/examples/purchase-admin`。先读本项目 AGENTS.md 中的模板说明，区分运行代码与参考资料。API 以当前包公开导出和生成契约为准，不发明不存在的配置和方法。
-
-### 启动、验证与排错
-
-在项目根目录执行：首次 `pnpm install`，复制并编辑 .env.example，仅提供已有库管理员连接后 `pnpm exec cage init`；再 `pnpm build:app`、`pnpm gen`，审查后 `pnpm migrate`；用 `pnpm exec cage bootstrap --credentials-file .cage/admin-credentials.json` 显式初始化组织，最后 `pnpm dev`。已有配置不能覆盖，凭据文件必须是新受限文件且父目录存在。
-
-init 只准备账号/schema/授权并填写三个连接，不创建数据库；APP/READ/MIGRATE 指向同一个库。已有集群账号复用原密码，日常启动不用管理员。普通项目不新增 Docker 生命周期命令。
-
-API 日常启动不初始化组织、不输出管理员密码；生产缺少合格 Cookie 密钥会拒绝启动。bootstrap 不自动授予业务能力。`/healthz` 只表示存活，`/readyz` 检查必要依赖。首阶段 API 与 worker 同版本部署，查看实际注册指纹和消费者心跳。
-
-- `pnpm exec cage graph`：浏览器图谱，默认端口 15418，以终端为准。
-- `pnpm exec cage context command:对象.命令 --format json --out .cage/context.json`：按完整 key 取精简上下文；默认 Markdown，可用 --depth/--limit 调整范围。CLI 每次重新抽取；Web“复制 AI 上下文”使用当前页面快照，改代码后先刷新图谱。
-- `graph inspect/path` 有歧义时复制候选完整 key；path 默认沿箭头，--direction both 的逆向遍历不表示执行方向。报告中的测试/前端文件是候选，须核对；context 与图谱查询不覆盖当前图或命名快照。
-- `pnpm exec cage capabilities 关键词 --format json`：查当前安装版本公开签名；`cage doctor`：区分注册、生成、构建、迁移、授权与实际进程证据，unknown 不能当作通过。`cage timeline/explain` 关联实际异步证据与解释授权，参数和权限见 docs/ai/diagnostics.md。
-- 生成方法支持 signal/timeoutMs/idempotencyKey 请求选项。底层 CageResult 与 mutation 行为有区别：useCageCommand 失败抛 CageCommandError，成功才返回业务数据。订阅 client.subscribe 在退出、401、切换账号时取消查询并清除应用缓存。
-- `pnpm exec cage gen --check`：生成一致性；`pnpm exec cage sync --check`：本托管区一致性。
-- `pnpm exec cage test --only project`：业务测试；`pnpm verify`：类型、依赖、lint、图规则、生成、托管区、预算和测试。
-- `pnpm exec cage verify --skip-tests` 表示不完整门禁；派生测试跳过不能当作通过。测试连接只用独立测试集群。
-- 重要业务改动验证成功路径及有风险的反例；文档或可逆的小改动不反复跑全量数据库测试。
-- 修改页面/导航后实际验收深链接、刷新、前进后退、登录回跳、无权限和 404；生产再查 SPA 回退。check/verify 不自动完成浏览器验收，未执行要明确报告。见 docs/ai/routing.md。
-- CLI 报错先看 code/at/reason/fix，再查错误码册；HTTP 错误查 runtime.md。异步失败先看 worker、同步记录和死信，修复后重放，不能直接 SQL 改状态。
-
-框架托管区由 cage sync 更新；项目独有的业务规则写在标记之外，避免升级覆盖。
+### 学习与任务入口
+
+本项目使用 `@yss123/cage-*`，业务写在本项目。先读项目说明指定的教材；独立项目默认入口是 `docs/development/README.md`。
+
+开始 Cage 业务开发或排错时，加载 `docs/development/skills/cage-development/SKILL.md`，统一按“理解需求 → 澄清 → 查证能力 → 说明实现映射 → 编码 → 验收”工作。首次学习配合 `docs/development/getting-started/first-feature.md`；已熟悉时只读受影响专题，普通样式/文案改动无需重走业务建模。
+
+支持 Agent Skills 的工具可发现 `.agents/skills/cage-development`；其他工具直接读取上述 Markdown，使用相同流程。教材随框架版本分发，均为本地文件，不需要额外服务、模型或索引。框架仓库范例使用项目说明指定的规范教材位置。
+
+### 框架执行什么
+
+- 业务声明从 domain 总入口导出，框架据此构建注册表、能力、HTTP 接口、本体图、契约与迁移草稿；只有文件而未导出不会生效。
+- 命令是业务写入口；handler 描述变化与显式 reads，内核处理授权、状态、范围、版本、事务、审计及 outbox。读侧通过生成契约或 query 的安全视图，外部 IO 通过连接器。
+- 角色、能力、数据范围、调用身份与业务约束分别建模。前端 can() 只影响显示，新增能力不自动授给生产角色；审批选人不授予能力。
+- 页面依赖生成契约及客户端。表单、弹窗等临时状态留在前端；正式业务数据和流程结果通过服务端读写。实际记录不能用模拟仓储或固定统计替代。
+
+### 编码前的依据
+
+业务疑点按 `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 按需引导，不重建框架已有运行时。
+
+### 代码与环境边界
+
+- 所有手写代码遵守 `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 证明各自检查范围；业务读写还需独立读取结果，权限需直接请求验证，审批需待办与结论，文件需实际内容，异步需任务终态，页面需浏览器操作。
+
+`pnpm verify` 汇总门禁；`verify --skip-tests` 不代表完整通过。诊断用 `cage doctor`、`timeline`、`explain`，具体前提见 `docs/development/tools/diagnostics.md`。交付分别说明通过、跳过、未执行及剩余配置；文档和可逆小改动不反复执行全量数据库回归。
 <!-- cage:end -->