EcoPaste 仓库平台接入文件解析：Trellis 平台文件（Platform Files）架构全解

• 桌面应用

导读

本文聚焦 Trellis 将本地架构接入不同 AI 工具的核心机制——平台文件（Platform Files）。内容围绕.claude/、.codex/、.cursor/、.opencode/、.kiro/、.gemini/等平台目录的定位、分类与三种集成模式展开，并结合 EcoPaste 仓库中实际存在的适配文件进行佐证。读者读完可掌握：如何区分共享文件与平台文件、各类平台文件的职责边界、平台接入的三种工作模式，以及自定义行为时的本地修改顺序与排查路径。

平台文件的定位：连接本地架构与 AI 工具的适配层

Trellis 将同一套本地架构连接到不同的 AI 工具。.trellis/存放共享运行时，平台目录存放适配文件，定义每种 AI 工具如何进入 Trellis。平台文件不存储业务状态，只负责让对应的 AI 工具读取 Trellis 状态、调用 Trellis 脚本、加载 Trellis 的 skills/agents/hooks。

在 EcoPaste 仓库中，这一结构已经实际落地：

• 共享文件：.trellis/workflow.md、.trellis/tasks/、.trellis/spec/、.trellis/scripts/、.trellis/agents/、.trellis/config.yaml、.trellis/workspace/
• 平台文件：.claude/、.codex/、.cursor/、.opencode/、.kiro/、.gemini/、.agents/skills/（Codex 写入的共享 skills 层）、.github/等

平台文件分类：五大职责域

EcoPaste 仓库实际验证了这一分类。以.claude/为例：

• 设置文件.claude/settings.json注册了 SessionStart、UserPromptSubmit、PreToolUse（Task/Agent）三类 hooks
• hooks 目录.claude/hooks/存放session-start.py、inject-workflow-state.py、inject-subagent-context.py
• agents 目录.claude/agents/存放trellis-research.md、trellis-implement.md、trellis-check.md
• skills 目录.claude/skills/存放trellis-meta、trellis-brainstorm、trellis-before-dev等
• commands 目录.claude/commands/trellis/存放continue.md、finish-work.md

三种平台集成模式

1. Hook / Extension 驱动模式

这类平台能在特定事件触发脚本或插件，主动向 AI 注入 Trellis 上下文。常见能力：

• 会话开始注入.trellis/概览
• 每轮用户输入注入 workflow 状态提示
• 子 Agent 启动时注入 PRD/spec/research
• Shell 命令继承会话身份

要修改"AI 何时知道什么"，先检查 hooks/plugins/extensions 和 settings。EcoPaste 中.claude/settings.json的 SessionStart 钩子在 startup/clear/compact 三个 matcher 下运行session-start.py，UserPromptSubmit 钩子运行inject-workflow-state.py（解析[workflow-state:STATUS]块），PreToolUse 钩子为 Task/Agent 注入子 Agent 上下文。.cursor/hooks.json对应地注册了beforeShellExecution、preToolUse（matcher:Task|Subagent）、sessionStart三类钩子。

2. Agent Prelude / 拉取模式

部分平台无法让 hooks 可靠改写子 Agent 提示词，因此 agent 文件自身指示 agent 在启动后读取活动任务、PRD 和 JSONL 上下文。要修改子 Agent 的上下文加载方式，直接检查 agent 文件。

3. 主会话工作流模式

Kilo、Antigravity、Devin 等平台没有 Trellis 子 Agent 或 hook 能力，依赖 workflows/skills/commands 引导主会话 AI 读取文件、运行脚本、推进任务。修改行为需检查平台 workflows/skills/commands 和.trellis/workflow.md。

本地修改顺序：五步操作法

当用户要求定制某平台行为时，按此顺序检查：

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

不要只改平台文件而忘了共享 workflow；也不要只改.trellis/workflow.md而忘了平台入口可能仍含旧描述。

平台文件映射与决策规则

平台目录矩阵

修改平台文件时的决策规则

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

路径不一致时以实际文件为准

平台生态会变，用户项目可能已被定制。若矩阵与本地文件不一致，以用户项目中实际的 settings/config 为准：

• 检查 settings 注册的 hook 指向
• 检查 command/prompt/workflow 指向的脚本
• 依据 agent 文件当前的读取规则判断行为

不要因为路径表没列出就删除自定义文件。

平台文件的分工与修改要点

agents：角色定义文件

Trellis agent 文件定义专业化角色：trellis-research（调查问题并把发现写入当前任务research/）、trellis-implement（依据 prd.md、可选 design.md/implement.md、implement.jsonl 和相关 spec/research 实现）、trellis-check（审查变更、修复发现的问题并运行必要检查）。各平台 agent 路径不同：

• Claude Code：.claude/agents/trellis-*.md
• Codex：.codex/agents/trellis-*.toml
• Kiro：.kiro/agents/trellis-*.json
• Cursor：.cursor/agents/trellis-*.md
• OpenCode：.opencode/agents/trellis-*.md

两种上下文加载模式：hook push（平台 hook 在 agent 启动前注入任务上下文，agent 文件专注职责与边界）和agent pull（agent 文件指示 agent 启动后读取：task.py current --source、implement.jsonl/check.jsonl、JSONL 引用的 spec/research、prd.md、design.md、implement.md）。修改原则：保持单一职责、明确读取顺序、明确写入边界、多平台语义同步。EcoPaste 中.trellis/agents/check.md与 implement.md 是平台无关的 channel runtime agent 定义，编辑平台内 trellis-implement/check.md 不会改变 channel worker 行为。

hooks 与 settings：连接平台的入口层

settings/config 通常注册：session-start hook（会话开始注入 Trellis 概览）、workflow-state hook（解析[workflow-state:STATUS]块并发出匹配当前任务状态的内容）、sub-agent context hook（子 Agent 启动时注入任务上下文）、shell/session bridge（让 shell 命令看到同一 Trellis 会话身份）、平台插件/扩展入口。常见脚本类型：

EcoPaste 中.claude/hooks/inject-workflow-state.py正是这样解析 workflow.md 中的[workflow-state:no_task]、[workflow-state:planning]、[workflow-state:in_progress]、[workflow-state:completed]等块。.claude/hooks/session-start.py则输出<session-context>、<current-state>（含 git 分支状态、当前任务状态、journal 行数、spec index 数）、<trellis-workflow>（Phase Index 摘要）、<task-status>等结构化块，并支持TRELLIS_HOOKS=0/TRELLIS_DISABLE_HOOKS=1及非交互标志跳过注入。Cursor 的.cursor/hooks/inject-shell-session-context.py负责 shell 会话桥接。修改原则：settings 负责接线、hooks 定义行为；先确认平台事件名；hooks 读本地.trellis/而非上游源码；错误必须可见。

skills、commands、prompts、workflows：文本入口

常见 skill 结构为目录（SKILL.md+references/）：SKILL.md说明何时使用、先读哪个 reference、不该做什么；references 承载长文解释。命令/提示词/工作流通常是单文件，包含何时使用、读哪些.trellis/文件、运行哪些脚本、完成后如何汇报，不存储任务状态。修改原则：入口文件保持简短、触发描述具体、跨平台语义一致、项目特定能力放入本地 skill。

排障路径：AI 未读取 Trellis 状态时

若用户反馈"AI 没有读取 Trellis 状态"：

1. 检查平台 settings 是否注册了 hook
2. 检查 hook 文件是否存在
3. 手动运行 hook 依赖的命令（.trellis/scripts/get_context.py或task.py current --source）
4. 检查.trellis/.runtime/sessions/是否存在活动任务状态
5. 检查平台 shell 是否传递会话身份

关键配置文件实例

.claude/settings.json的 hook 注册结构

{ "hooks": { "PreToolUse": [ { "hooks": [{ "command": "python3 .claude/hooks/inject-subagent-context.py", "timeout": 30, "type": "command" }], "matcher": "Task" }, { "hooks": [{ "command": "python3 .claude/hooks/inject-subagent-context.py", "timeout": 30, "type": "command" }], "matcher": "Agent" } ], "SessionStart": [ { "hooks": [{ "command": "python3 .claude/hooks/session-start.py", "timeout": 30, "type": "command" }], "matcher": "startup" }, { "hooks": [{ "command": "python3 .claude/hooks/session-start.py", "timeout": 30, "type": "command" }], "matcher": "clear" }, { "hooks": [{ "command": "python3 .claude/hooks/session-start.py", "timeout": 30, "type": "command" }], "matcher": "compact" } ], "UserPromptSubmit": [ { "hooks": [{ "command": "python3 .claude/hooks/inject-workflow-state.py", "timeout": 15, "type": "command" }] } ] } }

.cursor/hooks.json的对应注册

{ "hooks": { "beforeShellExecution": [{ "command": "python3 .cursor/hooks/inject-shell-session-context.py", "timeout": 5 }], "preToolUse": [{ "command": "python3 .cursor/hooks/inject-subagent-context.py", "matcher": "Task|Subagent", "timeout": 30 }], "sessionStart": [{ "command": "python3 .cursor/hooks/session-start.py", "timeout": 30 }] }, "version": 1 }

.trellis/config.yaml中的平台相关配置

channel: worker_guard: idle_timeout: 5m max_live_workers: 6 # codex: # dispatch_mode: inline # 或 "sub-agent" 派发 trellis-* 子 Agent

codex.dispatch_mode是 Codex 专属开关，默认inline（主 Agent 直接改代码，因为 Codex 子 Agent 以fork_turns="none"隔离运行，无法继承父会话上下文）；设为sub-agent可启用旧式派发模型。其他平台忽略此键。

结论

Trellis 平台文件的本质是一层薄适配：共享运行时在.trellis/，平台目录只负责"接线"。EcoPaste 仓库展示了多平台（Claude Code、Cursor、Codex、OpenCode、Kiro、Gemini CLI）同时接入的实际布局，涵盖 hooks 驱动、agent 拉取、主会话工作流三种模式。理解共享/平台文件的边界、按序检查、以本地文件为准，是安全定制多平台 AI 工作流的关键。

• 桌面应用