# https://github.com/Todmy/valis-cli 项目说明书

生成时间：2026-06-18 14:57:38 UTC

## 目录

- [Project Overview and System Architecture](#page-1)
- [Decision Capture, Storage, and Hybrid Search](#page-2)
- [MCP Tools, AI Agent Adapters, and APE Subsystem](#page-3)
- [Self-Hosting, Admin Operations, and Configuration](#page-4)

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

## Project Overview and System Architecture

### 相关页面

相关主题：[Decision Capture, Storage, and Hybrid Search](#page-2), [Self-Hosting, Admin Operations, and Configuration](#page-4)

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

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

- [src/commands/index-cmd.ts](https://github.com/Todmy/valis-cli/blob/main/src/commands/index-cmd.ts)
- [src/commands/help-topics.ts](https://github.com/Todmy/valis-cli/blob/main/src/commands/help-topics.ts)
- [src/commands/schema-cmd.ts](https://github.com/Todmy/valis-cli/blob/main/src/commands/schema-cmd.ts)
- [src/commands/add-command.ts](https://github.com/Todmy/valis-cli/blob/main/src/commands/add-command.ts)
- [src/commands/admin-consolidate.ts](https://github.com/Todmy/valis-cli/blob/main/src/commands/admin-consolidate.ts)
- [src/cloud/qdrant/decisions.ts](https://github.com/Todmy/valis-cli/blob/main/src/cloud/qdrant/decisions.ts)
- [src/cloud/qdrant/admin.ts](https://github.com/Todmy/valis-cli/blob/main/src/cloud/qdrant/admin.ts)
- [src/cloud/supabase/proposed-pending.ts](https://github.com/Todmy/valis-cli/blob/main/src/cloud/supabase/proposed-pending.ts)
- [src/cloud/supabase/members.ts](https://github.com/Todmy/valis-cli/blob/main/src/cloud/supabase/members.ts)
- [src/lib/type-inference.ts](https://github.com/Todmy/valis-cli/blob/main/src/lib/type-inference.ts)
- [src/mcp/tools/store.ts](https://github.com/Todmy/valis-cli/blob/main/src/mcp/tools/store.ts)
- [src/mcp/tools/link-extractor.ts](https://github.com/Todmy/valis-cli/blob/main/src/mcp/tools/link-extractor.ts)
- [src/mcp/tools/ground-truth-injector.ts](https://github.com/Todmy/valis-cli/blob/main/src/mcp/tools/ground-truth-injector.ts)
- [src/mcp/tools/verdict-queue.ts](https://github.com/Todmy/valis-cli/blob/main/src/mcp/tools/verdict-queue.ts)
</details>

# Project Overview and System Architecture

## 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 增强）。

```mermaid
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. 模块划分与职责

| 模块 | 关键文件 | 主要职责 |
|------|----------|----------|
| 命令层 | `src/commands/*.ts` | 解析 argv、加载配置、转发到 MCP handlers；含 `index` 批量、`admin consolidate` 知识压缩、`add-command` Agent 角色模板 |
| MCP 工具层 | `src/mcp/tools/*.ts` | 提供 `valis_search`、`valis_store`、`valis_lifecycle`、`verdict-queue` 等 Agent 可调用工具 |
| 持久层 - Postgres | `src/cloud/supabase/*.ts` | 真源；处理项目创建、提案队列统计（truncation-proof COUNT + 按类型分桶）、成员与租户管理 |
| 持久层 - Qdrant | `src/cloud/qdrant/*.ts` | 向量 CRUD、分块、双写窗口、admin 迁移（`project_id` 回填、reindex、cosine probe） |
| 推理与配置 | `src/lib/*.ts`、`src/config/*.ts` | 类型推断、配置加载与项目解析（`.valis.json`） |

辅助能力方面，`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`

---

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

## Decision Capture, Storage, and Hybrid Search

### 相关页面

相关主题：[Project Overview and System Architecture](#page-1), [MCP Tools, AI Agent Adapters, and APE Subsystem](#page-3), [Self-Hosting, Admin Operations, and Configuration](#page-4)

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

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

- [src/commands/index-cmd.ts](https://github.com/Todmy/valis-cli/blob/main/src/commands/index-cmd.ts)
- [src/commands/help-topics.ts](https://github.com/Todmy/valis-cli/blob/main/src/commands/help-topics.ts)
- [src/commands/admin-consolidate.ts](https://github.com/Todmy/valis-cli/blob/main/src/commands/admin-consolidate.ts)
- [src/cloud/qdrant/decisions.ts](https://github.com/Todmy/valis-cli/blob/main/src/cloud/qdrant/decisions.ts)
- [src/cloud/qdrant/search.ts](https://github.com/Todmy/valis-cli/blob/main/src/cloud/qdrant/search.ts)
- [src/cloud/supabase/proposed-pending.ts](https://github.com/Todmy/valis-cli/blob/main/src/cloud/supabase/proposed-pending.ts)
- [src/lib/type-inference.ts](https://github.com/Todmy/valis-cli/blob/main/src/lib/type-inference.ts)
- [src/mcp/tools/ground-truth-injector.ts](https://github.com/Todmy/valis-cli/blob/main/src/mcp/tools/ground-truth-injector.ts)
- [src/mcp/tools/link-extractor.ts](https://github.com/Todmy/valis-cli/blob/main/src/mcp/tools/link-extractor.ts)
- [src/mcp/tools/evolve.ts](https://github.com/Todmy/valis-cli/blob/main/src/mcp/tools/evolve.ts)
</details>

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

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

---

## 一、捕获层：类型推断、注入式去重与批量导入

捕获层的入口是 `valis_store`（MCP 工具）与 CLI `valis index <folder>`。在写入前会执行两条防误入链：

1. **客户端类型推断**。[src/lib/type-inference.ts](https://github.com/Todmy/valis-cli/blob/main/src/lib/type-inference.ts) 用确定性正则按 `decision → constraint → pattern → lesson` 优先级匹配，匹配失败回退为 `lesson`，符合"核心操作不依赖 LLM"的原则。命中类型在写入时一并落到 Qdrant payload 的 `type` 字段（`src/cloud/qdrant/decisions.ts`）。
2. **注入式语义去重（Ground Truth Injector）**。[src/mcp/tools/ground-truth-injector.ts](https://github.com/Todmy/valis-cli/blob/main/src/mcp/tools/ground-truth-injector.ts) 在 `handleStore` 内部、项目范围内检索候选文本的近邻，并按相似度分桶：`[0.97, 1.0]` 视为 `duplicate` 直接短路返回既有 ID；`[0.70, 0.97)` 视为 `neighbour`，写入继续但自动填充 `depends_on`；`[0.00, 0.70)` 视为 `none` 透传。该阈值在 2026-05-19 从 0.92 调高到 0.97，以解决混合语料下"同一主题被新事实重新记录"被误拦截的问题（BACKLOG #181 跟踪后续更细粒度的克隆边替换）。

批量导入走 `valis index <folder>`（[src/commands/index-cmd.ts](https://github.com/Todmy/valis-cli/blob/main/src/commands/index-cmd.ts)）：递归遍历 `.md / .markdown`，从首个 H1 提取 `summary`、整段正文作为 `detail`，可选 `--use-git` 通过 `git log` 抽取作者与首次提交时间。无前缀的文件默认以 `status='proposed'` 入队至草稿队列等待分诊，命中 `decision-/pattern-/constraint-/lesson-/postmortem-` 前缀的文件则按前缀推断类型。导入后可选 LLM 增强（Haiku 分类 + 摘要 + 影响面抽取 + 置信度评分），并在询问前显示 token 估算与美元成本。

---

## 二、存储层：双写、分块与上下文增强

写入路径采用 Postgres（source-of-truth） + Qdrant（检索副本）的双写模型。[src/cloud/qdrant/decisions.ts](https://github.com/Todmy/valis-cli/blob/main/src/cloud/qdrant/decisions.ts) 中 `upsertDecision` 在落库前构造两个文本字段以提升检索质量：

- `contextual_text = buildContextualText(raw.text, raw.type, raw.affects)`——把类型与影响面标签拼接到正文前，得到更稠密的嵌入。
- `hypothetical_query = generateHypotheticalQuery(raw)`——为每条决策生成一个 HyPE（hypothetical prompt embedding）查询式。

长决策按 `chunkText` 切片（1500 字符 + 200 重叠，段落→句子→硬切）后，每片以独立 Qdrant point 写入，point id 通过 `chunkPointId(decisionId, chunkIndex)` 派生。Payload 包含 `org_id / type / summary / detail / contextual_text / hypothetical_query / author / affects / confidence / pinned / depends_on / replaces / status / source / outcome / created_at`，并在提供 `projectId` 时附带 `project_id` 以支持项目级过滤。

无前缀批量导入的草稿落入 `proposed-pending` 队列。[src/cloud/supabase/proposed-pending.ts](https://github.com/Todmy/valis-cli/blob/main/src/cloud/supabase/proposed-pending.ts) 用 PostgREST 的 `status.eq.proposed,type.eq.pending` 谓词聚合，count 与 `by_type` 全部走服务端 `count: 'exact'`，避免对超大表用 `.length` 静默欠数（教训 `104083be`）；任意异常按 Constitution III 返回 `null` 让调用方整块省略而非伪造零值。

```mermaid
flowchart LR
  A[valis_store / valis index] --> B[类型推断]
  B --> C[Ground Truth Injector]
  C -->|duplicate| Z[短路返回既有 ID]
  C -->|neighbour / none| D[LinkExtractor 补充 depends_on]
  D --> E[Postgres 写入]
  E --> F[Qdrant 双写]
  F --> G1[contextual_text 嵌入]
  F --> G2[HyPE hypothetical_query]
  F --> G3[按 1500+200 分块 → 多 point]
```

---

## 三、检索层：项目级混合查询与关系维护

读取路径在 [src/cloud/qdrant/search.ts](https://github.com/Todmy/valis-cli/blob/main/src/cloud/qdrant/search.ts) 中实现。`buildProjectFilter` 构造 `org_id` 必选 + 可选 `project_id` 的过滤子句，迁移期通过 `legacyFallback` 兼容无 `project_id` 的历史 point。查询是 hybrid 模式：稠密向量（`DENSE_VECTOR_NAME`）叠加 BM25 稀疏向量（`BM25_VECTOR_NAME`），结合 `type / status / affects / pinned` 等 payload 过滤。

显式关系维护由 [src/mcp/tools/evolve.ts](https://github.com/Todmy/valis-cli/blob/main/src/mcp/tools/evolve.ts) 提供的 `valis_evolve` 工具承担，支持 `supersedes / builds_on / synthesizes / contradicts` 四种 `decision_edges` 边类型，写入一行边 + 一条审计；跨组织访问的"未找到"与"不同 org"返回相同错误以避免存在性泄露。[src/mcp/tools/link-extractor.ts](https://github.com/Todmy/valis-cli/blob/main/src/mcp/tools/link-extractor.ts) 则是写入时的隐式 `depends_on` 提取器，泛型于 `SearchFn`、永不拒绝（超时 / 错误统一收敛为 `status: 'failed'`），保证 Constitution III 的非阻塞承诺。

检索结果可通过 `expand='siblings'` 拉取同决策其他 chunk 的上下文；最终在仪表盘的 Proposals 标签中，[src/commands/admin-consolidate.ts](https://github.com/Todmy/valis-cli/blob/main/src/commands/admin-consolidate.ts) 的 `valis admin consolidate` 进一步通过语义聚类与 0.7/0.9 阈值合并高度重叠的决策群组（dry-run 默认开启，`--auto-merge` 才真正写入），并把被合并条目置为 `status='deprecated'` 以保留历史可审计性。

---

## 四、典型端到端工作流

[src/commands/help-topics.ts](https://github.com/Todmy/valis-cli/blob/main/src/commands/help-topics.ts) 给出了官方推荐的三段式流程：

1. **Onboarding**：`valis init --template ts-saas` 写入 18 条种子决策 → `valis switch --project <name>` 绑定 cwd → `valis index ./docs` 批量导入既有 Markdown → `valis search "postgres"` 验证可见。
2. **Capture loop**：`valis search "<topic>"` 排查既有 → 通过 IDE 插件触发 `/valis:store "<decision>"`（调用 `valis_store`）→ 再 search 验证。
3. **Lifecycle curation**：仪表盘 Proposals 标签人工 promote / dismiss，或调用 `valis_lifecycle({action: 'promote', decision_id})`；`valis admin consolidate --auto-merge` 处理长期积累的语义重复。

---

## 参见

- [CLI Schema & Machine-Readable Catalog](./schema-cli-catalog.md)
- [MCP Tools & Agent Integration](./mcp-tools-and-integration.md)
- [Project Scoping & Access Control](./project-scoping-and-access.md)

---

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

## MCP Tools, AI Agent Adapters, and APE Subsystem

### 相关页面

相关主题：[Project Overview and System Architecture](#page-1), [Decision Capture, Storage, and Hybrid Search](#page-2), [Self-Hosting, Admin Operations, and Configuration](#page-4)

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

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

- [src/mcp/tools/evolve.ts](https://github.com/Todmy/valis-cli/blob/main/src/mcp/tools/evolve.ts)
- [src/mcp/tools/verdict-queue.ts](https://github.com/Todmy/valis-cli/blob/main/src/mcp/tools/verdict-queue.ts)
- [src/mcp/tools/ground-truth-injector.ts](https://github.com/Todmy/valis-cli/blob/main/src/mcp/tools/ground-truth-injector.ts)
- [src/mcp/tools/link-extractor.ts](https://github.com/Todmy/valis-cli/blob/main/src/mcp/tools/link-extractor.ts)
- [src/commands/schema-cmd.ts](https://github.com/Todmy/valis-cli/blob/main/src/commands/schema-cmd.ts)
- [src/commands/help-topics.ts](https://github.com/Todmy/valis-cli/blob/main/src/commands/help-topics.ts)
- [src/commands/add-command.ts](https://github.com/Todmy/valis-cli/blob/main/src/commands/add-command.ts)
- [src/ape/agents/adapter.ts](https://github.com/Todmy/valis-cli/blob/main/src/ape/agents/adapter.ts)
- [src/ape/agents/claude-code.ts](https://github.com/Todmy/valis-cli/blob/main/src/ape/agents/claude-code.ts)
- [src/lib/type-inference.ts](https://github.com/Todmy/valis-cli/blob/main/src/lib/type-inference.ts)
</details>

# 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](https://github.com/Todmy/valis-cli/blob/main/src/commands/help-topics.ts)）。`valis index` 是少数仅有 CLI 形态的命令，因为批量遍历本地文件比通过 MCP 流式传输 N 个文件更高效（[src/commands/help-topics.ts:54-60](https://github.com/Todmy/valis-cli/blob/main/src/commands/help-topics.ts)）。

## 二、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](https://github.com/Todmy/valis-cli/blob/main/src/commands/schema-cmd.ts)）。

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

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

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

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

## 三、AI Agent 适配器

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

目前唯一实现是 `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](https://github.com/Todmy/valis-cli/blob/main/src/ape/agents/claude-code.ts)）。该实现坚守"不拦截 IDE 流"——只读取磁盘上的 JSONL（[src/ape/agents/claude-code.ts:18-23](https://github.com/Todmy/valis-cli/blob/main/src/ape/agents/claude-code.ts)）。

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

## 四、APE 评估子系统

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

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

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

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

| CLI 命令 | MCP 工具 | 只读 |
|---|---|---|
| `valis search` | `valis_search` | 是 |
| `valis index` | （CLI 独占，循环调用 `valis_store`） | 否 |
| `valis init` | `valis_create_project` | 否 |
| `valis switch` | `valis_lifecycle` | 否 |

资料来源：[src/commands/help-topics.ts:32-52](https://github.com/Todmy/valis-cli/blob/main/src/commands/help-topics.ts)

## 六、典型调用流程

```mermaid
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](https://github.com/Todmy/valis-cli/blob/main/README.md)
- `valis index` 批量导入：[src/commands/index-cmd.ts](https://github.com/Todmy/valis-cli/blob/main/src/commands/index-cmd.ts)
- 类型推断：[src/lib/type-inference.ts](https://github.com/Todmy/valis-cli/blob/main/src/lib/type-inference.ts)
- 初始化流程：[src/commands/init/helpers.ts](https://github.com/Todmy/valis-cli/blob/main/src/commands/init/helpers.ts)

---

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

## Self-Hosting, Admin Operations, and Configuration

### 相关页面

相关主题：[Project Overview and System Architecture](#page-1), [Decision Capture, Storage, and Hybrid Search](#page-2), [MCP Tools, AI Agent Adapters, and APE Subsystem](#page-3)

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

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

- [README.md](https://github.com/Todmy/valis-cli/blob/main/README.md)
- [package.json](https://github.com/Todmy/valis-cli/blob/main/package.json)
- [src/commands/init/helpers.ts](https://github.com/Todmy/valis-cli/blob/main/src/commands/init/helpers.ts)
- [src/commands/admin-consolidate.ts](https://github.com/Todmy/valis-cli/blob/main/src/commands/admin-consolidate.ts)
- [src/cloud/qdrant/admin.ts](https://github.com/Todmy/valis-cli/blob/main/src/cloud/qdrant/admin.ts)
- [src/cloud/qdrant/decisions.ts](https://github.com/Todmy/valis-cli/blob/main/src/cloud/qdrant/decisions.ts)
- [src/commands/schema-cmd.ts](https://github.com/Todmy/valis-cli/blob/main/src/commands/schema-cmd.ts)
- [src/commands/help-topics.ts](https://github.com/Todmy/valis-cli/blob/main/src/commands/help-topics.ts)
- [src/commands/index-cmd.ts](https://github.com/Todmy/valis-cli/blob/main/src/commands/index-cmd.ts)
- [src/mcp/tools/ground-truth-injector.ts](https://github.com/Todmy/valis-cli/blob/main/src/mcp/tools/ground-truth-injector.ts)
- [src/mcp/tools/verdict-queue.ts](https://github.com/Todmy/valis-cli/blob/main/src/mcp/tools/verdict-queue.ts)
- [src/cloud/supabase/proposed-pending.ts](https://github.com/Todmy/valis-cli/blob/main/src/cloud/supabase/proposed-pending.ts)
- [src/cloud/supabase/members.ts](https://github.com/Todmy/valis-cli/blob/main/src/cloud/supabase/members.ts)
- [src/commands/add-command.ts](https://github.com/Todmy/valis-cli/blob/main/src/commands/add-command.ts)
</details>

# 自托管、管理操作与配置

## 概述

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]()）。

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

| 命令 / 模块 | 作用 | 关键配置 |
| --- | --- | --- |
| `valis admin consolidate` | 语义合并冗余决策 | `--threshold` 默认 0.7；`--auto-merge` 触发 0.9 合并 |
| `valis admin reindex`（Qdrant） | 重新计算嵌入并回写 | `REINDEX_BATCH_SIZE`（embedding.ts） |
| `valis init --template <id>` | 种子化 starter decisions | `ts-saas` / `fintech` / `ai-agent` |
| `valis index <folder>` | 批量导入 markdown | `--enrich` / `--use-git` / `--dry-run` |

## 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]()

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

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

<!-- canonical_name: Todmy/valis-cli; human_manual_source: deepwiki_human_wiki -->