AuraRead
用于工程代码阅读的本地 VS Code 扩展：把实现原理、边界条件和问题关联到代码，用有顺序的阅读路线串起跨文件流程。笔记存入项目 .auraread/，不修改源码、不上传数据。
安装与启动
需要 VS Code 1.96 或更新的稳定版、本地文件夹工作区。
在 VS Code 扩展面板搜索 AuraRead，核对市场详情中的发布者后安装。打开工程文件夹，在活动栏选择 AuraRead。后续发布的新版本可通过 VS Code 扩展更新功能安装。
如果此前安装的 VSIX 使用不同的 Publisher ID，请先停用旧版本，避免两个扩展同时操作同一个项目。项目内 .auraread/ 笔记可以继续使用。
使用
批注
- 在原生编辑器选择代码，右键 添加 AuraRead 批注。没有选区则引用当前行；支持跨行和 UTF-16 位置。
- 选择项目共享或个人范围，填写标题、Markdown 正文；可插入 emoji、加粗、行内代码和列表。保存后显示预览；已有批注默认预览。
- 代码旁的原生批注标记可展开，再点击 打开批注详情。侧栏按文件显示标题；点击即定位、高亮并显示详情。
- 侧栏标题菜单提供搜索，匹配标题、正文和路径；搜索也包含归档笔记。清空查询恢复正常列表。
- 详情提供归档、取消归档、删除和导出；删除可从通知或命令 AuraRead: 撤销删除批注 恢复。撤销记录保留到本次扩展会话结束。
- 个人笔记忽略说明通过 AuraRead: 个人笔记忽略说明 打开。扩展不会修改
.gitignore 或 Git 配置。
代码变化
自动检查由文件/文档事件触发，220ms 合并防抖，只重新计算相关文件中的笔记。不扫描工程所有代码。位置结果仅保存在内存；不会因为浏览、分支切换或 pull 改写笔记。
- 完整片段唯一匹配且可用上下文支持，或重复片段被精确前后文唯一消歧：可以跳转和显示标记。
- 原片段改变，但两侧精确上下文仍唯一：显示 代码已变更，批注待复核，提供当前代码范围供比较。
- 多处无法消歧：位置待确认；重新关联时可选择候选并确认。
- 文件或片段找不到：当前版本无法定位。保留笔记，不推断永久删除。
从“待处理”列表打开笔记，用 对比引用 在 VS Code diff 编辑器比较原始引用与当前代码。无法确定范围时右侧显示完整当前文件。选中正确代码后使用 关联到当前选区；随后核对解释，使用 确认仍然适用 建立新基线；修改正文后也可点击 保存并更新适用基线。原始引用和历次基线永久保留。正文从不被自动改写。
未保存源码可参与当前定位预览，但创建/确认/重新关联持久化引用前须先保存源码。分支切换后以文件变化重新校验；没有改变引用代码的提交不自动改变解释适用版本。
阅读路线
在阅读路线视图创建路线，输入标题、介绍和可见范围。点击路线名称或其右键菜单 管理阅读路线：
- 添加已有批注（稳定 ID 引用），或添加当前编辑器的代码位置。
- 每一步可写说明，调整顺序、移除或修改说明。
- 开始阅读或点击步骤跳转；通过通知按钮或 路线上一步／路线下一步 继续。
- 共享路线不会引用个人笔记；个人路线可以引用共享或个人笔记。路线只跨同一项目内的文件。
删除被引用批注后路线保留该 ID 并提示不可用；撤销删除即可恢复。纯代码步骤保留独立快照；若失效，可移除后从新选区重新添加。
导出
使用详情中的导出，或命令 AuraRead: 导出 Markdown，选择单条批注、路线、项目共享笔记或含个人笔记的整个项目。导出包含正文、路径、代码片段、采集时间和可获得的 Git 提交号；源码缺失仍可导出原始引用。
数据、安全与支持范围
- TypeScript；仅使用稳定 VS Code API。原生 Comments API 负责标记，原生 Tree View 负责导航，Webview 只编辑笔记，不实现代码编辑器。
- 本地
file: 工作区，支持多根隔离。不支持虚拟工作区、浏览器版、远程扩展宿主作为正式支持范围。
- 定义、引用、符号导航完全由已有语言扩展提供。没有正则语义分析或 AI 功能。
- Workspace Trust 受限模式下可以读写笔记，但禁用 Git 调用；Git 使用
execFile 参数数组，不调用 shell、不运行项目代码。
- Markdown 禁用 HTML、图片和链接渲染；CSP 拒绝外部资源、网络和笔记脚本。唯一允许运行的是扩展自己的 nonce 脚本。
.auraread/private/ 是组织约定，不提供加密或访问控制。如需忽略，用户自行加入 .gitignore 或 .git/info/exclude。Git 已跟踪文件不受新忽略规则影响。- 笔记使用同目录临时文件与 rename 原子替换，并检查外部修改冲突。损坏/未来版本笔记列入侧栏错误提示，不会直接覆盖。
安装包包含数据格式、架构与已知限制、验证记录等文档，位于扩展的 docs/ 目录。
验证与限制
0.1.2 已通过 14 项核心测试及真实 VS Code 宿主的持久化、预览、跳转、外部修改和完整重启恢复回归。无选区当前行、空行和反向多行选区均有回归覆盖。尚未完成完整鼠标交互及视觉验收。
本版不支持跨文件自动识别代码移动；无法可靠定位时需要手动重新关联。删除撤销仅在当前扩展会话有效。个人笔记不加密。
