🧠 概念总览

这一页把 sip 用到的所有概念用大白话讲清楚。每个概念都标注它是什么、在哪、怎么理解。详细操作见对应章节的链接。

1. 数据与存储

数据目录 readwithhotsoup/

所有数据都放在可执行程序同级的 readwithhotsoup/ 文件夹里（首次启动自动创建）。把它整个备份/迁移 = 备份/迁移你的全部数据。默认是开放标准格式：SQLite + 明文 JSON，随时可被其它工具读取、可更换软件核心迁移（注意：孟思琳挡位 3 开启数据加密后，rss.db、全文缓存与去重规则为密文——见安全）。

主数据库 rss.db（SQLite）

核心数据，几类表：

• Feeds：订阅源（标题、FeedUrl、官网、调度、原始 XML、上次拉取时间）。
• Items：文章。每篇文章一行，含 FeedId（属于哪个源）、Guid（唯一标识）、Version（第几版）、Status（状态）。
• Models：AI 模型元数据（embedding / llm）。
• Vectors：文章向量（语义搜索用，blob）。

文章的「状态」Status

每篇文章有一个状态，决定它在哪些地方出现：

状态	含义	会出现在？
active	正常	列表 / 搜索 / 全文 / 摘要 / 计数都算
archived	归档（作者改版时旧版被归档；或你主动归档）	默认不显示，-l N 里有计数
deleted	标记删除	默认不显示（软删，数据仍在）
dedup	你确认「跨源重复」后隐藏（见跨源去重）	全渠道隐藏，--dedup list 可查、可撤销

关键机制：所有查询只读 Status='active'。所以把文章标成 archived/deleted/dedup，它就会自动从搜索、全文、摘要、计数里消失——不用改任何查询代码。

「版本」与「文章」的关系（Guid + Version）

• 一篇文章的唯一标识是 Guid（来自 RSS 的 id 或链接）。
• 作者改内容 → sip 把旧版标 archived（记时间戳），插入新版本行（Version+1）。
• 所以「同一 Guid」可能有多个 Version 行 = 版本历史。用 --versions <id> 看，--diff 对比两版。
• HasHistory / VersionCount 表示这篇文章是否被改过（TUI 里标题带 ✎）。

侧车文件（Sidecar JSON）

主库之外，还有一堆 JSON 小文件，各管一件事（默认明文、开放、可读、可备份；挡位 3 加密后 dedup.json 等为密文，见安全）：

文件	作用
feed_health.json	来源健康：失败次数 / 上次成功时间
article_signals.json	文章标记：用户♥ / AI🤖
reading_progress.json	阅读进度（滚动位置）
sip_settings.json	应用设置：报告间隔、高频阈值、去重阈值
dedup.json	跨源去重规则（你确认的「忽略」）
source_policy.json	Source Policy（你确认的处理规则）
simon_events.json	孟思琳事件记录（数据库修复 / 拦截 / 挡位变更，最近 200 条）
templates.json	Onboarding 推荐源模板
telemetry.db	遥测独立库（默认关闭）
fulltext/	全文抓取缓存

2. 订阅与内容

订阅源（Feed / Source）

你订阅的 RSS/Atom 源。用 -d <url> 添加，-l 列出。sip 只从你订阅的源取内容——这就是「白名单」的本质：你选哪些源，AI 和你就只见哪些源的内容，这是个人信息库的「收集」环。

归档（Archive）——注意两种「归档」

• 源的归档（-a）：给源标题加 _时间戳 后缀，表示「不再更新这个源」。再 -una 去归档。会跟其它操作区分，防止误当新源。
• 文章的归档：作者改版时旧版被自动归档；Status='archived'。

更新调度（Schedule）

每个源可设一条更新计划，到期才自动拉取（--schedule <id> <expr>）：

• 间隔：30m / 1h / 6h / 1d / 7d / 30d
• 固定时刻：daily@HH:mm、weekly@Ddd HH:mm
• manual 或空：不自动更新
• 到期判断：now >= 上次拉取 + 间隔；--sync 只更新到期的源。

3. 阅读

全文抓取（Fulltext）

RSS 摘要常常太短。--fulltext <id> 抓取原文存到 fulltext/<id>.md 本地缓存，--show 时优先用全文。抓取有同意流程 + SSRF 防护（只抓 http/https，拒绝回环/私网）。

今日哈汤 / 今日变化摘要（--today）

• 今日推荐：规则式选文（近 48h 新增 / 被作者更新 / 全文质量 / ♥🤖 加权），一天固定一碗。
• 今日变化摘要（顶部）：每个源各新增多少、⚠ 高频源（腹泻式更新）单独折叠、被作者改过带改动概览（标题改没改 / 增删行数 / 约±字数，纯 diff 计数、零 LLM）、⚠ 可能同文（跨源重复）。

阅读进度（Reading Progress）

reading_progress.json 记录每篇文章的滚动位置。重开文章按 Space 可跳回上次位置（TUI 行为；AI 用 --show --json 读取不受影响）。

4. AI 与语义

ai_config.json

AI 配置（模型名、端点、维度）。API Key 存在操作系统凭据库（不是配置文件）。--init 交互式配置，--config 查看。

向量与语义搜索（Embedding / Vectors）

• 文章标题/内容被转成向量存 Vectors 表（--index 向量化，--reindex 换模型后重来）。
• --search "query" 用向量相似度找「意思相近但字面不同」的文章（--threshold 控制底线）。
• 换 embedding 模型后维度可能变，需 --reindex。

LLM 摘要（Summary）

--summary <id> 让 LLM 生成摘要存进 Items.Summary（带 --json、退出码）。--summary feed:N / --summary-all 批量。

标记（Signals：♥ / 🤖）

--like <id> 用户点赞（♥），--like <id> --ai [理由] AI 判断（🤖），存 article_signals.json。出现在侧栏 / -l N / JSON 输出，供 --today 加权。

5. 决策与规则

阅读情况报告（Insights）——status 与 reasons

--insights 按源呈现阅读事实，不替你做决定：

• status（状态）：只反映技术故障——正常 / ⚠ 长期未更新 / ✗ 失败 N 次。
• activity（活跃度）：打开 / 读完 / 完成率 / 跳过 / ♥🤖 点赞——这是关于你的行为，低阅读 ≠ 低价值，绝不影响 status。
• reasons（事实原因）：可解释的事实列表（如「窗口内打开 0 篇」「完读率仅 30%」），没有黑盒评分、没有「建议退订」这类价值结论——判断留给你。

需遥测开启；AI 调用（摘要/搜索/嵌入）按文章/源归因，报告可按源统计。

Source Policy（--policy）

把「你的决定」存成 source_policy.json 并持续生效：lower_frequency（改更新频率）/ archive / tag（打标签）/ keep / unsubscribe。规则永远是你确认的（createdBy: user），AI 永不自动写。这是 sip「读 → 分析 → 调整输入 → 信息流变好」闭环的关键。

跨源去重（--dedup）

同一篇文章被多个源转发时，按段落重合度（零 LLM）识别「可能同文」→ 你看 diff 确认 → hide-cluster <代表Id> 隐藏整簇（或 hide <hiddenId> <canonicalId> 单篇），把重复篇标 Status='dedup'（数据保留）。v1.1.4 起检测输出重复簇（一组同文文章：代表 + 成员），再大的重复量也只出少量簇，无配对爆炸。dedup.json 记规则，--sync 导入时跳过（防卷土重来）；undo 可撤销。隐藏 ≠ 删除，非破坏可恢复。

白名单 / 黑名单（概念）

sip 的「白名单」= 你订阅的源本身就是白名单：AI 和阅读只碰这些源。更精细的域名/关键词过滤、黑名单见规划。

6. 遥测与隐私

苏暖泉（Sumenia）遥测

本地阅读遥测（事件层），默认关闭、仅本地、绝不自动上传。事件：article_open / progress / complete / skip / like、ai_call、consent_change、feed_change、search（记完整查询词，仅本机）。sip telemetry status/show/enable/disable/clear/export 管理。详见遥测。

Onboarding（--onboarding）

降低「第一次打开该加什么」的门槛：按领域列出推荐源，add <分类> <索引|all> 一键添加。templates.json 可编辑。

---

速查：这些命令各是干嘛的

命令	概念
-l / -l N	列出订阅源 / 某源文章
-d / -u / --sync / --update-all	加源 / 更新单个 / 更新到期 / 更新全部
--schedule <id> <expr>	设置某源更新频率
-a / -una / -r	归档源 / 去归档 / 删除源
--versions / --diff	版本历史 / 两版对比（--semantic 语义 diff）
--grep / --search	全文搜索 / 语义搜索
--fulltext	抓全文
--summary / --summary-all	LLM 摘要
--like / --likes	标记 ♥/🤖 / 查看标记
--today	今日推荐 + 变化摘要
--insights / --insights-interval	阅读报告 / 报告定时
--dedup	跨源去重（scan/hide-cluster/hide/list/undo）
--policy	Source Policy
--onboarding	推荐源模板
telemetry ...	遥测管理
--export / --export-opml / --import-opml	导出 / OPML