Rouen / Godspeed

主题

近期学习计划 ​

这里记录正在进行和排队中的技术学习主题：学什么、为什么学、按什么步骤学、当前进度以及硬性验收标准。

写下来的目的不是立 flag，而是逼自己把「随便翻翻源码」变成有验收标准的事情。每个主题都要求能回答一组具体问题、产出可验证的工程代码或架构方案，答不上、做不出就是没学完。

进行中 ​

1. 开源 AI Agent 架构：openhanako / HanaAgent ​

  • 是什么 — 一个基于 Electron + 独立 Node 服务的本地 AI Agent 桌面应用，内置持久化记忆、人格设定、多 Agent 协作、插件系统、跨平台权限沙盒和多聊天平台接入。规模约 9,000 文件，核心层 5 万余行。
  • 为什么学 — 它是少数把「Agent 产品化落地」做到相对完整的开源实现：不只是简单套壳调用 LLM，而是完整处理了记忆动态压缩、进程权限沙盒、扩展生态协议、多端会话一致性等真实工程挑战。同时其架构演进痕迹明显，是研究「产品业务面跑得比内核抽象快」的最佳解剖样本。
  • 学习步骤与落地 — 详见 openhanako 架构学习：规划与步骤
  • 核心验收问题：
    1. 为什么其持久化层会出现多处数据结构竞态？如何通过引入 Durable Run 账本解决？
    2. 其系统提示词是如何按缓存分界线（Prompt Caching Boundary）排序以降低 API 延迟和成本的？
    3. 外部 SDK 适配层在发生 Breaking Change 时，如何做到上层 Agent 业务零感知？
  • 当前状态 — 四层架构通读已完成，已输出一份完整架构导读和两份架构改进提案。当前正在执行提案 01 第一阶段：统一会话账本的类型定义与历史数据回填校验。

2. 生产级 Agent Skill 架构与 MCP 协议扩展实践 ​

  • 是什么 — 研究并实践基于 Markdown 规范的标准 Agent Skill（如 Antigravity / Codex / Claude Code 体系）与 MCP (Model Context Protocol) 工具协议的设计、分发、隔离执行与自动化图文蒸馏。
  • 为什么学 — 单纯依靠 System Prompt 无法承载复杂领域的专业知识与长链路操作。通过设计高内聚、带环境降级和单真相源（SSOT）规则体系的 Skill，可以让通用 Agent 进化为特定领域的高级专家（如交易模型蒸馏、代码审查、数据管道运维）。
  • 学习与实践步骤：
    1. 规则与上下文解耦：确立长期规则唯一真相源（如 operation-guide.md）与每日增量（日更记录）的分层写入纪律；
    2. 自动化蒸馏管道：实现从外部数据源（如 Discord/REST API）采集、多模态图文对齐、环境沙盒隔离校验到静态站自动部署的闭环流水线；
    3. 模型无关与冷启动优化：编写标准 cold-start.md 与黑话字典，让不同大模型接手时均能快速建立边界认知。
  • 核心验收问题：
    1. Skill 如何在缺少可选外部依赖（如特定 CLI 或图表源）时优雅降级并显式报告置信度，而非产生静默幻觉？
    2. 如何防止单日的特殊案例污染长效规则库？
  • 当前状态 — 已在实盘交易与学习分析领域实现全自动化的 garbage-teacher-operator 蒸馏发布管线，正在将其抽象为通用的 Agent 知识萃取脚手架。

排队中 ​

3. Agent 运行时内核与 Durable Execution 对比研究 ​

  • 为什么学 — 同一个问题——「一轮 Agent 执行是什么」——不同项目给出的底层模型差别巨大。单体循环协调器在遇到长耗时任务或崩溃时极易状态丢失；事件溯源虽然完整但查询与回放负担沉重；而基于 Temporal / Durable State 的状态机则兼顾了断点续跑与幂等性。
  • 计划步骤：
    1. 横向对比 3 种主流开源 Agent 内核的调度模型（Loop 调度、Actor 模型、状态机账本）；
    2. 针对「执行超时」、「多 Agent 并发消息乱序」、「工具调用中断」三种典型故障，设计最小复现用例与恢复评测；
    3. 产出一份横向对比报告与一套轻量级的 Durable Run 状态机原型。
  • 验收标准：能在进程随时被 kill -9 强杀的情况下，重启后自动恢复到最近一步已确认工具调用的上下文，无重复执行、无状态损坏。

4. 上下文预算控制与分层记忆压缩机制 ​

  • 为什么学 — 随着多轮对话和长工具输出不断累积，Context Window 预算极易超载，导致模型注意力稀释与 Token 成本飙升。传统的直接截断（Truncation）会丢失前序决策关键因果，暴力摘要又容易丢失精细数据。
  • 计划步骤：
    1. 梳理短时上下文（Working Memory）、会话摘要（Compacted Summary）、语义向量库（RAG Retrieval）与持久化规则（Skill Rules）的四层分级流转策略；
    2. 测试不同压缩粒度（逐轮微摘要、任务完成阶段快照、关键状态变量提取）对模型后续推理成功率的影响；
    3. 实现一套带 Token 预算水位线（Watermark）感知的自动记忆收割与 Compact 机制。
  • 验收标准：在长达 100 轮交互、累计消耗超 500k Token 的复杂重构任务中，核心约束与架构决策不发生遗忘，且单轮平均 Context 维持在安全预算线内。

5. 跨平台进程沙盒与安全权限体系 ​

  • 为什么学 — 给予 Agent 运行 Shell 和执行代码的能力后，安全边界与权限控制成为最大的系统风险。macOS（Seatbelt/App Sandbox）、Linux（Bubblewrap/Namespaces）与 Windows（Restricted Tokens/AppContainer）在内核级隔离能力和开发者体验上存在巨大代沟。
  • 计划步骤：
    1. 梳理 macOS sandbox-exec 与 Linux bwrap 的最小隔离配置模板（文件只读挂载、临时写入区隔离、网络白名单）；
    2. 分析 Windows 平台多数 Agent 项目放弃强沙盒而退化为「提示词请求确认」的底层原因与替代方案；
    3. 搭建统一的 CLI 执行封装层，提供统一的权限升级（Escalation）交互协议。
  • 验收标准：能够拦截一切尝试越权读取用户主目录敏感文件（如 SSH 私钥、未授权环境配置）的任意脚本，并返回结构化的错误诊断与提权申请。

方法论：怎么读一个陌生的大项目 ​

几次实践下来固定成这套流程：

  1. 先看数据不看代码。 找到它的数据目录，看文件怎么组织。数据布局比任何架构图都诚实——目录结构就是设计决策的化石。
  2. 按「一次请求的生命周期」读，不按目录顺序读。 目录是按模块分的，理解是按数据流走的，两者不一致。
  3. 每层读完写验收问题。 不是写笔记，是写「读懂了应该能回答什么」，然后自己答。答不上就是没读懂，回去重读。
  4. 找作者自己标注的接缝。 代码里的 legacy_* 常量、TODO、「过渡态」注释，都是作者知道没做完的地方。在这些地方做改进，比重构人家写好的东西正当得多。
  5. 注释密度最高的地方就是设计精华。 作者花力气解释的，一定是他觉得不解释就会被改坏的。这些地方值得逐字读。
  6. 同时找一个对照项目。 单看一个项目分不清「这是设计」还是「这就是唯一做法」。有对照才知道哪些决策是真的做了选择。