1. 项目概述：一个技能图谱的诞生
最近在整理自己的技术栈和项目经验时，我一直在思考一个问题：如何能系统性地、可视化地展示一个开发者（或者说任何一个专业人士）的综合能力？简历太单薄，个人网站又太静态。直到我偶然在 GitHub 上看到了hicoldcat/skills这个项目，它提供了一个非常巧妙的解决方案——一个基于 GitHub Actions 和 SVG 动态生成的个人技能图谱。
这个项目本质上是一个自动化工具链。它允许你将你的技能数据（比如编程语言、框架、工具、软技能等）以结构化的方式（例如一个 YAML 或 JSON 文件）存储在你的代码仓库里。然后，通过配置好的 GitHub Actions 工作流，定期（比如每天）自动运行一个生成脚本。这个脚本会读取你的技能数据，结合一些预设的模板和样式，动态生成一张精美的、可定制的 SVG 格式的技能图谱，并自动提交更新到你的仓库中。最终，你可以将这张实时更新的 SVG 图片嵌入到你的 GitHub Profile README、个人博客或者在线简历中，让访客一目了然地看到你的能力画像。
它解决的核心痛点在于“动态”和“维护成本”。静态的技能列表一旦写好就很容易过时，手动更新又麻烦。而hicoldcat/skills通过自动化将维护成本降到最低，你只需要维护源头数据文件，图表就会自动保持最新。这对于持续学习的开发者来说，是一个非常实用的“数字名片”增强工具。接下来，我将详细拆解这个项目的设计思路、实现细节，并分享如何从零开始配置属于你自己的动态技能图谱。
2. 核心设计思路与架构解析
2.1 为什么选择 SVG 与 GitHub Actions 的组合？
在技术选型上，hicoldcat/skills做出了两个非常关键且合理的选择：使用 SVG 作为输出格式，以及使用 GitHub Actions 作为自动化引擎。这背后有深刻的考量。
首先，SVG（可缩放矢量图形）是展示这类信息图的绝佳载体。与 PNG、JPG 等位图格式不同，SVG 是基于 XML 的矢量格式。这意味着无论你如何放大，图像都不会失真，始终保持清晰。这对于需要嵌入在不同尺寸页面（如手机、桌面）的图表至关重要。更重要的是，SVG 是纯文本描述的，可以被 Git 版本管理，可以很方便地用 CSS 进行样式定制，甚至可以通过 JavaScript 进行交互（虽然本项目主要生成静态 SVG）。生成 SVG 的库在各大编程语言中都很成熟，例如 Python 的svgwrite、cairoSVG，或者 Node.js 的d3.js。项目选择 SVG，保证了输出结果的高质量、可定制和易集成。
其次，GitHub Actions是驱动整个项目自动化的心脏。GitHub Actions 提供了免费、稳定且与 GitHub 仓库深度集成的自动化环境。它的核心价值在于“事件驱动”。我们可以配置一个工作流，在特定事件发生时触发，例如schedule（定时任务，如每天凌晨2点）、push（当技能数据文件被推送时）或者workflow_dispatch（手动触发）。一旦触发，GitHub 会启动一个虚拟运行器（Runner），在其中按照我们定义的步骤执行任务，比如安装 Python、拉取代码、运行生成脚本、将生成的 SVG 提交回仓库。这一切都是免费的（在额度内），并且无需自己维护服务器。对于个人项目来说，没有比这更经济、省心的方案了。
注意：GitHub Actions 的免费额度对于个人项目完全足够。但需要注意，定时任务（schedule）的触发并非绝对精确，可能会有几分钟的延迟。此外，如果仓库是私有的，Actions 分钟数消耗会更快，公开仓库则基本无限制。
2.2 数据与表现分离的架构哲学
项目的架构清晰体现了“数据与表现分离”的良好设计原则。整个流程可以抽象为三个核心部分：
数据层：通常是一个配置文件，如
skills.yaml或skills.json。这里以结构化的方式定义了你所有的技能项。每个技能项可能包含：技能名称、熟练等级（如：初学者、进阶、熟练、专家）、类别（如：前端、后端、DevOps）、学习开始时间、相关项目链接等。这是整个系统的“单一数据源”。逻辑层：这是核心的生成脚本，通常是一个 Python 或 JavaScript 脚本。它的职责是：
- 读取并解析数据层的配置文件。
- 根据业务逻辑处理数据（例如，计算某项技能的“经验时长”）。
- 调用图形库（如
svgwrite），将处理后的数据映射为视觉元素（矩形、圆形、文本、连线等），并按照一定的布局算法（如力导向图、网格布局、时间线）进行排列，最终组合成一个完整的 SVG DOM 树。 - 将 SVG 树写入到指定的输出文件，例如
skills.svg。
自动化与交付层：即 GitHub Actions 工作流文件（
.github/workflows/update-skills.yml）。它定义了何时以及如何运行逻辑层的脚本，并处理产出物。关键步骤包括：检出代码、安装依赖、运行生成脚本、检查文件是否有变化、如果有变化则配置 Git 用户并提交推送。
这种分离带来了巨大的灵活性。如果你想调整技能项的视觉样式（比如颜色、形状），你只需要修改逻辑层中绘图部分的代码，而无需触碰数据。如果你想增加新的技能属性（比如“自信程度”），你只需要在数据层和逻辑层的解析部分做相应扩展即可。这种低耦合的设计使得项目易于维护和定制。
3. 从零开始构建你的技能图谱
3.1 准备工作与仓库初始化
首先，你需要在 GitHub 上创建一个新的公共仓库，例如命名为my-skills-chart。公开仓库可以确保 GitHub Actions 运行无额度顾虑。初始化时可以选择添加一个README.md和.gitignore文件（选择 Python 模板）。
克隆仓库到本地后，我们开始创建项目的基本结构。一个典型的目录结构如下：
my-skills-chart/ ├── .github/ │ └── workflows/ │ └── update-skills.yml # GitHub Actions 工作流定义 ├── scripts/ │ ├── generate_skills.py # 核心生成脚本 │ └── requirements.txt # Python 依赖列表 ├── data/ │ └── skills.yaml # 技能数据源 ├── output/ │ └── skills.svg # 生成的 SVG 文件（由脚本创建） └── README.md接下来，我们创建最核心的数据文件data/skills.yaml。YAML 格式的可读性非常好，适合手动编辑。下面是一个结构示例：
categories: - name: "编程语言" skills: - name: "Python" level: 5 since: "2018-03" description: "主要用于自动化脚本、数据分析和后端开发。熟悉 FastAPI、Django。" color: "#3572A5" - name: "JavaScript" level: 4 since: "2017-09" description: "ES6+， Vue.js/React 生态。" color: "#F1E05A" - name: "云与运维" skills: - name: "Docker" level: 4 since: "2019-11" - name: "GitHub Actions" level: 5 since: "2020-05"在这个结构中，level可以用 1-5 的数字表示熟练度，since表示开始接触的时间，用于后续可能计算“经验时长”。color可以指定该技能项在图表中的显示颜色，如果不指定，脚本可以赋予默认的类别颜色。
3.2 核心生成脚本的编写要点
生成脚本是项目的灵魂。这里以 Python 为例，使用svgwrite库。首先，在scripts/requirements.txt中写明依赖：
svgwrite==1.4.3 pyyaml==6.0脚本scripts/generate_skills.py的主要逻辑如下：
- 加载与解析数据：使用
yaml.safe_load()读取skills.yaml。 - 设计布局：这是最具挑战性的部分。一个简单有效的布局是“分类网格”。我们可以为每个类别分配一个区域，然后在该区域内，将技能项排列成网格。需要计算每个技能项的位置（x, y）、宽度和高度。
- 假设每个技能项用一个圆角矩形表示。
- 矩形宽度可以根据技能名称的长度动态计算，或者固定一个最大值。
- 矩形的高度可以固定。
- 矩形之间的间距（水平和垂直）需要预留。
- 需要遍历所有类别和技能，累加计算整个画布所需的总宽度和总高度。
- 绘制 SVG 元素：
- 创建
svgwrite.Drawing对象，指定画布大小。 - 遍历数据，为每个技能项创建
<rect>（圆角矩形）和<text>（技能名）。 - 矩形的填充色可以使用技能项自定义的
color，或者根据level映射到一个渐变色系（如从浅蓝到深蓝）。 - 可以在矩形内部或上方添加一个表示熟练度的小指示条，比如在矩形底部再画一个不同颜色、宽度与
level成正比的矩形。 - 为每个类别添加一个背景色块和类别标题文本。
- 创建
- 保存输出：将生成的 SVG 保存到
output/skills.svg。
一个关键的细节是确保生成结果是确定性的。脚本不应该依赖运行环境的时间、随机数等，否则每次 Actions 运行生成的 SVG 在 Git 看来都可能“有变化”，导致不必要的提交。所有颜色、位置都应完全由输入数据计算得出。
实操心得：在绘制文本时，务必注意文本的锚点（
text-anchor）和基线（dominant-baseline）属性，这对于文本在形状内的居中显示至关重要。一个常见的技巧是，将文本元素包裹在<text>中，并设置text-anchor="middle"和dominant-baseline="central"，然后将其精确放置在形状的中心坐标上。
3.3 配置 GitHub Actions 自动化工作流
自动化是让这个项目“活”起来的关键。在.github/workflows/update-skills.yml中定义工作流。
name: Update Skills Chart on: schedule: # 每天 UTC 时间 18:00 运行（即北京时间凌晨2点） - cron: '0 18 * * *' push: # 当数据文件或脚本被修改时也触发 paths: - 'data/skills.yaml' - 'scripts/**' workflow_dispatch: # 允许手动触发 jobs: generate: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v4 with: persist-credentials: false # 重要！使用后续的 token 推送 - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.10' - name: Install dependencies run: | cd scripts pip install -r requirements.txt - name: Generate SVG run: | cd scripts python generate_skills.py - name: Check for changes id: git-check run: | git diff --quiet output/skills.svg || echo "changed=true" >> $GITHUB_OUTPUT - name: Commit and push if changed if: steps.git-check.outputs.changed == 'true' run: | git config --local user.email "action@github.com" git config --local user.name "GitHub Action" git add output/skills.svg git commit -m "chore: auto-update skills chart [skip ci]" git push env: # 使用 GitHub Token 进行推送 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}这个工作流做了以下几件事：
- 触发条件：每天定时触发；当数据或脚本被推送时触发；支持手动在 GitHub 网页点击触发。
- 环境准备：检出代码，安装指定版本的 Python。
- 执行生成：安装 Python 依赖，运行我们的生成脚本。
- 智能提交：这是一个关键优化。使用
git diff --quiet检查生成的skills.svg文件是否与上一次提交的版本有差异。只有文件内容真正发生变化时，才执行提交和推送操作。这避免了生成结果未变时产生大量无意义的提交记录。[skip ci]标记可以防止本次推送再次触发 Actions（如果配置了其他由 push 触发的工作流），避免循环触发。
注意事项：
secrets.GITHUB_TOKEN是 GitHub 自动为每个仓库工作流提供的令牌，拥有对该仓库的读写权限，非常适合用于此类自动提交。无需额外配置。但注意persist-credentials: false的设置，这是为了确保我们使用后续显式配置的 Token 进行推送，避免冲突。
4. 高级定制与可视化方案探讨
4.1 丰富数据模型与视觉编码
基础的技能列表展示只是开始。我们可以通过丰富数据模型和视觉编码来传递更多信息。
- 经验时长：利用
since字段，可以计算从开始日期到当前日期的时长。在视觉上，可以用矩形的“长度”或一个额外的“时间条”来表示。例如，一个从2018年开始的技能，其时间条会比2022年开始的技能长。 - 热度/使用频率：可以增加一个
frequency字段（如：日常、每周、每月、偶尔）。用元素的饱和度或亮度来表示，高频使用的技能颜色鲜艳，低频使用的技能颜色灰暗。 - 技能关联：在数据中定义技能之间的关系（如“Python” 和 “Django” 是“主要使用”关系）。在图表中，可以用曲线或直线连接相关的技能项。这能形成一张“技能知识图谱”，直观展示你的技术生态。
- 进度与目标：除了当前水平（
current_level），还可以设定一个目标水平（goal_level）。在视觉上，可以用一个填充的圆环图（类似仪表盘）来展示当前进度，非常具有激励性。
实现这些高级特性，需要在数据文件中增加相应字段，并在生成脚本中扩展绘图逻辑。例如，绘制关联线时，需要计算两个技能项矩形边缘的坐标，然后绘制一条贝塞尔曲线。
4.2 探索不同的布局算法
网格布局简单直观，但可能缺乏美感或不适合技能项数量差异很大的情况。我们可以探索其他布局：
- 力导向图：这是展示关联网络的经典布局。每个技能项是一个节点，节点之间存在斥力（防止重叠），如果定义了关联关系，则存在引力。经过多次迭代模拟后，节点会达到一个平衡状态，形成自然、有机的分布。D3.js 在这方面非常强大，但用 Python 的
networkx库配合svgwrite也能实现基础版本。 - 圆形布局：将所有技能项排列在一个或多个同心圆上。类别可以占据不同的扇形区域。这种布局紧凑且美观，适合技能项数量适中的情况。
- 时间线布局：如果强调技能的“时间”属性，可以采用水平或垂直时间线。每个技能项根据其
since日期放置在时间线的对应位置，其宽度或高度可以表示熟练度或使用频率。这能清晰展示你技术栈的演进历程。
选择布局时，需要考虑技能项的数量、类别数量以及你想要强调的核心信息（是分类、关联还是演进）。
4.3 样式主题与交互性
静态 SVG 可以通过 CSS 进行样式化。你可以在 SVG 文件内部定义<style>标签，或者将 SVG 嵌入 HTML 后使用外部 CSS 控制。这意味着你可以轻松切换“深色模式”和“浅色模式”，或者根据季节、心情更换主题色系。
虽然 GitHub README 中嵌入的 SVG 不支持脚本（出于安全考虑），但如果你将 SVG 部署到个人网站，可以为其添加简单的交互性。例如，使用<title>元素为每个技能矩形添加悬停提示（tooltip），当鼠标悬停时显示技能的详细描述。更进一步的，可以使用 JavaScript 为 SVG 元素绑定点击事件，点击后跳转到该技能的详细说明页面或相关项目。
5. 集成展示与常见问题排查
5.1 将图谱嵌入你的数字名片
生成skills.svg后，最关键的一步是把它展示出来。最流行的位置是GitHub Profile README。
- 创建一个与你 GitHub 用户名同名的公共仓库（如
github.com/hicoldcat/hicoldcat）。 - 在该仓库的根目录下，编辑
README.md文件。 - 使用 Markdown 的图片语法，并指向你技能图谱仓库中 SVG 文件的原始链接。
## 🛠️ 我的技能图谱 使用raw.githubusercontent.com的链接至关重要，这能确保访问的是 SVG 源文件，而不是 GitHub 的预览页面。这样，每次 Actions 自动更新skills.svg后，你的 Profile 页面也会同步显示最新的图表。
此外，你还可以将 SVG 嵌入到你的个人博客（如 Hugo、Hexo、WordPress）、在线简历（如 LinkedIn 的 Featured 部分，需注意平台是否支持 SVG）或者 Notion 页面中。
5.2 常见问题与调试技巧
在搭建和运行过程中，你可能会遇到一些典型问题：
问题1：GitHub Actions 运行失败，提示“ModuleNotFoundError”
- 排查：这通常是依赖安装问题。确保
requirements.txt文件位于scripts/目录下，并且工作流中的pip install命令正确指向了该目录。可以在工作流中添加一个pwd和ls步骤来确认当前工作目录和文件。 - 解决：检查
requirements.txt中的包名和版本是否正确。可以在本地虚拟环境中测试pip install -r requirements.txt是否成功。
问题2：SVG 图片生成成功，但布局混乱，元素重叠或跑出画布。
- 排查：这几乎总是布局计算逻辑有误。首先，打印出计算出的每个技能项的位置坐标和画布总宽高，检查是否有负数或异常大的值。
- 解决：仔细检查布局算法。确保在计算每个技能项位置时，正确累加了前一项的宽度和间距。画布大小（
drawing的size参数）必须大于或等于所有元素占据的实际空间。可以给画布设置一个临时背景色，方便看清边界。
问题3：Actions 每次运行都产生提交，即使技能数据没变。
- 排查：这可能是生成脚本中包含了非确定性的输出，例如使用了当前时间、随机数，或者文件写入模式导致时间戳变化。
- 解决：确保脚本是纯函数式的，输出只依赖于输入数据。检查
git diff命令是否正常工作。可以在工作流中增加一个步骤，在生成前后分别输出文件的md5sum进行对比。
问题4：图片在 GitHub README 中显示为损坏的图标或无法加载。
- 排查：首先，直接浏览器访问 raw SVG 链接，看是否能正常显示。如果浏览器显示正常，但 README 不显示，可能是缓存问题。如果浏览器也报错，说明 SVG 文件本身可能格式有误。
- 解决：使用在线的 SVG 验证器检查 SVG 文件格式。确保 SVG 文件的 XML 声明和根标签正确。另外，GitHub 和某些平台对 SVG 内的外部资源（如
xlink:href引用）支持有限，尽量使用内联样式。
问题5：如何更新技能数据？
- 流程：非常简单。只需本地编辑
data/skills.yaml文件，修改、添加或删除技能项。然后提交并推送到 GitHub 仓库。push事件会触发 Actions 工作流，自动生成新的 SVG 并提交。整个过程无需手动运行任何生成命令。
这个项目的美妙之处在于，一旦搭建完成，维护就变成了简单的 YAML 文件编辑。它不仅仅是一个图表生成工具，更是一个促使你定期回顾和梳理自身技能成长的系统。看着图谱随着时间推移而不断丰富和演变，本身就是一种巨大的成就感。
