README
¶
LUBAN Code
LUBAN Code 是一款运行在终端中的开源 AI 编程代理，面向真实代码库提供代码理解、修改、命令验证、会话管理和多模型接入能力。
安装
Homebrew（macOS / Linux）
brew install agent-dance/tap/luban-code
安装脚本（macOS / Linux）
curl -fsSL https://raw.githubusercontent.com/agent-dance/luban/main/install.sh | sh
脚本会下载 GitHub Release 中与当前平台匹配的归档并校验 SHA-256；默认安装到用户可写目录，不会静默使用 sudo。需要固定版本或安装目录时，请参阅安装指南。
PowerShell（Windows）
irm https://raw.githubusercontent.com/agent-dance/luban/main/install.ps1 | iex
也可以从 GitHub Releases 下载 Windows ZIP，解压后将 luban.exe 所在目录加入 PATH。
快速开始
选择一个模型提供商并设置 API key：
# DeepSeek
export DEEPSEEK_API_KEY="your-api-key"
# 或 OpenAI
export OPENAI_API_KEY="your-api-key"
# 或 Anthropic
export ANTHROPIC_API_KEY="your-api-key"
进入项目并启动交互界面：
cd your-project
luban
也可以执行一次性任务：
luban -p "解释这个仓库的架构"
LUBAN Code 会根据可用的 key 自动选择提供商；可用 --provider 和 --model 显式指定。完整环境变量、项目配置和权限选项见配置指南。
升级与卸载
# Homebrew
brew upgrade luban-code
brew uninstall luban-code
# 安装脚本安装的版本
curl -fsSL https://raw.githubusercontent.com/agent-dance/luban/main/install.sh | sh
Windows 用户可重新运行 install.ps1 升级；卸载方式和数据目录说明见安装指南。
校验下载
Release 同时发布 SHA-256 校验文件、SBOM 和 GitHub artifact attestation。下载归档后可验证：
sha256sum -c checksums.txt --ignore-missing
gh attestation verify luban-code_Darwin_arm64.tar.gz --repo agent-dance/luban
macOS 可使用 shasum -a 256 <archive> 与 checksums.txt 中对应条目比较。安装脚本会自动执行 checksum 校验，但直接下载的用户应手动校验。
支持平台
| 操作系统 | 架构 | 发布格式 | 安装方式 |
|---|---|---|---|
| macOS | Apple Silicon (arm64) |
tar.gz |
Homebrew、install.sh、手动下载 |
| macOS | Intel (x86_64) |
tar.gz |
Homebrew、install.sh、手动下载 |
| Linux | x86_64 |
tar.gz |
Homebrew、install.sh、手动下载 |
| Linux | arm64 |
tar.gz |
Homebrew、install.sh、手动下载 |
| Windows | x86_64 |
zip |
install.ps1、手动下载 |
运行时不要求安装 Go。源码构建需要仓库 go.mod 声明的 Go 版本。平台归档名称和离线安装步骤见安装指南。
文档与项目治理
性能与评测
15 题优化实测：Luban 总耗时低 28.8%，Token 低 61.7%，LLM 调用低 30.8%
以 Codex 为 0% 基准；负值表示 Luban 更低。每格按“优化前 → 优化后 / Codex（优化后相对 Codex）”展示。针对原先落后的 7 道题完成优化复测后，Luban 的 15 题合计耗时从高于 Codex 96.3% 变为低 28.8%，超时从 2 次降为 0 次；7 道复测题的耗时与 Token 均已低于 Codex。
20 题目录已经冻结，但按要求在第 15 题后停止，最后 5 题未运行。复测沿用原有本地代理方式，没有下载 Docker 镜像；新增 10 题未做官方判分，因此 resolved 只展示原 5 题结果。
| 任务 | 耗时：优化前 → Luban / Codex（变化） | Token：优化前 → Luban / Codex（变化） | LLM 调用：优化前 → Luban / Codex（变化） | resolved / 状态 |
|---|---|---|---|---|
| Fabric | 169.3s → 169.3s / 219.5s（−22.9%） | 128,319 → 128,319 / 581,257（−77.9%） | 8 → 8 / 14（−42.9%） | 是 / 是；沿用基线 |
| agents-js | 265.3s → 265.3s / 521.9s（−49.2%） | 666,894 → 666,894 / 1,429,141（−53.3%） | 22 → 22 / 30（−26.7%） | 是 / 是；沿用基线 |
| kube | 253.7s → 253.7s / 319.1s（−20.5%） | 402,703 → 402,703 / 644,164（−37.5%） | 16 → 16 / 19（−15.8%） | 否 / 否；沿用基线 |
| skim | 277.3s → 277.3s / 513.9s（−46.0%） | 582,076 → 582,076 / 1,518,938（−61.7%） | 17 → 17 / 28（−39.3%） | 是 / 是；沿用基线 |
| IWYU | 277.3s → 277.3s / 616.0s（−55.0%） | 431,561 → 431,561 / 2,238,240（−80.7%） | 20 → 20 / 37（−45.9%） | 否 / 否；沿用基线 |
| ninja | 547.0s → 547.0s / 611.1s（−10.5%） | 1,435,423 → 1,435,423 / 2,859,848（−49.8%） | 33 → 33 / 39（−15.4%） | 未判分；沿用基线 |
| crush | 153.7s → 153.7s / 230.0s（−33.2%） | 74,322 → 74,322 / 374,868（−80.2%） | 7 → 7 / 13（−46.2%） | 未判分；沿用基线 |
| floci | 246.6s → 169.4s / 191.9s（−11.7%） | 372,478 → 168,545 / 410,507（−58.9%） | 15 → 10 / 14（−28.6%） | 未判分；正式复测 |
| eza | 1,800.2s → 245.3s / 470.8s（−47.9%） | — → 394,477 / 2,234,769（−82.3%） | 4 → 15 / 37（−59.5%） | 未判分；超时 → 完成 |
| assistant-ui | 632.2s → 123.9s / 194.6s（−36.3%） | 459,912 → 74,139 / 322,474（−77.0%） | 23 → 7 / 12（−41.7%） | 未判分；正式复测 |
| actor-framework | 1,439.4s → 282.8s / 312.6s（−9.5%） | 1,070,509 → 349,663 / 977,723（−64.2%） | 31 → 16 / 22（−27.3%） | 未判分；正式复测 |
| lima | 372.6s → 372.6s / 392.6s（−5.1%） | 548,817 → 548,817 / 1,313,747（−58.2%） | 18 → 18 / 23（−21.7%） | 未判分；沿用基线 |
| springdoc | 1,800.2s → 218.3s / 274.0s（−20.3%） | — → 612,031 / 911,769（−32.9%） | 2 → 20 / 18（+11.1%） | 未判分；超时 → 完成 |
| napi-rs | 1,354.1s → 292.8s / 340.2s（−13.9%） | 1,287,671 → 372,716 / 660,232（−43.5%） | 37 → 14 / 18（−22.2%） | 未判分；正式复测 |
| G2 | 1,490.6s → 371.8s / 436.2s（−14.8%） | 2,651,755 → 615,804 / 1,411,342（−56.4%） | 45 → 22 / 30（−26.7%） | 未判分；正式复测 |
| 合计 | 11,079.5s → 4,020.6s / 5,644.5s（−28.8%） | 10,112,440 → 6,857,490 / 17,889,019（−61.7%）* | 298 → 245 / 354（−30.8%） | 超时 2 → 0 / 0；patch 15/15 / 15/15 |
* 优化前 eza、springdoc 超时且无可解析 Token，因此优化前 Token 合计只有 13 题；优化后与 Codex 的百分比按完整 15 题计算。新增任务未判分，不能用于比较解决率。每项工程优化、原因、关联任务和实际效果均沉淀在完整报告中。
Directories
¶
| Path | Synopsis |
|---|---|
|
benchmark
|
|
|
agentic/cacheevidence
Package cacheevidence projects prompt-cache request policy without retaining prompt text, cache keys, or other request content.
|
Package cacheevidence projects prompt-cache request policy without retaining prompt text, cache keys, or other request content. |
|
agentic/cmd/agenticbench
command
|
|
|
agentic/cmd/agenticpilot
command
|
|
|
agentic/cmd/benchmark
command
|
|
|
agentic/evidenceproxy
Package evidenceproxy implements a prompt-blind reverse proxy used only by the benchmark harness.
|
Package evidenceproxy implements a prompt-blind reverse proxy used only by the benchmark harness. |
|
agentic/harness
Package harness defines the reproducible Agentic Coding benchmark protocol.
|
Package harness defines the reproducible Agentic Coding benchmark protocol. |
|
agentic/pierbackend
Package pierbackend binds the generic benchmark contract to a frozen Pier runtime and DeepSWE-style Harbor tasks.
|
Package pierbackend binds the generic benchmark contract to a frozen Pier runtime and DeepSWE-style Harbor tasks. |
|
agentic/pilot
Package pilot provides a development-only, fail-closed five-task runner.
|
Package pilot provides a development-only, fail-closed five-task runner. |
|
agentic/report
Package report turns content-addressed agentic benchmark artifacts into a deterministic, self-contained HTML report.
|
Package report turns content-addressed agentic benchmark artifacts into a deterministic, self-contained HTML report. |
|
agentic/report/cmd/devreport
command
|
|
|
agentic/report/cmd/reportgen
command
|
|
|
benchmark-results
|
|
|
agentic-2026-07-27
command
|
|
|
Package brand centralizes LUBAN Code product identity.
|
Package brand centralizes LUBAN Code product identity. |
|
Package buildinfo captures the identity of the running executable and compares that immutable identity with a repository checkout.
|
Package buildinfo captures the identity of the running executable and compares that immutable identity with a repository checkout. |
|
Package cli provides minimal flag parsing for LUBAN Code using only the standard library flag package — no external dependencies.
|
Package cli provides minimal flag parsing for LUBAN Code using only the standard library flag package — no external dependencies. |
|
cmd
|
|
|
cache-bench
command
cache_bench sends multiple rounds through the real QueryLoop to measure actual prompt cache hit rates against a live OpenAI-compatible backend.
|
cache_bench sends multiple rounds through the real QueryLoop to measure actual prompt cache hit rates against a live OpenAI-compatible backend. |
|
luban-code
command
|
|
|
Package i18n provides multi-language support for the LUBAN Code UI.
|
Package i18n provides multi-language support for the LUBAN Code UI. |
|
internal
|
|
|
agent
Package tools — agent_feature_gates.go provides defaults for the builtin-set feature gates referenced by agent.go.
|
Package tools — agent_feature_gates.go provides defaults for the builtin-set feature gates referenced by agent.go. |
|
agentic/inspect
Package inspect implements the repository-scoped composite Inspect tool.
|
Package inspect implements the repository-scoped composite Inspect tool. |
|
contracts/compactproof
Package compactproof defines the content-free, tool-owned facts that survive Agentic V2 microcompaction.
|
Package compactproof defines the content-free, tool-owned facts that survive Agentic V2 microcompaction. |
|
contracts/contextupdate
Package contextupdate defines the model-to-runtime proposal protocol for progressive context handling.
|
Package contextupdate defines the model-to-runtime proposal protocol for progressive context handling. |
|
contracts/execution
Package execution defines the runtime-neutral context carried through one model-requested tool invocation.
|
Package execution defines the runtime-neutral context carried through one model-requested tool invocation. |
|
contracts/filemutation
Package filemutation defines the capability boundary used by tools that mutate files through a command or another non-file-domain executor.
|
Package filemutation defines the capability boundary used by tools that mutate files through a command or another non-file-domain executor. |
|
contracts/interaction
Package interaction defines surface-neutral contracts for structured user interaction.
|
Package interaction defines surface-neutral contracts for structured user interaction. |
|
contracts/permission
Package permission defines the runtime-neutral authorization contract shared by execution loops, engine orchestration, and first-party permission policy.
|
Package permission defines the runtime-neutral authorization contract shared by execution loops, engine orchestration, and first-party permission policy. |
|
contracts/stream
Package stream defines the surface-neutral events emitted by the model runtime and consumed by presentation, orchestration, and embedding layers.
|
Package stream defines the surface-neutral events emitted by the model runtime and consumed by presentation, orchestration, and embedding layers. |
|
contracts/toolmeta
Package toolmeta defines implementation-neutral metadata contracts shared by tool producers, the registry, and discovery consumers.
|
Package toolmeta defines implementation-neutral metadata contracts shared by tool producers, the registry, and discovery consumers. |
|
contracts/workspacerevision
Package workspacerevision binds a verification tool execution to the exact mutation state produced by a preceding tool in the same model response.
|
Package workspacerevision binds a verification tool execution to the exact mutation state produced by a preceding tool in the same model response. |
|
mcp/auth
Package auth owns transport-independent MCP OAuth behavior.
|
Package auth owns transport-independent MCP OAuth behavior. |
|
mcp/protocol
Package protocol owns MCP's transport-independent JSON-RPC wire contract.
|
Package protocol owns MCP's transport-independent JSON-RPC wire contract. |
|
mcp/transport
Package transport owns the MCP JSON-RPC client and concrete transports.
|
Package transport owns the MCP JSON-RPC client and concrete transports. |
|
messagecontrol
Package messagecontrol owns the capability used to establish that a model-visible control message was created by this runtime.
|
Package messagecontrol owns the capability used to establish that a model-visible control message was created by this runtime. |
|
presentation
Package presentation defines renderer-neutral events, projections, and capabilities shared by terminal, full-screen TUI, and application adapters.
|
Package presentation defines renderer-neutral events, projections, and capabilities shared by terminal, full-screen TUI, and application adapters. |
|
runtime/compact
Package compact implements full, partial, automatic, and tool-result context compaction together with the trusted controls used to install their output.
|
Package compact implements full, partial, automatic, and tool-result context compaction together with the trusted controls used to install their output. |
|
runtime/flight
Package flight contains the deterministic correctness state machine for an agentic coding flight.
|
Package flight contains the deterministic correctness state machine for an agentic coding flight. |
|
runtime/skillauthority
Package skillauthority validates the skill catalog authority pinned to one runtime-owned tool execution.
|
Package skillauthority validates the skill catalog authority pinned to one runtime-owned tool execution. |
|
store/secureio
Package secureio provides directory-descriptor-relative filesystem operations for private runtime state.
|
Package secureio provides directory-descriptor-relative filesystem operations for private runtime state. |
|
tokenizer
Package tokenizer provides model-text token counters without depending on runtime orchestration packages.
|
Package tokenizer provides model-text token counters without depending on runtime orchestration packages. |
|
tools/config
Package config exposes runtime configuration reads and writes as a tool.
|
Package config exposes runtime configuration reads and writes as a tool. |
|
tools/file
Package file — file_edit.go provides the FileEditTool.
|
Package file — file_edit.go provides the FileEditTool. |
|
tools/interaction
Package interaction implements interactive, model-facing tools.
|
Package interaction implements interactive, model-facing tools. |
|
tools/schedule
Package schedule implements the CronCreate, CronDelete, and CronList tools and the runtime that delivers their scheduled work.
|
Package schedule implements the CronCreate, CronDelete, and CronList tools and the runtime that delivers their scheduled work. |
|
tools/search
Package search restricts Glob/Grep search roots and emitted matches to the allowed directories in the invocation's runtime scope.
|
Package search restricts Glob/Grep search roots and emitted matches to the allowed directories in the invocation's runtime scope. |
|
tools/toolbase
Package toolbase provides domain-neutral helpers shared by tool packages.
|
Package toolbase provides domain-neutral helpers shared by tool packages. |
|
tools/web
Package tools implements the raw-content cache used by WebFetch.
|
Package tools implements the raw-content cache used by WebFetch. |
|
ui/terminal
Package ui provides terminal rendering abstractions for the CLI layer.
|
Package ui provides terminal rendering abstractions for the CLI layer. |
|
ui/theme
Package theme owns the shared visual palette for terminal surfaces.
|
Package theme owns the shared visual palette for terminal surfaces. |
|
ui/tui
Package tui provides the go-tui based terminal UI for the CLI.
|
Package tui provides the go-tui based terminal UI for the CLI. |
|
Package observability provides bounded, process-local incident metrics.
|
Package observability provides bounded, process-local incident metrics. |
|
Package runtimeevent projects private runtime events into explicit audience schemas.
|
Package runtimeevent projects private runtime events into explicit audience schemas. |
|
Package sdk implements the NDJSON stream-JSON transport layer that allows external processes (e.g.
|
Package sdk implements the NDJSON stream-JSON transport layer that allows external processes (e.g. |
|
Package skills provides skill loading, parsing, and management.
|
Package skills provides skill loading, parsing, and management. |
Click to show internal directories.
Click to hide internal directories.