从 AGENTS.md 读懂 Soup面向 AI 编码 Agent 的仓库入口、构建测试与强制开发约定【免费下载链接】SoupFine-tune LLMs from one YAML. Layer streaming trains an 8B model on a 4 GB laptop GPU.项目地址: https://gitcode.com/GitHub_Trending/soup12/Soup导读Soupsoup-cli当前版本 0.75.0是一个 CLI 优先的 LLM 微调工具主打“从一个 YAML 完成微调”并要求 Python 3.10、Apache-2.0 许可。本文以仓库根目录的AGENTS.md为主体系统拆解这份“工具无关的 AI 编码 Agent 入口文件”它如何指导 Codex、Cursor、Aider、Claude Code 等 Agent 完成构建、测试与提交前自检如何用一组强制约定保证配置单一来源、CLI 启动轻量、路径安全与代码风格统一以及每条约定背后的源码与测试证据Pydantic v2 配置、延迟导入、rich输出、realpathcommonpath 路径包含、ruff 100 列等帮助读者快速上手开发与自动化协作。AGENTS.md 的定位给 AI Agent 的“项目使用说明书”在当今的 AI 辅助开发工作流中Codex、Cursor、Aider、Claude Code 等编码 Agent 在动手改代码之前需要一个可靠的入口来快速了解项目规则。仓库根目录的 AGENTS.md 正是为此设计的——它在文件头就写明自己是“Tool-agnostic entry point for AI coding agents”工具无关的 AI 编码 Agent 入口点即不绑定任何特定 Agent 产品任何能读懂 Markdown 的自动化工具都可以把它当作行为准则。文件同时对项目做了两句话定位Soup 是一个 CLI-firstCLI 优先的 LLM 微调工具Python 3.10Apache-2.0 许可。这份定位与 pyproject.toml 中的声明完全一致项目名soup-cli版本 0.75.0requires-python 3.10,3.13。值得注意的上限约束3.13在 pyproject 中有明确注释说明CI 只验证 3.10/3.11/3.12若放开上限pip 在 3.13 上解析出的 torch wheel 从未被本项目运行验证过且失败会以c10.dll/libc10.so的加载崩溃形式出现用户得不到任何可操作的错误信息。同时tests/test_requires_python_bound.py从 CI 矩阵推导该边界只改一边而不改另一边会导致测试套件失败——这本身就是 AGENTS.md 强调“约定必须被测试锁定”的范例。构建与测试一条命令进入可开发状态AGENTS.md 给出的“Build test”段落是三行核心命令也是 Agent 进入开发状态的第一动作pip install -e .[dev] # Editable install test deps pytest tests/ -v --tbshort # Run the suite (smoke tests are excluded by default) ruff check src/soup_cli/ tests/ # Lint — must be clean before any commit可编辑安装与[dev]依赖树pip install -e .[dev]执行的是可编辑安装并带入 dev 测试依赖。从 pyproject.toml 可以看到依赖管理的几个关键设计核心依赖刻意保持轻量v0.71.0 起typer、rich、pydantic、pyyaml、huggingface-hub、plotext、packaging不包含 PyTorch重型训练栈被拆进[train]extratorch2.6.0、transformers5.16.1,6.0.0、peft0.20.0,1.0.0、trl0.29.0,1.0.0、datasets、bitsandbytes、accelerate等只有pip install soup-cli[train]才会带入[dev]通过自引用soup-cli[train,mcp,data]拉入完整训练栈同时带上pytest、ruff、pytest-cov、mypy、pre-commit等开发工具——这正是 CI 跑pip install -e .[dev]后每个测试都能import torch成功的原因[dev]还顺带带入cryptography[sign]extra和reportlab[pdf]extra保证soup adapters sign/soup attest与soup train --annex-xi *.pdf的测试在 CI 中可运行。此外[project.scripts]中注册了soup soup_cli.cli:run安装后即可直接用soup命令。测试套件与 smoke 标记pytest tests/ -v --tbshort # 默认排除 smoke 测试 pytest -m smoke # 运行下载模型并真实训练的慢测试AGENTS.md 特别说明pytest -m smoke运行那些“下载模型并训练”的慢测试默认被跳过。这一行为来自 pyproject.toml 的 pytest 配置markers [ smoke: slow smoke tests that download models and run training (run with: pytest -m smoke), unit: fast isolated tests — no subprocess, network, filesystem, or real model load, integration: tests that touch real subprocess, SQLite, filesystem, or HTTP, ] addopts -m not smoke --covsoup_cli --cov-fail-under77 --cov-reportterm-missing:skip-covered可见默认addopts是-m not smoke同时强制了 77% 的代码覆盖率门槛--cov-fail-under77并把未覆盖行以 term-missing 形式输出方便提交前补齐。CI 矩阵AGENTS.md 声明 CI 矩阵为Python 3.10 / 3.11 / 3.12 × Ubuntu / Windows / macOS共九组组合。这与requires-python 3.10,3.13的边界一一对应也与tests/test_requires_python_bound.py的推导逻辑互相锁定——这也是为什么 AGENTS.md 会把 Python 版本上限当作一条不可随意改动的纪律。强制开发约定Conventions逐条拆解AGENTS.md 的“Conventions (must follow)”一节是全文的硬核部分共五条。每条背后都能在源码与测试中找到对应实现。约定 1配置是 Pydantic v2schema.py是唯一事实来源Configis Pydantic v2 insrc/soup_cli/config/schema.py— single source of truth.Soup 的全部配置字段由 src/soup_cli/config/schema.py 定义任何其他位置都不得另立一套字段解释。该文件当前约 7000 行全部由 Pydantic v2 的BaseModel/Field构成。以 LoraConfig 为例可以看到“唯一事实来源”的实际形态——每个字段都带有校验与说明class LoraConfig(BaseModel): # #340 — r: 0 is the first-class full-fine-tuning switch... r: int Field( default64, ge0, description( LoRA rank. 0 full fine-tuning: no adapter, every base parameter trains (sft / embedding transformers text quantizationnone only). ), ) alpha: int Field(default16, descriptionLoRA alpha) dropout: float Field(default0.05, descriptionLoRA dropout) target_modules: Union[str, List[str]] Field(defaultauto, ...) use_dora: bool Field(defaultFalse, ...) use_rslora: bool Field(defaultFalse, ...) use_vera: bool Field(defaultFalse, ...) use_olora: bool Field(defaultFalse, ...) rank_pattern: Optional[Dict[str, int]] Field(defaultNone, ...)几个值得注意的设计细节r字段带ge0其中r: 0被设计为一等公民的“全参微调开关”不挂任何 adapter基础权重直接训练见 schema 中 #340 的注释这是trainer/classifier.py自 v0.71.12 起就读取的语义在 #340 之前负 rank 会穿透到 peft 深处才报错ge0从解析阶段就堵住了这个洞schema 的边界常量从运行时模块导入例如stream_buffers的上下界直接来自soup_cli.utils.layer_stream的MIN/MAX_STREAM_BUFFERS见 schema.py 顶部导入noise_floor的上下界来自soup_cli.utils.ship_verdictschema.py 第 25-28 行——这样“schema 里的边界”与“运行时校验器的报错信息”永远不会互相矛盾schema 甚至对参数名模式做了ReDoS 防护_UNFROZEN_REDOS_RE会在解析阶段拒绝(x)y这类嵌套无界量词的正则schema.py 第 39-43 行因为soup.yaml是可共享的配置文件模式“类”必须在 parse 时就被拒绝而不是等re.search灾难性回溯时才暴露。配置的加载与校验则由同目录的 src/soup_cli/config/loader.py 承担测试侧有tests/test_loader.py、tests/test_config.py以及专门验证“配置字段确实有消费者”的tests/test_issue748_config_fields_reach_a_consumer.py来反向锁定——字段不能只躺在 schema 里而无人消费。约定 2重型依赖必须函数内延迟导入Heavy deps(torch,transformers,peft,trl,mlx) are lazy-imported inside functions, never at module top.这条约定的动机非常实际CLI 的启动速度。核心安装刻意不含 PyTorch见前述[train]extra 拆分因此import soup_cli.cli绝不能把 torch 等重型依赖带进内存——否则在未安装[train]的环境里 CLI 直接崩溃在已安装的环境里启动会慢约 7 倍。这条约定不只是风格建议而是有运行时测试锁定的硬性不变量tests/test_cli_startup_is_light.py 在全新的子进程里执行import soup_cli.cli随后检查sys.modules中是否出现torch、transformers、accelerate、peft、trl、datasets、bitsandbytes中的任何一个见该文件 HEAVY 常量与 probe 逻辑。该测试文件的 docstring 点明了为什么 AST 静态扫描不够用AST 守卫只能证明“这个文件没有顶层import torch”但无法看穿传递导入也无法看穿在模块作用域被调用的“伪装成延迟”的工厂函数——v0.71.41 的回归正是这样在所有守卫全绿的情况下混进去的。而一个运行时断言可以传递覆盖所有模块且不会漂移。对应的正向佐证在 src/soup_cli/cli.py 中模块顶部只导入typer、rich、soup_cli.commands等轻量模块而所有训练相关的重型导入都发生在命令函数内部。CONTRIBUTING.md 也给出了正反示例对比错误写法是在模块顶层from torch import cuda正确写法是在函数内部延迟导入并改用rich输出。约定 3输出必须走rich.console.Console禁止裸print()Outputviarich.console.Console, never bareprint().cli.py 第 72 行 创建了全局console Console()所有命令模块的输出统一走 Rich 的表格、进度条、着色等能力。这条约定保证了两件事一是输出风格与终端宽度处理全局一致二是配合 UTF-8 引导见下避免 Windows 上的UnicodeEncodeError。值得一提的是 cli.py 顶部的 UTF-8 stdio 引导from soup_cli.utils.encoding import force_utf8_stdio必须在任何 Rich console 构造之前运行在 Windows 上把sys.stdout/stderr重配为 UTF-8防止 β / ✓ / 框线字符在 cp1251/cp1252 终端上崩溃POSIX 下是 no-op。约定 4路径包含判定用 realpath commonpath不用Path.resolve() relative_to()Path containment: useos.path.realpathos.path.commonpath, notPath.resolve() relative_to()(breaks on Windows short names).这是 AGENTS.md 中最“反直觉”的一条约定背后是一个真实的 Windows 兼容性坑两个路径中的一个可能携带 Windows 8.3 短名如C:\Users\RUNNER~1另一个携带长名此时relative_to会对“确实在基目录内”的路径抛出ValueError导致守卫误拒合法的写入。仓库中的正确姿势是soup_cli.utils.paths模块其中is_under(path, base)/is_under_cwd(path)封装了os.path.realpathos.path.commonpath的组合可见于 autodistill/fingerprints.py 第 34-38 行 与 autodistill/mlx_worker.py 第 147-151 行 的同款实现。更重要的是这条约定有一个专门的 AST 扫描测试把它锁成仓库级铁律tests/test_issue775_path_containment_ratchet.py。该测试对src/soup_cli/**/*.py做 AST 遍历识别所有“做出包含性判断”的relative_to/is_relative_to调用is_relative_to一律判为违规它存在的唯一目的就是回答包含性问题try中except可捕获ValueError的relative_to判为违规该 handler 就是包含性决策出现在if/while/assert条件、布尔表达式、推导式 filter 中的relative_to判为违规而纯展示用途的rel p.relative_to(root)无 ValueError 守卫放行——缩短路径用于表格展示不构成决策。该文件还包含“扫描器必须真的能抓到东西”的控制测试TestTheScannerCanActuallyFail以及“allowlist 不允许有死条目”的校验test_the_allowlist_has_no_dead_entries——两条 allowlist 条目commands/adapters.py:29与:98都被证明是展示用途且附有理由代码一旦移动或修复allowlist 必须同步更新否则测试失败。这说明 Soup 的工程纪律是“约定 测试锁 反测试”三层结构。约定 5行长 100ruff 规则 E, F, I, N, WLine length100, ruff rulesE, F, I, N, W.pyproject.toml 第 240-245 行 的 ruff 配置与之完全对应[tool.ruff] target-version py310 line-length 100 [tool.ruff.lint] select [E, F, I, N, W]Epycodestyle 错误含行长FPyflakes未使用导入/变量等Iisort 风格的导入排序NPEP 8 命名约定Wpycodestyle 警告。CONTRIBUTING.md 还补充了这条规则的几个推论禁止单字母变量名ruff E741建议用entry、part、length而非l、p以及一条很容易被 AI 生成代码踩中的红线——禁止第三方许可证头项目以 Apache-2.0 发布并上 PyPI任何SPDX-License-Identifier或他人版权行都是无法做出的许可声明tests/test_no_foreign_license_headers.py会在构建时拦截而不是依赖人工 review 发现历史上已发生过三次模板生成带入的情况。完整指引Full instructionsAgent 动手改代码前的阅读顺序AGENTS.md 的最后一段给出了“完整指引”告诉 Agent 在改动任何功能之前先读什么特性参考在docs/——按主题划分的指南外加完整的soup命令列表docs/commands.md。改某个特性之前先读对应页面贡献流程、项目结构与架构笔记在CONTRIBUTING.md——做非平凡改动前必读Pydantic 配置 schema在src/soup_cli/config/schema.py——每个配置字段的唯一事实来源。这三条本质上在说同一件事Soup 的文档、配置与代码三者互为索引Agent 不能只凭对项目的泛泛印象就动手。从 docs/README.md 的目录表可以看到文档覆盖面训练任务与方法SFT、DPO/GRPO/PPO/KTO/ORPO/SimPO/IPO/BCO、工具调用、蒸馏、视觉/音频/TTS 等、PEFT 与效率DoRA、LoRA、rsLoRA、VeRA、OLoRA、NEFTune、PiSSA、ReLoRA、packing、curriculum 等、性能与量化QAT、FP8、KV-cache、层流式加载 layer streaming、多卡/DeepSpeed/FSDP、数据工程、评估、服务与导出、适配器与治理、合规快速入门、后端与运维、命令参考、模型与 extras 矩阵。README 本身是“5 分钟快速入门”docs/则是完整的特性参考。而 CONTRIBUTING.md 进一步给出了开发环境搭建的细节Python 3.10/3.11/3.12、在虚拟环境中pip install -e .[dev]并在 PEP 668 的 Debian 12 / Ubuntu 23.04 上强调 venv 不可省略、pytest tests/ -v --tbshort验证、ruff check src/soup_cli/ scripts/ tests/ benchmarks/检查。它还说明了项目结构src/soup_cli/cli.py是命令路由入口commands/是各命令实现config/是 schema 与 loaderdata/、trainer/、utils/等按功能分域。结语AGENTS.md 是“可被自动执行的工程契约”通读 AGENTS.md 可以看到它并非一份普通的 README 附录而是一份刻意写给自动化工具、并刻意可被自动化验证的工程契约定位清晰工具无关任何 AI 编码 Agent 都能消费动作明确安装、测试、lint 三条命令即可进入可贡献状态约定可证配置唯一来源Pydantic v2 schema、CLI 轻启动延迟导入 运行时探针测试、路径安全realpathcommonpath AST 扫描 ratchet、代码风格ruff E/F/I/N/W 100 列——每一条都有对应的源码路径与测试用例锁定而不是停留在“建议”层面路径索引完备改功能先查docs/、非平凡改动先读CONTRIBUTING.md、改配置先看schema.py文档-配置-代码三方闭环。对于接入 Soup 仓库的编码 AgentCodex、Cursor、Aider、Claude Code 等而言这份文件相当于“上岗前培训”读完它Agent 就知道在哪里建环境、用什么命令自检、遵守哪些不可违背的约定以及在改动前该查阅哪份文档。对于想理解 Soup 工程实践的开发者它同样是一份浓缩的架构与质量红线索引——沿着文中给出的每个路径schema.py、cli.py、utils/paths.py、test_issue775_path_containment_ratchet.py、test_cli_startup_is_light.py、pyproject.toml继续深入即可还原整个项目的设计决策链。【免费下载链接】SoupFine-tune LLMs from one YAML. Layer streaming trains an 8B model on a 4 GB laptop GPU.项目地址: https://gitcode.com/GitHub_Trending/soup12/Soup创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考