Devlog

August 7, 2026 · View on GitHub

Galley 开发日志：记录设计与工程决策的"为什么"，以及考虑过但被否的方案。

补充于 PRD（产品定义）、DESIGN.md（设计规则）、CLAUDE.md（项目宪法）—— devlog 提供历史叙事和 decision provenance。git log 太短只说"是什么"，PRD 太静态只说"现在是什么"，devlog 才记录"我们怎么走到这里的"。

谁在读 · 怎么用

本 devlog 的主要读者是跨 session 的 agent —— 用它在新会话里快速接回项目的决策脉络。按三层用：

  • 检索（已知关键词）：rg docs/devlog/，搜正文每个字，对体量免疫。
  • 路由（不确定去哪篇）：扫下方时间线的一行索引，再 Read 命中的 entry。
  • 开工前：扫一眼 deferred.md，别重新提议早已被否或搁置的方案。

索引只负责路由，搜索交给 rg —— 所以时间线保持一行一条，不塞长摘要（长摘要既吃 agent 的 context，又会和正文双写漂移）。

时间线

按日期分组，每条一行索引供 agent 路由；hook 只需含能判断相关性、可 grep 的关键词（功能名 / 模块名 / 版本号），不追求文采。点标题进对应 entry 看完整叙事。

2026-05-07

2026-05-08

2026-05-09

2026-05-11

2026-05-12

2026-05-13

2026-05-14

2026-05-15

2026-05-18

2026-05-19

2026-05-20

2026-05-21

2026-05-22

2026-05-25

2026-05-26

2026-05-27

2026-05-28

2026-05-29

2026-05-31

  • Alpha.2 dogfood UX polish — 小屏 Onboarding + 外部 GA probe + Tooltip/Toast 降噪 + Channels 入口
  • v0.2.0 stable release — 第一个正式版 v0.2.0 非 prerelease Latest，release notes 中英双语，promote beta 通道

2026-06-01

2026-06-02

2026-06-03

2026-06-04

2026-06-09

2026-06-10

2026-06-11

2026-06-12

2026-06-15

  • Knowledge Sync rules — neat-freak 原则裁成轻量 Session Close 子流程：按受众同步 + 允许 no-op

2026-06-16

2026-06-18

2026-06-19

2026-06-20

2026-06-22

2026-06-23

2026-06-24

2026-06-25

2026-06-29

2026-07-02

2026-07-03

2026-07-04

2026-07-05

2026-07-06

2026-07-07

2026-07-09

2026-07-10

2026-07-11

2026-07-15

2026-07-16

2026-07-17

2026-07-20

2026-07-21

2026-07-22

2026-07-23

  • Rust 大文件拆分五连 + GUI 第四轮 — lib.rs run()/session_cmds/hive 主循环/codex_oauth/im_supervisor 五拆 + App.tsx host 组件/runtime store 切片/MarkdownView 三拆；migration_backup 决定不拆；workbench_bridge 缓做入 deferred
  • GA upstream upgrade 1d3c1a09 -> 4086d5c 与上游历史重写 — 上游 force-push 改写 main（提交信息英文化），旧基线 SHA 官方不可达，tree 等价锚点 8a75b39 证明内容同一；真实增量仅 5 提交；get_llm_name 去 Session 后缀 → bridge 容错匹配；基线文档增记 tree hash

2026-07-24

  • v0.4.0 发布:定时任务 + 内核基线 4086d5c — 聚合 v0.3.7..HEAD 打包 minor:定时任务(GUI 闭环 9/10 issue,06 CLI 面刻意留 v1 非目标)+ baseline 5257dec→1d3c1a09→4086d5c 首发 + plan mode 移除 + Rust/GUI 拆分;版本决策否掉 0.3.8 patch

2026-07-25

  • Dark theme 降暖一档 — dark 表面/墨色 chroma ×0.6（L 与色相不动，对比度 14.97→14.95）；相对饱和度 C/L 指标暴露 light 中性纸 vs dark 染色纸的策略分叉；Ghostty 参考结论是「抬画布」而非低对比，冷蓝色相不借；brand 家族与语义色留待下轮
  • 深色下"主对话区字体太亮" — 病因不是颜色而是 -webkit-font-smoothing: auto 的笔画膨胀（macOS 已无次像素渲染），亮字压暗底被放大；覆盖限定浅色（html:not([data-theme="dark"]) [data-cjk-prose]），浅色行为不变；抬画布与降 ink 明度（Notion 档）双双未执行，数值留档

2026-07-28

  • 架构审查第二轮:四个 Strong 候选落地 — scheduler fire 进 HandlerCtx seam(修时间戳字典序/fail-all 读取/re-enable 三缺陷 + SessionNewResult 类型化);/btw 判定统一到 lib/side-question(修 \t 不一致真 bug)+ composer-hint 政策抽纯函数;useMessageSend 21 参收 5 + 双 send-phase 状态机合一;GA baseline gate 改生成式(manifest 补 commitDate/treeHash,defaults.ts 与 fixture 退出手动同步);候选 5-7 与 quick wins 入 deferred

2026-07-30

  • 窗口几何:失忆→持久化 + Reset to Default Layout — 同日三次决策:上午裁决启动失忆并实施,复议后反转为持久化 + 恢复默认布局三入口(Window 菜单/命令面板/分隔条双击),发版讨论中第三裁将分隔条双击从仅分栏升级为完整恢复(可发现性)并加 hover tooltip 教学;保留首启居中与小屏钳制两个净收益;失忆实现留在 git(c7c994fc)可考古
  • v0.4.1 发布:composer 文件拖放 + 窗口布局复位 — 聚合 v0.4.0..HEAD 打包:文件拖放/文件引用(5/6 issue done,05 Windows smoke 留发布装机终验)+ 窗口布局 + 架构评审轮收口 + 主题微调;GA baseline 4086d5c 不变;版本定级 JC 裁决按功能量级判为 patch,agent 按 v0.4.0 先例推荐的 0.5.0 minor 被否
  • 定时任务信任面打磨轮 — 信任三问框架驱动 issues 11–14:失败可见性(需行动数角标+失败通知)/表单触发预览(preview_scheduled_fire)/立即运行(run_task_now 盖戳语义)/自启条件式引导;否决总任务数角标(alarm fatigue);footer 按钮两轮返工教训(ghost+邻近)

2026-08-03

  • Question Rail:tooltip 加回答预览,用 final answer 而非 summary — 缺口定位为辨识而非导航,故只改 tooltip 不加 dot;初判推荐 AgentTurn.summary 后翻代码改判(它是喂回 agent 的工作记忆、语义前瞻、最终答案轮 no_tool 框架失配);跳 ATX 标题取首个正文行;配对取最后一个非 null finalAnswer(JC 裁 (a) 案);逻辑抽进 lib/rail-preview.ts 并单测;tooltip 竖直阈值 6/94→10/90
  • GA upstream 升级 4086d5c -> d8d90ee — 20 commits/11 天,2/3 是 upstream 前端(含新 hub.py WS peer hub)inert;引擎实质是中断响应性(active_response+should_stop)、max_retry_after 封顶、Responses API incomplete/failed 终止事件;方法论教训:零上下文 git apply 探针全绿≠无冲突,只有 commit-chain rebase 的 3-way merge 才测得出(0007 codex 429 富化撞上游 retry-after 改写,两边保留);遗留耦合断裂:thinking_delta 现在吐无标签推理文本,而 Galley 剥的 <thinking> 标签是提示词约定(走 text_delta)、跟 API 原生 thinking block 是两条通道;因 managed_model.rs 默认 thinking_type: adaptive,对托管 Anthropic 模型默认命中(初判"不可达"系查错了开关名,已纠正);不动的代价是 final_answer 落库+FTS 索引被永久写脏、思考面板反而空、刚做的 rail tooltip 失效;同轮加 0016 补丁收口——整块缓冲后包 <thinking> 标签发出,归一到既有约定,顺带让原生推理正确进思考面板;否决"关 thinking"(拿模型质量换显示)和"撤 yield"(纯分叉且永久丢失推理)
  • TurnMarker 副标题与回答重复:GA summary 兜底的渲染层去重 — draft dogfood 发现同一段话显示两遍;根因是 ga.py:594-601 在模型漏写 <summary> 时拿整段正文当摘要,Galley 把它渲染在同一段正文正上方;查证非 v0.4.2 回归(重复行早于 d8d90ee 升级,turn_end_callback 逐字未变,补丁 0016 不进 response.content),也非协议问题(是模型合规度:glm-5.2 12 行中 4 行漏写,gpt-5.6-sol 5 行全写);否决改 GA 兜底(summary 进 history_info 是 agent 工作记忆,完整正文在那端更有价值),改在渲染层判重,顺带修好已入库历史行;否决前缀匹配(误伤合规短摘要且盖不住带围栏的形状),改用"去围栏候选 + smart_format 省略形"精确比对;preamble 一半已被既有 narrationDuplicatesPreamble 盖住
  • v0.4.2 发布:定时任务信任面 + 引擎升级到 d8d90ee — 聚合 v0.4.1..HEAD 11 个提交:定时任务信任面 issues 11–14 + rail tooltip 回答预览 + GA baseline 首发 d8d90ee;定级沿用 v0.4.1 的功能量级规则判 patch(v0.2.16 发运审计 baseline 同为 patch);补丁 0016 是发运前提而非附带(不打则 thinking 脏数据永久落 final_answer);06 CLI schedule 继续留作 v1 非目标——属 Agent API 面,不搭 patch 版顺风车;构建机是 Intel Mac,bundled runtime gate 走 mac-x64,arm64 产物由 CI 出

2026-08-04

  • UI Polish 马拉松:六轮全域界面细节打磨 — polish-checklist 建档(make-interfaces-feel-better 摘录+否决);同心圆角/hover 瞬时/tabular-nums/pop-in register 六轮清扫;裁决:0.5px 按压判负、submit-ack 与 runtime-highlight off-scale 保留、focus-visible 暂缓;transition-colors 家族清零;dark 主题高亮环 color-mix 修复
  • 自动标题 + 下一步建议 ghost text — <next-suggestion> 标签走 managed prompt 同次补全(否独立侧调用/静态 chips);标题走 GaSession.side_ask 每会话一次(否 summary 复用/通用 side-ask 设施);title_source 四态 seed/derived/auto/user + CAS 防改名竞态;migration 038;generate_title/title_generated IPC;ghost 显示是派生条件非一次性事件;零模型选项零开关;立辅助 LLM 功能三条准入判据,否 EmptyState ghost 等一批候选

2026-08-05

  • Next-suggestion 默认强制 + ghost 可达性 — dogfood 首轮复现标签遵从率失灵(glm-5.2 散文提议无标签);推翻「有才写」为默认强制+枚举豁免(唯一豁免:对话明确终结),失败模式不对称+格式习惯优于逐次裁量+token 占比 <1%;「结尾提议即下一步」转换规则+grounding 地板;节挪 RUNTIME_PROMPT_STATIC 末尾,prompt_hash 翻新;ghost hint 改可点击 button(鼠标通道)+aria-describedby sr-only(AT 通道)+textarea title 看截断全文;否:正文风格管制、散文解析兜底

2026-08-06

  • v0.4.3 发布 — 聚合会话智能(自动标题+ghost 建议)、阅读体验(run 折叠+高亮笔)、polish marathon、0017 记账;patch 定级(单功能量级判,不按批次总量);发布准备修掉两个 gate 缺口:ipc.ts 缺 generate_title 镜像(CI 自 08-04 连红)、baseline gate 的 replay=auditedAt 假设被首个补丁单独落地案例打破(改为不早于)
  • 完成 run 的过程折叠 — settled run 过程段折成一行折叠头,pickToolTier 哲学升维到 run 层;run-groups.ts 单一真相源(折叠+rail 共用,ask_user 回复启发式);折叠时机=注意力交接点(最新展开/提交即折/重开全折);rail 圆点重定义为 run 发起消息;四轮 dogfood:行首 disclosure triangle、工具名走 copy.tools、墨阶降档+折叠头 vs Footer 领土表(耗时归折叠头,Footer 删 ⏱)、「用时」前缀防中文时长模板误读
  • 0017 兼容端点 input token 记账修复 — Footer ↑0 根因:GLM 等 Anthropic 兼容端点在 message_start 给零 usage、完整 usage 在 message_delta,上游只从 message_start 记 input;llmcore delta 侧兜底(真 Anthropic 不重复计数)+cost_tracker requests 门控;基线重放验证
  • Settings 泛用入口默认 tab 收口 — 齿轮/命令面板/⌘, 裸调 setSettingsOpen 落点不确定;收口 openSettings() 确定落 General(对应性原则);深链不变;否:记住上次 tab
  • User 消息重设计:callout → 高亮笔 — 用户消息从大棱角矩形改高亮笔形态(b-fused),文档隐喻重推,两轮真机 A/B 落定
  • 折叠 run 的垂直节奏 — 折叠态移除 StrongHr,折叠头贴紧回答;proximity 绑定修正(header 是回答的 eyebrow)
  • 单步 run 也可折 — 删 foldable 的 stepCount>=2 条件;耗时归折叠头独家后缺席即丢数据;否:单步专属元数据头、Footer 恢复 ⏱
  • ask_user 三连修 + 折叠头截断策略 — pending 期回显与气泡同屏去重(askUserPending 抑制);ask_user 终止 run 误发「回复完成」通知改 askUser 类(复用 replyDone 开关);重启后从 tool args 重建 pendingAskUser(chips/黄点复活);折叠头 scent 按次数降序+提问计数移出截断区+溢出 tooltip

2026-08-07

  • Dialog 关闭按钮统一 — 抽 DialogCloseButton 进 ui/(inline ghost / floating 软化双变体;否 DialogShell:骨架不同构);内容型必有 X、确认型不放 X 成文;真机 A/B 否 secondary 凸起;Settings 右栏 pt-12 安全区+同色渐隐(角落争议是结构问题皮肤解不了);删 session-browser 冗余 onClick 与重复 close 文案 key
  • v0.4.4 发布 — 聚合 ask_user 可达性三连、滚动双态信号、overlay 920 档 + 摘要清洗、推理强度徽章;patch 定级(同 v0.4.1 规则,按最大单功能判);发版触发是 v0.4.3 自带的 sidebar hover 失明回归,不是攒够了;零 Rust 改动、未触 managed GA 故跳过 bundled runtime gate;顺带补掉连续两版 carry over 的应用内更新 dogfood 欠账
  • 滚动按钮双态信号 + 追尾修复 — 置底按钮运行中 pulse ring / 完成未读静态点(边沿触发真未读,回底即清);三轮语义翻转(区分→未读反转→双态合成);smooth scroll 追移动靶+超时 snap+attach,点击语义定为「挂上尾部」
  • Sidebar hover 失明修复 — 08-05 chrome 加深后 --color-hover 反比底亮(ΔL* 0.7 反向);.chrome-hover-scope 作用域覆写 #E5E3E0(ΔL* ~3.9 复刻 chrome 递进);否:专用 token(忘用即重演)、全局 alpha 叠层(波及 inline code);selected 明度持平记 deferred
  • Overlay 920 档定型 + session 摘要清洗 — 尺寸阶梯 420/920/1040(否:全统一 Settings 尺寸;640 中档被真机推翻清空);PaletteRow sub 挤压 bug→inline preview;GA 兜底摘要脏数据双端镜像清洗(_clean_turn_summary / cleanSessionSummary);定时空状态 grid-cols-3 模板卡;Earlier/Archived 维持双行(否:与 palette 统一单行,邮件客户端类比)
  • 推理强度默认语义 + 第一方 high + 行徽章 — 「默认」=不发参数跟随服务商;仅三个第一方预设显式 high(第三方兼容端点保留不传);存量不迁移;Models 行档位 chip 读快照不读推荐叠加;否:Composer 快捷入口(作用域错位,走 effort 变体条目路线,记 deferred)

格式约定

每个 entry 6 段：

  • Date / Status / Related — 元信息（含 PRD/DESIGN/commit 引用）
  • Context — 这次讨论或工作的背景
  • Decisions — 对齐的具体结论，列表化、可索引
  • Rejected alternatives — 考虑过但没选的方案 + 理由（最有价值的部分）
  • Open questions — 留待后续的问题
  • Next — 这次工作的下一步

触发时机

主动写 devlog 的三种场合：

  1. 每次 work session 结束（"今天先到这里"）
  2. 重大设计/架构决策对齐后（不一定等 session 结束）
  3. 阶段切换（如 Stage 1 → Stage 2，写一份阶段总结）

写作责任

  • Claude 主写：每次决策对齐后主动提议落 devlog
  • 作者 review：可以 inline 调整，Claude 根据反馈改
  • 不重复信息：devlog 不复述 PRD / DESIGN.md / CLAUDE.md 已有的内容，只记叙事 + decision provenance
  • 命名一致性（为 agent 检索）：同一条线（baseline 的 commit 短哈希、IPC 命令名、模块名等）在 hook 和正文里用同一个稳定、可 grep 的词。agent 靠 rg 把散在数月里的相关 entry 串起来，命名一飘就串不起来

文件命名

YYYY-MM-DD-topic-in-kebab-case.md，一天可以多个 entry（按主题分）。

挂起 / 暂不实施的想法不单独成 entry —— 记进 deferred.md 台账（一想法一节：状态 / 提出 / 启动信号 / 方案 / 实施要点 / 待定 / 关联）。真正开工时再从台账拎出、落成正式 entry。