OpenSpec 是什么？我用 200 行代码实现了一个 AI Agent

本文将：

用最通俗的方式讲清 OpenSpec
带你实现一个可运行的 OpenSpec Agent 项目

一、OpenSpec 到底是什么？

OpenSpec = 给 AI 定义“怎么调用能力”的标准

换个更好理解的类比

如果没有 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

核心变化：

三、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
}

这一步非常关键：

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）

本质上：

八、可以怎么升级（真正价值）

1. 接入真实 LLM（关键）

把：

decidePlan()

换成：

OpenAI Tool Calling / Function Calling

2. 自动生成执行链（Agent 进化）

现在是写死的：

if (input.includes("天气"))

未来是：

AI 自动规划任务链

3. 插件化 Skill（架构升级）

自动扫描 /skills 目录

4. 加 Memory（上下文能力）

• 短期对话
• 长期用户数据

5. 前端可视化

你可以做：

执行链路可视化
Skill 调用流程图

这一步非常适合前端工程师做差异化。

九、和传统开发的本质区别

认知升级一句话：

十、总结

OpenSpec = AI 世界的“能力操作系统规范”

Agent = 基于 OpenSpec 运行的执行引擎