@xdxer/dingtalk-agent 0.1.1 → 0.1.2

package/README.md

@@ -1,124 +1,125 @@
 # dingtalk-agent
 
-**钉钉数字员工的标准范式：CLI（拦）+ Skill（劝）。**
+让 Claude Code、Codex 或其他 Agent 在获得一个全局 Skill 后，像钉钉里的真实同事一样处理消息和协作事项。
 
-零运行时依赖。任何 Coding Agent（Claude Code / Codex / …）`init` 即用。
+它不内置模型，也不复制 DWS：
 
-```bash
-npm i -g dingtalk-agent
+- Basic Behavior Skill 判断何时响应、追问、沉默，以及如何使用记忆；
+- `dingtalk-agent` 包装需要目标冻结、幂等、回读和状态迁移的员工级动作；
+- DWS 负责钉钉消息、文档、待办、日历等具体产品能力。
 
-mkdir my-agent && cd my-agent
-dingtalk-agent init          # 铺出工作区
-# 填 ontology/self/ 的三件套
-dingtalk-agent boot          # 真去摸一遍工位，拉不到就 BOOT FAIL
-```
+![Skill-first 架构](docs/architecture/dingtalk-agent-blueprint.png)
 
----
+## 两步开始
 
-## 范式
+```bash
+npm i -g @xdxer/dingtalk-agent
+dingtalk-agent skill install
+```
 
-| | | |
-|---|---|---|
-| **CLI** | **拦** | 标准动作：可程序化、可强制、可验证。**撞上去没得商量** |
-| **Skill** | **劝** | 判断：只有 LLM 能做的——该不该答、话题归属、怎么写点评 |
-| **本体** | **记** | 我是谁 + 我知道什么。`git clone` 就带走 |
+这会安装一个 canonical Skill：
 
-**分界线：凡是能程序化的，收进 CLI；凡是需要判断的，留在 Skill。**
+```text
+~/.agents/skills/dingtalk-basic-behavior/     # Codex 直接发现
+~/.claude/skills/dingtalk-basic-behavior      # 相对 symlink → canonical
+```
 
-因为文档会被漏读、误读、自我说服；**撞到闸门上就没得商量。**
+它不会初始化当前目录，也不会修改项目的 `AGENTS.md`、`CLAUDE.md` 或 `.gitignore`。新 Agent 会话会自动发现 Skill；检查状态：
 
-## 三个判定（现场可测）
+```bash
+dingtalk-agent skill status
+```
 
-1. **不喊它，它自己会动吗？** → **事件**。答否，只是聊天框。
-2. **昨天教它的，今天还记得吗？** → **存储**。答否，永远是新来的。
-3. **它干的事，能查、能撤、能追责吗？** → **身份**。答否，没人敢让它真干活。
+## 每个 Agent Session
 
----
+普通会话不要求 init：
 
-## 知识库：所有权决定真值方向
+```bash
+dingtalk-agent bootstrap --json
+```
 
-| | **owned**（我的本体） | **external**（别人维护的） |
-|---|---|---|
-| 真值在 | **Git**（本地） | **钉钉**（远端） |
-| 同步 | `push` 本地 → 钉钉（**给人看**） | `pull` 钉钉 → 本地（**给我 grep**） |
-| 冲突了 | 远端被人改过 → **停下来问** | 远端赢，本地缓存**可丢弃** |
+如果当前目录存在 `WORKSPACE.md`、`MEMORY.md`、`knowledge/INDEX.md`，bootstrap 会直接挂载；都不存在也不是错误，不会自动创建文件。
 
-**Git 是常量层，钉钉是可替换的暴露层。**
+也可显式选择存储：
 
 ```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
-
-dingtalk-agent kb sync                  # 同步（漂移检测，绝不盲覆盖）
-dingtalk-agent kb search "<关键词>"      # 跨所有挂载点搜（过期缓存会警告）
+# 本地开发：直接挂载，不复制
+dingtalk-agent bootstrap --storage local-dir:/path/to/workspace --json
+
+# 远端员工：DWS probe 后拉成隐藏只读快照
+dingtalk-agent bootstrap \
+  --storage 'dingtalk-doc:<nodeId-or-url>' \
+  --state-dir /path/to/session-state \
+  --json
 ```
 
-三种源：`dingtalk:doc:<folderId>`（最常见——很多组织根本没建"知识库"）·
-`dingtalk:wiki:<spaceId>` · `local:<路径>`
+## 三种模式
 
-**三个硬约束**（全是踩出来的）：
+| 模式 | 是否需要 init | 用途 |
+|---|---:|---|
+| Direct Session | 否 | 普通 Claude Code/Codex 会话；应用同事行为，按需使用 DWS |
+| Mounted Session | 否 | 读取已有本地或钉钉文档中的身份、记忆、知识 |
+| Prepared Run | 是，一次 | 可信事件宿主冻结目标、身份、Session/Run、Wait、预算和回执 |
 
-1. **绝不双向自动 merge。** 一个方向是真值，另一个是投影。
-2. **重排版不是漂移。** 钉钉会重写 markdown——用行级 diff 判漂移会**每次都误报**，
-   然后你就会开始无脑 `--force`，**真漂移也一起覆盖掉**。判据是"剥掉符号后的文字流"。
-3. **缓存不新鲜就不许用。** *拿着过期快照回答，比说"我不知道"危险得多。*
-
----
-
-## 命令面
+只有第三种模式需要显式初始化：
 
+```bash
+mkdir fde-coach && cd fde-coach
+dingtalk-agent init                 # contextId 可省略，由目录名稳定派生
+dingtalk-agent prepare --event-file event.json --json
 ```
-init                          铺出工作区
-boot                          冷启动：真去摸工位，拉不到就 BOOT FAIL
 
-kb mount / list / sync / search
+重复 `init` 只检查现有 Workspace，不重绑 Context、不复制 Skill、不覆盖用户内容。
 
-duty --check                  一拍两问之一（无事静默，退出码 0）
-duty --run <值班>
-todo                          把待办【拉全】（翻页，不漏循环件）
+## 员工级原子行为
 
-log --did … --asked … --conv X --issue X --msg X     答完落一行
-feedback --kind 纠正|追问|认可 --text … --conv X     主人的下一句话
-runs --conv <会话>                                   拉出整条对话流（训练素材）
-evolve                                               这周该改什么
+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
 ```
 
-## 留痕：三个硬 ID
+- `ack` 是“看到了且需要时间”，不等于接单或完成；
+- `reply` 只交付给原消息；CLI 没有 `--to`；
+- `ask` 一次只问一个阻塞问题，并由宿主建立等待；
+- `silence` 是有意识地不打扰，也有本地回执。
 
-每行运行记录钉住 `issue`（翻得出运行过程）· `conv`（**拉得出整条对话流**）· `msg`（定位到那一句）。
+文档写、待办创建等裸 API 不在这里重复包装。只有当一个员工意图需要固定作用域、权限、幂等、回读、状态迁移或跨产品组合时，才值得成为新的 `dingtalk-agent` 动作。
 
-**缺了这三个，记录就只是一堆"我做了什么"，出了问题什么也追不到。**
+## 新任务承接
 
-而且两个成败必须**分开**：
+Basic Behavior 使用一条极简协议：`UNDERSTAND → CLARIFY → PLAN → EXECUTE → WAIT → VERIFY → COMPLETE`。“澄清”先在内部检查目标、交付物、完成条件和权限；信息完整就直接做，只有阻塞才向人问一个问题。
 
-- `r` = **引擎层**（命令跑通没有）
-- `fb` = **用户层**（主人认不认）
+跨消息、等待依赖或已经产生副作用的事项才写 task checkpoint；单轮问答不建状态。Prepared Run 使用 `$DTA_SESSION/memory/task.md`，本地 Mounted Session 只写显式配置的 state root，远端钉钉文档必须通过授权 Provider 写入并回读。控制面的 Wait、锁、幂等和 Receipt 不进入 Markdown。详见 [任务承接与 Checkpoint](skills/dingtalk-basic-behavior/references/task-lifecycle.md)。
 
-**引擎跑通 ≠ 答对 ≠ 主人满意。只看 `r`，你会看到一片绿，然后什么也进化不了。**
+## 可选事件宿主
 
----
+`listen` 只是开发联调适配器，不是 Agent 的主入口：
 
-## 六条铁律
+```bash
+dingtalk-agent help runtime
+dingtalk-agent help adapters
+```
 
-1. **人能读。** 裸 ID 必须紧跟中文名。*技能不是私有格式，是人和 Agent 的共同契约。*
-2. **渐进披露。** 上下文是成本，步数是延迟。*"能不能做到"只是及格线，"几步做到"才是分数。*
-3. **本体不乱动。** 骨骼可以长，但不能天天重接。
-4. **驱动靠心跳，不靠待办。** *待办是给人的，心跳是 Agent 的生理。*
-   把"永远做不完的义务"塞进"有终态的待办"，链一断就**静默漏执行且不自知**。
-5. **不许本地自证。** 回平台真派一次，**而且要看执行过程**。
-6. **环境正面修，不绕过。**
+云端 Driver、Claude Code 插件或本地 DWS 都可以提供事件；它们从标准化事件以后共享同一 Session/Run/Action 内核和唯一外发 owner。
 
-> **一条例外**：当一条自定的约束成了阻塞，先解阻塞。
-> **规矩是为了让事情成立，不是为了守规矩。**
+## 自测
 
----
+```bash
+npm ci
+npm run typecheck
+npm run eval:contract
+```
 
-## 依赖
+当前确定性合同包含 26 个场景，覆盖全局 Skill 安装与生命周期、无 init bootstrap、本地/远端 Storage、类型闸门、Direct Session 外发闸门，以及原有的 Session、Wait、幂等、目标防篡改和 Skill 冻结。评测页面见 [review.html](evals/results/contract/review.html)。
 
-- `node >= 18.3`
-- `dws` —— 钉钉的 CLI（Agent 在钉钉上的行动界面）
-- **零 npm 运行时依赖**
+- [代码与运行架构](docs/ARCHITECTURE.md)
+- [最小 Workspace 决策记录](docs/MINIMAL-WORKSPACE-V1.md)
+- [自测与持续进化](docs/SELF-TEST.md)
+- [开源项目差异与共同范式](docs/OPEN-SOURCE-REFERENCES.md)
 
 ## License