内容
# Alembic
<p align="center">
<strong>减少编码代理在处理大量无用输出时损失的上下文</strong>
</p>
<p align="center">
<a href="#前后对比">前后对比</a> •
<a href="#为什么使用Alembic">为什么使用Alembic</a> •
<a href="#安装">安装</a> •
<a href="#30秒证明">首次基准测试</a> •
<a href="#详细级别">级别</a> •
<a href="#钩子标志和持久化默认值">标志</a> •
<a href="#工作量评估">工作量</a> •
<a href="#预设">预设</a> •
<a href="#用法">用法</a> •
<a href="#基准测试">基准测试</a> •
</p>

Alembic是一款适用于Codex和Claude的技能优先、本地降噪工具。它可以将测试洪水、CI日志、MCP聊天、堆栈跟踪、差异、监视输出、Docker日志和Kubernetes日志压缩成仍然能回答您问题的最小化产物。
## 为什么使用Alembic
大多数代理循环不会因为模型弱而失败,而是因为模型被迫读取太多噪音。
Alembic的目的是解决这个问题:
- 将通过测试的洪水减少到一行有用的信息
- 将CI日志折叠成失败的作业、步骤、命令和原因
- 将巨大的MCP JSON有效载荷转换为您实际请求的几行
- 缩小监视模式的变更,以便重复检查不会消耗上下文
- 在您自己的仓库中基准测试节省,而不是要求您信任截图
为什么这很重要:
- 更少的输出意味着更少的上下文浪费
- 更小的答案通常在紧密的循环中处理速度更快
- 噪音日志停止隐藏真正的故障
- 基准测试模式为您提供在您自己的工作流中直接证明价值
## 前后对比
Alembic在原始输出大得多时很有用,而您需要做出的决策很小。
### 测试
之前:
```text
[... 180 passing test lines omitted ...]
FAIL src/auth/session.test.ts > rejects expired token
AssertionError: expected 401 to equal 403
[... stack trace omitted ...]
```
之后:
```text
FAIL src/auth/session.test.ts > rejects expired token
```
为什么有帮助:代理保留失败的测试并丢弃洪水。
### GitHub Actions
之前:
```text
[... 400 setup, cache, install, and cleanup lines omitted ...]
build Run pnpm test 2026-04-11T15:10:04.000Z pnpm test
build Run pnpm test 2026-04-11T15:10:07.000Z FAIL src/auth/session.test.ts > rejects expired token
build Run pnpm test 2026-04-11T15:10:07.100Z AssertionError: expected 401 to equal 403
build Run pnpm test 2026-04-11T15:10:08.000Z Error: Process completed with exit code 1.
```
之后:
```text
FAIL Job: build
Step: Run pnpm test
Command: pnpm test
Reason: FAIL src/auth/session.test.ts > rejects expired token
Exit: 1
```
为什么有帮助:它将整个工作流日志转换为单个失败步骤和原因。
### MCP工具响应数据
MCP工具调用返回包含包装字段的大型JSON有效载荷。Alembic自动检测JSON响应并将它们压缩到可读的列表中。
之前(来自MCP工具调用的原始响应):
```json
{"issues":[{"id":"PAYMENTS-17","title":"TypeError: Cannot read properties of undefined (reading 'id')","level":"error","status":"unresolved","count":"137","userCount":29,"firstSeen":"2026-04-01T09:00:00.000Z","lastSeen":"2026-04-10T14:22:00.000Z","culprit":"payments/checkout.tsx in submitPayment","project":{"slug":"web-app"}},{"id":"API-42","title":"TimeoutError: upstream request exceeded 30s","level":"warning","status":"regressed","count":"54","userCount":7,"firstSeen":"2026-04-08T10:15:00.000Z","lastSeen":"2026-04-10T13:57:00.000Z","culprit":"api/routes/orders.ts in createOrder","project":{"slug":"backend-api"}}]}
```
之后:
```text
[unresolved]
PAYMENTS-17 | TypeError: Cannot read properties of undefined (reading 'id') | error | 137 events
[regressed]
API-42 | TimeoutError: upstream request exceeded 30s | warning | 54 events
```
为什么有帮助:包装字段、ID、时间戳和元数据消失了。您请求的行仍然存在。
### MCP错误日志
之前:
```text
[... session setup omitted ...]
[MCP] tool=list_issues server=sentry request_id=abc123
[MCP] error=permission_denied project=web-app endpoint=issues
[MCP] retry attempt 1/3
[MCP] retry attempt 2/3 error=timeout
```
之后:
```text
MCP FAIL list_issues
Server: sentry
Target: project=web-app endpoint=issues
Reason: [MCP] error=permission_denied project=web-app endpoint=issues
Next: [MCP] retry attempt 1/3
```
为什么有帮助:失败的工具、目标和原因被保留。重试聊天消失了。
### Docker
之前:
```text
[... image pull and layer cache lines omitted ...]
Step 7/10 : RUN pnpm build
---> Running in 123456789abc
src/server.ts:12:3 error TS2304: Cannot find name 'window'.
The command '/bin/sh -c pnpm build' returned a non-zero code: 2
[... cleanup omitted ...]
```
之后:
```text
DOCKER FAIL unknown service
Step: Step 7/10 : RUN pnpm build
Command: pnpm build
Reason: src/server.ts:12:3 error TS2304: Cannot find name 'window'.
```
为什么有帮助:构建失败仍然存在;层变更消失了。
### Kubernetes
之前:
```text
[... describe output omitted ...]
Name: api-7d9f8c6d8f-2xk9m
Warning Failed 2m (x4 over 5m) kubelet Error: ImagePullBackOff
Warning Failed 2m (x4 over 5m) kubelet Failed to pull image "ghcr.io/openai/alembic:missing"
[... events omitted ...]
```
之后:
```text
K8S FAIL api-7d9f8c6d8f-2xk9m
Container: unknown container
Reason: Warning Failed 2m (x4 over 5m) kubelet Error: ImagePullBackOff
```
为什么有帮助:您保留了失败的Pod和原因,而无需滚动浏览事件垃圾。
## 安装
选择您的代理。按照表格操作。
| 代理 | 安装 |
| --- | --- |
| Claude Code | 从Claude市场添加此仓库,安装Alembic插件,然后运行`npm run install:claude`。 |
| Codex | 克隆此仓库,打开`/plugins`,搜索`Alembic`,然后安装它。可选:如果你还想在仓库外部创建一个个人技能副本,请运行`npm run install:codex`。 |
| Cursor | `npx skills add FrangSierra/Alembic -a cursor` |
| Copilot | `npx skills add FrangSierra/Alembic -a github-copilot` |
安装一次。从那里开始使用。
### 您获得的功能
| 功能 | Claude Code | Codex | Cursor | Copilot |
| --- | --- | --- | --- | --- |
| Alembic技能在您的个人技能列表中可用 | Y | Y | Y | Y |
| 仓库本地插件默认值和`/alembic ...`命令 | Y | Y | — | — |
| 测试、CI日志、差异、MCP有效载荷和监视输出的默认设置 | Y | Y | Y | Y |
`npx skills add`为Cursor和Copilot安装Alembic技能,但不安装插件钩子或仓库本地默认值。
如果Claude Code已经有插件但您仍然看不到该技能,请运行:
```bash
npm run install:claude
```
您可以安全地重新运行该命令以刷新现有的Alembic技能安装。
使用 `--force` 仅当 `~/.claude/skills/alembic` 已经存在但看起来不像Alembic安装,并且您想替换它时:
```bash
node scripts/install-claude.mjs --force
```
### 使用`alembic init`添加项目规则
安装技能使Alembic可用。它本身并不教每个仓库何时使用它。
如果您希望项目始终在正确的位置调用Alembic,请在该仓库中运行一次:
```bash
alembic init
alembic init claude
```
它做了什么:
- `alembic init` 创建或更新 `AGENTS.md`
- `alembic init claude` 创建或更新 `CLAUDE.md`
- 插入一个托管的Alembic块,而不是重写文件的其余部分
- 告诉代理使用 `$alembic` 处理诸如测试套件、CI日志、MCP有效载荷、Docker输出、Kubernetes日志、差异和其他shell聊天等噪音输出
- 告诉代理仅在用户明确要求时保留原始输出
- 可以提及可选的工作量建议工作流作为推荐步骤,而不是作为应用程序实时线程设置的证明
您可以安全地重新运行它。Alembic保持其自己的托管块更新,并将项目的其余规则单独保留。
如果您更喜欢手动管理项目规则,那么这就是Alembic编写的精确块:
```md
<!-- ALEMBIC:START -->
## Alembic
- 使用 `$alembic` 处理shell输出噪音并用户未要求原始记录的转录。这包括测试套件、监视模式变更、CI或GitHub Actions日志、MCP工具有效载荷、长差异、`rg`或`grep`结果、Docker构建和容器日志、Kubernetes `describe`或日志输出、迁移输出以及沙盒或审批聊天。
- 在调用它之前解析辅助程序。优先使用`alembic`如果它已经在`PATH`上。否则,使用`node <helper> ...`并使用以下第一个现有辅助程序,按此顺序: `$HOME/.codex/skills/alembic/runtime/bin/alembic.mjs`, `$HOME/.claude/skills/alembic/runtime/bin/alembic.mjs`, `./tooling/alembic/bin/alembic.mjs`, `./alembic/runtime/bin/alembic.mjs`, `./plugins/alembic/skills/alembic/runtime/bin/alembic.mjs`。在shell中探测时,使用`-e`检查存在,而不是使用`-x`检查可执行性。
- 如果Alembic工作量建议已启用,并且用户已经足够确定任务的形状以判断实现范围,则可以作为推荐步骤在昂贵实现通过之前运行Alembic工作量启发式。
- 您可以跳过工作量检查,对于明显微小、可逆转的编辑,如拼写修复、单个重命名或单行文本更改。
- 使用 `<alembic-helper> effort --format json --requested <intended-or-user-provided-level> "<task summary>"` 进行此检查,其中 `<alembic-helper>` 是 `alembic` 或 `node <resolved-helper-path>`。在shell中探测时,检查存在性使用 `-e` 而不是可执行性 `-x`。
- 将结果视为建议。
- 优先使用Alembic详细级别来控制输出量:`flame` 用于完整的减少的摘要,`ember` 用于紧凑的单行减少,`ash` 用于抑制例行成功噪音。
- 不要减少用户明确要求原始输出的输出,不要将Alembic用作检查确切事实的替代方法,当原始输出是任务时。
<!-- ALEMBIC:END -->
```
### 仓库助手仅限
如果您只想在该仓库中使用助手:
```bash
node tooling/alembic/bin/alembic.mjs --help
```
可选shell别名:
```bash
alias alembic='node /absolute/path/to/tooling/alembic/bin/alembic.mjs'
```
仓库还保留了一个自包含的验证包在 [`alembic/`](./alembic) 中,以便安装和生成的副本可以在不经过构建步骤的情况下进行测试。
## 30秒证明
最有力的证明概念不是截图。它是在您已经使用的命令上运行Alembic。
首先:
```bash
alembic benchmark exec --preset tests -- npm test
```
或者,如果您想进行差异聚焦证明:
```bash
alembic benchmark diff --preset safety --base main
```
基准测试模式为您提供:
- 原始命令输出
- Alembic的减少答案
- 字节减少
- 行减少
- 令牌减少或令牌估计
- 保全检查,以便您查看重要信号是否存活
典型的基准测试输出如下:
```text
alembic benchmark: exec
Verdict: PASS
Compared: npm test raw output vs Alembic-reduced output
Source used: wrapped command output
Reduction: 6,459 bytes / 105 lines -> 5 bytes / 1 lines (99.9% bytes, 99.0% lines)
Tokens: 1,257 -> 2 (99.8% saved)
Preservation: status preserved; no failing tests to compare
```
如果您的安装在没有tokenizer依赖的情况下运行,Alembic仍然显示本地`Token estimate:`行,以便基准测试在自包含的技能安装中仍然有用。
## 详细级别
Alembic支持三个输出级别:
| 级别 | 功能 | 最适合 | 为什么 |
| --- | --- | --- | --- |
| `flame` | 完整的减少输出 | 普通交互式工作 | 保留重要细节同时减少噪音 |
| `ember` | 紧凑的单行或接近单行的输出 | 紧凑的代理循环、重复检查、快速状态读取 | 在不丢失信息的情况下尽量减少令牌使用 |
| `ash` | 成功时保持沉默,显示失败、提示和需要操作的 状态 | 监视模式、后台验证、噪音大的命令通过率重 | 减少通常浪费上下文的变更 |
快速思维模型:
- 使用 `flame` 时,人类将阅读答案
- 使用 `ember` 时,您主要需要状态
- 使用 `ash` 时,成功的输出不是很有用
示例:
```bash
alembic --level flame "Summarize this output."
alembic --level ember "Summarize this output."
alembic --level ash "Summarize this output."
alembic exec --level ash --preset tests -- npm test
```
## 钩子标志和持久化默认值
Alembic插件安装可以持久化几个默认值,以便您不必每次会话都重复它们。
配置值:
- `enabled`: `on` 或 `off`
- `detailLevel`: `flame`、`ember` 或 `ash`
- `effortAdvisor`: `off` 或 `suggest`
检查或更改它们:
```bash
alembic hook-config show --host claude
alembic hook-config set --host claude --level ember --effort off
alembic hook-config set --host codex --level ash
alembic hook-config set --host codex --disable
alembic hook-config reset --host claude
```
您也可以使用插件安装从提示更改它们:
```text
/alembic
/alembic status
/alembic on
/alembic off
/alembic flame
/alembic ember
/alembic ash
/alembic effort suggest
/alembic effort off
/alembic reset
```
这些标志的作用:
- `enabled on|off`: 启用或关闭Alembic钩子默认值而无需卸载任何内容
- `detailLevel`: 默认情况下,您希望减少多少输出
- `effortAdvisor suggest`: 让Alembic建议任务的可能推理级别
- `effortAdvisor off`: 保持Alembic仅专注于减少输出
为什么重要:
- 团队通常希望交互式工作和循环或监视模式混乱的不同默认值
- 一些用户希望Alembic始终可见,其他用户仅在失败时可见
- 许多团队过度使用 `xhigh`;`suggest` 提供了一个轻量级本地检查在昂贵的实现通过之前
- 当Alemic推荐更改时,它将给您一个更清晰的信号,表明是否在继续之前切换到不同的级别
- 最适合使用建议的地方是在计划模式之后,当任务形状足够清晰,可以判断实现范围时
- 不要在明显微小、可逆转的编辑(如拼写修复、单个重命名或一行文本更改)上跳过检查
## 工作量评估
Alembic还提供了一个本地工作量评估器,用于主机侧集成,但正确地理解它很重要:
- 它是一个任务工作量启发式,而不是实时线程检查器
- 它有助于回答“我们应该在什么级别运行这个任务?”而不是“应用程序当前正在使用什么级别?”
- 它在您想要避免在任务形状清晰之前浪费令牌在高或xhigh上的情况下最有用
- 它在计划模式之后变得最可信,一旦任务已经分解到足以判断实现是否仍然小、有界和可逆转
```bash
alembic effort --requested xhigh "重命名几个文件并更新导入。"
alembic effort --requested medium "计划完成:实现批准的身份验证迁移,跨API、DB和滚动验证进行迁移。"
alembic effort --format json --requested low "计划完成后,验证flaky身份验证竞赛修复是否仍然适合低或应该提高。"
alembic benchmark effort --set smoke
```
工作原理:
- 本地且确定性
- 评估工程难度,而不是单独的提示长度
- 仅在更改请求有意义时建议更改
- `--requested` 应该是您打算使用的级别或用户告诉您当前设置的级别
推荐工作流:
1. 首先使用计划模式,以便任务停止成为模糊请求并成为具体的实现形状。
2. 在规划后,在实施总结上运行 `alembic effort`,使用您打算运行的级别或用户明确给出的级别。
3. 如果Alembic建议一个更便宜或更强的级别,请在继续之前决定是否切换。
4. 如果任务很小且可逆转,请跳过检查并直接完成工作。
示例:
- 小型重命名后规划:
```bash
alembic effort --requested xhigh "规划审查后:重命名AccountCard为ProfileCard并更新导入。"
```
像这样的任务,Alembic通常应该将其推向下限,这样您就不会在机械编辑上浪费`xhigh`。
- 规划后大型实施:
```bash
alembic effort --requested medium "审批后计划:实施计费重试重新设计,添加迁移,更新工作线程,并验证回滚安全性。"
```
这里Alembic可以证明要求在实施前使用`high`或`xhigh`是合理的。
当前校准目标:
- 单独的长提示不意味着`xhigh`
- 有界的仅限UI工作限制在`high`
- 具有清晰重现的本地异步错误不自动跳转到`xhigh`
- `xhigh` 保留用于任务结合不确定性、辐射范围、耦合、状态或硬验证
当前执行经验:
- 启发式本身很有用
- 它应被描述为推荐系统,而不是一种机制,可以验证应用程序的当前努力级别
- 仅基于提示的强制执行在代理已经开始探索后不再完全确定
- 如果您希望获得最高的现实成功率,请将计划模式视为主要检查点,将所有其他检查视为回退
这很有用,当您的团队倾向于为所有事情默认使用昂贵的推理,或者相反的问题:复杂调试和迁移工作的推理不足。
预设
Alembic 提供针对最常见的噪音工作流的专注输出合约:
| 预设 | 您将获得 |
| --- | --- |
| `tests` | `PASS`,或 `FAIL` 加上失败的测试名称 |
| `actions` | 失败的 GitHub Actions 工作流、步骤、命令、原因、退出代码 |
| `mcp` | 失败的 MCP 、错误和下一步的 Docker 步骤/服务和最小有用线索 |
| `k8s` | 失败的 pod/container、原因和下一个` | `SAFE`、`REVIEW` 或 `UNSAFE`,然后文件和原因 |
| `files` | 仅文件路径 |
| `summary` | 更改的文件,每个文件有一行摘要 |
| `logs` | 最高信号错误加上最小有用摘要 |
| `approval` | 阻止的操作、原因、下一个步骤 |
规则:
- 当其中一个合约已经与工作流匹配时,使用 `--preset`
- 当您需要自定义输出格式时,使用 `--question`
- 如果两者都存在,`--question` 优先
有用示例:
```bash
alembic --preset logs
alembic exec --preset tests -- npm test
gh run view --log | alembic --preset actions
cat mcp-trace.log | alembic --preset mcp
docker build . 2>&1 | alembic --preset docker --drop-level INFO,DEBUG
kubectl describe pod api-123 | alembic --preset k8s --keep-level ERROR,WARN
al safety --base main
rg -n "TODO" . | alembic --preset files
```
审批噪音是另一个很好的选择:
之前 failed in sandbox.
Network access is restricted.
This command requires escalated permissions.
Please re-run with sandbox_permissions=require_escalated.
Command failed in sandbox.
Network access is restricted.
This command requires escalated permissions.
Please re-run with sandbox_permissions=require_escalated.
npm install failed because registry access is blocked.
```
之后:
```text
BLOCKED npm install failed because registry access is blocked.
Reason: Network access is restricted.
Next: Please re-run with sandbox_permissions=require_escalated.
```
## 用法
当退出状态很重要时,优先使用 `exec`:
```bash
alembic exec --level ash --preset tests -- npm test
```
当使用管道模式更简单时:
```bash
git diff -- src | alembic --level ember --preset summary
```
### MCP 工具响应数据
MCP 工具调用的 JSON 响应会自动检测。管道响应并描述您想要的:
```bash
# 紧凑列表,包含默认字段(ID、标题、状态)
echo "$MCP_RESPONSE" | alembic --question "List each item: ID, title, status."
# 按字段分组
echo "$MCP_RESPONSE" | alembic --question "List each Sentry issue: ID, title, status, level. Group by status."
# 过滤
echo "$MCP_RESPONSE" | alembic --question "List each Sentry issue: ID, title, status where status is unresolved or regressed."
```
如果自动检测失败,则强制使用 `--mode data`:
```bash
echo "$MCP_RESPONSE" | alembic --mode data --question "List each item: ID, title, status."
```
### 其他有用命令
```bash
alembic doctor
alembic benchmark exec --level flame --preset tests -- npm test
gh run view --log | alembic --level ember --preset actions
cat mcp-trace.log | alembic --level ember --preset mcp
docker build . 2>&1 | alembic --level ember --preset docker --drop-level INFO,DEBUG
kubectl describe pod api-123 | alembic --level ash --preset k8s --keep-level ERROR,WARN
alembic benchmark diff --level ember --preset safety --base main
```
## 基准测试您的工作流
基准测试模式是决定 Alembic 是否适合您的循环的最佳方式。
在您需要数字而不是感觉时使用它:
```bash
alembic benchmark exec --preset tests -- npm test
alembic benchmark exec --preset
alembic benchmark diff --preset safety --base main
alembic benchmark effort --set smoke
测试证明的内容:
- `benchmark exec`:实际命令缩小的 diff`:分支或工作树审查噪音缩小的程度
-启发式是否仍然校准
这些示例数字来自实际本地运行:
| 工作流 | 原始令牌 | 当前令牌 | 令牌节省 | 字节节省 |
| --- | ---: | ---: | ---: | ---: |
| `npm test` -> `PASS` | 1,257 | 2 | 99.8% | 99.9% |
| Sentry top 50 issues | 96,439 | 344 | 99.6% | 99.5% |
| Sentry grouped by status | 96,439 | 881 | 99.1% | 99.4% |
| Sentry filtered statuses | 96,439 | 244 | 99.7% | 99.7% |
| First-commit diff summary | 154,386 | 787 | 99.5% | 99.5% |
本节的重要性:
- 单行计数可能不准确,尤其是对于 JSONL-heavy MCP 输出
- 字节和令牌显示实际节省
- 它为用户提供了一个快速、具体的证明,安装后立即生效
## 验证
本地验证:
```bash
alembic doctor
```
仓库验证:
```bash
npm test
npm run check:generated
npm run release:validate
```
安装:codex`
- `npm run install:claude`
- 从仓库或安装包运行 `alembic doctor`
当前边界:
- Alembic 是一种技能,而不是 MCP 减少了噪、代理输出和 MCP-adjacent 输出,在主机发出后
- 它在默认路径中没有提供商或网络依赖
## 给这个仓库点星
[](https://star-history.com/#FrangSierra/Alembic&Date)
---
## 致谢
> Alembic 最初受到 [Distill](https://github.com/samuelfaj/distill) 的启发。
> 最初建立的小项目在这个基础上慢慢成长,迭代演变成它自己的音的代理工作流,使本地验证更容易信任。
对原始 Distill 项目表示深深的感谢,它激发了这个仓库的灵感。
连接信息
猜你喜欢
暂无推荐服务器