跳转到主要内容

​
架构全景

​
4.1 整体架构



​
4.2 会话启动流程


这两个平台的 Hook 系统在会话开始时自动触发 session-start.py，无需手动输入 /start。
用户打开终端即可直接描述任务。可选运行 /start 获取更详细的上下文报告。

当你输入 /start 时（或 Claude Code Hook 自动触发时），背后发生了什么：


session-start.py 是一个 SessionStart Hook，在每次新会话开始时自动触发，确保 AI 总是带着完整上下文开始工作。

​
4.3 规范注入机制


规范自动注入是 Claude Code 的专属功能，依赖 Hook 系统（PreToolUse 拦截 Task 工具调用）。
Cursor、Codex、OpenCode 等平台需要通过命令手动加载规范（如 /before-backend-dev）。

inject-subagent-context.py 是 Trellis 的核心引擎。当主 Agent 调用子 Agent（如 Implement）时，这个 Hook 自动拦截并注入上下文。
工作流程：



​
JSONL 配置格式详解

JSONL（JSON Lines）文件定义了每个 Agent 需要读取哪些文件。每行是一个 JSON 对象：


字段说明：

三种 JSONL 文件：

实际示例（后端任务的 implement.jsonl）：


注入时机和控制：

    

  • implement Agent：注入 implement.jsonl + prd.md + info.md
    • 

  • check Agent：注入 check.jsonl + prd.md（用于理解意图）
    • 

  • check Agent（[finish] 标记）：轻量注入 finish-work.md + prd.md
    • 

  • debug Agent：注入 debug.jsonl + codex-review-output.txt（如果有）
    • 

  • research Agent：注入项目结构概览 + research.jsonl（可选）
    • 



​
4.4 质量控制循环（Ralph Loop）


Ralph Loop 是 Claude Code 专属的质量控制机制，依赖 SubagentStop Hook。 Cursor 等平台需要手动运行
/check-backend（/trellis-check-backend）或 /check-frontend 进行代码检查。

Ralph Loop 基于 Ralph Wiggum 技术，在 Check Agent 完成工作时进行自动验证。


两种验证模式：
模式 A — 程序化验证（推荐，在 worktree.yaml 中配置）：


Ralph Loop 会依次运行每个命令，全部返回 0 才放行。
模式 B — Completion Markers（无 verify 配置时的回退方案）：
从 check.jsonl 的 reason 字段生成标记。例如：


生成的标记：TYPECHECK_FINISH、LINT_FINISH。Check Agent 必须在输出中包含所有标记才能停止。
状态跟踪：
Ralph Loop 通过 .trellis/.ralph-state.json 跟踪循环次数：



    

  • 任务切换时自动重置
    • 

  • 30 分钟超时自动重置
    • 

  • 达到 5 次上限强制放行（防止无限循环）
    • 



​
4.5 Agent 系统全解

Trellis 内置 6 个 Agent，各有不同的角色、工具和职责：

Agent 协作流程（Multi-Agent Pipeline）：


Dispatch Agent 的 Timeout 配置：