plane-dsh-plugin

Readme

# plane-dsh-plugin

[简体中文](README.zh-CN.md)

[![CI](https://github.com/Bene-2020/plane-dsh-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/Bene-2020/plane-dsh-plugin/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

A native [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) plugin that quietly turns meaningful coding work into Plane project updates.

The plugin recognizes tasks, bugs, decisions, ideas, risks, milestones, plans, progress, and completions during an agent session. It writes events to a local SQLite outbox first, synchronizes them to [Plane](https://plane.so/) asynchronously, and exposes a global floating panel for inspecting and updating work items.

> [!NOTE]
> This project is an early release. The storage and synchronization paths are extensively tested, but DSH and its external plugin APIs are still evolving.

## Features

- DSH-native Cordis host and browser client plugin in one installable bundle.
- Eight agent tools for project discovery, binding, capture, and review.
- Durable local SQLite outbox with idempotency, retries, leases, and crash recovery.
- Asynchronous synchronization to Plane without blocking the main agent task.
- Incremental active-item context instead of repeating a full project snapshot every turn.
- Floating Plane-style panel with status filters, optimistic updates, and sync health.
- Manual project switcher for DSH's global overlay, including duplicate-name disambiguation and stale-response protection.
- Plane API keys resolved through DSH credentials and never written to the plugin database.

## Requirements

- Node.js 22.19 or newer.
- pnpm available on `PATH` for DSH plugin management.
- A recent `@deepseek-ai/dsh` release with external bundles, credentials, tools, client slots, and Typert remote support.
- A Plane workspace and API key.

## Install

Install the prebuilt npm package into DSH's Web profile:

```sh
npx @deepseek-ai/dsh plugin --profile web add plane-dsh-plugin
```

The npm package already contains the host and browser bundles. Installation does not build this repository or require an `allowBuilds` exception.

### From a local checkout

Use this path only when developing the plugin itself:

```sh
git clone https://github.com/Bene-2020/plane-dsh-plugin.git
cd plane-dsh-plugin
pnpm install --frozen-lockfile
pnpm build
npx @deepseek-ai/dsh plugin --profile web add .
```

## Configure

Store the Plane key in DSH credentials, never in `cordis.patch.yml`:

```yaml
# $DSH_HOME/.credentials.yaml
PLANE_API_KEY: "your-plane-api-key"
```

Then override the bundle row in `$DSH_HOME/profiles/web/cordis.patch.yml` with your workspace slug:

```yaml
- id: plane-dsh-plugin
  config:
    workspaceSlug: your-workspace-slug
    planeBaseUrl: https://api.plane.so
    planeMode: sdk
```

Start DSH with the same profile:

```sh
npx @deepseek-ai/dsh web
```

The agent will offer Plane project binding when it first encounters an unbound working directory. The panel appears as a floating button in the DSH web UI. See [Configuration](docs/configuration.md) for every option and troubleshooting guidance.

## How it works

```mermaid
flowchart LR
  A[DSH session events] --> B[Context and capture rules]
  B --> C[Local SQLite outbox]
  C --> D[Background worker]
  D --> E[Plane API]
  C --> F[Typert live RPC]
  F --> G[Global floating panel]
```

See [Architecture](docs/architecture.md) for the design rationale.

## Development

```sh
pnpm install --frozen-lockfile
pnpm test
pnpm run test:coverage
```

`pnpm test` builds the workspace and distributable bundle, validates the packed artifact, and runs the full test suite. Client coverage is held at 100% for statements, branches, functions, and lines.

Useful commands:

| Command | Purpose |
| --- | --- |
| `pnpm build` | Build internal packages and assemble the public bundle. |
| `pnpm test` | Build, verify the package contract, and run tests. |
| `pnpm run test:coverage` | Run the coverage gate. |
| `pnpm run pack:check` | Inspect the publishable tarball contract in a temporary directory. |

## Privacy and security

- Source code, terminal output, and full transcripts are not stored by the plugin.
- The Plane API key is resolved per operation through DSH credentials.
- Local project metadata and the outbox are stored in SQLite at `~/.dsh/plugins/ambient-project/ambient.sqlite` by default.
- Before reporting a vulnerability, read [SECURITY.md](SECURITY.md).

## Contributing

Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md) before opening a pull request.

## License

[MIT](LICENSE) © 2026 Wenyan Wei.