EcoPaste 仓库中的 Trellis Hooks 与 Settings 接入层:平台事件如何驱动 AI 上下文注入

原创2026-10-08 18:59:001,923 阅读
文章标签:桌面应用开发工具

EcoPaste 仓库中的 Trellis Hooks 与 Settings 接入层:平台事件如何驱动 AI 上下文注入

导读

本篇文章围绕 Trellis 架构中的「Hooks And Settings」接入层展开,说明 settings/config 文件与 hook 脚本如何协作,把剪贴板管理工具 EcoPaste 这类本地项目连接到不同 AI 平台(Cursor、Claude Code、Codex、Gemini CLI 等),决定平台在哪些事件上运行哪些脚本。读完本文,你将掌握 Trellis 每类 hook 的职责、各平台配置文件位置、本地修改的正确顺序,以及当「AI 没有读取 Trellis 状态」时的排查路径。文中所引用的配置与脚本均来自当前仓库真实存在的 .cursor/hooks.json、.claude/settings.json 与 .cursor/hooks/ 目录,可作为落地参考。

Hooks 与 Settings 的定位:平台与 Trellis 之间的入口层

在 Trellis 的本地架构中,.trellis/ 目录存放共享运行态(workflow、tasks、spec、scripts),而平台目录(.claude/、.cursor/、.codex/、.opencode/ 等)存放「适配文件」,负责让对应 AI 工具进入 Trellis。Hooks/settings 正是这一入口层:它们决定平台为哪些事件运行哪些脚本、插件或扩展,是「AI 何时知道什么」的开关所在。

一个平台目录是否出现、出现哪些文件,取决于用户运行过哪些 trellis init --<platform> 参数。也就是说,hooks 与 settings 文件是 trellis init 的产物,而不是 Trellis 上游源码的一部分。以本仓库为例,当前项目根目录下实际存在 .cursor/hooks.json 与 .claude/settings.json,说明该仓库至少通过 --cursor 与 --claude 完成了初始化。

Settings 的职责:注册而非实现

settings/config 文件本身不承载业务逻辑,它们负责注册:

  • session-start hook:新会话开始或上下文重置时,注入一份 Trellis 概览;
  • workflow-state hook:解析 .trellis/workflow.md 中的 [workflow-state:STATUS] 块,在每次用户输入时输出与当前任务 status 匹配的正文;该脚本仅做解析,不内嵌任何兜底内容;
  • sub-agent context hook:在 implementation/check/research 类 Agent 启动时注入任务上下文;
  • shell/session bridge:让 shell 命令看到与 Trellis 会话一致的会话身份;
  • 平台插件或扩展的入口点。

各平台的 settings/config 文件位置如下:

平台 settings/config
Claude Code .claude/settings.json
Cursor .cursor/hooks.json
Codex .codex/hooks.json、.codex/config.toml
OpenCode .opencode/package.json、.opencode/plugins/*
Kiro .kiro/hooks/ + 平台配置
Gemini CLI .gemini/settings.json
Qoder .qoder/settings.json
CodeBuddy .codebuddy/settings.json
GitHub Copilot .github/copilot/hooks.json
Factory Droid .factory/settings.json
Pi Agent .pi/settings.json、.pi/extensions/trellis/
Trae IDE .trae/hooks.json

Reasonix 与 ZCode 属于 pull-based 平台,不使用 hooks/settings 文件;它们的 agent 文件内含 prelude 指令,在启动后主动读取上下文。这些文件是否存在于某个项目,取决于用户运行过哪些 trellis init --<platform> 参数。

Hook 脚本类型与各自职责

平台注册的 hook 最终会调用本地脚本。Trellis 的标准脚本类型如下:

脚本 用途
session-start.py 生成 session-start 上下文
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 会话身份

并非每个平台都支持全部 hook 类型。 当一个平台缺少某类 hook 时,不要直接从其他平台复制文件——应首先确认该平台是否支持对应的事件(如 SessionStart、UserPromptSubmit、AgentSpawn、shell 执行等)。

仓库实例:.cursor/hooks.json 的真实注册

当前仓库根目录的 .cursor/hooks.json 展示了 Cursor 平台上三类事件的注册方式:

{
  "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
}

可以看到三个要点:

  1. 事件名是平台特定的:Cursor 使用 beforeShellExecution、preToolUse、sessionStart,而不是 Claude Code 的 PreToolUse、SessionStart、UserPromptSubmit;
  2. matcher 用于缩小触发范围:preToolUse 只在工具匹配 Task|Subagent 时才运行 inject-subagent-context.py;
  3. timeout 明确给出:上下文注入类 hook 允许 30 秒,shell 桥接仅 5 秒。

这些命令指向的脚本确实存在于仓库的 .cursor/hooks/ 目录下(inject-shell-session-context.py、inject-subagent-context.py、session-start.py),与注册命令一一对应。

仓库实例:.claude/settings.json 的注册结构

Claude Code 的配置采用嵌套的 matcher -> hooks 结构,同一脚本可被多个事件复用。仓库根目录的 .claude/settings.json 摘录如下:

{
  "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" }] }
    ]
  }
}

关键差异点:

  • 同一 inject-subagent-context.py 同时挂在 Task 与 Agent 两个 matcher 下,实现「子 Agent 启动前注入上下文」;
  • SessionStart 细分了 startup、clear、compact 三种触发时机,对应新会话、上下文清空与压缩;
  • UserPromptSubmit 每轮用户输入都会调用 inject-workflow-state.py,且只给 15 秒超时——这正是「每轮轻量提示」定位的体现;
  • 从源码结构看,Claude Code 侧注册了 inject-workflow-state.py,而 Cursor 侧未注册该 hook,说明两平台的注入策略确实不同,印证了「不要跨平台照抄 settings」的原则。

本地修改场景:用户需求对应到哪一层

当用户提出定制诉求时,应按下表找到正确的编辑位置:

用户需求 编辑位置
AI 在新会话中应看到更多/更少的上下文 平台的 session-start hook
每轮提示策略需要调整 .trellis/workflow.md 中的 [workflow-state:STATUS] 块。hook 逐字解析 workflow.md,无需改脚本
子 Agent 读不到 PRD/spec inject-subagent-context hook 或 agent prelude
shell 中执行 task.py current 显示无活动任务 shell/session bridge hook 或平台环境变量配置
禁用某类自动注入 对应 hook 在 settings/config 中的注册条目

以第二行为例:workflow-state 的语义完全由 .trellis/workflow.md 中的状态块决定(如 no_task、planning、in_progress、completed),hook 只负责「找到匹配块并输出其正文」,因此在 workflow.md 中调整提示策略是最直接、也最不容易出错的方式——不需要触碰任何脚本。

修改原则:四条约束

  1. Settings 负责接线,Hooks 负责行为。只改 hook 脚本,平台可能永远不会调用它;只改 settings,行为可能没有变化。两者必须成对检查。
  2. 先确认平台事件名。SessionStart、UserPromptSubmit、AgentSpawn、shell 执行等事件在不同平台叫法不同(如 .cursor/hooks.json 中的 beforeShellExecution 与 .claude/settings.json 中的 PreToolUse),直接套用另一平台的配置文件是常见失败原因。
  3. Hooks 只读本地 .trellis/,不依赖上游源码。.trellis/scripts/ 与 .trellis/workflow.md 是默认目标,hook 不应引用 Trellis 上游源路径。
  4. 错误必须可见。hook 失败时应当明确告知用户「哪些内容没有注入」,而不是静默让 AI 失去上下文。

排查路径:当「AI 没有读取 Trellis 状态」时

当用户反馈「AI did not read Trellis state」时,按以下顺序逐层排查:

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

这套路径覆盖了「注册缺失」「文件缺失」「脚本本身失败」「运行时状态缺失」「会话身份未贯通」五类根因。第 3 步尤为关键:它能把「hook 未生效」与「脚本自身报错」区分开——若手动执行脚本正常,问题大概率出在 settings 注册或事件匹配上;若手动执行即失败,则要先修复脚本依赖。

结合上下文注入系统理解 hooks 的定位

从 .cursor/skills/trellis-meta/references/local-architecture/context-injection.md 可以看到 hooks 在整条注入链路中的位置:session 上下文(get_context.py)、workflow 上下文(workflow.md)、spec 上下文(.trellis/spec/ + 任务 JSONL)、task 上下文(prd.md / design.md / implement.md / research/)最终都靠「平台 hooks/settings/agents」这一层输送给不同 AI 工具。

子 Agent 的上下文加载有两种模式:

  • hook push:平台 hook 在 Agent 启动前注入 JSONL 引用的文件以及 prd.md、design.md(若存在)、implement.md(若存在);
  • agent pull:agent 定义指示 Agent 启动后自行读取活动任务、JSONL 上下文与任务产物。

判断当前平台属于哪种模式,是排查「Agent 没读 JSONL」问题的前提:hook push 模式改 inject-subagent-context,agent pull 模式则改 agent 文件本身。此外,活动任务状态位于 .trellis/.runtime/sessions/ 且按会话隔离,hook 会尝试从平台事件、环境变量、transcript 路径或 TRELLIS_CONTEXT_ID 解析 context key——若 shell 命令看不到同一个 key,task.py current --source 就可能报「无活动任务」,此时应检查平台是否把会话身份传入 shell,而不是手工写一个全局 current-task 文件。

小结

Hooks 与 Settings 是 Trellis 在本地项目中的「接线层」:settings 注册事件与脚本的对应关系,hook 脚本实现具体的上下文注入行为,二者缺一不可。修改时遵循「先确认平台事件名、再成对检查 settings 与脚本、只读本地 .trellis/、错误必须可见」四条原则,并在排查时沿着「注册 → 文件 → 脚本 → 运行时状态 → 会话身份」的路径逐层定位。仓库中 .cursor/hooks.json 与 .claude/settings.json 两份真实配置,恰好展示了同一套 hook 体系在两个平台上的不同事件命名与注册风格,可作为你理解与自定义自家项目接入层时的直接参考。

登录后查看全文
EcoPaste