跳转到主要内容

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.

升级 Codex 0.129 后跑一次 /hooks 审批 Trellis hook（不审批工作流不会自动注入，详见下方）。新增 codex.dispatch_mode，Codex 项目可切换到 inline 派发模式。修复：Codex 子代理 wait_agent 卡死（#240 follow-up、#241）、Kiro CLI 拒认 agent JSON（#247）、Windows trellis init 找不到 python3 / py -3（#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 新增项目级开关： 
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： 
{
  "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 follow-up、#241）

v0.5.5 移除了 SessionStart 注入路径。v0.5.6 在 AGENTS.md 加了 prompt-layer 的 fork_turns="none" 提示。两条都是 prompt 层修复。Ca11back 在 #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 现在带： 
[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）

Kiro CLI 拒绝 Trellis 0.5.7 之前的 agent JSON，报 “invalid agent”。按 Kiro 官方 Agent Configuration Reference，三处 schema 变更：
  1. instructions 改成 prompt。Kiro CLI 不再接受 instructions。
  2. 新增 allowedTools 字段，镜像 tools。Kiro 把”可用工具”和”允许调用工具”分开；没 allowedTools 的话 agent 实际上没法调任何工具。
  3. hooks 数组改成按事件名 key 的对象： 
    // 之前
"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）

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 顺序探测：
平台候选顺序
Windowspython、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

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。