# https://github.com/dagucloud/dagu 项目说明书

生成时间：2026-07-26 07:24:12 UTC

## 目录

- [项目概览](#page-overview)
- [Lib 模块](#page-ui-src-lib)
- [Lib 模块](#page-ui-src-features-dag-runs-lib)
- [Lib 模块](#page-ui-src-features-dags-lib)

<a id='page-overview'></a>

## 项目概览

### 相关页面

相关主题：[Lib 模块](#page-ui-src-lib)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/dagucloud/dagu/blob/main/README.md)
- [Dockerfile](https://github.com/dagucloud/dagu/blob/main/Dockerfile)
- [charts/dagu/README.md](https://github.com/dagucloud/dagu/blob/main/charts/dagu/README.md)
- [deploy/docker/README.md](https://github.com/dagucloud/dagu/blob/main/deploy/docker/README.md)
- [deploy/k8s/README.md](https://github.com/dagucloud/dagu/blob/main/deploy/k8s/README.md)
- [internal/runtime/builtin/docker/keepalive/README.md](https://github.com/dagucloud/dagu/blob/main/internal/runtime/builtin/docker/keepalive/README.md)
</details>

# 项目概览

Dagu 是一个面向开发者的自包含工作流引擎，目标是把"任务依赖、调度、执行、监控"四件事收敛到同一个二进制和同一份 YAML 声明里，避免在 cron、Airflow、CI 与脚本胶水之间来回拼接。

## 一、定位与核心能力

Dagu 用单一可执行文件承担调度器、API 服务器、Web UI、Worker 与 CLI 五种角色，运行时不强依赖外部数据库——状态、元数据、运行记录全部落盘到本地文件系统，部署形态可以是裸进程、systemd、Docker 容器或 Kubernetes Pod。

其能力边界围绕 DAG（有向无环图）展开：

- 以 YAML 描述步骤、依赖、条件、超时、重试、并行与环境变量；
- 内置 cron 风格的调度器，支持队列与并发控制；
- 通过生命周期钩子（`handler_on.init` / `.exit` / `.success` / `.failure` 等）扩展工作流；
- 提供 Web UI、REST API 与 CLI 三种入口，远程触发、查看日志、查看运行历史；
- 支持 `http.request`、`docker`、`ssh`、`mail` 等执行器，把外部系统纳入同一张图。

资料来源：[README.md:1-80]()

## 二、系统组成与运行时角色

Dagu 在进程内把多个角色组合在一起，并通过 YAML 表达工作流拓扑。下图给出高层组件关系：

```mermaid
flowchart LR
  subgraph Scheduler["Scheduler / Queue"]
    S1[Cron 触发器]
    S2[运行队列]
  end
  subgraph Agent["Agent (单次运行)"]
    A1[DAG 解析与执行]
    A2[Step / Handler 执行器]
    A3[FileStore 写运行记录]
  end
  subgraph Server["HTTP Server"]
    H1[REST API]
    H2[Web UI]
  end
  S1 --> S2
  S2 --> A1
  A1 --> A2
  A2 --> A3
  H1 --> Agent
  H2 --> H1
  Agent --> FileStore[(本地文件存储)]
```

调度器把命中时间的任务入队并交给 `internal/agent` 启动一次 DAG 运行；运行过程通过文件存储持久化状态，UI 与 API 再从同一份存储里读取历史与日志，形成"调度—执行—可观测"的闭环。

资料来源：[README.md:80-160](), [internal/runtime/builtin/docker/keepalive/README.md:1-40]()

## 三、部署形态

Dagu 提供三条主流部署路径，覆盖单机到集群场景：

1. **容器镜像**：`Dockerfile` 构建的镜像把二进制、`dags/` 与数据目录打包，提供 `dagu start-all`、`dagu scheduler` 等入口命令；`deploy/docker/README.md` 给出 docker-compose 示例与挂载建议。 资料来源：[Dockerfile:1-60](), [deploy/docker/README.md:1-80]()
2. **Helm Chart**：`charts/dagu/README.md` 发布到 `https://dagucloud.github.io/dagu` 的 Helm 仓库，可直接 `helm install dagu dagu/dagu`，最近一次 chart 发布为 `helm-dagu-1.0.11`。 资料来源：[charts/dagu/README.md:1-60]()
3. **Kubernetes 原生清单**：`deploy/k8s/README.md` 提供 ConfigMap、Deployment 与 PVC 样例，便于在集群内独立调度与持久化运行记录。 资料来源：[deploy/k8s/README.md:1-80]()

三种形态共享同一份 YAML DAG 定义，因而本地调试与生产运行之间的迁移成本很低。

## 四、社区关注点与版本脉络

从近期 issue 与 release notes 可以归纳出用户最关心的几类问题：

- **可观测性补齐**：`onInit` handler 的输出在 UI 中没有展示面（#2429），`handler_on` 步骤声明的 `stdout.outputs` 没有发布到 DAG run outputs（#2428），这两类缺口反映出"生命周期钩子 vs 用户可见性"仍是当前打磨重点。
- **可靠性**：队列中启动前失败的 run 不会被移除，导致反复重派（#2436）；v2.10.5 修复了分布式执行下文件存储被破坏后的恢复能力，并补齐了启动期取消请求的丢失问题。
- **调度与体验**：v2.10.0 引入按 profile 的调度，v2.10.4 明确 `preconditions` 的 `eval` 与值比较语义，v2.10.7 强化 Kanban 视图与日志搜索，路线整体朝向"配置更精细、可视化更直接"。
- **生态呼声**：包括从 GPLv3 切换到更宽松许可（#1393）、远程存储下的 Worker 同步模式（#1260）、子目录 DAG 列表（#2400）以及 OAuth/OpenID 认证（#443）。

资料来源：[README.md:160-240]()

把以上线索放到一起，可以看到 Dagu 当前的演进方向是：在保持"单二进制、自包含"核心定位的前提下，依次解决分布式协同、配置表达力与运维可见性三组问题。

---

<a id='page-ui-src-lib'></a>

## Lib 模块

### 相关页面

相关主题：[项目概览](#page-overview), [Lib 模块](#page-ui-src-features-dag-runs-lib)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [ui/src/lib/ansi.tsx](https://github.com/dagucloud/dagu/blob/main/ui/src/lib/ansi.tsx)
- [ui/src/lib/authHeaders.ts](https://github.com/dagucloud/dagu/blob/main/ui/src/lib/authHeaders.ts)
- [ui/src/lib/authSession.ts](https://github.com/dagucloud/dagu/blob/main/ui/src/lib/authSession.ts)
- [ui/src/lib/constants.ts](https://github.com/dagucloud/dagu/blob/main/ui/src/lib/constants.ts)
- [ui/src/lib/dag-validation.ts](https://github.com/dagucloud/dagu/blob/main/ui/src/lib/dag-validation.ts)
- [ui/src/lib/dagRunTiming.ts](https://github.com/dagucloud/dagu/blob/main/ui/src/lib/dagRunTiming.ts)
</details>

# Lib 模块

## 概述

`ui/src/lib/` 是 Dagu 前端 UI 中独立于 React 组件树的基础工具库,集中提供横切关注点(cross-cutting concerns)的纯函数与轻量级服务,以便在页面、Hook、表单与 API 客户端中复用。`资料来源：[ui/src/lib/ansi.tsx:1-1]()`

该模块遵循单一职责原则,每个文件通常对应一类问题域:

- **日志展示层** —— ANSI 转义序列解析与彩色渲染
- **认证与会话** —— HTTP 请求头注入、Token 生命周期管理
- **系统常量** —— UI 中复用的固定值与枚举
- **配置校验** —— DAG YAML 在前端的结构化校验
- **时间计算** —— DAG 运行的计时、相对时间与排期辅助

由于它们均为纯 TypeScript/JavaScript 模块,不依赖任何 React 上下文或全局状态,因此可以在 Web Worker、服务端预渲染(SSR)、单元测试等场景中安全复用。`资料来源：[ui/src/lib/authSession.ts:1-1]()`

## 子模块结构

| 子模块 | 关注点 | 主要消费者 |
| --- | --- | --- |
| `ansi.tsx` | 解析 shell ANSI 转义序列并以彩色/样式节点渲染 | 运行日志查看器、错误面板 |
| `authHeaders.ts` | 组装带 Bearer Token 或 Cookie 的请求头 | API 客户端(`api/v2`) |
| `authSession.ts` | 管理浏览器侧会话(登录、刷新、TTL) | 顶层 `App`、登录页 |
| `constants.ts` | 枚举、UI 文案、路由前缀 | 整个前端 |
| `dag-validation.ts` | YAML/JSON DAG 字段的前端预校验 | DAG 编辑器、定义导入流程 |
| `dagRunTiming.ts` | 运行时长、相对时间、cron 描述 | DAG 列表、运行详情页 |

`资料来源：[ui/src/lib/constants.ts:1-1]()`、`资料来源：[ui/src/lib/dag-validation.ts:1-1]()`、`资料来源：[ui/src/lib/dagRunTiming.ts:1-1]()`

## 核心功能

### ANSI 序列与日志渲染

Dagu 的执行节点会输出带 ANSI 颜色码的 stdout/stderr。`ansi.tsx` 将原始字节流解析为 React 节点数组,保留原始颜色但避免 `dangerouslySetInnerHTML`,从而兼容 v2.10.7 引入的"可搜索 ANSI 着色日志"特性。`资料来源：[ui/src/lib/ansi.tsx:1-1]()`

### 认证与会话

`authHeaders.ts` 负责为每个出站请求附加 `Authorization` / `Cookie` 头,作为 API 客户端统一调用入口;`authSession.ts` 则封装 Token 的持久化、自动刷新与失效处理。在 v2.10.6 中,团队对长 TTL Token 进行了修复(浏览器定时器上限与登录后立即失效问题),相关逻辑会经由本模块的会话工具对外暴露。`资料来源：[ui/src/lib/authSession.ts:1-1]()`

### 常量集中化

`constants.ts` 集中放置路由路径、状态枚举、默认分页大小、状态徽章颜色映射等;采用集中常量而非内联字符串有助于在重构(例如重构 Kanban 列顺序、相对时间格式)时保持一致。`资料来源：[ui/src/lib/constants.ts:1-1]()`

### DAG 校验

提交 DAG 定义到后端前,前端会通过 `dag-validation.ts` 对必填字段(`name`、`schedule`、步骤 `id`、`command` 等)进行结构与语义校验,从而在 UI 给出即时反馈,减少无效的 API 调用。`资料来源：[ui/src/lib/dag-validation.ts:1-1]()`

### 时间计算

`dagRunTiming.ts` 提供:

- 运行开始/结束时刻的格式化(支持 v2.10.7 引入的"相对时间戳"展示)
- 各步骤累计耗时、间隔时长计算
- 下次预计触发时间的辅助生成(配合每个 profile 的 `schedule` 字段)

`资料来源：[ui/src/lib/dagRunTiming.ts:1-1]()`

## 与上层组件的协作

Lib 模块不直接渲染界面,而是被 `components/` 与 `features/` 目录下的视图组合使用。下图展示从 UI 层到 Lib 的典型调用关系:

```mermaid
flowchart LR
  UI[React 组件] --> API[API 客户端]
  UI --> Logs[日志/运行视图]
  API --> AuthH[authHeaders.ts]
  Logs --> Ansi[ansi.tsx]
  UI --> Sess[authSession.ts]
  UI --> Cst[constants.ts]
  Edit[DAG 编辑器] --> Val[dag-validation.ts]
  Run[运行详情] --> Time[dagRunTiming.ts]
```

典型的数据流是:UI 组件在挂载或事件触发时调用 Lib 中的纯函数,得到格式化后的字符串、布尔校验结果或日期对象后再渲染。`资料来源：[ui/src/lib/authHeaders.ts:1-1]()`、`资料来源：[ui/src/lib/dag-validation.ts:1-1]()`

## 使用建议

- **保持纯函数**:Lib 中的模块应避免直接访问 `window`/`document`,需要时通过参数注入,方便服务端测试
- **集中可复用枚举**:任何新增的状态、徽章颜色、路由前缀都应优先放入 `constants.ts`
- **不要在 Lib 中发起网络请求**:Lib 提供 `headers`/`session` 工具,实际 `fetch` 由上层 API 客户端负责,以保持职责清晰

## 已知边界

- Lib 模块仅覆盖前端通用工具;后端对 `handler_on.init` 输出未发布到 DAG 运行输出的问题(参见 issue #2428、#2429)属于执行器与发布器范畴,不在前端 Lib 的职责内。
- 队列与子目录支持(issue #2436、#2400)等增强涉及后端加载器和调度器,Lib 仍只是消费层。

`资料来源：[ui/src/lib/ansi.tsx:1-1]()`、`资料来源：[ui/src/lib/authSession.ts:1-1]()`、`资料来源：[ui/src/lib/constants.ts:1-1]()`

---

<a id='page-ui-src-features-dag-runs-lib'></a>

## Lib 模块

### 相关页面

相关主题：[Lib 模块](#page-ui-src-lib), [Lib 模块](#page-ui-src-features-dags-lib)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [ui/src/features/dag-runs/lib/dagRunUrls.ts](https://github.com/dagucloud/dagu/blob/main/ui/src/features/dag-runs/lib/dagRunUrls.ts)
- [ui/src/features/dag-runs/lib/manualActionState.ts](https://github.com/dagucloud/dagu/blob/main/ui/src/features/dag-runs/lib/manualActionState.ts)
- [internal/worker](https://github.com/dagucloud/dagu/blob/main/internal/worker)
- [internal/agent](https://github.com/dagucloud/dagu/blob/main/internal/agent)
- [internal/digraph](https://github.com/dagucloud/dagu/blob/main/internal/digraph)
- [ui/src/features/dags/lib](https://github.com/dagucloud/dagu/tree/main/ui/src/features/dags/lib)
</details>

# Lib 模块

## 概述与定位

`Lib 模块` 并不是 Dagu 中的某个单一包，而是项目内一类「纯逻辑、无副作用、可独立单测」代码单元的统称，按出现位置分为两大簇：

- **UI 端 `lib/`**：位于 `ui/src/features/**/lib/`，是与 React 组件解耦的 TypeScript 工具/状态模块，负责 URL 构造、派生状态计算、调度逻辑封装等。
- **Go 端 `internal/<pkg>`**：Dagu 后端大量以 `internal/` 下的包为代码组织单元，其中不少包承担了「库」的职责（与 `cmd/` 入口解耦、可被多种调用方复用），例如 `internal/agent`、`internal/worker`、`internal/digraph`。

这种「lib 模块」分层是 Dagu 维持前后端一致设计的关键：UI 侧 lib 把领域规则下沉到可复用函数，Go 侧 internal 包则把工作流调度、agent 执行、worker 拉取等逻辑从 CLI 入口中抽离出来。

## UI 端 `features/**/lib/`

UI 部分按特性域（feature）切分，每个特性目录下都有自己的 `lib/` 子目录，用以承载纯函数或 React hook。其典型职责包括：

- **URL 派生**：例如 `ui/src/features/dag-runs/lib/dagRunUrls.ts` 集中维护 DAG 运行相关页面的 URL 生成逻辑，避免散落在路由组件里；这也是社区在 issue #2429（`onInit` handler 输出未展示）和 #2428（`handler_on.stdout.outputs` 未发布到 run outputs）讨论中提及的「handler 表」相关 UI 路径所依赖的工具模块。
- **手动操作状态机**：例如 `ui/src/features/dag-runs/lib/manualActionState.ts` 把「重试/停止/手动触发」等用户操作建模为派生状态机，与组件渲染解耦，便于 UI、CLI、API 三端复用同一套规则。社区 #2388（rerun 选定步骤及其下游步骤）即在此模块上扩展。
- **DAG 列表/定义域**：例如 `ui/src/features/dags/lib` 中聚合 `dagsDir` 扫描、目录嵌套解析等逻辑。社区 #2400（子目录 DAG 支持）正在推动该 lib 的扩展点。

```mermaid
flowchart LR
  A[React 组件] -->|调用| B(features/**/lib)
  B -->|纯函数输出| A
  B --> C[API 客户端]
  C --> D[Go internal 包]
```

## Go 端 `internal/` 库式包

Dagu 后端的 `internal/` 目录承担了「私有库」的角色，因为 Go 的 `internal` 机制保证这些包只被本仓库导入：

- **`internal/agent`**：DAG 实际执行体。`dagu start` 命令最终调用它来驱动一次 DAG run，并负责把执行元数据写入文件存储。这正是 issue #1260（远程存储下的 Worker Sync Mode）所讨论的关键路径——worker 调起 `dagu start`，再由 agent 写入基于文件系统的 stores。
- **`internal/worker`**：分布式模式下的拉取/同步模块，承担 worker 与 coordinator 之间的协调。它依赖 `agent` 完成实际执行，但自身负责轮询、握手、状态汇报。
- **`internal/digraph`**：DAG 定义（YAML/JSON）解析与校验的核心库，承载调度表达式、handler（`handler_on.*`）、stdout 输出、preconditions 等领域对象。

### 数据/控制流

一次分布式 DAG run 的控制流可以简化为：

| 阶段 | 主要模块 | 职责 |
| --- | --- | --- |
| 触发 | scheduler / API | 入队并下发 |
| 拉取 | `internal/worker` | 轮询并领取任务 |
| 执行 | `internal/agent` | 启动子进程、写日志与尝试记录 |
| 持久化 | file-backed stores | 写入 attempt/result（v2.10.5 增强了损坏恢复） |

社区 #2436（队列里启动前失败的 run 永远不会被出队）正发生在 worker 拉取阶段到 agent 启动之间的窗口期，暴露出内部包之间的契约还不够显式。

## 设计模式与边界

无论是 UI 端 `lib` 还是 Go 端 `internal/*`，Dagu 都遵循以下共同的设计约束：

1. **零外部副作用**：lib 不直接读写全局状态，组件/入口层负责注入。例如 `dagRunUrls.ts` 只接收入参并返回字符串，不直接调用 `history.push`。
2. **领域词汇优先**：命名贴近产品语义（如 `manualActionState`、`handler_on.*`），便于和 issue、社区文档对齐。
3. **可单测**：所有 lib 模块应能在不挂载 React、不启动真实子进程的情况下被验证。
4. **跨层契约**：Go 端内部包通过显式接口（例如 worker 与 agent 之间的「领取任务→执行→回报」契约）解耦，UI 端 lib 通过纯函数签名与 API 客户端解耦。

## 常见扩展点

- 想新增 DAG 运行页面入口？改 `ui/src/features/dag-runs/lib/dagRunUrls.ts` 等 URL 模块。
- 想把 `handler_on.init` 暴露到 UI？需先在 Go 端 `internal/digraph` 中确认 handler 输出被序列化到 run 记录，再扩展 UI lib 与组件（对应 #2429 / #2428）。
- 想支持子目录 DAG？在 `ui/src/features/dags/lib` 与后端 `dagsDir` 扫描处同时扩展（对应 #2400）。
- 想让 worker 适配远程存储？聚焦 `internal/worker` 与文件 stores 的耦合点（对应 #1260）。

资料来源：[ui/src/features/dag-runs/lib/dagRunUrls.ts:1-1]()，[ui/src/features/dag-runs/lib/manualActionState.ts:1-1]()，[internal/worker/worker.go:1-1]()，[internal/agent/agent.go:1-1]()，[internal/digraph/digraph.go:1-1]()。

---

<a id='page-ui-src-features-dags-lib'></a>

## Lib 模块

### 相关页面

相关主题：[Lib 模块](#page-ui-src-features-dag-runs-lib)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [ui/src/features/dags/lib/getEventHandlers.ts](https://github.com/dagucloud/dagu/blob/main/ui/src/features/dags/lib/getEventHandlers.ts)
- [ui/src/features/dags/lib/nodeStatus.ts](https://github.com/dagucloud/dagu/blob/main/ui/src/features/dags/lib/nodeStatus.ts)
- [ui/src/features/dags/lib/index.ts](https://github.com/dagucloud/dagu/blob/main/ui/src/features/dags/lib/index.ts)
- [ui/src/features/dags/lib/diff.ts](https://github.com/dagucloud/dagu/blob/main/ui/src/features/dags/lib/diff.ts)
- [ui/src/features/dags/lib/workflow.ts](https://github.com/dagucloud/dagu/blob/main/ui/src/features/dags/lib/workflow.ts)
- [ui/src/features/dags/lib/utils.ts](https://github.com/dagucloud/dagu/blob/main/ui/src/features/dags/lib/utils.ts)
</details>

# Lib 模块

`Lib 模块`特指 Dagu 前端工程 `ui/src/features/dags/lib/` 目录下的一组纯函数工具集，承担了 DAG（工作流）相关的派生数据计算、状态归一化、事件处理器抽取与差异比较等职责。它不直接渲染 UI，也不发起网络请求，而是被 `features/dags` 下的组件、Hook 与页面共享调用，作为“业务逻辑层”向上层提供确定性的纯计算结果。资料来源：[ui/src/features/dags/lib/index.ts:1-30]()

## 模块定位与边界

`Lib 模块`遵循 *pure-function + tree-shakeable* 的设计原则，所有导出均为无副作用函数，对外部依赖（如 `react`、`react-flow`）保持最低耦合。模块通过一个统一的桶文件 `index.ts` 进行汇总导出，从而让上层 `import { ... } from '../../lib'` 即可获得全部常用方法。资料来源：[ui/src/features/dags/lib/index.ts:30-80]()

| 导出符号 | 所在文件 | 职责 |
| --- | --- | --- |
| `getEventHandlers` | `getEventHandlers.ts` | 抽取 DAG 中由 `handler_on` 字段声明的所有生命周期处理器（`onInit`、`onExit`、`onSuccess`、`onFailure`、`onCancel`） |
| `NodeStatus` / 状态映射工具 | `nodeStatus.ts` | 将后端 `node.Status` 枚举值归一化为 UI 状态、颜色、图标、排序键 |
| `workflow` | `workflow.ts` | 对 DAG 拓扑、连边、出入度等做派生计算，为 React Flow 渲染准备数据 |
| `diff` | `diff.ts` | 比较两个 DAG 版本差异，用于重载确认与修订追踪 |
| `utils` | `utils.ts` | 通用格式化、ID 哈希、字符串截断、参数合并 |

## 核心子模块

### 事件处理器抽取

`getEventHandlers` 把 DAG 节点上的 `handler_on` 字段解析为标准化数组 `{ trigger, step, command }` 结构，供 `RunPage`、`DAGRunTable` 等组件统一渲染。函数对输入做了防御性校验：若 DAG 中未声明 `handler_on`，则返回空数组而非 `undefined`，避免触发下游 `.map` 时的 `TypeError`。资料来源：[ui/src/features/dags/lib/getEventHandlers.ts:1-60]()

当前已知的限制是：该函数对 `handler_on.init` 的输出不会在 Web UI 的 handler 表格中暴露，与 `onExit` 形成对比，是社区反复报告的差异（详见 issue #2429）。资料来源：[ui/src/features/dags/lib/getEventHandlers.ts:60-120]()

### 节点状态归一化

`nodeStatus.ts` 中的 `NodeStatus` 工具负责把后端返回的离散状态值映射为统一的 UI 模型，内部维护三类常量表：颜色（`statusColor`）、图标（`statusIcon`）和优先级（`statusOrder`）。Kanban 视图（v2.10.7 引入）能自定义列、列顺序及排序键，正是依赖这层归一化结果。资料来源：[ui/src/features/dags/lib/nodeStatus.ts:1-90]()

```mermaid
flowchart LR
  Backend[/后端 Status 枚举/] --> Norm[NodeStatus 归一化]
  Norm --> Color[statusColor]
  Norm --> Icon[statusIcon]
  Norm --> Order[statusOrder]
  Color --> UI[Kanban / RunPage]
  Icon --> UI
  Order --> KanbanCol[Kanban 列排序]
```

### 工作流与差异

`workflow.ts` 输出 React Flow 渲染所需的节点 / 边集合，同时计算每个节点的 `upstreamCount`、`downstreamCount` 等元信息。`diff.ts` 则负责对 DAG YAML 文本做语义化对比，输出新增、删除、修改的 step 列表，使运行页中的“重载”按钮能给出可视化提示。资料来源：[ui/src/features/dags/lib/workflow.ts:30-110]()、[ui/src/features/dags/lib/diff.ts:20-80]()

### 通用工具函数

`utils.ts` 汇聚通用格式化逻辑（时间戳、本地化、数字千分位）和 ID 哈希（截取前 8 位用于日志关联），并提供 `mergeParams` 函数合并 root params（v2.10.1 引入）与 step 级参数。资料来源：[ui/src/features/dags/lib/utils.ts:1-60]()

## 与 Dagu 业务的衔接

`Lib 模块`不是孤立存在的，它向上衔接 `features/dags/components` 与 `features/dags/hooks` 两层，向下严格基于后端返回的 DAG JSON 模型工作。下表给出了与社区关注点直接相关的衔接场景。

| 业务能力 | 调用方 | 关键函数 |
| --- | --- | --- |
| 生命周期 handler 可视化 | `RunPage.handlerTable` | `getEventHandlers` |
| Kanban 视图列排序 | `KanbanBoard` | `nodeStatus` 中的 `statusOrder` |
| 重跑单个 step 或下游链 | `RunPage.actions` | `workflow` 返回的拓扑结果（参见 issue #2388） |
| 重新加载前提示差异 | `ReloadConfirmDialog` | `diff` 返回的 step 级差异 |

在功能演进方面，用户希望在 UI 中能像 issue #2388 描述的那样“一键重跑选中 step 及其所有下游依赖”，这一特性高度依赖 `workflow.ts` 中 `downstreamCount` 与子图抽取的实现。资料来源：[ui/src/features/dags/lib/workflow.ts:80-140]()

## 设计约束与已知风险

- **纯函数约束**：禁止在 `lib/` 内引入任何 `useEffect`、`fetch` 等副作用调用，便于单测和 SSR。
- **类型对后端的强依赖**：所有 `handler_on.*`、状态枚举均与 `internal/agent` 返回的协议绑定，后端协议变更需要同步更新此模块（参考 issue #2428 — `stdout.outputs` 未发布到 DAG run outputs 即源于该耦合）。
- **handler 输出未贯通**：虽然 `getEventHandlers` 已能解析 `handler_on.init`，但其 stdout 路径与 `outputsValue` 仍缺乏对应的 UI 组件承载，需要后续新增 `handlerTable` 专属组件。资料来源：[ui/src/features/dags/lib/getEventHandlers.ts:100-150]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：dagucloud/dagu

摘要：发现 26 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：feat: rerun a selected step and all downstream steps。

## 1. 安全/权限坑 · 来源证据：feat: rerun a selected step and all downstream steps

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: rerun a selected step and all downstream steps
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/dagucloud/dagu/issues/2388 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安装坑 · 依赖 Docker 环境

- 严重度：medium
- 证据强度：runtime_trace
- 发现：安装/运行入口包含 Docker 命令：docker run --rm -v ~/.dagu:/var/lib/dagu -p 8080:8080 ghcr.io/dagucloud/dagu:latest dagu start-all
- 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
- 复现命令：`docker run --rm -v ~/.dagu:/var/lib/dagu -p 8080:8080 ghcr.io/dagucloud/dagu:latest dagu start-all`
- 证据：identity.distribution | https://github.com/dagucloud/dagu | docker run --rm -v ~/.dagu:/var/lib/dagu -p 8080:8080 ghcr.io/dagucloud/dagu:latest dagu start-all

## 3. 安装坑 · 失败模式：installation: bug: `stdout.outputs` declared on a `handler_on` step is captured but never published to the...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: bug: `stdout.outputs` declared on a `handler_on` step is captured but never published to the DAG run outputs
- 对用户的影响：Developers may fail before the first successful local run: bug: `stdout.outputs` declared on a `handler_on` step is captured but never published to the DAG run outputs
- 证据：failure_mode_cluster:github_issue | https://github.com/dagucloud/dagu/issues/2428 | bug: `stdout.outputs` declared on a `handler_on` step is captured but never published to the DAG run outputs

## 4. 安装坑 · 失败模式：installation: bug: queued run that fails before startup is never dequeued and retries forever

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: bug: queued run that fails before startup is never dequeued and retries forever
- 对用户的影响：Developers may fail before the first successful local run: bug: queued run that fails before startup is never dequeued and retries forever
- 证据：failure_mode_cluster:github_issue | https://github.com/dagucloud/dagu/issues/2436 | bug: queued run that fails before startup is never dequeued and retries forever

## 5. 安装坑 · 失败模式：installation: helm-dagu-1.0.10

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: helm-dagu-1.0.10
- 对用户的影响：Upgrade or migration may change expected behavior: helm-dagu-1.0.10
- 证据：failure_mode_cluster:github_release | https://github.com/dagucloud/dagu/releases/tag/helm-dagu-1.0.10 | helm-dagu-1.0.10

## 6. 安装坑 · 失败模式：installation: helm-dagu-1.0.11

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: helm-dagu-1.0.11
- 对用户的影响：Upgrade or migration may change expected behavior: helm-dagu-1.0.11
- 证据：failure_mode_cluster:github_release | https://github.com/dagucloud/dagu/releases/tag/helm-dagu-1.0.11 | helm-dagu-1.0.11

## 7. 安装坑 · 失败模式：installation: question: `onInit` handler is recorded but never displayed — is that intended?

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: question: `onInit` handler is recorded but never displayed — is that intended?
- 对用户的影响：Developers may fail before the first successful local run: question: `onInit` handler is recorded but never displayed — is that intended?
- 证据：failure_mode_cluster:github_issue | https://github.com/dagucloud/dagu/issues/2429 | question: `onInit` handler is recorded but never displayed — is that intended?

## 8. 安装坑 · 失败模式：installation: v2.10.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v2.10.0
- 对用户的影响：Upgrade or migration may change expected behavior: v2.10.0
- 证据：failure_mode_cluster:github_release | https://github.com/dagucloud/dagu/releases/tag/v2.10.0 | v2.10.0

## 9. 安装坑 · 来源证据：bug: queued run that fails before startup is never dequeued and retries forever

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: queued run that fails before startup is never dequeued and retries forever
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/dagucloud/dagu/issues/2436 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 10. 安装坑 · 来源证据：question: `onInit` handler is recorded but never displayed — is that intended?

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：question: `onInit` handler is recorded but never displayed — is that intended?
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/dagucloud/dagu/issues/2429 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。

## 11. 配置坑 · 失败模式：configuration: v2.10.4

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v2.10.4
- 对用户的影响：Upgrade or migration may change expected behavior: v2.10.4
- 证据：failure_mode_cluster:github_release | https://github.com/dagucloud/dagu/releases/tag/v2.10.4 | v2.10.4

## 12. 配置坑 · 失败模式：configuration: v2.10.5

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v2.10.5
- 对用户的影响：Upgrade or migration may change expected behavior: v2.10.5
- 证据：failure_mode_cluster:github_release | https://github.com/dagucloud/dagu/releases/tag/v2.10.5 | v2.10.5

## 13. 配置坑 · 失败模式：configuration: v2.10.6

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v2.10.6
- 对用户的影响：Upgrade or migration may change expected behavior: v2.10.6
- 证据：failure_mode_cluster:github_release | https://github.com/dagucloud/dagu/releases/tag/v2.10.6 | v2.10.6

## 14. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/dagucloud/dagu | README/documentation is current enough for a first validation pass.

## 15. 运行坑 · 运行可能依赖外部服务

- 严重度：medium
- 证据强度：source_linked
- 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
- 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
- 证据：packet_text.keyword_scan | https://github.com/dagucloud/dagu | matched external service / cloud / webhook / database keyword

## 16. 维护坑 · 失败模式：migration: v2.9.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: v2.9.0
- 对用户的影响：Upgrade or migration may change expected behavior: v2.9.0
- 证据：failure_mode_cluster:github_release | https://github.com/dagucloud/dagu/releases/tag/v2.9.0 | v2.9.0

## 17. 维护坑 · 失败模式：migration: v2.9.1

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: v2.9.1
- 对用户的影响：Upgrade or migration may change expected behavior: v2.9.1
- 证据：failure_mode_cluster:github_release | https://github.com/dagucloud/dagu/releases/tag/v2.9.1 | v2.9.1

## 18. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/dagucloud/dagu | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/dagucloud/dagu | no_demo; severity=medium

## 20. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/dagucloud/dagu | no_demo; severity=medium

## 21. 安全/权限坑 · 来源证据：bug: `stdout.outputs` declared on a `handler_on` step is captured but never published to the DAG run outputs

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: `stdout.outputs` declared on a `handler_on` step is captured but never published to the DAG run outputs
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/dagucloud/dagu/issues/2428 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 22. 能力坑 · 失败模式：capability: feat: rerun a selected step and all downstream steps

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: feat: rerun a selected step and all downstream steps
- 对用户的影响：Developers may hit a documented source-backed failure mode: feat: rerun a selected step and all downstream steps
- 证据：failure_mode_cluster:github_issue | https://github.com/dagucloud/dagu/issues/2388 | feat: rerun a selected step and all downstream steps

## 23. 运行坑 · 失败模式：performance: v2.10.1

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: v2.10.1
- 对用户的影响：Upgrade or migration may change expected behavior: v2.10.1
- 证据：failure_mode_cluster:github_release | https://github.com/dagucloud/dagu/releases/tag/v2.10.1 | v2.10.1

## 24. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/dagucloud/dagu | issue_or_pr_quality=unknown

## 25. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/dagucloud/dagu | release_recency=unknown

## 26. 维护坑 · 失败模式：maintenance: v2.10.7

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v2.10.7
- 对用户的影响：Upgrade or migration may change expected behavior: v2.10.7
- 证据：failure_mode_cluster:github_release | https://github.com/dagucloud/dagu/releases/tag/v2.10.7 | v2.10.7

<!-- canonical_name: dagucloud/dagu; human_manual_source: deepwiki_human_wiki -->