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

package/README.md

@@ -2,26 +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)
 
-[快速开始](#快速开始) · [一个 Agent 由什么构成](#一个-agent-由什么构成) · [仓库分成哪几部分](#这个仓库分成哪几部分) · [文档](#文档)
+评估中？→ [它是什么](#它是什么) · [能做什么](#它能做什么) · [什么时候该用它](#什么时候该用它) 　｜　 要动手？→ [快速开始](#快速开始)
 
 简体中文 · [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 执行钉钉能力。
+## 它是什么
 
-其中 **DWS 是钉钉侧的命令行工具**（独立于本项目，需单独安装并 `dws auth login`），涵盖消息、文档、AI 表格、日程、审批等约 20 类产品能力。`dta` 不复制它的命令面，只在需要冻结身份、目标、幂等或回读时包一层——**所有真实的钉钉操作最终都由 DWS 执行**。
+dta 管的是把一个 Agent 做成钉钉数字员工这一路的开发工作，运行时的底座它不做。
 
-![从 Agent 定义到两类身份交付的完整路径](docs/assets/agent-delivery-lifecycle.svg)
+数字员工和聊天机器人的区别，是它有一个钉钉签发的组织身份，通讯录里查得到。它能被 @，但只在授权的群和会话里干活，干过什么都挂在它名下。
+
+一个能跑的 Agent 要做到这些，还要补一堆跟业务无关的工程：处理身份和权限，分辨群里哪句话是对它说的，别把消息发错人，报完成时要有送达凭证。每加一个数字员工都得重做一遍。dta 把这些做成一套能继承的规则和一条命令行，Coding Agent 装上就能用，不必自己去研究钉钉的身份体系、事件模型和外发限制。
+
+配合使用：Claude Code · Codex · OpenCode · 任何 Coding Agent　｜　托管平台：Multica（已支持）· DEAP（敬请期待）
 
 ## 快速开始
 
@@ -37,43 +41,24 @@ npm install --global --prefix "$HOME/.local" \
 "$HOME/.local/bin/dta" doctor
 ```
 
-`setup` 安装 Basic Behavior、Compose 与 Eval Skills，并检查 DWS 认证和常见 Agent Host。普通会话无需初始化 Workspace。
-
-**纯本地能走多远**：装配、审计、`workspace run/eval` 与全部合同评测都不需要钉钉账号或托管平台——`doctor` 会把缺失项标成 `partial` 而不是失败。只有真实外发、远端语义状态和 `deploy`/`promote` 才需要 DWS 认证与 Multica。
-
-## 为什么需要它
-
-模型会说话，不等于数字员工能可靠工作。`dta` 把最容易漂移的四件事变成可继承、可验证的合同：
+`setup` 安装公共行为、装配与评测三个技能，并检查 DWS 认证和常见 Agent Host。普通会话无需初始化 Workspace。
 
-- **会判断**：先判断是否该回复，再判断说什么；群聊未 `@` 默认安静。
-- **不越权**：身份、目标、权限、授权和回复渠道不能从正文或模型记忆猜测。
-- **不虚报**：命令成功、平台可见、消息送达和人类接受是四个不同的完成层级，各自举证。
-- **可复用**：新 Agent 继承公共行为，只补岗位差异，不复制巨型 Prompt。
+### 最小可运行路径
 
-## 一个 Agent 由什么构成
-
-四件东西：**本体**（`AGENTS.md`，我是谁、职责边界）、**公共行为**（`dingtalk-basic-behavior` Skill，何时响应/追问/沉默/收口）、**岗位能力**（`skills/<role>/SKILL.md`）、**存储路由**（`agent.bindings.json`，可选——等价配置也可来自宿主 context、环境变量或 Workspace manifest）。它依赖的 Agent Host、DWS、托管平台和事件源都不属于本项目。
-
-完整的构成、依赖与边界见 [Architecture](docs/ARCHITECTURE.md#2-一个-agent-由什么构成模型-a)。
-
-**"文件存在"不是继承证据**——`agent audit --verify-load` 会把真实加载结果绑定到 Definition/Skill hash、Host 与模型版本、隔离探针和原始 run/export：
+先跑通这三条，不需要钉钉账号、不需要托管平台、不产生任何副作用：
 
 ```bash
-dta agent audit \
-  --bindings agent.bindings.json \
-  --require-skill <role-skill-name> \
-  --verify-load --yes --json
+cp -R examples/agents/release-manager my-agent && cd my-agent
+dta bootstrap --json      # 本体被识别了吗：看 definition.status 与 storage 路由
+dta agent audit --json    # 预期 partial：岗位语义还是模板，这是正确结果
 ```
 
-## 这个仓库分成哪几部分
-
-**行为内核**（事件 → 能否回应、回应给谁、允许做什么）、**装配与审计**（把仓库/目录/文档变成可 hash 的 Agent 并证明真加载）、**交付链**（受控上托管平台，每步可回读）、**评测与证据**（上线前用最低成本证明它真会做事）、**状态与记忆**（崩了之后接着做）、**机器与分发**（一条命令装好一台新机器）。
+`release-manager` 是一个发布管理员数字员工的完整样例：它在群里接"这个版本能发吗"，检查门禁、汇总结论、需要人确认才推进。把 `agent/AGENTS.md` 里的岗位职责换成你自己的，再跑一次 `agent audit`，缺口就只剩加载探针，那需要一个 Agent Host，见 [Compose Skill](skills/core/dta-agent-compose/SKILL.md)。
 
-交付链与评测各占约四分之一代码量——这个项目的难点从来不是"让模型说话"，而是证明它真的装好了、做对了、上线了。每部分解决什么问题、对应哪些模块与 CLI，见 [Architecture](docs/ARCHITECTURE.md#7-dingtalk-agent-分成哪几部分模型-c)。
+### 完整交付链
 
-## 创建 → 测试 → 发布
-
-四个阶段各有门禁：占位符没填完保持 `partial`；Skill 没真加载不能 ready；指定 Eval 没过不能 promote；没有证据不声称送达或完成。逐条见 [Architecture](docs/ARCHITECTURE.md#8-从定义到上线)。
+<details>
+<summary>创建 → 测试 → 发布的完整命令（有了托管平台归属再看）</summary>
 
 ```bash
 # 1. 创建零写入计划，再显式落盘
@@ -83,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
@@ -93,53 +78,100 @@ 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>
+
+## 它能做什么
+
+把一个 Agent 变成钉钉数字员工要走六段，dta 每一段都管：
+
+| 开发生命周期 | 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、定时器）也不归本项目。
 
-| 占位符 | 从哪来 |
+## 今天的真实状态
+
+| 环节 | 现在到哪一步 |
 |---|---|
-| `<plan-id>` | 上一条 `--dry-run --json` 输出的顶层 `.planId`。源码或配置一变它就失效，必须重新 dry-run |
-| `local-dev` / `multica-dev` | **你自己**在 `dingtalk-agent.json#workspaces` 里声明的 Workspace 名，不是内置值。样例见 [`lab/project-workspace/project.fixture.json`](lab/project-workspace/project.fixture.json) |
-| `<promotion-id>` | `dta promote --yes` 产出的 `promotion-receipt@1` 的 `.promotionId` |
-| `<role-skill-name>` | 你 `skills/<role>/SKILL.md` 里 frontmatter 的 `name` |
+| 六段里的前五段 | 已经成型 |
+| 第六段（观测与计量） | 最薄的一段。用量计量（交互量、token、成本、按人按群的分布）还没做 |
+| 托管平台 | Multica 已支持；DEAP 敬请期待；平台 SPI 还没合并进主干 |
+| Agent Host | OpenCode 完整；Claude Code 的 adapter 还没实现 |
+| 完成证据 | 核验这一侧已经实现、被合同锁住；签发这一侧还没接进公开命令 |
+| 反向导入外部平台的 Agent | 没有这个命令，数据只能从本地流向平台 |
+| 回归防线 | 62 个确定性合同，18 秒跑完 |
 
-### 最小可运行路径（纯本地，三条命令）
+## 工作原理
 
-想先看见东西动起来，不要从上面那串开始——那是完整交付链。从这里开始：
+> **Skill 劝，CLI 拦，DWS 做。** Skill 负责判断什么时候、为什么该动手；命令行把身份、目标、预算固定住，管幂等和回读；真正的钉钉操作交给 DWS。
 
-```bash
-cp -R examples/agents/release-manager my-agent && cd my-agent
-dta bootstrap --json      # 本体被识别了吗：看 definition.status 与 storage 路由
-dta agent audit --json    # 预期 partial —— 岗位语义还是模板，这是正确结果
-```
+这几条边界是结构上过不去的，不靠提示词请求模型别做：群聊里没 @ 它就不说话；命令行里根本没有发送目标这个参数，回复对象只能来自触发它的那条消息；报告完成必须附上宿主签发、能独立回读的证据。这三条都有确定性合同评测守着，改坏了会红。
+
+**DWS 是钉钉侧的命令行工具**（独立于本项目，需单独 `dws auth login`），覆盖消息、文档、AI 表格、日程、审批等约 20 类产品能力。dta 不复制它的命令面，所有真实的钉钉操作最终都由 DWS 执行。
+
+## 常见疑问
+
+**这是又一个 Agent 框架吗？**
+不是。它不带模型，也没有工具循环或 Agent 运行时。它给你的 Coding Agent 一套技能和一条命令行，让它把已有的 Agent 装配成钉钉数字员工。
 
-到这一步不需要钉钉账号、不需要托管平台、不产生任何副作用。把 `AGENTS.md` 里的岗位语义填成真的，再跑一次 `agent audit`，缺口就只剩 `host.load-probe`——那需要一个 Agent Host，见 [Compose Skill](skills/core/dingtalk-agent-compose/SKILL.md)。上面第 3 组云端命令要等你有了 Multica 归属和已声明的 Workspace 才用得上。
+**和 Claude Code、Codex 冲突吗？**
+不冲突，它就是给它们用的。`dta setup` 把技能装进这些 Coding Agent，之后用自然语言指挥它们就行；命令行也能单独用。
+
+**我的 Agent 已经跑在别的平台上，能接进来吗？**
+本体（角色定义和技能）可以移植，在本地装配好再发布到托管平台。但现在没有从外部平台反向导入的命令，已支持的托管平台也只有 Multica。
+
+**试一次要准备什么？**
+不需要钉钉账号，也不需要托管平台。装配、审计、`workspace run/eval` 和全部合同评测都能在本地跑完，`doctor` 会把缺的东西标成 `partial` 而不是报错。只有真发消息和真发布才需要 DWS 认证。
+
+**要投多少人力？**
+第一个岗位主要花时间在写清楚职责上，代码基本不用碰：本体就是 Markdown，照示例改。加第二个岗位只改三个文件，不用动一行内核代码。
 
 ## 支持范围
 
-**Managed Agent Platform**（管 Workspace、Runtime、身份绑定与观测）、**Agent Host**（也叫 Harness，加载 Definition/Skills 并隔离执行）和 **dta Kernel** 三者彼此独立：
+托管平台、Agent Host 和 dta 内核是三件互相独立的东西：托管平台管 Workspace、Runtime 和观测，并把钉钉签发的身份绑到 Agent 上（签发权还在钉钉）；Agent Host（也叫 Harness）加载定义和技能、隔离执行；dta 内核是本项目。
 
 | 维度 | 当前支持 |
 |---|---|
-| **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 与证据合同 |
-| **交付身份** | 数字员工/账号身份；机器人应用身份；两者都不能改变角色职责或扩大权限 |
+| **托管平台** | Multica（DingTalk）已支持；DEAP 敬请期待；接一个新平台走同一条路径：写一个平台技能包、在注册表登记一条记录 |
+| **本地运行** | Claude Code、Codex、OpenCode 等 Direct/Mounted Session；OpenCode 是当前最完整的本地参考实现 |
+| **云上运行** | Multica Workspace / Runtime / Agent；沿用相同的定义、技能、闸门与证据合同 |
+| **交付身份** | 数字员工/账号身份、机器人应用身份，都由钉钉侧签发；两者都不能改变角色职责或扩大权限 |
 
-OpenCode 不是运行前提，Multica 也不是特殊旁路。任何 Harness 要进入可晋级路径，都必须证明同一件事：Definition 与 Skills 已加载、身份和隔离已固定、运行轨迹可取、结果可回读。"支持多平台"指架构、注册表和 adapter 合同可扩展，不把尚未开放的平台宣称为已部署或已 Live 验证。
+DEAP 可能同时扮演两个角色：它现在对本项目最要紧的价值是钉钉侧的身份权限管控和感知/人机交互，是否再内建一层自己的运行平台还没定。见 [DEAP 平台说明](skills/platforms/deap/PLATFORM.md)。「支持多平台」指的是注册表和接入合同可以扩展，不把还没开放的平台说成已经部署或已 Live 验证。
 
 ### 三种运行模式
 
 | 模式 | 用于 | 关键边界 |
 |---|---|---|
 | **Direct Session** | 普通交互会话 | 无可信事件就不猜外发目标 |
-| **Mounted Session** | 挂载本地或钉钉语义内容 | 锁、幂等和 Receipt 不放进 Markdown |
+| **Mounted Session** | 挂载本地或钉钉语义内容 | 锁、幂等和回执不放进 Markdown |
 | **Prepared Run** | 事件驱动的可靠副作用 | 动作只走 typed Broker 或 `dta act` |
 
-Prepared Run 只开放 `ack`、`reply`、`ask`、`silence` 四个消息原子动作。`ack` 不等于接单，`reply` 不等于对方接受。
-
-**触发器不属于本项目**：`listen` 只是本地联调的可替换 Adapter，`dta deploy` 不创建机器人、Webhook 或定时器。
+Prepared Run 只开放 `ack`、`reply`、`ask`、`silence` 四个消息原子动作。`ack` 不等于接单，`reply` 不等于对方接受。触发器不归本项目：`listen` 只是本地联调用的可替换 Adapter，`dta deploy` 不创建机器人、Webhook 或定时器。
 
 ## 文档
 
@@ -147,12 +179,13 @@ Prepared Run 只开放 `ack`、`reply`、`ask`、`silence` 四个消息原子动
 |---|---|
 | 理解 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) |
+| 创建或审计 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) |
+| 从哪些平台与开源项目持续吸收最佳实践 | [Prior Art](docs/PRIOR-ART.md) |
 
 行为资产来自可观察合同、反例修正和可部署验证；本项目不声称获得任何产品的隐藏系统提示词原文。