dsh-plugin-t-expert 0.2.7 → 0.2.10

package/lib/skill.js

@@ -1,11 +1,18 @@
+// @ts-check
 /**
- * 运维 skill：把「名册 / 小队 / 装机 / 发布」的运维入口做成一个**随插件发布**的 skill。
+ * 随包发布的 skill：把「T专家 运维」与「DeepSeek Harness 项目知识」做成**随 npm 包分发**的 skill。
  *
- * 为什么是 skill 而不是再加一段 systemPrompt：这套流程只在用户说"帮我把这个专家加进去 / 改个小队 /
- * 校验名册"时才需要，常驻提示段是纯浪费 token；skill 的 description 本来就是路由面。
+ * 为什么是 skill 而不是再加一段 systemPrompt：这些内容只在特定任务里需要（改名册/小队/装机/发布，
+ * 或在一个 deepseek-harness 检出里读写代码），常驻提示段是纯浪费 token；skill 的 description 本来就是路由面。
  *
- * 形态：`<包根>/skills/t-expert-manager/SKILL.md` 是标准 skill 文件（任何 skill 扫描器都能直接发现），
- * 这里额外把它注册进宿主的 skill 注册表，这样 npm 安装（插件在 node_modules 里、没有运维台）也能用。
+ * 形态：`<包根>/skills/<name>/SKILL.md` 是标准 skill 文件（任何 skill 扫描器都能直接发现），
+ * 这里额外把它们注册进宿主的 skill 注册表，这样 npm 安装（插件在 node_modules 里、没有运维台）也能用。
+ *
+ * 三个 skill 的来源：
+ *   - `t-expert-manager`：本仓运维入口，正文带占位符，注册时按本机布局渲染。
+ *   - `dsh-harness-project` / `dsh-harness-languages`：`dsh-project-expert` agent preset 里那两个
+ *     项目知识 skill 的**逐字节拷贝**（preset 是源，这里是随插件发布的副本），
+ *     所以插件用户在任何仓库里都能加载这套 harness 项目知识。
  *
  * 两条刻意的设计：
  *   1. **可选依赖**：走 `ctx.inject(["skills"], …)`，而不是把 `skills` 加进插件的静态 `inject`。
@@ -13,16 +20,25 @@
  *   2. **路径不写死在正文里**：注册时解出运维台根目录（`tz.sh` 所在目录）再替换 `{{TZ}}` / `{{OPS_ROOT}}`，
  *      所以同一份 skill 在开发机和别的安装布局下都不会说谎；解不出来就明说"没找到"。
  *
- * @module t-expert-manager skill
+ * @module bundled skills
  */
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-/** skill 名（kebab-case；宿主按它路由与去重）。 */
-export const OPS_SKILL_NAME = "t-expert-manager";
-/** 包内 skill 目录（`<包根>/skills/t-expert-manager`），同时作为 skill 的资源基准目录。 */
-export const OPS_SKILL_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "skills", OPS_SKILL_NAME);
+/** 包内 skills 根目录：`<包根>/skills`。 */
+export const SKILLS_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "skills");
+
+/**
+ * 随包发布的 skill 清单（目录名 = 宿主路由用的 skill 名）。
+ *
+ * 顺序即注册顺序。缺文件的条目会被跳过并逐条告警，而不是让整段注册失败 ——
+ * 一个 skill 文件缺失不该带走另外两个。
+ */
+export const BUNDLED_SKILL_NAMES = ["t-expert-manager", "dsh-harness-project", "dsh-harness-languages"];
+
+/** 只有运维 skill 的正文带 `{{TZ}}` / `{{OPS_ROOT}}` 占位符，其余按原样注册。 */
+const PLACEHOLDER_SKILL = "t-expert-manager";
 
 /** 运维台根目录不存在时的正文占位说明（宁可说不知道，也不要指向一个不存在的脚本）。 */
 const NO_OPS_ROOT = "（未在本机找到 tz.sh：请用 T_TEAM_REPO 指定插件仓库，或从源码目录运行运维台。）";
@@ -38,7 +54,7 @@ function readText(path) {
 /**
  * 取 SKILL.md frontmatter 里的一个单行标量字段。
  *
- * 只认单行，所以本 skill 的 `description` 必须写在一行里 —— 刻意不引 YAML 依赖，
+ * 只认单行，所以随包 skill 的 `description` 必须写在一行里 —— 刻意不引 YAML 依赖，
  * frontmatter 里就只有 name/description 两个键。
  * @param text - 完整 SKILL.md 文本。
  * @param key - 字段名。
@@ -59,8 +75,10 @@ export function frontmatterField(text, key) {
  *
  * 候选按序：`T_TEAM_REPO` 的父目录 → 数据目录的父目录 → 包目录的父目录。
  * 每个候选都要**真的存在 tz.sh** 才算数，否则返回空串（不猜）。
- * @param options - `dataDir` = 数据目录（默认 `~/.t-team`，本机是指向 `<ops>/data` 的软链）；
- *   `packageDir` = 本包根目录；`env` = 环境变量（测试可注入）。
+ * @param {object} [options] 调用选项
+ * @param {string} [options.dataDir] 数据目录（默认 `~/.t-team`，本机是指向 `<ops>/data` 的软链）
+ * @param {string} [options.packageDir] 本包根目录
+ * @param {Record<string, string | undefined>} [options.env] 环境变量（测试可注入）
  * @returns 运维台根目录，或空串。
  */
 export function resolveOpsRoot({ dataDir, packageDir, env = process.env } = {}) {
@@ -102,48 +120,93 @@ export function renderOpsSkill({ template, opsRoot }) {
 }
 
 /**
- * 组织出要交给宿主的 skill 定义（便于自检直接断言，不依赖宿主）。
- * @param config - 插件配置（用 `root` 推数据目录）。
- * @returns `{ name, description, content, resourceBase }`；包内缺 SKILL.md 时返回 `undefined`。
+ * 组织出一个随包 skill，并带上失败原因（供调用方逐条告警）。
+ *
+ * 与 {@link buildBundledSkill} 的区别只在「失败时说什么」：这里保留原因，那里只看有没有。
+ * @param name - skill 名（= `<包根>/skills/<name>/SKILL.md` 的目录名）。
+ * @param config - 插件配置；只有运维 skill 用到（由 `root` 推数据目录）。
+ * @returns `{ skill }` 或 `{ reason }`；`reason` 是给人/日志看的一句话。
  */
-export function buildOpsSkill(config = {}) {
-  const text = readText(join(OPS_SKILL_DIR, "SKILL.md"));
-  if (text === "") return undefined;
-  const name = frontmatterField(text, "name") || OPS_SKILL_NAME;
+function loadBundledSkill(name, config = {}) {
+  const directory = join(SKILLS_ROOT, name);
+  const path = join(directory, "SKILL.md");
+  const text = readText(path);
+  if (text === "") return { reason: `读不到 ${path}` };
+  const skillName = frontmatterField(text, "name") || name;
   const description = frontmatterField(text, "description");
-  if (description === "") return undefined;
-  const body = text.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/u, "").trim();
-  const dataDir = typeof config.root === "string" && config.root !== "" ? dirname(config.root) : undefined;
-  const opsRoot = resolveOpsRoot({ dataDir, packageDir: resolve(OPS_SKILL_DIR, "..", "..") });
+  if (description === "") {
+    return { reason: `${path} 的 frontmatter 缺 description（没有它就没法作为 skill 的路由面）` };
+  }
+  let body = text.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/u, "").trim();
+  if (name === PLACEHOLDER_SKILL) {
+    const dataDir = typeof config.root === "string" && config.root !== "" ? dirname(config.root) : undefined;
+    // `resolveOpsRoot` 取的是传入目录的父目录，所以这里传**包根**（skills/ 的上一层）。
+    body = renderOpsSkill({ template: body, opsRoot: resolveOpsRoot({ dataDir, packageDir: resolve(SKILLS_ROOT, "..") }) });
+  }
   return {
-    name,
-    description,
-    content: renderOpsSkill({ template: body, opsRoot }),
-    // `source` 必须自己给：宿主只给 invocation / provider 兜默认值，**不兜 source**，
-    // 而加载路径（skills.get）会校验 source 必须是字符串 —— 少了它，skill 在目录里
-    // 显示正常、一加载就抛 `source must be a string`。
-    source: "runtime",
-    // 让模型能从资源基准目录读到 references/ops-reference.md
-    resourceBase: { kind: "directory", path: OPS_SKILL_DIR },
+    skill: {
+      name: skillName,
+      description,
+      content: body,
+      // `source` 必须自己给：宿主只给 invocation / provider 兜默认值，**不兜 source**，
+      // 而加载路径（skills.get）会校验 source 必须是字符串 —— 少了它，skill 在目录里
+      // 显示正常、一加载就抛 `source must be a string`。
+      source: "runtime",
+      // 让模型能从资源基准目录读到同目录下的附属文件（如运维 skill 的 references/）。
+      resourceBase: { kind: "directory", path: directory },
+    },
   };
 }
 
 /**
- * 把运维 skill 注册进宿主。`skills` 服务缺席时什么都不做（可选依赖，见文件头注释）。
+ * 逐个构建随包 skill，并**记下**哪些条目没建成以及为什么。
+ *
+ * 注册方靠 `missing` 逐条告警 —— 缺一个文件不该静默、也不该带走另外两个。
+ * @param config - 插件配置。
+ * @returns `{ skills, missing }`；顺序与 {@link BUNDLED_SKILL_NAMES} 一致。
+ */
+function collectBundledSkills(config = {}) {
+  const skills = [];
+  const missing = [];
+  for (const name of BUNDLED_SKILL_NAMES) {
+    const loaded = loadBundledSkill(name, config);
+    if (loaded.skill === undefined) missing.push({ name, reason: loaded.reason });
+    else skills.push(loaded.skill);
+  }
+  return { skills, missing };
+}
+
+/**
+ * 组织出全部随包 skill（失败条目不进数组，见 {@link collectBundledSkills} 拿原因）。
+ * @param config - 插件配置。
+ * @returns 定义数组；缺文件的条目被跳过（顺序与 {@link BUNDLED_SKILL_NAMES} 一致）。
+ */
+export function buildBundledSkills(config = {}) {
+  return collectBundledSkills(config).skills;
+}
+
+/**
+ * 把随包 skill 注册进宿主。`skills` 服务缺席时什么都不做（可选依赖，见文件头注释）。
+ *
+ * 缺失条目**逐条 warn**（一个 skill 文件缺失不该带走另外两个，但也不能悄悄消失）；
+ * 全军覆没时额外再给一条汇总 warn，保持既有的「都读不到」信号。
  * @param ctx - 插件上下文。
  * @param config - 插件配置。
- * @returns `true` 表示已排入注册；`false` 表示宿主没有 skill 注册表或包内缺 skill 文件。
+ * @returns 排入注册的 skill 数；`0` 表示宿主没有 skill 注册表，或包内一个 skill 文件都读不到。
  */
-export function installOpsSkill(ctx, config) {
-  if (typeof ctx?.inject !== "function") return false;
-  const skill = buildOpsSkill(config);
-  if (skill === undefined) {
-    ctx.logger?.warn?.(`[t-team] 运维 skill 未注册：读不到 ${join(OPS_SKILL_DIR, "SKILL.md")}`);
-    return false;
+export function installBundledSkills(ctx, config) {
+  if (typeof ctx?.inject !== "function") return 0;
+  const { skills, missing } = collectBundledSkills(config);
+  for (const item of missing) {
+    ctx.logger?.warn?.(`[t-team] 随包 skill「${item.name}」未注册：${item.reason}（其余 skill 照常注册）`);
+  }
+  if (skills.length === 0) {
+    ctx.logger?.warn?.(`[t-team] 随包 skill 未注册：读不到 ${join(SKILLS_ROOT, "<name>", "SKILL.md")}`);
+    return 0;
   }
   ctx.inject(["skills"], (scoped) => {
-    scoped.effect(() => scoped.skills.register(skill));
-    ctx.logger?.info?.(`[t-team] 已注册运维 skill：${skill.name}`);
+    for (const skill of skills) scoped.effect(() => scoped.skills.register(skill));
+    ctx.logger?.info?.(`[t-team] 已注册随包 skill：${skills.map((skill) => skill.name).join("、")}`);
   });
-  return true;
+  return skills.length;
 }

package/lib/squads.js

@@ -1,3 +1,4 @@
+// @ts-check
 /**
  * T专家 小队数据层：读写 `teams.json`，并把改动编译成引擎配置。
  *
@@ -5,10 +6,16 @@
  * 编译交给既有的 `team-profiles.py`（它已内置成员名撞键预检、别名校验、人格注入）。
  * 这样 UI 编辑器不需要复制一份校验逻辑，生成器仍是唯一权威。
  */
-import { readFileSync, writeFileSync, statSync, existsSync } from "node:fs";
-import { execFileSync } from "node:child_process";
+import { readFileSync, statSync, existsSync } from "node:fs";
+import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+
+import { writeFileAtomic } from "./catalog.js";
+
+/** 异步编译器调用：**绝不能**用 execFileSync —— 那会同步阻塞整个 Host 事件循环。 */
+const runFile = promisify(execFile);
 
 /** profile key 只允许小写 ASCII + 数字 + 连字符（引擎按它生成命令别名）。 */
 const KEY_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
@@ -18,6 +25,7 @@ function text(value) {
 }
 
 function fail(code, message, details = {}) {
+  /** @type {Error & { code?: string, details?: object }} */
   const error = new Error(message);
   error.code = code;
   error.details = details;
@@ -36,16 +44,66 @@ function memberSlug(member) {
 }
 
 /**
- * @param generator - 小队编译器路径。调用方**优先传包内那份**（`<包>/data/team-profiles.py`）：
- *   它是随插件版本走的**代码**，而数据目录里那份只在首次启动时播种一次（非破坏性），
- *   升级时不会更新 —— 一直用数据目录那份，等于这个版本的编译器修复永远送不到老用户手里。
+ * 编译器的成员上限默认值（与 `data/team-profiles.py` 的 `MAX_MEMBERS` 同一口径）。
+ *
+ * 它只是**兼容旧编译器的回退默认**，不是第二个真源：调用方通过 `maxMembers` 把
+ * `Config.maxMembers` 传进来，编译器支持 `--max-members` 时以传入值为准（见 `build()`）。
+ */
+export const COMPILER_DEFAULT_MAX_MEMBERS = 8;
+
+/**
+ * @param generator - 小队编译器路径。调用方**只有传包内那份**才是安全且正确的接线：
+ *   `lib/index.js` 现在**只**传 `<包>/data/team-profiles.py`，**不回退**数据目录副本。
+ *   为什么：数据目录那份是 bootstrap 播种的**用户可写**文件，让「保存小队」去执行它
+ *   等于一条同权限代码执行面，且它与包内版本的漂移无法校验（C-3）。
+ *   本函数保留「未传就取同目录 `team-profiles.py`」的默认，只是为了直连数据层的调用方
+ *   （自检 / 面板预览脚本）不必显式传路径 —— **插件运行路径绝不走这个默认**。
+ * @param maxMembers - 成员上限（来自 `Config.maxMembers`）。只有编译器声明支持 `--max-members`
+ *   时才会真正生效；旧编译器把上限写死在源码里，此时会**记一条 warn** 并退回它的默认值，
+ *   而不是让保存小队在「改大上限」后必然编译失败并回滚（D-14）。
+ * @param onReload - 小队保存**编译成功之后**的热重载回调（由 `lib/index.js` 注入：它持有团队引擎的
+ *   fiber，用新的 profiles 重挂引擎）。数据层不碰 `ctx`：这里只负责在正确时机敲门。
+ *   回调返回 `{ ok: true }` 表示重载成功；`{ ok: false, detail }` 表示重载失败（原因要能报给用户）。
+ *   **没有注入时不算成功**：那与"重载失败"是同一个后果（盘上是新配置、引擎还在用旧的），
+ *   所以会记成 `lastReload.ok === false` 并带出明确原因，而不是静默当成功（见 `scheduleReload()`）。
+ *   编译失败并回滚时本回调**绝不**被调用：那时盘上还是旧配置，重载只会重新加载同一份旧配置
+ *   （见 `save()`）。
+ * @param logger - 宿主 logger（`ctx.logger`，可选）。小队编译/重载的诊断**必须走这里**，
+ *   不能写 `console`：桌面与 Web 里 stderr 用户看不见，等于这条失败从来没被上报过
+ *   （与 `catalog.js` 的 N-3 同一条口径）。
+ *   **没有注入时也不写 console**：那正是「用户看不见」的老毛病，宁可静默也不能假装报了。
  */
-export function createSquadService({ teamsFile, catalog, python = "python3", generator: generatorPath }) {
+export function createSquadService({ teamsFile, catalog, python = "python3", generator: generatorPath, maxMembers, onReload, logger }) {
   const dataDir = dirname(teamsFile);
   const generator = typeof generatorPath === "string" && generatorPath !== ""
     ? generatorPath
     : join(dataDir, "team-profiles.py");
+  const memberLimit = typeof maxMembers === "number" && Number.isSafeInteger(maxMembers) && maxMembers > 0
+    ? maxMembers
+    : COMPILER_DEFAULT_MAX_MEMBERS;
+  // 编译器能力探测**只做一次**（读它自己的源码找 flag）：比「先试传、失败再重跑」便宜，
+  // 也不会在 argparse 报错时留下半跑过的生成物。
+  const generatorSupportsMemberLimit = existsSync(generator)
+    ? readFileSync(generator, "utf8").includes("--max-members")
+    : false;
+  /** 诊断一律走宿主 logger（见 `logger` 参数的说明）：console 在 GUI 里无人可见。 */
+  const logError = (message) => logger?.error?.(`[t-team] ${message}`);
   let lastBuild = { at: 0, ok: true, output: "" };
+  /** 正在跑的编译（见 `build()`）：并发调用合并成同一次，避免共享的 `lastBuild` 被交错覆盖。 */
+  let buildInFlight;
+  /**
+   * 热重载的**串行尾**：连续快速保存时，后一次重载必须等前一次结束再开始。
+   *
+   * 不只是节流：引擎重挂期间它自己的 fiber 处于 unload→load 过渡，并发重挂会让两次
+   * dispose/apply 交叠，最后一次重挂会在「已卸载」的中间态上跑，留下半死的引擎。
+   * 用一条 promise 链把重载串起来，天然满足「重载中不得并发重载」。
+   */
+  let reloadTail;
+  /**
+   * 最近一次**已完成**的重载结果（诊断用：设置页面板与系统提示段都读它）。
+   * 初值是 ok:true —— 「还没重载过」不等于失败。
+   */
+  let lastReload = { at: 0, ok: true, detail: "" };
 
   function readSpec() {
     try {
@@ -133,9 +191,14 @@ export function createSquadService({ teamsFile, catalog, python = "python3", gen
       engine: spec.engine ?? {},
       defaults: spec.defaults ?? {},
       lastBuild,
+      lastReload,
+      reloading: reloadTail !== undefined,
     };
   }
 
+  /** 编译器**实际**会执行的上限：旧编译器不认 --max-members，用它写死的默认值。 */
+  const effectiveMemberLimit = () => (generatorSupportsMemberLimit ? memberLimit : COMPILER_DEFAULT_MAX_MEMBERS);
+
   /** 校验（生成器之外的第一道闸门，错误信息面向面板）。 */
   function validate(squads) {
     if (!Array.isArray(squads) || squads.length === 0) {
@@ -153,6 +216,16 @@ export function createSquadService({ teamsFile, catalog, python = "python3", gen
       seenKeys.add(key);
       const members = Array.isArray(squad?.members) ? squad.members.map(memberSlug).filter((slug) => slug !== "") : [];
       if (members.length === 0) throw fail("tTeam/squads-invalid", `「${key}」没有成员：至少要选一位专家。`);
+      // 上限只有一个真源，但旧编译器**执行不了** Config 的值：直接挡在保存前，并把原因说清，
+      // 而不是把 10 人小队写下去、让编译器报「超过上限 8」再回滚（D-14 的可见形态）。
+      const limit = effectiveMemberLimit();
+      if (members.length > limit) {
+        throw fail("tTeam/squads-invalid",
+          `「${key}」有 ${members.length} 位成员，超过当前生效上限 ${limit}。`
+          + (generatorSupportsMemberLimit
+            ? "（上限来自 Config.maxMembers）"
+            : `该编译器版本不支持 --max-members，只能按它内置的 ${COMPILER_DEFAULT_MAX_MEMBERS} 执行；请更新 data/team-profiles.py 后再调大 Config.maxMembers。`));
+      }
       for (const alias of Array.isArray(squad?.aliases) ? squad.aliases : []) {
         const value = text(alias).trim();
         if (value === "") continue;
@@ -191,25 +264,101 @@ export function createSquadService({ teamsFile, catalog, python = "python3", gen
     return { ...spec, profiles };
   }
 
-  /** 跑生成器：编译 t-team.config.json + teams.resolved.json（失败即回滚 teams.json）。 */
+  /**
+   * 跑生成器：编译 t-team.config.json + teams.resolved.json（失败即回滚 teams.json）。
+   *
+   * **异步、且不得并发**（P-1）：这里过去用 `execFileSync`，保存一次小队就把整个 Host 事件
+   * 循环同步阻塞（最长 60s）—— 同一进程里所有会话的 SSE、工具调用与 Web 请求全部停摆。
+   * 改成 `await execFile(...)` 之后事件循环继续转，但会引入原来不存在的交错点：两次 `build()`
+   * 可能并行运行，共享的 `lastBuild` 会被先完成的那次覆盖。所以用一条 in-flight promise 把
+   * 并发调用**合并成同一次**（语义上也更正确：同时刻的 teams.json 只该被编译一次）。
+   *
+   * @returns {Promise<{at:number, ok:boolean, output:string}>}
+   */
   function build() {
-    if (!existsSync(generator)) {
-      lastBuild = { at: Date.now(), ok: false, output: `找不到生成器 ${generator}` };
+    if (buildInFlight !== undefined) return buildInFlight;
+    const run = (async () => {
+      if (!existsSync(generator)) {
+        lastBuild = { at: Date.now(), ok: false, output: `找不到生成器 ${generator}` };
+        return lastBuild;
+      }
+      try {
+        // 上限随 Config 走；旧编译器（无 --max-members）退回它写死的默认值并明确告警。
+        if (memberLimit !== COMPILER_DEFAULT_MAX_MEMBERS && !generatorSupportsMemberLimit) {
+          lastBuild = {
+            at: Date.now(),
+            ok: true,
+            output: `[warn] 小队编译器不支持 --max-members（${generator}），成员上限仍按它内置的 ${COMPILER_DEFAULT_MAX_MEMBERS} 执行：`
+              + `超过 ${COMPILER_DEFAULT_MAX_MEMBERS} 人的小队会编译失败，Config.maxMembers=${memberLimit} 不会生效。`
+              + `要真正用上它，请把 data/team-profiles.py 更新到带 --max-members 的版本。`,
+          };
+        }
+        const memberArgs = generatorSupportsMemberLimit ? ["--max-members", String(memberLimit)] : [];
+        // 参数与 execFileSync 时代逐项一致（数组传参、无 shell、60s 上限），只换执行方式。
+        const { stdout, stderr } = await runFile(python, [generator, "--teams", teamsFile, ...memberArgs], {
+          cwd: dataDir,
+          encoding: "utf8",
+          timeout: 60_000,
+          maxBuffer: 4 * 1024 * 1024,
+        });
+        const parts = [stdout, stderr].map((part) => text(part).trim()).filter((part) => part !== "");
+        lastBuild = { at: Date.now(), ok: true, output: parts.join("\n").split("\n").slice(-6).join("\n") };
+      } catch (error) {
+        const output = [error?.stdout, error?.stderr].map((part) => text(part).trim()).filter((part) => part !== "").join("\n");
+        lastBuild = { at: Date.now(), ok: false, output: output === "" ? String(error) : output };
+      }
       return lastBuild;
-    }
-    try {
-      const output = execFileSync(python, [generator, "--teams", teamsFile], {
-        cwd: dataDir,
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "pipe"],
-        timeout: 60_000,
-      });
-      lastBuild = { at: Date.now(), ok: true, output: output.trim().split("\n").slice(-6).join("\n") };
-    } catch (error) {
-      const output = [error?.stdout, error?.stderr].map((part) => text(part).trim()).filter((part) => part !== "").join("\n");
-      lastBuild = { at: Date.now(), ok: false, output: output === "" ? String(error) : output };
-    }
-    return lastBuild;
+    })().finally(() => {
+      if (buildInFlight === run) buildInFlight = undefined;
+    });
+    buildInFlight = run;
+    return run;
+  }
+
+  /**
+   * 引擎热重载：保存成功后，让运行中的引擎用**新的** profiles 重挂，无需重启 DSH。
+   *
+   * 为什么必须在这里做：`/t` 列表每次从磁盘读（`lib/command.js` 的 `readTeams`），而引擎的
+   * profiles 是挂载期快照 —— 两者过去只在「重启」这一个点上重新对齐。保存是唯一让磁盘
+   * 配置变化的地方，所以在**编译成功之后**敲门重载是恢复一致性的正确时机。
+   *
+   * 三条不可动摇的语义：
+   *   1. 编译失败并回滚 → **不调用**（见 `save()`：回滚分支在调用点之前就抛了）；
+   *   2. 重载失败**不改抛**——盘上已经是新配置，抛错会让用户以为「保存没生效」而不停重试；
+   *      失败原因通过返回值进 `lastReload`、日志与系统提示段，用户/模型都看得到；
+   *   3. 重载串行化：并发保存不会产生并发重挂。
+   */
+  function scheduleReload() {
+    const run = (reloadTail ?? Promise.resolve()).then(async () => {
+      if (typeof onReload !== "function") {
+        // **绝不能静默当成功**：没有注入重载方意味着「保存生效了、引擎还用着旧 profiles」，
+        // 与"重载失败"是同一个可观察后果。记成失败（lastReload.ok=false + 原因），
+        // 系统提示段与 lastReload 都会带出去，用户/模型复述得到的是真实状态。
+        // 唯一的合法场景是单测直接构造数据层（此时没人会读 lastReload）。
+        lastReload = {
+          at: Date.now(),
+          ok: false,
+          detail: "没有注入热重载回调（onReload）：这次保存已写入磁盘，但引擎仍在使用上一次的小队配置，需要重载插件或重启 DSH 才能用新小队建队。",
+        };
+        logError(lastReload.detail);
+        return;
+      }
+      const outcome = await onReload();
+      const ok = outcome?.ok !== false;
+      lastReload = { at: Date.now(), ok, detail: text(outcome?.detail) };
+      if (!ok) {
+        // 失败必须响：重载失败意味着"保存生效了、但运行中的引擎还用着旧 profiles"。
+        logError(`小队已保存，但团队引擎热重载失败：${lastReload.detail}`);
+      }
+    }).catch((error) => {
+      // 注入方自己抛错（契约违背）也要留住，不能让保存报告成"一切正常"。
+      lastReload = { at: Date.now(), ok: false, detail: String(error) };
+      logError(`小队已保存，但团队引擎热重载异常：${lastReload.detail}`);
+    }).finally(() => {
+      if (reloadTail === run) reloadTail = undefined;
+    });
+    reloadTail = run;
+    return run;
   }
 
   async function save(squads, expectedRevision) {
@@ -223,16 +372,34 @@ export function createSquadService({ teamsFile, catalog, python = "python3", gen
     }
     const previousText = readFileSync(teamsFile, "utf8");
     const nextSpec = serialize(readSpec(), squads);
-    writeFileSync(teamsFile, `${JSON.stringify(nextSpec, null, 2)}\n`);
-    const built = build();
+    // 原子写（P-2）：先写临时文件再 rename。进程若在写入中途被杀，原来会留下**截断的**
+    // teams.json，`readSpec()` 随即抛 `tTeam/squads-unreadable`，设置页「小队」标签整体不可用。
+    await writeFileAtomic(teamsFile, `${JSON.stringify(nextSpec, null, 2)}\n`);
+    const built = await build();
     if (!built.ok) {
-      writeFileSync(teamsFile, previousText); // 回滚，别把坏定义留在盘上
+      await writeFileAtomic(teamsFile, previousText); // 回滚，别把坏定义留在盘上（同样原子）
+      // 回滚之后**不重载**：盘上是旧配置，重载只会重新加载同一份旧配置，白跑一次还可能
+      // 让「保存失败」看起来像「保存成功」。下一次成功保存会重新对齐。
       throw fail("tTeam/squads-build-failed", `配置生成失败，已回滚 teams.json：\n${built.output}`, {
         actualRevision: revisionOf(),
       });
     }
-    return await list();
+    // 编译成功 = 新配置已经落在盘上（`build()` 写的正是引擎启动时读的那份），现在敲门重载。
+    const settled = scheduleReload();
+    const result = await list();
+    // 有重载还在跑时（可能是本次的，也可能是上一次的尾巴）就等它结束：这样本次保存返回的
+    // `lastReload` 才名副其实，调用方（自检探针 / 未来的面板）能直接读到「这次保存到底重载
+    // 成功没有」。等待期间系统提示段已经把真相写出来了，不会误导。
+    await settled;
+    return { ...result, lastReload, reloading: reloadTail !== undefined };
   }
 
-  return { list, save, validate, revision: revisionOf, generator, dataDir };
+  return {
+    list, save, validate, revision: revisionOf, generator, dataDir,
+    // 本服务没有 `dispose()`：它只在 `save()` 调用期间持有状态（重载串行尾由 save() 自己 await
+    // 干净），两次调用之间是无状态的，所以宿主卸载时没有需要收尾的异步工作。
+    // 让调用方（与自检）看得到「这次编译用的是哪个上限、编译器到底认不认这个参数」。
+    memberLimit,
+    generatorSupportsMemberLimit,
+  };
 }

package/lib/teams/assignee-contract.js

@@ -0,0 +1,47 @@
+/**
+ * 「谁能当 assignee」的契约 —— 一处定义，三处复用。
+ *
+ * `captain` 是引擎的**预留键**，不是成员：`add_member` 明确禁止把成员命名成
+ * captain（`tools.js`），成员表里也永远查不到它。
+ *
+ * 但同名参数 `assignee` 在三个入口里的合法取值**并不相同**：
+ *
+ * | 入口 | `assignee="captain"` |
+ * |---|---|
+ * | `t_team_create_task` | ✗ 拒绝（本模块的报错） |
+ * | `t_team_reassign_task` | ✓ 队长接管，由它自己开旁路并执行接管约束 |
+ * | `t_team_plan_check` | ✗ 拒绝（与 create_task 一致） |
+ *
+ * 为什么不干脆让 create_task 也接受：队长接管受两条**只能在接管阶段**判断的约束
+ * （依赖未完成的阻塞任务不能被接管；同一时刻只能持有 1 个未完成接管任务），
+ * 而建图时任务还是 pending、两条都无据可查。放开等于绕开安全闸。
+ *
+ * 因此正确做法是：**建任务不给 assignee（进共享池），等依赖完成后用
+ * `reassign_task(task_id, assignee="captain")` 接管**。
+ *
+ * 曾经的缺陷：create_task 直接把它丢给按成员名精确匹配的 `requireMember()`，
+ * 于是只回一句 `no active member named "captain"`，不提示正确入口 ——
+ * 模型自然会重试同一条路。本模块存在的意义就是把这个岔路口说清楚。
+ * @module t-team/assignee-contract
+ */
+import { CAPTAIN_KEY } from "./state.js";
+
+/** create_task / plan_check 对 reserve 键的标准报错文案（含可执行的下一步）。 */
+export const CAPTAIN_ASSIGNEE_HINT = 'captain 是引擎预留键、不是成员，create_task 不能把任务派给队长；'
+    + '请不带 assignee 建任务（进共享池），等依赖完成后再用 t_team_reassign_task(task_id, assignee="captain") 接管'
+    + '（依赖未完成的任务不能被接管，且队长同一时刻只能持有 1 个未完成接管任务）';
+
+/**
+ * 在 create_task / plan_check 的 assignee 校验位拦下预留键。
+ * 大小写与空白无关（`Captain`、` CAPTAIN ` 同样拦下），与 `sanitizeKey` 的语义对齐。
+ * @param {unknown} assignee 调用方给的 assignee 原值
+ * @returns {string | undefined} 通过时返回清洗后的成员名，未给 assignee 时返回 undefined
+ * @throws {Error} 取值等价于 captain 时抛出，文案即 `CAPTAIN_ASSIGNEE_HINT`
+ */
+export function normalizeAssigneeForCreate(assignee) {
+    if (typeof assignee !== 'string') return undefined;
+    const trimmed = assignee.trim();
+    if (trimmed === '') return undefined;
+    if (trimmed.toLowerCase() === CAPTAIN_KEY) throw new Error(CAPTAIN_ASSIGNEE_HINT);
+    return trimmed;
+}

package/lib/teams/harness-compat.js

@@ -16,6 +16,32 @@ function boundary(runtime) {
 function unsupported(detail) {
     throw new Error(`t-team: unsupported Harness subagent contract (${detail}); use an explicitly tested Harness version and a coherent dependency installation`);
 }
+/**
+ * 这个兼容层**实测过**的 Harness 版本（A-1/E-1）。
+ *
+ * 为什么要写出来：`guardSubagentDelivery` 会覆写共享的 `ctx.subagents` 服务，用的两个
+ * `Symbol.for` 与调用签名都来自**未文档化的上游内部实现**。上游一旦改动，症状是"团队功能
+ * 突然不可用（引擎降级）"，没有这张表就只能靠猜。升级 Harness 后**必须**把这里改成
+ * "已实测通过"再发布，未知版本会走 `unsupported()` 明确报错（而不是半死）。
+ */
+export const TESTED_HARNESS_VERSIONS = ['0.1.5-rc.1', '0.1.5-rc.2'];
+/** 单个属性能否被安全覆写：可写数据属性、有 setter 的访问器，或对象可扩展时的新属性。 */
+function canAssign(object, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(object, key);
+    if (descriptor === undefined)
+        return Object.isExtensible(object);
+    if ('value' in descriptor)
+        return descriptor.writable === true;
+    return typeof descriptor.set === 'function';
+}
+/** 覆写前先确认**每一个**目标属性都可写，否则响亮失败（避免 strict mode 下抛裸 TypeError）。 */
+function assertAssignable(object, keys) {
+    const blocked = keys.filter((key) => !canAssign(object, key));
+    if (blocked.length > 0) {
+        const names = blocked.map((key) => (typeof key === 'symbol' ? key.toString() : key)).join(', ');
+        return unsupported(`subagent service properties are not writable (${names}); upstream may have frozen or accessor-ized the service`);
+    }
+}
 /** Read child-owned history, excluding any descriptor inherited from a parent. */
 export function sessionOwnEvents(session) {
     const current = session;
@@ -116,6 +142,16 @@ export function guardSubagentDelivery(ctx, isRetired) {
     if (typeof legacy !== 'function' && ((typeof queue !== 'function' && typeof deliver !== 'function') || typeof send !== 'function')) {
         return unsupported('cannot install complete retired-member guard');
     }
+    // A-1/E-1：**先探测可写性再动手**。过去直接赋值，若上游把服务冻结（`Object.freeze`）
+    // 或改成只有 getter 的访问器，strict mode 下这里会抛一个与"版本不支持"毫无关系的裸
+    // TypeError；现在会得到明确原因。同时这也是一次"契约变了"的早期信号。
+    const targets = [
+        ...(typeof legacy === 'function' ? ['followup'] : []),
+        ...(typeof queue === 'function' ? [hostPromptQueue] : []),
+        ...(typeof deliver === 'function' ? [hostPromptDeliver] : []),
+        ...(typeof send === 'function' ? ['sendMessage'] : []),
+    ];
+    assertAssignable(host, targets);
     ctx.effect(() => {
         const descriptors = new Map([
             ['followup', Object.getOwnPropertyDescriptor(host, 'followup')],

package/lib/teams/index.js

@@ -111,6 +111,12 @@ export function apply(ctx, config) {
         maxMembers: config.maxMembers ?? 8,
         profiles: config.profiles ?? {},
     };
+    // Hot reload: a squad saved in the settings tab re-applies this plugin with a new
+    // `profiles` object (the host updates the fiber's config instead of restarting the
+    // harness). Every read below must therefore go through `resolved.profiles` — the
+    // per-apply snapshot — and never through a module-level constant captured once at
+    // startup: that was the "edit a squad, restart DSH" behaviour this exists to remove.
+    const profiles = () => resolved.profiles;
     // Provider registration is a sibling plugin's effect (`subagent-spawn` /
     // `subagent-fork` rows), which can land after this mount under the Loader's
     // concurrent activation — so capability validation happens at the first
@@ -123,7 +129,9 @@ export function apply(ctx, config) {
         order: config.promptSectionOrder,
         // Keep the bounded profile directory available without extra tool calls.
         // installTeamCapabilities snapshots this once; no business state rewrites it.
-        captainPrompt: () => usageSectionText(TEAM_TOOL_NAMES.join(', '), formatProfilesForPrompt(config.profiles)),
+        // resolved.profiles is this apply's snapshot, so a hot reload rebuilds the
+        // captain prompt with the new squad directory instead of a stale closure.
+        captainPrompt: () => usageSectionText(TEAM_TOOL_NAMES.join(', '), formatProfilesForPrompt(profiles())),
     });
     // Deterministic activation surfaces: the closed-namespace `/t-team`
     // host command (surfaces in the Web GUI slash menu via the Harness
@@ -137,9 +145,9 @@ export function apply(ctx, config) {
     // never pends on it and simply never gains the slash command.
     if (config.slashCommand ?? true) {
         ctx.inject(['commands'], (commandCtx) => {
-            registerTTeamCommand(commandCtx, () => config.profiles ?? {});
+            registerTTeamCommand(commandCtx, profiles);
         });
-        installTTeamGestureBoundary(ctx, () => config.profiles ?? {});
+        installTTeamGestureBoundary(ctx, profiles);
     }
     // The activity panel data/artwork routes need the Web server and the
     // workspace registry, which headless profiles do not mount; under