Repository navigation
Conversation
reference 共 2196 行,其中 1021 行是中英对等镜像 —— 改一边忘一边,没有任何检查会发现漂移,这是
「容易过时」最大的结构性原因。英文 README 仍然双语,只是把详细参考指向中文版并标注语言。
- 删除 `docs/reference/{memory-core,pi-memory,dsh-memory}.md`
- 根 README 与三个包的英文 README:链接改到 `.zh.md`,锚点换成中文(`#跨设备同步` / `#工具参考` /
`#为什么索引要冻结`),Docs 小节标注 reference 用中文书写
- `docs/guides/testing.md` 与 `sync-e2e.md` 里指向英文 reference 的两处同步改掉
- 中文 reference 之间的互链不变
上一版(同一分支的前一个 commit)只是把示例里的 2.2.0 逐个换成 2.3.0 —— 治标:每发一个 core 版本就得改一次文档,忘了改就把人指向一个过时版本。 - 版本与范围统一用 `<新版本号>` / `<范围>` 占位,并写明 `memory-core/package.json` 的 `version` 是唯一真相源,**本文件不复制这个数字**。 - 去掉「哪些 API 从哪版起」的版本清单,换成稳定规则:适配层 import 的每个 core 导出都必须存在于 它声明的范围里;core 新增导出时先发 core、再抬范围。 - `registry-smoke` 的硬失败例子保留真实报错的**形态**,但不再绑定版本叙事: 范围不存在 → `No matching version found`;导出了新东西而 core 没发 → `does not provide an export named '<导出名>'`。 - 验收 curl 同样用占位符。 全文已无 2.2.0 / 2.3.0 / 4.3.1 这类易变数字。
判断标准:文档只回答「现在是什么、怎么用、什么不能改」,不回答「当初怎么改的」。 - architecture:端口契约与布局合并去重,`budgeted()` 这类内部函数名改成行为描述,精确到个位的 ms 改成量级(机器一换那些数字就假);发布形态三行表格化。 - dependencies:删掉 0.80.2 → 1.5.0 的宿主 API 演变(那是 spec 的内容),只留「peer 写下限、dev 钉精确、 升级必带代码改动」三条规则;版本号以 `package.json` 为准,不再复制。 - testing:删掉「挪了 harness 之后 89 个用例红了 73 个」这类一次性数字,保留失败模式与护栏。
原来那节是验收日志:日期、`321 passed`、逐条调用序列、子会话 `request/header` 内容。这些属于 PR 与 spec,不属于文档。 - dsh:46 行验收记录 → 一段现状(真机确认了什么、同步仍未对真实远端验证);随之把「常驻 worker」 与「一次性宿主的限制」提升为独立小节,不再挂在验证状态下面。 - pi:去掉日期与逐条过程,只保留「哪些路径真的跑通过」。 - sync-e2e:§4 从「回写 Verification status」改成「更新验证状态」,明确不写日期、测试数量与逐条过程。
防复发:文档不是 changelog。新增一节写明不写日期/PR/CI 编号/测试数量/过程叙事/版本演进,易变数字指向 `package.json` 与 CI,历史留在 git log、PR 与(作为唯一例外的)specs。
- 「容量」原来四个长段落讲两套口径(写入口径 200 行 / 注入窗口 50 行),改成一张表 + 5 条 bullet: 超限不失败、窗口取最新、被挤出不等于丢失、48/199 两条线、`Index:` 与 `Inject:` 的区别。 - 「本包刻意不管的事」六行表格压成一段:仍是同一份边界(何时注入、cache 重放、schema/UI、模型解析、 配置位置、consolidate 提醒),只是不再按行摊开。
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
把文档从「变更日志」改回「现状快照」。触发点是两个批评,都成立:
release.md把当前版本号写进示例 → 每发一版都得改文档(上一版 PR 只是把 2.2.0 换成 2.3.0,治标);321 passed、逐条验收过程、宿主 API 演进、PR/commit 叙事)—— 文档被当成了 log。定下的四条原则
package.json、CI、git log),文档里用占位符或只写规则。本 PR 的改动(按 commit)
docs(release):版本号全部抽成<新版本号>/<范围>,memory-core/package.json是唯一真相源;registry-smoke 的硬失败只保留两种报错形态,不绑定版本叙事。docs(reference):删掉三份英文镜像(1175 行)。双语对等维护是「容易过时」最大的结构性原因 —— 改一边忘一边,没有任何检查会发现漂移。英文 README 仍双语,只把详细参考指向中文并标注语言。docs(guides):architecture / dependencies / testing 三篇瘦身。删掉 0.80.2 → 1.5.0 的宿主 API 演变(那是 spec 的内容)、精确到个位的 ms、内部函数名(budgeted())、一次性统计数字。docs(reference):验证状态从「验收日志」改成现状一句话(dsh 46 行 → 6 行),随之把两个###提升为独立小节;pi 去掉日期与逐条过程;sync-e2e 的「回写」一节改成「更新现状」。docs(agents):把「文档只写现状」写成硬规则,防复发。行数:guides 407 → 453(release 因补了两种失败形态反而变长)、reference 2196 → 995(含删除英文 1175)。
不包含
docs/superpowers/specs/(3701 行)—— 它是历史决策记录,本来就该是 log,不动。还没做
三份中文 reference 的内容级压缩(
pi-memory.zh.md437 行、dsh-memory.zh.md330 行、memory-core.zh.md228 行)会继续追加到本 PR。