dsh-research-library

Readme

# dsh-research-library

面向 DeepSeek Harness 的原生研究文献库工作台，由 [Field Current](https://github.com/LKRCharon/field-current) 提供事实源。它不是一层提示词或单个 skill：宿主侧注册原生研究工具并保存会话关联快照，浏览器侧把工具结果渲染成文献卡片与常驻面板。

当前代码面向：

- Field Current `0.3.0+`
- `@deepseek-ai/dsh` `0.1.0-rc.6`
- Node.js `^22.19.0 || >=24.0.0`
- `pnpm` 已在 `PATH` 中（`dsh plugin` 安装流程需要）

## 能做什么

| DSH 工具 | 用途 |
|---|---|
| `field_current_search` | 从策展文献库按标题、作者、key 或 collection label 检索论文。 |
| `field_current_lookup` | 用标题向 DBLP / arXiv 做外部书目信息核验。 |
| `field_current_bib` | 按 keys 或 collection label 获取规范 BibTeX。 |
| `field_current_snapshot` | 把选中的条目与 BibTeX 保存成不可变的 DSH 本地研究快照，并关联当前 session。 |
| `field_current_snapshots` | 列出当前 session 最近的研究快照。 |

插件只允许调用 Field Current `/mcp` 暴露的 `lookup`、`entries`、`bib` 三个工具；不会把任意 MCP 工具透传给模型，也不调用通用 `/api/*` 路由。返回值在进入 DSH 前会按本地 schema 校验，额外工具被忽略，缺少所需工具或协议漂移时会失败关闭。

Web 端为五个原生工具提供紧凑的 tool card，并在输入区上方维护当前 session 的 Field Current 面板。面板只消费经过守卫的持久化 presentation metadata；论文标题、摘要、作者、机构与 BibTeX 都按不可信数据处理，不执行 HTML。

## 边界

对策展论文库而言，这条 MCP 能力面是只读的：没有导入、修改、删除、账户管理或任意 HTTP 写入工具。不过“只读”不等于运行过程零写入：

- `lookup` 可能更新 Field Current 的一次性外部来源缓存；
- 使用个人读取令牌时，Field Current 可能更新该令牌的 `last_used_at`；
- `field_current_snapshot` 会写入 DSH 自己的本地 storage domain，但不会修改 Field Current 的论文记录。

Field Current 的 key 是单实例主键，不应被当作跨实例永久标识；DOI / arXiv ID 更适合作为跨实例线索。collection label 也不是租户或权限边界。

## 准备 Field Current

启动一个 Field Current `0.3.0+` 实例，并确认 MCP 地址是 `/mcp`。本地默认地址为：

```text
http://127.0.0.1:8788/mcp
```

推荐在 Field Current 的账户面板创建仅含 `library:read` 权限的 `fcpat_...` 个人令牌。兼容部署也可使用独立的 `MCP_READ_TOKEN`。不要使用能够访问写路由的 `AUTH_TOKEN` 代替 MCP 读取令牌；Field Current 的 `/mcp` 不把它视为 MCP 凭据。

把读取令牌只放进进程环境，不要写进 DSH profile、`cordis.patch.yml`、命令行参数、日志或 Git：

```sh
read -rs FIELD_CURRENT_MCP_TOKEN
export FIELD_CURRENT_MCP_TOKEN
```

插件配置保存的是环境变量名 `FIELD_CURRENT_MCP_TOKEN`，启动时才读取其值。`dsh --dump-config` 因而不会因为插件默认配置而打印令牌。

## 安装

先检查前置：

```sh
node --version
pnpm --version
```

从 npm 包安装（先用 `npm view dsh-research-library@0.1.0 version` 核实该版本在当前 registry 可见）：

```sh
npx --yes @deepseek-ai/dsh@0.1.0-rc.6 \
  plugin --profile web add dsh-research-library@0.1.0
```

从已构建的本地 checkout 安装：

```sh
cd /absolute/path/to/dsh-research-library
pnpm install --frozen-lockfile
pnpm run check
npx --yes @deepseek-ai/dsh@0.1.0-rc.6 \
  plugin --profile web add "file:$PWD"
```

不要把一个尚未安装依赖、尚未构建的 checkout 当作发布包使用。安装后重启 `web` profile，并新开一个会话验证工具卡和 Field Current 面板。

本仓库不会仅凭 README 宣称 npm registry 已发布；请以 `npm view` 的实时结果为准。

## 配置

随包提供的 `cordis.patch.yml` 使用以下安全默认值：

| 配置 | 默认值 | 说明 |
|---|---:|---|
| `endpoint` | `http://127.0.0.1:8788/mcp` | Field Current Streamable HTTP MCP 地址。 |
| `tokenEnv` | `FIELD_CURRENT_MCP_TOKEN` | 保存环境变量名，不保存令牌。 |
| `timeoutMs` | `15000` | 单次 MCP 请求超时。 |
| `maxResponseBytes` | `2359296` | 单次 MCP structured result 的本地 UTF-8 上限；超限拒绝进入工具结果和会话日志。 |
| `maxSnapshots` | `500` | DSH 本地保留的快照上限。 |
| `maxSnapshotBytes` | `1048576` | 单个持久化快照的字节上限。 |
| `failOnStartupError` | `true` | 缺令牌、缺工具或连接失败时阻止误启动。 |
| `allowInsecureRemote` | `false` | 默认只允许 loopback 使用明文 HTTP；远端应使用 HTTPS。 |

如需连接远端 Field Current，在 `web` profile 中覆盖该服务的 `endpoint`；不要在 URL 中嵌入用户名、密码、令牌、query 或 fragment。仅在可信的隔离网络中才考虑开启 `allowInsecureRemote`。
各项同时在插件 schema 中设有同值默认值，因此 DSH 后置 patch 即使只覆盖一个字段，也不会丢失其余必需配置。

## 使用示例

可以直接让 DSH：

```text
在 Field Current 里找最近的 LLM watermark 论文，给我 5 篇并保留摘要。
```

```text
用 Field Current 核验 “Attention Is All You Need”，然后导出对应 BibTeX。
```

```text
把刚才选中的 key 保存成名为 related-work-baseline 的研究快照。
```

搜索分页中的 `count` 是本页返回数量，不是全库总数。作者机构是论文发表时的元数据证据，不应被解释为当前任职。书目信息来源证据也不等于论文主张已经得到事实核验。

## 开发与验证

```sh
pnpm install --frozen-lockfile
pnpm run check
```

`pnpm run check` 应覆盖类型检查、单元测试、宿主/客户端构建与发布包检查。CI 在 Node `22.19.0` 和 Node `24` 上分别用锁文件安装并执行同一检查。

发布前至少还应在干净的临时 DSH profile 中安装生成的 tarball，并连接临时 Field Current 实例验证：启动、三项 MCP 能力协商、五个 DSH 工具、session 快照重放以及浏览器 tool card / panel。

## 许可证

AGPL-3.0-only。详见 [LICENSE](./LICENSE)。