# autodsh —— DeepSeek Harness 自动化任务插件

> ⚠️ **AI 开发声明**：本项目由 AI（DeepSeek Harness 编码智能体）辅助开发，
> 源码、注释与文档包含 AI 生成内容，并经过人工与多轮自动审查。发布者对本项目
> 的最终内容负责。

autodsh 是一款运行在 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
上的自动化任务插件。用户通过对话即可创建自动化任务；每个任务由
**触发器 + 自动化内容 + 结果通知** 三段式架构构成，统一由任务面板管理。

## 功能一览

| 能力 | 说明 |
| --- | --- |
| 持久化 | 任务与运行历史持久化到 `$DSH_HOME/storages/autodsh.json`（官方 storage-domain + JSON 后端，原子写） |
| 生命周期 | 插件随 DSH 启停；启用的任务随插件启动自动恢复调度 |
| 触发器 | 固定间隔循环（interval）、cron 定时（schedule）、条件触发（condition）、父子级触发（parent） |
| 执行隔离 | 每个任务独立 agent 会话 + 独立工作目录；父子任务默认继承父任务工作目录与运行上下文 |
| 运行统计 | 运行次数、总耗时、总 token、上次运行时间/耗时/状态/结果、调用过的插件与 skill |
| 结果通知 | record（通知日志）/ email（SMTP 邮件，支持附件）/ session（DSH-IM 社交软件桥接） |
| 权限管理 | 每任务权限预设：`workspace-write`（默认）或 `danger-full-access`（长期授权：全权限且免审批，无人值守稳定） |
| 对话控制 | 9 个 `autodsh_*` 模型工具：创建/修改/删除/列表/详情/运行/停止/历史/设置 |
| 自动学习 | 安装后注册 `autodsh-control` skill，模型自动掌握本插件的控制知识 |
| 任务面板 | Web 设置页内置任务面板（列表/详情/启停/运行/删除/历史 + 完整配置表单） |

## 架构

```
               ┌────────────────────────────────────────────┐
   对话/用户 ──▶│  autodsh（Host 半区，随 DSH 常驻）            │
               │                                            │
               │  autodsh_* 工具 ←→ 任务存储(storage-domain)  │
               │       │            ▲                       │
               │       ▼            │ 变更事件               │
               │  触发器引擎 ──▶ 任务执行器                    │
               │  (interval/     (独立 agent 会话 +           │
               │   cron/          工作目录、统计收集)          │
               │   condition/                                │
               │   parent)          │                        │
               │                    ▼                        │
               │              结果通知器（日志/邮件/IM）         │
               │       │                                    │
               │  autodsh-control skill（模型自动学习）         │
               └───────┼────────────────────────────────────┘
                       │ /autodsh/api（webServer 路由）
               ┌───────▼────────────────────────────────────┐
               │ 任务面板（Client 半区，Web 设置页）            │
               └────────────────────────────────────────────┘
```

详见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。

## 安装

> **版本要求**：DeepSeek Harness `>=0.1.2-rc.1`（dsh 0.1.2 线）+
> `@deepseek-ai/cordis ^4.0.2`。v0.2.0 **不兼容** 0.1.1 线，升级说明见
> [RELEASE_NOTES.md](RELEASE_NOTES.md)。

> **挂载名必须是完整包名**：DSH Desktop 2.0.6 / dsh 0.1.2-rc.1 起会校验
> loader 行的 specifier 与目标目录 `package.json` 的 `name` 完全一致。请把本包
> 装在 `node_modules/@juuuw/autodsh`，并以 `name: '@juuuw/autodsh'` 挂载。
> 旧布局（`node_modules/autodsh` + `name: 'autodsh'`）会让整个 DSH 启动失败：
> `dsh-plugin-desktop: profile package identity is invalid for autodsh`；
> `scripts/install-local.mjs` 会自动迁移旧布局。

### 方式一：本地开发安装（推荐先本地验证）

```sh
# 1. 在项目根目录构建
npm install
npm run build

# 2. 一键安装到目标 profile（复制产物 + 写入完整包名挂载行 + 迁移旧布局 + 备份 patch）
node scripts/install-local.mjs desktop
# 或 node scripts/install-local.mjs web

# 3. 重启 DSH 生效
```

不启动日常 profile 的启动冒烟测试（隔离 DSH_HOME）：

```sh
node scripts/verify-boot.mjs --app "<...>/DSH Desktop.exe"
# 打印插件自己的 boot.log，出现 "[ready] all ok" 即通过
```

手动方式（不适用安装脚本时）：

```sh
dsh plugin --profile web add link:<本仓库绝对路径>
# 在目标 profile 的 cordis.patch.yml 中加入挂载行
- insert:
    - id: autodsh
      name: '@juuuw/autodsh'
```

重启 DSH 后生效。数据落在 `$DSH_HOME/storages/autodsh.json`。

### 方式二：npm 官方源安装（已发布 npmjs.com）

包已发布到 npm 官方源，包名 `@juuuw/autodsh`：

```sh
# 1. 从默认 npm 源安装
npm install @juuuw/autodsh

# 2. 在 profile 的 cordis.patch.yml 中加入挂载行：
# - insert:
#     - id: autodsh
#       name: '@juuuw/autodsh'
```

> 备选源：`@juuwaii/autodsh` 亦发布在 GitHub Packages registry（需配置
> `@juuwaii:registry https://npm.pkg.github.com/` 与 PAT 认证）。

## 快速开始（对话）

安装并重启后，直接在对话中说：

- “创建一个自动化任务，每天早上 9 点检查我的项目依赖并总结”
- “每 2 小时抓取一次新闻摘要，发邮件给我”
- “当我的巡检任务失败时，自动重试一次”
- “列出所有任务”“停用任务 xxx”“立即运行任务 xxx”

模型会自动加载 `autodsh-control` 技能并使用 `autodsh_*` 工具完成操作。
也可以在 **设置 → Autodsh 任务面板** 中管理任务。

## 任务字段（任务面板可查看/修改的主要内容）

任务名、描述、启用开关、触发器（类型与参数）、任务内容（prompt）、关键参数
（含敏感参数打码）、工作目录、agent preset、**权限预设**、单次运行超时、
通知渠道与时机、邮件收件人、父任务关系、运行统计（上次运行时间/耗时/状态/结果、
总运行次数/总耗时/总 token、调用过的插件与 skill）、运行历史。

面板 **"编辑配置"** 表单支持：

- 任务名 / 描述 / 任务内容
- 触发器切换（interval 间隔毫秒，或 cron 表达式）
- 通知渠道勾选（record / email / session）与通知时机、邮件收件人
- **权限预设**（跟随默认 / `workspace-write` / `danger-full-access`）

## 权限管理（长期授权）

每个任务可通过 `permission` 字段声明权限预设（面板与 `autodsh_task_create/update`
工具均可配置）：

| 预设 | 沙箱 | 审批 | 适用场景 |
| --- | --- | --- | --- |
| `workspace-write` | 工作区 + 允许的临时目录 | ask（更宽操作需审批） | 默认；一般任务 |
| `danger-full-access` | 全文件访问 | never（免审批） | **无人值守长期任务**：全权限执行、不弹审批 |

权限在任务 agent 创建后通过 `permissionPresets.set` 应用（同时设置沙箱模式与
审批策略）。未知预设名仅警告、不阻断任务。

## 结果通知说明

- **record**：写入 `<数据根>/notifications.log`（JSONL），始终可用；
- **email**：SMTP 邮件。在 `autodsh_task_settings` 工具或设置中配置
  `smtp.host/port/secure/user/password/from`，任务上配置 `emailTo`；
  内置极简 SMTP 客户端（node:net/tls，零依赖），支持 465 直连 TLS 与
  587/25 STARTTLS、AUTH LOGIN/PLAIN、UTF-8 base64 正文，以及**结果文件附件**
  （multipart/mixed；单文件 10MB 以内自动附加，超限/不可读跳过）；
- **session**：把结果注入创建任务的会话。若该会话由
  [DSH-IM（@xmanrui/dsh-im）](https://github.com/xmanrui/dsh-im) 绑定在社交软件
  上，结果**随用户下一次互动送达**（DSH-IM 推送为消息驱动：仅入站消息回合的
  回复会被推送，无主动文本推送 API；QQ 渠道未实现文件消息）。需要**主动即时**
  通知时请使用 email 渠道。

## 触发器说明

- `interval`：固定间隔（毫秒），可选随机抖动；
- `schedule`：5 字段 cron（`分 时 日 月 周`，本地时区；日与周按标准 cron 语义
  组合——一方为通配时以另一方为准）；
- `condition`：上次运行状态 / 上次耗时比较 / 时间窗口（每窗口触发一次）；
- `parent`：父任务一次运行结束后，按 `success | failure | completion | always`
  触发子任务（可延迟），并把父任务本次结果注入子任务提示词。

## 开发与测试

```sh
npm install
npm run build        # 构建 Host（tsc）与 Client（tsc + rollup）
npm test             # 运行单元测试（node --test）
```

- 测试覆盖：cron 解析、文件存储（含原子更新/容量控制/历史清理）、触发器引擎
  （四类触发器）、通知器、SMTP 客户端（本地假服务器，含 multipart 附件）、
  任务执行器全链路编排、面板 API（含通知/权限字段）——共 45 个测试；
- 代码注释丰富（项目要求）；相对导入遵循 NodeNext `.js` 后缀约定。

## 需求对照（项目原始需求）

| 需求 | 实现 |
| --- | --- |
| 1 核心持久化 | storage-domain + JSON 后端，原子写；运行历史容量控制 |
| 2 随 DSH 启停 | Cordis 插件生命周期：apply 启动引擎、卸载清理全部资源 |
| 3 自动启动 | `enabled=true` 的任务随插件启动恢复调度（interval 以上次运行为基准） |
| 4 独立环境/父子继承 | 每任务独立会话 + 工作目录；子任务默认继承父任务工作目录与上下文 |
| 5 安装后自动学习 | `autodsh-control` skill（运行时注册，模型初始目录可见） |
| 6 任务面板信息 | 任务名/触发器/内容/关键参数/通知/权限/统计/插件与 skill/父子关系全部可查可改（工具 + 面板完整配置表单） |
| 7 多类型触发器 | interval / schedule（cron）/ condition / parent 四类 |
| 8 结果通知 | DSH-IM 桥接（session 通道，随互动送达）+ SMTP 邮件（含附件）+ 通知日志 |
| 9 AI 声明 | 本 README 与 LICENSE 顶部声明 |
| 10 保留开源信息 | 见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 与 [docs/OFFICIAL-REFERENCES.md](docs/OFFICIAL-REFERENCES.md) |

## 隐私与安全

- 提交到本仓库的代码**不含任何个人信息、密钥、token 或本机路径**；
  本地测试数据位于 `$DSH_HOME` 与 `.gitignore` 忽略的目录；
- 任务关键参数支持 `secret` 标记：在面板与模型工具展示时打码为 `******`；
- SMTP 密码等敏感配置保存在 `$DSH_HOME/settings.yaml`（DSH 默认 0600 权限），
  读取接口一律打码；
- 插件数据为本地明文存储，请勿存放高敏凭据；发布/分享任务配置前请自行清除。

## License

[MIT](LICENSE)