dominds 1.18.2 → 1.19.3

package/dist/tools/prompts/mcp_admin/zh/tools.md

@@ -21,7 +21,7 @@
 
 ### 1. mcp_restart
 
-重启 MCP 服务。
+按当前 `.minds/mcp.yaml` 配置启用并重建 MCP 服务。如果目标 server 当前是 `enabled: false`，会先写回 `enabled: true` 再尝试启动。重启成功后会替换全局 MCP runtime/tool 注册，并清理旧 runtime 上所有对话持有的 lease；重启失败时保留旧 runtime/lease，避免排障过程中把仍可用的连接拆掉。
 
 **参数：**
 
@@ -30,9 +30,7 @@
 **返回：**
 
 ```yaml
-status: ok|error
-serverId: <MCP 服务标识符>
-restarted_at: <重启时间戳>
+ok: restarted <MCP 服务标识符>
 ```
 
 **错误：**
@@ -50,9 +48,13 @@ restarted_at: <重启时间戳>
 **返回：**
 
 ```yaml
-status: ok|error
-serverId: <MCP 服务标识符>
-released_at: <释放时间戳>
+ok: released <MCP 服务标识符> for dialog <对话标识符>
+```
+
+如果当前对话没有可释放的 lease，返回：
+
+```yaml
+ok: no active lease for <MCP 服务标识符> (or server is truely-stateless)
 ```
 
 **错误：**
@@ -60,7 +62,21 @@ released_at: <释放时间戳>
 - `MCP_NOT_FOUND`：MCP 服务不存在
 - `MCP_NOT_RUNNING`：MCP 服务未运行
 
-### 3. env_get
+### 3. mcp_disable
+
+禁用 MCP 服务并将 `.minds/mcp.yaml` 中对应 server 写为 `enabled: false`。该操作不等待新服务可用：会无条件清理已加载 runtime/lease。禁用后的 server 仍作为 0 工具 MCP toolset 可见，并在手册中明确标记为 disabled。
+
+**参数：**
+
+- `serverId`（必需）：MCP 服务标识符
+
+**返回：**
+
+```yaml
+ok: disabled <MCP 服务标识符> and set enabled=false
+```
+
+### 4. env_get
 
 获取环境变量（与 os 工具集共享）。
 
@@ -70,16 +86,41 @@ released_at: <释放时间戳>
 
 **返回：**
 
+- 已设置：直接返回环境变量值
+- 未设置：返回 `(unset)`
+
+### 5. env_set
+
+设置 Dominds 服务进程的环境变量（与 os 工具集共享）。
+
+**参数：**
+
+- `key`（必需）：环境变量名称
+- `value`（必需）：环境变量值
+
+**返回：**
+
 ```yaml
-status: ok|error
-key: <环境变量名称>
-value: <环境变量值>
-retrieved_at: <获取时间戳>
+ok: <环境变量名称>
+prev: <之前的值或 (unset)>
+next: <新的值>
 ```
 
-**错误：**
+### 6. env_unset
 
-- `ENV_NOT_FOUND`：环境变量不存在
+删除 Dominds 服务进程的环境变量（与 os 工具集共享）。
+
+**参数：**
+
+- `key`（必需）：环境变量名称
+
+**返回：**
+
+```yaml
+ok: <环境变量名称>
+prev: <之前的值或 (unset)>
+next: (unset)
+```
 
 ## 使用示例
 
@@ -99,6 +140,14 @@ mcp_release({
 });
 ```
 
+### 禁用 MCP 服务
+
+```typescript
+mcp_disable({
+  serverId: 'browser',
+});
+```
+
 ### 获取环境变量
 
 ```typescript
@@ -107,17 +156,32 @@ env_get({
 });
 ```
 
-## YAML 输出契约
+### 设置环境变量
+
+```typescript
+env_set({
+  key: 'MCP_AUTH_TOKEN',
+  value: 'local-token',
+});
+```
+
+### 删除环境变量
+
+```typescript
+env_unset({
+  key: 'MCP_AUTH_TOKEN',
+});
+```
+
+## 输出契约
 
-所有工具的输出都使用 YAML 格式，便于程序化处理：
+这些工具使用各自工具小节描述的简短文本返回格式：
 
-- `status`：操作状态，`ok` 表示成功，`error` 表示失败
-- 其他字段：具体操作的附加信息
+- 成功：以 `ok:` 开头
+- 失败：以 `error:` 开头
 
 错误时返回：
 
 ```yaml
-status: error
-error_code: <错误代码>
-message: <错误消息>
+error: <错误消息>
 ```

package/dist/tools/prompts/os/en/errors.md

@@ -56,34 +56,6 @@
 - Restart daemon process
 - Check daemon process logs
 
-### ENV_NOT_FOUND
-
-**Description:** Environment variable doesn't exist.
-
-**Cause:**
-
-- Environment variable not set
-- Environment variable has been deleted
-
-**Solution:**
-
-- Use `env_set` to set environment variable
-- Check if environment variable name is correct
-
-### ENV_PERMISSION_DENIED
-
-**Description:** Insufficient permissions for environment variable operation.
-
-**Cause:**
-
-- Some environment variables require root permissions
-- System-protected environment variables
-
-**Solution:**
-
-- Use sudo to elevate permissions
-- Avoid modifying system-protected environment variables
-
 ## Frequently Asked Questions
 
 ### Q: What security risks does shell command execution have?

package/dist/tools/prompts/os/en/scenarios.md

@@ -90,7 +90,7 @@ Manage environment variables.
 ### Example
 
 ```typescript
-// View all environment variables
+// View one environment variable
 env_get({
   key: 'PATH',
 });

package/dist/tools/prompts/os/en/tools.md

@@ -90,16 +90,8 @@ Get environment variable.
 
 **Returns:**
 
-```yaml
-status: ok|error
-key: <environment variable name>
-value: <environment variable value>
-retrieved_at: <retrieval timestamp>
-```
-
-**Errors:**
-
-- `ENV_NOT_FOUND`: Environment variable doesn't exist
+- Set: returns the environment variable value directly
+- Unset: returns `(unset)`
 
 ### 5. env_set
 
@@ -113,10 +105,9 @@ Set environment variable.
 **Returns:**
 
 ```yaml
-status: ok|error
-key: <environment variable name>
-value: <environment variable value>
-set_at: <set timestamp>
+ok: <environment variable name>
+prev: <previous value or (unset)>
+next: <new value>
 ```
 
 ### 6. env_unset
@@ -130,9 +121,9 @@ Delete environment variable.
 **Returns:**
 
 ```yaml
-status: ok|error
-key: <environment variable name>
-unset_at: <deletion timestamp>
+ok: <environment variable name>
+prev: <previous value or (unset)>
+next: (unset)
 ```
 
 ## Usage Examples

package/dist/tools/prompts/os/zh/errors.md

@@ -56,34 +56,6 @@
 - 重新启动守护进程
 - 检查守护进程日志
 
-### ENV_NOT_FOUND
-
-**描述：** 环境变量不存在。
-
-**原因：**
-
-- 环境变量未被设置
-- 环境变量已被删除
-
-**解决方案：**
-
-- 使用 `env_set` 设置环境变量
-- 检查环境变量名称是否正确
-
-### ENV_PERMISSION_DENIED
-
-**描述：** 环境变量操作权限不足。
-
-**原因：**
-
-- 某些环境变量需要 root 权限
-- 系统保护的环境变量
-
-**解决方案：**
-
-- 使用 sudo 提升权限
-- 避免修改系统保护的环境变量
-
 ## 常见问题
 
 ### Q: Shell 命令执行有什么安全风险？

package/dist/tools/prompts/os/zh/scenarios.md

@@ -90,7 +90,7 @@ shell_cmd({
 ### 示例
 
 ```typescript
-// 查看所有环境变量
+// 查看单个环境变量
 env_get({
   key: 'PATH',
 });

package/dist/tools/prompts/os/zh/tools.md

@@ -90,16 +90,8 @@ stderr: <请求时返回 stderr 输出>
 
 **返回：**
 
-```yaml
-status: ok|error
-key: <环境变量名称>
-value: <环境变量值>
-retrieved_at: <获取时间戳>
-```
-
-**错误：**
-
-- `ENV_NOT_FOUND`：环境变量不存在
+- 已设置：直接返回环境变量值
+- 未设置：返回 `(unset)`
 
 ### 5. env_set
 
@@ -113,10 +105,9 @@ retrieved_at: <获取时间戳>
 **返回：**
 
 ```yaml
-status: ok|error
-key: <环境变量名称>
-value: <环境变量值>
-set_at: <设置时间戳>
+ok: <环境变量名称>
+prev: <之前的值或 (unset)>
+next: <新的值>
 ```
 
 ### 6. env_unset
@@ -130,9 +121,9 @@ set_at: <设置时间戳>
 **返回：**
 
 ```yaml
-status: ok|error
-key: <环境变量名称>
-unset_at: <删除时间戳>
+ok: <环境变量名称>
+prev: <之前的值或 (unset)>
+next: (unset)
 ```
 
 ## 使用示例

package/dist/tools/prompts/team_memory/en/scenarios.md

@@ -103,7 +103,7 @@ Maintain shared terminology and standard wording across the team.
 add_team_memory({
   path: 'team/glossary/dialog-terms',
   content:
-    '## Dialog Terms\n\n- In user-facing copy, prefer: Mainline dialog / Sideline dialog\n- In implementation context, main dialog / subdialog / supdialog are acceptable\n- Do not surface implementation terms directly into user-facing copy',
+    '## Dialog Terms\n\n- In user-facing copy, prefer: Main Dialog / Side Dialog\n- In implementation context, main dialog / sideDialog / askerDialog are acceptable\n- Do not surface implementation terms directly into user-facing copy',
 });
 ```
 

package/dist/tools/prompts/team_memory/zh/scenarios.md

@@ -103,7 +103,7 @@ add_team_memory({
 add_team_memory({
   path: 'team/glossary/dialog-terms',
   content:
-    '## 对话术语\n\n- 用户面向文案优先使用：主线对话 / 支线对话\n- 实现上下文可使用：main dialog / subdialog / supdialog\n- 不要把实现术语直接裸露到用户可见 copy',
+    '## 对话术语\n\n- 用户面向文案优先使用：主线对话 / 支线对话\n- 实现上下文可使用：main dialog / sideDialog / askerDialog\n- 不要把实现术语直接裸露到用户可见 copy',
 });
 ```
 

package/dist/tools/registry.d.ts

@@ -28,6 +28,11 @@ export type ToolsetMeta = {
      * When omitted, `man` falls back to deriving topic files from `promptFilesI18n`.
      */
     manualSpec?: ManualSpec;
+    /**
+     * Optional notice prepended by the generic `man` tool. Runtime-generated toolsets
+     * use this to surface operational state without hiding their configured manual.
+     */
+    manualNoticeI18n?: I18nText;
 };
 export declare const toolsetMetaRegistry: Map<string, ToolsetMeta>;
 export declare const reminderOwnersRegistry: Map<string, ReminderOwner>;

package/dist/tools/team_mgmt-manual.js

@@ -114,7 +114,7 @@ async function renderTeamMgmtGuideContent(language, topicsRaw = []) {
                     '`model_param_options` 可选：用于记录该 provider 支持的 `.minds/team.yaml model_params` 选项（文档用途）。',
                     '`apiQuirks` 可选：写在 `providers.<providerKey>.apiQuirks`，类型是 `string|string[]`。它是 provider 级 transport / 网关兼容开关，用来描述“这个供应商/网关的 API 有非标准行为”，不是 `.minds/team.yaml` 的成员参数，也不是 `model_params`。',
                     '使用原则：只有在你确认某个上游网关确实偏离了标准协议，而且 Dominds 已为这个偏差实现了命名 quirk 时才配置；不要把它当作随意调参入口。当前实现里，未知 quirk 值通常不会报错，但也不会带来任何效果。',
-                    '当前已知示例：OpenAI Responses 包装层支持 `apiQuirks: xcode.best`（或数组里包含它）。它一方面会把供应商额外发出的 `keepalive` 流事件识别为 heartbeat，而不是当作异常事件处理；另一方面也会对该网关特有的失败模式做 provider-specific failure handling，包括“同一对话上下文连续返回 empty response”时先做少量临时重试；如果在同一未变化上下文里连续达到阈值，就判定这是 provider 侧 same-context deadlock，而不是普通基础设施抖动：此时继续沿用同一上下文自动重试大概率仍然不会有真实进展，必须引入新的信息或新的指令（例如补充上下文、改写问题、换一个切入方式，或在确实需要人类判断时调用 askHuman）。这类 provider/API retry 状态在同一次 driver 自动续跑链里会继续沿用，不因中途换 course 而自动清零；若当前对话启用了鞭策，driver 也会优先判断是否能按鞭策逻辑直接续跑一次，而不是先落入 stopped，并且一旦 driver 接受这次自动恢复资格，就会立刻记作已消费；这里的恢复语义是“deadlock break”而不是普通空转鞭策，所以即使当前轮次已经登记了在途诉请/支线对话，也不会仅因 pending subdialog 就否决这一次恢复；以及把网关返回的 HTML 版 502 Bad Gateway 错误页和 `500 auth_unavailable: no auth available` 这类基础设施失败归类为 conservative 策略重试。最小示例：\n```yaml\nproviders:\n  my_gateway:\n    apiType: openai\n    baseUrl: https://example.invalid/v1\n    apiKeyEnvVar: MY_GATEWAY_API_KEY\n    apiQuirks: xcode.best\n    models:\n      my_model: { name: "upstream-model-id" }\n```',
+                    '当前已知示例：OpenAI Responses 包装层支持 `apiQuirks: xcode.best`（或数组里包含它）。它一方面会把供应商额外发出的 `keepalive` 流事件识别为 heartbeat，而不是当作异常事件处理；另一方面也会对该网关特有的失败模式做 provider-specific failure handling，包括“同一对话上下文连续返回 empty response”时先做少量临时重试；如果在同一未变化上下文里连续达到阈值，就判定这是 provider 侧 same-context deadlock，而不是普通基础设施抖动：此时继续沿用同一上下文自动重试大概率仍然不会有真实进展，必须引入新的信息或新的指令（例如补充上下文、改写问题、换一个切入方式，或在确实需要人类判断时调用 askHuman）。这类 provider/API retry 状态在同一次 driver 自动续跑链里会继续沿用，不因中途换 course 而自动清零；若当前对话启用了鞭策，driver 也会优先判断是否能按鞭策逻辑直接续跑一次，而不是先落入 stopped，并且一旦 driver 接受这次自动恢复资格，就会立刻记作已消费；这里的恢复语义是“deadlock break”而不是普通空转鞭策，所以即使当前轮次已经登记了在途诉请/支线对话，也不会仅因 pending sideDialog 就否决这一次恢复；以及把网关返回的 HTML 版 502 Bad Gateway 错误页和 `500 auth_unavailable: no auth available` 这类基础设施失败归类为 conservative 策略重试。最小示例：\n```yaml\nproviders:\n  my_gateway:\n    apiType: openai\n    baseUrl: https://example.invalid/v1\n    apiKeyEnvVar: MY_GATEWAY_API_KEY\n    apiQuirks: xcode.best\n    models:\n      my_model: { name: "upstream-model-id" }\n```',
                     '边界提醒：`apiQuirks` 只影响实现里显式消费它的 provider/generator。就当前实现看，至少 OpenAI Responses 路径会读取它；不要假设所有 `apiType` 都支持或需要它。若配置后行为仍异常，应继续检查上游网关文档、抓流事件类型，并结合 `team_mgmt_check_provider(...)` / 运行日志排查。',
                 ])
             : fmtHeader('.minds/llm.yaml') +
@@ -128,7 +128,7 @@ async function renderTeamMgmtGuideContent(language, topicsRaw = []) {
                     'Optional: `model_param_options` documents `.minds/team.yaml model_params` knobs (documentation only).',
                     '`apiQuirks` is optional under `providers.<providerKey>.apiQuirks`, with type `string|string[]`. It is a provider-level transport / gateway compatibility switch for non-standard upstream API behavior. It is not a `.minds/team.yaml` member field and not part of `model_params`.',
                     'Use it only when you have confirmed that an upstream gateway deviates from the expected protocol and Dominds has an explicitly named quirk for that deviation. Do not treat it as a generic tuning field. In the current implementation, unknown quirk values are usually ignored rather than rejected, so a typo may silently do nothing.',
-                    'Known current example: the OpenAI Responses wrapper supports `apiQuirks: xcode.best` (or an array containing it). It not only treats vendor-emitted `keepalive` stream events as heartbeat events instead of unexpected protocol noise, but also applies provider-specific failure handling for gateway-specific failures, including repeated empty responses in the same unchanged dialog context (a few temporary retries first; once the unchanged-context streak reaches the threshold, Dominds treats it as a provider-side same-context deadlock rather than ordinary infrastructure flakiness, which means repeating the same automatic retry path is no longer expected to make real progress and fresh information or fresh instructions are required, such as adding context, reframing the ask, changing the angle, or calling askHuman when human judgment is genuinely needed; this provider/API retry state intentionally continues across course changes within the same driver auto-continue chain; if Diligence Push is enabled for the dialog, the driver will first see whether it can continue once through that path before falling into stopped, and that recovery budget is considered consumed as soon as the driver accepts that path; this is a deadlock-break recovery rather than the ordinary idle-time Diligence Push, so a pending subdialog alone does not veto that one recovery injection) and gateway-returned HTML 502 Bad Gateway pages plus `500 auth_unavailable: no auth available` infrastructure failures classified into conservative retry. Minimal example:\n```yaml\nproviders:\n  my_gateway:\n    apiType: openai\n    baseUrl: https://example.invalid/v1\n    apiKeyEnvVar: MY_GATEWAY_API_KEY\n    apiQuirks: xcode.best\n    models:\n      my_model: { name: "upstream-model-id" }\n```',
+                    'Known current example: the OpenAI Responses wrapper supports `apiQuirks: xcode.best` (or an array containing it). It not only treats vendor-emitted `keepalive` stream events as heartbeat events instead of unexpected protocol noise, but also applies provider-specific failure handling for gateway-specific failures, including repeated empty responses in the same unchanged dialog context (a few temporary retries first; once the unchanged-context streak reaches the threshold, Dominds treats it as a provider-side same-context deadlock rather than ordinary infrastructure flakiness, which means repeating the same automatic retry path is no longer expected to make real progress and fresh information or fresh instructions are required, such as adding context, reframing the ask, changing the angle, or calling askHuman when human judgment is genuinely needed; this provider/API retry state intentionally continues across course changes within the same driver auto-continue chain; if Diligence Push is enabled for the dialog, the driver will first see whether it can continue once through that path before falling into stopped, and that recovery budget is considered consumed as soon as the driver accepts that path; this is a deadlock-break recovery rather than the ordinary idle-time Diligence Push, so a pending sideDialog alone does not veto that one recovery injection) and gateway-returned HTML 502 Bad Gateway pages plus `500 auth_unavailable: no auth available` infrastructure failures classified into conservative retry. Minimal example:\n```yaml\nproviders:\n  my_gateway:\n    apiType: openai\n    baseUrl: https://example.invalid/v1\n    apiKeyEnvVar: MY_GATEWAY_API_KEY\n    apiQuirks: xcode.best\n    models:\n      my_model: { name: "upstream-model-id" }\n```',
                     'Boundary reminder: `apiQuirks` only affects providers/generators that explicitly read it in code. In the current implementation, at least the OpenAI Responses path consumes it; do not assume every `apiType` supports or needs it. If behavior is still wrong after setting it, continue with upstream gateway docs, raw stream event inspection, and `team_mgmt_check_provider(...)` / runtime logs.',
                 ]);
     }

package/dist/tools/team_mgmt-mcp-manual.d.ts

@@ -2,8 +2,8 @@ import type { LanguageCode } from '@longrun-ai/kernel/types/language';
 import { type McpToolsetManualState } from '../mcp/manual-problems';
 export type McpToolsetMappingEntry = {
     serverId: string;
-    transport: 'stdio' | 'streamable_http' | 'invalid';
-    status: 'registered' | 'declared_unloaded' | 'declared_invalid';
+    transport: 'stdio' | 'streamable_http' | 'invalid' | 'unknown';
+    status: 'registered' | 'declared_unloaded' | 'declared_invalid' | 'disabled';
     loadedToolCount?: number;
     loadedToolNames?: string[];
     loadedToolNamesPreview?: string[];

package/dist/tools/team_mgmt-mcp-manual.js

@@ -157,14 +157,24 @@ function renderAutoGeneratedMcpManualDraftSection(language, entry) {
         ? language === 'zh'
             ? '已加载'
             : 'loaded'
-        : entry.status === 'declared_unloaded'
+        : entry.status === 'disabled'
             ? language === 'zh'
-                ? '已声明但未加载'
-                : 'declared but not loaded'
-            : language === 'zh'
-                ? '声明无效'
-                : 'invalid declaration';
-    const transportText = entry.transport === 'invalid' ? 'invalid' : entry.transport === 'stdio' ? 'stdio' : 'http';
+                ? '已禁用'
+                : 'disabled'
+            : entry.status === 'declared_unloaded'
+                ? language === 'zh'
+                    ? '已声明但未加载'
+                    : 'declared but not loaded'
+                : language === 'zh'
+                    ? '声明无效'
+                    : 'invalid declaration';
+    const transportText = entry.transport === 'invalid'
+        ? 'invalid'
+        : entry.transport === 'unknown'
+            ? 'unknown'
+            : entry.transport === 'stdio'
+                ? 'stdio'
+                : 'http';
     lines.push(`\n### toolset \`${entry.serverId}\``);
     lines.push(...fmtList([
         language === 'zh'
@@ -195,8 +205,12 @@ function renderAutoGeneratedMcpManualDraftSection(language, entry) {
     else {
         lines.push(...fmtList([
             language === 'zh'
-                ? '当前无法给出已加载 tools 清单（通常因为该 server 尚未加载）。先运行 `team_mgmt_validate_mcp_cfg({})`，必要时再 `mcp_restart`。'
-                : 'Loaded tools are not currently available (usually because this server is not loaded yet). Run `team_mgmt_validate_mcp_cfg({})`, then `mcp_restart` if needed.',
+                ? entry.status === 'disabled'
+                    ? '该 server 当前为 disabled，按设计暴露为 0 工具 toolset。需要启用时运行 `mcp_restart`。'
+                    : '当前无法给出已加载 tools 清单（通常因为该 server 尚未加载或启动失败）。先运行 `team_mgmt_validate_mcp_cfg({})`，必要时再 `mcp_restart`。'
+                : entry.status === 'disabled'
+                    ? 'This server is disabled and intentionally exposed as a zero-tool toolset. Run `mcp_restart` to enable it.'
+                    : 'Loaded tools are not currently available (usually because this server is not loaded yet or failed to start). Run `team_mgmt_validate_mcp_cfg({})`, then `mcp_restart` if needed.',
         ])
             .trimEnd()
             .split('\n'));
@@ -290,6 +304,7 @@ async function readMcpToolsetMappingSnapshot() {
     for (const invalid of parsed.invalidServers) {
         invalidByServerId.set(invalid.serverId, invalid.errorText);
     }
+    const disabledServerIds = new Set(parsed.disabledServerIdsInYamlOrder);
     const entries = [];
     for (const serverId of parsed.serverIdsInYamlOrder) {
         const invalidError = invalidByServerId.get(serverId);
@@ -310,6 +325,18 @@ async function readMcpToolsetMappingSnapshot() {
             });
             continue;
         }
+        if (disabledServerIds.has(serverId)) {
+            entries.push({
+                serverId,
+                transport: 'unknown',
+                status: 'disabled',
+                loadedToolCount: 0,
+                loadedToolNames: [],
+                loadedToolNamesPreview: [],
+                manualState,
+            });
+            continue;
+        }
         const transport = parsed.config.servers[serverId]?.transport ?? 'invalid';
         const loadedTools = registeredToolsets[serverId];
         if (loadedTools) {
@@ -378,7 +405,13 @@ function renderMcpToolsetMappingSection(language, snapshot) {
     }
     const lines = [];
     for (const entry of snapshot.entries) {
-        const transportText = entry.transport === 'invalid' ? 'invalid' : entry.transport === 'stdio' ? 'stdio' : 'http';
+        const transportText = entry.transport === 'invalid'
+            ? 'invalid'
+            : entry.transport === 'unknown'
+                ? 'unknown'
+                : entry.transport === 'stdio'
+                    ? 'stdio'
+                    : 'http';
         const manualText = describeMcpManualState(language, entry.manualState);
         if (entry.status === 'registered') {
             const preview = entry.loadedToolNamesPreview ?? [];
@@ -399,6 +432,12 @@ function renderMcpToolsetMappingSection(language, snapshot) {
                 : `\`servers.${entry.serverId}\` -> toolset \`${entry.serverId}\` (transport=${transportText}, status=declared but not loaded; ${manualText})`);
             continue;
         }
+        if (entry.status === 'disabled') {
+            lines.push(language === 'zh'
+                ? `\`servers.${entry.serverId}\` -> toolset \`${entry.serverId}\`（状态=已禁用，tools=0；${manualText}）`
+                : `\`servers.${entry.serverId}\` -> toolset \`${entry.serverId}\` (status=disabled, tools=0; ${manualText})`);
+            continue;
+        }
         lines.push(language === 'zh'
             ? `\`servers.${entry.serverId}\` -> toolset \`${entry.serverId}\`（状态=声明无效：${firstNonEmptyLine(entry.errorText ?? '')}；${manualText}）`
             : `\`servers.${entry.serverId}\` -> toolset \`${entry.serverId}\` (status=invalid declaration: ${firstNonEmptyLine(entry.errorText ?? '')}; ${manualText})`);
@@ -406,11 +445,13 @@ function renderMcpToolsetMappingSection(language, snapshot) {
     const tail = language === 'zh'
         ? [
             '说明：`已声明但未加载` 通常表示当前会话尚未完成 MCP 重载，或 server 启动失败。',
+            '说明：`已禁用` 表示该 server 在 `.minds/mcp.yaml` 中为 `enabled: false`，会保留 0 工具 toolset 和手册可见性。',
             '说明：MCP toolset “没有 manual” 不等于“不可用”。无 manual 仅表示团队管理者没有提供章节化手册；你应继续阅读每个工具的 description/参数并谨慎使用。',
             '建议：运行 `team_mgmt_validate_mcp_cfg({})`，必要时执行 `mcp_restart`。',
         ]
         : [
             '`declared but not loaded` usually means MCP reload has not completed in the current session, or server startup failed.',
+            '`disabled` means the server has `enabled: false` in `.minds/mcp.yaml`; Dominds keeps a zero-tool toolset and manual visible.',
             'Important: “missing manual” for an MCP toolset does NOT mean unavailable. It only means the team manager did not provide chapterized manual text; continue by reading each tool description/arguments and use with care.',
             'Recommendation: run `team_mgmt_validate_mcp_cfg({})`, then `mcp_restart` if needed.',
         ];
@@ -481,9 +522,10 @@ async function renderMcpManual(language) {
         return (fmtHeader('.minds/mcp.yaml') +
             fmtList([
                 '每个 MCP `serverId` 注册一个 toolset，toolset 名称 = `serverId`（不加 `mcp_` 前缀）。成员通过 `members.<id>.toolsets` 选择能用哪些 MCP toolset。',
-                '支持热重载：编辑 `.minds/mcp.yaml` 后通常无需重启 Dominds；必要时用 `mcp_restart`。',
-                '默认按“每个对话租用一个 MCP 运行时实例”运行（更安全）：某个对话首次使用该 server 时，可能为它启动/持有一个运行时实例（HTTP 连接或 stdio 进程），并添加 sticky reminder。确认当前对话不再需要该运行时实例后，用 `mcp_release` 释放。租约只表达运行时资源归属，不决定该 server 的全局工具注册/可见性；如确实是无状态服务器，可配置 `truely-stateless: true` 允许跨对话共享。',
+                '支持热重载：编辑 `.minds/mcp.yaml` 后通常无需重启 Dominds；必要时用 `mcp_restart`。`mcp_restart` 会把目标 server 的 `enabled: false` 写回 `enabled: true` 后尝试启动；成功后替换全局 runtime 并清掉旧 runtime 的全部对话 lease。',
+                '默认按“每个对话租用一个 MCP 运行时实例”运行（更安全）：某个对话首次使用该 server 时，可能为它启动/持有一个运行时实例（HTTP 连接或 stdio 进程），并添加 sticky reminder。确认当前对话不再需要该运行时实例后，用 `mcp_release` 释放。租约只表达运行时资源归属，不决定该 server 的全局工具注册/可见性；如确实是无状态服务器，可配置 `truely-stateless: true` 允许跨对话共享。若需停用某 server，用 `mcp_disable` 写入 `enabled: false`；禁用后仍会保留 0 工具 toolset 和手册可见性。',
                 'stdio 配置格式：`command` 必须是字符串（可执行命令），参数放在 `args`（string[]，可省略，默认空数组）。`cwd` 可选（字符串）：用于固定相对路径解析目录。',
+                'HTTP headers 支持三种值：字面量字符串、`{ env: NAME }`、`{ prefix: "Bearer ", env: NAME }`；认证 token 建议从环境变量读取，不要写死在 YAML。',
                 '用 `tools.whitelist/blacklist` 控制暴露的工具，用 `transform` 做命名变换。',
                 '常见坑：stdio transport 需要可执行命令路径正确，且受成员权限（目录 + 扩展名：`*_dirs/no_*_dirs/*_file_ext_names/no_*_file_ext_names`）约束；HTTP transport 需要服务可达（url/端口/网络）。',
                 '高频坑（stdio 路径）：若未设置 `cwd`，相对路径按 Dominds 进程工作目录（通常 rtws 根目录）解析；建议显式配置 `cwd` 或直接使用绝对路径。`cwd` 必须存在且是目录。',
@@ -494,7 +536,7 @@ async function renderMcpManual(language) {
                 '团队管理者建议：配置并验证 MCP 后，应先精读该 server 暴露的每个工具 description/参数，再与人类用户讨论本 rtws 中这些工具的使用意图，然后把正式手册沉淀到 `manual.contentFile`；若还需要在团队管理层额外解释业务边界，可再补 inline `content + sections`。',
                 '章节组织建议采用“半结构化”：可优先考虑 `何时使用`、`安全边界`、`不可用时业务处置` 这类高价值章节，但不要求所有 toolset 都照抄同一模板。应从真实业务目标出发，决定哪些章节需要展开、哪些只需一句话、哪些可以合并或另起更贴切的标题。',
                 '对每个 MCP toolset，团队管理者仍应刻意写明“不可用时业务处置规约”：至少回答 1) 当前 toolset 暂不可达时是否必须找协调者/专员接手；2) 是否允许走人工或其他工具链降级路径；3) 哪些业务动作在该 toolset 恢复前必须暂停，禁止擅自继续。',
-                '最小诊断流程（建议顺序）：1) 先用 `team_mgmt_check_provider({ provider_key: "<providerKey>", model: "", all_models: false, live: false })` 确认 LLM provider 可用；2) 再检查该成员的目录权限（`man({ "toolsetId": "team_mgmt", "topics": ["permissions"] })`）；3) 运行 `team_mgmt_validate_mcp_cfg({})` 汇总 `.minds/mcp.yaml` 与 MCP 问题；4) 必要时 `mcp_restart`，用完记得 `mcp_release`。',
+                '最小诊断流程（建议顺序）：1) 先用 `team_mgmt_check_provider({ provider_key: "<providerKey>", model: "", all_models: false, live: false })` 确认 LLM provider 可用；2) 再检查该成员的目录权限（`man({ "toolsetId": "team_mgmt", "topics": ["permissions"] })`）；3) 运行 `team_mgmt_validate_mcp_cfg({})` 汇总 `.minds/mcp.yaml` 与 MCP 问题；4) 必要时 `mcp_restart` 启用/重启，或 `mcp_disable` 禁用；只在当前对话确实持有不再需要的 lease 时使用 `mcp_release`。',
             ]) +
             fmtCodeBlock('yaml', [
                 '# 最小模板（stdio）',
@@ -545,6 +587,10 @@ async function renderMcpManual(language) {
                 '    truely-stateless: false',
                 '    transport: streamable_http',
                 '    url: http://127.0.0.1:3000/mcp',
+                '    # headers:',
+                '    #   Authorization:',
+                '    #     prefix: "Bearer "',
+                '    #     env: MCP_AUTH_TOKEN',
                 '    tools: { whitelist: [], blacklist: [] }',
                 '    transform: []',
                 '    manual:',
@@ -560,9 +606,10 @@ async function renderMcpManual(language) {
     return (fmtHeader('.minds/mcp.yaml') +
         fmtList([
             'Each MCP `serverId` registers one toolset, and the toolset name is exactly `serverId` (no `mcp_` prefix). Members choose MCP access via `members.<id>.toolsets`.',
-            'Hot reload: edits usually apply without restarting Dominds; use `mcp_restart` when needed.',
-            "Default is per-dialog MCP runtime leasing (safer): a dialog's first use may start/hold one runtime instance for that server (an HTTP connection or stdio process), and first use adds a sticky reminder. Call `mcp_release` when you're sure the current dialog no longer needs that runtime instance. This lease is about runtime resource ownership only; tool registration/visibility still follows the latest global server instance. If the server is truly stateless, set `truely-stateless: true` to allow cross-dialog sharing.",
+            'Hot reload: edits usually apply without restarting Dominds; use `mcp_restart` when needed. `mcp_restart` writes `enabled: true` when the target server is currently `enabled: false`, then tries to start it; after success it replaces the global runtime and clears all dialog leases on the old runtime.',
+            "Default is per-dialog MCP runtime leasing (safer): a dialog's first use may start/hold one runtime instance for that server (an HTTP connection or stdio process), and first use adds a sticky reminder. Call `mcp_release` when you're sure the current dialog no longer needs that runtime instance. This lease is about runtime resource ownership only; tool registration/visibility still follows the latest global server instance. If the server is truly stateless, set `truely-stateless: true` to allow cross-dialog sharing. To disable a server, use `mcp_disable` to write `enabled: false`; disabled servers remain visible as zero-tool toolsets with their manuals.",
             'Stdio shape: `command` must be a string executable; parameters go in `args` (string[], optional, defaults to empty). Optional `cwd` (string) fixes the working directory used for relative paths.',
+            'HTTP headers support three value forms: literal strings, `{ env: NAME }`, and `{ prefix: "Bearer ", env: NAME }`; keep auth tokens in env instead of hardcoding them in YAML.',
             'Use `tools.whitelist/blacklist` for exposure control and `transform` for naming transforms.',
             'Common pitfalls: stdio transport needs a correct executable/command path, and is subject to member permissions (directory + extension: `*_dirs/no_*_dirs/*_file_ext_names/no_*_file_ext_names`); HTTP transport requires the server URL to be reachable.',
             'High-frequency pitfall (stdio paths): if `cwd` is omitted, relative paths are resolved from Dominds process cwd (usually rtws root). Prefer setting `cwd` explicitly or use absolute paths. `cwd` must exist and be a directory.',
@@ -573,7 +620,7 @@ async function renderMcpManual(language) {
             'Team-manager recommendation: after MCP config is validated, carefully read descriptions/arguments of each exposed tool, discuss intended usage for this rtws with the human user, then write the formal manual into `manual.contentFile`; if extra team-management interpretation is still useful, add inline `content + sections` alongside it.',
             'Use a semi-structured chapter shape: high-value sections often include `When To Use`, `Guardrails`, and `Business Handling When Unavailable`, but do not force every toolset into one fixed template. Start from the real business goal, then decide which sections deserve depth, which can stay brief, and which should be merged or renamed to fit the scenario.',
             'For each MCP toolset, still document unavailable-case business rules explicitly: at minimum answer 1) whether a temporarily unavailable toolset must be escalated to a coordinator or specialist, 2) whether a manual or alternate-tool fallback path is allowed, and 3) which business actions must pause until this toolset recovers.',
-            'Minimal diagnostic flow: 1) run `team_mgmt_check_provider({ provider_key: "<providerKey>", model: "", all_models: false, live: false })` to confirm the LLM provider works; 2) review member directory permissions (`man({ "toolsetId": "team_mgmt", "topics": ["permissions"] })`); 3) run `team_mgmt_validate_mcp_cfg({})` to summarize `.minds/mcp.yaml` + MCP issues; 4) use `mcp_restart` if needed, and `mcp_release` when done.',
+            'Minimal diagnostic flow: 1) run `team_mgmt_check_provider({ provider_key: "<providerKey>", model: "", all_models: false, live: false })` to confirm the LLM provider works; 2) review member directory permissions (`man({ "toolsetId": "team_mgmt", "topics": ["permissions"] })`); 3) run `team_mgmt_validate_mcp_cfg({})` to summarize `.minds/mcp.yaml` + MCP issues; 4) use `mcp_restart` to enable/restart, or `mcp_disable` to disable; use `mcp_release` only when the current dialog actually holds a lease it no longer needs.',
         ]) +
         fmtCodeBlock('yaml', [
             '# Minimal template (stdio)',
@@ -624,6 +671,10 @@ async function renderMcpManual(language) {
             '    truely-stateless: false',
             '    transport: streamable_http',
             '    url: http://127.0.0.1:3000/mcp',
+            '    # headers:',
+            '    #   Authorization:',
+            '    #     prefix: "Bearer "',
+            '    #     env: MCP_AUTH_TOKEN',
             '    tools: { whitelist: [], blacklist: [] }',
             '    transform: []',
             '    manual:',