dsh-agent-toolkit 0.2.1 → 0.2.3

package/lib/index.d.ts

@@ -47,6 +47,21 @@ interface BotsModuleConfig {
   errorDetailMaxChars: number;
 }
 //#endregion
+//#region src/agents/team-preset.d.ts
+/** 本功能的可调配置（Config schema 在 ../index.ts）。 */
+interface AgentTeamPresetConfig {
+  /** 总开关：false 时启动不生成/刷新 preset。 */
+  enabled: boolean;
+  /** 生成的 preset id（即目录名）。 */
+  id: string;
+  /** 源 preset id，读其 composition 做派生。 */
+  source: string;
+  /** preset.yml 的显示名。 */
+  name: string;
+  /** preset.yml 的描述。 */
+  description: string;
+}
+//#endregion
 //#region src/index.d.ts
 declare const name = "dsh-agent-toolkit";
 declare const inject: string[];
@@ -62,6 +77,7 @@ interface Config {
   provider: string;
   toolName: string;
   feishu: BotsModuleConfig;
+  agentTeamPreset: AgentTeamPresetConfig;
 }
 /** layers/rules 的 schemastery schema 照归档 prompt-stack/src/index.ts:21-41 逐字段平移（含 overrides transform hack）。 */
 declare const Config: z<unknown, Config>;

package/lib/index.js

@@ -1,16 +1,16 @@
 import z from "@deepseek-ai/schemastery";
 import { z as z$1 } from "zod";
 import { defineDomain, domainTable } from "@deepseek-ai/dsh-storage-domain";
-import { readFile, readdir } from "node:fs/promises";
-import { join } from "node:path";
+import { access, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
 import yaml from "js-yaml";
-import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
+import { expandHomePath, resolveDshHome } from "@deepseek-ai/dsh-home-paths";
 import { defineTool } from "@deepseek-ai/dsh-tools";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
 import { existsSync } from "node:fs";
 import { SessionId } from "@deepseek-ai/dsh-session";
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
 import * as lark from "@larksuiteoapi/node-sdk";
-import { createUserMessage } from "@deepseek-ai/dsh-llm";
 import { randomBytes, randomUUID } from "node:crypto";
 import { setupUsage } from "@dsh-agent-toolkit/token-usage";
 //#region src/agents/store.ts
@@ -1612,6 +1612,59 @@ function setupAgentsApi(ctx, deps) {
 	});
 }
 //#endregion
+//#region src/agents/create-command.ts
+/** 拼装 /create-agent 的引导文本（模型面契约，文案为规格锁定内容）。 */
+function buildCreateAgentGuidance(input) {
+	const lines = [
+		"# 交互式创建 Agent 团队成员",
+		"",
+		"## 工作流（三步）",
+		"1. 澄清需求：需求不明确时用 ask_user_question 向用户提问，整个流程提问总次数不超过 5 次，不重复问已确认的信息；",
+		"2. 生成推荐并请用户确认：推荐 id / name / description / persona / tools 五个字段（id 是团队内唯一标识，name 是显示名，description 是职责一句话描述，persona 是系统提示词个性段，tools 是工具白名单）；",
+		"3. 迭代：用户有修改意见时按意见修订名称、描述、个性和工具后再次确认，直到用户明确确认。"
+	];
+	if (input.requirement !== "") lines.push("", "## 用户初始需求", `用户已在命令中提供初始需求：「${input.requirement}」。请据此减少提问轮次，仅就不明确的点提问。`);
+	lines.push("", "## 现有 Agent id（不可复用）", input.agentIds.join(", "), "id 规则：小写字母开头，仅含小写字母/数字/连字符（[a-z0-9-]），最长 32 字符。", "", "## 可用工具清单", `原生工具：${NATIVE_TOOL_NAMES.join(", ")}`, `全局工具：${input.globalTools.join(", ")}`, "省略 tools 字段表示不限制（Agent 可使用全部工具）。一旦给出白名单，该 Agent 只有列出的工具可用：通常应保留原生工具，否则失去读文件/搜索/执行命令等基本能力（最终取舍按需求判断，如只读角色可去掉 write/edit）。");
+	if (input.origin === void 0) lines.push("", "## 落库", "当前宿主无 web 服务，无法自动落库。用户确认推荐后，请把最终配置完整输出给用户，并提示其打开 Agents 面板按推荐内容手动创建。");
+	else lines.push("", "## 落库（用户明确确认后执行）", "用你的 shell 工具调用 Agents 面板同一 HTTP 端点完成创建：", `1. 先 GET ${input.origin}/dsh-agent-toolkit/api/agents 复核所选 id 仍未被占用；`, `2. 再 PUT ${input.origin}/dsh-agent-toolkit/api/agents/<id>，请求体为 JSON（不要在 body 中携带 id 或 builtin 字段）：`, "   {\"name\":\"...\",\"description\":\"...\",\"persona\":\"...\",\"tools\":{\"allow\":[\"...\"]}}", "   （description/persona/tools 均可省略；省略 tools 表示不限制）", "3. curl 示例（Windows 的 pwsh 里用 curl.exe）：", `   curl.exe -s -X PUT "${input.origin}/dsh-agent-toolkit/api/agents/<id>" -H "Content-Type: application/json" -d "{\\"name\\":\\"...\\"}"`, `4. 返回 200 后必须再 GET ${input.origin}/dsh-agent-toolkit/api/agents，在返回列表中找到该 id 的记录，把它的 name/description/persona/tools 关键字段展示给用户，作为落库证据；`, "5. 落库成功后告知用户可在 Agents 面板查看、并可被 team_delegate 委派；任一步返回 4xx 则把错误信息展示给用户，修正后重试。");
+	return lines.join("\n");
+}
+/**
+* 注册 /create-agent。webServer 为可选服务按仓库规则经 ctx.get 读取（不进 inject），
+* 缺席（headless/CLI）时 origin 为 undefined，引导文本落库节降级为手动创建指引。
+*
+* 命令结果（command/done）是 log-only、不进模型：引导文本必须经 agent.followup
+* 投递为 user 消息驱动主 Agent（与 channels/inbound.ts 同一机制），命令卡只回执短文案。
+*/
+function setupCreateAgentCommand(ctx, deps) {
+	ctx.commands.register({
+		name: "create-agent",
+		description: "交互式创建 Agent 团队成员：访谈澄清需求 → 推荐配置 → 确认后经面板 API 落库",
+		input: { hint: "初始需求描述，可空" },
+		handler: ({ rawInput, agent }) => {
+			const webServer = ctx.get("webServer");
+			const origin = webServer === void 0 ? void 0 : `http://127.0.0.1:${webServer.port}`;
+			const text = buildCreateAgentGuidance({
+				requirement: rawInput.trim(),
+				agentIds: deps.registry.list().map((agent) => agent.id),
+				globalTools: deps.listTools(),
+				origin
+			});
+			agent.followup(createUserMessage({
+				content: [{
+					type: "text",
+					text
+				}],
+				source: { kind: "user" }
+			}));
+			return {
+				kind: "success",
+				text: "已向主 Agent 发出创建 Agent 引导，请继续对话完成访谈与确认。"
+			};
+		}
+	});
+}
+//#endregion
 //#region src/channels/agent-setup.ts
 /** bot 会话角色 persona 的 scoped 段名：与全局 persona 层同名，scoped 注册即 shadow 覆盖主 Agent persona。 */
 const TOOLKIT_PERSONA_SECTION = "prompt-stack:persona";
@@ -2213,20 +2266,23 @@ const feishuChannel = {
 			appSecret: bot.secret
 		}));
 		const dedup = new MessageDedup();
-		const dispatcher = new lark.EventDispatcher({}).register({ "im.message.receive_v1": async (data) => {
-			const parsed = parseMessageEvent(data);
-			if (parsed === null || !dedup.check(parsed.messageId)) return;
-			const reply = new FeishuReplyHandle(api, parsed.chatId, tunables, log);
-			io.onMessage({
-				botId: bot.record.id,
-				chatId: parsed.chatId,
-				userId: parsed.userId,
-				messageId: parsed.messageId,
-				text: parsed.text,
-				reply,
-				ackProcessing: makeAck(api, parsed.messageId, tunables.processingReactionEmoji)
-			});
-		} });
+		const dispatcher = new lark.EventDispatcher({}).register({
+			"im.message.message_read_v1": async () => void 0,
+			"im.message.receive_v1": async (data) => {
+				const parsed = parseMessageEvent(data);
+				if (parsed === null || !dedup.check(parsed.messageId)) return;
+				const reply = new FeishuReplyHandle(api, parsed.chatId, tunables, log);
+				io.onMessage({
+					botId: bot.record.id,
+					chatId: parsed.chatId,
+					userId: parsed.userId,
+					messageId: parsed.messageId,
+					text: parsed.text,
+					reply,
+					ackProcessing: makeAck(api, parsed.messageId, tunables.processingReactionEmoji)
+				});
+			}
+		});
 		const ws = new lark.WSClient({
 			appId,
 			appSecret: bot.secret,
@@ -2289,66 +2345,6 @@ const projectBotDomain = defineDomain({
 function bindingKey(botId, chatId) {
 	return `${botId}:${chatId}`;
 }
-//#endregion
-//#region src/channels/inbound.ts
-/** 入站：指令分流 → 路由 → 单 in-flight 准入 → 表情回复 → followup 投递。 */
-var Inbound = class {
-	deps;
-	constructor(deps) {
-		this.deps = deps;
-	}
-	onMessage(msg) {
-		this.handle(msg).catch(async (error) => {
-			this.deps.onError(`[project-bot] 入站处理失败：${error instanceof Error ? error.message : String(error)}`);
-			await msg.reply.notice("处理失败，请稍后再试").catch(() => void 0);
-		});
-	}
-	async handle(msg) {
-		const bot = this.deps.bots.get(msg.botId);
-		if (bot === void 0) return;
-		const directive = parseDirective(msg.text);
-		if (directive === "new") {
-			await this.deps.router.reset(bot, msg.chatId, msg.reply);
-			await msg.reply.notice("已开启新会话");
-			return;
-		}
-		if (directive === "stop") {
-			const rt = this.deps.router.lookup(bot.id, msg.chatId);
-			if (rt?.inflight !== void 0) {
-				rt.agent.cancel();
-				await msg.reply.notice("已请求停止当前任务");
-			} else await msg.reply.notice("当前没有进行中的任务");
-			return;
-		}
-		if (directive === "status") {
-			const rt = this.deps.router.lookup(bot.id, msg.chatId);
-			await msg.reply.notice(rt === void 0 ? `项目：${bot.project}\n会话：未创建（发送消息即创建）` : `项目：${bot.project}\n会话：${rt.sessionId}\n状态：${rt.inflight !== void 0 ? "处理中" : "空闲"}`);
-			return;
-		}
-		const rt = await this.deps.router.ensure(bot, msg.chatId, msg.reply);
-		if (rt.inflight !== void 0) {
-			await msg.reply.notice("上一条还在处理中，请稍候（或发送 /stop 取消）");
-			return;
-		}
-		rt.inflight = { ack: void 0 };
-		rt.inflight.ack = await msg.ackProcessing().catch(() => void 0) ?? void 0;
-		const message = createUserMessage({
-			content: [{
-				type: "text",
-				text: msg.text
-			}],
-			source: { kind: "user" }
-		});
-		try {
-			rt.agent.followup(message);
-		} catch (error) {
-			const ack = rt.inflight.ack;
-			rt.inflight = void 0;
-			await ack?.();
-			throw error;
-		}
-	}
-};
 /** 向段序列追加内容：与尾段同类则合并，异类开新段。 */
 function appendToSegments(segments, kind, text) {
 	const tail = segments[segments.length - 1];
@@ -2466,6 +2462,67 @@ var Outbound = class {
 	}
 };
 //#endregion
+//#region src/channels/inbound.ts
+/** 入站：指令分流 → 路由 → 单 in-flight 准入 → 表情回复 → followup 投递。 */
+var Inbound = class {
+	deps;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	onMessage(msg) {
+		this.handle(msg).catch(async (error) => {
+			const detail = truncateDetail(error instanceof Error ? error.message : String(error), this.deps.maxErrorDetailChars);
+			this.deps.onError(`[project-bot] 入站处理失败：${detail}`);
+			await msg.reply.notice(`处理失败：${detail}`).catch(() => void 0);
+		});
+	}
+	async handle(msg) {
+		const bot = this.deps.bots.get(msg.botId);
+		if (bot === void 0) return;
+		const directive = parseDirective(msg.text);
+		if (directive === "new") {
+			await this.deps.router.reset(bot, msg.chatId, msg.reply);
+			await msg.reply.notice("已开启新会话");
+			return;
+		}
+		if (directive === "stop") {
+			const rt = this.deps.router.lookup(bot.id, msg.chatId);
+			if (rt?.inflight !== void 0) {
+				rt.agent.cancel();
+				await msg.reply.notice("已请求停止当前任务");
+			} else await msg.reply.notice("当前没有进行中的任务");
+			return;
+		}
+		if (directive === "status") {
+			const rt = this.deps.router.lookup(bot.id, msg.chatId);
+			await msg.reply.notice(rt === void 0 ? `项目：${bot.project}\n会话：未创建（发送消息即创建）` : `项目：${bot.project}\n会话：${rt.sessionId}\n状态：${rt.inflight !== void 0 ? "处理中" : "空闲"}`);
+			return;
+		}
+		const rt = await this.deps.router.ensure(bot, msg.chatId, msg.reply);
+		if (rt.inflight !== void 0) {
+			await msg.reply.notice("上一条还在处理中，请稍候（或发送 /stop 取消）");
+			return;
+		}
+		rt.inflight = { ack: void 0 };
+		rt.inflight.ack = await msg.ackProcessing().catch(() => void 0) ?? void 0;
+		const message = createUserMessage({
+			content: [{
+				type: "text",
+				text: msg.text
+			}],
+			source: { kind: "user" }
+		});
+		try {
+			rt.agent.followup(message);
+		} catch (error) {
+			const ack = rt.inflight.ack;
+			rt.inflight = void 0;
+			await ack?.();
+			throw error;
+		}
+	}
+};
+//#endregion
 //#region src/channels/ports.ts
 /** 从 bot 记录提取创作期注入（主 Agent 绑定形态）。 */
 function hooksOf(bot) {
@@ -2606,6 +2663,7 @@ var BotRuntime = class {
 		this.inbound = new Inbound({
 			router: this.router,
 			bots: deps.bots,
+			maxErrorDetailChars: deps.maxErrorDetailChars,
 			onError: (m) => deps.log.warn(m)
 		});
 		this.outbound = new Outbound(this.sessions, (m) => deps.log.warn(m), deps.maxErrorDetailChars);
@@ -2940,6 +2998,18 @@ function createApiHandler(deps) {
 //#endregion
 //#region src/bots/register-app.ts
 /** 扫码一键创建飞书应用：lark.registerApp（OAuth 2.0 Device Authorization Grant）的状态机封装。 */
+/** 扫码创建应用时申请的权限/事件（流式卡片 + 收发消息 + 表情 + 通讯录基础信息）。
+* 故意不加 as const：readonly 元组不可赋值给 SDK AppAddons 的 mutable string[]，
+* 否则 bots/index.ts 的 lark.registerApp(options) 透传会 typecheck 失败。 */
+const FEISHU_REGISTER_APP_ADDONS = {
+	scopes: { tenant: [
+		"im:message",
+		"im:message:send_as_bot",
+		"cardkit:card:write",
+		"contact:user.base:readonly"
+	] },
+	events: { items: { tenant: ["im.message.receive_v1"] } }
+};
 var RegisterAppService = class {
 	deps;
 	sessions = /* @__PURE__ */ new Map();
@@ -2960,6 +3030,7 @@ var RegisterAppService = class {
 		this.sessions.set(id, entry);
 		this.deps.registerApp({
 			signal: controller.signal,
+			addons: FEISHU_REGISTER_APP_ADDONS,
 			onQRCodeReady: (info) => {
 				entry.state = {
 					status: "pending",
@@ -3141,6 +3212,125 @@ function setupBots(ctx, config, deps) {
 	});
 }
 //#endregion
+//#region src/agents/team-preset.ts
+/**
+* Agent 团队 preset 自动生成：派生宿主当前 shipped standard composition，
+* 文本级禁用 subagent 工具族 4 个行，写入首个 trust=user 的 preset root。
+* 设计：docs/superpowers/specs/2026-09-02-agent-team-preset-design.md
+*/
+/** 禁用目标行：覆盖与 team_delegate 竞争/配套的 5 个模型可见工具所属的 4 个行。 */
+const TEAM_PRESET_DISABLED_ROWS = [
+	"tool-subagent",
+	"tool-subagent-fork",
+	"tool-subagent-control",
+	"tool-subagent-list-agents"
+];
+/**
+* 文本级锚点改写：对 4 个目标行各插入一行 `disabled: true`（缩进 = 锚点缩进 + 2 空格）。
+* 锚点是整行精确匹配 `- id: <行id>`（忽略首尾空白），防 tool-subagent 误中
+* tool-subagent-fork / tool-subagent-control 前缀；锚点所属块内（锚点行之后、
+* 首个缩进 <= 锚点缩进的非空行之前）已有 `disabled:` 键则跳过——既幂等，也避免
+* 与宿主已有的 `disabled: !!js ...` 撞出 YAML 重复键。锚点缺失 warn 并跳过该锚点，
+* 其余照常。除插入行外文本逐字节不变。
+*/
+function disableSubagentRows(source, warn) {
+	const lines = source.split("\n");
+	for (const row of TEAM_PRESET_DISABLED_ROWS) {
+		const anchor = `- id: ${row}`;
+		const index = lines.findIndex((line) => line.trim() === anchor);
+		if (index === -1) {
+			warn(`dsh-agent-toolkit: agent-team preset 锚点行 "${anchor}" 在源 composition 中缺失，已跳过`);
+			continue;
+		}
+		const indent = lines[index].length - lines[index].trimStart().length;
+		let hasDisabled = false;
+		for (let i = index + 1; i < lines.length; i += 1) {
+			const line = lines[i];
+			if (line.trim() === "") continue;
+			if (line.length - line.trimStart().length <= indent) break;
+			if (/^\s*disabled\s*:/.test(line)) {
+				hasDisabled = true;
+				break;
+			}
+		}
+		if (hasDisabled) continue;
+		lines.splice(index + 1, 0, `${" ".repeat(indent + 2)}disabled: true`);
+	}
+	return lines.join("\n");
+}
+const COMPOSITION_FILE = "agent.cordis.yml";
+const METADATA_FILE = "preset.yml";
+/**
+* 生成目录的归属标记：无此标记的同名目录视为用户手工 preset，不覆盖。
+* 标记必须在 mkdir 后最先写入（marker-first）：这样写 composition/metadata 失败留下的是
+* 带标记的半成品目录，下次启动会被正常重写自愈；若最后才写标记，则半成品目录无标记、
+* 会被误判为用户手工 preset 而永久卡死不覆盖。
+*/
+const MARKER_FILE = ".generated-by";
+const MARKER_CONTENT = "dsh-agent-toolkit";
+/** 镜像宿主 PRESET_ID：preset id 即目录名，正则白名单是路径逃逸的 containment 边界。 */
+const PRESET_ID = /^[a-z0-9][a-z0-9-]*$/;
+const GENERATED_HEADER = "# 本文件由 dsh-agent-toolkit 自动生成，勿手改（每次启动重写）。\n";
+/**
+* 启动时生成/刷新 agent-team preset。所有失败路径 warn 降级，不影响插件其余功能。
+* 不设为默认 preset、卸载不删目录（可能有会话在用；composition 不引用 toolkit 行，
+* 残留 preset 自身仍可用）。每次启动重写：standing mount 按文件代际，重写只影响新会话。
+*/
+async function setupAgentTeamPreset(ctx, config) {
+	if (!config.enabled) return;
+	const warn = (msg) => {
+		ctx.logger.warn(msg);
+	};
+	const agentPresets = ctx.get("agentPresets", false);
+	if (agentPresets === void 0) return;
+	if (!PRESET_ID.test(config.id)) {
+		warn(`dsh-agent-toolkit: agentTeamPreset.id "${config.id}" 不是合法 preset id，跳过 agent-team 生成`);
+		return;
+	}
+	let source;
+	try {
+		source = await agentPresets.read(config.source);
+	} catch (error) {
+		warn(`dsh-agent-toolkit: 读取源 preset "${config.source}" 失败，跳过 agent-team 生成：${error instanceof Error ? error.message : String(error)}`);
+		return;
+	}
+	const root = agentPresets.roots.find((r) => r.trust === "user");
+	if (root === void 0) {
+		warn("dsh-agent-toolkit: preset roots 中无 trust=user 的目录，跳过 agent-team 生成");
+		return;
+	}
+	const composition = GENERATED_HEADER + disableSubagentRows(source, warn);
+	const dir = join(resolve(expandHomePath(root.path)), config.id);
+	try {
+		const markerPath = join(dir, MARKER_FILE);
+		let dirExists = true;
+		try {
+			await access(dir);
+		} catch {
+			dirExists = false;
+		}
+		if (dirExists) {
+			let marked = false;
+			try {
+				marked = (await readFile(markerPath, "utf8")).trim() === MARKER_CONTENT;
+			} catch {}
+			if (!marked) {
+				warn(`dsh-agent-toolkit: ${dir} 已存在且非本插件生成，不覆盖，跳过 agent-team 生成`);
+				return;
+			}
+		}
+		await mkdir(dir, { recursive: true });
+		await writeFile(markerPath, `${MARKER_CONTENT}\n`, "utf8");
+		await writeFile(join(dir, COMPOSITION_FILE), composition, "utf8");
+		await writeFile(join(dir, METADATA_FILE), yaml.dump({
+			name: config.name,
+			description: config.description
+		}, { lineWidth: -1 }), "utf8");
+	} catch (error) {
+		warn(`dsh-agent-toolkit: 写入 agent-team preset 失败（${dir}）：${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+//#endregion
 //#region src/index.ts
 const name = "dsh-agent-toolkit";
 const inject = [
@@ -3195,6 +3385,19 @@ const Config = z.object({
 		registerAppTimeoutMs: 6e5,
 		processingReactionEmoji: "OneSecond",
 		errorDetailMaxChars: 500
+	}),
+	agentTeamPreset: z.object({
+		enabled: z.boolean().default(true),
+		id: z.string().default("agent-team"),
+		source: z.string().default("standard"),
+		name: z.string().default("Agent 团队"),
+		description: z.string().default("Agent 团队模式：禁用原生 subagent 工具族，委派统一走 team_delegate 团队角色")
+	}).default({
+		enabled: true,
+		id: "agent-team",
+		source: "standard",
+		name: "Agent 团队",
+		description: "Agent 团队模式：禁用原生 subagent 工具族，委派统一走 team_delegate 团队角色"
 	})
 });
 async function apply(ctx, config) {
@@ -3241,9 +3444,10 @@ async function apply(ctx, config) {
 		active: activeRoutes,
 		routes: routesTable
 	});
+	const listTools = () => ctx.tools.schemas().map((s) => s.name);
 	setupAgentsApi(ctx, {
 		registry,
-		listTools: () => ctx.tools.schemas().map((s) => s.name),
+		listTools,
 		listProviders: () => ctx.llm.listProviders().map(({ id, name }) => ({
 			id,
 			name
@@ -3253,6 +3457,10 @@ async function apply(ctx, config) {
 			name
 		})))
 	});
+	setupCreateAgentCommand(ctx, {
+		registry,
+		listTools
+	});
 	setupPromptLayersApi(ctx, {
 		source: layerSource,
 		rules: config.rules,
@@ -3271,6 +3479,7 @@ async function apply(ctx, config) {
 			};
 		}
 	});
+	await setupAgentTeamPreset(ctx, config.agentTeamPreset);
 	if (config.modules.feishu) setupBots(ctx, config.feishu, { registry });
 	if (config.modules.usage) setupUsage(ctx, { timezone: config.timezone }, name);
 }