跳转到主要内容

​
架构全景

​
整体架构

┌──────────────────────────────────────────────────────────────┐
│                             User                             │
└─────────────────────────────┬────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────┐
│  Claude Code / Cursor / OpenCode / Codex / Kiro / Gemini /   │
│  Qoder / CodeBuddy / Copilot / Droid / Kilo / Antigravity /  │
│  Windsurf  +  .agents/skills/ ecosystem (Amp, Cline, ...)    │
│                 (AI Coding Assistant Layer)                  │
└─────────────────────────────┬────────────────────────────────┘
                              │
          ┌───────────────────┼──────────────────┐
          │                   │                  │
          ▼                   ▼                  ▼
  ┌───────────────┐  ┌──────────────────┐  ┌─────────────────┐
  │  Commands     │  │  Skills          │  │  Hooks          │
  │  /trellis:*   │  │  (auto-trigger)  │  │  (hook-capable) │
  │               │  │                  │  │                 │
  │  start        │  │  brainstorm      │  │  SessionStart   │
  │  finish-work  │  │  before-dev      │  │  PreToolUse     │
  │  continue     │  │  check           │  │  UserPrompt     │
  │               │  │  update-spec     │  │                 │
  │  [all]        │  │  break-loop      │  │  [see §2.2]     │
  └───────┬───────┘  └────────┬─────────┘  └────────┬────────┘
          │                   │                      │
          └───────────────────┼──────────────────────┘
                              │
                              ▼
      ┌──────────────────────────────────────────────────────┐
      │                .trellis/ directory                   │
      │                                                      │
      │  spec/        workspace/      tasks/      scripts/   │
      │  (specs)      (journals)      (tasks)     (Python)   │
      └─────────────────────────┬────────────────────────────┘
                                │
                                ▼
      ┌──────────────────────────────────────────────────────┐
      │                  Sub-agent system                    │
      │                                                      │
      │  trellis-research -> trellis-implement -> trellis-check │
      │                                                      │
      │   Each sub-agent receives precise context via JSONL  │
      └─────────────────────────┬────────────────────────────┘
                                │
                                ▼
      ┌──────────────────────────────────────────────────────┐
      │                  Your project code                   │
      │      (AI generates / modifies code per specs)        │
      └──────────────────────────────────────────────────────┘

​
workflow.md：Single Source of Truth

.trellis/workflow.md 是定义 Plan / Execute / Finish 契约的唯一一份文件：Phase 1（1.0 task.py create → 1.4 task.py start）、Phase 2（2.1 trellis-implement → 2.2 trellis-check）、Phase 3（3.1 最终验证 → 3.4 /trellis:finish-work）。系统其余部件都从它读：
  • SessionStart hook 自动注入它的 TOC + 步骤级详情，你开口前 AI 已经拿到契约。
  • /trellis:continue 读 .current-task + 任务 status，再对照 workflow.md 判断当前在哪一步、下一步该做什么。
  • Skill 和 sub-agent 通过 JSONL 拿到它（workflow.md 是 implement.jsonl 默认第一条）。
  • 任务状态 默认三个：planning / in_progress / completed（由 task.py create / start / archive 自动设置），与 workflow.md 里的三个 Phase 一一对应。workflow.md 里按状态分块写提醒；要加自定义状态直接在 workflow.md 里加对应 block。
改 workflow.md 就能改整个项目的工作流，下次 session 所有平台、skill、sub-agent、命令全都按新版读。别处没有工作流硬编码。

​
会话启动流程

SessionStart hook 在 session 启动时自动触发，平台对应的 session-start.py / session-start.js 不需要手动调用即完成 Trellis 上下文注入。打开终端就直接描述任务；想显式看上下文报告可以跑 /trellis:start。
/trellis:start 运行时（或 SessionStart hook 自动触发时）的行为： 
/trellis:start
     │
     ▼
┌────────────────────────────────────────┐
│  Hook / command body:                  │
│                                        │
│  read .trellis/.developer    -> id     │
│  read .trellis/workflow.md   -> flow   │
│  read workspace/{name}/index -> history│
│  read git log                -> commits│
│  read .trellis/tasks/        -> tasks  │
└───────────────────┬────────────────────┘
                    │
                    ▼
         ┌──────────────────────────┐
         │   Context injected to AI │
         └────────────┬─────────────┘
                      │
                      ▼
      ┌──────────────────────────────────┐
      │  start.md command continues:     │
      │                                  │
      │  Step 1: read workflow.md        │
      │  Step 2: run get_context.py      │
      │  Step 3: read spec indexes       │
      │  Step 4: report & ask user       │
      └──────────────────────────────────┘

​
规范注入机制

Sub-agent 自动规范注入依赖平台的 PreToolUse hook（或等价机制）。当前支持：Claude Code、Cursor、OpenCode、CodeBuddy、Droid。其他平台由主会话自行读 JSONL 并把相关内容传给 sub-agent。
inject-subagent-context（Claude Code 的 Python，OpenCode 的 JS）是规范注入引擎。主会话 spawn trellis-* sub-agent 时，这个 hook 拦截调用并按 JSONL 注入精准上下文。 工作流程： 
Main session spawns: Task(subagent_type="trellis-implement", prompt="...")
     │
     ▼
┌──────────────────────────────────────────────────────────────┐
│  Hook: inject-subagent-context  (runs BEFORE sub-agent)      │
│                                                              │
│  Reads happen in the HOOK, not in the sub-agent:             │
│                                                              │
│  1. Hook reads .trellis/.current-task                        │
│     -> current task directory path                           │
│                                                              │
│  2. Hook reads {task_dir}/implement.jsonl                    │
│     -> list of spec files this sub-agent needs               │
│                                                              │
│  3. Hook reads each file referenced in the JSONL             │
│     -> .trellis/spec/backend/index.md                        │
│     -> .trellis/spec/backend/database-guidelines.md          │
│     -> ...                                                   │
│                                                              │
│  4. Hook reads prd.md (requirements) and info.md (design)    │
│                                                              │
│  5. Hook concatenates it all and prepends as                 │
│     "additionalContext" to the sub-agent's prompt            │
└───────────────────────┬──────────────────────────────────────┘
                        │
                        ▼
Sub-agent 启动时 prompt 里已经带着这些内容了（它本身不读任何文件）：

  # trellis-implement 任务
  ## 你的上下文
  === .trellis/spec/backend/index.md ===
  （完整后端 spec 内容）
  === .trellis/spec/backend/database-guidelines.md ===
  （完整数据库 spec 内容）
  === {task_dir}/prd.md（需求） ===
  （完整需求文档）
  ## 你的任务
  实现该功能

​
JSONL 配置格式

JSONL（JSON Lines）定义 hook 要替 sub-agent 注入哪些文件。每行一个 JSON 对象： 
{"file": ".trellis/workflow.md", "reason": "项目工作流和约定"}
{"file": ".trellis/spec/backend/index.md", "reason": "后端开发指南"}
{"file": "src/services/auth.ts", "reason": "现有 auth 实现，要对齐模式"}
{"file": ".trellis/tasks/02-27-user-login/research/", "type": "directory", "reason": "调研产物"}
字段说明：
字段必填说明
file是文件或目录的相对路径（相对项目根）
reason是为什么要读这个文件
type否默认 "file"。单文件模式下 hook 按原样读引用的文件，不管扩展名（源码、JSON 等都能读）。"directory" 模式只按文件名排序注入目录里的 .md（最多 20 个），非 .md 跳过。
JSONL 里该放什么，取决于 sub-agent 执行这个任务需要什么：
  • Spec 和 workflow：.trellis/workflow.md、.trellis/spec/**/index.md、具体指南文件——塑形 sub-agent怎么写代码。
  • 现有代码作为参照：指向单个源码文件（src/services/auth.ts）能让 sub-agent 对齐现有实现模式。优先单文件；目录模式不会读 .ts / .py 等。
  • 调研产物：目录模式指向 {task_dir}/research/，会把 trellis-research 产出的每个 .md 全拉进来。
三种 JSONL 文件：
文件使用者典型内容
implement.jsonltrellis-implementworkflow.md + 相关 spec + 代码模式范例
check.jsonltrellis-check质量 checklist spec + 测试 / lint 规则
research.jsonltrellis-research项目结构概览 + 调研目标
实战示例（后端任务、brainstorm 追加上下文后的 implement.jsonl）： 
{"file": ".trellis/workflow.md", "reason": "项目工作流和约定"}
{"file": ".trellis/spec/backend/index.md", "reason": "后端开发指南"}
{"file": ".trellis/spec/backend/database-guidelines.md", "reason": "本任务涉及的 DB 模式"}
{"file": ".trellis/tasks/02-27-user-login/research/", "type": "directory", "reason": "trellis-research 的调研产物"}
前两条是默认写入的，后面是任务相关的，一般通过 task.py add-context 追加。 各 sub-agent 的注入行为：
  • trellis-implement：注入 implement.jsonl + prd.md + info.md
  • trellis-check：注入 check.jsonl + prd.md（用于理解意图）
  • trellis-research：注入项目结构概览 + research.jsonl（可选）

​
Sub-agent 系统

Trellis 原生带有 3 个 sub-agent，每个角色明确、约束清晰、有独立的 JSONL spec 注入通道：
Sub-agent角色约束主要上下文
trellis-research代码 / 文档搜索只读research.jsonl
trellis-implement写代码禁止 git commitimplement.jsonl + prd.md
trellis-check验证 + 自修复只为了修复才写代码check.jsonl + prd.md
主会话中的典型任务流： 
trellis-brainstorm skill
  │
  │  澄清范围、起草 prd.md、创建任务目录 + JSONL 配置
  │  需要调研时并行 spawn trellis-research sub-agent
  │
  ▼
trellis-before-dev skill
  │
  │  编码前先读相关 spec
  │
  ▼
Spawn trellis-implement sub-agent
  │
  │  Hook 注入 implement.jsonl 上下文
  │  Sub-agent 写代码，不 git commit
  │
  ▼
Spawn trellis-check sub-agent
  │
  │  Hook 注入 check.jsonl 上下文
  │  跑 lint / typecheck / test，对照质量 checklist 比对 diff
  │  在内部重试循环里自修复
  │
  ▼
/trellis:finish-work
  │
  │  人工测试 + commit 后，finish-work 归档任务
  │  并把 session 条目追加到 workspace journal