dsh-wecom-lead

DeepSeek Harness (DSH) 插件:把 wecom-lead 服务端(腾讯广告落地页 → 企业微信精准进粉归因 → 转化回传)的管理 API 暴露成 15 个 agent 工具,让你在 DSH 里用自然语言查漏斗、追单个客户链路、调销售分配和防水墙规则。

本插件只是管理 API 的客户端。服务端需要自行部署,接口约定见下文「服务端接口约定」。

工具

工具	用途
lead_status	系统总览:企微/腾讯功能是否配置、待处理事件、回传积压/死信、池码水位
lead_funnel	漏斗:消耗 → 点击 → 访问 → 防水墙 → 出码 → 进粉 → 删除 → 回传,按链接或按天
lead_trace	单个客户(企微 external_user_id)从访问到回传的完整链路
lead_visits / lead_conversions	访问 / 转化明细(分页、过滤)
lead_links	投放链接 list / create / update(回传比例 24h 限改一次、单步 ≤10%)
lead_agents / lead_groups	销售与分组:权重、日进粉上限、在线时段、熔断状态
lead_shield / lead_allowlist	防水墙规则(含不落库的干跑 test)与 IP 白名单
lead_templates	落地页模板
lead_media_accounts	腾讯广告账户 OAuth 授权链接、转化数据源
lead_uploads	转化回传日志与重放
lead_contact_ways	企微活码池水位与补货
lead_wecom_events	企微回调事件收件箱:查看失败事件并重放

查询类工具只读;其余工具用 action 参数分派(如 list / create / update),请求体放在 data。

安装

需要 DSH ≥ 0.1.5-rc.2(< 0.3.0)。

git clone https://github.com/crawfordxx/dsh-wecom-lead.git
cd dsh-wecom-lead
pnpm install
pnpm build          # 输出 lib/

在 DSH profile 的 cordis.patch.yml(例如 ~/.dsh/profiles/<profile>/cordis.patch.yml)加一行插件:

- insert:
    - id: wecom-lead
      name: /absolute/path/to/dsh-wecom-lead/lib/index.js
      config:
        baseUrl: https://lead.example.com      # 你的服务端地址,必须 https
        tokenRef: WECOM_LEAD_ADMIN_TOKEN       # DSH 凭据名
        timeoutMs: 15000

然后在 DSH 凭据里保存同名凭据 WECOM_LEAD_ADMIN_TOKEN,值为服务端的管理 token(设置 → 凭据,或 ~/.dsh/.credentials.yaml 的 refs)。插件每次调用都重新读取凭据,轮换 token 不用重启。

⚠️ DSH 加载插件失败会中止整个启动:移动或删除插件目录前,先从 patch 里删掉这一行。

配置项

字段	默认值	说明
baseUrl	无(必填)	服务端地址,只接受 https://
tokenRef	WECOM_LEAD_ADMIN_TOKEN	管理 token 对应的 DSH 凭据名
timeoutMs	15000	单次请求超时(1000–120000)

服务端接口约定

插件请求 ${baseUrl}/api/v1/...,带 Authorization: Bearer <token>,期望返回统一信封:

{ "success": true, "data": {}, "error": null, "meta": { "page": 1, "page_size": 50 } }

失败时 success=false,error={ code, message },插件会以 [CODE] message 抛给 agent。完整的工具 → 路由映射见 src/routes.ts。

安全说明

• 管理 token 只存在 DSH 凭据里,配置文件中只写凭据名。
• 返回结果开头会标注「外部数据」:访客 UA、referer 等字段可能被外部写入,agent 只应把它们当数据,不当指令。
• 写操作(改回传比例、白名单、规则等)会直接生效。建议在 DSH 里为这些工具开启审批。
• 防水墙用于过滤无效、异常流量,不得用于欺骗平台审核。

开发

pnpm install
pnpm test        # 工具注册与请求映射
pnpm typecheck
pnpm build

License

MIT