我的项目进化日志 · Project Evolution Log

§0 你一定经历过这个场景

> 你打开一个六个月没碰的项目。
>
> 你看到一段奇怪的代码，一个诡异的架构选择，一个你完全不记得为什么存在的模块。
>
> 你问：「当时为什么要这样做？」
>
> 没人能回答你。当时的你也没有，现在的你也不知道。Git log 告诉你「重构模块」——但没说为什么重构。PR 描述写着「优化性能」——但没写具体优化了什么、放弃了什么。
>
> 项目的进化史消失了。只剩下代码的化石层，没有故事的沉积岩。

项目进化日志做一件事：在项目推进的每个关键时刻，顺手记录"为什么"。决策、踩坑、架构变更、灵感来源——一条一条刻进项目的进化年轮里。你随时可以翻回去，看这个项目从哪来、到哪去、每个转折点发生了什么。

它不是 git log（记录代码变化），而是项目叙事（记录决策背后的故事）。

§1 六种进化事件类型

§2 进化事件标准格式

每条进化事件包含以下字段：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  进化事件 #EV-0032

  时间      2026-07-13 14:22
  类型      E1 决策记录
  标题      放弃 WebSocket，改用 SSE
  标签      #后端 #实时通信 #架构

  背景
  我们需要给仪表盘加实时数据推送。最初设计了
  WebSocket 双向通道。

  决策
  放弃 WebSocket，改用 Server-Sent Events (SSE)。

  理由
  1. 仪表盘只需要服务端→客户端单向推送，不需要
     客户端回传
  2. SSE 基于 HTTP，不需要额外协议升级，CDN 和
     代理兼容性更好
  3. 自动重连是 SSE 原生能力，不用自己写
  4. 我们的 Nginx 配置已经支持 SSE 长连接

  放弃的选项
  • WebSocket：双向能力用不上，徒增复杂度
  • 轮询：延迟太高，不适合仪表盘

  影响范围
  后端：推送层从 ws:// 改为 HTTP + text/event-stream
  前端：EventSource API 替代 WebSocket 客户端
  预计节省开发时间约 3 天

  相关事件
  EV-0028（仪表盘需求评审）
  EV-0030（前端实时方案调研）

  记录者  李工
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

2.1 六种类型的完整填写示例

以下示例覆盖全部六种事件类型，每条展示标准填法。对于日常快速记录，允许简化为"一句话条目"（见 §R 第 2 条）。

E1 决策记录

E1 决策记录 · 数据库索引策略从联合索引改为覆盖索引

背景：用户列表页的 SQL 用了联合索引 (status, created_at)，
      但查询还需要取 username 和 avatar_url，每次都要回表。

决策：改为覆盖索引 (status, created_at, username, avatar_url)。

理由：这三个字段是列表页的固定查询列，覆盖索引可以完全
      消除回表。代价是索引体积增加约 40%，但查询量远大于
      写入量，值得换。

放弃的选项：
• 缓存查询结果：缓存失效时机难以精确控制，用户对实时性有要求
• 拆成两次查询（先查 id 再批量取详情）：增加网络往返，效果有限

影响：列表页 P99 从 320ms 降到 45ms。索引额外占用约 200MB。

E2 架构变更

E2 架构变更 · 将支付模块从单体中拆分为独立服务

背景：支付模块每次部署都要跟随主应用一起重启，导致正在处理
      中的支付回调中断。而且支付相关的数据库表（订单、退款、
      对账）与主业务表耦合在同一库中，互相拖慢。

决策：拆分支付服务（payment-service），独立部署、独立数据库。

迁移路径：
1. 先在单体中给支付相关表加双写逻辑（同时写旧表和新库）
2. 跑数据校验脚本，确认双写一致性 > 99.99%
3. 逐步将支付接口流量切换到新服务（按 5%→30%→100%灰度）
4. 稳定运行 2 周后删除旧表

影响范围：
• 新增 payment-service 仓库和服务
• 主应用减少约 12000 行支付相关代码
• 支付回调中断率从 1.2% 降到 0%

E3 技术选型

E3 技术选型 · 日志系统从 ELK 迁移到 Loki

背景：ELK 运维成本越来越高——ES 集群需要 3 台 32GB 机器，
     每月存储成本约 6000 元，且我们实际上只做日志检索，
     几乎不用 Kibana 的可视化和 ES 的全文分析能力。

对比：
| 方案 | 存储成本/月 | 运维复杂度 | 检索能力 | 迁移成本 |
| Loki | ~1500元     | 低         | 日志检索 | 2天      |
| ELK  | ~6000元     | 高         | 全文分析 | 当前方案 |

决策：选择 Loki（配合 Promtail + Grafana）。

理由：
1. 我们只用日志检索，Loki 的 LogQL 完全够用
2. 存储成本降低 75%（Loki 只索引标签，不索引全文）
3. 与现有 Grafana + Prometheus 监控栈天然集成
4. 运维从"维护 ES 集群"降为"加一行配置"

放弃的选项：
• 继续用 ELK 但降配：降配后查询速度不可接受
• 切到腾讯云 CLS：功能更强但锁定云平台，迁移成本太高

E4 踩坑记录

E4 踩坑记录 · Redis 大 key 导致主从同步延迟 3 秒

现象：
2026-07-12 下午 3 点线上出现间歇性数据不一致——用户在 A 页面
看到的订单状态与 B 页面不同。持续约 2 小时。

排查过程：
1. 查 API 日志：两个页面调的不是同一个 Redis 节点
2. 查 Redis 监控：主从同步延迟 3 秒（正常 < 50ms）
3. 查慢日志：一条 HGETALL 命令耗时 2.8 秒
4. 定位：user:session:12345 这个 key 存了所有登录设备信息，
   大小 8.7MB——是一个失控的大 key

根因：
半年前设计的"记录所有登录设备"功能，没有设置设备数量上限。
活跃用户积累了 300+ 设备记录，每次登录都 HGETALL + HINCRBY。

修复：
1. 紧急拆分：将大 key 拆为 user:session:12345:device:{id} 粒度
2. 加 TTL：每个设备记录 30 天过期
3. 加上限：每个用户最多保留 50 个设备

避免方案：
• 所有 Redis 集合类型 key 必须设 TTL 或上限
• 监控告警：单个 key 超过 1MB 触发通知
• Code Review 规则：涉及 HGETALL / SMEMBERS 等全量命令时必须
  确认数据量可控

耗时：4 小时排查 + 1 小时修复 + 2 小时制定预防措施

E5 灵感注入

E5 灵感注入 · 从 Linear 的任务关联设计获得启发

来源：
试用 Linear 时发现它的 Issue 关联方式——不是手工输入 Issue ID，
而是在描述里用自然语言提到另一个任务时，Linear 自动识别并建立
双向链接。

启发：
我们的项目管理工具可以做一个"智能关联"——用户在任务描述或
评论里写了「这个跟 #123 相关」「依赖后端 API 那个任务」，系统
自动提取并建议关联。不只是 #编号，而是语义匹配。

初步想法：
1. 对任务描述做实体识别（任务编号 + 关键词匹配）
2. 候选关联按置信度排序，展示在侧栏
3. 用户一键确认或忽略

待验证：
• 误关联率会不会太高导致用户不信任？
• 是否值得投入开发资源？可以先做 MVP（仅匹配 #编号）验证

E6 里程碑

E6 里程碑 · v2.0 正式上线

时间：2026-07-13
版本：v2.0.0

关键数据：
• 日活：从 200 → 1000（达成 Q2 目标）
• 用户反馈好评率：92%（v1.0 时期为 78%）
• 首次加载时间：从 3.2s 降到 1.1s

本版本核心交付：
• 仪表盘实时数据推送（基于 SSE，见 EV-0032）
• Redis 缓存层上线（见 EV-0041）
• 支付模块独立部署（见 EV-0042）

遗留问题：
• 移动端适配未完成（计划 v2.1）
• 部分旧 API 未迁移到新架构（已标记 deprecated）

下一个里程碑目标：
v2.1 目标：移动端适配完成 + 旧 API 下线。

§3 完整走通流程

场景：你和 AI 在讨论项目的缓存方案

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
第 1 步：自然对话中触发了记录点

用户：「我们接口响应太慢了，我想加一层 Redis 缓存。
      你觉得缓存策略用什么好？」

AI：  [分析并给出建议……]

AI：  （检测到这是一个明确的技术决策场景）
      顺便问一下，要把「引入 Redis 缓存层」记录到
      项目进化日志吗？

用户：「记吧。」

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
第 2 步：AI 从对话中提取关键信息，生成事件草稿

AI：  根据我们的讨论，草稿如下——

  ┌─────────────────────────────────────────────┐
  │ E3 技术选型 · 引入 Redis 缓存层             │
  │                                             │
  │ 决策：在 API 层与数据库之间加入 Redis       │
  │       作为读缓存                             │
  │ 策略：Cache-Aside 模式，先查缓存→未命中     │
  │       →查库→回写缓存                         │
  │ TTL：热点数据 5 分钟，普通数据 30 分钟       │
  │ 淘汰：allkeys-lru                           │
  │                                             │
  │ 放弃的选项：                                │
  │ • 本地内存缓存：无法跨实例共享              │
  │ • 直接 CDN 缓存：不适用动态 API 响应        │
  │                                             │
  │ 需要补充或修改吗？                          │
  └─────────────────────────────────────────────┘

用户：「TTL 热点数据改成 3 分钟，其他没问题。」

AI：  已更新 TTL 为 3 分钟。记录已写入。

      📜 进化事件 #EV-0041 已记录：
         E3 技术选型 · 引入 Redis 缓存层
         2026-07-13 14:35 · #后端 #缓存 #性能

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
第 3 步：三个月后，你回来看这个项目

用户：「当时为什么用 Redis 做缓存来着？有没有
      考虑过直接用本地缓存？」

AI：  [搜索进化日志，找到 EV-0041]

      找到了。2026-07-13 记录了这次决策：

      E3 技术选型 · 引入 Redis 缓存层
      决策理由：需要跨实例共享缓存状态，本地内存
      缓存无法满足多实例部署需求。选择了 Cache-
      Aside 模式 + allkeys-lru 淘汰策略。

      当时放弃的选项中就包括「本地内存缓存」——
      原因写得很清楚：「无法跨实例共享」。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
第 4 步：项目回顾

用户：「这半年项目在架构上经历了哪些大变化？」

AI：  这半年的架构变迁：

      2026-03     E2 架构变更 · 单体拆微服务
                  先拆出用户服务和订单服务

      2026-04     E3 技术选型 · 引入 Redis 缓存层
                  API 读性能提升 60%

      2026-05     E2 架构变更 · 消息队列从 RabbitMQ
                  迁移到 Kafka
                  理由：事件溯源架构需要日志持久化

      2026-06     E4 踩坑记录 · Kafka Consumer
                  重复消费问题
                  根因：未正确设置 enable.auto.commit

      2026-07     E3 技术选型 · 放弃 WebSocket
                  改用 SSE
                  节省开发时间 3 天

§4 什么不值得记录（反过滤规则）

不是每个技术动作都值得进入化日志。以下场景不应记录——如果 AI 误触发了询问，直接说"不用"即可。

判断标准：问自己——三个月后回看，这条记录还能帮到我吗？如果答案是"不会"或者"我不确定"，不记。

§5 五种记录触发方式（含精确触发规则）

5.1 对话中自动检测（精确匹配规则）

AI 在对话中监听以下语义模式。只有当用户的表述同时命中"信号词"和"决策感"时，才触发询问。

触发条件 = 信号词 + 决策感（二选一不触发，同时命中才问）

询问次数限制：同一轮对话中，每个事件类型最多触发 1 次询问。用户说"不用"后，该类型本轮不再询问。整轮对话累计询问不超过 3 次——超过 3 次说明对话本身不是决策密集场景，AI 停止所有自动检测。

5.2 自动检测失败时的兜底

如果 AI 检测到了决策场景但无法从对话中提取足够信息：

AI：「检测到你可能在做一个决策（关于 Redis 缓存方案），
    但对话中缺少一些关键信息。你希望我——

    ① 直接记录（我会基于已有对话内容生成草稿，你审核）
    ② 问你几个问题再记录（我会追问决策理由、放弃的选项等）
    ③ 先跳过（你手动说「记录」时我再记）」

不要猜测缺失的信息。三个选项让用户决定投入多少精力。

5.3 主动要求记录

5.4 手动编写事件

直接描述事件，AI 帮你格式化：

用户：「记录：今天把数据库从 MySQL 5.7 升级到 8.0，
      因为 8.0 支持窗口函数，可以把那个 200 行的报表
      SQL 重写成 20 行。」

AI：解析为 E3 技术选型，提取理由和影响，生成标准格式。

5.5 批量导入

用户：「把这份架构评审纪要里所有决策和变动整理成进化事件」

AI：解析文档 → 识别决策点 → 逐条生成事件 → 列出清单让用户确认 → 批量写入

5.6 一句话极简记录

当你说「简单记一句就行」，AI 接受一句话条目：

用户：「记一句：Redis TTL 设了 3 分钟，因为仪表盘数据刷新频率是 2 分钟。」

AI：生成 E3 条目，标题 = 「Redis TTL 设为 3 分钟」，其余字段根据这一句话推断填充（标注"基于单句推断"）。

§5 查询与回溯

进化日志的价值在"回头看"。支持以下查询方式：

§6 项目清单

进化日志支持多项目。首次使用时会让你确认项目信息：

{
  "project": {
    "name": "Marvis Skill Hub",
    "slug": "marvis-skill-hub",
    "description": "AI 助手 Skill 生态平台",
    "start_date": "2026-06-01",
    "status": "active",
    "tech_stack": ["Python", "FastAPI", "PostgreSQL", "Redis"],
    "team_size": 3
  },
  "stats": {
    "total_events": 47,
    "first_event": "2026-06-01",
    "last_event": "2026-07-13",
    "most_active_month": "2026-06",
    "top_event_type": "E1 决策记录"
  }
}

切换项目：「切换到 xxx 项目」。查看当前项目：「当前项目是什么」。

§7 存储机制

进化事件存储在项目目录下的 evolution-log.json：

{
  "project": {
    "name": "Marvis Skill Hub",
    "slug": "marvis-skill-hub"
  },
  "events": [
    {
      "id": "EV-0041",
      "timestamp": "2026-07-13T14:35:00+08:00",
      "type": "E3",
      "type_label": "技术选型",
      "title": "引入 Redis 缓存层",
      "description": "在 API 层与数据库之间加入 Redis 作为读缓存",
      "context": "接口响应时间过长，需要缓存加速",
      "decision": "Cache-Aside 模式，TTL 热点 3 分钟 / 普通 30 分钟",
      "alternatives": ["本地内存缓存（无法跨实例共享）", "CDN 缓存（不适用动态 API）"],
      "impact": "预期读性能提升 60%",
      "tags": ["后端", "缓存", "性能"],
      "related_events": ["EV-0038"],
      "recorded_by": "marvis-assistant"
    }
  ],
  "meta": {
    "last_updated": "2026-07-13T14:35:00+08:00",
    "event_count": 47,
    "version": "1.0.0"
  }
}

§8 进化报告

随时可以生成按周期汇总的报告：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📜 Marvis Skill Hub · Q2 2026 进化报告

  项目状态：活跃开发中
  本季事件：23 条

  事件分布：
  E1 决策记录   ████████████ 12 条
  E2 架构变更   ████ 4 条
  E3 技术选型   ████ 4 条
  E4 踩坑记录   ██ 2 条
  E5 灵感注入   █ 1 条

  本季里程碑
  2026-04-15  ·  v1.0 内部测试版上线
  2026-05-20  ·  首批 6 个 Skill 完成开发
  2026-06-30  ·  Skill Hub 用户数突破 50

  本季最大决策
  EV-0028：确定 Skill 的存储和分发架构（文件系统 + JSON manifest）
  影响：后续所有 Skill 的加载逻辑都基于此架构

  本季最痛的坑
  EV-0035：跨平台路径兼容性问题——Windows 反斜杠导致插件加载失败
  耗时：4 小时排查，2 行代码修复

  展望 Q3
  待决策：Skill 市场是否需要 OAuth 统一认证？
  待优化：EV-0035 暴露的跨平台兼容性需要系统化测试
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

§R 核心铁律

1. 记录"为什么"，不只"做了什么"：git 已经记录了代码变更。进化日志存在的全部价值在于记录 git 记录不了的东西——决策的理由、放弃的选项、当时的上下文。没有"为什么"的记录是废条目。
2. 即时的价值 > 完美的格式：5 秒记一句「Redis 的 TTL 设了 3 分钟，因为仪表盘数据刷新频率是 2 分钟」比三天后花 30 分钟补一篇完美的决策记录有价值十倍。允许一句话条目。
3. 宁缺毋滥：不是每个 commit 都要记。只记"将来回头看会觉得有价值"的事件。如果一条记录在三个月后你读起来会想「这有什么好记的」，那它就不该被记。反过滤规则见 §4。
4. 关联而非孤立：事件之间用 related_events 串联。一个架构变更可能由某个踩坑触发，一个技术选型可能因为某个决策而改变。孤立的条目是死数据，关联形成进化树。
5. 可以更新，不能删除：一条进化事件一旦记录，不应被删除（因为它是历史）。如果当初的决策后来被推翻了，不删旧记录，而是新增一条 E1 决策记录：「推翻 EV-0041：Redis 换成本地缓存，因为后来发现不需要跨实例共享」。
6. 追问式触发，不骚扰：AI 检测到你正在做决策时，最多问一次「要记录吗」。你说「不用」就不再追问本轮。不说话就不自动记录。自动检测的精确规则见 §5.1——必须同时命中信号词和决策感才触发询问。整轮对话累计询问不超过 3 次。违反任一条件，不自作主张问。
7. 演化而非堆砌：项目日志的长期价值取决于有没有事件之间的演变脉络。定期（每月/每季度）做回顾时，AI 不仅要列出事件，要尝试讲出"这个项目是如何一步一步变成今天的样子的"这个叙事。
8. 信息不足时不猜测：AI 无法从对话中提取足够的决策理由、放弃的选项、影响范围时，不编造。触发 §5.2 兜底流程——三个选项让用户决定投入多少精力。即使选择"直接生成草稿"，缺失字段留空标注"待补充"，不填假数据。
9. 反过滤优先于触发：自动检测命中信号词后，先过 §4 反过滤规则。属于反过滤场景的，不触发询问，不记录——即使用户手动要求记录，也只温和提示一次。

§A 结构化异常处理

§B 常见错误与纠正

好的记录 vs 差的记录（对比表）

一句话口诀：写了"为什么"而不是光写"做了什么" + 有数字 + 有放弃的选项 + 有关联事件 = 一条好记录。

§C 能力边界

§D 常见问题与快速排错

使用类

Q1：和 git log 有什么区别？

git log 记录代码变了什么。进化日志记录为什么变。两者互补——git 告诉你「这行代码是 6 月 1 日改的」，进化日志告诉你「6 月 1 日改这行代码是因为 Redis 大 key 导致超时」。

Q2：和 Memory Entry Panel 有什么区别？

记忆词条记录的是你的个人偏好和长期规则——"你这个人喜欢什么风格"。进化日志记录的是项目的决策历史——"这个项目经历过什么"。一个是关于你，一个是关于项目。

Q3：和 AI 无限进化引擎有什么区别？

无限进化跟踪 AI 自身的成长——偏好提取、规则固化、能力迭代。进化日志跟踪你正在做的项目的成长——技术选型、架构变迁、踩坑经验。进化引擎的自省对象是 AI，进化日志的记录对象是你的项目。

Q4：我一个人开发，需要进化日志吗？

更需要。团队项目有 PR、设计文档、会议纪要作为"为什么"的痕迹。个人项目只有你自己知道当时怎么想的——三个月后的你等于一个新加入的成员。

Q5：每天记多少条算正常？

活跃开发阶段：每周 3-5 条（几条决策 + 偶尔的踩坑或灵感）。稳定维护阶段：每月 2-3 条。如果每天都记、每条都写满——你在写日记，不是在记进化日志。

Q6：能导出吗？

可以。说「导出进化日志」即可生成 Markdown / JSON 两种格式。

Q7：AI 老是打断我，问我要不要记录，很烦怎么办？

三种方式：① 说「先别记录」——本轮对话 AI 不再询问；② 在频繁编码阶段说「关闭自动检测」——全局关闭自动触发，只保留手动触发（「记录一下」）；③ 说「恢复自动检测」重新开启。自动检测默认开启。

Q8：我记录的决策后来被推翻了怎么办？

不删旧记录。新增一条 E1 决策记录，标题写「推翻 EV-00XX：[新决策]」，在理由里写清为什么推翻。这样三个月后你不仅知道当初怎么想的，也知道后来为什么变了。

Q9：一条记录应该写多长？

没有硬性规定。三句话搞定最好：做什么 → 为什么 → 影响。但如果一句话能说清楚，一句话也行（见 §5.6 极简记录）。关键是"为什么"写清楚。

Q10：我不确定该用哪种事件类型？

先看 §1 的表格找最接近的。实在不确定时：涉及"选哪个"用 E1 决策；涉及"怎么拆/怎么组"用 E2 架构；涉及"用什么工具/库"用 E3 选型；涉及"出问题了"用 E4 踩坑；涉及"突然想到"用 E5 灵感；涉及"到了某个标志性节点"用 E6 里程碑。

排错类

Q11：记录后发现写错了怎么办？

说「修改 EV-00XX」并告诉我要改什么字段。只有记录者标识之前的字段可以修改——事件 id、时间戳、类型不可改。

Q12：进化日志文件在哪？

当前项目的 evolution-log.json。说「打开进化日志文件」即可定位。

Q13：自动检测为什么没触发？

检查：① 你的话同时命中了"信号词"和"决策感"吗？（见 §5.1 精确触发规则表）② 本轮对话累计询问是否已达 3 次上限？③ 该事件类型本轮是否已被你拒绝过？④ 是否说过「关闭自动检测」？如果都不是，直接说「记录一下」手动触发即可——自动检测是辅助，漏了一两条不影响核心价值。

Q14：JSON 文件打开是乱码？

进化日志的 JSON 是 UTF-8 编码。如果记事本打开乱码，用 VS Code 或说「导出进化日志为 Markdown」获取可读版本。

§E 最佳实践

三句话写好一条进化事件

一句话写做了什么，一句话写为什么，一句话写影响。

> ❌ 太抽象：「优化了数据库性能」
>
> ✅ 三句话：「给 users 表加了复合索引（做了什么），因为登录接口需要同时查 email 和 status 字段（为什么），P99 响应时间从 800ms 降到 120ms（影响）」

每月做一次 5 分钟回顾

月末说「生成这个月的进化报告」。花 5 分钟扫一眼——你会看到本月走了多远、做了什么大决策、踩了什么坑。这个过程本身就是最有价值的复盘。

踩坑记录写全四要素

现象 → 根因 → 修复 → 避免方案。四样缺一个，三个月后别人（包括你自己）还是不知道下次怎么避免。

里程碑带数字

「v2.0 上线」是废条目。「v2.0 上线，日活从 200 涨到 1000，用户反馈好评率 92%」是有价值的里程碑。

§F 与其他 Skill 联动

§G 版本历史