Agent 可以询问的内容 · 快速开始 · Pipeline · 工具 · 架构 · Zetetic 标准
关联项目：
Cortex — 持久化记忆，可跨会话进行整合与重新整合
zetetic-team-subagents — 97 个天才推理 agent + 18 个团队专家
prd-spec-generator — TypeScript PRD 生成器，使用我们的图谱智能
每个 AI 编程助手都会遇到同样的瓶颈：你让它修改 `handle_tool_call`，它要么产生幻觉，捏造出一个上周已经被重命名的函数；要么在错误的代码社区中进行修改；要么悄无声息地破坏了三个模块之外的一条调用链。Agent 操作的是字符串；而代码库是有结构的。这个差距正是 bug 滋生的地方。
**automatised-pipeline** 是一个 Rust MCP 服务器，它将任何 Rust / Python / TypeScript 代码库索引到 LadybugDB 属性图中，解析跨文件的导入和调用链，通过 Leiden 类社区检测算法识别功能社区，从入口点追踪执行流，构建混合 BM25 + 稀疏 TF-IDF + RRF 搜索索引，并通过 23 个 MCP 工具将这一切暴露给 AI agent。
它是位于发现（“存在此 bug”）和 PRD（“这是修复方案，这是它影响的范围，这是它绝不能破坏的内容”）之间的**代码库智能层**。它是**只读智能**——它绝不编写代码、提交 PR 或运行 CI。它告诉系统关于代码的真实情况，以便下一阶段可以进行推理而无需猜测。
**一个 pipeline 阶段 = 一个 MCP 工具。10 个阶段。23 个工具。12,000 多行 Rust 代码。220 个测试。零警告。每个常量均有出处。**
## Agent 可以询问它的内容
```
analyze_codebase(path: "/path/to/project", output_dir: "/tmp/run")
→ index + resolve + cluster + build search index in one call
→ 430 nodes, 400 edges, 216 communities, 35 processes on our own codebase
search_codebase(graph_path, query: "process incoming tool requests")
→ hybrid ranked results: BM25 lexical + sparse TF-IDF semantic + RRF fusion
→ returns: handle_tool_call (score 0.021), dispatch_request (0.020), ...
get_context(graph_path, qualified_name: "src/main.rs::handle_tool_call")
→ 360° view: community membership, process participation,
incoming calls, outgoing calls, types used, types that use it
→ did-you-mean suggestions when the symbol isn't found exactly
get_impact(graph_path, qualified_name)
→ blast radius: every process that transits this symbol, every community it touches
→ the answer to "what breaks if I change this?"
detect_changes(graph_path, diff_text OR base_ref+head_ref)
→ git diff → affected symbols → impacted communities → touched processes
→ risk score for the change
validate_prd_against_graph(prd_path, graph_path)
→ does the PRD reference real symbols? (symbol hallucination check)
→ does "scoped to X" match the actual community count?
→ does "doesn't affect main" hold against the call graph?
check_security_gates(graph_path, changed_symbols)
→ auth-critical community touch · unsafe symbol · public API change ·
unresolved imports · test coverage gap
verify_semantic_diff(before_graph_path, after_graph_path)
→ what nodes/edges appeared, what disappeared, what dangles,
new cycles via Tarjan SCC, regression score with verdict
```
## 快速开始
### 前置条件
- Rust 1.94+ (`rustup install stable`)
- CMake (LadybugDB 从源码构建其 C++ 核心 — 首次构建约 5 分钟，之后会缓存)
### 克隆 + 构建
```
git clone https://github.com/cdeust/automatised-pipeline.git
cd automatised-pipeline
cargo build --release
# 首次构建：~5 分钟（编译 LadybugDB C++ core）
# 后续构建：<1 秒增量
```
### 注册 MCP 服务器
仓库自带 `.mcp.json` 文件，当你打开该目录时，Claude Code 会自动识别它：
```
{
"mcpServers": {
"ai-architect": {
"command": "cargo",
"args": ["run", "--quiet", "--release", "--manifest-path", "Cargo.toml"]
}
}
}
```
或者全局注册：
```
claude mcp add ai-architect -- /absolute/path/to/target/release/ai-architect-mcp
```
### 首次运行
```
# 直接运行二进制文件以验证 handshake
./target/release/ai-architect-mcp
# 或通过 stdio JSON-RPC 进行测试：
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
'{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"health_check","arguments":{}}}' \
| ./target/release/ai-architect-mcp
```
## Pipeline
每个阶段都是一个工具。各阶段相互构建，但可独立调用。Pipeline 在逻辑上是串行顺序的，但 MCP 调用是无状态的 — 你可以在全新的代码库上重新运行阶段 3a-3d，而无需重新运行阶段 1-2。
| # | 工具 | 功能描述 |
|---|---|---|
| **0** | `health_check` | 握手 + 协议 + 工具数量 |
| **1** | `extract_finding`, `refine_finding` | 确定性发现提取 + 感知编排器的提示词优化 |
| **2** | `start_verification`, `append_clarification`, `finalize_verification`, `abort_verification` | 人工把关的澄清循环，带有 SHA-256 记录摘要和原子级单文件会话状态 |
| **3a** | `index_codebase`, `query_graph`, `get_symbol` | tree-sitter AST → LadybugDB 图谱（16 种节点标签，36+ 关系表） |
| **3b** | `resolve_graph`, `lsp_resolve` | 带置信度评分的导入/调用/impl 解析 + 可选的 LSP 深度解析 (rust-analyzer / pyright / typescript-language-server) |
| **3c** | `cluster_graph`, `get_processes`, `get_impact` | Leiden 类社区检测 (Louvain + C2 修复) + 从入口点进行 BFS 执行流追踪 |
| **3d** | `search_codebase`, `get_context`, `analyze_codebase`, `detect_changes` | 混合 BM25 + 稀疏 TF-IDF + RRF 搜索 · 360° 符号视图 · 多合一分析 · git-diff 影响 |
| **4** | `prepare_prd_input` | 将已验证的发现 + 图谱智能打包 → 供 prd-spec-generator 使用的 artifact |
| **6** | `validate_prd_against_graph` | 符号幻觉 · 社区一致性 · 流程影响矛盾 |
| **8** | `check_security_gates` | 验证关键社区 · 不安全符号 · 公共 API 变更 · 引入未解析的导入 · 测试覆盖率缺口 |
| **9** | `verify_semantic_diff` | 前后图谱差异对比，采用 Tarjan SCC 环检测和回归评分 |
## 23 个 MCP 工具
每个工具通过 MCP 协议接收结构化的 JSON 参数，并返回结构化的 JSON 响应。任何工具内部都不会调用 LLM — 智能推理是 agent 的工作；工具的工作是带有不变量的安全、快速的数据传输。
```
Stage 0: health_check
Stage 1: extract_finding · refine_finding
Stage 2: start_verification · append_clarification · finalize_verification · abort_verification
Stage 3a: index_codebase · query_graph · get_symbol
Stage 3b: resolve_graph · lsp_resolve
Stage 3c: cluster_graph · get_processes · get_impact
Stage 3d: search_codebase · get_context · analyze_codebase · detect_changes
Stage 4: prepare_prd_input
Stage 6: validate_prd_against_graph
Stage 8: check_security_gates
Stage 9: verify_semantic_diff
```
每个工具在通信层面上都强制执行 JSON Schema，错误时提供原因代码（绝不晦涩难懂的协议错误），并返回带有时间和计数的收据式响应。
## 架构
Rust MCP 服务器，手工实现的 stdio JSON-RPC 2.0（不使用 SDK — 我们完全掌控底层通信）。采用具有模块边界的整洁架构。
```
transport (stdio, JSON-RPC framing)
↓
server/main.rs (request dispatch, tool registry)
↓
handlers (do_* functions, one per tool)
↓
core modules:
graph_store — LadybugDB port (Cypher + UNWIND + prepared statements)
parser/{rust,python,typescript,mod} — tree-sitter AST extractors
indexer — walk + parse + persist pipeline
resolver — cross-file import/call/impl resolution
lsp_{client,resolver} — optional LSP deep resolution
clustering — inline Louvain + C2 repair + process tracing
search/{bm25,vector,rrf,mod} — hybrid search (Tantivy + sparse TF-IDF + RRF)
prd_input — stage 4: bundle for prd-spec-generator
prd_validator — stage 6: validate PRD claims against graph
security_gates — stage 8: auth/unsafe/API/imports/coverage checks
semantic_diff — stage 9: before/after graph regression scoring
git_diff — diff parser + symbol mapping
```
### Crates
八个 crate。没有投机性的内容；一切都事出有因。
| Crate | 用途 | 许可证 | 原因 |
|---|---|---|---|
| `serde` + `serde_json` | 通信序列化 | MIT | JSON-RPC、artifact 持久化 |
| `sha2` | 阶段 2 记录摘要 | MIT | 防篡改检测 |
| `lbug` (LadybugDB) | 嵌入式属性图 + Cypher | MIT | 原生 Cypher，支持 FTS，Kùzu 的继任者 |
| `tree-sitter` | 增量解析器运行时 | MIT | 一流的 Rust 绑定 |
| `tree-sitter-rust` · `-python` · `-typescript` | 语言语法 | MIT | 无需编译器即可获取语义结构 |
| `tantivy` | Lucene 级别的 BM25 | MIT | 真正的排序文本搜索，启动时间 <10ms |
刻意**不**包含的内容：async runtime（我们采用 stdio 阻塞模式）、HTTP 客户端、LLM SDK、embedding 模型运行时（以零依赖成本用稀疏 TF-IDF 替代了它）。
### 存储
根据设计，图谱是针对每个发现的（Lamport 的隔离不变量）：每个发现都有自己的 LadybugDB 实例，位于 `
/runs//findings//graph/`。零协调并发，清理极其简单，没有跨发现的状态泄漏。针对共享代码库的冗余索引已被认知，并在随后的可选缓存层中进行了缓解 — 并未生硬地塞入核心模块中。
## Zetetic 标准
继承自 [zetetic-team-subagents](https://github.com/cdeust/zetetic-team-subagents)。这不是一个提示词建议 — 而是一条在代码中强制执行的规则。
| 支柱 | 问题 |
|---|---|
| **逻辑** | *它是一致的吗？* |
| **批判** | *它是真的吗？* |
| **理性** | *它有用吗？* |
| **本质** | *它是必要的吗？* |
**在本代码库中，它具体意味着：**
1. 每个算法都能溯源。Louvain → *Blondel et al. 2008*。Leiden C2 修复 → *Traag et al. 2019*。RRF → *Cormack, Clarke, Büttcher 2009*。SCC → *Tarjan 1972*。基于 Tantivy 的 BM25 → *Robertson et al. 1994*。
2. 每个具名常量都有 `// source:` 注释。`RRF_K = 60` 引用了 Cormack 2009。`BULK_BATCH_SIZE = 500` 引用了 Kùzu/LadybugDB 调优。`PARSE_TIMEOUT_MICROS = 5_000_000` 在其上方的块中给出了理由。
3. 绝不凭空捏造数字。当某个值是基于判断选择的，注释会如实说明（“启发式方法，非论文支持”）并引用其实际操作的理由。
4. 工具响应会引用管理每个错误原因的规范。`unsafe finding_id (spec §5.1.4, §9.3 Q4): must match [A-Za-z0-9._-]+` — 调用者能看到自己违反了哪条规则。
5. 当某项功能在规范阶段无法被证明时，工具会优雅降级并用通俗易懂的语言予以说明。示例：在 stub 二进制文件上运行 `lsp_resolve` 会返回 `lsp_probe_failed: found on PATH but didn't respond as an LSP server (stdout closed immediately; likely a stub, proxy, or non-LSP binary)` — 而不是一个晦涩难懂的协议错误。
## 安全性
在一次 `security-auditor` agent 检查中发现了四个 CRITICAL、四个 HIGH 和三个 MEDIUM 级别的问题，并已在提交 [`512d683`](https://github.com/cdeust/automatised-pipeline/commit/512d683) 中修复：
- 通过 `insert_edge` 引发的 Cypher 注入 → 集中化的 `cypher_str()` 转义（先转义 `\`，然后是 `'`）
- Git 参数注入 → `validate_git_ref` 拒绝 `--`、换行符、NUL；在 refs 前使用 `--` 分隔符
- 通过 `lsp_command` 执行任意二进制文件 → 严格的白名单（`rust-analyzer`、`pyright`、`pyright-langserver`、`typescript-language-server`）
- 符号链接遍历 → `fs::symlink_metadata` + `MAX_DEPTH`
- 资源耗尽 → `MAX_FILES=100_000`、`MAX_FILE_BYTES=10 MB`、`MAX_TOTAL_BYTES=2 GB`、`MAX_DEPTH=64`
- tree-sitter 病态输入 → `set_timeout_micros(5_000_000)` + `MAX_PARSE_BYTES=1 MB`
- `query_graph` 只读 → 针对全词过滤器的禁用关键字 (CREATE/DELETE/MERGE/SET/REMOVE/DROP/ALTER/CALL/LOAD)
- `graph_path` 文件系统安全 → 在执行任何 `remove_dir_all` 前调用 `validate_graph_path_safe()`
- LSP `rootUri` → RFC 3986 百分号编码
- Diff 行溢出 → `DIFF_LINE_MAX = u64::MAX / 2` 防护
每个修复都包含一个测试，用于断言漏洞利用现已被拒绝。运行 `cargo test` 即可看到 220 个测试通过，其中包括漏洞利用回归测试套件。
## 规模
由 `dba` agent 通过针对 lbug 0.15.3 进行编译并运行探测验证得出：
| 策略 | ms/edge |
|---|---|
| 每条边使用原始字符串（朴素方法） | 5.36 |
| 预处理语句，无事务 | 5.48 |
| `BEGIN TRANSACTION` + 预处理 + `COMMIT` | 0.70 |
| **UNWIND + 类型化 `LogicalType::Struct`** | **0.143** |
批量插入路径使用了带有类型化 struct schema 的 UNWIND（编写初版的工程师使用了 `LogicalType::Any`，但这会导致 binder 失败 — 类型化 struct 形式则有效）。预处理语句缓存在 `GraphStore` 的 `RefCell>` 中。稀疏 TF-IDF 取代了密集的 `N × V × 4B` 矩阵 — 在我们自己的代码库上**小了 30.5 倍**（108 KB 对比 3.2 MB），并且随非零项数量而不是词表大小呈线性扩展。集群分析消除了 `probe_node_label_for_process`（按节点进行 Cypher 往返），改为单次填充内存中的 `HashMap`。
包含 500 个文件的合成 Rust 测试夹具端到端（解析 + 解析 + 集群 + 搜索索引）索引耗时约 **~38 秒**，相比审计前暗示的“5 分钟 - 1 小时”区间大幅缩短。
## 与栈其余部分的集成
```
┌─────────────────────────────────────────┐
│ Claude Code agent │
└────────────┬────────────────────────────┘
│ MCP (stdio JSON-RPC)
↓
┌──────────────────────────────────────────────────┐
│ automatised-pipeline │ ← this repo
│ stage 0 · 1 · 2 · 3a-d · 4 · 6 · 8 · 9 │
│ Rust · LadybugDB · tree-sitter · Tantivy │
└──────┬──────────────────┬────────────────────────┘
│ │
│ └────→ stage 5 (PRD gen)
│ [prd-spec-generator]
↓ TypeScript / Node
┌─────────────────┐ │
│ Cortex │ │
│ memory engine │ ←──────────────────┘
│ PostgreSQL + │
│ pgvector │
└─────────────────┘
↑
│ cross-session memory for findings,
│ decisions, lessons learned
│
┌─────────────────────────────┐
│ zetetic-team-subagents │
│ 97 genius + 18 specialists │
│ problem-shape routing │
└─────────────────────────────┘
```
- **Cortex** — pipeline 运行期间做出的每一个架构决策都会被记录下来。当下一个发现涉及相似领域时，Cortex 会在你重新推导之前提供先前的推理。
- **zetetic-team-subagents** — 天才 agent（Shannon、Lamport、Simon、Popper、Feynman、Fermi、dba、architect、security-auditor、engineer）逐步设计了这个项目。`stages/*.md` 中的每一个重大决策都能追溯到一次 agent 分发。
- **prd-spec-generator** — 通过磁盘或 MCP 到 MCP 查询 `search_codebase` / `get_context` / `get_impact` 的方式，使用我们的 `stage-4.prd_input.json` artifact。各自使用其最理想的语言：我们性能关键的图谱工作使用 Rust，他们的文档生成使用 TypeScript。
## 测试
```
cargo test # 220 tests, full suite
cargo test --release --test scalability_bench # 500-file synthetic fixture
cargo test --release --test lbug_bulk_investigation # dba's 9 UNWIND probes
cargo test --release --test stage3a_integration # end-to-end per sub-stage
cargo test --release --test stage9_integration # before/after diff
cargo check # zero warnings required
cargo build --release # release binary
```
每个阶段都有带测试夹具数据的集成测试。`lbug_bulk_investigation` 测试被特意保留了下来 — 它是 dba 的 UNWIND 模式有效的编译并运行证明，保留它是为了回归保护和文档记录。
## 仓库布局
```
automatised-pipeline/
├── src/
│ ├── main.rs ← MCP server, 23 tool handlers
│ ├── tool_schemas.rs ← JSON Schemas for every tool
│ ├── lib.rs ← re-exports for integration tests
│ ├── graph_store.rs ← LadybugDB port (UNWIND + prepared + cached)
│ ├── parser/
│ │ ├── mod.rs ← language dispatch
│ │ ├── rust.rs · python.rs · typescript.rs
│ ├── indexer.rs ← walk + parse + persist
│ ├── resolver.rs ← cross-file resolution
│ ├── lsp_client.rs ← minimal LSP probe + client
│ ├── lsp_resolver.rs ← LSP-backed deep resolution
│ ├── clustering.rs ← Louvain + C2 repair + BFS process tracing
│ ├── search/
│ │ ├── mod.rs ← orchestration, get_context, 3-layer qn lookup
│ │ ├── bm25.rs · vector.rs · rrf.rs
│ ├── prd_input.rs ← stage 4
│ ├── prd_validator.rs ← stage 6
│ ├── security_gates.rs ← stage 8
│ ├── semantic_diff.rs ← stage 9
│ └── git_diff.rs ← diff parsing + symbol mapping
├── stages/ ← locked spec per stage (Shannon, then engineer implements)
│ ├── stage-1.md · stage-2.md · stage-3.md · stage-3b.md · stage-3c.md
│ ├── stage-6.md · stage-8.md
│ ├── stage-1.review.md · stage-3-db-evaluation.md · stage-3-research.md
│ └── decisions/ ← Popper / Lamport / Simon verdicts per decision
├── tests/
│ ├── stage{3a,3b,3c,3d,4,6,8,9}_integration.rs
│ ├── multilang_integration.rs
│ ├── stage3d_hybrid_search.rs
│ ├── scalability_bench.rs
│ ├── lbug_bulk_investigation.rs
│ ├── tfidf_size_report.rs
│ └── fixtures/multilang/ ← sample.rs · sample.py · sample.ts
├── .claude/
│ ├── agents/ ← 18 specialists + 97 genius agents
│ ├── skills/ · commands/ · tools/ · hooks/
│ └── scripts/
├── .mcp.json
├── NOTES.md ← stages table + growth rule
├── Cargo.toml
└── README.md
```
## 构建背后的 Zetetic 决策
每一项重大架构决策都是由具有特定问题形态的天才 agent 做出的。存储在 `stages/decisions/*.md` 和 Cortex 中。
| 决策 | Agent | 结论 |
|---|---|---|
| 粘合层选择 Rust vs C/C++ | **Popper** | “Rust 是合适的语言”这一猜想未被证伪。`lbug` + `tree-sitter` 已经运行原生 C/C++；Rust 是 borrow checker 回报最大的粘合层。 |
| 每个发现一个图 vs 每个代码库一个图 | **Lamport** | 每个发现一个图。隔离性在结构上得以保持，无需任何协调；冗余索引成本可在以后的可选缓存层中得到缓解。 |
| 阶段 3a 分解 | **Simon** | 五个步骤，满足于增长规则；在第 4 步即可进行首次有用的查询。 |
| 数据库后端选择 | **dba** | LadybugDB (`lbug 0.15.3`) — 同时兼顾维护、原生 Cypher、嵌入式且具备 FTS + 向量 + 算法扩展的唯一选择。 |
| 阶段 2 澄清循环形态 | **Shannon** | 四工具状态机，具有原子级单文件会话（独立文件之间无崩溃窗口），在结束前无条件保证最少一轮交互。 |
| lbug UNWIND 模式 | **dba** | `LogicalType::Struct { fields }` 有效；`LogicalType::Any` 会导致 binder 失败 — 通过编译并运行探测验证了 38 倍的加速。 |
Agent 通过 [zetetic-team-subagents](https://github.com/cdeust/zetetic-team-subagents) 生成；每个天才是具有标准步骤和一手来源引用的推理模式（而非角色扮演）。
## 状态
有意设为私有仓库。在完成全面的加固过程之前，尚不准备公开发布 — 安全审计修复已完成，正确性修复已完成，规模修复已完成，阶段 4/6/8/9 已上线，但上文标记为“上线”的每一项功能仅在本机上进行了端到端验证，尚未在实际的生产环境中验证。
**今天可用的功能**：端到端索引 Rust / Python / TypeScript 代码库，解析跨文件关系，聚类成各个社区，从入口点追踪流程，混合搜索，PRD 输入准备，PRD 声明验证，安全门检查，前后回归检测。
**暂缓的功能**：
- 跨文件索引器批处理，以充分发挥 38 倍 UNWIND 的优势（目前总体为 1.17 倍；每边速率已达到 0.143 ms）
- Rust 解析器中的 `is_unsafe` 提取（阶段 8 S2 在此之前以 `info`-skip 模式运行）
- 基于推断类型进行基于 LSP 的深度方法解析
- 多仓库 / 工作组操作 (GitNexus `group_*`)
- 重命名 / 重构工具（我们在设计上是只读的）
## 许可证
MIT — 查看 [LICENSE](LICENSE)。
由 cdeust 构建。每个阶段均由天才 agent 设计。每个常量均有出处。