2026-01-09 15:00:00

做一个有温度和有干货的技术分享作者 —— Qborfy

一、概述

CodeBuddy 是腾讯面向开发者的基于 AI 大模型，提供代码生成补全、技术问答、智能代码评审、单测生成等能力，结合 Spec Kit（规范套件） 与 AI 能力，旨在通过“规范驱动+智能辅助”的模式，帮助团队统一代码风格、规避常见错误、提升开发效率。本指南将详细介绍从环境准备到日常开发的全流程操作，涵盖规范定义、AI 辅助编码、自动化检查与修复等核心场景。

1.1 Spec 是什么

传统开发 vs Spec-Driven 开发
很多开发者开始一个项目时是这样的流程：

💭 “嗯，我想要一个标签管理工具…”
💻 “开始写代码吧，边写边想”
🤖 “AI，帮我生成一个 React 组件…”
🐛 “等等，这个需求没想清楚啊”
🔄 “改需求、改代码、来回折腾…”
😫 “代码越来越乱，难以维护”

Spec-Driven 开发 的思路则完全不同：
💭 “我的问题是什么？我想要的真实需求是什么？”
📝 “写一份清晰的 Spec（规格书），定义问题的边界”
🤖 “基于 Spec，让 AI 精准理解需求并生成代码”
✅ “代码与 Spec 完全对齐，清晰可维护”

是什么？

Spec（规格） 简单来说，就是在开始编码前，用结构化的文档明确定义：

1. 问题是什么: 用户的真实需求和痛点
2. 解决方案长什么样: 功能描述、交互流程、数据模型
3. 怎样判断成功: 验收标准和成功指标
4. 有哪些约束: 技术限制、性能要求、安全规范

一个好的 Spec 应该包含：

参考例子说明

❌ 没有 Spec，你可能这样 Prompt

1

"给我写个 Chrome 扩展，能管理标签页，要好看"

✅ 有 Spec，你可以这样 Prompt：

1. “根据 spec.md，实现 TabList 组件，要求：- 显示 Tab[] 数组
2. 支持虚拟滚动（超过 50 个标签时）
3. 点击时调用 onTabClick 回调
4. 按打开时间降序排列”
5. …

二、快速开始

2.1 环境要求

• 操作系统：macOS 10.15+/Windows 10+/Linux (Ubuntu 20.04+)
• Node.js 版本：≥20.0.0
• 包管理器：npm/yarn/pnpm（任选其一）
• Python 版本：≥3.12

Nodejs 版本 nvm 安装操作命令：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Mac ｜ Linux安装命令
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

# Windows 上安装 NVM，可以通过 GitHub https://github.com/coreybutler/nvm-windows/releases 下载 nvm-setup.exe 文件

# 验证是否安装成功
nvm version

# 使用 nvm安装  node20+版本
nvm install v20.19.0
# 设置别名
nvm alias ai v20.19.0
# 设置为当前node版本
nvm use ai

Python 版本管理器 uv 安装操作命令

1
2
3
4
5
6
7
8
9
10

# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# With pip.
pip install uv
# 验证
uv help

2.2 安装 codebuddy-code

官方文档：https://www.codebuddy.ai/cli codebuddy 外网版（内网版有点问题，推荐使用外网版）

通过 npm 全局安装（推荐）：

1
2
3
4
5
6
7
8

npm install -g @tencent-ai/codebuddy-code

# 验证安装成功：

# 输入 codebuddy 启动 CodeBuddy 触发登录验证，后续按照操作选择 iOA步骤即可
codebuddy

# 选择认证方式就可以了进入使用啦

2.3 安装 spec-kit(首次初始化项目使用)

spec 官方 github: https://github.com/github/spec-kit

1
2
3
4
5
6

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
# 验证安装成功
specify --help

# 初始化项目 主要是把后续几个主要指令放入到.codebuddy 中
specify init --ai=codebuddy

2.4 配置 Codebuddy 语言偏好

CODEBUDDY.md 放在长期记忆的开头，项目特有的在后边追加（项目/CODEBUDDY.md）

如果同时在用 Codebuddy IDE 则 CODEBUDDY.md 可以放在自己的项目 rules 中，共享 CodebuddyCode 的长期记忆（.codebuddy/.rules）。

具体内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13

# 指令集(Instructions)

## 语言偏好（Language Preference）

**重要提示：** 之后所有沟通（包括代码注释和解释）都请使用中文。

## 命令约束

**重要提示：** 当进行/speckit.\* 命令时，都需要将本文件内作为基础对话认识

## 咨询

**重要提示：** 当对项目内业务有疑问时优先在本文件中查询，如果没有找到相关内容，或指出错误，则根据代码调研并且向研发人员确认，确认后应当更新本文件

2.5 初始化项目 Spec 规范

进入你的项目根目录，运行初始化命令：

1
2
3

cd /path/to/your-project
# 初始化项目
specify init .

第一次运行可能会出现错误：

解决方案就是前往 Github 申请令牌：

https://github.com/settings/personal-access-tokens

1. 获取 token 声明到全局变量中：

1
2
3
4
5
6
7

# Mac | Linux进行导入配置变量，其中/root/.bashrc 为 Linux 系统本机的变量位置，如在 Mac 安装，默认地址为 ~/\.zshrc  或 ~/\.bashrc
export GH_TOKEN='<github-token>' & export GITHUB_TOKEN="$GH_TOKEN" >> root/\.bashrc

source  /root/.bashrc

# Windows
可以通过我的电脑 → 系统属性 → 高级系统设置 → 环境变量

2. 可以在命令后添加参数 –github-token=xxx

1

specify init . --ai codebuddy --github-token=<KEY>

完成初始化后，会在项目根目录生成 .specify和.codebuddy目录，具体如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

.codebuddy/
└── commands/ # 包含AI辅助开发的各种命令工具
    ├── speckit.analyze.md          # 跨工件一致性分析命令
    ├── speckit.checklist.md        # 检查清单生成命令
    ├── speckit.clarify.md          # 需求澄清命令
    ├── speckit.constitution.md     # 宪法管理命令
    ├── speckit.implement.md        # 实现命令
    ├── speckit.plan.md             # 计划制定命令
    ├── speckit.specify.md          # 规范制定命令
    ├── speckit.tasks.md            # 任务生成命令
    └── speckit.taskstoissues.md    # 任务转问题命令

.specify/ # 项目规范化和自动化工具集
├── memory/
│   └── constitution.md             # 项目宪法文件
├── scripts/
│   └── bash/
│       ├── check-prerequisites.sh  # 检查先决条件脚本
│       ├── common.sh               # 通用脚本函数
│       ├── create-new-feature.sh   # 创建新特性脚本
│       ├── setup-plan.sh           # 设置计划脚本
│       └── update-agent-context.sh # 更新代理上下文脚本
└── templates/
    ├── agent-file-template.md      # 代理文件模板
    ├── checklist-template.md       # 检查清单模板
    ├── plan-template.md            # 计划模板
    ├── spec-template.md            # 规范模板
    └── tasks-template.md           # 任务模板

三、speckit 规范 AI 编程全流程

3.1 完整的 speckit 开发流程

以上步骤可以多次执行，如：

• /speckit.constitution 可以针对项目，多次调整定义开发规范。
• /speckit.specify 针对需求我们可以多次调整，直到生成的 spec.md 符合我们需求。
• /speckit.plan 可以查看生成 plan.md 调整生成技术实现方案。
• …等等

3.2 定义宪章 /speckit.constitution

宪章是项目的架构原则和约束的集合。它在整个开发过程中起到”守门员”的作用，确保所有设计决策都符合核心原则。

操作步骤
启动 codebuddy ，输入/speckit.constitution 这是一个xxx项目，主要使用技术栈为xxx ，具体如下图：

不同技术栈生成项目宪章是不一样，但主要包含以下内容：

• 项目主要技术栈
• 项目主要规范和约束
• 项目主要测试策略
• 其他一些约定规范等等

3.3 需求设计(/speckit.specify)和需求澄清(/speckit.clarify)

需求设计与澄清解决最大的问题：在开发设计前消除歧义与认知偏差，避免“带猜测”进入 /plan 导致返工。

需求设计(/speckit.specify)

需求设计工作过程：

• 用户输入初步需求内容 /speckit.specify 需要实现一个xxx内容 ， 需求内容越仔细，AI 对此的疑问就越少。
• Spec 会根据需求生成“疑问列表”：模糊术语、未量化指标、冲突需求、缺失边界
• 让用户回答疑问列表，进行交互式问答（可能循环多轮）
• 记录决策与补充说明（形成“澄清日志”）

参考例子：

• 模糊指标 → 转化为量化：例如“高性能”→“P95 响应 < 300ms”。
• 冲突：Story A 说“匿名可用”，Story B 要求“强制登录”。
• 依赖外部系统 SLA 未说明。
• 安全责任归属不清。

下面实际操作，具体如下图：

需求澄清 (/speckit.clarify)

这里需求澄清 ≈ 需求评审，如果没有需求澄清那么开发流程如下：

1
2
3

❌ 开发者猜测 → 实现 A 版本
❌ 产品验收 → "这不是我想要的"
❌ 返工修改 → 浪费时间和资源

1
2
3

1 ❌ 开发者猜测 → 实现 A 版本
2 ❌ 产品验收 → "这不是我想要的"
3 ❌ 返工修改 → 浪费时间和资源

如果有需求澄清，那么就会这样子：

1
2
3

1 ✅ 结构化提问 → 明确所有歧义点
2 ✅ Q&A 记录 → 形成 Clarifications 文档
3 ✅ 减少返工 → 编码前统一认知

举例子说明：

输入模糊需求：”我需要新增一个页面去展示 tko 特有的域名列表”

Speckit 自动识别模糊点，并生成结构化的澄清问题。你逐一回答这些问题。

经过需求设计与澄清，我们就得到了一个清晰的需求文档，大概如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Feature Specification: TKO域名列表展示页面

**Feature Branch**: `001-tko-domain-list-page`
**Created**: 2025-12-01
**Status**: Draft
**Input**: User description: "需要新增一个页面去展示 tko特有的域名列表"

## Clarifications

### Session 2025-12-01

- Q: TKO域名的业务含义和数据结构定义是什么？ → A: TKO域名是指特定业务场景下使用的专有域名集合，需要明确的业务定义和数据结构
- Q: 域名数据的获取方式和来源是什么？ → A: 静态配置文件中定义域名列表，适合数据不经常变更的场景
......

这里会把需求澄清中所有内容都记录起来，如果你需要需求澄清过程越短，那么你在描述需求的时候，需求内容越清晰越好。

3.4 技术方案设计(/speckit.plan)

这一步主要把需求澄清好的内容拆分一个完整可以实现的技术方案，类似：从产品思维向工程思维的转换。

这一步会生成多个文件，具体说明如下：

1
2
3
4
5

specs/001-tko-domain-list-page/
├── plan.md                 # 总体实施计划
├── research.md             # 技术调研报告 包含针对项目特定技术栈的深度研究
├── data-model.md           # 数据模型设计 定义项目的核心数据结构
└── quickstart.md           # 开发快速入门 给开发者提供即用的指引

具体可以看其产出内容specs/001-tko-domain-list-page/plan.md：

1
2
3
4
5
6
7
8
9
10
11
12

# Implementation Plan: TKO域名列表展示页面

**Branch**: `001-tko-domain-list-page` | **Date**: 2025-12-01 | **Spec**: /specs/001-tko-domain-list-page/spec.md
**Input**: Feature specification from `/specs/001-tko-domain-list-page/spec.md`

**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.

## Summary

基于功能规格要求，TKO域名列表展示页面将采用Vue 3 + Ant Design Vue技术栈，使用静态配置文件存储域名数据，提供公开访问的域名列表展示、详情查看和搜索筛选功能。页面将支持多语言、环境过滤，并通过虚拟滚动和分页策略处理大规模数据展示。
....

3.5 生成任务清单 (/speckit.tasks)

这一步会根据前面的设计和规划，生成详细的开发任务清单，帮助团队高效地推进项目实施。

这一步其实也是开发中必不可少的部分，就是把技术方案拆成一个个可以真正实现的子任务。

因为从一个几百甚至上千行行的技术方案，如果没有一个可以真正实现的任务列表，AI 大模型陷入实现混乱。

具体可以看其产出内容tasks/001-tko-domain-list-page/tasks.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

......

## Phase 1: Setup (Shared Infrastructure)
......


## Phase 2: Foundational (Blocking Prerequisites)
......


## Phase 3: User Story 1 - 查看TKO域名列表 (Priority: P1) 🎯 MVP
......


## Phase 4: User Story 2 - 域名信息详情查看 (Priority: P2)
......


## Phase 5: User Story 3 - 域名列表搜索与筛选 (Priority: P3)
......


## Phase 6: Polish & Cross-Cutting Concerns
......

！！！注意： 这一步请仔细查看每个生成的步骤内容是否符合要求，如果不符合，请重新调整规划和技术方案。

3.6 检查任务清单(/speckit.checklist)

这一步是验证任务清单是否符合预期，是否可以实现。是可选步骤，如果不是必须的，可以跳过。

如果没有指定生成检查案例方向，会提出相关问答确定测试案例方向，最终会按照你的要求去生成测试案例。

最终会生成一个检查清单，具体可以看其产出内容tasks/001-tko-domain-list-page/checklist/implementation-readiness.md

1
2
3
4
5
6
7
8
9

# 实施准备度检查清单: TKO域名列表展示页面

**目的**: 在开发前验证需求规格和技术设计的完整性、清晰度,确保开发准备就绪
**创建日期**: 2026-01-12
**特性文档**: [spec.md](../spec.md) | [plan.md](../plan.md) | [tasks.md](../tasks.md)

**说明**: 此检查清单用于"实施前准备度验证",以轻量级方式快速检查需求质量的关键方面,重点关注需求完整性和清晰度。这不是测试实现是否正确,而是验证需求本身是否写得足够好、足够清晰以支持实施。

---

3.7 确认任务可实现(/speckit.analyze)

为什么？

在开始编码前，需要对整个方案进行全面的合规性检查：

✅ 所有用户故事都有对应的任务吗？

✅ 数据模型覆盖了所有需求吗？

✅ 宪章的所有原则都被满足了吗？

✅ 有遗漏的边界情况处理吗？

✅ 技术方案有风险点吗？

这个步骤主要让 AI 大模型去分析 上述生成 task 任务是否真正可以实现，有没有什么风险点？如下图所示：

3.8 开始实现 (/speckit.implement)

在真正执行之前，需要保证项目是可运行的，如：

前端项目：npm run dev 没有问题

后端项目：运行没有问题。

然后开始执行，等待 AI 自动编写代码，具体如下图所示：

以上就是基于spec-kitSDD 编程开发的全流程，具体可以参考spec-kit。

4. 最佳实践

5. 方案评估

经过上面的介绍，相信你已经对 SDD 有了一定的了解，下面我们来评估一下 Spec-Kit SDD 的优缺点。

5.1 优点

• 结构化开发：Spec Kit 强制执行结构化的、分步的软件设计流程（包括规范、计划、任务、实现），使整个开发过程更具纪律性。
• 减少“意图走样”：通过将需求转化为机器可读的 YAML 或 Markdown 规范文件，可以最大限度地减少传统开发流程中需求在不同阶段（需求 → 设计 → 实现）被误解的情况。
• 规范即“单一事实来源”：所有开发活动均以规范文件为准绳。当需求变更时，只需更新规范，然后重新生成计划和代码，避免了昂贵的代码重构。
• 改善协作和新人引导：安全策略、合规规则、设计系统约束等都写入规范，为团队提供了清晰的共享上下文，有助于团队协作和新成员快速上手。
• 模块化和可测试性：该方法将大型功能分解为原子的、可管理的任务单元，每个任务通常只涉及几个文件，提高了代码质量的一致性、可预测性和可审查性。
• 与现有工具集成：Spec Kit 是一个开源、模型不可知（model-agnostic）的工具包，可以与现有的 IDE（如 VS Code 的 Cursor 命令）、CI/CD 流水线以及多种 AI 模型（如 Claude Code）自然集成。

5.2 缺点

• 流程缓慢且成本高昂：整个过程需要生成大量的 Markdown 文档，可能非常缓慢，并且会消耗大量的 AI 模型 token（费用）。
• 变更困难：该流程依赖于前一步骤的输出。如果在流程中途（例如在实现阶段）想要修改规范，则必须重新生成计划和任务等后续所有文件，这个过程非常痛苦且繁琐。
• 文档负担重：对于喜欢快速迭代（vibe coding）的开发者来说，阅读和编辑大量的正式 Markdown 文档可能很无聊，感觉像是回到了传统的瀑布开发模型。
• 技术门槛较高：尽管学习曲线平缓，但有效使用 Spec Kit 仍需要相当高的技术知识水平和对架构原则的理解，需要知道最终的代码应该是什么样子。
• 适用场景有限：目前该工具最适合新项目（Greenfield work）或构建简单的原型。对于大型现有项目或需求频繁变更的项目，集成和维护成本很高。

6. 参考资料

• 《CodeBuddy Cli 官方说明文档》https://www.codebuddy.ai/docs/zh/cli/overview
• 《Specification-Driven Development (SDD) 规范驱动开发（SDD）》https://github.com/github/spec-kit/blob/main/spec-driven.md

2026-01-07 12:00:00

做一个有温度和有干货的技术分享作者 —— Qborfy

今天我们来学习 Agent Skill

Agent Skill 是一个可复用的知识包，它是 Anthropic 在 Claude 在内部使用的规范，由于其具备实用性，因此扩展成大部分 AI 代码 Agent 通用标准，它主要是基于文件系统的可重用资源，为 Claude 提供特定领域的专业知识：工作流程、上下文和最佳实践，可将通用代理转变为专家。与提示词（针对一次性任务的对话级指令）不同的地方是 Skill 按需加载模式，无需在多个对话中重复提供相同的指导。当 AI Agent 识别到你的任务与某个 Skill 描述相匹配时，它会自动按需加载并运用该 Skill 中的知识来帮助你，而无需你每次都重新解释整个工作流程。

通俗来讲，Skill 就像为 Agent 准备的一份份专门的“工作说明书”或“操作手册”。例如，你可以创建一个“代码审查”Skill，里面写明了团队审查代码的标准流程、注意事项和常用话术。之后，你只需对 AI Agent 说“请审查这段代码”，它就会自动调用这份说明书，像一位受过专门训练的专家一样为你服务。

是什么

核心价值：它将重复性的、复杂的工作流程（如代码审查、文档生成、数据清洗）标准化和自动化，让 AI Agent 从“通才”变成处理特定任务的“专家”，确保输出结果每次都高质量、一致。

组成部分：

1
2
3
4
5
6

my-skill/
├── SKILL.md # 核心文件：定义技能
├── scripts/
│ └── process.py # 可执行的辅助脚本
└── references/
└── guide.md # 参考文档和其他资源存放

• SKILL.md： 基础描述，里面有包含：
  • Metadata 元数据：始终加载在对话内，YAML 格式的前置元数据提供发现信息
  • Instructions 指令：触发时加载主体内容包含程序性知识：工作流程、最佳实践和指导原则
• scripts 和 references： 属于 skill 的绑定资料
  • scripts：脚本代码
  • references：参考资料，例如数据库模式、API 文档、模板或示例。

核心原理

官方解析流程图

用一个“审查这段代码“的例子来解释 Skill 运行流程：

图解说明：

1. 触发阶段：你提出一个任务，AI Agent 会将其与所有 Skill 的“描述”字段进行匹配。
2. 加载阶段：匹配成功后，AI Agent 不会一次性读取所有信息，而是先加载核心指令（SKILL.md），这是一种高效的“渐进式加载”。
3. 执行阶段：AI Agent 按照说明书中的步骤工作，必要时会调用 scripts/目录下的 Python 或其他脚本完成具体操作（如运行一个代码分析工具），而不仅仅是生成文本。
4. 输出阶段：最终 AI Agent 会交付一个符合预设标准的高质量结果。

怎么做

Claude 官方给出建议,好的 Skill 描述应简洁明了、结构清晰，并经过实际应用测试，主要由以下几点原则：

• 简洁是关键
• 设定适当的自由度，把 AI Agent 想象成一个探索路径的机器人，可以指定一定方向，但是不要限制死走哪条路
• 完整的测试，需要在对应 AI 模型进行完整测试

案例 1：智能代码审查 Skill

这是一个非常实用的场景，可以为团队建立统一的代码质量标准。

技能目标：当 AI Agent 接收到“请审查此代码”的指令时，自动激活并执行一套预设的审查清单。

Skill 实现要点：

• SKILL.md的描述：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

---
name: code-review-helper
description: "针对Python与JavaScript代码进行审查，重点检查安全反模式、性能瓶颈和代码风格一致性。当用户提出'代码审查'、'review'或'check'时触发。"
---
# 智能代码审查

## 功能概述
本Skill为Claude Code提供自动化代码审查能力，当用户提出代码审查相关请求时自动激活。基于智能代码分析技术，结合传统静态分析工具与AI语义理解，实现对Python和JavaScript代码的全面审查[1,5](@ref)。

## 触发条件
- **主要触发词**: "代码审查"、"review this code"、"check code"、"analyze code"
- **支持语言**: Python, JavaScript/TypeScript
- **自动检测**: 当用户提交代码片段并包含审查请求时自动激活

xxxxxxxx


## Python审查命令

pylint {file_path} --output-format=json
flake8 {file_path} --config=.flake8


## JavaScript审查命令

eslint {file_path} --format=json

• scripts/code_review.py

1
2
3
4
5
6

#!/usr/bin/env python3
"""
代码审查自动化脚本
支持Python和JavaScript代码的自动审查
"""
xxx

最终文件目录如下：

1
2
3
4

code-review-helper/
├── SKILL.md
├── scripts/
│   └── code_review.py

最终把文件放入对应 AI Agent 的 Skill 目录下即可。

使用工作流和反馈循环

把复杂的逻辑拆分一个个步骤工作流，参考如下：

1
2
3
4
5
6
7
8
9

## PDF表单填写流程
复制此清单并在完成后勾选项目：

任务进度：
- [ ] 第1步：分析表单（运行analyze_form.py）
- [ ] 第2步：创建字段映射（编辑fields.json）
- [ ] 第3步：验证映射（运行validate_fields.py）
- [ ] 第4步：填写表单（运行fill_form.py）
- [ ] 第5步：验证输出（运行verify_output.py）

结合反馈循环从而提升输出质量：运行验证器 → 修复错误 → 重复，具体如下：

1
2
3
4
5
6
7
8
9
10
11
12
13

## 内容审查流程

1. 按照STYLE_GUIDE.md中的指南撰写内容
2. 对照检查清单进行审查：
   - 检查术语一致性
   - 确认示例符合标准格式
   - 确认所有必需部分均已包含
3. 如发现问题：
   - 标注每个问题并注明具体部分参考
   - 修改内容
   - 再次审查检查清单
4. 仅当所有要求均满足时继续
5. 最终确定并保存文档

总结

1. 它不是“超级提示词”：Skill 和单纯的提示词关键区别在于脚本执行能力。Skill 能让 Claude“动手”运行代码（如：执行一个 Python 脚本处理数据），而不仅仅是“动口”生成代码建议。
2. 触发取决于“描述”：一个 Skill 能否被激活，90%取决于SKILL.md文件顶部 YAML Frontmatter 中的description字段。描述必须清晰地说明“做什么”和“何时触发”。
3. 三种技能位置，作用不同：
   • 个人技能 (~/.claude/skills/)：对所有项目有效，适合通用工具（如通用文件处理）。
   • 项目技能 (./.claude/skills/)：仅针对当前项目，可纳入 Git 管理，适合团队规范（如项目特定的组件生成）。
   • 插件技能：通过插件安装，功能通常更强大、更专业。
4. 避免“技能肥胖症”：一个 Skill 应只做一件事并把它做好。不要把“从登录到注销”的整个流程塞进一个 Skill。应拆分为“用户注册”、“密码重置”等多个小技能，Claude 可以自动组合使用。

与 MCP 的区别

• MCP：
  • 是基于规则的，需要人工编写规则
  • 不支持脚本执行
  • 不支持反馈循环
  • 不支持自动化测试
• Agent Skill：
  • 是基于文件的，不需要人工编写规则
  • 支持脚本执行
  • 支持反馈循环
  • 支持自动化测试

在 Anthropic 官方解释中，MCP 是连接大模型与世界的桥梁，而 Agent Skill 是大模型操作的世界的手。

参考资料

• Claude Skill 官方文档
• Clade Skill 最佳实战

2025-12-31 15:00:00

做一个有温度和有干货的技术分享作者 —— Qborfy

本文参考 roadmap.sh AI Engineer(AI应用开发工程师)RoadMap整理，如有侵权，请联系删除。

学习一门技能最重要的是目标和路线：

• 有了目标，才能知道自己所学可以用到哪里
• 有了路线，才能知道自己该学什么，怎么学

AI应用开发学习路线图

完整思维导图

前置知识

入门能力

进阶能力

高级能力

后续发展路线

参考资料

• AI Engineer RoadMap (AI应用开发工程师学习路线图)
• 如何选择AI Agent框架？五种主流AI Agent框架对比

2025-12-18 17:45:08

做一个有温度和有干货的技术分享作者 —— Qborfy

今天我们来学习 Claude-Code 中的 Skill 技能

Claude Code 中的 Skill 是一个可复用的知识包，它将特定的操作指南、代码示例和最佳实践打包成一个模块。当 Claude 识别到你的任务与某个 Skill 描述相匹配时，它会自动按需加载并运用该 Skill 中的知识来帮助你，而无需你每次都重新解释整个工作流程。

通俗来讲，Skill 就像为 Claude Code 准备的一份份专门的“工作说明书”或“操作手册”。例如，你可以创建一个“代码审查”Skill，里面写明了团队审查代码的标准流程、注意事项和常用话术。之后，你只需对 Claude Code 说“请审查这段代码”，它就会自动调用这份说明书，像一位受过专门训练的专家一样为你服务。

是什么

参考资料

• Anthropic MCP 官方文档
• Model Context Protocol(MCP) 编程极速入门
• FastMCP 官方文档
• OpenAI MCP 文档

2025-12-17 12:00:00

做一个有温度和有干货的技术分享作者 —— Qborfy

今天我们来学习 模型上下文协议（MCP）

MCP（Model Context Protocol，模型上下文协议） 是由 Anthropic 公司推出的开源协议，旨在为大型语言模型与外部数据源、工具之间建立安全、标准化、双向的连接通道。

通俗地说，MCP 如同 AI 世界的“USB-C 接口”。它定义了一套通用标准，使得任何支持 MCP 的 AI 应用（如 Claude Desktop、Cursor IDE）都能通过统一的“插口”，即插即用地连接各种外部工具（如数据库、API、本地文件），而无需为每个工具单独开发适配器。其核心价值在于解决了 AI 应用与外部资源交互时的碎片化集成问题，实现了生态的标准化和去中心化。

是什么

MCP 遵循经典的客户端-服务器架构，其核心组件与协作流程如下图所示，清晰地展示了数据如何在不同部分间流转。

核心组件解析：

• MCP Host（宿主）：这是用户直接交互的 AI 应用程序，例如 Cursor IDE、Claude Desktop 等。它是发起所有请求的“大脑”和总指挥。
• MCP Client（客户端）：它内嵌于 Host 内部，充当协议的“翻译官”。每个 Client 与一个 Server 保持一对一的专有连接，负责所有通信的路由和转换。
• MCP Server（服务器）：这是提供具体能力的轻量级服务程序。它向外暴露三种核心能力：
  • 工具 Tool：可执行的函数，允许 LLM 执行操作，如发送邮件、查询数据库。
  • 资源 Resource：只读的数据源，如文件内容、数据库记录、API 响应。
  • 提示模板 Prompt：预定义的对话模板，指导 LLM 完成特定工作流。
• MCP Protocol（协议）：基于JSON-RPC 2.0的消息格式，定义了组件间的通信规则。支持 Stdio（本地）和 HTTP（远程）两种传输方式。

怎么做

MCP 服务器搭建

使用 Python 创建 MCP 服务器的简明示例，该服务器提供一个获取网页标题的工具。

1
2
3
4
5
6
7
8
9
10

from fastmcp import FastMCP

mcp = FastMCP("My MCP Server")

@mcp.tool
def greet(name: str) -> str:
    return f"Hello, {name}!"

if __name__ == "__main__":
    mcp.run(transport="http", port=8000)

MCP 客户端调用

使用 Python 创建 MCP 客户端的简明示例，调用上面创建的 MCP
服务器的 get_webpage_title 工具。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

import asyncio
from fastmcp import Client

client = Client("http://localhost:8000/mcp")

# 列出可用工具
async def list_tools():
    async with client:
        tools = await client.list_tools()
        print(tools)

# 调用 greet MCP tool
async def call_tool(name: str):
    async with client:
        result = await client.call_tool("greet", {"name": name})
        print(result)

asyncio.run(call_tool("Ford"))

OpenAI MCP 调用

使用 OpenAI Python SDK 创建 MCP 客户端的简明示例，调用 MCP 服务器的 greet 工具。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-5",
    tools=[
        {
            "type": "mcp",
            "server_label": "dmcp",
            "server_description": "Demo MCP Server",
            "server_url": "http://localhost:8000/mcp",
            "require_approval": "never",
        },
    ],
    input="Hello, MCP!",
)

print(resp.output_text)

我们在大模型中调用 MCP 服务正常步骤如下：

1. 列出 MCP 服务中可用的工具和资源。
2. 筛选出需要调用的工具或资源。
3. 构造调用请求并发送给 MCP 服务。
4. 处理 MCP 服务返回的结果。
5. 将结果添加到输入中，继续与模型对话。

MCP 生态

• 主流 MCP Hosts（应用）：Cursor IDE、Claude Desktop、OpenWebUI等是当前最流行的 MCP 宿主应用。只需在它们的设置中添加 MCP Server，即可扩展其能力。
• MCP Server 资源库：要寻找现成的 Server，可以访问 github.com/modelcontextprotocol/servers（官方示例）和 cursor.directory（社区目录），这里有从文件系统、数据库到各类云服务的丰富工具。
• 开发工具：Anthropic 提供了官方的 Python 和 TypeScript SDK等，极大简化了 MCP Server 和 Client 的开发流程。
  • SDK 文档：https://github.com/modelcontextprotocol

❄️ 冷知识

• 灵感来源：MCP 的设计深受语言服务器协议（LSP） 的启发。LSP 统一了 IDE 对不同编程语言的支持，而 MCP 旨在统一 AI 应用对不同工具和数据的访问。
• 权限控制：在 MCP 架构下，工具由模型控制调用，而资源（数据）的访问权完全由用户控制。Server 所有者无需将 API 密钥等敏感信息暴露给 LLM 提供商，提升了安全性。
• 商业前景：分析认为，MCP 在To C（消费者）领域（如智能硬件、社交 App）有广阔前景，因其能快速集成多样化服务。但在To B（企业）领域可能面临挑战，因为企业级软件更倾向于成为用户入口而非被调用的工具。

参考资料

• Anthropic MCP 官方文档
• Model Context Protocol(MCP) 编程极速入门
• FastMCP 官方文档
• OpenAI MCP 文档

2025-12-16 12:00:00

做一个有温度和有干货的技术分享作者 —— Qborfy

今天我们来学习 AI 函数调用 Function Calling

一句话核心: Function Calling（函数调用）是大模型在对话过程中，根据用户需求调用外部函数或工具的一种能力。

通俗地讲，它让大模型从“能说会道”的参谋，变成了“能动手做事”的助手。当模型遇到自己无法直接解决的问题时（比如查询实时信息、进行复杂计算），它不再说“我做不到”，而是会“告诉”你的程序：“嘿，你需要调用那个叫 get_weather 的函数，并把 location 参数设置为‘北京’。”

需要注意的是，模型本身并不直接执行函数，它只负责生成调用的“指令”。真正的执行工作由你的程序来完成。

它的核心价值在于将大模型的语言理解能力与外部工具的执行能力相结合，从而突破其固有局限（如知识截止日期、无法访问网络等），完成更复杂的任务。

是什么

通过一张图来理解 Function Calling 的工作原理：

这个流程的核心在于，大模型至少被调用了两次：第一次是分析意图并决定调用哪个函数，第二次是将函数的执行结果整合成对人类友好的自然语言回复。

怎么做

下面我们通过几个案例来理解 Function Calling 的使用场景和实现方式。

案例 1：智能天气查询助手

这是最经典的案例，展示了如何弥补大模型知识时效性的不足。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

# 1. 定义可供调用的工具（告诉模型你有什么函数）
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_current_weather",  # 函数名
            "description": "获取指定城市的当前天气",  # 给模型看的功能描述
            "parameters": {  # 参数定义
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "城市名称，例如：北京",
                    }
                },
                "required": ["location"],  # 必须提供的参数
            },
        },
    }
]

# 2. 用户提问
messages = [{"role": "user", "content": "北京天气怎么样？"}]

# 3. 首次调用模型，模型会返回类似以下的指令：
# function_call = {
#   "name": "get_current_weather",
#   "arguments": "{\"location\": \"北京\"}"
# }

# 4. 你的程序执行真实的天气API调用函数
# 5. 将执行结果 `weather_result` 传给模型进行第二次调用，生成最终回复

案例 2：并行查询（进阶技巧）

当用户的问题涉及多个独立查询时，可以开启并行调用功能，大幅提升效率。

用户提问：“同时查询北京和上海的天气。”
实现：设置 parallel_tool_calls=True 参数，模型可以同时生成两个函数调用请求，你的程序可以并行执行两个天气查询 API，然后一次性将结果返回给模型进行总结。

案例 3：股票查询系统

这个案例展示了如何将专业、实时的数据（如股价）接入对话系统。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 工具定义示例
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_stock_price",
            "description": "获取指定股票的实时价格",
            "parameters": {
                "type": "object",
                "properties": {
                    "symbol": {"type": "string", "description": "股票代码"}
                },
                "required": ["symbol"],
            },
        }
    }
]

当用户询问“青岛啤酒的股价是多少？”，模型会调用此函数，你的程序可以连接真实的金融数据 API 获取信息，再由模型生成回复。

实战案例

下面我们通过 openai sdk 来实现一个简单的天气查询功能：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

from openai import OpenAI
import json

client = OpenAI()

# 1. 定义可供调用的工具（告诉模型你有什么函数）
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_current_weather",  # 函数名
            "description": "获取指定城市的当前天气",  # 给模型看的功能描述
            "parameters": {  # 参数定义
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "城市名称，例如：北京",
                    }
                },
                "required": ["location"],  # 必须提供的参数
            },
        },
    }
]

def get_current_weather(params):
    location = params.get("location")
    # 这里你可以调用真实的天气API，这里我们模拟返回数据
    return f"{location} 当前天气晴，温度25摄氏度"

# 这个列表会随着对话进行不断更新
input_list = [
    {"role": "user", "content": "请告诉我北京的天气。"}
]

# 2. 第一次调用模型，模型会返回函数调用指令
response = client.responses.create(
    model="gpt-5",
    tools=tools,
    input=input_list,
)

# 这时候我们把模型的输出添加到输入列表中
input_list += response.output

for item in response.output:
    if item.type == "function_call":
        if item.name == "get_current_weather":
            # 3. 执行函数调用
            args = json.loads(item.arguments)
            weather = get_current_weather(args)


            # 4. 将函数调用结果添加回输入列表，供模型继续处理
            input_list.append({
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps({
                  "horoscope": weather
                })
            })

print("最终的输入列表:")
print(input_list)

response = client.responses.create(
    model="gpt-5",
    instructions="根据用户的提问和函数调用结果，生成一个友好的回复。",
    tools=tools,
    input=input_list,
)

# 5. The model should be able to give a response!
print("最终输出：")
print(response.model_dump_json(indent=2))
print("\n" + response.output_text)

• 核心工具/库：OpenAI Python SDK。即使你使用的不是 OpenAI 的模型（如通义千问、DeepSeek），许多国产大模型平台也兼容 OpenAI 的 API 格式。这意味着你只需简单配置不同的 base_url 和 api_key，就可以用几乎相同的代码调用不同品牌的模型，大大降低了学习和开发成本。
• 关键参数：在调用 client.chat.completions.create 方法时，核心参数是 tools（用于定义可用函数列表）和 tool_choice（用于控制调用行为，如 auto 自动决定或强制调用某个函数）。

❄️ 冷知识

1. 模型没有“手”：一个大反直觉的真相是，大模型本身并不具备执行代码的能力。它只是一个“超级大脑”，负责生成调用函数的“计划”。真正去执行这个计划、拥有“手和脚”的是你自己的程序。
2. 描述决定一切：模型是否调用一个函数，很大程度上依赖于你为函数写的 description（描述）。描述必须清晰、准确，模型才能正确理解何时该调用它。
3. “思考”过程可控：你可以通过 tool_choice 参数精细控制模型的行为。比如，可以强制模型必须调用某个函数（tool_choice={"type": "function", "function": {"name": "get_weather"}}），或者禁止它调用任何函数（tool_choice="none"），让它完全靠自己知识库回答。
4. 与 MCP 的关系：你可以把 Function Calling 看作是一个“基础版”的工具调用技术，简单直接。而MCP（Model Context Protocol） 则是一个更高级、更标准化的“企业级工具箱协议”，它旨在以统一的方式管理成千上万的工具，更适合构建复杂的 AI 智能体（Agent）工作流。它们是互补而非替代关系。

参考资料

• OpenAI Function Calling 官方文档
• 阿里云百炼平台文档 Function Calling
• DeepSeek Function Calling 文档