桌面应用【免费下载链接】EcoPaste跨平台的剪贴板管理工具 | Cross-platform clipboard management tool项目地址https://gitcode.com/ayangweb/EcoPaste点击查看免费下载本文以 hooks-and-settings.md 为核心骨架结合 EcoPaste 仓库中已落地的.claude/、.cursor/、.codex/、.opencode/、.gemini/、.kiro/等平台目录与.trellis/运行时进行源码级佐证讲解settings/config 文件负责注册钩子钩子脚本负责注入行为两者如何协作让不同 AI 工具Claude Code、Cursor、Codex、OpenCode、Gemini CLI、Kiro 等在正确的时机读取同一个 Trellis 会话状态。读完本文你将能① 分清哪些平台文件负责注册、哪些负责行为② 针对AI 没读到 Trellis 状态给出完整的排查路径③ 按本地修改顺序正确落地一次上下文策略调整而不会改错层级。一、先厘清概念平台文件与 Trellis 共享文件的边界在进入 hooks/settings 之前必须先确立一个边界否则后面的所有判断都会出错。Trellis 采用同一套本地架构、多个 AI 工具适配的设计platform-files/overview.md 把仓库根目录下的文件划分成两类共享文件Shared files.trellis/workflow.md、.trellis/tasks/、.trellis/spec/、.trellis/scripts/。这是 Trellis 的业务状态与脚本所在地所有平台共用不归属任何一个 AI 工具。平台文件Platform files.claude/、.codex/、.cursor/、.opencode/、.kiro/、.gemini/、.qoder/、.codebuddy/、.github/、.factory/、.pi/、.trae/等目录。这些目录不存储业务状态只负责让对应 AI 工具看得见Trellis 状态、能调用 Trellis 脚本、能加载 Trellis 的 skills/agents/hooks。换句话说hooks/settings 是连接平台与 Trellis 的入口层entry layer——它决定某个平台在哪些事件上运行哪些脚本、插件或扩展。以 EcoPaste 仓库为例可以直观看到这套布局同时存在.claude/、.cursor/、.codex/、.gemini/、.kiro/、.opencode/六个平台目录都已生成而.trellis/下同时存在workflow.md、tasks/、spec/、scripts/等共享内容。这些平台目录是否存在于某个项目完全取决于用户当初执行过哪些trellis init --platform参数。二、Settings 的职责它们到底注册了什么settings/config 文件的核心职责是注册register而不是实现。文档明确列出它们通常注册的五类能力注册项作用session-start hook新会话启动或上下文重置时注入一份 Trellis 总览workflow-state hook每次用户输入时解析.trellis/workflow.md中的[workflow-state:STATUS]块并输出与当前任务status匹配的正文纯解析器脚本内不内置兜底内容sub-agent context hook当 implement/check/research 等子代理启动时注入任务上下文shell/session bridge让 shell 命令看到与当前 Trellis 会话一致的会话身份platform plugin / extension 入口平台自身的插件或扩展注册点下面逐项看 EcoPaste 仓库中的真实落地并对照文档给出的常见文件清单逐一验证。2.1 各平台 settings/config 常见路径与仓库实证文档给出如下平台到配置文件的映射表EcoPaste 仓库中已生成的五个平台均可逐条对应上平台settings/config 路径仓库实测已存在Claude Code.claude/settings.json✅.claude/settings.jsonCursor.cursor/hooks.json✅.cursor/hooks.jsonCodex.codex/hooks.json、.codex/config.toml✅ 两者均存在OpenCode.opencode/package.json、.opencode/plugins/*✅package.json声明插件依赖plugins/下有三个插件Kiro.kiro/hooks/ 平台配置✅.kiro/hooks/下含 4 个脚本/配置文件Gemini CLI.gemini/settings.json✅.gemini/settings.jsonGitHub Copilot.github/copilot/hooks.json文档列出本仓库未生成取决于 init 参数Trae IDE.trae/hooks.json文档列出本仓库未生成Reasonix / ZCode不使用 hooks/settingspull 式平台见下文第四节说明.claude/、.cursor/、.codex/、.opencode/、.gemini/、.kiro/六个目录在仓库根目录中真实存在其余平台Copilot、Qoder、CodeBuddy、Factory Droid、Pi Agent、Trae 等属于文档列出的映射不在当前仓库生成范围内。不要因为某平台目录缺失就推断其不支持 hooks——这只是 init 参数没选到它。2.2 逐平台解读注册内容仓库源码级Claude Code ——.claude/settings.json注册了 3 类事件、共 4 个钩子注册块SessionStartmatcher 分别为startup、clear、compact统一执行python3 .claude/hooks/session-start.pytimeout 30 秒。也就是说新开会话、/clear清空上下文、/compact压缩上下文这三种上下文重置场景都会触发会话总览注入。UserPromptSubmit每次用户提交提示词时执行python3 .claude/hooks/inject-workflow-state.pytimeout 15 秒——这就是逐轮 workflow 面包屑。PreToolUsematcher 为Task与Agent执行python3 .claude/hooks/inject-subagent-context.pytimeout 30 秒——在调用子代理工具前注入 PRD/spec 上下文。Cursor ——.cursor/hooks.json采用与 Claude 不同的事件命名注册 3 个钩子sessionStart执行.cursor/hooks/session-start.py。preToolUsematcherTask|Subagent执行.cursor/hooks/inject-subagent-context.py。beforeShellExecution执行.cursor/hooks/inject-shell-session-context.pytimeout 仅 5 秒——这是 Cursor 独有的 shell 会话桥见 2.4 节。Codex —— 注册文件拆成两个.codex/hooks.json只注册了UserPromptSubmit→python3 -X utf8 .codex/hooks/inject-workflow-state.pytimeout 15。注意-X utf8这是对 Windows 代码页cp936 等下非 ASCII 内容中文任务名、PRD 片段的显式 UTF-8 兜底。.codex/config.toml本身不注册钩子而是配置项目级行为project_doc_fallback_filenames [AGENTS.md]声明 AGENTS.md 为主项目指令文件文件内注释还给出了两条重要的运行时前提——① Codex hooks 只有在用户级~/.codex/config.toml中开启[features].hooks true才生效Codex 0.129旧名codex_hooks true会触发弃用警告② Codex 0.129 还要求用户在/hooksTUI 中逐个审批安装的钩子未审批前钩子保持不激活。这是一处很好的settings 与运行时前提对照注册了 ≠ 生效了。Gemini CLI ——.gemini/settings.json是逐轮事件命名差异的典型样本。它注册两个钩子SessionStart→.gemini/hooks/session-start.pytimeout 30000ms注意 Gemini 的 timeout 单位是毫秒。BeforeAgent→.gemini/hooks/inject-workflow-state.pytimeout 15000ms。为什么是BeforeAgent而不是UserPromptSubmitinject-workflow-state.py 的文件头注释给出答案Gemini CLI 0.40.x 把逐轮事件改名为BeforeAgent其 schema 校验器会拒绝旧事件名因此脚本用_detect_platform在运行时从输入数据中探测平台例如检测cursor_version字段、CLAUDE_PROJECT_DIR/CURSOR_PROJECT_DIR环境变量再决定输出hookEventName用哪个名字。这就是不同平台对同一事件有不同的命名的实证。Kiro ——.kiro/hooks/ 平台配置。Kiro 的注册方式与以上都不同.kiro/hooks/trellis-workflow-state.kiro.hook是一个独立 JSON 声明文件结构为{ version: 1.0.0, enabled: true, name: trellis-workflow-state, description: Inject Trellis workflow state on each prompt, when: { type: promptSubmit }, then: { type: runCommand, command: python3 .kiro/hooks/inject-workflow-state.py, timeout: 30 } }它把触发事件when.type promptSubmit与要执行的命令then显式分离是hooks 文件描述事件接线、脚本定义行为这一原则最直白的体现。inject-workflow-state.py 的注释还补充说明Kiro 有两条接线路径——CLI 自定义 agent 的hooks.userPromptSubmit与 IDE 的.kiro.hookpromptSubmit事件且 Kiro 会直接把 hook 的 stdout 拼进对话上下文因此它的输出分支是纯文本面包屑。OpenCode —— 插件体系。OpenCode 不走 CLI hooks 文件而是.opencode/package.json声明插件依赖 plugins/*.js实现三个插件{ dependencies: { opencode-ai/plugin: ^1.14.39 } }.opencode/plugins/session-start.js监听chat.message事件用户发送首条消息时把构建好的会话上下文直接改写进消息本身从而持久化在历史中文件头注释明确说明选择chat.message而非chat.init正是为了让它留在历史里。.opencode/plugins/inject-subagent-context.js监听tool.execute.before在 Task 工具被调用且子代理类型为 implement/check/research 时注入 PRD、spec、research 上下文它还用正则^\s*Active task:\s*(\S)\s*$从派发提示词首行解析出目标任务路径支持多窗口下区分任务。.opencode/plugins/inject-workflow-state.jsOpenCode 版的逐轮面包屑。2.3 OpenCode 作为三模式融合的样本对照 platform-files/overview.md 的三种平台集成模式OpenCode 恰好是叠加态Hook/Extension 驱动plugins/*三个插件做事件注入Agent Prelude / Pull 式.opencode/agents/trellis-implement.md、trellis-check.md、trellis-research.md三个 agent 文件通过 prelude 指令指导子代理启动后读什么Main-Session Workflow.opencode/commands/trellis/下的start.md、continue.md、finish-work.md三个命令作为显式入口。同时它把插件共享逻辑抽到.opencode/lib/session-utils.js、trellis-context.js三个插件都复用同一套上下文构建与去重逻辑hasPersistedInjectedContext/markContextInjected防止重复注入。2.4 shell 会话桥让 shell 命令继承会话身份shell/session bridge是 settings 注册项里最容易被忽略的一项。它在 Cursor 的落地是.cursor/hooks/inject-shell-session-context.pybeforeShellExecutiontimeout 5 秒脚本头部注释解释了问题与解法Cursor 的 shell 命令环境不会继承 SessionStart 数据。此钩子在 Cursor 运行一个会调用task.py start/current/finish的 shell 命令之前写入一张短生命周期的 runtime 票据tickettask 脚本只有在没有原生会话环境时才消费这张票据。脚本定义了DIR_RUNTIME .runtime、DIR_CURSOR_SHELL cursor-shell、SESSION_SUBCOMMANDS {start, current, finish}、TICKET_TTL_SECONDS 30。也就是说如果你在 Cursor 的终端里跑task.py current却发现没有活跃任务问题极可能出在这一层会话身份的传递上见第六节排查路径第 5 步。三、Hook 脚本类型四种脚本各管一件事文档给出四种 hook 脚本的职责矩阵仓库中各平台 hooks 目录的实际情况完全对应脚本职责仓库分布实证session-start.py生成会话起始上下文.claude/hooks/、.cursor/hooks/、.codex/hooks/、.gemini/hooks/、.kiro/hooks/均存在inject-workflow-state.py解析.trellis/workflow.md中[workflow-state:STATUS]块输出与当前任务状态匹配的正文找不到匹配块时回退到固定行Refer to workflow.md for current step..claude/hooks/、.codex/hooks/、.gemini/hooks/、.kiro/hooks/OpenCode 侧为inject-workflow-state.jsinject-subagent-context.py向子代理注入 PRD、JSONL 上下文及关联 spec/research.claude/hooks/、.cursor/hooks/、.kiro/hooks/OpenCode 侧为inject-subagent-context.jsinject-shell-session-context.py让 shell 命令继承 Trellis 会话身份仅.cursor/hooks/两点重要的运行时事实需要强调1. workflow-state 是纯解析器脚本里没有兜底字典。inject-workflow-state.py 头部注释明确Breadcrumb text is pulled exclusively from workflow.md [workflow-state:STATUS] tag blocks — workflow.md is the single source of truth. There are no fallback dicts in this script。当.trellis/目录不存在或对应 tag 缺失时脚本只会输出那一句通用回退文案让用户看得见并去修复而不是静默掩盖问题。它还区分了安静退出exit 0 且无输出的场景非 Trellis 项目无.trellis/目录、task.json 损坏或缺少 status。2. 不是每个平台都有每一种 hook。对比六个平台目录能清晰看到差异inject-shell-session-context.py只存在于.cursor/hooks/因为只有 Cursor 暴露了beforeShellExecution事件.codex/hooks/只有inject-workflow-state.py和session-start.py没有 subagent 注入脚本——Codex 的 sub-agent 上下文由 agent 文件 prelude 承担。修改时严禁把别的平台的脚本复制过来硬凑第一步永远是确认该平台是否支持对应事件见第五节原则 2。四、pull 式平台不需要 hooks/settings文档特别指出Reasonix 与 ZCode 是 pull 式平台不使用 hooks 或 settings 文件它们的 agent 文件内包含启动后读取上下文的 prelude 指令。这与 overview.md 的三种平台集成模式中的第二种Agent Prelude / Pull-Based一致这类平台无法可靠地让 hooks 改写子代理提示词因此改为在 agent 文件里写死启动后读活跃任务、PRD、JSONL 上下文的指令。这也是一个重要的判断准则一个平台目录里没有 hooks/settings不代表它没有接入 Trellis只是接法不同。判断平台如何接入应该先看它属于三种模式中的哪一种再决定去检查 hooks/plugins 还是 agent prelude。五、修改原则settings 接线、hooks 定义行为文档给出四条修改原则全部有仓库实证支撑原则 1Settings 负责接线hooks 负责定义行为。只改 hook 脚本平台可能根本不会调用它没注册只改 settings行为可能不变。举例若你想改逐轮提示的措辞正确动作是编辑.trellis/workflow.md中的[workflow-state:STATUS]块——因为 hook 是verbatim解析 workflow.md 的无需改任何脚本而如果你想让每次输入都注入变成只在某个事件注入那才需要改 settings如.claude/settings.json的UserPromptSubmit注册块。原则 2先确认平台事件名。SessionStart、UserPromptSubmit、AgentSpawn、shell 执行等事件在各平台的命名不同Claude Code 用UserPromptSubmitGemini CLI 0.40.x 改名BeforeAgentCursor 用sessionStart/preToolUse/beforeShellExecutionKiro 用promptSubmitOpenCode 用chat.message/tool.execute.before。跨平台复制注册配置前务必核对目标平台文档的事件名。原则 3hooks 读本地.trellis/不读上游源码。脚本默认目标是用户项目里的.trellis/scripts/与.trellis/workflow.md。例如.trellis/scripts/get_context.py就是 session-start 注入所依赖的上下文脚本它以python3 get_context.py输出文本格式、python3 get_context.py --json输出 JSON 格式底层委托给.trellis/scripts/common/git_context.py的main()。原则 4错误必须可见。hook 失败时应明确告诉用户哪一段没有被注入而不是让 AI 在缺上下文的静默状态下继续工作。这就是 workflow-state 脚本刻意不做兜底字典、只输出Refer to workflow.md for current step.的原因——可见的退化优于静默的缺失。5.1 workflow-state 块的实际形态以 EcoPaste 为例.trellis/workflow.md是面包屑的唯一数据源。它的## Phase Index之前有一段WORKFLOW-STATE BREADCRUMB CONTRACT注释定义了完整的契约STATUS 字符集[A-Za-z0-9_-]TAG ↔ PHASE 作用域映射no_task无活跃任务Phase 1 前、planning整个 Phase 1statusplanning、planning-inlineCodex 内联变体、in_progressPhase 2 Phase 3.2-3.4status 从task.py start一直保持到task.py archive、in_progress-inlineCodex 内联变体、completed当前是死块——task.py archive在同一调用里写 status 并移动目录resolver 会丢失指针保留给未来的显式状态迁移不变量对应 regression 测试每个标记[required · once]的 walkthrough 步骤必须在其所在阶段的[workflow-state:*]块里有对应的强制执行行——面包屑是唯一的逐轮通道若某个必做步骤没被提及AI 会静默跳过Phase 1 计划门禁与 Phase 3.4 提交门禁都曾通过这个缺口暴露过 bug编辑检查清单改某个[workflow-state:STATUS]块时要同步核对对应阶段的[required · once]步骤改完运行trellis update把新正文推送到下游用户项目。真实块示例in_progressworkflow.md[workflow-state:in_progress] Tools: trellis-implement / trellis-research are sub-agent types only (Task/Agent tool, NOT Skill; there is no skill by these names). trellis-update-spec is a skill. trellis-check exists as both; prefer the Agent form when verifying after code changes. Flow: trellis-implement - trellis-check - trellis-update-spec - commit (Phase 3.4) - /trellis:finish-work. Main-session default: dispatch implement/check sub-agents. ... Dispatch prompt starts with Active task: task path from task.py current. Read context: jsonl entries - prd.md - design.md if present - implement.md if present. [/workflow-state:in_progress]这条逐轮提示策略要变 → 改 workflow.md 的块不需要改脚本的链路与文档Local Change Scenarios表中第二行完全对应。六、本地修改场景速查表文档原表附仓库落点文档给出的用户需求 → 修改位置映射结合仓库可归纳为用户需求修改位置仓库中的具体落点新会话中 AI 看到更多/更少的上下文平台session-starthook.claude/hooks/session-start.py、.cursor/hooks/session-start.py等及对应 settings 注册块逐轮提示策略要变.trellis/workflow.md中的[workflow-state:STATUS]块hook 原样解析无需改脚本workflow.md 的 Phase Index 块子代理读不到 PRD/specinject-subagent-contexthook 或 agent prelude.claude/hooks/inject-subagent-context.py、.cursor/hooks/inject-subagent-context.py、.opencode/plugins/inject-subagent-context.js或.claude/agents/trellis-implement.md的 Context Loading Protocolshell 里task.py current没有活跃任务shell/session bridge hook 或平台环境变量配置.cursor/hooks/inject-shell-session-context.py票据 TTL 30 秒禁用某个自动注入对应 settings/config 中的 hook 注册项如.claude/settings.json的 hooks 段、.cursor/hooks.json、.gemini/settings.json其中子代理上下文这一行值得展开.claude/agents/trellis-implement.md里有一段Trellis Context Loading Protocol子代理先查找输入中的!-- trellis-hook-injected --标记——标记存在说明 PRD/spec/research 已由 hook 自动加载直接开工标记缺失Windows Claude Code、--continue续会话、fork 分发、hooks 被禁用等场景则回退到从派发提示词首行Active task: path找任务路径手动读implement.jsonl、各清单文件、prd.md、design.md若有、implement.md若有。这证明了 hooks 与 agent prelude 是一对互为兜底的机制。七、故障排查路径当用户说AI 没有读到 Trellis 状态文档给出五步排查路径这里结合源码逐条给出验证手段第 1 步检查平台 settings 是否注册了 hook。直接核对注册文件.claude/settings.json、.cursor/hooks.json、.codex/hooks.json注意 Codex 还要先满足.codex/config.toml注释中提到的用户级[features].hooks true与/hooksTUI 审批、.gemini/settings.json、.kiro/hooks/*.kiro.hook的enabled字段。第 2 步检查 hook 文件是否存在。ls对应平台的 hooks/plugins 目录。注意各平台文件名与实现语言可能不同Python 系.claude/hooks/*.py、.cursor/hooks/*.py、.codex/hooks/*.py、.gemini/hooks/*.py、.kiro/hooks/*.pyOpenCode 是.opencode/plugins/*.js。第 3 步手动运行 hook 依赖的命令。python3 .trellis/scripts/get_context.py或加--json——session-start 注入依赖的会话上下文python3 .trellis/scripts/task.py current --source——活跃任务状态查询--source让脚本输出任务来源便于判断会话身份链路是否通。第 4 步检查活跃任务状态是否存在。活跃任务指针存储在.trellis/.runtime/sessions/下按 AI 会话/窗口维度存文件。workflow.md 的 Current-task mechanism 一节说明task.py create在会话身份可用时自动写入 per-session 活跃任务指针task.py start重复写入该指针幂等并把task.json.status从planning翻转为in_progresstask.py finish删除当前会话文件status 不变task.py archive task写statuscompleted、把目录移入archive/并清理遗留的 runtime 会话文件。若.trellis/.runtime/sessions/里没有对应文件说明没有活跃任务或会话身份未建立。第 5 步检查平台 shell 是否传递了会话身份。这正是 Cursor 的beforeShellExecution钩子inject-shell-session-context.py要解决的问题——写 30 秒 TTL 票据给task.py消费同时.trellis/scripts/common/active_task.py也证实活跃任务解析按每个 AI 会话/窗口存于.trellis/.runtime/sessions/没有稳定的会话身份会导致task.py start直接失败并给出会话身份提示提示语见 workflow.md 的 current-task 段落。排查时的另一个重要提醒hooks 只在事件触发时注入。如果你改了.claude/hooks/inject-subagent-context.py但对应的PreToolUse注册块还指向旧命令路径改动不会生效反之只在.claude/settings.json里加了注册、脚本文件却不存在平台会因找不到命令而报错或静默跳过。八、综合修改顺序从需求到落地的五步走当用户要求为某平台定制行为时platform-files/overview.md 给出的是自上而下逐层定位的顺序本文结合 hooks-and-settings 的职责把它收敛为一个可操作清单先读.trellis/workflow.md确认共享流程这个平台的逐轮行为到底应该长什么样、哪些步骤是[required · once]。因为 hooks 是它的只读解析器改任何注入行为前必须知道共享流程本身。读目标平台的 settings/config看它注册了哪些 hooks/agents/skills/commands对应本文第二节各平台注册清单。读目标平台的 agents/skills/commands/hooks具体实现确认已注册的接线对应的行为是什么。改离需求最近的那个本地文件逐轮提示改workflow.md的块注入量改 session-start 钩子/脚本子代理上下文改 subagent 钩子或 agent preludeshell 会话改 bridge 钩子禁用注入改 settings 注册。若改动影响共享流程同步.trellis/workflow.md或.trellis/spec/。反向同理——不能只改共享流程而忘了平台入口文件里可能还残留旧描述。最后再强调一遍文档中反复出现的两种错误形态只改平台文件而忘记共享流程hooks 解析的还是旧的 workflow.md以及只改.trellis/workflow.md而忘了平台入口文件里旧的描述agents 的 prelude 还在指老路径。每一次上下文策略调整本质上都是在共享事实workflow.md与平台接线settings/hooks之间保持同步这就是 Trellis 多平台接入能够稳定运行的底层原因。赞分享桌面应用【免费下载链接】EcoPaste跨平台的剪贴板管理工具 | Cross-platform clipboard management tool项目地址https://gitcode.com/ayangweb/EcoPaste点击查看免费下载相关推荐EcoPaste 仓库平台接入文件解析Trellis 平台文件Platform Files架构全解EcoPaste 仓库平台接入文件解析Trellis 平台文件Platform Files架构全解 导读 本文聚焦 Trellis 将本地架构接入不同 A桌面应用Trellis 项目本地约定注入指南用 .trellis/spec/ 与项目级 Skill 承载团队规范EcoPaste 仓库实战Trellis 项目本地约定注入指南用 .trellis/spec/ 与项目级 Skill 承载团队规范EcoPaste 仓库实战 本篇指南讲解在已通过桌面应用Superpowers 接入 OpenCodeopencode.json 插件配置、技能自动注册与故障排查实战Superpowers 接入 OpenCodeopencode.json 插件配置、技能自动注册与故障排查实战 Superpowers 以「git 后端的插件AI 技能AI 插件开发工具上一篇React Bits 实战指南JSX 条件渲染的六种模式与最佳实践短路求值、IIFE、do 表达式与提前返回下一篇告别模糊标注LabelImg低光照图像优化的3个实用技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
