dsh-web-ui

# dsh-web Repository Instructions

This repository is a monorepo of DeepSeek Harness Web GUI plugins; skins ship as pure asset packs of the skins plugin, distributed through the Workshop. Each plugin is an independent Cordis bundle mounted through `cordis.patch.yml` and profiles. Never modify a DSH source checkout.

Before changing `packages/`, read [packages/AGENTS.md](packages/AGENTS.md). Before editing documentation, read [docs/AGENTS.md](docs/AGENTS.md).

## Repository Layout

`packages/` contains feature plugins and the `dsh-web-all` aggregate package. The Skin Center, the Pet plugin, the community plugin index and the preset center live in their own repositories (`dsh-skins`, `dsh-pet`, `dsh-community-plugins`, `dsh-presets`), are mounted here as published npm packages, and are the submodules under `satellites/`. The `dsh-market` package is the Workshop store: one settings entry (`settings.section` id `dsh-workshop`) rendering the store card (browsing dsh-market.com manifests for skins / pets / plugins / presets with one-click install into the DSH home directories; the card declares the `dsh-workshop.panel` child slot asset-kind panels register into). The Skin Center and the Pet plugin register their own first-level settings sections listing only installed items, and the preset center (the `dsh-presets` repository, which also carries the published `presets/` catalog the market build reads) owns community presets (the inert library `$DSH_HOME/agent-presets/<id>/`, enable/disable into `$DSH_HOME/.agent-presets/<id>/`, and the Presets panel in that slot); the community-plugins package is the community.json data source (the dsh-market.com plugin manifest and the store plugin list derive from it) and keeps an inert cordis row so existing profiles keep resolving. The skin-center npm package ships only the `skins/blue-fantasy` asset (files whitelist); every other skin stays in the dsh-skins repository as the market-build source and installs on demand into `$DSH_HOME/skins/<id>/` from the Workshop.

`satellites/` holds those four repositories as git submodules; the gitlink a branch records is the commit whose *content* the market build reads, and [market-inputs.lock.json](market-inputs.lock.json) maps each market input to the submodule carrying it and to the content directory inside it. Their content belongs to those repositories: commit and push there, then move the gitlink here. Only the gitlink lives in this repository — a clone that never initializes a submodule still builds the market from the pinned tarball, while `git submodule update --init satellites/<repo>` plus that repository's own `pnpm install` is the opt-in for working on that content in place ([CONTRIBUTING.md](CONTRIBUTING.md) owns that flow and the rule for builds from unpinned content), and `node scripts/link-profile.mjs` links the satellite packages into the DSH profile beside the in-repo family so a local DSH runs them from the working tree. They version and release from their own repositories ([docs/publish-prep.md](docs/publish-prep.md)).

`shared/tsdown.client.ts` is the only shared client build preset. `shared/web-platform.ts` defines the browser platform seed table. `shared/host/client/` contains the cross-package runtime source; package copies generated by `sync-shared.mjs` must not be edited manually.

`scripts/` contains repository maintenance tools, `docs/` contains long-lived documentation and archives, and `market/` contains the dsh-market.com site (`src/` hand-written sources, `shell/` the vendored browser-only WebDsh try-on shell whose git-ignored build is copied into `dist/tryon/`, `dist/` generated by `scripts/market-build` — including `tryon-assets/` with build-time transformed skin CSS — and `worker/` the Cloudflare Workers edge API with its D1 migrations and Turnstile-gated anonymous likes).

## Common Commands

```sh
pnpm install
pnpm build
pnpm dev:watch   # watch-rebuild browser bundles; the dsh web host reloads the GUI itself
pnpm test
pnpm typecheck
pnpm test:scripts
pnpm test:standards   # business test discipline: BDD structure, deterministic time, assertion quality
pnpm docs:check
pnpm i18n:check   # zh/en/ru key parity + no CJK outside comments in client copy (scripts/i18n-audit.mjs)
pnpm emoji:check   # no pictographs in hand-written sources (scripts/emoji-audit.mjs)
pnpm aggregate:check
pnpm market:fetch   # materialize the pinned skin / pet / community content into .market-inputs/
pnpm market:check
pnpm libs:check    # committed lib/ fingerprints vs the sources they were built from
pnpm coverage:check   # Tier-2 coverage ratchet; runs the whole suite under v8 coverage
pnpm deploy:market
node scripts/dsh-plugin-new <name>
node scripts/link-profile.mjs   # link the local family and the satellite packages into the DSH profile
```

Before merging, run at least `pnpm typecheck && pnpm test && pnpm test:standards && pnpm docs:check && pnpm i18n:check`. Run the aggregate and market checks when those areas change. [docs/development.md](docs/development.md) owns the test rules, their baseline, and the failure-path audit checklist; `.github/workflows/nightly.yml` is the Tier-2 lane that adds the coverage ratchet and three consecutive full-suite runs for flake detection. Two packages commit their build output under `lib/` (`dsh-market`, `dsh-web-all`); the satellite repositories carry the same rule for their own packages in their own CI. After changing any package's `src/` — including a child plugin's client sources, which the aggregate inlines — rebuild with `pnpm build`, record the new fingerprints with `pnpm libs:write`, and commit the refreshed `lib/` together with `scripts/lib-artifact-fingerprints.json`. `pnpm libs:check` is the gate. Market site changes must also commit the regenerated `market/dist` (never rebuild in CI; `market:check` verifies consistency, `deploy-market.yml` deploys the committed artifacts).

Market build order: build `market/shell` first (`npm run build` in `market/shell`; its dist is git-ignored), then `node scripts/market-build` to refresh `market/dist` (`tryon/` copies the shell build, `tryon-assets/` is derived with Skin Center `transformSkinCss`). In a clean checkout without the shell dist, `market-build --check` verifies the committed `tryon/` against its hash manifest instead of rebuilding. Deploy with `node scripts/deploy-market`.

## Repository Rules

- Mount plugins only through `cordis.patch.yml` and profiles. TypeScript configuration must not reference a DSH checkout; use official `@deepseek-ai/*` SDK packages from `node_modules`.
- New packages use the `dsh-` prefix and the `@linxin666/dsh-*` npm scope. Client UI packages use `@linxin666/dsh-client-ui-*` when applicable.
- Use `shared/tsdown.client.ts`; do not copy the build preset into a package.
- Keep `NPM_TOKEN` in the environment. Store token configuration in the user `~/.npmrc`; the project `.npmrc` should contain only scope mappings.
- Do not use emoji in code, comments, documentation, UI text, scripts, or commit messages.
- Market API trust: client-asserted headers (for example `x-dsh-market-client`) are not a trust boundary; anonymous likes must stay Turnstile-gated and written through one D1 batch.
- Keep each fact in its owning document. Update documentation when behavior changes, and put temporary handoffs or validation snapshots in `docs/archive/`.
- Plugin package READMEs require English, Chinese, and `README.i18n.yaml`; skin asset READMEs require English and Chinese. Follow [docs/AGENTS.md](docs/AGENTS.md) for the contract.

## Development Workflow

- For implementation and maintenance tasks, load [dsh-web-agent-coding](.agents/skills/dsh-web-agent-coding/SKILL.md) and the focused skill it selects.
- [Agent Note rules](.agents/notes/README.md) own decision-record requirements; the coding skill owns context use, delegation, failure recovery, navigation, and task-specific validation.
- Before modifying existing subsystems or architectures, search `.agents/notes/implemented/` for the Owning Note to review past constraints and rejected alternatives. Updating the note that already owns a decision satisfies the rule; create a new note only when no note owns it. Keep implemented notes current with shipped reality in the present tense (One home per fact).
- Agent 的代码改动涉及 Wallpaper Engine / 渲染器域时，通知负责该域的协作者 Aa728848（EDDYCRAZY-CC）；该域的代码（`src/client/wallpaper.ts`、`src/we-player-source.ts` 及其测试）已随皮肤中心迁至 [dsh-skins](https://github.com/zhu1090093659/dsh-skins)，域归属见 [CONTRIBUTING.md](CONTRIBUTING.md)。

## 运行中的 DSH 服务

- 会话运行期间不得中断或重启当前正在运行的 DSH 服务（`dsh web` 及其宿主进程）：禁止
  `kill` / `pkill` / `SIGTERM`，禁止抢占其端口另起替代实例。
- 改动需要服务重启才生效时（例如 bundle 行或 `cordis.patch.yml` 变化），不要自行
  重启；改为在交付报告中明确标注「需要用户重启 DSH 服务后生效」，由用户自行
  重启验证。页面刷新、只读探测等不打扰服务的验证不受此限制。
- 需要另起宿主来验证时（探针、QA 实例），让该实例使用自己的 `DSH_HOME`（约定
  `/tmp/dsh-verify-<topic>`），并在本会话内停掉它启动的每个进程：任务看板账本只允许
  一个写入者，残留实例会剥夺用户正在使用的看板。共享服务报告外来占用者时先归因
  pid 再终止，只处理本探测可归因的进程。隔离与回收的完整理由见
  [2026-10-02-shared-dsh-home-probe-isolation](.agents/notes/implemented/process/2026-10-02-shared-dsh-home-probe-isolation.md)。

## Branches, Commits, and PRs

- 本项目唯一的远程仓库是 `https://github.com/zhu1090093659/dsh-web`（`origin`）；`JAVA-LW/dsh-web-ui` 不是本项目的远程仓库，不要向其推送、创建 PR 或修改其仓库元数据（如 About 描述）。
- `origin` 的 url / pushurl 禁止改指向任何 fork 或第三方仓库（2026-08-31 事故：PR fork 流程遗留 `remote.origin.pushurl` 指向作者 fork，下一次 `git push origin dev` 会静默打到错误仓库）。向贡献者 fork 推送只用一次性命名 remote（`git remote add <name> <fork-url>`）或直接 URL；推送前 `git remote -v` 的 fetch/push 必须都指向规范仓库。首次在新检出开发时安装推送保护钩子：`ln -sf ../../scripts/git-pre-push-guard.sh .git/hooks/pre-push`。
- `dev` is the integration branch. Rebase on `origin/dev` before submitting a PR. `main` receives tested changes from `dev` through maintainer integration.
- 同步远程仓库代码时，本地与远程的同步对象只能是 `dev` 分支：`git fetch origin dev`，
  需要整合时把本地 `dev` rebase 或 merge 到 `origin/dev`。禁止把 `main` / `origin/main`
  作为本地 `dev` 的同步来源或重基目标——`main` 只通过维护者集成接收 `dev` 的
  测试内容，agent 不向 main 同步，也不以 main 重写本地 dev 的历史。
- Use Conventional Commits: `type(scope): subject`, with types such as `feat`, `fix`, `docs`, `test`, `refactor`, and `chore`. Do not include emoji.
- 改动默认直接提交到 `dev`（本地提交即可；需要时推送 `origin/dev`），**PR 不是强制流程**——只有需要评审或走合入流程时才开 PR。若开 PR：target 必须是 `dev`，并按 [.github/pull_request_template.md](.github/pull_request_template.md) 填写 scope、变更类型、上游同步、AI 披露、本地测试证据与用户可见证据。
- README changes update all paired files and run `pnpm docs:write-pair <package-directory>`. Package registry changes also update `docs/publish-prep.md` and regenerate `packages/dsh-web-all/aggregate.yml` with `node scripts/aggregate.mjs`.

## Release

Only an explicit current release request authorizes publication; CI/configuration repair, available credentials, and enabled workflows do not. Follow [dsh-web-release](.agents/skills/dsh-web-release/SKILL.md) for unified versions, dev-to-main release integration, tag-driven gates, npm switching, and bilingual release notes. Do not bypass that process with ad-hoc version edits.

## Instruction Layers

- This file: repository layout, commands, and cross-repository rules.
- [dsh-web-agent-coding](.agents/skills/dsh-web-agent-coding/SKILL.md): implementation workflow and task-specific skill routing.
- [packages/AGENTS.md](packages/AGENTS.md): package-level SDK, bundle, and testing rules.
- [docs/AGENTS.md](docs/AGENTS.md): documentation structure, writing, and i18n rules.
- [.agents/notes/](.agents/notes/README.md): Agent Note decision records — where proposals and shipped decisions are written down.
- Package-level `AGENTS.md` files: package-specific behavior and constraints.

Keep each rule in its owning file. Prefer short rules and links over duplicated explanations.

More agent context in zhu1090093659/dsh-web-ui

12 other files this repository gives its agents.

Also found in one other repository

The same file, byte for byte, in the weekly crawl of public GitHub.

• zhu1090093659/dsh-web8.5k