农大门户（cau-portal）

给中国农业大学学生用的 DeepSeek Harness（DSH）插件与数据管道：自动抓取学院/学校通知公告，AI 生成摘要/分类/重要度/截止日期，在 DSH 侧边栏面板浏览，并可在对话中直接查询（MCP 工具）。

本项目只开源工具本身：数据由每位使用者自己收集、自己保管，不作为工具服务的一部分。校内数据版权归学校所有，公开页面信息仅作个人学习使用（见文末免责声明）。

维护者：@ZBber-lab · 欢迎提 Issue / 建议

功能特性

• 面板：停靠在 DSH 官方右侧栏里的一个页面标签（入口在左侧栏底部，没有打开会话时置灰；要求 DSH ≥ 0.1.5-rc.2）。含 今日要览 / 要闻 / 我的事项（截止提醒）/ 栏目频道 / 关注与归档 / 数据管理 / 文章阅读（原文 + AI 摘要 + deadline 高亮 + 一键引用到对话）
• 栏目频道管理：设置里逐个来源开关首页显示（黑名单语义，新接入来源默认显示），关闭只是不显示、数据照抓
• 添加新来源：设置 → 智能与数据 → 栏目频道管理 → 「添加新来源」→ 填名称 + 网址 → 「添加到聊天框」，由对话里的 AI 用 tools/scraper/probe.mjs 探测站点结构并报告「能直接接 / 需写解析器 / 接不了」，你确认后才写进 sites.json
• 多种建站系统：sites.json 数据驱动，内置博达 boda（/col/col<栏目号>/index.html + dataproxy 翻页）、苏迪 sudy（/<栏目号>/list.htm + /<年>/<月日>/c<a>/page.htm）与校新闻网自研 news-custom 三类解析器；node tools/scraper/probe.mjs <网址> 可探测目标站（判定 CMS、列出可用栏目、给出现成的 sites.json 片段），因此也能接入其他院校/院系的公开栏目
• 对话查询：6 个 MCP 工具（最新通知 / 关键词检索 / 截止事项 / 站点目录 / 用量统计 / 文章详情），AI 可以直接在对话中回答"最近有什么通知""推免报名截止几号"
• AI 加工：DeepSeek 模型生成一句话摘要、分类（通知/新闻/讲座/竞赛/评奖/选课/学术）、重要度、截止日期（本地校验防幻觉）
• 数据自主：数据仓库可配置（owner/repo），完全由你掌控；令牌仅存本机（面板设置页写入后由插件与 MCP 共用）
• 定时管道：GitHub Actions 每 2 小时自动抓取 + AI 加工（无需电脑开机）

架构

┌─────────────┐   GitHub Contents API / 代理    ┌──────────────────┐
│  DSH 浏览器  │ ──────────────────────────────▶ │  你的数据仓库       │
│  侧边栏面板  │                                 │  data/           │
│  （插件）    │                                 │  ├ index.json     │
└──────┬──────┘                                 │  ├ feed/ 栏目列表  │
       │                                        │  ├ articles/ 全文  │
┌──────▼──────┐   MCP（stdio）                  │  └ usage.jsonl     │
│  对话查询    │ ──────────────────────────────▶ └──────────────────┘
│  mcp__cau__*│
└─────────────┘
        ▲
        │ 工具代码公开；数据各自收集
┌───────┴────────────────────────────────────────┐
│  爬虫管道 tools/scraper（本仓库，公开）           │
│  抓取 → AI 加工 → 提交到**你自己的**数据仓库       │
└────────────────────────────────────────────────┘

数据流：爬虫抓取公开网页 → AI 加工（DeepSeek API）→ 产物提交到你的数据仓库 data/ → 插件与 MCP 读取展示。数据仓库与你绑定，与工具代码解耦。

快速开始

前置要求

• DeepSeek Harness（DSH）官方桌面版（2026-09-29 起正式发布；老的 web / CLI 环境同样可用），版本 ≥ 0.1.5-rc.2（面板停靠在 DSH 官方右侧栏里，旧版本没有这个栏）
• Node.js 18+
• 一个 GitHub 账号与一个私有仓库（存放你的数据；见下）
• DeepSeek API Key（管道 AI 加工用；deepseek-v4-flash 等）

凭据与服务来源一览

| 需要什么 | 从哪获取 | 用途 | |---|---|---| | DeepSeek API Key | platform.deepseek.com → 注册/登录 → API Keys → 创建（账户需有余额） | 管道 AI 加工、面板按需摘要 | | GitHub 数据仓 | github.com/new → 新建 私有 仓 | 存放你的 data/ | | GitHub 细粒度令牌 | github.com/settings/personal-access-tokens → Fine-grained tokens → 选你的数据仓 → Contents: Read(+/Write) | 面板/MCP 读你的数据 | | cron-job.org（调度桥） | console.cron-job.org → 免费注册 → 新建 job | 定时触发抓取（免费私有仓的 schedule 被禁用，需外部触发） | | SMTP 邮箱授权码 | QQ：设置→账户→SMTP生成授权码；163：设置→POP3/SMTP/IMAP授权密码；Outlook：账户→安全→应用密码 | 每日邮件报告（可选） |

安全：这些 key/令牌只服务于你自己的数据与调度；除调度桥的令牌需填入 cron-job.org（第三方）外，其余凭据只存本机。

第 1 步：安装插件

桌面版（官方已发布，推荐这条）：在 DSH 侧边栏点「插件」→「添加插件」，把下面这段填进去：

github:ZBber-lab/cau-portal-open

装完一定要点「立即启用」 —— 直接关掉对话框＝已安装但未启用，侧边栏不会出现「农大门户」入口。

有 dsh 命令的环境（web / CLI；桌面版安装目录默认不提供这个命令，它打包在应用内部但没加进 PATH）：

dsh plugin --profile desktop add "github:ZBber-lab/cau-portal-open"   # 桌面版的 profile 是 desktop
dsh plugin --profile web add "github:ZBber-lab/cau-portal-open"       # 老的 web / CLI 环境

⚠️ profile 别填错：桌面版读 profiles/desktop，web/CLI 读 profiles/web。装错 profile 的症状是「显示安装成功，但界面上什么都不出现」。拿不准就先看现有插件装在哪个 profile —— ~/.dsh/profiles/<名字>/node_modules/ 下有 cau-portal 的那个就是（设了 DSH_HOME 的话把 ~/.dsh 换成它）。 ⚠️ 第三方插件暂不支持自动更新：升级要先在「插件」页卸载、再安装新版（直接再装一次不会覆盖旧版）。

（这是官方仓库；若你 fork 了自己的一份，把地址换成你自己的 github:你的用户名/仓库名。安装后侧边栏出现「农大门户」入口。）

第 2 步：准备数据仓库

1. 新建（或复用）一个 GitHub 仓库（建议私有），作为你的数据仓；
2. 在该仓库开通一个细粒度令牌：GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → 选「Only select repositories」→ 勾选你的数据仓 → Permissions → Contents: Read（如需面板「删除」功能再加 Read and write）；令牌只存本机（面板设置页写入后由插件与 MCP 共用）；
3. 仓库内建 data/ 目录（可先留空，管道会自动生成内容）。

第 3 步：配置插件

打开 DSH 侧边栏 →「设置」：

1. 数据源：把「数据仓库（owner/repo）」填成你的数据仓（如 yourname/cau-data）—— 填一次即可： 保存后面板会把它同步到本机共享存储（<profile>\cau-portal-store\config.json），对话里的 MCP 用同一个仓（v0.5.4 起不必再在配置文件里写 CAU_GITHUB_REPO）；
2. 令牌管理：登记第 2 步的令牌；
3. AI 加工 · 模型配置：选择管道/面板按需加工用的模型（独立配置槽，与主对话模型解耦）。

第 4 步：运行管道攒数据

管道代码在工具仓里，产物要写进你的数据仓 —— 所以两个仓都克隆到本地（工具仓只用来跑，数据仓才是你提交的地方）：

git clone https://github.com/ZBber-lab/cau-portal-open   # 工具（只读用）
git clone https://github.com/<你>/<数据仓>                 # 你的数据仓
cd cau-portal-open

# 抓取 + AI 加工：用 --data-dir 指定产物写进你的数据仓
node tools/scraper/crawl.mjs  --data-dir ../<数据仓>/data --pages 2 --articles 8
DEEPSEEK_API_KEY=sk-... node tools/scraper/enrich.mjs --data-dir ../<数据仓>/data --limit 8

Windows PowerShell 用户：$env:DEEPSEEK_API_KEY='sk-...'; node tools/scraper/enrich.mjs --data-dir ..\<数据仓>\data --limit 8（DEEPSEEK_API_KEY=... node ... 是 macOS/Linux 语法）。 为什么要 --data-dir：不加就会写进工具仓目录；指定后爬虫只写你自己的数据仓，工具仓保持干净，也不会误把数据提交到工具仓。

产物在 <数据仓>/data/：index.json（目录与统计）/ feed/<site>__<column>.json（栏目列表）/ articles/<sha1>.json（全文 + AI 元数据）/ usage.jsonl（用量账本）。然后在你的数据仓里提交：

cd ../<数据仓> && git add data && git commit -m "data: first crawl" && git push

插件即可读到数据（面板会自动刷新）。

第 5 步：定时自动抓取（可选）

只把一个文件复制到你自己的数据仓库：.github/workflows/crawl.yml，再配置仓库 Secret DEEPSEEK_API_KEY（AI 加工用；缺省时抓取照常、AI 加工跳过）。

这个 workflow 会先 checkout 你的数据仓，再临时把公开的工具仓取到 .cau-tools/ 跑爬虫，用 --data-dir ./data 把产物写回你的数据仓。因此：

• 你的数据仓里只有 data/，不含任何工具代码 —— 数据始终由你自己保管；
• 工具永远是最新版：不需要你手动复制/同步 tools/，工具升级你自动跟上；
• 想自定义站点/栏目：把你的 sites.json 放在数据仓根，并在 workflow 的两条命令里各加 --sites ./sites.json（爬虫本来就支持这个参数；不加就用工具仓里的默认配置）。

本 workflow 用 workflow_dispatch（手动触发）而非原生 schedule，因为 GitHub 免费私有仓的 schedule 触发器不生效。要实现「每 2 小时自动」，需用外部触发器调用 Actions 的 dispatch 接口，常用 cron-job.org（免费）：

1. 在数据仓建一个尽量最小权限的细粒度令牌：仅选该数据仓，Permissions → Actions: Read & write；
2. 到 cron-job.org 新建一个 cron job：
   • Method：POST，URL：https://api.github.com/repos/<你的用户名>/<你的数据仓>/actions/workflows/crawl.yml/dispatches
   • Headers：Authorization: Bearer <第 1 步的令牌>、Accept: application/vnd.github+json
   • Body：{"ref":"main"}
3. 设执行频率（如每 2 小时），保存即可。

安全提醒：该调度令牌只用于触发，请只授予 Actions: Read & write 一个最小权限，且不要写进任何仓库或共享给他人。

第 6 步：接入对话查询（MCP，推荐）

想让 AI 直接在对话里查询（如最近有什么通知、推免报名截止几号），需把 MCP 服务器接入 DSH：

1. 安装 MCP 依赖（一次性）：

   cd tools/mcp && pnpm install
   

2. 注册 MCP client：在 DSH profile 的 cordis.patch.yml 里加（@deepseek-ai/dsh-mcp-client 是 DSH 内置插件；<...> 换成你的实际路径）。路径按你那套选——桌面版：C:\Users\<你>\.dsh\profiles\desktop\cordis.patch.yml（macOS/Linux：~/.dsh/profiles/desktop/cordis.patch.yml）；web / CLI：…\.dsh\profiles\web\cordis.patch.yml；若你设了 DSH_HOME，主目录就是它而不是 ~/.dsh：

   - id: mcp-cau
     name: '@deepseek-ai/dsh-mcp-client'
     serverName: cau
     transport: stdio
     command: <Node 可执行文件路径，如 D:\nodejs1\node.exe>
     args: [<本仓库路径>\tools\mcp\index.mjs]
     cwd: <本仓库路径>\tools\mcp
     env:
       # 数据仓名**不必写在这里**（v0.5.4 起 MCP 直接读面板「设置 → 数据源」写下的那份）；
       # 只想临时换仓时才用这行覆盖：
       # CAU_GITHUB_REPO: <你的数据仓，owner/repo>
       # 若你设了 DSH_HOME（数据目录不在 ~/.dsh），这行必须带上，否则 MCP 找不到令牌：
       # DSH_HOME: <你的 DSH 主目录>
   

   数据仓名不用在这里再写一次（v0.5.4 起）：MCP 每次调用现读本机共享存储里的 <profile>\cau-portal-store\config.json —— 也就是面板「设置 → 数据源」填的那一份，改完不必重启 DSH。 CAU_GITHUB_REPO 仅在想临时覆盖时使用（优先级最高）。 不需要在配置里写令牌 —— MCP 服务器会自动读面板设置页写下的那份（见下）。 （如果你确实想用环境变量覆盖，加 env: { CAU_GITHUB_TOKEN: <令牌> } 即可，它的优先级最高。）
3. 把令牌填进面板：DSH 侧边栏 →「农大门户」→ 设置 → 令牌管理 → 粘贴你的数据仓令牌 → 保存。 保存时插件会把它写进本机共享存储（<profile>\cau-portal-store\token.json），MCP 与工具脚本都读这一份 —— 以后换令牌只改这里，不用再动配置文件、也不用重启 DSH。
4. 重启 DSH（桌面版：完全退出应用再打开；web/CLI：重启 dsh web），对话里即可使用 mcp__cau__* 工具（共 6 个：最新通知 / 检索 / 截止事项 / 站点目录 / 用量统计 / 文章详情）。

说明：令牌是共用的 —— 面板设置页是唯一入口，MCP 与工具脚本都读那一份。 数据仓库名也只需要写一次（v0.5.4 起）：面板「设置 → 数据源」保存后写入 <profile>\cau-portal-store\config.json， MCP 每次调用现读它（5 秒缓存，改完不用重启 DSH）。想让 MCP 暂时用别的仓，再用 CAU_GITHUB_REPO 覆盖。 自查办法：对话里调一次 mcp__cau__list_sites，返回的 data_source 应显示 github:<你的数据仓>@main；若显示成别的仓、或报 404，就是数据仓没配对 —— MCP 的报错里会直接写出它当前正在用哪个仓。 没配数据仓时：MCP 不会再静默去读别人的仓，而是明确提示「请先配置数据仓库（面板 设置 → 数据源）」。 找不到令牌时 MCP 会退回本地 data/ 目录，不会静默失败：启动日志里会写明当前用的是 GitHub 还是本地。

第 7 步：每日邮件报告（可选）

设置 → 通知与关注 → 每日邮件报告：

1. 填 发件邮箱（如 123456@qq.com）与 邮箱授权码 —— 是授权码，不是邮箱登录密码（QQ/163/Outlook 等常见服务商会被自动识别，SMTP 参数免手填）；
2. 收件邮箱留空＝发给自己（与发件邮箱相同）；
3. 可选改 发送时间（本机时间，默认 08:00）；
4. 先点 测试发送，确认收件箱（含垃圾箱）收到了，再打开「启用每日邮件报告」—— ⚠️ 没填发件邮箱与授权码时无法启用（界面会提示）。

发什么：今日高重要通知 + 3 天内截止 + 命中关注规则 + 昨日回顾。若发送时间已过才开机，会自动补发。授权码只存本机（仓库外），不上传、不进日志、不显示。

面板怎么用

面板是 DSH 官方右侧栏里的一个页面标签（入口在左侧栏底部，没有打开会话时置灰）。视图状态按会话各记一份（切走再切回来还停在你上次看的那一页），不跨会话跟随。

| 页面 | 说明 | |---|---| | 今日要览（打开面板第一眼） | 高重要新进 · 3 天内截止 · 关注规则命中（显示「命中关注 N」）；下方是「我的事项」精选大卡与「栏目频道」入口 | | 我的事项 | 人工精选的截止事项大卡（带原文链接，含已过期）。可 「+ 自定义事项」 直接记要办的事，也可在「全部待办」或文章页点「我的事项」精选进来 | | 要闻 | 按 AI 判定的高/中重要 + 近 7 天自动汇集，分三栏：校内平台（统一门户）/ 校内其他 / 校外来源（分组由 sites.json 的 group 决定，缺省＝校内其他）。顶部搜索匹配 标题/来源/栏目/AI 摘要，空格分隔的多关键词需全部命中，三栏一起搜（不影响未读计数）。带 沙漏 标记的是「发布已超 7 天、但截止日期还没到」的临期通知 —— 它们在分组内置顶，不会因为变旧而消失 | | 全部待办 | 所有未过期的截止事项，按截止日升序；顶部可切「剩余 7 / 30 / 90 天 / 全部」。搜索是严格口径：只在你当前选的时间范围里匹配（想放宽就把范围切成「全部」）。每行可「我的事项」精选或「归档」，归档后在首页「归档 N」入口找回（也可取消归档） | | 栏目频道 | 按来源浏览各栏目（点进某个学院/栏目看全部条目）；未读点标未读。某个来源被关掉时这里会引导你去「设置 → 智能与数据 → 栏目频道管理」重新打开（数据一直都在） | | 关注 | 文章页点「加入关注」进来的内容，不设上限 | | 数据管理 | 按【起始日期 ~ 终止日期】筛选（留空＝不限）+ 搜索标题/链接，然后批量删除：本地立即隐藏，云端在下一轮抓取（≤2 小时）后真正删除，不可恢复；关注中的文章本地缓存仍可读，但云端删除后「我的事项」的原文链接会失效。需要令牌有 Contents: Read and write，否则提交不了删除 | | 文章页 | 原文 + AI 摘要 + deadline 高亮 + 「引用到对话」+ 「加入关注」/「我的事项」 |

面板底栏：左侧圆点 + 时间显示云端数据新鲜度 —— 超过 4 小时变黄、超过 24 小时变红；悬停能看到原因（例如「可能上一轮抓取失败或定时任务没触发」）。面板开着时「已 N 小时」会自己往前走。正常每 2 小时一轮。

设置页

设置首页是三组卡片（智能与数据 / 通知与关注 / 面板行为），顶部有提醒条（红＝基本需求没满足，黄＝提醒）。功能卡（AI / 数据源 / 待办 / 引用协同 / 邮件）在首页就有总开关；凭据卡（令牌 / 门户账号，淡底）没有开关，只显示状态。

| 子页 | 说明 | |---|---| | AI 加工 · 模型配置 | 独立配置槽（与主对话模型互不影响）：面板按需加工（摘要/分类/重要度/deadline）与后续监控都用它；含用量柱状图（7/30/90 天，次数 / token / 费用可切换）。换模型只影响之后的加工，数据不需要重爬 | | 令牌管理 | 多枚令牌登记：值 / 过期日 / 剩余天数 / 逐枚启用开关 / 「管理」跳 GitHub 令牌页。保存后自动同步到本机共享存储（<profile>\cau-portal-store\token.json）—— MCP 与每日邮件报告都读这一份。停用全部令牌＝面板无数据（顶部红条提醒） | | 面板偏好 · 引用协同 | 「自动附加阅读上下文」「引用到对话」「面板固定」三个开关 | | 待办提醒 · 关注 | ① 首页待办卡总开关；② 关注规则：关键词（必填）+ 来源 + 重要度下限（不限 / 高或中 / 只要高），多规则取并集，命中的条目在首页「今日要览」标出（规则存本机浏览器）；③ 系统通知：页面开着时（不必打开面板）每 10 分钟检查一次，命中关注规则或新增高重要通知就弹系统通知 —— 首次要先点「请求通知授权」 | | 数据源 | 数据仓库（owner/repo，支持完整 GitHub 链接与 .git 后缀）+ 「GitHub 云端」总开关 + 连通性检查；读写都用「令牌管理」里那枚令牌。填一次即可：保存后同步到 <profile>\cau-portal-store\config.json，对话里的 MCP 用同一个仓（改完不用重启 DSH）。留空＝未配置（顶部红条提醒，MCP 也会提示先配置）。另有一个「统一门户」开关（开源版不提供该来源，见上方说明） | | 栏目频道管理 | 逐个来源开关首页「栏目频道 / 要闻 / 今日要览」的显示，黑名单语义（新接入的来源默认显示）。关掉只是不显示 —— 数据照抓、AI 照加工，待办 / 关注 / 归档 / 对话查询都不受影响，重新打开立刻恢复。每个来源还有「编辑」：本机名称 / 标签（归到 校内平台 / 校内其他 / 校外来源）/ 主题色（只替换该来源页面里原本是品牌绿的部分：AI 摘要条、未读点、选中标签、按钮…）—— 三项都只存本机、立即生效、不动数据仓、不需要写权限，可「还原默认」。旁边是「添加新来源」 | | 每日邮件报告 | 见第 7 步 | | 统一门户 · 账号 | 开源版不可用（统一门户需要登录校园门户，属凭据/数据源范畴） |

安全与隐私

• 令牌 / API Key / 邮箱授权码：只存在本机（浏览器 localStorage / 本地工具目录），不进仓库、不进日志、不经过任何第三方服务；
• 数据仓库完全由你掌控，可随时停更或删除；
• 插件代码不含任何凭据与个人数据；
• 本仓库为纯工具代码开源：不含任何校园系统的登录自动化、不内置任何账号/凭据，仅在 sites.json 中面向公开页面进行抓取。

版权说明

• 本仓库为开源版，不使用中国农业大学官方校徽、校名题字等学校标识素材：界面徽标采用中性「CAU」文本、题字采用系统宋体文字，仓库内不包含任何官方校徽/校名文件。
• 本项目抓取的数据来源于各学校/单位公开网页，版权归原作者/单位所有；本项目不