Anno for DeepSeek Harness (native)

In the DeepSeek Harness ecosystem, reviewing, editing, and annotating local HTML files usually requires MCP bridging or launching additional service processes. @philmingdao/anno-dsh-native provides a native solution: it integrates Anno’s core capabilities directly into the Harness process, removing middleware and subprocess overhead and enabling a lighter architecture.

This is a native DeepSeek Harness plugin for Anno, including an HTML review server, persistent session storage, and six model tools, without an MCP intermediary.

Core Features¶

In-process operation
The plugin runs inside the Harness process. The HTTP review server, disk session storage, and the registration logic for html_review_* tools are all completed within the same process. This avoids the extra overhead of MCP bridging and does not require managing a separate npx subprocess.

Session persistence
Review sessions are persisted by default under $ANNO_DATA_DIR/sessions (default ~/.anno/sessions). Source files are not overwritten, and generated output files are version-controlled (e.g., -reviewed.html, -reviewed-v2.html).

Model tools
The plugin registers six native model tools that the agent can invoke directly:
- html_review_start_session
- html_review_get_session
- html_review_claim_handoff
- html_review_mark_handoff_sent
- html_review_list_sessions
- html_review_register_final

System prompt integration
The plugin includes a tool:anno system prompt section that explicitly teaches the agent how to follow the “start -> review -> receive -> resolve” workflow.

Installation and Configuration¶

Installing this plugin requires DSH’s profile mechanism.

dsh plugin --profile web add @philmingdao/anno-dsh-native

After installation, the plugin applies cordis.patch.yml, inserting the anno-native line into the profile’s host plane. Start Harness as usual:

dsh web

All agents under the same profile share the same review server and session storage.

Configuration options

The anno-native line supports the following configuration:

Typical Usage¶

The interaction between the agent and the plugin follows this workflow:

1. Start a review
   The agent calls html_review_start_session, passing the absolute path to the source file. The plugin returns a loopback URL (127.0.0.1 + a temporary port), and Harness opens the URL in a browser.

2. User interaction and handoff
   After the user completes the review in the browser editor and clicks “Submit to Agent”, the plugin captures the agent that started the session and prepares the handoff data. The server pushes a normal follow-up turn message via agent.followup, containing the complete review content (text edits, formatting changes, annotations, etc.).

3. Agent resolution
   After receiving the message, the agent’s prompt instructs it to execute the following in order:
   - html_review_claim_handoff (persist the receipt acknowledgment)
   - html_review_get_session (reload the full session)
   - html_review_register_final (apply changes to the draft HTML and generate the final file)

Because the push is in-process, the agent can resolve the handoff immediately without manual polling.

Architecture and Dependencies¶

The plugin uses the Cordis plugin architecture, with the core divided into two parts:

• lib/anno-core.js: responsible for the HTTP server, disk storage, and handoff hooks. This module intentionally removes the dependency on DSH and can be unit tested directly.
• lib/index.js: serves as the Cordis binding layer, registering tools, injecting system prompts, starting the server, and handling the agent’s call context.

The package keeps zero external dependencies, uses Node.js’s native node:crypto module to construct messages, and does not depend on @deepseek-ai/dsh-tools.

Notes¶

Version requirements
- DeepSeek Harness version must be >=0.1.0-rc.6 <0.2.0.
- Node.js version must be 22 or newer.

Uninstall behavior
After running the uninstall command, existing review sessions under the data directory are retained. If the source agent is already offline, handoff data remains persisted on disk, and the agent can inspect and take over it through the regular html_review_* tools.

License
The plugin uses the MIT license. The fonts used by the editor UI follow the SIL Open Font License; see the main Anno repository for details.