企业官网建设流程全解析

• 桌面应用
• 开发工具

导读

trellis mem是 Trellis 工作流系统中负责跨会话记忆检索的本地命令行工具，它直接索引 Claude Code、Codex、Pi Agent 等平台在本机留下的对话日志（JSONL），让开发者和 AI 可以“想起”过去任务里讨论过、决定过、解决过的事。本文以 EcoPaste 仓库中随 Trellis 工作流一同落地的.agents/skills/trellis-session-insight/references/cli-quick-reference.md为核心骨架，完整展开其五个子命令、全部标志位、常用一行命令、输出格式与边界约束，并结合本仓库真实的.trellis/目录结构（会话记录、任务系统、阶段边界）做源码级印证。读完本文，你将能熟练使用trellis mem在任意 Trellis 项目里完成“上次怎么解的”“之前讨论过吗”“继续上次的任务”这类跨会话召回，并在二次开发时理解其能力边界。

trellis mem是什么：从能力定位看它的边界

在进入命令细节之前，先明确trellis mem在 Trellis 体系中的定位。根据本仓库的 trellis-session-insight/SKILL.md 定义，它被设计为能力型工具（capability skill），而非固定工作流：没有强制输出文件、没有固定回写步骤。它负责把“曾经说过的话”捞回来，至于捞回来之后是直接引用、写入prd.md、追加到任务笔记，还是仅仅内化为后续回答的上下文，都由当时对话自行判断。

几个关键事实（均来自本仓库文档，可作事实依据）：

• 本地索引、零上传：mem只读本机磁盘上的平台会话 JSONL 文件，所有读取都是本地的，没有任何内容上传。
• 索引对象：~/.claude/projects/、~/.codex/sessions/、~/.pi/agent/sessions/下的对话日志；OpenCode 目前尚不可索引（provider adapter 待定）。
• 只读不改：mem不会修改平台 JSONL，也不会推送或同步到远程；基于检索结果的任何写入动作，都是你自己的后续决定。
• 文档优先级：trellis mem help在运行时打印的内容与这份参考一致，且是权威来源；快速迭代的 beta 版本中，运行时帮助信息会领先于本文档。

在 EcoPaste 仓库中，Trellis 工作流已被实际启用：根目录存在完整的 .trellis/config.yaml（会话提交信息、任务生命周期钩子、channel worker 配置等）、.trellis/workspace/ayangweb/index.md（已记录 12 个开发会话的标题、提交哈希与分支）、.trellis/spec/（项目级编码规范）以及.agents/skills/下的多个 skill。这意味着本文讲解的命令，在这个仓库的真实开发流程中就是可以直接执行、可以回溯历史会话的实战工具。

五个子命令：Trellis 会话记忆的完整操作面

trellis mem有且仅有五个子命令，mem后不接任何参数时默认执行list。以下为参考文档中的速查表：

从使用节奏上看，这五个命令构成一条典型的检索链路：

1. 不知道会话在哪 →projects或list定位项目作用域；
2. 只记得关键词 →search命中候选会话；
3. 命中后要上下文 →context查看命中轮次及其前后文；
4. 需要完整对话或按阶段切片 →extract导出处理；
5. 要统计本机所有项目的会话分布 →projects。

参考文档特别强调：context与extract是“深入单会话”的两条路径，二者的差异在于context关注命中点及其邻域，extract关注整段对话的清洗与切片，应根据“我要局部证据还是完整过程”来选。

全部标志位详解：参数、作用域与默认值

以下标志位表完整继承自参考文档，并补充了每条参数的实际影响：

关键参数的实际影响

• 作用域三件套（--global/--cwd/--since/--until）：默认情况下list与search只覆盖“当前项目”，即从运行位置推断出的cwd。当你想跨项目翻找记忆，或想强制以某个项目为检索范围时，才需要显式传--cwd <path>；--global则把范围扩到本机全部 Trellis 项目。日期过滤是闭区间（inclusive），用于把检索收窄到某个时间窗口，比如“上周讨论过什么”。
• --grep的多词语义：与一般搜索引擎的 OR 不同，--grep "lock contention"表示同时出现两个词才算命中（multi-token AND）。这让context在单会话内做“关键词锚定”时足够精确——你得到的是同时提到两个词的轮次及其邻域，而不是命中任意一个词的全部轮次。
• --phase的阶段边界机制：这是mem与 Trellis 任务系统深度耦合的关键参数。brainstorm窗口被定义为task.py create与task.py start两次调用之间的轮次，implement则是该窗口之外的部分。在本仓库的 .trellis/scripts/ 中确实存在task.py（其源码中也引用着task.py create/start等生命周期命令），任务状态文件位于.trellis/tasks/<task>/task.json，会话级活跃任务指针位于.trellis/.runtime/sessions/<context-key>.json。task.py start会把任务路径写入当前会话的 runtime 文件，这正是mem能够以--phase区分“规划讨论”与“执行过程”的底层依据。
• --turns/--around/--max-chars的组合控制：context的输出量由三者共同决定——命中轮次数（--turns，默认 3）、每命中点附带的上下文轮数（--around，默认 1）和总字符预算（--max-chars，默认 6000）。当会话很长时，先search定位再context深挖，比直接extract整段对话更省 token。
• --json的稳定性：--json输出使用稳定的 schema，适合程序化解析；而人类可读输出为终端换行排版，会话 id 高亮、轮次标记可见，适合人眼阅读但不适合粘进 Markdown。

常用一行命令：四条高频实战句式

参考文档给出了四条可直接复制执行的常用命令，全部继承如下：

# 本机所有会话里，哪些讨论过 "deadlock"？（跨项目，最多 20 行） trellis mem search "deadlock" --global --limit 20 # 在某个具体会话内，找出提到 "lock contention" 的 Top 5 轮次， # 每轮附带前后各 2 轮上下文。 trellis mem context 5842592d --grep "lock contention" --turns 5 --around 2 # 恢复某个会话的规划阶段（brainstorm 窗口）——适合续接用户一周前 # 开始、尚未完成的任务。 trellis mem extract 5842592d --phase brainstorm # 列出本机每个有 Trellis 会话的项目及其会话数量。 trellis mem projects

在此基础上，结合 trellis-session-insight/SKILL.md 与 triggering-patterns.md，还有几条覆盖 80% 场景的补充句式：

# 项目级默认检索：不传 --global 时只搜当前 cwd 所在项目。 trellis mem search "<keyword>" # 按任务目录找最近会话（适合"继续上次的"场景）。 trellis mem list --cwd <project-path> trellis mem list --task <current-task-dir> # 直接锁定当前活跃任务 # 对当前任务做复盘：分别导出规划讨论与执行过程。 trellis mem extract <session-id> --phase brainstorm trellis mem extract <session-id> --phase implement # 不知道会话 id 时的标准流程：先 list 过滤，再 projects 看全貌。 trellis mem list --since 2026-06-01 --until 2026-07-01

检索意图到命令的映射（何时该用哪条）

本仓库的 triggering-patterns.md 按用户意图对触发场景做了分组，可直接映射为命令选择：

• 过去方案召回（“上次怎么解的 / 之前是怎么搞定 X 的”）→trellis mem search "<症状关键词>" --global --limit 10，再对最接近的命中context深挖。
• 决策检索（“我们当时为啥选了 X 而不是 Y / 之前讨论过 X 的方案吗”）→ 先search "<决策关键词>"找到会话，再用extract <id> --phase brainstorm恢复规划讨论——因为决策往往诞生在 brainstorm 窗口里。
• 跨会话续接（“继续上次的 / 我们上次做到哪了”）→list --task <current-task-dir>找到当前任务最近会话，然后extract最后一条。
• 熟悉 bug 排障（“这个错好像之前见过 / 怎么又是这个 error”）→search "<错误信息片段>" --global，锚定错误串中一个短而独特的 token 效果最好。
• 自身模式观察（“我每次都踩这个坑吗 / 这类问题之前出现过几次”）→search "<主题>" --global --limit 50，扫描列表中的日期与项目分布，必要时extract两三条对比。

同时，参考文档明确列出了一组不该用mem的反模式：问函数作用就读源码、问测试为何失败就看测试输出与文件、问代码库模式就 grep/读 spec、问 npm 版本就npm view、修 bug 就调试——只有在怀疑存在历史上下文时才值得触碰mem。判断标准始终是一句话：“一个资深队友在回答前会不会问一句‘我们不是已经聊过这个了吗？’”

输出形态：人类可读与--json的选择

mem有两种输出形态，参考文档给出的结论非常实用：

• 默认人类可读输出（不带--json）：按终端宽度换行排版，会话 id 有高亮，轮次标记可见。适合直接阅读，但粘进 Markdown 文件会显得杂乱（messy）。
• --json输出：使用稳定 schema，安全可解析。凡是需要把mem输出喂给后续步骤（例如为 Lessons 章节做总结）的场景，优先用--json。

这条建议的本质是：人类可读输出优化的是“人眼扫读”，JSON 输出优化的是“程序消费”。在 AI 工作流里，mem的输出经常要作为后续总结、写入任务笔记或内化的原始素材，因此默认--json是更稳妥的工程选择。

Caveats：四条必须牢记的边界约束

参考文档的“Caveats”部分是trellis mem的能力红线，完整继承如下并逐条展开：

1. OpenCode 适配器是桩（stub）：在0.6.0-beta.*版本上，当--platform解析到 OpenCode（或使用all且 OpenCode 会被纳入）时，mem只会打印一行 “reader unavailable” 提示，然后继续处理其他平台。在适配器正式发布之前，不要在回复中承诺 OpenCode 会话的覆盖能力。
2. --phase切片依赖task.py create/task.py start的调用记录：阶段边界需要这两条命令出现在会话的 bash 调用记录里。如果用户是在记录 AI 循环之外的另一个终端里手动运行task.py，那么该会话就不会有阶段边界，此时--phase all是安全回退。
3. mem直接索引平台 JSONL 文件：如果用户已经清除了 Claude / Codex / Pi 的会话存储，磁盘上不存在的日志mem无法恢复。mem不是云备份，它的记忆上限就是本机 JSONL 文件的存活时间。
4. mem是只读的：没有远程同步，不会编辑平台 JSONL。基于mem检索结果做的任何写入，都是你自己的后续动作（比如更新prd.md、追加任务笔记、更新.trellis/spec/），mem本身不会替你写。

其中第 2 条与 Trellis 任务系统的关联值得再强调：task.py create/task.py start这两个生命周期命令正是本仓库 .trellis/config.yaml 中任务生命周期钩子（after_create/after_start等）所挂接的事件，也是 .trellis/workspace/ayangweb/index.md 中会话记录得以按任务归类的机制来源。阶段切片的可靠性，本质上是“任务边界调用是否发生在被记录会话内”的函数。

当这份参考不够用时

参考文档在结尾给出了明确的升级路径：在用户 shell 中运行trellis mem help。运行时帮助是权威来源，在快速迭代的 beta 版本中会领先于这份静态参考——因此任何“文档与实际输出不一致”的场合，都应优先相信trellis mem help的实际输出。这也符合 Trellis 文档体系的一贯原则：静态参考用于日常速查，运行时帮助用于版本漂移时校准。

• 桌面应用
• 开发工具