v0.6.0:架构基线
以 trellis channel 多 Agent 协作为头部能力,补齐
trellis mem、Core
SDK、任务规划产物与多平台工作流。官方当时列出 15
个支持平台。[1]
ChannelMemoryPRD/Design/Implement
一份版本锁定、可回滚的执行指南:先识别真实项目边界和版本,再升级 CLI、受保护地分析项目差异、同步模板并验证。Codex 模式、模型分层、Claude Code + GLM-5.3 系列共存和高级编排规范作为按需配置。
新项目与旧项目的推荐目标版本。
0.6.8+ 的原生 Codex 子代理模式;0.6.16 默认模板值。
仅在确需修改且选择尚未明确时,确认模式与模型方案。
先确认 Git 根与干净基线,保护 task、spec、人工模板和个人配置。
0.6.16;复杂任务采用 auto +
均衡模型方案,小任务直接 Inline 或不创建完整 Trellis task;Claude
Code + GLM-5.3 系列保持用户环境继承,不在仓库中写入密钥、Endpoint
或个人模型映射。
auto。它会派发
trellis-research、trellis-implement、trellis-check;sub-agent
只是
auto 的兼容别名。只有希望实现与检查都留在主会话时才写
inline。[4]
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 的版本锁定模板”,不能只看未锁定版本的页面。
本指南答案:是。所有主路径命令都固定到
0.6.16;如果你有意跟随 latest,应先重新核验
changelog、模板和本页结论。
结论:不是二选一的永久宗教。小任务 Inline
更快、总 Token 通常更低;复杂多模块任务用
Auto/Sub-agent,可隔离上下文并获得独立 Review。0.6.16
的配置值应优先使用 auto,而不是旧写法
sub-agent。
结论:最强模型应放在“高杠杆判断”上:Main 做规划,Check 做质量门禁;Research 与大量 Implement 可用更均衡的模型。默认推荐 Sol / Terra 混合,而不是所有角色都使用最贵模型。
结论:先检测;无需修改时直接报告。确需修改但模式或模型方案尚未明确时才询问,最多两次。用户已经明确选择时不重复确认,同时将 Claude Code + GLM-5.3 系列视为独立用户环境。
以 trellis channel 多 Agent 协作为头部能力,补齐
trellis mem、Core
SDK、任务规划产物与多平台工作流。官方当时列出 15
个支持平台。[1]
ChannelMemoryPRD/Design/Implement
新增 Trae,修复 Pi 启动上下文与子代理工具,改善 Windows channel,并收紧 hook 与 planning gate。它的价值更多是“从能用到可靠”,不是第二次架构重写。[2]
TraePiWindowsPlanning Gate
引入 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 根
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
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
# 先查看将执行的 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。
.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
update --dry-run
前后哈希一致,或所有变更都已明确解释并恢复。
update、--migrate 或
-f,保存终端输出和当前 diff。
npm install -g @mindfoldhq/trellis@0.6.16,再核对
command -v trellis 与
trellis --version。
| 起点 → 目标 | 建议动作 | 说明 |
|---|---|---|
| 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。
同一个 Main Codex 完成理解、实现、检查。
上下文连续启动快总 Token 通常较低
代价:主会话膨胀更快;Review 不够独立;长需求更容易受 compaction 影响。
Main 做 Tech Lead,Research / Implement / Check 隔离执行。
上下文隔离独立 Review适合复杂任务
代价:有调度与重复加载开销,总 Token 可能更高,且依赖结构化任务上下文质量。
| 决策信号 | 优先 Inline | 优先 Auto/Sub-agent |
|---|---|---|
| 任务边界 | 问题局部、输入完整、一个会话内可理解与验证。 | 跨模块或跨角色,前置研究会影响后续实施。 |
| 风险 | 可快速回退,不涉及关键权限、资金、数据迁移或并发一致性。 | 错误代价高,需要独立检查或多层证据。 |
| 上下文 | 材料少且连续,拆分会增加重复加载。 | 材料多、会话长,隔离上下文能降低遗漏。 |
| 协作成本 | 单一所有者即可完成,调度成本高于收益。 | 职责和读写边界可以明确拆分,输出可独立验收。 |
codex:
dispatch_mode: inline
codex:
dispatch_mode: auto
# "sub-agent" 只是兼容别名
单文件或少量文件、小 Bug、文案/CSS、简单类型错误、能在一个会话内理解与验证。
跨模块、架构变化、复杂状态,或涉及权限、支付、迁移、并发等高风险任务;重点是依赖和风险,不是机械文件数。
项目默认 auto;小任务不创建完整 Trellis
task,或明确要求本轮 Inline。不要用牛刀处理一行修改。
以下是截至 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 与重复性开发较多。 |
需求理解、架构、拆分一旦错,所有下游都会围绕错误方向工作,因此 Main 最值得使用强模型。
Review 相对短,却要识别需求遗漏、架构偏差和边界风险,使用强模型常比让 Implement 全程使用最强模型更划算。
多数工作是代码搜索、模式识别和总结,Terra/medium 通常足够;机械枚举任务可进一步降到 Luna。
在高质量 PRD / Design / Plan 已明确后,Implement 应主要执行而不是重新发明架构,均衡模型可承担大量编码。
high 是复杂工程任务的常用高质量档;xhigh
留给架构迁移、疑难 Bug、高风险设计;max
不作为日常默认,且必须确认当前 Codex 客户端确实支持。
从 0.6.9 起,用户设置的 model /
model_reasoning_effort 会在
trellis update 重新生成时保留。若不固定,子代理继承
Main 会话模型。[6]
model = "gpt-5.6-terra"
model_reasoning_effort = "medium"
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
model = "gpt-5.6-sol"
model_reasoning_effort = "high"
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。
dispatch_mode。~/.claude/settings.json。.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、映射
codex.dispatch_mode 仅影响 Codex,其他平台忽略。因此
Codex 使用 auto 不应改变 Claude Code + GLM-5.3
系列的执行环境。[4]
.claude/ 单独做 Git
diff,确保无意覆盖没有发生。
implement.jsonl /
check.jsonl 存在但没有 curated entries 时,0.6.16
的 validate 会失败,start 会拒绝执行,除非显式使用
--allow-empty-context。[3]
不要填无意义占位行绕过门禁;应引用真正相关的 spec、research、源文件或任务产物。
研究结果写入当前 task 的 research/,让 Implement
和 Check 获得稳定上下文,而不是只依赖 Main 会话的聊天记忆。
检查不仅跑 lint/typecheck/test,还应对照 PRD、Design、Spec 与 diff,识别遗漏并在有边界的循环中 self-fix。
0.6.9 起默认限制单文件 32 KiB、单 artifact 64 KiB、总注入 128 KiB;超出时降级为截断或索引,二进制不内联。[6]
no-trellis 默认可跳过该轮 workflow-state
注入。它适合简单解释或临时问题,但不是长期关闭工作流的替代品。
task.py rename 会同步目录、task
identity、父子引用与 JSONL;start 记录分支元数据,archive
校验,适合多分支与 worktree。
trellis ablate 可逆移除 Trellis 管理文件,trellis restore
恢复,适合评估“有/无 Trellis”的实际收益。
v0.6.16 的 dry-run 可能改写模板哈希。执行前后比较 SHA-256、大小和 mtime;人工定制应解释、合并、保留,而不是为了“显示已更新”就强推模板。
聚合目录、monorepo 和嵌套仓库不能只看当前路径。先确认 Git 根、Trellis 项目根、CLI 实际路径及平台目录,再决定在哪一级升级和验证。
仅在多个 Agent 共同决定同一交付、共享外部目标写入或前置研究存在依赖时启用。普通升级、小修复和单 Agent 任务无需展开这一套协调层。
这些场景仍遵守任务工件、文件所有权和验收流程,但不增加额外审批。
主 Agent 负责收敛最新需求、判定前置依赖、记录冲突裁决、分配写入权并确认最终验收。不能把多个 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. 实施前验收断言
| 类型 | 断言 | 证据或回读方式 |
| --- | --- | --- |
| 机器可查 | | |
| 人工语义 | | |
research/<topic>.md,不得悄悄改变范围、代码或共享外部目标。
implement.jsonl 与
check.jsonl
只负责注入相关规范和研究材料,不承载依赖图、唯一写入者或裁决状态。
| 对象 | 允许的并行方式 | 强制保护 |
|---|---|---|
| 代码与本地文件 | 按独占文件或模块并行;重叠文件、同一生成物、不可分割契约串行移交。 | 交接前重读最新文件;发现他人修改或格式化结果后,不在旧快照上继续编辑。 |
| 飞书、后台、共享表格 | 默认仅一名指定写入者,通常由主 Agent 操作;Research 与 Verify 只读。 | 写前核对 revision、block ID、保护项和允许范围;写后立即回读。 |
| 数据库与环境配置 | 默认单一写入者;只有用户明确授权且可安全分区时才允许互斥区域并行。 | 记录分区、合并方式和回滚点;不得扩大记录数、环境或 API 动作范围。 |
文件或资源数量、唯一性、编号连续性、指定字段、去重结果、保护块、测试或类型检查、敏感信息扫描。
页面是否为同一对象、字段和按钮是否属于正确模块、事实是否标明环境范围、读者是否会误解能力或风险边界。
可计数内容、外部编辑保护、事实适用环境、禁止的语义串线、风险动作边界以及最终回读证据,都应在实施前进入断言表。独立 Check/Verify 失败时,要区分“实现没满足断言”和“PRD/协调记录已经失效”;后者必须回到裁决。
| 场景 | 是否启用 | 正确处理 | 典型错误 |
|---|---|---|---|
| 两份研究分别建议最小迁移和完整迁移 | 启用 | 收齐研究,由主 Agent 裁决并更新数量断言后再实施。 | 让两个 Agent 按各自假设继续写,最后强行拼接。 |
| 多 Agent 修改互不重叠的本地模块 | 通常不启用 | 列清文件所有权,按原有实现与检查流程完成。 | 只因用了多个 Agent 就增加多轮审批。 |
| 整合用户正在编辑的共享文档 | 启用 | 指定单一写入者,刷新版本和保护项,局部写入后回读。 | 多个 Agent 复用旧定位并发整篇替换。 |
| 单 Agent 修改一个已验证的本地文案 | 不启用 | 按普通小任务直接修改和验证。 | 创建冗长依赖图,流程成本超过修改本身。 |
| 把名称相似页面的字段互相迁移 | 启用 | 先验证业务对象是否相同,记录不能硬映射的反例。 | 因名称相似而混写字段、按钮和数值限制。 |
主流程读者无需阅读整段提示词。需要让 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 摘要;
- 尚未解决的风险。
如果检测后发现当前配置已经合理,不要为了“完成任务”强行改文件,直接说明无需修改。
严格按以下状态机执行:
只读定位与受保护检测 → 输出报告 → 无需修改则结束 → 复用我已明确的选择;仍缺少必要选择时才询问模式/方案 → 修改 → 验证 → 汇报。
trellis --version 与
.trellis/.version 都精确为 0.6.16。
trellis update --dry-run
前后哈希一致,或变化已解释并恢复。
auto。inline。~/.claude/settings.json 未被改动。.claude/ 没有被写入 GPT 模型 ID。
先把概念与配置值分开:0.6.16 推荐写
dispatch_mode: auto。检查本地版本、对应 tag
模板、Codex hooks 与 Agent 文件是否齐全。sub-agent
虽是兼容别名,但新配置不应继续传播旧值。
确认三个
.codex/agents/trellis-*.toml 中存在未注释的
model 与
model_reasoning_effort。0.6.9+ 未固定时会继承
Main;固定值应在 update 后保留。
这是 0.6.16 的质量门禁,不应绕过。为
implement.jsonl /
check.jsonl 添加与任务真正相关的
spec、research、代码或任务产物。仅在平台本来没有子代理、或经过明确评估的特殊情况才考虑
--allow-empty-context。
查看 Git diff 和
.trellis/.template-hashes.json,判断修改是团队定制还是偶然漂移。优先手工合并新模板变化,不要直接
-f 覆盖。
这是 v0.6.16 的已知实现风险:orphan manifest key 清理可能被持久化。立即停止后续 update/migrate,保存 diff,核对升级前 SHA-256、大小和 mtime,并仅从已确认的 Git 基线或备份恢复该文件。不要把“No changes made”当作只读证明。[10]
检查当前 Codex 是否启用
hooks、项目是否受信任,以及是否完成一次性 hooks
授权。用户级配置只应由成员本人确认修改;项目内 AI
应检测和报告,不要静默改 ~/.codex/config.toml。
先对比 .claude/ 和用户级
~/.claude/settings.json。Trellis
项目升级不应重写用户 Provider/Token;若项目文件写入 GPT
模型或覆盖自定义 Claude Agent,应回退并恢复平台隔离。具体 GLM
模型 ID 以成员当前配置为准。
不是。Trellis 当前工作流允许把一个回合就能理解和验证的修改归为 Inline small task,甚至不创建完整 task。Auto 更适合正式、复杂、有持久规划价值的任务。
不能。先等待所有被标记为前置的研究返回,再由主 Agent 对每项结论记录“采纳 / 不采纳 / 待用户决定”,同步更新 PRD、Design 和验收断言。仍属于用户业务选择的事项必须交给用户决定,不能用 Agent 多数意见替代。
默认不能。共享外部目标应指定单一写入者,其他 Agent 只读研究或独立验收;只有用户明确授权、目标可以安全划分互斥区域且已记录合并方式时,才允许分区并行。每次写入都要写前重读、写后回读。
版本行为优先采用对应版本的官方 changelog 与 Git tag 模板;滚动文档与版本锁定模板冲突时,以本地版本/对应 tag 为准。