@yss123/cage-cli 0.1.0 → 0.3.0

package/dist/graph-query.js

@@ -0,0 +1,304 @@
+/**
+ * 在单次本体快照上执行可解释检索、精确定位与有界关系路径查询。
+ * 复用共享投影、中文搜索和关系解释，为报告补充源码精度、抽取时间、图指纹和证据边界。
+ * 查询为纯计算，不重新读取源码或启动业务；路径是静态关系链，逆向遍历不表示反向执行。
+ */
+// 本体查询只消费一次抽取快照。CLI 每次重新抽取；Web 使用页面显示的快照，
+// 报告明确记录时间与来源，不能把常驻页面里的旧图伪装成刚分析的代码。
+import { createHash } from 'node:crypto';
+import { kindLabels, nodeLabel, projectGraph } from './graph-model.js';
+import { explainEdge } from './graph-relations.js';
+import { searchGraphNodes } from './graph-search.js';
+/**
+ * 所有图查询共用的能力边界说明，必须随报告交付以免把静态关系解释成运行结果。
+ */
+export const graphLimits = [
+    '图描述业务声明及可抽取的依赖；条件分支、计算和 map 返回 null 等行为仍须阅读源码。',
+    '名称检索与测试匹配是候选线索；未覆盖全部前端依赖，也不证明业务正确性或测试已通过。',
+    'source.precision=aggregate 表示只定位到所属聚合声明；source=null 表示当前项目索引没有源码位置。',
+];
+/**
+ * 建立单次快照的索引和解释函数，不再次抽取或读取源码。
+ * @param snapshot 当前图及展示信息。
+ * @param freshness 区分新进程抽取与页面已显示快照。
+ * @returns 节点/关系访问器、精确解析、搜索和带时间指纹的公共元数据。
+ */
+export function graphReader(snapshot, freshness = 'fresh-extraction') {
+    const model = projectGraph(snapshot.graph);
+    const byKey = new Map(model.nodes.map((node) => [node.key, node]));
+    const labels = snapshot.presentation.labels;
+    const sourceOf = (node) => {
+        if (node.file)
+            return { file: node.file, line: node.line, precision: 'declaration' };
+        if (['field', 'state', 'capability', 'entry'].includes(node.kind)) {
+            const owner = byKey.get(`aggregate:${node.id.split('.')[0]}`);
+            if (owner?.file)
+                return { file: owner.file, line: owner.line, precision: 'aggregate' };
+        }
+        return null;
+    };
+    const nodeInfo = (node) => ({
+        key: node.key,
+        id: node.id,
+        kind: node.kind,
+        kindLabel: kindLabels[node.kind],
+        label: nodeLabel(node, labels),
+        hash: node.hash,
+        source: sourceOf(node),
+        attrs: node.attrs,
+    });
+    const relationInfo = (edge) => {
+        const explanation = explainEdge(edge, model, labels);
+        return {
+            ...edge,
+            label: explanation.label,
+            why: explanation.why,
+            purpose: explanation.purpose,
+            direction: explanation.direction,
+            evidence: {
+                basis: explanation.basis,
+                entries: explanation.evidence,
+                source: sourceOf(explanation.source),
+            },
+        };
+    };
+    const search = (query, kind) => searchGraphNodes(model, query, labels, { kind, descriptions: snapshot.presentation.descriptions });
+    const resolve = (selector) => {
+        const query = selector.normalize('NFKC').trim().toLowerCase();
+        // 先匹配带类型的完整身份，再匹配裸 ID / 中文全称。歧义时返回候选，不偷选第一项。
+        const keyed = model.nodes.filter((n) => n.key.normalize('NFKC').toLowerCase() === query);
+        const exact = keyed.length
+            ? keyed
+            : model.nodes.filter((n) => n.id.normalize('NFKC').toLowerCase() === query);
+        const named = exact.length
+            ? exact
+            : model.nodes.filter((n) => nodeLabel(n, labels).normalize('NFKC').toLowerCase() === query);
+        const hits = search(selector);
+        const candidates = named.length
+            ? named.map((n) => hits.find((hit) => hit.key === n.key))
+            : hits.slice(0, 8);
+        return {
+            selector,
+            status: named.length === 1 ? 'ok' : named.length > 1 ? 'ambiguous' : 'not-found',
+            candidates,
+        };
+    };
+    const meta = {
+        schemaVersion: 1,
+        project: snapshot.project,
+        domain: snapshot.domain,
+        extractedAt: snapshot.generatedAt,
+        freshness,
+        graphHash: createHash('sha256').update(JSON.stringify(snapshot.graph)).digest('hex').slice(0, 16),
+        findings: snapshot.findings,
+        limitations: graphLimits,
+    };
+    return { model, byKey, meta, sourceOf, nodeInfo, relationInfo, search, resolve };
+}
+/**
+ * 查询关键词并附源码位置，截断时仍报告完整命中总数。
+ * @param snapshot 单次快照。
+ * @param query 查询词。
+ * @param options limit 默认 10，kind 可限制类型。
+ * @returns 候选报告；没有命中返回 not-found，不表示框架不支持需求。
+ */
+export function searchGraph(snapshot, query, options = {}) {
+    const reader = graphReader(snapshot);
+    const hits = reader.search(query, options.kind);
+    const limit = options.limit ?? 10;
+    return {
+        ...reader.meta,
+        operation: 'search',
+        status: hits.length ? 'ok' : 'not-found',
+        query,
+        total: hits.length,
+        truncated: hits.length > limit,
+        hits: hits
+            .slice(0, limit)
+            .map((hit) => ({ ...hit, source: reader.sourceOf(reader.byKey.get(hit.key)) })),
+    };
+}
+/**
+ * 精确检查唯一节点及直接关联，不以模糊候选替代选择。
+ * @param snapshot 单次快照。
+ * @param selector 完整 key、唯一 ID 或唯一中文全称。
+ * @returns 节点/关联及解析状态；歧义时 node=null，并保留候选。
+ */
+export function inspectGraph(snapshot, selector) {
+    const reader = graphReader(snapshot);
+    const resolution = reader.resolve(selector);
+    const node = resolution.status === 'ok' ? reader.byKey.get(resolution.candidates[0].key) : undefined;
+    return {
+        ...reader.meta,
+        operation: 'inspect',
+        status: resolution.status,
+        resolution,
+        node: node ? reader.nodeInfo(node) : null,
+        relations: node
+            ? reader.model.edges
+                .filter((edge) => edge.from === node.key ||
+                edge.to === node.key ||
+                (edge.kind === 'transition' && edge.via === node.id && node.kind === 'command'))
+                .map(reader.relationInfo)
+            : [],
+    };
+}
+/** 默认沿箭头找最短关系链；双向探索要显式选择 both，每一步保留原箭头。
+ * 归属虚线只用于整理对象，不能借它制造“任意两个命令都会互相调用”的短路。 */
+/**
+ * 广度优先寻找深度内最短声明关系链，排除派生归属边。
+ * @param snapshot 单次快照。
+ * @param from 起点选择器。
+ * @param to 终点选择器。
+ * @param options 默认 out 沿箭头、深度 6，both 允许明确标记的逆向遍历。
+ * @returns 路径或定位/深度内未找到状态；不证明实际执行先后。
+ */
+export function findGraphPath(snapshot, from, to, options = {}) {
+    const reader = graphReader(snapshot);
+    const start = reader.resolve(from), end = reader.resolve(to);
+    const direction = options.direction ?? 'out', depth = options.depth ?? 6;
+    const base = { ...reader.meta, operation: 'path', from: start, to: end, direction, depth };
+    const nodes = [], steps = [];
+    if (start.status !== 'ok' || end.status !== 'ok')
+        return {
+            ...base,
+            status: start.status === 'ambiguous' || end.status === 'ambiguous'
+                ? 'ambiguous'
+                : 'not-found',
+            nodes,
+            steps,
+        };
+    const first = start.candidates[0].key, last = end.candidates[0].key;
+    const queue = [{ key: first, steps: [] }];
+    const visited = new Set([first]);
+    for (const current of queue) {
+        if (current.key === last) {
+            steps.push(...current.steps);
+            nodes.push(...[first, ...steps.map((s) => s.to)].map((key) => reader.nodeInfo(reader.byKey.get(key))));
+            return { ...base, status: 'ok', nodes, steps };
+        }
+        if (current.steps.length >= depth)
+            continue;
+        for (const edge of reader.model.edges) {
+            if (edge.derived)
+                continue;
+            const forward = edge.from === current.key;
+            const next = forward
+                ? edge.to
+                : direction === 'both' && edge.to === current.key
+                    ? edge.from
+                    : undefined;
+            if (!next || visited.has(next))
+                continue;
+            visited.add(next);
+            queue.push({
+                key: next,
+                steps: [
+                    ...current.steps,
+                    {
+                        from: current.key,
+                        to: next,
+                        traversal: forward ? 'forward' : 'reverse',
+                        relation: reader.relationInfo(edge),
+                    },
+                ],
+            });
+        }
+    }
+    return { ...base, status: 'not-found-within-depth', nodes, steps };
+}
+/**
+ * 格式化可空源码位置，聚合精度额外标记；没有位置时引导查公开 API，不伪造文件名。
+ */
+export const sourceText = (source) => source
+    ? `${source.file}${source.line ? `:${source.line}` : ''}${source.precision === 'aggregate' ? '（所属聚合）' : ''}`
+    : '当前工程无源码定位，查对应依赖的公开 API';
+/**
+ * 报告使用的证据强度中文名称，显式、推导、文本匹配不能互相替代。
+ */
+export const evidenceLabels = { declared: '显式声明', inferred: '规则推导', 'text-match': '文本匹配线索' };
+/**
+ * 把关系解释转换为 Markdown 条目，保留原因、用途与源码。
+ * @param relation 完整关系证据。
+ * @returns 文本行数组，不执行连线所指操作。
+ */
+export function relationMarkdown(relation) {
+    return [
+        `- ${relation.from} → ${relation.to}：${relation.label}${relation.via ? `；经 ${relation.via}` : ''}`,
+        `  - 原因：${relation.why}`,
+        `  - 用途：${relation.purpose}`,
+        `  - 依据：${evidenceLabels[relation.evidence.basis]}；${relation.evidence.entries.join('；')}`,
+        `  - 源码：${sourceText(relation.evidence.source)}`,
+    ];
+}
+/**
+ * 输出项目、抽取时间、指纹及新鲜度说明。
+ * @param report 查询公共元数据。
+ * @param title 报告标题。
+ * @returns Markdown 头部行数组，不访问文件。
+ */
+export function reportHeader(report, title) {
+    return [
+        `# ${title}`,
+        '',
+        `项目：${report.project}；抽取时间：${report.extractedAt}；图指纹：${report.graphHash}`,
+        `来源：${report.freshness === 'fresh-extraction' ? '本次重新抽取' : '页面当前快照，修改代码后需重新抽取'}。`,
+        '',
+    ];
+}
+/**
+ * 输出当前规则问题及共同边界，规则无问题也不声称测试已运行。
+ * @param report 查询元数据与 findings。
+ * @returns Markdown 尾部行数组。
+ */
+export function reportFooter(report) {
+    return [
+        '',
+        '## 当前规则问题',
+        '',
+        ...(report.findings.length
+            ? report.findings.map((f) => `- [${f.code}] ${f.at ?? ''} ${f.reason}；修复：${f.fix}`)
+            : ['当前抽取未发现规则问题；未执行测试。']),
+        '',
+        '## 使用边界',
+        '',
+        ...report.limitations.map((note) => `- ${note}`),
+    ];
+}
+/**
+ * 按 search、inspect、path 分支渲染报告，保留歧义、截断和逆向解释。
+ * @param report 查询结果联合。
+ * @returns Markdown 字符串；写盘和退出码由 graphCommand 决定。
+ */
+export function formatGraphQuery(report) {
+    const lines = reportHeader(report, `Cage 本体${report.operation === 'search' ? '检索' : report.operation === 'inspect' ? '节点详情' : '关系路径'}`);
+    if (report.operation === 'search') {
+        lines.push(`关键词：${report.query}；命中 ${report.total} 项${report.truncated ? '，结果已截断，可提高 --limit 或缩小关键词' : ''}。`, '');
+        for (const hit of report.hits)
+            lines.push(`- **${hit.label}** \`${hit.key}\`（${kindLabels[hit.kind]}，得分 ${hit.score}）`, `  - 命中：${hit.matches.map((m) => `${m.field}=${m.value}（${m.terms.join('、')}）`).join('；')}`, `  - 源码：${sourceText(hit.source)}`);
+    }
+    else if (report.operation === 'inspect') {
+        if (report.node)
+            lines.push(`## ${report.node.label} · ${report.node.key}`, '', `源码：${sourceText(report.node.source)}`, '', '```json', JSON.stringify(report.node.attrs, null, 2), '```', '', '## 关联原因与用途', '', ...report.relations.flatMap(relationMarkdown));
+        else
+            lines.push(`节点定位：${report.status}；请从候选中复制完整 key 再执行 inspect。`, '', ...report.resolution.candidates.map((hit) => `- ${hit.label} \`${hit.key}\``));
+    }
+    else {
+        lines.push(`路径状态：${report.status}；方向：${report.direction}；深度上限：${report.depth}。`, '');
+        if (report.status === 'ok') {
+            lines.push(report.nodes.map((n) => `${n.label}（${n.key}）`).join(' → '), '');
+            for (const step of report.steps)
+                lines.push(`遍历：${step.from} → ${step.to}${step.traversal === 'reverse' ? '（逆向查看依赖，不表示执行方向）' : ''}`, ...relationMarkdown(step.relation), '');
+        }
+        else {
+            lines.push('未得到路径；未命中时缩小到完整 key，有歧义时从以下候选选择。已定位两端时可提高 --depth，或使用 --direction both 探索反向依赖。', '', ...[report.from, report.to].flatMap((r) => [
+                `${r.selector}：${r.status}`,
+                ...r.candidates.map((hit) => `- ${hit.label} \`${hit.key}\``),
+            ]));
+        }
+    }
+    if (report.status === 'not-found')
+        lines.push('', '未命中精确节点；检索基于已注册声明和名称，尝试更短的中文词或代码标识。');
+    return [...lines, ...reportFooter(report)].join('\n');
+}
+//# sourceMappingURL=graph-query.js.map

package/dist/graph-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-query.js","sourceRoot":"","sources":["../src/graph-query.ts"],"names":[],"mappings":"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"}

package/dist/graph-relations.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 将每种本体连线翻译为中文原因、用途、方向与证据，供 CLI 和浏览器详情复用。
+ * 解释基于投影端点及已抽取属性，分别标注显式声明、规则推导与文本匹配。
+ * 不求值 handler、映射或审批条件；存在连线只代表对应声明关系，不证明某次操作已发生。
+ */
+import { type GraphModel, type ViewEdge, type ViewNode } from './graph-model.js';
+/** 解释来自已抽取的声明，不借连线猜测运行结果。尤其要区分“允许读取”、
+ * “声明依赖”和“事件触发”，否则图谱很容易被误读为一张执行时序图。 */
+export interface RelationExplanation {
+    /** 适合连线显示的中文短名。 */
+    label: string;
+    /** 关系类别文案，用于解释栏分组。 */
+    category: string;
+    /** 本关系存在的声明原因。 */
+    why: string;
+    /** 维护时应如何理解或检查这条关系。 */
+    purpose: string;
+    /** 按源端到目标端阅读的中文语句。 */
+    direction: string;
+    /** 可阅读的声明片段或推导规则列表。 */
+    evidence: string[];
+    /** 用于定位主要证据的节点，不一定等于连线源端。 */
+    source: ViewNode;
+    /** declared 为直接声明，inferred 为标识推导，text-match 为文本候选。 */
+    basis: 'declared' | 'inferred' | 'text-match';
+}
+/**
+ * 按真实关系种类解释连线，补充声明来源和证据强度。
+ * @param edge 已投影且两端有效的边。
+ * @param model 展示图，提供端点和辅助声明。
+ * @param labels 中文名称覆盖。
+ * @returns 中文解释；只读元数据，不执行审批、映射、查询或业务命令。
+ */
+export declare function explainEdge(edge: ViewEdge, model: GraphModel, labels?: Record<string, string>): RelationExplanation;

package/dist/graph-relations.js

@@ -0,0 +1,172 @@
+/**
+ * 将每种本体连线翻译为中文原因、用途、方向与证据，供 CLI 和浏览器详情复用。
+ * 解释基于投影端点及已抽取属性，分别标注显式声明、规则推导与文本匹配。
+ * 不求值 handler、映射或审批条件；存在连线只代表对应声明关系，不证明某次操作已发生。
+ */
+import { kindLabels, nodeLabel } from './graph-model.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);
+    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 '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 中的集合关系，不占主表列；点击它指向目标的连线，查看关系基数、存储和读写方式。'
+                : '说明业务对象由哪些数据组成；调整字段时，可以继续沿线查看受影响的查询、审批和事件。', [`${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 !== 'when' ? [n] : n.steps))
+                    .filter((s) => (s.approver ?? s.handoff)?.kind === 'deptLeader' && (s.approver ?? s.handoff)?.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);
+            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 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':
+            return result('允许调用命令', '任务调用范围', `“${a}”在 calls 中声明可以调用“${b}”。`, '明确任务能执行哪些业务写入，并支持影响分析。每次任务是否实际调用该命令，取决于 run 中的业务逻辑。', [`${from.id}.calls → ${to.id}`]);
+    }
+}
+//# sourceMappingURL=graph-relations.js.map

package/dist/graph-relations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-relations.js","sourceRoot":"","sources":["../src/graph-relations.ts"],"names":[],"mappings":"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"}

package/dist/graph-search.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 不依赖模型的本体名称检索，供 CLI、agent 上下文和浏览器筛选共用。
+ * 归一化标识与文案，按完整命中或英文词、相邻中文片段计算权重，并返回命中字段。
+ * 结果是稳定排序的候选；不进行语义推理，无法保证理解否定、业务同义词或任意自然语言要求。
+ */
+import { type GraphModel, type ViewNode } from './graph-model.js';
+/**
+ * 一次命中说明，保存字段原值和实际匹配片段，便于 agent 核对候选来源。
+ */
+export interface SearchMatch {
+    /** 实际命中的索引字段，用来解释召回依据。 */
+    field: 'key' | 'id' | 'label' | 'description' | 'owner';
+    /** 被命中的原始索引文本。 */
+    value: string;
+    /** 本次查询中命中的词项，不代表全文语义等价。 */
+    terms: string[];
+}
+/**
+ * 可解释检索候选，score 只是当前权重排名，不是语义置信概率。
+ */
+export interface GraphSearchHit {
+    /** 完整节点身份，可用于后续 inspect/context 精确查询。 */
+    key: string;
+    /** 领域原始标识。 */
+    id: string;
+    /** 展示节点类型。 */
+    kind: ViewNode['kind'];
+    /** 节点中文显示名。 */
+    label: string;
+    /** 当前词法检索的排序分数，仅用于同次结果比较。 */
+    score: number;
+    /** 各字段的命中证据，支持 agent 评估候选相关性。 */
+    matches: SearchMatch[];
+}
+/** 排序稳定，结果携带命中字段；多个候选不静默合成一个“正确需求”。 */
+/**
+ * 按可选类型筛选并稳定排序名称候选。
+ * @param model 展示图。
+ * @param query 关键词。
+ * @param labels 中文覆盖。
+ * @param options 类型范围及原始描述。
+ * @returns 完整候选数组，调用方负责 limit 和截断提示。
+ */
+export declare function searchGraphNodes(model: GraphModel, query: string, labels?: Record<string, string>, options?: {
+    kind?: ViewNode['kind'];
+    descriptions?: Record<string, string>;
+}): GraphSearchHit[];
+/** 画布的筛选与搜索下拉共用同一匹配规则，保留按节点类型查找的用法。 */
+/**
+ * 供画布筛选复用名称匹配，并额外允许按中文类型名称筛选。
+ * @param node 展示节点。
+ * @param query 筛选文字。
+ * @param labels 中文映射。
+ * @returns 是否命中；空查询可匹配类型名称，不修改图。
+ */
+export declare function matchesNode(node: ViewNode, query: string, labels: Record<string, string>): boolean;