如何看懂 Maka 会话任务账本AI Agent 任务生命周期与持久化合同完全剖析【免费下载链接】makaApache Maka (Incubating) is a local-first AI agent workspace. Model messages, tool calls, tool results, permission decisions, and termination events are recorded as an append-only log.项目地址: https://gitcode.com/GitHub_Trending/mak/makaMakaApache Maka, Incubating是一个本地优先的 AI Agent 工作区它的**会话任务账本Session Task Ledger**为每个交互会话维护一份可恢复的工作记录Agent 创建的任务、状态流转、阻塞原因、完成证据全部以追加日志形式落盘。这篇文章带你完全看懂它的生命周期与持久化合同无需阅读源码也能理解设计思路。为什么 Agent 需要任务账本大模型每轮对话都有上下文窗口限制长任务执行到一半就可能忘记自己还欠哪些事。Maka 的解法很朴素把模型可见的工作项记录成一本账本每个回合把当前账本重新注入提示词尾部让 Agent 始终知道我在干什么、卡在哪里、完成了什么 关键边界来自官方合同文档 session-task-ledger-lifecycle.md账本不是工作流引擎没有定时调度、依赖图或拖拽 UI任务状态只是建议性控制状态不能推翻文件系统、git、测试等真实证据与 AgentRun、RuntimeEvent、Eval 实验台账互相独立。任务的身份证UUID 短键每个任务同时持有两个标识标识形态用途id持久 UUID永不改写存储主键、跨回合引用key会话内短键如T1、T1.1提示词、工具、UI 展示短键按父键 点号层级分配T1的子任务必须是T1.1不允许跳过层级直接出现T1.1.1否则投影会失效并失败关闭fail closed。这套规则定义在 task-ledger.ts 中工具入参和读取路径都同时接受 UUID 或短键两种形式。六大状态任务生命周期状态机账本支持 6 种状态与一组受控的迁移路径状态机实现见 canTransitionTaskStatuspending ──→ in_progress ──→ completed ✅ │ │ │ │ │ └──→ blocked ⇄ in_progress └──→ cancelled │ ├────→ failed ──→ pending重试 └────→ cancelled completed / cancelled ──→ 重新打开必须显式传 explicitReopen: true规则要点子任务未终结时父任务不能被标记为completed终结状态下不能再建子任务completed只能显式重开回in_progresscancelled只能重开回pending非法跳变如pending直接到completed会被拒绝并附带恢复提示。证据合同没有证据不能完成状态迁移不是随便声明的进入特定状态必须携带紧凑文本证据校验逻辑见 validateTaskEvidence进入blocked→ 必填blockedReason为什么卡住进入failed→ 必填failureReason失败原因进入completed→ 必填completionEvidence完成证据每条证据最长 1000 字符任务标题最长 200 字符。这意味着模型必须拿证据说话账本里不会出现一笔没有依据的已完成。持久化合同追加日志 事件重放账本的持久化遵循 Maka Log is the Runtime 的整体哲学只追加、不修改每次变更创建、启动、阻塞、完成……都写入一条账本事件SQLite 表workflow_task_ledger_events只增不减存储实现见 task-ledger-store.ts事件重放得到投影任何时刻的任务列表都是从事件流重放投影出来的而不是直接维护一份可改的状态兼容回填旧版本缺key、endedAt的快照依然可读投影时按创建顺序补出稳定短键并在下次变更时把补出的字段固化下来UUID 保持不变。事件类型共 12 种task_created、task_started、task_blocked、task_reopened等完整清单见 TASK_LEDGER_EVENT_TYPES。断点续跑resumeTrust 信任分级会话被中断后重启账本里的任务还能信吗Maka 内置了一个保守的恢复信任分类器classifyTaskResumeTrust级别含义trusted持久证据完整可直接信任needs_revalidation状态可能仍正确但需重新核对外部事实stale中断时任务正处于in_progressrepaired恢复逻辑已修正过投影untrusted账本损坏、引用缺失模型可见视图直接排除注意resumeTrust是系统诊断字段不会注入给模型只出现在调试、导出与桌面端只读面板中——避免模型被元信息干扰。模型视角4 个工具 回合尾部注入模型操作账本只需 4 个本地工具实现在 task-ledger-tools.ts工具作用task_create批量创建任务可带parent_id建层级task_update更新状态/标题/证据task_list按status、include_terminal等过滤查询task_get按 UUID 或短键取单个任务这 4 个工具只读写本地会话状态不派发任何实际工作。每回合还会把账本渲染成回合尾部再注入一次预算上限 8000 字符约 2000 tokens优先展示in_progresspendingblocked分支并保留其祖先链预算允许时追加最近 3 条终结任务被省略的任务会给出数量提示引导模型用task_list自查渲染前统一做密钥脱敏与标签剥离防止模型写出的标题夹带假字段或 secret安全渲染见 renderSafeTaskLedgerText。子 Agent 领任务所有权与结算当主 Agent 用agent_spawn(task_id...)派子 Agent 干活时账本记录了完整的所有权生命周期运行时真正分配子回合后任务才被认领为in_progress并写入child_agent属主子 Agent成功 ≠ 任务完成——父 Agent 必须亲自核验结果并补充completionEvidence子 Agent 失败或取消会如实记录任务结果等待权限时任务保持blocked已被其他子回合占用的活跃任务不可被抢占防竞态。归档与 Goal 门禁账本不会无限膨胀7 天归档终结任务打上endedAt后 7 天逻辑归档——存储仍追加保留、永不删除但提示词与 UI 默认不再展示显式工具查询可找回Goal 门禁自主 Goal 运行时若评估器认为目标未达成且仍有pending/in_progress任务续跑文本会附带一条任务提醒每次注入决策都记录为task_gate_decided事件全程可审计单一写权威Runtime Host 是生产环境下唯一的交互式账本写者桌面端和 CLI 只消费同一份只读投影避免多份权威。代码地图从哪开始读想了解看这里完整生命周期与持久化合同权威文档docs/session-task-ledger-lifecycle.md核心契约状态机、校验、投影、渲染packages/core/src/task-ledger.ts模型侧 4 个工具的定义packages/runtime/src/task-ledger-tools.tsSQLite 持久化实现packages/storage/src/task-ledger-store.ts行为契约测试packages/core/src/tests/task-ledger.test.ts小结Maka 的会话任务账本用一份追加事件日志 严格状态机 证据合同 信任分级解决了 AI Agent 长任务中失忆、谎报进度、断点不可信三大痛点。它刻意保持克制不碰工作流引擎、不替代真实执行证据把任务状态严格限定为可恢复、可审计的会话级投影——这正是本地优先 Agent 工作区值得借鉴的设计范式 【免费下载链接】makaApache Maka (Incubating) is a local-first AI agent workspace. Model messages, tool calls, tool results, permission decisions, and termination events are recorded as an append-only log.项目地址: https://gitcode.com/GitHub_Trending/mak/maka创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
如何看懂 Maka 会话任务账本：AI Agent 任务生命周期与持久化合同完全剖析
如何看懂 Maka 会话任务账本AI Agent 任务生命周期与持久化合同完全剖析【免费下载链接】makaApache Maka (Incubating) is a local-first AI agent workspace. Model messages, tool calls, tool results, permission decisions, and termination events are recorded as an append-only log.项目地址: https://gitcode.com/GitHub_Trending/mak/makaMakaApache Maka, Incubating是一个本地优先的 AI Agent 工作区它的**会话任务账本Session Task Ledger**为每个交互会话维护一份可恢复的工作记录Agent 创建的任务、状态流转、阻塞原因、完成证据全部以追加日志形式落盘。这篇文章带你完全看懂它的生命周期与持久化合同无需阅读源码也能理解设计思路。为什么 Agent 需要任务账本大模型每轮对话都有上下文窗口限制长任务执行到一半就可能忘记自己还欠哪些事。Maka 的解法很朴素把模型可见的工作项记录成一本账本每个回合把当前账本重新注入提示词尾部让 Agent 始终知道我在干什么、卡在哪里、完成了什么 关键边界来自官方合同文档 session-task-ledger-lifecycle.md账本不是工作流引擎没有定时调度、依赖图或拖拽 UI任务状态只是建议性控制状态不能推翻文件系统、git、测试等真实证据与 AgentRun、RuntimeEvent、Eval 实验台账互相独立。任务的身份证UUID 短键每个任务同时持有两个标识标识形态用途id持久 UUID永不改写存储主键、跨回合引用key会话内短键如T1、T1.1提示词、工具、UI 展示短键按父键 点号层级分配T1的子任务必须是T1.1不允许跳过层级直接出现T1.1.1否则投影会失效并失败关闭fail closed。这套规则定义在 task-ledger.ts 中工具入参和读取路径都同时接受 UUID 或短键两种形式。六大状态任务生命周期状态机账本支持 6 种状态与一组受控的迁移路径状态机实现见 canTransitionTaskStatuspending ──→ in_progress ──→ completed ✅ │ │ │ │ │ └──→ blocked ⇄ in_progress └──→ cancelled │ ├────→ failed ──→ pending重试 └────→ cancelled completed / cancelled ──→ 重新打开必须显式传 explicitReopen: true规则要点子任务未终结时父任务不能被标记为completed终结状态下不能再建子任务completed只能显式重开回in_progresscancelled只能重开回pending非法跳变如pending直接到completed会被拒绝并附带恢复提示。证据合同没有证据不能完成状态迁移不是随便声明的进入特定状态必须携带紧凑文本证据校验逻辑见 validateTaskEvidence进入blocked→ 必填blockedReason为什么卡住进入failed→ 必填failureReason失败原因进入completed→ 必填completionEvidence完成证据每条证据最长 1000 字符任务标题最长 200 字符。这意味着模型必须拿证据说话账本里不会出现一笔没有依据的已完成。持久化合同追加日志 事件重放账本的持久化遵循 Maka Log is the Runtime 的整体哲学只追加、不修改每次变更创建、启动、阻塞、完成……都写入一条账本事件SQLite 表workflow_task_ledger_events只增不减存储实现见 task-ledger-store.ts事件重放得到投影任何时刻的任务列表都是从事件流重放投影出来的而不是直接维护一份可改的状态兼容回填旧版本缺key、endedAt的快照依然可读投影时按创建顺序补出稳定短键并在下次变更时把补出的字段固化下来UUID 保持不变。事件类型共 12 种task_created、task_started、task_blocked、task_reopened等完整清单见 TASK_LEDGER_EVENT_TYPES。断点续跑resumeTrust 信任分级会话被中断后重启账本里的任务还能信吗Maka 内置了一个保守的恢复信任分类器classifyTaskResumeTrust级别含义trusted持久证据完整可直接信任needs_revalidation状态可能仍正确但需重新核对外部事实stale中断时任务正处于in_progressrepaired恢复逻辑已修正过投影untrusted账本损坏、引用缺失模型可见视图直接排除注意resumeTrust是系统诊断字段不会注入给模型只出现在调试、导出与桌面端只读面板中——避免模型被元信息干扰。模型视角4 个工具 回合尾部注入模型操作账本只需 4 个本地工具实现在 task-ledger-tools.ts工具作用task_create批量创建任务可带parent_id建层级task_update更新状态/标题/证据task_list按status、include_terminal等过滤查询task_get按 UUID 或短键取单个任务这 4 个工具只读写本地会话状态不派发任何实际工作。每回合还会把账本渲染成回合尾部再注入一次预算上限 8000 字符约 2000 tokens优先展示in_progresspendingblocked分支并保留其祖先链预算允许时追加最近 3 条终结任务被省略的任务会给出数量提示引导模型用task_list自查渲染前统一做密钥脱敏与标签剥离防止模型写出的标题夹带假字段或 secret安全渲染见 renderSafeTaskLedgerText。子 Agent 领任务所有权与结算当主 Agent 用agent_spawn(task_id...)派子 Agent 干活时账本记录了完整的所有权生命周期运行时真正分配子回合后任务才被认领为in_progress并写入child_agent属主子 Agent成功 ≠ 任务完成——父 Agent 必须亲自核验结果并补充completionEvidence子 Agent 失败或取消会如实记录任务结果等待权限时任务保持blocked已被其他子回合占用的活跃任务不可被抢占防竞态。归档与 Goal 门禁账本不会无限膨胀7 天归档终结任务打上endedAt后 7 天逻辑归档——存储仍追加保留、永不删除但提示词与 UI 默认不再展示显式工具查询可找回Goal 门禁自主 Goal 运行时若评估器认为目标未达成且仍有pending/in_progress任务续跑文本会附带一条任务提醒每次注入决策都记录为task_gate_decided事件全程可审计单一写权威Runtime Host 是生产环境下唯一的交互式账本写者桌面端和 CLI 只消费同一份只读投影避免多份权威。代码地图从哪开始读想了解看这里完整生命周期与持久化合同权威文档docs/session-task-ledger-lifecycle.md核心契约状态机、校验、投影、渲染packages/core/src/task-ledger.ts模型侧 4 个工具的定义packages/runtime/src/task-ledger-tools.tsSQLite 持久化实现packages/storage/src/task-ledger-store.ts行为契约测试packages/core/src/tests/task-ledger.test.ts小结Maka 的会话任务账本用一份追加事件日志 严格状态机 证据合同 信任分级解决了 AI Agent 长任务中失忆、谎报进度、断点不可信三大痛点。它刻意保持克制不碰工作流引擎、不替代真实执行证据把任务状态严格限定为可恢复、可审计的会话级投影——这正是本地优先 Agent 工作区值得借鉴的设计范式 【免费下载链接】makaApache Maka (Incubating) is a local-first AI agent workspace. Model messages, tool calls, tool results, permission decisions, and termination events are recorded as an append-only log.项目地址: https://gitcode.com/GitHub_Trending/mak/maka创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
![[光学原理与应用-521]：对光的错误理解与纠偏](http://pic.xiahunao.cn/yaotu/[光学原理与应用-521]：对光的错误理解与纠偏)
