dsh-sdr/packages/dsh-sdr

一句话定位

给 DeepSeek Harness Web 增加「SDR 数字员工」模式，让 Agent 严格按九阶段外贸获客 SOP（任务解析→客户发现→背调→评分→开发信→人工审批→跟进→报价→结案）跑流程，并在开发信发出前强制人工审批。

核心能力

• 推进九阶段外贸获客 SOP：服务端状态机控制阶段顺序，模型不能跳阶段也不能自己指定阶段
• 人工审批卡点：草稿必须经人类逐封选择，所有草稿都通过 sdr_review_drafts 批准后，sdr_continue_after_approval 才放行
• 草稿哈希绑定：每条批准凭证绑定草稿内容 SHA-256 哈希，草稿被改动后原有批准自动失效
• 客户去重：基于 domain/email/phone/company 计算 canonical_lead_id，跨活动复用同一批客户不会重复开发
• 混合 RAG 知识库：默认本地 BM25+向量重排；可换 PostgreSQL+pgvector 适配器，支持来源版本引用与 Recall@K/MRR 评测
• 真实发送边界：Email/WhatsApp/CRM 三个 connector 默认全部 dry-run，模型拿不到 send_email 这类通用发送工具，调用名包含 approve/send_email/send 的工具会被门控拒绝

技术实现

• 语言: JavaScript (ESM，"type": "module")
• 关键依赖: 仅使用 Node.js 标准库 (node:fs/promises、node:crypto、node:os、node:path、node:url)；可选注入 pg 作为 Postgres adapter
• 架构模式: DSH bundle 插件，通过 cordis.patch.yml 注入 dsh-sdr-installer 行（角色 installer）把 preset 写入 $DSH_HOME/.agent-presets/sdr，并由 agent.cordis.yml 在 agent 行通过 inject: [tools, userQuestions] 调用原生 JS 服务
• 入口文件: packages/dsh-sdr/lib/index.js（导出 apply(ctx, config) 与领域类 SdrService、JsonStore、ConnectorRegistry）

适用场景

做外贸获客的中小企业用户希望把「找客户、写开发信」这种重复流程交给 Agent，但又不放心让 AI 自己直接发邮件给陌生买家——这个插件用服务端状态机把流程拆成九个必须按顺序走的阶段，并在开发信发出前要求人类逐封批准，保证 Agent 永远不会绕过人发出消息。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:Xuxchloris/deepseek-harness-sdr-plugin/packages/dsh-sdr

配置项

常见问题

Q: 安装后 DSH Web 模式菜单里没有「SDR 数字员工」怎么办？

A: 重新执行一次 dsh plugin --profile web add ...，然后重启 dsh web 并新建一个会话——旧会话里加载的是安装前的 preset，必须新建会话才能看到新模式。

Q: 真实邮件会发出去吗？

A: 默认不会。内置的 Email / WhatsApp / CRM 三个 connector 的 send() 都返回 blocked-dry-run，没有真实凭证也不会发出。要对接真实渠道需要部署方自己注册 connector 实现，审批流程仍然不变。

Q: 开发信改过之后，原来的批准还算数吗？

A: 不算。每条批准凭证绑定的是草稿 subject+body 的 SHA-256 哈希，草稿改过之后再调用 sdr_review_drafts 会报「哈希不匹配」，必须重新审批。

Q: 任务状态保存在哪里？怎么改路径？

A: 默认写入 $DSH_HOME/.dsh-sdr/state.json，Windows 若没设 DSH_HOME 则是 %USERPROFILE%\.dsh-sdr\state.json。设置环境变量 DSH_SDR_DATA_FILE 即可改成自定义路径。

Q: 审批阶段报 fetch failed 怎么办？

A: 这表示当前会话不支持向用户发起交互式提问，任务不会绕过审批继续推进，会冻结在 human_approval 阶段。改用 DSH Web 模式菜单里的「SDR 数字员工」会话即可。

Q: 多实例部署能共享数据吗？

A: 默认的本地 JSON 存储只适合单实例。多实例/生产环境请用 PostgresKnowledgeRepository，自己注入 pg pool、embedder、reranker；任务状态也需要部署方自己安排共享存储。

Q: 不想让 Agent 写入知识或改 connector 配置，怎么部署？

A: 默认就是不允许。DSH_SDR_AGENT_KNOWLEDGE、DSH_SDR_AGENT_CONFIG、DSH_SDR_AGENT_LIVE_CONFIG 三个开关默认关闭，只有显式设为 1 才放行；并且 Agent 写入密码、token、API key 等敏感字段会被直接拒绝。

Q: 没有 DSH Web 也能跑吗？

A: 可以做离线演示。在 packages/dsh-sdr 目录执行 npm test 跑 7 个 node:test 单元测试，或在仓库根目录执行 node scripts/demo_dsh_sdr.mjs 跑端到端 demo，全部使用合成数据，不需要任何凭证。

上手难度

入门 — 安装一行命令即可使用；默认配置齐全、dry-run 默认安全、无需任何凭证即可演示九阶段流程；进阶调优只需理解 4 个环境变量即可。

已知问题与限制

• 只针对 DeepSeek Harness 0.1.0-rc.6 验证，其他版本未测（README.md:143 / cordis.patch.yml:1）
• 默认本地 JSON 状态存储只适合单实例部署；多实例需要切换到 PostgreSQL adapter 并自己共享状态文件（README.md:146）
• Email / WhatsApp / CRM 三个真实 connector 不随插件提供，只有接口和 dry-run 实现；要发真实消息必须由部署方注册自定义 connector（README.md:147）
• 模型无法调用任何名字包含 approve、send_email、send-email 或 send 的工具，所有审批和发送都必须经过原生人工审批门控（lib/domain.js:336-342）
• 当会话不支持交互式提问时（如部分 headless 环境），审批请求会失败，任务冻结在审批阶段，不会跳过审批继续推进（README.md:148）
• Agent 通过 sdr_knowledge_upsert 写入的内容若疑似包含 PRIVATE KEY、sk-…、password=、api_key= 等模式会被直接拒绝；connector 配置中 password/secret/token/api_key/private_key 等键名（非 _ref 结尾）同样会被拒绝（lib/domain.js:74、84、108）

DeepSeek Harness 的外贸获客 SDR 插件。安装后在 DSH Web 的模式菜单中选择「SDR 数字员工」，Agent 按九阶段销售流程工作：解析任务、开发客户、公司背调、评分、写开发信、人工审批、跟进计划、报价素材、结案。

阶段顺序由服务端状态机决定，模型不能跳阶段。开发信必须经人工批准才能进入后续流程。Email、WhatsApp、CRM 默认 dry-run，不会发出真实消息。

安装

要求 DeepSeek Harness 0.1.0-rc.6、Node.js 20+。

dsh plugin --profile web add @xuxchloris/dsh-sdr
dsh web

重启 Web 后新建会话，在模式菜单选择「SDR 数字员工」。旧会话仍使用旧 preset，需要新建。

从源码安装：

git clone https://github.com/Xuxchloris/deepseek-harness-sdr-plugin.git
cd deepseek-harness-sdr-plugin
dsh plugin --profile web add ".\packages\dsh-sdr"
dsh web

preset 写入 $DSH_HOME/.agent-presets/sdr；Windows 未设置 DSH_HOME 时是 %USERPROFILE%\.dsh\.agent-presets\sdr。安装器不会覆盖没有 dsh-sdr 管理标记的同名 preset。

使用

在 SDR 模式中输入任务，例如：

开发 3 个美国户外用品客户

Agent 调用 sdr_create_task 创建任务，然后反复调用 sdr_next_step 推进，每次只完成一个阶段。

第 6 阶段时，sdr_review_drafts 列出开发信草稿，等人工选择。只要还有草稿没批，sdr_continue_after_approval 就拒绝放行。批准凭证绑定草稿内容哈希：草稿改过后，原来的批准自动失效，需要重新审批。

用离线演示跑一遍，实际顺序是这样的：

> 开发 3 个美国户外用品客户

sdr_create_task              创建任务，进入 task_parse
sdr_next_step × 4            客户发现 → 公司背调 → 评分 → 生成 3 封开发信草稿
sdr_next_step                进入 human_approval，流程停在这里
sdr_continue_after_approval  拒绝：仍有 3 封草稿未获批准
sdr_review_drafts            列出 3 封草稿，等人工逐封选择
（人工批准全部草稿）
sdr_continue_after_approval  校验草稿哈希，放行
sdr_next_step × 3            跟进计划 → 报价素材 → 结案报告，附 11 条审计事件

没有 DSH Web 时可以跑离线演示，合成数据，不需要凭证：

npm.cmd test --prefix ".\packages\dsh-sdr"
node ".\scripts\demo_dsh_sdr.mjs"

架构

flowchart LR
    U[DSH Web / SDR 模式] --> T[Cordis 原生工具]
    T --> S[dsh-sdr Node runtime]
    S --> SOP[九阶段 SOP 状态机]
    S --> G[审批哈希门控]
    S --> L[Lead Registry 去重]
    S --> K[Hybrid RAG 知识库]
    S --> A[审计事件与结案报告]
    S --> C[Connector Registry]
    C --> E[Email dry-run]
    C --> W[WhatsApp 预留]
    C --> R[CRM 预留]
    K --> J[本地 JSON]
    K --> P[PostgreSQL / pgvector]

DSH 负责 Agent loop、工具调用和人机交互；插件负责任务状态、审批、去重、知识库和发送边界。模型没有 send_email 之类的通用发送工具可用。

工具

知识库

知识库存放产品、品牌、认证、报价政策、市场规则等资料，供开发信草稿和结案报告引用，引用记录来源和版本。默认实现是本地原子 JSON 文件，支持全文检索，可注入 embedding 和 reranker；生产环境可换成 PostgreSQL + pgvector，见 lib/postgres-rag.js。

默认只读。允许 Agent 写入用户确认过的知识时开启：

$env:DSH_SDR_AGENT_KNOWLEDGE = '1'

密码、API key、token 不会进入知识库、工具参数或审计日志。

外部连接

Email、WhatsApp、CRM 都走 connector 接口，默认实现是 dry-run，send() 返回 blocked-dry-run。接真实渠道需要部署方注册自己的 connector 实现，审批流程不变。

允许 Agent 补充部署配置时开启 DSH_SDR_AGENT_CONFIG=1。Agent 只能写 host、port、provider、发件人和凭证引用名，写不了密码和 token 的值。DSH_SDR_AGENT_LIVE_CONFIG=1 只保存 live 配置，不会自动启用真实发送。

任务状态默认保存在 %USERPROFILE%\.dsh\.dsh-sdr\state.json，可用 DSH_SDR_DATA_FILE 改路径。JSON 写入先落临时文件再 rename，进程中断不会写坏状态。

项目结构

packages/dsh-sdr/       DSH 插件 bundle（交付物）
  lib/domain.js         SOP 状态机、审批、去重和知识服务
  lib/rag.js            本地混合 RAG、reranker 和评测
  lib/postgres-rag.js   PostgreSQL/pgvector adapter
  lib/index.js          DSH 工具注册入口
  presets/sdr/          「SDR 数字员工」persona 和 preset
app/                    原 ai-sdr Python 业务代码，完整保留
scripts/                离线演示脚本
docs/                   迁移方案和验收记录

与原 ai-sdr 的关系

这个仓库的前身是 Python 项目 ai-sdr（app/：FastAPI、飞书机器人、Pydantic AI、旧 MCP 入口），代码完整保留，可独立运行。当前交付物是 packages/dsh-sdr/，用 Node.js 重新实现，运行时不依赖 Python 环境。取舍过程见 docs/迁移方案.md。

限制

• 只验证过 DSH 0.1.0-rc.6，其他版本未测。
• 默认 JSON 存储适合本地和单实例；多实例部署用 PostgreSQL adapter。
• 真实邮件、WhatsApp、CRM connector 不随包提供，只有接口和 dry-run 实现。
• 当前会话不支持 agent 交互提问时，审批请求会失败，任务冻结在原地，不会跳过审批继续跑。

开发与发布

npm.cmd test --prefix ".\packages\dsh-sdr"

发布由 .github/workflows/npm-publish.yml 完成：推 dsh-sdr-v* 标签触发，先跑测试，再用 npm Trusted Publishing 发布，不需要长期 npm token。

许可证

MIT。仓库不含 .env、真实客户数据和 API key，示例数据均为合成。