Skip to content

feat(documentation): 托管插件静态文档快照 - #41

Merged
xiaoland merged 9 commits into
mainfrom
feat/extension-documentation
Sep 21, 2026
Merged

xiaoland merged 9 commits into
mainfrom
feat/extension-documentation

Conversation

@xiaoland

@xiaoland xiaoland commented Sep 21, 2026

Copy link
Copy Markdown
Member

Registry 现在可按精确 Extension Release 和 globalpythonmodule-federation scope 托管作者自行构建的静态文档。作者可修订文档而无需发布新的插件版本,旧快照仍保留完整资源和原所属 Release 的生命周期约束。

实现

  • 完整 ZIP staging 成功后,在 Release 行锁内重检 ETag 并原子替换当前指针;PostgreSQL 复合外键保证指针与快照属于同一 Release/scope。
  • 每个快照使用独立 origin。管理域与内容域须为不同可注册域,由包内 ICANN/private PSL 校验,启动不访问网络;本地 HTTP loopback 配对除外。blocked 拒绝历史读取,yanked 稳定入口提示撤回。
  • DocumentationRepository 独立拥有文档查询、事务和共享并发额度,使用现有 ArtifactStore。
  • Toolkit 0.3.0 已通过 Changie 准备,Registry 依赖为 >=0.3,<0.4;提供地址生成、候选打包、幂等发布及发现。
  • 发布使用 POST,expected_etag 是必填可空业务字段。snapshot_id 与完整不可变请求(含原始前提)共同识别候选;精确重放返回原历史提交回执,不移动 current,也不更新 current 时间。同 ID 改写身份或新候选前提过期返回 409;鉴权和 blocked 检查仍优先。
  • 快照行本身就是事务提交回执,不增加 operation 表或后台恢复任务。回执的 committed_atsnapshot_etag 不表示它仍为 current;A 成功后被 B 替换,重试 A 仍确认 A,而不会回滚 B。
  • Toolkit 仅 best-effort:网络错误、500/502/503/504 或无效回执最多原样重试一次;仍无法确认则以非零退出报告“结果未知”,保留候选供稍后原样重试,不刷新 ETag/ID、不承诺最终送达。明确的客户端错误不重试。
  • JSON Schema 包含 upload/publication/receipt/release/hosting;OpenAPI 描述 JSON 文本字段的 contentSchema 与错误响应。作者协议完整列出 ZIP、路径、MIME 和资源限制,并提供逐步发布命令。

验证

完整 pnpm check 在 Node 22 下通过。新增 wheel 安装检查从构建产物和依赖元数据创建干净环境,执行 pip check 与服务 import,防止 workspace 隐藏错误版本依赖。

一次性 PostgreSQL 17 + Moto 验收覆盖真实迁移、跨 Release/scope 指针拒绝、被引用快照归属修改拒绝、并发条件替换、失败 staging、历史快照、blocked/yanked 及 ZIP 安全边界。新增 A→B→重试 A 的历史回执/current 不变、同 ID 并发只产生一个快照且回执相同、不可变身份冲突与 blocked 重放拒绝。Toolkit 在 HTTP transport 边界模拟响应丢失、503、无效回执和 409,验证最多两次请求及未知结果;这不是实际网络丢包 E2E。配置回归覆盖多级公共后缀、private PSL、同站拒绝、本地例外和大小写域名。原有真实 VitePress 输出打包验收保持有效。

交付与运维

追加 0003 文档模型迁移和 0004 归属约束迁移,运行账号获得文档表所需权限。生产启用还需配置独立内容域 DNS/TLS 和 DOCUMENTATION_ORIGIN_TEMPLATE,内容域不得接入 SSO 或共享认证 Cookie。配置校验无法盘点其他服务的 Cookie,因此独立内容域仍是部署责任。

本 PR 保持 Draft;本次未部署服务、修改生产域名或发布包。未来合入 protected main 后,现有 package release 流程会发布准备好的 Toolkit 0.3.0;Registry 生产部署另行执行。回滚服务时保留新增表和已发布快照,不通过反向迁移删除文档数据;必要时可暂时关闭内容域入口并修复后重新部署。

相关交付

2026-09-21:Web 消费接口与本轮验证

  • 独立 Web Runtime 复用真实 SDK 的 PeerManager,提供精确目标管理命令、已宣告管理能力的在线 Peer 列表和独立 exact Release 文档发现。应用保留本地/远端/离线策略;不引入 Wizard 框架。
  • 删除 ambient SDK stub,按固定 producer SHA 的冻结 lock 构建真实 SDK;输出仅位于本 workspace 的私有 node_modules,不修改 pnpm store。
  • Runtime 包级 HTTP 边界检查、完整 PG/Moto 本地门禁通过。真实 Memos 0.3 候选的 Python/MF 及三组文档经正式 API 发布至隔离 Registry,实际 Web 外链导航与作者锚点通过。
  • 9615b0d 已解决构建阻塞:只检出固定 SHA 的 packages/core,用 ext-reg 自身冻结依赖构建真实 SDK;不安装 Web 根 workspace,撤回额外包认证。无 token/禁用户 npmrc/全新 store 安装通过,远端35587933605全部通过(含完整门禁、镜像与HTTP/数据库smoke),未关闭供应链检查。最终候选再次被 Web 完整门禁验证。
  • 新 Runtime minor intent 尚未正式发布;Web #115 的公开依赖更新需等待真实产物,不提交本机路径或虚构 lock。各 PR 不可据此直接合并。

- 固定到已确认的静态快照托管合同
- 按 Release 与文档渠道保存不可变静态资源快照
- 提供条件写入、稳定入口与独立内容源访问
- 补齐契约、生成客户端、迁移与行为检查
- 从任意静态站点输出打包文档候选
- 支持查看、创建及条件替换 Registry 文档
- 对丢失响应执行精确候选恢复
@xiaoland
xiaoland marked this pull request as ready for review September 21, 2026 10:48
@xiaoland
xiaoland merged commit 8ed374d into main Sep 21, 2026
2 checks passed
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.

1 participant