dingtalk-agent

钉钉数字员工的标准范式：CLI（拦）+ Skill（劝）。

零运行时依赖。任何 Coding Agent（Claude Code / Codex / …）init 即用。

npm i -g dingtalk-agent

mkdir my-agent && cd my-agent
dingtalk-agent init          # 铺出工作区
# 填 ontology/self/ 的三件套
dingtalk-agent boot          # 真去摸一遍工位，拉不到就 BOOT FAIL

范式

| | | | |---|---|---| | CLI | 拦 | 标准动作：可程序化、可强制、可验证。撞上去没得商量 | | Skill | 劝 | 判断：只有 LLM 能做的——该不该答、话题归属、怎么写点评 | | 本体 | 记 | 我是谁 + 我知道什么。git clone 就带走 |

分界线：凡是能程序化的，收进 CLI；凡是需要判断的，留在 Skill。

因为文档会被漏读、误读、自我说服；撞到闸门上就没得商量。

三个判定（现场可测）

1. 不喊它，它自己会动吗？ → 事件。答否，只是聊天框。
2. 昨天教它的，今天还记得吗？ → 存储。答否，永远是新来的。
3. 它干的事，能查、能撤、能追责吗？ → 身份。答否，没人敢让它真干活。

知识库：所有权决定真值方向

| | owned（我的本体） | external（别人维护的） | |---|---|---| | 真值在 | Git（本地） | 钉钉（远端） | | 同步 | push 本地 → 钉钉（给人看） | pull 钉钉 → 本地（给我 grep） | | 冲突了 | 远端被人改过 → 停下来问 | 远端赢，本地缓存可丢弃 |

Git 是常量层，钉钉是可替换的暴露层。

dingtalk-agent kb mount --name 公司知识库 --from dingtalk:doc:<folderId> --own external
dingtalk-agent kb mount --name 本体      --from dingtalk:doc:<folderId> --own owned --local ontology
dingtalk-agent kb mount --name 团队wiki  --from local:/path/to/wiki --sync none

dingtalk-agent kb sync                  # 同步（漂移检测，绝不盲覆盖）
dingtalk-agent kb search "<关键词>"      # 跨所有挂载点搜（过期缓存会警告）

三种源：dingtalk:doc:<folderId>（最常见——很多组织根本没建"知识库"）· dingtalk:wiki:<spaceId> · local:<路径>

三个硬约束（全是踩出来的）：

1. 绝不双向自动 merge。 一个方向是真值，另一个是投影。
2. 重排版不是漂移。 钉钉会重写 markdown——用行级 diff 判漂移会每次都误报， 然后你就会开始无脑 --force，真漂移也一起覆盖掉。判据是"剥掉符号后的文字流"。
3. 缓存不新鲜就不许用。 拿着过期快照回答，比说"我不知道"危险得多。

命令面

init                          铺出工作区
boot                          冷启动：真去摸工位，拉不到就 BOOT FAIL

kb mount / list / sync / search

duty --check                  一拍两问之一（无事静默，退出码 0）
duty --run <值班>
todo                          把待办【拉全】（翻页，不漏循环件）

log --did … --asked … --conv X --issue X --msg X     答完落一行
feedback --kind 纠正|追问|认可 --text … --conv X     主人的下一句话
runs --conv <会话>                                   拉出整条对话流（训练素材）
evolve                                               这周该改什么

留痕：三个硬 ID

每行运行记录钉住 issue（翻得出运行过程）· conv（拉得出整条对话流）· msg（定位到那一句）。

缺了这三个，记录就只是一堆"我做了什么"，出了问题什么也追不到。

而且两个成败必须分开：

• r = 引擎层（命令跑通没有）
• fb = 用户层（主人认不认）

引擎跑通 ≠ 答对 ≠ 主人满意。只看 r，你会看到一片绿，然后什么也进化不了。

六条铁律

1. 人能读。 裸 ID 必须紧跟中文名。技能不是私有格式，是人和 Agent 的共同契约。
2. 渐进披露。 上下文是成本，步数是延迟。"能不能做到"只是及格线，"几步做到"才是分数。
3. 本体不乱动。 骨骼可以长，但不能天天重接。
4. 驱动靠心跳，不靠待办。 待办是给人的，心跳是 Agent 的生理。 把"永远做不完的义务"塞进"有终态的待办"，链一断就静默漏执行且不自知。
5. 不许本地自证。 回平台真派一次，而且要看执行过程。
6. 环境正面修，不绕过。

一条例外：当一条自定的约束成了阻塞，先解阻塞。 规矩是为了让事情成立，不是为了守规矩。

依赖

• node >= 18.3
• dws —— 钉钉的 CLI（Agent 在钉钉上的行动界面）
• 零 npm 运行时依赖

License

MIT