Back to Details

ccbox-insights

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ccbox-insights

ccbox-insights

Use 
ccbox
session logs to produce an evidence-based "lessons learned" memo for the agent (and humans), plus copy-ready instruction snippets that improve future sessions.
Tool-call failures are an important signal, but the goal is broader than errors: capture what worked, what did not, and what should become standing behavior in the future.
使用
ccbox
会话日志为Agent（及人类）生成基于证据的“经验教训”备忘录，同时生成可直接使用的指令片段以优化后续会话。
工具调用失败是重要信号，但目标不仅限于错误：还要捕捉哪些方法有效、哪些无效，以及哪些行为应成为未来的常规操作。

Requirements

要求

  • ccbox
    on your 
    $PATH
    .
  • Access to the local sessions directory scanned by 
    ccbox
    (see 
    ccbox --help
    if discovery looks empty).
  • ccbox
    已添加至你的
    $PATH
    环境变量中。
  • 可访问
    ccbox
    扫描的本地会话目录（如果未发现内容，可查看
    ccbox --help
    ）。

Quick start (single session)

快速开始（单会话）

  1. Find the latest session for the current folder:
bash
ccbox sessions --limit 5 --offset 0 --size
  1. Inspect the latest session timeline (increase 
    --limit
    if needed):
bash
ccbox history --full --limit 200 --offset 0
  1. 查找当前文件夹的最新会话：
bash
ccbox sessions --limit 5 --offset 0 --size
  1. 查看最新会话的时间线（必要时增大
    --limit
    参数）：
bash
ccbox history --full --limit 200 --offset 0

Workflow (recommended)

推荐工作流

Follow a staged pipeline: collect -> filter -> summarize -> label -> aggregate -> synthesize -> propose instructions.
遵循分阶段流程：收集→筛选→总结→标记→聚合→合成→提出指令。

Stage 0: Choose scope

阶段0：选择范围

  • Session: one 
    .jsonl
    log for deep root-cause analysis.
  • Project: last N sessions for one project to find recurring failure patterns.
  • Global: a sample across projects to find cross-project patterns.
  • 会话：单个
    .jsonl
    日志，用于深度根因分析。
  • 项目：某一项目的最近N个会话，用于发现重复出现的失败模式。
  • 全局：跨项目的样本，用于发现跨项目的模式。

Stage 1: Collect evidence with 
ccbox

阶段1：使用
ccbox
收集证据

  • Project discovery: 
    ccbox projects
  • Session listing: 
    ccbox sessions [project-path] --limit N --offset 0 --size
  • Timeline capture: 
    ccbox history [log-or-project] --full --limit N --offset 0
  • Skill spans (optional): 
    ccbox skills [log-or-project] --json
When triaging quickly, scan the timeline for failure signals (examples): 
error
, 
failed
, 
non-zero
, 
rejected
, 
permission
, 
timeout
.
  • 项目发现：
    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
。

Stage 1.5: Identify clarifications, corrections, and interruptions

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

Treat user clarifications/corrections as high-signal evidence of workflow breakdowns. Your goal is to pinpoint where the agent went off-track and what rule would prevent it next time.
Look for user messages that:
  • Clarify intent ("I meant X", "not that", "use Y instead").
  • Correct mistakes ("this is wrong", "stop", "revert", "you didn't follow the instructions").
  • Restate constraints after the fact ("do not run X", "no emojis", "do not use cargo", "do not change version", "do not release automatically").
  • Interrupt the session due to friction (hangs, repeated retries, "cancel", abandoning the thread).
For each such moment, capture a small "course-correction record":
  • Trigger: what the agent did immediately before (tool call, plan, edit, or assumption).
  • Correction: the exact user sentence(s) that clarified/corrected.
  • Fix: what changed after the correction (new approach, different tool, narrower scope).
  • Lesson: one rule that would have prevented the detour (copy-ready, scoped project/global).
If the session ends without a clear resolution (or the user abandons it), mark the outcome accordingly and explain the likely interruption reason using evidence (for example: hang/timeout, repeated invalid tool use, conflicting constraints).
将用户的澄清/修正视为工作流故障的高信号证据。目标是准确定位Agent偏离轨道的节点，以及可避免此类问题的规则。
留意用户的以下类型消息：
  • 澄清意图（“我指的是X”、“不是那个”、“改用Y”）。
  • 修正错误（“这不对”、“停止”、“撤销”、“你没有遵循指令”）。
  • 事后重申约束条件（“不要运行X”、“不要使用表情符号”、“不要用cargo”、“不要修改版本”、“不要自动发布”）。
  • 因摩擦中断会话（卡顿、重复重试、“取消”、放弃会话线程）。
针对每个此类时刻，记录一条简短的“路线修正记录”：
  • 触发点：Agent在修正前的操作（工具调用、计划、编辑或假设）。
  • 修正内容：用户用于澄清/修正的具体语句。
  • 修复结果：修正后的变化（新方法、不同工具、更窄的范围）。
  • 经验教训：可避免此次偏离的一条规则（可直接使用，区分项目级/全局级）。
如果会话未得到明确解决就结束（或用户放弃会话），需相应标记结果，并使用证据解释可能的中断原因（例如：卡顿/超时、重复使用无效工具、约束条件冲突）。

Stage 2: Summarize long timelines (only if needed)

阶段2：总结长时间线（仅在必要时）

If the timeline is too large to analyze in one pass, summarize in chunks:
  • Focus on: user request, tool calls, tool outputs/errors, and outcome.
  • Preserve: tool names, command lines, error messages, and user feedback.
  • Keep each chunk summary to 3-5 sentences.
如果时间线过长无法一次分析，可分块总结：
  • 重点关注：用户请求、工具调用、工具输出/错误、以及结果。
  • 保留内容：工具名称、命令行、错误消息、用户反馈。
  • 每个块的总结控制在3-5句话。

Stage 3: Extract per-session tool-call facets

阶段3：提取每个会话的工具调用维度

For each session in scope, produce one JSON object matching 
references/facets.md
.
If skill spans are available (via 
ccbox skills --json
), annotate each failure with the active skill context when possible (e.g., "this failure happened inside the commit skill span").
Hard rules:
  • Use only evidence from the session log; do not guess missing details.
  • Separate "tool failed" from "wrong approach" (a tool can succeed but still be the wrong move).
  • Count explicit user rejections as their own category (the tool did not fail; the action was declined).
针对范围内的每个会话，生成一个符合
references/facets.md
的JSON对象。
如果技能跨度可用（通过
ccbox skills --json
获取），尽可能为每个失败标注对应的活跃技能上下文（例如：“此失败发生在commit技能跨度内”）。
硬性规则：
  • 仅使用会话日志中的证据；不要猜测缺失的细节。
  • 区分“工具失败”与“方法错误”（工具可能执行成功，但选择的方法仍不正确）。
  • 将用户明确拒绝的情况单独归为一类（工具未失败，但操作被拒绝）。

Stage 4: Aggregate and analyze

阶段4：聚合与分析

Aggregate the facet set to produce:
  • Top failing tools and failure categories.
  • Three root-cause themes with concrete evidence snippets.
  • Repeated user constraints that should become standing instructions.
  • Engine-neutral recommendations that reduce tool-call failures and improve UX.
Use 
references/report.md
as the output template.
聚合维度数据以生成：
  • 失败次数最多的工具及失败类别。
  • 三个带有具体证据片段的根因主题。
  • 应成为常规指令的重复出现的用户约束条件。
  • 与引擎无关的建议，以减少工具调用失败并提升用户体验。
使用
references/report.md
作为输出模板。

Stage 5: Propose instruction updates (project + global)

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

Produce two additive sets of copy-ready snippets:
  • Project-level: bullets to add to 
    AGENTS.md
    .
  • Global: bullets for the user's global agent instructions.
Guidelines:
  • Do not include local paths, repository names, or one-off incident details.
  • Prefer rules that prevent repeated errors (2+ occurrences) over one-time fixes.
  • Each instruction should include: what to do, what to avoid, and why (1 sentence).
生成两组可直接使用的增量指令片段：
  • 项目级：需添加至
    AGENTS.md
    的项目符号列表。
  • 全局级：用于用户全局Agent指令的项目符号列表。
指导原则：
  • 不要包含本地路径、仓库名称或一次性事件细节。
  • 优先选择可避免重复错误（出现2次及以上）的规则，而非一次性修复方案。
  • 每条指令应包含：操作内容、禁止内容、原因（1句话）。

Stage 6: Deliverables

阶段6：交付物

Deliver:
  • A concise lessons learned memo (Markdown), following 
    references/report.md
    .
  • Proposed additive 
    AGENTS.md
    snippet (project-level).
  • Proposed additive global instruction snippet.
Optional (for future memory systems):
  • "AutoMemorial candidates": a short, structured list of rules that should become standing agent memory, each backed by evidence and scoped (project vs global).
交付内容：
  • 一份简洁的经验教训备忘录（Markdown格式），遵循
    references/report.md
    模板。
  • 建议添加的
    AGENTS.md
    增量片段（项目级）。
  • 建议添加的全局指令增量片段。
可选（针对未来记忆系统）：
  • “自动记忆候选项”：一份简短的结构化规则列表，应成为Agent的常规记忆，每条规则均有证据支持，并区分项目级/全局级。

References

参考资料

  • Facet schema + taxonomy: 
    references/facets.md
  • Report template + instruction templates: 
    references/report.md
  • 维度 schema + 分类体系：
    references/facets.md
  • 报告模板 + 指令模板：
    references/report.md