hhix-uiux — HHIX/MBCM UI 设计工作台（DSH 插件）

一条 /hhix-init，就把 DSH 里的一个文件夹变成完整的产品设计工程：内置 DESIGN.md、 shadcn-vue 组件库、hhix-ui-design 技能、AGENTS.md、git 仓库（含首次提交）与已装好的依赖。文件夹本身就是设计根目录，没有嵌套的 prototypes/<slug>/。

空文件夹  →  /hhix-init  →  /hhix-ui-design <需求>  →  /hhix-open  →  /hhix-verify

工作区就是你的会话工作区，所以不需要为了改页面另开会话。

0.3.0 起，每条 /hhix-* 命令都会把执行过程逐步打印出来（做了什么、多久、跑的是哪条命令、日志落在哪），不再是黑盒。见 §4 与 §5。

1. 它提供什么

能力	内容
一条命令成型	`/hhix-init` = 复制模板 + 注入技能 + `git init` + 首次提交 + 装依赖 + 记录工作区
设计根 = 工作区根	`DESIGN.md`／`src/`／`docs/`／`package.json` 就在这一层，一工作区 = 一产品设计
模板快照	`DESIGN.md`、19 个 shadcn-vue 组件族、示例页面、设计令牌校验脚本（约 1.4 MB，188 个文件）
零安装预览	预构建 `dist/` 快照，不装依赖也能先看模板长什么样
技能	`hhix-ui-design` 随插件提供，任何会话都能用，不依赖你本机 `~/.agents/skills`
8 个工具	`hhix_workspace_init` / `hhix_workspace_status` + `hhix_design_` `serve`/`stop`/`open`/`verify`/`sync`/`git_init`
7 个命令	`/hhix-init` `/hhix-status` `/hhix-open` `/hhix-stop` `/hhix-verify` `/hhix-sync` `/hhix-log`
执行日志	每条命令输出逐步 trace，同时写入 `<设计根>/.hhix/logs/`，可用 `/hhix-log` 回看

2. 安装

当前版本：0.3.4（包名 @hanbd/dsh-plugin-hhix-uiux）。

A. 从 npm 装（推荐）

dsh plugin --profile desktop add @hanbd/dsh-plugin-hhix-uiux

或 DSH 侧栏 Plugins → Add plugin，粘贴 @hanbd/dsh-plugin-hhix-uiux。国内用默认的 registry.npmmirror.com 即可（它是 npmjs 的只读镜像，会自动同步）。

B. 从 `.tgz` 装（离线 / 内网 / 不走 registry）

dsh plugin --profile desktop add /path/to/hanbd-dsh-plugin-hhix-uiux-0.3.4.tgz

或 Plugins 页粘贴 tgz 绝对路径。

安装后确认

新会话里有 /hhix- 开头的命令；
/hhix-ui-design 出现在技能列表里；
Plugins 页能看到 bundle 卡片。

换版本后必须完全退出并重启 DSH。 同一进程内的 JS 模块代际会被缓存， set_plugin 返回 applied 也不代表新代码已加载。

从 0.2.x 升级

0.3.0 把「工作区容器 + prototypes/<slug>/ 设计」换成「工作区根就是设计根」，所以：

0.2.x	0.3.0
`/hhix-init` 只建 `prototypes/` + `.hhix/`	`/hhix-init` 直接把模板、技能、git 铺进该文件夹
`/hhix-new <slug> "标题"` 建一个设计	已移除，`/hhix-init` 一步到位
`/hhix-list` `/hhix-workspace` 列多个设计	合并为 `/hhix-status`
`/hhix-open <slug>` `/hhix-stop <slug>` `/hhix-verify <slug>` `/hhix-sync <slug>`	不再需要 slug：`/hhix-open` `/hhix-stop` `/hhix-verify` `/hhix-sync`
`hhix_prototype_*` 工具	改为 `hhix_design_*`（`create`/`list` 移除）
命令没有任何输出	每条命令输出逐步 trace，并写入 `.hhix/logs/`

已有的 0.2.x 工作区不会被自动迁移：它的设计还在 prototypes/<slug>/ 里，插件会照常工作，但 /hhix-status 会提醒你当前布局是旧的。要迁移，把某个设计目录的内容整体上移到工作区根（或干脆在别处跑一次 /hhix-init 重新开始），然后把旧的 prototypes/ 删掉。

3. 工作方式

3.1 一次 `/hhix-init`（每个设计做一次）

在 DSH 里新建一个空文件夹（或选一个现成的前端工程），把它作为会话工作区打开。
跑：

/hhix-init

或者让 agent 调 hhix_workspace_init。插件会把该文件夹布置成设计根：

你的文件夹/
├── DESIGN.md            视觉真源（唯一）
├── AGENTS.md            agent 协作约定
├── package.json         Vue 3 + Vite + Tailwind v4 + shadcn-vue
├── index.html
├── src/
│   ├── components/      ui / patterns / layout —— 优先复用
│   ├── pages/           示例页面
│   ├── styles/          设计令牌
│   └── router/
├── docs/ui-ux/          规格（<feature>.md）与参考图（images/）
├── .agents/skills/      随模板注入的 hhix-ui-design 技能
├── .gitignore           基线忽略规则（node_modules / dist / 日志）+ 托管块
├── .hhix/               插件元数据 + 执行日志（已被 .gitignore 排除）
└── .git/                已初始化，含首次提交

特性：

幂等 —— 重复跑只刷新工作区记录与指针，不覆盖任何已有文件；
不覆盖 —— 已存在的文件一律保留，并在 trace 里报告保留了多少个；
可接管现成工程 —— 文件夹非空也能用（只补缺失文件），并给出提示；
git 只认自己的 —— 已经是 git 仓库的文件夹，插件不碰它的历史和提交；
先提交再装依赖 —— 首次提交不含 node_modules/、dist/、日志；
默认装依赖 —— 除非加 --no-install。

/hhix-init                                    ← 在当前会话工作区里初始化
/hhix-init ~/work/mbcm-design "MBCM 设计"      ← 指定目录与标题
/hhix-init --no-install                       ← 先不装依赖

3.2 设计页面

设计根就在你的会话工作区内，所以当前会话直接改：

/hhix-ui-design 照这张图做【环保管理】页面，数据来自监测站…

技能会自己走完：读 DESIGN.md → 查组件 → 写规格到 docs/ui-ux/<feature>.md → 实现页面 → 校验。参考图放 docs/ui-ux/images/。

3.3 看效果

/hhix-open                                     ← 起服务 + 打开系统默认浏览器
/hhix-open /app/environment/monitor            ← 直接打开某个路由
/hhix-open --preview                           ← 零安装看插件自带的模板快照
/hhix-stop                                     ← 用完停掉

3.4 一个工作区，一个设计

插件只认一个活动工作区（记录在 $DSH_HOME/hhix-uiux/active-workspace.json，重启 DSH 后依然有效）。需要另一个设计时，显式再跑一次：

/hhix-init /path/to/another-folder

4. 命令详解

斜杠命令是你直接敲的快捷方式。它们只做机械动作 —— 建目录、复制模板、git init、起服务、跑校验 —— 不会让 agent 写页面（命令输出不进模型历史）。要让 agent 实现页面，用技能入口 /hhix-ui-design <需求>。

参数约定

写法	含义
`[x]`	可选
`"标题"`	用引号包住含空格的值
`--flag`	开关，位置任意，放在最后最清楚

含空格的路径必须加引号（否则会在第一个空格处断开）：

/hhix-init "/Users/me/My Documents/design" "我的设计"     ← 正确
/hhix-init /Users/me/My Documents/design                  ← 会被拆成两段，错误

命令名必须完整输入，不支持前缀缩写（打 /hhix 不会出现匹配）。

`/hhix-init` — 初始化设计工作区（并铺好设计）

/hhix-init [folder] ["标题"] [--no-install]

参数	必填	说明
`folder`	否	要初始化的文件夹，绝对路径（支持 `~`）。含空格必须加引号
`"标题"`	否	设计标题，写进 `.hhix/workspace.json`
`--no-install`	否	跳过依赖安装。默认会跑 `pnpm install --frozen-lockfile`

省略 folder 时的回退顺序：

会话工作区 —— 你为这个会话打开的那个文件夹（DSH 通过 agent.session.header.cwd 提供，与读写文件、执行 bash 用的是同一个位置）。所以在目标文件夹里开会话时，裸跑 /hhix-init 就会初始化当前文件夹。
活动工作区 —— 已经初始化过的工作区，重复执行会把指针刷新回它（幂等）。
都没有 → 报错并给出示例，不会随便挑一个目录。

插件的错误目录防护：Harness 配置目录（~/.dsh 及其内部）永远不会被初始化为设计根 —— 那里存放着实时配置与已安装插件，而设计根会在顶层写 DESIGN.md、src/、.hhix/。若会话恰好开在 ~/.dsh 下，插件会拒绝并提示你换一个普通项目目录。

执行前会先预检两个命令行工具（此时还没有创建任何文件）：

工具	何时需要	缺失时
`git`	总是需要（会建仓库并打首次提交）	阻止执行，不创建任何东西
包管理器	仅当会装依赖时（默认会；`--no-install` 跳过）	先尝试 `npm` 兜底（Node 自带），再不行就阻止执行

缺失时会唤醒 agent，把"装什么、怎么装、装完重跑哪条命令"作为一条请求交给它；命令本身会把缺什么、怎么修打印出来。装完后重跑 /hhix-init 即可 —— 失败的预检不会留下任何文件，连 .hhix/logs/ 都不会创建。

做什么：见 §3.1 的目录树。每一步都会打印出来：

hhix-init
  args: /Users/me/work/env-board "环保监测看板"
  at:   2026-10-08T15:04:35.847Z

steps:
15:04:35.847  ok    check that git is available  (13ms)
             git version 2.50.1
15:04:35.860  ok    check that the package manager "pnpm" is available  (24ms)
             pnpm (10.33.0)
15:04:35.848  info  target folder resolved from the argument  (1ms)
             /Users/me/work/env-board
15:04:35.849  ok    copy template v0.3.4 into the folder  (103ms)
             188 template file(s), 0 kept as-is
15:04:35.952  ok    inject AGENTS.md and the hhix-ui-design skill  (9ms)
             .agents/skills/hhix-ui-design/
15:04:35.961  ok    write .hhix/workspace.json and register the active workspace  (1ms)
             title "环保监测看板"; README.md left as it is
15:04:35.962  ok    initialize a git repository and commit the scaffold  (186ms)
             first commit created (193 files)
15:04:36.148  ok    install dependencies (pnpm install --frozen-lockfile)  (1.2s)

total: 1.5s

Design workspace and product design are ready.
  root:     /Users/me/work/env-board
  ...

`/hhix-status` — 看当前设计的状态

/hhix-status

无参数。显示设计根路径、标题、DESIGN.md 是否在、依赖是否装好、服务是否在跑、模板版本，以及旧版布局（prototypes/）的提醒。尚未初始化任何工作区时会给出下一步提示。

`/hhix-open` — 起服务并打开浏览器

/hhix-open [route]
/hhix-open --preview

参数	必填	说明
`route`	否	追加的应用内路由，如 `/app/environment/monitor`
`--preview`	否	不碰你的设计，直接服务插件内置的模板快照（零安装，看看模板长什么样）

做什么：若服务未运行则先起（用配置的 serveMode），然后用操作系统默认浏览器打开。已在跑的服务会复用，不会重启。

依赖没装时 dev 模式起不来。trace 会直接把原因说清楚（vite: command not found

该先跑 pnpm install --frozen-lockfile），而不是干等一分钟。想马上看效果就用 --preview。

也会打印 URL。想在 DSH 右侧边栏浏览器里看，就点 agent 回复里的链接（侧栏只接受 http://127.0.0.1:<port>，不接受 file: 或同源路由）。

`/hhix-stop` — 停止服务

/hhix-stop

无参数。终止服务进程组（先 SIGTERM，2 秒后仍在则 SIGKILL）并释放端口。没在跑时会提示 Nothing was running。

dev 模式是 detached 子进程，不会随会话或 DSH 退出而死 —— 这是刻意的（你要一直开着链接），所以用完记得停。preview 模式的服务在插件进程内，插件卸载时自动关闭。

`/hhix-verify` — 校验

/hhix-verify [--full]

参数	必填	说明
`--full`	否	额外跑生产构建（慢），默认不跑

依次执行（项目里没定义该 script 的会跳过）：

检查	来源	失败是否算失败
`typecheck`	`package.json` script	是
`lint`	`package.json` script	是
`design:tokens:check`	`package.json` script	是
`design:lint`	`package.json` script	是
`build`	仅 `--full` 时	是
`scan-raw-tokens`	技能自带脚本	提示性（只报告候选，不判失败）

未装依赖时结果是 BLOCKED（不是 FAIL），并告诉你怎么装，而不是超时。

/hhix-verify
/hhix-verify --full

`/hhix-sync` — 用新版模板更新设计

/hhix-sync [--dry-run]

参数	必填	说明
`--dry-run`	否	只报告不写入

做什么：按 .hhix/template.json 的哈希清单做三方比对（模板旧哈希 / 模板新哈希 / 你的当前文件）：

情况	结果
模板改了、你没改	更新
模板改了、你也改了	冲突 —— 保留你的版本，单独列出
你改了、模板没改	不动（报告为 `yours`）

只增不删：永远不会删除设计里的文件。同时会把新版技能一起同步进去；如果设计根没有 .gitignore 就按模板补一份基线规则（node_modules / dist / 日志），然后追加本插件的 .hhix/ 托管块。

/hhix-sync --dry-run
/hhix-sync

何时用：装了新版本插件之后。templateVersion 取的是插件版本号，所以升级插件即可被识别。

`/hhix-log` — 回看命令执行记录

/hhix-log [count]
/hhix-log latest
/hhix-log <file-name>.log

参数	必填	说明
`count`	否	列出最近 N 次执行（默认 15）
`latest`	否	把最近一次的完整日志打印出来
`<file-name>.log`	否	打印指定那次的完整日志（文件名从列表里抄）

/hhix-log
/hhix-log 30
/hhix-log latest

输出形如：

5 most recent run(s) in ~/work/env-board/.hhix/logs:

2026-10-08 15:04:18  ok    hhix-sync               1 steps     0ms  --dry-run
2026-10-08 15:04:18  warn  hhix-verify             7 steps    57ms
2026-10-08 15:04:15  ok    hhix-open --preview     2 steps   159ms
2026-10-08 15:04:15  ok    hhix-status             7 steps     3ms
2026-10-08 15:04:12  ok    hhix-init               7 steps   269ms  /Users/me/work/env-board --no-install

为什么命令能在对话里看到输出

DSH 里命令的返回值本身只落成一条 command/done 会话事件，不会唤醒 agent，也不一定渲染出来 —— 实测就是这样：/hhix-init 复制完 188 个文件、建好 git、装完依赖，而敲命令的人什么都没看到 （会话日志里只有 command/run + command/done，没有 turn/start）。

所以本插件在命令返回后主动唤醒 agent，把带前缀的执行报告作为一条消息投进对话，模型因此会给出一段正常回复：

[hhix-uiux · /hhix-init] completed
Summary: design root ~/Code/tmp/hhix-uiux-test created: template v0.3.4, 188 files, git initialized, deps ok

The execution log below is machine output from the plugin, not a request from the user.
Do not repeat it verbatim and do not re-run the work. Reply with a short account of what
now exists and what the user should do next, then wait for their instruction.

```text
hhix-init
  args: ~/Code/tmp/hhix-uiux-test "环保监测看板"
  at:   2026-10-09T01:36:29.150Z

steps:
01:36:29.152  info  target folder resolved from the session workspace  (1ms)
01:36:29.154  ok    copy template v0.3.4 into the folder  (89ms)
             187 template file(s), 0 kept as-is
01:36:29.243  ok    inject AGENTS.md and the hhix-ui-design skill  (8ms)
             .agents/skills/hhix-ui-design/; .gitignore created with the .hhix/ rules
01:36:29.251  ok    initialize a git repository and commit the scaffold  (162ms)
             first commit created (192 files)
01:36:29.413  ok    install dependencies (pnpm install --frozen-lockfile)  (1.4s)

total: 1.6s


然后模型回一句「工作区已就绪，可以直接描述要做的页面」，会话就和你平时跟模型对话一样。

消息的来源标记为 `plugin: hhix-uiux`，**不是** `user` —— 报告不是你说的话，
把它伪装成用户消息会往历史里塞一段你从没写过的内容。

**默认只对改变状态的命令这样做**（`/hhix-init` `/hhix-open` `/hhix-stop` `/hhix-sync`）。
`/hhix-status` `/hhix-verify` `/hhix-log` 这类查询默认**不**唤醒模型，免得一次查看就花掉一个模型轮次。
想全都唤醒就把 `announceCommands` 设成 `always`，想全都安静就设成 `never`
（那样命令输出只留在 `.hhix/logs/` 里）。

> **命令不会替 agent 干活。** 唤醒 agent 只是让它把刚才发生的事讲清楚，
> 不是让它开始写页面。要让 agent 实现页面，请用技能入口：
> `/hhix-ui-design <需求描述>`（可贴参考图）。

---

## 5. 命令执行日志

每条命令都会输出一段逐步 trace，并把它写成一份持久日志。

**trace 里有什么**：命令名与参数、开始时间、每一步的 `HH:MM:SS.mmm` + 结果
（`ok` / `info` / `warn` / `FAIL`）+ 该步耗时、实际跑的子命令与退出情况、总耗时，
以及这次日志的落盘位置。

**日志落在哪**：

<设计根>/.hhix/logs/ ├── hhix-2026-10-08T15-04-35-847-32894.log ← 每次执行一份，JSONL + 可读文本 ├── hhix-2026-10-08T15-04-36-149-32894.log └── latest.log ← 最近一次的副本


JSONL 第一行是这次执行的汇总（`hhix-command-run`），之后每个 `step` 一行，便于脚本消费。
`/hhix-log` 就是读这些行拼出上面那张表的。

**为什么要落盘**：`/hhix-init` 会复制 188 个文件、建 git 仓库、打首次提交、装依赖，
还会在 `$DSH_HOME` 下写指针文件。这些动作过后要能回答「到底做了什么」，
所以每次执行都留一份可审计的记录 —— 包括**失败的那次**（失败路径同样会写日志）。

**其它落盘日志**：

| 文件 | 内容 |
|---|---|
| `.hhix/install.log` | 那次 `pnpm install` 的完整输出 |
| `.hhix/serve.log` | dev server 的输出（Vite 启动信息、编译错误都在这） |
| `.hhix/verify.log` | `/hhix-verify` 每条检查的完整输出 |
| `.hhix/prototype.json` | 服务的端口 / pid / 模式 / URL |
| `.hhix/workspace.json` | 工作区记录（标题、创建时间、布局版本） |
| `.hhix/template.json` | 模板版本 + 每个文件的哈希（`/hhix-sync` 的基线） |

设计根的 `.gitignore` 由两部分组成：

1. **模板带来的基线规则** —— `node_modules`、`dist`、`*.log`、编辑器目录等。
   模板快照里这个文件叫 `gitignore`（**没有点**），因为 `npm pack` 会把任何名为 `.gitignore`
   的文件从包里丢掉；插件复制时再还原成 `.gitignore`。
   > 这个缺陷从 0.2.0 一直存在到 0.3.1：那些版本装出来的设计根**没有基线忽略规则**，
   > `node_modules/` 会一直出现在 `git status` 里。0.3.2 修好了，`/hhix-sync` 也能给老设计根补上。
2. **本插件追加的托管块** —— 带 `hhix-uiux:begin` / `hhix-uiux:end` 标记，里面是 `.hhix/`，
   所以插件的元数据与执行日志不会污染你的提交。

已有的 `.gitignore` **不会被覆盖**；只有完全没有时才按模板补一份。

---

## 6. 工具参考（agent 调用）

| 工具 | 参数 | 说明 |
|---|---|---|
| `hhix_workspace_init` | `path?`, `title?`, `install?` | 一步完成：预检 `git`/包管理器、复制模板、注入技能与 `AGENTS.md`、`git init` + 首次提交、装依赖、记录活动工作区 |
| `hhix_workspace_status` | — | 报告活动工作区、设计根内容、模板版本、依赖与服务的运行状态 |
| `hhix_design_serve` | `mode?`, `port?`, `open?` | `dev` 起 Vite（需装依赖）；`preview` 用插件自带静态服务（零依赖，含 SPA fallback） |
| `hhix_design_stop` | — | 终止进程组并释放端口 |
| `hhix_design_open` | `path?`, `mode?` | 起服务（若未跑）+ 打开系统默认浏览器，可带路由 |
| `hhix_design_verify` | `full?` | typecheck → lint → design:tokens:check →（`full` 时 build）；raw-token 扫描为提示性 |
| `hhix_design_sync` | `dryRun?` | 按哈希清单与模板比对，**只增不删**，冲突单列 |
| `hhix_design_git_init` | — | 给缺失 git 仓库的设计补一个（已有仓库不碰） |

工具不接收 slug：活动工作区就是唯一的设计根。工具的 trace 会渲染给模型看，但**不**写进
`.hhix/logs/` —— 那个目录只记录**你**显式敲的命令，免得被模型的高频调用淹没。

**端口**：默认在 `5300–5399` 里找空位，写进 `.hhix/prototype.json`，重启复用。
Vite 以 `--strictPort --host 127.0.0.1` 启动：端口不会静默漂移，且只监听本机 IPv4。

**服务进程**：`dev` 模式是 **detached** 子进程，不会随会话或 DSH 退出而死
（这是刻意的，用户要一直开着链接），**用完请** `/hhix-stop`。

---

## 7. 配置

安装时 patch 行里的 `config`。行内 `config` 是**整体替换**而非深合并，覆盖时请写全你要用的键。

| 键 | 默认 | 说明 |
| --- | --- | --- |
| `prototypesRoot` | `~/hhix-prototypes` | **仅为兼容保留**。0.3.0 起设计根必须显式指定，插件不会往里铺设计；它只是「还没有工作区」时工具报告的位置 |
| `portRange` | `[5300, 5399]` | 端口扫描范围 |
| `packageManager` | `pnpm` | 装依赖用的包管理器。**缺失时自动回落到 `npm`**（Node 自带）并在 trace 里报告；`npm` 也没有才视为前置条件不满足 |
| `announceCommands` | `on-change` | 命令结果是否唤醒 agent，从而以正常会话轮次出现在对话里：`on-change` / `always` / `never` |
| `installOnCreate` | `true` | `/hhix-init` 时自动装依赖 |
| `openOnServe` | `true` | 起服务时自动开系统浏览器 |
| `serveMode` | `dev` | 默认服务模式 |
| `templateDir` | `''` | 指向团队 git checkout 以覆盖内置模板 |
| `preferOfflineInstall` | `true` | 给包管理器加 `--prefer-offline` |
| `checkTimeoutMs` | `600000` | 单条校验命令超时 |
| `installTimeoutMs` | `900000` | 单次依赖安装超时 |
| `readyTimeoutMs` | `60000` | 等待服务响应 HTTP 的时间 |
| `registerSkillProvider` | `true` | 是否由本插件提供内置 `hhix-ui-design` 技能 |

覆盖示例（写进 `~/.dsh/profiles/desktop/cordis.patch.yml`）：

```yaml
- id: hhix-uiux
  name: '@hanbd/dsh-plugin-hhix-uiux'
  config:
    prototypesRoot: '~/hhix-prototypes'
    portRange: [5400, 5499]
    packageManager: pnpm
    announceCommands: on-change
    installOnCreate: true
    openOnServe: true
    serveMode: dev
    templateDir: ''
    preferOfflineInstall: true
    checkTimeoutMs: 600000
    installTimeoutMs: 900000
    readyTimeoutMs: 60000
    registerSkillProvider: true

未知键会被忽略并记进激活日志（config.x is not an option ...），不会让插件启用失败 —— 这一条在 0.3.2 起改过：0.3.1 时"未知键即报错"撞上模块代际错配（应用运行期间更新插件），导致插件完全不激活。已知键的值仍然严格校验。

8. agent 集成约定：只用 `.agents/` + `AGENTS.md`

文件	作用
`AGENTS.md`	设计根的协作约定：技能入口、视觉真源、组件复用、规格与图片位置、完工前要跑的检查
`.agents/skills/hhix-ui-design/`	随模板注入的技能本体（每个设计自带一份，可用 `/hhix-sync` 升级）

不再创建 CLAUDE.md，也不再建 .claude/skills/ 软链。 旧版本生成的这两样会在下次 /hhix-init 或 /hhix-sync 时被清理（只删本插件生成的内容，用户自己写的 CLAUDE.md 会保留）。顺带的好处是去掉了符号链接 —— Windows 上建软链需要开发者模式或管理员权限。

9. 技能从哪来

位置	优先级	作用
设计根的 `.agents/skills/hhix-ui-design/`	高	随模板注入，每个设计自带；遵循 `.agents` + `AGENTS.md` 约定的 agent 都能发现
插件内置 `skills/hhix-ui-design/`	低	保底，任何会话可用，不依赖本机全局技能
`~/.agents/skills/hhix-ui-design`	—	不受影响，你的全局技能保持原样

优先级高的先命中：设计里的技能版本说了算。这也是「模板升级带动技能升级」的机制 —— /hhix-sync 会把新版技能一起同步进设计。

10. 排障

症状	原因	处置
`/hhix-*` 命令不存在	bundle 未启用 / 模块代际是旧的	Plugins 页确认开关；换版本后必须完全退出并重启 DSH
敲了命令，但对话里什么都没有	客户端没有渲染 `command/done` 事件（DSH 侧的显示问题）	0.3.0 起命令会主动唤醒 agent，正常应该能看到了；确认 `announceCommands` 不是 `never`，并重启 DSH 让新版本生效
不想让查询类命令也唤醒模型	默认就不会	`announceCommands` 保持默认的 `on-change`；设成 `never` 则完全不唤醒
不知道某条命令做了什么	命令只给了一行结果	看输出里的 `steps:` 段，或 `/hhix-log latest` 读完整日志
提示活动工作区不存在	文件夹被移走或删了	重新 `/hhix-init <新路径>`，或把文件夹移回来
`/hhix-open` 报 `vite: command not found`	依赖没装	`/hhix-init` 会默认装；手动补 `pnpm install --frozen-lockfile`，或先用 `/hhix-open --preview`
链接点开空白	用了 `file:` 或 DSH 同源路由	只用 `http://127.0.0.1:<port>`；`file:` 被侧栏浏览器禁用
自己手起的 Vite 打不开（连接被拒）	Vite 8 默认只监听 IPv6 `[::1]`	插件启动时强制 `--host 127.0.0.1`；手动起请自己加这个参数
`pnpm install` 失败（私服/离线）	无网或 npmrc 指向私服	用 `--preview` 零安装模式；或先手动 `pnpm install` 再 `/hhix-open`
提示 `git is not available`，且没创建任何文件	机器上没装 git	按提示装好 git 并重开终端，再跑 `/hhix-init`。这是刻意的：宁可不做，也不做一半
提示包管理器不可用	`pnpm` 没装，且 `npm` 也不在 PATH 上	装 Node.js（自带 npm）或 pnpm；或把 `packageManager` 配成你已有的管理器
`spawn pnpm EINVAL`（Windows）	旧版本未处理 `.cmd` 批处理	升级到 0.3.4+；该版本按 `PATHEXT` 解析并走 `cmd.exe`
`/hhix-stop` 后端口仍被占（Windows）	旧版本只杀父进程	升级到 0.3.4+；该版本用 `taskkill /F /T` 杀整棵树
`/hhix-open --preview` 报缺 snapshot	插件包不完整	重装插件
`/hhix-verify` 报 lint 失败且指向 `.agents/`	设计根的 eslint 没忽略注入的技能目录	新版模板已在 `eslint.config.js` 忽略 `.agents`；旧设计请 `/hhix-sync`
`git status` 里冒出 `.hhix/`	旧版设计根没有托管忽略块	`/hhix-sync` 会补上；或手工加一行 `.hhix/`
`git status` 里冒出 `node_modules/`	0.2.0–0.3.1 的发布包被 `npm pack` 丢掉了 `.gitignore`（该文件在 npm 的永不打包清单里）	升级到 0.3.4 并跑一次 `/hhix-sync`，它会补上基线规则；或手工把 `node_modules`/`dist`/`*.log` 加进 `.gitignore`
`/hhix-status` 提示 `prototypes/` 旧布局	0.2.x 建的工作区	见 §2 从 0.2.x 升级
服务残留	detached 设计使然	`/hhix-stop`

11. Windows 支持现状

结论：设计上已按平台处理，但作者没有 Windows 机器，未经实机验证。 首次在 Windows 上使用时请把异常原文反馈回来。

已经按平台处理的四处：

位置	问题	处理
启动子进程（`lib/exec.js`）	`pnpm`/`npm` 在 Windows 上是 `.cmd` 批处理，Node 的 `spawn` 无法直接执行批处理文件（`EINVAL`），而同样命令在你自己的终端里是好的	按 `PATH` + `PATHEXT` 解析目标；命中 `.cmd`/`.bat` 时改走 `cmd.exe /d /s /c`（不是 `shell: true`，避免 `cmd` 二次解析参数）
停止服务（`lib/process.js`）	POSIX 用负 PID 杀进程组；Windows 没有信号，只杀父进程会让 Vite 的 esbuild 子进程继续占着端口	Windows 改用 `taskkill /T`（温和）→ `taskkill /F /T`（强制）杀整棵进程树
打开浏览器（`lib/opener.js`）	—	`cmd /c start`
执行日志文件名（`lib/logger.js`）	`:` 是 Windows 非法字符	文件名里的 `:`/`.` 已替换为 `-`

另外：不再创建符号链接（见 §8），所以不再需要开发者模式或管理员权限。

仍可能存在但未验证的点：

taskkill 的行为（权限、UAC、进程树边界）只在文档层面确认过。
PowerShell 与 cmd.exe 混用时的 ComSpec 取值（代码优先用环境变量 ComSpec）。
非 ASCII 路径（中文目录名）在模板复制与 git 提交路径上的编码表现。
pnpm 通过 corepack / fnm / nvm-windows 安装时可能同时存在无扩展名脚本与 .cmd，解析顺序按 PATHEXT。

12. 已知限制

一次只用一个工作区。需要第二个时显式跑 /hhix-init <新目录>；插件不会自动切换。
一个工作区一个设计。插件不提供「同一目录放多个设计」的模式。
没有侧栏 UI。目前只有工具与斜杠命令，没有 DSH 客户端页面。
/hhix-sync 按文件粒度合并，没有行级三方合并；冲突需手工处理。
校验依赖设计根已装依赖；未装时 /hhix-verify 返回 BLOCKED 而不是超时。
命令不行内流式输出。DSH 的命令协议只接受一个最终结果，所以 trace 是执行完一次性给出的，不是边跑边刷；装依赖这类慢步骤期间不会动。
命令输出依赖一次模型轮次。报告是作为一条消息投进对话的，所以会消耗一次模型调用；嫌吵就把 announceCommands 设成 never。

dsh-plugin-hhix-uiux

Install

Source

Tags

Creators

Readme

hhix-uiux — HHIX/MBCM UI 设计工作台（DSH 插件）

1. 它提供什么

2. 安装

A. 从 npm 装（推荐）

B. 从 `.tgz` 装（离线 / 内网 / 不走 registry）

安装后确认

从 0.2.x 升级

3. 工作方式

3.1 一次 `/hhix-init`（每个设计做一次）

3.2 设计页面

3.3 看效果

3.4 一个工作区，一个设计

4. 命令详解

参数约定

`/hhix-init` — 初始化设计工作区（并铺好设计）

`/hhix-status` — 看当前设计的状态

`/hhix-open` — 起服务并打开浏览器

`/hhix-stop` — 停止服务

`/hhix-verify` — 校验

`/hhix-sync` — 用新版模板更新设计

`/hhix-log` — 回看命令执行记录

为什么命令能在对话里看到输出

8. agent 集成约定：只用 `.agents/` + `AGENTS.md`

9. 技能从哪来

10. 排障

11. Windows 支持现状

12. 已知限制

Install

Source

Tags

Creators

Readme

hhix-uiux — HHIX/MBCM UI 设计工作台（DSH 插件）

1. 它提供什么

2. 安装

A. 从 npm 装（推荐）

B. 从 .tgz 装（离线 / 内网 / 不走 registry）

安装后确认

从 0.2.x 升级

3. 工作方式

3.1 一次 /hhix-init（每个设计做一次）

3.2 设计页面

3.3 看效果

3.4 一个工作区，一个设计

4. 命令详解

参数约定

/hhix-init — 初始化设计工作区（并铺好设计）

/hhix-status — 看当前设计的状态

/hhix-open — 起服务并打开浏览器

/hhix-stop — 停止服务

/hhix-verify — 校验

/hhix-sync — 用新版模板更新设计

/hhix-log — 回看命令执行记录

为什么命令能在对话里看到输出

8. agent 集成约定：只用 .agents/ + AGENTS.md

9. 技能从哪来

10. 排障

11. Windows 支持现状

12. 已知限制

B. 从 `.tgz` 装（离线 / 内网 / 不走 registry）

3.1 一次 `/hhix-init`（每个设计做一次）

`/hhix-init` — 初始化设计工作区（并铺好设计）

`/hhix-status` — 看当前设计的状态

`/hhix-open` — 起服务并打开浏览器

`/hhix-stop` — 停止服务

`/hhix-verify` — 校验

`/hhix-sync` — 用新版模板更新设计

`/hhix-log` — 回看命令执行记录

8. agent 集成约定：只用 `.agents/` + `AGENTS.md`