Maka 全产品交付与测试计划解读从功能完成到可发布的质量契约体系【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka本文基于仓库归档文档 full-product-test-plan-2026-05.md 展开。该文档是 MakaApache 孵化项目桌面产品在 2026 年 5-6 月期间的一份一个月交付计划与质量门禁契约已于 2026-07-13 归档作为历史上下文保留。文中所述的能力Artifact 工作台、模型目录、工作站外壳、健康中心、首次运行引导、快速聊天等在后续版本中逐步落地但其确立的**交付契约方法论**——一个功能只有在用户流程、数据契约、测试、fixture、冒烟路径、安全/隐私门禁全部就位时才视为完成——至今仍贯穿 Maka 的工程实践。一、文档定位交付契约而非功能清单文档开篇即明确其本质This document is a delivery contract.它不是一个 UI 存在、PR 合并就宣告完成的功能清单而是一份把完成重新定义的契约。归档批注说明当前进度与工作项已迁移到 GitHub issues 与 pull requests 中本文件仅作为历史计划保留。这份契约的核心判断标准是一个功能只有同时满足以下全部条件才算完成用户流程User Flow可完整走通数据契约Data Contract被定义且稳定单元/存储/运行时/IPC/渲染器辅助等各层测试齐备fixture 与冒烟路径Smoke Path确定性可复现安全/隐私门禁Security/Privacy Gates通过。这一理念与仓库当前的测试组织方式一脉相承——根目录 package.json 将test定义为先构建再并行跑全部 workspace 测试而 apps/desktop/tests/smoke.md 作为桌面发布检查清单明确场景清单与检查标识符存在于脚本和 fixture 中而非文档中把可执行证据下沉到代码层。二、非协商规则Non-negotiable Rules文档第 0 节定义了每条 PR 描述中必须回答的五个问题这是整个质量体系的第一道闸门问题要求Contract契约变更了哪些数据结构、IPC 通道、运行时事件、持久化状态或组件契约User Flow用户流程用户在此 PR 之后能走通的确切路径是什么Tests测试哪些单元/存储/运行时/IPC 主进程/渲染器辅助/fixture/冒烟测试覆盖了它Security安全适用的信任边界、密钥处理、路径防护、沙箱、脱敏或权限规则Not Included未包含明确声明哪些相邻工作不在范围内、另行跟踪同时文档给出**八条任一命中即禁止发布No release**的红线已配置可用的默认模型但旧会话仍可阻塞发送Provider 密钥、原始 Provider 错误、文件系统绝对路径、chatId 或密钥形态的值泄漏到 stdout、UI、遥测、导出、诊断或产物元数据渲染进程可读取或打开任意绝对路径HTML/Markdown 内容可导航 Electron 渲染进程、打开启用 Node 的窗口或逃逸沙箱新 UI 面缺少空态、加载态、错误态和焦点态新有状态功能缺少确定性 fixture 场景与冒烟路径新逻辑分支仅存在于 React 代码中而在纯辅助函数可行时没有抽取为纯函数或缺少自动化测试能用node:test确定性测试的场景却用手工门禁。这八条红线与源码中的实现事实相互印证。例如packages/core/src/redaction.ts中实现了redactSecrets、classifyGeneralizedError与generalizedErrorMessage专门用于把原始 Provider 错误如401、429、5xx、net::ERR_CONNECTION_RESET归类为timeout/rate_limited/auth_failed/provider_error/network_error五类稳定机器码并提供 en / zh-CN / zh-TW 三语文案——这正是红线 2 中原始 Provider 错误不得泄漏的落地实现。三、一个月交付计划的四个阶段文档将交付拆为四个周目标每阶段都给出必需交付物Required deliverables与完成标准Done means。Week 1恢复信任并完成 Artifact 工作台目标核心聊天发送路径与生成的工作产物必须可靠。P0彻底关闭陈旧会话stale session发送/重绑定问题Artifact 面板成为真正的工作台面而非转录装饰Artifact 具备真实的保存/导出行为Artifact 运行时钩子覆盖常见产文件工具fixture 与冒烟覆盖 normal、error、deleted、too-large、unsupported MIME、reload 状态。完成标准包括fake、旧后端、已删除连接、陈旧模型、有效 Z.ai 默认值等场景全部有测试Artifact 记录以文件为后端渲染进程永不接触绝对路径删除 tombstone 阻断读取symlink 逃逸失败HTML 预览仅查看且带沙箱并阻断导航二进制预览使用嗅探后的 MIME 白名单冒烟路径覆盖亮色、暗色、窄宽、重载与失败状态。Week 2模型目录、工作站外壳、会话状态、回合控制目标Maka 不再像通用聊天列表而是带显式状态的工作台。ModelCatalogEntry携带归一化的能力、来源、陈旧/不支持原因、上下文与定价字段聊天默认模型不能是仅图像、仅嵌入、不支持、已禁用、缺失或陈旧且无可见原因会话状态模型active、running、waiting、blocked、review、done、archived、stale、errored侧边栏/头部暴露工作区、模型、状态、阻塞原因与旧会话迁移状态回合控制retry、regenerate、branch-from-turn、cancel、checkpoint-before-tools。完成标准状态转换有node:test覆盖回合控制不能覆盖旧输出取消持久化显式 aborted 状态不支持模型在 ModelTable 可见且在发送就绪检查中 fail closedfixture 场景播种每种状态与模型能力组合。Week 3健康中心、首次运行、快速聊天、设置补全目标设置、调试与入口点成为一等公民。Health Center 覆盖 provider、credential、bot、proxy、search、voice、open-gateway、storage、artifact、workspace 健康脱敏诊断复制首次运行分步器provider 预设 → 粘贴 key → 测试/拉取模型 → 选择默认 → 发送冒烟提示Quick Chat MVP全局快捷键与面板窗口MVP 中不采集无障碍树除非单独批准并加门禁设置面板字体/侧边栏、聊天调优、可编辑快捷键、高级开关。完成标准首次运行不允许降级即成功fallback-as-successHealth Center 使用泛化原因而非原始 Provider 错误Quick Chat 打开快速、聚焦输入框、复用就绪守卫、无可就绪模型时 fail closed快捷键检测冲突并可重置默认。Week 4Open Gateway、记忆、语音、搜索、MCP、来源/技能/自动化目标在不隐性扩大权限的前提下完成承诺的生态与自动化面。兼容 OpenAI 的本地网关auth、SSE、模型映射、用量遥测、shutdown记忆 MVP显式 inspect/delete 控制无隐藏权限扩大语音输入 MVP权限状态与转录修正搜索/网页引用面来源 chips 与导出行为MCP 服务器面板状态、作用域、工具列表、禁用控制Sources、Skills、Automations 视图auth/scope、允许的工具、上次运行、上次错误、禁用。完成标准每个外部集成都有 auth、missing、timeout、network、rate limit、revoked 状态每个自动化可见、可禁用、可审计技能安装绝不隐含权限扩大诊断与遥测脱敏并按原因编码。四、九层测试体系Testing Layers文档第 2 节把测试按作用域划分为九层每层都给出用途与命令门禁是理解 Maka 工程质量体系的核心骨架。4.1 核心单元测试用于数据契约与枚举校验、权限分类、脱敏与泛化错误消息、模型能力/就绪规则、会话/回合状态转换。npm --workspace maka/core test对应源码位于 packages/core/src其中 model-catalog.ts 的ModelCatalogEntry接口canUseAsChatDefault、supportsVision、thinkingLevels、contextWindow、knowledgeCutoff等字段与 model-catalog.test.ts 正是模型能力/就绪规则与数据契约校验的典型对象。buildModelCatalogEntries对 fetched / fallback / fetched-empty / saved-id 等来源做归一化合并isModelExplicitlyUnsupportedForChat依据显式chat: false、仅图像/音频输出模态declaresNoTextOutput或仅图像生成且无其他能力三种规则判定模型不可用于聊天——这与 Week 2 中聊天默认模型不能是仅图像/不支持的完成标准一一对应。4.2 存储测试用于JSONL 头迁移、Artifact 元数据与文件后端载荷、凭据/连接持久化、遥测聚合、symlink 与路径穿越防护、tombstone 与清理行为。npm --workspace maka/storage test从源码结构看packages/storage/src/__tests__/下存在 artifact-store.test.ts、artifact-attachments.test.ts、atomic-file-write.test.ts 等测试覆盖 Artifact 文件后端、路径防护与原子写入印证 Week 1 中Artifact 记录文件后端化、tombstone 阻断读取、symlink 逃逸失败的要求。4.3 运行时测试用于SessionManager 生命周期、配置变更后后端重建、流式事件、工具产物推导、取消、权限搁置permission parking、Provider 模型拉取与连接测试。npm --workspace maka/runtime test4.4 桌面主进程 / IPC 测试用于聊天就绪与自动重绑定、外部链接守卫、窗口状态、打开路径守卫、可视化冒烟 fixture 模式、连接状态、设置 IPC 辅助、Artifact IPC 失败原因、沙箱桥健全性。npm --workspace maka/desktop test4.5 渲染器纯辅助函数测试用于状态派生、键盘转换辅助、显示复制矩阵、状态优先级、回合物化、命令面板过滤、侧边栏陈旧/会话状态投影。规则如果 React 分支依据数据决定行为除非该分支微不足道否则必须抽取为纯辅助函数。这条规则是架构层面防止逻辑只存在于组件内、无法被自动化测试的硬约束。4.6 Fixture 场景每个新 UI 面都要有确定性 fixture。fixture 必须仅在 dev/test 运行使用隔离的workspaces/visual-smoke-*启动时从零播种不依赖真实密钥或网络仅通过visualSmoke.getState()暴露瞬态状态fixture 模式关闭时返回null。文档给出的完整场景表共 16 个场景场景用途first-run空工作区、无连接provider-workspace已拉取模型、默认、已验证provider-fallback降级来源与刷新错误provider-empty拉取为空状态connection-errorneeds_reauth/error 头部turn-narrative用户、工具、助手、token 汇总、思考streaming-sidebar流式预览与未读优先级permission-destructive破坏性 PermissionDialogartifact-panehtml、diff、markdown/文件产物artifact-errors已删除、过大、不支持的 MIME、缺失stale-sessionsfake/陈旧/已删除会话行与头部徽章workstation-statusesactive/running/waiting/blocked/review/done/archiveturn-controlsretry/regenerate/branch/cancel/checkpointmodel-catalog聊天/图像/嵌入/不支持/陈旧模型health-center全部健康 全部错误first-run-stepper快乐路径 测试/拉取失败quick-chat面板打开、无就绪默认、就绪默认sources-skills-automations来源 auth/scope、技能工具、自动化上次运行注文档原始表格列出 18 行此处完整保留。当前仓库中fixture 机制由MAKA_E2E_FIXTURE环境变量驱动apps/desktop/tests/smoke.md 明确说明MAKA_E2E_FIXTUREall npm --workspace maka/desktop run dev可在不触碰真实工作区的情况下交互式检查确定性 fixture并使用MAKA_E2E_FIXTURE指定单一场景做窄范围启动。4.7 冒烟路径apps/desktop/tests/smoke.md 是发布检查清单。每个 fixture 场景都需要一条冒烟路径或明确说明由现有路径覆盖的理由。每条冒烟路径必须包含启动命令fixture 场景精确的用户步骤预期 UI 状态失败状态亮/暗/窄宽截图要求重载持久化预期禁止回归项no-go regressions。当前 smoke.md 中还补充了真实 Electron 窗口冒烟npm --workspace maka/desktop run smoke:real-window与程序化窗口冒烟smoke:programmatic-window因为截图和 DOM 检查不能证明原生缩放、拖拽区域、模态焦点或健康的活动渲染进程——这正是文档每条冒烟路径必须含失败状态精神的延续。4.8 视觉回归每个新 UI 面必须覆盖的截图状态亮色桌面暗色桌面窄宽度加载空态错误/失败激活/焦点态。当前自动化命令npm --workspace maka/desktop run screenshots # 捕获所有 fixture 场景覆盖亮/暗、1280/990 宽度、正常/减少动效 npm --workspace maka/desktop run screenshots:diff:stable # 稳定子集artifact-pane、first-run、artifact-errors的阻塞健全性门禁该门禁PR-IR-02只在采集/管线/视口失败时失败缺失 PNG、损坏 PNG、过小/截断 PNG、尺寸错误。字节大小漂移仅是警告而非阻塞。文档明确声明其局限这不是像素级视觉回归测试不证明布局、颜色、排版、间距或焦点渲染保持正确审查者仍须人工检查截图并用冒烟路径验证行为。未来自动化目标先在稳定子集试点像素级 diff用校准容差代替字节/SHA 相等支持时间戳/流式/瞬态 UI 的忽略动态区域保存 diff 产物供审查门禁在主分支安静后才扩展到稳定子集之外。4.9 安全与隐私门禁每个功能必须声明七条边界路径边界网络边界密钥边界渲染进程/主进程信任边界导出/剪贴板边界遥测/日志边界权限边界。必须通过的检查scripts/check-console.mjs通过新增console.*仅限 dev 或带理由加入白名单导出/诊断中的用户/Provider 文本已脱敏原始 Provider 错误走generalizedErrorMessage渲染进程永不接收解密后的密钥除非该面是明确的本地路径管理面否则不展示绝对路径文件操作使用 realpath 包含containment而非字符串前缀检查不受信任内容的 Electron 导航/window-open 保持阻断。脱敏与泛化错误的实现可在 packages/core/src/redaction.ts 中直接查看redactSecrets组合了 JSON 序列化脱敏与文本脱敏URL userinfo/query、Authorization 头、AWS CLI 令牌、sk-/AIza/ghp_等密钥形态正则classifyGeneralizedError把错误分类为五类机器码generalizedErrorMessage输出英文泛化文案。同目录的 redaction.test.ts 为这些规则提供测试覆盖。五、功能完成定义Feature Done Definitions文档第 3 节为九个功能面逐一给出用例矩阵与完成标准是交付契约的具体化。以下完整保留。5.1 聊天发送与会话就绪用例无默认连接默认指向fake连接缺失连接被禁用API key 缺失模型缺失模型列表为空模型未启用陈旧 fake 会话 就绪默认陈旧缺失连接 就绪默认陈旧会话无就绪默认重绑定后的活跃后端缓存。完成标准就绪默认 陈旧旧会话在自动重绑定后成功发送无就绪默认以原始机器可读原因失败发送失败时渲染进程保留未发送输入头部/侧边栏在发送前解释陈旧状态所有用例有测试。5.2 Artifact 工作台用例list/get/read text/read binary/delete工具输出的实时产物创建已删除 tombstone 阻断读取symlink 逃逸路径穿越文本过大不支持 MIME含外链的 HTML重载持久化Finder 中显示真实 Save As。完成标准Artifact 是一等对象转录引用紧凑面板预览可靠导出/保存不向渲染进程暴露绝对路径。5.3 模型目录用例fetched 来源fallback 来源fetched-empty陈旧缓存不支持的仅图像不支持的仅嵌入执行模式缺工具调用自定义 OpenAI 兼容定价覆盖。完成标准UI 展示来自后端归一化目录的事实聊天就绪拒绝不支持的默认模型表解释禁用行。5.4 工作站外壳用例activerunningwaiting permission被配置/认证阻塞reviewdonearchivedstale/rebounderror。完成标准侧边栏、头部与聊天主体状态一致状态变更被持久化状态转换被测试没有仅靠样式推断的状态。5.5 回合控制用例重试失败回合重新生成助手回答从先前回合分支取消运行中回合工具前检查点保留旧输出。完成标准持久化回合状态防止覆盖分支复制正确的消息边界取消写入 aborted按钮在无效时禁用。5.6 健康中心用例provider OK/error/reauthcredential 缺失/吊销bot 禁用/错误/已连接proxy 禁用/错误/okstorage 路径不可用artifact 根不可用open gateway stopped/running/errorsearch/voice/MCP 不可用。完成标准用户有一个统一位置检查系统健康复制诊断已脱敏每个子系统使用原因编码的状态。5.7 首次运行用例无连接无效 key 格式provider 测试 401模型拉取错误fetched-empty选择默认发送冒烟提示。完成标准用户能在四步内从空工作区到达第一条真实消息失败内联展示无降级即成功。5.8 快速聊天用例全局快捷键已注册热键冲突无就绪模型有就绪模型既有活跃会话上下文发送/停止关闭/重开保持草稿策略。完成标准Quick Chat 是同一就绪/运行时契约的入口不引入第二条发送路径。5.9 集成用例Open Gateway auth/SSE/错误Memory inspect/deleteVoice 权限/转录错误Search 引用/导出MCP 服务安装/连接/工具列表Sources/Skills/Automations 作用域与禁用。完成标准每个集成可见、受限、可禁用、可测试没有集成静默扩大工具权限。六、PR 检查清单与命令门禁6.1 PR 检查清单模板文档第 4 节提供可直接复制进 PR 描述的清单节选核心## Contract - [ ] Data/API/event/state changes described - [ ] docs/design-system.md or docs/full-product-test-plan.md updated if contract changed ## User Flow - [ ] Main happy path described - [ ] Failure path described - [ ] Reload/persistence behavior described ## Tests - [ ] core/storage/runtime/desktop tests added or marked N/A with reason - [ ] renderer pure helper test added where practical - [ ] fixture scenario added/updated - [ ] smoke.md path added/updated - [ ] light/dark/narrow screenshots captured or visual gate marked N/A with reason ## Security - [ ] secrets redacted - [ ] raw provider errors generalized - [ ] path boundary uses realpath containment - [ ] renderer does not receive arbitrary absolute paths - [ ] Electron navigation/window-open/sandbox boundary unchanged or tightened - [ ] console/log behavior checked ## Not Included - [ ] Follow-up work listed explicitly6.2 命令门禁任何非纯文档 PR 合并前必须通过npm run build npm run typecheck npm test --workspaces --if-presentUI 面还需运行 apps/desktop/tests/smoke.md 中对应的 fixture 冒烟路径。这一门禁在根 package.json 中有完整映射build依次构建 core → storage → mcp → runtime → runtime-host → computer-use → eval → maka-agent → ui → desktop 各 workspacetest先执行build:test再通过scripts/run-workspace-tests-parallel.mjs以并发 3 并行跑全部 workspace 测试。七、后续优先级与启示文档第 6 节给出 P0 陈旧会话修复后的优先级顺序Artifact 工作台补全真实 Save As、产物错误 fixture、deleted/too-large/unsupported 冒烟ModelCatalogEntry与不支持默认守卫工作站外壳/会话状态回合控制健康中心首次运行分步器快速聊天Open Gateway / Memory / Voice / Search / MCP / Sources-Skills-Automations。并明确要求下一个实现 PR 应针对第 1 项且不得把范围扩大到无关的 UI 打磨。这份归档计划对 Maka 及同类 Agent 桌面产品最有价值的启示在于质量体系不是测试数量的堆叠而是把完成从主观判断改写为可验证契约——每个功能必须同时回答契约、用户流程、测试、安全、范围五个问题任何一环缺失都不能发布。读者可将本文作为理解 Maka 工程质量方法论的人口进一步阅读 apps/desktop/tests/smoke.md发布冒烟运行手册、packages/core/src/model-catalog.ts模型目录归一化实现与 packages/core/src/redaction.ts脱敏与错误泛化实现以对照计划中的门禁在实际代码中的落地形态。【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
