harness-auto-docs 0.3.2 → 0.3.3

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

@@ -0,0 +1,68 @@
+# Design: Multi-Provider Model Support
+
+**Date:** 2026-04-03
+**Status:** Approved
+**Scope:** Add support for Qwen, 智谱 (Zhipu), DeepSeek, 豆包 (Doubao), Kimi, and Grok AI models
+
+---
+
+## Overview
+
+Extend `harness-auto-docs` to support six additional AI model providers. Each provider exposes an OpenAI-compatible Chat Completions API, so each will be implemented as an individual provider class (matching the existing `openai.ts` pattern) pointing to the provider's base URL.
+
+Each provider uses its own dedicated API key environment variable — keys are not shared.
+
+---
+
+## New Provider Files
+
+Six new files under `src/ai/`, one per provider:
+
+| File | Class | Model prefix | Base URL |
+|------|-------|-------------|---------|
+| `src/ai/qwen.ts` | `QwenProvider` | `qwen-` | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
+| `src/ai/zhipu.ts` | `ZhipuProvider` | `glm-` | `https://open.bigmodel.cn/api/paas/v4` |
+| `src/ai/deepseek.ts` | `DeepSeekProvider` | `deepseek-` | `https://api.deepseek.com` |
+| `src/ai/doubao.ts` | `DoubaoProvider` | `doubao-` | `https://ark.cn-beijing.volces.com/api/v3` |
+| `src/ai/kimi.ts` | `KimiProvider` | `moonshot-` | `https://api.moonshot.cn/v1` |
+| `src/ai/grok.ts` | `GrokProvider` | `grok-` | `https://api.x.ai/v1` |
+
+Each file is structurally identical to `src/ai/openai.ts`, using the `openai` SDK with a custom `baseURL`.
+
+---
+
+## Environment Variables
+
+Each provider requires its own API key. Missing keys cause the CLI to exit with a clear error.
+
+| Provider | Env var |
+|----------|---------|
+| Qwen | `QWEN_API_KEY` |
+| 智谱 | `ZHIPU_API_KEY` |
+| DeepSeek | `DEEPSEEK_API_KEY` |
+| 豆包 | `DOUBAO_API_KEY` |
+| Kimi | `KIMI_API_KEY` |
+| Grok | `GROK_API_KEY` |
+
+---
+
+## `selectAI` Changes (`src/cli.ts`)
+
+Extend the `selectAI` function with new prefix branches. Each branch reads the provider-specific env var via `requireEnv` and instantiates the corresponding provider.
+
+The error message for unknown models is updated to list all supported prefixes.
+
+---
+
+## README Updates
+
+Add a table row for each new provider in the "Supported models" section, showing the model prefix, env var, and example model name.
+
+---
+
+## What Is Not Changed
+
+- `AIProvider` interface — no changes needed
+- Existing providers (`AnthropicProvider`, `OpenAIProvider`, `MiniMaxProvider`) — untouched
+- Platform providers, diff logic, generator — untouched
+- No new tests required (provider classes are thin wrappers; existing test patterns do not test provider instantiation)

package/examples/github-workflow.yml

@@ -27,6 +27,14 @@ jobs:
       - name: Generate and PR Harness Engineering docs
         run: npx harness-auto-docs@latest
         env:
-          AI_MODEL: claude-sonnet-4-6          # or gpt-4o
-          AI_API_KEY: ${{ secrets.AI_API_KEY }}
+          AI_MODEL: claude-sonnet-4-6          # or gpt-4o, MiniMax-Text-01, qwen-turbo, etc.
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}   # for claude-* models
+          # OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}       # for gpt-* models
+          # MINIMAX_API_KEY: ${{ secrets.MINIMAX_API_KEY }}     # for MiniMax-* models
+          # QWEN_API_KEY: ${{ secrets.QWEN_API_KEY }}           # for qwen-* models
+          # ZHIPU_API_KEY: ${{ secrets.ZHIPU_API_KEY }}         # for glm-* models
+          # DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}   # for deepseek-* models
+          # DOUBAO_API_KEY: ${{ secrets.DOUBAO_API_KEY }}       # for doubao-* models
+          # KIMI_API_KEY: ${{ secrets.KIMI_API_KEY }}           # for moonshot-* models
+          # GROK_API_KEY: ${{ secrets.GROK_API_KEY }}           # for grok-* models
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-auto-docs",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Auto-generate Harness Engineering docs on git tag",
   "type": "module",
   "bin": {

package/src/ai/deepseek.ts

@@ -0,0 +1,20 @@
+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 ?? '';
+  }
+}

package/src/ai/doubao.ts

@@ -0,0 +1,20 @@
+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 ?? '';
+  }
+}

package/src/ai/grok.ts

@@ -0,0 +1,20 @@
+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 ?? '';
+  }
+}

package/src/ai/kimi.ts

@@ -0,0 +1,20 @@
+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 ?? '';
+  }
+}

package/src/ai/qwen.ts

@@ -0,0 +1,20 @@
+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 ?? '';
+  }
+}

package/src/ai/zhipu.ts

@@ -0,0 +1,20 @@
+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 ?? '';
+  }
+}

package/src/cli.ts

@@ -9,6 +9,12 @@ import { GitLabProvider } from './providers/gitlab.js';
 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';
 import type { PlatformProvider } from './providers/interface.js';
 
@@ -36,11 +42,19 @@ function detectPlatform(): PlatformProvider {
   return new GitHubProvider(token);
 }
 
-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.`);
+function selectAI(model: string): AIProvider {
+  if (model.startsWith('claude-')) return new AnthropicProvider(requireEnv('ANTHROPIC_API_KEY'), model);
+  if (model.startsWith('gpt-')) return new OpenAIProvider(requireEnv('OPENAI_API_KEY'), model);
+  if (model.startsWith('MiniMax-')) return new MiniMaxProvider(requireEnv('MINIMAX_API_KEY'), 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); // Kimi is the product; Moonshot AI is the provider
+  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);
 }
 
@@ -55,7 +69,6 @@ function getDefaultBranch(): string {
 
 async function main() {
   const model = requireEnv('AI_MODEL');
-  const apiKey = requireEnv('AI_API_KEY');
 
   const diff = extractDiff();
 
@@ -66,7 +79,7 @@ async function main() {
 
   console.log(`Generating docs: ${diff.prevTag} → ${diff.currentTag}`);
 
-  const ai = selectAI(model, apiKey);
+  const ai = selectAI(model);
   const targets = selectTargets(diff.fileGroups, diff.changedFiles);
   console.log(`Updating ${targets.length} documents: ${targets.join(', ')}`);
 

package/tests/core/deepseek.test.ts

@@ -0,0 +1,30 @@
+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('');
+  });
+});

package/tests/core/doubao.test.ts

@@ -0,0 +1,30 @@
+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('');
+  });
+});

package/tests/core/grok.test.ts

@@ -0,0 +1,30 @@
+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('');
+  });
+});

package/tests/core/kimi.test.ts

@@ -0,0 +1,30 @@
+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('');
+  });
+});

package/tests/core/qwen.test.ts

@@ -0,0 +1,30 @@
+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('');
+  });
+});

package/tests/core/zhipu.test.ts

@@ -0,0 +1,30 @@
+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('');
+  });
+});