Skip to content

v0.7.36 — 文档对齐真实实现 + 8 个真实缺陷修复

Choose a tag to compare

View all tags
@kingdol666 kingdol666 released this 11 Sep 17:26
· 130 commits to main since this release
v0.7.36
4d0b68a

v0.7.36 — 文档对齐真实实现，并修掉对齐过程中暴露的 7 个真实缺陷

这一版的主线是把 README / VitePress 双语文档全部对齐到代码事实。三个并行只读审计逐行
对照源码，独立对抗式复核又按机械规则随机抽样 41 条断言复验 —— 命中的假声明全部修掉，
而更要紧的是：对齐过程中暴露了 8 个真实代码缺陷，它们此前一直与文档承诺相矛盾。

修复的真实缺陷

# 缺陷 影响
1 createPluginContext 漏接宿主的 onDispose 注入口 ctx.onDispose / ctx.timer.* / ctx.subscriptions.add 登记的清理永不执行：热重载后旧定时器继续跑，退出前 200ms 的 kv 写入丢失
2 客户端插件卸载挂在 visibilitychange→hidden 且 dispose() 一次性 用户切一次标签页，全部插件面板与订阅就永久失效直到刷新。改为 pagehide
3 ctx.route() 返回 undefined，类型声明却是 boolean 宿主 registerRoute 少了 return；已补齐并只在成功时记账
4 sdk/index.d.mts 与运行时两头不符 少了 4 个函数的声明 + 多个资源的 update/remove + permissions + ctx.config.define* + 宿主注入面；同时声明了一个运行时不存在的具名导出 el
5 配置分组字段名：类型写 groups，宿主读 configGroups 照类型写插件会得到一个被静默忽略的键
6 -g / -f / -y 短选项被静默丢弃（无命令声明 meta.short） aw register x.mjs -g 不报错地注册到项目级而非用户级
7 设了 AW_HOME 时，全局注册的指令永远扫描不到 写侧用 awHome(env)、读侧用 homedir()，两边统一
8 对外示例本身是坏的 三个 sdk/examples/*/client.mjs 订阅的是服务端钩子名，浏览器里全是静默空订阅；Array.isArray(await api.lines.list()) 恒为 false（该接口返回 { lines, states }）

另修：LIFECYCLE_EVENTS/CLIENT_EVENTS 两份"单一事实源"清单各缺一项；
config.yml 的 app.version 长期停在 0.7.9 而 /api/health 直接回显它（现以 package.json 为准，
实测已报 0.7.36）；若干注释级事实源错误。

文档

  • 新增英文事实源 docs/{cli,plugins,sdk}.en.md，部署工作流改为中英成对同步。
    此前只有中文单页指南由 CI 覆盖，英文页长期手工维护，最大缺口达 87%
    （英文 CLI 手册 29 行 vs 中文 227 行）。
  • README / README-zh：补上一直缺失的 AML 模块、插件与 SDK 文档索引、完整路由清单、
    退出码与 --json 契约；修正 73→98 设置项、6→14 执行引擎（并按接入形态分三类）、
    "npm 安装首次要构建 2-3 分钟"（tarball 本就含 .output）、"npx 零残留"、
    不存在的版本迁移承诺、pnpm aw 等。两份 README 经机械校验逐项 1:1
    （40 标题 / 146 表格行 / 32 围栏 / 15 图 / 6 徽章）。
  • 文档站新增 /guide/aml；补齐配置根解析规则与环境别名表、14 行引擎表、
    英文许可证页（此前漏掉全部义务条款）、权限与数控读写页的英文程序化访问章节。
  • 端到端验证段落改为可追溯（套件 → 最新结果 → 复跑命令），并区分当前 head 与历史基线。

视觉

文档站新增材质/动效/可读性层，并经一次敌意评审 + 15 条实测复验（15/15）：

  • 修掉一个真·阻断缺陷：appearance:false 却不声明 markdown 主题 → VitePress 注入了
    浅色 Shiki 调色板，代码块里出现 1.49:1 的字符串色，正文级不可读。改用 github-dark-default。
  • 显式声明 CJK 字体族（VitePress 的 zh 默认栈里没有任何中文字体）。
  • 导航玻璃、顶缘镜面、分层投影、弹簧缓动、阅读进度条（scroll-driven，零 JS）、分节入场、
    焦点环修正、390px 布局修补。
  • 评审提出的 5 个阻断项全部修复并复验：入场动画选择器此前匹配 0 个元素；
    reduce-motion 总闸把每个侧栏条目都点亮成"当前页"；:focus-visible{border-radius:0}
    把 CTA 压成方角；390px 下控制台标题被挤成省略号；正文链接下划线规则漏排 .hw-btn。

新增守卫

  • scripts/check-docs-sync.mjs（58 断言）：CI 复制对逐字节同源、中英页对标题层级序列与
    代码块数同构、文档里硬编码的版本号与 npx 锁定示例必须等于 package.json、
    13 类已知错误断言不得回归、VitePress 模板安全（正文裸尖括号会让构建直接失败）、
    表格内联代码里未转义的竖线。
  • scripts/test-plugin-lifecycle.mjs（22 断言）覆盖上面第 1、3 项。
  • test-cli-exit.mjs 增加 14 条断言：每个内建指令都必须能真正 import ——
    registry 会把 import 失败吞进 failures，指令静默消失而静态检查看不出来
    （本次真实踩坑：模板字符串里漏转义一个反引号）。

验证

项目 结果
e2e-full-closedloop.mjs（0.7.36 生产构建，隔离环境） 124 PASS / 0 FAIL
e2e-aml.ts --real 0 失败
check-docs-sync 58 / 0
docs-v3-verify（视觉逐条实测） 15 / 0
文档站构建 + 11 路由截图 全绿，0 前端/请求错误
离线套件 cli-exit 66/66 · data-root 52 · log-flooding 31 · plugin-lifecycle 22 · lru 20 · rollback-index 20 · memory-month-query 16 · plugin-hardening 13 · events-index 8 · sdk-surface 全过
发布包验收 18 / 0
eslint / tsc 0 error / 0

安装

npm install -g agentworkshop
aw start

本版 tarball 已随附（agentworkshop-0.7.36.tgz），含预构建 .output，npm 安装后直接启动、无需构建。

在线文档：https://kingdol666.github.io/AgentWorkShop/

Assets 3
Loading