dsh-plugin-t-expert 0.2.7 → 0.2.9

package/lib/remote.js

@@ -6,7 +6,18 @@
  */
 import { Remote, RemoteError, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import { z } from "zod";
-import { CATALOG_SERVICE, SETTINGS_NAMESPACE, SQUAD_SERVICE, TEAM_SERVICE } from "./index.js";
+import { CATALOG_SERVICE, SETTINGS_NAMESPACE, SQUAD_SERVICE, TEAM_SERVICE, UNKNOWN_SLUG_ERROR_CODE } from "./index.js";
+
+/**
+ * 领域码形态：`<domain>/<reason>`（如 `tTeam/squads-invalid`）。
+ *
+ * 只有通过它校验的 `error.code` 才允许当 wire code 透传 —— 系统 errno（`EACCES`…）不是领域码，
+ * 透传出去会让客户端按 code 分支时把「文件权限」误认成业务失败类型（D-17）。口径与宿主网关一致
+ * （`<domain>/<reason>`，见 docs/cookbook/adding-a-remote-api.md）。
+ */
+const DOMAIN_CODE_PATTERN = /^[a-zA-Z][a-zA-Z0-9]*\/[a-z0-9-]+$/u;
+/** 与 `lib/index.js` 共用的「未知专家 slug」稳定码（不用显示文案做分类，见 D-3）。 */
+const UNKNOWN_SLUG_CODE = UNKNOWN_SLUG_ERROR_CODE;
 
 const expertSchema = z.object({
   slug: z.string(),
@@ -349,16 +360,37 @@ class TTeamRemote extends TypertRemoteService {
     this.ctx.typert.register(TYPERT);
   }
 
+  /**
+   * host 侧服务缺失的统一领域错误。
+   *
+   * 三个访问器（catalog / squads / teams）共用它：**不要**裸抛 `Error` —— 裸 Error 过线会被
+   * 网关折成 `gateway/internal`，领域信息全丢；也**不要**把「host 没加载」塞进别的领域码
+   * （例如 `tTeam/missing-expert`），那会把「服务不可用」显示成「专家不存在」（D-4）。
+   * @param name - 服务名（写进 details，便于面板区分是哪一个）。
+   * @param hint - 面向用户/面板的原因说明。
+   * @returns 带稳定 code 的 RemoteError。
+   */
+  hostUnavailable(name, hint) {
+    return new RemoteError("tTeam/host-unavailable", hint, { service: name });
+  }
+
   /** 名册服务由 host 主插件通过 ctx.reflect.provide 提供。 */
   catalog() {
     const service = this.ctx.get(CATALOG_SERVICE);
-    if (service === undefined) throw new Error("T专家 名册服务不可用（host 插件未加载或已卸载）");
+    if (service === undefined) {
+      throw this.hostUnavailable(CATALOG_SERVICE, "T专家 名册服务不可用（host 插件未加载或已卸载）");
+    }
     return service;
   }
 
   /** 动态名册：完整专家列表 + 已启用 slug + 修订号。 */
   async getCatalog() {
-    return this.catalog().snapshot();
+    try {
+      return await this.catalog().snapshot();
+    } catch (error) {
+      // 服务缺失已在 catalog() 里铸成 tTeam/host-unavailable；这里只兜业务失败。
+      throw this.businessError(error, "tTeam/catalog-unreadable");
+    }
   }
 
   /** 整体替换启用列表；过期修订号由 settings 服务拒绝。 */
@@ -369,27 +401,52 @@ class TTeamRemote extends TypertRemoteService {
       const message = error instanceof Error ? error.message : String(error);
       const code = typeof error === "object" && error !== null ? error.code : undefined;
       // 裸 Error 过线会退化成 gateway/internal 并丢掉 code，所以业务错误统一转成 RemoteError。
-      if (code === "SETTINGS_CONFLICT" || /changed since it was read|another window|其他窗口/.test(message)) {
+      //
+      // 冲突**只认稳定 code**，不再按显示文案兜底（复核 F-3）。依据：
+      //   · 宿主 SettingsConflictError 自带 `code = "SETTINGS_CONFLICT"`，且 dsh-settings 的
+      //     Service Definition 在 JSDoc 里承诺「namespace 移动后拒绝写入即抛 SettingsConflictError」
+      //     —— 也就是说这个 code 是**契约的一部分**，不是实现细节；
+      //   · 原先那条 `/changed since it was read|another window|其他窗口/` 与 D-3 被修掉的根因同类：
+      //     用随宿主版本/locale 变的文案做身份判断，宿主一改措辞冲突就会被误归成 settings-failed；
+      //   · 「其他窗口」在本仓根本不存在于宿主侧，纯属臆测的变体。
+      // 因此无 code 的同类错误会落到下面的 settings-failed（可见且可诊断），而不是被文案猜成冲突。
+      if (code === "SETTINGS_CONFLICT") {
         throw new RemoteError("tTeam/conflict", message, { expectedRevision: String(expectedRevision) });
       }
-      if (message.includes("未知专家")) {
+      // 未知专家 slug 由 host 侧抛带稳定 code 的错误（lib/index.js 的 customError）。
+      // **不再**用 message.includes("未知专家") 分类 —— 显示文案随 locale 变，用它做身份会让
+      // 非中文 locale（或任何文案改写）下的错误直接退化成裸 Error，客户端只剩 gateway/internal（D-3）。
+      if (code === UNKNOWN_SLUG_CODE) {
         throw new RemoteError("tTeam/unknown-expert", message, {});
       }
-      throw error;
+      throw this.businessError(error, "tTeam/settings-failed");
     }
   }
 
   /** 小队定义服务（设置页「小队」标签）。 */
   squads() {
     const service = this.ctx.get(SQUAD_SERVICE);
-    if (service === undefined) throw new Error("T专家 小队服务不可用（host 插件未加载）");
+    if (service === undefined) {
+      throw this.hostUnavailable(SQUAD_SERVICE, "T专家 小队服务不可用（host 插件未加载）");
+    }
     return service;
   }
 
-  /** 团队运行服务（设置页「团队」标签）。 */
+  /**
+   * 团队运行服务（设置页「团队」标签）。
+   *
+   * 这一处**刻意偏离**「缺服务一律 tTeam/host-unavailable」的统一口径，原因有两条，都记录在此：
+   * ① 语义上仍准确 —— 对 `startSquad` 来说「host 没挂团队服务」就是「这支小队起不来」，
+   *    `tTeam/start-failed` 是可读的，而 `host-unavailable` 会丢掉「用户点的是启动」这层上下文；
+   * ② 向后兼容 —— 既有自检（verify.mjs 的 "startSquad 未知小队 → tTeam/start-failed"）与客户端都把
+   *    这个码当作「启动失败」的分类键，改成新码会让唯一被断言的分类断裂。
+   * 缺的是 `catalog`/`squads` 那两个访问器（没有等价的历史承诺），它们统一走 hostUnavailable()。
+   */
   teams() {
     const service = this.ctx.get(TEAM_SERVICE);
-    if (service === undefined) throw new Error("T专家 团队服务不可用（host 插件未加载）");
+    if (service === undefined) {
+      throw new RemoteError("tTeam/start-failed", "T专家 团队服务不可用（host 插件未加载）", { service: TEAM_SERVICE });
+    }
     return service;
   }
 
@@ -439,21 +496,31 @@ class TTeamRemote extends TypertRemoteService {
     }
   }
 
-  /** 业务错误统一转 RemoteError（裸 Error 过线会退化成 gateway/internal 并丢掉 code）。 */
+  /**
+   * 业务错误统一转 RemoteError（裸 Error 过线会退化成 gateway/internal 并丢掉 code）。
+   *
+   * `error.code` 只有**形如 `<domain>/<reason>`** 才能当 wire code 用：系统 errno
+   * （`EACCES`/`ENOENT`/`EPERM`…）过线后被客户端按 code 分支时会误当领域码（D-17），
+   * 所以形态不符一律回落 `fallbackCode`。
+   * @param error - 被捕获的原错误。
+   * @param fallbackCode - 该访问器的领域码。
+   */
   businessError(error, fallbackCode) {
     if (error instanceof RemoteError) return error;
     const message = error instanceof Error ? error.message : String(error);
-    const code = typeof error === "object" && error !== null && typeof error.code === "string" ? error.code : fallbackCode;
-    return new RemoteError(code, message, {});
+    const candidate = typeof error === "object" && error !== null && typeof error.code === "string" ? error.code : undefined;
+    return new RemoteError(DOMAIN_CODE_PATTERN.test(candidate ?? "") ? candidate : fallbackCode, message, {});
   }
 
   /** 按需读取一位专家的 persona 正文（面板预览用）。 */
   async getPrompt(slug, division) {
+    // 先判服务：服务缺失要说「host 不可用」，不能说「专家不存在」——客户端把后者当
+    // 「这位专家不在名册里」，用户于是去一个根本没加载的名册里找人（D-4）。
+    const service = this.catalog();
     try {
-      return await this.catalog().prompt(slug, division);
+      return await service.prompt(slug, division);
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      throw new RemoteError("tTeam/missing-expert", message, { slug });
+      throw this.businessError(error, "tTeam/missing-expert");
     }
   }
 

package/lib/skill.js

@@ -1,11 +1,17 @@
 /**
- * 运维 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 +19,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 +53,7 @@ function readText(path) {
 /**
  * 取 SKILL.md frontmatter 里的一个单行标量字段。
  *
- * 只认单行，所以本 skill 的 `description` 必须写在一行里 —— 刻意不引 YAML 依赖，
+ * 只认单行，所以随包 skill 的 `description` 必须写在一行里 —— 刻意不引 YAML 依赖，
  * frontmatter 里就只有 name/description 两个键。
  * @param text - 完整 SKILL.md 文本。
  * @param key - 字段名。
@@ -102,48 +117,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

@@ -35,16 +35,35 @@ function memberSlug(member) {
   return "";
 }
 
+/**
+ * 编译器的成员上限默认值（与 `data/team-profiles.py` 的 `MAX_MEMBERS` 同一口径）。
+ *
+ * 它只是**兼容旧编译器的回退默认**，不是第二个真源：调用方通过 `maxMembers` 把
+ * `Config.maxMembers` 传进来，编译器支持 `--max-members` 时以传入值为准（见 `build()`）。
+ */
+export const COMPILER_DEFAULT_MAX_MEMBERS = 8;
+
 /**
  * @param generator - 小队编译器路径。调用方**优先传包内那份**（`<包>/data/team-profiles.py`）：
  *   它是随插件版本走的**代码**，而数据目录里那份只在首次启动时播种一次（非破坏性），
  *   升级时不会更新 —— 一直用数据目录那份，等于这个版本的编译器修复永远送不到老用户手里。
+ * @param maxMembers - 成员上限（来自 `Config.maxMembers`）。只有编译器声明支持 `--max-members`
+ *   时才会真正生效；旧编译器把上限写死在源码里，此时会**记一条 warn** 并退回它的默认值，
+ *   而不是让保存小队在「改大上限」后必然编译失败并回滚（D-14）。
  */
-export function createSquadService({ teamsFile, catalog, python = "python3", generator: generatorPath }) {
+export function createSquadService({ teamsFile, catalog, python = "python3", generator: generatorPath, maxMembers }) {
   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;
   let lastBuild = { at: 0, ok: true, output: "" };
 
   function readSpec() {
@@ -136,6 +155,9 @@ export function createSquadService({ teamsFile, catalog, python = "python3", gen
     };
   }
 
+  /** 编译器**实际**会执行的上限：旧编译器不认 --max-members，用它写死的默认值。 */
+  const effectiveMemberLimit = () => (generatorSupportsMemberLimit ? memberLimit : COMPILER_DEFAULT_MAX_MEMBERS);
+
   /** 校验（生成器之外的第一道闸门，错误信息面向面板）。 */
   function validate(squads) {
     if (!Array.isArray(squads) || squads.length === 0) {
@@ -153,6 +175,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;
@@ -198,7 +230,18 @@ export function createSquadService({ teamsFile, catalog, python = "python3", gen
       return lastBuild;
     }
     try {
-      const output = execFileSync(python, [generator, "--teams", teamsFile], {
+      // 上限随 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)] : [];
+      const output = execFileSync(python, [generator, "--teams", teamsFile, ...memberArgs], {
         cwd: dataDir,
         encoding: "utf8",
         stdio: ["ignore", "pipe", "pipe"],
@@ -234,5 +277,10 @@ export function createSquadService({ teamsFile, catalog, python = "python3", gen
     return await list();
   }
 
-  return { list, save, validate, revision: revisionOf, generator, dataDir };
+  return {
+    list, save, validate, revision: revisionOf, generator, dataDir,
+    // 让调用方（与自检）看得到「这次编译用的是哪个上限、编译器到底认不认这个参数」。
+    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/quality-gates.js

@@ -97,14 +97,37 @@ export function pathMatchesScope(path, pattern) {
     const rawPattern = pattern.trim().replaceAll('\\', '/');
     if (rawPattern.startsWith('~') || rawPattern.startsWith('/') || /^[A-Za-z]:/.test(rawPattern))
         return false;
+    // 审计 N-20：旧实现只在模式**以 `/` 结尾**时才当目录，于是 `inScope: ["src"]` 对 `src/a.ts`
+    // 返回 false —— 写域等于没声明，真正该拦的写冲突会被放过。这里补齐两种常见写法：
+    //   · `src`  —— 不含扩展名的裸目录名，按目录前缀处理（含 `.` 的仍按文件精确匹配，保住 `src/a.ts` 语义）
+    //   · `src/*` / `src/**` —— 单层 / 任意层通配
     const directory = rawPattern.endsWith('/');
+    const wildcard = rawPattern.includes('*');
+    const bareDirectory = !directory && !wildcard && !rawPattern.includes('.') && rawPattern !== '.' && rawPattern !== '';
+    if (wildcard) {
+        const normalizedWildcardPattern = normalizeWorkspacePath(rawPattern);
+        if (normalizedWildcardPattern === undefined)
+            return false;
+        // 逐段翻译：`*` = 单层，`**` = 任意层；其余段按字面量并转义正则元字符。
+        const escaped = normalizedWildcardPattern
+            .split('/')
+            .map((segment) => {
+                if (segment === '**')
+                    return '.*';
+                if (segment === '*')
+                    return '[^/]+';
+                return segment.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+            })
+            .join('/');
+        return new RegExp(`^${escaped}$`, 'u').test(normalizedPath);
+    }
     const normalizedPattern = normalizeWorkspacePath(rawPattern);
     if (normalizedPattern === undefined) {
         if (directory && (rawPattern === './' || rawPattern === '/' || rawPattern === '.'))
             return true;
         return false;
     }
-    if (directory || rawPattern === './' || rawPattern === '.') {
+    if (directory || bareDirectory || rawPattern === './' || rawPattern === '.') {
         if (normalizedPattern === '')
             return true;
         return normalizedPath === normalizedPattern || normalizedPath.startsWith(`${normalizedPattern}/`);

package/lib/teams/state.js

@@ -235,14 +235,26 @@ export function readTeamSync(stateRoot, teamId) {
 }
 /**
  * Persist one team record (inside the caller's lock).
+ *
+ * **落盘前必须先过读侧同一套判据（审计 N-18）**：`readTeam` 会 `coerceTeamState`，不合法就抛
+ * `invalid T Team state in team "<id>"`。曾经的缺陷是 `writeTeam` **完全不校验**，于是状态可以被写成
+ * 引擎自己拒绝读的形态（例如 provider 每次 spawn 返回同一个 childId → 成员 id 重复），
+ * 之后**任何**团队工具都会永久抛错、整支团队报废，而错误串里没有任何可定位字段。
+ * 写侧与读侧用同一判据，两者就无法再分叉：能写下去的，一定读得回来。
  * @param stateRoot - resolved absolute state root directory.
  * @param state - the record to persist.
  */
 export async function writeTeam(stateRoot, state) {
+    const teamId = isRecord(state) ? state['id'] : undefined;
+    if (coerceTeamState(JSON.parse(JSON.stringify(state)), teamId) === undefined) {
+        throw new Error(`refusing to persist invalid T Team state for team "${String(teamId ?? '(缺少 id)')}"：`
+            + '写入前校验未通过（与 readTeam 同一判据）。常见原因：成员 id 重复、成员缺 joinedAt、'
+            + 'status 不在 idle/working/removed 之内、任务缺 createdAt/updatedAt/dependencies。');
+    }
+    await mkdir(join(stateRoot, state.id), { recursive: true });
     await atomicWriteText(join(stateRoot, state.id, 'team.json'), JSON.stringify(state, null, 2));
 }
-/** Read the durable set of member session ids retired by remove/delete. */
-function parseRetiredMemberIds(raw) {
+/** Read the durable set of member session ids retired by remove/delete. */function parseRetiredMemberIds(raw) {
     const parsed = JSON.parse(stripLeadingBom(raw));
     if (!Array.isArray(parsed) || parsed.some(value => typeof value !== 'string' || value === '')) {
         throw new Error('invalid T Team retired member index');

package/lib/teams/tools.js

@@ -15,6 +15,7 @@ import { appendTeamEvent, captainSessionOf } from "./events.js";
 import { acknowledgeMailbox, appendMailbox, archiveTeamDir, beginTaskAttempt, CAPTAIN_KEY, createMessage, createTeamDir, findTeamByCaptain, findTeamByParticipant, cancelUnfinishedTask, invalidateTaskAttempt, readUnreadMailbox, recordRetiredMemberIds, releaseMailboxDelivery, readTeam, sanitizeKey, transitionError, unsatisfiedDependencies, withTeamLock, writeTeam, removeTeamDir, validateCreateTask, evaluateQualityCompletion, planQualityFollowUp, resumeTeamState, buildCoverageMatrix, canDeclareDelivery, describeQualityLoop, sanitizeReviewAcceptance, sanitizeReviewObjective, normalizeBlankOptionalTaskFields, taskKindOf, } from "./state.js";
 import { deliverToMember, installRetiredMemberGuard, installMemberSelectionRuntime, interruptMember, memberActivity, resolveMemberLlmSelection, spawnMember, steerCaptainReport, validateMemberLlmSelections, } from "./members.js";
 import { TERMINAL_TASK_STATUSES } from "./types.js";
+import { normalizeAssigneeForCreate } from "./assignee-contract.js";
 import { installTeamScheduler } from "./scheduler.js";
 import { resolveTeamProfile } from "./profiles.js";
 export { steerCaptainReport } from "./members.js";
@@ -1034,7 +1035,7 @@ export function registerTTeamTools(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: 't_team_create_task',
-        description: 'Create a task in your team\'s task list. Every call must include a non-empty subject, including verification and review tasks. Tasks can depend on other tasks (dependencies): a task is only claimable once every dependency is completed. Optionally assign it to a member, who still claims it before working.',
+        description: 'Create a task in your team\'s task list. Every call must include a non-empty subject, including verification and review tasks. Tasks can depend on other tasks (dependencies): a task is only claimable once every dependency is completed. Optionally assign it to a member, who still claims it before working. Omit assignee to put the task in the shared pool; the captain cannot be set here — take a task over with t_team_reassign_task(assignee="captain").',
         parameters: {
             subject: { type: 'string', required: true, description: 'Required non-empty title for this task. Never omit it, including for verification or review tasks.' },
             description: { type: 'string', description: 'What needs to be done, in detail.' },
@@ -1043,7 +1044,7 @@ export function registerTTeamTools(ctx, config) {
                 items: { type: 'string' },
                 description: 'Task ids this task depends on (must be completed before this task can be claimed).',
             },
-            assignee: { type: 'string', description: 'Optional member name this task is intended for.' },
+            assignee: { type: 'string', description: 'Optional active member name this task is intended for. Omit for the shared pool. Never "captain": create the task unassigned, then take it over with t_team_reassign_task(assignee="captain").' },
             kind: {
                 type: 'string',
                 enum: ['work', 'requirements', 'implementation', 'verification', 'review', 'repair', 'integration'],
@@ -1133,8 +1134,13 @@ export function registerTTeamTools(ctx, config) {
                         throw new Error(`dependency "${dependency}" does not exist in team "${fresh.name}"`);
                     }
                 }
-                if (args.assignee !== undefined)
+                if (args.assignee !== undefined) {
+                    // 预留键 `captain` 必须在这里被拦下并**指向 reassign_task**：
+                    // 直接丢给 requireMember 只会回一句 no active member named "captain"，
+                    // 那是按成员名精确匹配的报错，完全不提示正确入口（曾经的实际缺陷）。
+                    normalizeAssigneeForCreate(args.assignee);
                     requireMember(fresh, args.assignee);
+                }
                 const kind = gate.kind ?? 'work';
                 const objective = kind === 'review' || kind === 'requirements'
                     ? sanitizeReviewObjective(input.objective)