@yss123/cage-cli 0.1.0 → 0.3.0

package/graph-ui/relations.js

@@ -1,125 +1,6 @@
-import { kinds, nodeLabel } from './model.js';
-export function explainEdge(edge, model, labels = {}) {
-    const from = model.nodes.find((n) => n.key === edge.from);
-    const to = model.nodes.find((n) => n.key === edge.to);
-    const a = nodeLabel(from, labels), b = nodeLabel(to, labels);
-    const field = to.id.slice(to.id.indexOf('.') + 1);
-    const resource = (id) => labels[`resource:${id}`] ?? id;
-    const result = (label, category, why, purpose, evidence, source = from) => ({
-        label,
-        category,
-        why,
-        purpose,
-        evidence,
-        source,
-        direction: `“${a}” → “${b}”：${label}。`,
-    });
-    switch (edge.kind) {
-        case 'field':
-            return result('包含字段', '数据结构', `“${a}”的字段声明中包含“${b}”。`, '说明业务对象由哪些数据组成；调整字段时，可以继续沿线查看受影响的查询、审批和事件。', [`${from.id}.fields.${field}`]);
-        case 'refs':
-            return result('引用对象', '数据关联', `“${a}”声明为引用“${b}”的字段，保存所关联对象的标识。`, `用于理解这条数据关联到哪个${kinds[to.kind].label}。例如部门字段关联部门对象；具体查询仍受数据范围约束。这条线本身不执行查询。`, [`${from.id}: ref(${JSON.stringify(to.id)})`]);
-        case 'ownership':
-            return result(`拥有${kinds[to.kind].label}`, '视图归属 · 虚线', `“${b}”的标识位于“${from.id}.”之下，页面据此将它归入“${a}”。`, '帮助整理同一业务对象的命令、状态和能力点。这是页面推导的归属，不是抽取器声明的依赖，也不会触发命令。', [`${to.id} → 所属聚合 ${from.id}`]);
-        case 'transition': {
-            const command = model.nodes.find((n) => n.kind === 'command' && n.id === edge.via);
-            const name = nodeLabel(command, labels);
-            const stays = edge.from === edge.to;
-            return result(stays ? '保持状态' : '迁移状态', '状态变化', `“${name}”声明${stays ? `在“${a}”状态执行后保持原状态` : `从“${a}”进入“${b}”`}。`, `用于检查业务生命周期是否完整。只有命令通过权限、约束并成功提交，${stays ? '操作才生效' : '状态才改变'}。`, [
-                `命令：${command.id}`,
-                `from: ${JSON.stringify(command.attrs.from)}`,
-                `to: ${JSON.stringify(command.attrs.to)}`,
-            ], command);
-        }
-        case 'reads':
-        case 'queries':
-            return result('读取数据', '读取依赖', `“${a}”在 reads 中声明读取“${b}”${edge.alias ? `，使用别名 ${edge.alias}` : ''}。`, '明确可读取的业务对象，并让影响分析找到依赖方；实际读取通过安全视图，受权限和数据范围约束。箭头指向数据来源，不表示先执行它。', [`${from.id}.reads${edge.alias ? `.${edge.alias}` : ''} → ${to.id}`]);
-        case 'emits':
-            return result('产生事件', '事件协作', `“${a}”的 emits 中声明了“${b}”事件。`, '命令成功执行时按声明生成事件，连接后续反应、审批或外部同步；事务失败时不能当作已经发生。', [`${from.id}.emits → ${to.id}`]);
-        case 'uses': {
-            const as = edge.as ?? '';
-            if (as === '可路由字段')
-                return result('允许审批读取', '审批可用字段', `“${a}”把“${b}”列入 routable，允许该字段作为审批流程变量。`, '明确审批可以拿到哪些业务数据。这里只表示允许使用；是否真的参与分支或审批选人，要查看审批路由的字段关系。', [`${from.id}.routable 包含 ${field}`]);
-            if (as === '路由条件') {
-                // fieldsUsed 同时包含 when 条件和 deptLeader 选人字段，不能一律解释成条件判断。
-                const nodes = from.attrs.nodes;
-                const conditions = nodes.filter((n) => n.kind === 'when' && n.cond.field === field);
-                const steps = nodes
-                    .flatMap((n) => (n.kind === 'step' ? [n] : n.steps))
-                    .filter((s) => s.approver.kind === 'deptLeader' && s.approver.field === field);
-                const operators = {
-                    gt: '大于',
-                    gte: '大于等于',
-                    lt: '小于',
-                    lte: '小于等于',
-                    eq: '等于',
-                    ne: '不等于',
-                    in: '属于',
-                };
-                const reasons = [
-                    ...steps.map((s) => `“${s.title}”步骤根据“${b}”找到对应部门的负责人`),
-                    ...conditions.map((n) => `当“${b}”${operators[n.cond.op]} ${JSON.stringify(n.cond.value)} 时，加入${n.steps.map((s) => `“${s.title}”`).join('、')}步骤`),
-                ];
-                return result(steps.length && conditions.length ? '选人和分支依据' : steps.length ? '确定审批人' : '判断审批分支', '审批路由依赖', `${reasons.join('；')}。`, '字段值会影响审批人或需要经过的审批步骤；修改字段含义时，应一起检查这些路由配置。', [
-                    ...steps.map((s) => `${s.title}: approver.deptLeader(${JSON.stringify(field)})`),
-                    ...conditions.map((n) => `when(${n.cond.op}(${JSON.stringify(field)}, ${JSON.stringify(n.cond.value)}))`),
-                ]);
-            }
-            if (as === '事件载荷')
-                return result('携带字段', '事件数据依赖', `“${a}”的默认事件载荷按同名字段从业务对象取“${b}”。`, '订阅方可以用事件中的这份数据处理后续业务；字段变更需要检查事件及订阅方的数据约定。箭头指向载荷的数据来源。', [`事件 ${from.id} 的同名字段 ${field} ← ${to.id}`]);
-            if (as === '查询')
-                return result('查询使用字段', '查询字段线索', `抽取器在“${a}”的 SQL 或查询构造函数文本中匹配到了“${b}”的字段名。`, '提供检查查询依赖的线索。这里基于字段名文本匹配，可能匹配到注释或同名内容；实际筛选、分组或计算用途请核对查询声明。', [`${from.id}: SQL / build 文本匹配 ${field}`]);
-            if (as === '出站映射')
-                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}”执行命令前的业务检查；字段变更时应一起复核约束。`;
-                return result('执行约束检查', '命令校验依赖', `“${a}”声明的约束 ${rule} 使用“${b}”。`, purpose, [
-                    `${from.id}.constraints → ${rule}`,
-                    `约束 fields 包含 ${field}`,
-                ]);
-            }
-            return result('使用字段', '字段依赖', `“${a}”声明使用“${b}”。`, '用于追踪字段变更的影响范围。', [
-                as || edge.kind,
-            ]);
-        }
-        case 'triggers': {
-            const label = to.kind === 'approval' ? '启动审批' : to.kind === 'outbound' ? '触发外部同步' : '触发反应';
-            return result(label, '事件触发', `“${b}”订阅“${a}”作为${to.kind === 'approval' ? '启动' : '触发'}事件。`, to.kind === 'approval'
-                ? '事件发生后启动对应审批流程，生成流程中的审批任务。'
-                : to.kind === 'outbound'
-                    ? '事件发生后由 worker 处理外部推送，失败按投递策略重试。'
-                    : `事件发生后执行订阅的反应${to.attrs.tx === 'same' ? '，该反应与原命令处于同一事务' : '；执行方式由反应的事务声明决定'}。`, [`${to.id}.${to.kind === 'approval' ? 'start' : 'event'} → ${from.id}`], to);
-        }
-        case 'targets': {
-            if (to.kind === 'connector')
-                return result('调用外部系统', '连接器调用', `“${a}”声明通过“${b}”执行操作 ${labels[`operation:${from.attrs.operation}`] ?? from.attrs.operation}。`, '由连接器统一处理地址与字段白名单、密钥、限流和超时，让外部同步保持可管控。', [`${from.id}.connector → ${to.id}`, `operation: ${from.attrs.operation}`]);
-            if (from.kind === 'outbound')
-                return result('成功后回写', '同步成功回调', `“${a}”的 onSuccess 绑定“${b}”。`, '外部操作成功后调用该命令，将返回结果按映射写回业务；失败时不执行成功回写。', [`${from.id}.onSuccess → ${to.id}`]);
-            if (from.kind === 'inbound')
-                return result('回调转为命令', '外部回调', `“${a}”将接收的外部回调映射到“${b}”。`, '外部回调通过验签和数据校验后，使用业务命令处理，统一遵守状态和业务约束。', [`${from.id}.command → ${to.id}`]);
-            const resources = [
-                edge.acquires ? `获取“${resource(edge.acquires)}”` : '',
-                edge.releases ? `释放“${resource(edge.releases)}”` : '',
-            ].filter(Boolean);
-            return result('调用业务命令', '反应调用', `“${a}”把事件映射后交给“${b}”处理。`, `将后续业务操作交给受约束的命令执行。${resources.length ? `此声明还标记${resources.join('、')}，用于检查资源获取与释放是否成对。` : ''}`, [`${from.id}.command → ${to.id}`, ...resources]);
-        }
-        case 'binds': {
-            if (from.kind === 'route')
-                return result('定义审批步骤', '流程配置', `“${a}”与“${b}”使用同一流程标识 ${from.attrs.process}。`, '这份路由定义流程里的审批步骤、选人方式和条件分支，供代码内审批引擎使用。', [`process: ${from.attrs.process}`]);
-            const approved = from.attrs.onApproved === to.id;
-            const rejected = from.attrs.onRejected === to.id;
-            const outcome = approved && rejected ? '结束' : approved ? '通过' : '驳回';
-            return result(`${outcome}后执行`, '审批结论回写', `“${a}”${outcome}时绑定执行“${b}”。`, '将审批结论交给业务命令推进单据状态，并统一执行权限和业务约束。', [
-                approved ? `${from.id}.onApproved → ${to.id}` : '',
-                rejected ? `${from.id}.onRejected → ${to.id}` : '',
-            ].filter(Boolean));
-        }
-        case 'calls':
-            return result('允许调用命令', '任务调用范围', `“${a}”在 calls 中声明可以调用“${b}”。`, '明确任务能执行哪些业务写入，并支持影响分析。每次任务是否实际调用该命令，取决于 run 中的业务逻辑。', [`${from.id}.calls → ${to.id}`]);
-    }
-}
+/**
+ * 浏览器关系解释的转导出入口，与 CLI 使用同一份 src/graph-relations 规则。
+ * 这里只暴露可浏览器执行的纯解释逻辑，不加载数据库、审批引擎或 Node 文件访问模块。
+ */
+// Web 与 AI 上下文共用关系解释，保持证据和业务含义一致。
+export { explainEdge } from './graph-relations.js';

package/graph-ui/structure.js

@@ -1,10 +1,28 @@
+/**
+ * 字段卡片固定宽度，单位为画布单位；布局与引用线共享该值。
+ */
 export const TABLE_WIDTH = 336;
+/**
+ * 字段卡片标题区高度，引用目标连接到其中心。
+ */
 export const TABLE_HEADER = 58;
+/**
+ * 单字段行高度，字段引用起点用此值定位行中心。
+ */
 export const TABLE_ROW = 38;
+/**
+ * 字段卡片尾部留白高度，与动态字段数一起确定总高。
+ */
 export const TABLE_FOOTER = 34;
 /** 对象卡片展示声明字段，而不是猜测完整数据库结构。系统自动添加的列不在
- * 抽取结果中，因此这里不补造 id、主键、外键约束或一对多基数。
+ * 抽取结果中，因此这里不补造 id 或主键。集合关系也留在 fields 中展示，
+ * 用类型和虚拟关系标记区分物理列，基数来自抽取器明确记录的声明。
  * 字段仍保留原节点身份，搜索、点击和关系解释都能回到同一份声明。 */
+/**
+ * 沿 field 边收集聚合声明字段并计算卡片高度，不补造系统列。
+ * @param model 展示图。
+ * @returns 所有聚合卡片，虚拟关系仍作为声明字段展示。
+ */
 export function tableCards(model) {
     return model.nodes
         .filter((n) => n.kind === 'aggregate')
@@ -15,11 +33,24 @@ export function tableCards(model) {
     });
 }
 /** 用真实字段归属解析端点；不能把两个同名字段合并，也不能把命令算成列。 */
+/**
+ * 通过完整 key 找到聚合或字段所属卡片。
+ * @param cards 卡片列表。
+ * @param key 聚合或字段身份。
+ * @returns 匹配卡片或 undefined，命令不会被当字段。
+ */
 export function tableOwner(cards, key) {
     return cards.find((card) => card.node.key === key || card.fields.some((field) => field.key === key));
 }
 /** 关联较多的对象优先放置，再按实际卡片高度分配到最短列。
  * 两列上限保持字段字可读；卡片高度由字段数决定，避免固定网格裁掉长表。 */
+/**
+ * 优先放置关系多且较高的卡片，再将每张卡放入当前最短列。
+ * @param cards 卡片数组，不修改。
+ * @param edges 引用关系，用于连接度排序。
+ * @param columns 调用方按可用宽度给出的列数。
+ * @returns 卡片坐标映射，未连接数据库或保存布局。
+ */
 export function layoutTables(cards, edges, columns) {
     const positions = new Map();
     const heights = Array.from({ length: Math.min(columns, cards.length) }, () => 0);
@@ -34,6 +65,13 @@ export function layoutTables(cards, edges, columns) {
 }
 /** 引用线从具体字段行连接到目标对象表头。端点随卡片拖动一起计算，
  * 不把整张卡片的中心当成字段位置；同列时从侧边绕开表体。 */
+/**
+ * 从具体字段行中心连接到目标卡片表头，随拖动位置实时计算。
+ * @param edge 已确认有效的字段引用边。
+ * @param cards 可见卡片。
+ * @param positions 卡片坐标。
+ * @returns SVG 曲线路径，同列侧绕避免穿过表体。
+ */
 export function tableEdgePath(edge, cards, positions) {
     const source = tableOwner(cards, edge.from);
     const target = tableOwner(cards, edge.to);
@@ -53,6 +91,11 @@ export function tableEdgePath(edge, cards, positions) {
     const bend = Math.max(65, Math.abs(x2 - x1) / 2) * (forward ? 1 : -1);
     return `M${x1},${y1} C${x1 + bend},${y1} ${x2 - bend},${y2} ${x2},${y2}`;
 }
+/**
+ * 将已抽取字段 kind 显示为中文类型。
+ * @param field 字段节点。
+ * @returns 已知中文类型或原 kind，不推断数据库实际类型。
+ */
 export function fieldType(field) {
     const types = {
         text: '文本',
@@ -64,6 +107,10 @@ export function fieldType(field) {
         boolean: '布尔',
         id: '标识',
         ref: '引用',
+        hasMany: '一对多',
+        manyToMany: '多对多',
+        file: '文件',
+        files: '多文件',
         list: '列表',
         json: 'JSON',
         date: '日期',

package/graph-ui/style.css

@@ -1,5 +1,7 @@
 /* 图谱工作台使用低饱和的纸面色与矿物绿。节点颜色承担类型区分，装饰保持克制，
    让长名称、连线和选中状态始终是画面的第一层信息。 */
+/* 本体工作台的基础外观与完整图/对象字段视图样式，由 index.html 先加载。
+ * 主题变量、布局和 SVG 状态与 app.ts/model.ts/structure.ts 约定配合；业务流程专属覆盖放在后续 business.css。 */
 :root {
   font-family: 'Bahnschrift', 'Microsoft YaHei UI', 'PingFang SC', sans-serif;
   color: #283d37;
@@ -56,6 +58,7 @@ a {
 [hidden] {
   display: none !important;
 }
+/* 顶部、侧栏与主体的共享页面骨架；侧栏宽度由断点覆盖，主体必须允许内部画布收缩。 */
 .app-shell {
   min-height: 100vh;
   display: grid;
@@ -209,6 +212,7 @@ a {
   color: #225d49;
   text-decoration: underline;
 }
+/* 业务对象导航与类型筛选使用同一选择状态；active 表示当前筛选，不代表服务端授权。 */
 .aggregate-list {
   display: grid;
   gap: 3px;
@@ -490,6 +494,7 @@ h1 {
   font-size: 12px;
   white-space: pre-wrap;
 }
+/* 完整图的画布和解释栏并排组成探索区；窄屏断点将解释栏移到画布下方。 */
 .explorer {
   display: grid;
   grid-template-columns: minmax(0, 1fr) 267px;
@@ -569,6 +574,7 @@ h1 {
   padding: 1px 4px;
   color: #a6afa0;
 }
+/* 检索结果浮在工具条下方，不参与画布几何；长名称截断仅影响显示，节点身份由数据保持。 */
 .search-results {
   position: absolute;
   z-index: 10;
@@ -643,6 +649,7 @@ h1 {
   color: #a8b19f;
   white-space: nowrap;
 }
+/* SVG 画布自身裁剪平移内容；缩放、拖动和节点位置由脚本更新 transform，本层只提供容器与光标。 */
 .canvas {
   flex: 1;
   min-height: 0;
@@ -738,6 +745,7 @@ h1 {
   border-top-style: dashed;
   margin-left: 7px;
 }
+/* 边与节点的可读状态：派生关系、邻域高亮、选中和淡出分开表达，颜色不改变关系语义。 */
 .edge {
   fill: none;
   stroke: #aebdb0;
@@ -847,6 +855,7 @@ h1 {
     transform: rotate(360deg);
   }
 }
+/* 解释栏承载节点、关系和证据，长内容独立滚动；来源位置与原始 JSON 不参与图谱布局。 */
 .inspector {
   border-left: 1px solid #e5eadd;
   background: #fff;
@@ -904,6 +913,27 @@ h1 {
   font-size: 10px;
   padding: 8px 9px;
 }
+/* 交给 AI 的入口沿用纸面绿，以独立阅读块说明包含什么，避免挤进节点操作行。 */
+.context-handoff {
+  padding: 12px;
+  margin: 0 0 20px;
+  background: #f1f6ed;
+  border: 1px solid #dde7d5;
+  border-radius: 7px;
+}
+.context-handoff .button {
+  width: 100%;
+  font-size: 11px;
+  color: #365f45;
+  border-color: #ceddc3;
+  background: #fbfdf8;
+}
+.context-handoff p {
+  margin: 9px 0 0;
+  font-size: 10px;
+  line-height: 1.8;
+  color: #7b8d72;
+}
 .detail-section {
   border-top: 1px solid #edf0e7;
   padding-top: 16px;
@@ -1051,6 +1081,7 @@ dialog::backdrop {
   background: #263c2d44;
   backdrop-filter: blur(3px);
 }
+/* 检查结果使用原生 dialog 的内容布局，打开关闭和 findings 列表由 app.ts 管理。 */
 .dialog-heading {
   display: flex;
   align-items: center;
@@ -1100,6 +1131,7 @@ dialog::backdrop {
     margin-bottom: 29px;
   }
 }
+/* 中等宽度逐步压缩边距和工具条，保留交互控件；更窄断点再切换单列布局。 */
 @media (max-width: 1200px) {
   :root {
     --sidebar: 186px;
@@ -1557,6 +1589,7 @@ dialog::backdrop {
 .table-card.selected .table-shadow {
   opacity: 1;
 }
+/* 对象字段视图的 SVG 卡片。表头拖动整卡，字段行提供独立命中与选择，字体大小与 structure.ts 测量约定配合。 */
 .table-body {
   fill: #fafcf6;
   stroke: #d7e2cc;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@yss123/cage-cli",
-  "version": "0.1.0",
-  "description": "cage 命令行：gen、check、impact、test、verify、budget、sync、upgrade、dev、migrate",
+  "version": "0.3.0",
+  "description": "cage 命令行：init、gen、check、graph、context、impact、test、verify、budget、sync、upgrade、dev、migrate",
   "type": "module",
   "bin": {
     "cage": "./bin/cage.js",
@@ -19,10 +19,10 @@
     "dist",
     "bin",
     "graph-ui",
-    "templates",
-    "managed"
+    "templates"
   ],
   "dependencies": {
+    "@clack/prompts": "^1.8.1",
     "dependency-cruiser": "^17.0.1",
     "eslint": "^9.35.0",
     "pg": "^8.16.3",
@@ -31,9 +31,11 @@
     "typescript": "~5.9.3",
     "vitest": "^4.1.12",
     "zod": "^4.1.5",
-    "@yss123/cage-testkit": "0.1.0",
-    "@yss123/cage-kernel": "0.1.0",
-    "@yss123/cage-lint": "0.1.0"
+    "@yss123/cage-ontology": "0.3.0",
+    "@yss123/cage-admin": "0.3.0",
+    "@yss123/cage-kernel": "0.3.0",
+    "@yss123/cage-lint": "0.3.0",
+    "@yss123/cage-testkit": "0.3.0"
   },
   "devDependencies": {
     "@types/pg": "^8.15.5"
@@ -56,7 +58,7 @@
     "node": ">=24"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json && tsc -p ui/tsconfig.json && node scripts/build-graph.mjs && node scripts/copy-assets.mjs",
+    "build": "node scripts/clean-dist.ts && tsc -p tsconfig.json && tsc -p ui/tsconfig.json && node scripts/build-graph.ts && node scripts/copy-assets.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p ui/tsconfig.json",
     "test": "vitest run"
   }

package/templates/app/.dockerignore

@@ -4,6 +4,8 @@ node_modules
 .git
 .cage
 **/.cage
+.cage-files
+**/.cage-files
 generated
 .env
 .env.*

package/templates/app/.env.example

@@ -1,17 +1,71 @@
-# 推荐运行 pnpm db:setup 自动生成 .env 和随机密码；不要直接使用占位符连接。
-CAGE_POSTGRES_PORT=54329
-CAGE_TEST_POSTGRES_PORT=54330
-POSTGRES_PASSWORD=<开发集群超级用户密码>
-CAGE_TEST_POSTGRES_PASSWORD=<测试集群独立密码>
-CAGE_SUPER_DATABASE_URL=postgresql://postgres:<开发集群超级用户密码>@127.0.0.1:54329/postgres
-CAGE_APP_DATABASE_URL=postgresql://cage_app:<业务写入密码>@127.0.0.1:54329/cage_dev
-CAGE_READ_DATABASE_URL=postgresql://cage_read:<只读密码>@127.0.0.1:54329/cage_dev
-CAGE_MIGRATE_DATABASE_URL=postgresql://cage_migrate:<迁移密码>@127.0.0.1:54329/cage_dev
-# 只允许指向可丢弃的独立测试集群。
-CAGE_TEST_DATABASE_URL=postgresql://postgres:<测试集群独立密码>@127.0.0.1:54330/postgres
-CAGE_COOKIE_SECRET=<随机会话签名密钥>
+# Cage 业务项目配置：复制此文件为同目录的 .env，首次只填写管理员数据库连接。
+# .env 位于业务项目根目录，与 package.json、cage.config.json 同级。
+# pnpm exec cage init / pnpm dev / pnpm migrate 自动读取它；同名外部环境变量优先。
+# 修改后重启 dev；migrate 在下次执行时读取新值。不要把 .env 提交到 Git。
+# 数据库需已经存在并能连接；框架不安装 PostgreSQL、不创建数据库、不管理 Docker。
+
+# ===== 第一步：提供已有数据库的管理员连接，执行 pnpm exec cage init =====
+# 格式：postgresql://用户名:密码@主机:端口/数据库名
+# 将 127.0.0.1、5432、business_db 换成实际地址、端口和已有数据库名。
+# 密码中的特殊字符必须 URL 编码，例如 @ 写成 %40、# 写成 %23、% 写成 %25。
+# [首次初始化必填] 管理员通常叫 postgres；若你的管理员叫 root，使用实际账号名。
+# 管理员需要创建角色、schema 和授权的权限。连接的数据库必须已经存在。
+# 将下面的管理员密码、主机、端口和库名改为实际值，再执行 pnpm exec cage init。
+# init 会创建框架账号、生成独立随机密码和 Cookie 密钥，并自动填好下面的配置。
+# 成功后管理员连接会从 .env 移除；日常开发不用再提供管理员密码。
+CAGE_ADMIN_DATABASE_URL=postgresql://postgres:REPLACE_WITH_ADMIN_PASSWORD@127.0.0.1:5432/business_db
+
+# ===== 第二步：以下配置由 init 自动填充，无需手动创建账号或编写授权 SQL =====
+# 三个连接使用同一个数据库，主机、端口、库名一致，账号权限不同。
+# 重复 init 会验证并复用已保存的账号，不重置密码。
+# 若集群已有 Cage 账号且本项目未保存连接，需复用原凭证，不能仅凭管理员重置其他项目的密码。
+
+# [必填] 业务写入账号 cage_app：API 和 worker 执行命令、审计和后台任务使用。
+# 它有业务所需读写权限，不应使用 postgres 超级用户替代。
+# CAGE_APP_DATABASE_URL=
+
+# [必填] 安全查询账号 cage_read：仅通过安全视图读取，经数据范围过滤和敏感字段掩码。
+# 不要与写入账号混用，否则会破坏读写权限隔离。
+# CAGE_READ_DATABASE_URL=
+
+# [执行迁移时必填] 迁移账号 cage_migrate：pnpm migrate 用它更新表、索引、视图和权限。
+# 它连接上述同一个数据库；迁移只在手动执行命令时发生，dev 不自动执行迁移。
+# 生产环境只给迁移任务配置此项，API / worker 无需获得此账号。
+# CAGE_MIGRATE_DATABASE_URL=
+
+# ===== 应用配置 =====
+# [init 自动生成] Cookie 签名密钥，不是数据库密码，也不是网页登录密码。
+# 自动生成 32 字节随机值；已有值保留。同一应用的多个实例使用同一值。
+# CAGE_COOKIE_SECRET=
+
+# 生产 NODE_ENV=production 时必须提供合格随机密钥；固定开发值会被拒绝。
+# 组织在审查执行 migrate 后，显式 cage bootstrap --credentials-file <新的受限文件>。
+# API 日常启动不会初始化组织或向日志输出管理员密码。
+# 可信代理在 apps/api/src/main.ts 显式配置地址/网段；默认 trustProxy: false。
+# /healthz 表示存活，/readyz 检查数据库和授权监听；API 与 worker 使用同版本部署。
+
+# [可选，开发默认 fake] 第三方连接器阶段：fake 使用模拟实现；test / prod 使用真实适配器。
+# 本项只影响第三方外部服务，fake 阶段仍连接真实 PostgreSQL。
+# test / prod 需另行配置业务连接器要求的地址与密钥，不是修改此值就完成对接。
 CAGE_STAGE=fake
-# 5173 被 Windows 保留时，可改成 15173。端口不会自动漂移，避免访问到错误的服务。
-CAGE_WEB_PORT=5173
+
+# [可选，Vite 默认 5173] 本地 Web 页面端口。这里选 15173，减少 Windows 保留端口冲突。
+# 多个应用同时运行时，各选一个空闲端口；它与数据库端口无关。
+CAGE_WEB_PORT=15173
+
+# [可选，默认 3000] API 服务端口；本地 Web 代理自动转发到这个端口。
 PORT=3000
+
+# 私有上传目录，不能通过 Nginx/静态服务公开；生产挂载持久卷并与数据库配套备份。
+# 默认是项目根目录 .cage-files；改变目录前必须迁移已有文件。
+CAGE_FILES_DIR=.cage-files
+
+# [可选，范例默认 0.0.0.0] API 监听地址；这里使用 127.0.0.1，仅允许本机访问。
+# 需要容器内或局域网访问时改为 0.0.0.0，并按部署环境配置网络访问权限。
 HOST=127.0.0.1
+
+# ===== 仅执行数据库测试时使用；正常启动不需要 =====
+# [可选] 独立、可丢弃 PostgreSQL 测试集群的管理连接，需有建库和管理角色权限。
+# 测试会创建/删除临时库、初始化集群级角色；不能指向业务或生产数据库所在的集群。
+# 不填写时测试工具使用内嵌真实 PostgreSQL；这仅是测试行为，dev 不会自动启动数据库。
+# CAGE_TEST_DATABASE_URL=postgresql://test_admin:REPLACE_WITH_TEST_PASSWORD@127.0.0.1:5433/postgres

package/templates/app/AGENTS.md

@@ -1,13 +1,136 @@
-<!-- cage:begin v0.1.0 -->
-## Cage 框架约定
-
-1. 先声明聚合、状态、命令、约束和事件，再实现 handler、查询与页面。
-2. 修改后运行 cage check、cage gen、cage verify；用 cage impact --base-file 旧本体图.json 查看影响。
-3. domain 的声明必须是模块顶层 export const，并从 index.ts 导出。
-4. handler 的读依赖写入 reads；写入只走命令，第三方 IO 通过连接器。
-5. 前端从 @app/contracts 导入契约；生成物通过 cage gen 更新。
-6. 不得手写 HTTP 路由、拼接 SQL 或嵌入密钥；unsafe 必须注明 reason、owner。
-7. 迁移草稿需审查，已发布的迁移不可修改；新增能力点由管理员授权。
-8. 错误码见 docs/errors；完整示例见框架仓库 examples/purchase-admin。
-<!-- cage:end -->
+# 本项目的业务开发说明
+
+这是 create-cage-app 生成的业务项目，当前包含采购演示，可逐步替换成客户业务。业务源码在本项目，框架通过 @yss123/cage-* 依赖提供。
+
+先读 [业务开发指南](docs/ai/README.md)，按需求查 [任务配方](docs/ai/recipes.md)、[完整采购范例](docs/ai/purchase-example.md) 和 [错误码册](docs/errors/README.md)。这些资料就在项目内，无需克隆框架仓库。
+
+## 项目自己的业务约定
+
+客户术语、角色权限、状态规则、第三方协议和验收标准写在本节或独立业务文档，再从这里链接。新增业务以用户需求为准，不因模板包含采购示例就固定实现采购流程。
+
+本节位于托管区之外，cage sync 会保留。下面的托管区提供框架工作方法。
+
+<!-- cage:begin v0.3.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 命令；选中审批人不等于已具备能力、范围和额度。第三方 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 更新；项目独有的业务规则写在标记之外，避免升级覆盖。
+<!-- cage:end -->