MaxCode v2.0.0

[2.0.0] - 2026-04-21

V2.0 UX 大升级正式发布 —— 合并 V2.0-1（Keybindings 键绑定系统）与
V2.0-2（项目模板系统）两大里程碑。用户可自定义 27+ 键位行为，并通过
/init 一键脚手架 Python FastAPI / Node Express / TypeScript CLI 三类
常见项目。全量测试从 V1.3.0 的 1101 → 1277 pass / 0 fail（+176 测试）。

• V2.0-1 Keybindings 详见下方 [2.0.0-alpha.1]（+111 测试）
• V2.0-2 Templates 详见下方 [2.0.0-alpha.2]（+65 测试）

V2.0 验收清单全部勾选：tsc 零错误、所有新文件 <500 行、28+ 斜杠命令全部可用、
三套模板 E2E 脚手架成功、Keybindings JSON 覆盖热身通过。

显式不做（留给 V2.0-3/V2.0-2.x）：Vim 模式、Voice 输入、Chord 和弦键、
远程 URL 模板、~/.maxcode/templates/ 用户自定义模板、Handlebars 高级语法。

---

MaxCode v1.3.0

[1.3.0] - 2026-04-20

V1.3 主题：面向中国开发者的差异化深化。完成 4 个战略工作包（V1.3-1 / V1.3-3 / V1.3-4 / V1.3-I1）+ 5 个交互改进包（V1.3-I2 ~ V1.3-I6）+ P1 复盘重修。全量测试从 969 → 1101 pass / 0 fail（+132 测试）。

Added

• V1.3-1 Metaso 搜索 + Reader 迁移到 v1 API：
  • src/tools/web/WebSearchTool.ts：迁移到 POST /api/v1/search，字段契约：q / scope / size / includeSummary / includeRawContent / conciseSnippet，响应读取 webpages[].{title,link,snippet,date}
  • src/tools/web/WebReaderTool.ts（新）：POST /api/v1/reader 网页正文抓取，返回 text/plain Markdown
  • src/config/search.ts：统一 Metaso API Key 加载（env METASO_API_KEY 优先，config 次之），缺失时工具优雅降级
  • 真机活体探针 probes/v1.3-1-metaso-verify.ts
• V1.3-3 Hook 扩展 agent 类型（自主子 agent 守门人）：
  • AgentHookSchema：{type:'agent', prompt, maxTurns?, timeout?, fallback?, if?} judged union 分支
  • HookEngine.executeAgentHook()：通过 AgentRunner 依赖注入执行多轮子 agent，默认 maxTurns=10 / timeout=180s
  • extractAgentJson()：三档正则提取 {"ok":bool,"reason"}（整段 JSON / 代码块 / 混合文本），失败走 hook.fallback
  • src/tools/agent/subAgentRunner.ts：createSubAgentRunner() 工厂，子 TurnLoop 刻意不注入 hookEngine，彻底切断 hook 递归
  • 真机 E2E 探针：allow/deny 双分支验证（4.6s / 3.5s）
• V1.3-4 Coordinator 系统提示词 + Worker 续传 + 结构性嵌套防护：
  • src/core/coordinator/coordinatorPrompt.ts：协调者身份段 + 四阶段工作流（任务理解 → 方案拟定 → 派发 worker → 汇总交付）+ <task-continuation> XML 协议
  • 双通道激活：env MAXCODE_COORDINATOR_MODE=1 或 config.coordinator.enabled=true
  • AgentTool worker 分支：过滤后的 registry 剥离 Agent 工具 + worker 身份 prompt 双重结构性切断嵌套
  • SendMessage 续传路径：对已完成 worker 投递新指令，产出 <task-continuation> XML，WorkerSession 在 registry 持久化消息历史
  • src/index.ts 两入口（TUI + --print）均注册 AgentTool/SendMessageTool（parity 修复）
  • 真机 E2E：worker 派发 9.7s → continuation 4.5s（上下文复用 2x 加速）
• V1.3-I1 Memory 三件套工具：memory_write / memory_read / memory_search，PersistentMemory 原生 API 接入，替代模型 bash+sqlite3 直连的 P1-1 越权路径
• V1.3-I2 系统提示身份锚定强化：P0-2 Memory 注入 + P0-3 Identity Anchoring 探针保障
• V1.3-I4 OutputStyle 效果强化：builtin 风格内容加权 + styleWeighting 测试
• V1.3-I5 UI 消息去重：ChatHistory 重复渲染修复
• V1.3-P1 复盘重修：/output-style UX 源头修复（B 点 normalizeName 兜底）+ ConfigTool null+exists+source 三字段语义修复（真根因：runtime 合并源对齐）

Deprecated

• V1.3-2 Ollama / OpenAI-compat 本地模型支持弃用：2026-04-19 决策，MaxCode 范围收敛至 MiniMax-only。src/model/openai-compat.ts 保留但标记 @deprecated（避免破坏现有 import）

Fixed

• P1-1 ConfigTool 写入不落盘：loader 的 runtime 合并源未对齐写入源
• P1-3 ConfigTool key 探测口径不一致：返回 {setting, value, exists, source} 完整语义

Infrastructure

• 真机 E2E 探针套件：scripts/probe-coordinator-e2e.ts（19/19 mock 断言）+ scripts/probe-coordinator-real.ts（真实 MiniMax）+ scripts/probe-agent-hook-real.ts（真实 MiniMax agent hook）
• probes/ 活体验证脚本：V1.3-1 Metaso v1 · V1.3-I1 Memory 工具 · P0-2 Memory 注入 · P0-3 Identity 锚定

---

MaxCode v1.2.0

1.2.0 - 2026-04-18

V1.2 主题：内部查漏补缺 + 系统化集成。完成 7 个工作包（V1.2-1 ~ V1.2-7），
全量测试从 724 → 969 pass / 0 fail（+245 测试）。

Added

• V1.2-1 EventTrigger 接线（激活 L2 已实装的事件驱动唤醒）：
  • ToolDispatcher 新增 FireEventCallback 构造参数 + FILE_MUTATION_TOOLS 白名单；
    file_write / file_edit 成功后投递 file.changed 事件 + {toolName, path} 载荷
  • 新增 /fire-event <name> [json-payload] 斜杠命令（带 JSON 解析错误处理）
  • 6 个新单元测试
• V1.2-2 工具 DESCRIPTION 中文化锁：src/tools/__tests__/i18n.test.ts
  自动审计 22 个核心工具的 description / prompt / zod .describe()，CJK 正则判定，
  68 条断言；未来 PR 引入英文工具文档即 CI 失败
• V1.2-3 microCompact 两段式压缩：src/core/compact/microCompact.ts（~215 行）
  在 autoCompact（~93% 阈值）前增加零 LLM 的轻量裁剪档（60% 阈值），仅替换
  白名单工具的旧 tool_result.content 为占位符，保留最近 5 个结果 + 100% pairing
  完整性；合成场景 token 降幅 ≥30%；21 个新测试
• V1.2-4 Hook 扩展 prompt 类型（LLM 守门人）：
  • 新增 PromptHook 类型：配置化 LLM 评估作为 Pre/PostToolUse 事件的守门人
  • executePromptHook() 支持 $ARGUMENTS 占位符替换 + 三种 JSON 抽取路径
    （整段 / Markdown 代码块 / 混合文本）+ temperature=0 确定性采样
  • fallback 三档：LLM 失败回退到 passthrough/deny/ask
  • 20 个新单元测试 + E2E 探针（8 场景 / 25 断言）
• V1.2-5 Skills bundled 内置技能：开箱即用，无需用户放置 ~/.maxcode/skills/*.md
  • 3 个内置中文技能：commit（原子化中文 commit 生成）/ code-review（结构化
    代码审查）/ explain（代码讲解）
  • SkillMetadata.source 扩展为 'bundled' | 'project' | 'user'，优先级
    user > project > bundled
  • getBundledSkillsDir() 基于 import.meta.url 解析 + MAXCODE_BUNDLED_SKILLS_DIR
    环境变量覆盖
  • 11 个新测试 + E2E 探针（7 场景 / 30 断言）
• V1.2-6 OutputStyles 输出风格系统：可切换的终端输出风格
  • 3 个内置风格：default（空 prompt）/ concise（≤3 句、去寒暄）/ tutorial
    （解释原理 / 专有名词附定义）
  • 项目级 .maxcode/output-styles/ + 用户级 ~/.maxcode/output-styles/ 自定义
    风格，后者覆盖前者
  • TurnLoop.buildSystemPrompt() 末尾动态注入当前风格 prompt
  • /output-style [list|<name>] 斜杠命令
  • 24 个新测试 + E2E 探针（8 场景 / 40 断言）
• V1.2-7 Plugins builtin 内置插件统一管理：把分散的 builtin 能力聚合为
  可列出 + 可禁用的视图，对齐 reference 的 builtinPlugins.ts 模型
  • 4 个内置插件声明：bundled-skills / output-styles / metaso-search / reflection
  • config.plugins.disabled: string[] 禁用清单支持
  • PluginManager.loadBuiltinPlugins / isBuiltin / getBuiltinPlugins /
    getExternalPlugins 切分；同名 external 覆盖 builtin
  • SkillSystem.reload() 查询 isBuiltinPluginDisabled('bundled-skills') 决定
    是否跳过 bundled 目录（白名单语义保向后兼容）
  • 语义区分：isBuiltinPluginEnabled（严格：未注册→false）vs
    isBuiltinPluginDisabled（白名单：未注册→false）
  • /plugins 斜杠命令分组展示 builtin / external + ✅/⛔ 状态 + capabilities
  • 12 个新单元测试 + E2E 探针（8 场景 / 35 断言）
• V1.2 跨特性集成测试：src/__tests__/integration/v1.2-cross-features.test.ts
  22 个测试 / 85 断言覆盖 7 个组合场景（Output Style + System Prompt 联动、
  Builtin Plugin 禁用 → Bundled Skill 失效、microCompact pairing 完整性、
  Prompt Hook decision 透传、EventTrigger + file_write 端到端、/plugins 输出稳定性）

Changed（承袭自 L1/L2 阶段）

• A3 测试框架统一：全量迁移 vitest → bun:test（43 个测试文件）；
  vi.fn() → mock()、vi.mocked() / vi.spyOn() 改为 bun:test 原生 API；
  package.json 删除 vitest devDependency；bunfig.toml 注释澄清为 bun:test 单栈
• L1 FTS5 全文搜索：PersistentMemory 搜索从 LIKE 模糊匹配升级到 SQLite FTS5 虚拟表
  • trigram 分词器（原生支持中文）+ 加权 BM25 排序（key 10× / content 2× / tags 1×）
• L2 事件驱动 + 条件轮询触发器：EventTrigger + ConditionTrigger（白名单 DSL）
  实装；两者支持 taskStorage 持久化；scheduler.fireEvent(name, payload) 投递入口

Known Limitations

• V1.2-7 只为 bundled-skills 接入了实际行为门禁；output-styles / metaso-search /
  reflection 仅声明式接入 /plugins 展示，运行时禁用状态不改变模块行为（后续
  迭代按需实装）
• registry.ts（611 行）、hooks/engine.ts（649 行）、turnLoop.ts（1118 行）
  超过 CLAUDE.md 500 行软约束，计划在 V1.3 做架构拆分

MaxCode v1.0.1

1.0.1 - 2026-04-17

Added

• M6 发布工程化：GitHub Actions CI（每次 push 自动触发 typecheck + 724 单元测试）
• 多平台 Binary：release.yml 流水线在 tag 推送时交叉编译 4 个平台独立可执行文件
  （maxcode-linux-x64 / maxcode-darwin-arm64 / maxcode-darwin-x64 / maxcode-windows-x64.exe）
• 开箱即用安装：README 新增 curl 一行命令安装说明，无需安装 Bun

Fixed

• CI 环境安装 ripgrep 系统依赖，修复 GrepTool / GlobTool 在 Linux 上的测试失败

MaxCode V1.0.0 - 首个正式版本

[1.0.0] - 2026-04-17

Added — 三层产品价值全部激活

① 编程助手（基础）

• 14 个核心工具：file_read / file_write / file_edit / glob / grep / bash / web_search / web_fetch / task 六件套 / todo_write / ask_user / plan_mode / config / schedule / agent / send_message / skill
• 13 个斜杠命令：/help /feedback /review /tasks /skills /agents /plan /config /memory /save-memory /memories /compact /clear /exit
• 权限三级制：allow / ask / deny，规则优先级链与 Claude Code 对齐

② 自主 Agent（进阶）

• 四级授权系统 + LLM 风险评估：Level 0-3 按操作类型（file / git / system / web / destructive / scheduled）分别配置；LLM 动态评估是否升级授权（如 rm -rf 自动拦截并要求确认）
• PlanningEngine：ComplexityEstimator + ExperienceRetriever + RiskAssessor 三组件协同；LLM 智能分解任务 + 关键词启发式回退
• 主动唤醒机制：CronTrigger 定时触发；WakeupScheduler 任务持久化（进程重启后保留）
• 子代理系统：AgentTool 并行任务 + SendMessageTool 消息传递（XML <task-notification> 格式兼容 Claude Code）

③ 持续进化（差异化）

• 三层记忆系统：
  • WorkingMemory（内存 Map + pub-sub 订阅）
  • SessionMemory（JSON 文件持久化 + projectSlug 隔离）
  • PersistentMemory（SQLite + 四分类 user/feedback/project/reference + 自动 Consolidator 下沉）
• LLM 驱动反思引擎：
  • 轻量反思（任务完成后）：extractLessonsWithLLM 生成经验教训
  • 深度反思（/feedback 触发）：analyzeFeedbackWithLLM 识别多偏好维度（速度 / 详细度）
  • 每日自动复盘：WakeupScheduler + cron 触发 triggerDailyReview(24)，默认每日 23:00（可通过 reflection.dailyReviewCron 自定义）
• 自主复盘报告：/review 查看工具使用统计（调用次数、成功率、平均耗时）+ LLM 生成优化建议
• 技能系统：~/.maxcode/skills/*.md 或 .maxcode/skills/*.md 加载 Markdown 技能（Claude Code 兼容格式）
• 插件系统：~/.maxcode/plugins/ 动态加载第三方工具

Architecture — 架构亮点

• structuredCall helper：统一"LLM → 结构化 JSON"调用链路（流式收集 → JSON 抽取 → Zod 校验 → 4 种分类失败原因 empty/parse_failed/schema_failed/llm_error）；函数重载确保无 schema 时返回 unknown，消除类型洞
• LLM / 启发式双轨回退：所有 LLM 模块（PlanningEngine / ReflectionEngine / AutonomyController）LLM 失败时自动回退到启发式实现，保证基础功能永不阻塞
• Feature Gate：features.autonomy / memory / reflection 运行时开关
• 模型提供者抽象：ModelProvider 接口 + MiniMax 适配器 + OpenAI 兼容层，便于未来扩展其他模型
• 事件驱动 UI：TurnLoop.submitMessage() 的 AsyncGenerator<TurnEvent> 事件流 + Ink 流式渲染 + 50ms 防抖
• 模块依赖向下：ui → core → model / memory / security → utils / types，杜绝循环依赖

Tests & Quality

• 724 个单元测试（59 测试文件）全部通过
• TypeScript 严格模式零错误
• 所有单文件 ≤500 行（最大 App.tsx 480 行）
• E2E 手动验证：T1（反思引擎 LLM 路径）/ T2（四级授权风险评估）/ T3（/feedback 深度反思）/ T4（命令接入 + 持久化）全部通过

Technical Highlights — 技术亮点

• Bun 原生 TS：无需预编译，bun run 直接执行
• React + Ink TUI：流畅终端交互；自研 cursor-up 幽灵边框修复（StatusBar/InputBox 改用纯 Text 分隔线）
• Zod v3 验证：所有配置和工具参数运行时校验
• SQLite 持久化：复用 Bun 内建 bun:sqlite，零额外依赖

Known Limitations — 已知限制

• features.autonomy 默认关闭（安全优先），需用户显式开启四级授权
• EventTrigger / ConditionTrigger 触发器未实现（P2 功能，延后到 V2）
• MiniMax 529 过载时自动回退到启发式模式（不阻塞基础工具调用，有中文友好提示）
• 测试框架 bun:test 与 vitest 并存（V1.0 后统一）

---