Ducklab

一个全周期的软件开发工具链，默认多 LLM，并且从构造上就是诚实的。

一句话概括： 自托管的开发工具链（Go 引擎 + CLI + 桌面端，优先 Linux）· 简报 → 需求 → 规格 → 计划 → 构建 → 审查 → 发布 · 判定是退出码，而不是模型的意见 · 本地模型优先（llama.cpp、vLLM），同时支持任何 OpenAI 兼容或 Anthropic 端点 · 可由人类或其他代理通过 MCP 操作，决策有记录、可归属 · Apache-2.0 · 自我开发（.ducklab/ 中的运行记录就是凭证）。代理：从 AGENTS.md 和 llms.txt 开始。

你给它一份简报。它编写需求、规格和计划；用一个或多个模型争论来构建任务；运行你项目的真实测试门；并在任何提交之前停下来等你。每次模型调用都有日志。没有模型能决定判定。

它是为本地模型优先而构建的——构建它的大部分工作的两个模型是局域网上的 vLLM 服务器和 localhost 上的 llama.cpp 服务器，两者价格均为零——托管模型与它们并列在同一名册中，用同样的证据衡量。

为什么存在

大多数代理式编码工具假设一个强大的模型并信任它。Ducklab 假设几个便宜的模型，并且不信任任何一个：

• 门决定，而不是模型。 判定是命令的退出码。测试优先的运行在任何测试编写之前测量绿色的基线，之后测量新测试上的红色失败，每次接受都从提交的 sha 的干净检出中重现门——没有重现的东西不会落地，而重现失败的接受会撤回自己的提交。

• 处处去相关。 不同的模型审查；审查者永远不会知道谁写了代码（从负载中缺席，而不是在 UI 中隐藏）；锦标赛评委盲选；议会评论者阅读草稿，而不是彼此。

• 工作是契约。 任务的可交付物是实现者的编号清单；它按编号报告每一项，审查者对照差异检查每一项，未交付的项目会召唤橡皮鸭——一个只在测量到困境（刹车拒绝、失败连击、红色门）时醒来的顾问席位，回答 none（一条让实现者直接回去工作的笔记）或 stop。

• 席位基于证据选择。 每只小鸭都带有记分卡——来自你自己运行的在席通过率、每次运行成本、编码指数——名册板根据这些建议席位，排名标准由你重新排序。建议很少且有理有据：通过率按 Wilson 下界排名，最少三次运行，本地模型永远不会因为 $0 价格而获胜。

• 没有什么是无界的。 轮次、令牌、成本、墙钟时间、工具输出、shell 命令——每个上限都可见且可在运行中提升，并记录在案。

• 你的文档不受模型窗口的限制。 将 wiki 附加到阶段，大席位可以完整读取；小席位会得到每份文档的摘要以适应，全文只需一次 ref_read 调用，门会指出任何没人打开的文档。一个 32k 的本地模型可以被 25 万字符的参考资料简报——工具链承担工作记忆。

而存在性证明：ducklab 是在 ducklab 内部开发的。 计划、错误、发布以及最近九十多个已接受的任务都经过了它自己的循环，由它测量的相同本地和托管模型驱动——最近的功能（多模态聊天、顾问席位、导轨的运行历史）都是由鸭子构建的，由人把关。

Related MCP server: Loki Mode

状态

v0.6.1+，快速推进。七个阶段、五种模式、带有证据和建议的名册板、自动消化的参考文档、从桌面管理的技能、可聊天的坐席顾问（包括图片，发送前验证视觉）、带截图证据的错误、发布、自动驾驶、CLI、桌面应用，以及一个 MCP 服务器，让另一个模型操作整个循环，决策有记录、可归属。

docs/status.md 跟踪所有验收标准，并且不会四舍五入。代码和规格不一致的地方，差异记录在 docs/decisions/。

安装

需要 Go 1.25+、桌面端需要 Node 22+，以及 git。

Linux

CLI 和引擎是纯 Go。桌面端是 Wails v3 应用，需要 GTK/WebKit 开发包：

sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev   # Debian/Ubuntu names
make desktop && make install

在 Ubuntu 24.04+ 上，桌面端还需要 AppArmor 配置文件——参见决策 0003 和 packaging/apparmor/。

macOS

xcode-select --install    # the desktop build links against WebKit
brew install go node
make desktop && make install

诚实说明：ducklab 每天都在 Linux 上开发和运行。CLI 和引擎在每次 make cross 时都会对 darwin/arm64 进行编译检查，但尚未在 Mac 上验证过桌面构建——第一个尝试的人就是测试，make install 无论如何都会给你 CLI 和引擎。请报告任何问题。

两者

make install 安装到 ~/.local/bin——确保它在你的 PATH 中。当桌面二进制文件早于 frontend/src 时，它会发出警告，因为它会愉快地安装过时的版本。

三个二进制文件

提供商密钥来自引擎调用时的环境——在它启动前导出它们，或者通过加载密钥环的包装器启动桌面。应用会告诉你它采用的引擎是否缺少此应用拥有的密钥，并在旁边显示重启按钮。

一个完整的循环

从桌面：项目 → 新项目，然后 循环 → 起草。从终端：

cd ~/dev/myproject
git init                                    # ducklab needs a git repo
ducklab project init --name MyProject       # auto-starts the engine if none is running

ducklab intake --from brief.txt             # brief        → requirements
ducklab spec                                # requirements → spec
ducklab plan                                # spec         → milestones and tasks

ducklab run T-001                           # build it
ducklab run accept r-20260729-...           # commit it

ducklab review T-001                        # read the commit
ducklab release plan --bump minor           # what shipped

每个阶段先写一个 .proposed 文件，然后等你。accept 提升它；reject 精确恢复运行写入的内容，没有其他；"请求更改"将任何草稿——规格、计划、发布说明——连同你的笔记发回。没有你（或你明确授予的自主级别）就不会提交任何内容。

参考文档可以附加到任何阶段：--ref ~/wiki/product/（或桌面中的附加门）加载文件或整个目录作为架构师的背景——由提示中明确陈述的两条规则约束：已批准的需求拥有范围，参考与代码不一致时，代码是真相。当语料库超出席位的上下文时，每份文档被消化一次（按内容哈希缓存），全文仍可通过 ref_read 工具访问，提案卡片列出任何席位从未打开的文档。

采用现有代码库的工作方式相同：接收读取代码并编写按现状需求，规格将其部分标记为 as-built，计划故意保持为空——新工作然后通过错误报告和计划修正进入，这正是 ducklab 自身开发的方式。

你的项目在 .ducklab/project.toml 中声明自己的真相：门（[verify]——包括 link_deps 和 setup 用于干净检出所需）、应用如何启动（[run] 带有预检）、以及项目自己的二进制文件如何重建（[install]），以便整个循环无需离开 ducklab 即可运行。

添加模型

ducklab provider set openrouter --url https://openrouter.ai/api/v1 \
                                --key-env OPENROUTER_API_KEY
ducklab duckling set pato-sonnet --provider openrouter \
                                 --model anthropic/claude-sonnet-4.5 \
                                 --roles reviewer,judge --context 200000 \
                                 --cost-in 3.0 --cost-out 15.0
ducklab duckling test pato-sonnet --prompt "say OK"

--key-env 是环境变量的名称，绝不是密钥。没有密钥写入配置、通过 API 发送或保留在 shell 历史中。

桌面的 名册 视图是分配席位的地方：从鸭群拖到模式的席位上，全局或按项目，每只小鸭的证据在卡片上，引擎的建议在席位旁边。编码/智能/代理指数来自 OpenRouter 的基准端点（当小鸭在那里时）；你自己的运行提供其余部分。

五种模式

ducklab run T-001 --mode <mode>

它不会做什么

这些是承重墙，不是偏好。

• 模型永远不会决定判定。 门是命令的退出码。

• 绿色候选者按字节应用。 通过后不会重新生成。

• 审查者永远不会知道谁写了代码。

• 没有从干净检出重现的东西不会落地。

• 拒绝会撤销运行写入的内容，而不是别人的工作。

• 没有什么是无界的。

• 秘密永远不会触及项目状态。

• 引擎仅限回环。 没有远程模式。

技能

技能是包含 SKILL.md 的目录——在 .ducklab/skills/ 下用于单个项目，或在机器级技能目录中服务于所有项目（项目在名称冲突时遮蔽全局）。仅文档形式没有脚本，是默认：模型阅读并遵循的配方。架构师在采用前阅读调查指南（skill_list 在其提示中），顾问在聊天中阅读，只有实现者可以 skill_run 可执行的技能。

技能从桌面管理（齿轮 → 技能）：列出带有范围徽章和验证问题的列表，读取、编辑整个 SKILL.md，带参数运行，删除。小鸭在运行期间编写的技能在那里显示灰色 待接受，直到其运行被接受——提议技能与提议代码经历相同的门。

ducklab skill new house-style
ducklab skill run changelog-entry --arg summary="..."

顾问

每个项目都设有一个 顾问（名册板上的一个 Common 席位）： 它是"chat about this"门后以及导轨中自由聊天背后的模型。 它阅读代码、运行记录、看板和技能——从不写入——并接受 图片：粘贴一张损坏视图的截图并提问。 视觉能力是经过验证的，而非假设的：声明具有视觉能力的席位会收到一次真实的图片请求来探测，而纯文本席位会以文字拒绝粘贴，而不是凭空捏造答案。

通过另一个模型操作 ducklab

ducklab mcp serve 通过 stdio 将整个循环暴露为 MCP 服务器： 外部模型读取每个结果，决定门禁（带有必需且记录在案的理由——决策以 approved_by: mcp:<client> 的形式落地，绝不会是"human"）， 回答问题、提交 bug、修订计划并开始工作。引擎的 next 列表就是法律：操作者不能采取人无法采取的行动。

参与贡献

参见 CONTRIBUTING.md — 如何构建、测试如何守护架构、工作如何流经 ducklab 自身的循环，以及从哪里开始。简而言之：

make            # vet, test, build the frontend
go test ./...   # 38 packages
cd frontend && npx vitest run

许可证： Apache-2.0。贡献在相同条款下被接受（许可证第 §5 条——无需 CLA）。Ducklab 名称和鸭子形象归维护者所有（§6）。

规范

代码实现了本仓库中的一份书面规范： docs/spec/（00-VISION 至 08-DESKTOP-UI）是 规范性 层——愿景、不变量、协议契约、验收标准。 系统今天的样子存在于 .ducklab/docs/ 中——循环自身维护的建成需求、规范和计划，每个版本都在人工门禁处签名。 两者有意不同之处记录在 docs/decisions/ 中；两者之间的差异就是路线图，对齐阶段会计算它。