Apache Maka 能力成熟度审计 v1 全解读从聊天式桌面 App 到参考级 Agent 工作台的能力契约路线图【免费下载链接】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本文基于 Maka 仓库归档的能力审计文档docs/archive/maka-capability-audit-v1-2026-05.md该文档是对 2026-05-22main832bbac基线的一次时点性审计回应了 task #12 中详细挖掘现在项目存在的问题和需要继续做的能力。它给出的是将 Maka 从能聊天的桌面 app推向成熟工作台时必须补齐的 13 项系统级 contract 与分波次落地路线。读完本文你将掌握 Maka 的工件Artifact模型、工具输出流式增量协议、模型目录演进、会话状态机、Turn 控制、健康中心、Sources/Skills/Automations、首次运行、Memory MVP、Open Gateway 等核心契约的完整定义以及按 Wave A–D 推进的推荐 PR 顺序和明确的不可照搬清单。0. 审计背景与基线判断审计针对的是 2026 年 5 月的 Maka 代码基线其参考代码路径包括 packages/core/src/session.ts、packages/core/src/events.ts、packages/core/src/llm-connections.ts、packages/runtime/src/session-manager.ts、packages/runtime/src/builtin-tools.ts、apps/desktop/src/main/main.ts。文档已声明于 2026-07-13 归档其进度与前端文档引用不再构成当前指引——因此本文保留其作为能力契约的参考骨架并用当前仓库代码佐证其中若干契约的落地形态。审计基线判断给出的核心结论有三层Maka 当时已不是早期 chat demoprovider model discovery 已走 live fetch source/fetchedAt contractSettings / ModelTable / turn grouping / typed tool renderer / visual smoke fixture 已有基本 gateElectron 安全边界、console audit、readiness reason、window state 等桌面基础已补过一轮。但能力层仍然薄核心数据模型仍围绕 session JSONL messages没有 artifact、workspace status、turn control、source/automation、health、memory 这类成熟工作台必须具备的持久化对象。因此接下来最重要的不是继续堆 Settings polish而是补数据结构和状态机。这一判断在今天仓库里依然成立例如 packages/core/src/session.ts 已把SESSION_STATUSES固化为active / running / waiting_for_user / blocked / aborted五种运行态并给出SESSION_BLOCKED_REASONSNO_REAL_CONNECTION / auth / permission_required / tool_failed / unknown说明文档提出的session 状态机已经进入 core 层成为一等契约。1. 第一优先级ArtifactRecord 与右栏成果面板现状问题审计时的痛点当时 Maka 的 tool result 全部落在 transcript 里ToolResultContent只有file_diff / file_write / terminal / image / summary等结果形状UI 通过 typed renderer 渲染 diff/terminal但仍是 chat turn 的一部分大 HTML、图片、PDF、长 diff、生成文件没有成为可选择、可复看、可导出的工作成果。用户路径上的不成熟感生成网页/图片/文档后只能在长聊天里翻找结果terminal/diff 占据主叙事缺少成果面板后续 snapshot / rollback / preview 没有对象可挂载。Contract / API审计文档给出的核心契约export type ArtifactKind | file | html | image | pdf | diff | terminal | json | markdown; export interface ArtifactRecord { id: string; sessionId: string; turnId?: string; toolUseId?: string; kind: ArtifactKind; title: string; createdAt: number; updatedAt: number; source: tool_result | user_upload | export | snapshot; ref: StorageRef; mimeType?: string; bytes?: number; summary?: string; status: ready | streaming | errored | deleted; errorReason?: string; }存储约束artifacts.jsonlper session 或artifacts/metadata.jsonlper workspacelarge payload 必须 file-backed不进入session.jsonlHTML preview 使用sandboxed iframe禁止 inline untrusted script 执行deletion 先soft-delete避免 transcript 中引用断裂。IPC 面artifacts:list(sessionId?)、artifacts:get(id)、artifacts:open(id)、artifacts:delete(id)、artifacts:export(id, format?)Renderer 面right pane 作为--z-panel消费者Chat turn 内只显示 compact artifact cardpane 负责 full preview / copy / open / export。失败原因failure state需固定语义artifact_missing、artifact_deleted、artifact_too_large、artifact_preview_unsupported、artifact_load_failed、artifact_sandbox_blocked。当前仓库中的落地证据这条契约在今天的仓库中已深度落地且比审计文档定义得更细packages/core/src/artifacts.ts 把ARTIFACT_KINDS收敛为[file, diff, html, image, pdf]并新增ArtifactDescriptor/ArtifactRecord接口其中relativePath被明确规定为artifact-root 相对路径绝不暴露为 renderer 可用的文件系统路径artifacts.ts。来源source枚举比审计文档更丰富tool_result、tool_result_projection、tool_result_archive、subagent_writeback、deep_research、user_upload、session_effect并配套三张策略表userDeletable/userVisible/sharedReadableartifacts.ts。这直接落实了审计文档删除先 soft-delete、可见性不等于可删除的原则——例如tool_result_archive属于用户不可见、不可删、不可共享读而tool_result的 HTML 工件被特判为用户可见artifacts.ts。图片预览有字节级护栏ARTIFACT_IMAGE_PREVIEW_MAX_BYTES 2 * 1024 * 1024并通过resolveArtifactImagePreview统一裁决mime_match / ext_fallback与kind_disallowed / mime_disallowed / no_mime_no_ext / oversize等拒绝原因artifacts.ts。存储侧 packages/storage/src/artifact-store.ts 提供createSqliteArtifactStoreWriteAuthority文本预览上限 10MB、二进制预览上限 50MBARTIFACT_TEXT_PREVIEW_LIMIT_BYTES/ARTIFACT_BINARY_PREVIEW_LIMIT_BYTES删除走ArtifactUserDeleteResult { kind: deleted }的软删除语义。桌面端已有真实的成果面板apps/desktop/src/renderer/features/workbar/tools/artifacts/artifact-pane.tsx与配套样式apps/desktop/src/renderer/styles/workbar/artifacts.cssIPC 层在apps/desktop/src/main/runtime-host-artifacts-ipc-main.ts与apps/desktop/src/preload/preload.ts。Gate审计文档要求node:test 覆盖 ArtifactStore 的 append/list/get/delete 与 HTML file-backed 不变量fixture 新增artifact-panescenario含 html image diff errored artifactsmoke 覆盖 Artifact pane open / preview / export / error截图覆盖 light/dark/narrow 与 missing artifact failure state。2. Tool output streaming delta 协议让长任务看得见现状问题Maka 当时已有ToolProgressEvent但 runtime tools 多数只在 tool 完成后返回完整 resultBash使用exec只有完成后一次性拿到 stdout/stderrUI 的 terminal renderer 只能显示 settled output。后果是长测试 / build / install 没有实时 stdout用户以为 app 卡住Stop 后看不到 partial output。Contract / API扩展事件export interface ToolProgressEvent extends BaseEvent { type: tool_progress; toolUseId: string; sequence: number; stream: stdout | stderr | progress | text; text: string; truncated?: boolean; }Runtime 侧Bash 从exec改成spawnstdout/stderr chunk 经redaction后发tool_progressfinaltool_result保留 capped output artifact ref完整日志入 artifactabort 时落tool_resultwithisErrortruereasonaborted或独立 aborted event。失败原因tool_aborted、tool_timeout、tool_output_truncated、tool_spawn_failed、tool_permission_denied。当前仓库中的落地证据core 事件层已经把delta 先到 UI、final result 再落盘模型化ToolOutputDeltaEventtype: tool_output_delta被明确定义为与ToolResultEvent分离的瞬时 UI 侧信道——deltas are transient UI updates, while tool_result remains the terminal persisted result并通过单调递增的seqper toolCallId/toolUseId让 renderer 可以在事件/结果竞争race中做去重与修复而不依赖到达顺序packages/core/src/events.ts。同时ToolProgressEvent保留chunk形态支持steps:N/M形式的进度编码encodeToolStepProgress/decodeToolStepProgressevents.ts。这些字段与审计文档的sequence / stream / text一一对应且额外补上了redacted标记——这正是审计文档强调的chunk 经 redaction 后发出的落地形态。3. ModelCatalogEntry模型目录不再只是 ModelInfo现状问题当时ModelInfo只有id/contextWindow/maxOutputTokens/capabilitiescapabilities 也只有 vision/reasoning/functionCalling。不足没有modechat/image/audio/embedding/rerank没有 pricing/source/stale/unsupporteddefault model 校验只看 model id 是否在 enabled list无法阻止 image-only / embedding-only model 被设为 chat defaultHealth / first-run 无法解释模型存在但不能用于当前 chat。Contract / APIexport type ModelCapability | chat | tool_use | vision | reasoning | image_generation | audio_input | audio_output | embedding; export interface ModelCatalogEntry { id: string; displayName?: string; providerType: ProviderType; capabilities: ModelCapability[]; contextWindow?: number; maxOutputTokens?: number; pricing?: { inputPerMtok?: number; outputPerMtok?: number; currency: USD | CNY; source: builtin | provider | user; }; source: fetched | fallback | user_custom; fetchedAt?: number; stale?: boolean; unsupportedReason?: not_chat_model | missing_tool_use | provider_deprecated | unknown; }Readiness guard审计文档要求chat default 必须capabilities.includes(chat)tool mode 必须tool_useimage/audio model 不能设为 chat default。失败原因model_unsupported、model_stale、model_not_chat_capable、model_requires_refresh。当前仓库中的落地证据packages/core/src/model-catalog.ts 中的ModelCatalogEntry已按此方向演进canUseAsChatDefault、isDefault、supportsVision、thinkingLevels、compactionThreshold、contextWindow、inputLimit、knowledgeCutoff等字段取代了单纯的ModelInfo。其底层核心正是审计文档强调的backend-normalized catalog而不是 UI 猜buildModelCatalogEntries统一处理live fetched / empty fetched权威空/ fallback / savedModelIds / modelOverrides的合并优先级空数组只有在modelSource fetched时才被视为权威空响应否则回退到静态目录model-catalog.tsresolveConnectionModelCatalog作为 Host 侧唯一入口先经normalizeOpenAiCodexConnection过滤订阅不可服务的模型再构建目录——one entry point for what models does this connection have, and what is true about themmodel-catalog.tschat 守卫的实现细节很有参考价值isModelExplicitlyUnsupportedForChat不只查capabilities.chat false还检查modalities.output是否非空且不含textdeclaresNoTextOutput——空列表不是证据只有非空且不含 text 才说明该模型只出图/只出音无法对话model-catalog.ts。这正是审计文档unsupportedReason: not_chat_model的源码级落地。Gatenode:test 验证 unsupported/image-only 不能成为 defaultfixture 构造 mixed chat/image/embedding 模型smoke 验证 ModelTable 将 unsupported row 置灰并显示 reason。4. Session status / workstation shell把运行态变成持久状态现状问题SessionSummary当时没有 status运行态由 renderer 的streamingBySessionmap 临时推断。单窗口短聊天够用但对工作台不够session 处于 running / waiting permission / blocked / errored / review / done 无持久状态app 重启后无法恢复上次卡在 permission / 上次工具失败sidebar 只能显示 unread / streaming dot不知道工作流阶段Health / automations / artifacts 都缺 workspace shell 可挂载的位置。Contract / APIexport type SessionStatus | active | running | waiting_permission | blocked | review | done | errored | archived; export interface SessionHeader { status: SessionStatus; statusReason?: string; workspace?: { root: string; branch?: string; pr?: string; dirty?: boolean; }; }Runtime 状态转换规则send start →runningpermission_request →waiting_permissionpermission deny →blockedcomplete →done或review由 turn control 决定error →erroredwith reasonarchive →archived。失败原因session_connection_missing、session_permission_blocked、session_tool_failed、session_aborted、session_recovery_needed。当前仓库中的落地证据packages/core/src/session.ts 已把状态机固化为SESSION_STATUSES [active, running, waiting_for_user, blocked, aborted]并配套SessionBlockedReasonSessionHeader接口包含status与statusUpdatedAtsession.tsSessionSummary同样携带status/statusUpdatedAt。值得注意的演进是turn 状态被单独建模为TURN_STATUSES [running, completed, aborted, failed]session.ts并且代码注释特别提醒status写入存储崩溃发生在 turn 结束与 status 写入之间会让running永远遗留——因此引入了runningTurnIds报告与turn_state消息的记录/推断双通道statusSource: recorded | inferredsession.ts。这正是审计文档session 状态机和 workspace metadata 可复制的工程化延续。5. Turn controlretry / branch / regenerate / checkpoint现状问题Maka 当时有 turn grouping但没有 turn-level controlsretry/regenerate 没有 contractbranch-from-turn 没有 lineagecancel/abort 只是一条 system note不是 turn statustool 执行前没有 checkpoint/snapshotdestructive 修改后无法 rollback旧输出不可覆盖原则没有被模型化。审计强调分支/重试必须从第一天就有 sidecar anchor 和 lineage不要先做 UI 按钮。Contract / APIexport interface TurnRecord { id: string; sessionId: string; parentTurnId?: string; branchId?: string; status: running | completed | aborted | errored | superseded; startedAt: number; completedAt?: number; modelId?: string; snapshotIdBeforeTools?: string; errorReason?: string; }IPCturns:retry(sessionId, turnId)、turns:branch(sessionId, turnId)、turns:cancel(sessionId, turnId)、turns:createCheckpoint(sessionId, turnId)。失败原因turn_not_found、turn_already_running、branch_cutoff_invalid、checkpoint_failed、retry_requires_model。当前仓库中的落地证据会话修订revision与分支体系已在 packages/core/src/session-revisions.ts 中成型SessionConversationCopy以kind: branch | revision区分分支会话与修订副本并记录sourceSessionIdsession.ts普通分支会话不设revisionRootSessionId保持彼此独立session-revisions.ts。测试方面packages/core/src/tests/session-revisions.test.ts 与 packages/core/src/tests/session-status.test.ts 覆盖了审计文档 Gate 要求的 branch copies messages up to turn boundary only 与 status transitions 两类关键不变量。6. Health Center把分散状态收拢成一页现状问题当时健康状态分散在provider credentialAccount/Models、proxyNetwork、botBot Chat、model fetch sourceModelTablestorage / visual smoke / console gate 不在 UImissing connection 只在 chat header。用户出错时不知道是 key、网络、proxy、provider、bot、model list 还是 workspace 权限的问题bug report 不能一键 copy redacted diagnosticsrelease smoke 没有综合状态页。Contract / APIexport type HealthComponent | provider | credential | model_catalog | proxy | bot | storage | skills | search | voice | open_gateway; export interface HealthCheckResult { component: HealthComponent; id: string; label: string; status: ok | warning | error | disabled | unknown; reason?: string; message: string; lastCheckedAt?: number; details?: Recordstring, unknown; // redacted only }IPChealth:list()、health:run(component?, id?)、health:copyDiagnostics()。Diagnostics 必须包含app version / OS / workspace schemaprovider statuseswithout secretslatest generalized errorsproxy enabled/type不含凭据storage file presence / JSON parse status除非用户显式复制 workspace 路径否则不输出原始路径。失败原因复用 readiness/connection/proxy 词汇auth、timeout、network、provider_unavailable、connection_missing、storage_corrupt、unsupported。当前仓库中的落地证据packages/core/src/health.ts 将健康信号建模为HealthSignalStatus [ok,info,warning,error,unknown]、HealthSignalLayerconfiguration / validation / permission / feature / action_approval / memory_acceptance / runtime_probe / storage、HealthSignalScopellm_connection / bot / capability与HealthSignalSourceconnection_test / capability_snapshot / permission_snapshot / runtime_probe / settings并预置connection_disabled、awaiting_default_model、needs_reauth、no_models_enabled等消息码。相比审计文档的HealthComponent列表这套分层模型把组件升级为信号 × 层级 × 来源的多维结构同时保留了redactSecrets这一贯穿全仓的脱敏机制详见下文 Memory 与 redaction 工具。7. Sources / Skills / Automations让外部能力可见、可审计、可撤销现状问题Maka 当时只从workspaceRoot/skills列出已安装 skills没有一等 citizen 的 source没有 source-scoped permissions没有 automations。具体缺口skill visibility 不等于 invocability/permissions没有 source auth/scope/status没有 automation last-run/history用户无法审计哪个 capability 能碰什么。Contract / APIexport interface SourceRecord { slug: string; name: string; type: mcp | api | local; enabled: boolean; authType: oauth | bearer | none; scopeSummary: string[]; status: ready | needs_auth | error | disabled; lastTestAt?: number; lastErrorReason?: string; } export interface AutomationRecord { id: string; name: string; enabled: boolean; trigger: manual | schedule | event; permissionMode: explore | ask | execute; lastRunAt?: number; lastRunStatus?: ok | error | skipped; }失败原因source_needs_auth、source_scope_denied、automation_disabled、automation_last_run_failed、skill_missing_source。审计给出的首要最小步skill 不能自行扩大 permission modeSettings 面必须能显示 source/skill/automation 的 enabled/disabled/test 状态。这一外部能力可见且可撤销的模型在 packages/core/src/capabilities.tsCapabilityId / CapabilityReadinessState / CapabilitySnapshot与 packages/core/src/runtime-policy.ts含 runtime-policy/model-catalog-entry-codec.ts中已有对应的 capability 与权限投影支撑测试见 packages/core/src/tests/goal-authority.test.ts 与 packages/core/src/tests/runtime-policy-codec.test.ts。8. First-run to value把 7 步碎流程收成状态机现状问题OnboardingHero 存在、provider save auto-fetch 可用但流程仍是碎片化的 7 步provider preset → paste key → save → auto-fetch → choose default → back to chat → send prompt。没有显式的 you are ready smoke prompt没有 inline model fetch failure lane没有 first-run state machine。审计强调可复制的是 first-run guided state而不是 cinematic onboarding。Contract / APIexport type FirstRunStep | choose_provider | enter_secret | fetch_models | choose_default | send_smoke_prompt | done; export interface FirstRunState { current: FirstRunStep; providerSlug?: string; errorReason?: string; completedAt?: number; }失败原因secret_invalid、model_fetch_failed、no_chat_models、default_model_missing、smoke_prompt_failed。Gate 目标很具体从 provider pick 到第一次成功回答最多 4 屏fixture 覆盖first-run、first-run-auth-error、first-run-fetched-emptynode:test 覆盖 step transition reducer。仓库中的 onboarding 状态机见 packages/core/src/onboarding.ts含 onboarding milestone 相关契约其配套的模型可不可用作 chat default判定即可复用第 3 节的canUseAsChatDefault这也是文档要求 first-run 能解释模型存在但不能用于当前 chat的答案来源。9. Memory MVP先做用户可见的 CRUD再谈 embedding现状问题Maka 当时只有 personalization prompt没有 memory object没有 persistent facts、没有 retrieval、没有 memory source visibility、没有 user review/delete、没有 sleep/consolidation。审计明确警告不要直接跳到 sqlite-vec ONNX——第一个缺口是用户可见的 memory CRUD 与 retrieval contract。Contract / APIexport interface MemoryRecord { id: string; content: string; source: user_pinned | assistant_suggested | imported; durability: temporary | permanent; createdAt: number; updatedAt: number; archivedAt?: number; }第一个 PR 不做 embeddings用keyword search 显式 user pin/delete。失败原因memory_search_failed、memory_disabled、memory_import_invalid。Gatenode:test 覆盖 CRUD/search/archivefixture 用 3 条 memory 1 条 archivedsmoke 验证 Settings/Memory 页可增删查、chat 可引用检索到的 memory source。当前仓库中的落地证据当前仓库的 packages/core/src/local-memory.ts 恰如其分地体现了透明本地 MEMORY.md contract的 V0.1文档注释明确写着does not implement hidden durable memory, extraction, embeddings, recall, or agent toolslocal-memory.ts。它提供LocalMemorySettingsenabled/agentReadEnabled、LocalMemoryOriginmanual / extracted / imported / unknown、LocalMemoryEntryStatusdraft / review_required / active / archived / rejected / unknown、LocalMemoryScopeworkspace / session与LocalMemorySourceuser_authored / chat_extracted / unknown——这与审计文档的MemoryRecord完全同构且把source拆成 origin/status/scope 三个维度便于渐进演进。测试见 packages/core/src/tests/local-memory.test.ts 与 packages/core/src/tests/long-term-memory.test.ts。10. Open Gateway / Voice / SearchComing Soon 面板的兑现顺序现状问题Settings 当时已有 search / voice / open gateway 三个 Coming Soon 面板文案更好但能力缺席——形成 expectation debt。审计给出的推荐顺序Open Gateway SSE bridge——最容易被本地 contract 化与测试Search service——可从 provider abstraction disabled health state 起步Voice input——需要 macOS 权限与音频设备 UX除非用户优先否则后置。Open Gateway contract审计文档定义仅在显式启用时暴露本地 OpenAI 兼容端点默认绑定127.0.0.1per-workspace token 本地生成日志中不出现明文 secret/v1/models只返回 chat-capable 的ModelCatalogEntry/v1/chat/completions路由到所选 connection默认 connection 不可用时给出 health reason。失败原因gateway_disabled、gateway_token_invalid、gateway_model_unsupported、gateway_connection_unavailable。Gatenode:test 覆盖 token auth disabled pathfixture 覆盖 gateway enabled/unavailablesmoke 用 curl 打本地端点验证。这与第 3 节的ModelCatalogEntry.canUseAsChatDefault形成直接配合——/v1/models只需过滤出 chat-capable 条目即可安全暴露。11. 推荐 PR 顺序四个 Wave 的取舍逻辑审计文档给出了明确的落地排序并解释了每个 Wave 为什么排在那里Wave A: Workbench foundation工作台地基ArtifactRecordcore/storage contract fixture seed暂不做 UI paneRight artifact pane renderer smoke pathTool streaming delta for Bash terminal artifact ref。Why first: 这一步把 Maka 从 chat transcript 变成 work product workspace。Wave B: Decision quality决策质量ModelCatalogEntry chat default gateHealth Center core result type provider/proxy/bot/storage checksFirst-run state reducer first-run fixture expansion。Why second: 用户对 setup 与 provider/model 信任变得可理解。Wave C: Workflow control工作流控制Session status state machineTurnRecord cancel/abort persistence cleanupBranch/regenerate/checkpoint API。Why third: 这些侵入性更强应构建在 artifact/snapshot 形态之上。Wave D: Ecosystem生态Sources/Skills/Automations recordsMemory MVPOpen GatewaySearch / Voice。12. Do-not-copy 清单从参考实现中只学结构不抄捷径审计明确列出从参考实现中不应照搬进 Maka 的模式wide-open local HTTP API无显式 enable/token通过 IPC/API 返回明文 secretauto-approval 或 subagent--approve-all式信任捷径默认开启的 activity/screen recorder延迟首次价值的 cinematic onboarding隐藏的 skill permission widening对 chat ID、API responses、provider bodies 打原始 console 日志。Maka should copy structure and state models, not unsafe shortcuts.这条清单与当前仓库的工程实践高度一致从第 1 节可见ArtifactRecord.relativePath被显式禁止暴露为文件系统路径第 6 节 diagnostics 强制脱敏redactSecrets贯穿 packages/core/src/redaction.ts 及 local-memory 等模块第 9 节 Memory V0.1 明确不做隐藏的长期记忆。13. 立即行动PR-A1 的最小可测试切面审计给出的下一个实现 PR 是PR-A1:ArtifactRecordcore/storage/fixture contract only交付物packages/core/src/artifacts.tscore contractpackages/storage/src/artifact-store.ts存储实现apps/desktop/src/main/visual-smoke-fixture.ts增加artifact-panefixturenode:test 覆盖 append/list/get/soft-delete/file-backed 不变量docs 更新 design-system §9.1 细化暂不做 renderer pane这让第一步保持小、可测试并直接为右栏成果面板解锁。对照当前仓库packages/core/src/artifacts.ts、packages/storage/src/artifact-store.ts、apps/desktop/src/renderer/features/workbar/tools/artifacts/artifact-pane.tsx均已存在说明这条审计路线在其后的迭代中被实际执行——本文档作为 2026-05 基线的时点快照其最大价值在于13 项契约定义 失败原因词汇表 Wave A–D 的依赖排序 Do-not-copy 安全红线任何想把 Maka或同类 Agent 工作台从聊天记录仓库升级为工作成果工作台的实现者都可以直接以此作为验收清单。【免费下载链接】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），仅供参考