码脉 · AI 驱动的中文代码导读

码脉是面向 VS Code / Cursor 的中文代码学习扩展。它把陌生工作区整理成可交互的模块地图、五段阅读路线、当前文件脉络、学习概念和带源码依据的问答。

从 0.11.0 起，AI 是唯一的语义内容引擎：项目边界、模块职责、文档摘要、入口、调用链、状态、测试路线、节点解释、教学问题、学习卡、概念边注和问答都由所选模型生成。扩展宿主只登记真实文件、语言、符号范围、引用、内容哈希和证据白名单，不再用目录名、正则或固定词典生成替代讲解。

码脉以第三方 OpenAI Chat Completions 兼容 API 为主要远程接入，也可通过 VS Code Language Model API 复用 GCMP / GitHub Copilot，或连接本机 Ollama。首次打开码脉侧栏只展示本次分析范围与所选模型；宿主可以只读刷新 Git/未保存编辑等本地事实，但点击“开始分析工作区”后才会读取源码正文并调用模型。相同工作区内容、模型和分析设置会直接复用缓存，不新增模型请求。未配置模型或请求失败时会明确停在配置/重试状态，不展示本地语义兜底。

需要让另一个 AI 指导用户操作并基于证据讲解时，请先提供 本页“使用与隐私”说明。该手册包含意图路由、逐页操作、运行状态、授权边界、讲解模板、故障恢复和可直接复用的 AI 提示词。

当前能力

• 确认后初始化：首次进入先显示分析范围、模型来源与明确的开始按钮；未确认前不读取源码正文、不调用模型，本地 Git/编辑器变更事实仍可安全刷新。开始后按真实任务权重显示“地图 → 取证 → 证据图”、当前工作和等待时长。
• 可暂停与断点继续：任务工件完成即按内容哈希保存；暂停后可继续未完成任务、清除断点重新开始，或先更换 AI。
• 单模块 / 多模块地图：模型先理解整个工作区架构，再为每个模块分别生成“边界 → 入口 → 主链路 → 状态 → 测试”路线。
• 多 root 事实地图：工作区先建立不含源码正文的路径、语言、符号、引用、测试与哈希地图；多个 root 轮询登记，避免第一个目录耗尽容量。完整覆盖模式会先为地图内每个范围建立可恢复计划。
• 完整覆盖模式：按事实地图为纳入范围生成确定性源码分片计划，以有界并发逐片读取和归并；新任务使用 8 路归并树，278 个源码分片约需 41 个归并回合，旧 4 路断点继续原位复用。每层归并保留完整规范路径，最终五段路线必须绑定真实索引文件；模型漏交关联时只按本地模块边界恢复候选，不会把空路线保存为成功。默认按需取证模式保持快速。完整覆盖受 include/exclude 规则、maimai.project.maxFiles、字符预算和模型上下文能力约束，不等于无限制扫描所有目录。
• AI 按需取证：模型通过 list/search/read-range/symbol/reference/test 六个只读工具主动补充证据，不再接收固定源码批次或重复的整仓归并输入。
• 共享证据图：模块、入口、调用、状态、测试、文档、概念和风险都绑定 evidence ID；路线、脉络、学习和问答从同一图投影。
• 文档消噪：README、构建清单、AI 工作流、运维与参考资料由 AI 分类、总结并提示需要复核的时效问题，不再平铺文件列表。
• AI 重点脉络：VS Code 语言服务只提供真实符号与范围；模型从符号中选择主干、关键与必要辅助节点并说明取舍理由，简单字段、样板方法和重复叶子不再千篇一律地占满脉络。
• 证据簇学习知识库：学习扫描先在本地把工作区分成主体代码、上下文与排除文件，再依据真实引用、模块和测试关系组成跨文件证据簇。生成代码和第三方依赖排除；协议、配置、测试与文档只有被链路引用时才作上下文，不再按文件顺序逐个硬凑卡片。
• 主题学习：直接复用路线、证据图与当前源码匹配的文件精读，形成项目讲解；通用基础与跨文件业务实践保留各自语义。默认推荐当前阅读相关主题，支持目标与基础排序、先修跳转、搜索、错题复习和随机探索。独立全库扫描仍可主动启动，但不再是学习前置条件。
• 按需教学与本地练习：只为当前主题补充缺失的原理、边界或练习，不重复发送源码或重写原讲解。重复点击合并为一个请求，支持取消和持久化缓存；题目本地判分，保留次数、正误与最近结果，不保存原答案，掌握标记仍由用户决定。
• 本地全局脉络：进入“脉络”不会自动扫描；只有点击“建立本地文件脉络”后，才按“当前文件 → AI 路线文件 → 其余代码文件”顺序逐个调用本地语言服务。README、构建清单和配置文件不会混入代码队列，修改过的文件按哈希重新读取，过程可安全暂停、继续并在队列内前后切换，零模型请求。切页或重建 Webview 只恢复状态，不会重新启动。
• 精读历史与连续导航：当前源码匹配的文件知识直接形成项目主题，节点可进入相关学习内容并返回原位置。路线入口始终切回代码脉络；阅读顺序可定位节点，并能继续路线下一份文件。切页不触发模型。
• 可控自动预精读：默认关闭；可在设置中选择入口与主链、全部路线或路线优先并补充工作区源码，并限制每批文件数。代码脉络可独立选择另一个已保存接入方案或 VS Code / GCMP 模型，不改变路线和问答模型。自动阶段使用轻量 preview，不生成全局学习卡；用户点击“AI 精读”时再用独立 deep 缓存身份升级完整讲解和文件局部概念提示。有界并发队列只显示一个可控任务，手动精读始终优先。
• 全量文件深度预精读：在“脉络 → 代码脉络”显式点击后，以 workspace + deep 提前精读全部可纳入的代码文件；默认 8、最高 32 个模型请求并发，支持暂停、从缓存继续和失败补跑。界面分别显示可精读范围、实际 deep 覆盖、仍在缓存中保留的结果、失败与容量遗漏；条目或字节预算不足时不会误报完整覆盖。
• 缓存空间管理：设置页按文件精读、项目路线与证据图、断点、本地事实索引和完整覆盖 sidecar 展示实际序列化占用；同一文件更新覆盖旧版本，并可清理孤立结果、过期覆盖计划和超过配额的工件。清理不删除源码、模型连接、API Key 或学习进度。
• 新手 / 专业双模式：新手模式强调基础、顺序和主动回忆；专业模式隐藏“带着问题读”、检查点等脚手架，聚焦难点、边界、异常、并发、性能和设计取舍。切换只重新投影现有语义与证据，零模型请求。
• 默认 / 业务双视角：默认视角沿用项目路线与代码职责；业务视角从交付价值、输入与决策、状态变化、失败代价进入代码，再连接框架架构、数据结构、网络和操作系统。视角切换只在本地重排同一份项目证据和知识，不调用模型、不清缓存，也不改变已掌握状态。
• 三级阅读字号：设置中的“阅读字号与密度”提供舒适阅读、大字阅读和紧凑显示。舒适模式跟随 VS Code 字体并保证中文正文下限；大字模式优先放大学习、路线、脉络和问答的阅读正文，不使用会破坏窄侧栏布局的整体页面缩放。该偏好保存到编辑器全局，切换时不调用模型。
• 连续导航：路线文件可直接进入脉络，节点可定位源码、聚焦分支或继续学习；顶部可快速切换任意工作区文件。
• 工作区变更并发理解：在“脉络 → 工作区变更”按仓库和模块查看已暂存、未暂存、未跟踪、冲突与未保存修改；AI 将选中范围按固定 8 文件分片并发取证，每片独立保存，最后归并跨文件影响、风险与测试。默认 4 并发、可调到 16，支持暂停、继续、失败项重试和历史切换。
• 范围化 AI 问答：可按当前选区、当前文件、整个项目或本次变更提问；变更范围会再次要求发送确认，回答附带可定位的真实源码依据。未配置 AI 时问答禁用。
• 可客制化模型：支持自定义地址、模型、密钥 Header/前缀、输出 token 字段、额外请求体、分析要求、系统提示和容量。
• 接入方案历史：自动保留最近 12 个模型连接，支持快速切换、重命名与删除；切换只改变 Provider 连接，教学模式、容量和提示继续全局复用。
• GCMP / Copilot 模型复用：动态发现 VS Code 注册的 gcmp.* 与 copilot 模型，显示来源、上下文窗口和授权状态；码脉只保存 vendor 与模型 ID，不读取或复制其他扩展的密钥。
• Copilot 项目上下文工具：Agent 可引用 #maimaiProjectContext，经确认后读取码脉的模块地图、路线与相关源码证据；工具只返回相对路径，并按当前聊天 token 预算整文件收缩。
• 第三方兼容主渠道：自由填写服务根地址、/v1 或完整 /chat/completions 地址，以及模型、认证 Header、密钥前缀、输出 token 字段和额外请求体；设置页直接展示最终请求地址并可保存后真实测试。原生 tools、多轮 tool history、SSE、普通 JSON 与 action envelope 使用同一套本地完整性门禁，截断、过滤或没有完成终态的结构结果不会落盘。
• 可靠运行：tokenizer 预检、模型能力探测、原生工具回合、任务 DAG、工件级断点、按功能独立公平并发、结构化结果校验、工具前正文止损、主动取消、旧响应丢弃和流式问答。路线、学习、文件精读、变更各自遵守独立并发上限，问答和连接测试使用独立名额；第三方 delta 实时进入止损并能关闭底层 fetch，不支持 tools 的端点按端点和模型安全降级，具体 schema 错误不会被吞掉。完整覆盖和学习内部批次成功后立即保存，取消会等待在途任务退出并把未保存任务恢复为排队。网络、限流或上游临时失败仍有限恢复；完整覆盖跑满超时预算后只保留准确失败任务，不立即复制另一条昂贵请求。断点和 sidecar 只保留哈希、范围、摘要与状态，不持久化源码正文。
• 本地调用诊断：按 operation / task / turn / tool 记录耗时、token、断点复用、截断与错误类型；日志由 VS Code 本地持久化和轮转，不写入工作区，也不记录源码、提示词、模型正文、密钥或完整远程地址。
• 证据边界：模型给出的路径和符号必须命中工作区清单与语言服务节点；虚构引用在进入 UI 前被丢弃。
• 隐私边界：API Key 存入 VS Code SecretStorage；非回环端点必须明确允许后才能接收源码上下文。

上手顺序

1. 打开包含源码的工作区，点击活动栏“码脉”。
2. 初次未配置时进入“设置”，选择“第三方兼容 API · 主渠道”，填写服务地址和模型；需要鉴权时把 API Key 保存到 VS Code SecretStorage，并明确允许远程发送代码上下文，最后点击“保存当前配置并测试”。保存后会自动加入“接入方案”，以后可从顶部选择器快速切换。
3. 已安装 GCMP 或使用 GitHub Copilot 时，也可选择“VS Code · GCMP / Copilot”，重新发现并选择模型；本机模型则选择 Ollama。码脉不会读取这些提供方的密钥。
4. 回到“路线”确认本次模型与分析范围，点击“开始分析工作区”；此前不会建立项目源码地图或发送模型请求，开始后可随时暂停。
5. 在顶部品牌旁选择“新手”或“专业”。切换会保留当前路线和证据图，只改变教学脚手架；如果文字偏小，在“设置 → 阅读字号与密度”选择“大字阅读”并保存。
6. 在“路线”选择模块并展开五段路线；点“开始学这个文件”进入“脉络”，点击节点即可定位源码。若希望之后打开任意文件都立即看到完整讲解，可在代码脉络点击“提前精读整个工作区”；该动作会显式调用所选文件模型，已保存 deep 结果会直接跳过。
7. 需要理解正在开发的修改时，进入“脉络 → 工作区变更”。本地 Git 状态会自动刷新但不会调用 AI；勾选发送范围并点击“AI 解读这些修改”后，才会按需读取有限差异。分析可暂停、继续或重试，完成结果会进入历史。
8. 在“学习”直接阅读已有路线与脉络形成的主题。默认推荐当前阅读相关内容，可切换全部、项目讲解、通用基础或业务实践；需要时点击“补充原理、边界、练习”。展开“扩展学习范围”可主动扫描全库。在主题上点击“围绕此主题提问”，问答会继承主题、学习目标与有界近期对话。
9. 大型项目需要完整触达时，在“设置 → 容量与成本 → 工作区路线”选择“完整覆盖”，从并发 2 开始；完成后路线会显示完整文件、分片、字符和失败审计。按需取证适合先快速建立项目地图。

AI 与容量设置

设置页提供“应用大型项目建议值”和“填入能力上限”。能力上限不是通用推荐：运行时仍依据所选模型的 tokenizer、maxInputTokens、只读工具硬上限和总证据预算收缩；只有实际取得的证据才能支持内容级结论。

兼容端点可填写服务根地址、/v1 或完整 /chat/completions 地址。extraBodyJson 可放供应商支持的 top_p、seed 或思考模式开关，但不能覆盖核心消息、tools、n、stop 与 token 字段，也不要存放密钥。普通问答原样使用其余参数；路线、脉络等 JSON 阶段若只产生推理内容，会保留其他参数并关闭常见思考字段，仅重试当前阶段一次。旧版 DeepSeek 官方专用 Provider 已停用：升级后必须在第三方兼容渠道重新确认地址并设置密钥，旧密钥不会被静默复用。

接入方案只记录 Provider、vendor、地址、模型和请求兼容参数，最多保留最近 12 个并按使用时间排序；相同方案会更新时间而不会重复堆积。API Key 始终独立存于 SecretStorage，并按最终服务地址及认证方式隔离；同一服务切换模型或采样参数可复用凭据。切换方案会停止旧请求，但不会自动开始工作区分析；存在未保存草稿时，界面会先要求确认。

项目讲解是可随时查阅的资料，不是必须逐条完成的课程。学习页先按已有路线模块展示专题，缺少模块归属时按目录收纳；进入专题后逐批查看讲解，保留完整内容和证据。主干/关键符号不再自动变成独立课程，项目资料也不计入总掌握进度和待学习徽标。

工作方式

工作区文件、符号、引用、哈希 ──> 不含源码正文的事实地图 ──> AI 规划缺失证据
                                                              │
                                   有界 search/read/symbol/test 工具回合
                                                              │
                                                     结构化语义 + Evidence Graph
                                                              │
                                              路线 / 脉络 / 学习 / 问答投影

当前文件源码 + 真实符号 + 项目结论 ──> 独立文件模型 ──> AI 文件脉络 / 教学 / 局部概念
工作区代码文件 ──> 本地逐文件语言服务 ──> 可切换符号骨架（不调用模型）
工作区代码文件 ──> 显式全量 deep 队列（1–32 并发）──> 可恢复文件缓存 ──> 脉络即时复用
工作区事实索引 ──> 文件角色 + 引用/测试图 ──> 跨文件证据簇 ──> 通用基础 / 业务实践 ──> 本地分池、练习、随机抽样
路线主题 + 当前源码匹配的文件精读 + Evidence Graph ──> 项目学习主题 ──> 按需补教学缺口
选区 / 文件 / 项目上下文 + 当前主题 + 有界对话 ───────────> 同一 Provider 的问答

模型输出 ──> 真实路径 / 符号 ID / 行号校验 ──> Webview 展示与源码跳转

宿主的结构信息是安全边界，不是语义分析结果。它可以证明“文件和符号存在”，不能自行声称“这是入口”或“这个模块负责订单”。

缓存与初始化语义

• 同一扩展标识下覆盖安装新版 VSIX 会保留历史记录。 商店扩展标识为 idtw2333.maimai-code；模型接入方案与密钥、路线结果与断点、文件精读历史、独立学习目录、掌握进度和变更解读分别保存在 VS Code 的 globalState、SecretStorage、workspaceState 与扩展工作区存储中，不写进会被替换的 VSIX 安装目录。请直接覆盖安装，不要先卸载扩展；同一源码若换成另一个工作区打开方式，VS Code 可能分配新的 workspaceState，此时原记录仍在旧工作区存储中。

• Webview 第一次 ready 只发布设置、模型发现与确认态；只有 startProjectAnalysis 用户动作才启动项目分析，项目成功后再精读当前文件。

• 项目缓存键包含整个索引指纹、模型、提示要求与生成参数，不包含教学模式或业务视角。内容合同升级时只检查代码显式声明兼容的上一合同精确 key；命中后迁移完整模块、路线文件、讲解理由与证据，只清洗旧顶部概览中的内部归并术语，不按工作区根目录盲目复用其他模型结果。完整覆盖缓存若任一模块缺五段路线、任一阶段没有真实文件或没有入口文件，会被视为不可迁移结果并从旧断点重建最终归并。

• 文件缓存键包含 URI、相对路径、语言、文件哈希、项目 AI 指纹、实际文件模型、文件容量和 preview / deep 层级，也不包含教学模式；切换文件专用模型只使文件结果失效，不会重跑路线，内容相同的不同文件也不会串用结果。

• 路线、文件精读与独立扫描保留各自生命周期，学习汇总层按身份、领域和来源关联它们；有歧义的同名内容不静默合并。主讲解按结构完整性与证据选择，互补解释保留在来源展开区，不按段落长度拼接。

• 独立全库学习扫描默认不启动；只有学习页的明确按钮会调用模型。它以本地文件角色和引用图建立证据簇，默认以 8 并发执行、可独立调到 32；每个成功簇会立即形成临时知识，暂停、失败或重启恢复时仍可学习。大型簇可分片取证，但只对缺少跨文件业务结论的簇执行至多 4 并发的小型摘要归并，不重复发送源码或整个目录。分片完成即释放源码正文，只持久化课程摘要、证据范围、覆盖状态与断点。

• 路线完整覆盖期间若源码被 AI coding 或人工编辑，码脉会取消旧快照、等待断点落盘，并在变更静默 1.5 秒后自动按最新源码恢复。手动“从断点继续”也会先在本机重建最新文件清单，再按分片路径、内容哈希和范围逐项复核，只重跑变化分片及其上层归并；源码漂移不会再被误报为模型或网络故障。

• 自动 preview 默认关闭，只针对用户确认后在当前会话新完成的项目分析启动；恢复已有项目缓存、打开侧栏、切换页签或切换文件本身不会暗中发起模型调用。自动 preview 与显式全量 deep 默认每批 32 个文件、8 并发，最高 100 文件/批、32 并发，并对每个文件独立结算。当前文件手动精读会先暂停后台队列。

• 文件精读采用“同 URI 新结果覆盖旧结果”的双限缓存；条目数或字节预算先到即按生成顺序淘汰较旧结果。覆盖 sidecar 同样按工作区、计划和分片保留元数据/摘要，并由配额、过期计划和孤儿工件清理控制，不保存源码正文。

• 项目和文件结果落盘前都会复核当前工作区身份与源码 hash；工作区根目录或文件在请求期间变化时，旧响应不会进入缓存或触发后续自动读取。单项文件结果超过缓存预算时只保留在当前页面，并明确提示未持久化。

• Workspace Map、Evidence Agent、Project Output、Coverage Shard/Merge 和 Evidence Graph 任务完成后分别保存 v2 工件；失败页“从断点继续”只补 inputHash/planHash 不一致或未完成的任务，不重读已验证分片。切换模型、Provider、超时、输出 token 或并发后，最终结果缓存仍按新配置隔离，但同一工作区源码的断点会先被找回，再由任务哈希逐项判断复用；更改项目内容要求或分析模式不会把旧结论冒充新结果。

• 完整覆盖只针对事实地图纳入的文件与范围：默认排除依赖、构建产物、缓存和版本控制目录，并受 include/exclude、最大文件数、字符预算、分片计划和模型能力约束。存在失败、部分分片或范围截断时，覆盖审计只能报告 partial/failed，不能标记完整成功。

• 缓存命中显示“未新增模型请求”；强制“重新分析工作区 / 重新精读”会忽略成功结果缓存。

• 主题教学补充按主题正文、证据哈希与生成配置隔离缓存，最多保留 300 条；无关主题变化不使其身份失效。补充只代表基于摘要的教学，不增加源码覆盖率。清理学习存储会一并清理补充，保留源码与用户学习进度。

• 问答的源码、证据图、学习目标、主题和近期对话共用一个上下文字符预算。长文件优先提供命中问题的行段；传输首字立即显示，后续累计正文最多约每 50ms 推送一次，完成时发送最终全文。

• 共享模型闸门在总上限大于 1 时保留一个交互名额，问答、主题补充和手动精读优先；自动文件队列、路线与独立扫描受后台容量约束。不会通过增大用户设置获得并发。日志保留上下文准备、排队、首字和完成耗时。

开发与安装

要求 Node.js 20+、VS Code 1.95+ 或兼容编辑器。

npm install
npm run check
npm run package

打包生成 maimai-code-0.19.12.vsix。可在编辑器扩展视图选择“从 VSIX 安装…”，也可直接把 .vsix 发给他人离线安装；对方仍需自行安装/配置所选模型提供方并完成授权。已有用户应直接覆盖安装，以继续使用原工作区历史、断点和 SecretStorage 配置。

本地调用日志与模拟链路

命令面板可运行“码脉：显示 AI 调用日志”查看 码脉 AI 调用 Log Output Channel，或运行“码脉：打开本地日志目录”检查 VS Code 当前会话的持久化日志。每条 JSON 事件带 schema version、时间、递增序号及可用的 operation/run/task/attempt/turn/call 标识，可串起 operation.started → model.turn → tool → analysis.task → operation.completed/timeout/failed。日志只包含 Provider、模型 ID、配置超时、token/字符数量、工具名与安全相对路径、耗时、覆盖/截断和错误分类；不会记录 API Key、Header、prompt、源码、diff、模型正文、完整 endpoint、文件 URI 或本机绝对路径。

GCMP 自身的请求面板不是码脉任务状态源。部分版本会在 pending 记录超过约 300 秒后清除回写句柄，而慢模型仍可能继续到码脉的 600 秒超时；完成回调随后无法把旧行从 ACTIVE 更新为 DONE。0.19.10 会在 required-tool 前正文失控时提前关闭底层流，并确保码脉 operation 自身都有终态，但不能改写 GCMP 已持久化的历史行。判断是否仍在运行应以码脉任务条和 operation/model.turn 终态日志为准。

无需调用真实模型即可验证调用、取证、落盘和恢复链路：

npm run test:ai-flow

该命令会模拟 VS Code / GCMP 的原生工具调用、结构提交与兼容 API action envelope，并注入一次立即发生的超时，验证超时设置透传、脱敏日志、任务断点、路径规范化、证据图、五段路线，以及“从断点继续”不重复执行已保存任务。它不读取密钥、不联网，也不会修改工作区源码。

给其他 AIcoding 工具提供只读事实上下文时，可调用 VS Code 命令 maimai.getProjectContext，参数为 { query?, maxFiles?, maxCharacters? }。它返回带证据的 ContextPack，不会写工作区或主动调用远程模型。Copilot Agent 使用 #maimaiProjectContext 时可传 includeChanges: true，附加当前变更的结构化状态、路径、层级和证据锚点；该工具不返回 diff/源码正文。

工作区变更有两层边界：本地事实层只读 Git/编辑器状态，始终不调用模型；AI 解读层必须再次确认发送范围。首轮请求只含相对路径、状态、统计和 hunk 坐标，模型随后只能用 file id 调用有界的 read_diff/read_before/read_after 等只读工具。疑似密钥、凭据、构建产物、二进制和子模块正文默认排除；完成历史最多保留 20 条结构化结论与锚点，不持久化原始源码或 diff。

在 VS Code Copilot Agent 中可直接附加 #maimaiProjectContext。工具会先显示确认信息，再返回工作区状态、AI 模块/路线和任务相关源码；若仅有事实索引，会明确返回 inventory-only 并建议运行 maimai.deepAnalyzeProject，不会伪造尚未生成的模块路线。

能力边界

• 默认“按需取证”是 AI 面向整个 Workspace Map 自主决定读取范围，并在容量内生成路线；它不保证触达全部源码。设置“工作区路线 → 完整覆盖”后，码脉会由本地生成确定性源码分片计划，以有界并发逐片读取、分层归并和断点审计；若仍有失败或部分分片，不会报告为完整成功。
• 模型输出只代表本次静态上下文，不能证明生产状态、运行时拓扑或业务正确性。
• 工作区事实索引默认排除依赖、构建产物、缓存和版本控制目录；可用 include/exclude glob 客制化。
• 没有 AI 时仍可使用真实文件搜索、符号范围、源码定位、内容哈希和证据校验，但不会生成路线、解释、学习卡或回答。
• 码脉不会下载模型，也不会替用户开启远程发送。
• GCMP/Copilot 模式使用 VS Code 的授权、额度与 Provider 生命周期；模型被移除或扩展不在同一扩展宿主时，码脉会要求重新发现，不会转而读取其内部客户端或 SecretStorage。

TODO

• [x] 全量文件深度预精读：收口完整覆盖概览中的内部归并文案，并在脉络页提供高并发、可恢复、可审计且受存储容量约束的全工作区 deep 精读队列。（0.19.5）
• [x] 学习知识体系 V3：按文件角色与跨文件调用链生成知识簇，严格拆分 408/计算机基础通用知识、业务实践与项目现场，并加入选择题、填空题和题目级掌握记录。
• [x] 主题学习：直接复用路线与文件深度精读，区分项目讲解、通用基础与业务实践；按需补教学，独立全库扫描作为可选扩展，轻量 preview 不额外生成知识。
• [x] 文件精读模型路由与调度：代码脉络可独立选择接入方案，使用受限结构化输出，并以有限并发和可恢复错误重试运行自动预精读。
• [x] 全局本地脉络与随机学习流：脉络默认逐个建立相关代码文件的本地符号骨架，学习从通用去重知识池随机换组，切换过程不调用模型。
• [x] 工作区变更并发理解：把多仓库修改按稳定文件分片并发取证、独立保存断点，再归并为可暂停、可追溯并能联动路线/脉络、学习、问答的 AI 变更解读。
• [x] AI 接入方案历史：保存最近使用的模型连接，隔离第三方凭据，并支持在设置页快速切换、重命名与删除。
• [x] 重点脉络与知识池轮换：由 AI 区分主干、关键与辅助节点，合并多处出现的同一知识点并保留全部源码位置，扩充学习容量并支持随机“换一组”。
• [x] 大型项目完整覆盖：支持按需取证与完整覆盖两种模式；完整模式按源码分片并行分析，持久化分片工件，最终显示文件、字符、分片和失败覆盖审计。
• [x] 慢速后台通道适配：连通性测试超时放宽到 60 秒；深读/精读单请求超过 15 秒未返回时补充等待进度；问答区分“等待首个输出”与“正在接收输出”。

参考与许可

产品闭环参考 Analect 公开描述中的层级摘要、点击跳转和内容哈希缓存；信息结构吸收 Shithub 的仓库路径与高密度代码浏览习惯。代码、品牌、文案、图像与布局均为重新实现。详见 docs/REFERENCE_RESEARCH.md。

MIT，完整条款见 LICENSE。

使用与隐私

1. 在 VS Code 中打开代码工作区，进入“码脉”侧栏，在设置中选择模型服务。
2. 可以连接本机 Ollama、用户配置的 Chat Completions 兼容服务，或 VS Code 提供的语言模型。扩展不内置 API Key，也不包含模型额度。
3. 用户确认后才启动 AI 分析。使用远程服务会把所选分析范围内的源码或摘要发送至该模型服务；远程发送默认关闭，可在设置中明确允许。
4. API Key 通过 VS Code SecretStorage 保存；调用诊断日志不记录密钥、完整提示、源码或回答正文。
5. 路线、文件精读、学习结果和断点保存在当前扩展的本地工作区存储中，可通过设置中的缓存管理清理。

商店版发布者为 idtw2333。此前发布者为 local-first-lab 的离线版本属于另一扩展身份，其模型凭据与学习历史不会自动迁移到商店版；旧版本数据仍属于原扩展。