先装 CLI
全局安装最新版。旧 CLI 也可用 trellis upgrade。
npm install -g @mindfoldhq/trellis@latest
Mindfold 的 AI 编码工程化框架。把 Spec、任务、记忆沉淀进仓库;按场景查命令,复制后可贴进终端或会话。
Node.js ≥ 18,Python ≥ 3.9。先装 CLI,再在仓库里 init;0.6.17 升 CLI 后跑 trellis update 即可,无需 --migrate。
全局安装最新版。旧 CLI 也可用 trellis upgrade。
npm install -g @mindfoldhq/trellis@latest
-u 是开发者身份。可加平台 flag,如 --cursor --codex。
trellis init -u your-name
描述需求 → AI brainstorm 写 PRD → 一路 continue 推进实现与检查。
/trellis:continue
先 commit 工作改动,再 finish-work:归档任务并写 journal。
/trellis:finish-work
先找当前要做的事,再复制对应命令。v0.6.16–0.6.17 新增消融、mem、rename、上下文门禁等已并入。
创建 .trellis/、默认 Spec 模板,以及 00-bootstrap-guidelines 任务。别跳过 bootstrap。
trellis init -u your-name --claude
在已有 .trellis/ 上叠加平台配置目录,不新建任务。
trellis init --cursor --opencode --codex
有 .trellis/ 但没有本机 .developer 时,会生成 00-join-<slug> 入职任务。
trellis init -u their-name
两步:先升全局 CLI,再在项目里 sync。0.6.17 无 breaking,一般不用 --migrate;出现 MIGRATION REQUIRED 时再加。
trellis upgrade && trellis update
按当前 task 状态和 workflow breadcrumb 推进下一步。不必自己记阶段命令。
/trellis:continue
要求工作改动已 commit。会归档完成任务并追加 journal。
/trellis:finish-work
trellis mem 只读本地平台会话库。0.6.17 起支持 Cognition Devin CLI(--platform devin),别和 init --devin(Desktop)搞混。
trellis mem search "deadlock" --global --limit 20
0.6.16+:task.py rename 会改目录、改写 task.json 身份与父子引用、以及 jsonl。先 --dry-run。
./.trellis/scripts/task.py rename add-login add-sso --dry-run
子代理平台上,空的 implement.jsonl/check.jsonl 会让 validate/start 失败。先 add-context 策展;刻意空跑才加 --allow-empty-context。
./.trellis/scripts/task.py start "$DIR" --allow-empty-context
官方 marketplace 或自定义 registry。已有 Spec 时用 --overwrite / --append。
trellis init -u your-name --template electron-fullstack
消融会备份后移除项目级表面;对比完 restore。不同于永久 uninstall。
trellis ablate --dry-run
通常 AI 会调 task.py。手操时 create 需要非空 --description(归档也会拒绝空描述)。
./.trellis/scripts/task.py list --mine
临时禁用会话注入 hooks。消融 / 卸载是更重的操作。
TRELLIS_HOOKS=0
否则 / 菜单看不到 Trellis 命令。开完再跑一次 /hooks 批准。
features.hooks = true # ~/.codex/config.toml
身份、git 状态、活跃任务、Spec 索引。收尾模式用 --mode record。0.6.17:缺 session id 时不再自动绑到「项目里唯一会话」的任务。
./.trellis/scripts/get_context.py
把几条命令串起来,覆盖真实使用。
装 CLI → init → 跑完 bootstrap 填 Spec → 用自然语言开第一个真实任务。
skill-first:你几乎只需要自然语言和两个 slash。
CLI 与项目模板版本分开。0.6.17 无文件迁移;有 breaking 变更再 --migrate。
多数由 auto-trigger skill / sub-agent 自动跑,用户侧靠 continue 推进。
先 projects/search 定位,再用 context/extract 抽对话。Devin CLI 加 --platform devin。
消融后请新开 agent 会话;结束后精确恢复。
.trellis/ 核心共享;各平台只差 commands / skills / hooks 目录。
create 会 seed 空 jsonl;策展 Spec/research 进 manifest,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 生成。 |
在系统终端运行。权威来源是官方文档与 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 可能不同。 |
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/。 |
脚本在 .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 |
只读本机会话。权威 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。