Trellis 核心能力验证

1. 分层 Spec 系统分析

1.1 Spec 系统的结构设计

Trellis 的 Spec 系统不是单一的大文件，而是采用分层结构：

.trellis/spec/
├── project-spec.md         # 项目级规范（必读）
├── coding-standards.md     # 编码标准（必读）
├── workflow.md             # 工作流规则（必读）
├── architecture/           # 架构相关（按需加载）
│   ├── tech-stack.md
│   └── patterns.md
├── domain/                 # 领域知识（按需加载）
│   ├── api-conventions.md
│   └── data-models.md
└── integrations/           # 集成规范（按需加载）
    └── ci-cd.md

设计原理：

• 必读 vs 按需：不是所有 Spec 都需要在每次会话中加载，避免上下文污染
• 分层治理：项目级、架构级、领域级、集成级各有不同的稳定性和受众
• 可组合性：任务可以根据需要组合不同的 Spec 模块

1.2 Spec 注入机制

Trellis 的 Spec 注入不是简单的文件拼接，而是基于任务类型的智能选择：

注入策略：

1. 基础注入：project-spec.md + coding-standards.md 始终注入
2. 条件注入：根据任务类型选择 domain/ 或 architecture/ 下的相关 Spec
3. 显式引用：任务 PRD 中可以显式声明需要哪些 Spec

实现方式（概念性）：

// 伪代码：Spec 注入逻辑
async function injectSpecs(task) {
  const baseSpecs = await loadBaseSpecs();  // 基础 Spec
  const contextSpecs = await selectContextSpecs(task.type);  // 按任务类型选择
  const explicitSpecs = await loadExplicitSpecs(task.requiredSpecs);  // 显式声明
  
  return deduplicate([...baseSpecs, ...contextSpecs, ...explicitSpecs]);
}

验证结论：

• ✅ 可行性：基于规则的智能注入在技术上是可行的
• ✅ 价值：相比”全量注入”或”手动选择”，智能注入平衡了完整性和精准度
• ⚠️ 挑战：需要准确定义”任务类型”和”Spec 选择规则”

1.3 与现有方案的对比

2. 任务上下文隔离机制

2.1 任务结构设计

Trellis 的每个任务都有独立的上下文目录：

.trellis/tasks/task-001/
├── prd.md              # 产品需求文档（任务目标、验收标准）
├── context/            # 实现上下文
│   ├── files.md        # 相关文件列表
│   ├── decisions.md    # 决策记录
│   └── snippets/       # 关键代码片段
├── checklist.md        # 检查清单（完成标准）
├── state.json          # 任务状态机
└── journal.md          # 工作日志（时间线）

2.2 状态机设计

state.json 记录了任务的生命周期：

{
  "taskId": "task-001",
  "status": "in_progress",  // pending, in_progress, blocked, completed, cancelled
  "createdAt": "2026-03-04T10:00:00Z",
  "updatedAt": "2026-03-04T15:30:00Z",
  "assignedTo": "alice",
  "branch": "feature/task-001",
  "worktree": "task-001",
  "metadata": {
    "priority": "high",
    "estimatedHours": 8,
    "actualHours": 6.5,
    "tags": ["feature", "frontend"]
  },
  "checkpoints": [
    {
      "id": 1,
      "name": "PRD 评审",
      "completed": true,
      "completedAt": "2026-03-04T11:00:00Z"
    },
    {
      "id": 2,
      "name": "实现完成",
      "completed": true,
      "completedAt": "2026-03-04T14:00:00Z"
    },
    {
      "id": 3,
      "name": "代码审查",
      "completed": false
    }
  ]
}

状态流转：

pending → in_progress → blocked → in_progress → completed
                        ↓
                    cancelled

2.3 上下文隔离的实现

隔离层次：

1. 文件系统隔离：每个任务有独立的 context 目录
2. 分支隔离：每个任务对应独立的 git 分支
3. Worktree 隔离（可选）：物理隔离的执行环境
4. 内存隔离：Agent 会话的上下文不交叉

验证结论：

• ✅ 可行性：文件系统和 git 分支隔离技术成熟
• ✅ 价值：多任务并行时避免上下文污染
• ⚠️ 挑战：Worktree 管理增加复杂度，需要额外的存储和同步

3. Workspace Journal 记忆系统

3.1 Journal 的结构

.trellis/workspace/alice/
├── journal.md          # 连续的工作日志
├── sessions/           # 会话历史
│   ├── 2026-03-04-session-001.md
│   ├── 2026-03-04-session-002.md
│   └── ...
└── context/            # 个人上下文
    ├── preferences.md  # 个人偏好
    └── notes/          # 个人笔记

3.2 Journal 与 Session 的关系

Journal（日志）：

• 连续的、累积的工作记录
• 保留”上一次工作的脉络”
• 包含决策、踩坑、待办等

Session（会话）：

• 单次 AI 交互的记录
• 包含完整的对话历史
• 可追溯但不可修改

关系：

Session 001 → Session 002 → Session 003 → ...
     ↓             ↓             ↓
     └──────── Journal (聚合) ──┘

3.3 会话连续性实现

连续性机制：

1. 会话启动时：加载 Journal 的最新 N 条记录作为上下文
2. 会话进行中：实时记录关键决策和操作
3. 会话结束时：将本次会话的关键信息提取到 Journal

伪代码：

async function startSession(workspace, task) {
  // 1. 加载个人偏好
  const preferences = await loadPreferences(workspace.user);
  
  // 2. 加载最近 Journal 条目
  const recentJournal = await loadRecentJournal(workspace, 10);
  
  // 3. 加载任务上下文
  const taskContext = await loadTaskContext(task);
  
  // 4. 组合初始上下文
  return {
    systemPrompt: buildSystemPrompt(preferences),
    context: [recentJournal, taskContext].flat(),
    onDecision: (decision) => appendToJournal(decision),
    onComplete: (summary) => summarizeSession(summary)
  };
}

验证结论：

• ✅ 可行性：Journal 本质是追加日志，技术简单
• ✅ 价值：显著减少”从零开始解释”的成本
• ⚠️ 挑战：Journal 增长后的摘要和检索需要优化

4. 多平台适配层架构

4.1 支持的平台列表

Trellis 目前支持 9 个平台：

• Claude Code (.claude/)
• Cursor (.cursor/)
• OpenCode (AGENTS.md)
• iFlow (.iflow/)
• Codex (.codex/)
• Kilo (.kilocode/)
• Kiro (.kiro/)
• Gemini CLI (.gemini/)
• Antigravity (.antigravity/)
• Qoder (.qoder/)

4.2 适配器模式

统一接口：

interface PlatformAdapter {
  getName(): string;
  getSpecFormat(): SpecFormat;
  injectContext(context: Context): void;
  getSessionConfig(): SessionConfig;
}

适配器实现（以 Claude Code 为例）：

class ClaudeCodeAdapter implements PlatformAdapter {
  getName() { return 'Claude Code'; }
  
  getSpecFormat() {
    return {
      type: 'markdown',
      location: '.claude/CLAUDE.md',
      format: 'full-file'
    };
  }
  
  injectContext(context: Context) {
    // 写入 .claude/CLAUDE.md
    writeFile('.claude/CLAUDE.md', context.toMarkdown());
  }
}

4.3 配置生成

Trellis 初始化时会根据选择的平台生成对应的配置文件：

trellis init --cursor --opencode --codex -u alice

生成的结构：

project/
├── .trellis/               # 统一管理
├── .cursor/
│   └── rules.md           # Cursor 规则（从 Trellis Spec 生成）
├── AGENTS.md              # OpenCode 规则
└── .codex/
    └── config.md          # Codex 配置

验证结论：

• ✅ 可行性：适配器模式成熟，易于扩展新平台
• ✅ 价值：一次定义，多处复用，降低迁移成本
• ⚠️ 挑战：各平台能力差异大，需要对齐到”最小公分母”

5. Git Worktree 并行执行

5.1 Worktree 集成原理

Git Worktree 允许一个仓库有多个工作目录：

# 创建任务 worktree
git worktree add -b feature/task-001 ../.git/worktrees/task-001 main

# 进入 worktree 工作
cd ../.git/worktrees/task-001
# 这里可以独立修改文件、安装依赖、运行构建

5.2 Trellis 的 Worktree 管理

任务与 Worktree 映射：

.trellis/tasks/task-001/
  └── state.json
      {
        "worktree": "task-001",
        "branch": "feature/task-001",
        "path": "../.git/worktrees/task-001"
      }

并行执行流程：

1. 创建任务 → 创建分支 + worktree
2. 切换到 worktree → Agent 开始工作
3. 任务完成 → 提交代码 → 清理 worktree

验证结论：

• ✅ 可行性：Git Worktree 是成熟功能
• ✅ 价值：真正的物理隔离，避免依赖冲突、构建产物冲突
• ⚠️ 挑战：磁盘占用增加（每个 worktree 都有 node_modules 等）

6. 能力验证总结

6.1 核心能力可行性评估

6.2 关键设计洞察

1. 结构化胜过堆砌：Trellis 的核心价值不是”更多文档”，而是”更好的组织”
2. 隔离是关键：无论是任务、会话还是平台，隔离机制让系统可扩展
3. 记忆需要主动管理：Journal 不是自动产生的，需要明确的记录点
4. 适配器的力量：多平台支持不是魔法，是精心设计的适配器模式

6.3 与 pi-mono 的集成点

基于上述分析，pi-mono agent 助手可以从以下点切入：

1. 立即可以做的：

   • 引入分层 Spec 结构
   • 设计任务上下文数据模型
   • 实现基础的 Journal 机制

2. 中期可以做的：

   • 实现 Spec 智能注入
   • 建立任务状态机
   • 开发平台适配器

3. 长期可以做的：

   • Git Worktree 集成
   • 多平台支持
   • 生态系统建设

参考资料

• Trellis 官方文档
• Trellis GitHub 仓库
• Git Worktree 官方文档
• 适配器模式 - 维基百科