通用工程智能体内核MajidAsghariTabrizi/universal-engineering-agent

通用工程智能体（UEA）——参考工具包

与配置文件无关、可运行、MIT 许可的
通用工程智能体操作内核契约参考实现。

独立于任何单一供应商。设计为可独立使用，或与
DeepSeek Harness
的 dsh-universal-harness-core 插件配合使用，或与
free-best-router 配合使用。

已发布至 DSH 的 "Show Your Plugins!" 讨论板。

什么是 UEA？

通用工程智能体（UEA） 是一种模式，而非产品。它是任何编码智能体在交付可靠工作而不成为维护负担时所需的一小组行为：

1. 检查（Inspect） 工作区并组合一个预算化的上下文包。
2. 规划（Plan） 将任务分解为分阶段的任务。
3. 实现（Implement） 这些任务，跟踪工具卫生。
4. 验证（Verify） 使用分阶段运行器（STATIC → UNIT → INTEGRATION）。
5. 分类（Classify） 将每个失败归入稳定的 10 类错误代码。
6. 恢复（Recover） 使用有界重试和不可重试的穿透处理。
7. 测试（Test） 智能体自身的代码，而不仅仅是用户的代码。
8. 泛化（Generalize） 将经验教训提炼为与配置文件无关的检查点。

9 阶段形式是完整契约：上面的 test 阶段测试智能体的代码，verify 阶段测试用户的代码。该工具包为阶段 7 提供了 31 个自测试，并为阶段 4 提供了分阶段运行器。

UEA 不是模型、不是智能体框架、也不是供应商产品。它是 LLM 驱动的工程智能体可以驻留其中并仍然保持生产安全的最小可复用外壳。

本仓库是该模式的参考实现。它用纯 Node.js 编写，零运行时依赖，可在 Node 18.17 及更高版本上运行，并附带一个自包含的 CLI 以及 31 个自测试。

为什么存在这个项目？

现实中的大多数工程智能体提示词会不断膨胀，直到变得无法维护。作者不断添加“还要做 X”和“还要记住 Y”，直到系统提示词变成 4,000 个 token 的部落知识，除了作者之外没有人能复用。

UEA 是相反的方向。它有意保持小巧，并且有意做到与配置文件无关。产品特定的知识（哪些语言、哪些部署策略、哪个安全层级）存在于配置文件（profile）中，而不是内核中。内核只拥有每个智能体都需要的东西。

本仓库是内核契约的权威参考。它是每个配置文件——包括生产配置文件、语言配置文件以及你自己的自定义配置文件——都可以依赖的东西。

与其他项目的关系

| 项目 | 与 UEA 的关系 |
|---|---|
| deepseek-ai/deepseek-harness | DSH 框架。UEA 作为 dsh-universal-harness-core 插件在 DSH 内部运行。本仓库是该插件契约的独立参考实现。 |
| dsh-universal-harness-core（DSH 插件） | 生产实现。本仓库是其开放、公开规范的对应版本，任何人都可以 npm install 并在没有 DSH 的情况下运行。 |
| MajidAsghariTabrizi/free-best-router | 一个姊妹开源项目。free-best-router 解决的是调用哪个免费模型的问题；UEA 解决的是如何围绕任意模型协调一个智能体的问题。二者互补，而非竞争。 |
| 你自己的项目 | 你可以编写一个 profile.yml（参见 examples/profiles/generic.yml），将 UEA 接入你的技术栈，并在 CI 中运行 npx universal-engineering-agent-kit verify .。 |

安装

npm install universal-engineering-agent-kit
或者，无需安装，直接从本仓库运行：
npx --prefix . uea inspect examples/sample-workspace

该工具包附带一个 uea 二进制文件，让你无需编写任何胶水代码即可使用四个最实用的命令：

uea inspect      # 打印工作区的上下文包
uea plan      # 将任务分阶段为可执行任务
uea verify       # 运行分阶段验证
uea classify       # 对失败字符串进行分类
uea test                    # 运行本工具包自身的自测
uea scan                    # 运行发布前的密钥/PII 扫描器

快速开始

git clone https://github.com/MajidAsghariTabrizi/universal-engineering-agent
cd universal-engineering-agent
npm install
npm test

查看上下文包
node bin/uea.mjs inspect examples/sample-workspace

分阶段一个任务
node bin/uea.mjs plan examples/missions/mission-add-readme.json

对失败进行分类
node bin/uea.mjs classify "permission denied while deploying"

运行分阶段验证（示例工作区中有一个故意留下的 bug；
这就是“找 bug”演示——参见 examples/missions/）
node bin/uea.mjs verify examples/sample-workspace

9 阶段内核

内核实例通过 createKernel({ workspaceRoot, stateDir, profile, maxAttempts }) 创建。
它暴露上述 9 个阶段以及一个 hygiene 追踪器。完整契约及每个阶段的
设计理由参见 docs/OPERATING-KERNEL.md。

import { createKernel } from 'universal-engineering-agent-kit'

const kernel = createKernel({
workspaceRoot: '/path/to/your/repo',
stateDir:      '/path/to/your/repo/.uea',
profile:       'generic',
maxAttempts:   3,
})

const { bundle } = await kernel.inspect()        // 1. inspect
const plan       = await kernel.plan(mission)    // 2. plan
const { trace }  = await kernel.implement(plan)  // 3. implement（排队的 trace；由你运行）
const report     = await kernel.verify()         // 4. verifymarkdown
const code       = kernel.classify(err.message)  // 5. 分类（同步）
const result     = await kernel.withRetry(fn)    // 6. 恢复
const ckpts      = await kernel.checkpoint('list') // 7. 测试 + 泛化（读取历史）

文档

| 文档 | 内容 |
|---|---|
| docs/OPERATING-KERNEL.md | 9 阶段契约，每个阶段一节，附有为什么。 |
| docs/ARCHITECTURE.md | UEA 如何融入 DSH 生态系统，以及它与其他开源项目的关系。 |
| docs/MISSIONS.md | 三个示例任务以及每个任务所演练的内容。 |
| docs/INTEGRATION.md | 如何安装、运行和扩展该工具包；如何编写你自己的 profile。 |
| docs/ROADMAP.md | 诚实的后续步骤。已完成的内容、计划中的内容、刻意不计划的内容。 |
| SECURITY.md | 威胁模型、本仓库中不包含的内容、如何报告问题。 |
| CHANGELOG.md | 发布历史。 |

局限性以及本仓库中刻意不包含的内容

UEA 是一个内核，而不是一个工作器。本参考工具包不：

- 调用任何 LLM。它是一个工具，而不是一个智能体。模型由你提供。
- 将状态持久化到数据库。检查点是磁盘上的 JSON-lines。
- 依赖 Graphify、任何厂商 SDK 或任何特定的云。DSH 生产插件提供了所有这些；内核契约并不要求它们。
- 包含任何产品特定、项目特定或厂商特定的术语。（这由每次提交时的 npm run scan 进行验证。）

完整而诚实的列表请参见 docs/ROADMAP.md。

贡献

欢迎提交 PR。门槛很低：

1. 为任何新行为添加自测（test/*.test.mjs，直接使用 node --test）。
2. 保持内核与 profile 无关。项目特定的知识放入 profile 中。
3. 不要在 PR 描述中没有书面理由的情况下引入运行时依赖。
4. 推送前运行 npm run scan；它必须保持绿色。

许可证

MIT。请参见 LICENSE。

致谢

- 感谢 DeepSeek Harness 团队提供的 dsh-universal-harness-core 插件，本工具包正是以它为蓝本。
- 感谢每一位曾与提示工程债务作斗争的智能体作者——UEA 是对这种债务的回应，而不是承担它的新方式。