@zqagent/core 0.3.13 → 0.3.22

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { M as Mode, S as ShellPolicy, E as EngineHook, C as CompactionStartInfo, a as CompactionDoneInfo, b as EventType, c as EngineErrorInfo, P as ProviderClient, T as TurnEngine } from './TurnEngine-CMGdcSdp.cjs';
-export { A as ApprovalOutcome, d as Approver, e as CompactionTrigger, D as Decision, O as OpenAIProvider, f as PermissionEngine, g as PermissionRequest, h as ShellSandboxStatus, i as TurnEngineOpts, W as WsEvent } from './TurnEngine-CMGdcSdp.cjs';
+import { M as Mode, S as ShellPolicy, E as EngineHook, C as CompactionStartInfo, a as CompactionDoneInfo, b as EventType, c as EngineErrorInfo, T as TurnEngine, P as ProviderClient } from './TurnEngine-DKSczYaA.cjs';
+export { A as ApprovalOutcome, d as Approver, e as CompactionTrigger, D as Decision, O as OpenAIProvider, f as PermissionEngine, g as PermissionRequest, h as ShellSandboxStatus, i as TurnActor, j as TurnEngineOpts, W as WsEvent } from './TurnEngine-DKSczYaA.cjs';
 import { T as TokenUsage, M as Message, R as ReasoningEffort } from './types-BYyXWWPW.cjs';
 export { A as ATTACHMENT_DIR, d as AssistantTurn, e as AttachmentError, f as MAX_ATTACHMENTS, g as MAX_ATTACHMENT_BYTES, b as MessageAttachment, c as StoredAttachment, S as StreamChunk, h as ToolCall, a as ToolSchema, U as UPLOAD_DIR, W as WorkspaceFileRef, i as attachmentBytes, j as buildWorkspaceFileNotice, k as hasNonImageAttachments, n as normalizeAttachments, r as readStoredAttachment, s as saveAttachments, l as saveAttachmentsToWorkspace, m as splitByCapability, o as stripAttachments } from './types-BYyXWWPW.cjs';
 import { T as ToolRegistry } from './ToolRegistry-DouDvn9E.cjs';
@@ -12,7 +12,7 @@ import { a as McpServerConfig, M as McpBuiltinContext } from './McpClient-CEQBUP
 export { b as McpClient, c as McpClientOptions, d as McpToolInfo, e as McpTransportType, O as OcrLlmConfig, f as OcrRuntimeOverrides, m as mcpToolKey, s as sanitizeToolName } from './McpClient-CEQBUPuC.cjs';
 export { BUILTIN_MCP_CONFIGS, McpConfigNormalizeOptions, McpConfigNormalizeResult, defaultMcpConfigPath, loadMcpConfigFile, normalizeMcpConfig, normalizeMcpConfigs, readMcpConfigFile, saveMcpConfigFile, splitCommandLine, withBuiltinMcpConfigs } from './internal/mcp/config.cjs';
 export { registerFileTools, registerReadOnlyFileTools } from './tools/files.cjs';
-export { C as ConflictGuard, W as WriteConflict, c as contentDigest } from './conflictGuard-BBOOIxxK.cjs';
+export { C as ConflictGuard, W as WriteConflict, c as contentDigest } from './conflictGuard-BuICnWEI.cjs';
 export { getShellCwd, registerShellTool } from './internal/tools/shell.cjs';
 export { registerSearchTool } from './tools/search.cjs';
 export { registerWebTools } from './tools/web.cjs';
@@ -413,6 +413,27 @@ interface PromptSet {
     summarySystemPrompt: string;
     /** 压缩后续接的指令（作为最后一条用户消息注入） */
     continuationContract: string;
+    /**
+     * 压缩块（`<compacted-history>`）的结构标题。
+     *
+     * 早先这些是硬编码英文，而压缩块**每轮都随上下文重发**：中文用户聊到触发
+     * 压缩（软阈值 60% 窗口）之后，上下文里就混进大量英文结构标题，模型的回复
+     * 语言随之漂移成英文 —— 表现为「我明明用中文聊，AI 却回英文」，且只在长
+     * 会话出现。因此这几条必须跟随界面语言。
+     */
+    compactedIntro: string;
+    /** 压缩块里「用户消息原文」小节标题 */
+    compactedUserMessagesHeader: string;
+    /** 压缩块里「更早的用户消息被省略」说明（{n} = 条数） */
+    compactedOmittedNote: (n: number) => string;
+    /** 摘要不可用时的降级说明（旧轮次只做了裁剪） */
+    compactedTrimmedNote: string;
+    /** 机械提取的工作状态块标题 */
+    workingStateHeader: string;
+    workingStateFiles: string;
+    workingStateCommands: string;
+    /** {list} = 工具名列表 */
+    workingStateTools: (list: string) => string;
     /** Git 提交说明生成提示词 */
     genCommitMessageInstructions: string;
 }
@@ -481,9 +502,205 @@ declare function buildExplorerInstructions(maxIterations: number, lang?: string
  * @param workspace 工作区路径（注入到环境信息块中）
  * @param today     当前日期（ISO 格式，注入到环境信息块中）
  * @param lang      界面语言（缺省简中）
+ * @param repoMapBlock 代码结构图（可选）。由 repomap 渲染，**放在最后**：
+ *   它是系统提示词里唯一会随工作区变化的内容，紧跟其后没有别的内容，
+ *   这样它变化时不会击穿前面稳定前缀的服务端缓存。
  * @returns 拼接后的完整系统提示词（代理提示词 + 叙述规则 + MCP/OCR/语言引导 + 环境信息）
  */
-declare function buildInstructions(agentType: "code" | "cowork", workspace: string, today: string, lang?: string | null): string;
+declare function buildInstructions(agentType: "code" | "cowork", workspace: string, today: string, lang?: string | null, repoMapBlock?: string): string;
+
+/** 项目规模档：决定注入形态（文件级 / 模块级 / 只给骨架） */
+type Scale = "small" | "medium" | "large";
+/** 符号种类（跨语言归一化；只用于渲染分组，不追求某语言的精确分类） */
+type SymbolKind = "class" | "interface" | "struct" | "enum" | "record" | "trait" | "impl" | "type"
+/** 模块级常量（`export const FOO = 1`） */
+ | "const" | "function" | "method" | "module" | "namespace";
+/** 一个符号 */
+interface SymbolNode {
+    name: string;
+    kind: SymbolKind;
+    /**
+     * 声明起始行（1 起始）。渲染成 `Name:12`，模型可直接 `read_file start_line=12`，
+     * 省掉先 grep 一行号的那一轮 —— 一轮工具调用要重发整个上下文，比这几个字符贵得多。
+     */
+    line?: number;
+    /** 声明结束行；与 {@link line} 相同时渲染层只写一个行号 */
+    endLine?: number;
+}
+/** 单文件的索引结果 */
+interface FileSymbols {
+    /** mtime（毫秒）：与 size 一起构成失效判据 */
+    mtimeMs: number;
+    size: number;
+    /** 提取出的符号（已截断到单文件上限） */
+    symbols: SymbolNode[];
+    /**
+     * 包名 / 命名空间（Java `package`、C# `namespace`、Go `package`）。
+     * 比目录结构可靠，用于渲染分组；取不到则缺省。
+     */
+    pkg?: string;
+    /**
+     * 再导出语句数（`export * from "./x"` / `export { a } from "./x"`）。
+     *
+     * barrel 文件（`index.ts` 只有再导出）提取不到任何符号，但它往往是**全仓
+     * 被 import 最多的文件**，是「该从哪个包入口开始」的最佳答案。没有这个计数，
+     * 索引器会把它连同其它 0 符号文件一起丢掉，包入口在结构图里彻底不可见。
+     */
+    reexports?: number;
+    /** 该文件由哪个提取器处理（诊断用） */
+    via: "tree-sitter" | "regex" | "path-only";
+}
+/** 缓存文件内容 */
+interface RepoMapCache {
+    version: number;
+    /** 工作区绝对路径（缓存自检用，避免 hash 碰撞时用错缓存） */
+    root: string;
+    builtAt: number;
+    scale: Scale;
+    /** 枚举与索引的统计，用于诊断与注入文案 */
+    scan: {
+        /** 枚举到的文件总数（可能远大于 indexed） */
+        files: number;
+        /** 进地图的文件数（有声明 / 纯 barrel / 入口；受 MAX_FILES 封顶） */
+        indexed: number;
+        /** 是否因上限被截断 */
+        truncated: boolean;
+        elapsedMs: number;
+    };
+    /** 相对工作区（POSIX 分隔符）→ 索引结果 */
+    files: Record<string, FileSymbols>;
+    /**
+     * 项目形状（探测 + 学习得到）。存在时后续会话跳过探测。
+     */
+    shape?: ProjectShape;
+}
+/** 构建文件暴露出的项目形状 */
+interface ProjectShape {
+    /** 构建体系类型 */
+    kinds: string[];
+    /** 源码根（相对工作区，POSIX），如 `src/main/java` */
+    sourceRoots: string[];
+    /** 模块划分 */
+    modules: Array<{
+        /** 相对工作区的模块目录；根模块为 "." */
+        path: string;
+        /** 该模块的构建文件名 */
+        buildFile?: string;
+        /** 识别出的框架（spring-boot / aspnet / cmake / cargo / npm-workspace …） */
+        framework?: string;
+        /** 入口文件（相对工作区） */
+        entry?: string;
+    }>;
+    /** 连续观察到同一形状的次数；达到阈值才固化 */
+    confirmations: number;
+    learnedAt: number;
+}
+/** 排序后的候选文件 */
+interface RankedFile {
+    /** 相对工作区的 POSIX 路径 */
+    path: string;
+    score: number;
+}
+/** 对外 API 返回的仓库地图 */
+interface RepoMap {
+    root: string;
+    scale: Scale;
+    scan: RepoMapCache["scan"];
+    /** 已排序的文件（score 降序），与 {@link files} 的键集完全一致 */
+    ranked: RankedFile[];
+    /**
+     * path → 索引结果，**只含进地图的文件**：有顶层声明、纯 barrel、或模块入口。
+     *
+     * 解析成功但三者都不满足的文件（例如只有顶层调用的脚本）不在这里 —— 它们在
+     * 结构图里只能占一行而不提供任何定位信息。索引磁盘缓存仍保留它们以支持增量。
+     */
+    files: Record<string, FileSymbols>;
+    shape?: ProjectShape;
+}
+
+/**
+ * 渲染：把索引结果压成能塞进系统提示词的一小段文本
+ *
+ * 三个档位（由项目规模决定），核心矛盾是同一个：
+ * **大项目里文件太多，列不完也没意义**。5 万个文件里列 250 个类名，对模型
+ * 定位代码毫无帮助；而「payment-service 里有 gateway 层」这种模块级信息
+ * 才能真正指路。所以大项目只给骨架，细节交给 `repo_map` 工具按需下钻。
+ *
+ * token 上的取舍（都按"能否帮模型少走一轮"来判断）：
+ *   - 目录路径只写一次（分组标题），不在每行重复
+ *   - 符号写「名字 + 行号」，不写 kind：行号能省掉先 grep 定位的那一轮，
+ *     kind 省不了任何一次工具调用
+ *   - 不画树形符号（`├──` 每行要花 4-8 个 token）
+ */
+
+/**
+ * 渲染 repo map 为可注入提示词的文本。
+ *
+ * @param map 仓库地图
+ * @returns 空字符串表示没有可渲染内容（调用方应跳过注入）
+ */
+declare function renderRepoMap(map: RepoMap): string;
+
+/**
+ * 确保运行时已初始化。
+ *
+ * @returns true = 可用；false = 不可用（调用方降级到正则提取）
+ */
+declare function ensureRuntime(): Promise<boolean>;
+
+/**
+ * 取得某工作区的结构图（带进程内复用与 TTL 刷新）。
+ *
+ * @param workspace 工作区绝对路径
+ * @returns 永不为 null；失败时是空地图（有旧图时退回旧图）
+ */
+declare function loadRepoMap(workspace: string): Promise<RepoMap>;
+/**
+ * 作废某工作区的缓存（写文件后调用）。
+ *
+ * 只丢缓存不重建：真正的重建发生在下一次取用时，且是增量的 —— 连续写 10 个
+ * 文件也只会在下一次真正需要结构图时重建一次。
+ */
+declare function invalidateRepoMap(workspace: string): void;
+/** 清空进程内缓存（测试 / 工作区内容大幅变化时） */
+declare function resetRepoMapMemo(): void;
+
+/**
+ * 把代码结构图接进一个已经建好的引擎。
+ *
+ * `createDefaultEngine` 用它做默认装配；CLI / server 这类自己拼装系统提示词的
+ * 调用方也用它，否则 `!instructions` 那道判断会让结构图整段失效 —— 它们都传了
+ * 自定义提示词（按当前 agent / 界面语言组装），属于设计上必须传的场景。
+ *
+ * 注入方式是**回调**而不是一段固定字符串：提示词的内容由调用方决定（agent
+ * 人设、语言），这里只负责把渲染好的结构图块交给它。这样 `attach.ts` 不需要
+ * 知道 AgentRegistry 或 PromptLang 的存在。
+ *
+ * 失败一律静默：结构图是纯增益，索引失败时表现为「没有结构图」，而不是会话报错。
+ */
+
+interface AttachRepoMapOptions {
+    /** 工作区根目录 */
+    workspace: string;
+    /**
+     * 用最新的结构图块（可能为空串）重建系统提示词。
+     *
+     * 调用方在这里拼自己的提示词（`AgentRegistry.buildSystemPrompt` /
+     * `buildInstructions`），再 `engine.setSystemPrompt(...)`。
+     */
+    buildPrompt: (repoMapBlock: string) => string;
+    /** 设 false 可完全关闭（默认 true） */
+    enabled?: boolean;
+}
+/**
+ * 立即挂上「写文件后失效 + 合并刷新」的钩子，并在后台补一次结构图。
+ *
+ * 首轮渲染不阻塞调用方：索引大仓库要几百毫秒到几秒，挡在装配流程里会让启动
+ * 明显变慢；而首轮没有结构图也能正常跑，只是少了点方向感。
+ *
+ * @returns 清理函数（引擎被判废时调用，避免定时器挂在废弃的引擎上）
+ */
+declare function attachRepoMap(engine: TurnEngine, opts: AttachRepoMapOptions): () => void;
 
 /**
  * Agent 注册表（AgentRegistry）
@@ -566,8 +783,11 @@ declare class AgentRegistry {
      * @param workspace 工作区路径（注入环境信息块）
      * @param today     当前日期（ISO 格式，注入环境信息块）
      * @param lang      界面语言（缺省简体中文）
+     * @param repoMapBlock 代码结构图（可选）。由 repomap 渲染，**放在最后**：
+     *   它是系统提示词里唯一随工作区变化的内容，紧跟其后没有别的内容，
+     *   这样它变化时不会击穿前面稳定前缀的服务端缓存。
      */
-    buildSystemPrompt(name: string, workspace: string, today: string, lang?: string | null): string;
+    buildSystemPrompt(name: string, workspace: string, today: string, lang?: string | null, repoMapBlock?: string): string;
 }
 
 /**
@@ -917,6 +1137,9 @@ declare function gitOk(r: GitResult): boolean;
 /** 取 stderr/stdout 的首行，用于错误提示 */
 declare function gitMessage(r: GitResult): string;
 
+/** 注册 repo_map 工具（低风险只读） */
+declare function registerRepoMapTool(registry: ToolRegistry, workspace: string): void;
+
 /**
  * 终端工具（控制台「终端」面板的长驻会话 → Agent 的只读上下文）
  *
@@ -1174,6 +1397,19 @@ interface CreateEngineOpts {
      *   仅建议在隔离环境或完全可信的输入下使用）。
      */
     defaultApproval?: "error" | "deny" | "allow";
+    /**
+     * 代码结构图（repo map）。
+     *
+     * 开启后会在**后台**索引工作区，构建完把结构摘要补进系统提示词，用于让模型
+     * 在读代码前就知道大致结构，减少「grep 摸底 → 读错文件 → 换词重搜」的轮次。
+     *
+     * 只在调用方没有显式传 `instructions` 时生效（自定义提示词的集成自己决定）。
+     * 任何失败都静默跳过，不影响会话。
+     */
+    repomap?: {
+        /** 默认 true；设 false 可完全关闭 */
+        enabled?: boolean;
+    };
 }
 /**
  * 一键装配完整的 TurnEngine
@@ -1190,4 +1426,4 @@ interface CreateEngineOpts {
  */
 declare function createDefaultEngine(opts: CreateEngineOpts): TurnEngine;
 
-export { type AgentDef, AgentRegistry, BUILTIN_AGENTS, CODE_INSTRUCTIONS, COWORK_INSTRUCTIONS, CompactionDoneInfo, CompactionStartInfo, CompositeHook, type ConfinementResult, ConsoleHook, type ConsoleHookOptions, type CreateEngineOpts, DEFAULT_ALLOWED_COMMANDS, DISCUSS_MODE_CONTEXT, type DownloadResult, EngineErrorInfo, EngineHook, EventType, type GitResult, MCP_CALL_TOOL, MCP_GUIDANCE, MCP_SEARCH_TOOL, MarkdownRenderer, McpBuiltinContext, type McpConnectResult, type McpLazyOptions, McpManager, type McpManagerOptions, McpServerConfig, Message, Mode, OCR_GUIDANCE, PLAN_MODE_CONTEXT, PROMPT_LANGS, type PermissionConfig, type PromptLang, type PromptSet, ProviderClient, ReasoningEffort, type RepairResult, type ResolveVcsOptions, type ResolvedBin, type ResolvedMedia, type RestoreResult, SHADOW_DIR, SandboxMode, SandboxOptions, SessionVcs, ShellPolicy, SubagentHook, type TerminalMetaView, type TerminalRecordView, type TerminalSource, TokenUsage, ToolRegistry, type TurnCommit, TurnEngine, type VcsConfigMode, VcsHook, type VcsMode, type VcsPlan, agentRef, assessCommand, buildEnvBlock, buildExplorerInstructions, buildInstructions, createDefaultEngine, downloadFfmpeg, getPrompts, gitMessage, gitOk, installHints, isGitRepo, loadPermissionConfig, matchPromptLang, normalizePromptLang, promptSets, registerTerminalTools, repairToolCallHistory, repairToolCallHistoryDetailed, resetFfmpegCache, resolveMedia, resolveVcsPlan, runGit, sessionIndexPath };
+export { type AgentDef, AgentRegistry, type AttachRepoMapOptions, BUILTIN_AGENTS, CODE_INSTRUCTIONS, COWORK_INSTRUCTIONS, CompactionDoneInfo, CompactionStartInfo, CompositeHook, type ConfinementResult, ConsoleHook, type ConsoleHookOptions, type CreateEngineOpts, DEFAULT_ALLOWED_COMMANDS, DISCUSS_MODE_CONTEXT, type DownloadResult, EngineErrorInfo, EngineHook, EventType, type GitResult, MCP_CALL_TOOL, MCP_GUIDANCE, MCP_SEARCH_TOOL, MarkdownRenderer, McpBuiltinContext, type McpConnectResult, type McpLazyOptions, McpManager, type McpManagerOptions, McpServerConfig, Message, Mode, OCR_GUIDANCE, PLAN_MODE_CONTEXT, PROMPT_LANGS, type PermissionConfig, type PromptLang, type PromptSet, ProviderClient, ReasoningEffort, type RepairResult, type RepoMap, type ResolveVcsOptions, type ResolvedBin, type ResolvedMedia, type RestoreResult, SHADOW_DIR, SandboxMode, SandboxOptions, type Scale, SessionVcs, ShellPolicy, SubagentHook, type TerminalMetaView, type TerminalRecordView, type TerminalSource, TokenUsage, ToolRegistry, type TurnCommit, TurnEngine, type VcsConfigMode, VcsHook, type VcsMode, type VcsPlan, agentRef, assessCommand, attachRepoMap, buildEnvBlock, buildExplorerInstructions, buildInstructions, createDefaultEngine, downloadFfmpeg, ensureRuntime, getPrompts, gitMessage, gitOk, installHints, invalidateRepoMap, isGitRepo, loadPermissionConfig, loadRepoMap, matchPromptLang, normalizePromptLang, promptSets, registerRepoMapTool, registerTerminalTools, renderRepoMap, repairToolCallHistory, repairToolCallHistoryDetailed, resetFfmpegCache, resetRepoMapMemo, resolveMedia, resolveVcsPlan, runGit, sessionIndexPath };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { M as Mode, S as ShellPolicy, E as EngineHook, C as CompactionStartInfo, a as CompactionDoneInfo, b as EventType, c as EngineErrorInfo, P as ProviderClient, T as TurnEngine } from './TurnEngine-BZjUGic_.js';
-export { A as ApprovalOutcome, d as Approver, e as CompactionTrigger, D as Decision, O as OpenAIProvider, f as PermissionEngine, g as PermissionRequest, h as ShellSandboxStatus, i as TurnEngineOpts, W as WsEvent } from './TurnEngine-BZjUGic_.js';
+import { M as Mode, S as ShellPolicy, E as EngineHook, C as CompactionStartInfo, a as CompactionDoneInfo, b as EventType, c as EngineErrorInfo, T as TurnEngine, P as ProviderClient } from './TurnEngine-C8qqbilC.js';
+export { A as ApprovalOutcome, d as Approver, e as CompactionTrigger, D as Decision, O as OpenAIProvider, f as PermissionEngine, g as PermissionRequest, h as ShellSandboxStatus, i as TurnActor, j as TurnEngineOpts, W as WsEvent } from './TurnEngine-C8qqbilC.js';
 import { T as TokenUsage, M as Message, R as ReasoningEffort } from './types-BYyXWWPW.js';
 export { A as ATTACHMENT_DIR, d as AssistantTurn, e as AttachmentError, f as MAX_ATTACHMENTS, g as MAX_ATTACHMENT_BYTES, b as MessageAttachment, c as StoredAttachment, S as StreamChunk, h as ToolCall, a as ToolSchema, U as UPLOAD_DIR, W as WorkspaceFileRef, i as attachmentBytes, j as buildWorkspaceFileNotice, k as hasNonImageAttachments, n as normalizeAttachments, r as readStoredAttachment, s as saveAttachments, l as saveAttachmentsToWorkspace, m as splitByCapability, o as stripAttachments } from './types-BYyXWWPW.js';
 import { T as ToolRegistry } from './ToolRegistry-Cy0fQxrb.js';
@@ -12,7 +12,7 @@ import { a as McpServerConfig, M as McpBuiltinContext } from './McpClient-CEQBUP
 export { b as McpClient, c as McpClientOptions, d as McpToolInfo, e as McpTransportType, O as OcrLlmConfig, f as OcrRuntimeOverrides, m as mcpToolKey, s as sanitizeToolName } from './McpClient-CEQBUPuC.js';
 export { BUILTIN_MCP_CONFIGS, McpConfigNormalizeOptions, McpConfigNormalizeResult, defaultMcpConfigPath, loadMcpConfigFile, normalizeMcpConfig, normalizeMcpConfigs, readMcpConfigFile, saveMcpConfigFile, splitCommandLine, withBuiltinMcpConfigs } from './internal/mcp/config.js';
 export { registerFileTools, registerReadOnlyFileTools } from './tools/files.js';
-export { C as ConflictGuard, W as WriteConflict, c as contentDigest } from './conflictGuard-BBOOIxxK.js';
+export { C as ConflictGuard, W as WriteConflict, c as contentDigest } from './conflictGuard-BuICnWEI.js';
 export { getShellCwd, registerShellTool } from './internal/tools/shell.js';
 export { registerSearchTool } from './tools/search.js';
 export { registerWebTools } from './tools/web.js';
@@ -413,6 +413,27 @@ interface PromptSet {
     summarySystemPrompt: string;
     /** 压缩后续接的指令（作为最后一条用户消息注入） */
     continuationContract: string;
+    /**
+     * 压缩块（`<compacted-history>`）的结构标题。
+     *
+     * 早先这些是硬编码英文，而压缩块**每轮都随上下文重发**：中文用户聊到触发
+     * 压缩（软阈值 60% 窗口）之后，上下文里就混进大量英文结构标题，模型的回复
+     * 语言随之漂移成英文 —— 表现为「我明明用中文聊，AI 却回英文」，且只在长
+     * 会话出现。因此这几条必须跟随界面语言。
+     */
+    compactedIntro: string;
+    /** 压缩块里「用户消息原文」小节标题 */
+    compactedUserMessagesHeader: string;
+    /** 压缩块里「更早的用户消息被省略」说明（{n} = 条数） */
+    compactedOmittedNote: (n: number) => string;
+    /** 摘要不可用时的降级说明（旧轮次只做了裁剪） */
+    compactedTrimmedNote: string;
+    /** 机械提取的工作状态块标题 */
+    workingStateHeader: string;
+    workingStateFiles: string;
+    workingStateCommands: string;
+    /** {list} = 工具名列表 */
+    workingStateTools: (list: string) => string;
     /** Git 提交说明生成提示词 */
     genCommitMessageInstructions: string;
 }
@@ -481,9 +502,205 @@ declare function buildExplorerInstructions(maxIterations: number, lang?: string
  * @param workspace 工作区路径（注入到环境信息块中）
  * @param today     当前日期（ISO 格式，注入到环境信息块中）
  * @param lang      界面语言（缺省简中）
+ * @param repoMapBlock 代码结构图（可选）。由 repomap 渲染，**放在最后**：
+ *   它是系统提示词里唯一会随工作区变化的内容，紧跟其后没有别的内容，
+ *   这样它变化时不会击穿前面稳定前缀的服务端缓存。
  * @returns 拼接后的完整系统提示词（代理提示词 + 叙述规则 + MCP/OCR/语言引导 + 环境信息）
  */
-declare function buildInstructions(agentType: "code" | "cowork", workspace: string, today: string, lang?: string | null): string;
+declare function buildInstructions(agentType: "code" | "cowork", workspace: string, today: string, lang?: string | null, repoMapBlock?: string): string;
+
+/** 项目规模档：决定注入形态（文件级 / 模块级 / 只给骨架） */
+type Scale = "small" | "medium" | "large";
+/** 符号种类（跨语言归一化；只用于渲染分组，不追求某语言的精确分类） */
+type SymbolKind = "class" | "interface" | "struct" | "enum" | "record" | "trait" | "impl" | "type"
+/** 模块级常量（`export const FOO = 1`） */
+ | "const" | "function" | "method" | "module" | "namespace";
+/** 一个符号 */
+interface SymbolNode {
+    name: string;
+    kind: SymbolKind;
+    /**
+     * 声明起始行（1 起始）。渲染成 `Name:12`，模型可直接 `read_file start_line=12`，
+     * 省掉先 grep 一行号的那一轮 —— 一轮工具调用要重发整个上下文，比这几个字符贵得多。
+     */
+    line?: number;
+    /** 声明结束行；与 {@link line} 相同时渲染层只写一个行号 */
+    endLine?: number;
+}
+/** 单文件的索引结果 */
+interface FileSymbols {
+    /** mtime（毫秒）：与 size 一起构成失效判据 */
+    mtimeMs: number;
+    size: number;
+    /** 提取出的符号（已截断到单文件上限） */
+    symbols: SymbolNode[];
+    /**
+     * 包名 / 命名空间（Java `package`、C# `namespace`、Go `package`）。
+     * 比目录结构可靠，用于渲染分组；取不到则缺省。
+     */
+    pkg?: string;
+    /**
+     * 再导出语句数（`export * from "./x"` / `export { a } from "./x"`）。
+     *
+     * barrel 文件（`index.ts` 只有再导出）提取不到任何符号，但它往往是**全仓
+     * 被 import 最多的文件**，是「该从哪个包入口开始」的最佳答案。没有这个计数，
+     * 索引器会把它连同其它 0 符号文件一起丢掉，包入口在结构图里彻底不可见。
+     */
+    reexports?: number;
+    /** 该文件由哪个提取器处理（诊断用） */
+    via: "tree-sitter" | "regex" | "path-only";
+}
+/** 缓存文件内容 */
+interface RepoMapCache {
+    version: number;
+    /** 工作区绝对路径（缓存自检用，避免 hash 碰撞时用错缓存） */
+    root: string;
+    builtAt: number;
+    scale: Scale;
+    /** 枚举与索引的统计，用于诊断与注入文案 */
+    scan: {
+        /** 枚举到的文件总数（可能远大于 indexed） */
+        files: number;
+        /** 进地图的文件数（有声明 / 纯 barrel / 入口；受 MAX_FILES 封顶） */
+        indexed: number;
+        /** 是否因上限被截断 */
+        truncated: boolean;
+        elapsedMs: number;
+    };
+    /** 相对工作区（POSIX 分隔符）→ 索引结果 */
+    files: Record<string, FileSymbols>;
+    /**
+     * 项目形状（探测 + 学习得到）。存在时后续会话跳过探测。
+     */
+    shape?: ProjectShape;
+}
+/** 构建文件暴露出的项目形状 */
+interface ProjectShape {
+    /** 构建体系类型 */
+    kinds: string[];
+    /** 源码根（相对工作区，POSIX），如 `src/main/java` */
+    sourceRoots: string[];
+    /** 模块划分 */
+    modules: Array<{
+        /** 相对工作区的模块目录；根模块为 "." */
+        path: string;
+        /** 该模块的构建文件名 */
+        buildFile?: string;
+        /** 识别出的框架（spring-boot / aspnet / cmake / cargo / npm-workspace …） */
+        framework?: string;
+        /** 入口文件（相对工作区） */
+        entry?: string;
+    }>;
+    /** 连续观察到同一形状的次数；达到阈值才固化 */
+    confirmations: number;
+    learnedAt: number;
+}
+/** 排序后的候选文件 */
+interface RankedFile {
+    /** 相对工作区的 POSIX 路径 */
+    path: string;
+    score: number;
+}
+/** 对外 API 返回的仓库地图 */
+interface RepoMap {
+    root: string;
+    scale: Scale;
+    scan: RepoMapCache["scan"];
+    /** 已排序的文件（score 降序），与 {@link files} 的键集完全一致 */
+    ranked: RankedFile[];
+    /**
+     * path → 索引结果，**只含进地图的文件**：有顶层声明、纯 barrel、或模块入口。
+     *
+     * 解析成功但三者都不满足的文件（例如只有顶层调用的脚本）不在这里 —— 它们在
+     * 结构图里只能占一行而不提供任何定位信息。索引磁盘缓存仍保留它们以支持增量。
+     */
+    files: Record<string, FileSymbols>;
+    shape?: ProjectShape;
+}
+
+/**
+ * 渲染：把索引结果压成能塞进系统提示词的一小段文本
+ *
+ * 三个档位（由项目规模决定），核心矛盾是同一个：
+ * **大项目里文件太多，列不完也没意义**。5 万个文件里列 250 个类名，对模型
+ * 定位代码毫无帮助；而「payment-service 里有 gateway 层」这种模块级信息
+ * 才能真正指路。所以大项目只给骨架，细节交给 `repo_map` 工具按需下钻。
+ *
+ * token 上的取舍（都按"能否帮模型少走一轮"来判断）：
+ *   - 目录路径只写一次（分组标题），不在每行重复
+ *   - 符号写「名字 + 行号」，不写 kind：行号能省掉先 grep 定位的那一轮，
+ *     kind 省不了任何一次工具调用
+ *   - 不画树形符号（`├──` 每行要花 4-8 个 token）
+ */
+
+/**
+ * 渲染 repo map 为可注入提示词的文本。
+ *
+ * @param map 仓库地图
+ * @returns 空字符串表示没有可渲染内容（调用方应跳过注入）
+ */
+declare function renderRepoMap(map: RepoMap): string;
+
+/**
+ * 确保运行时已初始化。
+ *
+ * @returns true = 可用；false = 不可用（调用方降级到正则提取）
+ */
+declare function ensureRuntime(): Promise<boolean>;
+
+/**
+ * 取得某工作区的结构图（带进程内复用与 TTL 刷新）。
+ *
+ * @param workspace 工作区绝对路径
+ * @returns 永不为 null；失败时是空地图（有旧图时退回旧图）
+ */
+declare function loadRepoMap(workspace: string): Promise<RepoMap>;
+/**
+ * 作废某工作区的缓存（写文件后调用）。
+ *
+ * 只丢缓存不重建：真正的重建发生在下一次取用时，且是增量的 —— 连续写 10 个
+ * 文件也只会在下一次真正需要结构图时重建一次。
+ */
+declare function invalidateRepoMap(workspace: string): void;
+/** 清空进程内缓存（测试 / 工作区内容大幅变化时） */
+declare function resetRepoMapMemo(): void;
+
+/**
+ * 把代码结构图接进一个已经建好的引擎。
+ *
+ * `createDefaultEngine` 用它做默认装配；CLI / server 这类自己拼装系统提示词的
+ * 调用方也用它，否则 `!instructions` 那道判断会让结构图整段失效 —— 它们都传了
+ * 自定义提示词（按当前 agent / 界面语言组装），属于设计上必须传的场景。
+ *
+ * 注入方式是**回调**而不是一段固定字符串：提示词的内容由调用方决定（agent
+ * 人设、语言），这里只负责把渲染好的结构图块交给它。这样 `attach.ts` 不需要
+ * 知道 AgentRegistry 或 PromptLang 的存在。
+ *
+ * 失败一律静默：结构图是纯增益，索引失败时表现为「没有结构图」，而不是会话报错。
+ */
+
+interface AttachRepoMapOptions {
+    /** 工作区根目录 */
+    workspace: string;
+    /**
+     * 用最新的结构图块（可能为空串）重建系统提示词。
+     *
+     * 调用方在这里拼自己的提示词（`AgentRegistry.buildSystemPrompt` /
+     * `buildInstructions`），再 `engine.setSystemPrompt(...)`。
+     */
+    buildPrompt: (repoMapBlock: string) => string;
+    /** 设 false 可完全关闭（默认 true） */
+    enabled?: boolean;
+}
+/**
+ * 立即挂上「写文件后失效 + 合并刷新」的钩子，并在后台补一次结构图。
+ *
+ * 首轮渲染不阻塞调用方：索引大仓库要几百毫秒到几秒，挡在装配流程里会让启动
+ * 明显变慢；而首轮没有结构图也能正常跑，只是少了点方向感。
+ *
+ * @returns 清理函数（引擎被判废时调用，避免定时器挂在废弃的引擎上）
+ */
+declare function attachRepoMap(engine: TurnEngine, opts: AttachRepoMapOptions): () => void;
 
 /**
  * Agent 注册表（AgentRegistry）
@@ -566,8 +783,11 @@ declare class AgentRegistry {
      * @param workspace 工作区路径（注入环境信息块）
      * @param today     当前日期（ISO 格式，注入环境信息块）
      * @param lang      界面语言（缺省简体中文）
+     * @param repoMapBlock 代码结构图（可选）。由 repomap 渲染，**放在最后**：
+     *   它是系统提示词里唯一随工作区变化的内容，紧跟其后没有别的内容，
+     *   这样它变化时不会击穿前面稳定前缀的服务端缓存。
      */
-    buildSystemPrompt(name: string, workspace: string, today: string, lang?: string | null): string;
+    buildSystemPrompt(name: string, workspace: string, today: string, lang?: string | null, repoMapBlock?: string): string;
 }
 
 /**
@@ -917,6 +1137,9 @@ declare function gitOk(r: GitResult): boolean;
 /** 取 stderr/stdout 的首行，用于错误提示 */
 declare function gitMessage(r: GitResult): string;
 
+/** 注册 repo_map 工具（低风险只读） */
+declare function registerRepoMapTool(registry: ToolRegistry, workspace: string): void;
+
 /**
  * 终端工具（控制台「终端」面板的长驻会话 → Agent 的只读上下文）
  *
@@ -1174,6 +1397,19 @@ interface CreateEngineOpts {
      *   仅建议在隔离环境或完全可信的输入下使用）。
      */
     defaultApproval?: "error" | "deny" | "allow";
+    /**
+     * 代码结构图（repo map）。
+     *
+     * 开启后会在**后台**索引工作区，构建完把结构摘要补进系统提示词，用于让模型
+     * 在读代码前就知道大致结构，减少「grep 摸底 → 读错文件 → 换词重搜」的轮次。
+     *
+     * 只在调用方没有显式传 `instructions` 时生效（自定义提示词的集成自己决定）。
+     * 任何失败都静默跳过，不影响会话。
+     */
+    repomap?: {
+        /** 默认 true；设 false 可完全关闭 */
+        enabled?: boolean;
+    };
 }
 /**
  * 一键装配完整的 TurnEngine
@@ -1190,4 +1426,4 @@ interface CreateEngineOpts {
  */
 declare function createDefaultEngine(opts: CreateEngineOpts): TurnEngine;
 
-export { type AgentDef, AgentRegistry, BUILTIN_AGENTS, CODE_INSTRUCTIONS, COWORK_INSTRUCTIONS, CompactionDoneInfo, CompactionStartInfo, CompositeHook, type ConfinementResult, ConsoleHook, type ConsoleHookOptions, type CreateEngineOpts, DEFAULT_ALLOWED_COMMANDS, DISCUSS_MODE_CONTEXT, type DownloadResult, EngineErrorInfo, EngineHook, EventType, type GitResult, MCP_CALL_TOOL, MCP_GUIDANCE, MCP_SEARCH_TOOL, MarkdownRenderer, McpBuiltinContext, type McpConnectResult, type McpLazyOptions, McpManager, type McpManagerOptions, McpServerConfig, Message, Mode, OCR_GUIDANCE, PLAN_MODE_CONTEXT, PROMPT_LANGS, type PermissionConfig, type PromptLang, type PromptSet, ProviderClient, ReasoningEffort, type RepairResult, type ResolveVcsOptions, type ResolvedBin, type ResolvedMedia, type RestoreResult, SHADOW_DIR, SandboxMode, SandboxOptions, SessionVcs, ShellPolicy, SubagentHook, type TerminalMetaView, type TerminalRecordView, type TerminalSource, TokenUsage, ToolRegistry, type TurnCommit, TurnEngine, type VcsConfigMode, VcsHook, type VcsMode, type VcsPlan, agentRef, assessCommand, buildEnvBlock, buildExplorerInstructions, buildInstructions, createDefaultEngine, downloadFfmpeg, getPrompts, gitMessage, gitOk, installHints, isGitRepo, loadPermissionConfig, matchPromptLang, normalizePromptLang, promptSets, registerTerminalTools, repairToolCallHistory, repairToolCallHistoryDetailed, resetFfmpegCache, resolveMedia, resolveVcsPlan, runGit, sessionIndexPath };
+export { type AgentDef, AgentRegistry, type AttachRepoMapOptions, BUILTIN_AGENTS, CODE_INSTRUCTIONS, COWORK_INSTRUCTIONS, CompactionDoneInfo, CompactionStartInfo, CompositeHook, type ConfinementResult, ConsoleHook, type ConsoleHookOptions, type CreateEngineOpts, DEFAULT_ALLOWED_COMMANDS, DISCUSS_MODE_CONTEXT, type DownloadResult, EngineErrorInfo, EngineHook, EventType, type GitResult, MCP_CALL_TOOL, MCP_GUIDANCE, MCP_SEARCH_TOOL, MarkdownRenderer, McpBuiltinContext, type McpConnectResult, type McpLazyOptions, McpManager, type McpManagerOptions, McpServerConfig, Message, Mode, OCR_GUIDANCE, PLAN_MODE_CONTEXT, PROMPT_LANGS, type PermissionConfig, type PromptLang, type PromptSet, ProviderClient, ReasoningEffort, type RepairResult, type RepoMap, type ResolveVcsOptions, type ResolvedBin, type ResolvedMedia, type RestoreResult, SHADOW_DIR, SandboxMode, SandboxOptions, type Scale, SessionVcs, ShellPolicy, SubagentHook, type TerminalMetaView, type TerminalRecordView, type TerminalSource, TokenUsage, ToolRegistry, type TurnCommit, TurnEngine, type VcsConfigMode, VcsHook, type VcsMode, type VcsPlan, agentRef, assessCommand, attachRepoMap, buildEnvBlock, buildExplorerInstructions, buildInstructions, createDefaultEngine, downloadFfmpeg, ensureRuntime, getPrompts, gitMessage, gitOk, installHints, invalidateRepoMap, isGitRepo, loadPermissionConfig, loadRepoMap, matchPromptLang, normalizePromptLang, promptSets, registerRepoMapTool, registerTerminalTools, renderRepoMap, repairToolCallHistory, repairToolCallHistoryDetailed, resetFfmpegCache, resetRepoMapMemo, resolveMedia, resolveVcsPlan, runGit, sessionIndexPath };