Contributing Guide

August 18, 2026 · View on GitHub

欢迎为 @studyzy/dsh-web-remote-access 贡献代码、文档或 issue!在动手前请先阅读本指南与 README。

开发环境

要求:Node.js ≥ 18、pnpm(本仓库使用 pnpm 管理依赖)。

pnpm install      # 安装依赖
pnpm test         # 运行 vitest 测试套件
pnpm build        # tsc 编译到 lib/(ESM)

项目结构

src/
  index.ts        # 包入口,导出启动服务的类型与常量
  startup.ts      # fork @deepseek-ai/dsh-web-app/startup:--web_token / $DSH_WEB_TOKEN / 随机令牌
  webserver.ts    # fork @deepseek-ai/dsh-host-webserver:令牌门卫 + /api 回环呈现
  url.ts          # 打印带 ?web_token= 的 URL 行(本地 + LAN)
  polyfill.ts     # 向 index.html 注入 crypto.randomUUID polyfill
tests/            # vitest:fork 契约 + 门卫行为(真实 Loader 组合)
cordis.patch.yml  # dsh bundle patch 层:替换 web-app 行、挂载本包插件

分支与提交

  • 从 main 切出功能分支,命名如 feat/<description>、fix/<description>。
  • 提交信息遵循 Conventional Commits(feat:、fix:、docs:、refactor:、test:、chore: 等)。
  • 保持提交聚焦:一个逻辑变更一个提交。

代码约定

  • TypeScript,strict 模式(见 tsconfig.json);目标 ES2022、NodeNext 模块解析。
  • 新增/修改行为必须配套测试,并跑通 pnpm test。
  • 本包 fork 自上游(@deepseek-ai/dsh-web-app/startup、@deepseek-ai/dsh-host-webserver)。改动时保持上游契约(ctx.webServer 服务、webStartup 服务、路由/升级/fallback/索引 tap 语义)不变;如契约必须演进,需在 PR 说明理由。
  • 保持零运行时依赖的克制:能用 Node 内建/现有依赖解决的,不新增依赖。
  • 代码注释用英文;面向用户文档(README 等)用中文(本项目 README 为中文)。

测试

pnpm test                 # 全部测试
pnpm vitest run <file>    # 单文件,如 tests/webserver.spec.ts

测试覆盖两类:

  1. fork 契约:真实 Loader 组合下,webserver 的路由优先级、fallback 席位、索引 tap、升级路由、错误隔离与 teardown;
  2. 门卫行为:401 拒绝、?web_token= 授权 302 与 Cookie 下发、Cookie 放行、/api 回环呈现、manifest 豁免、升级路径 401。

提交 PR

  1. 确保 pnpm test 与 pnpm build 全部通过。
  2. 更新 CHANGELOG.md(若存在 [Unreleased] 一节则补入;发布时归档为版本章节)。
  3. 若变更了用户可见行为(CLI flag、环境变量、URL 格式、安全边界),同步更新 README。
  4. 描述 PR 动机、变更内容与测试方式。

Issue 与安全

  • Bug 报告:请附 dsh 版本、本包版本、复现步骤与日志。
  • 安全问题:请走 SECURITY.md 的私有报告渠道,不要在 issue 中公开。