dsh-web/AGENTS.md

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. Before editing documentation, read 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 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 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).

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

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 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 for the contract.

Development Workflow

• For implementation and maintenance tasks, load dsh-web-agent-coding and the focused skill it selects.
• Agent Note rules 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，域归属见 CONTRIBUTING.md。

运行中的 DSH 服务

• 会话运行期间不得中断或重启当前正在运行的 DSH 服务（dsh web 及其宿主进程）：禁止 kill / pkill / SIGTERM，禁止抢占其端口另起替代实例。
• 改动需要服务重启才生效时（例如 bundle 行或 cordis.patch.yml 变化），不要自行 重启；改为在交付报告中明确标注「需要用户重启 DSH 服务后生效」，由用户自行 重启验证。页面刷新、只读探测等不打扰服务的验证不受此限制。

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 填写 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 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: implementation workflow and task-specific skill routing.
• packages/AGENTS.md: package-level SDK, bundle, and testing rules.
• docs/AGENTS.md: documentation structure, writing, and i18n rules.
• .agents/notes/: 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.