@yangdcm/dsh-expert-team 1.2.1 → 1.2.3

package/CHANGELOG.md

@@ -3,6 +3,32 @@
 本包遵循[语义化版本](https://semver.org/lang/zh-CN/)。dsh 宿主版本线的对应关系写在
 `package.json` 的 `engines.dsh` 与 `dsh.compatibility` 里，插件市场按它判断"这个插件跟你的宿主兼不兼容"。
 
+## 1.2.3
+
+**给 lead 工具面收窄加开关**（因为 1.2.2 让一个从未生效的行为突然生效了）
+
+- 背景：A 线"把执行类工具从 lead 手上拿走"此前因取错作用域**从未真正生效**，1.2.2 修好后它会
+  立刻改变日常形态 —— expert-team 会话的 lead 不再持有 `bash/write/edit/grep/glob`。
+  这是设计意图，但**没有开关的行为变更不该只留一个"忍着或回退版本"的选项**。
+- 新增开关 `gates.leadToolFace`（`on`/`off`，默认 `on`）：优先级与档位门一致
+  **`config.leadToolFace` > `DSH_EXPERT_TEAM_LEAD_TOOLFACE` > 设置（官方面板/浮层） > 默认 on**；
+  非法值一律回默认 on（不猜、不报错 —— 与档位门同一条纪律）。
+- 关掉时**出声一次**（`[expert-team] lead 工具面收窄已关闭…`）：否则"我明明关了"与
+  "开关没生效"看起来一模一样。
+## 1.2.2
+
+**修掉"lead 工具面收窄静默失效"**（拿真机启动日志换来的）
+
+- 症状：每次创建 agent 都刷一行 `lead 工具面**未**收窄（nothing-to-deny）… 宿主里这些名字一个都不存在`，
+  而实际上模型可见的 `bash/write/edit/grep/glob` **存在** —— 结论不成立，收窄也没发生。
+- 根因：宿主 `tools.view(scope)` **不传 scope = 全局视图**；0.1.5 起模型可见工具由 preset 注册在
+  **agent 平面**，于是全局视图"非空但缺这几个名字"，纯函数据实报 `nothing-to-deny`。
+  宿主自己的 `restrict()` 用的就是 `scopeOf(this.ctx)`，我们却用了不传 scope 的 `view()`。
+- 修法：新增 `agentScopedToolNames()`（动态 import `@deepseek-ai/dsh-scope` 取 `scopeOf(agent.ctx)`，
+  再 `view(scope)`）；取不到 scope 时返回 `knownNames: undefined` ⇒ 如实报 **no-known-names**
+  （"我不知道有什么"），绝不再退化成"宿主里没有这些工具"这种不成立的结论。
+- 告警去重：同一 status 每进程只喊一次（十行同样的 warn 会把"响亮"变成噪声，
+  而噪声的代价是所有告警一起被降权）。两种零仍然分得清。
 ## 1.2.1
 
 **卸载回收覆盖历史副本**（1.2.0 的补丁）

package/README.en.md

@@ -91,6 +91,10 @@ pnpm install && dsh web
 > on the official page — its value type cannot be expressed reliably in the host schema, so it stays with
 > the overlay's settings tab and `$DSH_HOME/expert-team/settings.json`. On a host with no settings service
 > every setting falls back to that file.
+>
+> **The A-line switch**: the "narrow the lead's tool face" gate (`gates.leadToolFace`, default `on`)
+> decides whether execution tools (`bash/write/edit/grep/glob`) are taken away from the lead and given
+> to the role subagents. Turn it off with `config.leadToolFace` or `DSH_EXPERT_TEAM_LEAD_TOOLFACE=off`.
 
 ## Quick start
 

package/README.md

@@ -84,6 +84,10 @@ pnpm install && dsh web
 > 并且随插件市场的**备份与恢复**一起走。**诚实边界**：`默认班底`（角色 id 数组）不在官方页面里
 > —— 它的取值类型在宿主 schema 里表达不可靠，继续由浮层设置页签与
 > `$DSH_HOME/expert-team/settings.json` 负责；宿主没有 settings 服务时，全部设置退回该文件。
+>
+> **A 线开关**：设置里的「门禁 → 收窄 lead 工具面」（`gates.leadToolFace`，默认 `on`）决定
+> 是否把执行类工具（`bash/write/edit/grep/glob`）从 lead 手上拿走、交给角色子代理。
+> 也可用 `config.leadToolFace` 或环境变量 `DSH_EXPERT_TEAM_LEAD_TOOLFACE=off` 关闭。
 
 ## 快速上手
 

package/lib/command.js

@@ -41,7 +41,7 @@ import { collectTokenUsage } from './metrics/token-usage.js';
 import { renderTokenSection } from './metrics/tokens.js';
 // A 线（token 成本治理 · 第 2 步）：**收窄 lead 自己的工具面**。判定全在
 // `lib/lead-toolface.js`（纯函数、零宿主依赖、可单测）；这里只负责在 agent **创建时刻**接线。
-import { planLeadToolFace, shouldNarrowLeadToolFace } from './lead-toolface.js';
+import { planLeadToolFace, shouldNarrowLeadToolFace, agentScopedToolNames } from './lead-toolface.js';
 // G 线（档位）：档位词表/裁剪表/suggestTier 的**唯一真源**。SKILL 的裁剪表、`/team status`
 // 的输出、浮层候选项全部从这里来 —— 两处各写一份就是又一次「一个事实多份拷贝」。
 import { normalizeTier, suggestTier, tierSummaryLine, tierDetailLines, tierChoices, TIER_SPEC, TIER_LABELS_ZH, DEFAULT_TIER, narrowedRoles } from './tier.js';
@@ -565,6 +565,7 @@ function reapplySettingsDerived() {
     resolveLimits(PLUGIN_CONFIG, limitsBaseFromSettings(s));
     resolveRoundLimits(PLUGIN_CONFIG, roundLimitsBaseFromSettings(s));
     resolveTierGate(PLUGIN_CONFIG, s.gates);
+    resolveLeadToolFace(PLUGIN_CONFIG, s.gates);
     return true;
   } catch (e) {
     console.warn('[expert-team] 重算设置派生值失败（保持上一次生效值）：' + String(e && e.message ? e.message : e));
@@ -1611,6 +1612,28 @@ const TIER_GATE_VALUES = ['soft', 'hard'];
 const TIER_GATE_ENV = 'DSH_EXPERT_TEAM_TIER_GATE';
 let TIER_GATE = DEFAULT_TIER_GATE;
 
+// ── lead 工具面收窄的开关（2026-09-14 加）──────────────────────────────────────
+// 为什么需要它：A 线的"把执行类工具从 lead 手上拿走"此前因一个 bug **从未真正生效**
+// （清单取错作用域，见 lib/lead-toolface.js）。修好之后它会立刻改变日常使用形态 ——
+// lead（含正在跟你对话的那个）不再持有 bash/write/edit/grep/glob，执行全部落到角色子代理。
+// 这是设计意图，但**没有开关的行为变更不该只留给用户一个"忍着或回退版本"**。
+// 优先级与档位门完全一致：**config > env > 设置控制台 > 内置默认（on）**。
+const DEFAULT_LEAD_TOOLFACE = 'on';
+const LEAD_TOOLFACE_VALUES = ['on', 'off'];
+const LEAD_TOOLFACE_ENV = 'DSH_EXPERT_TEAM_LEAD_TOOLFACE';
+let LEAD_TOOLFACE = DEFAULT_LEAD_TOOLFACE;
+
+/** 解析 lead 工具面收窄开关（非法值一律回默认 on —— 与档位门同理，不猜不报错）。 */
+function resolveLeadToolFace(config, base) {
+  const cfgRaw = String((config && typeof config === 'object' && config.leadToolFace) || '').trim().toLowerCase();
+  const envRaw = String(((typeof process !== 'undefined' && process.env) || {})[LEAD_TOOLFACE_ENV] || '').trim().toLowerCase();
+  const baseRaw = String((base && typeof base === 'object' ? base.leadToolFace : base) || '').trim().toLowerCase();
+  LEAD_TOOLFACE = LEAD_TOOLFACE_VALUES.includes(cfgRaw) ? cfgRaw
+    : (LEAD_TOOLFACE_VALUES.includes(envRaw) ? envRaw
+      : (LEAD_TOOLFACE_VALUES.includes(baseRaw) ? baseRaw : DEFAULT_LEAD_TOOLFACE));
+  return LEAD_TOOLFACE;
+}
+
 /**
  * 解析档位门是软还是硬。**非法值一律回默认（soft）**，不猜也不报错 ——
  * 一个拼错的开关值把流程卡死（hard）比静默放行更糟，而"卡死"正是最贵的失败模式。
@@ -4409,7 +4432,20 @@ async function executeTeamCommand(ctx, invocation) {
 /** 并发写追踪器：**进程级单例**（跨工具调用累积；`_live` 暴露以便单测重置与断言）。 */
 const WRITE_TRACER = createWriteTracer();
 
-export const _live = { pushActivity, phaseAccountingViolations, loggedPhases, authorityViolations, WRITE_TRACER, createWriteTracer, formatConflict, summarizeTool, parseLogLine, roleOfSub, mapRoleToSub, membersFromState, buildRoleSubMap, resolveSubRoles, childSessionTiming, SUB_HEADER_CACHE, workflowEventIndex, workflowChildLabels, workflowChildMeta, workflowRuns, WF_EVENT_CACHE, rememberSessionRun, sessionRunFor, runOwnerSession, SESSION_RUNS, parseTeamCommand, deriveMemberEntries, schemaViolations, runHealth, RUN_STALL_MS, scaffoldFingerprint, SCAFFOLD_REQUIRED, strandedTasks, settleStranded, IN_FLIGHT_STATUSES, normalizeCoverage, SCHEMA_WARN_SEEN, pushActivityEvent, DEFAULT_LIMITS, LIMITS, resolveLimits, capacityViolations, DEFAULT_ROUND_LIMITS, ROUND_LIMITS, ROUND_LIMIT_ENV, resolveRoundLimits, ROUND_LIMIT_OF_KIND, roundOf, isQualityTask, normTitle, roundLimitViolations, reworkLoopWriteGuard, mutateTasks, readStandingRules, appendStandingRule, rulesRun, scopeOverlapWarnings, applyTaskStatus, waitRun, eventFamily, verdictFromToken, normalizeRoleName, truncateCodepoints, filterRunScopedSubs, runCreatedAtMs, runLogTail, liveFiles, LIVE_FILES_CACHE, DEFAULT_ROLES, resolveTierGate, TIER_GATE_ENV, snapshotRun, settingsPath, loadSettingsSync, currentSettings, limitsBaseFromSettings, roundLimitsBaseFromSettings, effectiveTierGate: () => TIER_GATE, ensureSkillInstalled, ensurePresetInstalled, uninstallInstalled, buildSkillRegistration, parseSkillMarkdown, PLUGIN_VERSION, INSTALL_STAMP, runtimeSkillRegistered: () => RUNTIME_SKILL_REGISTERED, installHostSettings, hostValues, hostScope, hostSettingsNote, updateHostSettings, pickFileOnly, pickHostExpressible, buildHostSchema, hostBase, hostSchemaPaths, reapplySettingsDerived, currentSettings, mergeSettings };
+/**
+ * lead 工具面告警去重：同一 status 每个进程只喊一次。
+ * 为什么：该告警按 **agent 创建**触发，一个会话里每建一个 agent 都会喊 —— 十行同样的 warn
+ * 会把"响亮"变成"噪声"，而噪声的代价是所有告警一起被降权（本仓反复记录过的失败模式）。
+ * 去重只影响**重复次数**，不影响"第一次一定喊"，也不合并不同 status（两种零仍然分得清）。
+ */
+const LEAD_TOOLFACE_WARNED = new Set();
+let LEAD_TOOLFACE_OFF_LOGGED = false;
+function warnLeadToolFaceOnce(status, detail) {
+  if (LEAD_TOOLFACE_WARNED.has(status)) return;
+  LEAD_TOOLFACE_WARNED.add(status);
+  console.warn(`[expert-team] lead 工具面**未**收窄（${status}）：${detail}`);
+}
+export const _live = { pushActivity, phaseAccountingViolations, loggedPhases, authorityViolations, WRITE_TRACER, createWriteTracer, formatConflict, summarizeTool, parseLogLine, roleOfSub, mapRoleToSub, membersFromState, buildRoleSubMap, resolveSubRoles, childSessionTiming, SUB_HEADER_CACHE, workflowEventIndex, workflowChildLabels, workflowChildMeta, workflowRuns, WF_EVENT_CACHE, rememberSessionRun, sessionRunFor, runOwnerSession, SESSION_RUNS, parseTeamCommand, deriveMemberEntries, schemaViolations, runHealth, RUN_STALL_MS, scaffoldFingerprint, SCAFFOLD_REQUIRED, strandedTasks, settleStranded, IN_FLIGHT_STATUSES, normalizeCoverage, SCHEMA_WARN_SEEN, pushActivityEvent, DEFAULT_LIMITS, LIMITS, resolveLimits, capacityViolations, DEFAULT_ROUND_LIMITS, ROUND_LIMITS, ROUND_LIMIT_ENV, resolveRoundLimits, ROUND_LIMIT_OF_KIND, roundOf, isQualityTask, normTitle, roundLimitViolations, reworkLoopWriteGuard, mutateTasks, readStandingRules, appendStandingRule, rulesRun, scopeOverlapWarnings, applyTaskStatus, waitRun, eventFamily, verdictFromToken, normalizeRoleName, truncateCodepoints, filterRunScopedSubs, runCreatedAtMs, runLogTail, liveFiles, LIVE_FILES_CACHE, DEFAULT_ROLES, resolveTierGate, TIER_GATE_ENV, snapshotRun, settingsPath, loadSettingsSync, currentSettings, limitsBaseFromSettings, roundLimitsBaseFromSettings, effectiveTierGate: () => TIER_GATE, ensureSkillInstalled, ensurePresetInstalled, uninstallInstalled, buildSkillRegistration, parseSkillMarkdown, PLUGIN_VERSION, INSTALL_STAMP, runtimeSkillRegistered: () => RUNTIME_SKILL_REGISTERED, agentScopedToolNames, warnLeadToolFaceOnce, resolveLeadToolFace, LEAD_TOOLFACE_ENV, effectiveLeadToolFace: () => LEAD_TOOLFACE, installHostSettings, hostValues, hostScope, hostSettingsNote, updateHostSettings, pickFileOnly, pickHostExpressible, buildHostSchema, hostBase, hostSchemaPaths, reapplySettingsDerived, currentSettings, mergeSettings };
 
 export function apply(ctx, config) {
   // 留一份 config：设置在运行时改变（官方面板 / 浮层）时要**用同一份 config** 重算上限与档位门，
@@ -4427,6 +4463,8 @@ export function apply(ctx, config) {
   resolveRoundLimits(config, roundLimitsBaseFromSettings());
   // G 线：档位门软/硬（config.tierGate > DSH_EXPERT_TEAM_TIER_GATE > 设置 > soft）。
   resolveTierGate(config, currentSettings().gates);
+  // A 线开关：config > env > 设置 > 默认(on)。关掉即 lead 保留全部工具。
+  resolveLeadToolFace(config, currentSettings().gates);
   // 批 2-1：宿主若提供 ctx.fs，就让它接管工件写入（真实版本栅栏）；否则保持同语义的回退实现。
   // 机会式探测而非 inject —— 见 ARTIFACT 声明处的说明（inject 缺失服务会让整条命令挂不上）。
   const hostFsAdopted = adoptHostFs(ctx);
@@ -4589,7 +4627,7 @@ export function apply(ctx, config) {
       // 为什么是这个时刻：`agent/created` 由宿主 `announce()` 在**创建时刻**发出；宿主自己对
       //   子代理也是在组合（setup）阶段调 `childCtx.tools.restrict(...)`（`dsh-subagent:554`）。
       //   即：**照抄宿主自己的时序**，不另造。
-      ctx.on('agent/created', ({ agent }) => {
+      ctx.on('agent/created', async ({ agent }) => {
         try {
           const agents = ctx.get('agents');
           // ① preset 必须是专家团（`composedPreset` 读活动作用域链，未写会话头也答得出）
@@ -4599,12 +4637,25 @@ export function apply(ctx, config) {
           const isRoot = agents?.roots?.().includes(agent) === true;
           if (!shouldNarrowLeadToolFace({ presetId, isRoot }).apply) return;   // 无关 agent：静默返回，不是失败
 
-          const knownNames = ctx.get('tools')?.view?.()?.restrictableNames;
+          if (LEAD_TOOLFACE === 'off') {
+            // 关掉时**出声一次**：否则"我明明关了"与"开关没生效"看起来一模一样（两种零纪律）。
+            if (!LEAD_TOOLFACE_OFF_LOGGED) {
+              LEAD_TOOLFACE_OFF_LOGGED = true;
+              console.log(`[expert-team] lead 工具面收窄已关闭（${LEAD_TOOLFACE_ENV}=off 或设置 gates.leadToolFace=off）⇒ lead 保留全部工具`);
+            }
+            return;
+          }
+
+          // ③ **必须取 agent 作用域**的名字清单：`view()` 不传 scope = 全局视图，而模型可见工具
+          //    在 0.1.5 起由 preset 注册在 agent 平面 ⇒ 全局视图非空但缺那几个名字，收窄会静默失效
+          //    且给出"宿主里没有这些工具"的错误结论（拿真机日志换来的教训，详见 lead-toolface.js）。
+          const { knownNames, reason } = await agentScopedToolNames({ agentCtx: agent.ctx });
           const plan = planLeadToolFace({ platform: process.platform, knownNames });
           if (!plan.effective) {
             // **两种零都要出声**：`no-known-names`（我不知道宿主有什么）与
             // `nothing-to-deny`（宿主确实没有这些）不是同一件事，不能长成同一个样子。
-            console.warn(`[expert-team] lead 工具面**未**收窄（${plan.status}）：${plan.notes.join(' ')}`);
+            // 但同一状态**只喊一次**：每个会话都刷会把 warn 变成噪声，而噪声会让所有告警一起被降权。
+            warnLeadToolFaceOnce(plan.status, `${plan.notes.join(' ')}（清单来源：${reason}）`);
             return;
           }
           // 成功不打印：每个会话都刷一行会把 warn 变成噪声（本仓纪律：warn 必须保持可见）。

package/lib/lead-toolface.js

@@ -177,3 +177,49 @@ export function shouldNarrowLeadToolFace({ presetId, isRoot } = {}) {
   if (isRoot !== true) return { apply: false, reason: 'is-subagent' };
   return { apply: true, reason: 'lead' };
 }
+
+/**
+ * 取**agent 作用域**下的"可限制工具名清单"。
+ *
+ * ── 为什么必须带 scope（这一条是拿真机日志换来的）────────────────────────────
+ * 宿主 `tools.view(scope)` 的文档写得很直白：**不传 scope = 全局视图**。而 0.1.5 起模型可见的
+ * `bash/write/edit/grep/glob` 由 **preset 注册在 agent 平面**，不再是全局工具 ——
+ * 于是 `view()`（全局）会返回一个**非空但缺这几个名字**的集合，`planLeadToolFace` 据此报
+ * `nothing-to-deny`，收窄**静默失效**，而日志还在说"宿主里这些名字一个都不存在"（不属实）。
+ * 宿主自己的 `restrict()` 用的就是 `scopeOf(this.ctx)` —— 本函数照抄同一条取 scope 的路。
+ *
+ * scope 是 `@deepseek-ai/dsh-scope` 里的**模块私有 Symbol**（`Symbol("dsh.scope")`，不是
+ * `Symbol.for`），因此只能经该包的 `scopeOf()` 取得 ⇒ **动态 import**：仓库里解析不到该包时
+ * 返回 `knownNames: undefined`，由调用方如实报 `no-known-names`（"我不知道有什么"），
+ * 绝不退化成"宿主里没有这些工具"那种**不成立**的结论。
+ *
+ * @param {object} input
+ * @param {object} [input.agentCtx] - `agent.ctx`（scope 就挂在它上面）
+ * @param {object} [input.tools] - 工具服务（默认取 `agentCtx.tools`）
+ * @param {Function} [input.loadScope] - **仅供测试**注入 `@deepseek-ai/dsh-scope` 的加载器
+ * @returns {Promise<{knownNames: Set<string>|undefined, reason: string}>}
+ */
+export async function agentScopedToolNames({ agentCtx, tools, loadScope } = {}) {
+  const loader = typeof loadScope === 'function' ? loadScope : () => import('@deepseek-ai/dsh-scope');
+  let scopeOf;
+  try {
+    const mod = await loader();
+    scopeOf = mod && mod.scopeOf;
+  } catch (e) {
+    return { knownNames: undefined, reason: 'scope-module-unavailable:' + String((e && e.message) || e) };
+  }
+  if (typeof scopeOf !== 'function') return { knownNames: undefined, reason: 'scope-of-missing' };
+  const service = tools || (agentCtx && agentCtx.tools);
+  if (!service || typeof service.view !== 'function') return { knownNames: undefined, reason: 'tools-service-unavailable' };
+  let scope;
+  try { scope = scopeOf(agentCtx); } catch { return { knownNames: undefined, reason: 'scope-undetectable' }; }
+  if (scope === undefined) return { knownNames: undefined, reason: 'not-a-scoped-ctx' };
+  try {
+    const view = service.view(scope);
+    const names = view && view.restrictableNames;
+    const size = names && typeof names.size === 'number' ? names.size : 0;
+    return { knownNames: names, reason: size > 0 ? 'ok' : 'empty-scoped-view' };
+  } catch (e) {
+    return { knownNames: undefined, reason: 'view-failed:' + String((e && e.message) || e) };
+  }
+}

package/lib/settings.js

@@ -57,6 +57,7 @@ export const SETTINGS_SPEC = {
       boundarySpec: { type: 'bool', default: true, label: '规格边界章节（SPEC.md）', hint: '边界没填就不让进 implement' },
       loopGuard: { type: 'bool', default: true, label: '振荡检测（A→B→A→B）', hint: '宿主那份只管同工具重复，这份管来回振荡' },
       tierGate: { type: 'enum', values: ['soft', 'hard'], default: 'soft', label: '档位选择门', hint: 'soft = 建议先生效；hard = 不选不开工' },
+      leadToolFace: { type: 'enum', values: ['on', 'off'], default: 'on', label: '收窄 lead 工具面', hint: 'on = 执行类工具（bash/write/edit/grep/glob）从 lead 手上拿走，交给角色子代理（省 token）；off = lead 保留全部工具' },
       maxReviewRounds: { type: 'int', min: 1, max: 20, default: 3, label: '评审轮次上限', hint: '到顶的正确动作是升级用户，不是再来一轮' },
       maxTestRounds: { type: 'int', min: 1, max: 20, default: 3, label: '测试轮次上限', hint: '同上' },
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yangdcm/dsh-expert-team",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "dsh「专家团」bundle：一句自然语言自动组建/持久化一支 12 角色多智能体团队，共享工作区协议 + 阶段门控编排 + 结构化交接 + 质量门禁/自动调度，实现者直接改代码并产出持久工件；带 live 团队浮层（质量门禁/覆盖率/工件预览）。 · Role-based multi-agent expert team for DeepSeek Harness: one sentence in, a staged and gated team delivery out.",
   "type": "module",
   "license": "MIT",