@yss123/cage-cli 0.2.0 → 0.3.0

package/graph-ui/graph-search.js

@@ -1,7 +1,20 @@
+/**
+ * 不依赖模型的本体名称检索，供 CLI、agent 上下文和浏览器筛选共用。
+ * 归一化标识与文案，按完整命中或英文词、相邻中文片段计算权重，并返回命中字段。
+ * 结果是稳定排序的候选；不进行语义推理，无法保证理解否定、业务同义词或任意自然语言要求。
+ */
 // 轻量、可解释的名称检索；不调用模型，不把关键词匹配描述成“理解任意需求”。
 // 中文用相邻双字作为线索，让“采购单取消”能匹配“取消采购单”，同时返回命中依据。
 import { kindLabels, nodeLabel } from './graph-model.js';
+/**
+ * 统一全半角、大小写与首尾空白后进行词法比较，不改变输出中的原始标识。
+ */
 const normalize = (value) => value.normalize('NFKC').toLowerCase().trim();
+/**
+ * 拆出英文标识词及连续中文的相邻双字片段，并稳定去重。
+ * @param query 已归一化查询。
+ * @returns 匹配词列表；单汉字单独保留，不执行分词模型。
+ */
 function searchTerms(query) {
     const terms = query.match(/[a-z0-9_$.:/-]+/g) ?? [];
     for (const segment of query.match(/[\p{Script=Han}]+/gu) ?? []) {
@@ -14,6 +27,14 @@ function searchTerms(query) {
     }
     return [...new Set(terms)];
 }
+/**
+ * 对 key、ID、中文文案、原描述及所属对象分别评分，取最高单字段得分。
+ * @param node 待匹配节点。
+ * @param query 用户输入。
+ * @param labels 显示覆盖。
+ * @param descriptions 声明原始描述。
+ * @returns 有依据的候选或 undefined；所有命中字段仍保留，不把分数当业务证明。
+ */
 function matchNode(node, query, labels, descriptions) {
     const normalized = normalize(query);
     if (!normalized)
@@ -49,6 +70,14 @@ function matchNode(node, query, labels, descriptions) {
     return { key: node.key, id: node.id, kind: node.kind, label: nodeLabel(node, labels), score, matches };
 }
 /** 排序稳定，结果携带命中字段；多个候选不静默合成一个“正确需求”。 */
+/**
+ * 按可选类型筛选并稳定排序名称候选。
+ * @param model 展示图。
+ * @param query 关键词。
+ * @param labels 中文覆盖。
+ * @param options 类型范围及原始描述。
+ * @returns 完整候选数组，调用方负责 limit 和截断提示。
+ */
 export function searchGraphNodes(model, query, labels = {}, options = {}) {
     return model.nodes
         .filter((node) => !options.kind || node.kind === options.kind)
@@ -57,6 +86,13 @@ export function searchGraphNodes(model, query, labels = {}, options = {}) {
         .sort((a, b) => b.score - a.score || a.key.localeCompare(b.key));
 }
 /** 画布的筛选与搜索下拉共用同一匹配规则，保留按节点类型查找的用法。 */
+/**
+ * 供画布筛选复用名称匹配，并额外允许按中文类型名称筛选。
+ * @param node 展示节点。
+ * @param query 筛选文字。
+ * @param labels 中文映射。
+ * @returns 是否命中；空查询可匹配类型名称，不修改图。
+ */
 export function matchesNode(node, query, labels) {
     return !!matchNode(node, query, labels, {}) || normalize(kindLabels[node.kind]).includes(normalize(query));
 }

package/graph-ui/index.html

@@ -1,4 +1,6 @@
 <!doctype html>
+<!-- 本地本体探索器的静态骨架，由 graph 服务提供并由 app.js 填充。
+  ID 是脚本绑定契约；本页不嵌入领域执行代码，业务地图与完整本体共用导航和检查结果。 -->
 <html lang="zh-CN">
   <head>
     <meta charset="UTF-8" />
@@ -10,6 +12,7 @@
       href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 40 40'%3E%3Crect width='40' height='40' rx='10' fill='%232d665a'/%3E%3Cpath d='M11 12h18v16H11zm0 8h18m-9-8v16' stroke='%23fff' fill='none' stroke-width='2'/%3E%3C/svg%3E"
     />
     <link rel="stylesheet" href="/style.css" />
+    <link rel="stylesheet" href="/business.css" />
   </head>
   <body>
     <div class="app-shell">
@@ -19,7 +22,7 @@
           ><strong>CAGE<span>ATLAS</span></strong></a
         >
         <div class="breadcrumb">
-          <span>开发者工作台</span><b>/</b><span id="project-name">正在读取项目</span>
+          <span>业务探索工作台</span><b>/</b><span id="project-name">正在读取项目</span>
         </div>
         <span class="local-badge"><i></i>本地声明</span>
         <button
@@ -32,10 +35,13 @@
         </button>
       </header>
 
+      <!-- 对象/板块导航与类型筛选由当前视图重建，移动端展开状态由按钮的 aria-expanded 同步。 -->
       <aside class="sidebar" id="sidebar">
         <div class="section-label">项目工作区 <span>01</span></div>
         <div class="nav-active"><span class="nav-symbol">◇</span> 本体图谱 <span class="nav-dot"></span></div>
-        <div class="sidebar-heading">业务对象 <span id="aggregate-total"></span></div>
+        <div class="sidebar-heading">
+          <span id="objects-heading-label">业务板块</span><span id="aggregate-total"></span>
+        </div>
         <div id="aggregate-list" class="aggregate-list"></div>
         <div class="sidebar-heading" id="types-heading">
           节点类型 <button id="reset-types" class="text-button">重置</button>
@@ -61,12 +67,12 @@
         >
       </aside>
 
-      <main class="main">
+      <main class="main business-page" id="main">
         <section class="page-heading">
           <div>
             <div class="eyebrow">业务关系探索</div>
-            <h1>本体图谱<span class="version-tag">v0.1</span></h1>
-            <p>从声明出发，看见业务如何连接。</p>
+            <h1 id="page-title">业务地图</h1>
+            <p id="page-description">先理解业务，再沿流程找到实现。</p>
           </div>
           <div class="heading-actions">
             <button id="download" class="button secondary"><span>↓</span> 导出 JSON</button
@@ -77,15 +83,17 @@
         <section class="overview" aria-label="图谱统计">
           <div class="overview-item">
             <span class="metric-icon aggregate-icon">◇</span>
-            <div><small>业务对象</small><strong id="metric-aggregates">—</strong></div>
+            <div>
+              <small id="metric-first-label">业务板块</small><strong id="metric-aggregates">—</strong>
+            </div>
           </div>
           <div class="overview-item">
             <span class="metric-icon node-icon">⠿</span>
-            <div><small>声明节点</small><strong id="metric-nodes">—</strong></div>
+            <div><small id="metric-second-label">流程入口</small><strong id="metric-nodes">—</strong></div>
           </div>
           <div class="overview-item">
             <span class="metric-icon edge-icon">↗</span>
-            <div><small>声明关系</small><strong id="metric-edges">—</strong></div>
+            <div><small id="metric-third-label">业务对象</small><strong id="metric-edges">—</strong></div>
           </div>
           <div class="overview-health">
             <span id="health-dot" class="health-dot"></span>
@@ -94,12 +102,13 @@
           </div>
         </section>
 
-        <section class="explorer" aria-label="交互式本体图谱">
+        <!-- 三个视图共享工具条；business-view 承载流程，canvas 承载完整图和对象字段图。 -->
+        <section class="explorer business-mode" id="explorer" aria-label="交互式业务地图与本体图谱">
           <div class="graph-panel">
             <div class="graph-toolbar">
               <div class="tabs" role="group" aria-label="图谱视图">
-                <button data-mode="structure" class="active" aria-pressed="true">对象与字段</button
-                ><button data-mode="business" aria-pressed="false">业务流程</button
+                <button data-mode="business" class="active" aria-pressed="true">业务地图</button
+                ><button data-mode="structure" aria-pressed="false">对象与字段</button
                 ><button data-mode="all" aria-pressed="false">完整本体</button>
               </div>
               <div class="search-wrap">
@@ -107,13 +116,14 @@
                 ><input
                   id="search"
                   type="search"
-                  placeholder="搜索中文名称或代码标识"
+                  placeholder="搜索业务、流程或代码标识"
                   aria-label="搜索节点"
                   autocomplete="off"
                 /><kbd>/</kbd>
                 <div id="search-results" class="search-results" hidden></div>
               </div>
             </div>
+            <div id="business-view" class="business-view" aria-label="业务板块与流程"></div>
             <div class="graph-subbar">
               <span
                 ><i class="tiny-dot"></i><strong id="view-title">全部业务</strong
@@ -150,6 +160,7 @@
                     <path d="M0 0L10 5L0 10z" fill="#357c6c" />
                   </marker>
                 </defs>
+                <!-- 脚本只变换 viewport 来实现平移和缩放，边先于节点绘制以保留节点命中面。 -->
                 <g id="viewport">
                   <g id="edges"></g>
                   <g id="nodes"></g>
@@ -180,11 +191,13 @@
           </div>
           <aside id="inspector" class="inspector" aria-label="节点与关系详情" aria-live="polite"></aside>
         </section>
+        <div id="business-health" class="business-health" aria-live="polite"></div>
         <footer class="page-footer">
           <span id="domain-path">packages/domain/src/index.ts</span><span>只读探索 · 不连接业务数据库</span>
         </footer>
       </main>
     </div>
+    <!-- 规则发现保留在独立对话框，不因主画布能显示就隐藏声明错误。 -->
     <dialog id="findings-dialog">
       <div class="dialog-heading">
         <h2>声明检查</h2>
@@ -192,6 +205,7 @@
       </div>
       <div id="findings-list"></div>
     </dialog>
+    <!-- 模块入口在 DOM 骨架之后加载，固定资源由 CLI 构建脚本输出到 graph-ui。 -->
     <script type="module" src="/app.js"></script>
   </body>
 </html>

package/graph-ui/model.js

@@ -1,6 +1,9 @@
 import { kindLabels } from './graph-model.js';
 export { nodeLabel, projectGraph, neighborhood, edgeLabels } from './graph-model.js';
 export { matchesNode } from './graph-search.js';
+/**
+ * 节点类型对应的中文标签、颜色、短字和布局列优先级；只影响图谱呈现。
+ */
 export const kinds = {
     aggregate: { label: kindLabels.aggregate, color: '#197c72', short: '表', column: 0 },
     command: { label: kindLabels.command, color: '#547db2', short: '令', column: 1 },
@@ -17,12 +20,30 @@ export const kinds = {
     state: { label: kindLabels.state, color: '#898b69', short: '态', column: 2 },
     capability: { label: kindLabels.capability, color: '#81949f', short: '权', column: 1 },
     entry: { label: kindLabels.entry, color: '#89938e', short: '+', column: 0 },
+    process: { label: kindLabels.process, color: '#397a56', short: '流', column: 0 },
+    stage: { label: kindLabels.stage, color: '#648c5b', short: '段', column: 1 },
 };
+/**
+ * 按组织聚合前缀识别默认隐藏对象，不是能力或租户授权判断。
+ */
 export const isSystem = (node) => /^(User|Role|Dept)(\.|$)/.test(node.id);
+/**
+ * 完整本体普通节点的固定宽度，单位为画布单位，与 edgePath 端点计算保持一致。
+ */
 export const NODE_WIDTH = 190;
+/**
+ * 完整本体普通节点高度，单位为画布单位；对象字段卡片使用独立动态高度。
+ */
 export const NODE_HEIGHT = 56;
 /** 按类型分组的平衡列 + 邻接排序。相同声明每次打开位置相同，没有持续运动的力导向
  * 动画；读长名称、比较刷新前后的关系时不会被随机布局打断。 */
+/**
+ * 按语义列与邻接平均纵坐标计算确定性位置，避免随机布局干扰阅读。
+ * @param nodes 可见节点，不修改原数组。
+ * @param edges 可见关系。
+ * @param focusKey 小于等于 12 节点时以该节点作为中间列。
+ * @returns 节点 key 到坐标映射；没有持续动画或 DOM 副作用。
+ */
 export function layoutGraph(nodes, edges, focusKey) {
     const positions = new Map();
     // 小范围聚焦按关系方向排布：依赖方在左、当前节点居中、目标在右。
@@ -65,6 +86,13 @@ export function layoutGraph(nodes, edges, focusKey) {
     }
     return positions;
 }
+/**
+ * 根据两个普通节点位置绘制曲线，同列及自环从侧面绕行。
+ * @param from 起点左上角。
+ * @param to 终点左上角。
+ * @param self 是否自环。
+ * @returns SVG d 属性，不绘制或修改节点。
+ */
 export function edgePath(from, to, self) {
     if (self)
         return `M${from.x + NODE_WIDTH - 25},${from.y} C${from.x + NODE_WIDTH + 50},${from.y - 65} ${from.x + NODE_WIDTH + 50},${from.y + 100} ${from.x + NODE_WIDTH - 25},${from.y + NODE_HEIGHT}`;

package/graph-ui/relations.js

@@ -1,2 +1,6 @@
+/**
+ * 浏览器关系解释的转导出入口，与 CLI 使用同一份 src/graph-relations 规则。
+ * 这里只暴露可浏览器执行的纯解释逻辑，不加载数据库、审批引擎或 Node 文件访问模块。
+ */
 // Web 与 AI 上下文共用关系解释，保持证据和业务含义一致。
 export { explainEdge } from './graph-relations.js';

package/graph-ui/structure.js

@@ -1,11 +1,28 @@
+/**
+ * 字段卡片固定宽度，单位为画布单位；布局与引用线共享该值。
+ */
 export const TABLE_WIDTH = 336;
+/**
+ * 字段卡片标题区高度，引用目标连接到其中心。
+ */
 export const TABLE_HEADER = 58;
+/**
+ * 单字段行高度，字段引用起点用此值定位行中心。
+ */
 export const TABLE_ROW = 38;
+/**
+ * 字段卡片尾部留白高度，与动态字段数一起确定总高。
+ */
 export const TABLE_FOOTER = 34;
 /** 对象卡片展示声明字段，而不是猜测完整数据库结构。系统自动添加的列不在
  * 抽取结果中，因此这里不补造 id 或主键。集合关系也留在 fields 中展示，
  * 用类型和虚拟关系标记区分物理列，基数来自抽取器明确记录的声明。
  * 字段仍保留原节点身份，搜索、点击和关系解释都能回到同一份声明。 */
+/**
+ * 沿 field 边收集聚合声明字段并计算卡片高度，不补造系统列。
+ * @param model 展示图。
+ * @returns 所有聚合卡片，虚拟关系仍作为声明字段展示。
+ */
 export function tableCards(model) {
     return model.nodes
         .filter((n) => n.kind === 'aggregate')
@@ -16,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);
@@ -35,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);
@@ -54,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: '文本',
@@ -67,6 +109,8 @@ export function fieldType(field) {
         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;
@@ -1072,6 +1081,7 @@ dialog::backdrop {
   background: #263c2d44;
   backdrop-filter: blur(3px);
 }
+/* 检查结果使用原生 dialog 的内容布局，打开关闭和 findings 列表由 app.ts 管理。 */
 .dialog-heading {
   display: flex;
   align-items: center;
@@ -1121,6 +1131,7 @@ dialog::backdrop {
     margin-bottom: 29px;
   }
 }
+/* 中等宽度逐步压缩边距和工具条，保留交互控件；更窄断点再切换单列布局。 */
 @media (max-width: 1200px) {
   :root {
     --sidebar: 186px;
@@ -1578,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,6 +1,6 @@
 {
   "name": "@yss123/cage-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "cage 命令行：init、gen、check、graph、context、impact、test、verify、budget、sync、upgrade、dev、migrate",
   "type": "module",
   "bin": {
@@ -31,9 +31,11 @@
     "typescript": "~5.9.3",
     "vitest": "^4.1.12",
     "zod": "^4.1.5",
-    "@yss123/cage-kernel": "0.2.0",
-    "@yss123/cage-lint": "0.2.0",
-    "@yss123/cage-testkit": "0.2.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"

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

@@ -38,6 +38,12 @@ CAGE_ADMIN_DATABASE_URL=postgresql://postgres:REPLACE_WITH_ADMIN_PASSWORD@127.0.
 # 自动生成 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 需另行配置业务连接器要求的地址与密钥，不是修改此值就完成对接。
@@ -50,6 +56,10 @@ 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

package/templates/app/AGENTS.md

@@ -10,7 +10,7 @@
 
 本节位于托管区之外，cage sync 会保留。下面的托管区提供框架工作方法。
 
-<!-- cage:begin v0.2.0 -->
+<!-- cage:begin v0.3.0 -->
 ## Cage 业务开发约定（框架托管）
 
 ### 先读，再按需求改业务
@@ -19,6 +19,33 @@
 
 先读项目说明指定的学习资料，默认入口为 `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）和**实际验证通过**（真实角色与模型联调）；空白模板的参考代码不表示已启用。具体接入顺序和验收步骤见该指南，不必将整份指南塞入每次任务上下文。
+
 ### 业务代码放在哪里
 
 | 位置 | 职责 |
@@ -28,7 +55,7 @@
 | `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` | 会话、导航、布局、模块组合；main.tsx 只挂载和装配 Provider |
+| `apps/web/src/app` | 会话、URL 路由、布局、模块组合；main.tsx 只挂载和装配 Provider |
 | `apps/web/src/modules/<业务>` | 页面、表单、专用 hooks/API/样式；从模块 index.ts 暴露页面 |
 | `apps/web/src/shared` | 跨模块复用且不绑定业务的 UI、hooks、纯辅助函数 |
 | `db/migrations` | 审查过的结构迁移，作用于已配置的数据库 |
@@ -40,11 +67,11 @@
 ### 实现一项需求的顺序
 
 1. 先运行 `pnpm exec cage context "需求关键词"`；按需 `graph search` 查候选、`graph inspect` 查完整节点、`graph path` 看关系路径。确认中文匹配入口后按源码位置阅读实现；候选和子图不是全部依赖，具体条件不能凭连线推断。完整用法见 `docs/ai/ontology-context.md`。从用户需求确定字段、状态/动作、角色/范围、约束与后续动作；能由业务声明表达的不改框架。
-2. 已有业务含义变化时，修改前保存本体图基线：`pnpm exec cage analyze` 后将 `.cage/ontology.json` 另存为独立文件；或使用真实 Git 基线。
+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 --base-file 旧图.json`，补中文图谱名。
-5. 页面使用生成方法并处理 code/domainCode；新增能力由管理员授权。数据库结构变化审查后显式 `pnpm migrate`，dev 不代办迁移。
-6. 按改动运行必要验证，交付时说明体验步骤、授权配置、迁移，以及通过/跳过/未执行项。
+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` 逐文件检查详细中文注释与实现一致，再按改动运行必要验证；交付时说明体验步骤、授权配置、迁移、注释覆盖，以及通过/跳过/未执行项。
 
 ### 必守边界
 
@@ -55,17 +82,25 @@
 - 自定义查询声明 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，不能替代普通业务声明。
-- 代码注释说明职责、关键流程和设计原因；避免无业务价值的防御分支和静默兜底。维护脚本用 TypeScript，不新增 .mjs。
+- 按前述详细中文注释规范完成文件、API、业务声明和关键流程说明；避免无业务价值的防御分支和静默兜底。维护脚本用 TypeScript，不新增 .mjs。
 
 ### 最小命令形状
 
 ```ts
 // 片段：Order 为已导出的聚合，OrderSubmitted 为事件，业务校验按需求添加。
+/**
+ * 将草稿订单提交审批：只有 draft 可进入 pending_approval。
+ * 入口使用 Order.submit 能力，真实授权、范围、状态和版本由内核检查；声明本身不自动授予权限。
+ * handler 返回草稿供后续校验和持久化，OrderSubmitted 随命令事务登记，后续由已配置消费者处理。
+ * 失败不会提交这次业务变更；事件已登记也不代表后续审批已经完成。
+ */
 export const submitOrder = command(Order, {
   name: 'submit',
   from: 'draft',
@@ -79,17 +114,22 @@ export const submitOrder = command(Order, {
 
 ### 启动、验证与排错
 
-在项目根目录执行：首次 `pnpm install`，复制并编辑 .env.example，仅提供已有库管理员连接后 `pnpm exec cage init`；再 `pnpm build:app`、`pnpm gen`，审查后 `pnpm migrate`，最后 `pnpm dev`。已有配置不能覆盖。
+在项目根目录执行：首次 `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 的逆向遍历不表示执行方向。报告中的测试/前端文件是候选，须核对；查询也会覆盖当前 .cage/ontology.json，旧基线务必另存。
+- `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 更新；项目独有的业务规则写在标记之外，避免升级覆盖。

package/templates/app/README.md

@@ -21,6 +21,7 @@ pnpm exec cage init
 pnpm gen
 # 审查 db/migrations 后执行表结构迁移。
 pnpm migrate
+pnpm exec cage bootstrap --credentials-file .cage/admin-credentials.json
 pnpm dev
 ```
 
@@ -48,11 +49,13 @@ pnpm dev
 
 测试环境会初始化集群级角色，因此 `CAGE_TEST_DATABASE_URL` 必须指向独立测试集群。运行 `pnpm cage verify` 验证示例；框架仓库根目录的 `pnpm test:docker` 验证全部框架测试。
 
-浏览器打开终端打印的 Web 地址；配置示例使用 <http://localhost:15173>。初始管理员凭证在 API 终端显示一次。
+浏览器打开终端打印的 Web 地址；配置示例使用 <http://localhost:15173>。管理员凭证由显式 bootstrap 交付到新的受限文件，交付后移除。初始化仅授予系统管理能力，采购能力需要管理员明确配置。
 `CAGE_WEB_PORT` 控制 Web 端口，`PORT` 控制 API 端口，Vite 代理同步使用它。缺少数据库配置时会给出错误，需填写 `.env` 后重新启动。
 
 ## 体验完整采购流程
 
+前端使用 React Router：工作台 `/workspace`，采购列表 `/procurement/orders`，单据详情 `/procurement/orders/:id`，审批 `/approvals`，库存 `/inventory`，登录 `/login`。单号和审批待办可直接打开详情；刷新、前进后退和登录回跳保留页面地址。新增页面与部署按[路由和浏览器验收指南](docs/ai/routing.md)执行；Nginx 示例见 [deploy/nginx.conf](deploy/nginx.conf)。
+
 1. 管理员在“库存台账”登记 `A-01` 等物料。
 2. 进入 `/admin/` 创建采购员、经理，分别分配采购命令和审批能力；经理的 `PurchaseOrder.approve` 参数配置 `ceiling`。
 3. 把经理设为采购员所在部门的负责人。提单人与审批人必须不同。