docs: 新增数据源标准流程(analyzer 打包→技能安装→登录→运行时注册→排程→强化)

docs/add-new-source.md

+# 新增数据源标准流程
+
+> 适用:news-hub-skills(技能仓)+ news-harvester-runtime(运行时仓)双仓协作的新机部署形态。
+> 以"给路透社再加一个 reuters-energy 栏目"或"新接入一个站点"为例,按本文从上到下执行即可。
+
+## 一、两仓分工与关键概念
+
+| | news-hub-skills | news-harvester-runtime |
+|---|---|---|
+| 职责 | 源的定义与采集能力:分析(analyzer)、配方(recipe)、登录配方、采集/摘要/推送脚本 | 采集编排:调度、排队、Provider/预算、重试、面板、邮件 |
+| 源相关文件 | `skills/news-harvester/bundles/<id>.nhsource.json`(安装包)、`helpers/<id>.md`(配方=YAML frontmatter)、`logins/<id>.json`(登录配方) | 部署态 conf 与调度(见下表,不进 git) |
+| 技能安装位置 | `~/.agents/skills` symlink 指向本仓 | 面板/脚本经 `platform_layer.py` 读写技能 |
+
+**源(source)与站点(site)**:源=一个栏目频道(`reuters-world`);站点=源名第一段(`reuters`)。
+同站多频道**共享**:一个浏览器实例(CDP 端口 `9300+hash(site)%200`)、一个 profile(`~/.news-harvester/profiles/<site>/`,登录 cookie 落这里)、一份登录凭据(`~/NewsHarvester/etc/news-harvester/logins/<site>.json`,600)。给已有站点加频道**不需要**重新配登录。
+
+**method**:`browser`(需配方,走 Chromium,可登录)或 `direct`(仅需 urlPattern 正则,免浏览器)。
+
+**各文件落位总表**:
+
+| 文件 | 位置 | 性质 |
+|---|---|---|
+| 安装包 `<id>.nhsource.json` | 技能仓 `skills/news-harvester/bundles/` | 入 git |
+| 采集配方 `<id>.md` | 技能仓 `skills/news-harvester/helpers/` | 入 git |
+| 登录配方 `<id>.json` | 技能仓 `skills/news-harvester/logins/` | 入 git |
+| 栏目 conf `<id>.conf` | `~/NewsHarvester/etc/news-harvester/` | 部署态 |
+| 站点凭据 `<site>.json` | 同上 `logins/` 子目录(600) | 部署态,保密 |
+| 入口脚本 | `~/NewsHarvester/agents/news-harvester-<id>.sh`(写死端口+profile) | 部署态 |
+| 调度 plist | `~/Library/LaunchAgents/com.newsharvester.<id>.plist` | 部署态 |
+| 排程意图 | `~/NewsHarvester/etc/news-harvester/schedule-plan.json`(frequencies/windows) | 部署态 |
+| 归档产物 | `~/NewsHub/<vaultFolder>/<YYYYMMDD>/`(bundle 的 vaultFolder 决定,如 `路透社/世界`) | Obsidian |
+
+## 二、标准流程(七步)
+
+### 1. 判定站点归属
+新源的 id 用小写连字符。第一段就是站点名:
+- 已有站点加频道(`reuters-energy`)→ 复用该站登录/浏览器/排队,只需第 2-5 步;
+- 新站点(`scmp-world`)→ 额外要做第 4 步的登录配置,站点实例/端口自动派生,无需手建。
+
+### 2. 分析网站,产出配方(analyzer 技能)
+```bash
+cd ~/news-hub-skills/skills/news-source-analyzer
+node scripts/inspect-source.js <列表页URL> --scroll 3 --write <id> --name "中文名"   # 生成配方草稿
+node scripts/preview.js --url <列表页URL> --recipe recipes/<id>.json --count 3 --full  # 只读预览
+node scripts/recipe-test.js <id> --url <homepageUrl>                                   # 回归校验
+```
+配方核心字段:`listSelector/linkSelector/urlPattern`(列表页与文章判定)、`bodySelectors/bodyMinChars/bodyMinParagraphs`(正文校验,反爬空壳页靠它拦截)、`scrollSteps/waitMs`。direct 源只需 `--pattern <regex>`。
+
+### 3. 打包并安装到 harvester
+```bash
+# analyzer 侧打包(browser 源;direct 用 --method direct --pattern)
+node scripts/pack.js --id <id> --name "中文名" --url <homepageUrl> \
+  --method browser --folder "<站点>/<频道>" --recipe recipes/<id>.json
+
+# harvester 侧安装(写入 config.json sources + helpers/)
+cd ~/news-hub-skills/skills/news-harvester
+node scripts/source-manage.js install bundles/<id>.nhsource.json
+node scripts/source-manage.js list          # 确认 enabled ✅
+```
+
+### 4. 登录配置(仅 browser 且需登录的站点;新站点才做)
+```bash
+# 凭据落部署态(600):~/NewsHarvester/etc/news-harvester/logins/<site>.json
+# 自动登录:面板 站点登录→发现登录流(生成 logins/<site>.json 步骤配方,自动登录用)
+# 反爬强(DataDome)站点:只写检测型配方(无 steps,防自动登录被墙),人工登录兜底:
+#   面板 站点登录→人工登录 打开实例窗口,人肉输入账号+过滑块,cookie 落 profile,自动检测记录
+# 验证:面板 站点登录→测试(或 platform.sh call nh_login_preflight <id>)
+```
+已有站点的同站频道跳过本步。
+
+### 5. 运行时注册(运行时仓)
+```bash
+cd ~/ZCodeProject/news-harvester-runtime
+./bin/add-source.sh <id> --provider <主Provider> --fallback-provider <备用>   # 时间不填=自动错峰
+# 等价入口:面板 添加栏目(表单同参数)。两者都产出:入口脚本+plist+可选 conf
+# 生成后 launchctl bootstrap 由 nh_schedule_write 完成;同站排队(按端口分锁)自动生效
+```
+按需覆盖 conf(`~/NewsHarvester/etc/news-harvester/<id>.conf`):`COUNT`(默认20)、`MAX_RUNTIME_MIN`(默认60)、`MAIL_ON_SUCCESS` 等。
+
+### 6. 排程意图 + 首跑验证
+- 面板 调度中心 → 该源 `✎ 排程`:频率(每日 1-6 次)+ 各次时段,保存自动按交付线/全局间隔重排;
+- 面板该源 `▶ 采集` 立即跑一次 → **最近抓取**页看文章标题与状态、`~/NewsHub/<folder>/<今日>/` 核对归档、源详情页看成本/日志;
+- 常见首跑问题:候选全"Not an article"=正文校验没过(回第 2 步调 bodySelectors)或撞反爬墙(回第 4 步人工登录)。
+
+### 7. 按需强化 + 提交推送
+- **反爬站点保温**:参照 `com.newsharvester.keepalive-reuters` 复制一份 plist(`bin/keepalive.sh <site>`,StartInterval 3600),维持 DataDome cookie 活性;
+- **Provider 策略**:默认 glm;墙敏感站点经验上 `PROVIDER=ccswitch-gpt FALLBACK_PROVIDER=glm`;
+- **提交**:技能仓提交 `bundles/<id>.nhsource.json + helpers/<id>.md (+ logins/<id>.json 配方)`;运行时仓只有代码变更才提交(conf/plist 是部署态,不随仓库走,换机按部署手册重建)。
+
+## 三、速查:一条命令的溯源
+
+`launchd plist → ~/NewsHarvester/agents/news-harvester-<id>.sh(注入端口/profile) → bin/harvest.sh(排队→登录预检→claude 会话[技能 recipe 抓取→finalize 摘要→push News Hub]→重试链→合并→报告/邮件→回收实例)`
+
+数据落点:归档+摘要 `~/NewsHub/<vaultFolder>/<YYYYMMDD>/`,推送状态 `.syncstate.json`,运行记录 `~/NewsHarvester/logs/<id>.*`,近 7 天去重 registry 同日目录 `registry.json`。