Spirit

Spirit 是一套面向研发团队的 AI-first 工程工作流方案，用来把“发现问题”“分析问题”“修复代码”“提交 MR”和“验证质量”串成一个闭环。

它的核心目标不是给现有流程加一个聊天助手，而是把日志、代码、数据库、CI、Git 工作流统一到一个可被 AI 调用的执行平面里，让 AI 能在受控边界内完成分析和修复，开发者只需要做 review 和 merge。

Spirit 解决什么问题

传统流程里，错误日志、代码仓库、数据库、CI 和 MR 评论是分散的。定位问题通常要靠开发者手动切换多个系统，修复效率受上下文碎片化影响很大。

Spirit 试图解决的是两类高频场景：

1. 线上或测试环境出现错误日志后，系统自动分析根因，并在隔离 worktree 中生成修复分支和 GitLab MR。
2. 开发者在 GitLab Issue 中写需求后，系统自动创建独立开发环境，完成代码实现，并通过 Issue 评论持续迭代，最终提交 MR。

一句话理解 Spirit

Spirit = 观测 + 分析 + 修复 + 验证 + 提交流程的 AI 自动化编排层。

它的典型闭环是：

日志或 Issue -> Claude 分析 -> worktree 隔离修改 -> 本地验证 -> commit/push -> 创建 GitLab MR -> 开发者 review

两条核心工作流

1. 日志驱动自动修复

• 轮询 Elasticsearch 错误日志，同时监听本地日志文件变化。
• 对错误做指纹去重，并在必要时用 LLM 做语义去重，避免同一类问题被重复分析。
• 用 Claude 分析根因，输出风险等级、疑似文件和修复计划。
• 对 A/B 风险问题进入自动修复流程，在隔离 worktree 中改代码。
• 修复后先做本地构建或静态校验，通过后再推送分支并创建 GitLab MR。

2. Issue 驱动自动开发

• 定时拉取带有 ai-dev 标签的 GitLab Issue。
• 为每个 Issue 创建独立 worktree 和 feature 分支。
• 使用 Anthropic SDK 的 tool-use loop 执行开发任务，而不是依赖 CLI 会话。
• 持久化对话历史到 SQLite，支持跨进程恢复和多轮评论迭代。
• 自动提交代码、推送分支、创建 MR，并在 MR 合并后关闭 Issue。

架构概览

Spirit 由三层组成：

MCP Server

供 IDE 或 Agent 调用的工具层，统一暴露读、查、改、提交流程能力。工具大致分为五类：

• 读取面：搜索日志、查询数据库、读取文件、搜索代码、列目录
• Incident 面：列出、查看、确认、解决告警
• Git 执行面：建分支、管 worktree、写补丁、提交、推送、创建 MR、查询 MR 状态
• CI 面：触发流水线、查询流水线状态
• 通过 stdio 协议接入 .mcp.json

Log Watcher

长驻后台进程，负责日志轮询、错误去重、风险分级和自动修复触发。

Issue Watcher

负责识别带标签的 GitLab Issue，拉起独立开发任务，并通过评论轮询完成多轮协作。

Spirit 的关键设计

1. 先去重，再分析

同一 bug 可能在极短时间内产生大量重复日志。Spirit 先做字符串规范化和指纹计算，再用 LLM 兜底语义去重，避免把 token 和算力浪费在重复问题上。

2. 风险分级决定自动化边界

• A 级：低风险，可自动修复并自动提 MR
• B 级：中风险，可自动修复，但必须人工 review
• C 级：高风险，只分析和记录，不自动改代码

这让 AI 自动化保持在可控边界内，而不是不加区分地全自动执行。

3. Worktree 隔离保证并发安全

Spirit 不直接在主仓库工作，而是在 Git worktree 中执行修复和开发任务。

• 自动修复路径复用共享 worktree
• Issue 开发路径为每个 Issue 分配独立 worktree
• 所有写操作前都要做 assertWorktree() 校验，拒绝在主工作区直接 commit 或 push

4. 验证先于提交

Spirit 的原则不是“先生成代码，再交给 CI 兜底”，而是“先在本地验证，验证通过后再提交”。

典型验证包括：

• Go 项目：go vet ./...、go build ./...
• TypeScript 项目：tsc --noEmit、npm run build

如果验证失败，可以把报错重新反馈给模型继续修复，但重试次数需要受控。

5. 对话可恢复，而不是一次性脚本

Issue 驱动开发是一个持续过程，不是单次调用。Spirit 会把工具调用历史和模型消息持久化到数据库中，支持进程重启后恢复上下文，继续迭代。

数据与状态管理

Spirit 使用 SQLite 管理两类核心对象：

• incidents：记录从日志中发现的问题，包括指纹、环境、状态、风险等级、分析结果、分支和 MR 信息
• issue_tasks：记录从 GitLab Issue 派生出的开发任务，包括 worktree、分支、MR、历史消息、评论水位线和迭代次数

这两个表把“错误”与“执行过程”从非结构化文本提升为可跟踪、可恢复、可审计的状态机。

CI 为什么是 Spirit 的前提

Spirit 的自动修复能力依赖一个前提：项目必须先有稳定、可重复执行的验证基线。

如果连构建、静态检查、单测、健康检查都不稳定，那么 AI 自动修复只会制造更多不确定性。因此，Spirit 的工程方法是：

先统一验证命令，再接入 CI，最后才谈自动修复自治。

CI 落地思路

原则

• 先统一命令，再统一平台
• 先能跑，再跑全
• 先验证，后自治
• 优先复用项目已有构建工具，不额外造轮子

推荐分层

Spirit 对 CI 的建议不是一开始就上全套，而是分层建设：

1. L1 快速门禁：编译、lint、类型检查、可稳定执行的单测，要求每次 push 或 MR 自动运行，并阻塞合并。
2. L2 Smoke：启动最小依赖环境，验证健康检查、登录链路和核心只读接口，通常在 MR 上手动触发。
3. L3 E2E：覆盖核心用户路径，允许手动触发或定时运行。
4. L4 AI Review：对变更 diff 做模型审查，作为非阻塞补充。
5. L5 Nightly：执行更重、更慢、更依赖外部系统的全链路验证。

落地顺序

推荐按三个阶段推进：

1. 现状摸底：识别语言、构建工具、包管理器、CI 现状、验证能力和阻塞项。
2. 统一 CI 命令入口：把构建、检查、测试收敛成 make ci 或等效命令，保证本地与 CI 共用同一套入口。
3. 编排平台配置：再写 .gitlab-ci.yml 或 GitHub Actions，把快速门禁、smoke、E2E 和 AI review 逐步接进去。

CI 的工程重点

• 命令必须幂等、无副作用、可在本地和 CI 同时执行
• 缓存目录要显式隔离，避免污染开发环境
• 对不稳定模块要先排除，再逐步收敛问题范围
• Smoke 测试尽量使用 bash + curl，减少平台依赖
• docker compose 的 smoke 环境应最小化，只保留被测服务及必要中间件
• E2E 只保留关键路径，先建立基线，再逐步扩展覆盖率

Spirit 和传统 CI/CD 的区别

传统 CI/CD 主要在“代码已提交”之后运行；Spirit 想做的是把 AI 拉到提交之前，让它拥有足够的上下文来分析和修复问题。

简单来说：

• 传统 CI/CD：人改代码 -> CI 验证
• Spirit：日志或 Issue 触发 -> AI 分析和改代码 -> 本地验证 -> MR -> 人工 review

这意味着 Spirit 不是替代 CI，而是建立在 CI 基线之上的上层自动化系统。

适合什么团队

Spirit 适合以下场景：

• 已经有基本工程规范，但问题定位和修复流程仍然依赖大量人工切换上下文
• 使用 GitLab / GitHub 等代码托管平台，并接受通过 MR/PR 做最终审查
• 希望逐步引入 AI 自动化，而不是直接把高风险生产操作完全交给模型
• 有多服务、多环境、多代码根，需要统一观测、验证和提交流程

仓库里的两份文档分别是什么

• spirit-workflow-prompt.md：聚焦 Spirit 的整体架构、MCP 工具面、日志修复和 Issue 驱动开发工作流
• CI-practice-prompt.md：聚焦 CI 的工程化落地方法，包括命令统一、流水线分层、Smoke、E2E 和 AI Review

两者关系可以理解为：

• Spirit 文档回答“AI 自动修复系统应该怎么设计”
• CI 文档回答“要让这个系统真正可控，验证基线应该怎么建设”

最重要的结论

Spirit 的核心不是“让 AI 自动写代码”，而是把观测、执行、验证和治理组织成一个 AI 可操作、可回滚、可审计的工程系统。

而 CI 的核心不是“写一份流水线 YAML”，而是先把验证命令和验证分层做扎实。没有这个前提，就不会有稳定的自动修复闭环。