# Trellis 实战使用手册

> 以实际示例展示"何时输入什么"以及"系统默认会做什么"

---

## 快速概念

在开始之前，理解 Trellis 的核心交互模型：

```
你（用户）说话
    ↓
平台 hook 自动触发（你看不到这一步）
    ↓
hook 读取 task.json 状态，注入 breadcrumb 到 AI 的 prompt
    ↓
AI 收到 breadcrumb 指令，知道该做什么
    ↓
AI 按阶段行动（brainstorm / implement / check）
```

**你不需要记住流程——AI 会被 breadcrumb 引导去做正确的事。** 你只需要：
1. 说出你想做什么
2. 回答 AI 的问题
3. 确认/拒绝 AI 的建议

---

## 场景一：首次安装后（Bootstrap）

### 你的项目现状

```
harness-learning/
├── .trellis/              ← trellis init 刚创建
│   ├── spec/              ← 空的规范骨架
│   ├── tasks/
│   │   └── 00-bootstrap-guidelines/  ← 自动创建的初始化任务
│   └── workspace/lili/    ← 你的工作空间
└── ... (你的项目代码)
```

### 你需要输入什么

**你说：** "帮我填充项目规范" 或 "开始 bootstrap 任务"

**AI 自动做的事：**
1. 检测到 `00-bootstrap-guidelines` 任务存在（status=in_progress）
2. 读取 prd.md 中的指引
3. 搜索项目中已有的规范文件（CLAUDE.md, .cursorrules 等）
4. 开始对话式地帮你填充 `.trellis/spec/` 的各个文件

**AI 会问你的问题（举例）：**
- "你的后端用什么框架？有 ORM 吗？"
- "错误处理是用 try/except + 自定义异常，还是用 Result 类型？"
- "前端组件是 class-based 还是 functional？状态管理用什么？"

**你回答后，AI 直接填写 spec 文件。完成后：**

```bash
# AI 会引导你运行：
python3 ./.trellis/scripts/task.py finish
python3 ./.trellis/scripts/task.py archive 00-bootstrap-guidelines
```

---

## 场景二：开始一个新功能（完整流程）

### 第一步：你说出需求

**你说：** "我想给项目加一个用户登录功能"

**系统默认行为（你看不到的）：**
- hook 注入 `[workflow-state:no_task]` breadcrumb
- AI 读到 breadcrumb 知道当前无任务
- AI 判断这是"实现工作"→ 选择路径 B（Create a task）

**AI 自动执行：**
```bash
python3 ./.trellis/scripts/task.py create "用户登录功能" --slug user-login
```

**这条命令会：**
- 创建 `.trellis/tasks/05-07-user-login/` 目录
- 生成空的 `prd.md`、`task.json`（status=planning）
- 生成种子 `implement.jsonl` 和 `check.jsonl`
- 设置 session pointer（如果 session identity 可用）

**Breadcrumb 自动切换为 `[workflow-state:planning]`**

---

### 第二步：AI 加载 brainstorm 技能，开始问你问题

**AI 自动加载 `trellis-brainstorm` skill**，然后：

**AI 说：** "好的，我来帮你规划登录功能。第一个问题：你想支持哪些登录方式？
1. 邮箱 + 密码
2. OAuth（Google/GitHub）
3. 手机号 + 验证码
4. 以上全部"

**你说：** "先做邮箱密码就行"

**AI 立刻更新 `prd.md`**：
```markdown
# 用户登录功能

## 需求
- 邮箱 + 密码登录
- ...

## 验收标准
- 用户可以用邮箱注册
- 用户可以用邮箱登录
- ...
```

**AI 继续问：** "密码策略要什么级别？
1. 简单（6位以上）
2. 中等（8位 + 大小写 + 数字）
3. 严格（12位 + 特殊字符）"

**你说：** "中等"

**AI 更新 prd.md，继续下一个问题...**

这个过程持续 3-8 个问题，直到需求清晰。

---

### 第三步（可选）：研究阶段

如果需要技术调研（比如选择 auth 库），AI 会：

**AI 说：** "需要我调研一下 Python 的 auth 库选项吗？"

**你说：** "好"

**AI 派出 research sub-agent：**
- 调研 3-5 个候选方案
- 写入 `.trellis/tasks/05-07-user-login/research/auth-libraries.md`
- 回来给你总结 + 建议

---

### 第四步：Context Curation（JSONL 配置）

**AI 自动执行**（你可能注意不到这一步）：

```bash
# AI 根据任务内容，选择相关的 spec 文件
python3 ./.trellis/scripts/task.py add-context user-login implement \
    ".trellis/spec/backend/index.md" "Backend patterns for auth module"

python3 ./.trellis/scripts/task.py add-context user-login implement \
    ".trellis/spec/backend/error-handling.md" "Auth error handling patterns"

python3 ./.trellis/scripts/task.py add-context user-login check \
    ".trellis/spec/backend/quality-guidelines.md" "Quality check standards"
```

**这决定了后续 implement/check sub-agent 会看到什么规范。**

---

### 第五步：激活任务

AI 确认 PRD 完成后：

**AI 说：** "需求已经明确，PRD 写好了。准备开始实现吗？"

**你说：** "开始吧"

**AI 执行：**
```bash
python3 ./.trellis/scripts/task.py start 05-07-user-login
```

**这条命令会：**
- `task.json.status` 从 `planning` 变为 `in_progress`
- Breadcrumb 切换为 `[workflow-state:in_progress]`
- AI 被指示进入实现阶段

---

### 第六步：实现

**AI 自动派出 `trellis-implement` sub-agent：**

Sub-agent 收到的 context（你看不到，hook 自动注入）：
- prd.md 的全部内容
- implement.jsonl 列出的所有 spec 文件内容
- research/ 目录下的调研结论

**Sub-agent 开始写代码...** （你看到文件被创建/修改）

---

### 第七步：质量检查

实现完成后，**AI 自动派出 `trellis-check` sub-agent：**

Check agent 收到的 context：
- check.jsonl 列出的质量规范
- 当前的代码变更（git diff）

**Check agent 的输出示例：**
```
✅ 代码结构符合 backend/directory-structure 规范
✅ 错误处理使用了项目统一的异常类
⚠️ 发现问题：密码哈希函数缺少 salt 参数
→ 已自动修复
✅ 重新验证通过
```

如果有问题 → check agent 直接修 → 重新验证 → 直到通过。

---

### 第八步：Spec 更新

**AI 加载 `trellis-update-spec` skill：**

**AI 说：** "这次实现我发现了一个新模式：auth 相关的路由都用了 `/api/auth/` 前缀。要把这个记录到 spec 里吗？"

**你说：** "好"

**AI 更新 `.trellis/spec/backend/directory-structure.md`**，加入新规则。

---

### 第九步：提交

**AI 执行 Phase 3.4 commit 流程：**

```bash
git status --porcelain
git log --oneline -5
```

**AI 展示提交计划：**
```
Proposed commits (in order):
  1. feat(auth): add user registration and login endpoints
     - src/auth/routes.py
     - src/auth/models.py
     - src/auth/service.py
  2. test(auth): add unit tests for auth service
     - tests/auth/test_service.py
     - tests/auth/test_routes.py

Unrecognized dirty files (NOT in any commit):
  (none)

Reply 'ok' / '行' to execute.
```

**你说：** "行"

**AI 执行 git add + git commit。**

---

### 第十步：结束

**AI 说：** "代码已提交。你可以运行 `/trellis:finish-work` 来归档任务并记录会话。"

**你说：** `/trellis:finish-work`

**系统执行：**
- `task.py archive user-login` → 移动到 `tasks/archive/2026-05/`
- `add_session.py` → 记录到 `workspace/lili/journal-1.md`
- 清除 session pointer

---

## 场景三：纯问答（不创建任务）

**你说：** "Python 的 dataclass 和 Pydantic BaseModel 有什么区别？"

**系统默认行为：**
- hook 注入 `[workflow-state:no_task]`
- AI 判断这是纯 Q&A → 路径 A（Direct answer）
- **不创建任务，直接回答**

---

## 场景四：跳过流程（inline 模式）

**你说：** "小修一下，把 README 的标题改成中文"

**AI 识别到关键词"小修一下"**（在白名单中）：
- 跳过 Trellis 流程
- 直接修改文件
- 不创建任务、不派 sub-agent

---

## 场景五：跨会话恢复

### 昨天的会话

你做到一半（status=in_progress），关掉了 IDE。

### 今天重新打开

**系统自动做的事：**
1. Hook 触发
2. 读取 `.trellis/.runtime/sessions/{your_session}.json`
3. 发现 `current_task` 指向 `05-07-user-login`
4. 读取 `task.json`，status = `in_progress`
5. 注入 `[workflow-state:in_progress]` breadcrumb

**AI 说：** "上次你在做'用户登录功能'（Phase 2），代码已写完但还没通过 check。要继续吗？"

**你不需要做任何额外操作——session pointer 自动恢复了上下文。**

---

## 场景六：调试循环（Break Loop）

**情况**：你修了一个 bug 三次，每次都"修好了"但又复现。

**你说：** "这个 bug 我修了三次了还是有问题"

**AI 加载 `trellis-break-loop` skill：**

```
🔍 根因分析：
- 分类：竞态条件 (Race Condition)
- 为什么前两次修复失败：只处理了主路径，没考虑并发写入
- 真正的根因：缺少数据库事务隔离

💡 预防措施（已写入 spec）：
- 所有涉及"读-改-写"的操作必须使用事务
- 添加到 .trellis/spec/backend/database-guidelines.md
```

---

## 场景七：中途修改需求（Rollback）

**情况**：implement 阶段发现 PRD 有遗漏。

**你说：** "等等，登录失败要限制重试次数，PRD 里没写"

**AI 自动回到 Phase 1：**
1. 更新 prd.md（加入重试限制需求）
2. 可能更新 implement.jsonl（如果需要额外 spec）
3. 重新进入 Phase 2（implement agent 会看到更新后的 PRD）

---

## 命令速查表

### 你可能需要手动输入的命令

| 场景 | 输入 |
|------|------|
| 开始新功能 | 直接用自然语言描述需求 |
| 跳过流程 | 需求前加"小修一下" / "直接改" / "跳过 trellis" |
| 归档完成的任务 | `/trellis:finish-work` |
| 继续未完成的任务 | `/trellis:continue` |
| 查看当前任务 | `python3 .trellis/scripts/task.py current --source` |
| 列出所有任务 | `python3 .trellis/scripts/task.py list` |
| 手动创建任务 | `python3 .trellis/scripts/task.py create "标题" --slug name` |

### 系统自动执行的（你不需要管）

| 动作 | 触发时机 |
|------|---------|
| 注入 breadcrumb | 每次你发消息 |
| 恢复 session pointer | 打开 IDE 时 |
| 读取 task.json status | 每次 turn |
| 加载 brainstorm skill | status = planning |
| 派出 implement sub-agent | status = in_progress + 用户确认 |
| 派出 check sub-agent | implement 完成后 |
| 加载 update-spec | check 通过后 |
| 记录 session 到 journal | /finish-work 时 |

---

## Skill 一览表

| Skill | 何时触发 | 你需要说什么 |
|-------|---------|-------------|
| `trellis-brainstorm` | 需求不明确时 | "我想做 XXX"（AI 自动进入） |
| `trellis-before-dev` | 开始写代码前 | （Class-3 平台才用，Claude Code 用 sub-agent） |
| `trellis-check` | 代码写完后 | （自动触发）或 "帮我检查一下" |
| `trellis-break-loop` | 反复修同一个 bug | "这个 bug 又出现了" / "修了好几次了" |
| `trellis-update-spec` | 任务完成时 | （自动触发，Phase 3.3） |
| `trellis-meta` | 想修改 Trellis 本身 | "我想改一下 Trellis 的 workflow" |

---

## 常见问题

### Q: 如果我不想走流程，直接改代码可以吗？

**A**: 可以。说 **"直接改"** / **"跳过 trellis"** / **"小修一下"** 之一，AI 就会跳过流程直接执行。

### Q: sub-agent 是什么？我会看到它吗？

**A**: 在 Claude Code 里，sub-agent 就是一个新的 Agent 调用（你会看到 "Dispatching agent..." 的提示）。它在独立 context 里运行，带着 spec 注入的规范去写代码或审查代码。

### Q: 如果 hook/session pointer 不工作怎么办？

**A**: 你可以手动设置：
```bash
export TRELLIS_CONTEXT_ID="my-session"
python3 .trellis/scripts/task.py start <task-name>
```

### Q: 多个任务可以同时存在吗？

**A**: 可以存在多个 task 目录，但每个 session 只有一个 active task。`task.py list` 可以看到所有任务。

### Q: 什么时候应该用 Trellis 流程，什么时候跳过？

| 跳过 | 走流程 |
|------|--------|
| 改个 typo | 加新功能 |
| 加个 console.log 调试 | 修复复杂 bug |
| 更新一行配置 | 重构模块 |
| 问一个问题 | 任何需要 >30min 的工作 |

### Q: `implement.jsonl` 和 `check.jsonl` 有什么区别？

**A**: 
- `implement.jsonl` → 给**写代码**的 agent 看的 spec（"怎么写"）
- `check.jsonl` → 给**审查代码**的 agent 看的 spec（"怎么查"）

通常 implement 需要编码规范，check 需要质量标准。两者可能有交集。

---

## 完整的用户交互时间线

```
00:00  你: "我想加个用户登录功能"
       [hook 注入 no_task breadcrumb]
       AI: 执行 task.py create → 创建任务

00:01  [hook 注入 planning breadcrumb]
       AI: 加载 brainstorm，问第一个问题
       你: 回答

00:03  AI: 问第二个问题 → 你答 → AI 更新 prd.md
       ...（3-8 个问题）

00:08  AI: "需要调研 auth 库吗？" → 你: "好"
       AI: 派出 research sub-agent → 写 research/auth-libs.md

00:10  AI: 完成 JSONL curation（自动）
       AI: "需求清楚了，开始实现？" → 你: "开始"
       AI: task.py start → status 变 in_progress

00:11  [hook 注入 in_progress breadcrumb]
       AI: 派出 implement sub-agent
       ...（sub-agent 写代码）

00:18  AI: 派出 check sub-agent
       check: 发现问题 → 自动修 → 通过

00:20  AI: 加载 update-spec → "发现新模式，要记录吗？" → 你: "好"
       AI: 更新 spec 文件

00:21  AI: 展示 commit 计划 → 你: "行"
       AI: git commit

00:22  AI: "可以运行 /trellis:finish-work 归档了"
       你: /trellis:finish-work
       → 任务归档 → 会话记录到 journal → 完成 ✓
```

---

## 关键洞见：你主要在做什么？

在整个流程中，**你真正需要做的只有**：

1. **描述需求**（自然语言）
2. **回答问题**（3-8 个选择题）
3. **说"开始"**（确认进入实现）
4. **说"行"**（确认提交计划）
5. **说 `/trellis:finish-work`**（归档）

其他一切——状态转换、spec 注入、sub-agent 调度、session 恢复——**都是自动的**。