Skip to content

armgit / peach

Public Imported from GitHub
0

Peach: Local-first video metadata scraper and media manager.

2.8 KB
Raw Blame

ADR-0010:先复用、再重实现

  • 状态:Accepted
  • 日期:2026-08-14

背景

项目结构迁移删除了旧文件名,但多项实现实际以高相似度迁入 scripts/。按旧文件名查找导致现有 scripts/scrape_codes.py 被误判为缺失,并准备从 Git 恢复旧 scraper。迁移期间也出现过未对照已验证实现而重写 mDNS、重复媒体抽象、重复计费/磁盘闸门等问题。

2026-08 的 FANBOX 追更又暴露了同类缺陷:Peach 先围绕 User-Agent、Cookie 与错误状态反复补丁,后来 用成熟的 curl_cffi 传输立即解决站点指纹问题;继续审计时还发现自写正文解析只覆盖 article 的 段落与图片,而 PixivUtil2 已处理 image、file、article、video、embed 等公开数据形态。这说明「查当前 仓库」仍不够,外部成熟轮子和参考实现必须进入新增或重写前的强制路径。

决策

  • 新增、恢复或重写实现前,按能力、输入输出和数据副作用搜索当前树,检查 docs/REUSE.md 和 Git 历史,再检索官方 SDK、成熟依赖、维护中的开源实现和系统原生能力。
  • 候选必须用当前任务的真实输入做无写入 POC,并核对许可证、维护状态、固定版本、平台/Python 兼容、依赖体积、打包和已知失败。仅凭项目主页或名称相似不得决定采用。
  • Peach 只自研领域差异:实体身份、行为、跨来源绑定、成本/隐私、review/provenance 和任务语义。
  • 协议、解析、媒体编解码、搜索基础设施、播放器、图标和调度优先使用成熟依赖;首个真实消费者、固定版本和隔离测试必须同批落地。
  • 没有可直接安装的成熟依赖时,可以固定 revision 复用成熟实现的数据模型或算法边界;只有外部方案 不满足已验证约束时才保留自研,并把拒绝理由与实证写进 docs/REUSE.md。
  • 运行时只保留一个正式 abstraction。迁移 facade 若未接入生产,不得算作能力完成。
  • 用户不承担代理间信息同步;公开知识写入产品文档、REUSE 和 ADR,私有运行记录保存在仓库外,见 ADR-0015。

被否决的方案

  • 因旧文件名消失就从 Git 恢复整份脚本。
  • 为统一表面接口,把 Codex/Claude agent runtime 与普通 inference API 强行等同。
  • 在没有首个消费者时提前堆积依赖。
  • 因外部实现不是现成 Python wheel 就跳过检索,继续用站点补丁试错。
  • 保留两套生产 abstraction,依靠调用者自行选择。

后果

每项能力多一道短审计,但能避免迁移回归、重复维护和不必要的协议实现。docs/REUSE.md 成为可更新的实现索引,不替代具体 ADR 和测试证据。