Deadwax

一个基于个人收听历史的智能体音乐图书管理员。它回答关于你听过什么的自然语言问题，并根据硬约束构建播放列表——带有确定性验证器、修复循环，以及报告通过率而非通过/失败的评估套件。

作为展示生产级 LLM 工程实践的作品集项目而构建：工具使用、检索、追踪、评估和 MCP。

有趣的部分

大多数 LLM 演示在运行两次之前都有效。Deadwax 是围绕第二次运行时发生的情况构建的。

系统沿一条线划分：模型从不计算。 它解释语言、选择工具并撰写文本。每个算术运算、阈值检查和约束裁决都发生在不知道 LLM 存在的纯 Python 中。当播放列表违反约束时，验证器不会返回 False——它返回违规代码、违规曲目 ID 和具体补救措施，这是自动化修复循环能够工作的唯一原因。

可行性在生成之前检查。如果无法满足需求，系统会明确说明。它从不填充、替换或静默降级——status="infeasible" 是一个正确的结果，并有自己的评估用例。

Related MCP server: Navidrome-MCP

架构规则

不是风格偏好。违反其中任何一条都会破坏项目的目标。

1. 模型从不计算。

2. 工具描述是行为控制——它们是提示词，不是文档。更改工具描述是行为变更，在合并前需要重新评估。

3. 违规是机器可操作的：一个代码、违规 ID、一个补救措施。绝不只是单纯的布尔值，绝不只是文字。

4. 可行性在生成之前检查。

5. 失败是有效的结果。

6. 硬约束被测量和执行。软约束被推断和评分，并带有 provenance 字段，任何关于它们的消息都必须披露该字段。

7. 没有追踪就没有模型调用。

决策及其权衡记录在 docs/adr 中。

技术栈

一切都在免费层上运行。这是一个硬约束，不是偏好。

第 0 到第 2 阶段仅使用标准库——没有框架、没有 SDK、没有依赖。在引入任何抽象之前，原始 HTTP 调用是手工编写的，因此当框架歪曲其行为时，差异是可见的。

构建进度

十二个阶段，四个阶段组。每个阶段一个分支和一个 squash 合并的 PR，因此历史记录读起来就像构建实际发生的过程。

运行

你需要 uv。它安装并管理 Python 本身，因此它是唯一的先决条件。

winget install --id=astral-sh.uv -e

然后，从仓库根目录：

uv sync

这会创建一个虚拟环境，从 .python-version 安装固定的 Python 版本，并安装项目。

从 Google AI Studio 添加免费的 Gemini API 密钥：

copy .env.example .env

将密钥粘贴到 GEMINI_API_KEY= 后面。然后查看你的密钥可以访问哪些模型，因为免费层的目录会随时更改，恕不另行通知：

uv run scripts/raw_call.py --list

将其中一个 ID 作为 GEMINI_MODEL 放入 .env，然后发起调用：

uv run scripts/raw_call.py

它在提取答案之前打印完整的请求和完整的响应。这就是脚本的意义所在——在框架隐藏它们之前，这些结构值得了解。

你账户的实际速率限制显示在 aistudio.google.com/rate-limit；Google 不再在 API 文档中发布按模型划分的免费层表格。

评估

评估套件在第 5 阶段落地。用例是手工编写的，从不生成——如果同一个工具既编写代码又编写评分，那么分数毫无意义。分数以多次运行的通过率报告，因为在非确定性系统上的一次通过只是一个轶事。

任何更改提示词、工具描述或模型的提交，其消息中都会包含评估前后的分数。

许可证

MIT。参见 LICENSE。

由 David Koen 构建。