# Trellis - AI 编码工程化框架

> **GitHub**: https://github.com/mindfold-ai/Trellis
> **官网/文档**: https://docs.trytrellis.app/zh
> **npm**: `@mindfoldhq/trellis`
> **License**: AGPL-3.0
> **开发商**: Mindfold (mindfold-ai)
> **研究日期**: 2026-06-06

---

## 一句话总结

Trellis 是一个**开箱即用的 AI 编码工程化框架**，核心解决的问题是：**AI 编码 Agent 每次会话从零开始，记不住项目规范和团队标准**。它将规范、任务、记忆沉淀进代码仓库，让任何 Coding Agent 都按你的工程标准执行。

## 核心痛点

AI 编码工具（Cursor、Claude Code、Codex 等）虽然能快速生成代码，但存在以下问题：
1. **无记忆** — 每次新会话从零开始理解项目
2. **无规范持久化** — `CLAUDE.md`、`.cursorrules` 等文件容易膨胀变臃肿
3. **无任务结构化** — PRD、实现上下文、审查记录散落各处
4. **无跨平台统一** — 每个工具都要单独配置工作流

## 核心能力

| 能力 | 说明 |
|------|------|
| **自动注入规范** | 规范写在 `.trellis/spec/`，Trellis 按当前任务自动注入相关上下文 |
| **任务驱动工作流** | PRD、实现上下文、审查上下文统一在 `.trellis/tasks/` 管理 |
| **项目记忆** | `.trellis/workspace/` 中的 journal 保留上次会话脉络 |
| **团队共享标准** | Spec 随仓库版本化，个人规则可成为团队基础设施 |
| **多平台复用** | 一套结构覆盖 **14 个 AI Coding 平台** |

## 工作原理（4阶段循环）

```
Plan → Implement → Verify → Finish → (循环)
```

### 1. Plan（规划）
- `trellis-brainstorm` 逐题梳理需求 → 写入 `prd.md`
- 资料调研派发给 `trellis-research` 子代理
- 产出：精选 Spec + 研究文件，由 `implement.jsonl` / `check.jsonl` 编排

### 2. Implement（实现）
- `trellis-implement` 子代理依据 PRD 编写代码
- 上下文按 `implement.jsonl` 自动注入
- **不会执行 git commit**

### 3. Verify（验证）
- `trellis-check` 子代理基于 diff 对照 Spec 逐项核查
- 运行 lint、type-check、测试
- 自动修复能力范围内的问题

### 4. Finish（收尾）
- 最终检查
- `trellis-update-spec` 将新增认知沉淀回 `.trellis/spec/`
- 归档任务，更新 journal

## 目录结构

```
.trellis/
├── spec/           # 项目规范（自动注入到 Agent 上下文）
├── tasks/          # 任务 PRD、实现/审查上下文、状态
├── workspace/      # 工作日志（journal），会话间记忆
└── ...             # 各平台适配文件（自动生成）
```

## 支持平台（14个）

仓库中包含以下平台的配置目录：
- `.claude/` — Claude Code
- `.cursor/` — Cursor
- `.codex/` — OpenAI Codex
- `.opencode/` — OpenCode
- `.pi/` — Pi
- `.agents/` — 通用 Agent Skills
- `.husky/` — Git Hooks 集成
- 其他更多...

## 快速开始

```bash
# 安装
npm install -g @mindfoldhq/trellis@latest

# 在项目中初始化
trellis init -u your-name

# 指定平台初始化
trellis init --cursor --opencode --codex -u your-name
```

**前置要求**：Node.js >= 18, Python >= 3.9

## 使用流程

1. 用自然语言描述需求
2. AI 逐题头脑风暴 → 澄清 PRD
3. AI 自主调用 `trellis-implement` 编码 + 自动校验
4. 完成时输入 `/trellis:finish-work`，归档任务、更新记忆

## 与 CLAUDE.md / AGENTS.md / .cursorrules 的区别

这些文件是有用的入口，但容易膨胀。Trellis 在此之上补充了：
- **作用域明确的 Spec**（不是一个大文件）
- **按任务划分的 PRD**
- **工作流关卡**（Plan→Implement→Verify→Finish）
- **工作区记忆**（跨会话）
- **多平台自动适配文件**

## 适用场景

- **个人开发者**：记忆机制 + 可复用工作流，不用每次重复说明
- **团队**：标准统一、任务边界清晰、上下文可审查、跨平台可移植
- **多工具用户**：同一套 Trellis 结构在 Cursor/Claude Code/Codex 间复用

## 评价

### ✅ 优点
- 解决了 AI 编码的核心痛点（记忆 + 规范持久化）
- 多平台支持是一大亮点，不用为每个工具单独配置
- 4阶段循环（Plan→Implement→Verify→Finish）是成熟的工程化思路
- 规范随仓库版本化，团队协作友好
- 开源 AGPL-3.0，可自托管

### ⚠️ 注意
- AGPL-3.0 许可证，商业使用需注意传染性
- 需要团队统一采用，否则收益有限
- 增加 `.trellis/` 目录到仓库，有一定侵入性

### 📊 项目热度
- GitHub Stars：持续增长中
- 有微信群 + 飞书群，国内社区活跃
- npm 周下载量可见

## 相关链接

- [官方文档](https://docs.trytrellis.app/zh)
- [快速开始](https://docs.trytrellis.app/zh/start/install-and-first-task)
- [支持平台](https://docs.trytrellis.app/zh/advanced/multi-platform)
- [真实场景](https://docs.trytrellis.app/zh/start/real-world-scenarios)
- [Spec 模板](https://docs.trytrellis.app/zh/templates/specs-index)
- [Discord](https://discord.com/invite/tWcCZ3aRHc)
- [DeepWiki](https://deepwiki.com/mindfold-ai/Trellis)

---

*研究归档：2026-06-06 | 路径：/obsidian/AI工程/Trellis_AI编码工程化框架.md*