这类技术统称测试影响分析（test impact analysis），而 testmon 是在 Python 里免费、开源地用上它的一种办法。它完全不依赖 git：它对比的是上次运行时看到的代码，提交没提交都一样。

这周我把它加进了我那个集市应用的 Python 测试里，原因并不是为了快而快。

为什么要加它

#

一个功能需求通常很小：一个界面、一个接口、一条要换个做法的规则。跑整个测试套件，让每个需求都变得比它本身更大。这个套件有 2,248 个 Django 测试，四个进程跑大约三分半，单进程要 11 分钟，而每次编辑都会把它整个跑一遍，尽管其中几乎全部检查的都是这个需求根本没碰过的东西。只要有不相干的测试失败，或者运行单纯慢了点，功能就得等着。拖住它的，是功能需求之外的情况，而那个拖住它的东西，正是我自己的测试套件。

另一条路也好不到哪儿去：不跑全量，猜哪个测试文件覆盖了这次改动，偶尔猜错。这样是快，但不精确，而我发出去的每一个未经测试的改动，都是一个要做两遍的功能需求。

我等的测试应该恰好是这次改动能触及的那些，不多也不少。testmon 给我的这组测试来自记录，而不是猜测。全量套件照样在跑，只不过是在 CI 里，不会拖住我接下来手上的任何事。

它怎么决定跑什么

#

testmon 把每个 Python 文件切成代码块：模块的顶层、每个类、每个函数，嵌套函数的函数体会从外层代码块里切出去。它为每个代码块存一个校验和，从不存代码本身。测试运行时，coverage.py 记录它执行的代码行，testmon 记下这些行属于哪些代码块。没有静态分析，也不靠 import 去猜。一个测试依赖的，恰好就是它跑过的那些代码块。

拿这样一个模块来说：

# pricing.py
def subtotal(items):
    return sum(item.price * item.quantity for item in items)

def discount(total, code):
    if code == "WELCOME10":
        return total * 0.9
    return total

一个只调用 subtotal() 的测试，依赖的是模块顶层和 subtotal 的函数体。discount() 随你怎么改写，testmon 都不会重跑这个测试，因为它从没执行过 discount 里的任何一行。而在 subtotal 里哪怕只改一个字符，它就会再跑一次，即使这个改动根本不可能改变结果。testmon 不会在副作用上耍聪明：你执行过的代码块变了，你就得跑。

它还会追踪代码周围的东西。记录里包括 Python 版本，以及已安装的包及其版本。它不看环境变量：同一份代码要在两个 settings 模块下跑的话，得用 --testmon-env（第 8 步）给它们起名字，否则它们共用一份记录。升级一下 Django，所有碰过 Django 的东西都会再次受影响，而在一个 Django 应用里，那就是全部。

它看不到什么

#

testmon 追踪的是测试执行的 Python 代码。测试读取的其他文件它不追踪：模板、JSON、文本，磁盘上的任何别的东西。经网络访问的服务它也不追踪。而在测试开始前只跑一次的东西，它没法归到某个具体测试头上。

放在 Django 项目里，首先是迁移：它们只在创建测试数据库时跑一次，所以没有哪个测试的记录里包含它们（有新迁移时，下面的包装脚本会重建测试数据库）。其次是设置和启动代码，它们在 pytest 启动时运行，不属于任何一个测试。再就是模板和数据文件：模板不是 Python，所以改了模板，渲染它的测试一个都不会重跑。

我的测试套件还有几样自己特有的。有些测试读取一个 JSON fixture 文件，移动应用的测试也共用它。有些检查构建出来的 Web bundle，还有些检查同一个仓库里生成的静态网站的输出。改了其中任何一个，testmon 都会高高兴兴地告诉你什么都不用跑。所以下面的教程会用一个脚本把 testmon 包起来，这个脚本会留意这些文件，只要其中一个改了，就全部跑一遍。

怎么把它加进 Django 项目

#

以下步骤假定你用 pytest 和 pytest-django，依赖用 uv 管理。用 pip 的话，把 uv add --dev 换成 pip install，去掉 uv run。

1. 安装。

uv add --dev pytest-testmon

2. 确保 pytest 能跑这套测试。 testmon 是 pytest 插件，所以在 python manage.py test 下它什么都不做。pytest-django 需要知道设置模块，以及你的测试所用的文件命名模式：

# pytest.ini
[pytest]
DJANGO_SETTINGS_MODULE = myproject.settings
python_files = tests.py test_*.py *_tests.py
python_classes = Test* *Tests *TestCase

如果这套测试一直只在 Django 自带的 runner 下跑过，先在 pytest 下跑一遍，把不一致的地方修好，再加 testmon。不然你就得同时调试两件事。

3. 别把记录放进 git。 testmon 会在 pytest 根目录写入 .testmondata。它是一个 SQLite 数据库，所以旁边还会出现 -shm 和 -wal 文件，下面的脚本还会再加一个时间戳文件。一个模式就能把它们全部覆盖：

# .gitignore
.testmondata*

4. 先把整套测试记录一遍。 testmon 在看过每个测试运行之前，什么都选不出来：

uv run pytest --testmon

在全新的检出里，第一次运行就是单进程跑完整个套件。在我这里，2,248 个测试大约要 12 分钟。从那以后，同一条命令就只跑受影响的测试。什么都没改的话，它什么都不跑。

有两个坑。在 testmon 2.2.0 及更早版本上，它需要 pytest 的 cache 插件：我第一次尝试时带着 -p no:cacheprovider，结果以 KeyError: 'lf' 崩掉了（2.3.0 会把缺失的 --lf 当作未设置）。另外，在 Python 3.14 或更高版本上，记录之前要先设置 COVERAGE_CORE=ctrace。原因在后面的“看起来全绿的那个 bug”一节里解释。这是下面脚本里最重要的一行。

更新（11 月 7 日）：11 月 2 日发布的 testmon 2.3.0 会自己强制使用 coverage 的 C tracer，所以在这个版本上，这行 export 只是多一道保险。如果你用的是 2.2.0 或更早的版本，就留着它。而故意弄坏点什么来验证的那一步，不管哪个版本都要做。

5. 为它看不到的文件包一层。 正是这一步，让它可以放心地天天用。脚本保留一个时间戳文件，记的是上次运行开始的时间。只要有任何 testmon 追踪不到的文件比这个时间戳新，就全部跑一遍并重新记录。新的迁移只会让它重建测试数据库。其余情况就让 testmon 来选。删减后的示例：

#!/usr/bin/env bash
# scripts/test-changed.sh: the tests a change can affect, or all when in doubt.
#   scripts/test-changed.sh            # affected tests
#   scripts/test-changed.sh --all      # everything, re-recorded
#   scripts/test-changed.sh -k orders  # anything else goes to pytest
set -euo pipefail
cd "$(dirname "$0")/.."

# coverage's C tracer: from Python 3.14 coverage defaults to sys.monitoring,
# which reports a line only the first time a process runs it, so testmon
# would credit each line to one test. Changing this means --all.
export COVERAGE_CORE=ctrace

STAMP=.testmondata.started
full=false
rebuild=false
if [ "${1:-}" = "--all" ]; then
    full=true; shift
elif [ ! -f .testmondata ] || [ ! -f "$STAMP" ]; then
    echo "No record yet: running everything once."
    full=true
else
    # Changed since the last run started, and not traceable per test:
    # anything that isn't Python, plus settings and conftest.
    newer="$(find myapp myproject fixtures pytest.ini \
        -type f -newer "$STAMP" ! -path '*/migrations/*' \
        \( ! -name '*.py' -o -path 'myproject/settings*' -o -name 'conftest.py' \) \
        ! -path '*/__pycache__/*' | head -5)"
    if [ -n "$newer" ]; then
        echo "Changed, and not traceable per test:"; printf '  %s\n' $newer
        full=true
    fi
    # A new migration needs a fresh test database, not a full run.
    [ -n "$(find myapp -path '*/migrations/*.py' -newer "$STAMP" | head -1)" ] && rebuild=true
fi

# Stamp the start, so an edit made while the tests run counts next time.
started="$(mktemp .testmondata.run.XXXXXX)"
args=(--testmon --reuse-db)
# --create-db alone deletes the database when the run ends; with
# --reuse-db as well, the rebuilt one is kept for next time.
[ "$rebuild" = true ] && args=(--testmon --reuse-db --create-db)
[ "$full" = true ] && args=(--testmon-noselect --reuse-db --create-db)

status=0
uv run pytest "${args[@]}" -q "$@" || status=$?
# 0: passed, or nothing selected. 1: some failed (still recorded).
# 5: nothing collected at all.
case "$status" in 0|1|5) mv "$started" "$STAMP" ;; *) rm -f "$started" ;; esac
[ "$status" = 5 ] && exit 0
exit "$status"

这里面有两个细节值得解释。--reuse-db 是 pytest-django 的参数，用来在两次运行之间保留测试数据库。一旦一次运行只要几秒，这一点就很要紧：每次重新创建数据库，花的时间可能比测试本身还长。全量运行，或者有新迁移之后的那次运行，会再加上 --create-db，让数据库用上当前的 schema。--reuse-db 要和它一起留着：单独用 --create-db 时，pytest-django 会在运行结束时删掉数据库，下一次运行就得从头再建一遍。

还有，当 testmon 把所有测试都取消选中时，运行的退出码是 0，所以“什么都没改”算作通过。退出码 5 是 pytest 的 “no tests collected”（没有收集到测试），脚本把它也当作没问题。

注意清单里没有什么：pyproject.toml 和 lock 文件。我的第一版只要 lock 文件一变就全部跑一遍，结果这个慢吞吞的兜底大多数日子都会触发，整件事比以前还糟。testmon 本身就会追踪已安装包的版本，用不着帮这个忙。

6. 给它单独的数据库和缓存。 如果同一台机器上还有别的东西在跑测试，比如第二个终端、一个编程 agent 或者 manage.py test，就让脚本指向它自己的测试数据库和它自己的缓存编号，这样保留下来的数据库永远不会撞上别人的运行：

export DATABASE_URL="postgresql://myapp:myapp@localhost:5432/myapp_changed"
export REDIS_URL="redis://localhost:6379/8"

7. 每次运行前清空那个缓存。 这一条我是吃了亏才学到的。子集运行开始出现 KeyError，全量运行却没有。有些分类标签的缓存没有过期时间，于是一次运行保留下来的测试数据库，碰上了更早一次运行留下、还热着的缓存。在脚本开头清掉缓存，问题就解决了：

uv run python -c "import os, redis; redis.Redis.from_url(os.environ['REDIS_URL']).flushdb()"

这正是 testmon 在做它文档里说过会做的事：每次跑不同的子集，会暴露出那些只是因为之前跑过什么才通过的测试。修复应该放在测试的 setup 里，而不是 testmon 里。

8. 记住选择出错时用的参数。

• --testmon-noselect 跑所有测试，但把可能失败的排在前面。当你同时传了 -k、-m、--lf 或某个测试的 node ID 时，testmon 会自动切换到这个模式。
• --testmon-forceselect 只跑既受影响、又匹配你的 -k 或 -m 的测试。
• --testmon-nocollect 使用已有的记录，但不往里添加。在调试器下，或者 coverage 已经在运行时，会强制使用这个模式。
• --no-testmon 在它写进了 addopts 时，用来关掉一次运行。
• --testmon-env=<name> 在一个文件里保存多份独立的记录，适合要在两个设置模块下跑的测试套件。

如果项目还有 JavaScript 那一侧，Jest 自带了同类功能。jest --changedSince=main 会跑那些 import 了自 main 以来改动过的任何东西的测试，它跟的是 import，而不是覆盖率。我把它加进了应用的 package.json，叫 npm run test:changed，这样两边是同一个习惯。改了一个工具模块，它从应用的 121 个测试文件里选中了 7 个。

它能省下多少

#

包装脚本就位、并修好下一节说的那个 bug 之后，我计了一下时，包括启动时间：

日常的一次编辑，比并行跑整个套件快大约 25 倍；什么都没改的时候，快大约两百倍。

这份记录从更宽的角度说明了同一件事。在测试套件跑的 307 个非测试 Python 文件中，改动中位数的那个文件会波及 22 个测试，测试时间大约 8 秒。另一头是几个核心模块：几乎每个测试都会跑到它们，所以改了那里会波及 1,500 个左右的测试，testmon 会重跑套件的大部分。这才是正确的答案，不是失败。这些数字是按文件算的上限：testmon 按代码块工作，所以改了一个函数，只会选中跑过那个函数的测试。

代价出现在包装脚本退回全量运行的时候。一次全量运行和第一次一样，是单进程的记录，大约 12 分钟，比它取代的那个并行套件还慢。之所以是单进程，只是因为我还没试过把 testmon 和 pytest-xdist 一起用；它从 1.4 起就支持 xdist，下一个该量的就是这个。所以触发全量运行的文件清单，应该在不自欺的前提下尽量短。

看起来全绿的那个 bug

#

我最早的数字比这些好看：改一处，6 个测试，3.3 秒。它们是错的，而屏幕上没有任何东西提示这一点。

从 Python 3.14 开始，coverage.py 默认使用一个新的核心，建立在解释器的 sys.monitoring 之上。这个核心只在一个进程第一次运行某一行时报告它。testmon 关于哪个测试跑了哪一行的记录，是从 coverage 得来的，所以每一行都只记在碰巧第一个跑到它的测试头上，别的测试一概没有。改一行八个测试共用的代码，testmon 只会选中其中一个。

发现它，是在我另一个更小的项目上，那个项目照搬了这套配置。在那里引入它的步骤之一，就是故意弄坏一行代码、对比结果，而数字对不上。回到这个套件，我做了同样的检查。我弄坏了首页横幅代码里的一行，也就是一张幻灯片的标题。直接跑 pytest，报告了 8 个失败的测试。testmon 选中了 4 个。另外 4 个坏掉的测试根本没跑，输出里也没有任何地方说它们被漏掉了。

修复只要一行，export COVERAGE_CORE=ctrace，让 coverage 回到经典的 C tracer。换了 tracer，记录也就不一样了，所以我重新记录了一遍：2,248 个测试，12 分 3 秒。之后，同样那种弄坏代码的改动，把它弄坏的 11 个测试全都跑了。

更新（11 月 7 日）：11 月 2 日发布的 testmon 2.3.0 现在会自己设置 C tracer，进程内和子进程里都会，所以新装的话不再需要这行 export。下一段里的检查仍然需要。

这是我最想先传下去的一条教训。一个选得太少的测试选择器，看起来和成功一模一样：测试更少，跑得更快，全是绿的。所以搭一个这样的东西时，要故意弄坏某个共用的东西，分别跑原本的完整套件和选择器，确认它们失败的是同一批测试。之后每当 Python 或 coverage.py 升级版本，再做一遍。

编程 agent 在哪里用得上

#

那个仓库里的改动，已经不全是我自己做的了。一个编程 agent，我用的是 Claude Code，做了很多小改动，而一个好的 agent 每次编辑后都会跑测试。面对一个 11 分钟的测试套件，它的两个坏选择和我当初一样：等，或者猜哪个测试文件要紧。

所以仓库里给 agent 的说明现在写着：工作时跑测试，默认就用这个包装脚本，要全量运行就加 --all。每次编辑后，agent 都能在几秒内拿到和我一样精确的那组测试。这也是第 6 步要给脚本单独的数据库和缓存的原因：忙的时候，同一台机器上不止一个会话在跑测试，而保留下来的数据库绝不能撞上别人的运行。

这些都不需要 testmon 提供任何 AI 专属的东西。还是同一份记录、同一套选择。只不过，当做改动的那一方改得非常多时，它就更重要了。

为什么 CI 用的是更粗的版本

#

testmon 没有 CI 模式。它在 runner 上和在笔记本上表现一样，而它的作者写道，在 CI runner 之间共享或缓存 .testmondata，效果远不如他们的托管服务 testmon.net。缓存下来的记录还会带着上面说的所有盲区，再加上我的 CI 是用 Django 自带的 runner、四个进程跑这套测试的，所以我没在 CI 里用 testmon。

CI 拿到的，是同一个思路的文件级版本。检查工作流现在先跑一个小 job，对这次推送做 diff，判断它碰到了仓库的哪一半：Python API、移动应用、两者都有，或者都没有。在这之前，每次推送 CI 都会把 Python 和应用两个 job 都跑一遍，只改文档的推送也不例外。现在只改文档的推送什么都不跑，只改应用的推送会跳过 Django 测试套件。我拿五个真实的提交试跑了这个 job：只改文档的那个什么都没跑，只改应用的那个跳过了 Python job，只改后端的那个跳过了应用 job。删减后的示例：

jobs:
  changes:
    runs-on: ubuntu-latest
    outputs:
      python: ${{ steps.diff.outputs.python }}
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - id: diff
        env:
          BEFORE: ${{ github.event.before }}
          HEAD: ${{ github.sha }}
        run: |
          FILES="$(git diff --name-only "$BEFORE" "$HEAD")"
          # Python's inputs include the non-Python files its tests read.
          PY='^(myapp/|myproject/|fixtures/shared\.json$|web/dist/|pyproject\.toml$|uv\.lock$)'
          if printf '%s\n' "$FILES" | grep -qE "$PY"; then
            echo "python=true" >> "$GITHUB_OUTPUT"
          else
            echo "python=false" >> "$GITHUB_OUTPUT"
          fi

  python:
    needs: changes
    if: needs.changes.outputs.python == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - run: uv run python manage.py test --parallel 4 --noinput

真实的版本在没有可比较的范围时，也会全部跑一遍：新分支、强制推送（force push），或者手动运行。

盲区还是同一个，只是换了个形式。testmon 看不到 JSON 文件，路径过滤器也看不到，除非你把它列出来。所以这个模式里明确写出了共享的 fixture、构建出来的 bundle 和生成的网站，还加了一条注释，请改它的人让这份清单保持如实。文件级的版本更粗糙，但它出错时偏向安全的一边：Python 那边只要有任何改动，就跑整个套件。

值得吗？

#

对一个要跑好几分钟的测试套件来说，值得。真正的代价在于它看不到的东西，而那正是包装脚本的用处。即便如此，testmon 该待的地方是笔记本上的开发循环。只要 Python 那边有改动，CI 照样跑整个套件，部署前我信任的是那一次运行。

如果你是来找「怎么在 GitHub Actions 里跑 Docker Compose」的：我这么干了两年，然后停了。现在 CI 把同样的 Postgres 和 Valkey 镜像声明为 services:，直接在 runner 上跑同样的 uv run … 和 npm run …；Compose 回归成开发者本地跑的东西。下面是原因，连同文件。

2024 年我写过一篇用 Docker Compose 做 CI/CD，别把逻辑写进平台专属的 YAML，意思是构建逻辑放进 Compose，CI 工具只负责调用它。两年后，我把自己真正用来发布的仓库全部翻了一遍。有工作流的仓库一共四个，提交者都只有我一个人，而这些工作流里，已经没有一个在调用 docker compose 了。原则留下来了，做法没有。下面是取而代之的东西：删减过的示例文件、GitHub 记录下的每一步耗时，以及那些没有 CI/CD 示意图期望的那么自动化的部分。

我跑的所有流水线，一张表

#

用教科书的话说，两个 Hugo 网站是持续部署；而那个应用（我做的一个集市兼社区应用）是持续集成加上一条命令就能完成的发布，也就是持续交付：检查会告诉我哪里不对，但不会拦着我部署。这是有意为之。一次 OTA 更新会送到所有装着目标二进制版本的手机上，所以发布它应该是一个决定，而不是合并的副作用；而 API 是数据库迁移运行的地方。我另外两个 Django 应用，压根没有工作流。

CI 这一半：一个工作流，两个 job

#

这个应用的 CI 只有一个文件，.github/workflows/checks.yml。10 月 11 日之前，连它都没有。下面是删减后的示例，看个大致样子：

# Lint, types and tests on every push and pull request to main.
# Nothing here deploys.
name: Checks

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

concurrency:
  group: checks-${{ github.ref }}
  cancel-in-progress: true

jobs:
  python:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    services:
      postgres:
        image: postgres:17
        env:
          POSTGRES_USER: myapp
          POSTGRES_PASSWORD: myapp
          POSTGRES_DB: myapp
        ports: ["5432:5432"]
        options: >-
          --health-cmd "pg_isready -U myapp"
          --health-interval 5s --health-timeout 5s --health-retries 20
      valkey:
        image: valkey/valkey:8-alpine
        ports: ["6379:6379"]
    env:
      DEBUG: "True"
      DATABASE_URL: postgresql://myapp:myapp@localhost:5432/myapp
      REDIS_URL: redis://localhost:6379
      PYTHON_JIT: "0"   # match production
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10
        with:
          enable-cache: true
          prune-cache: true
      - run: uv sync --locked
      - run: uv run ruff check .
      - run: uv run mypy myapp/
      - run: uv run python manage.py test --parallel 4 --noinput

  app:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    defaults:
      run:
        working-directory: frontend
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
          cache-dependency-path: frontend/package-lock.json
      - run: npm ci
      # Expo writes this on `expo start` and it is gitignored,
      # so a fresh checkout doesn't have it.
      - run: printf '/// <reference types="expo/types" />\n' > expo-env.d.ts
      - run: npm run typecheck
      - run: npx jest --ci

两个 job 并行运行。到目前为止成功的 35 次运行里，应用 job 的中位数大约七分钟，Python job 大约十二分半。

services: 这一块，就是 Compose 文件搬去的地方，下一节细说。环境变量只有寥寥几个，外加一个开关；其余的一切，都会回落到开发者 docker compose up 时拿到的开发默认值，所以测试不需要任何密钥。为了确认真是这样，我只用这套环境、别的什么都不带，跑了一部分测试。

CI 用的解释器和我的笔记本、生产镜像是同一个，也就是 uv 自己构建的 Python 3.15.0，因为 uv sync 会读 .python-version，并下载正是那个版本。（我真实的文件里还给 setup-uv 传了一个 python-version-file 输入，其实什么都没做：setup-uv v6 没有这个输入，每次运行都带着一条这样说的警告。写这篇文章时我才发现。）

解释器一致的好处，在工作流上线八天后就显出来了。10 月 19 日我打开了 3.15 的 JIT 编译器，开启后的第一次运行就有一个测试失败：一句再普通不过的 yield from，在每次保存都会经过的代码路径上，抛出了 AttributeError: 'list' object has no attribute 'send'。同一个提交关掉 JIT 就能通过。我的 Mac 是 arm64，从没碰到过它；而 runner 是 x86_64，和生产机器一样。JIT 现在在 CI 和 Dockerfile 里都重新关掉了，这个 bug 从没到过生产环境。这就是 python/cpython#155823，上游在 10 月 13 日、也就是 3.15.0 发布之后修掉了它。

其实第一次运行也失败了，原因更无聊。Expo 在 expo start 时会生成 expo-env.d.ts，而这个文件被 gitignore 了，所以我用过的每个工作副本里都有它，全新的检出里却没有。TypeScript 报了五个本地从没出现过的错误。补上生成这个文件的那一步，就修好了。

concurrency 会在同一分支来了更新的推送时，取消之前的运行；到目前为止被取消的十二次运行，全都是这么结束的。另外还有一个提交前钩子（pre-commit），会跑代码检查，暂存了 Python 或 TypeScript 文件时再跑类型检查，所以大部分错误根本走不到推送那一步。

Docker Compose 文件去哪儿了

#

下面是这个应用的 docker-compose.yml 里 CI 关心的那部分，同样是示例。真实文件里服务更多，环境变量也多得多。

services:
  valkey:
    image: valkey/valkey:8-alpine
    ports:
      - "6379:6379"

  # Host port 55432, not 5432, so it can't collide with a local Postgres.
  postgres:
    image: postgres:17-alpine
    environment:
      - POSTGRES_USER=myapp
      - POSTGRES_PASSWORD=myapp
      - POSTGRES_DB=myapp
    ports:
      - "55432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U myapp -d myapp"]
      interval: 5s
      retries: 10

  api:
    build: .
    command: python manage.py runserver 0.0.0.0:8000
    volumes:
      - .:/app
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://myapp:myapp@postgres:5432/myapp
      - REDIS_URL=redis://valkey:6379
    depends_on:
      postgres:
        condition: service_healthy
      valkey:
        condition: service_started

volumes:
  postgres_data:

把它和 checks.yml 里的 services: 放在一起看，是同样的两个镜像：Postgres 17（这里是 Alpine 版，CI 里是 Debian 版）和 valkey/valkey:8-alpine。现在两者的关系就是这样：Compose 文件是开发者跑的东西；CI 把同样的镜像声明为服务容器，然后直接在 runner 上跑开发者跑的那些命令，uv run … 和 npm run …。

和 2024 年那篇对照，我最在意的部分留了下来：CI 工具依然很薄，检查和部署都是我自己就能跑的命令。没留下来的，是让 CI 去调用 Compose。

这个应用的 CI 根本不构建 Docker 镜像；镜像在部署时由 Fly 的构建机构建一次，CI 只需要回答代码好不好，工具链有缓存的话，这只要六秒的安装。另外，Compose 文件会把工作副本 bind mount 进去、灌入种子数据，这些都不是一次测试运行该做的事。所以 CI 本来还得有一份自己的 Compose 文件，也就是同一组服务的第二份描述，靠手工保持同步。

还有，2024 年那个例子里有个我当时没发现的 bug。docker compose build 只构建镜像，从不运行服务的 command，所以那个文件里的 npm test 在 CI 里一次都没跑过，工作流不管测试过没过都是绿的。

那篇文章最担心的风险，也就是换 CI 供应商，始终没有发生。真正发生的迁移在另一头：这个博客和那个客户的网站换了托管，搬到了 Cloudflare Pages，博客这边只是新写了一个 45 行的工作流，因为构建本来就只是一条命令。至于我当年警告过的三百行工作流？我确实有一个，pyhtml2text 的。它之所以长，是因为 wheel 必须分别在 Linux、macOS 和 Windows 的 runner 上、为多种架构构建，也正因为如此，这是唯一一个平台专属 YAML 才是对的工具的活儿。

缓存：先看每一步的耗时

#

GitHub 记录了每一步的耗时，用 gh api repos/<owner>/<repo>/actions/runs/<run-id>/jobs 就能拿到。下面是这个应用最近一次成功的运行，10 月 20 日：

两个依赖缓存都开着，而且都是便宜的那部分。GitHub 为这个仓库保存的 uv 缓存只有 200 KB 左右，因为 setup-uv 会清掉 uv 重新下载就行的东西；npm 的接近 400 MB。时间花在测试上，而测试已经四路并行了。想让运行更快的话，我会去改测试套件，而不是缓存。

博客的情况正好相反。Hugo 处理过的图片放在被 gitignore 的 resources/_gen 里，所以每台新的 runner 都要把封面、正文图片和占位图全部重新编码一遍。下文的工作流用 actions/cache 把它们恢复回来，键是图片本身的哈希，对不上时退回到最新的旧缓存，因为 Hugo 只处理缺的部分。加缓存之前的最后八次运行，构建这一步要 33 到 76 秒；之后的 26 次是 6 到 20 秒，只有一次例外，94 秒。而且同一个提交还加了占位图和第二种卡片尺寸。

这个应用的镜像在 Fly 的构建机上构建，依赖文件先于代码复制进去，uv 的下载缓存放在 BuildKit 的缓存挂载里（RUN --mount=type=cache,target=/root/.cache/uv）。不过最大的改进并不是缓存。旧的 .dockerignore 是黑名单，漏掉了一个放额外 git worktree 的文件夹，每个 worktree 都带着自己的依赖和构建产物，结果每次部署都有 27.7 万个文件、7.7 GB 被传到构建机。改写成白名单之后，构建上下文大约 40 MB。这种写法的示例：

# Exclude everything, then let back in only what the Dockerfile COPYs.
*

!pyproject.toml
!uv.lock
!manage.py
!myapp
!static

# Rules match the whole relative path and the last match wins,
# so these re-excludes apply inside the allowed directories too.
**/__pycache__/
**/*.pyc
**/.DS_Store
**/*.log

密钥，放在尽量少的地方

#

密钥放在三个地方。GitHub Actions 的密钥用于工作流要做的事，两个 Hugo 仓库各自只有一个，CLOUDFLARE_API_TOKEN。Fly 的密钥是应用运行时的配置，用 flyctl secrets set 设置，从不经过 Actions。最后，我笔记本上被 gitignore 的 .env 里，放着部署脚本清 Cloudflare 缓存用的令牌。

PyPI 完全不需要密钥。pyhtml2text 用的是可信发布（trusted publishing）：PyPI 接受 GitHub 签发给工作流的短期 OIDC 令牌，所以发布 job 只申请 id-token: write，仓库的密钥页面是空的。没有可泄露的，也没有要轮换的。

令牌只给它需要的权限。这个应用在 GitHub 上的 Fly 令牌，服务于一个只列出机器的定时检查，所以是用 fly tokens create readonly 创建的。Pages 部署只申请 contents: read 和 deployments: write，别无其他。

输入一律经过 env:，绝不直接塞进脚本。OTA 工作流接收自由填写的发布说明。如果在 run: 里写成 ${{ inputs.notes }}，文本会在 bash 读取之前原样贴进脚本，于是一条带引号和分号的说明就成了代码。作为环境变量传进去，它就始终只是数据。这种写法的示例：

      - name: Publish
        env:
          OTA_API_TOKEN: ${{ secrets.OTA_API_TOKEN }}
          INPUT_PLATFORM: ${{ inputs.platform }}
          INPUT_ROLLOUT: ${{ inputs.rollout }}
          INPUT_NOTES: ${{ inputs.notes }}
        run: |
          args=("$INPUT_PLATFORM")
          [ -n "$INPUT_ROLLOUT" ] && args+=(--rollout "$INPUT_ROLLOUT")
          [ -n "$INPUT_NOTES" ] && args+=(--notes "$INPUT_NOTES")
          ./scripts/publish-ota.sh "${args[@]}"

有些密钥干脆不放在 GitHub 上。有一份定时报告需要一个对应用登录后端有管理员权限的密钥，所以它从定时工作流搬到了我 Mac 上的一个定时任务。工作流仍然留着作为手动备用，只是会略过需要那个密钥的部分。

部署：每次推送、靠脚本、按 tag

#

Hugo 网站每次推送都部署

#

这是博客工作流的示例版本，省掉了第一次运行时创建 Pages 项目的那一步：

name: Deploy to Cloudflare Pages

on:
  push:
  workflow_dispatch:

env:
  HUGO_VERSION: "0.165.0"
  PAGES_PROJECT: my-site

concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      deployments: write
    steps:
      - uses: actions/checkout@v7
        with:
          submodules: true

      - uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: ${{ env.HUGO_VERSION }}
          extended: true

      # Processed images are gitignored; restore them so Hugo only
      # re-encodes what is new. An older cache still helps.
      - uses: actions/cache@v6
        with:
          path: resources/_gen
          key: hugo-resources-${{ hashFiles('content/**/*.jpg', 'content/**/*.png', 'assets/img/**') }}
          restore-keys: |
            hugo-resources-

      # A multilingual site has no root 404.html; without one, Pages
      # answers unknown paths with index.html and a 200.
      - name: Build
        run: |
          hugo --gc
          cp public/en/404.html public/404.html

      # ...

      - name: Deploy
        uses: cloudflare/wrangler-action@v4
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy public --project-name=${{ env.PAGES_PROJECT }} --branch=${{ github.ref_name }}

--branch=${{ github.ref_name }} 让 main 成为生产，其他每个分支都得到预览 URL。那个客户网站的工作流和它是同一个结构，只是在构建前多了一行 rm -rf public，因为那边的 public/ 是提交进仓库的，不这样做的话，已删除的页面会一直留在上传内容里。

Hugo 的版本只在这里固定，别处都不固定。10 月份一次包管理器升级把我笔记本上的 Hugo 升到了 0.168，比主题支持的最新版本还高一个。部署一直停在 0.165，毫无察觉。

而构建本身就是测试。9 月 14 日，某个分支的预览部署连续失败了三次：那个分支上的一篇文章，用 Hugo 的 ref 链接到了一篇还是草稿的文章。CI 和生产一样，构建时不包含草稿，所以这个链接什么都指不到，Hugo 以 REF_NOT_FOUND 停了下来。在此期间，main 照常部署。

应用的 API 靠脚本部署

#

部署脚本的核心部分，示例如下：

IMAGE_LABEL="deploy-$(git rev-parse --short HEAD)-$(date +%Y%m%d%H%M%S)"

# Build first, then wake a spare machine, then roll out exactly that image.
flyctl deploy --config fly.toml --build-only --push --image-label "$IMAGE_LABEL"
curl -fsS --retry 5 https://myapp.fly.dev/health > /dev/null
flyctl deploy --config fly.toml --image "registry.fly.io/myapp:$IMAGE_LABEL"

以及 fly.toml 里对应的几行：

[deploy]
  # max_unavailable only counts machines that are running,
  # which is why the script wakes one first.
  strategy = "rolling"
  max_unavailable = 1

镜像只构建一次，以提交和时间组成的标签推到 Fly 的镜像仓库，再按这个标签部署，所以滚动上线的正是构建出来的那个东西。

让它做到零停机的，是先唤醒一台备用机器。max_unavailable = 1 只计算正在运行的机器，而这个应用空闲时一台运行中的机器都不留（挂起的机器大约一秒就能恢复）。所以以前那台唯一醒着的机器，会和睡着的机器在同一批里被替换掉，身后没有一台热着的机器。9 月 28 日，我用探针持续请求源站：直接 flyctl deploy 时出现了 7 次超时和一段 7.3 秒的空白；而用脚本部署时，先构建、在滚动开始前就有一台机器醒着，2,514 个请求一个都没失败。

脚本的其余部分，会在错误告警所在的团队聊天频道里留下部署标记，这样一阵错误涌来时，可以对照刚刚改了什么；然后清掉 Cloudflare 缓存，再把机器预热一遍。Web 前端完全不经过镜像，这部分我写在前后端分开部署：不重新部署 API 也能发布 Web 前端里。

迁移不是流水线的一个步骤。Fly 的 release_command 在我这里会卡住，所以由第一台用新镜像启动的机器拿锁并执行迁移，其他机器等着。因此每次迁移都必须兼容仍在运行的代码：一次部署里加列，下一次部署不再使用它，第三次再删掉。

这个脚本里没有哪一处非得在我的笔记本上不可，但有几个只在本地的文件把它留在了那里：Cloudflare 凭据，以及一份最后部署了什么的记录，全新的 runner 上不会有它们。它还会把未提交的改动也一起部署，并在聊天频道里说明这一点，而 Web 的发布脚本会拒绝不干净的工作区。

在每个分支一个预览环境里我写过，这些事手工来做，只有你一个人时没问题；从第二个开发者开始，它就必须因为 git 里发生了什么而发生。这个应用现在还是我一个开发者。那篇文章里的分支环境工作流，还留在我当初搭建它们的那个分支上。

OTA 工作流只能手动运行，因为发布应该是一个决定，也因为在有部分发布（partial rollout）进行中时，更新服务会拒绝新的发布，换成推送触发的话，每次金丝雀发布都会撞上。这个工作流一次都没跑过。到目前为止，每一次 OTA 更新都是从我的笔记本上，通过工作流调用的同一个脚本发出去的。保持工作流轻薄的理由，一句话就是这个：不管发布从哪里开始，跑的都是同一个脚本。

pyhtml2text 按 tag 发布

#

发布 job 如下，包名换成了通用的名字：

  release:
    runs-on: ubuntu-latest
    if: ${{ startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch' }}
    needs: [linux, macos, windows, sdist]
    environment:
      name: pypi
      url: https://pypi.org/p/mypackage
    permissions:
      id-token: write       # trusted publishing and signing
      contents: write
      attestations: write
    steps:
      - uses: actions/download-artifact@v8
      - uses: actions/attest@v4
        with:
          subject-path: 'wheels-*/*'
      - uses: astral-sh/setup-uv@v10
        if: ${{ startsWith(github.ref, 'refs/tags/') }}
        with:
          prune-cache: true
      - name: Publish to PyPI
        if: ${{ startsWith(github.ref, 'refs/tags/') }}
        run: uv publish --trusted-publishing always 'wheels-*/*'

发布 job 会等所有构建 job 完成，只有 tag 才会真正发布；手动运行会构建并生成证明（attestation），但什么都不上传。actions/attest 记录每个 wheel 是由哪个工作流构建的，uv publish --trusted-publishing always 用 OIDC 令牌而不是密码来上传。这个包本身，我写在一个被关闭的 Pull Request、一个 fork 和一个 PyPI 包里。

定时工作流只是尽力而为

#

这个应用有一个定时工作流，检查 Fly 启动的机器有没有超过基线，不检查的话，第一次发现会是在账单上。它靠故意失败来报警，因为定时运行失败时 GitHub 会给仓库所有者发邮件。

它设的是 cron: '*/15 * * * *'，一天 96 次。可过去两周里，它每天只跑了三到八次，两次运行之间间隔的中位数大约三小时四十分。GitHub 文档给出的唯一解释是负载：Actions 忙的时候，定时运行可能会延迟，忙到一定程度还可能被丢掉。对持续的扩容来说，几个小时足够了。对于必须在几分钟内报警的东西，GitHub 的 cron 不是监控。

我会问一条流水线的几个问题

#

不管你是在搭新的，还是在审视现有的：

1. 如果 GitHub Actions 停摆一整天，你还能发布吗？不能的话，你的发布逻辑就在 YAML 里，2024 年那篇依然适用。
2. CI 跑的解释器、CPU 架构和数据库大版本，和生产一致吗？我的 CI 能抓到一个编译器 bug，只是因为 runner 和生产都是 x86_64，而我的笔记本不是。
3. 全新的检出能通过吗？通不过的话，通常是那些自动生成、又被 gitignore 的文件在作怪。
4. 一次运行的时间到底花在哪儿？加缓存之前，先看每一步的耗时。
5. 每个密钥放在几个地方？它真的需要放在 GitHub 上吗？

pip install pyhtml2text

from pyhtml2text import html2markdown

html = """<h2>Before you start</h2>
<p>Read the <a href="setup.html">setup guide</a> and <b>back up</b> your data.</p>
<img src="https://jared.lynskey.co.nz/img/diagram.png" alt="How it fits together">
<table><tr><th>Plan</th><th>Price</th></tr><tr><td>Basic</td><td>Free</td></tr></table>"""

print(html2markdown(html, base_url="https://example.com/docs/intro.html"))

## Before you start

Read the [setup guide](https://example.com/docs/setup.html) and **back up** your data.

![How it fits together](https://example.com/img/diagram.png)

| Plan | Price |
| --- | --- |
| Basic | Free |

它最初是给 rust-html2text 提的一个 pull request。维护者因为它是用 LLM 写的而关闭了它，所以 pyhtml2text 改为基于一个 fork 运行。这篇文章讲事情的经过、fork 和这个包里有什么，以及我怎么确认生成的 Markdown 是对的。

为什么需要它

#

我做的一个集市兼社区应用，收到 Accept: text/markdown 的请求时会返回 Markdown 而不是 HTML，给那些不想在导航栏和页脚里翻找内容的 AI agent 和 LLM 客户端用。边缘那一侧的做法我在关于爬虫和缓存的文章里写过。由应用数据生成的页面，HTML 只是一个空的 JavaScript 外壳，所以直接生成 Markdown。其余都是静态 HTML（营销页、法律条款和博客），这部分要经过转换。

转换的麻烦在于链接。静态站点的页面里到处都是 /en/posts/... 和 ../setup/ 这样的链接。在浏览器里没问题，因为浏览器知道它们来自哪个页面。读 Markdown 的 agent 没有这个上下文，所以它没法打开 /login，它需要的是 https://example.com/login。

纯 Python 的 html2text 有一个 baseurl 选项专门做这件事，我一开始用的就是它。但它很慢，生成的 Markdown 也有一些问题，后面会讲到。rust-html2text 速度快、测试充分，但它没有办法解析链接。

先问上游

#

8 月 29 日，我提了 issue #287，写明了使用场景和我想要的行为：按 RFC 3986 解析，绝对 URL 以及 mailto:、data: 和 #fragment 链接保持不变。几分钟后，我提了 pull request #288。它加了一个 Config::base_url(...) 选项，我在 issue 里说明这只是一个起点，如果维护者想换一种做法，我完全理解。

10 月 11 日，维护者关闭了这个 PR：

Thanks for the contribution, but I’m unable to accept this as it appears to be LLM generated. (I have now added a brief policy to the README.md - it wasn’t previously stated)

（大意：感谢贡献，但我无法接受，因为它看起来是 LLM 生成的。我已经在 README.md 里加了一条简短的政策，之前没有写明。）

并在 issue 里回复：

Hi - this is a reasonable feature request, thanks! I have closed the PR as it appears to be LLM-written which I can’t accept, but thanks for the attempt.

A short HTML sample and expected output would definitely help get the feature implemented!

（大意：这是个合理的功能请求，谢谢！PR 看起来是 LLM 写的，我无法接受，所以关闭了，但感谢你的尝试。如果能提供一小段 HTML 示例和期望的输出，肯定有助于实现这个功能！）

现在 README 里有这样一条政策：

At this time, this project is not able to accept code contributions produced with generative AI/LLMs due to the uncertain copyright status.

（大意：由于版权状态尚不明确，本项目目前无法接受由生成式 AI/LLM 产出的代码贡献。）

维护者的判断没错：那段代码确实是我用 AI 编程助手写的。我也不觉得这条政策不合理。LLM 输出的版权归属还没有定论，而把它合进一个许多项目都依赖的 MIT crate，风险是由维护者来承担的。这是对方的项目，而且回复也很客气。那个功能请求现在仍然开着。

不过我还是需要这个功能，而跟维护者争论对方自己定的贡献政策，并不是拿到它的好办法。所以我把改动留在一个 fork 上，在它之上构建了 Python 包，两者都清楚写明了自己不是上游。

fork 里有什么

#

fork 是我那个 rust-html2text fork 里的 pyhtml2text-perf 分支。为了能干净地 rebase 到上游，我只保留了三个小提交。最主要的是 PR 里那个 Config::base_url 选项：按 RFC 3986 §5.3 解析相对链接，不传 base URL 时输出完全不变。另一个提交让 crate 不再每次调用都重建样式规则，短片段的耗时从 7.3 µs 降到 5.6 µs。大页面上这点差别可以忽略，但调用几千次就积少成多了。第三个只是把下文 Markdown 转换器需要的部分从 crate 里导出来。

Python 包

#

pyhtml2text 用 PyO3 和 maturin 构建，提供两个函数：

from pyhtml2text import html2text, html2markdown

html2text(html, width=80, *, base_url=None, decorate=True, link_footnotes=True,
          table_borders=True, wrap_links=True, max_wrap_width=None, raw=False)

html2markdown(html, *, base_url=None)

html2text 就是 rust-html2text 的纯文本渲染器，它是为终端和电子邮件的 text/plain 部分设计的：

print(html2text('<p>Please <a href="https://jared.lynskey.co.nz/login">sign in</a> first.</p>',
                base_url="https://example.com/docs/page.html"))

Please [sign in][1] first.

[1]: https://example.com/login

关于这些绑定，有几点可能不那么显而易见：

• 两个函数都接受 str 或 UTF-8 的 bytes，所以可以直接传 response.content，不用先解码。输入是借用的，不会复制。
• 转换期间会释放 GIL。 从头到尾都是纯 Rust，所以多线程能用满多个核。模块还声明了自己不需要 GIL，因此在 free-threaded 的 Python 3.14t 上，导入它时不会把 GIL 重新打开。
• panic 会变成 ValueError。 PyO3 默认抛出的是 PanicException，而 except Exception 捕获不到它。一个以为自己已经处理好转换错误的 web worker 会因此崩掉，所以绑定层把它捕获下来，重新抛成 ValueError。
• 一共有 30 个 wheel： CPython 3.10 及以上的 abi3 wheel，加上 free-threaded 3.14t 的 wheel，覆盖 Linux（glibc 和 musl）、macOS 和 Windows 上 maturin 的 CI 能构建的所有架构。所以安装时谁都不需要 Rust 工具链。

让它变快

#

0.2.0 在真实页面上比 0.1.0 快 1.5 到 1.7 倍，短片段上快一倍，输出逐字节一致。大部分提升来自配置文件引导优化（PGO）：CI 先构建一个插桩版 wheel，在一组由文档页面和 RFC 组成的训练集上跑一遍，再用得到的 profile 构建正式的 wheel。在训练集以外的页面上大约快 25%，只在 CI 能原生运行插桩构建的平台上启用。剩下的来自换用 mimalloc 分配器（大量小块分配时它比系统分配器强得多），以及 fork 里那个样式规则的改动。

为了确认提速没有改变任何输出，我把一批真实页面用每一组选项都转换一遍，记录输出的哈希，还加上了空输入、极深嵌套之类的边界情况。每个改动都必须让所有哈希保持不变。

下面是在 Apple Silicon Mac 上转 Markdown 的中位耗时：

转纯文本：

深层嵌套的 HTML，以及给 html5ever 打的补丁

#

没人会手写 40,000 层嵌套的列表。但如果你要转换不是自己写的页面，迟早会碰到某个恶意的或者坏掉的页面给你来这么一下。用原版解析器，解析 40,000 层嵌套的 <ul><li> 要 6 秒，也就是一个 worker 被一个请求卡住 6 秒。

原因在 rust-html2text 使用的 HTML5 解析器 html5ever。大多数块级开始标签都要检查是否有一个打开的 <p> 元素处于 “button scope” 之内，而 html5ever 每次都要把打开元素的栈从头到尾走一遍。嵌套越深，每个标签花的时间越长，总时间随深度的平方增长。

这个包附带了打过一个补丁的 html5ever 0.39.0。补丁让这个答案在元素打开和关闭时随时更新，所以检查的耗时不再取决于嵌套深度。同一个文档现在 0.14 秒就解析完了。为了确保补丁没有改变别的行为，我在 html5lib 的全部树构建测试、约 20 个真实页面和 30 万个随机标签汤文档上，对比了原版和补丁版解析器生成的 DOM，结果完全一致。

出于同样的原因，Markdown 转换器也设了上限：任何输入都不会撑爆线程栈；引用块和列表超过 32 层就不再缩进，免得输出按平方膨胀；展开后网格超过 100,000 个单元格的表格，只输出单元格内容。

html2markdown

#

0.3.0 版加入了 html2markdown，这个包的大部分工作都花在它上面。rust-html2text 的渲染器输出的文本看起来像 Markdown，但它是按终端宽度折行的，并不打算被解析。所以 html2markdown 只借用它的解析器，输出则自己来写：CommonMark，外加 GitHub 风格的管道表格和 ~~删除线~~：

• # 标题、- 列表、_强调_ 和 **加粗**。
• 行内链接和图片，给了 base_url 时转成绝对地址。如果一个链接里只有图标，就用它的 aria-label 或 title 作为链接文字。
• 围栏代码块，页面标明了语言时（class="language-python"）会带上语言标记。
• 管道表格。跨行或跨列的单元格变成空单元格，没有表头行的表格会补一个空表头，用来做页面布局的表格则写成普通段落。
• 不折行。隐藏内容（hidden、aria-hidden、display: none）、脚本、样式和表单控件都会被去掉。

只转义需要转义的

#

有些 HTML 转 Markdown 的工具会把所有可能是 Markdown 语法的字符都转义掉。比如 markdownify 默认会转义每一个 _ 和 *。这样的输出是正确的，但满篇都是 snake\_case 和 5 \* 3，人读起来费劲，对模型来说也是浪费 token。pyhtml2text 只在 CommonMark 解析器会把某个字符当成语法的地方才转义它：

html2markdown('<p>Use <code>snake_case</code>, 5 * 3, $5 and '
              '<a href="../setup.html">setup</a></p>',
              base_url="https://example.com/docs/intro.html")

Use `snake_case`, 5 * 3, $5 and [setup](https://example.com/setup.html)

韩语助词前的加粗

#

这个问题来自我那个应用自己的页面。韩语的助词紧跟在名词后面，中间没有空格，所以一个带括号的加粗词语是这样的：

<p><b>타이타닉(Titanic)</b>의 감독</p>

最直接的 Markdown 写法是 **타이타닉(Titanic)**의，markdownify 输出的就是这个，但它不起作用。CommonMark 的 flanking 规则规定，** 跟在标点后面时，只有后面紧接空格或另一个标点才能闭合，而 의 是一个字母，所以这些星号会原样留在文本里。纯 Python 的 html2text 的办法是加一个空格：

**타이타닉(Titanic)** 의 감독

这样能渲染出加粗，但改动了韩语原文。助词变成了一个单独的词，在韩语里这是拼写错误。pyhtml2text 的做法是把标点移到标记外面：

**타이타닉(Titanic**)의 감독

括号不再是粗体，但强调依然能正确解析，原文的每个字符也都保留了下来。日语和中文也是同样的道理：中文词与词之间没有空格，一段以括号结尾的加粗文字后面如果直接跟着"的"之类的字，也会碰到同样的问题。任何不在后续文字前加空格的语言都一样。

读回来检查输出

#

我不会因为一个转换器的单元测试都通过了就相信它，因为 Markdown 输出里的 bug 往往藏在没人想到要写测试的组合里。所以输出要读回来检查。

转换时，每个段落都会按 CommonMark 重新解析一次，确认强调读回来符合预期。如果不符合，就换另一种强调写法重写（用 * 代替 _，或者反过来）；两种都不行，就保留文字、链接和代码，去掉格式，保证一个字都不丢。测试套件则用另一个 Markdown 解析器做往返检查，把每一个可见的词、链接地址和图片地址同原始 HTML 逐一比较。因为没转义而被语法吞掉的文字、没解析出来的链接、多出来的 *，都会作为差异显示出来。它在真实页面和成千上万个随机文档上运行，出错时还会把文档缩减成最小的复现用例。

上线

#

0.3.0 发布当天，我那个应用的 Markdown 内容协商就从纯 Python 的 html2text 换成了 pyhtml2text。在其中一个指南页面上，转换时间从 4.2 ms 降到了 0.36 ms，快了大约 12 倍。链接都是绝对地址，表格是真正的管道表格，韩语的加粗也不会再把助词分开。abi3 wheel 本来就覆盖了 x86_64 和 arm64 上的 Python 3.14，所以容器镜像不需要加任何新东西就能装上它。

致谢，以及在哪里报告 bug

#

纯文本渲染来自 Chris Emerson 的 rust-html2text，采用 MIT 许可证。pyhtml2text 在此之上加了它的一个 fork、一份打过补丁的 html5ever（MIT/Apache-2.0）以及 Markdown 转换器。这个包与这两个项目都没有关联，也没有得到它们的认可，所以有问题请报到 pyhtml2text 的 issue 页面，不要报到上游。这些代码里的 bug 由我来修，上游维护者不应该收到关于他们拒绝接受的代码的报告。

如果你在用 Python 转换 HTML，特别是要给模型读的，不妨试试：

pip install pyhtml2text

源码在 GitHub 上，changelog 里列出了 0.1.0 到 0.3.0 的所有改动。

我目前以独立开发者的身份运营着两个产品：一个是面向上门报价的手艺人的现场估价应用，另一个是带有信息发布和实时消息的集市兼社区应用。

产品完全不同，用户完全不同，但技术栈几乎一模一样——而且两者都只跑在 Fly.io 最便宜的档位 shared-cpu-1x 机器上。这个约束是刻意为之的。与其按峰值负载来配置服务器，我选择把一台小机器的性能榨到极限，精确测出它在哪里崩溃，然后让 Fly 的自动扩缩容器围绕这个实测极限来增减机器。这篇文章讲的就是让这一切成为可能的优化、阈值背后的压测数据，以及 Fly.io 上扩容和缩容到底是怎么运作的。

理念：先测准一台机器，再做乘法

#

两个应用的扩缩容策略都是同样的三步：

1. 把一台小机器在合理范围内做到尽可能快。
2. 压测到它崩溃为止，记下延迟塌陷时的并发水平。
3. 配置 Fly 的自动扩缩容器，在临界点之前启动第二台机器，并在流量回落时停掉空闲机器。

这样容量就随机器数量近似线性增长，而基线成本是每个应用一台小虚拟机。下面的所有内容，都是为这三步中的某一步服务的。

让一台小机器变快

#

Granian：API 走 WSGI，WebSocket 走 uvloop ASGI

#

两个后端都是 Django 6 + Django REST Framework。API 由基于 Rust 的服务器 Granian 提供服务，但跑的是 带阻塞线程池的 WSGI，而不是 ASGI：

granian --interface wsgi myapp.wsgi:application \
    --workers 1 --blocking-threads 16 \
    --workers-max-rss 1400 \
    --workers-kill-timeout 15 --respawn-failed-workers

我最初用的是 --interface asgi --loop uvloop，事后看是选错了。这些应用里的每个 HTTP 视图都是同步（sync）的，而 Django 的 ASGI 处理器会以 thread_sensitive 方式跑同步视图——每个 worker（工作进程）一次只跑一个。于是 ASGI 把每个 worker 的并发请求实质压到约 1 个，却还把整套 asyncio/uvloop/Channels 栈白白装进内存。带 --blocking-threads 的 WSGI 则把这些同步视图放进一个真正的线程池：1 个 worker × 16 个线程 = 16 个并发的 I/O 密集型请求（数据库读取、S3 预签名），而常驻内存比异步栈更低。

为什么只用一个 worker？因为这台 VM 是 shared-cpu-1x——只有一个核。第二个 worker 在单核上没法并行跑 Python（GIL + 单核），却要白白多占一整个常驻的 Django 进程；Granian 会直接就此发出警告。一个 worker 配 16 个线程，就是单 vCPU 机器在 I/O 密集型工作上诚实的上限。--workers-max-rss 1400 会在 worker 越过内存上限时重启它，于是失控的 PDF 或图片任务会被回收，而不是把机器一路拖向 OOM。

WebSocket 被拆到了它自己的 Granian 进程里——一个用 uvloop 和 --ws 的 ASGI 应用，为长连接跑 1 个 worker。同步 API 完全不需要 ASGI 路径：当某个视图想往 socket 推送时，它会经由 Redis 调用 async_to_sync(channel_layer.group_send)，消息照样会跨进程送到 WebSocket 应用。两台服务器，各自跑自己真正擅长的接口。本地 Docker 也跑同样的 WSGI 线程池，因此测试时我的笔记本约等于一台生产机器。

热路径交给 Rust

#

只要 Python 热路径上存在 Rust 实现的替代品，我就用它：

• orjson（通过 drf-orjson-renderer）——所有 API 响应都经由 Rust 序列化，而不是标准库的 JSON 编码器。
• blurhash-rs——在上传时计算图片占位符。
• uuid-utils——Rust 实现的 UUID 生成。
• psycopg 3 (binary)——C 加速的 Postgres 驱动。

这些都不改变架构，只是抬高了一颗 vCPU 在需要第二台机器之前所能承受的上限。

消灭隐藏的延迟税

#

两个代码库里最大的一次性能提升不是算法，而是连接复用。在 Granian 的线程池下，每个新线程都会重新构建一个 boto3 的 S3 客户端，而每个返回照片或 PDF 的接口都在支付这笔开销。我写了一个小小的自定义存储类，改为按进程缓存客户端之后：

新线程上生成签名 URL 的耗时从 约 150ms 降到约 1ms。

同样的教训也适用于数据库：Fly 的 Postgres 位于 PgBouncer 之后，所以应用设置 conn_max_age=0，把连接复用交给连接池，并用 5 秒的 connect_timeout 快速失败，避免 worker 挂在失效的 SSL 连接上。

把缓存放在真正的瓶颈前面

#

压测社区市集时发现了一个值得记住的事实：天花板是 Postgres 连接数，而不是 CPU。浏览流量绝大多数是匿名的、用户之间完全相同，而在高负载下，这些相同的列表查询会在 CPU 闲置的同时把连接池打满。

解决办法是给匿名列表页加一层 Redis 缓存，用按命名空间的版本计数器做失效——一次写操作只需把一个计数器加一（O(1)，无需管理任何键），该资源的所有缓存页面立即失效。再用一个短 TTL 兜底。让浏览页面直接从 Redis 出去，真正的瓶颈就消失了，小机器可以把连接留给已登录的流量。

不要消息代理的后台任务

#

两个应用都用 django-tasks-db——Django 的数据库后端任务框架——而不是 Celery。一个独立的 db_worker 进程轮询数据库来处理任务：图片处理、PDF 生成、机器翻译、提醒推送。没有消息代理，没有需要额外估算容量和监控的服务，API 进程也永远不会被重活阻塞。这个 worker 甚至绕过 PgBouncer 直连 Postgres，因为长时间运行的任务和事务级连接池合不来。

内存：jemalloc 和交换空间缓冲

#

图片和 PDF 处理造成的内存尖峰，是按稳态估算内存时无法预测的。两个便宜的缓解手段：在 Docker 镜像里预加载 jemalloc 来减少内存碎片，以及给每台机器都配交换空间（API 机器 2GB，WebSocket 机器 1GB），这样尖峰来临时进程会把内存换出到磁盘，而不是被 OOM 杀掉。交换空间不是性能特性——它是一份保险，让我能把内存配置一直保持在小规格。

Django 压力测试：找到拐点

#

阈值只有在被实测过之后才站得住脚。每个项目都有自己的压测工具：

• 估价应用有一个小的 Python 压测脚本，扫描各个并发级别并报告 RPS、p50/p95/p99 和错误率；它跑在预先生成的几百条样例数据上，让列表接口在接近真实的数据量下被查询。
• 社区市集用 Locust 以 30 秒为步长从 50 爬升到 500 用户来寻找饱和点，接口权重按真实的浏览为主的流量设定；另有一套更小的独立测试，以 p95 < 2 秒为阈值，对生产环境从 5 爬升到 50 个虚拟用户。

估价应用扫描的代表性数据（1 个 Granian worker × 16 个阻塞线程，开发机上的 Docker）：

而决定其他一切的那个数字，来自在单台 shared-cpu-1x 机器上对社区市集的压测。在旧的 ASGI 构建里，这曾是一堵硬墙：同步视图被实质串行化到大约3 个可用槽位，于是 p95 在约 5 个并发请求以内保持在 300ms 以下，随后当一切都排在 thread_sensitive 锁后面时，超过约 8–10 个并发就塌陷。把拐点往外推的，正是把 API 迁到 WSGI 线程池这件事——每台机器的真实并发槽位从约 3 个变成了 16 个，而这个新的上限就是整个自动扩缩容配置的依据。

Fly.io 上的扩缩容是怎么运作的

#

Fly 的模型很简单：你的应用是代理后面的一组相同机器，代理统计每台机器的负载。你只需要声明两个数字：

[http_service.concurrency]
  type = 'requests'
  soft_limit = 12   # 超过就启动另一台机器
  hard_limit = 24   # 超过就直接卸载负载而不是排队

auto_stop_machines = 'stop'
auto_start_machines = true
min_machines_running = 1

**扩容：**当一台机器上的在途（in-flight）请求超过软上限（soft limit），代理会启动一台停止中的机器，并把新流量路由过去。WSGI 线程池让每台机器有 16 个真实并发槽位，所以软上限设为 12——约为池子的 75%，于是第二台机器会在线程还有余量时启动，而不是等用户已经在承受数秒延迟之后。硬上限 24（池子的 1.5 倍）是熔断器：短促的突发会在线程上排队，超过它，代理宁可卸载负载，也不让一台机器被压垮。（旧的 ASGI 构建只有约 3 个真实槽位，用的是 8/20；正是把池子拓宽，才让这两个数字都能往上调。）

**缩容：**流量回落时，Fly 自动停掉空闲机器，最低降到 min_machines_running = 1。停止的机器不产生计算费用，只收 rootfs 存储费，所以每个应用的基线成本就是字面意义上的一台小虚拟机，而突发容量随时待命。

我原本在这里写着，停止的机器"冷启动不到一秒"。这是错的，而且错得很贵。当我不再假设、真正去测量之后，一次冷启动要 25 到 33 秒，落到一台还在启动的机器上的请求，就得把这段时间整个等完。我一开始把 CDN 面板上 22% 的失败率归咎于这些冷启动，当时健康检查一直是绿的。后来才发现，那个数字是 CDN 自己的 Early Hints 探测请求在源站失败造成的，真实客户端一个 504 都没收到。不过冷启动本身确实存在。

解法不在上面的伸缩数字里，那些数字没问题。解法在于机器启动过程中做了什么，以及让 Fly 挂起机器而不是停止它们——那样唤醒就变成大约 3 秒的内存恢复。我单独写了一篇：缩容到零，于是每次重启都是一次 30 秒的故障 讲了诊断过程和该改什么。如果你在 Fly 上跑着任何用了 auto_stop_machines 的东西，先读那篇，再来相信这一段。

一个微妙之处：并发类型是 requests 而不是 connections。现代客户端会一直保持 keep-alive 连接，所以按连接数统计时数字在真实负载下几乎不动，自动扩缩容永远不会触发。统计在途请求，才能追踪真实的工作量。

WebSocket 在另一条轴上扩缩

#

社区市集把 WebSocket 服务器拆成了第二个 Fly 应用，与 API 共享同一个 Docker 镜像。API 应用用 WSGI 跑 1 个 worker × 16 个阻塞线程，按请求计数（软上限 12）；WebSocket 应用在一台 512MB 的机器上用 ASGI 配 uvloop 跑 1 个 worker，按连接计数：

[http_service.concurrency]
  type = 'connections'
  soft_limit = 1500
  hard_limit = 2000

一条长连接维持起来几乎零成本，却会占用一个槽位好几个小时；而一个 HTTP 请求只占用槽位几毫秒——同一个扩缩容信号无法同时服务两者。拆开之后，每个机群都按对自己诚实的指标扩缩，而空闲的 WebSocket 容量只花 512MB，不是 2GB。在 Channels 这一侧，Redis 层以 capacity: 1500、消息 60 秒过期运行，并每 30 秒发送 socket keepalive——因为 Fly 的 Redis 代理会把 Channels 赖以工作的长时间 BRPOP 连接当作空闲连接掐掉。

把计算卸载到边缘和客户端

#

最便宜的服务器工作，是服务器根本不用做的工作：

• 静态文件和媒体放在 Fly 的 S3 兼容对象存储上，私有媒体通过签名 URL 走 CDN 分发——图片的每一个字节都不经过 Django 机器。
• **AI 推理跑在用户的手机上。**两个应用都内嵌了一个小型本地 LLM（量化的 4B 模型，约 2.7GB），直接在设备上运行。服务端推理成本为零，而且离线也能用。
• 离线优先的移动端（设备上的 SQLite 加带重试的同步队列）意味着应用会把写操作攒批、容忍信号盲区，而不是每敲一个键就向 API 发一次琐碎请求。

其余的技术栈，简单说

#

认证用托管的身份服务加 WebAuthn 通行密钥（passkey），WebSocket 连接在协议升级完成前就完成认证。生产用 Postgres，开发用 SQLite。后台管理和审计记录用了几个现成的 Django 包。移动端是基于 Expo 的 React Native 和 TypeScript，配 Expo Router 和 Tailwind，OTA 更新由自托管的 Expo Updates 服务器下发，应用内订阅交给一个订阅管理服务。质量关卡：后端 pytest 和 mypy，客户端单元测试和端到端测试。

值得你拿走的东西

#

可迁移的想法不是某个具体的库，而是这个循环本身：把一台便宜机器做到真正的快（Rust 热路径、连接复用、在真正的瓶颈前面加缓存、能卸给 CDN 和客户端的都卸掉）；压测到找出它到底在哪个并发数崩溃；把自动扩缩容的软上限设在那个拐点上，让空闲机器停机，把最小机群保持在 1。两个生产应用、实时功能、AI 助手——而平时的账单，只是这个平台上最便宜的几台虚拟机。

过去几周我在做两个相关的项目。第一个是复现 2024 年 Scientific Reports 上 Lee 等人的论文 “Social signals predict contemporary art prices better than visual features, particularly in emerging markets”，它用 590 位在世艺术家的 34,200 条拍卖记录训练了一个 XGBoost 模型。第二个是搭建一个艺术品平台，核心是一张连接艺术家、拥有者和拍卖记录的知识图谱。说白了，就是你想拿那种模型做点正经事时必须先铺好的数据管道。

两个项目最后绕回的都是同一个问题：一件艺术品能卖多少钱，真的可以预测吗？答案是可以，但靠看作品本身不行。管用的特征几乎全是社会性的。

为什么艺术品难估价

#

动手写代码之前，我花了几天读评估师和拍卖行到底怎么定价。要考虑的因素很多，而且大多没法干净地量化。来源——谁拥有过它、在哪展出过、被哪些图录收录。归属和真伪：经艺术家基金会确认的真品，比只是"传为某人所作"的作品贵好几个数量级。艺术家的声誉，由个展、双年展、博物馆收藏和批评界反响一点点垒起来。再加上品相和修复史、在艺术家作品体系里的稀缺程度，还有媒介——布面油画通常好过纸本，纸本又好过版画。被大博物馆收藏，等于盖上了一枚二级市场信得过的章。时机也算数：五年前的可比案例已经过时了。

拍卖行的专家还会谈"情感价值"：藏家的渴望、竞价大战的氛围、个人的共鸣。这种东西能把落槌价推到任何理性估算之外。你没法直接建模它，但可以借拍卖行的预估价间接捕到它的轮廓。

实务中占主导的估值方法是可比销售分析：找同一位艺术家相似作品的近期拍卖结果，再按差异调整。XGBoost 干的本质上就是这件事，只是规模大得多，用的特征也多到任何人类评估师都没法手工跟踪。

论文的核心论点

#

Lee 等人的论点很反直觉：作品的视觉内容几乎解释不了价格。他们只用视觉特征（颜色、构图、边缘密度、ResNet18 嵌入）的模型，R² 大约 0.055，比直接猜均值强不了多少。

而只用艺术家层面"社会性"特征（职业阶段、展览履历、过往拍卖价格、ArtFacts 排名）的模型能到 R² ≈ 0.73。再把拍卖行的预售估价加进特征，能升到 0.92。

换句话说，作品本身几乎无关紧要。要紧的是谁做的，以及市场对这个人已经说过什么。

论文的第二个论点是，这个差距在新兴市场还会进一步拉大。他们说的新兴市场，指美国、英国、法国、德国这四个既有核心之外的一切。在那些市场里，社会信号更管用，专家预估反而更不准，留给算法预测创造价值的空间也就更大。

复现论文

#

任务本身很直接：以单人开发的 MVP 复现这篇论文。不上生产，没有实时数据管道。忠实的重新实现、原型级的代码，加一份写清结论的报告。

数据

#

论文以补充材料的形式提供了清洗好的 CSV：

全部加起来大约 5 GB，轻松塞进内存。这个规模的数据集，XGBoost 在笔记本 CPU 上五分钟内就能训练完，核心模型根本不需要 GPU。这个体量的表格数据，梯度提升树的训练成本约等于零——要是这几年一直泡在神经网络的世界里，这件事很容易忘。

特征

#

模型用 38 个特征，分三类。

关于艺术家（30 个）：

• 人口属性：年龄、性别、教育程度、是否名校。
• 职业：ArtFacts 排名、个展、群展、双年展参与、获奖。
• 收藏：个人和公共收藏数量。
• 价格历史：艺术家最近 5 次和 10 次销售的均值、中位数、最高、最低。
• 面积调整后的价格历史（每平方英寸价格）。
• 地理：艺术家工作和居住地，编码为按国家的标志位。
• 匹配标志：作品的题材是否与艺术家典型题材一致？销售国家是否一致？

关于市场（8 个）：

• 拍卖行等级（1–4）。
• 当年该国家/地区的价格水平（最低、平均、中位、最高）。

关于作品本身（非视觉）：

• 宽度、高度、平方英寸面积。
• 媒介类别（绘画、版画、摄影、雕塑、其他）。

注意这份清单里缺了什么：任何关于作品实际视觉内容的信息。那部分只在单独的消融实验里出现。

训练/测试拆分

#

按时间拆，不是随机拆。2011 年 5 月之前的全部进训练集（约 80%，约 27,360 条），之后的进测试集（约 20%，约 6,840 条）。随机拆分会通过艺术家的价格历史特征泄漏未来信息：把同一位艺术家的记录随机撒在训练集和测试集里，测试集的行就已经通过滚动窗口"看过"彼此的价格，R² 会被人为抬高。

这种事看穿了觉得理所当然，第一次搭的时候却很容易漏掉。

模型

#

XGBoost 回归，预测 log10(price_usd)。在留出的验证切片上搜索 max_depth 和 learning_rate。两个模型变体：

1. 不用专家预估。 目标 R² ≈ 0.73。
2. 使用专家预估。 目标 R² ≈ 0.92。

“使用预估"的变体把拍卖行预售的低估和高估作为额外特征。这两个数字单独拿出来用，就能达到 R² ≈ 0.90。社会特征叠上去再多 0.02。绝对值不大，但这 0.02 才是模型在专家已知信息之外真正做出的预测贡献。

我瞄准的目标

#

我没打算超过论文。目标是在所有条件下把 R² 控制在他们数值的 ±0.03 之内。头条数字（仅元数据约 0.73，加预估约 0.92）的可复现性应该不错：XGBoost 固定种子后是确定性的，特征定义也清楚。我预计会漂移的地方有两处：视觉特征消融，PCA 维数或图像预处理的小差异都会让结果晃动；还有新兴市场那一刀，只有 4,346 条记录，噪声下限本来就高。

为什么视觉特征几乎没用

#

这是我觉得最有意思的结果。论文的视觉流水线为每张图片提取 8,971 个数字：

• GIST 描述子（960 维）：整体空间布局。
• 方向梯度直方图（HOG）（2,915 维）：边缘结构。
• 颜色直方图（4,096 维）：调色板分解。
• ResNet18 特征（1,000 维）：高层级预训练嵌入。
• 色彩饱和度（1 维）：鲜艳度标量。
• 复杂度（1 维）：边缘密度标量。

全部用 PCA 压缩后喂给 XGBoost，得到 R² ≈ 0.055。只用颜色是 0.056，边缘结构 0.029，神经网络嵌入 0.009，基本等于零。

干净利落的解释是：拍卖价格是在艺术家层面、而不是单件作品层面定下来的。同一位艺术家的两幅画，不管画布上是什么，都会卖出相近的价钱，因为被定价的是签名。

读过拍卖图录注释的人会立刻明白这为什么成立。那些文字几乎全花在来源、展览史和可比销售上，对作品本身几乎不着一笔。

如果认真对待这个 5%，结论就是作品的美学内容和它的市场价值几乎脱钩。市场在奖励的东西，不管是什么，都不在画布上。一个能在像素层面理解艺术的模型，预测价格反而会输给一个只认识艺术家简历的模型。

第三阶段是有条件的

#

论文的图片链接列指向的是 2012 年还有效的 URL，到 2026 年大多已经死了。我写的计划在第 8 天就安排了这项风险检查：随机抽 100 个 URL，看有几个还活着。要是一半以上都没了，视觉阶段整个跳过，把原因写进报告。

反正视觉特征只解释约 5% 的价格方差。为了确认一个这么小的数字，去和链接腐烂搏斗两个星期，划不来。把死链的调查结果写进报告，继续往前走，才是正解。

既有市场 vs 新兴市场

#

论文为既有市场（美国、英国、法国、德国）和新兴市场（其余 19 个国家）分别训练模型。核心结果：

有两点跳出来。第一，社会信号在新兴市场更管用，而不是更不管用。我原以为既有市场数据更厚，社会特征的表现应该更好，结果正好相反。

第二，新兴市场的专家预估更不准——加入预估后的 0.916 对 0.859，差距就在这。在既有市场，算法预测得和背靠几十年可比数据的大拍卖行专家硬碰硬；在新兴市场，那位专家手里的数据薄得多，算法能补的缺口也就大得多。

真要把这种模型拿去商业化，能赚回饭钱的地方是新兴市场。

该说清楚的局限

#

这是论文复现，不是生产系统。它没有实时数据管道，模型用 1996–2012 的拍卖数据训练完就再也不更新了。没有部署，产出是几个 Notebook 和一份报告，不是预测 API。没有漂移检测，训练完的模型不知道市场什么时候变了。数据集是冻结的：加密艺术、NFT、新冠之后的市场变化，在训练数据里根本不存在。要是想预测韩国拍卖行的价格，还需要拍卖行专属特征，可能还得给韩国市场单独训一个模型——这些都没做。

模型反映的也只是历史模式。如果当代艺术市场在 2015 年前后发生过结构性变化（确实有人这么论证：艺博会崛起为一级市场的主要场地，新一代藏家入场），那 1996–2012 的规律未必还能外推。

从论文到平台

#

读完论文，我看第二个项目的眼光变了。这个平台最初的定位是艺术展览的众筹市场：艺术家提前为即将举办的展览锁定资金，投资者则比拍卖市场通常允许的时点更早接触到新兴艺术家。

产品表层刻意做得简单。艺术家发布需要资金的展览（场地、日期、预计参展作品）。投资者按分级金额（$100、$500、$1k、$5k）支持特定展览，作品售出后分享收益。艺术家和投资者之间的大部分聊天由 AI agent 接手，双方都不必在线，对话也不会断。韩国画廊隔着 14 个小时时差和美国藏家谈事情的时候，这一点格外有用。

一旦"资产是艺术家而不是作品"这件事沉淀下来，数据模型也得跟着改。要抓住的是：每件作品被谁拥有过、在哪展出过、可比作品卖了多少钱、还有谁也收藏这位艺术家。所有权链条、机构认可、拍卖可比案例、藏家网络——这正是知识图谱的用武之地。

数据模型故意做得很小：艺术家、作品、拍卖记录、持有期，再加一份数据本身的来源日志，每条记录是从哪抓来的都能追回去。最后这一项听着像记账，但数据是爬来的，有了它这张图才信得过。

移动端把这一切渲染成一张力导向图。时间范围滑块可以在年份间拖动，看着网络一点点长出来：哪些藏家什么时候入场，哪些艺术家被哪家博物馆相中，哪些作品在 2008 年低谷期换了主人。

每类实体有自己的形状和颜色：艺术家是菱形，作品是圆角矩形，拍卖行是六边形，收藏者、经销商、博物馆、遗产管理这些持有方则是不同颜色的圆。

形状不是装饰。缩小到几百个节点的时候，不用等标签渲染，光看轮廓就知道那是什么实体。被一圈圆围住的菱形，是一位有藏家网络的艺术家；连着一堆菱形的六边形，是一家代理多位艺术家的拍卖行。市场的结构一眼就能读出来。

第二个标签页把同样的数据放到时间轴上：持有期是水平条，销售是点事件。同一张图，换个镜头。想看的是"谁在什么时候持有了什么"的先后顺序、而不是某一时刻的网络形状时，就用它。

这个平台本身不是价格预测工具，它是垫在预测工具下面的数据层。想给 Lee 等人那样的模型喂上鲜活的当前数据、而不是冻结在 2012 年的 CSV，需要的就是这套结构。

把估价做成一个游戏

#

我还没动手做、却最感兴趣的部分，是把艺术品估价变成游戏。

Lee 等人的论文把拍卖行预售估价当特征用，R² 因此大涨。那些预估之所以值钱，是因为它们是受过训练的专家的聚合判断——这些人看过成千上万件可比作品，而且对结果有切身利害。但拍卖行专家是一种又窄又贵的资源：全球就几百位，只做具体的委托案，够不着那条还没人委托的艺术家长尾。

我反复回到的问题是：能不能从一个更宽、更便宜的判断池里，合成出一个可比的信号？

粗略的设计：

• 给用户看一件作品：图片、尺寸、年份、艺术家名字、简短履历。
• 问他们这件作品拍卖会卖多少钱。
• 让他们选一个价格区间，或者直接猜落槌价。
• 提交之后揭晓真实成交价。
• 用类似 Brier 分数的方式，随时间给他们打准确度评级。
• 提供排行榜、每日连胜、手感火热徽章。
• 用历史准确度给每位用户未来的预测加权。

本质上这是一个艺术品价格的预测市场，套着猜价游戏的壳。循环和猜地理位置的游戏、在线国际象棋的谜题评分一样：可重复、可打分、有反馈，能练出真本事。猜得准的人在排行榜上爬升，他们未来的猜测在聚合信号里的权重也更大。

真正的价值在模型那一侧。这些猜测的加权聚合，可以和社会信号并排喂给 XGBoost。如果群体的准确度加权中位数和落槌价相关性够好，你就为那些没有真实预估的作品造出了近似的"合成拍卖行预估”。而这恰恰补在 Lee 等人的模型最缺帮助的位置——艺术家长尾。

冷启动的角度也说得通。模型在价格历史丰厚的艺术家身上训练得很好，在只有三笔销售的艺术家身上一塌糊涂。三笔销售加一千个群体猜测，至少有东西可用了。众包估价，就是在给底层数据覆盖不到的情形制造训练信号。

游戏化在这里之所以关键，是因为让群体可靠的唯一办法，是把参与做得足够好玩，让人反复来玩。一次性的问卷只能从随手点过的人那里收到噪声。每日连胜加排行榜加校准徽章，能让同一个人在一年里认认真真做出 500 次预测。数量，再加上自我筛选（猜得准的留下来，猜不准的觉得无聊走人），才是把噪声变成信号的方式。

动手之前还有几个设计问题要想清楚。给用户看多少东西——只有图片和履历，还是连可比销售也给？上下文越多猜测越有依据，但过了某个点，用户就只是在复读你已经展示的内容。价格反馈给到什么粒度？揭示精确落槌价、一个区间，还是只告诉他们有没有落在 ±20% 之内？太精细会训练出锚定具体数字的用户，太模糊又没法校准。还有刷榜问题：玩家会扎堆猜自己认识的艺术家，猜 Banksy 基本是常识题而不是技能题。解法大概是像语言学习 App 选课那样强制随机抽样，再给隐去艺术家姓名的"盲猜"轮单设一个榜。最后是事后偏见，躲不掉——用户一旦知道某件 Basquiat 卖了 1.1 亿美元，就再也无法当作不知道。让这个循环保持诚实的，是源源不断的新作品供给，而这种供给每周是有限的。

游戏化的框架还把平台的两半拧在了一起。众筹一侧奖励的是展览财务表现好时的投资者；猜价一侧奖励任何会准确叫价的人，不管掏没掏钱。两者是同一个想法的两种形态：把群体的集体判断变成可交易的信号——一个交易资本，一个交易注意力。真正练出准头的玩家，最终可以带着可验证的叫价准确度记录，“毕业"到投资者那一侧。这个过滤器，比"认识对的画廊主"强多了。

我带走的几件事

#

预售估价非常厉害。拍卖行常因定价不透明挨骂，但他们的预估单凭自己就能捕捉接近 90% 的价格方差。专家在做什么且不论，做得是真好。可与此同时，作品本身在统计上几乎无关紧要——如果你是出于审美喜欢艺术，这个结论并不好受。市场定价的不是你眼睛看到的东西，而是别人已经为相邻作品掏过的钱。

建模层面，有两个习惯物有所值。按时间拆分是评估价格模型唯一诚实的方式，随机拆分给出的漂亮 R² 到了真实生产环境就露馅。梯度提升树在这里依然是正确的工具：论文里 XGBoost 赢了所有神经网络基线，这种规模、这种工程化程度的表格数据，没有理由去够 transformer。

商业上的观察也有两条。有意思的机会在新兴市场，那里专家定价最薄，算法预测能补的缺口最大。以及，群体是一个被低估的数据来源。Lee 等人模型里最大的单一特征就是拍卖行预估；如果校准过的群体能为艺术家长尾产出可比的信号，那是实打实的机会——既是模型输入，本身也能是个产品。

两个项目最后比我计划的更互补。论文复现教会我什么在预测价格，平台工作教会我要用上这些知识需要什么样的数据结构，游戏化的想法则把两头接起来：知识图谱供给作品和历史销售，猜价游戏产出群体推导的预估特征，模型把这个特征和社会信号一起消化，为那些原本对它不可见的艺术家给出预测。

这些都还没做完。论文复现是一个附带书面报告、能跑的原型；平台是一个填了种子数据的演示；众包猜价游戏眼下只存在于你刚读完的这份设计笔记里。但贯穿其中的想法足够一致，正确的形状在我看来已经相当清楚：给艺术家定价，而不是给作品定价；聚合群体，而不是只依赖专家；把估价当成市场共同产出的东西，而不是专家自上而下交下来的结论。

有时间的话，下一个要做的就是这个版本。