EcoPaste 项目内 Trellis 本地定制指南：基于 overview.md 的定制入口、操作顺序与文件优先级解析

• 桌面应用

Trellis 通过trellis init会在项目内生成.trellis/与各类平台目录（.claude/、.cursor/、.codex/等），本文基于仓库内.cursor/skills/trellis-meta/references/customize-local/overview.md展开，为在 EcoPaste 这类用户项目中工作的 AI（或开发者）提供一份"该改哪个文件、按什么顺序改、哪些绝对不要碰"的本地定制全景指南。读完本文，你将掌握按用户诉求快速定位定制入口的方法、一套安全的本地操作流程，以及判断何时需要回退到 Trellis 上游源码改动的边界。

先明确本地定制的适用范围

overview.md 的开篇就划定了本目录的适用前提：Trellis 已通过 npm 安装，且项目内已执行过trellis init。在这种场景下，本地 AI 应修改项目内生成的.trellis/与各平台目录，而不是去改 Trellis CLI 的上游源码。

从 SKILL.md 可以确认，默认操作范围是用户项目内的本地文件，具体包括：

• .trellis/：workflow、config、tasks、spec、workspace、scripts、bundled runtime agents 与运行时状态；
• 平台目录：.claude/、.codex/、.cursor/、.opencode/、.kiro/、.gemini/、.qoder/、.codebuddy/、.github/、.factory/、.pi/、.reasonix/、.kilocode/、.agent/、.devin/等；
• 共享技能层：.agents/skills/；
• 项目树之外的用户级 channel 存储：~/.trellis/channels/<project>/<channel>/events.jsonl；
• 可通过trellis mem查询的原始平台会话日志：~/.claude/projects/、~/.codex/sessions/、~/.pi/agent/sessions/。

一句话概括：凡是trellis init生成在项目里的文件，都是本地定制的合法目标；凡是node_modules或全局 npm 安装目录里的东西，都不应该作为本地定制的默认目标。

第一步：判断用户到底想改什么

overview.md 给出的核心方法论是：动手之前先根据用户的措辞，决定优先阅读哪一份定制文档。这张决策表是整个定制体系的入口：

这八份文档共同构成了 overview.md 所说的"定制主题库"。例如：

• 用户说"Trellis 的 flow / phases 不对"→ 入口是.trellis/workflow.md，具体改动点包括Phase Index、[workflow-state:STATUS]状态块和Skill Routing表（见 change-workflow.md）；
• 用户说"AI 没读 specs / 任务上下文丢了"→ 入口是.trellis/scripts/get_context.py、session_context.py、task_context.py与active_task.py（见 change-context-loading.md）；
• 用户说"某个平台钩子行为不对"→ 入口是平台 settings/config 与 hooks 目录（见 change-hooks.md）。

通用操作顺序：先确认、再读取、后窄改、最后同步

overview.md 规定了一套五步通用操作顺序，适用于所有本地定制请求：

1. 确认平台与目录：先检查项目里实际存在哪些平台目录（如.claude/、.codex/、.cursor/、.zcode/），只改真实存在的平台。
2. 确认当前激活任务：运行python3 ./.trellis/scripts/task.py current --source，确认当前任务是什么、从哪个来源激活的。
3. 读取本地事实源：优先读.trellis/workflow.md、.trellis/config.yaml以及相关平台文件，而不是凭记忆或旧会话规则行事。
4. 窄幅修改：只编辑与用户请求直接相关的文件，不顺手重构无关内容。
5. 同步语义：这是最容易被忽略的一步——如果共享流程（.trellis/workflow.md）变了，要检查平台入口文件是否需要同步修改；如果平台入口变了，要检查.trellis/workflow.md是否仍然与之保持一致。

以任务生命周期定制为例（change-task-lifecycle.md 明确要求的读取顺序）：先读.trellis/workflow.md、.trellis/config.yaml、.trellis/scripts/task.py、.trellis/scripts/common/task_store.py、.trellis/scripts/common/task_utils.py，再读当前任务的.trellis/tasks/<task>/task.json。配置类需求优先改.trellis/config.yaml，脚本行为需求再改.trellis/scripts/，AI 流程变了再同步.trellis/workflow.md。

本地文件优先级：从 workflow 到 platform 的分层视图

overview.md 给出了一张"本地文件优先级"表，这是定位改动点时最重要的分层视图：

各层职责在 SKILL.md 的 Current Rules 中有更细的落地说明：

• .trellis/workflow.md是本地工作流的事实源。它的初始内容在trellis init时从内置模板（native、tdd、channel-driven-subagent-dispatch）或 marketplace 模板中选取，之后可用trellis workflow --template <id>重新选择。若激活模板引用的.trellis/agents/<name>.md缺失，CLI 会输出指向trellis update的非阻塞 stderr 警告。
• .trellis/config.yaml是项目级配置入口，承载任务生命周期钩子（hooks.after_create/after_start/after_finish/after_archive）、日志形态（session_commit_message/max_journal_lines/session_auto_commit）、channel worker 守护（channel.worker_guard.idle_timeout/max_live_workers）、Codex 分发模式（codex.dispatch_mode: inline | sub-agent）以及 spec registry 块（registry.spec.source+registry.spec.template）。
• .trellis/spec/存项目专属编码约定与设计约束，可由trellis update按registry.spec刷新，本地修改会在.trellis/.template-hashes.json中标记为 "modified by user" 冲突。
• .trellis/tasks/存任务 PRD、设计笔记、实施计划、研究文件与 JSONL 上下文，任务形成父子树结构，可通过task.py create --parent <slug>、add-subtask、remove-subtask、list-context管理。
• .trellis/workspace/只存"刻意书写"的开发者日志，原始跨会话对话不在这里，而是通过trellis mem search|extract|context从磁盘上的原始日志恢复。
• .trellis/agents/{check,implement}.md是平台无关的 channel 运行时 Agent 定义，由trellis channel spawn --agent <name>加载，可编辑；注意修改各平台的trellis-implement.md/trellis-check.md并不会改变 channel 运行时 worker 的行为。
• ~/.trellis/channels/<project>/<channel>/events.jsonl是每项目每 channel 的运行时事件日志，文件锁分配序号、支持持久化idempotencyKey，永不落入.trellis/内。

默认不要做的事（Things Not To Do By Default）

overview.md 明确列出了本地定制的五条禁区，违规操作往往会导致更新被覆盖或改动不生效：

• 不编辑全局 npm 安装目录；
• 不编辑node_modules/@mindfoldhq/trellis（同样应避开@mindfoldhq/trellis-core，两个包同版本发布）；
• 不假设用户持有 Trellis 的 GitHub 仓库——本地定制不需要上游源码；
• 不用默认模板覆盖用户已修改的本地文件——先检查.trellis/.template-hashes.json，优先使用.newsidecar 文件而非破坏性覆盖；
• 不把团队项目规则放进公开的trellis-meta——项目规则应放在.trellis/spec/或本地技能中，因为trellis update会覆盖 bundled skill 目录里的任何内容。

这条规则在技能层面有直接对应：SKILL.md 的 Do Not 部分进一步补充——不要手工编辑~/.trellis/channels/<project>/<channel>/events.jsonl（序号在文件锁下分配，回放安全写入必须走trellis channelCLI 或@mindfoldhq/trellis-core/channelSDK）；当目标是改变 channel 运行时 worker 行为时，不要编辑.claude/agents/trellis-implement.md等各平台子 Agent 文件，而要改.trellis/agents/<name>.md。

何时才需要切换到上游源码视角

overview.md 指出：只有用户明确表达以下四种目标之一时，才切换到 Trellis 上游源码视角：

• "I want to open a PR to Trellis"（想向 Trellis 提交 PR）；
• "I want to change npm package publish contents"（想改变 npm 包发布内容）；
• "I want to fork Trellis"（想 fork Trellis）；
• "I want to modify the generation logic fortrellis init/update"（想修改trellis init/update的生成逻辑）。

除此之外，默认都在用户项目内的本地 Trellis 文件中修改。例如，想给 Trellis 上游贡献 bundled skill 改动，应编辑 CLI 仓库中的packages/cli/src/templates/common/bundled-skills/<name>/，而不是改部署副本（见 change-skills-or-commands.md 的 Which Entry Type To Choose 表）。

实战组合：一次完整定制请求的拆解示例

把上面的方法论串起来，可以模拟一个典型请求的处理路径（例如："AI 在实施阶段没有读安全 spec"）：

1. 措辞归类：属于 "AI did not read context" → 读 change-context-loading.md；
2. 确认任务：python3 ./.trellis/scripts/task.py current --source；
3. 确认 JSONL 正确：python3 ./.trellis/scripts/task.py list-context <task>与task.py validate <task>，确认任务与 JSONL 无误后再动 hooks/agents；
4. 判断平台模式：若平台是 hook push，则编辑inject-subagent-context钩子；若是 agent pull，则编辑trellis-implement/trellis-check的读取步骤；
5. 检查 JSONL 内容：implement.jsonl/check.jsonl中只应包含 spec/research 文件（如{"file": ".trellis/spec/backend/index.md", "reason": "Backend conventions"}），不应放入将被修改的代码文件；
6. 同步流程：若改动影响流程语义，回到.trellis/workflow.md检查一致性。

这条链路正是 overview.md 决策表 + 通用操作顺序 + 文件优先级三者的实际合体，也体现了"钩子负责注册、脚本负责行为，settings 与 hook 必须一起检查"的要点（change-hooks.md）。

结语：本地定制的三条底线

综合 overview.md 与其子文档，本地定制始终要守住三条底线：

1. 改动范围最小化：只动与请求相关的.trellis/或平台文件，流程语义变化务必同步到.trellis/workflow.md；
2. 上游/本地界限分明：node_modules与全局安装目录不是定制目标，只有明确的 PR / 发布 / fork / 生成逻辑诉求才切换到上游源码视角；
3. 冲突意识：改 bundled skill 或模板派生文件前先看.trellis/.template-hashes.json，项目私有约定一律落到.trellis/spec/或项目本地技能，否则下一次trellis update会把改动冲掉。

以此为纲，无论是改 workflow、任务生命周期、上下文注入、钩子、Agent，还是新增技能/命令/spec，都能在 overview.md 这张"定制地图"上快速找到正确的落笔位置。

• 桌面应用