Carl723000 · Sep 6, 2026 · Aug 23, 2026 · Aug 29, 2026 · Aug 23, 2026 · Aug 27, 2026
@@ -18,6 +18,10 @@ const FORBIDDEN_ENTRY_PATTERNS = [
   /^extension\/node_modules(?:\/|$)/i,
   /^extension\/issue87-.*\.cjs$/i,
   /^extension\/out\/claudeIncrementalPrototype\.js$/i,
+  /^extension\/out\/adviceEffectiveness\/(?:evidencePreparation|feedback|legacyBridge|legacyPersonalization|modelExperiment)\.js$/i,
+  /^extension\/out\/(?:adviceDemoSample|adviceSummary)\.js$/i,
+  /^extension\/(?:AI-ADVICE-.*V2\.3\.1|V2\.3\.1-CANDIDATE-CONTRACT(?:\.zh-CN)?)\.md$/i,
+  /^extension\/CLAUDE-COLD-AB-V2\.3\.1(?:\.zh-CN)?\.md$/i,
   /(?:^|\/)\.env(?:\.|$)/i,
   /\.(?:pem|key|p12|pfx)$/i,
 ];

@@ -73,6 +73,26 @@ test('VSIX policy rejects internal Superpowers review material', () => {
   );
 });
 
+test('VSIX policy rejects dormant v2.3.1 preparation seams and review documents', () => {
+  for (const entry of [
+    'extension/out/adviceEffectiveness/evidencePreparation.js',
+    'extension/out/adviceEffectiveness/feedback.js',
+    'extension/out/adviceEffectiveness/legacyBridge.js',
+    'extension/out/adviceEffectiveness/legacyPersonalization.js',
+    'extension/out/adviceEffectiveness/modelExperiment.js',
+    'extension/out/adviceDemoSample.js',
+    'extension/out/adviceSummary.js',
+    'extension/AI-ADVICE-INTEGRATION-V2.3.1.md',
+    'extension/V2.3.1-CANDIDATE-CONTRACT.zh-CN.md',
+  ]) {
+    assert.throws(
+      () => assertSafeVsixEntries([...minimalEntries, entry]),
+      /forbidden VSIX entry/,
+      entry,
+    );
+  }
+});
+
 test('VSIX policy rejects unsafe or non-canonical archive paths', () => {
   for (const entry of [
     '/extension/out/extra.js',

@@ -20,6 +20,16 @@ CONTRIBUTING.md
 probe-*.mjs
 issue87-*.cjs
 out/claudeIncrementalPrototype.js
+out/adviceEffectiveness/evidencePreparation.js
+out/adviceEffectiveness/feedback.js
+out/adviceEffectiveness/legacyBridge.js
+out/adviceEffectiveness/legacyPersonalization.js
+out/adviceEffectiveness/modelExperiment.js
+out/adviceDemoSample.js
+out/adviceSummary.js
+AI-ADVICE-*V2.3.1*.md
+CLAUDE-COLD-AB-V2.3.1*.md
+V2.3.1-CANDIDATE-CONTRACT*.md
 docs/**
 
 .gitignore

@@ -177,3 +177,9 @@ Co-authored-by: OpenAI Codex <215057067+openai-codex[bot]@users.noreply.github.c
 ```
 - comment-only 的受控 first-pass automation 与 maintainer-only 的高权限 mention
   workflow 必须保持分离。
+
+## Codex 工具适配
+
+浏览器操作使用当前可用的 Codex browser／computer-use 工具；原文中的 Claude MCP
+工具名称只描述操作意图，不能直接调用。提问按当前模式使用可用工具；Git 操作仍须
+获得当次明确授权。
@@ -0,0 +1,132 @@
+# v2.3.1 AI 建议有效性：候选实现说明
+
+## 状态与边界
+
+当前 worktree 是从正式 `v2.3.0` 基线选择性移植并继续收敛的 v2.3.1 本地候选；版本号、
+release workflow 与发布入口保持不变，尚未发布。
+
+候选代码已经进入 `extension.ts`、`webview.ts` 与生产 VSIX 路径，但相关功能默认关闭。
+关闭、隐藏或未授权时不创建 AI timer、watcher、worker、network 或额外日志扫描。启用后，
+只有用户先检查完整请求预览、再另行点击“发送”，才会调用现有用户配置的 BYOK endpoint。
+旧 `Get AI Advice` 命令仅打开这一统一界面；Prompt Optimizer 也使用同一 prepare → preview →
+explicit Send → strict parse → local feedback 边界，不再保留一次性持久授权或宽松 parser fallback。
+
+## 新增核心
+
+### `src/adviceEffectiveness/contract.ts`
+
+`AdviceContract` 是 provider-neutral 的 v1 契约，统一保存：
+
+- host 生成的本地 observation 与 evidence；
+- direct / correlational / proxy 证据强度；
+- AI 只能引用已有证据的 explanation；
+- 带 `when` 与 stop condition 的 conditional action；
+- 带最小可比任务数与质量 guardrail 的 success criterion；
+- host 盖章的 privacy、source、confidence、quality flags 与 provenance。
+
+模型不能提供 observation、evidence、privacy 或 provenance。`createAdviceContract()`
+只在整个引用图和隐私声明一致时返回 `{ ok: true }`。空 recommendations 是合法的
+“没有足够证据下结论”，不会自动补通用建议。
+
+### `src/adviceEffectiveness/payload.ts`
+
+`buildAdviceAggregateSnapshot()` 只消费现有 `UsageData` aggregate，并通过 allow-list
+重建 DTO。完整/自定义 model ID 被压成 `opus / sonnet / haiku / fable / other`；raw
+record、project label/path、cwd、session、prompt、response、credential 没有目标字段。
+可远程发送的 metric 还有单独 allow-list；新增 metric 必须经过显式隐私评审。low/unknown
+confidence 或仍带 quality flag 的 source 会在 payload 生成前失败，不会要求模型填补缺口。
+
+`prepareAdvicePayload()` 默认生成 `aggregates-only` 的内层 evidence body，且序列化结果中完全没有
+`promptSamples` key。只有调用者额外提供：
+
+```ts
+{ consent: 'explicit', samples: [{ text: '...' }] }
+```
+
+才会加入受数量、单条长度和总长度限制的 prompt 文本；sample 上的 `cwd` 等多余字段仍会被
+丢弃。`advice.userContext` 与 prompt sample 共用独立于 aggregate 的 personalization consent；
+未授权时两者都不进入 body，授权后必须逐字出现在完整预览中。
+
+生产路径再由 `preparedRequest.ts` 把内层 evidence body 封装为完整 Anthropic / OpenAI-compatible
+provider HTTP JSON body。该 body 只序列化一次，生成 host-retained `PreparedAiInvocation`、
+`canonicalBytes` 与 SHA-256；预览从同一 bytes 解码，实际发送和同一次发送内的 retry / curl
+fallback 继续复用该 Prepared bytes。API key 只在发送边界加入 header，不进入预览 body。
+
+### `src/adviceEffectiveness/versionedPersistence.ts`
+
+生产反馈统一写入 `ccu.adviceEffectiveness.localState` v2 envelope，只接受
+`helpful / not-helpful / applied`、格式验证后的 advice/recommendation ID 与本地 epoch 时间。
+它不接受自由文本、prompt、payload、解释、endpoint、path 或 session ID。helpful 与
+not-helpful 互斥，applied 独立；再次点击已选状态会撤回并在全部状态清空时删除该条记录。
+Advice 的每条 recommendation 与 Prompt Optimizer 的每次结果都走同一个写入函数。
+损坏、未知版本或带额外字段的数据 fail closed，写失败后不会用旧快照覆盖新决定。
+
+### `src/adviceEffectiveness/comparison.ts`
+
+`compareAdviceEffectiveness()` 是无时间/IO 依赖的 paired comparison。只有以下条件全部
+满足，才可能返回 `improved`：
+
+- task kind、complexity、provider、model family、effort、metric definition、单位、方向、
+  quality rubric 在 pair 内和 cohort 间一致；
+- coverage complete，confidence 不是 low/unknown，无未允许的 quality flag；
+- 达到预先声明的最小 pair 数，数值均为有限值且 baseline 非零；
+- before/after 质量证据已知，after 全部通过 rubric；
+- 主指标达到阈值，同时 minimum quality 与最大允许退化两个 guardrail 都守住。
+
+任何可比性、覆盖、置信度、数值或质量证据问题都返回 `insufficient-evidence`。主指标
+改善但质量退化返回 `quality-guardrail-failed`；没有达到预设幅度只返回
+`no-demonstrated-improvement`，不声称建议造成伤害或收益。
+
+`comparisonPairing.ts`、`comparisonProduction.ts` 与 `comparisonResult.ts` 把这条纯比较边界接入
+真实、已净化的 provider/task-level 物化 aggregate。只有 scope、task kind、complexity、provider、
+model、effort、metric definition 与 quality rubric 全部相同，且 applied 时间能可靠划分前后时，
+才形成 comparable pair。版本化 result envelope 只保存 schema、provider、measurement / recommendation
+version、guardrail、replay eligibility、sample 与 result；prompt、response、session、path、正文和未知字段
+没有目标字段。无可靠 pair 时 UI 明确显示“证据不足”。
+
+### `src/adviceEffectiveness/structuredOutput.ts`
+
+`parseStructuredAdviceOutput()` 只接受一个严格 JSON 值，并逐层拒绝未知/缺失字段、错误
+schema version、非法枚举、超长/超量内容、重复 ID、空 action/criterion 和未知证据引用。
+任一 recommendation 非法会拒绝整批。它不会剥 Markdown fence、修 JSON、接受尾随 prose、
+返回 partial batch，或把 raw 输出 fallback 成看似有效的建议；错误结果也不回显 raw 模型
+正文。`recommendations: []` 是明确的 no-conclusion 成功结果。
+
+## 当前生产闭环
+
+1. **本地证据**：Claude 只消费 `claudeIncrementalIndex` 已物化的同窗口 aggregate / session
+   summary；Codex 只消费现有结构化数值 insight 与任务级物化 aggregate，不新增日志扫描器。
+2. **独立 consent**：Advice 的 aggregate consent 与 prompt-personalization consent 分开持久化；
+   默认是 aggregates-only。Optimizer 只包含用户主动粘贴的 draft，不使用持久网络授权。
+3. **exact preview / explicit Send**：host 保留完整 Prepared provider body；Webview 只持有 opaque
+   snapshot ID、精确 body、byte count、content type、data mode 与 SHA-256。只有另行 Send 点击会联网。
+4. **唯一生产 sender**：Advice 与 Optimizer 都进入 `sendPreparedModelRequest()` →
+   `sendPreparedAiInvocation()`，且只能使用配置的 BYOK key / endpoint。
+5. **strict response**：Advice 只接受 exact-shape JSON 与已知 evidence references；Optimizer 只接受
+   完整 marker / 三行 settings contract。任一失败都不显示 raw 或自由文本 fallback。
+6. **可撤销本地 feedback**：每条 Advice recommendation 和 Optimizer result 共用 v2 bounded ledger；
+   不接 analytics、telemetry、contribution endpoint 或 advice payload。
+7. **有效性评估**：只有 applied 后出现严格可比的前后任务时才写 pair / result envelope；否则显示
+   `insufficient-evidence`。结果是受控描述性证据，不是因果证明。
+
+## 排除项与剩余边界
+
+- `claudeCodeUsage.getAdvice` 只打开统一 Content 界面，不再构建旧 summary 或直接调用模型。
+- `legacyBridge.ts`、`adviceSummary.ts`、旧 demo / personalization / experiment 准备模块被排除出 VSIX，
+  且 `extension.ts` / `webview.ts` 没有生产调用点；它们不能成为默认或第三条 sender。
+- 生产 backend 固定为 BYOK `api`。Claude Code OAuth/subscription 凭据仅服务既有 quota/usage，
+  不用于 Advice 或 Optimizer，也不存在后台模型请求。
+- Codex remote advice 仍保持关闭；Codex recommendation 与 comparison 使用本地结构数据。
+- comparison 不做显著性或因果识别；缺少可靠 cohort、质量证据或最小样本时保持证据不足。
+- feedback 不存自由文本、不同步、不发 telemetry；Optimizer feedback 当前不触发 comparable-task comparison。
+
+## 验证
+
+测试平铺在 `src/test/` 与 `tests/ui/`，覆盖契约引用、完整 Prepared preview/send object identity、
+默认 aggregates-only、prompt 独立 opt-in、Optimizer 关闭态与严格 parser、敌意隐私字段注入、
+可撤销本地 feedback、真实 pairing / 版本化 result envelope、可比性 / quality guardrail 以及
+未知字段 fail-closed。候选验证仍按仓库流程运行：
+
+```bash
+npm test
+```
@@ -0,0 +1,120 @@
+# v2.3.1 AI Advice Effectiveness: Experimental UI Design Plan
+
+> Status: v2.3.1 integration candidate only. The feature flag is off by default;
+> this document is not a current-release commitment.
+
+## Goal and boundaries
+
+The UI answers one question: can a user see which local evidence supports an
+advice candidate, exactly what would leave the device, and how effectiveness
+would be judged before opting in? It extends the existing AI Advice and Prompt
+Optimizer cards on the Content tab instead of adding a third top-level entry.
+
+Both features are off by default and create no AI network work while disabled.
+When enabled, AI Advice and Prompt Optimizer use the same interaction grammar:
+prepare a complete provider HTTP JSON body, preview its exact UTF-8 bytes, require
+a separate explicit Send click, strictly parse the response, and offer reversible
+local helpful / not-helpful / applied feedback. There is no automatic or default
+model request.
+
+## Visual system
+
+- **Color:** use existing VS Code theme tokens only. Background and copy use
+  `--vscode-editor-background` / `--vscode-foreground`; borders and secondary
+  copy use `--vscode-panel-border` / `--vscode-descriptionForeground`; actions
+  and focus use `--vscode-button-background` / `--vscode-focusBorder`; the
+  snapshot uses `--vscode-editorWidget-background`. Light+ and Dark+ remain
+  host-owned, with no new gradient or hard-coded brand accent.
+- **Type:** explanatory copy uses `--vscode-font-family` at the existing 13px
+  density. Metrics, byte counts, and JSON use `--vscode-editor-font-family`.
+  Small 10–11px status stamps never carry meaning by color alone.
+- **Spacing:** reuse `.action-card`, `.model-details-stacked`, and the existing
+  button/input rhythm. Avoid a new oversized KPI-card language.
+- **Signature:** one continuous evidence spine joins five ordered stages. The
+  sealed snapshot header reads `SEALED · N BYTES · SHA-256`, and its body is
+  decoded verbatim from the same canonical UTF-8 bytes.
+
+## Information architecture and wireframe
+
+Wide layout:
+
+```text
+┌ AI advice effectiveness (experimental) ──────────────────────────┐
+│ [Observed] ─── [Evidence] ─── [Advice] ─── [Action] ─── [Result] │
+│   values          strength       conditional   local feedback     │
+│                                                   sample/guardrail│
+│                                                                  │
+│ □ Allow aggregates only   □ Allow prompt samples (separate, off) │
+│ [Create sealed snapshot]                                         │
+│ ▾ SEALED · 1248 BYTES · SHA-256 · AGGREGATES ONLY                │
+│   {"schemaVersion":1,...}                                        │
+│ [Send prepared request]  (disabled until a valid preview exists) │
+│ Helpful ○  Not helpful ○  Applied ○                              │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+At narrow widths the five stages stack vertically and the spine becomes a left
+rail. Consent controls and actions wrap naturally. JSON scrolls horizontally;
+actual transmitted bytes are never compressed or elided.
+
+## Interaction and accessibility
+
+- Aggregate consent and prompt-personalization consent are separate values in
+  version-migrated VS Code `globalState`. Both start off; prompt consent is
+  disabled until aggregate consent is selected. Every included prompt is
+  visible in the sealed snapshot.
+- “Create sealed snapshot” asks the extension host to prepare the object. The
+  host rechecks the flag and consent, serializes the complete provider body once,
+  and retains its canonical UTF-8 bytes. Preview text, byte count, and SHA-256 all
+  come from that object. The separately clicked Send action resolves the opaque
+  snapshot ID and passes the same Prepared object to the sole production BYOK
+  transport; it cannot rebuild a request from webview text.
+- Prompt Optimizer has the same preview and Send stages. Its body contains only
+  the pasted draft plus the fixed optimizer system instruction and configured
+  model fields; it has no persistent “first-run authorization.”
+- Advice output uses the strict evidence-referencing JSON parser. Optimizer output
+  uses its strict marker/settings parser. Neither repairs malformed output or
+  falls back to free-form prose.
+- Helpful / not helpful / applied are native buttons with `aria-pressed` for
+  every advice recommendation and for an Optimizer result. Selecting an active
+  button again withdraws that value. Helpful and not helpful are mutually
+  exclusive; applied is independent. All mutations use the same bounded local
+  `globalState` envelope and never enter a remote payload.
+- Every action is keyboard reachable. Headings, lists, `fieldset` / `legend`,
+  `aria-live`, and VS Code focus tokens give screen-reader and focus semantics.
+  Consent, disclosure, and provider UI state survive a webview reload.
+- The result stage says “insufficient evidence” until comparable sample and
+  quality guardrails are met; a one-off movement is never called effective.
+
+## Content and privacy rules
+
+- The default route carries same-window aggregate numbers, coarse model families,
+  allow-listed metrics, confidence, and evidence references only. It never accepts
+  or serializes raw sessions, per-record data, prompts, responses, project paths,
+  cwd values, or stable session IDs.
+- Long sessions use elapsed-duration as a proxy; large context uses numeric token
+  thresholds. A conditional “start a new session / `/clear` at a stable task
+  boundary” action appears only when deterministic thresholds and sample rules pass.
+- Topic drift is semantic. It may enter the AI Advice model request only after
+  separate prompt-personalization consent, with every included prompt visible in
+  the exact preview. The host never infers drift from body-free signals.
+- Strict parse failure, unknown persistence versions, damaged state, or incomplete
+  evidence closes the result and never produces a permissive fallback suggestion.
+- `claudeCodeUsage.getAdvice` only reveals the unified Content surface. It does
+  not call a model, build a legacy summary, or open a separate Markdown result.
+- `legacyBridge.ts`, `adviceSummary.ts`, and the demo/preparation modules have no
+  production import and are excluded from the VSIX. They are neither a default
+  transport nor a third sender.
+- Only the configured Anthropic/OpenAI-compatible BYOK endpoint may receive these
+  requests. Claude Code OAuth/subscription credentials are not an AI backend, and
+  no preview, refresh, timer, or background task sends a model request.
+
+## Design critique and revision
+
+An early direction risked becoming another generic dashboard and a third isolated
+experience. The revision embeds the evidence chain in the existing Advice card and
+applies the same preview, Send, strict-result, and feedback grammar to Prompt
+Optimizer. The only new visual signature is the sealed byte snapshot because it
+directly supports privacy review. Narrow layouts, keyboard use, screen readers, and
+theme changes remain candidate checks; with either feature disabled, its host
+message seam fails closed and creates no AI network resource.