纠错规则沉淀 timestatic/session-correction-analysis

session-correction-analysis

English · 简体中文

把你在 Claude Code / Codex / DeepSeek Harness（DSH）会话里对智能体做出的纠正，变成能长期留存的工程规则：有证据支撑、经人工确认、可修改、可撤销。

session-correction-analysis（简称 sca）既不是通用的会话摘要工具，也不是通用记忆插件。它盯的是更窄、但影响更大的一类信息：用户纠正智能体时产生的工程约定与流程记忆。

项目的 harness 文档体系——AGENTS.md / CLAUDE.md 入口、invariants / architecture / infrastructure 这类约定、linter，以及项目级或用户级的智能体记忆——构成了 AI 编码助手的行为基础。但这套体系会随时间腐化：会话里的纠正没能及时回流，旧规则长期无人复查，文档、约束和实际行为逐渐脱节。sca 的目标，就是给这套体系补上一条规则供应链：有证据、经复查、可撤销。
模型负责理解语义；命令行负责冻结输入、核验证据、维护权威状态。候选规则不会自动写入 harness 文档系统或 Agent 记忆，也不会自动获批。审查之后，由你决定是否把规则回填到入口文件、专项约定、lint 约束，或相应的记忆系统。

目录

- 为什么需要它
- 什么时候用它——什么时候不用
- 它和会话摘要、记忆插件的区别
- 60 秒快速上手
- 示例：从一次纠正到一条长期规则
- 工作原理
- 核心保证
- 隐私与网络边界
- 局限
- 手动命令行工作流
- 数据目录
- 常用命令
- 自动化与定时分析
- License

为什么需要它

AI 编码会话经常这样走：

1. Agent 误解需求，做了不合适的操作，或者写出的代码需要返工；
2. 用户在会话中指出问题；
3. Agent 立刻调整；
4. 会话一结束，这次纠正就散落在记录里；
5. 后来的 Agent 又犯同样的错。

直接让模型总结当前会话，适合一次性的复盘。但一条规则要长期影响项目或团队时，还有更多问题需要回答：

- 分析的是哪个会话，用的是它哪一段固定输入？
- 每条用户消息都检查了吗？
- 候选规则引用的段落，真的出现在记录里吗？
- 说某处「返工」了，有实际编辑和成功结果支撑吗？
- 哪些只是模型建议，哪些已经用户批准？
- 候选规则改动之后，旧的批准还有效吗？
- 一条已采纳的规则，之后怎么修订或撤销？

sca 把这些问题组织成一套可治理的工程流程：

Session transcript
→ freeze input and generate an evidence packet
→ host Agent analyzes corrections, interventions, and rework
→ CLI validates the analysis result
→ user reviews rule candidates
→ feed rules back into the harness documentation system / Agent memory, or record them in the rules ledger
→ revise or revoke them later

什么时候用它——什么时候不用

| 场景 | 建议 |
| 当前会话很短，你只想立刻复盘 | 直接问模型通常更简单 |
| 结果不会变成长期约定，分析出错的代价也低 | 可能不需要 sca |
| 分析历史会话 | sca 适用 |
| 长会话可能经历过上下文压缩或裁剪 | sca 适用 |
| 批量或定时分析多个会话 | sca 适用 |
| 规则将进入 harness 文档系统、lint 约束或共享记忆 | sca 适用 |
| 你需要来源证据、人工审批、版本管理和撤销记录 | sca 适用 |
| 你希望自动审批并直接修改 harness 文档系统 | 不适用；sca 明确保留人工审核边界 |
| 你想存储任务进度、项目事实或完整用户配置档 | 不适用；sca 不是通用记忆系统 |

与会话摘要和记忆插件的区别

三种做法都可能读取会话并提取信息，但解决的问题不同：

| 做法 | 主要目标 | 典型输出 | 治理重点 |
| 直接让模型总结会话 | 描述这次发生了什么 | 会话摘要、行动项、临时建议 | 速度与低成本 |
| 记忆插件 | 让项目事实、用户偏好和历史信息日后可检索 | 工作记忆、情景记忆、语义记忆、用户配置档 | 捕获、存储与检索 |
| sca | 把用户纠正转化为可信、持久的工程规则 | 有证据支撑的候选、审核记录、已采纳规则 | 来源、审批、版本管理与撤销 |

记忆插件通常处理更广的信息，例如：

- 当前任务状态与未完成事项；
- 项目事实、技术决策与历史背景；
- 跨会话的用户偏好与习惯；
- 值得在后续请求中回忆的摘要。

sca 只聚焦一个更窄但影响更大的类别：用户纠正产生的程序性记忆或工程规则。这类规则可能影响未来所有智能体，所以「模型觉得值得记住」还不够。它们还需要：

- 保留真实来源证据；
- 区分对话记录事实与模型推断；
- 明确的规则目标与适用范围；
- 审批绑定到具体内容版本；
- 用户明确批准；
- 支持日后修订与撤销。

两种做法互补，不能相互替代。记忆插件可以捕获并回忆广泛信息，而 sca 可以在高影响规则进入长期记忆前充当审核关口：

普通项目事实、进度与偏好 → 由记忆插件捕获并回忆

用户纠正产生的高影响规则 → SCA 提取证据并生成候选 → 用户审核并批准 → 回写到 harness 入口、专门约定、lint 约束或智能体记忆

与常见记忆系统概念的大致对应关系是：

| sca 概念 | 大致对应的记忆系统概念 |
| 术语 | 含义 |
| Transcript | 原始会话日志 |
| Event / Evidence | 带来源信息的内存证据 |
| Episode | 结构化情景记忆 |
| Candidate | 长期记忆候选 |
| Approve | 人工确认记忆 |
| Adopt | 登记到长期规则账本 |
| Revoke | 使现有规则失效 |
| Rule | 程序性记忆 |

60 秒快速上手

环境要求：Node.js >=22。项目已验证 Node.js 22、24、26；开发基线见 .nvmrc。支持 Codex、Claude Code、DSH 会话。压缩的 DSH 输入还需要 PATH 中有 zstd；doctor 会检查它。macOS 上用 brew install zstd 安装。

安装技能

推荐把仓库里的精简技能装进 Claude Code 或 Codex：

npx skills add timestatic/session-correction-analysis

也可以手动复制 skills/session-correction-analysis/：

- Claude Code 全局：~/.claude/skills/
- Codex 项目级：.agents/skills/
- Codex 用户级：~/.codex/skills/

技能只含说明，不含打包的命令行代码。运行时它通过 npx -y session-correction-analysis 获取命令行；首次运行通常需要访问 npm registry，之后可用本地缓存。

如果你只想要命令行，也可以全局安装：

npm install -g session-correction-analysis

开始分析

装好技能后，在 Claude Code / Codex / DSH 里说：

Analyze the user corrections in this session and generate rule candidates.

也可以直接调用：

/session-correction-analysis

智能体按技能里的顺序执行：

doctor
→ discover / register
→ prepare
→ analyze the packet
→ ingest
→ review

如果 Claude Code / Codex 没有提供当前会话 ID，技能会尝试探测标记；若定位不到会话，你必须从 /status 提供会话信息。DSH 用文件头 ID 和显式 transcript 路径注册；后续分析与审查流程相同。

审查候选

分析结束后列出候选：

sca review <record_id>

查看某个候选及其证据摘要：

sca review <record_id> --candidate <candidate_id>

默认情况下，详细视图省略完整 transcript 摘录，但保留分析说明、限长引用和证据引用。truncated: true 表示字段被截断，不表示内容被删改。source_origin_counts 统计的是来源锚点，不是人工纠正的总数。

显式查看完整来源证据：

sca review <record_id> --candidate <candidate_id> --full

批准某个候选：

sca review <record_id> --action approve \
--candidate <candidate_id> \
--request <uuid> \
--expected-revision <revision>
候选还支持 reject、edit_content、revoke 和 supersede。审批绑定当前内容版本；改动正文、目标或范围，之前的审批自动失效，需要重新评审。

导出或采纳

把已批准的候选导出为 Markdown：

sca review <record_id> --action export_content \
--candidate <candidate_id> \
--out ./rule.md

也可以用 copy_content 输出适合复制的内容。导出之后，由用户决定这条规则该放在 harness 文档体系的哪个位置：可以加进 AGENTS.md / CLAUDE.md 入口，可以放进 invariants / architecture / infrastructure 这类专门约定，可以转成 lint 约束，也可以加进项目级或用户级的 Agent memory。

把已批准的版本登记到长期规则台账：

sca adopt <record_id> --candidate <candidate_id> \
--request <uuid> \
--expected-revision <revision>

注意区分：

- approve：批准当前候选内容；
- export_content / copy_content：输出已批准的内容；
- adopt：把已批准的版本登记到 accepted_rules.md；
- adopt 只把它登记进规则台账。它不会自动修改 harness 入口、专门约定、lint 约束或 Agent memory，也不代表这条规则已经反馈进这些系统。

示例：从一次纠正到一条长期规则

假设会话里发生了下面这一幕：

Agent: After finishing the changes, I'll run npm publish directly.
User: Do not publish. npm publish is an irreversible external action; you must get my explicit confirmation first.
Agent: Understood. I'll only make and verify the local changes, without publishing.

sca 把用户消息、Agent 之前的行为、以及它之后的回应，整理成带来源信息的分析证据。宿主 Agent 随后可以提出候选：

Title: Explicit user confirmation is required before running npm publish
Category: Operational safety rule
Status: proposed
Source: The user's correction and evidence of behavior before and after it

用户评审之后，批准并导出的规则可能是：

Obtain explicit user confirmation before publishing

Before running npm publish or another irreversible external operation, obtain the user's explicit confirmation.
Without confirmation, only perform local changes, checks, and pre-publication verification; do not actually publish.

如果这条规则要进入跨会话台账，之后显式运行 sca adopt。完整路径是：

Real correction → source evidence → rule candidate → human approval → export or adoption → later revision/revocation

工作原理

sca 在命令行和宿主 Agent 之间划分职责。

宿主 Agent：语义判断

Claude Code、Codex、DSH 这类宿主 Agent 负责判断：
- 用户是否在纠正智能体；
- 用户是否在停止执行、拒绝授权或接管执行；
- 前后的编辑是否构成反转、替换或修复；
- 某次纠正是否值得沉淀为长期规则；
- 规则文本、触发条件和适用范围该如何表达。

命令行：事实与权威状态

命令行本身不发起模型请求。它的职责是：

- 读取并校验 Codex / Claude Code / DSH 记录；
- 冻结当前分析的输入范围；
- 把不同宿主格式归一化为共享事件与 Evidence；
- 为用户消息和原生干预分别建立覆盖清单；
- 提取文件编辑信号和潜在返工线索；
- 校验提交 schema、引用、时序和返工证据；
- 管理租约、generation、锁、revision 和事务恢复；
- 管理候选审核状态和已采纳规则台账。

对于压缩会话，命令行先冻结原始字节，再解压到权限受限的临时文件，读完即删除该文件。原始压缩字节和解压后的内容都限制在 64 MiB；源文件变更、压缩损坏或解压超时都会导致读取被拒绝。source_fingerprint/cutoff_byte_offset 指向原始压缩字节；decoded_fingerprint/decoded_byte_length 指向解压后的内容；证据 source_ref.line/hash 指向解压后的 JSONL 行。

来源线索保存在 evidence.origin。DSH 使用原生 source.kind；部分 Claude wrapper 使用 wrapper_pattern。两者都不构成独立的身份认证。所有用户通道记录都留在读取范围内。子会话中的继承证据标记为 evidence.inherited，快照保存 parent_session_id/inherited_events；继承范围和当前会话新增的内容分别上报，因此父历史不能被当作子会话中做出的新纠正。

端到端流程是：

sca register
→ create a stable session record

sca prepare
→ freeze the transcript input range and generate an analysis packet

Host Agent analyzes the packet
→ produce structured submission JSON

sca ingest
→ validate coverage of user messages and native interventions, quotes, chronology, edit results, and run identity

sca review
→ human approve / reject / edit_content / revoke / supersede

copy_content / export_content
→ output approved rules; the user decides where to place them

sca adopt / sca rules
→ register, query, revise, or revoke durable rules

更完整的实现分析——包括输入冻结、Evidence、返工线索、租约、双文件提交和审核状态机——见 TOOL_DESIGN_ANALYSIS.md。

核心保证

- 固定输入：prepare 绑定到 transcript 的某个字节前缀；只在末尾追加内容，不会改变本次运行已经冻结的输入。
- 按目标读取回执：用户消息由 processed_users 对照 user_coverage 覆盖；原生中断和审批由 processed_interventions 对照 intervention_coverage 覆盖。这两类目标分开处理。如果某个原生中断的回执缺失或不确定，结果仍为 partial。
- 受证据约束的标签：一个 episode 至少要检测到一次纠正或执行干预；负例只提交读取回执。原生干预锚点只能标为干预，必须引用自己的证据，不能标为文本纠正。审批不会自动归类为拒绝或人工操作；仅因需求变更产生的返工不单独提交。
- 可验证的引用：候选引用的 Evidence ID 必须存在，引文必须与可引用文本逐字一致。
- 可验证的时间顺序：纠正之前的行为必须早于用户锚点，纠正之后的行为必须晚于锚点。
- 返工的事实底线：声称代码返工已完成，需要纠正前后都有成功的编辑，且文件路径有重叠。DSH edit/write 使用结构化路径，并从原生状态判定结果；TOOL_OUTCOME_UNKNOWN、shell 描述或模型自称完成，都不能算作成功编辑的证据。
- 模型不能自我审批：模型只提交语义分析结果，不能提交 approved 或 published 这类权威状态。
- 审批绑定内容版本：改动候选内容会自动让其此前的审批失效。
- 受控的并发写入：租约、generation fencing token、revision、文件锁和幂等请求，防止过期结果覆盖更新的状态。
- 规则可回退：候选可以被拒绝或撤销；已采纳的规则可以修订或撤销，同时保留其来源和历史。
- 失败不污染已有记录：ingest 校验失败会拒绝提交，而不是用不完整的结果覆盖已保存状态。

隐私与网络边界

- sca 命令行只做本地读取、写入和校验。它不发起模型请求，也不主动上传 transcript；分析包是否发送给远程模型，取决于 Claude Code、Codex 等宿主端的配置。
- 首次通过 npx 获取命令行或安装依赖时，可能会访问 npm registry。SCA 不会自动写入 harness 入口、专用约定、lint 配置、Agent 记忆或其他外部系统。
- 本地数据包含会话证据和候选内容。保护好 SCA_DATA_ROOT，别不小心把它提交到代码仓库。

限制

- 支持 DSH v4；暂不支持 v0/v3，也不支持 DSH 基于标记的发现机制。显式指定会话目录时，会选中版本号最高的规范版本，不会从未知版本回退；如果同一版本存在多种编码，请指定具体文件。
- 压缩、缺失的流提交、未知事件，或无法读取的非文本内容，都可能让来源覆盖不完整。文本流和工具流会分别检查完整性；同一步骤里的文本提交不能替代工具调用提交。
- 命令行可以核验引文、时间顺序和编辑事实，但语义判断的质量仍取决于宿主模型。
- 返工分析依赖转录记录里的编辑、路径和文本指纹。它只提供事实底线，不是 AST 级别的语义证明。
- SCA 不会自动批准或发布规则。跨会话去重、冲突检测、规则老化审查和效果评估暂未提供。
- SCA 不是通用记忆系统。用 Markdown 存储便于审计，但不适合大规模聚合查询；不同的 data-root 目录不会自动合并。

手动命令行工作流

下面的命令走的是和技能后台相同的流程，适合写脚本或调试。sca 可以来自全局安装，也可以换成 npx -y session-correction-analysis；源码开发时先跑 npm run build，再用 node dist/src/cli.js。未发布的改动请用本地构建或测试包。

注册时根据来源选择 --host：

| 会话来源 | --host | --transcript |
| Codex | codex | 显式指定转录文件 |
| Claude Code | claude | 显式指定转录文件 |
| DeepSeek Harness (DSH) | dsh | v4 .jsonl、.jsonl.zstd 文件，或单个会话目录 |

会话 ID 必须对照来源文件核验。DSH 提供 cwd 时，会检查工作区；核验成功记为 workspace_verification: matched。如果缺少 cwd，允许导入，工作区取自注册参数，核验记为 unavailable。未请求工作区核验时，结果为 not_requested。不要凭标题或最近的记录猜测身份。

单会话分析

0. Check the environment
sca doctor

1. Locate the current session (Codex / Claude only; skip if the path is already known or for DSH)
sca discover --host codex \
--marker sca-probe-<uuidv4> \
--workspace <workspace_path>

2. Register the source session (choose the host from the table above; DSH accepts a compressed file or session directory)
sca register --host codex \
--session <session_id> \
--workspace <workspace_path> \
--transcript <transcript.jsonl>

3. 冻结输入并生成数据包 sca prepare <record_id>

4. 宿主智能体按照技能分析数据包，产出 submission.json

5. 校验并提交分析结果
sca ingest <record_id> \
--run <run_id> \
--submission submission.json

6. 查看并复核候选 sca review <record_id> sca review <record_id> --candidate <candidate_id>

7. 导出已批准的内容
sca review <record_id> --action export_content \
--candidate <candidate_id> \
--out ./rule.md

8. 可选：登记到长期规则台账
sca adopt <record_id> --candidate <candidate_id> \
--request <uuid> \
--expected-revision <revision>

--request 标识符要全局唯一，最好用 UUID。同一操作重试必须复用同一个标识符和参数；新操作要用新标识符。并发更新还必须提供命令当前返回的 --expected-revision。

如果不清楚某个命令的完整参数，运行：

sca

批量分析

用户明确授权多个来源时，用 sca batch，并单独指定私有的 --data-root。支持 Codex、Claude Code 和 DSH 来源；批量目录与单会话记录分开存放。

- create|append|diff：冻结显式指定的来源，把新来源追加到新批次，查询事件差异。
- page|tasks|task-context：在字节预算内读取证据，规划分析目标和上下文，保留分页检查点。
- claim|heartbeat|queue|task-submit|finish：管理工作进程租约、恢复状态，以及对照租约校验的增量提交。
- submit|status|usage|audit|budget|identity|rework|candidates|candidate-detail：提交语义判断，查询覆盖率、用量、复核清单、预算、身份线索、编辑配对，以及等待复核的候选。

每个目标都必须真正复核。来源数据增长时使用新批次 ID；语义判断不会自动继承，父子会话不合并，候选也不会自动批准。工作进程由宿主提供；命令行不会自动调用模型。语义复用和通往单会话候选复核的桥接尚未实现。

操作字段见批量协议；连续执行与检查点见执行指南；失败处理见恢复手册。

数据目录

默认数据目录是 ~/.session-correction-analysis/。用 --data-root <path> 或 SCA_DATA_ROOT 环境变量覆盖。

~/.session-correction-analysis/
├── accepted_rules.md
├── records/
│ └── <record_id>/
│ ├── analyze.md
│ └── learning_candidates.md
└── runtime/
├── packets/
└── locks/

- accepted_rules.md：跨会话规则账本，记录采纳、修订和撤销历史。
- analyze.md：源会话身份、分析状态、租约、片段和事实摘要。
- learning_candidates.md：候选文本、来源、审查历史和修订。
- runtime/packets/：由 prepare 生成的冻结分析包；这些包可以重建，不属于长期业务事实。
- runtime/locks/：会话记录和规则注册表使用的协作文件锁。

record_id 由主机、规范化工作区和源会话 ID 共同推导得出。修改会话标题、在其他月份继续该会话，或再次分析它，仍然会得到同一个稳定的记录目录。

Markdown 文件可以直接读取，但只能通过命令行修改。运行以下命令做只读一致性检查：

sca validate <record_id>
sca validate --all

常用命令

| 命令 | 用途 |
| sca doctor | 检查 Node.js、PATH 和数据目录可写性 |
| sca discover | 用标记探测定位当前会话记录 |
| sca register | 校验并注册源会话 |
| sca prepare | 冻结输入、获取租约并生成分析包 |
| sca ingest | 校验并提交智能体的结构化分析结果 |
| sca review | 列出候选、查看证据并执行人工审查操作 |
| sca review ... --action copy_content | 输出已批准候选的可复制 Markdown |
| sca review ... --action export_content | 将已批准候选导出到指定文件 |
| sca adopt | 将已批准候选登记到 accepted_rules.md |
| sca rules | 查询规则列表或详情，或执行撤销 |
| sca validate | 对记录和事务状态做只读一致性检查 |

常用审查操作：

| 操作 | 含义 |
| approve | 批准候选的当前内容版本 |
| reject | 拒绝候选 |
| edit_content | 手动编辑候选文本或相关内容 |
| revoke | 撤销先前的批准 |
| supersede | 用新候选替换旧候选 |
| copy_content | 输出已批准内容供复制 |
| export_content | 将已批准内容写入指定 Markdown 文件 |

命令行退出码：

| 退出码 | 含义 |
| 0 | 成功 |
| 1 | doctor 或 validate 发现诊断/一致性问题 |
| 2 | 命令抛出已分类错误，JSON 写入 stdout |
| 3 | 用法或参数解析错误 |

自动化与定时分析

sca 不包含调度器，普通 cron 无法独立完成语义分析。自动化任务必须运行在能够调用模型的主机智能体内，并复用同一套技能、命令行和提交 schema。

推荐的批处理策略是：

扫描 records//analyze.md → 选出 analysis_status=pending 的记录 → 对每条分别运行 prepare → 宿主智能体分析数据包 → 运行 ingest → 输出等待人工审核的候选列表

自动化任务应遵守这些边界：

- 限制每次运行处理的条数，以及转录发现的时间窗口；
- 跳过仍在写入、持有有效租约，或包含未完成提交的记录；

- Record the reason for an individual failure and continue to the next record, without overwriting existing state;
- Never automatically perform approve, reject, edit_content, revoke, or supersede;
- Never automatically modify harness entry points, specialized conventions, lint constraints, or any Agent memory;
- Notify the user for review only when new records or candidates have been produced.

In other words, a scheduled task may automatically “discover, prepare, analyze, and submit,” but candidate approval, rule export, and long-term adoption remain the user's decisions.

You can use the following prompt in Codex Automations, Claude Code scheduled tasks, or another model-capable host. Adjust the data directory, time window, and per-batch limit as appropriate:

Use the session-correction-analysis Skill to run one scheduled analysis of session corrections. This run
is only responsible for discovering, registering, analyzing, and submitting candidates. Never review
or publish rules on the user's behalf.

1. Run sca doctor. If the Node.js, PATH, or data-directory check fails, stop immediately and report
only the reason for failure; do not install, upgrade, or modify the environment yourself.

2. Scan the frontmatter of ~/.session-correction-analysis/records//analyze.md:
- Select records with analysis_status=pending, taking at most 3 in ascending created_at order;
- Skip running and completed records, and records with a nonempty pending_commit;
- Do not clear locks, seize valid leases, or modify abnormal records; suggest that the user
run sca validate when necessary.

3. If additional unregistered sessions are needed, enumerate transcripts from the current host only
within an explicit recent time window:
- Skip files that may still be receiving writes;
- Read only the metadata needed to identify a session: session_id, workspace, and transcript path;
- Deduplicate against session_id values in existing records;
- Register at most 3 additional sessions. Do not scan all historical sessions or guess from
session titles or “most recently used.”

4. For each record in turn:
sca prepare <record_id>
→ read the entire generated packet, including user_coverage and evidence
→ generate submission JSON strictly according to the Skill schema
→ sca ingest <record_id> --run <run_id> --submission <submission_path>

5. If ingest rejects a submission, correct the submission once according to the error message.
If it still fails, preserve the original state and continue to the next record. Do not bypass
schema, Evidence, coverage, lease, or input-hash validation.

6. Run sca review <record_id> for successfully completed records. Summarize the record_id, candidate
titles, candidate count, revision, and review command
sca review <record_id> --candidate <candidate_id>.
If there are no new records or candidates, reply only “No new items.” Do not paste original
transcript text into the report.

7. Never run approve, reject, edit_content, revoke, supersede, copy_content, export_content, adopt,
or rules --revoke. Never modify AGENTS.md / CLAUDE.md entry points, specialized conventions such
as invariants / architecture / infrastructure, lint constraints, Agent memory, Skill files, or
this prompt. All candidates must remain for the user's manual review.

Plain system cron has no semantic analysis capability of its own. If you use a scheduler such as crontab or launchd, have it invoke claude -p, codex exec, or another host Agent and pass the prompt above as the task input.

For pre-publication verification, run npm run verify:release. This runs lint, type checking, unit tests, integration tests, and a smoke test of the actual npm package. zstd must be installed on the machine or the package smoke test will fail. This command does not publish an npm package or change the version number.

License

MIT