dsh-webui-studio 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CH4ACKO3
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PRODUCT.md

@@ -0,0 +1,74 @@
+# Product
+
+<!-- impeccable:product-schema 1 -->
+
+## Platform
+
+web
+
+## Users
+
+The primary users are developers who build, adapt, and debug DeepSeek Harness WebUI plugins and Harmony patches. They need to understand the live WebUI, work against the same plugin graph their users run, and turn changes into distributable plugin-owned patches instead of editing installed DSH sources.
+
+The wider product context also includes DSH users who install plugins and manage Harmony patch order. Studio does not replace their normal DSH workflow; it helps plugin developers produce changes that remain compatible with that workflow.
+
+## Product Purpose
+
+`dsh-webui-studio` is a local development environment for creating and modifying DSH WebUI plugins as isolated Draft layers. It combines an interactive real WebUI preview, DOM and React inspection, source editing, build and Harmony activation, readiness checks, and DSH-hosted Agent assistance without loading in-progress plugin code into the user's stable DSH Host.
+
+Success means a developer can start from a new package or an existing local plugin folder, test the Draft against a representative DSH profile, trace previewed UI back to relevant source, make a plugin-shaped change, and verify the activated result while the stable DSH environment remains usable.
+
+## Positioning
+
+Studio is not a generic page builder and does not treat the rendered WebUI as freely editable application source. It treats each change as a plugin or Harmony patch layered over an existing DSH WebUI whose components and data may come from multiple plugins.
+
+Its defining mechanism is a stable DSH control plane paired with one isolated Git worktree, child `DSH_HOME`, dependency tree, Harmony state, and child Preview Host per Draft. This lets multiple Drafts run concurrently and preserves the real DSH plugin and Patch semantics during development.
+
+## Operating Context
+
+Studio is served by a stable local `dsh web` Host at `/studio`. The stable Host owns the Studio interface, Draft registry, and Agent sessions. Each running Draft is previewed by a separate child `dsh web` Host inside Studio's main iframe, which can expand to fullscreen.
+
+Developers may create a minimal new Web Client plugin or import an existing local plugin folder as an isolated snapshot. A new plugin remains Studio-only by default; creation may record an optional absolute destination for a new or empty local folder, but Studio does not touch that folder until the user explicitly saves the project there. Later explicit saves synchronize the Studio snapshot without deleting destination-only files. Studio validates the Web Client manifest, excludes `.git` and `node_modules`, rejects symbolic links, and commits the copy into a Studio-owned Git repository without modifying the source folder. Draft repositories, worktrees, runtime homes, and registry records live under the stable Harness home's `studio` directory.
+
+The normal loop is to start a Draft Preview Host, interact with the WebUI in Browse mode, inspect an element when source context is needed, edit the selected Draft package directly or through the stable DSH Agent, run the package's build, apply the result through the child Harmony transaction, and confirm the live Client graph revision.
+
+## Capabilities and Constraints
+
+- Every Draft owns an isolated worktree, child Harness home, `profiles/web`, dependency installation, Harmony state, and Preview Host. Multiple Draft Preview Hosts may run at once.
+- The implemented profile mode snapshots the main `web` profile. Relative `link:` dependencies are made absolute and the Draft package is linked to its worktree. Custom profile configuration is intentionally unavailable until its editor exists; Studio must not silently fall back to the main profile.
+- Browse mode preserves normal WebUI interaction. Inspect mode captures a redacted DOM snapshot and provides best-effort React component, owner, and source mapping.
+- The Source panel edits UTF-8 files inside the selected Draft package. Builds use the package's fixed `scripts.build`; activation completes only after Preview confirms the new live Client graph revision.
+- Readiness inspection covers package identity, DSH exports, built and Patch artifacts, dependencies, Harmony state and order, target version bounds, and differential Source Patch providers. Package inspection uses `npm pack --dry-run --json --ignore-scripts` through the managed DSH subprocess runtime.
+- Agent sessions stay in the stable DSH and inherit its model and session configuration. Draft-specific Agent tooling may see the current selection, inspect Harmony, read installed dependency source without writing it, read and exactly patch Draft files, build and reload, and check Preview status. Preview-derived DOM, source, Patch, and comment data is untrusted evidence rather than Agent instruction. The child Preview Host does not own the Agent control plane.
+- The official WebUI continues to use its own-origin `/api` and WebSockets. Studio does not proxy WebUI traffic or introduce a second backend address.
+- Draft labels are persisted independently from npm package names. Studio stores ordered open Draft tabs and the active Draft in `$DSH_HOME/studio/workspace.json`; closing every tab remains an explicit empty workspace across Host restarts. Plugin Management can reopen any persisted Draft, and closing a tab never stops or deletes it. Unsaved Source changes block tab switching and closing until saved.
+- Stopping a Draft terminates its child Host but preserves its repository, worktree, profile, and registry record. Closing the Studio page does not delete Drafts.
+- A Draft package must be a buildable DSH Web Client package with `dsh.client.platform: "web"`, the required package exports, and a non-empty `scripts.build`.
+- Studio is a local development surface. Its Host extension is disabled when `dsh web` is not bound to `127.0.0.1`.
+
+## Brand Commitments
+
+The product name is `dsh-webui-studio`, displayed as DeepSeek WebUI Studio inside DSH. Its voice is native, precise, and calm: terminology should follow DSH and Harmony concepts instead of introducing a separate low-code vocabulary.
+
+Studio is a focused developer environment rather than a decorative mod manager. It should keep Draft state, isolation boundaries, build consequences, and Preview status legible without turning primary workflows into raw diagnostic output. Motion should be purposeful rather than flashy.
+
+## Evidence on Hand
+
+- The runnable Studio Host extension and browser application live under `src`.
+- The implemented architecture and development contract are documented in `README.md`.
+- Harmony runtime behavior and public terminology are documented in the repository root `README.md`.
+- React-aware patch factories available to Draft plugin authors are documented by the upstream `dsh-harmony-react` package.
+- Existing Harmony icon assets are available at `assets/harmony-icon.png` and `assets/harmony-icon-mono.png`; `assets/webui-banner-example.jpg` is a WebUI integration example, not product proof.
+- There are no confirmed customer testimonials, usage benchmarks, pricing claims, or deployment claims. Future product or marketing work must not fabricate them.
+
+## Product Principles
+
+- Preserve the stable DSH environment: unfinished Draft code belongs in isolated Preview Hosts.
+- Express changes as distributable plugin and Harmony artifacts, not arbitrary edits to installed WebUI sources.
+- Preview the real system: retain DSH origin, plugin graph, data, and interaction semantics during testing.
+- Make state transitions explicit: distinguish staged, built, preview-pending, active, stopped, and preserved Draft state.
+- Keep the development loop layered and direct: inspect, edit, build, activate, and verify without hiding the underlying files or Patch behavior.
+
+## Accessibility & Inclusion
+
+Follow the host WebUI accessibility baseline. Essential Studio actions need keyboard-accessible controls and visible focus; status and validation must not rely on color alone; reduced-motion preferences and the host theme's contrast-tested tokens must be respected.

package/README.md

@@ -0,0 +1,213 @@
+<div align="center">
+  <a href="https://github.com/CH4ACKO3/dsh-harmony">
+    <img width="132" alt="Harmony" src="assets/harmony-icon.png">
+  </a>
+
+  <h1>DeepSeek WebUI Studio</h1>
+
+  <p>
+    <strong>A visual-first studio for building DSH WebUI plugins.</strong>
+    <br />
+    Inspect the real interface, edit source, run builds, and validate patches without loading unfinished code into your stable DSH Host.
+    <br />
+    Powered by <a href="https://github.com/CH4ACKO3/dsh-harmony"><strong>dsh-harmony</strong></a>.
+  </p>
+
+  <p>
+    <a href="#getting-started"><strong>Get started</strong></a>
+    ·
+    <a href="https://github.com/CH4ACKO3/dsh-webui-studio/issues">Report a bug</a>
+    ·
+    <a href="https://github.com/CH4ACKO3/dsh-webui-studio/issues">Request a feature</a>
+  </p>
+
+  [![License: MIT](https://img.shields.io/badge/license-MIT-0b63f6.svg)](LICENSE)
+  [![CI](https://github.com/CH4ACKO3/dsh-webui-studio/actions/workflows/ci.yml/badge.svg)](https://github.com/CH4ACKO3/dsh-webui-studio/actions/workflows/ci.yml)
+  [![npm](https://img.shields.io/npm/v/dsh-webui-studio.svg?color=0b63f6)](https://www.npmjs.com/package/dsh-webui-studio)
+  [![Node.js](https://img.shields.io/badge/node-%5E22.22.3%20%7C%7C%20%3E%3D24.11.1-2f6f3e.svg)](package.json)
+  [![GitHub stars](https://img.shields.io/github/stars/CH4ACKO3/dsh-webui-studio?style=flat&color=0b63f6)](https://github.com/CH4ACKO3/dsh-webui-studio/stargazers)
+  [![Powered by Harmony](https://img.shields.io/badge/powered%20by-dsh--harmony-111827.svg)](https://github.com/CH4ACKO3/dsh-harmony)
+
+  [简体中文](README.zh-CN.md) / [English](README.md)
+</div>
+
+## A visual workspace for the real DSH WebUI
+
+WebUI Studio is not a mock page builder. It runs against the official DSH WebUI
+and its real plugin graph, then turns visual inspection and source edits into
+distributable plugin-owned artifacts.
+
+Studio is an independent downstream application of
+[`dsh-harmony`](https://github.com/CH4ACKO3/dsh-harmony). It uses Harmony's
+public Host extension, runtime, Patch engine, and Draft APIs together with the
+generic React registration API from
+[`dsh-harmony-react`](https://github.com/CH4ACKO3/dsh-harmony/tree/main/packages/react).
+The dependency direction stays one-way: Studio depends on Harmony; Harmony does
+not depend on Studio.
+
+## What you can do
+
+- [x] Create a minimal DSH Web Client plugin or import an existing local plugin folder
+- [x] Give every Draft its own Git worktree, `DSH_HOME`, profile, dependencies, and child Host
+- [x] Preview the official WebUI without loading Draft code into the stable Host
+- [x] Browse normally or inspect DOM, React owners, source candidates, and Patch traces
+- [x] Edit Draft source with CodeMirror and protect installed dependency sources as read-only
+- [x] Build, apply through Harmony, reload, and confirm the live Client graph revision
+- [x] Run Draft-scoped DSH Agents with explicit Studio tools
+- [x] Check package exports, artifacts, Patch state, ordering, dependencies, and pack output
+- [x] Run multiple isolated Draft Preview Hosts at the same time
+- [ ] Configure custom Draft profiles in the UI
+
+## How it works
+
+```mermaid
+flowchart LR
+  A["Stable DSH Host"] --> B["WebUI Studio"]
+  B --> C["Draft worktree"]
+  B --> D["Draft worktree"]
+  C --> E["Isolated DSH Home + Preview Host"]
+  D --> F["Isolated DSH Home + Preview Host"]
+  E --> G["Harmony runtime + real WebUI"]
+  F --> G
+```
+
+The stable Host owns the Studio interface, Draft registry, and Agent sessions.
+Each Draft owns an isolated worktree and child Preview Host. A build becomes
+active only after the Preview confirms the new live Client graph revision.
+Stopping a Draft terminates its child Host but preserves its files and state.
+
+Studio is served locally at:
+
+```text
+http://127.0.0.1:<dsh-port>/studio
+```
+
+Its managed data lives under `$DSH_HOME/studio/`:
+
+```text
+studio/
+├── workspace.json
+├── drafts/<draft-id>.json
+├── repositories/<draft-id>/
+├── worktrees/<draft-id>/
+└── runtimes/<draft-id>/dsh-home/profiles/web/
+```
+
+Creating a new plugin initializes and commits a minimal DSH Web Client package.
+New plugins stay inside Studio by default. Creation can optionally record an
+absolute destination for a new or empty local folder; Studio does not create
+or modify that folder until **Save plugin to folder** is used from the instance
+panel. Later saves synchronize the Studio-owned project snapshot while leaving
+destination-only files such as `node_modules` untouched.
+Importing an existing plugin accepts an absolute local folder after validating
+its Web Client manifest, then copies an isolated snapshot without `.git` or
+`node_modules` into a Studio-owned Git repository. Symbolic links are rejected,
+and the original folder is never modified.
+
+Draft display names are independent from npm package identities and can be
+renamed in the instance panel. Studio persists the ordered open tabs and active
+Draft in `workspace.json`; closing a tab only removes it from the current
+workspace and never stops or deletes the Draft. Plugin Management can reopen
+any persisted Draft. Unsaved Source changes must be saved with `Ctrl+S` or
+`Command+S` before switching or closing tabs.
+
+## Getting started
+
+> [!IMPORTANT]
+> Studio requires the public Harmony extension and Draft APIs documented in
+> [`docs/harmony-api-requirements.md`](docs/harmony-api-requirements.md).
+> `dsh-harmony@0.1.3` is the minimum compatible release.
+
+```sh
+dsh plugin --profile web add dsh-webui-studio --allow-build=dsh-harmony
+dsh web
+```
+
+Harmony is resolved transitively and does not need to be installed as a second
+plugin. The build permission allows its global-only DSH shim installer; normal
+profile installs do not modify the global command.
+
+To develop Studio itself from source:
+
+```sh
+git clone https://github.com/CH4ACKO3/dsh-webui-studio.git
+cd dsh-webui-studio
+npm install
+npm run check
+
+dsh plugin --profile web add link:$(pwd)
+dsh web
+```
+
+To exercise the same single-package installation path as a release artifact:
+
+```sh
+studio_tarball="$(npm pack --silent --ignore-scripts)"
+dsh plugin --profile web add "file:$(pwd)/${studio_tarball}" \
+  --allow-build=dsh-harmony
+```
+
+Open the Studio URL printed by the local `dsh web` process, create or import a
+Draft, and start its Preview Host.
+
+A Draft package must:
+
+- declare `dsh.client.platform: "web"`;
+- export `.`, `./client`, and `./package.json`;
+- define a non-empty `scripts.build` command.
+
+## Development
+
+| Command | Purpose |
+| --- | --- |
+| `npm run typecheck` | Check the Host, browser app, and Preview bridge |
+| `npm test` | Run the unit and component test suite |
+| `npm run build` | Build the Host, Studio UI, and Preview bridge |
+| `npm run check` | Run typecheck, tests, build, and packed fresh-install integration |
+| `npm run test:integration` | Pack and install the tarball in a fresh DSH home, then exercise Host, Draft, Preview, build, activation, and shutdown end to end |
+
+The integration test requires a Harmony build that exposes the APIs described
+in the compatibility note above.
+
+## Design boundaries
+
+- The official WebUI keeps its own-origin `/api` and WebSockets; Studio does not proxy them.
+- The Preview bridge requires the exact parent origin and a per-start capability.
+- Preview DOM, React, source, Patch, and comment data is treated as untrusted evidence.
+- Source writes stay inside the selected Draft package and never follow symbolic links outside it.
+- Registered element boundaries and Patch traces are candidate evidence, not claims of exact DOM ownership.
+
+## Frequently asked questions
+
+### How is Studio different from other WYSIWYG tools?
+
+DSH WebUI changes are delivered through plugins rather than direct edits to
+the upstream source. Its interface elements also participate in Cordis plugin
+lifecycle and control logic, so the problem extends beyond manipulating static
+DOM and CSS. Those constraints call for a dedicated toolkit that understands
+the DSH plugin system from preview through distribution.
+
+### Why not simply ask an Agent to edit the source?
+
+Studio still connects to the real Agent inside DSH. It gives that Agent richer
+project context, integrated previews, purpose-built tools and skills, and a
+tighter edit-build-inspect-validate loop. Studio does not replace the Agent; it
+turns source editing into a more capable interactive workflow for both the
+Agent and the developer.
+
+### What is Harmony, and why use it?
+
+The DSH WebUI exposes many useful slots, but Studio aims for deeper and more
+flexible changes—including UI and behavior introduced by other plugins—while
+keeping independently authored modifications as compatible as possible.
+[`dsh-harmony`](https://github.com/CH4ACKO3/dsh-harmony) provides the runtime
+patching and extension model that makes this possible.
+
+## Related projects
+
+- [`dsh-harmony`](https://github.com/CH4ACKO3/dsh-harmony) - runtime patching, Host extension mounting, Draft lifecycle, and Patch inspection
+- [`dsh-harmony-react`](https://github.com/CH4ACKO3/dsh-harmony/tree/main/packages/react) - React-aware Patch factories and Studio element/variable registration
+
+## License
+
+Distributed under the [MIT License](LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,196 @@
+<div align="center">
+  <a href="https://github.com/CH4ACKO3/dsh-harmony">
+    <img width="132" alt="Harmony" src="assets/harmony-icon.png">
+  </a>
+
+  <h1>DeepSeek WebUI Studio</h1>
+
+  <p>
+    <strong>DSH WebUI 插件的可视化优先开发环境。</strong>
+    <br />
+    实时预览你的插件对 dsh webui 的修改效果，在可视化的集成开发工具中交互式地与 agent 协作构建插件客户端。
+    <br />
+    Powered by <a href="https://github.com/CH4ACKO3/dsh-harmony"><strong>dsh-harmony</strong></a>.
+  </p>
+
+  <p>
+    <a href="#快速开始"><strong>快速开始</strong></a>
+    ·
+    <a href="https://github.com/CH4ACKO3/dsh-webui-studio/issues">报告问题</a>
+    ·
+    <a href="https://github.com/CH4ACKO3/dsh-webui-studio/issues">功能建议</a>
+  </p>
+
+  [![License: MIT](https://img.shields.io/badge/license-MIT-0b63f6.svg)](LICENSE)
+  [![CI](https://github.com/CH4ACKO3/dsh-webui-studio/actions/workflows/ci.yml/badge.svg)](https://github.com/CH4ACKO3/dsh-webui-studio/actions/workflows/ci.yml)
+  [![npm](https://img.shields.io/npm/v/dsh-webui-studio.svg?color=0b63f6)](https://www.npmjs.com/package/dsh-webui-studio)
+  [![Node.js](https://img.shields.io/badge/node-%5E22.22.3%20%7C%7C%20%3E%3D24.11.1-2f6f3e.svg)](package.json)
+  [![GitHub stars](https://img.shields.io/github/stars/CH4ACKO3/dsh-webui-studio?style=flat&color=0b63f6)](https://github.com/CH4ACKO3/dsh-webui-studio/stargazers)
+  [![Powered by Harmony](https://img.shields.io/badge/powered%20by-dsh--harmony-111827.svg)](https://github.com/CH4ACKO3/dsh-harmony)
+
+  [简体中文](README.zh-CN.md) / [English](README.md)
+</div>
+
+## 面向真实 DSH WebUI 的可视化工作区
+
+WebUI Studio 不是模拟页面生成器。它运行在官方 DSH WebUI 和真实插件图谱之上，
+把可视化检查与源码修改转化为可分发、由插件自身拥有的产物。
+
+Studio 是 [`dsh-harmony`](https://github.com/CH4ACKO3/dsh-harmony)
+的独立下游应用。它通过公共 package exports 使用 Harmony 的 Host extension、runtime、
+Patch engine 与 Draft API，并使用
+[`dsh-harmony-react`](https://github.com/CH4ACKO3/dsh-harmony/tree/main/packages/react)
+提供的通用 React 注册 API。依赖始终保持单向：Studio 依赖 Harmony，Harmony 不依赖 Studio。
+
+## 你可以做什么
+
+- [x] 创建最小 DSH Web Client 插件，或导入已有的本地插件文件夹
+- [x] 为每个 Draft 分配独立 Git worktree、`DSH_HOME`、profile、依赖树和 child Host
+- [x] 预览官方 WebUI，同时不把 Draft 代码加载进稳定 Host
+- [x] 正常浏览，或检查 DOM、React owner、源码候选和 Patch trace
+- [x] 使用 CodeMirror 编辑 Draft 源码，并保持已安装依赖源码只读
+- [x] 构建、经 Harmony 应用、重载，并确认实时 Client graph revision
+- [x] 运行带显式 Studio tools 的 Draft 级 DSH Agent
+- [x] 检查 package exports、构建产物、Patch 状态、顺序、依赖和 pack 输出
+- [x] 同时运行多个相互隔离的 Draft Preview Host
+- [ ] 在 UI 中配置自定义 Draft profile
+
+## 工作原理
+
+```mermaid
+flowchart LR
+  A["稳定 DSH Host"] --> B["WebUI Studio"]
+  B --> C["Draft worktree"]
+  B --> D["Draft worktree"]
+  C --> E["独立 DSH Home + Preview Host"]
+  D --> F["独立 DSH Home + Preview Host"]
+  E --> G["Harmony runtime + 真实 WebUI"]
+  F --> G
+```
+
+稳定 Host 负责 Studio 界面、Draft registry 和 Agent session。每个 Draft 拥有隔离的
+worktree 与 child Preview Host。只有在 Preview 确认新的实时 Client graph revision 后，
+构建结果才会激活。停止 Draft 只终止 child Host，不会删除文件和状态。
+
+Studio 的本地地址为：
+
+```text
+http://127.0.0.1:<dsh-port>/studio
+```
+
+托管数据位于 `$DSH_HOME/studio/`：
+
+```text
+studio/
+├── workspace.json
+├── drafts/<draft-id>.json
+├── repositories/<draft-id>/
+├── worktrees/<draft-id>/
+└── runtimes/<draft-id>/dsh-home/profiles/web/
+```
+
+创建新插件时，Studio 会初始化并提交一个最小 DSH Web Client package，并默认只将它
+保存在 Studio 内。创建时也可以记录一个新建或空白本地文件夹的绝对路径；在实例面板
+显式点击“保存插件到文件夹”前，Studio 不会创建或修改该目录。后续保存会同步 Studio
+中的项目快照，同时保留目标目录独有的 `node_modules` 等文件。导入已有插件时，
+Studio 只接受本机绝对文件夹路径；验证 Web Client manifest 后，它会跳过 `.git` 与
+`node_modules`，将快照复制到 Studio 自有 Git repository。符号链接会被拒绝，原插件
+文件夹始终保持只读且不会被修改。
+
+Draft 显示名与 npm package identity 相互独立，可在实例面板中重命名。Studio 会在
+`workspace.json` 中保存标签顺序与当前 Draft；关闭标签只会将其移出当前工作区，不会
+停止或删除 Draft。所有持久化 Draft 都可以从插件管理页重新打开。Source 存在未保存
+修改时，必须先按 `Ctrl+S` 或 `Command+S` 保存，才能切换或关闭标签。
+
+## 快速开始
+
+> [!IMPORTANT]
+> Studio 依赖 [`docs/harmony-api-requirements.md`](docs/harmony-api-requirements.md)
+> 中列出的 Harmony 公共 extension 与 Draft API，最低兼容版本为
+> `dsh-harmony@0.1.3`。
+
+```sh
+dsh plugin --profile web add dsh-webui-studio --allow-build=dsh-harmony
+dsh web
+```
+
+Harmony 会作为传递依赖自动解析，无需作为第二个插件单独安装。该构建权限用于允许其
+仅在全局安装时生效的 DSH shim 安装器；普通 profile 安装不会修改全局命令。
+
+如需开发 Studio 本身：
+
+```sh
+git clone https://github.com/CH4ACKO3/dsh-webui-studio.git
+cd dsh-webui-studio
+npm install
+npm run check
+
+dsh plugin --profile web add link:$(pwd)
+dsh web
+```
+
+如需用发布产物验证相同的单包安装流程：
+
+```sh
+studio_tarball="$(npm pack --silent --ignore-scripts)"
+dsh plugin --profile web add "file:$(pwd)/${studio_tarball}" \
+  --allow-build=dsh-harmony
+```
+
+打开本地 `dsh web` 进程输出的 Studio 地址，创建或导入 Draft，然后启动它的 Preview Host。
+
+Draft package 必须：
+
+- 声明 `dsh.client.platform: "web"`；
+- 导出 `.`, `./client` 和 `./package.json`；
+- 定义非空的 `scripts.build` 命令。
+
+## 开发命令
+
+| 命令 | 用途 |
+| --- | --- |
+| `npm run typecheck` | 检查 Host、浏览器应用和 Preview bridge |
+| `npm test` | 运行单元测试与组件测试 |
+| `npm run build` | 构建 Host、Studio UI 和 Preview bridge |
+| `npm run check` | 运行 typecheck、测试、构建和 tarball 全新安装集成验证 |
+| `npm run test:integration` | 将 tarball 安装到全新的 DSH home，再端到端验证 Host、Draft、Preview、构建、激活与停止 |
+
+集成测试需要 Harmony build 已公开兼容性说明中列出的 API。
+
+## 设计边界
+
+- 官方 WebUI 保持自己的同源 `/api` 与 WebSocket；Studio 不代理它们。
+- Preview bridge 要求精确的 parent origin 和每次启动生成的 capability。
+- 来自 Preview 的 DOM、React、源码、Patch 与注释数据均被视为不可信证据。
+- 源码写入始终限制在所选 Draft package 内，且不会沿符号链接写到外部。
+- 已注册 element boundary 与 Patch trace 只是候选证据，不代表对 DOM 的精确所有权声明。
+
+## 常见问题
+
+### Studio 与其他 WYSIWYG 工具有何不同？
+
+DSH WebUI 的修改不能直接改动上游源码，而要以插件形式交付。界面元素还会参与
+Cordis 的插件生命周期与控制逻辑，因此问题不只是操作静态 DOM 和 CSS。预览、修改、
+验证与分发都需要理解 DSH 插件体系，这足以构成一套独立的专用工具。
+
+### 为什么不直接让 Agent 对着源码修改？
+
+Studio 仍然连接 DSH 内部真实的 Agent，同时为它提供更完整的项目上下文、集成预览、
+专用 Agent 工具与 Skill，以及更紧密的编辑、构建、检查和验证闭环。Studio 不是取代
+Agent，而是为 Agent 和开发者提供更好的交互式修改体验。
+
+### Harmony 是什么，为什么选择 Harmony？
+
+DSH WebUI 已经提供了许多 Slot 点位，但 Studio 不满足于此。我们希望实现更深层、
+更高自由度的修改，包括修改其他插件加入的 UI 和逻辑，同时让不同修改插件之间尽可能
+兼容。[`dsh-harmony`](https://github.com/CH4ACKO3/dsh-harmony) 提供的运行时 Patch 与
+扩展模型，让这种能力成为可能。
+
+## 相关项目
+
+- [`dsh-harmony`](https://github.com/CH4ACKO3/dsh-harmony) - runtime patch、Host extension 挂载、Draft 生命周期与 Patch 检查
+- [`dsh-harmony-react`](https://github.com/CH4ACKO3/dsh-harmony/tree/main/packages/react) - React-aware Patch 工厂与 Studio element/variable 注册
+
+## 许可证
+
+本项目采用 [MIT License](LICENSE)。