Excalibur

Excalibur 快速入门

大多数 Agent 只会写代码。Excalibur 懂整个产品周期——从决定该不该做，到证明做对了什么。

这是什么？适合谁？

Excalibur 是由 Rafael Casuso 开发的开源 AI 编程 Agent，核心理念是「产品工程师需要的不只是代码生成，而是覆盖完整产品周期的智能助手」。它的工作流从 Decide（决定要不要做）开始，经过 Plan→Build→Test→Docs→Review→Ship，最终到 Audit（审计），全程由一个 Agent 自主推进。

具体来说，当你输入「给公开 API 加限流」，Excalibur 内部会：

• Discovery 阶段：先评估这个需求是否值得做——检查现有代码库、分析影响范围、评估风险，给出「build / validate / don’t-build」的建议。这是其他编程 Agent 都不具备的能力。
• Plan 阶段：把需求拆成可执行步骤，估算工作量。
• Build 阶段：多 Agent 并行（swarm），在隔离的 git worktree 中各自完成任务。
• Test + Docs 阶段：测试和文档不是事后补的，而是工作流中的内置阶段。
• Review + Ship 阶段：通过 Adversarial Verification Mesh（对抗验证网格）检查类型安全、无密钥泄露、测试通过，然后生成 PR。
• Audit 阶段：回放整个过程的不可变事件日志，审查每一步决策。

Excalibur 的杀手锏是 Time-travel 事件日志：每次运行产生一个不可变的、只追加的事件流，你可以像拖视频进度条一样回放、从任意步骤分支新运行。这个事件流同时驱动实时视图、回放、仪表盘和审计轨迹——字节级一致，没有其他工具能做到。

适合谁？个人开发者和小团队，想要一个能帮你判断「该不该做」而不只是「怎么做」的编程 Agent；产品工程师，需要从需求到交付的端到端自动化；追求透明度的团队，希望每一次 Agent 操作都有完整的可审计日志。

不适合「我只想快速修一个 bug」——那种场景用 Claude Code 或 Cursor 更直接；也不适合需要大量社区插件和第三方集成的场景——Excalibur 生态还很新。

准备工作

1. Node.js 18+：Excalibur 是 Node.js 项目，推荐 20+。访问 https://nodejs.org/ 安装。
2. 大模型 API Key：Excalibur 不自带模型，需自备 Anthropic / OpenAI / Gemini / Ollama 等 API Key。推荐 Claude Opus 4 做主模型 + 一个便宜的模型做辅助。
3. Git：用于克隆仓库和 worktree 隔离。访问 https://git-scm.com/ 安装。

3 步快速上手

第 1 步：全局安装

打开终端，执行：

npm install -g @excalibur-oss/excalibur

安装完成后验证：

excalibur --version

应该输出类似 1.16.4 的版本号。

第 2 步：配置 API Key

在项目根目录创建 .env 文件，填入你的 API Key：

# 至少配置一个
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
# 可选：本地模型
OLLAMA_HOST=http://localhost:11434

Excalibur 会自动读取 .env，且该文件已在 .gitignore 中排除，不会误提交。

第 3 步：跑第一个任务

进入你的项目目录，执行：

cd your-project
excalibur run "Add error handling to the API endpoints"

Excalibur 会进入交互式 TUI 界面，你会看到：

• 左侧：任务列表和步骤进度
• 右侧：实时终端输出
• 底部：状态栏（耗时、花费、安全模式）

默认是 standard-safe 模式——不会自动推送代码。如果想让它全自动：

excalibur run "Add rate limiting to the public API" --level L4

L4 是最高自主级别，Excalibur 会自主完成 Plan→Build→Test→Docs→Review→PR 全流程。

核心功能速览

Time-travel 事件日志

按 Esc-Esc 进入回放模式，拖动时间轴回看任意步骤。从某个步骤点「fork from here」可以分支新运行，之前的好前缀会缓存复用，只重新执行变化的部分。

Discovery 阶段

在任何代码生成之前，Discovery 分析需求清晰度、证据充分性、范围合理性和风险，给出「build / validate / don’t-build」建议。这个关卡能帮你毙掉不值得做的需求。

Web 仪表盘

excalibur serve

打开 http://localhost:7878，你会看到：

• Kanban 看板（Backlog / Running / Done）
• 实时任务进度和成本统计
• --write 模式：从浏览器直接驱动 Agent
• --share 生成只读分享链接

多模型切换

运行中按 /models 可以热切换模型。支持 Anthropic（Claude Opus 4 / Sonnet）、OpenAI（GPT-4o）、Ollama 本地模型等。主模型处理复杂推理，辅助模型做快速补全——自动配对。

Swarm 多 Agent 并行

大任务自动拆分为多个 Agent，在隔离的 git worktree 中并行开发，最后合并。每个 Agent 独立运行，互不干扰。

常见踩坑

1. 「npm install 报权限错误」：Windows 上用管理员权限打开终端，Mac/Linux 上如果不用 nvm 管理 Node 可能需要 sudo。
2. 「Discovery 阶段一直跑不完」：Discovery 依赖模型推理质量，弱模型可能卡住。建议用 Claude Opus 4 或 GPT-4o。
3. 「跑一半 API Key 额度用完」：全周期运行消耗 token 较多（典型任务 $0.5-2），建议在 API 平台设置额度告警。
4. 「国内网络无法访问 Anthropic API」：需要代理或使用 OpenAI 兼容的国内模型端点。
5. 「Windows 上 TUI 显示异常」：确保使用 Windows Terminal 而非 cmd.exe，cmd.exe 不支持 TUI 渲染。
6. 「Web 仪表盘 localhost:7878 打不开」：确认 excalibur serve 正在运行，且端口未被其他进程占用。

初级用法

• 快速修复 bug：excalibur run "Fix the login timeout bug" → 自动定位代码 → 修复 → 测试 → 生成 PR
• 代码审查：excalibur run "Review this PR for security issues" → 自动检查安全漏洞、类型错误、密钥泄露
• 写文档：excalibur run "Generate API documentation for the /users endpoints" → 自动生成 API 文档
• 技术债务清理：excalibur run "Refactor the payment module to use the new SDK" → 全流程重构

高级玩法

• 自定义 Agent 角色：通过自定义 Persona 创建专用 Agent（如「安全审计员」只做安全检查，「性能优化师」只做性能调优）
• MCP 协议扩展：Excalibur 原生支持 MCP，可以连接外部工具（数据库、API、文件系统）扩展 Agent 能力
• CI/CD 嵌入：在 GitHub Actions 中调用 excalibur 做自动 Code Review 和测试
• 多项目编排：一个 excalibur 进程可以管理多个项目的并行任务，通过 Web 仪表盘统一监控

小技巧

1. 用 --share 分享运行记录：excalibur run "..." --share 生成只读链接，团队成员可以查看完整运行过程。
2. 先跑 Discovery 再决定：大需求先用 excalibur run "..." --discovery-only 做评估，确认值得做再投入完整流程。
3. L0 模式做简单任务：不需要全周期时用 --level L0（纯问答模式），省 token 省钱。
4. 保留 .env 的模型配置灵活切换：主模型和辅助模型可以在 .env 中分别配置，不同项目用不同模型组合。
5. 定期 excalibur update：项目更新频繁（v1.16.4 已发布 39 个 tag），定期更新获得最新功能。

参考链接

• Excalibur 官网
• GitHub 仓库
• Excalibur 文档
• Excalibur 定价
• npm 包