@yss123/cage-cli 0.1.0 → 0.3.0

package/dist/graph-search.js

@@ -0,0 +1,99 @@
+/**
+ * 不依赖模型的本体名称检索，供 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) ?? []) {
+        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)];
+}
+/**
+ * 对 key、ID、中文文案、原描述及所属对象分别评分，取最高单字段得分。
+ * @param node 待匹配节点。
+ * @param query 用户输入。
+ * @param labels 显示覆盖。
+ * @param descriptions 声明原始描述。
+ * @returns 有依据的候选或 undefined；所有命中字段仍保留，不把分数当业务证明。
+ */
+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 };
+}
+/** 排序稳定，结果携带命中字段；多个候选不静默合成一个“正确需求”。 */
+/**
+ * 按可选类型筛选并稳定排序名称候选。
+ * @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)
+        .map((node) => matchNode(node, query, labels, options.descriptions ?? {}))
+        .filter((hit) => !!hit)
+        .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));
+}
+//# sourceMappingURL=graph-search.js.map

package/dist/graph-search.js.map

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

package/dist/graph-snapshot.d.ts

@@ -1,13 +1,37 @@
 import type { Finding } from './findings.js';
 import type { Ontology } from './ontology.js';
+import { type GraphPresentation } from './graph-presentation.js';
+/**
+ * 单次独立进程抽取的完整快照，图、问题、标签和可选代码片段属于同一时刻。
+ */
 export interface GraphSnapshot {
+    /** 项目显示名称。 */
     project: string;
+    /** 本次加载的领域入口路径。 */
     domain: string;
+    /** 本次抽取完成时间的 ISO 字符串。 */
     generatedAt: string;
+    /** 单次抽取所得语义本体。 */
     graph: Ontology;
+    /** 静态和图规则诊断，图可展示时也需保留错误。 */
     findings: Finding[];
-    presentation: {
-        title: string;
-        labels: Record<string, string>;
-    };
+    /** 不参与业务身份的中文标题和描述索引。 */
+    presentation: GraphPresentation;
+    /** 仅保存在本地抽取快照；HTTP 按节点提供，不能接受任意文件路径。 */
+    sources?: Record<string, GraphSource>;
+}
+/**
+ * 静态扫描保存的声明源码片段，供按已注册节点读取，行号为一基。
+ */
+export interface GraphSource {
+    /** 已索引声明所在的项目相对路径。 */
+    file: string;
+    /** 源码片段起始行，从 1 计数。 */
+    line: number;
+    /** 源码片段终止行，从 1 计数并包含末行。 */
+    endLine: number;
+    /** 当前源码声明的导出名称。 */
+    exportName: string;
+    /** 允许展示的声明片段；服务按已知节点读取此值。 */
+    code: string;
 }

package/dist/graph-snapshot.js

@@ -1,31 +1,24 @@
+/**
+ * 独立抽取子进程的入口，由 collectGraph fork 启动并通过 IPC 交付快照。
+ * 加载指定应用配置，分析声明后同时保存语义图、展示标签、发现的问题及注册声明代码片段。
+ * 普通导入不刷新 ESM 依赖缓存，因此每次抽取使用新进程；只交付本次已读源码，不开放任意路径读取。
+ */
 // 图谱每次刷新都在独立进程抽取。ESM 会缓存 domain 及其依赖；只给入口添加
 // 时间戳无法刷新所有间接导入，因此不在常驻 Web 服务里重复 import domain。
 import { analyze } from './analyze.js';
 import { loadConfig } from './config.js';
+import { graphPresentation } from './graph-presentation.js';
+/**
+ * 按子进程参数加载应用并通过 IPC 交付一次快照。
+ * 静态错误导致没有图时抛出；可抽取的图规则错误仍随 findings 交付。
+ * 完成发送后由入口断开 IPC；不监听业务文件，也不执行具体命令。
+ */
 async function collect() {
     const cfg = loadConfig(process.argv[2]);
-    const result = await analyze(cfg, { write: true });
+    const result = await analyze(cfg);
     if (!result.graph) {
         throw new Error(result.findings.map((f) => `[${f.code}] ${f.reason}`).join('\n'));
     }
-    // 优先复用声明已有的描述。图谱文案单独传递，不给本体节点改名或改哈希，
-    // 避免一次中文标题调整被误认为命令、能力点或数据库结构发生变化。
-    const labels = {};
-    const remember = (kind, id, description) => {
-        if (description)
-            labels[`${kind}:${id}`] = description;
-    };
-    const registry = result.registry;
-    for (const a of registry.aggregates)
-        remember('aggregate', a.name, a.description);
-    for (const c of registry.commands)
-        remember('command', c.capability, c.cmd.description);
-    for (const e of registry.events)
-        remember('event', e.name, e.description);
-    for (const q of registry.queries)
-        remember('query', q.name, q.description);
-    for (const j of registry.jobs)
-        remember('job', j.name, j.description);
     // 有图规则问题时仍展示图和问题列表，开发者可以借助关系图定位错误。
     const snapshot = {
         project: cfg.name,
@@ -33,7 +26,26 @@ async function collect() {
         generatedAt: new Date().toISOString(),
         graph: result.graph,
         findings: result.findings,
-        presentation: { title: cfg.graph?.title ?? cfg.name, labels: { ...labels, ...cfg.graph?.labels } },
+        presentation: graphPresentation(cfg, result.registry),
+        // 复用本次静态检查已读到的声明，预览和图谱始终对应同一时刻；
+        // 请求代码时不重新读磁盘，避免旧行号错指及任意文件读取。
+        sources: Object.fromEntries(result.graph.nodes.flatMap((node) => {
+            const site = result.source.sites.find((s) => s.file === node.file && s.line === node.line);
+            return site
+                ? [
+                    [
+                        `${node.kind}:${node.id}`,
+                        {
+                            file: site.file,
+                            line: site.line,
+                            endLine: site.line + site.text.split('\n').length - 1,
+                            exportName: site.exportName,
+                            code: site.text,
+                        },
+                    ],
+                ]
+                : [];
+        })),
     };
     process.send({ snapshot });
 }

package/dist/graph-snapshot.js.map

@@ -1 +1 @@
-{"version":3,"file":"graph-snapshot.js","sourceRoot":"","sources":["../src/graph-snapshot.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,gDAAgD;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAazC,KAAK,UAAU,OAAO;IACpB,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACnD,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACpF,CAAC;IACD,qCAAqC;IACrC,kCAAkC;IAClC,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAE,EAAU,EAAE,WAAoB,EAAE,EAAE;QAClE,IAAI,WAAW;YAAE,MAAM,CAAC,GAAG,IAAI,IAAI,EAAE,EAAE,CAAC,GAAG,WAAW,CAAC;IACzD,CAAC,CAAC;IACF,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAS,CAAC;IAClC,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,UAAU;QAAE,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC;IAClF,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,QAAQ;QAAE,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACxF,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,MAAM;QAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC;IAC1E,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,OAAO;QAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC;IAC3E,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,IAAI;QAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC;IACtE,mCAAmC;IACnC,MAAM,QAAQ,GAAkB;QAC9B,OAAO,EAAE,GAAG,CAAC,IAAI;QACjB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACrC,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,YAAY,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,KAAK,IAAI,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,GAAG,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;KACnG,CAAC;IACF,OAAO,CAAC,IAAK,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED,OAAO,EAAE;KACN,KAAK,CAAC,CAAC,KAAY,EAAE,EAAE;IACtB,OAAO,CAAC,IAAK,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IACxC,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC;KACD,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC"}
+{"version":3,"file":"graph-snapshot.js","sourceRoot":"","sources":["../src/graph-snapshot.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,4CAA4C;AAC5C,gDAAgD;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,EAAE,iBAAiB,EAA0B,MAAM,yBAAyB,CAAC;AAsCpF;;;;GAIG;AACH,KAAK,UAAU,OAAO;IACpB,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACpF,CAAC;IACD,mCAAmC;IACnC,MAAM,QAAQ,GAAkB;QAC9B,OAAO,EAAE,GAAG,CAAC,IAAI;QACjB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACrC,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,YAAY,EAAE,iBAAiB,CAAC,GAAG,EAAE,MAAM,CAAC,QAAS,CAAC;QACtD,gCAAgC;QAChC,8BAA8B;QAC9B,OAAO,EAAE,MAAM,CAAC,WAAW,CACzB,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;YAClC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,CAAC,CAAC;YAC3F,OAAO,IAAI;gBACT,CAAC,CAAC;oBACE;wBACE,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,EAAE,EAAE;wBACzB;4BACE,IAAI,EAAE,IAAI,CAAC,IAAI;4BACf,IAAI,EAAE,IAAI,CAAC,IAAI;4BACf,OAAO,EAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC;4BACrD,UAAU,EAAE,IAAI,CAAC,UAAU;4BAC3B,IAAI,EAAE,IAAI,CAAC,IAAI;yBAChB;qBACF;iBACF;gBACH,CAAC,CAAC,EAAE,CAAC;QACT,CAAC,CAAC,CACH;KACF,CAAC;IACF,OAAO,CAAC,IAAK,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED,OAAO,EAAE;KACN,KAAK,CAAC,CAAC,KAAY,EAAE,EAAE;IACtB,OAAO,CAAC,IAAK,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IACxC,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC;KACD,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC"}

package/dist/graph.d.ts

@@ -2,9 +2,20 @@ import type { CageConfig } from './config.js';
 import type { GraphSnapshot } from './graph-snapshot.js';
 /** 只采集声明元数据，不连接业务数据库。子进程的 IPC 把日志和 JSON 分开，
  * domain 的普通日志不会污染响应，也不会把进程环境变量发送给浏览器。 */
+/**
+ * fork 独立快照进程以绕开 ESM 缓存，使用 IPC 避免普通日志污染 JSON。
+ * @param root 应用目录，传给子进程。
+ * @returns 快照 Promise；启动、抽取或无结果退出导致拒绝，不连接业务数据库。
+ */
 export declare function collectGraph(root: string): Promise<GraphSnapshot>;
-/** 本地开发工具只监听回环地址；固定路由表不接受文件路径，不能拿来读取
- * 项目的 .env、源码或任意本机文件。它不挂载到业务 API 或生产 /admin。 */
+/** 本地开发工具只监听回环地址；源码预览只提供抽取快照内的注册声明，
+ * 固定路由不接受文件路径。它不挂载到业务 API 或生产 /admin。 */
+/**
+ * 先抽取再启动本地图谱服务，并缓存可显式刷新的快照。
+ * @param cfg 应用配置。
+ * @param port 默认 15418，0 可由系统分配空闲端口。
+ * @returns HTTP server 与实际 URL，调用方负责关闭；仅监听回环，不提供任意文件读取。
+ */
 export declare function serveGraph(cfg: CageConfig, port?: number): Promise<{
     server: import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>;
     url: string;

package/dist/graph.js

@@ -1,9 +1,20 @@
+/**
+ * 本地图谱 HTTP 服务与独立抽取进程的管理层，由 cage graph 或查询命令调用。
+ * 抽取结果通过 IPC 传递，服务缓存当前快照，固定路由提供静态资源、节点源码和上下文。
+ * 仅监听回环地址并校验 Host/刷新来源；这是开发工具，不属于业务 API，刷新失败不会伪装成新快照。
+ */
 import { fork } from 'node:child_process';
 import { readFile } from 'node:fs/promises';
 import { createServer } from 'node:http';
 import { fileURLToPath } from 'node:url';
+import { buildContext, formatContext } from './context.js';
 /** 只采集声明元数据，不连接业务数据库。子进程的 IPC 把日志和 JSON 分开，
  * domain 的普通日志不会污染响应，也不会把进程环境变量发送给浏览器。 */
+/**
+ * fork 独立快照进程以绕开 ESM 缓存，使用 IPC 避免普通日志污染 JSON。
+ * @param root 应用目录，传给子进程。
+ * @returns 快照 Promise；启动、抽取或无结果退出导致拒绝，不连接业务数据库。
+ */
 export function collectGraph(root) {
     return new Promise((resolve, reject) => {
         const child = fork(fileURLToPath(new URL('./graph-snapshot.js', import.meta.url)), [root], {
@@ -24,8 +35,14 @@ export function collectGraph(root) {
         child.once('exit', (code) => reject(new Error(failure || `本体抽取进程退出（${code}）`)));
     });
 }
-/** 本地开发工具只监听回环地址；固定路由表不接受文件路径，不能拿来读取
- * 项目的 .env、源码或任意本机文件。它不挂载到业务 API 或生产 /admin。 */
+/** 本地开发工具只监听回环地址；源码预览只提供抽取快照内的注册声明，
+ * 固定路由不接受文件路径。它不挂载到业务 API 或生产 /admin。 */
+/**
+ * 先抽取再启动本地图谱服务，并缓存可显式刷新的快照。
+ * @param cfg 应用配置。
+ * @param port 默认 15418，0 可由系统分配空闲端口。
+ * @returns HTTP server 与实际 URL，调用方负责关闭；仅监听回环，不提供任意文件读取。
+ */
 export async function serveGraph(cfg, port = 15418) {
     let snapshot = await collectGraph(cfg.root);
     let refreshing;
@@ -35,7 +52,17 @@ export async function serveGraph(cfg, port = 15418) {
         ['/model.js', ['model.js', 'text/javascript; charset=utf-8']],
         ['/relations.js', ['relations.js', 'text/javascript; charset=utf-8']],
         ['/structure.js', ['structure.js', 'text/javascript; charset=utf-8']],
+        ['/approval-flow.js', ['approval-flow.js', 'text/javascript; charset=utf-8']],
+        ['/graph-approvals.js', ['graph-approvals.js', 'text/javascript; charset=utf-8']],
+        ['/graph-model.js', ['graph-model.js', 'text/javascript; charset=utf-8']],
+        ['/graph-relations.js', ['graph-relations.js', 'text/javascript; charset=utf-8']],
+        ['/graph-search.js', ['graph-search.js', 'text/javascript; charset=utf-8']],
+        ['/graph-business.js', ['graph-business.js', 'text/javascript; charset=utf-8']],
+        ['/business.js', ['business.js', 'text/javascript; charset=utf-8']],
+        ['/flowchart.js', ['flowchart.js', 'text/javascript; charset=utf-8']],
+        ['/flowchart-interaction.js', ['flowchart-interaction.js', 'text/javascript; charset=utf-8']],
         ['/style.css', ['style.css', 'text/css; charset=utf-8']],
+        ['/business.css', ['business.css', 'text/css; charset=utf-8']],
     ]);
     let origin = '';
     const server = createServer(async (req, res) => {
@@ -49,10 +76,56 @@ export async function serveGraph(cfg, port = 15418) {
         // 限制 Host 和刷新来源，避免其他网站借用户浏览器触发本地模块求值。
         if (req.headers.host !== new URL(origin).host)
             return json(403, { error: '请使用终端输出的本地地址访问' });
-        const path = new URL(req.url, origin).pathname;
+        const requestUrl = new URL(req.url, origin);
+        const path = requestUrl.pathname;
         try {
+            // 默认响应仍是声明元数据；实现代码由用户打开具体节点后单独请求。
+            const displayedSnapshot = () => {
+                const { sources, ...displayed } = snapshot;
+                return displayed;
+            };
             if (req.method === 'GET' && path === '/api/graph')
-                return json(200, snapshot);
+                return json(200, displayedSnapshot());
+            if (req.method === 'GET' && path === '/api/source') {
+                const key = requestUrl.searchParams.get('node');
+                if (!key)
+                    return json(400, { error: '需要完整节点 key' });
+                const node = snapshot.graph.nodes.find((n) => `${n.kind}:${n.id}` === key);
+                if (!node)
+                    return json(404, { error: '当前图谱中没有这个节点' });
+                const owner = ['field', 'state', 'capability'].includes(node.kind)
+                    ? snapshot.graph.nodes
+                        .filter((n) => n.kind === 'aggregate' && node.id.startsWith(`${n.id}.`))
+                        .sort((a, b) => b.id.length - a.id.length)[0]
+                    : undefined;
+                const sourceKey = node.file ? key : owner ? `${owner.kind}:${owner.id}` : key;
+                const source = snapshot.sources?.[sourceKey];
+                if (!source)
+                    return json(404, {
+                        error: '该声明来自依赖包，或当前快照没有项目源码；可在完整本体中查看声明属性。',
+                    });
+                return json(200, {
+                    ...source,
+                    nodeKey: key,
+                    sourceKey,
+                    precision: sourceKey === key ? 'declaration' : 'aggregate',
+                    extractedAt: snapshot.generatedAt,
+                    freshness: 'displayed-snapshot',
+                });
+            }
+            if (req.method === 'GET' && path === '/api/context') {
+                const node = requestUrl.searchParams.get('node');
+                const format = requestUrl.searchParams.get('format') ?? 'json';
+                if (!node?.trim() || !['json', 'md'].includes(format))
+                    return json(400, { error: '需要 node 参数；format 只能是 json 或 md' });
+                // 使用页面已有快照，时间与来源随报告交付；要看代码最新状态应先重新抽取。
+                const context = buildContext(cfg, snapshot, node, { freshness: 'displayed-snapshot' });
+                if (format === 'json')
+                    return json(200, context);
+                res.writeHead(200, { 'Content-Type': 'text/markdown; charset=utf-8' });
+                res.end(formatContext(context));
+                return;
+            }
             if (req.method === 'POST' && path === '/api/refresh') {
                 if (req.headers.origin !== origin)
                     return json(403, { error: '刷新必须由本地图谱页面发起' });
@@ -61,7 +134,7 @@ export async function serveGraph(cfg, port = 15418) {
                     refreshing = undefined;
                 });
                 snapshot = await refreshing;
-                return json(200, snapshot);
+                return json(200, displayedSnapshot());
             }
             const asset = req.method === 'GET' ? assets.get(path) : undefined;
             if (!asset)

package/dist/graph.js.map

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

package/dist/impact.d.ts

@@ -1,25 +1,81 @@
 import type { DerivedTest } from './derive.js';
 import { type NodeDiff, type Ontology } from './ontology.js';
 import type { Finding } from './findings.js';
+/**
+ * 本体差异、受影响主体、候选测试及人工复核提示；不包含执行测试后的通过结论。
+ */
 export interface ImpactResult {
+    /** 按节点身份和哈希计算的增删改。 */
     diff: NodeDiff;
+    /** 直接变化或改动文件映射得到的起点 ID。 */
     start: string[];
+    /** 沿相关新旧关系传播得到的受影响 ID。 */
     affected: string[];
     /** 受影响节点 → 通过哪条边、以什么身份受影响 */
     reasons: Map<string, string>;
+    /** 按 subject 命中的派生验证候选，尚未执行。 */
     tests: DerivedTest[];
+    /** 调用方提供且匹配到主体名称的项目测试文件。 */
     projectTests: string[];
+    /** 需要人工或额外证据确认的授权、外部兼容等事项。 */
     confirm: string[];
+    /** 基线与当前 unsafe 使用数量，不表示每一处风险已审查。 */
     unsafe: {
         base: number;
         head: number;
     };
+    /** 事件兼容等影响规则发现。 */
     findings: Finding[];
 }
+/**
+ * 只读判断当前目录是否处于 Git 工作树。
+ * @param root 检查目录。
+ * @returns rev-parse 成功且为 true 时真，失败时假。
+ */
 export declare function isGitRepo(root: string): boolean;
+/**
+ * 汇总基线至 HEAD、暂存、未暂存与未跟踪文件名。
+ * @param root 应用目录。
+ * @param base Git 比较基线。
+ * @returns 去重文件名；单次 Git 查询失败按该部分无结果处理，不负责验证基线有效性。
+ */
 export declare function changedFiles(root: string, base: string): string[];
+/**
+ * 读取本体 JSON 或带 graph 的快照信封并检查基础形状。
+ * @param path 文件路径。
+ * @returns version=1 的本体；形状、读取或 JSON 错误抛出，不做完整节点语义校验。
+ */
 export declare function readOntology(path: string): Ontology;
+/** 影响分析与开发前上下文共用测试候选选择。项目测试只按源码里的名字匹配，
+ * 调用方必须标明它是线索，不能据此声称已找到全部需要执行的测试。 */
+/**
+ * 选择主体相关派生用例和源码名称命中的项目测试。
+ * @param subjects 受影响主体 ID 集合。
+ * @param tests 派生索引。
+ * @param projectTestFiles 调用方提供的候选文件；不存在的已删文件忽略。
+ * @returns 测试候选，不代表完整覆盖或已执行；短于三字符的名称不匹配项目测试。
+ */
+export declare function selectRelatedTests(subjects: ReadonlySet<string>, tests: DerivedTest[], projectTestFiles: string[]): {
+    derived: DerivedTest[];
+    project: string[];
+};
+/**
+ * 比较节点哈希并沿新旧边传播影响，保留已删除节点的旧消费者。
+ * @param base 修改前本体。
+ * @param head 当前本体。
+ * @param files 额外变化文件，映射到其中声明。
+ * @param tests 派生测试索引，默认空。
+ * @param projectTestFiles 需要调用方传入的项目测试路径，默认空。
+ * @returns 变化、影响理由和复核项；不运行测试或验证真实外部系统。
+ */
 export declare function impact(base: Ontology, head: Ontology, files: string[], tests?: DerivedTest[], projectTestFiles?: string[]): ImpactResult;
+/**
+ * 渲染本体变化摘要、影响范围、候选计数与兼容提示。
+ * @param r impact 结果。
+ * @param head 当前图用于查中文类别及属性。
+ * @param opts 文本/Markdown 格式和可选标题、门禁描述。
+ * @returns 报告文本；候选数量不等于测试完成或全覆盖。
+ */
 export declare function formatImpact(r: ImpactResult, head: Ontology, opts: {
     base: string;
     format: 'text' | 'md';