企业官网建设流程全解析

• 桌面应用

导读

本文围绕 EcoPaste 仓库内.kiro/skills/trellis-session-insight/SKILL.md所定义的能力型技能展开：它教会 AI 如何在正确时机调用trellis mem—— 一个本地化、只读的跨会话记忆检索 CLI，用来索引并搜索历史 AI 对话日志。读完本文，你将掌握trellis mem的全部子命令与标志位用法、判断"该不该翻历史"的触发模式与反模式，以及拿到检索结果后如何在 PRD、spec、任务笔记之间做出正确的落盘决策。

背景：这套 Skill 在仓库中的位置

本技能文件位于 .kiro/skills/trellis-session-insight/SKILL.md，与其配套的还有两份权威参考文档：

• references/cli-quick-reference.md：trellis mem五个子命令的完整标志位速查表，运行时trellis mem help输出与之相同，是运行时之外的权威来源；
• references/triggering-patterns.md：中英文逐字触发短语清单，按用户意图而非表面措辞分组。

从设计定位上看，这是一个能力型（capability）技能，而非工作流型（workflow）技能。它没有固定的输出文件、没有强制写回步骤、没有"finish-work 后必须运行"的硬性规则。技能存在意义是让 AI 知道"这个能力存在"，并在恰当的对话时刻自行判断是否启用、以及拿返回值做什么。

trellis mem是什么

trellis mem是一个本地 CLI，用于索引用户在过往对话中产生的 AI 会话日志，并提供列表、搜索、按 Trellis 任务边界切片、以及导出清洗后对话的能力。具体来说，它直接读取各平台本地存储的 JSONL 文件：

需要特别注意的是，OpenCode 日志目前不可索引。当目标会话明显来自 OpenCode 时，应直接向用户说明这一限制，而不是猜测或编造覆盖能力。

隐私与只读边界：mem的所有读取都发生在本地，任何内容都不会被上传。同时它对平台 JSONL 存储保持只读，不推送、不同步到远端。

什么时候该翻历史：六类触发场景

技能的判定标准可以概括为一句话："一位资深同事会不会在回答前问一句'我们之前是不是已经聊过这个？'"—— 会问，就该调mem。具体有六类可操作的场景：

1. 头脑风暴重演风险（Brainstorm rerun risk）：新任务触及用户此前涉足过的领域，想在再次向用户提问前确认是否已有决策。
2. 眼熟的 Bug 调试（Familiar-bug debugging）：当前 bug 模式与用户之前报告/修复过的相似，拉取相关历史会话可能省下一整轮调试循环。
3. 跨会话续接（Cross-session continuation）：用户隔了一段时间回来，只说"where were we / 继续上次的"，上下文完全隐式。
4. 决策检索（Decision retrieval）：用户提到"我们当时对 X 的决定"，但该决定存在于旧的头脑风暴对话中，而不是任何prd.md或spec/文件里。
5. 收尾复盘（Finish-work retrospective，按需触发）：用户明确要求总结本次任务的决定/痛点/意外点——注意这是用户主动要求时才做，不是每次 finish-work 的强制步骤。
6. 跨历史找规律（Pattern-spotting across past work）：用户问"我是不是老在 X 上犯同样的错"，需要跨会话搜索来回答。

反过来，如果以上场景都不适用，就不要调用mem。它是一件工具，不是一种仪式。

什么时候不该翻历史：四大禁区

• 上下文已在手边：相关信息已经出现在当前对话轮次、prd.md、design.md、最近的git log或已打开的文件中。mem是为"已经掉出即时可及范围"的信息准备的。
• 问的是代码事实而非对话事实：用户问的是代码里的某个事实时，git log -p/grep/ 直接读文件更快也更权威。
• 身处子代理中：trellis-implement/trellis-check子代理的派发 prompt 已经包含了精选过的implement.jsonl/check.jsonl上下文，此时叠加mem通常只会造成信息冗余。
• 用户明确拒绝：用户已经说了"别翻历史，直接回答我问的"。

references/triggering-patterns.md中还列举了五类"反模式"提问，均不适用mem：

拿到mem返回值之后：五种即时决策

mem的输出应被当作原材料（raw material）而非交付物。拿到之后，根据实时对话氛围决定处置方式：

1. 在回复中内联引用：某段具体的历史交流恰好能回答当前问题——引用时附带 session-id / phase，便于用户自行核实。
2. 更新<task>/prd.md或<task>/design.md：mem挖出了某个本应落盘却没落盘的关键决策。先向用户展示拟议的修改。
3. 追加到任务本地笔记：例如<task>/notes.md或扩展已有笔记文件——当发现属于当前任务记录、但又不适合放进 PRD 时。
4. 更新.trellis/spec/：发现的是项目级通用约定或坑点时，调用trellis-update-spec技能来做这件事——session-insight的职责止步于"发现"。
5. 仅仅吸收：在接下来几轮对话中用更好的回答回报用户，什么也不写。对一次性回忆来说这通常是最正确的选择。

Trellis 不规定唯一的落盘目的地。把每一次回忆都强塞进固定文件，只会让文件膨胀成噪音——让现场情况决定去向。

这与仓库中其他记忆系统的分工互为补充：.trellis/workspace/存跨会话的工作记录（journal），.trellis/tasks/存具体任务的需求与状态，.trellis/spec/存需要长期遵守的工程约定（详见 .kiro/skills/trellis-meta/references/local-architecture/workspace-memory.md）。

怎么调用：五个子命令速查

mem的 CLI 接口由五个子命令组成，其中list是缺省子命令。完整的标志位参考见 references/cli-quick-reference.md：

最常见的 80% 用例就是下面这几条：

# 查找内容提到某关键字的会话（默认按当前项目范围；加 --global 搜索本机所有项目） trellis mem search "<keyword>" # 导出一个会话的对话，可按 phase 或关键字过滤 trellis mem extract <session-id> --phase brainstorm trellis mem extract <session-id> --grep "<keyword>" # 钻入会话：Top-N 命中轮次 + 周边上下文 trellis mem context <session-id> --turns 3 --around 2 # 还不知道 session id 时，先从 list + 过滤开始 trellis mem list --cwd <project-path> trellis mem projects # → 列出活跃项目 cwd，再收窄范围

标志位全景表

在适用处，mem支持以下标志（含义以trellis mem help的运行时输出为最终权威）：

Phase 切片的原理

--phase切片依赖会话 bash 调用记录中出现的task.py create与task.py start调用作为边界：brainstorm区间是[task.py create, task.py start)，implement区间是其余轮次，默认all不做切片。在做当前任务的收尾复盘时，--phase brainstorm可以恢复规划期的讨论，--phase implement可以恢复执行循环。

一个重要的限制：如果用户在另一个终端（AI 记录循环之外）运行了task.py，该会话将不存在 phase 边界，此时--phase all是安全的回退。

常用单行命令示例

# 本机任何项目的历史会话里谁讨论过 "deadlock"？ 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

注意context示例中的 session-id5842592d为占位示意，实际使用时请先通过list/search/projects获取真实 id。

输出形态：人读与机读

• 默认人类可读输出（不加--json）：按终端宽度折行，session id 高亮，轮次标记可见。适合直接内联阅读，但不适合粘贴进 markdown 文件。
• --json输出：schema 稳定、可安全解析。当要把mem输出管道化到后续步骤（例如为 Lessons 章节做摘要）时，优先使用--json。

注意事项与已知边界

参考文档明确列出了四类必须牢记的 caveats：

1. OpenCode 适配器仍是 stub：在0.6.0-beta.*版本上，当--platform解析到 OpenCode（或all且本应包含 OpenCode）时，mem会打印一行 "reader unavailable" 提示并继续处理其他平台。在适配器发布之前，不要在回复中承诺 OpenCode 覆盖。
2. Phase 边界依赖记录：--phase切片依赖会话中记录的task.py create/task.py startbash 调用。从外部终端运行task.py的会话没有 phase 边界。
3. 索引直接基于平台 JSONL 文件：如果用户清空了 Claude / Codex / Pi 的会话存储，mem无法恢复已不在磁盘上的内容。
4. 只读：无远端同步、不改动平台 JSONL。基于mem发现所做的任何写入，都是你自己对编辑工具的后续调用。

当这份参考不够用时：在用户的 shell 中运行trellis mem help。运行时帮助是权威来源，在快速迭代的 beta 版本中会比这份参考文档更新得更快。

触发短语清单：训练直觉的对照表

references/triggering-patterns.md 提供了大量逐字用户短语（中英双语），按"背后的意图"而非表面措辞分组。技能建议用这些来校准直觉：命中其中之一却没有想起mem，很可能就是漏掉了一次明显的回忆。

对收尾复盘场景，技能还强调：总结时应尽量附上具体的 file:line 引用；是否把总结写入某处（PRD、spec、笔记文件）由用户决定——可以提议，但不要自动写入。

与其他技能的分工边界

trellis-session-insight明确声明了自己的 Out of scope，避免与其他技能职责混淆：

• mem不编辑代码、不更新文件：任何写回动作都是你在当下做出的判断。
• mem对平台 JSONL 存储只读：不推送、不同步到远端。
• 本技能不替代trellis-update-spec：把发现提升为项目级指导是trellis-update-spec的职责（见 .kiro/skills/trellis-update-spec/SKILL.md），也替代不了平台原生的任务/spec 工作流。

这条分工在整体架构上是自洽的：从 .kiro/agents/trellis.json 可以看到，主代理通过 hook 注入<workflow-state>面包屑来定位当前任务与阶段，而mem解决的是"历史对话里发生了什么"；从 .kiro/skills/trellis-finish-work/SKILL.md 可以看到，会话收尾时会把工作记录写入 workspace journal——mem检索的正是这些跨会话的痕迹，两者形成"写入—检索"的闭环。

总结

trellis mem是一把精心限界的记忆检索工具：它只读、本地、索引三大主流平台的 AI 会话日志，用五个子命令覆盖"找会话、看上下文、导对话、列项目"的完整检索路径。而trellis-session-insight这个能力型技能的价值在于教 AI克制地使用它——只在"资深同事会问我们是不是聊过"的时刻调用，拿到结果后按现场情况决定是内联引用、补写 PRD、追加笔记、升级 spec 还是单纯吸收。判断力本身，才是这个技能真正想传递的东西。

• 桌面应用