内容
<p align="center">
<a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
</p>
<p align="center">
<img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/ollama-intern-mcp/readme.png" alt="Ollama Intern MCP" width="500">
</p>
<p align="center">
<a href="https://github.com/mcp-tool-shop-org/ollama-intern-mcp/actions"><img alt="CI" src="https://github.com/mcp-tool-shop-org/ollama-intern-mcp/actions/workflows/ci.yml/badge.svg"></a>
<a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
<a href="https://mcp-tool-shop-org.github.io/ollama-intern-mcp/"><img alt="Landing Page" src="https://img.shields.io/badge/landing-page-8b5cf6"></a>
<a href="https://mcp-tool-shop-org.github.io/ollama-intern-mcp/handbook/"><img alt="Handbook" src="https://img.shields.io/badge/handbook-docs-10b981"></a>
</p>
> **适用于 Claude Code 的本地实习生。** <!-- TOOL_COUNT:start -->44<!-- TOOL_COUNT:end --> 种工具，基于证据的简报，持久的产物。
一个 MCP 服务器，为 Claude Code 提供 **本地实习生**，具有规则、层级、办公桌和文件柜。Claude 选择 _工具_；工具选择 _层级_（即时 / 工作 / 深度 / 嵌入）；层级写入一个您可以下周打开的文件。
**还驱动 [Hermes Agent](https://github.com/NousResearch/hermes-agent) 在 `hermes3:8b`** — 验证的端到端 2026-04-19。默认的阶梯是 `hermes3:8b`；`qwen3:*` 是备用轨道。参见下面的 [与 Hermes 一起使用](#use-with-hermes)。
**硬件要求：** `hermes3:8b` 约 6 GB VRAM，或 CPU 推理约 16 GB RAM。有关完整分析，请参见 [手册/入门](https://mcp-tool-shop-org.github.io/ollama-intern-mcp/handbook/getting-started/#hardware-minimums)。
**未使用 Claude？** [`examples/`](./examples/) 目录中有一个最小的 Node.js 和 Python MCP 客户端，您可以通过 stdio 启动。另请参阅 [手册/与 Hermes 结合使用](https://mcp-tool-shop-org.github.io/ollama-intern-mcp/handbook/with-hermes/)。
**本地优先** — 在您选择加入之前，零网络外流。无遥测。无“自主”功能。每次调用都会显示其工作。可选的 [Ollama Cloud](#ollama-cloud-optional) 路由将 600B 类模型置于同一工具后面，当本地硬件成为瓶颈时 - 自动回落到本地。
---
## v2.9.0 中的新增内容
**云功能通道 — 跨家族验证通道，按需云升级，以及实现此功能的经济模型。** 本地优先功能保持不变：未设置密钥时，其行为与 v2.8.0 完全相同（零外流，无启动云探测）。
- **`ollama_verify_claims` — 跨家族验证。** `ollama_code_review` 生成发现；本功能对其进行 **裁决**。它在您的声明 + 证据上运行一个独立的 Ollama Cloud 旗舰小组（默认为 deepseek / kimi / glm），并返回每个声明的 CONFIRMED / REFUTED / NEEDS_REVIEW。聚合采用 lone-dissent-never-decides（≥2 个反对，≥2 个确认），每个陪审员都经过模型验证服务（本地备用或替代模型被排除，不被计数），并且输入声明在结构上被推理剥夺。诚实的上限是有文档记录的：CONFIRMED 是支持证据，而不是证明 - 可靠地标记重大错误，对前沿模型的微妙错误较弱。
- **每次调用云升级 + 待机模式。** 单独设置 `OLLAMA_API_KEY`（无需 `OLLAMA_CLOUD_PRIMARY`），您就处于 **待机状态**：本地优先，无外流，无启动探测 - 直到单个调用选择加入 `backend:'cloud'`。将单个高风险审查升级到 600B 模型，而无需将每个调用切换到云。第一次升级会在发生时公开显示出口；现在，调用 `model` 覆盖会直接运行云尝试。
- **`ollama_log_stats` — 衡量的经济效益，即口号所承诺的。** 无 LLM 汇总的 NDJSON 收据：云/本地分割，云→本地回落率，工具的 token 数，p50/p95 延迟，由 `since` 窗口限定。
有关详细信息，请参阅 [CHANGELOG.md](./CHANGELOG.md)。
## v2.8.0 中的新增内容
**可靠性、持久性和安全性强化 — 25 个修复程序，每个都是先测试后验证，并且跨家族验证。** 本地优先行为保持不变，没有删除任何工具合约；现有的调用者继续正常工作。承载负载的胜利：
- **不再无声的数据丢失。** `ollama_corpus_refresh` 期间的瞬时读取错误（Windows 文件锁定、杀毒软件阻止、编辑器的保存窗口）以前会使文件被归类为“丢失”并 **永久删除其索引内容**。现在，只有真正不存在的文件才会删除；瞬时错误会保留路径，标记为重试，并保留其块。
- **遵守其预算的并发性。** 层超时现在可以取消仍在排队获取许可证的调用（它过去会无限期挂起，而收据声称并非如此），并且 `ollama_chat` 最终通过超时/层缝隙路由 - 因此，一个卡住的本地生成不会阻塞所有工具，并且它实际上会在云优先模式下到达云。
- **云服务会降级而不是宕机。** 退休的云模型 ID 现在会回落到本地，并带有明确的 `cloud_model_missing` 原因和云特定的提示，而不是完全断电；断路器不会永久卡住；持续缺失的模型会停止为每个调用支付云往返的费用。
- **与其文档相匹配的安全表面。** `ollama_batch_proof_check` 现在真正强制执行 cwd 包含（带有新的操作员 env 能力 `INTERN_BATCH_PROOF_ALLOWED_ROOTS` 调用者无法扩大），提示注入净化器获得了覆盖范围 + 公开披露的上限，并且受保护路径的防护在 macOS 上也是不区分大小写的。
- **诚实的产物和收据。** 打包写入是原子的，从不无声地覆盖；降级信封报告实际使用的层；中断写入检测器捕获任何突变的撕裂写入；块 ID 不会在具有相同内容的文件之间发生冲突。依赖项审计完全清除（0 个漏洞）。
有关详细信息，请参阅 [CHANGELOG.md](./CHANGELOG.md)。
## v2.7.0 中的新增内容
**可选的 Ollama Cloud 路由 — 云优先，本地回落。** 使用密钥 + 标志选择加入，生成层路由到 600B 类云模型；嵌入保持本地；断路器在任何云失败时回落到您的本地配置文件。**默认关闭 — 除非您同时设置 `OLLAMA_API_KEY` 和 `OLLAMA_CLOUD_PRIMARY=1`，否则无外流。** 附加的次要版本 — v2.7.0 之前的调用者（以及未选择加入的调用者）看到字节相同的行为。
- **云优先的安全网。** `RoutingOllamaClient` 尝试云优先，并在超时 / 5xx / 429 / 网络时回落到本地配置文件。错误的密钥（401/403）通过粘性断路器公开显示，而不是无限期静默退化；退休/输入错误云模型 ID（404）也会显示。
- **从不静默降级。** 每个信封都有 `backend`（`cloud`|`local`）、`degraded` 和 `degrade_reason`，因此您始终知道何时获得大模型而不是本地模型。`backend_fallback` NDJSON 事件使云→本地回落率在 `ollama_log_tail` 中可见。
- **`ollama_doctor` 报告云身份验证 + 可达性** 作为一个单独的块；`ollama-intern-mcp doctor` 显示一个 `Cloud (primary)` 部分。
- 默认云模型在 v2.7.0 版本时为 `minimax-m3:cloud` *(自重新固定到 `qwen3-coder-next:cloud` — 一个思考的默认返回空回复的工具；请参阅 [环境变量表](#cloud-env-vars))*；通过 `INTERN_CLOUD_MODEL` / `INTERN_CLOUD_DEEP_MODEL` 按层覆盖。
## v2.6.0 中的新增内容
`ollama_extract` 上的每次调用层预算覆盖。附加的次要版本 — v2.6.0 之前的调用者保持不变。 [CHANGELOG.md](./CHANGELOG.md) 中有详细的条目。
- **`tier_budget_ms_override?: number` 架构字段在 `ollama_extract` 上（可选，限定 `[1, 600000]` 毫秒）。存在时，将覆盖运行器访问的每个层的预算，以便 `src/guardrails/timeouts.ts:61` 中的内部 `runWithTimeoutAndFallback` 机制遵循操作员提供的预算而不是配置文件默认值。级联（工作 -> 即时超时）仍然会触发；覆盖层统一控制每个级联跳跃。
- **为什么存在此功能。** 研究操作系统 R-018 包装器（v0.12.1）用 `Promise.race` 包装 MCP `callTool`，发现包装器的预算未达到内部层 — `DEV_RTX5080_TIMEOUTS.instant = 15_000` 在 15000ms 时继续触发 `TIER_TIMEOUT`，无论 180000ms 包装器预算如何。v2.6.0 提供 MCP 端的权威预算，以便操作员的 `--planner-timeout-ms` 标志（研究操作系统）最终控制内部层超时，如设计的那样。
- **保留默认行为。** 字段省略 = 配置文件默认值以字节相同的方式控制。v2.6.0 之前的调用者看到零变化。
- **R-010 回落原因正则表达式保留。** 服务器端 `TIER_TIMEOUT` 错误消息仍然与 `/elapsed=(\d+)ms/` + `/budget=(\d+)ms/` 匹配，以便 AI- advisor 在覆盖和默认路径上都能看到下游工作。
### 历史 — v2.4.0 功能
有关完整的 v2.4.0 条目，请参阅 [CHANGELOG.md](./CHANGELOG.md) 和 [docs/release-notes/v2.4.0.md](./docs/release-notes/v2.4.0.md)。
## v2.4.0 中的新增内容
配置文件系统上的每个层 `num_ctx`（上下文窗口）控制。附加的次要版本 — v2.3.0 调用者保持不变。 [CHANGELOG.md](./CHANGELOG.md) 和 [docs/release-notes/v2.4.0.md](./docs/release-notes/v2.4.0.md) 中有详细的条目。
- **`TierConfig.num_ctx` 映射（新增）** — 配置文件中可选的 `{ instant?, workhorse?, deep?, embed? }`。当为层设置时，MCP 服务器在路由到该层的每个 Ollama 生成/聊天请求上设置 `options.num_ctx = <value>`（初始 + 回落）。当未设置时，请求完全省略 `num_ctx`，以便 Ollama 使用其加载的模型默认值 — 保留 v2.3.0 行为。
- **新的信封字段 `num_ctx_used?: number`** — 仅当 MCP 服务器实际发送 `num_ctx` 时存在。无需推断默认值 — MCP 服务器不会查询 Ollama 的实际值。
- **配置文件默认值**：`dev-rtx5080` / `dev-rtx5080-qwen3` 配置文件自带 `instant: 4096`、`workhorse: 8192`、`deep`/`embed` 未设置。大小适合将 `hermes3:8b` 放入 RTX 5080 的 16GB VRAM 预算中以实现快速工具。`m5-max` 保留所有层未设置 — 128GB 统一内存无溢出问题。
- **关闭 v0.8.0 第 1 阶段诊断** — `hermes3:8b` 在默认 32K 上下文在 RTX 5080 上溢出到 CPU 并开始超时 `ollama_extract` 调用。v2.4.0 在配置文件层阻止这种情况。
### 每个层的 `num_ctx` 控制（v2.4.0 新增）
配置文件（`src/profiles.ts` 的摘录）：
```ts
"dev-rtx5080": {
tiers: {
instant: "hermes3:8b",
workhorse: "hermes3:8b",
deep: "hermes3:8b",
embed: "nomic-embed-text",
num_ctx: {
instant: 4096, // 快速分类/总结
workhorse: 8192, // 架构绑定提取 / 批量
// deep: 未设置 — 长上下文简报保持当前行为
// embed: 未设置 — 嵌入对上下文窗口没有压力
},
},
// ... 超时，预热
}
```
工作层调用的信封（例如 `ollama_extract`）：
```jsonc
{
"result": { /* 提取的数据 */ },
"tier_used": "workhorse",
"model": "hermes3:8b",
"num_ctx_used": 8192, // 存在，因为配置文件设置了 workhorse=8192
// ... 信封的其他部分保持不变
}
```
在 `m5-max`（或任何将层留空的配置文件）上，`num_ctx_used` 从信封中缺失，发送到 Ollama 的请求不包含 `num_ctx` 字段 — Ollama 使用其加载的模型默认值。
操作员通过选择/编辑配置文件进行调整；没有每个调用的 `num_ctx` 输入工具模式。如果未来的调用出现需求，模式遵循 v2.3.0 的 `model` 覆盖。
### 历史 — v2.3.0 功能
有关完整的 v2.3.0 条目，请参阅 [CHANGELOG.md](./CHANGELOG.md) 和 [docs/release-notes/v2.3.0.md](./docs/release-notes/v2.3.0.md)。
## v2.3.0 中的新增内容
LLM 支持的原子工具上的每次调用模型覆盖。附加的次要版本 — v2.2.0 调用者保持不变。 [CHANGELOG.md](./CHANGELOG.md) 和 [docs/release-notes/v2.3.0.md](./docs/release-notes/v2.3.0.md) 中有详细的条目。
- **8 个原子工具上的可选 `model: string` 输入** — `ollama_extract`、`ollama_classify`、`ollama_summarize_fast`、`ollama_summarize_deep`、`ollama_research`、`ollama_corpus_answer`、`ollama_chat`、`ollama_code_citation`. 工具的第一个尝试在层上运行针对调用者指定的模型；超时后，现有的 `TIER_FALLBACK` 级联解析更便宜层的模型（而不是调用者的覆盖）。复合/简报/打包工具故意 **不** 接受 `model` — 原子获得每个调用的控制，复合使用层级默认值。
- **新的信封字段 `model_requested?: string`** — 仅当提供了覆盖。校准感知型调用者比较 `model_requested` 与 `model` 以检测回落替换：`if (env.model_requested && env.model !== env.model_requested) { /* 替换 */}`。空/空白输入抛出 `ZodError` 进行模式解析，而不是静默回落。
- **错误修复 — `src/version.ts` 漂移。** 运行时 `VERSION` 常量现在从模块加载时的 `package.json` 读取；v2.1.0 和 v2.2.0 版本报告陈旧的 `"2.0.0"` 字符串标识。新 `tests/version.test.ts` 锁定 `VERSION === pkg.version`。
### 调用模型覆盖（v2.3.0 中新增）
```jsonc
{
"tool": "ollama_classify",
"arguments": {
"text": "patch null pointer in auth",
"labels": ["feat", "fix", "chore"],
"frame": "what is the change kind?",
"model": "hermes3:8b"
}
}
```
信封：
```jsonc
{
"result": { "label": "fix", "confidence": 0.9, "off_topic": false, ... },
"tier_used": "instant",
"model": "hermes3:8b",
"model_requested": "hermes3:8b", // 存在，因为提供了覆盖
// ... 信封的其他部分保持不变
}
```
如果工作线程/深度层超时，调用将级联到即时层，并且 `env.model` 将是即时层的解析模型，而 `env.fallback_from` 将是 `"workhorse"` — `env.model_requested` 仍将是 `"hermes3:8b"`，并且 `env.model !== env.model_requested` 是替换信号。覆盖不会被带入更便宜的层；所选模型可能根本不适合该层。
### 历史 — v2.2.0 功能
有关完整的 v2.2.0 条目，请参阅 [CHANGELOG.md](./CHANGELOG.md) 和 [docs/release-notes/v2.2.0.md](./docs/release-notes/v2.2.0.md)。
## v2.2.0 中的新增内容
本地证据工作角色合同：帧边界和结构化放弃。附加的次要版本 — v2.1.0 调用者保持不变。详细的条目在 [CHANGELOG.md](./CHANGELOG.md) 和 [docs/release-notes/v2.2.0.md](./docs/release-notes/v2.2.0.md)。
- **帧边界提取** 在 `ollama_extract`、`ollama_classify`、`ollama_summarize_fast`、`ollama_summarize_deep` — 可选的 `frame: string` 输入 + 结构化的 `frame_alignment` / `on_topic` / `frame_addressed` / `off_topic` 输出。非主题来源被标记，而不是改述为模式。
- **`ollama_research` 上的结构化放弃** — `weak` / `abstained` / `sources_address_question` 字段。空的 `citations[]` 和非空的 `answer` 不再是静默成功。
- **`ollama_corpus_answer` 上的主题阈值** — 可选的 `min_top_score`。低于该阈值，工具会短路并带有 `abstained: true`，跳过合成。每个引用的 `score` 现在使用每个引用的 `score`。
- **通过简报证据保留检索分数** — `corpusHitsToEvidence` 携带 `score`（和 `corpus_min_evidence_score` 旋钮在组装时过滤 `incident_brief` / `repo_brief` / `change_brief`）。
- **引用行范围边界** — `guardrails/citations.ts` 拒绝 `ollama_research` 和 `ollama_code_citation` 上的越界范围。
- **操作员合同文档纠正** — README `chunk_id`/`chunk_index` 修复，“验证服务器端” 重写，证据法部分限定，营销口号注释。
### 种子回归 — 验证
切片的合约是针对字面意思的研究操作系统新包失败进行验证的：arxiv 2112.10422（宇宙学标准计时器）在第一节框架 *"本地优先的工作流中，证据管理在本地优先和云LLM深度研究工作流中意味着什么？"* 之下 — 9/9 个模拟LLM合约测试确认离题源现在被遏制（`frame_alignment.on_topic = false` 在提取；`off_topic: true` 在分类；`frame_addressed: false` 在深度总结；`abstained: true` 在 `min_top_score` 设置的 corpus_answer 上）。
### 历史 — v2.1.0 功能
有关完整的 v2.1.0 条目，请参阅 [CHANGELOG.md](./CHANGELOG.md)。
## 架构概览
```mermaid
flowchart LR
Claude["Claude 代码<br/>(MCP 客户端)"]
MCP["ollama-intern-mcp<br/>服务器（stdio）"]
Ollama["Ollama 守护进程<br/>(127.0.0.1:11434)"]
Models[("Hermes 3 / Qwen 3<br/>nomic-embed-text")]
Corpus[("~/.ollama-intern/<br/>语料库/")]
Artifacts[("~/.ollama-intern/<br/>制品/")]
NDJSON[("~/.ollama-intern/<br/>log.ndjson")]
Guards{{"防护措施<br/>引用 · 禁止短语<br/>保护路径 · 置信度"}}
Claude -- "JSON-RPC via stdio" --> MCP
MCP --> Guards
MCP -- "/api/generate · /api/chat<br/>/api/embed · /api/ps · /api/tags" --> Ollama
Ollama --> Models
MCP --- Corpus
MCP --- Artifacts
MCP --> NDJSON
```
每个 Claude 工具调用都通过 stdio JSON-RPC 进入 MCP 服务器。服务器根据工具的 zod 模式验证调用，运行配置的防护措施（引用验证、禁止短语剥离、保护路径强制执行、置信度阈值），然后路由到确定性渲染器（制品层）或 Ollama HTTP 调用（其他层）。Ollama 守护进程永远不会看到用户提供的路径 - 只有模型层和准备好的提示。每个调用都在 `~/.ollama-intern/log.ndjson` 的 NDJSON 日志中追加一个结构化事件，`ollama_log_tail` 和您的 shell 可以读取它。
---
## 典型示例 - 一个调用，一个制品
```jsonc
// Claude → ollama-intern-mcp
{
"tool": "ollama_incident_pack",
"arguments": {
"title": "sprite pipeline 5 AM paging regression",
"logs": "[2026-04-16 05:07] worker-3 OOM killed\n[2026-04-16 05:07] ollama /api/ps reports evicted=true size=8.1GB\n...",
"source_paths": ["F:/AI/sprite-foundry/src/worker.ts", "memory/sprite-foundry-visual-mastery.md"]
}
}
```
返回一个指向磁盘上文件的信封：
```jsonc
{
"result": {
"pack": "incident",
"slug": "2026-04-16-sprite-pipeline-5-am-paging-regression",
"artifact_md": "~/.ollama-intern/artifacts/incident/2026-04-16-sprite-pipeline-5-am-paging-regression.md",
"artifact_json": "~/.ollama-intern/artifacts/incident/2026-04-16-sprite-pipeline-5-am-paging-regression.json",
"weak": false,
"evidence_count": 6,
"next_checks": ["residency.evicted across last 24h", "OLLAMA_MAX_LOADED_MODELS vs loaded size"]
},
"tier_used": "deep",
"model": "hermes3:8b",
"hardware_profile": "dev-rtx5080",
"tokens_in": 4180, "tokens_out": 612,
"elapsed_ms": 8410,
"residency": { "in_vram": true, "evicted": false }
}
```
→ `weak: false` 表示已组装 ≥2 个证据项；它不表示假设已被验证。参见下面的[证据法则](#证据法则)。
该 Markdown 文件是 intern 的桌面输出 - 标题、带有引用 ID 的证据块、调查 `next_checks`、`weak: true` 横幅（如果证据薄弱）。它是确定性的：渲染器是代码，而不是提示。（渲染器是确定性的；假设和表面的内容是生成的 - 将它们视为草稿，而不是已验证的。）打开它明天，diff 它下周，导出它到手册中，使用 `ollama_artifact_export_to_path`。
---
## 第二个示例 - 构建语料库，然后查询它
```jsonc
// 1. 在您的项目上构建一个持久、可搜索的语料库。
{ "tool": "ollama_corpus_index",
"arguments": { "name": "sprite-foundry",
"paths": ["F:/AI/sprite-foundry/src"],
"embed_model": "nomic-embed-text" } }
// → { chunks_written: 1204, paths_indexed: 312, failed_paths: [] }
// 2. 对它提出一个有证据约束的问题。
{ "tool": "ollama_corpus_answer",
"arguments": { "name": "sprite-foundry",
"query": "worker 如何处理 OOM 驱逐？",
"top_k": 8 } }
// → { answer: "...", citations: [{chunk_index, path}...], weak: false }
```
服务器验证引用身份和每个 `chunk_index` 是否在检索的命中范围内。它不证明每个生成的声明在语义上都得到引用块内容的支持 - 那是模型的责任，而弱检索仍然可以产生引用形答案。[手册/语料库](https://mcp-tool-shop-org.github.io/ollama-intern-mcp/handbook/corpora/)中有完整的演练。
---
## 帧边界提取（v2.2.0 新增）
`ollama_extract`、`ollama_classify`、`ollama_summarize_fast` 和 `ollama_summarize_deep` 接受一个可选的 `frame: string` 输入。帧命名源被要求回答的问题；模型被指示在源不涉及帧时放弃，而不是发出真实但不相关的内容。
```jsonc
{
"tool": "ollama_extract",
"arguments": {
"text": "<长源文档>",
"schema": { /* 您的字段 */ },
"frame": "章节目的 - 例如 'sprite worker 中的 OOM 驱逐行为'"
}
}
// → 结果包括 frame_alignment: { on_topic: boolean, reason: string, unaddressed_aspects: string[] }
```
如果省略 `frame`，则行为与 v2.1.0 不变。当提供时，`frame_alignment.on_topic = false` 表示提取的字段可能是源的真实内容，但与帧无关 - 将其视为与 `weak: true` 简报相同：有用，但在使用前请仔细检查。
---
## 弃用合同（v2.2.0 新增）
`ollama_research` 返回结构化的弃用字段：`weak: boolean`、`abstained: boolean`、`sources_address_question: boolean | null`。空的 `citations[]` 且非空的 `answer` 不再沉默 - `abstained: true` 表示模型拒绝合成，因为调用者提供的路径没有解决这个问题。将弃用视为成功，而不是失败：这是工具拒绝将弱检索变成权威输出。
`ollama_corpus_answer` 接受一个可选的 `min_top_score: number` 话题性阈值（0.0-1.0）。当查询的 top 检索分数低于 `min_top_score` 时，工具会短路并设置 `abstained: true`，跳过合成 - 防止“5 个离题块，分数 0.21 仍然驱动完整答案”的失败模式，而 v2.1.0 的 `weak: true` 规则无法捕获（`weak: true` 仅在 `hits.length < 2` 时触发）。将此与每个引用的 `score` 字段结合使用，该字段在每个引用上新建，以便直接从信封中审计检索质量。
---
## 这里的内容 - 四个层级， <!-- TOOL_COUNT:start -->44<!-- TOOL_COUNT:end --> 个工具
**任务型** 意味着每个工具都命名一个您会交给实习生的任务 - 分类此内容，提取那项内容，分类这些日志，草拟此发布说明，打包此事件。工具的输入是任务规范；输出是交付成果。没有通用的 `run_model` / `chat_with_llm` 原始操作在顶部。
| 层级 | 数量 | 这里有什么 |
|---|---|---|
| **原子** | 31 | 任务型基本操作。**原始 15 个：** `classify`、`extract`、`triage_logs`、`summarize_fast` / `deep`、`draft`、`research`、`corpus_search` / `answer` / `index` / `refresh` / `list`、`embed_search`、`embed`、`chat`。**+13 在 v2.1.0 中添加：** `doctor`、`log_tail`、`batch_proof_check`（运维）；`code_map`、`code_citation`、`multi_file_refactor_propose`、`refactor_plan`（重构）；`artifact_prune`、`hypothesis_drill`（制品/简报）；`corpus_health`、`corpus_amend`、`corpus_amend_history`、`corpus_rerank`（语料库）。**+1 审查原子：** `code_review`（结构化 PR 审查结果，工作量大；仅审查）。**+2 在 v2.9 中：** `verify_claims`（跨家族云旗舰面板裁决主张；需要云）；和 `log_stats`（将 NDJSON 收据汇总为测量的经济学 - 云/本地拆分，备用率，p50/p95 每工具；无模型调用）。批量原子（`classify`、`extract`、`triage_logs`）接受 `items: [{id, text}]`。 |
| **简报** | 3 | 有证据支持的结构化操作员简报。`incident_brief`、`repo_brief`、`change_brief`。每个主张都引用证据 ID；服务器端未知数被剥离。弱证据表面 `weak: true` 而不是伪叙述。 |
| **打包** | 3 | 固定管道复合作业，写入持久 Markdown + JSON 到 `~/.ollama-intern/artifacts/`。`incident_pack`、`repo_pack`、`change_pack`。确定性渲染器 - 无模型调用在制品形状上。 |
| **制品** | 7 | 连续性表面在打包输出上。`artifact_list` / `read` / `diff` / `export_to_path`，另外三个确定性片段：`incident_note`、`onboarding_section`、`release_note`。 |
总数：**31 原子 + 3 简报 + 3 打包 + 7 制品工具 = <!-- TOOL_COUNT:start -->44<!-- TOOL_COUNT:end -->**。
冻结行：
- 原子：冻结 **在 v2.1.0 处提升**（今天 31 个；+13 在 v2.1.0 功能传递中添加，+1 `code_review` 后来，+2 在 v2.9 中：`verify_claims`、`log_stats`）。新原子仍然需要审计证明的间隙，测试，文档页面和 CHANGELOG 条目 - 没有随意的添加。
- 打包在 3 处冻结。没有新的打包类型。
- 制品层冻结在 7 处。
完整的工具参考资料存放在[手册](https://mcp-tool-shop-org.github.io/ollama-intern-mcp/handbook/tools/)中。
---
## 安装
需要 [Ollama](https://ollama.com) 在本地运行和提取的层模型（参见下面的模型提取）。
### Claude 代码（推荐）
大多数用户通过将此添加到他们的Claude Code MCP服务器配置中来安装它 - 不需要全局安装。Claude Code 按需运行服务器 via `npx`：
```json
{
"mcpServers": {
"ollama-intern": {
"command": "npx",
"args": ["-y", "ollama-intern-mcp"],
"env": {
"OLLAMA_HOST": "http://127.0.0.1:11434",
"INTERN_PROFILE": "dev-rtx5080"
}
}
}
}
```
### 克劳德桌面
相同的块，写入 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）。
### 全局安装（高级）
仅当您希望二进制文件在您的 `PATH` 上用于超出 Claude Code 的临时使用时才需要：
```bash
npm install -g ollama-intern-mcp
```
### 与 Hermes 一起使用
此 MCP 已针对 `hermes3:8b` 在 Ollama 上（2026-04-19）与 [Hermes Agent](https://github.com/NousResearch/hermes-agent) 进行端到端验证。Hermes 是一个外部代理，它调用到此 MCP 的冻结原始表面 - 它进行规划，我们进行工作。
参考配置（此存储库中的 `hermes.config.example.yaml`）：
```yaml
model:
provider: custom
base_url: http://localhost:11434/v1
default: hermes3:8b
context_length: 65536 # Hermes requires 64K floor under model.*
providers:
local-ollama:
name: local-ollama
base_url: http://localhost:11434/v1
api_mode: openai_chat
api_key: ollama
model: hermes3:8b
mcp_servers:
ollama-intern:
command: npx
args: ["-y", "ollama-intern-mcp"],
env:
OLLAMA_HOST: http://localhost:11434
INTERN_PROFILE: dev-rtx5080
# hermes3:8b 是 v2.0.0 中的默认梯度，因此如果您正在固定不同的本地模型，则仅需要这些覆盖。
```
**提示形状很重要。** 命令式工具调用提示（“调用 X 并带有参数…”）是集成测试 - 它们给 8B 本地模型足够的脚手架来发出干净的 `tool_calls`。列表形式的多任务提示（“执行 A，然后 B，然后 C”）是容量基准测试，用于较大的模型；不要将 8B 上的列表形式失败解释为“线路已损坏”。参见[手册/与 Hermes](https://mcp-tool-shop-org.github.io/ollama-intern-mcp/handbook/with-hermes/)以获取完整的集成演练 + 已知传输问题（Ollama `/v1` 流 + openai-SDK 非流式 shim）。
### 模型提取
**默认开发配置文件（RTX 5080 16GB 及类似）：
```bash
ollama pull hermes3:8b
ollama pull nomic-embed-text
export OLLAMA_MAX_LOADED_MODELS=2
export OLLAMA_KEEP_ALIVE=-1
```
**Qwen 3 替代轨道（相同硬件，用于 Qwen 工具）：
```bash
ollama pull qwen3:8b
ollama pull qwen3:14b
ollama pull nomic-embed-text
export INTERN_PROFILE=dev-rtx5080-qwen3
```
**M5 Max 配置文件（128GB 统一内存）：
```bash
ollama pull qwen3:14b
ollama pull qwen3:32b
ollama pull nomic-embed-text
export INTERN_PROFILE=m5-max
```
每个层 env 变量（`INTERN_TIER_INSTANT`、`INTERN_TIER_WORKHORSE`、`INTERN_TIER_DEEP`、`INTERN_EMBED_MODEL`）仍然覆盖配置文件选择以进行一次性操作。
---
## 统一信封
```ts
{
result: <工具特定>,
tier_used: "instant" | "workhorse" | "deep" | "embed",
model: string,
hardware_profile: string, // "dev-rtx5080" | "dev-rtx5080-qwen3" | "m5-max"
tokens_in: number,
tokens_out: number,
elapsed_ms: number,
residency: {
in_vram: boolean,
size_bytes: number,
size_vram_bytes: number,
evicted: boolean
} | null
}
```
`residency` 来自 Ollama 的 `/api/ps`。当 `evicted: true` 或 `size_vram < size` 时，模型分页到磁盘，推理下降 5-10 倍 - 在用户界面上显示这一点，以便他们知道要重启 Ollama 或修剪加载的模型数量。
在 [Ollama Cloud](#ollama-cloud-可选) 模式下，信封还带有 `backend`（`"cloud"` | `"local"`）和云端转本地失败时，`degraded: true` + `degrade_reason`。这些字段在默认的本地唯一路径中 **不存在**，因此现有消费者不受影响。`residency` 为云端服务调用（无本地 VRAM 驻留状态）为 null。
每次调用都会记录为 NDJSON 行到 `~/.ollama-intern/log.ndjson`。按 `hardware_profile` 过滤以排除 dev 数字。
---
## 硬件配置
| 配置文件 | Instant | Workhorse | Deep | Embed |
|---|---|---|---|---|
| **`dev-rtx5080`** （默认）| hermes3 8B | hermes3 8B | hermes3 8B | nomic-embed-text |
| `dev-rtx5080-qwen3` | qwen3 8B | qwen3 8B | qwen3 14B | nomic-embed-text |
| `m5-max` | qwen3 14B | qwen3 14B | qwen3 32B | nomic-embed-text |
**默认开发** 折叠所有三个工作层级到 `hermes3:8b` - 验证 Hermes Agent 集成路径。相同模型顶部到底部意味着只有一个提取内容，一个驻留成本，一个需要理解的行为集。用户更喜欢 Qwen 3（带有 `THINK_BY_SHAPE` 管道）选择进入 `dev-rtx5080-qwen3`。`m5-max` 是为统一内存大小写的 Qwen 3 梯度。
---
## Ollama Cloud（可选）
本地 8B 模型是大多数人遇到的硬件瓶颈。 [Ollama Cloud](https://ollama.com/cloud) 在 **相同** `/api/*` 表面下提供 600B 级模型，因此您可以将重型工具路由到更强大的模型并释放本地 VRAM - 同时将本地保留为始终在线的备用。
**这是可选的，默认情况下关闭。** 如果没有设置密钥，软件包保持本地优先，**零外联** - 任何选择加入的人都不会受到影响。 有两种选择加入的方式：
- **云端优先**（如下）：设置 *both* `OLLAMA_CLOUD_PRIMARY=1` 和 `OLLAMA_API_KEY` - 生成层路由到云端，本地备用。
- **云端备用**（v2.9）：仅设置 `OLLAMA_API_KEY` - 只要有一个调用显式要求升级，使用 `backend: "cloud"`，所有操作都保持本地（仍然没有外联，不是甚至启动探测）。参见 [云端备用和按调用升级](#云端备用和按调用升级)。
```json
{
"mcpServers": {
"ollama-intern": {
"command": "npx",
"args": ["-y", "ollama-intern-mcp"],
"env": {
"OLLAMA_CLOUD_PRIMARY": "1",
"OLLAMA_API_KEY": "sk-...your-key...",
"INTERN_PROFILE": "dev-rtx5080"
}
}
}
}
```
> **密钥是运行时环境变量，不是 CI 秘密。** GitHub Actions 秘密仅在 CI 运行中可见 - 它永远不会到达正在运行的服务器。 在 [ollama.com/settings/keys](https://ollama.com/settings/keys) 处创建密钥并将其放入 MCP 客户端的 `env` 块中（或您的 shell 环境中）。
**路由方式。** 当云端开启时，生成层（instant / workhorse / deep）前往云端模型；**嵌入始终保持本地**（Ollama Cloud 不提供嵌入模型，因此语料库/嵌入工具不受影响）。故障转移电路尝试云端优先，并在超时/5xx/429/网络错误时回退到本地配置文件。坏密钥（401/403）触发一个 *sticky* 分隔器，该分隔器大声显示而不是静默降级。本地配置文件（`INTERN_PROFILE`）是备用梯度，因此请保持其模型加载。
**你永远不会被静默降级。** 每个信封报告哪个后端提供服务：
```ts
{ ...envelope, backend: "cloud" | "local", degraded?: true, degrade_reason?: "cloud_timeout" | "cloud_5xx" | "cloud_rate_limited" | "cloud_unreachable" | "cloud_auth_failed" | "circuit_open" }
```
每当发生云端到本地的故障转移时，`backend_fallback` 行会出现在 `~/.ollama-intern/log.ndjson` 中（`ollama_log_tail --filter_kind backend_fallback`），`ollama-intern-mcp doctor` 显示一个包含模式、可用性和身份验证状态的 **Cloud（primary | standby）** 块。
### 云备份与逐案升级
设置 `OLLAMA_API_KEY` **而未设置** `OLLAMA_CLOUD_PRIMARY` 会启用**备份模式**：路由保持本地优先，任何请求都不会离开机器，直到某个调用携带 `backend: "cloud"`（在 `ollama_chat` 中暴露，内部由 `ollama_verify_claims` 使用）。该调用会升级到云模型，具备相同的断路器 + 本地回退机制和相同的信封来源；其他调用仍保持本地。**首次**升级的调用会打印一条包含主机名的.stderr 消息，并向 NDJSON 日志写入一条 `cloud_egress` 记录 — 只有在发生时才会披露出口，而不仅仅是在文档中。
机械强制执行以下规则：
- 没有密钥 → `backend: "cloud"` 失败，返回 `CLOUD_NOT_CONFIGURED`。在声称升级的情况下，它**绝不会**被本地模型无声地提供服务。
- 备份模式 + 没有指令 → 本地，零出口（启动时也不会探测云主机）。
- 在云优先模式下，`backend: "local"` 将一个调用固定在本地 — 相反的逃生口。
- 调用级别的 `model` 重写现在可以直接使用云路径（以前会被层→云模型映射覆盖），因此基于收据的编排器可以为每个调用指定确切的云模型。
主要的消费者是 **`ollama_verify_claims`**：用 3 个模型的跨家族云面板（默认 `deepseek-v4-pro:cloud` / `kimi-k2.7-code:cloud` / `glm-5.2:cloud`）来审理声明/发现 - 独立裁决从不决定，服务模型检查每个评审员，并在面板变薄时提供诚实的 `weak` 标志。来自面板对前沿模型作者声明的确认是*支持证据，而不是证明* — 面板可靠地捕获粗大错误，但在微妙错误上较弱。参见 [手册页面](https://mcp-tool-shop-org.github.io/ollama-intern-mcp/handbook/tools/verify-claims/)。
**延迟 vs 质量**。大型云模型运行速度比本地 8B 模型慢得多（数秒，而不是毫秒） — 质量升级，而不是速度升级。云层使用慷慨的超时阶梯（默认为 instant 30s / workhorse 120s / deep 300s）。
### 云环境变量
| 变量 | 默认值 | 目的 |
|---|---|---|
| `OLLAMA_CLOUD_PRIMARY` | _(未设置)_ | **云优先开关**。`1`/`true`/`yes`/`on` 将生成层路由到云。未设置且有密钥 = **备份模式**（本地优先，仅逐案升级）。未设置且无密钥 = 仅本地，零出口。 |
| `OLLAMA_API_KEY` | _(未设置)_ | Ollama Cloud 的 Bearer 密钥。单独设置它会启用**备份模式**；当启用 `OLLAMA_CLOUD_PRIMARY` 时**必填**（如果缺少，则在启动时快速失败）。 |
| `OLLAMA_CLOUD_HOST` | `https://ollama.com` | 云基站主机。 |
| `INTERN_CLOUD_MODEL` | `qwen3-coder-next:cloud` | 用于 instant + workhorse + deep 的云模型。保持默认**非思考** — 这里的思考模型会消耗短输出预算（将大型推理器放在下面的深层覆盖）。 |
| `INTERN_CLOUD_DEEP_MODEL` | _(= `INTERN_CLOUD_MODEL`)_ | 可选的仅深层覆盖，例如 `deepseek-v3.1:671b`。 |
| `INTERN_CLOUD_TIMEOUT_{INSTANT,WORKHORSE,DEEP}_MS` | `30000`/`120000`/`300000` | 每个层级的云尝试超时。 |
| `INTERN_CLOUD_NUM_CTX` | `32768` | 云调用的上下文窗口上限（云按 GPU 时间计费；上限控制成本）。 |
> **模型可用性变化**。Ollama 在服务器端轮换/淘汰云 ID。截至 2026-07，`qwen3-coder-next:cloud`（非思考默认）和思考旗舰 `deepseek-v4-pro:cloud` / `kimi-k2.7-code:cloud` / `glm-5.2:cloud` 是当前的；在固定 ID 之前，请查看 [ollama.com/search?c=cloud](https://ollama.com/search?c=cloud)。退役的 ID 会明显降级（`cloud_model_missing`），绝不会无声无息。
**隐私注意**。路由到 Ollama Cloud 会将提示发送给第三方。Ollama 的 [隐私政策](https://ollama.com/privacy) 指出，云提示会暂时处理，不会在请求后保留，也不会用于训练 — 但这仍然是出口，因此是选择加入并披露的。仅本地模式（默认）不会发送任何数据。
---
## 证据法则
这些法则在服务器上强制执行，而不是在提示中：
- **需要引用**。每个简要声明都引用一个证据 ID。
- **未知 ID 在服务器端被剥离**。引用证据包中不存在的 ID 的模型会在结果返回前丢弃这些 ID 并发出警告。
- **ID 验证，而不是内容验证**。服务器检查每个引用的 `evidence_ref` 是否指向组装集中的真实证据 ID。它**不**验证声明文本是否可从引用的证据中推导出来 — 那是模型的任务，薄弱的简要声明有时包含有效引用的不支持声明。使用 `weak: true` + 覆盖范围注释 + 包含的 `excerpt` 字段进行抽样检查。
- **弱势是弱势**。薄弱证据用 `weak: true` 标记覆盖范围注释。绝不会伪造为假叙述。
- **调查性质，而不是规定性质**。仅限 `next_checks` / `read_next` / `likely_breakpoints`。提示禁止“应用此修复”。
- **确定性渲染器**。工件 Markdown 形状是代码，而不是提示。`draft` 保留用于模型措辞重要的散文。
- **仅限相同包的差异**。跨包 `artifact_diff` 被大声拒绝；有效载荷保持不同。
---
## 工件与连续性
软件包写入 `~/.ollama-intern/artifacts/{incident,repo,change}/<slug>.(md|json)`。工件层为您提供连续性表面，而不将此工具转变为文件管理工具：
- `artifact_list` — 元数据索引，仅限按包、日期、slug 通配符过滤
- `artifact_read` — 按 `{pack, slug}` 或 `{json_path}` 类型读取
- `artifact_diff` — 结构化同包比较；表面弱翻转
- `artifact_export_to_path` — 将现有工件（带有出处头）写入调用者声明的 `allowed_roots`。除非 `overwrite: true`，否则拒绝现有文件。
- `artifact_incident_note_snippet` — 操作员注释片段
- `artifact_onboarding_section_snippet` — 手册片段
- `artifact_release_note_snippet` — 草稿发布注释片段
此层级中没有模型调用。所有内容都从存储的内容中渲染。
---
## 威胁模型与遥测
**触及的数据：** 调用者明确给出的文件路径（`ollama_research`，语料库工具），内联文本，以及调用者要求写入的工件 `~/.ollama-intern/artifacts/` 或调用者声明的 `allowed_roots`。
**未触及的数据：** `source_paths` / `allowed_roots` 之外的数据。`..` 在规范化前被拒绝。`artifact_export_to_path` 除非 `overwrite: true`，否则拒绝现有文件。针对受保护路径（`memory/`、`.claude/`、`docs/canon/` 等）的草稿需要明确的 `confirm_write: true`，在服务器端强制执行。
**网络出口：** **默认关闭**。开箱即用，唯一的外发流量是到本地 Ollama HTTP 端点 — 没有云调用，没有更新 ping，没有崩溃报告。**例外：** 如果您启用 [Ollama Cloud](#ollama-cloud-optional)（`OLLAMA_CLOUD_PRIMARY=1` + `OLLAMA_API_KEY`），则生成层级的提示会通过 HTTPS 使用 Bearer 密钥发送到 `ollama.com`。这是明确的、披露的，除非您设置两个变量，否则不会出口；嵌入仍然不会离开设备。参见 [SECURITY.md](SECURITY.md) §11。
**遥测：** **无**。每个调用都记录为 `~/.ollama-intern/log.ndjson` 上的一个 NDJSON 行。服务器本身不会向任何地方发送数据。
**错误：** 结构化形状 `{ code, message, hint, retryable }`。堆栈跟踪绝不会通过工具结果暴露。
完整策略：[SECURITY.md](SECURITY.md)。
---
## 标准
按照 [Shipcheck](https://github.com/mcp-tool-shop-org/shipcheck) 标准构建。A-D 级别的硬性门槛均已通过；参见 [SHIP_GATE.md](SHIP_GATE.md) 和 [SCORECARD.md](SCORE CARD.md)。
- **A. 安全** — SECURITY.md，威胁模型，无遥测，路径安全，`confirm_write` 保护路径
- **B. 错误** — 结构化形状适用于所有工具结果；无原始堆栈
- **C. 文档** — README 当前，CHANGELOG，LICENSE；工具模式自我文档
- **D. 清洁度** — `npm run verify`（完整的 vitest 套件），CI 依赖扫描，Dependabot，锁定文件，`engines.node`
---
## 路线图（强化，而不是范围扩展）
- **第一阶段 — 委托主干** ✓ 已交付：原子表面，统一信封，分层路由，防护栏
- **第二阶段 — 真相主干** ✓ 已交付：模式 v2 分段，BM25 + RRF，实时语料库，证据支持的简报，检索评估包
- **第三阶段 — 包和工件主干** ✓ 已交付：具有持久工件和连续性层的固定管道包
- **第四阶段 — 采用主干** ✓ v2.0.1：三阶段健康检查强化语料库（TOCTOU，50 MB 文件上限，符号链接拒绝，原子写入，每个文件失败捕获），工具路径遍历，可观察性（信号量等待事件，超时错误上下文，配置文件环境变量日志记录，预热冷启动信号），测试安全性（模块加载环境快照跨 10 个文件，`tools/call` E2E）。为操作员添加了故障排除手册和硬件最低要求。
- **第五阶段 — M5 Max 基准测试** — 硬件到位后发布可比数字（~2026-04-24）
按强化层划分阶段。包和工件层分别在 3 和 7 处冻结。原子冻结在 v2.1.0 处解除 — 新原子需要审计证明的间隙、测试、手册页面和 CHANGELOG 条目。
---
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
---
<p align="center">由 <a href="https://mcp-tool-shop.github.io/">MCP 工具商店</a> 构建</p>
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器