企业官网建设流程全解析

最近这两周，我用 Pi 把一个几乎空白的新领域从头啃了一遍。老实说，真正劝退我的从来不是“学不会”，而是“不知道自己哪里不会”——翻开教程每句话都认识，合上文档又讲不出个所以然。后来我把学习拆成了四步：摸底、画图、出题、写笔记，并且把这套流程做成了一个 Pi 的 skill，名字叫 learn-buddy。现在只要丢给它一个主题，它就能按固定流程帮我补齐认知短板。这篇文章会把思路、配置、核心提示词，以及踩过的坑一起整理出来，方便大家直接抄作业。

如果你还没接触过 Pi，可以把它理解成一个跑在命令行里的智能体：能读写文件、执行命令、处理项目，而 skill 等于给智能体加装的能力包，相当于一本岗位操作手册。两者配合以后，能做到“输入一个主题，自动执行一套学习动作”。这套玩法适合三类人：想认真学技术但总被碎片化信息带偏的；用 AI 学习但觉得对话式学习太浅的；以及好奇 skill 怎么写、想拿现成配置改一改的。

1. 为什么我要把学习流程做成一个 skill

1.1 skill 和普通提示词的根本区别

我先说个结论：普通提示词是“即兴发挥”，skill 是“标准化作业”。很多人以为 skill 无非就是把一段提示词存起来，换个地方调用，真做起来才发现差异很大。

举一个我自己的例子。以前我让 AI 帮我学一个主题，需要打一大段话：“请你先了解一下这个概念，然后给我讲清楚，最后帮我整理成笔记。”每次都要重新解释背景，AI 每次的发挥也不稳定。今天它先讲原理，明天它先讲应用，反馈飘得很。后来我把流程写进 skill，等于给它固定了一本 SOP：主语永远是用户，先做什么后做什么都有顺序，输出格式也有模板，甚至连“不许在摸底阶段直接给我答案”这种违反直觉的规则都写进去了。

skill 和 agent 的关系也常有人问。我的理解是：agent 是“执行者”，负责规划任务、调用工具、管理上下文；skill 是“操作手册”，专攻某一个领域或场景。还是拿厨师举例，agent 是厨师长，负责排菜、安排人手、控火候；skill 写着宫保鸡丁的标准做法、调料比例、出菜顺序。厨师长换谁都能炒，但没这本手册，每次的味道就不稳定。

普通提示词和 skill 的核心差异，我整理成了下面这张表：

这五点里，最容易被低估的是“边界控制”。比如摸底这个动作，如果我用普通提示词，AI 大概率会跳过提问直接开始讲课，因为它默认用户是来“听讲”的。而 skill 里我明确写了“摸底阶段只提问、只评分、不给结论”，AI 就会老老实实把问卷出完。这种约定俗成的“行为约束”，靠普通提示词很难稳定做到。

1.2 学习这件事，卡住的其实就是四个环节

做这套 skill 之前，我把自己过去学新东西的路径重新捋了一遍，发现绝大多数卡点都落在四个环节上。

第一个是摸底。学新领域最难的不是不懂，而是不知道自己哪里不懂。比如我想学消息队列，我可能知道自己“不会用”，但说不出自己缺的是基础概念、网络原理还是运维经验。如果 AI 一上来就给我灌一篇万字长文，我根本不知道往哪个方向使劲。

第二个是画图。很多概念看文字觉得懂了，一旦要求自己画出来就露馅。因为文字是线性的，而知识是网状的。AI 很擅长把一段话变成一张图，但它不会主动告诉你“为什么选流程图而不是时序图”，所以需要 skill 把它规范成“先定图型，再生成图，再解释结构”这个顺序。

第三个是出题。这是检验“假性学习”的最好工具。看完材料觉得自己会了，但让你做几道题，立刻原形毕露。问题在于，自己给自己出题很容易只考自己会的部分，考不到盲区。让 AI 出题，再配合标准答案，就能从记忆、理解、应用三个层面查漏补缺。

第四个是写笔记。我对传统笔记最大的意见是它像流水账：日期、标题、一堆摘抄，三个月后根本不知道重点在哪。有价值的笔记应该是一张张结构化的卡片，每张卡片解决一个具体问题，还能通过标签互相串联，方便以后检索。

这四件事恰好对应 skill 的四个动作。下面两章我先把环境搭好，再逐个拆解具体实现。

2. 搭建 Pi 环境与 learn-buddy 技能包

2.1 先把 Pi 装好并跑起来

安装 Pi 的过程不算复杂，但不同版本命令会有些出入。我这边用的是当前主流的 CLI 版本，安装命令大致是这样：

npm install -g pi-agent

如果你的环境里没有 Node.js，也可以走 pip 路线：

pip install pi-agent

装完之后先验证一下：

pi --version pi doctor

pi doctor是我很推荐先跑的一条命令，它会检查环境变量、插件目录、权限配置这些基础项，能省掉后面很多莫名其妙的报错。如果你安装的版本命令名不一样，直接执行pi --help就能看到当前支持的命令列表，不用死记。

跑通之后，再确认一下 skill 相关的命令能用。由于 Pi 的版本迭代比较快，有的版本用pi skill list，有的版本简写成pi s list，直接看 help 输出最稳。这一步的目的是确保后续能安装和调试我们自己的 skill。

2.2 skill 包的标准目录结构

Pi 的 skill 通常是一个目录，里面至少包含一个主文件和若干资源。我的 learn-buddy 完整结构如下：

learn-buddy/ ├── SKILL.md # 技能主文件，包含说明和指令 ├── assets/ │ ├── survey_template.md # 摸底问卷模板 │ ├── diagram_guide.md # 图形选择指南 │ ├── quiz_template.md # 出题模板 │ └── note_template.md # 笔记模板 └── scripts/ └── parse_output.py # 可选的输出解析脚本

每个文件的用途我后面会逐个展开。这里先强调一个容易被忽略的点：assets 目录不只是摆设，它能让 skill 在运行时把模板读进上下文，比把模板硬编码在 SKILL.md 里干净得多。skill 一长，主文件里的提示词很容易超过上下文窗口，把模板抽出来是必须做的。

安装的时候，把整个目录放到 Pi 的 skills 目录下，然后执行：

pi skill install ./learn-buddy pi skill list

如果 list 里能看到 learn-buddy，说明安装成功。

2.3 SKILL.md 的核心内容怎么写

SKILL.md 一般分成两部分，开头的 YAML 元信息和正文指令。元信息最重要的字段是 description，它决定了这个 skill 在什么场景下被触发。我的写法是：

--- name: learn-buddy description: 学习辅助技能。用户输入一个想学的主题时，自动执行摸底、画图、出题、写笔记四步。 allowed-tools: read, write, bash ---

description 要尽量贴近用户会说的话，否则触发率很低。比如你写“用于学习场景的高级认知流程”，AI 可能根本匹配不上；写成“用户输入一个想学的主题时”，它就知道什么时候该调用了。

正文部分，我会在下一章把四段核心指令分别贴出来。这里先定一个大框架：整个技能强调顺序执行，每一步之间要给出小结，并且禁止跳步。这也符合学习认知的规律，先测基线，再建结构，再验证，最后沉淀。还要提醒一句：SKILL.md 里的指令不是越长越好。太长的指令会占用上下文，而且容易让模型抓不住重点。我的经验是控制在 500 行以内，能用模板解决的内容不要写死在指令里。

3. 四大功能逐个拆解：摸底、画图、出题、笔记

3.1 摸底：先知道我哪里不会

摸底的核心思路不是让 AI 讲课，而是让 AI 当一面镜子。它通过有层次的提问，帮我把“我不知道自己不知道”的区域照出来。

我的 survey_template.md 把摸底问题分成了五个维度：基础概念、核心原理、应用场景、常见误区、实操经验。每个维度下面都有 3 到 5 道题，每题让用户用 1 到 5 分自评，并写一句理由。

在 SKILL.md 里，这一段的指令我写的是：

当用户进入摸底阶段时，不许直接解释主题，只输出问卷。问卷包含 5 个维度，每个维度至少 3 题，每题给出自评打分标准。问卷结束后，输出一张能力差距表，按得分从低到高列出最需要优先学习的 3 个知识点。

你可能觉得“不许直接解释主题”这条规则很奇怪。但实际使用里，AI 的默认倾向就是赶紧开始讲课。如果你不把它写死，它大概率会在摸底环节顺便把答案也说了。这会让用户失去主动思考的机会，摸底就废了。

摸底阶段的输出长这样（以“消息队列”为例）：

这张表对我的价值在于：它不是让我“从头学”，而是直接告诉我三个优先知识点——ack 机制、持久化、专业 MQ 和 Redis 的差异。后续所有学习都围绕这三块展开，效率完全不同。

3.2 画图：把概念变成结构

很多概念看文字觉得懂了，一旦要求自己画出来就露馅。因为文字是线性的，而知识是网状的。Pi 可以把一段文字变成图，但它不会主动告诉你“为什么选流程图而不是时序图”，所以我把这个决策过程也写进了技能。

diagram_guide.md 里维护了一张图形类型对照表：

技能启动画图动作时，会先根据主题内容判断应该用哪种图，再要求 AI 给出“图形选择理由 + 图本身 + 图例说明”三件套。强制输出选择理由，是为了避免 AI 随手画一张图糊弄过去。

实际效果举例。有一次我让它画“HTTP 缓存更新流程”，它先告诉我“这里涉及浏览器、服务器、缓存三个角色，信息有来有回，推荐时序图”，然后才生成图。这个过程本身就在帮我梳理结构：我被迫去想这些角色之间到底有什么消息在流动。

3.3 出题：从看懂到会用

出题是整个 skill 里我最看重的部分，因为它直接对抗“假性学习”。看完材料自信满满，一做题原地崩溃，这是最典型的学习错觉。

我把出题分成了六个层次，对应布鲁姆分类法：记忆、理解、应用、分析、评价、创造。skill 会要求在这六个层次里至少覆盖四个，每种题型都必须包含标准答案和解析。

题库模板大致是这样的：

出题时最忌讳的是全出选择题，因为选择题天然有蒙的成分。我要求至少两道场景题和一道综合题，凡是答案能直接用原文复述的题，都会被打回重出。

实际上，AI 生成的解析比题目本身还有价值。它会告诉你这个考点对应哪块知识点，容易错在哪。我通常会把“错因分析”和“考点定位”两列加进题目表里，相当于给每个错误预埋了一根纠偏线索。

3.4 写笔记：让知识可以被检索

最后的笔记阶段，负责把前面所有学习成果沉淀下来。我使用的不是传统流水账，而是一张张结构化的知识卡片。

note_template.md 里的卡片模板分为四类：

• 概念卡：这个东西是什么、不是什么
• 原理卡：底层机制是怎样的，为什么这样设计
• 代码卡：怎么用、关键代码、参数含义
• 坑卡：容易出错的地方、避坑方法

每张卡片必须有独立的标题和标签，方便之后放进 Obsidian 这类双链笔记工具里检索。技能在写笔记时会额外做一件事：把本次学习过程中出现的错误理解单独拎出来，生成一张“纠偏卡”，记录“我原来是怎么理解的，正确理解是什么”。这张卡是我后来复盘时觉得最值钱的资产。

我在 SKILL.md 里对笔记阶段的要求是：控制单张卡片篇幅，一般不超过 15 行；标题必须包含关键词；结尾附一行“下一步建议”。这样做的目的是让笔记成为可以行动的清单，而不是一堆好看但没人看的 Markdown 文件。

4. 一次完整实战：用 Pi 从零学习 Python 异步编程

光讲设计不说实例，总觉得不够落地。下面用一个完整的例子，把 learn-buddy 跑一遍。我选的主题是“Python 异步编程”，一个我自己其实一知半解的领域。

4.1 第一步：摸底问卷帮我锁定了三个盲区

我向 Pi 输入：

用 learn-buddy 学习：Python 异步编程

它先进入了摸底阶段。整个过程大概持续了五分钟，它问了我 15 道问题，涵盖协程、事件循环、async/await、并发与并行的区别、GIL 的影响、asyncio 的实际应用等。

我印象最深的一道题是：“如果你有一个 IO 密集型任务和一个 CPU 密集型任务，你会分别怎么用异步处理？请说明理由。”这道题直接暴露了我把异步当成“万能并发”的错误认知。最终输出的能力差距表显示，我最需要优先补的是三个点：事件循环的调度机制、asyncio 的并发模型边界、异步与多线程的适用场景。

4.2 第二步：画图把事件循环讲明白了

摸底之后，Pi 进入画图环节。它先给了一个图形类型判断：“这里涉及任务注册、调度、挂起、恢复这些状态变化，推荐状态图为主，辅以流程图。”

它生成的文本结构图大概是这样的：

Task A --注册--> Event Loop --调度--> Task A 执行 | +--IO等待--挂起--> 注册回调 | +--IO完成--唤醒--> 恢复执行

我不打算把整张图贴全，重点在于它接下来的解释。它解释说 Event Loop 并不会神奇地让两个任务同时跑，它只是在等待 IO 的时候切去执行别的任务，让 CPU 不要闲着。这句话我之前看过无数遍，但配合那张图以后，我一下就理解透了。这说明一个好的画图环节，不只是给你一张图，而是帮你把脑子里的混沌结构重建一遍。

4.3 第三步：十道题检验我是不是真的会了

出题阶段，它给了我一份十道题的试卷，题型分布是：

其中一道场景题我到现在还记得：“假设你要写一个爬虫，同时请求 100 个网页，你会用 asyncio 还是线程池？”我一开始想选 asyncio，但看完解析后发现题目里的陷阱在于——如果你还要在请求之间做大量 CPU 计算，纯异步并不合适。这道题把我之前那个“异步万能”的错误认知连根拔起。

做完这套题，我给自己打的分是刚及格。很挫败，但也非常清醒：我知道自己卡在哪个环节，而不是像以前一样学完一个主题就自我感觉良好。

4.4 第四步：沉淀出可以复用的笔记卡片

最后，Pi 根据整个学习过程生成了八张笔记卡，包括三张概念卡、两张原理卡、两张代码卡和一张纠偏卡。

纠偏卡的核心我抄在这里：

错误理解：asyncio 是 Python 里的多线程并发。 正确理解：asyncio 是协作式并发，靠事件循环在等待 IO 时主动让出 CPU；真正的并行执行仍需要多进程。 触发场景：看到“异步就是并发”时自动触发提醒。

这八张卡片我现在还在用。每次遇到 async 相关代码，我都会先翻一下原理卡和坑卡，基本五分钟内就能回到状态，不用重新啃一遍教程。这就是结构化笔记最大的回报。

5. 踩坑实录：skill 不生效、响应中断怎么办

5.1 高频错误速查表

实操中遇到过不少问题，我把最典型的几条整理成表格：

其中response stream was malformed这个报错值得单独拿出来说一句。它不是 skill 本身的问题，而是流式传输过程中数据不完整，导致 AI 侧没有拿到完整内容。遇到这个情况，我的第一反应不是去改代码，而是先把任务拆小。比如原先让 skill 一次输出 2000 字的笔记，改成让它分章节输出，报错率会明显下降。

5.2 排查思路：先路径，后描述，再上下文

如果 skill 不生效，我摸索出一套排查顺序。第一步查路径，确认 skill 被装在 Pi 认可的目录里；第二步查 description，确认触发的语义描述够不够直白；第三步查上下文，确认是不是同一个会话里塞了太多内容，把 skill 指令挤出了上下文窗口。

这里有个比较反直觉的点：技能不生效，很多时候不是代码问题，而是“描述问题”。我的一个朋友把技能 description 写得特别学术，叫什么“基于元认知的个性化学习干预框架”，结果怎么调用都不生效。我让他改成“用户想学一个新主题时使用”，一次就通了。触发词越接近用户的自然表达，匹配率越高。

5.3 让 skill 发挥最大作用的两个经验

第一个经验：在 SKILL.md 里设置“退出条件”。比如摸底阶段，我要求“用户明确输入‘开始学习’之后才能进入下一步”。这看起来多余，实际能防止 AI 自作主张把所有阶段一次跑完，导致用户没有思考时间。学习这件事，最怕的就是赶进度。

第二个经验：让输出尽量结构化。问卷用表格、题目用编号、笔记用固定模板，这些结构化的输出不仅方便我自己记录，也方便后续二次加工。我甚至写过一个脚本，把 skill 输出的题目表自动转成 JSON，再导入到题库软件里抽题练习。这个思路你也可以复用：skill 负责生成结构化内容，脚本负责搬运和转换，两边都轻松。

最后再说点题外的。这套 skill 用了两周以后，我最大的体会是：学习新东西，真正稀缺的不是资料，而是反馈。Pi 和 learn-buddy 给我的不是更多知识，而是一套不断告诉我“你哪里还不会、为什么不会”的反馈机制。摸底、画图、出题、写笔记，每一步本质上都是在制造反馈信号。如果你也想做一套自己的 skill，我的建议是从你最常重复的一个工作流开始，把它拆成步骤写进 SKILL.md，哪怕只有三步也比没有强。跑通了之后，再慢慢加模板、加脚本，让流程越来越接近你脑子里的那条思考路径。