dsh-social-trace 0.1.0 → 0.1.1

package/README.md

@@ -1,38 +1,108 @@
-# dsh-Social Trace
+# Social Trace
 
-DeepSeek Harness 的本地社交动态监控插件，支持微博和雪球。
+**把你在微博、雪球关注的博主说过的话，完整留在本地。**
 
-## 功能
+Social Trace 是 DeepSeek Harness 的本地社交动态监控插件。它按博主持续检查新动态，把正文、转发原文和配图归档到本机；有新内容时，可以通过 dsh-im 推送到 QQ / 微信。
 
-- 可视化监控流向，按平台、博主独立启停。
-- 定时检查新动态，按日期缓存历史消息，支持断点续传。
-- 按平台和博主保存正文、转发及图片，支持搜索和 Markdown / JSONL 导出。
-- 通过 dsh-im 向 QQ、微信等多个接收目标推送消息。
-- 内置版本检查；通过 npm 安装的插件支持一键更新。
+[![npm](https://img.shields.io/npm/v/dsh-social-trace.svg)](https://www.npmjs.com/package/dsh-social-trace)
+[![license](https://img.shields.io/npm/l/dsh-social-trace.svg)](LICENSE)
+
+## 为什么用它
+
+- **平台上的内容会消失。** 博主删帖、改口、设置半年可见，刷过去就找不到了。Social Trace 把看到的动态按博主留在本地，之后还能搜索、导出。
+- **不想每天手动刷主页。** 按博主设置检查频率和时间段，只在新动态出现时记录和提醒。
+- **不想把账号交给 AI。** 登录在插件自己的浏览器里完成，Cookie 不经过模型，资料库只落在本机。
+
+## 核心能力
+
+| 能力 | 说明 |
+| --- | --- |
+| 按博主监控 | 微博、雪球；每位博主独立开关、频率和时间段 |
+| 增量检查 | 定时读取新动态；关机/重启后补查期间仍可见的内容 |
+| 历史缓存 | 按日期范围回补旧动态，支持断点续传，不重复抓取 |
+| 完整留档 | 正文、转发原文、配图；按平台和博主 UID 分目录保存 |
+| 本地资料库 | SQLite + 按博主分目录的 Markdown；支持中文正文搜索 |
+| 导出 | 单博主 Markdown / JSONL，正文和来源一起带走 |
+| 可视化流向 | 博主 → 平台 → Social Trace → 资料库四层拓扑，状态、进度、异常一眼可见 |
+| dsh-im 推送 | 新动态原文推送到 QQ / 微信；支持多个接收目标；默认关闭 |
+| 本地优先 | 授权会话只存插件目录（0600），资料库不额外上传云端，不写进仓库 |
+
+## 它怎么工作
+
+1. **添加博主**：粘贴微博/雪球主页链接或数字 UID。
+2. **选择记录方式**：从现在开始，或按日期范围缓存历史消息。
+3. **交给它跑**：按设定频率检查；新内容入库后写 Markdown、下载配图；需要时通过 dsh-im 推送。
 
 ## 安装
 
-需要 DeepSeek Harness 桌面版、Google Chrome 和 Node.js 22.19 或以上。
+需要 DeepSeek Harness 桌面版、Google Chrome，以及 Node.js 22.19 或以上。
 
-在源码目录执行：
+从 npm 安装（也可以在 Harness 的插件管理里直接安装 `dsh-social-trace`）：
 
 ```sh
+dsh plugin --profile desktop add dsh-social-trace
+```
+
+也可以从源码安装：
+
+```sh
+git clone https://github.com/chiinsight/dsh-social-trace.git
+cd dsh-social-trace
 npm ci
 dsh plugin --profile desktop add .
 ```
 
-重新打开 Harness，在侧栏进入 Social Trace。
+安装后完全退出并重新打开 Harness，在侧栏打开 Social Trace。
+
+## 快速开始
+
+1. **选保存位置**：在「连接与设置」里选择资料库文件夹。
+2. **登录平台**：点「登录微博」/「登录雪球」，在独立浏览器窗口完成登录，回来点「我已登录，继续」。
+3. **添加博主**：粘贴主页或 UID，读取昵称/头像/总数，选择从现在记录或缓存历史。
+4. **调频率**：点大屏里的博主、平台或总控齿轮，设置检查频率、时间段和历史范围。
+5. **开推送（可选）**：先在 dsh-im 里连接机器人并创建接收目标，再到 Social Trace 的 dsh-im 节点添加渠道、选择博主范围、开启自动推送。
+
+## 通过 dsh-im 推送
+
+推送的是**新动态原文通知**，不是 AI 摘要：包含博主、发布时间、正文节选、转发引用和原文链接。
+
+- 默认关闭；安装、打开设置或选择目标都不会自动发送。
+- 只推送开启之后新采集的内容；历史缓存和此前已存内容不补发。
+- 支持多个接收目标（QQ、微信等），每个目标可单独开关；一个渠道失败不影响其他渠道。
+- 投递记录可查；失败或结果未知不会自动重发，避免重复打扰。
+- 机器人密钥由 dsh-im 管理，Social Trace 不重复保存。
+
+配置入口：大屏的 dsh-im 节点，或「连接与设置」里的消息推送区域。
+
+## 数据放在哪
+
+默认在 `~/.local/share/dsh-social-trace/`，也可以在设置里改到自己的文件夹。
+
+```text
+你选择的文件夹/
+  archive.sqlite       正文、任务、状态和消息
+  documents/
+    weibo/<UID>/       该博主的 Markdown 与配图
+    xueqiu/<UID>/
+```
+
+登录会话单独保存在插件目录，权限 0600，不进入仓库，也不会复制到资料文件夹。资料库不是加密数据库；需要更高保护时请把文件夹放在加密磁盘里。
 
-## 开始使用
+## 边界
 
-1. 在「连接与设置」选择信息保存位置，登录对应平台。
-2. 添加博主主页链接或 UID，选择从现在记录或缓存历史消息。
-3. 点击大屏节点齿轮，配置监控时间、频率及历史缓存范围。
-4. 如需推送，在 dsh-im 配好机器人和接收目标，再从大屏 dsh-im 节点添加渠道并开启推送。
+- 需要电脑唤醒且 Harness/插件在运行；关机期间不会采集，重开后补查仍可见的内容。
+- 已删除、被权限挡住或超出平台可见范围的内容无法补回。
+- 平台要求登录/验证时会暂停采集，处理后继续；不会绕过验证码、轮换账号或使用代理池。
+- 雪球文章只保存标题和原文链接，不保存文章正文。
+- 当前推送的是原文通知；AI 总结和 IM 内问答尚未接入。
 
-## 说明
+## 开发
 
-监控需要电脑唤醒且插件运行。重新启动后会补查期间仍可见的动态；已删除或无权访问的内容无法补存。平台要求登录或验证时会暂停采集，处理后可继续。雪球文章仅保存标题和原文链接。
+```sh
+npm ci
+npm test        # 244 项离线测试
+npm run test:ui # 5 项界面测试（需要 Chrome）
+```
 
 ## 许可
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-social-trace",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Social Trace：微博与雪球增量监控、可视化拓扑、历史缓存与本地检索",
   "type": "module",
   "license": "MIT",