dsh-grill-first 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## 0.1.5
+
+"让人一眼看懂"版本：只有文档，没有代码改动。
+
+### 新增
+
+- **英文 README**（`README.en.md`）：面向英文用户重写的，不是逐字翻译——一句话卖点、30 秒对话演示、四档对比、配置表、兼容性与已知限制。
+- **中文 README 首屏重做**：一句话主张「Agent 不是不会做，是经常做完了你才发现不是你要的」、一段真实对话示例、四种门档位的对比表，都提到首屏。
+
+### 变更
+
+- 中英文 README 顶部互相加了语言切换链接。
+
 ## 0.1.4
 
 "真的按你确认过的意思做"版本：修掉四个"配置写了但不生效"的地方，并让询问类消息不再被当成模糊任务。

package/README.en.md

@@ -0,0 +1,167 @@
+# dsh-grill-first
+
+![tests](https://img.shields.io/badge/tests-127%20passing-brightgreen)
+![license](https://img.shields.io/badge/license-MIT-blue)
+![DSH plugin](https://img.shields.io/badge/DSH-plugin-blueviolet)
+
+> A [DSH (DeepSeek Harness)](https://github.com/deepseek-ai/dsh) plugin that **interviews you before it starts working**: vague requests get clarified first, and the main task only starts once you confirm the summary.
+
+**Agents rarely fail because they can't do the work. They fail because they do the wrong work, confidently.**
+
+[中文](./README.md) · [Install](#install) · [Configuration](#configuration) · [Known limitations](#known-limitations)
+
+## See it in 30 seconds
+
+```text
+you  optimize that page
+
+it   1) Which page? 2) "Optimize" meaning speed, style or copy?
+     3) How do we know it's done?
+
+you  the login page, mostly styling — the alignment and spacing look off
+
+it   GOAL      tidy up the login page's visuals
+     SCOPE     styling only; structure and copy stay as-is
+     CONSTRAINTS use the existing design tokens
+     ACCEPTANCE key screens don't break on mobile
+                          [ Confirm and start ]  [ Change something ]
+
+you  confirm
+
+it   (only now does it touch anything)
+```
+
+Without the plugin, the same sentence usually goes like this:
+
+```text
+you  optimize that page
+
+it   Done! I've updated the homepage copy and color scheme ✨   ← you meant the login page
+```
+
+## The four gate modes
+
+| | No plugin | `gateMode: warn` (default) | `gateMode: ask` | `gateMode: strict` |
+|---|---|---|---|---|
+| Vague request | Guesses and starts | Asks; actions not blocked | Asks; one confirmation card before acting | Asks; blocks writes and commands until confirmed |
+
+`warn` is the default so upgrading never silently freezes a workflow you already had.
+
+## How it works
+
+Every new task starts with a check, not with work:
+
+1. The model passes your request to `grill_start`.
+2. If it's missing goal / scope / constraints / acceptance criteria, the plugin asks up to 3 questions per round, 3 rounds max, each round built on your previous answer.
+3. Once the picture is clear, `grill_confirm` hands you a four-part summary (goal / scope / constraints / acceptance criteria).
+4. "Confirm" releases the task; "change something" makes it revise and ask again.
+5. One-liners and questions don't trigger any of this — nor do messages containing `直接做`, `跳过提问`, `不用问`, `skip`, `skip the questions`, `just do it`.
+
+## Install
+
+Quit any running task first. Any of these works:
+
+**Plugin marketplace (recommended)** — DSH settings → Plugins → search `dsh-grill-first`.
+
+**npm**
+
+```bash
+dsh plugin --profile <your-profile> add dsh-grill-first
+```
+
+**From source**
+
+```bash
+dsh plugin --profile <your-profile> add github:InoriMutsumi/dsh-grill-first
+```
+
+Live profiles hot-load the plugin — no restart needed (restart DSH once if it doesn't show up).
+
+## What you get
+
+- **A protocol paragraph** injected into the system prompt (~600 chars) telling the model to run `grill_start` before new work. If you can see `【开工前提问协议（grill-first）】` in the prompt, it's installed.
+- **Two tools:**
+
+| Tool | What it does |
+|---|---|
+| `grill_start` | Decides whether the request needs clarification. Returns `verdict`, `focus_hints` (what to ask), and `memory_context` (preferences you already confirmed, so it doesn't ask twice) |
+| `grill_confirm` | Hands you the four-part summary; on confirmation releases the task and saves what you confirmed |
+
+## When you don't want to be asked
+
+- Put `直接做`, `跳过提问`, `不用问`, `skip`, `skip the questions` or `just do it` in the message → it starts immediately.
+- Asks a question ("how is this plugin", "check my repos", "explain this code") → treated as a question, not a task, so nothing is clarified.
+- Or turn `enabled` off / set `gateMode: off` in the config → fully silent.
+
+## Configuration
+
+DSH settings → Plugins → dsh-grill-first, eight options:
+
+| Option | Type | Default | Meaning |
+|---|---|---|---|
+| `enabled` | boolean | `true` | Master switch. Off = no questions, no gate |
+| `gateMode` | `off` / `warn` / `ask` / `strict` | `warn` | `off` never blocks; `warn` only logs; `ask` shows one confirmation card; `strict` blocks mutating tools until confirmed |
+| `maxQuestionsPerRound` | 1–6 | `3` | Questions per round |
+| `maxRounds` | 1–10 | `3` | Max clarification rounds; on the last round `grill_start` passes the task through |
+| `intensity` | `gentle` / `standard` / `grill` | `standard` | How much detail counts as clear: `gentle` needs two dimensions, `standard` three, `grill` also requires acceptance criteria |
+| `bypassKeywords` | string[] | `["直接做","跳过提问","不用问","skip"]` | Hit any of these → skip the interview |
+| `memoryEnabled` | boolean | `true` | Enable the two-layer memory |
+| `memoryScope` | `project` / `global` | `project` | Where project context lives: in the workspace, or in the global directory shared across projects |
+
+### Editing the config
+
+The plugin page only offers an enable/disable toggle, so edit the profile's patch layer, `<profile>/cordis.patch.yml`:
+
+```yaml
+- id: dsh-grill-first
+  name: dsh-grill-first
+  config:
+    gateMode: ask
+    maxQuestionsPerRound: 3
+    maxRounds: 3
+    intensity: standard
+    memoryEnabled: true
+    memoryScope: project
+    bypassKeywords: [直接做, 跳过提问, 不用问, skip]
+```
+
+Only the keys you set are overridden; the rest keep their defaults. Config changes hot-reload, code changes need a DSH restart.
+
+## Two-layer memory
+
+Only what you actually confirmed is stored — never raw conversation, never the summary as a file.
+
+| Layer | Location | Contents |
+|---|---|---|
+| Global | `<profile>/grill-first/global.json` (falls back to `~/.dsh-grill-first/global.json`) | Standing preferences, e.g. "comments in English" |
+| Project | `<workspace>/.dsh/grill-first/memory.json` | Project background and task history (task name, summary, date; last 100 entries) |
+
+Set `memoryScope: global` to keep project context in the global directory instead — handy when you don't want a `.dsh/` folder in every repo. Next interview, `grill_start` returns this as `memory_context`, so the same question is never asked twice.
+
+## Development
+
+```bash
+npm install                 # dev dependencies (schemastery comes from the host at runtime)
+npm run build               # TypeScript → dist/
+npm test                    # build + 127 unit / end-to-end tests
+node scripts/selfcheck.mjs  # static check: Chinese JSDoc, `any` usage, spec-to-code map
+```
+
+`dist/` is committed on purpose so `dsh plugin add github:…` works without compiling on your machine. CI runs `typecheck` + tests on Node 22.
+
+## Compatibility
+
+- Peer dependency: only `@deepseek-ai/schemastery` (`^3.18.1`, shipped by the host).
+- No import of any `@deepseek-ai/dsh*` runtime package, so no `engines.dsh` and no DSH peer range to keep in sync. Verified against DSH `0.2.1-rc.2`.
+
+## Known limitations
+
+- The gate only applies to the **root agent** that talks to you. Delegated work isn't gated (but delegation tools themselves are, so a subagent can't be used to sidestep it). This is deliberate.
+- `ask` mode asks **once per task** — otherwise a task that writes 20 files would show 20 cards. Use `strict` if you want every action blocked.
+- The judge is **keyword heuristics**, not a semantic model: questions are detected by punctuation and interrogatives. Rare ambiguous sentences can be misjudged; say `直接做` or let the model call `grill_start` again to correct it.
+- The judge runs in Chinese and English only. English keywords match on word boundaries (`skip` matches `skip` and `(skip)` but not `skipList`).
+- Memory is plain local JSON, unencrypted.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/README.md

@@ -6,6 +6,46 @@
 
 > DSH（DeepSeek Harness）插件：**开工前先刨根问底**——把模糊需求问成明确需求，你在对话里点头之后，主任务才开工。
 
+**Agent 不是不会做，是经常做完了你才发现不是你要的。**
+
+[English](./README.en.md) · [安装](#安装) · [配置项](#配置项) · [已知限制](#已知限制)
+
+## 30 秒看懂
+
+```text
+你  把那个页面优化一下
+
+它  1) 是哪个页面？2) 「优化」指速度、样式还是文案？
+    3) 怎么才算优化好了？
+
+你  登录页，主要是样式，现在对齐和间距看着乱
+
+它  【目标】整理登录页视觉
+    【范围】只改样式，不动结构和文案
+    【约束】沿用现有设计规范
+    【验收标准】主要页面在移动端不错位
+                     [ 确认，按此开工 ]  [ 要改 ]
+
+你  确认
+
+它  （这时才动手）
+```
+
+不装这个插件时，同一句话大概率是这样：
+
+```text
+你  把那个页面优化一下
+它  好的，已经帮你调整了首页的文案和配色 ✨   ← 你要的是登录页
+```
+
+## 四种档位的区别
+
+| | 不装插件 | `gateMode: warn`（默认） | `gateMode: ask` | `gateMode: strict` |
+|---|---|---|---|---|
+| 任务模糊时 | 直接猜着做 | 追问；动手不拦 | 追问；动手前弹一次确认卡片 | 追问；没确认前拦截写文件、执行命令 |
+
+`warn` 是默认值：升级插件不会突然卡住你已有的工作流。
+
 ## 它解决什么问题
 
 AI 助手最常见的失败不是"不会做"，而是"做完了才发现做的不是你要的"。这个插件在**任何新任务开工前**插入一道需求澄清环节：
@@ -37,7 +77,7 @@ dsh plugin --profile <你的 profile 名> add dsh-grill-first
 **方式三：本地包 / GitHub 仓库**
 
 ```bash
-dsh plugin --profile <你的 profile 名> add /绝对路径/dsh-grill-first-0.1.3.tgz
+dsh plugin --profile <你的 profile 名> add /绝对路径/dsh-grill-first-0.1.5.tgz
 dsh plugin --profile <你的 profile 名> add github:InoriMutsumi/dsh-grill-first
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-grill-first",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "DSH 插件：开工前刨根问底——把模糊需求问成明确需求，用户确认后才放行主任务",
   "icon": "./icon.png",
   "author": "InoriMutsumi",