跳转到主要内容

​
通用

npm install -g @mindfoldhq/trellis@latest，在你的项目下面用 trellis init 进行初始化，然后就可以直接开始使用了。
  1. Claude Code / iFlow 用户 — 打开一个新会话就可以直接开始使用。session start hook 会自动注入 AI 所需的所有信息（Trellis 工作流程、最近的 git 提交、最近的 journal 记录、项目上下文）。说需求，AI 会自动创建 task、生成 PRD、加载相关 spec 规范，然后委派给专门的 agent（implement、check 等）去干活。验收通过后用 /trellis:record-session 记录日志。也可以手动执行 /trellis:start 了解完整流程。
  2. OpenCode 用户 — 跟 Claude Code 类似。session start 插件会在你第一条消息时自动注入上下文。用 /trellis:start 开始，然后按流程：说需求 → AI 加载 spec → 干活 → /trellis:check-backend 或 /trellis:check-frontend 自检 → /trellis:record-session 记录。要完整支持多 agent 流水线，需要安装 oh-my-opencode 全局插件。
  3. Cursor 用户 — 用 trellis init --cursor 初始化。Cursor 目前不支持 hooks，所以每次会话需要手动触发 /trellis-start。流程：/trellis-start → /trellis-before-backend-dev 或 /trellis-before-frontend-dev 加载规范 → 干活 → /trellis-check-backend 或 /trellis-check-frontend 自检 → /trellis-record-session 记录。注意 Cursor 命令用 - 而不是 :。
  4. Codex 用户 — Codex 使用 skills（$ 前缀）而不是 slash commands。流程：$start → $before-backend-dev 或 $before-frontend-dev → 干活 → $check-backend 或 $check-frontend → $record-session。
  5. 其它工具（Trae、Windsurf 等） — 可以根据自己用的 IDE/CLI 手动创建对应的 slash command，然后按 Cursor 类似的流程使用。
安装（推荐全局安装）：
npm install -g @mindfoldhq/trellis@latest
验证安装：
trellis --version
在项目中初始化：
trellis init                # （推荐）交互式，逐项确认
trellis init -y             # 跳过确认，使用默认配置
trellis init -u {username}  # 同时设置开发者身份（不加此参数会自动从 .git/ 读取默认配置）
trellis init -f             # 强制覆盖已有文件
trellis init -s             # 跳过已有文件
版本切换与更新：
trellis update                    # 对比版本差异并更新
trellis update --migrate          # 应用文件重命名/删除等迁移
回退到正式版： npm install -g @mindfoldhq/trellis@latesttrellis update 永远不会覆盖 .trellis/workspace/、.trellis/tasks/、.trellis/.developer、.trellis/spec/frontend/、.trellis/spec/backend/ — 这些路径受保护。并且每次 update 时，.trellis/、.cursor/、.claude/ 等目录下的所有内容都会自动生成一个备份保存在 .trellis/.backup-* 目录下，无需担心更新会破坏原有结构。
Skills 是可选的 — AI 可能跳过它们，导致质量不一致。Trellis 通过注入来强制执行规范。不管 AI “想不想”，每次会话都会拿到规范。
AI 通常根据你的指示来生成规范。但当你有 AI 无法独立弄明白的架构洞察时，你应该参与进来 — 比如”我们用这个错误格式是因为 X 历史原因”或者”这个模式存在是因为 Y 约束”。
那些格式每次都加载全部内容。如果你有 50 页规范，每个会话都读全部 50 页。Trellis 用分层架构和上下文压缩。JSONL 文件指定哪个任务加载哪些规范。你的认证功能加载认证规范。你的 UI 组件加载前端规范。噪音少，信号多。
不会。每个团队成员在 .trellis/workspace/{name}/ 有隔离的工作区。你的日志是你的。队友的日志是他们的。规范是共享的，这正是重点 — 所有人遵循同样的约定。
用 /trellis:record-session 让 AI 把摘要写到日志文件。下次会话开始时，它读取最近的日志和 git 信息来恢复上下文。这不是魔法记忆。是明确的日志记录。你控制什么被记住。
支持。运行 trellis init --cursor 来配置 Cursor 专用命令。Trellis 会创建 .cursor/commands/，包含所有命令（如 /trellis-start、/trellis-finish-work）。注意 Cursor 的命令用 - 而不是 :。Hooks：Cursor 目前不支持自动注入 hooks，所以每次会话开始需要手动触发 /trellis-start。Multi-Agent（同目录多 agent）：有限支持，需手动协调。Multi-Session（worktree 隔离）：不支持。

​
Specs 规范

短到能在 30 秒内扫完。如果更久，拆成多个文件。AI 会读整个规范，但规范太长时每部分得到的注意力就少。
常见原因：
  1. 太模糊 — “用好的错误处理”没意义。加上带代码例子的具体模式。
  2. 没例子 — 放实际代码。AI 从例子学比从描述学更有效。
  3. 路径过时 — 如果你引用的文件不存在了，规范就让人困惑。
  4. 规则冲突 — 两个规范说了不同的事。选一个。
测一下：开新会话，让它写规范覆盖的代码，看规则有没有被遵循。
可以。文档风格、commit message 格式、PR 模板、API 设计模式 — 任何你想保持一致的东西。

​
Tasks 和 Workspace

不用。任务在需要追踪和上下文隔离时有帮助。快速修复不需要任务。多天的功能开发有任务会受益。
会话在没有任务特定上下文的情况下运行。规范还是会从默认值加载，但 AI 不知道你的 PRD 或任务特定的文件。做任务相关的工作时，先用 /trellis:start 命令开始会话。
每行指定一个要包含的文件：
{"file": ".trellis/spec/backend/index.md", "reason": "后端编码规范"}
{"file": "src/api/users.ts", "reason": "API 实现上下文"}
不同 agent 拿到不同的文件。implement agent 可能比 check agent 需要更多上下文。

​
多 Agent

没有硬性限制，但实际受限于：
  • API 额度（每个 agent 消耗 token）
  • 你审查输出的能力
3-5 个 agent 可控。再多就难跟踪了。
取决于运行模式：
  • Multi-Agent（同目录）：agent 共享同一目录，可能产生冲突。规划任务时避免文件重叠。
  • Multi-Session（worktree）：每个 agent 在独立的 Git worktree 工作，开发过程不冲突。合并 PR 时再解决冲突。

​
问题排查

Trellis 在后台工作。没有 UI 变化。验证：
  1. .trellis/ 目录存在
  2. .claude/settings.json 有 hook 配置
  3. 开个会话 — 规范应该出现在上下文里
可能的原因：
  1. 规范没加载：检查 .trellis/spec/ 和 JSONL 上下文文件的路径
  2. 对话太长：AI 可能在长对话中「忘记」规范。开新会话或提醒它
  3. 规范清晰度：具体的规范比模糊的更有效
Trellis 能提升一致性，但不是银弹。AI 仍然会犯错。
先更新 CLI：
npm install -g @mindfoldhq/trellis@latest
然后更新项目：
trellis update
这只动没改过的文件，你改的东西不会丢。受保护路径（永远不会被覆盖）：.trellis/workspace/、.trellis/tasks/、.trellis/.developer、.trellis/spec/frontend/、.trellis/spec/backend/。自动备份：每次 update 都会将 .trellis/、.cursor/、.claude/ 等目录的内容备份到 .trellis/.backup-*，无需担心破坏性更新。有破坏性改动（比如目录结构调整）时，加 --migrate：
trellis update --migrate
这会执行文件迁移 — 重命名和删除旧文件来适配新结构。改过的文件会先问你再动。