一、项目定位与目标

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

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

最新发布版本为 0.9.3.4（release v0.9.3.4），延续 0.9.x 系列的"按需认知、即时启动、Lean 安装"主线。

二、整体架构

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

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）。

2.1 CLI 命令层

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

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

2.2 认知委员会（Cognition Council）

PlannerAgent 负责将自然语言任务拆解为 JSON DAG，每个步骤包含 id、description、target_files、expected_outcome 与 agent_role 字段，并要求"严格输出原始 JSON，禁止代码块或 Markdown 包装"（velune/cognition/agents/planner.py:1-50）。ReviewerAgent 则对提议的代码改动进行质量、安全与回归审计，输出 passed / critical_issues / suggestions / confidence_rating（velune/cognition/agents/reviewer.py:1-35）。所有代理受 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）。

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

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

每个模型描述符携带 CapabilityLevel（BASIC → EXPERT）能力画像，并附 cost_per_1k_tokens、speed_tier 与 tags 字段，供成本/延迟敏感的路由器使用（providers/adapters/together.py）。

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

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

社区高度关注的 MCP 工具集成已在 issue #9 中被审计为"非常成熟"——项目同时提供客户端与服务端实现，可作为其它 AI 编程助手的扩展宿主使用。

四、See Also

• 推理委员会与多代理编排
• 提供商与模型路由
• 仓库认知与混合检索
• CHANGELOG

概述与目标

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

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

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

体系结构

代理角色

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

任务分类与路由

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

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

审议与执行流程

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。

Coder 阶段

Coder 代理读取 Planner 生成的步骤，在沙箱中写入或修改文件。社区关注的 MCP 工具集成（如 issue #9）正是扩展此阶段的工具调用能力。资料来源：GitHub Issue #9。

Reviewer 阶段

ReviewerAgent 输出 ReviewDecision，包含 passed、critical_issues、suggestions 与 confidence_rating。未通过评审的代码会被打回 Coder 重新实现，形成闭环。资料来源：velune/cognition/agents/reviewer.py:30-50。

预算、容错与安全

预算强制

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

异步循环与启动路径

v0.9.3-beta.1 重新设计了启动路径：REPL 启动时不再自动执行仓库认知（索引），而改为"按需认知"模式，以获得即时启动体验。资料来源：v0.9.3-beta.1 Release Notes。

v0.9.0 集中化异步事件循环管理，移除 run_until_complete 反模式，所有顶层入口通过 entrypoint.py 调度。资料来源：v0.9.0 Release Notes。

模型族适配

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

常见失败模式

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。
4. 可选依赖缺失：v0.9.2 引入"精益安装"模式，将 lancedb、pyarrow、qdrant-client、tree-sitter 等移至 extras。缺失时语义检索退化为 no-op，委员会仍可继续工作。资料来源：v0.9.2 Release Notes。

See Also

• 仓库主页：Surya-Hariharan/Velune-CLI
• 安全策略：docs/SECURITY.md
• 贡献指南：docs/CONTRIBUTING.md
• 更新日志：docs/CHANGELOG.md
• MCP 工具集成审计：Issue #9

一、设计目标与定位

Velune 是一个面向终端的多模型 AI 开发者 CLI，其核心差异在于把"持久化记忆"、"仓库认知"和"Council 多智能体协同"串联成统一的推理栈。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。

二、仓库认知（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 解耦的，可以重复执行。

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/*
• Council 智能体实现：velune/cognition/agents/*
• 任务分类与模型能力画像：velune/providers/task_classifier.py
• 发行说明：v0.9.3-beta.1、v0.9.2

概述与设计目标

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） 指出 Velune 已具备成熟的客户端/服务端 MCP 实现，这也是扩展机制的重要支柱。

适配器架构：Discovery + Adapter 双层

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

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）确认其已具备成熟的 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，无需修改上层路由逻辑。

失败模式与最佳实践

常见失败模式包括：

Pitfall Log / 踩坑日志

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