切换外观
决策记录
状态：首切片设计基线已完成，产品待实现。本文记录范围、取舍理由、实现顺序与后续问题；外部行为唯一定义在信息契约，本地持久化方法唯一定义在架构。故事、Skill 和数学说明可从各自视角重复解释，但不另立协议。
背景见原始设计 v0.3。产品意图见 product.md，职责边界见 architecture.md，工作方式见 development.md。
已对齐的方向
首切片、后续切片与历史参考的效力不同；具体范围与未决问题以本记录为准。
- 泛化输入与结构化输出构成产品边界。 输入可以来自 Agent 自身工作、外部观测或用户告知；输出是预定义结构，供 UI、推送与日志消费。Pinboard 和推送发送都是下游应用。
- LLM 让语境估计成为可调用的环节。 Agent 结合当前状态和用户背景估计关注价值；Skill 通过表述转换与上下文供给帮助估计。估计质量需要用场景验证。
- Agent 做判断，脚本守边界。 重要性、让位和合并由 Agent 决定；脚本执行明确操作、检查约束、保留记录，不自行降档或驱逐。
- 信息失效与行动截止是不同概念。 账单逾期后仍然重要；到期不推出撤下。
- Skill 同时交付判断指引与操作工具。 Agent 通过固定语义的命令读取、提交、批注和查询，不临时实现存储与预算逻辑。
- 通知与持续整理可以同时发生。 紧急事项先走即时渠道，是否纳入后续整理按持续关注价值判断；用户是否在场不是 Fold 的使用门槛。
首个切片：US-01 单 Agent 本地闭环
首切片以信息契约为规范，conformance/cases 提供对应的验收断言，Skill 设计指导 Agent 如何使用。用例目前是待实现的验收材料，不表示产品已通过测试；发现用例与规范不一致时修正两者，不让实现暗中选择一种解释。
| 决定 | 内容 | 理由 |
|---|---|---|
| 范围 | 单用户、单 Agent、本地目录存储、Agent 自己的进度声明、文字简报、批注往返，以及 state 的可选静态 overview / diff 图。不在场是 US-01 的验证场景。 | 先验证完整往返，并帮助 Agent 从大状态中定位全局与变化。 |
| 份额协议 | Agent 默认提交五档 weight，脚本派生 share：critical 3B/8、high 3B/16、normal 3B/32、low 3B/64、trace 1，向下取整、最小 1。B = 64 时为 24 / 12 / 6 / 3 / 1。 | 减少直接填写数字的负担，固定换算；判断质量仍须单独评估。 |
| 超额处理 | 总和超过预算时整批拒绝，错误返回预算、候选总量、超出量和每项份额。不做同档平分、拥挤下调、自动降档或驱逐。 | 谁让位由 Agent 决定，脚本只说明超在哪里。 |
| 份额覆盖 | share 可显式覆盖映射，必须同时给 reason；share: null 取消覆盖并重新派生。存储区分覆盖值与派生结果。 | 保留对尺度的明确控制，并能取消此前例外。 |
| 份额评估 | 记录本批显式份额覆盖率、等义改写下的档位稳定率，并继续检查关键事实与遗漏后果。定义见 Skill 设计。 | 检查默认映射是否省力，以及判断是否稳定；稳定不等于正确。 |
| 排序与消费信号 | rank 由脚本派生：share 降序，同 share 时 needs-you 优先，再按 updated_at 新者优先，最后按 id 字典序。消费者使用 weight、share、rank、kind、status；身份、时间与来源等结构字段仍保留。 | 固定排序，不把模型的自由文本当程序协议。 |
| 时间 | 存储 created_at、updated_at、due_at、stale_after；以调用方的 now 派生 age、since_update、until_due、until_stale。到期只改投影，不改状态。 | 时间算术交给脚本，撤下仍需明确声明。 |
| 用户阅读 | 首切片不采集用户查看；last_seen_at、since_seen 均为 null，含义是未采集，不是从未看过。state 与 annotate 不推导人是否读过。 | 没有查看入口时不制造阅读证据。 |
| 输入范围 | 首切片接受 Agent 声明，可带 sources 附件。附件只做必要的结构检查，不核验事实，也不参与重要性或份额判断。 | Observation 接入是一条独立管道。 |
| 标题信息密度 | 标题的长度、直述与更新规则见声明字段。 | 标题是首要识别入口，需要同时容纳对象、关键数值与当前状态，减少进入详情才能理解事项的负担。 |
| 安全重试 | 采用批次与回执协议。重复判定保留执行者与完整操作，排除调用时间；冲突提供原已提交结果。 | Agent 重试时更新时间不应制造冲突，执行归属和操作差异仍须核对。 |
| 提交与恢复 | 事件为事实源，快照为可重建缓存；完整本地顺序见架构。 | 原子保存不保证回执到达，缓存落后可以恢复；不在各篇复制存储协议。 |
| 版本 | 每条持久事件递增 event_seq。有业务变化或新增批注确认时 revision 递增一次；保存批注与 checked 不增加 revision。 | 事件顺序与条目/确认状态的版本分别表达。 |
| 无变化提交 | 无业务变化、无新增 acknowledge：写 checked，带 batch_id、actor、now，不改 revision 或条目 updated_at。有新增 acknowledge：写 acknowledge，revision 递增，updated_at 不变。 | 记录检查与确认，不伪造内容更新。 |
| 有效变化 | 先应用补丁、继承和派生，再比较业务字段。同内容 supersede、reason-only 和自动元数据变化不算业务变化。重复确认不覆盖首次绑定 revision。 | 保护 since_update 和排序，不靠重复提交刷新内容。 |
| 补丁语义 | supersede 省略可选字段即保留；非 withdraw 每次仍须提供 weight/kind。允许为空的字段可显式 null 清空，最终状态仍须满足结构约束。 | 避免更新摘要时丢失期限、来源或子层。 |
| 子层编辑 | children 描述目标集合，但移除原有子项必须另有明确 withdraw；错误列出受影响对象。 | 父项的一句 reason 不能证明 Agent 有意撤下列表中遗漏的孩子。 |
| 合并范围 | 首切片只支持同层 active 叶子、没有历史子树的合并。复杂合并与 detail-of 推迟，具体拒绝条件见信息契约。 | 保留 US-01 的 PR 汇总，不引入未定义的子树迁移或旧项恢复。 |
| 撤下 | withdraw 不要求 weight/kind，作用于整棵子树的当前可见性；保留原 ID、关系、内容、来源、批注与原因，未确认批注仍可取得。 | 退出关注范围不等于删除资料。 |
| 重新纳入 | supersedes 原 ID 恢复被明确声明的条目，旧后代不自动恢复；恢复子项的最终父项须为 active。 | 保持身份与资料连续，不让历史子树意外重新占用预算。 |
| 反馈状态 | saved / acknowledged。仅在成功的 commit 中确认，并绑定首次确认 revision；外部行动结果另行表达。 | 尚未确认不证明尚未读取，确认也不证明外部行动完成。 |
| 调用时机 | 开始时读状态与待确认批注；里程碑提交；结束前调用一次 commit，允许 checked 或仅确认。 | 非常驻宿主也能完成整理与确认。 |
| 资料更新 | sources 属于可变资料，补充来源会刷新 updated_at；该时间不表示现实事项一定推进。 | 先保留一个清楚的资料更新时间，不为排序再增加一套时钟。 |
| 首个渲染器 | 文字简报，遵循消费者规则；首切片不设额外总行数硬限制。 | 先验证摘要与档位折叠的阅读效果，不凭空加入 12 行裁切。 |
| Agent 视觉概览 | 以精简 Pinboard 表达 state：同层面积映射最终 share / budget，留白与未展示占位分开；颜色与标记承载其他属性。选择、真实渲染和 diff 见视觉概览规范。 | 让关注份额有直观大小，而非仅显示数字；不改变状态结构、不重新判定重要性。 |
| 实现栈与输入格式 | 内核、存储及普通 CLI 使用 Python 标准库，事件与快照保持原结构；可视模块另用可选浏览器运行环境。commit 只接收 JSON，YAML 仅用于设计用例。 | 将实际截图依赖与核心隔离；无浏览器仍可读取 JSON，不用生成式图片伪造业务图。 |
实现顺序与完成标准
先形成可阅读的用户往返，再补足边界与可靠落盘。阶段按依赖推进，用例编号不代表模块可以彼此独立实现。
| 阶段 | 实现什么 | 完成时能够验证什么 |
|---|---|---|
| 1. 内存中的完整往返 | 纯内核、内存事件与批注上下文、文字简报；包含 01/02 已依赖的补丁继承、子层创建、按 ID 更新孩子、叶子合并与撤下。 | 跑通 01/02 的语义、历史查询和简报断言，实际阅读 US-01 的结果。此阶段不宣称真实 CLI 的持久化已完成。 |
| 2. 核心边界与读取投影 | 完善 04 的子树边界、05 的操作限制、03 的非中断场景，以及 06 的选择范围与语义 diff。 | 同一规范在边界情况下仍一致，视觉投影与 JSON 对应；不把这些数据断言当作实际截图验收。 |
| 3. 本地存储与 CLI 交付 | 接入文件恢复、四个 CLI 子命令及可选浏览器渲染；运行 03 的真实中断恢复和 06 的 PNG/DOM 验收。 | 六组完整用例、CLI 输入输出、重启恢复和真实概览图通过；用户往返与 Agent 视觉辅助均可在本地完成。 |
内核用进程内调用验证，存储故障可用明确的测试注入点；恢复验收保留少量真实子进程终止后重新启动的检查，不能用普通异常替代全部崩溃场景。当前 make check 仍只检查仓库材料，产品测试命令随实现加入。
设计阶段以这份基线收束。后续实现发现矛盾时，同步修正规范和用例；语义估计质量与真实阅读体验仍需执行验证，不因设计基线完成而视为已证明。
推迟到后续切片
| 问题 | 触发条件 | 当前倾向 |
|---|---|---|
| Observation 正式 schema、去重与 subject 关联 | 接入第一个非 Agent 渠道时 | 沿用信息契约第 2、3 节的候选表达。 |
| detail-of 与跨层移动 | 出现首切片 children 无法表达的明确场景时 | 先区分新增细节与移动旧项，再定义身份、父层预算和历史关系。 |
| 带当前或历史子树的合并、合并后的拆分 | 真实整理需要迁移细节或恢复旧合并项时 | 先定义子树归属、来源及反馈留存；首切片对这些结构明确拒绝。 |
| 多 Agent 的语义协作 | 接入第二个 Agent 时 | 提交带读取时 revision，不一致重读；Agent 只修改自己创建的条目，以 yield_request 请求他人让位。本地写入互斥不因此延期。 |
| 推送消费者的阈值与发送 | 实现第一个推送应用时 | 依赖 kind 与 weight，不用 share 做阈值。 |
| 交互式 Pinboard 与媒介适配 | 首切片文字简报与静态 Agent 概览跑通后 | 拖拽、点击与持续布局等交互另行设计；静态 state / diff 图已纳入首切片，份额不因屏幕尺寸重算。 |
| 文字简报总行数预算 | 实际阅读发现默认档位折叠仍过长时 | 先定义逻辑行计数、被折叠内容与展开入口，再比较容量；不按终端宽度截断摘要。 |
| 自动失效的触发点 | 需要无 Agent 介入的状态变化时 | 读取时投影“已过期”，撤下仍需声明。 |
| 远程存储与多端恢复 | 存储离开本地文件时 | 在现有 batch_id 核对与事件恢复契约上扩展，不重新定义成功与失败。 |
| 完整输入档案的保存范围 | 产品承诺“任何收到的信息都能查”时 | 输出日志不冒充输入档案。 |
| 用户查看入口、阅读统计与 typical_return | 实现能明确记录用户查看对象和版本的消费者时 | 定义查看动作及范围后才产生 last_seen_at；不能用 Agent 查询代替。 |
| 五档方案的调整 | 语义评估显示默认映射频繁需要覆盖，或档位不稳定时 | 结合错误案例与阅读效果再比较相对排序、比例分配等替代方案，不仅凭一个比例换协议。 |
| SKILL.md 与 SDK 指引的共用源 | 交付第二种宿主形态时 | 同一份源生成两种包装。 |
原稿中不再作为默认实现要求的内容
以下设计保留在原稿中供理解演进过程，未经重新讨论不按它们实现：
- 同档条目平分某个固定份额池，以及拥挤时整体下调。
- 编译器按固定顺序自动降档、嵌套、挤出条目，以替 Agent 完成溢出取舍。
- 溢出时优先撤下临近失效的条目，或把临近行动截止等同于信息价值降低。
- 把坐标与矩形排版放进通用内核。
- 起步时就交付双语言内核、全部框架适配器和远程 MCP 形态。
- 仅把 Agent 自己的工作进展视为输入；当前边界已扩展为泛化输入和多应用消费，首切片只是从 Agent 声明开始。