这里只放每次动手都要遵守的规则。细则、模板与历史记录在 docs/:
| 想找什么 | 去哪 |
|---|---|
| 发版步骤、版本号同步清单、Release note 模板 | docs/release.md |
| 开发规范细则(构建 / i18n / 皮肤 / 稳态 / 测试矩阵) | docs/development.md |
| DSH 基线、支持线、抬基线清单 | docs/dsh-version-adaptation.md |
| 宿主契约(原 §3.4 第 1–13 条,编号不变) | docs/host-contracts.md |
| 插件接入 API 全参考 | docs/external-plugin-guide.md |
| 设计史、历次适配与分诊记录 | docs/plans/ |
- 功能与修复先进
dev:feat|fix|chore|docs|test/*从dev切出、合回dev;回填贡献者 PR 沿用对方分支名。 - 不要用
dev/前缀命名分支:本地已有refs/heads/dev,dev/x会撞 ref(cannot lock ref)。 main只在发版时从dev合入,流程见 docs/release.md。- 纯文档改动(README / AGENTS.md / docs/ / CHANGELOG)允许不切分支,直接提交
main或dev。 - CI 的
push覆盖main与dev;pull_request不看 base,合进dev的每一批都有门禁。 - 并行开发用
.worktrees/(每槽独立node_modules);集成只在单一 worktree 串行做。
- 禁止修改 DSH 源码(官方 checkout
~/.dsh/source/current零写入)。缺能力时用宿主现成的只读 / 公开 API 或插件自有路由;做不到先说明取舍。 - 非文档改动必须走分支并合入
dev:外部贡献者走gh pr create+ review;维护者整合贡献者 PR 时优先把对方分支 rebase 到最新dev后git merge --ff-only(保留作者并让贡献提交进入 first-parent),只有无法 rebase / 必须保留合并关系时才用--no-ff,并在 merge message 与发布 note 中写明贡献者;每批都要跑门禁。 - 挂载只走
cordis.patch.yml+ profile 机制:插件作为独立包被 profile 引用,不反向侵入 DSH。 - 市场受管安装约束:
dependencies/peerDependencies/optionalDependencies不得出现cordis;scripts不得含preinstall/install/postinstall/prepare(tests/market-manifest.spec.ts 守护)。
| 改动 | 必跑 |
|---|---|
| 任何非文档改动 | typecheck + lint + test |
| 动构建产物 / 公开导出面 | 上面 + build + check:consumer-types |
| 动承载面(客户端渲染、tab、原生侧栏、编辑器、文件 / Git / 终端路由、事件通道) | 上面 + test:mount(真实宿主 + Chromium) |
| 动 win32 分支 / 安装脚本 | 上面 + test:windows |
| 改搜索引擎 | check:engines |
| 抬 DSH 基线 | docs/dsh-version-adaptation.md 的清单 |
- 本地挂载冒烟:
pnpm build && pnpm pack && pnpm test:mount。它钉住插件挂载无 pageerror、原生 guide 里宿主终端条目恰好 1 条、browser 条目缺席、文件树能打开 seed 文件并加载 editor chunk、页面内条目替换无native register … error。逐条机制与本地命令见 docs/development.md 的「挂载冒烟」。 - 环境:
NODE_OPTIONS=--max-old-space-size=4096;不要加--legacy-peer-deps;本机 registry 是 npmmirror,装不到新预发布时加--registry https://registry.npmjs.org。 - 已知 flake:tests/fs-watch.spec.ts 满载下偶发超时(#868),隔离跑通过即可,不要为它改代码。
一句话:dev 准备提交 → 门禁 → 合 main → 打 tag → GitHub Release 触发 npm 发布。完整步骤、版本号同步清单与 Release note 模板见 docs/release.md。
不可省的三件事:
- 版本号三处齐:package.json / dsh.plugin.json / SIDEBAR_SERVICE_VERSION(tests/service.spec.ts 锁步校验)。
- Release note 中英双语、面向用户:写现象 / 变更 / 影响面,不写内部发布细节;贡献者必须署名(
@handle+ PR 链接表)。 - 发布后验证:npm
dist-tags的 latest 指向新版本,版本端点与 tarball 可下载。
每条一句话;理由、示例与例外在 docs/development.md 对应小节。
- 构建纯度:client bundle 禁止 value-import
@dsh-external/*或非白名单@deepseek-ai/*(tsdown.config.ts 拦截);跨插件交互走ctx.betterSidebar。 - 懒加载 chunk:重依赖只在
lib/client-<name>.js,经/sidebar/bundle下发;核心 bundle 禁止静态 importsrc/client/chunks/*;CHUNK_NAMES的 5 处镜像要同步。 - i18n:新增 zh key 必须同步 locales-ja.ts 与其余词典(tests/locales.spec.ts 守护)。
- 保存语义:写盘前按磁盘现状还原编码与行尾;客户端只发送 LF。
- 皮肤:视觉值只用
--dsw-alias-*/--dsw-font-*/--ds-*,零硬编码颜色,插件没有任何豁免面。 - 图标:宿主
Icon*默认 16px,要 14px 显式传size={14};设置页导航图标走settings.section.icon插槽,不要用「标记行 + CSS 遮盖」。 - 稳态开销:轮询器 / socket / 观察者按可见性门控;每会话 / 每资源的东西单例化;模块级 Map 必须有上限与淘汰。
- 单一数据源:git 状态轮询只有 src/client/ui/git-status.ts 一条,不要自建第二个。
- 接入 API 即文档:src/client/service.ts 与 src/client/builtins/ 的行为变更必须同步 docs/external-plugin-guide.md。
- 不写运行时兼容层:抬基线就抬下限,旧宿主固定旧插件版本(见 docs/dsh-version-adaptation.md)。
- 测试契约写在每个 spec 的头注释里;子系统到 spec 的映射与跨平台三规则在 docs/development.md。
- Issue / PR 分诊:.agents/skills/issue-triage/SKILL.md(脚本在同目录)。
- 外部 PR 合入 / 贡献者署名:.agents/skills/external-pr-integration/SKILL.md。
- 用户可见变更:CHANGELOG.md(中文权威)+ CHANGELOG_EN.md。