坚定的观点,
由代码支撑

每个项目都有其信念。大多数信念存在于某人的脑海中,并在每次代码审查时逐渐泄露。这些是 Duct 的信念,已书面记录,每条都附有强制执行它的文件。

Duct 是一个 AI 智能体,它能读取你的产品和增长技术栈,并能对其进行更改。这对于一个并非你编写的工具来说,需要极大的信任。因此,其推理过程是公开的,支撑它的代码也是公开的。

以下内容均非空想。 每条原则都链接到使其成立的文件。如果你发现代码与页面不符,那是一个 bug,请提交问题。

01

智能体提出建议。人类批准。

Duct 可以为你的实时系统准备变更:暂停广告系列、添加否定关键词、标记 GA4 关键事件。它会向你显示预览和安全检查。然后它会停止。

没有面向智能体的批准或应用工具。没有禁用版本,也没有隐藏在功能标志后面的版本。它不存在于模型看到的工具注册表中,因此模型无法调用它,无法被说服调用它,也无法通过提示注入来调用它。破坏性门控是绝对的:没有任何配置允许破坏性操作自动应用。回滚是每个执行器契约的一部分,而不是事后才考虑的。

更高的自主性是一种姿态,而非更宽泛的允许列表。它改变了智能体打断你的频率。它从不改变未经点击即可应用的内容。

backend/service/execution/policy.py
02

Duct 租用智能体线束。它不绑定任何一个。

智能体框架是此技术栈中变化最快、差异化最小的层。它们是 0.x 版本,每周发布,并且每个都曾强制某人进行破坏性迁移。在此之上构建产品无异于租用地基。

因此,这里的领域代码不导入任何智能体框架。提示、工具、模式、目标、评分和成果文档契约都是纯 Python。框架导入仅存在于运行器和绑定器中,并且一个测试通过显式允许列表来强制执行边界。将文件添加到该允许列表是一个有意的行为,而不是你修复失败测试的方式。

我们刻意没有 AgentHarness 接口,也永远不应该有。取交集会让你失去子智能体、文件系统、技能、HITL 粒度和压缩,而这正是租用 harness 的全部原因。取并集则是在编写一个框架。

backend/agents/core/ports/__init__.py
03

在第二个实现上编写适配器,而不是第一个。

只有一个实现的端口是猜测。有两个实现的端口是事实。在第二个实现出现之前构建的抽象会编码第一个实现碰巧需要的任何东西,然后后续的一切都将与该形状作斗争。

智能体层中的每个端口都有两个适配器,只有一个例外,该端口在其自己的文档字符串中说明了这一点,并命名了将获得它的实现。指出这个空白可以防止它被悄悄地用猜测填补。

STYLE.md
04

授权即成员资格,API key 并非边界。

应用的 API 密钥会发送到浏览器。它证明“此请求来自 Duct 应用”。它从未证明“此调用者拥有该行”,如果这样对待它,就会导致多租户数据泄露。

因此,每个涉及项目范围行的路由都会解析已登录用户并检查成员资格。非成员会收到 404,而不是 403,因为 403 会告诉他们该行存在。一个测试会遍历树中的每个路由,如果某个路由未经书面理由而未受限制,则构建失败。

backend/tests/test_route_auth_boundaries.py
05

你的机器,你的密钥,你的数据。

Duct 作为桌面应用运行,将后端捆绑为本地伴随服务:磁盘上的 SQLite,仅限回环,提供商密钥存储在操作系统密钥链中。没有账户,没有服务器,没有任何东西离开你的机器。或者自托管后端。或者使用 getduct.ai 上的托管版本,它运行的代码与你可阅读的代码相同。

也请自带模型。Anthropic、OpenAI、Gemini 或 OpenRouter 上的任何模型,按作业分配到三个层级,这样推理密集型工作和廉价摘要就不会支付相同的价格。一个读取你整个业务的工具不应该同时决定你的供应商是谁。

desktop/README.md
06

注释承载原因。差异已显示内容。

重复下方代码的注释比没有注释更糟糕,因为它会引导读者跳过注释。值得编写的注释应承载代码无法表达的内容:约束、契约、促成该行的失败原因,以及被拒绝的替代方案及其原因。

在部分由智能体编写的代码库中,这一点变得更加重要。一组单独可辩护的变更,如果它们共同瓦解了架构,正是智能体加速的代码库失败的特定方式:每个变更都为自己辩护,但没有人为整体辩护。文件中留下的推理能让下一个人或下一个模型分辨出差异。

STYLE.md
07

欢迎智能体编写的贡献。审查更严格,而非更宽松。

许多项目正在悄悄禁止 AI 辅助的拉取请求。Duct 则要求相反:PR 模板会询问智能体在何处提供了帮助,以便审阅者知道在哪里最需要仔细查看。那不是惩罚区。这与你说明对变更的哪个部分最不确定是出于同样的原因。

Duct 是一个用智能体构建的智能体产品。在贡献过程中假装不是这样是不诚实的,并且会丢弃审阅者能获得的最有用的信号。

CONTRIBUTING.md

不同意?

好的。提交问题。

这些默认设置都有其原因,而非法律。如果原因有误,应改变的是原因。这种讨论应公开进行。

开始讨论 → 阅读代码 →