聚能推 开发文档

一个 API 连接微信服务号、邮件、短信等多渠道的消息推送平台。本文档面向开发者与 AI Agent，说明如何注册、获取令牌、调用接口完成消息推送。所有接口统一返回 {"code":200,"msg":"...","data":{...}} 结构。

快速开始（3 分钟对接）

# 发送一条微信消息（未绑定渠道时进入开发模式，消息仅打印到服务端控制台）
curl -X POST https://ddnt.com/api/push \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_API_TOKEN",
    "title": "服务器告警",
    "content": "CPU 使用率 99%，请及时处理！",
    "channel": "wechat"
  }'

如何获取 API 令牌

API 令牌用于调用消息推送接口（/api/push）。有两种获取方式：

方式一：控制台创建（推荐）

• 登录控制台 → 左侧导航「令牌管理」
• 输入令牌名称（如「服务器A」「监控脚本」），点击「新建令牌」
• 在列表中找到刚创建的令牌并复制；可创建多个令牌分别管理不同业务
• 令牌丢失或被滥用时，可在该页面删除（删除后立即失效）

方式二：接口创建

登录后调用（需携带 JWT）：

# 1. 登录获取 JWT
curl -X POST https://ddnt.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "YOUR_USERNAME", "password": "YOUR_PASSWORD"}'
# 返回: {"code":200,"data":{"token":"<JWT>","username":"..."}}

# 2. 用 JWT 创建 API 令牌
curl -X POST https://ddnt.com/api/tokens \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{"name": "服务器A"}'
# 返回: {"code":200,"data":{"token":"<API令牌>","name":"服务器A"}}

请求地址与鉴权

Base URL：https://ddnt.com（本地开发 http://localhost:3000）。所有接口默认使用 HTTPS。

推送 API

POST/api/push

发送一条消息，支持单发、一对多话题群发、多渠道同时投递。这是平台最核心的接口。

示例：向话题群发（微信 + 邮件）

curl -X POST https://ddnt.com/api/push \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_API_TOKEN",
    "title": "版本发布通知",
    "content": "v2.3.0 已上线，包含 12 项更新。",
    "channel": "wechat,email",
    "topic": "全体员工"
  }'

示例：指定手机号发短信

curl -X POST https://ddnt.com/api/push \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_API_TOKEN",
    "content": "您的验证码是 886512，5 分钟内有效。",
    "channel": "sms",
    "to": "13800138000"
  }'

响应

{ "code": 200, "msg": "推送成功",
  "data": { "recipients": 1, "channel": "wechat", "target": "oXXXX_xxxxxxxxxx" } }

话题订阅（一对多）

场景：一条消息推送给一群人。流程：创建话题 → 收集订阅者 → 向话题推送即群发。

令牌管理

以下接口需 JWT 鉴权。

消息日志

渠道绑定

绑定自有渠道后，推送将使用你的凭证发送（自有优先，未绑定则回落平台默认渠道）。

注册 / 登录

用户信息

套餐与余额

功能市场

知产服务

商标评估 / 商机查询按次扣费，结果自动推送到绑定的微信 / 邮箱 / 手机。

MQTT 订阅

物联网场景：设备通过 MQTT 发布消息 → 平台自动推送到你绑定的渠道（不占套餐配额）。需先在「功能市场」开通 MQTT 订阅。

设备发布消息格式

# 消息体（JSON）：title=标题, content=内容, channel=渠道(可逗号多选)
{ "title": "设备告警", "content": "温控器温度超限 42℃", "channel": "wechat,email" }

# 也可直接发纯文本，整段作为 content
# 客户端示例（mosquitto）：
mosquitto_pub -h YOUR_BROKER_HOST -p 1883 -u YOUR_DEVICE_USER -P YOUR_DEVICE_PASS \
  -t "jnt/你的主话题" -m '{"title":"设备告警","content":"温度超限","channel":"wechat"}'

AI 助手

平台内置 AI 对话（按 token 计费，余额兜底扣费）。

工单（帮助与反馈）

在控制台「帮助与反馈」提交问题，后台客服实时回复；支持文字与图片（单张 ≤2MB）。

运维工具箱（即时查询）

控制台「运维服务」内置一组开发者常用工具：Whois / DNS / SSL 证书 / TCP 拨测 / 端口扫描 / 备案查询。所有接口为登录会话鉴权（Cookie JWT），也可用 API Token 直调；目标为主域名或公网 IP（禁止内网地址，防 SSRF）。

持续监测与告警

把目标加入监测任务后，平台按间隔自动拨测；「下线」「恢复」状态变化时向你选择的渠道（微信 / 邮件 / 短信）推送告警。检测过程自动采样延迟，控制台可看近 24 小时延迟曲线（保留 7 天）。SSL 到期 / 备案变更 / DNS 变更监测同在「运维服务」分区管理。

服务器探针（Agent）

在你的服务器上运行零依赖 Agent（Node 18+，无需安装依赖），每 10 秒上报 CPU / 内存 / 磁盘 / 负载 / 网络流量；离线超过 3 分钟或超过自设阈值时自动推送告警。控制台可看实时占用与资源趋势图。

安装步骤

# 1. 控制台「运维服务 → 服务器探针」创建探针，拿到 token
# 2. 在被监控服务器上执行（命令可在控制台一键复制）：
curl -sL https://ddnt.com/probe-agent.js -o probe-agent.js && node probe-agent.js https://ddnt.com/api/ops/probe/report YOUR_TOKEN
# 3. 建议用 systemd / pm2 常驻，如：
pm2 start probe-agent.js -- YOUR_REPORT_URL YOUR_TOKEN

运维计费说明

持续监测任务与探针走「功能市场」订阅（ops-tools / ops-probe）；即时查询类工具（Whois / DNS / SSL / 拨测 / 端口 / 备案）默认免费，平台开启按次计费后从平台余额扣费（单价见 /api/ops/pricing，余额不足返回 402）。监测任务本身的定时检测不扣费。

控制面板（主控 / 被控，对标宝塔）

ddnt 平台 = 主控面板，服务器执行一键脚本或在线 SSH 安装后成为被控服务器。主控面板发起操作（软件商店 / 网站 / 反向代理 / Docker / Node / Java / Python / 数据库 / 计划任务 / 监控 / Web 终端 / 文件管理 / 安全审计），安装与执行脚本在被控服务器本地运行，执行日志保留在被控端，主控可随时请求分段回看。被控端零依赖、不开公网面板端口；实时能力（终端 / 文件 / 日志滚动）经 WebSocket 桥（被控出站连主控，零入站端口）。

接入方式（两种）

# 方式 A · 复制脚本：主控「控制面板 → + 复制脚本接入」生成一次性命令，到新服务器执行
curl -fsSL https://ddnt.com/install-panel.sh | bash -s -- --install-token YOUR_TOKEN --name '我的服务器'
# 装完自动注册进主控面板列表，可自定义名称；install-token 一次性，注册后作废

# 方式 B · 在线 SSH：主控「+ 在线 SSH 安装」填 IP/端口/账号/密码或私钥，平台远程自动安装
# 凭据默认安装完即删（可勾选加密留存供后续直连）

主控地址自动探测：生成命令时优先取 PUBLIC_BASE_URL 环境变量，其次浏览器实际访问地址（Origin/Referer 请求头），最后才是请求 host；生成后弹窗内可手工修改「主控地址」，命令 URL 实时同步，检测到本机/内网地址会给出醒目告警。在线 SSH 安装同样使用该探测地址。生产环境建议显式配置 PUBLIC_BASE_URL（含 http(s):// 前缀）。

被控本机独立面板（可选）

install-panel.sh 默认开启 --panel-port 8888（0=关闭），安装完成输出默认账号（admin）与随机密码；root 下 cat /opt/ddnt-panel/agent.json 可随时找回，登录后台可修改密码。本机后台提供：系统状态、主控绑定状态、本机执行日志查看、常用软件探测；并支持自主切断主控控制——切断后主控无法再向本机下发命令/终端/文件操作（面板状态转离线），本机面板不受影响，可随时在后台恢复或重跑接入命令重新绑定。已知限制：独立面板为纯 HTTP 无 TLS，建议仅内网/本机使用或经反向代理叠加 HTTPS；Agent 依赖 Node ≥21 提供内置 WebSocket（安装脚本自动装 Node 22，低于 21 时实时终端/文件桥自动降级跳过，命令与监控不受影响）。

Dpanel 独立版（被控本机面板）

install-panel.sh 默认开启 --panel-port 7856（0=关闭），安装完成输出默认账号（admin）与随机密码；root 下 cat /opt/ddnt-panel/agent.json 可随时找回，登录后台可修改密码。Dpanel 为可独立发布的产品（对标宝塔）。

套餐与授权（对标宝塔：免费全能 + 增值分层，企业 ⊇ 专业 ⊇ 免费）：免费版=系统状态/执行日志/应用中心一键安装/防火墙端口管理/本机终端/SSL 证书（自签、上传、部署 nginx）/改密/自主切断主控；专业版=+网站防火墙 WAF、防篡改、监控报表、任务管理器、云备份、SSL 进阶（ACME 自动续期）；企业版=+多用户、操作审计、SSH 审计、安全基线、开放 API、白标 OEM。升级：平台后台 POST /api/admin/dpanel/license/issue 签发激活码（Ed25519 离线验签，公钥随安装脚本下发到被控 dpanel-license.pub）→ Dpanel「授权管理」输入激活。已知限制：本机面板为纯 HTTP 无 TLS，建议内网使用或反代叠加 HTTPS；实时终端/文件桥（WS relay）需被控 Node ≥21（安装脚本自动装 Node 22，低版本自动降级跳过）。

WAF 网站防火墙（专业版，nginx 层）

Dpanel「WAF」页提供 nginx 层网站防火墙：CC 防护（limit_req 按源 IP 限速，速率/突发可调）、SQL 注入与 XSS 拦截（query_string 规则）、UA / URL / IP 黑名单（每行一条）、IP 白名单（跳过 CC 限速）、敏感路径拦截（.env/.git/wp-admin 等）与拦截日志。启用后写入 /etc/nginx/conf.d/dpanel-waf.conf 与 /opt/ddnt-panel/waf/server.conf；站点在「站点接入」列表一键接入（自动 include 并 nginx -t 校验，失败自动回滚）。规则保存即重载 nginx。

典型流程：软件商店安装 MySQL 5.7

主控「软件商店」选 MySQL → 版本 5.7 → 确定 → 安装脚本在被控服务器本地执行（apt/yum）→ 命令状态变「成功」→ 点「📄 日志」从被控端实时回看安装日志 → 软件商店更新为「已安装」。命令执行日志按命令 ID 保留在被控端 $PANEL_WORKDIR/logs/cmd_<id>.log，可配置保留天数与大小轮转。

核心接口

命令类型枚举：install_runtime（软件商店）/ deploy（项目）/ site_add site_rm site_backup cert_issue（网站/SSL）/ nginx_reload / process_start|stop|restart|status / docker_compose|restart|stop|rm / cron_add|cron_del / db_create|db_backup|db_restore / fetch_log（日志回看）/ audit_report / agent_command（智能体入口）/ echo_test。执行严格走模板白名单 + 参数转义，审计全程留痕。

计费：控制面板走「功能市场」订阅（ops-panel）；命令按次计费默认关闭（免费体验），后台「运维服务 → 控制面板」开启后按条扣平台余额（panel.price_cmd）。

DDNT 能力网络（AI 档案库 + MCP）

DDNT（AI 动态能力互联网络）让 AI 智能体安全地「认识主人、按主人的规则办事」：账号所有者把画像、行为规则、长期记忆、重要私钥存进专属 AI 档案库（档案文件化+版本控制），再签发受限的 Agent Token 交给 AI 实例。AI 通过 MCP 协议读取资产、调用平台能力（推送/商标评估/运维查询），甚至经代理网关使用主人注册的外部 MCP 服务。全程审计，随时吊销。

两把钥匙（鉴权模型）

Agent Token 的 10 个 scope

MCP 平台工具（15 个）

档案命名空间：全局资产 = persona.md / rules.md / memory.md + 自建档案（跨项目通用）；项目资产 = <项目名>/档案名（如 my-app/devlog.md）。每次保存生成新版本（旧版不可变、可回滚=生成新版本）。

安全机制

• 最小授权：AI 只拿到任务必需的 scope，凭证可设有效期（最长 365 天），一条 ddnt token revoke 即刻切断。
• 工具黑白名单：mcp_deny 屏蔽指定工具（如 send_push），mcp_allow 限定可代理的外部服务白名单。
• 防调用回环：平台转发外部工具时带 X-DDNT-Depth 标记，外部工具回调 DDNT /mcp 直接拒绝（403 / -32001）。
• 限流：每 Token 每分钟 60 次请求（429 / -32002）。
• 风控冻结：10 分钟内 30 次鉴权失败自动冻结 Token，需账号所有者处理。
• 全量审计：每次调用记录工具、参数摘要、结果、耗时与计费，控制台可查，审计日志 90 天自动清理。
• 隐私可控：控制台支持一键清除全部资产、销毁审计记录、吊销全部 Agent Token。

接入方式

推荐：ddnt CLI 内置桥（Token 不进 AI 客户端，见下节 MCP（智能体接入））。

也支持远端直连（Token 会出现在客户端配置里，注意保管）：

curl -X POST https://ddnt.com/mcp \
  -H "Authorization: Bearer ddnt_xxxx" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

计费与门控

DDNT 能力网络走「功能市场」订阅门控（未订阅时 MCP 工具返回订阅提示）；外部 MCP 代理转发可由平台开启按次计费（单价见 /api/ops/pricing 的 mcpproxy 项，默认关闭）。

错误码速查

开放能力与二次开发契约（CLI / API / MCP 三层）

DDNT 是中立、开放、包容的通用 AI 与设备调度通讯底座：不绑定任何自研组件，用户可基于下述三层开放能力完成全场景开发——完全不用平台前端、完全不用平台安全组件。

三层开放能力总览

结构化输出契约

• HTTP：所有接口统一 {"code":200,"msg":"...","data":{...}}；判断成功只看 code===200，不依赖 HTTP 状态码（错误时 HTTP 与 code 同行，如 400/401/403/404/429/500）。
• MCP 归一化：tools/call 成功返回 MCP 标准 result.content[].text——文本型工具返回纯文本，数据型工具返回 JSON.stringify(obj,null,2)；业务失败（权限/门控/参数/工具自身报错）统一为 result.isError=true + 提示文本（协议层仍 200）；协议错误（未知 method、防回环、限流）走 JSON-RPC error（-32001 防回环 403 / -32002 限流 429 / -32601 未知工具 / -32600 报文非法）。
• 计费提示：运维四查询与 MCP 代理转发按次计费（失败不扣费），工具结果文本不含计费字段，计费明细见调用审计。

档案数据模型（二开契约）

• 档案寻址：全局 persona.md 等单层名；项目 <项目名>/<档案名>（项目名小写字母/数字/连字符 ≤40，档案名 ≤64）。
• 版本链：每次保存 = 新版本（从 1 递增、不可变）；回滚 = 以历史版本生成新版本；版本说明/来源/大小/时间可查。
• 配额档位：免费 10 档案 × 64KB × 20 版本、2 项目；付费 20 × 512KB × 50、10 项目（超限自动修剪最旧非当前版本）。

私有化部署

• 数据库：SQLite（开发）/ MySQL（生产），环境变量 DB_TYPE=mysql + MySQL 参数；启动自动建表与迁移。
• 安全密钥：生产必须配置 SETTINGS_MASTER_KEY（≥16 位）等，未配置直接拒绝启动（防明文级泄露）；JWT_SECRET / ADMIN_KEY 同理。
• 开发模式：DEV_MODE=1 放行本地外部 MCP 注册与固定密钥回退——仅限联调，生产禁止。
• 资产存储 provider（对接任意安全体系/存储的默认插槽）：

# 默认本地（零依赖）：密文经 每用户 DEK(AES-256-GCM) 信封加密后落库——自动可用
# 切换 agi.locker / 任意第三方 blob 存储（零知识：只保管密文不解密）：
DDNT_LOCKER_URL=https://<服务地址>   # 三件套齐备才启用，缺省 local 零风险启动
DDNT_LOCKER_KEY=<调用方 key>
DDNT_LOCKER_SECRET=<HMAC 密钥>
DDNT_ASSET_PROVIDER=locker|local

provider 适配契约（开放生态规范红线）：任何能按 key 存取不透明字节的系统都能作为资产后端——只需实现 put/get/del(blobKey, 密文bytes) 语义（blobKey=u{user}/f{file}/v{version}，不可变+同 key 幂等）；加密永远是调用方（平台）的事，存储方不理解内容、不持密钥。

二次开发约定（红线）

• 仅凭 CLI/API/MCP 三层即可完成全场景开发，无需依赖平台任何前端/安全组件——若你觉得某项能力缺文档，提交工单指路。
• 外部 MCP 服务注册仅在控制台（公网地址 + SSRF 防护）；代理转发按次计费默认关闭。
• 私钥条目值只进不出（管理接口永不回显），只能经 secrets:read 授权 AI 服务端读取——不要设计"回显明文"的脚本。

CLI 命令行工具（ddnt）

平台统一品牌 CLI ddnt（Node 18+，零依赖），同时是推送工具、储物柜管家与 MCP 桥。源码在仓库 bin/ddnt.js，完整说明见 cli/README.md。原 jnt 指令已并入（旧配置与 JNT_* 环境变量仍兼容）。

安装与配置

# Linux/Mac 可直接使用；Windows 用 node 前缀，如 node bin/ddnt.js ...
npm link                          # 或直接 node bin/ddnt.js
ddnt config set-url https://ddnt.com
ddnt config set-token YOUR_API_TOKEN   # 后台「令牌管理」创建（主 API Token）
# 环境变量优先（适合 CI）：DDNT_API_BASE / DDNT_API_TOKEN（兼容 JNT_*）

命令一览

示例

# 服务器告警推送到邮箱
ddnt push "服务器告警：CPU 超 90%" --title 告警 --channel email --to ops@ddnt.com
# 写入主人画像并签发只读凭证
echo "主人是全栈开发者，偏好简洁回答" | ddnt asset set profile -
ddnt token create --name claude --scopes profile:read,rules:read,memory:read --days 30

MCP 接入（智能体直接调用）

推荐用 ddnt CLI 内置桥 ddnt mcp：AI 客户端通过 stdio 与本进程对话，本进程携带 Agent Token 转发到平台 /mcp（Streamable HTTP）。Token 只存主人本机，AI 客户端配置文件里没有任何密钥，泄露或滥用一条 ddnt token revoke 即刻切断。工具清单与安全机制见 DDNT 能力网络。

准备（一次性）

ddnt token create --name my-ai --scopes profile:read,rules:read,memory:read,push:send,mcp:proxy --mcp-allow '*'
ddnt config set-agent-token <上一步输出的 ddnt_xxx>   # 或环境变量 DDNT_AGENT_TOKEN

接入 Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "ddnt": {
      "command": "node",
      "args": ["/绝对路径/junengtui/bin/ddnt.js", "mcp"]
    }
  }
}

接入 Cursor（~/.cursor/mcp.json）

{
  "mcpServers": {
    "ddnt": {
      "command": "node",
      "args": ["/绝对路径/junengtui/bin/ddnt.js", "mcp"]
    }
  }
}

Agent 查询接口（API Token 直调）

CLI 与 MCP 底层使用的查询接口，均以 API Token 鉴权（与网页会话隔离），适合程序化读取账号状态。鉴权三种方式任选：Authorization: Bearer <token>、X-Api-Token 头、或 body/query 传 token（与推送接口一致）。

# 查询账号余额与配额
curl https://ddnt.com/api/agent/whoami -H "Authorization: Bearer YOUR_API_TOKEN"

场景示例

以下为几个典型接入场景，复制后替换令牌与参数即可直接使用。

场景一：服务器告警推送（微信）

curl -X POST https://ddnt.com/api/push \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_API_TOKEN",
    "title": "服务器告警",
    "content": "CPU 使用率 99%，已持续 5 分钟",
    "channel": "wechat"
  }'

场景二：电商订单通知（话题群发：微信 + 邮件）

curl -X POST https://ddnt.com/api/push \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_API_TOKEN",
    "topic": "订单通知组",
    "title": "新订单提醒",
    "content": "订单 #20260829 已支付 ¥299.00",
    "channel": "wechat,email"
  }'

先在「话题订阅」中创建话题并让成员订阅，群发一次触达全部订阅人。

场景三：IoT 设备上线（MQTT 触发推送）

设备通过 MQTT 发布一条消息到已订阅的主题，平台自动将其转化为微信/邮件推送；设备数据也可以经 Webhook 回调进入业务系统。详见「MQTT 订阅」章节。

场景四：定时数据报告（备忘录 / 监测中心）

在控制台「备忘录」设置每日定时提醒，或用「监测中心」监控网页/接口/关键词变化，变化即推送——无需编写任何代码。

更新日志

条款与协议

使用条款

• 本平台仅供合法业务使用：不得推送违法、侵权、骚扰或垃圾信息，违者将封禁账号并保留追责权利。
• API 令牌即账户凭证，请妥善保管；因保管不善造成的配额消耗由账户所有者承担。
• 各业务按套餐配额或按量计费，超出配额后将按余额兜底扣费或拒绝请求（以页面提示为准）。

数据与隐私

• 渠道密钥采用 AES-256-GCM 加密落库，全链路 TLS 传输。
• 推送内容由发布者自行决定，平台不对消息正文做长期留存。

免责声明

• AI 生成内容仅供参考，请自行核对后再用于业务决策。
• 商标评估结果为算法参考意见，不构成法律意见；注册结果以商标主管部门审查为准。

常见问题

错误码

给 AI 对接者的说明

如果你是一个 AI Agent 或自动化脚本，首选 MCP 接入（见上文，可直接对话调用）；也可直接用 HTTP 接口。请遵循以下约定：

• 鉴权：推送与 /api/agent/* 查询接口用 API Token，建议 Authorization: Bearer <token>（或 X-Api-Token 头）；其余控制台接口用 Authorization: Bearer <JWT>（JWT 从登录接口获取）。
• 响应：所有接口统一 {"code":200,"msg":"...","data":{...}}；判断成功只看 code === 200，不要依赖 HTTP 状态码。
• 推送：content 必填；channel 缺省为 wechat；要群发请先建话题再传 topic；未指定收件人且未绑定渠道时会返回 400 提示。
• 限流：推送接口 60 次/分钟；失败返回 429 时应退避重试（建议指数退避，初始 1s）。
• 敏感信息：API 令牌、密码、JWT 属于敏感信息，示例中一律使用占位符，对接时由调用方注入真实值。
• 开发模式：未配置渠道凭证时推送不会真实发出（仅服务端控制台打印），联调时注意区分环境。