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

> 2026-06-15

`0.6.0-rc.0` 的稳定版升级，src/ 无新增改动。v0.6.0 相对 0.5.x 是 breaking release —— `trellis channel` 多 agent 协作运行时、`trellis mem` 跨会话记忆 CLI，以及把 channel / task / mem 原语提取到 `@mindfoldhq/trellis-core` SDK。

<Tip>
  **多 agent 协作在 v0.6 升为一等原语。** `trellis channel` 提供 worker-supervisor 运行时（Claude
  `stream-json` + Codex `app-server` adapter）、`~/.trellis/channels/` 下的持久事件日志、forum /
  thread 风格 issue 板、默认 OOM 防护，以及 `@mindfoldhq/trellis-core/channel` 暴露的生命周期 / 订阅
  API。`trellis init` / `trellis update` 现在会把内置的 `check` / `implement` agent
  定义自动下发到每个新装项目，因此 `trellis channel spawn --agent check` 开箱即用。详见下方 "[多
  agent 协作](#多-agent-协作)" 段。
</Tip>

<Note>
  **Codex 用户 —— 0.6.0 升级注意事项：**

  * **`[features.multi_agent_v2]` 块在 0.6.0 移除（beta.21）** —— Codex CLI 在 0.130 与 0.131 之间改了 `features` 反序列化协议，结构化表格只在 0.131+ 加载；0.130 及更早（含 Codex 桌面版自带 CLI）会报 `data did not match any variant of untagged enum FeatureToml…` 并中断 config 加载。`trellis init` / `trellis update` 不再写这个块 —— 使用 Codex 自身默认值。如有需要请在 `~/.codex/config.toml` 自行调整。
  * **`codex.dispatch_mode: inline` 成为默认（beta.1）** —— Codex sub-agent 跑 `fork_turns="none"` 隔离模式，无法继承父会话的 task 上下文。现在主 Codex agent 直接改代码。需要 sub-agent dispatch 可在 `.trellis/config.yaml` 设置 `codex.dispatch_mode: sub-agent` 重新开启。
</Note>

<Note>
  **0.6.0 新支持平台：**

  * **Reasonix（DeepSeek-Reasonix）** —— 第 15 个支持的 AI 编码工具，通过 `trellis init --reasonix` 启用。Skills 放在 `.reasonix/skills/<name>/SKILL.md`；slash 命令是平台内建。Sub-agent 形态 skill 带 `runAs: subagent` frontmatter 跑隔离 subagent 循环。关闭 `#301`。
  * **Pi Agent —— 原生 `trellis_subagent` 扩展** —— Pi 暴露 `trellis_subagent`（避开与社区包 `subagent` 的命名空间冲突），支持 `single` / `parallel` / `chain` dispatch 模式、原生进度卡片（`Alt+O` 详情视图）、节流实时更新、Trellis-agent 校验。关闭 `#286`、`#290`。
</Note>

<Note>
  **OpenCode 用户 —— reader 暂时不可用：**

  * **`trellis mem` 在 OpenCode 1.2+ 返回空** —— OpenCode 1.2 把会话存储改为 SQLite。beta.3 加了 SQLite reader 但其 `better-sqlite3` 原生依赖在无 C 工具链的机器上安装失败，beta.4 已回退。`trellis mem list / search / extract` 在 OpenCode 路径上返回空并打印一次性 stderr 警告；Claude 与 Codex 路径不受影响。完整 OpenCode reader 重做延后到 v0.6.0 之后。
</Note>

<Warning>
  **GA 切口的已知上游问题（Trellis 侧暂不修复）：**

  * **OpenCode 1.2+ SQLite 会话 reader** —— 详见上方 `<Note>`，追踪到 v0.7+。
  * **延后到 v0.6 之后的 feature 请求** —— `#193`、`#318`、`#320`、`#325`、`#326` 等 tracker item 按 `rc.0` 切口明确推到 v0.7 或更晚。
</Warning>

## 多 agent 协作

### Channel runtime —— 初版 CLI + adapter + 事件存储

`trellis channel create | send | wait | spawn | run | list | messages | kill | rm | prune` 是 v0.6 的核心新增。Claude `stream-json` 与 Codex `app-server` JSON-RPC adapter 把 provider 输出统一归一为 `message` / `progress` / `done` / `error` 事件，落盘到 `~/.trellis/channels/<project>/<channel>/events.jsonl`，序号通过 lock 文件原子分配。

### Thread / forum channel —— 持久 issue 板 / 论坛

事件型 channel 是一次性流；`--type threads` 与 `--type forum` 提供持久的 issue / thread 风格讨论板，单 thread 有稳定 context：

* `channel post | threads | thread | forum` 子命令族
* `channel context add | delete | list` 管理稳定上下文
* `channel title set | clear`、`channel thread rename`
* 事件可携带 `--description`、`--context-file`、`--context-raw`（兼容旧的 `--linked-context-*` 别名）

### `--scope project|global` 解析

每个 channel 子命令都接受 `--scope project|global`，显式指定存储到项目桶还是全局桶 —— 之前只能写项目桶。

### Worker 协调 —— wait 多 kind 过滤、超时预警、inbox API

* `channel wait --kind done,killed` 支持多 kind 过滤
* `channel spawn --warn-before <duration>` 在结束前发出 `supervisor_warning` 事件（默认 5 分钟提前量，`0ms` 可关闭）
* `@mindfoldhq/trellis-core/channel` 导出 worker 生命周期 / 订阅原语：`listWorkers`、`watchWorkers`、`spawnWorker`、`requestInterrupt`、`interruptWorker`、`readChannelEvents`、`watchChannels`、`readWorkerInbox`、`watchWorkerInbox`、`WorkerInboxError`、`matchesInboxPolicy`
* Codex worker 在 `done` 之前先记录完成的回答，且对非 interrupt 轮做 turn 序列化（`turn_started` / `turn_finished` / `interrupt_requested` / `interrupted`）

### Channel worker OOM 防护

长期运行的 worker 进程可能堆积撑爆内存。新增默认守卫：`channel.worker_guard.idle_timeout`（5 分钟）与 `channel.worker_guard.max_live_workers`（6）。每次 spawn 可通过 `--idle-timeout` / `--max-live-workers` 覆盖，也可走环境变量（`TRELLIS_CHANNEL_WORKER_IDLE_TIMEOUT`、`TRELLIS_CHANNEL_MAX_LIVE_WORKERS`）。空闲 worker 被 kill 时事件 `reason: "idle-timeout"`；turn 中的 worker 不会被 kill。

### 消息路由清理 + 持久 idempotency

| 旧                                                      | 新                                                                              |
| ------------------------------------------------------ | ------------------------------------------------------------------------------ |
| Tag-based 路由跨 `send.ts` / `wait.ts` / provider adapter | Tag 仅保留在 channel events、worker inbox policy 与显式 `to` 上                         |
| 重复写入产生重复 `undeliverable` 事件                            | `sendMessage` 与 `postThread` 支持 `idempotencyKey`：同 key 重写返回原始 JSONL 事件，不产生 dup |
| Interrupt 走通用 adapter 编码                               | Interrupt 独立 adapter 编码                                                        |

### Codex streaming deltas

Codex channel worker 现在透出 streamed `item/agentMessage/delta` 内容，progress 事件携带 `detail.kind`（`output|commentary|reasoning`）、`detail.stream_id`、`detail.phase`、`detail.text_delta`。消费者按 `stream_id` 聚合 delta，把 `kind:"message"` 作为最终完整答案。

### Channel runtime agent 定义自动下发

`trellis channel spawn --agent check` 之前会在切换到 `channel-driven-subagent-dispatch` 工作流后报 `Agent 'check' not found` —— 因为没有命令负责下发 `.trellis/agents/{check,implement}.md`（关闭 #323）。现在 `trellis init` / `trellis update` 默认把平台无关的 `.trellis/agents/{check,implement}.md` 写到每个新装项目。`trellis workflow --template <id>` 在工作流引用了缺失的 `.trellis/agents/<name>.md` 时打印非阻塞警告（检测见 `utils/agent-refs.ts`）。

## Memory (`trellis mem`)

### 初版 `trellis mem` CLI

AI 之前无法回忆 Claude Code / Codex / OpenCode 的历史会话内容 —— 历史只锁在各平台磁盘格式里。新增 `trellis mem list | search | context | extract | projects` 直接读各平台的会话文件，剥离 hook 注入 / AGENTS.md 前言 / 工具调用噪声，支持 `--since`、`--cwd`、`--platform`、`--json` 过滤。处理 Claude compaction 摘要与 Codex compacted 事件。84 个单元测试；语句覆盖率 81.89%。

### `--phase brainstorm|implement|all` 切片

AI 回忆某个历史 task 时往往只想要规划讨论或只想要实现部分，不需要全 transcript。`mem extract <id> --phase brainstorm` 切 `task.py create` 到 `task.py start` 之间；`--phase implement` 是反过来；`--phase all` 是默认。多 task 会话以 `--- task: <slug> ---` 分隔。Claude 和 Codex 支持；OpenCode 回退到完整对话。`mem list` / `mem extract` 速度提升 5–9×。`--phase` 解析器处理 `$(... --slug NAME)` 替换、单条 Bash 命令多次调 `task.py`、以及 commit-message heredoc 里出现 `task.py start`。

### 跨日 session 窗口正确性

29MB Claude 会话从 N–1 日开始、仍在 N 日写入时，`--since <N 日>` 返回 0 条匹配，尽管会话当日实际写了 19 条匹配 turn。过滤逻辑从 "session 创建时间落在区间" 改为 `inRangeOverlap(start, end, filter)` —— `[created, updated]` 与 `[since, until]` 有交集就匹配。移除了错误优化的 codex filename-ts 短路。新增 23 个测试覆盖 5 种区间关系 × 3 个平台。

### OpenCode 1.2+ reader → 降级

beta.3 加了 SQLite reader，但 `better-sqlite3` 原生依赖在无 C 工具链的机器上安装失败，beta.4 回退。OpenCode 路径的 `tl mem list / search / extract` 现在返回空并打印一次性 stderr 警告。Claude 和 Codex 路径不变。完整 OpenCode reader 重做延后到 v0.6.0 之后。

### Core mem API 入 SDK

`@mindfoldhq/trellis-core/mem` 导出 `listMemSessions`、`searchMemSessions`、`readMemContext`、`extractMemDialogue`、`listMemProjects`，各平台 adapter 在 `packages/core/src/mem/adapters/` 下。CLI 退化为薄壳。

### 内置 `trellis-session-insight` skill

AI 即使在用户清晰表达 "我们之前讨论过" 时也不一定会主动调 `trellis mem`。新增内置 skill 教 AI 何时调用 `trellis mem`（过往方案回忆、决策检索、跨会话延续、熟悉 bug 调试、自我模式识别、finish-work 复盘），中英文触发短语逐字保留。**故意不规定固定回写文件** —— AI 当下判断是直接引用 / 更新 `prd.md` / `design.md` / 交给 `trellis-update-spec` 等。自动下发到所有支持平台。

## SDK 提取 (`@mindfoldhq/trellis-core`)

### Core SDK 包

Channel 与 task 原语之前锁在 CLI 二进制里，Node 消费者和外部集成拿不到。新发布的 `@mindfoldhq/trellis-core` 包暴露 `/channel`、`/task`、`/testing` 子路径导出。CLI 依赖它；两个包共享一个 git tag、一个 npm dist-tag、一个 release 版本号。

### 双包发版流水线

| 环节                         | 实现                                                                                     |
| -------------------------- | -------------------------------------------------------------------------------------- |
| 发版顺序                       | `.github/workflows/publish.yml` 先发 `@mindfoldhq/trellis-core` 再发 `@mindfoldhq/trellis` |
| Preflight / bump / publish | `release-preflight.js`、`bump-versions.js`、`release.js` 适配双包                            |
| 发版后校验                      | `verify-npm --package all` 校验两个包都已在公共 npm 注册表                                          |

### 可复用 channel + mem API

`@mindfoldhq/trellis-core/channel` 与 `/mem` 暴露上面 1d 与 2e 提到的生命周期 / 订阅 / inbox / 检索原语。

## 平台覆盖

* 总计 15 个平台。新增：**Reasonix**（DeepSeek-Reasonix），通过 `trellis init --reasonix` 启用。Sub-agent 形态 skill 带 `runAs: subagent` frontmatter，Reasonix 把它们当隔离 subagent 循环 spawn。`/skill trellis-` `cmdRefPrefix` 把 `{{CMD_REF:start}}` 解析为 `/skill trellis-start`（关闭 #301）。
* Pi Agent 扩展成熟：新增 `trellis_subagent` 工具（避开 `subagent` 命名空间冲突），支持 `single` / `parallel` / `chain` dispatch 模式，原生进度卡片（`renderResult`，按 `THROTTLE_MS` 节流），`Alt+O` 详情视图，`isTrellisAgent()` 校验，有界 stdout/stderr 缓冲。`<workflow-state>` 与 `<session-overview>` 每次 `input` 与 `before_agent_start` 自动注入。项目级 `.pi/settings.json` 覆盖防止全局 `npm:pi-subagents` 干扰当前 Trellis 项目（关闭 #246、#249）。
* Codex dispatch 默认改为 `inline`（原 `sub-agent`）。`codex-inline` / `codex-sub-agent` 虚拟平台驱动正确的 `workflow.md` 分支；`UserPromptSubmit` 里的 `<codex-mode>` banner 标明当前模式。`.codex/config.toml` 不再写 `[features.multi_agent_v2]` 块 —— 使用 Codex 自己的默认值（修复 Codex CLI ≤ 0.130 config 加载中断）。
* OpenCode `TRELLIS_CONTEXT_ID` 按 shell dialect 选前缀：PowerShell `$env:TRELLIS_CONTEXT_ID = …`、Git Bash / MSYS / Cygwin `export TRELLIS_CONTEXT_ID=…`、其余 `env TRELLIS_CONTEXT_ID=…`。Sub-agent 上下文隔离；active task 通过 session context / `Active task:` 提示 / 单会话回退解析。
* Cursor `sessionStart` 顶层发 `additional_context`（Cursor 期待的 schema）；移除不支持的 `beforeSubmitPrompt` hook 与拷过来的 `inject-workflow-state.py`。
* GitHub Copilot SessionStart 不再携带过时的 `systemMessage`；走支持的 `hookSpecificOutput.additionalContext`。

## 工作流 + 规划

### Task triage consent gate

之前 Trellis 每轮都会静默创建 task，连闲聊都不放过，把任务列表污染严重。现在无 task 状态下的轮次会先做请求分类：

* **简单 / 小**：只问要不要建 Trellis task；不建就跳过 Trellis
* **复杂**：请求许可建 task 并进入规划；拒绝则澄清范围或建议拆得更小

### 规划工件 (`prd.md` / `design.md` / `implement.md`)

复杂 task 不再把所有内容塞进单一 PRD。`task.py create` 默认建 `prd.md`。复杂规划走：

* `prd.md` —— 需求、约束、验收标准、不在范围内
* `design.md` —— 边界、数据流、契约、tradeoff
* `implement.md` —— checklist、验证命令、review gate

`task.py start` 之前完成。implement / check 的上下文加载顺序在 hook-push、pull-prelude、Pi 扩展、OpenCode plugin、inline 五种模式下保持一致：`jsonl entries → prd.md → design.md → implement.md`。

### 父子 task 树

`.trellis/workflow.md` 和 `get_context.py --mode phase --step 1.1` 文档化了带独立可验证子任务的父任务树用法。`[workflow-state:planning]` 与 `[workflow-state:planning-inline]` breadcrumb 同步更新。`trellis-brainstorm` 与 `trellis-meta` skill 涵盖该模式。

### 工作流模板（可选 + 可切换）

之前只有一个内建 `workflow.md`，没法切口味。新增 `trellis init --workflow / --workflow-source` 与 `trellis workflow` 切换命令。内置模板：`native`、`tdd`、`channel-driven-subagent-dispatch`。也可通过 `workflow-resolver.ts` 走 marketplace。当前激活的工作流仍然是 `.trellis/workflow.md`。

### Check agent 先读规划工件

Check agent 之前可能没看 PRD / design / implement 就照 spec 盖章。现在 check agent 必须读 `prd.md`，可选读 `design.md` / `implement.md`。覆盖：Claude Code、Cursor、OpenCode、Gemini、Kiro、Qoder、CodeBuddy、Droid、Pi（`trellis-implement.md` + `trellis-check.md`）。

### Workflow-state 工具路由 —— agent vs skill

`[workflow-state:in_progress]` 之前模糊了 sub-agent 类型与 skill，导致 agent 尝试调用不存在的 `trellis-implement` / `trellis-research` skill。现在 `trellis-implement` 和 `trellis-research` 只声明为 sub-agent 类型；`trellis-update-spec` 声明为 skill；`trellis-check` 两种都有（代码改动后做验证应优先用 Agent 形态）。

## Updater (`trellis upgrade` + spec 刷新 + 可配置 hook)

### `trellis upgrade` 命令

升级提示之前直接抛出原始 `npm install -g @mindfoldhq/trellis@…`，用户得自己猜 channel。新增 `trellis upgrade` 按当前 CLI 版本匹配 npm channel（`latest` / `beta` / `rc`）。flag：`--tag <tag>` 指定 dist-tag/version；`--dry-run` 预览。校验输入，POSIX 路径避免 shell 插值，Windows 走 `cmd.exe /d /s /c`，失败时打印 npm/PATH 排障信息。Session-start hint 现在指向 `trellis upgrade`。

### Registry-backed `.trellis/spec` 刷新

`trellis init --template <id>` 从 registry 拉的 spec 模板之前在 `trellis update` 上拿不到 registry 更新（关闭 #315）。现在 `trellis init --template <id>` 把 spec source + template id 持久化到 `.trellis/config.yaml` 的新 `registry.spec` 块。`trellis update` 读这个块，把配置的 spec registry 下到临时目录，再走现有的 hash / 冲突 / "你改过" 流程。支持直连 spec registry 与 marketplace 风格 registry，含 SSH 和自托管 Git。新工具：`utils/registry-config.ts`。

### `.trellis/config.yaml` 可配置 hook

之前 hook 与 channel runtime 的项目级配置散落或缺失。`.trellis/config.yaml` 现在驱动：

* `session_commit_message` / `max_journal_lines` / `session_auto_commit`（journal 自动 commit 形态）
* `hooks.after_create` / `after_start` / `after_finish` / `after_archive`（task 生命周期上的用户 shell 命令）
* `channel.worker_guard.idle_timeout` / `max_live_workers`（channel OOM 防护）
* `codex.dispatch_mode: inline | sub-agent`

已存在项目在 `trellis update` 时会通过 `configSectionsAdded` 收到注释掉的模板块。

### Updater 加固（模板归属、hash 跟踪、`workflow.md` 整文件刷新）

`initializeHashes()` 现在从 `startRecordingWrites()` 输出里取平台 / 根文件，不再扫 `.codex/` / `.claude/` 等目录。`pruneOrphanManifestKeys()` 在 `update` 与 `uninstall` 之前清理过期 orphan。`trellis init` / `uninstall` 在 `$HOME` 下默认拒绝运行（覆盖：`TRELLIS_ALLOW_HOMEDIR=1`）。`trellis update` 把 hash 跟踪的 `.trellis/workflow.md` 当整模板刷新（修复升级版 Codex 装机带过期 `[Codex]` 块的问题）。Hook 模板在 Windows 强制 UTF-8（`python -X utf8` + stdio reconfigure 用替换错误模式）。

## 内置 skills

### `trellis-channel`

新增内置 capability skill，教 AI 何时调用 `trellis channel` —— 多 agent 协作、live worker dispatch、跨 agent review、进度巡检、forum / thread 板、channel 日志排障。SKILL.md 加 5 个 reference 文件（workflows、forum、workers、progress-debugging、command-reference）。通过 `getBundledSkillTemplates()` 目录扫描自动下发到所有支持平台。

### `trellis-meta`

按 v0.6 架构重写。SKILL.md 前言新增 channel runtime、`trellis mem`、双包 SDK 三块；description 触发短语覆盖 bundled-skill 自动下发流程。新增 `references/local-architecture/multi-agent-channel.md` 与 `references/local-architecture/bundled-skills.md`，说明 channel 与其他原语的取舍、状态去向、`.trellis/config.yaml channel.*` 旋钮、bundled vs project-local 归属与覆盖约定。`platform-files/platform-map.md` 新增 Reasonix 行（第 15 个平台）与 Pi 原生 `trellis_subagent` 标注；`customize-local/change-skills-or-commands.md` 把平台路径表从 6 平台扩到 13 平台，列出四个内置 skill 的反碰撞规则。

### `trellis-spec-bootstrap`

`trellis init` 之后默认 spec 模板需要项目特定内容；之前用户得自己找并装 marketplace skill 来从真实代码库 bootstrap `.trellis/spec/`（关闭 #296）。新增平台无关内置 skill 在 `templates/common/bundled-skills/trellis-spec-bootstrap/`，提供仓库分析、spec 任务规划、spec 撰写、MCP 设置的源代码索引。`trellis init` / `trellis update` 在所有平台自动安装，替代旧的 `cc-codex-spec-bootstrap` marketplace 入口。beta.23 的 `rename-dir` migration 把已装的拼错目录（`trellis-spec-bootstarp`）跨 13 个平台 skill 根（`.claude/skills/`、`.cursor/skills/`、`.opencode/skills/`、`.agents/skills/`、`.kiro/skills/`、`.qoder/skills/`、`.codebuddy/skills/`、`.github/skills/`、`.factory/skills/`、`.pi/skills/`、`.agent/skills/`、`.windsurf/skills/`、`.kilocode/skills/`）改名到位。

### `trellis-session-insight`

详见 [Memory § `trellis-session-insight` 内置 skill](#内置-trellis-session-insight-skill)。

## Bug 修复

### `trellis-implement` / `trellis-check` 在缺失 Exa MCP 时不再静默跳过注册

内置的 `trellis-implement` 与 `trellis-check` agent 定义之前显式声明了 `mcp__exa__web_search_exa` 与 `mcp__exa__get_code_context_exa`。Claude Code 的 `tools:` 解析器在显式 MCP 工具名解析失败时静默跳过 agent 注册 —— 任何没装 Exa MCP 的用户会丢掉所有 Trellis sub-agent，主 agent 自己干活而不 dispatch。

修复：

* `trellis-implement` 与 `trellis-check` 去掉两个 `mcp__exa__*` 条目。这两个 agent 不需要外部 web search；工具列表收缩到 `Read, Write, Edit, Bash, Glob, Grep`。
* `trellis-research` 把原先的 `mcp__exa__*` + `mcp__chrome-devtools__*` 折成单一 `mcp__*` 通配。Claude Code 懒解析通配（无匹配时不静默跳过），所以 research 自动适配用户配置的任意 MCP，源模板不再锁死某个 provider。
* Copilot transformer（`mapLegacyToolToCopilot`，在 `packages/cli/src/configurators/shared.ts`）补上对应 `mcp__*` 分支，下发完整 Copilot MCP 等价工具集。

OpenCode agent 文件用不同的权限映射语法（`mcp__exa__*: allow`），不存在静默跳过问题，故意保留不变。关闭 `#302`。

## 破坏性变更与升级

breaking gate 在 `0.6.0-beta.0` 触发——那一份 manifest 携带 rename + delete migration chain。`0.6.0` manifest 本身 `breaking: false` 且 `migrations: []`（rc.0 → GA 源码零改动），但从任意 `0.5.x` 升上来的用户在 manifest 链走查时会穿过 `0.6.0-beta.0.json`，那一站是 breaking。必须带 `--migrate` 才能正确穿过链。

## RC 稳定化

v0.6.0 GA = `0.6.0-rc.0`，src/ 零改动；不再切 rc.1。breaking 工作在 `0.6.0-beta.0` 已完成，rc.0 到 GA 之间没有新的源代码变更。

## 升级

从 0.5.x：

```bash theme={null}
trellis update --migrate
```

`--migrate` 必加 —— `0.6.0-beta.0` 的 breaking-change gate 在遍历 migration 链时触发。rename / delete migration 经 hash 校验，本地改过的文件保留并警告，只清理原版 Trellis 写入的文件。每条 confirm prompt 的 `reason` 字段会内联说明版本特定的判定原因。

从任意 0.6.0 预发布版本（`beta.X` / `rc.X`）：

```bash theme={null}
trellis update
```

普通 `trellis update`，clean version bump，不需要 flag。

安装：

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