From a6eb0ef8ead5a8e7aabaf2aca850d51a85e786f4 Mon Sep 17 00:00:00 2001 From: Harshit Nagila Date: Tue, 17 Nov 2026 08:47:14 +0530 Subject: [PATCH 1/2] docs(tutorial): add provider preset guide --- CHANGELOG.md | 1 + docs/tutorial/07-provider-presets.en.md | 87 +++++++++++++++++++++++++ docs/tutorial/07-provider-presets.zh.md | 87 +++++++++++++++++++++++++ docs/tutorial/README.en.md | 1 + docs/tutorial/README.md | 1 + website/src/tutorial.ts | 3 + 6 files changed, 180 insertions(+) create mode 100644 docs/tutorial/07-provider-presets.en.md create mode 100644 docs/tutorial/07-provider-presets.zh.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 0f42154f..9d2cb097 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ All notable changes to DreamCoder will be documented in this file. ### 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. - **Sessions can start other sessions and message each other.** The agent can start a new session with `StartSession`, either fresh with a brief or as a fork of its own conversation, optionally in a new git worktree; you approve every new session, whatever the permission mode. Any session can message any other with `SendMessage`, across projects: a message wakes the receiver, and a progress report from a child to its parent waits for the parent's next turn instead of interrupting it (a parent that is already working sees it right away). Reports waiting for the parent are listed above its message box. The server stamps who sent each message, so a session cannot pass itself off as you or as another session. `ListSessions` lists sessions, and `RenameSession` lets the agent rename its own session (#239). - **Sessions are nested in the sidebar.** Sessions the agent started, and conversations you forked, appear under the session they came from, with an icon for each kind and a count that collapses or expands them. Messages from another session appear in the conversation as a one-line row with the sender, which expands to the full text (#239). - **Project board.** Each project gets a persistent board of tasks and sub-tasks that you and your sessions share; every worktree of the project uses the same board. Open it from the project in the sidebar. A task records its owner, reviewer and creator, acceptance criteria, priority, dependencies, progress, and the owner's and reviewer's reports. Sessions read and update the board with four tools (`KanbanList`, `KanbanGet`, `KanbanCreate`, `KanbanUpdate`): they split work into sub-tasks, record progress, block a task with a question, submit their work and review it. The board notifies the sessions involved when they are assigned, when work is submitted, blocked, sent back, reset or cancelled, and when you comment. `StartSession` can start a session as a task's owner or reviewer. The board page has a board view and a hierarchy view, opens a task in the side panel, and lists what waits on you under "Needs me": blocked tasks, deliveries to accept and tasks whose owner session is gone. You approve every time a session creates the board, starts a session on a task, cancels a task, changes acceptance criteria it did not set, or makes itself a reviewer; only a task's creator or you choose its reviewer (#242). diff --git a/docs/tutorial/07-provider-presets.en.md b/docs/tutorial/07-provider-presets.en.md new file mode 100644 index 00000000..dde278b9 --- /dev/null +++ b/docs/tutorial/07-provider-presets.en.md @@ -0,0 +1,87 @@ +# 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 | Authentication mapping for the selected API format. | +| `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. Keep the built-in `custom` preset last in the array; the current tests also pin the local LM Studio and Ollama entries immediately before it. + +Use an explicit `authStrategy` when the provider requires behavior other than the form's default. `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 `custom` ordering assertions 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 and open **Settings → Providers → 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 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, **Discover 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. diff --git a/docs/tutorial/07-provider-presets.zh.md b/docs/tutorial/07-provider-presets.zh.md new file mode 100644 index 00000000..957b876a --- /dev/null +++ b/docs/tutorial/07-provider-presets.zh.md @@ -0,0 +1,87 @@ +# 添加 Provider 预设 + +本指南介绍如何把一个服务商加入 DreamCoder 的内置 Provider 列表,并说明预设 JSON、设置表单和连接测试之间的关系。本指南不涉及新增 API 协议,也不改变 Provider 运行机制。 + +以下源码链接固定在 commit [`75d9b3b`](https://github.com/GoDiao/dreamcoder/tree/75d9b3bf7572c5feb7b44e4421a7dcb81bb7a21f)。后续修改前请先检查当前源码。 + +## 了解预设的数据结构 + +内置预设保存在 [`src/server/config/providerPresets.json`](https://github.com/GoDiao/dreamcoder/blob/75d9b3bf7572c5feb7b44e4421a7dcb81bb7a21f/src/server/config/providerPresets.json)。服务端通过 [`providerPresets.ts`](https://github.com/GoDiao/dreamcoder/blob/75d9b3bf7572c5feb7b44e4421a7dcb81bb7a21f/src/server/config/providerPresets.ts) 中的 Zod Schema 解析 JSON。模块加载时会校验每个预设;字段无效会导致预设列表无法加载。 + +每个条目描述服务商的端点和模型默认值: + +| 字段 | 必填 | 含义 | +| --- | --- | --- | +| `id` | 是 | 稳定标识符,用于将已保存的 Provider 关联到预设。 | +| `name` | 是 | 设置表单中显示的名称。 | +| `baseUrl` | 是 | Provider API 端点。 | +| `apiFormat` | 是 | `anthropic`、`openai_chat` 或 `openai_responses` 之一。 | +| `defaultModels` | 是 | 初始模型 ID,可附带显示名称。ID 不能为空且必须唯一。 | +| `defaultFastModel` | 否 | 初始快速模型;应使用 `defaultModels` 中已有的 ID。 | +| `needsApiKey` | 是 | 保存或测试前,表单是否要求用户填写密钥。 | +| `websiteUrl` | 是 | 服务商网站。 | +| `apiKeyUrl` | 否 | 服务商管理 API 密钥的页面链接。 | +| `authStrategy` | 否 | 当前 API 格式对应的认证方式。 | +| `defaultEnv` | 否 | Provider 配置使用的非机密环境变量默认值。不要在此填写真实 API 密钥或其他秘密。 | +| `modelContextWindows` | 否 | 按模型 ID 记录的已知上下文窗口大小。值必须是 16,000 至 10,000,000 之间的整数。 | + +[`src/server/types/provider.ts`](https://github.com/GoDiao/dreamcoder/blob/75d9b3bf7572c5feb7b44e4421a7dcb81bb7a21f/src/server/types/provider.ts) 定义了可用的 API 格式和认证方式。普通预设只能选择已有行为;新增格式或认证流程属于独立的运行时改动。 + +## 添加预设 + +编辑前,请从服务商官方文档确认基础 URL、API 格式、认证要求、模型 ID 和上下文窗口。只添加有可靠来源且稳定的默认值,不要根据产品宣传名称猜测模型 ID 或上下文大小。 + +将条目加入 `providerPresets.json`。以下缩略结构只展示必填字段;请用经过核实的服务商信息替换示例值: + +```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" +} +``` + +上面的 `.invalid` 域名和模型 ID 都是占位符,不代表真实服务商配置。数组中的内置 `custom` 预设必须保留在最后;现有测试还要求 LM Studio 和 Ollama 这两个本地预设紧邻它之前。 + +如果服务商需要表单默认认证方式以外的行为,请明确设置 `authStrategy`。`defaultEnv` 只适用于非机密兼容性设置,不用于存放凭证。用户应在表单中输入自己的密钥。不要把真实密钥放入预设、示例、截图或测试夹具。 + +## 更新预设测试 + +在 [`src/server/__tests__/provider-presets.test.ts`](https://github.com/GoDiao/dreamcoder/blob/75d9b3bf7572c5feb7b44e4421a7dcb81bb7a21f/src/server/__tests__/provider-presets.test.ts) 中增加断言,按新增 ID 查找预设,并验证官方文档支持的 URL、API 格式、初始模型及新增的可选默认值。该测试文件已经覆盖 `GET /api/providers/presets` 返回配置列表,也会校验部分预设与服务商发布的信息一致。保留关于 `custom` 顺序的断言。 + +设置表单从同一个 `GET /api/providers/presets` 接口读取列表。选择预设时,表单会填入 URL、API 格式、认证方式、初始模型、快速模型和已知上下文窗口。相关界面逻辑位于 [`ProviderFormModal.tsx`](https://github.com/GoDiao/dreamcoder/blob/75d9b3bf7572c5feb7b44e4421a7dcb81bb7a21f/desktop/src/components/settings/ProviderFormModal.tsx)。普通预设不需要再添加一份独立 UI 注册表。 + +在仓库根目录运行服务端定向测试: + +```bash +bun test ./src/server/__tests__/provider-presets.test.ts +``` + +如果改动影响服务商选择或认证方式,也应更新 `desktop/src/components/settings/ProviderFormModal.test.tsx` 中相关桌面测试,并在 `desktop` 目录运行: + +```bash +bun run test -- --run src/components/settings/ProviderFormModal.test.tsx +``` + +## 在应用中测试连接 + +启动 DreamCoder,打开 **Settings → Providers → Add provider**。选择新增预设;若需要密钥,请输入有效密钥,并确认表单中的第一个模型已在该账户中启用。保存之前选择 **Test Connection**。 + +表单会把当前尚未保存的 URL、API 格式、认证方式、密钥和第一个模型发送到 `POST /api/providers/test`。服务端校验请求后调用 `ProviderService`,向该模型发送简短的流式请求并读取响应。成功表示当前配置可以访问所选模型;它不代表列表中所有模型都可用,也不代表完整的编程智能体会话已经验证。如果该端点支持模型发现,**Discover models** 是独立操作,可用于填充模型列表。 + +不要把真实 API 密钥粘贴到 issue 评论、拉取请求、截图或日志中。只在本机设置表单中使用个人密钥;如果密钥已泄露,请删除或轮换。 + +## 提交前检查 + +- 端点和模型默认值有服务商文档作为依据。 +- 可选认证、环境变量和上下文窗口字段符合现有 Schema,并有依据。 +- 预设测试覆盖新条目,同时保留必要的顺序断言。 +- 服务端定向测试通过;若修改表单行为,相关桌面检查也通过。 +- 本机连接测试成功;如果无法运行,应在 PR 中说明原因。 +- 改动中没有凭证或其他秘密信息。 diff --git a/docs/tutorial/README.en.md b/docs/tutorial/README.en.md index 165bf7da..55f9b3d9 100644 --- a/docs/tutorial/README.en.md +++ b/docs/tutorial/README.en.md @@ -38,6 +38,7 @@ You need basic TypeScript and `async/await`, and you should know what HTTP and W | [Part 4: Session persistence and context engineering](./04-session-context.en.md) | How the same set of messages differs on disk, after resume and in a model request, and how auto-compaction works | | [Part 5: Streaming responses and failure recovery](./05-streaming-recovery.en.md) | Running tools while the model is still producing output, and what has already run and what will repeat on cancellation and fallback | | [Part 6: Model access and desktop integration](./06-desktop-integration.en.md) | How provider configuration reaches the CLI, session processes and message channels, protocol conversion for the OpenAI format, and continuing on a phone | +| [Part 7: Adding a provider preset](./07-provider-presets.en.md) | How to add a built-in provider preset, validate its metadata, and test a connection from the settings form | ## Reading conventions diff --git a/docs/tutorial/README.md b/docs/tutorial/README.md index 11d16d6e..ae2288a4 100644 --- a/docs/tutorial/README.md +++ b/docs/tutorial/README.md @@ -36,6 +36,7 @@ | [第四篇:会话持久化与上下文工程](./04-session-context.zh.md) | 同一组消息在磁盘、恢复后和模型请求中的差别,自动压缩怎样工作 | | [第五篇:流式响应与故障恢复](./05-streaming-recovery.zh.md) | 模型输出期间就执行工具,取消和回退时哪些已经执行、哪些会重复 | | [第六篇:模型接入与桌面端集成](./06-desktop-integration.zh.md) | Provider 配置怎样进入 CLI,会话进程与消息通道,OpenAI 格式的协议转换和手机接续 | +| [第七篇:添加 Provider 预设](./07-provider-presets.zh.md) | 如何添加内置 Provider 预设、校验配置,并在设置表单中测试连接 | ## 阅读约定 diff --git a/website/src/tutorial.ts b/website/src/tutorial.ts index a1d45a6b..528effdc 100644 --- a/website/src/tutorial.ts +++ b/website/src/tutorial.ts @@ -9,6 +9,7 @@ export const docIds = [ '04-session-context', '05-streaming-recovery', '06-desktop-integration', + '07-provider-presets', ] as const; export type DocId = (typeof docIds)[number]; @@ -23,6 +24,7 @@ export const docTitles: Record> = { '04-session-context': '会话持久化与上下文工程', '05-streaming-recovery': '流式响应与故障恢复', '06-desktop-integration': '模型接入与桌面端集成', + '07-provider-presets': '添加 Provider 预设', }, en: { README: 'Contents and conventions', @@ -33,6 +35,7 @@ export const docTitles: Record> = { '04-session-context': 'Session persistence and context engineering', '05-streaming-recovery': 'Streaming responses and failure recovery', '06-desktop-integration': 'Model access and desktop integration', + '07-provider-presets': 'Adding a provider preset', }, }; From 4cfeb3f2e3697ed209345b88e542d67dd0a829cb Mon Sep 17 00:00:00 2001 From: Harshit Nagila Date: Tue, 17 Nov 2026 20:50:33 +0530 Subject: [PATCH 2/2] docs(tutorial): address review of the provider preset guide - Use the app's own labels: the English UI strings in the English chapter and the Chinese UI strings in the Chinese chapter. - Say when Test Connection is disabled or does nothing. - Tell readers to insert a new preset before lmstudio, and why. - Describe authStrategy as how the key is sent, separate from the API format, and list its values. - Add the language switch line to both chapters. - Count eight parts in the READMEs and on the website. - Link CONTRIBUTING to the chapter under its real title. - Move the changelog entry under Unreleased and add (#260). --- CHANGELOG.md | 5 ++++- README.md | 4 ++-- README_zh.md | 4 ++-- docs/general/CONTRIBUTING_en.md | 2 +- docs/general/CONTRIBUTING_zh.md | 2 +- docs/tutorial/07-provider-presets.en.md | 26 +++++++++++++++++++------ docs/tutorial/07-provider-presets.zh.md | 26 +++++++++++++++++++------ website/src/App.tsx | 4 ++-- 8 files changed, 52 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3ed75e6b..e89a3f8f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. @@ -12,7 +16,6 @@ Thanks to everyone who contributed to this release: @AIR-Xie, @Oscar-Williams, @ ### 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. - **Sessions can start other sessions and message each other.** The agent can start a new session with `StartSession`, either fresh with a brief or as a fork of its own conversation, optionally in a new git worktree; you approve every new session, whatever the permission mode. Any session can message any other with `SendMessage`, across projects: a message wakes the receiver, and a progress report from a child to its parent waits for the parent's next turn instead of interrupting it (a parent that is already working sees it right away). Reports waiting for the parent are listed above its message box. The server stamps who sent each message, so a session cannot pass itself off as you or as another session. `ListSessions` lists sessions, and `RenameSession` lets the agent rename its own session (#239). - **Sessions are nested in the sidebar.** Sessions the agent started, and conversations you forked, appear under the session they came from, with an icon for each kind and a count that collapses or expands them. Messages from another session appear in the conversation as a one-line row with the sender, which expands to the full text (#239). - **Project board.** Each project gets a persistent board of tasks and sub-tasks that you and your sessions share; every worktree of the project uses the same board. Open it from the project in the sidebar. A task records its owner, reviewer and creator, acceptance criteria, priority, dependencies, progress, and the owner's and reviewer's reports. Sessions read and update the board with four tools (`KanbanList`, `KanbanGet`, `KanbanCreate`, `KanbanUpdate`): they split work into sub-tasks, record progress, block a task with a question, submit their work and review it. The board notifies the sessions involved when they are assigned, when work is submitted, blocked, sent back, reset or cancelled, and when you comment. `StartSession` can start a session as a task's owner or reviewer. The board page has a board view and a hierarchy view, opens a task in the side panel, and lists what waits on you under "Needs me": blocked tasks, deliveries to accept and tasks whose owner session is gone. You approve every time a session creates the board, starts a session on a task, cancels a task, changes acceptance criteria it did not set, or makes itself a reviewer; only a task's creator or you choose its reviewer (#242). diff --git a/README.md b/README.md index 761b32e9..97e57e00 100644 --- a/README.md +++ b/README.md @@ -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). @@ -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. --- diff --git a/README_zh.md b/README_zh.md index 119fcf1c..04217cf5 100644 --- a/README_zh.md +++ b/README_zh.md @@ -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)。 @@ -183,7 +183,7 @@ Provider 配置和 API Key 保存在本机文件中。使用云端模型时, ## 📖 源码导读 -想了解编程智能体内部怎样工作,可以读[《编程智能体实现指南》](docs/tutorial/README.md)。系列共七篇,沿一次小的代码修改,依次讲解执行循环、代码工具、权限控制、会话与上下文、流式响应与故障恢复,以及桌面端集成,文中结论都附有源码链接。 +想了解编程智能体内部怎样工作,可以读[《编程智能体实现指南》](docs/tutorial/README.md)。系列共八篇,沿一次小的代码修改,依次讲解执行循环、代码工具、权限控制、会话与上下文、流式响应与故障恢复,以及桌面端集成,最后介绍如何添加 Provider 预设,文中结论都附有源码链接。 --- diff --git a/docs/general/CONTRIBUTING_en.md b/docs/general/CONTRIBUTING_en.md index b7fe52dd..934407d0 100644 --- a/docs/general/CONTRIBUTING_en.md +++ b/docs/general/CONTRIBUTING_en.md @@ -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 diff --git a/docs/general/CONTRIBUTING_zh.md b/docs/general/CONTRIBUTING_zh.md index db0e767b..143e8bea 100644 --- a/docs/general/CONTRIBUTING_zh.md +++ b/docs/general/CONTRIBUTING_zh.md @@ -118,7 +118,7 @@ dreamcoder/ └── docs/ # 文档 ``` -如果你要新增 Provider 预设,请先阅读网站技术手册中的“新增 Provider 预设”。 +如果你要新增 Provider 预设,请先阅读[《添加 Provider 预设》](../tutorial/07-provider-presets.zh.md)(《编程智能体实现指南》第七篇)。 ## 开发环境 diff --git a/docs/tutorial/07-provider-presets.en.md b/docs/tutorial/07-provider-presets.en.md index dde278b9..284b3c72 100644 --- a/docs/tutorial/07-provider-presets.en.md +++ b/docs/tutorial/07-provider-presets.en.md @@ -1,3 +1,5 @@ +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. @@ -21,7 +23,7 @@ Each entry describes a provider endpoint and model defaults: | `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 | Authentication mapping for the selected API format. | +| `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. | @@ -47,13 +49,25 @@ Add the entry to `providerPresets.json`. For example, this abbreviated shape sho } ``` -The `.invalid` domain and model ID above are placeholders, not a real provider configuration. Keep the built-in `custom` preset last in the array; the current tests also pin the local LM Studio and Ollama entries immediately before it. +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. -Use an explicit `authStrategy` when the provider requires behavior other than the form's default. `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. +`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 `custom` ordering assertions intact. +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. @@ -71,9 +85,9 @@ bun run test -- --run src/components/settings/ProviderFormModal.test.tsx ## Test a connection in the app -To exercise the manual flow, start DreamCoder and open **Settings → Providers → 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. +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, **Discover models** is a separate operation and can help populate the list. +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. diff --git a/docs/tutorial/07-provider-presets.zh.md b/docs/tutorial/07-provider-presets.zh.md index 957b876a..02582f25 100644 --- a/docs/tutorial/07-provider-presets.zh.md +++ b/docs/tutorial/07-provider-presets.zh.md @@ -1,3 +1,5 @@ +[English](./07-provider-presets.en.md) | 简体中文 + # 添加 Provider 预设 本指南介绍如何把一个服务商加入 DreamCoder 的内置 Provider 列表,并说明预设 JSON、设置表单和连接测试之间的关系。本指南不涉及新增 API 协议,也不改变 Provider 运行机制。 @@ -21,7 +23,7 @@ | `needsApiKey` | 是 | 保存或测试前,表单是否要求用户填写密钥。 | | `websiteUrl` | 是 | 服务商网站。 | | `apiKeyUrl` | 否 | 服务商管理 API 密钥的页面链接。 | -| `authStrategy` | 否 | 当前 API 格式对应的认证方式。 | +| `authStrategy` | 否 | API 密钥的发送方式。它与 `apiFormat` 分开设置,可选值见下文。 | | `defaultEnv` | 否 | Provider 配置使用的非机密环境变量默认值。不要在此填写真实 API 密钥或其他秘密。 | | `modelContextWindows` | 否 | 按模型 ID 记录的已知上下文窗口大小。值必须是 16,000 至 10,000,000 之间的整数。 | @@ -47,13 +49,25 @@ } ``` -上面的 `.invalid` 域名和模型 ID 都是占位符,不代表真实服务商配置。数组中的内置 `custom` 预设必须保留在最后;现有测试还要求 LM Studio 和 Ollama 这两个本地预设紧邻它之前。 +上面的 `.invalid` 域名和模型 ID 都是占位符,不代表真实服务商配置。请把新条目插入到 `lmstudio` 之前。最后三个预设必须依次保持为 `lmstudio`、`ollama` 和 `custom`:预设测试会检查这一顺序,而且添加服务商时,表单会把最后一个预设作为后备预设。 + +如果服务商需要表单默认认证方式以外的行为,请明确设置 `authStrategy`。它决定密钥怎样发送,与 `apiFormat` 是两个独立的设置。对于 Anthropic 格式的请求,它决定请求头([`upstream/client.ts`](https://github.com/GoDiao/dreamcoder/blob/75d9b3bf7572c5feb7b44e4421a7dcb81bb7a21f/src/server/upstream/client.ts))以及传给 CLI 的环境变量([`providerRuntimeEnv.ts`](https://github.com/GoDiao/dreamcoder/blob/75d9b3bf7572c5feb7b44e4421a7dcb81bb7a21f/src/server/services/providerRuntimeEnv.ts)): + +| 取值 | 密钥的发送方式 | +| --- | --- | +| `api_key` | 放在 `x-api-key` 请求头中(`ANTHROPIC_API_KEY`)。 | +| `auth_token` | 作为 `Authorization` 中的 Bearer 令牌(`ANTHROPIC_AUTH_TOKEN`),同时 `ANTHROPIC_API_KEY` 为空。 | +| `auth_token_empty_api_key` | 与 `auth_token` 相同。 | +| `dual_same_token` | 以上两处同时发送同一个密钥。 | +| `dual_dummy` | 两处都发送占位值 `dummy`,适用于不校验密钥的本地服务。 | + +`openai_chat` 和 `openai_responses` 格式的请求始终以 Bearer 令牌发送密钥。 -如果服务商需要表单默认认证方式以外的行为,请明确设置 `authStrategy`。`defaultEnv` 只适用于非机密兼容性设置,不用于存放凭证。用户应在表单中输入自己的密钥。不要把真实密钥放入预设、示例、截图或测试夹具。 +`defaultEnv` 只适用于非机密兼容性设置,不用于存放凭证。用户应在表单中输入自己的密钥。不要把真实密钥放入预设、示例、截图或测试夹具。 ## 更新预设测试 -在 [`src/server/__tests__/provider-presets.test.ts`](https://github.com/GoDiao/dreamcoder/blob/75d9b3bf7572c5feb7b44e4421a7dcb81bb7a21f/src/server/__tests__/provider-presets.test.ts) 中增加断言,按新增 ID 查找预设,并验证官方文档支持的 URL、API 格式、初始模型及新增的可选默认值。该测试文件已经覆盖 `GET /api/providers/presets` 返回配置列表,也会校验部分预设与服务商发布的信息一致。保留关于 `custom` 顺序的断言。 +在 [`src/server/__tests__/provider-presets.test.ts`](https://github.com/GoDiao/dreamcoder/blob/75d9b3bf7572c5feb7b44e4421a7dcb81bb7a21f/src/server/__tests__/provider-presets.test.ts) 中增加断言,按新增 ID 查找预设,并验证官方文档支持的 URL、API 格式、初始模型及新增的可选默认值。该测试文件已经覆盖 `GET /api/providers/presets` 返回配置列表,也会校验部分预设与服务商发布的信息一致。保留关于 `lmstudio`、`ollama` 和 `custom` 顺序的断言。 设置表单从同一个 `GET /api/providers/presets` 接口读取列表。选择预设时,表单会填入 URL、API 格式、认证方式、初始模型、快速模型和已知上下文窗口。相关界面逻辑位于 [`ProviderFormModal.tsx`](https://github.com/GoDiao/dreamcoder/blob/75d9b3bf7572c5feb7b44e4421a7dcb81bb7a21f/desktop/src/components/settings/ProviderFormModal.tsx)。普通预设不需要再添加一份独立 UI 注册表。 @@ -71,9 +85,9 @@ bun run test -- --run src/components/settings/ProviderFormModal.test.tsx ## 在应用中测试连接 -启动 DreamCoder,打开 **Settings → Providers → Add provider**。选择新增预设;若需要密钥,请输入有效密钥,并确认表单中的第一个模型已在该账户中启用。保存之前选择 **Test Connection**。 +启动 DreamCoder,打开**设置**,选择**服务商**,然后点击**添加服务商**。选择新增预设;若需要密钥,请输入有效密钥,并确认表单中的第一个模型已在该账户中启用。保存之前点击**测试连接**。基础 URL 或第一个模型为空时,该按钮不可用;如果预设需要密钥而没有填写,点击后不会有任何反应,也不会显示提示。 -表单会把当前尚未保存的 URL、API 格式、认证方式、密钥和第一个模型发送到 `POST /api/providers/test`。服务端校验请求后调用 `ProviderService`,向该模型发送简短的流式请求并读取响应。成功表示当前配置可以访问所选模型;它不代表列表中所有模型都可用,也不代表完整的编程智能体会话已经验证。如果该端点支持模型发现,**Discover models** 是独立操作,可用于填充模型列表。 +表单会把当前尚未保存的 URL、API 格式、认证方式、密钥和第一个模型发送到 `POST /api/providers/test`。服务端校验请求后调用 `ProviderService`,向该模型发送简短的流式请求并读取响应。成功表示当前配置可以访问所选模型;它不代表列表中所有模型都可用,也不代表完整的编程智能体会话已经验证。如果该端点支持模型发现,**获取模型**是独立操作,可用于填充模型列表。 不要把真实 API 密钥粘贴到 issue 评论、拉取请求、截图或日志中。只在本机设置表单中使用个人密钥;如果密钥已泄露,请删除或轮换。 diff --git a/website/src/App.tsx b/website/src/App.tsx index e13768f8..e3c77ba3 100644 --- a/website/src/App.tsx +++ b/website/src/App.tsx @@ -41,7 +41,7 @@ const copy = { ], tutorialEyebrow: '源码导读', tutorialTitle: '沿一次代码修改,读懂编程智能体。', - tutorialBody: '七篇源码导读从一条“把 value 改成 2”的消息讲起:它怎样变成多次模型请求和工具执行,程序怎样校验参数、请求确认、保存会话,又怎样处理取消和失败。文中结论都附有指向固定版本源码的链接。', + tutorialBody: '八篇源码导读从一条“把 value 改成 2”的消息讲起:它怎样变成多次模型请求和工具执行,程序怎样校验参数、请求确认、保存会话,又怎样处理取消和失败。文中结论都附有指向固定版本源码的链接。', tutorialNote: '需要 TypeScript 基础和 async/await。', tutorialLink: '开始阅读', accessEyebrow: '离开桌面时', @@ -97,7 +97,7 @@ const copy = { ], tutorialEyebrow: 'Source code walkthrough', tutorialTitle: 'Learn how a coding agent works, one code change at a time.', - tutorialBody: 'A seven-part walkthrough starts from a single "change value to 2" message: how it turns into several model requests and tool runs, how the program validates arguments, asks for confirmation, and saves the session, and how it handles cancellation and failure. Each point links to a pinned version of the source.', + tutorialBody: 'An eight-part walkthrough starts from a single "change value to 2" message: how it turns into several model requests and tool runs, how the program validates arguments, asks for confirmation, and saves the session, and how it handles cancellation and failure. Each point links to a pinned version of the source.', tutorialNote: 'Assumes basic TypeScript and async/await.', tutorialLink: 'Start reading', accessEyebrow: 'Away from your desk',