1. 项目概述当你的代码库需要一个“活字典”如果你曾经面对一个拥有数千次提交、数万行代码的庞大项目试图理解“为什么这段代码要这么写”或者“这个功能的历史变更是什么”你大概能体会那种在代码海洋里捞针的无力感。传统的代码搜索工具如grep只能帮你找到字符串却无法理解上下文而直接向通用大模型提问它要么对项目一无所知要么需要你手动粘贴大量代码片段既低效又昂贵。Machtiani (mct)就是为了解决这个痛点而生的。它不是一个简单的代码补全工具而是一个基于终端、本地运行的代码对话服务。你可以把它想象成为你整个代码库配备了一个“活字典”或“资深架构师”。这个“架构师”不仅读过你项目的每一行代码、每一个提交记录还能基于这些精确的上下文用最少的成本token给你最高质量的答案。它的核心价值在于将你的整个 Git 历史与大型语言模型LLM的智能理解能力深度结合让你能像与同事讨论一样与你的代码库进行自然语言对话。1.1 核心需求解析为什么我们需要“代码对话”在软件开发中尤其是维护和迭代阶段我们常常面临几类典型问题理解遗留代码新加入一个项目如何快速理解某个复杂模块的设计意图和历史变迁精准定位问题遇到一个 Bug如何快速找到所有相关的代码文件和可能的影响范围安全地进行重构想修改一个函数如何确保不会破坏其他依赖它的模块高效获取上下文在编写新功能或修复 Bug 时如何快速获得所有必要的背景信息而不是在 IDE 和浏览器标签页之间来回切换传统的解决方案要么是碎片化的如代码注释、文档要么是机械化的如全文搜索要么成本高昂如向云端 LLM 发送大量代码。Machtiani 的解决方案是预先对项目的 Git 历史进行智能分析和向量化存储Embedding。当你提问时它能从海量提交记录中精准检索出与问题最相关的代码片段和变更上下文然后将这些“精华”连同你的问题一起发送给 LLM。这样LLM 就能在极小的上下文窗口内给出高度相关且准确的回答。注意Machtiani 本身不运行 LLM 模型它是一个“智能检索与编排层”。它负责理解你的项目、找到关键上下文然后调用你配置的 LLM API如 OpenAI, Anthropic, 本地运行的 Ollama 等来生成答案。这种设计使其极其灵活且成本可控。1.2 核心优势效率与成本的平衡艺术与直接使用 ChatGPT 或 Claude 网页版相比Machtiani 在大型项目上的优势是压倒性的极致的上下文效率它不会把整个代码文件扔给 LLM。而是通过分析 Git 提交提取出真正有信息量的代码变更片段diffs和提交信息将其转换为向量。你的问题也会被向量化系统通过相似度匹配只召回最相关的几个片段。这通常能将需要发送的上下文从数万 token 压缩到几百或几千 token。显著的成本降低更少的上下文意味着更低的 API 调用成本。对于拥有大量历史的项目一次深入的问答Machtiani 的成本可能只有直接使用 GPT-4 的十分之一甚至百分之一。答案质量更高由于上下文高度相关且精准LLM 更容易给出符合项目实际架构和编码规范的答案减少了“胡言乱语”或脱离项目实际的情况。完全的本地控制与隐私项目的向量化数据Embeddings和聊天记录默认存储在本地。只有当你提问时经过筛选的少量上下文和问题才会被发送到你指定的 API。如果你使用本地模型如通过 Ollama整个过程可以完全在离线环境下进行。与现有工作流无缝集成作为命令行工具它可以轻松嵌入到你的 Shell、编辑器如 Vim/Emacs 的插件或自动化脚本中与git,make等工具协同工作。2. 核心架构与工作原理拆解要真正用好 Machtiani理解其内部工作机制至关重要。这能帮助你在遇到问题时进行排查也能让你更明智地配置和使用它。2.1 工作流程从代码库到智能答案Machtiani 的工作可以分为两个主要阶段同步Sync和对话Chat。第一阶段同步mct sync这是为你的代码库建立“知识图谱”的过程。当你第一次在项目目录下运行mct sync时它会执行以下操作遍历 Git 历史读取指定深度内的所有提交commit。提取与解析对每个提交提取其提交信息commit message和代码变更diff。提交信息通常包含了“为什么Why”要这么改而代码变更则包含了“改了什么What”。分块与向量化将提取出的文本提交信息变更代码切割成适当大小的文本块chunks。然后使用一个嵌入模型Embedding Model将这些文本块转换为高维向量vectors并存储在本地的向量数据库中。建立索引为这些向量建立高效的索引例如使用 HNSW 算法以便在后续对话中进行快速的相似度搜索。这个过程是一次性的后续只需对新的提交进行增量同步即可速度很快。实操心得同步阶段的选择直接影响后续对话的质量和成本。--model参数在这里指定的是用于生成文本摘要或理解的 LLM默认是gpt-4o-mini而向量化使用的是专门的嵌入模型如all-MiniLM-L6-v2。对于同步强烈建议使用低成本、高速度的模型如gpt-4o-mini或claude-3-haiku因为它的目的是处理大量文本对推理深度要求不高。第二阶段对话mct [prompt]当你就项目提问时Machtiani 会问题向量化将你的自然语言问题同样转换为向量。语义检索在本地向量数据库中快速查找与问题向量最相似的几个代码/提交文本块。这就是检索增强生成RAG的核心。构造提示词Prompt将检索到的相关上下文代码片段、提交原因与你的原始问题按照预设的模板组合成一个完整的提示词。调用 LLM将这个精心构造的提示词发送给你指定的 LLM API如gpt-4o。返回与执行接收 LLM 的回复。根据运行模式--mode它可能只是返回文本答案chat模式也可能尝试生成 Git 补丁并应用到代码中commit模式。2.2 关键组件解析向量数据库Machtiani 使用本地文件如 SQLite 向量扩展来存储和检索向量无需部署独立的向量数据库服务降低了复杂度。嵌入模型Embedding Model负责将文本转换为向量。项目内置或允许配置轻量级、高效的句子转换模型。好的嵌入模型能确保语义相似的代码片段在向量空间中也彼此接近。检索策略--match-strength参数控制检索的严格程度。high会返回最相关但可能数量较少的片段适合精确问答low会返回更多相关性稍弱的片段适合探索性、需要更多背景的问题。LLM 网关Machtiani 通过标准化的 OpenAI API 格式与各种模型服务商通信。这意味着它支持 OpenAI、Anthropic、Google Gemini通过兼容服务、OpenRouter 以及任何本地部署的兼容服务如 Ollama、LM Studio。3. 从零开始完整安装与配置指南让我们一步步搭建起你的个人代码助手。整个过程大约需要 10-15 分钟。3.1 环境准备与依赖安装Machtiani 的核心服务端由 Go 语言编写并通过 Docker Compose 运行。因此你需要确保系统中已安装以下基础软件Git用于克隆项目和后续的代码库同步。几乎所有系统都已预装。Go 语言 (1.21)用于编译mct命令行客户端。macOS:brew install goLinux (Ubuntu/Debian):sudo apt update sudo apt install golang-go安装后请将$(go env GOPATH)/bin添加到你的PATH环境变量中通常需要添加到~/.zshrc或~/.bashrc。Docker 与 Docker Compose用于一键启动包含向量数据库等后端服务的完整环境。访问 Docker 官网 下载并安装 Docker Desktop已包含 Compose。安装后在终端运行docker --version和docker compose version确认安装成功。3.2 获取与安装 Machtiani克隆项目使用--recurse-submodules参数确保克隆所有必要的子模块。git clone --recurse-submodules https://github.com/tursomari/machtiani cd machtiani编译并安装mct命令行工具cd mct go install -ldflags$(go run ./generate_ldflags) ./cmd/mct cd -go install会将编译好的mct二进制文件安装到$GOPATH/bin目录下。-ldflags参数用于在编译时注入版本信息如 Git 提交哈希方便后续问题排查。验证安装运行mct --help如果看到帮助信息说明客户端安装成功。如果提示“命令未找到”请确认已正确将$GOPATH/bin加入PATH并重新加载 Shell 配置source ~/.zshrc。3.3 启动本地服务与配置 API 密钥Machtiani 的后端服务包括向量数据库、API 服务器等通过 Docker Compose 管理。启动服务在machtiani项目根目录即有docker-compose.yml文件的目录下运行docker-compose up --build --remove-orphans首次运行会下载并构建多个 Docker 镜像需要一些时间。看到所有服务都显示“ready”或类似状态后服务就启动成功了。通常你会看到一个运行在http://localhost:8080的 API 服务。配置 LLM 访问Machtiani 需要知道如何访问你的 LLM。支持通过环境变量或配置文件设置。这里以环境变量为例更灵活使用 OpenAI:export MCT_MODEL_BASE_URLhttps://api.openai.com/v1 export MCT_MODEL_API_KEYsk-your-openai-api-key-here使用 OpenRouter可访问多种模型:export MCT_MODEL_BASE_URLhttps://openrouter.ai/api/v1 export MCT_MODEL_API_KEYsk-your-openrouter-api-key-here使用本地 Ollama:export MCT_MODEL_BASE_URLhttp://localhost:11434/v1 # Ollama 默认地址 export MCT_MODEL_API_KEYollama # Ollama 通常不需要真密钥但字段需存在可选配置代码仓库访问密钥如果你的项目 Git 远程地址是私有的如私有 GitHub 仓库需要提供访问令牌。export CODE_HOST_API_KEYghp-your-github-personal-access-token-here这个配置是通用的适用于 GitHub、GitLab、Bitbucket 等。注意事项将这些export命令添加到你的 Shell 配置文件如~/.zshrc中可以避免每次打开终端都需要重新设置。你也可以使用项目根目录或家目录下的.machtiani-config.yml文件来配置格式为 YAML。环境变量的优先级高于配置文件。4. 实战演练与你的第一个项目对话假设我们有一个名为my-awesome-project的私有 GitHub 项目现在想让它成为 Machtiani 的“知识库”。4.1 初始同步为项目建立索引进入项目目录cd /path/to/my-awesome-project执行初始同步这是最耗时的一步取决于项目提交历史的大小。mct sync --model gpt-4o-mini --model-threads 10--model gpt-4o-mini指定用于分析提交的 LLM。选择低成本模型以节省费用。--model-threads 10并发请求数。提高此值可以显著加快同步速度但受限于你的 API 提供商的速率限制和本地网络。对于 OpenRouter 等允许高并发的服务可以设置为 50 甚至 100。同步过程会显示进度、预估成本和已处理的提交数。对于一个有几千次提交的中型项目使用gpt-4o-mini和足够的并发成本可能只需几美分时间在几分钟到十几分钟。检查同步状态同步过程中或完成后可以随时运行mct status查看当前项目的同步状态和基本信息。避坑技巧首次同步前可以先使用--cost-only标志进行成本预估避免意外产生高额账单。mct sync --cost-only --model gpt-4o-mini这会分析你的 Git 历史估算出需要处理的 token 数量和大致费用而不会真正调用 API。4.2 开始对话提出你的第一个问题同步完成后你就可以像询问一位熟悉项目的专家一样提问了。基础问答mct 我们项目的用户登录模块历史上做过哪些主要的安全加固 --model gpt-4oMachtiani 会检索与“用户登录”、“安全”相关的提交记录让gpt-4o基于这些上下文生成一个总结性的回答。代码理解与解释mct 解释一下 src/utils/encryption.js 文件中 secureHash 函数的设计思路以及它经历过哪些重要改动。 --model claude-3-5-sonnet获取修改建议只聊不执行mct 我想在 UserService 类中添加一个根据邮箱前缀模糊查找用户的方法应该怎么做请给出具体的代码修改建议。 --mode chat --model gpt-4o使用--mode chat模式Machtiani 只会返回文本建议不会实际修改代码文件。让 AI 直接修改代码高风险需谨慎mct 修复 api/auth/login.py 第 45 行可能存在的 SQL 注入漏洞。 --model gpt-4o在默认的commit模式下如果 Machtiani 认为找到了解决方案并可以生成有效的 Git 补丁patch它会询问你是否要应用这个补丁。务必在应用前仔细审查 AI 生成的变更建议先在单独的分支上测试。4.3 高级用法与执行器如 Codex组合使用Machtiani 的强项在于理解和检索而像codex一个假设的 CLI 代码执行器这样的工具擅长执行和验证。将它们组合起来可以构建一个强大的自动化工作流。核心理念让mct做“大脑”负责分析问题、制定精确的修改计划让codex做“双手”负责执行这个计划如运行测试、应用重构。# 步骤1用 mct 分析问题并生成一个极简、精确的行动计划 PLAN$(mct 为 /api/users 端点添加请求速率限制 --mode answer-only --model Qwen2.5-Coder-7B-Instruct-Q6) # 步骤2将这份精确的计划交给 codex 去执行 codex $PLAN--mode answer-only让mct输出一个高度浓缩、只包含必要修改指令和文件路径的“答案”不包含任何多余的对话或解释。这样codex收到的指令非常清晰没有歧义可以更高效、更准确地执行避免了 LLM 在复杂任务中常见的“思维循环”和 token 浪费。模型混搭策略你可以用一个小而快的本地模型如Qwen2.5-Coder-7B运行mct来做检索和规划然后用一个强大但昂贵的云端模型如o1-preview运行codex来执行复杂的代码生成和测试。这样在保证质量的同时最大化成本效益。5. 配置详解与性能调优要让 Machtiani 在你的工作环境中发挥最大效能合理的配置是关键。5.1 配置文件与环境变量如前所述配置有两种方式环境变量和 YAML 文件。以下是所有关键配置项的说明环境变量YAML 键说明示例值MCT_MODEL_BASE_URLenvironment.MCT_MODEL_BASE_URLLLM API 的基础 URL。https://api.openai.com/v1MCT_MODEL_API_KEYenvironment.MCT_MODEL_API_KEYLLM API 的密钥。sk-...CODE_HOST_API_KEYenvironment.CODE_HOST_API_KEY访问私有 Git 仓库的令牌。ghp_...或glpat-...MCT_LOCAL_EMBEDDING_MODELenvironment.MCT_LOCAL_EMBEDDING_MODEL高级本地嵌入模型路径。/path/to/all-MiniLM-L6-v2配置文件示例 (~/.machtiani-config.yml)environment: MCT_MODEL_BASE_URL: https://openrouter.ai/api/v1 MCT_MODEL_API_KEY: sk-or-... # CODE_HOST_API_KEY 可以不配置在使用时通过环境变量临时设置5.2 同步策略与性能调优mct sync命令有多个参数深刻影响同步的效率和最终检索质量。--amplify(低/中/高)这个参数控制同步时对提交信息的“增强”程度。默认是off。low对提交信息进行轻度总结和扩展成本约增加 2 倍能提升后续问答的准确性尤其是当提交信息写得比较简略时。high进行深度分析和重构成本可能增加 20 倍速度慢 5 倍。仅推荐用于那些提交历史非常混乱、提交信息毫无价值的关键项目或者你对成本不敏感且追求极致精度。建议对于大多数情况首次同步使用--amplify low是性价比最高的选择。后续的增量同步可以不用此参数。--depth限制同步的提交数量从最新提交开始计算。例如--depth 1000只同步最近的 1000 次提交。对于历史极其悠久但近期活跃的项目可以用此参数聚焦于最新、最相关的代码。--model-threads这是影响同步速度的最关键参数。它决定了向 LLM API 发送并发请求的数量。如果你的 API 提供商允许高并发如 OpenRouter 的付费计划将其设置为 50-100 可以将同步时间从小时级缩短到分钟级。请根据你的 API 速率限制和机器性能调整。一个优化的同步策略示例# 首次同步使用低成本模型低度增强高并发只同步最近2000次提交 mct sync --model gpt-4o-mini --amplify low --depth 2000 --model-threads 50 --force # 后续增量同步在推送新提交后运行无需增强快速同步 mct sync --model gpt-4o-mini --model-threads 205.3 对话模式与匹配强度--modecommit(默认)尝试理解你的意图并可能生成并应用 Git 补丁来修改代码。使用时务必在干净的工作区或特性分支上并仔细审查变更。chat仅进行对话返回文本答案即使答案包含代码建议也不会执行。pure-chat不进行任何代码检索直接将你的问题发送给 LLM。相当于一个简单的 CLI 聊天接口用于快速测试模型或问一些通用问题。answer-only输出一个极度精简、面向行动的答案适合作为其他自动化工具如codex的输入。--match-strengthhigh严格匹配返回最相关但数量最少的上下文片段。适合非常具体、指向明确的问题例如“foo.go第 23 行的函数是做什么的”。mid(默认)平衡模式在相关性和上下文广度间取得平衡。适用于大多数问题。low宽松匹配返回更多相关性稍弱的片段。适合探索性、宽泛的问题例如“我们这个项目里有哪些地方用到了 Redis 缓存”以获取更全面的背景。6. 常见问题与故障排查实录在实际使用中你可能会遇到一些问题。以下是我在长期使用中积累的排查经验和解决方案。6.1 同步阶段问题问题mct sync速度非常慢甚至卡住。排查首先检查--model-threads设置是否过低默认可能为 1。其次确认你的网络连接和 API 服务商如 OpenRouter的当前状态。最后运行mct status查看同步进度。解决适当提高--model-threads如设置为 20。如果使用本地模型Ollama检查模型是否已正确加载且没有其他进程占用大量资源。问题同步成本远超预估。排查是否错误地使用了--amplify high或者--depth参数设置得非常大同步了整个历史解决始终先用--cost-only标志进行预估。对于大型历史项目考虑使用--depth限制范围或分批次同步如先同步最近一年的提交。问题同步失败提示“无法访问 Git 远程仓库”。排查你的项目是否设置了 Git 远程地址git remote -v如果是私有仓库是否已正确设置CODE_HOST_API_KEY环境变量解决确保远程地址是 HTTPS 格式SSH 格式目前可能不支持。对于私有仓库生成并配置具有仓库读取权限的 Personal Access Token。6.2 对话阶段问题问题mct的回答似乎没有基于我的项目代码像是在胡编乱造。排查首先确认同步是否成功完成mct status。其次检查你提问时是否在正确的项目目录下。最后尝试一个非常具体、指向明确文件的问题如“src/main.go里的StartServer函数接受哪些参数”。解决如果同步没问题尝试提高--match-strength到high。如果问题依然存在可能是检索到的上下文仍然不相关可以考虑在初始同步时使用--amplify low来增强提交信息提升检索质量。问题AI 生成的代码补丁patch看起来有问题不敢应用。解决这是预期行为也是安全边界。永远不要盲目信任 AI 生成的代码。正确的做法是在运行mct前确保你的工作区是干净的git status显示没有未提交的修改。创建一个新的特性分支git checkout -b mct-feature-fix。运行mct命令。当它询问是否应用补丁时选择n否。补丁文件会保存在.machtiani/chat/目录下。用git apply --check patch-file检查补丁是否能干净地应用。仔细阅读补丁内容理解每一处修改。可以手动应用git apply patch-file或选择性地合并。运行项目的测试套件确保修改没有引入回归。确认无误后再提交。问题我想排除一些文件如node_modules,.env不被同步和检索。解决在项目根目录创建.machtiani.ignore文件语法类似于.gitignore每行一个模式。node_modules/ *.log .env dist/ *.pyc这样这些文件就不会被分析、向量化也不会出现在检索结果中能提升同步速度和检索精度。6.3 性能与资源问题问题本地向量数据库占用磁盘空间过大。排查向量数据库通常存储在~/.machtiani或项目下的.machtiani目录中。大型项目数万次提交的嵌入向量可能占用几个 GB 空间。解决这是存储知识必须付出的代价。可以考虑定期清理不再需要的旧项目索引使用mct remove。也可以检查是否同步了不必要的分支或历史深度过深。问题运行mct聊天时CPU/内存占用突然飙升。排查这通常发生在使用本地嵌入模型进行实时检索时。检索过程涉及向量计算对 CPU 有一定要求。解决确保你的本地嵌入模型是轻量级的如all-MiniLM-L6-v2。如果问题持续可以考虑将 Machtiani 服务部署在性能更强的机器上或者使用云端的嵌入模型服务如果 Machtiani 支持配置。7. 进阶技巧与生态集成当你熟悉基础操作后这些技巧能让你如虎添翼。7.1 打造个性化工作流脚本将mct嵌入你的日常开发脚本。例如创建一个code_review_helper.sh脚本#!/bin/bash # 用法./code_review_helper.sh 本次提交的哈希 COMMIT_HASH$1 # 获取本次提交的变更摘要 CHANGE_SUMMARY$(git show --stat $COMMIT_HASH | head -20) # 询问 mct 这些变更可能影响哪些现有功能 echo 分析提交 $COMMIT_HASH 的潜在影响... mct 以下是最近一次提交的变更摘要\n$CHANGE_SUMMARY\n\n请分析这些代码修改可能会对项目中哪些已有的功能模块造成影响或需要额外关注列出可能的风险点。 --mode chat --model claude-3-5-sonnet review_notes.md echo 分析完成结果已保存到 review_notes.md7.2 与编辑器集成虽然 Machtiani 是 CLI 工具但你可以通过 Shell 集成将其接入你的编辑器如 VS Code, Vim, Emacs。VS Code可以创建一个任务Task或使用终端插件绑定快捷键来运行mct命令并将选中的代码或当前文件路径作为问题的一部分发送。Vim/Neovim写一个简单的 Vim 函数调用:!mct并将当前缓冲区的内容或视觉选择区域作为输入。7.3 管理多个项目Machtiani 可以同时为多个项目建立索引。只需在不同的项目目录下分别运行mct sync即可。所有的索引数据是隔离的。当你在一个项目目录下提问时Machtiani 会自动使用该项目的索引。要查看所有已同步的项目可以检查~/.machtiani/projects/目录具体路径可能因配置而异。要删除某个项目的索引进入该项目目录运行mct remove。7.4 本地模型部署指南对于完全离线的场景或极致隐私需求使用本地 LLM 是绝佳选择。部署 Ollama这是最简单的方式。安装 Ollama 后拉取一个适合编程的模型如codellama:7b或qwen2.5-coder:7b。ollama pull qwen2.5-coder:7b配置 Machtiani将 API 指向本地 Ollama。export MCT_MODEL_BASE_URLhttp://localhost:11434/v1 export MCT_MODEL_API_KEYollama性能考量本地 7B 参数模型在代码理解上已经相当不错但响应速度取决于你的硬件尤其是 GPU。对于同步sync操作由于需要处理大量文本使用本地模型可能非常慢建议仍使用快速的云端小模型进行同步聊天时再用本地大模型。我个人在实际使用中发现Machtiani 最大的价值不在于替代你写代码而在于极大地压缩了“理解现有代码”所需的时间。它把从“面对陌生代码库的迷茫”到“清晰知道从哪里下手”的过程从几小时甚至几天缩短到几分钟。它更像是一个永不疲倦、记忆力超群的项目导航员让你能把宝贵的精力集中在真正的设计和创造上而不是迷失在寻找和阅读代码的丛林里。刚开始使用时建议从一些具体的、有明确答案的问题开始比如“这个函数的作用是什么”“这个 Bug 是哪次提交引入的”逐步建立对它的信任感和使用直觉。