@yss123/cage-cli 0.2.0 → 0.3.1

package/graph-ui/graph-relations.js

@@ -1,4 +1,17 @@
+/**
+ * 将每种本体连线翻译为中文原因、用途、方向与证据，供 CLI 和浏览器详情复用。
+ * 解释基于投影端点及已抽取属性，分别标注显式声明、规则推导与文本匹配。
+ * 不求值 handler、映射或审批条件；存在连线只代表对应声明关系，不证明某次操作已发生。
+ */
 import { kindLabels, nodeLabel } from './graph-model.js';
+import { approvalRouteNodes, approvalRouteSteps } from './approval-tree.js';
+/**
+ * 按真实关系种类解释连线，补充声明来源和证据强度。
+ * @param edge 已投影且两端有效的边。
+ * @param model 展示图，提供端点和辅助声明。
+ * @param labels 中文名称覆盖。
+ * @returns 中文解释；只读元数据，不执行审批、映射、查询或业务命令。
+ */
 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);
@@ -20,6 +33,16 @@ export function explainEdge(edge, model, labels = {}) {
         direction: `“${a}” → “${b}”：${label}。`,
     });
     switch (edge.kind) {
+        case 'contains':
+            return result('包含业务阶段', '业务流程', `“${a}”声明了“${b}”阶段。`, '组织完整业务过程；阶段本身不执行命令。', [`${from.id}.stages → ${to.id}`]);
+        case 'implements':
+            return result('阶段实现', '实现依据', `“${a}”引用“${b}”作为实现。`, '从业务阶段追到实际声明；引用顺序不表示执行顺序。', [`${from.id}.action / details → ${to.id}`]);
+        case 'follows': {
+            const mode = { manual: '人工下一步', automatic: '自动触发', wait: '等待后继续' }[edge.mode ?? 'manual'];
+            return result(edge.label ?? mode, mode, `“${a}” → “${b}”：${edge.label}（${mode}）。`, edge.mode === 'automatic' ? '检查实际触发链是否存在；映射条件、事务和权限仍以引用的实现为准。' : '这是业务规格中的后续步骤，不会自动调度目标操作。', [`${from.attrs.process}.transitions`, `mode: ${edge.mode}`]);
+        }
+        case 'relates':
+            return result(edge.label ?? '关联业务对象', '业务关联', `“${a}”关联“${b}”：${edge.label}。`, '展示这个环节涉及的业务对象；数据引用、读取和写入由对应实现决定。', [edge.via ?? `${from.id}.subject`]);
         case 'field':
             return result(to.attrs.virtual ? '声明关联字段' : '包含字段', '数据结构', `“${a}”的字段声明中包含“${b}”。`, to.attrs.virtual
                 ? '这是 fields 中的集合关系，不占主表列；点击它指向目标的连线，查看关系基数、存储和读写方式。'
@@ -54,13 +77,14 @@ export function explainEdge(edge, model, labels = {}) {
             const as = edge.as ?? '';
             if (as === '可路由字段')
                 return result('允许审批读取', '审批可用字段', `“${a}”把“${b}”列入 routable，允许该字段作为审批流程变量。`, '明确审批可以拿到哪些业务数据。这里只表示允许使用；是否真的参与分支或审批选人，要查看审批路由的字段关系。', [`${from.id}.routable 包含 ${field}`]);
+            if (as === '催办申请人')
+                return result('确定催办申请人', '流程运营依赖', `“${a}”以提交时“${b}”的用户标识确定可催办申请人。`, '字段必须进入 routable；催办仍校验当前对象可见性、运行节点、业务版本及冷却，不赋予审批权限。字段也可能被选人或条件使用，完整用途见路由声明。', [`route.reminders.requesterField = ${JSON.stringify(field)}`]);
             if (as === '路由条件') {
-                // fieldsUsed 同时包含 when 条件和 deptLeader 选人字段，不能一律解释成条件判断。
+                // fieldsUsed 同时包含 when 条件、部门负责人和单据人员字段，必须区分实际选人方式。
                 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 conditions = approvalRouteNodes(nodes).filter((n) => n.kind === 'when' && n.cond.field === field);
+                const steps = approvalRouteSteps(nodes).map(step => ({ ...step, selector: step.kind === 'ai' ? step.handoff : step.approver }))
+                    .filter(step => (step.selector.kind === 'deptLeader' || step.selector.kind === 'field') && step.selector.field === field);
                 const operators = {
                     gt: '大于',
                     gte: '大于等于',
@@ -71,11 +95,11 @@ export function explainEdge(edge, model, labels = {}) {
                     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('、')}步骤`),
+                    ...steps.map((s) => s.selector.kind === 'field' ? `“${s.title}”步骤读取“${b}”保存的审批人员` : `“${s.title}”步骤根据“${b}”找到对应部门的负责人`),
+                    ...conditions.map((n) => `当“${b}”${operators[n.cond.op]} ${JSON.stringify(n.cond.value)} 时，加入${approvalRouteSteps(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)})`),
+                    ...steps.map((s) => `${s.title}: approver.${s.selector.kind}(${JSON.stringify(field)})`),
                     ...conditions.map((n) => `when(${n.cond.op}(${JSON.stringify(field)}, ${JSON.stringify(n.cond.value)}))`),
                 ]);
             }
@@ -122,17 +146,25 @@ export function explainEdge(edge, model, labels = {}) {
                 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]);
+            const collection = from.attrs.collection;
+            const execution = [
+                from.attrs.tx === 'same' ? '同一事务，任意一项失败共同回滚' : '异步投递',
+                from.attrs.order !== null && from.attrs.order !== undefined ? `步骤顺序 ${from.attrs.order}` : '',
+                collection ? `最多 ${collection.maxItems} 项，按 ${collection.orderBy} 排序，串行调用` : '',
+            ].filter(Boolean);
+            return result('调用业务命令', '反应调用', `“${a}”把事件映射后交给“${b}”处理。`, `将后续业务操作交给受约束的命令执行。${execution.join('；')}。${resources.length ? `此声明还标记${resources.join('、')}，用于检查资源获取与释放是否成对。` : ''}`, [`${from.id}.command → ${to.id}`, ...execution, ...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 ? '通过' : '驳回';
+            const returned = from.attrs.onReturned === to.id;
+            const outcome = approved && rejected ? '结束' : approved ? '通过' : returned ? '退回修改' : '驳回';
             return result(`${outcome}后执行`, '审批结论回写', `“${a}”${outcome}时绑定执行“${b}”。`, '将审批结论交给业务命令推进单据状态，并统一执行权限和业务约束。', [
                 approved ? `${from.id}.onApproved → ${to.id}` : '',
                 rejected ? `${from.id}.onRejected → ${to.id}` : '',
+                returned ? `${from.id}.onReturned → ${to.id}` : '',
             ].filter(Boolean));
         }
         case 'calls':

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.1",
   "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.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"
   },
   "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