深入解析 Trellis 本地架构:项目内三层系统模型与 AI 定制入口(EcoPaste 实战视角)

发布时间:2026/11/15 21:55:31

深入解析 Trellis 本地架构:项目内三层系统模型与 AI 定制入口(EcoPaste 实战视角) 桌面应用【免费下载链接】EcoPaste跨平台的剪贴板管理工具 | Cross-platform clipboard management tool项目地址https://gitcode.com/ayangweb/EcoPaste点击查看免费下载导读Trellis 是一套运行在用户项目内部的 AI 协作编排系统它的核心不在 CLI 源码里而在trellis init生成、位于项目根目录下的.trellis/目录以及各 AI 平台目录之中。本文基于.agents/skills/trellis-meta/references/local-architecture/overview.md及其配套参考文档完整拆解这套项目本地优先的分层架构——工作流层、持久化层、平台集成层逐项说明每个核心路径的作用与可编辑边界并总结 AI 定制时必须遵守的五条原则。读完你将掌握如何在不触碰 Trellis CLI 源码的前提下读懂并安全地修改当前项目如 EcoPaste 仓库中已生成的 Trellis 文件让工作流、任务、规范与记忆真正为你所用。一、本地优先Trellis 的默认操作模型trellis-meta技能专门面向已经执行过trellis init的用户项目。这类项目的机器上通常只有 npm 安装的trellis命令加上项目内生成的 Trellis 文件未必包含 Trellis CLI 源码。因此当 AI 使用该技能时默认的定制目标永远是用户项目内的本地文件.trellis/工作流、任务、规范spec、记忆memory、脚本与运行时状态平台目录.claude/、.codex/、.cursor/、.opencode/、.kiro/、.gemini/、.qoder/、.codebuddy/、.github/、.factory/、.pi/、.kilocode/、.agent/、.devin/、.reasonix/、.zcode/等 AI 工具各自的配置目录共享技能层.agents/skills/。默认情况下不要引导用户 fork Trellis CLI 仓库。只有用户明确表示想修改 Trellis 上游源码、发布 npm 包或提交 PR 时才把上游源码当作操作对象。这一边界在 EcoPaste 仓库中可以直接印证项目根目录下确实生成了.trellis/含workflow.md、config.yaml、spec/、tasks/、workspace/、scripts/、agents/等与.agents/skills/含trellis-meta、trellis-before-dev、trellis-channel等一批技能这些就是本文讨论的全部操作面。二、本地系统模型项目内的三层架构Trellis 在一个用户项目内部提供三层结构三层全部位于项目目录内因此 AI 可以直接读取并修改它们层级位置职责工作流层Workflow layer.trellis/workflow.md定义阶段Phase、路由Routing、下一步动作Next Actions与提示块Prompt Blocks持久化层Persistence layer.trellis/tasks/、.trellis/spec/、.trellis/workspace/存放任务、规范与跨会话记忆平台集成层Platform integration layer各平台目录中的 hooks、settings、agents、skills、commands、prompts、workflows把 Trellis 工作流桥接到不同的 AI 工具这套三层都在项目内的模型是后续所有定制动作的前提正因为三层都在项目目录里AI 无需拥有 Trellis 源码也能理解当前项目该如何推进任务并能直接进行本地化修改。三、核心路径一览每个文件干什么、能不能动overview.md 给出了初始化后 Trellis 目录内的核心路径清单这是理解整个系统的地图路径作用.trellis/workflow.md工作流阶段、技能路由以及工作流状态提示块.trellis/config.yaml项目配置、任务生命周期钩子、monorepo 包配置、日志journal配置.trellis/spec/用户项目特有的编码规范与思考指南.trellis/tasks/每个任务的 PRD、技术笔记、研究文件与 JSONL 上下文.trellis/workspace/按开发者划分的日志与跨会话记忆.trellis/scripts/命令、钩子与上下文注入所用的本地 Python 运行时.trellis/.runtime/会话级运行时状态例如当前任务指针.trellis/.template-hashes.jsonTrellis 托管文件的模板哈希供trellis update判断本地文件是否被用户改过在 EcoPaste 仓库中这套路径与文档描述完全一致.trellis/config.yaml、.trellis/workflow.md存在.trellis/spec/下按backend/、frontend/、guides/分层组织且每层都有index.md入口.trellis/tasks/内按2026-06/、2026-07/月份归档任务每个任务目录含prd.md、task.json、check.jsonl、implement.jsonl等文件.trellis/workspace/下按开发者ayangweb/划分包含index.md与journal-1.md.trellis/agents/提供了check.md、implement.md两个内置运行时 Agent 定义。这套真实目录结构与 overview.md 描述一一对应可作为读者对照排查的实例。3.1 各路径的可编辑边界配套的 generated-files.md 进一步明确了能不能动路径通常可编辑备注.trellis/workflow.md是本地工作流文档与 AI 路由规则.trellis/config.yaml是项目配置、hooks、packages、日志行数限制等.trellis/spec/是项目规范应被用户和 AI 定期更新.trellis/tasks/是任务素材与研究产物由任务工作流维护.trellis/workspace/是会话记录通常由add_session.py写入.trellis/scripts/谨慎本地运行时可定制但必须先理解调用链.trellis/.runtime/否运行时状态通常由 hooks/scripts 自动写入.trellis/.developer谨慎当前开发者身份.trellis/.version否Trellis 版本记录供 update/migration 逻辑使用.trellis/.template-hashes.json否模板哈希记录不要在这里手写业务规则3.2 模板哈希的三种情形.trellis/.template-hashes.json记录了 Trellis 上次写入模板文件时的内容哈希trellis update借此区分三种情况并决定行为情形更新行为文件未被用户修改可自动更新文件被用户修改提示用户选择覆盖、保留或生成.new旁侧文件文件已不再是当前模板按迁移规则决定删除、改名或保留AI 在定制本地文件时无需手动维护哈希——被 Trellis 识别为用户已修改是正常现象。对应到 EcoPaste 仓库.trellis/spec/中由trellis update刷新的文件一旦被本地编辑就会在哈希记录中以modified by user冲突的形式体现。四、AI 定制五原则改什么、怎么改才安全overview.md 给出了五条必须遵守的定制原则它们是所有本地修改动作的底线先找本地真相源source of truth不要凭记忆修改。先读.trellis/workflow.md、.trellis/config.yaml、相关平台目录及相关任务文件。改用户项目而不是 npm 包缓存修改项目内生成的文件不要改node_modules或全局 npm 安装目录。让平台文件与.trellis/保持一致如果工作流路由变了同时检查平台技能或命令是否还在描述旧流程。项目专属规则放进.trellis/spec/或本地技能不要把团队约定写进trellis-meta这类公开捆绑技能trellis update会覆盖捆绑技能目录内的任何内容。保留用户改动如果文件已被本地修改基于当前内容继续工作而不是用默认模板覆盖它。4.1 默认可编辑与默认不可编辑默认可编辑.trellis/workflow.md、.trellis/config.yaml、.trellis/spec/**、.trellis/scripts/**以及各平台 hooks/settings/agents/skills/commands/prompts/workflows。默认不可编辑全局 npm 安装目录、node_modules/mindfoldhq/trellis、Trellis GitHub 仓库源码、.trellis/.runtime/**下的具体状态文件、.trellis/.template-hashes.json中的哈希内容。只有用户明确想向上游贡献时才切换到 CLI 源码视角。五、如何阅读与使用本目录进入各子系统overview.md 最后给出了按需深入各子系统的入口配合 EcoPaste 仓库中的实际文件可逐一对照你的目标先读的文档对应本地实现本仓库了解 init 后生成了哪些文件generated-files.md.trellis/目录结构修改阶段、路由或下一步动作workflow.md.trellis/workflow.md修改任务模型、JSONL 上下文或活动任务行为task-system.md.trellis/tasks/、.trellis/scripts/task.py修改编码规范注入spec-system.md.trellis/spec/、.trellis/scripts/get_context.py理解日志与跨会话记忆workspace-memory.md.trellis/workspace/、.trellis/scripts/add_session.py修改 hooks 或子 Agent 上下文加载context-injection.md.trellis/scripts/、平台 hooks六、源码级纵深四个子系统的本地实现下面把 overview.md 的三层模型展开到各子系统的实现细节全部以 EcoPaste 仓库中实际存在的文件为证据。6.1 工作流层.trellis/workflow.md的三重职责.trellis/workflow.md是项目内工作流的语义中心负责三件事解释阶段Plan → Execute → Finish 三阶段、定义技能路由有子 Agent 能力的平台默认派发trellis-implement/trellis-check无子 Agent 的平台由主会话直接读trellis-before-dev等技能后执行、提供工作流状态提示块。文件底部可以挂[workflow-state:no_task]这类状态块由 hooks 根据当前任务状态挑选并注入会话。常见状态块含义no_task当前会话无活动任务、planning任务仍在需求/研究/上下文配置、in_progress已进入实现与检查、completed完成待收尾或归档。若要改变无任务时是否建任务何时可跳过建任务是否强制子 Agent等策略应优先编辑这些状态块及其上方的路由表改完后让 AI 重读workflow.md而不是沿用旧会话的流程记忆。阶段中的编号步骤如1.3 Configure context只是供人和 AI 阅读的工作流结构不是task.json的运行时字段。6.2 持久化层之任务系统.trellis/tasks/每个任务是一个目录标准结构为task.json状态、负责人、优先级、分支、父子任务等元数据、prd.md需求与验收标准、design.md复杂任务的技术设计、implement.md执行计划有序清单、验证命令、评审关口、回滚点、implement.jsonl/check.jsonl实现/检查 Agent 必须先读的 spec/research 文件清单、research/研究产物复杂结论不能只留在聊天里。父子任务树用于组织可独立交付的工作父任务拥有源需求、子任务地图与跨子任务验收标准子任务可独立走完规划—实现—检查—归档。父子关系不是依赖调度器依赖应写在子任务的prd.md/implement.md中。常用命令在项目根目录下执行python3 ./.trellis/scripts/task.py create child title --slug child-slug --parent parent-dir python3 ./.trellis/scripts/task.py add-subtask parent-dir child-dir python3 ./.trellis/scripts/task.py remove-subtask parent-dir child-dir python3 ./.trellis/scripts/task.py start task python3 ./.trellis/scripts/task.py current --source python3 ./.trellis/scripts/task.py add-context task implement file reason python3 ./.trellis/scripts/task.py validate task python3 ./.trellis/scripts/task.py finish python3 ./.trellis/scripts/task.py archive task活动任务按会话隔离存储在.trellis/.runtime/sessions/context-key.json不同 AI 窗口可以指向不同任务而互不覆盖若平台或 shell 环境没有稳定会话身份task.py start可能无法设置活动任务此时应检查平台 hook/会话环境而不是回退到一个共享的全局指针。JSONL 上下文格式为每行一个 JSON 对象如{file: .trellis/spec/backend/index.md, reason: Backend conventions}。规则包括只包含 spec/research 文件不预注册即将被修改的代码文件种子行没有file字段只提示 AI 填写真实条目。implement.jsonl不替代implement.md——后者是给人读的执行计划。EcoPaste 仓库的.trellis/tasks/archive/2026-06/与2026-07/中每个任务目录都同时包含prd.md、task.json与implement.jsonl/check.jsonl正是这套模型的直接产物。6.3 持久化层之规范系统.trellis/spec/与 config 包配置.trellis/spec/是项目专属工程规范库单仓库常见结构为backend/、frontend/、guides/分层monorepo 则按package/layer组织每层以index.md作为入口列出 Pre-Development Checklist 与 Quality Check具体细则放在同目录的其它 Markdown 中。EcoPaste 仓库的.trellis/spec/正是如此backend/含architecture.md、clipboard-pipeline.md、commands-and-events.md等frontend/含component-guidelines.md、hook-guidelines.md、state-management.md等guides/含跨层思考指南。.trellis/config.yaml可通过packages/default_package声明 monorepo 包映射packages: cli: path: packages/cli docs-site: path: docs-site type: submodule default_package: cli然后用python3 ./.trellis/scripts/get_context.py --mode packages列出包与规范层作为配置上下文 JSONL 的参照。规范应包含的是可执行的工程约定而非通用最佳实践文件应该放哪、错误处理怎么写、API/hooks/命令的输入输出契约、被禁止的模式、必须写测试的场景、项目特有坑。AI 在实现或调试中学到新规则时应写回.trellis/spec/而不是只总结在聊天里。6.4 持久化层之记忆系统.trellis/workspace/.trellis/workspace/存的是刻意撰写的开发者日志结构为index.mddeveloper/index.mddeveloper/journal-N.md每份日志默认约 2000 行后轮转到下一个文件。首次使用执行python3 ./.trellis/scripts/init_developer.py name创建.trellis/.developer与对应工作区目录记录会话用python3 ./.trellis/scripts/add_session.py \ --title Session title \ --summary What changed \ --commit abc1234无提交的规划/评审工作可用--no-commit或空 commit 值。关键区别是任务相关信息进.trellis/tasks/本次会话发生的事进 workspace 日志未来每次写代码都要遵守的规则进 spec。注意原始的跨会话对话不存这里而是留在磁盘上的~/.claude/projects/、~/.codex/sessions/、~/.pi/agent/sessions/中通过trellis mem search|extract|context按--phase brainstorm|implement|all切片恢复且绝不上传任何内容。日志行数上限与自动提交消息分别由config.yaml的max_journal_lines与session_commit_message控制。6.5 平台集成层上下文注入与多 Agent 通道上下文注入的目标是让 AI 在对的时间读对的文件而不是依赖模型记忆。注入类型包括会话上下文.trellis/scripts/get_context.py、工作流上下文workflow.md、规范上下文spec 任务 JSONL、任务上下文任务目录产物与平台上下文。三种机制session-start会话开始时注入 Trellis 概览、workflow-state每轮对话按状态注入轻量提示、子 Agent 上下文hook push 或 agent pull 两种模式任务产物按prd.md→design.md如有→implement.md如有顺序读取。若新会话里 AI 不认识当前任务优先检查平台的 session-start hook 是否安装并在运行。多 Agent 通道trellis channel是本地协作运行时跨越三个本地表面~/.trellis/channels/project/channel/events.jsonl事件日志追加式、序列加锁、可重放项目桶名由项目绝对路径脱敏而来可用TRELLIS_CHANNEL_ROOT/TRELLIS_CHANNEL_PROJECT覆盖、.trellis/agents/{check,implement}.md平台无关角色卡、.trellis/config.yaml的channel.*配置块worker 空闲超时channel.worker_guard.idle_timeout、存活 worker 预算channel.worker_guard.max_live_workers内置默认分别为5m与6优先级为 CLI flag 环境变量 config.yaml 内置默认。使用条件需要两个以上 Agent 多轮对话、worker 需以对等进程运行、对话需持久可查、多 worker 需共享事件日志。一个易混淆的边界编辑.claude/agents/trellis-implement.md等平台子 Agent 文件不会改变通道 worker 行为——通道 worker 只加载.trellis/agents/name.md。七、结语把定制锚定在项目本地Trellis 的设计哲学很明确项目内的.trellis/是权威真相平台目录是桥接上游源码不是默认目标。对 EcoPaste 这样的真实仓库而言意味着所有日常定制都应落在.trellis/workflow.md、.trellis/config.yaml、.trellis/spec/、.trellis/tasks/、.trellis/workspace/及对应平台目录上要尊重trellis update的哈希判定机制用.new旁侧文件而非破坏性覆盖来保留用户修改要把团队专属规则写进项目本地而不是任何公开捆绑技能。按 overview.md 的五条原则与核心路径表操作你就能在不依赖 CLI 源码的前提下安全、精准地重塑项目内的 AI 工作流。赞分享桌面应用【免费下载链接】EcoPaste跨平台的剪贴板管理工具 | Cross-platform clipboard management tool项目地址https://gitcode.com/ayangweb/EcoPaste点击查看免费下载相关推荐EcoPaste 仓库内 Trellis 本地任务系统Local Task System架构与实战指南EcoPaste 仓库内 Trellis 本地任务系统Local Task System架构与实战指南 本篇技术指南以 .agents/skills/tre桌面应用EcoPaste 项目中的 Trellis 本地工作流系统.trellis/workflow.md 的阶段模型、技能路由与状态注入EcoPaste 项目中的 Trellis 本地工作流系统.trellis/workflow.md 的阶段模型、技能路由与状态注入 导读本文以仓库内 .ag桌面应用Quickemu 快速指南两条命令创建并启动 macOS、Windows、Linux 虚拟机Quickemu 快速指南两条命令创建并启动 macOS、Windows、Linux 虚拟机 想在 Linux 主机上跑一个 macOS 测试环境传统做法要桌面应用上一篇终极分屏工具如何用一台电脑实现4人同乐的游戏革命下一篇3步搭建个人云游戏服务器Sunshine终极免费串流方案创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/11/15 22:51:54

AI Agent落地实战:用AutoGen+Qwen2-7B搞定办公杂活

1. 这不是“AI打工人”,是我在真实工作流里埋下的一个“数字副驾”“我让AI Agent替我干了一个月杂活,说点没人敢说的大实话”——这句话刚在朋友圈刷出来,我就被三个同事同时。不是问链接,不是求教程,而是直接甩来一句…

2026/11/13 19:37:47

GitHub开源项目筛选指南:从文档转换到本地AI编程的10个实用项目

1. 本周榜单的筛选逻辑:为什么这 10 个项目值得占用你的收藏夹每周 GitHub 上新增的开源项目数以万计,Trending 榜单每小时都在滚动,但真正能沉淀下来、值得你花一个周末去跑一遍的项目其实并不多。我做开源项目跟踪这件事已经有些年头了&…

2026/11/16 11:43:52

浚县电工证在哪里申?上岗必备全流程避坑指南

浚县电工证在哪里申?上岗必备全流程避坑指南 怕考不过白交培训费?别急,浚县电工证在哪里申,怎么选机构、怎么备考,全在这篇干货里。 一、浚县电工证在哪里申?官方渠道和靠谱机构怎么找…

2026/11/16 11:43:52

北京大兴电工证考试在哪考?工地太忙根本没时间复习考试

北京大兴电工证考试在哪考?工地太忙根本没时间复习考试 工地太忙根本没时间复习考试,特别是像你这样在新乡房建工程一线干活的,每天跟钢筋混凝土打交道,哪还有心思去研究电工证考试?但别小看这个【北京大兴电工证考试】,它是你往后接项目、进工地、甚至…

2026/11/16 11:43:52

电工证修马达多少钱?外省证书怎么转过来

电工证修马达多少钱?外省证书怎么转过来 之前考的证在外省能不能转过来?这几乎是所有在外务工的特种作业人员最头疼的问题。特别是像你这样在周口从事建筑工作的电工,可能之前在老家或者别的省份考的证,现在需要在本地继续使用。但问题来了:…

2026/11/16 11:43:52

初几电工证考试网上查询全攻略:外省证书怎么转?别再踩坑了!

初几电工证考试网上查询全攻略:外省证书怎么转?别再踩坑了! 之前考的证在外省能不能转过来?这可能是很多电工朋友最头疼的问题。特别是那些在外省考过证、现在又回到本地工作的朋友们,常常遇到证书无法使用的情况。好消息是, 网上查询…

2026/11/16 11:43:51

低压电工证多久检一次,学历不高也能考,多少钱全说清楚

低压电工证多久检一次,学历不高也能考,多少钱全说清楚 学历不高怕报不上名?低压电工证其实不难考,关键是你得知道低压电工证多久检一次,以及报名多少钱。别再被那些“学历门槛高”的说法骗了,现在只要你年满18岁、有相关工作经验,基本上都能报名。今…

2026/11/16 11:38:51

电工证在外省能转吗?考取电工证需要什么书通过率揭秘

电工证在外省能转吗?考取电工证需要什么书通过率揭秘 之前考的证在外省能不能转过来?这是很多电工从业者最关心的问题。如果你正打算考电工证,或者已经在外地考了证但想转回本地,那么这篇文章就是为你准备的。今天就来聊聊考取电工证需要什么书、通过率揭…

2026/11/16 7:29:52

电工证考试口诉怎么准备值不值得考

电工证考试口诉怎么准备值不值得考 实操考试心里没底怕挂科,这是大多数准备考电工证的人心里最真实的感受。尤其是面对【电工证考试口诉】环节,很多人不知道该怎么准备,甚至担心自己说不好就被淘汰。其实,只要掌握方法, 值不值得考…

2026/11/16 5:30:20

桑植县考电工证千万别踩坑!报名全流程教你避坑

桑植县考电工证千万别踩坑!报名全流程教你避坑 你是不是也遇到过这种情况:想考个电工证,但不知道从哪儿下手,怕被中介坑,怕花冤枉钱,更怕考了证还不能用?别急,这正是你该看这篇文章的原因。在桑植县考电工证,确实有很多人被坑过,但只要你知道流程、…

2026/11/16 0:00:11

黎城电工证查询报名费多少钱 内部消息告诉你怎么避开中介陷阱

黎城电工证查询报名费多少钱 内部消息告诉你怎么避开中介陷阱 你是不是也和我一样,想考电工证,但不知道去哪报名,怕被中介坑?最近网上有不少人问“黎城电工证查询报名费多少钱”,结果一查,信息五花八门,真假难辨。别担心,今天我就从一线从业者的角度…

2026/11/16 0:00:11

青岛崂山区电工证培训通过率揭秘:外省证书怎么转过来?

青岛崂山区电工证培训通过率揭秘:外省证书怎么转过来? 之前考的证在外省能不能转过来?这个问题困扰着很多在外地打工的电工,尤其是像南阳卧龙区的建筑工人,他们常年在工地作业,手上持有电工证是基本要求,但很多人因为工作流动性大,担心证书不能转到本…

2026/11/15 4:46:37

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

在智慧养宠时代,基于视觉的宠物身份识别技术正逐步从实验室走向家庭应用。然而,与配合度高的人类不同,宠物是典型的“非合作生物识别对象”——它们不会主动配合摄像头调整姿态,更无法控制光照环境。实际应用中,我们常…

2026/11/16 3:17:47

SSM电子书店源码全解析:结构、原理、部署与排错实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑