Sheernox/cedr · 上手攻略

仓库：Sheernox/cedr
链接：https://github.com/Sheernox/cedr
分类：agent / 开发工具（多 agent 编排与治理）
作者：spark
更新：2026-11-04

版本说明：本文基于 2026-11-04 抓取的 README（main 分支）与 docs/route.md 设计契约。仓库 README 明确标注 public beta，命令与文件格式在 1.0 前仍可能变动。抓取到的搜索摘要中 GitHub Action 示例出现过 v0.3.0 与旧式 cedr lint / cedr verify 写法，而当前 README 已改为 cedr guard lint / cedr guard verify 与 Sheernox/cedr@vX.Y.Z 占位——本文以当前 README 实抓内容为准，具体 release tag 请以 releases 页为准（⚠️ 版本浮动）。

一、这是什么

cedr 是 cedr.dev 背后的命令行工具，用 Rust 编写，Apache-2.0 许可，定位是「每个 coding agent，一个控制面板」。它不是又一个 agent 本身，而是站在多个 agent 之上的路由与治理层，把六个能力打包成一个二进制：

子命令	职责
`cedr route`	按工作类型挑选 agent / 模型 / effort，依据各订阅计划的剩余额度
`cedr council`	每家厂商各出一名 reviewer，合并报告、归并同处问题、裁决门禁
`cedr guard`	lint agent 配置，把 skill 与 MCP server 锁进 `.cedr/guard.lock`，CI 检出漂移
`cedr sync`	规则 / skills / MCP / 权限 / hooks 只写一份，编译成各家 agent 的原生文件
`cedr monitor`	汇总各 agent 本地日志的 token、缓存、API 等价成本、会话与额度水位
`cedr bench`	用真实任务跑 baseline vs candidate，测试判定胜负，在预算内输出通过率与可信度

关键点：cedr mcp 可把上述能力暴露成 MCP stdio 服务，因此任何会说 MCP 的 agent 都能直接调用它。

README 的安全边界相当克制：cedr 不读 agent 凭据、不代你调用厂商 API；额度来自 agent 自己的 statusline 或 CLI；picks / verdicts / stats 默认留在本机；推送时只发计数、名称、版本、哈希，不发 prompt、响应、路径与密钥。

二、解决什么问题

同时用 Claude、Codex、Cursor、Gemini、Copilot、opencode、Grok 的人会遇到一串互相纠缠的痛点，cedr 的六条产品线基本是一一对应：

选错模型导致额度打满。 手动在几个 CLI 之间挑，常把大任务派给只剩 4% 额度的那个订阅。route 依据各计划的 percent 使用率自动选，并跳过接近上限的计划。
多厂商 review 结论打架。 一个说 P0，一个说通过。council 合并归组各报告，任何 P0/P1 直接阻断，且报告数不足时绝不静默放行。
agent 配置漂移。 skills 与 MCP server 被随手改、版本悄悄升级、权限悄悄扩大。guard 用 lockfile 固定哈希，CI 里 guard verify 让变更可见。
配置重复维护。 每个 agent 一套规则，改一处要改七处。sync 单一源 + 编译输出，CI 检测 drift，手改默认不被覆盖（除非 --force）。
花费黑洞。 不知道 token 花在哪、离额度还有多远。monitor 把本地日志汇总成视图，缺数据就标 unknown 而不是猜。
换模型/换 agent 靠感觉。 bench 用带测试的真实任务集，输出通过率、成本与差异可信度。

三、快速安装

README 给的是「下载 release 归档、解压、放进 PATH」，而不是 curl | sh：

# Linux x86_64 示例
curl -fsSL https://github.com/Sheernox/cedr/releases/latest/download/cedr-linux-x86_64.tar.gz | tar -xz
install -m 755 cedr-linux-x86_64/cedr ~/.local/bin/cedr
cedr --version

平台归档名：cedr-linux-x86_64.tar.gz / cedr-linux-arm64.tar.gz / cedr-macos-arm64.tar.gz / cedr-macos-x86_64.tar.gz / cedr-windows-x86_64.zip。

也可以从源码装（需要较新的稳定 Rust 工具链）：

cargo install --locked --git https://github.com/Sheernox/cedr cedr

前置条件：Linux 构建需要 glibc 2.34 或更新（Ubuntu 22.04 / Debian 12 / RHEL 9+）。每个 release 提供 SHA256SUMS，并带签名构建溯源，可用 gh attestation verify <archive> --repo Sheernox/cedr 验证。

自动更新：cedr 每天后台检查一次 release，校验 SHA256 后自替换。cedr update 立即更新，cedr update --check 只报告不执行，cedr update --auto off（或 CEDR_NO_AUTO_UPDATE=1）关掉每日检查。CI 中不会自动更新；cargo install 装的版本请用 cargo 更新。

四、核心用法

4.1 诊断起步：doctor

cedr doctor            # 检查 account / Route / MCP / Monitor / Sync / Guard 配置并给出修复提示
cedr doctor --format json   # 给 agent 消费

它不改动任何东西，失败退出码 1，仅有警告时退出 0。

4.2 Route：按额度选 agent

配置写在 ~/.config/cedr/routes.toml（查找顺序：--config PATH → $CEDR_ROUTES → 从当前目录向上最近的 .cedr/routes.toml → $XDG_CONFIG_HOME/cedr/routes.toml）。路由是按人平衡的（因为它平衡的是你的订阅计划），所以用户级文件是常态，仓库级文件用于覆盖。

version = 1

[orchestrator]        # 你当前所在的 agent：没有别人该接的工作它会自己留着
harness = "claude"
model = "opus"

[harnesses.claude]
expect = ["five_hour", "seven_day"]
effort_option = "effort"

[harnesses.codex]
expect = ["primary"]
effort_option = "reasoningEffort"

[[readings]]           # 计划用量从哪来
kind = "claude-statusline"
harness = "claude"

[[readings]]
kind = "codex"
harness = "codex"

[routes."review.code"]
work = "Independent correctness and security review"
role = "review"
candidates = [
  { target = "codex/sol", effort = "high", tier = 1 },
  { target = "claude/sonnet", effort = "high", tier = 1 },
  { target = "self" },
]

要让 cedr 看到 Claude 的计划用量，把它设成 ~/.claude/settings.json 的 statusline（加 -- <你的命令> 可保留原有 statusline）：

{ "statusLine": { "type": "command", "command": "cedr route statusline" } }

然后挑选、记录结论：

cedr route pick review.code
# codex/gpt-6.1-sol high | balanced:31%<claude=64% | codex s22% w31%; claude s64% w48% | rules 770517e | pick p-979e77351990>

cedr route verdict p-979e77351990 accepted
cedr route stats        # 每条 route / 每个模型分别表现如何
cedr route pools        # 各计划还剩多少空间
cedr route list

阈值语义值得记：session_conserve / weekly_conserve 默认 85、out 默认 90；conserve_sizes 决定「处于 conserve 状态的计划仍可接哪类工作」，unknown_sizes（默认 ["small","medium"]）决定「状态未知的计划仍可接哪类工作」。取阈值按最具体层覆盖：route 的 harness_thresholds > route 的 thresholds > harness 的 > 全局 > 默认值。

4.3 Council：多厂商合并评审

cedr council plan review.council   # 指定合格评审者与法定人数
cedr council merge <report1> <report2> ...   # 合并报告并裁决门禁

Council 支持候补成员、指定评审者、修订设置与不限轮次（带停滞停止）。某条 route 设 council = true，即可让每个合格候选都参与而非只选一个。

4.4 Guard：锁定 skill 与 MCP server

cedr guard lint       # 找出仓库 agent 配置里的问题
cedr guard lock       # 把所有 skill 与 MCP server 固定进 .cedr/guard.lock
cedr guard verify     # 离线校验：配置与 lock 不一致就失败
cedr guard outdated   # 查看 npm 上的新版本及其 surface 变化（不运行它们）
cedr guard push       # 推送 pin 与发现到组织的 Guard 页面；--updates 带上 npm 更新

Guard 会发现 Claude、Codex、Cursor、Gemini、Copilot、opencode 与 Grok 的 MCP 配置及标准 skill 目录。guard lock 只有显式传 --introspect 时才会运行某个 MCP server，且会先警告。

4.5 Sync：一处写，各家编译

cedr sync init        # 把仓库现有 agent 文件导入 .cedr/
cedr sync             # 写出各家 agent 的原生文件；--dry-run 只打印 diff
cedr sync check       # 离线检查：生成文件漂移或组织规则被破坏则失败
cedr sync pull --org <id>
cedr sync push --org <id>    # 只报告漂移，不发文件内容与环境变量

需提交三样东西：源文件、生成的文件、.cedr/sync.lock。Sync 拒绝管理未被纳管的 Markdown 与手改内容，除非加 --force。

4.6 Monitor：用量与额度

cedr monitor limits
cedr monitor --since 7d --by model
cedr monitor sessions    # 最贵的会话
cedr monitor sources     # 每个 agent 找到了什么、为什么某个没数据

采集与可选自动推送在 ~/.config/cedr/monitor.toml 配置。缺失的用量保持为 unknown，不会被当成 0。

4.7 Bench：跑分对比

cedr bench init       # 在 .cedr/bench/ 写一份起步测试集
cedr bench plan       # 校验测试集并预览要做什么，不启动
cedr bench run        # 在预算内跑 agent 与测试；--fail-on lower 会在候选更差时让 CI 失败
cedr bench budget [USD]   # 设置上限（默认 $2.00）
cedr bench history
cedr bench show <id>

Bench 用厂商未经修改的 CLI 与你自己的登录凭据，每次 trial 在全新 clone 中运行。测试集的 setup 与 test 命令以你的权限执行，只跑你信任的测试集。

4.8 MCP 接入与 CI

claude mcp add cedr -- cedr mcp
codex mcp add cedr -- cedr mcp

GitHub Action 会安装已发布的 cedr（对照 release 的 SHA256SUMS 校验）、跑 guard lint 与 guard verify，并把每条发现作为 PR annotation 显示；存在 .cedr/sync.toml 时还会对 Sync 漂移失败。

- uses: actions/checkout@v5
- uses: Sheernox/cedr@vX.Y.Z   # 替换为最新 release tag，固定 tag 则 CI 只在你主动变更时才变

4.9 遥测与更新开关

cedr telemetry status|off|on 控制匿名使用数据上报。发送的内容为：命令名、退出码、耗时、版本、OS、装了哪些 agent，外加一个随机安装 ID；从不发送参数、路径、仓库名或代码。cedr telemetry off、CEDR_TELEMETRY=0 或 DO_NOT_TRACK=1 可关闭。

五、典型适用场景

多订阅重度用户：同时买了 Claude Pro/Max 和 Codex 计划，需要按剩余额度自动分流。Route 的核心场景。
团队统一 agent 配置：把规则、skills、MCP server、权限、hooks 写进 .cedr/，新成员 clone 即得同一套环境；配合 CI 的 sync check 防漂移。
MCP 供应链安全：担心某个 MCP server 被悄悄换了工具描述或加了新网络主机，guard lock + guard verify 让这类变更在 PR 里显形。
想用数据决定用哪个模型：route verdict 记录每次派工结果，route stats 汇总出「哪类活儿哪个模型最靠谱」。
换 agent / 换模型的 A/B 决策：bench 用带测试的真实任务给出通过率与成本对比，而不是凭感觉。

六、坑与注意

下列每条按「现象 → 影响 → 做法」三段式给出。

现象：命令名发生过变更。 影响：旧教程或旧 CI 里的 cedr lint / cedr verify 在当前版本不存在，照抄会直接失败。做法：以当前 README 的 cedr guard lint / cedr guard verify 为准，并用 cedr <command> --help 确认；版本浮动风险已标 ⚠️，建议在 CI 里固定 release tag。
现象：public beta，命令与文件格式在 1.0 前仍会变。 影响：脚本化调用随时可能被打断。做法：把 cedr 当工具人用而非依赖其输出格式的稳定契约层；真要自动化，接 cedr doctor --format json 这类结构化出口。
现象：Linux 构建要求 glibc 2.34+。 影响：Ubuntu 22.04 之前、Debian 12 之前的机器装不上预编译包。做法：换用 musl/源码构建，或确认系统 glibc 版本；对应环境直接上 cargo install。
现象：只装归档版才有自更新，cargo install 版没有。 影响：两条安装路径混用时误以为「每天自动更新」存在，结果某个环境长期停留在旧版。做法：按安装来源分别用 cedr update 或 cargo install --locked --git ... 更新，别混。
现象：statusline 读取只在 Claude 开启会话后才新鲜。 影响：claude-statusline 读取会在最后一次活跃会话 10 分钟后过期，额度状态退回 unknown，可能导致路由误判。做法：把 cedr route pools 的 unknown 视作「未知而非 0」；或改用 codex / http / file / command 类型的 readings 源。
现象：Claude 只对 Pro 与 Max 订阅、且在会话首次响应后，才发送 rate_limits。 影响：免费层或未开始的会话读不到用量，路线图长期缺一个数据源。做法：确认订阅类型；Gemini 更特殊——cedr 没有 Gemini 内置 reader（其配额只在 OAuth 凭据里，cedr 不读），因此 Gemini 计划永远显示 unknown。
现象：[machine] skip 里的 harness 在本机一律视为 absent。 影响：共享 routes 假设全员同订阅，本机没有的计划会被静默排除，团队里不同订阅的人选出的模型会不一样。做法：接受这种差异，或用机器级 [[readings]] 补齐；skip 写错名字只是警告不是错误。
现象：Bench 会以你的权限运行测试集的 setup 与 test 命令，并调用厂商 CLI 用你自己的登录凭据。 影响：不可信的测试集等同于任你执行任意代码；每次 trial 全新 clone 也意味着真实磁盘与网络消耗。做法：只跑自己审过的测试集；先用 cedr bench plan 预览；用 cedr bench budget 设上限；不需要上传时加 --no-push 或 --no-record。
现象：配置了 sync 后，Bench 的升级开始自动上传每次运行结果。 影响：会上报结果、仓库名、machine id/name 与 GitHub PR 号与 run URL（虽不含 prompt、agent 输出与路径）。做法：敏感仓库用 --no-push，或把 auto = false 同时关掉 Bench 与 Route 的自动发送。
现象：多数推送类命令默认选中「当前仓库」。 影响：--all 才会显式选全部仓库，裸 push 不会误传，但也意味着「以为全传了其实没传」的可能。做法：批量发送时显式加 --all；先 --dry-run 看 body。
现象：Sync 拒绝管理未被纳管的 Markdown 与手改内容。 影响：你精心调过某个 agent 的原生文件，sync 一跑可能被拒或需 --force 覆盖。做法：把手改迁移进 .cedr/ 源文件；--force 只作为最后手段。
现象：guard lock 除非显式 --introspect 否则不会运行 MCP server。 影响：这是安全设计而非功能缺失——tool surface 指纹可能依赖实际 introspect。做法：需要在 lock 中记录运行时信息时再加 --introspect，并接受其警告。

七、与同类对比

对比手工切 CLI：cedr 的增量是「按额度自动选 + 记录 verdict + 统计哪个模型适合哪类活」。手工切换不会留下可分析的历史。
对比 .mcp.json / claude_desktop_config.json 手工维护：Guard 提供 lockfile 与 CI 校验，把「配置漂移」变成可阻断的检查项，而不是靠人自觉。
对比 tmux / 多会话管理类工具：cedr 管的是策略层（选谁、审谁、锁谁、测谁），不是会话层。
对比 Claude Code 自带的多 agent 机制：Claude 的 subagent 仍在 Claude 生态内；cedr 是跨厂商（Claude / Codex / Cursor / Gemini / Copilot / opencode / Grok）的横向编排层。
对比 CI 上手写脚本做多厂商 review：Council 提供了报告合并、同处问题归组、P0/P1 阻断与「报告不足不静默放行」这些现成语义。
对比付费 SaaS 用量看板：cedr 开源可自托管，且默认本地留存——推送是显式可选的，边界写在 README 与 docs/telemetry.md。

八、一句话推荐结论

如果你同时在用两个以上编码 agent 或订阅计划，又被「额度打满、review 打架、配置漂移、花钱没数」这四件事反复绊住，cedr 值得装——它的 Route + Monitor + Council 三件套是真正解决痛点的部分；但要按 public beta 对待：先用 cedr doctor 和 cedr monitor limits 验证数据源接得对，再把 Guard / Sync 挂进 CI，并且永远固定 release tag。

来源

https://github.com/Sheernox/cedr（README，2026-11-04 抓取）
https://raw.githubusercontent.com/Sheernox/cedr/main/docs/route.md（Route 设计契约）
https://github.com/Sheernox/cedr/blob/main/docs/versioning.md、docs/bench.md、docs/telemetry.md（README 内引用，未逐篇展开）
web_search 结果中出现的 GitHub Action 旧写法（v0.3.0、cedr lint/cedr verify），用于版本漂移佐证

不确定与待核

⚠️ 当前 release 的准确版本号未在本文锁定；README 的 Action 示例使用 vX.Y.Z 占位。安装前请查 releases 页。
⚠️ docs/council.md、docs/design.md、docs/sync.md、docs/monitor.md、docs/bench.md、docs/doctor.md 未逐篇抓取，本文对这些子命令的描述基于 README 的命令表。
⚠️ 搜索摘要中出现 cedr lint / cedr verify 旧命令名（疑为 v0.3.0 时期），未能确认具体在哪个版本被 guard 子命令取代。
⚠️ 「Coming next: Index（一份所有 agent 共享的代码图）」为 README 声明的未来功能，尚未确认是否已发布。