如果你最近在看 AI Agent、Copilot、Cursor，一定绕不开一个词：OpenSpec
本文将：
✅ 用最通俗的方式讲清 OpenSpec
✅ 带你实现一个可运行的 OpenSpec Agent 项目
一、OpenSpec 到底是什么？
👉 OpenSpec = 给 AI 定义“怎么调用能力”的标准
🧠 换个更好理解的类比
| 世界 | 对应 |
|---|---|
| 操作系统（iOS） | OpenSpec |
| App | Skill（能力） |
| 用户操作 | Agent 调度 |
👉 如果没有 OpenSpec：
- 每个能力调用方式不同
- AI 无法复用能力
- 无法组合复杂任务
结果就是：
❌ AI = 聊天工具
❌ 系统 = 工具孤岛
👉 有了 OpenSpec：
- 能力被标准化
- AI 可以自动调用
- 能力可以自由组合
结果：
✅ AI 开始“干活”
✅ 系统变成“能力网络”
二、一个真实问题：为什么需要 OpenSpec？
假设用户说：
帮我查东京天气并总结
❌ 传统写法
const weather = await getWeather()
const result = await callLLM(`请总结：${weather}`)
问题：
- 强耦合
- 不可扩展
- AI 只是“文本生成器”
✅ OpenSpec 思路
先定义能力：
{
"name": "getWeather",
"input": { "city": "string" },
"output": { "temperature": "number" }
}
然后交给 AI：
1. 调 getWeather
2. 再调 summarize
👉 核心变化：
AI 不再输出“答案”，而是输出“行动（Action）”
三、OpenSpec 的本质（工程视角）
OpenSpec 干了三件关键的事：
1️⃣ 能力标准化（Spec）
{
"name": "search",
"input": { "query": "string" },
"output": { "results": "array" }
}
👉 AI 可以“理解能力”
2️⃣ 调用协议统一（Tool Calling）
{
"tool": "search",
"params": { "query": "OpenSpec" }
}
👉 AI 开始“调用工具”
3️⃣ 模型与能力解耦
模型（决策） + Skill（执行）
👉 可以随意替换模型
四、重点来了：我们实现一个可运行的 OpenSpec Agent
不讲虚的，直接上代码。
五、项目结构（最小可运行）
openspec-demo/
├── index.ts
├── agent/
│ └── orchestrator.ts
├── skills/
│ ├── weather.ts
│ └── summarize.ts
├── spec/
│ └── registry.ts
├── llm/
│ └── mock.ts
├── types/
│ └── skill.ts
六、核心实现（精简版）
1️⃣ 定义 Skill（能力抽象）
export interface Skill<I = any, O = any> {
name: string
description: string
inputSchema: Record<string, string>
outputSchema: Record<string, string>
run: (input: I) => Promise<O>
}
2️⃣ 实现两个能力
🌤️ 获取天气
export const weatherSkill = {
name: "getWeather",
async run({ city }) {
return {
temperature: 18,
desc: "东京多云"
}
}
}
🧠 文本总结
export const summarizeSkill = {
name: "summarize",
async run({ text }) {
return `总结：${text}`
}
}
3️⃣ OpenSpec 注册中心（核心）
export const skillRegistry = {
getWeather: weatherSkill,
summarize: summarizeSkill
}
👉 这一步非常关键：
这就是 OpenSpec 的最小实现形态
4️⃣ 模拟 AI 决策
export async function decidePlan(input) {
return [
{ tool: "getWeather", params: { city: "东京" }},
{ tool: "summarize", params: { fromPrevious: true }}
]
}
5️⃣ Agent 调度器（核心大脑）
export async function runAgent(input) {
const plan = await decidePlan(input)
let lastResult = null
for (const step of plan) {
const skill = skillRegistry[step.tool]
let params = step.params
if (params.fromPrevious) {
params = { text: JSON.stringify(lastResult) }
}
lastResult = await skill.run(params)
}
return lastResult
}
6️⃣ 运行入口
runAgent("帮我查东京天气并总结").then(console.log)
👉 输出：
总结：{"temperature":18,"desc":"东京多云"}
七、这个 Demo 到底厉害在哪？
虽然只有 200 行代码，但已经具备：
✅ 能力抽象（Skill）
✅ 标准化注册（OpenSpec）
✅ 自动调度（Agent）
✅ 多步骤执行（Pipeline）
👉 本质上：
你已经实现了一个最小版 AI 操作系统
八、可以怎么升级（真正价值）
🚀 1. 接入真实 LLM（关键）
把：
decidePlan()
换成：
👉 OpenAI Tool Calling / Function Calling
🚀 2. 自动生成执行链（Agent 进化）
现在是写死的：
if (input.includes("天气"))
未来是：
👉 AI 自动规划任务链
🚀 3. 插件化 Skill（架构升级）
自动扫描 /skills 目录
🚀 4. 加 Memory（上下文能力）
- 短期对话
- 长期用户数据
🚀 5. 前端可视化
你可以做：
👉 执行链路可视化
👉 Skill 调用流程图
这一步非常适合前端工程师做差异化。
九、和传统开发的本质区别
| 传统开发 | AI 架构 |
|---|---|
| 写函数调用 | 定义能力 |
| 手动编排逻辑 | AI 自动调度 |
| 面向接口 | 面向能力 |
👉 认知升级一句话：
未来不是“写代码”，而是“设计能力系统”
十、总结
👉 OpenSpec = AI 世界的“能力操作系统规范”
👉 Agent = 基于 OpenSpec 运行的执行引擎
