Logo
热心市民王先生

需求拆解

技术研究 Agent 架构 Trellis

分析 Trellis 架构思想的核心能力，识别用户目标、关键路径和集成需求

1. 研究背景与目标

1.1 为什么研究 Trellis

Trellis 是一个”给 AI 立规矩的开源框架”，核心定位是 AI 开发工作流的结构化基础设施。它要解决的问题是：

  • 上下文管理混乱：AI 开发过程中，项目知识、编码规范、任务状态往往散落在多个地方（CLAUDE.md、.cursorrules、AGENTS.md 等），容易越写越大、越写越散
  • 任务并行困难：多个 AI 任务同时进行时，分支和本地状态容易互相干扰
  • 知识无法沉淀：每次会话结束后，决策上下文和工作经验无法有效保留到下一次会话
  • 工具链割裂：团队使用多个 AI coding 工具时，每换一个平台就需要重搭一次工作流

1.2 用户的核心需求

用户基于 pi-mono 开发了一个 agent 助手，希望借鉴 Trellis 的思想来提升现有系统的架构能力。核心关注点：

  1. 如何结构化地管理 AI 开发上下文（Spec、Task、Workspace）
  2. 如何实现任务驱动的并行执行（git worktree + 任务隔离）
  3. 如何建立项目级记忆机制（journal、会话连续性）
  4. 如何设计可扩展的多平台接入层（支持 9+ AI coding 平台）

1.3 研究范围与边界

本研究聚焦于 Trellis 的架构思想和设计模式，而非具体实现细节。重点分析：

  • ✅ 分层 Spec 系统的设计原理
  • ✅ 任务上下文与状态管理机制
  • ✅ Workspace journal 的记忆模型
  • ✅ 多平台适配的架构模式
  • ⚠️ 具体代码实现（仅作为理解架构的参考）

2. Trellis 核心能力识别

2.1 自动注入 Spec 系统

能力描述： Trellis 将项目规范、编码标准、工作流偏好等写进 .trellis/spec/ 目录，在每次 AI 会话时自动注入当前任务真正需要的上下文。

核心价值：

  • 减少重复解释：不需要每次都从头解释项目如何做事
  • 按需加载：不是简单堆砌所有文档，而是智能加载相关部分
  • 版本化管理：Spec 跟随仓库版本控制，可评审、可追溯

关键设计：

.trellis/spec/
├── project-spec.md      # 项目整体规范
├── coding-standards.md  # 编码标准
├── workflow.md          # 工作流规则
└── domain-specific/     # 领域特定规范（按需加载）

2.2 任务驱动工作流

能力描述： 将 PRD（产品需求文档）、实现上下文、检查上下文和任务状态统一放进 .trellis/tasks/，每个任务有独立的状态文件和上下文目录。

核心价值：

  • 任务隔离：不同任务的上下文互不干扰
  • 状态可追踪：任务进度、检查清单、决策记录都有迹可循
  • AI 开发不失控：避免”AI 开发越做越乱”的问题

关键设计：

.trellis/tasks/
├── task-001-feature-x/
│   ├── prd.md           # 任务 PRD
│   ├── context/         # 实现上下文
│   ├── checklist.md     # 检查清单
│   └── state.json       # 任务状态
└── task-002-bugfix-y/
    └── ...

2.3 并行 Agent 执行

能力描述： 借助 git worktree 和 Trellis 的任务结构，可以将不同任务拆开并行推进，多个 Agent 同时工作时分支和本地状态不会互相踩来踩去。

核心价值：

  • 真正的并行：不是简单的多线程，而是物理隔离的执行环境
  • 分支管理简化：每个任务有独立的 worktree 和分支
  • 状态不冲突：本地文件、依赖安装、构建产物都隔离

关键设计：

project/
├── main worktree/       # 主工作区
├── .git/worktrees/
│   ├── task-001/        # 任务 1 的 worktree
│   └── task-002/        # 任务 2 的 worktree
└── .trellis/tasks/      # 任务元数据

2.4 项目记忆系统

能力描述： .trellis/workspace/ 里的 journal 会保留上一次工作的脉络，让新会话不是从空白开始。支持开发者级别的连续性。

核心价值：

  • 会话连续性：新入场的 Agent 不需要从零开始猜上下文
  • 经验沉淀：决策过程、踩过的坑、解决方案都被记录
  • 个人化隔离：不同开发者的 workspace journal 是隔离的

关键设计：

.trellis/workspace/
├── alice/
│   ├── journal.md       # Alice 的工作日志
│   └── sessions/        # 会话历史
└── bob/
    └── ...

2.5 多平台复用层

能力描述： 同一套 Trellis 结构可以带到 10 个 AI coding 平台上，而不是每换一个工具就重搭一次工作流。通过适配层对接不同平台的配置文件格式。

核心价值：

  • 一次定义，多处复用：Spec、Task、流程结构统一管理
  • 降低迁移成本：换工具时不需要重新搭建工作流
  • 团队标准化：不同成员使用不同工具时仍能保持统一流程

关键设计：

.trellis/
├── spec/                # 统一规范
├── tasks/               # 统一任务结构
└── scripts/             # 统一流程脚本

平台适配层：
├── .claude/             # Claude Code 适配
├── .cursor/             # Cursor 适配
├── AGENTS.md            # OpenCode 适配
├── .agents/             # 其他平台适配
└── ...

3. 关键路径识别

3.1 最需要借鉴的核心能力

基于用户基于 pi-mono 开发 agent 助手的背景，以下能力最值得优先借鉴：

能力优先级集成难度预期收益
分层 Spec 系统P0低高 - 立即改善上下文管理
任务上下文隔离P0中高 - 支持多任务并行
Workspace journalP1中中 - 改善会话连续性
多平台适配层P2高中 - 取决于目标平台数量
git worktree 集成P2高高 - 但实现复杂度也高

3.2 集成的关键挑战

  1. 上下文注入的精准度：如何判断”当前任务真正需要的上下文”，避免信息过载
  2. 任务状态的持久化：如何设计轻量但完整的状态模型
  3. 与现有架构的兼容：pi-mono 的现有架构可能与 Trellis 有不同的设计理念
  4. 用户体验的平衡：结构化带来的复杂度 vs 灵活性

4. 成功标准定义

4.1 短期目标（1-2 周）

  • 实现基础的分层 Spec 系统
  • 设计任务上下文的数据结构
  • 完成 Spec 自动注入的概念验证

4.2 中期目标（1 个月）

  • 实现任务隔离与并行执行
  • 建立 Workspace journal 机制
  • 支持至少 2 个 AI coding 平台

4.3 长期目标（3 个月）

  • 完整的 git worktree 集成
  • 支持 5+ 平台
  • 建立社区和生态

5. 约束条件与风险

5.1 技术约束

  • pi-mono 架构限制：需要评估 pi-mono 的扩展性，可能存在架构不兼容的风险
  • 性能开销：多层上下文注入可能带来延迟
  • 存储管理：大量 journal 和状态文件需要合理的清理策略

5.2 非技术约束

  • 学习曲线：团队成员需要适应新的工作流
  • 工具链适配：需要为不同平台编写适配层
  • 维护成本：多平台支持意味着更多的维护工作

5.3 风险缓解

风险可能性影响缓解措施
架构不兼容中高先做小规模概念验证
性能问题低中按需加载、懒加载
adoption 低中中提供渐进式迁移路径

6. 下一步行动

  1. 深度分析 Trellis 源码：理解具体实现细节
  2. 评估 pi-mono 现状：识别集成点和改造点
  3. 设计集成方案：制定分阶段实施计划
  4. 概念验证：选择 1-2 个核心能力做 PoC

参考资料