Skip to content

Commit ca02046

Browse files
author
王璨
committed
docs: add settings.json configuration section to READMEs
 - Add dedicated "Configuration" section in both EN/ZH READMEs - Document two-level settings (user ~/.dscode/settings.json + project .dscode/settings.json) - Include full JSON reference covering mcpServers, permissions, skills, retry, @-file limits - Add Retry fields explanation (exponential backoff, retry conditions) - Add MCP server config field reference table - Add environment variables table for CI/container use - Clarify that model config lives in config.json, not settings.json
1 parent a402ff0 commit ca02046

2 files changed

Lines changed: 218 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -182,6 +182,115 @@ node dist/dscode.mjs
182182

183183
---
184184

185+
## Configuration
186+
187+
dscode uses two levels of `settings.json`, merged with project settings overriding user settings:
188+
189+
| Scope | Path | Purpose |
190+
|-------|------|---------|
191+
| User | `~/.dscode/settings.json` | Defaults across all projects |
192+
| Project | `.dscode/settings.json` | Per-project overrides |
193+
194+
> **Note:** Model configuration (`provider`, `modelId`, `apiKey`, `thinkingLevel`) lives in `~/.dscode/config.json`, managed via `/config` commands. Type `/help` in-session for the full command list.
195+
196+
### Quick reference
197+
198+
```jsonc
199+
// ~/.dscode/settings.json
200+
{
201+
// --- MCP Servers ---
202+
"mcpServers": {
203+
"blender": {
204+
"command": "uvx",
205+
"args": ["blender-mcp"]
206+
},
207+
"playwright": {
208+
"command": "npx",
209+
"args": ["@anthropic/mcp-playwright"]
210+
},
211+
"my-api": {
212+
"url": "https://my-mcp.example.com/mcp",
213+
"headers": { "Authorization": "Bearer <token>" }
214+
}
215+
},
216+
217+
// --- Permissions ---
218+
"permissions": {
219+
"allow": [
220+
"Bash(git add *)",
221+
"Bash(npm *)"
222+
],
223+
"deny": [
224+
"Bash(rm -rf *)"
225+
],
226+
"rules": [
227+
{ "tool": "Bash(curl *)", "decision": "allow", "priority": 5 }
228+
]
229+
},
230+
231+
// --- Skills ---
232+
"skills": ["brandkit", "minimalist-ui"],
233+
234+
// --- Retry ---
235+
// Controls how dscode retries failed API calls (rate limits, timeouts, server errors).
236+
// Uses exponential backoff: starts at baseDelayMs, doubles each retry, capped at maxDelayMs.
237+
"retry": {
238+
"maxRetries": 3, // Max retry attempts before giving up
239+
"baseDelayMs": 1000, // Initial delay before first retry (ms)
240+
"maxDelayMs": 30000, // Upper bound on backoff delay (ms)
241+
"retryOnTimeout": true, // Retry when the provider times out
242+
"retryOnRateLimit": true, // Retry when hitting rate limits (respects Retry-After header)
243+
"retryOnServerError": true // Retry on 5xx server errors
244+
},
245+
246+
// --- @-file limits ---
247+
"atFileMaxFiles": 5,
248+
"atFileMaxFileSize": 51200,
249+
"atFileMaxTotalSize": 204800
250+
}
251+
```
252+
253+
### MCP server config
254+
255+
Each server under `mcpServers` supports:
256+
257+
| Field | Type | Description |
258+
|-------|------|-------------|
259+
| `command` | string | Executable (for stdio transport) |
260+
| `args` | string[] | Arguments passed to the command |
261+
| `url` | string | HTTP endpoint (for streamable-http transport) |
262+
| `env` | object | Extra environment variables for the server process |
263+
| `headers` | object | Custom HTTP headers |
264+
| `transport` | string | `"stdio"` \| `"streamable-http"` \| `"sse"` (auto-detected if omitted) |
265+
| `preferredProtocolVersion` | string | `"2025-11-25"` \| `"2025-03-26"` \| `"2024-11-05"` |
266+
| `requestTimeoutMs` | number | Per-request timeout |
267+
| `connectTimeoutMs` | number | Connection timeout |
268+
269+
> **Tip:** Transport is auto-detected — if `url` is set without `command`, streamable-http is used. Otherwise stdio.
270+
271+
### Environment variables
272+
273+
All settings can also be set via environment variables for CI / containers:
274+
275+
| Variable | Setting |
276+
|----------|---------|
277+
| `DEEPSEEK_API_KEY` | API key (provider-specific vars also supported: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.) |
278+
| `AGENT_PROVIDER` | Provider override |
279+
| `AGENT_MODEL` | Model override |
280+
| `AGENT_THINKING_LEVEL` | Thinking level override |
281+
| `AGENT_VISION_PROVIDER` | Vision model provider |
282+
| `AGENT_VISION_MODEL` | Vision model ID |
283+
| `DSCODE_MAX_TOKENS` | Max tokens |
284+
| `DSCODE_CONFIG_HOME` | Custom config directory (default: `~/.dscode`) |
285+
| `DSCODE_DATA_HOME` | Custom data directory |
286+
| `DSCODE_PROJECT_PATH` | Project directory |
287+
| `DSCODE_RETRY_MAX_RETRIES` | Retry max retries |
288+
| `DSCODE_RETRY_BASE_DELAY_MS` | Retry base delay |
289+
| `DSCODE_RETRY_MAX_DELAY_MS` | Retry max delay |
290+
291+
---
292+
293+
185294
## Harness Philosophy
186295

187296
We follow **Occam's razor** in harness design. dscode does not pre-build intent understanding modules, plan modes, or elaborate agentic scaffolding until the system prompt proves insufficient. Most coding agents pile on pre-turn planning, reflection loops, and multi-agent orchestration upfront — we wait until the model demands it.

‎README.zh-CN.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -182,6 +182,115 @@ node dist/dscode.mjs
182182

183183
---
184184

185+
## 配置
186+
187+
dscode 使用两层 `settings.json`，项目级配置覆盖用户级配置：
188+
189+
| 作用域 | 路径 | 用途 |
190+
|-------|------|---------|
191+
| 用户级 | `~/.dscode/settings.json` | 所有项目的默认配置 |
192+
| 项目级 | `.dscode/settings.json` | 单个项目的覆盖配置 |
193+
194+
> **注意：** 模型配置（`provider`、`modelId`、`apiKey`、`thinkingLevel`）存放在 `~/.dscode/config.json`，通过 `/config` 命令管理。在会话中输入 `/help` 查看完整命令列表。
195+
196+
### 配置速览
197+
198+
```jsonc
199+
// ~/.dscode/settings.json
200+
{
201+
// --- MCP 服务器 ---
202+
"mcpServers": {
203+
"blender": {
204+
"command": "uvx",
205+
"args": ["blender-mcp"]
206+
},
207+
"playwright": {
208+
"command": "npx",
209+
"args": ["@anthropic/mcp-playwright"]
210+
},
211+
"my-api": {
212+
"url": "https://my-mcp.example.com/mcp",
213+
"headers": { "Authorization": "Bearer <token>" }
214+
}
215+
},
216+
217+
// --- 权限 ---
218+
"permissions": {
219+
"allow": [
220+
"Bash(git add *)",
221+
"Bash(npm *)"
222+
],
223+
"deny": [
224+
"Bash(rm -rf *)"
225+
],
226+
"rules": [
227+
{ "tool": "Bash(curl *)", "decision": "allow", "priority": 5 }
228+
]
229+
},
230+
231+
// --- Skills ---
232+
"skills": ["brandkit", "minimalist-ui"],
233+
234+
// --- 重试 ---
235+
// 控制 dscode 如何在 API 调用失败时重试（限流、超时、服务器错误）。
236+
// 使用指数退避策略：从 baseDelayMs 开始，每次重试翻倍，上限为 maxDelayMs。
237+
"retry": {
238+
"maxRetries": 3, // 最大重试次数
239+
"baseDelayMs": 1000, // 首次重试前的初始延迟（毫秒）
240+
"maxDelayMs": 30000, // 退避延迟的上限（毫秒）
241+
"retryOnTimeout": true, // 提供商超时时重试
242+
"retryOnRateLimit": true, // 触发限流时重试（遵循 Retry-After 头）
243+
"retryOnServerError": true // 5xx 服务器错误时重试
244+
},
245+
246+
// --- @-文件 限制 ---
247+
"atFileMaxFiles": 5,
248+
"atFileMaxFileSize": 51200,
249+
"atFileMaxTotalSize": 204800
250+
}
251+
```
252+
253+
### MCP 服务器配置
254+
255+
`mcpServers` 下每个服务器支持以下字段：
256+
257+
| 字段 | 类型 | 说明 |
258+
|-------|------|-------------|
259+
| `command` | string | 可执行文件（用于 stdio 传输） |
260+
| `args` | string[] | 传递给命令的参数 |
261+
| `url` | string | HTTP 端点（用于 streamable-http 传输） |
262+
| `env` | object | 服务器进程的额外环境变量 |
263+
| `headers` | object | 自定义 HTTP 头 |
264+
| `transport` | string | `"stdio"` \| `"streamable-http"` \| `"sse"`（省略时自动检测） |
265+
| `preferredProtocolVersion` | string | `"2025-11-25"` \| `"2025-03-26"` \| `"2024-11-05"` |
266+
| `requestTimeoutMs` | number | 单次请求超时时间 |
267+
| `connectTimeoutMs` | number | 连接超时时间 |
268+
269+
> **提示：** 传输方式自动检测 —— 如果设置了 `url` 而没有 `command`，则使用 streamable-http，否则使用 stdio。
270+
271+
### 环境变量
272+
273+
所有配置均可通过环境变量设置，适用于 CI / 容器场景：
274+
275+
| 变量 | 对应配置 |
276+
|----------|---------|
277+
| `DEEPSEEK_API_KEY` | API Key（也支持 provider 专用变量：`OPENAI_API_KEY`、`ANTHROPIC_API_KEY` 等） |
278+
| `AGENT_PROVIDER` | Provider 覆盖 |
279+
| `AGENT_MODEL` | Model 覆盖 |
280+
| `AGENT_THINKING_LEVEL` | Thinking Level 覆盖 |
281+
| `AGENT_VISION_PROVIDER` | Vision 模型 provider |
282+
| `AGENT_VISION_MODEL` | Vision 模型 ID |
283+
| `DSCODE_MAX_TOKENS` | 最大 token 数 |
284+
| `DSCODE_CONFIG_HOME` | 自定义配置目录（默认：`~/.dscode`） |
285+
| `DSCODE_DATA_HOME` | 自定义数据目录 |
286+
| `DSCODE_PROJECT_PATH` | 项目目录 |
287+
| `DSCODE_RETRY_MAX_RETRIES` | 重试最大次数 |
288+
| `DSCODE_RETRY_BASE_DELAY_MS` | 重试基础延迟 |
289+
| `DSCODE_RETRY_MAX_DELAY_MS` | 重试最大延迟 |
290+
291+
---
292+
293+
185294
## Harness 设计哲学
186295

187296
我们在 Harness 设计上遵循**奥卡姆剃刀原则**。dscode 不会预设意图理解模块、Plan 模式或复杂的 agent 编排层——直到系统提示词确实不够用。大多数 coding agent 在一开始就堆叠了推理规划、反思循环和多 agent 协调，而我们选择等模型真正需要时再添加。

0 commit comments

Comments
 (0)