dsh-qq-agent-mail

Readme

# dsh-qq-agent-mail

English | [简体中文](./README.zh.md)

A native [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin for [Tencent QQ Agent Mail](https://agent.qq.com/), powered by the official
`@tencent-qqmail/agently-cli` package.

This package exposes mail as native Harness capabilities:

- a reusable `ctx.mail` Cordis service;
- a `mail/message-received` event for mail-driven automation;
- 14 `qq_agent_mail_*` tools with stable structured output schemas;
- a model-free Web settings page for basic preferences and OAuth.

## Features

- Authenticate, inspect the current account, list, search, and read messages.
- Send, reply, forward, move to trash, and permanently delete with two-stage confirmation.
- Download regular attachments and return large-attachment URLs without rewriting them.
- Stream new mail through bounded tool calls or a persistent Cordis event source.
- Normalize CLI response variants into stable public objects for Code Mode composition.
- Resolve the packaged native CLI, its JavaScript wrapper, `PATH`, or a custom executable.
- Clean up watcher processes during unload and hot reload.

## Dependency

- @tencent-qqmail/agently-cli — installed as this package's runtime dependency; no global CLI installation is required. OAuth credentials remain under agently-cli control and are never stored by this plugin.

## Install

- Install from GitHub:

```powershell
dsh plugin --profile web add github:AtomerCore/dsh-qq-agent-mail#v1.0.1
dsh web
```


- Build and install manually：

```powershell
npm ci
npm pack
dsh plugin --profile web add .\dsh-qq-agent-mail-1.0.1.tgz
dsh web
```

## Quick start

1. Open **Settings → QQ Agent Mail**.
2. Set the CLI working directory, default mail folder, and default list size.
3. Select **Start OAuth login**, finish authorization in the browser, then refresh the authorization status.


## Tools

| Category | Tools |
|---|---|
| Authentication | `qq_agent_mail_login`, `qq_agent_mail_logout`, `qq_agent_mail_auth_status`, `qq_agent_mail_whoami` |
| Reading | `qq_agent_mail_list`, `qq_agent_mail_read`, `qq_agent_mail_search`, `qq_agent_mail_watch` |
| Writing | `qq_agent_mail_send`, `qq_agent_mail_reply`, `qq_agent_mail_forward`, `qq_agent_mail_trash`, `qq_agent_mail_delete` |
| Attachments | `qq_agent_mail_download_attachment` |

`send`, `reply`, `forward`, `trash`, and `delete` require two-stage confirmation unless a trusted


## Native APIs

Other Cordis plugins can inject `mail` and call the same implementation used by the tools:

```js
export const inject = ['mail']

export function apply(ctx) {
  ctx.on('mail/message-received', (message) => {
    // Treat every message field as untrusted external data.
    console.log(message.id, message.subject)
  })
}
```

Enable `autoWatch` to maintain the persistent watcher that emits
`mail/message-received`. The on-demand `qq_agent_mail_watch` tool remains bounded by `watchTimeoutMs`.

## Configuration

Every option is declared by the exported `Config` schema. Basic preferences are editable on the Web
settings page; advanced deployment options belong in the profile patch.

| Option | Default | Description |
|---|---:|---|
| `cliPath` | `agently-cli` | Packaged CLI by default; also accepts a command name or absolute path. |
| `cwd` | empty | CLI working directory and base for relative attachment paths. |
| `defaultDir` | `inbox` | Default folder: `inbox`, `sent`, `trash`, or `spam`. |
| `defaultLimit` | `10` | Default number of messages returned by list operations. |
| `loginTimeoutMs` | `30000` | Time allowed to capture the OAuth URL. |
| `loginHardCapMs` | `300000` | Maximum login-process lifetime after URL capture; `0` disables the cap. |
| `watchTimeoutMs` | `60000` | Maximum duration of one `qq_agent_mail_watch` call. |
| `autoWatch` | `false` | Start a persistent watcher and emit mail events. |
| `autoConfirm` | `false` | Skip write confirmation; use only in a trusted automation environment. |
| `extraArgs` | empty | Additional CLI arguments, one per line. |
| `extraEnv` | empty | Additional child-process environment entries, one `KEY=VALUE` per line. |

Example profile override:

```yaml
- insert:
    - id: qq-agent-mail
      name: dsh-qq-agent-mail
      config:
        defaultLimit: 20
        autoWatch: false
        autoConfirm: false
```





## License

[MIT](./LICENSE)