dsh-dingtalk-self

> English TL;DR — A DeepSeek Harness (dsh) plugin that answers DingTalk direct messages as your own account. It watches the chats you pick, asks the agent (bound to a DSH workspace) to look the answer up, and sends it back through the dws CLI with an opt-out marker line. No bot account, no forwarded questions. Requires macOS + dws auth login; replies are Markdown, and tables/charts/flow diagrams can be rendered to PNG by the host.

DSH 插件：钉钉代答。别人在钉钉问你，agent 自己去你绑定的工作区里查资料，然后以你本人身份直接答复对方——
你不用把问题转发给 agent，对方收到的也是「你」发的普通消息，不是机器人、不是数字员工账号。

它和普通钉钉插件的区别

链路：

对方私聊你
↓  dws chat message list --open-dingtalk-id   （以你身份读）
过滤 / 去重 / 合并
↓  投递到绑定的 DSH 工作区（仅可查看）
生成回复
↓  出站护栏（禁代码 / 禁路径 / 禁内网地址）
dws chat message send --ai-tag=false --idempotency-key
↓
对方看到「你」发的普通消息

安装

# 1. 装进你的 profile（路径改成你的实际目录；日常用桌面版就是 desktop）
dsh plugin --profile desktop add ~/projects/dsh-dingtalk-self

# 2. 重启 DSH App，然后刷新页面
# 3. 打开 设置 → 钉钉代答（设置侧栏里，order=45）

装好后检查两处（缺一不可）：

python3 -c "import json;d=json.load(open('$HOME/.dsh/profiles/desktop/package.json'));print('deps:', 'dsh-dingtalk-self' in d['dependencies'], 'bundles:', 'dsh-dingtalk-self' in d['dsh']['profile']['bundles'])"
cat ~/.dsh/data/dsh-dingtalk-self/boot.log   # 应有一行 version=0.2.0 ... schema=yes

• 客户端半边（设置页）由 package.json 的 dsh.client 声明，普通 JS、无需构建；
  重装/改代码后必须重启 App 才会重新装配（实测 Host 侧改代码不会热重载插件）。

卸载：

dsh plugin --profile web remove dsh-dingtalk-self

> dsh 不在 PATH 时用全路径：
> /Applications/DeepSeek\ Harness.app/Contents/Resources/runtime/cli/bin/dsh

前置条件（缺一不可）

1. dws 已安装（dws --version 有输出）
2. 已完成个人 OAuth 登录：

dws auth login          # 扫码授权
dws auth status         # 应返回 "authenticated": true

⚠️ dws auth login 必须在你自己的终端里执行 —— 在 Agent 沙箱里跑会因无法写 ~/.dws 而 EPERM。

3. 有一个可绑定的 DSH 工作区（侧栏里那个，例如 my-workspace）

设置页（client 半边）

设置 → 钉钉代答 一页完成全部操作，不需要手改配置文件：

数据通道（契约见 docs/client-host-api.md）：客户端不直连宿主服务，
而是访问插件自己注册的五个同源 HTTP 端点：

GET  /dsh-dingtalk-self/api/state
POST /dsh-dingtalk-self/api/config     { patch }
POST /dsh-dingtalk-self/api/pause      { paused }
POST /dsh-dingtalk-self/api/confirm    { contact, action }
POST /dsh-dingtalk-self/api/diagnose
POST /dsh-dingtalk-self/api/contacts/search   { query }
POST /dsh-dingtalk-self/api/cycle              {}   // 立即检查一次
POST /dsh-dingtalk-self/api/test-reply         { message }   // 模拟回答，不发送

配置存放位置（当前 DSH 版本）：本机 settings 服务没有 register，describe() 也不返回插件条目，
所以配置落在 ~/.dsh/data/dsh-dingtalk-self/config.json，设置页里「配置来源」会显示这一点。
宿主若提供可写的 settings.update，代码会优先走 DSH 原生 settings（响应里的 configSource: "settings"）。

配置

设置页里的字段与含义（同一份 schema 也是 lib/settings.js 里的 Config）：

开起来的最小步骤：enabled=true → 加一条 contacts → mode=draft → 先看草稿。

回复排版（Markdown 优先）

dws chat message send 的默认消息类型就是纯文本 / Markdown，钉钉客户端会渲染加粗、列表、小标题，所以默认按 Markdown 发。
config.replyFormat 可选 markdown（默认）/ text，两层处理：

实测同一个接口问题的输出（markdown 模式，钉钉会渲染成加粗/列表/小标题）：

APP 端提交工单的接口，写入工单主表并推进状态。

### 主要作用
- 接收 APP 提交的工单，写入 **work_order**
- 含工单号、客户信息、处理意见与附件
- 按入参把工单状态推进到 **DONE**

### 顺带做的事
- 把联系人回写到对应主体
- 生成一条待发通知记录
- 异步重新生成这张工单的 **PDF**

### 几个规则
- 按租户配置 **SIGN_MODE** 校验附件：**1** 电子签、**2** 纸质签、**3** 双要求
- 附件不齐不报错：先保存，状态不动，提示待补齐
- 同一工单重复调用只补录，一单只留 **1** 条记录

注意：通知只写待发记录，状态为未发，本接口不同步发送。

> 表格和代码围栏在钉钉 Markdown 里渲染不好，提示词里已禁止模型输出它们。

回复字数上限默认 1200（要点式回答需要空间），可在 limits.maxReplyChars 调。

配图：表格 / 步骤图（宿主侧渲染）

模型不画图，只输出结构化块；插件在宿主进程里用 DSH 自带的 Python + Pillow 渲染成 PNG 再发（宿主不受沙箱限制，用户也不用装依赖）。

[[render:table|各区域订单量]]
区域 | 渠道 | 订单
华东 | 直营 | 1399
华北 | 直营 | 1344
[[/render]]

柱状图（用于对比，值是数字）：

[[render:bar|各区域订单量]]
华东 | 1399
华北 | 1344
[[/render]]

流程图（有先后/流转的链路）：

[[render:flow|工单提交的流转]]
前端提交 | 表单校验通过后上传
服务端校验 | 字段与权限检查
写入记录 | 一单一条，重复只更新
[[/render]]

或步骤图：

[[render:steps|提交签名接口做了什么]]
接收签名 | 前端一次性上传签名图、邮箱、评价
写签名记录 | 一张工单只保留一条
[[/render]]

渲染块会从正文里抽掉，正文仍然能独立读；渲染失败只记审计，文字照发。渲染产物落在 ~/.dsh/data/dsh-dingtalk-self/outbox/，随后按附件链路补发。

什么时候画：按对方意图判断，不是按数据类型一刀切。

两层约束：提示词按上表判断；代码闸门 render.minRows（默认 3）会丢掉少于 3 行/步/节点的块（柱状图少于 2 项也不画）。每条回复最多一张图。

附件（attachments.enabled）支持工作区里已有的图片与常见文档：png/jpg/webp/gif/pdf/docx/xlsx/csv/md/txt/zip。

回复附带图片（附件）

钉钉的 Markdown 内联图只认公网 URL；本地图片只能走 --msg-type file 作为文件附件发（不是内联大图）。所以附件是「文字发完再补发文件」的两条消息。

安全与边界：

• 只允许 png/jpg/webp/gif/pdf/docx/xlsx/csv/md/txt/zip；
• 路径必须落在工作区目录、插件数据目录或 outbox 里（越界直接拒绝并记审计）；
• 路径指令会被抽出来，正文里不会出现路径（否则护栏会抹成 [路径]）；
• 附件被拒时只记审计，文字照发，不会因为一张图失败而整条不回；
• 草稿/确认模式会把附件一起存进待确认队列，人工确认发送时一并补发。

> 「让它自己生成图」目前受限：agent.readOnly 默认开（不能写文件），而且这台机器没有可用的沙箱后端，bash 在 headless 里跑不了，所以它没法跑绘图脚本生成 PNG。要走到这一步，需要关掉只读并给它一个可用的画图/渲染能力。

会话标题：一眼看出是跟谁的对话

插件每次生成都会在绑定的工作区里留一个 DSH 会话。为了让侧栏里能分辨，会话标题被固定成：

【钉钉代答·赵迎凯】保养合同从 APP 提交签名到最终签收，经过哪些状态？（+1 条）

实现上做了两件事（lib/agents/headless.js）：

1. 提示词首行就是这条标题（DSH 的标题 fallback 取首条消息的前 N 字节）；
2. 每次运行的 overlay 里关掉标题小模型（session-title-llm），并把 session-title 的
   fallbackMaxBytes 精确设成首行的字节数——否则小模型会把名字改掉（实测会变成「钉钉代答简单算术问题」）。

会话数量方面：

• 真实回复每个联系人复用一个会话（state.sessions），上下文连续；
• 模拟回答每个联系人复用一个「模拟会话」（state.simSessions），与真实会话隔离，不再每点一次多一个。

出站标识（让对方知道是助手代答）

每条发出去的消息末尾会附一行标识，默认 （本条由助手代答），可在 设置 → 钉钉代答 → 行为设置 → 回复标识 改或留空关闭。

• 标识前留一个空行（Markdown 里单换行不分段，直接紧跟会糊在最后一句后面）；
• 标识在护栏截断之后追加，字数上限会先给标识留空间；
• 草稿、待确认队列里存的也是带标识的正文，人工确认发出去同样带；
• 审计里会同时记录这条回复是哪个模型产生的（config.agent.provider/model，留空则显示为空）。

三种模式

生成回复用哪个模型、能不能改文件

这两件事都在 设置 → 钉钉代答 → 行为设置 → 生成回复 里：

两个实现细节（都在没有 GUI 的情况下验证过）：

• 凭据：headless bundle 把 credentials / authorization 两个插件禁用了（官方注释：one-shot jobs use launch-time credentials），
  子进程只认环境变量。插件因此从 $DSH_HOME/.credentials.yaml 的 refs 段读出形如 DEEPSEEK_API_KEY / MAGPIE_GATEWAY_KEY
  的键，在 spawn 时注入子进程环境（只在内存转发，不落盘、不打日志）。
• 为什么不能"跟随某个工作区"：DSH 里模型不是工作区的属性，而是「profile 默认 + 每个会话自己选」。
  插件生成发生在独立子进程里，没有你的 GUI 会话，所以只能指定到 profile 级默认。

出站护栏（本方案最关键的安全措施）

「仅可查看」只挡住 agent 改文件，挡不住它把工作区里的代码读出来发给你同事。所以发送前一定过一道减法：

清理后若为空（原文全是代码/路径），不发送，记审计。

已验证 / 未验证

已验证（本机，54 个自动化用例 + 真机浏览器）
- 护栏：剥代码块、抹路径、抹内网地址、禁用词、全代码拦截、截断、可关闭
- 策略：静默时段（含跨零点）、每小时上限、最小间隔、只认对方消息
- 主流程：草稿 / 确认 / 自动三档、autoReply 双层保险、自发消息过滤、去重、连发合并、合并窗口、生成失败保留、发送失败不重试、SKIP、护栏拦截留审计、未启用/空名单/急停、非文本跳过
- dws 参数：--ai-tag=false、--idempotency-key、--open-dingtalk-id、--direction newer

真机验证（DSH 0.2.1-rc.3，临时 profile 独立实例，端口 53555）

• 设置侧栏出现「钉钉代答」，页面完整渲染（见上方截图）
• dws 未登录 状态与原因正常显示；一键自检六项全部返回
• 急停 → 生成 PAUSE 文件、状态变「已暂停」、toast 提示
• 打开总开关 → 保存 → 写出 config.json、配置来源切到「状态目录 config.json」
• 五个 HTTP 端点用 curl 直连验证（state / config / pause / confirm / diagnose）

已确认的限制（重要）

1. 本版本没有「自动生成设置页」。 0.2.1-rc.3 的 settings 服务对象上没有 register，
   describe() 也只返回内置命名空间，所以插件必须自带客户端页（已实现）。
   Config 仍然导出，留给 Loader 校验与未来版本使用。
2. agent.kind=session 未适配完成 —— 会话创建 sessions.create({ workspaceId, agentPreset }) 已确认；但「注入 prompt 并取答复」的方法因 DSH 版本而异，代码里做了能力探测，探测不到会明确报错并提示切 headless。默认走 headless。

未验证（需要你的账号才能确认）

3. --ai-tag=false 服务端是否真去掉角标 —— 参数已确认存在，实际效果需你发一条真实消息目视确认。这是整个方案成立的前提。
4. 真实私聊收发 —— 需要先 dws auth login，再用一条真实私聊走完「收 → 生成 → 发」。
5. 日常 desktop profile 里的实际加载 —— 本机 desktop profile 由 Electron 独占，CLI 无法 --dump-config，只能重启 App 后看设置页与 boot.log。

已修复的两个健壮性问题

• @deepseek-ai/schemastery 解析不到会让整个插件加载失败（连带轮询与护栏全部失效）。已改为可选依赖：解析不到就用纯对象默认值，插件照常挂载。
• 状态目录不可写（只读 home / 沙箱）会让 apply() 抛 EPERM 导致挂载失败。已改为降级到内存存储，并在日志里明确告警。

排障

装完没反应 / 不确定有没有在跑
先看设置页状态卡的「上次检查」一行（来自 lastCycle），或点「立即检查一次」：它会明确告诉你
读了几条、有没有新私聊、有没有生成草稿。三种常见情况：

1. 总开关没开 —— enabled=false，插件一次都不会跑（state.json 不会刷新）。
2. 首次启用看不到历史消息 —— 首次只回看 initialLookbackSeconds（默认 15 分钟）。
3. 模式是 confirm —— 回复只进「待确认草稿」，要你手动点发送，不会自动发出去；
   想全自动需要 mode=auto 且该联系人/分组开启「允许真实发送」。

看 DSH 控制台是否打印 [dingtalk-self] 已加载。没有就是挂载失败，检查 profile 是否重启。

工具注册失败
插件用 try/catch 包了工具注册，失败只告警不影响轮询；dingtalk_self_status 不可用时改用审计日志/设置页。

审计里出现 dsh 退出码 1: session "dshdt-…" does not exist
0.2.1 的 headless runner 里 --session-id 只能接管已存在的会话（不会新建）。
0.2.2 起插件这样处理：每个联系人第一次生成时用 --json 跑，从首行 session 事件里拿到新建的会话 id
并存进 state.sessions，之后再用 --session-id 续上同一段上下文；若会话丢失则自动新建一次。

审计里出现 [generate] dsh 进程错误：spawn dsh ENOENT
宿主进程的 PATH 里没有 dsh（它不是全局安装，只在 App 包内）。0.2.1 起会自动按
「配置的 dshCliPath → DSH_CLI 环境变量 → App 包内 CLI → /opt/homebrew/bin → /usr/local/bin」
找真实存在的绝对路径；「环境诊断」里也新增了「dsh CLI（生成回复用）」一项。
还找不到就在配置里填 dshCliPath。

发不出去：cannot resolve --user ... to openDingTalkId
把该联系人的 openDingTalkId 填进配置，代码会优先用它。

sandbox / EPERM
在 Agent 沙箱里跑 dws 会失败，所有 dws auth 类操作请在你自己终端执行。

开发

node --test test/core.test.js test/plugin.test.js test/plugin-http.test.js test/rpc.test.js test/headless.test.js

核心逻辑全部与宿主解耦（adapters 注入）；test/plugin-http.test.js 用假 ctx 跑真实的 apply()，
所以不需要装进 DSH 也能覆盖「设置命名空间 + HTTP 路由 + 配置读写 + 工具注册」这条线。

不改你日常 profile 的验证方式

用一个临时 DSH_HOME 起一个独立实例（不同端口，互不影响）：

export DSH_HOME=/tmp/dshdt-verify-home
DSH="/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh"

"$DSH" --profile verify --from-default-profile web --dump-config   # 造 profile
"$DSH" plugin --profile verify add ~/projects/dsh-dingtalk-self
"$DSH" --profile verify --port 53555 --no-open                      # 启动，输出的 URL 带 token

curl -s -b cookie.txt http://127.0.0.1:53555/dsh-dingtalk-self/api/state   # 先访问一次带 token 的 / 拿 cookie

# 清理
kill $(lsof -ti tcp:53555); rm -rf /tmp/dshdt-verify-home

改完宿主代码必须重启这个实例（实测 Host 侧没有热重载）；改客户端代码刷新页面即可。