1. 项目概述一套跨AI编程助手的标准化工作流命令集如果你和我一样日常开发中频繁使用OpenCode、Claude Code或Kilo Code这类AI编程助手那你肯定遇到过这样的场景每次想让AI帮你提交代码、创建PR或者规划功能时都得在聊天框里重新描述一遍你的需求解释清楚每一步要做什么、用什么格式、有哪些注意事项。这个过程不仅重复低效而且容易因为表述不清导致AI执行出错比如提交信息格式混乱、忘了检查当前分支就直接推送甚至不小心把代码推到受保护的主分支上。CommandKenobi这个项目就是为了解决这个痛点而生的。它本质上是一个预定义的“斜杠命令”规范仓库专门针对Git操作和项目规划这类高频开发工作流。你只需要把它克隆到你的项目里就能立刻在支持的AI助手OpenCode、Claude Code、Kilo Code中使用诸如/commit-all、/create-pr、/plan-interview这样的命令。这些命令不是简单的别名而是包含了完整逻辑的“剧本”从执行前的环境检查比如Git配置、分支状态到生成符合规范的提交信息再到关键操作前必须的用户确认最后才安全地执行命令。它的核心价值在于“一次编写多处运行”——同一套工作流逻辑被翻译成了三种不同AI助手能理解的格式确保了无论你切换哪个工具都能获得一致、可靠且安全的操作体验。对于任何希望提升与AI协作效率、规范团队Git操作、减少人为失误的开发者或团队来说CommandKenobi都是一个能立刻上手、开箱即用的效率工具。它尤其适合在多人协作的项目中推广能有效统一提交信息格式强制执行代码推送前的检查流程。2. 核心设计思路与架构解析2.1 为什么需要标准化的AI命令在深入代码之前我们先聊聊设计初衷。AI助手很强大但它们本质上是“解释型”的。你每次输入的指令它都需要实时解析并决定如何执行。对于复杂、多步骤且包含安全检查的工作流比如Git提交这种“临场解释”存在几个固有风险不一致性不同开发者甚至同一个人在不同时间描述需求的方式都可能不同导致AI执行的动作千差万别。安全性缺失开发者很容易忘记在指令中加入“检查当前分支是否为main”或“提交前让我确认信息”这样的安全步骤。效率瓶颈每次都要重复描述“使用Conventional Commits格式”、“主题行不超过72字符”等规范浪费时间。CommandKenobi的解决方案是“声明式工作流”。它将最佳实践固化为一组Markdown文件AI助手只需读取并严格遵循文件中的步骤执行。这就像为AI编写了一份详细的SOP标准作业程序把人的经验和规范“编码”了进去。2.2 多工具兼容性一套逻辑三种“方言”这是项目最精妙的设计之一。OpenCode、Claude Code和Kilo Code虽然都是AI编程助手但它们的命令解析引擎、可调用工具Tools和用户交互方式各有不同。强行让一个格式通吃所有平台是不可能的。CommandKenobi采用了“核心逻辑共享交互层适配”的策略。项目目录结构清晰地体现了这一点CommandKenobi/ ├── .opencode/commands/ # 适配OpenCode的“方言” ├── .claude/commands/ # 适配Claude Code的“方言” └── .kilocode/workflows/ # 适配Kilo Code的“方言”每个目录下存放着功能完全相同的9个命令但它们的“写法”针对各自平台做了优化OpenCode使用YAML Frontmatter定义元数据description,agent通过专用的question工具进行结构化用户询问。Claude Code同样使用Frontmatter但通过allowed-tools字段严格限定可用的工具如Bash(git:*)用户交互采用直接在聊天中列出选项的“内联提示”方式。Kilo Code最简洁无需Frontmatter使用纯Markdown通过ask_user函数询问用户用execute_command执行Bash命令。尽管“方言”不同但所有命令的核心工作流逻辑——预检、分析、生成、确认、执行——是完全一致的。这种设计确保了行为的一致性也极大降低了维护成本当需要更新某个工作流时只需同步修改三个目录下的对应文件即可。2.3 安全第一的设计哲学预检与用户确认翻阅任何一个命令文件你都会发现它们把“安全”刻在了DNA里。这主要体现在两个机制上1. 预检Pre-flight Checks在执行任何实质性操作尤其是写操作之前命令会先运行一系列检查。以/commit-all为例它的预检步骤通常包括Git身份验证检查git config user.name和user.email是否已设置。没有身份信息提交会失败。仓库状态检查当前目录是否是一个Git仓库git status是否成功。分支保护获取当前分支名git branch --show-current并判断是否属于受保护分支如main,master,develop。如果在受保护分支上会向用户发出明确警告并要求额外确认。远程仓库检查是否存在远程仓库origingit remote get-url origin为后续的推送操作做准备。这些检查遵循“快速失败”原则。任何一项检查失败命令都会立即停止并给出清晰的错误提示和修复建议而不是等到执行中途才报错。2. 用户确认User Approval Workflow对于创建提交、推送代码、创建PR这类“不可逆”或“会产生影响”的操作命令绝不会擅自行动。它们会在关键节点暂停将生成的结果如拟定的提交信息、将要推送的分支清晰地呈现给用户并请求明确的批准。例如在生成提交信息后AI会展示生成的提交信息 feat(auth): 添加基于JWT的用户登录端点 请选择 1. 接受 - 使用此信息提交所有更改。 2. 重新生成 - 为我创建另一个提交信息。 3. 取消 - 中止提交操作。只有用户选择“1. 接受”后AI才会执行git commit -m feat(auth): ...。这种设计将最终控制权牢牢交还给开发者避免了AI因误解而执行错误操作的风险。3. 核心命令详解与实操指南3.1 Git操作类命令从提交到PR的一站式服务这类命令是使用频率最高的它们将日常繁琐的Git操作封装成了几个简单的单词。/commit-all与/commit-staged智能提交这两个命令都用于创建符合Conventional Commits规范的提交区别在于处理范围。/commit-all分析工作区中所有的变更包括未暂存的自动归纳变更类型生成提交信息。/commit-staged只分析已经通过git add暂存起来的变更。这给了你更大的控制权你可以先精心挑选要提交的文件再使用此命令。实操心得我个人的习惯是对于小型、关联性强的修改用/commit-all省事。对于涉及多个功能点的大修改我会先用git add -p进行交互式暂存分块处理然后对每一块使用/commit-staged这样可以保持提交历史的清晰和原子性。它们的执行流程完全一致预检检查Git配置、仓库状态、分支。分析变更运行git diff或git diff --cached分析代码变动。智能生成AI根据变更内容判断属于feat、fix、docs等哪种类型并尝试提取范围scope和简洁的主题subject。例如修改了src/auth/login.js文件它可能会生成fix(auth): 修复登录接口在空密码时的崩溃问题。用户确认展示生成的提交信息等待你确认、修改或取消。执行确认后执行git add .或跳过对于commit-staged和git commit -m “...”。/push-all与/push-staged提交并推送这两个命令在/commit-all和/commit-staged的基础上增加了推送git push到远程仓库的步骤。在推送前它会再次确认远程分支和推送操作。这是将本地工作同步到团队协作环境的关键一步。/create-pr一键创建拉取请求这是功能最集成的命令堪称“流水线终结者”。它一次性完成了提交所有更改 - 推送到远程分支 - 创建Pull Request。它首先执行类似/commit-all的流程完成提交。接着将当前分支推送到远程例如git push origin feature/new-auth。然后尝试使用GitHub CLI (gh) 自动创建PR。它会从提交历史和变更内容中提取信息自动生成PR的标题和描述正文。如果系统未安装gh它会生成一个包含预填信息的GitHub新建PR页面链接你只需点击即可手动创建。注意事项/create-pr命令的成功运行依赖于两个前提一是远程仓库如GitHub已正确配置二是如果你希望自动创建需要预先安装并认证GitHub CLI (gh auth login)。在团队项目中确保每个人都了解这个依赖可以避免命令执行到一半卡住。3.2 规划与文档类命令提升项目协作维度除了Git操作CommandKenobi还提供了提升项目前期规划和后期文档质量的命令。/plan-interview功能规划访谈当你只有一个模糊的想法时直接让AI写代码往往不是最佳选择。/plan-interview命令扮演了“产品经理”或“系统分析师”的角色。你输入一个粗略的描述如“为我们的博客系统添加文章草稿自动保存功能”AI会启动一个结构化的访谈问你一系列澄清问题自动保存的触发条件是什么时间间隔内容变化草稿数据存储在哪里前端本地存储后端数据库用户界面如何提示保存状态是否需要版本历史 通过多轮问答AI会帮你将模糊的需求梳理成一个结构清晰、包含功能点、技术考虑和验收标准的详细规划文档plan.md。如果当前在Git仓库中它还会自动为你创建一个对应的功能分支如feat/auto-save-drafts。/add-documentation为代码添加文档这个命令用于为现有的代码块或功能模块快速生成文档。你选中一段代码或指定一个文件执行此命令AI会分析代码逻辑生成包含功能说明、接口定义、使用示例和注意事项的文档。这对于补齐项目文档、生成API说明特别有用。3.3 高级工作流命令并行化与可视化/generate-social-content多平台内容并行生成这个命令展示了CommandKenobi处理复杂、多任务工作流的能力。当你需要为一个技术产品发布、版本更新或技术文章进行社交媒体宣传时手动为每个平台Twitter、LinkedIn、Reddit等撰写不同风格和格式的内容非常耗时。输入与配置你提供一个核心主题如“我们开源了CommandKenobi”选择目标时区用于安排最佳发布时间并勾选需要发布的平台如LinkedIn, Twitter。并行子代理命令不会让一个AI线程依次为每个平台写稿。相反它会为每个选中的平台启动一个独立的并行子代理Subagent。一个子代理专门研究LinkedIn的专业长文风格另一个则专注于Twitter的短平快和话题标签。它们同时工作极大缩短了总生成时间。统一输出每个子代理将其成果保存为一个独立的Markdown文件。最后一个汇总文件summary.md会被创建里面包含了一个跨平台的发布日历建议你在每个平台的最佳时间发布相应内容。/generate-onboarding生成交互式代码导览对于新加入项目的开发者来说理解代码结构是一大挑战。这个命令能自动生成一个独立的、可视化的项目导览。项目分析AI首先扫描整个项目结构识别主要的技术栈、入口文件和关键目录。并行研究随后它会启动5个并行研究子代理各自负责一个维度执行流追踪程序从启动到退出的主流程。数据流分析核心数据如用户请求、API响应如何在系统中流动。配置梳理配置文件、环境变量和初始化逻辑。模式识别项目中使用的设计模式或架构模式如MVC、Repository。依赖理清模块和第三方库之间的依赖关系。生成导览所有研究结果被汇总生成一个自包含的HTML文件。这个文件用Mermaid图表可视化架构和流程并高亮展示了关键文件的代码片段及其解释。新成员只需在浏览器中打开这个HTML文件就能获得一个结构化的项目入门指南。核心优势这两个命令的核心思想是“并行化”和“关注点分离”。通过将一个大任务拆解成多个可并行执行的子任务并分配给专门化的子代理不仅速度快而且每个部分的质量更高因为每个AI线程可以更专注。4. 深入实现命令文件结构与工具语法差异要真正用好CommandKenobi或者为其贡献新命令必须理解三种格式的具体写法。我们以最核心的“用户确认”环节为例看看同一意图在不同平台如何表达。4.1 OpenCode 格式解析OpenCode的命令文件像一个结构化的剧本以YAML Frontmatter开头定义了命令的基本信息和执行者。--- description: “提交所有更改并创建符合规范的提交信息” agent: build # 指定由‘build’类型的AI代理来执行此命令 --- ## 预检 1. 检查Git用户配置git config user.name 2. 检查当前分支git branch --show-current 3. 验证非保护分支... ## 工作流 ...分析变更、生成提交信息... ## 用户确认 使用 question 工具询问用户 - question: “提交信息已就绪。您希望执行什么操作” - header: “提交操作” - options: - label: “接受” description: “暂存所有更改并用此信息提交” - label: “取消” description: “中止提交操作” ## 错误处理 - 如果Git未配置提示用户运行 git config --global user.name “Your Name” - 如果在保护分支上警告用户并请求额外确认。关键点agent: build这很重要它告诉OpenCode应该由擅长构建、代码操作的AI来执行而不是通用聊天的AI。question工具这是OpenCode提供的结构化交互工具。它会在聊天界面弹出一个清晰的选项框用户点击即可选择体验非常友好。4.2 Claude Code 格式解析Claude Code的格式类似但Frontmatter和交互方式有区别。--- description: “提交所有更改并创建符合规范的提交信息” allowed-tools: Bash(git:*), Read, Grep # 明确允许使用的工具列表 --- ## 预检 1. 执行 Bash(git config user.name) 获取用户名。 2. 执行 Bash(git branch --show-current) 获取分支名。 ... ## 工作流 ...分析变更... ## 用户确认 在聊天中询问 生成的提交信息feat(api): 新增用户列表分页查询接口 请选择 1. 接受 — 暂存所有更改并用此信息提交 2. 重新生成 — 生成另一个提交信息 3. 取消 — 中止提交操作 请回复数字。 ## 错误处理 ...关键点allowed-tools这是安全沙箱机制。它严格限制了该命令可以调用的工具比如这里只允许执行Git相关的Bash命令、读取文件和搜索文本不能执行其他危险操作。内联聊天提示用户交互通过直接在聊天流中输出选项文本来实现用户需要输入“1”、“2”、“3”这样的数字来回应。这种方式更灵活但不如OpenCode的图形化选项直观。4.3 Kilo Code 格式解析Kilo Code的格式最为简洁去除了Frontmatter使用其内置的函数。# 提交所有更改 提交所有更改并创建符合规范的提交信息。 ## 预检 1. 使用 execute_command 执行 git config user.name。 2. 使用 execute_command 执行 git branch --show-current。 ... ## 工作流 ...分析变更... ## 用户确认 使用 ask_user: 提交信息已就绪。您希望执行什么操作 1. 接受 — 暂存所有更改并用此信息提交 2. 重新生成 — 生成另一个提交信息 3. 取消 — 中止提交操作 ## 错误处理 ...关键点无Frontmatter文件以一级标题#开头作为命令名。execute_command这是Kilo Code中执行Shell命令的函数。ask_user这是Kilo Code中用于暂停流程、向用户提问的函数。其样式类似于在代码块中显示问题。4.4 Conventional Commits 规范强制执行所有Git类命令都强制使用Conventional Commits规范这是项目统一性的基石。规范格式为type(scope): subject。type类型必须是预定义的类型之一如feat新功能、fix修复、docs文档、refactor重构等。这便于工具自动生成变更日志CHANGELOG。scope范围可选说明提交影响的范围通常是模块或组件名如(auth)、(api)。subject主题简短描述使用祈使语气“添加”而非“添加了”不超过72字符不以句号结尾。命令中的AI在生成信息时会努力从代码变更中推断出正确的type和scope。例如修改了src/models/User.js中的BUG可能会生成fix(models): 修复用户模型字段验证逻辑。5. 部署、使用与问题排查实录5.1 快速部署指南部署CommandKenobi极其简单因为它只是一个包含规范文件的仓库无需安装任何运行时。步骤一获取命令集你有两种主要方式克隆到项目推荐在你的项目根目录下直接运行git clone CommandKenobi仓库URL .。注意末尾的点号这表示克隆到当前目录而不是创建子文件夹。这会直接将.opencode、.claude、.kilocode等目录放入你的项目。手动复制如果你不想引入整个Git历史也可以直接从CommandKenobi仓库下载所需的命令目录.opencode/commands/等复制到你的项目根目录。步骤二在AI助手中使用完成复制后重启你IDE中的AI助手会话有时需要刷新。助手会自动扫描项目根目录下的特定文件夹来发现新命令。在OpenCode中输入/你应该能看到commit-all等命令出现在补全列表中。在Claude Code或Kilo Code中同理。现在你就可以像使用内置命令一样使用它们了。5.2 典型使用流程与示例假设你刚完成了一个用户登录功能的修复。检查更改你运行了git status看到修改了src/auth/login.js和test/auth.test.js。智能提交在AI聊天框中输入/commit-all并回车。预检通过AI回复“✓ Git用户已配置: yourname ✓ 当前分支: fix/login-bug ✓ 远程仓库origin存在。”分析并生成AI分析差异后提议“检测到对登录逻辑的修复和测试更新。生成的提交信息fix(auth): 修复登录时令牌验证逻辑错误并更新对应测试用例”确认执行你觉得信息很准确回复“1”或点击“接受”。完成AI执行git add .和git commit -m “...”并返回提交成功的哈希值。接下来你想把这个修复推送到远程并合并。 7.创建PR输入/create-pr。 8.自动推送AI会基于刚才的提交将fix/login-bug分支推送到远程。 9.创建PR如果安装了gh它会自动创建PR标题和描述已从提交信息中生成。如果没有它会给你一个创建PR的链接。 10.分享链接你将AI生成的PR链接发到团队群邀请同事审查。5.3 常见问题与排查技巧即使设计得再完善在实际使用中也可能遇到问题。以下是我在长期使用中总结的一些常见坑点及解决方法。问题一AI助手找不到命令现象输入/commit-all后AI没有反应或者说不认识这个命令。排查检查目录位置确认.opencode、.claude或.kilocode文件夹是否在项目的根目录下。AI助手通常只在根目录扫描这些特殊文件夹。检查文件夹名称确保文件夹名称完全正确特别是.opencode前面有点号。重启会话尝试关闭并重新打开与AI助手的聊天窗口。有时助手需要重新加载项目文件。工具匹配确保你使用的命令格式对应你当前的AI助手。不要在OpenCode中使用.kilocode/workflows/下的命令文件。问题二预检失败提示“Git用户未配置”现象执行命令时第一步就报错无法继续。解决这是最常见的问题。在终端中运行以下命令进行全局配置git config --global user.name “你的姓名” git config --global user.email “你的邮箱example.com”进阶技巧如果你需要在不同项目使用不同身份可以在项目目录下运行不加--global的上述命令设置局部配置。问题三提交信息生成不准确现象AI生成的type或scope不符合预期比如把refactor误判为feat。处理这正是用户确认环节的价值所在。当AI给出选项时直接选择“2. 重新生成”或“建议另一个”。你可以进一步用自然语言指导它例如回复“这是一个重构不是新功能请生成refactor类型的提交信息。”AI会根据你的反馈重新生成。问题四在保护分支上操作被警告现象在main分支上尝试/commit-allAI发出严重警告。最佳实践不要忽略这个警告这是项目防止误操作的重要防线。正确的做法是立即创建一个新功能分支git checkout -b feat/your-feature。切换到新分支后再执行你的命令。如果确实需要在保护分支上进行微小调整如文档更新请在确认警告后明确按照AI的提示进行额外确认。问题五/create-pr命令卡在“正在创建PR”现象命令执行了提交和推送但在创建PR时没有反应。排查检查GitHub CLI (gh)在终端运行gh --version。如果未安装命令会回退到生成手动创建链接。确保你已安装并登录gh auth login。检查远程仓库确保你的本地仓库已关联到正确的GitHub远程仓库git remote -v。网络权限有时gh需要访问令牌确认你的令牌有创建PR的权限。5.4 为团队定制与扩展命令CommandKenobi的开箱即用性很好但真正的威力在于为你的团队工作流进行定制。场景添加代码风格检查你的团队要求在提交前必须通过ESLint检查。你可以修改/commit-all等命令的“预检”部分在Git检查之后加入## 预检 ... 4. 运行代码风格检查npx eslint . --max-warnings 0 - 如果检查失败则停止并提示“ESLint检查未通过请先修复代码风格问题。”这样任何不符合规范的代码都无法被提交从流程上保证了代码质量。场景关联JIRA等任务管理系统你们使用JIRA希望提交信息能自动关联任务号。你可以修改“生成提交信息”的逻辑让AI在生成信息前先询问或自动提取当前分支名中的任务号如feature/JIRA-123-add-auth然后将任务号加入到提交信息中生成类似feat(auth): [JIRA-123] 添加用户认证模块的信息。添加全新命令如果你想添加一个全新的命令例如/run-tests运行测试套件并报告结果请遵循项目贡献指南在.opencode/commands/下创建run-tests.md编写YAML Frontmatter和基于question工具的工作流。在.claude/commands/下创建同名文件将交互方式改为内联提示并设置合适的allowed-tools如Bash(npm:*), Read。在.kilocode/workflows/下创建同名文件使用ask_user和execute_command。确保三个文件的核心逻辑预检、执行步骤、错误处理完全一致只有交互语法不同。经过这样的定制CommandKenobi就从一个通用工具变成了深度融入你团队研发流程的“自动化协作者”。它不仅仅是在执行命令更是在强制执行你们共同认可的最佳实践和规范。 CommandKenobi：一套跨AI编程助手的标准化工作流命令集
1. 项目概述一套跨AI编程助手的标准化工作流命令集如果你和我一样日常开发中频繁使用OpenCode、Claude Code或Kilo Code这类AI编程助手那你肯定遇到过这样的场景每次想让AI帮你提交代码、创建PR或者规划功能时都得在聊天框里重新描述一遍你的需求解释清楚每一步要做什么、用什么格式、有哪些注意事项。这个过程不仅重复低效而且容易因为表述不清导致AI执行出错比如提交信息格式混乱、忘了检查当前分支就直接推送甚至不小心把代码推到受保护的主分支上。CommandKenobi这个项目就是为了解决这个痛点而生的。它本质上是一个预定义的“斜杠命令”规范仓库专门针对Git操作和项目规划这类高频开发工作流。你只需要把它克隆到你的项目里就能立刻在支持的AI助手OpenCode、Claude Code、Kilo Code中使用诸如/commit-all、/create-pr、/plan-interview这样的命令。这些命令不是简单的别名而是包含了完整逻辑的“剧本”从执行前的环境检查比如Git配置、分支状态到生成符合规范的提交信息再到关键操作前必须的用户确认最后才安全地执行命令。它的核心价值在于“一次编写多处运行”——同一套工作流逻辑被翻译成了三种不同AI助手能理解的格式确保了无论你切换哪个工具都能获得一致、可靠且安全的操作体验。对于任何希望提升与AI协作效率、规范团队Git操作、减少人为失误的开发者或团队来说CommandKenobi都是一个能立刻上手、开箱即用的效率工具。它尤其适合在多人协作的项目中推广能有效统一提交信息格式强制执行代码推送前的检查流程。2. 核心设计思路与架构解析2.1 为什么需要标准化的AI命令在深入代码之前我们先聊聊设计初衷。AI助手很强大但它们本质上是“解释型”的。你每次输入的指令它都需要实时解析并决定如何执行。对于复杂、多步骤且包含安全检查的工作流比如Git提交这种“临场解释”存在几个固有风险不一致性不同开发者甚至同一个人在不同时间描述需求的方式都可能不同导致AI执行的动作千差万别。安全性缺失开发者很容易忘记在指令中加入“检查当前分支是否为main”或“提交前让我确认信息”这样的安全步骤。效率瓶颈每次都要重复描述“使用Conventional Commits格式”、“主题行不超过72字符”等规范浪费时间。CommandKenobi的解决方案是“声明式工作流”。它将最佳实践固化为一组Markdown文件AI助手只需读取并严格遵循文件中的步骤执行。这就像为AI编写了一份详细的SOP标准作业程序把人的经验和规范“编码”了进去。2.2 多工具兼容性一套逻辑三种“方言”这是项目最精妙的设计之一。OpenCode、Claude Code和Kilo Code虽然都是AI编程助手但它们的命令解析引擎、可调用工具Tools和用户交互方式各有不同。强行让一个格式通吃所有平台是不可能的。CommandKenobi采用了“核心逻辑共享交互层适配”的策略。项目目录结构清晰地体现了这一点CommandKenobi/ ├── .opencode/commands/ # 适配OpenCode的“方言” ├── .claude/commands/ # 适配Claude Code的“方言” └── .kilocode/workflows/ # 适配Kilo Code的“方言”每个目录下存放着功能完全相同的9个命令但它们的“写法”针对各自平台做了优化OpenCode使用YAML Frontmatter定义元数据description,agent通过专用的question工具进行结构化用户询问。Claude Code同样使用Frontmatter但通过allowed-tools字段严格限定可用的工具如Bash(git:*)用户交互采用直接在聊天中列出选项的“内联提示”方式。Kilo Code最简洁无需Frontmatter使用纯Markdown通过ask_user函数询问用户用execute_command执行Bash命令。尽管“方言”不同但所有命令的核心工作流逻辑——预检、分析、生成、确认、执行——是完全一致的。这种设计确保了行为的一致性也极大降低了维护成本当需要更新某个工作流时只需同步修改三个目录下的对应文件即可。2.3 安全第一的设计哲学预检与用户确认翻阅任何一个命令文件你都会发现它们把“安全”刻在了DNA里。这主要体现在两个机制上1. 预检Pre-flight Checks在执行任何实质性操作尤其是写操作之前命令会先运行一系列检查。以/commit-all为例它的预检步骤通常包括Git身份验证检查git config user.name和user.email是否已设置。没有身份信息提交会失败。仓库状态检查当前目录是否是一个Git仓库git status是否成功。分支保护获取当前分支名git branch --show-current并判断是否属于受保护分支如main,master,develop。如果在受保护分支上会向用户发出明确警告并要求额外确认。远程仓库检查是否存在远程仓库origingit remote get-url origin为后续的推送操作做准备。这些检查遵循“快速失败”原则。任何一项检查失败命令都会立即停止并给出清晰的错误提示和修复建议而不是等到执行中途才报错。2. 用户确认User Approval Workflow对于创建提交、推送代码、创建PR这类“不可逆”或“会产生影响”的操作命令绝不会擅自行动。它们会在关键节点暂停将生成的结果如拟定的提交信息、将要推送的分支清晰地呈现给用户并请求明确的批准。例如在生成提交信息后AI会展示生成的提交信息 feat(auth): 添加基于JWT的用户登录端点 请选择 1. 接受 - 使用此信息提交所有更改。 2. 重新生成 - 为我创建另一个提交信息。 3. 取消 - 中止提交操作。只有用户选择“1. 接受”后AI才会执行git commit -m feat(auth): ...。这种设计将最终控制权牢牢交还给开发者避免了AI因误解而执行错误操作的风险。3. 核心命令详解与实操指南3.1 Git操作类命令从提交到PR的一站式服务这类命令是使用频率最高的它们将日常繁琐的Git操作封装成了几个简单的单词。/commit-all与/commit-staged智能提交这两个命令都用于创建符合Conventional Commits规范的提交区别在于处理范围。/commit-all分析工作区中所有的变更包括未暂存的自动归纳变更类型生成提交信息。/commit-staged只分析已经通过git add暂存起来的变更。这给了你更大的控制权你可以先精心挑选要提交的文件再使用此命令。实操心得我个人的习惯是对于小型、关联性强的修改用/commit-all省事。对于涉及多个功能点的大修改我会先用git add -p进行交互式暂存分块处理然后对每一块使用/commit-staged这样可以保持提交历史的清晰和原子性。它们的执行流程完全一致预检检查Git配置、仓库状态、分支。分析变更运行git diff或git diff --cached分析代码变动。智能生成AI根据变更内容判断属于feat、fix、docs等哪种类型并尝试提取范围scope和简洁的主题subject。例如修改了src/auth/login.js文件它可能会生成fix(auth): 修复登录接口在空密码时的崩溃问题。用户确认展示生成的提交信息等待你确认、修改或取消。执行确认后执行git add .或跳过对于commit-staged和git commit -m “...”。/push-all与/push-staged提交并推送这两个命令在/commit-all和/commit-staged的基础上增加了推送git push到远程仓库的步骤。在推送前它会再次确认远程分支和推送操作。这是将本地工作同步到团队协作环境的关键一步。/create-pr一键创建拉取请求这是功能最集成的命令堪称“流水线终结者”。它一次性完成了提交所有更改 - 推送到远程分支 - 创建Pull Request。它首先执行类似/commit-all的流程完成提交。接着将当前分支推送到远程例如git push origin feature/new-auth。然后尝试使用GitHub CLI (gh) 自动创建PR。它会从提交历史和变更内容中提取信息自动生成PR的标题和描述正文。如果系统未安装gh它会生成一个包含预填信息的GitHub新建PR页面链接你只需点击即可手动创建。注意事项/create-pr命令的成功运行依赖于两个前提一是远程仓库如GitHub已正确配置二是如果你希望自动创建需要预先安装并认证GitHub CLI (gh auth login)。在团队项目中确保每个人都了解这个依赖可以避免命令执行到一半卡住。3.2 规划与文档类命令提升项目协作维度除了Git操作CommandKenobi还提供了提升项目前期规划和后期文档质量的命令。/plan-interview功能规划访谈当你只有一个模糊的想法时直接让AI写代码往往不是最佳选择。/plan-interview命令扮演了“产品经理”或“系统分析师”的角色。你输入一个粗略的描述如“为我们的博客系统添加文章草稿自动保存功能”AI会启动一个结构化的访谈问你一系列澄清问题自动保存的触发条件是什么时间间隔内容变化草稿数据存储在哪里前端本地存储后端数据库用户界面如何提示保存状态是否需要版本历史 通过多轮问答AI会帮你将模糊的需求梳理成一个结构清晰、包含功能点、技术考虑和验收标准的详细规划文档plan.md。如果当前在Git仓库中它还会自动为你创建一个对应的功能分支如feat/auto-save-drafts。/add-documentation为代码添加文档这个命令用于为现有的代码块或功能模块快速生成文档。你选中一段代码或指定一个文件执行此命令AI会分析代码逻辑生成包含功能说明、接口定义、使用示例和注意事项的文档。这对于补齐项目文档、生成API说明特别有用。3.3 高级工作流命令并行化与可视化/generate-social-content多平台内容并行生成这个命令展示了CommandKenobi处理复杂、多任务工作流的能力。当你需要为一个技术产品发布、版本更新或技术文章进行社交媒体宣传时手动为每个平台Twitter、LinkedIn、Reddit等撰写不同风格和格式的内容非常耗时。输入与配置你提供一个核心主题如“我们开源了CommandKenobi”选择目标时区用于安排最佳发布时间并勾选需要发布的平台如LinkedIn, Twitter。并行子代理命令不会让一个AI线程依次为每个平台写稿。相反它会为每个选中的平台启动一个独立的并行子代理Subagent。一个子代理专门研究LinkedIn的专业长文风格另一个则专注于Twitter的短平快和话题标签。它们同时工作极大缩短了总生成时间。统一输出每个子代理将其成果保存为一个独立的Markdown文件。最后一个汇总文件summary.md会被创建里面包含了一个跨平台的发布日历建议你在每个平台的最佳时间发布相应内容。/generate-onboarding生成交互式代码导览对于新加入项目的开发者来说理解代码结构是一大挑战。这个命令能自动生成一个独立的、可视化的项目导览。项目分析AI首先扫描整个项目结构识别主要的技术栈、入口文件和关键目录。并行研究随后它会启动5个并行研究子代理各自负责一个维度执行流追踪程序从启动到退出的主流程。数据流分析核心数据如用户请求、API响应如何在系统中流动。配置梳理配置文件、环境变量和初始化逻辑。模式识别项目中使用的设计模式或架构模式如MVC、Repository。依赖理清模块和第三方库之间的依赖关系。生成导览所有研究结果被汇总生成一个自包含的HTML文件。这个文件用Mermaid图表可视化架构和流程并高亮展示了关键文件的代码片段及其解释。新成员只需在浏览器中打开这个HTML文件就能获得一个结构化的项目入门指南。核心优势这两个命令的核心思想是“并行化”和“关注点分离”。通过将一个大任务拆解成多个可并行执行的子任务并分配给专门化的子代理不仅速度快而且每个部分的质量更高因为每个AI线程可以更专注。4. 深入实现命令文件结构与工具语法差异要真正用好CommandKenobi或者为其贡献新命令必须理解三种格式的具体写法。我们以最核心的“用户确认”环节为例看看同一意图在不同平台如何表达。4.1 OpenCode 格式解析OpenCode的命令文件像一个结构化的剧本以YAML Frontmatter开头定义了命令的基本信息和执行者。--- description: “提交所有更改并创建符合规范的提交信息” agent: build # 指定由‘build’类型的AI代理来执行此命令 --- ## 预检 1. 检查Git用户配置git config user.name 2. 检查当前分支git branch --show-current 3. 验证非保护分支... ## 工作流 ...分析变更、生成提交信息... ## 用户确认 使用 question 工具询问用户 - question: “提交信息已就绪。您希望执行什么操作” - header: “提交操作” - options: - label: “接受” description: “暂存所有更改并用此信息提交” - label: “取消” description: “中止提交操作” ## 错误处理 - 如果Git未配置提示用户运行 git config --global user.name “Your Name” - 如果在保护分支上警告用户并请求额外确认。关键点agent: build这很重要它告诉OpenCode应该由擅长构建、代码操作的AI来执行而不是通用聊天的AI。question工具这是OpenCode提供的结构化交互工具。它会在聊天界面弹出一个清晰的选项框用户点击即可选择体验非常友好。4.2 Claude Code 格式解析Claude Code的格式类似但Frontmatter和交互方式有区别。--- description: “提交所有更改并创建符合规范的提交信息” allowed-tools: Bash(git:*), Read, Grep # 明确允许使用的工具列表 --- ## 预检 1. 执行 Bash(git config user.name) 获取用户名。 2. 执行 Bash(git branch --show-current) 获取分支名。 ... ## 工作流 ...分析变更... ## 用户确认 在聊天中询问 生成的提交信息feat(api): 新增用户列表分页查询接口 请选择 1. 接受 — 暂存所有更改并用此信息提交 2. 重新生成 — 生成另一个提交信息 3. 取消 — 中止提交操作 请回复数字。 ## 错误处理 ...关键点allowed-tools这是安全沙箱机制。它严格限制了该命令可以调用的工具比如这里只允许执行Git相关的Bash命令、读取文件和搜索文本不能执行其他危险操作。内联聊天提示用户交互通过直接在聊天流中输出选项文本来实现用户需要输入“1”、“2”、“3”这样的数字来回应。这种方式更灵活但不如OpenCode的图形化选项直观。4.3 Kilo Code 格式解析Kilo Code的格式最为简洁去除了Frontmatter使用其内置的函数。# 提交所有更改 提交所有更改并创建符合规范的提交信息。 ## 预检 1. 使用 execute_command 执行 git config user.name。 2. 使用 execute_command 执行 git branch --show-current。 ... ## 工作流 ...分析变更... ## 用户确认 使用 ask_user: 提交信息已就绪。您希望执行什么操作 1. 接受 — 暂存所有更改并用此信息提交 2. 重新生成 — 生成另一个提交信息 3. 取消 — 中止提交操作 ## 错误处理 ...关键点无Frontmatter文件以一级标题#开头作为命令名。execute_command这是Kilo Code中执行Shell命令的函数。ask_user这是Kilo Code中用于暂停流程、向用户提问的函数。其样式类似于在代码块中显示问题。4.4 Conventional Commits 规范强制执行所有Git类命令都强制使用Conventional Commits规范这是项目统一性的基石。规范格式为type(scope): subject。type类型必须是预定义的类型之一如feat新功能、fix修复、docs文档、refactor重构等。这便于工具自动生成变更日志CHANGELOG。scope范围可选说明提交影响的范围通常是模块或组件名如(auth)、(api)。subject主题简短描述使用祈使语气“添加”而非“添加了”不超过72字符不以句号结尾。命令中的AI在生成信息时会努力从代码变更中推断出正确的type和scope。例如修改了src/models/User.js中的BUG可能会生成fix(models): 修复用户模型字段验证逻辑。5. 部署、使用与问题排查实录5.1 快速部署指南部署CommandKenobi极其简单因为它只是一个包含规范文件的仓库无需安装任何运行时。步骤一获取命令集你有两种主要方式克隆到项目推荐在你的项目根目录下直接运行git clone CommandKenobi仓库URL .。注意末尾的点号这表示克隆到当前目录而不是创建子文件夹。这会直接将.opencode、.claude、.kilocode等目录放入你的项目。手动复制如果你不想引入整个Git历史也可以直接从CommandKenobi仓库下载所需的命令目录.opencode/commands/等复制到你的项目根目录。步骤二在AI助手中使用完成复制后重启你IDE中的AI助手会话有时需要刷新。助手会自动扫描项目根目录下的特定文件夹来发现新命令。在OpenCode中输入/你应该能看到commit-all等命令出现在补全列表中。在Claude Code或Kilo Code中同理。现在你就可以像使用内置命令一样使用它们了。5.2 典型使用流程与示例假设你刚完成了一个用户登录功能的修复。检查更改你运行了git status看到修改了src/auth/login.js和test/auth.test.js。智能提交在AI聊天框中输入/commit-all并回车。预检通过AI回复“✓ Git用户已配置: yourname ✓ 当前分支: fix/login-bug ✓ 远程仓库origin存在。”分析并生成AI分析差异后提议“检测到对登录逻辑的修复和测试更新。生成的提交信息fix(auth): 修复登录时令牌验证逻辑错误并更新对应测试用例”确认执行你觉得信息很准确回复“1”或点击“接受”。完成AI执行git add .和git commit -m “...”并返回提交成功的哈希值。接下来你想把这个修复推送到远程并合并。 7.创建PR输入/create-pr。 8.自动推送AI会基于刚才的提交将fix/login-bug分支推送到远程。 9.创建PR如果安装了gh它会自动创建PR标题和描述已从提交信息中生成。如果没有它会给你一个创建PR的链接。 10.分享链接你将AI生成的PR链接发到团队群邀请同事审查。5.3 常见问题与排查技巧即使设计得再完善在实际使用中也可能遇到问题。以下是我在长期使用中总结的一些常见坑点及解决方法。问题一AI助手找不到命令现象输入/commit-all后AI没有反应或者说不认识这个命令。排查检查目录位置确认.opencode、.claude或.kilocode文件夹是否在项目的根目录下。AI助手通常只在根目录扫描这些特殊文件夹。检查文件夹名称确保文件夹名称完全正确特别是.opencode前面有点号。重启会话尝试关闭并重新打开与AI助手的聊天窗口。有时助手需要重新加载项目文件。工具匹配确保你使用的命令格式对应你当前的AI助手。不要在OpenCode中使用.kilocode/workflows/下的命令文件。问题二预检失败提示“Git用户未配置”现象执行命令时第一步就报错无法继续。解决这是最常见的问题。在终端中运行以下命令进行全局配置git config --global user.name “你的姓名” git config --global user.email “你的邮箱example.com”进阶技巧如果你需要在不同项目使用不同身份可以在项目目录下运行不加--global的上述命令设置局部配置。问题三提交信息生成不准确现象AI生成的type或scope不符合预期比如把refactor误判为feat。处理这正是用户确认环节的价值所在。当AI给出选项时直接选择“2. 重新生成”或“建议另一个”。你可以进一步用自然语言指导它例如回复“这是一个重构不是新功能请生成refactor类型的提交信息。”AI会根据你的反馈重新生成。问题四在保护分支上操作被警告现象在main分支上尝试/commit-allAI发出严重警告。最佳实践不要忽略这个警告这是项目防止误操作的重要防线。正确的做法是立即创建一个新功能分支git checkout -b feat/your-feature。切换到新分支后再执行你的命令。如果确实需要在保护分支上进行微小调整如文档更新请在确认警告后明确按照AI的提示进行额外确认。问题五/create-pr命令卡在“正在创建PR”现象命令执行了提交和推送但在创建PR时没有反应。排查检查GitHub CLI (gh)在终端运行gh --version。如果未安装命令会回退到生成手动创建链接。确保你已安装并登录gh auth login。检查远程仓库确保你的本地仓库已关联到正确的GitHub远程仓库git remote -v。网络权限有时gh需要访问令牌确认你的令牌有创建PR的权限。5.4 为团队定制与扩展命令CommandKenobi的开箱即用性很好但真正的威力在于为你的团队工作流进行定制。场景添加代码风格检查你的团队要求在提交前必须通过ESLint检查。你可以修改/commit-all等命令的“预检”部分在Git检查之后加入## 预检 ... 4. 运行代码风格检查npx eslint . --max-warnings 0 - 如果检查失败则停止并提示“ESLint检查未通过请先修复代码风格问题。”这样任何不符合规范的代码都无法被提交从流程上保证了代码质量。场景关联JIRA等任务管理系统你们使用JIRA希望提交信息能自动关联任务号。你可以修改“生成提交信息”的逻辑让AI在生成信息前先询问或自动提取当前分支名中的任务号如feature/JIRA-123-add-auth然后将任务号加入到提交信息中生成类似feat(auth): [JIRA-123] 添加用户认证模块的信息。添加全新命令如果你想添加一个全新的命令例如/run-tests运行测试套件并报告结果请遵循项目贡献指南在.opencode/commands/下创建run-tests.md编写YAML Frontmatter和基于question工具的工作流。在.claude/commands/下创建同名文件将交互方式改为内联提示并设置合适的allowed-tools如Bash(npm:*), Read。在.kilocode/workflows/下创建同名文件使用ask_user和execute_command。确保三个文件的核心逻辑预检、执行步骤、错误处理完全一致只有交互语法不同。经过这样的定制CommandKenobi就从一个通用工具变成了深度融入你团队研发流程的“自动化协作者”。它不仅仅是在执行命令更是在强制执行你们共同认可的最佳实践和规范。