tuneloop/tuneloop

# tuneloop 为你的 AI 编码会话提供本地分析。**衡量产出，而非 token。** tuneloop 能将你的 AI 编码工具已经生成的会话记录转化为一个本地仪表盘，展示你实际交付的内容、花费以及你的工作模式。

具体来说，它通过以下内容丰富每个会话： - **产出链接** — 合并的 PR、交付的功能、更改的文件 - **精细的产出成本归因** - **任务复杂度** - **Agent 自主性** - **工作类型** - **关键决策** - **工具错误类别** 结合记录中已有的数据 —— 模型、Agent 框架、repo 等 —— 这些数据让你能够回答以下问题： - 我在 AI 上的花费有多少投入到了 PR #2 或功能 *X* 中？ - 随着时间的推移，我的 Agent 在复杂任务上是否变得更加自主了？ - 我在 repo *X* 与 repo *Y* 上的成功率是多少 —— 或者你关心的任何其他维度？ 兼容 Claude Code、Codex、OpenCode 和 Pi。所有内容都在你的机器上运行并保留在你的机器上；需要 LLM 的增强处理可以使用你自己的提供商密钥或本地模型。上述内置功能只是默认选项 —— tuneloop 是可扩展的，添加你自己的增强处理非常简单。 ## 快速开始 ``` npx tuneloop analyze ``` 这会扫描典型的会话文件夹（如 `~/.claude/projects`），构建一个本地存储，并打印摘要。**首次运行**会处理每个记录，因此预计需要几分钟（开启 [LLM 增强](#llm-enrichment) 处理约 80 个会话大约需要 4 分钟；仅运行静态分析会更快）；后续运行是增量的，仅重新处理已更改的会话，因此会很快完成。完成后，CLI 会打印仪表盘 URL —— 按 **Enter** 键在浏览器中打开它（按 `Ctrl+C` 停止）。通过逗号分隔的列表将其指向其他位置： ``` npx tuneloop analyze ~/.claude/projects,/path/to/more/sessions ``` 常用 flag： - `--no-serve` — 构建存储并退出，不启动仪表盘 - `--port ` — 在不同的端口上提供服务 - `npx tuneloop serve` — 在已分析的存储上打开仪表盘，无需重新分析 ## 你能得到什么 仪表盘实时从本地 SQLite 存储中读取所有内容： - **会话成功率** — 你的会话中有多少以成功告终（由你定义成功的标准）。 - **每个交付产出的成本** — 每个合并的 PR 或交付的功能所花费的 AI 美元。 - **总支出** — 随时间变化，按模型、工作类型或 repo 划分。 - **工具和技能使用情况** — 每个会话中的调用次数、错误率和错误类别。 - **可过滤的会话查看器**，包含每个会话背后的完整记录和文件更改。 - 轻松的记录导航（按轮次、错误、自由文本搜索和产出）。例如：你可以直接跳转到会话中你处理特定功能或代码更改的部分。 - 过滤涉及特定文件 / PR / 功能的会话。 成本、工具、文件和 git/PR 结果来自静态分析 —— 无需设置或 API 密钥。工作类型、复杂度、自主性和功能名称来自 [LLM 增强](#llm-enrichment)，这值得设置：仪表盘的大部分实用性都依赖于它。 **亮点** 功能将相同的数据转化为关于你近期工作的通俗见解：

并且每个会话都是一个可读的记录，你可以按轮次、工作类型或错误进行导航 —— 旁边还会显示它更改的文件：

## 工作原理 **增强处理** 通过一次 LLM 调用标记每个会话： - **工作类型** — `plan` · `implement` · `debug` · `research` · `review` · `docs` · `other` 中的一种。 - **复杂度** — `trivial` · `routine` · `substantial` · `open-ended` 中的一种。 - **自主性** — Agent 自主驱动的程度：`autonomous` · `guided` · `minimal`。 - **功能** — 将会话链接到已交付的功能，复用你现有的功能名称并提出新名称。分类体系会随着你的分析不断增长，因此相关工作会归入同一个功能下，而不会变得零散。 - **成功** — 判定的结果（`success` / `partial` / `failure`），作为你可以统计的 `session_success` 结果展示。 **PR 链接** 通过两种方式将 会话与其产生的 PR 连接起来： - **显式** — 记录显示 Agent 创建、合并或审查了 PR（`gh pr create` / `gh pr review` / GitHub MCP 工具）；实时状态来自你的本地 `gh`。 - **内容匹配** — 针对Agent 编写代码而*由你*提交和推送（记录中没有 `gh pr create`）的常见情况，tuneloop 会将 Agent 编写的代码行与你自己的 PR diff 进行匹配，并链接最佳匹配项。 有关检测规则，请参见 [ARCHITECTURE.md](./ARCHITECTURE.md#built-in-processors)。 **块级成本归因** — 涉及多项内容的冗长会话不会被计为一整笔费用。tuneloop 将其拆分为多个块，并归因每个块的 token 成本，因此每个 PR 或每个功能的成本仅反映投入到其中的工作。 → [块的工作原理](./ARCHITECTURE.md#blocks-and-cost-attribution-srccoreblocksts) **指标** — 仪表盘的五个核心标题（成功率、每个交付产出的成本、总支出、会话数、工具错误率）分别在 [ARCHITECTURE.md](./ARCHITECTURE.md#the-metrics-explained) 中进行了解释。 ## 从你的编码 Agent 中查询 仪表盘上的所有内容都是对存储的查询 —— 它*未*显示的任何内容也是如此。`tuneloop query` 直接从你的终端或编码 Agent 的 shell 中对该存储运行只读 SQL： ``` tuneloop query "SELECT model, SUM(cost_usd) FROM usage_facts GROUP BY 1 ORDER BY 2 DESC" tuneloop query --schema # tables, facets, and measures — learn the shape first ``` 仅允许运行 `SELECT` / `WITH … SELECT`；禁止写入和访问原始记录。因为它不需要服务器并且使用纯粹的 SQL，所以它非常适合 Claude Code 和其他 Agent。安装内置技能，以便你的 Agent 在编写查询之前了解 schema 和粒度规则： ``` npx skills add tuneloop/tuneloop ``` 然后只需提问 —— *“查询 tuneloop：上周我每个模型花了多少钱？”* —— Agent 就会编写 SQL，运行它，并读出答案。 ## LLM 增强 要为每个会话标记工作类型、复杂度、自主性和 LLM 判定的成功信号 —— 并为你交付的功能命名 —— 请将 tuneloop 指向**你自己的** LLM 密钥。你的会话数据只会发送到你选择的提供商： ``` export TUNELOOP_LLM_PROVIDER=anthropic export ANTHROPIC_API_KEY=sk-ant-... # 可选：export TUNELOOP_LLM_MODEL=claude-haiku-4-5 npx tuneloop analyze ``` 或者跳过环境设置：在终端中运行 `npx tuneloop analyze`，当未配置提供商时，它会提议以交互方式进行设置 —— 选择一个提供商，粘贴密钥（输入已隐藏），该运行就会执行增强处理。如果提供商的密钥已经导出（例如 `ANTHROPIC_API_KEY`），则无需询问即可自动获取。该密钥永远不会写入磁盘；运行结束时会打印使其永久生效的 `export` 命令行。 选择一个预设并提供其密钥；模型默认设置很合理，也可以使用 `TUNELOOP_LLM_MODEL`（或 `--llm-model`）覆盖。Anthropic、OpenAI 和 AWS Bedrock 是原生的；其他所有服务都使用兼容 OpenAI 的 API。 | `TUNELOOP_LLM_PROVIDER` | 密钥环境变量 | 备注 | |---|---|---| | `anthropic` | `ANTHROPIC_API_KEY` | 原生 | | `openai` | `OPENAI_API_KEY` | 原生 | | `bedrock` | `AWS_BEARER_TOKEN_BEDROCK` _（或标准 AWS 凭证）_ | 通过 AWS 使用 Claude；设置 `AWS_REGION` | | `openrouter` | `OPENROUTER_API_KEY` | 通过一个密钥使用 400 多种模型 | | `groq` | `GROQ_API_KEY` | 速度快；有免费额度 | | `deepseek` | `DEEPSEEK_API_KEY` | | | `gemini` | `GEMINI_API_KEY` | Google，兼容 OpenAI 的 endpoint | | `together` / `fireworks` / `xai` | `TOGETHER_API_KEY` / `FIREWORKS_API_KEY` / `XAI_API_KEY` | | | `ollama` | _（无）_ | 本地；`http://localhost:11434` | | `openai-compatible` | `TUNELOOP_LLM_API_KEY` | 任何其他主机；设置 `TUNELOOP_LLM_BASE_URL` | ``` # 托管的 provider —— 只需输入名称，无需输入 URL： TUNELOOP_LLM_PROVIDER=openrouter OPENROUTER_API_KEY=sk-or-... \ npx tuneloop analyze --llm-model deepseek/deepseek-chat # 完全本地，无需 key，任何数据都不会离开您的机器： npx tuneloop analyze --llm-provider ollama --llm-model qwen2.5 # AWS Bedrock —— 一个 Bedrock API key，或任何标准的 AWS credentials (SigV4)： TUNELOOP_LLM_PROVIDER=bedrock AWS_BEARER_TOKEN_BEDROCK=... AWS_REGION=us-east-1 \ npx tuneloop analyze # 默认 model 是一个 US inference profile；其他区域会选择各自的，例如： # --llm-model eu.anthropic.claude-haiku-4-5-20251001-v1:0 # 任何其他兼容 OpenAI 的 host： TUNELOOP_LLM_PROVIDER=openai-compatible TUNELOOP_LLM_BASE_URL=https://host/v1 \ TUNELOOP_LLM_API_KEY=… npx tuneloop analyze --llm-model my-model ``` 增强处理是每个会话一次结构化的 **tool call**，因此请使用支持 tool call 的模型（所有托管的默认模型都符合条件）。flag 会覆盖单次运行的环境变量；API 密钥绝不能作为 flag —— 请在环境中设置它或在交互式提示中粘贴。它很便宜 —— 一个包含约 80 个会话的典型语料库使用 Claude Haiku 大约需要 **$0.60**。此成本在摘要中显示为 **分析支出**，价格取自内置的价目表，并使用 OpenRouter 公开价格表填补空缺（缓存在 `~/.tuneloop/` 下）。 **本地 Ollama** 需要更大的上下文窗口和强大的模型：增强处理的 prompt 约为 4–6k 个 token，但 Ollama 默认的约 2k 限制会将其静默截断，因此请使用 `OLLAMA_CONTEXT_LENGTH=8192 ollama serve` 启动服务器，并使用支持强大 tool call 的 ≥7B 模型，如 `qwen2.5:7b`（极小的模型在 tool call 时表现不稳定）。 ## 隐私 记录会在本地处理，结果将写入本地 SQLite 存储（默认为 `~/.tuneloop/`）。tuneloop 绝不会将你的**会话数据**发布到任何地方 —— 唯一离开本机的只有发送到你提供密钥的 LLM 提供商的记录，而且仅在启用增强处理时才会发生。它的其他网络调用都是只读的，并且不携带你的任何数据：使用你的本地 `gh` 获取 PR 状态和 diff（通过你自己的 GitHub 授权），以及获取 OpenRouter 的公开价目表，以为内置表格中未知的模型计算成本。要避免将记录发送到本机之外，请针对本地模型进行增强处理（`--llm-provider ollama`）。 ## 从源码运行 `npx tuneloop` 就能满足大多数人的需求。如果要修改 tuneloop 本身，请在本地签出的代码中运行它： ``` npm install npm run dev -- analyze # builds, runs the CLI (args after `--`), then serves the dashboard ``` 或者构建一次并直接调用二进制文件： ``` npm run build node dist/cli.js analyze ``` `npm link` 会为你提供一个由本地构建支持的全局 `tuneloop`。LLM 增强处理的工作方式相同 —— 在运行之前设置 `TUNELOOP_LLM_PROVIDER` 及其密钥。 ## 扩展 添加新的分析只需一个文件：实现 `Processor` 接口，声明任何可切片的切面，并注册它 —— 它会自动出现在存储和仪表盘中（作为卡片和过滤器），无需迁移。要支持新的 AI 工具，请编写 `SourceAdapter`。请参见 [ARCHITECTURE.md](./ARCHITECTURE.md)。 ## 许可证 MIT

标签：AI编程, MITM代理, 代码示例, 会话分析, 开发效率, 成本分析, 数据分析, 文档结构分析, 本地仪表盘, 网络可观测性, 自动化攻击