Agent-almanac render-icon-pipeline

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/render-icon-pipeline" ~/.claude/skills/pjt222-agent-almanac-render-icon-pipeline-66d920 && rm -rf "$T"

manifest: i18n/zh-CN/skills/render-icon-pipeline/SKILL.md

source content

渲染图标流水线

端到端运行 viz 流水线，从现有符号渲染图标。涵盖调色板生成、数据构建、清单创建以及技能、代理和团队的图标渲染。

标准入口点：从项目根目录运行

bash viz/build.sh [flags]

，或从

viz/

运行

bash build.sh [flags]

。该脚本负责平台检测（WSL、Docker、原生）、R 二进制选择以及步骤顺序。切勿直接调用

Rscript

运行构建脚本 —— 该路径仅用于 MCP 服务器配置。

适用场景

创建或修改符号函数后
将新的技能、代理或团队添加到注册表后
图标需要为新的或更新的调色板重新渲染时
需要完整的流水线重建（例如基础设施变更后）
首次搭建 viz 环境时

输入

可选：实体类型 —
```
skill
```
、
```
agent
```
、
```
team
```
或
```
all
```
（默认：
```
all
```
）
可选：调色板 — 具体调色板名称或
```
all
```
（默认：
```
all
```
）
可选：领域过滤 — 用于技能图标的特定领域（例如
```
git
```
、
```
design
```
）
可选：渲染模式 —
```
full
```
、
```
incremental
```
或
```
dry-run
```
（默认：
```
incremental
```
）

流程

步骤 1：验证前置条件

确保环境已准备好进行渲染。

确认

viz/build.sh

存在：

ls -la viz/build.sh

验证 Node.js 可用：
```
node --version
```

检查

viz/config.yml

是否存在（平台特定的 R 路径配置）：

ls viz/config.yml

build.sh

会自动处理 R 二进制解析 —— 无需手动验证 R 路径。在 WSL 上使用

/usr/local/bin/Rscript

（WSL 原生 R），在 Docker 上使用容器 R，在原生 Linux/macOS 上使用 PATH 中的

Rscript

。

预期结果：

build.sh

、Node.js 和

config.yml

均存在。

失败处理： 如果

config.yml

缺失，流水线将回退到系统默认值。如果 Node.js 缺失，通过 nvm 安装。

步骤 2：运行流水线

build.sh

按顺序执行 5 个步骤：

生成调色板颜色（R） →
```
palette-colors.json
```
+
```
colors-generated.js
```
构建数据（Node） →
```
skills.json
```

构建清单（Node） →

icon-manifest.json

、

agent-icon-manifest.json

、

team-icon-manifest.json

渲染图标（R） →
```
icons/
```
和
```
icons-hd/
```
WebP 文件
生成终端符号（Node） →
```
cli/lib/glyph-data.json
```

完整流水线（所有类型、所有调色板、标准 + 高清）：

bash viz/build.sh

增量渲染（跳过磁盘上已存在的图标）：

bash viz/build.sh --skip-existing

单一领域（仅技能）：

bash viz/build.sh --only design

单一实体类型：

bash viz/build.sh --type skill
bash viz/build.sh --type agent
bash viz/build.sh --type team

试运行（预览但不渲染）：

bash viz/build.sh --dry-run

仅标准尺寸（跳过高清）：

bash viz/build.sh --no-hd

build.sh

之后的所有标志都会透传给

build-all-icons.R

。

预期结果： 图标渲染到

viz/public/icons/<palette>/

和

viz/public/icons-hd/<palette>/

。

失败处理：

NTFS 上的 renv 卡住：viz 的
```
.Rprofile
```
绕过
```
renv/activate.R
```
并直接设置
```
.libPaths()
```
。确保从
```
viz/
```
运行（build.sh 通过
```
cd "$(dirname "$0")"
```
自动完成此操作）

缺失 R 包：从

build.sh

选择的 R 环境中运行

Rscript -e "install.packages(c('ggplot2', 'ggforce', 'ggfx', 'ragg', 'magick', 'future', 'furrr', 'digest'))"

No glyph mapped：实体需要符号函数 —— 在渲染前使用
```
create-glyph
```
技能

步骤 3：验证输出

确认渲染成功完成。

检查文件数量是否符合预期：

find viz/public/icons/cyberpunk -name "*.webp" | wc -l
find viz/public/icons-hd/cyberpunk -name "*.webp" | wc -l

检查文件大小是否合理（每个图标 2-80 KB）
运行
```
audit-icon-pipeline
```
技能进行完整检查

预期结果： 文件数量与清单条目数匹配。文件大小在预期范围内。

失败处理： 如果数量不匹配，某些符号可能在渲染过程中出错。检查构建日志中的

[ERROR]

行。

CLI 标志参考

所有标志都会通过

build.sh

透传给

build-all-icons.R

：

Flag	Default	说明
`--type <types>`	`all`	逗号分隔：skill, agent, team
`--palette <name>`	`all`	单个调色板或 `all` （9 个调色板）
`--only <filter>`	无	领域（技能）或实体 ID（代理/团队）
`--skip-existing`	关闭	跳过已有 WebP 文件的图标
`--dry-run`	关闭	列出将要生成的内容
`--size <n>`	`512`	输出尺寸（像素）
`--glow-sigma <n>`	`4`	发光模糊半径
`--workers <n>`	自动	并行工作进程数（detectCores()-1）
`--no-cache`	关闭	忽略内容哈希缓存
`--hd`	开启	启用高清变体（1024px）
`--no-hd`	关闭	跳过高清变体
`--strict`	关闭	遇到首个子脚本失败时退出

build.sh 内部工作原理

仅供参考 —— 切勿手动运行这些步骤：

cd viz/
# 1. Platform detection: sets R_CONFIG_ACTIVE (wsl, docker, or unset)
# 2. R binary selection: WSL → /usr/local/bin/Rscript, Docker → same, native → Rscript
# 3. $RSCRIPT generate-palette-colors.R
# 4. node build-data.js
# 5. node build-icon-manifest.js --type all
# 6. $RSCRIPT build-all-icons.R "$@"  (flags passed through)
# 7. node build-terminal-glyphs.js

Docker 替代方案

流水线也可以在 Docker 中运行：

cd viz
docker compose up --build

这将在隔离的 Linux 环境中运行完整的流水线，并在 8080 端口提供结果。

验证清单

已运行
```
bash viz/build.sh
```
（而非裸
```
Rscript
```
）
已生成调色板颜色（JSON + JS）
已从注册表构建数据文件
已从数据生成清单
已为目标类型和调色板渲染图标
文件数量符合预期
文件大小在预期范围内（2-80 KB）

常见陷阱

直接调用 Rscript：切勿手动运行
```
Rscript build-icons.R
```
或
```
Rscript generate-palette-colors.R
```
。始终使用
```
bash build.sh [flags]
```
。直接的 Rscript 调用会绕过平台检测，并可能使用错误的 R 二进制（通过
```
~/bin/Rscript
```
包装器使用 Windows R，而不是
```
/usr/local/bin/Rscript
```
下的 WSL 原生 R）。注意：CLAUDE.md 和指南中的 Windows R 路径仅用于 MCP 服务器配置，不适用于构建脚本。
错误的工作目录：
```
build.sh
```
会自动切换到自己的目录（
```
cd "$(dirname "$0")"
```
），因此可以从任何位置调用：从项目根目录运行
```
bash viz/build.sh
```
也能正确工作。
清单过时：
```
build.sh
```
按顺序运行步骤 1-5，因此清单在渲染前始终会重新生成。如果只需要清单而不渲染，使用
```
node viz/build-data.js && node viz/build-icon-manifest.js
```
（Node 步骤不需要 R）。
renv 未激活：
```
.Rprofile
```
变通方案需要从
```
viz/
```
运行 ——
```
build.sh
```
会处理这一点。使用
```
--vanilla
```
标志或从其他目录运行 R 会跳过它。
Windows 上的并行处理：Windows 不支持基于 fork 的并行 —— 流水线通过
```
config.yml
```
自动选择
```
multisession
```
。