CodeReadMate · 码阅助手
在源码旁读懂代码：AI 导读、代码批注与持续讨论。说明独立保存，源码保持原样。
CodeReadMate 把源码、导读与讨论放在一起，帮助你理解代码并保留阅读过程中的问题。支持中文说明、Markdown 和本地 Mermaid 图表。
可选直接模式：命令面板执行“代码批注: 设置 AI 结果处理方式（直接发布或预览）”，选择“直接发布／保存”。只需设置一次，后续完整AI回复直接发布、导读完整生成后直接保存；不用逐条采用。也可在设置中开启 aiCodeComments.autoPublishAi，关闭后恢复预览模式（默认关闭）。模式在每次生成开始时确定，修改设置影响下一次生成。
直接模式仍需主动点击生成，不自动调用模型或修改源码。取消、失败或上下文变化时不自动保存；批量导读全部完成才保存，人工说明不自动覆盖。回复继续标明AI与模型，自动发布会明确标记“按设置自动发布”，不冒充人工审核。已有手写回复输入保留；自动发布失败时保留可手动重试的草稿。跨文件上下文的发送前预览不因直接模式而跳过。
在源码旁记录问题、阅读 Python 代码、讨论导读内容，并把批注和说明保存在源码之外。
主要功能
- 代码批注：对选区或插入点添加批注，在侧栏回复、编辑、解决或重新打开。代码变化后跟踪绑定；无法可靠定位时提示重新绑定。
- Word 式审阅：左侧源码、右侧批注卡片，通过连线查看对应关系；可显示已保存的文件概览和代码导读。
- Python 代码导读：按文件、Class、函数生成说明，包含用途、输入输出、流程和有依据的思考问题。源码上方显示摘要，悬浮查看全文。
- 导读追问：从已保存导读进入侧栏讨论，自动引用说明快照并关联代码；同一快照重复点击复用已有讨论。
- AI 回复：逐步显示回复；默认由你检查、采用并发布，也可设置完成后直接发布。模型不能替你修改源码或解决批注。
- 备份与恢复：导出批注、回复、解决状态、代码绑定及导读，支持迁移和恢复预览。
- 项目实验：选择自己的 Python 脚本、解释器及参数，预览后运行；支持取消、超时、原始输出及可选表格/折线/路径视图。
使用要求
- VS Code 1.104.0 或更新版本，可信的文件夹工作区。
- Python 导读需要扩展宿主能够找到 Python 3.8+。可设置
aiCodeComments.pythonPath 为解释器路径；批注本身不需要 Python。
- AI 功能需要 VS Code Language Model API 提供可用模型：在 VS Code 聊天界面添加模型提供方并配置账户。仅安装某个聊天扩展不保证它的模型可供本插件调用。模型用量由提供方计费，插件不附带模型额度。
- 首版主要在 Windows 桌面、本地项目验证。不支持 vscode.dev/Web 或虚拟工作区；远程宿主和其他操作系统未完成同等验收，不作为首发支持承诺。
快速开始
记录一条批注
- 打开项目文件，选中代码或放置光标。
- 右键选择“代码批注: 添加代码批注”，在侧栏输入并发布。
- 使用“回复”“解决”“重新打开”继续审阅。
默认快捷键为 Windows/Linux Ctrl+Alt+M、macOS Cmd+Alt+M。若与输入法或其他扩展冲突，可以在“键盘快捷方式”里修改；右键和命令面板始终可作为入口。
生成 Python 导读
- 打开
.py 文件，在源码上方点击“一键生成导读”，或从命令面板执行同名命令。
- 选择可用模型；默认预览后采用，开启直接模式时完整生成后自动保存。
- 在源码上方点击摘要或悬浮查看全文；也可打开“Python 代码导读”或“Word 式审阅视图”。
生成不会改写源码；批量生成保留人工说明和人工编辑内容。安装新版不会自动重写旧导读；想使用新模板时，需重新生成并采用对应说明。
导读中的“代码事实”仍是 AI 整理，需核对源码引用；“AI 推测”和“待确认的业务要求”分别标注。核实建议不代表已经执行测试，也不证明代码没有缺陷。
追问与 AI 回复
已保存导读的“思考问题”旁点“追问”，或在源码上方点“追问导读”。侧栏自动打开对应讨论，引用导读快照并聚焦回复框。可以直接补充问题；直接模式点击“AI 回复”，预览模式点击“AI 回复草稿”。预览模式下草稿需手动采用并发布；直接模式下成功结果自动发布。
源码或说明已经变化时，先更新并核对说明；未采用的导读候选不能直接创建追问。旧导读没有思考问题栏目时，仍可使用源码入口。
数据、模型与隐私
- 批注保存在 VS Code 的工作区状态中；导读独立保存到项目
.code-comments/guides。默认在保存后向 .code-comments/backups 写本地备份。不会为显示说明而向业务源码插入注释。
- 插件没有自建云端存储或遥测服务。只有主动生成 AI 内容时，才通过 VS Code 模型接口向你选择的提供方发送上下文；账户和凭据由 VS Code/提供方管理，插件不自行收集 API Key。
- AI 回复默认发送当前完整文件和当前批注的全部讨论；可切换仅选区。导读生成发送当前完整 Python 文件；批量生成对不同说明块分别请求，因此可能产生多次模型用量。
- 跨文件上下文须主动开启、选择片段并预览确认，不自动上传整个项目。仍需自行检查代码、讨论和所选片段是否适合发送。
- 导出包含批注正文、代码锚定片段和导读。请把导出文件及
.code-comments 当作项目资料管理；源码不变不等于这些资料不包含代码内容。
- 本地实验按当前用户权限执行所选磁盘脚本，可能产生脚本自身的副作用；预览后才运行，不是沙箱。插件不会自动安装依赖或调用项目函数。
迁移、备份与升级
命令面板执行“导出批注与导读”，保存可迁移 JSON。换电脑、重建工作区或恢复旧数据后，执行“导入／恢复批注”，检查文件映射、冲突和预览结果，再确认恢复。自动备份默认保留10份，可在设置中调整。
正式版扩展 ID 为 zhenqingfan.codereadmate，与本地测试版 local-workspace.ai-code-workspace 不同。VS Code 会把它们视为两个扩展，正式版不会自动读取旧扩展的工作区批注。
- 在旧版打开原项目，执行“导出批注与导读”，保存 JSON 并确认文件已生成。
- 在该工作区禁用旧版，然后安装并启用 CodeReadMate；避免两版同时处理快捷键或写入相同导读文件。
- 在正式版执行“导入／恢复批注”，选择导出文件，核对原项目映射与冲突，再确认恢复。
- 检查批注、回复、解决状态和导读后，再决定是否卸载旧版；保留导出文件和项目本地备份。
原有 aiCodeComments.* 设置键及命令 ID 保持兼容。不要通过复制或修改 VS Code 内部数据库来迁移。
常见情况
- 没有摘要：确认
.py 文件已有采用保存的导读，编辑器 CodeLens 与 aiCodeComments.inlineGuide 已启用，并可找到 Python。
- 没有思考问题：旧说明不会自动更新。重新生成并采用新模板；人工块由批量生成保留，可单独核对后明确替换。
- 没有可用模型：检查 VS Code 的模型提供方配置、登录、网络及账户额度。普通批注、备份和已有导读阅读仍可使用。
- 模型超时或取消：已采用内容保留；批量导读可只重试未完成部分。没有完成的流式正文不作为正式说明保存。
- 代码绑定失联：插件会保留记录，请手动选择正确代码重新绑定，不保证跨任意重构自动定位。
当前范围
导读主要支持 Python。首版导读/Word审阅视图限制为5000行、300000字符；批量导读最多40个待生成块，说明过长或上下文超限会提示。大文件可使用普通侧栏批注；AI 上下文仍受各自容量限制。
修改标准复制/剪切/粘贴行为的 aiCodeComments.trackClipboard 默认开启，用于单选区携带批注；可在设置关闭。外部应用、多选区或无法确认来源的操作不承诺携带批注。
插件辅助理解与审阅代码，不自动修复漏洞，不承诺模型解释或示例已验证。
许可证与反馈
MIT。随包附带本地 Markdown/Mermaid 组件及其许可声明。
遇到问题时，可记录插件版本、VS Code 版本、操作步骤及脱敏后的截图，在扩展市场的问答区反馈。不要公开 API Key、完整私有源码或含敏感内容的备份。
