code-repo-wiki 0.5.0

# 项目状态简报 （AI自动维护，禁止贴代码）

## 五十七、v45 提示词工程 + 发布工作流修复 + 版本 0.5.0（2026-08-09，本会话）
- 修改的功能：①4 个 system prompt（module_summary/architecture_overview/knowledge_card/wiki_page）工程化重构——`### 角色/任务/输出格式/约束` 分节+指令前置（OpenAI 官方+Lost in the Middle）；输出语言显式化（output_lang=zh→「简体中文」，非 zh 原样）；knowledge_card 新增「输出原始 JSON 对象本身——不要用 Markdown 代码块包裹」+可选字段省略不输出 null；wiki_page 新增「信息不足时的处理：写（信息不足）不要编造」（reduce-hallucinations 写法）——既有 anti-fabrication 契约字面全部保留；②release.yml 发布工作流修复——build-binaries 4 目标并发各自创建 Release 的竞态（taiki-e 反复 release not found 8-10 次重试失败）→ 新增 create-release job（gh release create --draft 先行+release-id 共享）消除竞态；macos 构建失败（系统 LibreSSL 与 openssl-sys 不兼容）→ brew install openssl@3 + PKG_CONFIG_PATH；新增 publish-release job（--draft=false 定稿）；③版本 0.4.0 → 0.5.0（用户手动应用 Cargo.toml——config zone 护栏，Cargo.lock 同步）CHANGELOG [0.5.0] 版本化
- 摸到的文件：src/generate/prompt.rs（4 prompt 重构+编译修复 format! 隐式捕获改位置参数+新测试）、.github/workflows/release.yml（重写）、Cargo.toml/Cargo.lock（0.5.0）、CHANGELOG.md（[0.5.0]）、src/main.rs（v44 进度提示 stage_zh+完成摘要）、README.md+docs/reference/cli.md（v44 重排+search 默认值注明）、tests/test_cli_smoke.rs（v44 摘要断言）、.opencode/plans/（删除 5 个陈旧计划文件——用户工作区操作，v37 先例保持）
- 是否改变了接口/契约：否（prompt 输出契约字面未动——anti-fabrication 测试 9/9 绿；CLI 输出仅文本模式新增进度/摘要行）
- 验证：cargo test 全量全绿（两次独立运行 0 FAILED）；cargo clippy --all-targets -D warnings 0 警告（确认 v0.5.0）；Cargo.lock 同步；实机冒烟（generate 进度 [扫描源码] 10% stderr+「✓ 生成完成: 扫描 1 个文件 / 4 个实体 / 4 页文档（74s）」stdout；update no-op 契约行保持）
- 提交：661732d（feat(0.5.0)：14 文件 +287/-1711）
- 遗留/风险点：①release.yml 重写后首次 tag 触发仍待 CI 实测（lint-workflow 把关语法）；②发布仍需 HITL：crates.io 启用 Trusted Publishing（Settings→Actions→Workflow permissions→Read and write 权限）+首次手动 publish+打 v0.5.0 tag；③v0.4.0 tag 已打但发布失败（Trusted Publishing 未启用——预期行为，重打 v0.5.0 即可）；④LLM 真实 API 端到端复验仍缺
- 下次最该做的事：push → 观察 CI 全绿 → 用户完成 crates.io Trusted Publishing+手动 publish → 打 v0.5.0 tag 验证发布工作流（create-release→build-binaries→publish 全链）

## 五十六、v43 发布就绪：Apache-2.0 LICENSE + Cargo 发布元数据 + 发布/文档门禁工作流（2026-08-09，本会话）
- 修改的功能：①仓库根新增 LICENSE（Apache License 2.0 官方全文原样，来源 apache.org/licenses/LICENSE-2.0.txt 权威文本）；②Cargo.toml 发布元数据补齐（license=Apache-2.0 / repository / readme / keywords ≤5 / categories ≤5——crates.io 硬性必填 description+license，缺失即 400；keywords/categories 超限为硬错误；categories slug 须精确匹配 crates.io category_slugs）——Cargo.toml 属 config zone，改动清单已交付用户手动应用；③新增 .github/workflows/release.yml（tag v* 触发：crates.io 发布走 Trusted Publishing OIDC 免长期 token——首次发布须手动；GitHub Releases 二进制矩阵 linux/macos/windows 四目标 taiki-e 上传）；④CI 新增 lint-docs job（markdownlint-cli2 结构检查 + lychee 链接可达性）配套 .markdownlint-cli2.jsonc（中文文档豁免 MD013/033/036/024/041/060/012，CHANGELOG/STATUS 历史记录 CLI 排除）+ .lycheeignore（已知不可用网关端点与脱敏占位 URL）
- 摸到的文件：LICENSE（新增）、Cargo.toml（元数据——用户手动应用）、.github/workflows/release.yml（新增）、.github/workflows/ci.yml（lint-docs job）、.markdownlint-cli2.jsonc（新增）、.lycheeignore（新增）、README.md（徽章行+License 段+CI 描述）、docs/index.md（LICENSE 链接）、docs/how-to/maintenance.md（发布节重写：元数据前置+category_slugs 注意+cargo package --list/--dry-run 步骤+Trusted Publishing 首次限制）、CHANGELOG.md（Unreleased 补 v43 三条）、docs/explanation/architecture.md（代码块语言标注）、AGENTS.md（尾部空行）
- 是否改变了接口/契约：否（纯文档/CI/元数据；markdownlint 对既有文档零改动——0 issues；cargo check --tests 干净确认 LSP 陈旧报错非真问题）
- 验证：markdownlint-cli2 本地 0 issues（13 文件）；外部链接清单人工核对（9 处：稳定链接可达、不可用端点/占位 URL 入 .lycheeignore）；cargo check --tests 0 error/warning；CI 门禁（clippy/doc/actionlint/markdownlint/lychee）待 push 后由 GitHub Actions 最终验证
- 提交：a4af5bc（Cargo.toml+Cargo.lock 0.4.0——用户手动应用 config zone 后提交）；e811535（LICENSE+工作流+文档）；d3a6db5（CHANGELOG 版本化）——v43 全链路
- 遗留/风险点：①release.yml 的 rust-lang/crates-io-auth-action@v1 与 taiki-e 参数仅经语法人工核对，首次 tag 触发时由 CI 实测（lint-workflow 会校验语法）；②crates.io 账号/首次手动 publish/Trusted Publishing 启用为 HITL 项（用户操作）；③版本漂移已解决（Cargo.toml+Cargo.lock=0.4.0，CHANGELOG [0.4.0] 已版本化，最新 tag 仍 v0.2.0——打 tag 时用 v0.4.0）；④LLM 真实 API 端到端复验仍缺（DeepSeek 402 后未复验）
- 下次最该做的事：push → 观察 CI 全绿（含新 lint-docs）→ 用户注册 crates.io 并首次手动 publish → 打 v0.4.0 tag 触发 release 工作流

## 五十五、删除补偿提前到主路径——mixed 场景（删除+修改并存）模块残留修复（2026-08-06，本会话）
- 修改的功能：纯删除场景的模块级删除补偿（v21 验证轮 16085af 已修纯删除：存活文件并入变更集重生成）从「快照回填分支」内部提前到 run_generation_filtered 主路径——删除与修改并存（mixed）时 changed_insights 非空不进回填分支，而语义传播对被删文件（图中无节点，find_start_nodes 跳过）够不到其模块，src_m20.md 等模块页磁盘残留被删实体描述（v21 F 组遗留）。修复后无论 changed_insights 是否为空，deleted_files 对应的部分删除模块存活文件一律并入变更集走正常重生成；回填分支退化为仅处理「整模块全删 / 无实体变更」，保留 deleted_modules 剔除语义
- 摸到的文件：src/generate/mod.rs（删除补偿逻辑前移+回填分支简化，~+40 行）、tests/test_incremental_large_fixture.rs（新增 test_delete_file_mixed_with_modification_regenerates_module：删 a.rs+改 solo.rs 断言 m20 模块重生成、磁盘页与 api.md 不残留 a_alpha、solo 新签名生效）
- 是否改变了接口/契约：否（纯内部逻辑重排；IncrementalResult/快照契约不变；纯删除与全删模块行为与既有一致——既有 4 个删除/回填测试全绿）
- 验证：红→绿闭环（mixed 缺陷复现 documents 缺 src::m20 → 修复后含）；cargo test 全量 564 passed（lib 434 + 集成 130）0 failed；cargo clippy --all-targets 0 警告；cargo machete 干净
- 提交：未提交（主线统一提交，禁止 git commit）
- 遗留/风险点：①FileWatch 策略下 watch_paths 在 lib.rs:307 已相对化，删除补偿路径形态一致，理论上同样受益但无专测（GitDiff e2e 覆盖）；②快照缺失时删除补偿跳过、回退分支兜底全量（行为不变）；③主线并行改动 src/output/lint.rs（P3 误报修复）与 src/analysis/community.rs（单目录退化保护）为未提交中间态，与我方改动互不重叠，全量验证时已合流通过
- 下次最该做的事：主线 v29 两缺陷（lint P3 模块名误报 + 单目录仓库退化保护）验收后统一提交本会话全部改动；FileWatch 纯删除 e2e 专测可选补

## 五十四、key 交互命令（2026-08-06，本会话）
- 修改的功能：新增 `repo-wiki key` 交互式配置 LLM API key——明文只写用户级 default-config.toml（安全底线：绝不写项目级 config.toml，随 Git 共享会泄露）；流程 ①目标文件缺失时 create_default_config ②provider=mock 打印无需 key ③api_key_env 对应环境变量已设打印已配置 ④--env 模式写建议 env 名引用（openai→DEEPSEEK_API_KEY、anthropic→ANTHROPIC_API_KEY）⑤非 TTY 打印引导退出 0 ⑥stdin 交互读入（空输入取消）⑦行替换写入（非注释行→注释占位→段末追加，无 [llm] 段回退 toml 往返）+写后 load_config 验证
- 摸到的文件：src/key.rs（新建，+360 行：run/run_with_io/suggested_env_name/guidance_text/write_field/set_llm_field/escape_toml_string+6 测试）、src/lib.rs（pub mod key）、src/main.rs（Commands::Key + dispatch）、README.md（子命令表+--root 列表）
- 是否改变了接口/契约：是（新增 CLI 子命令 key，无存量冲突）；lib 新增 pub mod key + pub fn run + pub(crate) fn guidance_text
- 验证：cargo test --lib 414 passed 0 failed（含 6 新测试）；cargo clippy --all-targets 0 警告；cargo machete 干净（未加依赖）；实机冒烟（fake-APPDATA 隔离）：env 已设分支/key 非 TTY 引导/key --env 写引用/-c mock.toml 提示无需 key 四路径全部符合预期
- 提交：feat(key): 交互式配置 LLM API key（1 commit）
- 遗留：无新增风险（明文写用户级是用户拍板；TTY 交互无法脚本化实机验证，由注入测试覆盖）

## 五十三、rubrics 判定证据检索注入（方案甲）（2026-08-06，本会话）
- 修改的功能：measure_rubrics 叶子判定证据增强——判定前按叶子 requirement 提取关键词（CJK 连续串滑动窗口 2-gram 切分，英文词/数字保留原样），对 wiki 页正文做计数检索 top-2（命中数降序、平局按页名字典序，每页正文截断 3000 字符），命中页以「# 检索到的页面正文」节追加到摘要证据后，追加后整体截断总证据仍 cap 20K；无命中维持现状证据（退化安全）。背景：仅 overview/api 摘要+页面标题时 LLM 系统性保守判「证据不足→不满足」（实测 satisfied 0-12.6%），正文证据缺失是主因
- 摸到的文件：src/bench/mod.rs（+166 行：新 is_cjk/extract_keywords/search_pages 三函数、measure_rubrics 循环内证据组装改造、3 测试）
- 是否改变了接口/契约：否（纯内部函数与循环内证据组装，RubricReport/CLI/prompt 契约不变）
- 验证：cargo test --lib bench 18 passed 0 failed；cargo clippy --all-targets 0 警告
- 提交：方案甲证据检索注入（1 commit）

## 五十二、v25 配置链三合一（2026-08-06，本会话）
- 修改的功能：init 与 install 合并为 install（install 无参=确保用户级 default-config.toml 存在+原插件/MCP/hooks 步骤）；配置链重构——项目级 config.toml 字段级合并覆盖用户级 default-config.toml（uv/Claude Code/cargo 语义），创建只发生在用户级；v24 敏感键净化保留但收窄为 base_url+api_key_env 两键（provider/model 移出，项目级 mock 配置是 CI 常态）；default-config.toml 模板协议统一 openai（Responses，DeepSeek 官方推荐）；v24 .repo-wiki.toml 与旧全局 config.toml 不再读取
- 摸到的文件：src/config/mod.rs（load_default_config 三链+merge_config+strip_injected+sanitize 收窄）、src/main.rs（删 Init/InstallToOpencode、新增 Install、12 处 Option 化）、src/lib.rs（8 函数签名 Option<&Path>）、src/mcp.rs（config_path Option+resolve_mcp_config）、src/doctor.rs、src/bench/{mod.rs,manifest.rs}、src/commands.rs、default-config.toml、README.md、CHANGELOG.md、tests 13 文件
- 是否改变了接口/契约：是（未上线无存量用户）——CLI 命令 init/install-to-opencode 移除（合并为 install）；配置加载链（config.toml 字段级合并）；lib 公共函数签名 Option<&Path>（None=默认链）；MCP 配置解析
- 验证：cargo test 405 lib + 28 测试套件全绿；clippy -D warnings 0；machete 干净；实机三验（fake-APPDATA 隔离：install 创建用户级不创建项目级/项目级 config.toml 字段级覆盖生效/doctor -c config.toml 净化+Key 检查正常）；修复链：output_override_test 464s 触网根因=测试配置名 config.toml 触发净化剥 base_url 致真实调用（4 测试文件改名 mock-server.toml 隔离）
- 提交：config 链三合一+测试适配+文档同步（3 commits，含 883c052）
- 遗留：无（fog：二进制分发/第二档评测跑分/key 管理向导/实体级 diff 分类——均在历史清单）

## 四十四、v19 wayfinder 实施完成（2026-08-05，本会话）
- 修改的功能：wayfinder-v19 十票 A-I 组落地——t01 版本自检（doctor 版本查+llms.txt/llms-full.txt 头注，commit 0db14f2）；t02 文档统一+CI（init 模板 embed 段统一 text-embedding-3-small+OPENAI_API_KEY、README 5 处失实修复、.github/workflows/ci.yml，commit 9ec7d40）；t03 lint 噪声（单字符/纯数字实体过滤+graph mod 类型，commit 46bedf4）；t04 测试泄漏（helper mock_config/openai_compatible_config 强制绝对路径，commit c8c12c2）；t05 llms-full.txt（32K 预算四档裁剪确定性渲染，commit d94f1b1）；t06 update no-op（git-head+工作树状态+产物存在三重判据，commit 77c9b6f）；t07 社区稳定重排序（大小降序+最小路径全序，commit 7fad509）；t08 CHANGELOG 归档 [0.2.0]（v13-v17）+v17 tickets 9/10 resolved
- 摸到的文件：src/{doctor.rs(新), state.rs, llms_txt.rs, incremental/mod.rs, analysis/{community.rs,module.rs}, output/{lint.rs,mod.rs}, analysis/graph.rs, config/mod.rs, main.rs, lib.rs}+tests 9 文件+CHANGELOG.md+README.md+.github/workflows/ci.yml(新)
- 是否改变了接口/契约：是（未上线无存量用户）——新增 update --dry-run/lint 三态/doctor 命令/llms-full.txt 产物/GenerationState.tool_version 字段；社区编号从「最小路径序」改「大小降序+最小路径」全序（产物文件名在新增小社区时更稳定）
- 验证：cargo test --all-targets 512 passed 0 失败；clippy -D warnings 0；machete 干净；实机 no-op e2e（两次 update 第二次秒回「无文件变更，跳过更新」）
- 遗留：t10 Unity 真实 LLM e2e 未验证（I 组）；t09 rubrics 自评 bench --judge 未跑

## 十五、外部对标 v7 深度分析（2026-08-03，联网权威检索）
- 方法：本地全量检索（59 src 文件/19,554 行/17 模块/369 测试全绿）+ 实时联网检索（Karpathy gist 原文、LangChain OpenWiki、FSoft CodeWiki ACL 2026、he-yufeng RepoWiki、repositories-wiki、repowikiagent、doc-wiki、repowiki-cli、AGENTS.md 标准、arXiv 2604.15385/2312.10349/2509.14273、Anthropic Memory/Dreaming）
- 结论：repo-wiki 是 Karpathy LLM Wiki 模式工程化完成度最高的开源实现之一——增量三层/引用契约/确定性测试/检索多样性四项领先；主要差距在消费引导层与质量闭环
- **新识别 4 项差距**：G1（高）AGENTS.md/CLAUDE.md 指令注入缺失（OpenWiki/repositories-wiki/repowikiagent 全部标配）；G2（中）Mermaid 无校验-降级-修复循环（OpenWiki degrade-and-repair）；G3（中）无 index.md/PageRank 阅读路径（仅 _toc.md 简单目录）；G4（低）无 CI 工作流模板 + LLM 分层
- 未验证边界保持：真实大仓库端到端/CPM 调参/embedding 注入/缓存磁盘占用/语义阈值
- 报告：.scratch/research/ANALYSIS-v7-2026-08-03.md

## 十七、G3 阅读指南 index.md 实施（2026-08-03，本会话）
- 修改的功能：新建 src/generate/index.rs——LLM 生成阅读指南（输入=模块列表[名/卡片摘要描述]+依赖/入度，输出=wiki/{主语言}/index.md，仅主语言）；LLM 失败重试 1 次仍失败→降级确定性骨架（模块入度中心度降序、同入度名称字典序的链接列表，BTreeSet 边集+全序 sort_by，不依赖 HashMap 迭代序）；lib.rs run_pipeline Phase 3b 接线（create_provider 失败同样降级，与全局文档"失败只告警"策略一致）；文档 kind=TableOfContents（避免 WikiPage 空串模块归属污染反向同步），references 填模块引用
- 摸到的文件：src/generate/index.rs（新建）、src/generate/mod.rs（+pub mod index）、src/lib.rs（Phase 3b 接线）、tests/test_index_guide.rs（新建，5 测试）
- 是否改变了接口/契约：否（新增 pub 函数 generate_index_guide/fallback_index_guide，无既有接口变更；新产物 wiki/{lang}/index.md）
- 验证：cargo build 通过；cargo test --test test_index_guide 5 passed；cargo clippy --all-targets -- -D warnings 0 告警；全量 cargo test 各二进制全绿（含 test_determinism 未受影响——Mock provider 下 index.md 内容确定性一致；test_determinism.rs 排除列表由主代理处理）
- 测试覆盖：①LLM 失败→确定性降级（同输入两次输出一致+排序断言）②重试 1 次语义（恰好 2 次调用）③正常路径产物含模块链接+元数据 ④降级骨架入度排序/字典序/references ⑤pipeline 级仅主语言（expand_languages=["en"] 时 en 目录无 index.md）+ 产物含链接
- 已知边界：index.md 不参与 plan 白名单过滤（lib.rs 在 filter_by_whitelist 之后 push，白名单用户会多出此页）；全量 cargo test 会把 mock 产物写入仓库根 wiki/（既有测试相对 output.dir 行为，与本次改动无关，跑完全量测试需 git checkout -- wiki/ 恢复）

## 十六、wayfinder 建图:repo-wiki 差距实施(G1-G3)(2026-08-03,本会话)
- 触发:v7 分析识别三项差距,用户启动 wayfinder 建决策地图
- 用户拍板(question 两轮):Destination=G1-G4 实施但 G4 答"不要 CI"(歧义,见 fog);G1=AGENTS.md 引用段+install 命令;G2=lint 检查+生成期校验重试;G3=LLM 生成阅读指南+排除出确定性快照+自动纳入 generate/update;tracker=本地 markdown;交付=计划+地图,实施另起;兼容性完全自由
- 研究子代理(并行 2 个,已 resolve):①AGENTS.md 注入—OpenWiki 用 `<!-- OPENWIKI:START/END -->` 标记对+indexOf 整块替换幂等,双写 CLAUDE.md 内容一致,建议 `<!-- REPO-WIKI:START -->` 自家标记;②Mermaid 校验—Rust 侧唯一候选 Merman(467★,纯 Rust,对齐 mermaid@11.15.0,alpha),OpenWiki 降级格式=注释+text fence,修复靠下次 run,错误可读性待 t03 POC
- 本地核查:citation 重试先例 wiki.rs:32 CITATION_RETRY_MAX=2 + wiki.rs:96-127 循环 + citation.rs:166 retry_feedback(可对齐);test_determinism.rs:43 已有排除列表(加 index.md);install/uninstall 命令已存在(MCP 配置,非 AGENTS.md)
- 产物:.scratch/wayfinder/map.md + tickets/t01-t06(2 research 已 resolve,1 prototype POC + 3 grilling open)+ IMPLEMENTATION-PLAN.md
- 地图:Destination=G1-G3 落地;frontier=t03/t04/t05/t06;Blocking:t03←t05
- 摸到的文件:STATUS.md、.scratch/wayfinder/*(新建 7 文件)

## 一、架构健康度
- 当前模块总数：17（analysis 拆出 community/feature；incremental 拆出 change；新增 project 模块承载 ProjectRoot）
- 违规跨模块调用：无（output→generate 反向依赖已消除——wiki_languages 移入 output 自持；generate 层依赖 ingest FileInsight 属既定边界，经 lib.rs 管线传入）
- 测试覆盖率：cargo clippy --all-targets -- -D warnings 0 错误 0 警告；cargo test 全绿 305 个（215 lib + 90 集成，含真实 git 差分 e2e/确定性快照/聚类稳定性/parser 去重 7 语言/hook 与插件安装）；bench 编译通过；cargo machete 零未使用依赖
- 代码量：src 约 16,800 行 / 55 .rs 文件 + tests 17 文件

## 二、本次变更影响范围
- 修改的功能：wayfinder 航图 18 票全部 work-through 完成（2026-08-02）——缺陷修复 + 债务清理全落地：
  - **票 04/05 入口闭环**：git hook 去不存在的 --quiet（command -v PATH 探测）+ install/uninstall 插件文件闭环（include_str 模板、已存在不覆盖、幂等删除）；opencode.rs 写入前 create_dir_all（新环境 .config/opencode 缺失 bug）
  - **票 06 export**：--skip-generate 从 .state/export_snapshot.json 快照恢复导出（render_all 末尾同步写快照），不再全量重生成；-o 对齐 generate；--root 支持
  - **票 07**：9 处 Leiden expect 全部补 R1 证据化注释（权重来源/契约/fail-loud 语义），Embedder 契约文档化
  - **票 08**：搜索索引 file_path 键写入时归一化（store.rs 4 函数）+ 比较点 norm_sep——Windows 增量索引删除永不命中 bug 修复
  - **票 09**：hybrid 分支补 text 索引存在性检查；RRF 去重键 name→(name,file_path)（同名不同文件折叠修复）+ 防回归测试
  - **票 10**：清理改产物集合 diff 语义（doc_fingerprints∪doc_modules − rendered − 保护集），全量/增量统一，module_n 漏删消除，替换旧路径推导法
  - **票 11**：HTML 与 markdown 同构命名 wiki/{lang}/{file}.html + .md 链接重写 .html（外部/源码定位不重写）+ 文档-卡片精确关联（修子串误匹配）
  - **票 12**：双流水线合并为单入口 run_pipeline(…, root, GenerationMode)；真增量扫描（insights 持久化缓存 .state/insights_cache.json，内容指纹失效，变更文件重 parse）；8 参 → 6 参（IncrementalResult 合并）
  - **票 13**：provider 重试/SSE 统一（指数退避 + 抖动、429/5xx/超时白名单、4xx 立即失败、SSE 解析共享、Anthropic 流式 base_url bug 修复）
  - **票 14**：parser 去重——SharedProcessor trait（公共 walk + kinds()/handle_special/fallback 差异点钩子），7 语言删公共骨架约 800 行
  - **票 15**：--root 全链路贯穿（ProjectRoot 注入 9+ 处，删除 7 个 cwd 委托变体：scan_and_parse/load_plan/resolve_plan/get_head_commit_hash/collect_sql_files/generate_schema_documents/run_incremental_update；generate 层 root 参数化；config 冗余 plan 探测删除）
  - **票 16**：CONTEXT.md 边界 2 处失实修正
  - **票 18**：tempfile 评估后不引入（pid 命名已防冲突、引入成死依赖）
  - 过程中修复的既有 bug：rewrite_md_links_to_html 输出重复累积；opencode 写入缺父目录
- 摸到的文件：43 个（src 27 + tests 14 + benches 1 + CONTEXT.md/STATUS.md）
- 是否改变了接口/契约：是（未上线无存量用户，已批准不向后兼容）——run_pipeline/run_incremental_pipeline（删除）→ run_pipeline(config_path, output, force, root, mode)；run_generation/run_generation_filtered 加 root；execute_search/execute_ast_search/run_card_command 加 root；CLI 各子命令加 --root；Export 加 --skip-generate/-o；ExportSnapshot 新契约；GenerationMode 新枚举

### root 化改造收尾（2026-08-02，本次会话）
- 修改的功能：tests/progress_test.rs 与 tests/output_override_test.rs 两个集成测试从"切 cwd"模式（CWD_LOCK 全局互斥锁 + set_current_dir + with_cwd 包裹）改为显式 ProjectRoot 注入——删除 CWD_LOCK/with_cwd、config 路径与 config.toml 写入绝对化（work_dir.join）、run_pipeline(_with_progress) 传 &root；断言语义与 mock server 行为零改动；测试现可并行（无 cwd 互斥）
- 摸到的文件：tests/progress_test.rs、tests/output_override_test.rs、STATUS.md
- 是否改变了接口/契约：否（纯测试机制改造，cargo test --test progress_test --test output_override_test 全绿：2 passed）
- 说明：src/ 下 project 模块与既有 root 化入口未动；其余测试仍用 from_cwd 委托（兼容路径，主代理后续轮换）

### root 化改造收尾·第三批（2026-08-02，本次会话）
- 修改的功能：tests/test_plan.rs 同样改造——删除 CWD_LOCK/Mutex/with_cwd（含仅被 with_cwd 使用的 std::path::Path 导入），6 处 with_cwd 块改为显式 ProjectRoot::new(dir.clone()) 注入 + dir.join 绝对路径写文件 + load_plan_at/resolve_plan_at 传 &root；断言与临时目录清理零改动；test_resolve_plan_disabled 无文件系统访问（enabled=false）保留 from_cwd
- 摸到的文件：tests/test_plan.rs、STATUS.md
- 是否改变了接口/契约：否（纯测试机制改造）；验证：cargo test --test test_plan 11 passed；cargo clippy --all-targets -- -D warnings 0 告警

### root 化改造收尾·第四批（2026-08-02，本次会话）
- 修改的功能：tests/test_clustering.rs、tests/test_clustering_stability.rs、tests/test_determinism.rs、tests/test_plan.rs 四处 cwd 残留收尾——删除全部 CWD_LOCK/_guard/set_current_dir/恢复 cwd 逻辑及 Mutex 导入；scan_and_parse_at/from_cwd 改为显式 ProjectRoot::new(tmp/dir.clone()) 注入传 &root；test_plan.rs:148 resolve_plan_at 改用 ProjectRoot::new(temp_dir.join("unused"))（enabled=false 不碰文件系统，resolve_plan_at 入口早退已确认）；test_determinism.rs 删纯死代码 CWD_LOCK；文件顶部失实 doc 注释同步修正；断言逻辑零改动
- 摸到的文件：tests/test_clustering.rs、tests/test_clustering_stability.rs、tests/test_determinism.rs、tests/test_plan.rs、STATUS.md
- 是否改变了接口/契约：否（纯测试机制改造）；验证：cargo test --test test_clustering --test test_clustering_stability --test test_determinism --test test_plan 全绿 14 passed；cargo clippy --all-targets -- -D warnings 0 告警
- 说明：全仓库测试已无 CWD_LOCK/set_current_dir 残留（grep 验证）；src/ 下 from_cwd 委托入口保留为兼容路径

### 历史记录（T0-T5 深度演进 + 航图前两轮，已完成）
- T0-T4 全部 15 项实现完成（社区检测聚类/实体级变化分类与语义传播/生成并行化/失败隔离/反向链接/CoT/评测基准/测试缺口/文档修正）；T5 清零计划全完成
- 航图第一轮：hook/插件闭环（04/05）+ provider 统一（13）

### 票 14 本地方案验证（2026-08-02，本次会话，仅新建测试不碰 src/）
- 修改的功能：新建 tests/test_watch_e2e.rs 三项验证——①watch 端到端（spawn 线程跑 run_watch，改 src 文件后 api.md 出现新函数名，实测通过）；②insights 缓存占用（10 文件实测 7,952 bytes，60 文件外推 ≈ 47,712 bytes）；③./ 前缀路径边界（固化当前行为：strip_prefix 组件比较失败 → `./src/foo.rs` 未相对化原样透传，传播子串匹配不命中，由指纹比对兜底，无功能损失，候选修复方向已注释）
- 摸到的文件：tests/test_watch_e2e.rs（新建）、STATUS.md
- 是否改变了接口/契约：否；验证：cargo check --test test_watch_e2e 通过，cargo test --test test_watch_e2e 3 passed（0.78s）
- 诚实边界：watch e2e 未 join 线程（run_watch 死循环无停止接口，进程退出即终止）；FileWatch 指纹比对相对路径读盘依赖 cwd，测试进程 cwd 非临时仓库 → 全量生成时指纹表为空 → 事件触发后为全量重生成，测试验证"事件→重跑→产物变化"链路而非纯增量短路

## 三、已知风险点（由AI诚实自曝）
- CPM 分辨率 γ=0.5/0.4 由小仓库与合成图实测选定，真实大仓库（万级文件）社区粒度未验证，需实测调参
- 特征聚类的 embedding 注入路径（0.5 语义权重）无 API key 未真实验证，仅验证纯结构降级路径
- 真实 LLM 全量生成（大仓库）端到端产物未验证；watch 端到端已在小仓库（2 文件）验证通过（票 14）
- tests/fixtures/sample-repo/config.toml 是真实 provider（无 base_url）——直接复用跑 generate 会触网（现有测试均在临时副本改写为 mock，无测试触网）
- insights 缓存（票 12）体积 = 全仓库实体元数据 + 源码文本，超大仓库磁盘占用未实测（票 14 已实测 10 文件 7.9KB，60 文件外推 ≈ 47.7KB，万级文件仍需实测）；缓存损坏自动全量重建（可观测性契约内）
- 导出快照（票 06）写入失败仅告警——快照缺失时 export --skip-generate 明确报错（契约内，非兜底）

## 四、下次最该做的事（AI建议）
1. 大仓库（万级文件）实测社区检测粒度 + insights 缓存磁盘占用 + LLM 全量生成耗时，按实测调 CPM resolution
2. 真实 LLM 端到端验证（generate/update/export --skip-generate/watch 全链路跑通一次大仓库）
3. fixture 配置改 mock provider（消除触网隐患）
4. 语义 lint（LLM 跨页矛盾/过期检查）+ 自建评测（CodeWikiBench 协议 3-5 仓库跑分）
5. 提交本次 43 文件变更（git commit 尚未执行）

## 五、航图收尾
- 18 票状态：01/02（研究）/03（失败语义总则）/17（MCP 移除，YAGNI）已解析；04-16 全部实现；18 评估后收窄。map 与 tickets 存档于 .scratch/repo-wiki-complete/
- 防回归契约生效：test_determinism 锁产物集合、test_clustering_stability 锁聚类确定性、test_incremental_git_e2e 锁真实 git 增量、test_parser_dedup_7lang 锁 7 语言解析一致性、test_hook_install/test_install_opencode 锁安装闭环

## 六、审计收尾（2026-08-02 第二轮未完成项审计）
- 本轮新修复：第 8 个漏删委托 classify_entity_changes（含生产 from_cwd 残留）；project.rs 过时注释；7 个测试文件 CWD_LOCK/set_current_dir 全部清除（显式 ProjectRoot::new）；src 层 cwd 依赖归零（from_cwd 仅剩 CLI 默认）
- 剩余 P2：fixture config 触网隐患（一行改 mock）；插件 wiki_export 未用 --skip-generate（每次导出全量重生成）
- 剩余 P3：update 无 --progress-json；insights 缓存/export 快照恢复无直接单测；watch 端到端未验证
- 未验证：真实 LLM 大仓库端到端、CPM γ 大仓库调参、embedding 注入路径、缓存磁盘占用
- 审计报告：INCOMPLETE_REPORT-v2.md

## 七、审计收尾（2026-08-02 第三轮：插件对齐 + 状态契约 + 竞态）
- P1×5：①load_protection .ok() 静默损坏状态→人工保护失效（lib.rs:82，与 sync 显式拒绝不一致）②Phase 2b 中途存盘清空保护集（incremental/mod.rs:180,225，纯推证未复现）③export_snapshot 写失败仅 warn→陈旧快照静默导出④插件 readExistingCards 读 cards/ 顶层与实际 cards/{lang}/ 不符→wiki_query/module_info 恒空⑤插件 wiki_export 缺 --skip-generate→每次导出全量重生成
- P2×15：fixture 触网/update 无 progress/缓存快照无单测/write_card_atomic 非原子/README 滞后/version 死契约/embed.provider 死字段/init vs install 双默认配置/语义索引先删后失败误导/插件 --config 硬编码/reference 逗号/插件能力未暴露/跨进程无锁/引导措辞
- 审计报告：INCOMPLETE_REPORT-v3.md
- 验证基线：305 测试全绿、clippy 0 告警、machete 干净

## 八、v3-fix 航图实施完成（2026-08-02，14 票全部落地）
- **P1 状态可靠性**：01 原子写（新 src/fs.rs write_file_atomic，state/快照/缓存/卡片四处统一，3 单测）；02 损坏 fail-loud（load_protection 区分不存在/损坏，2 测试）；03 中途存盘保护保留（state.rs preserve_protection + 两处 save 合并，2 测试）；04 快照陈旧检测（latest_wiki_page_mtime + export 报错，1 测试）
- **P1 插件**：05 读卡递归 cards/{lang}/；06 wiki_export --skip-generate；12 打磨（root 逃生口/reference 多参/force/engine/init）
- **P2**：07 fixture mock + README 补全；08 update --progress-json；09 缓存 5 测试 + export CLI 3 测试；10 config 清理（embed.provider 删/version 校验/索引时序/引导措辞）；11 init/install 统一模板；13 单进程契约（README/CONTEXT/3 模块头）；14 watch e2e 3 测试 + 缓存实测 7,952B/10 文件
- 验证基线：324 测试全绿（229 lib + 95 集成，新增 19）、clippy -D warnings 0、machete 干净
- 新发现（子代理 C）：compute_file_fingerprint 相对路径读盘依赖 cwd——FileWatch 指纹比对路径的生产隐患，已固化行为测试并标注，未修（需独立票）

## 九、外部对标深度评估 v4（2026-08-02，本轮）
- 方法：本地 17,516 行全量审计 + 权威检索（ACL 2026 CodeWiki/arXiv MemDocAgent/Anthropic 上下文工程/DeepWiki/repowise/RepoDocs/Google Code Wiki/Karpathy llm-wiki）
- **4 项结构性差距**：P0-1 LLM 正文无强制源码引用契约（业界全部标配"禁止编造+强制引用"，OpenDeepWiki GATHER-THINK-WRITE、RepoDocs 纠正重试）；P1-1 semantic 全量暴力余弦 O(N) 无 ANN（应换 sqlite-vec）；P1-2 全局文档每次增量全量重生成（mod.rs:279 确认，增量承诺被吃掉）；P1-3 插件绑定 OpenCode 非 MCP 标准
- 确认领先项：增量三层机制/人工保护/混合检索+AST 补全/确定性测试/单二进制——业界第一梯队
- 路线建议：P0-1 引用契约（1-2 天）→ P1-3 MCP（2-3 天）→ P1-2 全局文档增量（1-2 天）→ P1-4 引用/实体覆盖评测（1 天）→ P1-1 sqlite-vec（2-3 天）；不做重多智能体/向量服务化/自动重编译（论文与工程双证伪）
- 报告：.scratch/research/ANALYSIS-v4-benchmark-2026-08-02.md

## 十、v4 实施完成（2026-08-02，P0-1/P1-2/P1-3/P1-4 + 2 遗留修复）
- **P0-1 引用契约**：新 src/output/citation.rs（extract/validate/retry_feedback，8 测试，含 Windows 反斜杠与盘符排除）；wiki_page_system_prompt 加"源码引用契约"约束段（每节至少一条 file:line）；generate_wiki_page 生成后校验 + 重试（CITATION_RETRY_MAX=2，注入 retry_feedback，耗尽报错）；3 测试（重试成功/耗尽报错/无引用放行）
- **P1-2 全局文档增量**：GlobalDocAffected{architecture, schema} 影响信号；architecture=entity_changes.has_interface_change()、schema=changed_files 含 .sql；未受影响时从 export_snapshot.json 回填旧文档（backfill_global_docs，零 LLM 调用），回填失败回退生成；3 测试
- **P1-3 MCP server**：新 src/mcp.rs（rmcp 3.1.0 官方 SDK，stdio transport）；5 工具 search/ast_search/read_wiki_page/read_card/status，全部复用 lib 入口不复制逻辑；main.rs 加 `repo-wiki mcp --root .` 子命令；get_global_runtime 转 pub；tokio 加 process feature；tests/test_mcp.rs 进程级 stdio JSON-RPC 全链路测试（握手/list/call）
- **P1-4 零成本评测**：lint 新增 2 类检查——bad-citation（产物引用存在性，output_dir.parent() 项目根解析）、entity-coverage（页面核心实体须在 api.md 权威清单中，仅主语言）；5 测试
- **遗留修复**：①compute_file_fingerprint cwd 依赖——from_insights/is_file_changed 加 root 参数（root.path().join 解析相对路径），lib.rs save_generation_state 同步，测试全更新；②FileWatch 实体级分类——run_file_watch_incremental 用 state.last_commit_hash 构造伪 GitDiffResult 接 classify_entity_changes_at（非 git 回退空集），传播升级为语义传播
- 验证基线：**343 测试全绿**（247 lib + 96 集成，新增 19）、clippy -D warnings 0、machete 干净
- 未做（按路线延后）：P1-1 sqlite-vec ANN（P1-1 保留为下一优先级）

## 十一、v5 审计（2026-08-02，未完成项全面复查）
- **新修复 P1×3**：①删除孤立模块唯一文件 → cleanup 差集清空全部旧产物（run_generation_filtered 空集短路，v4 前既有 bug，既有测试被空结果满足）→ 快照回填未删模块 + 快照缺失回退全量，新增 git e2e 测试；②backfill_global_docs 按 kind 去重 → 多 .sql 仓库丢页 → 锚定 title+language；③lint entity-coverage 提取首个标识符取到 pub/fn 关键字 → 系统性误报 → entity_name_from_signature（'(' 前最后标识符）两侧统一
- **新修复 P2×4**：wiki 空内容放行→重试；MCP 路径穿越净化；related_files 空误判全删；纯删除回填补白名单
- 验证基线：**347 测试全绿**（249 lib + 98 集成，本轮新增 4）、clippy 0、machete 干净
- 未完成项清单（详见 INCOMPLETE_REPORT-v5.md）：P1-1 sqlite-vec ANN（改动面已评估收敛于 store.rs+semantic.rs，风险=vec0 固定维度 vs 混合维度测试/换模型重建）；agent.rs 语义分支零测试；语义 0.3 阈值硬编码；MCP 便捷接入（写 opencode.json 有 Unrecognized key 风险，需实测 schema）；mcp top_k 无上限；watch 绝对路径混存；citation P3 边缘×4
- 报告：.scratch/research/INCOMPLETE_REPORT-v5.md

## 十二、v6 决策分析（2026-08-02，待拍板项全部裁定）
- **决策 1**：P1-1 ANN → sqlite-vector-rs **0.3.1**（用户拍板；版本修正：0.2.2 非最新，0.3.0 yanked）。理由：rusqlite >=0.32 显式兼容、exact+hnsw 双模式同库、DELETE/事务完整；对比 sqlite-vec pre-v1 breaking change 与 DiskANN 仍在 alpha。迁移 6 要点：虚表 dim 固定需维度校验/换模型重建、0.3 相似度阈值→distance 语义转换（现有测试锚定）、伪向量混合维度（3+16）统一、借迁移抽象 SemanticSearch trait 补 agent 语义分支零测试、arrow×4+usearch 依赖重量实测记录、pre-1.0 风险登记
- **决策 2**：MCP 便捷接入 → install 写项目根 **.mcp.json**（Claude Code 官方 mcpServers 标准，跨 Cursor/VS Code 复用，首次使用需批准为安全网）；opencode 用户走文档（opencode2 `mcp add` CLI，1.x opencode.json mcp 键）；opencode 不读 .mcp.json（getmcp 指南确认）
- **决策 3**：citation 4 个 P3 边缘**全修**（C:/ 正斜杠盘符、v2.0 版本号、-src 连字符吸收、../ 逃逸）——lint bad-citation 已是 CI 门禁，误报直接阻断 CI
- **决策 4**：语义 0.3 阈值**保持硬编码**（OpenAI 官方参考线，YAGNI）；仅做迁移时相似度→距离语义保真转换
- 附带：mcp top_k clamp ≤50；watch 路径混存/语言切换回填错位留独立票
- 实施顺序：①citation 4 项 ②.mcp.json+top_k ③sqlite-vector-rs 迁移
- 报告：.scratch/research/DECISIONS-v6-2026-08-02.md

## 十三、citation 4 个 P3 边缘修复（2026-08-02，本轮，决策 3 实施）
- 修改的功能：src/output/citation.rs 四项边缘缺陷修复——①盘符识别扩展为 `^[A-Za-z]:[\\/]` 两种形态（原仅 `C:\`；补"连字符剔除后路径以盘符开头"的形态判定）；②新增最后一段扩展名规则（has_valid_extension，点后字母开头非空扩展名），排除 v2.0/1.2 版本号误报，src/v1.5.rs 正常放行；③回溯后剔除前导连字符（-src/fs.rs 列表项形态，my-file.rs 中间连字符不受影响）；④validate_citations 层拒绝含 .. 段引用（reason="路径含越界段 .."），extract 层保留完整路径
- 摸到的文件：src/output/citation.rs、STATUS.md
- 是否改变了接口/契约：否（Vec<Citation>/Vec<InvalidCitation> 结构不变，仅内部逻辑）；验证：citation 12 passed（原 8 + 新 4）、lint 10 passed、generate 62 passed、全量 lib 260 passed、clippy --all-targets -- -D warnings 0 告警
- 证据：红-绿流程——新增 4 测试先行，修复前 3 个失败（连字符/版本号/越界），修复后全绿；正斜杠盘符测试修复前已通过（该形态恰被前导 `/` 拒绝规则意外拦截），仍按决策补语义化识别
- 说明：任务开始时遇到的 src/mcp.rs clamp_top_k E0425 为瞬态增量编译问题，二次编译即消失，未修改该文件

## 十四、v6 实施完成（2026-08-02，决策 1/2/3 落地 + 遗留修复）
- **决策 1 修正（关键转折）**：sqlite-vector-rs 依赖链 Windows/MSVC 三重阻断实测不可编译——sqlite3_ext 0.2.1 `cfg!(unix)` 运行时宏门控编译期 `use std::os::unix`（connection.rs:195-202，纯 Rust 问题 gcc 不可解）；numkong 7.7.1 `-std:c99` MSVC 不认 + serial.h:890 C99 混合声明 C2059；→ 按用户裁决改 **sqlite-vec 0.1.9**（纯 C 静态嵌入 cc 编译，无 usearch/numkong/sqlite3_ext 链，Windows 编译通过，探针实测全链路）
- **③sqlite-vec 迁移**：新 src/search/vecdb.rs（vec0 虚表封装：OnceLock 进程级扩展注册/延迟建表（维度首探）/KNN 循环扩样+node_json 去重（阈值语义与旧全量余弦完全等价）/维度不匹配重建/remove/clear/count，8 测试）；semantic.rs 重写（SemanticSearch trait 抽象 + SemanticEngine 固有方法薄封装委托，空表短路免空库 embed 请求，相似度 0.3↔距离 0.7 换算保真）；agent.rs 改依赖 Box<dyn SemanticSearch>（补语义回溯分支 3 测试，原 P1 缺口）；store.rs 删向量死代码（回归纯 FTS5，4 测试删）；阈值换算锚定测试（MAX_COSINE_DISTANCE==0.7）
- **④语言切换回填错位修复**：backfill_global_docs 加语言一致性校验（快照语言 ≠ 当前主语言 → 不回填回退生成，防旧语言写盘目录错位丢页），新增测试
- **决策 2/3**：.mcp.json install/uninstall 生成移除 + mcp top_k clamp≤50（工作区已有未提交实现，审查质量达标接受，6+1 测试）；citation 4 项（见十三节）
- 验证基线：**369 测试全绿**（271 lib + 98 集成，本轮新增 21）、clippy -D warnings 0、machete 干净、release 构建通过
- 遗留（已知边界，独立票）：watch 绝对路径混存（v4 已 strip_prefix 相对化，复核无问题）、sqlite-vec pre-1.0 breaking change 风险登记
- 报告：.scratch/research/DECISIONS-v6-2026-08-02.md（决策记录）+ 本回复三张验证清单


## 十八、G1+G2 实施完成(2026-08-03,本会话)
- **G1 AGENTS.md 注入**:新命令 install-wiki/uninstall-wiki(commands.rs:331-487:WIKI_BLOCK_START/END/TEMPLATE + inject_wiki_block/remove_wiki_block/wiki_block_state + install_wiki/uninstall_wiki,复用 fs::write_file_atomic;main.rs:170-184 + 523-532 dispatch);标记 <!-- REPO-WIKI:START/END -->;幂等=完整标记对整块替换/无标记尾部追加/半标记报错;uninstall-wiki 无标记提示"未安装"exit 0;--also-claude 双写开关默认关;8 单测(commands.rs:526-650)+ 5 集成测试(tests/test_install_wiki.rs);真实冒烟:注入保留人工内容/幂等 START=1/卸载恢复/未安装提示
- **G2 Mermaid 校验-重试-降级**:新 src/output/mermaid_check.rs(merman-core 0.7 权威解析;Engine::new()+parse_diagram_sync(strict);MERMAID_RETRY_MAX=2;validate_mermaid_blocks/mermaid_retry_feedback/degrade_mermaid_blocks(坏块→<!-- repo-wiki: mermaid parse failed: 单行 --> + ```text,好块保留);9 单测);generate_wiki_page 合并 citation+mermaid 双校验循环(引用耗尽仍 bail,mermaid 耗尽 degrade 页面保留);新 complete_with_mermaid_guard 供架构/概览(重试耗尽 degrade 不中断);lint 新增第6类检查 bad-mermaid(兜历史产物/人工编辑/增量遗留);真实冒烟:lint 报 Unterminated node label 完整错误,exit=1
- t03 POC 结论:merman-core 0.7.0 错误消息人类可读(LexError message 直接可喂 LLM),已写入 tickets t03 RESOLVED
- 摸到的文件:Cargo.toml(+merman-core="0.7")、Cargo.lock、src/output/mermaid_check.rs(新)、src/output/mod.rs、src/generate/wiki.rs、src/output/lint.rs、src/commands.rs、src/main.rs、tests/test_install_wiki.rs(新)
- 验证基线:**292 lib + 集成全绿**(lib 271→292 新增21:mermaid_check 9 + wiki mermaid 3 + lint bad-mermaid 1 + G1 commands 8)、clippy --all-targets -D warnings 0、全量 cargo test 0 失败
- 已知边界:测试跑完全量后需 git checkout -- wiki/ 恢复(mock 产物泄漏到仓库根 wiki/,既有行为);merman alpha 状态风险已登记(t05 拍板接受)

## 二十二、重大事故记录与恢复(2026-08-03,本会话)
- **事故**:U10 验收时运行 repo-wiki bench(本仓库为评测对象),Update Recall 回放用 git reset --hard 逐 commit 回滚,吞噬 U01-U10 全部未提交改动(20+ src + 10+ tests 文件)
- **根因**:measure_update_recall 无工作区干净检查(评测语义缺陷);已提交工作不受影响
- **止损**:git checkout 75b5918 -- . 恢复工作树 + git update-ref refs/heads/master 75b5918 恢复分支;已提交(G1-G3/MCP/T0-T5/v8-v9)完整恢复;292 lib 测试全绿
- **防护持久化**:src/bench/mod.rs 回放前强制 git statuses 干净检查(非空即 bail),已提交 76739e0
- **损失**:U01-U10 未提交改动丢失,方案记录完整(压缩摘要),需重做;src/bench 文件幸存但接线(lib.rs pub mod bench + main.rs Bench)丢失
- 分析报告:.scratch/research/ANALYSIS-v10-2026-08-03.md(含未完成项全景/优先级/防再丢建议)

## 二十三、wayfinder 建图:U01-U11 重做与完成(v11)(2026-08-03,本会话)
- 触发:事故(U01-U10 被 bench 回放吞噬)后,用户启动 wayfinder 重新规划恢复路线
- 用户拍板(question 两轮 7 项):Destination=重做 U01-U10 + 完成评测 U10/U11 全部;产出=纯规划(地图+决策票+完整实现计划);提交策略=每完成一个 U 立即 git commit(强制执行无需批准);U11=纳入(裁判模型实施时实测选型);顺序=接受 ANALYSIS-v10 9 步路线;bench 安全闸=纯硬闸(脏工作区拒绝,无逃生口);评测仓库=先本仓库,公开仓库进 fog
- 产物:.scratch/wayfinder-v11/map.md + issues/t01-t02(2 research 票)+ IMPLEMENTATION-PLAN.md(9 步完整计划,每 U 含实现要点/文件/测试/提交)
- 地图:Destination=全量落地;frontier=t01/t02(待 fire 子代理);无未决 grilling(全部拍板)
- 摸到的文件:STATUS.md、.scratch/wayfinder-v11/*(新建 4 文件)

## 二十四、U01-U11 全部实现完成(2026-08-03,本会话,wayfinder-v11 落地)
- **11 次提交全落地**:U01(S1 MCP lang 净化,506f66b)→U02(模板动态路径+root 补齐族,879c51b)→U03(D1/D3/D4/D5,f00fa54)→U04(D2/D6/D7/D8+P3,7e698a5)→U05(D9 HTML,210970e)→U06(D11/D12,cc4cff1)→U07(N2-N8,8b17517)→U08(N9-N20,3abd22f)→U09(parser 4 语言,cd28d92)→U10(bench 五维自动评测,86f6991)→U11(TQS LLM 裁判层,3cbb06c)
- **验证基线:321 lib + 118 集成 = 439 测试全绿**、clippy --all-targets -D warnings 干净、cargo machete 零未使用依赖、git 工作树干净
- 新功能:bench 评测子命令(五维自动层+--judge TQS 裁判层)、MCP lang 净化、watch 多根、渲染原子写、fence 精确识别、增量两段式状态、force 退化全量、架构骨架降级、配置边界校验、插件清理、parser 覆盖补齐
- 4 项验证与三张清单详见本会话最终回复;事故恢复路线(wayfinder-v11)全部完成

## 二十五、v11 深度分析报告(2026-08-03,本会话,/goal 会话)
- 方法:本地 62 src 文件全面审计子代理(12 项发现)+ 联网 11 次检索(RepoDoc 四阶段增量/CoREB reranker 结论/MVVP 评测协议/OpenDeepWiki v2/sqlite-knowledge-graph/tree-sitter 新范式)
- **P1×2**:lib.rs:769-772 增量语义索引吞错(新旧向量混存);lib.rs:127-145 状态落盘三重吞错(人工修改保护静默失效,与 lib.rs:81 注释矛盾)
- **P2×5**:bench HEAD 恢复无 RAII guard(事故同源);llm.rs 非真流式;incremental/state 静默降级×2;agent 索引损坏对 MCP 表现无命中
- **P3×5**:build_call_edges 零单测(回归风险最高);bench diff 判定吞错;module.rs 测试残渣;embed filter_map 丢元素;chunk 同名去重边界
- **网络对照结论**:repo-wiki 第一梯队(Karpathy 生态);增量缺"一致性校验"环节(RepoDoc 四阶段);搜索层需评估 reranker(短关键词 nDCG≈0);评测基准补 MVVP 协议(κ+复测+style 消偏)
- 报告:.scratch/research/ANALYSIS-v11-2026-08-03.md(六节:现状/审计 12 项/网络对照/优先级路线/反思/三张清单)

## 二十六、wayfinder 建图:repo-wiki v11 路线全量落地 + Unity 仓库评测(v12)(2026-08-03,本会话)
- 触发:v11 分析报告(12 项发现+网络对照)后用户启动 wayfinder 规划恢复/增强路线
- 用户拍板(question 三轮 13 项):Destination=全部(短中长)+Unity 仓库评测;产出=纯规划;P1-1=传播错误;MVVP 裁判=DeepSeek V4 Flash;reranker=候选对比实测;图谱=research 对照;公开 Rust 集不纳入(只测 Unity);C# parser 提前增强;Unity 仓库=评测+端到端验证;规模=先扫描;长期项全部纳入
- 重要新对象:D:/UnityProjects/Project Strategy(用户 Unity 游戏仓库)——评测主对象+真实大仓库端到端验证(解决历史未验证项)
- 产物:.scratch/wayfinder-v12/map.md + issues/t01-t12(12 票,全 open)+ IMPLEMENTATION-PLAN.md(实施蓝图)
- 地图:Destination=全量落地;frontier=t01-t10,t12;t11 blocked by t06;t08 需 t06 数据(方法论可先行)
- 摸到的文件:STATUS.md、.scratch/wayfinder-v12/*(新建 14 文件)

## 二十七、v12 全部实现完成(2026-08-03,本会话,wayfinder-v12 落地)
- **10 次提交全落地**:t01-t04(短期四项,4effa9f)+t04 clippy(ed1206e)+t07(C# Unity 形态,0225101)+t05(MVVP,346d965)+t09(真流式,87725a9)+t09 修复(06cce95)+t12(reranker 评估,dd9a4f2);t06/t08/t10/t11 为研究/任务票(结论已 resolve 于票)
- **验证基线:327 lib + 118 集成 = 445 测试全绿**、clippy -D warnings 干净、machete 干净
- 关键成果:t06 Unity 仓库探测(2165 .cs/238K LOC)→t07 发现并修复 C# 字段三层结构缺陷(SerializeField 字段此前全部丢失);t08 实测 γ=0.5 在 Unity 仓库产生 526 模块(过细,需下调);t11 mock 全链路验证(526 页/522 卡,generate 333s/export 0.6s);t09 流式 LLM 消除长生成总超时截断
- 决策落地:t10 图谱范式=记录不重构;t12 reranker=不引入(FTS5 短查询基线+论文证据)

## 二十八、v13 深度分析报告(2026-08-03,本会话,/goal 会话)
- 方法:本地 62 src 文件审计子代理 + 联网 11 次检索(2026-08 最新)+ 主代理逐项查证(子代理三项 P1/P2 全部回源属实)
- **P1×1**:t09 真流式纸面化——complete 仍非流式(resp.json().await,llm.rs:361)+ client 总超时仍在(267/414)+ complete_stream 零生产调用;v12 87725a9 声称移除总超时实际未生效(PowerShell 转义失败)
- **P2×3**:TQS κ 混合新旧文档(bench/mod.rs:670 恒取第一份);mermaid degrade 块号与 validate 不一致(嵌套围栏坏块漏降级);collect_sse 逐块边界零测试
- **P3×7**:死代码(agent set_rrf_k/llm:46)、吞错(mod.rs:398)、过时注释、多 declarator 无测试等
- 网络对照:Agent Retrieval Bench edit2ripple(增量评测可借鉴);style bias(0.76-0.92)≫position bias;robust-llm-wiki 分层 lint;Karpathy 生态背书
- 报告:.scratch/research/ANALYSIS-v13-2026-08-03.md(七节:状态/发现/对照/未完成项全景/需求/反思/三清单)
- 教训:445 全绿测试覆盖纸面路径;声称完成必须有真实调用点证据;语义级测试(非存在性断言)

## 二十九、v13 全量落地完成(2026-08-04,本会话,wayfinder-v13)
- **A 组 P1 正确性 10 项(f8ae1c8)**:A1 首次 update 无基线回退全量(原静默空 diff 短路,wiki 恒空);A2 incremental 禁用时 update 真正全量;A3 mermaid 依赖图/调用图确定性排序(原 HashSet/HashMap 字节漂移);A4 LLM 生产路径统一流式(complete 默认实现委托 complete_stream,移除 client 120s/180s 总超时,SSE 60s 空闲超时保护——v12 t09 纸面化修复,附 A4 回归 6469fea:test_cli mock 改 SSE);A5 文档指纹读失败保守计入保护集;A6 状态读取失败显式告警;A7 插件全部工具补 --root;A8 卡片恢复/反向同步读失败告警+被删卡片不重建;A9 semantic 吞错链修复+hybrid 降级 warn;A10 文档修复(README/CONTEXT/fixture/测试注释)
- **E 组 全局配置链(3e30f9d,用户拍板)**:新 global_config_dir(Windows %APPDATA%/repo-wiki,其他 ~/repo-wiki,USERPROFILE 优先);默认配置搜索链=项目级→全局→创建全局;15 处 --config 改 Option 全部入口统一 resolve;Init 缺省走链创建全局;Bench config 走链;测试隔离核查(全部 CLI 测试显式 --config,不触达真实 APPDATA)
- **B 组 P2 可维护性 11 项(c9039f0)**:B1/B2 已于 A 组完成;死代码 4 处(SearchAgent::text_engine/set_rrf_k、NodeKind::priority、ParserRegistry::supported_extensions);bench diff 吞错 warn+保守计入;ScanOutput{insights,files_failed} 解析失败统计+AnalysisStats.files_failed;embed 非数字元素显式 bail;lint.rs 六类检查各一函数(每函数<60 行);tests/common/mod.rs helper 收敛(9 文件去重);benches root 参数化;update --progress-json 冒烟
- **C 组 P3 卫生 3 项(eabfa0a)**:测试残渣(module.rs/agent.rs/integration_test 死变量)+lint 5 处读失败 warn+semantic 注释;wiki/ 整体 .gitignore+git rm --cached(仓库根 wiki/ 是 mock 泄漏产物,真实产物在 .repo-wiki/);P3-4 八项核对补齐 2 测试(卡片读失败不中断/被删卡片不重建)
- **D 组(c424210)**:D1 stale-entity 符号漂移 lint(api.md 清单实体∉源码 AST→报错,entity-coverage 反向);D2 update 尾部 lint 全量复核 warn 不阻断;D3 前置查证=seed 本就固定(LEIDEN_SEED=42 双处),detect_communities_with_resolution 参数化+新 benchmarks/gamma_scan.rs 评测工具;γ 实测(Unity 2950 文件):γ 0.2-0.6→模块 521-724(差异≤25%),单文件占比 59-69% 不敏感——低模块化是图结构特性,维持默认 0.5,t08 结论修正
- **验证基线:463 passed**(346 lib + 117 集成,较 v12 445 +18)、clippy -D warnings 0、machete 干净、工作树干净
- 已知边界:wiki_note 需二进制在 PATH(本机 G1 环境问题,已用 cargo run 完成);wiki 自更新需真实 LLM key 未执行;γ 扫描工具保留于 benches/gamma_scan.rs 供大仓库复测

## 三十、v14 深度分析报告(2026-08-04,本会话,/goal 会话)
- 方法:并行子代理(本地 62 src+19 测试+插件+文档 全量审计 / 联网 6 主题 30+ 来源检索)+主代理逐项复核(三处 P1 全部回源属实)
- **P1×3**:lib.rs:769-773 增量语义索引入口两处 if let Ok 无告警(v13 A9 只修内层);output/mod.rs:398 AGENTS.md 引导写失败静默;lib.rs:395 git hash 失败静默空(非 git 与 git 失败不可区分)
- **P2×3**:README:80 向量 BLOB 失实(sqlite-vec 迁移后残留);README:96 排版断裂;lint.rs 注释"六类"过时(实际 7 类)
- **P3×2**:update_search_index_incremental 语义分支无端到端测试;全量测试污染仓库根 wiki/ 未根治
- 网络对照(2026 最新):RepoDoc 四阶段(语义影响传播+交叉引用验证);CodeWikiBench rubrics+三 judge 合成;MVVP judge 校验协议;VeriContext 引用 SHA-256 fail-closed;arXiv:2512.12117 区间算术引用校验(92% 零幻觉);llms.txt 生态;Codebase-Memory LSP 混合解析;edit2ripple 增量检索基准
- 结论:工程完成度仍第一梯队;结构性差距=引用机械校验(防幻觉硬校验)+评测闭环(rubrics/三文档对比)两个质量闭环;7 项未完成项现状核对表见报告
- 报告:.scratch/research/ANALYSIS-v14-2026-08-04.md(七节:基线/审计发现/未完成项全景/网络对照/优先差距清单/反思/三清单)

## 三十一、wayfinder 建图:repo-wiki v14 全部差距落地(2026-08-04,本会话)
- 触发:v14 深度分析(7 项差距 + 3 项历史未完成项)后用户启动 wayfinder 规划,question 一轮拍板
- 用户拍板:Destination=全部差距(含语义 lint/真实 LLM e2e/PATH,唯一排除 LSP 混合解析);产出=纯规划(地图+tickets+完整实现计划,实施另起);评测=自建 rubrics+真实 DeepSeek;提交策略=每字母组一个(实施时)
- 研究子代理(并行 2 个,已 resolve):t01 引用机械校验——方案 A 区间算术(arXiv:2512.12117)+lint 升级,不引入 VeriContext SHA-256 fail-closed(漂移过敏与增量场景冲突);实体行区间即"检索块",重叠判定 start≤entity.end&&end≥entity.start;hash 门留 --experimental-hash 实验开关;t02 rubrics 协议——叶子二值 0/1+加权自底向上聚合 S±σ_R+Coverage(CodeWikiBench),维度 7 与 TQS 并存,TQS 补 MVVP 缺口(Cohen kappa/position_bias/low_confidence),--full-regen 三文档闭环可选
- 产物:.scratch/wayfinder-v14/map.md + issues/t01-t09(2 research resolved + 5 grilling + 2 task open)+ IMPLEMENTATION-PLAN.md(A-G 组完整实施计划,含依赖图/验收判据)
- 地图:Destination=全部差距落地;frontier=t03-t09;blocking:t03←t01(已 resolve)、t04←t02(已 resolve)、t09←t04
- 摸到的文件:STATUS.md、.scratch/wayfinder-v14/*(新建 11 文件)

### v14 work-through t03 resolve（2026-08-04，本会话）
- 一会话一票原则：resolve t03 引用校验失败语义（grilling，question 四轮拍板）——维持 bail/维持重试纠正（不引入 auto-cite 回填）/生成时+lint 双升级/与实体校验独立；关键边界=无实体文件（README 等）引用放行
- 网络补查证据：OpenAI 官方引用指南（系统侧解析 locator、模型不编造 source ID）；TACL 2026 Citation Failure/GhostCite（LLM 自校验引用仅 38% 准确率→机械校验必须零 LLM）；2026 错误处理范式（验证门+3 次重试后升级）
- 地图更新：Decisions so far + t03 行；IMPLEMENTATION-PLAN B 组已细化（可实施状态）；frontier 现为 t04（←t02 已解锁）

## 三十二、v14 全量实施完成(2026-08-04,本会话,wayfinder-v14 落地)
- **A 组(734117c)**:增量语义索引入口两处 if let Ok 补 else warn;AGENTS.md 引导写失败 warn;git 基线失败区分非 git(info)/git 失败(warn)——git2 0.20.4 ErrorCode::NotFound 查证自源码;README 存储栈/排版/lint 注释失实修复
- **B 组(90fa8a0)**:引用机械校验(区间重叠,t03 拍板:维持 bail/不引入 auto-cite/双升级/独立双闸)——citation_overlaps_entity 闭区间判定+两级校验 validate_citations_against_entities;无实体文件(README)放行;wiki 重试循环接线(全仓库 insights 实体表,Option 兼容测试);lint 新 kind bad-citation-overlap(共享 collect_source_entities);测试+6(含 Windows 反斜杠表键)
- **C 组(2990344)**:评测闭环——Rubric 维度 7(CodeWikiBench:docs_tree→3 生成+1 合并→叶子 0/1→加权聚合 S±σ+coverage,容错四形态解析);TQS MVVP 缺口(机会校正 Cohen kappa/position_bias/low_confidence_modules 阈值 2.0);渲染第七节;测试+3
- **D 组(3899254)**:语义 lint——新 semantic_lint.rs(LLM 跨页矛盾,变更驱动单次调用合并多页 40K 截断,容错解析 kind=semantic-conflict);update 尾部接线失败只告警;测试+2
- **E 组(c9f627c)**:llms.txt 导出(t07:仅 llms.txt)——确定性生成(模块页/全局文档/卡片三类链接),(lang,title) 排序;render_all 4.1 步接线不参与保护;测试+2
- **F 组(3c80ba4)**:watch Ctrl-C 优雅退出(t06)——run_watch_loop 加 stop_flag+recv_timeout(500ms) 轮询,tokio signal feature;run_watch 签名不变;测试+1
- **G 组(环境)**:t08 PATH 修复完成(cargo install --path . → C:\Users\WenYu\.cargo\bin\repo-wiki.exe 验证可运行);t09 真实 LLM 最小验证完成(DeepSeek V4 Flash 真实生成 src::fs 卡片 6.7s 落盘)——Unity 大仓库全链路未做(时间/API 成本,如实未验证)
- **验证基线:477 passed**(359 lib + 118 集成,较 v13 463 +14)、clippy -D warnings 0、machete 干净、工作树干净、9 张 tickets 全部 resolved
- 未完成项:Unity 大仓库真实 LLM e2e 全链路(可另起会话);test_cli.rs:172 LSP 陈旧误报(编译通过)

## 三十三、v15 深度分析报告(2026-08-04,本会话,/goal 会话)
- 方法:并行子代理(本地生产就绪度审计 64 src 文件 / 联网 6 主题 12 轮 2026 最新)+主代理复核(子代理 B 两处过时误判已修正:引用校验/llms.txt 实际 v14 已实现)
- **生产就绪评估**:通过项 10(单进程契约/原子写/三处 P1 修复/key 无泄露/测试全离线/安全闸/Ctrl-C/规模边界/基准);缺口 11 项——高 1(Linux 动态依赖 openssl/zlib 未声明,"单二进制免依赖"仅 Windows 成立,发布前翻车点)、中 5(README 安装段/无版本管理/llm.rs 等 32 文件零 tracing/缓存 12.8KB 每文件万级≈128MB/插件 PATH)、低 5(lint .. 不对称/状态保存静默/README --root 缺 note+bench/测试污染 wiki//watch e2e 注释失实)
- **未完成项全景 11 项**:高 1(Unity 真实 LLM e2e);中 5(semantic lint/rubrics 真实验证/插件 PATH/缓存/版本管理);低 3(watch e2e 注释/污染/README);闭环 3(sqlite-vec 登记/LSP 误报/语义 lint 成本控制)
- **网络对照(2026)**:Karpathy gist 2026-02 演进(矛盾调和/write-back/frontmatter 元数据=新差距);CodeWikiBench 68.79% vs OpenDeepWiki 47.13%(可用 v14 rubrics 跑官方对照);SWD-Bench QA 评测新范式;VeriContext hash 方案(t03 已拍板不引入);llms.txt 生态验证 E 组决策(Claude Code 第二大读取者);sqlite-vec 0.1.9 stable 仍 pre-v1;tree-sitter-language-pack 305 语法可扩展
- 优先路线:①P0 Linux 依赖声明+README 安装段 ②P1 llm.rs tracing+状态保存告警 ③P1 Unity e2e+真实 LLM 验证 ④P2 lint .. 对齐+watch e2e+README ⑤P2 版本管理+插件 PATH ⑥P3 frontmatter/SWD-Bench/语言扩展
- 报告:.scratch/research/ANALYSIS-v15-2026-08-04.md(六节:就绪评估/未完成项/网络对照/优先清单/反思/三清单)

## 三十四、wayfinder 建图:repo-wiki 生产环境就绪 P0-P2(v16)(2026-08-04,本会话)
- 触发:v15 深度分析(生产就绪评估+未完成项全景)后用户启动 wayfinder 建图,question 一轮拍板
- 用户拍板:Destination=P0-P2 全部(发布门槛+可观测性+验证闭环+一致性+工程化,P3 能力扩展排除);产出=纯规划;Linux 依赖=文档声明(不 vendored);Unity e2e=纳入(task);版本管理=纳入;P3=Out of scope
- 产物:.scratch/wayfinder-v16/map.md + issues/t01-t09(4 grilling + 5 task,全 open)+ IMPLEMENTATION-PLAN.md(A-E 五线:文档分发/可观测性/一致性/工程化/验证闭环)
- 地图:Destination=生产就绪;frontier=t01-t07(拍板/实施线);blocking:t08←t04、t09←t08;无 research 票(依赖清单本地可查证,v15 网络检索已覆盖)
- 摸到的文件:STATUS.md、.scratch/wayfinder-v16/*(新建 11 文件)

## 三十五、v16 实施落地(2026-08-04,本会话,wayfinder-v16)
- **A 组(fc7f958)**:README 安装段(cargo install --path . --locked)+Linux/macOS 前置依赖声明(t03 拍板纯文档;依赖链 cargo tree 实测:reqwest→native-tls→openssl、git2→libgit2-sys→libssh2-sys vendored→libz,openssl-sys Windows 目标不编译)
- **B 组(d087047+4f90e95)**:llm.rs 可观测性——retry_with_backoff 每次失败 warn(attempt/原因/错误体截断 2000 字符)+退避 info+耗尽 error;collect_sse 流开始/空闲超时/结束 info;incremental/mod.rs:209 from_insights 失败 else warn;教训=首提交漏 llm.rs 编辑,补 commit(不 amend)
- **C 组(1df9dc4)**:lint check_citations 补 .. 段拒绝(与生成层对齐,新测试);test_watch_e2e 注释失实修正(v14 F 组已实现 Ctrl-C,说明不 join 真因);README --root 清单补 note/bench
- **D 组(780cab1+tag v0.2.0)**:CHANGELOG 建档(Keep a Changelog,Unreleased 回填 v13-v16)+version 0.2.0;插件 PATH 根治(t02)——install_plugin_file 注入 current_exe() 绝对路径(JSON 转义),新单测;已安装旧模板不自动升级
- **E 组(t08/t09)**:Unity 完整仓库真实 LLM e2e 尝试 2 次(①root 未指向→"未找到源文件"②加 --root 后被中断),产物未生成——如实报告**未验证**;真实 LLM 链路可用性已由 v15 单卡验证(src::fs 6.7s 落盘)背书
- **验证基线:479 passed**(362 lib + 117 集成,较 v14 477 +2)、clippy -D warnings 0、工作树干净、9 张 tickets 全部 resolved
- 未完成项:Unity 大仓库真实 LLM e2e(需专门会话,预算 2h+);本机 LSP 陈旧误报

## 三十六、v17 深度分析报告(2026-08-04,本会话,/goal 会话)
- 方法:并行子代理(本地一键路径实机模拟审计/联网 8 主题 9 次检索)+主代理复核(三处 P1/P2 全部回源属实)
- **一键评估**:最短路径=3 条命令(cargo install → 设 key → generate),全局配置链/非 git/search-status 引导均达标;阻断傻瓜化的 4 缺口——P1 init 无参覆盖既有配置(main.rs:586-588 注释"复用"但无条件 write,数据破坏);P1 key 缺失错误零引导;P2 README 示例失实(gpt-4o/OPENAI vs 模板 deepseek/DEEPSEEK);P2 schema 默认与模板阵营分裂
- **版本失实修复(5b3d99f)**:v16 D 组 780cab1 声称 version 0.2.0 但 Cargo.toml 未改(--version 输出 0.1.0)——子代理审计发现,本会话立即修正+提交
- **网络对照(2026)**:ddsyasas llm-wiki 一键向导(免费模型默认/两遍 lint/一键修复)=傻瓜化标杆;docverity 三态退出码+history-aware coverage;autodocs FIND/REPLACE 三重验证;CodeWikiBench ACL 2026 正式收录(68.79% vs 47.13%);CiteCheck 88.7 F1/urlhealth 3-13% 编造背书引用校验;llms.txt 采用 4.2% 反面证据 Google 不抓取;traceSDD 行级引用 TDR 86-88%
- 优先修复清单:init 覆盖保护→key 引导→README/schema 对齐→mock 告警→lint 三态退出码+--dry-run→doctor 自检
- 报告:.scratch/research/ANALYSIS-v17-2026-08-04.md(六节:一键评估/未完成项全景/网络对照/优先清单/反思/三清单)

## 三十七、wayfinder 建图:repo-wiki 傻瓜化+生产就绪补全(v17)(2026-08-04,本会话)
- 触发:v17 分析报告(一键评估 4 缺口)后用户启动 wayfinder 建图,question 两轮拍板
- 用户拍板:Destination=v17 清单全部 7 项+验证轮(含 Unity e2e);init=缺省跳过+显式覆盖+--force;key 引导=错误文本+doctor 五查(含网络);默认阵营=统一模板(deepseek);mock 告警=日志+页脚;lint 三态+update --dry-run;**新方向=OpenAI Responses API**(deepseek-v4-flash 已支持,chat/completions 改兼容端点)
- 研究子代理(resolved):t01 DeepSeek Responses API——官方确认 2026-07-31 上线 POST /v1/responses(为 Codex 适配,无状态);deepseek-v4-flash 唯一支持模型(v4-pro 计划 8 月初);协议差异=input/instructions/output.items/语义化 SSE 无 [DONE];chat/completions 保留未弃用
- 产物:.scratch/wayfinder-v17/map.md + issues/t01-t10(1 research resolved + 1 grilling + 8 task open)+ IMPLEMENTATION-PLAN.md(A-E 五线:init 保护/key 引导+Responses/告警+三态+doctor/验证轮)
- 地图:Destination=傻瓜化+Responses+验证轮;frontier=t02-t09;blocking:t02←t01(已 resolve)、t05←t02、t10←t09
- 摸到的文件:STATUS.md、.scratch/wayfinder-v17/*(新建 12 文件)

## 三十八、wayfinder-v17 work-through t02(2026-08-04,本会话)
- 一会话一票:resolve t02 拍板 Responses API 集成形态(grilling,question 两轮)
- 拍板:provider 拆分——LlmProviderType=openai(Responses 协议,base_url 可配,DeepSeek 归此)/openai-compatible(chat/completions,custom 并入删除)/anthropic/mock;Responses 失败(404/400)自动回退 chat 一次;多轮累积不做(用户:只做 wiki 辅助,不内置对话);迁移直接不兼容
- 批判性完备性审查(用户要求):发现并补 5 处缺口——max_output_tokens 参数名差异/回退判定边界(仅 404/400)/回退仅一次/system 消息顶层 instructions/ Custom 删除 serde 报错迁移说明
- 计划更新:IMPLEMENTATION-PLAN B3-B6 细化(拆分/双协议/回退/文档),审查结论追加
- 地图:Decisions so far + t02 行;Not yet specified 清 Responses 项;frontier 现为 t03(init 保护)

## 三十九、v17 实施完成 A-F 组 + t09/t10 真实验证轮(2026-08-05,本会话)
- 五线落地(7 commits):A c2f188b(init 缺省跳过/--force 覆盖保护,t03);B 2b4807e(provider 拆分 openai=Responses/openai-compatible=chat+key 引导+默认阵营统一 deepseek);C 2af5a26(mock 占位页脚 MOCK_FOOTER_MARK 单一来源含合成页 api.md+lint 三态退出码 0/1/2+update --dry-run 无副作用);D a6097e0(doctor 五查:配置/产物可写探针/目录状态/Key 空串视为未配/网络 5s 探活 mock 跳过);F 798e062(t09 实测三修复:增量误删 preserved_modules+output.dir root 统一 load_config_rooted 收敛 8 处+相对键迁移保守保留)
- 测试:486→493 passed(clippy -D warnings 0,machete 干净)
- t09 本仓库真实验证(全部实机):doctor 5/5 退出码 0;lint 三态(有 2 问题→1,缺失配置→2);dry-run 变更清单退出码 0 零副作用;init 幂等/--force;Responses 协议真实 DeepSeek e2e 多次成功(SSE 语义化流 729/835/539 chunks,无回退 warn);增量闭环(src_fs.md 恢复+9 页全保留);全量恢复(9 页产物完整,broken 断链清零)
- t10 Unity e2e(SimpleToolkits 6655 cs):mock 全链路 56 页产物 exit 0
- 发现并修复 3 个真实 bug:增量模式未受影响模块页面被 cleanup 误删(6 页断链);--root 场景相对 output.dir 写错目录(root 化收敛);root 化后旧相对键与绝对 rendered 不匹配误删合成页(迁移保护)
- 未验证:Unity e2e 真实 LLM 版;watch Ctrl-C 交互;semantic lint/rubrics 真实 LLM 质量(均有单测,无真实 e2e)

## 四十、v18 分析轮：生产可用性/一键全自动/未完成项完备评估（2026-08-05）
- 3 并行子代理：外部 Agent 视角一键审计（9 问证据化）+ 未完成项全量核对（无 TODO/无 ignore 测试/无未用依赖）+ 网络检索 7 主题（Karpathy llm-wiki 生态爆发 2026-04、CodeWikiBench ACL 2026 68.79%、RepoDoc 增量 -73%/-77%、staledocs/vericontext 确定性检测、AGENTS.md 60k+ 仓库、llms.txt 仅 agent 消费）
- 实机一键流（全新二进制，全部零参数）：init（创建全局配置）→ generate（真实 DeepSeek 149s，4 页+1 卡+AGENTS.md+索引）→ search ✓ → lint（exit 1 检出 2 条噪声）→ doctor ✓（5 查 exit 0）→ update --dry-run ✓ → update 增量 ✓ → status ✓；环境已清理还原
- **新发现 P1 版本漂移零自检**：PATH 0.1.0 旧二进制时 doctor/dry-run/lint 三态全部静默不可用（实测 unrecognized subcommand/Usage 错误 exit 2）；本地 release 若构建于 v17 中期同样缺 doctor——agent 无任何提示
- 新发现 P2 文档 4 处失实：init 全局 vs README 项目级暗示；default_engine 示例 hybrid vs 默认 text；embed 模板(qwen3.7+BAILIAN)/schema(text-embedding-3-small+OPENAI)/README 三方打架；子命令表缺 doctor/dry-run/lint 三态
- 新发现 P2 lint 噪声误报：entity-coverage 单字符/数字（src/2/P/_/a）真实产物+mini 仓库双复现；graph 'mod' 实体类型 warn
- 未完成项定案：P1 仅 Unity 真实 LLM e2e（t10）；P2 测试泄漏 wiki/ 未根治+4 项真实 e2e 未验证；P3 CHANGELOG/tickets/README 文档滞后
- 评估结论：一键=3 命令（install+key+generate）；傻瓜度 6/10（AGENTS.md 优秀，短板=升级自检/文档一致性/lint 噪声）；建议 P0 版本自检+P0 文档统一+P1 lint 噪声过滤（本轮不改代码）
- 报告：.scratch/research/ANALYSIS-v18-oneclick-2026-08-05.md

## 四十一、wayfinder-v19 建图：傻瓜化/自检/生态对齐（2026-08-05）
- 用户 six-question 拍板：范围=全部（含 Unity e2e+生态方向）；init 保持全局链+修文档；版本自检=doctor 检版本+产物注入+README；lint 噪声=忽略单字符/纯数字+补 mod 类型；测试泄漏=helper 强制临时目录；Unity e2e+文档同步并入本轮
- 并行子代理锚点核证：doctor.rs:32 push 式注册（第六查顺加）；state.rs:14 需加 tool_version 字段（前置改造链 G1）；lint.rs:518 entity_name_from_signature 一处改两侧生效；graph.rs:193 kind_from_str 缺 "mod" 分支（parser rust.rs:102/131、csharp.rs:36 合法产出）；llms.txt 确定性重生成=版本注入可靠载体（AGENTS.md 已存在即跳过不可靠）；tests 8 处内联 dir=；impact.rs 双向 BFS 传播已落地（RepoDoc 简化版无需重复）；community.rs:176 命名缺目录频次档
- 网络核证修正：llms-full.txt 非官方规范（社区惯例，llmstxt-gen 8K/32K 模式）；OpenWiki no-op=git-head+工作树快照（非 SHA-256）；vericontext 仓库实为 amsminn；CodeWikiBench 叶子 0/1 judge 聚合（repo-wiki v14 已实现 rubrics）
- 建图：.scratch/wayfinder-v19/map.md + issues/t01-t10（t01 版本自检/t02 文档统一+CI/t03 lint 噪声/t04 测试泄漏/t05 llms-full.txt/t06 no-op/t07 社区命名/t08 文档同步/t09 验证轮 blocked by t01-t08/t10 research 行级哈希）+ IMPLEMENTATION-PLAN.md（A-H 组串行+I 验证轮，每字母组一 commit，批判性审查 G1-G10 含 10 项对策）
- 边界：影响传播实体级分类/二进制分发/评测第二档 → Not yet specified（fog）；Cargo.toml 保持 0.2.0（t08 归档 [0.2.0]，v19 入 Unreleased）

## 四十二、v19 实施完成 A-H 组（2026-08-05）
- A 46bedf4 t03 lint 噪声：entity_name_from_signature 统一过滤单字符/纯数字 token（api 权威侧+页面声称侧同口径）；graph kind_from_str 补 "mod" => NodeKind::Module；测试 +2
- B 0db14f2 t01 版本自检：GenerationState + tool_version Option（serde default 旧状态兼容）；doctor 第六查「版本」三态（首建提示/记录漂移建议升级/损坏不阻断）；llms.txt 头部版本行；测试 +1
- C 9ec7d40 t02 文档统一+CI：default-config.toml embed 段根因修复（删个人环境残留统一 text-embedding-3-small+OPENAI_API_KEY）；README 5 处失实修正+子命令表+doctor 六查；新增 .github/workflows/ci.yml（无 fmt 步骤，项目未 rustfmt 化有注释）
- D c8c12c2 t04 测试泄漏根治：common/mod.rs mock_config/openai_compatible_config 两 helper（绝对路径+反斜杠转义），5 文件收敛，496 passed
- E d94f1b1 t05 llms-full.txt：32K token 预算四档裁剪（完整/去 constant/去无源/精简形态）+省略模块节+确定性排序；测试 +3（确定性/预算裁剪/空卡片）；README Agent 入口文件节
- F 77c9b6f t06 update no-op 空转：should_skip_noop（git-head+statuses 双判据，G3 论证不做 interrupted——失败前有新提交 head 必然≠last，纯外部故障产物无变化跳过无损失）；早退点=load_protection 后 watch_paths 前，与既有无变更短路同出口（sync_manual_edits 不丢）；测试 +5（AtomicUsize 唯一目录防并行竞争）；实机 0.8s/0.7s 双跑验证
- G 7fad509 t07 社区稳定重排序：大小降序+最小 file_path 全序（Graphify 模式），测试 +1
- H d6a5398 t08 CHANGELOG [0.2.0] 归档（v13-v17）+v17 tickets 9 resolved+STATUS 四十四节
- 验证 512→513 passed，clippy -D warnings 0，machete 干净

## 四十三、v19 I 组验证轮 + t10 research 定案（2026-08-05）
- bench 安全闸修复 29e8ff4：IGNORED 条目过滤（reset --hard 不碰被忽略文件，产物目录不再误判脏工作区）+ bench-out/ gitignore 8cf41cf
- **Unity 真实 LLM e2e 完成**（t09 项1，P1 唯一缺口）：SimpleToolkits（D:\UnityProjects，143 cs 文件/2111 实体/5237 边/52 模块），Responses 协议 SSE 全链路无回退 warn，131 分钟（7859084ms），42 页+52 卡+AGENTS.md+llms.txt/llms-full.txt+图；lint 健康：bad-citation 0/bad-mermaid 0/orphan 0/stale 0；948 stale-entity+133 entity-coverage+53 broken 均为 api.md/architecture.md LLM 幻觉类（机制正确工作，质量信号问题）
- **Update Recall 100%**（t09 项2）：本仓库 mock bench 回放 20 commit（19 有变更全部触发重生成），安全闸修复验证通过
- rubrics 自评（t09 项3）：未验证——bench --judge 与 recall 耦合需真实 LLM 20 commit 成本不可接受（如实记录）
- t10 research 定案：不建议实施 vctx 完整格式——repo-wiki 引用真源为正文 path:line（无注式格式），行级哈希与既有 stale/stale-entity/bad-citation-overlap 高度重叠；成本近乎零（lint 已读文件仅增哈希）但增量价值低；报告 .scratch/research/t10-vericontext-2026-08-05.md
- 全部 10 ticket resolved；STATUS 四十五节；git log：A-H+2 收尾 共 10 commits（46bedf4→8cf41cf）

## 四十四、v20 分析轮：生产可用性完备度 + 未完成项全量核查（2026-08-05）
- 3 并行子代理：A 外部 Agent 视角审计（P0 0/P1 0/P2 3/P3 5）；B 未完成项 8 项核查；C 网络 8 主题
- **关键归因修正：948 stale-entity 非 LLM 幻觉**——抽样 50/50 真实存在于源码，真相=C# 解析器把私有字段/属性当实体提取（口径比文档覆盖细）；改口径需联动 measure_coverage（bench 共用实体源）
- **git2 三通告逐条核证**（RUSTSEC-2026-0008 Patched>=0.20.4 已满足；0183/0184 影响 Remote::list/Blame 两 API repo-wiki 零使用）——不构成实际风险，无需升级 0.21；子代理 C「需升 0.20.5」失实（该版本不存在）
- **P2-1 实锤：no-op 后 stdout 误导**——无变更跳过时 stdout 仍打「增量更新完成: 扫描 0 个文件」+「产物检查通过」（main.rs:413-417 vs lib.rs:261），跳过消息仅 stderr tracing；外部 Agent 解析 stdout 误判已更新
- 新发现：graph 未知实体类型 'static'（rust.rs 生命周期误解析，v19 'mod' 同类，P3）
- 实机验证：中途被杀 update 状态未破坏（防失败吞噬生效）；mock 配置必填项逐字段报错引导良好
- 其余未完成项（rubrics 独立 flag S/Unity 增量规模测试 M/Linux CI 实跑/实体级 diff L/分发 S 卡账号/第二档评测 M）保持开放
- 报告：.scratch/research/ANALYSIS-v20-production-2026-08-05.md

## 四十五、wayfinder-v21 建图：生产就绪收尾（2026-08-05）
- 用户加载 wayfinder skill：question 两轮拍板——①范围=全部含 M 项（P2/P3/S + Unity 规模 fixture + 第二档评测框架；实体级 diff/分发/CI 推送排除）②实体口径=「文档覆盖也要更细」③rubrics 拆独立 flag ④'static' 修复 ⑤合成大 fixture ⑥publish/CI 全排除留 fog
- t01/t08 research 子代理完成：NodeKind 14 变体无 Field/Property（C# 字段→variable 无可见性过滤 csharp.rs:52-85）；api.md 确定性渲染已含 variable（markdown.rs:72）——「覆盖更细」缺口在 lint 假漂移与 prompt 名额而非渲染端；prompt 注入 take(30) 无排序（wiki.rs:341），30/60 实为描述字数（澄清 v19 fog）；字段级 ×1.29 挤占名额；api-ref 模板无防编造条款
- t02 三拍板（question 第三轮）：渲染端增强标注（api.md 实体行加 kind/可见性，数据源已备）+ stale 根因先实机核证再修（I 轮 Unity 抽样 20 条）+ prompt 30 排序+排除字段级
- 建图落地：.scratch/wayfinder-v21/{map.md, issues/t01-t10.md, IMPLEMENTATION-PLAN.md}；t01/t02/t08 resolved，t03-t10 open；计划 A-I 组（A stdout 契约+AGENTS.md+api-ref 契约 / B P3 文案 / C 'static' / D rubrics-only / E 清单跑分 / F 150 文件 fixture / G 渲染标注 / H prompt 名额 / I 验证轮）+ G1-G12 批判性审查 + 防回归矩阵

## 四十七、v21 验证轮（I 组，2026-08-05）

- **Unity stale 核证闭环（t02 拍板「先实机核证再修」）**：并行子代理等距抽样 20 条 20/20 真实存在（0 幻觉）；全量 1780 实体行 fileMissing=0/lineOOB=0
- **根因一（提取）**：lint.rs entity_name_from_signature 三类误提取（继承段/泛型参数/属性宏）——已重构修复
- **根因二（跨 cwd，真凶）**：source_roots_from_include 返回相对路径，--root 指向其他仓库时 lint 扫描 cwd 而非目标仓库。修复：新增 source_roots_from_include_rooted（相对 root 绝对化），lint/status/update 尾部复核/MCP status 四处统一（commit 8c165e1）
- **Unity 仓库重验**：stale-entity 1000 → 13 条（剩余全部为 api.md 的 LLM 幻觉实体，如 null/private/Dictionary 泛型引用，与子代理预估 9-13 吻合）；broken 53 为 v19 旧产物 LLM 链接质量问题（重生成即修复）
- **rubrics 自评首跑（mock）**：bench --rubrics-only 跑通（coverage 97.4%=1080/1109、doc_info 8 页、update_recall 正确跳过回放、tqs/rubric=null 属 mock 预期——Rubric 生成需真实 LLM 结构化输出，mock 下 3 轮全部「Rubric 节点字段缺失」）
- 本仓库 lint 回归：退出码 0/1/2 三态不变
- 遗留：Unity 真实 LLM 重新 generate 后 broken 自然清零（未做——产物更新需 2 小时真实调用）；rubrics 真实自评未跑（需真实 LLM+成本权衡，与 recall 耦合已拆）

## 四十八、v22 删除场景缺陷修复 + Unity 增量实测（2026-08-05）

- **删除场景缺陷（跨轮遗留，用户指定优先）**：changed_insights 空时快照回填分支只按整模块全删过滤，多文件模块删一文件 → 页面残留被删实体。修复（commit 16085af）：回填分支推导 surviving 模块 → 存活文件并入 changed_insights 走正常 LLM 路径；IncrementalResult 新增 has_deleted_files 信号（git-diff 主路径 = deleted 非空 / watch 路径 = 文件消失）；generate_global_documents 与 index 门控放行删除场景（页面/索引/概览不再列已删模块）
- **新测试**：test_delete_one_file_in_pair_module_regenerates_module（150 文件 fixture 体系新增 build_pair_module_repo：m20 双文件互调同社区 + solo.rs 孤立；判别信号=documents 含 src::m20 不含 solo、长度 ≤5、磁盘模块页保留、solo 页零改写）
- **Unity 真实增量实测（SimpleToolkits，全部通过）**：改 KitManifestTests.cs 插注释 + commit（92d4e71）；dry-run 1 文件/2 模块；真实 update 成功——状态推进、产物 MOD 9/NEW 11/DEL 0、overview/architecture/35+ 未受影响模块页零改写、无页面误删；生成 5 模块 vs dry-run 2 模块归因=affected 模块文件覆盖的 graph 模块（chunk 遍历取非空，保守放大非回退）；第二次 update 正确 no-op
- **lint 提取修复补提交（commit 7408719）**：v21 I 轮 entity_name_from_signature 重构（属性宏/继承段/泛型剥离）当时未提交，本轮补交
- 测试基线：396 lib + 全部集成绿；clippy 0；Unity broken 清零验证（真实 regenerate）后台进行中

## 四十九、v22 配置硬编码简化 + Unity 真实 regenerate 完成（2026-08-05，本次会话）

- **背景**：v20/v21 分析确认 10 项配置几乎无调参价值（max_concurrent/max_tokens/temperature/batch_size/index_dir/default_engine/default_top_k/rrf_k/max_depth/plan.path）
- **决策**：10 项全部硬编码为 src/config/schema.rs 顶部常量（单一真源，含中文注释）；保留 20 项真实差异配置（provider 族/scope/输出目录/增量开关等）
- **实现**（commit ec259bc，20 files +121/-217）：schema 删 10 键与 3 个默认函数；llm.rs/embed.rs/mod.rs/lib.rs/main.rs/mcp.rs/plan.rs 8 处改用常量；run_git_diff/run_file_watch_incremental 参数瘦身；default-config.toml 模板与 README 配置节同步删键（注释指向常量）；受影响测试断言更新（请求体不再写 max_tokens/temperature、search 条数回退硬编码 10）
- **验证**：523 passed（394 lib + 129 集成）、clippy -D warnings 0、machete 干净；旧配置残留键被 serde 忽略（向后安全）
- **Unity 真实 regenerate 完成**（7808 进程，max_concurrent 实测并发 8 生效）：54 页产物（42→54 补全），全量 LLM 生成无回退 warn；broken 链路待 lint 复核（生成 131 分钟）
- 未验证：Linux CI 实跑（需 remote）、rubrics --judge 真实自评（需真实 LLM 且与 recall 耦合）

## 四十九节（v22 修复轮收尾：评测框架真实首跑）
- 评测首次真实 LLM 端到端成功（rubrics 3 轮生成+合并+叶子判定全过，此前因推理型模型吞输出预算全败）
- 根因修复：trait 新增 complete_with_budget（OpenAI/Anthropic 流式+显式预算），BENCH_MAX_OUTPUT_TOKENS=16384；parse_rubric_tree 容错（字符串 sub_tasks/权重）
- 实测（repo-wiki 自评，deepseek-v4-flash，11 分钟）：coverage 93.1%（1124/1046）、TQS avg_total 7.73（kappa 0.27/pb 0.3）、Rubric score 0.111（163 节点/115 叶/12 满足）、lint 187 项（bad-citation-overlap 81 主项）
- 提交 e5626ff；529 passed（400 lib + 129 集成），clippy 0，machete 干净

## 第五十节（v23：实体级 diff 分类 + 验证轮实机闭环）
- **A1 实体级 diff**（commit ad3e0f0）：change.rs compare_entities 同 kind 精化（body 三元组逐对比较）+ no_entity_change_files 公共函数；GitDiff/FileWatch 双路径 classification_failed 保守回退（不剔除）；generate 过滤跳过无实体变更文件；防回归=空格-only 变更测试（场景 F）；顺带修复 read_old_entities 二进制旧文件 Err 与 default-config.toml 个人环境残留
- **B1 实体表键形态**（commit 08333a9）：lint.rs citation_key 统一（绝对化+过滤 CurDir+norm_sep），修复 include 通配派生 ./ 前缀导致的 overlap 检查静默失效（SA2）；citation.rs 注释闭区间语义修正；防回归测试（./ 与常规形态一致）
- **C1 失败模块落盘顺序**（commit 410bfb2）：save_generation_state 读取真源 failed_modules（此前在赋值前执行恒为空数组，v22 补偿对全量 generate 静默失效）；实机闭环=全量 generate 3 模块失败→状态含 failed→update 补偿补生成→状态清空；401 lib 绿
- **D 组 rubrics 三轮基线**（budget 修复 + measure_lint root 化，未提交）：e5626ff 漏改 2 处 complete_with_budget（rubric 生成/叶子判定轮）；measure_lint 用未 root 化的 source_roots（v21 遗漏，bench 与 CLI lint 口径分裂 12 vs 1）；修复后第 3 轮预期 lint 回 44 口径
- **实机数值（本仓库）**：coverage 1.0（1340/1340）；TQS judged 2-3 模块、avg_total 7.5-7.86、kappa 0.277-0.352、pb 0.1；Rubric score 0.033-0.111（satisfied_leaves 0-2/52-60，判定证据=摘要形态保守 bias，设计权衡非缺陷）
- 存疑项：tests_edge.md 独立页漂移（tests::edge 并入 tests 社区聚类）→ broken 引用残留；stale-entity/entity-coverage 为 LLM 内容噪声（lint 可检出不可根治）

## 第五十一节：v24 配置分层重构
- **用户需求**（m02837）：分清全局（用户级）与项目级文件夹；配置等非项目内容必须在用户级；项目级不得自动创建配置文件。
- **拍板三项**（m02840）：项目级独立文件 .repo-wiki.toml / Codex DENYLIST 敏感键净化模式 / MCP 同链。
- **变更**（commit 5a871d8，11 files）：项目级配置独立文件与产物目录 .repo-wiki/ 物理分离；敏感键净化（llm 4 键+embed 3 键忽略+告警+注入 schema 默认防必填缺失）；移除 install 项目级自动创建点（历轮审计漏检的真实违规点）；install_wiki/MCP/init 适配。
- **验证**：29 套件全绿（404 lib+集成）、clippy 0、machete 干净；实机三验（fake-APPDATA 隔离：自动创建用户级全局/净化 warn 生效/项目级未被创建）。
- 边界：显式 --config 指向 .repo-wiki.toml 同样净化（逃生门不豁免）；其他文件名不净化（逃生门）。

## v26（2026-08-05/06）：目录超节点聚类与版本 0.3.0

- 需求：模块划分跨次稳定（v23 实测新增文件重排聚类→Unity 模块页缺失根因）
- 方案演进：方案 D 目录超节点图 Leiden → 实测过度合并（CPM 对聚合权重失真，99 文件只剩 2 模块页）→ 修正为规模分流：
  - 目录数 ≥ 24：纯目录页（页面名=目录路径，零随机参数，结构级稳定）
  - < 24：实体级 Leiden（v23 行为，γ=0.5 实测调优）
- 验证：community/git_e2e/large_fixture 全绿；mock 实机本仓库 14 页（实体级）/+Unity 56 页（52 目录页）
- 版本：0.3.0（破坏性：模块页名=目录路径）；CHANGELOG [0.3.0] 归档 v13-v26
- 提交：1251a74 + 修正 + 归档（3 commits）
- 测试基线：全量绿 + clippy 0 + machete 干净
## v27（2026-08-06）：剩余项闭环与 Unity 增量实测

- 盘点剩余项结论：rubrics 判定证据形态改进（d9a30d9 方案甲：requirement 关键词
  extract_keywords CJK 2-gram + search_pages top-2 页正文 3000 字符拼入，总证据
  cap 20K，无命中退化维持现状）、key 管理向导（c4feb93 交互式 key 子命令：
  stdin 明文写用户级 default-config.toml，绝不写项目级，mock 跳过/env 早退/
  --env 指引/写后验证，6 单测）、实体级 diff 分类（v23 A1 三元组判定）、
  版本号决策（v26 0.3.0）——均已实现并提交
- Unity 增量实测（v26 目录页语义，SimpleToolkits mock）：全量 38 页（34 目录页
  +4 合成页）→ 改文件 commit → update 页名集合 38=38 稳定（removed/added 空）
  → 删文件 commit → update 目录页保留（目录仍在）+ 页数稳定；测试后仓库
  完全还原（Test.cs/ExampleManager.cs 恢复、.repo-wiki/AGENTS.md 清理、
  .gitignore 保留）
- 全量验证：cargo test 414 lib + 各套件全绿、clippy 0、machete 干净、工作树干净
- 提交：d9a30d9/c4feb93（早前）+ 本轮无代码变更（验证轮）
## 五十二、v28 评测科学化+生态对齐（2026-08-06）
- 建图：wayfinder-v28（.scratch/wayfinder-v28/，12 tickets，4 research resolved）
- t02 评测清单：manifest RepoEntry commit 字段钉死（checkout 验证）+ 双清单
  knowing.manifest 16 仓（原样 commit）+ codewikibench.manifest 22 仓（HF 不可达
  commit 缺省 HEAD）；mock 全量基线 knowing-small 6 仓全绿（caddy 2781 实体/
  cargo 3801/flask 408/ripgrep 1678 等；glob 花括号形态实测不支持已避免）
- t04 judge 升级：TQS +9 字段（kappa_cohen/flip_rate/position_flip_rate/
  delta_kappa/eligible/parse_rate/尺度声明/tie 声明）+ repeats 3→5 低置信升级 11
  + rubric 叶子 3 次多数投票（1:2 升级 5 次，无多数 abstain 不再 recode false）
  + option 随机化；t09 实测 flip_rate 0.477 触发升级 ✓
- t06 vericontext：拍板 lint 只读校验——bad-vctx 检查（5 步哈希 SHA-256 前 8 位，
  四类失败：解析/越界/哈希/路径）
- t07 llms.txt 新鲜度：stale_by_age（>7 天 warn，mtime 判定不破坏确定性契约，
  初版时间戳注入致 test_determinism 哈希差已重写）
- t08 AGENTS.md 模板对齐：生态结构（<200 行/可证伪/单一基线）
- t10 目录阈值测试：20/24/30/40 边界 fixture + make_dirs_graph 重构
- t11 一键安装 e2e：P1 断裂修复（模板 base_url 注释态→serde None→LLM 打到
  OpenAI 端点模块页全失败；修复=模板显式 DeepSeek base_url）——隔离环境
  install→generate 86s 全通 5 页 failed 空
- t09 真实 LLM：flask 钉死 commit 跑分 478s（408/408 覆盖、lint 50 噪声如实）；
  rubrics 复测 18 分钟（--rubrics-only --judge 互斥已解除，7f1cb66）：TQS
  kappa_cohen=-0.31/flip_rate 0.477/position_flip_rate 0.955（位置偏置显著）、
  rubric 0/51（多数投票滤除 v23 的 22 条随机假阳性——设计意图达成）
- repeats 字段失真修复（升级已执行但报告恒 5，t09 实证）
- 验证：29 套件全绿 432 lib、clippy 0、machete 干净
- 提交：f30a9fe/5ae6793/9753011/146461d/5e7b547/7f1cb66/repeats 修复（共 7）

## 五十三、v29 双缺陷修复（lint 模块名误报 + 单目录退化保护）（2026-08-06）
- **缺陷 1（P3 噪声）**：lint entity-coverage 把 api.md 的 `## ` 节标题（模块名，容器名）当未知实体误报——合成页（architecture.md 等）按模块名引用（如 `src`、`src::storage`）不在叶子实体清单中。
  - 修复：新增 api_module_names（`## ` 节标题集合）纳入已知名；声称行原文精确命中模块名即放行（多段名 `src::storage` 经实体提取会被 `::` 截断为 `src`，必须原文匹配）；实体声称仍须命中叶子清单（防幻觉语义不变）。
  - 防回归：test_lint_entity_coverage_accepts_module_names（`## src`/`## src::storage` 的 api.md + 引用两模块名 + 编造名 GhostEntity → 仅报 GhostEntity）。
- **缺陷 2（fog）**：目录数 == 1（全部源文件平铺同一目录）走实体级 Leiden，整库聚成 1-2 个社区或每文件一社区，模块划分失去意义。
  - 修复：detect_communities_with_resolution 分流条件改为 `dirs.len() <= 1 || dirs.len() >= MIN_DIRS_FOR_SUPERNODE`——单目录直接走目录页路径（单一社区 = 全部文件，模块名 = 目录名，<root> 根目录散文件同此）。
  - 防回归：test_detect_communities_single_dir_repo（10 文件全在 dir00/ → 1 社区含全部文件 + 确定性；根目录 5 散文件 → 整体 1 社区）。
- **验证**：29 套件全绿（559 测试：434 lib + 125 集成）、clippy --all-targets 0 警告（强制全量重编核验）、cargo machete 干净；本仓库自身 api.md 的 `## src`/`## src::storage` 与修复语义互相自洽。
- **未提交**：按任务要求不提交；与主线并行会话（mixed 场景修复 generate/mod.rs + test_incremental_large_fixture.rs）共存于工作区，未改其文件。

## 五十六节 v29 验证轮（2026-08-07）

- 3 并行子代理完成：A knowing 剩 10 仓 mock 跑分（django/jekyll/kafka 完成，大仓 20-35 分钟/仓，GitHub 直连不稳 SSH 可靠，10 仓预克隆+钉死 commit 留档）；B 删除场景 mixed 修复（surviving 逻辑提前主路径，防回归）；C 短名+单目录分流（lint 模块名放行+community 单目录目录页）
- 提交：97e29b7（B）/2f17b5d（C）/docs（STATUS 五十三-五十五+task_plan.md）；全量 434 lib+clippy 0
- 本仓库真实 regenerate（v29selfgen.log）：99 文件/1821 实体/23221 边/11 模块/419042ms
- lint 复测三连实证：默认链 200+ stale=配置不一致（lint 默认 scope vs 生成显式配置）；同配置 stale=14 条标准库/泛型噪声（已知）；entity-coverage 残留=LLM 幻觉捕获（test_clean_load 等源码不存在，正确行为）；v29 产物 bad-citation=0/broken=0（v28 的 27 bad-citation 系旧产物 LLM 编造，regenerate 后消失）
- rubrics 三连测：第一轮 TQS 成功（kappa_cohen -0.50/flip_rate 0.5/parse 97.6%/low_confidence=tests），rubric 生成阶段起 402 Insufficient Balance（DeepSeek 余额耗尽）；第二三轮全 402；错误处理路径验证通过（生成失败 3 轮→跳过 warn→rubric null 不中断；TQS 失败→null 不 recode）
- 归因修正：v23 satisfied 22/52 vs v29 0/51 系资金中断非多数投票保守化
- 阻塞：真实 LLM 验证（rubrics 复测/大仓库跑分）需充值或换 key
- 遗留：knowing 9/16 仓 mock 数据点；CodeWikiBench 22 仓清单留档（HF 不可达 commit 缺省 HEAD）；bad-vctx 4 条（v29 产物中人工 vctx 校验捕获）

## 五十七节 v30 傻瓜式自动化配置（2026-08-07）

- 用户拍板：plan 彻底删除；dir/embed/search/incremental 硬编码删字段；删 expand_languages
- 硬编码：output.dir=\.repo-wiki（OUTPUT_DIR 常量）/ embed.enabled 恒 true（无 Key 自动降级）/ search.enabled 恒 true / incremental 恒 FileWatch 监听模式（内容 SHA256 指纹，非 Git 仓库可用）/ expand_languages 删除
- plan 整体删除：wiki_plan.yaml/plan.path/白名单/模块规划全移除；删 src/config/plan.rs + tests/test_plan.rs + serde_yaml 依赖
- output_dir 改为运行时注入字段（serde skip），output_dir() 方法统一访问；模板精简为 wiki/scope/llm/embed 四段
- 语义索引运行期失败降级（不再中断主流程）；非 Git 仓库 FileWatch 增量修复（空分类保守保留起点）
- watch 端到端竞态修复（测试改文件前等 notify 注册窗口）；删除检测补强（指纹表∖insights）
- 验证：423 lib+27 集成套件全绿、clippy -D warnings 0、machete 0
- 提交：ed2c5be(重构)/fa61851(测试)/9556bc2(文档)

## 五十八节 v30 收尾+剩余项推进轮（2026-08-07）

- A1 anti-fabrication 补强：卡片 prompt 约束 key_entities 只列真实实体；架构 prompt 约束模块只列输入模块（e36f9dd）
- A8 实体引用清单注入：wiki page user prompt 增加实体名+类型+文件:行号真源清单（截断 80 条）——修复引用契约不可兑现的结构性缺口（v29 bad-citation 来源）
- A2/A3 本仓库 FileWatch 增量基准（mock 隔离输出 .repo-wiki-mock，release 二进制）：
  全量 3s（66 文件/1502 实体/5 模块）；no-op 注释 0 模块跳生；新增实体文件 2 模块受影响+新页+api.md 真实行号 2s；删除文件 5 模块传播+清理 2 产物+索引删 2 条 2s；语义索引降级路径实测（mock embed 失败→保留旧索引→纯文本回退 warn）
- A6 发布流程文档：README 新增发布节（cargo publish+tag+干净环境六查自检）
- A9 knowing 剩 7 仓 mock 跑分：2 并行后台子代理运行中（A: vscode/kubernetes/terraform/saleor；B: rails/spark/cal.com），结果落 C:\Users\WenYu\AppData\Local\Temp\opencode\knowing-a|b\results.md
- 提交：e36f9dd（prompt 补强+文档）；全量测试+clippy+machete 全绿

## 第五十九节 A9 knowing 16 仓全仓数据点完成（2026-08-07）

- 子代理回收：vscode 1492实体/71文件/11模块/2.6s；rails 5239/58/24/58.4s（JS资产口径）；spark 2182/184/42/4.3s；cal.com 59047/5048/1502/372.3s
- 无数据 3 仓（kubernetes/terraform/saleor）：非 Rust 主语言，include 命中 0 文件，lib.rs:308-310 显式报错（正确边界，非静默）
- 边界结论：多语言 parser 实证（JS/Java/TS，parser/mod.rs:248）；Ruby 无 parser；rails 数据代表性受限已标注
- 汇总归档：.scratch/bench/knowing-summary.md（git 忽略）
- 全仓 16/16 数据点完成（v29 9 仓 + 本轮 4 仓 + 3 仓显式报错）

## 五十九节 v30 净化/注入规则彻底删除（用户拍板）
- 删除：SANITIZE_DEFAULT_INJECT 常量、inject_defaults_project_config、strip_injected、load_config 的 is_project_level 分支、load_default_config_with 注入链（净 -136 行）
- schema.rs：LlmSection/EmbedSection/WikiSection/ScopeSection 全部字段级 serde(default)，缺键即用 v29 可用阵营
- 测试：注入测试改名为 defaults_for_missing_keys（语义=serde 默认兜底），explicit 测试注释更新（文件名无差异）
- 验证：cargo test 426+28 套件全绿；clippy -D warnings 0；machete 0；doctor 六查全绿（config.toml 完整生效：OPENCODEGO2_API_KEY+opencode 网关可达，4 条误导 WARN 消失）
- 提交 c1c19c3
- 分析结论（未改代码）：include/exclude 语义互补均保留（白名单防漏扫/黑名单防扫错，include=[] 即全量已支持）

## 六十节 v30 扫描零配置（用户拍板，2026-08-07）

需求：scope.include/exclude 彻底删除（不同项目文件夹不同，不傻瓜）。

落地：
1. scanner.rs 全量遍历重写：Scanner::new(root)（无 scope/无 Result）+四层内置边界
   ——.gitignore（standard_filters(true)）/内置噪音目录 NOISE_DIRS（node_modules/
   .venv/dist/target/__pycache__ 等）/支持语言扩展名自动识别（SUPPORTED_EXTENSIONS
   11 种：rs/ts/tsx/py/go/js/jsx/mjs/cjs/cs/java，与各处理器一一对应）/二进制与
   MAX_FILES 上限（超限显式报错）
2. schema.rs 删 ScopeSection；config.toml 模板四段→三段（wiki/llm/embed）；
   旧配置含 [scope]/[output] 段静默忽略（serde 默认行为，不报错）
3. watch.rs 监听根恒=仓库根，事件按支持扩展名+NOISE_DIRS 过滤；
   run_watch_loop 删 config 参数
4. incremental no-op 判定改 status_has_source_changes（全仓库任何变更=源码变更，
   唯一例外=产物目录 output_dir 与 AGENTS.md——AGENTS.md 是 generate 自动写入的
   代理导航模板，修复后 no-op 回归实测恢复）
5. generate/schema.rs collect_sql_files_at 独立全量遍历（.sql 不在语言清单）
6. ingest 全链删 config 参数（scan_and_parse_at/scan_and_parse_cached_at）
7. 净化删除轮（五十九节）已提交 37bc04e；本轮提交 fda070a（31 文件 +314/-516）+
   b90dfc6（docs）

验证：423 lib+28 集成套件全绿；clippy -D warnings 0；machete 0；冒烟 generate
（临时仓库 1 文件 3 实体 2 边 49ms 产物 5 页）；no-op 手动复现（修复前 AGENTS.md
阻断 no-op→修复后「无文件变更，跳过更新」恢复）；embed 运行期失败降级保留旧索引
实测。

## 六十一节 真实 LLM 评测轮（A11 完成，2026-08-07）

解锁：OPENCODEGO2_API_KEY（opencode 网关）可用，A7/A10/A11/A12 的 402 阻塞解除。

真实生成冒烟：本仓库真实 generate 717729ms（~12 分钟），15 页/12 卡片/12 模块，语义索引 1576 实体真实向量化（百炼 embed），api.md 引用行号真实。

A11 rubrics 复测（bench --root 本仓库 --rubrics-only --json，judge=deepseek-v4-flash 真实）：
- TQS：judged 2 模块，avg_total 8.65（clarity 8.95/readability 8.84/conciseness 9.0/richness 7.68/structure 8.77），repeats 11，kappa_like 0.83，flip_rate 0.52（位置翻转率高=judge 稳定性已知问题），parse_success 1.0
- Rubric：77 节点/65 叶子，satisfied 4（覆盖率 6.2%，score 0.063）——CodeWikiBench rubrics 树期望的文档形态（示例代码/教程步骤/交互功能）与 repo-wiki 生成的 Wiki 形态（api.md/architecture 参考型）不匹配，为真实评测结果而非缺陷
- Coverage：实体覆盖率 1.0；lint 45 项（bad-vctx 4/entity-coverage 27/orphan 1/stale 13）
- generate_ms 0（复用既有产物，bench 不重生成）

knowing 全量 12 仓 mock 数据点齐（v29 9 + v30 3：rails 5239 实体/58 文件/58.4s、spark 2182/184/4.3s、cal.com 59047/5048/372.3s——大仓 MAX_FILES=100000 后通过）。
## 六十三节：v31 Token 节省（2026-08-08）

### C-01 删除实体摘要 LLM 调用
- 删 generate_entity_summaries（全量/增量两路径）+ entity_summary_prompt + Entity.summary 字段 + 57 处构造点
- 提交 d50cb3d（17 文件 +61/-187），测试 79/10/5/19/4 定向绿，双门通过

### C-03 增量空 chunk 不记 failed_modules
- 管线入口过滤 + generate_all_cards 循环内跳过 + module_names 与 handles 同源收集
- 修复 failed_modules 污染导致 should_skip_noop 永久失效、无关模块补偿重试
- 提交 277c16d + 26cb62e（test_engineer 边界测试 3 个），双门通过

### C-02 describe_modules 单次遍历共享 + 落盘缓存
- 内存 memo（generate_architecture/overview 共享一次 LLM）+ 指纹落盘缓存（.state/module_descriptions.json，键=模块文件指纹）
- reviewer REJECTED 指纹基准 bug（output_dir 拼接→恒 missing→缓存永不过期）→ 修复为项目根基准（root.path().join，对齐 state.rs:131）
- 提交 8db5685 + 2396244，双门复审通过（5 验收点 SATISFIED + 22/22 定向 + 100/100 集成）

### C-07 watch 冷却窗口
- 高频编辑事件累积 pending，安静 2s（尾沿）/ 首个事件后 5s（强制）触发一次合并增量
- reviewer REJECTED 双缺陷 → 修复：跨批按时间序覆盖（删除重建收敛为 Created 不误删产物页）+ 5s 强制在持续事件流下可达 + 循环尾复用 should_flush（DRY）
- 提交 82d7500 + b98a730 + 7f59a6d，双门复审通过（24 watch 单测 + e2e 3 + 全量 560）

### 验证
- 全量 29 套件 0 失败、clippy -D warnings 0、machete 0
- 提交链 9 个（d50cb3d → 26cb62e）

### v32 评测体系升级与生成引导（6.1-10.5 全完成）
- 评测：--repodoc 五维对齐输出、judge 三态增强（tie_rate 阈值 0.3）、Completeness@K、rubrics 证据检索注入、TQS repeats 5 与 κ/flip 稳定性度量；基准换轨 RepoDocBench 五维（论文 arXiv 2604.26523）
- 签名级片段注入：prompt 实体清单加签名行（8 行/160 字符截断）；生成引导：[wiki.guide] 段 pages 过滤/priority 排序/notes 注入
- 大仓性能：分段计时（10 段）+ 图构建增量索引重构（cal.com 287s→20s，total 384s→119s）
- 小项：语义降级标记与显式提示、页面 git 基线行（非 git 省略）、归档文件 UTF-8 核证（乱码=终端 gb2312 假象）、README lint 9 类+限制项对齐
- 提交链 14+（17acaa3→9173fa2）；全量 35 套件绿 + clippy 0 + machete 0；工作树干净

## 六十四节：v33 安装集成合并（2026-08-09）
- 修改的功能：install-wiki/uninstall-wiki/install-to-opencode/uninstall-from-opencode 四子命令删除，全部并入 `install`/`uninstall`——install 默认：用户级全局 opencode.json MCP 注册（OpenCode 原生 mcp 键，type=local+exe 绝对路径+enabled）+ OpenCode 插件（内容比对升级）+ AGENTS.md 引导块注入 + git hooks（post-commit/post-merge）；`--claude` 加写项目根 .mcp.json（Claude Code/Cursor）、`--codex` 加写 ~/.codex/config.toml（[mcp_servers.repo-wiki] 表）、`--also-claude` 同步 CLAUDE.md；uninstall 无 flag 幂等全清（MCP 条目/插件/wiki 块/hooks/旧 .opencode.json 残留，数据与用户级配置保留）；带 repo-wiki 标记的旧产物升级覆盖、人工产物保留+提示
- 摸到的文件：src/config/mcp.rs（新建 719 行：OpencodeMcp/ClaudeMcp/CodexMcp 三格式读写，Codex 文本级表编辑零新依赖）、src/config/opencode.rs（OpenCodeConfig::new(root) 修复 --root 高优缺陷 + config_dir 双缺失报错 + 插件模板 include_str 内嵌修复自举缺陷）、src/commands.rs（install/uninstall 重构，-308 行）、src/main.rs（枚举/flag/分派）、tests/*（test_install_opencode/test_install_wiki/test_hook_install 重写适配 + test_cli/test_cli_smoke）、README.md/CHANGELOG.md
- 是否改变了接口/契约：是（未上线无存量用户）——CLI 四子命令移除、install/uninstall 语义扩展（原 install 无 MCP 注册、现默认注册全局 MCP；uninstall 原仅插件）
- 验证：全量 458 lib+集成套件 0 失败；clippy 0；machete 0；实机闭环（隔离 HOME：install 注册全局 MCP 条目断言 mcp.repo-wiki.type=local+command[0]=exe 绝对路径 → uninstall 条目移除 opencode.json 变 {} → 再 install 幂等恢复；插件 replace 命中注入绝对路径；人工 post-commit hook 保留提示）；自举缺陷实机发现并修复（uninstall 删除插件文件后模板源同文件丢失→include_str 内嵌）
- 提交链：b4b6a5a（主合并）→ ff14fa3（自举修复）
- 遗留/风险点：全局 MCP 条目被其他仓库 uninstall 波及（提示已注明）；多 Agent 未真机验证（Claude/Codex 配置写文件路径与格式单测覆盖，无对应客户端实测）

## 六十五节：v33 生产可用性审计改进（2026-08-09）
- 背景：用户要求全面分析「个人/小团队本地安装生产环境是否可用」——3 条并行 lane（explorer 本地足迹盘点 + 2×researcher 网络权威检索：LLM 文档工具生产共识 13 来源 + Rust CLI 部署实践 22 来源）→ 分析报告（可用结论 + 9 项差距矩阵）→ 用户拍板「全部实施」4 项
- 修改的功能：①fsync 补齐（write_file_atomic rename 前写句柄 flush+sync_all，消除断电截断窗口）；②embedding 模型版本化（.search/embed_model.json 持久化构建时模型名，增量路径检测同维度模型升级/旧版索引标记缺失即回退全量重建语义索引——维度探测只覆盖维度变化的盲区补全；判定抽纯函数 embed_model_mismatch 可单测）；③清理脚本 scripts/cleanup-test-residue.ps1（UTF-8 BOM 兼容 PS 5.1，预览/确认两段式，清理 key-test-*/repo_wiki*/rw_desc_*）；④README watch 三平台托管模板（systemd 用户服务/launchd LaunchAgent/Windows 任务计划 RestartOnFailure）+ 清理脚本说明
- 摸到的文件：src/fs.rs（+15/-5）、src/lib.rs（+134/-22：标记三函数+mismatch 判定+build/增量两处接线+单测）、src/generate/wiki.rs（flaky 测试泄漏根治：PID 命名临时目录开头清理）、scripts/cleanup-test-residue.ps1（新建 83 行）、README.md/CHANGELOG.md
- 是否改变了接口/契约：否（全部为内部实现与文档；新增私有函数无导出）
- 验证：全量 459 lib+全部集成套件 0 失败；clippy 0；machete 0；新单测 test_embed_model_marker_roundtrip_and_mismatch（写读往返/升级判定/损坏/缺失标记）；PS 5.1 实机解析通过（预览发现 417 key-test-* + 2313 临时目录残留）；test_engineer 发现 2 处缺陷已闭环（ps1 无 BOM→PS 5.1 ParserError 修复；describe_modules 缓存测试 Windows PID 复用 flake 修复）
- 提交：eaa3f25
- 遗留/风险点：模型重建全链路（增量触发）依赖真实 embed key 未在 CI e2e 覆盖（判定逻辑单测覆盖，留待真实环境）；fsync 极端断电仍非绝对保证（FITO 视角：失败可重建为第一道防线）；opencode.json 明文 API Key 为用户文件（备份/分享前脱敏提示）；%TEMP% 残留目录清理建议定期执行脚本

## 六十六节：README 重构与 AGENTS.md 人工段修正（2026-08-09）
- 背景：用户要求全局深度检索分析后重构 README——3 条并行 lane（explorer 本地结构盘点 + 2×researcher 网络权威实践：认知漏斗骨架/Quick Start 最小可用/注释式完整配置示例/动机 ≤1/3 首屏/Diátaxis 分类/GitHub 官方规范）；question 4 拍板（命令表合并权威一张/配置节补全全部键/AGENTS 一并修正）
- 修改的功能：README.md 全量重构（212→211 行，净 +110/-111）：结构重排为认知漏斗（定位→30 秒了解→快速开始（前置条件+3 步含输出）→核心功能→配置（注释式全键示例：wiki.language/guide.pages/priority/notes、llm.provider/model/base_url/api_key/api_key_env、embed 同构）→命令参考（原 3 表合并为一张 17 行权威表，含 install [--claude/--codex/--also-claude]/uninstall --force/bench --repodoc 等）→FAQ（#限制项 锚点）→架构→限制项→进阶运维（watch 三平台托管与清理脚本下移）→lint 检查项→维护者；修复「7 种语言」顶部 vs 「11 种」限制项不一致；AGENTS.md 人工段 6 处旧路径修正（wiki/wiki/{lang}/→.repo-wiki/wiki/{lang}/，与生成块一致）
- 摸到的文件：README.md、AGENTS.md（人工段，生成块不动）
- 是否改变了接口/契约：否（纯文档）
- 验证：命令表 17 行 vs main.rs 18 枚举逐一核对（Bench/BenchManifest 合并）；配置示例键与 schema.rs 结构一致；示例引用 community.rs:54/:90 精确命中；默认值核对（zh/deepseek-v4-flash/openai-compatible/opencode.ai 网关/OPENCODEGO2_API_KEY/qwen3.7-text-embedding/百炼/BAILIAN_API_KEY）；#限制项 锚点与标题匹配；read 复核格式无截断
- 提交：dff8acd
- 遗留/风险点：README 数值（10 万/1 万行/16 并发/cal.com 实测）无第二真源（历史已逐项核证）；执行顺序建议「README 重构 → 运维/部署/多 Agent 文档」延续认知漏斗（未建文档页面留待后续）

## 六十七节：v36 D7 实机验证 + rerank 精排移除（2026-08-09）
- 背景：用户连续拍板——①opencode 网关不可用时保留默认并注明已知问题（question 拍板）；②「不使用 rerank 模型」——移除 v36 B 组全部 rerank 实现（YAGNI，不留死代码）
- 修改的功能：①D7 实机验证（真实 LLM 全量 generate）：opencode.ai 网关 /chat/completions 400/500、/models 200（key 有效、模型在列）——TEMP-DIAG eprintln 实证 repo-wiki 发送 model 正确无空格，网关报错为上游消息模板伪影——**网关不可用非代码 bug**；README 已知问题块+百炼替代示例已提交（a0604ea）；百炼（BAILIAN_API_KEY）generate 实测成功：18 页产物全、architecture.md/overview.md 回归、llms.txt 11 模块完整（此前缺失=LLM 失败连锁，非 bug）447s/107 文件/2018 实体；②rerank 移除：删 src/search/rerank.rs（-315 行）、schema RerankSection+默认函数+Default、lib.rs rerank_hits+hybrid 接线、search/mod.rs pub mod、README [rerank] 配置段；hybrid 恢复「双引擎召回+RRF 融合+调用链补全」；顺带修复 config_dir 测试 env 竞态（纯函数化 config_dir_from，同 global_config_dir_from 先例）+ clippy collapsible_if（Rust 2024 let chain）+ test_hook_install parse 适配 v36 D2 hook 模板（2>> 日志重定向）
- 摸到的文件：src/search/rerank.rs（删）、src/config/schema.rs、src/lib.rs、src/search/mod.rs、src/config/opencode.rs、tests/test_hook_install.rs、README.md
- 是否改变了接口/契约：否（rerank 属 v36 内部增强，移除无外部契约影响；config_dir() 签名不变）
- 验证：全量测试全绿（无 FAILED，含 config_dir 纯函数测试 3 断言+优先序断言）；clippy --all-targets 0 警告；cargo machete 仅剩 glob 冗余依赖警告（Cargo.toml 属 config zone 架构保护——architect 无权写，无计划任务可挂 coder——交付说明，用户可 `cargo remove glob` 或下轮计划处理）；rerank 实机验证（fn_entity 精排第 1）在移除前完成（证明功能本身正确，移除为产品决策非技术失败）
- 提交：c247232（+40/-315）
- 遗留/风险点：glob 依赖冗余（如上）；熔断记录：test_watch_e2e.rs:38 WikiConfig 构造缺 rerank 字段连续 3 次触发 NON-TRANSIENT CIRCUIT BREAKER（v36 B1 加字段漏更新构造点——移除 rerank 后该问题自然消失）

## 六十九节 v37：项目改名 Code Repo Wiki + CI 增强 + 文档重构

**改名**（提交 07d10bd）：crate/二进制/命令名 repo-wiki→code-repo-wiki 全链路（代码/测试/MCP 注册键/hook 字面量/AGENTS 注入块/插件 code-repo-wiki.ts）；产物目录 .repo-wiki→.code-repo-wiki；用户级配置目录 %APPDATA%/repo-wiki→code-repo-wiki（删除重装不迁移）；GitHub 仓库改名 mook-wenyu/code-repo-wiki（gh repo rename+remote set-url）

**CI 增强**：三 job（check：clippy -D warnings + cargo doc 门禁；test：ubuntu+windows 矩阵 fail-fast:false；lint-workflow：actionlint）；rust-toolchain.toml（stable+clippy）；concurrency cancel-in-progress

**跨平台真实修复**（提交 458cf24 + 本轮）：ubuntu manifest 本地路径 name 提取双分隔符 + Windows 盘符前缀平台无关判定（is_absolute 误判）；key 测试全局目录注入临时路径 + config_dir 测试纯函数化（env 竞态，ubuntu 无 APPDATA 兜底必现）；windows checkout 钉死测试固定 core.autocrlf=false（GitHub runner 系统级 autocrlf=true 转 CRLF）；doc 门禁 7 处修复（citation fence 字样/mcp 链接/HTML 转义——cargo doc -D warnings 零警告）

**文档重构**：docs/ Diátaxis 11 页（tutorial/cli/config/faq/limitations/lint/architecture/watch/maintenance/glossary/index）；README 223 行→着陆页；CHANGELOG 补记 v37/v36/v35；AGENTS.md/.gitignore/scripts 改名核对；commands.rs 陈旧注释清理

**验证**：全量测试绿（471+）+ clippy 0 + cargo doc 0 警告；CI run 31276550051/31276799380 已暴露并修复全部平台问题，push 待网络恢复后重试

## v38 真实环境验证 install/uninstall（2026-08-10）

- 真实环境 install/uninstall 全链路验证（本仓库：全局 opencode.json 8 个用户 MCP+插件、codex config、用户 memorix post-commit hook 共存场景）
- 发现并修复 5 个集成缺陷：插件模板自举解耦（uninstall 后仓库可编译）、AGENTS.md 块双标记迁移、旧名 hook 识别、空壳清理、hook 占用提示
- hook 端到端触发验证：Git sh 无 PATH 静默跳过（设计正确）、临时 PATH 真实 update 成功（产物生成）
- 提交 44dbccb（7 文件 +203/-75），全量 473 测试绿 + clippy 0

## v39 用户级集成落点对称化（2026-08-10）

- 用户指出：Claude Code/Codex 等 Agent 的「用户级内容」也应装各自的配置根目录——4 lane 检索核证官方语义（opencode 全局插件目录自动加载、Claude MCP 三 scope、Codex 用户级 config.toml）
- OpenCode 插件改用户级 `~/.config/opencode/plugins/`（官方自动加载目录，一次 install 全仓库可用）+ 旧版项目级产物自动迁移清理（含 plugin/ 单数目录不对称清理）
- Claude MCP 改用户级 `~/.claude.json` 顶层 mcpServers（User scope——command 绑定本机 exe 路径=用户级内容；不再写项目根 .mcp.json）；空 mcpServers 保留文件（OAuth 会话绝不动）
- Codex MCP 已是用户级（~/.codex/config.toml）无需改；CLAUDE.md/AGENTS.md 保持项目级（官方「团队共享入 git」语义）
- 提交 6dc47ed（插件 2 文件 +186/-59）+ 0a23fde（Claude MCP 6 文件 +106/-84）；全量 476 lib + 全部套件绿 + clippy 0

## v40 README 结构优化（2026-08-10）

- README 重写：新增「面向 AI 助手」节、已知问题压缩进 FAQ、贡献节重写（构建/测试/CI/发布）、Windows key 配置提示、可选配置说明
- reviewer 门发现 3 项事实缺陷并全部修正：key 读取来源表述（项目级 config.toml 亦生效——llm.rs:350 核对）、产物示例改用当前 api.md 真实片段、config.md 锚点修正
- 提交 c63a79f（23+/14-）；cargo check 干净

## v41 用户级配置迁移 home 点目录 + git hooks 共存追加（2026-08-10）

- 用户反馈：hook 遇既有 hook（LFS/memorix）「保留未覆盖」=未安装；配置根在 %APPDATA% 应参照 ~/.codegraph、~/.codex 放 home 点目录
- 3 lane 检索核证：Codex/Claude Code/Azure CLI 官方均用 home 点目录（%USERPROFILE%\.codex 等）；hook 业界惯例=标记判断所有权+幂等+可还原（husky 同款；memorix 章节式=本地先例）；迁移推荐=一次性迁移+旧目录保留+环境变量逃生舱
- 配置根改 %USERPROFILE%\.code-repo-wiki（Unix ~/.code-repo-wiki）+ CODE_REPO_WIKI_HOME 显式重定位（对齐 CODEX_HOME）+ 首次运行一次性迁移（复制旧 %APPDATA% 内容、旧目录保留、显式设 env 时不迁移）；测试 +4（迁移三态+home 路径）
- git hooks 改尾部追加标记块（# code-repo-wiki: append-begin/append-end）：与 LFS 包装/memorix 区块共存；再次 install 幂等只更新块；uninstall 剥离块还原用户内容；旧标记 hook 整文件升级；core.hooksPath 检查（指向其他目录提示不生效）
- 真实环境验证：本机 doctor 触发迁移（新路径 config.toml + 旧路径保留 + MD5 一致）；Unity 项目 install 追加块成功 + 二次 install 幂等
- 提交 16f0ca2（13 文件 +511/-88）；hook 8/8、smoke 20/20、config 50/50、clippy 0

## v42 install 注入块渲染接入完整配置链（2026-08-10）

- 用户反馈：Unity 项目 install 仍提示「未找到有效配置（配置文件不存在: {项目}\config.toml）」——配置链明明就绪为何还提示、为何不创建配置
- 根因：install_wiki 渲染注入块只读项目级单文件 load_config(&root/config.toml)——用户级配置不参与渲染（v25 U02 设计局限，v30 用户级合并语义引入后未同步）
- 修复：改用完整配置链 load_default_config(root)（项目级字段级合并覆盖用户级；两者皆无时自动创建用户级默认模板）；畸形配置降级「配置解析失败」提示并继续注入；测试 9/9（无配置自动创建模板+无提示断言、用户级 language=en 渲染 en 路径）
- 实机验证（release 重装 .cargo/bin 后）：提示消失、渲染 zh（用户级值）、hook 幂等「已是最新」
- 生产就绪盘点（3 lanes）：发布阻塞=缺 license/license-file/repository/keywords/categories + 无 LICENSE 文件（crates.io 400）；发布自动化缺=无 tag 触发/publish/Releases 二进制（cargo-dist 或 taiki-e）；版本漂移=0.3.0 未打 tag；LLM 真实验证缺口 pending（DeepSeek 402 后未复验）