跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

night-market-build-and-env

Rebuild the dev environment: uv, Python tiers, pins, traps. Use when onboarding or toolchain breaks. Do not use for daily commands; use night-market-operations.

athola · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add athola/claude-night-market --skill night-market-build-and-env

技能说明


name: night-market-build-and-env description: "Rebuild the dev environment: uv, Python tiers, pins, traps. Use when onboarding or toolchain breaks. Do not use for daily commands; use night-market-operations."

night-market-build-and-env

Recreate a working claude-night-market development environment from a bare machine, verify it in under an hour, and avoid the traps that have broken it before. Everything below was verified against the repo on 2026-07-02 (v1.9.15).

One rule dominates: every Python tool runs through uv run. uv is Astral's Python package and environment manager. On first uv run it creates .venv/ and syncs it from uv.lock. Never install repo dependencies with bare pip.

Toolchain setup

Install in this order. "via uv" means the tool resolves from uv.lock automatically. There is no manual install step for those rows.

#ToolRequired?Install hintVerify command
1uvREQUIREDofficial installer at astral.sh/uvuv --version
2Python 3.12REQUIREDuv python install 3.12python3 --version
3make + bashREQUIREDdistro package (build-essential, Xcode CLT)make --version
4ruff >=0.14.13via uvnone (dev dependency in uv.lock)uv run ruff --version
5banditvia uvnone (pre-commit env is pinned separately, see traps)uv run bandit --version
6mypy >=1.13via uvnoneuv run mypy --version
7pre-commit >=4via uvuv run pre-commit installuv run pre-commit --version
8Python 3.9optionaluv python install 3.9uv venv --python 3.9 /tmp/py39-check
9node + npmoptionalneeded for conjure Gemini delegationnode --version
10Rust + cargooptionalrustup (only for make skrills-build)cargo --version
11skrills binaryoptionalmake skrills-build or make skrills-installmake skrills-verify
12mdbookoptionalcargo install mdbook; builds book/mdbook --version
13gh CLIoptionalcli.github.com (releases and Discussions)gh --version

Notes on the optional rows:

  • Python 3.9 is ONLY for local hook-compatibility testing. Hooks are scripts Claude Code runs on tool events under the host system Python (macOS ships 3.9.6), outside any virtual environment. CI enforces this in .github/workflows/python39-compat.yml.
  • The conjure plugin delegates to Gemini. The root package.json pins @google/gemini-cli at ^0.25.1. Run npm install at the repo root only if you use conjure delegation.
  • skrills is a Rust CLI that validates and analyzes skill files. Every Makefile target that uses it (make validate-skills, make analyze-skills) has a Python fallback, so you can skip Rust entirely.
  • gh is needed for releases and for GitHub Discussions. Discussions have no gh discussion subcommand. They are reachable only through gh api graphql.

Version numbers observed on the reference machine (2026-07-02): uv 0.8.22, Python 3.12.3, ruff 0.14.13, mypy 1.19.1, bandit 1.9.2, pre-commit 4.5.1. Newer versions of uv are fine. The ruff version must match uv.lock (see traps).

First-hour verification sequence

Run these in order after installing rows 1-3 above. Each step lists the output shape that means success.

Step 1: clone and check uv.

git clone git@github.com:athola/claude-night-market.git
cd claude-night-market
uv --version

Expected: a single line like uv 0.8.22. Any 0.8+ version works. CI pins astral-sh/setup-uv@v8.2.0.

Step 2: validate all plugin structures (also proves the venv syncs).

make validate-all

Expected: one block per plugin (26 directories) shaped like:

>>> Validating plugins/abstract:
Plugin Validation Report: abstract
...
OK Plugin validation passed

Blue "Recommendations" lines are advisory and fine. A red failure line or (validation failed) is not.

Step 3: run one fast plugin test suite.

make -C plugins/leyline test

Expected: verbose pytest output ending with a coverage table and a summary like 710 passed, 6 warnings in 9.96s (counts and timing drift, but zero failures is the invariant). This proves uv run, pytest, and per-plugin coverage thresholds all work.

Step 4: install the git hooks.

uv run pre-commit install

Expected: pre-commit installed at .git/hooks/pre-commit. From now on commits run the full hook chain (file validation, bandit, ruff, mypy, changed-plugin tests, structure validation). Never bypass it with --no-verify; CONSTITUTION.md forbids that.

If any step fails, load night-market-debugging-playbook.

Python version tiers

This is the number-one onboarding misconception. The README says "Python 3.9+ for hooks", and newcomers read that as "the repo runs on 3.9". It does not. There are three tiers:

TierVersionEnforced byWhy
Root tooling (pytest, ruff, mypy)3.12root pyproject.toml requires-python = ">=3.12", ruff target-version = "py312", mypy python_version = "3.12"dev toolchain runs inside the uv venv
Plugin packagesvaries, 3.9 to 3.12each plugins/<name>/pyproject.tomlplugins are independent deployables (ADR-0001)
Hook import chains3.9.github/workflows/python39-compat.ymlhooks run under the HOST system Python (macOS 3.9.6), outside any venv

Per-plugin requires-python as of 2026-07-02 (22 of 26 plugin dirs have a pyproject.toml):

  • 3.12: abstract, conjure (also <3.14), imbue, leyline, minister, sanctum, scry
  • 3.10: attune, conserve, hookify, memory-palace, parseltongue, pensive, scribe, spec-kit
  • 3.9: archetypes, egregore, gauntlet, herald, oracle, phantom, tome

Why the hook tier exists: Claude Code executes hook scripts with whatever interpreter the host provides, not the repo venv. A hook file AND everything it transitively imports must therefore sta

阅读完整来源 ↗