DingTalk DSH Assistant

dingtalk-dsh-assistant 是一组运行在 DeepSeek Harness（DSH）中的钉钉个人助理插件，不是独立 Agent 平台，也不自行实现第二套 Session、Agent 或任务执行引擎。

插件负责把钉钉群消息接入 DSH，并将群聊协作映射到 DSH 原生能力：每个常驻群绑定一个固定主 Session，主 Session 负责沟通与协调；实际任务由独立叶子 Session 和 Goal 执行。Agent 身份、工作规则与可用工具由配置的工作区及其 AGENTS.md 决定，插件本身不包含个人姓名或数字分身设定。

与 DSH 的关系

插件直接复用以下 DSH 机制：

Session：每个群一个常驻主会话，每个 Task 一个独立叶子会话。
subagent：主会话只协调，叶子会话独立执行任务。
Goal：维持叶子任务的持续执行、恢复和完成状态。
systemPrompt.section：向主会话注入群名称、群 ID、群职责与决策协议；向叶子会话注入任务流程和证据要求。
Agent Registry 与原生 descriptor：在 DSH Web 中展示并打开常驻会话、叶子对话和轨迹。
默认模型、推理深度与权限 preset：由 DSH 原生服务保存和应用。
storage domain：持久化群订阅、消息、Task、可靠投递、授权申请和告警。
attachment service：将钉钉图片作为 DSH 原生多模态附件传入会话。

插件只补充钉钉渠道和群聊工作流特有的能力：DWS 订阅与补拉、消息去重排序、任务准入与关联、可靠 outbox、授权审批、任务看板和运行告警。

DWS 群消息
  → dingtalk-dsh-assistant
  → DSH resident 主 Session（判断、沟通、协调）
  → DSH leaf Session + Goal（独立执行）
  → 主 Session（组织结果）
  → outbox + DWS 回读确认
  → 原群引用回复并 @任务提出人

不依赖 Agent Studio，也不要再并行启动另一套会话或任务 Runtime。

包结构

packages/dingtalk-dsh-assistant：核心业务插件。负责 DWS 接入、群与 Session 绑定、消息处理、Task 调度、授权审批、可靠回复和配置页面。
packages/dingtalk-dsh-observer：DSH Web 展示扩展。提供群聊会话、任务看板、归档任务、授权审批和告警页面。
.dsh/profiles/resident：resident Runtime 的参考 profile 与 Cordis patch。
.dsh/profiles/web：Web contribution 的参考 profile。
docs/spec：关键状态机和工作流设计说明。
test：插件单元测试和 Runtime 契约测试。

环境要求

Windows 11 与 PowerShell 7。
Node.js 24 或更高版本。较低版本缺少 DSH Session JSONL 持久化所需的 zstd API。
已安装 DSH，并能正常启动 dsh web。
已安装并配置所选模型对应的 DSH provider。只有使用 ChatGPT/Codex 订阅时才需要 dsh-codex-connect。
已安装并登录 DWS。只有启用真实钉钉订阅时才需要。

网络环境需要代理时，可在插件的 Agent 配置中填写代理地址，也可以在启动前设置 HTTP_PROXY / HTTPS_PROXY。

Skill 文件路径

DSH 根据 Session 的 Agent 工作目录发现项目级 Skill，同时加载用户级 Skill。默认扫描顺序如下，靠前的同名 Skill 优先：

<Agent工作区>\.dsh\skills\<skill-name>\SKILL.md
<Agent工作区>\.agents\skills\<skill-name>\SKILL.md
profile 显式配置的 customSkillDirs
%DSH_HOME%\skills\<skill-name>\SKILL.md，DSH_HOME 默认是 %USERPROFILE%\.dsh
%DSH_AGENTS_HOME%\skills\<skill-name>\SKILL.md，DSH_AGENTS_HOME 默认是 %USERPROFILE%\.agents

给本机所有 DSH 项目共享的 Skill，推荐安装到 %USERPROFILE%\.agents\skills；只服务当前 Agent 工作区的 Skill，推荐安装到 <Agent工作区>\.agents\skills。DSH 不扫描 %USERPROFILE%\.codex\skills，仅安装在 Codex Skill 目录中的 write-pr、dingtalk-* 等 Skill 不会进入 resident 或叶子 Session。

复制时必须保留完整的 <skill-name> 目录，不能只复制 SKILL.md，因为 Skill 可能引用同目录下的 references、scripts 或其他资源。目录被发现只表示 Skill 已进入会话目录；模型仍会在任务命中触发条件后调用 skill 工具加载完整指令。验证是否真正加载时，应在 Session JSONL 中同时确认对应的 tool/call 和 isError: false 的 tool/result，不能只检查文件存在。

安装到 DSH

推荐让 Web、resident Runtime 和看板运行在同一个 DSH Web 进程中，避免两个进程同时写同一份 Session JSONL 和 storage domain。

正式版本发布后，可用 DSH 原生插件命令一次安装发行包：

dsh plugin --profile web add dingtalk-dsh-assistant

版本历史见 CHANGELOG。设置页会通过 GitHub Release 检查新版本；检查失败会明确显示错误，不会误报为最新版本。升级使用：

dsh plugin --profile web update dingtalk-dsh-assistant

尚未发布到 npm 时，继续使用下面的源码安装方式。

维护者发布新版本时，先将根包、assistant 和 observer 的版本号及 CHANGELOG.md 更新为同一版本并合并到 main，再推送对应的 v<version> Tag。GitHub Actions 会在 Node.js 24.19.0 下重新构建、测试和打包，按 observer → assistant → 根发行包的顺序发布 npm；三个包回读一致后才创建 GitHub Release。发布 job 绑定 GitHub Environment NPM_PUBLISH，优先使用其中的 NPM_PUBLISH_TOKEN，未配置时回退到 NPM_TOKEN。

1. 获取源码并验证

git clone https://github.com/HiQ-AI/dingtalk-dsh-assistant.git
Set-Location .\dingtalk-dsh-assistant
pnpm install
pnpm test

2. 将插件加入 DSH Web profile

在 %USERPROFILE%\.dsh\profiles\web\package.json 中加入两个本地依赖。路径应替换为仓库的真实绝对目录：

{
  "dependencies": {
    "@zzusp/dingtalk-dsh-assistant": "file:D:/path/to/dingtalk-dsh-assistant/packages/dingtalk-dsh-assistant",
    "@zzusp/dingtalk-dsh-observer": "file:D:/path/to/dingtalk-dsh-assistant/packages/dingtalk-dsh-observer"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "@zzusp/dingtalk-dsh-assistant",
        "@zzusp/dingtalk-dsh-observer"
      ]
    }
  }
}

保留 profile 中原有的 DSH 依赖和 bundle，不要用上面的片段覆盖完整文件。

若使用 ChatGPT/Codex 订阅，再把 dsh-codex-connect 同时加入 dependencies 和 bundles；使用其他模型来源时保留对应 provider，不需要安装 dsh-codex-connect。

3. 装配 resident Runtime

把 .dsh/profiles/resident/cordis.patch.yml 中的 resident 配置按需合并到实际使用的 Web profile patch。Web 基础 bundle 已包含 storage 相关插件，只覆盖 storage-json 配置并插入 dingtalk-dsh-assistant/resident，不要重复插入同名 storage 项。

仓库模板有意保持以下安全默认值：

groups: []
dws:
  enabled: false
  writesAuthorized: false

不要把个人群 ID、DWS profile、Agent 名称、工作目录或职责写入仓库模板；这些内容应保存在本机 DSH 配置和插件 storage 中。

4. 安装 profile 依赖

Set-Location "$env:USERPROFILE\.dsh\profiles\web"
pnpm install

5. 启动 DSH Web

Set-Location D:\path\to\dingtalk-dsh-assistant
pwsh -NoProfile -File .\scripts\start-web.ps1

默认 Web 地址由 DSH 提供；resident 插件监听 127.0.0.1:18998。GET http://127.0.0.1:18998/health 可检查插件 Runtime 状态。

scripts/start-web.ps1 使用当前用户的 %USERPROFILE%\.dsh 作为默认 DSH_HOME；若需要隔离 profile，可在启动前显式设置 DSH_HOME。脚本从当前项目根启动，并自动发现 PATH 中的 Node.js 和全局安装的 DSH。

首次配置

启动后，在 DSH Web 的“设置 → 插件 → 钉钉个人助理”中完成配置：

已选中的钉钉个人助理插件配置

设置 Agent 名称和别名，多个名称使用英文逗号分隔。
设置 Agent 工作区绝对目录。DSH 会从该目录原生发现 AGENTS.md。
设置默认模型、推理深度和叶子任务并行上限，默认并行上限为 5。
按需设置网络代理。
填写任务流程引导和完成证据要求；这两项只注入叶子 Session。
通过群名称模糊搜索添加常驻群，并为每个群配置会话职责。

确认页面的环境检查显示 DWS 已安装、已登录后，再在实际 profile 中启用：

dws:
  enabled: true
  writesAuthorized: false

先验证真实消息能够进入固定 resident Session，再将 writesAuthorized 改为 true 开放群聊回复。修改 profile 后需要重启 DSH Web。

完整的逐步安装、页面字段说明和“先收后发”验收流程见安装插件并在 DSH Web 中完成配置。

群聊工作流

常驻主会话

每个群唯一绑定一个 resident Session。群名称、群 ID、职责和稳定决策协议通过 DSH systemPrompt.section 注入。主会话可以按职责主动补充事实、纠错或解除讨论阻塞，但只有消息明确指向已配置的 Agent 名称、别名、DWS 登录人或使用 cc:，并形成职责范围内的可验证目标时，才创建或续接 Task。主会话只负责选择 Task 路由；Runtime 使用原始群消息生成来源证据信封交给叶子，主会话生成的根因、完成度、方案优劣或排除性判断不作为叶子事实。

叶子任务

Task 可设置独立的简短标题用于看板展示；标题与 objective 分离，重命名不会改变任务授权范围、Goal 或验收标准。运行看板通过 DSH 官方 sidebar.footer.action 提供左侧菜单入口，并由 shell.overlay 承载右侧完整内容区域；点击运行看板时切换到看板并清除 Session 选中状态，点击任意 Session 时关闭看板、恢复该 Session 的选中状态与对话/轨迹。运行看板复用 Session 的实际选中背景色，不额外显示焦点边框。

运行看板顶部固定为 76px；各页按剩余视口高度计算内容区，任务列扣除顶部、主内容内边距和标题后使用可视高度，卡片在列内独立滚动，不再强制至少 1000px 高。

Runtime 使用 DSH 原生 subagent 和 Goal 创建叶子 Session。主会话不执行具体工作。Task 将简短任务名、当前有效目标和叶子执行用的来源证据信封分开持久化；任务看板和原生子会话展示任务名，叶子 Goal 同时接收当前目标与完整来源证据。来源信封包含消息 ID、发送者、时间、引用 ID、原始正文和附件异常，并明确要求结合当前代码、运行态和工具证据独立核验。Task 正式执行状态为 running、waiting、completed，超过并行上限时进入产品层 queued。归档只影响看板展示，不删除 Task、Session、Goal 或历史上下文；已完成或已归档 Task 收到关联上下文时会重新打开原 Task，并复用同一个叶子 Session，但创建独立的新执行轮次和全新 Goal。新轮次会覆盖当前目标、来源消息与发送人、验收标准、阶段任务、开始时间、阻塞和结果；上一轮的 Session、目标、来源、验收、阶段和结果快照进入 runHistory，只作为历史参考。后续消息明确扩大或收窄动作范围时，Runtime 在同一 Task 中修订当前有效目标并保留旧目标历史；普通事实补充不会修改目标。每轮重开会把新的群消息与发送人记录为当前触发来源，同时保留历次触发历史；该轮完成通知引用并 @当前触发人。

阻塞与授权

缺少任务信息：叶子进入 information waiting，由主会话回群向任务提出人询问。
受控操作或必须真人确认：叶子创建授权申请，页面“授权审批”和 DWS 登录人本人私聊共享同一申请状态机。
钉钉批复必须引用申请消息并明确回复“批准”或“拒绝”；等待不设超时。
相同操作范围复用原申请，已批准范围不会重复申请；范围变化才创建新申请。

完成通知

任务完成后，叶子把结构化结果交回主会话。Runtime 使用 DWS 原生引用回复任务发起消息，并通过结构化 atOpenDingTalkIds @任务提出人。发送后必须回读钉钉真实消息才将 outbox 标记为已投递。

任务进度、阻塞和完成通知只有 Runtime 一个群聊发送出口；叶子会话不得自行调用 DWS 向来源群发送通知。叶子提交完成结果后，Runtime 会把摘要、证据、交付物及部署信息完整交给常驻主会话组织群通知；通知可合并重复表述，但必须保留不同关注点、限定条件、失败项和未验证/未部署边界，不能为了简短只复述摘要。完成通知优先引用当前真实群触发消息；Web 与内部恢复来源只用于触发内部操作，不得覆盖 Task 当前真实消息及发送人，也不得写入消息触发历史；发现旧数据中的伪来源时会回溯最近一条带真实发送人 ID 的群消息并清理伪触发记录。通知层仍会独立回溯真实来源，避免旧数据清理前丢失引用和结构化 @。同事或其 AI 助理发送的回复、任务回执和状态通知不会按文案或发送者在模型外过滤，而是进入常驻模型，由模型结合引用、上下文和任务索引决定忽略、回答或关联任务。

叶子提交 completed 后，Runtime 会先让常驻模型对照当前最新目标审查本轮结果和证据。若新增或修订范围未完成、缺少验证，Task 保持 running，缺口反馈给原叶子继续执行，不生成完成通知。

running 和 waiting（包括阻塞中）任务收到新增信息时只追加 task-context，继续同一执行轮次；只有 completed 任务（包括已归档展示）才允许 reopen 并初始化下一轮。

Web 运行看板

dingtalk-dsh-observer 在 DSH Web header 中提供：

钉钉个人助理任务看板

群聊会话：查看不同 resident Session 的分页消息和 Agent 投递状态。
任务看板：按待执行、执行中、等待中、已完成展示 Task，并打开 DSH 原生叶子对话和轨迹。
归档任务：查看已归档 Task，相关群消息仍可重新打开原任务。
授权审批：分页查看完整申请单，并在页面批准或拒绝。
告警：按类型查看当前异常和分页的已恢复历史。

看板不读取或重建 DSH Session JSONL，只通过插件状态接口展示业务投影；对话与轨迹仍由 DSH 原生页面负责。

状态与数据目录

正式运行使用标准用户级 DSH_HOME：

插件状态：%USERPROFILE%\.dsh\storages\dingtalk-dsh-assistant\
DSH Session：%USERPROFILE%\.dsh\sessions\
profile：%USERPROFILE%\.dsh\profiles\

仓库不提交本机 Session、消息、Task、授权记录、DWS profile、群 ID、打包产物或凭据。

开发与测试

pnpm install
pnpm test

测试接口仅在 testApiEnabled 显式开启时可用。生产状态接口默认只监听本机地址，不应直接暴露到外网。

关键设计说明：

dingtalk-dsh-assistant

安装

源码

标签

作者

说明文档