Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@ All notable changes to DreamCoder will be documented in this file.

## [Unreleased]

### Added

- **Provider preset contributor guide.** Adds English and Chinese instructions for adding a built-in provider preset, updating its API tests, and checking connectivity from the settings form (#260).

## [0.9.0] — 2026-11-17

Sessions now work together: they start and message each other, share a project board, and open side chats. The agent can also make slide decks. These notes cover everything since 0.8.0.
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ DreamCoder runs its desktop app and session service locally, bringing model conf
* **Design and clone**: Start from 60+ templates and 156+ design systems with `/design`: the agent interviews you first, then builds a web page or app prototype. It can also clone a website. Results are kept in your project's `dc_artifacts/`, ready to export, keep editing, or compare side by side on a canvas.
* **Plan work on a board**: A project board keeps tasks, owners, reviewers and progress for you and your sessions, across sessions and worktrees.
* **Continue on your phone**: Enable H5 Access to reach desktop sessions from a phone browser on the same LAN. Access across networks requires a reverse proxy you configure yourself.
* **Learn how a coding agent works**: A seven-part source code walkthrough follows one code change through the execution loop, tools, permissions, sessions, and desktop integration. See the [Coding Agent Implementation Guide](docs/tutorial/README.en.md).
* **Learn how a coding agent works**: An eight-part source code walkthrough follows one code change through the execution loop, tools, permissions, sessions, and desktop integration, then shows how to add a provider preset. See the [Coding Agent Implementation Guide](docs/tutorial/README.en.md).

Provider settings and API keys are stored in local files. When you use a cloud model, requests are sent to your chosen provider. See the [privacy notice](PRIVACY.md).

Expand Down Expand Up @@ -180,7 +180,7 @@ The templates and most of the design systems are converted from [Open Design](ht

## 📖 Source Code Walkthrough

To learn how a coding agent works under the hood, read the [Coding Agent Implementation Guide](docs/tutorial/README.en.md) (also available in [Chinese](docs/tutorial/README.md)). The seven-part series follows one small code change through the execution loop, code tools, permissions, sessions and context, streaming and failure recovery, and desktop integration, with source links for each point.
To learn how a coding agent works under the hood, read the [Coding Agent Implementation Guide](docs/tutorial/README.en.md) (also available in [Chinese](docs/tutorial/README.md)). The eight-part series follows one small code change through the execution loop, code tools, permissions, sessions and context, streaming and failure recovery, and desktop integration, then shows how to add a provider preset, with source links for each point.

---

Expand Down
4 changes: 2 additions & 2 deletions README_zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ DreamCoder 在本机运行桌面应用与会话服务,把模型配置、编程
* **设计与复刻**:用 `/design` 从 60+ 个模板和 156+ 套设计系统出发,Agent 先访谈再动手,做出网页或应用原型;也能复刻网站。成果保存在项目的 `dc_artifacts/` 里,可导出、可继续改、可在画布上并排比较。
* **在看板上安排工作**:项目看板为你和会话记录任务、负责人、审核人和进展,跨会话、跨 worktree 保留。
* **从手机接续**:启用 H5 接入后,可在同一局域网内通过手机浏览器访问桌面会话;跨网络访问需要自行配置反向代理。
* **读懂编程智能体**:附带七篇源码导读,沿一次代码修改讲解执行循环、工具、权限、会话与桌面集成,见[《编程智能体实现指南》](docs/tutorial/README.md)。
* **读懂编程智能体**:附带八篇源码导读,沿一次代码修改讲解执行循环、工具、权限、会话与桌面集成,并介绍如何添加 Provider 预设,见[《编程智能体实现指南》](docs/tutorial/README.md)。

Provider 配置和 API Key 保存在本机文件中。使用云端模型时,请求数据会发送给你选择的服务商;详见 [隐私说明](PRIVACY.md)。

Expand Down Expand Up @@ -183,7 +183,7 @@ Provider 配置和 API Key 保存在本机文件中。使用云端模型时,

## 📖 源码导读

想了解编程智能体内部怎样工作,可以读[《编程智能体实现指南》](docs/tutorial/README.md)。系列共七篇,沿一次小的代码修改,依次讲解执行循环、代码工具、权限控制、会话与上下文、流式响应与故障恢复,以及桌面端集成,文中结论都附有源码链接。
想了解编程智能体内部怎样工作,可以读[《编程智能体实现指南》](docs/tutorial/README.md)。系列共八篇,沿一次小的代码修改,依次讲解执行循环、代码工具、权限控制、会话与上下文、流式响应与故障恢复,以及桌面端集成,最后介绍如何添加 Provider 预设,文中结论都附有源码链接。

---

Expand Down
2 changes: 1 addition & 1 deletion docs/general/CONTRIBUTING_en.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ dreamcoder/
└── docs/ # Documentation
```

Provider preset contributions have a focused guide in the website documentation under "Adding Provider Presets".
Provider preset contributions have a focused guide: [Adding a provider preset](../tutorial/07-provider-presets.en.md), part 7 of the Coding Agent Implementation Guide.

## Development Environment

Expand Down
2 changes: 1 addition & 1 deletion docs/general/CONTRIBUTING_zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ dreamcoder/
└── docs/ # 文档
```

如果你要新增 Provider 预设,请先阅读网站技术手册中的“新增 Provider 预设”。
如果你要新增 Provider 预设,请先阅读[《添加 Provider 预设》](../tutorial/07-provider-presets.zh.md)(《编程智能体实现指南》第七篇)。

## 开发环境

Expand Down
101 changes: 101 additions & 0 deletions docs/tutorial/07-provider-presets.en.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
English | [简体中文](./07-provider-presets.zh.md)

# Adding a provider preset

This guide covers adding a provider to DreamCoder's built-in provider list. It follows the preset from its JSON definition to the settings form and the connection test. It does not add a new API protocol or change how the provider runtime works.

The source references below are pinned to commit [`75d9b3b`](https://github.com/GoDiao/dreamcoder/tree/75d9b3bf7572c5feb7b44e4421a7dcb81bb7a21f). Check the current source before using the examples in a later revision.

## Find the preset contract

Built-in presets are listed in [`src/server/config/providerPresets.json`](https://github.com/GoDiao/dreamcoder/blob/75d9b3bf7572c5feb7b44e4421a7dcb81bb7a21f/src/server/config/providerPresets.json). The server imports that file and parses it with the Zod schema in [`providerPresets.ts`](https://github.com/GoDiao/dreamcoder/blob/75d9b3bf7572c5feb7b44e4421a7dcb81bb7a21f/src/server/config/providerPresets.ts). The schema checks every preset when the module loads; an invalid entry prevents the preset list from loading.

Each entry describes a provider endpoint and model defaults:

| Field | Required | Meaning |
| --- | --- | --- |
| `id` | yes | Stable identifier used to associate a saved provider with its preset. |
| `name` | yes | Name shown in the settings form. |
| `baseUrl` | yes | Provider API endpoint. |
| `apiFormat` | yes | One of `anthropic`, `openai_chat`, or `openai_responses`. |
| `defaultModels` | yes | Initial model IDs, optionally with display names. IDs must be non-empty and unique. |
| `defaultFastModel` | no | Initial fast model; use an ID present in `defaultModels`. |
| `needsApiKey` | yes | Whether the form requires the user to enter a key before saving or testing. |
| `websiteUrl` | yes | Provider website. |
| `apiKeyUrl` | no | Direct link to the provider's key-management page. |
| `authStrategy` | no | How the API key is sent. It is set separately from `apiFormat`; see the values below. |
| `defaultEnv` | no | Non-secret environment defaults passed through the provider configuration. Never put a real API key or other secret here. |
| `modelContextWindows` | no | Known context-window sizes keyed by model ID. Values must be integers from 16,000 through 10,000,000. |

The accepted API formats and authentication strategies are defined in [`src/server/types/provider.ts`](https://github.com/GoDiao/dreamcoder/blob/75d9b3bf7572c5feb7b44e4421a7dcb81bb7a21f/src/server/types/provider.ts). A preset only selects these existing behaviors; adding a format or a new authentication flow is a separate runtime change.

## Add an entry

Before editing, confirm the base URL, API format, authentication requirements, model IDs, and any context-window values from the provider's own documentation. Only include defaults that are stable and supported by those sources. Do not infer a model ID or context size from a marketing name.

Add the entry to `providerPresets.json`. For example, this abbreviated shape shows the required fields; replace every illustrative value with verified provider information:

```json
{
"id": "example-provider",
"name": "Example Provider",
"baseUrl": "https://api.example.invalid/v1",
"apiFormat": "openai_chat",
"defaultModels": [{ "id": "example-model" }],
"needsApiKey": true,
"websiteUrl": "https://example.invalid",
"apiKeyUrl": "https://example.invalid/api-keys",
"authStrategy": "api_key"
}
```

The `.invalid` domain and model ID above are placeholders, not a real provider configuration. Insert the new entry before `lmstudio`. The last three presets must stay `lmstudio`, `ollama` and `custom`, in that order: the preset tests check this, and when you add a provider the form uses the last preset as its fallback.

Use an explicit `authStrategy` when the provider requires behavior other than the form's default. It chooses how the key is sent and is a separate setting from `apiFormat`. For Anthropic-format requests it sets the request headers ([`upstream/client.ts`](https://github.com/GoDiao/dreamcoder/blob/75d9b3bf7572c5feb7b44e4421a7dcb81bb7a21f/src/server/upstream/client.ts)) and the variables passed to the CLI ([`providerRuntimeEnv.ts`](https://github.com/GoDiao/dreamcoder/blob/75d9b3bf7572c5feb7b44e4421a7dcb81bb7a21f/src/server/services/providerRuntimeEnv.ts)):

| Value | Sends the key as |
| --- | --- |
| `api_key` | The `x-api-key` header (`ANTHROPIC_API_KEY`). |
| `auth_token` | A bearer token in `Authorization` (`ANTHROPIC_AUTH_TOKEN`), with `ANTHROPIC_API_KEY` empty. |
| `auth_token_empty_api_key` | The same as `auth_token`. |
| `dual_same_token` | Both of the above, with the same key. |
| `dual_dummy` | The placeholder `dummy` in both, for local servers that do not check a key. |

Requests in the `openai_chat` and `openai_responses` formats always send the key as a bearer token.

`defaultEnv` is appropriate for non-secret compatibility settings, not credentials. Users enter their own key in the form. Never commit a real key in the preset, examples, screenshots, or test fixtures.

## Update preset tests

Extend [`src/server/__tests__/provider-presets.test.ts`](https://github.com/GoDiao/dreamcoder/blob/75d9b3bf7572c5feb7b44e4421a7dcb81bb7a21f/src/server/__tests__/provider-presets.test.ts) to find the new ID and assert its documented URL, API format, initial models, and any optional defaults you added. The test file already checks that `GET /api/providers/presets` returns the configured list and that selected provider defaults match their published details. Keep the ordering assertions for `lmstudio`, `ollama` and `custom` intact.

The form reads this same list from `GET /api/providers/presets`. Selecting a preset copies its URL, API format, authentication strategy, initial models, fast model, and any known context windows into the form. The UI behavior lives in [`ProviderFormModal.tsx`](https://github.com/GoDiao/dreamcoder/blob/75d9b3bf7572c5feb7b44e4421a7dcb81bb7a21f/desktop/src/components/settings/ProviderFormModal.tsx); no separate UI registry is needed for a normal preset.

Run the focused server test from the repository root:

```bash
bun test ./src/server/__tests__/provider-presets.test.ts
```

If the change alters how users select or authenticate a provider, also update the relevant desktop tests in `desktop/src/components/settings/ProviderFormModal.test.tsx` and run them from `desktop`:

```bash
bun run test -- --run src/components/settings/ProviderFormModal.test.tsx
```

## Test a connection in the app

To exercise the manual flow, start DreamCoder, open **Settings**, choose **Providers**, then **Add Provider**. Select the new preset, enter a valid key if it requires one, and make sure the first model in the form is enabled by that account. Choose **Test Connection** before saving. The button stays disabled until the base URL and the first model are filled in, and if the preset needs a key and none is entered, clicking it does nothing and shows no message.

The form sends the current unsaved URL, API format, authentication strategy, key, and first model to `POST /api/providers/test`. The server validates the request and asks `ProviderService` to send a short streaming request to that model and read its response. A successful result confirms that this configuration can reach the selected model; it does not verify every model in the list or a complete coding-agent session. If model discovery is supported for that endpoint, **Fetch models** is a separate operation and can help populate the list.

Do not paste real API keys into issue comments, pull requests, screenshots, or logs. Use a personal key only in the local settings form, and remove or rotate it if it was exposed.

## Checklist

- The preset uses provider-documented endpoint and model values.
- Optional auth, environment, and context-window fields are justified by the existing schema.
- The preset test asserts the new entry and preserves required ordering.
- The focused server test passes; relevant desktop checks pass if form behavior changed.
- The connection test succeeds locally, or the PR explains why it could not be run.
- No credentials or other secrets are included in the change.
Loading
Loading