开源 cursor-trellis：为 Cursor 深度适配的 Trellis 工作流工具

背景

Trellis 是一个基于 AI 的自动化开发工作流框架，旨在通过结构化的任务分解、子代理（subagent）协作以及严格的上下文管理来提升代码实现的效率与质量。然而，Trellis 原生设计主要面向通用 CLI 环境或特定 IDE（如 Claude Code），在接入 Cursor 这一以“原生 AI 通道”和高度定制化著称的代码编辑器时，存在适配层面的摩擦。

Cursor 提供了独特的 API 机制（包括 Native API 和 BYOK 模式下的 Cursor++），其会话注入、模型路由、技能加载（Skills）以及工具调用（Hooks）的方式与传统开发工具链存在显著差异。直接运行原生 Trellis 往往面临模型指定失效、上下文注入失败、技能列表冗余干扰等问题。

cursor-trellis 正是在此背景下诞生的开源适配项目。它并非重写 Trellis 的核心逻辑，而是作为一层“适配层”，将 Trellis 的框架语义通过 Cursor 的原生通道重新实现，解决了在 Cursor 环境中高效运行 Trellis 工作流的兼容性难题。

核心内容

cursor-trellis 的核心工作流依然遵循 Trellis 的设计哲学，但针对 Cursor 的特性进行了深度定制。其核心改动主要体现在以下五个方面：

1. Cursor Native 与 Cursor++ 的双环境适配

项目明确区分了两种 Cursor 使用环境，并提供了不同的配置策略：

• Native Cursor API：利用 Cursor 内置的 API 通道。在此模式下，trellis-* 相关的模型配置对 Agent frontmatter 生效，且支持 Settings 中每 Agent 模型的 UI 配置。
• Cursor++ (BYOK)：基于 Bring Your Own Key 的增强模式。在此模式下，Agent frontmatter 中的模型配置被忽略，Settings 中的 overrides 也不填充。

模型路由的痛点与解决方案： 在 Cursor++ 环境下，尝试让 trellis-* 固定使用特定模型非常困难，因为标准配置会被忽略。项目采用了一种“补丁”策略：

• 使用 patch_wpelc8.py 脚本配合 ~/.ccursor/trellis-task-models.json5 配置文件。
• 该方案通过 patch resolver 本身来实现模型固定，具有可逆性。
• 注意：每次 Cursor 更新后，都需要重新执行 patch 操作。Native 用户则无需此步骤。

初始化命令 trellis init --cursor 默认针对 Native 环境，若使用 Cursor++ 需添加 --cursor2plus 参数。

2. 简化的命令接口与技能语义传递

为了解决在 Cursor 中安装 Trellis 后，斜杠命令（/）下拉列表中技能过多、造成视觉干扰的问题，项目采用了“命令仅暴露”策略：

• 内部技能隐藏：如 trellis-brainstorm 等内部技能不写入 .cursor/skills/ 目录。
• 精简命令入口：仅向用户暴露三个核心命令：
  • /trellis-continue
  • /trellis-finish-work
  • /trellis-cursor2plus-setup
• 语义传递机制：技能的详细语义通过 .cursor/rules、AGENTS.md 以及 workflow.md 传递，由工作流匹配器自动加载。这种方式既保持了工作流的完整性，又保持了用户界面的整洁。

3. Subagent 派发与执行策略

项目定义了三个核心的 Subagent 角色，并设计了精细的执行策略：

• 角色定义：
  • trellis-research：负责内外部研究。
  • trellis-implement：仅负责代码实现。
  • trellis-check：独立审查，确保通过。
• 派发逻辑：主会话仅在 execution_mode: worker 时才派发实现或审查 Subagent。
• 执行策略配置：在 implement.md 中，通过 YAML 块定义 execution_mode、isolation 和 verification_profile，以决定谁负责实现、谁负责检查以及隔离方式。
• 数据驱动建议：规划阶段可运行 task.py suggest-execution-strategy <task> 获取建议。通常文档操作和研究任务会走 inline 模式。
• 上下文加载双路径：
  1. 主路径 (CLI Layer 2)：在派发前，通过 task.py generate-dispatch-prompt 将 PRD/Spec/Research 预嵌入派发 Prompt，并打上 <!-- trellis-hook-injected --> 标记。
  2. 辅助路径 (Hook)：preToolUse Hook 作为 best-effort 补充。如果标记已存在则跳过。
  3. Subagent 行为：Subagent 见到标记直接执行；若未见到，则从 Selected task: <path> 手动读取 jsonl 和工件。
  • 此机制在 Native 和 BYOK 环境下通用，与模型路由无关。

4. 检索层设计

检索层采用了分层路由策略，以平衡准确性与成本：

• 外部事实检索：优先使用项目内的 smart-search CLI。仅在 smart-search 不可用时，才回退到 Cursor 自带的 WebSearch 或 WebFetch。
• 本地/代码库检索：
  • 精确串/路径：使用 Grep。
  • 调用链/影响面：使用 codegraph。
  • 跨包同名消歧：使用 codegraph。
  • 概念级检索（如“这项目怎么工作”）：Native 环境使用内置的 @codebase；BYOK 环境使用 fast-context-mcp。
• 计划块注入：由 beforeSubmitPrompt Hook 注入，并由 .cursor/rules 兜底。

5. 联网搜索依赖

项目依赖配套的 smart-search 工具进行外部事实检索。安装 cursor-trellis 时会自动安装 smart-search。该工具基于站内版本进行了微调，主要增加了双语搜索支持，并削减了一些搜索服务以优化性能。

关键要点

• 环境隔离：必须明确区分使用 Native Cursor API 还是 Cursor++ (BYOK)，两者在模型配置、技能加载和 Patch 需求上完全不同。
• 模型固定难点：在 Cursor++ 中固定 trellis-* 模型需要手动 Patch resolver，且每次 Cursor 更新后需重新 Patch，这是目前的主要维护成本。
• 界面优化：通过隐藏内部技能、仅暴露核心命令，解决了 Cursor 中技能列表过载的问题，提升了用户体验。
• 上下文注入机制：采用“预嵌入 Prompt + 标记 + Hook 补充”的双路径机制，确保 Subagent 能获取足够的上下文，同时兼容不同环境。
• 检索分层：外部搜索优先使用专用的 smart-search，本地代码搜索根据意图（精确、图谱、概念）路由到不同工具，避免盲目调用大模型检索。
• 自动化安装：smart-search 作为依赖自动安装，降低了用户配置联网搜索的门槛。

意义与影响

cursor-trellis 的出现填补了 Trellis 工作流在 Cursor 编辑器生态中的适配空白。它证明了复杂的 AI 辅助开发框架可以通过精细的适配层，无缝融入具有独特 API 机制的现代 IDE。

对于开发者而言，该项目提供了一种在 Cursor 中高效运行结构化 AI 工作流的成熟方案，特别是解决了模型路由、上下文管理和技能干扰等痛点。对于 Trellis 社区，它扩展了框架的兼容性，使其能够覆盖更广泛的编辑器用户群体。此外，其对检索层的分层设计和对 Cursor Hook 机制的深度挖掘，也为其他 AI 开发工具的适配提供了有价值的参考案例。