做了这么些年技术侧的事我一直有个挺要命的习惯资料存了一堆技能树画了一堆真到要用的时候反而得翻半天。GitHub星标几百个开源仓库真正沉淀下来的却没多少。后来我实在忍不了决定做个私人的“skills”项目把所有会用、想学和正在学的技能全部结构化、地图化地管起来。这个项目做到了三件事一是让我在两分钟内看清自己的技术栈全貌哪些能打、哪些刚入门二是沉淀了一套可以随时更新的“技能档案”不再依赖脑子记三是把学习路径拆成了有进度、有依据的节点每一步的投入和产出都看得见。整个过程踩了不少坑也总结了一些可复用的做法。这篇博文就把完整的拆分思路、数据结构设计和落地过程都摊开聊一聊适合那些想把自己“知识资产”真正管理起来的朋友参考。1. 项目整体设计与思路拆解做“skills”项目之前我首先搞清楚了一个问题我要管理的是什么是单纯罗列技术的Excel表还是动态追踪能力的成长体系如果只是列个清单那还不如一条便签纸。所以我从一开始就决定整个项目要有三层结构技能分类、技能详情、成长状态。1.1 从“技术清单”升级为“技能地图”很多人喜欢把技能写成一长条列表比如“Python、React、Docker、K8s、爬虫、数据分析……”。这种列表最大的问题在于没有层级关系也看不出能力之间的依赖。你写了Python和爬虫但这两者之间是什么关系前端会React后端会Flask可它们组合起来能做什么列表回答不了。我设计的第一层是分类域。把所有技能按照用途分成几个主域前端、后端、工程化、数据、软技能甚至包括领域知识。每个主域下面再拆成具体的技能点和子技能点。这样在查看时是树状结构而不是一张大饼任何一项技能都能找到它的归属位置从整体到细节一目了然。这套结构也不复杂本质上就是构建一棵“技能树”。举个例子后端域下面可以挂“Java”“Go”“数据库设计”这类节点而“数据库设计”又能继续往下细化成“索引优化”“分库分表”“慢查询排查”。前两层是宏观分类越往下越贴近具体实操恰好对应“知道什么”“用过什么”“精通什么”的不同层次。我还在每个技能节点上添加了归属标签比如“当前主力”“正在补充”“准备了解”方便后续做优先级排序。标签比单一等级更灵活可以组合查询比如“主力技能后端数据库”筛出来就是当前最值得投入时间去复盘和深入的部分。1.2 信息架构选型Markdown存储、结构化展示确定好结构之后接下来就是选存储方案。一开始我考虑过用数据库甚至想做一个完整的管理后台后来发现完全没必要。个人技能管理场景的特点是数据量不大、字段不复杂、需要频繁编辑。用数据库管理和后台表单反而会增加很多维护成本。我最终选了Markdown 前端渲染的方案。每个技能写成一个MD文件文件名就是这把技能的ID文件内部用YAML Front Matter记录元信息正文内容则用Markdown记录学习笔记、进度和踩坑经验。渲染端用Vite Vue 3搭了个轻量站点读取这些MD文件渲染成结构化的技能地图。这个方案最大的好处是低摩擦。记录经验这个动作本身要足够轻才不会变成负担。打开编辑器新建一个文件花一分钟写下今天学会了什么顺手更新进度百分比这就是一次完整记录。如果每次记录都要打开后台、填表单、点保存我保证用不了一个月你就会放弃。1.3 数据模型的迭代过程最开始我设计的数据结构其实繁琐得多每个技能下面包含很多冗余字段比如预期时间、资源链接、评审结论等。用了一段时间之后发现大部分字段根本不会被填也容易因为维护成本高而瘫痪。后来我把字段砍到了最低限度只保留几个核心维度技能名称与唯一ID所属分类和标签掌握程度百分比或等级最近更新时间相关链接与依赖技能这样设计的好处是把“记录”这个动作简化到极致。掌握程度和更新时间是靠数据说话的硬指标标签和分类是外部属性剩下的内容随心写。复杂想法可以写长笔记简单补充就一两句话系统不会因为信息过载而失真。2. 核心细节解析与实操要点结构设计完最核心的环节就是怎么让这套系统真正“运转”起来。运转包括两个层面一是内容层面的记录规则二是数据层面的组织方式。很多人的技能管理项目最后烂尾问题就出在这两个层面的细节没想清楚。2.1 技能节点的粒度控制这是整个项目里最关键、也最容易出错的地方。如果技能粒度太粗比如“后端开发”作为一个技能点那这条数据基本等于没记录因为它没法指导你下一步学什么。如果粒度太细把“容器网络策略配置”这种知识点也单独列一个节点维护成本又会暴涨时间一长必然放弃。我摸索出的经验是以“能否在一到两周内产生可验证的实践成果”为粒度标准。比如“Docker”粒度偏粗但“Docker常用命令与Dockerfile编写”“Docker Compose部署多容器应用”“镜像构建优化”这三个细分兴趣点就刚刚好。每个点都对应一个具体场景能通过一个小项目或需求验证掌握程度。实操时还需要注意一点粒度规则要保持一致。不要今天写一个很细的节点明天又写一个大而全的节点否则后期渲染出的地图结构会很乱。我的做法是在根目录建了一个命名规范说明文档明确每个技能节点的描述格式、标签格式和进度更新规则每次新增节点时对照着写能保持整个体系的一致性。2.2 进度状态与关联关系的处理进度状态不要只用一个百分比表示因为“掌握程度70%”在不同人眼里的含义完全不同。我做了一套更符合实际操作习惯的状态定义探索中刚接触看过文档或视频但还没有完整的实践产出实操中正在做项目踩过坑、填过坑理解逐步加深可复用能够将这项技能稳定运用于新场景并有自己的经验沉淀精进中对底层原理和边界条件有深入理解能解决问题并输出方法论这四个状态的判断标准不是自我感觉而是看有没有对应的产出物。比如“实操中”意味着至少有一个未完成或已完成的项目片段“可复用”意味着在独立项目里完整使用过该技术并解决问题。这样数据才算可信。关联关系的处理也挺讲究。每个技能节点我允许定义两个相关字段支持技能和扩展技能。支持技能代表掌握该技能需要的前置条件扩展技能代表学完这个技能之后可攀延的方向。这些关系链最终会生成一张隐形的学习路径图比逼着自己从头学一本700页的书要高效得多。2.3 内容维护的更新频率与信息过滤这是我用了一段时间才意识到的关键点技能管理不能“宽进宽出”否则信息噪音会淹没真正有价值的内容。每周整理一次所有节点的更新情况把进度状态有变化的地方更新一遍并补充笔记或链接这是维持整个系统有效性的核心习惯。我给自己定了一个很笨但有效的规则每次实际完成一个技术任务后必须回填技能记录。比如解决了某个线上问题就把排查思路写到对应的技能节点笔记里学会了一种新的设计模式就新建一个节点或更新现有节点的笔记。这个动作和写周报不一样写周报是给别人看的记录技能节点是给自己未来踩坑时看的。同时我还定期做“信息过滤”把那些长期停留在“探索中”且已经超过三个月没有更新的节点标记为“搁置”。这并非否定自己的学习冲动而是让资源分配回归现实。想学的东西无穷无尽但人的时间和精力有限明确承认优先级比假装拥有一棵无限大的技能树更实际。3. 实操过程与核心环节实现聊完设计思路再来说具体怎么落地。这部分会直接给出目录结构、代码示例和步骤感兴趣的朋友可以直接照着搭一套自己的版本。我用的技术栈是Vite Vue 3 VitePress但核心思想不绑定框架就算你用其他静态站点生成器也能实现相同效果。3.1 目录结构与配置文件设计整个项目的目录结构非常清晰大概长这样skills/ ├── docs/ │ ├── .vitepress/ │ │ ├── config.mts │ │ └── theme/ │ └── index.md ├── skills-data/ │ ├── frontend/ │ │ ├── react.md │ │ ├── vue.md │ │ └── engineering.md │ ├── backend/ │ │ ├── java.md │ │ ├── go.md │ │ └── database.md │ └── meta/ │ ├── categories.json │ └── tags.json ├── scripts/ │ ├── generate-data.mjs │ └── validate-files.mjs └── package.jsonskills-data目录是全部内容的数据源所有Markdown文件按分类归置。meta目录存的是分类和标签的元数据包括分类描述、排序权重和标签颜色。scripts目录放的是自动化脚本一个负责生成前端需要的索引数据一个负责校验文件格式是否规范。这样分离的好处是数据与展示完全解耦。Markdown是源数据任何编辑器都能修改脚本生成的内容是产物可以直接被前端消费。后面就算想迁移到其他站点框架也只需要改脚本和展示层核心数据零损失。3.2 技能文件的内容规范每个技能文件我统一采用这样的格式--- name: Docker部署与编排 id: docker-deploy-orchestration category: backend/engineering tags: [容器化, DevOps] status: operational progress: 78 related: - linux-basics - ci-cd-pipeline created: 2025-01-15 updated: 2025-03-02 --- ## 当前掌握情况 - 镜像构建与优化多阶段构建、构建上下文优化 … - 容器网络bridge网络、host网络、overlay网络的使用边界 … - Compose部署多容器编排、依赖启动顺序、日志聚合 … ## 踩坑记录 ### Compose健康检查的陷阱 写启动依赖条件时直接检查目标服务端口容易误判因为很多容器是端口先监听、应用还没就绪。后来改用healthcheck指令配合条件启动才稳定下来 … ## 学习资源 - 官方文档: … - 参考项目: …YAML元信息中的status字段取值有限制可以直接用枚举值progress是0到100的整数前端据此渲染进度环related字段通过技能ID建立关联即使文件不在同一分类目录也不妨碍图结构生成。每天早上我用脚本扫描一遍所有markdown文件的头部信息自动检查字段格式是否合法字段值是否越界以及关联的技能ID是否存在。这个校验脚本虽然简单但非常实用因为Markdown手工编辑容易出现拼写错误越早发现越容易修复。3.3 索引生成脚本与数据流VitePress本身可以直接遍历文件系统生成侧边栏但我们的场景需要更定制化的索引数据。比如要在首页展示技能分类统计、各分类掌握程度对比以及每个技能的最近更新时间列表这些界面需要聚合数据。所以我在scripts/generate-data.mts里面写了一段读取Markdown并生成JSON索引的逻辑import { globSync } from node:fs; import matter from gray-matter; import path from node:path; const skillDirs [frontend, backend, engineering, data, soft-skills]; const result skillDirs.map((dir) { const files globSync(${dir}/*.md, { cwd: skills-data }); const skills files.map((file) { const raw await readFile(path.join(skills-data, file), utf-8); const { data } matter(raw); return { name: data.name, id: data.id, category: data.category, tags: data.tags, status: data.status, progress: data.progress, updated: data.updated, }; }); return { dir, skills }; }); writeFile(docs/.vitepress/generated-index.json, JSON.stringify(result));这里有个细节值得提一下为什么索引数据用JSON文件而不是直接用VitePress插件动态注入因为VitePress的构建时序里页面渲染和数据获取需要保持同步直接用异步读取文件系统会破坏SSG的编译过程。生成静态JSON再导入等于把数据获取提前到构建脚本阶段构建时纯粹消费静态数据稳定且快速。3.4 前端展示的组件拆分到展示层我拆分成三类组件概览仪表盘组件、技能树组件、详情面板组件。概览仪表盘负责显示分类统计和整体进度技能树组件负责呈现左边分类、右边技能列表的布局详情面板则负责具体某一个技能的笔记渲染。技能树组件做了个很关键的小功能状态筛选。顶部一排下拉选项可以同时选中“当前主力实操中后端”这样筛选出来的就是当前最值得深入整理的技能子集。点击技能节点之后右侧浮现详情面板把对应Markdown的正文内容渲染出来整个交互路径非常短。为了让整体看起来更像一份“资产表”我在首页还放了一个简单的个人能力矩阵图横轴是分类域纵轴是技能状态气泡大小代表投入时间或复杂度。这个效果不用额外图表库用纯CSS网格就能实现数据来源就是生成好的索引JSON。看着这个小图你对整体能力分布就有直觉认知了。3.5 自动化发布流程内容写完之后我配置了一条自动发布链路每次推送代码到主分支后由CI自动执行构建和部署。这省去了每次手动执行构建命令的麻烦也让“记录-提交-发布”各个环节都在极短周期内完成最大程度降低维护成本。配置文件并不复杂大致分成两步name: Deploy Skills Site on: push: branches: [main] jobs: build-and-deploy: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm install - run: npm run generate - run: npm run build - uses: peaceiris/actions-gh-pagesv4 with: deploy_key: ${{ secrets.DEPLOY_KEY }} publish_dir: ./docs/.vitepress/dist这套流程比较稳定实践下来没出过问题。容易漏掉的一点是手动编辑Markdown后一定要在本地跑一次npm run generate确认索引数据正确后再推送否则构建阶段会因为数据不一致而产生不可预期的页面展示。4. 常见问题与排查技巧实录做这个项目的过程中我踩了不少坑。有些属于设计层面的误判有些是具体实现时的隐藏问题。整理一份遭遇记录出来应该能帮你少走弯路。4.1 索引数据不更新页面一直显示旧的技能列表出现这个问题通常在于你修改了Markdown文件但没有重新生成索引数据。VitePress构建过程中如果只构建页面而索引JSON还是旧的技能列表就不会更新。排查思路是这样先看generated-index.json里面的更新时间有没有变如果没变就手动执行一次npm run generate再看控制台输出有没有报错。记得在npm脚本中把生成索引和构建串联起来比如build: npm run generate vitepress build。我后来为了防止这种低级错误在生成脚本里故意加了一条校验当检测到某个技能文件的更新时间早于索引文件的更新时间时直接抛出异常从源头上阻断掉旧数据的发布。4.2 技能ID修改后关联关系全部断掉这个问题很隐蔽因为关联字段是手写的一旦某个节点ID改了所有引用它的文件里面的related列表就不会自动更新。虽然可以靠搜索全部替换来批量修复但遇到大范围结构调整时稍微漏一处展示层就会出现悬空连接。后来我在校验脚本里增加了一项检查所有节点中被引用但是不存在的ID并输出警告列表。配合一个小函数在pre-commit钩子里面运行提交时就会自动发现这些断裂关联。修复提示也直接给出建议哪个文件引用了不存在ID修改起来效率高很多。4.3 同一分类下技能数量太多页面横向过长这个问题出现在技能树组件里当一个分类下面挂了大量技能节点左侧列表会撑得很长交互体验很差。我的做法是引入“聚焦模式”默认展示每个分类前8个技能用户点开分类或者切换到“全部”才展示完整列表。此外把所有标签也做成过滤条件比如选了“容器化”就只剩相关的节点列表长度自然大幅度下降。这个解决方案后来成了这个组件最有用的功能之一比不停优化Lazy Loading更直接。4.4 知识零散无法沉淀为完整技能经验这个虽然跟技术关系不大但是项目制技能管理系统最容易翻车的点。很多人的“skills”仓库最后变成一堆零散链接和随手记因为只记录了“我在学什么”没有记录“我学到了什么、学到的过程如何验证”。我的调整方案很简单为每个技能强制要求一个“实践记录”的章节。哪怕只有三百字也要说明这个技能在什么场景下解决了什么问题用了什么手段踩了什么坑。字数不多但完整记录过之后再看这个技能节点才有“真的掌握”的感觉。长期下来这套系统就不再是给人看的简历墙而是真正的工作底稿。4.5 分类边界的拉扯还有一种常见问题是分类设计得太绝对。比如“Docker”这个技能到底属于后端还是工程化我在维护初期经常为了这种归属纠结半天耗费精力还没有任何收益。后来我引入了“标签优先”的思路不再拘泥于唯一分类。一个技能可以归类到一个主分类同时在标签中携带其他领域属性。比如Docker的主分类是工程化标签有容器化、DevOps、后端基础设施。做查询时优先使用标签筛选分类只作为组织维度真正达到“一处记录多处可见”的效果。5. 内容生态与扩展方向规划当技能数据积累到一定规模之后继续往里塞内容不是关键关键的是让这套系统持续产生更多价值。我有两个扩展方向正在推进给还在规划类似项目的朋友做个参考。5.1 技能关联与学习路径的自动推荐现在我的数据里有技能节点之间的依赖关系下一步想基于这些关系自动生成学习路径推荐。比如当某个节点处于“探索中”状态系统可以根据它的前置技能状态生成一个动态提示你的“Linux基础”还处于“探索中”“容器网络”这个技能的学习路径建议先补足前置节点。实现思路不复杂本质上是对related字段的递归遍历。在一轮遍历中找出所有状态小于当前节点且有关联关系的节点按依赖顺序排成队列。这能有效避免“跳级式学习”造成的基础不牢问题比单纯的手工路径规划更适合长期演进。5.2 复盘周期与技能健康度审查技能点和知识体系一样如果不做定期体检整个系统的可信度会逐渐下降。我会每季度跑一次“技能健康度审查”统计哪些技能持续更新、哪些节点长期没有变动、哪些分类存在明显偏科同时对比上一季度的数据识别趋势。体检结果会输出一份简单的Markdown格式报告作为下一季度学习规划的参考。这不是为了给你打分而是帮你把时间和精力投向当前阶段更有回报的方向。技术风口变化快但个人的知识基础是长线投资定期复盘就是给这笔投资做检查确保收益比合理。5.3 外部数据导入与自动化运维目前Markdown数据格式是自己定义的后续还有一个更让人省心的方向支持导入其他平台的数据导出。比如某个技术训练营结业后导出的学习记录、某本书的章节打卡数据都可以通过一个小工具转换成本项目的技能节点格式。这种导入能力配合自动化脚本能大幅减少人工录入成本让“skills”仓库从静态记录变成活跃的私人学习中心。你可以设定一个周期性的定时任务每两周自动拉取某个远程练习平台的做题记录更新到本地技能节点再从已读笔记中提取最新心得整个循环完全脱离手工维护的范畴。6. 维护成本与心得让技能资产“活”起来做完这个项目最大的体会是企业做知识库和个人做技能管理其实是同一件事的两面。你需要的不是一套拿来炫耀的仪表盘而是一套能真正反映自己能力现状、辅助自己做出下一步学习与投入决策的工具。这套系统的维护成本远没有想象中那么高。就我实际操作下来的体验每周维护一次大概需要二十分钟更新进度、补几行踩坑点、偶尔新增一两个节点。很多时候更新进度甚至用不了二十分钟五分钟就完事了。一个人不需要专门为此管理后台只要编辑器加一个快捷键就能达到快速记录的目的。如果你是刚开始做这类项目我的建议是不要一开始就追求字段丰富、功能全面。优先搭建最小闭环一个干净的目录结构、一套能生成索引的文件规范、一个只会展示与筛选的前端页面。先用起来再根据自己实际记录习惯去迭代。另外别太在“记录”这个动作上花过多时间。真正的成长来自实践而不在于你记录了多少漂亮的技能节点。一个几百字的踩坑记录比十次“复制粘贴资源链接”带来更多可沉淀的资产。每个节点写下“它在什么场景解决了什么问题”就足够了。我还是很推荐做一套自己的技能资产管理系统的从最初的“什么都想记”阶段慢慢调整到“只记真正和主线相关的内容”这个过程本身就是一个很好的自我梳理与专注力训练。数据不用太复杂坚持是第一生产力。等哪一天你在项目里再次需要某个知识点但完全不记得当初学过的时候你就会知道这套薄薄的Markdown仓库远比一个硬盘里的收藏夹有价值。 
长河君 · 2026/10/29 3:54:09 · 阅读 1.2k 构建个人技能管理系统：用Markdown与VitePress打造结构化技能地图
做了这么些年技术侧的事我一直有个挺要命的习惯资料存了一堆技能树画了一堆真到要用的时候反而得翻半天。GitHub星标几百个开源仓库真正沉淀下来的却没多少。后来我实在忍不了决定做个私人的“skills”项目把所有会用、想学和正在学的技能全部结构化、地图化地管起来。这个项目做到了三件事一是让我在两分钟内看清自己的技术栈全貌哪些能打、哪些刚入门二是沉淀了一套可以随时更新的“技能档案”不再依赖脑子记三是把学习路径拆成了有进度、有依据的节点每一步的投入和产出都看得见。整个过程踩了不少坑也总结了一些可复用的做法。这篇博文就把完整的拆分思路、数据结构设计和落地过程都摊开聊一聊适合那些想把自己“知识资产”真正管理起来的朋友参考。1. 项目整体设计与思路拆解做“skills”项目之前我首先搞清楚了一个问题我要管理的是什么是单纯罗列技术的Excel表还是动态追踪能力的成长体系如果只是列个清单那还不如一条便签纸。所以我从一开始就决定整个项目要有三层结构技能分类、技能详情、成长状态。1.1 从“技术清单”升级为“技能地图”很多人喜欢把技能写成一长条列表比如“Python、React、Docker、K8s、爬虫、数据分析……”。这种列表最大的问题在于没有层级关系也看不出能力之间的依赖。你写了Python和爬虫但这两者之间是什么关系前端会React后端会Flask可它们组合起来能做什么列表回答不了。我设计的第一层是分类域。把所有技能按照用途分成几个主域前端、后端、工程化、数据、软技能甚至包括领域知识。每个主域下面再拆成具体的技能点和子技能点。这样在查看时是树状结构而不是一张大饼任何一项技能都能找到它的归属位置从整体到细节一目了然。这套结构也不复杂本质上就是构建一棵“技能树”。举个例子后端域下面可以挂“Java”“Go”“数据库设计”这类节点而“数据库设计”又能继续往下细化成“索引优化”“分库分表”“慢查询排查”。前两层是宏观分类越往下越贴近具体实操恰好对应“知道什么”“用过什么”“精通什么”的不同层次。我还在每个技能节点上添加了归属标签比如“当前主力”“正在补充”“准备了解”方便后续做优先级排序。标签比单一等级更灵活可以组合查询比如“主力技能后端数据库”筛出来就是当前最值得投入时间去复盘和深入的部分。1.2 信息架构选型Markdown存储、结构化展示确定好结构之后接下来就是选存储方案。一开始我考虑过用数据库甚至想做一个完整的管理后台后来发现完全没必要。个人技能管理场景的特点是数据量不大、字段不复杂、需要频繁编辑。用数据库管理和后台表单反而会增加很多维护成本。我最终选了Markdown 前端渲染的方案。每个技能写成一个MD文件文件名就是这把技能的ID文件内部用YAML Front Matter记录元信息正文内容则用Markdown记录学习笔记、进度和踩坑经验。渲染端用Vite Vue 3搭了个轻量站点读取这些MD文件渲染成结构化的技能地图。这个方案最大的好处是低摩擦。记录经验这个动作本身要足够轻才不会变成负担。打开编辑器新建一个文件花一分钟写下今天学会了什么顺手更新进度百分比这就是一次完整记录。如果每次记录都要打开后台、填表单、点保存我保证用不了一个月你就会放弃。1.3 数据模型的迭代过程最开始我设计的数据结构其实繁琐得多每个技能下面包含很多冗余字段比如预期时间、资源链接、评审结论等。用了一段时间之后发现大部分字段根本不会被填也容易因为维护成本高而瘫痪。后来我把字段砍到了最低限度只保留几个核心维度技能名称与唯一ID所属分类和标签掌握程度百分比或等级最近更新时间相关链接与依赖技能这样设计的好处是把“记录”这个动作简化到极致。掌握程度和更新时间是靠数据说话的硬指标标签和分类是外部属性剩下的内容随心写。复杂想法可以写长笔记简单补充就一两句话系统不会因为信息过载而失真。2. 核心细节解析与实操要点结构设计完最核心的环节就是怎么让这套系统真正“运转”起来。运转包括两个层面一是内容层面的记录规则二是数据层面的组织方式。很多人的技能管理项目最后烂尾问题就出在这两个层面的细节没想清楚。2.1 技能节点的粒度控制这是整个项目里最关键、也最容易出错的地方。如果技能粒度太粗比如“后端开发”作为一个技能点那这条数据基本等于没记录因为它没法指导你下一步学什么。如果粒度太细把“容器网络策略配置”这种知识点也单独列一个节点维护成本又会暴涨时间一长必然放弃。我摸索出的经验是以“能否在一到两周内产生可验证的实践成果”为粒度标准。比如“Docker”粒度偏粗但“Docker常用命令与Dockerfile编写”“Docker Compose部署多容器应用”“镜像构建优化”这三个细分兴趣点就刚刚好。每个点都对应一个具体场景能通过一个小项目或需求验证掌握程度。实操时还需要注意一点粒度规则要保持一致。不要今天写一个很细的节点明天又写一个大而全的节点否则后期渲染出的地图结构会很乱。我的做法是在根目录建了一个命名规范说明文档明确每个技能节点的描述格式、标签格式和进度更新规则每次新增节点时对照着写能保持整个体系的一致性。2.2 进度状态与关联关系的处理进度状态不要只用一个百分比表示因为“掌握程度70%”在不同人眼里的含义完全不同。我做了一套更符合实际操作习惯的状态定义探索中刚接触看过文档或视频但还没有完整的实践产出实操中正在做项目踩过坑、填过坑理解逐步加深可复用能够将这项技能稳定运用于新场景并有自己的经验沉淀精进中对底层原理和边界条件有深入理解能解决问题并输出方法论这四个状态的判断标准不是自我感觉而是看有没有对应的产出物。比如“实操中”意味着至少有一个未完成或已完成的项目片段“可复用”意味着在独立项目里完整使用过该技术并解决问题。这样数据才算可信。关联关系的处理也挺讲究。每个技能节点我允许定义两个相关字段支持技能和扩展技能。支持技能代表掌握该技能需要的前置条件扩展技能代表学完这个技能之后可攀延的方向。这些关系链最终会生成一张隐形的学习路径图比逼着自己从头学一本700页的书要高效得多。2.3 内容维护的更新频率与信息过滤这是我用了一段时间才意识到的关键点技能管理不能“宽进宽出”否则信息噪音会淹没真正有价值的内容。每周整理一次所有节点的更新情况把进度状态有变化的地方更新一遍并补充笔记或链接这是维持整个系统有效性的核心习惯。我给自己定了一个很笨但有效的规则每次实际完成一个技术任务后必须回填技能记录。比如解决了某个线上问题就把排查思路写到对应的技能节点笔记里学会了一种新的设计模式就新建一个节点或更新现有节点的笔记。这个动作和写周报不一样写周报是给别人看的记录技能节点是给自己未来踩坑时看的。同时我还定期做“信息过滤”把那些长期停留在“探索中”且已经超过三个月没有更新的节点标记为“搁置”。这并非否定自己的学习冲动而是让资源分配回归现实。想学的东西无穷无尽但人的时间和精力有限明确承认优先级比假装拥有一棵无限大的技能树更实际。3. 实操过程与核心环节实现聊完设计思路再来说具体怎么落地。这部分会直接给出目录结构、代码示例和步骤感兴趣的朋友可以直接照着搭一套自己的版本。我用的技术栈是Vite Vue 3 VitePress但核心思想不绑定框架就算你用其他静态站点生成器也能实现相同效果。3.1 目录结构与配置文件设计整个项目的目录结构非常清晰大概长这样skills/ ├── docs/ │ ├── .vitepress/ │ │ ├── config.mts │ │ └── theme/ │ └── index.md ├── skills-data/ │ ├── frontend/ │ │ ├── react.md │ │ ├── vue.md │ │ └── engineering.md │ ├── backend/ │ │ ├── java.md │ │ ├── go.md │ │ └── database.md │ └── meta/ │ ├── categories.json │ └── tags.json ├── scripts/ │ ├── generate-data.mjs │ └── validate-files.mjs └── package.jsonskills-data目录是全部内容的数据源所有Markdown文件按分类归置。meta目录存的是分类和标签的元数据包括分类描述、排序权重和标签颜色。scripts目录放的是自动化脚本一个负责生成前端需要的索引数据一个负责校验文件格式是否规范。这样分离的好处是数据与展示完全解耦。Markdown是源数据任何编辑器都能修改脚本生成的内容是产物可以直接被前端消费。后面就算想迁移到其他站点框架也只需要改脚本和展示层核心数据零损失。3.2 技能文件的内容规范每个技能文件我统一采用这样的格式--- name: Docker部署与编排 id: docker-deploy-orchestration category: backend/engineering tags: [容器化, DevOps] status: operational progress: 78 related: - linux-basics - ci-cd-pipeline created: 2025-01-15 updated: 2025-03-02 --- ## 当前掌握情况 - 镜像构建与优化多阶段构建、构建上下文优化 … - 容器网络bridge网络、host网络、overlay网络的使用边界 … - Compose部署多容器编排、依赖启动顺序、日志聚合 … ## 踩坑记录 ### Compose健康检查的陷阱 写启动依赖条件时直接检查目标服务端口容易误判因为很多容器是端口先监听、应用还没就绪。后来改用healthcheck指令配合条件启动才稳定下来 … ## 学习资源 - 官方文档: … - 参考项目: …YAML元信息中的status字段取值有限制可以直接用枚举值progress是0到100的整数前端据此渲染进度环related字段通过技能ID建立关联即使文件不在同一分类目录也不妨碍图结构生成。每天早上我用脚本扫描一遍所有markdown文件的头部信息自动检查字段格式是否合法字段值是否越界以及关联的技能ID是否存在。这个校验脚本虽然简单但非常实用因为Markdown手工编辑容易出现拼写错误越早发现越容易修复。3.3 索引生成脚本与数据流VitePress本身可以直接遍历文件系统生成侧边栏但我们的场景需要更定制化的索引数据。比如要在首页展示技能分类统计、各分类掌握程度对比以及每个技能的最近更新时间列表这些界面需要聚合数据。所以我在scripts/generate-data.mts里面写了一段读取Markdown并生成JSON索引的逻辑import { globSync } from node:fs; import matter from gray-matter; import path from node:path; const skillDirs [frontend, backend, engineering, data, soft-skills]; const result skillDirs.map((dir) { const files globSync(${dir}/*.md, { cwd: skills-data }); const skills files.map((file) { const raw await readFile(path.join(skills-data, file), utf-8); const { data } matter(raw); return { name: data.name, id: data.id, category: data.category, tags: data.tags, status: data.status, progress: data.progress, updated: data.updated, }; }); return { dir, skills }; }); writeFile(docs/.vitepress/generated-index.json, JSON.stringify(result));这里有个细节值得提一下为什么索引数据用JSON文件而不是直接用VitePress插件动态注入因为VitePress的构建时序里页面渲染和数据获取需要保持同步直接用异步读取文件系统会破坏SSG的编译过程。生成静态JSON再导入等于把数据获取提前到构建脚本阶段构建时纯粹消费静态数据稳定且快速。3.4 前端展示的组件拆分到展示层我拆分成三类组件概览仪表盘组件、技能树组件、详情面板组件。概览仪表盘负责显示分类统计和整体进度技能树组件负责呈现左边分类、右边技能列表的布局详情面板则负责具体某一个技能的笔记渲染。技能树组件做了个很关键的小功能状态筛选。顶部一排下拉选项可以同时选中“当前主力实操中后端”这样筛选出来的就是当前最值得深入整理的技能子集。点击技能节点之后右侧浮现详情面板把对应Markdown的正文内容渲染出来整个交互路径非常短。为了让整体看起来更像一份“资产表”我在首页还放了一个简单的个人能力矩阵图横轴是分类域纵轴是技能状态气泡大小代表投入时间或复杂度。这个效果不用额外图表库用纯CSS网格就能实现数据来源就是生成好的索引JSON。看着这个小图你对整体能力分布就有直觉认知了。3.5 自动化发布流程内容写完之后我配置了一条自动发布链路每次推送代码到主分支后由CI自动执行构建和部署。这省去了每次手动执行构建命令的麻烦也让“记录-提交-发布”各个环节都在极短周期内完成最大程度降低维护成本。配置文件并不复杂大致分成两步name: Deploy Skills Site on: push: branches: [main] jobs: build-and-deploy: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm install - run: npm run generate - run: npm run build - uses: peaceiris/actions-gh-pagesv4 with: deploy_key: ${{ secrets.DEPLOY_KEY }} publish_dir: ./docs/.vitepress/dist这套流程比较稳定实践下来没出过问题。容易漏掉的一点是手动编辑Markdown后一定要在本地跑一次npm run generate确认索引数据正确后再推送否则构建阶段会因为数据不一致而产生不可预期的页面展示。4. 常见问题与排查技巧实录做这个项目的过程中我踩了不少坑。有些属于设计层面的误判有些是具体实现时的隐藏问题。整理一份遭遇记录出来应该能帮你少走弯路。4.1 索引数据不更新页面一直显示旧的技能列表出现这个问题通常在于你修改了Markdown文件但没有重新生成索引数据。VitePress构建过程中如果只构建页面而索引JSON还是旧的技能列表就不会更新。排查思路是这样先看generated-index.json里面的更新时间有没有变如果没变就手动执行一次npm run generate再看控制台输出有没有报错。记得在npm脚本中把生成索引和构建串联起来比如build: npm run generate vitepress build。我后来为了防止这种低级错误在生成脚本里故意加了一条校验当检测到某个技能文件的更新时间早于索引文件的更新时间时直接抛出异常从源头上阻断掉旧数据的发布。4.2 技能ID修改后关联关系全部断掉这个问题很隐蔽因为关联字段是手写的一旦某个节点ID改了所有引用它的文件里面的related列表就不会自动更新。虽然可以靠搜索全部替换来批量修复但遇到大范围结构调整时稍微漏一处展示层就会出现悬空连接。后来我在校验脚本里增加了一项检查所有节点中被引用但是不存在的ID并输出警告列表。配合一个小函数在pre-commit钩子里面运行提交时就会自动发现这些断裂关联。修复提示也直接给出建议哪个文件引用了不存在ID修改起来效率高很多。4.3 同一分类下技能数量太多页面横向过长这个问题出现在技能树组件里当一个分类下面挂了大量技能节点左侧列表会撑得很长交互体验很差。我的做法是引入“聚焦模式”默认展示每个分类前8个技能用户点开分类或者切换到“全部”才展示完整列表。此外把所有标签也做成过滤条件比如选了“容器化”就只剩相关的节点列表长度自然大幅度下降。这个解决方案后来成了这个组件最有用的功能之一比不停优化Lazy Loading更直接。4.4 知识零散无法沉淀为完整技能经验这个虽然跟技术关系不大但是项目制技能管理系统最容易翻车的点。很多人的“skills”仓库最后变成一堆零散链接和随手记因为只记录了“我在学什么”没有记录“我学到了什么、学到的过程如何验证”。我的调整方案很简单为每个技能强制要求一个“实践记录”的章节。哪怕只有三百字也要说明这个技能在什么场景下解决了什么问题用了什么手段踩了什么坑。字数不多但完整记录过之后再看这个技能节点才有“真的掌握”的感觉。长期下来这套系统就不再是给人看的简历墙而是真正的工作底稿。4.5 分类边界的拉扯还有一种常见问题是分类设计得太绝对。比如“Docker”这个技能到底属于后端还是工程化我在维护初期经常为了这种归属纠结半天耗费精力还没有任何收益。后来我引入了“标签优先”的思路不再拘泥于唯一分类。一个技能可以归类到一个主分类同时在标签中携带其他领域属性。比如Docker的主分类是工程化标签有容器化、DevOps、后端基础设施。做查询时优先使用标签筛选分类只作为组织维度真正达到“一处记录多处可见”的效果。5. 内容生态与扩展方向规划当技能数据积累到一定规模之后继续往里塞内容不是关键关键的是让这套系统持续产生更多价值。我有两个扩展方向正在推进给还在规划类似项目的朋友做个参考。5.1 技能关联与学习路径的自动推荐现在我的数据里有技能节点之间的依赖关系下一步想基于这些关系自动生成学习路径推荐。比如当某个节点处于“探索中”状态系统可以根据它的前置技能状态生成一个动态提示你的“Linux基础”还处于“探索中”“容器网络”这个技能的学习路径建议先补足前置节点。实现思路不复杂本质上是对related字段的递归遍历。在一轮遍历中找出所有状态小于当前节点且有关联关系的节点按依赖顺序排成队列。这能有效避免“跳级式学习”造成的基础不牢问题比单纯的手工路径规划更适合长期演进。5.2 复盘周期与技能健康度审查技能点和知识体系一样如果不做定期体检整个系统的可信度会逐渐下降。我会每季度跑一次“技能健康度审查”统计哪些技能持续更新、哪些节点长期没有变动、哪些分类存在明显偏科同时对比上一季度的数据识别趋势。体检结果会输出一份简单的Markdown格式报告作为下一季度学习规划的参考。这不是为了给你打分而是帮你把时间和精力投向当前阶段更有回报的方向。技术风口变化快但个人的知识基础是长线投资定期复盘就是给这笔投资做检查确保收益比合理。5.3 外部数据导入与自动化运维目前Markdown数据格式是自己定义的后续还有一个更让人省心的方向支持导入其他平台的数据导出。比如某个技术训练营结业后导出的学习记录、某本书的章节打卡数据都可以通过一个小工具转换成本项目的技能节点格式。这种导入能力配合自动化脚本能大幅减少人工录入成本让“skills”仓库从静态记录变成活跃的私人学习中心。你可以设定一个周期性的定时任务每两周自动拉取某个远程练习平台的做题记录更新到本地技能节点再从已读笔记中提取最新心得整个循环完全脱离手工维护的范畴。6. 维护成本与心得让技能资产“活”起来做完这个项目最大的体会是企业做知识库和个人做技能管理其实是同一件事的两面。你需要的不是一套拿来炫耀的仪表盘而是一套能真正反映自己能力现状、辅助自己做出下一步学习与投入决策的工具。这套系统的维护成本远没有想象中那么高。就我实际操作下来的体验每周维护一次大概需要二十分钟更新进度、补几行踩坑点、偶尔新增一两个节点。很多时候更新进度甚至用不了二十分钟五分钟就完事了。一个人不需要专门为此管理后台只要编辑器加一个快捷键就能达到快速记录的目的。如果你是刚开始做这类项目我的建议是不要一开始就追求字段丰富、功能全面。优先搭建最小闭环一个干净的目录结构、一套能生成索引的文件规范、一个只会展示与筛选的前端页面。先用起来再根据自己实际记录习惯去迭代。另外别太在“记录”这个动作上花过多时间。真正的成长来自实践而不在于你记录了多少漂亮的技能节点。一个几百字的踩坑记录比十次“复制粘贴资源链接”带来更多可沉淀的资产。每个节点写下“它在什么场景解决了什么问题”就足够了。我还是很推荐做一套自己的技能资产管理系统的从最初的“什么都想记”阶段慢慢调整到“只记真正和主线相关的内容”这个过程本身就是一个很好的自我梳理与专注力训练。数据不用太复杂坚持是第一生产力。等哪一天你在项目里再次需要某个知识点但完全不记得当初学过的时候你就会知道这套薄薄的Markdown仓库远比一个硬盘里的收藏夹有价值。