dsh-m 0.9.91 → 0.9.93

package/CHANGELOG.md

@@ -8,6 +8,18 @@ The full release history of dsh-m, maintained bilingually: **Chinese first, Engl
 
 ## 中文
 
+### 0.9.93 重构：装后守卫线格式收敛至 InstallGuardError.toWire——加守卫字段编辑点 8 → 2（纯重构，线格式语义零变化）
+
+- **需求（2026-10-16 架构巡查摩擦点 3，巡查首推）**：`InstallGuardError` → 线格式的投影在手写 5 处逐字重复（host-api 409 payload / tools install+upgrade 两臂 / cli install+upgrade 两臂）+ client 再拼一次——加一个守卫字段要碰 8 处（类 + 5 投影 + client 读取 + 测试），`repairBasis` 后加时各点手补已实证过一次复发。
+- **方案**：产地方法 `toWire(): InstallGuardWire`（随类导出接口 + `GuardViolation` re-export）成为 6 字段共享线格式单一事实源；五处投影改一行展开（信封差异留在各端：host-api `ok/error`、tools `ok/guard/message`、cli 裸 JSON），`repairBasis` undefined 时键不存在的语义移入方法本体。加字段编辑点降为 2（类+toWire 一处、client 读取一处——浏览器边界不能 import core，防御性拼装留守，如实注记）。自觉差异注记：tools 信封键序 kind/message 交换（JSON 键序对消费方无语义，全 tests/ 无原始 JSON 键序钉）。
+- **验证**：全量 1530 测试全绿（新增 toWire 三钉例：六字段齐/repairBasis 键缺席/键序；新增 host-api dispatcher 409 钉例补 host-api 投影零测试覆盖的缺口；tools 两臂 execute 钉例零迁移）、typecheck 零错误；收敛锚 `repairBasis ? { repairBasis: … }` 三文件 5 → 0（兼证无第 6 处投影）；实施计划经两轮独立评审四项收敛 + 执行评审两轮（含 A1 钉例独立成 describe）记录在 `docs/plans/2026-10-17-install-guard-towire-implementation-plan.md`。
+
+### 0.9.92 修复+重构：三端市场查询文法统一（market-query 单一入口）——CLI 非法 category 吞错修复
+
+- **需求（2026-10-16 实测）**：`dshm search --category <非法>` 静默返回「没有匹配的收录条目」+ exit 0，而同输入 GUI 得 400、agent 工具显式报错——「合并市场」词条承诺的「三端同源同语义」被 CLI 打破；根因是分类 slug 正则、source/offset/limit 解析、精选标签表在三端各持一份拷贝（正则 ×3、解析 ×3、标签表 ×2、deadline 常量 ×2），CLI 的拷贝漏了 category 校验。
+- **方案**：新模块 `src/core/market-query.ts`（GLOSSARY「市场查询文法」）作为三端共享文法单一事实源——单一入口 `parseMarketQueryInput(raw, policy)` 吃下 category（精选五桶 ∪ 社区 slug，trim 后校验与透传）/source（三值枚举）/limit（floor 先行 + 各端 policy：GUI 96/32、tools/CLI 80/10）/offset，文法违规 throw `MarketQueryError`（消息逐字节沿用既有文案），各端一行信封映射（host-api 400 / tools throw 直飞 / CLI 经 dispatch 统一 catch `错误：` + exit 1）；顺手单源化 slug 正则（含目录适配层第 3 份）、精选标签表（以 registry `CATEGORIES` 为键集基准 + 漂移守卫测试）、deadline 常量；CLI help 的 category 列表同步为现行策展五桶（旧值为 0.9.16 前残留）。自觉差异注记：① tools limit 的 (1,80) 区间小数今日由 core `clampLimit` 隐式 floor，改后在入口显式 floor（floor 位置前移，值域逐点相同，输出对象不含 limit 字段）；② CLI category/source 改为 trim 后校验（对齐 host-api/tools，`' self-dev '` 今日匹配不到任何条目、`--source ' all '` 今日报非法，改后均按 trim 值正常判定）；③ 双违例请求报错归属顺序统一 category → source（单违例逐字节不变）。
+- **验证**：全量 1526 测试全绿（新增 market-query 文法矩阵 18 例 + 标签键集 ≡ CATEGORIES 漂移守卫 + CLI 非法 category/非法 source 回归钉例；既有「非法分类/非法 source」锚零迁移）、typecheck 零错误；真机 `node lib/cli.js search --category '非法分类!!'` → stderr `错误：非法分类: 非法分类!!（需精选分类或 [a-z0-9-]{1,32} slug）` + exit 1（校验先于任何网络调用）；实施计划与 grill 十决议、独立评审三轮 15 项收敛记录在 `docs/plans/2026-10-16-market-query-intake-implementation-plan.md`。
+
 ### 0.9.91 优化：设置页三卡行 4:7:3 → 4:7:4——「社区清单」与「关于」等宽
 
 - **需求（2026-10-16，主人真机反馈）**：宽屏/全屏下设置页三卡行左右不对称——「社区清单」（4fr）与「关于」（3fr）宽度不一致，视觉失衡。
@@ -643,6 +655,18 @@ The full release history of dsh-m, maintained bilingually: **Chinese first, Engl
 
 ## English
 
+### Refactor in 0.9.93 — post-install guard wire format converged onto InstallGuardError.toWire; adding a guard field now touches 8 → 2 points (pure refactor, zero wire-format semantic change)
+
+- **Need (2026-10-16 architecture walk, friction point 3, the walk's top pick)**: the `InstallGuardError` → wire-format projection was hand-written verbatim in 5 places (host-api 409 payload / tools install+upgrade arms / cli install+upgrade arms) plus one more assembly in the client — adding a guard field meant touching 8 points (class + 5 projections + client read + tests); the later addition of `repairBasis` had already demonstrated the recurrence once.
+- **Approach**: a source method `toWire(): InstallGuardWire` (interface exported alongside the class, plus a `GuardViolation` re-export) becomes the single source of the shared 6-field wire format; the five projections become one-line spreads (envelope differences stay per-end: host-api `ok/error`, tools `ok/guard/message`, cli bare JSON), and the "repairBasis key absent when undefined" semantics move into the method body. Adding a field now touches 2 points (class+toWire, and the client read — the browser bundle cannot import core modules, so its defensive assembly stays, honestly noted). Deliberate delta: the tools envelope swaps key order between kind/message (JSON key order carries no consumer semantics; no raw-JSON key-order pins exist across tests/).
+- **Verification**: full suite 1530 green (three new toWire pins: six fields / repairBasis key absence / key order; a new host-api dispatcher 409 pin closing the "host-api projection had zero test coverage" gap; tools-arm execute pins migrated zero), typecheck clean; the convergence anchor `repairBasis ? { repairBasis: … }` went 5 → 0 across the three files (also proving there is no 6th projection); plan review (two rounds, four findings) and execution review (two rounds, including A1 extracting the pin into its own describe) recorded in `docs/plans/2026-10-17-install-guard-towire-implementation-plan.md`.
+
+### Fix + refactor in 0.9.92 — unified three-end market query intake (market-query single entry); CLI invalid-category silent swallow fixed
+
+- **Need (2026-10-16, reproduced live)**: `dshm search --category <invalid>` silently printed "no matching entries" and exited 0, while the same input gets a 400 from the panel API and an explicit error from the agent tool — breaking the "same source, same semantics across GUI / tools / CLI" promise. Root cause: the category slug regex, source/offset/limit parsing, and the curated label map each had per-end copies (regex ×3, parsing ×3, labels ×2, deadline constants ×2), and the CLI copy lacked category validation.
+- **Approach**: new module `src/core/market-query.ts` (GLOSSARY "Market Query Intake") is the single source of the shared grammar — one entry point `parseMarketQueryInput(raw, policy)` covers category (curated five ∪ community slug, validate-and-pass trimmed), source (three-value enum), limit (floor-first + per-end policy: GUI 96/32, tools/CLI 80/10), and offset; grammar violations throw `MarketQueryError` with byte-identical legacy messages, and each end maps to its own envelope (HTTP 400 / thrown tool error / CLI dispatch catch `错误：` + exit 1). Also single-sourced: the slug regex (including the catalog adapter's third copy), the curated label map (keyed off registry `CATEGORIES` with a drift-guard test), and the deadline constants; the CLI help category list now shows the current curated five (the old list was a pre-0.9.16 leftover). Deliberate deltas: (1) tools' in-range fractional limits were implicitly floored by core `clampLimit`; the floor now happens explicitly at intake (same values pointwise; output objects carry no limit field); (2) CLI category/source are now validated after trimming, matching host-api/tools (`' self-dev '` used to match nothing and `--source ' all '` used to error); (3) dual-violation requests now report category before source (single-violation messages byte-identical).
+- **Verification**: full suite 1526 green (18 new grammar-matrix cases + label-keys ≡ CATEGORIES drift guard + CLI invalid-category/invalid-source regression pins; existing "非法分类/非法 source" anchors migrated zero), typecheck clean; live `node lib/cli.js search --category '非法分类!!'` → stderr `错误：非法分类: 非法分类!!（需精选分类或 [a-z0-9]{1,32} slug）` + exit 1 (validation precedes any network call); plan, grill decisions, and the three-round 15-item independent review live in `docs/plans/2026-10-16-market-query-intake-implementation-plan.md`.
+
 ### Polish in 0.9.91 — settings three-card row 4:7:3 → 4:7:4: Community and About equal width
 
 - **Need (2026-10-16, live feedback)**: on wide/fullscreen the settings three-card row was asymmetric — Community (4fr) and About (3fr) had different widths.

package/lib/cli.js

@@ -11,21 +11,15 @@ import { runDoctor } from './core/doctor.js';
 import { readLauncherPackageVersion } from './core/dsh-version.js';
 import { webProfileDir, desktopProfileDir } from './core/env.js';
 import { loadRegistry } from './core/registry.js';
+import { parseMarketQueryInput, PRIMARY_CATEGORY_LABELS, SEARCH_CORE_DEADLINE_MS, INSTALLED_CORE_DEADLINE_MS } from './core/market-query.js';
 import { COMMUNITY_CATEGORY_LABELS } from './core/community.js';
 import { scheduleRestart } from './core/restart.js';
 import { upgradeEffectLine } from './core/activation.js';
 import { pathToFileURL } from 'node:url';
 import { realpathSync, existsSync } from 'node:fs';
-/** 分类中文标签（0.7.0 Task 6；0.9.16 策展五桶）：精选策展桶本地表 + 社区已知标签单一事实源；未知 slug 原样。 */
-const CLI_CATEGORY_LABELS = {
-    essentials: '装机必备',
-    'cui-picks': '崔添翼精选',
-    'self-dev': 'iasi自研',
-    'tencent-lighthouse': '腾讯轻量云专区',
-    watchlist: '观察区',
-};
+/** 分类中文标签（0.9.16 策展五桶）：精选桶单一事实源 market-query PRIMARY_CATEGORY_LABELS + 社区已知标签单一事实源；未知 slug 原样。 */
 function categoryLabelOf(category) {
-    return CLI_CATEGORY_LABELS[category] ?? COMMUNITY_CATEGORY_LABELS[category] ?? category;
+    return PRIMARY_CATEGORY_LABELS[category] ?? COMMUNITY_CATEGORY_LABELS[category] ?? category;
 }
 function parseArgs(argv) {
     const cmd = argv[0] || 'help';
@@ -59,9 +53,7 @@ function cliConfig() {
         communityCatalogPin: process.env.DSHM_COMMUNITY_CATALOG_PIN || undefined,
     };
 }
-/** 搜索工具 deadline 对齐（Task 7）：CLI 无请求 signal，deadline 44s 与工具侧一致。 */
-const SEARCH_CORE_DEADLINE_MS = 44_000;
-const INSTALLED_CORE_DEADLINE_MS = 60_000;
+/** 搜索工具 deadline 对齐（Task 7）：CLI 无请求 signal，两个 core deadline 常量单源于 market-query（0.9.92，与工具侧共用）。 */
 /** latestErrorCode → 安全化原因（与 tools.ts 同表；CLI 终端呈现）。 */
 function latestErrorCodeReason(code) {
     switch (code) {
@@ -131,7 +123,7 @@ const HELP = `dshm — DSH Marketplace（DSH 插件市场：精选策展 + 社
 用法：dshm <命令> [参数]
 
 只读命令：
-  dshm search [关键词] [--query 关键词] [--category market|tools|ui|search|other|<社区slug>] [--source primary|community|all] [--limit N] [--offset N]
+  dshm search [关键词] [--query 关键词] [--category essentials|cui-picks|self-dev|tencent-lighthouse|watchlist|<社区slug>] [--source primary|community|all] [--limit N] [--offset N]
                                         （首个位置参数等价 --query，--query 缺值时也回退它，多余位置参数忽略；source 分区：community=社区目录 4000+ 条 / primary=精选策展 / all=默认；limit 默认 10；offset 翻页）
   dshm list                          列出 web profile 已装插件（含市场标注/可升级）
   dshm outdated                      检查已装插件的最新版本
@@ -198,24 +190,18 @@ async function runCliDispatch(argv, deps, io) {
             out(HELP);
             return 0;
         case 'search': {
-            // metadata-only：不构造全量 latest；source/offset/limit 直接交给 core（0.7.0 Task 6：与工具同语义）；
+            // metadata-only：不构造全量 latest；0.9.92 三端查询文法：category/source/limit/offset 经
+            // market-query 单一入口归一（与 host-api/工具同源同语义）；文法违规 throw 直飞 dispatch 统一
+            // catch（`错误：${msg}` + exit 1，与此前 source 内联报错输出逐字节同款）——非法 category
+            // 自此显式报错（≤0.9.91 静默空结果吞错，回归钉例在 cli-search.test.mjs）。
             // 双源判定：主清单 unavailable 但社区有条目 → 照常出页（Q42）；两层皆不可用 → exit 1
-            const sourceRaw = typeof flags.source === 'string' ? flags.source : '';
-            if (sourceRaw !== '' && sourceRaw !== 'primary' && sourceRaw !== 'community' && sourceRaw !== 'all') {
-                err(`错误：非法 source: ${sourceRaw}（需 primary/community/all）`);
-                return 1;
-            }
-            const source = sourceRaw === '' ? 'all' : sourceRaw;
-            const limitRaw = Number(flags.limit);
-            const limit = Number.isFinite(limitRaw) && limitRaw > 0 ? Math.min(80, Math.max(1, Math.floor(limitRaw))) : 10;
-            const offsetRaw = Number(flags.offset);
-            const offset = Number.isFinite(offsetRaw) && offsetRaw > 0 ? Math.floor(offsetRaw) : 0;
+            const intake = parseMarketQueryInput({ category: flags.category, source: flags.source, limit: flags.limit, offset: flags.offset }, { limitMax: 80, limitDefault: 10 });
             const result = await d.listMarket(cfg, {
                 query: typeof flags.query === 'string' ? flags.query : positionals[0],
-                category: typeof flags.category === 'string' ? flags.category : null,
-                source,
-                offset,
-                limit,
+                category: intake.category,
+                source: intake.source,
+                offset: intake.offset,
+                limit: intake.limit,
                 withLatest: false,
                 namespace: 'cli',
                 deadlineMs: SEARCH_CORE_DEADLINE_MS,
@@ -241,6 +227,7 @@ async function runCliDispatch(argv, deps, io) {
                 out(`  ${it.description}`);
             }
             const shown = result.items.length;
+            const offset = intake.offset;
             const nextOffset = offset + shown < result.total ? offset + shown : null;
             const s = result.registryState;
             out(`\n来源：${registrySourceLabel(s.source)}${s.stale ? '（缓存）' : ''} · 更新：${s.fetchedAt ?? '—'} · 共 ${result.total} 条`);
@@ -345,7 +332,7 @@ async function runCliDispatch(argv, deps, io) {
             }
             catch (e) {
                 if (e instanceof InstallGuardError) {
-                    err('[⛔ 装后守卫拦截] ' + JSON.stringify({ kind: e.kind, violations: e.violations, compensation: e.compensation, needsRestart: e.needsRestart, restartSafe: e.restartSafe, ...(e.repairBasis ? { repairBasis: e.repairBasis } : {}) }));
+                    err('[⛔ 装后守卫拦截] ' + JSON.stringify(e.toWire()));
                     err(e.message);
                     err(e.restartSafe ? '可以重启 DSH Web：dshm restart --yes' : '修复后再重启（不要现在重启）。');
                     return 1;
@@ -370,7 +357,7 @@ async function runCliDispatch(argv, deps, io) {
             }
             catch (e) {
                 if (e instanceof InstallGuardError) {
-                    err('[⛔ 装后守卫拦截] ' + JSON.stringify({ kind: e.kind, violations: e.violations, compensation: e.compensation, needsRestart: e.needsRestart, restartSafe: e.restartSafe, ...(e.repairBasis ? { repairBasis: e.repairBasis } : {}) }));
+                    err('[⛔ 装后守卫拦截] ' + JSON.stringify(e.toWire()));
                     err(e.message);
                     err(e.restartSafe ? '可以重启 DSH Web：dshm restart --yes' : '修复后再重启（不要现在重启）。');
                     return 1;

package/lib/core/community-adapter.js

@@ -7,6 +7,7 @@
  * 本体，仅随 CommunityEntry 透传、由市场层展示（Q44：卡片不打标，详情折叠区才展示）。
  */
 import { createHash } from 'node:crypto';
+import { COMMUNITY_SLUG_RE } from './market-query.js';
 /** 与主清单 v1 同款约束（registry.ts MAX_ID / ID_RE / NPM_RE / GITHUB_RE 同语义，锚定不漂移）。 */
 const MAX_ID = 64;
 const MAX_DESCRIPTION = 500;
@@ -14,8 +15,6 @@ const ID_ILLEGAL_RE = /[^a-z0-9._-]+/g;
 const ID_LEADING_ILLEGAL_RE = /^[._-]+/;
 const NPM_SHAPE_RE = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
 const GITHUB_SHAPE_RE = /^[A-Za-z0-9][A-Za-z0-9-]*\/[A-Za-z0-9._-]+$/;
-/** 社区开放分类的安全 slug（计划 Task 4 契约；原生值保留不转译，Q40）。 */
-const COMMUNITY_CATEGORY_RE = /^[a-z0-9-]{1,32}$/;
 const HASH_SUFFIX_LEN = 8;
 const TRUNCATED_BODY_LEN = MAX_ID - (HASH_SUFFIX_LEN + 1);
 function isBlank(v) {
@@ -109,7 +108,8 @@ export function adaptCommunityCatalog(catalog) {
         }
         const name = raw.name.trim();
         const owner = raw.owner.trim();
-        if (typeof raw.category !== 'string' || !COMMUNITY_CATEGORY_RE.test(raw.category)) {
+        // 社区分类安全 slug：正则单源于 market-query（0.9.92），与三端查询文法同一文法规则
+        if (typeof raw.category !== 'string' || !COMMUNITY_SLUG_RE.test(raw.category)) {
             skippedDirty += 1;
             continue;
         }

package/lib/core/host-api.js

@@ -19,7 +19,7 @@ import { isNewerVersion, npmLatest, npmPackumentReadme } from './versions.js';
 import { getCommunitySummary } from './community.js';
 import { RegistryConfigError } from './registry-controller.js';
 import { checkRegistryEntries } from './registry-check.js';
-import { CATEGORIES } from './registry.js';
+import { parseMarketQueryInput, MarketQueryError } from './market-query.js';
 import { servingPort, scheduleRestart } from './restart.js';
 import { togglePlugin, ToggleError } from './toggle.js';
 import { IncompatibleError } from './compat-check.js';
@@ -39,8 +39,6 @@ class ApiProtocolError extends Error {
     }
 }
 const BODY_MAX_BYTES = 1 << 20;
-/** 社区开放分类安全 slug（计划 Task 6；与适配层 COMMUNITY_CATEGORY_RE 同语义） */
-const COMMUNITY_SLUG_RE = /^[a-z0-9-]{1,32}$/;
 function readBody(req, maxBytes = BODY_MAX_BYTES) {
     return new Promise((resolve, reject) => {
         const chunks = [];
@@ -168,18 +166,14 @@ function errorStatus(err) {
         return { status, payload: { ok: false, error: err.message, code: err.code } };
     }
     if (err instanceof InstallGuardError) {
-        // 装后守卫拦截（M2 Task 3）：结构化投影含 needsRestart/restartSafe/kind——GUI 一键重启只读 restartSafe
+        // 装后守卫拦截（M2 Task 3）：结构化投影含 needsRestart/restartSafe/kind——GUI 一键重启只读 restartSafe；
+        // 0.9.93 起线格式单源于 toWire（信封 ok/error 本端自拼）
         return {
             status: 409,
             payload: {
                 ok: false,
                 error: err.message,
-                kind: err.kind,
-                violations: err.violations,
-                compensation: err.compensation,
-                needsRestart: err.needsRestart,
-                restartSafe: err.restartSafe,
-                ...(err.repairBasis ? { repairBasis: err.repairBasis } : {}),
+                ...err.toWire(),
             },
         };
     }
@@ -363,30 +357,21 @@ export function createApiDispatcher(ctx) {
                     // GUI policy：忽略客户端 withLatest，固定 true；limit clamp 1..96、缺省 32
                     // （0.7.0 Task 7 探测预算决策：96 为 opt-in 页大小，0.9.28 起默认 32 仍低于 0.6.x 默认 50 的探测负载；
                     //  最坏情况被 core 60s deadline 框死为 latestError，不阻塞列表，Q46 不动）
-                    const limitRaw = Number(body.limit);
-                    const limit = Number.isFinite(limitRaw) && limitRaw > 0 ? Math.min(96, Math.max(1, Math.floor(limitRaw))) : 32;
-                    const offsetRaw = Number(body.offset);
-                    const offset = Number.isFinite(offsetRaw) && offsetRaw > 0 ? Math.floor(offsetRaw) : 0;
-                    // category：策展五桶 + 社区开放 slug（非法 slug → 400，不静默吞）
-                    const categoryRaw = typeof body.category === 'string' ? body.category.trim() : '';
-                    let category = null;
-                    if (categoryRaw !== '') {
-                        if (CATEGORIES.includes(categoryRaw) || COMMUNITY_SLUG_RE.test(categoryRaw)) {
-                            category = categoryRaw;
-                        }
-                        else {
-                            throw new ApiProtocolError(400, `非法分类: ${categoryRaw}（需精选分类或 [a-z0-9-]{1,32} slug）`);
-                        }
+                    // 0.9.92 三端查询文法：category/source/limit/offset 经 market-query 单一入口归一（与 tools/CLI
+                    // 同源同语义）；双违例顺序统一 category → source → 端本地参数（红线 #6 注记）。
+                    let intake;
+                    try {
+                        intake = parseMarketQueryInput({ category: body.category, source: body.source, limit: body.limit, offset: body.offset }, { limitMax: 96, limitDefault: 32 });
+                    }
+                    catch (e) {
+                        if (e instanceof MarketQueryError)
+                            throw new ApiProtocolError(400, e.message);
+                        throw e;
                     }
                     // source 分区 + sort（0.7.0 Task 7）：非法值 400（不静默吞）；primaryOnly 已删除——显式拒绝而非静默忽略（审计 #8）
                     if (body.primaryOnly !== undefined) {
                         throw new ApiProtocolError(400, '参数 primaryOnly 已删除：改用 source（primary/community/all）');
                     }
-                    const sourceRaw = typeof body.source === 'string' ? body.source.trim() : '';
-                    if (sourceRaw !== '' && sourceRaw !== 'primary' && sourceRaw !== 'community' && sourceRaw !== 'all') {
-                        throw new ApiProtocolError(400, `非法 source: ${sourceRaw}（需 primary/community/all）`);
-                    }
-                    const source = sourceRaw === '' ? 'all' : sourceRaw;
                     let sort;
                     if (body.sort !== undefined && body.sort !== null) {
                         const s = body.sort;
@@ -405,14 +390,14 @@ export function createApiDispatcher(ctx) {
                     }
                     const result = await d.listMarket(cfg(), {
                         query: strArg(body, 'query'),
-                        category,
-                        source,
+                        category: intake.category,
+                        source: intake.source,
                         sort,
                         // 0.9.26：GUI 跨区搜索精选稳定前置（listMarket 内部仅在 source='all' 且 query 非空时生效）。
                         // 本参数仅 GUI 通道携带——tools/CLI 走各自调用面不传，搜索排序三端同序不变。
                         curatedFirst: true,
-                        offset,
-                        limit,
+                        offset: intake.offset,
+                        limit: intake.limit,
                         force: boolArg(body.force),
                         withLatest: true,
                         probeMode: probeModeRaw,

package/lib/core/market-query.js

@@ -0,0 +1,70 @@
+/**
+ * 市场查询文法（GLOSSARY「市场查询文法」）：三端（面板 API / agent 工具 / CLI）市场查询
+ * 参数的共享校验与归一模块——「合并市场」条目「三端同源同语义」承诺的执行机制。
+ *
+ * 单一入口 parseMarketQueryInput 一次吃下 {category, source, limit, offset}，文法违规
+ * throw MarketQueryError（消息即契约，逐字节沿用 host-api/tools 既有文案，测试锚零迁移）；
+ * 各端 policy（limitMax / limitDefault）表达 channel 差异（GUI 96/32，tools/CLI 80/10）。
+ *
+ * 环纪律：本模块 import 白名单仅 ./registry.js——community → merged-market →
+ * community-adapter 已是值链，adapter 接入本模块后再值引用 community 即成环。
+ * categoryLabelOf 的社区段合并（?? COMMUNITY_CATEGORY_LABELS[cat]）因此留在 tools/cli 各一行。
+ *
+ * 不入本模块（grill D1）：sort/probeMode/force/primaryOnly（仅 GUI 暴露）、query 字符串
+ * （三端语义不同：host-api strArg 会 trim、tools 不 trim、cli 位置参数合并在前）。
+ */
+import { CATEGORIES } from './registry.js';
+/** 社区分类 slug 文法（单一事实源；host-api/tools/cli/community-adapter 共用）。 */
+export const COMMUNITY_SLUG_RE = /^[a-z0-9-]{1,32}$/;
+/** 精选五桶中文标签（键集 ≡ registry CATEGORIES，market-query.test.mjs 漂移守卫钉住）。 */
+export const PRIMARY_CATEGORY_LABELS = {
+    essentials: '装机必备',
+    'cui-picks': '崔添翼精选',
+    'self-dev': 'iasi自研',
+    'tencent-lighthouse': '腾讯轻量云专区',
+    watchlist: '观察区',
+};
+/** 三端查询接线策略常量（原 tools.ts / cli.ts 双份字面量收敛；0.9.92 起单源）。 */
+export const SEARCH_CORE_DEADLINE_MS = 44_000;
+export const INSTALLED_CORE_DEADLINE_MS = 60_000;
+/** 文法违规错误：消息即契约（各端映射自身信封：400 / throw 直飞 / stderr+exit 1），无 code 字段（YAGNI）。 */
+export class MarketQueryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MarketQueryError';
+    }
+}
+/**
+ * 归一文法（错误检查顺序 category → source，红线 #6 双违例注记）：
+ * - category：非字符串或 trim 后为空 → null；精选五桶（registry CATEGORIES）∪ 社区 slug → trim 后值；
+ *   否则 throw `非法分类: …`
+ * - source：非字符串或 trim 后为空 → 'all'；primary/community/all → trim 后值（勿返回未 trim 原值）；
+ *   否则 throw `非法 source: …`
+ * - limit：Number() 后 Number.isFinite && > 0 ? floor 先行钳 [1, limitMax] : limitDefault
+ *   （floor 发生位置从 core clampLimit 前移到入口，值域结果逐点相同——红线 #3）
+ * - offset：Number() 后 Number.isFinite && > 0 ? Math.floor : 0
+ */
+export function parseMarketQueryInput(raw, policy) {
+    const categoryRaw = typeof raw.category === 'string' ? raw.category.trim() : '';
+    let category = null;
+    if (categoryRaw !== '') {
+        if (CATEGORIES.includes(categoryRaw) || COMMUNITY_SLUG_RE.test(categoryRaw)) {
+            category = categoryRaw;
+        }
+        else {
+            throw new MarketQueryError(`非法分类: ${categoryRaw}（需精选分类或 [a-z0-9-]{1,32} slug）`);
+        }
+    }
+    const sourceRaw = typeof raw.source === 'string' ? raw.source.trim() : '';
+    if (sourceRaw !== '' && sourceRaw !== 'primary' && sourceRaw !== 'community' && sourceRaw !== 'all') {
+        throw new MarketQueryError(`非法 source: ${sourceRaw}（需 primary/community/all）`);
+    }
+    const source = sourceRaw === '' ? 'all' : sourceRaw;
+    const rawLimit = Number(raw.limit);
+    const limit = Number.isFinite(rawLimit) && rawLimit > 0
+        ? Math.min(policy.limitMax, Math.max(1, Math.floor(rawLimit)))
+        : policy.limitDefault;
+    const rawOffset = Number(raw.offset);
+    const offset = Number.isFinite(rawOffset) && rawOffset > 0 ? Math.floor(rawOffset) : 0;
+    return { category, source, limit, offset };
+}

package/lib/core/market.js

@@ -822,6 +822,21 @@ export class InstallGuardError extends Error {
         this.compensation = fields.compensation;
         this.repairBasis = fields.repairBasis;
     }
+    /**
+     * 线格式单一事实源（0.9.93）：三端共享的 6 字段守卫投影。各端信封自拼（host-api 409 payload 的
+     * ok/error、tools 的 ok/guard/message、cli 的裸 JSON），共享部分一律经此方法——加守卫字段只改
+     * 本方法 + client 读取一处。repairBasis undefined 时键不存在（今日 5 处投影同语义）。
+     */
+    toWire() {
+        return {
+            kind: this.kind,
+            violations: this.violations,
+            compensation: this.compensation,
+            needsRestart: this.needsRestart,
+            restartSafe: this.restartSafe,
+            ...(this.repairBasis ? { repairBasis: this.repairBasis } : {}),
+        };
+    }
 }
 /** lockfile packages 段的目标包 resolution 提取（行扫描：键行 `pkg@ver:` → 收集至下一键行；引号/嵌套键兼容）。 */
 function lockResolutionOf(lockText, pkg) {

package/lib/tools.js

@@ -2,30 +2,19 @@ import { defineTool } from '@deepseek-ai/dsh-tools';
 import { installTimeoutMs } from './core/env.js';
 import { installFromRegistry, listInstalledWithMeta, listMarket, uninstallPlugin, upgradePlugin, InstallGuardError, } from './core/market.js';
 import { COMMUNITY_CATEGORY_LABELS } from './core/community.js';
+import { parseMarketQueryInput, PRIMARY_CATEGORY_LABELS, SEARCH_CORE_DEADLINE_MS, INSTALLED_CORE_DEADLINE_MS } from './core/market-query.js';
 import { appExitFromContext, scheduleRestart } from './core/restart.js';
 import { togglePlugin as coreTogglePlugin } from './core/toggle.js';
 import { resolveActiveProfile, assertWriteAllowed } from './core/active-profile.js';
 import { desktopInstallFromRegistry, desktopToggle, desktopUninstall, desktopUpgradeFromRegistry } from './core/profile-ops.js';
-export const CATEGORY_LABELS = {
-    essentials: '装机必备',
-    'cui-picks': '崔添翼精选',
-    'self-dev': 'iasi自研',
-    'tencent-lighthouse': '腾讯轻量云专区',
-    watchlist: '观察区',
-};
-/** 分类中文标签（0.7.0 Task 5）：精选 5 类 + 社区已知标签（单一事实源 COMMUNITY_CATEGORY_LABELS）；未知 slug 原样。 */
+/** 分类中文标签（0.7.0 Task 5）：精选 5 类（单一事实源 market-query PRIMARY_CATEGORY_LABELS）+ 社区已知标签（单一事实源 COMMUNITY_CATEGORY_LABELS）；未知 slug 原样。 */
 function categoryLabelOf(category) {
-    return (CATEGORY_LABELS[category] ??
-        COMMUNITY_CATEGORY_LABELS[category] ??
-        category);
+    return PRIMARY_CATEGORY_LABELS[category] ?? COMMUNITY_CATEGORY_LABELS[category] ?? category;
 }
-/** 工具 deadline 对齐（M1 Task 7）：search 45s（core 44s）、list/outdated 65s（core 60s + 5s 回包余量）。 */
+/** 工具 deadline 对齐（M1 Task 7）：search 45s（core 44s）、list/outdated 65s（core 60s + 5s 回包余量）。
+ *  core 侧两个 deadline 常量单源于 market-query（0.9.92，与 CLI 共用）；TOOL_TIMEOUT 为本端信封专属。 */
 const SEARCH_TOOL_TIMEOUT_MS = 45_000;
-const SEARCH_CORE_DEADLINE_MS = 44_000;
 const INSTALLED_TOOL_TIMEOUT_MS = 65_000;
-const INSTALLED_CORE_DEADLINE_MS = 60_000;
-/** 社区开放分类安全 slug（与 host-api 侧同语义） */
-const COMMUNITY_SLUG_RE = /^[a-z0-9-]{1,32}$/;
 /** 社区 summary 四键投影（Task 7 ②）：agent 工具输出只带这四个字段。 */
 export function communityToolSummary(c) {
     if (!c)
@@ -83,7 +72,7 @@ export function registerTools(ctx, cfg, deps = {}, profile = resolveActiveProfil
             query: { type: 'string', description: 'Main keyword, e.g. 主题 or 搜索. Optional; omit to browse.' },
             category: {
                 type: 'string',
-                description: `Optional category: curated ${Object.keys(CATEGORY_LABELS).join('/')} or any community slug ([a-z0-9-]{1,32}, e.g. theme/memory/git).`,
+                description: `Optional category: curated ${Object.keys(PRIMARY_CATEGORY_LABELS).join('/')} or any community slug ([a-z0-9-]{1,32}, e.g. theme/memory/git).`,
             },
             source: {
                 type: 'string',
@@ -110,24 +99,11 @@ export function registerTools(ctx, cfg, deps = {}, profile = resolveActiveProfil
         }),
         timeoutMs: SEARCH_TOOL_TIMEOUT_MS,
         async execute(args, exec) {
-            const categoryRaw = typeof args.category === 'string' ? args.category.trim() : '';
-            let category = null;
-            if (categoryRaw !== '') {
-                if (categoryRaw in CATEGORY_LABELS || COMMUNITY_SLUG_RE.test(categoryRaw))
-                    category = categoryRaw;
-                else
-                    throw new Error(`非法分类: ${categoryRaw}（需精选分类或 [a-z0-9-]{1,32} slug）`);
-            }
-            // 分区参数（0.7.0 Task 5）：与 GUI 分区对齐；primary_only 已删除（D6a 允许破坏性变更）
-            const sourceRaw = typeof args.source === 'string' ? args.source.trim() : '';
-            if (sourceRaw !== '' && sourceRaw !== 'primary' && sourceRaw !== 'community' && sourceRaw !== 'all') {
-                throw new Error(`非法 source: ${sourceRaw}（需 primary/community/all）`);
-            }
-            const source = sourceRaw === '' ? 'all' : sourceRaw;
-            const rawLimit = Number(args.limit);
-            const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? clamp(rawLimit, 1, 80) : 10;
-            const rawOffset = Number(args.offset);
-            const offset = Number.isFinite(rawOffset) && rawOffset > 0 ? Math.floor(rawOffset) : 0;
+            // 0.9.92 三端查询文法：category/source/limit/offset 经 market-query 单一入口归一
+            //（与 host-api/CLI 同源同语义；文法违规 throw 直飞，与此前 throw new Error 同通道）。
+            // 分区参数语义 0.7.0 Task 5 不变；primary_only 已删除（D6a 允许破坏性变更）。
+            const intake = parseMarketQueryInput({ category: args.category, source: args.source, limit: args.limit, offset: args.offset }, { limitMax: 80, limitDefault: 10 });
+            const { category, source, offset, limit } = intake;
             // metadata-only：agent 卡片不需要 latest；与 Host GUI 共用 host namespace；
             // deadline 44s 是本 waiter 的绝对上限（工具 timeout 45s 先到兜底）
             const result = await m.listMarket(cfg, {
@@ -265,7 +241,7 @@ export function registerTools(ctx, cfg, deps = {}, profile = resolveActiveProfil
             catch (err) {
                 if (err instanceof InstallGuardError) {
                     // 结构化 error result（M2 Task 3 ㉑-㉜）：不渲染「已安装」，无 force 通道；restartSafe 随结果携带
-                    return { ok: false, guard: true, kind: err.kind, message: err.message, violations: err.violations, compensation: err.compensation, needsRestart: err.needsRestart, restartSafe: err.restartSafe, ...(err.repairBasis ? { repairBasis: err.repairBasis } : {}) };
+                    return { ok: false, guard: true, message: err.message, ...err.toWire() };
                 }
                 throw err;
             }
@@ -427,7 +403,7 @@ export function registerTools(ctx, cfg, deps = {}, profile = resolveActiveProfil
             }
             catch (err) {
                 if (err instanceof InstallGuardError) {
-                    return { ok: false, guard: true, kind: err.kind, message: err.message, violations: err.violations, compensation: err.compensation, needsRestart: err.needsRestart, restartSafe: err.restartSafe, ...(err.repairBasis ? { repairBasis: err.repairBasis } : {}) };
+                    return { ok: false, guard: true, message: err.message, ...err.toWire() };
                 }
                 throw err;
             }
@@ -464,7 +440,7 @@ export function registerTools(ctx, cfg, deps = {}, profile = resolveActiveProfil
             order: 211,
             text: [
                 'Finding / recommending / browsing DSH plugins (插件) in the personal marketplace: you MUST call dshm_search, never web_search or bash. One call per user message; extract a real keyword. After cards appear, reply with AT MOST one short sentence. Do not print install commands.',
-                `Plugin categories: ${Object.entries(CATEGORY_LABELS).map(([k, v]) => `${k}=${v}`).join(', ')}.`,
+                `Plugin categories: ${Object.entries(PRIMARY_CATEGORY_LABELS).map(([k, v]) => `${k}=${v}`).join(', ')}.`,
                 'Install only after the user names a card: dshm_install with its id. Then one short sentence mentioning the restart requirement; offer dshm_restart.',
                 'For installed plugins, call dshm_list / dshm_outdated. Upgrade only after the user confirms which one: dshm_upgrade. Uninstall only after confirmation: dshm_uninstall.',
                 'dshm_toggle switches a plugin on/off: confirm first unless the user already said it in the same message (把 skins 关掉 → execute directly); report live vs restart-required accordingly. ',
@@ -603,6 +579,3 @@ export function renderUpgrade(out) {
             : '需要重启生效——询问是否 dshm_restart。';
     return `✅ ${out.pkg} 已升级（${from}${to}）。${extra}${tail}`;
 }
-function clamp(n, min, max) {
-    return Math.min(max, Math.max(min, n));
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-m",
-  "version": "0.9.91",
+  "version": "0.9.93",
   "description": "可自定义收录清单的 DSH 插件市场：收录、安装、卸载、升级一站完成，附 agent 工具与 dshm CLI。",
   "license": "MIT",
   "type": "module",