EcoPaste 项目中的 Trellis 本地上下文注入系统（Local Context Injection）：让 AI 在正确时机读取正确文件的完整指南-北京尧图网络

桌面应用【免费下载链接】EcoPaste跨平台的剪贴板管理工具 | Cross-platform clipboard management tool项目地址https://gitcode.com/ayangweb/EcoPaste点击查看免费下载导读Trellis 的上下文注入Context Injection旨在让 AI 在正确的时间读取正确的文件而不是依赖模型记忆。本文以 Trellis 的本地架构参考文档 context-injection.md 为骨架结合 EcoPaste 仓库中实际部署在.kiro/目录下的钩子脚本、Agent 定义与技能配置系统讲解五种注入上下文类型、session-start / workflow-state / sub-agent 三种注入机制、JSONL 读取规则、Active Task 上下文键解析以及完整的本地定制点与排障流程。读完本文你将掌握如何排查AI 在新会话中不认识当前任务、如何调整每个用户回合的 workflow-state 提示、如何为 implement/check 子代理装配任务上下文以及如何把 JSONL 清单正确配置成 spec/research 的上下文清单。一、背景Trellis 本地架构与上下文注入的定位在 EcoPaste 项目中Trellis 以用户项目内的本地文件形态存在.trellis/目录承载工作流、任务、规范、记忆、脚本与运行时状态而.kiro/、.claude/、.cursor/等平台目录负责把 Trellis 工作流接到不同的 AI 工具上。整体分为三层见 overview.md工作流层.trellis/workflow.md定义阶段、路由、下一步动作与提示块持久化层.trellis/tasks/、.trellis/spec/、.trellis/workspace/存储任务、规范与会话记忆平台集成层平台目录下的 hooks、settings、agents、skills 等把工作流接到不同 AI 工具。上下文注入正是横跨这三层的关键机制它把持久化层的内容通过平台集成层的钩子与 Agent 定义在正确的时机注入到工作流层的会话中。其核心哲学是——AI 应该从文件系统读取上下文而不是靠模型记忆。二、注入的上下文类型Injected Context Types原文档用一张表定义了 Trellis 注入的五类上下文。下表完整保留其定义并补充了在 EcoPaste 仓库中的落点类型来源用途session context会话上下文.trellis/scripts/get_context.py当前开发者、git 状态、活动任务、活跃任务列表、日志journal、包信息workflow context工作流上下文.trellis/workflow.md当前 Trellis 流程与下一步动作spec context规范上下文.trellis/spec/ 任务 JSONL实现/检查阶段必须遵守的规范task context任务上下文.trellis/tasks/task/prd.md、design.md、implement.md、research/当前任务的需求、设计、执行计划与调研资料platform context平台上下文平台 hooks/settings/agents让不同 AI 工具通过各自机制读取上述文件在 EcoPaste 的.kiro/目录中这三类平台集成落点均有实际文件hooks/下有session-start.py、inject-workflow-state.py、inject-subagent-context.py三个钩子脚本agents/下有trellis.json主会话代理、trellis-implement.json、trellis-check.json、trellis-research.json四个代理定义skills/下则是一组 Trellis 技能trellis-brainstorm、trellis-check、trellis-finish-work 等。主代理 trellis.json 的 prompt 中明确写道信任注入的session-context概览与workflow-state面包屑来定位自身不要从零重新推导上下文——这正是注入替代记忆的实践体现。三、session-start新会话注入总览3.1 触发时机与注入内容支持 session-start 的平台会在会话启动、清空、压缩compact或收到类似事件时向 AI 注入一份 Trellis 总览。原文档列出注入内容通常包括工作流摘要workflow summary当前任务状态current task status活跃任务active tasks规范索引路径spec index paths开发者身份与 git 状态developer identity and git status。3.2 EcoPaste 中的实现session-start.py.kiro/hooks/session-start.py 是这一机制在 EcoPaste 的实际落地。它从 stdin 读取平台传入的 JSON payload解析出项目根目录后依次组装以下注入块session-context声明Trellis 压缩版 SessionStart 上下文用于定位会话细节按需加载first-reply-notice一次性通知 AI 首条回复时用中文声明 SessionStart 上下文已加载one-shot同会话内不重复current-state由_build_compact_current_state()生成包含开发者身份、git 分支与脏文件数_format_git_state、当前任务路径与状态、活跃任务总数、日志行数Journal: xxx, N / 2000 lines、可用规范索引数trellis-workflow只注入workflow.md中## Phase Index的压缩摘要_extract_range截取 _strip_breadcrumb_tag_blocks剔除面包屑标签块并提示完整细节可用get_context.py --mode phase --step X.Y按需加载guidelines任务上下文读取顺序jsonl → prd.md → design.md 若存在 → implement.md 若存在以及可用规范索引清单与get_context.py --mode packages的发现方式task-status由_get_task_status()根据活动任务状态生成区分NO ACTIVE TASK、STALE POINTER、COMPLETED、PLANNING细分为缺 prd / 缺 design、implement.md / JSONL 未就绪等等分支并给出对应 Next-Actionready收尾提示上下文已加载遵循task-status按需加载 workflow/spec/task 细节。该脚本还有几处值得注意的工程细节Windows 下强制 stdin/stdout/stderr 使用 UTF-8避免中文任务名与 prd 片段触发编码错误支持TRELLIS_HOOKS0/TRELLIS_DISABLE_HOOKS1及一系列*_NON_INTERACTIVE1环境变量跳过注入should_skip_injection通过_detect_platform从环境变量如KIRO_PROJECT_DIR与脚本路径识别当前平台并为 Kiro 直接输出裸文本、为其他平台输出多格式 JSONhookSpecificOutputadditional_context双字段兼容 Cursor 风格。3.3 排障AI 不认识当前任务时先查钩子原文档给出关键排查原则如果用户在新会话中感觉 AI 不认识当前任务第一步是检查平台的 session-start 钩子或等价机制是否已安装并正常运行。在 EcoPaste 中主代理 trellis.json 的agentSpawn钩子即挂载了python3 .kiro/hooks/session-start.py若该钩子未触发则新会话将缺少上述全部注入块。四、workflow-state每个用户回合的轻量提示4.1 机制说明workflow-state 是每个用户回合注入一次的轻量提示。它根据当前任务状态从.trellis/workflow.md中选择对应状态块如no_task、planning、in_progress、completed注入。若用户想改变某状态下 AI 接下来该做什么应先编辑.trellis/workflow.md中对应的状态块——因为注入内容原样取自该文件。4.2 EcoPaste 中的实现inject-workflow-state.py.kiro/hooks/inject-workflow-state.py 通过 Kiro 钩子配置 trellis-workflow-state.kiro.hookpromptSubmit事件触发runCommand在每个用户提示时执行。脚本的解析核心是load_breadcrumbs()用正则_TAG_RE解析workflow.md中的[workflow-state:STATUS]...[/workflow-state:STATUS]标签块状态值支持字母、数字、下划线与连字符如in-review、blocked-by-team。原文档强调workflow.md 是唯一事实来源无回退字典。脚本对此的实现值得注意已知状态workflow.md 中有对应标签→ 注入详细模板正文未知状态或 workflow.md 缺失 → 退化为通用一行Refer to workflow.md for current step.让用户看到并修复损坏状态而不是钩子静默掩盖问题no_task伪状态无活动任务时→ 头部省略任务信息提示 AI 在用户描述真实工作时应引导创建任务Codex 平台特判从.trellis/config.yaml读取codex.dispatch_modeinline/sub-agent决定使用status-inline标签还是status标签并额外输出codex-mode横幅与无任务时的引导通知Gemini CLI 0.40.x 的回合事件名是BeforeAgent其余平台沿用UserPromptSubmit脚本在运行时选择正确的事件名。脚本同时实现了一个健壮的 stdin 读取器用守护线程 0.2 秒超时读取 payloadKiro IDE 的runCommand可能不关闭 stdin直接json.load(sys.stdin)会永久阻塞读取失败或超时则安全降级为{}。五、sub-agent context子代理的任务上下文5.1 两种加载模式Trellis 为 implement / check 等子代理提供两种上下文加载模式hook push钩子推送平台钩子在代理启动前注入 jsonl 引用的文件以及prd.md若存在、design.md若存在、implement.md若存在agent pull代理拉取代理定义指示代理启动后自行读取活动任务、jsonl 上下文与任务产物。两种模式下任务目录中的 JSONL 文件都是 spec/research 上下文的清单manifest。任务产物的读取顺序固定为prd.md→design.md若存在→implement.md若存在。5.2 EcoPaste 中的实现inject-subagent-context.py.kiro/hooks/inject-subagent-context.py 在 EcoPaste 中同时服务三种代理其设计哲学在脚本头注释中写得很明确钩子负责注入全部上下文子代理拿到完整信息后自主工作无需 resume、无需分段行为由代码而非 prompt 控制。它由PreToolUseTask 工具调用前触发各代理的agentSpawn钩子统一挂载该脚本见 trellis-implement.json、trellis-check.json、trellis-research.json。脚本的关键路径上下文来源通过统一的活动任务解析器定位任务目录读取implement.jsonlImplement 代理专用、check.jsonlCheck 代理专用、prd.md、design.md复杂任务、implement.md复杂任务执行计划以及codex-review-output.txtImplement 上下文顺序get_implement_context① implement.jsonl 中引用的全部文件 → ② prd.md需求→ ③ design.md若存在技术设计→ ④ implement.md若存在执行计划每一部分用路径分隔包装Check 上下文get_check_contextcheck.jsonl 条目同样的任务产物顺序get_finish_context复用 check.jsonl prd.md 作为 final checkFinish 阶段的上下文Research 上下文get_research_context不需要任务目录脚本头常量AGENTS_REQUIRE_TASK (AGENT_IMPLEMENT, AGENT_CHECK)明确 implement/check 才要求任务目录只注入.trellis/spec/目录结构的动态树与搜索提示prompt 组装build_implement_prompt/build_check_prompt/build_finish_prompt/build_research_prompt分别把上下文与原始 prompt 拼装成完整指令并带!-- trellis-hook-injected --标记——代理据此判断上下文已由钩子注入直接干活还是注入未触发自行拉取平台输入解析_parse_hook_input兼容 Claude Code / Qoder / CodeBuddy / Droidtool_nameTask|Agent、CursorTask|Subagent、Copilot CLIcamelCasetoolName、Gemini CLItool_name 即代理名、KiroagentSpawn顶层agent_name等多种格式甚至能解析 Cursor protobuf oneof 编码的{custom: {name: ...}}结构输出格式同时输出hookSpecificOutputClaude 系格式含permissionDecision: allow与updatedInput、permissionupdated_inputCursor 格式、updatedInputGemini 格式让各平台各取所需。5.3 Agent pull 侧的回退协议尽管 EcoPaste 使用 hook push 模式代理定义中仍内置了 pull 回退以 trellis-implement.json 为例其 prompt 先检查输入中是否有!-- trellis-hook-injected --标记——标记存在则直接干活标记缺失Windows Claude Code、--continue恢复会话、fork 分发、钩子被禁用等场景则从派发 prompt 首行Active task: path找到任务路径自行读取prd.md、info.md及implement.jsonl中列出的 spec 文件。Check 代理的协议与之对称读check.jsonl。两个代理的 prompt 中还都包含递归守卫禁止再派生子代理避免无限递归。六、JSONL 读取规则6.1 文件格式与种子行implement.jsonl和check.jsonl每行一个 JSON 对象格式如下{file: .trellis/spec/backend/index.md, reason: Backend rules}读取方读者应跳过没有file字段的种子行。在 EcoPaste 的inject-subagent-context.py中这一规则体现在read_jsonl_entries()支持file/path字段与type: directory目录模式按文件名排序读取目录内最多 20 个.md文件max_files: int 20防止超大目录无file字段的行如task.py create写入的自描述种子行{_example: ...}静默跳过若某 jsonl 完全没有任何真实条目则向 stderr 输出 WARN 提示说明子代理将只收到任务产物。session-start.py中还有配套的_has_curated_jsonl_entry()判断一个 jsonl 是否至少包含一条带file字段的已策展条目——只有{_example: ...}种子行的 jsonl 不算就绪该判断同时用于_get_task_status()中 planning 阶段的start 前需策展 JSONL提示。6.2 配置原则只登记 spec/research不预登记将被修改的代码文件原文档明确配置 JSONL 时AI 只应包含 spec/research 文件不要预登记将被修改的代码文件。因为代码文件应由代理在实现过程中自行读取。这一点在 change-context-loading.md 中得到强化Include only spec/research files. Do not put code files that will be modified into these manifests。七、Active Task 与上下文键Context Key7.1 会话隔离的活动任务状态活动任务状态存放在.trellis/.runtime/sessions/按会话隔离。钩子会尝试从平台事件、环境变量、转录路径或TRELLIS_CONTEXT_ID中解析上下文键context key。7.2 上下文键如何进入 shell原文档给出了一个重要排查场景如果 shell 命令看不到同一个上下文键task.py current --source可能报告没有活动任务。此时应检查平台是否把会话身份传入了 shell而不是手工写一个全局的 current-task 文件。在 EcoPaste 的session-start.py中这一场景有专门解决_persist_context_key_for_bash()在解析出 context key 后将其以export TRELLIS_CONTEXT_IDshlex.quote(context_key)追加到CLAUDE_ENV_FILE指向的环境文件中——这样会话启动时钩子 stdin 里的身份能被后续的 Bash 工具如task.py current感知到从而让 shell 命令看到与钩子一致的上下文键。此外run_script()在启动.py子进程时也会通过环境变量TRELLIS_CONTEXT_ID把 context key 传递给get_context.py等脚本。八、本地定制点Local Customization Points原文档的定制点表格是本文最核心的实战索引完整保留如下并补充 EcoPaste 仓库中的实际编辑位置需求编辑位置修改 session-start 注入内容平台的session-start钩子或插件文件EcoPaste 中为 .kiro/hooks/session-start.py修改每回合 workflow-state 规则.trellis/workflow.md中的[workflow-state:STATUS]块。平台 workflow-state 钩子逐字解析这些块不嵌入回退文本EcoPaste 中为 .kiro/hooks/inject-workflow-state.py修改子代理读取上下文的方式平台代理定义、inject-subagent-context钩子或代理 preludeEcoPaste 中为 .kiro/hooks/inject-subagent-context.py 及 .kiro/agents/ 下四个代理文件修改 JSONL 校验/展示.trellis/scripts/common/task_context.py修改活动任务解析.trellis/scripts/common/active_task.py8.1 定制时的双层验证原文档强调修改上下文注入后必须验证两件事新会话能看到正确的任务session-start 注入正常task-status反映真实状态子代理能看到正确的任务产物 / spec / researchjsonl 清单任务产物按序装配。8.2 排障命令序列结合 change-context-loading.md完整的排障顺序如下python3 ./.trellis/scripts/task.py current --source # 确认活动任务与来源 python3 ./.trellis/scripts/task.py list-context task # 查看任务上下文清单 python3 ./.trellis/scripts/task.py validate task # 校验任务与 JSONL python3 ./.trellis/scripts/get_context.py --mode packages # 查看包/规范索引原文档的排障原则是在编辑 hooks/agents 之前先确认任务与 JSONL 是正确的——上下文注入链条的起点是活动任务解析而不是钩子本身。Research 代理 trellis-research.json 的 prompt 也把task.py current --source作为解析当前任务的第一步与主代理 trellis.json 中面包屑缺失或过期时用task.py current --source解析活动任务的约定互相印证。九、注入链路总览与阅读延伸9.1 三种注入的时机与职责注入触发时机内容关键文件EcoPastesession-start会话启动/清空/压缩工作流摘要、任务状态、活跃任务、spec 索引、开发者与 git.kiro/hooks/session-start.pyworkflow-state每个用户回合按状态从 workflow.md 选块.kiro/hooks/inject-workflow-state.py trellis-workflow-state.kiro.hooksub-agent context子代理派发前PreToolUsejsonl 引用文件 prd/design/implement.kiro/hooks/inject-subagent-context.py9.2 相关文档指引想了解注入在整个 Trellis 本地架构中的位置读 overview.md想修改上下文加载行为AI 不认识当前任务代理没读 spec上下文太多/太少读 change-context-loading.md想修改 hooks 本身读 change-hooks.md想修改三个子代理的行为读 change-agents.md。十、总结Trellis 的本地上下文注入系统用三层注入一份 JSONL 清单解决了 AI 会话中的上下文时效问题session-start 在会话起点铺底、workflow-state 在每回合轻量提醒、sub-agent context 在派发前把任务与规范装配齐整而implement.jsonl/check.jsonl作为 spec/research 的清单配合跳过种子行、只登记 spec/research、不预登记待改代码的读取规则构成了一个可按需扩展且不会无限膨胀的上下文模型。在 EcoPaste 仓库中这三条链路分别在 session-start.py、inject-workflow-state.py 与 inject-subagent-context.py 中落地并配齐了 Windows 编码兼容、平台识别、多格式输出、注入失败静默降级等工程细节。掌握本文的注入类型、读取规则与定制点表格你就能独立回答为什么 AI 不知道当前任务并给出正确的修法。赞分享桌面应用【免费下载链接】EcoPaste跨平台的剪贴板管理工具 | Cross-platform clipboard management tool项目地址https://gitcode.com/ayangweb/EcoPaste点击查看免费下载相关推荐Trellis 本地上下文注入系统解析让 AI 在正确时间读取正确文件Trellis 本地上下文注入系统解析让 AI 在正确时间读取正确文件 Trellis 的上下文注入context injection机制旨在让 AI 在桌面应用Trellis 本地上下文注入系统全解析让 AI 在正确的时间读取正确的文件Trellis 本地上下文注入系统全解析让 AI 在正确的时间读取正确的文件导读 Trellis 本地上下文注入Local Context Injecti桌面应用EcoPaste 项目本地化 Trellis 团队约定在 .trellis/spec、本地 Skill 与任务上下文中正确落位EcoPaste 项目本地化 Trellis 团队约定在 .trellis/spec 、本地 Skill 与任务上下文中正确落位本指南基于 EcoPaste桌面应用上一篇分子对接新手速通指南用AutoDock Vina在Mac上完成第一次虚拟筛选实战下一篇微信聊天记录备份实战三步上手免费开源工具 WechatBakTool创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

EcoPaste 项目中的 Trellis 本地上下文注入系统（Local Context Injection）：让 AI 在正确时机读取正确文件的完整指南

相关推荐

基于SpringBoot的非遗项目推广系统设计与实现(源码+lw+部署文档+讲解等)

BrowserSkill bsk 快速上手：3 种拍法截稳 10 万像素高长页面

Xberg Go 绑定中的 Post-Processor 清理：ClearPostProcessors 用法与插件注册表生命周期解析

更多资讯

Flask实战：构建在线云音乐系统从零到部署完整指南

IPC-A-600M PCB验收标准实战指南：从孔壁空洞到切片检测

Flask构建在线云音乐系统：核心设计与踩坑指南

创业公司股权激励怎么算价值？期权、行权价与回购条款避坑指南

Windows下高效处理XML：xmlstarlet命令行工具实战指南

context-mode 上下文管理：从原理到实战的工程实践指南

今日更新

Multisim仿真NE555 PWM控制器：从搭电路到调占空比全流程

S32K312 AUTOSAR BSW开发实战：从配置踩坑到烧录交付

双目视觉三维人脸重建：从视差图到点云粗配准全流程解析

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？