develop-hackernews-reader

# 开发 Hacker News Reader ## 使用方式 先阅读仓库根目录 `AGENTS.md`。以当前源码、类型、测试、构建配置和运行契约为事实源；涉及架构决策时按需阅读 `docs/ARCHITECTURE.md` 与相关 ADR，涉及性能、安全或验收时阅读 `docs/QUALITY_GATES.md`。 默认只处理开发与可自动化的本地验证。运行态调试、浏览器交互验收和其他手动测试由用户执行；只有用户明确要求调试或指定手动验收目标时才执行。未经用户明确要求，不提交、不推送、不发布。 ## 锁定任务边界 - 先确定用户可见行为、源码 owner、关联契约、测试和生成物。 - 只编辑 `lite/src`、`lite/styles`、元数据、测试和构建配置等事实源；不要直接编辑生成的 userscript 或拆分库。 - 保留用户已有改动，不整理无关文件。 ## 实现不变量 - 默认路径 DOM-first；缺失回复才经 HN API 补全，不轮询。 - 评论树先归一化为唯一状态，再派生 Reddit 式可见扁平列表和虚拟窗口。 - 请求必须经过有界调度、去重、取消和生命周期清理；全局并发遵循架构约束。 - userscript 只匹配 Hacker News，初始加载不主动请求、不启动轮询、不做全页高频观察。 - 全帖预热只能在 Reader 首屏后以可取消空闲分片运行；它可以准备搜索、翻译分段、指纹、树索引和虚拟高度，但不得自动发起翻译、AI 或其他网络请求。 - 阅读器只读；登录、投票、回复和收藏继续交给 Hacker News 原生页面。 - Google/Microsoft 仅作公共翻译后备；自定义 AI 必须由用户显式配置并触发。 - 外链文章抓取、抽取、翻译和总结在浮窗会话内完成，不注入第三方页面。 - 离线文件直接在内存生成并交给浏览器下载，不建立下载历史管理器。 - 资源、监听器、观察器、计时器和请求都必须由明确的生命周期 scope 回收。 ## 修改与验证 1. 修改前直接阅读命中 owner 及其调用点、类型和测试，沿用当前模式完成最小改动。 2. JS、TS 或 React 改动只对本次文件运行一次 ESLint；本次引入问题时修复后再运行一次。 3. 按影响范围运行已有的匹配测试、类型检查和本地构建；性能变更按 `docs/QUALITY_GATES.md` 验证。 4. 将源码检查、静态检查、测试、构建、浏览器验收和性能验收分层报告；未执行的层级明确标注。 用户目标和相关回归证据满足后停止，不顺手重构相邻 owner。