Equipment Developer 是一个针对 Equipment 框架的专家技能。Equipment 是发布于 PyPI(包名 equipment)的 Python 项目脚手架框架,源代码位于 https://github.com/rogervila/equipment。该技能用于协助用户和 LLM 构建、测试、调试、部署与维护 Equipment 应用。
分层模型
Equipment 分为两层。框架层是已安装的 equipment 包,包含配置加载、dependency-injector 容器,以及日志、队列、存储和 SQLAlchemy 的工厂。应用层是 equipment new 生成的项目,归用户所有,可以自由编辑。技能要求以托管文档作为预期用法依据,以已安装包源码作为实际运行时行为依据;两者冲突时,按 references/verified-behavior.md 中经验证的行为执行,并告知用户存在差异。
何时使用
当项目包含 app/init.py 且内有 class App(Equipment) 或 from equipment import Equipment、config/*.yaml 含 ${VAR:default} 占位符、存在 main.py、web.py、queues.py、scheduler.py 入口,或依赖中出现 equipment、用户提到 equipment new / equipment compile / equipment-python.vercel.app / rogervila/equipment 时;任务涉及容器、配置、数据库、日志、队列、调度器、存储、测试、编译或生成的 FastAPI 入口时;以及需要修改 Equipment 仓库本身(equipment/ 包、project/ 模板、测试、website/ 文档)时使用。非 Equipment 项目、同名但指设备/库存、或与 Equipment 无关的通用库问题,不应以此技能为主要依据。
前置条件
改代码之前需先确认:项目性质(Equipment 应用、Equipment 仓库或都不是);Python 版本(3.13、3.14 或 3.15)、操作系统与安装方式(pip install . 或 pip install -e .);.env 与进程环境中启用的 DB_CONNECTION、QUEUE_CONNECTION、FILESYSTEM_DISK、LOG_CHANNEL、APP_ENV(不得打印密钥值);哪些入口在哪些进程中运行、存在哪些外部服务(Redis、S3、MySQL、PostgreSQL);以及 app/init.py、相关 config/*、tests/TestCase.py 和所涉入口的当前内容。
快速流程
先分类请求,再检查上述项目文件(可选运行只读的 python scripts/equipment_doctor.py <project-root>),引用易变细节前先查当前文档(llms-full.txt 或单个 .md 页面),然后按 Equipment 惯例实现:服务放在 app/、在 app/init.py 注册、每个服务一个配置文件、构造器注入、模块级队列任务、完整类型注解;补充使用生成 TestCase 的 unittest 测试并撤销所有覆盖;在项目根目录用 python -m unittest、对每个新写文件的严格 mypy 检查,以及相关入口/迁移/编译冒烟测试进行验证;最后报告改动、验证结果与文档差异或坑点。
心智模型
app() 调用 App.make(base_path):先加载 .env,再加载基础路径下的 config/.ini、.yaml、*.json,并按 (class, base_path) 为整个进程缓存一个容器。基础容器提供 config、log、queue、storage、database,均为首次调用时构建的 ThreadSafeSingleton provider;queue、storage、database 都接收 log。app/init.py 中的 App 是组合根,服务在此以构造器注入注册。驱动由配置选择:sync 或 redis 队列;local 或 s3 存储;sqlite、mysql、postgresql 数据库;stack、single、daily、console、sqlite、null 日志通道。Equipment 不替代 FastAPI、SQLAlchemy、Alembic、RQ、schedule、boto3、unittest,需要时在服务中直接使用这些库。
命令速查(在项目根目录执行)
创建项目:equipment new my-app(确认 my-app/pyproject.toml 存在,退出码始终为 0)。 开发安装:python -m pip install -e ".[dev]"。 运行脚本入口:python main.py。 测试:python -m unittest 或 python -m unittest discover -s tests -t .。 单测:python -m unittest tests.app.test_Inspire.TestInspire.test_quote。 覆盖率:python -m coverage run -m unittest,然后 python -m coverage report --omit="/tests/,*.pyx"。 类型检查:python -m mypy --explicit-package-bases --follow-untyped-imports app tests;对自写文件追加 --follow-imports=silent --disallow-untyped-defs --disallow-incomplete-defs <files>。 迁移:cd database/migrations 后 alembic upgrade head。 Worker:python queues.py(Redis;需 push_at 时用 w.work(with_scheduler=True))。 调度器:python scheduler.py(单副本)。 Web:python web.py 或 uvicorn web:web --host 127.0.0.1 --port 8000。 编译:python -m equipment compile dist,然后 cd dist 并 python main.pyc。
已验证的主要坑点(2026-11-01,equipment 1.3.0)
文档中的 python -m unittest discover -s tests 会因 tests/app/ 遮蔽 app 而失败,应改用 python -m unittest 或加 -t .;生成的 .env 默认 APP_ENV=production、DB_CONNECTION=mysql、DB_DATABASE=equipment,本地应改为 local、sqlite、database/database.sqlite;app() 按进程缓存,测试中的覆盖与 from_value() 会泄漏,需用 self.enterContext(provider.override(x))、self.enterContext(config.key.override(v)) 与 reset_singletons();YAML 会插值类型(yes 变 True、00123 变 83),需保持字符串的占位符要加引号或用 .as_int()/cast;缺失配置键会静默返回 None,强制值用 .required();alembic revision --autogenerate 因 target_metadata = None 失败,需在 database/migrations/env.py 设为 Base.metadata;生成的 queues.py 不会执行 push_at() 任务,需 w.work(with_scheduler=True);REDIS_USERNAME 与 REDIS_PASSWORD 被忽略,需用已认证工厂覆盖队列 provider;同步队列会吞掉任务异常,Redis 下队列化的 lambda 与嵌套函数会先返回 True 再在 worker 中失败,应检查 push() 结果、以 ID 参数排队模块级函数并查看 RQ 失败任务注册表;scheduler 没有 self.config 且作业异常会终止循环;本地 move() 到不存在目录会失败、local 与 S3 的 list() 行为不同、../ 可逃逸根目录;覆盖 App 中的 queue 不影响使用 Equipment.queue 的 provider;equipment compile 会编译项目内 .venv 和 build/ 并复制 .env;对已有目录执行 equipment new 并回答 y 会覆盖 app/init.py 和 .env;在项目根目录外运行会报 TypeError: 'NoneType' object is not subscriptable;被 app/init.py 导入的模块若顶层 from app import app 会循环导入,应在函数内导入;模板 todos 示例使用 BIGINT 主键在 SQLite 不自动递增,需 BigInteger().with_variant(Integer, "sqlite");mypy 需 --explicit-package-bases --follow-untyped-imports 并对 App.make 加窄化 # type: ignore[arg-type]。
输出与完成标准
编写代码须完全类型注解(含 -> None),框架服务标注 AbstractLogger、AbstractQueue、AbstractStorage、SQLAlchemyFactory;使用 unittest 与生成 TestCase,不引入 pytest(除非项目已用);服务在 app/init.py 以构造器注入注册,app() 只在进程边界调用;新配置写入 config/<name>.yaml 并配顶层键、同步更新 .env.example 的假值、字符串占位符加引号;优先配置和现有驱动,不修改已安装的 equipment 包;给出跨平台命令(python -m ...)及 Windows 差异说明。完成条件为:代码符合 Equipment 模型;测试通过且撤销全部覆盖;每个新写函数完全注解且严格 mypy 通过(不可用需说明);配置变更反映到 .env.example;数据库变更含已审阅的 Alembic 迁移或说明无需原因;相关运行时路径已实际执行;依赖不可用服务(Redis、S3、MySQL、PostgreSQL、Windows)的检查列为未运行。请求不明确、需凭据或生产数据、会覆盖用户工作/删除数据/泄漏密钥、已安装版本行为与经验证笔记不同、或问题属上游缺陷(可建议在 https://github.com/rogervila/equipment/issues 提 issue)时,应停下询问或明确报告。
限制
该技能针对 Equipment 框架及其生成项目,不适用于同名但指实体设备库存/租赁的场景;非 Equipment 项目中 SQLAlchemy、Alembic、RQ、schedule、boto3、FastAPI 的通用问题应转向对应库文档。