Appearance
AI 开发工具链：Skill 系统
定位：CodeBuddy 的领域知识扩展层，让 AI 从「懂代码」进化到「懂你的项目」。 配套视频：本文档与《Skill 系统实战》两期视频配套使用——视频建立认知，手册提供可复制模板与完整案例。
一、痛点：AI 懂代码，但不懂你的项目
你有没有遇到过这种情况？
你跟 AI 说：帮我部署一下小程序。AI 回你一连串问题：用什么命令？部署到服务器还是 COS？后端要不要一起部署？数据库迁移做了吗？
它懂代码，但它不懂你的项目。
每次对话都像带一个新员工——先科普一遍项目结构、部署方式、服务器地址，才能进入正题。
Skill 系统解决的就是这个问题：把项目的领域知识、操作规范、安全底线，写成结构化的 Markdown 文件，让 AI 自带项目记忆。
你说「部署小程序」，它直接知道：H5 走对象存储上传，后端走标准部署脚本，数据库迁移不能跳过。
二、架构：三层知识系统
Skill 不是高级 Prompt，它是三层知识系统：
用户提问
↓
L0 总分诊（SKILL.md） ← 关键词 → 域路由
↓
Domain 领域知识（DOMAIN.md） ← 该域的完整规范
↓
Tools 可执行工具（*.yaml） ← 带检查、带异常处理的流程
↓
执行结果| 层级 | 类比 | 文件 | 职责 |
|---|---|---|---|
| L0 总分诊 | 医院导诊台 | SKILL.md | 关键词匹配 → 路由到对应域 |
| Domain | 专科医生知识 | DOMAIN.md | 架构、规范、操作流程、严禁事项 |
| Tools | 处方单 | tools/*.yaml | 可执行命令 + 前置检查 + 异常处理 |
2.1 L0 总分诊：关键词路由
SKILL.md 是一张关键词路由表，把用户的自然语言翻译为「挂哪个科」。
示例：
| 关键词 | 路由到 | 覆盖场景 |
|---|---|---|
| 部署、上线、发布、deploy、publish、ship | deploy/ | 代码发布到服务器或 COS |
| 开发、编码、运行、调试、npm、pip | develop/ | 本地开发环境操作 |
| 服务器、数据库、日志、备份 | ops/ | 生产环境运维 |
| review、审查、安全 | review/ | 代码审查与安全审计 |
| 产品、课程、方法论、SDAD | product/ | 产品体系与实践手册 |
| 小程序、H5、uni-app、场景 | app/ | 小程序多场景开发 |
| 后台、admin、编排、flow | admin/ | 3 个管理后台 |
| 课图、diagram、手绘、模板 | diagram/ | 课图生成器 |
| 后端、API、FastAPI、Agent、RAG | platform/ | 后端核心 200+ 模块 |
设计要点：同义词要兜住。「部署」「上线」「publish」「ship」指向同一个域，用户怎么说 AI 都不会迷路。
2.2 Domain：领域知识
DOMAIN.md 是该域的「诊断规范」，回答三个问题：
- 这个域管什么？ —— 职责边界
- 怎么操作？ —— 配置、决策树、流程
- 什么不能做？ —— 严禁操作、安全底线
2.3 Tools：可执行工具
tools/*.yaml 是「处方单」，不是写死的命令，而是：
- 有前置检查（SSH 通不通？配置对不对？）
- 有异常处理（卡住了怎么排查？失败了怎么回滚？）
- 有参数化（文件路径、环境变量用占位符，换项目改一行就行）
三、案例解剖：deploy 域设计（脱敏示例）
不空讲概念，用 deploy 域的结构 说明 Skill 怎么写。以下为公开版示例——真实 IP、SSH、服务器路径等运维细节仅保留在仓库内 .codebuddy/skills/（不对外发布）。
3.1 目录结构
.codebuddy/skills/<your-project>/deploy/
├── DOMAIN.md ← 领域知识（配置表、决策树、严禁操作）
├── tools/
│ ├── ssh.yaml ← 远程部署（占位符，不含真实地址）
│ ├── cos.yaml ← 静态资源上传
│ ├── alembic.yaml ← 数据库迁移
│ └── workflows/
│ └── full-deploy.yaml3.2 DOMAIN.md 应写什么
关键配置表（用占位符，勿写生产真值）
| 配置项 | 公开文档示例 | 说明 |
|---|---|---|
| SSH 别名 | <your-ssh-alias> | 写在本地 ~/.ssh/config，勿写 IP |
| 生产域名 | <your-domain.com> | 仅域名，无账号密码 |
| 后端服务名 | <your-systemd-service> | systemd 单元名 |
| 对象存储 | <your-bucket> / <region> | bucket 与地域，勿写密钥 |
| 项目根路径 | <server-app-path> | 服务器目录用占位符 |
部署决策树（模块 → 方式）
| 改动模块 | 部署方式 | 执行位置 |
|---|---|---|
| 后端 API | 标准部署脚本 | SSH 或 CI |
| 管理后台 | 构建 + 同步静态资源 | SSH 或 CI |
| H5 / 小程序 | 构建后上传对象存储 / 开发者工具 | 本地或 CI |
部署原则
- 代码部署 ≠ 数据迁移 — 两者分开处理
- 备份先行 — 生产库操作前必须备份
- 可回滚 — 部署前打 Git Tag
- 密钥隔离 —
.env、SSH 私钥不进 Git、不进公开文档
严禁操作
- ❌ 不要在公开文档或对话中粘贴生产 IP、SSH 密钥、
.env内容 - ❌ 不要修改生产
.env（除非授权且二次确认） - ❌ 不要执行
alembic downgrade（除非明确回滚且已备份） - ❌ 不要在部署失败时清数据库、删文件或
git reset --hard - ❌ 不要跳过
alembic upgrade head（有新迁移时必须执行）
3.3 tools/*.yaml 写法要点
公开文档只展示结构，不粘贴可直连生产的命令。Tool 文件应包含：
- 前置条件（SSH 别名已配置、代码已 push 等）
- 参数（如
dry_run） - 分步命令（用
{ssh_alias}、{app_path}等占位符） - 异常处理（连不上、脚本卡住、服务起不来时的排查思路）
示例（脱敏）：
yaml
# deploy/tools/ssh.yaml（结构示例 — 非生产命令）
用途：通过 SSH 执行远程部署脚本。
## 前置条件
- 本地已配置 SSH 别名 `{ssh_alias}`（私钥路径仅写在本机，不进文档）
- 代码已合并并 push 到主分支
## 执行步骤
### 步骤 1：连通性检查
ssh {ssh_alias} "echo OK && cd {app_path} && pwd"
### 步骤 2：执行部署脚本
ssh {ssh_alias} "cd {app_path} && ./scripts/deploy.sh"
### 步骤 3：健康检查
curl -s https://{your-domain}/health
## 异常处理
- SSH 失败 → 检查本机 `~/.ssh/config` 与密钥权限
- 部署卡住 → 分步执行 pull / migrate / restart，查服务日志
- 健康检查失败 → 查应用日志与反向代理配置设计要点：AI 读的是结构与禁忌；真实主机名、IP、路径放在仓库内 Skill 或密码管理器，不进入 VitePress 公网构建。
四、动手实战：写一个最小 Skill
看完案例，自己动手。三步搞定一个代码审查 Skill。
4.1 第一步：建目录
bash
mkdir -p .codebuddy/skills/my-project/review/tools4.2 第二步：写 DOMAIN.md
markdown
# 代码审查领域
> 对项目中的 S 级模块做安全与质量审查。
## S 级模块清单
以下模块涉及资金安全、用户隐私或核心权限，必须审查：
- 支付相关（payment/、order/、wallet/）
- 用户权限（auth/、role/、permission/）
- 数据导出（export/、report/）
## 审查要点
1. **输入校验**：所有外部输入是否做了类型校验和长度限制？
2. **敏感信息**：是否有密码、密钥、Token 硬编码在代码中？
3. **权限控制**：接口是否有身份验证？敏感操作是否有权限检查？
4. **SQL 注入**：拼接 SQL 的地方是否用了参数化查询？
## 输出格式
审查结果按以下结构输出：【审查文件】xxx.py 【风险等级】🔴 高 / 🟡 中 / 🟢 低 【问题描述】... 【修复建议】...
4.3 第三步：写 Tool
yaml
# review/tools/security-check.yaml
name: security-check
description: 对指定文件做安全检查，扫描硬编码密钥和常见风险
## 参数
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| file | string | 是 | 要审查的文件路径 |
## 执行步骤
### 步骤 1：检查文件是否存在
```bash
test -f {file} && echo "文件存在" || echo "文件不存在: {file}"
```
### 步骤 2：扫描硬编码密钥
```bash
grep -n -E "(password|secret|token|api_key|private_key)\\s*[=:]\\s*[\"'][^\"']{8,}" {file} || echo "未发现明显硬编码"
```
### 步骤 3：检查 SQL 拼接
```bash
grep -n -E "(execute|query)\\s*\\(\\s*['\"].*%s" {file} || echo "未发现 SQL 拼接"
```4.4 第四步：加路由
在 SKILL.md 中加一行：
markdown
| review、审查、安全、代码检查 | `review/` | 代码审查与安全审计 |4.5 测试
在 CodeBuddy 中输入：
review 一下 payment.py
AI 应该：
- 匹配到
review/域 - 读 DOMAIN.md，知道 payment 是 S 级模块
- 调用 security-check.yaml
- 输出审查结果
五、设计原则
5.1 按职能切域，不按项目切
❌ 不要每个项目建一个 deploy：
❌ project-a/deploy/
❌ project-b/deploy/✅ 一个 deploy 管所有项目的部署：
✅ deploy/DOMAIN.md 里写明：后端用部署脚本，H5 用对象存储，小程序用开发者工具知识可复用，维护一份就行。
5.2 知识写「刚好够用」
AI 不需要知道项目的历史沿革，它只需要知道「现在怎么操作、有什么禁忌」。
| 写太多 | 写刚好 |
|---|---|
| 项目 2022 年为什么选 FastAPI | FastAPI 版本要求、启动命令、常用调试方式 |
| 团队组织架构和汇报关系 | 这个域的职责边界和对接人 |
| 技术选型的完整论证过程 | 当前技术栈和关键配置 |
保留行动所需的最小信息集。
5.3 Skill 和代码一起变
Skill 不是写一次就忘的文档，它和代码一样需要维护。
推荐做法：
- PR 改了数据库结构 → 同步改
DOMAIN.md的表结构说明 - 改了构建命令 → 同步改
tools/*.yaml - 新增了一个部署方式 → 同步改
DOMAIN.md决策树 - 把「Skill 维护」加入 Code Review checklist
六、9 域速查表
| 域 | 覆盖项目 | 触发词示例 | 能做什么 |
|---|---|---|---|
| deploy | 各子项目 | 部署、上线、发布 | 远程部署、静态资源上传、数据库迁移（细节见内网 Skill） |
| develop | 全项目 | 开发、运行、调试、npm/pip | 环境初始化、启动命令、编码规范、MCP 配置 |
| ops | 后端服务 | 服务器、数据库、日志、备份 | 状态查询、日志排查（生产细节不进公开文档） |
| review | 全项目 | review、代码审查、安全 | S 级模块审查清单、安全审计 |
| product | product / official-web | 产品、课程、方法论、SDAD | 手册结构、官网内容、转型路径 |
| app | app | 小程序、场景、uni-app | 5 场景切换、分包结构、设计 Token、真机预览 |
| admin | 各管理后台 | 后台、编排 | 构建命令、发布流程（路径见内网 Skill） |
| diagram | diagram | 课图、手绘、模板、PNG | 5 模板映射、AI 生成→渲染→嵌入手册 |
| platform | platform | API、路由、Agent、RAG、模型 | 200+ 模块全景、10 层架构、对话链路 |
七、配套视频
- 视频①：《Skill 系统实战（上）》— 为什么需要 Skill，解剖 deploy 域完整设计
- 视频②：《Skill 系统实战（下）》— 动手写一个最小 Skill，三个设计原则
视频建立认知和方法，本文档提供完整案例和可复制模板。建议先看完视频，再对照本文档查阅细节。
八、与工程文档的关系
| 层 | 位置 | 给谁看 | 用途 |
|---|---|---|---|
| Skill（完整版） | 仓库内 .codebuddy/skills/ | 本机 AI / 团队 | 含部署细节，不进入公网文档站构建 |
| Skill（公开版） | 本站 engineering/skill-system | 学员 / 读者 | 方法论与结构示例，已脱敏 |
| 工程文档 | 仓库根 docs/ | 团队内 | 完整设计、面试、架构 |
| 产品手册 | chenyue-product/docs/ | 公网浏览 | 转型路径、案例、编排说明 |
公开文档只保留「能自学的方法」；运维真值、支付方案、内部目录索引等通过 srcExclude 排除在 VitePress 生产构建之外。