Extension Chinese Reader（插件中文介绍）

一个 VS Code 插件：当你安装新插件、或在扩展商店里点开某个插件时，自动读取它的 README 与描述，翻译成中文，并在独立面板中展示，同时用大模型为你生成一段通俗易懂的「插件简介」，并显示本次翻译消耗的 token 数量。

目标：让你不用再逐字啃英文 README，一眼看懂每个插件是干什么的、怎么用。

✨ 功能特性

• 自动检测新安装插件：启动时记录已安装插件基线，之后每 3 秒轮询一次，发现新装插件立即触发翻译。
• 商店详情页自动触发：在扩展商店里点击某个（尚未安装的）插件、弹出介绍页时，自动从 Marketplace 拉取信息并翻译展示，无需安装。
• 多翻译引擎：支持 llm（大模型，质量最高，推荐）、mymemory（免费无需密钥）、bing（微软翻译 API）、none（不翻译，仅展示原文）。
• LLM 详细插件简介：使用大模型根据插件名称、官方描述和 README，生成一段 150~300 字的中文简介，概括用途与核心亮点（仅 llm 模式可用）。
• Token 用量统计：面板底部显示本次翻译消耗的 token 数（输入 / 输出 / 总计）。LLM 模式为接口返回的精确值，免费接口为按字符估算值并明确标注。
• Markdown 渲染：在 Webview 面板中渲染翻译后的内容，支持标题、代码块、行内代码、列表、表格、链接、图片、引用等。
• 代码与图片保护：翻译时自动暂存代码块、行内代码与图片，翻译完成后原样还原，避免被翻译器破坏。
• 手动命令：可手动翻译任意已安装插件、重新打开最近一次的介绍。
• 失败兜底：单段翻译失败时保留原文，不会导致整体失败；全部失败时给出错误提示与解决建议。

🚀 安装

方式一：从 VSIX 安装（推荐）

1. 获取 extension-chinese-reader-0.0.1.vsix 文件。
2. 打开 VS Code 扩展面板（Ctrl+Shift+X）。
3. 点击右上角 ... 菜单 → 从 VSIX 安装…（Install from VSIX…） → 选择该文件。

或命令行：

code --install-extension extension-chinese-reader-0.0.1.vsix

方式二：从源码运行（开发）

npm install
npm run compile

在 VS Code 中按 F5 启动扩展开发宿主（Extension Development Host），即可测试。

📖 使用方法

自动触发（无需任何操作）

• 安装新插件后：插件自动检测并打开中文介绍面板。
• 在商店点开插件时：自动拉取并翻译该插件的介绍（即使尚未安装）。

面板标题会显示「翻译中: xxx」，翻译完成后变为「插件介绍: xxx」。长文档可能需要 10~30 秒。

手动命令

按 Ctrl+Shift+P（macOS 为 Cmd+Shift+P）打开命令面板，输入「插件中文介绍」：

面板内容说明

打开的介绍面板从上到下依次为：

1. 状态提示条（仅翻译中 / 失败时显示）。
2. 元信息：插件名称、安装状态徽标（已安装 / 商店未安装）、插件 ID、发布者、版本。
3. 官方描述（已翻译）。
4. 📖 插件简介（仅 llm 模式且生成成功时显示）：大模型撰写的详细中文介绍。
5. README 正文（已翻译，Markdown 渲染）。
6. 🔢 Token 用量：本次翻译消耗的 token 统计。

⚙️ 设置项

在设置中搜索 extChineseReader 即可修改。

🔌 翻译服务配置详解

llm（推荐，质量最高）

使用任意 OpenAI 兼容 的大模型接口翻译，并额外生成「插件简介」。支持本地 Ollama 与各类云端服务。

本地 Ollama 需先启动：ollama serve，并拉取模型：ollama pull qwen3.8:27b-nothink。

mymemory（免费，无需密钥）

• 无需任何配置，开箱即用。
• 免费接口有速率限制，长文档可能较慢或偶发失败，可稍后重试。
• 单次请求约 500 字符上限，插件会自动分段。

bing（微软翻译 API）

• 需在 Azure 门户 创建 Translator 资源，获取 bingApiKey 与 bingRegion。
• 质量稳定，但需要付费/试用资源。

none（不翻译）

• 不调用任何翻译接口，直接展示原文 README 与描述。
• 适合离线环境或仅想查看原文的场景。

❓ 常见问题

Q：为什么没有「插件简介」？ A：简介仅在 provider 为 llm 且生成成功时显示。若使用 mymemory / bing / none，或 LLM 调用失败，该区块会自动隐藏，不影响其余翻译内容。

Q：token 用量是精确的吗？ A：llm 模式下为接口返回的精确值；mymemory / bing 不返回 usage，插件按字符经验值估算（英文约 4 字符/token、中文约 1.5 字符/token），并在面板中标注「估算值」。

Q：翻译失败怎么办？ A：面板会显示错误原因。常见原因是免费接口被限流，可稍后重试；或改用 llm（推荐）/ bing。单段失败会保留原文，不会导致整体失败。

Q：为什么不能直接改写商店原生的扩展详情页？ A：VS Code 没有提供公开 API 来改写原生的「扩展详情页面」（Marketplace Webview）。因此本插件采用可行的替代方案：检测到新插件安装或商店点开插件后，读取其 README 并翻译，在独立面板中展示中文介绍。这是目前在不修改 VS Code 内部实现前提下最稳定的做法。

Q：如何排查商店页识别问题？ A：运行命令 插件中文介绍: [调试] 查看当前 Tab 结构，在「插件中文介绍 Debug」输出面板中查看当前所有 Tab 的 input 结构与解析出的扩展 ID。

🛠️ 本地开发

npm install        # 安装依赖
npm run compile    # 编译 TypeScript 到 out/
npm run watch      # 监听模式，自动重新编译

按 F5 启动扩展开发宿主进行测试。

📦 打包发布

npm install -g @vscode/vsce
# 确认 package.json 中的 publisher 字段
npx vsce package

打包前会自动执行 vscode:prepublish（即 npm run compile），确保 out/ 为最新代码。产物为 extension-chinese-reader-<version>.vsix。

📁 目录结构

├── package.json          # 插件清单（命令、设置、入口）
├── tsconfig.json
├── src/
│   ├── extension.ts      # 入口：检测新安装 / 商店页、编排流程
│   ├── translator.ts     # 翻译逻辑（LLM / MyMemory / Bing）+ 简介生成 + token 统计
│   ├── readerPanel.ts    # Webview 面板 + 极简 Markdown 渲染
│   └── marketplace.ts    # 从 VS Code Marketplace 拉取未安装插件信息
└── out/                  # 编译产物

📄 许可证

MIT