Skip to content

📝 docs: 状态回归事实 —— M4/M5 早已落地,README 却还停在 M3 - #37

Merged
MrXnneHang merged 1 commit into
mainfrom
docs/status-sync-post-m5
Aug 1, 2026
Merged

📝 docs: 状态回归事实 —— M4/M5 早已落地,README 却还停在 M3#37
MrXnneHang merged 1 commit into
mainfrom
docs/status-sync-post-m5

Conversation

@xnne-bot

Copy link
Copy Markdown
Collaborator

动机

#36 合并后,我按惯例核对了一遍项目自己对自己的状态声明,结果它落后现实两个里程碑

文件 声称 实际
README.md M3(当前),M4 CLI 写成将来时 CLI 在 #12 就落地了
README.zh-CN.md 同上 同上
docs/guide/what-is-wikimem.md M4 CLI「(next)」 同上
docs/zh/guide/what-is-wikimem.md M4「(下一步)」 同上

还有两处更难看的:

  1. README 与 guide 互相矛盾 —— 一个说 M3 是「当前」,另一个说 M3 已 ✅。同一个事实,两个页面两种说法。
  2. M5(日记 + 时间门控)在四份状态清单里一次都没出现过。 那是本仓库迄今最大的一块工作(♻️ refactor: 抽取共享序列化到 _serialize.py(#15 Phase 1) #16 ✨ feat: diary 事件流原语 —— 追加 + 按日读取(#15 Phase 2) #17 ✨ feat: diary 时间窗口 window() —— 跨日范围读取(#15 Phase 3) #19 + ✨ feat: 时间正则快通道 parse_time_range()(#25 Phase 1) #26 ✨ feat: 时间门控接入检索 —— 日记可召回了(#25 Phase 2) #27 ✨ feat: 时间门控的 explain 与文档(#25 Phase 3) #31,两个跟踪 issue),而项目首页对它只字未提。

换句话说:首页把这个项目说小了两个里程碑。

解决方案

① 里程碑清单回归事实:M3 / M4 标 ✅,补 M5,补 M6(serve,暂缓)。

编号不是我编的 —— M5 / M6 都是 ADR 自己划的,我只是把它们抄进状态清单:

  • docs/adr/0001-diary-store.md:「建议作为下一个里程碑(M5)拆 issue:Diary 存储 API → ADR-0002 的窗口检索」
  • docs/adr/0002-time-range-retrieval.md:「建议同一里程碑(M5)内实现」
  • docs/adr/0004-api-contract-thin-shells.md:「serve 作为独立里程碑(建议 M6)」

② 加一句防复发的话,四份清单末尾统一:

Past M5 the work is tracked per decision, not per milestone — see the ADR index, where every decision carries its own implementation status.

这条是这个 PR 里唯一带判断的改动,理由:里程碑清单已经不是这个项目的状态载体了。 M5 之后的工作(ADR-0003 #33、ADR-0005 #24 #36、ADR-0006 #29 #30 #32 #34)没有一件能塞进 M 编号里,它们是按 ADR 组织的。让四份清单继续假装自己是状态权威,只会保证下一条 ADR 落地时它们再次过期 —— 而这正是本 PR 在修的东西。#35 建的那张带「实施」列的 ADR 索引才是真正的状态面,这句话把读者送过去。

③ 兑现 #35 里的承诺:ADR-0005 的实施行与索引行从「⚠️ 模式 A 已落地 #24;模式 B 未做」改为「✅ 模式 A #24、模式 B #36」。当时两个 PR 都要改 docs/adr/README.md 同一行,所以刻意留到 #36 合并之后再动。

验证

CLI 是实测存在的,不是从 PR 记录推断的

$ uv run wikimem --help
usage: wikimem [-h] [-s STORE] {ls,show,grep,explain,graph} ...

五个子命令全在 —— 也就是 README 写成「将来时」的那五个。

文档站本地构建通过pnpm i --frozen-lockfile && pnpm buildbuild complete in 5.16s。VitePress 默认对死链直接报错,所以新增的 /adr/README 链接是通的。顺带一个发现:ADR 索引在站上的路径是 /adr/README(200)/adr/(目录形式)反而是 404 —— 已按能通的那个写。

四道闸门(与 CI 同命令):

uv run pytest -q                   → 216 passed, 1 skipped   (与 main 基线一致,纯文档改动)
uvx ruff format --check .          → 27 files already formatted
uvx ruff check .                   → All checks passed!
uv run ty check --error-on-warning → All checks passed!

零代码变更,6 个文档文件。

类型

  • 📝 docs: 对文档进行修改

#36 合并后顺手核对了一遍项目自己的状态声明,发现落后现实**两个里程碑**:

| 文件 | 声称 | 实际 |
|---|---|---|
| README.md | **M3(当前)**,M4 CLI 是将来时 | CLI 在 #12 就落地了 |
| README.zh-CN.md | 同上 | 同上 |
| docs/guide/what-is-wikimem.md | M4 CLI「(next)」 | 同上 |
| docs/zh/guide/what-is-wikimem.md | M4「(下一步)」 | 同上 |

另外两处:README 与 guide 之间**互相矛盾**(一个说 M3 是当前、一个说 M3 已完成);
而 **M5(日记 + 时间门控)—— 本仓库迄今最大的一块工作 —— 四份状态清单里一次
都没出现过**。

改动:

- M3/M4 标 ✅,补上 M5(#16 #17 #19 + #26 #27 #31),补上 M6 = serve(暂缓)。
  M5 / M6 这两个编号不是我编的:ADR-0001、ADR-0002 的「实施」段就把日记与时间
  门控划为 M5,ADR-0004 把 serve 划为 M6。
- 四份清单末尾统一加一句:**M5 之后按决策跟踪、不按里程碑**,指向 ADR 索引。
  这条是防复发的 —— 里程碑清单本来就不再是这个项目的状态载体了,让它继续假装
  是,下一条 ADR 落地时它就会再次过期。
- 同步 ADR-0005:模式 B 已由 #36 落地,实施行与索引行从「⚠️ 模式 B 未做」
  改为「✅ 模式 A #24、模式 B #36」。这是我在 #35 里承诺合并后补的那一处。

CLI 确实存在,不是照 PR 记录推断的 —— `uv run wikimem --help` 五个子命令
(ls/show/grep/explain/graph)都在。文档站本地 `pnpm build` 通过(VitePress
默认对死链报错,因此新加的 `/adr/README` 链接是通的;该路径线上实测 200,
`/adr/` 反而是 404)。

Co-Authored-By: Claude <noreply@anthropic.com>
@MrXnneHang
MrXnneHang merged commit 82ef9a6 into main Aug 1, 2026
6 checks passed
@MrXnneHang
MrXnneHang deleted the docs/status-sync-post-m5 branch August 1, 2026 11:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants