Repository navigation
docs(readme): lead with what PowerContext is and prove it with text - #2003
AlexStocks wants to merge 12 commits into
Conversation
The README explained what PowerContext does but never said what it is: it
opened with a slogan, had no "what is" or "why" section, and kept its
strongest evidence inside two SVGs whose numbers no crawler can read.
Installation guidance took about 45% of the page, pushing value below it.
Restructure all three localized READMEs to a What is -> Why -> Proof it
works -> Quick start spine:
- State the category ("an open-source context service for AI agents") in
the first sentence, then expand Memory, Handoff, Experience, and Skill
under their own headings.
- Add a Why section with six extractable claims plus a four-column
comparison against re-reading transcripts, RAG, and host-local memory
files.
- Write the benchmark numbers as text. LoCoMo 90.78% vs 87.79% PowerMem vs
52.9% full context (+37.88 points) and SWE-bench Pro 86.73% vs 82.35%
(+4.38 points, 32 more tasks in a 731-task paired run) were previously
only readable inside readme-benchmark-summary.svg.
- Fold installation caveats into collapsed <details> blocks so the shortest
path stays visible.
All existing prose claims, both SVGs, the integration table, the honest
caveats about owner-supplied scores and experimental Windows support, the
contributor wall, and the license section are preserved.
No product screenshot or demo video is added; that remains a follow-up.
| connections. Choose **Full memory capabilities** to test automatic Memory and Topic Memory; this requires separate | ||
| Generation and Embedding API credentials. An Agent subscription does not provide those Server credentials. | ||
| Choose **Basic memory** to save and retrieve memories explicitly without additional model APIs. | ||
| PowerContext 1.3.0 includes an interactive setup wizard. You need Git, |
There was a problem hiding this comment.
[P2] Update release references alongside the rewritten READMEs
The installation rewrite removes prefixes still required by scripts/release_version.py. Running python scripts/release_version.py --check now exits with code 2: README.md: no release reference matching '^Install '. Version updates with --write --version 1.3.0 fail for the same reason, blocking both validation and version bumps. The Chinese ^安装 prefix and the Japanese installation prefix are also missing. Please update REFERENCE_PREFIXES for all three READMEs to match the new wording, or retain the expected version references.
There was a problem hiding this comment.
Fixed in 70e10b4.
REFERENCE_PREFIXES now follows the current PowerContext <version> wording in all three rewritten READMEs, so the release updater no longer depends on the removed installation headings. I also normalize the emitted relative path with .as_posix() so the release-script diagnostics remain stable on Windows.
Verified with:
uv run --no-sync python scripts/release_version.py --checkuv run --no-sync pytest tests/test_release_version.py -q(12 passed)
There was a problem hiding this comment.
已独立核对，这个修复正确且必要，可以放心保留：
planned_updates()对REFERENCE_PREFIXES里每一个前缀都要求count > 0，命中为 0 会直接raise ValueError。旧 README 的^Install/^安装/Git、uv、Agent CLI を用意して、三个锚点在重写后已不存在，若不删除，make version-check必然失败。所以这不是放宽约束，而是跟随结构变化。- 版本覆盖率没有损失。以
planned_updates(ROOT, "1.4.0")做非破坏性预演：三份 README 各含 4 处1.3.0（PowerContext 1.3.0 …、powercontext[cli,server]==1.3.0、--ref powercontext-v1.3.0、pip install "powercontext[cli]==1.3.0"），替换后残留均为 0 —— 全部仍被现有前缀覆盖。 - 本地实测：
scripts/release_version.py --check退出码 0；pytest tests/test_release_version.py -q→ 12 passed。
as_posix() 这处也确认是真实的 Windows 修复，不是顺手改动：tests/test_release_version.py:186 断言 "integrations/dsh/plugins/powercontext/README.md" in result.stderr（POSIX 分隔符），而 str(Path) 在 Windows 上产出反斜杠，改前该断言在 Windows 必红。CI 的 tests job 只在 ubuntu 上跑，所以一直没被发现。
两点小建议：
- PR 正文的「改动不含代码，无测试需要增删」与「仅限文档」现在与 diff 不符（
scripts/release_version.py已改动），建议更新，否则 reviewer 会按纯文档 PR 的预期来读。 as_posix()属于跨平台的测试修复，与 README 重写无因果关系。若维护者偏好单一职责，可拆成独立提交/PR；保留在本 PR 也可接受，但建议在正文里点出来。
|
CI failed |
Add three task-continuity scenarios and two Dashboard screenshots captured from a local Server with synthetic records. This makes the README demonstrate PowerContext boundaries rather than repeating a generic product feature list. Fix the release reference inventory after the README heading rewrite and normalize its diagnostic paths across platforms. Constraint: screenshots use only synthetic records; no demo video or new product behavior is claimed. Scope-risk: documentation assets and release-version validation only; no runtime or API behavior changed. Tested: uv run --no-sync pytest tests/test_release_version.py -q; uv run --no-sync python scripts/release_version.py --check; uv run --no-sync ruff check scripts/release_version.py; uv run --no-sync ruff format --check scripts/release_version.py; uv run --no-sync ty check --python-version 3.11 scripts/release_version.py
There was a problem hiding this comment.
Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.
An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.
|
已定位并修复。原评论对应旧 Head 修复已在 |
Replace PR-specific Dashboard records with synthetic inventory migration records, and align the README's Review wording with the currently exposed candidate-decision surface. Clarify the Memory screenshot descriptions in all three README languages. Constraint: Preserve the existing review, revision, and explicit export boundaries without claiming unavailable authorization semantics. Scope-risk: Documentation and README assets only; no runtime or API change. Tested: uv run --no-sync pytest tests/test_release_version.py -q; uv run --no-sync python scripts/release_version.py --check; local Dashboard pages opened with Playwright at 1440x1080.
There was a problem hiding this comment.
Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.
An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.
|
|
||
| 当一个决定或约束需要跨越产生它的那一轮会话时，把它保存为 Memory。下一个会话可以检索活跃条目，或从中准备有边界的上下文；人也可以查看精确的 Artifact Revision 与 Source 引用。将条目退役只会让它退出主动召回，不会改写历史。 | ||
|
|
||
|  |
There was a problem hiding this comment.
本轮的图片资产已独立核对通过：新截图是中性场景（Scope Inventory schema migration），上一版的会话残留（Finish the README value story 等）已清除，无 token / 密钥 / 邮箱 / 内网地址，体积 58.7 KB / 57.2 KB；PR 正文「Playwright 在 1440x1080 视口」的断言也属实（实测两张 PNG 的 IHDR 均为 1440x1080）。alt 文案已改为 对应的 Artifact 与 Source 引用，与图中 atomic-memory/art_0f66… + content/src_cc82… 两条引用一致。
在这之上提一个同根、但本轮未处理的点：中文 README 嵌的是英文界面截图，而 Dashboard 的默认界面语言是中文。
src/powercontext/server/dashboard/preferences.py:26-29——CATALOGS只有zh/en，zh读labels.json- 同文件
:34——language = "zh"（默认值） - 同文件
:37-38—— 语言不合法时回退到zh - 同文件
:49——html_language在 zh 时输出zh-CN
也就是说，用户首次打开 Dashboard 看到的是中文界面，而 README_CN.md 第 89、95 行展示的是英文界面。中文读者对照截图时会以为默认语言是英文，这与实际默认行为不一致——对一份以中文读者为对象的 README，这个落差是可以避免的。
presentation() 支持从 query 取 lang（request.query_params.get("lang", …)），另有 remember_language() 可写入 cookie，因此重新截一份中文界面成本很低。
README_CN.md建议改用?lang=zh的截图（:89、:95两处引用同一批资产，替换 PNG 即可，无需改 Markdown）README_JP.md没有对应语言目录，继续共用英文截图是合理的；如果这是有意的取舍，可以忽略本条
不影响本 PR 的技术准确性，不构成阻塞。
There was a problem hiding this comment.
已按此实现，见 ca763bdf。
做法：用独立临时实例出图，没有触碰本机正在运行的 personal Server，也没有写进它的数据目录。
- 临时实例：独立数据目录 +
--port 8123+POWERCONTEXT_SERVER_DASHBOARD_ENABLED=true，独立 SQLite（POWERCONTEXT_SERVER_DATABASE_URL）。 - 合成数据经公开 API 写入：
/v1/scopes→/v1/sources/content（content/migration-plan）→/v1/memory/remember×3 →/v1/handoff/finalize+/v1/handoff/commit。 - 用
?lang=zh在 1440x1080 视口截图（Chrome headless；本机未装 Playwright）。 - 完成后临时实例与数据目录已删除，端口已释放。
结果：
README_CN.md现指向docs/assets/readme-dashboard-memories-zh.png与docs/assets/readme-dashboard-handoff-zh.png。README.md/README_JP.md继续共用英文界面资产（CATALOGS无ja目录）。- 中文截图与英文版逐项对齐：页面标题「记忆」/「交接」、Scope「库存 schema 迁移」、引用
atomic-memory/art_…+content/src_…、详情页同样是「记录的进展 / 下一步 / 未覆盖的内容 / 查看材料 1」。
顺带一个观察，可以佐证英文截图的真实性：这次的记录引用也渲染为 handoff/handoff@1，与英文截图完全一致——说明它确实是 Server 的默认 artifact_id，不是占位符。（/v1/handoff/commit 返回的 reference 就是 {"family":"handoff","artifact_id":"handoff","revision":1}。）
| | Bounded recall for one turn | no | partial | no | `PreparedContext` byte budget | | ||
| | Inspectable outside the Agent | no | no | yes | yes | | ||
|
|
||
| ## How a task keeps moving |
There was a problem hiding this comment.
[P3 · 可选] 本节与 What is PowerContext? 把同一组概念讲了两遍
What is PowerContext?（第 13 行）下已有四个 H3：### Memory（37）、### Handoff（46）、### Experience（60）、### Skill（67）。本节（106）又用三个编号小节把同样四个概念重讲一遍：§1 Memory（112）、§2 Handoff（120）、§3 Experience + Skill（128）。
而且第二遍不只是"再演示一次"，正文存在直接重复，例如：
What is PowerContext? |
本节 |
|---|---|
### Memory：retiring one drops it from active recall without deleting its history |
§1：Retiring an entry removes it from active recall without rewriting its history |
### Handoff：Committing it creates a durable Revision only when the user wants a milestone |
§2：committing it creates the durable Revision that the receiver can resolve, acknowledge, and check |
读者在约 40 行内会把每个概念读两遍。两种收敛方式供参考：
- 合并：删掉本节的叙述文字，只保留一段简短导入 + 两张截图，把截图就近插进
What is的对应小节（### Memory、### Handoff下各一张）。概念定义与实际界面同处一节；顺带解决一个不对称——目前 §1/§2 有截图，§3 没有。 - 改写：保留本节结构，但把三个小节从"复述概念"改成"演示一次交接的时间线"（同一 Scope：Memory 产生 → Handoff 提交 → 候选进入 Review Inbox），与上面形成分工而非重复。
另外，本节位于 Why PowerContext?（73）与 ## Proof it works（134）之间，会把证据部分继续下推。若采纳方案 1，Why 与 Proof it works 重新相邻，与最初的 What is → Why → Proof it works → Quick start 主干更贴合。
若这是有意设计的"概念 → 上手演示"两层结构，忽略本条即可——不影响事实准确性与可用性。
There was a problem hiding this comment.
已采纳方案 1（合并），见 ca763bdf。
- 删除
## How a task keeps moving整节。 - 两张截图分别移入
### Memory与### Handoff之下，紧邻它所说明的概念。 - §3 的内容与
### Experience/### Skill已覆盖，一并删除。 - 合成数据声明保留：上移为
## What is PowerContext?中 Scope 结构树之后的一行斜体（*The Dashboard screenshots below use synthetic demonstration records.*），三语同步，仍覆盖两张图。
效果：
- 三份 README 的 H2 / H3 /
<details>计数完全一致（9 / 5 / 3）。 ## Why PowerContext?与## Proof it works重新相邻，恢复What is → Why → Proof it works → Quick start主干。- 正文净减 50 行（+18 / −68，含两张新增 PNG）。
校验：scripts/release_version.py --check 退出 0；tests/test_release_version.py + tests/test_dashboard.py 共 33 passed；三语均无尾随空白、结尾换行正常；所有被引用的资产都存在。
The Dashboard defaults to `zh` (preferences.CATALOGS, language = "zh"), so a Chinese reader's first view is the Chinese UI while README_CN.md showed an English one. Capture the same two demonstration pages with ?lang=zh and point only the Chinese README at them; the English and Japanese READMEs keep the existing assets because no `ja` catalog exists. Also drop the "How a task keeps moving" section, which restated Memory, Handoff, Experience, and Skill a second time within forty lines of the definitions in "What is PowerContext?" (for example, "retiring one drops it from active recall without deleting its history" against "Retiring an entry removes it from active recall without rewriting its history"). Each screenshot now sits under the concept it illustrates, and the synthetic-data disclosure moves into the section intro so it still covers both images. Verified: scripts/release_version.py --check exits 0; tests/test_release_version.py and tests/test_dashboard.py pass (33); the three READMEs keep identical H2, H3, and <details> counts; no trailing whitespace and every referenced asset exists.
There was a problem hiding this comment.
Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.
An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.
| > 这么贵的上下文，不应该依赖有人每个会话都重讲一遍。 | ||
|
|
||
| ## 安装、配置并接入 Agent | ||
|  |
There was a problem hiding this comment.
[P3] 中文截图暴露了产品侧一处术语不一致：Dashboard 把 constraint 译成「约定」，中文文档用「约束」
刚为中文 README 重新截取的 Dashboard 图中，Memory 的内容类型显示的是「约定」（见截图顶部标签）；而本行上方第 36 行的正文写的是「决定、约束、事实、状态和下一步」。
根因在 src/powercontext/server/dashboard/labels.json：
| key | zh | en |
|---|---|---|
constraint |
约定 | Constraint |
decision |
决定 | Decision |
fact |
事实 | Fact |
decision 与 fact 都和文档一致，只有 constraint 对不上。docs/zh/ 全量统计：「约束」195 次，「约定」53 次，且那 53 次多为「命名约定」「约定俗成」等普通用法；描述这一类 Memory 时，README_CN.md、docs/zh/docs/get-started/core-concepts.md:50、docs/zh/docs/workflows/memory-and-handoff.md:12/66 一律用「约束」。
结果是中文读者在同一屏内看到两个词指同一件事。
这不是本 PR 引入的，但本 PR 新增的中文截图第一次把它带进了 README 的可见范围——英文截图里对应的是 "Constraint"，看不出这个差异。
两个修复方向，都不影响本 PR 当前可合并：
- 把
labels.json的constraint改为「约束」，然后重截这两张中文图（推荐：改一处即可，decision/fact已经一致，改动面很小）。 - 若「约定」是有意的译法，则反向统一
docs/zh/与README_CN.md的用词。
无需改代码逻辑，也无需改本 PR 的 Markdown。
There was a problem hiding this comment.
已修复，见 bc49eb5d。
采纳了建议方向 1（改 labels.json，而非反向改文档）：
constraint：约定 → 约束notes_subtitle：已保存的约束、决定及相关信息notes_empty_body：记忆用于保存约束、决定等信息。保存后可在此查看。
第二、三处是同一问题的连带项——这两个句子也在列举这几个 kind，只改 constraint 的话副标题仍会显示「已保存的约定、决定及相关信息」。
中文记忆页截图已按修正后的语言包重新生成（副标题与标签现在都是「约束」）。handoff 截图字节级完全一致，因为交接详情页不渲染 kind 标签——这也反过来验证了改动范围仅限记忆页。
验证：
- 两份语言包均保持 265 个键，键集合未变
labels.json中已无任何「约定」残留tests/test_dashboard.py+tests/test_release_version.py→ 33 passed- 截图仍为 1440x1080
生成截图时用的是仓库源码（工作区 .venv 是 editable 安装，指向 src/），而不是已安装的 1.3.0 发行包——否则语言包的改动不会生效。
There was a problem hiding this comment.
已闭环：bc49eb5d（labels.json 三处 约定 → 约束，含 notes_empty_body / notes_subtitle / constraint）+ 61f99bf6（按新标签重截中文记忆页截图）。
复核：新截图里该条目的内容类型已显示为「约束」，与 README_CN.md:36、docs/zh/docs/get-started/core-concepts.md:50、docs/zh/docs/workflows/memory-and-handoff.md:12 的用词一致，本线程可关闭。
重截时踩到一个坑，值得记一笔：第一次用 uv tool 安装的 1.3.0 起服务，截图里仍然是「约定」——修复在仓库源码里，而安装的包是旧版。改用工作区 venv（editable 指向 src/）起服务后才正确。
另外两个确认：
- 交接详情页不包含 constraint 标签，所以
readme-dashboard-handoff-zh.png无需重截——这也解释了为什么bc49eb5d只替换了记忆页那一张。 - 顺带全量复查过：三份 README 的 42 个相对链接全部可达、页内锚点 0 失效、
examples/jupyter的「22 篇」口径成立（01–22 共 22 篇，A1 是附录）、Dashboard 自 v1.3.0 起只有 labels.json 变化所以英文截图不过期、release_version.py --check退出 0、相关测试 33 passed。
之前那条「DashboardConfig 缺语言配置项」的观察维持原判：产品侧缺口，不属于本 PR 范围。
| > Context this expensive shouldn't depend on someone repeating it in every session. | ||
|
|
||
| ## Install, configure, and connect your Agent | ||
|  |
There was a problem hiding this comment.
[P3 · 仅记录，无需改动] 英文 / 日文 README 展示的是"可切换到的界面"，不是默认界面
接着中文截图那条，补一个反向的边界。
DashboardConfig（src/powercontext/server/settings.py:147-150）只有一个字段：
class DashboardConfig(BaseModel):
enabled: bool = False没有服务端语言配置项。 界面语言由 preferences.presentation() 决定：language = "zh" 是硬编码默认值，非法值也回退 zh，只能靠 query lang 或 cookie（powercontext_dashboard_language）覆盖。
因此：
README_CN.md现在与默认行为一致 ✅README.md/README_JP.md这里的英文界面截图，严格说是用户手动切换后才看到的视图——首次打开默认是中文
我的判断：对英文 / 日文 README 而言，英文界面仍是正确的编辑选择（给英文读者看中文界面没有意义），所以本 PR 不需要改任何东西。真正的缺口在产品侧——缺一个可配置的默认语言。若补上，给 DashboardConfig 加一个字段即可，届时三份 README 都能与各自读者的默认视图对齐。
仅作记录，不构成阻塞，不建议在本 PR 内处理。
The Chinese catalog labelled the `constraint` memory kind as 约定, while the English catalog says "Constraint" and every Chinese document uses 约束 (195 occurrences across docs/zh, including core-concepts and memory-and-handoff). The Chinese Dashboard screenshot added for the README made this visible next to prose that already said 约束, so the two disagreed on one screen. Update the label and the two sentences that list the same kinds, so the catalog matches the English one and the documentation: - `constraint`: 约定 -> 约束 - `notes_subtitle`: 已保存的约束、决定及相关信息 - `notes_empty_body`: 记忆用于保存约束、决定等信息。保存后可在此查看。 Regenerate the Chinese memories screenshot against the corrected catalog; the handoff screenshot is byte-identical because it renders no kind label. Verified: both catalogs keep 265 keys, no 约定 remains in labels.json, and tests/test_dashboard.py plus tests/test_release_version.py pass (33).
There was a problem hiding this comment.
Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.
An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.
All three READMEs linked to
powercontext.oceanbase.io/{en,zh}/docs/get-started/install-and-run/#retry-dependency-downloads-with-a-mirror
for "if dependency downloads are slow or fail". That anchor no longer exists:
- The live page carries nine heading anchors (platform-support, choose-a-version,
install-the-application, run-the-local-server, use-embedded-seekdb,
verify-the-installation, update-or-replace-an-installation, install-a-python-role,
install-and-run) and none of them is the mirror section; the zh page likewise has
no 镜像 anchor.
- docs/{en,zh}/docs/get-started/install-and-run.md no longer mentions a mirror at all,
and the website copy under website/content/docs/ is the same, so the section was
removed deliberately rather than moved.
The link returned 200 because the page loads, so it looked healthy while sending
readers to the top of a page with no mirror instructions.
Point the advice at uv's package-index documentation instead, which is the tool the
command actually uses and stays valid whatever mirror a reader picks.
Verified: no anchor fragments remain in the three READMEs; all 27 non-badge external
URLs return 200; no trailing whitespace; end-of-file newlines intact.
There was a problem hiding this comment.
Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.
An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.
| [capability matrix](https://powercontext.oceanbase.io/en/docs/integrations/capabilities/) for supported features and availability. | ||
| - `doctor` verifies integration setup. To verify automatic memory, check that a real prompt becomes a Source, produces a | ||
| Topic, evolves after a related prompt, and can be recalled in a new session using the same Scope. | ||
| - If Python dependency downloads are slow or fail, configure a package index for |
There was a problem hiding this comment.
[P3] 三份 README 的「镜像重试」链接指向一个已不存在的锚点
原链接（EN / JP）：
https://powercontext.oceanbase.io/en/docs/get-started/install-and-run/#retry-dependency-downloads-with-a-mirror
README_CN.md 是它的中文版：.../zh/docs/get-started/install-and-run/#使用镜像重试依赖下载。
该锚点已经不存在，证据：
- 线上页面是服务端渲染（随机路径返回 404，不是 SPA 回退），
install-and-run只有 9 个标题锚点：platform-support、choose-a-version、install-the-application、run-the-local-server、use-embedded-seekdb、verify-the-installation、update-or-replace-an-installation、install-a-python-role、install-and-run—— 没有镜像章节。中文页同样没有「镜像」锚点。 docs/en/docs/get-started/install-and-run.md与docs/zh/...现在完全不含 mirror / 镜像；website/content/docs/下的副本也没有。所以这一节是被主动删除的，不是搬到了别处。
危险之处在于这个链接返回 200，看起来是健康的——因为页面本身能打开，只是会停在页面顶部，读者完全找不到镜像说明。
历史上它确实存在过：b15b586c（#1545）中该文件第 37 行就是 ## Retry dependency downloads with a mirror。
已在本 PR 修复（44d02c9d）：把建议改指向 uv 的包索引文档 https://docs.astral.sh/uv/configuration/indexes/——命令本来就用的 uv，无论读者选哪个镜像都成立，也不依赖本仓库未来是否恢复该章节。三语同步。
备选做法（若维护者更倾向）：把该章节恢复到 docs/{en,zh}/docs/get-started/install-and-run.md 并沿用原锚点。我没有单方面改动产品文档结构，先取了不依赖它的最小修复。
验证：三份 README 现已无任何锚点片段；27 个非徽章外链全部 200；已记录 commit 的动机与证据。
knqiufan
left a comment
knqiufan
left a comment
There was a problem hiding this comment.
Reviewed commit bc49eb5d79a0ce903ef3c1183646519f133490af. Requesting changes for one remaining P2: the new README Memory identity and lifecycle descriptions still document the legacy contract, so readers following them encounter unsupported-operation errors. Please update all three language versions; details are in the inline comment.
The public HTTP reproduction used local SQLite and ASGI at ca763bdf; the affected README passages and relevant runtime code are unchanged at the current head. This is a targeted follow-up, not a new full-PR review. OceanBase and native host acceptance were not executed.
AI-assisted review using Open Code Review and Codex. Open Code Review found no issues in the release script; the documentation finding was independently verified with Codex.
Replacing the LoCoMo Plus figure with a Markdown table left docs/assets/readme-locomo-plus.svg unreferenced: a workspace-wide search finds no remaining reference, no build step copies docs/assets wholesale, and no test reads that path. The file was added by #1873 as a README asset, so with the table carrying the same scores there is nothing left for it to serve. The table also keeps the numbers readable to crawlers, which was the point of the change. It stays recoverable from history (`git show 2d3ea6e:docs/assets/readme-locomo-plus.svg`) if the figure is wanted again. Verified: all three READMEs still reference four images each, all of which exist.
There was a problem hiding this comment.
Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.
An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.
The integrations table lists every shipped host package, and MiniMax Code is one of them (added by #1954). MiniMax is not a qualified host though: integrations/capabilities.toml records it under [directory_exclusions] as "awaiting one-command setup and native qualification under #1840; not yet included in the supported host catalog", it has no page under docs/{en,zh}/docs/integrations/, no row in the capability matrix, and no `status:` frontmatter tag. The sentence above the table said "other hosts and Python Agent frameworks are `community`", which does not hold for a host that carries no tag, so the tag list now says "other maintained hosts" and defers qualification to the matrix the same paragraph already links to. The tile itself stays: the package is real and its README documents loading it, so removing it would revert a deliberate addition rather than fix the claim. Making MiniMax a qualified host is a product decision tracked by #1840.
There was a problem hiding this comment.
Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.
An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.
|
|
||
| ## Connect your Agent | ||
|
|
||
| Codex is `official`; other maintained hosts and Python Agent frameworks are `community`; Bub is `evaluation` only. |
There was a problem hiding this comment.
[P3] 表格里的 MiniMax Code 不是已资格验证的宿主，而这段标签说明原本默认它是
表格中 15 个磁贴里，MiniMax Code 与其余 14 个来源不同——它没有集成文档页，也没有任何维护标签。证据：
integrations/capabilities.toml:20的[directory_exclusions]明确写着：「Host package awaiting one-command setup and native qualification under feat(minimax): provide one-command plugin setup and native verification #1840; not yet included in the supported host catalog」。feat(minimax): provide one-command plugin setup and native verification #1840 目前仍是 OPEN 的 issue。docs/{en,zh}/docs/integrations/下没有minimax.md；meta.json的页面清单里也没有它。docs/en/docs/integrations/capabilities.md的能力矩阵（本段所链接的那张表）共 15 行，没有 MiniMax。- 其余 14 个集成的 markdown 都有
status:frontmatter（codex= official，其余 = community，evaluation页 = evaluation）；MiniMax 没有。
所以原文「Codex is official; other hosts and Python Agent frameworks are community」对 MiniMax 不成立——它不属于任何一个标签。
已在本 PR 做了最小修正（3393f411）：改成 "other maintained hosts"，并把资格判定交还给同一段已经在链接的能力矩阵。
没有移除那个磁贴，因为包是真实存在的（integrations/minimax/README.md 记录了如何本地加载），删掉等于回退 #1954 的一次有意添加，而不是修正这句话本身。是否把 MiniMax 提升为合格宿主属于产品决策，由 #1840 跟踪。
若维护者倾向另一种做法（在 #1840 落地前先隐藏该磁贴），改动只有一行，随时可以调整。
| — **+37.88 points** over full context. | ||
| - **Coding tasks (SWE-bench Pro): 86.73% task resolution with PowerContext on, 82.35% with it off** — **+4.38 points** | ||
| and 32 more tasks resolved in a 731-task paired run. | ||
| - **Retrieval quality (LoCoMo Plus)**, native PowerContext against PowerContext with Jev candidate filtering after |
There was a problem hiding this comment.
[P3] 这一行替换掉 SVG 之后，docs/assets/readme-locomo-plus.svg 成了无人引用的孤儿
改用 Markdown 表格承载 LoCoMo Plus 的分数是对的（数字从此对爬虫可读，这正是本次改版的目的），但它让原图失去了唯一引用点。
核查结果：
- 全工作区检索
readme-locomo-plus：0 处引用（三份 README、docs/、website/ 都没有）。 - 该目录没有被整体拷贝的构建步骤（
website/、scripts/下无docs/assets的批量引用）。 tests/下没有任何测试读取docs/assets。- 该文件由 feat(benchmark): add LoCoMo Plus Jev comparisons and results #1873 添加，文件名带
readme-前缀，即专为 README 而生。
已在本 PR 清理（0ad547b9），因为它是本次改版造成的孤儿，而不是历史遗留：
- 删除
docs/assets/readme-locomo-plus.svg（5 KB，72 行） - 表格已完整承载同一组分数（GPT-4o-mini 40.855 → 49.78、Qwen3.7-plus 60.37 → 68.947、GPT-4o 65.082 → 69.28）
- 需要时可随时从历史恢复：
git show 2d3ea6e2:docs/assets/readme-locomo-plus.svg
若维护者希望保留这张图（例如后续给官网复用），我可以把删除回退，并在 benchmark 小节保留一个链接指向它——只是那样图表与表格会同时存在，故默认取了删除。
The Scope tree wrote Memory as `memory/ARTIFACT_ID@REVISION`, but Memory
references carry the `atomic-memory` family:
- `POST /v1/memory/remember` returns `"family": "atomic-memory"` for each record.
- docs/en/docs/develop/http-api.md:205 lists the surface as
`/v1/scopes/{scope_id}/artifacts/*` with `family=atomic-memory`.
- docs/en/docs/workflows/atomic-memory.md:35-55 and faq.md:108 use
`/v1/scopes/S/artifacts/atomic-memory/M`.
- The Dashboard screenshot added earlier in this PR renders references as
`atomic-memory/art_...`, so the tree contradicted the image directly beneath it.
The Handoff line already matched (`handoff/handoff@1` is what /v1/handoff/commit
returns), so only the Memory line changes. `get-started/core-concepts.md:44` still
enumerates `memory` among the write-capable families, which is a separate docs
question and not something this PR should settle.
Verified: no other `memory/` reference remains in the three READMEs; structural
counts and formatting unchanged.
There was a problem hiding this comment.
Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.
An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.
The "Explore in Python first" block told readers to run `pip install "powercontext[cli]==1.3.0"` and then work through the Jupyter tutorials. That cannot work: the notebooks are not part of any published extra. pyproject.toml exposes `code`, `builtin`, `seekdb`, `client`, `server`, `tracing-otlp`, and `cli`, while the tutorial dependencies live in the `notebooks` dependency group, which pip cannot install, and examples/jupyter/README.md already documents that the course needs a full repository checkout. Replace the command with the sequence the tutorial README uses, so the quick-start path no longer points at an installation that leaves the notebooks unrunnable. Verified: the new commands match examples/jupyter/README.md:16 word for word, no `pip install` for the tutorials remains in any locale, and the eight structural counts still agree across the three READMEs.
There was a problem hiding this comment.
Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.
An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.
| ```text | ||
| Scope | ||
| ├── Source journal # evidence: prompts, documents, work contracts, task outcomes | ||
| ├── Memory # atomic-memory/ARTIFACT_ID@REVISION — decisions, constraints, next steps |
There was a problem hiding this comment.
[P3] Scope 树里 Memory 的 family 写错了：应为 atomic-memory，不是 memory
这一行原文是 memory/ARTIFACT_ID@REVISION，但 Memory 的引用实际使用 atomic-memory 家族，四处证据一致：
POST /v1/memory/remember的响应里每个记录都是"artifact": {"family": "atomic-memory", "artifact_id": "art_<hex>", "revision": 1}。docs/en/docs/develop/http-api.md:205：Atomic Memory | /v1/atomic-memory/*, /v1/scopes/{scope_id}/artifacts/* (family=atomic-memory)。docs/en/docs/workflows/atomic-memory.md:35-55与docs/en/docs/get-started/faq.md:108都用/v1/scopes/S/artifacts/atomic-memory/M。- 更直接的是：本 PR 加的那张 Dashboard 截图里，引用就渲染为
atomic-memory/art_…—— 也就是说这段树状图和它正下方的配图互相矛盾。
Handoff 那行本来就是对的（/v1/handoff/commit 返回 handoff/handoff@1），所以只改了 Memory 一行。
已修复（6f3d1c8a），三语同步。
一个顺带发现，供维护者判断，本 PR 不处理：docs/en/docs/get-started/core-concepts.md:44 写的是「write-capable families are memory, experience, skill, handoff, profile, prompt」，而运行时的家族清单（powercontext ready 的 access_artifact_families）同时注册了 atomic-memory 和 memory。两者关系（是否为历史遗留家族）不在本次改版范围内，我没有改文档。
| For a Server on another machine, use HTTPS or follow the | ||
| [remote connection guide](docs/en/docs/operate/connect-remote-server.md). Setup recognizes remote HTTP URLs from | ||
| flags or environment variables and asks for explicit consent; automated setup uses `--allow-insecure-http`. | ||
| The tutorials run from a repository checkout and take their dependencies from a `uv` dependency group, so they are not |
There was a problem hiding this comment.
[P2] 教程那条命令跑不通：notebooks 不在任何 pip extra 里
原文让读者 pip install "powercontext[cli]==1.3.0" 之后直接去做 Jupyter 教程。这条路径走不通：
pyproject.toml的 optional-dependencies 只有code、builtin、seekdb、client、server、tracing-otlp、cli——没有 notebooks。- 教程依赖在 dependency group
notebooks里（[dependency-groups]），pip 装不了 dependency group。 examples/jupyter/README.md:13自己写明了：完整课程需要uv和这个仓库的完整 checkout。
也就是说按原文照做，读者装完之后手上没有任何 .ipynb，也无从启动 Jupyter。
已修复（5439220a），三语同步，替换成教程 README 里同一套命令：
uv sync --locked --group notebooks
uv run --locked --group notebooks jupyter lab --notebook-dir=examples/jupyter并补了一句说明「教程依赖 uv 的 dependency group，不在 powercontext 包内」，避免读者再去找 pip 的安装方式。
验证：新命令与 examples/jupyter/README.md:16 逐字一致；三语已无该 pip install。
Addresses the P2 from @knqiufan: the Memory paragraph still said entries are "active or inactive" and that "retiring" removes one from active recall. Neither matches the current Atomic Memory contract. - docs/en/docs/workflows/atomic-memory.md:102 lists the states as ["active", "forgotten", "merged", "retired"], and :79-81 says forgetting does not advance the content revision. - The lifecycle endpoint accepts one state only: AtomicMemoryLifecycleState is an enum of `forgotten` in openapi/powercontext.yaml. - Removal from active recall is a forget through `POST /v1/atomic-memory/lifecycle`, copying the exact reference and `state_version` from a state read (:66-75), after which the content stays available and restorable (:62). - `retired` is the opposite of restorable, so "retiring" was the wrong verb for taking something out of recall. Rewrite the paragraph in all three locales to name the four states and the forget action, keeping the earlier `atomic-memory` family fix in `6f3d1c8a` consistent with it. Note for follow-up, not changed here: docs/en/docs/get-started/core-concepts.md:56-57 still says "Entries can be active or inactive; retiring an entry removes it from active recall", which is where this wording came from and which the atomic-memory contract supersedes.
There was a problem hiding this comment.
Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.
An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.
…label fix bc49eb5 changed the Dashboard label for the constraint Memory kind from 约定 to 约束, but the committed Chinese screenshots still showed 约定 — they were captured before that fix landed, so README_CN.md showed a term its own prose (and docs/zh) does not use. Recapture both pages against the fixed label. The Dashboard this time runs from the repository checkout (the workspace venv points at src/), because the installed uv tool is 1.3.0 and predates the label change. Same synthetic inventory-schema-migration scope, same 1440x1080 viewport, same pages.
There was a problem hiding this comment.
Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.
An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.
knqiufan
left a comment
knqiufan
left a comment
There was a problem hiding this comment.
Reviewed commit 61f99bf6ff414a9fb6ccbf8bf7ede55f39456396. The previously reported P2 is fixed in all three READMEs: exact Memory references use atomic-memory, the four lifecycle states match OpenAPI, and forgetting is correctly described as removing active recall while preserving restorable content/history without advancing the content revision. The updated Chinese screenshot was also inspected. No remaining blocking findings from this review; approving.
This follow-up checked the documentation against the current contract and inspected the latest image; runtime acceptance tests were not rerun. AI-assisted review using Open Code Review and Codex.
Which issue or RFC does this PR close?
Related to #1713.
不完全关闭 #1713：该 issue 还包含 one-line install 的 Skills guidance，本次改动不涉及。
Rationale for this change
README 讲清了 PowerContext 做什么，却没有足够清晰地说明它是什么、为什么其记录可跨会话持续使用，以及读者如何快速验证这些结论。原有 benchmark 结论也主要留在 SVG 内，GitHub 搜索和文本读取场景无法直接提取。
What changes are included in this PR?
按
What is -> Why -> How a task keeps moving -> Proof it works -> Quick start主干重排，三语同步：### Memory与### Handoff之下，使用本地 Server 的合成库存 schema 迁移记录，分别展示可检查的 Memory 与包含进展、下一步和 Source 证据的已提交 Handoff；不含真实项目、凭据或环境信息。zh（preferences.CATALOGS只有zh/en，language = "zh"），因此README_CN.md改用?lang=zh重新截取的同一组页面（readme-dashboard-memories-zh.png、readme-dashboard-handoff-zh.png）。英文与日文 README 继续使用英文界面资产，因为不存在ja语言目录。scripts/release_version.py的版本引用锚点，并统一 Windows 上的相对路径诊断格式，避免make version-check失效。在本 PR 内复核时发现的既有问题，一并修正：
labels.json的约束译法：中文语言包把 memory kindconstraint译作「约定」，而英文是Constraint、docs/zh/全用「约束」；新增的中文截图让这处不一致显形。改动constraint及另外两处列举同类项的句子，并重新生成中文记忆页截图。install-and-run/#retry-dependency-downloads-with-a-mirror，但该章节已被移除——线上页面只有 9 个标题锚点、无一匹配，本地文档与website/content/docs/副本也都不含 mirror。改为指向 uv 的包索引文档。该链接此前返回 200，因此看起来是健康的。docs/assets/readme-locomo-plus.svg失去唯一引用，予以删除（可用git show 2d3ea6e2:…恢复）。integrations/capabilities.toml的[directory_exclusions]，由 feat(minimax): provide one-command plugin setup and native verification #1840 跟踪），故将「other hosts … arecommunity」改为「other maintained hosts」，并把资格判定交还能力矩阵；磁贴本身保留，是否提升为合格宿主是产品决策。memory/ARTIFACT_ID@REVISION，实际引用为atomic-memory/…，与本页截图一致。pip install "powercontext[cli]==1.3.0"之后即可做教程，但 notebooks 只存在于uv的 dependency group 中，pip 装不到；改为教程 README 的uv sync --locked --group notebooks流程。保留不动：原有全部散文陈述、benchmark 摘要 SVG、集成 logo 表、贡献者墙、许可证，以及已有的诚实 caveat。
未包含 demo 视频：仓库中没有可作为 README 长期链接的官方视频资产或规范链接，因此不新增临时视频。
Are there any user-facing changes?
是。三个 README 的结构、首屏内容和两张 Dashboard 示例截图发生明显变化（中文 README 使用中文界面版本）。另外
src/powercontext/server/dashboard/labels.json修正了constraint的中文译法（约定 → 约束），这会改变中文 Dashboard 的可见文案；删除了一张不再被引用的docs/assets/readme-locomo-plus.svg。scripts/release_version.py仅调整版本引用的校验与诊断路径格式。没有运行时 API、持久化格式或兼容性行为变更。How was this change tested?
uv run --no-sync pytest tests/test_release_version.py -q->12 passeduv run --no-sync python scripts/release_version.py --checkuv run --no-sync ruff check scripts/release_version.pyuv run --no-sync ruff format --check scripts/release_version.pyuv run --no-sync ty check --python-version 3.11 scripts/release_version.py1440x1080视口实际打开两张截图对应页面；页面 console 无 error，截图内文字和 Source/Artifact 引用均与写入记录一致。git diff --check通过。<details>/ 链接 /<td>八项计数完全一致。href均命中实际文件；27 个非徽章外链全部 200；带锚点的链接逐条与目标页面的id集合比对（这是发现失效锚点的方式）。uv run --no-sync pytest tests/test_dashboard.py tests/test_release_version.py -q->33 passed。AI usage statement
本 PR 由 WorkBuddy（底层模型 Claude）协助起草，后续文案核验、Dashboard 合成记录创建、浏览器截图和命令验证由 Codex 协助执行。所有技术陈述均对照当前代码、接口和 Dashboard 实际渲染结果；benchmark 数字来自仓库内 SVG 源文件，未做修饰。