1. 项目定位与设计目标

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

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

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

2. 总体架构

nucleus-mcp 内部划分为四大子系统：能力层（Capabilities）、代理层（Agents）、飞轮引擎（Flywheel）、会话层（Sessions）。整体结构如以下 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-50budget_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：

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。

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)

三大前沿构成一条闭环:

  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)

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)
• 每次失败 → 通过 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)。

3. ALIGN — 人类纠偏层

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

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

4. COMPOUND — 系统学习层

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

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

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)。
• BUG-002(静默跳过路径):_PostPrecomputeGuard 回调在 _loaded_from_cache=True 时静默跳过缓存保存,无任何日志。用户只能看到 [OOM guard] GPU free after cleanup: 6.4 GB,无法判断缓存究竟已保存还是被跳过——这与 GROUND"每条 receipt 都必须可审计"的原则相悖(issues/9)。

6. 配置与隐私说明

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

See Also

• 飞轮公开 API 总览:flywheel/__init__.py
• Brain 路径与全局初始化:见 NUCLEUS_BRAIN_PATH 环境变量(flywheel/core.py:54-58)
• Oracle Agent 治理身份:runtime/agents/oracle/manifest.json
• v1.8.0 Three Frontiers 发布说明:v1.8.0

概述

nucleus-mcp 的核心架构围绕 v1.8.0 提出的"三大前沿"——GROUND（机器验证）、ALIGN（人类纠正）、COMPOUND（系统学习）构建，三者形成可靠性复利闭环（资料来源：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 服务端能够以一致的方式枚举与调度各业务域的工具，并对外屏蔽底层实现差异。

主要能力集群示例：

（资料来源：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）

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
• src/mcp_server_nucleus/flywheel/__init__.py
• src/mcp_server_nucleus/runtime/capabilities/base.py
• src/mcp_server_nucleus/runtime/agents/oracle/manifest.json
• v1.8.0 — Three Frontiers 发布说明

概述与系统定位

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

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

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

镜像解析器与只读契约

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

代理清单与权限路径

代理通过清单文件声明能力范围，例如 runtime/agents/oracle/manifest.json 中的 The Oracle 代理通过 ${BRAIN_PATH}/strategy 等路径模板声明读/写能力，并定义 persistence: immortal、cleanup: none 等生命周期字段，明确部署与清理策略。资料来源：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

仪表盘与周报

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、src/mcp_server_nucleus/flywheel/report.py、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、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

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

部署示例与社区关注点

仓库在 examples/ 目录下提供 Engram Ledger、Depth Tracker、Governance、Task Queue、Recursive Mounter 等示例脚本，运行前需设置 PYTHONPATH=src 后调用对应脚本；这些示例仅用于开发测试，生产环境应通过 MCP 客户端调用。资料来源：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 总览
• Capability 基类契约
• Flywheel 子包 API 索引

Pitfall Log / 踩坑日志

项目：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