---

name: render-icon-pipeline locale: wenyan-lite source_locale: en source_commit: 82c77053 fence_basis_commit: 82c77053 translator: "Julius Brussee homage — caveman" translation_date: "2026-04-26" description: > Run the viz pipeline to render icons from existing glyphs. Entry point for the viz subproject covering palette generation, data building, manifest creation, and icon rendering for skills, agents, and teams. Always use build.sh as the pipeline entry point — never call Rscript directly. license: MIT allowed-tools: Read Bash Grep Glob metadata: author: Philipp Thoss version: "1.1" domain: visualization complexity: basic language: multi tags: visualization, rendering, pipeline, icons, glyphs, build

渲染圖示管線

端對端跑 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
   

2. 驗 Node.js 可用：

   node --version
   

3. 檢 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 安裝。

步驟二：跑管線

build.sh 按序執五步：

1. 生調色板顏色（R）→ palette-colors.json + colors-generated.js
2. 建資料（Node）→ skills.json
3. 建清單（Node）→ icon-manifest.json、agent-icon-manifest.json、team-icon-manifest.json
4. 渲染圖示（R）→ icons/ 與 icons-hd/ WebP 文件
5. 生終端字符（Node）→ cli/lib/glyph-data.json

完整管線（所有類型、所有調色板、標準與 HD）：

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

僅標準大小（略 HD）：

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'))"
• 無字符映射：實體需字符函數——渲染前用 create-glyph 技能

步驟三：驗輸出

確認渲染成功完成。

1. 檢查文件數合預期：

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

2. 檢查文件大小合理（每圖示 2-80 KB）
3. 跑 audit-icon-pipeline 技能作完整檢

預期： 文件數合清單條目數。文件大小於預期範圍。

失敗時： 若數不符，部分字符渲染時恐錯。檢構建日誌之 [ERROR] 行。

CLI 旗標參考

所有旗標皆透傳 build.sh 至 build-all-icons.R：

旗標	預設	描述
--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	開	啟用 HD 變體（1024px）
--no-hd	關	略 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 至自身目錄（cd "$(dirname "$0")"），故可自任處呼叫：自項目根之 bash viz/build.sh 正常運作
• 陳舊清單：build.sh 按序跑步驟一至五，故清單於渲染前必重建。若僅需清單不渲，用 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

相關技能

• audit-icon-pipeline — 渲染前察缺字符與圖示
• create-glyph — 為缺圖示之實體建新字符函數
• enhance-glyph — 重渲前改善既有字符