DotCraft

简体中文

English

简体中文

English

外观

DotCraft 完整配置参考 ​

本页集中列出配置字段、默认值、JSON 示例和高级参考。第一次配置请先读 项目级工作区。想理解功能本身时先读对应 Feature 页面，需要准确字段时再回到这里。

DotCraft 先读取全局 ~/.craft/config.json，再叠加工作区 .craft/config.json，工作区字段优先生效。配置字符串支持 $VAR 和 ${VAR} 环境变量占位；变量不存在时保留原始占位符。

基础模型与 Provider ​

配置项说明默认值
ProviderId当前选择的个人 Provider id；为空表示未选择 Provider空
Model默认模型名称gpt-4o-mini
NetworkTimeoutSeconds全局模型请求超时时间，单位秒；Provider 可单独覆盖600
Providers个人模型 Provider 字典，通常写在 ~/.craft/config.json空
Language界面语言：Chinese / EnglishChinese
SubagentMaxConcurrency最大并发子 Agent 数量3
MaxSessionQueueSize每个 Session 最大排队请求数；0 表示无限制3
ConsolidationModel记忆整合专用模型，空值使用主模型空
DebugMode控制台不截断工具调用参数输出false
EnabledTools全局启用的工具名称列表，为空时启用所有工具[]

个人 Provider 示例：

json
{
  "Providers": {
    "anthropic": {
      "DisplayName": "Anthropic",
      "Protocol": "anthropic",
      "ApiKey": "${ANTHROPIC_API_KEY}"
    },
    "openrouter": {
      "DisplayName": "OpenRouter",
      "Protocol": "openai-chat-completions",
      "ApiKey": "${OPENROUTER_API_KEY}",
      "EndPoint": "https://openrouter.ai/api/v1"
    }
  }
}

工作区模型选择示例：

json
{
  "ProviderId": "anthropic",
  "Model": "claude-sonnet-4-5"
}

Provider 对象字段：

字段说明默认值
DisplayName面向用户显示的 Provider 名称；为空时使用 provider id空
ProtocolProvider 协议：anthropic、openai-chat-completions 或 openai-responses；空值和旧值 openai 按 openai-chat-completions 处理openai-chat-completions
ApiKeyProvider API Key；建议使用 ${ENV_NAME} 引用环境变量空
EndPointProvider base URL；为空时使用协议默认地址OpenAI 协议：https://api.openai.com/v1；anthropic: https://api.anthropic.com
NetworkTimeoutSeconds单个 Provider 请求超时时间，覆盖全局 NetworkTimeoutSeconds空
StreamMaxRetries单个 Provider 的流式响应断线重连次数；设为 0 可关闭 stream retry5
StreamIdleTimeoutMs单个 Provider 的流式响应空闲超时时间，单位毫秒300000

Workspace Memory 与 Skills ​

配置项说明默认值
Memory.AutoConsolidateEnabled启用长期记忆自动沉淀true
Memory.ConsolidateEveryNTurns每个线程成功完成多少轮后触发一次长期记忆沉淀5
Skills.SelfLearning.EnabledSkill 自学习主开关；关闭后模型看不到 skill 编辑能力true
Skills.SelfLearning.MaxSkillContentChars通过自学习写入单个 SKILL.md 的最大字符数100000
Skills.SelfLearning.MaxSupportingFileBytes通过自学习写入单个 supporting file 的最大字节数1048576

Skill 自学习示例：

json
{
  "Skills": {
    "SelfLearning": {
      "Enabled": true,
      "MaxSkillContentChars": 100000,
      "MaxSupportingFileBytes": 1048576
    }
  }
}

SkillManage(action, ...) 参考：

Action必填参数用途
createname, content创建新的工作区 skill
patchname, oldString, newString局部修补 SKILL.md 或 supporting file
editname, content完整替换已有工作区 skill 的 SKILL.md
write_filename, filePath, fileContent写入 supporting file
remove_filename, filePath删除 supporting file

create 会触发 kind: skill 审批；破坏性删除也需要审批。自学习只写当前工作区 skill 目录。系统和个人 skills 视为只读，supporting files 只能写在 scripts/ 或 assets/ 下，绝对路径和 .. 路径穿越会被拒绝。

Compaction ​

配置项说明默认值
Compaction.AutoCompactEnabled启用基于阈值的自动压缩true
Compaction.ReactiveCompactEnabled启用对 prompt_too_long 错误的反应式压缩true
Compaction.ContextWindow模型上下文窗口（Token）；未配置时按当前有效模型推导模型映射值 / 256000
Compaction.MaxContextWindow推导模型上下文窗口时使用的上限；显式值保留256000
Compaction.SummaryReserveTokens为摘要输出预留的 Token20000
Compaction.AutoCompactBufferTokens低于硬上限多少 Token 时触发自动压缩13000
Compaction.WarningBufferTokens到达自动阈值前多少 Token 发出 warning20000
Compaction.ErrorBufferTokens到达自动阈值前多少 Token 发出 error10000
Compaction.ManualCompactBufferTokens低于硬上限多少 Token 时仍允许手动 /compact3000
Compaction.KeepRecentMinTokens局部摘要后尾部至少保留的 Token 数10000
Compaction.KeepRecentMinGroups局部摘要后尾部至少保留的 API 轮次数3
Compaction.KeepRecentMaxTokens局部摘要后尾部最多保留的 Token 数40000
Compaction.MicrocompactEnabled启用微压缩true
Compaction.MicrocompactTriggerCount可压缩工具结果数量达到该值时触发微压缩30
Compaction.MicrocompactKeepRecent微压缩时保留的最近工具结果数8
Compaction.MicrocompactGapMinutes距离上次助理消息超过该分钟数也触发微压缩；0 表示禁用20
Compaction.MaxConsecutiveFailures连续失败次数达到该值时熔断3

模型上下文窗口映射 ​

DotCraft 内置一份常见模型上下文窗口映射表，并会在 Compaction.ContextWindow 未显式配置时自动选择。可以用以下文件补充或覆盖：

  • 全局：~/.craft/model-context-windows.json
  • 工作区：.craft/model-context-windows.json
json
{
  "defaultContextWindow": 256000,
  "models": {
    "my-256k-model": 256000,
    "custom-long-context-": 1048576
  }
}

Reasoning 与 PromptCaching ​

配置项说明默认值
Reasoning.Enabled是否请求 Provider 的推理支持false
Reasoning.Effort推理深度：None / Low / Medium / High / ExtraHighMedium
Reasoning.Output推理内容是否暴露在响应中：None / Summary / FullFull
PromptCaching.Enabled是否为匹配模型注入 prompt cache markertrue
PromptCaching.ModelPatterns大小写不敏感的模型名片段；为空则不匹配任何模型["claude"]
PromptCaching.Placementmarker 放置策略；当前仅支持 ConversationTailConversationTail
PromptCaching.TtlAnthropic cache TTL；为空使用默认 5 分钟，1h 使用长缓存空

Deep-thinking adapter 文件：

  • 全局：~/.craft/model-thinking-adapters.json
  • 工作区：.craft/model-thinking-adapters.json
json
{
  "deepThinking": {
    "models": ["deepseek", "mimo", "my-thinking-model-"],
    "endpoints": ["deepseek", "my-thinking-gateway"]
  }
}

Tools Security 与 Sandbox ​

配置项说明默认值
Security.BlacklistedPathsAgent 绝不能访问的路径；也检查子路径[]
Tools.File.RequireApprovalOutsideWorkspace工作区外文件操作是否需要审批true
Tools.File.MaxFileSize最大可读取文件大小（字节）10485760
Tools.File.RipgrepPath可选 rg 路径；为空时依次尝试 DOTCRAFT_RG_PATH、PATH 和内置回退""
Tools.File.SearchTimeoutSecondsGrepFiles 内容搜索最长运行时间，超时后返回超时结果30
Tools.Shell.RequireApprovalOutsideWorkspace工作区外 Shell 命令是否需要审批true
Tools.Shell.TimeoutShell 命令超时时间（秒）300
Tools.Shell.MaxOutputLengthShell 命令最大输出长度（字符）10000
Tools.Web.MaxCharsWeb 抓取最大字符数50000
Tools.Web.TimeoutWeb 请求超时时间（秒）300
Tools.Web.SearchMaxResults联网搜索默认返回结果数5
Tools.Web.SearchProvider搜索引擎提供商：Bing / ExaExa
Tools.Lsp.Enabled是否启用内置 LSP 工具false
Tools.Lsp.MaxFileSizeLSP 打开或同步文件时允许的最大文件大小10485760
Tools.Sandbox.Enabled是否启用沙箱模式false
Tools.Sandbox.DomainOpenSandbox 服务地址localhost:5880
Tools.Sandbox.ApiKeyOpenSandbox API Key空
Tools.Sandbox.UseHttps是否使用 HTTPSfalse
Tools.Sandbox.Image沙箱容器 Docker 镜像ubuntu:latest
Tools.Sandbox.TimeoutSeconds沙箱超时时间（秒）600
Tools.Sandbox.Cpu容器 CPU 限制1
Tools.Sandbox.Memory容器内存限制512Mi
Tools.Sandbox.NetworkPolicy网络策略：deny / allow / customallow
Tools.Sandbox.AllowedEgressDomains自定义允许出站域名列表[]
Tools.Sandbox.IdleTimeoutSeconds空闲超时（秒）300
Tools.Sandbox.SyncWorkspace是否同步 workspace 到容器true

个人本地 hardening 示例：

json
{
  "Security": {
    "BlacklistedPaths": [
      "~/.ssh",
      "~/.gnupg",
      "~/.aws"
    ]
  },
  "Tools": {
    "File": {
      "RequireApprovalOutsideWorkspace": true
    },
    "Shell": {
      "RequireApprovalOutsideWorkspace": true,
      "Timeout": 300
    }
  }
}

工具 allow-list 示例：

json
{
  "EnabledTools": ["ReadFile", "GrepFiles", "WebSearch"]
}

OpenSandbox 示例：

json
{
  "Tools": {
    "Sandbox": {
      "Enabled": true,
      "Domain": "localhost:5880",
      "Image": "ubuntu:latest",
      "NetworkPolicy": "allow",
      "SyncWorkspace": true
    }
  }
}

Automations Goals 与 Hooks ​

配置项说明默认值
Automations.Enabled是否启用 Automations 编排器true
Automations.LocalTasksRoot本地任务根目录，留空使用 .craft/tasks/空
Automations.PollingInterval轮询间隔00:00:30
Automations.MaxConcurrentTasks本地任务最大并发数3
Automations.TurnTimeout单轮对话超时时间00:30:00
Automations.StallTimeout停顿超时时间00:10:00
Automations.MaxRetries最大重试次数3
Automations.RetryInitialDelay重试初始延迟00:00:30
Automations.RetryMaxDelay重试最大延迟00:10:00
Goals.Enabled启用目标存储、AppServer 方法、目标上下文注入、用量统计和模型 Goal 工具true
Goals.AutoContinueEnabled允许 active 目标在线程空闲时自动继续true
Hooks.Enabled是否启用 Hookstrue
Hooks.EventsHook 事件配置列表[]
Cron.Enabled是否启用 Cron 定时任务服务true
Heartbeat.Enabled是否启用心跳服务false
Heartbeat.IntervalSeconds检查间隔（秒）1800
Heartbeat.NotifyAdmin社交渠道下是否将结果通知管理员true

Automation AppServer 方法：

Method说明
automation/task/list列出本地任务
automation/task/read读取单个本地任务
automation/task/create创建本地任务
automation/task/run立即运行本地任务
automation/task/updateBinding更新或清除线程绑定
automation/task/delete删除本地任务
automation/template/list列出模板
automation/template/save保存用户模板
automation/template/delete删除用户模板

Goal AppServer 方法：

Method说明
thread/goal/set设置、替换、暂停或恢复 Thread goal
thread/goal/get读取当前 Thread goal 状态
thread/goal/clear清除当前 Thread goal

Hook 快速示例：

json
{
  "Hooks": {
    "Enabled": true,
    "Events": {
      "AfterToolCall": [
        {
          "name": "log-tool-call",
          "type": "command",
          "command": "node .craft/hooks/log-tool-call.js",
          "matcher": ".*",
          "timeoutSeconds": 10
        }
      ]
    }
  }
}

Hook 条目字段：

字段说明
nameHook 名称，用于日志和排查
type支持 "command"
command要运行的 Shell 命令
matcher匹配工具名的正则；为空时匹配所有工具相关事件
timeoutSecondsHook 超时时间

生命周期事件：

Event用途
BeforeToolCall工具调用前检查或阻塞
AfterToolCall工具调用后记录、格式化或通知
BeforeTurnAgent turn 前准备上下文
AfterTurnAgent turn 后记录结果或通知
BeforeAutomationTask自动化任务运行前检查
AfterAutomationTask自动化任务完成后同步状态

工具相关 Hook stdin 通常包含：

json
{
  "event": "BeforeToolCall",
  "workspace": "F:\\project",
  "sessionId": "thread-id",
  "toolName": "Exec",
  "arguments": {
    "command": "dotnet test"
  }
}

Turn 相关 Hook stdin 通常包含：

json
{
  "event": "AfterTurn",
  "workspace": "F:\\project",
  "sessionId": "thread-id",
  "summary": "Agent completed the turn"
}

退出码语义：

退出码含义
0成功，继续执行
非零Hook 失败；Before* 事件可以阻塞当前操作

Matcher 示例：

matcher匹配
WriteFile|EditFile文件写入和编辑
ExecShell 命令
.*所有工具

Entry Points and Services ​

配置项说明默认值
Acp.Enabled是否启用 ACP 模式false
DashBoard.Enabled是否启用 Dashboardfalse
DashBoard.HostDashboard 监听地址127.0.0.1
DashBoard.PortDashboard 监听端口8080
Gateway.Enabled是否启用 Gateway Hostfalse
AppServer.ModeAppServer transport mode，例如 stdio 或 WebSocket空
AppServer.WebSocket.HostWebSocket 监听地址127.0.0.1
AppServer.WebSocket.PortWebSocket 监听端口9100
AppServer.WebSocket.Token远程 WebSocket 客户端需要使用的 token空
ExternalChannels外部渠道注册表{}

Dashboard 示例：

json
{
  "DashBoard": {
    "Enabled": true,
    "Host": "127.0.0.1",
    "Port": 8080
  }
}

外部渠道注册示例：

json
{
  "AppServer": {
    "Mode": "WebSocket",
    "WebSocket": {
      "Host": "127.0.0.1",
      "Port": 9100,
      "Token": ""
    }
  },
  "ExternalChannels": {
    "qq": {
      "enabled": true,
      "transport": "subprocess",
      "builtinModule": "channel-qq"
    },
    "wecom": {
      "enabled": true,
      "transport": "websocket"
    }
  }
}

平台连接、权限白名单和审批超时等渠道专属设置分别放在 .craft/qq.json、.craft/wecom.json 等适配器配置文件中。

Plugins MCP 与 LSP ​

配置项说明默认值
Plugins.PluginRoots.craft/plugins/ 之外额外维护的 plugin root 目录[]
McpServersMCP 服务配置集合{}
Tools.DeferredLoading.Strategy工具延迟加载策略：Off、Auto、Simulated 或 NativeAuto
Tools.DeferredLoading.AlwaysLoadedTools始终预加载的 MCP 工具名列表[]
Tools.DeferredLoading.DeferThresholdMCP 工具数量达到该阈值后才延迟加载 MCP 工具10
Tools.DeferredLoading.MaxSearchResults每次延迟工具搜索最多返回的结果数5
LspServersLSP 服务配置集合{}
Tools.Lsp.Enabled是否启用内置 LSP 工具false

外部 plugin root 示例：

json
{
  "Plugins": {
    "PluginRoots": ["./samples/plugins"]
  }
}

MCP 示例：

json
{
  "McpServers": {
    "everything": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"]
    }
  },
  "Tools": {
    "DeferredLoading": {
      "Strategy": "Auto",
      "DeferThreshold": 10
    }
  }
}

Tools.DeferredLoading.Strategy = Auto 时，openai-responses 使用原生 client-executed tool_search，chat-completions / Anthropic 使用模拟 SearchTools。

SubAgent 与 External CLI Profiles ​

入门说明见 SubAgents。

配置项说明默认值
SubAgent.MaxDepthsession-backed SubAgent 最大生成深度；第一级子代理深度为 11
SubAgent.ModelDotCraft 原生 SubAgent 使用的模型；空值继承当前线程的有效主模型空
SubAgent.EnableExternalCliSessionResume是否允许支持 resume 的 external CLI profile 复用已保存外部会话false
SubAgent.DisabledProfiles当前工作区隐藏和禁用的 SubAgent profile 名称列表[]
SubAgent.Roles工作区自定义 SubAgent role；同名条目覆盖内置 role[]

Role 示例：

json
{
  "SubAgent": {
    "MaxDepth": 2,
    "Roles": [
      {
        "Name": "docs-explorer",
        "Description": "Read-only documentation and code explorer.",
        "ToolAllowList": ["ReadFile", "GrepFiles", "FindFiles", "WebSearch", "WebFetch", "SkillView"],
        "AgentControlToolAccess": "Disabled",
        "PromptProfile": "subagent-light",
        "Instructions": "Inspect files and web sources only. Do not edit files, execute shell commands, manage skills, or spawn agents."
      }
    ]
  }
}

SubAgent.Roles 的条目字段：

字段说明
Namerole 名称，也是 SpawnAgent.agentRole 使用的值
Descriptionrole 简短说明，会暴露给主 Agent
ToolAllowList精确工具允许列表；为空表示不额外限制候选工具
ToolDenyList精确工具拒绝列表，会在工具集合构建完成后移除
AgentControlToolAccessAgentTools 策略：Disabled / Full / AllowList
AllowedAgentControlToolsAgentControlToolAccess 为 AllowList 时允许的 AgentTools 名称
PromptProfile原生 SubAgent 提示词 profile：subagent-light / full
Instructions追加到 SubAgent prompt 的 role instructions
Mode可选 mode 覆盖
Model可选 model 覆盖
OverrideBasePrompt是否用 Instructions 覆盖基础 prompt；默认追加而不是覆盖

自定义外部 CLI profile 位于 SubAgentProfiles。工作区配置覆盖同名全局 profile。

json
{
  "SubAgent": {
    "EnableExternalCliSessionResume": true
  },
  "SubAgentProfiles": {
    "my-cli": {
      "runtime": "cli-oneshot",
      "bin": "my-cli",
      "workingDirectoryMode": "workspace",
      "inputMode": "arg",
      "outputFormat": "text",
      "supportsResume": true,
      "resumeArgTemplate": "--resume {sessionId}",
      "resumeSessionIdJsonPath": "session_id"
    }
  }
}

SubAgentProfiles 条目字段：

字段说明
runtimeRuntime 类型；外部短进程 CLI 使用 cli-oneshot
binCLI 可执行文件名或绝对路径
args固定参数列表
workingDirectoryModeworkspace / specified
inputModestdin / arg / arg-template / env
inputArgTemplatearg-template 模式下的输入参数模板
inputEnvKeyenv 模式下接收任务文本的环境变量名
env注入子进程的固定环境变量
envPassthrough从父进程透传的环境变量名
outputFormattext 或 json
outputJsonPathjson 模式下提取最终结果的路径
readOutputFile优先读取输出文件作为最终结果
outputFileArgTemplate输出文件参数模板，支持 {path}
supportsResume是否允许 DotCraft 保存和复用外部 session id
resumeArgTemplateResume 参数模板，支持 {sessionId}
resumeSessionIdJsonPath从 stdout 提取 session id 的 JSON path
resumeSessionIdRegexstdout 不是单个 JSON object 时的正则 fallback
timeout单次运行超时时间（秒）
maxOutputBytes最大捕获输出字节数
trustLeveltrusted / prompt / restricted
permissionModeMapping将 DotCraft 审批模式映射为 CLI 参数

厂商 headless 参考：

Profile行为
cursor-cliDotCraft 注入 -p --output-format json，恢复时追加 --resume {sessionId}
codex-cliDotCraft 注入 exec 和输出文件参数；恢复时使用 exec resume {sessionId}

自定义命令 ​

CustomCommands 可把常用提示词或工作流保存为命令。命令内容通常放在工作区 .craft/commands/ 或对应配置项中，供 CLI、Desktop 或其他入口复用。

Apache License 2.0

Copyright © DotHarness