# plane-dsh-plugin

[English](README.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)

一个原生的 [DeepSeek Harness（DSH）](https://github.com/deepseek-ai/deepseek-harness) 插件，在不中断 Agent 主任务的前提下，把有项目价值的编码工作同步到 Plane。

插件会识别会话中的任务、Bug、决策、想法、风险、里程碑、计划、进展和完成事件，先可靠写入本地 SQLite Outbox，再异步同步到 [Plane](https://plane.so/)。DSH Web 中还会出现一个全局悬浮面板，用于查看项目状态和更新工作项。

> [!NOTE]
> 当前是早期版本。存储与同步链路已经经过完整测试，但 DSH 的外部插件 API 仍在快速演进。

## 主要功能

- 一个安装包同时提供 DSH Cordis host 插件和浏览器 client 插件。
- 8 个用于项目发现、绑定、事件记录和审计的 Agent 工具。
- 带幂等、重试、租约和崩溃恢复能力的本地 SQLite Outbox。
- 后台异步同步 Plane，不阻塞当前 Agent 工作。
- 增量注入活跃工作项，避免每回合重复完整项目快照。
- Plane 风格悬浮面板，支持状态筛选、乐观更新和同步健康展示。
- 面向 DSH 全局悬浮层的手动项目切换器，支持同名项目区分和过期响应隔离。
- Plane API Key 通过 DSH credentials 读取，不写入插件数据库。

## 环境要求

- Node.js 22.19 或更高版本。
- `PATH` 中可用的 pnpm，用于 DSH 插件管理。
- 支持外部 bundle、credentials、tools、client slots 和 Typert remote 的较新 `@deepseek-ai/dsh` 版本。
- 一个 Plane workspace 和 API Key。

## 安装

将预构建的 npm 包安装到 DSH Web profile：

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

该 npm 包已经包含 host 和浏览器 bundle。安装时不会构建本仓库，也不需要配置 `allowBuilds`。

### 从本地源码安装

仅在开发插件本身时使用这种方式：

```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 .
```

## 配置

把 Plane Key 放入 DSH credentials，不要写进 `cordis.patch.yml`：

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

然后在 `$DSH_HOME/profiles/web/cordis.patch.yml` 覆盖插件配置，填入自己的 workspace slug：

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

使用同一个 profile 启动 DSH：

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

当 Agent 首次进入尚未绑定的工作目录时，会询问要关联哪个 Plane 项目。DSH Web 中会出现悬浮按钮。全部配置项和排障方法见[配置文档](docs/configuration.md)。

## 工作原理

```mermaid
flowchart LR
  A[DSH 会话事件] --> B[上下文与采集规则]
  B --> C[本地 SQLite Outbox]
  C --> D[后台同步 Worker]
  D --> E[Plane API]
  C --> F[Typert live RPC]
  F --> G[全局悬浮面板]
```

详细设计见[架构文档](docs/architecture.md)。

## 开发

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

`pnpm test` 会构建 workspace 和公开 bundle、检查打包产物契约，并运行完整测试。Client 代码要求语句、分支、函数和行覆盖率全部达到 100%。

## 隐私与安全

- 插件不保存源码、终端输出或完整对话记录。
- Plane API Key 每次操作时从 DSH credentials 获取。
- 项目元数据和 Outbox 默认保存在 `~/.dsh/plugins/ambient-project/ambient.sqlite`。
- 报告安全问题前请阅读 [SECURITY.md](SECURITY.md)。

## 参与贡献

欢迎提交贡献。发起 Pull Request 前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 和[行为准则](CODE_OF_CONDUCT.md)。

## 许可证

[MIT](LICENSE) © 2026 Wenyan Wei。