现有 AI 编程助手大多是单体智能模式，在跨模块开发和长链路排障中容易出现稳定性与一致性问题。Magi 的核心目标是把“对话能力”升级为“工程交付能力”。

任务迷航	长对话后目标漂移、上下文衰减，任务完成度不稳定。	Mission 合同驱动：目标、验收、上下文三元组约束执行路径。
并发冲突	多模型并发写文件易相互覆盖，修改不可控。	零冲突引擎：File Mutex + 实时强读 + 意图驱动编辑。
故障反复	失败后重复同路径重试，缺少根因沉淀。	闭环自修复：动态 Todo + 多轮验证 + 补充指令注入。
知识断层	对话结束即“失忆”，经验无法持续复用。	本地知识沉淀：Rolling Summary + WisdomExtractor + PKB。
治理失衡	所有任务用同一执行强度，效率与安全难兼得。	双模式治理：常规模式提速，深度模式强约束保安全。

• 跨模块功能开发：前后端/配置/脚本联动变更，自动拆分并并行推进。
• 复杂 Bug 排障：支持“定位-修复-复验”闭环，减少反复重试。
• 大规模重构：深度模式下强制委派 + 快照回溯，降低改造风险。

• 深度模式更稳但更慢：适合高复杂任务，不追求秒级响应。
• 结果质量依赖任务描述：Goal 与 Acceptance 越清晰，交付越稳定。
• 外部能力依赖本地配置：CLI/MCP 未正确配置会影响对应能力可用性。

• 本地优先：代码检索、任务状态、知识沉淀在本地工作区完成。
• 模型调用可控：仅使用你配置的模型通道（OpenAI/Anthropic/Gemini 等）执行推理。

Magi 的核心理念： 用正确的模型，做正确的事。

你只需描述目标，Magi 自动完成：

你不再是提示词工程师，而是 AI 团队的技术负责人。

• 以 Goal / Acceptance / Context 组织任务，不再依赖发散式自由对话。
• 支持 Assignment 级责任划分，Worker 结果可追踪、可验收。
• 执行中允许动态追加 Todo，面向真实工程问题逐步收敛。

• 常规模式：低延迟交付，适合轻量修改与日常开发。
• 深度模式：编排者禁改代码，强制委派 Worker，适配跨模块与系统级改造。
• 同一套引擎下按任务复杂度切换治理强度，平衡速度与稳定性。

• File-level Mutex：同文件写入串行化，防并发覆盖。
• 实时强读：写入前读取磁盘最新状态，降低上下文陈旧风险。
• 意图驱动编辑：模型表达“改什么”，底层负责稳定落盘。
• 上下文新鲜度治理：执行中自动处理文件上下文陈旧，减少无效重试。

• UnifiedSessionManager 按 trace/session 物理隔离状态，避免串会话污染。
• 快照机制覆盖关键写操作，支持故障后恢复与回溯。
• 补充指令队列支持执行中追加需求，在下一决策点生效，不打断主流程。

• MemoryDocument 负责滚动摘要，压缩噪声并保留关键上下文。
• WisdomExtractor 从 Worker 报告提取 learnings / decisions / warnings。
• 结果沉淀到项目知识库（PKB），提升后续同类任务命中率。

• 内置文件读写、代码检索、任务调度、进程执行等工程工具。
• 原生支持 MCP（Model Context Protocol）接入外部能力。
• 支持 Skills 动态加载，按场景扩展专业能力。

• Mission：面向用户目标的总体任务。
• Assignment：分派给具体 Worker 的职责单元。
• Todo：执行中的可演化步骤（可新增、可重排、可闭环修复）。

• Phase A 规划：意图分析、复杂度评估、任务拆解与上下文注入。
• Phase B 执行：Worker 并行推进，依赖任务按拓扑顺序接力。
• Phase C 验收：对照验收标准复核，未达标自动进入修复循环。

• ContractManager：管理接口契约与协作边界。
• FileMutex：保障并发写安全。
• SnapshotManager：关键步骤可回溯。
• TaskViewService：任务态可视化，便于追踪执行链路。

• VSCode：插件模式需要 >= 1.93.0
• Node.js：建议 >= 18
• 可用 CLI：至少配置一个（Claude / Codex / Gemini）
• 网络：如需联网检索或外部模型调用，请确保网络可用

在 VSCode 扩展市场搜索 Magi 并安装，或通过 .vsix 本地安装。

在 VSCode 设置中搜索 magi，配置编排与 Worker 使用的 CLI 路径：

• magi.claude.path
• magi.codex.path
• magi.gemini.path

• magi.deepTask = false：常规模式（默认）
• magi.deepTask = true：深度模式（项目级治理）

• 打开面板：Ctrl+Shift+A（Mac: Cmd+Shift+A）
• 启动任务：Ctrl+Shift+Enter（Mac: Cmd+Shift+Enter）
• 新建会话：Ctrl+Alt+N（Mac: Cmd+Alt+N）
• 停止任务：Ctrl+Shift+Backspace（Mac: Cmd+Shift+Backspace）
• 打开 Web 客户端：命令面板执行 Magi: 打开 Web 客户端

Web 模式不依赖 VSCode 插件，但需要你自己启动 Local Agent。当前提供两种启动方式：

先构建：

npm install
npm run build:agent
npm run build:web

再启动后端：

MAGI_AGENT_WORKSPACES='[{"rootPath":"/absolute/path/to/your/project","name":"your-project"}]' node dist/agent.js

启动完成后，浏览器访问：

http://127.0.0.1:46231/web.html?workspacePath=/absolute/path/to/your/project

说明：

• Local Agent 默认监听 127.0.0.1:46231
• workspacePath 建议传绝对路径，前端会据此自动绑定工作区
• 这种方式下，后端会直接托管 dist/web，因此只需要起一个服务

终端 1 启动后端：

MAGI_AGENT_WORKSPACES='[{"rootPath":"/absolute/path/to/your/project","name":"your-project"}]' npm run dev:agent

终端 2 启动前端：

npm run dev:web

浏览器访问：

http://127.0.0.1:3000/web.html?workspacePath=/absolute/path/to/your/project

说明：

• npm run dev:web 会启动 Vite 开发服务器，默认端口 3000
• 前端 /api 与 /api/events 会自动代理到 http://127.0.0.1:46231
• 适合调试 Web UI 或前后端联调

• 在新会话输入：请读取 README.md 并总结当前版本号
• 观察是否成功触发任务、出现执行状态与最终回复
• 若失败，优先检查 CLI 路径、API Key、MAGI_AGENT_WORKSPACES 与工作区路径是否正确

Magi 的诞生离不开早期支持者的帮助。

Poonwai

agassiz

StoneFancyX

Token 支持: BinCode 中转站

无论是功能建议、Bug 反馈还是商务合作，欢迎随时交流。

本项目采用 双重授权协议 (Dual Licensing)：

1. 开源授权：本项目核心代码采用 GNU GPL v3 协议。你可以免费使用、修改和分发代码；如果你基于此项目开发新软件并分发，项目也必须保持开源并采用 GPL 协议。
2. 商业授权：如果你不希望受到 GPL 协议的限制（例如集成到闭源商业产品），可联系购买商业授权。

如有商业授权需求或任何疑问，请联系作者：

• WeChat: MistRipple
• GitHub: MistRipple