dsh-paoding 0.2.0

package/presets/orchestrator/restrict.mjs

@@ -0,0 +1,191 @@
+/**
+ * Orchestrator tool-surface filter (restrict.mjs)
+ *
+ * Part of the dsh-paoding 编排模式 (orchestrator) preset. Hooks the
+ * `system-prompt/assemble` waterfall and narrows the MAIN agent's model-facing
+ * tool catalog to an orchestration + internal-search surface. Delegated child
+ * agents are left untouched here: their tool surface is already constrained by
+ * the `toolFilter` each dsh-tool-subagent delegation tool declares (applied as
+ * a per-child `tools.restrict()` at child creation), so re-filtering them here
+ * would intersect with — and wrongly shrink — those role surfaces.
+ *
+ * What the main agent keeps:
+ *   - orchestration: search_external / design / implement (role delegation),
+ *     send_message / list_agents / interrupt_agent (child management)
+ *   - internal search (hot path, zero delegation round-trip): glob / grep /
+ *     read / read_image / bash
+ *   - coordination: todo_write / ask_user_question / goal_* / job_* /
+ *     exit_plan_mode
+ *
+ * Host 工具（mcp__*、插件工具：codegraph / memory_search / mnemon_* 等）一律
+ * 不硬编码进本文件——它们是"检测期事实"：主 agent 需要时经 dsh-paoding 配置
+ * （main_agent_extra）勾选，由生成层按运行时检测把仍启用的注入下方 allow，
+ * 停用即自动清除。本文件只保留 dsh 核心工具。
+ *
+ * What the main agent deliberately does NOT see (all costs drop to zero for
+ * its requests): web_search, every mcp__tavily__*, write / edit /
+ * str_replace_editor, skill (+ its ~1.3k-token catalog), workflow, ralph,
+ * ssh_*, mcp__tablepro__*, describe_image, and the unfiltered subagent /
+ * subagent_fork delegations.
+ *
+ * The prompt-level filter alone cannot keep the skill catalog out: the
+ * dsh-tool-skill catalog injection guards on REGISTRY visibility
+ * (`ctx.tools.get('skill', agent)`), not on the model-facing list above, so a
+ * registry-level `deny: ['skill']` for the main agent is applied at
+ * `agent/created` (see MAIN_AGENT_REGISTRY_DENY below) — the ~1.3k-token
+ * catalog injection then stops as well.
+ *
+ * The filter is fail-open: any unexpected error returns the assembly
+ * unchanged so a filter bug can never brick every request of a session.
+ */
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'orchestrator-restrict'
+
+/** Prompt assembly and the tool registry must exist before this filter runs. */
+export const inject = ['systemPrompt', 'tools']
+
+/**
+ * Main-agent allow list. Names are matched against the resolved
+ * `assembly.tools` array (post-registration), so entries that are not
+ * currently mounted are simply absent — never an error.
+ */
+const MAIN_AGENT_ALLOW = new Set([
+  // ── role delegation ──────────────────────────────────────────────
+  'search_external',
+  'design',
+  'implement',
+  'search_internal_deep',
+  // ── child management ─────────────────────────────────────────────
+  'send_message',
+  'list_agents',
+  'interrupt_agent',
+  // ── internal search (hot path) ───────────────────────────────────
+  'glob',
+  'grep',
+  'read',
+  'read_image',
+  'bash',
+  // Host 工具（mcp__*、插件工具）不在本常量硬编码：主 agent 需要时经
+  // dsh-paoding 配置写入 main_agent_extra，由生成层注入下方 allow（见文件头说明）。
+  // ── coordination ─────────────────────────────────────────────────
+  'todo_write',
+  'ask_user_question',
+  'get_goal',
+  'create_goal',
+  'update_goal',
+  'exit_plan_mode',
+  'job_output',
+  'job_list',
+  'job_kill',
+])
+
+/**
+ * Registry-level supplement for the MAIN agent. The skill-catalog injection
+ * (dsh-tool-skill) guards on REGISTRY visibility — `ctx.tools.get('skill',
+ * agent)` — not on the model-facing surface filtered by MAIN_AGENT_ALLOW, so a
+ * prompt-only filter still lets the ~1.3k-token catalog leak into the main
+ * agent's session history. Denying 'skill' at the main agent's registry scope
+ * short-circuits that guard. Children are exempt: their surface comes from
+ * each delegation's toolFilter, and per-agent restrictions never cross scope
+ * layers (a child scope is a sibling under the shared standing mount, not a
+ * descendant of the main agent's scope).
+ */
+const MAIN_AGENT_REGISTRY_DENY = ['skill']
+
+/** Warn once so a misbehaving filter never spams the log per request. */
+let warned = false
+
+/**
+ * Whether `context.agent` is a delegated child rather than the session's main
+ * agent. Child sessions are stamped `origin: 'subagent'` with
+ * `delegationDepth >= 1` in their session header (see dsh-subagent's
+ * childSessionMeta). The origin marker is the durable, header-level signal;
+ * delegationDepth is kept as a belt-and-braces fallback.
+ */
+function isDelegatedChild(agent) {
+  const header = agent?.session?.header
+  if (header === undefined) return false
+  return header.origin === 'subagent' || (header.delegationDepth ?? 0) > 0
+}
+
+export function apply(ctx, config = {}) {
+  const allow = new Set(config.allow ?? MAIN_AGENT_ALLOW)
+  if (allow.size === 0) {
+    throw new TypeError(
+      `${name}: configured allow list is empty — refusing to strip every tool from the main agent`,
+    )
+  }
+
+  // `prepend: true` places this filter at the outermost position of the
+  // waterfall, so `await next()` observes the complete downstream result
+  // before the allow list is applied.
+  ctx.on(
+    'system-prompt/assemble',
+    async (_assembly, context, next) => {
+      // Downstream errors propagate untouched (the same contract as the
+      // liangshen tool-bootstrap): only this filter's own logic is guarded.
+      const assembled = await next()
+      try {
+        const agent = context?.agent
+        if (agent === undefined) return assembled
+        // Children carry their own role surface via tool-subagent's
+        // toolFilter; filtering them here would intersect and shrink it.
+        if (isDelegatedChild(agent)) return assembled
+
+        const tools = Array.isArray(assembled.tools) ? assembled.tools : []
+        const filtered = tools.filter((tool) => allow.has(tool?.name))
+        if (!warned) {
+          ctx.logger.info(
+            `${name}: main agent tool surface ${tools.length} -> ${filtered.length} tools (allow=${[...allow].sort().join(', ')})`,
+          )
+          warned = true
+        }
+        return { ...assembled, tools: filtered }
+      } catch (error) {
+        // Fail open: a filter bug must never brick every request of a session.
+        ctx.logger.warn(`${name}: filter failed, exposing full catalog: ${String(error)}`)
+        return assembled
+      }
+    },
+    { prepend: true },
+  )
+
+  // Registry-level supplement for the main agent. The skill-catalog injection
+  // (dsh-tool-skill) guards on REGISTRY visibility — `ctx.tools.get('skill',
+  // agent)` — not on the model-facing surface filtered above, so a prompt-only
+  // filter still lets the ~1.3k-token catalog leak into the main agent's
+  // session history. Denying 'skill' at the main agent's registry scope short-
+  // circuits that guard. Children are exempt (their surface comes from each
+  // delegation's toolFilter; per-agent restrictions never cross scopes), and
+  // whitelisting 'skill' in `allow` opts the main agent back into the catalog.
+  const disposers = []
+  ctx.on('agent/created', ({ agent }) => {
+    if (agent === undefined || isDelegatedChild(agent)) return
+    try {
+      const tools = agent?.ctx?.tools
+      if (tools === undefined || typeof tools.restrict !== 'function') return
+      const deny = MAIN_AGENT_REGISTRY_DENY.filter(
+        (name) => !allow.has(name) && tools.get(name, agent) !== undefined,
+      )
+      if (deny.length === 0) return
+      disposers.push(tools.restrict({ deny }))
+      ctx.logger.info(`${name}: main agent registry deny: ${deny.sort().join(', ')}`)
+    } catch (error) {
+      // Fail open: without the registry denial only the skill catalog leaks
+      // back — the prompt-level filter above still applies either way.
+      ctx.logger.warn(`${name}: registry deny failed, skill catalog may inject: ${String(error)}`)
+    }
+  })
+  if (typeof ctx.effect === 'function') {
+    ctx.effect(() => () => {
+      for (const dispose of disposers.splice(0)) {
+        try {
+          dispose()
+        } catch {
+          // best-effort lift on plugin unload
+        }
+      }
+    }, `${name}: main agent registry deny lift`)
+  }
+}

package/tools/install.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * dsh-paoding installer — CLI 入口 + 公共 API 聚合薄层。
+ *
+ * 原单文件（2767 行）的功能实现已按模块拆分到 tools/lib/*.mjs（util / yaml /
+ * config / host / skills / spans / compose / alloc / wizard / state / cli 模块
+ * 树）；本文件仅保留：
+ *   - 公共导出面（与旧单文件完全一致，供 plugins/paoding-config-ui 消费）：
+ *     DEFAULT_MAIN_AGENT_PERSONA_EXTRA / collectState / generateAndInstall；
+ *   - 直接运行守卫（CLI entry：import 本模块不触发安装，仅直接执行时经
+ *     lib/cli.mjs 的 main() 运行）。
+ */
+import { pathToFileURL } from 'node:url'
+import { main } from './lib/cli.mjs'
+
+export { DEFAULT_MAIN_AGENT_PERSONA_EXTRA } from './lib/util.mjs'
+export { collectState, generateAndInstall } from './lib/state.mjs'
+
+// CLI entry: only run main() when invoked directly (importing this module for
+// the visual config UI must not trigger an install).
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  const exitCode = await main()
+  process.exit(exitCode)
+}

package/tools/lib/alloc.mjs

@@ -0,0 +1,138 @@
+/**
+ * 分配策略：smartDefaults 按工具名关键词（keywords）给出默认角色分配、在无既有
+ * 配置时作 --auto 的兜底 assignments；baseAssignments 给出「基础模板」（仅 dsh
+ * 内置工具，fresh 非交互安装的默认起点）；resolveAssignments 把既有配置 / 建议 /
+ * 静态基础合成最终 assignments。纯参数计算，仅依赖 util 的 ROLES 常量；
+ * 被 state（smartDefaults）/ cli（resolveAssignments / baseAssignments）引用。
+ */
+import { ROLES } from './util.mjs'
+
+
+// ── smart default allocation ────────────────────────────────────────────────
+
+/**
+ * Default host-tool → role assignment used by --auto without a config file
+ * and as the wizard's suggested values.  codegraph and memory_search stay on
+ * the main agent (matching the static preset); other MCP tools are suggested
+ * by tool-name keywords.  角色条目形状 { model, provider, persona, tools }：
+ * model / provider（角色专用模型）在此恒为 null（= 不注入 agentOptions，子 agent
+ * 继承主 agent 当前模型），仅配置文件 / 向导 4d 显式设置。
+ */
+export function smartDefaults(mcpReports, inventory, staticBase) {
+  const roles = {}
+  const extra = []
+  const byServer = new Map()
+  for (const report of mcpReports) {
+    const server = report.serverName
+    const tools = [...inventory].filter((name) => name.startsWith(`mcp__${server}__`))
+    byServer.set(server, tools)
+    const assign = (role) => {
+      roles[role] ??= { model: null, provider: null, persona: null, tools: [...staticBase[role]] }
+      for (const t of tools) if (!roles[role].tools.includes(t)) roles[role].tools.push(t)
+    }
+    if (server === 'codegraph') {
+      extra.push(...tools)
+    } else if (keywords(tools, /search|research|crawl|extract|map|web/)) {
+      assign('search_external')
+    } else if (keywords(tools, /code|coding|fs|file|write|edit|bash|exec|run/)) {
+      assign('implement')
+    } else if (keywords(tools, /design|render|image|screenshot|paint/)) {
+      assign('design')
+    } else {
+      assign('search_external')
+    }
+  }
+  if (inventory.has('memory_search')) extra.push('memory_search')
+  // main_agent_persona_extra 不在此赋值（null 即可）：compose 时 null 回落默认常量。
+  // roles_remove / main_agent_name 不在此赋值（[] / null 即可）：删除与改名是显式配置。
+  return {
+    roles,
+    roles_remove: [],
+    main_agent_extra: extra,
+    main_agent_remove: [],
+    main_agent_skills: [],
+    main_agent_skills_inline: [],
+    main_agent_persona_extra: null,
+    main_agent_name: null,
+    skills: {},
+  }
+}
+
+export function keywords(names, pattern) {
+  return names.some((name) => pattern.test(name))
+}
+
+/**
+ * 基础模板 assignments（fresh 非交互安装的默认起点）：每个内置角色保留静态
+ * preset 的 dsh 基础工具，host/MCP 工具一概不纳入 —— npx 场景先装完可用基础
+ * 版，host 工具留给用户在 设置 → 庖丁配置（或向导）里显式开启，避免智能默认
+ * 把检测到的 host 工具静默塞进委派链。形状与 smartDefaults 返回值完全一致，
+ * 生成层 / 序列化层无需区分来源；staticBase 复制而非别名，防调用方原地改写。
+ */
+export function baseAssignments(staticBase) {
+  const roles = {}
+  for (const role of ROLES) {
+    // static preset 的角色 allow 自带静态 host 工具名（如 mcp__tavily__*）；模板
+    // 一律剔除 mcp__ 前缀名（KNOWN_HOST_PLUGINS 工具不在 staticBase 里，无需再滤），
+    // 保证落盘的配置文件只含 dsh 基础工具 —— host 工具全部经 UI/向导显式开启。
+    const baseTools = (staticBase[role] ?? []).filter((name) => !name.startsWith('mcp__'))
+    roles[role] = { name: null, model: null, provider: null, persona: null, tools: [...baseTools] }
+  }
+  return {
+    roles,
+    roles_remove: [],
+    main_agent_extra: [],
+    main_agent_remove: [],
+    main_agent_skills: [],
+    main_agent_skills_inline: [],
+    main_agent_persona_extra: null,
+    main_agent_name: null,
+    skills: {},
+  }
+}
+
+/**
+ * Resolve the final assignments from the existing config, smart defaults, or
+ * the interactive wizard.  Returns { roles, roles_remove, main_agent_extra,
+ * main_agent_remove, main_agent_skills, main_agent_skills_inline,
+ * main_agent_persona_extra, main_agent_name, skills }；roles 条目形状
+ * { name, model, provider, persona, tools }（model / provider = 角色专用模型，
+ * 缺省 null = 不注入 agentOptions）。
+ */
+export function resolveAssignments(existing, suggested, staticBase) {
+  if (existing) {
+    const roles = {}
+    // roles_remove 命中的内置角色即使仍残留在 config.roles 里也跳过：不让回落逻辑
+    // （suggested/staticBase 默认 entry）把已删除的角色悄悄复活。
+    const removedBuiltins = new Set(existing.roles_remove ?? [])
+    for (const [toolName, role] of Object.entries(existing.roles)) {
+      if (removedBuiltins.has(toolName)) continue
+      roles[toolName] = {
+        name: role.name ?? null,
+        model: role.model ?? null,
+        provider: role.provider ?? null,
+        persona: role.persona ?? null,
+        tools: role.tools ?? (suggested.roles[toolName]?.tools ?? staticBase[toolName] ?? []),
+      }
+    }
+    return {
+      roles,
+      roles_remove: existing.roles_remove ?? [],
+      // main_agent_extra 回填语义：配置文件里「显式写了键」（含显式空列表，见
+      // normalizeConfig.has_main_agent_extra）一律尊重 —— 显式 [] = 用户明确不
+      // 要任何 host 工具，不得被智能默认悄悄回填；只有键完全缺失（老配置，无
+      // 该标记）才按旧行为用 suggested.main_agent_extra 兜底。
+      main_agent_extra:
+        existing.has_main_agent_extra || existing.main_agent_extra.length > 0
+          ? existing.main_agent_extra
+          : suggested.main_agent_extra,
+      main_agent_remove: existing.main_agent_remove ?? [],
+      main_agent_skills: existing.main_agent_skills ?? [],
+      main_agent_skills_inline: existing.main_agent_skills_inline ?? [],
+      main_agent_persona_extra: existing.main_agent_persona_extra ?? null,
+      main_agent_name: existing.main_agent_name ?? null,
+      skills: existing.skills,
+    }
+  }
+  return suggested
+}