> ## 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.5.0-beta.19

> 2026-04-29

beta.19 紧急修复 beta.18 引入的回归：在没有 `<!-- TRELLIS:START -->` / `<!-- TRELLIS:END -->` 标记的 `AGENTS.md` 上跑 `trellis update` 时，用户原有内容会被 Trellis 模板整个覆盖。

## Bug Fixes

### 没有 TRELLIS 标记的 `AGENTS.md` 不再被覆盖

beta.18 给 `AGENTS.md` 引入了 `<!-- TRELLIS:START -->` / `<!-- TRELLIS:END -->` 受管块替换机制。当现有文件**没有这两个标记**时，fallback 路径返回的是裸模板，导致 `trellis update` 静默覆盖了用户内容。

| 现有 `AGENTS.md` 状态                 | beta.18（有回归） | beta.19           |
| --------------------------------- | ------------ | ----------------- |
| 有 `TRELLIS:START` / `TRELLIS:END` | 替换块内，外面保留    | 同上（不变）            |
| 无标记，beta.18 之前手写                  | **整个文件被覆盖**  | 用户内容保留，受管块追加到文件末尾 |
| 文件不存在                             | 写入完整模板       | 同上（不变）            |

修复在 `buildAgentsMdTemplate`（`packages/cli/src/commands/update.ts`）：fallback 现在通过 `getTrellisManagedBlock` 从规范模板里抽出受管块，用一个空行分隔追加到用户原内容后面。已经被 beta.18 覆盖过的项目可以 `git checkout <update 之前的 commit> -- AGENTS.md` 恢复，再在 beta.19 上重跑 `trellis update`。

### 测试覆盖

`packages/cli/test/commands/update.integration.test.ts` 新增 `#4d preserves user AGENTS.md without TRELLIS markers by appending the managed block`。之前的 `#4b`（legacy pristine）和 `#4c`（用户改过 managed block）覆盖了相邻 case，但漏了"完全没标记"这一个，回归就藏在这。

## Upgrade

存量项目：

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

本次 beta 不需要加 `--migrate` flag。