Trellis 被 opencode 加载的机制

先来讲一讲AGENT.MD文档AGENTS.md 文件的作用AGENTS.md 是 opencode 的项目级自定义指令文件用于告诉 LLM 如何理解和操作当前项目。一、核心用途AGENTS.md├── 项目结构说明 → packages/ infra/ 等目录职责├── 构建/测试命令 → npm run build / npm test├── 编码规范 → 命名风格、import 规则、错误处理约定├── 架构约定 → 依赖方向、分层规则├── 项目特定的注意事项 → 部署流程、环境变量、常见陷阱└── 参考其他指令文件 → docs/guidelines.md通过 Read 工具按需加载二、查找顺序优先级① 从当前目录向上遍历找到的第一个 AGENTS.md ← 项目级② ~/.config/opencode/AGENTS.md ← 全局规则③ ~/.claude/CLAUDE.mdAGENTS.md 不存在时回退 ← Claude Code 兼容同时存在 AGENTS.md 和 CLAUDE.md 时只使用 AGENTS.md。三、典型内容示例# 项目规则## 技术栈- Spring Boot 2.7 MyBatis-Plus RocketMQ- 构建命令: mvn clean install -DskipTests- 测试命令: mvn test## 项目结构- gateway/ → Spring Cloud Gateway统一入口- ticket/ → 票务订单服务- admin/ → 管理后台## 编码规范- Controller 统一返回 Response 对象- 所有 API 使用 ApiMapping 注解- 异常使用 ServiceException 抛出## 重要约定- 不要直接修改网关层的 ModifyResponseFilter- 景区配置通过管理后台维护不要硬编码四、生成方式opencode 推荐的 /init 命令会扫描项目中的关键文件提取构建命令、测试框架、架构结构等信息自动生成或更新 AGENTS.md五、与 opencode/agents/name.md 的区别简而言之AGENTS.md 是告诉 LLM 你的项目是什么agent/name.md 是告诉 LLM 某个角色应该做什么。Trellis 被 opencode 加载的机制Trellis 不是一个 MCP 服务或 plugin而是通过 AGENTS.md 声明 Skill 注入的方式整合到 opencode 中的。先来看下agent.md 中注入的Trellis加载内容Trellis 指令块解释AGENT.MD 内容对以上内容进行逐行翻译 !-- TRELLIS:START --Trellis 自动生成的标记块开始。opencode/LLM 将此块作为 AGENTS.md 的一部分加载到 context 中。# Trellis Instructions These instructions are for AI assistants working in this project.声明本块内容的受众是 AI 助手即 opencode LLM而非人类开发者。This project is managed by Trellis. The working knowledge you need lives under .trellis/:核心声明项目的开发工作流由 Trellis 管理。LLM 所需的全部上下文知识存放在 .trellis/ 目录下。- .trellis/workflow.md — development phases, when to create tasks, skill routing告诉 LLM 去读这个文件了解开发分几个阶段、什么时候创建任务、以及如何路由到不同的 skill。- .trellis/spec/ — package- and layer-scoped coding guidelines (read before writing code in a given layer)编码规范目录。LLM 被要求在写某层的代码之前先读对应的 spec避免违反项目约定。- .trellis/workspace/ — per-developer journals and session traces开发者工作日志和会话记录。LLM 可以从中了解之前做过什么、遇到了什么问题以及决策历史。- .trellis/tasks/ — active and archived tasks (PRDs, research, jsonl context)任务目录。当前活跃任务的 PRD需求文档、实现步骤 (jsonl)、检查清单等都在这里。LLM 通过读取这里来确定当前要做什么。If a Trellis command is available on your platform (e.g. /trellis:finish-work, /trellis:continue), prefer it over manual steps. Not every platform exposes every command.如果当前工具支持 Trellis 命令如 /trellis:finish-work优先使用这些命令而不是手动执行脚本。例如在 opencode 中这些命令通常通过 custom command 机制注册。If youre using Codex or another agent-capable tool, additional project-scoped helpers may live in: - .agents/skills/ — reusable Trellis skills - .codex/agents/ — optional custom subagents针对 Codex 等其他 agent 平台的兼容说明。提示可能还有额外的 skill 和 agent 文件可以加载。Managed by Trellis. Edits outside this block are preserved; edits inside may be overwritten by a future trellis update.版本管理提醒 这个 !-- TRELLIS:START -- 与 !-- TRELLIS:END -- 之间的内容由 Trellis 工具自动管理 如果将来运行 trellis update块内的内容可能被覆盖 如果需要在 AGENTS.md 中加其他项目说明写在块外面不会被覆盖!-- TRELLIS:END --标记块结束。加载链路opencode 启动 │ ├── ① 读取 AGENTS.md项目根目录 │ 内容开头声明: │ This project is managed by Trellis. The working knowledge │ you need lives under .trellis/: │ ├── ② AGENTS.md 告诉 LLM: │ - .trellis/workflow.md → 开发流程 │ - .trellis/spec/ → 编码规范 │ - .trellis/tasks/ → 当前任务 │ - .trellis/workspace/ → 开发者日志 │ ├── ③ LLM 在需要时按 AGENTS.md 的指示 │ 通过 Read 工具读取 .trellis/ 下的文件 │ ├── ④ .trellis/scripts/ 中的 Python 脚本 │ 被 bash 工具调用管理任务生命周期: │ - task.py create/start/finish/archive │ - add_session.py 记录会话日志 │ - get_context.py 获取包/层信息 │ └── ⑤ 如果环境中注册了 Trellis 命令 如 /trellis:finish-work优先使用命令数据流AGENTS.md声明项目由 Trellis 管理 │ ▼ opencode LLM 读取 AGENTS.md 后知道要这样做: │ ├── 看 workflow.md → 知道开发分几个阶段 ├── 看 spec/index.md → 知道各层代码规范 ├── 看 tasks/current → 知道当前要做什么任务 └── 看 task/name/prd.md → 知道任务具体需求 │ ▼ LLM 按规范编码完成任务后调用 task.py 更新状态Trellis 目录结构.trellis/ ├── config.yaml ← 配置session 自动提交、hooks、packages ├── workflow.md ← 开发工作流说明书690 行含 Plan Phase / Code Phase 等 ├── spec/ ← 编码规范按包和层级组织 │ └── package/layer/index.md ├── tasks/ ← 任务目录每个任务一个子目录 │ └── name/prd.md, implement.jsonl, task.json ├── workspace/ ← 每个开发者的会话日志 │ └── name/journal-*.md └── scripts/ ← Python 工具脚本 ├── task.py ← 任务生命周期管理 ├── add_session.py ← 记录会话 ├── get_context.py ← 获取包/层上下文 └── init_developer.py ← 初始化开发者身份核心Trellis 没有特殊的加载机制它只是通过AGENTS.md中的一段声明文本告诉 LLM 去读.trellis/下的文件来获取上下文。LLM 在需要时会自主使用 Read 工具读取这些文件。加载到 opencode 的简要流程辛苦您看到文章最后送一份学习网站给您吧。Trellis 教程https://docs.trytrellis.app/zh/start/how-it-works