# 算法对齐检查

> 对照 `apps/memos-local-plugin/docs/Reflect2Skill_算法设计核心.md`
> 逐节检查 `memos-local-plugin` 的后端 + 前端实现，列出：
>
> - ✅ **已实现**：代码 + UI 都跟得上
> - ⚠️ **部分实现 / 有偏差**：核心在，但闭环没合上、字段没显示、或细节走样
> - ❌ **缺失**：算法文档要求但代码里没有
>
> 每一项都给出对应文件路径行号，便于后续按 ROI 修复。
> 配套阅读：[`GRANULARITY-AND-MEMORY-LAYERS.md`](./GRANULARITY-AND-MEMORY-LAYERS.md)
> （术语 + 粒度 + 经验/环境认知/技能层级关系）。

---

## §0 交互驱动的自我进化框架

### §0.1 步级决策过程 — 步级记忆 (L1 grounded trace)

- ✅ 捕获 `(s_t, a_t, o_t, ρ_t)` — `core/capture/capture.ts` + `step-extractor.ts` + `reflection-extractor.ts`
- ✅ 写 `traces` 表（`storage/migrations/001-initial.sql`）
- ✅ 一个工具调用 = 一个 step；最终 assistant 回复 = 一个 step（`step-extractor.ts` sub-step 拆分）
- ✅ 同一用户消息引出的所有 sub-step 共享 `turn_id`，前端按 `(episodeId, turnId)` 聚合（migration 013 + `MemoriesView.buildGroups`）
- ⚠️ 反思合成：`capture/reflection-synth.ts` 默认开启，但 alpha 评分还依赖 reflection — LLM 缺席时会退化成 α=0，导致 V 全为 0。**建议**：`alpha-scorer.ts` heuristic fallback 至少给 α=0.3 最低值

### §0.2 任务级反馈 — 会话/回合关系分类

- ✅ `q_{k+1}` vs `q_k` 的 **revision / follow_up / new_task** 判定 — `core/session/relation-classifier.ts`
- ✅ revision → reopen episode；follow_up → 同 session 新 episode；new_task → 新 session — `pipeline/orchestrator.ts::onTurnStart`
- ❌ **revision 触发已 finalize traces 重新 backprop** — algorithm §0.2 / §2.4.3 要求"修正型反馈回溯修正 $q_k$ 轮所有 traces 的 $V$"，目前 reopen 事件不会触发新一轮 reward 计算。**缺口**：reopen 时应派发 `reward.rescheduled` 事件让 reward subscriber 用新的 `R_human` 覆盖旧 V

### §0.5 在线进化更新规则

- ✅ 每条新记忆写入触发增量经验关联：`memory/l2/subscriber.ts` 监听 `reward.updated` → `runL2`
- ✅ 多经验抽象环境认知：`memory/l3/subscriber.ts` 同时订阅 `l2.policy.induced` 和 `l2.policy.updated`（status=active 时）
- ✅ 检索按 priority 降权：`retrieval/recency.ts::applyRecencyDecay`
- ❌ **手动改 trace.value** — `updateTrace` 只能改 `summary / userText / agentText / tags`，前端无"标为正/负样本"按钮
- ⚠️ **修订入口分散**：经验有 `setPolicyStatus` + `upsert`、环境认知有 `adjustConfidence`、技能有 `archive` / `rebuild`，但没有原子的 "加一条 boundary / 改 verification" 操作

### §0.6 反馈效用量化

- ✅ `reward/human-scorer.ts` 调 LLM 按 rubric 打分，落到 $R_{\text{human}} \in [-1, 1]$
- ✅ 三 axes（goalAchievement / processQuality / userSatisfaction）实现都在
- ✅ `reward/backprop.ts` 反思加权回溯：`V_t = α_t · R + (1-α_t) · γ · V_{t+1}`
- ✅ 反思权重 α_t — `core/capture/alpha-scorer.ts`（LLM 评分 + heuristic 兜底）
- ⚠️ Analytics 页面没把 R_human 三 axes 拆开显示

### §0.6 Policy Gain

- ✅ $G(f^{(2)}) = \bar{V}_{\text{with}} - \tilde{V}_{\text{without}}$ — `core/memory/l2/gain.ts::computeGain`，with-set 用 softmax 加权（V7 §0.6 eq. 3），without-set 用 Bayesian shrinkage 把经验均值往中性 $V_0=0.5$ 收缩（pseudocount $N_0=5$）
- ✅ shrinkage 的工程动机：原始 V7 公式假设训练样本里有显式失败对照，但真实交互中绝大多数 episode 都成功，导致 $\bar{V}_{\text{without}} \approx \bar{V}_{\text{with}}$、$G \to 0$，所有 policy 永远卡在 candidate；中性先验保证有用 policy 在 $\bar{V}_{\text{with}} \approx 0.7$–$0.85$ 时拿到 $G \approx 0.05$–$0.20$ 正分；样本量足够后先验自然淡化
- ✅ 首次 induction gain 修复（详见末尾"已修复"小节）
- ✅ L2/L3/Skill 默认阈值同步下调以匹配新的 gain 分布：`l2.minTraceValue` 0.05→0.01、`l3.minPolicies` 3→2、`l3.minPolicyGain` 0.1→0.02、`skill.minGain` 0.1→0.02、`skill.candidateTrials` 5→3
- ✅ L3 cluster 二段式 admission（`core/memory/l3/cluster.ts`）：原 V7 §2.4.1 严格 cosine 形成 cluster 在 LLM 归纳出主题分散的 policy 时几乎无法成型；改成"严格优先 → 否则用整个 domain-key bucket 做 loose cluster"，并把 `cohesion ∈ [0,1]` 透传给 `abstract.ts`，对 loose cluster 的 confidence 做 0.6× ~ 1.0× 渐变降权。`PolicyCluster` 新增 `cohesion` + `admission: "strict"|"loose"` 两个字段

---

## §1 三层认知（小步 / 经验 / 环境认知）形式化对照

| 算法层 | 形式定义 | 实现行 / 文件 | 评价 |
|---|---|---|---|
| 小步 (L1) | $f^{(1)} = (s, a, o, \rho, r)$ | `core/types.ts::TraceRow` | ✅ 字段齐全 |
| 经验 (L2) | $f^{(2)} = (\phi, \pi, \kappa, \Omega, \{f^{(1)}\})$ | `core/types.ts::PolicyRow` | ⚠️ trigger/procedure/verification/boundary 都有；`{f^(1)}` 只到 episode 粒度（`sourceEpisodeIds`），**没有直接的 trace ids** |
| 环境认知 (L3) | $f^{(3)} = (\mathcal{E}, \mathcal{I}, \mathcal{C}, \{f^{(2)}\})$ | `core/types.ts::WorldModelRow` + `WorldModelStructure` | ✅ 完整 — `environment / inference / constraints` 三段式齐全；每条 entry 还有 `evidenceIds`（含 policy + trace ids） |

---

## §2 技能结晶与持续进化

### §2.1 Skill 字段完整性

算法文档要求的字段（`Skill:` YAML 示例）vs 当前 `SkillRow` + `procedureJson`（`SkillProcedure`）：

| 算法要求字段 | 对应实现 | 状态 |
|---|---|---|
| `id` | `SkillRow.id` | ✅ |
| `trigger` | `procedureJson.steps` 第一步 + `policy.trigger`（renderInvocationGuide 拼接） | ⚠️ 没单独字段，藏在 markdown 里 |
| `procedure` | `procedureJson.steps[]` | ✅ 结构化 |
| `verification` | — | ❌ Skill 没有独立 verification 字段（policy 有，但没传到 skill） |
| `scope` | `procedureJson.preconditions` | ⚠️ 部分 — preconditions 算前置条件，但没 `applies_to` / `not_applies_to` / `boundary` 三段式 |
| `evidence_anchors` (L1 trace 级) | `SkillRow.evidenceAnchors` (migration 014) + `SkillDTO.evidenceAnchors` | ✅ **已实现** — `packager.buildSkillRow` 持久化 `gatherEvidence` 返回的 trace ids（cap 10, best-first），SkillsView drawer 渲染点击跳 MemoriesView |
| `domain_model` (L3) | `sourceWorldModelIds` | ⚠️ 只存 id 数组，crystallize 时**不把 world model 内容传给 LLM 作 domain prior** |
| `decision_guidance.anti_pattern` | `procedureJson.decisionGuidance.antiPattern` | ✅ **已实现** — `SKILL_CRYSTALLIZE_PROMPT v2` 读 policy.boundary `@repair` 块 + counter examples，`packager.buildProcedure` 用 draft 数据填充（不再硬编码空） |
| `decision_guidance.preference` | `procedureJson.decisionGuidance.preference` | ✅ 同上 |
| `reliability.support_count` | `support` | ✅ |
| `reliability.success_rate` | — | ⚠️ 只有 `trialsAttempted / trialsPassed`，可推导但没暴露 |
| `reliability.beta_posterior` | — | ❌ |

**结论**：算法 §2.1 要求的核心字段已经基本就位 — `evidence_anchors`、`decision_guidance` 都从"硬编码空"修复为真正端到端落地（生成→持久化→DTO→前端显示）。剩余缺口收窄为：`domain_model` 内容传给 crystallize（只传了 id）、独立 `verification` 列、`reliability.success_rate / beta_posterior` 暴露。

### §2.4.1 五层加工流水线

| # | 算法步骤 | 实现 | 状态 |
|---|---|---|---|
| 1 | Trace extraction | `core/capture/*` | ✅ |
| 2 | Value backfill | `core/reward/*`（任务级 R_human + 反思加权回溯） | ✅ |
| 3 | 跨任务经验关联 / 诱导 | `core/memory/l2/*`（subscriber + induce + candidate_pool） | ✅ |
| 4 | Episode stitching（辅助） | `core/retrieval/tier2-trace.ts::rollupEpisodes` + `core/session/episode-manager.ts` | ✅ **旧 alignment 写错为 ⚠️**，实际实现完整 |
| 5 | Model abstraction + value-guided 降权 | `core/memory/l3/*` + `retrieval/recency.ts` | ✅ |

### §2.4.3 反向修订

- ⚠️ "改写小步 + 回溯价值更新"：`updateTrace` 只改文本，**没有重新 backprop 入口**
- ⚠️ "修订经验"：`setPolicyStatus` 改 status、`upsert` 改 body，但没"加 boundary / 改 verification" 的原子方法
- ⚠️ "修订环境认知"：`adjustConfidence` 调 confidence，但**不会用新反馈重跑 `l3.abstraction` prompt**
- ⚠️ "修订技能"：`retireSkill` ✅ + `skill/skill.ts` rebuild 分支 ✅，但没显式的 "Repair / Shrink" 路径

### §2.4.5 V 的五个用途

| # | 用途 | 实现 | 状态 |
|---|---|---|---|
| ① | 检索降权 | `retrieval/recency.ts::applyRecencyDecay` | ✅ |
| ② | 检索排序 | `retrieval/tier2-trace.ts` 按 V+priority 排序 | ✅ |
| ③ | 策略归纳加权 | `memory/l2/similarity.ts::valueWeightedMean`（softmax(V/τ)） | ✅ |
| ④ | Skill 可靠性 (η) | `skill/packager.ts::deriveInitialEta` 从 policy.gain + support 推导 | ⚠️ η 在 packager 里基于 policy.gain 推导；trial 期更新 η 走 `lifecycle.ts::updateEta`。**没暴露 success_rate / beta** |
| ⑤ | 决策指引生成 | `core/feedback/*` | ⚠️ **生成有，闭环没合上**（详见 §2.4.6） |

### §2.4.6 Decision Repair —— 算法核心闭环之一

| 环节 | 实现 | 状态 |
|---|---|---|
| Burst 触发（同工具连续失败 ≥ threshold） | `core/feedback/feedback.ts` | ✅ |
| 用户文本触发（"不对 / 应该 X / 不要 Y"） | `core/feedback/classifier.ts` | ✅ |
| **算法要求的"同 context 下 V 分布对比 > δ"触发** | — | ❌ 没实现这条触发路径 |
| LLM 合成 anti_pattern + preference | `core/feedback/synthesize.ts` + `core/llm/prompts/decision-repair.ts` | ✅ |
| Heuristic fallback（最高/最低 V 取 reflection） | `synthesize.ts::templateDraft` | ✅ |
| 写入 `decision_repairs` 表 | `core/storage/repos/decision_repairs.ts` | ✅ |
| **挂到 PolicyRow** | `feedback.ts::attachRepairToPolicies` 把 `{preference, antiPattern}` 塞进 `policy.boundary` 的 `@repair {…}` JSON 块 | ⚠️ 工作但是 hack — 应该是独立列 |
| PolicyDTO 透出 preference / antiPattern | `memory-core.ts::parsePolicyGuidanceBlock` | ✅ |
| PoliciesView 显示 | `viewer/src/views/PoliciesView.tsx:243-256, 497-518` | ✅ |
| **写入 SkillRow.procedureJson.decisionGuidance** | `core/skill/packager.ts::buildProcedure` | ✅ **已实现** — 用 draft.decisionGuidance 替换原硬编码空 |
| **Skill crystallize prompt 输入 policy 的 @repair** | `core/llm/prompts/skill-crystallize.ts v2` + `crystallize.ts::packPrompt::parseRepairBlock` | ✅ **已实现** — 把 `@repair {…}` 提到 `repair_hints`，加上 `counter_examples` 一起喂给 LLM |
| **SkillsView 显示 decisionGuidance** | `viewer/src/views/SkillsView.tsx::SkillDrawer` | ✅ **已实现** — drawer 新增 "Decision guidance (prefer / avoid)" 段，列出双数组 |
| **retrieval/injector 把 decision_guidance 注入到 agent prompt** | `core/retrieval/decision-guidance.ts::collectDecisionGuidance` + `injector.ts::renderDecisionGuidance` | ✅ **已实现** — retrieval 拉 active policies, 按 `sourceEpisodeIds` 与召回的 trace 关联, 解析 `@repair` 块, 在注入包尾部渲染 "## Decision guidance" 段 |

→ **决策修复链路完整闭环**：repair 的 preference / anti-pattern 三处都消费了：① 写入到 Skill 的 `decisionGuidance` 字段并随技能注入；② retrieval 时按 episode-policy 关联从 active policies 临时召回，独立成段注入到 agent prompt；③ PoliciesView + SkillsView 都展示。Agent 现在真正能感知到"吃一堑长一智"的教训。

---

## §2.5 技能结晶五步

| Step | 算法描述 | 实现 | 状态 |
|---|---|---|---|
| 0 | 收集 Support Set（正例 / 反例 / 边界样本） | `core/skill/evidence.ts::gatherEvidence` 取高 V trace 作正例 | ⚠️ **只取正例**，没区分反例（V<0）和边界样本（V≈0）。算法要求三类 |
| 0 | L3 作为 domain prior | — | ❌ crystallize 不接收 sourceWorldModelIds 对应的 worldModel 内容 |
| 1 | LLM 诱导草案 | `core/skill/crystallize.ts` + `SKILL_CRYSTALLIZE_PROMPT` | ✅ |
| 2 | 结构化解析 → ϕ/π/κ/η 四元组 | `crystallize.ts::normaliseDraft` + `packager.ts::buildSkillRow` | ⚠️ ϕ trigger 没单独字段；κ verification 完全缺失 |
| 3 | 双重检验 — 一致性检验 | `core/skill/verifier.ts`（coverage + resonance） | ✅ |
| 3 | 双重检验 — 执行增益检验（小规模实际部署） | — | ❌ 算法要求"在后续任务中实际部署 + 对比"，目前只有被动 `trialsAttempted/passed` 计数 |
| 4 | Active vs Probationary | `core/skill/lifecycle.ts` | ✅ |
| 5 | 结晶后持续修订（强化 / Repair / Shrink / Retire / Rebuild） | `lifecycle.ts` 有 strengthen / archive；`skill.ts` 有 rebuild 分支 | ⚠️ 缺显式 Repair / Shrink |

---

## §2.6 三层检索

- ✅ Tier 1（技能）：`retrieval/tier1-skill.ts`，按 η 阈值过滤
- ✅ Tier 2a（单步记忆）：`retrieval/tier2-trace.ts`，三路并行（structural / semantic / pattern / FTS），RRF 融合
- ✅ Tier 2b（子任务序列回放）：`retrieval/tier2-trace.ts::rollupEpisodes`（按 episode_id 拼接）
- ✅ Tier 3（环境认知）：`retrieval/tier3-world.ts`，按 confidence + 领域标签
- ✅ MMR：`retrieval/mmr.ts`
- ✅ RRF：`retrieval/rrf.ts`
- ❌ **decision_guidance 注入**（§2.4.6 闭环断点）— 在 Tier 2 片段后追加 `<anti_pattern>` / `<preference>` 段未实现

---

## §3 evidence 全栈追踪能力对照

> 这是用户专门问到的"evidence 是否实现 + 用在哪"，单独成节。

| 起点 | 能否找到底层 trace 证据？ | 通过什么字段 / API |
|---|---|---|
| 一条 L2 经验 | ⚠️ 只能找到 episode（不到 trace） | `PolicyRow.sourceEpisodeIds` → 然后枚举每个 episode 的 traces。**candidate_pool 在诱导阶段持有过具体 trace ids 但消费完就清** |
| 一条 L3 环境认知 | ✅ **每条 entry 直接挂 trace + policy ids** | `WorldModelStructureEntry.evidenceIds` |
| 一条技能 | ✅ **直接挂 trace ids**（migration 014） | `SkillRow.evidenceAnchors: TraceId[]` — packager 落 `gatherEvidence` 输出，cap 10，best-first |

**前端显示**：
- L2 PoliciesView：✅ 显示来源 episode 列表
- L3 WorldModelsView：✅ 显示来源 policy 列表 + ✅ **entry 级 evidenceIds chips**（含 trace + policy 跳转）
- Skill SkillsView：✅ 显示 source policy + source world model 跳转 chip + ✅ **trace 级 evidence anchors 跳 MemoriesView**

**LLM prompt 是否要求输出 evidence？**
- L2 induction prompt（v2）：✅ 输出 `support_trace_ids`（但**没存到 PolicyRow**，仍是一处小缺口）
- L3 abstraction prompt（v2）：✅ 输出 `evidenceIds` per entry，**已存进 `WorldModelStructure`** + UI 渲染
- Skill crystallize prompt（v2）：✅ 不要求 LLM 输出（packager 直接持久化 `gatherEvidence` 的输出）+ ✅ 持久化到 `SkillRow.evidenceAnchors`

---

## 已修复（本仓库历史）

1. **L2 首次 induction gain 为负 → 永久 candidate**（`core/memory/l2/l2.ts`）
2. **L3 对 `policy.updated → active` 不敏感**（`core/memory/l3/subscriber.ts`）
3. **任务轮次阈值缺失 → 单条消息也会被记成 completed**（`core/reward/reward.ts` + `minExchangesForCompletion` / `minContentCharsForCompletion`）
4. **多工具调用之间的"思考"丢失**（`adapters/openclaw/bridge.ts` thinkingBefore + 持久化进 `tool_calls_json`）
5. **状态术语统一**（`probationary/retired` → `candidate/archived`，policies / skills / world_model 统一） — 已固化进 `001-initial.sql`
6. **trace.turn_id 列**（前端"一轮一卡"聚合用，算法层不可见） — 已固化进 `001-initial.sql`
7. **prompt v2** — L2 / L3 加 boundary 守卫，明确禁止"经验越界写成环境事实 / 环境认知越界写成动作建议"
8. **Decision guidance 全链路闭环**（V7 §2.4.6）：
   - retrieval/injector 新增 "Decision guidance" 段（`core/retrieval/decision-guidance.ts` + `injector.ts::renderDecisionGuidance`）
   - Skill crystallize prompt v2 读 policy `@repair` + counter examples
   - packager 真正落地 `procedureJson.decisionGuidance`（不再硬编码空）
   - SkillsView drawer 加 "Decision guidance" 段
9. **Skill `evidence_anchors` 持久化 + 显示**（V7 §2.1）：
   - `skills.evidence_anchors_json` 列（已固化进 `001-initial.sql`）
   - SkillRow + SkillDTO 加 `evidenceAnchors: TraceId[]`
   - SkillsView drawer 渲染 trace chip 跳 MemoriesView
10. **L3 entry 级 evidenceIds 前端渲染**（V7 §1.1）：
   - WorldModelDTO 暴露 `structure: { environment, inference, constraints }` 三段式
   - WorldModelsView drawer 加 `<StructureSection>` 每个 entry 显示 evidence chips（trace 跳 MemoriesView，policy 跳 PoliciesView）

---

## 建议后续迭代（按 ROI 排序）

### 高 ROI（剩余闭环缺口）

1. **revision 反馈触发 trace 回溯重算** — 算法 §0.2 / §2.4.3 核心
   - relation classifier 识别 revision 后，派发 `reward.rescheduled` 事件
   - reward subscriber 重新打分，覆盖旧 V
   - 影响：用户说"不对"时，整轮 trace 的 V 真的会被新的 R_human 覆盖（目前 reopen 后还是旧 V）

2. **Skill crystallize 接收 L3 world model 作 domain prior** — 算法 §2.5 step 1
   - `packPrompt` 加载 `policy.sourceEpisodeIds → world_models referencing those policies` 的 body 段
   - prompt schema 加 `domain_model: string` 输出字段
   - `packager` 持久化到 `procedureJson.domainModel`

3. **L2 induction 持久化 `support_trace_ids`** — 当前已经 LLM 输出但没存
   - PolicyRow 加 `evidenceAnchors: TraceId[]` 列（新建 `002-policy-evidence-anchors.sql`）
   - `induce.ts` 把 LLM 返回的 `support_trace_ids` 落进字段
   - PoliciesView drawer 加 trace 跳转 chip

### 中 ROI

4. **Trace 手动改 value（"标为正/负样本"）** — 算法 §2.4.5
   - 后端：`updateTrace` 接受 `value` patch（带 audit 字段）
   - 前端：MemoriesView 抽屉加按钮

5. **Decision repair "同 context 下 V 分布对比" 触发路径** — §2.4.6 三种触发的最后一种
   - 现在只有 burst + 用户文本两种触发；算法还要求"V 分布差 > δ"自动触发
   - 实现：`feedback/subscriber.ts` 监听 `reward.updated`，对刚收尾的 episode 跑一次 V 分布对比

### 低 ROI

6. **α_t heuristic 兜底**：LLM 缺席时 α 至少 0.3
7. **Analytics 页面 R_human 三 axes 拆开显示**
8. **Skill verification / scope 字段单独拆出**（不再藏在 invocationGuide markdown 里）
9. **Skill 主动小规模 A/B 试用**（把 trial 从被动累计改成主动派发）
10. **Skill `reliability.beta_posterior / success_rate` 暴露到 DTO + UI**