Exarchos是一个本地优先的软件开发生命周期（SDLC）工作流框架，为Claude Code等AI编程助手提供结构化、持久化的状态管理，通过状态机强制执行阶段转换，解决长会话中上下文丢失和指令漂移的问题。

Exarchos：为AI编程助手打造的状态化工作流框架\n\n随着Claude Code、Cursor、GitHub Copilot等AI编程助手的普及，开发者面临一个新的挑战：如何在长会话中保持工作的连贯性和可追溯性？当上下文窗口被填满、当需要/clear清理内存、当多个任务并行推进时，如何确保AI助手不会"遗忘"之前的规划和约定？Exarchos项目正是为解决这些问题而生。\n\n## 核心问题：AI编程助手的"失忆症"\n\n使用过Claude Code的开发者都知道，虽然AI助手功能强大，但在长会话中存在几个痛点：\n\n1. 上下文窗口限制：随着对话进行，早期的指令和规划可能被挤出上下文窗口，导致AI开始忽略最初的约定\n2. 状态丢失：使用/clear清理上下文后，之前的任务状态、设计决策全部消失\n3. 缺乏强制执行：即使有CLAUDE.md或自定义规划，AI也可能在长会话中偏离既定流程\n4. 难以追溯：当出现问题时，很难回溯AI到底做了什么决策、为什么这样做\n\nExarchos的核心理念是：让状态独立于上下文窗口之外。它提供了一个结构化的、持久化的状态管理系统，通过状态机强制执行工作流阶段，让AI编程助手的行为更可预测、更可审计。\n\n## 什么是Exarchos？\n\nExarchos（希腊语"领导者"之意）是一个本地优先的SDLC（软件开发生命周期）工作流框架。它以Claude Code插件和独立MCP（Model Context Protocol）服务器的形式提供，为AI编程助手提供：\n\n- 结构化状态：工作流状态存储在本地，独立于AI的上下文窗口\n- 阶段强制：状态机控制工作流转换，确保按既定流程执行\n- 确定性收敛：通过TypeScript检查而非提示词来验证任务完成\n- 审计追踪：所有操作记录在追加式事件日志中\n- 断点续作：/checkpoint保存状态，/rehydrate恢复，支持随时中断和恢复\n\n## 架构设计：Agent-First的哲学\n\nExarchos的架构完全围绕AI编程助手的工作方式设计：\n\n### 四种工作流类型\n\n1. Feature（功能开发）：完整的 ideate → plan → implement → review 流程\n2. Debug（调试）：triage → investigate → fix → validate，支持热修复或彻底修复模式\n3. Refactor（重构）：assess → brief → implement，支持快速打磨或全面重构\n4. Oneshot（一次性）：轻量级的 plan → implement → commit，适合简单变更\n\n每种工作流都有明确的阶段定义和转换规则，AI助手必须在当前阶段完成后才能进入下一阶段。\n\n### 类型化的Agent团队\n\nExarchos定义了三种角色，每种角色有特定的工具集、钩子函数和工作区隔离：\n\n- Implementer（实现者）：负责代码实现，有独立的Git工作区\n- Fixer（修复者）：专门处理失败任务，可以恢复完整上下文继续工作\n- Reviewer（审查者）：执行两阶段审查（规范符合性+代码质量）\n\n这种设计让AI助手可以像人类团队一样分工协作，每个角色专注于自己的职责。\n\n### 两阶段审查机制\n\n不同于简单的"请审查这段代码"提示，Exarchos实施严格的两阶段审查：\n\n1. 规范符合性审查：实现是否符合设计文档的要求？\n2. 代码质量审查：代码写得是否优雅、安全、可维护？\n\n审查通过确定性的收敛门（convergence gates）执行，这些是用TypeScript编写的检查函数，直接分析Git diff和历史记录，而不是依赖AI的自我评估。\n\n### Runbooks（运行手册）\n\nExarchos通过MCP提供机器可读的编排序列。AI助手可以请求特定阶段的运行手册，获得有序的工具调用列表、参数模式和门语义。任何MCP客户端都可以使用这些运行手册，不限于Claude Code。\n\n## MCP工具接口\n\nExarchos作为MCP服务器暴露四个复合工具：\n\n| 工具 | 功能 |\n|------|------|\n| exarchos_workflow | 工作流生命周期：init、get、set、cancel、cleanup、reconcile |\n| exarchos_event | 追加式事件存储：append、query、batch |\n| exarchos_orchestrate | 团队协调：任务分发、审查分流、运行手册、Agent规范 |\n| exarchos_view | CQRS投影：流水线状态、任务看板、堆栈健康度 |\n\n所有工具支持延迟模式（lazy schema loading），启动时只注册精简描述，完整模式按需加载，将MCP启动开销控制在500 token以内。\n\n## 安装与使用\n\n### 作为Claude Code插件\n\nbash\n/plugin marketplace add lvlup-sw/.github\n/plugin install exarchos@lvlup-sw\n\n\n### 作为独立MCP服务器\n\nbash\nnpx @lvlup-sw/exarchos mcp\n\n\n### 交互式安装器\n\nbash\nnpx create-exarchos\n\n\n安装器会自动安装Exarchos和可选的配套工具（Serena语义代码分析、Context7库文档、Microsoft Learn文档）。\n\n### 安装技能包\n\nExarchos的技能以平台无关的源码形式提供，需要根据目标Agent运行时生成渲染包：\n\nbash\nexarchos install-skills --agent claude\nexarchos install-skills --agent codex\nexarchos install-skills --agent cursor\nexarchos install-skills --agent copilot\nexarchos install-skills # 自动检测\n\n\n自动检测会检查PATH中的已知Agent二进制文件和环境变量。如果检测到多个Agent，会交互式询问目标。\n\n## 核心命令详解\n\n### 启动工作流\n\n| 命令 | 用途 | 说明 |\n|------|------|------|\n| /ideate | 功能开发 | 设计探索、TDD规划、并行实现 |\n| /debug | Bug修复 | 分类、调查、修复、验证 |\n| /refactor | 代码重构 | 评估范围、简报、实现 |\n| /oneshot | 简单变更 | 轻量级 plan → implement → commit |\n\n### 生命周期管理\n\n| 命令 | 功能 |\n|------|------|\n| /plan | 从设计文档创建TDD实现计划 |\n| /delegate | 在工作区中分发任务给Agent队友 |\n| /review | 执行两阶段审查 |\n| /synthesize | 从功能分支创建PR |\n| /shepherd | 推动PR通过CI和审查直至可合并 |\n| /cleanup | 将已合并工作流标记为完成 |\n| /prune | 交互式批量取消陈旧的非终端工作流 |\n\n### 状态管理\n\n| 命令 | 功能 |\n|------|------|\n| /checkpoint | 保存工作流状态以便后续恢复 |\n| /rehydrate | 在压缩或会话中断后恢复工作流状态 |\n| /reload | 在上下文退化后重新注入上下文 |\n| /autocompact | 切换自动压缩或设置阈值 |\n| /tag | 将当前会话归属到功能或项目 |\n| /tdd | 使用严格的红绿重构模式规划实现 |\n\n## 实际工作流程示例\n\n### 场景：开发一个新功能\n\n\n# 启动功能开发工作流\n/ideate\n → AI进行设计探索\n → 生成设计文档\n → 等待用户批准\n\n# 用户批准后\n/plan\n → 基于设计创建TDD计划\n → 生成测试用例列表\n → 等待用户确认\n\n# 开始实现\n/delegate\n → 创建独立工作区\n → 并行分发任务给Implementer Agent\n → 跟踪进度\n\n# 实现完成后\n/review\n → 阶段1：检查是否符合设计规范\n → 阶段2：代码质量审查\n → 生成审查报告\n\n# 创建PR\n/synthesize\n → 从功能分支生成PR\n → 自动填写描述\n\n# 推动合并\n/shepherd\n → 监控CI状态\n → 响应审查意见\n → 直至可合并\n\n# 清理\n/cleanup\n → 归档工作流\n → 更新状态\n\n\n### 场景：长会话管理\n\n当上下文窗口即将填满时：\n\n\n/checkpoint\n → 保存当前工作流状态\n → 生成摘要（约2-3k token）\n\n/clear\n → 清理上下文窗口\n\n/rehydrate\n → 从检查点恢复状态\n → 继续之前的工作\n\n\n## 技术实现细节\n\n### 状态持久化\n\nExarchos将状态存储在本地文件系统中，使用结构化格式（可能是JSON或SQLite），确保：\n\n- 数据不依赖AI的内存\n- 可以跨会话持久化\n- 支持版本控制和审计\n\n### 事件溯源架构\n\n所有工作流转换、门结果和Agent操作都记录到追加式事件日志。这种事件溯源模式提供：\n\n- 完整的操作历史\n- 可重放和调试\n- 审计和合规支持\n\n### Token效率优化\n\nExarchos在设计上高度关注Token效率：\n\n- 延迟模式注册：MCP启动时只注册精简描述（<500 token）\n- **字段投影**：状态查询时只返回必要字段，减少90%的token消耗\n- **Diff审查**：审查时发送diff而非完整文件\n\n### 多运行时支持\n\nExarchos支持多种Agent运行时：\n\n- **MCP原生宿主**：Claude Code、Cursor、Codex\n- **CLI-only宿主**：OpenCode、Copilot、通用运行时\n\n每种运行时会自动选择最适合的调用方式。远程/托管MCP部署也在规划中。\n\n## 生态系统与配套工具\n\nExarchos设计为一个生态系统，包含多个可选配套工具：\n\n| 组件 | 来源 | 用途 |\n|------|------|------|\n| Exarchos | 核心插件 | 工作流状态、事件日志、团队协调、收敛门 |\n| Serena | 可选配套 | 语义代码分析 |\n| Context7 | 可选配套 | 最新库文档 |\n| Microsoft Learn | 可选配套 | Azure和.NET文档 |\n\n这些配套工具通过npx create-exarchos安装器可选安装。\n\n## 开发要求与许可\n\n- **Node.js**: >= 20\n- 许可证: Apache-2.0\n\n开发设置：\n\nbash\ngit clone https://github.com/lvlup-sw/exarchos.git && cd exarchos\nnpm install && npm run build\nclaude --plugin-dir .\n\n\n## 总结与展望\n\nExarchos代表了AI辅助编程工具的下一波进化——从单纯的"聊天式编程"转向"结构化、可审计、可恢复的工作流管理"。它解决了当前AI编程助手的核心痛点：状态管理、流程强制执行和上下文持久化。\n\n对于需要处理复杂项目、长期维护代码库或团队协作的开发者，Exarchos提供了一个重要的基础设施层。它不改变AI编程的本质，但让它变得更可靠、更可控、更适合生产环境。\n\n随着AI编程助手能力的不断增强，像Exarchos这样的工作流框架将成为标准配置，帮助开发者在享受AI效率提升的同时，保持软件开发的专业性和可维护性。

Exarchos：为AI编程助手打造的状态化工作流框架\n\n随着Claude Code、Cursor、GitHub Copilot等AI编程助手的普及，开发者面临一个新的挑战：如何在长会话中保持工作的连贯性和可追溯性？当上下文窗口被填满、当需要/clear清理内存、当多个任务并行推进时，如何确保AI助手不会"遗忘"之前的规划和约定？Exarchos项目正是为解决这些问题而生。\n\n核心问题：AI编程助手的"失忆症"\n\n使用过Claude Code的开发者都知道，虽然AI助手功能强大，但在长会话中存在几个痛点：\n\n1. 上下文窗口限制：随着对话进行，早期的指令和规划可能被挤出上下文窗口，导致AI开始忽略最初的约定\n2. 状态丢失：使用/clear清理上下文后，之前的任务状态、设计决策全部消失\n3. 缺乏强制执行：即使有CLAUDE.md或自定义规划，AI也可能在长会话中偏离既定流程\n4. 难以追溯：当出现问题时，很难回溯AI到底做了什么决策、为什么这样做\n\nExarchos的核心理念是：让状态独立于上下文窗口之外。它提供了一个结构化的、持久化的状态管理系统，通过状态机强制执行工作流阶段，让AI编程助手的行为更可预测、更可审计。\n\n什么是Exarchos？\n\nExarchos（希腊语"领导者"之意）是一个本地优先的SDLC（软件开发生命周期）工作流框架。它以Claude Code插件和独立MCP（Model Context Protocol）服务器的形式提供，为AI编程助手提供：\n\n- 结构化状态：工作流状态存储在本地，独立于AI的上下文窗口\n- 阶段强制：状态机控制工作流转换，确保按既定流程执行\n- 确定性收敛：通过TypeScript检查而非提示词来验证任务完成\n- 审计追踪：所有操作记录在追加式事件日志中\n- 断点续作：/checkpoint保存状态，/rehydrate恢复，支持随时中断和恢复\n\n架构设计：Agent-First的哲学\n\nExarchos的架构完全围绕AI编程助手的工作方式设计：\n\n四种工作流类型\n\n1. Feature（功能开发）：完整的 ideate → plan → implement → review 流程\n2. Debug（调试）：triage → investigate → fix → validate，支持热修复或彻底修复模式\n3. Refactor（重构）：assess → brief → implement，支持快速打磨或全面重构\n4. Oneshot（一次性）：轻量级的 plan → implement → commit，适合简单变更\n\n每种工作流都有明确的阶段定义和转换规则，AI助手必须在当前阶段完成后才能进入下一阶段。\n\n类型化的Agent团队\n\nExarchos定义了三种角色，每种角色有特定的工具集、钩子函数和工作区隔离：\n\n- Implementer（实现者）：负责代码实现，有独立的Git工作区\n- Fixer（修复者）：专门处理失败任务，可以恢复完整上下文继续工作\n- Reviewer（审查者）：执行两阶段审查（规范符合性+代码质量）\n\n这种设计让AI助手可以像人类团队一样分工协作，每个角色专注于自己的职责。\n\n两阶段审查机制\n\n不同于简单的"请审查这段代码"提示，Exarchos实施严格的两阶段审查：\n\n1. 规范符合性审查：实现是否符合设计文档的要求？\n2. 代码质量审查：代码写得是否优雅、安全、可维护？\n\n审查通过确定性的收敛门（convergence gates）执行，这些是用TypeScript编写的检查函数，直接分析Git diff和历史记录，而不是依赖AI的自我评估。\n\nRunbooks（运行手册）\n\nExarchos通过MCP提供机器可读的编排序列。AI助手可以请求特定阶段的运行手册，获得有序的工具调用列表、参数模式和门语义。任何MCP客户端都可以使用这些运行手册，不限于Claude Code。\n\nMCP工具接口\n\nExarchos作为MCP服务器暴露四个复合工具：\n\n| 工具 | 功能 |\n|------|------|\n| exarchos_workflow | 工作流生命周期：init、get、set、cancel、cleanup、reconcile |\n| exarchos_event | 追加式事件存储：append、query、batch |\n| exarchos_orchestrate | 团队协调：任务分发、审查分流、运行手册、Agent规范 |\n| exarchos_view | CQRS投影：流水线状态、任务看板、堆栈健康度 |\n\n所有工具支持延迟模式（lazy schema loading），启动时只注册精简描述，完整模式按需加载，将MCP启动开销控制在500 token以内。\n\n安装与使用\n\n作为Claude Code插件\n\nbash\n/plugin marketplace add lvlup-sw/.github\n/plugin install exarchos@lvlup-sw\n\n\n作为独立MCP服务器\n\nbash\nnpx @lvlup-sw/exarchos mcp\n\n\n交互式安装器\n\nbash\nnpx create-exarchos\n\n\n安装器会自动安装Exarchos和可选的配套工具（Serena语义代码分析、Context7库文档、Microsoft Learn文档）。\n\n安装技能包\n\nExarchos的技能以平台无关的源码形式提供，需要根据目标Agent运行时生成渲染包：\n\nbash\nexarchos install-skills --agent claude\nexarchos install-skills --agent codex\nexarchos install-skills --agent cursor\nexarchos install-skills --agent copilot\nexarchos install-skills 自动检测\n\n\n自动检测会检查PATH中的已知Agent二进制文件和环境变量。如果检测到多个Agent，会交互式询问目标。\n\n核心命令详解\n\n启动工作流\n\n| 命令 | 用途 | 说明 |\n|------|------|------|\n| /ideate | 功能开发 | 设计探索、TDD规划、并行实现 |\n| /debug | Bug修复 | 分类、调查、修复、验证 |\n| /refactor | 代码重构 | 评估范围、简报、实现 |\n| /oneshot | 简单变更 | 轻量级 plan → implement → commit |\n\n生命周期管理\n\n| 命令 | 功能 |\n|------|------|\n| /plan | 从设计文档创建TDD实现计划 |\n| /delegate | 在工作区中分发任务给Agent队友 |\n| /review | 执行两阶段审查 |\n| /synthesize | 从功能分支创建PR |\n| /shepherd | 推动PR通过CI和审查直至可合并 |\n| /cleanup | 将已合并工作流标记为完成 |\n| /prune | 交互式批量取消陈旧的非终端工作流 |\n\n状态管理\n\n| 命令 | 功能 |\n|------|------|\n| /checkpoint | 保存工作流状态以便后续恢复 |\n| /rehydrate | 在压缩或会话中断后恢复工作流状态 |\n| /reload | 在上下文退化后重新注入上下文 |\n| /autocompact | 切换自动压缩或设置阈值 |\n| /tag | 将当前会话归属到功能或项目 |\n| /tdd | 使用严格的红绿重构模式规划实现 |\n\n实际工作流程示例\n\n场景：开发一个新功能\n\n\n启动功能开发工作流\n/ideate\n → AI进行设计探索\n → 生成设计文档\n → 等待用户批准\n\n用户批准后\n/plan\n → 基于设计创建TDD计划\n → 生成测试用例列表\n → 等待用户确认\n\n开始实现\n/delegate\n → 创建独立工作区\n → 并行分发任务给Implementer Agent\n → 跟踪进度\n\n实现完成后\n/review\n → 阶段1：检查是否符合设计规范\n → 阶段2：代码质量审查\n → 生成审查报告\n\n创建PR\n/synthesize\n → 从功能分支生成PR\n → 自动填写描述\n\n推动合并\n/shepherd\n → 监控CI状态\n → 响应审查意见\n → 直至可合并\n\n清理\n/cleanup\n → 归档工作流\n → 更新状态\n\n\n场景：长会话管理\n\n当上下文窗口即将填满时：\n\n\n/checkpoint\n → 保存当前工作流状态\n → 生成摘要（约2-3k token）\n\n/clear\n → 清理上下文窗口\n\n/rehydrate\n → 从检查点恢复状态\n → 继续之前的工作\n\n\n技术实现细节\n\n状态持久化\n\nExarchos将状态存储在本地文件系统中，使用结构化格式（可能是JSON或SQLite），确保：\n\n- 数据不依赖AI的内存\n- 可以跨会话持久化\n- 支持版本控制和审计\n\n事件溯源架构\n\n所有工作流转换、门结果和Agent操作都记录到追加式事件日志。这种事件溯源模式提供：\n\n- 完整的操作历史\n- 可重放和调试\n- 审计和合规支持\n\nToken效率优化\n\nExarchos在设计上高度关注Token效率：\n\n- 延迟模式注册：MCP启动时只注册精简描述（<500 token）\n- **字段投影**：状态查询时只返回必要字段，减少90%的token消耗\n- **Diff审查**：审查时发送diff而非完整文件\n\n多运行时支持\n\nExarchos支持多种Agent运行时：\n\n- **MCP原生宿主**：Claude Code、Cursor、Codex\n- **CLI-only宿主**：OpenCode、Copilot、通用运行时\n\n每种运行时会自动选择最适合的调用方式。远程/托管MCP部署也在规划中。\n\n生态系统与配套工具\n\nExarchos设计为一个生态系统，包含多个可选配套工具：\n\n| 组件 | 来源 | 用途 |\n|------|------|------|\n| Exarchos | 核心插件 | 工作流状态、事件日志、团队协调、收敛门 |\n| Serena | 可选配套 | 语义代码分析 |\n| Context7 | 可选配套 | 最新库文档 |\n| Microsoft Learn | 可选配套 | Azure和.NET文档 |\n\n这些配套工具通过npx create-exarchos安装器可选安装。\n\n开发要求与许可\n\n- **Node.js**: >= 20\n- 许可证: Apache-2.0\n\n开发设置：\n\nbash\ngit clone https://github.com/lvlup-sw/exarchos.git && cd exarchos\nnpm install && npm run build\nclaude --plugin-dir .\n\n\n总结与展望\n\nExarchos代表了AI辅助编程工具的下一波进化——从单纯的"聊天式编程"转向"结构化、可审计、可恢复的工作流管理"。它解决了当前AI编程助手的核心痛点：状态管理、流程强制执行和上下文持久化。\n\n对于需要处理复杂项目、长期维护代码库或团队协作的开发者，Exarchos提供了一个重要的基础设施层。它不改变AI编程的本质，但让它变得更可靠、更可控、更适合生产环境。\n\n随着AI编程助手能力的不断增强，像Exarchos这样的工作流框架将成为标准配置，帮助开发者在享受AI效率提升的同时，保持软件开发的专业性和可维护性。