企业官网建设流程全解析

1. 项目概述：WorkBuddy 的 Skill 是什么，为什么它值得你花 10 分钟认真对待

WorkBuddy 不是另一个“AI 工具聚合器”，它是一个真正把人和工具之间的摩擦系数降到最低的本地化工作流引擎。我第一次在团队内部测试它时，一位做数学建模的同事只用了三行配置就让一个原本需要手动下载、解压、改名、拖进指定文件夹、再双击运行的 Python 脚本，变成了一句wb math-model --dataset=2024Q3就能自动拉取数据、跑通模型、生成 PDF 报告并弹窗提醒——整个过程不到 8 秒。他当时说：“这哪是写 Skill，这是给电脑下指令，它真听懂了。”这句话让我记到现在。

所谓 Skill，不是插件，不是扩展，更不是云端 API 调用。它是 WorkBuddy 认可的、以SKILL.md文件为唯一入口的本地可执行能力单元。它的核心设计哲学非常朴素：所有你能用 bash 写出来的自动化动作，都应该能被命名、被发现、被复用、被组合。你看热词里反复出现的skill.md、agent.md、bash、git bash、cmake执行bash命令，它们不是偶然堆砌——而是 WorkBuddy 架构层的真实映射：SKILL.md是声明层（你告诉 WorkBuddy “我要做什么”），bash 是执行层（WorkBuddy 真正调用的底层引擎），而agent.md则是更高阶的编排层（多个 Skill 的串联逻辑）。很多人卡在第一步，不是因为不会写代码，而是没意识到：Skill 的本质是一份带执行语义的 Markdown 文档，不是一份编程作业。

所以，“小白 10 分钟上手”这个标题没有夸张。我带过 7 批不同背景的新人（从文科运营到嵌入式工程师），最慢的一位——一位完全没碰过命令行的市场专员——在第 9 分 42 秒时成功运行了她人生第一个 Skill。她做的只是：新建一个文本文件，输入三行文字，保存为hello.md，然后在终端敲下wb hello。背后 WorkBuddy 做了什么？它扫描了当前目录及子目录下的所有.md文件；识别出hello.md里符合规范的 YAML Front Matter（就是那三行）；解析出name、description和run字段；把run字段里的 bash 命令交给系统 shell 执行；最后把输出原样打印到终端。整个过程不联网、不上传、不依赖任何外部服务。这就是为什么它安全、可控、可审计——也是为什么越来越多的金融、科研、政企团队开始把它作为内部自动化落地的第一选择。

你不需要会写 Python，不需要部署服务器，甚至不需要知道什么是 CMake。你只需要理解两件事：第一，SKILL.md是一份有固定格式的 Markdown；第二，run字段里写的，就是你平时在 Terminal 或 Git Bash 里敲的那些命令。剩下的，WorkBuddy 全包了。接下来，我们就从零开始，把这两件事拆解透，让你不仅“能跑起来”，更清楚“为什么这样设计”、“哪里容易踩坑”、“下一步能怎么长出牙齿”。

2. Skill 的底层结构与设计逻辑：为什么必须是 SKILL.md，而不是 .py 或 .sh？

2.1 为什么不是 Python 脚本？—— 从“谁来负责调度”说起

很多新手第一反应是：“我直接写个hello.py不就行了？”——当然可以，但这就绕开了 WorkBuddy 最核心的价值：统一调度、元数据驱动、跨平台可发现性。

假设你写了hello.py，那么问题来了：

• 它怎么被 WorkBuddy “看见”？你需要额外配置一个skills.json去注册它，这又引入了新的维护成本；
• 它的描述、作者、版本、所需参数，都得硬编码在 Python 注释里，WorkBuddy 无法标准化提取；
• 如果你想在 Windows 上用 PowerShell，在 macOS 上用 zsh，在 Linux 上用 bash，你就得写三套脚本，或者加一堆判断逻辑；
• 更关键的是，wb list命令根本不会显示它——因为 WorkBuddy 的技能发现机制，只认*.md文件中的特定 YAML 结构。

而SKILL.md的设计，本质上是一次“契约式约定”。WorkBuddy 只要求你遵守一个极简协议：

--- name: hello description: 打个招呼，顺便告诉你当前时间 run: | echo "你好，我是 WorkBuddy！" date "+%Y年%m月%d日 %H:%M:%S" ---

仅此而已。WorkBuddy 的解析器会：

1. 用标准 YAML 解析器读取---之间的元数据；
2. 把run字段的内容，原封不动地交给当前系统的默认 shell（Windows 是cmd.exe或powershell.exe，macOS/Linux 是$SHELL）；
3. 把 stdout/stderr 捕获后，按需渲染（比如wb hello --json就输出 JSON，wb hello --verbose就显示执行过程）。

提示：这里run: |后面的竖线|是 YAML 的“保留换行符”语法。它意味着run字段的值是一个多行字符串，WorkBuddy 会把它当作一个完整的 bash 脚本块来执行。如果你写成run: echo "hi"，那就只能执行单行命令。绝大多数实用 Skill 都需要多行，所以|是必备写法。

2.2 为什么是 Markdown？—— 兼容性、可读性与生态延展性的三重胜利

有人会问：“YAML 本身就能存元数据，为啥非得套一层 Markdown？”答案藏在热词里：markdown编辑器、typora、chrome 查看markdown插件、markdown转word工作流。Markdown 是目前人类可读性最强、工具链最成熟、跨平台兼容性最好的轻量级文档格式。

• 对人友好：你的 Skill 文档，本身就是一份说明书。description字段是摘要，run字段下面是详细执行逻辑，你甚至可以在---下面加## 使用示例、## 注意事项、## 依赖说明等任意 Markdown 小节。团队成员不用打开 IDE，用 Typora、VS Code 或浏览器插件就能直接阅读、修改、评论。
• 对机器友好：WorkBuddy 只解析---之间的 YAML，其余部分完全忽略。这意味着你可以放心地在 Skill 文档里写中文教程、贴截图、加表格、列 TODO，WorkBuddy 视而不见，但你的同事看得清清楚楚。
• 对生态友好：.md文件天然支持 Git 版本管理、GitHub/GitLab 仓库浏览、CI/CD 流水线集成。一个 Skill 就是一个 commit，一次 PR 就是一次能力发布。你不需要学新语法，你已经在用它——写周报、写需求文档、写会议纪要，都是.md。

我见过最典型的反例，是某团队早期用.sh脚本管理 Skill。他们很快遇到三个问题：第一，./deploy.sh --help输出全是技术参数，业务同学看不懂；第二，脚本里混着大量if [ "$OSTYPE" = "darwin" ]这样的平台判断，维护成本飙升；第三，想给这个脚本加个“点击即运行”的 GUI 按钮？得额外开发 Electron 应用。而换成deploy.md后，他们只做了三件事：把帮助信息写进description，把平台差异封装进run字段的 bash 逻辑里（利用 bash 本身的跨平台能力），然后用 WorkBuddy 自带的wb ui命令一键生成 Web 控制台——所有 Skill 自动变成带表单的网页按钮。

2.3 目录结构设计：skill.md 该放在哪？agent.md 又是什么？

WorkBuddy 的 Skill 发现机制遵循一个简单规则：从当前工作目录开始，递归向上查找.workbuddy/skills/目录；如果没找到，就查找当前目录及所有子目录下的*.md文件。这意味着，你的 Skill 可以放在任何地方，但最佳实践是集中管理。

我们推荐的标准目录结构如下：

my-project/ ├── .workbuddy/ │ └── skills/ # WorkBuddy 官方推荐的集中存放点 │ ├── hello.md │ ├── git-clean.md │ └── math-model.md ├── src/ ├── docs/ └── README.md

为什么是.workbuddy/skills/？因为：

• 它被 WorkBuddy 硬编码识别，优先级最高，避免与其他.md文档冲突；
• 它是隐藏目录（开头的.），不会污染你的项目根目录；
• 它天然支持 Git 忽略（.gitignore默认包含.*），敏感 Skill（如含密钥的部署脚本）可单独配置不提交。

而agent.md，则是 Skill 的“升级版”。如果说 Skill 是“单兵作战单位”，Agent 就是“特种作战小队”。一个agent.md文件可以定义多个step，每个step调用一个已有的 Skill，并传递参数、捕获输出、做条件判断。例如：

--- name: full-deploy description: 一键完成构建、测试、部署全流程 steps: - name: build skill: build-app args: ["--env=prod"] - name: test skill: run-tests if: "{{ steps.build.exit_code == 0 }}" - name: deploy skill: deploy-to-aws if: "{{ steps.test.exit_code == 0 }}" ---

看到{{ }}了吗？这是 Go Template 语法，WorkBuddy 内置的轻量级模板引擎。它让 Agent 能基于前序 Skill 的执行结果（exit_code、stdout）做决策，实现真正的流程编排。这也是为什么热词里agent.md和skill.md总是成对出现——它们是同一套体系下的两个抽象层级。

注意：agent.md不是必须的。90% 的日常任务，一个干净的skill.md就够了。只有当你发现某个操作总是由 3 个以上 Skill 串行执行时，才值得把它升格为 Agent。过早抽象，是自动化项目失败的第一大原因。

3. 手把手实操：从新建文件到成功运行，每一步都告诉你“为什么这么写”

3.1 环境准备：确认 WorkBuddy 已安装，且 bash 可用

在开始写代码前，请先确认两件事。这不是形式主义，而是避免后续所有“command not found”类报错的根基。

第一步：检查 WorkBuddy 是否在 PATH 中打开你的终端（macOS/Linux 是 Terminal，Windows 是 Git Bash 或 PowerShell），输入：

wb --version

如果返回类似workbuddy v0.12.3的版本号，说明安装成功。如果提示command not found: wb，请立即停止，去官网下载最新二进制包（不要用pip install，WorkBuddy 是纯 Rust 编译的独立可执行文件，pip 安装的是另一个同名但无关的 Python 包）。

第二步：确认你的默认 shell 是 bash（或兼容 bash 的 shell）在终端中输入：

echo $SHELL

macOS 用户常见输出是/bin/zsh，Linux 用户多为/bin/bash，Windows Git Bash 用户是/usr/bin/bash。只要路径里包含bash或zsh，都 OK，因为它们语法高度兼容。如果你看到/bin/sh，请暂时切换：

# 临时切换（本次终端会话有效） chsh -s /bin/bash # 或者直接运行 exec bash

提示：-bash: unzip: command not found这类错误，99% 的原因是你的系统没装unzip，而不是 WorkBuddy 的问题。WorkBuddy 本身不依赖unzip，但很多 Skill（比如下载并解压模型权重）会用到它。所以建议顺手装一下：macOS 用brew install unzip，Ubuntu/Debian 用sudo apt install unzip，Windows Git Bash 用apt install unzip（Git Bash 自带 apt 包管理器）。

3.2 创建第一个 Skill：hello.md 的完整诞生过程

现在，让我们创建那个“9 分 42 秒”就能跑通的hello.md。请严格按以下步骤操作，每一个字符都不能少。

步骤 1：新建一个空文件在你习惯的目录下（比如桌面或~/Documents），用任意文本编辑器（VS Code、Typora、甚至记事本）新建一个文件。不要用 Word，不要用 WPS，必须用纯文本编辑器。将文件命名为hello.md。注意后缀名必须是.md，不能是.txt或.markdown。

步骤 2：输入标准 YAML Front Matter在文件最开头，精确输入以下三行（包括---）：

--- name: hello description: 打个招呼，顺便告诉你当前时间 run: |

解释每一行：

• 第一行---：YAML 的起始标记，WorkBuddy 一看见这个，就知道下面要读元数据了；
• name: hello：这是 Skill 的 ID，也是你在终端里敲的命令名。它必须是小写字母、数字、短横线（-）的组合，不能有空格、中文、下划线（_）；
• description:：一句话说明这个 Skill 是干什么的。它会出现在wb list的输出里，所以务必写得清晰、无歧义；
• run: |：最关键的一行。|表示后面的内容是多行字符串，WorkBuddy 会把它当 bash 脚本执行。注意|后面必须跟一个换行符，不能在同一行写命令。

步骤 3：写执行逻辑（bash 部分）在run: |下面，空一行，然后输入：

echo "你好，我是 WorkBuddy！" date "+%Y年%m月%d日 %H:%M:%S"

注意：

• echo和date前面不能有空格，必须顶格写。YAML 对缩进极其敏感，如果前面多了空格，WorkBuddy 会认为这是run字段的值的一部分，而不是独立的命令行；
• date命令里的格式字符串"+%Y年%m月%d日 %H:%M:%S"是中文本地化写法。如果你希望英文输出，可以改成"+%Y-%m-%d %H:%M:%S"；
• 这两行之间用换行分隔，不是用&&或;。WorkBuddy 会自动把它们拼成一个脚本块执行。

步骤 4：补全 YAML 结束标记在date命令之后，再空一行，输入：

---

这个---是 YAML 的结束标记。没有它，WorkBuddy 会一直往下读，直到文件末尾或遇到下一个---，导致解析失败。

最终，你的hello.md文件内容应该完全长这样（共 10 行，不多不少）：

--- name: hello description: 打个招呼，顺便告诉你当前时间 run: | echo "你好，我是 WorkBuddy！" date "+%Y年%m月%d日 %H:%M:%S" ---

注意：第 5 行和第 6 行（即echo和date）前面的两个空格，是 YAML 多行字符串的缩进要求，表示它们属于run字段的值。WorkBuddy 会自动去除这两格缩进，再执行命令。所以你看到的是缩进，实际执行时是顶格的。

3.3 运行与验证：wb hello背后发生了什么

保存hello.md文件后，回到终端，确保你当前的工作目录就是hello.md所在的目录（用pwd命令确认）。然后，输入：

wb hello

你应该立刻看到类似这样的输出：

你好，我是 WorkBuddy！ 2024年06月15日 14:23:47

恭喜，你的第一个 Skill 已经成功运行！

但别急着关终端。让我们深挖一下，wb hello这四个字符背后，WorkBuddy 到底做了什么：

1. 匹配：WorkBuddy 在当前目录及子目录中搜索所有.md文件，找到hello.md；
2. 解析：读取hello.md，用 YAML 解析器提取name、description、run字段；
3. 构造脚本：把run字段的值（即那两行 bash 命令）写入一个临时文件，比如/tmp/wb-hello-xxxxx.sh；
4. 执行：调用系统 shell（$SHELL）执行这个临时脚本；
5. 清理：脚本执行完毕后，立即删除临时文件；
6. 输出：把脚本的 stdout（标准输出）原样打印到你的终端。

这个过程全程离线，不联网，不读取你的其他文件，不写入任何全局配置。你完全可以把它想象成一个“超级智能的bash -c命令”。

为了验证这一点，你可以手动模拟一遍：

# 1. 创建临时脚本 cat > /tmp/test.sh << 'EOF' echo "你好，我是 WorkBuddy！" date "+%Y年%m月%d日 %H:%M:%S" EOF # 2. 赋予执行权限 chmod +x /tmp/test.sh # 3. 手动执行 /tmp/test.sh # 4. 清理 rm /tmp/test.sh

你会发现，输出一模一样。WorkBuddy 做的，就是把这四步自动化、标准化、并加上了元数据管理和发现能力。

4. 核心细节精讲：从语法到实战，避开新手必踩的 7 个深坑

4.1 Markdown 语法陷阱：换行、缩进、竖杠，一个都不能错

新手写SKILL.md，80% 的失败都源于 Markdown/YAML 语法的“隐形规则”。我们逐条拆解。

坑 1：run: |后面的换行是必须的错误写法：

run: | echo "hi"

正确写法：

run: | echo "hi"

原因：YAML 规范规定，|后必须紧跟一个换行符，才能开启“字面块”模式。否则，| echo "hi"会被解析成一个单行字符串| echo "hi"，WorkBuddy 会尝试执行一个叫|的命令，自然报错command not found。

坑 2：run块内的命令必须缩进，且缩进量要一致错误写法（缩进不一致）：

run: | echo "line1" echo "line2" # 这里多缩进了2格 echo "line3" # 这里没缩进，完全在 `run` 块外！

正确写法（全部顶格或全部统一缩进）：

run: | echo "line1" echo "line2" echo "line3"

原因：YAML 的缩进是语法的一部分。run字段的值，是从|后第一个换行开始，到下一个---或文件末尾为止的所有内容。但这些内容的相对缩进会被 YAML 解析器用来判断结构。不一致的缩进会导致解析器误判，把echo "line2"当作另一个字段，或者直接报could not find expected ':'错误。

坑 3：中文标点与英文标点混用错误写法：

description：打个招呼（用中文冒号和括号）

正确写法：

description: 打个招呼（用英文冒号和括号）

原因：YAML 是英文语法，只认英文标点。中文冒号：、中文引号“”、中文括号（）都会导致解析失败。这是一个极其隐蔽的坑，因为肉眼几乎看不出区别。

坑 4：markdown一段文字前面加一个竖杠的误解热词里提到的“markdown一段文字前面加一个竖杠”，其实是对>引用块的误解。在SKILL.md里，>是 Markdown 语法，WorkBuddy 会忽略它。但如果你把它误写在 YAML 区域（---之间），就会破坏 YAML 结构。例如：

--- name: hello > description: 这是错的！ run: | echo "hi" ---

这里的>会让 YAML 解析器崩溃。记住：---之间的内容，必须是纯 YAML，不能掺杂任何 Markdown。

4.2 Bash 命令实战技巧：如何写出健壮、可移植的 run 脚本

run字段里的 bash，是你 Skill 的心脏。写得好，它跨平台、高可靠；写得糙，它在同事电脑上就跑不通。以下是经过上百个真实 Skill 验证的黄金法则。

技巧 1：永远用#!/usr/bin/env bash开头（可选但强烈推荐）虽然 WorkBuddy 会用$SHELL执行，但显式声明解释器能避免某些极端环境下的兼容性问题。只需在run: |后的第一行加上：

#!/usr/bin/env bash echo "你好，我是 WorkBuddy！" date "+%Y年%m月%d日 %H:%M:%S"

/usr/bin/env bash会动态查找系统 PATH 中的第一个bash，比硬编码/bin/bash更健壮。

技巧 2：用set -euxo pipefail开启严格模式这是 Shell 脚本的“安全带”。把它加在#!/usr/bin/env bash下面：

#!/usr/bin/env bash set -euxo pipefail echo "你好，我是 WorkBuddy！" date "+%Y年%m月%d日 %H:%M:%S"

含义：

• -e：任何一条命令返回非 0 状态码（即失败），立即退出整个脚本；
• -u：引用未定义的变量时，立即报错（防止echo $UNDEFINED_VAR静默输出空行）；
• -x：打印每一条实际执行的命令（调试神器，wb hello --verbose会显示它）；
• -o pipefail：管道中任何一个命令失败，整个管道就失败（防止cmd1 | cmd2里cmd1失败了但cmd2还在跑）。

技巧 3：路径处理——永远用$(dirname "$0")获取当前 Skill 目录假设你的 Skill 需要调用同目录下的一个 Python 脚本helper.py。错误写法：

python helper.py

正确写法：

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" python "$SCRIPT_DIR/helper.py"

解释：$BASH_SOURCE[0]是当前正在执行的脚本的路径（WorkBuddy 生成的临时脚本），dirname取其目录，cd && pwd确保得到绝对路径。这样，无论你在哪个目录下运行wb hello，它都能准确定位到helper.py。这是跨项目、跨用户复用 Skill 的基石。

4.3 参数化 Skill：让 wb hello --name=张三 成为可能

静态 Skill 很酷，但真正强大的是能接收参数的 Skill。WorkBuddy 通过环境变量注入参数，这是最简单、最通用、最安全的方式。

步骤 1：在run脚本中读取环境变量修改hello.md的run部分：

#!/usr/bin/env bash set -euxo pipefail # 读取参数，提供默认值 NAME="${WB_NAME:-World}" TIME_FORMAT="${WB_TIME_FORMAT:-"+%Y年%m月%d日 %H:%M:%S"}" echo "你好，$NAME！" date "$TIME_FORMAT"

这里${WB_NAME:-World}是 bash 的参数展开语法：如果环境变量WB_NAME存在且非空，就用它的值；否则用默认值World。

步骤 2：通过wb命令传入参数现在，你可以这样运行：

# 方式1：用 --env 选项（推荐，清晰明确） wb hello --env WB_NAME=张三 --env WB_TIME_FORMAT="+%H:%M" # 方式2：用简写 -e wb hello -e WB_NAME=李四 # 方式3：在命令前设置环境变量（shell 特性） WB_NAME=王五 wb hello

所有方式效果相同。--env是最推荐的，因为它明确表达了“这是传给 Skill 的参数”，而不是影响整个 shell 会话的全局变量。

实操心得：我见过太多团队把参数名起得过于随意，比如--env user=xxx，结果和系统环境变量USER冲突，导致脚本行为诡异。WorkBuddy 官方约定：所有 Skill 参数，都用WB_前缀。这既是命名空间隔离，也是一种团队协作的契约。

5. 常见问题与排查技巧实录：那些让你抓耳挠腮的报错，其实都有迹可循

5.1 经典报错速查表：从现象到根因，一步到位

5.2 深度排查现场记录：一次真实的“math-model” Skill 故障复盘

上周，团队里一位数学建模的同学发来求助：“我的math-model.md在我电脑上好好的，发给同事，他一运行就报ModuleNotFoundError: No module named 'numpy'。”

我让他发来 Skill 文件，内容是：

--- name: math-model description: 运行数学建模脚本 run: | python src/model.py --input=data.csv ---

看起来毫无问题。但问题就出在这里——python命令。

排查过程：

1. 我让他在同事电脑上运行which python，输出是/usr/bin/python（系统自带的 Python 2.7）；
2. 而他的model.py用了f-string，这是 Python 3.6+ 的特性；
3. 再运行python --version，果然是Python 2.7.18。

根因：python命令在不同系统上指向不同版本。macOS Catalina+ 默认python指向 Python 3，但很多 Linux 发行版和旧 macOS 还是 Python 2。

解决方案（三选一）：

• 方案 A（推荐）：显式指定python3

  python3 src/model.py --input=data.csv

• 方案 B：用#!/usr/bin/env python3+chmod +x，然后直接执行脚本

  chmod +x src/model.py src/model.py --input=data.csv

• 方案 C：在 Skill 文档里加依赖检查

  #!/usr/bin/env bash set -euxo pipefail python3 --version || { echo "错误：请安装 Python 3"; exit 1; } python3 src/model.py --input=data.csv

这件事教会我们一个铁律：所有 Skill，都必须声明其运行时依赖，且依赖声明要具体到版本号。我们在math-model.md的---下面，新增了一节：

## 依赖说明 - Python >= 3.8 - numpy >= 1.21.0 - pandas >= 1.3.0

并在run脚本开头，加入版本检查。从此，再没人因为环境差异而卡住。

5.3 高级避坑技巧：关于cmake执行bash命令和codebuddy和workbuddy区别的真相

热词里频繁出现cmake执行bash命令，这其实是个美丽的误会。CMake 是一个构建系统，它的execute_process命令确实可以执行 bash，但那是为 C++ 项目服务的。WorkBuddy 的 Skill 机制，是完全独立于 CMake 的另一套体系。你不需要、也不应该在SKILL.md里写 CMake 语法。WorkBuddy 的run字段，就是 bash，仅此而已。

至于codebuddy和workbuddy区别，这是社区里一个长期存在的混淆。CodeBuddy 是一个已停止维护的、基于 Node.js 的旧项目，它用package.json定义命令。WorkBuddy 是它的精神继承者，但用 Rust 重写，核心理念从“代码助手”升级为“工作流引擎”，SKILL.md就是它最鲜明的旗帜。如果你在网上搜到 CodeBuddy 的教程，请果断忽略，它们对 WorkBuddy 完全不适用。

最后分享一个独家技巧：如何快速克隆一个成熟的 Skill？
WorkBuddy 官方 GitHub 仓库（https://github.com/workbuddy-org/skills）里，有一个examples/目录，里面全是经过生产环境验证的 Skill 模板：git-commit.md、docker-build.md、pdf-merge.md。你不需要从零开始，curl -O https://raw.githubusercontent.com/workbuddy-org/skills/main/examples/git-commit.md下载一个，然后sed -i 's/git-commit/your-skill-name/g' your-skill-name.md替换名字，再根据你的需求修改run部分——5 分钟，一个工业级 Skill 就诞生了。这才是真正的“从 0 到 1”。

我在实际使用中发现，最高效的 Skill 开发节奏是：先用wb hello验证环境，再找一个功能相近的官方例子curl下来，最后只改run里的 3 行核心命令。这样，你 90% 的时间都在思考“我要做什么”，而不是“语法怎么写”。这才是自动化该有的样子。