# https://github.com/eidetic-works/nucleus-mcp 项目说明书

生成时间：2026-06-27 10:12:59 UTC

## 目录

- [项目概述与系统架构](#page-1)
- [三大前沿:GROUND / ALIGN / COMPOUND 详解](#page-2)
- [数据管理、能力外观层与治理](#page-3)
- [部署、传输桥接、遥测与运维](#page-4)

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

## 项目概述与系统架构

### 相关页面

相关主题：[三大前沿:GROUND / ALIGN / COMPOUND 详解](#page-2), [部署、传输桥接、遥测与运维](#page-4)

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

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

- [README.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/README.md)
- [src/mcp_server_nucleus/runtime/capabilities/base.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/base.py)
- [src/mcp_server_nucleus/runtime/capabilities/feature_map.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/feature_map.py)
- [src/mcp_server_nucleus/runtime/capabilities/proof_system.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/proof_system.py)
- [src/mcp_server_nucleus/runtime/capabilities/synthesizer.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/synthesizer.py)
- [src/mcp_server_nucleus/runtime/capabilities/code_ops.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/code_ops.py)
- [src/mcp_server_nucleus/runtime/capabilities/agent_dashboard.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/agent_dashboard.py)
- [src/mcp_server_nucleus/runtime/capabilities/budget_ops.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/budget_ops.py)
- [src/mcp_server_nucleus/runtime/agents/oracle/manifest.json](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/agents/oracle/manifest.json)
- [src/mcp_server_nucleus/flywheel/__init__.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/__init__.py)
- [src/mcp_server_nucleus/flywheel/core.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/core.py)
- [src/mcp_server_nucleus/flywheel/dashboard.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/dashboard.py)
- [src/mcp_server_nucleus/flywheel/report.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/report.py)
- [src/mcp_server_nucleus/sessions/autonomous_wake.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/sessions/autonomous_wake.py)
- [src/mcp_server_nucleus/mirror/parsers/claude_code.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/mirror/parsers/claude_code.py)
- [examples/README.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/examples/README.md)
</details>

# 项目概述与系统架构

## 1. 项目定位与设计目标

`nucleus-mcp` 是一个基于 MCP（Model Context Protocol）协议的服务器项目，旨在为 AI 客户端（Claude Desktop、Cursor、Windsurf 等）提供持久化、可审计的"决策与记忆中枢"。项目以 MIT 协议开源，采用"文件即真相源"的存储哲学——所有决策、策略、计划都以纯 JSON 与 Markdown 形式落盘，不依赖嵌入向量，也不存在供应商锁定 [README.md:1-3]()。

核心理念围绕 **"Three Frontiers"**（三大前沿）展开，定义在 v1.8.0 版本中：

| 阶段 | 角色 | 行为 | 数据落点 |
|------|------|------|----------|
| **GROUND** | 机器验证 | 5 层执行验证：diff、语法、imports、测试、运行时 | `.brain/verification_log.jsonl` |
| **ALIGN** | 人类纠错 | 一键纠错 → 判决事件被记录 | `.brain/decisions/` |
| **COMPOUND** | 系统学习 | 错误自动生成 DPO 训练对 | `training/exports/` |

该闭环使每一次失败都转化为下一轮训练的养料，构成"AI 可靠性随时间复利增长"的核心机制 [README.md:30-44]()。

## 2. 总体架构

`nucleus-mcp` 内部划分为四大子系统：能力层（Capabilities）、代理层（Agents）、飞轮引擎（Flywheel）、会话层（Sessions）。整体结构如以下 Mermaid 图所示：

```mermaid
graph TB
    Client[MCP Client<br/>Claude Desktop / Cursor] -->|stdio| Server[nucleus-mcp Server]
    Server --> Caps[Capabilities 层]
    Server --> Agents[Agents 运行时]
    Server --> FW[Flywheel 引擎]
    Server --> Sess[Sessions / Mirror]
    Caps --> FO[feature_map<br/>proof_system]
    Caps --> CO[code_ops<br/>web_ops]
    Caps --> SO[synthesizer<br/>agent_dashboard]
    Caps --> BO[budget_ops]
    Agents --> Oracle[Oracle<br/>Antifragile Co-Founder]
    FW --> CSR[CSR 计数器]
    FW --> Tickets[pending_issues.jsonl]
    FW --> Reports[week-N.md / dashboard.html]
    Sess --> Wake[Autonomous Wake]
    Sess --> Mirror[claude_code parser]
    FW -.->|训练对导出| Train[DPO Training Pipeline]
```

### 2.1 能力层（Capabilities）

所有 MCP 工具必须实现 `Capability` 抽象基类，统一对外暴露 `name`、`description` 与 `get_tools()` 三要素 [base.py:3-19]()。该层按功能聚类：

- **feature_map**：登记产品特性（`product`、`status`、`how_to_test`、`expected_result` 等字段），支持按 `product`、`status`、`tag` 过滤 [feature_map.py:1-40]()。
- **proof_system**：为每个已发布功能生成 Markdown 格式的"举证文档"，含验证步骤、回滚策略、风险等级 [proof_system.py:1-60]()。
- **synthesizer**：调用 Google Gemini（`gemini-2.0-flash-exp`）合成"项目状态报告"，需环境变量 `GEMINI_API_KEY` [synthesizer.py:1-90]()。
- **code_ops**：提供 `code_read_file`、`code_write_file`、`code_run_command`、`code_list_files` 等基础文件与命令操作，含自愈路径解析 [code_ops.py:1-50]()。
- **agent_dashboard / budget_ops**：监控 Agent Runtime V2 的执行指标、限流统计与成本阈值 [agent_dashboard.py:1-50]()[budget_ops.py:1-30]()。

### 2.2 代理层（Agents）

代理是具备持久身份与可声明权限的智能体。以 `nucleus.core.oracle` 为例，其 manifest 声明：

- **生命周期**：`persistence: immortal`，表示无清理窗口 [oracle/manifest.json:18-21]()。
- **能力范围**：以 `scope` 标注、绑定文件系统路径与读写模式（`read_write`），通过 `${BRAIN_PATH}` 占位符解析 [oracle/manifest.json:7-17]()。

这种"路径即权限"的显式声明，使代理权限可被审计，与 v1.13.1 引入的隐私审计协议形成一致 [release v1.13.1]()。

### 2.3 飞轮引擎（Flywheel）

Flywheel 是整个项目的"复利引擎"，封装于 `src/mcp_server_nucleus/flywheel/` 子包。其稳定公开 API 包括 [flywheel/__init__.py:25-30]()：

```python
Flywheel, file_ticket, record_survived,
bump_survived, bump_unsurvived, read_csr,
render_dashboard_json, render_dashboard_html,
generate_week_report, curriculum_refresh
```

关键组件：

- **CSR（Claim Survival Rate）计数器**：每次成功 → `record_survived()`，每次失败 → `file_ticket()` 自动调用 `gh issue create` 提交工单 [flywheel/core.py:1-30]()。
- **Dashboard 渲染器**：将 CSR 状态与近期待办工单投影为 JSON 与自包含 HTML 页面，供 MCP resource 查询 [flywheel/dashboard.py:1-40]()。
- **周报生成器**：按 ISO 周编号读取 `pending_issues.jsonl`，覆盖写 `week-N.md` 但保留 append-only 工单日志 [flywheel/report.py:1-30]()。
- **课程刷新器**（`curriculum_refresh`）：闭合训练回路，将累积的纠正数据导出为 DPO 训练对。

### 2.4 会话与镜像层（Sessions / Mirror）

`sessions/autonomous_wake.py` 实现了"自主唤醒"客户端，向远端 nucleus-mcp-cloud 发起带 Bearer 认证的 `POST /v1/messages?beta=true` 请求；其内部扁平化 `mcp_servers` 列表为标准 `{name, description, input_schema}` 形式，并对畸形条目防御性跳过 [autonomous_wake.py:1-30]()。

`mirror/parsers/claude_code.py` 仅以**只读模式**打开 `.claude/` 下的会话 JSONL，逐行解析为 `EngramEvent` 流，并在 `JSONDecodeError` 时静默跳过，履行"记忆契约"中的不写原则 [claude_code.py:1-30]()。

## 3. 三大前沿闭环的运行时序

GROUND → ALIGN → COMPOUND 在代码层面的执行顺序至关重要：

1. **GROUND** 在 `code_ops` 执行后写 `.brain/verification_log.jsonl`；
2. **ALIGN** 通过人类发起的纠错调用记录判决；
3. **COMPOUND** 必须在训练器 `.train()` 调用**内部**触发，而非构造阶段——这正是社区报告的 BUG-001 教训：把 `np.savez()` 参考 logprob 缓存提前到 `DPOTrainer.__init__()` 之后、`.train()` 之前是无意义的，因为 TRL 的参考 logprob 预计算发生在 `.train()` 内部 [issue #8]()。

类似地，v1.13.1 之后的 `_PostPrecomputeGuard` 回调需为"已从缓存加载"分支输出明确日志，避免 BUG-002 中"沉默跳过"造成的用户困惑 [issue #9]()。

## 4. 常见使用模式与配置入口

- **CLI 入口**：`nucleus init` 首次运行时提示是否开启匿名遥测（默认 N，符合 v1.13.1 的 OPT-IN 政策）。
- **配置落点**：`nucleus.yaml` 中 `telemetry.anonymous.enabled` 显式值受尊重，不强制重提示。
- **示例程序**：`examples/` 提供 6 个演示脚本（`basic_usage.py`、`engram_demo.py`、`depth_tracker_demo.py`、`governance_demo.py`、`task_management_demo.py`、`mounter_demo.py`），需设置 `PYTHONPATH=src` 后运行 [examples/README.md:1-30]()。
- **辅助工具**：项目同捆独立工具 `nucleus-rabbithole`，提供 push/pop 深度栈与上下文切换抖动检测，零网络、零守护进程 [README.md:9-25]()。

---

## See Also

- [Three Frontiers（GROUD/ALIGN/COMPOUND）详解](#)
- [Flywheel 引擎与 CSR 计数器](#)
- [Capabilities 扩展开发指南](#)
- [MCP 客户端接入（QUICK_START）](#)
- [Relay v0.2 双向桥接守护进程](https://github.com/eidetic-works/nucleus-mcp/releases/tag/v1.13.0)

---

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

## 三大前沿:GROUND / ALIGN / COMPOUND 详解

### 相关页面

相关主题：[项目概述与系统架构](#page-1), [数据管理、能力外观层与治理](#page-3)

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

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

- [src/mcp_server_nucleus/runtime/ground.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/ground.py)
- [src/mcp_server_nucleus/runtime/align_ops.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/align_ops.py)
- [src/mcp_server_nucleus/runtime/execution_verifier.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/execution_verifier.py)
- [src/mcp_server_nucleus/runtime/ground_ops.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/ground_ops.py)
- [src/mcp_server_nucleus/runtime/engram_hooks.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/engram_hooks.py)
- [src/mcp_server_nucleus/runtime/delta_ops.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/delta_ops.py)
- [src/mcp_server_nucleus/flywheel/core.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/core.py)
- [src/mcp_server_nucleus/flywheel/__init__.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/__init__.py)
- [src/mcp_server_nucleus/flywheel/dashboard.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/dashboard.py)
- [src/mcp_server_nucleus/flywheel/report.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/report.py)
- [README.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/README.md)
</details>

# 三大前沿:GROUND / ALIGN / COMPOUND 详解

## 1. 设计理念与核心循环

`nucleus-mcp` 的"三大前沿(Three Frontiers)"是 v1.8.0 起确立的核心理念,其目标是让 AI 的可靠性随时间复利:`README.md` 明确将其归纳为 "Every AI output verified. Every correction recorded. Every mistake trains the system."([README.md:34-44](README.md))

三大前沿构成一条闭环:

```
  GROUND              ALIGN               COMPOUND
  ──────              ─────               ────────
  Machine verifies    Human corrects      System learns

  AI writes code  →  You fix a mistake →  Delta recorded
  GROUND checks   →  Verdict stored    →  DPO pair created
  Receipt logged  →  Event emitted     →  Training data grows
```

该闭环的飞轮实现位于 `src/mcp_server_nucleus/flywheel/` 子包,其包级 docstring 直接点明了核心循环:"Every failure → ticket → curriculum pair → next training run. Every success → CSR claim bump → dashboard delta."([flywheel/__init__.py:3-9](src/mcp_server_nucleus/flywheel/__init__.py))

## 2. GROUND — 机器验证层

GROUND 负责"机器自查":AI 产出代码后由系统执行 5 级执行验证(diff / syntax / imports / tests / runtime),验证通过后签发 receipt 并写入 `.brain/verification_log.jsonl`(参考 v1.8.0 发布说明)。

GROUND 与 Flywheel 的协作点在于:
- 每次成功验证 → 调用 `record_survived()` 增加 CSR(`claims_survived`)([flywheel/core.py:74-77](src/mcp_server_nucleus/flywheel/core.py))
- 每次失败 → 通过 `file_ticket()` 触发 6 步问责流程

`file_ticket()` 的 6 步动作(全为 best-effort、幂等)包括:1) 写入 `.brain/flywheel/pending_issues.jsonl`;2) CSR `unsurvived` 计数;3) 向 `training/exports/unified_dpo_pending.jsonl` 追加 DPO 训练种子;4) 追加到本周 `week-N.md`;5) 通过 `gh` CLI 创建 GitHub issue(若 `gh` 不可用则降级为排队);6) 写入 `.brain/flywheel/pending_tasks.jsonl`([flywheel/core.py:8-19](src/mcp_server_nucleus/flywheel/core.py))。

## 3. ALIGN — 人类纠偏层

ALIGN 是"人工一次调用纠偏"通道:当 AI 输出有误,用户通过 MCP 工具链提交修正,系统记录 verdict 并发出事件。该层的产出物是 delta(差异),下游被 COMPOUND 消费。

`flywheel/__init__.py` 导出的 `bump_survived`、`bump_unsurvived`、`read_csr` 三个函数即服务于 ALIGN 阶段对 CSR 计数器的双向写入([flywheel/__init__.py:24-31](src/mcp_server_nucleus/flywheel/__init__.py))。Brain 路径由环境变量 `NUCLEUS_BRAIN_PATH` 解析,缺省时回退到 `cwd/.brain`([flywheel/core.py:54-58](src/mcp_server_nucleus/flywheel/core.py))。

## 4. COMPOUND — 系统学习层

COMPOUND 负责把 GROUND/ALIGN 产生的 delta 转化为训练数据,并通过 CSR dashboard 量化收益。关键入口:

| 函数 | 作用 | 所在文件 |
|------|------|----------|
| `Flywheel.file_ticket()` | 失败问责,6 步动作 | flywheel/core.py |
| `Flywheel.record_survived()` | 成功签到,CSR bump | flywheel/core.py |
| `curriculum_refresh()` | 关闭训练回路,刷新 DPO 配对 | flywheel/__init__.py:5 |
| `render_dashboard_json()` | 看板 JSON 投影 | flywheel/dashboard.py |
| `render_dashboard_html()` | 自包含 HTML 看板 | flywheel/dashboard.py |
| `generate_week_report()` | 周报 markdown | flywheel/report.py |

Dashboard 同时展示 CSR 百分比、`pending_issues.jsonl` 行数(开放 tickets)、`pending_tasks.jsonl` 行数(开放 tasks)与 `unified_dpo_pending.jsonl` 行数(curriculum pairs),并以时间戳标注生成时刻([flywheel/dashboard.py:43-78](src/mcp_server_nucleus/flywheel/dashboard.py))。

## 5. 常见故障模式与社区已知问题

社区已记录的与 GROUND/ALIGN 直接相关的两个问题:

- **BUG-001(回调时序)**:在某 DPO 训练 notebook 中,`gc.collect()` 与 `np.savez()`(ref logprob 缓存)被放置在 `.train()` **之前**——但 TRL 的 ref logprob 预计算实际发生在 `.train()` 内部,而非 `DPOTrainer.__init__()` 阶段,导致两次 52 分钟的 T4 GPU 浪费。教训:GROUND 的执行验证必须严格对应事件真实发生点([issues/8](https://github.com/eidetic-works/nucleus-mcp/issues/8))。
- **BUG-002(静默跳过路径)**:`_PostPrecomputeGuard` 回调在 `_loaded_from_cache=True` 时静默跳过缓存保存,无任何日志。用户只能看到 `[OOM guard] GPU free after cleanup: 6.4 GB`,无法判断缓存究竟已保存还是被跳过——这与 GROUND"每条 receipt 都必须可审计"的原则相悖([issues/9](https://github.com/eidetic-works/nucleus-mcp/issues/9))。

## 6. 配置与隐私说明

v1.13.1 起,匿名遥测已切换为 OPT-IN:全新安装默认禁用,既有安装尊重 `nucleus.yaml` 中已有的 `telemetry.anonymous.enabled` 显式设置,首次 `nucleus init` 会提示 `Enable anonymous telemetry? [y/N]`,默认 **N**([v1.13.1](https://github.com/eidetic-works/nucleus-mcp/releases/tag/v1.13.1))。该变更不破坏 GROUND/ALIGN/COMPOUND 闭环,但用户在做 CSR 离线分析时应确认遥测开关状态,以避免本地的 CSR 信号被无意上送。

## See Also

- 飞轮公开 API 总览:[flywheel/__init__.py](src/mcp_server_nucleus/flywheel/__init__.py)
- Brain 路径与全局初始化:见 `NUCLEUS_BRAIN_PATH` 环境变量([flywheel/core.py:54-58](src/mcp_server_nucleus/flywheel/core.py))
- Oracle Agent 治理身份:[runtime/agents/oracle/manifest.json](src/mcp_server_nucleus/runtime/agents/oracle/manifest.json)
- v1.8.0 Three Frontiers 发布说明:[v1.8.0](https://github.com/eidetic-works/nucleus-mcp/releases/tag/v1.8.0)

---

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

## 数据管理、能力外观层与治理

### 相关页面

相关主题：[三大前沿:GROUND / ALIGN / COMPOUND 详解](#page-2), [部署、传输桥接、遥测与运维](#page-4)

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

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

- [src/mcp_server_nucleus/runtime/capabilities/base.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/base.py)
- [src/mcp_server_nucleus/runtime/capabilities/proof_system.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/proof_system.py)
- [src/mcp_server_nucleus/runtime/capabilities/feature_map.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/feature_map.py)
- [src/mcp_server_nucleus/runtime/capabilities/code_ops.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/code_ops.py)
- [src/mcp_server_nucleus/runtime/capabilities/web_ops.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/web_ops.py)
- [src/mcp_server_nucleus/runtime/capabilities/budget_ops.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/budget_ops.py)
- [src/mcp_server_nucleus/runtime/capabilities/agent_dashboard.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/agent_dashboard.py)
- [src/mcp_server_nucleus/runtime/capabilities/synthesizer.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/synthesizer.py)
- [src/mcp_server_nucleus/flywheel/__init__.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/__init__.py)
- [src/mcp_server_nucleus/flywheel/core.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/core.py)
- [src/mcp_server_nucleus/flywheel/dashboard.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/dashboard.py)
- [src/mcp_server_nucleus/flywheel/report.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/report.py)
- [src/mcp_server_nucleus/runtime/agents/oracle/manifest.json](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/agents/oracle/manifest.json)
- [README.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/README.md)
</details>

# 数据管理、能力外观层与治理

## 概述

`nucleus-mcp` 的核心架构围绕 v1.8.0 提出的"三大前沿"——**GROUND**（机器验证）、**ALIGN**（人类纠正）、**COMPOUND**（系统学习）构建，三者形成可靠性复利闭环（资料来源：[README.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/README.md)）。在此框架下，`runtime/capabilities/` 子包提供了统一的能力外观层（Capability Facade），将证明文档、功能地图、代码操作、网络访问、预算、代理仪表盘等异构领域封装为标准化的 MCP 工具；而 `flywheel/` 子包与 `runtime/agents/oracle/` 则构成治理层，通过 CSR（Claim Survival Rate）统计、问责票证、预算阈值与战略仿真实现对整个系统的可观测与可约束。

## 能力外观层

`Capability` 是所有领域适配器的抽象基类，要求实现 `name`、`description` 两个属性以及 `get_tools()` 与 `execute_tool(tool_name, args)` 两个方法（资料来源：[src/mcp_server_nucleus/runtime/capabilities/base.py:1-15]()）。这一薄接口让 MCP 服务端能够以一致的方式枚举与调度各业务域的工具，并对外屏蔽底层实现差异。

主要能力集群示例：

| 能力类 | 主要工具 | 职责 |
|--------|----------|------|
| ProofSystem | `brain_generate_proof` / `brain_get_proof` / `brain_list_proofs` | 维护 `.brain/proofs/` 下的 markdown 回滚文档 |
| FeatureMap | `brain_list_features` / `brain_get_feature` | 跨产品的功能登记、检索与状态过滤 |
| CodeOps | `code_read_file` / `code_write_file` / `code_run_command` | 带自愈路径解析的文件与 shell 操作 |
| WebOps | `web_search` / `web_read_page` | 基于 DuckDuckGo 的轻量网络访问 |
| BudgetOps | `brain_budget_status` / `brain_budget_set_daily` | 预算阈值与告警 |
| AgentDashboard | `brain_agent_dashboard` / `brain_agent_cancel` | Agent Runtime V2 指标与生命周期管理 |
| Synthesizer | `brain_synthesize_status_report` | 调用 Gemini 生成"国情咨文"式状态报告 |

（资料来源：[src/mcp_server_nucleus/runtime/capabilities/proof_system.py]()、[src/mcp_server_nucleus/runtime/capabilities/feature_map.py]()、[src/mcp_server_nucleus/runtime/capabilities/code_ops.py]()、[src/mcp_server_nucleus/runtime/capabilities/web_ops.py]()、[src/mcp_server_nucleus/runtime/capabilities/budget_ops.py]()、[src/mcp_server_nucleus/runtime/capabilities/agent_dashboard.py]()、[src/mcp_server_nucleus/runtime/capabilities/synthesizer.py]()）

```mermaid
flowchart LR
    Client[MCP 客户端] -->|tools/list| Facade[Capability 外观]
    Facade --> PS[ProofSystem]
    Facade --> FM[FeatureMap]
    Facade --> CO[CodeOps]
    Facade --> WO[WebOps]
    Facade --> BO[BudgetOps]
    Facade --> AD[AgentDashboard]
    Facade --> SY[Synthesizer]
    PS --> Disk[(.brain/proofs/*.md)]
    FM --> Disk
    CO --> FS[(本地文件系统)]
    WO --> Net[(HTTP / DuckDuckGo)]
    BO --> Mon[(budget monitor)]
    AD --> Mgr[(AgentRuntimeV2)]
    SY --> LLM[(Gemini API)]
```

## 数据管理

数据层以纯文件为主，刻意避免数据库与向量库依赖。证明系统将每次部署的回滚步骤、风险等级与影响文件写入 `proofs_dir/{feature_id}.md`，缺失时返回明确提示而非异常（资料来源：[src/mcp_server_nucleus/runtime/capabilities/proof_system.py:55-78]()）；FeatureMap 则要求 `product`、`name`、`version`、`how_to_test` 等结构化字段，用于跨产品检索与状态过滤（资料来源：[src/mcp_server_nucleus/runtime/capabilities/feature_map.py:9-22]()）。

Flywheel 在 `.brain/flywheel/` 下维护 `csr.json`、`pending_issues.jsonl` 与 `pending_tasks.jsonl`，构成可追加的训练数据池（资料来源：[src/mcp_server_nucleus/flywheel/__init__.py:1-31]()）。仪表盘模块把这些 JSONL 行数与 CSR 计数投影为 JSON 或自包含 HTML 页面，供 MCP 资源查询与公开查看（资料来源：[src/mcp_server_nucleus/flywheel/dashboard.py]()）。周报模块按 ISO 周索引生成 `week-N.md`，读取本周票证并保留追加日志（资料来源：[src/mcp_server_nucleus/flywheel/report.py]()）。Synthesizer 在生成报告前会先聚合 `.brain/task.md`、日志与愿景文件，再交给 Gemini 汇总成"已完成能力 / 运行中机制 / 在建工程"三段式（资料来源：[src/mcp_server_nucleus/runtime/capabilities/synthesizer.py:39-60]()）。

## 治理层

治理由三层叠加而成。**第一层——预算与资源闸门**：`BudgetOps` 暴露每日/每小时的 USD 阈值接口与 `brain_budget_reset`，由 `get_budget_monitor()` 单例支撑（资料来源：[src/mcp_server_nucleus/runtime/capabilities/budget_ops.py:34-58]()）。**第二层——代理运行时**：AgentDashboard 借助 `get_execution_manager()` 取得活跃代理、成本指标与速率限制状态，并提供 `brain_agent_cancel` / `brain_agent_cleanup` 干预手段（资料来源：[src/mcp_server_nucleus/runtime/capabilities/agent_dashboard.py:28-40]()）。**第三层——战略治理实体**：Oracle 代理声明 `strategy` 作用域，可读写 `PROTOCOL_THE_ORACLE.md`、`IMPLEMENTATION_PLAN_PHASE61.md` 与 `decisions/` 目录，生命周期为 *immortal*——这意味着它持久存在、不会被清理（资料来源：[src/mcp_server_nucleus/runtime/agents/oracle/manifest.json:1-27]()）。

Flywheel 提供问责闭环：失败时通过 `file_ticket()` 调用 `gh issue create` 提交带 `nucleus-bug,flywheel-auto` 标签的工单；成功时 `record_survived()` 提升 CSR 的 `claims_survived` 计数（资料来源：[src/mcp_server_nucleus/flywheel/core.py]()）。这一机制与 GROUND/ALIGN/COMPOUND 循环直接呼应（资料来源：[README.md]()）。

**已知治理盲点**：社区曾记录 BUG-001（DPO 训练中 ref-logprob 缓存的回调时机错误，将 `gc.collect()` 与 `np.savez()` 误置于 `.train()` 之前，导致 2 次 52 分钟的 T4 算力浪费）与 BUG-002（`_PostPrecomputeGuard` 在 `_loaded_from_cache=True` 时静默跳过保存路径、零日志输出）两类典型治理盲点。两者共同提示：**验证回调必须显式区分"命中 / 未命中 / 跳过"三种状态并写入日志**，否则 GROUND 层的回执将失去审计意义。

## 参见

- [README.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/README.md)
- [src/mcp_server_nucleus/flywheel/__init__.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/__init__.py)
- [src/mcp_server_nucleus/runtime/capabilities/base.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/base.py)
- [src/mcp_server_nucleus/runtime/agents/oracle/manifest.json](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/agents/oracle/manifest.json)
- [v1.8.0 — Three Frontiers 发布说明](https://github.com/eidetic-works/nucleus-mcp/releases/tag/v1.8.0)

---

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

## 部署、传输桥接、遥测与运维

### 相关页面

相关主题：[项目概述与系统架构](#page-1), [数据管理、能力外观层与治理](#page-3)

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

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

- [README.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/README.md)
- [src/mcp_server_nucleus/sessions/autonomous_wake.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/sessions/autonomous_wake.py)
- [src/mcp_server_nucleus/mirror/parsers/claude_code.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/mirror/parsers/claude_code.py)
- [src/mcp_server_nucleus/flywheel/__init__.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/__init__.py)
- [src/mcp_server_nucleus/flywheel/core.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/core.py)
- [src/mcp_server_nucleus/flywheel/dashboard.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/dashboard.py)
- [src/mcp_server_nucleus/flywheel/report.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/report.py)
- [src/mcp_server_nucleus/runtime/capabilities/budget_ops.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/budget_ops.py)
- [src/mcp_server_nucleus/runtime/capabilities/agent_dashboard.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/agent_dashboard.py)
- [src/mcp_server_nucleus/runtime/capabilities/synthesizer.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/synthesizer.py)
- [src/mcp_server_nucleus/runtime/capabilities/proof_system.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/proof_system.py)
- [src/mcp_server_nucleus/runtime/agents/oracle/manifest.json](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/agents/oracle/manifest.json)
- [examples/README.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/examples/README.md)
</details>

# 部署、传输桥接、遥测与运维

## 概述与系统定位

nucleus-mcp 是一个基于文件的 MCP（Model Context Protocol）服务器，以纯 JSON 与 Markdown 存储策略、决策与计划，让"决策一次写入、跨会话跨工具复用"成为现实。系统采用 MIT 许可、无嵌入、无供应商锁定的设计。资料来源：[README.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/README.md)

部署、传输桥接、遥测与运维四个领域共同构成 nucleus-mcp 的生产化支柱：部署决定 `.brain/` 目录如何在本地或云端落地；传输桥接决定会话、镜像、远端调用之间的数据通路；运维提供仪表盘、预算、状态报告等可观测能力；遥测则提供匿名可观测性与发布协议审计。

```mermaid
flowchart LR
    subgraph Deploy[部署层]
        D1[本地 .brain/]
        D2[Mac launchd]
        D3[Cloud 节点]
    end
    subgraph Transport[传输桥接层]
        T1[HTTP Bearer 会话]
        T2[Mirror 只读解析]
        T3[Relay v0.2 FS↔HTTP]
    end
    subgraph Ops[运维层]
        O1[Flywheel 闭环]
        O2[Budget / Agent Dashboard]
        O3[Synthesizer 状态报告]
        O4[Proof 审计链]
    end
    subgraph Telemetry[遥测层]
        E1[Opt-In 匿名遥测]
        E2[Release Protocol]
    end
    Deploy --> Transport --> Ops
    Ops --> Telemetry
    Telemetry --> Deploy
```

## 传输桥接：会话、镜像与远端调用

### HTTP 会话唤醒

`sessions/autonomous_wake.py` 承载远端 Bearer 鉴权的 HTTP 调用入口。`post_inference` 通过 `POST /v1/messages?beta=true` 提交推理请求并返回解析后的响应体。模块明确强调"伪匿名性"：bearer 令牌与负载正文内容**永远不会被写入日志**。资料来源：[src/mcp_server_nucleus/sessions/autonomous_wake.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/sessions/autonomous_wake.py)

### 镜像解析器与只读契约

`mirror/parsers/claude_code.py` 是 Claude Code 会话 JSONL 文件的解析器。其文档明确引用 `memory/feedback_never_prune_claude_paths.md` 中的"记忆契约"：解析器**只读打开**这些文件，绝不以写模式打开；监控器 `claude_code_watcher` 强制执行相同的契约。这种"只读"约束是传输桥接的关键，防止镜像组件在不知情时污染源数据。资料来源：[src/mcp_server_nucleus/mirror/parsers/claude_code.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/mirror/parsers/claude_code.py)

### 代理清单与权限路径

代理通过清单文件声明能力范围，例如 `runtime/agents/oracle/manifest.json` 中的 The Oracle 代理通过 `${BRAIN_PATH}/strategy` 等路径模板声明读/写能力，并定义 `persistence: immortal`、`cleanup: none` 等生命周期字段，明确部署与清理策略。资料来源：[src/mcp_server_nucleus/runtime/agents/oracle/manifest.json](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/agents/oracle/manifest.json)

## 运维：Flywheel、仪表盘与预算

### Flywheel 闭环引擎

Flywheel 子包是 nucleus-mcp 的"复利引擎"，核心理念是"每一次失败 → ticket → 训练对 → 下一次训练运行；每一次成功 → CSR claim 累加 → 仪表盘增量"。其公开 API 包括 `Flywheel`、`file_ticket`、`record_survived`、`render_dashboard_json`、`generate_week_report`、`curriculum_refresh` 等。资料来源：[src/mcp_server_nucleus/flywheel/__init__.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/__init__.py)

### 仪表盘与周报

| 文件 | 职责 | 输出形态 |
|---|---|---|
| `flywheel/dashboard.py` | CSR + 工单聚合 | JSON / HTML |
| `flywheel/report.py` | 周维度 Markdown 报告 | week-N.md |
| `flywheel/core.py` | 工单创建与 CSR bump | gh CLI / jsonl |

`flywheel/dashboard.py` 提供 JSON 与 HTML 渲染器，将 CSR 状态与近期工单聚合成 MCP 资源可查询视图；`flywheel/report.py` 按 ISO 周编号读取 `pending_issues.jsonl` 与 CSR 状态生成周报，保留 append-only 的 ticket 日志。`flywheel/core.py` 中的 `Flywheel.file_ticket` 在步骤失败时自动调用 `gh issue create` 创建带 `nucleus-bug,flywheel-auto` 标签的工单；当 `gh` 未安装或超时时优雅降级为 `queued: ...`。资料来源：[src/mcp_server_nucleus/flywheel/dashboard.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/dashboard.py)、[src/mcp_server_nucleus/flywheel/report.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/report.py)、[src/mcp_server_nucleus/flywheel/core.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/flywheel/core.py)

### 预算与代理仪表

`runtime/capabilities/budget_ops.py` 通过 MCP 工具暴露每日、每小时、单代理的预算阈值与重置能力；`runtime/capabilities/agent_dashboard.py` 提供代理执行仪表盘，涵盖指标、成本、活跃代理列表、取消与清理。两类能力均属于"Phase 68: Agent Runtime V2 Enhancement"。资料来源：[src/mcp_server_nucleus/runtime/capabilities/budget_ops.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/budget_ops.py)、[src/mcp_server_nucleus/runtime/capabilities/agent_dashboard.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/agent_dashboard.py)

## 状态报告与证明系统

`runtime/capabilities/synthesizer.py` 中的 `brain_synthesize_status_report` 是"行政大脑"能力，借助 Gemini 模型生成"国情咨文"式报告：聚合 `task.md`、日志与愿景文件，将系统状态分为"已完成能力"、"运行中机器"、"在建项目"三类，并明确 Mac 与 Cloud 的部署差异，最终给出下一步具体建议。当 `GEMINI_API_KEY` 缺失或 `google-genai` 未安装时优雅降级返回错误状态。资料来源：[src/mcp_server_nucleus/runtime/capabilities/synthesizer.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/synthesizer.py)

`runtime/capabilities/proof_system.py` 提供 `brain_generate_proof`、`brain_get_proof`、`brain_list_proofs` 三个 MCP 工具，可为每个功能生成包含部署 URL、变更文件、风险等级、回滚时间与策略的证明 Markdown，与 Flywheel 仪表盘共同形成审计证据链。资料来源：[src/mcp_server_nucleus/runtime/capabilities/proof_system.py](https://github.com/eidetic-works/nucleus-mcp/blob/main/src/mcp_server_nucleus/runtime/capabilities/proof_system.py)

## 部署示例与社区关注点

仓库在 `examples/` 目录下提供 Engram Ledger、Depth Tracker、Governance、Task Queue、Recursive Mounter 等示例脚本，运行前需设置 `PYTHONPATH=src` 后调用对应脚本；这些示例仅用于开发测试，生产环境应通过 MCP 客户端调用。资料来源：[examples/README.md](https://github.com/eidetic-works/nucleus-mcp/blob/main/examples/README.md)

社区近期关注的重点：

- **v1.13.1（2026-06-14）**：匿名遥测已切换为 opt-in，默认禁用；首次 `nucleus init` 会显式提示是否启用，已有安装尊重 `nucleus.yaml` 中 `telemetry.anonymous.enabled` 的显式配置，不再强制重新询问。
- **v1.13.0**：引入 Relay v0.2 双向 FS↔HTTP 桥接守护进程，提供 `nucleus-relay-bridge` 控制台脚本与 `deploy/mac/` launchd 模板，将本地 `.brain/relay/*` 镜像至远端 relay 服务。
- **BUG-001 / BUG-002**：DPO 训练笔记本在 `.train()` 之前放置 `gc.collect()` 与 `np.savez()` 缓存写入导致无效——TRL 的 ref logprob 预计算发生在 `.train()` 内部；`_PostPrecomputeGuard` 回调在 `_loaded_from_cache=True` 时静默跳过保存、无日志反馈。这两点提示运维层必须严格验证回调时序，并避免静默失败路径。

## See Also

- [README.md — Three Frontiers 与 nucleus-rabbithole 总览](README.md)
- [Capability 基类契约](src/mcp_server_nucleus/runtime/capabilities/base.py)
- [Flywheel 子包 API 索引](src/mcp_server_nucleus/flywheel/__init__.py)

---

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

---

## Doramagic 踩坑日志

项目：eidetic-works/nucleus-mcp

摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：BUG-001: GROUND/ALIGN missed execution-order verification (callback timing)。

## 1. 安装坑 · 来源证据：BUG-001: GROUND/ALIGN missed execution-order verification (callback timing)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：BUG-001: GROUND/ALIGN missed execution-order verification (callback timing)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/eidetic-works/nucleus-mcp/issues/8 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安装坑 · 来源证据：BUG-002: Silent skip path in ref logprob cache — no feedback when save is skipped

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：BUG-002: Silent skip path in ref logprob cache — no feedback when save is skipped
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/eidetic-works/nucleus-mcp/issues/9 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

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

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

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

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

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

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

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/eidetic-works/nucleus-mcp | no_demo; severity=medium

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

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

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

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

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

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

<!-- canonical_name: eidetic-works/nucleus-mcp; human_manual_source: deepwiki_human_wiki -->