内容
<div align="center">
<img src="./assets/banner.svg" width="100%" alt="Polyprompt — 使用 Claude、Codex 或 Gemini 在您熟悉的语言中编码，同时学习新语言" />
<br/>
<p align="center">
<img alt="许可证：MIT" src="https://img.shields.io/badge/License-MIT-22c55e?style=flat-square">
<img alt="Node >= 18.18" src="https://img.shields.io/badge/Node-%E2%89%A5%2018.18-339933?style=flat-square&logo=nodedotjs&logoColor=white">
<img alt="TypeScript 5.7" src="https://img.shields.io/badge/TypeScript-5.7-3178c6?style=flat-square&logo=typescript&logoColor=white">
<img alt="MCP 服务器" src="https://img.shields.io/badge/MCP-server-a78bfa?style=flat-square">
<img alt="测试：175 通过" src="https://img.shields.io/badge/tests-175%20passing-22c55e?style=flat-square">
<img alt="欢迎 PR" src="https://img.shields.io/badge/PRs-welcome-2dd4bf?style=flat-square">
</p>
<p align="center">
<img alt="与 Claude、Codex 和 Gemini 兼容" src="https://img.shields.io/badge/works%20with-Claude%20%C2%B7%20Codex%20%C2%B7%20Gemini-60a5fa?style=flat-square">
<img alt="引擎：MCP 采样" src="https://img.shields.io/badge/engine-MCP%20sampling%20(no%20extra%20key)-f59e0b?style=flat-square">
</p>
### **使用您熟悉的语言与 Claude、Codex 或 Gemini 编码 — 同时学习新语言**
</div>
---
Polyprompt 是一个 [MCP](https://modelcontextprotocol.io) 服务器。您可以编写编码提示，使用的语言是您**熟悉的语言**（例如意大利语）；Polyprompt 会将其翻译成您想要**学习**的语言（例如英语），AI 代理会在该语言中工作，同时将每个有用的新单词保存并通过**间隔重复**的方式复习。
您在学习语言的过程中，可以被动地、自然地学习，不需要额外的学习习惯，只需使用您已经付费的 AI 订阅服务 — **无需额外的 API 密钥**。
```text
您： "crea un endpoint REST per gli utenti"
↓ 翻译工具
Polyprompt：意大利语 → 英语
"create a REST endpoint for users"
端点 — punto di accesso （名词）· 用户 — utenti （名词）
↓
代理构建功能；新单词进入您的复习卡组。
```
---
## 两种学习方式
Polyprompt 支持 **两种** 学习方式 — 在编辑器中纠正和沉浸式学习 — 同时适用于您正在开发的项目。
| 模式 | 您编写… | Polyprompt 提供… |
| --- | --- | --- |
| **沉浸式** | **熟悉的语言**（意大利语） | **目标语言**（英语）+ 词汇表，您可以通过潜移默化的方式学习 |
| **辅导** | **目标语言**（英语） | **错误纠正**，每个错误都用**您的熟悉语言**解释，并提供改进版本 |
```text
辅导模式 — 您尝试用英语编写：
您： "add validate to the form and create a users"
↓ 纠正工具
Polyprompt： "add validation to the form and create a user"
"add validate" → "add validation" — 'validate' 是动词；需要名词
"create a users" → "create a user" — 在 'a' 后面应该使用单数
↓
代理构建功能；您刚刚学习了两个修正 — 用意大利语。
```
代理根据您编写的语言（或固定为 `mode: immersion | tutor`）自动选择方向。
---
## 为什么
大多数开发人员通过潜移默化的方式学习技术英语 — 但这种方式效率低下、缓慢且存在知识盲点。Polyprompt 将您已经编写的数千个提示转化为刻意、间隔的语言练习，无需额外的学习习惯。您可以输入熟悉的语言，输出目标语言，同时记住词汇。
- **沉浸式，而不是摩擦** — 用您的语言思考，在您正在学习的语言中交付。
- **使用您的订阅服务** — 翻译运行在主机模型上，通过 MCP *采样*，无需额外的 API 密钥或配置。
- **适用于所有 MCP 客户端** — Claude Code、Codex CLI、Gemini CLI 以及其他 MCP 客户端。
- **真正的间隔重复** — SM-2 调度器将遇到的单词转化为持久的记忆。
---
## 快速入门
一条命令即可安装 Polyprompt，选择您的语言并连接到它找到的所有 AI 客户端（Claude Code、Codex、Gemini） — 所有操作均在一步完成：
```bash
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/DisSa12/polyprompt/main/install.sh | sh
# Windows (PowerShell)
irm https://raw.githubusercontent.com/DisSa12/polyprompt/main/install.ps1 | iex
```
针对单个客户端使用 `--client claude`（sh）或 `-Client claude`（PowerShell）。
如果您更喜欢手动安装，只需两个简单的步骤：
```bash
npm install -g polyprompt # 1. 安装（Node 18+）；"npx -y polyprompt <cmd>" 也有效
polyprompt setup # 2. 选择语言 + 自动连接您的 AI 客户端
# polyprompt init --native it --target en # 仅限语言设置，无客户端连接
```
然后直接编码。当您用意大利语编写时，代理调用 `translate`，在英语中工作，并向您展示您用英语说的内容以及新单词。
> **提示：** 询问您的代理一次 — *"使用 Polyprompt 沉浸模式"* — 或加载服务器公开的 `immersion` 提示，以便它始终翻译您的提示。
---
## 首次运行
您在终端中首次运行 `polyprompt init` 时，它将引导您完成快速的**语言选择器** — 选择您**思考的语言**和您想要**学习的语言**（按 Enter 键选择默认值，或输入 `?` 列出所有 30+ 种语言）。如果您已经知道自己想要的语言，或者使用脚本编写，可以直接传递 `--native`/`--target` 参数，跳过提示。
<div align="center">
<img src="./assets/setup.svg" width="82%" alt="polyprompt init — 交互式首次运行语言选择器，询问您的熟悉语言和目标语言" />
</div>
---
## 自适应级别
Polyprompt 根据您的水平和成长提供帮助。每次您用目标语言编写，辅导模式会评估您的代码质量；如果您一直写得很好，Polyprompt 会自动提高您的 CEFR 水平。随着您的水平提高，它会逐渐将解释语言从您的熟悉语言切换到目标语言：
| 您的水平 | 解释语言 |
| --- | --- |
| A1 – A2 | 您的熟悉语言 |
| B1 | 您的熟悉语言，保留目标语言的关键术语 |
| B2 | 两种语言的混合 |
| C1 | 大部分是目标语言 |
| C2 | 全部是目标语言 |
因此，初学者会在自己的语言中得到温和的指导，而高级学习者则完全沉浸在目标语言中。您可以通过 `POLYPROMPT_NO_AUTO_LEVEL=1` 关闭此功能，或随时使用 `polyprompt config --level B1` 固定级别。
---
## 保持更新
Polyprompt 会自行更新。日常命令会运行安静、有节制的检查（每天最多一次），并在发布新版本时在后台更新 — 无论您是通过 npm 全局安装还是从 git 克隆安装。立即强制更新，使用 `polyprompt update`，或使用 `POLYPROMPT_NO_UPDATE=1` 关闭自动检查（它永远不会在 CI 中运行，也不会在 MCP 服务器为客户端提供服务时运行）。
---
## 工作原理
```mermaid
flowchart LR
U["您"] -->|"用意大利语编写（熟悉语言）"| H["Claude / Codex / Gemini"]
U -->|"用英语编写（目标语言）"| H
H -->|"翻译 · 沉浸式"| T["Polyprompt MCP 服务器"]
H -->|"纠正 · 辅导"| T
T -->|"采样 · 您的订阅服务"| H
T -->|"英语文本 / 纠正 + 词汇表"| H
H -->|"构建功能"| U
T -. 保存词汇 .-> G[("glossary.json · SM-2 卡组")]
```
1. 主机 AI 调用 **`translate`** 工具，输入您的熟悉语言提示。
2. Polyprompt 翻译它 — 默认通过 **MCP 采样**，即询问主机 AI 本身进行翻译（您的订阅服务，无需额外的密钥）。如果采样不可用且未设置 API 密钥 — 或配置的引擎在调用时失败 — 它返回 *instruct-mode* 指导，以便代理翻译提示本身并通过 `record_translation` 记录它。**学习循环永远不会中断。**
3. 新词汇保存在 `~/.polyprompt/glossary.json` 中，并安排复习。
4. 代理使用翻译后的文本执行您的请求。
---
## 工具
| 工具 | 功能 |
| --- | --- |
| `translate` | **沉浸式** — 翻译熟悉语言的提示；保存新单词。 |
| `correct` | **辅导** — 纠正目标语言的写作；在您的熟悉语言中解释每个错误。 |
| `record_translation` | 记录代理自己进行的翻译（instruct-mode / 手动）。 |
| `explain` | 用您的熟悉语言解释一个单词或短语，并提供示例。 |
| `review` | 列出因间隔重复而需要复习的词汇。 |
| `record_review` | 给回忆评分（0-5）并重新安排卡片。 |
| `stats` | 显示进度：收集的单词、掌握的单词、到期日期、连胜记录。 |
| `config` | 查看或更改语言对、级别、模式和引擎。 |
它还公开了 **`immersion`** 和 **`tutor`** 提示，为主机 AI 提供行为说明。
---
## CLI
同一个引擎可从您的终端使用：
```bash
polyprompt translate "aggiungi validazione al form" --provider mock # 沉浸式
polyprompt correct "add validate to the form" --provider mock # 辅导
polyprompt explain "endpoint"
polyprompt review --limit 10
polyprompt grade "endpoint" 4 # 给回忆评分（0-5）并重新安排
polyprompt stats
polyprompt config --mode tutor --level B1 # 切换模式 / 级别
polyprompt languages # 列出支持的语言
polyprompt setup --client claude # 将 Polyprompt 连接到您的 AI 客户端
polyprompt update # 立即更新到最新版本
polyprompt uninstall --purge # 断开与客户端的连接 + 删除您的数据
```
> `mock` 是一个内置的离线引擎 — 在没有模型的情况下尝试 Polyprompt 很方便。
> 它只支持意大利语和英语；对于其他语言，请使用 `sampling` 或 API 密钥引擎。
---
## 配置
存储在 `~/.polyprompt/config.json`（使用 `POLYPROMPT_HOME` 覆盖目录）：
| 字段 | 含义 | 默认值 |
| --- | --- | --- |
| `nativeLang` | 您思考的语言（ISO 639-1） | `it` |
| `targetLang` | 您正在学习的语言 | `en` |
| `level` | 您的 CEFR 级别 `A1`–`C2`（调整难度） | `A2` |
| `mode` | 默认方向：`immersion` 或 `tutor` | `immersion` |
| `provider` | 翻译引擎（见下文） | `auto` |
### 引擎
| `provider` | 源 | 需要 |
| --- | --- | --- |
| `auto` *(默认)* | 最佳可用，按顺序：采样 → Anthropic → OpenAI → Gemini（第一个准备好的获胜者；`mock` 永远不会自动选择） | — |
| `sampling` | 主机 AI 通过 MCP 采样 | 支持采样的 MCP 客户端 |
| `anthropic` | Anthropic API | `ANTHROPIC_API_KEY` |
| `openai` | OpenAI（或兼容）API | `OPENAI_API_KEY`（可选 `POLYPROMPT_OPENAI_BASE_URL`） |
| `gemini` | Google Gemini API | `GEMINI_API_KEY` |
| `mock` | 离线词典（仅限意大利语和英语） | — （演示/测试） |
模型覆盖：`POLYPROMPT_MODEL`，或每个引擎的 `POLYPROMPT_ANTHROPIC_MODEL` / `POLYPROMPT_OPENAI_MODEL` / `POLYPROMPT_GEMINI_MODEL`。
行为开关：`POLYPROMPT_NO_AUTO_LEVEL=1` 禁用自动升级；`POLYPROMPT_NO_UPDATE=1` 禁用后台自我更新。
---
## 客户端设置
运行 `polyprompt install <client>` 以获取复制粘贴配置。简而言之：
**Claude Code**
```bash
claude mcp add polyprompt -- polyprompt mcp
```
**Codex CLI** — `~/.codex/config.toml`
```toml
[mcp_servers.polyprompt]
command = "polyprompt"
args = ["mcp"]
```
**Gemini CLI** — `~/.gemini/settings.json`
```json
{ "mcpServers": { "polyprompt": { "command": "polyprompt", "args": ["mcp"] } } }
```
参见 [`examples/`](./examples) 以获取现成的配置文件，包括一个 Claude Code 技能，该技能会自动开启沉浸式行为。
---
## 卸载
```bash
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/DisSa12/polyprompt/main/uninstall.sh | sh
# Windows (PowerShell)
irm https://raw.githubusercontent.com/DisSa12/polyprompt/main/uninstall.ps1 | iex
# 或手动：
polyprompt uninstall --purge # 从每个客户端断开连接（+ 删除本地数据）
npm uninstall -g polyprompt
```
`uninstall` 从您的 MCP 客户端（Claude Code、Codex、Gemini）删除 Polyprompt；`--purge` 还会删除您的本地配置和词汇表。
---
## 开发
```bash
npm install
npm run build # 编译到 dist/
npm test # vitest（单元测试 + 内存 MCP 集成 + 真实 stdio 连接）
npm run typecheck # tsc --noEmit
npm run dev -- translate "ciao" --provider mock # 从源代码运行 CLI
```
代码库很小且结构清晰：纯 SRS/存储逻辑（`src/glossary`）、引擎无关提供者（`src/providers`）、一个将它们结合在一起的运行时（`src/runtime.ts`）和一个薄的 MCP/CLI 接口（`src/server`、`src/cli.ts`）。
> 在 **两次对抗性多智能体审查通过** 中构建和强化 — 每个确认的发现都已应用，**175 个测试** 通过。
---
## 路线图
- **错误卡组** — 用于辅导模式下找到的纠正的间隔重复，而不是词汇。
- 更丰富的复习 UX（cloze，听力）和导出到 Anki。
- 按项目分类的词汇表。
## 许可证
MIT — 参见 [LICENSE](./LICENSE)。
