@xdxer/dingtalk-agent 0.1.4-beta.8 → 0.1.4

package/README.md

@@ -2,313 +2,166 @@
 
 # dingtalk-agent
 
-**让 AI 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)
 
-[快速开始](#两分钟开始) · [核心模型](#核心模型) · [架构](#架构) · [行为协议](#数字员工行为协议) · [评测](#评测与验证)
+[快速开始](#快速开始) · [工作方式](#工作方式) · [支持范围](#支持范围) · [文档](#文档)
 
-</div>
-
-`dingtalk-agent` 是一个 **Skill-first 的钉钉数字员工行为框架**。它不内置模型，也不复制 DWS；它把“像同事一样工作”拆成三层：
-
-- **Basic Behavior Skill**：判断何时响应、追问、确认或保持沉默；
-- **CLI Runtime**：冻结身份、目标和事务边界，提供可审计的员工级原子动作；
-- **DWS**：执行钉钉消息、文档、待办、日历等具体产品能力。
-
-它可以被 Claude Code、Codex 或其他 Agent Host 使用，也可以作为更完整数字员工系统的基础蓝本。
-
-![dingtalk-agent Skill-first 架构](docs/architecture/dingtalk-agent-blueprint.png)
+简体中文 · [English](README.en.md)
 
-## 为什么需要它
+</div>
 
-“会调用钉钉 API”不等于“会像员工一样工作”。真实协作还要求 Agent：
+`dingtalk-agent`（`dta`）是钉钉数字员工的 **Skill-first 行为内核与交付工具链**。它把角色定义、公共行为、岗位能力和执行门禁装配成一个可创建、测试、发布和审计的 Agent Project。
 
-- 群里未被提及时默认不抢话，被 `@` 或私聊时才获得响应资格；
-- 信息完整就直接交付，只有真正阻塞时才问一个问题；
-- 不从消息正文猜收件人、身份、文档 ID 或权限；
-- 长任务能确认收到、等待依赖、从下一条事件继续，而不是假装一直在线；
-- 区分“命令执行过”“平台写入成功”“回读可见”和“对方确认”；
-- 将任务状态、长期记忆、运行时锁和幂等回执放在正确的存储层。
+> **Skill 劝，CLI 拦，DWS 做。** Skill 判断何时、为何行动；CLI 固定身份、目标、预算、幂等与回读；DWS 执行钉钉能力。
 
-本项目把这些约束从一段巨型 Prompt 中拆出来：**Skill 负责判断，CLI 负责硬边界，DWS 负责平台能力。**
+![从 Agent 定义到两类身份交付的完整路径](docs/assets/agent-delivery-lifecycle.svg)
 
-## 两分钟开始
+## 快速开始
 
-> 要求 Node.js 18.3+。CLI 固定安装到用户目录 `~/.local`，不依赖系统级写权限。
+要求 Node.js 18.3+。
 
 ```bash
 npm install --global --prefix "$HOME/.local" \
   --registry=https://registry.npmjs.org @xdxer/dingtalk-agent@beta
-"$HOME/.local/bin/dta" setup --skip-cli-install
-```
-
-这里不使用 `npx @xdxer/dingtalk-agent...` 启动自身。Why：机器上已有旧版 `dta` 时，npm exec 可能复用 PATH 中的旧 binary；`npm install --prefix` 会确定性替换用户级版本，随后绝对路径不依赖当前 shell 是否已刷新 PATH。
 
-`setup` 会按顺序完成四件事：
-
-1. 将 CLI 安装到用户目录 `~/.local/bin`，必要时幂等补充 shell PATH；
-2. 检查 Node.js、DWS 版本和 `dws auth status`；
-3. 安装并验证 Basic Behavior Skill；
-4. 报告 Claude Code、Codex、OpenCode 是否能够发现 Skill。
-
-当前终端尚未加载新 PATH 时，setup 会打印一条可直接执行的 `export PATH=...`。验证结果：
-
-```bash
-dta --version
+"$HOME/.local/bin/dta" setup --skip-cli-install
 dta doctor
 ```
 
-之后升级不再重复安装步骤，直接运行：
-
-```bash
-dta upgrade                       # beta 版默认继续跟随 beta
-dta upgrade --channel latest      # 显式切换稳定通道
-dta upgrade --dry-run             # 只查看目标版本和将执行的命令
-```
-
-升级完成后，新的 CLI 会自动重新执行 setup，复核 PATH、DWS、Skill 与三个 Agent 客户端。
-
-安装后推荐使用短命令 `dta`；完整名称 `dingtalk-agent` 与它完全等价。错误会同时输出原因和一条可复制的 `提示:`，命令或子命令拼错时会给出最接近的建议。
-
-安装后，Skill 只有一份 canonical copy：
-
-```text
-~/.agents/skills/dingtalk-basic-behavior/     # Codex、OpenCode 直接发现
-~/.claude/skills/dingtalk-basic-behavior      # Claude Code → canonical 相对链接
-```
-
-如果只想临时运行、不做用户级安装，任何命令都可以通过 npm exec 执行：
-
-```bash
-"$HOME/.local/bin/dta" doctor
-"$HOME/.local/bin/dta" skill install
-```
-
-也兼容开放的 `skills` CLI。仓库有访问权限时，可只安装 Skill 到三个客户端：
-
-```bash
-npx skills add D1-2004/dingtalk-agent \
-  --skill dingtalk-basic-behavior --global --yes \
-  --agent claude-code --agent codex --agent opencode
-```
-
-从本地 checkout 安装则使用：
-
-```bash
-npx skills add ./skills/dingtalk-basic-behavior \
-  --global --yes --agent claude-code --agent codex --agent opencode
-```
-
-`dta skill install` 内部也直接委托 `npx skills add`，不再维护独立的复制、软链、marker 或卸载链路。`npx skills` 只安装行为说明，不安装 `dingtalk-agent` CLI，也不检查 DWS；需要真实执行钉钉动作时仍应运行 `setup` 或 `doctor`。完整排障见 [安装与首次使用](docs/INSTALLATION.md)。
+`setup` 安装 Basic Behavior 与 Compose Skills，并检查 DWS 认证和常见 Agent Host。普通会话无需初始化 Workspace。
 
-普通 Agent 会话无需初始化项目。进入任意目录后可直接发现上下文：
-
-```bash
-dta bootstrap --json
-```
+## 为什么需要它
 
-只有可信事件宿主需要冻结目标并建立 Prepared Run：
+模型会说话，不等于数字员工能可靠工作。`dta` 把最容易漂移的部分变成可继承、可验证的合同：
 
-```bash
-mkdir fde-coach && cd fde-coach
-dta init
-dta prepare --event-file event.json --json
-```
+- **会判断**：先判断是否该回复，再判断说什么；群聊未 `@` 默认安静。
+- **不越权**：身份、目标、权限、授权和回复渠道不能从正文或模型记忆猜测。
+- **不虚报**：命令成功、平台可见、消息送达和人类接受是不同的完成层级。
+- **可复用**：新 Agent 继承公共行为，只补岗位差异，不复制巨型 Prompt。
 
-## 核心模型
+## 工作方式
 
-### 三种运行模式
+一个 Agent 由四层合同组成：
 
-| 模式 | 初始化 | 上下文 | 适用场景 |
-|---|---:|---|---|
-| **Direct Session** | 不需要 | 当前请求与宿主提供的信息 | 普通 Claude Code / Codex 会话 |
-| **Mounted Session** | 不需要 | 本地 Markdown 或钉钉文档快照 | 带身份、记忆和知识的长期员工 |
-| **Prepared Run** | Workspace 一次性初始化 | 可信事件冻结的目标、身份与策略 | 自动化事件处理和强可靠外发 |
+| 层 | 负责什么 |
+|---|---|
+| **`AGENTS.md`** | 定义角色、岗位底线、做事范式和常犯错误；声明每轮先应用 Basic |
+| **Basic Behavior** | 所有数字员工共享的响应资格、作用域、授权、隐私、完成与记忆协议 |
+| **Role Skills** | 某个岗位的专业判断、流程、禁区和验收标准 |
+| **Gate + Receipt** | 把身份、目标、预算、幂等、状态迁移和平台回读变成硬约束 |
 
-本地内容直接挂载，不复制：
+Prompt 只保留必须常驻、必须严格定义的内容；完整行为树进入 Skill；不能依赖模型自觉的约束进入 Gate。
 
-```bash
-dingtalk-agent bootstrap --storage local-dir:/path/to/workspace --json
-```
+### 创建 → 测试 → 发布
 
-远端内容由 DWS 探测并拉成隐藏的只读快照：
+| 阶段 | 关键产物 | 门禁 |
+|---|---|---|
+| **创建** | `AGENTS.md`、Basic、Role Skills、bindings | 占位符未补全时保持 `partial` |
+| **测试** | 隔离 Workspace、load probe、行为评测、四类证据 | Definition/Skills 没有真实加载就不能 ready |
+| **发布** | 平台预检、部署 Receipt、远端 readback | 指定 Eval 未通过或身份链不完整就不能 promote |
+| **运行** | 数字员工账号或机器人入口、task trace | 无证据不声称写入、送达或完成 |
 
 ```bash
-dingtalk-agent bootstrap \
-  --storage 'dingtalk-doc:<node-id-or-url>' \
-  --state-dir /path/to/session-state \
-  --json
-```
-
-### 四个消息原子行为
+# 1. 创建零写入计划，再显式落盘
+dta agent enhance --project-name release-agent --role-skill release-manager --dry-run --json
+dta agent enhance --project-name release-agent --role-skill release-manager \
+  --plan-id <plan-id> --yes --json
 
-Prepared Run 只开放四个消息动作：
+# 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
 
-```bash
-dingtalk-agent act ack
-dingtalk-agent act reply --text-file reply.txt
-dingtalk-agent act ask --text "一个真正阻塞的问题"
-dingtalk-agent act silence --reason unmentioned
+# 3. 云端预检、发布与观测
+dta workspace inspect multica-dev --execute --yes --json
+dta workspace remote-list multica-dev --execute --yes --json
+dta promote --source local-dev --target multica-dev --dry-run --json
+dta observe --promotion-id <promotion-id> --input <observation.json> --dry-run --json
 ```
 
-| 动作 | 员工语义 | 关键边界 |
-|---|---|---|
-| `ack` | 看到了，确实需要时间处理 | 不等于接单、承诺或完成 |
-| `reply` | 已有可交付结果 | 只回复原消息，CLI 没有 `--to` |
-| `ask` | 缺少阻塞信息 | 一次只问一个问题，随后释放沙箱等待事件 |
-| `silence` | 有意识地不打扰 | 仍留下结构化 reason 和本地回执 |
-
-文档写入、待办创建等能力继续由 DWS 提供。只有当一个员工意图需要固定作用域、权限、幂等、回读、状态迁移或跨产品组合时，才值得包装成新的 CLI 动作。
-
-## 架构
-
-```mermaid
-flowchart TB
-  SIGNAL["钉钉消息 / @ / DM / 心跳"] --> HOST["Claude Code / Codex / Agent Host"]
-  BASIC["Basic Behavior Skill\n响应资格与员工协议"] --> HOST
-  ROLE["岗位 / Workflow Skill\nFDE、周报、事故处理"] --> HOST
-  HOST --> BOOT["bootstrap\n按需水合身份、记忆与知识"]
-  BOOT --> LOCAL["Local Markdown"]
-  BOOT --> DOC["DingTalk Doc Snapshot"]
-  HOST --> MODE{"可信事件？"}
-  MODE -- "否" --> DIRECT["Direct / Mounted Session"]
-  MODE -- "是" --> RUNTIME["Prepared Run Runtime\nSession / Run / Wait / Gate"]
-  RUNTIME --> ACTION["ack / reply / ask / silence"]
-  DIRECT --> DWS["DWS"]
-  ACTION --> DWS
-  DWS --> PRODUCTS["消息 / 文档 / 待办 / 日历"]
-```
-
-### 事件驱动的异步进程
+所有计划默认零写入；所有远端写入都需要明确目标、当前 `planId` 和显式确认。
 
-每条新信号可以启动一个新沙箱，但同一件事仍回到同一个 Session：
+## 支持范围
 
-```text
-Field / Workspace  = 长期身份、知识与 Skill（Heap）
-Session            = 一件工作的显式上下文（Stack）
-Run                = 一次事件唤醒的新沙箱
-Wait               = await continuation，由宿主持久化和恢复
-Action             = 受约束的系统调用
-Receipt            = 可审计的外部效果证据
-```
+### 平台、Harness 与运行时
 
-`ask` 后当前 Run 结束；匹配事件到达时，宿主恢复原 Session 并创建新 Run。系统持久化显式 checkpoint，而不是序列化 JavaScript 或模型的隐藏调用栈。
+这三个概念彼此独立：
 
-### 存储边界
+- **Managed Agent Platform** 管 Workspace、Runtime、Agent、Skill、身份绑定和观测。
+- **Agent Harness** 加载 Definition/Skills，隔离执行并采集证据。
+- **dta Kernel** 依赖统一合同，不依赖某个 Harness 的私有 Prompt 或目录结构。
 
-| Markdown / 钉钉文档 | 宿主状态存储 |
+| 维度 | 当前支持 |
 |---|---|
-| 身份、长期知识、社交记忆、任务 checkpoint、Skill 候选 | EventIndex、Wait、锁、generation、幂等键、Action intent/receipt |
+| **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 与证据合同 |
+| **交付身份** | 数字员工/账号身份；机器人应用身份；两者都不能改变角色职责或扩大权限 |
 
-Why：文档适合人和 Agent 共同审查，但没有可靠 CAS；请求超时也不能证明写失败，因此不能承担并发控制或副作用去重。
+OpenCode 不是运行前提，Multica 也不是特殊旁路。任何 Harness 要进入可晋级路径，都必须证明同一件事：Definition 与 Skills 已加载、身份和隔离已固定、运行轨迹可取、结果可回读。
 
-## 数字员工行为协议
+“支持多平台”指架构、注册表和 adapter 合同可扩展；不把尚未开放的平台宣称为已部署或已 Live 验证。
 
-新任务遵循：
-
-```text
-UNDERSTAND → CLARIFY → PLAN → EXECUTE → WAIT → VERIFY → COMPLETE
-```
+### 三种运行模式
 
-- **UNDERSTAND**：从当前消息和可信 continuation 还原目标、交付物、范围、完成条件、权限与时点；
-- **CLARIFY**：先查线程、附件、Workspace 和岗位 Skill；信息足够就做，真阻塞才问；
-- **PLAN**：单步任务不表演计划，多步任务建立 2～5 个可观察检查点；
-- **EXECUTE**：外部副作用前重新核对对象、权限、幂等和最新状态；
-- **WAIT**：记录等待谁、什么输入、从哪里继续，然后释放沙箱；
-- **VERIFY**：通过工具结果和必要回读区分生成、保存、送达与确认；
-- **COMPLETE**：回到原线程交付结果、证据、遗留项和下一责任人。
+| 模式 | 用于 | 关键边界 |
+|---|---|---|
+| **Direct Session** | 普通交互会话 | 无可信事件就不猜外发目标 |
+| **Mounted Session** | 挂载本地或钉钉语义内容 | 锁、幂等和 Receipt 不放进 Markdown |
+| **Prepared Run** | 事件驱动的可靠副作用 | 动作只走 typed Broker 或 `dta act` |
 
-只有跨消息、等待依赖、已经产生副作用、需要换沙箱接手或用户明确要求跟踪的事项才创建 checkpoint。单轮问答不制造“伪任务”。
+Prepared Run 只开放 `ack`、`reply`、`ask`、`silence` 四个消息原子动作。`ack` 不等于接单，`reply` 不等于对方接受。
 
-## Skill、CLI 与 DWS 如何组合
+## 创建出来的 Agent 会继承什么
 
 ```text
-Basic Behavior Skill      每个钉钉员工共享的社交与安全底座
-        +
-Role / Workflow Skill     某个岗位如何完成 FDE 评价、周报、事故处理
-        +
-Agent Definition          身份、服务对象、知识源、记忆与权限
-        +
-dingtalk-agent CLI        需要强约束的员工级事务边界
-        +
-DWS                       钉钉标准产品能力
-```
-
-这意味着一个 FDE 教练只需在基础行为之上叠加教练身份、评价方法与学员资料；基础层无需知道任何 FDE 业务细节。
-
-## 常用命令
-
-```bash
-dingtalk-agent --help
-dingtalk-agent doctor
-dingtalk-agent setup
-dingtalk-agent skill install
-dingtalk-agent skill status
-dingtalk-agent bootstrap --json
-dingtalk-agent init
-dingtalk-agent prepare --event-file event.json --json
-dingtalk-agent help runtime
-dingtalk-agent help adapters
+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
 ```
 
-`listen` 是可选的开发联调 Adapter，不是 Agent 主进程。云端 Driver、Claude Code 插件或本地 DWS 都可以提供事件，并从标准化事件之后复用同一 Session / Run / Action 内核。
+生成的 `AGENTS.md` 只保留四块原子合同：**定义、不能做的底线、做事标准范式、常犯错误**。模板同时声明每个任务先应用 `dingtalk-basic-behavior`，再按任务加载 Role Skills。
 
-## 评测与验证
+“文件存在”不是继承证据。`agent audit --verify-load` 会把真实加载结果绑定到 Definition/Skill hash、Host/模型版本、隔离探针和原始 run/export：
 
 ```bash
-npm ci
-npm run typecheck
-npm run eval:contract
+dta agent audit \
+  --bindings agent.bindings.json \
+  --require-skill <role-skill-name> \
+  --verify-load --yes --json
 ```
 
-当前确定性合同包含 **31 个场景**，覆盖：
-
-- 通过 `npx skills` 委托全局 Skill 安装、发现、重装和卸载；
-- 首次 setup、用户级 PATH、DWS 版本/认证和三端客户端发现；
-- `dta` 短命令安装，以及命令、子命令和参数错误的可恢复提示；
-- CLI 自升级、新 binary 版本校验和升级后 setup 复核；
-- 无 init bootstrap、本地/远端 Storage 与类型闸门；
-- Direct Session 外发边界；
-- Session continuation、Wait、幂等和目标防篡改；
-- Skill 冻结、动作预算和 Receipt。
-
-模型行为还可通过 Claude shadow 做 with-skill / baseline 对照；它只允许读取冻结输入并输出 ActionRequest，不产生任何钉钉副作用。完整晋级门禁见 [自测与持续进化](docs/SELF-TEST.md)。
+## 不可绕过的边界
 
-## 项目结构
+- 普通 Session 不自动运行 `dingtalk-agent init`。
+- target、actor、conversation、DWS profile 与权限只来自可信宿主或事件。
+- Prepared Run 的消息副作用只走 typed Broker 或 `dta act`，不能绕过 Gate。
+- 在线 Run 可以提出记忆或 Skill 候选，但不能热修改当前身份、权限或策略。
+- 模型自述、命令退出 0、平台写入可见、消息送达与人类接受必须分别举证。
 
-```text
-bin/                              CLI composition root
-src/                              TypeScript runtime
-skills/dingtalk-basic-behavior/   可安装的基础行为 Skill
-templates/                        Workspace 与行为模板
-evals/                            合同、fixture 与 shadow runner
-docs/                             架构、决策和调研文档
-.github/                          CI 与协作模板
-```
+## 文档
 
-## 深入阅读
-
-- [代码与运行架构](docs/ARCHITECTURE.md)
-- [安装与首次使用](docs/INSTALLATION.md)
-- [最小 Workspace 决策记录](docs/MINIMAL-WORKSPACE-V1.md)
-- [自测与持续进化](docs/SELF-TEST.md)
-- [开源项目差异与共同范式](docs/OPEN-SOURCE-REFERENCES.md)
-- [贡献指南](CONTRIBUTING.md)
-- [安全策略](SECURITY.md)
-
-## 当前边界
-
-- 不把 `listen` 作为 Agent 的强制主入口；
-- 不自动初始化或污染任意代码仓库；
-- 不复制整个 DWS 命令面；
-- 不把钉钉文档当锁、事务数据库或副作用回执；
-- 不允许在线 Run 自动扩大身份、权限或启用新 Skill；
-- 当前 `dingtalk-doc` 只读水合，远端写入必须经过显式授权 Provider 并回读。
+| 想做什么 | 从这里开始 |
+|---|---|
+| 理解架构与状态模型 | [Architecture](docs/ARCHITECTURE.md) |
+| 安装、升级与排障 | [Installation](docs/INSTALLATION.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) |
 
-## License
+行为资产来自可观察合同、反例修正和可部署验证；本项目不声称获得任何产品的隐藏系统提示词原文。
 
-[MIT](LICENSE)
+MIT License