> ## 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.4.0-beta.1

> 2026-03-12

Monorepo 支持、统一命令、Python 脚本重构。

<Warning>这是一个**破坏性更新**。请运行 `trellis update` 进行迁移。自定义过的命令文件会被保留——只有未修改的文件才会被自动删除。</Warning>

## 功能增强

* **Monorepo 自动检测** — `trellis init` 自动检测 pnpm/npm/Cargo/Go/uv workspaces 和 git submodules，生成按包划分的 spec 目录和含 packages 列表的 `config.yaml`
* **命令合并** — `before-backend-dev` + `before-frontend-dev` 合并为 `before-dev`；`check-backend` + `check-frontend` 合并为 `check`（全部 9 个平台）
* **安全文件删除** — 新增迁移类型 `safe-file-delete`，仅在文件内容 hash 匹配时删除过时文件（用户修改过的文件永远不会被删除）
* **受保护路径** — `PROTECTED_PATHS` 防止迁移操作触碰用户数据（`.trellis/workspace`、`spec`、`tasks`）
* **更新跳过路径** — `config.yaml` 新增 `update.skip`，排除指定路径不受 safe-file-delete 和模板更新影响
* **Worktree 子模块感知** — Worktree agent 自动为任务包初始化 git submodules
* **Monorepo 脚本支持** — session-start hook 支持 `spec_scope` 过滤；`task.py` 和 `add_session.py` 支持 `--package`
* **迁移任务自动创建** — 破坏性更新时自动在 `.trellis/tasks/` 创建迁移任务，包含迁移指南和 AI 协助说明

## Bug 修复

* **Update：受保护路径兼容** — 允许 rename/rename-dir 迁移目标为受保护路径（0.2.0 兼容）
* **Update：配置解析警告** — `config.yaml` 解析失败时发出警告，而非静默禁用 `update.skip`
* **Scripts：子模块状态** — 保留 git submodule 状态前缀字符（`.strip` → `.rstrip`）

## 内部改进

* **Python 脚本重构** — 提取共享 `io`/`log`/`git` 模块，引入 `TaskInfo` TypedDict 类型安全，拆分巨型模块（`task.py`、`git_context.py`、`status.py`）为聚焦模块。所有入口路径不变。

## 迁移指南

运行 `trellis update` 同步新的统一命令。旧的 `before-backend-dev`、`before-frontend-dev`、`check-backend`、`check-frontend` 文件会在未修改的情况下自动删除。如果你自定义了这些文件，请将改动合并到新的 `before-dev` / `check` 文件中，然后手动删除旧文件。