dsh-plugin-t-expert 0.2.7 → 0.2.10

package/skills/dsh-harness-project/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: dsh-harness-project
+description: Use when working in the deepseek-harness repository — the all-plugin Cordis agent harness — and you need the architecture, package map, profile/bundle boot model, extension points, repository conventions, quality gates, or the answer to "where does this change belong?". Load before writing, reviewing, or explaining code in this repo.
+---
+
+# DeepSeek Harness：项目知识
+
+本仓库 = **DeepSeek Harness（dsh）**：一个以 [Cordis](docs/cordis-primer.md) 为底座的「全插件」Agent Harness。版本 `0.1.5-rc.2`，MIT，pnpm workspace monorepo，发布包统一为 `@deepseek-ai/dsh-<name>`。
+
+**没有特权内核可打补丁。** 模型适配器、工具注册表、会话日志、甚至 agent loop 本身都是插件；扩展方式是「在旁边挂一个插件」，而不是修改核心。所有注册都是 effect，插件卸载时自动回滚。
+
+## 先读什么（权威顺序）
+
+1. [AGENTS.md](AGENTS.md) — 常驻规约（root）与 [packages/AGENTS.md](packages/AGENTS.md) — 包级规约。
+2. [docs/architecture.md](docs/architecture.md) — 改动 `packages/` 前必读：组合、核心包、loop、seam、扩展点。
+3. [docs/glossary.md](docs/glossary.md) — 一个概念一个权威术语（seam / scope / turn / step / round / goal / human command）。
+4. [packages/README.md](packages/README.md) — 包组地图；再进目标组的 README，最后进具体包的 README。
+5. `docs/subsystems/<subsystem>.md` — 类型定义、语义、生成的 Cordis API。
+6. `.agents/notes/` — 决策依据（active 决策记录；`archived/` 是冻结历史，**不是**当前权威）。
+
+冲突时以代码为准：文档与代码不符是文档缺陷，应报告而不是照抄。
+
+## 仓库布局
+
+| 路径 | 内容 |
+|---|---|
+| `vendor/` | Cordis 及其基础库的源码内联副本（重命名进 `@deepseek-ai` scope，见 [vendor/README.md](vendor/README.md)）。改它要走 vendor 同步流程。 |
+| `packages/<group>/<pkg>/` | 全部 npm workspace 包，按能力族分组（见下）。 |
+| `apps/` | `cli`（`dsh` 可执行入口）、`web`（Vite 前端产物）、`desktop`（Electron）、`desktop-host`。 |
+| `python/` | Python SDK（`sdk/`）与运行时载体（`sdk-runtime/`）。 |
+| `native/` | `@deepseek-ai/node-addon-system`：Linux Landlock launcher + POSIX flock，Node-API 预编译。 |
+| `docs/` | 架构、子系统、生成的参考目录、cookbook、user 指南、i18n。 |
+| `.agents/` | `notes/`（Agent Notes）与 `skills/`（仓库级 skill）。 |
+| `scripts/` | 生成器与质量门禁（`run-gates.ts` 是聚合入口）。 |
+| `snapshots/`、`benchmarks/` | 录制会话快照与性能门禁。 |
+| `website/` | docs/ 的 VitePress 投影。 |
+
+包组：`core/`（session、system-prompt、tools、agent、agent-loop、scope）、`llm/`、`subagent/`、`shell/`、`fs/`、`sandbox/`、`session/`、`session-query/`、`storage/`、`settings/`、`credentials/`、`interaction/`、`client/`（`ui-*`）、`host/`、`api/`、`typert/`、`preset/`、`bundle/`、`skill/`、`workflow/`、`webhook/`、`guard/`、`extensions/`、`util/` 等 —— 完整表见 [packages/README.md](packages/README.md)，不要在这里复述第二份清单。
+
+## 三个平面（改动落点判断的第一步）
+
+| 平面 | 拥有什么 | 判据 |
+|---|---|---|
+| **Host composition** | 注册表本体（tools/skills/subagents 注册表）、持久化、sandbox 与审批栈、模型路由、跨会话共享的服务 | 一个在 session 存在之前就完成注入的 host row；或 browser/其他 session 也要读的服务 |
+| **Agent preset**（`agent.cordis.yml`） | 单个 session 往那些注册表里**贡献**什么：工具、prompt section、persona、skill | 每 session 可不同；发布服务时**必须**待在带 `isolate` realm 的 group 里 |
+| **Session** | 该 session 自己的状态（日志、goal、plan、todo） | 按 Session/Agent 分键的状态 |
+
+- preset 里发布服务却不带 `isolate` realm → 落进 root realm 变成进程全局，`dsh-agent-presets` 在 mount 时直接拒绝。
+- `isolate: true` = entry-local realm（本次挂载私有）；**同名 label 不会共享实例**，label 连接的是 realm。
+- 用户自建 preset 放在 `${DSH_HOME:-$HOME/.dsh}/.agent-presets/<id>/`。**永远不要改内置 preset 安装目录**（升级会覆盖）。
+
+## 启动模型：profile / bundle / patch
+
+运行中的 `dsh` 是启动时按顺序分层组合出来的插件树。
+
+- **profile**：Harness home 里的具名组合，列出它叠加的 bundle、树外插件和用户自己的 `cordis.patch.yml`。内置模板：`web`、`headless`、`sdk`、`sdk-minimal`、`acp`。
+- **bundle**：Cordis config 行 + 其挂载代码的分发格式；在自身 `package.json` 的 `dsh.bundle` 指向 patch 文件，profile 用 `dsh.profile` 列 bundle。
+- **分层顺序**（从空 entry 列表开始）：profile 里各 bundle 的列出顺序 → profile 的 `cordis.patch.yml` → home 级 patch → `--patch` overlay。
+- patch 按 **row id** 定位：替换整条 config，或插入新行。
+- 覆盖 `web` profile 默认是 live reload；`headless`/`sdk`/`sdk-minimal`/`acp` 只在启动时应用一次（一次性或 stdio 应用在已拥有工作后替换依赖会破坏生命周期）。
+
+```sh
+dsh --profile web --dump-config   # 看本机实际启动的树；打印出的任何一行都能被 patch 替换
+```
+
+**应用启动只有一条路**：`dsh` CLI + 具名 profile（`dsh web` 是 `--profile web` 的别名）。package bin、demo、public SDK argv 直接拼 Cordis 树都是禁止的，`scripts/verify-application-entrypoints.ts` 会拒绝。
+
+## 核心包（spine）
+
+| 包 | 拥有 | ctx key |
+|---|---|---|
+| `core/session` | append-only `SessionEvent` 日志与内存存储 | `ctx.sessions` |
+| `core/system-prompt` | prompt section 与 tool schema 组装 | `ctx.systemPrompt` |
+| `core/tools` | 按 scope 的工具注册表 + 受控执行管线 | `ctx.tools` |
+| `core/agent` | `Agent` 接口、活体注册表、`agent/*` 事件 | `ctx.agents` |
+| `core/agent-loop` | 默认 driver（可替换） | `ctx.agentLoop` |
+| `core/scope` | 按 agent 的 scoped 注册原语 | 无 key |
+| `llm/llm` | 消息/流词汇 + adapter seam | `ctx.llm` |
+
+## turn / step 与三类事件
+
+- **step** = 一次模型请求 + 它触发的工具调用；**turn** = 零或多个 step。
+- 事件分三个域，选对域是大多数改动的第一个决定：
+  - **Session events**：追加进日志的持久事实（`turn/*`、`step/*`、`user/message`、`assistant/message`、`assistant/attempt`、`tool/*`、`system/message`）。要求 reload 后仍在，就用它。
+  - **Agent events**（`agent/*`）：携带活体 `Agent`（inbox、step、status、request、validation、continuation）。观察或拦截进行中的工作用它。
+  - **Capability events**（`fs/*`、`tools/*`、`telemetry/*`）：给 seam 挂策略和适配器，不必 import loop。
+- **waterfall 监听器必须调用 `next()`** 才算委派；不调用就是短路整条链。`agent/pre-step`、`agent/request`、`llm/stream`、三个 `tools/*` 是 waterfall；`agent/turn-stopping` 是串行、没有 `next()`。
+
+## 能力 seam
+
+**seam = 可替换能力，三角色齐全**：Service Definition（拥有 `ctx.<key>` 和词汇类型的 Cordis `Service` —— 抽象类如 `ShellExecutor`，或具体注册表如 `WebRuntime`，**绝不是 TS `interface`**）、一个或多个 Service Provider、一个或多个 Consumer（通常是模型可见工具）。`packages/shell` 是范例：`dsh-shell` + `dsh-bash-local`/`dsh-bash-sandbox` + `dsh-tool-bash`。
+
+- 只做一个角色不叫 seam。角色独立演化时才分包。
+- **扩展插件依赖 Service Definition，绝不依赖具体 Provider**。
+- 设计 Service Definition 要对齐所有当前 Consumer；让某一个 Consumer 决定 service 契约是反向坏味道。
+
+## 新行为放哪里
+
+| 目标 | 机制 |
+|---|---|
+| 加模型 provider | 在 `ctx.llm` 注册 adapter |
+| 加模型可见能力 | 注册到 `ctx.tools`，schema 进入 prompt 组装 |
+| 让某个 session 有不同能力集 | 组一个 agent preset（行内服务需 `isolate` realm） |
+| 加 shell 执行 | 注册 `ctx.shell` backend |
+| 加持久终端 | 注册 `ctx.terminals` backend + `dsh-tool-terminal` |
+| 加人类命令（斜杠） | 注册 `ctx.commands`，不产生模型 turn |
+| 加后台工作 | 注册 `ctx.jobs` |
+| 外部 webhook 起 Session | 在 `ctx.webhookRuntime` 注册可信规则 + provider adapter |
+| 文件系统访问或策略 | 注册 `ctx.fs` provider 或监听 `fs/*` |
+| 限制子进程 | 用 `ctx.sandbox` backend |
+| 拦截请求/工具/turn | 用对应 `agent/*` 或 `tools/*` 事件 |
+| 加模型可见上下文 | `agent.inject()`，在下一次被接受的请求中落地 |
+| 加 UI 或编辑器集成 | 驱动 `ctx.agents`，从 `session/event` 渲染 |
+| 加 Web Client Chat 节点 | 注册 `ConversationNodeDefinition` + keyed renderer |
+| 加持久 session 状态 | 扩展 `SessionEventMap`，从日志渲染与回放 |
+| 把注册限定到某个 agent | 用该 agent 的 `agent.ctx` |
+
+分步指南在 [docs/cookbook/](docs/cookbook/extension-cookbook.md)：加包、加工具、加 LLM adapter、加设置卡片、加 session 格式版本。
+
+## 会被拒绝的约定（改动前自查）
+
+- **注册即 effect**：一切贡献走 `ctx.effect()` / `ctx.on()`；注册表 `register()` 返回 disposer；每个注册表都要有 HMR 安全测试（dispose fiber，断言清理）。
+- **Model-visible ⟺ logged**：任何进入模型请求的东西都必须能从 session 日志重建（有运行时 invariant 断言）。新增模型可见输入 = 新增 session event + 从日志渲染。
+- **插件，不是改 loop**：新行为挂到已文档化的扩展点；改 `agent-loop` 必须同步更新 `docs/architecture.md`。
+- **不硬编码可调项**：随部署变化的取值是受校验的 `Config` 字段（可从 cordis.yml 改）。`DEFAULT_*` 常量或测试钩子不算可配置性。协议常量、外部规范、安全不变量保持固定。
+- **显式 > 隐式（包边界）**：默认值解析是拥有方实现里显式的一步 `resolve(request): Spec`，不是 `run()` 里藏的 `?? default`。
+- **跨边界的不透明 id 要 brand**（`Branded<B>`，来自 `dsh-brand`），不能是裸 `string`。
+- **类型化边界信任 TypeScript**：不要为静态接口已保证的输入加运行时校验/兜底/敌意输入测试；只在 parser/config、排队、模型/工具 JSON、持久化/文件、worker、进程、wire 边界校验。
+- **源码面 vs 产物面，永不混用**：静态门禁与测试通过 tsconfig `paths` 解析到 `src`，在干净树上通过；消费 `lib/` 的门禁必须显式声明该依赖。
+- **失败要响**：自包含的错误在加载时失败，否则在最早已可解析点失败，绝不静默跳过缺失的引用。
+- **switch 判别式 tag**：封闭联合以 `assertNever` 收尾；可合并扩展的联合走有文档的 default 分支。
+- **测试描述行为而非正确性**：行为过时就连同测试一起改，并在 PR 里说明原因。
+- **非平凡改动必须在同一个 PR 里带一篇 Agent Note**（仅机械/局部编辑豁免）。归档 note 冻结，不得编辑或当作当前权威。
+- **客户端 UI 文案归 locale 所有**：产品文案走类型化字典 + `t`/本地化 props，`verify-client-ui-i18n` 会拒绝硬编码文案。
+- **空 `catch` 要写明吞掉什么**、为什么别的到不了；`try` 只包一条语句。
+- 文件以恰好一个换行结尾（pre-commit 的 `git diff --cached --check` 把关）。
+
+## 命令
+
+```sh
+pnpm install              # pnpm workspace；Node ^22.19 || >=24，pnpm 11.7.0
+pnpm run typecheck        # 先跑完 Host lib 阶段，再 tsc Client
+pnpm run lint             # oxlint（先 build:lib:host）
+pnpm run test             # vitest 单测
+pnpm run test:coverage    # CI 覆盖率门禁：packages/*/*/src 逐文件 100%
+pnpm run test:e2e         # 真 API 测试；无 DEEPSEEK_API_KEY 自行跳过
+pnpm run test:expected    # owner 本地进程期望输出
+pnpm run test:snapshot    # 无密钥录制会话回放（-t <name> 过滤）
+pnpm run test:web         # 浏览器快照（先 build）
+pnpm run build            # tsc 产出 lib/types，tsdown 打包 runtime
+pnpm run hygiene          # publint + workspace/包/依赖检查 + NodeNext 消费者检查
+pnpm run doc-sync         # 全量文档门禁
+pnpm run test:docs        # 快速文档检查（doc-quick）
+pnpm run check:all        # 聚合门禁
+pnpm run duplication      # 跨文件 TS 克隆检测（jscpd）
+pnpm dsh --profile headless "task"   # 从源码跑一次真实任务（需 key）
+```
+
+改了代码之后选**覆盖该改动面**的最小检查，不要反射性地跑全量：行为测试、model/user 输出快照、文档用 `doc-sync`、发布路径用 built smoke、provider 用真 API e2e。CI 负责穷尽覆盖与平台矩阵。
+
+## 测试分级与「什么时候必须有快照」
+
+- **Unit**（`pnpm run test`）：vitest，spec 与被测代码同区；每个注册表要有 HMR 安全测试；偏好边界、错误路径、事件顺序、并发竞争、契约回归的永久测试。
+- **覆盖率门禁**（`test:coverage`）：逐文件 100%。未覆盖的行往往是该删的死代码，而不是该补的测试。行覆盖必要但绝不充分。
+- **真 API e2e**（`test:e2e`）：无 key 自跳；**不要省真 API 测试**——无 key 只证明管道通，有 key 才证明 agent 能用。最高价值是启动 shipped profile 的 smoke。
+- **快照**（`test:snapshot`）：顶层 scenario 的最高父代 generation 提供用户输入与模型回放，并作为期望的持久结果。改模型 transcript 用 `test:snapshot:record`，输入仍有效用 `refresh`。
+- **Web 浏览器快照**（`test:web`）：Chromium 比对 `snapshots/web/`；CI 强制 `DSH_SNAPSHOT=replay` 只读。
+- **任何非平凡、模型/协议/用户可见的改动，都要在同一个 PR 里新增或更新一个无密钥录制会话 scenario。** 包测试、e2e、mock-only 证据都不能替代组装后的 transcript。
+- agent-loop / session 生命周期 / `SessionEventMap` 改动要同步更新 **TypeScript 与 Python 两套 SDK 期望输出**。
+- **优先真实现，少用 mock**：只 mock 昂贵或不确定的边界（LLM adapter、网络、时钟），下游全部保持真实。
+- **验证世界，不验证自述**：e2e 断言要重新执行命令或重新读文件；对 agent 自身输出的关键字探测会让作弊的 agent 通过。
+- **测试真入口路径**：产品可见插件必须有非 unit 的 REAL 组合测试（通过 Loader 与 app/process 启动测试专用 `cordis.yml`）。
+- spec 在 fork worker 里并发执行：端口、路径、子进程都要自己负责到 teardown；「单独跑才过」的 spec 是 spec 的缺陷。
+
+## 文档分层（一个事实只有一个家）
+
+| 层 | 职责 |
+|---|---|
+| root `AGENTS.md` | 常驻命令：每个 session 都要在上下文里的规则，每条 1-3 行并链到它的家 |
+| 子树 `AGENTS.md` | 该子树特有规则 |
+| `docs/architecture.md` | 有序地图：组合、核心包、loop、seam、扩展点 |
+| `docs/subsystems/` | 每子系统一页参考：类型定义、语义、生成的 Cordis API |
+| `.agents/notes/` | 决策记录：为什么、放弃了什么、需要什么验证 |
+| `docs/postmortem/` | 事故叙事（唯一允许 war story 的层） |
+| `docs/cookbook/` | 带编号验证步骤的 how-to |
+| 包 README | 该包的契约：配置、语义、限制、扩展点、Model Experience |
+| 生成参考（subsystems 的 `cordis-surface` 区、cordis-api、tool-catalog、config-catalog、persistence-catalog、module-graph） | 从源码生成、有新鲜度门禁；**不要手改** |
+| `.agents/skills/` | 可复用工作流与专业判断标准 |
+
+放置规则：bug → postmortem；why → Agent Note；how-to → cookbook；类型 → subsystems；包契约 → README；常驻规则 → root `AGENTS.md` + 依据链接。
+
+写作规则：**只写当前状态，不写变更史**（不出现 previously/now/no longer/PR 编号）；**每段一个物理行**（`verify-md-wrap`）；`ts` 代码块必须能编译（`doc-typecheck`）；改了被文档化的类型，同一改动里更新 owning subsystems 页面；跨引用用相对 Markdown 路径，`verify-md-links` 会拒绝死链；JSDoc 写完整契约，不写推理过程。
+
+## 怎么找「谁拥有 X」
+
+1. `grep` 服务 key（`ctx.<name>`）→ 命中 `Service` 声明所在包 = 拥有方。
+2. `docs/subsystems/` 里找同名端点 → 拿到类型与语义。
+3. `.agents/notes/` 里搜关键词 → 拿到为什么这么设计、放弃了什么。
+4. `packages/<group>/README.md` → 确认它属于哪个能力族、同族还有谁。
+
+## 常见坑
+
+- 把 `interface` 当成 Service Definition（seam 的 Service Definition 必须是 Cordis `Service`）。
+- 在扩展插件里直接依赖具体 Provider，而不是 Service Definition。
+- waterfall 监听器忘记 `next()`，静默短路后续策略。
+- 让一个新的模型可见输入绕过 session event —— 破坏「可重建」不变量。
+- 在 preset 里裸发布服务（缺 `isolate` realm），mount 时被拒。
+- 改行为却不同步包 README / JSDoc / Agent Note / 快照。
+- 直接改 `vendor/` 或生成参考文档（手改会被门禁打回）。

package/skills/t-expert-manager/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: t-expert-manager
-description: T专家 运维台 —— 315 位专家 / 22 分区的名册增删、名册一致性校验、统计与中文覆盖、小队（/t）成员编辑、装机到 DSH Desktop、发布到 npm。Use when the user asks to add/remove/validate/count T专家 experts, 新增专家 / 删除专家 / 校验名册 / 名册统计 / 改小队 / 重装插件 / 发布插件.
+description: T专家 运维台 —— 316 位专家 / 22 分区的名册增删、名册一致性校验、统计与中文覆盖、小队（/t）成员编辑、装机到 DSH Desktop、发布到 npm。Use when the user asks to add/remove/validate/count T专家 experts, 新增专家 / 删除专家 / 校验名册 / 名册统计 / 改小队 / 重装插件 / 发布插件.
 ---
 
 # T专家 运维（expert-manager）
@@ -16,11 +16,18 @@ description: T专家 运维台 —— 315 位专家 / 22 分区的名册增删
    这些动作脚本都代劳了，绕开脚本换来的就是"源码加了、运行时没加"这类半成品状态。
 2. **`data/experts/` 是真源**。增删由 `add-expert.py`（tz.sh 代跑）执行，它**同时写**源码与运行时
    `~/.t-team/experts/`，两边永远一致。
-3. **统计必须递归**。有 15 位专家落在嵌套子目录（如 `game-development/unreal-engine/…`），
-   只数顶层目录会得到 299 而不是 315。
+3. **统计必须递归**。有专家落在嵌套子目录（如 `game-development/unreal-engine/…`），
+   只看分类目录的第一层会漏掉它们。位数一律以 `tz.sh status` 的递归结果为准 ——
+   正文里不写死位数，因为每加一位专家它就会过期。
 4. **数据更新不用重装、不用重启**（宿主按 mtime 指纹自动重载名册）；**改插件代码**才需要
    `tz.sh build` → `tz.sh install` → 重启 DSH Desktop。
-5. **小队改完必须 `tz.sh squads` + 重启 DSH Desktop** 才对建队生效。
+5. **小队改完分两条路，只有设置页那条会热重载**：
+   - **设置页「队伍」保存**（推荐）：`squads.save()` 编译成功后**就地热重载引擎配置 → 立即生效、不用重启**。
+   - **`tz.sh squads`（= 菜单 11）**：只是 CLI 直跑编译器（`python3 data/team-profiles.py`）把 `teams.json`
+     编译成引擎配置，**不经过插件、不会热重载**——运行中的引擎仍用旧 profiles，**必须重启 DSH**
+     （或再到设置页保存一次）才生效。所以别对用户说「跑完 tz.sh squads 就已经生效」。
+   两条路的失败语义一致：编译失败会**回滚**，盘上仍是旧配置（按旧小队建队）。
+   只有**改插件代码**才需要重启（见第 4 条）。
 6. **`data/zh/` 已冻结**：不要新增或"补译"中文。新专家没有中文名/简介会回退英文，这是预期行为。
 7. **破坏性动作先确认**：删除专家、卸载插件、发布 npm 之前，把影响讲给用户听，得到明确同意再执行。
 
@@ -77,7 +84,10 @@ bash "{{TZ}}" experts stats
    ```bash
    bash "{{TZ}}" squads
    ```
-3. 明确告诉用户：**重启 DSH Desktop 后生效**，之后用 `/t <小队> <目标>`。
+3. 明确告诉用户：**`tz.sh squads` 只是 CLI 直跑编译器**——它把 `teams.json` 编译成引擎配置，
+   **不会让运行中的插件重载**。所以：**要让新小队真正生效，需重启 DSH Desktop**（或再到设置页「队伍」保存一次，
+   那条路才会就地热重载、立即生效）。若 `/t` 里仍看不到新小队，先确认编译没报错（编译失败会回滚，盘上仍是旧配置）。
+4. 想免重启就直接走设置页：设置 → T专家 → 队伍 → 改完保存（`squads.save()` 编译成功后触发引擎热重载，立即生效）。
 
 ### F. 装机（只在改过插件代码时需要）
 

package/skills/t-expert-manager/references/ops-reference.md

@@ -14,7 +14,7 @@
 | `tz.sh experts check` | 名册一致性（源码 ↔ 运行时 ↔ 清单） | 退出码 1 = 漂移 |
 | `tz.sh roster` | 同 `experts stats` | |
 | `tz.sh verify` | `experts check` + `verify.mjs` 插件自检 | 改代码后必跑 |
-| `tz.sh squads` | 刷新小队配置（`teams.json` → 引擎 profiles） | 需重启 DSH Desktop |
+| `tz.sh squads` | 刷新小队配置（`teams.json` → 引擎 profiles，= 菜单 11） | **CLI 直跑编译器，不触发热重载**：运行中的引擎仍用旧 profiles → 需重启 DSH Desktop（或改走设置页保存） |
 | `tz.sh build` | 构建 client bundle | `npm run build` |
 | `tz.sh install` | 安装/重装到 profile | 见参数；`--dry-run` 预演 |
 | `tz.sh uninstall` | 卸载（保留 `experts/` 与 `zh/`） | |
@@ -72,7 +72,7 @@ tz.sh publish-dry | publish [--patch|--minor|--major|--version X.Y.Z] [--retry]
 
 | 内容 | 真源 | 说明 |
 | --- | --- | --- |
-| 专家名册 | `<ops>/dsh-plugin-t-expert/data/experts/` | 22 分类 / 315 位；运行时是它的同步副本 |
+| 专家名册 | `<ops>/dsh-plugin-t-expert/data/experts/` | 22 分类 / 316 位；运行时是它的同步副本 |
 | 中文侧车 | `<ops>/dsh-plugin-t-expert/data/zh/` | **已冻结**，只读不写 |
 | 小队定义 | 数据目录 `teams.json` | 人工维护；`data/` 与 `~/.t-team/` 同一份（软链） |
 | 小队编译产物 | 数据目录 `t-team.config.json` | 由 `team-profiles.py` 生成，**不要手改** |
@@ -92,9 +92,9 @@ tz.sh publish-dry | publish [--patch|--minor|--major|--version X.Y.Z] [--retry]
 
 | 现象 | 原因 / 处理 |
 | --- | --- |
-| 名册少了几位（299 vs 315） | 只数了顶层目录 —— 必须递归 |
+| 名册少了几位 | 只数了分类目录的第一层（嵌套子目录里的专家被漏掉）—— 必须递归，以 `tz.sh status` 为准 |
 | `experts check` 报"运行时缺/多出" | 绕开脚本手工拷贝过文件；用 `experts add` 重做那一条 |
 | 新增专家后面板看不到 | 面板按 mtime 指纹自动重载；仍看不到就查该专家是否被**启用**（设置页 T专家 标签，默认全禁用） |
-| 改了小队但 `/t` 里没有 | 没跑 `tz.sh squads`，或没重启 DSH Desktop |
+| 改了小队但 `/t` 里没生效 | 先看编译报错（失败会回滚，盘上仍是旧配置）；若编译成功却是走 `tz.sh squads` 的，**运行中的引擎不会热重载 → 需重启 DSH Desktop**，或改走设置页「队伍」保存（那条立即生效） |
 | 装了新版本但没变化 | 只跑了 `build` 没跑 `install`，或没重启 |
 | `找不到插件仓库` | 设 `T_TEAM_REPO`，或用 `--repo` 指定 |

package/vendor/third-party-licenses/README.md

@@ -5,7 +5,7 @@
 
 | 文件 | 覆盖的随包内容 | 来源 |
 | --- | --- | --- |
-| `agency-agents.LICENSE` | `data/experts/`（22 分区 / 315 位；其中 314 位来自第三方 —— 279 位为上游仓库逐字节镜像、35 位来自名册来源包快照；余 1 位为本仓自建，不由本许可覆盖） | The Agency / AgentLand 名册快照，MIT |
+| `agency-agents.LICENSE` | `data/experts/`（22 分区 / 316 位；其中 315 位来自第三方 —— 279 位为上游仓库逐字节镜像、35 位来自名册来源包快照；余 2 位为本仓自建，不由本许可覆盖） | The Agency / AgentLand 名册快照，MIT |
 | `agency-agents-zh.LICENSE` | `data/zh/` 中的中文名字、简介与人格正文 | `agency-agents-zh` 中文翻译与本地化资产，MIT |
 
 两份文本都是从实际用于生成快照的来源包内**逐字节复制**的，未经改写：