Appearance
AI 开发工具链：Skill 系统
定位：CodeBuddy 的领域知识扩展层，让 AI 从「懂代码」进化到「懂你的项目」。 配套视频：本文档与《Skill 系统实战》两期视频配套使用——视频建立认知，手册提供可复制模板与完整案例。
一、痛点：AI 懂代码，但不懂你的项目
你有没有遇到过这种情况？
你跟 AI 说：帮我部署一下小程序。AI 回你一连串问题：用什么命令？部署到服务器还是 COS？后端要不要一起部署？数据库迁移做了吗？
它懂代码，但它不懂你的项目。
每次对话都像带一个新员工——先科普一遍项目结构、部署方式、服务器地址，才能进入正题。
Skill 系统解决的就是这个问题：把项目的领域知识、操作规范、安全底线，写成结构化的 Markdown 文件，让 AI 自带项目记忆。
你说「部署小程序」，它直接知道：H5 用 coscmd 上传到 COS，后端用 deploy.sh，数据库迁移不能跳过。
二、架构：三层知识系统
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 域。
3.1 目录结构
.codebuddy/skills/chenyue/deploy/
├── DOMAIN.md ← 领域知识
├── 33-本地测试与服务器部署标准流程.md ← 原始文档
├── 61-部署规范书.md ← 原始文档
├── 62-H5部署操作手册.md ← 原始文档
└── tools/
├── ssh.yaml ← SSH 远程部署
├── cos.yaml ← COS 上传
├── alembic.yaml ← 数据库迁移
└── workflows/
└── full-deploy.yaml ← 端到端编排3.2 DOMAIN.md 核心内容
关键配置表
AI 不需要猜，全部写死：
| 配置项 | 值 |
|---|---|
| SSH 别名 | chenyue-prod → ubuntu@82.157.100.51 |
| SSH 密钥 | ~/.ssh/chenyue_prod |
| 生产域名 | chenyueinnokeji.com |
| 后端 systemd 服务 | linda-platform (端口 8000) |
| 服务器项目路径 | /home/ubuntu/apps/linda-coze |
| 服务器后端目录 | /home/ubuntu/apps/linda-coze/linda-platform |
| COS bucket | chenyuekeji-1301744011 (ap-guangzhou) |
| coscmd 路径 | /Users/linda/Library/Python/3.9/bin/coscmd |
部署决策树
改动了哪个模块，用什么方式部署——一张表说清楚：
| 改动模块 | 部署方式 | 执行位置 |
|---|---|---|
chenyue-platform/ (后端) | ./deploy.sh | ssh chenyue-prod |
goods-admin/ (好物后台) | deploy.sh 第 4 步 或 本地 deploy-frontend.sh | SSH 或本地 |
chenyue-admin/ (管理后台) | deploy.sh 第 5 步 | ssh chenyue-prod |
chenyue-app/ (H5 前端) | deploy-frontend.sh 或手动 coscmd | 本地 Mac |
chenyue-app/ (小程序) | 微信开发者工具上传 | 微信开发者工具 |
部署原则
- 代码部署 ≠ 数据迁移 — 两者分开处理
- 备份先行 — 任何操作前必须备份数据库（deploy.sh 自动完成）
- 可回滚 — 部署前打 Git Tag
- 密钥隔离 —
.env不进 Git
严禁操作
AI 不仅知道怎么做，还知道什么绝对不能做：
- ❌ 不要修改服务器上的
.env文件（除非用户明确要求） - ❌ 不要执行
alembic downgrade（除非用户明确要求回滚） - ❌ 不要在部署失败时清数据库、删文件或
git reset --hard - ❌ 不要提交
.env或包含密钥的文件到 Git - ❌ 不要跳过
alembic upgrade head（新表结构必须执行迁移）
这些严禁操作与
common/confirmation.md的二次确认规则联动。高风险操作（删数据、改生产配置）会触发确认模板，AI 会停下来等用户说「确认」才执行。
3.3 tools/ssh.yaml 完整解读
这不是一段写死的命令，是一个带检查、带异常处理的完整流程：
yaml
# SSH 远程部署
用途：通过 SSH 连接服务器，执行 deploy.sh 完成后端 + 管理后台部署。
## 前置条件
- 本地 `~/.ssh/config` 已配置 `chenyue-prod` 别名
- 密钥 `~/.ssh/chenyue_prod` 可用
- 代码已 `git commit && git push origin master`
## 参数
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| dry_run | bool | 否 | 仅检查连通性，不执行部署（默认 false） |
## 执行步骤
### 步骤 1：连通性检查
```bash
ssh chenyue-prod "echo 'SSH OK' && cd /home/ubuntu/apps/linda-coze && pwd && git status --short | head -5"
```
### 步骤 2：执行一键部署
```bash
ssh chenyue-prod "cd /home/ubuntu/apps/linda-coze && ./deploy.sh"
```
deploy.sh 自动执行：
0. 备份数据库 `chenyue_prod.db`
1. `git pull origin master`
2. `pip install -r requirements.txt` + `alembic upgrade head`
3. `sudo systemctl restart linda-platform` + 健康检查
4. `cd goods-admin && npm run build`
5. `cd chenyue-admin && npm run build`
6. 跳过 chenyue-flow-admin（项目暂停）
7. 更新 Nginx 配置（端口隔离方案）
8. `sudo nginx -t && sudo systemctl reload nginx`
9. 部署后冒烟检查（8000 生产 + 8001 测试）
### 步骤 3：部署后验证
```bash
# 后端健康检查
ssh chenyue-prod "curl -s http://localhost:8000/health"
# 预期: {"code":0,"data":{"status":"ok","database":"ok"}}
# 线上端点
curl -s https://chenyueinnokeji.com/health | python3 -m json.tool
```
## 异常处理
### SSH 连不上
```bash
ssh -i ~/.ssh/chenyue_prod ubuntu@82.157.100.51 "echo OK"
```
### deploy.sh 卡住
不要盲目重试。逐步执行排查：
```bash
ssh chenyue-prod "cd /home/ubuntu/apps/linda-coze && git pull origin master"
ssh chenyue-prod "cd /home/ubuntu/apps/linda-coze/linda-platform && source .venv/bin/activate && pip install -r requirements.txt -q && alembic upgrade head"
ssh chenyue-prod "sudo systemctl restart linda-platform && sleep 3 && curl -s http://localhost:8000/health"
```
### 后端启动失败
```bash
ssh chenyue-prod "journalctl -u linda-platform -n 50 --no-pager"
```
### Nginx 配置报错
```bash
ssh chenyue-prod "sudo nginx -t"
```设计要点解析：
- 前置条件：告诉 AI 执行前要检查什么，不会盲目操作
- dry_run 参数：支持仅检查不执行，适合演练
- 分步骤：每一步有明确输入输出，便于排查
- 异常处理：不是「失败了告诉我」，而是「失败了按这个步骤排查」
四、动手实战：写一个最小 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 里写明：后端用 deploy.sh，H5 用 coscmd，小程序用微信工具知识可复用，维护一份就行。
5.2 知识写「刚好够用」
AI 不需要知道项目的历史沿革，它只需要知道「现在怎么操作、有什么禁忌」。
| 写太多 | 写刚好 |
|---|---|
| 项目 2022 年为什么选 FastAPI | FastAPI 版本要求、启动命令、常用调试方式 |
| 团队组织架构和汇报关系 | 这个域的职责边界和对接人 |
| 技术选型的完整论证过程 | 当前技术栈和关键配置 |
保留行动所需的最小信息集。
5.3 Skill 和代码一起变
Skill 不是写一次就忘的文档，它和代码一样需要维护。
推荐做法：
- PR 改了数据库结构 → 同步改
DOMAIN.md的表结构说明 - 改了构建命令 → 同步改
tools/*.yaml - 新增了一个部署方式 → 同步改
DOMAIN.md决策树 - 把「Skill 维护」加入 Code Review checklist
六、9 域速查表
| 域 | 覆盖项目 | 触发词示例 | 能做什么 |
|---|---|---|---|
| deploy | platform / app / admin / official-web | 部署、上线、发布 | SSH 部署、COS 上传、数据库迁移、Nginx 配置 |
| develop | 全项目 | 开发、运行、调试、npm/pip | 环境初始化、启动命令、编码规范、MCP 配置 |
| ops | platform（服务器） | 服务器、数据库、日志、备份 | 状态查询、日志排查、定时任务 |
| review | 全项目 | review、代码审查、安全 | S 级模块审查清单、安全审计 |
| product | product / official-web | 产品、课程、方法论、SDAD | 手册结构、官网内容、转型路径 |
| app | app | 小程序、场景、uni-app | 5 场景切换、分包结构、设计 Token、真机预览 |
| admin | admin / flow-admin / goods-admin | 后台、编排、好物 | 构建命令、COS 路径、框架差异 |
| diagram | diagram | 课图、手绘、模板、PNG | 5 模板映射、AI 生成→渲染→嵌入手册 |
| platform | platform | API、路由、Agent、RAG、模型 | 200+ 模块全景、10 层架构、对话链路 |
七、配套视频
- 视频①：《Skill 系统实战（上）》— 为什么需要 Skill，解剖 deploy 域完整设计
- 视频②：《Skill 系统实战（下）》— 动手写一个最小 Skill，三个设计原则
视频建立认知和方法，本文档提供完整案例和可复制模板。建议先看完视频，再对照本文档查阅细节。
八、与工程文档的关系
| 层 | 路径 | 给谁看 | 用途 |
|---|---|---|---|
| Skill | .codebuddy/skills/chenyue/ | AI 读取 | 执行操作，路由请求 |
| 工程文档 | docs/ | 人类+AI | 完整设计、面试、架构 |
| 产品手册 | chenyue-product/docs/ | 人类 | 浏览层，转型路径+案例 |
Skill 是对工程文档的执行层提炼——保留行动所需的知识，去掉背景论述。原始文档保留在 docs/ 中，Skill 负责让 AI 能正确执行。