ccbox-insights

ccbox-insights

使用 ccbox 会话日志，为 Agent（以及人类）编写一份基于证据的「经验教训」备忘录，并提供可直接复制的指令片段，以改进后续会话。

工具调用失败是重要信号，但目标不只是发现错误：还要记录哪些做法奏效、哪些无效，以及未来应养成哪些固定行为。

要求

• $PATH 中需包含 ccbox。
• 能访问 ccbox 扫描的本地会话目录（如果发现结果为空，请参阅 ccbox --help）。

快速开始（单个会话）

1. 查找当前文件夹的最新会话：

ccbox sessions --limit 5 --offset 0 --size

2. 检查最新会话的时间线（如有需要，可增大 --limit）：

ccbox history --full --limit 200 --offset 0

工作流（推荐）

按分阶段的流程执行：收集 -> 筛选 -> 总结 -> 标注 -> 汇总 -> 综合分析 -> 提出指令。

阶段 0：选择范围

• 会话：针对一个 .jsonl 日志进行深入的根本原因分析。
• 项目：针对一个项目的最近 N 个会话，查找反复出现的失败模式。
• 全局：跨项目抽样，查找跨项目模式。

阶段 1：使用 ccbox 收集证据

• 发现项目：ccbox projects
• 列出会话：ccbox sessions [project-path] --limit N --offset 0 --size
• 捕获时间线：ccbox history [log-or-project] --full --limit N --offset 0
• 技能跨度（可选）：ccbox skills [log-or-project] --json

快速排查时，扫描时间线中的失败信号（例如）：error、failed、non-zero、rejected、permission、timeout。

阶段 1.5：识别澄清、更正与中断

将用户的澄清和更正视为工作流出现问题的高信号证据。你的目标是找出 Agent 在哪里偏离了方向，以及什么规则可以防止下次再次偏离。

查找以下用户消息：

• 澄清意图（「我的意思是 X」、「不是那个」、「改用 Y」）。
• 更正错误（「这不对」、「停止」、「还原」、「你没有遵循指示」）。
• 事后重申约束（「不要运行 X」、「不要用表情符号」、「不要使用 cargo」、「不要更改版本」、「不要自动发布」）。
• 因摩擦而中断会话（卡住、反复重试、「取消」、放弃对话）。

对每个此类时刻，记录一条简短的「纠偏记录」：

• 触发因素：Agent 紧接着之前做了什么（工具调用、计划、编辑或假设）。
• 更正：用于澄清或纠正的用户原句。
• 修正：更正后发生了什么变化（采用新方法、改用其他工具、缩小范围）。
• 经验：一条本可避免偏离的规则（可直接复制，并注明适用的项目或全局范围）。

如果会话结束时问题仍未明确解决（或用户放弃会话），应据实标注结果，并根据证据说明可能的中断原因（例如：卡住／超时、反复使用无效工具、约束相互冲突）。

阶段 2：总结较长的时间线（仅在需要时）

如果时间线过长，无法一次性分析，请分段总结：

• 聚焦于：用户请求、工具调用、工具输出／错误及结果。
• 保留：工具名称、命令行、错误消息和用户反馈。
• 每段总结控制在 3-5 句话。

阶段 3：提取每个会话的工具调用特征

对于范围内的每个会话，生成一个符合 references/facets.md 的 JSON 对象。

如果有可用的技能跨度（通过 ccbox skills --json 获取），请尽可能为每次失败标注当时的技能上下文（例如：「此失败发生在提交技能跨度内」）。

硬性规则：

• 只能使用会话日志中的证据；不得臆测缺失的细节。
• 区分「工具失败」与「方法不当」（工具可能执行成功，但仍然不是正确做法）。
• 将用户明确拒绝的操作单独归类（工具并未失败；用户拒绝了该操作）。

阶段 4：汇总与分析

汇总各个类别，整理出：

• 最常出现故障的工具和故障类别。
• 三个根因主题，并附上具体证据片段。
• 应转化为长期指令的重复用户约束。
• 与引擎无关、能够减少工具调用故障并改善用户体验的建议。

使用 references/report.md 作为输出模板。

阶段 5：提出指令更新（项目级 + 全局）

提供两组可直接复制使用的增量内容：

• 项目级：添加到 AGENTS.md 的要点。
• 全局：添加到用户全局 Agent 指令的要点。

指南：

• 不要包含本地路径、仓库名称或一次性事件的细节。
• 优先选择能防止重复错误（出现 2 次或以上）的规则，而不是只适用于单次问题的修复方案。
• 每条指令都应说明要做什么、要避免什么以及原因（1 句话）。

阶段 6：交付内容

交付：

• 一份简洁的经验总结备忘录（Markdown），遵循 references/report.md。
• 拟议的 AGENTS.md 增量片段（项目级）。
• 拟议的全局指令增量片段。

可选（供未来的记忆系统使用）：

• “AutoMemorial 候选项”：一份简短、结构化的规则清单；每条规则都应有证据支持，并标明适用范围（项目级还是全局）。

参考资料

• 类别架构与分类体系：references/facets.md
• 报告模板与指令模板：references/report.md