Polaris/integrations/deepseek-harness

一句话定位

这是一个把 Polaris 平台接入 DeepSeek Harness(DSH)的连接器插件。它一边把 Polaris 后端的 MCP 工具列表拉进 DSH,一边把 Polaris 上的助手技能以原生技能(而非 MCP 工具)的形式注入 DSH,并把每个技能声明的"允许工具"策略落到当前 DSH 回合里强制执行。

核心能力

• 通过 DSH 官方的 MCP 客户端连接 Polaris /mcp,把 Polaris 的工具(如 search_papers)以 mcp__polaris__* 命名空间注入 DSH 工具目录
• 作为原生技能提供者,定期拉取 Polaris 技能目录,把 Polaris 助手技能注册到 DSH 的原生技能系统中
• 注册 polaris_skill_resource 工具,按需读取技能声明的附件内容(只有被技能显式列出的路径才可读)
• 根据当前回合加载的 Polaris 技能,在工具层隐藏其 allowed-tools 白名单之外的 Polaris 工具,并对回合内后发现的工具执行守卫拦截
• 同一回合加载多个技能时,自动把它们的允许工具列表取交集,只收紧不放开
• 令牌失效(401/403)或被降权时,自动清空缓存并把 DSH 技能发现标记为无效,做到失败即关闭

技术实现

• 语言: TypeScript(ESM,tsconfig.json 构建输出到 dist/)
• 关键依赖: @deepseek-ai/dsh-mcp-client(官方 MCP 桥)、@deepseek-ai/schemastery(配置 schema)、zod(运行时数据结构校验)、@deepseek-ai/cordis(宿主注入)
• 架构模式: 双适配器 bundle。cordis.patch.yml 在启动时往宿主里插入两个 service:polaris-mcp(走官方 MCP 客户端)和 polaris-skills(本插件的原生 provider)。本插件再通过 Cordis 钩子(tools/post-execute、agent/pre-step、tools/change、agent/disposed、agent/error、agent/turn-stopping)追踪回合状态
• 入口文件: integrations/deepseek-harness/src/index.ts(apply(ctx, config) 是插件激活入口)

适用场景

已经部署了 Polaris 实例、并希望 DSH 既能调用 Polaris 暴露的 MCP 工具、又能利用 Polaris 上的助手技能统一管理团队提示词与触发规则的用户。它把技能当成 DSH 原生一等公民处理,避免技能被错位成 MCP 工具造成的重复注册问题;同时通过 allowed-tools 策略让单个技能可以声明自己的工具白名单,在保留 Polaris 工具的同时防止越权。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:ZJU-REAL/Polaris/integrations/deepseek-harness

配置项

环境变量由 cordis.patch.yml 在插件注入时读取,补丁行里也接受同名配置字段覆盖。

常见问题

Q: 安装后必须设置什么环境变量?

A: 至少 POLARIS_BASE_URL 和 POLARIS_DSH_TOKEN,否则插件会在构造客户端时因令牌为空直接抛错。如果走 dsh-full-v1 profile,后端账号还需要开通 Buddy 记忆,否则 remember 工具不会出现在发现列表里。

Q: 集成令牌的权限怎么给?

A: 用当前登录 JWT 调 POST /api/integration-tokens,选择 scopes。skills:read 用于发现和读取技能,mcp:read 用于连接 /mcp,mcp:write 用于打开写工具 profile。令牌明文只在创建响应里出现一次,Polaris 后端只存 SHA-256 摘要,所以丢失后必须重建。已创建令牌的 scopes 不能编辑,只能吊销重建。

Q: 怎么验证插件已经生效?

A: 在 DSH profile 启动前运行 dsh --profile web --dump-config,配置里应同时出现 polaris-mcp 和 polaris-skills 两行;启动后 DSH 的工具目录里应出现形如 mcp__polaris__search_papers 的工具,且 Polaris 后端的 skill_load 不会作为 MCP 工具出现(它由 DSH 原生 skill 工具承载)。

Q: 技能里的 allowed-tools 怎么写才对?

A: 必须是 Polaris 原始工具名(如 search_papers),不能写成 mcp__polaris__search_papers 这种 DSH 命名空间形式;多个 Polaris 技能在同一回合加载时,它们的允许列表会自动取交集,不会扩大工具集合,也不会限制非 Polaris 的 DSH 工具;allowed-tools: null 表示不施加额外限制。

Q: 令牌被吊销或账号降为只读会怎样?

A: 技能发现遇到 401 或 403 会立即清空已缓存的技能目录并把 DSH 的发现标记为失效,下一次请求若仍未恢复则直接拒绝;后端把账号降为只读后,即使令牌声明了写 scope,在 /mcp 上也会在下次请求时被拒,不只是浏览器会话受影响。

Q: allowedToolsMode 三种模式怎么选?

A: 默认 enforce 会从工具目录里隐藏违规 Polaris 工具,并在回合内对新发现的工具同步拦截;advisory 仅写日志不拦截,适合上线前排查;off 完全关闭策略,会把策略控制器整个关掉,适合在 Polaris 后端没声明任何策略时减少事件循环开销。

上手难度

进阶 — 需要先在 Polaris 后端准备数据库迁移和集成令牌,理解 DSH profile、cordis patch 与环境变量三者的关系,并能区分 enforce/advisory/off 三种策略强度才能避免误拦截。

已知问题与限制

• Polaris 后端必须应用迁移 8ff89f7fcdeb,否则技能相关接口不可用
• 集成令牌的 scopes 创建后不能编辑,只能 DELETE /api/integration-tokens/{id} 重建;serverName 必须与官方 MCP 客户端 row 一致,否则策略匹配会失败
• 技能附件路径在客户端会拒绝空段、"." 和 ".." 段(src/client.ts:84),防止未声明路径绕过校验重定向请求
• 当 Polaris 账号为只读时,即使令牌声明了 mcp:write 也会在 /mcp 上被拒绝;dsh-full-v1 中唯一写工具 remember 只在账号开启 Buddy 记忆后才会出现在发现与调用列表里
• 源码中没有 TODO / FIXME / HACK 注释,暂无显式标注的 bug

Autonomous, end-to-end AI research: from literature to a reviewed paper.
Powered by a long-running agent core that plans, executes, and self-verifies its own work, turning every task into a resumable, auditable, human-gated run.

English · 简体中文

---

Polaris runs the entire research lifecycle as a single web application: literature survey, idea generation, idea review, experiment building on real GPU servers, LaTeX paper writing, and paper review. It is built for a research lab, with multi-user access, RBAC, and invite-code registration, and it treats every long task as a Voyage: a persisted, resumable, human-gated agent run that can span hours or days without losing state.

[!NOTE] Polaris is not a chatbot wrapper. The heavy lifting (crawling, parsing, deduplication, metric parsing, citation matching) is deterministic code. LLMs are reserved for the judgement calls: scoring, synthesis, drafting, and review. This split keeps runs cheap, reproducible, and auditable.

Demo

A 2-minute tour of the platform: the six-stage pipeline, the Voyage agent core, a real experiment run, and PolarisBuddy.

https://github.com/user-attachments/assets/388972c1-7ffa-45f2-94c4-07f388379ba2

Try it live

A guest account on a running instance, for looking around: sign in at http://101.37.174.109:8080 with the username guest and the password zjuguest123.

The account is for demonstration only: it is read-only and cannot call any model. It reaches every screen, the admin views included, but nothing it does changes state — creating, editing, deleting and uploading are all refused, and no LLM call will run, whether from chat, compilation or the assistant. Lab members' details and the registration codes are hidden from it as well. It is there to show what the platform looks like, not to do work on it.

The research pipeline

Polaris models research as six stages. Each stage produces durable artifacts that the next stage consumes, and every hand-off can pause at a human approval gate.

flowchart LR
    L["Literature<br/>Research Wiki"]
    I["Idea<br/>Idea Forge"]
    R["Idea Review<br/>Elo debate"]
    X["Experiment<br/>GPU / SSH"]
    W["Paper Writing<br/>LaTeX"]
    V["Paper Review<br/>Citation check"]
    S(["Submission"])

    L --> I --> R
    R -->|promotion gate| X
    X --> W --> V
    V -->|submission gate| S

    classDef stage fill:#eaf1ff,stroke:#2f6bff,stroke-width:1px,color:#10233f;
    classDef gate fill:#fff3e0,stroke:#f59e0b,stroke-width:1px,color:#5b3b00;
    class L,I,R,X,W,V stage;
    class S gate;

The Voyage agent core

Research tasks are long-running by nature: a cold-start literature backfill takes hours, an experiment runs for days. Polaris's central abstraction is that every complex task is a Voyage: a resumable, auditable run driven by a persisted three-part loop.

[!IMPORTANT] A Voyage is backed by a persistent state machine (planning -> executing -> verifying -> ...). If a worker crashes mid-run, the Voyage resumes from its last checkpoint after a health check. Budgets are attached to the run and auto-pause it when exceeded; every plan, action, and verdict is retained and replayable in the UI.

Not every task needs the full cognitive loop. A shared Runtime shell (state machine, checkpointing, gates, budget, cancellation, event streaming) serves all task kinds, while the Brain (the full plan-execute-verify loop) activates only for open-ended kinds such as experiments. Predictable pipelines (wiki compile, idea review, paper drafting) run on fixed templates instead of being over-orchestrated.

Key features

• Research Wiki, "compile, don't retrieve." LLMs read papers and compile a persistent, cross-linked knowledge base up front, instead of doing on-demand RAG at query time. One wiki per paper, shared platform-wide. Research digests, and Obsidian vault sync with [[wikilinks]] and frontmatter.
• One content pool, four collections. Every paper is stored exactly once; direction libraries, topic shelves, personal libraries, and the daily feed are membership layers over that pool. Libraries are decoupled from topics (many-to-many), own their own inclusion config, and come with governance: curators, monthly budgets, duplicate merge, user-created libraries under admin approval, and a recycle bin that stays out of search.
• Daily arXiv feed. A lab-wide feed of each day's new papers, with likes and one-click collection into any library you can write to. It is also the single arXiv entry point: libraries sync from the pool instead of querying arXiv themselves, on an admin-configurable schedule.
• Idea Forge. Signal-driven gap analysis, four-axis scoring, semantic dedup, and a deep Research-Proposal builder with novelty double-checking against the library and external sources.
• Multi-agent and human review. Persona reviewer agents debate to an Elo ranking; humans join live and are injected into the agent context, not bolted on afterward.
• Experiment Lab over SSH. Agents write and run code on real GPU servers, iterate on metrics, and collect logs and figures, under gated remote writes, command allow/deny lists, full audit, and triple budget caps (total, per-run, concurrency). A run keeps a file-based memory across steps, repairs itself under a time budget, and pauses to ask you a question rather than dying; its console shows a task map and a terminal you can talk to while it runs.
• Paper Writer. Online multi-file LaTeX with collaborative CRDT editing and server-side tectonic compilation; agent drafting bound to real metrics and real citations, plus one-click reference refresh wired into the main TeX file.
• Paper Review with citation verification. Existence and support are checked per citation against the library, Semantic Scholar, and OpenAlex; numbers are fact-checked against the experiment record.
• PolarisBuddy, an in-app assistant. A global companion that rides along on every page: a Claude Code-style multi-turn tool loop (streamed over SSE, with tool cards and inline figures) over the same read-only tool layer, in chat, plan (research-only, propose before acting), and goal (loop toward an objective) modes. It runs the same Navigator / Helm / Sextant split as a Voyage, so its steps are verified rather than merely produced, and it can hand work to subagents. Its greeting is stitched from real SQL counts rather than the model, it searches every library you can see, and it carries page context and persistent per-user memory. It is off unless the account may call a model.
• Skills, in two layers. Agent behavior is packaged as data, not code. Voyage skills are versionable, composable guidance, rubric, persona, and workflow packs injected at named points into agent prompts, enabled globally, with a publish-approve-install-rate marketplace; each Voyage snapshots the skills it used for reproducibility. Agent skills take the SKILL.md shape with three-level progressive disclosure — a one-line description in the catalog, the body fetched by skill_load as a tool result, attachments read on demand — so the model decides what to load and the prompt prefix stays cacheable.
• MCP tool layer. A single registry of read-only tools (literature, knowledge, project state, manuscripts, external search) is exposed both internally to the agent loop and externally as an MCP server (Streamable HTTP and stdio) for Claude Code, Codex, and Cursor, with a self-check and try-it playground. Project-isolated and strictly read-only.
• Real-time everywhere. SSE for agent streaming and Voyage progress; WebSocket for review discussions, approval notifications, experiment log tracking, and collaborative editing.
• Multi-user and RBAC. JWT auth (fastapi-users), invite-code registration, role-based access, and per-call token/cost accounting attributed to user, project, and voyage. Library and paper views are counted into a 7-day heat list, so the lab can see what people are actually reading.
• LLM abstraction and model routing. All model calls go through one layer; a DB-backed routing table maps each research stage to a provider, a model, and a reasoning-effort level (cheap models for scoring, strong models for debate and drafting). Admins set the global routes and users may override their own. The built-in fake provider is structurally disabled in production — setting the flag by mistake cannot turn it on.

Tech stack

Desktop client

Polaris ships as a desktop app for macOS, Windows, and Linux. Download the installer from Releases — .dmg / .zip (macOS, universal), .exe / portable .zip (Windows), .AppImage / .deb (Linux), built by CI on every v* tag. The app checks for updates and applies them without a restart where it can.

The builds are neither signed nor notarized, so each platform needs to be told once that the app is safe to run: on macOS xattr -dr com.apple.quarantine /Applications/Polaris.app (or right-click → Open); on Windows choose More info → Run anyway past SmartScreen; on Linux the AppImage needs libnss3 libgtk-3-0 libasound2, and --no-sandbox under Ubuntu 24.04+ AppArmor. On first run the app asks for your lab's Polaris server address and validates it against /api/health; the server must whitelist the desktop origin, since the page is served from app://polaris and every request is cross-origin.

The Electron shell (src/desktop/) is a shell plus a small local process, not an offline build: Postgres, Redis, the worker, and all LLM calls stay on the remote server, and the renderer talks to it directly. To build it yourself:

make desktop-deps           # install the shell's dependencies (once)
make desktop-dev            # build the frontend and run the shell (app:// protocol)
make desktop-dist           # package an unsigned installer for the current platform

See docs/desktop.md for the process model, the IPC contract, and packaging notes.

Quick start

[!TIP] Docker Compose is the recommended way to run Polaris, in development and in production. It needs only Docker and Docker Compose installed, with no local Python, Node, or database. See docs/deployment.md for production deployment.

cp .env.example .env        # set provider keys and secrets
make dev                    # full stack via docker compose, hot reload

• Frontend: http://localhost:5173
• Backend API docs: http://localhost:8000/docs

Local development without Docker (falls back to SQLite):

make backend-dev            # venv + uvicorn on :8000
make frontend-dev           # npm install + vite dev on :5173

Common tasks:

make migrate                # alembic upgrade head
make test                   # backend pytest + frontend build
make lint                   # ruff check + tsc --noEmit

Docker deployment

Deploy from pre-built images on Docker Hub (tricktreat/polaris-{api,worker,frontend}, published by CI on every v* tag) — no local build needed:

cp .env.example .env        # set POLARIS_ENV=prod, POLARIS_IMAGE_TAG, secrets, and an LLM key
docker compose --env-file .env -f docker/docker-compose.yml pull
docker compose --env-file .env -f docker/docker-compose.yml up -d
docker compose -f docker/docker-compose.yml exec api alembic upgrade head   # required on first run

The frontend is served at http://<host>:8080. The worker container is required (it runs all long tasks), and the first-run migration is mandatory (Postgres tables are not auto-created). Pass --env-file .env so Compose reads POLARIS_IMAGE_TAG (default latest) / POLARIS_IMAGE_PREFIX (default tricktreat) from the repo-root .env.

For building locally instead, bind mounts, backups, and restricted networks, see docs/deployment.md.

Documentation

Full documentation lives in docs/:

• Getting started: install, configure, and run Polaris
• Architecture: system design and the Voyage agent core
• Concepts: the research pipeline, Voyage, skills, and MCP tools
• Deployment: production deployment with Docker Compose
• Desktop: the Electron shell — process model, IPC contract, and packaging
• Configuration: environment variables and settings
• Development: local workflow and conventions

Repository layout

src/
  backend/       FastAPI app (package: app) and ARQ worker (package: worker)
    app/
      api/         thin routers
      services/    business logic (ingest, wiki, ideas, review, experiments, manuscripts, ...)
      models/      SQLAlchemy models
      agents/voyage/  the Voyage engine (navigator, helm, sextant, tool loop, per-domain actions)
      core/        config, db, queue (ARQ), events (SSE), llm/ abstraction
      tools/, mcp/ read-only tool registry and the external MCP server
  frontend/      React + Vite (src/features/ has one folder per product area)
  desktop/       Electron shell that wraps the web bundle (macOS / Windows / Linux)
docker/          Dockerfiles and compose (base, dev override, prod overlay)
docs/            English project documentation

Design principles

• Strict layering. Thin routers call services; services hold the business logic and never import the web framework; models sit underneath.
• Deterministic vs. judgemental split. Deterministic work (crawling, parsing, dedup) is plain code or worker tasks; only judgement calls reach an LLM.
• One LLM boundary. All model calls go through a single abstraction layer, and model choice comes from a database routing table rather than being hard-coded.

See docs/architecture.md for the full design.

Contributing

See CONTRIBUTING.md. In short: one feature is one branch is one pull request, branched from the latest origin/main, with English conventional-commit messages, and main stays a read-only fast-forward mirror of origin/main.

License

Licensed under the Apache License, Version 2.0. See LICENSE for the full text.