# Gizwits Dingtalk Sync

> 机智云 BOLOLO 构建记录同步到钉钉多维表：拉 archives 接口、按版本拼接 APK 下载地址、 Webhook 推送到钉钉自动化、Windows 计划任务 09:00/15:00 定时跑。 Use when the user mentions 机智云同步、构建记录同步钉钉、apk_url、 gizwits_dingtalk、APP版本变更表、注册计划任务、测试某个版本同步。

- Skill: `lareina0011/gizwits-dingtalk-sync` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add lareina0011/gizwits-dingtalk-sync`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lareina0011/gizwits-dingtalk-sync/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: lareina0011 (https://skillmd.com/u/lareina0011)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/lareina0011/gizwits-dingtalk-sync

---


# 机智云 → 钉钉多维表同步

## 相关文件

| 文件 | 作用 |
|------|------|
| `gizwits_dingtalk_daily_sync.py` | 主同步：机智云 → Webhook →（可选）多维表贴图 |
| `register_daily_task.ps1` | 注册 Windows 计划任务 `GizwitsDingTalkDailySync` |
| `dingtalk_python_node.py` | 钉钉自动化 Python 节点（全量表） |
| `dingtalk_python_node_tice.py` | 钉钉 Python 节点（仅含「提测」的记录） |
| `dingtalk_notable_qr.py` | 开放平台上传草料 PNG 到「安卓二维码」列（需 AppKey） |
| `.env` / `.env.example` | Token、Webhook、开放平台配置 |
| `logs/sync_YYYYMMDD.log` | 运行日志 |
| `.sync_state.json` | 已推送 id（按 webhook 去重） |

## 数据流

```
机智云 archives API
  → 过滤 status=1、时间窗内、本地未推送
  → 拼接 apk_url（非接口字段）
  → POST 钉钉连接器 Webhook
  → 钉钉自动化：Python 解析 → 新增记录到多维表
```

## APK 下载地址规则

接口**不返回** `apk_url`，脚本本地拼接：

```
{GIZWITS_APK_BASE}/{version}-{archive_type}.apk
```

默认前缀：

`https://xbgroup-static.gizwits.com/applications/72c63478`

例：`2.1.42` + `release` →  
`https://xbgroup-static.gizwits.com/applications/72c63478/2.1.42-release.apk`

## Webhook 推送字段

POST 到钉钉连接器的 JSON（4 个字段）：

| 字段 | 说明 |
|------|------|
| `version` | 版本号，如 `2.1.42` |
| `archive_type` | 如 `release` |
| `update_content` | 原始备注 JSON 字符串 |
| `apk_url` | 上面规则拼好的下载地址 |

**没有** `qrcode_url`。多维表图片列不能直接写链接变二维码；要单元格内嵌图需开放平台（见 [reference.md](reference.md)）。

## 钉钉自动化配置要点

### 1. Webhook「接收到数据时」

- 关键词：`version`、`update_content`、`apk_url`
- 参数示例：

```json
{
  "version": "2.1.42",
  "update_content": "{\"remark\":\"[builder:master]更换探索板块资源\"}",
  "apk_url": "https://xbgroup-static.gizwits.com/applications/72c63478/2.1.42-release.apk"
}
```

### 2. Python 3.10 入参

| 变量名 | 映射 |
|--------|------|
| `version` | `1.接收到数据时 \| version` |
| `content` | `1.接收到数据时 \| update_content` |
| `apk_url` | `1.接收到数据时 \| apk_url` |

### 3. Python 出参（JSON）

| 字段 | 说明 |
|------|------|
| `version` | 版本号 |
| `environment` | `release`→测试环境，`master`→生产环境 |
| `update_text` | 去掉 `[builder:xxx]` 前缀后的文案 |
| `apk_url` | 下载地址透传 |

出参示例：

```json
{
  "version": "2.1.42",
  "environment": "生产环境",
  "update_text": "更换探索板块资源",
  "apk_url": "https://xbgroup-static.gizwits.com/applications/72c63478/2.1.42-release.apk"
}
```

### 4. 新增记录字段映射

- 版本号 ← `version`
- 软件环境 ← `environment`
- 更新内容 ← `update_text`
- 版本日期 ← 系统变量「今天」
- 安卓二维码 ← `apk_url`（文本/链接列；图片列需开放平台贴图）

完整 Python 节点代码见 `dingtalk_python_node.py`，直接粘贴到钉钉。

## 同步规则

- 仅 `status=1`（构建成功）才推送
- 默认时间窗：**昨天 09:00 ～ 现在**（`rolling_sync_window`）
- 本地 `.sync_state.json` 按 webhook 记录已推送 `id`，一天跑两次不重复
- 机智云 API：`packages/14535/archives?page_size=30&ordering=-id`

## 常用命令

```powershell
# 日常定时（计划任务调用，无参数）
py gizwits_dingtalk_daily_sync.py

# 试跑：只看会推什么
py gizwits_dingtalk_daily_sync.py --dry-run

# 测试：推今天 + 指定版本
py gizwits_dingtalk_daily_sync.py --today --version 2.1.42

# 强制再推（忽略已推送状态）
py gizwits_dingtalk_daily_sync.py --today --version 2.1.42 --include-pushed

# 注册/更新计划任务（每天 09:00、15:00）
powershell -ExecutionPolicy Bypass -File register_daily_task.ps1

# 立即触发计划任务
Start-ScheduledTask -TaskName GizwitsDingTalkDailySync

# 查看任务
Get-ScheduledTask -TaskName GizwitsDingTalkDailySync
```

## .env 必填项

复制 `.env.example` → `.env`：

| 变量 | 来源 |
|------|------|
| `GIZWITS_TOKEN` | 浏览器 F12 → archives 请求 → Authorization Bearer 后的 JWT |
| `GIZWITS_ORG_ID` | 默认 `15597` |
| `DINGTALK_WEBHOOK` / `_2` | 钉钉连接器 Webhook 地址 |
| `GIZWITS_APK_BASE` | CDN 前缀（见上） |

开放平台贴图（可选）：`DINGTALK_APP_KEY`、`DINGTALK_APP_SECRET`、`DINGTALK_OPERATOR_ID`、`DINGTALK_TABLE_URL`、`DINGTALK_SHEET`。详见 [reference.md](reference.md)。

## Agent 操作清单

用户要求测试/改定时/排查同步问题时：

1. 确认 `.env` 存在且 `GIZWITS_TOKEN`、Webhook 已填（勿把密钥贴到聊天）
2. 改定时 → 编辑 `register_daily_task.ps1` 后重新执行注册脚本
3. 测试单版本 → `--today --version X.Y.Z`；已推过则加 `--include-pushed`
4. 看 `logs/sync_YYYYMMDD.log` 和钉钉执行记录
5. `apk_url` 为空 → 检查 Webhook 关键词/参数示例/Python 入参是否映射 `apk_url`

## 附加说明

- 提测专用表用 `dingtalk_python_node_tice.py`（过滤「提测」，多返回 `skip`）
- 修改同步逻辑后**不必**重注册计划任务，除非改了 `register_daily_task.ps1` 本身
- 详细开放平台权限与 unionId 获取见 [reference.md](reference.md)