> ## 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.5

> 2026-06-25

补丁版本，包含 Trae IDE 支持、Pi Agent 启动上下文修复、Pi sub-agent tool 配置修复，以及 Windows channel session、hook、任务规划 gate 的可靠性改进。已有项目运行 `trellis update` 刷新即可，无需 `--migrate`。

## Highlights

### Trae IDE 平台支持

Trellis 现在把 Trae IDE 作为一等平台支持。

`trellis init --trae` 会写入：

* `.trae/commands/trellis-*.md`，带 frontmatter 的 slash commands
* `.trae/skills/`，workflow skills 和 bundled skills
* `.trae/agents/`，Trellis implement/check/research agents
* `.trae/hooks/`，共享 Python hooks
* `.trae/hooks.json`，注册 `SessionStart` 与 `UserPromptSubmit`

Trae 主会话通过 shared hooks 获取启动上下文和每轮 workflow context。Sub-agent context 走 class-2 pull-based prelude，因为 Trae 目前没有 Trellis 可用的 sub-agent prompt mutation surface。

内置 workflow 现在会把 class-2 implement dispatch（codex-sub-agent、Gemini、Qoder、Copilot、ZCode、Reasonix、Trae）保持在 pull-based block，而不是 hook auto-handles block。这样 workflow 文案与生成出来的 pull-based sub-agent context loading 保持一致。

### Pi Agent 启动上下文

Pi Agent 的 `session_start` 事件是 notify-only，不能直接注入 model-visible context。0.6.5 把启动 payload 移到每个 Trellis context key 的第一次 `before_agent_start`。

新的 Pi session 现在会在 `systemPrompt` 中收到紧凑的 Trellis 启动上下文：workflow state、session overview、active-task status、紧凑 workflow index，以及 first-reply notice。`.pi/prompts/trellis-start.md` 仍然保留为手动 fallback。

### Pi sub-agent tools

生成的 `.pi/agents/trellis-*.md` 现在可以用 `tools` frontmatter 声明 `trellis_subagent` 需要的工具。Tool names 会统一转成小写，同时移除未生效的 `PI_TOOL_ALLOWLIST` 路径，确保 Pi 收到它期望的 tool names。

## Reliability Fixes

### Windows channel sessions

Channel session 启动前会把 Windows npm `.cmd` shim 解析到可 spawn 的 executable path，修复 supervisor 尝试启动不存在的 `.exe` 路径导致的失败。

### Hooks and planning gates

共享 Python hooks 在 stdin 为空时不再阻塞。

ZCode command fallbacks 现在保留在 `.zcode/commands/trellis/`，不再写入共享的 `.agents/skills/` 目录。这样 Codex + ZCode 组合安装后，`trellis update --dry-run` 不会立刻报告 template drift。

Trellis 同时加强了任务 readiness：

* `workflow.md` 要求先整理好 `implement.jsonl` / `check.jsonl` context，再进入实现。
* `brainstorm` 要求 PRD lossless convergence 后再继续规划，避免迭代整理任务时丢掉已有需求。

## Internal

CI 现在会在 marketplace submodule pointer 变化时运行；marketplace workflow mirror 也已同步 Trae 支持。

## Upgrade

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

无需 `--migrate`。

* **Trae** 用户：尚未配置 `.trae/` 的项目运行 `trellis init --trae`；已有 Trellis 项目运行 `trellis update`。
* **Pi** 用户：运行 `trellis update` 获取生成的 start prompt 和 extension startup-context 更新。
* **Windows channel** 用户：启动新的 channel session 前先安装最新 CLI。