dsh-question 0.0.0-stage → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 1234ab484
+
+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/README.en.md

@@ -0,0 +1,149 @@
+# dsh-question
+
+[![npm version](https://img.shields.io/npm/v/dsh-question.svg)](https://www.npmjs.com/package/dsh-question)
+[![license](https://img.shields.io/npm/l/dsh-question.svg)](LICENSE)
+[![ci](https://github.com/1234ab484/dsh-question/actions/workflows/ci.yml/badge.svg)](https://github.com/1234ab484/dsh-question/actions/workflows/ci.yml)
+
+Ask-and-wait question cards for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH).
+
+`dsh-question` renders a question from the model as a card you answer in place: pick an option, hover
+for the full explanation, or type your own answer. The card holds the turn until you submit, then the
+answer goes back to the model and work continues.
+
+[English](README.en.md) | [中文](README.md)
+
+![Question card](docs/card.png)
+
+![Hover tooltip](docs/hover.png)
+
+| Single-select radio (8×) | Multi-select |
+| --- | --- |
+| ![radio](docs/radio-zoom.png) | ![multi](docs/multi.png) |
+
+## Features
+
+- **Key-point options** — each option row shows only the short label, clamped to two lines;
+- **Hover details** — hovering or focusing an option opens a floating tooltip with the full
+  explanation; a truncated label gets its complete text on the tooltip's first line;
+- **Free-form answers** — the custom row reads “其他：” or “Other: ” and takes typed input directly,
+  no pencil icon needed;
+- **Single & multi select** — 26px circular radios for single-select, native checkboxes for multi-select;
+- **Keyboard shortcuts** — `1`–`9` select/toggle, `Enter` runs the primary action (submit / next),
+  `←`/`→` switch between questions of a multi-question batch, `Esc` collapses the card without
+  cancelling the batch;
+- **Multiple questions, switchable** — a batch shows one question at a time; use the visible pager
+  buttons or `←`/`→` to move back and forth, and every answer draft is kept;
+- **Waits for you** — the turn stays paused until you submit; countdown, skip and paging keep working;
+- **Automatic Chinese / English** — the UI string follows the DSH interface language, switching live;
+  no manual edit or config.
+
+The plugin only renders the question card and its interactions; the model-facing tool contract is
+unchanged.
+
+## Installation
+
+### From npm
+
+```powershell
+dsh plugin --profile <profile> add dsh-question
+```
+
+### From GitHub
+
+```powershell
+dsh plugin --profile <profile> add github:1234ab484/dsh-question
+```
+
+### From a local checkout
+
+```powershell
+git clone https://github.com/1234ab484/dsh-question
+dsh plugin --profile <profile> add "link:<path-to-this-repo>"
+```
+
+### Manual
+
+1. Add `"dsh-question": "<npm version | github spec | link:<path>>"` to the profile's `package.json`
+   dependencies;
+2. Append `dsh-question` to `dsh.profile.bundles`;
+3. Run `pnpm install` in the profile directory.
+
+Uninstall: `dsh plugin --profile <profile> remove dsh-question`.
+
+The package carries `dsh.bundle.patch` (`cordis.patch.yml`, which inserts the `question-card` loader
+entry) and `dsh.client` (`platform: "web"`, serving `./client` → `lib/client.js`). Profiles with client
+HMR apply it live.
+
+## Language
+
+The plugin follows the DSH interface language automatically:
+
+| DSH language | Custom row prefix |
+| --- | --- |
+| 中文 | 其他： |
+| English | Other: |
+
+All other text on the card (question, options, descriptions) comes from the model and is shown as-is.
+
+## Keyboard shortcuts
+
+| Key | Action |
+| --- | --- |
+| `1`–`9` | Select the Nth option (single-select) / toggle it (multi-select) |
+| `Enter` | Run the primary footer action: submit on the last question, next otherwise |
+| `←` / `→` (or `PageUp` / `PageDown`) | Switch to the previous / next question in the same batch |
+| `Esc` | Collapse the card (same as the header collapse button; never cancels the batch) |
+
+Shortcuts only act while a question card is visible, never while focus is inside `input`,
+`textarea`, or a content-editable area, and never with `Ctrl`/`Alt`/`Cmd` held.
+
+## How it works
+
+1. **Stylesheet** (`lib/dsh-question.css`, injected as `<style data-plugin="dsh-question">`) — scoped to
+   `[data-question-key]`; hides the inline `*_description`, clamps labels, draws the circular radios,
+   the `其他/Other` prefix and the tooltip.
+2. **Interaction** (`lib/client.js`) — delegated `mouseover`/`focusin` listeners plus a `position: fixed`
+   tooltip reading the description text still present in the DOM; keyboard handling; the prefix follows
+   `<html lang>` through a `MutationObserver`.
+3. **HMR-safe** — `apply()` disposes the previous generation (`window.__DSH_QUESTION_CARD__`), so a
+   reloaded bundle never stacks listeners.
+
+## Requirements
+
+- DSH **0.2.1-rc.x** Web / Desktop client;
+- Node.js ≥ 20 only when building the bundle yourself (the published bundle is plain JavaScript).
+
+Selectors match DSH's CSS-module class **suffixes** (`_optionLabel`, `_description`, `_customRow`, …)
+and the `data-question-key` attribute, so a DSH CSS hash change is harmless — a structural UI refactor
+is not.
+
+## Development
+
+```bash
+npm run build   # src/*.js + lib/dsh-question.css -> lib/client.js
+npm run check   # node --check
+npm test        # node:test static contract tests
+```
+
+Open `dev/preview.html` in a browser for a standalone replica of the card DOM (no DSH required); hover
+an option to see the tooltip.
+
+```
+src/10-helpers.js   DOM helpers and language detection
+src/20-tooltip.js   tooltip element, stylesheet injection
+src/30-mount.js     apply(): listeners, language sync, idempotent teardown
+src/40-keys.js      keyboard shortcuts
+```
+
+## Known limitations
+
+- The custom-row prefix is Chinese or English only; other locales fall back to English.
+- Tooltip content comes from the asker's `description`; without one, only a truncated label falls back
+  to the tooltip.
+- Plan-review (`exit_plan_mode`) cards are intentionally untouched.
+- Depends on DSH's internal class suffixes and `data-question-key`; a structural refactor of the question
+  card needs selector updates.
+
+## License
+
+[MIT](LICENSE)

package/README.md

@@ -1,3 +1,132 @@
-# Temporary Holding Version
+# dsh-question
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/dsh-question.svg)](https://www.npmjs.com/package/dsh-question)
+[![license](https://img.shields.io/npm/l/dsh-question.svg)](LICENSE)
+[![ci](https://github.com/1234ab484/dsh-question/actions/workflows/ci.yml/badge.svg)](https://github.com/1234ab484/dsh-question/actions/workflows/ci.yml)
+
+给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）的提问卡片插件。
+
+`dsh-question` 把模型发起的提问渲染成一张可就地作答的卡片：选择选项、悬停查看详细说明，或者直接输入
+自己的答案。你提交之前它会一直等你，答案回传给模型后继续工作。
+
+[中文](README.md) | [English](README.en.md)
+
+![提问卡片](docs/card.png)
+
+![悬停浮层](docs/hover.png)
+
+| 单选圆钮（8×） | 多选 |
+| --- | --- |
+| ![圆钮](docs/radio-zoom.png) | ![多选](docs/multi.png) |
+
+## 功能介绍
+
+- **选项只显示重点** —— 每个选项行只留简短 label，最多两行，超出省略；
+- **悬停看详细说明** —— 鼠标悬停或键盘聚焦选项时，浮层展示完整说明；label 被截断时浮层第一行补完整 label；
+- **自由输入一行搞定** —— 自定义答案行显示「其他：」/“Other: ”并直接给输入框，不再需要铅笔图标；
+- **单选与多选** —— 单选是 26px 圆形单选框，多选保留原生方框；
+- **键盘操作** —— `1`–`9` 选择/勾选，`Enter` 触发主按钮（提交/下一题），`←`/`→` 在多题之间来回切换，`Esc` 收起卡片且不会取消整组问题；
+- **多题可来回切换** —— 一批问题一次显示一题，底部翻页按钮或 `←`/`→` 在问题间前后移动，已选草稿不丢；
+- **等你作答** —— 未提交前这一轮保持等待；倒计时、跳过、翻页等行为照常；
+- **中英文自动切换** —— 界面语言变，卡片文案跟着变，无需手动改配置。
+
+插件负责提问卡片的呈现与交互，不改变模型可见的工具约定。
+
+## 安装说明
+
+### 从 npm 安装
+
+```powershell
+dsh plugin --profile <profile> add dsh-question
+```
+
+### 从 GitHub 安装
+
+```powershell
+dsh plugin --profile <profile> add github:1234ab484/dsh-question
+```
+
+### 从本地 checkout 安装
+
+```powershell
+git clone https://github.com/1234ab484/dsh-question
+dsh plugin --profile <profile> add "link:<path-to-this-repo>"
+```
+
+### 手动安装
+
+1. 在 profile 的 `package.json` 依赖里加 `"dsh-question": "<npm 版本 | GitHub spec | link:<路径>>"`；
+2. 把 `dsh-question` 追加到 `dsh.profile.bundles`；
+3. 在 profile 目录执行 `pnpm install`。
+
+卸载：`dsh plugin --profile <profile> remove dsh-question`。
+
+包内声明了 `dsh.bundle.patch`（`cordis.patch.yml`，插入 `question-card` 这条 Loader 条目）和
+`dsh.client`（`platform: "web"`，把 `./client` 指向 `lib/client.js`）。启用了客户端 HMR 的 profile 会在线生效。
+
+## 语言
+
+插件自动跟随 DSH 的界面语言：
+
+| DSH 界面语言 | 自定义答案行前缀 |
+| --- | --- |
+| 中文 | 其他： |
+| English | Other: |
+
+卡片上的其它文字（问题、选项、说明）来自模型，按原样展示。
+
+## 键盘快捷键
+
+| 按键 | 行为 |
+| --- | --- |
+| `1`–`9` | 选中第 N 个选项（单选）/ 勾选或取消（多选） |
+| `Enter` | 触发右下角主按钮：最后一题提交，多题时下一题 |
+| `←` / `→`（或 `PageUp` / `PageDown`） | 在同一批问题里切换到上一题 / 下一题 |
+| `Esc` | 收起卡片（等同标题栏收起按钮；**不会**放弃整组问题） |
+
+快捷键只在提问卡片可见时生效；焦点在 `input`、`textarea` 或可编辑区域时不拦截；带 `Ctrl`/`Alt`/`Cmd`
+的组合键不处理。
+
+## 实现原理
+
+1. **样式层**（`lib/dsh-question.css`，以 `<style data-plugin="dsh-question">` 注入）—— 作用域限定在
+   `[data-question-key]`；隐藏行内 `*_description`、截断 label、画圆形单选框、「其他/Other」前缀和浮层。
+2. **交互层**（`lib/client.js`）—— 委托的 `mouseover`/`focusin` 监听 + `position: fixed` 浮层，读取 DOM 里
+   仍然存在的 description 文本；键盘处理；前缀通过 `MutationObserver` 跟随 `<html lang>`。
+3. **HMR 安全** —— `apply()` 先销毁上一代（`window.__DSH_QUESTION_CARD__`），热重载不叠加监听器。
+
+## 环境要求
+
+- DSH **0.2.1-rc.x** 的 Web / 桌面客户端；
+- 只有自己构建 bundle 时才需要 Node.js ≥ 20（发布出来的 bundle 是纯 JavaScript）。
+
+选择器匹配 DSH CSS Module 的**类名后缀**（`_optionLabel`、`_description`、`_customRow` 等）和
+`data-question-key` 属性，DSH 改变 CSS 哈希不影响插件；但卡片结构大改时需要更新选择器。
+
+## 开发
+
+```bash
+npm run build   # src/*.js + lib/dsh-question.css -> lib/client.js
+npm run check   # node --check
+npm test        # node:test 静态契约测试
+```
+
+浏览器打开 `dev/preview.html` 可以脱离 DSH 预览卡片 DOM（悬停选项可看浮层）。
+
+```
+src/10-helpers.js   DOM 辅助与语言判断
+src/20-tooltip.js   浮层元素、样式注入
+src/30-mount.js     apply()：监听器、语言同步、幂等销毁
+src/40-keys.js      键盘快捷键
+```
+
+## 已知限制
+
+- 自定义答案行前缀只覆盖中文和英文，其它语言回退到英文；
+- 浮层内容来自提问方的 `description`；没有 description 时，只有 label 被截断才会回退到浮层显示完整 label；
+- plan-review（`exit_plan_mode`）卡片不在改动范围内，保持原样；
+- 依赖 DSH 内部的类名后缀和 `data-question-key`，卡片结构大改时需要更新选择器。
+
+## 许可证
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# 把本插件作为一条 Loader 条目插入 profile 的组合树。
+# id 是插件在 Loader 中的稳定身份（改名会让 profile 里的旧条目失效，需要重装）；
+# name 是包名，profile 的 node_modules 里必须能解析到。
+- insert:
+    - id: question-card
+      name: dsh-question
+      config: {}