amphilagus / dsh-literature

@amphilagus/dsh-literature

DeepSeek Harness 的文献检索与定向跟踪插件，配套 agent preset 文献跟踪助理。标准编码 Agent 默认不加载本工具集，只有选中该 preset 的会话才会启用。

能力范围：

• 检索：Crossref 远程搜索；本地查询只打已筛查入藏的全局新库。DOI 详情先查新库，未入藏再走 Crossref。
• 跟踪：按研究主题（可选 ISSN 白名单）或研究者（必须 ORCID）定期检索 Crossref 与 arXiv，人工分级后写入全局新库。
• 辅助：SCI 期刊目录（刊名、ISSN、影响因子、中科院分区）、跨会话研究者档案、会话本地的到期提醒。

不做全文抓取或翻译。提醒只在当前会话进程存活时触发；关闭期间不响，重开后补发逾期任务。

用法

在 文献跟踪助理 会话里直接说需求即可；agent 按下面三条路径选技能。

1. 搜索某主题最近的文章
   加载 literature-survey。literature_search 带主题关键词和 recentDays（近一周=7，近一月=30）。筛完用 tracking_curate 写入全局新库。不建跟踪方案、不排班。

2. 搜索某研究者
   加载 literature-survey。已有 ORCID 则 literature_search 带 orcid；只有姓名时先 researcher_profile_disambiguate，确认身份后再搜。同样可按 recentDays 限制窗口。筛完入全局新库。不建方案、不排班。

3. 对研究者或主题持续跟踪，定时自动汇报
   加载 literature-tracking-setup：确认 topic / person →（person 先消歧建档）→ 主题可配 ISSN 白名单 → tracking_plan_add → schedule_create。
   到期后加载 literature-tracking-search：双源检索 → 人工分级 → 入全局新库 → tracking_log_complete 后汇报。默认周期提醒会自己反复触发。提醒只在本会话进程存活时响；关掉期间不触发，重开后补发逾期任务。

两件东西，分别安装

产物	是什么	装到哪
插件 @amphilagus/dsh-literature	host 平面 bundle：默认 enabled: false，不给任何会话注册工具	目标 profile（例如 web）的 dsh.profile.bundles
preset preset/	agent 平面组合：人设 + 把文献插件以 enabled: true 挂上 + 挂上 schedule	~/.dsh/.agent-presets/literature-tracking-assistant

只装插件、不装 preset：工具全部关闭，picker 里也没有「文献跟踪助理」。只装 preset、不装插件：preset 里的 @amphilagus/dsh-literature 行解析失败，会话起不来。

技能不用单独放置。 literature-survey、literature-tracking-setup 和 literature-tracking-search 是插件在 enabled: true 时用 ctx.skills.register 注册的运行时技能，不是 ~/.dsh/skills 里的文件。不要把它们拷进 skills 目录。选中本 preset 后，agent 用自带的 skill 工具加载即可。

部署

下面默认 profile 名为 web，DSH home 为 ~/.dsh（若设了 DSH_HOME 则换成那个目录）。web profile 关了 HMR，每一步装完都要重启 dsh --profile web 才生效。

1. 安装文献插件

先构建，再链进 profile：

cd dsh-literature
pnpm install
pnpm run build
./scripts/install-profile.sh web

或：

dsh plugin --profile web add "link:/绝对路径/dsh-literature"

这会把包写进 profile 的 package.json，并因本仓库声明了 dsh.bundle.patch 而加入 dsh.profile.bundles。host 上的那一行是空壳（enabled: false），标准 / PM / 浏览器等 preset 仍然没有文献工具。

2. 安装 schedule 包（仍须在 profile 的 node_modules 里）

@deepseek-ai/dsh-schedule 不在默认 web 组合里。文献 bundle 会插入一行 disabled: true 的 schedule（Loader 不 apply，标准模式没有 schedule_*）。preset 里再写一行不带 disabled 的 schedule，只有文献跟踪助理会真正挂上工具。

包本身还是要装进 profile 的 node_modules（disabled 不会替你装依赖），否则 preset 那一行解析失败：

dsh plugin --profile web add "link:/绝对路径/deepseek-harness/packages/schedule/schedule"

或：

dsh plugin --profile web add @deepseek-ai/dsh-schedule

不要在 profile 的 cordis.patch.yml 里再单独 insert 一行 schedule。host 上的那一行已经由本仓库的 cordis.patch.yml 插入。

3. 放置 preset

目录名就是 preset id，必须是 literature-tracking-assistant：

mkdir -p ~/.dsh/.agent-presets
cp -R preset ~/.dsh/.agent-presets/literature-tracking-assistant

应得到：

~/.dsh/.agent-presets/literature-tracking-assistant/preset.yml
~/.dsh/.agent-presets/literature-tracking-assistant/agent.cordis.yml

preset.yml 只是 picker 上的显示名「文献跟踪助理」。改人设、mailto、是否挂 schedule，编辑的是 拷过去之后 的 agent.cordis.yml，不是仓库里的源文件（除非你改完再重新拷）。

Web UI 的 agent-preset picker 应出现「文献跟踪助理」。已有会话不能中途换 preset，开一个新会话再选。

4. 重启并验收

dsh --profile web

1. 新建会话，选「文献跟踪助理」。
2. 应能看到 literature_search / literature_get / literature_db / tracking_* / researcher_profile_* / schedule_create / schedule_list / schedule_delete。
3. literature_db 的 action: journals 按刊名、ISSN 或学科（如「物理」）能返回目录里的刊。
4. skill 列表里应有 literature-survey、literature-tracking-setup、literature-tracking-search。
5. 另开一个标准模式会话：上述文献工具和 schedule 工具都不应出现。

数据落在哪

首次在文献跟踪助理会话里启用插件后：

$DSH_HOME/data/literature/literature.db      # 搜索缓存 + 全局新库 + 跟踪方案 / 档案 / 搜索记录
$DSH_HOME/data/literature/sci_journals.db    # 从本仓库 data/sci_journals.db 拷出的 SCI 目录

同一文件里两张文献表职责不同：papers 是远程搜索的过渡缓存（上限 2000 行，按 updated_at 淘汰），agent 本地查的是 library_papers（全局新库，主题和研究者筛完都进这里）。literature_db 的 import / search / get / delete 打新库；stats 同时报 libraryCount 和 cacheCount。

有 sandboxPolicy.grant 的 DSH 会把这个目录登记为额外可写根，bash/fs 才能碰 backup 和 export。没有 grant 的旧版 DSH 插件仍能加载，只是 shell 可能写不进去；文献工具本身不走 sandbox。

常用配置

文献插件配置写在 preset 那次重新挂载 上（host 空壳的 enabled: false 行改 mailto 不会传到本 agent）。编辑：

~/.dsh/.agent-presets/literature-tracking-assistant/agent.cordis.yml

- id: literature-search
  name: '@amphilagus/dsh-literature'
  config:
    enabled: true
    mailto: you@example.com    # Crossref polite pool，建议填
    # dbPath: ~/custom/literature.db
    # cacheRemote: true

键	默认	含义
enabled	host 上 false；本 preset 必须 true	主开关
mailto	空	Crossref 礼貌池邮箱
dbPath	$DSH_HOME/data/literature/literature.db	SQLite 路径（缓存 + 新库 + 方案）
cacheRemote	true	是否把远程命中写入搜索缓存（不是新库）
sciJournalsPath	包内 data/sci_journals.db	SCI 目录路径

改完 preset 文件后新开的会话才会用新组合；已在跑的会话保持启动时那一版。

跟踪流程

第 3 种用法的工具顺序：

1. literature-tracking-setup：定方向 → person 先消歧建档 → literature_db journals 挑 ISSN → tracking_plan_add。若返回 possible_duplicate，把该 kind 的现有名单给用户确认后再带 confirm=true 调一次 → schedule_create（默认 every）。
2. 提醒到期（或手动要求跑一次）时 literature-tracking-search：tracking_search → 人工分级 → tracking_curate（plan 只是来源备注）→ tracking_log_complete（status=done 才算完成）。默认 every 会自己反复触发，不要再 schedule_create。

schedule_create 的周期是 every_seconds（最小 300 秒），不是日历「每周一 9 点」。prompt 里写明要执行的方向名和技能名。删除方案只删搜索记录与排班，全局新库和研究者档案保留。

开发

pnpm install
bash scripts/link-dsh.sh   # 把 DSH checkout 里的 @deepseek-ai/* 链到本包
pnpm run typecheck
pnpm run test
pnpm run build

测试不访问网络。Crossref / arXiv 在单测里用 stub。

License

MIT