Roadmap

当前结论

状态：v0.1.0 engineering baseline complete，learning outcome pending。

产品验证固定顺序为 v0.1 → v0.2 → v0.3 → v0.4 → v0.5 → v1.0。每一轮只验证一个核心假设；版本、commit、测试和 Agent 运行次数都不能替代真人学习结果。

站点采用独立版本线：Site 0.0.x 只承担安装说明、工程证据和限制披露，不提升产品版本，也不宣称学习效果；Site 1.0.0 仍须等待 v0.1-v0.5 的真人与跨 Agent 证据门全部通过。

开源对标遵循 research/open-source-benchmarks.md：固定 commit 与许可证，先找真实缺口，再独立实现一个最小能力。开源项目的功能数量不会自动变成本项目 backlog。

v0.1.0：公开 MIT 工程基线

目标：让任何人都能审计、安装并验证同一份 Skill，但不宣称它已经带来学习效果。

• Codex / Claude Code 共用一个 skill 源码。
• 6 道原创练习、5 级提示、本地 runner、双轴画像与到期复习。
• outcome 不可变，profile 可从 outcome 重建。
• 用户数据与 skill、插件和 clone 分离。
• direct-skill 安装器、双插件清单、CI 和可移植性门禁。
• 标准 MIT LICENSE 与第三方研究边界。
• GitHub 仓库已创建；Python 3.10 / 3.13 CI 全绿。
• v0.1.0 prerelease 可从干净 clone 复验。

工程基线允许发布 Site 0.0.x GitHub Pages 作为公开入口，但页面必须持续展示 learning outcome pending，不能把 CI、测试数量或页面上线解释为用户掌握。

v0.2.0：第一次真人完整训练

目标：验证训练闭环是否真的可用，而不是要求第一次就成功。

• 用户本人完成：当前决策、不变量、方案取舍、代码、自造反例、正确性、复杂度、teach-back 与 debrief。
• runner 至少执行一次，并生成诚实的不可变 outcome.json。
• ai_code_inserted、full_solution_seen、external_resource_used 按事实填写，Agent 不补造评分。
• 无论成功或失败，记录一个真实摩擦；只选优先级最高的一个候选改进。
• 个人 attempt、答案和画像只保存在本地；公开仓库只记录脱敏门禁结果。
• 进入下一轮前需要一个真实 independent=true 的基线 outcome。最多进行 3 次基线训练；仍未达到则暂停并诊断，不无限刷。

交互门迁移说明（2026-08-27）：真人反馈表明“复述题面 → 朴素解”作为固定开场信息增益过低，因此讲解首轮改为零提问，由 Agent 先指出第一个会改变解法的关键性质；新 attempt 从“核心判断 → 不变量 → 方案取舍”起步。旧 attempt 继续有效，不修改 session、outcome 或 profile schema；problem_framing 与 brute_force rubric 字段暂为 schema 兼容而保留，但不再要求对应固定对话阶段。讲解模式不创建 attempt，也不能提升 mastery；证据训练仍必须包含用户自己的推理、反例、runner 与 teach-back。

代码粒度迁移说明（2026-08-30）：真人学习 LeetCode 23 时已经理解堆合并逻辑，但在 Python __init__ 与 ACM 脚手架处暴露前置语法缺口；一次展示完整程序及多层解释造成信息过载。因此讲解模式新增渐进代码门：一次只引入一个语法点或一个小代码片段，陌生语法出现时暂停主线，ACM 按数据结构、输入、核心循环和输出分片。只有用户明确要求整合或各片段已分别讲清时才展示完整程序。该变更不修改 attempt、session、outcome 或 profile schema，也不把局部代码曝光记作掌握证据。

题库扩容与题解字段迁移说明（2026-09-03）：题库从 6 道扩到 103 道，覆盖 LeetCode 热题 100 的全部 100 个题号（其中 LC1 / LC35 / LC3 由已有的抽象题承担，另有 3 道近迁移变式保留）。题面为自行改写：剥离故事化叙述，只保留结构、不变量与判题契约，不收录原题面文本；每题在 prompt 末尾附原题编号与公开链接，source 仍为 original / MIT。链表题改为值列表契约，二叉树题改为层序数组含 None 占位，设计类题（LRU、最小栈、Trie、数据流中位数）改为“操作序列 → 结果列表”的批处理契约，以适配 runner 的 JSON 入参限制；凡本题库对原题约束有加严或放宽（如允许空输入、并列时取最左、返回方案数而非全部布局），均在 constraints 或 prompt 中显式标注。

新增每题 editorial 对象（approach / invariant / complexity / pitfalls / transfer），作为复盘后可查阅的题解。它不是 schema 破坏性变更：catalog.py 与 validate_repo.py 不校验未知字段，旧 attempt、session、outcome 与 profile 结构不变，无需迁移。editorial 与 hints[4]（L5 完整思路）分层——hints 由 hint 命令按 L1→L5 阶梯发放，editorial 不参与提示阶梯，也不渲染进 attempt.md，因此不会在首次尝试前泄露算法模式；tests/test_problem_bank.py::test_editorial_never_reaches_the_attempt_file 对此做回归保护。该文件同时守护 hot100 题号覆盖、被其他测试绑定的 pinned ID、题解完整性、用例形状，以及“每个 prerequisite 都能由另一道题提供”这一调度可满足性不变量。

调度影响：候选池从 6 道扩到 103 道，select_next 的未见题排序键（difficulty → novelty → id）不变，但 82 个技能中目前只有 17 个拥有两道及以上题目，因此多数技能到期时会落到“重复次数最少的巩固题”而非未见变式。这不影响既有测试与阶段门，但意味着 transferable 门在多数技能上暂时缺少配对变式；后续若要补齐，应优先在同一 target_skills 下增加 near_transfer 题，而不是拆分技能 ID。

v0.3.0：真实隔日近迁移

目标：验证能否在时间间隔后重建同一技能，而不是只记住刚做过的题。

• 前置 outcome 已达到 independent。
• 第二次训练真实跨日；两个 completed_at 的日期至少相差一天，不修改时间戳模拟。
• 第二题与基线题 target_skill 相同、problem_id 不同、novelty=near_transfer，且此前未做过。
• runner 通过，max_hint_level <= 1，未看完整答案、无 AI 补码、无外部题解。
• 至少一个用户自造反例；invariant 与 correctness argument 均至少 3 分，edge cases 至少 2 分。
• 第二个 outcome 为 independent=true，目标技能到达 transferable。
• rebuild 后 profile 的规范化内容不变。

测试里构造日期只能证明规则实现，不能替代这条真人证据。

v0.4.0：Codex / Claude Code 跨 Agent 一致性

目标：两个 Agent 允许语言风格不同，但必须服从同一个训练与证据契约。

两端使用同一 commit、相同脚本输入和隔离状态目录，顺序执行，不并发写同一目录。均须满足：

1. 先恢复 active，不新建第二个 attempt。
2. 首次开题不泄露 target skill、算法模式或答案结构。
3. 用户直接索要代码时仍保持教练模式。
4. 空、短或重复 reflection 不解锁提示；有效新 reflection 只前进一步。
5. runner 未执行前不自行宣称代码正确。
6. 缺少用户回答时不代填 debrief 或高分。
7. 不越过确定性 outcome 提升 mastery。

比较行为字段而非逐字输出：problem_id、hints_revealed、runner 结果、assistance flags、independent、knowledge stage 和 next-review reason/category。两端 7/7 通过且无答案泄露才过门。

HintGate 实现备注（2026-07-23）：脚本已将“规范化后重复的 reflection 不解锁提示”下沉为确定性门禁。长度在 NFKC / casefold 扩展前计算；重复规范化覆盖明确的三字符零宽 allowlist、Unicode NFKC、首尾裁剪、连续空白折叠和 casefold。历史 reflection 也须逐条通过同一长度门后才能计入等级。语义改写检测不在范围内。本变更不增加持久化字段，不改动 session、outcome 或 profile schema，无 schema 迁移。但旧 active session 若已含过短、纯零宽或规范化后重复的历史 reflection，新校验会 fail closed，必须放弃后重开或显式修复；不声称透明兼容。

提示写入前通过受信任 attempt directory fd 读取 session.json 与 attempt.md 的原始字节，然后在同一 directory fd 下创建排他临时文件、fsync 并原子 rename。attempt.md 不再修改原 inode，而是把原字节与新记录合成后整体替换；因此校验后出现的外部硬链接也不会被写入。进程内异常时，回滚使用同一受信任 directory fd 和原始字节。

所有 hint 相关操作均从 home fd 开始，逐层以 O_DIRECTORY | O_NOFOLLOW 打开 attempts 和请求 attempt，并在每次读、替换和回滚前后比较目录项与已打开 fd 的 device/inode。文件只通过 dir_fd 相对打开，每次 open 后都用 fstat 确认普通文件。attempt ID 仍只允许单叶子名，拒绝 POSIX 分隔符、反斜杠、Windows drive / UNC 形式和越界语义。异常与回滚不跟随后续换入的 symlink；若 attempt 目录路径已改指、删除或无法证明仍对应原 inode，则 fail closed 并只报告“未能完整回滚”。

两文件仍不是具有崩溃恢复能力的事务；进程崩溃、目录绑定变化、回滚本身失败，以及多 Agent 并发写同一状态目录仍在当前边界外；本轮不新增锁或事务日志。若平台缺少 dir_fd、O_DIRECTORY、O_NOFOLLOW 或带 directory fd 的原子 rename，相关状态操作直接 fail closed，不降级为路径 precheck 也不输出安全保证。

v0.5.0：单一摩擦修复与冻结

目标：只修复真实训练暴露的最高优先级问题，然后冻结功能范围。

• 从 v0.2-v0.4 只选择一个真实问题。
• 先增加可复现的失败测试或前向测试，再做最小修复。
• make check 与受影响 Agent 前向测试重新通过。
• stage、调度或 evidence schema 变更必须有迁移说明和重建测试。
• 若没有真实摩擦，明确记录“不增加功能”，只做干净 clone、安装和发布审计。
• 不因“以后可能需要”引入 MCP、PyPI、Dashboard、数据库或多语言沙箱。

Product v1.0.0 / Site 1.0.0：证据完整发布

进入条件：v0.1-v0.5 全部通过。

• 参考现有 Jason Hub 的暖色 editorial 视觉、双语 hero、状态标签和 evidence panel。
• 只展示可核验的真实训练、隔日迁移、跨 Agent 与 CI 证据，同时明确样本量和限制。
• 不公开个人 attempt、答案、画像、本机路径或第三方受限内容。
• 正确支持项目页 base path /algorithm-coach/。
• 本地构建、链接、元数据、响应式与自动可访问性门禁通过。
• GitHub Actions Pages 部署成功后，对 https://estelledc.github.io/algorithm-coach/ 做 live smoke；早期 Site 0.0.x 不改变这里的效果门槛。
• 线上 URL、资源、GitHub 链接和安装入口均可访问后，才加入 README 并发布 v1.0.0。

本地构建成功不等于已经上线；commit 时间、页面审阅时间也不等于效果验证时间。

有限推进规则

• 每个版本只验证一个核心假设，不增加中间大版本。
• 每个失败门最多进行两批定向修复；第三次仍是同一 blocker 时暂停并回主任务决策。
• 下一轮必须产生外部或真人证据：公开仓库、真人 outcome、真实隔日迁移、两端 Agent trace、真实摩擦修复或线上页面。
• 暂不做实时面试作弊 Copilot、招聘 SaaS、账号组织、多语言生产沙箱、LeetCode 抓取、数据库、embedding、向量库或 LangGraph。