dsh-plugin-t-expert 0.2.4 → 0.2.5

package/README.md

@@ -1,6 +1,6 @@
 # T专家（dsh-plugin-t-expert）
 
-**T专家** 把一个 **22 个分区 / 314 位专家**的名册（含全量中文译文）
+**T专家** 把一个 **22 个分类 / 314 位专家**的名册（含全量中文译文）
 做成一个独立的 DeepSeek Harness 插件，并在插件内部**自带一套多智能体团队引擎**（多成员小队、任务 DAG、调度、邮箱、活动面板）。
 
 装上一个插件，你同时得到三样东西：
@@ -8,10 +8,10 @@
 | 能力 | 说明 |
 | --- | --- |
 | 专家名册 | 314 位专家，含**中文侧车**（中文名 / 中文简介 / 中文人格正文，当前覆盖率 314/314） |
-| `@` 召唤 | 在输入框打 `@` 出现按分区分组的中文菜单，选中的专家作为原生引用 chip 进入本轮对话 |
+| `@` 召唤 | 在输入框打 `@` 出现按分类分组的中文菜单，选中的专家作为原生引用 chip 进入本轮对话 |
 | 模型工具 | `list_t_experts` / `summon_t_expert` / `summon_t_experts` / `t_team_plan_check` 四个工具 |
 | 小队命令 | `/t` 列出小队；`/t <小队名\|别名> <目标>` 直接拉起一支多成员小队干活 |
-| 设置页 | 设置 → T专家，两个标签：**专家**（启停 / 看提示词）与 **队伍**（小队模板 + 运行中的团队） |
+| 设置页 | 设置 → T专家，**三个标签**：**专家**（启停 / 看提示词 / 新建自建专家）、**分类**（新建 / 改名 / 删除自建分类）、**队伍**（小队模板 + 运行中的团队） |
 
 专家名册与团队引擎**解耦**：团队引擎挂载失败（例如宿主子代理契约不匹配）时，
 专家名册、`@` 召唤、`/t` 列表仍然照常可用。
@@ -91,12 +91,12 @@ error: profile "desktop" is managed exclusively by the Electron application
 
 ```
 ~/.t-team/
-├── experts/              # 专家名册：<分区>/<slug>.md（22 个分区、314 位）
+├── experts/              # 专家名册：<分类>/<slug>.md（22 个分类、314 位）
 ├── zh/                   # 中文侧车（译文只在这里，永不写进 experts/）
 │   ├── names.json        # slug → 中文名
 │   ├── descriptions.json # slug → 中文简介
-│   ├── divisions.json    # 分区中文标签
-│   ├── <分区>/<slug>.md  # 中文人格正文（与 experts/ 同相对路径）
+│   ├── divisions.json    # 分类中文标签
+│   ├── <分类>/<slug>.md  # 中文人格正文（与 experts/ 同相对路径）
 │   ├── manual.json       # 人工补译：names / descriptions（优先于自动层）
 │   ├── manual-bodies/    # 人工补译正文（最高优先，不会被覆盖）
 │   └── COVERAGE.json     # 中文覆盖率与缺口清单
@@ -117,10 +117,11 @@ error: profile "desktop" is managed exclusively by the Electron application
 
 | 配置项 | 类型 | 默认值 | 含义 |
 | --- | --- | --- | --- |
-| `root` | string | `~/.t-team/experts` | 专家名册目录，读 `experts/<分区>/<slug>.md` |
-| `zhRoot` | string | `~/.t-team/zh` | 中文侧车目录（名字 / 简介 / 正文 / 分区标签） |
+| `root` | string | `~/.t-team/experts` | 专家名册目录，读 `experts/<分类>/<slug>.md` |
+| `zhRoot` | string | `~/.t-team/zh` | 中文侧车目录（名字 / 简介 / 正文 / 分类标签） |
+| `customRoot` | string | `~/.t-team/custom` | 自建专家目录（面板「新建专家」写这里，默认落 `custom` 分类，可在表单里另建分类；与 `root` 分开是硬要求） |
 | `provider` | string | `"spawn"` | 召唤专家时使用的子代理 provider |
-| `divisions` | string[] | `[]` | 留空 = 自动扫描 `root` 下所有含 `.md` 的分区目录 |
+| `divisions` | string[] | `[]` | 留空 = 自动扫描 `root` 下所有含 `.md` 的分类目录 |
 | `maxDepth` | natural | 无默认（不传则不加限制） | 传给子代理的嵌套深度上限 |
 | `maxSummonBatch` | natural | `8` | 一次 `summon_t_experts` 最多几位专家 |
 | `summonConcurrency` | natural | `4` | `summon_t_experts` 的并发度 |
@@ -154,7 +155,7 @@ error: profile "desktop" is managed exclusively by the Electron application
 
 | 工具 | 作用 |
 | --- | --- |
-| `list_t_experts` | 列出**已启用**专家的分区与数量；传入分区名可列出该分区专家（用于挑出唯一的专家名） |
+| `list_t_experts` | 列出**已启用**专家的分类与数量；传入分类名可列出该分类专家（用于挑出唯一的专家名） |
 | `summon_t_expert` | 召唤 1 位专家：以该专家的完整人格跑一个子代理并返回结果（阻塞等待） |
 | `summon_t_experts` | 并行召唤多位专家：最多 8 位、并发 4；部分失败时仍返回成功的结果 |
 | `t_team_plan_check` | **只读** DAG 预检：把打算创建的一批团队任务先跑一遍引擎校验，一次报出全部问题、警示与建议执行顺序 |
@@ -208,6 +209,8 @@ error: profile "desktop" is managed exclusively by the Electron application
 
 随包分发的专家名册、中文译文与内置团队引擎各自按 MIT 授权使用，
 各自的来源、版本与署名要求写在 `THIRD-PARTY-NOTICES` 里，**完整许可文本随包放在 `vendor/` 下**。
+名册与引擎**不再从上游同步**：`data/experts/` 与 `lib/teams/` 现在就是本仓的真源 / 手工源码，
+而上游项目的署名义务不因停止同步而消失，故这些声明必须保留。
 再分发本插件（含修改版）时，请一并保留 `LICENSE`、`THIRD-PARTY-NOTICES` 与 `vendor/` 下的许可文本。
 
 ---
@@ -216,24 +219,38 @@ error: profile "desktop" is managed exclusively by the Electron application
 
 ```bash
 npm install          # 安装依赖（peer 依赖由 DSH 宿主提供）
-npm run build        # 品牌化 + 构建客户端产物
+npm run build        # 构建客户端产物
 npm run verify       # 自检套件（插件契约、工具、remote、客户端产物、播种与快照一致性）
 npm run sync-data    # 把运行时数据同步进包内 data/（默认源 ~/.t-team）
 ```
 
 > ⚠️ 这些 script 的实现文件**不在本仓库里**：维护者把它们放在仓库同级的运维目录
-> （`../brand.mjs`、`../build-client.mjs`、`../verify.mjs`、`../sync-data.mjs`，由 `package.json`
+> （`../build-client.mjs`、`../verify.mjs`、`../sync-data.mjs`、`../add-expert.py`，由 `package.json`
 > 的 `scripts` 以相对路径引用）。只 clone 本仓库是跑不了构建与自检的；要发布请使用完整的工作目录。
 >
-> `npm run build` 必须**先**品牌化再构建客户端：客户端产物把品牌化后的引擎 bundle 内联进去，
-> 顺序错了会把旧文本打进产物。
+> 内置团队引擎（`lib/teams/`）是**手工维护的源码**：品牌化生成链与上游镜像已经移除（2026-09-12），
+> 改引擎直接改 `lib/teams/*.js` 即可，不再有"改规则 → 重新生成"这一步。
 
 ---
 
 ## 九、已知限制
 
-- 客户端面板**不做自定义专家的增删改**；要加自己的专家，直接把 `.md` 放进 `~/.t-team/experts/<分区>/`，宿主按 mtime 指纹自动重载，不需要重启。
-  （中文侧车同理：`zh/` 下的名字 / 简介 / 正文文件增删改都会按指纹重载。）
+- **名册的增删（内置名册）**：`data/experts/` 就是真源（不再从上游拉取）。维护者用运维台
+  `bash ~/web/t-team/tz.sh 1` 新增：选分类（或新建分类）→ 给一个专家 `.md` 的路径 → 脚本把它
+  同时写进源码 `data/experts/<分类>/<slug>.md`（随包发布）与运行时 `~/.t-team/experts/<分类>/`（立即生效）。
+  删除走 `tz.sh 2`，统计 `tz.sh 3`，一致性校验 `tz.sh 5`。要求 `.md` 开头有 frontmatter
+  （`name` 与 `description` 必填，`emoji` 可选）；没有 frontmatter 的文件可以在命令里用
+  `--name/--description` 补出来。分类名与插件扫描口径一致：`a-z 0-9 . -`，不以 `.` 开头。
+- **自定义专家**：在 设置 → T专家 → 专家 里点「＋ 新建专家」，填名称、简介与人格正文即可；自建的会在卡片上带「自建」标记，可以就地编辑或删除。
+  它们写在 `customRoot`（默认 `~/.t-team/custom/<分类>/<slug>.md`），**与随包发布的内置名册（`experts/`）分开**：内置名册是包的一部分，重装/升级会整棵替换，往里放文件会被覆盖掉。
+- **自建分类**：表单里的「分类」下拉列出**全部分类**——官方 22 个（学术 / 金融 / 游戏 …）和你自建的都可以选；
+  选「＋ 新建分类…」则填两个字段——**目录名**（小写 ASCII，成为 `~/.t-team/custom/<目录名>/`）与**显示名**（中文，记在 `<customRoot>/divisions.json`）。
+  设置页的 **分类** 标签页可以新建、改名、删除自建分类，并看到每个分类下有多少专家（含其中自建多少）。
+- **把自建专家归到官方分类名下是允许的，也是安全的**：分类只是**归属**，文件永远写 `~/.t-team/custom/<分类>/<slug>.md`，
+  内置名册目录（`experts/`）一个字节都不会动，所以升级插件也不会把它删掉。官方分类本身只读——它的名字与存亡跟随包内名册，不接受本机改名或删除。
+  删除自建分类时若里面还有自建专家会被拒绝（先移走或删掉），不会静默连删。编辑时改分类＝移动文件。
+- 自建专家默认落在「自定义」分类，建好后记得启用；也能被 `/t` 小队挑成队员。
+- 中文侧车（`zh/` 下的名字 / 简介 / 正文）的增删改都按 mtime 指纹自动重载，不需要重启；名册与自建专家同理。
 - 包内快照只在数据目录**缺项**时播种。升级插件只更新包内快照，**不会覆盖你已有的数据目录内容**。
 - 小队定义的改动需要重启 DSH 才对**建队**生效（见第五、六节）。
 - 改插件代码后需要重新 `npm run build`（改了 `src/client.jsx` 才会重新生成客户端产物）并重装/重启。

package/THIRD-PARTY-NOTICES

@@ -12,13 +12,17 @@
 | 上游仓库 | https://github.com/NanmiCoder/dsh-agent-teams |
 | 版本 | `0.1.17-rc.1` |
 | 许可 | MIT（完整文本随包：`vendor/dsh-agent-teams/LICENSE`）— Copyright (c) 2026 程序员阿江(Relakkes) |
-| 位置 | `vendor/dsh-agent-teams/upstream/`（上游文件逐字节原样保留，含 `LICENSE` 与 `VENDOR.md`）、`lib/teams/`（由品牌化工具 `brand.mjs` 从上游镜像生成的品牌化产物：命令 `/agent-teams` → `/t`、工具 `agent_teams_*` → `t_team_*`） |
+| 位置 | `lib/teams/`（16 个文件，由上述上游派生的品牌化产物：命令 `/agent-teams` → `/t`、工具 `agent_teams_*` → `t_team_*`）。它的客户端产物内联在 `lib/client.js` 里 |
+| 许可全文 | `vendor/dsh-agent-teams/LICENSE` |
 
-**对上游镜像的改动**：`vendor/dsh-agent-teams/upstream/` 内的文件**永不修改**；
-`lib/teams/` 是生成物，差异 = 品牌化改名 + `brand.mjs` 中逐条注释的 `FIXES`。
-除改名外，`FIXES` 还包含少量**本地缺陷修补与必要的行为改动**（例如把 profile 上限从 16 抬到 48、
-修正命令视图 key、修正交接期与终态任务的校验、放行 `.env.example` 一类模板文件等）。
-每条 `FIXES` 都声明了期望命中次数，上游文本一变即构建失败，不会静默退回上游行为。
+**本插件对该上游做的改动**（都在 `lib/teams/` 里，可直接对照阅读）：
+一是品牌化改名（命令与工具名、包 id、事件与路由前缀）；二是少量**本地缺陷修补与必要的行为改动**
+（例如把 profile 上限从 16 抬到 48、修正命令视图 key、修正交接期与终态任务的校验、
+放行 `.env.example` 一类模板文件等）。上游文本从未被修改过——我们只在自己的产物里改。
+
+> 2026-09-12 起，上游的**逐字节原样镜像**（`vendor/dsh-agent-teams/upstream/`）与品牌化生成工具
+> （`brand.mjs`）已从仓库移除：`lib/teams/` 转为**手工维护的源码**，不再在构建时从上游重新生成。
+> 停止跟随上游不改变署名义务，故本节保留。
 
 ## 2. 专家名册与中文侧车
 
@@ -27,20 +31,22 @@
 | 英文名册 | The Agency / AgentLand（`msitarzewski/agency-agents`）— MIT，Copyright (c) 2025 AgentLand Contributors。完整文本随包：`vendor/third-party-licenses/agency-agents.LICENSE` |
 | 中文译文 | `jnMetaCode/agency-agents-zh`（中文翻译与本地化）— MIT，Copyright (c) 2025 Michael Sitarzewski（英文原版）、Copyright (c) 2026 jnMetaCode（中文翻译与本地化）。完整文本随包：`vendor/third-party-licenses/agency-agents-zh.LICENSE` |
 | 分发形态 | 上述两部分内容随 `@michengai/dsh-agency-agents` 一同分发（该包自身的 TypeScript 源码与构建脚本为 Apache-2.0，**本插件不打包其任何代码**） |
-| 版本指纹 | 见 `data/source.json` 的 `sourceRevision`；补入部分见同文件的 `extraSource` / `extraSourceVersion` |
-| 位置 | `data/experts/`（22 分区 / 314 位）、`data/zh/`（中文名字 / 简介 / 人格正文 / 分区标签） |
+| 位置 | `data/experts/`（22 个分类 / 314 位）、`data/zh/`（中文名字 / 简介 / 人格正文 / 分类标签） |
+| 维护方式 | 上述内容随本插件分发（`data/` 是发布源，不再从上游重新镜像）；`data/source.json` 是该名册的清单（专家数 / 分类 / 更新时间） |
+
+名册的构成分两部分（总计 314 位）：
 
-名册的构成分两部分：
+- **279 位来自 `msitarzewski/agency-agents`**（上表英文名册一行）。
+- **35 位来自 `@michengai/dsh-agency-agents` 的包内快照**（company / hr / legal / supply-chain
+  四个分类，以及若干中国本地化角色）。这些条目在另一上游仓库的任何历史与分支里都不存在，只随该包分发。
+  它们的英文人格与中文译文同样按上表两个 MIT 项目（AgentLand Contributors / jnMetaCode）的条款使用，
+  完整许可文本与上表共用。与已有角色职能重复的条目未并入。
 
-- **279 位逐字节镜像上游仓库** `msitarzewski/agency-agents`（上表第 1 行），随时可 `git pull` 后重新镜像。
-- **35 位由 `@michengai/dsh-agency-agents` 包内快照补入**（company / hr / legal / supply-chain
-  四个分区，以及若干中国本地化角色）。这些条目在上游仓库的任何历史与分支里都不存在，只随该包分发；
-  其英文人格与中文译文同样按上表两个 MIT 项目（AgentLand Contributors / jnMetaCode）的条款使用，
-  完整许可文本与上表共用。补入范围与逐条判定依据记录在 `data/source.json` 的
-  `extraAdded` / `extraSkipped`（与上游角色职能重复的条目会被排除，不并入名册）。
+> 两部分内容自 2026-09-12 起随本插件分发并作为**名册真源**维护，不再从上游重新拉取或镜像
+> （原镜像 / 补入脚本与逐条判定记录已移除；需要追溯当时来源与判定，见仓库 git 历史）。
 
-`data/zh/manual.json` 与 `data/zh/manual-bodies/` 是**本项目的补充翻译**（用于补齐上游尚未覆盖的
-条目或在译文不准确时覆盖），随本插件以 MIT 发布。
+`data/zh/manual.json` 与 `data/zh/manual-bodies/` 是**本项目的补充翻译**（用于补齐尚未覆盖的条目
+或在译文不准确时覆盖），随本插件以 MIT 发布，同样保留在包内。
 
 ## 3. 分发要求
 

package/data/source.json

@@ -1,8 +1,6 @@
 {
-  "source": "<home>/.agency-agents",
-  "sourceRevision": "6d29a9b",
-  "target": "<home>/web/t-team/data/experts",
-  "syncedAt": "2026-09-12 14:47:18 +0800",
+  "updatedAt": "2026-09-12 15:56:06 +0800",
+  "expertFiles": 314,
   "divisions": [
     "academic",
     "company",
@@ -27,88 +25,5 @@
     "support",
     "testing"
   ],
-  "expertFiles": 314,
-  "extraSource": "<home>/.dsh/profiles/desktop/node_modules/@michengai/dsh-agency-agents/assets/agency-agents",
-  "extraSourceVersion": "0.1.41",
-  "extraAdded": 35,
-  "extraSkipped": [
-    {
-      "division": "company",
-      "slug": "chief-of-staff",
-      "duplicateOf": "specialized-chief-of-staff",
-      "verdict": "duplicate"
-    },
-    {
-      "division": "engineering",
-      "slug": "engineering-network-engineer-china",
-      "duplicateOf": "engineering-china-network-engineer",
-      "verdict": "duplicate"
-    },
-    {
-      "division": "engineering",
-      "slug": "engineering-security-engineer",
-      "duplicateOf": "security-appsec-engineer",
-      "verdict": "duplicate"
-    },
-    {
-      "division": "engineering",
-      "slug": "engineering-threat-detection-engineer",
-      "duplicateOf": "security-threat-detection-engineer",
-      "verdict": "duplicate"
-    },
-    {
-      "division": "finance",
-      "slug": "finance-financial-forecaster",
-      "duplicateOf": "finance-financial-analyst",
-      "verdict": "near-duplicate"
-    },
-    {
-      "division": "hr",
-      "slug": "hr-recruiter",
-      "duplicateOf": "specialized-recruitment-specialist",
-      "verdict": "duplicate"
-    },
-    {
-      "division": "marketing",
-      "slug": "marketing-bilibili-strategist",
-      "duplicateOf": "marketing-bilibili-content-strategist",
-      "verdict": "near-duplicate"
-    },
-    {
-      "division": "marketing",
-      "slug": "marketing-ecommerce-operator",
-      "duplicateOf": "marketing-china-ecommerce-operator",
-      "verdict": "duplicate"
-    },
-    {
-      "division": "marketing",
-      "slug": "marketing-wechat-operator",
-      "duplicateOf": "marketing-wechat-official-account",
-      "verdict": "duplicate"
-    },
-    {
-      "division": "marketing",
-      "slug": "marketing-xiaohongshu-operator",
-      "duplicateOf": "marketing-xiaohongshu-specialist",
-      "verdict": "duplicate"
-    },
-    {
-      "division": "specialized",
-      "slug": "prompt-engineer",
-      "duplicateOf": "engineering-prompt-engineer",
-      "verdict": "duplicate"
-    },
-    {
-      "division": "specialized",
-      "slug": "specialized-pricing-optimizer",
-      "duplicateOf": "specialized-pricing-analyst",
-      "verdict": "near-duplicate"
-    },
-    {
-      "division": "support",
-      "slug": "support-recruitment-specialist",
-      "duplicateOf": "specialized-recruitment-specialist",
-      "verdict": "duplicate"
-    }
-  ]
+  "note": "本仓名册清单：data/experts 是真源，由 add-expert.py 维护（上游同步已移除）"
 }

package/data/team-profiles.py

@@ -42,7 +42,7 @@ DEFAULT_PATCH = os.environ.get("T_TEAM_PATCH", os.path.join(HOME, ".dsh", "profi
 MARKER_START = "# >>> t-team teams（由 team-profiles.py 生成，勿手改；改 teams.json 后重跑）"
 MARKER_END = "# <<< t-team teams"
 
-MAX_PROFILES = 48          # 引擎侧已由品牌化工具 brand.mjs 把 MAX_TEAM_PROFILES 调到 48（上游默认 16）
+MAX_PROFILES = 48          # 引擎侧 lib/teams/profiles.js 已把 MAX_TEAM_PROFILES 调到 48（原默认 16）
 MAX_MEMBERS = 8            # 一个 profile 的成员数上限（经验值：队长上下文压力）
 MAX_SEED_TASKS = 32        # AgentTeams: MAX_PROFILE_TASKS
 PROFILE_KEY_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")

package/data/zh/COVERAGE.json

@@ -14,7 +14,7 @@
     "missingDescription": [],
     "missingBody": []
   },
-  "generatedFrom": "<home>/.dsh/profiles/desktop/node_modules/@michengai/dsh-agency-agents",
+  "generatedFrom": "<home>/web/t-team/vendor/agency-agents",
   "divisions": 22,
   "unlabelledDivisions": []
 }

package/lib/catalog.js

@@ -5,8 +5,9 @@
  * 其中 game-development 之类的分区可以再嵌套一层子目录（递归扫描）。
  * persona 正文在召唤时按需读取，不在目录列表阶段预加载。
  */
-import { readdir, readFile, stat } from "node:fs/promises";
-import { join, relative } from "node:path";
+import { createHash } from "node:crypto";
+import { mkdir, readdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
 
 /** 内置的分区目录名（= divisions.json 的键）。 */
 export const DEFAULT_DIVISIONS = [
@@ -50,10 +51,12 @@ export const DIVISION_LABEL = {
   specialized: { zh: "专业", en: "Specialized" },
   support: { zh: "支持", en: "Support" },
   testing: { zh: "测试", en: "Testing" },
+  /** 用户自建专家的分区（customRoot 下的默认分区），面板里与官方 22 个分区并列但可一眼分辨。 */
+  custom: { zh: "自定义", en: "Custom" },
 };
 
 /**
- * 取分区显示名：优先侧车目录 zh/divisions.json（数据驱动，上游新增分区只需补数据），
+ * 取分类显示名：优先侧车目录 zh/divisions.json（数据驱动，新增分类只需补数据），
  * 其次内置对照表，最后回退分区 key。
  */
 export function divisionOf(division, labels) {
@@ -73,7 +76,7 @@ export async function loadDivisionLabels(zhRoot) {
 
 /**
  * 自动发现分区：root 下所有直接含 .md 的顶层目录。
- * 这样上游新增的分区不必改代码就能被扫描到。
+ * 这样新增的分类不必改代码就能被扫描到。
  */
 export async function discoverDivisions(root) {
   let entries;
@@ -114,10 +117,13 @@ function field(frontmatter, key) {
   return match === null ? undefined : unquote(match[1]);
 }
 
-/** 解析 frontmatter 元数据（name/description/descriptionEn/emoji/color/vibe）。 */
+/** 解析 frontmatter 元数据（name/nameEn/description/descriptionEn/emoji/color/vibe）。 */
 export function parseMetadata(frontmatter) {
   return {
     name: field(frontmatter, "name"),
+    // 内置名册的英文名就是 name（英文原文），只有自建专家会单独写 nameEn；
+    // 不解析它的话，自建专家的英文名落盘却读不回来，重名校验与英文locale 都会失效。
+    nameEn: field(frontmatter, "nameEn"),
     description: field(frontmatter, "description"),
     descriptionEn: field(frontmatter, "descriptionEn"),
     emoji: field(frontmatter, "emoji"),
@@ -169,61 +175,103 @@ export async function assertDirectory(root) {
 
 /**
  * 载入花名册。
- * @param root 专家根目录
+ *
+ * 两个根：`root` 是随包发布的内置名册（**只读**，由 add-expert.py 维护）；`options.customRoot`
+ * 是用户自建专家的独立目录（默认 `~/.t-team/custom`）。两者必须分开——内置根是破坏性镜像，
+ * 放进去的自建专家会在下次同步时被当成"意外文件"删掉（2026-09-12 实测）。
+ *
+ * @param root 内置专家根目录
  * @param divisions 要扫描的分区目录名
  * @returns Map<slug, Expert>，Expert 额外带 personaPath（正文按需读取）
  */
 export async function loadCatalog(root, divisions, options = {}) {
   await assertDirectory(root);
   const zhRoot = typeof options.zhRoot === "string" && options.zhRoot !== "" ? options.zhRoot : undefined;
+  const customRoot = typeof options.customRoot === "string" && options.customRoot !== "" ? options.customRoot : undefined;
   // 中文侧车目录：names.json / descriptions.json / <与 experts 同相对路径的 .md>。
-  // 译文永不写进 experts（那是上游镜像），所以上游更新不受影响。
+  // 译文永不写进 experts（那是随包发布的只读名册），所以名册更新不受影响。
   const zhNames = zhRoot === undefined ? {} : await readJson(join(zhRoot, "names.json"));
   const zhDescriptions = zhRoot === undefined ? {} : await readJson(join(zhRoot, "descriptions.json"));
   const divisionLabels = await loadDivisionLabels(zhRoot);
-  // 未显式配置分区时自动发现：上游新增分区无需改代码。
-  const scanned = divisions !== undefined && divisions.length > 0 ? divisions : await discoverDivisions(root);
+  // 自建分类的显示名表（键 = 声明过的自建分类）；官方标签优先级更高，见文件末尾的合并处。
+  const customLabels = await loadCustomLabels(customRoot);
+  // 未显式配置分类时自动发现：新增分类无需改代码。
+  // 发现结果一律按 isValidDivision 过一遍，**列表与扫描共用同一份过滤结果** ——
+  // 否则目录名不合规时会出现「分区名在列表里、专家却一个都没扫到」的空分区（已实测）。
+  const scanned = (divisions !== undefined && divisions.length > 0 ? divisions : await discoverDivisions(root))
+    .filter(isValidDivision);
   const catalog = new Map();
-  for (const division of scanned) {
-    if (!SEGMENT_PATTERN.test(division) || division.includes("..")) continue;
-    const dir = join(root, division);
-    await walkMarkdown(dir, async (filePath, fileName) => {
-      const slug = fileName.slice(0, -3);
-      if (!SLUG_PATTERN.test(slug)) return;
-      let raw;
-      try {
-        raw = stripBom(await readFile(filePath, "utf8"));
-      } catch {
+
+  /** 解析一个 persona 文件并放进名册；自定义根的文件额外带 custom 标记与写回路径。 */
+  async function ingest(fromRoot, division, filePath, fileName, isCustom) {
+    const slug = fileName.slice(0, -3);
+    if (!SLUG_PATTERN.test(slug)) return;
+    let raw;
+    try {
+      raw = stripBom(await readFile(filePath, "utf8"));
+    } catch {
+      return;
+    }
+    const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (match === null) return;
+    const meta = parseMetadata(match[1]);
+    if (!meta.name || !meta.description) return;
+    if (catalog.has(slug)) {
+      if (isCustom) {
+        // 内置优先：自定义目录里出现同名 slug 时保留内置那位，不覆盖也不报冲突。
+        console.warn(`[t-team] 自定义专家与内置专家同 slug，已忽略：${slug}（${filePath}）`);
         return;
       }
-      const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-      if (match === null) return;
-      const meta = parseMetadata(match[1]);
-      if (!meta.name || !meta.description) return;
-      if (catalog.has(slug)) {
-        console.warn(`[t-team] slug 冲突，后者覆盖前者：${slug}`);
-      }
-      catalog.set(slug, {
-        slug,
-        name: meta.name,
-        nameEn: meta.name,
-        description: meta.description,
-        descriptionEn: meta.descriptionEn ?? "",
-        emoji: meta.emoji ?? "",
-        color: meta.color ?? "",
-        vibe: meta.vibe ?? "",
-        division,
-        personaPath: filePath,
-        relativePath: relative(root, filePath),
-      });
-    });
+      console.warn(`[t-team] slug 冲突，后者覆盖前者：${slug}`);
+    }
+    const entry = {
+      slug,
+      name: meta.name,
+      nameEn: meta.nameEn ?? meta.name,
+      description: meta.description,
+      descriptionEn: meta.descriptionEn ?? "",
+      emoji: meta.emoji ?? "",
+      color: meta.color ?? "",
+      vibe: meta.vibe ?? "",
+      division,
+      personaPath: filePath,
+      relativePath: relative(fromRoot, filePath),
+    };
+    if (isCustom) {
+      // 自建专家的名字就是用户写的那一个（通常是中文），不需要侧车译文即可显示中文。
+      entry.nameZh = meta.name;
+      entry.custom = true;
+      entry.customPath = filePath;
+    }
+    catalog.set(slug, entry);
   }
+
+  for (const division of scanned) {
+    await walkMarkdown(join(root, division), (filePath, fileName) => ingest(root, division, filePath, fileName, false));
+  }
+
+  // 自建专家根：目录可以不存在（还没建过任何自建专家），分区同样自动发现。
+  let customDivisions = [];
+  if (customRoot !== undefined) {
+    customDivisions = (await discoverDivisions(customRoot)).filter(isValidDivision);
+    for (const division of customDivisions) {
+      await walkMarkdown(join(customRoot, division), (filePath, fileName) => ingest(customRoot, division, filePath, fileName, true));
+    }
+  }
+
   if (catalog.size === 0) throw new Error(`专家目录为空或没有可解析的专家：${root}`);
   markConflicts(catalog);
-  catalog.divisions = scanned;
-  catalog.labels = divisionLabels;
+  catalog.divisions = [...scanned, ...customDivisions.filter((item) => !scanned.includes(item))];
+  catalog.rosterDivisions = scanned;          // 只来自内置根（官方分类，只读）
+  catalog.customDivisions = customDivisions;
+  catalog.customRoot = customRoot;
+  // 自建分类的显示名表；它的**键**同时就是"声明过的自建分类"——允许空分类（目录里还没有专家）。
+  catalog.customLabels = customLabels;
+  // 官方标签优先：官方分类的显示名跟随中文侧车，不允许被本机覆盖（2026-09-12 用户选定）。
+  catalog.labels = { ...customLabels, ...divisionLabels };
   if (zhRoot !== undefined) {
     for (const expert of catalog.values()) {
+      if (expert.custom === true) continue;              // 自建专家不查侧车
       const nameZh = zhNames[expert.slug];
       if (typeof nameZh === "string" && nameZh !== "") expert.nameZh = nameZh;
       const descriptionZh = zhDescriptions[expert.slug];
@@ -296,6 +344,122 @@ function normalizeName(value) {
   return String(value ?? "").trim().toLowerCase();
 }
 
+/** 导出给写回服务做「重名」校验用（与 resolveExpert 同一口径）。 */
+export function normalizedKey(value) {
+  return normalizeName(value);
+}
+
+// ---------------------------------------------------------------- 自建专家（写回）
+
+/** 自建专家的默认分区目录名（新建时的落点；用户可以在面板里另建分区）。 */
+export const CUSTOM_DIVISION = "custom";
+/** 自建专家的字段长度上限（校验用，写回前拦，不给面板塞坏数据）。 */
+export const CUSTOM_LIMITS = { name: 60, nameEn: 80, description: 240, body: 40000, divisionLabel: 40 };
+
+/**
+ * 分区目录名是否合法 —— **与扫描口径完全一致**（`SEGMENT_PATTERN` + 不许 `..`）。
+ *
+ * 两处必须共用这一个判断：`discoverDivisions()` 发现什么、`loadCatalog()` 就扫什么。
+ * 曾经列表用未过滤的结果、扫描用过滤过的结果，于是手建一个中文目录名后，
+ * 面板上凭空多出一个零专家的分区（2026-09-12 实测）。非 ASCII 分区名一律不支持：
+ * 分区 key 会进 `@` 源 id 与文件路径，ASCII 才和 slug、小队 key 的口径一致；
+ * 中文显示名走 `customDivisions[].label`（落在 `<customRoot>/divisions.json`）。
+ */
+export function isValidDivision(division) {
+  const key = String(division ?? "").trim();
+  return SEGMENT_PATTERN.test(key) && !key.includes("..");
+}
+
+/** 自建专家的文件路径：`<customRoot>/<division>/<slug>.md`（division 省缺时落默认分区）。 */
+export function customExpertPath(customRoot, slug, division = CUSTOM_DIVISION) {
+  return join(customRoot, division, `${slug}.md`);
+}
+
+/** 自建分区的显示名表：`{ "<division>": "<显示名>" }`（缺文件当空表）。 */
+export async function loadCustomLabels(customRoot) {
+  if (typeof customRoot !== "string" || customRoot === "") return {};
+  const raw = await readJson(join(customRoot, "divisions.json"));
+  const out = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (typeof value === "string" && value.trim() !== "" && isValidDivision(key)) out[key] = value.trim();
+  }
+  return out;
+}
+
+/**
+ * 记下一个自建分区的显示名（原子写；label 为空则删除该键）。
+ * 面板里「新建分区」填的中文名落在这里，`divisionOf()` 就能把它显示成中文。
+ */
+export async function saveCustomLabel(customRoot, division, label) {
+  if (!isValidDivision(division)) return false;
+  const path = join(customRoot, "divisions.json");
+  const current = await loadCustomLabels(customRoot);
+  const text = String(label ?? "").trim();
+  if (text === "") delete current[division];
+  else current[division] = text;
+  await writeFileAtomic(path, `${JSON.stringify(current, null, 2)}\n`);
+  return true;
+}
+
+/** slug 是否合法（与扫描口径一致）。 */
+export function isValidSlug(slug) {
+  return SLUG_PATTERN.test(String(slug ?? ""));
+}
+
+/**
+ * 写 frontmatter 标量。常规值裸写；以引号/空白/特殊符号开头结尾时加引号。
+ * 两端都有半角引号的极端情况把 `"` 换成全角 `”`——保住结构，且没人会把这种名字当标识符用。
+ */
+function yamlScalar(value) {
+  const text = String(value ?? "").replace(/[\r\n]+/g, " ").trim();
+  if (text === "") return "";
+  if (!/^[\s"']|[\s"']$|^[#\-?:!,&*|>%@`[\]{}]/.test(text)) return text;
+  if (!text.includes('"')) return `"${text}"`;
+  if (!text.includes("'")) return `'${text}'`;
+  return `"${text.replace(/"/g, "”")}"`;
+}
+
+/** 把自建专家序列化成文件文本（frontmatter + persona 正文）。 */
+export function serializeCustomExpert(fields) {
+  const lines = ["---", `name: ${yamlScalar(fields.name)}`];
+  if (fields.nameEn) lines.push(`nameEn: ${yamlScalar(fields.nameEn)}`);
+  lines.push(`description: ${yamlScalar(fields.description)}`);
+  if (fields.descriptionEn) lines.push(`descriptionEn: ${yamlScalar(fields.descriptionEn)}`);
+  if (fields.emoji) lines.push(`emoji: ${yamlScalar(fields.emoji)}`);
+  lines.push("custom: true");
+  lines.push("---", "", String(fields.body ?? "").trim(), "");
+  return lines.join("\n");
+}
+
+/** 文件内容指纹（并发编辑用：两个窗口改同一位自建专家时，后写的会因指纹不符被拒）。 */
+export async function fileFingerprint(path) {
+  try {
+    return createHash("sha256").update(await readFile(path)).digest("hex").slice(0, 12);
+  } catch {
+    return "";
+  }
+}
+
+/** 原子写入：先写临时文件再 rename，避免面板读到半截文件。 */
+export async function writeFileAtomic(path, text) {
+  await mkdir(dirname(path), { recursive: true });
+  const temp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  await writeFile(temp, text, "utf8");
+  await rename(temp, path);
+}
+
+/** 删除自建专家文件；文件已不在时返回 false（幂等）。 */
+export async function removeCustomExpert(customRoot, slug, division = CUSTOM_DIVISION) {
+  const path = customExpertPath(customRoot, slug, division);
+  try {
+    await unlink(path);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
 /**
  * 去掉 emoji / 标点后的比较形式：面板与 @ 芯片里会带 emoji 与全角空格，
  * 模型也可能把「🗺️ 地理学家」原样传回来，所以比较前摘掉非文字字符。