Pragma：构建跨 Harness 的可移植 Agent Team

"一次构建，随处运行。" 在 AI Agent 框架层出不穷的今天，Pragma 试图回答一个根本性问题：如何让 Agent 团队真正可移植、可复用？

痛点：从"一个人干活"到"团队协作"的鸿沟

2024 年下半年，Claude Code、GitHub Copilot Workspace、Cursor 等 AI Coding Agent 工具相继爆火。然而，当你试图让多个 Agent 协同完成复杂任务时，问题来了：

• 每个 Agent 框架（Codex、Claude Code、各家自研引擎）都有各自的配置方式，你写的专家定义无法迁移
• Agent 之间的交接（handoff）、共享记忆、权限控制，每个框架实现都不一样
• 同一个"代码审查专家"，你在 Cursor 里定义了一份，到 Claude Code 又要重写一遍

Pragma 的核心思路：把"Agent Team"作为最小可移植单元，用 YAML DSL 定义 Experts、Teams、Flows、Tools、Skills 和共享记忆，一次编写，随处运行。

项目概述：一套 DSL，打通所有主流 Agent 框架

Pragma 由 pqpo 团队开发（国内独立开发者，中文文档完善），是一个处于 Preview 阶段的跨框架 Agent 编排平台。它不只是一个库或工具，而是一套完整的 Agent 工作方法论的实现。

核心概念拆解

Expert（专家）：Pragma 中的基本执行单元。每个 Expert 拥有独立的 prompt、上下文边界、工具集和权限配置。你可以定义一个"代码审查专家"、"一个 QA 专家"或一个"产品经理代理"。

ExpertTeam（专家团队）：将多个 Expert 组织在一起，共享记忆层（Shared Memory）、技能（Skills）和工具（Tools）。团队成员之间可以相互交接（handoff），实现真正的多角色协作。

Flow（流程）：定义 Expert/Team 之间的执行顺序和条件分支，支持并行和串行组合。Flow 让复杂任务的编排变得可读、可维护。

Pragma.yaml DSL：所有配置都沉淀在 pragma.yaml 文件中。这是一个版本可控、可分享、可复用的 Agent 工作流定义。

Pragma Desktop：零代码构建 Agent Team

对于非技术用户，Pragma 提供了 Pragma Desktop——一个基于 Electron 的 macOS 桌面应用。通过图形界面，你可以拖拽式地定义 Expert、Team 和 Flow，无需编写 YAML。整个过程所见即所得。

跨框架集成：Codex、Claude Code 与自建系统

这是 Pragma 最具野心的部分。它不仅能在自己的运行时中执行 Agent Team，还支持将 Team 定义导出并接入到外部系统：

• Codex 集成：通过 .codex/ 目录或 MCP 协议接入 OpenAI Codex
• Claude Code 集成：通过导出格式接入 Anthropic 的 Claude Code 环境
• SDK 集成：提供 TypeScript SDK，可嵌入任何自建 AI 系统

也就是说，你在 Pragma Desktop 里构建的 Agent Team，可以"注入"到其他 Agent 运行时中使用。

技术架构：TypeScript monorepo 的工程实践

从代码组织来看，Pragma 是一个标准的大型 TypeScript monorepo，采用 pnpm workspaces 管理多包结构：

包名	职责
packages/core	Agent 运行时核心：Expert、ExpertTeam、Execution、Context System、Memory
packages/interpreter	DSL 编译器：Pragma.yaml 解析、版本迁移、Bundle 打包
packages/runtime	各 harness 的运行时适配器
apps/cli	命令行工具
apps/desktop	Electron 桌面应用（macOS）
apps/web	Web 前端界面
apps/server	后端服务
packages/built-in-agents	内置 DSL Agents

关键技术选型

• 语言：TypeScript（要求 Node.js >= 22）
• 构建工具：Turbo（monorepo 构建编排）+ pnpm workspaces
• 测试框架：Vitest
• 代码规范：ESLint + Prettier
• AI SDK：支持 OpenAI、Google GenAI、Qoder 等多模型提供商

记忆系统（Memory System）

Pragma 实现了多层次的记忆管理：

• 短期记忆：会话级别的运行时上下文
• 长期记忆：持久化存储，跨会话复用
• 共享记忆：ExpertTeam 成员共享的上下文空间
• 证据蒸馏（Evidence Distillation）：从历史执行中提取可复用的知识

上手体验：安装与运行

快速开始

# 安装依赖（需要 Node.js >= 22）
git clone https://github.com/pqpo/pragma.git
cd pragma
pnpm install

# 构建所有包
pnpm build

# 运行 CLI
pnpm --filter @pragma/cli run --help

Pragma Desktop

目前 Pragma Desktop 仅支持 macOS，官方提供预览版下载。安装后可在图形界面中：

1. 创建新的 Agent Team 项目
2. 通过界面定义 Expert 角色
3. 配置 Team 的共享工具和记忆
4. 测试运行并导出到目标 harness

环境要求

Pragma 本身是纯框架，无 GPU 需求。运行所需硬件取决于你接入的 AI 模型——如果使用云端 API（OpenAI/Anthropic），普通电脑即可；如果需要本地推理，则需要配备足够显存的 GPU。

当前局限与争议

1. 尚处于 Preview 阶段

项目当前版本为 preview，API 和 DSL 仍在快速迭代中。作者在 README 中明确标注了 status: preview，某些功能可能不稳定。

2. License 非标准开源

Pragma 采用的是 "Source Available" License（非标准 License，见 LICENSE 文件），而非流行的 MIT/Apache 2.0/GPL。这意味着你可以查看和修改源码，但商业使用可能受到限制。对于有商业化需求的团队，需要仔细评估 License 条款。

3. Desktop 仅 macOS

Pragma Desktop 当前只提供 macOS 版本。Windows 和 Linux 用户只能使用 CLI 或 Web 界面。

4. 生态建设早期

相比 AutoGen、CrewAI、LangGraph 等已有大量社区积累的框架，Pragma 的插件生态和第三方集成还比较匮乏，落地案例有限。

行业意义与前景

尽管存在局限，Pragma 的思路值得持续关注。它试图解决的是 AI Agent 领域的一个根本矛盾：框架多样化与工作流复用之间的矛盾。

当前市场现状是每家都有自己的 Agent 格式——OpenAI 的 Swarm、Anthropic 的 Agent SDK、Microsoft 的 AutoGen，各自为政。Pragma 提出的"以 Team 为可移植单元"的愿景若能普及，将极大降低 Agent 工作流的迁移成本。

项目由国内独立开发者维护，中文文档完善，对中文 AI 开发者社区相对友好。随着 AI Coding Agent 工具的持续进化，对跨框架 Agent 编排的需求只会越来越强。