diff --git "a/reports/2026-08-02_0943_\346\212\200\346\234\257\346\236\266\346\236\204_dscode\344\273\243\347\240\201\344\273\223\345\272\223\345\210\206\346\236\220.html" "b/reports/2026-08-02_0943_\346\212\200\346\234\257\346\236\266\346\236\204_dscode\344\273\243\347\240\201\344\273\223\345\272\223\345\210\206\346\236\220.html" new file mode 100644 index 0000000..0f4c84b --- /dev/null +++ "b/reports/2026-08-02_0943_\346\212\200\346\234\257\346\236\266\346\236\204_dscode\344\273\243\347\240\201\344\273\223\345\272\223\345\210\206\346\236\220.html" @@ -0,0 +1,1755 @@ + + + + + + dscode 技术架构深度分析 + + + + + + +
+
+ +
+ + +
+
+
+ + +
+ + +
+
+
+ 版本 v0.2.7 + 分支 develop + 分析日期 2026-08-02 +
+

dscode 技术架构深度分析

+

基于 develop 分支源码，版本 0.2.7，分析日期 2026-08-02

+
+ + +
+
+ ⚡ 架构核心判定 (Architecture Verdict) +
+

+ dscode 是一个“单进程、模块化单体”的本地 Agent Runtime：Harness 是事实上的 composition root，把 pi-agent-core 的模型循环与工具、权限、MCP、上下文、会话、记忆和双 UI 适配器编排在一起；外围模块接口已经形成，但关键实现仍集中在少数超大文件，扩展速度快于边界治理。 +

+
+ + +
+
+
26,847
+
Core TypeScript (src/) 行数
+
+
+
5,043
+
Web React (web/src/) 行数
+
+
+
32
+
Vitest 单元与集成测试套件
+
+
+
1,815
+
最大单文件 (web-backend.ts)
+
+
+
500+
+
CHIFF 评估触发 Step 阈值
+
+
+
+ + +
+ + + + + +
+ + +
+

01. 执行摘要与核心结论

+

基于对 develop 分支 26,847 行 TypeScript 核心源码及 5,043 行 Web SPA 源码的核验，归纳出以下 5 个核心架构结论：

+ +
+
+
1
+
+

核心不是 UI，而是 Harness 编排层

+

TUI 与 Web SPA 仅仅是同一事件总线 (HarnessEventBus) 的两个呈现适配器；模型循环、工具挂载、Session 生命周期与 MCP 跨进程调度均由 Harness 统一控制。

+
+
+ +
+
2
+
+

工具规模通过 Deferred Discovery 控制

+

内置工具恒定发送，MCP schema 默认延迟。模型先调用 search_tools，命中的工具 schema 才会从下一轮对话注入上下文，降低上下文膨胀。

+
+
+ +
+
3
+
+

文件变更采用多层安全链保障

+

内容哈希行锚点、文件版本控制、SnapshotStore 快照恢复、三方合并、语法/结构检查、Checkpoint 与单步 undo 共同降低误编辑风险。

+
+
+ +
+
4
+
+

本地优先与可恢复性较强，但并不均匀

+

Session 正文采用 tmp → rename 原子写入；但索引与 Memory 为直接 JSON 覆写。Context 的 summarize-prefix 尚未实现，Memory 也没有自动提取。

+
+
+ +
+
5
+
+

主要风险在于复杂度集中与实现漂移

+

Harness (1,259行)、Web backend (1,815行)、TUI (1,501行) 与 MCP client (1,003行) 已成为超大文件。旧文档仍描述不存在的自动记忆与旧 MCP 命名。

+
+
+
+
+ + +
+

02. 系统分层架构视图

+

dscode 采用清晰的六层模块化单体分层结构。各层间依赖严格向下，同一层内通过事件与 Driver 接口解耦。

+ +
+
+ 系统依赖方向架构图 (Layered Dependency View) + SVG 渲染 +
+ + + + + + + + + + + + + 1. Interaction Layer (交互适配层) + + TuiBackend → TuiApp + + WebUiBackend → WS → React SPA + + + + + + 2. Orchestration Layer (编排中心) + + core/main.ts (Entry & Signals) + + core/harness.ts (Composition Root) + + + + + + 3. Agent Runtime Layer (运行时) + + pi-agent-core Agent + + ContextManager + + Prompt Assembler + + + + + + 4. Capability Layer (工具与能力) + + ToolRegistry + + PermissionMgr + + MCPManager + + FS/Hash Edit + + + + + + 5. State & Recovery (状态与恢复) + + SessionStore + + MemoryStore + + CheckpointMgr + + CHIFF Eval + + + + + + 6. External Boundaries (外部边界) + + LLM APIs + + MCP Servers + + Local Filesystem + + Browser Web + + + + + + + + + +
+
+ + +
+

03. 系统启动与生命周期流程

+

源码依据：src/core/main.ts、src/core/harness.ts、src/ui/tui-backend.ts、src/ui/web/web-backend.ts

+ +
+

标准启动与优雅退出七步曲

+
    +
  1. + 进程初始化与全局捕获： main.ts 生成 runtime ID，初始化文件 Logger，注册 uncaughtException、unhandledRejection、SIGINT/SIGTERM 紧急 Session 保存。 +
    2. +
  2. + CLI 参数与 Daemon 守护： 解析 --web、--web-port、--debug、--cwd、--with-od；后者启动并守护 Open Design daemon。 +
    3. +
  3. + 配置加载与级联合并： 执行 loadConfig()，按优先级合并环境变量、用户配置、用户/项目 settings 与 MCP 配置。 +
    4. +
  4. + Harness 编排对象构造： 构造 Harness，在 initialize() 中扫描 Skill、初始化 checkpoint/snapshot、注册 discovery driver、启动本地 MCP App Host、拼装 system prompt、解析模型并创建 pi-agent-core Agent。 +
    5. +
  5. + UI Backend 适配器实例化： 默认实例化 TuiBackend；--web 实例化 WebUiBackend，启动 HTTP 静态资源服务与 /ws WebSocket。 +
    6. +
  6. + 运行时启动与定时持久化： Harness.run() 启动 UI，连接 MCP servers，把 MCP tools 注册为 drivers，初始化 ToolRegistry，启动 15 秒周期 autosave。 +
    7. +
  7. + 优雅停机 (Graceful Shutdown)： shutdown 顺序强调先保存 Session，再关闭 checkpoint、AppHost、MCP。 +
    8. +
+
+
+ + +
+

04. 端到端请求处理与事件流

+

无论是 TUI 还是 React SPA 界面，用户交互都会收敛至 HarnessEventBus 执行统一的 LLM 思考与 Tool 调用循环。

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
阶段 (Phase)Web / TUI 差异点Harness 核心处理逻辑状态持久化与安全校验
1. 意图接收React 通过 WebSocket 发 ClientCommand.chat；TUI 监听终端输入。Web backend 处理上传文件、@file 引用和附件；调用 promptAndSave() 或 promptWithImages()。记录 turn 起点并生成 Turn ID。
2. Turn 广播WebSocket 广播 processing:start 与 message:user。Harness 广播 processing:start / message:user，进入 turn-level retry。内存基线预存消息数。
3. 上下文预处理共享相同逻辑。Agent 请求前执行 transformContext：注入 anchor 失效提示、刷新动态工具列表与稳定 deferred catalog、调用 ContextManager 进行预算评估与压缩。ContextManager 执行 sliding-window 预算判断。
4. 流式生成WebSocket 实时推送 stream:thinking 与 stream:text。pi-agent-core 流式请求模型；thinking、text、tool、retry 事件经 HarnessEventBus 转为 UI 无关事件。维护助手消息流。
5. 工具拦截前端弹窗展示权限确认。若模型调用工具，beforeToolCall 先进入 PermissionManager。允许后由 ToolRegistry 中对应 driver 执行；拒绝则中断。
6. 工具执行TUI/Web 渲染工具调用卡片与执行进度。afterToolCall 处理工具发现刷新、全量写入后的 anchor 失效、Abort terminate 等副作用。自动保存 Checkpoint 快照与单步 undo。
7. Turn 完成发送 processing:end，Web 更新 contentHash。assistant turn 完成后保存 Session、更新 content hash / 活跃时间。WebSocket/TUI 渲染同一事件语义。失败时退避重试。tmp → rename 原子写入 Session 文件。
+
+
+ + +
+

05. 核心子系统与关键机制

+ + +
+ 5.1 工具延迟发现 (Deferred Discovery) 与 MCP 架构 +
+

源码证据：src/drivers/registry.ts、src/drivers/tool-registry.ts、src/drivers/discovery.ts、src/mcp/names.ts、src/mcp/manager.ts、src/mcp/client.ts、src/mcp/app/host.ts

+ +

1. 延迟加载与模式匹配

+

为解决加载大量工具导致 Prompt 上下文爆炸的问题，dscode 实现了动态发现机制：

+
    +
  • DriverRegistry 注册 builtin： fs, shell, search, edit；search_tools 与 skill 是 base tools。
    • +
  • ToolRegistry 初始化： builtin 永不 deferred；MCP 默认 deferred；alwaysLoad 和带 UI resource 的工具直接加载；visibility 只有 app 的工具不暴露给 Agent。
    • +
  • 按需调起： system prompt 放稳定 deferred catalog。search_tools 支持关键词打分与 select:ToolA,ToolB 精确选择；仅搜索尚未 discovered 的工具。discovered 集合随 Session 持久化与恢复，下一轮 transform 才把完整 schema 加入工具列表。
    • +
  • MCP 名称规范： MCP 名称必须由工具函数生成：driver 为 mcp__<server>，tool 为 mcp__<server>__<tool>。
    • +
+ +

2. MCP 传输与 AppHost 宿主

+

MCPClient 支持 stdio 子进程换行 JSON-RPC、legacy SSE、Streamable HTTP；默认请求超时 30 秒，tool call 120 秒；协议版本支持 2024-11-05、2025-03-26、2025-11-25。Streamable HTTP 保存 MCP-Session-Id，404/410 可重新 initialize 后重试一次；Manager 监听 list-changed 通知热刷新工具。断开时按错误分类和指数退避最多 10 次重连，带随机 jitter。MCP AppHost 在 127.0.0.1 随机端口托管 sandbox，校验 text/html;profile=mcp-app，注入 CSP/allow、用 SSE + POST bridge 转发 RPC。HTML 与 MDX/data 两种模式均支持。

+
+
+ + +
+ 5.2 多阶图像与 OCR 兜底处理链 +
+

源码证据：src/core/harness.ts、src/drivers/vision/pipeline.ts、src/drivers/vision/client.ts、src/drivers/vision/ocr.ts、src/utils/image-cache.ts

+ +
    +
  1. 主模型原生支持： 若主模型原生支持 image，Harness 把图片内容直接交给主 Agent。
    2. +
  2. 图像规范与压缩： 否则统一 ImagePipeline：规范化 image block → sharp 可用时压缩到最大高度 480 并转 PNG → SHA-256 前缀内容寻址去重缓存。
    3. +
  3. 独立 Vision 模型调用： 配置了支持图片且存在 key 的 Vision model 时，独立调用描述模型（60 秒、4096 tokens、reasoning off）。
    4. +
  4. Tesseract OCR 兜底： Vision 失败或返回空内容时，回退 Tesseract eng+chi_sim OCR；只有字符密度达到阈值才接受。
    5. +
  5. 最终占位符： 产出 <image_description>、<image_text>、原始文字或明确错误占位，同时保留缓存引用供 Session 恢复。Abort 会终止 Vision/OCR；MCP 返回图片也走相同管线。
    6. +
+
+
+ + +
+ 5.3 文件定点编辑与恢复安全链 (Hash-Anchor Safety Chain) +
+

源码证据：src/drivers/fs.ts、src/drivers/edit/tool.ts、src/drivers/edit/hash.ts、src/drivers/edit/recovery.ts、src/drivers/edit/syntax-validate.ts、src/checkpoint/checkpoint-manager.ts

+ +

1. 读取与身份标定

+

read_file(hashes:true) 为每行返回 lineNum#hash [quality]|content；行号只是位置提示，内容哈希才是身份。同时返回 file_version、anchor_format_version=v3、重复频率与 recommended_anchors。SnapshotStore 以 (filePath, fileVersion) 保存最多每文件 5 个、全局 500 个完整快照，LRU 淘汰。

+ +

2. 写入与乐观并发

+

覆写已有文件的 write_file 必须提供 expected_file_version；overwrite_file 强制要求版本。不匹配就拒绝并要求重读；成功后明确标记所有旧 anchor 失效，并把提醒注入下一轮 context。

+ +

3. 定点编辑与三方合并

+

支持 replace/insert/delete line 或 range；一批操作基于同一初始快照原子解析，任一 anchor 缺失、歧义、顺序错误则整批拒绝。低熵行降级，短哈希歧义可借助更长 resolution hash、上下文、occurrence 和 advisory line 解歧。dry_run 可仅做解析。文件版本已变化时：优先在原快照回放 operations，计算 snapshot→expected patch，再三方合并到 current；失败后尝试 content search；仍失败才要求重读。落盘前做 checkpoint 与单步内存 undo；落盘后检查新增重复行、定界符平衡与受支持语言语法 (TS/TSX/JS/JSX/JSON/CSS/HTML)。Checkpoint 保存修改前字节；rollback 可恢复或删除本次新建文件；FileWriteTracker 标记混合 writer 和 bash 导致的 anchor invalidation。

+
+
+ + +
+ 5.4 配置、Session、Context 与 Memory 数据流 +
+

源码依据：src/core/config.ts、src/session/manager.ts、src/session/store.ts、src/context/manager.ts、src/memory/manager.ts、src/memory/store.ts

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
模块核心机制与优先级持久化与恢复保证当前实现局限 / 漂移
Configuration关键项优先级大体为：环境变量 → ~/.dscode/config.json → 用户 settings → 项目 settings → 默认值。MCP 权威优先级：项目 .mcp.json 覆盖用户 ~/.mcp.json。只读加载。permissions、skills、disabledSkills 在用户和项目层合并；项目 AGENTS.md 内容注入 system prompt。具体字段按实现读取，不要画成一个绝对适用于所有字段的单一公式。
Session26 位时间排序 ID；项目目录由路径 slug + SHA-256 前 8 位隔离。标题从最后一个有意义的用户输入提取。Session 正文先写 .tmp 再 rename，具备原子替换；索引最多 100 条，损坏时可从 Session 文件重建。15 秒 autosave + turn 结束保存 + 信号紧急保存。Session 索引文件为直接 JSON 覆写，缺乏原子落盘。
Context启发式 token 估算；预算 = model context window - max output - 2,000 system reserve - 3,000 tools reserve。超过目标利用率时支持 drop-oldest / sliding-window。配置名 summarize-prefix 目前只是回退 sliding-window，并没有额外 LLM 摘要。
MemoryGlobal 与 project 两级 JSON；project 用项目路径 SHA-256 前 12 位隔离。Memory JSON 是直接 writeFileSync 覆写，不具备 Session 正文的 tmp/rename 原子保证。只支持手动 add/remove/clear 与 system prompt 注入。docs/ARCHITECTURE.md 声称 Session 结束自动 LLM 提取 Memory，但当前没有 extractAndStore()，配置为 autoExtract:false。
+
+
+
+ + +
+ 5.5 CHIFF 超长会话评估流水线 (Iterative Focusing Pipeline) +
+

源码证据：src/eval/index.ts、src/eval/focus/index.ts、skeleton.ts、scan.ts、zoom.ts、synthesize.ts、workspace.ts

+ +

当 Session 解析后达到 FOCUS_PATH_THRESHOLD = 500 steps，走 Iterative Focusing Pipeline：

+ +
+
+
+
Phase 0: Skeleton 骨架化工作区构建
+
+ 构建 skeleton，把 meta、phase map、signals、hot/cold zones、data-items 与按 150 steps 分块的 step library 写入 ~/.dscode/eval/<sessionId>/。 +
+
+ +
+
+
Phase 1: SCAN 阶段 (热点区域定位)
+
+ SCAN Agent 基于索引和信号定位 3–5 个 attention zones。 +
+
+ +
+
+
Phase 2: ZOOM 阶段 (深度归因追踪)
+
+ ZOOM Agent 逐 zone 追踪 subtasks、agent nodes、data flows 与候选根因。 +
+
+ +
+
+
Phase 3 & 4: SYNTHESIZE & 规则提取
+
+ SYNTHESIZE 合并 zone graph，归因 mistake agent / step，构造 cascade / recovery arcs。Phase 4 从归因结果抽取可复用 Harness rules。这是一种“把长历史投影成可检索文件工作区，再让 Agent 分阶段聚焦”的上下文工程。 +
+
+
+
+
+ + +
+ 5.6 双 UI 架构实现与 WebSocket 状态同步 +
+

源码证据：src/ui/backend.ts、src/ui/tui-backend.ts、src/ui/tui-app.ts、src/ui/web/web-backend.ts、src/ui/web/protocol.ts、src/ui/shared/reducer.ts、web/src/components/App.tsx、web/src/hooks/useWebSocket.ts

+ +
    +
  • TuiBackend 与 TuiApp： TuiBackend 把 Harness 回调转发给 TuiApp；TUI 负责输入、permission prompt、MCP browser、Session 与流式消息展示。TUI 与模型循环不直接耦合，核心事件由 backend 适配。
    • +
  • WebUiBackend 职责集中： 同时承担 HTTP 静态资源、WebSocket command routing、上传文件、Session/MCP/Skill 管理、permission promise、artifact dashboard 生成和缓存，是当前最大的职责集中点。
    • +
  • 共享 Reducer 语义： Vite 通过 alias 直接复用 src/ui/shared/reducer.ts，实现服务端与 Web 端一致的会话 reducer 语义。React App.tsx 用 useWebSocket 连接 /ws，断线 2 秒自动重连。
    • +
  • Session Dashboard 缓存： Session Dashboard HTML 以 contentHash 为 cache key 存 localStorage，最多 20 条；生成过程通过 artifact_start/delta/end 流式传递。WebSocket protocol 是 discriminated union。
    • +
+
+
+ +
+ + +
+

06. 架构优势与技术亮点

+ +
+
+
+

1. 共享核心，双 UI 适配

+

避免 TUI/Web 各自实现 Agent 生命周期，确保不同端拥有绝对一致的编排行为。

+
+ +
+

2. Schema 按需延迟加载

+

deferred catalog 直接解决 MCP 数量增长导致的上下文成本。

+
+ +
+

3. 编辑安全是系统能力

+

版本、锚点、快照、三方恢复、checkpoint 形成纵深防御，而不是依靠弱约束的 Prompt 约定。

+
+ +
+

4. 本地优先与全流程透明

+

配置、Session、Memory、eval workspace 都是透明文件格式，便于迁移、版本控制与排障。

+
+ +
+

5. 协议边界覆盖完整

+

MCP 多 transport、协议协商、热刷新、会话恢复、App UI 形成较完整生态面。

+
+ +
+

6. 图像路径统一管控

+

用户附件、主模型视觉、专用视觉、OCR、MCP 图片共用缓存与降级语义。

+
+ +
+

7. 事件总线解耦渲染

+

流式模型与工具事件不绑定 UI 框架，便于扩展新客户端适配器。

+
+
+
+
+ + +
+

07. 风险评估与证据分级

+

明确区分“已确认缺陷”、“需验证风险”与“治理建议”，提供源码证据支撑：

+ +
+ 等级筛选: + + + + + +
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
风险级别分类与源码位置问题描述与潜在后果治理建议 (Remediation)
高：已确认缺陷 + 复杂度集中 / 变更半径大
+ web-backend.ts (1,815行), tui-app.ts (1,501行), harness.ts (1,259行), client.ts (1,003行), TransitionCanvas.tsx (1,526行) + 		Harness 同时掌握 composition、模型生命周期、prompt、retry、Session、MCP、UI events、eval。Web backend 同时是 transport、controller、session coordinator、upload manager、artifact service。违背单文件 ≤300 行规范，单元测试隔离困难，UI 与协议演进易发生遗漏。按职责拆分：从 Harness 提取 TurnRunner, RuntimeLifecycle, PromptComposer, AgentToolCoordinator。从 WebUiBackend 提取 WsCommandRouter, SessionController, UploadStore, ArtifactService。
中高：需验证风险 + turn retry 回滚边界需验证
+ src/core/harness.ts (promptAndSave()) + 		promptAndSave() 的 retry 循环内重新计算 preTurnLength。若第一次尝试已把部分消息写入 Agent state，后续循环的回滚基线可能不再是真正的 turn 前长度。增加失败注入测试，并将 turn snapshot / 消息基线移到 retry 循环外。
中：已确认缺陷 + 重试错误分类过宽
+ src/core/harness.ts + 		isRetryableError() 使用 lower.includes("5") 判断服务端错误，任意包含字符 5 的错误消息（如 "invalid option 5"）都可能被当作 5xx。解析结构化 status/code，避免字符串模糊误判和无意义重试。
中：已确认缺陷 + 持久化耐久性不一致
+ src/memory/store.ts, src/session/store.ts + 		Session 正文原子写；Session index 与 Memory 直接 writeFileSync 覆写。Memory 解析失败直接回空数组，可能把损坏静默表现为“没有记忆”。统一 safe JSON store：tmp/rename、备份、schema version、corruption warning。
中：已确认缺陷 + 文档与实现漂移
+ docs/ARCHITECTURE.md, README.md, src/core/config.ts + 		docs/ARCHITECTURE.md 声称 Session 结束自动 LLM 提取 Memory，当前没有 extractAndStore()，配置为 autoExtract:false。旧文档 MCP 示例仍使用单下划线，实际规范是 mcp__server__tool。summarize-prefix 名称暗示摘要，实现只是 sliding-window。roadmap 中“自动重连未完成”描述落后于代码。校准文档：修正 MCP 命名规则说明、Memory 自动提取现状、Context 策略与 roadmap 状态。
中：需验证风险 + MCP AppHost 信任边界需专门审计
+ src/mcp/app/host.ts + 		优点：仅绑定 loopback、随机 app ID、CSP、resource MIME 校验、iframe permissions。需验证：bridge 的 tools/call 直接调用 MCPClient，不经过 Harness PermissionManager；未看到 Origin/token 校验。明确 threat model，加入 app capability allowlist、Origin/nonce 校验与审计日志。
中：已确认缺陷 + 构建可复现性与耗时
+ scripts/build.mjs + 		根构建脚本每次 Web build 都执行 npm install，会引入网络依赖、耗时与 lockfile 行为差异。CI/开发分离，在构建脚本中使用 npm ci 或避免自动安装。
低至中：已确认缺陷 + 可观测性与规范偏差
+ Command loader, Vision client logger + 		命令 loader 仍直接 console.warn，Vision client 的一个 Logger tag 是 kebab-case，与统一文件 Logger / PascalCase tag 规范不一致。关键大状态机缺少统一 trace/turn correlation schema。统一收缩到 Logger，纠正 Tag 命名，引入 Trace ID 与 Turn 关联。
+
+
+ + +
+

08. 建议演进路线图

+ +
+
+
+
+ 0–30 天：先锁住正确性 + 第一阶段 +
+
+
    +
  • retry baseline 移出循环并加失败注入测试；结构化解析 HTTP/provider 错误。
    • +
  • 建立文档 truth check：MCP naming、Memory auto extract、context strategy、roadmap status。
    • +
  • 为 AppHost bridge 写 threat model 与 permission integration test。
    • +
  • Memory/index 改为统一原子 safe-write，损坏时显式告警。
    • +
+
+
+ +
+
+
+ 30–60 天：拆状态机边界 + 第二阶段 +
+
+
    +
  • 从 Harness 提取 TurnRunner、RuntimeLifecycle、PromptComposer、AgentToolCoordinator。
    • +
  • 从 WebUiBackend 提取 WsCommandRouter、SessionController、UploadStore、ArtifactService。
    • +
  • 从 MCPClient 分离 transport adapters (stdio / SSE / streamable-http) 与 protocol session。
    • +
  • 用同一套 contract tests 验证 TUI/Web 对 ServerEvent 的一致处理。
    • +
+
+
+ +
+
+
+ 60–90 天：提升可演进性 + 第三阶段 +
+
+
    +
  • 真正实现 summarize-prefix 或改名消除误导，并加入真实 tokenizer / provider usage 校准。
    • +
  • 把自动 Memory extraction 做成可审计、可撤回、默认保守的独立 pipeline；在完成前保持 autoExtract:false。
    • +
  • 建立 schema-versioned state store、trace ID、turn metrics 与重试/恢复指标。
    • +
  • 为 CHIFF 建基准集：根因定位准确率、LLM calls、预算、workspace 清理与失败回退。
    • +
+
+
+
+
+ + +
+

09. 源码证据路径索引

+

本报告所有分析结论均严格锚定以下 develop 分支源码路径：

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
架构模块分类源码路径 (Source Path)关键职责与分析结论参考
启动与编排 + src/core/main.ts
+ src/core/harness.ts
+ src/core/harness-api.ts + 		入口、全局捕获、Open Design daemon 守护；Composition root、turn-level retry、autosave、shutdown 流程。
配置管理src/core/config.ts环境变量、用户/项目 Settings、.mcp.json 权威优先级与 AGENTS.md 注入。
模型注册 + src/models/registry.ts
+ src/models/qwen.ts
+ src/models/kimi.ts + 		Model Registry、Provider 特性映射、Vision 能力解析。
Drivers & 工具 discovery + src/drivers/registry.ts
+ src/drivers/tool-registry.ts
+ src/drivers/discovery.ts
+ src/drivers/fs.ts
+ src/drivers/shell.ts
+ src/drivers/search.ts + 		DriverRegistry/ToolRegistry 初始化；builtin 永不 deferred；search_tools 打分与 select；FS/Shell/Search 驱动。
Edit & 恢复 + src/drivers/edit/tool.ts
+ src/drivers/edit/hash.ts
+ src/drivers/edit/recovery.ts
+ src/drivers/edit/syntax-validate.ts
+ src/drivers/edit/edit-undo.ts + 		lineNum#hash [quality]|content 行锚点；三方合并与原快照回放；AST 语法校验与单步内存 undo。
Checkpoint 快照 + src/checkpoint/checkpoint-manager.ts
+ src/checkpoint/snapshot-store.ts
+ src/checkpoint/write-tracker.ts
+ src/checkpoint/store/fs-store.ts + 		SnapshotStore LRU (单文件 5，全局 500)；修改前字节保存；FileWriteTracker anchor invalidation。
MCP 子系统 + src/mcp/client.ts
+ src/mcp/manager.ts
+ src/mcp/names.ts
+ src/mcp/app/host.ts + 		mcp__<server>__<tool> 双下划线命名；stdio/SSE/streamable HTTP 传输；指数退避重连；AppHost 本地 Loopback 动态沙盒与 CSP。
Vision 处理链 + src/drivers/vision/pipeline.ts
+ src/drivers/vision/client.ts
+ src/drivers/vision/ocr.ts
+ src/utils/image-cache.ts + 		Sharp 480px PNG 压缩；SHA-256 去重缓存；独立 Vision 模型 fallback；Tesseract eng+chi_sim OCR 兜底。
Context / Session / Memory + src/context/manager.ts
+ src/session/manager.ts
+ src/session/store.ts
+ src/memory/manager.ts
+ src/memory/store.ts + 		Context Token 预算与 sliding-window；Session 26位ID、.tmp → rename 原子写；Memory 两级 JSON 存取。
UI 层及协议 + src/ui/backend.ts
+ src/ui/tui-backend.ts
+ src/ui/tui-app.ts
+ src/ui/web/web-backend.ts
+ src/ui/web/protocol.ts
+ src/ui/shared/reducer.ts + 		UiBackend 接口与 HarnessEventBus；WebUiBackend 职责集中；共享 conversationReducer 语义；WebSocket discriminated union。
Web 前端应用 + web/src/components/App.tsx
+ web/src/hooks/useWebSocket.ts
+ web/src/index.css + 		React 18 SPA 主界面、useWebSocket 自动重连与 CSS Token 规范。
Eval / CHIFF 流水线 + src/eval/index.ts
+ src/eval/focus/index.ts
+ skeleton.ts, scan.ts, zoom.ts, synthesize.ts, workspace.ts + 		500+ steps FOCUS_PATH_THRESHOLD 触发；Phase 0 Skeleton 150-step 分块工作区；SCAN 热点、ZOOM 根因与 SYNTHESIZE 规则提取。
构建与测试套件 + package.json
+ scripts/build.mjs
+ web/package.json
+ tests/ + 		esbuild 构建脚本、Node 20 ESM 单入口打包、Vitest 32 个测试套件。
+
+
+ +
+
+ +
+ + + + +