# 仓库 Agent 约束 > 状态：Active > 适用范围：整个仓库 > 最后核验：2026-08-28 > 维护责任：修改仓库级约束的提交者本文件是维护者与 AI Agent 进入仓库的执行入口。使用者视角的安装/发布说明见 [README.md](./README.md)，两者不重复承载内容。 ## 优先级 ```latex 宿主兼容契约（UI slot / 投影字段，见 README「维护须知」） > 本文件硬规则 > README 维护说明（「新增插件」「多插件四条硬约束」详述） > 本地 Active spec（docs/specs/active/，进行中变更的 SDD 四件套；本地不随仓库分发，完成验收后回填并归档） > 本地设计记录（docs/specs/archive/ 与 docs/debug/，仅历史证据，不随仓库分发，不约束当前实现） ``` 工程方法层参考本地指南（`docs/project-engineering-guardrails-guide.zh-CN.md`，不随仓库分发）：spec 反空壳与状态门（§7.7–7.8）、完成后的生命周期迁移映射（§5.8）。指南是方法论，不参与上表优先级仲裁。同级约束冲突且无法按上表裁决时，**停顿询问维护者**，不得自动选择。 ## 按变更范围读取 | 变更 | 必读材料 | 最低验证 | | --- | --- | --- | | `lib/client.js` 任意改动 | 本文件硬规则 + README「维护须知」 | `npm test`（含 client 浅渲染断言）+ `node scripts/check-plugin-structure.js` + 重启 dsh web 目检 | | `lib/index.js`（host 半边，tokstats 聚合器） | 本文件硬规则 5 的 host 延伸（只用 `node:` 内建，npm 包 import 不可解析）+ 本地 SPEC-tokstats §3/§9 | `npm test`（host 管线断言）+ 重启 dsh web 目检四表 | | `test/`（测试套件） | 对应被测模块 + 现有用例 | `npm test` | | 新增插件 | README「新增插件」四步；模式参考本地 SPEC-tokprev §11；含 UI 文案的还需本文件硬规则 7（词典 ns + `locale` 声明） | 同上 | | `cordis.patch.yml` | 本文件硬规则 1 / 3 | `node scripts/check-plugin-structure.js` | | `package.json`（dsh 声明 / exports / files） | README「发布到 GitHub」 | link 安装后重启目检 | | SDD 文档（`docs/specs/active/`） | 本地指南 §5.4 / §7.7–7.8 + 该变更的 SPEC | 状态头字段完整 + 交叉链接可达 | | 纯文档 / 图片 | — | 链接可达性检查 | ## 硬规则 1. **patch 行 name 必须是裸包名 `'dsh-plugins'`**：client 半边按包名发现；写成子路径只剩 host 半边； 2. **client 模块图按包扁平**：所有插件实现在 `lib/client.js` 单文件内，禁止拆分文件或使用相对路径 `require`（factory 的 require 只认模块表词）； 3. **host 按行分 fiber，client 每包单 fiber**：patch 每行建一个 host fiber（`config.plugin` 是 host 侧分发键，`lib/index.js` 的 `apply(ctx, config)` 据此分发——纯 UI 插件 host 半边为空，tokstats 的聚合器宿主在自己的行 fiber 上）；client boot manifest 每包只建一个条目且不传 config，`lib/client.js` 的 apply 无条件注册 `PLUGINS` 全部插件。新增插件必须同时在 `PLUGINS` 注册表注册，由 guard 静态校验防漂移（v0.2.3 前的"客户端按 config 分发 + 未注册告警"模型已废弃）； 4. **每插件独立样式 tag**：经 `ensurePluginStyles` 注入 `data-plugin-css="dsh-plugins/"`，禁止包级共享 `