harness-auto-docs 0.3.2 → 0.3.3

package/docs/superpowers/plans/2026-04-03-multi-provider-models.md

@@ -0,0 +1,802 @@
+# Multi-Provider Model Support Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add support for Qwen, 智谱, DeepSeek, 豆包, Kimi, and Grok AI models, each with its own provider file and dedicated API key env var.
+
+**Architecture:** Six new provider classes (one file each) mirror the existing `OpenAIProvider` — same OpenAI SDK, different `baseURL`. The `selectAI` function in `cli.ts` dispatches on model prefix and reads the appropriate env var. No changes to the `AIProvider` interface or any other module.
+
+**Tech Stack:** TypeScript, `openai` npm SDK, Vitest
+
+---
+
+## File Map
+
+| Action | Path |
+|--------|------|
+| Create | `src/ai/qwen.ts` |
+| Create | `src/ai/zhipu.ts` |
+| Create | `src/ai/deepseek.ts` |
+| Create | `src/ai/doubao.ts` |
+| Create | `src/ai/kimi.ts` |
+| Create | `src/ai/grok.ts` |
+| Create | `tests/core/qwen.test.ts` |
+| Create | `tests/core/zhipu.test.ts` |
+| Create | `tests/core/deepseek.test.ts` |
+| Create | `tests/core/doubao.test.ts` |
+| Create | `tests/core/kimi.test.ts` |
+| Create | `tests/core/grok.test.ts` |
+| Modify | `src/cli.ts` |
+| Modify | `README.md` |
+| Modify | `README_zh.md` |
+| Modify | `README_ja.md` |
+
+---
+
+## Task 1: QwenProvider
+
+**Files:**
+- Create: `src/ai/qwen.ts`
+- Create: `tests/core/qwen.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/core/qwen.test.ts`:
+
+```ts
+import { describe, it, expect, vi } from 'vitest';
+import { QwenProvider } from '../../src/ai/qwen.js';
+
+const mockCreate = vi.fn().mockResolvedValue({
+  choices: [{ message: { content: 'qwen generated content' } }],
+});
+
+vi.mock('openai', () => ({
+  default: vi.fn().mockImplementation(({ baseURL }: { baseURL: string }) => {
+    if (baseURL !== 'https://dashscope.aliyuncs.com/compatible-mode/v1') {
+      throw new Error(`unexpected baseURL: ${baseURL}`);
+    }
+    return { chat: { completions: { create: mockCreate } } };
+  }),
+}));
+
+describe('QwenProvider', () => {
+  it('returns text content from the API response', async () => {
+    const provider = new QwenProvider('test-key', 'qwen-turbo');
+    const result = await provider.generate('write docs for this diff');
+    expect(result).toBe('qwen generated content');
+  });
+
+  it('returns empty string when message content is null', async () => {
+    mockCreate.mockResolvedValueOnce({ choices: [{ message: { content: null } }] });
+    const provider = new QwenProvider('test-key', 'qwen-turbo');
+    const result = await provider.generate('prompt');
+    expect(result).toBe('');
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+npm test tests/core/qwen.test.ts
+```
+
+Expected: FAIL — `QwenProvider` not found.
+
+- [ ] **Step 3: Write implementation**
+
+Create `src/ai/qwen.ts`:
+
+```ts
+import OpenAI from 'openai';
+import type { AIProvider } from './interface.js';
+
+export class QwenProvider implements AIProvider {
+  private client: OpenAI;
+  private model: string;
+
+  constructor(apiKey: string, model: string) {
+    this.client = new OpenAI({ apiKey, baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1' });
+    this.model = model;
+  }
+
+  async generate(prompt: string): Promise<string> {
+    const completion = await this.client.chat.completions.create({
+      model: this.model,
+      messages: [{ role: 'user', content: prompt }],
+    });
+    return completion.choices[0].message.content ?? '';
+  }
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+```bash
+npm test tests/core/qwen.test.ts
+```
+
+Expected: PASS — 2 tests pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/ai/qwen.ts tests/core/qwen.test.ts
+git commit -m "feat: add QwenProvider"
+```
+
+---
+
+## Task 2: ZhipuProvider
+
+**Files:**
+- Create: `src/ai/zhipu.ts`
+- Create: `tests/core/zhipu.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/core/zhipu.test.ts`:
+
+```ts
+import { describe, it, expect, vi } from 'vitest';
+import { ZhipuProvider } from '../../src/ai/zhipu.js';
+
+const mockCreate = vi.fn().mockResolvedValue({
+  choices: [{ message: { content: 'zhipu generated content' } }],
+});
+
+vi.mock('openai', () => ({
+  default: vi.fn().mockImplementation(({ baseURL }: { baseURL: string }) => {
+    if (baseURL !== 'https://open.bigmodel.cn/api/paas/v4') {
+      throw new Error(`unexpected baseURL: ${baseURL}`);
+    }
+    return { chat: { completions: { create: mockCreate } } };
+  }),
+}));
+
+describe('ZhipuProvider', () => {
+  it('returns text content from the API response', async () => {
+    const provider = new ZhipuProvider('test-key', 'glm-4');
+    const result = await provider.generate('write docs for this diff');
+    expect(result).toBe('zhipu generated content');
+  });
+
+  it('returns empty string when message content is null', async () => {
+    mockCreate.mockResolvedValueOnce({ choices: [{ message: { content: null } }] });
+    const provider = new ZhipuProvider('test-key', 'glm-4');
+    const result = await provider.generate('prompt');
+    expect(result).toBe('');
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+npm test tests/core/zhipu.test.ts
+```
+
+Expected: FAIL — `ZhipuProvider` not found.
+
+- [ ] **Step 3: Write implementation**
+
+Create `src/ai/zhipu.ts`:
+
+```ts
+import OpenAI from 'openai';
+import type { AIProvider } from './interface.js';
+
+export class ZhipuProvider implements AIProvider {
+  private client: OpenAI;
+  private model: string;
+
+  constructor(apiKey: string, model: string) {
+    this.client = new OpenAI({ apiKey, baseURL: 'https://open.bigmodel.cn/api/paas/v4' });
+    this.model = model;
+  }
+
+  async generate(prompt: string): Promise<string> {
+    const completion = await this.client.chat.completions.create({
+      model: this.model,
+      messages: [{ role: 'user', content: prompt }],
+    });
+    return completion.choices[0].message.content ?? '';
+  }
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+```bash
+npm test tests/core/zhipu.test.ts
+```
+
+Expected: PASS — 2 tests pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/ai/zhipu.ts tests/core/zhipu.test.ts
+git commit -m "feat: add ZhipuProvider"
+```
+
+---
+
+## Task 3: DeepSeekProvider
+
+**Files:**
+- Create: `src/ai/deepseek.ts`
+- Create: `tests/core/deepseek.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/core/deepseek.test.ts`:
+
+```ts
+import { describe, it, expect, vi } from 'vitest';
+import { DeepSeekProvider } from '../../src/ai/deepseek.js';
+
+const mockCreate = vi.fn().mockResolvedValue({
+  choices: [{ message: { content: 'deepseek generated content' } }],
+});
+
+vi.mock('openai', () => ({
+  default: vi.fn().mockImplementation(({ baseURL }: { baseURL: string }) => {
+    if (baseURL !== 'https://api.deepseek.com') {
+      throw new Error(`unexpected baseURL: ${baseURL}`);
+    }
+    return { chat: { completions: { create: mockCreate } } };
+  }),
+}));
+
+describe('DeepSeekProvider', () => {
+  it('returns text content from the API response', async () => {
+    const provider = new DeepSeekProvider('test-key', 'deepseek-chat');
+    const result = await provider.generate('write docs for this diff');
+    expect(result).toBe('deepseek generated content');
+  });
+
+  it('returns empty string when message content is null', async () => {
+    mockCreate.mockResolvedValueOnce({ choices: [{ message: { content: null } }] });
+    const provider = new DeepSeekProvider('test-key', 'deepseek-chat');
+    const result = await provider.generate('prompt');
+    expect(result).toBe('');
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+npm test tests/core/deepseek.test.ts
+```
+
+Expected: FAIL — `DeepSeekProvider` not found.
+
+- [ ] **Step 3: Write implementation**
+
+Create `src/ai/deepseek.ts`:
+
+```ts
+import OpenAI from 'openai';
+import type { AIProvider } from './interface.js';
+
+export class DeepSeekProvider implements AIProvider {
+  private client: OpenAI;
+  private model: string;
+
+  constructor(apiKey: string, model: string) {
+    this.client = new OpenAI({ apiKey, baseURL: 'https://api.deepseek.com' });
+    this.model = model;
+  }
+
+  async generate(prompt: string): Promise<string> {
+    const completion = await this.client.chat.completions.create({
+      model: this.model,
+      messages: [{ role: 'user', content: prompt }],
+    });
+    return completion.choices[0].message.content ?? '';
+  }
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+```bash
+npm test tests/core/deepseek.test.ts
+```
+
+Expected: PASS — 2 tests pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/ai/deepseek.ts tests/core/deepseek.test.ts
+git commit -m "feat: add DeepSeekProvider"
+```
+
+---
+
+## Task 4: DoubaoProvider
+
+**Files:**
+- Create: `src/ai/doubao.ts`
+- Create: `tests/core/doubao.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/core/doubao.test.ts`:
+
+```ts
+import { describe, it, expect, vi } from 'vitest';
+import { DoubaoProvider } from '../../src/ai/doubao.js';
+
+const mockCreate = vi.fn().mockResolvedValue({
+  choices: [{ message: { content: 'doubao generated content' } }],
+});
+
+vi.mock('openai', () => ({
+  default: vi.fn().mockImplementation(({ baseURL }: { baseURL: string }) => {
+    if (baseURL !== 'https://ark.cn-beijing.volces.com/api/v3') {
+      throw new Error(`unexpected baseURL: ${baseURL}`);
+    }
+    return { chat: { completions: { create: mockCreate } } };
+  }),
+}));
+
+describe('DoubaoProvider', () => {
+  it('returns text content from the API response', async () => {
+    const provider = new DoubaoProvider('test-key', 'doubao-pro-4k');
+    const result = await provider.generate('write docs for this diff');
+    expect(result).toBe('doubao generated content');
+  });
+
+  it('returns empty string when message content is null', async () => {
+    mockCreate.mockResolvedValueOnce({ choices: [{ message: { content: null } }] });
+    const provider = new DoubaoProvider('test-key', 'doubao-pro-4k');
+    const result = await provider.generate('prompt');
+    expect(result).toBe('');
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+npm test tests/core/doubao.test.ts
+```
+
+Expected: FAIL — `DoubaoProvider` not found.
+
+- [ ] **Step 3: Write implementation**
+
+Create `src/ai/doubao.ts`:
+
+```ts
+import OpenAI from 'openai';
+import type { AIProvider } from './interface.js';
+
+export class DoubaoProvider implements AIProvider {
+  private client: OpenAI;
+  private model: string;
+
+  constructor(apiKey: string, model: string) {
+    this.client = new OpenAI({ apiKey, baseURL: 'https://ark.cn-beijing.volces.com/api/v3' });
+    this.model = model;
+  }
+
+  async generate(prompt: string): Promise<string> {
+    const completion = await this.client.chat.completions.create({
+      model: this.model,
+      messages: [{ role: 'user', content: prompt }],
+    });
+    return completion.choices[0].message.content ?? '';
+  }
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+```bash
+npm test tests/core/doubao.test.ts
+```
+
+Expected: PASS — 2 tests pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/ai/doubao.ts tests/core/doubao.test.ts
+git commit -m "feat: add DoubaoProvider"
+```
+
+---
+
+## Task 5: KimiProvider
+
+**Files:**
+- Create: `src/ai/kimi.ts`
+- Create: `tests/core/kimi.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/core/kimi.test.ts`:
+
+```ts
+import { describe, it, expect, vi } from 'vitest';
+import { KimiProvider } from '../../src/ai/kimi.js';
+
+const mockCreate = vi.fn().mockResolvedValue({
+  choices: [{ message: { content: 'kimi generated content' } }],
+});
+
+vi.mock('openai', () => ({
+  default: vi.fn().mockImplementation(({ baseURL }: { baseURL: string }) => {
+    if (baseURL !== 'https://api.moonshot.cn/v1') {
+      throw new Error(`unexpected baseURL: ${baseURL}`);
+    }
+    return { chat: { completions: { create: mockCreate } } };
+  }),
+}));
+
+describe('KimiProvider', () => {
+  it('returns text content from the API response', async () => {
+    const provider = new KimiProvider('test-key', 'moonshot-v1-8k');
+    const result = await provider.generate('write docs for this diff');
+    expect(result).toBe('kimi generated content');
+  });
+
+  it('returns empty string when message content is null', async () => {
+    mockCreate.mockResolvedValueOnce({ choices: [{ message: { content: null } }] });
+    const provider = new KimiProvider('test-key', 'moonshot-v1-8k');
+    const result = await provider.generate('prompt');
+    expect(result).toBe('');
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+npm test tests/core/kimi.test.ts
+```
+
+Expected: FAIL — `KimiProvider` not found.
+
+- [ ] **Step 3: Write implementation**
+
+Create `src/ai/kimi.ts`:
+
+```ts
+import OpenAI from 'openai';
+import type { AIProvider } from './interface.js';
+
+export class KimiProvider implements AIProvider {
+  private client: OpenAI;
+  private model: string;
+
+  constructor(apiKey: string, model: string) {
+    this.client = new OpenAI({ apiKey, baseURL: 'https://api.moonshot.cn/v1' });
+    this.model = model;
+  }
+
+  async generate(prompt: string): Promise<string> {
+    const completion = await this.client.chat.completions.create({
+      model: this.model,
+      messages: [{ role: 'user', content: prompt }],
+    });
+    return completion.choices[0].message.content ?? '';
+  }
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+```bash
+npm test tests/core/kimi.test.ts
+```
+
+Expected: PASS — 2 tests pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/ai/kimi.ts tests/core/kimi.test.ts
+git commit -m "feat: add KimiProvider"
+```
+
+---
+
+## Task 6: GrokProvider
+
+**Files:**
+- Create: `src/ai/grok.ts`
+- Create: `tests/core/grok.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/core/grok.test.ts`:
+
+```ts
+import { describe, it, expect, vi } from 'vitest';
+import { GrokProvider } from '../../src/ai/grok.js';
+
+const mockCreate = vi.fn().mockResolvedValue({
+  choices: [{ message: { content: 'grok generated content' } }],
+});
+
+vi.mock('openai', () => ({
+  default: vi.fn().mockImplementation(({ baseURL }: { baseURL: string }) => {
+    if (baseURL !== 'https://api.x.ai/v1') {
+      throw new Error(`unexpected baseURL: ${baseURL}`);
+    }
+    return { chat: { completions: { create: mockCreate } } };
+  }),
+}));
+
+describe('GrokProvider', () => {
+  it('returns text content from the API response', async () => {
+    const provider = new GrokProvider('test-key', 'grok-2');
+    const result = await provider.generate('write docs for this diff');
+    expect(result).toBe('grok generated content');
+  });
+
+  it('returns empty string when message content is null', async () => {
+    mockCreate.mockResolvedValueOnce({ choices: [{ message: { content: null } }] });
+    const provider = new GrokProvider('test-key', 'grok-2');
+    const result = await provider.generate('prompt');
+    expect(result).toBe('');
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+npm test tests/core/grok.test.ts
+```
+
+Expected: FAIL — `GrokProvider` not found.
+
+- [ ] **Step 3: Write implementation**
+
+Create `src/ai/grok.ts`:
+
+```ts
+import OpenAI from 'openai';
+import type { AIProvider } from './interface.js';
+
+export class GrokProvider implements AIProvider {
+  private client: OpenAI;
+  private model: string;
+
+  constructor(apiKey: string, model: string) {
+    this.client = new OpenAI({ apiKey, baseURL: 'https://api.x.ai/v1' });
+    this.model = model;
+  }
+
+  async generate(prompt: string): Promise<string> {
+    const completion = await this.client.chat.completions.create({
+      model: this.model,
+      messages: [{ role: 'user', content: prompt }],
+    });
+    return completion.choices[0].message.content ?? '';
+  }
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+```bash
+npm test tests/core/grok.test.ts
+```
+
+Expected: PASS — 2 tests pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/ai/grok.ts tests/core/grok.test.ts
+git commit -m "feat: add GrokProvider"
+```
+
+---
+
+## Task 7: Wire providers into `selectAI`
+
+**Files:**
+- Modify: `src/cli.ts`
+
+- [ ] **Step 1: Update imports and `selectAI` in `src/cli.ts`**
+
+Find and replace the existing AI import block:
+
+```ts
+// FIND (replace these 4 lines):
+import { AnthropicProvider } from './ai/anthropic.js';
+import { OpenAIProvider } from './ai/openai.js';
+import { MiniMaxProvider } from './ai/minimax.js';
+import type { AIProvider } from './ai/interface.js';
+
+// REPLACE WITH:
+import { AnthropicProvider } from './ai/anthropic.js';
+import { OpenAIProvider } from './ai/openai.js';
+import { MiniMaxProvider } from './ai/minimax.js';
+import { QwenProvider } from './ai/qwen.js';
+import { ZhipuProvider } from './ai/zhipu.js';
+import { DeepSeekProvider } from './ai/deepseek.js';
+import { DoubaoProvider } from './ai/doubao.js';
+import { KimiProvider } from './ai/kimi.js';
+import { GrokProvider } from './ai/grok.js';
+import type { AIProvider } from './ai/interface.js';
+```
+
+Find and replace the existing `selectAI` function:
+
+```ts
+// FIND (replace this entire function):
+function selectAI(model: string, apiKey: string): AIProvider {
+  if (model.startsWith('claude-')) return new AnthropicProvider(apiKey, model);
+  if (model.startsWith('gpt-')) return new OpenAIProvider(apiKey, model);
+  if (model.startsWith('MiniMax-')) return new MiniMaxProvider(apiKey, model);
+  console.error(`Error: Unknown model "${model}". Use a claude-*, gpt-*, or MiniMax-* model.`);
+  process.exit(1);
+}
+
+// REPLACE WITH:
+function selectAI(model: string, apiKey: string): AIProvider {
+  if (model.startsWith('claude-')) return new AnthropicProvider(apiKey, model);
+  if (model.startsWith('gpt-')) return new OpenAIProvider(apiKey, model);
+  if (model.startsWith('MiniMax-')) return new MiniMaxProvider(apiKey, model);
+  if (model.startsWith('qwen-')) return new QwenProvider(requireEnv('QWEN_API_KEY'), model);
+  if (model.startsWith('glm-')) return new ZhipuProvider(requireEnv('ZHIPU_API_KEY'), model);
+  if (model.startsWith('deepseek-')) return new DeepSeekProvider(requireEnv('DEEPSEEK_API_KEY'), model);
+  if (model.startsWith('doubao-')) return new DoubaoProvider(requireEnv('DOUBAO_API_KEY'), model);
+  if (model.startsWith('moonshot-')) return new KimiProvider(requireEnv('KIMI_API_KEY'), model);
+  if (model.startsWith('grok-')) return new GrokProvider(requireEnv('GROK_API_KEY'), model);
+  console.error(
+    `Error: Unknown model "${model}". Supported prefixes: claude-*, gpt-*, MiniMax-*, qwen-*, glm-*, deepseek-*, doubao-*, moonshot-*, grok-*`
+  );
+  process.exit(1);
+}
+```
+
+- [ ] **Step 2: Build to verify no TypeScript errors**
+
+```bash
+npm run build
+```
+
+Expected: exits 0, `dist/` updated with no errors.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/cli.ts
+git commit -m "feat: wire Qwen, Zhipu, DeepSeek, Doubao, Kimi, Grok into selectAI"
+```
+
+---
+
+## Task 8: Update README files
+
+**Files:**
+- Modify: `README.md`
+- Modify: `README_zh.md`
+- Modify: `README_ja.md`
+
+- [ ] **Step 1: Update the "Supported models" table in `README.md`**
+
+Find and replace the existing table block:
+
+```markdown
+// FIND:
+| Prefix | Provider | Example models |
+|--------|----------|----------------|
+| `claude-*` | Anthropic | `claude-sonnet-4-6`, `claude-opus-4-6`, `claude-haiku-4-5-20251001` |
+| `gpt-*` | OpenAI | `gpt-4o`, `gpt-4o-mini`, `o3` |
+| `MiniMax-*` | MiniMax (Anthropic-compatible) | `MiniMax-Text-01` |
+
+// REPLACE WITH:
+| Prefix | Provider | API key env var | Example models |
+|--------|----------|-----------------|----------------|
+| `claude-*` | Anthropic | `AI_API_KEY` | `claude-sonnet-4-6`, `claude-opus-4-6` |
+| `gpt-*` | OpenAI | `AI_API_KEY` | `gpt-4o`, `gpt-4o-mini`, `o3` |
+| `MiniMax-*` | MiniMax | `AI_API_KEY` | `MiniMax-Text-01` |
+| `qwen-*` | Qwen (阿里云) | `QWEN_API_KEY` | `qwen-turbo`, `qwen-plus`, `qwen-max` |
+| `glm-*` | 智谱 | `ZHIPU_API_KEY` | `glm-4`, `glm-4-flash` |
+| `deepseek-*` | DeepSeek | `DEEPSEEK_API_KEY` | `deepseek-chat`, `deepseek-coder` |
+| `doubao-*` | 豆包 (ByteDance) | `DOUBAO_API_KEY` | `doubao-pro-4k` |
+| `moonshot-*` | Kimi (Moonshot) | `KIMI_API_KEY` | `moonshot-v1-8k`, `moonshot-v1-32k` |
+| `grok-*` | Grok (xAI) | `GROK_API_KEY` | `grok-2`, `grok-beta` |
+```
+
+Also find and replace the `AI_API_KEY` usage description line:
+
+```markdown
+// FIND:
+- `AI_API_KEY` — your Anthropic, OpenAI, or MiniMax API key (repository secret)
+
+// REPLACE WITH:
+- `AI_API_KEY` — your Anthropic, OpenAI, or MiniMax API key (for Qwen/智谱/DeepSeek/豆包/Kimi/Grok use their respective `*_API_KEY` vars — see Supported models below)
+```
+
+- [ ] **Step 2: Apply the same table update to `README_zh.md`**
+
+Find and replace in `README_zh.md`:
+
+```markdown
+// FIND:
+| 前缀 | 提供商 | 示例模型 |
+|------|--------|---------|
+| `claude-*` | Anthropic | `claude-sonnet-4-6`、`claude-opus-4-6`、`claude-haiku-4-5-20251001` |
+| `gpt-*` | OpenAI | `gpt-4o`、`gpt-4o-mini`、`o3` |
+| `MiniMax-*` | MiniMax（Anthropic 兼容） | `MiniMax-Text-01` |
+
+// REPLACE WITH:
+| 前缀 | 供应商 | API 密钥环境变量 | 示例模型 |
+|------|--------|-----------------|---------|
+| `claude-*` | Anthropic | `AI_API_KEY` | `claude-sonnet-4-6`、`claude-opus-4-6` |
+| `gpt-*` | OpenAI | `AI_API_KEY` | `gpt-4o`、`gpt-4o-mini`、`o3` |
+| `MiniMax-*` | MiniMax | `AI_API_KEY` | `MiniMax-Text-01` |
+| `qwen-*` | 通义千问（阿里云） | `QWEN_API_KEY` | `qwen-turbo`、`qwen-plus`、`qwen-max` |
+| `glm-*` | 智谱 AI | `ZHIPU_API_KEY` | `glm-4`、`glm-4-flash` |
+| `deepseek-*` | DeepSeek | `DEEPSEEK_API_KEY` | `deepseek-chat`、`deepseek-coder` |
+| `doubao-*` | 豆包（字节跳动） | `DOUBAO_API_KEY` | `doubao-pro-4k` |
+| `moonshot-*` | Kimi（月之暗面） | `KIMI_API_KEY` | `moonshot-v1-8k`、`moonshot-v1-32k` |
+| `grok-*` | Grok（xAI） | `GROK_API_KEY` | `grok-2`、`grok-beta` |
+```
+
+Also find and replace the `AI_API_KEY` description line:
+
+```markdown
+// FIND:
+- `AI_API_KEY` — 你的 Anthropic、OpenAI 或 MiniMax API 密钥（repository secret）
+
+// REPLACE WITH:
+- `AI_API_KEY` — 你的 Anthropic、OpenAI 或 MiniMax API 密钥（Qwen/智谱/DeepSeek/豆包/Kimi/Grok 请使用各自的 `*_API_KEY` 环境变量，详见下方支持的模型表格）
+```
+
+- [ ] **Step 3: Apply the same table update to `README_ja.md`**
+
+Find and replace in `README_ja.md`:
+
+```markdown
+// FIND:
+| プレフィックス | プロバイダー | 対応モデル |
+|--------------|-------------|-----------|
+| `claude-*` | Anthropic | `claude-sonnet-4-6`、`claude-opus-4-6`、`claude-haiku-4-5-20251001` |
+| `gpt-*` | OpenAI | `gpt-4o`、`gpt-4o-mini`、`o3` |
+| `MiniMax-*` | MiniMax（Anthropic 互換） | `MiniMax-Text-01` |
+
+// REPLACE WITH:
+| プレフィックス | プロバイダー | API キー環境変数 | モデル例 |
+|--------------|------------|----------------|---------|
+| `claude-*` | Anthropic | `AI_API_KEY` | `claude-sonnet-4-6`、`claude-opus-4-6` |
+| `gpt-*` | OpenAI | `AI_API_KEY` | `gpt-4o`、`gpt-4o-mini`、`o3` |
+| `MiniMax-*` | MiniMax | `AI_API_KEY` | `MiniMax-Text-01` |
+| `qwen-*` | Qwen（阿里云） | `QWEN_API_KEY` | `qwen-turbo`、`qwen-plus`、`qwen-max` |
+| `glm-*` | 智谱 AI | `ZHIPU_API_KEY` | `glm-4`、`glm-4-flash` |
+| `deepseek-*` | DeepSeek | `DEEPSEEK_API_KEY` | `deepseek-chat`、`deepseek-coder` |
+| `doubao-*` | 豆包（ByteDance） | `DOUBAO_API_KEY` | `doubao-pro-4k` |
+| `moonshot-*` | Kimi（Moonshot） | `KIMI_API_KEY` | `moonshot-v1-8k`、`moonshot-v1-32k` |
+| `grok-*` | Grok（xAI） | `GROK_API_KEY` | `grok-2`、`grok-beta` |
+```
+
+Also find and replace the `AI_API_KEY` description line:
+
+```markdown
+// FIND:
+- `AI_API_KEY` — Anthropic、OpenAI、または MiniMax の API キー（repository secret）
+
+// REPLACE WITH:
+- `AI_API_KEY` — Anthropic、OpenAI、または MiniMax の API キー（Qwen/智谱/DeepSeek/豆包/Kimi/Grok は各自の `*_API_KEY` 環境変数を使用してください — 詳細はサポートモデル表を参照）
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add README.md README_zh.md README_ja.md
+git commit -m "docs: add Qwen, Zhipu, DeepSeek, Doubao, Kimi, Grok to supported models"
+```