Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Revert "fix(client): declare browser-only externals as devDependencies"

Browse Source
This commit is contained in:
imccyu
2026-08-15 02:19:09 +08:00
committed by GitHub
parent 6c18b04a6b
commit f2830fec6d
54 changed files with 293 additions and 1096 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
2026-07-30-generated-third-party-notices.md: 2128537b09f9d5d68cb1175b1ecb195fa50e1865
2026-07-30-generated-third-party-notices.zh.md: 906f5ed5b9a11f3ddd68491686b460c5d9f4a682
2026-07-30-generated-third-party-notices.md: 9ca24c9634b0410f9b7cc255902344cd6014bb90
2026-07-30-generated-third-party-notices.zh.md: b49e60565bbae62cf17026db17babc1ba7a408dc

4
.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
View File

@@ -26,8 +26,6 @@ The runtime tier deliberately covers **every mountable plugin**, not just what t
The manifest set is derived from the `packages:` members the root `pnpm-workspace.yaml` declares, including the Landlock workspace and its public packages, so a new member area is read the day it is declared rather than the day someone remembers to extend a list. License and repository metadata come from the root workspace's installed pnpm store and package-local link farms, so the generator requires an installed tree and fails loud when a package resolves to neither, rather than emitting an empty cell. `OVERRIDES` carries the packages whose published manifest cannot answer — Rust-built npm bins that omit `license`, and the `modelcontextprotocol/servers` packages whose repository is mid MIT→Apache-2.0 relicensing, so their effective terms are per-contribution. A runtime dependency whose license is not on the permissive list is a hard error: shipping copyleft is a distribution decision, not something a regenerated table may absorb silently. Vendored packages are cross-checked against `vendor/README.md` and rejected if any is not MIT, and `pnpm-workspace.yaml`'s `patchedDependencies` are listed under the runtime table because pnpm applies those patches at install time — shipped artifacts carry modified copies of `@earendil-works/pi-tui` and `node-pty`, and the patch files are the record of what changed.
**A package a published artifact carries is runtime whatever section declares it.** The browser side is built, not resolved: tsdown inlines every non-platform specifier into a plugin's `lib/client.js`, and Vite inlines the shell's imports into `@deepseek-ai/dsh-web-frontend`'s `dist`. Those packages are therefore declared as `devDependencies` — [the client build-time dependency note](../../proposed/process/2026-08-14-client-build-time-deps.md) owns that placement rule — while a copy of each is redistributed, so react, shiki, katex, and the markdown pipeline must stay in the runtime tier. [`scripts/browser-bundled-externals.ts`](../../../../scripts/browser-bundled-externals.ts) answers which ones those are from the build itself: it drives each client bundle through that package's own `tsdown.config.ts` and the shell through `apps/web`'s Vite config, with a recording plugin that resolves every bare specifier as external and notes it. The pass walks this repository's own source and stops at the package boundary, which costs about three seconds and yields exactly the direct-dependency granularity this file discloses. A specifier counts only once the host resolves it to a file inside a package, so a bundler's own virtual module is not mistaken for a shipped one: `vite/modulepreload-polyfill` is generated by a Vite plugin rather than published as a file, which makes the polyfill in the `dist` build glue of the same kind as an emitted TypeScript helper. Using the real configurations rather than a hand-kept list buys two properties no list has: an erased type import never appears, because the transform drops it before resolution, and a package stops being disclosed as shipped the moment its last browser import is gone. Workspace names are followed only on the Vite side, where the shell's aliases map them to source — that is how a browser-only library's own imports, `ui-primitives`' katex and shiki among them, become visible. A package that ships only type declarations is development-only however a shipped package names it: it contributes no redistributed code, and the dry run cannot see an erased type import anyway, because the transform drops it before resolution. `@types/mdast` and `micromark-util-types` moved to that tier for exactly this reason.
The project owner separately authorizes distribution of every official `@anthropic-ai/claude-agent-sdk` version and the official Claude Code CLI/platform payloads that version declares through `optionalDependencies`. The generator represents this as one exact direct-package identity exception, not as a permissive-license override: `SEE LICENSE IN README.md` and `SEE LICENSE IN LICENSE.md` remain non-permissive classifications, and every unrelated non-permissive runtime still fails closed. When the SDK is present, the generator reads its installed manifest, rejects optional identities outside the official SDK payload prefix, derives the current SDK, CLI, and payload versions, verifies the installed host payload's identity, version, and declared-license field, and renders the complete SDK-declared payload set in a separate notices section. Version, declared-license, and payload-set changes do not require new identity authorization, but they still require ordinary dependency, lockfile, compatibility, terms, and notices review.
## Testing
@@ -54,7 +52,7 @@ The Claude distribution tests prove that only the exact direct SDK identity bypa
## Consequences
A dependency edit now carries a regenerated notices file into the same commit. Contributors pay one generator run on commits that touch a manifest, and nothing on any other commit. It costs a few seconds rather than one, because learning what the browser artifacts carry drives the real client and shell bundlers; a broken client source therefore fails the hook, as the staged lint job already would. Committing with hooks disabled defers the cost to a test-lane failure that names the command.
A dependency edit now carries a regenerated notices file into the same commit. Contributors pay one generator run — about a second — on commits that touch a manifest, and nothing on any other commit. Committing with hooks disabled defers the cost to a test-lane failure that names the command.
The generator needs an installed tree, which makes it heavier than a pure-source generator, and a new package with unusable published metadata needs an `OVERRIDES` entry rather than silently rendering a blank license. Both failures are loud and name the remedy.

4
.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
View File

@@ -26,8 +26,6 @@ Status: implemented
manifest 集合由根 `pnpm-workspace.yaml` 声明的 `packages:` 成员派生，其中包括 Landlock 工作区及其公开包，因此新增成员区域在声明当天就会被读取，而不必等谁想起来去补一份列表。许可证与仓库地址取自根工作区已安装的 pnpm store 和包本地链接场；某个包两处都解析不到时直接失败，而不是留下空单元格。`OVERRIDES` 收录已发布 manifest 答不上来的包：用 Rust 构建、发布时省略 `license` 字段的 npm 可执行包，以及 `modelcontextprotocol/servers` 系列——该仓库正处在 MIT 向 Apache-2.0 的重新许可过程中，实际条款按贡献逐条而定。运行时依赖的许可证若不在宽松清单内即为硬失败：交付 copyleft 是一项分发决策，不该被一次重新生成悄悄吸收。被源码收编的包会与 `vendor/README.md` 交叉核对，出现非 MIT 即报错；`pnpm-workspace.yaml` 的 `patchedDependencies` 列入运行时表格，因为 pnpm 在安装期就会打上这些补丁——交付产物携带的是改动过的 `@earendil-works/pi-tui` 与 `node-pty`，补丁文件本身就是改动的完整记录。
**被已发布产物带上的包，无论由哪个区段声明都算 runtime。** 浏览器侧是构建出来的，不是解析出来的：tsdown 把每个非平台 specifier 内联进插件的 `lib/client.js`，Vite 把 shell 的 import 内联进 `@deepseek-ai/dsh-web-frontend` 的 `dist`。因此这些包声明在 `devDependencies`——落位规则归 [客户端构建期依赖那篇](../../proposed/process/2026-08-14-client-build-time-deps.md)——但它们各自都有一份副本被分发出去，所以 react、shiki、katex 与整条 markdown 管线必须留在 runtime 档。到底是哪些包，由 [`scripts/browser-bundled-externals.ts`](../../../../scripts/browser-bundled-externals.ts) 从构建本身取答案：它用各包自己的 `tsdown.config.ts` 驱动每个 client bundle，用 `apps/web` 的 Vite 配置驱动 shell，挂一个记录用插件把每个 bare specifier 解析成 external 并记下来。这一趟只走本仓自己的源码、到包边界即停，约三秒，且给出的正是本文件披露的「直接依赖」粒度。一个 specifier 只有在宿主把它解析到某个包内的文件之后才被计入，所以打包器自己的虚拟模块不会被误当成随产物分发的包：`vite/modulepreload-polyfill` 由 Vite 插件生成而非作为文件发布，因此 `dist` 里那段 polyfill 与 TypeScript 生成的辅助代码同类，属于构建胶水。用真配置而不是一张人工名单，白拿两个手写名单没有的性质：被擦除的类型 import 永远不会出现，因为 transform 在解析前就删了它；某个包最后一处浏览器 import 消失时，它也立刻不再被披露成随产物分发。workspace 名字只在 Vite 那侧继续走，因为 shell 的 alias 会把它们映射到源码——浏览器库包自己的 import，比如 `ui-primitives` 的 katex 与 shiki，正是这样才可见的。 只发布类型声明的包一律算 development-only，无论哪个已发布包具名了它：它不贡献任何被分发的代码，而 dry-run 本来也看不见被擦除的类型 import——transform 在解析前就删了它。`@types/mdast` 与 `micromark-util-types` 正是因此落到该档。
项目所有者另行授权分发每个官方 `@anthropic-ai/claude-agent-sdk` 版本，以及该版本通过 `optionalDependencies` 声明的官方 Claude Code CLI 与平台载荷。生成器将其表示为一项精确匹配直接包身份的例外，而非宽松许可证覆盖项：`SEE LICENSE IN README.md` 与 `SEE LICENSE IN LICENSE.md` 仍归类为非宽松，所有无关的非宽松运行时依赖仍以默认拒绝方式失败。存在该 SDK 时，生成器会读取其已安装 manifest，拒绝不符合官方 SDK 载荷前缀的可选包身份，推导当前 SDK、CLI 与载荷版本，核验已安装宿主载荷的身份、版本和声明许可证字段，并在单独的声明章节中渲染 SDK 声明的完整载荷集合。版本、声明许可证和载荷集合发生变化时无需新的身份授权，但仍须经过常规的依赖、锁文件、兼容性、条款和声明评审。
## 测试
@@ -54,7 +52,7 @@ Claude 分发测试证明：只有精确匹配的直接 SDK 身份会绕过通
## 后果
此后改动依赖时，重新生成的披露文件会随同一个提交入库。触及 manifest 的提交多付一次生成器运行；其余提交不受影响。这次运行从约一秒变成几秒，因为要弄清浏览器产物带了什么就得驱动真实的 client 与 shell 打包器；因此客户端源码坏掉会让这个 hook 失败，而暂存区的 lint job 本来也会失败。若禁用钩子提交，代价推迟为一次测试 lane 失败，其报错会指明补救命令。
此后改动依赖时，重新生成的披露文件会随同一个提交入库。触及 manifest 的提交多付一次生成器运行——约一秒；其余提交不受影响。若禁用钩子提交，代价推迟为一次测试 lane 失败，其报错会指明补救命令。
生成器需要已安装的依赖树，因此比纯源码生成器更重；发布元数据不可用的新包需要补一条 `OVERRIDES`，而不是默默渲染出空白许可证。这两类失败都会明确报错并指出补救方式。

6
.agents/notes/proposed/process/2026-08-14-client-build-time-deps.i18n.yaml
View File

@@ -1,6 +0,0 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/proposed/process/2026-08-14-client-build-time-deps.md
2026-08-14-client-build-time-deps.md: 0605225a70a16fed9004acfe26adba9b6166f201
2026-08-14-client-build-time-deps.zh.md: 5caed3422288711532c40cd767f72c97693e68b4

100
.agents/notes/proposed/process/2026-08-14-client-build-time-deps.md
View File

@@ -1,100 +0,0 @@
# Agent Note: Client build-time dependencies stay out of the install face
Status: proposed
English | [中文](2026-08-14-client-build-time-deps.zh.md)
## Problem
A browser artifact resolves nothing on the user's machine:
- A `ui-*` plugin package's browser artifact is `lib/client.js`, where tsdown inlines every non-platform specifier (`noExternal` in `packages/client/tsdown.client.ts`). The specifiers that survive are answered by the loader's frozen module table, because `require` inside that bundle is a parameter the loader injects, not Node's.
- Platform modules (`PLATFORM_MODULES`) come from the shell `dist`, never from Node resolution.
- The shell's own imports are inlined by Vite into `@deepseek-ai/dsh-web-frontend`'s published `dist`; that package ships `dist` alone and has no `.` export.
Every browser code path is therefore a build product, served as an asset or baked into `dist`. Yet the packages those artifacts are built from — react, react-dom, shiki, katex, clsx, the micromark and mdast families — sit in `dependencies` and non-optional `peerDependencies`, which npm installs for every consumer of the published package. Across the repository that is 79 such external declarations in 38 packages, downloaded by users who never load them.
## Proposal
### The rule
**An external package only a browser artifact reaches belongs in `devDependencies`.** Two deliberate omissions are as much part of the rule:
- **External packages only.** A `@deepseek-ai/*` name stays where its manifest puts it. Such a declaration also states which package supplies an injected service, which Remote contribution an assembly mounts, or which Loader row must resolve; [verify-runtime-closure](../../../../scripts/verify-runtime-closure.ts) and the Loader read it, and the app installs the package regardless — so moving one removes meaning without removing a download.
- **Anything the node half reaches stays**, an erased type import included.
Faces are walked from the entries a manifest publishes, not by a directory rule, so a module under `src/` that only the browser entry reaches counts as browser source:
| kind | test | host face entries |
| --- | --- | --- |
| `bundle-half` | has a `./client` export | every export target except `./client` |
| `browser-library` | under `packages/client/` with no `./client` export | `src/invariant.ts` alone — the companion the host mounts; `.` is browser code |
| `prebuilt-dist` | no `.` export, ships a `dist` | none: the package offers Node no entry |
### The gate: `scripts/verify-client-runtime-deps.ts`
Wired into `pnpm run hygiene`, about 35 seconds — the cost of two bound Programs, the same order as `verify-optional-dependency-imports` in that lane. It reuses the repository's tooling rather than growing its own: `TypeScriptProject` (`scripts/ts-project.ts`) binds the host and client compiler faces separately (that file states why the two cannot share one program — the cordis Context merges collide), `ts.resolveModuleName` resolves relative specifiers, and the walk stops at the package boundary.
Three findings decided the mechanism, after a first pass that scanned string literals:
1. A package name must match as a name: the `react` substring inside `'@deepseek-ai/dsh-client-web-react'` silently swallowed react.
2. Whether `./client` is the tsdown browser bundle is keyed on the **artifact path** (`./lib/client.js`), not the subpath name — `dsh-goal` publishes `./client` as `./lib/types/client.js`, a plain tsc-emitted browser-shared module.
3. `require`, `require.resolve`, and dynamic `import()` on a literal each reach a package; `require.resolve('@deepseek-ai/dsh-web-frontend/dist/index.html')` is a real host resolution path.
Two classes, both reported per entry:
| class | count | test |
| --- | --- | --- |
| `browser` | 74 | only a browser artifact reaches it |
| `nothing` | 5 | no reference names it: `client-runtime`'s `react` (which contradicts its own React-free layering red line), the peer `react` of `ui-settings` and `ui-theme`, `ui-trajectory`'s peer `react-dom`, and `ui-primitives`' `@types/mdast` |
Each conservative rule below answers a false report or a semantic loss observed while building it:
- **A type reference from the node half keeps its declaration.** `import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'` in `src/invariant.ts` is erased at run time, yet it states which package supplies the service that companion registers — `verify-runtime-closure`'s relation.
- **A package publishing a Node entry with no source counterpart is skipped whole, and named in the output.** `dsh-goal`'s `./typert -> ./lib/typert.host.js` is emitted by the typert generator and carries its own `import { z } from 'zod'`, which no source states. Getting this test right removed four false reports, among them `api-gateway`'s `typert-registry`.
- A `cordis*.yml` the package owns counts as host face: a Loader row names its plugin instead of importing it.
- `@deepseek-ai/cordis` is exempt — check-workspace-constraints requires it as both peer and dev everywhere.
`--json` output feeds the bulk edit and the install measurement.
### What leaves an install
Measured against a real `npm install` of the published CLI, with tarball bytes read from an isolated cache: 103 external tarballs stop being downloaded, 6.05 MB in total.
| group | packages | saved |
| --- | --- | --- |
| syntax highlighting and math (shiki family, oniguruma family, katex) | 16 | 3.93 MB |
| react and view libraries (react, react-dom, scheduler, immer, zustand, `@tanstack/*`, clsx, use-sync-external-store) | 11 | 1.47 MB |
| markdown and ansi pipeline plus odds and ends (micromark, mdast, hast families, anser, a few `@types/*`) | 76 | 0.65 MB |
Our own six browser-library packages (ui-primitives, ui-slots, web-react, ui-attachment, schema-form, client-web — 0.20 MB together) stay installed: code names them, and the rule above leaves those declarations alone.
### How it lands, split by nature
1. **Documentation first**: a declaration section in `packages/client/AGENTS.md`, and one clause in the new-plugin-package checklist.
2. **The gate**: `scripts/verify-client-runtime-deps.ts`, its `package.json` script, its place in `hygiene`, and a counterexample spec.
3. **The manifests**: 79 entries in 38 packages. 50 need a new `devDependencies` entry; the rest already carry one, so the change is a deleted line.
4. **Re-measure after the next release** with the same method, confirming the 103 tarballs stay gone.
## Alternatives considered
- **Scanning string literals**: the first implementation, rejected by the three findings above — the react-inside-web-react substring had already produced a silent miss.
- **Reading built artifacts (`lib/**/*.js`) instead of source**: that is Node's own view, but the gate would then depend on `pnpm run build`, and it still cannot judge a browser-library's `lib/index.js` (node platform, browser content), so the face test stays either way.
- **Asking the checker whether a binding is used in a value position** (what `verify-optional-dependency-imports` does): tried, and it also judged 83 node-face type-only declarations movable — no download saved for a real loss of meaning, 53 of them `dsh-invariants`. This gate needs to know whether a reference exists, not whether it is a value.
- **Also clearing our own six browser-library packages from the install face**, on the test that no install loads one: another 0.20 MB, at the price of deleting 74 workspace declarations that code genuinely names. Ruled out (2026-08-14): keep what the code names. The cleaner end state is to stop publishing those six packages, which is its own proposal.
- **`peerDependenciesMeta.optional` instead of `devDependencies`**: npm does skip an optional peer, but the meaning is "a consumer may supply this", and there is no run-time consumer at all. The repository must install it to build, which is what `devDependencies` says.
- **Leaving it to knip**: out of scope for knip, which reports a declared package nothing imports. These specifiers are imported; a bundler inlines them. The evidence is that they persisted on master with knip green. Only the five `nothing` entries overlap.
- **`optionalDependencies`**: wrong meaning — it says "skip this if it cannot be installed".
## Acceptance criteria
- `pnpm run hygiene` includes `verify-client-runtime-deps` and passes; a counterexample spec proves one `dependencies.react` is rejected.
- `pnpm run build`, `pnpm run test:gui`, and `DSH_SNAPSHOT=replay pnpm run test:web` pass — the move changes no build input, so artifacts stay byte-identical.
- A real install after the next release no longer downloads the 103 tarballs above.
## Risks
- **The six browser-library packages that stay installed carry bare imports nothing resolves**: `ui-primitives/lib/index.js` is a rolldown artifact and still reads `from "anser"`, while anser is now dev-only. It is inert — only our Vite build reads that file, and no loader exists for it on a user's machine (verified: only browser code imports those packages, never the host). Retiring their publication is the way to erase it; see Alternatives.
- **`@types/*` go unreported**: source never names them, so the rule cannot see them. `@types/mdast` was caught only because nothing referenced it either. They belong in dev regardless, and closing that gap is follow-up work.
- **A skipped package is unprotected**: `dsh-goal` is skipped whole for its generated entry, so its browser-side declarations are now nobody's business. Reading a generated artifact's own run-time imports is what would let the exemption be withdrawn.
- **A false report would delete a declaration something needs at run time**: three defenses hold that line — literal arguments to `require`, `require.resolve`, and dynamic `import()` count as references; a package's own `cordis*.yml` counts as host face; and no `@deepseek-ai/*` name is subject at all.

100
.agents/notes/proposed/process/2026-08-14-client-build-time-deps.zh.md
View File

@@ -1,100 +0,0 @@
# Agent Note: 客户端构建期依赖不进安装面
Status: proposed
[English](2026-08-14-client-build-time-deps.md) | 中文
## Problem
浏览器产物不在用户机上解析任何 specifier：
- `ui-*` 插件包的浏览器产物是 `lib/client.js`，tsdown 把每个非平台 specifier 直接内联（`packages/client/tsdown.client.ts` 的 `noExternal`）。留下来的 specifier 由 loader 的冻结模块表应答——那个 bundle 里的 `require` 是 loader 注入的形参，不是 Node 的。
- 平台模块（`PLATFORM_MODULES`）由 shell `dist` 提供，不走 Node 解析。
- shell 自身的 import 由 Vite 内联进 `@deepseek-ai/dsh-web-frontend` 已发布的 `dist`；该包只发 `dist`，连 `.` 导出都没有。
所以浏览器的每条代码路径都是构建产物，或作为静态资源下发，或烤进 `dist`。但这些产物的构建输入——react、react-dom、shiki、katex、clsx、micromark 与 mdast 全族——现在写在 `dependencies` 和非 optional `peerDependencies` 里，而 npm 对每个消费者都会安装这两个区段。全仓 38 个包共 79 处这样的外部依赖声明，装给了永远不会加载它们的用户。
## Proposal
### 规则
**只被浏览器产物触及的外部包落 `devDependencies`。** 两条留白同样是规则的一部分：
- **只管外部依赖**。`@deepseek-ai/*` 一律留在原处：那些声明还表达「谁提供我注入的服务」「这个 assembly 挂载了谁的 Remote」「哪个 Loader 行必须能解析」，[verify-runtime-closure](../../../../scripts/verify-runtime-closure.ts) 与 Loader 都读它，而 app 无论如何都会装那个包——移走只是删掉语义，并没有减少下载。
- **node 面触及的一律不动**，包括被擦除的类型引用。
face 从 manifest 真正发布的入口走图，不用目录规则，所以 `src/` 下只被浏览器入口触及的模块就算浏览器代码：
| kind | 判据 | host face 入口 |
| --- | --- | --- |
| `bundle-half` | 有 `./client` 导出 | 除 `./client` 外的每个导出目标 |
| `browser-library` | `packages/client/` 下且无 `./client` 导出 | 只有 `src/invariant.ts`——宿主唯一能挂载的伴生模块；`.` 面是浏览器代码 |
| `prebuilt-dist` | 无 `.` 导出、发布 `dist` | 没有：这个包不给 Node 提供任何入口 |
### 门禁：`scripts/verify-client-runtime-deps.ts`
接入 `pnpm run hygiene`，约 35 秒——两个绑定 Program 的开销，与同 lane 的 `verify-optional-dependency-imports` 同量级。复用仓内既有工具而不自造一套：`TypeScriptProject`（`scripts/ts-project.ts`）分别绑定 host 与 client 两个编译面（该文件写明两者不能合进一个 program——cordis Context merge 会撞），相对 specifier 交给 `ts.resolveModuleName` 解析，遍历到包边界即停。
判据要害有三条，都是起手那版扫字符串字面量踩出来的：
1. 包名必须按名匹配：`'@deepseek-ai/dsh-client-web-react'` 里的 `react` 子串会静默吞掉 react。
2. `./client` 是不是 tsdown 浏览器 bundle，看的是**产物路径**（`./lib/client.js`）而不是子路径名——`dsh-goal` 的 `./client` 是 `./lib/types/client.js`，一个 tsc 直出的浏览器共享模块。
3. `require`、`require.resolve`、动态 `import()` 的字面量实参都能触及一个包；`require.resolve('@deepseek-ai/dsh-web-frontend/dist/index.html')` 就是真实存在的宿主解析路径。
两类判定，逐条报告：
| 类 | 数量 | 判据 |
| --- | --- | --- |
| `browser` | 74 | 只有浏览器产物触及 |
| `nothing` | 5 | 没有任何引用具名它：`client-runtime` 的 `react`（与它自己「零 React 引用」的分层红线矛盾）、`ui-settings` 与 `ui-theme` 的 peer `react`、`ui-trajectory` 的 peer `react-dom`、`ui-primitives` 的 `@types/mdast` |
下面每条保守规则都对应一次实测到的误报或语义损失：
- **node 面的类型引用保留声明。** `src/invariant.ts` 里的 `import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'` 运行期被擦除，但它声明了谁提供这个伴生插件要注册的服务——归 `verify-runtime-closure` 管的关系。
- **发布了没有源码对应文件的 Node 入口的包整包跳过，并在输出里点名。** `dsh-goal` 的 `./typert -> ./lib/typert.host.js` 由 typert 生成器直出，自带 `import { z } from 'zod'`，没有任何源码陈述这件事。把这条判据修对，消掉了四处误报，其中包括 `api-gateway` 的 `typert-registry`。
- 包自带的 `cordis*.yml` 算 host face：Loader 行是具名它的插件而不是 import 它。
- `@deepseek-ai/cordis` 豁免——check-workspace-constraints 要求它在每个包里同时是 peer 和 dev。
`--json` 输出供批量改写与安装体积实测复用。
### 安装面少掉什么
对已发布 CLI 真装一遍实测，tarball 字节从独立 cache 读出：103 个外部 tarball 不再下载，合计 6.05 MB。
| 组 | 包数 | 省 |
| --- | --- | --- |
| 语法高亮与数学（shiki 族、oniguruma 族、katex） | 16 | 3.93 MB |
| react 与视图库（react、react-dom、scheduler、immer、zustand、`@tanstack/*`、clsx、use-sync-external-store） | 11 | 1.47 MB |
| markdown 与 ansi 管线及零碎（micromark、mdast、hast 全族、anser、若干 `@types/*`） | 76 | 0.65 MB |
我们自己的 6 个浏览器库包（ui-primitives、ui-slots、web-react、ui-attachment、schema-form、client-web，合计 0.20 MB）仍留在安装面：代码确实具名它们，上面的规则不动那些声明。
### 分刀落地
1. **文档住顶刀**：`packages/client/AGENTS.md` 的依赖声明节，加新插件包 checklist 里的一句。
2. **门禁**：`scripts/verify-client-runtime-deps.ts`、它的 `package.json` 脚本、它在 `hygiene` 里的位置，以及一条反例 spec。
3. **manifest**：38 个包 79 处。其中 50 处需要新增 `devDependencies` 条目，其余包已有同名条目，改动就是删掉一行。
4. **发版后按同一方法复测**，确认这 103 个 tarball 没有回来。
## Alternatives considered
- **扫字符串字面量**：起手就是这么实现的，被上面三条要害否掉——react-in-web-react 的子串已经造成过一次静默漏报。
- **读构建产物（`lib/**/*.js`）而不是源码**：那是 Node 自己的视角，但门禁从此依赖 `pnpm run build`，而且它照样判不了浏览器库包的 `lib/index.js`（platform 是 node、内容是浏览器代码），face 判据两种走法都得有。
- **用 checker 判绑定是否用在值位置**（`verify-optional-dependency-imports` 就是这么做的）：试过，它把 83 处 node 面纯类型声明也判成可移出——没省下任何下载，却实打实损失语义，其中 53 处是 `dsh-invariants`。本门禁要知道的是引用是否存在，而不是它是值还是类型。
- **顺带把我们自己的 6 个浏览器库包也清出安装面**，判据是任何安装都不加载它们：再省 0.20 MB，代价是删掉 74 处代码确实具名的 workspace 声明。已否（2026-08-14）：代码用到的就保留。更干净的终态是这 6 个包不再发布，那是另一个提案。
- **用 `peerDependenciesMeta.optional` 而不是 `devDependencies`**：npm 确实会跳过 optional peer，但那个语义是「消费者可以自行提供」，而这里根本没有运行期消费者。仓内必须装一份才能构建，这正是 `devDependencies` 的意思。
- **交给 knip**：不属于 knip 的范畴，它报的是「声明了但没人 import」。这些 specifier 确实被 import，只是被打包器内联了。实证就是它们在 master 上长期存在而 knip 全绿。只有 `nothing` 那 5 条与它重叠。
- **用 `optionalDependencies`**：语义错，它说的是「装不上就跳过」。
## Acceptance criteria
- `pnpm run hygiene` 包含 `verify-client-runtime-deps` 并通过；一条反例 spec 证明一处 `dependencies.react` 会被拒。
- `pnpm run build`、`pnpm run test:gui`、`DSH_SNAPSHOT=replay pnpm run test:web` 通过——这次迁移不改任何构建输入，产物应逐字节等价。
- 发版后真装一遍，上面那 103 个 tarball 不再被下载。
## Risks
- **留在安装面的 6 个浏览器库包会带着解析不了的 bare import**：`ui-primitives/lib/index.js` 是 rolldown 产物，仍写着 `from "anser"`，而 anser 已经只在 dev。它是惰性的——只有我们的 Vite 构建会读这个文件，用户机上没有任何加载者（已实证：只有浏览器代码 import 它们，宿主从不）。要彻底消掉就让这些包不再发布，见 Alternatives。
- **`@types/*` 报不出来**：源码从不具名它们，规则看不见。`@types/mdast` 被抓到只是因为恰好也没有任何引用。它们本来就该在 dev，补这个缺口是后续的事。
- **被跳过的包没人管**：`dsh-goal` 因生成入口整包跳过，它浏览器侧的声明现在没有门禁看着。能读到生成产物自身的运行期 import，这条豁免才能收回。
- **误报会删掉运行期真需要的声明**：三层兜底守住这条线——`require`、`require.resolve`、动态 `import()` 的字面量实参都算引用；包自带的 `cordis*.yml` 算 host face；`@deepseek-ai/*` 整体不在判据范围内。