1. 项目定位与设计目标

valis-cli 是一个面向工程团队决策管理的命令行与 MCP（Model Context Protocol）双形态工具。CLI 形式供开发者交互使用，MCP 形式供 AI Agent（如 Claude Code、Cursor、Aider）以工具调用方式访问同一套业务能力。两者共用配置、同一套服务端处理器。

CLI 实质是 MCP 的"薄外观"：它加载本地配置（.valis.json + Config Store），解析当前项目，再把请求转发到与 Agent 直接调用时完全相同的服务端处理器。批量操作（如 valis index 遍历本地目录）在 CLI 一侧完成，避免把 N 个文件通过 MCP 流式传输；高频调用则推荐 Agent 直接走 MCP，省去子进程开销 资料来源：src/commands/help-topics.ts:1-20。

为方便 Agent 在会话开始时构建能力图谱，CLI 暴露了 valis schema 命令，输出机器可读的指令目录（命令名、参数、选项、mutating 标志、phase 生命周期阶段），并刻意采用类 clispec.dev v0.1 的稳定形态，让任一 harness 仅需 20 行适配器即可消费 资料来源：src/commands/schema-cmd.ts:1-23。

2. 系统架构总览

整体架构由四层组成：交互层（CLI + MCP）、协调层（Handlers + 中间件）、持久层（Postgres + Qdrant）、推理层（FastEmbed 服务端嵌入 + 可选 LLM 增强）。

graph LR
    U[用户 / Agent] --> CLI["valis *<br/>CLI 命令"]
    U --> MCP["MCP 工具<br/>valis_search/store/..."]
    CLI -->|薄外观转发| H[Handlers]
    MCP -->|直接调用| H
    H -->|类型推断| TI[type-inference]
    H -->|语义去重| GTI[GroundTruthInjector]
    H -->|链接补全| LE[LinkExtractor]
    H --> PG[(Postgres<br/>真源)]
    H --> QD[(Qdrant<br/>向量 + 分块)]
    QD -->|FastEmbed| EMB[e5-small<br/>server-side]
    H -.可选.-> LLM[Haiku 增强]

Postgres 是 source of truth，Qdrant 仅承载向量索引与分块检索；写入路径采用"先 Postgres 后 Qdrant"的最终一致模式，并在 Qdrant 端按 1500 字符 + 200 重叠做段落→句子→硬切分的多级分块 资料来源：src/commands/index-cmd.ts:1-25、资料来源：src/cloud/qdrant/decisions.ts:1-50。

3. 核心数据流：决策写入管线

valis_store 是最复杂的数据流入口。handleStore 在真正落库前依次执行：

1. 类型推断：若调用方未指定 type，按正则优先级依次匹配 decision → constraint → pattern，默认回落到 lesson，并支持 FR-004~FR-007 的字段默认补全 资料来源：src/lib/type-inference.ts:1-20。
2. 计费闸门（fail-open）：调用 checkUsageOrProceed 检查额度；任何异常都被吞掉，确保计费故障不阻塞写入 资料来源：src/mcp/tools/store.ts:1-40。
3. replaces 校验：当请求声明替换某条决策时，验证目标存在且同属一个项目。
4. GroundTruthInjector 语义去重：在项目作用域内做向量检索，按相似度划分三档——[0.97, 1.0] 短路写、0.70, 0.97) 自动回填 depends_on、其余放行。该阈值历史从 0.92 调整到 0.97，源于混合领域个人语料下 0.92 误伤合法重录 资料来源：[src/mcp/tools/ground-truth-injector.ts:1-25。
5. LinkExtractor 链接补全：当调用方未显式提供 depends_on 时，基于向量邻居补全最多 3 条候选（默认阈值 0.7，硬超时 1500ms），任何异常折叠为 status: 'failed'，绝不阻塞写入 资料来源：src/mcp/tools/link-extractor.ts:1-20。
6. 双写：先入 Postgres，再以分块形式 upsert 到 Qdrant，并在 payload 中携带 contextual_text 与 hypothetical_query 用于增强检索质量 资料来源：src/cloud/qdrant/decisions.ts:1-50。

4. 模块划分与职责

辅助能力方面，admin consolidate 通过语义分组（默认阈值 0.7、--auto-merge 时降至 0.9）执行知识压缩，把若干决策合并为新 pattern 并把它们 deprecate 掉，所有动作写入 audit_entries 资料来源：src/commands/admin-consolidate.ts:1-25。verdict-queue 在 Agent 侧解析 bearer（tm_/tmm_ API key 兑换 JWT 或 OAuth 透传）后，向 verdict-queue Edge Function 列出待裁决项 资料来源：src/mcp/tools/verdict-queue.ts:1-20。add-command 则把 architect、security-advisor、product-manager 等多角色提示模板下发给插件侧的 Agent 资料来源：src/commands/add-command.ts:1-30。

See Also

• CLI ↔ MCP 工具对照：valis help mcp
• 入职工作流：valis help workflows
• Agent 能力目录：valis schema

决策捕获、存储与混合检索

Valis CLI 的核心数据通路是「决策（decision）」对象——一段带类型、影响面、置信度与作者信息的可检索知识单元。整个系统由三层组成：捕获层（CLI / MCP 工具 / 索引器）写入草稿；存储层（Postgres + Qdrant 双写，含分块与上下文增强）持久化；检索层（混合向量 + BM25 + 过滤 + 扩展）回读。下文按这三层展开。

MCP 工具、AI Agent 适配器与 APE 子系统

一、总体定位与设计目标

Valis 的目标是为 AI 编程代理提供"团队决策记忆"。CLI 是面向用户的薄壳，MCP（Model Context Protocol）工具 才是代理可以直接调用的核心接口；AI Agent 适配器 把不同代理框架（Claude Code、Codex、Cursor 等）的差异封装为统一契约；APE 子系统 则是该仓库内用于离线评估与优化代理行为的实验框架。三个层次共同构成"代理 ↔ Valis 后端"的完整链路。

CLI 与 MCP 的关系在仓库内被显式说明：CLI 是薄壳，加载配置、解析 .valis.json 中的项目，再把请求转发到与 MCP 处理函数共享的同一组实现（src/commands/help-topics.ts:32-52）。valis index 是少数仅有 CLI 形态的命令，因为批量遍历本地文件比通过 MCP 流式传输 N 个文件更高效（src/commands/help-topics.ts:54-60）。

二、MCP 工具层

MCP 工具分为"写"和"读"两类。读类工具（如 valis_search、valis_context、valis_check_duplicate、valis_get_taxonomy_spec、valis_list_projects）向代理暴露只读视图；写类工具（valis_store、valis_evolve、valis_lifecycle、valis_create_project）则执行实际的数据库或 Qdrant 修改（src/commands/schema-cmd.ts:24-32）。

写入路径中的关键中间件有两个：

1. LinkExtractor（valis_store 内部）：在写入前对决策正文做语义检索，自动追加 depends_on 关联。该模块承诺"Promise 永不 reject"——超时、检索错误、校验失败都会塌缩为 status: 'failed'，确保决策仍可写入，符合 Constitution III 的非阻塞原则（src/mcp/tools/link-extractor.ts:22-29）。
2. GroundTruthInjector：在写入前做语义去重，将候选文本与项目内现有决策做相似度比对，分入 duplicate/neighbour/none 三档。duplicate 档短路写入并返回既有 ID，neighbour 档正常写入并自动建立 depends_on（src/mcp/tools/ground-truth-injector.ts:14-26）。阈值历史上由 0.92 调整为 0.97（src/mcp/tools/ground-truth-injector.ts:26-33）。

valis_evolve 用于显式声明两个决策之间的有向关系（supersedes / builds_on / synthesizes / contradicts），直接插入 decision_edges 并写入审计；该路径不允许静默降级，跨组织的两个 ID 会被合并为相同的"未找到"错误，以避免被当成跨组织存在性预言机（src/mcp/tools/evolve.ts:11-18）。

verdict-queue 工具则把 Web 端的"Stage-A 评审队列"暴露给代理：列出待评审条目、解决条目、撤回解决。该机制遵循"先升级、再操作"——代理必须在调用 resolve/reverse 之前先与人类确认，工具调用本身就是那次明确确认（src/mcp/tools/verdict-queue.ts:11-17）。

三、AI Agent 适配器

适配器层把"代理调用了什么、何时调用、注入了什么上下文"这一类观测问题从代理实现中解耦。AgentAdapter 契约及其类型（ParsedSession、PatchDescriptor）从 ../types.js 统一再导出，避免实现与调用方各引一份（src/ape/agents/adapter.ts:7-15）。

目前唯一实现是 ClaudeCodeAdapter：它离线解析 Claude Code 的 JSONL 会话日志，识别两类信号——代理是否真的调用了 valis 工具（mcp__*valis*__valis_search|context|store|evolve|update_outcome|lifecycle），以及用户消息中是否携带 <valis_search_results> 注入块（src/ape/agents/claude-code.ts:26-32）。该实现坚守"不拦截 IDE 流"——只读取磁盘上的 JSONL（src/ape/agents/claude-code.ts:18-23）。

与适配器并行的是 add-command 目录下的内置代理模板：product-manager、architect、researcher、security-advisor、marketer 等十余个角色，按关键词匹配激活。它们的工作流都是"先 valis_search、再分析、最后 valis_store"的三段式（src/commands/add-command.ts:9-19）。

四、APE 评估子系统

APE（Agent Performance Evaluation）子系统当前围绕 Adapter 契约构建评估/优化机器；ClaudeCodeAdapter 即"被测代理"。其核心价值在于：让优化循环与具体代理实现解耦，未来加入新适配器时无需改写评估管线。模块自身仅薄薄一层再导出，详细类型定义在 ../types.js 中（src/ape/agents/adapter.ts:7-15）。

五、辅助：CLI 命令的机器可读契约

为方便代理一次性消费全部能力，valis schema 输出一份 JSON 目录，列出每条命令的入参、选项、是否变更状态、所属生命周期阶段（src/commands/schema-cmd.ts:21-40）。该目录形状参考了 clispec.dev v0.1，但仓库显式不声明完全兼容（src/commands/schema-cmd.ts:9-14）。

下表为最常用的 CLI ↔ MCP 映射（节选）：

资料来源：src/commands/help-topics.ts:32-52

六、典型调用流程

sequenceDiagram
    participant Agent as AI 代理
    participant MCP as MCP 工具层
    participant GTI as GroundTruthInjector
    participant LE as LinkExtractor
    participant DB as Postgres / Qdrant

    Agent->>MCP: valis_store(detail, summary)
    MCP->>GTI: 相似度比对
    GTI-->>MCP: duplicate / neighbour / none
    MCP->>LE: 检索依赖
    LE-->>MCP: chosen UUIDs 或 failed
    MCP->>DB: INSERT decision + edge
    DB-->>Agent: decision_id

See Also

• 仓库 README：README.md
• valis index 批量导入：src/commands/index-cmd.ts
• 类型推断：src/lib/type-inference.ts
• 初始化流程：src/commands/init/helpers.ts

自托管、管理操作与配置

概述

valis-cli 同时提供托管版（valis.krukit.co）与社区自托管版（Supabase + Qdrant + Docker Compose）两种部署形态（README.md:1-20）。本页聚焦自托管栈的初始化、valis admin * 子命令族与多层配置体系，帮助运维与集成方理解部署、治理与定制的方式。

1. 自托管栈与初始化

社区版可通过 community/ 目录的 docker compose up 一键拉起（README.md:14-18）。CLI 的 valis init 是用户首次进入自托管栈的总入口，src/commands/init/helpers.ts 把流程拆解为：模板选择（ts-saas / fintech / ai-agent）、starter decisions 种子注入、.valis.json 项目绑定、MCP 服务器配置写入以及 Claude / Codex / Cursor 等 IDE 适配器注入（init/helpers.ts:13-30）。

CLI 运行时受 engines 约束为 Node 20.x / 22.x / 24.x（package.json:53-55），并通过 exports 子路径（./mcp/server、./templates、./cloud/chunking 等）按需暴露模块（package.json:61-71），便于自托管场景下的子进程复用。

2. 管理操作（admin 子命令族）

valis admin * 与 Qdrant 后端模块共同承担数据治理。

• 知识合并 —— valis admin consolidate 走余弦相似度对决策做语义分组，默认阈值 0.7，--auto-merge 时对 >0.9 的组合自动合并：新建 pattern 决策、设 depends_on、原条目转 deprecated 并写审计日志（admin-consolidate.ts:1-19）。
• Qdrant 后台 —— cloud/qdrant/admin.ts 提供面板统计、project_id 回填（批大小 100）、reindex 与相似度探针（qdrant/admin.ts:9-31）。REINDEX_BATCH_SIZE 与 REINDEX_ABORT_THRESHOLD 集中定义在 embedding.ts，避免硬编码散落（qdrant/admin.ts:9-19）。
• 写入时去重 —— ground-truth-injector.ts 在 handleStore 内运行，将相似度分入 [0.97, 1.0] 短路写、0.70, 0.97) 自动填 depends_on、< 0.70 不变三档；阈值 2026-05-19 由 0.92 提升至 0.97，以避免跨域重录被误拦截（[ground-truth-injector.ts:1-23）。
• 裁决队列 —— verdict-queue.ts 暴露 list / resolve / reverse 三个工具，所有写入走 Web 端 RBAC，由人工通过工具调用显式确认（verdict-queue.ts）。
• 批量入库 —— valis index <folder> 走本地文件系统以避免 N 个文件流过 MCP（index-cmd.ts:1-15），并支持 --enrich / --use-git / --dry-run 脚本化参数（index-cmd.ts:23-33）。

下表汇总主要管理入口及其作用：

3. 配置体系

配置由三层组成：

• 全局配置 —— config/store.ts 的 loadConfig 加载 Supabase URL、API key 等连接信息（help-topics.ts:40-50）。
• 项目配置 —— config/project.ts 的 resolveConfig 根据 .valis.json 把当前目录绑定到指定 project（help-topics.ts:11-13）。
• CLI 元数据 —— schema-cmd.ts 输出 clispec 风格的机器可读命令目录，供 Cursor / Codex / Aider / Cline / Goose / OpenCode / Gemini CLI 等 agent harness 在会话开始时建立能力映射（schema-cmd.ts:1-12）。mutating 标志让 agent 用以门控写操作。

CLI 与 MCP 是薄封装关系：每个 CLI 命令都对应同名 MCP 工具。valis index 是例外（help-topics.ts:39-58）；valis_lifecycle、valis_store 等纯写命令没有 CLI 对应（help-topics.ts:40-55），全部由 agent 通过 MCP 调用。模板与角色方面，templates/index.ts 与 add-command.ts 分别承担模板检索与关键词角色注册——如 architect、product-manager、security-advisor 等（add-command.ts）。决策写入时附 contextual_text 与 hypothetical_query（HyPE）以提升检索质量（qdrant/decisions.ts）。

4. 常见失败模式

• 草稿计数截断 —— proposed-pending.ts 中的 lesson 104083be 指出，select() 后取 .length 在超过 PostgREST db-max-rows 上限时静默低估计数，必须用 select('id', { count: 'exact', head: true })（proposed-pending.ts）。
• 付费墙阻断 —— createProject 4xx 响应携带 upsell_url，调用方需原样透传并以非零退出码中断（members.ts）。
• 重索引失败 —— REINDEX_ABORT_THRESHOLD 触发后立即终止，避免大批量失败任务吞噬 Qdrant 配额（qdrant/admin.ts:9-19）。

参见

• 决策存储与检索：src/cloud/qdrant/decisions.ts
• 模板与 starter decisions：src/commands/init/helpers.ts
• 语义去重策略：src/mcp/tools/ground-truth-injector.ts
• CLI ↔ MCP 完整对照：src/commands/help-topics.ts

Pitfall Log / 踩坑日志

项目：Todmy/valis-cli

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

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

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

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

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

3. 维护坑 · 维护活跃度未知

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/Todmy/valis-cli | no_demo; severity=medium

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

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

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

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

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

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