声明 / Credits
本项目代码及文档由 Google Gemini (Model 2.0 Flash Experimental) 协助生成与维护。
The code and documentation of this project were generated with the assistance of Google Gemini.
Code Note Agent 是一个轻量级、单文件 (Single-file) 的网页端代码批量处理工具。它利用现代浏览器的 File System Access API，允许用户直接挂载本地文件夹，调用大语言模型（LLM）对代码进行批量中文注释、逻辑解释或重构。
- 🎛️ 按需处理 (Selective Processing)：
- 文件预览：选择目录后立即列出所有待处理文件清单。
- 混合工作流：引入勾选机制。打钩的文件由 AI 智能处理（加注释），未打钩的文件直接原样复制到输出目录。这使得“仅重构核心代码，保留静态资源”成为可能。
- 📊 实时计数：进度条区域新增
(已处理/总数)实时数值显示，配合百分比和耗时统计，让大规模任务进度一目了然。
- 🛠️ Custom 深度增强：为 Custom（自定义）模式增加了 “手动输入 ID”开关。选中后可手动填入 Endpoint ID（适用于 Azure OpenAI 或私有部署），未选中则自动获取模型列表。
- ⚡️ 即时反馈机制：
- 自动验证：在下拉框切换模型时，立即发送轻量级 Ping 请求验证连通性。
- 真实名称：连接成功后，按钮会尝试显示服务器返回的真实 Model Name（如
ep-xxx (doubao-pro)），让“连接了谁”更加清晰。
- 🐛 缓存隔离修复：彻底修复了 Doubao 和 Custom 模式下 Endpoint ID 缓存共用的 Bug，现在不同服务商的配置互不干扰，切换更丝滑。
- ✨ 多账号隔离：实现了 API Key 按服务商（DeepSeek/Gemini/豆包等）独立存储。切换服务商时自动恢复对应的 Key，无需重复输入。
- 🚀 无缝热切换：增加了断点检测功能。在任务中途切换模型并重新连接后，无需重新挂载文件夹，“启动”按钮自动解锁，实现丝滑切换。
- 🐛 死锁修复：修复了连接失败后按钮状态无法重置的问题。现在修改 Key 或 ID 会立即重置连接状态，允许随时重试。
- 🛡️ 实弹验证：针对豆包（Doubao），连接时增加轻量级探测请求（Ping），确保 Endpoint ID 有效且 Key 正确后才允许通过，杜绝无效配置。
- 🏗️ UI 分离：针对火山引擎架构特点，为豆包设计了独立的 Endpoint ID 输入框，隐藏了不适用的“获取模型列表”下拉框。
- 🧹 逻辑清理：移除了因浏览器 CORS 限制导致无效的自动列表获取逻辑，改为更可靠的手动指定模式。
- 🔒 步骤锁定机制：引入了 Step 1 (连接) -> Step 2 (挂载) -> Step 3 (启动) 的严格状态流转，防止误操作。
- 🖥️ 控制台优化：重写了日志输出逻辑，支持不同类型的日志（成功/警告/错误）高亮显示。
- 🥟 接入豆包：增加了对字节跳动豆包（火山引擎）的支持，解决了 Endpoint ID 与标准模型名不一致的配置问题。
- 🌍 CORS 兼容性探索：初步探索了不同厂商 API 的跨域策略。
- 🔌 协议泛化：重构了底层请求逻辑，兼容 OpenAI 格式接口。
- 🤝 新成员加入：正式支持 DeepSeek（深度求索）和 Kimi (月之暗面)，大幅降低了使用成本并提升了中文理解能力。
- 🚦 环境自检：增加了对
File System Access API的浏览器兼容性检测（Chrome/Edge）。 - 📊 可视化进度：引入了进度条和百分比显示，解决了批量处理时“不知道还要多久”的焦虑。
- 📜 模型列表拉取：实现了连接时自动获取账号下可用模型列表的功能。
- 🧊 冷却机制：增加了指数退避算法（Exponential Backoff），遇到 API 429 限流错误时自动倒计时等待，防止任务中断。
- 🌱 MVP 发布：基于 Google Gemini API 和 File System API 构建了首个单文件版本，实现了本地代码读取、AI 处理、本地写入的最小可行性闭环。
- 📂 本地直连：浏览器直接读写本地硬盘，代码不经过第三方中转服务器，隐私安全。
- 🧠 全模型支持：
- DeepSeek (默认推荐，高性价比)
- Doubao (火山引擎)
- Kimi (月之暗面)
- Gemini (Google)
- Ollama (本地模型支持)
- Custom(兼容所有 OpenAI 格式接口)
- 🛡️ 智能抗干扰：内置指数退避算法，自动处理 HTTP 429 限流错误，带有倒计时冷却提示。
- ⏱️ 实时监控：精准显示处理进度百分比及任务实时耗时。
必须使用支持 File System Access API 的现代浏览器：
- ✅ Google Chrome (推荐)
- ✅ Microsoft Edge
- ❌ Firefox / Safari (暂不支持)
- 打开工具：双击下载的
code_note_agent.html文件。 - Step 1: 连接大脑
- 选择 AI 服务商。
- 输入 API Key（会自动保存）。
- 如果是豆包，还需输入 Endpoint ID。
- 点击 “⚡ 连接并验证”。
- Step 2: 挂载文件
- 点击 “📂 选择源代码文件夹”（Input）。
- 点击 “💾 选择输出文件夹”（Output）。
- Step 3: 启动
- 点击 “🚀 启动智能注释 Agent”。
- 观察控制台日志，等待处理完成。
| 服务商 | Base URL (默认) | 鉴权填空说明 |
|---|---|---|
| DeepSeek | https://api.deepseek.com |
输入 sk- 开头的 API Key |
| Doubao (豆包) | https://ark.cn-beijing.volces.com/api/v3 |
特殊：输入 ep-2024... 格式的接入点 ID |
| Gemini | https://generativelanguage.googleapis.com/v1beta |
输入 Google AI Studio Key |
| Kimi | https://api.moonshot.cn/v1 |
输入 Moonshot API Key |
| Ollama | http://localhost:11434/v1 |
本地运行通常留空即可 |
- 零后端：本工具是纯静态 HTML/JS 页面。
- Key 存储：API Key 仅保存在您本地浏览器的
localStorage中。 - 网络请求：所有代码数据仅在您的浏览器与目标 AI 服务商之间直接传输。
- Core: Vanilla JavaScript (ES6+)
- UI: HTML5 + CSS3 (Flexbox/Grid)
- API: Fetch API (Async/Await) + File System Access API
- 提示词定义；
- 缓存优化；
- 中止行为优化；
License MIT License (开源免费，随意修改)