dsh-plugin-tool-management 0.2.0 → 0.5.1

package/lib/subagents/service.js

@@ -0,0 +1,333 @@
+// src/subagents/service.ts —— 轻量子智能体：人设发现（TTL 扫描）+ 官方 ctx.subagents.start 薄封装。
+// 设计 §3：人设 = $DSH_HOME/tool-management/agents/<name>.md（frontmatter 可选，缺省派生）；v1 串行运行；
+// spawn provider 缺失时经 createRequire 挂载官方 dsh-subagent-spawn-in-process（宿主侧包）。
+//
+// v0.4 目录变更：人设由 `$DSH_HOME/subagents/` 搬到 `$DSH_HOME/tool-management/agents/`
+// （插件产生的文件统一收在 tool-management/ 下）。旧目录在首次扫描时搬入，见 relocateLegacyPersonas。
+import { createRequire } from 'node:module';
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { resolveDshHome } from '../skills/core.js';
+import { expandUploads, planPersonaImport } from '../imports/upload.js';
+const message = (e) => String((e && e.message) || e);
+/** 人设默认目录：`$DSH_HOME/tool-management/agents/`。 */
+export function defaultPersonasDir() {
+    return join(resolveDshHome(), 'tool-management', 'agents');
+}
+/**
+ * 旧目录 `$DSH_HOME/subagents/` → `tool-management/agents/` 一次性搬移（幂等）。
+ * 只在目标不存在同名文件时搬（绝不覆盖）；源目录保留空壳。每个进程只跑一次。
+ */
+let personasRelocated = false;
+async function relocateLegacyPersonas(dir) {
+    if (personasRelocated)
+        return;
+    personasRelocated = true;
+    const legacy = join(resolveDshHome(), 'subagents');
+    if (legacy === dir)
+        return;
+    let names;
+    try {
+        names = (await readdir(legacy)).filter((n) => n.toLowerCase().endsWith('.md'));
+    }
+    catch {
+        return;
+    }
+    if (!names.length)
+        return;
+    await mkdir(dir, { recursive: true }).catch(() => undefined);
+    for (const name of names) {
+        const from = join(legacy, name);
+        const to = join(dir, name);
+        try {
+            const exists = await stat(to).then(() => true).catch(() => false);
+            if (exists)
+                continue;
+            await rename(from, to);
+        }
+        catch {
+            /* 单项失败（被占用等）不阻断其余；保留源文件，下次启动再试 */
+        }
+    }
+}
+/** 行式 frontmatter 解析：只认 description / provider / model / tools / toolsDeny 五个键。 */
+export function parsePersona(raw, fallbackName) {
+    const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw);
+    const data = {};
+    let body = raw;
+    if (m) {
+        for (const line of m[1].split(/\r?\n/)) {
+            const kv = /^([A-Za-z_-]+)\s*:\s*(.*)$/.exec(line.trim());
+            if (kv)
+                data[kv[1].toLowerCase()] = kv[2].trim();
+        }
+        body = raw.slice(m[0].length);
+    }
+    const listOf = (value) => {
+        if (!value)
+            return undefined;
+        const list = value.split(/[,，]/).map((s) => s.trim()).filter(Boolean);
+        return list.length ? list : undefined;
+    };
+    const tools = listOf(data.tools);
+    // 兼容两种写法：`toolsdeny: a, b`（线上格式）与 `toolsDeny: a, b`（键名统一小写后同形）。
+    const toolsDeny = listOf(data.toolsdeny);
+    const firstLine = body.split(/\r?\n/).find((l) => l.trim())?.trim() ?? '';
+    return {
+        name: fallbackName,
+        description: data.description || firstLine,
+        provider: data.provider || undefined,
+        model: data.model || undefined,
+        tools,
+        toolsDeny,
+        body: body.trim(),
+        path: '',
+    };
+}
+const RESULT_MAX = 16 * 1024;
+export function createSubagentService(ctx, opts) {
+    const dir = opts?.subagentsDir || defaultPersonasDir();
+    const req = createRequire(import.meta.url);
+    let cache = null;
+    async function list() {
+        if (cache && Date.now() - cache.at < 1000)
+            return cache.value;
+        // 旧目录搬家放在首次扫描前（幂等；失败不阻断，旧目录仍会被下面的读取兜底看到）。
+        await relocateLegacyPersonas(dir).catch(() => undefined);
+        const docs = [];
+        try {
+            const entries = await readdir(dir);
+            for (const fileName of entries.filter((e) => e.endsWith('.md')).sort()) {
+                const raw = await readFile(join(dir, fileName), 'utf8').catch(() => '');
+                if (!raw.trim())
+                    continue;
+                docs.push({ ...parsePersona(raw, fileName.slice(0, -3)), path: join(dir, fileName) });
+            }
+        }
+        catch { /* 目录缺失 = 无人设 */ }
+        cache = { at: Date.now(), value: docs };
+        return docs;
+    }
+    // spawn provider 在场性（设计 §3.2，落地方式见 cordis.patch.yml 的取舍注释）：
+    // 官方通道探测（ctx.subagents.list()）→ 缺失才挂载 → 失败把原因原样带出（不吞、不谎报）。
+    // 不是一次性静默标记：每次调用都先探测，宿主后来注册了 provider 也能立刻跟上。
+    let spawnMount = null;
+    function hasSpawnProvider(runtime) {
+        if (typeof runtime.list !== 'function')
+            return false;
+        try {
+            const names = runtime.list();
+            return Array.isArray(names) && names.indexOf('spawn') >= 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    async function ensureSpawnProvider() {
+        const runtime = ctx.get?.('subagents');
+        if (!runtime || typeof runtime.start !== 'function') {
+            throw new Error('子代理服务未挂载（ctx.subagents 缺失；请确认 DSH 版本 ≥0.1.5-rc.2）');
+        }
+        if (hasSpawnProvider(runtime))
+            return runtime;
+        // 宿主没有 list() 就探测不了：不重复挂载（避免同名 provider 二次注册），交给 start 报官方错误兜底。
+        if (typeof runtime.list !== 'function')
+            return runtime;
+        if (!spawnMount) {
+            try {
+                const mod = req('@deepseek-ai/dsh-subagent-spawn-in-process');
+                if (!mod || typeof mod.apply !== 'function')
+                    throw new Error('模块未导出 apply(ctx, config)（版本不匹配？）');
+                mod.apply(ctx, { providerName: 'spawn' });
+                spawnMount = { ok: true };
+            }
+            catch (e) {
+                spawnMount = {
+                    ok: false,
+                    error: 'spawn provider 不可用：宿主没有注册它，本插件挂载 @deepseek-ai/dsh-subagent-spawn-in-process 也失败（'
+                        + message(e) + '）。请在宿主 profile 挂载该包（本插件已声明为可选 peerDependency），或安装后重启 DSH。',
+                };
+            }
+        }
+        if (!spawnMount.ok)
+            throw new Error(spawnMount.error);
+        if (!hasSpawnProvider(runtime))
+            throw new Error('spawn provider 挂载后仍未出现在 ctx.subagents.list()（宿主版本不匹配？）');
+        return runtime;
+    }
+    async function runOnce(parentAgent, p, task, signal) {
+        const runtime = await ensureSpawnProvider();
+        // 官方签名：start(name, request) —— name = ctx.subagents 上的 provider 注册名。
+        const run = await runtime.start('spawn', {
+            label: p.name,
+            parent: parentAgent,
+            // 官方 SubagentStartRequest.signal 为必填：调用方缺省时给一个永不中止的信号，不传 undefined。
+            signal: signal ?? new AbortController().signal,
+            prompt: [{ type: 'text', text: task }],
+            persona: p.body,
+            // 工具白/黑名单 → 官方 ToolRestriction（`deny` 优先级高于 `allow`；未知名官方会直接拒绝启动，
+            // 所以选择器给的是「全体预设工具并集」，见 index.ts presetToolCandidates）。
+            ...((p.tools?.length || p.toolsDeny?.length)
+                ? { toolFilter: { ...(p.tools?.length ? { allow: p.tools } : {}), ...(p.toolsDeny?.length ? { deny: p.toolsDeny } : {}) } }
+                : {}),
+            maxDepth: 1,
+            // provider 与 model 是模型路由的两半：DSH 的 resolveModel(provider, model) 不做
+            // `provider/model` 字符串拆分，只改 model 会落在**主会话的 provider** 上——跨来源
+            // 指定模型（如 sensenova 的 sensenova-6.8-flash-lite）必须两个键一起给。
+            ...(p.provider || p.model
+                ? { agentOptions: { ...(p.provider ? { provider: p.provider } : {}), ...(p.model ? { model: p.model } : {}) } }
+                : {}),
+        });
+        try {
+            const result = await run.result; // 官方契约：child 级失败不 reject（stopReason 体现）
+            const text = (result.output ?? [])
+                .map((b) => (b && typeof b === 'object' && typeof b.text === 'string' ? b.text : ''))
+                .join('').trim();
+            // 官方 SubagentResult 的诊断字段是 `diagnostic`（旧代码读 .detail 恒空 → 失败时模型只见空输出）。
+            const diagnostic = result.diagnostic ? `\n\n[provider] ${String(result.diagnostic)}` : '';
+            return {
+                text: ((text || '(子代理无输出)') + diagnostic).slice(0, RESULT_MAX),
+                runId: String(run.id ?? ''),
+                stopReason: String(result.stopReason ?? 'completed'),
+            };
+        }
+        finally {
+            await run.dispose().catch(() => { }); // 官方前台语义：collection 后即弃
+        }
+    }
+    // v1 串行：同一时刻至多一个子代理运行（设计 §3.2）。
+    let chain = Promise.resolve();
+    const runSerial = (parentAgent, p, task, signal) => {
+        const queued = chain.then(() => runOnce(parentAgent, p, task, signal), () => runOnce(parentAgent, p, task, signal));
+        chain = queued.catch(() => undefined);
+        return queued;
+    };
+    const ops = {
+        'subagent-list': async () => {
+            const docs = await list();
+            return {
+                ok: true,
+                subagents: docs.map((p) => ({ name: p.name, description: p.description, provider: p.provider ?? null, model: p.model ?? null, tools: p.tools ?? null, toolsDeny: p.toolsDeny ?? null })),
+            };
+        },
+        'subagent-get': async (args) => {
+            const name = String((args && args.name) || '').trim();
+            const docs = await list();
+            const p = docs.find((d) => d.name === name);
+            if (!p)
+                return { ok: false, error: `人设不存在: ${name}` };
+            return { ok: true, persona: { name: p.name, description: p.description, provider: p.provider ?? '', model: p.model ?? '', tools: p.tools ?? [], toolsDeny: p.toolsDeny ?? [], body: p.body } };
+        },
+        'subagent-create': async (args) => {
+            const name = String((args && args.name) || '').trim();
+            if (!validPersonaName(name))
+                return { ok: false, error: `人设名不合法: ${name || '(空)'}（≤64 字符、不含路径分隔符与 < > : " | ? *、不以 . 开头）` };
+            const target = join(dir, name + '.md');
+            const exists = await readFile(target, 'utf8').then(() => true).catch(() => false);
+            if (exists)
+                return { ok: false, error: `人设已存在: ${name}` };
+            // 目录必须先建：v0.4 起人设落在 hub 内的 agents/，全新安装时它还不存在
+            // （旧版本落在 $DSH_HOME/subagents/，那个目录一直有人建，所以这个坑以前不显形）。
+            try {
+                await mkdir(dir, { recursive: true });
+            }
+            catch (e) {
+                return { ok: false, error: `创建人设目录失败: ${dir}（${message(e)}）` };
+            }
+            await writeFile(target, serializePersona(args), 'utf8');
+            cache = null;
+            return { ok: true, name };
+        },
+        'subagent-update': async (args) => {
+            const name = String((args && args.name) || '').trim();
+            if (!validPersonaName(name))
+                return { ok: false, error: `人设名不合法: ${name || '(空)'}` };
+            const target = join(dir, name + '.md');
+            const exists = await readFile(target, 'utf8').then(() => true).catch(() => false);
+            if (!exists)
+                return { ok: false, error: `人设不存在: ${name}` };
+            await writeFile(target, serializePersona(args), 'utf8');
+            cache = null;
+            return { ok: true, name };
+        },
+        'subagent-delete': async (args) => {
+            const name = String((args && args.name) || '').trim();
+            if (!validPersonaName(name))
+                return { ok: false, error: `人设名不合法: ${name || '(空)'}` };
+            await rm(join(dir, name + '.md')).catch(() => { });
+            cache = null;
+            return { ok: true, name };
+        },
+        /**
+         * 导入人设（.md / .zip）：一个 .md 一个人设，文件名（去扩展名）= 人设名；
+         * zip 内任意层级的 .md 都按文件名导入（目录层级忽略）。同名**跳过并报告**，不覆盖既有文件。
+         * 部分成功：单条失败只记 skipped。
+         */
+        'subagent-import': async (args) => {
+            const files = args && args.files;
+            if (!Array.isArray(files) || !files.length)
+                return { ok: false, error: '没有选择要导入的文件' };
+            const { entries, problems } = expandUploads(files);
+            const planned = planPersonaImport(entries);
+            const skipped = [...problems, ...planned.problems];
+            const imported = [];
+            for (const target of planned.targets) {
+                if (!validPersonaName(target.name)) {
+                    skipped.push({ name: target.name, reason: '人设名不合法（≤64 字符、不含路径分隔符与 < > : " | ? *、不以 . 开头）' });
+                    continue;
+                }
+                const text = Buffer.from(target.bytes).toString('utf8').replace(/^\uFEFF/, '');
+                if (!text.trim()) {
+                    skipped.push({ name: target.name, reason: '内容为空，已跳过' });
+                    continue;
+                }
+                const targetPath = join(dir, target.name + '.md');
+                const exists = await readFile(targetPath, 'utf8').then(() => true).catch(() => false);
+                if (exists) {
+                    skipped.push({ name: target.name, reason: '同名已存在（已跳过）' });
+                    continue;
+                }
+                try {
+                    await mkdir(dir, { recursive: true });
+                    await writeFile(targetPath, text, 'utf8');
+                }
+                catch (e) {
+                    skipped.push({ name: target.name, reason: '写入失败：' + message(e) });
+                    continue;
+                }
+                imported.push(target.name);
+            }
+            if (imported.length)
+                cache = null;
+            return { ok: true, imported, skipped };
+        },
+    };
+    return { list, runSerial, ops, writeOps: new Set(['subagent-create', 'subagent-update', 'subagent-delete', 'subagent-import']) };
+}
+function validPersonaName(name) {
+    return name.length > 0 && name.length <= 64 && !name.startsWith('.') && !/[\\/<>:"|?*]/.test(name);
+}
+/** 人设文件序列化：frontmatter 只写用户填过的键；正文 = 人设提示词。 */
+export function serializePersona(args) {
+    const description = String((args && args.description) || '').replace(/\r?\n/g, ' ').trim();
+    const provider = String((args && args.provider) || '').trim();
+    const model = String((args && args.model) || '').trim();
+    const toList = (v) => (Array.isArray(v) ? v.map((x) => String(x).trim()).filter(Boolean) : []);
+    const tools = toList(args?.tools);
+    // 黑名单字段兼容两种入参名：toolsDeny（UI/camel）与 tools_deny（snake）。
+    const toolsDeny = toList(args?.toolsDeny ?? args?.tools_deny);
+    const body = String((args && args.body) ?? '').trim();
+    const lines = ['---'];
+    if (description)
+        lines.push('description: ' + description);
+    if (provider)
+        lines.push('provider: ' + provider);
+    if (model)
+        lines.push('model: ' + model);
+    if (tools.length)
+        lines.push('tools: ' + tools.join(', '));
+    if (toolsDeny.length)
+        lines.push('toolsDeny: ' + toolsDeny.join(', '));
+    lines.push('---', '', body, '');
+    return lines.join('\n');
+}

package/lib/subagents/tools.js

@@ -0,0 +1,62 @@
+export function text(v) {
+    return [{ type: 'text', text: v }];
+}
+/** 场景绑定校验（设计 §3.3）：启用场景的 subagents 并集；空并集 = 全部可用。 */
+export async function filterBySceneBinding(docs, enabledSceneLists) {
+    const bound = new Set(enabledSceneLists.flat());
+    if (!bound.size)
+        return { allowed: docs, reason: null };
+    const allowed = docs.filter((d) => bound.has(d.name));
+    return { allowed, reason: allowed.length ? null : `当前启用场景的子智能体绑定: ${[...bound].join('、')}` };
+}
+export function defineSubagentListTool(subagents) {
+    return {
+        name: 'subagent_list',
+        description: 'List available personas (pre-configured subagent profiles) with their descriptions. Call before subagent_run.',
+        parameters: {
+            scene: { type: 'string', description: 'Optional scene name filter (informational; the tool already reflects scene binding).' },
+        },
+        output: {
+            schema: { type: 'string' },
+            render: (_a, v) => text(String(v)),
+        },
+        async execute() {
+            const { allowed, reason } = await filterBySceneBinding(await subagents.list(), await subagents.sceneLists());
+            const lines = allowed.map((p) => '- ' + p.name + ' — ' + (p.description || '(无描述)'));
+            return '人设子智能体（' + allowed.length + '）：\n' + (lines.join('\n') || '(无)') + (reason ? '\n注意：' + reason : '');
+        },
+    };
+}
+export function defineSubagentRunTool(subagents) {
+    return {
+        name: 'subagent_run',
+        description: 'Run a named persona as a one-shot subagent: it receives the persona as its own system prompt, works on `task` in a fresh context, and returns only its final output. Discover personas with subagent_list first. Each run is stateless and ephemeral; it does not see this conversation.',
+        parameters: {
+            agent: { type: 'string', required: true, description: 'Persona name from subagent_list.' },
+            task: { type: 'string', required: true, description: 'Complete, self-contained task for the subagent (include all context it needs).' },
+        },
+        output: {
+            schema: { type: 'string' },
+            render: (_a, v) => text(String(v)),
+        },
+        async execute(args, exec) {
+            const name = String((args && args.agent) || '').trim();
+            const task = String((args && args.task) || '').trim();
+            if (!task)
+                throw new Error('task 不能为空');
+            // 官方 SubagentStartRequest.parent 必填：调用方 agent 缺失时给结构化错误，不把 undefined 透传下去。
+            if (!exec || !exec.agent)
+                throw new Error('缺少调用方 agent（exec.agent 不可用）：无法创建子代理运行');
+            const docs = await subagents.list();
+            const { allowed, reason } = await filterBySceneBinding(docs, await subagents.sceneLists());
+            const persona = allowed.find((p) => p.name === name);
+            if (!persona) {
+                const available = allowed.map((p) => p.name).join('、') || '(无)';
+                throw new Error('人设不可用: ' + name + (reason ? '（' + reason + '）' : '（可用: ' + available + '）'));
+            }
+            const r = await subagents.runSerial(exec.agent, persona, task, exec.signal);
+            const prefix = r.stopReason && r.stopReason !== 'completed' ? `[stopReason: ${r.stopReason}]\n` : '';
+            return prefix + r.text;
+        },
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin-tool-management",
-  "version": "0.2.0",
-  "description": "DSH plugin: unified MCP, Skills, AGENTS.md presets, archived-session and scene-memory manager — Settings UI + HTTP API + model-facing skill_mcp_manager_* / skill_manager_* / rule_manager_* tools. Install with one command: dsh plugin --profile web add dsh-plugin-tool-management@latest",
+  "version": "0.5.1",
+  "description": "DSH plugin: one settings panel for MCP servers, Skills, AGENTS.md presets, archived sessions and scene memories — plus scene memory injected into the system prompt and one-shot persona subagents. Settings UI + HTTP API + 14 model tools (skill_mcp_manager_*, skill_manager_*, agentsmd_*, rule_manager_*, subagent_*). Install with one command: dsh plugin --profile web add dsh-plugin-tool-management@latest",
   "repository": {
     "type": "git",
     "url": "https://github.com/ouli-1242/dsh-plugin-tool-management"
@@ -35,7 +35,9 @@
     "build": "tsc -p tsconfig.json && node scripts/sync-client.mjs",
     "build:client": "node scripts/sync-client.mjs",
     "prepublishOnly": "npm run build",
-    "lint": "node --check lib/client.js && node --check lib/index.js"
+    "lint": "node --check lib/client.js && node --check lib/index.js",
+    "check:i18n": "node scripts/check-i18n.mjs src/client.js",
+    "test": "npm run build && npm run check:i18n && node --test test/archive.test.mjs test/import.test.mjs test/approval-policy.test.mjs test/subagent-scene.test.mjs test/subagent-persona.test.mjs test/hub-layout.test.mjs test/skills-state.test.mjs test/skills-delete.test.mjs test/skills-source-remove.test.mjs test/client-exports.test.mjs test/client-render.test.mjs"
   },
   "keywords": [
     "dsh",
@@ -66,14 +68,21 @@
     "@deepseek-ai/dsh-spill-local": ">=0.1.5-rc.2 <0.2.0-0",
     "@deepseek-ai/dsh-session-projection-cache": ">=0.1.5-rc.2 <0.2.0-0",
     "@deepseek-ai/dsh-storage-domain": ">=0.1.5-rc.2 <0.2.0-0",
+    "@deepseek-ai/dsh-subagent-spawn-in-process": ">=0.1.5-rc.2 <0.2.0-0",
     "react": "^18.2.0"
   },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-subagent-spawn-in-process": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-session-projection-cache": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-spill-local": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-storage-domain": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-tools": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-user-approval": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-workspace": "^0.1.5-rc.2",
     "@types/node": "^24.0.0",
     "typescript": "^6.0.0"

package/screenshots.json

@@ -1,7 +1,9 @@
 [
-  "docs/images/mcp.png",
-  "docs/images/skills.png",
-  "docs/images/agents-md.png",
-  "docs/images/history.png",
-  "docs/images/场景记忆.png"
+  "docs/images/MCP.png",
+  "docs/images/技能.png",
+  "docs/images/提示词.png",
+  "docs/images/会话.png",
+  "docs/images/场景.png",
+  "docs/images/记忆.png",
+  "docs/images/子智能体.png"
 ]