trellis-session-insight

Trellis 会话洞察

此技能教 AI 如何调用 trellis mem——项目的跨会话记忆素材库，以及何时适合使用它。

它有意设计为能力技能，而非工作流。没有固定的输出文件，也没有必需的回写步骤，更没有“每次完成工作后都要运行”的规则。如何处理 mem 返回的内容，取决于当下对话中的具体判断。此技能旨在让 AI 了解这项能力的存在，并自行决定是否使用。

trellis mem 是什么

这是一个本地 CLI，可为用户过去在 Claude Code、Codex、Devin CLI、Grok、OpenCode、Pi Agent 和 ZCode 中的对话日志建立索引，并允许你列出、搜索、按 Trellis 任务边界切片，以及导出清理后的对话内容。Claude 和 Codex 使用 ~/.claude/projects/ 和 ~/.codex/sessions/。Devin CLI（Cognition 终端 Agent，不是 trellis init --devin Desktop）使用 ~/.local/share/devin/cli/sessions.db。Grok 使用 ~/.grok/sessions/。OpenCode 使用 ~/.local/share/opencode/opencode.db（零依赖 SQLite 读取器）。Pi 使用其默认会话根目录或通过环境变量配置的会话根目录、全局 ~/.pi/agent/settings.json，以及项目范围内的 .pi/settings.json；相对 sessionDir 值会以设置文件所在目录为基准解析。项目本地 Pi 设置需要通过当前 cwd 或 --cwd 进行项目范围查找。ZCode 使用 ~/.zcode/cli/db/db.sqlite。

mem 不会上传任何内容。所有读取都在本地进行。

何时使用

判断标准是：“资深队友会不会问‘我们不是已经聊过这个了吗？’”——遇到这类情况时，就可以考虑使用。以下是一些具体场景：

• 避免重复头脑风暴。 开始一项涉及用户曾经处理过的领域的新任务，并想在再次询问用户前确认是否已经做出决定。
• 排查似曾相识的 Bug。 当前 Bug 的模式让你觉得用户以前报告过或修复过类似问题。调取相关的过往会话，可以省去完整的一轮调试。
• 跨会话继续工作。 用户间隔一段时间后继续工作，并含糊地说“我们进行到哪儿了”／“继续上次的”。
• 找回决策。 用户提到“我们关于 X 做出的决定”，但这个决定记录在较早的头脑风暴中，而不是任何 prd.md／spec/ 文件里。
• 完成工作后的回顾。 用户明确要求总结这项任务中做出的决定、遇到的困难或意外，而不是每次完成工作时都强制执行。
• 从过往工作中发现规律。 用户问“我是不是总在 X 上犯同样的错误”／“我每次都踩这个坑吗”——搜索过往会话可以找到答案。

如果不符合以上任何一种情况，就不要调用 mem。它是工具，不是仪式。

何时不要使用

• 相关上下文已经出现在当前轮次、prd.md、design.md、最近的 git log 或打开的文件中。mem 用于查找已经无法立即获取的信息。
• 用户问的是代码中的事实，而不是过往对话中的事实。直接使用 git log -p／grep 或阅读文件更快，也更可靠。
• 你正在子 Agent（trellis-implement／trellis-check）中，其派发提示词已经包含整理好的 implement.jsonl／check.jsonl 上下文。此时再使用 mem 通常只会让内容变得杂乱。
• 用户明确说了“不要翻历史，直接回答我问的内容”。

如何处理 mem 返回的内容

将输出视为原始素材，而非最终交付物。获取内容后，根据当前对话做出判断：

• 如果某段具体的过往交流回答了用户当前的问题，就在回复中直接引用，并注明 session-id / phase，方便用户核实。
• 如果 mem 找到了一项本应记录却遗漏的关键决策，就更新 <task>/prd.md 或 <task>/design.md。先向用户展示拟议的修改。
• 如果发现内容属于当前任务的记录，但不适合放进 PRD，就追加到任务专属的备注文件中（例如 <task>/notes.md，或扩展现有文件）。
• 如果发现内容是有助于未来任务的项目级约定或注意事项，就更新 .trellis/spec/。为此运行 trellis-update-spec 技能——session-insight 的职责到发现为止。
• 也可以只在接下来的几轮对话中记住这些内容，并据此给出更好的回答，而不写入任何文件。对于一次性回忆，这通常是正确的做法。

Trellis 不会规定唯一的存放位置。强行把每次回忆都写进固定文件，只会让文件逐渐充斥无关内容。根据具体情况决定。

如何调用

完整的 CLI 参考见 references/cli-quick-reference.md。最常见的 80% 情况可使用以下方式之一：

# Find sessions whose contents mention a keyword (project-scope is default;
# add --global to search every project on this machine).
trellis mem search "<keyword>"

# Dump dialogue from one session, optionally filtered by phase or keyword.
trellis mem extract <session-id> --phase brainstorm
trellis mem extract <session-id> --grep "<keyword>"

# Drill into a session: top-N hit turns + surrounding context.
trellis mem context <session-id> --turns 3 --around 2

# When you do not know the session id yet, start with list + filter.
trellis mem list --cwd <project-path>
trellis mem projects   # → list active project cwds, then narrow

按阶段切分（--phase brainstorm|implement|all）会在 task.py create 和 task.py start 的边界处切分会话。要复盘当前任务的收尾工作时，--phase brainstorm 会还原规划讨论，--phase implement 会还原执行过程。默认值为 all。

触发模式

references/triggering-patterns.md 列出了更多用户原话（英文 + 中文）。当这些表述出现时，你应想到“使用 mem”——训练直觉时请随手参考。

不适用范围

• mem 不会编辑代码或更新文件。是否写回由你根据当下情况决定。
• mem 对平台 JSONL 存储是只读的，不会推送或同步到远程。
• 此技能不能替代 trellis-update-spec（它才是将发现转化为项目级指南的正确工具），也不能替代平台原生的任务 / 规范工作流。