技术支撑能力

底线要求 · API/Skill/MCP/鉴权全栈技术解析

一、技术支撑能力总览

1.1 1.5线需要的技术深度

1.5线不是研发，不需要你会写Buddy的后端代码。但你需要：

读懂技术信息：能看懂错误日志、配置文件、API文档
动手验证：能自己复现问题、测试配置、验证方案
技术沟通：能和研发团队用技术语言准确描述问题
引导用户：能把技术操作翻译成用户能执行的步骤

1.2 核心技术栈要求

领域	要求级别	具体内容
JSON/配置文件	熟练	能读写JSON、YAML、Markdown frontmatter
HTTP/API基础	理解	请求方法、状态码、Header、Body、鉴权
命令行	基础	文件操作、进程管理、环境变量
Node.js/Python	了解	知道版本管理、包安装、环境隔离
Git基础	了解	基本命令、分支概念
网络基础	理解	DNS、代理、SSL/TLS、端口

二、API调用机制深度解析

2.1 什么是API调用（在Buddy语境下）

在Buddy产品中，API调用有两个含义：

用户通过API使用Buddy能力：开发者通过HTTP API调用Buddy的AI模型能力
Buddy内部调用外部API：WorkBuddy通过工具/MCP调用第三方服务的API

2.2 HTTP API 基础

请求组成

HTTP请求 = 方法(Method) + URL + Headers + Body

示例：
POST https://api.example.com/v1/chat/completions
Headers:
  Content-Type: application/json
  Authorization: Bearer sk-xxxxxxxx
Body:
  {
    "model": "model-name",
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }

常用HTTP方法

方法	用途	有Body	幂等
GET	获取资源	否	是
POST	创建资源/提交数据	是	否
PUT	替换资源	是	是
PATCH	部分更新资源	是	否
DELETE	删除资源	可选	是

HTTP状态码分类

范围	含义	常见
2xx	成功	200 OK, 201 Created, 204 No Content
3xx	重定向	301 永久重定向, 302 临时重定向
4xx	客户端错误	400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Too Many Requests
5xx	服务端错误	500 Internal Error, 502 Bad Gateway, 503 Service Unavailable

2.3 AI API 调用模式

AI大模型的API调用通常遵循以下模式：

Chat Completion 模式

请求：
POST /v1/chat/completions
{
  "model": "指定模型",
  "messages": [
    {"role": "system", "content": "系统提示词"},
    {"role": "user", "content": "用户消息"},
    {"role": "assistant", "content": "AI回复"},
    {"role": "user", "content": "用户追问"}
  ],
  "temperature": 0.7,
  "max_tokens": 4096,
  "stream": true
}

响应（流式）：
data: {"choices": [{"delta": {"content": "你"}}]}
data: {"choices": [{"delta": {"content": "好"}}]}
data: [DONE]

关键参数解释

参数	含义	常见问题
model	使用的模型名称	模型名写错导致404
messages	对话历史数组	格式不对导致400
temperature	随机性（0-2）	太高导致回复发散
max_tokens	最大回复长度	设太小导致回复被截断
stream	是否流式输出	流式需要特殊解析SSE

2.4 API调用常见错误与排查

错误码	含义	排查方向
400	请求格式错误	检查JSON格式、必填字段、参数类型
401	认证失败	API Key是否正确、是否过期
403	权限不足	该Key是否有权访问此接口
404	接口不存在	URL拼写、版本号、模型名是否正确
429	速率限制	请求太频繁，需要降低频率或升级配额
500	服务内部错误	服务端问题，重试或联系提供商
502/503	服务不可用	服务端过载或维护，等待恢复

三、Skill编写与调试实战

3.1 SKILL.md 编写规范

完整结构模板

---
title: "我的技能名称"
description: "当用户需要做xxx时使用此技能。触发词：关键词1、关键词2、关键词3。适用场景描述。"
agent_created: true
allowed-tools:
  - Read
  - Write
  - Bash
  - WebFetch
---

# 技能名称

## 触发条件
- 当用户提到xxx时触发
- 当用户需要xxx时触发

## 前置检查
1. 确认xxx是否就绪
2. 检查xxx环境

## 执行流程
### 步骤1：收集信息
- 确认用户需要什么
- 获取必要参数

### 步骤2：执行操作
- 具体操作指令
- 注意事项

### 步骤3：验证结果
- 如何确认执行成功
- 错误处理方式

## 注意事项
- 避免xxx
- 优先xxx
- 当xxx情况时，改用yyy方案

## 错误处理
- 如果遇到错误A → 执行方案A
- 如果遇到错误B → 执行方案B

3.2 Description 编写黄金法则

Description是skill最重要的字段——它决定了AI能否正确匹配和触发skill。

            黄金法则：
            具体明确：不写"处理各种任务"，写"当用户需要查询A股/港股/美股的K线数据时"
包含触发词：把用户可能说的关键词列出来
说明不适用场景：避免误匹配
简洁有力：一两句话说清楚，不要写一大段

        

好的Description示例

# 好的
description: "查询A股、港股、美股个股/指数/ETF的详细数据，包括K线/分时、财务报表、资金流向、技术指标。触发词：股票数据、K线、财报、资金流、技术分析"

# 不好的
description: "金融数据查询工具"  ← 太模糊，无法准确匹配

3.3 Skill 调试技巧

问题1：Skill不触发

检查description是否覆盖了用户的表达方式
检查SKILL.md是否在正确目录下
检查frontmatter格式是否正确（YAML语法）
尝试/skill-name手动触发测试

问题2：Skill触发了但执行错误

检查指令正文是否有歧义——AI可能理解错了你的意图
检查allowed-tools是否限制了必要的工具
检查是否引用了不存在的工具（deferred tools需要ToolSearch）
简化指令，逐步增加复杂度来定位问题

问题3：多个Skill冲突

检查是否有多个skill的description覆盖了相同的触发场景
通过更精确的description来区分各skill的适用范围
必要时合并功能相近的skill

3.4 Skill安全审计要点

安装第三方skill时需要注意的安全风险：

风险等级	说明	示例
P0 - 严重	可直接造成数据泄露/系统损坏	指令中有删除系统文件、发送数据到外部等操作
P1 - 高危	可能造成数据丢失或隐私风险	无限制地读取个人文件、执行网络请求
P2 - 安全	无明显风险	限定了工具范围、操作范围合理

四、MCP协议配置与排错

4.1 mcp.json 完整配置指南

// ~/.workbuddy/mcp.json
{
  "mcpServers": {
    // stdio 类型（本地CLI工具）
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {
        "BROWSER_PATH": "/path/to/browser"
      }
    },
    
    // HTTP/SSE 类型（远程服务）
    "my-api-server": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    },
    
    // 带环境变量的stdio类型
    "database-tool": {
      "command": "node",
      "args": ["./mcp-server.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_NAME": "mydb"
      }
    }
  }
}

4.2 配置字段详解

字段	类型	说明	必需
command	string	要执行的命令（stdio类型）	stdio必需
args	string[]	命令参数数组	可选
env	object	环境变量键值对	可选
url	string	MCP服务地址（HTTP类型）	HTTP必需
headers	object	HTTP请求头	可选

4.3 MCP 常见配置错误排查表

错误现象	可能原因	解决方案
JSON解析失败	尾逗号、缺少引号、注释	用JSON验证器检查，注意JSON不支持注释
command not found	可执行文件不在PATH中	使用绝对路径或确认工具已安装
ECONNREFUSED	HTTP服务未启动或端口不对	确认服务运行中，检查端口号
Permission denied	文件无执行权限	chmod +x 或检查Windows权限
tools未显示	配置正确但未重启	重启WorkBuddy客户端
认证失败	token过期或格式错误	检查headers中的Authorization格式

4.4 MCP调试步骤

验证JSON格式：用在线JSON验证器检查mcp.json
手动测试command：在终端直接执行command + args
检查依赖：确认Node.js、Python等运行时版本满足要求
网络测试：如果是HTTP类型，用curl测试URL可达性
日志查看：检查WorkBuddy日志中的MCP相关错误
最小化测试：先用最简配置验证基础连通性

五、鉴权体系完整解析

5.1 鉴权方式分类

方式	原理	使用场景	安全性
API Key	静态密钥直接认证	简单API调用	中（密钥泄露即失效）
OAuth 2.0	授权码换取token	连接器授权	高（可控权限范围）
Bearer Token	请求头携带token	API调用鉴权	中高（有过期时间）
签名认证	请求内容+密钥生成签名	腾讯云API（HMAC-SHA256）	高（防篡改）

5.2 OAuth 2.0 在Buddy中的应用

连接器（如腾讯文档、GitHub等）使用OAuth 2.0授权流程：

用户点击"连接" 
  → 跳转到第三方授权页面
  → 用户确认授权
  → 回调WorkBuddy，携带authorization_code
  → WorkBuddy用code换取access_token和refresh_token
  → 存储token用于后续API调用
  → token过期时用refresh_token刷新

OAuth常见问题

授权后还是disconnected：可能回调URL被阻止、token获取失败
过一段时间就断开：refresh_token过期或无效
权限不足：授权时选择的scope不够

5.3 腾讯云API鉴权（TC3-HMAC-SHA256）

如果涉及到腾讯云API调用（如通过tccli），需要了解其签名机制：

签名流程：
1. 拼接规范请求串（CanonicalRequest）
   = HTTPMethod + URI + QueryString + Headers + SignedHeaders + HashedPayload
2. 拼接待签名字符串
   = Algorithm + Timestamp + CredentialScope + Hash(CanonicalRequest)
3. 计算签名
   = HMAC-SHA256(SecretKey, Date, Service, "tc3_request", StringToSign)
4. 组装Authorization Header

tccli 配置文件位置

~/.tccli/
├── default.credential    # 密钥存储
├── default.configure     # 默认区域等配置
└── [profile].credential  # 多Profile支持

5.4 密钥安全最佳实践

❌ 不要把密钥硬编码在代码/配置文件中提交到Git
✅ 使用环境变量传递密钥
✅ 使用子用户/服务角色限制权限（最小权限原则）
✅ 定期轮换密钥
✅ 使用密钥管理服务（如腾讯云SSM）

六、错误码体系与处理策略

6.1 通用错误分层模型

错误来源分层：
├── 网络层错误（无法到达服务器）
│   ├── DNS解析失败 → 检查DNS配置
│   ├── 连接超时 → 检查网络/防火墙
│   ├── SSL错误 → 检查证书/时间
│   └── 代理错误 → 检查代理配置
│
├── 协议层错误（到达服务器但请求有问题）
│   ├── 4xx → 客户端问题
│   └── 5xx → 服务端问题
│
├── 业务层错误（请求成功但业务逻辑报错）
│   ├── 参数校验失败
│   ├── 资源不存在
│   ├── 权限不足
│   └── 业务规则冲突
│
└── 运行时错误（工具执行过程中）
    ├── 超时
    ├── 内存不足
    ├── 文件IO错误
    └── 进程崩溃

6.2 WorkBuddy 工具执行错误处理

错误类型	表现	用户视角	解决策略
工具超时	执行时间超过限制	"AI好像卡住了"	增加timeout或拆分任务
权限拒绝	sandbox阻止操作	"AI说不能执行"	确认操作合理性后授权
文件不存在	路径错误或文件被删	"AI说找不到文件"	确认路径正确性
命令执行失败	exit code非0	"操作失败了"	查看具体错误输出
网络请求失败	WebFetch/WebSearch报错	"AI说访问不了网页"	检查URL、网络、防火墙

6.3 错误日志阅读技巧

快速从错误日志中提取关键信息：

看最后一行：通常是最直接的错误描述
找Error/Exception关键词：定位错误类型
看堆栈第一行：错误发生的具体位置
找数字：状态码、行号、端口号等
注意时间戳：确认是否是最新的错误而不是历史日志

七、环境配置与依赖管理

7.1 Node.js 环境

# 版本检查
node -v
npm -v

# 常见问题：
# 1. npx命令找不到 → Node.js未安装或PATH配置问题
# 2. 版本不兼容 → 某些MCP工具要求特定Node版本
# 3. npm install失败 → 网络问题（换源）或权限问题

# 换源（国内加速）
npm config set registry https://registry.npmmirror.com

7.2 Python 环境

# 版本检查
python --version
pip --version

# 虚拟环境（避免污染全局）
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
.\.venv\Scripts\activate   # Windows

# WorkBuddy管理的Python路径：
# C:\Users\Administrator\.workbuddy\binaries\python\versions\3.13.12\python.exe

7.3 环境变量

# Windows (PowerShell)
$env:API_KEY = "your-key"
echo $env:PATH

# Linux/Mac
export API_KEY="your-key"
echo $PATH

# 永久设置
# Windows: 系统属性 → 环境变量
# Linux: ~/.bashrc 或 ~/.profile

7.4 常见环境问题速查

症状	原因	解决
"xxx is not recognized"	命令不在PATH中	添加到PATH或用绝对路径
"EACCES permission denied"	npm全局安装权限不足	用sudo或修改npm prefix
"Module not found"	包未安装或路径不对	npm install / pip install
"ENOSPC"	磁盘空间不足	清理磁盘
"CERT_UNTRUSTED"	SSL证书验证失败	检查系统时间、代理配置

八、命令行工具使用

8.1 文件系统操作

# 查看文件/目录
ls -la          # Linux/Mac
dir             # Windows
Get-ChildItem   # PowerShell

# 创建目录
mkdir -p path/to/dir     # Linux/Mac
New-Item -ItemType Directory -Path "path" -Force  # PowerShell

# 文件内容
cat file.txt         # 查看文件
head -20 file.txt    # 前20行
tail -f log.txt      # 实时追踪日志

# 文件搜索
find . -name "*.md"                    # Linux: 按名搜索
grep -rn "keyword" ./path/             # Linux: 按内容搜索
Get-ChildItem -Recurse -Filter "*.md"  # PowerShell: 按名搜索
Select-String -Path ".\" -Pattern "keyword" -Recurse  # PowerShell: 按内容搜索

8.2 网络诊断

# DNS解析
nslookup example.com
dig example.com

# 连通性测试
ping example.com
curl -v https://api.example.com/health

# 端口检查
netstat -tlnp | grep 3000     # Linux: 查看端口占用
Get-NetTCPConnection -LocalPort 3000  # PowerShell

# HTTP请求测试
curl -X POST https://api.example.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token" \
  -d '{"key": "value"}'

8.3 进程管理

# 查看进程
ps aux | grep node       # Linux
Get-Process | Where-Object {$_.ProcessName -like "*node*"}  # PowerShell

# 终止进程
kill -9 PID              # Linux
Stop-Process -Id PID -Force  # PowerShell

# 后台运行
nohup command &          # Linux
Start-Process command    # PowerShell

九、网络与安全基础

9.1 DNS 基础

A记录：域名 → IPv4地址
AAAA记录：域名 → IPv6地址
CNAME记录：域名 → 另一个域名
MX记录：邮件交换服务器
TXT记录：文本信息（常用于验证）
NS记录：域名服务器指向

9.2 SSL/TLS

作用：加密传输 + 身份验证
证书类型：DV（域名验证）/ OV（组织验证）/ EV（扩展验证）
常见问题：
- 证书过期 → 续期
- 域名不匹配 → 检查证书绑定的域名
- 证书链不完整 → 补充中间证书
- 系统时间不对 → 校正系统时间

9.3 代理与防火墙

企业环境常见网络问题：

HTTP代理：需要设置http_proxy/https_proxy环境变量
公司防火墙：可能阻止WebSocket、SSH等非标准端口
SSL审计：公司代理替换了SSL证书，导致证书验证失败

十、技术支撑面试题精选

Q1：用户说mcp.json配好了但工具不显示，你怎么排查？

            参考答案：
            请用户分享mcp.json内容，用JSON验证器检查格式
确认文件路径是否正确（~/.workbuddy/mcp.json）
如果是stdio类型：在终端手动执行command+args看是否能启动
如果是HTTP类型：用curl测试url是否可达
检查是否重启了WorkBuddy客户端（配置变更通常需要重启生效）
检查env字段中是否有必需的环境变量缺失
查看WorkBuddy日志中是否有MCP相关的报错信息

        

Q2：用户调用API返回401，你怎么处理？

            参考答案：
            401表示认证失败，首先确认API Key是否正确（注意前后空格）
确认Header格式：应该是 Authorization: Bearer sk-xxxxx，注意Bearer和token之间有空格
检查Key是否过期或被禁用
确认是否使用了正确的Key类型（有些服务区分test key和live key）
确认API endpoint是否和Key匹配（不同区域/环境的Key不通用）
如果是OAuth token：检查token是否过期，尝试用refresh_token刷新

        

Q3：Skill文件格式有什么要求？常见格式错误有哪些？

参考答案：

SKILL.md必须包含YAML frontmatter（用---包围）和Markdown正文。常见错误：

frontmatter缺少起始或结束的---分隔符
YAML缩进用了Tab而非空格
description值含有冒号但未加引号
allowed-tools列表格式不对（应该是- Tool这样的YAML列表）
文件保存编码不是UTF-8
文件名不是SKILL.md（大小写敏感）

Q4：解释一下什么是deferred tool，为什么Skill中直接调用会失败？

参考答案：

WorkBuddy的工具分为两类：常驻工具（Read/Write/Bash等，始终可用）和延迟工具（ImageGen/LSP等，按需加载）。延迟工具不在默认工具列表中，直接调用会报"Tool not found"。正确的使用方式是：先通过ToolSearch工具发现目标工具并获取其参数schema，然后通过DeferExecuteTool工具来调用。在Skill中引导AI使用延迟工具时，必须明确写明这个发现+调用的两步流程。

Q5：用户在公司网络环境下无法连接WorkBuddy，可能是什么原因？

            参考答案：
            公司防火墙阻止了WorkBuddy的服务域名或端口
公司HTTP代理需要配置但WorkBuddy未使用代理
公司SSL审计代理替换了证书，导致TLS握手失败
DNS解析被公司内网DNS服务器拦截
网络策略限制了WebSocket连接（WorkBuddy可能使用WS通信）
排查建议：尝试手机热点连接确认是否公司网络问题；如果是，联系IT部门白名单相关域名

        