企业官网建设流程全解析

• 桌面应用

在 AI 辅助开发中，最常被忽视却影响体验的环节，是「换一个窗口、换一天之后，AI 是否还记得上次做到哪里」。本文以 EcoPaste 仓库内捆绑的 Trellis 技能文档 workspace-memory.md 为核心，系统讲解 Trellis 的本地工作区记忆系统：.trellis/workspace/的目录结构、开发者身份初始化、会话日志（journal）的记录与轮转、以及它与任务目录、工程规范之间的分工。读完本文，你将掌握一套可落地的跨会话记忆维护方法，并能通过.trellis/config.yaml精确定制记忆容量与写入格式。

一、本地工作区记忆系统是什么

Trellis 在已执行trellis init的项目中，会在仓库根目录生成.trellis/运行时目录。其中.trellis/workspace/专门承担跨会话记忆的职责：它记录「在此之前发生了什么」，让 AI 和人类在不同窗口（不同终端、不同 AI 工具会话）与不同日期之间，都能快速理解项目此前的进展脉络。

在 overview.md 的三层本地系统模型中，这一目录属于持久化层（Persistence Layer）：

关键设计原则是：工作区记忆存储的是「刻意书写」的开发者日志，而不是原始对话流水。Trellis 的 SKILL.md 明确说明：原始跨会话对话不会存储在这里，而是留在各平台自己维护的 JSONL 日志中（如~/.claude/projects/、~/.codex/sessions/、~/.pi/agent/sessions/），需要时通过trellis mem search|extract|context命令回查。.trellis/workspace/与原始日志一「精」一「全」，共同构成完整的跨会话记忆体系。

二、目录结构与文件职责

workspace-memory.md给出的标准目录结构如下：

.trellis/workspace/ ├── index.md └── <developer>/ ├── index.md ├── journal-1.md └── journal-2.md

各文件的职责如下表所示：

从结构上可以看出两层设计：

• 按开发者隔离：每位开发者拥有独立的子目录，日志互不混淆，适合多人协作或同一机器上多身份交替使用的场景；
• 索引与正文分离：index.md承担「入口/概览」职能，journal-N.md才是具体的工作记录。这与 Trellis 全体系的索引化上下文设计一脉相承——先注入索引和路径，让 AI 按需读取详细文件，而不是把所有内容无限制塞进上下文（详见 change-context-loading.md 中「Context cannot grow without bound」的原则）。

在 generated-files.md 的可编辑性分级中，.trellis/workspace/被标记为可直接编辑（通常由add_session.py写入），而.trellis/.developer被标记为谨慎编辑——它记录当前开发者身份，改动会直接影响后续日志写入的归属。

三、开发者身份初始化

第一次使用工作区记忆系统时，需要先初始化开发者身份。在项目根目录执行：

python3 ./.trellis/scripts/init_developer.py <name>

例如：

python3 ./.trellis/scripts/init_developer.py alice

该命令会完成两件事：

1. 创建.trellis/.developer文件，写入当前开发者身份；
2. 创建对应的.trellis/workspace/<developer>/工作区目录，为后续日志写入做准备。

官方文档对此有一条重要提醒：AI 不应随意更改开发者身份。如果发现身份有误，应当先确认当前正在使用该项目的人是谁，而不是自作主张切换。这是因为身份一旦切换，跨会话记忆就会被拆散到不同的<developer>/子目录下，破坏「同一个开发者跨窗口、跨天」的记忆连续性。

四、会话日志（Journal）的记录与轮转

4.1 日志的定位与轮转机制

journal-N.md记录每个会话中已完成或部分完成的工作。默认情况下，单个 journal 文件约容纳2000 行；达到上限后会自动轮转到下一个文件（journal-1.md→journal-2.md→ ……），避免单个文件无限膨胀、难以检索。

该默认值与两个配置项直接相关，均位于.trellis/config.yaml：

此外，SKILL.md 还提到.trellis/config.yaml中有一个session_auto_commit配置项，它与session_commit_message共同决定会话结束后是否自动生成提交记录及其提交信息。

4.2 记录一次会话的标准命令

记录会话最常用的命令是add_session.py：

python3 ./.trellis/scripts/add_session.py \ --title "Session title" \ --summary "What changed" \ --commit "abc1234"

参数说明：

针对规划类或评审类工作（尚未产生提交），同样可以记录，只需使用--no-commit，或者传入一个空提交值：

python3 ./.trellis/scripts/add_session.py \ --title "Planning review" \ --summary "Reviewed API design options, no code yet" \ --no-commit

这一设计保证了工作区记忆不依赖 git 提交节奏：即使某次会话只有讨论、调研、设计结论，也依然能被忠实记录下来，供后续会话恢复背景。

4.3 日志的两种读取角色

从上下文注入的角度看，日志扮演两种角色（参见 context-injection.md）：

• 会话启动注入：session-start事件注入的 Trellis 概览中，包含当前开发者、git 状态、活跃任务、以及日志（journal），让新会话一开始就有记忆入口；
• 按需读取：AI 根据索引和路径决定是否深入阅读某篇 journal 的完整内容，避免上下文被冗余信息占满。

如果你在新会话中发现 AI「失忆」，优先检查平台是否安装了session-starthook、注入内容是否包含 workspace 概览，而不是直接怀疑日志没写入。

五、工作区记忆与任务、规范之间的分工

这是整个记忆体系中最容易被混淆的部分。.trellis/下有三个容易「放错东西」的目录，官方文档用一张对照表划清了边界：

对应地，官方给出了三条简单可执行的判定规则：

• 如果信息只对当前任务有用→ 放入任务目录.trellis/tasks/；
• 如果信息描述的是当前会话中发生了什么→ 放入工作区日志.trellis/workspace/；
• 如果信息是以后每次写代码都需要遵守的规则→ 放入.trellis/spec/。

这三条规则可以进一步与任务系统（task-system.md）与规范系统（spec-system.md）对应：任务目录中的prd.md、design.md、implement.md描述「这一件事要怎么做」，工作区日志描述「这段时间发生了什么」，spec 描述「这个项目永远要怎么做」。三者互不替代，共同构成完整的项目记忆闭环。

六、本地定制点

工作区记忆系统保留了清晰的定制入口，全部集中在项目本地，无需改动 Trellis CLI 源码：

其中两项操作前需要特别留意：

• .trellis/scripts/属于「谨慎编辑」区（见 generated-files.md）。它是本地运行时（Local Python runtime），被命令、hooks 与上下文注入共同调用，修改前必须先理解调用链，不能盲目改动；
• .trellis/.developer同样属于「谨慎编辑」区，身份变更应遵循「先确认使用者」的原则（见第三节）。

需要说明的是：.trellis/目录由trellis init生成，本文所引用的目录结构、脚本与配置项描述的是已初始化 Trellis 的项目中的形态；EcoPaste 仓库当前捆绑的是 Trellis 的技能与参考文档（位于.agents/skills/trellis-meta/），若要在项目中使用这套记忆系统，需先在本地执行trellis init完成运行时生成。

七、AI 使用规则与最佳实践

workspace-memory.md最后给出了一段对 AI 行为有约束力的规则，它决定了工作区记忆在整体工作流中的正确用法：

AI 不应把工作区当作唯一的事实来源。恢复任务时，应先阅读当前任务，再把工作区作为背景信息。任务完成后，把重要的过程记录写入工作区；如果产生了长期规则，则应更新 spec。

拆解为可执行的最佳实践：

1. 恢复任务时的读取顺序：先读任务目录（prd.md→design.md→implement.md），再读工作区日志补充背景，而不是反过来被日志牵着走；
2. 任务完成后的写入动作：会话结束时，用add_session.py写入过程记录，保证下次会话有迹可循；
3. 规则的沉淀路径：如果过程中「悟出」了值得长期遵守的约定，应当升级到.trellis/spec/，而不是只留在日志或聊天记录里；
4. 原始对话的查证路径：需要找回某段历史讨论原文时，使用trellis mem（对应技能见 trellis-session-insight/SKILL.md），它直接检索各平台落盘的 JSONL 会话日志，与工作区的「精编日志」互补。

八、结语：一套可持续的跨会话记忆闭环

EcoPaste 仓库捆绑的 Trellis 技能文档，把「跨会话记忆」拆成了清晰的三段式闭环：工作区日志负责「发生了什么」、任务目录负责「这一件事怎么做」、spec 负责「这个项目永远怎么做」，再用trellis mem回查原始对话兜底。这套设计让 AI 在切换窗口、切换天数之后，依然能快速找回上下文，同时通过.trellis/config.yaml中的max_journal_lines、session_commit_message等配置项，让记忆容量与格式完全适配团队的实际节奏。

对正在使用或计划引入 Trellis 的开发者而言，本文所述的目录结构、初始化命令、日志记录命令与定制点，均可在本地项目中原样落地；更完整的架构上下文，可继续阅读 overview.md（三层本地架构总览）、generated-files.md（init 生成文件与编辑边界）与 change-context-loading.md（上下文加载与注入调优）。

• 桌面应用