EcoPaste 仓库中的 Trellis 平台文件架构：共享运行时与 AI 工具适配层解析

本篇技术指南围绕 Trellis 项目的平台文件（Platform Files）架构展开，讲解 EcoPaste 仓库中 .trellis/ 共享运行时与 .claude/、.codex/、.cursor/、.kiro/、.opencode/、.github/ 等平台适配目录的分工协作模型。读完本文，你将掌握如何区分共享文件与平台文件、理解平台文件的四大功能分类、识别三种平台集成模式（Hook 驱动、Agent 拉取、主会话工作流），并能够按照正确的检查顺序对任意 AI 工具平台进行本地行为定制。

背景：Trellis 如何用一套本地架构连接多个 AI 工具

Trellis 的核心设计理念是：同一份本地架构可以复用于不同的 AI 工具。它在用户项目内生成两个层面的内容：

• .trellis/ 目录承载共享运行时——包括工作流定义、任务、规格说明、脚本和运行时状态；
• 各平台目录（.claude/、.codex/、.cursor/、.opencode/、.kiro/、.gemini/、.qoder/、.codebuddy/、.github/、.factory/、.pi/、.trae/、.kilocode/、.agent/、.devin/、.reasonix/、.zcode/ 等）存放适配器文件，定义每个 AI 工具如何"进入" Trellis。

从 EcoPaste 仓库根目录的实际结构看，这两层确实并存：根目录下有 .trellis/（包含 workflow.md、config.yaml、scripts/、spec/、tasks/、workspace/ 等），同时存在 .claude/、.codex/、.cursor/、.gemini/、.kiro/、.opencode/、.github/、.agents/ 等多个平台目录。

本地 AI 修改 Trellis 时，首先必须区分两类文件：

类别	包含路径	作用
共享文件（Shared files）	.trellis/workflow.md、.trellis/tasks/、.trellis/spec/、.trellis/scripts/	存储工作流、任务、规格、脚本等核心业务状态与运行逻辑
平台文件（Platform files）	.claude/、.codex/、.cursor/、.opencode/、.kiro/、.gemini/、.qoder/、.codebuddy/、.github/、.factory/、.pi/、.trae/、.kilocode/、.agent/、.devin/、.reasonix/、.zcode/ 等	让对应 AI 工具读取 Trellis 状态、调用 Trellis 脚本、加载 Trellis 的 skills / agents / hooks

关键原则：平台文件不存储业务状态。它们只是适配层，负责把不同 AI 工具桥接到同一套 .trellis/ 运行时上。

平台文件四大功能分类

不同平台目录的命名约定千差万别，但从功能上看，平台文件都可以归入以下四个类别（源自 overview.md，并与 platform-map.md 中各平台的实际目录矩阵一一对应）：

分类	常见路径示例	用途
settings / config	.claude/settings.json、.codex/hooks.json、.qoder/settings.json、.trae/hooks.json	注册 hooks、插件、扩展或平台行为
hooks / plugins / extensions	.claude/hooks/、.opencode/plugins/、.pi/extensions/	在会话启动、用户输入、Agent 启动、shell 执行等事件时注入上下文
agents	.claude/agents/、.codex/agents/、.kiro/agents/	定义 trellis-research、trellis-implement、trellis-check 三个专职 Agent
skills / commands / prompts / workflows	.cursor/commands/、.github/prompts/、.devin/workflows/	由用户显式调用的入口点（命令、提示词、工作流）

EcoPaste 仓库是这一分类的典型实例。例如：

• settings/config 层：.claude/settings.json、.codex/hooks.json、.codex/config.toml、.gemini/settings.json、.opencode/package.json；
• hooks 层：.claude/hooks/ 下的 session-start.py、inject-workflow-state.py、inject-subagent-context.py，.codex/hooks/、.gemini/hooks/、.kiro/hooks/ 中的同名脚本，以及 .github/copilot/hooks/；
• agents 层：.claude/agents/、.codex/agents/、.cursor/agents/、.gemini/agents/、.kiro/agents/ 中均存在 trellis-research、trellis-implement、trellis-check 三个文件（格式各不相同，详见下文）；
• skills/commands 层：.claude/skills/、.cursor/skills/、.opencode/skills/、.github/skills/、.kiro/skills/、.agents/skills/ 中都有 trellis-meta、trellis-channel、trellis-spec-bootstrap 等技能目录；.cursor/commands/、.gemini/commands/、.opencode/commands/、.github/prompts/ 存放命令与提示词入口。

各平台目录映射矩阵

详细映射可参考 platform-map.md。它按 trellis init --<platform> 的 CLI flag 列出主目录、技能目录、Agent 目录与 hooks/扩展位置，摘录部分关键平台如下：

平台	CLI flag	主目录	技能目录	Agent 目录	Hooks/扩展
Claude Code	--claude	.claude/	.claude/skills/	.claude/agents/	.claude/hooks/ + .claude/settings.json
Cursor	--cursor	.cursor/	.cursor/skills/	.cursor/agents/	.cursor/hooks.json + .cursor/hooks/
OpenCode	--opencode	.opencode/	.opencode/skills/	.opencode/agents/	.opencode/plugins/
Codex	--codex	.codex/	.agents/skills/	.codex/agents/	.codex/hooks/ + .codex/hooks.json
Kiro	--kiro	.kiro/	.kiro/skills/	.kiro/agents/	.kiro/hooks/
Gemini CLI	--gemini	.gemini/	.agents/skills/	.gemini/agents/	.gemini/settings.json + .gemini/hooks/
GitHub Copilot	--copilot	.github/	.github/skills/	.github/agents/	.github/copilot/hooks/ + prompts
Devin	--devin	.devin/	.devin/skills/	通常没有	.devin/workflows/

注意：某个平台目录是否真的存在于项目中，取决于用户实际运行过哪些 trellis init --<platform> 命令。EcoPaste 仓库实际存在的平台目录即为该仓库 init 时选择的集合。

三种平台集成模式

平台文件的存在形式由平台能力决定，Trellis 据此划分出三种集成模式（overview.md）：

1. Hook / Extension 驱动（推模式）

这类平台能够在特定事件上触发脚本或插件，主动把 Trellis 上下文"推"给 AI。常见能力包括：

• 会话启动（session-start）时注入 .trellis/ 概览；
• 每轮用户输入时给出工作流状态提示；
• 子 Agent 启动时注入 PRD / 规格 / 研究上下文；
• shell 命令继承会话身份。

在 EcoPaste 仓库的 .claude/settings.json 中可以直观看到这种"推"模式：它在 SessionStart 事件（matcher 覆盖 startup、clear、compact）注册 python3 .claude/hooks/session-start.py，在 UserPromptSubmit 事件注册 python3 .claude/hooks/inject-workflow-state.py，在 PreToolUse（matcher 为 Task 与 Agent）注册 python3 .claude/hooks/inject-subagent-context.py，每个 hook 都设置了 timeout 与 type: command。

修改提示：想改变"AI 在何时知道什么"，应当首先检查 hooks / plugins / extensions 以及 settings 文件。

2. Agent Prelude / 拉取模式（pull 模式）

部分平台无法可靠地让 hook 改写子 Agent 的提示词，因此改为在 Agent 文件本身中指示 Agent 启动后主动读取活动任务、PRD 与 JSONL 上下文。这类平台一般没有 hooks 或 settings 文件，Agent 文件自带"prelude"读取指令。

修改提示：想改变子 Agent 如何加载上下文，应检查 Agent 文件本身。

拉取模式在 Agent 文件中的典型指令序列是（详见 agents.md）：

python3 ./.trellis/scripts/task.py current --source

随后按顺序读取 implement.jsonl 或 check.jsonl、JSONL 引用的 spec/research 文件、当前任务的 prd.md，以及存在时的 design.md、implement.md。

EcoPaste 仓库的 .kiro/agents/trellis-research.json 是 pull 模式与 hook 结合的真实样本：它在 agentSpawn 时运行 python3 .kiro/hooks/inject-subagent-context.py（推），同时在 prompt 中要求"Run python3 ./.trellis/scripts/task.py current --source → active task path"（拉）。而 Reasonix、ZCode 则是纯 pull 平台——不使用 hooks 或 settings 文件，靠 Agent 文件中的 prelude 指令在启动后读取上下文。

3. 主会话工作流（Main-Session Workflow）

有些平台既没有 Trellis 子 Agent，也没有 hook 能力。它们依赖 workflows / skills / commands 引导主会话 AI 去读文件、跑脚本、推进任务。

修改提示：这类平台的行为调整点主要在平台侧的 workflows/skills/commands，以及 .trellis/workflow.md。

Kilo、Antigravity、Devin 属于此类主会话工作流平台（见 platform-map.md 的"Main-Session Workflow Platforms"一节），修改行为时应先检查 workflows 和 skills，不要假设它们存在 Trellis 子 Agent。

本地修改的标准检查顺序

当用户要求为某个平台定制行为时，AI 应严格按以下顺序检查（overview.md）：

1. 读取 .trellis/workflow.md，确认共享流程；
2. 读取目标平台的 settings/config，查看注册了哪些 hooks / agents / skills / commands；
3. 读取目标平台的 agents / skills / commands / hooks；
4. 修改最贴近用户需求的本地文件；
5. 若改动影响共享流程，同步更新 .trellis/workflow.md 或 .trellis/spec/。

同时有两条反向警告必须遵守：

• 不要只改平台文件而忘记共享工作流——否则共享流程与平台入口会脱节；
• 不要只改 .trellis/workflow.md 而忘记平台入口点可能仍含旧描述——否则平台侧的旧技能/命令描述会让 AI 按过时流程行事。

platform-map.md 还给出了更具体的决策规则：

1. 用户指定了平台：只改该平台目录（除非共享 workflow/spec 也必须变）；
2. 用户说"所有平台都应如此"：逐平台同步等价入口，不能只改一个目录；
3. 用户只说"我的 AI"：检查项目中实际存在的配置目录，推断当前 AI 平台；
4. 用户要项目级规则：优先用 .trellis/spec/ 或项目本地 skill；
5. 用户要 Trellis 行为：编辑 .trellis/workflow.md 加上平台 hooks/agents/skills/commands。

源码级实现证据：从仓库看平台文件如何运作

EcoPaste 仓库提供了大量可直接对照的实现样本，帮助你理解这套架构的落地形态。

hooks / settings 层：事件与脚本的绑定关系

hooks-and-settings.md 归纳了四类核心 hook 脚本的职责：

脚本	用途
session-start.py	生成会话启动上下文
inject-workflow-state.py	解析 .trellis/workflow.md 中的 [workflow-state:STATUS] 块，输出与当前任务状态匹配的内容；无匹配块时回退为 "Refer to workflow.md for current step."
inject-subagent-context.py	向子 Agent 注入 PRD、JSONL 上下文及相关 spec/research
inject-shell-session-context.py	让 shell 命令继承 Trellis 会话身份

仓库中的对应文件分布于各平台目录：.claude/hooks/、.codex/hooks/、.gemini/hooks/、.kiro/hooks/、.github/copilot/hooks/ 均包含同名 Python 脚本；.cursor/hooks/ 额外包含 inject-shell-session-context.py 与 inject-subagent-context.py。

不同平台注册 hook 的方式不同。对比可见：.codex/hooks.json 只注册了 UserPromptSubmit → python3 -X utf8 .codex/hooks/inject-workflow-state.py（timeout 15）；而 .claude/settings.json 则把 SessionStart（startup/clear/compact）、UserPromptSubmit、PreToolUse（Task/Agent）三个事件全部接线。Kiro 更特殊——它除了在 .kiro/agents/trellis.json 的 agentSpawn/userPromptSubmit 中注册脚本，还在 .kiro/hooks/trellis-workflow-state.kiro.hook 中以独立 hook 清单（version: 1.0.0、when.type: promptSubmit、then.type: runCommand）注册注入逻辑。

修改原则：

1. settings 负责接线，hooks 定义行为——只改 hook 文件但没在 settings 注册，平台永远不会调用它；只改 settings 而不改脚本，行为也不会变化；
2. 先确认平台事件名——不同平台对 SessionStart、UserPromptSubmit、AgentSpawn、shell 执行等事件叫法不同；
3. hooks 读取本地 .trellis/，而非上游源码；
4. 错误必须可见——hook 失败应明确告诉用户"什么没有被注入"，而不是让 AI 静默地缺少上下文。

排障路径：如果用户反馈"AI 没有读取 Trellis 状态"，按此顺序排查——① 检查平台 settings 是否注册了 hook；② 检查 hook 文件是否存在；③ 手动运行 hook 依赖的 .trellis/scripts/get_context.py 或 task.py current --source；④ 检查 .trellis/.runtime/sessions/ 中是否有活动任务状态；⑤ 检查平台 shell 是否传递了会话身份。

agents 层：三个专职角色与两种上下文加载模式

Trellis Agent 文件定义专职角色，三个核心 Agent 的职责边界保持一致（agents.md）：

Agent	职责
trellis-research	调查问题，把发现写入当前任务的 research/ 目录
trellis-implement	依据 prd.md、可选的 design.md/implement.md、implement.jsonl 及相关 spec/research 实现
trellis-check	审查变更、修复发现的问题并运行必要检查

Agent 文件不应变成泛泛的聊天提示词，而应明确输入来源、写入边界、是否允许改代码、如何汇报结果。

不同平台的 Agent 文件格式差异明显：Claude/Cursor/OpenCode/Gemini/Qoder/CodeBuddy 用 trellis-*.md，Codex 用 trellis-*.toml，Kiro 用 trellis-*.json（如 .kiro/agents/trellis-research.json），ZCode 放在 .zcode/cli/agents/，Reasonix 则把子 Agent 实现为带 runAs: subagent frontmatter 的 skills。

以 .kiro/agents/trellis-research.json 为实例，可以观察到成熟的职责边界设计：

• 输入来源：allowedTools 与 tools 均限定为 read/write/glob/grep/bash/web_search/web_fetch；
• 写入边界：allowedTools 中的 write 与 prompt 中的 Scope Limits 严格约束"只允许写 {TASK_DIR}/research/*.md，禁止写代码、spec、.trellis/scripts/、.trellis/workflow.md、平台配置，禁止任何 git 操作"；
• 汇报方式："返回文件路径 + 一行摘要给主 Agent，而不是贴出完整内容——文件才是交付物（Files are the contract）"。

修改 Agent 的原则：保持单一职责（不要把一个 Agent 混入 research/implement/check 三种职责）、规定读取顺序、规定写入边界、多平台项目需保持语义同步（例如同时配置了 Claude、Codex、Cursor 时，改动一个平台的 Agent 需评估是否也要应用到其他平台）。

skills / commands 层：概念差异与结构规范

skills、commands、prompts、workflows 是用户与 Trellis 交互的文本入口（skills-and-commands.md）：

类型	触发方式	最佳用途
skill	AI 自动匹配或用户显式提及	长期能力、工作流规则、修改指南
command	用户显式调用	明确的操作入口，如 continue、finish-work
prompt	用户显式调用或平台选择	类似 command，但采用平台 prompt 格式
workflow	用户显式选择或平台自动匹配	在没有子 Agent/hook 时引导主会话

技能的标准结构是一个目录：trellis-meta/ 下包含 SKILL.md 与 references/。SKILL.md 告诉 AI：何时使用该技能、当前任务先读哪个 reference、不该做什么；references 承载长文解释。EcoPaste 仓库中 trellis-meta 技能即严格遵循此结构，references 下细分为 local-architecture/、platform-files/、customize-local/ 三个子目录。

修改原则：入口文件保持精简、触发描述要具体（太宽泛会误触发，太窄则不触发）、跨平台保持语义一致、项目私有能力放进本地 skill（而不是公开的 trellis-meta）。若用户只是想"让本地 AI 多知道一条项目规则"，通常创建项目本地 skill 或更新 .trellis/spec/ 即可，而不是改动 Trellis 内置工作流技能。

共享运行时：.trellis/ 内部结构与三层模型

平台文件存在的意义是连接 .trellis/ 共享运行时。EcoPaste 仓库的 .trellis/ 目录包含：workflow.md（37 KB，定义阶段、路由、下一步动作与提示块）、config.yaml（项目配置）、spec/（项目专属编码约定与思考指南）、tasks/（每个任务的 PRD、技术笔记、研究文件与 JSONL 上下文）、workspace/（按开发者划分的日志与跨会话记忆）、scripts/（本地 Python 运行时，供 commands/hooks/上下文注入调用）、.runtime/（会话级运行时状态）以及 .template-hashes.json（用于 update 判断本地文件是否被用户改动过）。

对应的三层本地系统模型是（local-architecture/overview.md）：

1. 工作流层：.trellis/workflow.md 定义阶段、路由、下一步动作与提示块；
2. 持久化层：.trellis/tasks/、.trellis/spec/、.trellis/workspace/ 存储任务、规格与会话记忆；
3. 平台集成层：各平台目录中的 hooks、settings、agents、skills、commands、prompts、workflows 把 Trellis 工作流连接到不同 AI 工具。

三层全部位于用户项目内部，因此 AI 可以直接读取与修改。

值得一提的是 .trellis/config.yaml 中包含一个平台相关开关：codex.dispatch_mode（默认 inline）让 Codex 主 Agent 直接编辑代码，因为 Codex 子 Agent 运行在 fork_turns="none" 隔离下、无法继承父会话的任务上下文；设置为 sub-agent 才切换回传统派发模型。这印证了"平台差异必须在平台适配层处理，而不是污染共享运行时"的设计思想。

结论与实战要点

Trellis 平台文件架构的核心结论可以浓缩为五条：

1. 平台文件是适配层，不是业务层——所有业务状态都放在 .trellis/ 共享运行时中；
2. 先分类再动手——settings/config 负责注册、hooks/plugins/extensions 负责注入、agents 负责专职角色、skills/commands/prompts/workflows 负责用户入口；
3. 识别平台能力决定改哪里——支持 hook 的平台改 settings/hooks，无法改写子 Agent 提示词的平台改 Agent prelude，无子 Agent/hook 能力的平台改 workflows/skills/commands；
4. 严格遵循修改顺序——先 .trellis/workflow.md，再平台 settings，再平台入口文件，最后改动最小且贴合的本地文件，并反向检查两处脱节风险；
5. 以项目实际文件为准——路径表可能过时或与本地定制冲突，遇到分歧时以项目内实际 settings/config 与文件内容为权威，不要因为某个自定义文件不在路径表中就删除它。

在你自己的项目中使用这些原则时，先运行 ls -la 确认哪些平台目录真实存在，再进入对应目录核对 settings 与 hooks 的注册关系——这正是 EcoPaste 仓库中这套 Trellis 平台文件体系所展示的完整落地范式。