# https://github.com/HKUDS/OpenSpace 项目说明书

生成时间：2026-06-12 04:01:02 UTC

## 目录

- [OpenSpace 概览与系统架构](#page-overview)
- [自演化技能引擎与云端社区](#page-skill-engine)
- [MCP 集成、通信网关与前端 Dashboard](#page-mcp-communication)
- [多后端 Grounding 系统、安全沙箱、质量监控与运维排障](#page-grounding-ops)

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

## OpenSpace 概览与系统架构

### 相关页面

相关主题：[自演化技能引擎与云端社区](#page-skill-engine), [MCP 集成、通信网关与前端 Dashboard](#page-mcp-communication), [多后端 Grounding 系统、安全沙箱、质量监控与运维排障](#page-grounding-ops)

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

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

- [README.md](https://github.com/HKUDS/OpenSpace/blob/main/README.md)
- [openspace/__main__.py](https://github.com/HKUDS/OpenSpace/blob/main/openspace/__main__.py)
- [openspace/config/README.md](https://github.com/HKUDS/OpenSpace/blob/main/openspace/config/README.md)
- [openspace/tool_layer.py](https://github.com/HKUDS/OpenSpace/blob/main/openspace/tool_layer.py)
- [pyproject.toml](https://github.com/HKUDS/OpenSpace/blob/main/pyproject.toml)
- [frontend/README.md](https://github.com/HKUDS/OpenSpace/blob/main/frontend/README.md)
- [showcase/README.md](https://github.com/HKUDS/OpenSpace/blob/main/showcase/README.md)
- [showcase/my-daily-monitor/src/components/InsightsPanel.ts](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/src/components/InsightsPanel.ts)
- [frontend/src/hooks/useSkillEvolutionGraphData.ts](https://github.com/HKUDS/OpenSpace/blob/main/frontend/src/hooks/useSkillEvolutionGraphData.ts)
</details>

# OpenSpace 概览与系统架构

## 一、项目定位与核心目标

OpenSpace（[HKUDS/OpenSpace](https://github.com/HKUDS/OpenSpace)）定位为一个面向"自进化（Self-Evolving）"目标的智能体框架，强调**技能抽取（Skill Extraction）、技能复用与技能迭代**三大能力。项目以 Python 包形式发布，CLI 入口位于 [`openspace/__main__.py`](https://github.com/HKUDS/OpenSpace/blob/main/openspace/__main__.py)，用户通过 `openspace` 命令即可启动 Agent 会话、调用后端工具或接入 MCP（Model Context Protocol）服务。

OpenSpace 的设计哲学是"**以 Skill 为一等公民**"——Agent 在执行任务时不再依赖硬编码的工具链，而是从历史执行轨迹中动态发现、评估并组合已学习的技能。技能谱系数据通过 SQLite 进行持久化，前端则通过 [`useSkillEvolutionGraphData`](https://github.com/HKUDS/OpenSpace/blob/main/frontend/src/hooks/useSkillEvolutionGraphData.ts) 这类 Hook 渲染演化图谱，使用户能够直观看到每个技能的来源、评分、世代与有效率。

## 二、整体系统架构

OpenSpace 的运行时由四个主要层次组成：CLI 入口、Agent 核心循环、工具与后端层、以及可视化前端。

```mermaid
flowchart TB
    subgraph 用户层
        A[CLI: openspace/__main__.py]
        B[Dashboard Frontend<br/>frontend/]
    end

    subgraph Agent 核心
        C[Agent Loop / Skill Selector]
        D[Tool Layer<br/>openspace/tool_layer.py]
        E[Skill Registry & Lineage]
    end

    subgraph 后端能力
        F[Shell / GUI / Web / System Backend]
        G[MCP Client<br/>config_mcp.json]
        H[LLM via litellm]
    end

    A --> C
    B --> C
    C --> D
    C --> E
    D --> F
    D --> G
    C --> H
    E -.持久化.-> I[(SQLite<br/>openspace.db)]
    B --> I
```

**关键说明：**

- **CLI 入口**由 [`openspace/__main__.py`](https://github.com/HKUDS/OpenSpace/blob/main/openspace/__main__.py) 提供，负责解析子命令、加载环境变量并初始化 Agent 会话。
- **工具层** [`openspace/tool_layer.py`](https://github.com/HKUDS/OpenSpace/blob/main/openspace/tool_layer.py) 将 Shell、GUI、Web、System 等后端统一封装为可被 LLM 调用的工具集合，并通过 [`openspace/config/README.md`](https://github.com/HKUDS/OpenSpace/blob/main/openspace/config/README.md) 中描述的 `config_grounding.json` 控制后端作用域（`OPENSPACE_BACKEND_SCOPE`）。
- **技能存储**使用 SQLite，文件通常位于 `showcase/.openspace/openspace.db`，前端通过 `/api/v1` 代理读取并以演化图方式呈现（见 [showcase/README.md](https://github.com/HKUDS/OpenSpace/blob/main/showcase/README.md)）。
- **前端仪表盘** [`frontend/README.md`](https://github.com/HKUDS/OpenSpace/blob/main/frontend/README.md) 描述了开发模式：Vite 监听 `3888` 端口，通过 `VITE_API_PROXY_TARGET` 反向代理至后端 `7788` 端口。

## 三、配置与依赖

OpenSpace 的配置体系主要通过环境变量与 JSON 配置文件两层组合实现。常用变量如下（节选自 [`openspace/config/README.md`](https://github.com/HKUDS/OpenSpace/blob/main/openspace/config/README.md)）：

| 变量名 | 作用 | 默认值 |
|---|---|---|
| `OPENSPACE_MODEL` | 选择 LLM 模型 | `openrouter/anthropic/claude-sonnet-4.5` |
| `OPENSPACE_LLM_API_KEY` | Tier 1 覆盖密钥 | — |
| `OPENSPACE_API_KEY` | Cloud 服务密钥（[open-space.cloud](https://open-space.cloud)） | — |
| `OPENSPACE_MAX_ITERATIONS` | 单任务最大迭代次数 | `20` |
| `OPENSPACE_BACKEND_SCOPE` | 启用的后端列表 | `shell,gui,mcp,web,system` |
| `OPENSPACE_MCP_SERVERS_JSON` | MCP 服务器定义 | — |
| `OPENSPACE_LOG_LEVEL` | 日志级别 | `INFO` |

依赖方面，[`pyproject.toml`](https://github.com/HKUDS/OpenSpace/blob/main/pyproject.toml) 中 `litellm` 的版本被显式约束以规避供应链风险（[Issue #85](https://github.com/HKUDS/OpenSpace/issues/85)）。LLM 调用统一通过 `litellm` 抽象层，因此兼容 OpenAI、Anthropic、Ollama 等多种 provider。

## 四、社区关注与已知问题

根据社区反馈，OpenSpace 在以下场景中存在已知限制，部署时应重点关注：

1. **MCP 工具未被调用**（[Issue #84](https://github.com/HKUDS/OpenSpace/issues/84)）：当 OpenSpace 作为 MCP Server 被 OpenClaw 等宿主接入时，工具虽已注册但 Agent 倾向于不使用，导致技能评分始终为 0。建议在 prompt 中显式提示可用 MCP 工具。
2. **超时问题**（[Issue #73](https://github.com/HKUDS/OpenSpace/issues/73)）：OpenClaw + OpenSpace 联调时频繁触发任务超时。可通过调高 `OPENSPACE_MAX_ITERATIONS` 与宿主端超时阈值缓解。
3. **macOS launchd 兼容**（[Issue #87](https://github.com/HKUDS/OpenSpace/issues/87)）：交互式 `input()` 在无 TTY 的守护进程下会陷入 `EOFError` 循环并产生海量日志，需要在守护进程模式下禁用交互式提示。
4. **Windows 兼容性**（[Issue #90](https://github.com/HKUDS/OpenSpace/issues/90)）：`_is_pid_alive` 在 Windows 上不兼容 `signal.kill`，需要按平台分支处理。
5. **Cloud API Key 申请入口**（[Issue #88](https://github.com/HKUDS/OpenSpace/issues/88)）：部分用户在 `open-space.cloud` 找不到 API Key 申请菜单，需通过控制台工单流程获取。
6. **生态评估集成**（[Issue #82](https://github.com/HKUDS/OpenSpace/issues/82)）：社区建议引入 SOHH 等科学评估框架以量化技能有效性。

## See Also

- [OpenSpace 配置参考](README_config.md)
- [OpenSpace CLI 使用指南](cli_usage.md)
- [技能演化与评估机制](skill_evolution.md)
- [MCP 集成与外部工具](mcp_integration.md)

---

<a id='page-skill-engine'></a>

## 自演化技能引擎与云端社区

### 相关页面

相关主题：[OpenSpace 概览与系统架构](#page-overview), [多后端 Grounding 系统、安全沙箱、质量监控与运维排障](#page-grounding-ops)

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

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

- [openspace/skill_engine/registry.py](https://github.com/HKUDS/OpenSpace/blob/main/openspace/skill_engine/registry.py)
- [openspace/skill_engine/evolver.py](https://github.com/HKUDS/OpenSpace/blob/main/openspace/skill_engine/evolver.py)
- [openspace/skill_engine/analyzer.py](https://github.com/HKUDS/OpenSpace/blob/main/openspace/skill_engine/analyzer.py)
- [openspace/skill_engine/store.py](https://github.com/HKUDS/OpenSpace/blob/main/openspace/skill_engine/store.py)
- [openspace/skill_engine/patch.py](https://github.com/HKUDS/OpenSpace/blob/main/openspace/skill_engine/patch.py)
- [openspace/skill_engine/skill_ranker.py](https://github.com/HKUDS/OpenSpace/blob/main/openspace/skill_engine/skill_ranker.py)
- [showcase/README.md](https://github.com/HKUDS/OpenSpace/blob/main/showcase/README.md)
- [showcase/my-daily-monitor/src/services/social.ts](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/src/services/social.ts)
- [showcase/my-daily-monitor/server/routes/social.ts](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/server/routes/social.ts)
- [showcase/my-daily-monitor/src/components/SocialPanel.ts](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/src/components/SocialPanel.ts)
- [showcase/my-daily-monitor/src/components/InsightsPanel.ts](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/src/components/InsightsPanel.ts)
- [frontend/src/components/skill-detail/SkillVersionDrawer.tsx](https://github.com/HKUDS/OpenSpace/blob/main/frontend/src/components/skill-detail/SkillVersionDrawer.tsx)
- [frontend/src/i18n/zh.json](https://github.com/HKUDS/OpenSpace/blob/main/frontend/src/i18n/zh.json)
</details>

# 自演化技能引擎与云端社区

## 概述

OpenSpace 的核心定位是一个「自演化（Self-Evolving）技能引擎」，而非传统静态的提示工程库。它的特色在于：技能（Skill）本身会在多次任务执行中被分析、评分、变体生成、再评估，从而形成一条可追溯的版本谱系（lineage）。与此同时，OpenSpace 通过云端社区（Cloud Community）共享这些自演化出来的技能，使得来自不同部署、不同用户群体的 Agent 能够彼此复用最佳实践。

在官方 Showcase 项目 `my-daily-monitor` 中，零人工代码即可生成一个 29 个面板的个人仪表盘，其背后正是依靠「初始 6 个种子技能 → 领域适配 → 迭代演化」的流水线 资料来源：[showcase/README.md]()。这条流水线由前端 SkillVersionDrawer 中的版本谱系 UI 直接可视化展示 资料来源：[frontend/src/components/skill-detail/SkillVersionDrawer.tsx]()。

## 自演化引擎的架构

自演化引擎由若干解耦模块组成，每个模块职责清晰、可独立测试：

| 模块 | 文件 | 职责 |
|------|------|------|
| Registry（注册表） | `openspace/skill_engine/registry.py` | 管理 Skill 的注册、检索、版本指针 |
| Store（持久层） | `openspace/skill_engine/store.py` | 将技能元数据、执行记录持久化到 SQLite |
| Analyzer（分析器） | `openspace/skill_engine/analyzer.py` | 聚合执行日志，计算 effective / completion / fallback 等指标 |
| Evolver（演化器） | `openspace/skill_engine/evolver.py` | 根据分析结果触发 Patch 生成与版本晋升 |
| Patch（补丁器） | `openspace/skill_engine/patch.py` | 在现有 SKILL.md 上生成结构化变体 |
| Ranker（排序器） | `openspace/skill_engine/skill_ranker.py` | 在多个候选版本之间进行选择评分 |

```mermaid
flowchart LR
    A[任务执行] --> B[Store 记录]
    B --> C[Analyzer 聚合]
    C --> D{指标是否达标?}
    D -->|否| E[Evolver 触发 Patch]
    E --> F[Patch 生成变体]
    F --> G[Ranker 排序]
    G --> H[Registry 更新版本指针]
    D -->|是| H
    H --> I[云端社区共享]
    I --> J[其他 Agent 复用]
```

演化过程的入口位于 `evolver.py`，它读取 `analyzer.py` 输出的指标，决定是否需要基于 `patch.py` 生成新版本；新版本经 `skill_ranker.py` 排序后由 `registry.py` 提升为活跃版本 资料来源：[openspace/skill_engine/evolver.py]()。

## 云端社区与第三方数据接入

云端社区不仅承担技能共享，也是 Agent 运行时调用的实时数据通道。在 `my-daily-monitor` Showcase 中，社区面板（Tech Community Panel）聚合了 Hacker News、Reddit、V2EX 三大免费数据源：

- 客户端通过 `fetchCommunityPosts()` 调用 `/api/social?source=...`，使用 3 分钟内存缓存避免重复请求 资料来源：[showcase/my-daily-monitor/src/services/social.ts:32-40]()。
- 服务端 `handleSocialRequest()` 根据 `source` 参数路由到对应平台，HN/Reddit/V2EX 三个 fetcher 分别调用各自的免费 JSON 接口，并对每次请求设置 8 秒超时 资料来源：[showcase/my-daily-monitor/server/routes/social.ts:84-95]()。
- `InsightsPanel` 中的 AI 助手会根据关键词（如 "community"、"热帖"）路由到 community 工具，再把 HN/Reddit 帖子拼成 prompt 上下文 资料来源：[showcase/my-daily-monitor/src/components/InsightsPanel.ts]()。

值得注意的是，V2EX 数据源在当前提交中已被服务端注释禁用，原因是「content quality issues」 资料来源：[showcase/my-daily-monitor/server/routes/social.ts:90-92]()。

## 技能谱系可视化与多语言支持

前端 `SkillVersionDrawer` 把引擎产出的版本谱系渲染成抽屉式面板，关键指标包括：

- **活跃端点 / 未激活锚点**：通过 `activeVersions` 字段区分当前生效版本与历史版本 资料来源：[frontend/src/components/skill-detail/SkillVersionDrawer.tsx]()。
- **演化概览（Evolution Overview）**：显示最佳版本评分、平均评分、最大世代数 资料来源：[frontend/src/i18n/zh.json:drawer.evolutionOverview]()`。
- **执行质量（Execution Quality）**：进度条展示 effective_rate、completion_rate、applied_rate、fallback_rate 四个核心指标 资料来源：[frontend/src/components/skill-detail/SkillVersionDrawer.tsx]()`。

i18n 资源 `frontend/src/i18n/zh.json` 完整覆盖了上述字段的中文翻译，使得中文用户也能直观地审视自己技能的演化历史。

## 已知问题与社区讨论

自演化机制在实际运行中暴露出若干需要关注的边界情况：

1. **技能从未被调用**：在 OpenClaw v2026.4.24 + OpenSpace v1.26.0 的 MCP 集成中，Agent 虽已注册 Skill 工具，但调度器从未调用，导致 `total_selections` 长期为 0，所有技能评分为 0。资料来源：[Issue #84](https://github.com/HKUDS/OpenSpace/issues/84)
2. **MCP 超时**：当 OpenClaw 把任务委派给 OpenSpace MCP Server 时，常出现超过限制时间的错误，单独运行 OpenSpace 则正常。资料来源：[Issue #73](https://github.com/HKUDS/OpenSpace/issues/73)
3. **交互模式与 launchd 不兼容**：CLI 在 macOS launchd 后台运行时，因缺少 TTY 会陷入 `EOFError` 循环，CPU 100%、日志膨胀至 100GB+。资料来源：[Issue #87](https://github.com/HKUDS/OpenSpace/issues/87)
4. **API Key 入口缺失**：新用户期望在 `open-space.cloud` 找到 API Keys 菜单，但当前版本暂未开放自助创建。资料来源：[Issue #88](https://github.com/HKUDS/OpenSpace/issues/88)
5. **依赖安全**：建议将 `litellm` 的版本上限放宽到 `1.83.0+`，以跳过 PYSEC-2026-2 投毒版本（1.82.7/1.82.8）。资料来源：[Issue #85](https://github.com/HKUDS/OpenSpace/issues/85)
6. **Windows 兼容**：通信网关中 `_is_pid_alive` 函数的 POSIX 假设导致 Windows 启动失败。资料来源：[Issue #90](https://github.com/HKUDS/OpenSpace/issues/90)

## See Also

- [Showcase 项目与技能演化图谱](https://github.com/HKUDS/OpenSpace/blob/main/showcase/README.md)
- [OpenSpace Issue #84 — MCP 工具未被调用](https://github.com/HKUDS/OpenSpace/issues/84)
- [OpenSpace Issue #87 — launchd 兼容性问题](https://github.com/HKUDS/OpenSpace/issues/87)
- [OpenSpace Issue #90 — Windows 网关兼容性](https://github.com/HKUDS/OpenSpace/issues/90)

---

<a id='page-mcp-communication'></a>

## MCP 集成、通信网关与前端 Dashboard

### 相关页面

相关主题：[OpenSpace 概览与系统架构](#page-overview), [多后端 Grounding 系统、安全沙箱、质量监控与运维排障](#page-grounding-ops)

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

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

- [frontend/src/api/types.ts](https://github.com/HKUDS/OpenSpace/blob/main/frontend/src/api/types.ts)
- [frontend/src/components/skill-detail/SkillVersionDrawer.tsx](https://github.com/HKUDS/OpenSpace/blob/main/frontend/src/components/skill-detail/SkillVersionDrawer.tsx)
- [frontend/src/i18n/zh.json](https://github.com/HKUDS/OpenSpace/blob/main/frontend/src/i18n/zh.json)
- [frontend/src/index.css](https://github.com/HKUDS/OpenSpace/blob/main/frontend/src/index.css)
- [showcase/README.md](https://github.com/HKUDS/OpenSpace/blob/main/showcase/README.md)
- [showcase/my-daily-monitor/src/components/CommandPalette.ts](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/src/components/CommandPalette.ts)
- [showcase/my-daily-monitor/src/components/InsightsPanel.ts](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/src/components/InsightsPanel.ts)
- [showcase/my-daily-monitor/src/components/SocialPanel.ts](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/src/components/SocialPanel.ts)
- [showcase/my-daily-monitor/src/services/social.ts](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/src/services/social.ts)
- [showcase/my-daily-monitor/src/services/news.ts](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/src/services/news.ts)
- [showcase/my-daily-monitor/src/config/preferences.ts](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/src/config/preferences.ts)
- [showcase/my-daily-monitor/server/routes/social.ts](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/server/routes/social.ts)
</details>

# MCP 集成、通信网关与前端 Dashboard

## 1. 总体定位与子系统边界

OpenSpace 的对外能力由三块组成：作为 **MCP（Model Context Protocol）服务端** 暴露给上游 Agent 调用、通过 **通信网关（Communication Gateway）** 进行多进程 IPC 协调，以及使用 React/TypeScript 构建的 **前端 Dashboard** 来观察与回放运行结果。本页面不重新阐述 OpenSpace 的核心算法，而是聚焦于这三层之间的接口契约、目录结构与典型问题。

资料来源：[showcase/README.md](https://github.com/HKUDS/OpenSpace/blob/main/showcase/README.md)、[frontend/src/api/types.ts:1-90](https://github.com/HKUDS/OpenSpace/blob/main/frontend/src/api/types.ts)

## 2. 前端 Dashboard（`frontend/`）

前端 Dashboard 是人类操作员查看 OpenSpace 状态的主入口，基于 React + Vite，使用 `frontend/src/api/types.ts` 中定义的强类型 API 契约与后端通信。

### 2.1 数据契约

`Skill` 类型是页面渲染的核心：除了 `name`、`category`、`tags`、`score` 等基础字段外，还携带 `applied_rate`、`completion_rate`、`effective_rate`、`fallback_rate` 四个质量指标，以及 `recent_analyses`、`lineage_graph`、`critical_tools` 等扩展字段。这些指标在 `SkillVersionDrawer` 中以进度条形式呈现，便于回溯 Skill 的演化表现。

资料来源：[frontend/src/api/types.ts:1-90](https://github.com/HKUDS/OpenSpace/blob/main/frontend/src/api/types.ts)、[frontend/src/components/skill-detail/SkillVersionDrawer.tsx:1-30](https://github.com/HKUDS/OpenSpace/blob/main/frontend/src/components/skill-detail/SkillVersionDrawer.tsx)

### 2.2 国际化与样式

`frontend/src/i18n/zh.json` 提供了 `drawer`、`graph`、`diffViewer`、`workflows` 等命名空间，覆盖版本抽屉、谱系图、Diff 查看器与工作流页面。i18n 字符串以 `drawer.versionScore`、`drawer.executionQuality` 这种点路径组织。配套的 `frontend/src/index.css` 通过 CSS 变量（`--color-ink`、`--color-muted`、`--workflow-chip-bg` 等）定义主题。

资料来源：[frontend/src/i18n/zh.json](https://github.com/HKUDS/OpenSpace/blob/main/frontend/src/i18n/zh.json)、[frontend/src/index.css:1-40](https://github.com/HKUDS/OpenSpace/blob/main/frontend/src/index.css)

## 3. Showcase 仪表盘：`my-daily-monitor`

`showcase/my-daily-monitor` 是一个由 OpenSpace **零人工编码**生成的 TypeScript 仪表盘，作为前端 Dashboard 能力的活样本。

### 3.1 架构分层

```mermaid
graph TB
  subgraph Browser["浏览器"]
    P[Panel 组件层]
    S[Services 数据服务层]
  end
  subgraph Vite["Vite Dev Server"]
    M[vite-api-plugin.ts 中间件]
    R[server/routes/* API 路由]
  end
  P --> S --> M --> R
  R --> Ext[外部 HN/Reddit/GNews 等]
```

各 Panel（如 `SocialPanel`、`InsightsPanel`、`MyMonitorsPanel`）继承 `Panel` 基类，统一管理加载/错误态。Services 层使用 `createCircuitBreaker` 包裹 fetch，添加缓存与熔断。Vite 中间件转发到 `server/routes/` 下的真实路由，再聚合外部免费 API。

资料来源：[showcase/my-daily-monitor/src/components/SocialPanel.ts:1-30](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/src/components/SocialPanel.ts)、[showcase/my-daily-monitor/src/services/social.ts:1-25](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/src/services/social.ts)、[showcase/my-daily-monitor/server/routes/social.ts:1-25](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/server/routes/social.ts)

### 3.2 AI Agent 与命令面板

`InsightsPanel` 通过关键词匹配将用户查询路由到不同 Tool（天气、新闻等），并在缺失数据时诚实地提示用户在设置中补充密钥。`CommandPalette` 通过 `Cmd/Ctrl+K` 触发模糊搜索、键盘导航与最近命令持久化（`mdm-recent-commands`，最多 3 条）。

资料来源：[showcase/my-daily-monitor/src/components/InsightsPanel.ts:1-40](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/src/components/InsightsPanel.ts)、[showcase/my-daily-monitor/src/components/CommandPalette.ts:1-30](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/src/components/CommandPalette.ts)

### 3.3 配置入口

`showcase/my-daily-monitor/src/config/preferences.ts` 暴露了 `newsCategories`、`newsKeywords`、`githubRepos`、`feishuChatIds`、`refreshIntervalMs` 等偏好字段，并通过 `services/settings-store` 在运行时被读取。

资料来源：[showcase/my-daily-monitor/src/config/preferences.ts](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/src/config/preferences.ts)、[showcase/my-daily-monitor/src/services/news.ts:1-20](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/src/services/news.ts)

## 4. 已知问题与社区反馈

下列问题与 MCP/通信/前端三类子系统紧密相关，在排查时优先核对：

| 现象 | 根因方向 | 参考 |
|---|---|---|
| MCP 工具可用但 Agent 评分始终为 0 | Skill 注册未被调用或 metric 未上报 | [Issue #84](https://github.com/HKUDS/OpenSpace/issues/84) |
| OpenClaw 调用 MCP 频繁超时 | 单次任务执行时长超过上游 Agent 限流 | [Issue #73](https://github.com/HKUDS/OpenSpace/issues/73) |
| 在 launchd 下 CLI 进入 `EOFError` 死循环并产生百 GB 日志 | 交互模式 `input()` 无 TTY，需要守护进程兼容层 | [Issue #87](https://github.com/HKUDS/OpenSpace/issues/87) |
| 无法在 open-space.cloud 找到 API Key 入口 | 控制台未提供 Developer / API Keys 菜单 | [Issue #88](https://github.com/HKUDS/OpenSpace/issues/88) |
| Windows 通信网关启动失败（`WinError 87`） | `_is_pid_alive` 跨平台兼容性 | [Issue #90](https://github.com/HKUDS/OpenSpace/issues/90) |

当上游 Agent 反馈"MCP 工具存在但不调用"时，可结合前端 Dashboard 的 `Skill.applied_rate` 与 `effective_rate` 字段，确认 Skill 是否真的被加载与触发；这是排查 #84 一类问题的最快路径。

资料来源：[frontend/src/api/types.ts:1-90](https://github.com/HKUDS/OpenSpace/blob/main/frontend/src/api/types.ts)

## See Also

- [Skill 演化与版本谱系]()
- [Showcase: My Daily Monitor 详解]()
- [MCP Server 配置与排错]()

---

<a id='page-grounding-ops'></a>

## 多后端 Grounding 系统、安全沙箱、质量监控与运维排障

### 相关页面

相关主题：[OpenSpace 概览与系统架构](#page-overview), [自演化技能引擎与云端社区](#page-skill-engine), [MCP 集成、通信网关与前端 Dashboard](#page-mcp-communication)

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

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

- [openspace/config/README.md](https://github.com/HKUDS/OpenSpace/blob/main/openspace/config/README.md)
- [showcase/README.md](https://github.com/HKUDS/OpenSpace/blob/main/showcase/README.md)
- [frontend/src/components/skill-detail/SkillVersionDrawer.tsx](https://github.com/HKUDS/OpenSpace/blob/main/frontend/src/components/skill-detail/SkillVersionDrawer.tsx)
- [showcase/my-daily-monitor/src/services/social.ts](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/src/services/social.ts)
- [showcase/my-daily-monitor/src/components/SocialPanel.ts](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/src/components/SocialPanel.ts)
- [showcase/my-daily-monitor/src/components/InsightsPanel.ts](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/src/components/InsightsPanel.ts)
- [showcase/my-daily-monitor/src/components/CommandPalette.ts](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/src/components/CommandPalette.ts)
- [showcase/my-daily-monitor/src/services/news.ts](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/src/services/news.ts)
- [showcase/my-daily-monitor/server/routes/social.ts](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/server/routes/social.ts)
- [showcase/my-daily-monitor/src/config/preferences.ts](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/src/config/preferences.ts)
- [frontend/src/i18n/zh.json](https://github.com/HKUDS/OpenSpace/blob/main/frontend/src/i18n/zh.json)
</details>

# 多后端 Grounding 系统、安全沙箱、质量监控与运维排障

## 概述

OpenSpace 是一个面向"自演化 Agent"的开源框架,其核心由三层构成:多后端 Grounding 执行层(负责把抽象任务落到具体可运行环境)、安全沙箱层(隔离不可信代码与副作用)以及质量监控层(用指标驱动 Skill 的迭代淘汰)。`showcase/README.md` 明确指出,`showcase/my-daily-monitor/` 这个完整项目就是由 OpenSpace **零人工编码**自演化生成的产物,用于示范上述三个子系统如何在真实数据流中协同工作。本页围绕这三个子系统以及社区反馈的典型排障路径展开,资料来源:[showcase/README.md](https://github.com/HKUDS/OpenSpace/blob/main/showcase/README.md)。

## 多后端 Grounding 与执行模式

OpenSpace 的 Grounding 层通过 `config_grounding.json` 在多种后端之间路由任务,Shell 与 GUI 后端均支持 **Local** 与 **Server** 两种模式。Local 模式"零配置",适合本机开发;Server 模式需要先启动 `local_server`,适合远程 VM、隔离沙箱或多机部署,资料来源:[openspace/config/README.md:Execution Mode: Local vs Server](https://github.com/HKUDS/OpenSpace/blob/main/openspace/config/README.md)。

外部能力通过 MCP 协议接入,`config_mcp.json` 中以 `mcpServers` 字典声明下游服务(例如 GitHub、Slack、数据库),命令行/进程级均以 `npx -y @modelcontextprotocol/server-github` 形式挂载,token 等敏感信息从环境变量插值,资料来源:[openspace/config/README.md:MCP Servers](https://github.com/HKUDS/OpenSpace/blob/main/openspace/config/README.md)。运行期开关统一通过 `OPENSPACE_*` 环境变量控制,关键变量如下:

| 环境变量 | 作用 | 默认值 |
|---|---|---|
| `OPENSPACE_WORKSPACE` | 项目根目录,用于日志/工作区 | — |
| `OPENSPACE_ENABLE_RECORDING` | 是否记录执行轨迹 | `true` |
| `OPENSPACE_LOG_LEVEL` | 日志级别 | `INFO` |
| `OPENSPACE_MCP_SERVERS_JSON` | MCP 服务器定义(JSON) | — |
| `OPENSPACE_SHELL_CONDA_ENV` | Shell 后端使用的 Conda 环境 | — |

资料来源:[openspace/config/README.md:Environment Variables](https://github.com/HKUDS/OpenSpace/blob/main/openspace/config/README.md)。

```mermaid
flowchart LR
  A[Agent / MCP Client] --> B[Grounding 路由器]
  B --> C[Shell Backend]
  B --> D[GUI Backend]
  B --> E[MCP Client]
  C --> F{模式}
  F -- Local --> G[本机解释器]
  F -- Server --> H[local_server 远端]
  E --> I[GitHub / Slack / DB]
```

## 安全沙箱与质量监控

安全沙箱的目标是把不可信/未审计代码放到隔离环境中执行,例如远程 VM、容器或第三方隔离后端(配置层在 `config_grounding.json` 的 `"mode": "server"` 中体现),并结合 `OPENSPACE_SHELL_WORKING_DIR`、`OPENSPACE_SHELL_CONDA_ENV` 限定文件与依赖边界,资料来源:[openspace/config/README.md](https://github.com/HKUDS/OpenSpace/blob/main/openspace/config/README.md)。

质量监控以 SQLite 持久化的执行分析为底座,前端 `SkillVersionDrawer` 暴露的指标包括:

- `effective_rate` —— 实际生效占比,资料来源:[frontend/src/components/skill-detail/SkillVersionDrawer.tsx:ProgressBar effectiveRate](https://github.com/HKUDS/OpenSpace/blob/main/frontend/src/components/skill-detail/SkillVersionDrawer.tsx)
- `completion_rate` —— 任务完成率
- `applied_rate` —— 技能被复用的比例
- `fallback_rate` —— 失败回退率(以 `bg-danger` 红色高亮)
- `total_selections / total_applied / completions` —— 绝对计数

这些指标在 `frontend/src/i18n/zh.json` 中被本地化为"代表评分""活跃版本""平均评分"等概念,只有"完成率/有效率/应用率/回退率"同时达到阈值的版本,才会被记入演化图谱的活跃端点,资料来源:[frontend/src/i18n/zh.json:drawer.*](https://github.com/HKUDS/OpenSpace/blob/main/frontend/src/i18n/zh.json)。

## 运维排障与社区已知问题

社区工单中已经暴露了几类高频故障,运维侧可按以下路径处理:

1. **MCP 工具注册了但 Agent 始终不调用** —— Issue #84 报告 `execute_task` 等工具虽被注册,Skills 评分却全为 0,排障时应先确认 Prompt 中是否显式启用对应 skill,并校验 MCP server(例如 `streamable-http` 端口 8083)握手是否成功,资料来源:[Issue #84](https://github.com/HKUDS/OpenSpace/issues/84)。

2. **OpenClaw 调度 OpenSpace 任务超时** —— Issue #73 指出 OpenSpace 单独运行流畅,但经 OpenClaw 中转时频繁超出限时。常见原因是 `OPENSPACE_*` 环境变量未透传到子进程,需在 `openclaw.json` 的 MCP 段显式 `env` 注入,资料来源:[Issue #73](https://github.com/HKUDS/OpenSpace/issues/73)。

3. **macOS launchd 守护进程下交互模式死循环** —— Issue #87 报告 CLI 作为后台服务运行时,`input()` 因无 TTY 触发 `EOFError` 死循环,日志膨胀至 100GB+。解决方式是在 launchd plist 中将 `StandardIn` 指向 `/dev/null` 或关闭 `OPENSPACE_ENABLE_RECORDING` 之外的交互式 prompt,资料来源:[Issue #87](https://github.com/HKUDS/OpenSpace/issues/87)。

4. **Windows 通信网关启动失败** —— Issue #90 指出 `_is_pid_alive` 在 Windows 上因 `signal` 不支持导致 `OSError: [WinError 87]`,需替换为平台分支(使用 `psutil.pid_exists` 或任务列表查询),资料来源:[Issue #90](https://github.com/HKUDS/OpenSpace/issues/90)。

5. **依赖供应链风险** —— Issue #85 建议 `pyproject.toml` / `requirements.txt` 中将 `litellm` 上限放宽到 `>=1.83.0` 以避开 PYSEC-2026-2 污染版本(1.82.7/1.82.8),资料来源:[Issue #85](https://github.com/HKUDS/OpenSpace/issues/85)。

6. **Cloud 控制台缺少 API Key 入口** —— Issue #88 报告 `open-space.cloud` 个人页找不到 "API Keys / Developer" 菜单,需等待官方在个人设置中开放该入口,资料来源:[Issue #88](https://github.com/HKUDS/OpenSpace/issues/88)。

> 排障建议优先级:**先环境变量 → 再 MCP 握手 → 再沙箱模式(Local/Server)→ 最后质量指标**。`showcase/my-daily-monitor/src/config/preferences.ts` 中以集中字典管理 `refreshIntervalMs`、`aiSummaryEnabled` 等开关,是改写后再次自演化时的优先注入点,资料来源:[showcase/my-daily-monitor/src/config/preferences.ts](https://github.com/HKUDS/OpenSpace/blob/main/showcase/my-daily-monitor/src/config/preferences.ts)。

## See Also

- [OpenSpace 总览与 Skill 演化机制](https://github.com/HKUDS/OpenSpace)
- [showcase/my-daily-monitor 项目结构与运行说明](https://github.com/HKUDS/OpenSpace/blob/main/showcase/README.md)
- [配置与 MCP Server 注册](https://github.com/HKUDS/OpenSpace/blob/main/openspace/config/README.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：HKUDS/OpenSpace

摘要：发现 15 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：配置坑 - 来源证据：Agents have OpenSpace MCP tools available but never call them — all skills show 0 score。

## 1. 配置坑 · 来源证据：Agents have OpenSpace MCP tools available but never call them — all skills show 0 score

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Agents have OpenSpace MCP tools available but never call them — all skills show 0 score
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/HKUDS/OpenSpace/issues/84 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 2. 安全/权限坑 · 来源证据：Why it is smoothly to execute the task in the openspace lonely, however, when it comes to the openclaw with openspace,…

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Why it is smoothly to execute the task in the openspace lonely, however, when it comes to the openclaw with openspace, the mcp server always exceeds the limite…
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/HKUDS/OpenSpace/issues/73 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 安装坑 · 来源证据：[Bug] OpenSpace interactive mode incompatible with launchd — EOFError loop, 100% CPU, 100GB+ logs

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] OpenSpace interactive mode incompatible with launchd — EOFError loop, 100% CPU, 100GB+ logs
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/HKUDS/OpenSpace/issues/87 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

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

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

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

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

## 6. 运行坑 · 运行可能依赖外部服务

- 严重度：medium
- 证据强度：source_linked
- 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
- 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
- 证据：packet_text.keyword_scan | github_repo:1190363679 | https://github.com/HKUDS/OpenSpace | matched external service / cloud / webhook / database keyword

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

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

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | github_repo:1190363679 | https://github.com/HKUDS/OpenSpace | no_demo; severity=medium

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

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

## 10. 安全/权限坑 · 来源证据：Bump litellm pin to skip PYSEC-2026-2 (1.82.7+1.82.8) but allow 1.83.0+

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Bump litellm pin to skip PYSEC-2026-2 (1.82.7+1.82.8) but allow 1.83.0+
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/HKUDS/OpenSpace/issues/85 | 来源类型 github_issue 暴露的待验证使用条件。

## 11. 安全/权限坑 · 来源证据：No api keys

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：No api keys
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/HKUDS/OpenSpace/issues/88 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

## 12. 安全/权限坑 · 来源证据：[Recommendation] SOHH - Scientific Agent Evaluation Tool for OpenSpace Integration

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Recommendation] SOHH - Scientific Agent Evaluation Tool for OpenSpace Integration
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/HKUDS/OpenSpace/issues/82 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 13. 安全/权限坑 · 来源证据：[Windows] Communication gateway fails to start due to _is_pid_alive incompatibility

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Windows] Communication gateway fails to start due to _is_pid_alive incompatibility
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/HKUDS/OpenSpace/issues/90 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

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

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

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

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

<!-- canonical_name: HKUDS/OpenSpace; human_manual_source: deepwiki_human_wiki -->