Dify 的工程实践清单：从目录组织到 AI 友好 CLI

Dify 作为一个功能横跨 Workflow 编排、RAG、插件系统与 Agent 沙箱的 LLM 平台，代码量与模块数量都不小。但翻阅它的仓库会发现，它并非只靠功能取胜——在目录组织、错误处理、沙箱安全和 AI 协作这些「工程卫生」层面，有一批可以直接迁移到你自己项目里的实践。本文把这些实践梳理成一份清单，并配上仓库中的真实代码。

目录与分层约定：controllers/services/core/repositories

Dify 的 api 目录遵循一条清晰的分层脉络：controllers 只管 HTTP 协议，services 承载业务用例，core 放领域核心（workflow、rag、agent、plugin、mcp），repositories 隔离数据访问。这条链路的价值不在于「分层」这个名字，而在于每一层都有明确的依赖方向：Controller 依赖 Service，Service 依赖 Repository 与 core 域，反向依赖不存在。

{{figure:fig-1}}

更难得的是依赖装配不靠全局单例或 import 时副作用，而是集中在 api/extensions/application_services 里，用 frozen dataclass 组成组合根：

@dataclass(frozen=True)
class ApplicationServices:
    workflow_service: WorkflowService
    app_service: AppService
    ...

frozen=True 保证装配完成后容器不可变，测试时可以整体替换某一项。这个模式的可迁移之处在于：它不需要引入任何 DI 框架，一个纯标准库 dataclass 就完成了「依赖可注入、装配可集中」，对小团队尤其友好。

错误处理体系：领域异常到 HTTP 状态码的映射

很多项目的异常处理散落在各处 Controller 里，try/except 反复出现。Dify 选择在 AppResource.dispatch_request 里重写分发逻辑，建立统一的异常翻译层：

def dispatch_request(self, **kwargs):
    try:
        return super().dispatch_request(**kwargs)
    except NotFoundError as e:
        return jsonify({"code": "not_found", "message": str(e)}), 404
    except ValueError as e:
        return jsonify({"code": "invalid_param", "message": str(e)}), 400

设计意图很直接：Service 层抛领域异常（如 NotFoundError），完全不知道 HTTP 的存在；HTTP 语义（状态码、错误响应体结构）在一个地方集中维护。新增一种异常类型只需要加一个映射分支，而不是改几十个 Controller。这是「保持服务层纯净」最省力的实现方式。

沙箱与安全：Landlock、双进程与原子写入

Agent 要执行 shell 命令，安全隔离是刚需。早期 Dify 的沙箱靠 bash + python 脚本链实现，后来用 Go 重写了 shellctl-runner，采用父子双进程模式集成 Linux 的 Landlock 文件系统隔离：

// 父进程负责生命周期管理，子进程先自我施加 Landlock 限制
err := unix.LandlockRestrict(rulesetFD, AT_FDCWD)
if err != nil {
    log.Fatalf("landlock restrict failed: %v", err)
}

Landlock 是内核级的非特权沙箱，一旦在子进程中施加，即使后续代码被攻破也无法回退——这是脚本方案做不到的。配合 tmux 管理会话，整套链路消除了对 bash/python 脚本链的外部依赖。此外沙箱还做了环境变量过滤与配置的原子写入（先写临时文件再 rename），避免半写状态被读取。这条经验可以浓缩为：不受信代码的隔离应下沉到内核原语，而不是靠应用层约定。

{{figure:fig-2}}

面向 Agent 的工程化：AGENTS.md、skills 目录与 CLI agentGuide

Dify 对「代码库会被 AI Agent 阅读」这件事是认真对待的：仓库根目录维护 AGENTS.md 描述项目约定，skills 目录沉淀可复用技能，CLI 框架则为每个命令标注副作用级别与使用指南：

type Command struct {
    Name    string
    Effect  CommandEffect // write 或 destructive
    AgentGuide string     // 面向 AI Agent 的使用说明
}

CommandEffect 让 Agent（或人类）在执行前就知道某条命令是只读、可写还是破坏性的，可以据此决定是否需要确认；agentGuide 则保证命令的调用方式有机器可读的文档，而不是散落在 README 里。这预示着一个趋势：CLI 的用户不再只是人，接口设计的首要考虑对象正在扩展到 Agent。

CI 与质量基建

在测试组织上，Dify 把 e2e 测试独立成自己的目录与 workflow，与单元测试分开触发；linters（Ruff、ESLint 等）在 CI 中作为独立门禁，避免格式问题混入功能评审。异步执行的 Celery 任务与同步 API 各有独立的测试入口，对应 Docker Compose 中分进程部署的拓扑。对多语言仓库来说，「每种语言独立 lint、e2e 独立流水线」是最容易执行也最容易忽视的一条纪律。

可迁移的经验清单

把上面的内容压缩成可以直接抄走的条目：

1. 组合根 + frozen dataclass：用标准库做依赖注入，测试时可整体替换装配。
2. 统一异常翻译层：领域异常只在 HTTP 边界映射一次，Service 层不感知协议。
3. schema 驱动 API：Pydantic 模型同时服务校验与 OpenAPI 文档，一处声明多处受益。
4. 沙箱下沉内核：Landlock + 双进程替代脚本链，隔离不可逆才可信。
5. AI 友好接口：命令标注副作用（write/destructive）并内置 agentGuide。
6. gevent 时序意识：app.py 顶部最先完成 monkey-patching，再导入 DB/gRPC 相关模块，否则协程补丁失效。

Dify 的这些实践没有一条依赖重型框架，大多数是「用一个正确的位置集中处理一类关注点」。如果你的项目还在为散落的 try/except 和隐式全局依赖烦恼，这份清单值得逐条对照检查。