@xdxer/dingtalk-agent 0.1.1 → 0.1.4-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dingtalk-agent contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,125 +1,296 @@
+<div align="center">
+
 # dingtalk-agent
 
-**钉钉数字员工的标准范式：CLI（拦）+ Skill（劝）。**
+**让 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)
 
-零运行时依赖。任何 Coding Agent（Claude Code / Codex / …）`init` 即用。
+## 为什么需要它
+
+“会调用钉钉 API”不等于“会像员工一样工作”。真实协作还要求 Agent：
+
+- 群里未被提及时默认不抢话，被 `@` 或私聊时才获得响应资格；
+- 信息完整就直接交付，只有真正阻塞时才问一个问题；
+- 不从消息正文猜收件人、身份、文档 ID 或权限；
+- 长任务能确认收到、等待依赖、从下一条事件继续，而不是假装一直在线；
+- 区分“命令执行过”“平台写入成功”“回读可见”和“对方确认”；
+- 将任务状态、长期记忆、运行时锁和幂等回执放在正确的存储层。
+
+本项目把这些约束从一段巨型 Prompt 中拆出来：**Skill 负责判断，CLI 负责硬边界，DWS 负责平台能力。**
+
+## 两分钟开始
+
+> 要求 Node.js 18.3+。不需要先全局安装命令；`npx` 是不会受 PATH 影响的 bootstrap 入口。
 
 ```bash
-npm i -g dingtalk-agent
+npx --yes @xdxer/dingtalk-agent@beta setup
+```
+
+`setup` 会按顺序完成四件事：
 
-mkdir my-agent && cd my-agent
-dingtalk-agent init          # 铺出工作区
-# 填 ontology/self/ 的三件套
-dingtalk-agent boot          # 真去摸一遍工位，拉不到就 BOOT FAIL
+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
+dingtalk-agent doctor
 ```
 
----
+安装后，Skill 只有一份 canonical copy：
 
-## 范式
+```text
+~/.agents/skills/dingtalk-basic-behavior/     # Codex、OpenCode 直接发现
+~/.claude/skills/dingtalk-basic-behavior      # Claude Code → canonical 相对链接
+```
 
-| | | |
-|---|---|---|
-| **CLI** | **拦** | 标准动作：可程序化、可强制、可验证。**撞上去没得商量** |
-| **Skill** | **劝** | 判断：只有 LLM 能做的——该不该答、话题归属、怎么写点评 |
-| **本体** | **记** | 我是谁 + 我知道什么。`git clone` 就带走 |
+如果只想临时运行、不做用户级安装，任何命令都可以通过 npm exec 执行：
+
+```bash
+npx --yes @xdxer/dingtalk-agent@beta doctor
+npx --yes @xdxer/dingtalk-agent@beta skill install
+```
 
-**分界线：凡是能程序化的，收进 CLI；凡是需要判断的，留在 Skill。**
+也兼容开放的 `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 安装则使用：
 
-1. **不喊它，它自己会动吗？** → **事件**。答否，只是聊天框。
-2. **昨天教它的，今天还记得吗？** → **存储**。答否，永远是新来的。
-3. **它干的事，能查、能撤、能追责吗？** → **身份**。答否，没人敢让它真干活。
+```bash
+npx skills add ./skills/dingtalk-basic-behavior \
+  --global --yes --agent claude-code --agent codex --agent opencode
+```
 
----
+`npx skills` 只安装行为说明，不安装 `dingtalk-agent` CLI，也不检查 DWS；需要真实执行钉钉动作时仍应运行 `setup` 或 `doctor`。完整排障见 [安装与首次使用](docs/INSTALLATION.md)。
 
-## 知识库：所有权决定真值方向
+普通 Agent 会话无需初始化项目。进入任意目录后可直接发现上下文：
 
-| | **owned**（我的本体） | **external**（别人维护的） |
-|---|---|---|
-| 真值在 | **Git**（本地） | **钉钉**（远端） |
-| 同步 | `push` 本地 → 钉钉（**给人看**） | `pull` 钉钉 → 本地（**给我 grep**） |
-| 冲突了 | 远端被人改过 → **停下来问** | 远端赢，本地缓存**可丢弃** |
+```bash
+dingtalk-agent bootstrap --json
+```
 
-**Git 是常量层，钉钉是可替换的暴露层。**
+只有可信事件宿主需要冻结目标并建立 Prepared Run：
 
 ```bash
-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
+mkdir fde-coach && cd fde-coach
+dingtalk-agent init
+dingtalk-agent prepare --event-file event.json --json
+```
+
+## 核心模型
+
+### 三种运行模式
 
-dingtalk-agent kb sync                  # 同步（漂移检测，绝不盲覆盖）
-dingtalk-agent kb search "<关键词>"      # 跨所有挂载点搜（过期缓存会警告）
+| 模式 | 初始化 | 上下文 | 适用场景 |
+|---|---:|---|---|
+| **Direct Session** | 不需要 | 当前请求与宿主提供的信息 | 普通 Claude Code / Codex 会话 |
+| **Mounted Session** | 不需要 | 本地 Markdown 或钉钉文档快照 | 带身份、记忆和知识的长期员工 |
+| **Prepared Run** | Workspace 一次性初始化 | 可信事件冻结的目标、身份与策略 | 自动化事件处理和强可靠外发 |
+
+本地内容直接挂载，不复制：
+
+```bash
+dingtalk-agent bootstrap --storage local-dir:/path/to/workspace --json
 ```
 
-三种源：`dingtalk:doc:<folderId>`（最常见——很多组织根本没建"知识库"）·
-`dingtalk:wiki:<spaceId>` · `local:<路径>`
+远端内容由 DWS 探测并拉成隐藏的只读快照：
 
-**三个硬约束**（全是踩出来的）：
+```bash
+dingtalk-agent bootstrap \
+  --storage 'dingtalk-doc:<node-id-or-url>' \
+  --state-dir /path/to/session-state \
+  --json
+```
 
-1. **绝不双向自动 merge。** 一个方向是真值，另一个是投影。
-2. **重排版不是漂移。** 钉钉会重写 markdown——用行级 diff 判漂移会**每次都误报**，
-   然后你就会开始无脑 `--force`，**真漂移也一起覆盖掉**。判据是"剥掉符号后的文字流"。
-3. **缓存不新鲜就不许用。** *拿着过期快照回答，比说"我不知道"危险得多。*
+### 四个消息原子行为
 
----
+Prepared Run 只开放四个消息动作：
 
-## 命令面
+```bash
+dingtalk-agent act ack
+dingtalk-agent act reply --text-file reply.txt
+dingtalk-agent act ask --text "一个真正阻塞的问题"
+dingtalk-agent act silence --reason unmentioned
+```
 
+| 动作 | 员工语义 | 关键边界 |
+|---|---|---|
+| `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["消息 / 文档 / 待办 / 日历"]
 ```
-init                          铺出工作区
-boot                          冷启动：真去摸工位，拉不到就 BOOT FAIL
 
-kb mount / list / sync / search
+### 事件驱动的异步进程
 
-duty --check                  一拍两问之一（无事静默，退出码 0）
-duty --run <值班>
-todo                          把待办【拉全】（翻页，不漏循环件）
+每条新信号可以启动一个新沙箱，但同一件事仍回到同一个 Session：
 
-log --did … --asked … --conv X --issue X --msg X     答完落一行
-feedback --kind 纠正|追问|认可 --text … --conv X     主人的下一句话
-runs --conv <会话>                                   拉出整条对话流（训练素材）
-evolve                                               这周该改什么
+```text
+Field / Workspace  = 长期身份、知识与 Skill（Heap）
+Session            = 一件工作的显式上下文（Stack）
+Run                = 一次事件唤醒的新沙箱
+Wait               = await continuation，由宿主持久化和恢复
+Action             = 受约束的系统调用
+Receipt            = 可审计的外部效果证据
 ```
 
-## 留痕：三个硬 ID
+`ask` 后当前 Run 结束；匹配事件到达时，宿主恢复原 Session 并创建新 Run。系统持久化显式 checkpoint，而不是序列化 JavaScript 或模型的隐藏调用栈。
 
-每行运行记录钉住 `issue`（翻得出运行过程）· `conv`（**拉得出整条对话流**）· `msg`（定位到那一句）。
+### 存储边界
 
-**缺了这三个，记录就只是一堆"我做了什么"，出了问题什么也追不到。**
+| Markdown / 钉钉文档 | 宿主状态存储 |
+|---|---|
+| 身份、长期知识、社交记忆、任务 checkpoint、Skill 候选 | EventIndex、Wait、锁、generation、幂等键、Action intent/receipt |
 
-而且两个成败必须**分开**：
+Why：文档适合人和 Agent 共同审查，但没有可靠 CAS；请求超时也不能证明写失败，因此不能承担并发控制或副作用去重。
 
-- `r` = **引擎层**（命令跑通没有）
-- `fb` = **用户层**（主人认不认）
+## 数字员工行为协议
 
-**引擎跑通 ≠ 答对 ≠ 主人满意。只看 `r`，你会看到一片绿，然后什么也进化不了。**
+新任务遵循：
 
----
+```text
+UNDERSTAND → CLARIFY → PLAN → EXECUTE → WAIT → VERIFY → COMPLETE
+```
+
+- **UNDERSTAND**：从当前消息和可信 continuation 还原目标、交付物、范围、完成条件、权限与时点；
+- **CLARIFY**：先查线程、附件、Workspace 和岗位 Skill；信息足够就做，真阻塞才问；
+- **PLAN**：单步任务不表演计划，多步任务建立 2～5 个可观察检查点；
+- **EXECUTE**：外部副作用前重新核对对象、权限、幂等和最新状态；
+- **WAIT**：记录等待谁、什么输入、从哪里继续，然后释放沙箱；
+- **VERIFY**：通过工具结果和必要回读区分生成、保存、送达与确认；
+- **COMPLETE**：回到原线程交付结果、证据、遗留项和下一责任人。
+
+只有跨消息、等待依赖、已经产生副作用、需要换沙箱接手或用户明确要求跟踪的事项才创建 checkpoint。单轮问答不制造“伪任务”。
+
+## Skill、CLI 与 DWS 如何组合
+
+```text
+Basic Behavior Skill      每个钉钉员工共享的社交与安全底座
+        +
+Role / Workflow Skill     某个岗位如何完成 FDE 评价、周报、事故处理
+        +
+Agent Definition          身份、服务对象、知识源、记忆与权限
+        +
+dingtalk-agent CLI        需要强约束的员工级事务边界
+        +
+DWS                       钉钉标准产品能力
+```
 
-## 六条铁律
+这意味着一个 FDE 教练只需在基础行为之上叠加教练身份、评价方法与学员资料；基础层无需知道任何 FDE 业务细节。
 
-1. **人能读。** 裸 ID 必须紧跟中文名。*技能不是私有格式，是人和 Agent 的共同契约。*
-2. **渐进披露。** 上下文是成本，步数是延迟。*"能不能做到"只是及格线，"几步做到"才是分数。*
-3. **本体不乱动。** 骨骼可以长，但不能天天重接。
-4. **驱动靠心跳，不靠待办。** *待办是给人的，心跳是 Agent 的生理。*
-   把"永远做不完的义务"塞进"有终态的待办"，链一断就**静默漏执行且不自知**。
-5. **不许本地自证。** 回平台真派一次，**而且要看执行过程**。
-6. **环境正面修，不绕过。**
+## 常用命令
+
+```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
+dingtalk-agent eval contract
+```
+
+`listen` 是可选的开发联调 Adapter，不是 Agent 主进程。云端 Driver、Claude Code 插件或本地 DWS 都可以提供事件，并从标准化事件之后复用同一 Session / Run / Action 内核。
+
+## 评测与验证
+
+```bash
+npm ci
+npm run typecheck
+npm run eval:contract
+```
+
+当前确定性合同包含 **28 个场景**，覆盖：
+
+- 全局 Skill 安装、发现、升级和漂移保护；
+- 首次 setup、用户级 PATH、DWS 版本/认证和三端客户端发现；
+- 无 init bootstrap、本地/远端 Storage 与类型闸门；
+- Direct Session 外发边界；
+- Session continuation、Wait、幂等和目标防篡改；
+- Skill 冻结、动作预算和 Receipt。
+
+模型行为还可通过 Claude shadow 做 with-skill / baseline 对照；它只允许读取冻结输入并输出 ActionRequest，不产生任何钉钉副作用。完整晋级门禁见 [自测与持续进化](docs/SELF-TEST.md)。
+
+## 项目结构
+
+```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)
 
-## 依赖
+## 当前边界
 
-- `node >= 18.3`
-- `dws` —— 钉钉的 CLI（Agent 在钉钉上的行动界面）
-- **零 npm 运行时依赖**
+- 不把 `listen` 作为 Agent 的强制主入口；
+- 不自动初始化或污染任意代码仓库；
+- 不复制整个 DWS 命令面；
+- 不把钉钉文档当锁、事务数据库或副作用回执；
+- 不允许在线 Run 自动扩大身份、权限或启用新 Skill；
+- 当前 `dingtalk-doc` 只读水合，远端写入必须经过显式授权 Provider 并回读。
 
 ## License
 
-MIT
+[MIT](LICENSE)