Agent-almanac generate-workflow-diagram

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/zh-CN/skills/generate-workflow-diagram" ~/.claude/skills/pjt222-agent-almanac-generate-workflow-diagram-c7c37f && rm -rf "$T"

manifest: i18n/zh-CN/skills/generate-workflow-diagram/SKILL.md

source content

生成工作流图表

从 putior 工作流数据生成主题化的 Mermaid 流程图，并嵌入到文档中。

适用场景

注释源文件后准备生成可视图表
工作流变更后重新生成图表
为不同受众切换主题或输出格式
在 README、Quarto 或 R Markdown 文档中嵌入工作流图表

输入

必需：来自
```
put()
```
、
```
put_auto()
```
或
```
put_merge()
```
的工作流数据
可选：主题名称（默认：
```
"light"
```
；选项：light、dark、auto、minimal、github、viridis、magma、plasma、cividis）
可选：输出目标：控制台、文件路径、剪贴板或原始字符串
可选：交互功能：
```
show_source_info
```
、
```
enable_clicks
```

步骤

第 1 步：提取工作流数据

从三个来源之一获取工作流数据。

library(putior)

# From manual annotations
workflow <- put("./src/")

# From manual annotations, excluding specific files
workflow <- put("./src/", exclude = c("build-workflow\\.R$", "test_"))

# From auto-detection only
workflow <- put_auto("./src/")

# From merged (manual + auto)
workflow <- put_merge("./src/", merge_strategy = "supplement")

工作流数据框可能包含来自注释的

node_type

列。节点类型控制 Mermaid 形状：

`node_type`	Mermaid 形状	用途
`"input"`	Stadium `([...])`	数据源、配置文件
`"output"`	Subroutine `[[...]]`	生成的工件、报告
`"process"`	Rectangle `[...]`	处理步骤（默认）
`"decision"`	Diamond `{...}`	条件逻辑、分支
`"start"` / `"end"`	Stadium `([...])`	入口/终端节点

每个

node_type

还会收到相应的 CSS 类（如

class nodeId input;

）用于基于主题的样式。

预期结果： 包含至少一行的数据框，包含

id

、

label

，以及可选的

input

、

output

、

source_file

、

node_type

列。

失败处理： 如果数据框为空，表示未找到注释或模式。先运行

analyze-codebase-workflow

，或使用

put("./src/", validate = TRUE)

检查注释语法是否正确。

第 2 步：选择主题和选项

选择适合目标受众的主题。

# List all available themes
get_diagram_themes()

# Standard themes
# "light"   — Default, bright colors
# "dark"    — For dark mode environments
# "auto"    — GitHub-adaptive with solid colors
# "minimal" — Grayscale, print-friendly
# "github"  — Optimized for GitHub README files

# Colorblind-safe themes (viridis family)
# "viridis" — Purple→Blue→Green→Yellow, general accessibility
# "magma"   — Purple→Red→Yellow, high contrast for print
# "plasma"  — Purple→Pink→Orange→Yellow, presentations
# "cividis" — Blue→Gray→Yellow, maximum accessibility (no red-green)

其他参数：

```
direction
```
：图表流向——
```
"TD"
```
（自上而下，默认）、
```
"LR"
```
（从左到右）、
```
"RL"
```
、
```
"BT"
```
```
show_artifacts
```
：
```
TRUE
```
/
```
FALSE
```
——显示工件节点（文件、数据）；大型工作流可能会很嘈杂（如 16+ 个额外节点）
```
show_workflow_boundaries
```
：
```
TRUE
```
/
```
FALSE
```
——将每个源文件的节点包装在 Mermaid 子图中
```
source_info_style
```
：源文件信息在节点上的显示方式（如作为副标题）
```
node_labels
```
：节点标签文本的格式

预期结果： 主题名称已打印。根据上下文选择一个。

失败处理： 如果主题名称不被识别，

put_diagram()

回退到

"light"

。检查拼写。

第 3 步：使用

put_theme()

自定义调色板（可选）

如果 9 个内置主题不匹配你的项目调色板，使用

put_theme()

创建自定义主题。

# Create custom palette — unspecified types inherit from base theme
cyberpunk <- put_theme(
  base = "dark",
  input    = c(fill = "#1a1a2e", stroke = "#00ff88", color = "#00ff88"),
  process  = c(fill = "#16213e", stroke = "#44ddff", color = "#44ddff"),
  output   = c(fill = "#0f3460", stroke = "#ff3366", color = "#ff3366"),
  decision = c(fill = "#1a1a2e", stroke = "#ffaa33", color = "#ffaa33")
)

# Use the palette parameter (overrides theme when provided)
mermaid_content <- put_diagram(workflow, palette = cyberpunk, output = "raw")
writeLines(mermaid_content, "workflow.mmd")

put_theme()

接受

input

、

process

、

output

、

decision

、

artifact

、

start

和

end

节点类型。每个接受命名向量

c(fill = "#hex", stroke = "#hex", color = "#hex")

。未设置的类型从

base

主题继承。

预期结果： 带有自定义 classDef 行的 Mermaid 输出。来自

node_type

的节点形状保留；只有颜色改变。所有节点类型使用

stroke-width:2px

——当前不支持通过

put_theme()

覆盖。

失败处理： 如果调色板对象不是

putior_theme

类，

put_diagram()

会抛出描述性错误。确保传递

put_theme()

的返回值，而非原始列表。

备选方案——手动 classDef 替换： 对于超出

put_theme()

提供的细粒度控制（如每类型的线宽），使用基础主题生成后手动替换 classDef 行：

mermaid_content <- put_diagram(workflow, theme = "dark", output = "raw")
lines <- strsplit(mermaid_content, "\n")[[1]]
lines <- lines[!grepl("^\\s*classDef ", lines)]
custom_defs <- c("  classDef input fill:#1a1a2e,stroke:#00ff88,stroke-width:3px,color:#00ff88")
mermaid_content <- paste(c(lines, custom_defs), collapse = "\n")

第 4 步：生成 Mermaid 输出

以所需的输出模式生成图表。

# Print to console (default)
cat(put_diagram(workflow, theme = "github"))

# Save to file
writeLines(put_diagram(workflow, theme = "github"), "docs/workflow.md")

# Get raw string for embedding
mermaid_code <- put_diagram(workflow, output = "raw", theme = "github")

# With source file info (shows which file each node comes from)
cat(put_diagram(workflow, theme = "github", show_source_info = TRUE))

# With clickable nodes (for VS Code, RStudio, or file:// protocol)
cat(put_diagram(workflow,
  theme = "github",
  enable_clicks = TRUE,
  click_protocol = "vscode"  # or "rstudio", "file"
))

# Full-featured
cat(put_diagram(workflow,
  theme = "viridis",
  show_source_info = TRUE,
  enable_clicks = TRUE,
  click_protocol = "vscode"
))

预期结果： 以

flowchart TD

（或

LR

，取决于方向）开头的有效 Mermaid 代码。节点通过箭头连接显示数据流。

失败处理： 如果输出是没有节点的

flowchart TD

，则工作流数据框为空。如果连接缺失，检查跨节点的输出文件名是否与输入文件名匹配。

第 5 步：嵌入目标文档

将图表插入适当的文档格式。

GitHub README（```mermaid 代码围栏）：

## Workflow

```mermaid
flowchart TD
  A["Extract Data"] --> B["Transform"]
  B --> C["Load"]
```

Quarto 文档（通过 knit_child 的原生 mermaid 块）：

# Chunk 1: Generate code (visible, foldable)
workflow <- put("./src/")
mermaid_code <- put_diagram(workflow, output = "raw", theme = "github")

# Chunk 2: Output as native mermaid chunk (hidden)
#| output: asis
#| echo: false
mermaid_chunk <- paste0("```{mermaid}\n", mermaid_code, "\n```")
cat(knitr::knit_child(text = mermaid_chunk, quiet = TRUE))

R Markdown（使用 mermaid.js CDN 或 DiagrammeR）：

DiagrammeR::mermaid(put_diagram(workflow, output = "raw"))

预期结果： 图表在目标格式中正确渲染。GitHub 原生渲染 mermaid 代码围栏。

失败处理： 如果 GitHub 不渲染图表，确保代码围栏使用精确的

```mermaid

（无额外属性）。对于 Quarto，确保使用

knit_child()

方法，因为

{mermaid}

块不支持直接变量插值。

验证清单

```
put_diagram()
```
生成有效的 Mermaid 代码（以
```
flowchart
```
开头）
所有预期节点出现在图表中
连接节点之间存在数据流连接（箭头）
已应用选定的主题（检查输出中的 init 块是否有主题特定颜色）
图表在目标格式中正确渲染（GitHub、Quarto 等）

常见问题

空图表：通常意味着
```
put()
```
返回了空行。检查注释是否存在且语法正确
所有节点断开：输出文件名必须与跨节点的输入文件名精确匹配（包括扩展名），putior 才能绘制连接。
```
data.csv
```
和
```
Data.csv
```
是不同的
GitHub 上主题不可见：GitHub 的 mermaid 渲染器对主题支持有限。
```
"github"
```
主题专为 GitHub 渲染设计。
```
%%{init:...}%%
```
主题块可能被某些渲染器忽略
Quarto mermaid 变量插值：Quarto 的
```
{mermaid}
```
块不直接支持 R 变量。使用第 5 步中描述的
```
knit_child()
```
技术
可点击节点不工作：点击指令需要支持 Mermaid 交互事件的渲染器。GitHub 的静态渲染器不支持点击。使用本地 Mermaid 渲染器或 putior Shiny 沙盒

自引用的元流水线文件：扫描包含生成图表的构建脚本的目录会导致重复的子图 ID 和 Mermaid 错误。使用

exclude

参数在扫描时跳过它们：

workflow <- put("./src/", exclude = c("build-workflow\\.R$", "build-workflow\\.js$"))

show_artifacts = TRUE
太嘈杂：大型项目可能生成许多工件节点（10-20+），使图表混乱。使用
```
show_artifacts = FALSE
```
并依靠
```
node_type
```
注释明确标记关键输入/输出