open-dingtalk-executive

npm 安装与启动

需要 macOS / Linux（Windows 使用 WSL）、Bash、npm 和 Node >=26.8.1 <27。当前准备发布的首版为 0.1.0-beta.1；首次发布完成后可执行：

npm install -g @open-dingtalk/executive@beta --registry=https://registry.npmjs.org/
opendingtalk

opendingtalk 默认启动 assistant。首次运行会安装指定版本的 pnpm 和 DWS、引导设备登录，再提示输入模型 API Key、DWS profile、员工本人 ID、允许的会话与发送人、主管 ID。API Key 隐藏输入。仅指定会话内的指定人员可以驱动员工，主管也必须在允许名单内。

配置、会话与运行文件默认放在 ~/.opendingtalk，与 npm 安装目录分开；使用 --home /绝对路径 或 OPENDINGTALK_HOME 指定其他目录。现有源码部署保持使用原来的 make / bin/employee；npm 命令不会自动接管当前仓库中的进程。

opendingtalk init                 # 只完成配置
opendingtalk login                # 重新登录钉钉并查看 profile
opendingtalk                      # 后台启动，重复执行检查现有进程
opendingtalk run                  # 前台运行，Ctrl-C 正常退订
opendingtalk status
opendingtalk logs
opendingtalk stop
opendingtalk restart
opendingtalk doctor
opendingtalk build                # 修改员工 patch 后重新组装
opendingtalk --employee hr        # 制度问答岗位，需额外配置知识库
opendingtalk upgrade              # 保持当前 stable / beta 通道
opendingtalk upgrade --beta       # 使用 beta 通道
opendingtalk upgrade --stable     # 切换稳定版（首次稳定版发布后可用）

升级前先停止该目录的全部员工和 router。upgrade 更新全局 npm 包，下次启动同步模板并按需重新组装。.env、真实员工配置、var/ 会话和本地新增文件均保留；若发行模板文件存在本地修改，同步会列出冲突并停止，请先备份、合并并移走冲突文件后重试。升级不会自动重启进程。源码修改的插件随新包一起升级，用户自己的岗位 patch 需人工合并。

无人值守初始化可使用 opendingtalk init --config /绝对路径/config.json。以下文件包含密钥，请限制读取权限；配置成功后按需移除输入文件。再次传 --config 会明确替换该目录的共享模型配置和所选员工配置，请先停止进程。

{
  "apiKey": "你的模型 API Key",
  "baseUrl": "https://api.deepseek.com",
  "profile": "corpId:userId",
  "selfId": "员工视角的自身 openDingTalkId",
  "conversationId": "允许对话的 openConversationId",
  "senders": ["主管 openDingTalkId"],
  "supervisor": "主管 openDingTalkId",
  "port": 3082
}

hr 需额外提供 workspaceId，默认端口 3081，并在运行目录补齐知识库 var/kb-push/manifest.json 和 employees/hr/access.json 中的真实授权。引导创建的访问控制默认为拒绝；知识库内容与授权不会自动发布或放开。首次启动需要联网下载依赖，登录过期时使用 opendingtalk login 续期。

打包、账号准备和 Tag 自动发布见 npm 发布说明。

开发和部署钉钉数字员工的项目。Harness 用 deepseek-harness（dsh， 从 npm 装，版本 pin 在 package.json + pnpm-lock.yaml），所有能力通过 dsh 插件实现， profile 按员工 spec 组装。

当前有两个员工：hr（制度政策问答）和 assistant（Boss 秘书：收任务 → LLM 规划 → 主管审批 → 真执行 → 双向反馈）。两者共用同一个 dws 登录态，由 router/ 扇出消息 —— 否则钉钉 Stream 随机单播，约 50% 消息静默丢失。

架构一览

图示为多员工共用一个 DWS 账号：Router 只广播，准入与寻址由各员工处理。 各员工独立运行 DSH，按 profile 装配插件，并保存各自的会话与状态。点击图可查看 SVG 大图。

用 coding agent 上手（推荐）

checkout 后直接用 Claude Code（或任意 coding agent）打开本项目，发一句提示词：

帮我配置并启动钉钉数字员工

agent 以 CLAUDE.md 为索引、以 docs/ 为深水区完成初始化。 LLM 凭据只填 .env；钉钉侧走 dws 的 OAuth 登录态，不填也能 build。

手动快速开始

nvm use                   # node 版本见 .nvmrc（engines >=26.8.1 <27）
cp .env.example .env      # 只填 LLM 凭据
make build                # 装 dsh（版本 pin）+ 组装 profile 到 var/<NAME>/
make start                # 启动
make status               # 端口在听 ≠ 钉钉链路活着，status 才查订阅
make reset                # 改配置后、钉钉侧验证前必做，否则模型照抄旧会话答案

多员工：make start NAME=assistant（一员工 = 一进程 = 一 var/<name>/）。 命令全集见 make help。

两个 checkout 后容易踩的坑

• 别按包名写 modules。 _base.patch.yml 禁掉的是 client 产物注册表（无头部署不渲染界面）， entry id 是 modules，包名才是 @deepseek-ai/dsh-client-modules —— 按包名写静默无效，make check 抓过。
• bin/employee 里的 cd "$REPO" 和 exec 不能删。 dsh 的 app-boot 扫的是 invocation cwd 的 .env；exec 保证 SIGTERM 直达 dsh、让插件退订 dws 事件 （中间不能有吞信号的包装进程，停机也绝不 kill -9）。

文档

| 你想干什么 | 读这篇 | |---|---| | 给 coding agent 的索引、十条硬红线、目录结构 | CLAUDE.md | | 排查钉钉链路（不回消息、丢一半、准入、出站） | docs/dws-event-consume.md | | 改 profile / patch / 写新插件 | docs/dsh-机制.md | | 加语料、改检索 | docs/知识库与检索.md | | 加 eval、写闸门、开源脱敏 | docs/spec-与-evals.md | | 部署、容器、升级 dsh、换机迁移 | docs/部署.md | | Employee Loop 与审批流的设计 | docs/degital-employee-loop.md | | 某个员工能做什么 | employees/hr/SPEC.md · employees/assistant/SPEC.md | | 这个项目是怎么被「说」出来的 | docs/runbook/ |