dsh-web/CONTRIBUTING.md

贡献指南（Contributing）

欢迎为 dsh-web（DSH Web GUI 插件与皮肤全家桶）贡献代码。本文件是贡献者的 入口；仓库的全部规则与机制以 AGENTS.md（及其分层指令）为准， 冲突时以 AGENTS.md 为准。

分支与合入流程

• dev 是开发分支（集成分支）：本地开发与远程 PR 统一以 dev 为 目标分支；dev 上测试通过后，由维护者合入 main。
• PR 打开后由 .github/workflows/auto-assign-pr-reviewers.yml 按 PR 描述中 勾选的「PR 类别」自动分派：把对应协作者设为负责人并请求其审查，未命中任何 类别时交给 defaultRoute 兜底；Wallpaper Engine / WebGL / 渲染器代码在 dsh-skins 仓，本仓只保留其 Issue 类别。路由规则见 PR_TRIAGE.md。
• 合并门禁：dev / main 要求 3 个必需检查全绿，不要求人工审批； 具有 write 权限的协作者检查通过后即可自行合并（含自己的 PR），无需等待 维护者审批。
• main 是稳定分支：只接收从 dev 合入且测试通过的代码。
• 提 PR 一律以 dev 为 base，不要以 main 为 base。

PR 范围：内容贡献全部在独立仓

本仓库对外部贡献者不再接受任何直接 PR。四类内容贡献都在各自的独立仓提交 （下表），其余改动请先提 Issue 讨论；插件功能、文档、测试、维护等范围内的 PR 同样 不接受直接提交。

• 插件申请（社区插件索引登记）：第三方插件由作者在自己的仓库按官方 cordis bundle 标准实现，然后向 dsh-community-plugins 仓提交索引登记——在该仓根目录的 community.json 追加条目，运行 pnpm community:check 校验后随该仓 PR 提交；
• 皮肤增加（新皮肤收录）：新皮肤作为纯资产提交到 dsh-skins 仓的 skins/<id>/， 收录到我们部署的 dsh-market.com 服务器（Workshop 商店）供用户按需安装—— 默认安装不带：skin-center npm 包只随附 blue-fantasy，新皮肤由用户经 Workshop 按需安装到 $DSH_HOME/skins/<id>/。低质皮肤 PR 不予接受（没有 背景图、仅简单改色且样式存在明显问题，如暗色缺失、对比度不足、布局 错位），请完善样式并附亮 / 暗试穿截图后再提交；
• 宠物增加（新宠物收录）：按宠物契约在 dsh-pet 仓的 assets/<id>/ 新增 （pet.json manifest + 图集，可选语音包 / 预览 / 装饰），随该仓 PR 提交。
• 预设增加（agent 预设收录）：按 dsh-presets 仓的 presets README 发布格式新增 presets/<id>/（preset.yml + agent.cordis.yml）并登记 catalog.json，收录到我们部署的 dsh-market.com 服务器（Workshop）供用户按需 安装——默认安装不带。预设是代码：composition 可挂载 npm 插件、加载预设 目录内文件、执行 !!js 表达式，启用后运行在 DSH 宿主进程内，评审重点审核 composition 实际加载内容与用途。

按上述类别向本仓提交的 PR 会被 .github/workflows/reject-non-content-pr.yml 关闭并重定向到对应独立仓；其余 范围外的 PR 同样被自动关闭（仅文档类 PR 由 reject-docs-pr.yml 处理）；仓库 所有者、机器人与拥有写权限的协作者（维护者）的 PR 不受此限制。

开发前置

• Node.js >= 22 与 pnpm 11；
• 插件只基于官方 NPM SDK（@deepseek-ai/*），禁止修改 DSH 源码、禁止 tsconfig 指向任何 DSH 源码 checkout；
• 认证：token 放用户级 ~/.npmrc，项目 .npmrc 只留 scope 映射（详见 docs/plugins.md）。

快速开始

git clone https://github.com/zhu1090093659/dsh-web.git
cd dsh-web
git checkout dev                                 # 开发基线：dev 分支
git fetch origin && git rebase origin/dev        # 提交 / 提 PR 前同步最新 dev
pnpm install
pnpm -r build
pnpm typecheck && pnpm test && pnpm docs:check   # 提交前必过

三个卫星仓（dsh-skins / dsh-pet / dsh-community-plugins）以 git submodule 挂在 satellites/，市场构建按各自的 gitlink 固定提交拉取内容。默认不需要检出：要就地改卫星仓内容时才 git submodule update --init satellites/<仓名>。该命令把工作树停在 gitlink 固定的提交上（detached HEAD），要提交改动先切到该仓的默认分支：git -C satellites/<仓名> checkout main。检出停在该固定提交时 pnpm market:fetch 直接复制该工作树；检出离开固定提交（切了分支，或提交了自己的改动）时，默认运行会明确提示并仍按固定提交构建，pnpm market:fetch --local 才读取该工作树——这样构建出的 market/dist 来自未固定内容，不得提交。

卫星仓的改动必须在卫星仓提交。 satellites/<仓名> 是独立的 git 仓库， 在本仓写下的文件改动不会被本仓的 git add 收走：只 git add 本仓会把它们的 工作树留在 dirty 状态（git status 显示 m satellites/<仓名>），下次检出/清理 就可能丢失。改完卫星仓（含随源码一起重新生成的 lib/）后：

1. 在卫星仓提交：git -C satellites/<仓名> add -A && git -C satellites/<仓名> commit；
2. 把该提交推到卫星仓的远程：git -C satellites/<仓名> push origin main；
3. 回到本仓把新的 gitlink 一起提交：git add satellites/<仓名> && git commit。

三步缺一不可——只提交卫星仓，本仓仍指向旧提交，其他检出与市场构建读到的还是改动前的 内容；只提交 gitlink 则根本不成立（卫星仓的提交才是被固定的对象）。漏掉第 2 步最隐蔽： 本地检出的工作树停在该提交上，pnpm market:fetch 直接复制它、构建照常成功，但拉取内容时 的 tarball 回退只按 SHA 寻址该提交，于是只存在于本地的提交让每一个全新克隆与 CI 的 pnpm market:fetch 得到 HTTP 404——移动钉扎的那一次运行成功，掩盖了后续所有运行的失败。 卫星仓内改动的验收与门禁在该仓自己的 CI 跑（见该仓 AGENTS.md）。

桌面宿主读到的是哪份卫星副本：全家桶聚合包按 semver 声明这四个卫星包 （^0.4.3），pnpm install 因此把聚合包 node_modules/@linxin666 下的符号链接指到 pnpm store 的已发布 tarball。桌面宿主解析聚合 patch 行贡献的外部行时从聚合包自身的 node_modules 出发——仅提交卫星仓并重启，GUI 加载的仍是发布版旧代码。在本地检出开发 卫星内容后重跑 node scripts/link-profile.mjs：它会把这些 store 链接改指到本地卫星 （仅当该卫星已构建 lib/ 且版本满足声明的范围），随后重启 DSH 生效。

提交规范

提交信息格式 type(scope): subject，type 用 feat / fix / chore / docs / test / refactor / perf，scope 是包名或主题，关联 issue 时 subject 末尾追加 (#123)。示例：fix(task-board,ssh): hide composer under active panel (#76 #87)。提交信息禁止 emoji（全仓规则）。

提 PR 前检查清单

1. 门禁全绿：pnpm typecheck / pnpm test / pnpm test:scripts / pnpm docs:check；涉及聚合包或市场时另跑 pnpm aggregate:check / pnpm market:check。
2. 文档同步：改包 README 必须同 PR 维护中英双语三件套（README.md + README.zh.md + README.i18n.yaml），改完任一侧后重录配对记录：

pnpm docs:write-pair <包目录名>   # 如 dsh-ssh 或 dsh-update

3. 无 emoji：代码、注释、文档、提交信息均不得出现 emoji（CI 有全树 检查）。
4. 一次性记录（任务交接、验证快照）放 docs/archive/，不进长期文档目录。
5. 按模板填 PR：摘要、涉及包、PR 类别（必填，决定自动分派给哪位 协作者）、类型、最新代码确认、AI 编码披露、仓库规范检查、本地验证结果；测试证据与上游同步必填：提供自己本地测试 的证据，并附上同步上游最新 dev 分支（git fetch origin && git rebase origin/dev）后重新测试通过的证据。文本类改动可不附截图； 视觉修复 / 用户可见变更必须附截图（视觉修复还需完成态或修复前后 对比截图），且视觉修复必须使用支持图像输入的多模态 AI 模型完成—— 使用纯文本模型（如 deepseek-chat / deepseek-reasoner / gpt-3.5）修复 的视觉类 PR 不予接受。缺少上述证据的 PR 不予接受。
6. AI 编码披露：使用 AI 编码时在 PR 模板中如实披露模型与工具。

四类内容贡献怎么做

插件申请（社区插件索引登记）

插件在贡献者自己的仓库实现（官方 cordis bundle 标准：dsh.bundle.patch 指向 cordis.patch.yml、dsh.client 浏览器半区、仅基于 @deepseek-ai/* NPM SDK，不修改 DSH 源码），然后向 dsh-community-plugins 仓提交索引登记：在该仓根目录的 community.json 追加条目，运行 pnpm community:check 校验后随该仓 PR 提交。

皮肤增加（新皮肤收录）

在 dsh-skins 仓用 node scripts/dsh-skin-new.cjs <id> 生成纯资产骨架（无 package.json）， node scripts/dsh-skin.cjs 校验后按皮肤契约完善（skin.json v2、 skin.css token 重映射，可选 patches.css / hooks.mjs / assets/），按该仓 README 生成 preview/{light,dark}.png，pnpm skin-center:check 通过后随 该仓 PR 提交。皮肤收录到我们部署的 dsh-market.com 服务器（Workshop）供 用户按需安装，默认安装不带（见上文 PR 范围）。

宠物增加（新宠物收录）

宠物已迁至独立仓 dsh-pet：按该仓 README 的宠物契约 在 assets/<id>/ 下新增（pet.json v2 + 8 列 × 9 行图集， 可选 previews/、voice.json 与状态装饰），在该仓补齐该 manifest 的归一化 测试与构建产物，同步维护该仓 README 中英三件套，运行该仓的 pnpm test 与 pnpm typecheck 后随该仓 PR 提交。

预设增加（agent 预设收录）

预设已迁至独立仓 dsh-presets： 按该仓 CONTRIBUTING 把 presets/_template/ 复制为 presets/<id>/（目录名即 预设 id，匹配 ^[a-z0-9][a-z0-9-]*$，官方内置 id 保留），编辑 preset.yml （展示文案，单行标量）与 agent.cordis.yml（composition，service 行置于带 isolate realm 的 group 内），在 catalog.json 登记条目（id / author / version 必填），运行该仓的 pnpm preset:check 与 pnpm test 后随该仓 PR 提交。市场 构建按 submodule 钉扎读取该仓的 presets/，因此预设在该仓合并后，还要由维护者 移动本仓 satellites/dsh-presets 的 gitlink 并重建 market/dist 才到达 dsh-market.com。预设启用后运行在 DSH 宿主进程内，PR 描述需说明 composition 挂载了什么、为什么。

范围边界

新增内置插件包 / 全新功能不属于内容贡献：仅接受 Issue，确认后由维护者 实现（node scripts/dsh-plugin-new <name> 等脚手架命令供维护者使用）。 内部新增 / 删除包或改皮肤清单时，同步更新 docs/publish-prep.md 的发布清单快照。

文档体系

仓库采用分层指令（渐进式上下文），写代码 / 写文档前按需阅读：

文件	内容	何时读
AGENTS.md	布局、命令、全局约定、开发与贡献流程	每个会话
packages/AGENTS.md	包级规则：SDK 约束、bundle 形态、测试纪律	改 packages/ 前
docs/AGENTS.md	文档标准：结构分层、写作规则、i18n 配对	写文档前
各包 AGENTS.md	该包特有规则（如 dsh-ssh 安全模型）	改对应包前
docs/architecture.md	架构总览与运行时全景	了解整体架构时
docs/plugins.md	新插件入桶规范与脚手架	新增或改造插件时
docs/development.md	日常开发与发布流程	需要细节时
docs/i18n.md	双语文档配对契约	改 README 时

发布

发布由维护者推送 vX.Y.Z tag 触发（.github/workflows/release.yml），tag 是 版本唯一来源；scripts/verify-version.mjs 校验每个包版本与 tag 一致。 贡献者无需关心发布，但新增包时必须保证包版本与仓库版本节奏一致。

Issue 与讨论

• Bug / 功能请求用 Issue 模板 提交， Bug 用「Bug 报告」表单（自动附加 bug 标签），需附截图、冒烟测试与引用代码；
• 社区交流见根 README 的「社区」小节；
• 提 Issue 前先按标签检索（bug / enhancement / question / good first issue / duplicate）并搜索关键词，确认没有重复再提交；
• 标签体系、分类标准与关闭流程见 ISSUE_TRIAGE.md；
• 已解决、重复或已回答的 Issue 会被维护者关闭并附说明，如需继续跟进请 在评论区说明或重开。