ccbox-insights

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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)

快速开始（单会话）

Find the latest session for the current folder:

bash

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

Inspect the latest session timeline (increase
```
--limit
```
if needed):

bash

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

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

bash

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

查看最新会话的时间线（必要时增大
```
--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
```

ccbox-insights

Original

Translation

ccbox-insights

ccbox-insights

Requirements

要求

Quick start (single session)

快速开始（单会话）

Workflow (recommended)

推荐工作流

Stage 0: Choose scope

阶段0：选择范围

Stage 1: Collect evidence with
`ccbox`

阶段1：使用
`ccbox`
收集证据

Stage 1.5: Identify clarifications, corrections, and interruptions

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

Stage 2: Summarize long timelines (only if needed)

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

Stage 3: Extract per-session tool-call facets

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

Stage 4: Aggregate and analyze

阶段4：聚合与分析

Stage 5: Propose instruction updates (project + global)

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

Stage 6: Deliverables

阶段6：交付物

References

参考资料

ccbox-insights

Original

Translation

ccbox-insights

ccbox-insights

Requirements

要求

Quick start (single session)

快速开始（单会话）

Workflow (recommended)

推荐工作流

Stage 0: Choose scope

阶段0：选择范围

Stage 1: Collect evidence with ccbox

阶段1：使用ccbox收集证据

Stage 1.5: Identify clarifications, corrections, and interruptions

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

Stage 2: Summarize long timelines (only if needed)

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

Stage 3: Extract per-session tool-call facets

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

Stage 4: Aggregate and analyze

阶段4：聚合与分析

Stage 5: Propose instruction updates (project + global)

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

Stage 6: Deliverables

阶段6：交付物

References

参考资料

Stage 1: Collect evidence with
`ccbox`

阶段1：使用
`ccbox`
收集证据