# https://github.com/Surya-Hariharan/Velune-CLI 项目说明书

生成时间：2026-06-27 15:25:49 UTC

## 目录

- [项目概述与架构总览](#page-1)
- [委员会多代理系统与认知引擎](#page-2)
- [记忆体系、仓库认知与混合检索](#page-3)
- [提供商适配、MCP 集成与扩展机制](#page-4)

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

## 项目概述与架构总览

### 相关页面

相关主题：[委员会多代理系统与认知引擎](#page-2), [记忆体系、仓库认知与混合检索](#page-3), [提供商适配、MCP 集成与扩展机制](#page-4)

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

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

- [README.md](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/README.md)
- [velune/cli/commands/ask.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cli/commands/ask.py)
- [velune/cli/commands/run.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cli/commands/run.py)
- [velune/cli/commands/workspace.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cli/commands/workspace.py)
- [velune/cli/commands/context.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cli/commands/context.py)
- [velune/cognition/agents/planner.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cognition/agents/planner.py)
- [velune/cognition/agents/reviewer.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cognition/agents/reviewer.py)
- [velune/providers/task_classifier.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/task_classifier.py)
- [velune/providers/discovery/openai.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/discovery/openai.py)
- [velune/providers/adapters/google.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/adapters/google.py)
- [velune/providers/adapters/groq.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/adapters/groq.py)
- [velune/providers/adapters/cohere.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/adapters/cohere.py)
- [velune/providers/adapters/nvidia.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/adapters/nvidia.py)
- [velune/providers/adapters/together.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/adapters/together.py)

</details>

# 项目概述与架构总览

## 一、项目定位与目标

Velune-CLI 是一个面向开发者的、终端优先的多模型 AI 编程助手。它以命令行界面（CLI）为入口，提供 [README.md:35-60](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/README.md) 中所述的 "Terminal-first multi-model AI developer CLI" 能力。系统的核心设计目标包括：

- **多模型路由**：根据任务复杂度与成本，在本地与云端模型之间灵活调度。
- **委员会式多代理编排**：通过 Planner / Reviewer 等专门代理协作完成复杂编程任务。
- **仓库感知**：自动索引与混合检索（BM25 + 向量），让 AI 拥有对当前代码库的持续记忆。
- **三档会话模式**：在 `Optimus / Normal / Godly` 之间切换速度与质量。
- **MCP（Model Context Protocol）支持**：社区反馈表明项目已具备"最成熟的 MCP 实现之一"，可作为客户端/服务端进行工具集成（[issues/9](https://github.com/Surya-Hariharan/Velune-CLI/issues/9)）。

最新发布版本为 `0.9.3.4`（[release v0.9.3.4](https://github.com/Surya-Hariharan/Velune-CLI/releases/tag/v0.9.3.4)），延续 `0.9.x` 系列的"按需认知、即时启动、Lean 安装"主线。

## 二、整体架构

Velune 的运行时由四层组成：CLI 命令层 → 编排/认知层（Reasoning Council）→ 提供商适配层 → 仓库认知与本地存储。

```mermaid
flowchart TB
    User[开发者]
    CLI["CLI 命令层<br/>ask / run / workspace / context"]
    Firewall["CognitiveFirewall<br/>认知防火墙"]
    Council["Reasoning Council<br/>Planner / Reviewer / Coder"]
    Classifier["TaskClassifier<br/>任务路由"]
    Providers["提供商适配层<br/>OpenAI / Anthropic / Google<br/>Groq / Cohere / NVIDIA / Together<br/>Ollama / LM Studio"]
    Repo["Repository Cognition<br/>索引 + 混合检索"]
    Memory["持久化记忆层<br/>working / episodic / semantic"]

    User --> CLI
    CLI --> Firewall
    CLI --> Council
    Council --> Classifier
    Classifier --> Providers
    Council --> Repo
    Council --> Memory
```

各 CLI 子命令通过 `velune.core.event_loop.submit` 将异步任务投递到统一的事件循环，避免散落的 `run_until_complete` 反模式（[v0.9.0 changelog](https://github.com/Surya-Hariharan/Velune-CLI/releases/tag/v0.9.0)）。

### 2.1 CLI 命令层

入口命令通过 Typer 定义，统一从 `velune.cli.context.CLIContext` 获取容器与配置：

| 命令 | 作用 | 关键源文件 |
| --- | --- | --- |
| `velune ask` | 交互式问答或代码评审，不执行代码 | [velune/cli/commands/ask.py:1-40](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cli/commands/ask.py) |
| `velune run` | 触发 Reasoning Council 审议与沙箱执行 | [velune/cli/commands/run.py:1-50](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cli/commands/run.py) |
| `velune workspace init/explain` | 初始化工作区并生成架构摘要 | [velune/cli/commands/workspace.py:1-60](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cli/commands/workspace.py) |
| `velune context` | 渲染索引新鲜度、文件计数与存储占用 | [velune/cli/commands/context.py:1-50](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cli/commands/context.py) |

其中 `velune context` 强调"零占位符"的运营透明度——所有数字均来源于真实文件与 Git/SQLite 只读查询，由 `velune.observability.context_report.build_context_report` 计算（[velune/cli/commands/context.py:1-20](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cli/commands/context.py)）。

### 2.2 认知委员会（Cognition Council）

`PlannerAgent` 负责将自然语言任务拆解为 JSON DAG，每个步骤包含 `id`、`description`、`target_files`、`expected_outcome` 与 `agent_role` 字段，并要求"严格输出原始 JSON，禁止代码块或 Markdown 包装"（[velune/cognition/agents/planner.py:1-50](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cognition/agents/planner.py)）。`ReviewerAgent` 则对提议的代码改动进行质量、安全与回归审计，输出 `passed` / `critical_issues` / `suggestions` / `confidence_rating`（[velune/cognition/agents/reviewer.py:1-35](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cognition/agents/reviewer.py)）。所有代理受 `CouncilState` 中的预算（`planner_timeout_seconds`、总墙钟）约束，避免长任务失控。

### 2.3 任务分类与提供商适配

`TaskClassifier` 通过关键词集合识别任务类型，定义了 `CODING_KEYWORDS` / `REASONING_KEYWORDS` / `SUMMARIZATION_KEYWORDS` / `QUICK_PATTERNS` 四类集合，并基于粗略的"1 token ≈ 4 字符"启发式估算复杂度与上下文长度，进而决定路由策略（[velune/providers/task_classifier.py:1-80](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/task_classifier.py)）。

提供商层为每个后端实现统一的 `infer()` 接口与 `ModelDescriptor`：

- **云端付费**：OpenAI（GPT-4o 等，[providers/discovery/openai.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/discovery/openai.py)）、Google Gemini 1.5 / 2.0（[providers/adapters/google.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/adapters/google.py)）、Cohere Command（[providers/adapters/cohere.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/adapters/cohere.py)）、Together（[providers/adapters/together.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/adapters/together.py)）、NVIDIA NIM（[providers/adapters/nvidia.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/adapters/nvidia.py)）。
- **云端免费**：Groq 上的 Llama 3.3 70B / Mixtral / Gemma2，标记 `free_tier=True` 且 `cost_per_1k_tokens=0.0`（[providers/adapters/groq.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/adapters/groq.py)）。
- **本地**：Ollama、LM Studio，通过 README 中描述的 `velune setup` 流程配置（[README.md:65-90](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/README.md)）。

每个模型描述符携带 `CapabilityLevel`（BASIC → EXPERT）能力画像，并附 `cost_per_1k_tokens`、`speed_tier` 与 `tags` 字段，供成本/延迟敏感的路由器使用（[providers/adapters/together.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/adapters/together.py)）。

## 三、安装策略与社区关注点

自 `0.9.2` 起，Velune 采用"Lean 默认安装 + 可选 extras"策略：核心依赖从约 38 个精简到 21 个，重型编译依赖（lancedb、tree-sitter、docker 等）移入 `[rag]` / `[parsing]` / `[docker]` 等可选组，缺失时优雅降级（[release v0.9.2](https://github.com/Surya-Hariharan/Velune-CLI/releases/tag/v0.9.2)）。`0.9.3-beta.1` 进一步将仓库认知改为"用户主动触发"，启动延迟被显著压缩（[release v0.9.3-beta.1](https://github.com/Surya-Hariharan/Velune-CLI/releases/tag/v0.9.3-beta.1)）。同时，`0.9.0` 集中化了异步循环执行并移除了 `run_until_complete` 反模式，强化了安全审计套件（[release v0.9.0](https://github.com/Surya-Hariharan/Velune-CLI/releases/tag/v0.9.0)）。

社区高度关注的 MCP 工具集成已在 issue [#9](https://github.com/Surya-Hariharan/Velune-CLI/issues/9) 中被审计为"非常成熟"——项目同时提供客户端与服务端实现，可作为其它 AI 编程助手的扩展宿主使用。

## 四、See Also

- [推理委员会与多代理编排](./council-and-agents.md)
- [提供商与模型路由](./providers-and-routing.md)
- [仓库认知与混合检索](./repository-cognition.md)
- [CHANGELOG](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/docs/CHANGELOG.md)

---

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

## 委员会多代理系统与认知引擎

### 相关页面

相关主题：[项目概述与架构总览](#page-1), [记忆体系、仓库认知与混合检索](#page-3)

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

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

- [velune/cognition/agents/planner.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cognition/agents/planner.py)
- [velune/cognition/agents/reviewer.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cognition/agents/reviewer.py)
- [velune/cognition/council/base.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cognition/council/base.py)
- [velune/providers/task_classifier.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/task_classifier.py)
- [velune/models/family.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/models/family.py)
- [velune/cli/commands/run.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cli/commands/run.py)
- [velune/cli/commands/ask.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cli/commands/ask.py)
- [velune/providers/ollama_manager.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/ollama_manager.py)
- [README.md](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/README.md)
</details>

# 委员会多代理系统与认知引擎

## 概述与目标

Velune-CLI 的核心特性是 **委员会式多代理编排（Council-based Multi-Agent Orchestration）**，它在 v0.5.0-beta 公测版中作为"持久记忆层与混合检索"的一部分被正式引入。资料来源：[README.md](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/README.md)。

该系统通过多个专业化代理（Planner、Coder、Reviewer 等）协同审议用户任务，在沙箱中规划、编写并审阅代码。其设计目标包括：

- **任务分解**：将复杂的自然语言请求转换为结构化执行计划。
- **质量把关**：通过评审代理进行多轮反馈与拒绝机制。
- **预算控制**：基于 wall-clock 与单步超时的硬性限制防止失控。
- **多模型路由**：根据任务类型、复杂度与延迟敏感度选择合适的模型。

## 体系结构

### 代理角色

委员会由若干基于 `BaseCouncilAgent` 派生的角色组成，每个角色拥有独立的 `CouncilRole` 与系统提示词：

| 代理 | 职责 | 关键文件 |
| --- | --- | --- |
| Planner | 将用户任务与仓库上下文分解为 ExecutionPlan DAG | [velune/cognition/agents/planner.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cognition/agents/planner.py) |
| Coder | 依据计划生成或修改代码 | [velune/cognition/agents/coder.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cognition/agents/coder.py) |
| Reviewer | 对实现进行质量、安全与回归审计 | [velune/cognition/agents/reviewer.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cognition/agents/reviewer.py) |

### 任务分类与路由

`TaskClassifier` 在用户输入到达委员会前对其进行预处理。它基于关键词集合与启发式规则评估任务类型（编码、推理、总结、快速问答）、复杂度、延迟敏感性以及是否需要长上下文。资料来源：[velune/providers/task_classifier.py:50-90](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/task_classifier.py)。

分类结果会影响委员会的"执行档位"（instant / standard / full），用户也可通过 CLI 显式覆盖，例如 `velune run "..." --council-tier full`。

## 审议与执行流程

```mermaid
flowchart LR
    A[用户输入] --> B[TaskClassifier]
    B --> C{选择档位}
    C -->|instant| D[轻量代理]
    C -->|standard| E[标准委员会]
    C -->|full| F[完整 DAG]
    D --> G[Coder]
    E --> H[Planner → Coder → Reviewer]
    F --> I[多轮循环 + 评审]
    G --> J[沙箱执行]
    H --> J
    I --> J
    J --> K[结果回传]
```

### Planner 阶段

`PlannerAgent.generate_plan()` 接收原始任务、检索上下文与 `CouncilState`，输出严格的 JSON 执行计划。其系统提示要求 *"OUTPUT EXCLUSIVELY A RAW VALID JSON OBJECT WITH NO CODEBLOCK WRAPPERS OR Markdown"*，以确保下游解析可靠。资料来源：[velune/cognition/agents/planner.py:30-50](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cognition/agents/planner.py)。

### Coder 阶段

Coder 代理读取 Planner 生成的步骤，在沙箱中写入或修改文件。社区关注的 MCP 工具集成（如 issue #9）正是扩展此阶段的工具调用能力。资料来源：[GitHub Issue #9](https://github.com/Surya-Hariharan/Velune-CLI/issues/9)。

### Reviewer 阶段

`ReviewerAgent` 输出 `ReviewDecision`，包含 `passed`、`critical_issues`、`suggestions` 与 `confidence_rating`。未通过评审的代码会被打回 Coder 重新实现，形成闭环。资料来源：[velune/cognition/agents/reviewer.py:30-50](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cognition/agents/reviewer.py)。

## 预算、容错与安全

### 预算强制

`CouncilState` 跟踪 wall-clock 预算与单步超时。`PlannerAgent` 在生成计划前调用 `state.is_budget_exhausted()` 与 `state.remaining_budget_seconds()`，并以 `min(planner_timeout_seconds, remaining)` 作为本步超时上限。资料来源：[velune/cognition/agents/planner.py:60-90](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cognition/agents/planner.py)。

### 异步循环与启动路径

v0.9.3-beta.1 重新设计了启动路径：REPL 启动时不再自动执行仓库认知（索引），而改为"按需认知"模式，以获得即时启动体验。资料来源：[v0.9.3-beta.1 Release Notes](https://github.com/Surya-Hariharan/Velune-CLI/releases/tag/v0.9.3-beta.1)。

v0.9.0 集中化异步事件循环管理，移除 `run_until_complete` 反模式，所有顶层入口通过 `entrypoint.py` 调度。资料来源：[v0.9.0 Release Notes](https://github.com/Surya-Hariharan/Velune-CLI/releases/tag/v0.9.0)。

### 模型族适配

`ModelFamily` 枚举（QWEN、DEEPSEEK、LLAMA3、PHI、MISTRAL、GEMMA、CLAUDE、GPT、GEMINI）让不同家族模型获得最优的提示词格式。例如 Qwen 使用 ChatML，Llama3 使用 `[INST]/<<SYS>>` 标记。资料来源：[velune/models/family.py:20-60](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/models/family.py)。

## 常见失败模式

1. **预算耗尽**：当 wall-clock 超时先于评审通过时，`PlannerAgent` 会抛出 `ValueError("Wall-clock budget exhausted before Planner could run")`。
2. **模型族误判**：若 `detect_family()` 匹配失败，会回退至 `ModelFamily.UNKNOWN`，可能导致提示词格式不理想。
3. **本地 Ollama 不可用**：`OllamaManager` 的 `is_running()` 通过访问 `/api/tags` 探测服务，超时仅 2 秒，本地未启动时分类器不会路由至本地模型。资料来源：[velune/providers/ollama_manager.py:60-80](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/ollama_manager.py)。
4. **可选依赖缺失**：v0.9.2 引入"精益安装"模式，将 `lancedb`、`pyarrow`、`qdrant-client`、`tree-sitter` 等移至 extras。缺失时语义检索退化为 no-op，委员会仍可继续工作。资料来源：[v0.9.2 Release Notes](https://github.com/Surya-Hariharan/Velune-CLI/releases/tag/v0.9.2)。

## See Also

- 仓库主页：[Surya-Hariharan/Velune-CLI](https://github.com/Surya-Hariharan/Velune-CLI)
- 安全策略：[docs/SECURITY.md](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/docs/SECURITY.md)
- 贡献指南：[docs/CONTRIBUTING.md](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/docs/CONTRIBUTING.md)
- 更新日志：[docs/CHANGELOG.md](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/docs/CHANGELOG.md)
- MCP 工具集成审计：[Issue #9](https://github.com/Surya-Hariharan/Velune-CLI/issues/9)

---

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

## 记忆体系、仓库认知与混合检索

### 相关页面

相关主题：[委员会多代理系统与认知引擎](#page-2), [提供商适配、MCP 集成与扩展机制](#page-4)

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

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

- [velune/cognition/agents/planner.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cognition/agents/planner.py)
- [velune/cognition/agents/reviewer.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cognition/agents/reviewer.py)
- [velune/cli/commands/run.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cli/commands/run.py)
- [velune/cli/commands/workspace.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cli/commands/workspace.py)
- [velune/cli/commands/session.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cli/commands/session.py)
- [velune/providers/task_classifier.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/task_classifier.py)
- [README.md](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/README.md)
</details>

# 记忆体系、仓库认知与混合检索

## 一、设计目标与定位

Velune 是一个面向终端的多模型 AI 开发者 CLI，其核心差异在于把"持久化记忆"、"仓库认知"和"Council 多智能体协同"串联成统一的推理栈。[README.md](README.md) 把 CLI 描述为"terminal-first multi-model AI developer CLI"，并在 v0.5.0-beta 中将 "Persistent memory tiers (working, episodic, semantic)" 与 "Repository cognition and hybrid retrieval (BM25 + vector + graph)" 列为关键能力。

0.9.3-beta.1 起，"仓库认知"被改造为按需触发：REPL 启动时不再自动跑索引，而是由用户用 `/cognition quick|standard|deep` 这类命令显式启动，因此冷启动近乎瞬时。0.9.2 则把重型依赖（`lancedb`、`pyarrow`、`qdrant-client`）拆出默认安装，作为 `[rag]` extras，只有真正启用 RAG/混合检索时才付出代价 资料来源：[README.md](README.md)。

## 二、仓库认知（Repository Cognition）

仓库认知的作用是把本地代码库转成 Council 可以消费的 `RepositorySnapshot`。`velune/cli/commands/run.py` 中的 `run_command` 接收自然语言任务后，会先获取当前快照并交给 `CognitiveFirewall`，该对象是后续混合检索的输入面 资料来源：[velune/cli/commands/run.py:30-58]()。

认知结果落到工作区下的 `.velune` 目录。`velune/cli/commands/workspace.py` 的 `workspace_explain` 在该目录缺失时直接退出码 1，提示先运行 `velune workspace init`；随后调用 `ArchitectureDetector` 与 `TechnologyDetector`，**不调用任何 AI provider** 即生成框架、路由、状态管理等摘要 资料来源：[velune/cli/commands/workspace.py:1-40]()。这意味着认知阶段是确定性的、与 LLM 解耦的，可以重复执行。

```mermaid
flowchart LR
    A[velune workspace init] --> B[.velune 目录]
    B --> C[架构与技术检测]
    C --> D[RepositorySnapshot]
    D --> E[CognitiveFirewall]
    E --> F[Council 推理]
```

## 三、混合检索与 Council 上下文注入

仓库认知的产物进入混合检索后，以 `retrieved_context` 形式喂给 Planner。`PlannerAgent.generate_plan` 的签名把 `retrieved_context` 明确描述为 "Repository context + architectural drift alarms"，即混合检索要同时回答两件事：① 找到相关代码片段；② 标记架构漂移 资料来源：[velune/cognition/agents/planner.py:30-50]()。

Planner 还受 Council 预算约束：`state.is_budget_exhausted()` 为真时会直接抛 `ValueError`；否则以 `state.remaining_budget_seconds()` 与 `state.budget.planner_timeout_seconds` 中较小者作为超时上限，把"记忆 + 检索 + 规划"放在同一墙钟预算内 资料来源：[velune/cognition/agents/planner.py:55-75]()。规划完成后，`ReviewerAgent` 用只输出 JSON 的系统提示对实现做"质量、安全、回归"三轴审查，产出 `passed`、`critical_issues`、`suggestions`、`confidence_rating` 四元结果，作为事后记忆的消费者 资料来源：[velune/cognition/agents/reviewer.py:1-50]()。

## 四、任务分类与会话持久化

进入 Council 前，提示词先经 `TaskClassifier` 预处理：它基于关键字集合把任务分成代码、推理、摘要等大类，估算 `prompt_tokens + context_tokens`，若超过 8000 即标记 `requires_long_context`，从而决定是否走长上下文/混合检索路径 资料来源：[velune/providers/task_classifier.py:1-60]()。

会话层面，`velune/cli/commands/session.py` 的 `session list` 按 workspace 隔离列出历史会话；存储层用 `SessionStore`，支持 `--all` 跨工作区查询与 JSON 输出，相当于记忆体系中"episodic"层在用户面的入口 资料来源：[velune/cli/commands/session.py:1-40]()。

## 五、常见失败模式

- **仓库未初始化**：`workspace_explain` 在 `.velune` 缺失时直接退出码 1，需先 `velune workspace init`。
- **冷启动无快照**：`run_command` 拿不到 `RepositorySnapshot` 时混合检索为空，Planner 仅能依赖纯 prompt。
- **预算耗尽**：`PlannerAgent` 在 `budget exhausted` 时抛 `ValueError`，不会降级到更便宜的模型。

## 参见

- 提供商适配与路由：[velune/providers/adapters/*](velune/providers/adapters/)
- Council 智能体实现：[velune/cognition/agents/*](velune/cognition/agents/)
- 任务分类与模型能力画像：[velune/providers/task_classifier.py](velune/providers/task_classifier.py)
- 发行说明：[v0.9.3-beta.1](https://github.com/Surya-Hariharan/Velune-CLI/releases/tag/v0.9.3-beta.1)、[v0.9.2](https://github.com/Surya-Hariharan/Velune-CLI/releases/tag/v0.9.2)

---

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

## 提供商适配、MCP 集成与扩展机制

### 相关页面

相关主题：[项目概述与架构总览](#page-1), [委员会多代理系统与认知引擎](#page-2)

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

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

- [velune/providers/base.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/base.py)
- [velune/providers/registry.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/registry.py)
- [velune/providers/router.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/router.py)
- [velune/providers/keystore.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/keystore.py)
- [velune/providers/ollama_manager.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/ollama_manager.py)
- [velune/providers/adapters/ollama.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/adapters/ollama.py)
- [velune/providers/adapters/openai.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/adapters/openai.py)
- [velune/providers/adapters/anthropic.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/adapters/anthropic.py)
- [velune/providers/adapters/google.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/adapters/google.py)
- [velune/providers/adapters/groq.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/adapters/groq.py)
- [velune/providers/adapters/cohere.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/adapters/cohere.py)
- [velune/providers/adapters/nvidia.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/adapters/nvidia.py)
- [velune/providers/adapters/together.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/adapters/together.py)
- [velune/providers/discovery/openai.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/discovery/openai.py)
- [velune/providers/discovery/together.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/discovery/together.py)
- [velune/providers/task_classifier.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/providers/task_classifier.py)
- [velune/models/__init__.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/models/__init__.py)
- [README.md](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/README.md)
- [velune/cognition/agents/planner.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cognition/agents/planner.py)
- [velune/cognition/agents/coder.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cognition/agents/coder.py)
- [velune/cognition/agents/reviewer.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cognition/agents/reviewer.py)
- [velune/cli/commands/run.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cli/commands/run.py)
- [velune/cli/commands/ask.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cli/commands/workspace.py)
- [velune/cli/commands/session.py](https://github.com/Surya-Hariharan/Velune-CLI/blob/main/velune/cli/commands/session.py)
</details>

# 提供商适配、MCP 集成与扩展机制

## 概述与设计目标

Velune-CLI 是一个终端优先的多模型 AI 开发者 CLI，其核心抽象是"提供商（Provider）"——即任何能产出推理响应（文本或结构化输出）的后端，既可以是云端 API，也可以是本地推理服务器。`velune/providers/base.py` 定义了统一的 `ModelProvider` 抽象接口以及请求/响应类型（`InferenceRequest`、`InferenceResponse`），所有具体后端都必须实现该契约。`velune/providers/registry.py` 与 `velune/providers/router.py` 在该抽象之上构建了注册表与按能力路由的调度器，使得上层 Council 代理无需关心底层使用何种模型。README 中明确列出已支持的提供商矩阵：本地侧包括 Ollama、LM Studio，云端侧包括 Groq、OpenRouter、OpenAI、Anthropic、Google、Cohere、NVIDIA、Together、xAI 等。

社区方面，[Issue #9（MCP Audit）](https://github.com/Surya-Hariharan/Velune-CLI/issues/9) 指出 Velune 已具备成熟的客户端/服务端 MCP 实现，这也是扩展机制的重要支柱。

## 适配器架构：Discovery + Adapter 双层

提供商接入采用"Discovery（能力发现）+ Adapter（接口适配）"双层模式。

```mermaid
flowchart LR
    A[User / CLI Command] --> B[ProviderRegistry]
    B --> C{Router 能力匹配}
    C --> D[Adapter: Ollama / OpenAI / Anthropic / Google / Groq / Cohere / NVIDIA / Together / xAI]
    D --> E[外部模型 API / 本地推理服务器]
    D --> F[统一 InferenceResponse]
    F --> G[Council Agent: Planner / Coder / Reviewer]
```

### Discovery 层

Discovery 模块在运行时探测并构建 `ModelDescriptor` 列表，描述每个模型的上下文长度、`ModelCapabilityProfile`（编码、推理、规划、摘要、指令遵循、工具使用、长上下文等维度）、成本、速度档位与标签。`velune/providers/discovery/openai.py` 根据模型 ID（如 "gpt-4"）自动推断能力档位；`velune/providers/discovery/together.py` 列举 Qwen、DeepSeek-R1、Mistral 等开源模型及其能力画像。Discovery 层不直接发起推理，仅提供元数据。

### Adapter 层

Adapter 层负责协议转换。每个适配器继承 `ModelProvider` 基类并实现 `infer()` 方法，例如：

- `velune/providers/adapters/nvidia.py`：构造 `chat/completions` 风格的 payload 并解析 OpenAI 兼容响应；
- `velune/providers/adapters/cohere.py`：将消息拆分为 `preamble` / `chat_history` / `message`，调用 Cohere v2 chat 接口；
- `velune/providers/adapters/google.py`：将消息拆分为 Gemini *contents* 与 system instruction 文本；
- `velune/providers/adapters/groq.py`、`together.py`：在 OpenAI 兼容协议之上做薄封装，并对免费层模型打上 `free_tier=True` 与 `tags=["free"]` 元数据。

所有 Adapter 都通过 `httpx.AsyncClient` 异步发送请求、统一计算 `latency_ms`、抽取 token usage 并封装为 `InferenceResponse`，使得上层无需感知协议差异。

### 本地推理管理

`velune/providers/ollama_manager.py` 单独实现 `OllamaManager`：内置推荐模型清单（如 `qwen2.5:72b`、`codellama:13b`、`gemma2:9b`），每个条目注明 `size_gb`、`ram_needed` 与技能类型（编码 / 嵌入 / 通用），并在初始化时设置合理的 `httpx` 超时（默认 60s，pull 任务可按请求覆盖），防止模型下载或列表调用长时间挂起。

## 路由、密钥与任务分类

### 智能路由

`velune/providers/router.py` 接收 Discovery 提供的 `ModelDescriptor` 列表，结合 `velune/providers/task_classifier.py` 的分类结果，按"任务类型 + 能力档位 + 成本 + 速度档位 + 长上下文需求"进行匹配。任务分类器维护多组关键词集合：

- `CODING_KEYWORDS`（refactor、rewrite、pytest、sql 等）；
- `REASONING_KEYWORDS`（explain、deduce、proof 等）；
- `SUMMARIZATION_KEYWORDS`（summarize、tldr、gist 等）；
- `QUICK_PATTERNS`（what is、define 等低复杂度模式）。

分类输出 `TaskProfile`，包含 `task_type`、`complexity`、`latency_sensitive`、`requires_long_context` 等字段，供路由器选择最合适的模型——例如长上下文任务（> 8000 tokens）会倾向选择 `long_context=ADVANCED/EXPERT` 的模型。

### 密钥与凭据管理

`velune/providers/keystore.py` 负责 API key 的持久化与读取，配合 `velune setup` 流程将 key 写入本地安全存储，Adapter 在 `initialize()` 时按需加载。

### CLI 入口集成

提供商层在 CLI 中通过 `velune/cli/commands/ask.py`（交互式问答）和 `velune/cli/commands/run.py`（Council 委派执行）暴露：

- `velune ask <prompt> [--council-tier instant|standard|full]`：自然语言问题路由；
- `velune run <task> [--dry-run] [--force] [--yes]`：完整 Council 委派与沙箱执行。

`velune/cli/commands/session.py` 与 `velune/cli/commands/workspace.py` 则提供会话与工作区管理（如 `workspace explain`）。

## MCP 集成与扩展机制

Velune 在 v0.5.0-beta 起即引入 MCP（Model Context Protocol）相关抽象，社区审计报告（[Issue #9](https://github.com/Surya-Hariharan/Velune-CLI/issues/9)）确认其已具备成熟的 MCP 客户端/服务端实现。Provider 层与 MCP 的衔接点包括：

1. **Tool-Use 能力字段**：`ModelCapabilityProfile.tool_use`（BASIC / INTERMEDIATE / ADVANCED / EXPERT）显式标注模型对外部工具调用的支持程度，供 Router 在选择 Council Agent 使用的模型时进行决策；
2. **Council Agent 协议**：`velune/cognition/agents/planner.py`、`coder.py`、`reviewer.py` 均基于 `BaseCouncilAgent`，通过 `provider.infer()` 调用底层模型，并在结构化 JSON 输出中指定 `tool_use`、`expected_outcome` 等字段，为 MCP 工具描述提供受控接口；
3. **可插拔扩展**：新增提供商只需实现 `ModelProvider` 子类并在 `registry.py` 注册；新增模型只需在 Discovery 模块或 Adapter 中追加 `ModelDescriptor`，无需修改上层路由逻辑。

## 失败模式与最佳实践

常见失败模式包括：

| 现象 | 可能原因 | 建议 |
|------|---------|------|
| `Provider not found` | Adapter 未注册或 Discovery 未返回 | 检查 `registry.py` 与 Discovery 配置 |
| 长时间挂起 | Ollama pull 默认 60s 超时 | 在 `OllamaManager` 中按需放宽 |
| 路由到能力不足的模型 | `task_classifier` 关键词未覆盖 | 在 `task_classifier.py` 关键词集合中补充领域术语 |
| API key 丢失 | keystore 未持久化 | 重新运行 `velune setup` |

---

## See Also

- [Council 多代理编排与状态管理](council-orchestration.md)
- [仓库认知与混合检索](repository-cognition.md)
- [CLI 命令与会话管理](cli-commands.md)

---

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

---

## Doramagic 踩坑日志

项目：Surya-Hariharan/Velune-CLI

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

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

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

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

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

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

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

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

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

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/Surya-Hariharan/Velune-CLI | no_demo; severity=medium

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

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

## 7. 安全/权限坑 · 来源证据：MCP Audit: Add MCP server support for tool integration

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：MCP Audit: Add MCP server support for tool integration
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Surya-Hariharan/Velune-CLI/issues/9 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

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

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

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

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

<!-- canonical_name: Surya-Hariharan/Velune-CLI; human_manual_source: deepwiki_human_wiki -->