user-hash/Lifeblood

# Lifeblood 编译器即服务（Compiler-as-a-service），专为 AI 代理设计。 Lifeblood 让 AI 代理直接访问编译器所掌握的知识：类型解析、调用图、诊断、引用查找、代码执行。通过标准 MCP 连接完成，无需 IDE。加载项目，询问编译器，获取经过验证的答案。 编译器已经了解你的代码全部细节，只需将这些真实信息通过管道传递给 AI 代理，而不是让它们去 grep 和猜测。 ``` Roslyn (C#) ──┐ ┌── Execute code against project types TypeScript ──┤ ┌────────────────────────┐ ├── Diagnose / compile-check JSON graph ──┼→ │ Semantic Graph │ →┤── Find references / rename / format ──┤ │ (symbols / edges / │ ├── Blast radius / file impact community ──┘ │ evidence / trust) │ └── Context packs / architecture rules adapters └────────────────────────┘ ``` 源自将一个 [40 万行代码的 Unity 项目](https://github.com/user-hash/LivingDocFramework/blob/main/docs/CASE_STUDY.md) 在 AI 辅助下交付，并意识到 AI 可以写代码，但无法验证它所写的内容。 ## 快速开始 ### 安装（30 秒） ``` dotnet tool install --global Lifeblood dotnet tool install --global Lifeblood.Server.Mcp ``` 需要 [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0)。 ### 连接到 Claude Code、Cursor 或任意 MCP 客户端 将以下内容添加到项目的 `.mcp.json`： ``` { "mcpServers": { "lifeblood": { "command": "lifeblood-mcp", "args": [] } } } ``` 请参阅 [MCP 设置指南](docs/MCP_SETUP.md) 获取 Claude Desktop、VS Code、Cursor 和原始 stdio 的配置说明。 ### 使用 ``` lifeblood_analyze projectPath="/path/to/your/project" → load semantic graph lifeblood_blast_radius symbolId="type:MyApp.AuthService" → what breaks if I change this? lifeblood_file_impact filePath="src/AuthService.cs" → what files are affected? lifeblood_find_references symbolId="type:MyApp.IRepo" → every caller, every consumer lifeblood_search query="quantize timing to grid" → ranked keyword + xmldoc search lifeblood_invariant_check id="INV-CANONICAL-001" → query architectural invariants from CLAUDE.md lifeblood_compile_check code="var x = 1 + 1;" → snippet compiles, auto-wraps for library modules lifeblood_execute code="typeof(MyApp.Foo).GetMethods()" → run C# against your types ``` 首次分析后，使用 `incremental: true` 进行快速重分析（秒级而非分钟级）。 ### CLI（用于 CI 和脚本） ``` lifeblood analyze --project /path/to/your/project lifeblood analyze --project /path/to/your/project --rules hexagonal lifeblood context --project /path/to/your/project lifeblood export --project /path/to/your/project > graph.json ``` ### 从源码构建 ``` git clone https://github.com/user-hash/Lifeblood.git cd Lifeblood dotnet build dotnet test ``` ## 22 种工具 连接一个 MCP 代理。加载一个项目。AI 代理将获得 **22 种工具**：12 种只读，10 种写入。 | | 工具 | |---|---| | **只读** | 分析、上下文、查找、依赖关系、被依赖项、爆炸半径、文件影响、解析简称、搜索、死代码¹、局部视图、不变性检查 | | **写入** | 执行、诊断、编译检查、查找引用、查找定义、查找实现、符号定位、文档、重命名、格式化 | ¹ `lifeblood_dead_code` 在 v0.6.3 以实验性方式发布。v0.6.4 修复了五个误判类以及根本性的编译缺口（缺失的隐式全局 using），将自分析发现从 150 个减少到 10 个（93% 准确率）。在真实 75 模块的 Unity 工作区上验证，准确率达 96%（25/26 验证通过）。剩余的误判为结构性问题：Unity 反射分发、运行时入口点、静态字段初始化器方法组。详见 [CLAUDE.md](CLAUDE.md) 中的 `INV-DEADCODE-001`。 每一个接受 `symbolId` 的只读工具都通过一个解析器路由。精确的规范 ID、截断的方法形式、裸简称以及 **命名空间错误但简称正确**（v0.6.3 的 `INV-RESOLVER-005`）都能解析为相同答案。 **v0.6.3 新特性：** - `lifeblood_invariant_check`：查询 `CLAUDE.md` 的架构不变性并以结构化数据返回。按 ID 查找、列出全部、审计重复项。适用于任何包含 `INV-*` 标记的项目。 - `lifeblood_compile_check` 现在自动包裹裸语句片段（如 `var x = 1 + 1;`），使其无需手动类包装即可在库模块中编译。 - `lifeblood_search` 对多词查询进行分词并执行加权 OR 评分（此前长度大于 1 的查询会返回零结果）。 - 当输入带有类型前缀但命名空间错误而简称唯一时，解析器回退到提取的简称查找。 [完整工具参考](docs/TOOLS.md) ## 架构 六边形架构（Hexagonal）。无依赖的核心领域，左侧为语言适配器，右侧为 AI 连接器。 ``` LEFT SIDE CORE RIGHT SIDE (Language Adapters) (The Pipe) (AI Connectors) Roslyn (C#) ──┐ ┌── MCP Server (22 tools) TypeScript ──┼→ Domain → Application →┤── Context Pack Generator JSON graph ──┘ ↑ ├── Instruction File Generator Analysis (optional) └── CLI / CI ``` 22 个端口接口，全部连接（左侧适配器 + 右侧连接器 + `ISymbolResolver` 用于标识符解析 + `IInvariantProvider` 用于 CLAUDE.md 不变性内省）。边界通过 [架构不变性测试](tests/Lifeblood.Tests/ArchitectureInvariantTests.cs) 强制执行，[CLAUDE.md](CLAUDE.md) 中包含 63 个类型化不变性（可通过 `lifeblood_invariant_check` 查询），以及 [11 份冻结的 ADR](docs/ARCHITECTURE_DECISIONS.md)。  [完整架构](docs/ARCHITECTURE.md) | [交互式图表](docs/architecture.html) ## 三种语言，一个图谱 | 适配器 | 工作原理 | 置信度 | |--------|----------|--------| | **C# / Roslyn** | 编译器级别的语义分析，跨模块解析。双向：分析与代码执行。 | 已验证 | | **TypeScript** | 独立的 Node.js 环境。使用 `ts.createProgram` + `TypeChecker`。 | 高 | | **Python** | 独立的 `ast` 模块。零依赖。 | 结构级 | | **任意语言** | 输出符合 `schemas/graph.schema.json` 的 JSON。[适配器指南](docs/ADAPTERS.md)。 | 各有不同 | ## Unity 集成 Lifeblood 与 [Unity MCP](https://github.com/CoplayDev/MCPForUnity) 并行运行作为侧车（sidecar）。所有 22 种工具在 Unity 编辑器中均可通过 `[McpForUnityTool]` 发现。以独立进程运行，因此不会产生程序集冲突或域重载干扰。 [Unity 设置指南](docs/UNITY.md) ## 自我验证（Dogfooding） 自我分析（MCP，v0.6.4 之后）：1,887 个符号，8,223 条边，11 个模块，238 种类型，0 违规。v0.6.4 修复了五个死代码误判类以及隐式全局 using 编译缺口；后续提取器阶段增加了构造器 `Calls` 边、字段/属性初始化器到构造器的映射，以及属性访问器上下文路由（又关闭了三个误判类）。调用图完整性在 v0.6.4 中提升了 42%，并通过构造器边再次提升。Lifeblood 通过 `lifeblood_invariant_check` 针对 [CLAUDE.md](CLAUDE.md) 审计自身的架构不变性：25 个类别共 63 个不变性，零重复 ID，零解析警告。 在 75 模块、40 万行代码的 Unity 工作区上经过生产验证。同一工作区，两种不同路径、两种不同内存配置。两者均正确，且均为预期设计，均来源于每个 `lifeblood_analyze` 响应中的原生 `usage` 字段，因此可确定性引用。 | 路径 | 耗时 | CPU 总计 | 单核 CPU 占比 | 峰值内存占用 | 适用场景 | |------|------|----------|--------------|--------------|----------| | **CLI**（流式输出，编译结果已释放） | ~14 秒 | ~23 秒 | ~150% | ~570 MB | 一次性分析、规则检查、图导出 | | **MCP**（保留编译结果） | ~32 秒 | ~58 秒 | ~180% | ~2,800 MB | 交互式会话，使用写入类工具（`execute`、`find_references`、`rename` 等） | MCP 保留配置的内存占用约为 CLI 流式输出的 4 倍，因为写入类工具需要将工作区完整加载到内存以响应后续查询。将 `readOnly: true` 传递给 `lifeblood_analyze` 可切换回 CLI 流式输出，代价是无法使用写入类工具。两项均在 AMD Ryzen 9 5950X（16 核 / 32 线程）上测量。实际数值在每个 `lifeblood_analyze` 响应的 `usage` 字段中实时暴露，因此可确定性引用。 七次以上自我验证会话发现了 [50 多个真实缺陷](docs/DOGFOOD_FINDINGS.md)，这些缺陷在单元测试中不可见，包括 v0.6.3 的解析器命名空间错误回退（`INV-RESOLVER-005`）、compile_check 的库模块自动包裹，以及 `lifeblood_dead_code` 跟踪的误判类（`INV-DEADCODE-001`）。 ## 路线图 - **社区适配器**：为 [Go](adapters/go/) 和 [Rust](adapters/rust/) 提供贡献指南。合约和清单已就绪实现代码。 - **REST / LSP 桥接**：将图谱暴露给 IDE 扩展和 Web 服务。 ## 文档 | 页面 | 描述 | |------|------| | [工具](docs/TOOLS.md) | 所有 22 种工具的描述、符号 ID 格式、增量使用说明、死代码注意事项 | | [MCP 设置](docs/MCP_SETUP.md) | Claude Code、Cursor、VS Code、Claude Desktop、Unity 的复制粘贴配置 | | [Unity 集成](docs/UNITY.md) | 侧车架构、设置指南、增量、内存管理 | | [架构](docs/ARCHITECTURE.md) | 六边形结构、依赖流向、22 个端口接口、架构不变性 | | [架构决策](docs/ARCHITECTURE_DECISIONS.md) | 11 份冻结的 ADR | | [不变性](CLAUDE.md) | 63 个类型化架构不变性，可通过 `lifeblood_invariant_check` 查询 | | [第 8 阶段尖峰](docs/plans/invariant-check-spike.md) | `lifeblood_invariant_check` 的设计记录及 rollout 阶段 8A-8E | | [状态](docs/STATUS.md) | 组件表、测试数量、自我验证、生产统计 | | [适配器](docs/ADAPTERS.md) | 如何构建语言适配器（13 项检查清单） | | [Dogfood 发现](docs/DOGFOOD_FINDINGS.md) | 由自我验证和评审会话发现的 50+ 个缺陷 | | [变更日志](CHANGELOG.md) | 每次发布：新增、修复、已知限制 | ## 相关项目 - [LivingDocFramework](https://github.com/user-hash/LivingDocFramework)：塑造架构的方法论 - [Roslyn](https://github.com/dotnet/roslyn)：C# 编译器平台 - [案例研究](https://github.com/user-hash/LivingDocFramework/blob/main/docs/CASE_STUDY.md)：我们验证这些理念的 40 万行代码 Unity 项目 ## 许可证 AGPL v3

标签：AI工程化, MCP, Roslyn, SEO: AI代码分析, SEO: MCP工具, SEO: 编译器即服务, SEO: 语义图, TypeScript, 上下文编排, 代码可信验证, 代码执行, 代码智能分析, 代码诊断, 多人体追踪, 大模型工具, 安全插件, 开发效率, 引用查找, 插件架构, 文档结构分析, 社区适配器, 符号解析, 编译器即服务, 网络可观测性, 语义图, 调用图, 逆向工具