# harmonyos-harness-plugins

**Repository Path**: codersth/harmonyos-harness-plugins

## Basic Information

- **Project Name**: harmonyos-harness-plugins
- **Description**: 鸿蒙harness插件集
- **Primary Language**: NodeJS
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-15
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HarmonyOS Harness Plugins

基于 [DeepSeek Harness](https://zoahdev.github.io/deepseek-harness-handbook/)(DSH)框架的插件项目,提供华为 AGC 报表每日拉取、DeepSeek 分析与邮件推送能力。

## 功能

| 工具 | 说明 |
|---|---|
| `huawei_report_analysis` | 拉取 AGC 报表 → DeepSeek 分析 → 生成日报(可选邮件发送),参数 `lookbackDays` / `reportDays` / `sendEmail` |

插件加载后自动挂载每日定时任务（默认北京时间 9:00 执行报表分析），报告生成后写入 `reports/daily/` 并自动发送到 `config.json` 中 `mail.to` 配置的邮箱。

## 运行效果

每日 9:00，日报自动推送到配置邮箱（手机端直接查看）：

![邮件日报：指标合计与数据变化分析](docs/images/blog-effect-1.jpg)

报告不只罗列数据，AI 会自动做问题诊断并给出结论：

![问题诊断：AI 自动指出转化链路问题](docs/images/blog-effect-2.jpg)

## 一、前置准备

| 工具 | 要求 |
|---|---|
| Node.js | `^22.19.0` 或 `>=24.0.0`(DSH 硬性要求,版本不足启动失败) |
| npm 镜像 | 项目 `.npmrc` 已固定 `https://registry.npmmirror.com`,无需额外配置 |
| DSH 宿主 | 插件依赖中**不含** DSH,需单独安装: |

```bash
npm install -g @deepseek-ai/dsh --registry=https://registry.npmmirror.com
dsh --version   # 验证安装
```

## 二、安装

```bash
git clone <仓库地址>
cd harmonyos-harness-plugins
npm install
```

## 三、配置文件(敏感,不入库)

`config/config.json` 与 `config/service-account.json` 均被 `.gitignore` 排除,新机器需手动创建。**禁止通过 git 提交传递。**

### config/config.json

```json
{
  "appId": "华为AGC应用ID",
  "appName": "应用名称",
  "scheduleHour": 9,
  "scheduleMinute": 0,
  "lookbackDays": 1,
  "reportDays": 7,
  "deepseekModel": "deepseek-chat",
  "deepseekApiKey": "",
  "mail": {
    "from": "你的QQ邮箱",
    "authCode": "QQ邮箱SMTP授权码",
    "to": "收件邮箱",
    "smtpHost": "smtp.qq.com",
    "smtpPort": 587
  }
}
```

| 字段 | 说明 |
|---|---|
| `appId` / `appName` | 华为 AGC 应用标识 |
| `scheduleHour` / `scheduleMinute` | 每日定时任务执行时间(北京时间) |
| `lookbackDays` / `reportDays` | 报表拉取范围 |
| `deepseekModel` | 分析所用模型 |
| `deepseekApiKey` | 可留空,留空时按下方三级回退链自动解析 |
| `mail.*` | QQ 邮箱 SMTP 配置（`authCode` 是邮箱授权码，非登录密码）；报告生成后自动发送至 `to` 邮箱 |

### config/service-account.json

华为 AGC 服务账号凭据,从 AGC 控制台创建 Service Account 后下载:

```json
{
  "project_id": "",
  "key_id": "",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "sub_account": "",
  "auth_uri": "https://oauth-login.cloud.huawei.com/oauth2/v3/authorize",
  "token_uri": "https://oauth-login.cloud.huawei.com/oauth2/v3/token",
  "auth_provider_cert_uri": "https://oauth-login.cloud.huawei.com/oauth2/v3/certs",
  "client_cert_uri": "https://oauth-login.cloud.huawei.com/oauth2/v3/x509?client_id="
}
```

### DeepSeek API Key(三级回退链)

插件按以下顺序解析,命中即止:

1. `config.json` 的 `deepseekApiKey` 字段
2. 环境变量 `DEEPSEEK_API_KEY`
3. `~/.dsh/.credentials.yaml` 中的 `refs.DEEPSEEK_API_KEY`(DSH 设置页粘贴保存后自动生成)

推荐方式:启动 DSH 后进入设置页粘贴 API Key(只写存储,不回显明文)。

## 四、启动

```bash
dsh web --patch ./cordis.yml
```

- `--patch ./cordis.yml` 把插件挂载进 DSH 的 `web` profile;`./index.js` 相对路径相对 cordis.yml 所在目录解析,任意位置 clone 均可运行
- 默认地址 `http://127.0.0.1:3080`,端口占用时 `dsh web --patch ./cordis.yml --port <端口>`
- 验证:启动后日志出现 `华为报表分析工具已注册` 即加载成功

### 云端访问 Web 界面

云端无桌面环境时，通过 SSH 端口转发在本机浏览器访问：

```bash
ssh -L 3080:127.0.0.1:3080 你的云主机
# 本机浏览器打开 http://127.0.0.1:3080
```

### 云端常驻部署（systemd）

定时任务依赖进程常驻，SSH 直接裸跑断开即挂。一键注册为 systemd 服务（开机自启 + 崩溃自动拉起），自动定位 dsh 与项目路径，无需修改：

```bash
sudo bash deploy-service.sh              # 安装并启动（默认 root 运行）
sudo bash deploy-service.sh zhanglei     # 指定运行用户（凭据读该用户 ~/.dsh）
sudo bash deploy-service.sh status       # 查看状态
journalctl -u dsh-report.service -f     # 实时日志
sudo bash deploy-service.sh uninstall    # 卸载
```

## 五、常见问题

### 1. `dsh: command not found`

全局包装到了 nvm 的 bin 目录,但 PATH 未包含。**不要安装 apt 建议的 `dsh`**(那是无关软件)。

```bash
# 确认是否已装上
ls /root/.nvm/versions/node/v24.21.0/bin/ | grep dsh

# 已装上 → 补 PATH
export PATH="/root/.nvm/versions/node/v24.21.0/bin:$PATH"
source ~/.bashrc

# 没装上 → 明确用 nvm 的 npm 重装
/root/.nvm/versions/node/v24.21.0/bin/npm install -g @deepseek-ai/dsh --registry=https://registry.npmmirror.com
```

注意:若系统同时存在 apt 的 node 与 nvm 的 node,`npm` / `node` 可能指向不同版本,导致全局包装乱位置,先 `which node && node -v` 确认。

### 2. `npm install` 卡住不动

- 加超时与重试参数:

```bash
npm install --fetch-timeout=300000 --fetch-retries=3 --fetch-retry-mintimeout=30000 --fetch-retry-maxtimeout=120000
```

- 仍卡住 → 清缓存重试:

```bash
npm cache clean --force
```

- 低配机器可降低并发:`--maxsockets=3`

### 3. 想看 npm 的 HTTPS 下载过程

```bash
npm install --loglevel http        # 打印每个包的下载 URL、状态码、耗时
npm install --loglevel verbose     # 显示完整安装阶段(定位卡点用)
```

注意 `--loglevel silly` 会打印请求头/响应体,使用带鉴权的私有源时会泄露 token,不建议。

### 4. 敏感文件误入 git

`config/config.json`、`config/service-account.json`、`reports/` 均被 `.gitignore` 排除。提交前务必确认:

```bash
git status --short   # 确认无敏感文件出现在待提交列表
```

## 目录结构

```
├── cordis.yml            # 插件清单(DSH --patch 入口)
├── index.js              # 插件入口(工具注册、定时任务)
├── lib/
│   ├── config.js         # 配置读取、API Key 三级回退
│   ├── auth.js           # 华为 OAuth 认证
│   ├── agc-reports.js    # AGC 报表拉取
│   ├── analyze.js        # DeepSeek 分析
│   ├── deepseek.js       # DeepSeek API 封装
│   ├── scheduler.js      # 每日定时任务
│   ├── mailer.js         # 邮件发送
│   └── csv.js            # 报表 CSV 处理
├── config/               # 敏感配置(不入库,手动创建)
└── package.json
```