8000 dsh-web/AGENTS.md at dev · inier/dsh-web · GitHub
[go: up one dir, main page]

Skip to content
< 8000 /react-partial>

Latest commit

 

History

History
96 lines (73 loc) · 10.5 KB

AGENTS.md

File metadata and controls

96 lines (73 loc) · 10.5 KB

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, the Skin Center, and the dsh-web-all aggregate package. 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 with one-click 7880 install into the DSH home directories). The Skin Center and the Pet plugin register their own first-level settings sections listing only installed items; 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 packages/skins/skin-center/skins/ as the market-build source and installs on demand into $DSH_HOME/skins/<id>/ from the Workshop.

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 docs:check
pnpm i18n:check   # zh/en/ru key parity + no CJK outside comments in client copy (scripts/i18n-audit.mjs)
pnpm aggregate:check
pnpm market:check
pnpm skin-center:check
pnpm deploy:market
node scripts/dsh-plugin-new <name>
node scripts/dsh-skin-new

Before merging, run at least pnpm typecheck && pnpm test && pnpm docs:check && pnpm i18n:check. Run the aggregate, market, and Skin Center checks when those areas change. 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.
  • Record every non-trivial change as an Agent Note under .agents/notes/ in the same change; lifecycle, classes, and format rules live there.
  • Follow the Software Factory governance baseline in .agents/notes/README.md:
    • Prompt Layering & Caching: Preserve prefix stability across Layer 1 (global rules/identity) and Layer 2 (repository AGENTS.md/skills); place dynamic context (memories, CodeGraph queries, file diffs) in Layer 3 at the prompt tail.
    • Pareto Model Tiering: Default to lightweight models (flash/flash_lite) for read-only research, file search, static checks, and documentation/i18n translation; reserve high-reasoning models (pro) for planning, multi-module refactoring, and root-cause analysis.
    • Anti-Thrashing Circuit Breaker: If 3 consecutive attempts on the same issue fail or edits oscillate, halt immediately and ask for clarification.
    • CI Self-Healing Protocol: Deterministic 4-step loop on failures: Log Isolation -> Local Minimal Repro -> Targeted Minimal Diff -> Pre-Push Gate Check.
  • Prefer CodeGraph for code navigation, symbol lookup, dependency analysis, review, and impact analysis (query, explore, node, impact, affected; codegraph init <project-root> when needed). After all code changes in a session, before final validation, run codegraph sync <project-root> and codegraph status <project-root>; if the index is missing or sync fails, run codegraph index <project-root>.
  • Keep changes focused, preserve existing work, and verify real behavior. User-visible changes require appropriate runtime evidence; visual changes require screenshots and multimodal validation.
  • Agent 的代码改动涉及 Wallpaper Engine / 渲染器域(如 packages/skins/skin-center/src/client/wallpaper.ts、packages/skins/skin-center/src/we-player-source.ts 及其测试 packages/skins/skin-center/tests/wallpaper.spec.ts / packages/skins/skin-center/tests/we-player.spec.ts)时,通知负责该域的协作者 Aa728848(EDDYCRAZY-CC);域归属见 CONTRIBUTING.md 与 .github/pr-review-routes.json。

运行中的 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-or-skin-directory>. Package or skin registry changes also update docs/publish-prep.md and regenerate packages/dsh-web-all/aggregate.yml with node scripts/aggregate.mjs.

Release

Releases are tag-driven by .github/workflows/release.yml. Verify every package version against the vX.Y.Z tag, generate release notes with scripts/release-notes.mjs, and pass all gates. The npm publish lane stays behind the workflow NPM_PUBLISH_ENABLED switch. Do not bypass the release process by editing package versions manually.

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.

0