diff --git a/07-%E5%BC%80%E5%8F%91%E4%B8%8E%E6%B5%8B%E8%AF%95.-.md b/07-%E5%BC%80%E5%8F%91%E4%B8%8E%E6%B5%8B%E8%AF%95.-.md new file mode 100644 index 0000000..b8c7029 --- /dev/null +++ b/07-%E5%BC%80%E5%8F%91%E4%B8%8E%E6%B5%8B%E8%AF%95.-.md @@ -0,0 +1,164 @@ +# 07 · 开发与测试 + +> 面向改代码的人(与 agent)。**先读 [02-系统架构](02-系统架构) §六「关键不变量」**, +> 再动手改,能省掉大部分回退。 + +## 一、工程约定 + +| 项 | 约定 | +| --- | --- | +| 语言 | TypeScript **strict**(含 `noUncheckedIndexedAccess`)、ESM、导入写 `.ts` 扩展名 | +| 构建 | `tsdown`(rolldown),host/client 双产物;懒加载 chunk 走 `src/client/chunks/` | +| 包管理 | `pnpm`(11.x);`pnpm install` 会触发 `prepare` 构建 | +| 测试 | `vitest`;默认 node 环境,需要 DOM 的 spec 用 `// @vitest-environment jsdom` | +| 宿主 peer | `dsh-better-sidebar`(本仓库已改名)**永不打包**,必须留在 peer/neverBundle 一侧 | +| 命名 | 信息层 tab id 前缀 `apes:`;插件名 `dsh-apes-sidebar` | +| 颜色 | 只用 `--dsw-alias-*` 设计令牌(`var(--token, <回退>)`),不写死色值 | + +## 二、目录结构(`main` 实况) + +``` +src/ + index.ts HOST 入口:name / inject / apply(ctx, config),路由与围栏装配 + invariant.ts 零依赖不变量面(host/client 共用) + context-types.ts cordis 服务面契约(ctx.sessions / sidebarRight / …) + trust-fence.ts 请求信任围栏(Host 头 / 令牌) + html-route.ts /sidebar/html 路由(路径围栏 + 体积上限) + config.ts 挂载行配置 schema 与默认值(readLimit / mediaLimit / …) + fs-*.ts git.ts … 文件系统、Git、会话、任务、终端等 host 能力 + client/ + index.tsx CLIENT 入口(apply):装配 store/service/native/apes + service.ts ctx.betterSidebar 服务实现(对外 API + 能力清单) + state.ts 侧边栏状态存储(store) + native/ 原生右侧栏适配(tab 记录、tab 体、tab 芯片标题) + builtins/ 内置面板:editor / git / subagent / sidechat / terminal / browser + 预览器 + sidebar/ 自绘底部工作台与开合控件 + apes/ 信息层三 tab(本 fork 增量:tabs.tsx / icons.tsx / locales.ts) + changes/ diff/ 文件变动与 diff 视图 + chunks/ 懒加载 chunk:editor / locale / mermaid / terminal + locales*.ts i18n(`locales.ts` + 19 个语言覆盖文件) + *.module.css 组件样式(含 sidebar.module.css:面板宿主层契约) +tests/ vitest specs(131 个文件,含 e2e/ 的挂载脚本型用例) +scripts/ install / switch / e2e 挂载 / 发布辅助 +docs/ external-plugin-guide.md(对外契约)+ plans/(上游历史设计)+ wiki/(本百科源文件) +``` + +## 三、门禁(提交前必跑) + +```bash +pnpm typecheck # tsc --noEmit(strict) +pnpm build # rm -rf lib && tsc(d.ts) && tsdown +pnpm test # vitest run +``` + +当前基线(本次会话实测):`main` = 131 文件 / **1367 通过** + 9 skip; +`sync/v0.24.1` = 141 文件 / **1515 通过** + 9 skip。全量 test 约 3–4 分钟。 +**任何一条不过就不要提交**;三条全绿才算完成。 + +## 四、测试体系(按层次) + +| 层次 | 环境 | 手法 | 代表 spec | +| --- | --- | --- | --- | +| 宿主插件形状 / 对外契约 | node | 断言导出面与语义(含与 `package.json` 的版本一致性) | `smoke.spec.ts` · `plugin-shape.spec.ts` · `service.spec.ts` · `consumer-types.ts` | +| 原生侧边栏适配 | node | 用「类型为真、运行时为假」的 mock 注册表 | `native-surface.spec.ts` | +| 面板宿主与层叠契约 | node + jsdom | CSS 断言 + DOM 挂载点解析 | `panel-host-css.spec.ts` · `panel-host-parent.spec.ts` | +| 预览交付 | node + jsdom | 纯逻辑(`` 注入)+ 客户端挂载(stub `fetch`,`createRoot` + `act`) | `html-preview.spec.ts` · `html-preview-frame.spec.tsx` | +| 沙箱契约 | node | 对渲染结果做**字符串断言**(服务端渲染把 `srcDoc` 输出为 camelCase `srcDoc=""`,与客户端设置的真实属性 `srcdoc` 不同 —— 断言方式随之不同) | `sandbox-views.spec.tsx` | +| 信息层 tab | node | mock `ctx.sessions.list` 与投影 | `apes-tabs.spec.ts` | +| 桌面环境探测 | node | stub 全局(URL stamp / preload 标记) | `desktop-env.spec.ts` | + +约定: +- **不引入 jsdom 到默认环境**:需要 DOM 的 spec 在文件头写 `// @vitest-environment jsdom`。 +- **不依赖真实 DSH 宿主**:需要真宿主的用例归到 `tests/e2e/`(脚本型挂载),不进单元门禁。 +- 新增「契约」必须**同时新增 pin 它的 spec**(例如本文档提到的 25 层级、沙箱令牌、`srcDoc` 交付方式, + 都有对应断言)。改契约 = 改代码 + 改 spec,两者必须一起提交。 + +## 五、扩展点(对外服务) + +其他插件通过 `ctx.betterSidebar` 接入: + +```ts +// 注册一个 tab 类型 +await ctx.betterSidebar.registerTab(descriptor) +// 注册一个文件预览器 +await ctx.betterSidebar.registerFileViewer(viewer) +``` + +- 服务按**能力清单**做前向兼容门控(能力只增不减),消费方应据此判断可用性而非版本号比较。 +- 完整契约、字段表与示例见仓库内 [docs/external-plugin-guide.md](../blob/main/docs/external-plugin-guide.md)。 +- 改服务面时:**只能新增**;删除或改语义需同步更新能力清单、指南与本百科。 + +## 六、上游同步:测量式 re-base(本项目的方法论) + +**不 merge 上游**。上游每个版本差距可达数百文件,直接合并会引入无关变更并放大冲突面; +本项目改用「先测量、再重建、后补增量」: + +### 步骤 + +**① 测出自己的增量(把改名归一化掉)** + +```python +# 对每个变更文件:取出两边 blob,把改名归一化后比较 +old = git('show', f'{base}:{path}'); new = git('show', f'HEAD:{path}') +rename_only = old.replace('dsh-better-sidebar', 'dsh-apes-sidebar') == new +``` +→ 得到三张清单:**仅改名**(自动处理)/ **真改动** / **新增**。数量级参考:v0.19.1→v0.24.1 为 +78 / 11 / 10。 + +**② 确定改名的精确范围(不要重新推断)** + +```bash +# 仍保留上游名字的文件 = 有意保留(本仓库为 README.md、package.json、docs/plans/*) +comm -12 <(git grep -l 'dsh-better-sidebar' <旧基线> | cut -d: -f2 | sort) \ + <(git grep -l 'dsh-better-sidebar' HEAD | cut -d: -f2 | sort) +``` +其余文件只做子串替换 `dsh-better-sidebar` → `dsh-apes-sidebar`;**camelCase 服务名 `betterSidebar` 必须保留**。 + +**③ 造一个"改名归一化基座",让增量与改名解耦** + +```bash +git checkout -B tmp/norm-<旧基线> <旧基线 tag> +# → 套同一口径改名 → commit +git diff tmp/norm-<旧基线> HEAD -- . ':(exclude)pnpm-lock.yaml' > /tmp/apes-delta.patch +# 校验:这条 diff 的文件清单必须恰好等于 ① 的「真改动 + 新增」 +``` + +**④ 在新基线上重建 + 三点合并** + +```bash +git checkout -B sync/<新基线 tag> <新基线 tag> +# → 套同一口径改名 → commit("rename only") +git apply -3 /tmp/apes-delta.patch # 冲突会以 <<<<<<< ours / >>>>>>> theirs 留存(命令本身不失败) +``` + +**⑤ 逐条判读冲突(只有五种形态)** + +| 形态 | 判定 | +| --- | --- | +| 版本/身份 JSON | 取**新基线**侧,再改成本 fork 的版本;两侧各自新增的元数据取**并集**(依赖、files 条目、`forkedFrom` 块) | +| 上游搬走了某个 import | 取上游的新路径,保留本 fork 的新 import | +| 上游新环境里的注册块 | 保留本 fork 的块,放进上游的新上下文 | +| 同一函数两边都定义(上游上移/下移了它) | 删除本 fork 那份;用 `grep -c 'const '` 断言只剩 1 处 | +| 长文档(README) | 整体取上游原文,再机械套上本 fork 的两处增量:顶部 fork notice + 包名替换(**跳过** `github.com/<上游 org>` 与徽章域名行) | + +**⑥ 迁移检查(API 漂移)+ 门禁** + +- 先**解完所有冲突标记再** `pnpm install`(`prepare: tsdown` 会因为语法错误直接失败), + 并**删掉 lockfile 重新生成**(不要把旧 lockfile 带过来)。 +- 逐条跑 `pnpm typecheck` 修类型漂移。经验:漂移通常集中在**本 fork 自己新增的模块**里。 + 上游会在 `context-types.ts` 的注释里写清迁移路径(例:0.1.6 的 `subagentsByParent` + → 0.1.7 的 `projectionsBySession[id].values.subagentCatalog`,`list.current` 被删除),照注释做即可。 +- 最后跑门禁三连,并且**用 `grep` 核对关键标记**(tab id、`srcDoc`、`dsh-desktop-content-viewport` 等)。 + +**⑦ 收尾(纪律)** + +- 安全锚点:`backup/pre-sync-<新基线>` 分支 + `apes-v<版本>` tag,**推送远端**。 +- **不要把新线同步进正在使用的 profile**:peer 范围可能已跨 minor,同步过去只会「静默失效」, + 同时把本机环境弄脏。保持 profile 在已验证的线上。 + +## 七、提交与分支纪律 + +- 提交信息用 `type(scope): 摘要`(`feat` / `fix` / `chore` / `docs` / `refactor`),正文说明**为什么**与验证方式。 +- 一个提交一件事;re-base 类改动拆成「rename only」+「增量移植」两个提交,便于回溯与回滚。 +- 分支命名:`sync/<上游 tag>`(跟随上游)、`backup/pre-sync-<基线>`(锚点)、其余按需。 +- 提交前:门禁三连 + 关键标记 grep + (若涉及部署)提醒 profile 重装与完整重启。