Trellis 0.6.16 安全升级
Trellis Engineering Guide

从 0.6.0 / 0.6.5 安全升级到 0.6.16

一份版本锁定、可回滚的执行指南:先识别真实项目边界和版本,再升级 CLI、受保护地分析项目差异、同步模板并验证。Codex 模式、模型分层、Claude Code + GLM-5.3 系列共存和高级编排规范作为按需配置。

目标版本:Trellis v0.6.16 适用:新初始化 / 已长期使用项目 平台:Codex + Claude Code + GLM-5.3 系列 命令环境:macOS / Linux;含 PowerShell 对照 形式:单文件、离线可读、可打印

执行摘要

0.6.16

新项目与旧项目的推荐目标版本。

auto

0.6.8+ 的原生 Codex 子代理模式;0.6.16 默认模板值。

最多 2 次

仅在确需修改且选择尚未明确时,确认模式与模型方案。

可回滚

先确认 Git 根与干净基线,保护 task、spec、人工模板和个人配置。

推荐基线:将 CLI 和项目模板都锁定到 0.6.16;复杂任务采用 auto + 均衡模型方案,小任务直接 Inline 或不创建完整 Trellis task;Claude Code + GLM-5.3 系列保持用户环境继承,不在仓库中写入密钥、Endpoint 或个人模型映射。
定位
Git 根 / 项目根 / CLI 路径
保护性分析
哈希快照 / dry-run / diff
确认模式
Inline / Sub-agent
确认方案
质量 / 均衡 / 额度
修改与验证
diff / hooks / context / team

执行前必须知道的两个版本事实

事实 1:v0.6.16 的 Codex 默认模式是 auto它会派发 trellis-researchtrellis-implementtrellis-checksub-agent 只是 auto 的兼容别名。只有希望实现与检查都留在主会话时才写 inline[4]
事实 2:v0.6.16 的 trellis update --dry-run 不保证字节级只读。当模板哈希清单含 orphan key 时,CLI 可能改写 .trellis/.template-hashes.json,随后仍输出“没有修改”。因此每次 dry-run 前后都要比较该文件的 SHA-256、大小和 mtime;一旦变化,停止升级、审查差异并从已确认基线恢复。[10]
版本 模板默认值 开启子代理的写法 解释
0.6.0 inline sub-agent 早期 Codex 子代理上下文继承不够稳定,默认保守地留在主会话。
0.6.5 inline sub-agent 平台与工作流更稳,但尚未切到原生 Codex dispatch 默认。
0.6.8+ auto auto Codex 原生 SubagentStart 注入与 child-side fallback 就绪;sub-agent 保留为别名。[7]
0.6.16 auto auto 并增加 context manifest gate、上下文上限、配置持久化等保护。

部分滚动更新的网页说明可能仍显示旧默认值。配置决策应优先参考“本地安装版本生成的模板”或“对应 Git tag 的版本锁定模板”,不能只看未锁定版本的页面。

3 分钟决策:你真正需要选择什么

1. 目标版本是否固定为 0.6.16?

本指南答案:是。所有主路径命令都固定到 0.6.16;如果你有意跟随 latest,应先重新核验 changelog、模板和本页结论。

2. Codex 应用 Inline 还是 Auto/Sub-agent?

结论:不是二选一的永久宗教。小任务 Inline 更快、总 Token 通常更低;复杂多模块任务用 Auto/Sub-agent,可隔离上下文并获得独立 Review。0.6.16 的配置值应优先使用 auto,而不是旧写法 sub-agent

3. Main / Research / Implement / Check 如何分配模型?

结论:最强模型应放在“高杠杆判断”上:Main 做规划,Check 做质量门禁;Research 与大量 Implement 可用更均衡的模型。默认推荐 Sol / Terra 混合,而不是所有角色都使用最贵模型。

4. 什么时候需要 AI 询问?

结论:先检测;无需修改时直接报告。确需修改但模式或模型方案尚未明确时才询问,最多两次。用户已经明确选择时不重复确认,同时将 Claude Code + GLM-5.3 系列视为独立用户环境。

版本演进:0.6.0 → 0.6.5 → 0.6.16

2026-06-15

v0.6.0:架构基线

trellis channel 多 Agent 协作为头部能力,补齐 trellis mem、Core SDK、任务规划产物与多平台工作流。官方当时列出 15 个支持平台。[1]

ChannelMemoryPRD/Design/Implement

2026-06-25

v0.6.5:稳定化

新增 Trae,修复 Pi 启动上下文与子代理工具,改善 Windows channel,并收紧 hook 与 planning gate。它的价值更多是“从能用到可靠”,不是第二次架构重写。[2]

TraePiWindowsPlanning Gate

2026-08-27

v0.6.16:成熟化

引入 context manifest gate、task rename/branch metadata、ablate/restore、可恢复 session recorder、OpenCode mem reader,并集中修复 hooks/channel。[3]

Context GateTask LifecycleRecovery

能力维度 0.6.0 0.6.5 0.6.16 实际影响
Codex dispatch 默认 Inline 默认 Inline 默认 Auto 复杂任务可原生拆给 Research / Implement / Check。
上下文传递 早期能力,保守 pull-based 更稳 注入 + fallback + caps + gate 降低残缺上下文直接开工的风险。
Context manifest 有结构 强调 curated JSONL 空 manifest 阻止 start 从“提示约束”升级为“程序约束”。
Agent 模型配置 容易随生成变化 尚非重点 0.6.9+ update 保留 TOML 自定义 可长期维护 per-agent 成本与质量策略。
任务生命周期 基础任务流 planning gate 更严格 rename、branch metadata、archive 校验 多任务、多分支、多 worktree 更安全。
恢复与试验 基础备份 可靠性修补 ablate/restore、可恢复 recorder 可逆移除 Trellis,也更不怕半完成记录。
Memory mem 成型 平台扩展 压缩会话恢复、OpenCode reader 恢复 跨 Session 检索更完整。
升级价值排序:0.6.5 → 0.6.16 的工程收益通常明显大于 0.6.0 → 0.6.5,尤其对 Codex 子代理、长会话、多任务和团队项目。

安全升级操作:定位、锁定、分析、同步、回滚

Trellis 同时存在 npm 发布版本、本机 CLI 版本和仓库内项目模板版本。完整升级是先把全局 CLI 精确锁定到 0.6.16,再在真实 Trellis 项目根中同步项目文件。[5]

开始条件:先确认真实 Git 根和 Trellis 项目根,确保现有业务修改已提交到普通分支或有明确、可恢复的基线。聚合目录可能不是 Git 仓库;不要让模板变更混入无法解释的业务 diff,也不要仅因升级自行创建 worktree。

第一步:定位边界并记录基线(macOS / Linux)

# 在你认为的项目目录执行;第一条必须返回真实 Git 根
git rev-parse --show-toplevel
git status --short

# 确认当前 shell 实际调用的 CLI,以及 CLI / 项目模板版本
command -v trellis
trellis --version
test -f .trellis/.version || { echo '当前目录不是 Trellis 项目根'; exit 1; }
cat .trellis/.version

# 记录 dry-run 可能改写的文件基线
test -f .trellis/.template-hashes.json && \
  shasum -a 256 .trellis/.template-hashes.json
# macOS 与 Linux 分别执行对应一条
stat -f 'size=%z mtime=%m' .trellis/.template-hashes.json
stat -c 'size=%s mtime=%Y' .trellis/.template-hashes.json

# 当前版本支持时执行;失败必须保留真实错误,不要静默吞掉
trellis platforms --json
PowerShell 对照
git rev-parse --show-toplevel
git status --short
Get-Command trellis | Select-Object -ExpandProperty Source
trellis --version

if (Test-Path '.trellis/.version') {
  Get-Content '.trellis/.version'
} else {
  throw '当前目录不是 Trellis 项目根'
}
if (Test-Path '.trellis/.template-hashes.json') {
  Get-FileHash '.trellis/.template-hashes.json' -Algorithm SHA256
  Get-Item '.trellis/.template-hashes.json' |
    Select-Object Length, LastWriteTimeUtc
}
trellis platforms --json

第二步:把全局 CLI 精确锁定到 0.6.16

# 先查看将执行的 npm 命令,再安装指定版本
trellis upgrade --tag 0.6.16 --dry-run
trellis upgrade --tag 0.6.16

# 只有本机仍是 0.5.x、没有 trellis upgrade 命令时:
npm install -g @mindfoldhq/trellis@0.6.16

trellis --version

只有明确决定跟随未来稳定版、并准备重新核验 changelog 与模板时,才把 0.6.16 改成 latest。版本锁定指南不应默认使用会漂移的 dist-tag。

第三步:受保护地分析并同步项目

v0.6.16 已知风险:下面的 dry-run 可能改写 .trellis/.template-hashes.json。执行前后都要记录 SHA-256、大小和 mtime;若发生变化,立即停止并审查该文件,不要把“No changes made”当成只读证明。[10]
# 1. 记录 .template-hashes.json 的 SHA-256 / 大小 / mtime
# 2. 执行变更分析
trellis update --dry-run
# 3. 立即重新记录同一文件的 SHA-256 / 大小 / mtime,并检查 Git diff
git status --short
git diff -- .trellis/.template-hashes.json

# 只有基线仍可解释、且输出没有 MIGRATION REQUIRED 时才同步
trellis update

# 若明确提示 MIGRATION REQUIRED:先执行受保护的迁移分析
trellis update --migrate --dry-run
# 再次核对哈希和完整 diff,确认后执行
trellis update --migrate

官方文档说明 trellis update 通常只更新未被修改的模板并创建时间戳备份;这不等同于“零覆盖”。迁移包含重命名、移动或删除,仍须以真实 diff、备份和恢复验证为准。[5]

第四步:核验升级结果

command -v trellis
trellis --version
cat .trellis/.version
trellis platforms --json

git status --short
git diff -- .trellis .codex .claude .agents

# 再做一次受保护的差异分析,并比较前后哈希
trellis update --dry-run
  • 实际 CLI 路径正确,CLI 与项目模板版本都精确为 0.6.16。
  • update --dry-run 前后哈希一致,或所有变更都已明确解释并恢复。
  • task、spec、journal、workspace 和人工 workflow 未被清空或覆盖。
  • 没有 API Key、Endpoint、个人模型映射进入 Git diff。
  • Codex 与 Claude Code 的平台文件都仍存在且职责隔离。

第五步:异常时停止并回滚

  1. 停止继续执行 update--migrate-f,保存终端输出和当前 diff。
  2. 仅从升级前已确认的 Git 提交、分支或 Trellis 时间戳备份恢复受影响文件;不要用会丢失其他修改的全局重置命令。
  3. 若全局 CLI 版本错误,执行 npm install -g @mindfoldhq/trellis@0.6.16,再核对 command -v trellistrellis --version
  4. 恢复后重新比较 Git 状态、模板哈希和平台目录;原因未解释前,不要再次同步项目。

迁移判断:版本清单、CLI 输出与 diff 三方核对

起点 → 目标 建议动作 说明
0.5.x → 0.6.x --migrate 必需 0.6.0 的迁移链包含 breaking rename/delete;先用 npm 升 CLI,再 dry-run 迁移。[1]
0.6.0 → 0.6.5 普通 trellis update 0.6.5 官方标注无需 migrate。
0.6.0 / 0.6.5 → 0.6.16 受保护地分析 大多数项目可直接 update;若跨越涉及路径迁移的平台(例如旧 Pi 布局),CLI 会提示 MIGRATION REQUIRED。dry-run 前后必须核对模板哈希文件。
0.6.16 → 0.6.16 通常无需修改 若仍有漂移,应区分模板更新、人工定制或未完成的历史迁移。
避免:不要只凭版本号决定迁移,也不要为了消除提示直接执行 trellis update -f。Force 可能覆盖真正需要保留的人工配置;应同时核对版本迁移清单、CLI 输出、模板哈希和 Git diff。

Codex:Inline 与 Auto/Sub-agent 如何选择

Inline

同一个 Main Codex 完成理解、实现、检查。

上下文连续启动快总 Token 通常较低

代价:主会话膨胀更快;Review 不够独立;长需求更容易受 compaction 影响。

VS

Auto / Sub-agent

Main 做 Tech Lead,Research / Implement / Check 隔离执行。

上下文隔离独立 Review适合复杂任务

代价:有调度与重复加载开销,总 Token 可能更高,且依赖结构化任务上下文质量。

决策信号 优先 Inline 优先 Auto/Sub-agent
任务边界 问题局部、输入完整、一个会话内可理解与验证。 跨模块或跨角色,前置研究会影响后续实施。
风险 可快速回退,不涉及关键权限、资金、数据迁移或并发一致性。 错误代价高,需要独立检查或多层证据。
上下文 材料少且连续,拆分会增加重复加载。 材料多、会话长,隔离上下文能降低遗漏。
协作成本 单一所有者即可完成,调度成本高于收益。 职责和读写边界可以明确拆分,输出可独立验收。

0.6.16 配置示例

保留主会话执行

codex:
  dispatch_mode: inline

使用原生子代理

codex:
  dispatch_mode: auto

# "sub-agent" 只是兼容别名

实用选择规则

优先 Inline

单文件或少量文件、小 Bug、文案/CSS、简单类型错误、能在一个会话内理解与验证。

优先 Auto

跨模块、架构变化、复杂状态,或涉及权限、支付、迁移、并发等高风险任务;重点是依赖和风险,不是机械文件数。

最佳实践

项目默认 auto;小任务不创建完整 Trellis task,或明确要求本轮 Inline。不要用牛刀处理一行修改。

核心认识:Sub-agent 的主要价值是“主会话上下文隔离 + 角色独立”,并不等于“总 Token 更省”。

Codex Sub-agent 三套推荐配置基线

以下是截至 2026-09-04 的工程建议,不是 Trellis 官方强制默认。OpenAI 将 Sol 定位为复杂专业工作旗舰,Terra 用于能力/成本平衡,Luna 用于成本敏感的高吞吐工作;模型、reasoning 档位和额度以当前 Codex 客户端与账号实际可用性为准。[8]

方案 Main Research Implement Check 适用场景
1. 质量优先
高成本
Sol / high 或 xhigh Terra / high Sol / high Sol / high 或 xhigh 核心业务、架构调整、大型重构、支付/权限/迁移等高风险工作。
2. 均衡推荐
默认推荐
Sol / high Terra / medium Terra / high Sol / high 绝大多数真实项目、中大型 Feature、长期日常开发。
3. 额度/速度
低成本
Sol / high Luna / medium Terra / medium Terra / high 规范成熟、计划清楚、CRUD 与重复性开发较多。

为什么不是所有 Agent 都用最强模型?

Main:高杠杆决策

需求理解、架构、拆分一旦错,所有下游都会围绕错误方向工作,因此 Main 最值得使用强模型。

Check:高杠杆质量门禁

Review 相对短,却要识别需求遗漏、架构偏差和边界风险,使用强模型常比让 Implement 全程使用最强模型更划算。

Research:检索与归纳

多数工作是代码搜索、模式识别和总结,Terra/medium 通常足够;机械枚举任务可进一步降到 Luna。

Implement:最大工作量

在高质量 PRD / Design / Plan 已明确后,Implement 应主要执行而不是重新发明架构,均衡模型可承担大量编码。

Reasoning 建议:high 是复杂工程任务的常用高质量档;xhigh 留给架构迁移、疑难 Bug、高风险设计;max 不作为日常默认,且必须确认当前 Codex 客户端确实支持。

0.6.16:在 Agent TOML 中固定子代理模型

从 0.6.9 起,用户设置的 model / model_reasoning_effort 会在 trellis update 重新生成时保留。若不固定,子代理继承 Main 会话模型。[6]

trellis-research.toml

model = "gpt-5.6-terra"
model_reasoning_effort = "medium"

trellis-implement.toml

model = "gpt-5.6-terra"
model_reasoning_effort = "high"

trellis-check.toml

model = "gpt-5.6-sol"
model_reasoning_effort = "high"
不要破坏 Agent 定义:只调整必要的模型字段。保留 name、description、sandbox、developer instructions、上下文加载和递归保护。Main 模型通常由 Codex 会话或用户级配置选择,不是靠这三个 TOML 设置。

多人协作:Codex 与 Claude Code + GLM-5.3 系列共存

Z.AI 官方提供 Claude Code 的 Anthropic 兼容接入方式,其 Provider、Endpoint、Token 与 Claude 内部模型映射通常存放在用户级 ~/.claude/settings.json 或环境变量中;截至 2026-09-04,官方示例中的默认模型映射为 GLM-5.3-Flash[9] 因此本文中的“GLM-5.3 系列”是家族称呼,实际模型 ID 应以成员当前配置为准,团队仓库不接管个人 Provider。

仓库中可以提交

  • Trellis workflow、spec、task 结构。
  • 平台无关的 Claude Trellis Agent/Skill/Command 定义。
  • Codex 专属 dispatch_mode
  • 团队已共同接受的 Codex Agent 模型策略。

仓库中禁止提交

  • API Key、Token、个人 Endpoint。
  • 完整复制的 ~/.claude/settings.json
  • 强制覆盖所有人的 GLM/Claude 模型映射。
  • 把 GPT 模型 ID 写进 .claude/agents/

推荐目录与职责隔离

.trellis/                 # 团队共享:workflow、spec、tasks、配置
.codex/agents/            # Codex 专属 Agent;可设置 Codex 模型
.claude/agents/           # Claude Code 专属 Agent;保持 Provider 无关
.agents/                  # 跨平台共享 Skill(按 Trellis 当前版本生成)

~/.codex/config.toml      # 用户级;不由项目 AI 静默修改
~/.claude/settings.json   # 用户级;GLM/Claude Provider、Token、映射
平台隔离成立:v0.6.16 模板明确说明 codex.dispatch_mode 仅影响 Codex,其他平台忽略。因此 Codex 使用 auto 不应改变 Claude Code + GLM-5.3 系列的执行环境。[4]

团队落地规则

  • Claude Code Agent 默认继承每位成员当前的 GLM/Claude 环境。
  • 只检测并报告用户级 Claude 配置是否可用,AI 不静默改全局文件。
  • 项目文档可写“如何配置”,但示例必须用占位符,绝不包含真实 Token。
  • 模型映射不同的成员仍可共享同一套 Trellis task、spec 和 workflow。
  • 升级前后对 .claude/ 单独做 Git diff,确保无意覆盖没有发生。

0.6.16 工程最佳实践

1. Context manifest 必须“真实精选”

implement.jsonl / check.jsonl 存在但没有 curated entries 时,0.6.16 的 validate 会失败,start 会拒绝执行,除非显式使用 --allow-empty-context[3]

不要填无意义占位行绕过门禁;应引用真正相关的 spec、research、源文件或任务产物。

2. Research 必须落盘

研究结果写入当前 task 的 research/,让 Implement 和 Check 获得稳定上下文,而不是只依赖 Main 会话的聊天记忆。

3. Check 保持独立

检查不仅跑 lint/typecheck/test,还应对照 PRD、Design、Spec 与 diff,识别遗漏并在有边界的循环中 self-fix。

4. 控制上下文上限

0.6.9 起默认限制单文件 32 KiB、单 artifact 64 KiB、总注入 128 KiB;超出时降级为截断或索引,二进制不内联。[6]

5. 保留单轮逃生通道

no-trellis 默认可跳过该轮 workflow-state 注入。它适合简单解释或临时问题,但不是长期关闭工作流的替代品。

6. 利用新任务生命周期

task.py rename 会同步目录、task identity、父子引用与 JSONL;start 记录分支元数据,archive 校验,适合多分支与 worktree。

7. 用 ablate/restore 做对照

trellis ablate 可逆移除 Trellis 管理文件,trellis restore 恢复,适合评估“有/无 Trellis”的实际收益。

8. 把 dry-run 当作需防护的分析

v0.6.16 的 dry-run 可能改写模板哈希。执行前后比较 SHA-256、大小和 mtime;人工定制应解释、合并、保留,而不是为了“显示已更新”就强推模板。

9. 先定位真实项目边界

聚合目录、monorepo 和嵌套仓库不能只看当前路径。先确认 Git 根、Trellis 项目根、CLI 实际路径及平台目录,再决定在哪一级升级和验证。

高级附录:Sub Agent 编排防错门禁

仅在多个 Agent 共同决定同一交付、共享外部目标写入或前置研究存在依赖时启用。普通升级、小修复和单 Agent 任务无需展开这一套协调层。

展开高级编排规范与可复制模板
核心问题:Sub Agent 能并行,不代表所有工作都适合并行。需求版本不一致、前置研究未裁决、多个 Agent 同时写共享目标、验收口径后置,都会把并行速度转化为返工速度。

何时启用,何时保持轻量

命中任一条件就启用

  • 两个及以上 Agent 的输出共同决定同一交付。
  • 要写入飞书、浏览器后台、共享表格、数据库或环境配置。
  • 用户在已批准计划后改变领域、对象、数量、风险或验收口径。
  • 涉及可计数媒体、逐项迁移、语义映射、去重或保护用户外部编辑。
  • Agent 结论可能互斥,或某项研究是后续实施的前置条件。

以下场景不启用完整记录

  • 一次纯只读调研。
  • 单 Agent 的小范围修改。
  • 文件或模块完全独立的并行实现。
  • 常规“实现后独立检查”。

这些场景仍遵守任务工件、文件所有权和验收流程,但不增加额外审批。

主 Agent 是唯一协调责任人

主 Agent 负责收敛最新需求、判定前置依赖、记录冲突裁决、分配写入权并确认最终验收。不能把多个 Agent 的建议简单拼接,也不能用多数投票替代用户的业务决定。

需求快照
基线与保护项
工作拆分
所有权与依赖
前置研究
并行但只读
Barrier
全部返回
主 Agent 裁决
更新任务工件
实施与回读
单写入者
独立验证
机器 + 语义

唯一事实源与冲突优先级

任务工件是协调事实源;聊天记录、继承上下文和 Agent 建议只作为补充证据。发生冲突时按以下顺序处理:

最新用户明确意图
> 当前目标事实与用户已作的外部编辑
> 本轮已批准的 PRD / Design
> 旧任务约束与旧验收
> 参考材料
> Agent 建议
范围变化必须落盘:写清“保留什么、废止什么、采用什么及原因”。如果仍属于用户尚未明确的业务选择,应说明方案及影响并请求决定;如果用户已经明确,不重复制造确认环节。

可复制的协调决策记录

命中门禁时,将模板放入当前任务的 design.md,或新增 research/orchestration-decision-record.md。两者任选其一,不新增强制 Schema。

## 协调决策记录

### 1. 最新需求快照
- 记录时间:
- 用户明确意图(原话或可追溯摘要):
- 当前交付物与边界:

### 2. 当前基线与保护项
- 目标、revision / ETag / 版本 / 时间或其他定位符:
- 允许修改范围:
- 必须保留的用户外部编辑、数据或接口行为:
- 事实来源与适用环境:

### 3. 约束裁决
| 旧约束或候选方案 | 状态(保留/废止/待用户决定) | 采用依据与受影响断言 |
| --- | --- | --- |
|  |  |  |

### 4. Agent 工作表与依赖
| Agent/角色 | 唯一问题 | 输入 | 输出格式 | 读写边界/所有权 | 前置依赖 | 完成信号 | 禁止事项 |
| --- | --- | --- | --- | --- | --- | --- | --- |
|  |  |  |  |  |  |  |  |

### 5. 主 Agent 裁决
| 前置研究或冲突项 | 结论 | 裁决(采纳/不采纳/待用户决定) | 理由 | 对 PRD/Design/验收的更新 |
| --- | --- | --- | --- | --- |
|  |  |  |  |  |

### 6. 实施前验收断言
| 类型 | 断言 | 证据或回读方式 |
| --- | --- | --- |
| 机器可查 |  |  |
| 人工语义 |  |  |

委派契约与研究 Barrier

  1. 每个 Sub Agent 只回答一个可验证的问题,并明确输入、输出格式、读写范围、文件或模块所有权、前置依赖、完成信号和禁止事项。
  2. Research Agent 默认只读,结果写入当前任务的 research/<topic>.md,不得悄悄改变范围、代码或共享外部目标。
  3. 把会影响实施的研究标为“前置”;所有前置研究必须全部返回。
  4. 主 Agent 对每项结论记录“采纳 / 不采纳 / 待用户决定”,并同步更新 PRD、Design 与验收断言。
  5. 上述裁决完成前,不得派发实施工作,也不得修改代码或外部可变目标。
  6. 实施中新事实若改变领域、目标、精确数量、破坏性风险、用户编辑保护或验收口径,立即退回裁决阶段。

implement.jsonlcheck.jsonl 只负责注入相关规范和研究材料,不承载依赖图、唯一写入者或裁决状态。

并行边界与共享目标单一写入者

对象 允许的并行方式 强制保护
代码与本地文件 按独占文件或模块并行;重叠文件、同一生成物、不可分割契约串行移交。 交接前重读最新文件;发现他人修改或格式化结果后,不在旧快照上继续编辑。
飞书、后台、共享表格 默认仅一名指定写入者,通常由主 Agent 操作;Research 与 Verify 只读。 写前核对 revision、block ID、保护项和允许范围;写后立即回读。
数据库与环境配置 默认单一写入者;只有用户明确授权且可安全分区时才允许互斥区域并行。 记录分区、合并方式和回滚点;不得扩大记录数、环境或 API 动作范围。
旧定位不可复用:revision、ETag、block ID、版本号或页面状态变化后,旧定位立即失效,必须重新读取。

验收必须在实施前定义

机器可查断言

文件或资源数量、唯一性、编号连续性、指定字段、去重结果、保护块、测试或类型检查、敏感信息扫描。

人工语义断言

页面是否为同一对象、字段和按钮是否属于正确模块、事实是否标明环境范围、读者是否会误解能力或风险边界。

可计数内容、外部编辑保护、事实适用环境、禁止的语义串线、风险动作边界以及最终回读证据,都应在实施前进入断言表。独立 Check/Verify 失败时,要区分“实现没满足断言”和“PRD/协调记录已经失效”;后者必须回到裁决。

场景判断

场景 是否启用 正确处理 典型错误
两份研究分别建议最小迁移和完整迁移 启用 收齐研究,由主 Agent 裁决并更新数量断言后再实施。 让两个 Agent 按各自假设继续写,最后强行拼接。
多 Agent 修改互不重叠的本地模块 通常不启用 列清文件所有权,按原有实现与检查流程完成。 只因用了多个 Agent 就增加多轮审批。
整合用户正在编辑的共享文档 启用 指定单一写入者,刷新版本和保护项,局部写入后回读。 多个 Agent 复用旧定位并发整篇替换。
单 Agent 修改一个已验证的本地文案 不启用 按普通小任务直接修改和验证。 创建冗长依赖图,流程成本超过修改本身。
把名称相似页面的字段互相迁移 启用 先验证业务对象是否相同,记录不能硬映射的反例。 因名称相似而混写字段、按钮和数值限制。

最终检查清单

  • 已判断是否命中门禁;未命中时没有引入多余流程。
  • 最新需求、当前基线、保护项和废止约束有可追溯记录。
  • 每个 Agent 的唯一问题、所有权、依赖、读写边界和完成信号明确。
  • 所有前置研究已返回,主 Agent 已逐项裁决并更新任务工件。
  • 本地并行没有重叠文件;共享外部目标只有指定写入者或明确互斥分区。
  • 外部写入执行写前重读、写后回读,定位变化后未复用旧定位。
  • 机器断言与人工语义断言已在实施前定义,并由独立验证覆盖。
  • 新事实改变范围或验收时已回到裁决,而不是在旧计划上继续叠加。

附录:可直接发送给 AI 的自动配置提示词

主流程读者无需阅读整段提示词。需要让 AI 审计或修改项目配置时再展开;它包含 v0.6.16 dry-run 防护、按需确认、精确版本锁定和 Claude Code + GLM-5.3 系列隔离规则。

展开并复制完整提示词
约束重点:按需确认、版本锁定、保护定制、零密钥、可验证。
请作为“项目内 Trellis 配置审计与升级助手”,检查并优化当前仓库的 Trellis 配置。

适用场景:
- 项目刚执行完 `trellis init`;或
- 项目已经使用 Trellis 一段时间,存在 task、spec、journal、workflow、自定义 Agent 或多人协作配置。

总原则:先定位真实项目边界并执行受保护检测;无需修改时直接报告。确需修改但我尚未明确模式或模型方案时再按需询问,最多两次;已明确的选择不得重复询问。兼容现有项目、保留人工定制、禁止覆盖个人全局模型与密钥配置。

【0. 执行边界】
1. 先确定真实 Git 根、Trellis 项目根、当前 shell 实际调用的 CLI 路径、本地 CLI 版本和项目模板版本,不要凭当前目录或记忆使用配置项。
2. 以当前仓库实际版本为准,检查该版本模板、CLI 帮助和已有文件;文档与本地模板冲突时,以版本锁定的本地模板/对应 Git tag 为准。
3. 在第一次和第二次选择完成前,不得修改任何文件。
4. 不修改业务代码;仅在验证 Trellis 配置确有必要时执行最小范围检查。根据操作系统选择 macOS/Linux 或 PowerShell 命令,不得把 POSIX 命令直接交给 PowerShell。
5. 不执行 `trellis update -f`、删除任务、清空 spec、重建 workflow 或覆盖人工文件,除非我后续明确批准。
6. 不提交代码、不推送远程、不修改 Git 历史。

【1. 受保护检测】
请检查并汇总:
- `git rev-parse --show-toplevel` 与 Trellis 项目根;聚合目录、多仓库和嵌套仓库必须分别说明;
- `command -v trellis` 或 PowerShell `Get-Command trellis`(实际 CLI 路径);
- `trellis --version`(本地 CLI 版本);
- `.trellis/.version`(项目模板版本);
- 运行 `trellis update --dry-run` 前,记录 `.trellis/.template-hashes.json` 的 SHA-256、大小和 mtime;
- 运行 dry-run 后立即再次记录三项元数据并比较。v0.6.16 在 orphan manifest key 场景可能改写该文件,即使输出声称没有修改;若变化,停止后续操作、报告 diff,并从已确认基线恢复;
- 当前版本支持时,执行 `trellis platforms --json`;
- `.trellis/config.yaml`;
- `.trellis/workflow.md`;
- `.trellis/.template-hashes.json`;
- `.trellis/spec/`、`.trellis/tasks/`、`.trellis/workspace/`;
- `.codex/agents/trellis-*.toml`;
- `.claude/agents/`、`.claude/skills/`、`.claude/commands/`、`.claude/hooks*`;
- `.agents/` 以及当前项目实际存在的其他平台目录;
- Git 工作区是否干净;
- 是否存在旧路径、待迁移文件、模板漂移、手工改动、失效 hook、空 context manifest、模型被项目级硬编码等问题。

对于 Codex,再检测并报告:
- 当前 `codex.dispatch_mode`;
- 当前版本中 `inline`、`auto`、`sub-agent` 的真实语义和默认值;
- `trellis-research`、`trellis-implement`、`trellis-check` 是否存在;
- Agent TOML 是否固定了 `model` / `model_reasoning_effort`;
- Codex hooks 是否可用。若需要用户级 `~/.codex/config.toml` 或一次性 `/hooks` 授权,只报告,不要替我修改全局文件。

请先输出一份精简检测报告,至少包括:
1. CLI 版本与项目模板版本;
2. 已检测到的 AI 平台;
3. 更新或迁移需求;
4. 当前 dispatch 模式;
5. 自定义文件与潜在覆盖风险;
6. 明显缺失、错误或可优化项;
7. 你建议继续采用 Inline 还是 Sub-agent,以及理由,但不要代替我选择。

【2. 按需确认 Codex 执行模式】
仅当检测表明确实需要修改 dispatch、且我此前尚未选择时,停下来让我选择:

A. Inline 模式
- Research、Implement、Check 主要由 Codex 主会话完成;
- 优先上下文连续性、启动速度和较低的总 Token 消耗;
- 适合小型/中型需求、单模块修改、Bug 修复、简单重构;
- 缺点是主会话上下文增长更快,且“自己实现、自己审查”的独立性较弱。

B. Sub-agent 模式(概念名称)
- Main 负责需求理解、PRD、Design、Implement Plan、任务拆分和最终验收;
- `trellis-research`、`trellis-implement`、`trellis-check` 分别负责研究、实现、独立检查;
- 优先上下文隔离、独立 Review、复杂任务稳定性;
- 适合跨模块、多文件、架构调整、高风险修改;
- 总 Token 可能更高,因为多个 Agent 会重复加载结构化上下文。

版本映射规则:
- Trellis 0.6.0 / 0.6.5:通常使用 `inline` 或 `sub-agent`,默认模板为 `inline`;
- Trellis 0.6.8 及之后(包括 0.6.16):原生子代理模式应写为 `auto`,`sub-agent` 只是向后兼容别名,默认模板为 `auto`;
- 因此用户选择“B. Sub-agent”后,应根据本地版本写入真正受支持的值,0.6.16 优先写 `auto`,不要机械写旧别名。
- `codex.dispatch_mode` 是 Codex 专属配置,其他平台应忽略,不得影响 Claude Code。

若满足上述询问条件,在我回复 A 或 B 前必须停止;若我已经明确选择,直接复用;若无需修改,报告后结束。

【3. 如果选择 A:Inline 配置】
我选择 A 后:
- 按本地 Trellis 版本,把 Codex dispatch 设置为 `inline`;
- 不删除 Codex 的 Trellis Agent 文件,以便将来切换;
- 不把 Codex 子代理模型配置当作当前工作流的必要依赖;
- 检查 workflow、spec、task lifecycle、journal、context 注入与 skip keyword;
- 仅做安全、必要、非破坏性调整;
- 保持 Claude Code + GLM-5.3 系列完全兼容。

【4. 如果选择 B:按需确认三套 Sub-agent 方案】
我选择 B 且此前未明确模型方案时,先不要修改配置;展示下面三套方案的质量、速度、额度消耗和适用场景,然后停下来让我选择 1 / 2 / 3。若我已明确方案,直接复用,不重复询问。

方案 1:质量优先
- Main:GPT-5.6 Sol / high 或 xhigh
- Research:GPT-5.6 Terra / high
- Implement:GPT-5.6 Sol / high
- Check:GPT-5.6 Sol / high 或 xhigh
- 适合:核心业务、复杂架构、大规模重构、支付/权限/数据迁移等高风险任务。
- `max` 不作为默认值,只在极复杂问题且当前客户端支持时使用。

方案 2:均衡方案(默认推荐)
- Main:GPT-5.6 Sol / high
- Research:GPT-5.6 Terra / medium
- Implement:GPT-5.6 Terra / high
- Check:GPT-5.6 Sol / high
- 适合:绝大多数真实项目、长期日常开发、中大型 Feature 和普通重构。
- 原则:最强模型用于规划与质量门禁,均衡模型承担检索和大量实现工作。

方案 3:额度/速度优先
- Main:GPT-5.6 Sol / high
- Research:GPT-5.6 Luna / medium
- Implement:GPT-5.6 Terra / medium
- Check:GPT-5.6 Terra / high
- 适合:规范成熟、PRD/Design 清晰、CRUD 和重复性开发较多的项目。

模型可用性规则:
- 上述是 Codex 推荐映射,不是 Trellis 官方强制默认。
- 先检查当前 Codex 客户端/账号实际可用模型与 reasoning 档位;不可用时,不得编造模型 ID,应说明并给出“继承 Main 模型”或当前可用模型的等价替代方案。
- Main 模型通常由 Codex 会话或用户级配置决定,不要假装能仅靠 `.trellis/config.yaml` 设置 Main。

仅在方案仍未明确时,必须等我选择 1 / 2 / 3 后才能改文件。

【5. Claude Code + GLM-5.3 系列共存规则】
这是多人协作仓库,部分同事仍使用 Claude Code + GLM-5.3 系列。具体模型 ID 以成员当前配置为准,不得把家族名当作固定模型值。必须遵守:
- 不修改 `~/.claude/settings.json`;
- 不修改 `ANTHROPIC_BASE_URL`;
- 不修改 `ANTHROPIC_AUTH_TOKEN`、API Key 或任何密钥;
- 不修改 `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL`;
- 不覆盖同事已有 Provider、GLM Coding Plan、Endpoint、模型映射和 reasoning 设置;
- 不把 GPT 模型名称写入 `.claude/agents/`;
- 不在 Git 仓库提交个人 API 地址、密钥或用户级模型映射;
- Claude Code 的 Trellis Agent 默认继承每位成员自己的 Claude Code/GLM 环境;
- 已有人为修改的 `.claude/` 文件必须保留,说明其作用并仅在必要时给出 diff 建议;
- Codex 的 `dispatch_mode` 和 `.codex/agents/*.toml` 调整不得波及 Claude Code。

【6. 获得全部确认后的实际修改规则】
1. 只修改当前 Trellis 版本确实支持的项目级配置。
2. Trellis 0.6.8+ 的 Sub-agent 概念模式优先写:
   `codex.dispatch_mode: auto`
   Inline 写:
   `codex.dispatch_mode: inline`
3. 如果当前版本没有 `.trellis/config.yaml` 的 per-agent model 配置能力,则只在以下文件中设置 Codex 子代理模型:
   - `.codex/agents/trellis-research.toml`
   - `.codex/agents/trellis-implement.toml`
   - `.codex/agents/trellis-check.toml`
4. 修改 Agent TOML 时仅调整必要的 `model` 和 `model_reasoning_effort`;保留原有 name、description、sandbox、developer instructions、上下文加载和递归保护。
5. 不创建不存在且未被当前版本支持的 YAML 字段。
6. 复杂任务必须为 `implement.jsonl` / `check.jsonl` 写入真实、精选的 spec、research 和 task context;不得用无意义占位行绕过校验。
7. Research 结论写入当前 task 的 `research/`,不要只留在聊天记录。
8. Check 作为独立质量门禁,至少验证:
   - PRD / Acceptance Criteria 覆盖;
   - Design 一致性;
   - `.trellis/spec/` 合规;
   - diff 完整性;
   - lint、typecheck、tests(项目存在时);
   - 边界条件、错误处理、状态一致性和回归风险。
9. 保留小任务逃生通道:简单、单轮可理解和验证的修改可不创建完整 Trellis task;用户明确说“直接 inline”“不用 sub-agent”“本轮不走 Trellis”时,按当前 workflow 的安全边界处理。
10. 若发现模板文件有人工修改,先解释差异;必要时备份或只提供补丁,不得直接覆盖。

【7. 验证】
修改后执行适合当前版本的验证:
- 重新读取 `.trellis/config.yaml`;
- 检查三个 Codex Agent TOML;
- 受保护地执行 `trellis update --dry-run`,并比较模板哈希文件前后的 SHA-256、大小和 mtime;
- 当前版本支持时执行 `trellis platforms --json`;
- 检查 `git status --short`;
- 输出 `git diff -- .trellis .codex .claude .agents` 的核心摘要;
- 确认没有密钥、个人 Endpoint、用户级配置进入 Git diff;
- 确认 Claude Code + GLM-5.3 系列配置未被修改;
- 确认 Trellis 自定义文件没有被无意覆盖。

【8. 最终报告】
请报告:
- 修改了哪些文件;
- 每项修改的原因;
- 最终 CLI 和项目模板版本;
- 最终 Codex dispatch mode(并说明实际写入值);
- Main / Research / Implement / Check 的模型与 reasoning;
- 哪些角色继承 Main;
- Claude Code 是否兼容;
- GLM-5.3 系列的具体模型映射、Provider、API 配置是否保持不变;
- workflow、context manifest、research persistence、independent check 是否正常;
- 发现的旧版本遗留项和迁移项;
- 未来执行 `trellis update` 时需要注意的自定义文件;
- 核心 Git diff 摘要;
- 尚未解决的风险。

如果检测后发现当前配置已经合理,不要为了“完成任务”强行改文件,直接说明无需修改。

严格按以下状态机执行:
只读定位与受保护检测 → 输出报告 → 无需修改则结束 → 复用我已明确的选择;仍缺少必要选择时才询问模式/方案 → 修改 → 验证 → 汇报。

最终验证清单

版本与模板

  • Git 根、Trellis 项目根和 CLI 实际路径已经明确。
  • trellis --version.trellis/.version 都精确为 0.6.16。
  • 受保护的 trellis update --dry-run 前后哈希一致,或变化已解释并恢复。
  • 若发生迁移,旧路径已处理且无重复模板。

Codex

  • 0.6.16 的子代理模式写为 auto
  • Inline 模式写为 inline
  • Agent TOML 模型字段符合所选方案。
  • 未破坏 sandbox、instructions、递归保护。

上下文与工作流

  • 复杂任务的 manifest 有真实 curated entries。
  • Research 结论落在 task/research。
  • Implement 能读取 PRD / Design / Plan / Spec。
  • Check 能独立验证并运行项目测试命令。

Sub Agent 编排门禁

  • 命中高风险条件时已建立唯一需求与决策快照。
  • 前置研究已全部返回并由主 Agent 逐项裁决。
  • 代码所有权互斥,共享外部目标使用单一写入者。
  • 机器断言、人工语义断言及写后回读已前置。

Claude Code + GLM-5.3 系列

  • ~/.claude/settings.json 未被改动。
  • Provider、Endpoint、Token、模型映射未进入 diff。
  • .claude/ 没有被写入 GPT 模型 ID。
  • Claude Trellis Agent 仍继承用户环境。

Git 与团队

  • 模板升级 diff 与业务代码 diff 分开。
  • 人工配置都有解释或明确保留。
  • 没有真实密钥或个人路径。
  • 团队 README 记录模式和升级注意项。

结果报告

  • 列出修改文件与原因。
  • 列出最终 dispatch 与模型方案。
  • 列出验证命令及结果。
  • 列出未解决风险与未来 update 注意项。

常见问题与排查

配置写了 Sub-agent,但 0.6.16 没按预期工作

先把概念与配置值分开:0.6.16 推荐写 dispatch_mode: auto。检查本地版本、对应 tag 模板、Codex hooks 与 Agent 文件是否齐全。sub-agent 虽是兼容别名,但新配置不应继续传播旧值。

子代理仍继承 Main 的昂贵模型

确认三个 .codex/agents/trellis-*.toml 中存在未注释的 modelmodel_reasoning_effort。0.6.9+ 未固定时会继承 Main;固定值应在 update 后保留。

task.py start 提示空 context manifest

这是 0.6.16 的质量门禁,不应绕过。为 implement.jsonl / check.jsonl 添加与任务真正相关的 spec、research、代码或任务产物。仅在平台本来没有子代理、或经过明确评估的特殊情况才考虑 --allow-empty-context

trellis update 显示文件被修改,无法自动更新

查看 Git diff 和 .trellis/.template-hashes.json,判断修改是团队定制还是偶然漂移。优先手工合并新模板变化,不要直接 -f 覆盖。

dry-run 声称没有修改,但模板哈希文件发生变化

这是 v0.6.16 的已知实现风险:orphan manifest key 清理可能被持久化。立即停止后续 update/migrate,保存 diff,核对升级前 SHA-256、大小和 mtime,并仅从已确认的 Git 基线或备份恢复该文件。不要把“No changes made”当作只读证明。[10]

Codex Hook 没有注入 Trellis 上下文

检查当前 Codex 是否启用 hooks、项目是否受信任,以及是否完成一次性 hooks 授权。用户级配置只应由成员本人确认修改;项目内 AI 应检测和报告,不要静默改 ~/.codex/config.toml

升级后 Claude Code + GLM-5.3 系列不能用了

先对比 .claude/ 和用户级 ~/.claude/settings.json。Trellis 项目升级不应重写用户 Provider/Token;若项目文件写入 GPT 模型或覆盖自定义 Claude Agent,应回退并恢复平台隔离。具体 GLM 模型 ID 以成员当前配置为准。

Auto 模式是不是所有小修改都必须开三个 Agent?

不是。Trellis 当前工作流允许把一个回合就能理解和验证的修改归为 Inline small task,甚至不创建完整 task。Auto 更适合正式、复杂、有持久规划价值的任务。

多个 Sub Agent 的研究结论冲突,应该直接投票吗?

不能。先等待所有被标记为前置的研究返回,再由主 Agent 对每项结论记录“采纳 / 不采纳 / 待用户决定”,同步更新 PRD、Design 和验收断言。仍属于用户业务选择的事项必须交给用户决定,不能用 Agent 多数意见替代。

多个 Agent 能否同时修改飞书或后台配置?

默认不能。共享外部目标应指定单一写入者,其他 Agent 只读研究或独立验收;只有用户明确授权、目标可以安全划分互斥区域且已记录合并方式时,才允许分区并行。每次写入都要写前重读、写后回读。

官方来源与核验基线

版本行为优先采用对应版本的官方 changelog 与 Git tag 模板;滚动文档与版本锁定模板冲突时,以本地版本/对应 tag 为准。

  1. Trellis v0.6.0 Changelogdocs.trytrellis.app/changelog/v0.6.0
  2. Trellis v0.6.5 Changelogdocs.trytrellis.app/changelog/v0.6.5
  3. Trellis v0.6.16 Changelogdocs.trytrellis.app/changelog/v0.6.16
  4. v0.6.16 版本锁定 config.yaml 模板GitHub raw / v0.6.16 / config.yaml
  5. Trellis Commands, Upgrades, Tasks & Specsdocs.trytrellis.app/start/everyday-use
  6. Trellis v0.6.9 Changelog(上下文上限、skip keyword、Codex 模型配置持久化)— docs.trytrellis.app/changelog/v0.6.9
  7. Trellis v0.6.8 Changelog(Codex 原生 Sub-agent dispatch)— docs.trytrellis.app/changelog/v0.6.8
  8. OpenAI Models(Sol / Terra / Luna 定位与 reasoning 档位)— developers.openai.com/api/docs/models
  9. Z.AI Claude Code Guide(Claude Code 的 GLM Provider 与用户级配置)— docs.z.ai/devpack/tool/claude
  10. Trellis v0.6.16 dry-run 实现核验update.ts 调用位置manifest-prune.ts 默认持久化逻辑
  11. 旧版本模板对照v0.6.5 config.yamlv0.6.8 config.yaml
范围说明:模型方案属于基于官方模型定位与 Trellis Agent 职责做出的工程推荐;并非 Trellis 官方唯一配置。项目实际可用模型、额度和客户端支持可能不同,应在自动配置阶段先检测。