running-coding-tasks-with-dcode

能力目标

在自己的机器上把官方终端编码智能体装好、接上指定模型、在任意工程目录里跑通一个多步改码任务，并看到磁盘文件真的被改；交互模式下能看差异并逐步审批，无交互模式下能塞进脚本与持续集成。

前置

• 一个可用模型：某家厂商的凭证，或本机装好的本地模型服务。
• 先分清三个名字相近的包，装错就一直 command not found：核心库提供构造函数、部署包只含部署子命令、终端智能体包才提供 dcode 命令。原先用库名启动交互界面的命令已不存在。
• 这个成品内部字面调用的就是库里的智能体构造函数，同一套中间件、同一套审批参数，只是壳替你把后端与审批清单都拍板好了。

实操流程

1. 一键安装并验证：

   curl -LsSf https://langch.in/dcode | bash
   which dcode
   dcode --version 2>&1 | head -15
   

   底层等价于用 uv 把工具装进一套独立隔离的虚拟环境（自带独立解释器），可执行文件落在 ~/.local/bin/ 下。这个目录必须在环境变量 PATH 里。查落点：

   uv tool list | grep deepagents
   

2. 本机若设了 HTTP 代理，运行前先让本地地址绕过代理：

   export NO_PROXY="127.0.0.1,localhost"
   export no_proxy="127.0.0.1,localhost"
   

3. 准备任务目录：一个工作目录加一份写明需求的任务说明文件，代码文件放里面即可。

   mkdir -p my-task && cd my-task
   # 目录里放好待改的代码文件，再写一份 TASK.md 说明要做什么
   

4. 无交互模式首跑，显式指定模型（提供方前缀加型号名）：

   export DEEPSEEK_API_KEY=...     # 从自己的环境注入，不要写进脚本
   dcode --model deepseek:deepseek-chat \
     -n "按照 TASK.md 的要求完成任务。"
   

5. 要把某个模型定成稳定默认，写进配置的稳定键、而不是依赖会被覆盖的最近使用键：

   dcode config set models.default deepseek:deepseek-chat
   dcode config show 2>&1 | grep -i "openai\|deepseek\|anthropic"
   

   选模型走四层优先级，从高到低是：命令行显式指定、配置文件里的稳定默认键、配置文件里的最近使用键、按环境变量自动探测。

6. 进交互模式看差异与审批：

   dcode --model deepseek:deepseek-chat
   

   准备改文件时会弹出审批对话框，列出文件路径、变更差异与三个选项（本次批准、本线程内自动批准、拒绝），任务暂停等你拍板。这就是按工具名声明审批门的界面化呈现：有副作用的操作（写文件、编辑文件、执行命令、联网检索、抓取网页、委派）执行前暂停，只读操作（读文件、列目录、通配匹配、检索）不审批。加自动批准标志等价于把审批门清空，状态栏会从手动切到自动。任务跑完在输入框敲用量命令可查本线程的 token 明细。

7. 要在本地模型上零成本跑通链路，先把提供方依赖装进那套隔离环境。注意这个安装会替换之前的附加依赖列表，所有需要的提供方要一次列全：

   uv tool install deepagents-code --with langchain-ollama \
     --with langchain-deepseek --with langchain-openai --with langchain-anthropic
   dcode --model ollama:qwen2.5:0.5b -n "Read calc.py and list all function names."
   

8. 换数据复用只有三个旋钮：换任务就换工作目录与任务说明文件、换模型就换指定参数或配置、换运行方式就在交互与无交互之间切。

校验回路

• 装好的判据：which dcode 打印出可执行文件路径，版本命令一屏列出版本号与已装的提供方依赖清单。
• 首跑的判据：日志里出现服务就绪、随后是一串工具调用（读文件、通配匹配、编辑文件、写文件、执行命令），最后任务完成。
• 磁盘核验才是真验收：直接看目标文件内容是否真的按需求改了。任务完成那行只表示智能体回复了且没报错，不代表任务做对了——实测能力有限的小模型调错了工具、任务没完成，仍然打印了任务完成。
• 模型真生效的判据：每次运行的头信息里 Model: 字段是你指定的型号；配置查看命令里对应厂商的凭证状态为已配置。
• 想看能力全貌，跑一个足够复杂的多步任务（改函数、加测试、写说明），日志里应能看到规划工具的分步记录、多次文件读写、以及一次命令执行验证。

常见陷阱

• 敲库名当命令：报 command not found。交互界面已经拆到独立的终端智能体包里，命令名是 dcode。装的包名与敲的命令名不同名，这是最高频的坑。两个相关包的版本号可能同步，别因版本号一致就以为是同一个包。
• 服务健康检查 60 秒超时：报 Server did not become healthy within 60s。根因是本机 HTTP 代理把对本地回环地址的健康检查请求也路由给了代理、代理返回错误，而服务其实早就起好了。解法是让本地地址绕过代理。这一条曾长期被误判为版本缺陷、升级版本或反复重试都无效，别再往那个方向排查。
• 配了某家模型却在调另一家：自动探测名单只认几家主流厂商，名单外的厂商即使配了凭证也不会被自动选中。若环境里同时存在名单内厂商的凭证、配置文件里又没写默认键、命令也不带指定参数，就会静默回落到名单内的那家，头信息里显示的是另一个型号、随后抛鉴权错误。两条救回方法：命令显式指定，或写进配置的稳定默认键。
• 把最近使用键当默认：那个键是切换模型时系统自动写入的，会被下一次切换覆盖。稳定偏好要写另一个键。
• 装提供方依赖时只列新增的那个：附加依赖列表是整体替换，会把之前装的其他提供方顶掉，之后报缺提供方包。一次列全。
• 能连上不等于能跑好：成品为内置支持的型号预设了配置档（含最大输出长度、温度、重试策略、工具调用格式等），没有对应配置档的冷门模型工具调用格式可能不对、规划容易跳步。命令行提供了覆盖配置档字段的选项。
• 不清楚代码在哪台机器上跑：默认在本地机器执行，写的文件就是本机路径。只有显式加沙箱选项才上云隔离。判断准则：信任任务代码就默认本地执行、效率高；不信任就加沙箱。
• 以为它是另一套引擎：它内部字面调用的就是库里的智能体构造函数。区别只在于壳替你拍板了配置——库默认用的是状态后端（写文件只进状态字典、磁盘上没有文件），而这个成品启用的是写真实磁盘的后端。