Excalibur

Excalibur 快速入门

开源全周期 AI 编程 Agent，不只写代码—决定做什么、验证做对了、审计做过什么，一条命令跑完整个产品周期。

这是什么？适合谁？

Excalibur 是一个面向产品工程师（Product Engineer）的开源 AI 编程 Agent，核心定位是覆盖完整产品周期而不仅仅是代码生成。它的全周期包含八个阶段：Discover（发现/评估需求）-> Plan（规划）-> Build（构建）-> Test（测试）-> Docs（文档）-> Review（审查）-> Ship（发布）-> Audit（审计）。

与 Claude Code、Cursor Agent 等纯编码工具相比，Excalibur 有三个差异化能力：

1. Discovery 阶段：在写任何代码之前，Excalibur 先评估”是否值得做”—衡量范围、证据和风险，给出 build/validate/don’t-build 的建议。这是其他 AI 编程工具没有的能力。
2. Time-travel 事件日志：每次运行都是一个不可变的追加式事件日志（immutable append-only event log），可以像视频一样回放、从任意步骤分叉新运行。live 视图、replay、dashboard 和 audit trail 是同一份数据，字节级一致。
3. Adversarial Verification Mesh（对抗验证网格）：发布前通过类型化 claims 门控（tests_passed/type_safe/no_secrets）确保质量，不是简单的测试通过就放行。

适合谁？三类人最受益：一是产品工程师，需要从需求评估到发布审计的全流程自动化；二是技术团队 lead，需要审计 Agent 的工作过程和决策依据；三是有治理需求的企业，Enterprise 版提供 SSO/RBAC/合规审计/SIEM 集成。注意：Excalibur 需要自备 LLM API Key（支持 Anthropic/OpenAI/Ollama 等），核心功能免费开源（Apache-2.0）。

准备工作

• 设备要求：macOS 或 Linux（CLI + 本地 Web Dashboard），Node.js 环境
• 账号要求：无需注册账号，Core 版完全本地运行；Enterprise 版需联系销售
• API Key：需自备至少一个 LLM API Key（Anthropic/OpenAI/Azure 等兼容 OpenAI 协议的提供商）
• 安装方式：npm install -g @excalibur-oss/excalibur
• 许可协议：Apache-2.0 开源免费

3 步快速上手

第 1 步：安装 Excalibur

npm install -g @excalibur-oss/excalibur

安装后验证：

excalibur --version

第 2 步：配置 API Key 并启动

# 设置 API Key（以 Anthropic 为例）
export ANTHROPIC_API_KEY=sk-ant-xxxxx

# 启动交互式 shell
excalibur

首次启动会自动检测 Key 并引导配置。你也可以在运行中用 /models 命令切换模型：

/models
  ● claude-opus-4     good · default
  ○ gpt-4o
  ○ llama-3.3-70b     fast · paired
  ○ ollama/qwen       local

第 3 步：运行第一个全周期任务

在 m-shell（交互式 shell）中输入任务：

Add rate limiting to the public API

Excalibur 会自动进入全周期流程：

L4 - Full agentic · kimi-k2.7-code

✓ Plan          4 steps
│ ⠹ Implement   api/limiter.ts
│   └ edit api/limiter.ts     +38 −4
│   └ ▸ pnpm test api         running…
│ ○ Verify
│ ○ Document
│ ○ Review
│ ○ Pull Request

████░░░░ 1m12s · $0.42 · standard-safe · no push

进阶用法

Discovery 阶段：评估是否值得做

excalibur discover "Add AI invoice summaries"

Excalibur 会从五个维度评估：clarity（清晰度）、evidence（证据）、scope（范围）、risk（风险）、readiness（就绪度），最终给出建议（如 needs_validation），并创建工作项 WI-142。

Time-travel：回放和分叉

在运行中按 Esc-Esc 可以实时回退到任意步骤。回放视图支持从任意步骤分叉新运行（fork from here），好的前缀免费重放，只有变化部分重新执行。

本地 Web Dashboard

excalibur serve

打开浏览器访问 localhost:7878，你得到一个任务看板（Kanban）、运行浏览器、成本图表和实时编排时间线。无需账号、无需云端，完全本地运行。

• --write 模式：从浏览器面板驱动运行
• --share 模式：生成只读分享链接

自主级别（L0-L4）

Excalibur 支持五级自主度，逐任务调整：

• L0：快速回答，不执行操作
• L1：建议方案，需人工批准每步
• L2：执行简单任务，关键操作需批准
• L3：自主执行，仅高危操作需批准
• L4：完全自主，在隔离分支中运行

多 Agent 编排（Swarm）

大任务自动拆分为多个 Agent 并行执行，每个在隔离的 worktree 中工作：

excalibur run "Refactor auth module and add OAuth2 support" --autonomy L4

Excalibur 会自动评估任务规模，分配 3 个独立 Agent 在隔离 worktree 中并行工作。

内置工作流

14 个内置工作流 + 14 个方法论，YAML 可定制，每个含质量门控：

excalibur workflow list
  standard-feature    绿地功能开发
  bug-fix             缺陷修复
  refactor            重构
  migration           技术迁移
  ...

常见踩坑

踩坑 1：全周期执行耗时较长

• 症状：L4 全周期任务运行 5-10 分钟才完成
• 原因：Discovery + Plan + Build + Test + Docs + Review 全阶段串行执行，每步都调用 LLM
• 解决：简单任务用 L2 级别跳过 Discovery/Docs/Review；或用 --quick 模式只跑 Build+Test

踩坑 2：API 费用超预期

• 症状：一次 L4 运行花费 $0.50-$2.00
• 原因：全周期多步调用 frontier 模型，Token 消耗大
• 解决：配置 good+fast 模型对，简单步骤自动用 cheap 模型；Dashboard 有实时成本追踪和预算告警

踩坑 3：Discovery 评估质量依赖模型能力

• 症状：Discovery 给出的建议过于保守或过于乐观
• 原因：Discovery 阶段完全依赖 LLM 的产品判断力，弱模型表现差
• 解决：用 Claude Opus 4 或 GPT-4o 等 frontier 模型跑 Discovery；/models 切换

常见问题 FAQ

Q1：Excalibur 和 Claude Code 有什么区别？

A：Claude Code 是纯编码 Agent，Excalibur 覆盖完整产品周期（含 Discovery 决策阶段和 Audit 审计阶段）。Excalibur 还有 Time-travel 事件日志（可回放/分叉）和本地 Web Dashboard，这些 Claude Code 没有。

Q2：需要联网吗？

A：Core 版完全本地运行，无需注册账号。但需要访问 LLM API（Anthropic/OpenAI 等）。如果用 Ollama 本地模型，可以完全离线。

Q3：支持哪些 IDE？

A：提供 VS Code、Cursor、Windsurf 的 IDE 扩展。也可以纯 CLI 使用。

Q4：支持哪些模型？

A：所有 OpenAI 兼容协议的模型（含 Azure）、Anthropic Claude 系列、Ollama 本地模型。支持 good+fast 模型对，自动在复杂和简单步骤间切换。

参考链接

• Excalibur 官网：https://getexcalibur.dev
• GitHub 仓库：https://github.com/ExcaliburOSS/excalibur-core
• 文档：https://getexcalibur.dev/docs/
• 定价：https://getexcalibur.dev/pricing/
• npm 包：@excalibur-oss/excalibur
• Apache-2.0 License

本文基于官方文档和公开资料整理，AI辅助生成。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。