> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trytrellis.app/llms.txt
> Use this file to discover all available pages before exploring further.

# v0.6.0-beta.23

> 2026-06-08

## Enhancements

### Channel runtime agent 定义在 init/update 时自动落盘

`trellis init` 和 `trellis update` 现在会落盘 `.trellis/agents/{check,implement}.md`——这就是 `trellis channel spawn --agent <name>` 在运行时加载的 bundled agent 定义。

* 模板：`packages/cli/src/templates/trellis/agents/{implement,check}.md`
* Dispatch：`packages/cli/src/configurators/workflow.ts` 里的 `createWorkflowStructure`
* Update 刷新：`packages/cli/src/templates/trellis/index.ts` 里的 `getAllAgents()`，通过 `packages/cli/src/commands/update.ts` 的 `collectTemplateFiles` 接入

此前切到 channel-driven 工作流（`trellis workflow --template channel-driven-subagent-dispatch`）之后跑 `trellis channel spawn --agent check` 会运行时报 `Agent 'check' not found`，因为没有命令负责落盘这两个文件。它们是平台无关的，无论 `--workflow` / `--<platform>` 怎么选都会被 init 落盘。`trellis update` 的常规 hash/conflict 流程会给那些在 bundled 文件存在之前就装过的项目补齐缺失项（#323）。

### Registry-backed `.trellis/spec` 通过 `trellis update` 刷新

`trellis init --template <id>` 现在会把 spec 来源和 template id 持久化到 `.trellis/config.yaml` 的新 `registry.spec` 块。`trellis update` 会读这一块，把配置的 spec registry 下载到临时目录，再走 hash / conflict / "modified by you" 的现有流程，让 registry-backed 的 spec 模板与标准 CLI 模板一起保持同步。

* 新增工具：`packages/cli/src/utils/registry-config.ts`
* `init.ts` 和 `update.ts` 扩展以读写持久化的 registry config
* 支持直接的 spec registry 和 marketplace 风格 registry，包含 SSH 与自建 Git 源

关联 #315。

### 新增 Reasonix (DeepSeek-Reasonix) 平台支持

新增 Reasonix 作为第 15 个受支持的 AI 编码工具，通过 `trellis init --reasonix` 启用。Reasonix 以 `.reasonix/skills/<name>/SKILL.md` + YAML frontmatter 的形式存储 skill；slash command 是平台内建的，所以不会单独生成 `commands/` 目录。

* 新增 configurator：`packages/cli/src/configurators/reasonix.ts`
* 新增模板模块：`packages/cli/src/templates/reasonix/`
* 新增 CLI flag：`--reasonix`
* `{{CMD_REF:start}}` 在 Reasonix 下通过新增的 `cmdRefPrefix` `/skill trellis-` 解析为 `/skill trellis-start`

子代理 skill（`trellis-implement`、`trellis-check`）使用 `runAs: subagent` frontmatter，Reasonix 会把它们当作隔离的子代理循环来跑，而不是行内 slash skill。关联 #301。

### `trellis-session-insight` bundled skill

`packages/cli/src/templates/common/bundled-skills/trellis-session-insight/` 下的新 bundled skill 教 AI 何时该调 `trellis mem` CLI（过往解法回忆、决策回溯、跨会话续作、似曾相识的 bug、自身模式识别、finish-work 回顾），并**有意**不固定一个写回的文件。

`mem` 返回的原始材料怎么处置 —— 行内引用、更新 `prd.md` / `design.md`、追加到 task notes、只在脑里参考、还是交棒给 `trellis-update-spec` —— 由 AI 当下判断。参考：

* `references/cli-quick-reference.md` —— 完整的 `trellis mem` flag 参考。
* `references/triggering-patterns.md` —— 中英文用户原话样例，按意图分组校准 AI 直觉。

每个支持的平台在 `trellis init` 和 `trellis update` 时通过现有 `getBundledSkillTemplates()` 目录扫描自动落盘。

### Workflow 模板缺失 agent 时给提示

`trellis workflow --template <id>` 和 `trellis init --workflow <id>` 现在会在解析出的 `workflow.md` 引用了磁盘上不存在的 `.trellis/agents/<name>.md` 时输出一条**非阻塞**的 stderr 警告。检测逻辑在 `packages/cli/src/utils/agent-refs.ts`，同时识别 `--agent <name>` flag 形式和 workflow 正文中 `.trellis/agents/<name>.md` 字面路径引用。警告会指引用户运行 `trellis update` 补齐 bundled 集合，**不会**中断 workflow 切换。

## Bug Fixes

### Bundled skill 重命名：`trellis-spec-bootstarp` → `trellis-spec-bootstrap`

Bundled 的 spec-bootstrap skill 之前是个 typo 拼写。本次修复同时重命名源模板和每个平台已安装的目录。

* 源模板重命名：`packages/cli/src/templates/common/bundled-skills/trellis-spec-bootstarp/` → `trellis-spec-bootstrap/`
* 内部 `name:` frontmatter 字段同步修正。
* 测试引用更新。

对于已经装过 typo 拼写目录的用户，本次发版在 0.6.0-beta.23 manifest 里附带了一个 `rename-dir` migration，覆盖 13 个平台 skill 根目录：

| 平台                      | Skill 根目录            |
| ----------------------- | -------------------- |
| Claude Code             | `.claude/skills/`    |
| Cursor                  | `.cursor/skills/`    |
| OpenCode                | `.opencode/skills/`  |
| Codex + Gemini CLI (共享) | `.agents/skills/`    |
| Kiro                    | `.kiro/skills/`      |
| Qoder                   | `.qoder/skills/`     |
| CodeBuddy               | `.codebuddy/skills/` |
| GitHub Copilot          | `.github/skills/`    |
| Droid                   | `.factory/skills/`   |
| Pi Agent                | `.pi/skills/`        |
| Antigravity             | `.agent/skills/`     |
| Windsurf                | `.windsurf/skills/`  |
| Kilo                    | `.kilocode/skills/`  |

运行 `trellis update --migrate` 即可应用迁移。本机没安装的根目录会被静默跳过。

历史 migration manifest `src/migrations/manifests/0.5.17.json` 和 `src/migrations/manifests/0.6.0-beta.18.json` **有意**保留 typo 文本 —— 它们记录的是当时实际发给用户的内容，且对查找老版本安装的人保持可 grep。关联 #296。

## Upgrade

```bash theme={null}
npm install -g @mindfoldhq/trellis@beta
trellis update --migrate
```

本次发版建议使用 `--migrate`，因为有上文的 `rename-dir` migration。不加 `--migrate` 也会装上新的 `.trellis/agents/*.md` runtime 文件和 `trellis-session-insight` bundled skill，但旧的 `trellis-spec-bootstarp/` 目录不会被改名。