用途
sniffable-python 用于约定 Python 脚本的组织方式，使大语言模型能够在阅读约前 50 行后理解并调用该工具。文档的表述是："Structure code for the first 50 lines. That's all the LLM needs." 其目标不是发明新语法，而是对既有 Python 语法重新排布，以获得更优的 LLM 理解效果。
主要能力与结构模式
方案给出的规范结构分为几个区域：
- Shebang + Docstring（约 1-15 行）：包含用途、用法示例、关键行为；该 docstring 同时成为 --help 的输出内容，并对 LLM 直接可见。
- Imports（约 16-22 行）：依赖一目了然。
- Constants（约 23-30 行）：配置、有效取值、上限等。
- CLI Structure（约 31-50 行）：命令树，含类型与说明。
- Implementation（51 行起）：仅在需要修改行为时才阅读。
示例中 main() 只包含 argparse 的命令树定义（move / examine / status 子命令、参数与选项），随后调用 _dispatch(args)，实现部分放在 main 之下。
使用方式
sniffable-python 本身是一套约定，不含安装命令或运行命令；资料未提供安装方式。实际使用时按上述规范编写脚本，例如：
#!/usr/bin/env python3
"""skill-name: Brief description of what the script does.
Usage:
python script.py command [options]
Examples:
python script.py move north --quiet
python script.py examine sword --verbose
"""
文档建议 CLI 装饰器即文档，例如 @click.option('--verbose', '-v', is_flag=True, help='Show details') 一行同时定义 flag 名、短形式、类型、帮助文本与参数名，做到单一来源、无重复无漂移。
为何采用 argparse
文档对比 Argparse、Click、Typer：Argparse 在结构与实现分离、自上而下树序、内置无依赖、训练数据丰富、LLM 熟悉度最高等方面被列为更优。Click/Typer 的装饰器附着在函数上，导致 CLI 结构与实现交织，需要读实现才能理解。
注释的作用
文档主张把 YAML-JAZZ 原则用于 Python 注释，注释本身即数据，例如：
TIMEOUT = 30 # generous — API is flaky on Mondays
MAX_RETRIES = 3 # based on observed failure patterns in prod
BATCH_SIZE = 100 # memory-safe for 8GB instances
# TODO: Add circuit breaker after next major outage
# NOTE: This duplicates logic in api_client.py — consider extracting
规则是每个注释 token 都应携带含义，纯装饰性分隔或 ASCII 花边应删除。
目录无关的调用
文档要求脚本无论从哪个目录被调用都能找到自身上下文，应使用 Path(__file__) 而非 os.getcwd()：
SCRIPT_DIR = Path(__file__).resolve().parent
SKILL_DIR = SCRIPT_DIR.parent
CARD_FILE = SKILL_DIR / "CARD.yml"
适用场景
- 作为 skill 生成的 sister script 的结构规范。
- 需要被 LLM 快速理解并调用的 CLI 工具。
- 位于 play-learn-lift 流程的 LIFT 阶段，把验证过的流程固化为可复用自动化。
- adventure 类技能中的校验器反馈回路：LLM 生成内容 → sniffable linter 校验 → 输出 YAML 结果 → LLM 读取并修正。
限制与说明
文档明确反对压缩语法（如 Perl 式密集符号），认为符号歧义会增加模型消歧成本；主张可理解性优先于 token 数量。关于收费、价格、平台、具体效果等事实，资料来源未提供。