架构全景
4.1 整体架构
4.2 会话启动流程
Claude Code / OpenCode
Cursor / Codex
Kilo
Kiro
这两个平台的 Hook 系统在会话开始时自动触发 session-start.py，无需手动输入 /start。
用户打开终端即可直接描述任务。可选运行 /start 获取更详细的上下文报告。
Cursor 的 Hook 支持尚在开发中，Codex 通过 AGENTS.md 提供基础上下文。 用户必须手动调用
/start（Codex 为 $start）获取完整的项目上下文。 命令内部执行与 Claude Code Hook
相同的步骤：读取身份、工作流、历史、任务等上下文。
Kilo 通过 .kilocode/rules/ 和 AGENTS.md 自动加载项目规则到每次交互。 可选运行
/start.md workflow 获取完整的 Trellis 上下文（身份、Git 状态、活跃任务等）。
Kiro 通过 .kiro/steering/ 自动加载项目上下文（product.md、tech.md、structure.md
等）到每次交互。 可选运行自定义 prompt 获取 Trellis 完整上下文。Kiro 还支持通过 Spec
模式自动生成需求→设计→任务文档。
/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 对象：
{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
{"file": ".trellis/spec/backend/database-guidelines.md", "reason": "Database patterns"}
{"file": "src/services/", "type": "directory", "reason": "Existing service patterns"}
| 字段 | 必填 | 说明 |
|---|
file | 是 | 文件或目录的相对路径（相对于项目根目录） |
reason | 是 | 为什么需要这个文件（同时用于生成 completion markers） |
type | 否 | 默认 "file"。设为 "directory" 则读取目录下所有 .md 文件（最多 20 个） |
| 文件 | 用于 | 典型内容 |
|---|
implement.jsonl | Implement Agent | workflow.md + 相关 spec + 代码模式示例 |
check.jsonl | Check Agent | finish-work.md + check 命令 + 相关 spec |
debug.jsonl | Debug Agent | 相关 spec + check 命令 |
{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
{"file": ".trellis/spec/shared/index.md", "reason": "Shared coding standards"}
{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
{"file": ".trellis/spec/backend/api-module.md", "reason": "API module conventions"}
{"file": ".trellis/spec/backend/quality.md", "reason": "Code quality requirements"}
- 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 进行代码检查。
worktree.yaml 中配置）：
verify:
- pnpm lint
- pnpm typecheck
- pnpm test
check.jsonl 的 reason 字段生成标记。例如：
{"file": "...", "reason": "TypeCheck"}
{"file": "...", "reason": "Lint"}
TYPECHECK_FINISH、LINT_FINISH。Check Agent 必须在输出中包含所有标记才能停止。
状态跟踪：
Ralph Loop 通过 .trellis/.ralph-state.json 跟踪循环次数：
{
"task": ".trellis/tasks/02-27-user-login",
"iteration": 2,
"started_at": "2026-02-27T10:30:00"
}
- 任务切换时自动重置
- 30 分钟超时自动重置
- 达到 5 次上限强制放行（防止无限循环）
4.5 Agent 系统全解
Trellis 内置 6 个 Agent，各有不同的角色、工具和职责：
| Agent | 角色 | 工具 | Model | 关键特点 |
|---|
| dispatch | 纯调度器 | Read, Bash, Exa Search, Exa Code Context | opus | 只负责按顺序调用其他 Agent，不读 spec |
| plan | 需求评估 | Read, Bash, Glob, Grep, Task | opus | 可以拒绝不清晰的需求 |
| implement | 代码实现 | Read, Write, Edit, Bash, Glob, Grep, Exa Search, Exa Code Context | opus | 禁止 git commit |
| check | 质量检查 | Read, Write, Edit, Bash, Glob, Grep, Exa Search, Exa Code Context | opus | 必须自修复，受 Ralph Loop 控制 |
| debug | Bug 修复 | Read, Write, Edit, Bash, Glob, Grep, Exa Search, Exa Code Context | opus | 精确修复，不做额外重构 |
| research | 信息搜索 | Read, Glob, Grep, Exa Search, Exa Code Context | opus | 纯搜索，不修改文件 |
| Phase | 最大时间 | 轮询次数 |
|---|
| implement | 30 分钟 | 6 次 |
| check | 15 分钟 | 3 次 |
| debug | 20 分钟 | 4 次 |
