spectra-cli 4.1.1 → 4.3.0

package/dist/mcp/lib/telemetry.js

@@ -0,0 +1,113 @@
+/**
+ * Feature 158 — MCP Telemetry（从 agent-context-tools.ts 抽出，Feature 171）
+ *
+ * 抽到独立模块的动机（Feature 171 Codex TELEMETRY-COUPLING）：
+ *   file-nav-tools.ts 需复用 recordAndReturn，若从 agent-context-tools.ts import
+ *   会把整个 graph 查询依赖图拉进来。抽到本轻量模块后 file-nav 只依赖 tool-response + telemetry。
+ *
+ * agent-context-tools.ts 保留向后兼容 re-export（既有 telemetry.test.ts 从该路径 import）。
+ */
+import { appendFileSync } from 'node:fs';
+import { buildErrorResponse } from './tool-response.js';
+/**
+ * 写入 telemetry JSONL —— 静默降级：
+ *   - env 未设置 → no-op
+ *   - 写入失败 → 静默吞，不影响 MCP response
+ */
+export function writeTelemetry(entry) {
+    const telPath = process.env['SPECTRA_MCP_TELEMETRY_PATH'];
+    if (telPath === undefined || telPath.length === 0)
+        return;
+    try {
+        appendFileSync(telPath, JSON.stringify(entry) + '\n', 'utf-8');
+    }
+    catch {
+        // FR-G-002: silent degrade — 写入失败时不抛异常，不影响 handler 返回
+    }
+}
+/**
+ * 从 ToolResult 中提取 errorCode（仅 isError=true 时存在）。
+ * 解析失败时返回 undefined（telemetry 字段缺省）。
+ */
+export function extractErrorCode(result) {
+    if (result.isError !== true)
+        return undefined;
+    const text = result.content?.[0]?.text;
+    if (typeof text !== 'string')
+        return undefined;
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed.code === 'string' ? parsed.code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Wrapper：记录 handler 调用 telemetry 后返回原 result。
+ * 包裹所有 return 路径（含 buildErrorResponse 早 return）。
+ */
+export function recordAndReturn(toolName, startTimeMs, requestSize, result, responseSummary, responseSamples) {
+    const responseText = result.content?.[0]?.text ?? '';
+    const responseSize = typeof responseText === 'string' ? Buffer.byteLength(responseText, 'utf-8') : 0;
+    const entry = {
+        ts: new Date().toISOString(),
+        toolName,
+        requestSize,
+        responseSize,
+        durationMs: Date.now() - startTimeMs,
+        runId: process.env['SPECTRA_MCP_RUN_ID'] ?? 'unknown',
+    };
+    const errorCode = extractErrorCode(result);
+    if (errorCode !== undefined)
+        entry.errorCode = errorCode;
+    if (responseSummary !== undefined && errorCode === undefined) {
+        entry.responseSummary = responseSummary;
+    }
+    if (responseSamples !== undefined && errorCode === undefined) {
+        entry.responseSamples = responseSamples;
+    }
+    writeTelemetry(entry);
+    return result;
+}
+/**
+ * Feature 177 — 注册层 telemetry 装饰器。
+ *
+ * 把 F158 telemetry 采样从"handler 内部自调 recordAndReturn"推广到**注册层**，
+ * 用于无富采样需求（responseSummary/responseSamples）的工具（graph 6 + server 5 共 11 个）。
+ *
+ * 职责：
+ *   1. 入口记 start / requestSize
+ *   2. 出口经 recordAndReturn 透传（含 errorCode 提取）
+ *   3. 顶层未预期异常 → 脱敏 internal-error 安全网（不泄漏 err.message/stack，spec C-4）
+ *
+ * 不变量（spec AD-1 双源分区）：被本装饰器包裹的工具**不得**在 handler 内再调 recordAndReturn；
+ * 已在 handler 内自采样的工具（agent-context / file-nav）**不得**被本装饰器包裹。
+ * → 每个到达 handler 的调用恰写 1 行 telemetry（锁死双发射 EC-1）。
+ *
+ * 范围（spec EC-10）：MCP SDK 在 handler 前的 schema 校验失败走 SDK 自身错误，
+ * 不进入本装饰器，不在 F177 telemetry 覆盖范围内。
+ *
+ * 不接受泛型（YAGNI）：args 用 unknown；SDK 传入的 extra 形参被忽略（17 工具均不用 extra）。
+ */
+export function withTelemetry(toolName, handler) {
+    return async (args) => {
+        const startTimeMs = Date.now();
+        let requestSize = 0;
+        try {
+            requestSize = JSON.stringify(args).length;
+        }
+        catch {
+            // 循环引用等无法序列化 → requestSize 记 0
+        }
+        try {
+            const result = await handler(args);
+            return recordAndReturn(toolName, startTimeMs, requestSize, result);
+        }
+        catch {
+            // 顶层未预期异常 → 脱敏 internal-error（不回传 err.message/stack）
+            return recordAndReturn(toolName, startTimeMs, requestSize, buildErrorResponse('internal-error', `${toolName} 内部错误`));
+        }
+    };
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/mcp/lib/telemetry.js.map

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

package/dist/mcp/lib/tool-response.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Feature 171 — MCP 共享响应原语（tool-response）
+ *
+ * 从 agent-context-tools.ts 抽出的共享层，解决 Feature 171 Codex C-4：
+ *   ToolResult / ErrorCode / buildErrorResponse / buildSuccessResponse / PAYLOAD_CAP_BYTES
+ *   原为 agent-context-tools.ts 私有符号，file-nav-tools.ts 无法复用。
+ * 抽到本模块后 agent-context-tools 与 file-nav 双向导入（去重，非污染）。
+ *
+ * ErrorCode union 在既有 9 码基础上新增 Feature 171 的 3 码：
+ *   path-outside-root / binary-file / file-not-found
+ */
+/** 统一错误码（Feature 155 既有 9 码 + Feature 171 新增 3 码） */
+export type ErrorCode = 'graph-not-built' | 'symbol-not-found' | 'invalid-symbol-id' | 'invalid-input' | 'invalid-diff' | 'payload-too-large' | 'git-spawn-failed' | 'git-timeout' | 'internal-error' | 'path-outside-root' | 'binary-file' | 'file-not-found' | 'graph-query-failed' | 'graph-format-stale';
+/** MCP tool 统一响应 envelope */
+export interface ToolResult {
+    [key: string]: unknown;
+    content: Array<{
+        type: 'text';
+        text: string;
+        [key: string]: unknown;
+    }>;
+    isError?: true;
+}
+/**
+ * 构造错误响应 envelope。
+ * 调用方负责脱敏：message/hint/context 不得包含绝对路径、stack、raw errno path
+ * （Feature 171 FR-014）。
+ */
+export declare function buildErrorResponse(code: ErrorCode, message: string, hint?: string, context?: Record<string, unknown>): ToolResult;
+/** payload 字节上限：超限时截断可截断数组并加 payload-truncated warning */
+export declare const PAYLOAD_CAP_BYTES = 1000000;
+/**
+ * 构造成功响应 envelope。
+ * 当序列化超 PAYLOAD_CAP_BYTES 且提供了 truncatableArrayKeys 时，
+ * 按比例收缩这些数组并追加 warnings 含 'payload-truncated'。
+ *
+ * 注意：本函数始终返回 success（不返回 payload-too-large）。
+ * 若收缩后仍超 cap，由调用方（handler）复核 byteLength 后决定是否改返 payload-too-large。
+ */
+export declare function buildSuccessResponse(data: Record<string, unknown>, truncatableArrayKeys?: string[], warningsKey?: string): ToolResult;
+/**
+ * 复核 ToolResult 的序列化字节是否仍超 cap（Feature 171 FR-021）。
+ * handler 在 buildSuccessResponse 收缩后调用本函数，仍超则改返 payload-too-large。
+ */
+export declare function exceedsPayloadCap(result: ToolResult): boolean;
+//# sourceMappingURL=tool-response.d.ts.map

package/dist/mcp/lib/tool-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-response.d.ts","sourceRoot":"","sources":["../../../src/mcp/lib/tool-response.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,qDAAqD;AACrD,MAAM,MAAM,SAAS,GAEjB,iBAAiB,GACjB,kBAAkB,GAClB,mBAAmB,GACnB,eAAe,GACf,cAAc,GACd,mBAAmB,GACnB,kBAAkB,GAClB,aAAa,GACb,gBAAgB,GAEhB,mBAAmB,GACnB,aAAa,GACb,gBAAgB,GAGhB,oBAAoB,GAGpB,oBAAoB,CAAC;AAEzB,6BAA6B;AAC7B,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,CAAC;IACvE,OAAO,CAAC,EAAE,IAAI,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,UAAU,CAQZ;AAED,0DAA0D;AAC1D,eAAO,MAAM,iBAAiB,UAAY,CAAC;AAE3C;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,oBAAoB,GAAE,MAAM,EAAO,EACnC,WAAW,GAAE,MAAmB,GAC/B,UAAU,CAkCZ;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAG7D"}

package/dist/mcp/lib/tool-response.js

@@ -0,0 +1,83 @@
+/**
+ * Feature 171 — MCP 共享响应原语（tool-response）
+ *
+ * 从 agent-context-tools.ts 抽出的共享层，解决 Feature 171 Codex C-4：
+ *   ToolResult / ErrorCode / buildErrorResponse / buildSuccessResponse / PAYLOAD_CAP_BYTES
+ *   原为 agent-context-tools.ts 私有符号，file-nav-tools.ts 无法复用。
+ * 抽到本模块后 agent-context-tools 与 file-nav 双向导入（去重，非污染）。
+ *
+ * ErrorCode union 在既有 9 码基础上新增 Feature 171 的 3 码：
+ *   path-outside-root / binary-file / file-not-found
+ */
+/**
+ * 构造错误响应 envelope。
+ * 调用方负责脱敏：message/hint/context 不得包含绝对路径、stack、raw errno path
+ * （Feature 171 FR-014）。
+ */
+export function buildErrorResponse(code, message, hint, context) {
+    const payload = { code, message };
+    if (hint !== undefined)
+        payload['hint'] = hint;
+    if (context !== undefined)
+        payload['context'] = context;
+    return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify(payload) }],
+    };
+}
+/** payload 字节上限：超限时截断可截断数组并加 payload-truncated warning */
+export const PAYLOAD_CAP_BYTES = 1_000_000;
+/**
+ * 构造成功响应 envelope。
+ * 当序列化超 PAYLOAD_CAP_BYTES 且提供了 truncatableArrayKeys 时，
+ * 按比例收缩这些数组并追加 warnings 含 'payload-truncated'。
+ *
+ * 注意：本函数始终返回 success（不返回 payload-too-large）。
+ * 若收缩后仍超 cap，由调用方（handler）复核 byteLength 后决定是否改返 payload-too-large。
+ */
+export function buildSuccessResponse(data, truncatableArrayKeys = [], warningsKey = 'warnings') {
+    let text = JSON.stringify(data);
+    let bytes = Buffer.byteLength(text, 'utf-8');
+    if (bytes > PAYLOAD_CAP_BYTES && truncatableArrayKeys.length > 0) {
+        let truncated = false;
+        let safety = 0;
+        while (bytes > PAYLOAD_CAP_BYTES && safety < 8) {
+            safety++;
+            let progressed = false;
+            for (const key of truncatableArrayKeys) {
+                const arr = data[key];
+                if (!Array.isArray(arr) || arr.length === 0)
+                    continue;
+                // 按比例 0.7 收缩，至少减 1
+                const ratio = PAYLOAD_CAP_BYTES / bytes;
+                const newLen = Math.max(0, Math.min(arr.length - 1, Math.floor(arr.length * ratio * 0.7)));
+                if (newLen < arr.length) {
+                    data[key] = arr.slice(0, newLen);
+                    truncated = true;
+                    progressed = true;
+                }
+            }
+            if (!progressed)
+                break;
+            text = JSON.stringify(data);
+            bytes = Buffer.byteLength(text, 'utf-8');
+        }
+        if (truncated) {
+            const warnings = data[warningsKey] ?? [];
+            if (!warnings.includes('payload-truncated')) {
+                data[warningsKey] = [...warnings, 'payload-truncated'];
+                text = JSON.stringify(data);
+            }
+        }
+    }
+    return { content: [{ type: 'text', text }] };
+}
+/**
+ * 复核 ToolResult 的序列化字节是否仍超 cap（Feature 171 FR-021）。
+ * handler 在 buildSuccessResponse 收缩后调用本函数，仍超则改返 payload-too-large。
+ */
+export function exceedsPayloadCap(result) {
+    const text = result.content?.[0]?.text ?? '';
+    return Buffer.byteLength(text, 'utf-8') > PAYLOAD_CAP_BYTES;
+}
+//# sourceMappingURL=tool-response.js.map

package/dist/mcp/lib/tool-response.js.map

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

package/dist/mcp/server.d.ts

@@ -1,8 +1,21 @@
 /**
  * MCP Server 定义
- * 注册 10 个工具（prepare、generate、batch、diff、panoramic-query + 5 个 graph 查询工具）供 Claude Code 通过 MCP 协议调用
+ * 注册 17 个工具（prepare、generate、batch、diff、panoramic-query +
+ * 6 个 graph 查询工具 + 3 个 agent-context 工具 impact / context / detect_changes +
+ * 3 个 file-navigation 工具 view_file / search_in_file / list_directory）
+ * 供 Claude Code 通过 MCP 协议调用。
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * MCP server 级 instructions（F184 FR-002）：经 SDK `ServerOptions` 注入 initialize result，
+ * 给 driver / 子代理在无明确指令时一份工具分组导览 + 典型链路 + 恢复流，提升 MCP 工具采用率。
+ *
+ * 约束：
+ * - 控制在 ≤1600 字符（server 级一次性导览，避免上下文膨胀；F184 Codex Plan W-004）
+ * - 不硬编码工具总数（用分组描述，降工具增减时的漂移；新增/删除工具时同步本文）
+ * - 必含典型链路串 `detect_changes → impact → context → view_file` 与 `graph-not-built` 恢复流
+ */
+export declare const TOOL_GUIDE: string;
 /**
  * 创建并配置 MCP Server 实例
  */

package/dist/mcp/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAqBpE;;GAEG;AACH,wBAAgB,eAAe,IAAI,SAAS,CAkP3C"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAwBpE;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,QAWX,CAAC;AAEb;;GAEG;AACH,wBAAgB,eAAe,IAAI,SAAS,CAuS3C"}