npm - dominds - Versions diffs - 0.9.0 → 0.9.2 - Mend

dominds 0.9.0 → 0.9.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (101) hide show

package/dist/static/index.html CHANGED Viewed

@@ -52,7 +52,7 @@
         padding: 20px;
       }
     </style>
-    <script type="module" crossorigin src="/assets/index-BWgwzFdG.js"></script>
+    <script type="module" crossorigin src="/assets/index-CFSjKmjb.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-Be077roh.css">
   </head>
   <body>

package/dist/tools/prompts/team_mgmt/en/tools.md CHANGED Viewed

@@ -74,6 +74,10 @@
 - `codex_style_tools`: Codex-style tools (`apply_patch` / `readonly_shell` / `update_plan`); **do not configure this toolset on Windows**
 - `mcp_admin`: MCP operations (`mcp_restart` / `mcp_release`), plus env tools (`env_get` / `env_set` / `env_unset`)
 - MCP-declared toolsets: dynamically mapped from `.minds/mcp.yaml` `servers.<serverId>` (toolset name = `serverId`). Exact capabilities depend on each MCP server’s exposed tools; use `team_mgmt_manual({ topics: ["toolsets"] })` to view the current mapping snapshot
+  - Optional per-toolset manual can be placed at `servers.<serverId>.manual` using `content` (overview) and `sections` (chapters)
+  - Missing manual does **not** mean the toolset is unavailable; runtime manual will auto-generate a baseline draft (at least a tools-list section) for temporary use
+  - Auto-generated draft is only a scaffold: team manager must confirm intent/boundaries with the human user, then replace it with accurate manual content
+  - Team managers should, after MCP validation passes, carefully read each exposed tool description, align with the human user on intended rtws usage, then write `servers.<serverId>.manual` with typical usage patterns and primary intent directions
 ## ripgrep Dependency (Detection & Install)

package/dist/tools/prompts/team_mgmt/zh/tools.md CHANGED Viewed

@@ -74,6 +74,10 @@
 - `codex_style_tools`：Codex 风格工具（`apply_patch` / `readonly_shell` / `update_plan`）；**Windows 环境下不要配置该 toolset**
 - `mcp_admin`：MCP 运维（`mcp_restart` / `mcp_release`），并包含环境变量工具（`env_get` / `env_set` / `env_unset`）
 - MCP 声明型 toolset：来源于 `.minds/mcp.yaml` 的 `servers.<serverId>` 动态映射（toolset 名称 = `serverId`）。具体能力以该 MCP server 实际暴露工具为准；可在 `team_mgmt_manual({ topics: ["toolsets"] })` 查看当前映射快照
+  - 可选：在 `servers.<serverId>.manual` 放手册内容，支持 `content`（总说明）+ `sections`（章节）
+  - 注意：没有手册 **不代表** toolset 不可用；运行时手册会自动生成基础草稿（至少包含 tools 列表章节）供临时使用
+  - 自动草稿只是脚手架：团队管理者必须与人类用户确认意图与边界后，再改写成准确手册
+  - 团队管理者应在 MCP 配置验证通过后：先精读该 server 各工具说明，再与人类用户讨论本 rtws 的使用意图，最后把典型用法与主要意图方向写入 `servers.<serverId>.manual`
 ## ripgrep 依赖（检测与安装）

package/dist/tools/team_mgmt.js CHANGED Viewed

@@ -2858,6 +2858,7 @@ async function renderMcpManual(language) {
     const mcpSnapshot = await readMcpToolsetMappingSnapshot();
     const mcpMapping = renderMcpToolsetMappingSection(language, mcpSnapshot);
     const mcpSetup = renderMcpToolsetSetupGuideSection(language, mcpSnapshot);
+    const mcpManualDetails = renderMcpToolsetManualDetailsSection(language, mcpSnapshot);
     if (language === 'zh') {
         return (fmtHeader('.minds/mcp.yaml') +
             fmtList([
@@ -2868,6 +2869,9 @@ async function renderMcpManual(language) {
                 '用 `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` 必须存在且是目录。',
+                '可选手册字段：你可以在 `servers.<serverId>.manual` 放手册内容。支持 `content`（总说明）+ `sections`（章节列表），用于告诉智能体该 toolset 该怎么用。',
+                '重要：`manual` 缺失并不代表 MCP toolset 不可用；这只是团队管理工作不足。智能体应继续依据每个工具 description/参数自行判断并使用。',
+                '团队管理者建议：配置并验证 MCP 后，应先精读该 server 暴露的每个工具 description/参数，再与人类用户讨论本 rtws 中这些工具的使用意图，最后把“典型用法 + 主要意图方向”沉淀到 `servers.<serverId>.manual`（`content + sections`）。',
                 '最小诊断流程（建议顺序）：1) 先用 `team_mgmt_check_provider({ provider_key: \"<providerKey>\", model: \"\", all_models: false, live: false, max_models: 0 })` 确认 LLM provider 可用；2) 再检查该成员的目录权限（`team_mgmt_manual({ topics: [\"permissions\"] })`）；3) 运行 `team_mgmt_validate_mcp_cfg({})` 汇总 `.minds/mcp.yaml` 与 MCP 问题；4) 必要时 `mcp_restart`，用完记得 `mcp_release`。',
             ]) +
             fmtCodeBlock('yaml', [
@@ -2883,6 +2887,18 @@ async function renderMcpManual(language) {
                 '    env: {}',
                 '    tools: { whitelist: [], blacklist: [] }',
                 '    transform: []',
+                '    manual:',
+                '      content: |',
+                '        这个 MCP toolset 负责 xx，优先用于 xx 场景。',
+                '      sections:',
+                "        - title: '何时使用'",
+                '          content: |',
+                '            1) 当你需要 ...',
+                '            2) 执行前先确认 ...',
+                "        - title: '安全边界'",
+                '          content: |',
+                '            - 不要用于 ...',
+                '            - 若失败先看 ...',
             ]) +
             fmtCodeBlock('yaml', [
                 '# stdio 路径示例（最小）',
@@ -2905,9 +2921,15 @@ async function renderMcpManual(language) {
                 '    url: http://127.0.0.1:3000/mcp',
                 '    tools: { whitelist: [], blacklist: [] }',
                 '    transform: []',
+                '    manual:',
+                '      content: "用于远端 MCP 接口调用"',
+                '      sections:',
+                "        UseCases: '适用于 ...'",
+                "        Guardrails: '避免 ...'",
             ]) +
             mcpMapping +
-            mcpSetup);
+            mcpSetup +
+            mcpManualDetails);
     }
     return (fmtHeader('.minds/mcp.yaml') +
         fmtList([
@@ -2918,6 +2940,9 @@ async function renderMcpManual(language) {
             '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.',
+            'Optional manual field: place guide text at `servers.<serverId>.manual`. Supported shapes: `content` (overview) + `sections` (chapter list) to explain practical usage for this toolset.',
+            'Important: missing `manual` does not mean the MCP toolset is unavailable. It only indicates team-management coverage is incomplete; continue by reading each tool description/argument schema.',
+            '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 `servers.<serverId>.manual` (`content + sections`) capturing typical usage patterns and primary intent directions.',
             'Minimal diagnostic flow: 1) run `team_mgmt_check_provider({ provider_key: \"<providerKey>\", model: \"\", all_models: false, live: false, max_models: 0 })` to confirm the LLM provider works; 2) review member directory permissions (`team_mgmt_manual({ 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.',
         ]) +
         fmtCodeBlock('yaml', [
@@ -2933,6 +2958,18 @@ async function renderMcpManual(language) {
             '    env: {}',
             '    tools: { whitelist: [], blacklist: [] }',
             '    transform: []',
+            '    manual:',
+            '      content: |',
+            '        This MCP toolset is for xx and should be preferred in xx cases.',
+            '      sections:',
+            "        - title: 'When To Use'",
+            '          content: |',
+            '            1) Use when ...',
+            '            2) Confirm ... before execution.',
+            "        - title: 'Guardrails'",
+            '          content: |',
+            '            - Avoid using for ...',
+            '            - On failures, first inspect ...',
         ]) +
         fmtCodeBlock('yaml', [
             '# stdio path example (minimal)',
@@ -2955,9 +2992,15 @@ async function renderMcpManual(language) {
             '    url: http://127.0.0.1:3000/mcp',
             '    tools: { whitelist: [], blacklist: [] }',
             '    transform: []',
+            '    manual:',
+            '      content: "For remote MCP endpoint calls"',
+            '      sections:',
+            "        UseCases: 'Use for ...'",
+            "        Guardrails: 'Avoid ...'",
         ]) +
         mcpMapping +
-        mcpSetup);
+        mcpSetup +
+        mcpManualDetails);
 }
 function renderPermissionsManual(language) {
     if (language === 'zh') {
@@ -3219,6 +3262,320 @@ function firstNonEmptyLine(raw) {
     }
     return raw.trim();
 }
+function isObjectRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseMcpManualByServer(rawText) {
+    const manualByServerId = new Map();
+    const invalidByServerId = new Map();
+    let parsedRoot;
+    try {
+        parsedRoot = yaml_1.default.parse(rawText);
+    }
+    catch {
+        return { manualByServerId, invalidByServerId };
+    }
+    if (!isObjectRecord(parsedRoot)) {
+        return { manualByServerId, invalidByServerId };
+    }
+    const serversVal = parsedRoot['servers'];
+    if (!isObjectRecord(serversVal)) {
+        return { manualByServerId, invalidByServerId };
+    }
+    for (const [serverId, serverVal] of Object.entries(serversVal)) {
+        if (!isObjectRecord(serverVal))
+            continue;
+        const manualVal = serverVal['manual'];
+        if (manualVal === undefined || manualVal === null)
+            continue;
+        const parsed = parseMcpManualField(serverId, manualVal);
+        if (parsed.kind === 'present') {
+            manualByServerId.set(serverId, parsed.manual);
+            continue;
+        }
+        if (parsed.kind === 'invalid') {
+            invalidByServerId.set(serverId, parsed.errorText);
+        }
+    }
+    return { manualByServerId, invalidByServerId };
+}
+function parseMcpManualField(serverId, value) {
+    const fieldPath = `servers.${serverId}.manual`;
+    if (typeof value === 'string') {
+        const text = value.trim();
+        if (text === '') {
+            return { kind: 'invalid', errorText: `${fieldPath} must not be empty` };
+        }
+        return { kind: 'present', manual: { content: text, sections: [] } };
+    }
+    if (!isObjectRecord(value)) {
+        return {
+            kind: 'invalid',
+            errorText: `${fieldPath} must be either a string, or an object with optional content + sections`,
+        };
+    }
+    const contentVal = value['content'];
+    let content;
+    if (contentVal !== undefined) {
+        if (!isNonEmptyString(contentVal)) {
+            return {
+                kind: 'invalid',
+                errorText: `${fieldPath}.content must be a non-empty string when provided`,
+            };
+        }
+        content = contentVal.trim();
+    }
+    const sectionsVal = value['sections'];
+    const sections = [];
+    if (sectionsVal !== undefined) {
+        if (Array.isArray(sectionsVal)) {
+            for (let i = 0; i < sectionsVal.length; i++) {
+                const sectionVal = sectionsVal[i];
+                if (!isObjectRecord(sectionVal)) {
+                    return {
+                        kind: 'invalid',
+                        errorText: `${fieldPath}.sections[${i}] must be an object with title/content non-empty strings`,
+                    };
+                }
+                const title = sectionVal['title'];
+                const sectionContent = sectionVal['content'];
+                if (!isNonEmptyString(title) || !isNonEmptyString(sectionContent)) {
+                    return {
+                        kind: 'invalid',
+                        errorText: `${fieldPath}.sections[${i}] must provide non-empty title/content strings`,
+                    };
+                }
+                sections.push({ title: title.trim(), content: sectionContent.trim() });
+            }
+        }
+        else if (isObjectRecord(sectionsVal)) {
+            for (const [sectionTitle, sectionContent] of Object.entries(sectionsVal)) {
+                if (!isNonEmptyString(sectionTitle) || !isNonEmptyString(sectionContent)) {
+                    return {
+                        kind: 'invalid',
+                        errorText: `${fieldPath}.sections object entries must be non-empty string -> string`,
+                    };
+                }
+                sections.push({ title: sectionTitle.trim(), content: sectionContent.trim() });
+            }
+        }
+        else {
+            return {
+                kind: 'invalid',
+                errorText: `${fieldPath}.sections must be either [{ title, content }] or { "<title>": "<content>" }`,
+            };
+        }
+    }
+    if (!content && sections.length === 0) {
+        return {
+            kind: 'invalid',
+            errorText: `${fieldPath} must include at least one of content or sections`,
+        };
+    }
+    return { kind: 'present', manual: { content, sections } };
+}
+function describeMcpManualState(language, state) {
+    if (state.kind === 'present') {
+        const contentText = state.manual.content && state.manual.content.trim() !== ''
+            ? language === 'zh'
+                ? '有'
+                : 'yes'
+            : language === 'zh'
+                ? '无'
+                : 'no';
+        return language === 'zh'
+            ? `手册=已配置（content=${contentText}，sections=${state.manual.sections.length}）`
+            : `manual=configured (content=${contentText}, sections=${state.manual.sections.length})`;
+    }
+    if (state.kind === 'invalid') {
+        return language === 'zh'
+            ? `手册=声明无效（${firstNonEmptyLine(state.errorText)}；不影响 toolset 可用性，但这是团队管理配置问题）`
+            : `manual=invalid declaration (${firstNonEmptyLine(state.errorText)}; toolset availability is unaffected, but team management should fix this)`;
+    }
+    return language === 'zh'
+        ? '手册=缺失（不影响 toolset 可用性；这是团队管理配置不足，请根据每个工具 description/参数自行判断使用）'
+        : 'manual=missing (toolset availability is unaffected; this is a team-management gap, so rely on each tool description/arguments and proceed)';
+}
+function inferAutoGeneratedMcpIntentDirections(language, toolNames) {
+    const names = toolNames.map((name) => name.toLowerCase());
+    const out = [];
+    const pushUnique = (line) => {
+        if (!out.includes(line))
+            out.push(line);
+    };
+    const has = (needle) => names.some((name) => name.includes(needle));
+    if (has('browser') || has('page') || has('playwright') || has('screenshot')) {
+        pushUnique(language === 'zh'
+            ? '网页/浏览器自动化：用于页面操作、采样、信息抓取与可视化回归辅助。'
+            : 'Web/browser automation: page actions, sampling, information extraction, and visual-regression assistance.');
+    }
+    if (has('git') || has('repo') || has('diff') || has('pr') || has('commit')) {
+        pushUnique(language === 'zh'
+            ? '仓库协作与变更分析：用于读取仓库状态、比较差异、辅助代码审查。'
+            : 'Repository collaboration and change analysis: inspect repo state, compare diffs, and support review workflows.');
+    }
+    if (has('sql') || has('db') || has('query') || has('table') || has('postgres')) {
+        pushUnique(language === 'zh'
+            ? '数据查询/诊断：用于结构化检索与数据一致性排查。'
+            : 'Data query/diagnostics: structured retrieval and data-consistency investigation.');
+    }
+    if (has('k8s') || has('kubectl') || has('deploy') || has('cluster') || has('helm')) {
+        pushUnique(language === 'zh'
+            ? '部署与运行状态诊断：用于集群状态检查、发布过程观测与故障定位。'
+            : 'Deployment/runtime diagnostics: cluster-state checks, release observation, and incident localization.');
+    }
+    if (has('ticket') || has('issue') || has('jira') || has('linear')) {
+        pushUnique(language === 'zh'
+            ? '任务流转协作：用于工单读取、状态同步与流程追踪。'
+            : 'Ticket/workflow collaboration: ticket lookup, state synchronization, and process tracking.');
+    }
+    if (out.length === 0) {
+        out.push(language === 'zh'
+            ? '未识别出明确领域特征：建议按工具 description/参数逐个确认用途，并与人类用户共同定义边界。'
+            : 'No clear domain signature detected: review each tool description/arguments and define boundaries jointly with the human user.');
+    }
+    return out;
+}
+function renderAutoGeneratedMcpManualDraftSection(language, entry) {
+    const lines = [];
+    const statusText = entry.status === 'registered'
+        ? language === 'zh'
+            ? '已加载'
+            : 'loaded'
+        : entry.status === 'declared_unloaded'
+            ? language === 'zh'
+                ? '已声明但未加载'
+                : 'declared but not loaded'
+            : language === 'zh'
+                ? '声明无效'
+                : 'invalid declaration';
+    const transportText = entry.transport === 'invalid' ? 'invalid' : entry.transport === 'stdio' ? 'stdio' : 'http';
+    lines.push(`\n### toolset \`${entry.serverId}\``);
+    lines.push(...fmtList([
+        language === 'zh'
+            ? '检测到 `servers.<serverId>.manual` 缺失，以下为自动生成的基础手册草稿（供临时使用）。'
+            : '`servers.<serverId>.manual` is missing. Below is an auto-generated baseline manual draft (temporary use).',
+        language === 'zh'
+            ? `运行时状态：status=${statusText}，transport=${transportText}。`
+            : `Runtime status: status=${statusText}, transport=${transportText}.`,
+        language === 'zh'
+            ? '关键提醒：该草稿不等于最终规范。团队管理者必须与人类用户确认本 rtws 的真实意图后，再写入更准确的正式手册。'
+            : 'Critical reminder: this draft is not the final policy. Team manager must confirm actual rtws intent with the human user, then author a more accurate final manual.',
+    ])
+        .trimEnd()
+        .split('\n'));
+    lines.push(...fmtList([
+        language === 'zh'
+            ? '章节：tools 列表（运行时快照）'
+            : 'Section: Tools list (runtime snapshot)',
+    ])
+        .trimEnd()
+        .split('\n'));
+    if ((entry.loadedToolNames?.length ?? 0) > 0) {
+        const tools = entry.loadedToolNames ?? [];
+        lines.push(...fmtCodeBlock('text', tools.map((tool) => `- ${tool}`))
+            .trimEnd()
+            .split('\n'));
+    }
+    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.',
+        ])
+            .trimEnd()
+            .split('\n'));
+    }
+    lines.push(...fmtList([
+        language === 'zh'
+            ? '章节：主要意图方向（自动推测，待确认）'
+            : 'Section: Primary intent directions (auto-inferred, pending confirmation)',
+    ])
+        .trimEnd()
+        .split('\n'));
+    lines.push(...fmtList(inferAutoGeneratedMcpIntentDirections(language, entry.loadedToolNames ?? []))
+        .trimEnd()
+        .split('\n'));
+    lines.push(...fmtList([
+        language === 'zh'
+            ? '团队管理者后续动作：精读每个工具说明 -> 与人类用户确认意图与边界 -> 回写 `servers.<serverId>.manual.content + sections`。'
+            : 'Team-manager follow-up: read each tool description carefully -> confirm intent/boundaries with the human user -> write back to `servers.<serverId>.manual.content + sections`.',
+    ])
+        .trimEnd()
+        .split('\n'));
+    return lines.join('\n') + '\n';
+}
+function renderMcpToolsetManualDetailsSection(language, snapshot) {
+    const header = language === 'zh'
+        ? fmtSubHeader('MCP toolset 手册（来自 `.minds/mcp.yaml` 的 `servers.<serverId>.manual`）')
+        : fmtSubHeader('MCP Toolset Manuals (from `.minds/mcp.yaml` `servers.<serverId>.manual`)');
+    if (snapshot.kind !== 'loaded')
+        return '';
+    const entries = snapshot.entries;
+    if (entries.length === 0) {
+        return (header +
+            fmtList([
+                language === 'zh'
+                    ? '当前没有 MCP toolset 可展示。'
+                    : 'There are currently no MCP toolsets to display.',
+            ]));
+    }
+    let out = header +
+        fmtList([
+            language === 'zh'
+                ? '若 `servers.<serverId>.manual` 已配置，显示正式手册；若缺失，则自动生成基础草稿（含 tools 列表与意图方向草稿）供临时使用。'
+                : 'If `servers.<serverId>.manual` is configured, the formal manual is shown; if missing, an auto-generated baseline draft (including tools list and intent directions draft) is provided for temporary use.',
+        ]);
+    for (const entry of entries) {
+        if (entry.manualState.kind === 'missing') {
+            out += renderAutoGeneratedMcpManualDraftSection(language, entry);
+            continue;
+        }
+        if (entry.manualState.kind === 'invalid') {
+            out += `\n### toolset \`${entry.serverId}\`\n`;
+            out += fmtList([
+                language === 'zh'
+                    ? `\`servers.${entry.serverId}.manual\` 声明无效：${firstNonEmptyLine(entry.manualState.errorText)}`
+                    : `\`servers.${entry.serverId}.manual\` is invalid: ${firstNonEmptyLine(entry.manualState.errorText)}`,
+                language === 'zh'
+                    ? '这不影响 toolset 可用性；请根据工具说明继续使用，并通知团队管理者修复手册字段。'
+                    : 'Toolset availability is unaffected; continue by tool-level descriptions and ask the team manager to fix the manual field.',
+            ]);
+            continue;
+        }
+        if (entry.manualState.kind !== 'present')
+            continue;
+        const manual = entry.manualState.manual;
+        out += `\n### toolset \`${entry.serverId}\`\n`;
+        if (manual.content && manual.content.trim() !== '') {
+            out +=
+                fmtList([language === 'zh' ? '总说明（content）：' : 'Overview (`content`):']) +
+                    fmtCodeBlock('markdown', [manual.content]);
+        }
+        else {
+            out += fmtList([
+                language === 'zh'
+                    ? '总说明（content）：（未提供）'
+                    : 'Overview (`content`): (not provided)',
+            ]);
+        }
+        if (manual.sections.length > 0) {
+            for (const section of manual.sections) {
+                out +=
+                    fmtList([language === 'zh' ? `章节：${section.title}` : `Section: ${section.title}`]) +
+                        fmtCodeBlock('markdown', [section.content]);
+            }
+        }
+        else {
+            out += fmtList([
+                language === 'zh'
+                    ? '章节（sections）：（未提供）'
+                    : 'Sections (`sections`): (not provided)',
+            ]);
+        }
+    }
+    return out;
+}
 async function readMcpToolsetMappingSnapshot() {
     const mcpAbsPath = path_1.default.resolve(process.cwd(), MCP_YAML_REL);
     let rawText;
@@ -3238,6 +3595,7 @@ async function readMcpToolsetMappingSnapshot() {
     if (!parsed.ok) {
         return { kind: 'invalid_yaml', errorText: parsed.errorText };
     }
+    const manualInfo = parseMcpManualByServer(rawText);
     const registeredToolsets = (0, registry_2.listToolsets)();
     const invalidByServerId = new Map();
     for (const invalid of parsed.invalidServers) {
@@ -3246,24 +3604,35 @@ async function readMcpToolsetMappingSnapshot() {
     const entries = [];
     for (const serverId of parsed.serverIdsInYamlOrder) {
         const invalidError = invalidByServerId.get(serverId);
+        const manualError = manualInfo.invalidByServerId.get(serverId);
+        const manual = manualInfo.manualByServerId.get(serverId);
+        const manualState = manualError
+            ? { kind: 'invalid', errorText: manualError }
+            : manual
+                ? { kind: 'present', manual }
+                : { kind: 'missing' };
         if (invalidError) {
             entries.push({
                 serverId,
                 transport: 'invalid',
                 status: 'declared_invalid',
                 errorText: invalidError,
+                manualState,
             });
             continue;
         }
         const transport = parsed.config.servers[serverId]?.transport ?? 'invalid';
         const loadedTools = registeredToolsets[serverId];
         if (loadedTools) {
+            const loadedToolNames = loadedTools.map((t) => t.name);
             entries.push({
                 serverId,
                 transport,
                 status: 'registered',
                 loadedToolCount: loadedTools.length,
-                loadedToolNamesPreview: loadedTools.slice(0, 6).map((t) => t.name),
+                loadedToolNames,
+                loadedToolNamesPreview: loadedToolNames.slice(0, 6),
+                manualState,
             });
             continue;
         }
@@ -3271,6 +3640,7 @@ async function readMcpToolsetMappingSnapshot() {
             serverId,
             transport,
             status: 'declared_unloaded',
+            manualState,
         });
     }
     return { kind: 'loaded', entries };
@@ -3320,6 +3690,7 @@ function renderMcpToolsetMappingSection(language, snapshot) {
     const lines = [];
     for (const entry of snapshot.entries) {
         const transportText = entry.transport === 'invalid' ? 'invalid' : entry.transport === 'stdio' ? 'stdio' : 'http';
+        const manualText = describeMcpManualState(language, entry.manualState);
         if (entry.status === 'registered') {
             const preview = entry.loadedToolNamesPreview ?? [];
             const previewText = preview.length > 0
@@ -3329,27 +3700,29 @@ function renderMcpToolsetMappingSection(language, snapshot) {
                         : '')
                 : '(none)';
             lines.push(language === 'zh'
-                ? `\`servers.${entry.serverId}\` -> toolset \`${entry.serverId}\`（transport=${transportText}，状态=已加载，tools=${entry.loadedToolCount ?? 0}：${previewText}）`
-                : `\`servers.${entry.serverId}\` -> toolset \`${entry.serverId}\` (transport=${transportText}, status=loaded, tools=${entry.loadedToolCount ?? 0}: ${previewText})`);
+                ? `\`servers.${entry.serverId}\` -> toolset \`${entry.serverId}\`（transport=${transportText}，状态=已加载，tools=${entry.loadedToolCount ?? 0}：${previewText}；${manualText}）`
+                : `\`servers.${entry.serverId}\` -> toolset \`${entry.serverId}\` (transport=${transportText}, status=loaded, tools=${entry.loadedToolCount ?? 0}: ${previewText}; ${manualText})`);
             continue;
         }
         if (entry.status === 'declared_unloaded') {
             lines.push(language === 'zh'
-                ? `\`servers.${entry.serverId}\` -> toolset \`${entry.serverId}\`（transport=${transportText}，状态=已声明但未加载）`
-                : `\`servers.${entry.serverId}\` -> toolset \`${entry.serverId}\` (transport=${transportText}, status=declared but not loaded)`);
+                ? `\`servers.${entry.serverId}\` -> toolset \`${entry.serverId}\`（transport=${transportText}，状态=已声明但未加载；${manualText}）`
+                : `\`servers.${entry.serverId}\` -> toolset \`${entry.serverId}\` (transport=${transportText}, status=declared but not loaded; ${manualText})`);
             continue;
         }
         lines.push(language === 'zh'
-            ? `\`servers.${entry.serverId}\` -> toolset \`${entry.serverId}\`（状态=声明无效：${firstNonEmptyLine(entry.errorText ?? '')}）`
-            : `\`servers.${entry.serverId}\` -> toolset \`${entry.serverId}\` (status=invalid declaration: ${firstNonEmptyLine(entry.errorText ?? '')})`);
+            ? `\`servers.${entry.serverId}\` -> toolset \`${entry.serverId}\`（状态=声明无效：${firstNonEmptyLine(entry.errorText ?? '')}；${manualText}）`
+            : `\`servers.${entry.serverId}\` -> toolset \`${entry.serverId}\` (status=invalid declaration: ${firstNonEmptyLine(entry.errorText ?? '')}; ${manualText})`);
     }
     const tail = language === 'zh'
         ? [
             '说明：`已声明但未加载` 通常表示当前会话尚未完成 MCP 重载，或 server 启动失败。',
+            '说明：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.',
+            '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.',
         ];
     return header + fmtList(lines.concat(tail));
@@ -3553,6 +3926,7 @@ async function renderToolsets(language) {
     const mcpSnapshot = await readMcpToolsetMappingSnapshot();
     const mcpMapping = renderMcpToolsetMappingSection(language, mcpSnapshot);
     const mcpSetup = renderMcpToolsetSetupGuideSection(language, mcpSnapshot);
+    const mcpManualDetails = renderMcpToolsetManualDetailsSection(language, mcpSnapshot);
     return (header +
         intro +
         patterns +
@@ -3561,7 +3935,8 @@ async function renderToolsets(language) {
         list +
         capabilitySummary +
         mcpMapping +
-        mcpSetup);
+        mcpSetup +
+        mcpManualDetails);
 }
 async function renderBuiltinDefaults(language) {
     const header = language === 'zh'
@@ -3709,6 +4084,7 @@ exports.teamMgmtValidateMcpCfgTool = {
             let mcpRaw = null;
             let declaredServerCount = 0;
             let fallbackInvalidServers = [];
+            let fallbackInvalidToolsetManuals = [];
             try {
                 const st = await promises_1.default.stat(mcpYamlAbs);
                 if (!st.isFile()) {
@@ -3739,6 +4115,8 @@ exports.teamMgmtValidateMcpCfgTool = {
                 }
                 declaredServerCount = parsed.serverIdsInYamlOrder.length;
                 fallbackInvalidServers = parsed.invalidServers;
+                const manualInfo = parseMcpManualByServer(mcpRaw);
+                fallbackInvalidToolsetManuals = [...manualInfo.invalidByServerId.entries()].map(([serverId, errorText]) => ({ serverId, errorText }));
             }
             catch (err) {
                 if (!(isFsErrWithCode(err) && err.code === 'ENOENT')) {
@@ -3754,7 +4132,18 @@ exports.teamMgmtValidateMcpCfgTool = {
                     fallbackOnlyInvalidServers.push(s);
                 }
             }
-            if (mcpProblems.length === 0 && fallbackOnlyInvalidServers.length === 0) {
+            const fallbackOnlyInvalidToolsetManuals = [];
+            for (const s of fallbackInvalidToolsetManuals) {
+                const hasMatchingProblem = mcpProblems.some((p) => p.kind === 'mcp_server_error' &&
+                    p.detail.serverId === s.serverId &&
+                    p.detail.errorText.includes(firstNonEmptyLine(s.errorText)));
+                if (!hasMatchingProblem) {
+                    fallbackOnlyInvalidToolsetManuals.push(s);
+                }
+            }
+            if (mcpProblems.length === 0 &&
+                fallbackOnlyInvalidServers.length === 0 &&
+                fallbackOnlyInvalidToolsetManuals.length === 0) {
                 const msg = language === 'zh'
                     ? fmtHeader('mcp.yaml 校验通过') +
                         fmtList([
@@ -3809,19 +4198,29 @@ exports.teamMgmtValidateMcpCfgTool = {
                 issueLines.push(`  serverId: ${s.serverId}`);
                 issueLines.push('  ' + s.errorText.split('\n').join('\n  '));
             }
-            const totalIssues = mcpProblems.length + fallbackOnlyInvalidServers.length;
+            for (const s of fallbackOnlyInvalidToolsetManuals) {
+                issueLines.push(`- [error] ${MCP_SERVER_PROBLEM_PREFIX}${s.serverId}/toolset_manual_error`);
+                issueLines.push(`  serverId: ${s.serverId}`);
+                issueLines.push(language === 'zh'
+                    ? '  toolset manual: servers.<serverId>.manual 声明无效'
+                    : '  toolset manual: servers.<serverId>.manual invalid declaration');
+                issueLines.push('  ' + s.errorText.split('\n').join('\n  '));
+            }
+            const totalIssues = mcpProblems.length +
+                fallbackOnlyInvalidServers.length +
+                fallbackOnlyInvalidToolsetManuals.length;
             const msg = language === 'zh'
                 ? fmtHeader('mcp.yaml 校验失败') +
                     fmtList([
                         `\`${MCP_YAML_REL}\`：❌ 检测到 ${totalIssues} 个问题（详见 Problems 面板）`,
-                        '说明：MCP 配置问题会导致 server/toolset 加载失败、部分工具不可用或运行时异常。',
+                        '说明：MCP 配置问题（含 toolset manual 声明错误）会导致 server/toolset 加载失败、工具手册缺失/错误或运行时异常。',
                     ]) +
                     '\n' +
                     issueLines.join('\n')
                 : fmtHeader('mcp.yaml Validation Failed') +
                     fmtList([
                         `\`${MCP_YAML_REL}\`: ❌ ${totalIssues} issue(s) detected (see Problems panel)`,
-                        'Note: MCP config issues can block server/toolset loading and cause runtime tool failures.',
+                        'Note: MCP config issues (including toolset manual declaration errors) can block server/toolset loading, produce bad/missing manual guidance, or cause runtime tool failures.',
                     ]) +
                     '\n' +
                     issueLines.join('\n');

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "dominds",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "DevOps Mindsets — Sustainable Agentic Product Lifecycle",
   "type": "commonjs",
   "private": false,