一句话定位

让 DSH 模拟目标用户画像在开发阶段走查前端界面，发现体验问题并给出可一键复制给编码 AI 的任务 Prompt；改前端代码会触发自动复检。

核心能力

• 用自然语言发起走查：直接说「看看下单流程好不好用」，无需斜杠命令；项目里没画像时会从 README 自动推断 1–3 个用户作为走查依据
• 自动注入用户画像上下文：每次请求按当前项目自动注入生效的画像与走查协议，多项目并存时各会话注入各自的画像
• 27 条规则的多视角走查：基于 Nielsen 启发式的 27 条规则，模型主判、AST/CSS 辅证；每条结论都会打上 static / rendered / interactive 证据等级
• 改前端代码即自动复检：编辑前端文件后，回合收尾时自动对所属完整组件/页面跑一次走查，不打断人、不打扰画像；只有一级/二级问题才提示一句
• 报告卡片双面呈现：首屏只展示哪个页面、出了什么事、严不严重；文件路径、规则 ID、验证路径折叠在「技术细节」里，展开后可一键复制为结构化 YAML 喂给编码 AI
• 无 ID 化的确认闭环：点确认/不是问题按钮，或直接说「第 2 条不成立」「三级以下全部忽略」，无需记任何编号；结果写入会话日志，重放可完整恢复

技术实现

• 语言: TypeScript
• 关键依赖: @deepseek-ai/cordis、@deepseek-ai/dsh-tools、@deepseek-ai/dsh-client-runtime(client)、@vue/compiler-sfc + @vue/compiler-dom(Vue 走查)、typescript(源码 AST 求证)
• 架构模式: cordis 双面插件：Host 侧挂载命令、提示词注入、4 个模型工具、改动触发的自动走查；Client 侧通过 dsh.client 声明被 Web 模块表发现，注册 UI 报告卡片与确认闭环。Redline：所有能力挂在文档化扩展点（commands / systemPrompt.section / tools.register / SessionEventMap / tools/result / agent/turn-stopping），不修改 agent 主循环
• 入口文件: src/index.ts(Host 插件) / src/client/index.ts(Client 插件) / cordis.patch.yml(bundle 装载)

适用场景

前端研发在写代码阶段想提前发现体验问题，而不是上线后看用户反馈。适用于 React（TypeScript / JavaScript）与 Vue 3 项目，特别是需要在多次提交之间持续验证 UI 改动的团队；不适合 Svelte、Vue 2、小程序等当前未覆盖的栈。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:DietCokewithSugar/dsh-user-experience

配置项

本插件所有可调项都进了 Schema，可通过 profile 的 cordis.patch.yml --patch 层按 id ux-experience 覆盖，也可写到 .ux/rules.local.yml（个人偏好，优先级更高）。

常见问题

Q: 安装后需要做什么初始化？

A: 不需要任何初始化。直接用自然语言告诉 DSH「看看下单流程好不好用」即可；项目里没有用户画像时，会自动从 README 推断 1-3 个草稿作为走查依据。

Q: 应该用 npm 还是 github 方式安装？

A: 用包名安装（不要加 github: 前缀）。仓库不再提交 lib/ 构建产物，Git 检出目录缺少预编译文件，pnpm 默认会拦截构建步骤导致 github: 安装失败。

Q: 改完前端代码后会自动跑走查吗？

A: 默认会。改前端文件后回合收尾时会自动对所属完整组件/页面跑一次走查，并安静出报告；只有一级、二级问题才会提示一句。用户可通过 .ux/rules.local.yml 的 autoScan.enabled: false 关闭。

Q: 不支持哪些前端技术栈？

A: 不支持 Svelte、Vue 2 和小程序。其余 Vue 2 项目也会在被检出时明确告知；当前仅支持 React（TypeScript / JavaScript）和 Vue 3。

Q: 走查结果为什么会"出现在技术细节里、不显示文件路径"？

A: 报告卡片有两个读者：给人看的部分只说哪个页面、出了什么事、严不严重；给 AI 用的精确位置、规则 ID、验证路径折叠在「技术细节」里，展开后一键复制为结构化 YAML 喂给编码 AI。

Q: 如何卸载本插件？

A: 在 profile 的 package.json 中删除对应依赖行，并清理 node_modules 与 pnpm-lock.yaml 后重新安装覆盖。重启或刷新页面即可。

上手难度

入门 — 不需要学斜杠命令，直接用自然语言驱动；需要在硬规则上自定义（运行模式、排除目录、自动走查开关）时改项目根目录的 .ux/rules.local.yml 即可。

已知问题与限制

• 仅支持 React（TypeScript / JavaScript）与 Vue 3；Svelte、Vue 2、小程序（.wxml）均明确不支持，检出时直接告知（如 Svelte 给出"扩展规划中"，Vue 2 给出"SFC 语法与 @vue/compiler-sfc 不兼容"），不会做低质量猜测
• 浏览器证据（rendered / interactive）是可选能力：当前 Harness 会话没有浏览器/截图工具时，规则中需要真实截图的结论会跳过、不会谎称看过页面
• 改动触发的自动走查只针对前端文件（.tsx/.jsx/.vue/.ts/.js/.css/.scss/.sass/.less/.pcss），纯后端变更、测试文件、.d.ts 声明文件默认不进入
• 单次自动走查最多纳入 20 个改动文件，避免范围失控；可通过 autoScanMaxFiles 调整
• 仓库不再提交 lib/ 构建产物，因此 dsh plugin ... add github:... 形式的安装已失效；必须用包名方式安装

English · 简体中文

dsh-user-experience

A UX walkthrough plugin for DeepSeek Harness (DSH): AI simulates target users to uncover UX problems during development—before they reach production—and provides concrete optimization suggestions.

Scope: React + TypeScript / React + JavaScript / Vue 3, CSS/layout analysis, and optional browser evidence when the current Harness session can open the application.

🎉 Listed in awesome-dsh-plugin.

Existing automated checks (axe, Lighthouse) can only verify absolute rules — contrast ratio, missing alt text. But UX issues are inherently relative: a confirmation dialog before deleting protects an occasional user but wastes the time of an operator who processes hundreds of records a day. Without knowing who it's for, a "UX issue" cannot be defined.

This plugin makes target user personas the basis of every finding. If the project has no personas yet, the plugin infers a short draft from the README and routes—there is no setup command. By having AI walk through the product as those users, it surfaces experience problems during development and gives concrete, locatable, reviewable optimization suggestions—not post-launch user feedback.

It is a pipeline, not a CLI. Speak in plain language, or just edit a front-end file. There is no /ux command to learn. The report card leads with plain language (which page, what happened, how bad), and folds file paths and rule IDs into a "technical details" block you can copy straight to an AI in one click. Verdicts need no IDs either: click a button, or just say "the second one isn't a problem" or "ignore everything below level three".

Install in Harness

In DeepSeek Harness, enter:

Install the UX plugin in DeepSeek Harness: dsh plugin --profile web add [email protected]

Or run the command directly:

dsh plugin --profile web add [email protected]

Name an exact version rather than @latest: pnpm 11 holds back releases published in the last 24 hours, so @latest can resolve to nothing on a fresh profile. Check the npm version list for newer releases.

After a successful install, refresh the page. A restart is not required — restart or reload the web profile only if the market says it could not hot-load the plugin. Before installing, please read the security note.

Upgrading from a github: install

dsh plugin add github:DietCokewithSugar/dsh-user-experience no longer works. This repository stopped committing lib/, so a Git checkout carries no build artifacts, and pnpm blocks the build step by default. The market reports:

安装失败: dsh-user-experience — nothing installable: the plugin(s) need a build step
(blocked by default, see allowBuilds) or ship no prebuilt artifacts

and the exported log names the Git spec:

[warn]  install: github:DietCokewithSugar/dsh-user-experience: removed uninstallable pieces
        (no dsh manifest or missing build artifacts): dsh-user-experience
[error] install: github:DietCokewithSugar/dsh-user-experience: nothing installable survived validation

Install by package name instead — note there is no github: prefix:

dsh plugin --profile web add [email protected]

If the market still resolves the Git ref, the profile is reusing its old entry. Clean it out:

1. Delete the "dsh-user-experience": "github:DietCokewithSugar/…" line from the profile's package.json.
2. Delete that profile's node_modules and pnpm-lock.yaml. The lockfile pins the old Git resolution, so removing the dependency line alone is not enough.
3. Run the install command again.

On Windows, this locates the profile manifest:

Get-ChildItem -Path $env:APPDATA,$env:LOCALAPPDATA,$env:USERPROFILE -Recurse -Filter package.json -Depth 6 -ErrorAction SilentlyContinue | Where-Object { (Get-Content $_.FullName -Raw -ErrorAction SilentlyContinue) -match 'dsh-user-experience' } | Select-Object FullName

Screenshots

The walkthrough report explains the observed behavior and user impact in plain language:

Speak in plain language to start a walkthrough. If personas are missing, the plugin drafts 1–3 users and asks once before continuing:

Once you confirm that a finding is real, the card provides a task Prompt you can copy to another AI. It describes the observed phenomenon rather than prescribing code changes, tells the AI to inspect the complete project context, and explicitly allows copy changes:

After you edit front-end code, the walkthrough runs itself—no persona questions, no interruption. It speaks up only for level-one / level-two issues:

Multi-level evidence appears in the technical details so every visual or interaction conclusion can be reviewed:

The report card and confirmation workflow can use the developer’s language (English interface below):

---

Supported inputs and evidence

Explicitly unsupported (reported as-is, no low-quality guesses): Svelte, Vue 2 (SFC syntax is incompatible with @vue/compiler-sfc), mini-programs (.wxml), etc. See the current implementation specification for evidence, product-type, and language behavior.

• Every finding is marked static, rendered, or interactive. Browser capability is optional: without it the walkthrough continues with static evidence and never pretends to have seen the page
• Layout-density, visual-language, and primary-action findings require rendered evidence; redundant-flow findings require an interactive persona walkthrough
• No automatic code changes: the plugin gives optimization suggestions; after you confirm a finding, it generates an observation-led task Prompt for a coding AI
• This is still evidence-bounded: CSS can identify inspection leads, but actual whitespace, hierarchy, and visual quality are not asserted without a real rendered route

Features

Three run modes, picked by context

Resolution order: mode in .ux/rules.local.yml → plugin config → context detection.

The five-state finding machine

Both confirmed states count as effective findings in the metrics; stale is excluded from the denominator — "scanned and found nothing" must be distinguished from "never scanned", or deleting code gets misread as fixing it.

High-frequency review order

The walkthrough checks common issues first: (1) feedback and system status; (2) forms and flow recovery; (3) information architecture, navigation, and primary actions; then (4) cognitive load, consistency, edge states, basic usability, and performance. This order improves review efficiency; the final report is still sorted by actual severity.

The 27 rules

Severity is derived from a matrix: impact (does it block the persona's critical task; given by the model) × reach (share of target users affected; derived from the sum of share of hit personas, ≥0.5 is wide) → level one / two / three / four (still P0–P3 internally, never on screen).

Repository file conventions

Recommended addition to the project's .gitignore:

.ux/rules.local.yml
.ux/history.jsonl

Example preference file:

# .ux/rules.local.yml
mode: review        # Pin the run mode; omit to pick by context
autoScan:
  enabled: true     # Change-triggered walkthrough switch
  debounceTurns: 1  # Minimum turns between two automatic walkthroughs

---

Installation

⚠️ Security note (must read)

The npm tarball ships prebuilt artifacts. There is no prepare / preinstall / postinstall script, so pnpm ≥ 10 will not ask you to allowlist a build. Installation does not compile TypeScript on your machine.

Activating the plugin still runs its code inside the Harness process. Therefore:

1. Only install plugins from sources you trust;
2. Pin an exact version so later releases cannot silently change what you load:

dsh plugin --profile <your-profile> add [email protected]

Every published version is built from a tagged commit by the release workflow; the same tarball is attached to the corresponding GitHub Release if you want to diff it against the source.

Coexisting with other plugins

Harness, Cordis, and React are host-owned peer dependencies. This package does not install or bundle private copies of @deepseek-ai/dsh-tools, @deepseek-ai/cordis, other DSH service packages, or React into a profile. All plugins therefore resolve the profile's shared service definitions and Symbol identities.

• No overrides, packageExtensions, or profile dependency rewrites
• No Node.js or React version changes
• No install-time lifecycle scripts; the published tarball ships prebuilt artifacts and does not run pnpm/npm install, add, update, or upgrade
• Compatible DSH release candidates are accepted through peer ranges instead of forcing this plugin's development version into the profile
• CI installs a packed copy into a temporary profile and verifies that the profile and plugin resolve identical real paths for Harness, Cordis, and React packages

This prevents this plugin from creating the duplicate-runtime condition. A different plugin that ships DSH packages as direct dependencies can still introduce its own conflicting copy and should adopt the same peer-dependency contract.

After a successful install, the plugin row (id ux-experience) enters the configuration layer. Refresh the page; restart dsh or reload the profile only if the market cannot hot-load it. Available config options (overridden by id in the profile's cordis.patch.yml or the --patch layer):

- id: ux-experience
  config:
    maxScanFiles: 300            # Max files collected per scan
    maxCandidatesPerRule: 5      # Max candidates per rule per file
    maxCandidatesPerFile: 25     # Total candidate cap per file
    maxFindings: 30              # Max findings per report
    excludePatterns: ['test', 'stories']   # Extra dirs to skip (on top of defaults)
    mode: detect                 # detect|auto|review|interactive (default: pick by context)
    autoScan: true               # Change-triggered walkthrough (on by default)
    autoScanEditTools: ['write', 'edit']   # Tool names counted as "file edits"
    autoScanMaxFiles: 20         # Max changed files pulled into one automatic walkthrough
    autoScanDebounceTurns: 1     # Minimum turns between two automatic walkthroughs
    outputLanguage: auto          # auto|zh-CN|en

A user's .ux/rules.local.yml takes precedence over this layer.

Usage

Just talk. There is no slash command to learn:

check the checkout flow from selection to payment
we mostly build this for operators
the second one isn't a problem

If the project has no personas yet, the first walkthrough shows a short card (“look through these users’ eyes?”). After you say “those are fine” or change one line, the walkthrough continues. Later teammates pick up .ux/personas.yml from git and never see that step.

Once the report is up, click the card buttons or keep talking:

the second one isn't a problem
those are all right
ignore everything below level three
the delete one — I confirm it

After confirming a finding, click Copy task Prompt for AI on that card and paste it into your coding agent. The Prompt deliberately describes what users experience without guessing at the implementation from partial source context.

After editing front-end code—including CSS—you need do nothing at all: the static walkthrough runs as the turn wraps up, reports quietly, and speaks up only for level-one / level-two issues. A user-initiated walkthrough can upgrade evidence with browser screenshots and persona task execution when those tools are available.

Development

pnpm install
pnpm run build     # tsdown (host half + client bundle) + tsc (type declarations)
pnpm test          # smoke tests (AST/CSS / evidence levels / localization / persona / modes / ledger / end-to-end)
pnpm run test:singleton  # pack into a temporary profile and verify shared runtime identities

lib/ is a build artifact and is not committed — run pnpm run build before pnpm test. Releases are cut by tagging: bump version in package.json, then push a v<version> tag. The release workflow builds, tests, packs, publishes to npm, and attaches the tarball to a GitHub Release; it fails loudly if the tag and package.json version disagree, or if NPM_TOKEN is missing.

• Compatibility baseline: local build/tests use @deepseek-ai/dsh-*@0.1.0-rc.6 and @deepseek-ai/[email protected]; runtime framework packages are peers resolved from the profile (>=0.1.0-rc.6 <0.2.0 for DSH).
• Structure: src/index.ts is the Host plugin (hidden card-button channel + prompt injection + four model tools + the change-triggered walkthrough); src/client/ is the Web client plugin (report card, discovered by the module table via the dsh.client declaration); one bundle row (cordis.patch.yml) mounts both.
• Red line: the agent loop is untouched — all capabilities hang on documented extension points (ctx.commands / ctx.systemPrompt.section() / ctx.tools.register() / SessionEventMap / tools/result / agent/turn-stopping). The automatic walkthrough uses the framework's own /loop shape: a listener calls agent.steer() at the turn's stop boundary and the machine re-reads its inbox for one more step.

License

MIT