> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trytrellis.app/llms.txt
> Use this file to discover all available pages before exploring further.

# v0.5.0-beta.11

> 2026-04-22

Hotfix：`SessionStart` hook 在模块 import 阶段被 PEP 604 联合类型标注炸掉——AI CLI host 拉起的 `python3` 解析到 macOS 系统 3.9，哪怕用户 shell 里 `python3` 是 3.11。非 breaking，不用加 `--migrate`。同时把声明的 Python 版本底线从 3.10 下调到 3.9，让 macOS 系统自带的 `python3` 开箱可用。

## Bug 修复

### Hook PEP 604 标注崩溃

`packages/cli/src/templates/shared-hooks/session-start.py` 和 `inject-subagent-context.py` 顶部没写 `from __future__ import annotations`，于是 PEP 604 联合类型标注（`str | None`、`dict | None`）在 Python 处理 `def` 语句时就被立即求值。任何 `python3` \< 3.10 都会让模块直接抛：

```
TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'
```

现场踩到的场景是 macOS：用户 shell `python3 --version` 返回 3.11.12（homebrew），但 AI CLI host 拉起 hook 子进程时 PATH 是被裁剪过的，里面没有 `/opt/homebrew/bin`。`env python3` 落到 `/usr/bin/python3` → macOS 系统自带的 3.9，没实现 PEP 604 的表达式求值。

`packages/cli/src/templates/shared-hooks/statusline.py` 和 `copilot/codex` 两份 `session-start.py` 早就加上了这个 future import；只有 `shared-hooks/*.py` 这两个主文件漏了。

**修复** —— 在模块 docstring 后面加一行：

```python theme={null}
"""Session Start Hook - Inject structured context"""
from __future__ import annotations                   # 新增
```

| 文件                                                                   | 变更                                    |
| -------------------------------------------------------------------- | ------------------------------------- |
| `packages/cli/src/templates/shared-hooks/session-start.py`           | `+from __future__ import annotations` |
| `packages/cli/src/templates/shared-hooks/inject-subagent-context.py` | `+from __future__ import annotations` |

`from __future__ import annotations`（PEP 563）会把所有标注变成惰性字符串，所以标注里的 PEP 604 语法在 Python 3.7+ 都能跑。运行时的联合表达式——比如 `isinstance(x, int | str)`——**不**受这个 import 影响，仍然需要 3.10+；这两个 hook 都没用到。

## 改进

### Python 版本底线从 3.10 下调到 3.9

`packages/cli/src/commands/init.ts` 里的 `MIN_MINOR` 改成 `9`。原因：macOS Ventura / Sonoma / Sequoia 系统自带的 `/usr/bin/python3` 都是 3.9.6；另外 Trellis 分发的模板文件（`shared-hooks/*.py` 和 `trellis/scripts/**/*.py`）经过完整 package-import 矩阵实测，30 个文件在 CPython 3.8–3.13 全部导入通过。

| 改动                                          | 位置                                                              |
| ------------------------------------------- | --------------------------------------------------------------- |
| `MIN_MINOR = 10` → `9`                      | `packages/cli/src/commands/init.ts`                             |
| Warning 文案 `Python ≥ 3.10` → `Python ≥ 3.9` | `packages/cli/src/commands/init.ts`（2 处）                        |
| `Python ≥ 3.10` → `Python ≥ 3.9`            | `README.md`                                                     |
| Quickstart 前置要求表                            | `docs-site/quickstart.mdx` + `docs-site/zh/quickstart.mdx`（新增段） |

CI 矩阵暂未加——实测 harness 跑在 `/tmp/trellis-py-compat/` 下、没提交到仓库。不支持 Python 3.8：2024-10 已 EOL，声明支持会背上 CVE backport 的维护责任。

### init 现在和模板层共用同一套按 OS 选 Python 命令的规则

模板层早就把 `{{PYTHON_CMD}}` 渲染成 Windows 用 `python`、macOS / Linux
用 `python3`，但 `packages/cli/src/commands/init.ts` 之前还是所有平台都先探测
`python3`，失败后才回退到 `python`。结果就是 Windows 提示文案、生成出来的
hook 命令、以及 init 自己执行 `init_developer.py` 时实际用的解释器并不一致。

现在 `trellis init` 两边统一成同一条平台规则：

| 平台            | 生成到文件里的命令 | init 探测 / bootstrap 使用的命令                                            |
| ------------- | --------- | -------------------------------------------------------------------- |
| Windows       | `python`  | `python --version`、`python .trellis/scripts/init_developer.py ...`   |
| macOS / Linux | `python3` | `python3 --version`、`python3 .trellis/scripts/init_developer.py ...` |

如果当前平台对应的命令解析到 Python \< 3.9，init 会打印 warning，但仍然完成。
如果本机根本没有 Python，文件生成也还是不会被阻断；后续行为仍然是保留现有的
手动 bootstrap 提示。

| 文件                                                    | 变更                                                    |
| ----------------------------------------------------- | ----------------------------------------------------- |
| `packages/cli/src/configurators/shared.ts`            | 导出共享的 OS → Python 命令 helper，模板渲染直接复用                  |
| `packages/cli/src/commands/init.ts`                   | 复用同一个 helper 做版本探测、Windows 提示和 `init_developer.py` 调用 |
| `packages/cli/test/commands/init.integration.test.ts` | 给 init bootstrap 命令和 soft warning 路径补回归测试             |
| `packages/cli/test/commands/init-internals.test.ts`   | 给 Python 版本 warning 行为补单测                             |

## 升级

老项目：

```bash theme={null}
trellis update
```

会拉下两个修过的 hook 文件和新版 `cross-platform-thinking-guide.md` 模板。文件是 pristine 的会静默应用；本地改过的会走标准的 confirm 提示。

新装：

```bash theme={null}
npm i -g @mindfoldhq/trellis@0.5.0-beta.11
```