# velune-cli - Doramagic AI Context Pack

> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。

## 充分原则

- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。
- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。

## 给宿主 AI 的使用方式

你正在读取 Doramagic 为 velune-cli 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。

## Claim 消费规则

- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。
- **事实最低状态**：`supported`
- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。
- `weak`：只能作为低置信度线索，必须要求用户继续核实。
- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。
- `unverified`：不得作为事实使用，应明确说证据不足。
- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。

## 它最适合谁

- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86

## 它能做什么

- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86

## 怎么开始

- `curl -fsSL https://ollama.com/install.sh | sh` 证据：`README.md` Claim：`clm_0003` supported 0.86
- `pip install velune-cli` 证据：`README.md` Claim：`clm_0004` supported 0.86, `clm_0006` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86
- `pipx install velune-cli` 证据：`README.md` Claim：`clm_0005` supported 0.86
- `pip install velune-cli            # lean base (Ollama, cloud providers, chat, lexical search)` 证据：`README.md` Claim：`clm_0006` supported 0.86
- `pip install 'velune-cli[rag]'     # + semantic memory & vector retrieval` 证据：`README.md` Claim：`clm_0007` supported 0.86
- `pip install 'velune-cli[all]'     # + every optional feature` 证据：`README.md` Claim：`clm_0008` supported 0.86
- `pip install -e ".[dev]"` 证据：`README.md` Claim：`clm_0009` supported 0.86

## 继续前判断卡

- **当前建议**：仅建议沙盒试装
- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。

### 30 秒判断

- **现在怎么做**：仅建议沙盒试装
- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装
- **先别相信**：真实输出质量不能在安装前相信。
- **继续会触碰**：命令执行、本地环境或项目文件、宿主 AI 上下文

### 现在可以相信

- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86
- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86
- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86

### 现在还不能相信

- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。
- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。
- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。
- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。
- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。
- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。
- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`

### 继续会触碰什么

- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`
- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`
- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。

### 最小安全下一步

- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）
- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）
- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）

### 退出方式

- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。
- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。
- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。

## 哪些只能预览

- 解释项目适合谁和能做什么
- 基于项目文档演示典型对话流程
- 帮助用户判断是否值得安装或继续研究

## 哪些必须安装后验证

- 真实安装 Skill、插件或 CLI
- 执行脚本、修改本地文件或访问外部服务
- 验证真实输出质量、性能和兼容性

## 边界与风险判断卡

- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0010` inferred 0.45
- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0011` supported 0.86
- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。
- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。
- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。

## 开工前工作上下文

### 加载顺序

- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。
- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。
- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。
- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。
- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。

### 任务路由

- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86

### 上下文规模

- 文件总数：452
- 重要文件覆盖：40/452
- 证据索引条目：71
- 角色 / Skill 条目：13

### 证据不足时的处理

- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。
- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。
- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。
- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。

## Prompt Recipes

### 适配判断

- 目标：判断这个项目是否适合用户当前任务。
- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。

```text
请基于 velune-cli 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。
```

### 安装前体验

- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。
- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。

```text
请把 velune-cli 当作安装前体验资产，而不是已安装工具或真实运行环境。

请严格输出四段：
1. 先问我 3 个必要问题。
2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。
3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。
4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。

硬性边界：
- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。
- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。
- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。
- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。
- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。
- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。

```

### 角色 / Skill 选择

- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。
- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。

```text
请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。
```

### 风险预检

- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。
- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。

```text
请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。
```

### 宿主 AI 开工指令

- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。
- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。

```text
请基于 velune-cli 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。
```

## 角色 / Skill 索引

- 共索引 13 个角色 / Skill / 项目文档条目。

- **Contributing to Velune**（project_doc）：Thank you for helping improve Velune. This guide covers development setup, how to add new providers, agents, and commands, and the review process. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/CONTRIBUTING.md`
- **Velune**（project_doc）：Local-first multi-model AI developer CLI. Council-based agents, persistent memory, repository cognition. No cloud required. No quota. No lock-in. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`
- **Contributing to Velune**（project_doc）：Thank you for helping improve Velune. This guide covers development setup, how to add new providers, agents, and commands, and the review process. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`
- **Changelog**（project_doc）：All notable changes to this project will be documented in this file. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/CHANGELOG.md`
- **Security Policy**（project_doc）：Security fixes are triaged on main . Maintainers backport critical fixes to supported release branches where feasible. Users should upgrade to the latest release for timely protection. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/SECURITY.md`
- **Changelog**（project_doc）：All notable changes to this project will be documented in this file. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`
- **Security Policy**（project_doc）：Security fixes are triaged on main . Maintainers backport critical fixes to supported release branches where feasible. Users should upgrade to the latest release for timely protection. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`SECURITY.md`
- **Architecture**（project_doc）：Velune is organized into distinct layers with clear separation of concerns: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/ARCHITECTURE.md`
- **Architecture — Instant Startup & On-Demand Cognition**（project_doc）：Architecture — Instant Startup & On-Demand Cognition 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/ARCHITECTURE_STARTUP.md`
- **Contributor Covenant Code of Conduct**（project_doc）：Contributor Covenant Code of Conduct 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/CODE_OF_CONDUCT.md`
- **Development Guide**（project_doc）：Prerequisites - Python 3.11+ - Git - pip or uv 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/DEVELOPMENT.md`
- **Startup Architecture Refactor — Migration Report**（project_doc）：Startup Architecture Refactor — Migration Report 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/STARTUP_REFACTOR_MIGRATION.md`
- **Velune Threat Model**（project_doc）：This document defines Velune's attacker model, trust boundaries, and the controls enforced at each boundary. It complements SECURITY.md ../SECURITY.md policy, reporting with the engineering rationale. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/THREAT_MODEL.md`

## 证据索引

- 共索引 71 条证据。

- **Contributing to Velune**（documentation）：Thank you for helping improve Velune. This guide covers development setup, how to add new providers, agents, and commands, and the review process. 证据：`docs/CONTRIBUTING.md`
- **Velune**（documentation）：Local-first multi-model AI developer CLI. Council-based agents, persistent memory, repository cognition. No cloud required. No quota. No lock-in. 证据：`README.md`
- **Contributing to Velune**（documentation）：Thank you for helping improve Velune. This guide covers development setup, how to add new providers, agents, and commands, and the review process. 证据：`CONTRIBUTING.md`
- **Changelog**（documentation）：All notable changes to this project will be documented in this file. 证据：`docs/CHANGELOG.md`
- **Security Policy**（documentation）：Security fixes are triaged on main . Maintainers backport critical fixes to supported release branches where feasible. Users should upgrade to the latest release for timely protection. 证据：`docs/SECURITY.md`
- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`
- **Changelog**（documentation）：All notable changes to this project will be documented in this file. 证据：`CHANGELOG.md`
- **Security Policy**（documentation）：Security fixes are triaged on main . Maintainers backport critical fixes to supported release branches where feasible. Users should upgrade to the latest release for timely protection. 证据：`SECURITY.md`
- **Architecture**（documentation）：Velune is organized into distinct layers with clear separation of concerns: 证据：`docs/ARCHITECTURE.md`
- **Architecture — Instant Startup & On-Demand Cognition**（documentation）：Architecture — Instant Startup & On-Demand Cognition 证据：`docs/ARCHITECTURE_STARTUP.md`
- **Contributor Covenant Code of Conduct**（documentation）：Contributor Covenant Code of Conduct 证据：`docs/CODE_OF_CONDUCT.md`
- **Development Guide**（documentation）：Prerequisites - Python 3.11+ - Git - pip or uv 证据：`docs/DEVELOPMENT.md`
- **Startup Architecture Refactor — Migration Report**（documentation）：Startup Architecture Refactor — Migration Report 证据：`docs/STARTUP_REFACTOR_MIGRATION.md`
- **Velune Threat Model**（documentation）：This document defines Velune's attacker model, trust boundaries, and the controls enforced at each boundary. It complements SECURITY.md ../SECURITY.md policy, reporting with the engineering rationale. 证据：`docs/THREAT_MODEL.md`
- **Init**（source_file）：version = "0.9.3.4" all = " version " 证据：`velune/__init__.py`
- **Init**（source_file）：all = "app" def getattr name: str 证据：`velune/cli/__init__.py`
- **Only expose path and language — no raw symbol names or content**（source_file）：console = Console ask cmd = typer.Typer help="Interactive prompt entry point" ⋮---- cli context = ctx.obj ⋮---- prompt = typer.prompt "What would you like to ask Velune?" ⋮---- container = cli context.container lifecycle = container.get "runtime.lifecycle" model registry = container.get "runtime.model registry" model specialization = container.get "runtime.council orchestrator" .mapper repo cognition = container.get "runtime.repository cognition" orchestrator = container.get "runtime.council orchestrator" ⋮---- display = CouncilDisplayView console ⋮---- roles = model specialization.map roles ⋮---- firewall = CognitiveFirewall snapshot: RepositorySnapshot None = None ⋮---- snapshot = repo co… 证据：`velune/cli/commands/ask.py`
- **Base**（source_file）：class CommandRegistrar Protocol ⋮---- def register self, app: typer.Typer, container: ServiceContainer - None 证据：`velune/cli/commands/base.py`
- **--- Index summary + language breakdown ---**（source_file）：console = Console context cmd = typer.Typer help="Show index freshness, file counts, and workspace health." FRESHNESS STYLE = { STATE GLYPH = { ⋮---- @context cmd.callback invoke without command=True def context main ctx: typer.Context - None ⋮---- cli context = ctx.obj workspace = cli context.workspace if isinstance cli context, CLIContext else None ⋮---- json mode = isinstance cli context, CLIContext and cli context.json mode report = build context report workspace ⋮---- def render console: Console, report: ContextReport - None ⋮---- header = Text ⋮---- sha = report.head sha or "" :8 ⋮---- --- Index summary + language breakdown --- ⋮---- lang table = Table ⋮---- --- Top knowledge areas --… 证据：`velune/cli/commands/context.py`
- **Parse run id from milestones format: " run id milestone name"**（source_file）：console = Console run cmd = typer.Typer help="Autonomous council run commands" ⋮---- cli context = ctx.obj ⋮---- container = cli context.container lifecycle = container.get "runtime.lifecycle" model registry = container.get "runtime.model registry" orchestration engine = container.get "runtime.orchestration engine" ⋮---- async def stream runner ⋮---- milestones = ⋮---- Parse run id from milestones format: " run id milestone name" run id = None ⋮---- run id = m.run id ⋮---- run id = m.split " " 0 1: ⋮---- state = await stream runner ⋮---- success = state.status == ExecutionStatus.COMPLETED attempts count = len state.attempts plan steps = len state.task plan.steps if state.task plan else 0 ch… 证据：`velune/cli/commands/run.py`
- **Session**（source_file）：console = Console session cmd = typer.Typer help="List, resume, or delete chat sessions." ⋮---- cli context = ctx.obj ⋮---- store = SessionStore workspace = None if all workspaces else str cli context.workspace.resolve sessions = store.list workspace=workspace, limit=limit ⋮---- label = "any workspace" if all workspaces else str cli context.workspace ⋮---- table = Table box=ROUNDED, border style=design.FAINT, expand=False ⋮---- meta = store.load meta session id ⋮---- md = store.export markdown session id 证据：`velune/cli/commands/session.py`
- **1. Create .velune directory structure**（source_file）：console = Console workspace cmd = typer.Typer help="Browse, index, and switch projects." ⋮---- cli context = ctx.obj ⋮---- 1. Create .velune directory structure velune dir = path / ".velune" ⋮---- veluneignore path = path / ".veluneignore" ⋮---- container = cli context.container lifecycle = container.get "runtime.lifecycle" repo cognition = container.get "runtime.repository cognition" ⋮---- snapshot = repo cognition.index force=force ⋮---- num files = len snapshot.files num symbols = len snapshot.symbols num edges = len snapshot.edges excluded file paths: list str = languages: dict str, int = {} ⋮---- lang summary = ", ".join f"{count} {lang}" for lang, count in languages.items git branch =… 证据：`velune/cli/commands/workspace.py`
- **Context**（source_file）：@dataclass slots=True class CLIContext ⋮---- workspace: Path config path: Path None verbose: bool runtime: RuntimeContext json mode: bool = False yes: bool = False ⋮---- @property def console self - Console ⋮---- @property def config self - VeluneConfig ⋮---- @property def container self - ServiceContainer 证据：`velune/cli/context.py`
- **Session**（source_file）：log = logging.getLogger "velune.cli.handlers.session" async def cmd help repl: VeluneREPL, args: str - None ⋮---- show hidden = any tok in "--all", "-a", "all" for tok in args.split grouped: dict str, list = {} ⋮---- ordered = c for c in CATEGORY ORDER if c in grouped ⋮---- table = create table "Command", "Aliases", "Description", title=category ⋮---- aliases = ", ".join f"/{a}" for a in cmd.aliases if cmd.aliases else "" name = f" cyan /{cmd.name} /cyan " + " dim dev /dim " if cmd.hidden else "" ⋮---- tips = " dim Press bold Tab /bold to autocomplete · bold /help --all /bold for dev commands · bold /doctor /bold for diagnostics. /dim " ⋮---- async def cmd exit repl: VeluneREPL, args: str -… 证据：`velune/cli/handlers/session.py`
- **Workspace**（source_file）：log = logging.getLogger "velune.cli.handlers.workspace" async def cmd project repl: VeluneREPL, args: str - None ⋮---- parts = args.strip .split None, 1 sub = parts 0 .lower if parts else "" sub args = parts 1 if len parts 1 else "" ⋮---- target = Path sub args.strip or "." .expanduser ⋮---- info = repl. workspace registry.register target kind = info.project type or "git repo" if info.is git else "folder" ⋮---- async def project open repl: VeluneREPL, raw path: str - None ⋮---- target = Path raw path or "." .expanduser ⋮---- target = target.resolve ⋮---- current = Path repl.container.get "runtime.workspace" .resolve ⋮---- async def project close repl: VeluneREPL - None ⋮---- """Leave the cu… 证据：`velune/cli/handlers/workspace.py`
- **Registry**（source_file）：CORE = "Core" WORKSPACE = "Workspace & Sessions" SETUP = "Setup & Models" ANALYTICS = "Analytics & Monitoring" DIAG = "Diagnostics" ⋮---- @dataclass frozen=True class CommandSpec ⋮---- name: str kind: str module: str attr: str panel: str help: str hidden: bool = False bootstrap: str = "full" COMMAND SPECS: tuple CommandSpec, ... = SPECS BY NAME: dict str, CommandSpec = {spec.name: spec for spec in COMMAND SPECS} def bootstrap level command: str None - str ⋮---- spec = SPECS BY NAME.get command if command else None ⋮---- PANEL ORDER: tuple str, ... = CORE, WORKSPACE, SETUP, ANALYTICS, DIAG BUILTIN COMMAND MODULES: Sequence str = tuple dict.fromkeys spec.module for spec in COMMAND SPECS def d… 证据：`velune/cli/registry.py`
- **Init**（source_file）：all = "CustomMarkdown", "MarkdownStreamBuffer", "StreamStats" 证据：`velune/cli/rendering/__init__.py`
- **Init**（source_file）：all = "PlannerAgent", "CoderAgent", "ReviewerAgent" 证据：`velune/cognition/agents/__init__.py`
- **Coder**（source_file）：logger = logging.getLogger "velune.cognition.agents.coder" CODER SYSTEM PROMPT = """You are the Lead Coder for the Velune Reasoning Council. class CoderAgent BaseCouncilAgent ⋮---- def init self, model: ModelDescriptor, provider: ModelProvider - None ⋮---- """Generate code diffs with timeout enforcement from budget. Args: task: Original task description retrieved context: Repository context plan context: Task plan summary or refinement feedback from reviewer state: CouncilState to write diffs into style profile: Style hints for the codebase reviewer notes: Feedback from reviewer if in revision cycle Returns: List of diff dicts with keys: file path, original, proposed, is new file Raises: Ti… 证据：`velune/cognition/agents/coder.py`
- **Planner**（source_file）：logger = logging.getLogger "velune.cognition.agents.planner" PLANNER SYSTEM PROMPT = """You are the Lead Planner for the Velune Reasoning Council. class PlannerAgent BaseCouncilAgent ⋮---- def init self, model: ModelDescriptor, provider: ModelProvider - None ⋮---- remaining = state.remaining budget seconds timeout = min state.budget.planner timeout seconds, int remaining ⋮---- user messages = result = await asyncio.wait for ⋮---- task plan = self. create fallback plan task ⋮---- steps = ⋮---- task plan = TaskPlan ⋮---- def create fallback plan self, task: str - TaskPlan ⋮---- fallback step = TaskStep 证据：`velune/cognition/agents/planner.py`
- **Call reviewer with timeout**（source_file）：logger = logging.getLogger "velune.cognition.agents.reviewer" REVIEWER SYSTEM PROMPT = """You are the Senior Code Reviewer for the Velune Reasoning Council. class ReviewerAgent BaseCouncilAgent ⋮---- def init self, model: ModelDescriptor, provider: ModelProvider - None ⋮---- remaining = state.remaining budget seconds timeout = min state.budget.reviewer timeout seconds, int remaining ⋮---- user messages = Call reviewer with timeout result = await asyncio.wait for ⋮---- decision = ReviewDecision.REJECT notes = f"Review execution error: {result.parse error}. Please resubmit." ⋮---- notes = "" ⋮---- notes = "Critical issues found:\n" 证据：`velune/cognition/agents/reviewer.py`
- **Init**（source_file）：all = 证据：`velune/cognition/council/__init__.py`
- **Base**（source_file）：T = TypeVar "T", bound=BaseModel ⋮---- logger = TracedLogger "velune.cognition.council.base" ⋮---- class BaseCouncilAgent ABC ⋮---- profile = get sampling profile self.role ⋮---- temperature = profile.temperature ⋮---- top p = profile.top p ⋮---- max tokens = profile.max tokens ⋮---- system content = self.system prompt + "\n\n" + WORKSPACE SANDBOX NOTICE messages = {"role": "system", "content": system content} + context history firewall = CognitiveFirewall ⋮---- request = InferenceRequest request = self. cache manager.prepare request agent timeouts = { timeout = agent timeouts.get self.role, 120.0 ⋮---- start = time.perf counter ⋮---- supports streaming = False ⋮---- capabilities = self.pro… 证据：`velune/cognition/council/base.py`
- **Coder**（source_file）：logger = logging.getLogger "velune.cognition.council.coder" CODER SYSTEM PROMPT = get prompt COUNCIL CODER class CoderAgent BaseCouncilAgent ⋮---- def init self, model: ModelDescriptor, provider: ModelProvider - None ⋮---- """Emits concrete code implementations aligned with codebase styling conventions. temperature overrides the role default so the orchestrator can draw several divergent candidate solutions multi-solver self-consistency . """ ⋮---- style block = "" ⋮---- naming = style profile.get "naming conventions", {} dominant = naming.get "dominant", "Hybrid" strictness = style profile.get "type hinting strictness", 1.0 paradigm = style profile.get "class vs functional", "Hybrid" doc s… 证据：`velune/cognition/council/coder.py`
- **Planner**（source_file）：logger = logging.getLogger "velune.cognition.council.planner" PLANNER SYSTEM PROMPT = get prompt COUNCIL PLANNER class PlannerAgent BaseCouncilAgent ⋮---- def init self, model: ModelDescriptor, provider: ModelProvider - None async def generate plan self, prompt: str, repo context: str - TaskPlan ⋮---- user messages = result = await self.typed deliberate user messages, PlannerMessage, temperature=0.2 ⋮---- steps = ⋮---- def create fallback plan self, prompt: str - TaskPlan ⋮---- fallback step = TaskStep 证据：`velune/cognition/council/planner.py`
- **Reviewer**（source_file）：logger = logging.getLogger "velune.cognition.council.reviewer" REVIEWER SYSTEM PROMPT = get prompt COUNCIL REVIEWER class ReviewerAgent BaseCouncilAgent ⋮---- def init self, model: ModelDescriptor, provider: ModelProvider - None async def review self, task: str, proposal: str, context: str - ReviewerMessage ⋮---- user messages = result = await self.typed deliberate user messages, ReviewerMessage 证据：`velune/cognition/council/reviewer.py`
- **Init**（source_file）：COUNCIL PLANNER = "council.planner" COUNCIL CODER = "council.coder" COUNCIL REVIEWER = "council.reviewer" COUNCIL CHALLENGER = "council.challenger" COUNCIL SYNTHESIZER = "council.synthesizer" CHAT INTERACTIVE = "chat.interactive" CHAT CONVERSATIONAL = "chat.conversational" OVERRIDES: dict str, str = {} def load premium overrides - dict str, str ⋮---- overrides = getattr premium, "PROMPTS", None ⋮---- OVERRIDES = load premium overrides def get prompt key: str - str def is premium active - bool ⋮---- """Whether any private premium overrides were loaded useful for diagnostics .""" ⋮---- all = 证据：`velune/cognition/prompts/__init__.py`
- **Init**（source_file）：all = 证据：`velune/context/__init__.py`
- **Init**（source_file）：all = 证据：`velune/context/cache/__init__.py`
- **Init**（source_file）：all = 证据：`velune/core/__init__.py`
- **Init**（source_file）：all = 证据：`velune/core/config/__init__.py`
- **Init**（source_file）：all = 证据：`velune/core/errors/__init__.py`
- **Task Registry**（source_file）：T = TypeVar "T" logger = logging.getLogger "velune.core.task registry" TRACKED TASKS: set asyncio.Task Any = set def track task: asyncio.Task Any - asyncio.Task Any ⋮---- def on done completed: asyncio.Task Any - None ⋮---- exc = completed.exception ⋮---- class BackgroundTaskRegistry ⋮---- def init self - None ⋮---- running loop = asyncio.get running loop ⋮---- async def wrapped - Any ⋮---- result = await asyncio.wait for coro, timeout=timeout seconds ⋮---- task = running loop.create task wrapped , name=name ⋮---- async def cancel all self, timeout: float = 5.0 - None ⋮---- tasks = t for t in self. tasks.values if not t.done ⋮---- stats = self.stats ⋮---- def pending count self - int def is… 证据：`velune/core/task_registry.py`
- **Init**（source_file）：all = 证据：`velune/core/types/__init__.py`
- **Context**（source_file）：class ContextPriority StrEnum ⋮---- CRITICAL = "critical" HIGH = "high" MEDIUM = "medium" LOW = "low" class ContextChunk BaseModel ⋮---- content: str source: str priority: ContextPriority tokens: int relevance score: float = Field ge=0.0, le=1.0 timestamp: float metadata: dict str, Any = Field default factory=dict class ContextWindow BaseModel ⋮---- chunks: list ContextChunk total tokens: int max tokens: int compression ratio: float = Field ge=0.0, le=1.0 ⋮---- @property def utilization self - float 证据：`velune/core/types/context.py`
- **Task**（source_file）：class TaskStatus StrEnum ⋮---- PENDING = "pending" IN PROGRESS = "in progress" COMPLETED = "completed" FAILED = "failed" CANCELLED = "cancelled" class Task BaseModel ⋮---- id: str description: str status: TaskStatus = TaskStatus.PENDING priority: int = Field default=5, ge=1, le=10 dependencies: list str = Field default factory=list metadata: dict str, Any = Field default factory=dict class TaskStep BaseModel ⋮---- agent role: str ⋮---- estimated duration ms: int None = None ⋮---- class TaskPlan BaseModel ⋮---- task id: str steps: list TaskStep ⋮---- class TaskResult BaseModel ⋮---- success: bool output: Any None = None error: str None = None steps completed: int steps total: int execution t… 证据：`velune/core/types/task.py`
- **Workspace**（source_file）：class WorkspaceState StrEnum ⋮---- IDLE = "idle" TASK ACTIVE = "task active" DEBUGGING = "debugging" REVIEWING = "reviewing" INDEXING = "indexing" ERROR = "error" class WorkspaceEvent BaseModel ⋮---- event type: str timestamp: datetime source: str data: dict str, Any = Field default factory=dict metadata: dict str, Any = Field default factory=dict 证据：`velune/core/types/workspace.py`
- **Init**（source_file）：all = 证据：`velune/execution/__init__.py`
- **Init**（source_file）：all = 证据：`velune/execution/edit_formats/__init__.py`
- **Base**（source_file）：class EditFormat StrEnum ⋮---- SEARCH REPLACE = "search replace" WHOLE FILE = "whole file" UDIFF = "udiff" ⋮---- @dataclass class EditBlock ⋮---- file path: str original: str = "" proposed: str = "" is new file: bool = False is deletion: bool = False format used: EditFormat = EditFormat.SEARCH REPLACE confidence: float = 1.0 class ParseError Exception ⋮---- """Raised when an edit format cannot parse the LLM response.""" class BaseEditFormat ABC ⋮---- """Abstract base for all edit format parsers.""" ⋮---- @abstractmethod def parse self, response: str, workspace path: Path None = None - list EditBlock ⋮---- """Extract EditBlocks from a raw LLM response string.""" ⋮---- @abstractmethod def for… 证据：`velune/execution/edit_formats/base.py`
- **Registry**（source_file）：logger = logging.getLogger "velune.execution.edit formats.registry" FORMAT PREFERENCES: dict ModelFamily, list EditFormat = { PARSERS = { def preferred formats family: ModelFamily - list EditFormat def format instructions for family: ModelFamily - str ⋮---- fmts = preferred formats family 证据：`velune/execution/edit_formats/registry.py`
- **Planner**（source_file）：logger = logging.getLogger "velune.execution.planner" class ExecutionDAG ⋮---- def init self, plan id: str - None def add step self, step: TaskStep - None def topological sort self - list TaskStep ⋮---- in degrees = self.in degree.copy ⋮---- queue = sid for sid, degree in in degrees.items if degree == 0 sorted steps: list TaskStep = ⋮---- current id = queue.pop 0 ⋮---- circular candidates = sid for sid, deg in in degrees.items if deg 0 ⋮---- class ExecutionPlanner ⋮---- """Translates high-level council TaskPlans into DAG Execution chains.""" def compile self, plan: TaskPlan - ExecutionDAG ⋮---- """Compile a standard TaskPlan into a verifiable ExecutionDAG.""" ⋮---- dag = ExecutionDAG plan.t… 证据：`velune/execution/planner.py`
- **Init**（source_file）：all = 证据：`velune/hooks/__init__.py`
- **Init**（source_file）：def get provider provider: str, token: str, base url: str None = None - BaseGitProvider ⋮---- p = provider.lower ⋮---- all = 证据：`velune/integrations/__init__.py`
- **---------------------------------------------------------------------------**（source_file）：class GitProviderError Exception ⋮---- def init self, message: str, status code: int None = None - None class AuthenticationError GitProviderError class ResourceNotFoundError GitProviderError class RateLimitError GitProviderError ⋮---- @dataclass class PRInfo ⋮---- number: int title: str url: str state: str head: str base: str draft: bool = False body: str = "" provider: str = "" "github" or "gitlab" ⋮---- @dataclass class IssueInfo ⋮---- body: str ⋮---- labels: list str = field default factory=list assignees: list str = field default factory=list provider: str = "" ⋮---- @dataclass class IssueComment ⋮---- """A comment posted on an issue or PR.""" comment id: int ⋮---- created at: str = ""… 证据：`velune/integrations/base.py`
- **Init**（source_file）：all = 证据：`velune/kernel/__init__.py`
- **------------------------------------------------------------------**（source_file）：logger = logging.getLogger "velune.kernel.registry" T = TypeVar "T" class ServiceContainer ⋮---- def init self - None def register self, name: str, factory: Callable , T , singleton: bool = True - None def register instance self, name: str, instance: Any - None def hot swap self, name: str, replacement: Any - None def get self, name: str - Any ⋮---- factory = self. factories name ⋮---- callable srv = self. services name ⋮---- def has self, name: str - bool ⋮---- """Check if a service is registered in any tier.""" ⋮---- ------------------------------------------------------------------ Readiness — for background Tier 1 services ⋮---- def event for self, name: str - asyncio.Event ⋮---- event… 证据：`velune/kernel/registry.py`
- **Init**（source_file）：all = def getattr name: str - Any 证据：`velune/mcp/__init__.py`
- **------------------------------------------------------------------**（source_file）：logger = logging.getLogger "velune.mcp.registry" class ServerState StrEnum ⋮---- DISCONNECTED = "disconnected" CONNECTING = "connecting" CONNECTED = "connected" ERROR = "error" ⋮---- @dataclass class ServerEntry ⋮---- config: ServerConfig state: ServerState = ServerState.DISCONNECTED connection: MCPConnection None = None tools: list ToolInfo = field default factory=list resources: list ResourceInfo = field default factory=list error: str = "" ⋮---- @property def name self - str ⋮---- @property def is connected self - bool class MCPServerRegistry ⋮---- """Manages multiple MCP server connections and exposes a unified tool surface. The registry is the single source of truth for MCP state durin… 证据：`velune/mcp/registry.py`
- **Init**（source_file）：all = 证据：`velune/mcp/transports/__init__.py`
- 其余 11 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。

## 宿主 AI 必须遵守的规则

- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/CONTRIBUTING.md`, `README.md`, `CONTRIBUTING.md`
- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/CONTRIBUTING.md`, `README.md`, `CONTRIBUTING.md`

## 用户开工前应该回答的问题

- 你准备在哪个宿主 AI 或本地环境中使用它？
- 你只是想先体验工作流，还是准备真实安装？
- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？

## 验收标准

- 所有能力声明都能回指到 evidence_refs 中的文件路径。
- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。
- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。

---

## Doramagic Context Augmentation

下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。

## Human Manual 骨架

使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。

宿主 AI 硬性规则：
- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。
- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。
- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。

- **项目概述与架构总览**：importance `high`
  - source_paths: README.md, velune/main.py, velune/__main__.py, velune/kernel/entrypoint.py, velune/kernel/bootstrap.py
- **委员会多代理系统与认知引擎**：importance `high`
  - source_paths: velune/cognition/council_orchestrator.py, velune/cognition/council_runner.py, velune/cognition/orchestrator.py, velune/cognition/council/base.py, velune/cognition/council/planner.py
- **记忆体系、仓库认知与混合检索**：importance `high`
  - source_paths: velune/memory/module.py, velune/memory/tiers/working.py, velune/memory/tiers/episodic.py, velune/memory/tiers/semantic.py, velune/memory/tiers/graph.py
- **提供商适配、MCP 集成与扩展机制**：importance `high`
  - source_paths: velune/providers/base.py, velune/providers/registry.py, velune/providers/router.py, velune/providers/keystore.py, velune/providers/ollama_manager.py

## Repo Inspection Evidence / 源码检查证据

- repo_clone_verified: true
- repo_inspection_verified: true
- repo_commit: `2be547eb86f7ec4a350c1c0f2d571d705f7dcf93`
- inspected_files: `README.md`, `pyproject.toml`, `uv.lock`, `docs/ARCHITECTURE.md`, `docs/ARCHITECTURE_STARTUP.md`, `docs/CHANGELOG.md`, `docs/CODE_OF_CONDUCT.md`, `docs/CONTRIBUTING.md`, `docs/DEVELOPMENT.md`, `docs/SECURITY.md`, `docs/STARTUP_REFACTOR_MIGRATION.md`, `docs/THREAT_MODEL.md`

宿主 AI 硬性规则：
- 没有 repo_clone_verified=true 时，不得声称已经读过源码。
- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。
- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。

## Doramagic Pitfall Constraints / 踩坑约束

这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。

### Constraint 1: 可能修改宿主 AI 配置

- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。
- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- Evidence: capability.host_targets | https://github.com/Surya-Hariharan/Velune-CLI | host_targets=mcp_host, cursor
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 2: 能力判断依赖假设

- Trigger: README/documentation is current enough for a first validation pass.
- Host AI rule: 将假设转成下游验证清单。
- Why it matters: 假设不成立时，用户拿不到承诺的能力。
- Evidence: capability.assumptions | https://github.com/Surya-Hariharan/Velune-CLI | README/documentation is current enough for a first validation pass.
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 3: 运行可能依赖外部服务

- Trigger: 项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
- Host AI rule: 确认是否有离线 demo、mock 数据或可替代服务。
- Why it matters: 本地安装成功不等于能力可用，外部服务不可用会阻断体验。
- Evidence: packet_text.keyword_scan | https://github.com/Surya-Hariharan/Velune-CLI | matched external service / cloud / webhook / database keyword
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 4: 维护活跃度未知

- Trigger: 未记录 last_activity_observed。
- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。
- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- Evidence: evidence.maintainer_signals | https://github.com/Surya-Hariharan/Velune-CLI | last_activity_observed missing
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

- Trigger: no_demo
- Evidence: downstream_validation.risk_items | https://github.com/Surya-Hariharan/Velune-CLI | no_demo; severity=medium
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 6: 存在评分风险

- Trigger: no_demo
- Why it matters: 风险会影响是否适合普通用户安装。
- Evidence: risks.scoring_risks | https://github.com/Surya-Hariharan/Velune-CLI | no_demo; severity=medium
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 7: 来源证据：MCP Audit: Add MCP server support for tool integration

- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：MCP Audit: Add MCP server support for tool integration
- Why it matters: 可能影响授权、密钥配置或安全边界。
- Evidence: community_evidence:github | https://github.com/Surya-Hariharan/Velune-CLI/issues/9 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 8: issue/PR 响应质量未知

- Trigger: issue_or_pr_quality=unknown。
- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。
- Why it matters: 用户无法判断遇到问题后是否有人维护。
- Evidence: evidence.maintainer_signals | https://github.com/Surya-Hariharan/Velune-CLI | issue_or_pr_quality=unknown
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 9: 发布节奏不明确

- Trigger: release_recency=unknown。
- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。
- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。
- Evidence: evidence.maintainer_signals | https://github.com/Surya-Hariharan/Velune-CLI | release_recency=unknown
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。