EcoPaste 项目内 Trellis 本地架构解析：工作流、持久化与平台集成三层模型及定制指南

• 桌面应用

本篇技术指南以 EcoPaste 仓库中 Trellis 本地架构文档（overview.md）为核心，结合仓库内.trellis/目录的真实实现，讲解 Trellis 在用户项目内的三层系统模型、核心路径职责、AI 定制原则与各子系统的编辑入口。读完本文，你将能判断一个已执行过trellis init的项目里各文件由谁生成、由谁维护，并掌握在不触碰 Trellis 上游源码的前提下正确修改本地工作流、任务、Spec、记忆与上下文注入的方法。

前提：Local Trellis 的适用范围

trellis-meta技能面向已经在项目内执行过trellis init的用户项目。此时用户机器上通常只安装了 npm 发布的trellis命令，以及项目内生成的 Trellis 文件，可能并没有 Trellis CLI 的源码。

因此，当 AI 使用本技能时，默认的定制目标就是用户项目内的本地文件：

• .trellis/：工作流、任务、Spec、记忆、脚本与运行时状态。
• 平台目录：.claude/、.codex/、.cursor/、.opencode/、.kiro/、.gemini/、.qoder/、.codebuddy/、.github/、.factory/、.pi/、.kilocode/、.agent/、.devin/、.reasonix/、.zcode/等。
• 共享技能层：.agents/skills/。

在 EcoPaste 仓库中可以看到这些目录的真实形态：根目录同时存在.claude/（含agents/、commands/、hooks/、settings.json、skills/）、.codex/（含agents/、config.toml、hooks/、hooks.json）、.cursor/（含agents/、commands/、hooks/、hooks.json、skills/）、.github/（含agents/、copilot/、hooks/、prompts/、skills/、workflows/）以及共享技能层.agents/skills/。

除非用户明确表示要修改 Trellis 上游源码、发布 npm 包或贡献 PR，否则不要默认引导用户 fork Trellis CLI 仓库——上游源码仅在上述三种意图下才作为操作对象。

本地系统模型：三层架构

Trellis 在用户项目内提供三个层：

1. 工作流层（Workflow layer）：.trellis/workflow.md定义阶段（Phase）、路由（Routing）、下一步动作（Next Actions）与提示词块（Prompt Blocks）。
2. 持久化层（Persistence layer）：.trellis/tasks/、.trellis/spec/、.trellis/workspace/分别存放任务、Spec 与跨会话记忆。
3. 平台集成层（Platform integration layer）：平台目录中的 hooks、settings、agents、skills、commands、prompts、workflows 负责把 Trellis 工作流连接到不同 AI 工具。

三个层全部位于用户项目内，因此 AI 可以直接读取和修改它们。在 EcoPaste 仓库中，.trellis/下的真实目录结构与此完全对应：workflow.md、config.yaml、spec/、tasks/（含archive/2026-06、archive/2026-07）、workspace/、scripts/、agents/（含check.md、implement.md）、.runtime/约定的会话状态目录、.version与.template-hashes.json管理文件。

核心路径及其职责

trellis init生成的核心文件路径及用途如下表：

管理文件的实际形态

在 EcoPaste 仓库中可以看到这些管理文件的具体内容：

• .trellis/.version记录当前 Trellis 版本为0.6.5，供 update/migration 逻辑判断升级路径。
• .trellis/.template-hashes.json以__version: 2格式记录每个 Trellis 托管文件的 SHA-256 哈希，例如.agents/skills/trellis-before-dev/SKILL.md、.agents/skills/trellis-brainstorm/SKILL.md、.agents/skills/trellis-channel/references/command-reference.md等。trellis update通过比对哈希区分三种情况：文件未被用户修改（可自动更新）、文件已被用户修改（提示覆盖、保留或生成.new）、文件不再是当前模板（按迁移规则删除、重命名或保留）。

平台目录的类别

不同平台生成不同的目录，常见类别包括：

修改平台目录时，应同时确认.trellis/workflow.md是否仍然描述同一流程——语义需要保持同步。

AI 定制原则（五条）

1. 先找到本地的事实来源：不要凭记忆修改。先读.trellis/workflow.md、.trellis/config.yaml、相关平台目录与相关任务文件。
2. 改用户项目，不改 npm 包缓存：只修改项目内生成的文件，不要动node_modules或全局 npm 安装目录。
3. 保持平台文件与.trellis/对齐：若工作流路由发生变化，检查平台技能或命令是否仍描述同一流程。
4. 项目专属规则放入.trellis/spec/或本地技能：不要把团队约定写进trellis-meta。
5. 保留用户改动：若文件已被本地修改，应以当前内容为基准，而不是用默认模板覆盖。

工作流层：.trellis/workflow.md

.trellis/workflow.md是项目内工作流的"事实来源"（source of truth），AI 无需 Trellis 源码即可据此理解当前项目应如何推进任务。其职责有三：

1. 解释工作流阶段：Plan、Execute、Finish。
2. 定义技能路由：用户表达某种意图时，AI 应使用哪个技能或代理。
3. 提供工作流状态提示词块：hooks 可将当前状态对应的提示词块注入会话。

EcoPaste 仓库的 .trellis/workflow.md 中，阶段模型为：

Phase 1: Plan -> 澄清要构建什么，产出 prd.md 与必要研究 Phase 2: Execute -> 依据 PRD 与 Spec 实施，然后检查 Phase 3: Finish -> 最终验证、沉淀经验并收尾

每个阶段包含编号步骤（如1.3 Configure context），这些编号并非task.json的运行时字段，而是供 AI 与人阅读的工作流结构。技能路由按平台能力区分：支持子代理的平台默认派发trellis-implement实施、trellis-check检查；不支持子代理的平台由主会话读取技能后直接执行。工作流底部可包含如下状态块，hooks 依据当前任务状态选择对应块注入会话：

[workflow-state:no_task] ... [/workflow-state:no_task]

常见状态包括no_task（无活动任务）、planning（处于需求/研究/上下文配置阶段）、in_progress（进入实施与检查）、completed（完成待收尾或归档）。修改"无任务时是否创建任务""何时可跳过任务创建""是否必须使用子代理"等策略，应编辑这些状态块及其上的路由表，并让 AI 重新读取.trellis/workflow.md，不要沿用旧会话中的流程记忆。常用修改点如下表：

持久化层一：任务系统.trellis/tasks/

任务系统完全存放在.trellis/tasks/下，每个任务是一个目录，包含需求、上下文、研究、状态与关系信息。典型目录结构：

.trellis/tasks/ ├── 04-28-example-task/ │ ├── task.json │ ├── prd.md │ ├── design.md │ ├── implement.md │ ├── implement.jsonl │ ├── check.jsonl │ └── research/ └── archive/ └── 2026-04/

EcoPaste 仓库中.trellis/tasks/还包含archive/2026-06、archive/2026-07两个归档目录，印证了"归档后移入archive/{年-月}/"的约定。

task.json的常见字段包括：id/name/title（身份与标题）、status（如planning、in_progress、review、completed）、priority（P0~P3）、creator/assignee、package（monorepo 目标包，可空）、branch/base_branch、children/parent、commit/pr_url、meta（扩展字段）。

父子任务树

父子任务关系用于工作结构组织：父任务汇聚相关交付物为同一来源需求集，拥有源需求与用户可见范围、子任务映射及职责边界、跨子任务验收标准与最终集成评审；子任务用于可独立走完规划、实施、检查、归档流程的交付物。若子任务之间存在依赖，应写入子任务的prd.md/implement.md，不能依赖树位置暗示顺序。常用命令：

python3 ./.trellis/scripts/task.py create "<child title>" --slug <child-slug> --parent <parent-dir> python3 ./.trellis/scripts/task.py add-subtask <parent-dir> <child-dir> python3 ./.trellis/scripts/task.py remove-subtask <parent-dir> <child-dir>

父任务上的children是历史列表：子任务归档后 Trellis 仍保留其名称，使[2/3 done]这类进度在子任务移入archive/后依然有意义。注意：不要将阶段编号当作任务状态，任务进度主要由status、产物是否存在（prd.md，以及可选的design.md/implement.md）、是否配置了子代理模式的 JSONL 上下文，以及workflow.md中的阶段描述共同决定。

活动任务与 JSONL 上下文

用户看到的"当前任务"实际上是按会话存储的，路径为.trellis/.runtime/sessions/<context-key>.json。task.py start将任务路径写入当前会话的运行时文件；task.py current --source显示当前任务及其来源。不同 AI 窗口可指向不同任务互不覆盖。若平台或 shell 环境没有稳定的会话身份，task.py start可能无法设置活动任务——此时应读取报错、检查平台 hook/会话环境，而不是回退到共享的全局指针。

implement.jsonl与check.jsonl是子代理"先读什么"的上下文清单，不替代implement.md。格式为每行一个 JSON 对象：

{"file": ".trellis/spec/cli/backend/index.md", "reason": "Backend conventions"} {"file": ".trellis/tasks/04-28-example/research/api.md", "reason": "API research"}

规则：只包含 Spec 与研究文件；不要包含即将被修改的代码文件；不要把聊天中的临时结论当作唯一上下文；种子行（seed rows）没有file字段，仅提示 AI 填入真实条目。

常用任务命令

python3 ./.trellis/scripts/task.py create "<title>" --slug <slug> python3 ./.trellis/scripts/task.py start <task> python3 ./.trellis/scripts/task.py current --source python3 ./.trellis/scripts/task.py add-context <task> implement <file> <reason> python3 ./.trellis/scripts/task.py validate <task> python3 ./.trellis/scripts/task.py finish python3 ./.trellis/scripts/task.py archive <task>

修改任务系统时，AI 应优先使用脚本命令维护结构；仅当脚本无法覆盖需求时才直接编辑 JSON/Markdown。定制点对应关系：默认任务模板 →.trellis/scripts/common/task_store.py；状态语义 →.trellis/workflow.md与 workflow-state hook 逻辑；任务生命周期动作 →.trellis/config.yaml的hooks.after_*；上下文规则 →.trellis/workflow.md的规划产物指引；归档策略 →.trellis/scripts/common/task_store.py/task_utils.py。

持久化层二：Spec 系统.trellis/spec/

.trellis/spec/是用户项目的工程规范库。Trellis 的理念不是让 AI 死记规范，而是在正确时机注入相关 Spec 或要求 AI 阅读。单仓库常见结构：

.trellis/spec/ ├── backend/ │ ├── index.md │ └── ... ├── frontend/ │ ├── index.md │ └── ... └── guides/ ├── index.md └── ...

monorepo 常见结构则按包分层，如cli/backend/、cli/unit-test/、docs-site/docs/等。每个index.md是该层的入口，应列出 Pre-Development Checklist 与 Quality Check，具体规范放在同目录的其他 Markdown 文件中。

EcoPaste 仓库的 .trellis/spec/ 完全遵循该模型：backend/下有architecture.md、clipboard-pipeline.md、commands-and-events.md、database-and-storage.md、index.md、settings-window-platform.md；frontend/下有component-guidelines.md、directory-structure.md、hook-guidelines.md、index.md、quality-guidelines.md、state-management.md、type-safety.md；guides/下有code-reuse-thinking-guide.md、cross-layer-thinking-guide.md、index.md。

.trellis/config.yaml可声明包：

packages: cli: path: packages/cli docs-site: path: docs-site type: submodule default_package: cli

可运行python3 ./.trellis/scripts/get_context.py --mode packages列出当前项目的包与 Spec 层，以此作为配置上下文 JSONL 的参照。Spec 进入任务的方式：规划阶段将相关 Spec 写入implement.jsonl/check.jsonl，子代理或平台 prelude 读取这些 JSONL 加载对应 Spec；无子代理支持的平台上，AI 应按工作流直接阅读相关 Spec。

Spec 应包含的是可执行的工程约定而非通用最佳实践：文件应放哪里、错误处理如何表达、API/hooks/命令的输入输出契约、被禁止的模式、需要测试的情形、项目特定陷阱及规避方法。AI 在实施或调试中学到新规则时，应更新.trellis/spec/而不是只在聊天中总结。边界：.trellis/spec/是用户的项目规范，不是 Trellis 内置模板的永久副本，应鼓励用户按实际项目代码持续更新。

持久化层三：工作区记忆.trellis/workspace/

.trellis/workspace/存储跨会话记忆，让 AI 与人在不同窗口、不同天数之间理解此前发生的事情。目录结构：

.ttrellis/workspace/ ├── index.md └── <developer>/ ├── index.md ├── journal-1.md └── journal-2.md

EcoPaste 仓库中该结构已实际落地：.trellis/workspace/index.md与.trellis/workspace/ayangweb/（含index.md、journal-1.md）均存在。

首次使用需初始化身份：

python3 ./.trellis/scripts/init_developer.py <name>

这会创建.trellis/.developer与对应的 workspace 目录。AI 不应随意更换开发者身份；若身份不对，先确认当前项目的使用者。

journal-N.md记录每次会话已完成或部分完成的工作。默认每个 journal 约 2000 行，超限后滚动到下一个文件。记录会话的常用命令：

python3 ./.trellis/scripts/add_session.py \ --title "Session title" \ --summary "What changed" \ --commit "abc1234"

无提交的规划或评审工作可用--no-commit或空 commit 值记录。三个系统的分工：.trellis/tasks/存特定任务的需求、设计、研究与状态；.trellis/workspace/存跨任务、跨会话的工作记录；.trellis/spec/存应长期遵循的工程知识。判断规则——仅对当前任务有用的信息放任务目录；描述当前会话发生了什么放 workspace journal；未来每次写代码都应遵循的放 spec。

定制点：日志行数上限 →max_journal_lines；会话自动提交信息 →session_commit_message；会话内容格式 →.trellis/scripts/add_session.py；上下文中的工作区展示方式 →.trellis/scripts/common/session_context.py。AI 不应把 workspace 当作唯一事实来源：恢复任务时先读当前任务，再用 workspace 做背景；任务完成后在 workspace 记录重要过程，若涌现长期规则则更新 spec。

项目配置：.trellis/config.yaml

.trellis/config.yaml是项目级 Trellis 配置入口。EcoPaste 仓库的 .trellis/config.yaml 展示了全部可配置项的真实形态：

• 会话记录：session_commit_message: "chore: record journal"（add_session.py 后自动提交 journal/index 变更的提交信息）、max_journal_lines: 2000（每个 journal 文件轮转前的最大行数）。
• 会话自动提交：session_auto_commit接受true/false/yes/no/1/0/on/off（大小写不敏感）。默认true（脚本在 add_session.py / task.py archive 后自动暂存并提交）；设为false时脚本不触碰 git，适合.gitignore有意排除.trellis/、会话数据仅本地保留，或希望人工审查暂存变更的场景。
• 任务生命周期 hooks：hooks.after_create/after_start/after_finish/after_archive，每个 hook 接收TASK_JSON_PATH环境变量指向 task.json；hook 失败仅打印警告，不阻塞主操作。
• monorepo/packages：可声明包路径，trellis init会尝试自动检测 workspace；polyrepo/meta-repo 布局可在包上标记git: true；default_package指定未传--package时使用的默认包。
• Channel worker OOM guard：channel.worker_guard.idle_timeout: 5m与max_live_workers: 6。优先级为 CLI 标志 > 环境变量（TRELLIS_CHANNEL_WORKER_IDLE_TIMEOUT/TRELLIS_CHANNEL_MAX_LIVE_WORKERS）> 此配置 > 内置默认。idle_timeout: 0禁用空闲清理；max_live_workers: 0禁用 spawn 时的预算检查。
• Codex dispatch 行为：codex.dispatch_mode为 Codex 专属旋钮，默认inline（主 Codex 代理直接改代码，因为 Codex 子代理以fork_turns="none"隔离运行，无法继承父会话的任务上下文）；设为sub-agent可选用传统派发模型。

上下文注入系统

Trellis 上下文注入的目标是让 AI 在正确时机读正确文件，而非依赖模型记忆。注入类型包括：会话上下文（.trellis/scripts/get_context.py：当前开发者、git 状态、活动任务、journal、packages）、工作流上下文（.trellis/workflow.md）、Spec 上下文（.trellis/spec/+ 任务 JSONL）、任务上下文（.trellis/tasks/<task>/的prd.md、design.md、implement.md、research/）、平台上下文（平台 hooks/settings/agents）。

三种注入机制：

1. session-start：支持该事件（会话启动、清空、压缩等）的平台注入 Trellis 概览，通常包括工作流摘要、当前任务状态、活动任务、spec 索引路径、开发者身份与 git 状态。
2. workflow-state：每轮用户消息前注入轻量提示，依据当前任务状态从.trellis/workflow.md选择no_task、planning、in_progress、completed等块。
3. sub-agent context：实施与检查代理需要任务上下文，有 hook push 与 agent pull 两种加载模式；两种模式下，任务目录中的 JSONL 都是 Spec/研究上下文的清单，任务产物按prd.md→design.md（如存在）→implement.md（如存在）顺序读取。

JSONL 阅读规则：跳过无file字段的种子行；配置 JSONL 时只应包含 Spec/研究文件，不预注册将要修改的代码文件。活动任务状态存于.trellis/.runtime/sessions/，按会话隔离；hooks 尝试从平台事件、环境变量、transcript 路径或TRELLIS_CONTEXT_ID解析 context key。若 shell 命令看不到同一 context key，task.py current --source可能报告无活动任务——应检查平台是否向 shell 传递会话身份，而非手写全局 current-task 文件。

多代理 Channel 运行时与内置技能

Trellis v0.6 在基础三层模型之上新增三个架构面：

1. 多代理协作运行时trellis channel：通过~/.trellis/channels/<project>/<channel>/events.jsonl项目作用域事件日志协调多个 AI worker 进程，含 worker OOM guard、forum/thread 频道、持久化幂等键与内置.trellis/agents/{check,implement}.md运行时定义。项目桶名由项目绝对路径派生（斜杠展平、非字母数字替换为-），可用TRELLIS_CHANNEL_ROOT/TRELLIS_CHANNEL_PROJECT覆盖。EcoPaste 仓库中.trellis/agents/check.md与.trellis/agents/implement.md均已存在，可直接被trellis channel spawn --agent check|implement消费。
2. 跨会话记忆trellis mem：读取磁盘上已有的原始 Claude Code、Codex、Pi Agent JSONL 对话日志，按--phase brainstorm|implement|all切片，永不外传。
3. 双包 npm 发布：@mindfoldhq/trellis（CLI）与@mindfoldhq/trellis-core（SDK，含/channel、/task、/mem、/testing子路径）同版本同步发布。

内置技能（bundled skills）由trellis init自动写入每个受支持平台的技能根目录，并由trellis update保持同步。EcoPaste 的共享技能层 .agents/skills/ 即为真实产物，包含trellis-before-dev、trellis-brainstorm、trellis-channel、trellis-check、trellis-continue、trellis-finish-work、trellis-meta、trellis-session-insight、trellis-spec-bootstrap、trellis-start、trellis-update-spec等。本地覆盖内置技能的受支持方式是直接编辑平台技能根目录下的文件（哈希发散后trellis update不再自动覆盖，除非显式--force）；团队私有约定应放入.trellis/spec/或独立本地技能，而不是修改trellis-meta本身。

使用本目录的导航路径

原文档最后给出了按意图选择文档的导航：

• 了解 init 后存在哪些文件 → 读 generated-files.md（含每个.trellis/文件是否可编辑的边界与.template-hashes.json三种更新分支语义）。
• 修改阶段、路由或下一步动作 → 读 workflow.md。
• 修改任务模型、JSONL 上下文或活动任务行为 → 读 task-system.md。
• 修改编码规范注入 → 读 spec-system.md。
• 理解日志与跨会话记忆 → 读 workspace-memory.md。
• 修改 hooks 或子代理上下文加载 → 读 context-injection.md。

若要按具体诉求选择定制入口，可参照 customize-local/overview.md：改工作流流程/阶段/下一步提示词读change-workflow.md；改任务创建、状态、归档或 hooks 读change-task-lifecycle.md；改注入内容读change-context-loading.md；改平台 hook 读change-hooks.md；改实施/检查/研究代理行为读change-agents.md；新增技能/命令/工作流/提示词读change-skills-or-commands.md；调整 spec 结构读change-spec-structure.md；添加团队约定与本地笔记读add-project-local-conventions.md。

结语：定制边界总结

可默认编辑：.trellis/workflow.md、.trellis/config.yaml、.trellis/spec/**、.trellis/scripts/**、.trellis/agents/**，以及各平台的 hooks、settings、agents、skills、commands、prompts、workflows。默认不编辑：全局 npm 安装目录、node_modules/@mindfoldhq/trellis、Trellis 上游仓库源码、.trellis/.runtime/**下的具体状态文件、.trellis/.template-hashes.json内的哈希内容。只有当用户明确表示要向上游贡献时，才切换到 Trellis CLI 源码视角。在 EcoPaste 这类已完整执行trellis init的真实项目中，上述每一层的文件都能在仓库根目录下找到对应实体，本文所引用的路径均可直接打开核对。

• 桌面应用