lessonslearned

lessonslearned 是本地 Codex 支持仓库，主要维护 feedback-insights 技能及其脚本、测试、每日扫描草稿、评测 fixture 和项目级洞察记录。这个仓库的核心目标是把用户反馈整理成可审核、可追溯、可复用的 lesson、preference 和 skill-improvement，而不是让经验散落在一次次对话里。

本文档只记录当前仓库里已经核对过的入口和边界。涉及真实 insight、审核草稿、全局 memory 或 $CODEX_HOME 写入的命令，运行前先确认目标路径。

当前能力

• 项目 insight 管理：正式采纳的 lesson / preference 保存在项目 .codex/insights/，索引由 insight_index.py 生成。
• 每日扫描：从 Codex 本地上下文采集项目窗口，默认用 Codex LLM 的 dream-summary 路径生成项目总结、raw-only 线索和可审核候选。
• 候选质量门禁：代码只做确定性过滤，例如 schema、evidence_refs、当前窗口证据、一次性中文请求、automation/memory/system 噪声和已有概念未明确归并等；语义提炼由 LLM 和后续人工审核负责。
• 手动批示 GUI：本地浏览器审核候选草稿，人工执行采纳、稍后、拒绝。
• 全局经验提升：已采纳的项目 lesson / preference 可以从项目 Insight 库手动提升到 $CODEX_HOME/insights/global-experiences/。
• 固定样本评测：daily_scan_eval.py 使用冻结 fixture 和 gold facts 复跑固定历史窗口，输出覆盖率、候选质量、证据定位和 protected 路径漂移报告。

目录结构

• .codex/skills/feedback-insights/：技能说明、脚本、prompt、schema 和本地配置。
• .codex/insights/：当前项目正式 insight 记录和生成索引。不要把每日扫描候选绕过审核直接写到这里。
• .codex/review-drafts/：直接调用 daily_review.py scan-window 且没有设置输出 override 时使用的项目草稿默认位置。
• review-drafts/：历史或手动草稿区，提交前必须人工检查。
• daily-review-work/：定时 wrapper 和评测运行产物的默认工作区；已在 .gitignore 中忽略。
• tests/feedback_insights/：技能脚本和 daily review 流程的单元测试。
• tests/fixtures/feedback_insights/daily_scan_eval/gold_facts.json：固定评测窗口的 P0/P1/P2 gold facts。

常用命令

在仓库根目录执行。PowerShell 示例默认使用 Windows 路径。

# 查看入口
python .codex\skills\feedback-insights\scripts\insight_index.py --help
python .codex\skills\feedback-insights\scripts\daily_review.py --help
python .codex\skills\feedback-insights\scripts\daily_review_capture.py --help
python .codex\skills\feedback-insights\scripts\daily_scan_eval.py --help

# 重建当前项目 insight 索引
python .codex\skills\feedback-insights\scripts\insight_index.py ensure-root --project-root .
python .codex\skills\feedback-insights\scripts\insight_index.py rebuild-index --project-root .

# 重建全局技能改进 / 全局经验索引
python .codex\skills\feedback-insights\scripts\insight_index.py ensure-skill-improvements-root --codex-home "$HOME\.codex" --skill-name feedback-insights
python .codex\skills\feedback-insights\scripts\insight_index.py rebuild-skill-improvements-index --codex-home "$HOME\.codex" --skill-name feedback-insights
python .codex\skills\feedback-insights\scripts\insight_index.py ensure-global-experience-root --codex-home "$HOME\.codex" --record-type lesson
python .codex\skills\feedback-insights\scripts\insight_index.py rebuild-global-experience-index --codex-home "$HOME\.codex" --record-type lesson

# 跑当前测试套件
python -m unittest discover -s tests/feedback_insights -v

脚本面向 Python 3.12 和 Windows PowerShell 编写，目前主要依赖 Python 标准库。

每日扫描

普通每日扫描使用 wrapper：

# 默认扫描昨天，输出到 daily-review-work\
.\.codex\skills\feedback-insights\scripts\run_daily_review_scan.ps1

# 指定扫描日期
.\.codex\skills\feedback-insights\scripts\run_daily_review_scan.ps1 -ScanDate 2026-05-21

run_daily_review_scan.ps1 会先调用 daily_review_capture.py 写入 daily-review-work\capture\<date>\，再调用 daily_review.py scan-window。如果外部没有设置输出变量，wrapper 会把运行产物放在：

• daily-review-work\project-drafts\
• daily-review-work\global-daily-review\
• daily-review-work\dream-summary-tmp\

daily_review.py scan-window 可以直接调用，但直接调用时要明确输出根。没有设置下面这些环境变量时，它会走脚本默认路径，可能写入项目 .codex/review-drafts/ 和 $CODEX_HOME/insights/daily-review/：

$runRoot = Join-Path (Get-Location) "daily-review-work\manual-runs\2026-05-21"
$env:FEEDBACK_INSIGHTS_PROJECT_DRAFTS_ROOT = Join-Path $runRoot "project-drafts"
$env:FEEDBACK_INSIGHTS_DAILY_REVIEW_ROOT = Join-Path $runRoot "global-daily-review"
$env:FEEDBACK_INSIGHTS_CODEX_TMP_ROOT = Join-Path $runRoot "dream-summary-tmp"

python .codex\skills\feedback-insights\scripts\daily_review.py scan-window `
  --metadata-root daily-review-work\capture `
  --scan-date 2026-05-21 `
  --codex-home "$HOME\.codex"

默认 analyzer 是 dream-summary。它会通过 dream_summary_codex.py 启动 nested Codex，保留 --ephemeral --ignore-user-config --ignore-rules --sandbox read-only。可用环境变量包括：

• FEEDBACK_INSIGHTS_ANALYZER：默认 dream-summary。设置为 disabled、none、off、heuristic、high-intelligence 或 legacy 时不会产出候选。
• FEEDBACK_INSIGHTS_DREAM_SUMMARY_CMD：覆盖 dream-summary adapter 命令。
• FEEDBACK_INSIGHTS_DREAM_SUMMARY_TIMEOUT_SECONDS：外层 adapter 超时。
• FEEDBACK_INSIGHTS_CODEX_BIN：覆盖 nested Codex 可执行文件。
• FEEDBACK_INSIGHTS_CODEX_MODEL：传给 nested Codex 的模型名。
• FEEDBACK_INSIGHTS_CODEX_TIMEOUT_SECONDS：nested Codex 超时。

LLM 启动失败、超时或输出不合格时，扫描会记录 warning/raw-only，并保持候选数为 0；不会回退到规则式候选生成。

手动批示 GUI

每日扫描后，可以启动只监听 127.0.0.1 的审核控制台。GUI 读取的输出根要和扫描时一致：

$env:FEEDBACK_INSIGHTS_PROJECT_DRAFTS_ROOT = Join-Path (Get-Location) "daily-review-work\project-drafts"
$env:FEEDBACK_INSIGHTS_DAILY_REVIEW_ROOT = Join-Path (Get-Location) "daily-review-work\global-daily-review"

python .codex\skills\feedback-insights\scripts\daily_review_web.py serve `
  --codex-home "$HOME\.codex" `
  --scan-date 2026-05-21 `
  --host 127.0.0.1 `
  --port 53122

浏览器入口：

• http://127.0.0.1:53122/：默认草稿审核工作台。
• http://127.0.0.1:53122/reviews/<date>：指定日期的草稿审核工作台。
• http://127.0.0.1:53122/overview：完整扫描总览。
• http://127.0.0.1:53122/insights?project_root=<项目路径>：项目 Insight 库。
• http://127.0.0.1:53122/global：全局经验库。

草稿审核页只处理候选草稿。候选不是正式 insight，必须人工选择 采纳、稍后 或 拒绝；采纳后才会创建或归并到项目 .codex/insights/。如果持久化失败，候选会标记为 persist_failed，需要回到证据和原始草稿排查。

项目 insight 提升到全局必须先在草稿审核页采纳，使记录进入项目 .codex/insights/ 后，再到 Insight 库右侧抽屉填写 promoted_reason 并手动提升。不要直接把 daily-review 草稿提升到全局。

固定样本评测

daily_scan_eval.py 用来复跑固定历史窗口，默认只读冻结 fixture。它会在唯一 run-id 目录下写入：

• baseline.json：冻结日期、Codex CLI 版本、模型/命令配置、memory_summary.md 和 MEMORY.md 哈希。
• project-drafts/、global-daily-review/、dream-summary-tmp/：隔离扫描输出。
• protected-before.json、protected-after.json、protected-diff.json：只读保护路径漂移检查。
• quality-summary.json、quality-report.md：gold facts 覆盖、memory baseline 对比、候选证据、raw-only 和人工评审摘要。

冻结 fixture 复跑示例：

python .codex\skills\feedback-insights\scripts\daily_scan_eval.py `
  --eval-root daily-review-work\eval-runs `
  --run-id eval-20260528T-local `
  --fixture-root daily-review-work\eval-runs\<fixture-run>\fixtures `
  --codex-home "$HOME\.codex" `
  --gold-facts tests\fixtures\feedback_insights\daily_scan_eval\gold_facts.json

刷新 fixture 必须显式给出日期、项目 allowlist 和输出根：

python .codex\skills\feedback-insights\scripts\daily_scan_eval.py `
  --eval-root daily-review-work\eval-runs `
  --run-id eval-20260528T-refresh `
  --fixture-root daily-review-work\eval-runs\eval-20260528T-refresh\fixtures `
  --codex-home "$HOME\.codex" `
  --gold-facts tests\fixtures\feedback_insights\daily_scan_eval\gold_facts.json `
  --refresh-fixtures `
  --dates 2026-05-21,2026-05-22 `
  --project-allowlist BmsBattery,misc,lessonslearned `
  --refresh-output-root daily-review-work\eval-runs\eval-20260528T-refresh\fixtures

评测脚本会为 scan-window 显式设置 FEEDBACK_INSIGHTS_PROJECT_DRAFTS_ROOT、FEEDBACK_INSIGHTS_DAILY_REVIEW_ROOT 和 FEEDBACK_INSIGHTS_CODEX_TMP_ROOT 到 run-id 目录，避免写 live 顶层运行区。评测结论只对固定历史样本和对应 fixture 成立。

数据流

1. daily_review_capture.py 从本地 Codex 会话和归档会话采集窗口输入，写入 capture/<date>/。
2. daily_review.py scan-window 对每个项目运行 analyzer，生成项目 raw report、候选草稿和全局总览。
3. dream-summary analyzer 使用 LLM 生成语义总结和候选，确定性代码负责 schema、证据和噪声过滤。
4. daily_review_web.py serve 展示候选和证据，由人工采纳、稍后或拒绝。
5. 采纳后的项目 lesson / preference 才写入 .codex/insights/ 并重建索引。
6. 已采纳项目 insight 可以手动提升到 $CODEX_HOME/insights/global-experiences/。

注意事项

• .codex/insights/index.md 是生成文件，手工修改后可能被重建覆盖。
• .codex/insights/ 是正式记录库；每日扫描候选必须先经过审核。
• .codex/review-drafts/、review-drafts/ 和 daily-review-work/ 可能包含本地路径、项目上下文或对话摘要，提交或公开前必须检查。
• 真实 $CODEX_HOME 可能在仓库外；全局经验、技能改进、memory 和 automation memory 都不要误纳入 Git。
• heuristic、high-intelligence、legacy analyzer 现在是禁用/零候选路径，不是规则 fallback。
• .gitignore 防止后续误提交缓存、日志、数据库、临时产物和敏感配置；它不会删除已经被 Git 跟踪的文件。

English

lessonslearned is a local Codex support repository for the feedback-insights skill. It stores the skill implementation, tests, daily review tooling, evaluation fixtures, and project-level insight records.

Current daily scans default to the LLM-backed dream-summary analyzer. Deterministic code validates structure, evidence references, current-window evidence, and obvious noise; it does not replace LLM judgment or human review. The legacy heuristic, high-intelligence, and legacy analyzer names are disabled and produce no candidates.

Common commands:

python .codex\skills\feedback-insights\scripts\daily_review.py --help
python .codex\skills\feedback-insights\scripts\daily_scan_eval.py --help
.\.codex\skills\feedback-insights\scripts\run_daily_review_scan.ps1 -ScanDate 2026-05-21
python -m unittest discover -s tests/feedback_insights -v

Runtime outputs and evaluation outputs should stay under an explicit run directory, usually daily-review-work\.... Review drafts and $CODEX_HOME outputs may contain local context or user data and should be checked before publishing.