@yss123/cage-cli 0.1.0 → 0.2.0

package/graph-ui/graph-relations.js

@@ -0,0 +1,141 @@
+import { kindLabels, nodeLabel } from './graph-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,
+        basis: edge.derived || (edge.kind === 'uses' && ['事件载荷', '出站映射'].includes(edge.as ?? ''))
+            ? 'inferred'
+            : edge.kind === 'uses' && edge.as === '查询'
+                ? 'text-match'
+                : 'declared',
+        direction: `“${a}” → “${b}”：${label}。`,
+    });
+    switch (edge.kind) {
+        case 'field':
+            return result(to.attrs.virtual ? '声明关联字段' : '包含字段', '数据结构', `“${a}”的字段声明中包含“${b}”。`, to.attrs.virtual
+                ? '这是 fields 中的集合关系，不占主表列；点击它指向目标的连线，查看关系基数、存储和读写方式。'
+                : '说明业务对象由哪些数据组成；调整字段时，可以继续沿线查看受影响的查询、审批和事件。', [`${from.id}.fields.${field}`]);
+        case 'refs': {
+            if (edge.cardinality === 'one-to-many')
+                return result('一对多 1:N', '反向关联 · 只读', `“${a}”使用 hasMany 反查“${b}”，对应外键是 ${to.id}.${edge.mappedBy}。`, '按需分页列出属于当前对象的子对象，不新建列或中间表。改变归属要执行子对象的命令；读取同时受两侧权限和范围约束。', [`${from.id}: hasMany(${JSON.stringify(to.id)}, { mappedBy: ${JSON.stringify(edge.mappedBy)} })`]);
+            if (edge.cardinality === 'many-to-many')
+                return result('多对多 N:M', '集合关联 · 自动中间表', `“${a}”声明 manyToMany：一个所属对象可以关联多个“${b}”，同一个目标也可被多个所属对象关联。`, '框架生成中间表、同租户外键和组合唯一约束；所属对象的命令用 ID 数组替换关联，与主记录共同提交。解绑不删除目标，读取通过独立分页接口。', [`${from.id}: manyToMany(${JSON.stringify(to.id)})`, `自动中间表：${from.attrs.through}`]);
+            return result(edge.cardinality === 'one-to-one' ? '一对一 1:1' : '多对一 N:1', '数据关联', `“${a}”声明为引用“${b}”的字段，保存所关联对象的标识。`, edge.cardinality === 'one-to-one'
+                ? '租户内的唯一约束保证同一目标最多被这一字段引用一次；可选字段允许没有关联，并不要求双方一定存在。'
+                : `多个所属对象可以引用同一${kindLabels[to.kind]}。字段保存外键；具体查询仍受数据范围约束，这条线本身不执行查询。`, [`${from.id}: ref(${JSON.stringify(to.id)})${edge.cardinality === 'one-to-one' ? '.unique()' : ''}`]);
+        }
+        case 'ownership':
+            return result(`拥有${kindLabels[to.kind]}`, '标识归属 · 推导', `“${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 'cancels':
+            return result('取消审批', '流程取消', `“${b}”在 cancelOn 中声明了“${a}”事件。`, '事件发生后取消该单据仍在进行的审批；不会启动新流程，也不替代释放资源等业务反应。', [`${to.id}.cancelOn 包含 ${from.id}`], to);
+        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}`]);
+    }
+}

package/graph-ui/graph-search.js

@@ -0,0 +1,62 @@
+// 轻量、可解释的名称检索；不调用模型，不把关键词匹配描述成“理解任意需求”。
+// 中文用相邻双字作为线索，让“采购单取消”能匹配“取消采购单”，同时返回命中依据。
+import { kindLabels, nodeLabel } from './graph-model.js';
+const normalize = (value) => value.normalize('NFKC').toLowerCase().trim();
+function searchTerms(query) {
+    const terms = query.match(/[a-z0-9_$.:/-]+/g) ?? [];
+    for (const segment of query.match(/[\p{Script=Han}]+/gu) ?? []) {
+        const chars = [...segment];
+        if (chars.length === 1)
+            terms.push(segment);
+        else
+            for (let i = 0; i < chars.length - 1; i++)
+                terms.push(chars[i] + chars[i + 1]);
+    }
+    return [...new Set(terms)];
+}
+function matchNode(node, query, labels, descriptions) {
+    const normalized = normalize(query);
+    if (!normalized)
+        return;
+    const terms = searchTerms(normalized);
+    const ownerId = ['field', 'state', 'command', 'capability', 'entry'].includes(node.kind)
+        ? node.id.split('.')[0]
+        : undefined;
+    const fields = [
+        ['key', node.key, 18],
+        ['id', node.id, 16],
+        ['label', nodeLabel(node, labels), 12],
+        ['description', descriptions[node.key] ?? String(node.attrs.description ?? ''), 10],
+        ['owner', ownerId ? (labels[`aggregate:${ownerId}`] ?? ownerId) : '', 2],
+    ];
+    const matches = [];
+    let score = 0;
+    for (const [field, value, weight] of fields) {
+        const text = normalize(value);
+        if (!text)
+            continue;
+        const exact = text === normalized;
+        const whole = text.includes(normalized);
+        const found = terms.filter((term) => text.includes(term));
+        if (!exact && !whole && found.length === 0)
+            continue;
+        const points = exact ? weight * 100 : whole ? weight * 30 : weight * found.length;
+        score = Math.max(score, points);
+        matches.push({ field, value, terms: exact || whole ? [query.trim()] : found });
+    }
+    if (!matches.length)
+        return;
+    return { key: node.key, id: node.id, kind: node.kind, label: nodeLabel(node, labels), score, matches };
+}
+/** 排序稳定，结果携带命中字段；多个候选不静默合成一个“正确需求”。 */
+export function searchGraphNodes(model, query, labels = {}, options = {}) {
+    return model.nodes
+        .filter((node) => !options.kind || node.kind === options.kind)
+        .map((node) => matchNode(node, query, labels, options.descriptions ?? {}))
+        .filter((hit) => !!hit)
+        .sort((a, b) => b.score - a.score || a.key.localeCompare(b.key));
+}
+/** 画布的筛选与搜索下拉共用同一匹配规则，保留按节点类型查找的用法。 */
+export function matchesNode(node, query, labels) {
+    return !!matchNode(node, query, labels, {}) || normalize(kindLabels[node.kind]).includes(normalize(query));
+}

package/graph-ui/model.js

@@ -1,82 +1,24 @@
+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: '业务对象', color: '#197c72', short: '表', column: 0 },
-    command: { label: '命令', color: '#547db2', short: '令', column: 1 },
-    event: { label: '事件', color: '#c08c36', short: '事', column: 2 },
-    reaction: { label: '反应', color: '#aa7288', short: '应', column: 3 },
-    query: { label: '查询', color: '#648c5b', short: '查', column: 1 },
-    approval: { label: '审批', color: '#9c739f', short: '审', column: 3 },
-    route: { label: '审批路由', color: '#9c739f', short: '路', column: 3 },
-    job: { label: '定时任务', color: '#7f82a0', short: '时', column: 0 },
-    connector: { label: '连接器', color: '#b57452', short: '连', column: 4 },
-    outbound: { label: '出站映射', color: '#b57452', short: '出', column: 3 },
-    inbound: { label: '入站回调', color: '#b57452', short: '入', column: 4 },
-    field: { label: '字段', color: '#67998f', short: '字', column: 1 },
-    state: { label: '状态', color: '#898b69', short: '态', column: 2 },
-    capability: { label: '能力点', color: '#81949f', short: '权', column: 1 },
-    entry: { label: '新建入口', color: '#89938e', short: '+', column: 0 },
+    aggregate: { label: kindLabels.aggregate, color: '#197c72', short: '表', column: 0 },
+    command: { label: kindLabels.command, color: '#547db2', short: '令', column: 1 },
+    event: { label: kindLabels.event, color: '#c08c36', short: '事', column: 2 },
+    reaction: { label: kindLabels.reaction, color: '#aa7288', short: '应', column: 3 },
+    query: { label: kindLabels.query, color: '#648c5b', short: '查', column: 1 },
+    approval: { label: kindLabels.approval, color: '#9c739f', short: '审', column: 3 },
+    route: { label: kindLabels.route, color: '#9c739f', short: '路', column: 3 },
+    job: { label: kindLabels.job, color: '#7f82a0', short: '时', column: 0 },
+    connector: { label: kindLabels.connector, color: '#b57452', short: '连', column: 4 },
+    outbound: { label: kindLabels.outbound, color: '#b57452', short: '出', column: 3 },
+    inbound: { label: kindLabels.inbound, color: '#b57452', short: '入', column: 4 },
+    field: { label: kindLabels.field, color: '#67998f', short: '字', column: 1 },
+    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 },
 };
-export const edgeLabels = {
-    transition: '状态迁移',
-    reads: '读取',
-    emits: '发出',
-    uses: '使用字段',
-    triggers: '触发',
-    targets: '调用目标',
-    queries: '查询',
-    refs: '引用',
-    calls: '调用',
-    binds: '审批绑定',
-    field: '声明字段',
-    ownership: '归属（视图推导）',
-};
-/** 中文用于展示，英文仍作为复制、搜索和查源码的稳定标识。
- * 没有配置业务名称的未知节点保留原标识，不能猜测业务含义后悄悄改名。 */
-export function nodeLabel(node, labels = {}) {
-    if (node.kind === 'entry')
-        return '新建入口';
-    return labels[node.key] || String(node.attrs.description || node.id);
-}
-export function matchesNode(node, query, labels) {
-    return `${nodeLabel(node, labels)} ${node.id} ${kinds[node.kind].label}`
-        .toLowerCase()
-        .includes(query.toLowerCase());
-}
-export function projectGraph(graph) {
-    const nodes = graph.nodes.map((n) => ({ ...n, key: `${n.kind}:${n.id}` }));
-    const edges = [];
-    // 节点身份包含 kind。能力点和命令可能同名，不能单用显示名作为 SVG 的主键。
-    const find = (id) => nodes.find((n) => n.id === id && n.kind !== 'capability') ?? nodes.find((n) => n.id === id);
-    for (const e of graph.edges) {
-        let from = find(e.from);
-        const to = find(e.to);
-        // [new] 是迁移的起点，并不属于声明状态；在视图中显式标为虚拟入口。
-        if (!from && e.kind === 'transition' && e.from.endsWith('.[new]')) {
-            from = { key: `entry:${e.from}`, id: e.from, kind: 'entry', hash: '', attrs: {} };
-            nodes.push(from);
-        }
-        if (from && to)
-            edges.push({ ...e, from: from.key, to: to.key, key: `edge:${edges.length}`, derived: false });
-    }
-    for (const n of nodes) {
-        if (!['command', 'state', 'capability', 'entry'].includes(n.kind))
-            continue;
-        const owner = nodes.find((a) => a.kind === 'aggregate' && n.id.startsWith(`${a.id}.`));
-        if (owner)
-            edges.push({ key: `owner:${n.key}`, kind: 'ownership', from: owner.key, to: n.key, derived: true });
-    }
-    return { nodes, edges };
-}
-export const isSystem = (n) => /^(User|Role|Dept)(\.|$)/.test(n.id);
-export function neighborhood(model, key) {
-    const connected = new Set([key]);
-    for (const e of model.edges) {
-        if (e.from === key)
-            connected.add(e.to);
-        if (e.to === key)
-            connected.add(e.from);
-    }
-    return connected;
-}
+export const isSystem = (node) => /^(User|Role|Dept)(\.|$)/.test(node.id);
 export const NODE_WIDTH = 190;
 export const NODE_HEIGHT = 56;
 /** 按类型分组的平衡列 + 邻接排序。相同声明每次打开位置相同，没有持续运动的力导向

package/graph-ui/relations.js

@@ -1,125 +1,2 @@
-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}`]);
-    }
-}
+// Web 与 AI 上下文共用关系解释，保持证据和业务含义一致。
+export { explainEdge } from './graph-relations.js';

package/graph-ui/structure.js

@@ -3,7 +3,8 @@ export const TABLE_HEADER = 58;
 export const TABLE_ROW = 38;
 export const TABLE_FOOTER = 34;
 /** 对象卡片展示声明字段，而不是猜测完整数据库结构。系统自动添加的列不在
- * 抽取结果中，因此这里不补造 id、主键、外键约束或一对多基数。
+ * 抽取结果中，因此这里不补造 id 或主键。集合关系也留在 fields 中展示，
+ * 用类型和虚拟关系标记区分物理列，基数来自抽取器明确记录的声明。
  * 字段仍保留原节点身份，搜索、点击和关系解释都能回到同一份声明。 */
 export function tableCards(model) {
     return model.nodes
@@ -64,6 +65,8 @@ export function fieldType(field) {
         boolean: '布尔',
         id: '标识',
         ref: '引用',
+        hasMany: '一对多',
+        manyToMany: '多对多',
         list: '列表',
         json: 'JSON',
         date: '日期',

package/graph-ui/style.css

@@ -904,6 +904,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;

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.2.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,9 @@
     "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-kernel": "0.2.0",
+    "@yss123/cage-lint": "0.2.0",
+    "@yss123/cage-testkit": "0.2.0"
   },
   "devDependencies": {
     "@types/pg": "^8.15.5"
@@ -56,7 +56,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/.env.example

@@ -1,17 +1,61 @@
-# 推荐运行 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=
+
+# [可选，开发默认 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
+
+# [可选，范例默认 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