Trellis Cheatsheet

Trellis

Mindfold 的 AI 编码工程化框架。把 Spec、任务、记忆沉淀进仓库;按场景查命令,复制后可贴进终端或会话。

v0.6.17 npm @mindfoldhq/trellis 更新于 2026-09-14
复制按钮会复制可直接贴进终端或 Agent 会话的命令

最短记忆

Node.js ≥ 18,Python ≥ 3.9。先装 CLI,再在仓库里 init;0.6.17 升 CLI 后跑 trellis update 即可,无需 --migrate。

先装 CLI

全局安装最新版。旧 CLI 也可用 trellis upgrade。

npm install -g @mindfoldhq/trellis@latest

在仓库里初始化

-u 是开发者身份。可加平台 flag,如 --cursor --codex。

trellis init -u your-name

自然语言 + continue

描述需求 → AI brainstorm 写 PRD → 一路 continue 推进实现与检查。

/trellis:continue

做完再收尾

先 commit 工作改动,再 finish-work:归档任务并写 journal。

/trellis:finish-work

按场景查

先找当前要做的事,再复制对应命令。v0.6.16–0.6.17 新增消融、mem、rename、上下文门禁等已并入。

第一次给项目装 Trellis

创建 .trellis/、默认 Spec 模板,以及 00-bootstrap-guidelines 任务。别跳过 bootstrap。

initbootstrap
trellis init -u your-name --claude

给已有项目加平台

在已有 .trellis/ 上叠加平台配置目录,不新建任务。

platformcursor
trellis init --cursor --opencode --codex

新人 clone 已有 Trellis 项目

有 .trellis/ 但没有本机 .developer 时,会生成 00-join-<slug> 入职任务。

joineronboard
trellis init -u their-name

升级 CLI 和项目模板

两步:先升全局 CLI,再在项目里 sync。0.6.17 无 breaking,一般不用 --migrate;出现 MIGRATION REQUIRED 时再加。

upgradeupdate
trellis upgrade && trellis update

AI 卡住或跳步了

按当前 task 状态和 workflow breadcrumb 推进下一步。不必自己记阶段命令。

continue
/trellis:continue

会话结束 / 上下文快满

要求工作改动已 commit。会归档完成任务并追加 journal。

finish-workjournal
/trellis:finish-work

跨会话找回以前聊过什么

trellis mem 只读本地平台会话库。0.6.17 起支持 Cognition Devin CLI(--platform devin),别和 init --devin(Desktop)搞混。

memdevin
trellis mem search "deadlock" --global --limit 20

改任务 slug / 目录名

0.6.16+:task.py rename 会改目录、改写 task.json 身份与父子引用、以及 jsonl。先 --dry-run。

renametask
./.trellis/scripts/task.py rename add-login add-sso --dry-run

start 被空 jsonl 拦住

子代理平台上,空的 implement.jsonl/check.jsonl 会让 validate/start 失败。先 add-context 策展;刻意空跑才加 --allow-empty-context。

validatestart
./.trellis/scripts/task.py start "$DIR" --allow-empty-context

用 Spec 模板起步

官方 marketplace 或自定义 registry。已有 Spec 时用 --overwrite / --append。

templatespec
trellis init -u your-name --template electron-fullstack

临时对比有无 Trellis

消融会备份后移除项目级表面;对比完 restore。不同于永久 uninstall。

ablaterestore
trellis ablate --dry-run

手动创建 / 查看任务

通常 AI 会调 task.py。手操时 create 需要非空 --description(归档也会拒绝空描述)。

taskcreate
./.trellis/scripts/task.py list --mine

只关 hooks,不卸 Trellis

临时禁用会话注入 hooks。消融 / 卸载是更重的操作。

hooks
TRELLIS_HOOKS=0

Codex 要先开 hooks

否则 / 菜单看不到 Trellis 命令。开完再跑一次 /hooks 批准。

codexhooks
features.hooks = true # ~/.codex/config.toml

看当前上下文快照

身份、git 状态、活跃任务、Spec 索引。收尾模式用 --mode record。0.6.17:缺 session id 时不再自动绑到「项目里唯一会话」的任务。

contextsession
./.trellis/scripts/get_context.py

常用流程

把几条命令串起来,覆盖真实使用。

从零到第一次任务

装 CLI → init → 跑完 bootstrap 填 Spec → 用自然语言开第一个真实任务。

npm i -g @mindfoldhq/trellis@latest→trellis init -u you→bootstrap Spec→描述需求

日常一个完整任务

skill-first:你几乎只需要自然语言和两个 slash。

描述需求→/trellis:continue→…→/trellis:finish-work

跟上新版本

CLI 与项目模板版本分开。0.6.17 无文件迁移;有 breaking 变更再 --migrate。

trellis upgrade→trellis update→必要时 --migrate

内部四阶段循环

多数由 auto-trigger skill / sub-agent 自动跑,用户侧靠 continue 推进。

brainstorm→implement→check→update-spec

从旧会话捞上下文

先 projects/search 定位,再用 context/extract 抽对话。Devin CLI 加 --platform devin。

mem projects→mem search→mem context / extract

做有无 Trellis 的对照实验

消融后请新开 agent 会话;结束后精确恢复。

trellis ablate→新开会话对比→trellis restore

同一仓库服务多个 Agent

.trellis/ 核心共享;各平台只差 commands / skills / hooks 目录。

trellis init --claude→trellis init --cursor --codex

子代理任务:策展后再 start

create 会 seed 空 jsonl;策展 Spec/research 进 manifest,validate 通过后再 start。

create→add-context→validate→start

这些路径各管什么

搞混 Spec / Task / Workspace,是“AI 不记得项目约定”的最常见原因。

路径 装什么 谁写
.trellis/spec/ 项目编码规范与可执行契约。会话里按任务注入相关层。 你 + trellis-update-spec。建议版本化进 git。
.trellis/tasks/ 任务单元:task.json、prd.md、可选 design/implement、jsonl、research。 AI 经 task.py 创建;完成后进 archive/。
.trellis/workspace/{name}/ 个人会话 journal。跨会话记忆靠这里。 finish-work 调用 add_session.py 追加。
.trellis/workflow.md 开发工作流契约。每次会话起点。 Trellis 模板;可用 trellis update 同步。
.trellis/config.yaml packages、update.skip、任务生命周期 hooks、OMP prompt_injection.skip_keyword 等。 你。hooks 默认注释掉。
.trellis/.developer 本机开发者身份。gitignored,不进仓库。 trellis init -u 写入。新人 clone 后没有它。
.trellis/.runtime/sessions/ 每个 AI 会话/窗口的当前任务指针。缺 session id 时不再单会话 fallback 误绑(0.6.17)。 task.py start/finish;gitignored。
~/.claude · ~/.codex · ~/.local/share/devin/cli · … 各平台本机会话存储。trellis mem 只读索引,不写回。 平台 CLI;Trellis 不拥有这些文件。
.claude/ · .cursor/ · … 平台适配:commands、skills、agents、hooks。 trellis init / update 生成。

CLI 索引

在系统终端运行。权威来源是官方文档与 trellis --help。

命令 什么时候用 备注
trellis init -u name 首次装到仓库、加平台、或新人加入。 按 .trellis/ × .developer 三路分发。
trellis upgrade 升级全局 CLI package。 --tag latest / --dry-run。
trellis update 把项目模板同步到本地 CLI 版本。 breaking 时加 --migrate;0.6.17 不需要。
trellis mem … 跨平台检索本机 AI 会话(list / search / context / extract / projects)。 --platform claude|codex|devin|grok|opencode|pi|zcode|all。devin = Cognition CLI,不是 Desktop。
trellis ablate 临时移除项目级 Trellis 表面做对照。 先在项目外做恢复事务;建议 --dry-run。
trellis restore 从 ablate 事务精确恢复。 受管路径被改过会拒绝写入。
trellis uninstall 永久移除项目级 Trellis。 不同于 ablate / TRELLIS_HOOKS=0。
trellis --version 确认本地 CLI 版本。 和项目 .trellis/.version 可能不同。

Slash / Skill / Sub-agent

0.5+ 是 skill-first:用户侧主要记 continue 与 finish-work。平台调用写法略有差异。

名称 类型 什么时候用
/trellis:start Command 无自动注入的平台手动加载上下文。多数 hook 平台不装用户可见 start。
/trellis:continue Command 当前任务内推进下一步。Cursor 等写作 /trellis-continue。
/trellis:finish-work Command 工作 commit 之后:归档 + journal。工作区有未提交代码改动会拒绝。
trellis-brainstorm Skill 同意建任务后:逐题澄清需求,写 prd.md,需要时派 research。
trellis-before-dev Skill 动手改代码前自动读相关 Spec。
trellis-check Skill / Sub-agent 对照 Spec 审 diff,跑 lint / typecheck / test,自修复。
trellis-update-spec Skill 把决策 / 约定 / gotcha 写回 .trellis/spec/。
trellis-break-loop Skill 修完难 bug 后做 5 维根因与预防分析。
trellis-session-insight Skill 需要回忆旧会话时驱动 trellis mem(含 --platform devin 说明)。
trellis-implement Sub-agent 按 PRD + jsonl 上下文写代码,不 git commit。
trellis-research Sub-agent 只读搜索代码 / 文档;发现写入任务 research/。

task.py 速查

脚本在 .trellis/scripts/task.py。日常多由 AI 调用;下面是手操索引(含 0.6.16+ rename / 门禁)。

子命令 什么时候用 示例
create 新建任务目录 + 默认 prd.md。需要非空 --description;子代理平台 seed 空 jsonl。 task.py create "新增登录" --description "邮箱密码" --slug user-login -p P1
add-context 往 implement/check jsonl 加 Spec 或 research 路径(策展主路径)。 task.py add-context "$DIR" implement ".trellis/spec/…" "原因"
validate / list-context 校验 jsonl 引用存在;已 seed 但 0 条策展条目会失败。 task.py validate "$DIR"
start / current / finish 设置、查看或清除本 AI 会话的当前任务。空 jsonl 需 --allow-empty-context。 task.py start "$DIR"
rename 改 slug/目录,并重写身份、父子引用与 jsonl。 task.py rename add-login add-sso --dry-run
set-branch / set-scope / set-meta 写分支名、PR 目标、commit scope、任意 metadata。 task.py set-scope "$DIR" "auth"
add-subtask / remove-subtask 链接或解除父子任务。子任务是独立目录。 task.py add-subtask parent-dir child-dir
list / archive / list-archive 列活跃任务、归档、按月看归档。archive 会校验分支元数据;中断时会恢复子任务 parent 链接(0.6.17)。 task.py list --mine --status review

trellis mem 速查

只读本机会话。权威 flag 以 trellis mem help 为准。

子命令 什么时候用 示例
list 按时间列会话。无子命令时的默认行为。 trellis mem list --limit 20
search 关键词检索清洗后的对话(多 token 为 AND)。 trellis mem search "lock" --global
context 钻进单会话:命中 turn + 前后文,可限字符预算。 trellis mem context <id> --grep "auth" --turns 5
extract 导出清洗对话;可按 --phase brainstorm|implement|all 切片。 trellis mem extract <id> --phase brainstorm
projects 列出本机各项目 cwd 与会话数,便于再传 --cwd。 trellis mem projects
--platform 过滤平台。0.6.17:devin = ~/.local/share/devin/cli/sessions.db。 trellis mem list --platform devin

平台调用差异(摘)

同一语义,不同平台写法不同。完整表见官方 Appendix B。

平台 Continue Finish
Claude Code / OpenCode / Gemini / CodeBuddy / Droid /trellis:continue /trellis:finish-work
Cursor / Pi Agent / Qoder /trellis-continue /trellis-finish-work
Kiro @trellis:continue @trellis:finish-work
Kilo /continue.md /finish-work.md
Antigravity / Devin Desktop workflow picker → continue workflow picker → finish-work
GitHub Copilot Run Prompt → trellis-continue Run Prompt → trellis-finish-work
Codex skill / prompt(需 features.hooks) skill / prompt
使用习惯

先跑通 bootstrap 把 Spec 从空模板填成真实约定,再开业务任务。日常几乎只要自然语言 + continue;阶段 slash(如 before-backend-dev)在 0.5 已移除。升级永远是 upgrade(CLI)再 update(项目)——0.6.17 无需 --migrate。子代理任务务必策展 jsonl 再 start。对照实验用 ablate/restore,不要和 uninstall 搞混。mem --platform devin 读的是 Devin CLI 会话库,不是 init --devin。

已复制