规则核心库：AI系统的认知框架

摘要
AI编程智能体（如 Cline）正被赋予对文件系统、外部 API 和开发环境的自主操作权，但自主性的提升伴随着系统级的可靠性危机：缓存与物理文件漂移导致幻觉输出，工具空结果无限重试引发死循环挂起，跨会话推理链断裂造成认知失忆，上下文窗口溢出致使任务中途崩溃。这些瞬态与稳态故障使智能体频繁陷入反复重试、状态错乱和资源浪费，严重削弱了 IDE 级自动化开发工具的工程价值。

本文提出“规则核心库”——一个为 Cline 类智能体量身打造的形式化、可执行操作系统内核。其设计围绕三条认知状态公理构建：内部一致性（operationLog 杜绝悬挂操作）、外部一致性（SyncGuard 强制缓存与物理文件同步）、历史完整性（CompactProcedure 持久化推理链）。通过 StateManager 统一治理会话状态变量，ConfigInjection 与 ConflictResolution 元机制确保参数优先级与规则裁决的确定性。规则体系严格分层为公理（不可变逻辑）、策略（决策选择）、规范（约束边界）、反模式（错误知识库）和流程（可执行步骤），实现“决策”与“执行”的彻底解耦，将原本依赖 LLM 内省的启发式试探升级为可验证、可恢复的系统工程。

针对 Cline 日常开发场景（文件读写、编译诊断、代码搜索、模块重构），该规则库带来五大可量化性能提升：

输入 Token 成本直降 40%~55%：IdempotencyGuard 结合文件哈希与操作标识，将冗余文件 I/O 减少 60%~75%，避免重复读取与重复工具调用。

无限重试挂起事件降低 95% 以上：OnError 区分首次空结果（瞬态，零成本重试一次）与重复空结果（稳态，三阈值强制熔断），单次故障恢复时间从约 120 秒压缩至 15 秒内。

上下文溢出崩溃率降低 80%：CompactDecision 在上下文水位超 85% 时触发紧急纯文本转储（≤500 字符），ReadStrategy 对大文件分段索引按需检索，窗口利用率从 ~30% 提升至 80%。

决策路径延迟压缩 90%：将“选工具”“定策略”转化为确定性查表（[CM]/[CD]），每轮决策从 ~200ms 降至 <10ms，大幅减少 API 往返。

状态恢复二次循环轮次减少 70%：StateRecovery 写入恢复标记阻断“恢复→检查→再恢复”死锁，平均恢复耗时从 45 秒降至 15 秒。

综合端到端指标：多文件批处理任务耗时缩短 50%~65%，单次编译修复循环 API 调用次数从 12~18 次降至 5~8 次（减少 ~55%），长会话（100+ 轮）任务崩溃率从约 40% 降至 <8%，月度 LLM 调用费用预估节省 35%~50%。该规则核心库为 Cline 等自主智能体提供了一部“认知宪法”和一套“操作规范”，使自动化开发从高风险实验走向高可靠工程实践。

规则核心库

〇、元规则（Meta-rules）

RuleMetaModel

规则分类层级

公式类型定义

StateManager [元机制]

会话级状态变量的统一管理入口。所有规则通过 StateManager 读写状态，不直接操作状态变量。

• 状态一致性：遵循 StateSnapshot、StateMerge、StateIsolation 公理。在 @parallel 场景下，并行步骤使用独立的状态快照，执行完成后按工具链顺序合并回主状态。
• 初始化钩子：skipExternalConsistency 和 skipHistoricalIntegrity 标志由 StateManager 的初始化钩子自动管理，LLM 代码不可手动修改。
  • 触发条件：当 fileCache = ∅ 或 forceHalt = true 时，系统底层自动置位这两个标志。
  • 清除条件：首次 StateValidity 评估完成后，系统底层自动清除这两个标志。

ConfigInjection [元机制]

参数来源优先级：运行时参数 > 项目配置（→ project.md）> 环境变量（→ env:VAR）> 默认值（→ default:val）

参数缺失处理：按 project.md 定义的降级策略处理（必需参数缺失→规则降级，可选参数缺失或类型不匹配→使用默认值）。

ConflictResolution [元规则]

同层规则冲突时，按以下优先级裁决：① 参数来源优先级（由 ConfigInjection 定义）→ ② 规则特异性（更具体的规则优先于通用规则）→ ③ 时间顺序（后定义的规则覆盖先定义的规则）。跨层优先级由 RuleMetaModel 的层级定义隐含保证：公理 > 规范 > 策略 > 流程 > 反模式。

一、公理（Axioms）

认知状态元公理

StateValidity(cognitiveState, worldState) [QA]

Provides: stateValidity评估结果（valid/invalid/degraded）

认知状态有效性（三定律联合评估）。
InternalConsistency ∧ ExternalConsistency ∧ HistoricalIntegrity → valid · ¬InternalConsistency → invalid · InternalConsistency ∧ (ExternalConsistency ⊕ HistoricalIntegrity) → degraded · otherwise → invalid

• InternalConsistency=false 时直接判定为 invalid（对应 StateRecovery 的 full_reset），不进入 degraded 路径。
• 三定律：
  • InternalConsistency：¬∃partialOperation → true。真值由 operationLog 提供。
  • ExternalConsistency：∀f∈fileCache : f.timestamp ≥ f.lastModifiedTime → true。真值由 SyncGuard.sync_check 的物理校验结果提供，结果写入 StateManager.externalConsistency。
  • HistoricalIntegrity：∀phase∈completed : phase.reasoningTrace ≠ ∅ → true。真值由 CompactProcedure.persist_reasoning 的执行记录提供。
• 评估前置条件：调用 StateValidity 前应先通过 SyncGuard.sync_check 刷新 fileCache（fileCache 非空时）。若 sync_check 不可用，评估结果应标注 ExternalConsistency 维度的可信度。
• 空状态处理：当 fileCache = ∅（系统首次启动或空状态）时，由 StateManager 初始化钩子自动置位 skipExternalConsistency 和 skipHistoricalIntegrity 标志，跳过 ExternalConsistency 和 HistoricalIntegrity 两个维度的评估，仅评估 InternalConsistency。详见 StateManager 初始化钩子。

状态一致性公理

StateSnapshot [AX]

∀op∈Operations : op.readsFrom(snapshot) → op.result.deterministic

• 每个操作应基于一致的状态快照执行。同一快照下的重复操作应产生相同结果。
• @parallel 场景：并行步骤各自持有独立快照，互不干扰。

StateMerge [AX]

∀merge∈Merges : merge.conflictFree → merge.result.consistent

• 状态合并应保持一致性。当多个操作的结果需要合并时，后完成的写入不应覆盖先完成的写入所依赖的读取值。
• 冲突处理：合并时若检测到冲突，以先完成的步骤为准，后完成的步骤回退并重试。

StateIsolation [AX]

∀op₁,op₂∈Parallel : op₁.snapshot ∩ op₂.snapshot = ∅ → op₁∥op₂

• 并行操作应隔离执行。当两个并行步骤访问不同的状态变量时，可安全并发。访问同一状态变量时，应序列化执行。

空值元公理

NullExistence [AX]

∀x ∈ SystemState : x = null → LegalInitialState

• 系统首次启动时各组件处于空状态是预期行为。空集合是合法的中间状态。

ToolDeterminism [AX]

∀T, params, state : T(params, state) = T(params, state)

• 若两次调用同一工具+相同参数得到不同结果，说明系统状态已变化。此公理是幂等性检查和空结果熔断的理论基础。

NullResultLegitimacy [AX]

∀T, params : T(params) = ∅ → LegalOutput

• 空结果与错误有本质区别：空结果是合法输出，错误是异常状态。
• 瞬态空结果：首次调用返回空（callCount=0），根据 FirstCallTransient 公理，应重试一次（不递增 emptyCount）。详见 OnError 策略①.5分支。
• 稳态空结果：重试后仍返回空（callCount≥1），根据 RepeatedCallStable 公理，触发熔断逻辑。详见 OnError 策略②分支。
• 连续空结果的熔断处理由 OnError 策略定义。

瞬态与稳态公理

FirstCallTransient [AX]

∀x∈SystemState : callCount(x)=0 → x.mayBeTransient

• 首次观测到的状态可能是瞬态的（如网络抖动导致的空结果），应重试一次以排除瞬态因素。
• callCount 由 StateManager.callCount 维护，执行体在每次工具调用后递增对应 CallKey 的计数。

RepeatedCallStable [AX]

∀x∈SystemState : callCount(x)≥1 → x.isStable

• 重复观测到的状态是稳态的。重试后仍返回相同结果，说明该状态是稳定的，应触发正常处理逻辑。

TransientRetryNoCost [AX]

∀x∈SystemState : x.mayBeTransient → retry(x).cost = 0

• 瞬态重试不产生错误计数。首次空结果的重试不递增 emptyCount 或 retryCounter。
• cost=0 的含义：不递增 retryCounter、emptyCount、callCount 中的任何错误相关计数器。

二、策略（Strategies）

工具策略

DeprecateStrategy(D, hasReference) [CD] Provides: 废弃决策（cannot_delete/can_delete/no_action）

D ∧ hasReference → cannot_delete · D ∧ ¬hasReference → can_delete · ¬D → no_action

AmbiguityStrategy(semantics, phase) [CD] Provides: 歧义处理决策（extract_to_shared_config/use_alias/remove_alias）

same → extract_to_shared_config · different ∧ transition → use_alias · different ∧ migration_done → remove_alias

ReferenceStrategy(depA→B, depB→A) [CD] Provides: 循环引用检测结果（true/false）

depA→B ∧ depB→A → true · otherwise → false

RefactorStrategy(error) [CD] Provides: 重构优先级决策（refactor_first/normal_priority）

error ∈ RefactorScope → refactor_first · otherwise → normal_priority · RefactorScope = {模块迁移, 接口变更, 架构级改动}

ConflictStrategy(hasReference, isFirstTime, deprecationConfig) [CD] 处理决策（delete/firstTimeAction/retryAction）

¬hasReference → delete · hasReference ∧ isFirstTime → deprecationConfig.firstTimeAction · hasReference ∧ ¬isFirstTime → deprecationConfig.retryAction

ToolStrategy [CM] Provides: 工具选择决策（{tools, timeout, mode} 三元组）

• ToolPriority(toolType)：available(external) → external · ¬available(external) ∧ available(builtin) → builtin · otherwise → cli
• ToolSelect(taskType)：∈{file_io} → direct_file_ops · ∈{analysis,processing} → sandbox_processing · ∈{reasoning,decomposition} → structured_reasoning · ∈{batch,multi_query} → batch_processing · otherwise → builtin
• Toolchain(scene)：scene → guidesSceneMap[scene]（查表模式）。@parallel 标注表示该步骤可并发执行。新增场景只需在 guides.md 映射表中添加条目。
• Toolchain fallback：若 guidesSceneMap[scene] 未定义，回退到 ToolSelect 分类路径（ToolSelect(taskType)），由 ToolSelect 根据任务类型选择工具。若 ToolSelect 也未匹配，使用 builtin 兜底。

OnError(error, stepIndex, toolchain) [CD]

Provides: 错误处理决策（retry/switch_strategy/halt/continue/skip_remaining/forcehalt）

工具链错误处理策略。空结果（∅）与错误（exception）共用同一套熔断机制。输出纯决策值，不含流程动作（动作由 ErrorHandler 执行）。内部查询 StateManager.callCount 和 StateManager.emptyCount 获取调用计数和空结果计数。

① forceHalt=true? → true: forcehalt | false: 进入①.5
①.5 瞬态重试?（依据 NullResultLegitimacy 公理——首次空结果重试一次，不递增 emptyCount）
├─ result=∅ ∧ callCount(T, params)=0 → retry
└─ 否则 → 进入②
② 重试/空结果熔断?
├─ retryCounter ≥ 3 ∨ emptyCount(T) ≥ 3 → forcehalt
├─ emptyCount(T, params) ≥ 2 → switch_strategy
├─ result=∅ ∧ callCount(T, params)≥1 → switch_strategy
└─ 均不满足 → 进入③
③ 错误分类处理:
├─ error∈{timeout, execution_failure} ∧ stepIndex<len(toolchain) → halt+persist
├─ error∈{partial_output, warning} → continue
├─ error∈{resource_exhausted} → skip_remaining
└─ error∈{irrecoverable} → halt

• 计数器递增：error ∈ {execution_failure, compilation_error} 时 retryCounter += 1（在①的 false 分支之后、进入②之前执行）。入口处 forceHalt=true 时跳过所有计数器递增。
• forceHalt 通知机制：forceHalt=true 状态在连续 N 轮 OnError 调用（N=5）无新错误触发后，向用户报告当前熔断状态并请求确认是否清除 forceHalt 标志。用户确认前 forceHalt 保持有效。StateRecovery 是主动恢复的唯一路径。
• 空结果熔断：emptyCount 是工具连续返回空结果的计数器，分两个粒度——emptyCount(T)（不限参数）和 emptyCount(T, params)（特定参数）。两者共享同一套熔断模式：超过阈值（T≥3 或 T+params≥2）触发 forcehalt 或 switch_strategy。emptyCount 与 retryCounter 独立计数但共享 forceHalt 标志。
• emptyCount 与 switchCounter 联动：当工具 T 返回非空结果时，emptyCount(T) 重置为 0（工具能返回非空结果说明该工具本身正常，无需保留历史错误痕迹）；emptyCount(T, params) 同样重置为 0。当 switch_strategy 被触发时 switchCounter += 1，且 emptyCount(T, params) 重置为 0（策略切换意味着参数已变更）。switchCounter ≥ 3 时后续 switch_strategy 输出降级为 forcehalt，防止无限策略切换循环。注意：switchCounter 仅在 switch_strategy 输出时递增，不因工具返回非空结果而重置，确保防循环机制不受参数变更后非空结果的影响。
• switchCounter 衰减：switchCounter 在阶段变更（phaseChanged=true）时减半（switchCounter = floor(switchCounter × 0.5)），保留防循环所需的累积信息而非完全清零。连续 N 轮（N=10）无 switch_strategy 触发时，switchCounter 减 1（不低于 0），避免早期环境问题导致的计数器累积在系统稳定运行后仍持续影响。注意：衰减仅降低 switchCounter 的数值，不改变其防循环语义——当 switch_strategy 再次触发时，switchCounter 仍从衰减后的值继续递增，switchCounter ≥ 3 的 forcehalt 降级阈值不变。

KnowledgeDedup(entity, kb) [CD] Provides: 去重检查结果（skip/record）

hash(entity.name + entity.content) ∈ kb.hashes → skip · otherwise → record + kb.hashes.add(hash)

• 备策略：当 kb.hashes 未初始化时，先 search(entity.name) 检查同名实体。存在则 add_observations，不存在则 record。

PathStrategy(execEnv, projectConfig) [CM] Provides: 路径格式映射

execEnv → projectConfig.path.format[execEnv] · execEnv∈{direct_api, cli, sandbox}

• 通用路径原则：① 绝对路径原则 ② 禁止 cd ③ 兜底策略：路径解析失败时尝试 projectConfig.path.root ④ 沙箱转义：sandbox 路径使用 \\\\ 或 /

上下文策略

CB(actionType) [CM] Provides: 上下文预算模式

file_read→partial_read · code_execution→summary_only · batch_operation→batch_with_queries · doc_web→index_no_content

BudgetAlloc(phase) [CC]

P_plan→较多预算用于信息收集 · P_exec_prep→中等预算用于结构分析 · P_exec_core→最大预算用于编码实现 · P_exec_verify→少量预算用于验证 · P_complete→不分配预算

PD(phase) [CM] Provides: 阶段定义

P_plan→(规划,{需求分析,方案设计,信息收集}) · P_exec_prep→(执行-准备,{文件读取,代码理解,结构分析}) · P_exec_core→(执行-核心,{编码,修改,重构,配置变更}) · P_exec_verify→(执行-验证,{构建,测试,审查,验证}) · P_complete→(完成,{attempt_completion})

StateRecovery(stateValidity) [SM]

invalid → full_reset · degraded → targeted_recovery · valid → no_action

• 死锁消除：统一为 full_reset，消除 persistenceFileStatus 状态依赖。推理链持久化文件在 full_reset 中被清空并写入恢复标记，因为原内容基于已失效的运行时状态，保留可能导致恢复后推理链与重建状态不一致。
• full_reset：① 清空运行时缓存（operationLog、fileCache）→ ② 清空推理链持久化文件并写入恢复标记（标记格式：# FULL_RESET at {timestamp}）→ ③ 重新扫描文件系统建立 fileCache → ④ 向用户报告状态已重置，请求确认 → ⑤ 用户确认后继续
• 进度标记不受影响：full_reset 不清除 task_progress（由外部系统维护）。
• 恢复后首次 StateValidity：full_reset 完成后首次 StateValidity 检查由 StateManager 初始化钩子自动跳过 ExternalConsistency 和 HistoricalIntegrity 两个维度（fileCache 刚重建，推理链持久化文件仅含恢复标记），仅评估 InternalConsistency。详见 StateManager 初始化钩子。
• 二次恢复防护：推理链持久化文件中的恢复标记（# FULL_RESET at {timestamp}）在 full_reset 步骤②写入后，CompactProcedure 的 persist_reasoning 将其作为当前阶段的推理记录写入推理链。后续 StateValidity 检查 HistoricalIntegrity 时，该记录满足 phase.reasoningTrace ≠ ∅ 条件，不会因推理链文件为空而误判为 degraded/invalid，从根本上消除二次恢复循环风险。
• targeted_recovery：① 识别 degraded 的具体维度 → ② 仅恢复对应维度 → ③ 向用户报告部分状态已刷新
• 任何压缩操作前必须先执行 StateValidity 检查，invalid 状态不压缩先恢复。

CompactDecision(phaseChanged, moduleDone, ctx_critical, stateValidity) [CD] Provides: 压缩类型决策（none/phase_compact/module_compact/emergency_dump）

ctx_critical → emergency_dump · phaseChanged → phase_compact · moduleDone ∧ ¬phaseChanged → module_compact · otherwise → no_action

• 优先级：ctx_critical > phaseChanged（上下文截断风险 > 阶段压缩收益）。
• ctx_critical 由系统信号触发（任一满足即为 true）：上下文水位警告（>85%）、文件重读需求、输出截断检测。不依赖 AI 内省。

Background(taskType) [CM] Provides: 后台运行判断

taskType∈{dev_server,watcher,daemon}→true · otherwise→false

MergeServerRequest(hasServer, hasRequest) [CD] Provides: 合并决策（merge_in_one_call/separate）

hasServer∧hasRequest→merge_in_one_call · otherwise→separate

CohesionLowStrategy(methods, context) [CD]

methods > 40 → suggest_refactor + request_confirmation · 30 < methods ≤ 40 → record_as_intent + keep_structure · methods ≤ 30 → no_action

• 上帝类（methods > 40）→ 建议解耦；聚合类（30 < methods ≤ 40，安全缓冲带）→ 不触发解耦，记录意图；正常范围（methods ≤ 30）→ 不处理。
• 隐式聚合与无法区分场景：当 context 显示功能分散但无统一入口时，即使 methods ≤ 40，也输出 suggest_convergence + request_confirmation；当类型无法区分时，默认按聚合类处理（record_as_intent + keep_structure）。
• 阈值关系：CohesionCheck 的 Low 阈值（methods>30）是"触发进一步评估"的门槛，本策略的 god_class 阈值（40+）是"触发重构"的门槛。30<methods≤40 的区间为安全缓冲带，判定为 aggregate 不触发重构。

读取策略

ReadStrategy(S, filePath, projectConfig) [CD] Provides: 读取档位决策（direct/process/process_segmented）

S < SMALL → direct · SMALL ≤ S ≤ LARGE → process · S > LARGE → process_segmented

• 三档说明：direct=轻量预览，process=全量加载（摘要进对话），process_segmented=分段索引（按需检索）。
• 读取完成后更新 fileCache：按 StateManager 规范更新。
• degraded 状态处理：当 StateValidity 输出 degraded 时（InternalConsistency=true 且 ExternalConsistency=false），优先选择 direct 或 process 模式并强制重新读取（跳过 fileCache），读取完成后更新 fileCache 为后续恢复提供基础。若 StateValidity 输出 invalid（InternalConsistency=false），应先执行 StateRecovery 而非继续读取。

IdempotencyCheck(current, last, currentFileHash, lastFileHash) [QA]Provides: 幂等性检查结果（skip/proceed/null_input）

current = null → null_input · current ≠ null ∧ last = null → proceed · current ≠ null ∧ last ≠ null ∧ current = last ∧ currentFileHash = lastFileHash → skip · otherwise → proceed

• 两维检查：操作标识 + 文件哈希都相同才 Skip。任一维度不同都重新执行。
• null 保护：current=null → 返回 null_input（不跳过也不执行，由调用方处理空输入场景）；current≠null ∧ last=null → 进入 proceed（首次执行）。
• 状态变量更新：执行完毕后通过 StateManager 更新 last = current 和 lastFileHash = currentFileHash。

InfoDomain(task, readStrategy, projectConfig) [CM] Provides: 信息域评估结果

single_file → (scope=single, type=code, complexity=readStrategy档位对应) · single_module → (scope=module, type=mixed, complexity=moderate) · cross_module → (scope=multiple, type=mixed, complexity=complex) · full_project → (scope=all, type=mixed, complexity=complex)

• 档位对应：complexity 由 ReadStrategy 的输出档位决定——direct→simple，process→moderate，process_segmented→complex。

CalculateCost(N, T_i, R_perOp, R_batch) [CC] Provides: 操作成本估算

Cost_sequential(N)=ΣT_i + N×R_perOp · Cost_batch(N)≈max(T_1,…,T_N)+R_batch · 推论：N>1∧T_i分布均匀→Cost_batch<Cost_sequential

三、规范（Standards）

错误处理规范

FailMode(errorType) [CM] Provides: 失败模式（FailFast/FailSafe/FailGraceful）

errorType∈{unrecoverable,precondition_violation}→FailFast · ∈{user_input,optional_feature}→FailSafe · ∈{non_core,third_party_timeout}→FailGraceful

ThrowRule(violationType, language, projectConfig) [CM] Provides: 异常类型映射

violationType → projectConfig.exceptions[violationType] · 新增语言只需在 project.md 中配置异常类型。

FixPriority(errorType, projectConfig) [CM] Provides: 修复优先级映射

errorType → projectConfig.fixPriority[errorType]

CodeStandard(code) [QA] Provides: 代码质量评估（pass/block）

¬emptyCatch ∧ ¬consoleLog ∧ ¬magicNumber ∧ ¬unusedImport ∧ ¬hardcodedPath ∧ ¬todoFIXME → pass · otherwise → block

• 项目可覆盖：各项目可在 project.md 中声明 AllowedCodeViolations。
• Warn 级（不阻断，仅注释建议）：预留抽象、注释替代命名、冗余注释/配置。

架构规范

SCA(condition) [CD] Provides: 服务聚合锚点判断

condition∈{external_dependency,dataflow_boundary,capability_exit,change_hotspot}→true · otherwise→false

VB(boundary) [CD] Provides: 边界验证结果（valid/invalid:multiple_responsibilities/invalid:incomplete_coverage）

single_responsibility∧complete_coverage→valid · ¬single_responsibility→invalid:multiple_responsibilities · single_responsibility∧¬complete_coverage→invalid:incomplete_coverage

CommunicationMode(syncMode, processBoundary, crossSystem) [CM] Provides: 通信方式（method_call/remote_call/event_delegate/message_queue/data_object）

sync ∧ same_process ∧ ¬crossSystem → method_call · sync ∧ ¬same_process ∧ ¬crossSystem → remote_call · async ∧ same_process ∧ ¬crossSystem → event_delegate · async ∧ ¬same_process ∧ ¬crossSystem → message_queue · crossSystem → data_object

• crossSystem=true 时无视 syncMode 和 processBoundary，统一输出 data_object。

CohesionCheck(scope) [CM] Provides: 内聚性评估结果（{rating, method_count, lines}）

methods≤30 ∧ lines≤1000 → {rating: "High", method_count: methods, lines}
methods>30 ∨ lines>1000 → {rating: "Low", method_count: methods, lines}

• CohesionCheck 输出 Low 时由 CohesionLowStrategy 进一步评估具体类型和处理策略。CohesionCheck 的 methods>30 阈值是"触发进一步评估"的门槛，具体类型判定（god_class/aggregate/normal）由 CohesionLowStrategy 统一处理。

输出规范

ShouldWrite(isRedundant, simpler, costExceedsValue) [CD] Provides: 写入决策（true/false）

isRedundant→false · simpler_exists→false · costExceedsValue→false · otherwise→true

OA(state, scope, recoverable) [CD] Provides: 输出动作（replace/rewrite/deprecate/delete）

modify∧local→replace · modify∧global→rewrite · deprecate∧recoverable→deprecate · deprecate∧¬recoverable→delete

四、反模式索引（Anti-pattern Index）

各反模式与对应规则的快速查找表。详细处理逻辑见对应规则定义。

五、操作流程（Procedures）

SyncGuard [SM]

步骤序列：

• 默认在工具链执行前触发，可通过 @skip_sync_guard 标注跳过（由调用方在构建工具链时决定，适用于只读查询等无需前置校验的场景）。

IdempotencyGuard [SM]

步骤序列：

• 可选守卫，通过 @skip_idempotency_guard 标注跳过。与 SyncGuard 独立。

ErrorHandler [SM]

根据 OnError 输出的决策值执行对应动作：

forcehalt → 停止工具链 → 设置 forceHalt=true → 报告用户 → 强制挂起（不执行后处理）
halt → 停止工具链（不执行后处理）
halt+persist → 停止工具链 → persist_reasoning(error_summary)（不执行 record）
continue → 记录错误摘要到 operationLog → 继续执行后续步骤
skip_remaining → 跳过剩余步骤 → persist_reasoning(error_summary)（不执行 record）
retry → 验证参数和系统状态是否已变化 → 重试当前步骤
switch_strategy → [回滚脏代码 → 换参数/换工具/报告用户]
– **编译错误回滚**：当 `error = compilation_error` 时，先回滚到上次编译成功的代码版本（通过 git stash 暂存未提交更改后 git checkout，或通过 StateManager 文件快照恢复）。回滚范围仅限当前工具链中修改的文件。
– **文件快照机制**：执行体在修改文件前通过 StateManager 记录文件原始内容快照（`fileSnapshots: Map<Path, string>`），回滚时从快照恢复。git stash 优先于文件快照（git 提供更完善的版本管理）。
– **回滚失败处理**：回滚失败 → 输出 halt（不继续修复，避免进一步污染代码状态）。

• ErrorHandler 是 SyncGuard 和工具链执行失败时的统一处理入口，不包含决策逻辑。
• ErrorHandler 的 persist_reasoning 调用仅用于在异常终止时保存错误摘要，与 CompactProcedure 的阶段边界持久化职责不同。三种 persist_reasoning 的职责区分见 ReasoningPersistence 流程。

ReasoningPersistence [SM]

职责区分：persist_reasoning 有三种调用场景，职责互不重叠：

PostProcess [SM]

步骤序列：

• 与 CompactProcedure 的关系：PostProcess 的 record_knowledge 存事实/结论，CompactProcedure 的 persist_reasoning 存推理链。两者职责不同，避免重复记录。

FileDeprecationFlow [SM]

参数：deprecatedDir（默认 _deprecated/）、excludeMethod（compile_exclude/runtime_ignore/module_exclude）、excludeConfig、cleanTrigger
步骤：check_references → move_to_deprecated → apply_exclusion → verify_isolation → register_cleanup

CompactProcedure(compactType) [SM]

阶段动作映射：

phase_compact → [执行阶段动作 → mark_phase_done → clear_context → 新会话从进度标记恢复，加载推理链末3条到元提示]
module_compact → [record_module_summary + persist_reasoning → record_notes → update_progress_marker → clear_context]
emergency_dump → [输出极简纯文本状态摘要（≤500字符） → clear_context → 强制 Halt，等待用户输入]

• emergency_dump 不执行阶段动作：ctx_critical=true 时 LLM 生成大型 JSON 的成功率极低，跳过阶段动作映射，仅输出极简摘要（当前阶段、已完成模块列表、关键决策点最多3条）。
• ctx_critical 前置检测：ctx_critical 信号应在当前步骤执行前检测（而非执行中），检测到后立即触发 emergency_dump，避免 LLM 在上下文即将截断时执行复杂操作。ctx_critical 为最高优先级，检测到后不等待当前操作完成，立即触发 emergency_dump。
• 下次会话恢复：由 Bootstrap 从进度标记（task_progress）重建上下文，不依赖本次转储的完整性。
  none → no_action
• persist_reasoning 在阶段/模块边界和 module_compact 时强制执行。emergency_dump 跳过 persist_reasoning（截断风险 > 持久化收益）。