@morehao/dsh-github-trending 0.0.1 → 0.1.2

package/CHANGELOG.md

@@ -1,6 +1,66 @@
 # Changelog
 
+## 0.1.2
+
+> 0.1.1 从未发布到 npm（tag 推上去后 CI 在 `npm ci` 就失败），0.1.2 是它的第一次真实发布。
+
+### 修复
+
+- lockfile 里 57 个 `resolved` 指向 `registry.npmmirror.com`，npm 11 在 CI 拒绝拉取（`EALLOWREMOTE`）；统一为 `registry.npmjs.org`，并加 `scripts/check-lockfile.mjs`（`npm run check` 会跑），把这类只在发版暴露的错误前移到 PR。
+
+### 发布链路
+
+- 新增 tag 触发的发布：`.github/workflows/release.yml`（OIDC Trusted Publishing，无 NPM_TOKEN）+ `scripts/ci-publish.sh`（版本守卫 / 幂等 / 失败回读后重试）+ `scripts/release-notes.mjs`（只投影注记 tag 正文）+ `docs/publishing.md`。
+- `check.yml` 在 PR/main 上跑 `npm run check` 与 AC 机械检查。
+
+## 0.1.1
+
+分发方式变更：核心二进制不再走 npm 平台分包，改为 **GitHub Release 下载 + sha256 校验 + 本地缓存**（2026-10-30 决策 B）。
+
+### 变更
+
+- **获取核心**：`TRENDING_DIGEST_CORE` / 设置里的 `corePath`（覆盖，仅排障）→ 缓存 `$DSH_HOME/github-trending/core/v<version>/` → 按 `os/arch` 下载 `trendradar_<goos>_<goarch>`，用同目录 `checksums.txt` 校验（流式写入 + 原子 rename + 0755），失败不留半个文件；缓存命中后完全离线。
+- **版本来源**：`package.json` 的 `dsh.core.{repo,version}`；`scripts/sync-contract.mjs --ref vX.Y.Z` 会同步写入，保证「契约来源 tag」与「下载的核心版本」是同一个值。
+- **新增配置**：`coreAutoDownload`（默认 `true`）；关掉后只报 `CORE_NOT_DOWNLOADED`，由设置页显式下载。
+- **设置页**：显示 Release 版本 / 资产名 / 缓存状态 / 下载 URL，并提供「下载核心 / 重新下载」按钮（`POST /core/download`）。
+- **新增错误码**：`CORE_NOT_DOWNLOADED`（未下载，附下载地址）、`CORE_CHECKSUM_MISMATCH`（校验失败且已丢弃）；`CORE_UNAVAILABLE` 现在覆盖 404（版本未发布）、网络失败与平台不在矩阵。
+- **移除**：`optionalDependencies` 里的 6 个 `@morehao/trendradar-core-*`（从未发布，安装时只是 6 次无效探测）。
+
+### 修复（实测 v0.1.0 Release 后发现）
+
+- Windows 资产名带 `.exe`（goreleaser `formats: [binary]` 保留后缀）：`assetName()` 按平台补后缀，避免 Windows 上下载 404。
+
+### 测试
+
+- 新增 `test/release.test.mjs`（命名映射 / 下载校验 / 缓存复用 / 篡改重下 / 校验失败无残留 / 404 提示 / force）与 `test/core-status.test.mjs`（未下载 / 已缓存 / 覆盖路径三种状态）。
+- AC 脚本 AC-P-11 判据改为「环境变量优先 / 未设走 Release」，全套 71 条测试、11 条 AC 机械检查通过。
+
+## 0.1.0
+
+首个可用版本：插件侧完整落地，内容仍全部由 `trendradar` 核心产出。
+
+### 新增
+
+- **核心客户端**：`TRENDING_DIGEST_CORE` → 平台包（`@morehao/trendradar-core-<os>-<cpu>`）定位；`version --json` 握手比对 `ipcSchema`/`digestSchema`；一次 `run` 一次性进程，120 s 超时、`SIGTERM`→`SIGKILL` 取消；stdout 单信封解析，同时兼容契约 `RunResult` 与核心当前 `run --json` 形状。
+- **密钥不落盘**：核心配置经 POSIX FIFO 传入（文件系统里不出现明文），Windows 退化为 0600 临时文件并立即删除；GitHub token 只走子进程环境；日志统一脱敏。
+- **契约快照**：`contract/` 随包分发（schema + fixtures + `CONTRACT.sha256` + `UPSTREAM.json`），`scripts/sync-contract.mjs --ref <sha>` 从核心仓库同步并校验 aggregate；`src/ipc.gen.ts` 由 schema 生成，`npm run check:contract` 校验两者。
+- **设置页**：内容来源与核心状态、模型（快速填充 + 连通性预检）、归档仓库、GitHub 认证、榜单范围、调度；从本机 CLI 一次性导入非敏感字段（密钥不导入）。
+- **快速填充**：读宿主 `listProviders`/`listConfigurableProviders`/`listModels` 与 `ctx.credentials.describe/resolve`，按三种凭据形态落到 `direct` / `proxy` / 手填。
+- **回环代理**：OAuth 类 provider 由插件在 `127.0.0.1` 起一次性 OpenAI 兼容端点，转发 `ctx.llm.stream`；随机端口 + 一次性 token，运行结束即关闭。
+- **运行页与侧栏卡片**：本次（运行/试跑/取消、9 步、最近结果、错误卡）与历史（最近 30 条）；侧栏卡片显示状态、下次运行、上次结果与一键运行。
+- **两个工具**：`trending_run`、`trending_history`（稳定对外名）。
+- **调度**：插件自己的 60 s tick，按 IANA 时区判当日、6 小时补跑、同日不重复。
+- **共存检测**：`PATH` 上的 `trendradar` 只提示不切换。
+- **错误码映射**：17 个核心码 + 插件码（`CORE_*`、`IPC_INVALID`、`MODEL_KEY_MISSING`、`GITHUB_AUTH`、`PUSH_FAILED` 等），带落点与「下一步」。
+- **locale**：`locale/zh.json` / `locale/en.json`（市场卡片标题与描述）。
+
+### 已知偏差
+
+- 核心暂未实现 stdin 信封，插件按其现有 `run --config <path> --json` 传参；`RunResult` 已兼容。
+- 宿主 `schedule` 是会话本地提醒，插件改用自有 tick 覆盖无人值守场景。
+- 平台包（`@morehao/trendradar-core-*`）尚未发布：缺失时明确报 `CORE_UNAVAILABLE`，不降级。
+- 版式只支持 `canonical`；`template` 字段映射留待二期。
+
 ## 0.0.1
 
 - 初始化包结构：TypeScript + tsup 构建、Cordis 插件入口、市场元数据。
-- 业务功能待实现（抓取、解析、中文摘要、写文件、分支与 PR、自动合并、调度、设置页）。

package/README.md

@@ -1,15 +1,17 @@
 # dsh-github-trending
 
-> GitHub 趋势日报插件：每天抓取 GitHub Trending，生成中文简介与当日总结，写进你自己的仓库，并自动提交与合并 PR。
+> GitHub 趋势日报的 **DSH 入口**：每天定时 spawn 本地 [`trendradar`](https://github.com/morehao/trendradar) 核心，抓取 Trending、生成中文简介与当日总结，提交到你自己的仓库并自动合并 PR。
 
-**状态：脚手架（0.0.1）。** 包结构、构建与发布链路已就绪，业务功能按设计文档分阶段实现。
+**状态：0.1.1。** 插件侧（配置、调度、核心调用、状态与界面、两个工具）已完成。核心二进制走 **GitHub Release**：首次运行按 `os/arch` 下载、用 `checksums.txt` 校验 sha256、缓存到插件数据目录，之后离线复用。核心仓库打 tag 出资产之前，运行会明确报 `CORE_NOT_DOWNLOADED` / `CORE_UNAVAILABLE` 并给出下载地址——不会写空文件，也不会退回旧内容。
 
 ## 它做什么
 
-- 每天定时抓取 `github.com/trending`（全语言 + 你指定的语言）
-- 用宿主已配置的模型生成每个仓库的中文简介与当日总结
-- 写入你指定的本地仓库，建 `trending/YYYY-MM-DD` 分支，提交、创建 PR 并按配置自动合并
-- 认证优先「打开网页输码」的 OAuth Device Flow，也支持 PAT 与本机 `gh` 凭据
+- 按你设定的时间（IANA 时区）每天跑一次；也可以在设置页或侧栏卡片点「立即运行」
+- 一次运行 = **spawn 一次本地核心**：抓取 → 模型总结 → 渲染 → commit → push → PR → 合并，全部由核心完成
+- 插件只负责：收集配置、调度、传配置与密钥、展示结果与错误、记录最近 30 次运行
+- 内容按核心产出的成品**原样**落地（canonical），插件不改写、不重排、不二次调用模型
+
+**它不做什么**：不抓 GitHub、不解析 HTML、不调模型（回环代理模式除外）、不渲染内容、不执行 git。这些只有核心一处实现，避免两份实现漂移。
 
 ## 安装
 
@@ -17,15 +19,119 @@
 dsh plugin --profile <profile> add @morehao/dsh-github-trending
 ```
 
-装完重启宿主。
+装完重启宿主，在「设置 → GitHub 趋势」或侧栏入口进入。
+
+## 三步上手
+
+1. **选仓库**：填本地 git 仓库的绝对路径（插件不替你 `git init`，不是仓库就报 `REPO_NOT_GIT`）。
+2. **填模型**：点「沿用 DSH 配置」从宿主 provider 目录里挑 provider 与模型；可导出密钥的直接传给核心，OAuth 类凭据走本机回环代理。
+3. **试跑一次**：「试跑（不提交）」只抓取与渲染，不写文件、不提交。
+
+## 它需要什么 / 它访问哪里 / 它不上传什么
+
+**需要什么**
+
+- DSH `0.2.1-rc.3` 以上（`engines.dsh`），Node.js ≥ 22.20
+- 一个本地 **git 仓库**（提交目标）与可写的远端
+- 模型：provider + 模型 ID + 密钥（或用宿主已配置的 provider；OAuth 类凭据不需要密钥）
+- Git 与 GitHub 凭据（PAT / Device Flow / 本机 `gh`），仅 push 与开 PR 需要
+- 核心二进制：首次运行从 `github.com/morehao/trendradar/releases` 下载（按 `os/arch`，sha256 校验后缓存）；之后离线复用。开发/排障时可用 `TRENDING_DIGEST_CORE`（或设置里的「核心路径」）指向一个可执行的 `trendradar`，此时完全不下载
+
+**访问哪里**
+
+- 本地核心进程（一次性的 `run` 子进程）
+- `github.com/morehao/trendradar/releases`：仅首次运行（或点「下载核心」）时下载二进制与其 `checksums.txt`；之后不再联网
+- 你配置的模型端点（由**核心**发起，插件不代发）
+- `api.github.com`（由**核心**发起 push/PR；插件本身不发 GitHub 请求）
+- 本机 `127.0.0.1` 上的临时回环代理（仅当宿主 provider 的凭据不可导出时，端口随机、一次性 token、运行结束即关闭）
+
+**不上传什么**
+
+- 不向作者控制的任何服务器发送数据；插件没有遥测、没有云端账号
+- 不读取、不上传与你配置无关的仓库内容；核心只在目标仓库里写 `output.dir` 下的文件
+- 密钥与 token 只经 `ctx.credentials` 解析、只经运行时通道交给核心：**不写配置文件、不进日志、不进 argv**
+
+## 配置
+
+设置写在 `$DSH_HOME/github-trending/settings.json`（0600），**不含任何密钥**。
+
+| 键 | 默认 | 说明 |
+|---|---|---|
+| `model.provider` | `deepseek` | `deepseek` / `openai-compatible`（以核心 `version --json` 的 `supportedProviders` 为准） |
+| `model.mode` | `direct` | `direct` = 密钥直传核心；`proxy` = 本机回环代理转发宿主模型 |
+| `model.baseURL` | 空 | 空则用 provider 默认端点；代理模式由插件注入 |
+| `model.model` | 空 | 必填，不设隐式默认 |
+| `model.apiKeyRef` | `TRENDING_MODEL_KEY` | 指向 `ctx.credentials` 的引用名 |
+| `model.temperature` / `maxTokens` | `0.2` / `2048` | 单次调用参数 |
+| `model.allowDegraded` | `true` | 模型失败时核心是否退回原文（会标记 degraded） |
+| `repo.path` | 空 | 本地仓库绝对路径，必填 |
+| `repo.baseBranch` / `remote` | `main` / `origin` | |
+| `repo.commitMode` | `branch` | `branch`（分支 + PR）/ `direct` |
+| `pr.enabled` / `autoMerge` / `titleTemplate` | `true` / `true` / `chore(trending): add {date} digest` | |
+| `github.authMode` | `device` | `device` / `pat` / `gh` |
+| `github.tokenRef` | `GITHUB_TOKEN` | `ctx.credentials` 引用名 |
+| `trending.since` / `languages` / `topN` | `daily` / `all,typescript,python,go,rust` / `25` | 实际支持范围由核心决定 |
+| `output.dir` | `trending` | 仓库内相对目录 |
+| `schedule.enabled` / `time` / `timezone` | `true` / `08:30:00` / `Asia/Shanghai` | 插件自己的 60 s tick 驱动 |
+| `corePath` | 空 | 等价于 `TRENDING_DIGEST_CORE`（仅开发/排障；设了就完全不下载） |
+| `coreAutoDownload` | `true` | 缓存缺失时是否自动下载核心；关掉后只报 `CORE_NOT_DOWNLOADED`，由你在设置页点「下载核心」 |
 
-## 开发
+## 两个工具
+
+| 工具 | 参数 | 返回 |
+|---|---|---|
+| `trending_run` | `{ dryRun?: boolean, date?: string }` | 结构化摘要：文件数、commit/分支、PR、内容哈希、错误码与下一步 |
+| `trending_history` | `{ limit?: number }` | 上次/下次运行、最近 N 条记录、核心版本、模型、未合并 PR |
+
+工具名是稳定对外接口：**只新增不改名**。
+
+## 错误码
+
+| 码 | 含义 | 下一步 |
+|---|---|---|
+| `CORE_NOT_DOWNLOADED` | 核心还没下载（缓存为空，且自动下载被关或尚未触发） | 设置页点「下载核心」，或指向可执行的 `trendradar` |
+| `CORE_CHECKSUM_MISMATCH` | 下载内容的 sha256 与 `checksums.txt` 不符（已被丢弃） | 重试；仍失败则手动下载放到缓存目录（代理可能改写内容） |
+| `CORE_UNAVAILABLE` | 下载失败 / 版本还没发布（404）/ 平台不在矩阵 / 覆盖路径无效 | 按提示里的 URL 与发布顺序处理 |
+| `CORE_INCOMPATIBLE` | 核心 `ipcSchema`/`digestSchema` 与插件不一致 | 升级插件（含平台包）到同一版本 |
+| `CORE_TIMEOUT` / `CORE_CANCELLED` | 超时 / 用户取消 | 不提交任何状态，也留不下半成品 |
+| `IPC_INVALID` | 核心 stdout 不是约定的结果信封 | 升级插件与核心 |
+| `MODEL_KEY_MISSING` / `MODEL_UNAUTHORIZED` / `MODEL_NOT_FOUND` / `MODEL_RATE_LIMITED` | 模型侧 | 设置页「模型」区红字 + 重新选择 |
+| `GIT_NOT_INSTALLED` / `REPO_NOT_GIT` / `REPO_DIRTY` | 本机 git / 仓库状态 | 装 git ≥ 2.30、换仓库、先提交改动 |
+| `GITHUB_AUTH` / `PUSH_FAILED` / `PR_FAILED` / `NOT_MERGEABLE` | 推送与 PR | 本地 commit 已保留，修好后重试即可复用 |
+| `FETCH_FAILED` / `FETCH_RATE_LIMITED` | 抓取 | 检查网络/代理或稍后重试 |
+
+核心只在 stderr 给出 `error: <CODE>: ...` 文本；插件优先取核心自己的码，取不到时按稳定文本特征归类，并在结果里标 `inferred: true`（界面会注明「错误码由插件推断」）。
+
+## 与本地 CLI 共存
+
+- 插件**永远使用自带的平台包**，不从 `PATH` 解析核心
+- 运行前探测 `PATH` 上的 `trendradar`，版本/协议不一致只**提示**，不切换、不接管它的 cron/launchd
+- 首次可在设置页「从本机 CLI 导入」一次性导入非敏感字段；**密钥不导入**
+- 别让两套定时同时开着：内容侧靠 `contentHash` 与 PR 复用兜底，模型消耗无法兜底
+
+## 已知偏差（0.1.1）
+
+1. **核心尚无 stdin 信封**：核心当前的 `run` 只接受 `--config <path> --json`，插件据此传配置；`ok/startedAt/error.code` 形状的 `RunResult` 已兼容，核心补上后插件无需改。
+2. **密钥传输**：POSIX 上配置经 **FIFO** 交给核心（文件系统里不出现明文）；Windows 无 FIFO，退化为 0600 临时文件并在读完后立即删除。
+3. **GitHub token** 经子进程环境变量传给核心（核心只认 `GITHUB_TOKEN`/`GH_TOKEN`）；不进 argv、不进配置、不进日志。
+4. **调度**用插件自己的 60 s tick（宿主 `schedule` 是会话本地提醒，覆盖不到无人值守场景）。
+5. **二进制改为下载**（2026-10-30 决策 B）：不再随包发 npm 平台分包。首次运行需要能访问 GitHub Release；断网环境请用 `TRENDING_DIGEST_CORE` 指向本地核心。核心版本由 `package.json` 的 `dsh.core.version` 固定（`sync-contract --ref vX.Y.Z` 会同步写入）。
+6. **核心尚未打 tag**：`trendradar` 仓库还没有 Release，因此当前下载会得到「还没有发布」的明确提示；打上 `v0.1.0` 后无需改插件。
+
+## 开发与发版
 
 ```bash
 npm install
-npm run build
+npm run check          # typecheck + 契约校验 + 构建 + 全部测试
+node scripts/ac/run.mjs # AC-P-01…13 的机械部分
 ```
 
+发版走 **tag 触发的 CI**（Trusted Publishing / OIDC，不需要 npm token）：合并 PR → 在 `main` 打注记 tag `vX.Y.Z` → CI 发 npm 并用注记正文建 Release。细节见 [docs/publishing.md](docs/publishing.md)。
+
+- 契约快照：`contract/`（schema + fixtures + `UPSTREAM.json`），由 `node scripts/sync-contract.mjs --ref <sha|vX.Y.Z>` 从核心仓库同步；ref 是 tag 时会同时把版本写进 `package.json` 的 `dsh.core.version`；`npm run check:contract` 校验哈希与生成类型
+- 核心下载与缓存：`src/core/release.ts`（`ensureCore`），缓存位置 `$DSH_HOME/github-trending/core/v<version>/`
+- 宿主半 `src/`（tsup → `lib/`），客户端半 `client/`（esbuild → `client.js`，`window.__ModuleLoader__.load`）
+
 ## 许可
 
 MIT