dsh-plugin-t-expert 0.1.0

package/lib/index.js

@@ -0,0 +1,686 @@
+/**
+ * T专家 host 插件：把 ~/.t-team/experts 里的专家名册接到 DSH。
+ *
+ * 提供：
+ *   - 工具 list_t_experts / summon_t_expert / summon_t_experts
+ *   - 设置段 t-team（enabled: 已启用的专家 slug）
+ *   - systemPrompt 段（只在父会话里说明 @ 召唤语义与工具用法）
+ *   - 服务 tTeamCatalog（远程服务用它读名册与 persona）
+ *
+ * 与其它专家插件并存：工具名、设置命名空间、服务名、remote 服务名都不重叠。
+ */
+import { homedir } from "node:os";
+import { existsSync, readFileSync } from "node:fs";
+import { stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import schema from "@deepseek-ai/schemastery";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import {
+  DEFAULT_DIVISIONS,
+  catalogDivisions,
+  divisionOf,
+  groupByDivision,
+  loadCatalog,
+  mapPool,
+  readPersona,
+  resolveExpert,
+  sanitize,
+  truncate,
+} from "./catalog.js";
+import { localized, NS, readLocale, renderList, renderSummonResults, t } from "./i18n.js";
+import { seedData } from "./bootstrap.js";
+import { registerTeamCommand } from "./command.js";
+import { createSquadService } from "./squads.js";
+import { checkPlan } from "./plan-check.js";
+import { findTeamByCaptain } from "./teams/state.js";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+// 路线 A：上游团队引擎已 vendor 进 lib/teams/（由 scripts/brand.mjs 从 vendor/dsh-agent-teams/upstream/
+// 改名生成：命令 /agent-teams → /t、工具 agent_teams_* → t_team_*），这里在 T专家 内部挂载它 ——
+// 安装 T专家 即自带团队引擎与团队面板，不再需要单独安装上游插件。
+import * as teamsEngine from "./teams/index.js";
+// 引擎自带的 /t 命令不注册（否则与 T专家 自己的 /t 撞名），但手势边界必须复用：
+// 它把 `/t --profile <小队> <目标>` 这条用户消息翻译成队长协议指令。
+import { installTTeamGestureBoundary } from "./teams/command.js";
+// 设置页「团队」标签复用引擎自己的快照收集与停止实现（不重写一套）。
+import { collectArchivedTeamsActivity, collectTeamsActivity } from "./teams/snapshot.js";
+import { haltTeamWork } from "./teams/tools.js";
+
+export const name = NS;
+export const inject = ["tools", "subagents", "systemPrompt", "settings", "commands"];
+
+/** 插件配置；root 默认指向 T专家 的固定资产目录。 */
+export const Config = schema.object({
+  root: schema.string().default(join(homedir(), ".t-team", "experts")),
+  zhRoot: schema.string().default(join(homedir(), ".t-team", "zh")),
+  provider: schema.string().default("spawn"),
+  /** 留空 = 自动扫描 root 下所有含 .md 的分区目录（上游新增分区不必改配置/代码）。 */
+  divisions: schema.array(schema.string()).default([]),
+  maxDepth: schema.natural(),
+});
+
+/** 供 remote 服务读取名册的服务名。 */
+export const CATALOG_SERVICE = "tTeamCatalog";
+/** 小队定义服务（设置页「小队」标签读写 teams.json）。 */
+export const SQUAD_SERVICE = "tTeamSquads";
+/** 团队运行服务（设置页「团队」标签列活动/归档团队、停止团队）。 */
+export const TEAM_SERVICE = "tTeamTeams";
+/** 设置命名空间（= 插件名）。 */
+export const SETTINGS_NAMESPACE = NS;
+
+const SUMMON_EXPERTS_MAX = 8;
+const SUMMON_EXPERTS_CONCURRENCY = 4;
+const SUMMON_TASK_MAX_CHARS = 8000;
+const DESCRIPTION_LIMIT = 120;
+
+const settingsSchema = schema.object({
+  enabled: schema.array(schema.string()).default([]),
+});
+
+export function apply(ctx, config) {
+  const locale = () => readLocale(ctx);
+  const maxDepth = config.maxDepth;
+
+  // ---- 首次启动播种：包内自带名册快照 → 可写数据目录（非破坏性，已有内容不动）----
+  // 必须在下面同步读取 t-team.config.json / teams.json 之前完成，否则首次安装会读到空配置。
+  const seeded = seedData({ root: config.root, zhRoot: config.zhRoot });
+  if (seeded.copied.length > 0) {
+    console.log(`[t-team] 已把包内名册快照播种到 ${dirname(config.root)}（${seeded.copied.join(", ")}）`);
+  }
+  if (!seeded.ok) {
+    console.warn(`[t-team] 名册快照播种失败，将按已有数据继续：${seeded.error}`);
+  }
+
+  // ---- 设置段（T专家 自己的命名空间，与其它插件不冲突）----
+  const scope = ctx.settings.register(SETTINGS_NAMESPACE, settingsSchema, {
+    base: { enabled: [] },
+    applies: "live",
+    validate: (value) => {
+      const list = value?.enabled;
+      if (!Array.isArray(list) || list.some((item) => typeof item !== "string")) {
+        throw new Error("t-team.enabled 必须是字符串数组");
+      }
+    },
+  });
+  const enabledSet = () => new Set(
+    (scope.get()?.enabled ?? []).filter((value) => typeof value === "string"),
+  );
+
+  // ---- 花名册加载 ----
+  let entries = [];
+  let effectiveDivisions = config.divisions.length > 0 ? config.divisions.slice() : DEFAULT_DIVISIONS.slice();
+  let divisionLabels = {};
+  let loaded = false;
+  let loading = null;
+  let stamp = "";
+  let loadError = null;
+
+  /**
+   * 名册指纹：source.json 与各分区目录 + 中文侧车文件的 mtime。
+   * sync.sh / sync-zh.py 每次都会写这些文件，所以上游更新后**无需重启**即可自动重载；
+   * 目录 mtime 同时覆盖「新增/删除专家」。
+   */
+  async function fingerprint() {
+    const mtimeOf = (path) => stat(path).then((info) => info.mtimeMs).catch(() => 0);
+    const parts = await Promise.all([
+      mtimeOf(config.root),
+      mtimeOf(join(dirname(config.root), "source.json")),
+      mtimeOf(join(config.zhRoot, "names.json")),
+      mtimeOf(join(config.zhRoot, "descriptions.json")),
+      mtimeOf(join(config.zhRoot, "divisions.json")),
+      ...effectiveDivisions.map((division) => mtimeOf(join(config.root, division))),
+    ]);
+    return parts.join("|");
+  }
+
+  async function load() {
+    try {
+      const catalog = await loadCatalog(config.root, config.divisions, { zhRoot: config.zhRoot });
+      entries = [...catalog.values()];
+      const discovered = catalogDivisions(catalog);
+      if (discovered.length > 0) effectiveDivisions = discovered;
+      divisionLabels = catalog.labels ?? {};
+      loadError = null;
+      loaded = true;
+      stamp = await fingerprint();      // 记录加载后的指纹
+    } catch (error) {
+      loadError = error instanceof Error ? error : new Error(String(error));
+      loaded = false;
+    }
+  }
+
+  async function ensureReady() {
+    const now = await fingerprint();
+    if (!loaded || now !== stamp) {
+      if (loading === null) {
+        loading = load().finally(() => {
+          loading = null;
+        });
+      }
+      await loading;
+    }
+    if (loadError !== null) throw loadError;
+  }
+  /** 可召唤/可展示的专家（排除重名冲突项）。 */
+  const usable = () => entries.filter((expert) => expert.conflict !== true);
+
+  // ---- 设置段修订号与写入 ----
+  const revision = () => {
+    const descriptor = ctx.settings.describe().find((item) => item.ns === SETTINGS_NAMESPACE);
+    if (descriptor === undefined) throw new Error(t(locale(), "error.settingsMissing"));
+    return descriptor.revision;
+  };
+
+  /** 客户端面板用的名册快照。 */
+  async function snapshot() {
+    await ensureReady();
+    const enabled = enabledSet();
+    return {
+      // 面板按 locale 取字段：name/description 为中文（缺译回退英文），nameEn/descriptionEn 恒为英文。
+      experts: usable().map((expert) => ({
+        slug: expert.slug,
+        name: expert.nameZh ?? expert.name,
+        nameEn: expert.nameEn,
+        description: expert.descriptionZh ?? expert.description,
+        descriptionEn: expert.descriptionEn,
+        emoji: expert.emoji,
+        division: expert.division,
+        divisionZh: divisionOf(expert.division, divisionLabels).zh,
+        divisionEn: divisionOf(expert.division, divisionLabels).en,
+        conflict: expert.conflict === true,
+      })),
+      enabled: [...enabled],
+      revision: revision(),
+    };
+  }
+
+  /** 按需读取一位专家的 persona 正文。 */
+  async function prompt(slug, division) {
+    await ensureReady();
+    const expert = usable().find((item) => item.slug === slug && item.division === division);
+    if (expert === undefined) throw new Error(`找不到专家：${slug}`);
+    return { prompt: await readPersona(expert) };
+  }
+
+  /** 整体替换启用列表（远程服务用）。 */
+  async function setEnabled(next, expectedRevision) {
+    const list = (Array.isArray(next) ? next : []).filter((item) => typeof item === "string");
+    const known = new Set(usable().map((expert) => expert.slug));
+    const unknown = list.filter((slug) => !known.has(slug));
+    if (unknown.length > 0) throw new Error(`未知专家 slug：${unknown.slice(0, 5).join(", ")}`);
+    await ctx.settings.mutate(SETTINGS_NAMESPACE, [{ op: "set", path: ["enabled"], value: list }], expectedRevision);
+    return { enabled: [...enabledSet()], revision: revision() };
+  }
+
+  const catalogService = { snapshot, prompt, setEnabled, root: config.root };
+  ctx.reflect.provide(CATALOG_SERVICE, catalogService);
+
+  // ---- 召唤 ----
+  async function runExpert(query, task, exec) {
+    const current = locale();
+    const taskText = String(task ?? "").trim();
+    if (taskText === "") throw new Error(t(current, "error.taskEmpty"));
+    if ([...taskText].length > SUMMON_TASK_MAX_CHARS) {
+      throw new Error(t(current, "error.taskTooLong", { limit: SUMMON_TASK_MAX_CHARS }));
+    }
+    if (exec.agent === undefined) throw new Error(t(current, "error.summonRequiresAgent"));
+
+    const provider = ctx.subagents.getProvider(config.provider);
+    if (provider === undefined) {
+      throw new Error(t(current, "error.providerMissing", { provider: config.provider }));
+    }
+    if (provider.capabilities.persona !== true) {
+      throw new Error(t(current, "error.providerNoPersona", { provider: config.provider }));
+    }
+    if (provider.capabilities.toolFilter !== true) {
+      throw new Error(t(current, "error.providerNoToolFilter", { provider: config.provider }));
+    }
+    if (maxDepth !== undefined && provider.capabilities.depthLimit !== true) {
+      throw new Error(t(current, "error.providerNoMaxDepth", { provider: config.provider }));
+    }
+
+    await ensureReady();
+    const expert = resolveExpert(usable(), query, current);
+    if (!enabledSet().has(expert.slug)) {
+      throw new Error(t(current, "error.expertDisabled", { name: localized(expert, current).name }));
+    }
+    const persona = await readPersona(expert, current);
+    const run = await ctx.subagents.start(config.provider, {
+      label: `t-team:${expert.slug}`,
+      prompt: [{ type: "text", text: taskText }],
+      parent: exec.agent,
+      persona: sanitize(persona),
+      toolFilter: { deny: ["summon_t_expert", "summon_t_experts", "list_t_experts"] },
+      ...(maxDepth === undefined ? {} : { maxDepth }),
+      signal: exec.signal,
+    });
+    try {
+      const result = await run.result;
+      const text = (result.output ?? [])
+        .filter((block) => block?.type === "text")
+        .map((block) => block.text)
+        .join("");
+      if (result.stopReason !== "completed") {
+        throw new Error(t(current, "error.expertRun", {
+          reason: result.stopReason,
+          detail: text === "" ? "" : t(current, "error.partialOutput", { text }),
+        }));
+      }
+      return { expert: localized(expert, current).name, answer: text };
+    } finally {
+      await run.dispose();
+    }
+  }
+
+  /** 预检报告的中文渲染。 */
+  function renderPlanReport(value) {
+    const lines = [value.ok === true ? "预检通过：这套任务可以按顺序创建。" : `预检未通过：${value.problems.length} 个问题。`];
+    for (const problem of value.problems ?? []) {
+      const where = problem.id === undefined ? "" : `[${problem.id}] `;
+      lines.push(`- ✗ ${where}${problem.subject === "" ? "" : `${problem.subject}：`}${problem.error}`);
+    }
+    if ((value.warnings ?? []).length > 0) {
+      lines.push("提示（不阻塞）：");
+      for (const warning of value.warnings) lines.push(`- ! ${warning}`);
+    }
+    if ((value.order ?? []).length > 0) {
+      lines.push(`建议创建/执行顺序：${value.order.join(" → ")}`);
+    }
+    return lines.join("\n");
+  }
+
+  // ---- 工具 ----
+  ctx.tools.register(defineTool({
+    name: "list_t_experts",
+    description: "List the enabled T专家 domain experts grouped by division. Without a division filter it returns division names and counts; pass a division to expand it with expert names and descriptions. Call this before summon_t_expert to choose an expert name.",
+    parameters: {
+      division: {
+        type: "string",
+        description: "Optional division key to filter (e.g. engineering, marketing, security, design).",
+      },
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          divisions: { type: "array", required: true, items: { type: "json" } },
+          total: { type: "number", required: true },
+        },
+      },
+      render: (args, value) => [{
+        type: "text",
+        text: renderList(locale(), {
+          query: args.division === undefined ? "" : String(args.division).trim(),
+          groups: value.divisions,
+          total: value.total,
+          allDivisions: effectiveDivisions,
+        }),
+      }],
+    },
+    async execute(args) {
+      await ensureReady();
+      const query = args.division === undefined ? "" : String(args.division).trim();
+      const enabled = enabledSet();
+      const groups = groupByDivision(usable(), enabled);
+      if (query === "") {
+        return {
+          divisions: groups.map((group) => ({
+            division: group.division,
+            label: group.label,
+            labelEn: group.labelEn,
+            count: group.count,
+          })),
+          total: enabled.size,
+        };
+      }
+      const needle = query.toLowerCase();
+      const matched = groups
+        .filter((group) => group.division.toLowerCase() === needle
+          || group.label.toLowerCase() === needle
+          || group.labelEn.toLowerCase() === needle)
+        .map((group) => ({
+          division: group.division,
+          label: group.label,
+          labelEn: group.labelEn,
+          count: group.count,
+          experts: group.experts.map((expert) => {
+            const { name, description } = localized(expert, locale());
+            return {
+              slug: expert.slug,
+              name,
+              emoji: expert.emoji,
+              description: truncate(description, DESCRIPTION_LIMIT),
+            };
+          }),
+        }));
+      return {
+        divisions: matched,
+        total: matched.reduce((sum, group) => sum + group.count, 0),
+      };
+    },
+  }));
+
+  ctx.tools.register(defineTool({
+    name: "summon_t_expert",
+    description: "Summon one T专家 domain expert to complete a task: a specialist subagent runs with that expert's full persona and returns its result. Use it for tasks that clearly belong to a specialist domain. This call waits for the result. Call list_t_experts first when the expert name is unknown.",
+    parameters: {
+      expert: { type: "string", required: true, description: "Expert name to summon — the Chinese display name (e.g. \"前端开发者\"), the English name (e.g. \"Frontend Developer\"), or its slug (e.g. engineering-frontend-developer). Copy the name exactly as list_t_experts returned it." },
+      task: { type: "string", required: true, description: "The complete, self-contained task to give the expert. Include all necessary context." },
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          expert: { type: "string", required: true },
+          answer: { type: "string", required: true },
+        },
+      },
+      render: (_args, value) => [{ type: "text", text: value.answer }],
+    },
+    async execute(args, exec) {
+      await ensureReady();
+      return runExpert(args.expert, args.task, exec);
+    },
+  }));
+
+  ctx.tools.register(defineTool({
+    name: "summon_t_experts",
+    description: "Summon multiple T专家 experts in parallel for one mission. At most 8 experts run with concurrency 4; successful answers are returned even when some fail.",
+    parameters: {
+      experts: {
+        type: "array",
+        required: true,
+        description: "The experts to summon, each with its own name and task.",
+        items: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            expert: { type: "string", required: true, description: "Expert name — Chinese display name, English name, or slug." },
+            task: { type: "string", required: true, description: "That expert's complete task." },
+          },
+        },
+      },
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: { results: { type: "array", required: true, items: { type: "json" } } },
+      },
+      render: (_args, value) => [{
+        type: "text",
+        text: renderSummonResults(locale(), value.results),
+      }],
+    },
+    async execute(args, exec) {
+      await ensureReady();
+      const current = locale();
+      const specs = Array.isArray(args.experts) ? args.experts : [];
+      if (specs.length === 0) throw new Error(t(current, "error.specsEmpty"));
+      if (specs.length > SUMMON_EXPERTS_MAX) {
+        throw new Error(t(current, "error.specsTooMany", { limit: SUMMON_EXPERTS_MAX }));
+      }
+      specs.forEach((spec, index) => {
+        if (spec === null || typeof spec !== "object" || typeof spec.expert !== "string" || typeof spec.task !== "string") {
+          throw new Error(t(current, "error.specInvalid", { index }));
+        }
+      });
+      const results = await mapPool(specs, SUMMON_EXPERTS_CONCURRENCY, async (spec) => {
+        try {
+          const result = await runExpert(spec.expert, spec.task, exec);
+          return { expert: result.expert, ok: true, answer: result.answer };
+        } catch (error) {
+          return {
+            expert: spec.expert,
+            ok: false,
+            answer: "",
+            error: error instanceof Error ? error.message : String(error),
+          };
+        }
+      });
+      return { results };
+    },
+  }));
+
+  // ---- 内置团队引擎（vendor 自上游并品牌化；配置来自 team-profiles.py 生成的 JSON）----
+  // 配置文件名已随品牌改为 t-team.config.json，旧名 agent-teams.config.json 仍作为兜底读一次。
+  const engineConfigDir = dirname(config.root);
+  const engineConfigPath = ["t-team.config.json", "agent-teams.config.json"]
+    .map((file) => join(engineConfigDir, file))
+    .find((candidate) => existsSync(candidate)) ?? join(engineConfigDir, "t-team.config.json");
+  let engineConfig = {};
+  try {
+    const parsed = JSON.parse(readFileSync(engineConfigPath, "utf8"));
+    if (parsed !== null && typeof parsed === "object") engineConfig = parsed;
+  } catch {
+    console.warn(`[t-team] 未读到团队引擎配置 ${engineConfigPath}（跑一次 team-profiles.py 生成小队后即可用 /t 拉起团队）`);
+  }
+  // 引擎与名册解耦：引擎挂载失败（例如 Harness 子代理契约不匹配）时，
+  // T专家 的专家名册、@ 召唤、/t 列表仍然可用，只是团队功能不可用；失败原因会经 /t 报出来。
+  const engineState = { ok: false, detail: "" };
+  try {
+    ctx.plugin(teamsEngine, {
+      stateDir: typeof engineConfig.stateDir === "string" ? engineConfig.stateDir : ".agent-teams",
+      memberProvider: typeof engineConfig.memberProvider === "string" ? engineConfig.memberProvider : "spawn",
+      ...(engineConfig.memberModel === undefined ? {} : { memberModel: engineConfig.memberModel }),
+      ...(engineConfig.memberMaxDepth === undefined ? {} : { memberMaxDepth: engineConfig.memberMaxDepth }),
+      ...(engineConfig.maxMembers === undefined ? {} : { maxMembers: engineConfig.maxMembers }),
+      // 引擎自带命令必须关掉：T专家 自己注册 /t（带小队别名解析），否则两个同名命令相撞。
+      // 手势边界另外复用（见下），它是队长协议真正被触发的地方。
+      slashCommand: false,
+      profiles: engineConfig.profiles ?? {},
+    });
+    // 复用引擎导出的手势边界：把 `/t --profile <小队> <目标>` 这条用户消息翻成队长协议指令。
+    installTTeamGestureBoundary(ctx, () => engineConfig.profiles ?? {});
+    engineState.ok = true;
+  } catch (error) {
+    engineState.detail = error instanceof Error ? error.message : String(error);
+    console.error(`[t-team] 团队引擎挂载失败（专家名册功能不受影响）：${engineState.detail}`);
+  }
+
+  // ---- 小队定义服务（设置页「小队」标签用；写回 teams.json 后自动重跑 team-profiles.py）----
+  const teamsFile = join(dirname(config.root), "teams.json");
+  const squads = createSquadService({
+    teamsFile,
+    catalog: catalogService,
+  });
+  ctx.reflect.provide(SQUAD_SERVICE, squads);
+
+  // ---- 团队运行服务（设置页「团队」标签用；复用引擎的快照与停止实现）----
+  const engineStateDir = typeof engineConfig.stateDir === "string" ? engineConfig.stateDir : ".agent-teams";
+  const teamRoots = () => {
+    const registry = ctx.get("workspaceRegistry") ?? ctx.get("workspace");
+    const list = typeof registry?.list === "function" ? registry.list() : [];
+    return list
+      .map((workspace) => ({
+        workspace: workspace.title ?? workspace.path,
+        path: workspace.path,
+        stateRoot: join(workspace.path, engineStateDir),
+      }))
+      .filter((root) => typeof root.stateRoot === "string");
+  };
+  const compactTeam = (team) => ({
+    teamId: team.teamId,
+    name: team.name,
+    workspace: team.workspace,
+    captainSessionId: team.captainSessionId,
+    phase: team.phase,
+    halted: team.halted === true,
+    members: (team.members ?? []).map((member) => ({
+      name: member.name,
+      role: member.role ?? "",
+      status: member.status,
+      activity: member.activity,
+      done: member.done ?? 0,
+      total: member.total ?? 0,
+    })),
+    tasks: (team.tasks ?? []).map((task) => ({
+      id: task.id,
+      subject: task.subject,
+      status: task.status,
+      assignee: task.assignee ?? "",
+    })),
+  });
+  ctx.reflect.provide(TEAM_SERVICE, {
+    async list(archived = false) {
+      const roots = teamRoots();
+      if (roots.length === 0) return [];
+      const snapshots = archived
+        ? await collectArchivedTeamsActivity(ctx, roots)
+        : await collectTeamsActivity(ctx, roots);
+      return snapshots.map(compactTeam);
+    },
+    /** 面板里点一支小队：投一条 `/t --profile <key>` 让队长按该小队接活（目标由队长追问用户）。 */
+    async start(profileKey, sessionId) {
+      const list = await squads.list();
+      const hit = list.squads.find((squad) => squad.key === profileKey && squad.enabled !== false);
+      if (hit === undefined) throw new Error(`没有可用的「${profileKey}」小队（可能已关停或改名）。`);
+      // 注意：cordis 里 `ctx.agents` 是属性访问，未 inject 会抛 "cannot get property agents without inject"；
+      // 这里要的是「可选服务」，必须走 ctx.get()（与 workspaceRegistry 一样的用法）。
+      const agents = ctx.get("agents");
+      const agent = typeof sessionId === "string" && sessionId !== "" ? agents?.get?.(sessionId) : undefined;
+      if (agent === undefined) throw new Error("当前会话不在运行中，无法从这里拉起小队（先用 /t 试）。");
+      agent.followup(createUserMessage({
+        content: [{ type: "text", text: `/t --profile ${profileKey}` }],
+        source: { kind: "user" },
+      }));
+      return {
+        profile: profileKey,
+        label: hit.description === "" ? profileKey : hit.description,
+        members: hit.members.length,
+      };
+    },
+    async stop(teamId) {
+      const roots = teamRoots();
+      for (const root of roots) {
+        let snapshots;
+        try {
+          snapshots = await collectTeamsActivity(ctx, [root]);
+        } catch {
+          continue;
+        }
+        const team = snapshots.find((item) => item.teamId === teamId);
+        if (team === undefined) continue;
+        const captain = ctx.get("agents")?.get?.(team.captainSessionId);
+        if (captain === undefined) {
+          throw new Error("队长会话已不在运行中：这类团队只能用 /t 恢复后再操作，或直接在活动面板里归档。");
+        }
+        const result = await haltTeamWork({ ctx, stateRoot: root.stateRoot, teamId, captain });
+        return { teamName: result.teamName, cancelledTasks: result.cancelledTasks, alreadyHalted: result.alreadyHalted === true };
+      }
+      throw new Error(`没找到团队 ${teamId} 的状态目录（它可能已被归档）。`);
+    },
+  });
+
+  // ---- `/t` 小队短命令（把 /t <小队> <目标> 转成引擎认得的 /t --profile <key> <目标> 用户消息）----
+  registerTeamCommand(ctx, {
+    teamsFile,
+    hasEngine: () => {
+      if (engineState.ok !== true) return false;
+      try {
+        return ctx.tools.get("t_team_create") !== undefined;
+      } catch {
+        return false;
+      }
+    },
+    engineError: () => engineState.detail,
+  });
+
+  // ---- DAG 预检工具（只读）：把整套拟建任务一次跑完引擎校验，避免"边建边撞"留下半成品 ----
+  ctx.tools.register(defineTool({
+    name: "t_team_plan_check",
+    description: "Dry-run a batch of T Team tasks through the engine's own validators WITHOUT creating anything, and get every problem in one reply: missing contract fields (objective/acceptance/inScope/verify), inScope overlap with existing open write tasks, unknown or cyclic dependencies, unknown assignee. Also returns warnings (a member already owns an open task; duplicate subjects) and the execution order. Call this before creating more than one task, and after any failed t_team_create_task before retrying.",
+    parameters: {
+      tasks: {
+        type: "array",
+        required: true,
+        description: "Tasks you intend to create, in intended order. Each item accepts: subject (required), id (optional label so later items can reference it), kind, description, dependencies (task ids: existing ones or earlier items' labels), assignee, inScope, outOfScope, verify, acceptance, objective, deliverables, nonGoals, round, reviewedTaskId, sourceTaskId, sourceFindingIds.",
+        items: { type: "json" },
+      },
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          ok: { type: "boolean", required: true },
+          problems: { type: "array", required: true, items: { type: "json" } },
+          warnings: { type: "array", required: true, items: { type: "string" } },
+          order: { type: "array", required: true, items: { type: "string" } },
+        },
+      },
+      render: (_args, value) => [{ type: "text", text: renderPlanReport(value) }],
+    },
+    async execute(args, exec) {
+      const agent = exec?.agent;
+      if (agent === undefined) return { ok: false, problems: [{ index: -1, id: "agent", subject: "", error: "这个工具需要在会话里调用" }], warnings: [], order: [] };
+      const workspace = agent.session?.header?.cwd ?? process.cwd();
+      const stateRoot = join(workspace, engineStateDir);
+      let team;
+      try {
+        team = await findTeamByCaptain(stateRoot, agent.id);
+      } catch (error) {
+        return { ok: false, problems: [{ index: -1, id: "state", subject: "", error: `读团队状态失败：${String(error)}` }], warnings: [], order: [] };
+      }
+      if (team === undefined) {
+        return {
+          ok: false,
+          problems: [{ index: -1, id: "team", subject: "", error: "当前会话还没有团队；先用 t_team_create（approval=required）建一支 staged 团队，再来预检任务。" }],
+          warnings: [],
+          order: [],
+        };
+      }
+      const report = checkPlan(team, args.tasks);
+      return {
+        ok: report.ok,
+        problems: report.problems,
+        warnings: report.warnings,
+        order: report.order,
+      };
+    },
+  }));
+
+  // ---- 父会话系统提示 ----
+  /**
+   * T Team 的硬约束：引擎是**逐条硬校验、无事务、无预检**，模型却习惯"一次想好整套 DAG、逐条创建"，
+   * 于是很容易撞规则并留下半成品（重复任务）。这一节把规则与做法写成明文，减少试错。
+   */
+  ctx.systemPrompt.section({
+    name: "t-team:constraints",
+    order: 119,
+    text: (context) => {
+      if (context.agent?.session?.header?.parentSession !== undefined) return "";
+      return [
+        "## T Team 硬约束（建任务前必读）",
+        "The engine validates task creation one call at a time and never rolls back. Follow these rules:",
+        "1. **One writer per path.** Two open write tasks (implementation/repair) must not share any inScope path; if they need the same file, make the later one depend on the earlier one (serialize) or split the file paths. Otherwise: `inScope overlaps …`.",
+        "2. **One open task per member.** A member cannot hold two unfinished tasks; extra assignments are rejected/queued. Use the shared pool (leave assignee empty) or more members instead of stacking work on one person.",
+        "3. **Captain owns one takeover at a time**, and a dependency-blocked task cannot be taken over. Do not try to fix the plan by taking many tasks yourself.",
+        "4. **Dependencies may only reference already-created tasks.** Create in dependency order; never reference a task you have not created yet.",
+        "5. **After approval the plan is frozen** (`t_team_edit_plan` works only while staged). Before approving, get the plan right; afterwards you can only create/add, reassign, update.",
+        "",
+        "Working rules that prevent the failure spiral:",
+        "- Planning more than one task? **Call `t_team_plan_check` first** with the whole batch: it dry-runs the engine's own validators and returns every problem at once (contract fields, path overlaps, missing/cyclic dependencies, unknown assignee) plus warnings and the execution order. Fix until it reports ok, then create.",
+        "- **After any failed create, call `t_team_status` before retrying.** A failed call may still have created earlier tasks; retrying blindly duplicates work.",
+        "- Prefer one atomic batch edit while staged; keep task subjects unique.",
+      ].join("\n");
+    },
+  });
+
+  ctx.systemPrompt.section({
+    name: "t-team:experts",
+    order: 118,
+    text: (context) => {
+      if (context.agent?.session?.header?.parentSession !== undefined) return "";
+      return [
+        "## T专家 (T Expert) expert mode",
+        "The parent session has T专家 — a 279-expert, 18-division roster with full Chinese translations, exposed as summonable domain experts.",
+        "Experts are individually enabled/disabled in the T专家 settings tab; ALL are disabled by default and a disabled expert cannot be summoned.",
+        "A composer selection inserts one enabled expert as a native reference chip; the remaining draft text is that expert's task.",
+        "In the parent session, call `list_t_experts()` for enabled division names and counts, then `list_t_experts(division)` to pick a unique expert name, then `summon_t_expert(expert, task)` — or `summon_t_experts` for a small parallel team (at most 8; partial results when some fail).",
+        "For a long multi-step goal that needs a durable team (members, tasks with dependencies, review gates), the user can run a T专家 squad with the `/t <squad> <goal>` slash command (squad names and aliases come from the plugin's squad definitions; plain `/t` lists them); it activates the built-in T专家 team engine with a squad whose members already carry the experts' personas. Do not invent squad names when `/t` is available.",
+      ].join("\n");
+    },
+  });
+}