EcoPaste 仓库中的 Trellis Hooks 与 Settings 接入层:平台事件如何驱动 AI 上下文注入
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
}
可以看到三个要点:
- 事件名是平台特定的:Cursor 使用
beforeShellExecution、preToolUse、sessionStart,而不是 Claude Code 的PreToolUse、SessionStart、UserPromptSubmit; - matcher 用于缩小触发范围:
preToolUse只在工具匹配Task|Subagent时才运行inject-subagent-context.py; - 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 中调整提示策略是最直接、也最不容易出错的方式——不需要触碰任何脚本。
修改原则:四条约束
- Settings 负责接线,Hooks 负责行为。只改 hook 脚本,平台可能永远不会调用它;只改 settings,行为可能没有变化。两者必须成对检查。
- 先确认平台事件名。SessionStart、UserPromptSubmit、AgentSpawn、shell 执行等事件在不同平台叫法不同(如
.cursor/hooks.json中的beforeShellExecution与.claude/settings.json中的PreToolUse),直接套用另一平台的配置文件是常见失败原因。 - Hooks 只读本地
.trellis/,不依赖上游源码。.trellis/scripts/与.trellis/workflow.md是默认目标,hook 不应引用 Trellis 上游源路径。 - 错误必须可见。hook 失败时应当明确告知用户「哪些内容没有注入」,而不是静默让 AI 失去上下文。
排查路径:当「AI 没有读取 Trellis 状态」时
当用户反馈「AI did not read Trellis state」时,按以下顺序逐层排查:
- 检查平台 settings 是否注册了对应 hook;
- 检查 hook 文件是否存在;
- 手动运行 hook 所依赖的命令,例如
.trellis/scripts/get_context.py或task.py current --source; - 检查
.trellis/.runtime/sessions/中是否存在活动任务状态; - 检查平台 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 体系在两个平台上的不同事件命名与注册风格,可作为你理解与自定义自家项目接入层时的直接参考。