EcoPaste 项目实战：Trellis 本地上下文加载机制定制指南

桌面应用【免费下载链接】EcoPaste跨平台的剪贴板管理工具 | Cross-platform clipboard management tool项目地址https://gitcode.com/ayangweb/EcoPaste点击查看免费下载导读本文聚焦于 EcoPaste 仓库中 Trellis 工作流系统的**本地上下文加载Local Context Loading**机制它决定了 AI 代理在何时、以何种方式读取 workflow、任务、规格说明spec、研究资料、工作区记录与 git 状态。当出现“AI 不知道当前任务”“代理没有读取 spec”“上下文太多或太少”等典型问题时都需要回到这套机制进行排查与定制。读完本文你将掌握.trellis/目录的上下文数据源结构、implement.jsonl/check.jsonl两个关键清单的编写与校验规则以及如何通过 Python 脚本与 OpenCode 插件按需调整会话上下文、子代理上下文和每条用户消息的 workflow 提示。说明本仓库是跨平台剪贴板管理工具 EcoPasteTauri v2 Rust-First 架构Trellis 是仓库中用于管理 AI 编码工作流的本地系统本文只讨论该系统中“上下文加载”相关部分不涉及剪贴板业务功能本身。上下文加载先弄清它何时发生Trellis 本地上下文加载说明 对“上下文加载”的定义是决定 AI 在何时读取 workflow、任务、spec、研究、工作区与 git 状态。它不是一个一次性动作而是分布在多个时机新会话开始时主会话第一次收到用户消息时注入项目级上下文每次用户输入时为每轮对话注入 workflow 状态面包屑派发子代理时实现/检查代理被调用前把任务清单、spec、研究文件注入其提示词排障时通过 CLI 脚本快速核对当前任务与清单是否就绪。仓库中与之对应的实现有三层层级位置作用数据源.trellis/workflow.md、.trellis/spec/、.trellis/tasks/task/、.trellis/workspace/提供上下文内容Python 脚本.trellis/scripts/common/session_context.py、.trellis/scripts/common/task_context.py、.trellis/scripts/common/active_task.py生成上下文文本、维护 JSONL 清单OpenCode 插件.opencode/plugins/session-start.js、.opencode/plugins/inject-workflow-state.js、.opencode/plugins/inject-subagent-context.js在具体时机把上下文注入对话上下文来源一览在动手定制之前先明确 Trellis 能从哪些地方取上下文。下表是 change-context-loading.md 给出的权威清单来源用途.trellis/workflow.md工作流定义与下一步动作提示.trellis/tasks/task/prd.md当前任务的 PRD需求文档.trellis/tasks/task/design.md复杂任务的技术设计.trellis/tasks/task/implement.md复杂任务的执行计划.trellis/tasks/task/implement.jsonl实现前需要读取的 spec/研究清单.trellis/tasks/task/check.jsonl检查阶段需要读取的 spec/研究清单.trellis/spec/项目规格说明按包/分层组织.trellis/workspace/会话记录与开发者日志git status当前工作树变更仓库中这些目录实际存在且结构完整.trellis/spec/下按backend/、frontend/、guides/分层backend/内含architecture.md、clipboard-pipeline.md等规格.trellis/workspace/ayangweb/下有journal-1.md会话日志.trellis/workflow.md内含各阶段的[workflow-state:STATUS]提示块。这些数据源就是后续所有注入动作的原料。核心接口implement.jsonl 与 check.jsonl格式与写法change-context-loading.md 明确implement.jsonl/check.jsonl是上下文加载的关键接口。每一行是一条 JSON 记录{file: .trellis/spec/backend/index.md, reason: Backend conventions} {file: .trellis/tasks/04-28-x/research/api.md, reason: API research}字段语义字段说明file相对仓库根目录的 spec / 研究文件路径必需type可选为directory时表示条目指向目录路径需以/结尾缺省为filereason该文件被注入的原因说明供后续人工排查阅读硬性约束清单中只能包含 spec / 研究文件不要放入将被修改的代码文件——实现代码文件由代理在实现阶段自行读取否则会造成上下文冗余和事实失真。校验与维护命令清单由 .trellis/scripts/common/task_context.py 维护支持三条子命令由 .trellis/scripts/task.py 暴露# 显示当前任务及其来源 python3 ./.trellis/scripts/task.py current --source # 列出指定任务的 JSONL 清单条目含 reason python3 ./.trellis/scripts/task.py list-context task # 校验 JSONL 清单检查文件/目录是否真实存在、JSON 是否合法 python3 ./.trellis/scripts/task.py validate task从源码看task_context.py 中cmd_add_context支持一条快捷添加命令python3 task.py add-context dir file path [reason]会自动补全.jsonl后缀、根据路径是文件还是目录设置type并做重复条目去重_validate_jsonl会逐行解析 JSON跳过无file字段的种子行_example自描述行对真实条目检查file指向的文件或目录是否存在。按 workflow.md 中的 ready gate 约定在task.py start之前implement.jsonl与check.jsonl必须各包含至少一条真实的{file: ..., reason: ...}记录仅种子行不算就绪。种子机制与规划期维护需要留意清单文件并非手工从零创建。task_context.py 的模块注释说明cmd_init_context在 v0.5.0-beta.12 已被移除implement.jsonl/check.jsonl现在由task.py create在创建任务时以一行自描述_example种子行预置之后在规划阶段Phase 1由 AI 代理把真实条目补充进去。workflow.md 的[workflow-state:planning]块同样要求规划期即为子代理准备好两份 spec/research 清单。修改会话上下文让每个新会话看到更多项目状态如果希望每个新会话都能自动看到更多项目状态按文档指引编辑两处.trellis/scripts/common/session_context.py生成上下文文本对应平台的session-start钩子注入时机。从源码看session_context.py的get_context_text()会按固定节组装上下文## DEVELOPER、## GIT STATUS含分支、干净度、未提交变更列表、最近 5 条提交、## CURRENT TASK路径、来源、任务名、状态若存在prd.md会给出[!] This task has prd.md - read it for task details提示、## ACTIVE TASKS含层级树与进度、## MY TASKS、## JOURNAL FILE含行数与 2000 行上限告警、## PATHS等。仓库中的 .opencode/plugins/session-start.js 则通过chat.message钩子在会话第一条用户消息的文本部件前插入buildSessionContext()生成的上下文并且做了幂等保护同一会话只注入一次子代理轮次、非交互模式、TRELLIS_HOOKS0/TRELLIS_DISABLE_HOOKS1环境变量都会跳过注入。关键设计原则上下文不能无界增长。文档建议优先注入索引与路径让 AI 按需读取详细文件而不是把所有内容一次性塞进提示词——这与session_context.py中“给出行数与路径、提示代理去读 prd.md”的做法完全一致。修改子代理上下文hook 推入 与 agent 拉取子代理implement / check / research的上下文注入有两种模式定制前必须先确定当前平台用的是哪一种hook 推入hook push编辑 .opencode/plugins/inject-subagent-context.js 中对应的上下文构建逻辑。agent 拉取agent pull编辑 .opencode/agents/trellis-implement.md / .opencode/agents/trellis-check.md 的读取步骤。本仓库同时具备两种实现。inject-subagent-context.js通过 OpenCode 的tool.execute.before钩子在task工具被调用时按subagent_type注入上下文implement 代理读implement.jsonlprd.mdinfo.mdcheck 代理读check.jsonlprd.mdfinish 阶段复用 check 上下文research 代理则注入.trellis/spec/目录结构与检索提示。注入后的提示词以!-- trellis-hook-injected --标记开头作为“已自动加载”信号。而trellis-implement.md中有一套备用协议如果输入中不存在!-- trellis-hook-injected --标记说明 hook 注入未生效例如 Windows Claude Code、--continue续跑、fork 分发、hooks 被禁用等场景代理需要从派发提示首行的Active task: path读取活动任务路径或回退执行python3 ./.trellis/scripts/task.py current --source然后依次读取task/implement.jsonl及其列出的每个文件、prd.md、design.md若存在、implement.md若存在。无论哪种模式文档要求子代理最终都必须读到六样东西活动任务active task对应的 JSONL 清单JSONL 引用的 spec / research 文件prd.mddesign.md若存在implement.md若存在修改每次用户输入的提示workflow-state 面包屑如果希望每轮对话都出现当前工作流阶段提示编辑点是.trellis/workflow.md中的[workflow-state:STATUS]块。仓库里的 .opencode/plugins/inject-workflow-state.js 是纯解析器它用正则提取[workflow-state:STATUS]...[/workflow-state:STATUS]块原文拼成workflow-state面包屑插入每条用户消息逐字读取、不做任何改写。其注释明确.trellis/workflow.md是唯一真相源插件没有后备表当 workflow.md 缺失或状态标签不存在时面包屑降级为通用提示 “Refer to workflow.md for current step.”让用户看到并修复问题而不是被插件静默掩盖。仓库 workflow.md 中实际定义了多个状态块例如[workflow-state:no_task]、[workflow-state:planning]、[workflow-state:planning-inline]、[workflow-state:in_progress]、[workflow-state:in_progress-inline]、[workflow-state:completed]分别对应无任务、规划阶段、Codex 内联规划变体、执行阶段、Codex 内联执行变体与完成状态。如果你修改了某个状态块还要同步检查.trellis/spec/中对应的工作流状态契约说明保持两边一致。活动任务丢失active_task.py 与会话身份传播当出现“AI 不知道当前任务”且排查到是活动任务指针丢失时编辑点是 .trellis/scripts/common/active_task.py 与平台的会话身份传播逻辑。active_task.py负责解析“当前任务”的来源与上下文键resolve_context_keysession_context.py中get_current_task/get_current_task_source会把任务路径、来源类型与上下文键写进会话上下文inject-subagent-context.js则在派发子代理时按优先级解析任务① 会话运行时上下文中精确匹配current_task→ ② 派发提示里的Active task:显式覆盖 → ③ 仅当本地恰好只有一个会话时启用单会话回退。多窗口用户正是通过每条派发提示首行的Active task: path来消除歧义。排障顺序先验证再动手改文档给出了一套明确的排障顺序强调在修改任何钩子/代理之前先确认任务与 JSONL 是正确的# 1. 确认活动任务及其来源 python3 ./.trellis/scripts/task.py current --source # 2. 查看该任务的上下文清单 python3 ./.trellis/scripts/task.py list-context task # 3. 校验清单完整性文件存在性、JSON 合法性 python3 ./.trellis/scripts/task.py validate task # 4. 查看聚合后的会话上下文--mode packages 按包聚合 python3 ./.trellis/scripts/get_context.py --mode packages其中get_context.py在仓库中实现为 .trellis/scripts/get_context.py它把参数转发给.trellis/scripts/common/git_context.py的main()change-context-loading.md 原文为python3 ./.trellis/scripts/get_context.py --mode packages。对照文档的“Common Needs And Edit Points”表把症状映射到编辑点症状编辑点新会话想注入更多/更少信息session_context.py或平台session-start钩子每次用户输入要改提示.trellis/workflow.md的[workflow-state:STATUS]块inject-workflow-state钩子只做解析、逐字读取代理没有读 spec任务 JSONL、agent prelude、inject-subagent-context钩子活动任务丢失active_task.py与平台会话身份传播修改 JSONL 校验规则task_context.py定制清单速查想改新会话注入内容编辑 .trellis/scripts/common/session_context.py .opencode/plugins/session-start.js。想改每轮提示编辑 .trellis/workflow.md 的[workflow-state:STATUS]块插件 inject-workflow-state.js 会逐字注入。想改子代理上下文hook 推入模式改 inject-subagent-context.jsagent 拉取模式改 trellis-implement.md / trellis-check.md 的读取步骤。想改 JSONL 规则编辑 .trellis/scripts/common/task_context.py。先排查再动手依次运行task.py current --source→task.py list-context task→task.py validate task→get_context.py --mode packages确认无误后再进入上述编辑。这套机制的核心思想可以总结为一句Trellis 用“单一真相源 按需读取”控制上下文成本——workflow.md是状态唯一真相源JSONL 清单是子代理读取范围的显式契约注入器Python 脚本与 OpenCode 插件只负责在正确时机把索引、路径与提示交给 AI让 AI 按需深入文件避免上下文无限膨胀。赞分享桌面应用【免费下载链接】EcoPaste跨平台的剪贴板管理工具 | Cross-platform clipboard management tool项目地址https://gitcode.com/ayangweb/EcoPaste点击查看免费下载相关推荐EcoPaste 中的 Trellis 本地上下文注入系统架构、实现机制与定制指南EcoPaste 中的 Trellis 本地上下文注入系统架构、实现机制与定制指南 本指南以 context injection.md https://lin桌面应用EcoPaste 项目本地约定定制指南基于 Trellis 的 .trellis/spec 与本地 Skill 落地实践EcoPaste 项目本地约定定制指南基于 Trellis 的 .trellis/spec 与本地 Skill 落地实践 Trellis 是 EcoPaste桌面应用EcoPaste 中的 Trellis 本地上下文加载定制诊断AI 不知道当前任务并控制上下文注入的完整指南EcoPaste 中的 Trellis 本地上下文加载定制诊断AI 不知道当前任务并控制上下文注入的完整指南 本指南聚焦 Trellis AI 工作流系统桌面应用上一篇FastLED量子纠缠超距LED同步的理论实现下一篇重新定义数字手写为什么Saber是你需要的手写笔记应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考