> ## 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.7

> 2026-05-08

升级 Codex 0.129 后跑一次 `/hooks` 审批 Trellis hook（不审批工作流不会自动注入，详见下方）。新增 `codex.dispatch_mode`，Codex 项目可切换到 `inline` 派发模式。修复：Codex 子代理 `wait_agent` 卡死（[`#240`](https://github.com/mindfold-ai/Trellis/issues/240) follow-up、[`#241`](https://github.com/mindfold-ai/Trellis/issues/241)）、Kiro CLI 拒认 agent JSON（[`#247`](https://github.com/mindfold-ai/Trellis/issues/247)）、Windows `trellis init` 找不到 `python3` / `py -3`（[`#236`](https://github.com/mindfold-ai/Trellis/issues/236)）。无新增 migration。

## Codex 0.129 兼容性

### `/hooks` 审批门（必须在 TUI 里授权）

Codex 0.129 把每个安装的 hook 卡在一次性 `/hooks` TUI 审批之后。用户没在 Codex 里跑 `/hooks` 审批 Trellis 的 `UserPromptSubmit` hook 之前，workflow 指引不会自动注入；升级后每个新 Codex 会话看起来都像 Trellis 没接进去。

`inject-workflow-state.py` 里现成的 `<trellis-bootstrap>` fallback 会兜底：hook 没触发时让 AI 手动读 `trellis-start` skill，工作流照常跑（只是体验降一点）。Trellis 这边不需要任何代码变更。**升级 Codex 后跑一次 `/hooks`** 完成审批，自动注入恢复。

### `[features].codex_hooks` 改名为 `[features].hooks`

Codex 0.129 把 `[features].codex_hooks` 改名为 `[features].hooks`（旧名仍能用，但启动会打 deprecation 警告）。Trellis 文档（`advanced/multi-platform`、`advanced/architecture`、`advanced/custom-hooks`、`advanced/appendix-f`、`start/install-and-first-task`、`start/everyday-use`、`start/how-it-works`）、`spec/cli/backend/platform-integration.md` 规则、`trellis init` 运行时警告都更新到新名字。卸载脚本同时识别新的 `hooks = true` 和旧的 `codex_hooks = true`，老项目卸载不受影响。

## Enhancements

### Codex 可配置派发模式

`.trellis/config.yaml` 新增项目级开关：

```yaml theme={null}
codex:
  dispatch_mode: sub-agent # 默认；设为 "inline" 跳过子代理派发
```

设为 `inline` 后，`<workflow-state>` 指引会让主 Codex 代理加载 `trellis-before-dev` 直接改代码，然后加载 `trellis-check` 跑 lint / typecheck / tests，而不再派发 `trellis-implement` / `trellis-check` 子代理。

机制：`inject-workflow-state.py` 读 config，命中 codex+inline 时从 `workflow.md` 拿 `[workflow-state:in_progress-inline]` / `[workflow-state:planning-inline]` 块；`get_context.py --platform codex` 在 inline 模式下切到 `[Kilo, Antigravity, Windsurf]` 块内容。每轮的 inline override 短语（`do it inline` / `你直接改` 等）在两种模式下都继续生效。

仅限 Codex。Class-1 平台（Claude Code、Cursor、OpenCode、Kiro、CodeBuddy、Droid）和其他 class-2 平台保持派发默认。`.codex/agents/*.toml` 文件依旧写入，子代理基础设施保留。

### `configSectionsAdded` manifest 字段

新增可选 manifest 字段，声明本版本在 `.trellis/config.yaml` 引入的顶层 key：

```jsonc theme={null}
{
  "version": "0.5.7",
  "configSectionsAdded": [
    {
      "file": ".trellis/config.yaml",
      "sentinel": "codex:",
      "sectionHeading": "Codex (sub-agent dispatch behavior)",
    },
  ],
}
```

`trellis update` 遍历每个 manifest 的 `configSectionsAdded`，对每条缺 `sentinel` 的目标文件，从打包模板提取对应 section 追加到末尾。仅追加，幂等（重跑时 sentinel 已在），用户自定义内容不动。未来新增 config section 在对应版本 manifest 加条目即可，`update.ts` 无需改动。

替换原来的"已修改文件覆盖提示"路径，之前用户自定义过 `config.yaml` 后只能在"接受模板（丢自定义）"和"跳过（拿不到新 section）"中二选一。

## Bug Fixes

### Codex 子代理 collab 工具，协议层硬禁用（[`#240`](https://github.com/mindfold-ai/Trellis/issues/240) follow-up、[`#241`](https://github.com/mindfold-ai/Trellis/issues/241)）

[v0.5.5](/zh/changelog/v0.5.5) 移除了 `SessionStart` 注入路径。[v0.5.6](/zh/changelog/v0.5.6) 在 `AGENTS.md` 加了 prompt-layer 的 `fork_turns="none"` 提示。两条都是 prompt 层修复。[Ca11back 在 `#241` 下的复现](https://github.com/mindfold-ai/Trellis/issues/241)显示 prompt 层修复没落地：

* 主代理仍用默认 `fork_turns="all"` 派发 `trellis-research`，无视 AGENTS.md 规则。
* 子代理继承父对话历史，包含父之前的 `spawn_agent(...)` 工具调用记录。
* 子代理读到 AGENTS.md 的 "ALWAYS wait for every spawned subagent..." 规则，把它套到自己头上，对继承来的 spawn 记录调 `wait_agent`。
* 没有真实子代理可等。`No agents completed yet`。卡死。

结构性修复：每个 `packages/cli/src/templates/codex/agents/trellis-{implement,check,research}.toml` 现在带：

```toml theme={null}
[features]
multi_agent = false

[features.multi_agent_v2]
enabled = false
```

两个 flag 都关之后，Codex 不会给子代理注册 `spawn_agent` / `wait_agent` / `list_agents` / `close_agent`。

新增 `[issue-241-followup]` 回归测试断言三个 template toml 都保留 disable block。

### Codex `trellis-start` skill 在升级路径丢失

0.5.5 的 `configureCodex()` 写 `.agents/skills/trellis-start/SKILL.md`，让 `inject-workflow-state.py` 的 `<trellis-bootstrap>` 提示能解析到真实 skill。但 `collectPlatformTemplates.codex.collectTemplates()`（`trellis update` 用的路径）漏了。

后果：用户从 0.4.x 升到 0.5.5/0.5.6 时，先跑 safe-file-delete migration 删掉 `.agents/skills/start/`，然后 `trellis update` 通过 `collectTemplates` 重写其他 `trellis-*` skill 目录，但**永远不写 `trellis-start`**。AI 之后每次命中 `<trellis-bootstrap>` 都报 "no `.agents/skills/trellis-start/SKILL.md`"。

修法：抽 `resolveCodexTrellisStartSkill()` helper 进 `configurators/shared.ts`，在 `configureCodex()`（init）和 `collectPlatformTemplates.codex`（update）两处都调，让文件在两条路径都生成。两边共享同一个 helper，drift 不可能再发生。

### Kiro CLI agent JSON schema 迁移（[`#247`](https://github.com/mindfold-ai/Trellis/issues/247)）

Kiro CLI 拒绝 Trellis 0.5.7 之前的 agent JSON，报 "invalid agent"。按 Kiro 官方 [Agent Configuration Reference](https://kiro.dev/docs/cli/custom-agents/configuration-reference)，三处 schema 变更：

1. **`instructions` 改成 `prompt`**。Kiro CLI 不再接受 `instructions`。
2. **新增 `allowedTools` 字段**，镜像 `tools`。Kiro 把"可用工具"和"允许调用工具"分开；没 `allowedTools` 的话 agent 实际上没法调任何工具。
3. **`hooks` 数组改成按事件名 key 的对象**：

   ```json theme={null}
   // 之前
   "hooks": [
     { "on": "agentSpawn", "command": "...", "timeout_ms": 30000 }
   ]
   // 现在
   "hooks": {
     "agentSpawn": [{ "command": "..." }]
   }
   ```

   `on` 字段去掉（事件名变 key）。`timeout_ms` 去掉。

影响 `trellis-{implement,check,research}.json` 三个文件。新增 `[issue-247]` 回归测试断言新 schema（`prompt` 存在、`instructions` 不存在、`allowedTools` 是数组、`hooks` 是对象）。

### Windows Python 检测 fallback chain（[`#236`](https://github.com/mindfold-ai/Trellis/issues/236)）

`trellis init` 之前在 Windows 上只 try `python --version`。如果 host 上 Python 装在 `python3`（Microsoft Store）或 `py -3`（python.org launcher）下而没有 `python`，init 会直接失败 `Python command "python" not found`。

`packages/cli/src/commands/init.ts` 里的 `resolveSupportedPython()` 改成按平台 candidate list 顺序探测：

| 平台      | 候选顺序                       |
| ------- | -------------------------- |
| Windows | `python`、`python3`、`py -3` |
| 其他      | `python3`、`python`         |

第一个 `--version` 拿到 Python ≥ 3.9 的胜出。结果通过 `configurators/shared.ts` 的 `setResolvedPythonCommand()` 缓存，使 `replacePythonCommandLiterals()` 和所有后续 template / configurator 写入都用相同值。

两个 env-var 逃生口：

* `TRELLIS_PYTHON_CMD=<cmd>` 用于显式覆盖（不探测）。
* `TRELLIS_SKIP_PYTHON_CHECK=1` 用于完全跳过探测（之前就有）。

全部失败时抛出聚合错误：列出每个候选的探测结果，加上 Windows 专属安装提示（指向 python.org，提醒勾选 "Add Python to PATH"）。

`packages/cli/test/commands/init-internals.test.ts` 加 6 个单测覆盖 fallback chain、env-var 覆盖、sandbox-restricted EPERM、聚合失败。

## Upgrade

```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```

不需要 `--migrate`。Codex 用户拿到加固后的 sub-agent role 文件；Windows 用户不再需要先装 0.4.0。Codex 0.129+ 用户在 Codex 升级后跑一次 `/hooks` 审批 Trellis 的 `UserPromptSubmit` hook。