# https://github.com/rnd-pro/mcp-agent-portal 项目说明书

生成时间：2026-06-20 23:15:55 UTC

## 目录

- [Overview & System Architecture](#page-1)
- [MCP Proxy, Multiplexing & Tool Routing](#page-2)
- [Agent Runtime, Adapters & Skills System](#page-3)
- [Web Dashboard & Frontend Panels](#page-4)

<a id='page-1'></a>

## Overview & System Architecture

### 相关页面

相关主题：[MCP Proxy, Multiplexing & Tool Routing](#page-2), [Agent Runtime, Adapters & Skills System](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/rnd-pro/mcp-agent-portal/blob/main/README.md)
- [package.json](https://github.com/rnd-pro/mcp-agent-portal/blob/main/package.json)
- [src/node/agents/frontmatter.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/agents/frontmatter.js)
- [src/node/agents/agent-parser.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/agents/agent-parser.js)
- [src/node/proxy/mcp-multiplexer.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/proxy/mcp-multiplexer.js)
- [src/node/proxy/tool-index.ctx.md](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/proxy/tool-index.ctx.md)
- [src/node/proxy/orchestration-development-map.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/proxy/orchestration-development-map.js)
- [src/node/proxy/workflow-board-tools.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/proxy/workflow-board-tools.js)
- [src/node/proxy/portal-orchestrator-tools.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/proxy/portal-orchestrator-tools.js)
- [src/node/server/marketplace-registry.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/server/marketplace-registry.js)
- [src/node/server/demo-mode.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/server/demo-mode.js)
- [src/node/server/local-gateway.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/server/local-gateway.js)
- [src/node/adapters/index.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/adapters/index.js)
</details>

# 系统概览与架构

## 项目定位

`mcp-agent-portal` 是一个统一的「代理与 MCP 控制平面」（Unified Agent & MCP Control Plane），将 AI 代理、MCP 工具、工作流、调度与同级评审整合在同一入口。其核心目标是为多代理协作提供聚合层：上层代理可以透明地发现并调用来自不同 MCP 服务器的公共工具，并基于项目本地的 `.agent-portal/` 技能与代理定义执行复杂任务。资料来源：[README.md:1-10]()

项目以 ESM 模块组织（`"type": "module"`），通过 `npm start` 启动服务，`npm run build` 将前端资源构建到 `dist/web`，开发模式则通过 `npm run dev` 指向 `web/` 源码目录。资料来源：[package.json:1-40]()

## 总体架构

整个系统采用分层结构，自下而上依次为：**模型/CLI 适配层** → **MCP 代理多路复用层** → **门户编排与工作流层** → **浏览器前端**。下图为各组件之间的逻辑关系：

```mermaid
flowchart TB
  subgraph FE[浏览器前端]
    UI["Portal UI<br/>(web/dist)"]
  end
  subgraph BE[Node 后端]
    GW["local-gateway.js<br/>HTTP/WS 网关"]
    SRV["backend.js / demo-mode.js<br/>HTTP API"]
    MUX["mcp-multiplexer.js<br/>MCP 多路复用"]
    ORCH["portal-orchestrator-tools.js<br/>编排工具"]
    WB["workflow-board-tools.js<br/>看板元工具"]
    DM["orchestration-development-map.js<br/>运行态遥测"]
    AD["adapters/index.js<br/>CLI/模型适配"]
  end
  subgraph EXT[外部 MCP 与项目资产]
    MR["marketplace-registry.js<br/>MCP 注册表"]
    AP["agent-parser.js<br/>项目代理解析"]
  end
  UI --> GW --> SRV
  SRV --> MUX
  MUX --> AD
  MUX --> ORCH
  MUX --> WB
  MUX --> DM
  AP --> SRV
  MR --> MUX
```

- **网关层**：`local-gateway.js` 负责端口复用、HTTP 升级（WebSocket）转发，并为静态资源注入 `<base>` 标签以支持子路径部署。资料来源：[src/node/server/local-gateway.js:1-10]()
- **演示与 API 装配**：`demo-mode.js` 在沙箱项目根 `/workspace/agent-portal` 下提供 `/api/adapter/types`、`/api/cli/config`、`/api/flywheel/stats`、`/api/skills`、`/api/workflows`、`/api/groups` 等接口，并对文件列举施加白名单与 96 KiB 大小限制。资料来源：[src/node/server/demo-mode.js:1-30]()

## 关键子系统

### 代理与技能解析
`agent-parser.js` 解析 `.agent-portal/agents/*.md` 文件，识别 `name/description/role/icon/color/resource_group/provider/model/models[]/skills[]/visibleAgents[]` 等 frontmatter 字段，并支持两种技能组合方式：列表前置（`skills: [X, Y]`）与内联占位符（`{{skill:Z}}`）。底层 YAML 解析由 `frontmatter.js` 提供，支持标量、行内/多行数组、行内对象与嵌套对象。资料来源：[src/node/agents/agent-parser.js:1-20]()、[src/node/agents/frontmatter.js:1-15]()

### MCP 多路复用与工具索引
`mcp-multiplexer.js` 是公共 MCP 工具的聚合入口，对外暴露一组「元工具」：`discover_tools`（关键字/标签/服务器名搜索）、`call_tool`（按名称调用）、`get_portal_status`（门户健康与运行态摘要），以及 `create_chat`/`switch_chat`/`send_chat_message` 等会话控制。资料来源：[src/node/proxy/mcp-multiplexer.js:1-25]()

工具索引由 `tool-index.js` 维护：对每个子 MCP 服务器调用 `tools/list` 后构建摘要条目（工具对象 + 来源服务器），支持关键字、标签与服务器名检索；子服务器拓扑变化时应重建。资料来源：[src/node/proxy/tool-index.ctx.md:1-10]()

### 适配器与模型发现
`adapters/index.js` 通过 `getEffectiveModels()` 按「用户配置 → CLI 发现 → 默认」三段优先级合并模型列表：`claude` 使用 `CLAUDE_CODE_MODEL_CATALOG`；`opencode` 注入运行时 CLI 模型；`antigravity` 追加 `default` 占位。资料来源：[src/node/adapters/index.js:1-25]()

### 编排、看板与遥测
`orchestration-development-map.js` 输出统一的「开发地图」（`schemaVersion: 1`），聚合子代理、任务、工具调用与最近活动，并施加硬性上限 `SUBAGENT_LIMIT` / `TASK_LIMIT` / `TOOL_EVENT_LIMIT` / `TOOL_BUCKET_LIMIT`，避免超出代理上下文预算。资料来源：[src/node/proxy/orchestration-development-map.js:1-20]()

`workflow-board-tools.js` 将工作流看板收敛到单一 `workflow_board` 工具，通过 `action` 字段路由（`create_item`/`update_item`/`decompose`/`transition`/`control_board` 等），支持 `approvalMode: yolo|auto_edit|plan` 与乐观版本号。资料来源：[src/node/proxy/workflow-board-tools.js:1-25]()

`marketplace-registry.js` 维护官方/Google/社区三类 MCP 服务器清单（如 `brave-search`、`fetch`、`github`、`slack`、`linear` 等），并通过 `getRegistryByCategory()` 与 `findInRegistry(name)` 提供分类与按名查询。资料来源：[src/node/server/marketplace-registry.js:1-30]()

## 数据流与典型交互

用户通过浏览器门户发起请求后，请求经 `local-gateway` 进入后端 HTTP API。门户的根会话路由到编排器，由 `portal-orchestrator-tools.js` 注入 `promptHints` 字符串与结构化建议（`promptHintMap`），指导子代理在合适的时机调用 `discover_tools` 与 `call_tool`。编排过程中，所有工具调用、代理切换与任务生命周期事件被聚合到 `orchestration-development-map.js`，形成可消费的运行态视图；最终结果通过 `workflow_board.transition` 等动作落库到看板。资料来源：[src/node/proxy/portal-orchestrator-tools.js:1-25]()

> 备注：本检索批次未返回 `index.js` / `backend.js` / `bin/mcp-agent-portal.js` 的全文，上述入口职责以 `package.json` 中的脚本与同层文件所描述的接口为准。

---

<a id='page-2'></a>

## MCP Proxy, Multiplexing & Tool Routing

### 相关页面

相关主题：[Overview & System Architecture](#page-1), [Agent Runtime, Adapters & Skills System](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/node/proxy/mcp-proxy.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/proxy/mcp-proxy.js)
- [src/node/proxy/mcp-multiplexer.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/proxy/mcp-multiplexer.js)
- [src/node/proxy/mcp-http-handler.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/proxy/mcp-http-handler.js)
- [src/node/proxy/mcp-tool-visibility.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/proxy/mcp-tool-visibility.js)
- [src/node/proxy/mcp-helpers.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/proxy/mcp-helpers.js)
- [src/node/proxy/tool-index.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/proxy/tool-index.js)
- [src/node/server/web-server.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/server/web-server.js)
- [README.md](https://github.com/rnd-pro/mcp-agent-portal/blob/main/README.md)
</details>

# MCP Proxy, Multiplexing & Tool Routing

mcp-agent-portal 的核心职责之一，是把多个下游 MCP（Model Context Protocol）子服务器聚合成一个统一的对外接口，并向 IDE/Agent 客户端提供经过过滤的"门户级"工具视图。这一能力由 `src/node/proxy/` 目录下的若干模块协作完成，包括子进程生命周期管理、JSON-RPC 消息转发、工具索引缓存、可见性过滤与 HTTP/stdio 传输适配。本页介绍其整体架构与关键路径。

## 1. 总体架构与角色划分

门户（Agent Portal）运行后，会启动一个 `MCPProxyManager`，负责按配置拉起若干 child MCP server（通过 stdio 子进程），并对它们的 `tools/list`、`resources/read`、`tools/call` 等请求进行转发与聚合。资料来源：[README.md:1-120]()

整个请求链路可以概括为四层：

```mermaid
flowchart LR
  A[IDE / Agent 客户端] -->|stdio 或 HTTP| B[MCPProxyManager<br/>聚合与生命周期]
  B -->|转发 JSON-RPC| C1[project-graph-mcp]
  B -->|转发 JSON-RPC| C2[agent-pool-mcp]
  B -->|转发 JSON-RPC| C3[browser-x-mcp / 其他]
  B --> D[ToolIndex<br/>缓存与搜索]
  B --> E[mcp-multiplexer<br/>Meta-Tools Gateway]
  E --> F[portal-goal / portal-orchestrator<br/>工作流与编排工具]
  E --> G[workflow-board / chat-delegate<br/>子工具分发]
```

- **MCPProxyManager**：负责启动/停止 child server，缓存 server map，提供 `requestFromChild(serverName, method, params)`。
- **ToolIndex**：通过 `tools/list` 周期拉取各 child 的工具表，提供 keyword/tag/server 三种检索方式。资料来源：[src/node/proxy/tool-index.js:1-60]()
- **mcp-multiplexer**：作为"Smart Tool Gateway"，对外暴露门户级 meta-tools（`create_chat`、`resume_chat`、`get_development_map` 等），而不是把所有子工具原样泄露给客户端。资料来源：[src/node/proxy/mcp-multiplexer.js:1-90]()

## 2. 子服务器管理与 JSON-RPC 转发

`MCPProxyManager` 维护 `Map<string, ChildServer>`，其中 key 是 `~/.agent-portal/agent-portal.json` 中 `mcpServers` 的条目名，例如 `project-graph`、`agent-pool`。每个 child server 在 `startAllServers()` 阶段被 fork 为 stdio 子进程，并通过 `requestFromChild()` 进行 JSON-RPC 调用。资料来源：[src/node/server/backend.js:1-30]()

在 `requestFromChild()` 中实现了：

- 单子服务器 5 秒级的内部超时（`INTERNAL_TASK_STATE_TIMEOUT_MS = 5_000`），用于 `tools/list`、`tasks/state` 等 meta 查询。
- `withTimeout()` 包装 Promise，确保卡死的 child 不会拖垮主进程。资料来源：[src/node/proxy/mcp-multiplexer.js:30-50]()

这一层只关心"如何把消息可靠地送到下游"，不解析 method 语义，因此工具可见性、合并、过滤都在更上层完成。

## 3. ToolIndex：跨子服务器的工具缓存与检索

`ToolIndex` 是 `mcp-multiplexer` 与 HTTP handler 共享的只读缓存。它在 `rebuild(proxyManager)` 时遍历 `proxyManager.servers`，对每个公开 server 调用 `tools/list`，将 `{ tool, server }` 写入 `tools: Map<string, Entry>` 与 `tags: Map<string, string[]>`。资料来源：[src/node/proxy/tool-index.js:15-50]()

主要能力包括：

| 能力 | 描述 | 触发条件 |
|------|------|----------|
| `rebuild` | 重新拉取所有公开子服务器的工具清单 | 启动时、拓扑变化时（`CHILD_TOOLS_LIST_TIMEOUT_MS = 5_000`） |
| 关键词搜索 | 按 name/description 命中 | `discover_tools` 的 `query` 参数 |
| 标签过滤 | 命中 `tags` 索引 | `discover_tools` 的 `tags` 参数 |
| server 过滤 | 仅返回某 server 的工具 | `server` 字段 |

需要强调：未通过 `isPublicMcpToolServer()` 检查的 server（如 `agent-pool`）不会进入索引，从而不会暴露在 `tools/list` 给客户端。资料来源：[src/node/proxy/mcp-tool-visibility.js:1-50]()

## 4. Tool Multiplexer：Meta-Tools Gateway

`mcp-multiplexer.js` 是门户对外的"门面"。它没有把每个 child 的全部工具平铺出去，而是按优先级注册一组 portal 级工具，例如：

- `create_chat` / `resume_chat`：开启或恢复 UI 中的 Agent Chat 会话。
- `get_orchestrator_status`：返回活跃 agent 数量、可用标签、systemLoad、活跃 MCP client/proxy 遥测。
- `get_development_map`：默认返回"compact"精简开发地图；传入 `detail: "full"` 时返回 `subagentMap`、`taskMap`、`toolMap`、`activityMap`、`promptHintMap` 的完整结构，可能超出 agent 上下文预算。资料来源：[src/node/proxy/mcp-multiplexer.js:1-90]()

当请求进入 multiplexer 时，分发顺序大致为：

1. **Goal tools**：`isPortalGoalTool()` 命中后由 `handlePortalGoalTool()` 处理。
2. **Orchestrator tools**：`isPortalOrchestratorTool()` 命中后由 `handlePortalOrchestratorTool()` 处理。
3. **Delegate/Chat tools**：`isDelegateTool()` 命中后通过 `prepareDelegateTaskCall()` 解析 `resourceGroup`、`assignedAgent`、`parentChatId` 等参数。
4. **Memory tools**：`remember` / `recall` 直接走 `memory-store`。
5. **Child public tools**：最终 fallback 到 `proxyManager.requestFromChild()`。

资料来源：[src/node/proxy/mcp-multiplexer.js:1-90]() 与 [src/node/server/web-server.js:1-120]()

这种"先 portal meta，再 child public"的顺序确保了内部执行服务器（如 `agent-pool-mcp`）始终保留给门户自身使用，外部 MCP 客户端只能调用门户已经抽象过的入口。

## 5. HTTP 传输与可见性约束

`web-server.js` 在 `/mcp` 上提供 MCP Streamable HTTP 端点，并把 `mcpHttpHandler` 接到同一套转发逻辑上。该 handler 暴露了 `getTools`、`onToolCall`、`onResourcesList` 三个钩子，分别对应 `_collectAllTools`、`_routeToolCall`、`_aggregateResources`。资料来源：[src/node/server/web-server.js:1-120]()

可见性约束的核心来自 `mcp-tool-visibility.js`：

- `isPublicMcpToolServer(serverName)`：判断某个 child server 是否允许出现在公开 `tools/list` 中（例如 `agent-pool` 默认返回 `false`）。
- `isInternalMcpToolName(name)` / `internalMcpToolBlockedResult()`：即使客户端通过直接调用绕过 `tools/list`，某些内部工具名也会被显式拦截并返回 blocked 提示。
- `splitMcpHealthStatus()`：把 health status 拆分为 public 与 internal 两个层级，避免暴露内部 server 的细节。

资料来源：[src/node/proxy/mcp-tool-visibility.js:1-60]() 与 [src/node/server/web-server.js:40-120]()

此外，server 还支持 `serverDemoMode.enabled`，开启后 `/mcp`、`/mcp/message`、`/anthropic/*` 路径会返回 404，避免公网部署下被直接探测。资料来源：[src/node/server/web-server.js:20-60]()

## 常见失败模式与注意事项

- **Tool 数量膨胀**：`get_development_map(detail="full")` 返回的内容可能超出 agent context。默认应使用 `compact`，仅在调试时切换为 `full`。
- **重建超时**：`TOOL_INDEX_REBUILD_TIMEOUT_MS = 10_000`，若 child 在 10 秒内未返回 `tools/list`，整个 rebuild 会失败并被记入 `failures`。
- **HTTP 与 stdio 不一致**：HTTP 路径通过 `mcpHttpHandler` 复用同一份 multiplexer，但仍受 `serverDemoMode`、`networkAuth` 拦截；调试时务必确认 `networkAccess.lanEnabled` 与 token 配置。
- **重复启动 child**：`backend.js` 中 `proxyManager.startAllServers()` 在进程级别只调用一次；当以 detached singleton 模式运行时，多个 IDE 窗口共享同一进程，不会重复 fork child server。

## See Also

- 门户级 Meta-Tools：`portal-goal-tools.js`、`portal-orchestrator-tools.js`
- 工作流板：`workflow-board-tools.js` 与 `iso/workflow-board.js`
- Agent & Skill 解析：`agents/frontmatter.js`、`agents/agent-parser.js`
- 配置与市场：`server/marketplace-registry.js`、`~/.agent-portal/agent-portal.json`
- 总览：[README.md](https://github.com/rnd-pro/mcp-agent-portal/blob/main/README.md)

---

<a id='page-3'></a>

## Agent Runtime, Adapters & Skills System

### 相关页面

相关主题：[Overview & System Architecture](#page-1), [MCP Proxy, Multiplexing & Tool Routing](#page-2)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/node/agents/agent-parser.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/agents/agent-parser.js)
- [src/node/agents/frontmatter.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/agents/frontmatter.js)
- [src/node/adapters/index.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/adapters/index.js)
- [src/node/proxy/mcp-multiplexer.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/proxy/mcp-multiplexer.js)
- [src/node/proxy/portal-orchestrator-tools.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/proxy/portal-orchestrator-tools.js)
- [src/node/proxy/workflow-board-tools.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/proxy/workflow-board-tools.js)
- [src/node/proxy/orchestration-development-map.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/proxy/orchestration-development-map.js)
- [src/node/server/marketplace-registry.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/server/marketplace-registry.js)
- [src/node/server/demo-mode.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/server/demo-mode.js)
- [README.md](https://github.com/rnd-pro/mcp-agent-portal/blob/main/README.md)
- [package.json](https://github.com/rnd-pro/mcp-agent-portal/blob/main/package.json)
</details>

# Agent Runtime, Adapters & Skills System

## 1. 系统定位与总体架构

`mcp-agent-portal` 是一个统一的 Agent 与 MCP 控制平面（Unified Agent & MCP Control Plane），将项目本地的 Agent、技能、工作流与外部 MCP 工具市场聚合到同一运行时。`package.json` 中声明入口为 `bin/mcp-agent-portal.js`，并通过 `npm run build` / `npm start` 完成生产构建与启动 资料来源：[package.json:1-25]()。

运行时可视为三层：
- **适配器层（Adapters）**：把 Codex、Claude、Antigravity、Pool 等不同 LLM 提供方包装为统一对话接口；
- **解析与技能层（Agents & Skills）**：解析 `.agent-portal/agents/*.md` 中的 frontmatter 与技能引用；
- **代理与编排层（MCP Multiplexer / Orchestrator / Workflow Board）**：通过 Meta-Tool 暴露给上层 Agent，集中管理子任务、工具调用、看板与开发地图 资料来源：[README.md:1-30]()。

## 2. Agent 实体与技能解析

Agent 文件位于 `.agent-portal/agents/*.md`，由 `parseMarkdownFrontmatter` 拆分为 frontmatter 元数据与正文 资料来源：[src/node/agents/frontmatter.js:1-20]()。frontmatter 解析支持标量、内联数组、多行数组、内联对象与嵌套对象等 YAML 子集 资料来源：[src/node/agents/frontmatter.js:5-20]()。

`agent-parser.js` 在此基础上封装出**技能组合（Skill Composition）**机制：
- `skills: [X, Y]`：所列技能的内容会在 Agent 正文**之前**整体拼接；
- `{{skill:Z}}`：以行内占位符形式在正文**出现位置**就地展开 资料来源：[src/node/agents/agent-parser.js:1-15]()。

为减少磁盘 I/O，`getSkillMap` 会缓存目录扫描结果，2 秒内复用同一目录 资料来源：[src/node/agents/agent-parser.js:30-50]()。下图为 Agent 文件到最终 Prompt 的数据流：

```mermaid
flowchart LR
  A[".agent-portal/agents/*.md"] --> B["parseMarkdownFrontmatter"]
  B --> C{"meta + body"}
  C --> D["skills[] 预拼接"]
  C --> E["{{skill:Z}} 行内替换"]
  D --> F["最终 Agent Prompt"]
  E --> F
  F --> G["Adapter / Provider / Model"]
```

## 3. 适配器与资源组

`src/node/adapters/index.js` 的 `loadResourceGroupPreferences` 读取 `resource-groups.json`，抽取三类信息：
- 按 `provider` 汇总的 `preferredModel` 列表（`byProvider`）；
- 首个被发现的 `defaultModel`；
- 完整资源组（`groups`），包含 `rotation_mode`、`approval_mode`、`policy`、`max_agents`、`timeout` 等字段 资料来源：[src/node/adapters/index.js:1-40]()。

前端利用这些元数据构建**级联下拉选择**：Pool → Agent（来自 `.agent-portal/agents/`）→ Provider → Model → ChatType。同一 Adapter 既可作为根编排器使用，也可作为子聊天的 `agent_slug` 进行路由 资料来源：[src/node/proxy/mcp-multiplexer.js:create_chat]()。

## 4. MCP 多路复用、编排器与工作流看板

MCP Multiplexer 暴露一组 Meta-Tool：
- `create_chat`：在 UI 中即时创建聊天会话并返回 `activityMap`、`subagentMap`、`taskMap`、`toolMap`、`latestTools`、`promptHintMap` 等开发地图字段 资料来源：[src/node/proxy/mcp-multiplexer.js:create_chat]()；
- `discover_tools` / `call_tool`：按 `tag` 或 `server` 过滤后调用外部 MCP 工具，Agent Pool 的内部工具不参与 `call_tool` 资料来源：[src/node/proxy/mcp-multiplexer.js:discover_tools,call_tool]()；
- `get_portal_status`：返回已连接 MCP 服务、运行时健康度、tag 列表与 `systemLoad` 容量摘要；`detail:"full"` 时返回完整开发地图 资料来源：[src/node/proxy/mcp-multiplexer.js:get_portal_status]()。

`portal-orchestrator-tools.js` 负责在编排过程中检测“最终答复模板”（如以 “I now have … evidence.” 开头或 “Here is …” 结尾的句子），并对缺少 `requiredMarker` 的输出触发 `finalAnswerRepairHint` 修复流程 资料来源：[src/node/proxy/portal-orchestrator-tools.js:1-40]()。`orchestration-development-map.js` 在此基础上汇总 `subagentMap`、`taskMap`、`toolMap` 与 `promptHints`，产出 `latestTools` / `usage` / `liveness` 等结构化字段 资料来源：[src/node/proxy/orchestration-development-map.js:1-40]()。

`workflow-board-tools.js` 通过单一 `workflow_board` Meta-Tool 把列管理、卡片生命周期、自动化规则和事件查询统一到一致的入参模式，参数如 `approvalMode: 'yolo' | 'auto_edit' | 'plan'`、`expectedVersion`（乐观锁）以及 `entityRefs` 在所有 action 之间共享 资料来源：[src/node/proxy/workflow-board-tools.js:1-30]()。

外部 MCP 服务在 `marketplace-registry.js` 中按 `official` / `google` / `community` 等分类登记，包含 `command`、`args` 与 `envHint`，`envHint` 用于在面板中提示用户配置必要的环境变量 资料来源：[src/node/server/marketplace-registry.js:1-40]()。`demo-mode.js` 在公共/演示模式下限制可暴露的源码与资源类型（白名单 `src`、`public` 等目录、`.js`/`.mjs`/`.ts`/`.svg`/`.png` 等扩展名），并把项目根目录锁定到 `/workspace/agent-portal` 资料来源：[src/node/server/demo-mode.js:1-20]()。

## See Also

- [README.md](https://github.com/rnd-pro/mcp-agent-portal/blob/main/README.md)
- [package.json](https://github.com/rnd-pro/mcp-agent-portal/blob/main/package.json)
- [src/node/agents/frontmatter.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/agents/frontmatter.js)
- [src/node/adapters/index.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/adapters/index.js)
- [src/node/proxy/mcp-multiplexer.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/proxy/mcp-multiplexer.js)

---

<a id='page-4'></a>

## Web Dashboard & Frontend Panels

### 相关页面

相关主题：[MCP Proxy, Multiplexing & Tool Routing](#page-2), [Agent Runtime, Adapters & Skills System](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [web/index.html](https://github.com/rnd-pro/mcp-agent-portal/blob/main/web/index.html)
- [web/app.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/web/app.js)
- [web/dashboard.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/web/dashboard.js)
- [web/state.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/web/state.js)
- [web/router-registry.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/web/router-registry.js)
- [web/services/chat-ws-client.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/web/services/chat-ws-client.js)
- [src/node/server/web-server.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/server/web-server.js)
- [src/node/server/local-gateway.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/server/local-gateway.js)
- [src/node/server/demo-mode.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/server/demo-mode.js)
- [src/node/proxy/mcp-multiplexer.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/proxy/mcp-multiplexer.js)
- [src/node/server/xr-diagnostics-log.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/server/xr-diagnostics-log.js)
- [README.md](https://github.com/rnd-pro/mcp-agent-portal/blob/main/README.md)
</details>

# Web Dashboard & Frontend Panels

## 概述与定位

Web Dashboard（`web/index.html` + `web/app.js`）是 mcp-agent-portal 的浏览器入口，负责在单页中渲染项目文件、代码图谱、聊天会话、技能面板、运行时状态以及可选的 XR 沉浸式面板。门户前端通过静态资源服务器与本地网关拉取 `dist/web`（或 `web/`）下的资源，再由后端 Node 进程以 MCP 多路复用器（Multiplexer）和代理管理器为面板提供实时数据与公共工具调用。

- 静态资源入口约定见 [README.md](https://github.com/rnd-pro/mcp-agent-portal/blob/main/README.md)：生产构建产物位于 `dist/web`，缺失时回退至 `web/`；`AGENT_PORTAL_WEB_ROOT` 可在容器化构建中指向自定义 UI 目录。
- 前端模块按职责拆分：`web/dashboard.js` 负责面板装配，`web/state.js` 提供共享状态，`web/router-registry.js` 注册前端路由，`web/services/chat-ws-client.js` 处理与后端的实时消息流。

## 静态资源、网关与代理

[src/node/server/web-server.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/server/web-server.js) 中的 `serveStaticFile()` 负责从 `WEB_DIR`、各 `packages/` 子模块、已审核的 vendor 资源或共享 iso 助手目录中返回静态文件；当路径命中目录时自动追加 `index.html`，未命中时返回 403/404。无法识别的 `/api/*` 路径则经 `proxyToBackend()` 转发到名为 `serverName`（默认 `project-graph`）的子 MCP 服务进程。

[src/node/server/local-gateway.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/server/local-gateway.js) 是一段压缩的本地网关实现：
- 监听 `0.0.0.0` 并将端口写入运行时目录（`runtime/`），供子进程握手；
- 处理 HTTP 请求时若 `Accept` 包含 `text/html` 且存在前缀（prefix），会自动注入 `<base href="${prefix}/">` 以便子应用使用相对路径；
- WebSocket upgrade 仅代理到非 dashboard 后端，避免占用门户自身的长连接通道。

```mermaid
flowchart LR
  Browser[浏览器 / VR 头显] -->|HTTP/WS| WebServer[web-server.js]
  Browser -->|prefix 路由| Gateway[local-gateway.js]
  WebServer -->|dist/web 或 web/| Static[静态 UI 资源]
  Gateway -->|/api/*| Backend[project-graph / pool MCP]
  WebServer -->|XR 诊断| LogStore[xr-diagnostics-log.js]
  WebServer -->|演示数据| Demo[demo-mode.js]
  Backend --> Multiplexer[mcp-multiplexer.js]
  Multiplexer -->|门户元工具| Browser
```

## 演示模式与公共数据安全

为支持公开演示，门户在 [src/node/server/demo-mode.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/server/demo-mode.js) 中维护了一份白名单文件系统：
- `PUBLIC_ROOTS` 限制可浏览的顶级目录（如 `src/`、`web/`、`packages/`、`docs/` 等）；
- `BLOCKED_SEGMENTS` 显式屏蔽 `.env`、`.git`、`.ssh`、`node_modules`、`secrets`、`tmp` 等敏感段；
- `MAX_FILE_BYTES = 96 * 1024` 限制单文件大小；
- `PUBLIC_SOURCE_EXTENSIONS` 与 `PUBLIC_ASSET_EXTENSIONS` 分别控制源码（`.js/.ts/...`）与图片资源（`.svg/.png/...`）的可读性。

演示用的项目树（`DEMO_OPEN_LIBRARY_TREE` / `DEMO_AGENT_PORTAL_TREE`）和 `demoPortalFileContent()`、`demoWorkflowList()` 共同构成"安全沙箱"下的只读视图，确保公开部署不会泄露私有仓库或机密配置。资料来源：[src/node/server/demo-mode.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/server/demo-mode.js)。

## 门户侧的 MCP 元工具

前端面板通过 [src/node/proxy/mcp-multiplexer.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/proxy/mcp-multiplexer.js) 暴露的元工具与后端对话，核心条目包括：
- `get_portal_status`：返回已连接公共 MCP 服务、工具总数、`discover_tools` 可用标签、系统负载、活跃客户端/代理遥测以及开发图（`detail="compact"|"full"`）；
- `create_chat`：在门户 UI 中创建新会话（可指定 `adapter`、`agent`/`agent_slug`、`parentChatId`），返回结构化聊天元数据与 `promptHintMap`；
- `discover_tools`：按关键字、标签或服务器名检索已注册工具；
- `call_tool`：调用 `discover_tools` 选中的公共工具；Agent Pool 内部工具不通过此入口调用。

这些元工具的 `inputSchema` 描述了严格的参数约束，是前端面板（聊天、运行时、工具浏览）在协议层保持一致的关键。资料来源：[src/node/proxy/mcp-multiplexer.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/proxy/mcp-multiplexer.js)。

## XR 诊断与可视化面板

[src/node/server/xr-diagnostics-log.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/server/xr-diagnostics-log.js) 把 WebXR 会话的健康快照写入诊断日志，供面板实时显示：
- `htmlCanvasAvailability` / `htmlCanvasRecommendation` 反映 HTML-in-Canvas 纹理上传能力；
- `sceneQualityStatus`、`sceneQualityLowPanels` 记录场景质量降级状态；
- `readiness` / `visualReadiness` / `interactionReadiness` 三态汇总沉浸式会话的总体就绪度；
- `textureMode` / `textureStage` / `textureResolverStage` 严格模式的纹理解析状态；
- `deepGraphNodes` / `deepGraphEdges` 暴露图谱渲染规模。

依据 [README.md](https://github.com/rnd-pro/mcp-agent-portal/blob/main/README.md)，生产环境应通过 `npm run xr:production-smoke` 校验 `https://playground.rnd-pro.com/demos/agent-portal-vr/#spatial?project=agent-portal&target=graph&texture=strict` 处于 `production-spatial-ready` 状态，并在 `Panels live: 4/4`、`XR texture mode: strict` 下进入 `immersive-ar` 探针会话；严格模式下若 HTML-in-Canvas 不可用，前端必须隐藏未贴图的面板并显示 `XR texture gate: blocked:html-in-canvas-unsupported`，以避免向用户呈现空面板或材质回退面板。

## 常用配置

| 变量 / 选项 | 作用 | 出处 |
| --- | --- | --- |
| `AGENT_PORTAL_WEB_ROOT` | 自定义静态 UI 根目录（容器构建场景） | [README.md](https://github.com/rnd-pro/mcp-agent-portal/blob/main/README.md) |
| `AGENT_PORTAL_HTML_IN_CANVAS_ORIGIN_TRIAL_TOKEN` | 启用 HTML-in-Canvas 源试验；静态响应附带 `Origin-Trial` 头 | [README.md](https://github.com/rnd-pro/mcp-agent-portal/blob/main/README.md) |
| `dist/web` vs `web/` | 生产浏览器构建产物 vs 源模块开发目录 | [README.md](https://github.com/rnd-pro/mcp-agent-portal/blob/main/README.md)、[src/node/server/web-server.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/server/web-server.js) |
| 运行时端口文件 | local-gateway 写入端口文件供子进程握手 | [src/node/server/local-gateway.js](https://github.com/rnd-pro/mcp-agent-portal/blob/main/src/node/server/local-gateway.js) |

## 常见失败模式

1. **未构建直接启动**：`npm start` 找不到 `dist/web` 时会回退到 `web/`，如 `web/` 也不存在则 `serveStaticFile()` 返回 404，应先执行 `npm run build`。
2. **演示数据被截断**：`MAX_FILE_BYTES` 限制为 96 KiB，超大文件不会出现在公共浏览中；如需浏览大文件应改用非演示部署。
3. **严格模式下面板空白**：若 `htmlCanvas` 不可用且未隐藏 fallback 面板，前端会渲染空白；严格模式要求面板被隐藏并以诊断状态替代。
4. **WebSocket 被网关拦截**：`local-gateway.js` 仅代理非 dashboard 升级请求，仪表板自身的长连接不会被强制走网关。

## See Also

- [Project Graph MCP & Tools](./project-graph-mcp.md)
- [Agent Pool MCP](./agent-pool-mcp.md)
- [XR / WebXR 诊断](./xr-diagnostics.md)
- [Marketplace Registry](./marketplace-registry.md)

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：rnd-pro/mcp-agent-portal

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

## 1. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/rnd-pro/mcp-agent-portal | host_targets=mcp_host, claude, cursor

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/rnd-pro/mcp-agent-portal | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/rnd-pro/mcp-agent-portal | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/rnd-pro/mcp-agent-portal | no_demo; severity=medium

## 5. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/rnd-pro/mcp-agent-portal | no_demo; severity=medium

## 6. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/rnd-pro/mcp-agent-portal | issue_or_pr_quality=unknown

## 7. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/rnd-pro/mcp-agent-portal | release_recency=unknown

<!-- canonical_name: rnd-pro/mcp-agent-portal; human_manual_source: deepwiki_human_wiki -->