企业官网建设流程全解析

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 展开。该文档是 Maka（Apache 孵化项目）桌面产品在 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 描述中必须回答的五个问题，这是整个质量体系的第一道闸门：

同时文档给出**八条任一命中即禁止发布（No release）**的红线：

1. 已配置可用的默认模型，但旧会话仍可阻塞发送；
2. Provider 密钥、原始 Provider 错误、文件系统绝对路径、chatId 或密钥形态的值泄漏到 stdout、UI、遥测、导出、诊断或产物元数据；
3. 渲染进程可读取或打开任意绝对路径；
4. HTML/Markdown 内容可导航 Electron 渲染进程、打开启用 Node 的窗口或逃逸沙箱；
5. 新 UI 面缺少空态、加载态、错误态和焦点态；
6. 新有状态功能缺少确定性 fixture 场景与冒烟路径；
7. 新逻辑分支仅存在于 React 代码中，而在纯辅助函数可行时没有抽取为纯函数或缺少自动化测试；
8. 能用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 closed；fixture 场景播种每种状态与模型能力组合。

Week 3：健康中心、首次运行、快速聊天、设置补全

目标：设置、调试与入口点成为一等公民。

• Health Center 覆盖 provider、credential、bot、proxy、search、voice、open-gateway、storage、artifact、workspace 健康；
• 脱敏诊断复制；
• 首次运行分步器：provider 预设 → 粘贴 key → 测试/拉取模型 → 选择默认 → 发送冒烟提示；
• Quick Chat MVP：全局快捷键与面板窗口（MVP 中不采集无障碍树，除非单独批准并加门禁）；
• 设置面板：字体/侧边栏、聊天调优、可编辑快捷键、高级开关。

完成标准：首次运行不允许"降级即成功"（fallback-as-success）；Health Center 使用泛化原因而非原始 Provider 错误；Quick Chat 打开快速、聚焦输入框、复用就绪守卫、无可就绪模型时 fail closed；快捷键检测冲突并可重置默认。

Week 4：Open 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 test

4.4 桌面主进程 / IPC 测试

用于：聊天就绪与自动重绑定、外部链接守卫、窗口状态、打开路径守卫、可视化冒烟 fixture 模式、连接状态、设置 IPC 辅助、Artifact IPC 失败原因、沙箱桥健全性。

npm --workspace @maka/desktop test

4.5 渲染器纯辅助函数测试

用于：状态派生、键盘转换辅助、显示复制矩阵、状态优先级、回合物化、命令面板过滤、侧边栏陈旧/会话状态投影。

规则：如果 React 分支依据数据决定行为，除非该分支微不足道，否则必须抽取为纯辅助函数。这条规则是架构层面防止"逻辑只存在于组件内、无法被自动化测试"的硬约束。

4.6 Fixture 场景

每个新 UI 面都要有确定性 fixture。fixture 必须：

• 仅在 dev/test 运行；
• 使用隔离的workspaces/visual-smoke-*；
• 启动时从零播种；
• 不依赖真实密钥或网络；
• 仅通过visualSmoke.getState()暴露瞬态状态；
• fixture 模式关闭时返回null。

文档给出的完整场景表（共 16 个场景）：

（注：文档原始表格列出 18 行，此处完整保留。）当前仓库中，fixture 机制由MAKA_E2E_FIXTURE环境变量驱动，apps/desktop/tests/smoke.md 明确说明MAKA_E2E_FIXTURE=all 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 工作站外壳

用例：active；running；waiting permission；被配置/认证阻塞；review；done；archived；stale/rebound；error。

完成标准：侧边栏、头部与聊天主体状态一致；状态变更被持久化；状态转换被测试；没有仅靠样式推断的状态。

5.5 回合控制

用例：重试失败回合；重新生成助手回答；从先前回合分支；取消运行中回合；工具前检查点；保留旧输出。

完成标准：持久化回合状态防止覆盖；分支复制正确的消息边界；取消写入 aborted；按钮在无效时禁用。

5.6 健康中心

用例：provider OK/error/reauth；credential 缺失/吊销；bot 禁用/错误/已连接；proxy 禁用/错误/ok；storage 路径不可用；artifact 根不可用；open gateway stopped/running/error；search/voice/MCP 不可用。

完成标准：用户有一个统一位置检查系统健康；复制诊断已脱敏；每个子系统使用原因编码的状态。

5.7 首次运行

用例：无连接；无效 key 格式；provider 测试 401；模型拉取错误；fetched-empty；选择默认；发送冒烟提示。

完成标准：用户能在四步内从空工作区到达第一条真实消息；失败内联展示；无降级即成功。

5.8 快速聊天

用例：全局快捷键已注册；热键冲突；无就绪模型；有就绪模型；既有活跃会话上下文；发送/停止；关闭/重开保持草稿策略。

完成标准：Quick Chat 是同一就绪/运行时契约的入口，不引入第二条发送路径。

5.9 集成

用例：Open Gateway auth/SSE/错误；Memory inspect/delete；Voice 权限/转录错误；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 explicitly

6.2 命令门禁

任何非纯文档 PR 合并前必须通过：

npm run build npm run typecheck npm test --workspaces --if-present

UI 面还需运行 apps/desktop/tests/smoke.md 中对应的 fixture 冒烟路径。这一门禁在根 package.json 中有完整映射：build依次构建 core → storage → mcp → runtime → runtime-host → computer-use → eval → maka-agent → ui → desktop 各 workspace；test先执行build:test再通过scripts/run-workspace-tests-parallel.mjs以并发 3 并行跑全部 workspace 测试。

七、后续优先级与启示

文档第 6 节给出 P0 陈旧会话修复后的优先级顺序：

1. Artifact 工作台补全：真实 Save As、产物错误 fixture、deleted/too-large/unsupported 冒烟；
2. ModelCatalogEntry与不支持默认守卫；
3. 工作站外壳/会话状态；
4. 回合控制；
5. 健康中心；
6. 首次运行分步器；
7. 快速聊天；
8. 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