@linkdesk/plugin-docs 0.1.40 → 0.1.41
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -123,6 +123,10 @@ useEffect(() => {
|
|
|
123
123
|
- [ ] Each has a real handler registered pool-side (`registerCommand`), with `unregisterCommands(pluginId)` on `unmount`
|
|
124
124
|
- [ ] Buttons/menu items and the command handler call **the same** action function (not two implementations)
|
|
125
125
|
- [ ] Anything that changes state also has a **read-back** path (list/query)
|
|
126
|
+
- [ ] The reply **distinguishes three states**: done / not done but not a failure / the call itself is wrong (`reason` is a distinguishable literal)
|
|
127
|
+
- [ ] An **addressed command** (one taking a target id) that cannot find its target **refuses honestly and lists what exists** — ⛔ it never falls back to "the active one / the first one"
|
|
128
|
+
- [ ] A **read command** reports "empty" and "could not read" **separately** (⛔ never report "unknown" as an empty array)
|
|
129
|
+
- [ ] A toggle/flip command's reply carries the **value read back after the change** (`field` / `previous` / `value`)
|
|
126
130
|
- [ ] Streams have a **pull** read-back path (cursor-based — ⛔ not a subscription) plus a water-level read
|
|
127
131
|
- [ ] Self-test: install it → findable in the Command Palette → `description`/`params` visible in the command list → invoking it works **and the UI reflects it**
|
|
128
132
|
- [ ] I walked these actions through **without a mouse** (keyboard / Command Palette) and every step was reachable
|
|
@@ -143,6 +147,69 @@ useEffect(() => {
|
|
|
143
147
|
|
|
144
148
|
---
|
|
145
149
|
|
|
150
|
+
## 7. Standing discipline (established 2026-09-29)
|
|
151
|
+
|
|
152
|
+
- 🔴 **This is not a one-off delivery**: from here on, **every new feature / new plugin** must satisfy
|
|
153
|
+
"**① every user action has at least one non-mouse path; ② business actions are registered as commands, and the
|
|
154
|
+
registration meta carries `description` + `params`**". The same sentence is hard constraint 26 in the shell repo
|
|
155
|
+
(internal engineering rule, not linked here). Why: **holes grow back with each iteration** — the whole AI-friendliness
|
|
156
|
+
effort started from a hidden gate in an old feature that blocked an AI.
|
|
157
|
+
- **Two mechanical self-checks** (run them, ⛔ do not eyeball it): `npm run audit:plugin-commands`
|
|
158
|
+
(**reports, never blocks** — flags "a view is declared but there are zero commands" and "a whole batch lacks
|
|
159
|
+
`description`") · `npm run manual:build` (byte-for-byte drift gate on the host-command manual index; plugin commands
|
|
160
|
+
**do not** need to enter it — being visible to `getCommands()` at runtime is enough).
|
|
161
|
+
- **Verification is equally pointer-independent**: test commands through commands / APIs (or CLI / MCP), ⛔ never
|
|
162
|
+
"screenshot → guess coordinates → click"; for faces that exist **only under the pointer** (hover buttons), use
|
|
163
|
+
element anchoring ("grab the element, then act on the element itself") — ⛔ do not derive coordinates from window
|
|
164
|
+
position (those coordinates break under a different window layout).
|
|
165
|
+
- ⚠️ **Three pitfalls from real runs** (hit during acceptance on 2026-09-29, written down to save the next person a round):
|
|
166
|
+
1. **Registration timing** — if you only `registerCommand` when the **view component mounts**, an external AI
|
|
167
|
+
**cannot see your commands** in the command list when the view was never opened (invoking one raises `EUNKNOWN`)
|
|
168
|
+
⇒ if you can register at activate time, do not defer it to mount.
|
|
169
|
+
2. **Parameter shape** — `params` are **named**, while the execution face **originally** passed arguments **positionally**
|
|
170
|
+
⇒ a caller following the named-object form **silently did nothing** (`ok=true` with no effect). **Fixed**
|
|
171
|
+
(2026-09-29): the command bridge seam (shared by `exec` and pool-side `executeCommand`) now expands a **single
|
|
172
|
+
named object** in declared `params` order — positional spreading still works; both forms are correct. ⚠️ The
|
|
173
|
+
narrowing: **exactly one object argument** + the command **declares ≥2 `params`** + at least one key **matches**;
|
|
174
|
+
commands with ≤1 `params` are not expanded (that object is legitimately its argument).
|
|
175
|
+
3. **Return value** — when the handler **returns nothing**, an outside caller only sees the envelope's `ok:true`, so
|
|
176
|
+
"**ran but did nothing**" (target missing / precondition unmet / argument missing) and "**actually did it**" look
|
|
177
|
+
**identical** to an AI, which then has to guess via screenshots and retries. **Rule**: if a command does work,
|
|
178
|
+
**return a receipt** — done: `{ ok: true }`; **not done but not a failure**: `{ ok: true, noop: true, reason: "<literal>" }`
|
|
179
|
+
(e.g. `"single-tab"` / `"max-depth"` / target missing); **this call itself is wrong**:
|
|
180
|
+
`{ ok: false, noop: true, reason }` (e.g. missing argument / host not registered). `reason` must be a
|
|
181
|
+
**distinguishable literal**, ⛔ never a catch-all "other". The two built-in split commands already set the example —
|
|
182
|
+
**your handler's return value is the answer the AI reads**.
|
|
183
|
+
|
|
184
|
+
- 🔴 **Failure and addressing shapes** (established 2026-09-29; a standing convention alongside the three
|
|
185
|
+
pitfalls above, with precedents from the host config-write command and the serial plugin's session addressing):
|
|
186
|
+
1. **Read commands, and write commands that an outside caller addresses: bad arguments report in the payload, ⛔ never
|
|
187
|
+
by throwing.** A throw travels through the shell's `runCommand` catch → `reportError` → a **user-visible red toast**,
|
|
188
|
+
and "the caller wrote a bad argument" is something **the user can do nothing about** right then (a slap in the face
|
|
189
|
+
helps nobody). The uniform shape is `{ ok: false, noop: true, reason: "<literal>", error: "<one sentence for humans>" }`
|
|
190
|
+
— `reason` for code to branch on, `error` for humans/AI to read; when reporting "not found", **list what exists**
|
|
191
|
+
(⛔ do not make the caller ask again). ⚠️ **Be honest about the split, do not flatten it**: the older batch of
|
|
192
|
+
commands that "a human can click in a menu / context menu" (arguments filled in by the UI, so a bad argument can
|
|
193
|
+
only be a real bug) **keep throwing**. Both shapes coexisting is **intentional**: ⛔ do not convert old commands to
|
|
194
|
+
payloads, and do not write new ones as throws.
|
|
195
|
+
2. **If you name it, you must know the name**: a command taking a target id (`sessionId` / `tabId` / `key` / `uri` …)
|
|
196
|
+
**must hit when given one** — on a miss return `{ ok: false, noop: true, reason: "bad-…", error }` and list the
|
|
197
|
+
**available** candidates, ⛔ **never silently fall back** to "the active one / the first one": that produces
|
|
198
|
+
"**the books look fine, but a different object was changed**" — exactly the shape this effort keeps eradicating
|
|
199
|
+
(and the hardest to debug when several objects coexist). Only the default (no id given) uses the old
|
|
200
|
+
"active → first" semantics.
|
|
201
|
+
3. **Read commands: empty ≠ failure, and "cannot read" ≠ empty.** An empty read honestly returns
|
|
202
|
+
`{ ok: true, count: 0, … }`; an unreadable one (underlying error / that face not registered) returns
|
|
203
|
+
`{ ok: false, noop: true, reason: "read-failed" }` with the cause. "There is none" and "I do not know" call for
|
|
204
|
+
**opposite** responses (plug a device / change arguments vs. check drivers / permissions); blending them is the
|
|
205
|
+
"answered nothing but looked like an answer" defect — the very shape this effort keeps eradicating.
|
|
206
|
+
4. **Toggle/flip commands return the value read back**: `{ field, previous, value }` (`value` read **after** the change).
|
|
207
|
+
⛔ Do not let the caller infer state from the command title, the schema default, or its own intent — especially since
|
|
208
|
+
**titles change with state** (dynamic titles); using one as a reading is **guaranteed wrong** (that is precisely how
|
|
209
|
+
the external AI misjudged the 0.2.25 retest).
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
146
213
|
**Related:** [03-contributes-spec](03-contributes-spec.md) §3.1 (every `contributes.commands` field) ·
|
|
147
214
|
[07-plugin-to-plugin-communication](07-plugin-to-plugin-communication.md) (calling another plugin's command) ·
|
|
148
215
|
[14-data-pipeline-command-conventions](14-data-pipeline-command-conventions.md) (naming conventions for data pipeline commands)
|
|
@@ -125,6 +125,10 @@ useEffect(() => {
|
|
|
125
125
|
- [ ] **视图态命令**(在视图 `mount` 里才注册的那些)也写进了 `contributes.commands`——没开视图时 AI 只能从声明面看到它
|
|
126
126
|
- [ ] 按钮/菜单项与命令 handler 调**同一个**动作函数(不是两份实现)
|
|
127
127
|
- [ ] 改了状态的东西,另有**读回来**的路(列表/查询)
|
|
128
|
+
- [ ] 命令回执**三态**分得开:做了 / 没做但不是故障 / 这次调用有问题(`reason` 是可分辨的字面量)
|
|
129
|
+
- [ ] **点名的命令**(带目标 id)找不到目标时**如实拒并列出可用清单**,⛔ 没回退到「活跃/第一个」
|
|
130
|
+
- [ ] **读命令**把「空读数」与「读不出来」分开报(⛔ 不把「不知道」报成空数组)
|
|
131
|
+
- [ ] 翻转/开关类命令的回执带**改完读回来的值**(`field`/`previous`/`value`)
|
|
128
132
|
- [ ] 流式数据的读回路是**游标式拉取**(⛔ 不是订阅)+ 一条水位读数
|
|
129
133
|
- [ ] 自测:装进软件 → 命令面板里搜得到 → 命令清单里看得见 `description`/`params` → 调一次生效**且界面同步变化**
|
|
130
134
|
- [ ] 我在**没有鼠标**的情况下走过一遍这些动作(键盘/命令面板),确认每一步都到得了
|
|
@@ -153,6 +157,25 @@ useEffect(() => {
|
|
|
153
157
|
2. **参数形状**——`params` 是**具名**的,执行面**原先**只按**位置**透传 ⇒ 调用方照「具名对象」调会**静默无效**(`ok=true` 却没做事)。**已修**(2026-09-29):命令桥那条缝(`exec` 与池内 `executeCommand` 共用)现在把**单个具名对象**按 `params` 声明顺序展开——位置平铺照旧可用,两种写法都对。⚠️ 展开的窄口:**恰好 1 个对象实参** + 该命令**声明了 ≥2 个 `params`** + 键名**至少命中一个**;`params` ≤1 的命令不展开(那个对象本就是它的合法实参)。
|
|
154
158
|
3. **返回值**——handler **什么都不回**时,外部只看得到信封的 `ok:true`,于是「**跑了但没做事**」(目标不存在 / 前提不成立 / 参数缺失)与「**真做了**」在 AI 眼里**同形**,只能靠截图与反复试探去猜。**规矩**:命令要做事就**回一张回执**——做成了 `{ ok: true }`;**没做事但不是故障**回 `{ ok: true, noop: true, reason: "<字面量>" }`(例如 `"single-tab"` / `"max-depth"` / 目标不存在);**这次调用本身有问题**回 `{ ok: false, noop: true, reason }`(例如缺参数 / 宿主没注册)。`reason` 必须是**可分辨的字面量**,⛔ 不用「其它」兜底。壳内置的两条分屏命令已按此立样板——**你的 handler 返回值就是 AI 读到的答案**。
|
|
155
159
|
|
|
160
|
+
- 🔴 **失败与寻址的形状**(2026-09-29 立;与上面三条并列的常驻约定,判例来自宿主设置写入命令与串口插件的会话寻址命令):
|
|
161
|
+
1. **读命令、以及「由外部点名」的写命令:坏参出在载荷里,⛔ 不抛异常**。抛出去经壳的 `runCommand` catch →
|
|
162
|
+
`reportError` → 弹一张**用户可见的红色 toast**,而「调用方参数写错」这件事**用户当场什么也做不了**(糊脸无益)。
|
|
163
|
+
统一形状 `{ ok: false, noop: true, reason: "<字面量>", error: "<给人读的一句>" }`——`reason` 给代码分支,
|
|
164
|
+
`error` 给人/给 AI 读懂;报「找不到」时**顺手把现有哪些列出来**(⛔ 别让调用方再来问一次)。
|
|
165
|
+
⚠️ **诚实分档、别一刀切**:老一批「人在菜单/右键里点得到」的命令(实参由界面填,坏参只可能是真 bug)
|
|
166
|
+
**保留抛异常**。两种形状并存是**有意**的:⛔ 别顺手把老命令改成载荷,也别把新命令写成抛异常。
|
|
167
|
+
2. **点名就要认名字**:带目标 id 的命令(`sessionId` / `tabId` / `key` / `uri` …)**给了就必须命中**——
|
|
168
|
+
找不到回 `{ ok: false, noop: true, reason: "bad-…", error }` 并列出**可用清单**,
|
|
169
|
+
⛔ **不静默回退**到「活跃的那个 / 第一个」:那会造出「**账面无错、其实改了别的对象**」——
|
|
170
|
+
本系列反复消灭的就是这个形状(多对象并存时它最难查)。缺省(没给 id)才走「活跃 → 第一个」的老语义。
|
|
171
|
+
3. **读命令:空 ≠ 失败,问不出来 ≠ 空**。空读数如实回 `{ ok: true, count: 0, … }`;
|
|
172
|
+
读不出来(底层报错 / 那个面没注册)回 `{ ok: false, noop: true, reason: "read-failed" }` 并带上原因——
|
|
173
|
+
「没有」与「不知道」的处置**相反**(前者插设备/换参数,后者查驱动/权限),糊成一种就是
|
|
174
|
+
「答不上却看着像答了」——本系列反复消灭的就是这个形状。
|
|
175
|
+
4. **翻转/开关类命令的回执带回读值**:给 `{ field, previous, value }`(`value` 是**改完读回来的**)。
|
|
176
|
+
⛔ 别让调用方从命令标题、schema 默认值或自己的意图反推状态——尤其**标题会随状态变**(动态标题那类),
|
|
177
|
+
把它当读数用**必错**(外部 AI 0.2.25 复测里那条误判就是这么来的)。
|
|
178
|
+
|
|
156
179
|
---
|
|
157
180
|
|
|
158
181
|
**相关:** [03-插件contributes规范](03-插件contributes规范.md) §3.1(`contributes.commands` 全字段)·
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@linkdesk/plugin-docs",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.41",
|
|
4
4
|
"description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"files": [
|