1. 项目概述dotbot为团队设计的结构化AI辅助开发平台如果你和我一样在团队里尝试过用AI来写代码大概率会遇到一个头疼的问题爽是爽了但后续的协作和追溯简直是一场灾难。你让AI生成了一个复杂的模块代码看起来不错但它是怎么想的为什么选这个方案而不是另一个中途有没有考虑过其他路径这些决策过程就像黑盒一样除了AI自己没人知道。更麻烦的是当你想让同事接着你的AI会话继续开发或者几天后自己回来想修改时发现上下文早就断了一切又得从头开始解释和摸索。这就是dotbot要解决的核心痛点。它不是一个简单的AI代码生成器而是一个为团队协作设计的、结构化、可审计的AI辅助开发工作流引擎。你可以把它理解为一个“AI开发的项目管理平台”。它把原本散乱、不可控的AI编码过程包装进一个定义清晰、每一步都被追踪、结果可复现的管道里。所有决策、会话、代码变更都被完整记录并纳入版本控制让AI辅助开发从个人玩具变成了团队可依赖的工程实践。简单来说dotbot 让你能用定义好的“工作流”来驱动AI开发。比如你可以定义一个“通过Jira创建新功能”的工作流AI会按照预设的步骤拉取Jira描述、分析需求、生成产品文档、拆解技术任务、然后逐个实现。整个过程在Web仪表盘上实时可见每个任务的状态、使用的AI模型、产生的代码变更和决策记录都一目了然。.bot/目录直接放在项目仓库里所有团队成员都能通过git看到完整的历史。2. 核心设计理念与架构拆解2.1 为什么是“工作流驱动”而不是“聊天驱动”市面上大多数AI编程工具如GitHub Copilot Chat、Cursor等本质上是增强版的聊天界面。你提问它回答然后你手动把代码整合进去。这种方式在探索性、一次性任务上很高效但在需要重复、可预测、多人协作的工程化场景中短板非常明显缺乏可重复性每次对话都是独立的即使问题相似AI也可能给出不同的实现导致项目风格和架构不一致。上下文脆弱长对话中AI可能会“忘记”之前的约定或决策需要人工不断提醒和纠正。审计追踪困难聊天记录虽然存在但很难与具体的代码变更、git commit直接关联回溯“为什么这么改”成本很高。难以集成到CI/CD聊天过程无法自动化无法作为构建流水线的一环。dotbot 的“工作流驱动”模型正是为了弥补这些短板。它将开发任务抽象为一个个类型化任务并组织成有依赖关系的管道。这类似于你在Jenkins、GitHub Actions中定义流水线只不过执行者从脚本变成了AI或脚本与AI的混合。一个典型的工作流workflow.yaml可能长这样name: feature-implementation description: 基于产品文档实现一个新功能模块 tasks: - id: analyze-requirements type: prompt prompt: 分析位于 docs/requirements.md 的需求文档并输出功能点列表和实体关系图。 model: claude-3-5-sonnet-20241022 # 为分析任务指定一个更便宜、更快的模型 outputs: - path: workspace/analysis/feature-breakdown.md - id: generate-entity-model type: prompt prompt: 基于上一步的分析结果设计数据库实体模型并生成SQL迁移脚本。 dependsOn: [analyze-requirements] model: claude-3-5-sonnet-20241022 - id: implement-core-logic type: prompt prompt: 根据实体模型在 src/domain/ 目录下实现核心领域逻辑和服务层代码。 dependsOn: [generate-entity-model] model: claude-3-opus-20240229 # 为核心逻辑实现指定一个更强大的模型 hooks: pre: ./scripts/run-tests.sh # 执行前先跑一遍现有测试确保不会破坏已有功能 post: ./scripts/lint-and-format.sh # 执行后自动进行代码检查和格式化 - id: run-unit-tests type: script script: ./scripts/run-all-unit-tests.ps1 dependsOn: [implement-core-logic] # script类型任务完全绕过AI直接执行PowerShell脚本用于确定性的验证步骤 - id: create-pull-request type: mcp tool: github_create_pr inputs: title: feat: 实现XXX功能 body: 基于需求文档 #123 实现。核心变更包括1. ... 2. ... dependsOn: [run-unit-tests]通过这样的定义一次功能开发就变成了一个可预测、可监控、可重复执行的自动化流程。新成员加入项目不需要理解复杂的上下文直接运行dotbot run feature-implementation就能得到一套符合团队规范、经过基础验证的代码。2.2 核心架构模块化与隔离性dotbot 的目录结构清晰地反映了其模块化设计思想。.bot/目录是它的“大脑”和“控制中心”。.bot/ ├── systems/ # 核心系统引擎运行时、UI、MCP服务 ├── workflows/ # 已安装的工作流定义每个都是独立的 ├── settings/ # 全局和提供商配置 ├── recipes/ # AI的“知识库”和“技能包”代理、提示词、技能 ├── workspace/ # 版本控制的运行时状态任务、会话、文档 └── hooks/ # 项目特定的钩子脚本几个关键的设计亮点双阶段执行引擎每个任务都经历分析和实现两个阶段。分析阶段由AI负责理解任务、识别相关文件、构建上下文包实现阶段则消费这个上下文包来生成或修改代码。这强制了AI进行“思考再行动”减少了盲目修改也生成了可供审计的中间产物。基于Git工作树的隔离这是保证代码安全性和可追溯性的基石。每个任务都在一个独立的Git工作树一个临时分支中执行。AI只能看到和修改这个工作树里的文件。任务完成后工作树的内容被“压缩合并”回主分支。这意味着原子性一个任务要么完全成功并合并要么完全失败工作树被丢弃不会留下半成品。无冲突不同任务并行执行时操作的是各自独立的工作树从根源上避免了代码冲突。完整历史每一次AI的代码变更都会生成一个清晰的Git提交附带上完整的任务上下文和决策记录。多模型与多提供商支持不是所有任务都需要最强大、最贵的模型。dotbot允许在任务级别指定模型。你可以让Sonnet处理简单的代码生成让Opus处理复杂的架构设计甚至用Gemini或Codex来对比不同提供商的结果。这能显著优化token消耗和成本。纯PowerShell实现这是一个非常务实的选择。它意味着零外部依赖Node.js, Python, Docker在Windows上原生友好同时在macOS和Linux上通过PowerShell 7也能完美运行。这大大降低了团队的安装和运维成本尤其是在受控的企业环境中。3. 从零开始安装、配置与初体验3.1 环境准备与全局安装开始之前确保你的机器上已经备齐了三样东西PowerShell 7这是dotbot的运行环境。在Windows 10/11上你可以直接从Microsoft Store安装。在macOS或Linux上访问 PowerShell GitHub 页面下载。安装后在终端输入pwsh --version确认版本。Gitdotbot重度依赖Git进行版本管理和工作树隔离。确保已安装并配置好用户信息。至少一个AI提供商CLIdotbot本身不直接调用AI API而是通过官方的命令行工具来交互。你需要至少安装一个Claude CLI:npm install -g anthropic-ai/claudeOpenAI Codex CLI(或其他兼容工具): 通常需要配置API密钥。Gemini CLI: 通过相应的包管理器安装。安装好CLI后记得先运行一次登录或配置命令确保CLI可以正常访问API。接下来安装dotbot模块。最推荐的方式是使用PowerShell Gallery# 以当前用户身份安装Dotbot模块 Install-Module -Name Dotbot -Scope CurrentUser安装完成后务必关闭并重新打开你的终端窗口。这是为了让系统PATH变量更新识别新安装的dotbot命令。注意企业网络限制。如果你的环境无法访问PowerShell Gallery可以使用项目提供的备用安装脚本或者直接从GitHub仓库克隆源码进行安装。具体命令可以参考项目README中的“Alternative install methods”部分。3.2 初始化项目理解工作流与技术栈进入你的项目根目录运行初始化命令cd /path/to/your/project dotbot init这个命令会在当前目录下创建.bot/文件夹并将初始框架文件提交到Git中。这里有一个非常重要的最佳实践务必把.bot/目录纳入版本控制。很多开发者第一反应是把.bot/加入.gitignore觉得这是工具的运行时文件。但在dotbot的设计里.bot/包含了工作流定义、共享的技能、以及任务队列和会话历史等协作状态。工作树机制依赖于git来管理这些共享状态的链接。如果忽略了它任务隔离和团队同步都会失败。初始化时你可以选择为项目安装预定义的工作流或技术栈# 安装一个名为“kickstart-via-jira”的工作流假设已发布在公共注册表 dotbot init -Workflow kickstart-via-jira # 安装适用于.NET Blazor和Entity Framework的技术栈 dotbot init -Stack dotnet-blazor,dotnet-ef # 同时安装工作流和技术栈 dotbot init -Workflow kickstart-via-jira -Stack dotnet工作流定义了“做什么”。它是一个完整的自动化管道例如“从Jira创建新功能”、“修复SonarQube漏洞”、“编写组件单元测试”。技术栈定义了“用什么技术”。它提供了特定技术如.NET、React、Python所需的技能、验证脚本、代码风格钩子和MCP工具。技术栈可以继承例如dotnet-blazor栈会自动包含基础dotnet栈的所有能力。你可以随时使用dotbot list查看所有可用的工作流和技术栈。3.3 配置MCP服务器连接你的AI助手dotbot 通过Model Context Protocol与你的AI桌面应用如Claude Desktop、Warp AI通信。MCP是一种新兴标准允许AI工具安全地调用外部服务器的功能。配置方法是在你的AI工具的MCP设置文件中添加一个服务器条目。以Claude Desktop为例找到其配置文件通常在~/.config/Claude/claude_desktop_config.json或类似位置在mcpServers部分添加{ mcpServers: { dotbot: { command: pwsh, args: [ -NoProfile, -File, /ABSOLUTE/PATH/TO/YOUR/PROJECT/.bot/systems/mcp/dotbot-mcp.ps1 ], env: { DOTBOT_PROJECT_ROOT: /ABSOLUTE/PATH/TO/YOUR/PROJECT } } } }关键点command必须是pwsh(PowerShell 7)。args中的-File参数必须指向你项目里.bot/systems/mcp/dotbot-mcp.ps1这个脚本的绝对路径。相对路径通常不起作用。强烈建议设置DOTBOT_PROJECT_ROOT环境变量确保MCP服务器能正确定位项目根目录。配置完成后重启你的AI桌面应用。如果配置成功你在与AI对话时应该能看到它可以使用一系列以“dotbot_”开头的工具了比如dotbot_task_create,dotbot_decision_list等。3.4 启动仪表盘可视化掌控一切一切就绪后在项目根目录运行启动脚本.bot\go.ps1 # Windows # 或 .bot/go.ps1 # macOS/Linux脚本会启动一个本地的Web服务器并自动在浏览器中打开仪表盘默认地址是http://localhost:8686。如果端口被占用它会自动尝试下一个端口。仪表盘是你的指挥中心主要包含以下几个标签页概览显示所有已安装工作流的卡片以及它们的实时状态待办、进行中、已完成。产品查看和编辑项目级的文档如产品使命、技术栈、实体模型等。路线图查看由AI生成的任务执行计划。流程核心界面按阶段待办、分析中、已分析、进行中、完成过滤和查看所有任务。决策浏览所有的架构决策记录。工作流管理已安装的工作流查看其YAML定义。设置配置AI提供商、权限模式、主题等。4. 深入实操定义与运行你的第一个工作流4.1 解剖一个工作流定义文件让我们亲手创建一个简单但实用的工作流来理解其核心组件。在项目根目录创建.bot/workflows/my-first-workflow/workflow.yaml# workflow.yaml name: code-review-assistant description: 自动对最新提交的代码进行审查并生成审查意见。 version: 1.0.0 # 表单配置当通过仪表盘“启动”这个工作流时会显示哪些选项给用户 form: modes: - type: prompt label: 请输入本次审查的焦点如性能、安全性、代码风格留空则进行常规审查。 id: review_focus optional: true # 任务定义 tasks: - id: get-latest-commit type: script script: | $commitHash git log -1 --prettyformat:%H $commitMessage git log -1 --prettyformat:%B { hash $commitHash message $commitMessage diff git diff $commitHash^..$commitHash --no-patch # 获取变更文件列表 fullDiff git diff $commitHash^..$commitHash # 获取完整diff } | ConvertTo-Json -Depth 10 | Out-File -FilePath .bot/workspace/analysis/latest-commit.json # 这是一个纯脚本任务不经过AI用于获取确定性的数据。 - id: analyze-changes type: prompt prompt: | 你是一个资深的代码审查员。请对以下代码变更进行审查。 **提交信息**{{ readFile .bot/workspace/analysis/latest-commit.json | from_json | .message }} **变更文件列表**{{ readFile .bot/workspace/analysis/latest-commit.json | from_json | .diff }} **完整代码变更Diff** {{ readFile .bot/workspace/analysis/latest-commit.json | from_json | .fullDiff }} {% if inputs.review_focus %} **本次审查特别关注**{{ inputs.review_focus }} {% endif %} 请输出一份结构化的审查报告包括 1. 总体评价与风险等级低/中/高。 2. 发现的潜在问题按严重性排序每个问题需说明文件位置、问题描述、可能的影响、改进建议。 3. 值得表扬的好的实践。 4. 是否建议合并此提交。 model: claude-3-5-sonnet-20241022 dependsOn: [get-latest-commit] outputs: - path: .bot/workspace/reports/code-review-{{ timestamp }}.md - id: summarize-to-pr type: prompt prompt: | 将以下详细的代码审查报告浓缩成一段适合放在GitHub Pull Request评论中的总结。 总结应简洁、 actionable包含最关键的几个问题和建议。 报告内容 {{ readFile (last (glob .bot/workspace/reports/code-review-*.md)) }} model: claude-3-haiku-20240307 # 使用更小、更快的模型进行总结 dependsOn: [analyze-changes] outputs: - path: .bot/workspace/reports/pr-summary-{{ timestamp }}.txt关键元素解析form: 定义了交互界面。用户启动工作流时可以输入review_focus参数这个参数会在后续任务中通过{{ inputs.review_focus }}被引用。任务类型type: script 执行PowerShell脚本。用于获取Git信息、运行测试、执行构建等确定性操作。这类任务完全绕过AI执行速度快结果可预测。type: prompt 核心的AI任务。prompt字段支持模板语法可以嵌入上一个任务的输出readFile、输入参数inputs.xxx和函数timestamp,glob。依赖关系dependsOn确保了任务执行顺序。analyze-changes必须在get-latest-commit完成后才能开始因为它需要后者的输出文件。模型指定 每个prompt任务都可以指定不同的模型。这里用Sonnet做深度分析用更便宜的Haiku做总结优化成本。输出outputs将AI生成的内容保存到指定路径这些文件会被自动提交到工作树并可以在后续任务或仪表盘中查看。4.2 运行与监控保存好workflow.yaml后在项目目录下运行dotbot run code-review-assistantdotbot 会读取工作流定义创建任务队列然后开始执行。此时打开仪表盘http://localhost:8686切换到“流程”标签页你可以看到get-latest-commit任务状态迅速变为“进行中”然后“完成”。因为它是一个脚本任务执行速度很快。analyze-changes任务进入“分析中”状态。此时AI正在理解任务和上下文。分析完成后状态变为“已分析”。接着analyze-changes进入“进行中”状态AI开始生成审查报告。你可以实时看到任务日志在更新。最后summarize-to-pr任务被执行生成PR总结。在整个过程中你可以点击任何一个任务查看其详细的执行日志、AI的完整对话、以及生成的输出文件。所有这些都是可追溯、可审计的。4.3 实操心得如何编写高效的提示词在dotbot中编写提示词与直接和AI聊天略有不同因为你是在定义一个可重复的“程序”。以下是一些技巧明确上下文边界在prompt中使用模板变量{{ ... }}清晰地注入所需文件内容或参数。避免让AI去“猜测”或“寻找”文件这会导致不稳定的输出。结构化输出要求明确要求AI以特定格式如Markdown列表、JSON、YAML输出。这便于后续任务或人工解析和使用。例如“请以JSON格式输出包含issues和suggestions两个数组。”利用“技能”复用dotbot 的.bot/recipes/skills/目录下可以存放可复用的提示词片段。例如你可以创建一个code-review-style.md技能定义团队统一的审查标准然后在多个工作流的提示词中引用它{{ includeSkill ‘code-review-style’ }}。为分析阶段提供指引分析阶段analysing的提示词是内部使用的但你可以通过工作流定义影响它。确保你的prompt足够清晰让AI在分析时能准确识别出需要读取哪些文件、输出什么。5. 高级特性与团队协作实战5.1 企业注册表私有化共享工作流与技能对于团队来说最大的价值在于共享和复用最佳实践。dotbot 的企业注册表功能允许你将自定义的工作流、技术栈、工具打包并发布到内部的Git仓库如GitHub Enterprise, GitLab, Azure Repos中。创建私有注册表创建一个新的Git仓库例如your-company/dotbot-registry。在仓库根目录创建registry.yaml清单文件name: company-dotbot-registry description: 我们团队内部的dotbot扩展库 version: 1.0.0 workflows: secure-code-scan: path: ./workflows/secure-scan description: 安全检查工作流集成SonarQube和OWASP规则。 api-version-migration: path: ./workflows/api-migration description: 自动化API版本升级辅助工作流。 stacks: internal-java-stack: path: ./stacks/java-internal description: 包含公司内部Java代码规范、Checkstyle配置和私有库MCP工具的技术栈。按照path的指示创建对应的子目录和workflow.yaml或stack.yaml文件。将仓库推送到远程。在团队中使用私有注册表团队成员只需运行一次添加命令即可订阅这个注册表dotbot registry add mycompany https://github.your-company.com/your-company/dotbot-registry.git # 如果需要认证dotbot会提示或使用已配置的Git凭证之后初始化项目时就可以直接使用注册表中的内容了dotbot init -Workflow mycompany:secure-code-scan -Stack mycompany:internal-java-stack使用dotbot registry update可以定期拉取注册表的最新内容确保团队使用的是统一的最新版本。5.2 人工介入与审批流程全自动化的AI开发听起来很美好但在关键决策点或复杂问题上仍然需要人类的判断。dotbot 提供了灵活的人工介入机制。任务状态needs_input在提示词中你可以指示AI在无法决定或需要确认时将任务标记为needs_input。例如prompt: | 请设计用户服务的API接口。 如果关于身份验证策略使用JWT还是Session你无法从现有代码中确定倾向请将任务状态设置为needs_input并提问。 ...当任务进入needs_input状态时执行会暂停并在仪表盘上高亮显示。团队成员可以查看AI提出的问题并通过dotbot task_answer_question工具或仪表盘界面提供答案然后任务会继续。集成外部系统Jira, Teams, Email对于更正式的流程dotbot 可以配置为将问题路由到团队常用的协作工具。例如kickstart-via-jira工作流就能从Jira拉取需求并在需要澄清时将问题自动评论到对应的Jira issue下。决策记录对于重要的架构决策不应只留在AI的对话里。dotbot 提供了decision_*系列的MCP工具鼓励AI或开发者在关键节点创建正式的架构决策记录。这些记录会保存在.bot/workspace/decisions/目录下成为项目永久的、可搜索的知识库。5.3 性能优化与成本控制在团队中大规模使用AI成本和效率是必须考虑的问题。dotbot 提供了几个层面的优化手段任务级模型选择如前所述为不同的任务匹配合适的模型。代码生成用Sonnet复杂设计用Opus总结摘要用Haiku。在workflow.yaml中精细配置。并发执行dotbot 的工作流引擎支持多槽位并发。如果工作流中有多个独立的任务没有依赖关系它们可以同时执行充分利用计算资源缩短整体交付时间。上下文管理dotbot 的分析阶段会精心构建一个“上下文包”只包含实现阶段必需的文件和信息避免将整个项目代码库都塞给AI这能有效减少token消耗。脚本任务替代凡是确定性的、无需创造力的步骤都用type: script任务来完成。比如运行测试、代码格式化、执行数据库迁移脚本等。这完全免费且速度极快。6. 故障排查与维护指南6.1 常见问题速查表问题现象可能原因解决方案运行dotbot命令提示“找不到命令”1. 终端未重启。2. PowerShell模块安装路径不在PATH中。1. 关闭并重新打开所有终端窗口。2. 手动将模块路径如~/.local/share/powershell/Modules添加到用户PATH环境变量。MCP服务器连接失败AI工具中看不到dotbot工具1. MCP配置文件中路径错误。2.dotbot-mcp.ps1脚本执行权限问题。3. 项目路径包含空格或特殊字符。1. 检查claude_desktop_config.json中的args路径是否为绝对路径。2. 在PowerShell中尝试直接运行该脚本看是否有错误。3. 将项目移到不含空格和特殊字符的路径下。任务一直卡在“分析中”状态1. AI提供商CLI未正确认证或网络问题。2. 提示词过于复杂或模糊AI无法解析。3. 项目文件太多构建上下文超时。1. 运行claude --help或对应CLI命令确认API可访问。2. 查看该任务的日志在仪表盘或.bot/workspace/sessions/下看AI返回了什么错误。3. 优化提示词更明确地指定需要读取的文件。考虑使用script任务先预处理和过滤文件。Git操作失败如创建工作树失败1. 项目目录不是Git仓库。2..bot/目录被.gitignore忽略。3. 本地有未提交的更改。1. 运行git init初始化仓库。2. 检查并确保.gitignore中没有.bot/。3. 提交或贮藏当前的更改。仪表盘无法打开端口占用默认端口8686被其他程序占用。go.ps1脚本会自动尝试下一个端口8687, 8688...。检查终端输出它会在启动成功后打印正确的URL。6.2 日常维护命令项目健康检查定期运行dotbot doctor。这个命令会扫描项目检查是否存在过期的锁文件、孤立的工作树、设置不完整等问题并给出修复建议。查看状态dotbot status可以快速查看当前项目的dotbot安装状态、已安装的工作流/技术栈以及MCP服务器状态。清理如果怀疑状态混乱可以运行dotbot init --force。注意--force会重新初始化框架文件但会保留workspace/目录中的任务数据和会话历史。这是一个相对安全的“重置”操作。更新要更新全局的dotbot模块使用Update-Module Dotbot。要更新某个已安装的工作流或技术栈需要从注册表重新安装dotbot workflow add会覆盖。6.3 安全与隐私考量dotbot 在设计上考虑了一些企业级的安全需求路径净化PathSanitizer模块会从AI的输出中剥离绝对路径防止意外泄露服务器目录结构。隐私扫描在提交代码前可以配置钩子对暂存的文件运行gitleaks等工具防止密钥、令牌等敏感信息被提交。权限模式在设置中可以为每个AI提供商配置不同的权限模式。例如对于Claude可以设置为“auto”模式让AI自己判断操作是否安全对于不熟悉的提供商可以设置为“bypass”模式所有文件写操作都需要人工确认。代码防篡改.bot/systems/,.bot/hooks/等核心框架文件受预提交钩子保护直接编辑会被拒绝。更新必须通过dotbot init --force进行这保证了团队所有成员使用的核心逻辑是一致的。从我个人的使用经验来看dotbot 最大的价值在于它将AI的“灵光一现”变成了团队的“标准操作程序”。它没有取代开发者而是将开发者从重复性的、模式化的编码劳动中解放出来让我们能更专注于真正的架构设计、复杂问题解决和代码审查。对于追求工程效能和代码质量的团队来说它是一个值得深入探索的范式转变工具。刚开始定义工作流可能需要一些投入但一旦建立起几个高效的工作流模板整个团队的开发节奏和代码一致性都会得到显著的提升。