@xdxer/dingtalk-agent 0.1.4 → 0.1.5-beta.10

package/README.md

@@ -2,24 +2,30 @@
 
 # dingtalk-agent
 
-**让数字员工继承同一套可验证的行为底座。**
+**让你的 Coding Agent 把现成的 Agent 装成钉钉数字员工。**
 
 [![npm](https://img.shields.io/npm/v/%40xdxer%2Fdingtalk-agent?logo=npm&color=cb3837)](https://www.npmjs.com/package/@xdxer/dingtalk-agent)
 [![CI](https://github.com/D1-2004/dingtalk-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/D1-2004/dingtalk-agent/actions/workflows/ci.yml)
 [![Node.js](https://img.shields.io/node/v/%40xdxer%2Fdingtalk-agent)](https://nodejs.org/)
 [![License](https://img.shields.io/badge/license-MIT-2ea44f)](LICENSE)
 
-[快速开始](#快速开始) · [工作方式](#工作方式) · [支持范围](#支持范围) · [文档](#文档)
+评估中？→ [它是什么](#它是什么) · [能做什么](#它能做什么) · [什么时候该用它](#什么时候该用它) 　｜　 要动手？→ [快速开始](#快速开始)
 
 简体中文 · [English](README.en.md)
 
 </div>
 
-`dingtalk-agent`（`dta`）是钉钉数字员工的 **Skill-first 行为内核与交付工具链**。它把角色定义、公共行为、岗位能力和执行门禁装配成一个可创建、测试、发布和审计的 Agent Project。
+![在群里 @ 它，它会像同事一样把事做完，中间每一步都有记录](docs/assets/digital-employee-at-work.svg)
 
-> **Skill 劝，CLI 拦，DWS 做。** Skill 判断何时、为何行动；CLI 固定身份、目标、预算、幂等与回读；DWS 执行钉钉能力。
+## 它是什么
 
-![从 Agent 定义到两类身份交付的完整路径](docs/assets/agent-delivery-lifecycle.svg)
+dta 管的是把一个 Agent 做成钉钉数字员工这一路的开发工作，运行时的底座它不做。
+
+数字员工和聊天机器人的区别，是它有一个钉钉签发的组织身份，通讯录里查得到。它能被 @，但只在授权的群和会话里干活，干过什么都挂在它名下。
+
+一个能跑的 Agent 要做到这些，还要补一堆跟业务无关的工程：处理身份和权限，分辨群里哪句话是对它说的，别把消息发错人，报完成时要有送达凭证。每加一个数字员工都得重做一遍。dta 把这些做成一套能继承的规则和一条命令行，Coding Agent 装上就能用，不必自己去研究钉钉的身份体系、事件模型和外发限制。
+
+配合使用：Claude Code · Codex · OpenCode · 任何 Coding Agent　｜　托管平台：Multica（已支持）· DEAP（敬请期待）
 
 ## 快速开始
 
@@ -29,42 +35,30 @@
 npm install --global --prefix "$HOME/.local" \
   --registry=https://registry.npmjs.org @xdxer/dingtalk-agent@beta
 
+# setup 会把 PATH 区块写进 ~/.zshrc 或 ~/.bashrc，但子进程改不了当前 shell，
+# 所以这一轮继续用绝对路径；之后开新终端即可直接用 `dta`。
 "$HOME/.local/bin/dta" setup --skip-cli-install
-dta doctor
+"$HOME/.local/bin/dta" doctor
 ```
 
-`setup` 安装 Basic Behavior 与 Compose Skills，并检查 DWS 认证和常见 Agent Host。普通会话无需初始化 Workspace。
-
-## 为什么需要它
-
-模型会说话，不等于数字员工能可靠工作。`dta` 把最容易漂移的部分变成可继承、可验证的合同：
-
-- **会判断**：先判断是否该回复，再判断说什么；群聊未 `@` 默认安静。
-- **不越权**：身份、目标、权限、授权和回复渠道不能从正文或模型记忆猜测。
-- **不虚报**：命令成功、平台可见、消息送达和人类接受是不同的完成层级。
-- **可复用**：新 Agent 继承公共行为，只补岗位差异，不复制巨型 Prompt。
+`setup` 安装公共行为、装配与评测三个技能，并检查 DWS 认证和常见 Agent Host。普通会话无需初始化 Workspace。
 
-## 工作方式
+### 最小可运行路径
 
-一个 Agent 由四层合同组成：
+先跑通这三条，不需要钉钉账号、不需要托管平台、不产生任何副作用：
 
-| 层 | 负责什么 |
-|---|---|
-| **`AGENTS.md`** | 定义角色、岗位底线、做事范式和常犯错误；声明每轮先应用 Basic |
-| **Basic Behavior** | 所有数字员工共享的响应资格、作用域、授权、隐私、完成与记忆协议 |
-| **Role Skills** | 某个岗位的专业判断、流程、禁区和验收标准 |
-| **Gate + Receipt** | 把身份、目标、预算、幂等、状态迁移和平台回读变成硬约束 |
+```bash
+cp -R examples/agents/release-manager my-agent && cd my-agent
+dta bootstrap --json      # 本体被识别了吗：看 definition.status 与 storage 路由
+dta agent audit --json    # 预期 partial：岗位语义还是模板，这是正确结果
+```
 
-Prompt 只保留必须常驻、必须严格定义的内容；完整行为树进入 Skill；不能依赖模型自觉的约束进入 Gate。
+`release-manager` 是一个发布管理员数字员工的完整样例：它在群里接"这个版本能发吗"，检查门禁、汇总结论、需要人确认才推进。把 `agent/AGENTS.md` 里的岗位职责换成你自己的，再跑一次 `agent audit`，缺口就只剩加载探针，那需要一个 Agent Host，见 [Compose Skill](skills/core/dta-agent-compose/SKILL.md)。
 
-### 创建 → 测试 → 发布
+### 完整交付链
 
-| 阶段 | 关键产物 | 门禁 |
-|---|---|---|
-| **创建** | `AGENTS.md`、Basic、Role Skills、bindings | 占位符未补全时保持 `partial` |
-| **测试** | 隔离 Workspace、load probe、行为评测、四类证据 | Definition/Skills 没有真实加载就不能 ready |
-| **发布** | 平台预检、部署 Receipt、远端 readback | 指定 Eval 未通过或身份链不完整就不能 promote |
-| **运行** | 数字员工账号或机器人入口、task trace | 无证据不声称写入、送达或完成 |
+<details>
+<summary>创建 → 测试 → 发布的完整命令（有了托管平台归属再看）</summary>
 
 ```bash
 # 1. 创建零写入计划，再显式落盘
@@ -74,8 +68,8 @@ dta agent enhance --project-name release-agent --role-skill release-manager \
 
 # 2. 审计、运行与评测
 dta agent audit --bindings agent.bindings.json --require-skill release-manager --json
-dta workspace run local-dev --json
-dta workspace eval local-dev --json
+dta workspace run local-dev --prompt-file prompt.md --execute --yes --json
+dta workspace eval local-dev --suite evals/suite.json --execute --yes --json
 
 # 3. 云端预检、发布与观测
 dta workspace inspect multica-dev --execute --yes --json
@@ -84,83 +78,114 @@ dta promote --source local-dev --target multica-dev --dry-run --json
 dta observe --promotion-id <promotion-id> --input <observation.json> --dry-run --json
 ```
 
-所有计划默认零写入；所有远端写入都需要明确目标、当前 `planId` 和显式确认。
+所有计划默认零写入；所有远端写入都需要明确目标、当前 `planId` 和显式确认。`<plan-id>` 来自上一条 dry-run 输出的 `.planId`，`local-dev` / `multica-dev` 是你自己在 `dingtalk-agent.json#workspaces` 里声明的名字。四个阶段各有门禁：占位符没填完保持 `partial`；技能没真加载不能 ready；指定评测没过不能 promote；没有证据不声称送达或完成。逐条见 [Architecture](docs/ARCHITECTURE.md#8-开发生命周期从定义到观测)。
 
-## 支持范围
+</details>
 
-### 平台、Harness 与运行时
+## 它能做什么
 
-这三个概念彼此独立：
+把一个 Agent 变成钉钉数字员工要走六段，dta 每一段都管：
 
-- **Managed Agent Platform** 管 Workspace、Runtime、Agent、Skill、身份绑定和观测。
-- **Agent Harness** 加载 Definition/Skills，隔离执行并采集证据。
-- **dta Kernel** 依赖统一合同，不依赖某个 Harness 的私有 Prompt 或目录结构。
+| 开发生命周期 | dta 做的 | 用什么 |
+|---|---|---|
+| **① 本体与员工技能** | 一套可继承、可验证的共享行为合同：什么时候该开口、消息算不算任务、外部动作要谁批准、风险怎么分级、什么算完成、哪些要记哪些能忘。你只写岗位不一样的那几十行 | `dta-basic-behavior` · `agent enhance` · `examples/agents/` |
+| **② 身份获取与事件感知** | 把格式各异的原始事件归一成稳定结构。回复对象和执行身份会冻结成正文改不动的快照，发错人在结构上就做不到；权限和出口按场域绑定；同一个事件只产生一个 Run，崩了也不会丢、不会重复 | `prepare` · `run` · Field 配置 |
+| **③ 托管平台部署** | 先看计划再落盘：冻结本体和整棵 Skill 树的 hash 和写预算，写完独立回读、发加载烟测，重复跑同一版不再写入。出问题能回滚，上了线也能退役（当前落地于 Multica） | `deploy` · `promote` · `--retire` |
+| **④ 驱动它在钉钉里干活** | 外发就四个原语。动作做之前挡掉越权和发错目标，做完之后强制回读平台确认；结果不确定时不许乱重发，报完成得留下能再核验的证据 | `act` · Action Gate · `task checkpoint` |
+| **⑤ 评测设计** | 一套评测方法：帮你选够用的最低层级，决定一次结论要看哪几类证据，避免个别失败被平均分掩盖，把真实事故变成能复跑的用例，也给出什么时候不能上线 | `lab` · `workspace eval` · `dta-agent-eval` |
+| **⑥ 观测与反馈** | 把线上发现的问题绑定到具体哪一版，脱敏后回流评测素材，不会自动改动 Agent 的行为 | `observe` |
 
-| 维度 | 当前支持 |
+## 什么时候该用它
+
+适合用它的情况：
+
+- 你已经有一个能跑的 Agent，想让它以组织身份进钉钉群，被 @、被派活；
+- 你有钉钉自动化在跑，出过发错人、或者命令返回 0 就当成功这类事故；
+- 你要做好几个数字员工，不想把公共行为在每份提示词里各复制一遍、越改越不一样；
+- 你的活儿跨天、要等人确认、中途可能被叫停，不是一问一答；
+- 你要向别人证明线上跑的就是你调好的那一版。
+
+用不上它的情况：
+
+- 你只要一个问答机器人：一个钉钉机器人 webhook 就够了，这一套对你是多余的；
+- 你只是要调钉钉 API：直接用 DWS，它本来就能用，dta 不是前置；
+- 你不在钉钉生态：唯一的执行出口是 DWS、身份由钉钉签发，换不掉。
+
+今天还做不到：把已经部署在别的平台上的 Agent 导入进来（数据只能从本地流向托管平台，没有 import 命令）；事件触发器（Webhook、定时器）也不归本项目。
+
+## 今天的真实状态
+
+| 环节 | 现在到哪一步 |
 |---|---|
-| **Managed Platform** | Multica（DingTalk）已支持；DEAP 为 Coming soon；更多平台通过 registry + adapter 接入 |
-| **本地运行** | Claude Code、Codex、OpenCode 等 Direct/Mounted Session；OpenCode 是当前完整的本地 managed Harness 参考实现 |
-| **云上运行** | Multica Workspace / Runtime / Agent；沿用相同的 Definition、Skills、Gate 与证据合同 |
-| **交付身份** | 数字员工/账号身份；机器人应用身份；两者都不能改变角色职责或扩大权限 |
+| 六段里的前五段 | 已经成型 |
+| 第六段（观测与计量） | 最薄的一段。用量计量（交互量、token、成本、按人按群的分布）还没做 |
+| 托管平台 | Multica 已支持；DEAP 敬请期待；平台 SPI 还没合并进主干 |
+| Agent Host | OpenCode 完整；Claude Code 的 adapter 还没实现 |
+| 完成证据 | 核验这一侧已经实现、被合同锁住；签发这一侧还没接进公开命令 |
+| 反向导入外部平台的 Agent | 没有这个命令，数据只能从本地流向平台 |
+| 回归防线 | 62 个确定性合同，18 秒跑完 |
 
-OpenCode 不是运行前提，Multica 也不是特殊旁路。任何 Harness 要进入可晋级路径，都必须证明同一件事：Definition 与 Skills 已加载、身份和隔离已固定、运行轨迹可取、结果可回读。
+## 工作原理
 
-“支持多平台”指架构、注册表和 adapter 合同可扩展；不把尚未开放的平台宣称为已部署或已 Live 验证。
+> **Skill 劝，CLI 拦，DWS 做。** Skill 负责判断什么时候、为什么该动手；命令行把身份、目标、预算固定住，管幂等和回读；真正的钉钉操作交给 DWS。
 
-### 三种运行模式
+这几条边界是结构上过不去的，不靠提示词请求模型别做：群聊里没 @ 它就不说话；命令行里根本没有发送目标这个参数，回复对象只能来自触发它的那条消息；报告完成必须附上宿主签发、能独立回读的证据。这三条都有确定性合同评测守着，改坏了会红。
 
-| 模式 | 用于 | 关键边界 |
-|---|---|---|
-| **Direct Session** | 普通交互会话 | 无可信事件就不猜外发目标 |
-| **Mounted Session** | 挂载本地或钉钉语义内容 | 锁、幂等和 Receipt 不放进 Markdown |
-| **Prepared Run** | 事件驱动的可靠副作用 | 动作只走 typed Broker 或 `dta act` |
+**DWS 是钉钉侧的命令行工具**（独立于本项目，需单独 `dws auth login`），覆盖消息、文档、AI 表格、日程、审批等约 20 类产品能力。dta 不复制它的命令面，所有真实的钉钉操作最终都由 DWS 执行。
 
-Prepared Run 只开放 `ack`、`reply`、`ask`、`silence` 四个消息原子动作。`ack` 不等于接单，`reply` 不等于对方接受。
+## 常见疑问
 
-## 创建出来的 Agent 会继承什么
+**这是又一个 Agent 框架吗？**
+不是。它不带模型，也没有工具循环或 Agent 运行时。它给你的 Coding Agent 一套技能和一条命令行，让它把已有的 Agent 装配成钉钉数字员工。
 
-```text
-my-agent/
-├── AGENTS.md                     角色宪法 + Basic 继承锚点
-├── agent.bindings.json           Definition 与存储路由
-├── dingtalk-agent.json           Agent Project 期望状态
-├── .agents/skills/
-│   ├── dingtalk-basic-behavior/  完整公共行为树
-│   └── <role>/                   Host 可发现的岗位 Skill
-├── skills/<role>/SKILL.md        岗位能力的版本化来源
-└── .dingtalk-agent/              私有状态、证据与 Receipt
-```
+**和 Claude Code、Codex 冲突吗？**
+不冲突，它就是给它们用的。`dta setup` 把技能装进这些 Coding Agent，之后用自然语言指挥它们就行；命令行也能单独用。
 
-生成的 `AGENTS.md` 只保留四块原子合同：**定义、不能做的底线、做事标准范式、常犯错误**。模板同时声明每个任务先应用 `dingtalk-basic-behavior`，再按任务加载 Role Skills。
+**我的 Agent 已经跑在别的平台上，能接进来吗？**
+本体（角色定义和技能）可以移植，在本地装配好再发布到托管平台。但现在没有从外部平台反向导入的命令，已支持的托管平台也只有 Multica。
 
-“文件存在”不是继承证据。`agent audit --verify-load` 会把真实加载结果绑定到 Definition/Skill hash、Host/模型版本、隔离探针和原始 run/export：
+**试一次要准备什么？**
+不需要钉钉账号，也不需要托管平台。装配、审计、`workspace run/eval` 和全部合同评测都能在本地跑完，`doctor` 会把缺的东西标成 `partial` 而不是报错。只有真发消息和真发布才需要 DWS 认证。
 
-```bash
-dta agent audit \
-  --bindings agent.bindings.json \
-  --require-skill <role-skill-name> \
-  --verify-load --yes --json
-```
+**要投多少人力？**
+第一个岗位主要花时间在写清楚职责上，代码基本不用碰：本体就是 Markdown，照示例改。加第二个岗位只改三个文件，不用动一行内核代码。
+
+## 支持范围
+
+托管平台、Agent Host 和 dta 内核是三件互相独立的东西：托管平台管 Workspace、Runtime 和观测，并把钉钉签发的身份绑到 Agent 上（签发权还在钉钉）；Agent Host（也叫 Harness）加载定义和技能、隔离执行；dta 内核是本项目。
 
-## 不可绕过的边界
+| 维度 | 当前支持 |
+|---|---|
+| **托管平台** | Multica（DingTalk）已支持；DEAP 敬请期待；接一个新平台走同一条路径：写一个平台技能包、在注册表登记一条记录 |
+| **本地运行** | Claude Code、Codex、OpenCode 等 Direct/Mounted Session；OpenCode 是当前最完整的本地参考实现 |
+| **云上运行** | Multica Workspace / Runtime / Agent；沿用相同的定义、技能、闸门与证据合同 |
+| **交付身份** | 数字员工/账号身份、机器人应用身份，都由钉钉侧签发；两者都不能改变角色职责或扩大权限 |
+
+DEAP 可能同时扮演两个角色：它现在对本项目最要紧的价值是钉钉侧的身份权限管控和感知/人机交互，是否再内建一层自己的运行平台还没定。见 [DEAP 平台说明](skills/platforms/deap/PLATFORM.md)。「支持多平台」指的是注册表和接入合同可以扩展，不把还没开放的平台说成已经部署或已 Live 验证。
+
+### 三种运行模式
+
+| 模式 | 用于 | 关键边界 |
+|---|---|---|
+| **Direct Session** | 普通交互会话 | 无可信事件就不猜外发目标 |
+| **Mounted Session** | 挂载本地或钉钉语义内容 | 锁、幂等和回执不放进 Markdown |
+| **Prepared Run** | 事件驱动的可靠副作用 | 动作只走 typed Broker 或 `dta act` |
 
-- 普通 Session 不自动运行 `dingtalk-agent init`。
-- target、actor、conversation、DWS profile 与权限只来自可信宿主或事件。
-- Prepared Run 的消息副作用只走 typed Broker 或 `dta act`，不能绕过 Gate。
-- 在线 Run 可以提出记忆或 Skill 候选，但不能热修改当前身份、权限或策略。
-- 模型自述、命令退出 0、平台写入可见、消息送达与人类接受必须分别举证。
+Prepared Run 只开放 `ack`、`reply`、`ask`、`silence` 四个消息原子动作。`ack` 不等于接单，`reply` 不等于对方接受。触发器不归本项目：`listen` 只是本地联调用的可替换 Adapter，`dta deploy` 不创建机器人、Webhook 或定时器。
 
 ## 文档
 
 | 想做什么 | 从这里开始 |
 |---|---|
-| 理解架构与状态模型 | [Architecture](docs/ARCHITECTURE.md) |
+| 理解 Agent 架构与仓库分工 | [Architecture](docs/ARCHITECTURE.md) |
 | 安装、升级与排障 | [Installation](docs/INSTALLATION.md) |
+| 接手一个已经在跑的 Agent（运行视角） | [Agent in Production](docs/AGENT-IN-PRODUCTION.md) |
 | 理解评测与证据分层 | [Self-test](docs/SELF-TEST.md) |
-| 创建或审计 Agent | [Compose Skill](skills/core/dingtalk-agent-compose/SKILL.md) |
-| 测试或调试已交付的 Agent | [Eval Skill](skills/core/dingtalk-agent-eval/SKILL.md) |
-| 查看公共行为协议 | [Basic Behavior Skill](skills/core/dingtalk-basic-behavior/SKILL.md) |
-| 复制完整示例 | [Example Agents](examples/agents) |
+| 创建或审计 Agent | [Compose Skill](skills/core/dta-agent-compose/SKILL.md) |
+| 测试或调试已交付的 Agent | [Eval Skill](skills/core/dta-agent-eval/SKILL.md) |
+| 查看公共行为协议（写给模型读的合同，不是教程） | [Basic Behavior Skill](skills/core/dta-basic-behavior/SKILL.md) |
+| 复制一个完整示例开始改 | [Example Agents](examples/agents) |
+| 从哪些平台与开源项目持续吸收最佳实践 | [Prior Art](docs/PRIOR-ART.md) |
 
 行为资产来自可观察合同、反例修正和可部署验证；本项目不声称获得任何产品的隐藏系统提示词原文。