@xdxer/dingtalk-agent 0.1.5-beta.3 → 0.1.5-beta.4

package/CHANGELOG.md

@@ -2,12 +2,33 @@
 
 All notable changes to `@xdxer/dingtalk-agent` are documented here. The project follows semantic versioning; prerelease entries describe release candidates and do not imply that Live canaries or registry publication have completed.
 
+## 0.1.5-beta.4 - 2026-07-23
+
+Driving layer: the recurring drives that wake a digital employee become a version-controlled, provider-mapped declaration instead of imperative platform state, plus a smoke-whitelist bare-filename fix that had blocked live deployment (PR #16). Ships on the `beta` dist-tag; `latest` stays at 0.1.4.
+
+### Added
+
+- Agent Projects declare their internalized cron in `dingtalk-agent.json#schedules`: a provider-neutral list (`name`, `cron`, `timezone`, `mode` of `ephemeral`/`work-item`, plus governance metadata `wake`/`completion`/`unit`/`evidence`/`supervision`). The manifest validator rejects non-5-field crons, `@macro` forms, unknown modes and duplicate names; `dta info` reads them back. The project source hash covers only definition + skills, so declaring or editing schedules never perturbs the deployment hash.
+- `dta schedule show` lists the declared drives with each rhythm's data-derived completion predicate and statically checks that no two share a cron minute field (the precondition for collision-safe outward delivery). `dta schedule plan --workspace <name>` maps the declaration to a provider-specific reconcile plan — Multica to `autopilot` create commands (`ephemeral`→`run_only`, `work-item`→`create_issue`); an unsupported provider fails closed and records the declared rhythms as a gap rather than silently downgrading. Both are pure and network-free.
+- `docs/schemas/project.schema.json` gains the `schedules` definition; the compose Skill's `drive-and-schedules.md` is the authoring method: an internalized cron is a level-triggered reconciler (state decides the work and the done), not an edge-triggered dispatcher, and every rhythm must answer five questions with a data-derived completion predicate at its heart.
+
+### Changed
+
+- Architecture §3.1 makes driving an explicitly modeled layer: dingtalk-agent implements no trigger, but owns the driving contract — declare which rhythms an employee needs, verify per-provider capability at deploy time, and hold the behavior contract a tick must satisfy. Compose, Basic Behavior and the platform packages carry the three platform-independent constraints (timers are unreliable so completion is "did it happen", outward ticks have no lock so they must not share a minute, and the Agent never self-installs or hot-edits its own alarm).
+- The multica-external ops Skill reconciles autopilots from `dta schedule plan` rather than hand-authoring them: list live first, create only what is missing, and never blind-create — `autopilot-create` is not idempotent and duplicates cause duplicate outward sends.
+
+### Fixed
+
+- The Multica load-smoke whitelist accepted `./result.md` and absolute workdir paths but rejected the same file referenced by a bare name (`result.md`) — which is exactly how the platform Agent writes it — so a smoke that loaded all Skills and produced the correct structured response still reported `providerReady=false` and blocked deployment. Only exact basenames are now accepted (`foo/result.md` and `../result.md` still fail closed); a contract fixture reproduces the bare-name trace and the assertion was verified to go red when the fix is reverted.
+
 ## 0.1.5-beta.3 - 2026-07-22
 
 Agent delivery-package single-source layout and Multica Issue-Adapter receipt compatibility (PR #11). Ships on the `beta` dist-tag; `latest` stays at 0.1.4.
 
 ### Changed
 
+- Compose 0.13.2 keeps deployed `agent/AGENTS.md` role-only: shared behavior cases propagate through the versioned Basic directory tree instead of being copied into each Agent definition.
+- Basic Behavior 0.12.0 adds a general batch-side-effect boundary distilled from a supervised DingTalk forwarding incident and the Aily behavior audit: when correctness depends on pagination, stable person-content binding, reconciliation or crash recovery, the Agent must upgrade from a model-driven tool loop to a frozen effect list plus deterministic runner and durable receipts. Without that runtime it may preview or run an explicitly supervised bounded batch, but cannot claim unattended execution. Repository guidance now also defines how future cases progress from evidence to one owner, a lean Skill entry, decision-family references, deterministic fixtures and versioned deployment without copying shared rules into each Agent.
 - Agent delivery packages now have a single source of truth: new projects generate `agent/AGENTS.md` and `agent/skills/`, and Host exposure is materialized only into temporary isolated workspaces instead of being committed alongside the source. The project manifest gains `skillsRoot`; explicit paths and the legacy root layout keep working.
 - Basic Behavior 0.11.11 makes IM history file-identifier recovery mandatory: rich-message recovery follows a fixed readback-before-gap-judgment order, and a fileId present in a history file card must go through `drive info`/read-only download instead of the Agent claiming it cannot read the file. A deterministic history-file-card fixture locks the behavior.
 - Golden Path and load-evidence fixtures moved to the `agent/AGENTS.md` + `agent/skills` single-source layout; load evidence now verifies resolved instructions against the trusted `definitionInstruction` exactly, while the legacy implicit root-`AGENTS.md` rule remains accepted.

package/README.en.md

@@ -2,26 +2,30 @@
 
 # dingtalk-agent
 
-**Give every digital employee the same verifiable behavior foundation.**
+**Let your coding agent turn an existing Agent into a DingTalk digital employee.**
 
 [![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)
 
-[Quick start](#quick-start) · [What an Agent is made of](#what-an-agent-is-made-of) · [How this repo is divided](#how-this-repo-is-divided) · [Docs](#docs)
+Evaluating? → [What it is](#what-it-is) · [What it does](#what-it-does) · [When to use it](#when-to-use-it) 　|　 Ready to build? → [Quick start](#quick-start)
 
 [简体中文](README.md) · English
 
 </div>
 
-`dingtalk-agent` (`dta`) is the **Skill-first behavior kernel and delivery toolchain** for DingTalk digital employees. It assembles role definition, shared behavior, role capability, and execution gates into an Agent Project you can create, test, promote, and audit.
+![Someone @-mentions it in a group chat; it finishes the job like a colleague, leaving a trace at every step](docs/assets/digital-employee-at-work.svg)
 
-> **Skills advise. The CLI gates. DWS acts.** Skills decide when and why to act; the CLI pins identity, target, budget, idempotency, and readback; DWS performs DingTalk capabilities.
+## What it is
+
+dta doesn't build the runtime substrate, but it owns the whole path of turning an Agent into a DingTalk digital employee.
+
+What separates a digital employee from a chatbot is a DingTalk-issued organizational identity: it has a name in the directory, can be @-mentioned, works only in the groups and conversations it was authorized for, and everything it does is recorded under its name.
 
-**DWS is DingTalk's own command-line tool** — separate from this project, installed and authenticated on its own (`dws auth login`) — covering roughly 20 product areas: messaging, docs, AI tables, calendar, approvals, and more. `dta` does not clone its command surface; it wraps it only where identity, target, idempotency, or readback must be frozen. **Every real DingTalk operation is ultimately executed by DWS.**
+A working Agent still has to add a whole layer of engineering that has nothing to do with your business logic: identity and permissions, telling which message in a group is meant for it, not sending to the wrong person, and producing delivery evidence when it reports "done". Every new digital employee redoes all of that. dta turns it into a set of inheritable rules and one CLI that your coding agent installs and uses, so you don't have to study DingTalk's identity model, event model, and outbound limits yourself.
 
-![The complete path from Agent definition to delivery through two identity types](docs/assets/agent-delivery-lifecycle.svg)
+Works with: Claude Code · Codex · OpenCode · any coding agent　|　Managed platforms: Multica (supported) · DEAP (coming soon)
 
 ## Quick start
 
@@ -38,45 +42,24 @@ npm install --global --prefix "$HOME/.local" \
 "$HOME/.local/bin/dta" doctor
 ```
 
-`setup` installs the Basic Behavior, Compose, and Eval Skills, then checks DWS authentication and common Agent Hosts. Normal sessions do not require Workspace initialization.
-
-**How far you get with nothing external**: composing, auditing, `workspace run/eval`, and the full contract suite need no DingTalk account and no managed platform — `doctor` marks what is missing as `partial` rather than failing. Only real outbound messaging, remote semantic state, and `deploy`/`promote` require DWS authentication and Multica.
-
-## Why it exists
-
-A model that talks is not a digital employee that works reliably. `dta` turns the four most drift-prone concerns into inheritable, verifiable contracts:
-
-- **It judges first.** Decide whether to reply before deciding what to say; stay quiet in group chats without an `@`.
-- **It stays in scope.** Identity, target, permission, authorization, and reply channel are never guessed from message text or model memory.
-- **It does not overclaim.** Command success, platform visibility, message delivery, and human acceptance are four distinct completion levels, each evidenced separately.
-- **It is reusable.** A new Agent inherits shared behavior and only adds role differences — no copied mega-prompt.
-
-## What an Agent is made of
-
-Four things: the **Definition** (`agent/AGENTS.md` — who I am, where my duties stop), **shared behavior** (`agent/skills/dingtalk-basic-behavior`), **role capability** (`agent/skills/<role>/SKILL.md`), and **storage routing** (`agent.bindings.json` — optional; the same configuration can come from host context, environment variables, or a Workspace manifest). The repository-root `AGENTS.md` only governs coding agents and is never the remote System Prompt.
-
-For a new project, `agent/` is the only managed-platform delivery boundary; do not commit duplicate Skills under root `skills/` or `.agents/skills/`. Existing code repositories can retain custom layouts by explicitly declaring `agent.definition` and `agent.skillsRoot` in `dingtalk-agent.json`.
+`setup` installs the shared-behavior, compose, and eval Skills, then checks DWS authentication and common Agent Hosts. Normal sessions do not require Workspace initialization.
 
-Full composition, dependencies, and boundaries: [Architecture](docs/ARCHITECTURE.md#2-一个-agent-由什么构成模型-a).
+### Minimal runnable path
 
-**File presence is not inheritance evidence** — `agent audit --verify-load` binds real load results to Definition/Skill hashes, Host and model versions, isolated probes, and raw run/export evidence:
+Start with these three — no DingTalk account, no managed platform, and no side effects:
 
 ```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      # Was the body recognized? Check definition.status and storage routes
+dta agent audit --json    # Expect partial — the role semantics are still template text, which is correct
 ```
 
-## How this repo is divided
-
-**Behavior kernel** (event → may I respond, to whom, what am I allowed to do), **compose & audit** (turn a repo/folder/doc into a hashable Agent and prove the Skills really loaded), **delivery chain** (reach a managed platform under control, with readback at every step), **eval & evidence** (prove it works at the cheapest sufficient level before going live), **state & memory** (stay resumable after a crash), and **machine & distribution** (one command sets up a new machine).
-
-Delivery and evaluation are roughly a quarter of the codebase each — the hard part was never "make the model talk", but proving the thing really installed, really behaved, and really shipped. What each part solves, and its modules and CLI: [Architecture](docs/ARCHITECTURE.md#7-dingtalk-agent-分成哪几部分模型-c).
+`release-manager` is a complete sample of a release-manager digital employee: it picks up "can we ship this version?" in a group, checks the gates, summarizes the verdict, and requires human confirmation before moving on. Replace the role duties in `agent/AGENTS.md` with your own, run `agent audit` again, and the only gap left is the load probe — which needs an Agent Host, see the [Compose Skill](skills/core/dingtalk-agent-compose/SKILL.md).
 
-## Create → test → promote
+### Full delivery chain
 
-Each of the four stages has a gate: unfilled placeholders keep it `partial`; Skills that did not truly load cannot be ready; a missing named Eval blocks promote; nothing claims delivery or completion without evidence. Details: [Architecture](docs/ARCHITECTURE.md#8-从定义到上线).
+<details>
+<summary>The complete create → test → ship commands (worth reading once you have a managed platform binding)</summary>
 
 ```bash
 # 1. Generate a zero-write plan, then commit it explicitly
@@ -92,60 +75,104 @@ dta workspace eval local-dev --suite evals/suite.json --execute --yes --json
 # 3. Cloud preflight, promotion, and observation
 dta workspace inspect multica-dev --execute --yes --json
 dta workspace remote-list multica-dev --execute --yes --json
-dta workspace run multica-dev --prompt-file readonly-question.md --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
 ```
 
-Plans are zero-write by default. Remote writes require an explicit target, the current `planId`, and confirmation.
+Plans are zero-write by default; every remote write requires an explicit target, the current `planId`, and confirmation. `<plan-id>` comes from the preceding dry run's `.planId`; `local-dev` / `multica-dev` are Workspace names you declare in `dingtalk-agent.json#workspaces`. Each of the four stages has a gate: unfilled placeholders keep it `partial`; Skills that did not truly load cannot be ready; a missing named eval blocks promote; nothing claims delivery or completion without evidence. Details: [Architecture](docs/ARCHITECTURE.md#8-开发生命周期从定义到观测).
+
+</details>
+
+## What it does
+
+Turning an Agent into a DingTalk digital employee takes six stages, and dta covers every one:
+
+| Lifecycle stage | What dta does | With what |
+|---|---|---|
+| **① Body and employee skills** | An inheritable, verifiable shared behavior contract: when to speak, whether a message is even a task, who must approve an outbound action, how risk is graded, what counts as done, what to remember and forget. You write only the few dozen lines that differ by role | `dingtalk-basic-behavior` · `agent enhance` · `examples/agents/` |
+| **② Identity acquisition and event perception** | Normalize differently shaped raw events into a stable structure; freeze the reply target and execution identity into a snapshot message text cannot alter, making wrong-recipient structurally impossible; bind permissions and outbound ownership per field; one event yields exactly one Run, losing and duplicating nothing across crashes | `prepare` · `run` · Field config |
+| **③ Managed-platform deployment** | See the plan before anything lands: frozen hashes for the body and the whole Skill tree plus a write budget; independent readback and a load smoke test after writing; re-running the same version writes nothing; failures roll back and shipped agents can be retired (today this lands on Multica) | `deploy` · `promote` · `--retire` |
+| **④ Driving it to work inside DingTalk** | Outbound has only four atoms; before an action the gate blocks overreach and target drift, after it a platform readback is mandatory; no blind retries when the outcome is uncertain; a "done" report must carry re-verifiable evidence | `act` · Action Gate · `task checkpoint` |
+| **⑤ Evaluation design** | Not a scoring tool but a method: how to pick the cheapest sufficient level, which evidence surfaces one verdict must collect, which failures may never be averaged away, how a real incident becomes a replayable case, and what blocks a release | `lab` · `workspace eval` · `dingtalk-agent-eval` |
+| **⑥ Observation and feedback** | Bind a production finding to the exact version that ran, desensitize it, and feed it back into evaluation material, without ever changing the Agent's behavior on its own | `observe` |
+
+## When to use it
+
+Use it when:
+
+- you already have a working Agent and want it in DingTalk groups under an organizational identity, getting @-mentioned and assigned work;
+- you run DingTalk automation and have been bitten by sending to the wrong person, or by exit code 0 being treated as success;
+- you are building not one digital employee but a batch, and don't want shared behavior copied into several drifting prompts;
+- your work spans days, waits for human confirmation, and can be called off midway — not one-shot Q&A;
+- you need to prove to someone that what runs in production is the exact version you verified.
+
+Skip it when:
 
-The placeholders above are not yours to invent — each has a definite source:
+- you just want a Q&A bot: one DingTalk robot webhook is enough, and this is overhead;
+- you just want to call DingTalk APIs: use DWS directly — it already works, and dta is not a prerequisite;
+- you are not on DingTalk: the only execution path is DWS and identity is issued by DingTalk, neither of which is swappable.
 
-| Placeholder | Where it comes from |
+Not possible today: importing an Agent already deployed on another platform (data flows one way, local definition to managed platform, with no import command); triggers (webhooks, timers) are also out of scope.
+
+## Where it stands today
+
+| Area | Where it is |
 |---|---|
-| `<plan-id>` | Top-level `.planId` in the preceding `--dry-run --json` output. Any source or config change invalidates it, so re-run the dry run |
-| `local-dev` / `multica-dev` | Workspace names **you** declare in `dingtalk-agent.json#workspaces` — not built-in values. Sample: [`lab/project-workspace/project.fixture.json`](lab/project-workspace/project.fixture.json) |
-| `<promotion-id>` | `.promotionId` on the `promotion-receipt@1` produced by `dta promote --yes` |
-| `<role-skill-name>` | The `name` in your `agent/skills/<role>/SKILL.md` frontmatter |
+| First five of the six stages | In shape |
+| Stage six (observation & metering) | The thinnest. Usage metering — interaction counts, tokens, cost, per-person/per-group breakdown — isn't built yet |
+| Managed platform | Multica supported; DEAP coming soon; the platform SPI isn't merged into main yet |
+| Agent Host | OpenCode complete; the Claude Code adapter isn't implemented |
+| Completion evidence | The verify side is implemented and contract-locked; the issue side isn't wired to a public command |
+| Importing an Agent from an external platform | No such command; data flows one way, local to platform |
+| Regression net | 62 deterministic contracts, run in 18 seconds |
 
-### Minimal runnable path (local only, three commands)
+## How it works
 
-To see something move first, don't start with the chain above — that is the full delivery pipeline. Start here:
+> **Skills advise. The CLI gates. DWS acts.** Skills decide when and why to act; the CLI pins identity, target, budget, idempotency, and readback; DWS performs DingTalk capabilities.
 
-```bash
-cp -R examples/agents/release-manager my-agent && cd my-agent
-dta bootstrap --json      # Was the body recognized? Check definition.status and storage routes
-dta agent audit --json    # Expect partial — the role semantics are still template text, which is correct
-```
+These boundaries are structurally impossible to cross, not politely discouraged in a prompt: without an `@` in a group it stays silent; the CLI has no "send to" parameter, so the reply target can only come from the message that triggered it; a completion report must carry host-issued evidence that can be read back independently. All three are watched by deterministic contract evals — break them and the suite goes red.
+
+**DWS is DingTalk's own command-line tool** (separate from this project, with its own `dws auth login`), covering roughly 20 product areas: messaging, docs, AI tables, calendar, approvals, and more. dta does not clone its command surface; every real DingTalk operation is ultimately executed by DWS.
+
+## FAQ
 
-None of this needs a DingTalk account or a managed platform, and none of it has side effects. Fill in the real role semantics in `agent/AGENTS.md`, run `agent audit` again, and the only remaining gap is `host.load-probe` — which needs an Agent Host, see the [Compose Skill](skills/core/dingtalk-agent-compose/SKILL.md). The third command group above only applies once you have a Multica binding and declared Workspaces.
+**Is this yet another Agent framework?**
+No. It provides no model, no tool loop, and no agent runtime. It gives your coding agent a set of Skills and one CLI to compose an existing Agent into a DingTalk digital employee.
 
-When deploying to Multica, the remote System Prompt must equal the manifest-selected `agent/AGENTS.md` source. Deployment hashes, the Skill manifest, and assignment evidence stay in the plan/operation/Receipt control plane. Basic and Role Skills use the platform's native assignment instead of an extra startup prompt or startup Skill.
+**Does it conflict with Claude Code or Codex?**
+No — it is built for them. `dta setup` installs the Skills into these coding agents; after that you instruct them in natural language. The CLI also works standalone.
+
+**My Agent already runs on another platform — can I bring it in?**
+The body (role definition and Skills) is portable: compose locally, then ship to a managed platform. But there is no command today that imports from an external platform, and Multica is the only managed platform supported.
+
+**What do I need to try it once?**
+No DingTalk account and no managed platform. Composing, auditing, `workspace run/eval`, and the full contract suite all run locally; `doctor` marks what's missing as `partial` instead of failing. Only real outbound messaging and shipping need DWS authentication.
+
+**How much effort does it take?**
+The main work of the first role is writing the role duties clearly, not writing code: the body is Markdown, and you edit from the examples. Adding a second role changes three files and zero kernel code.
 
 ## Support
 
-A **Managed Agent Platform** (owning Workspace, Runtime, identity binding, and observation), an **Agent Host** (a.k.a. Harness — loads Definition/Skills and isolates execution), and the **dta Kernel** are three separate concepts:
+A managed platform, an Agent Host, and the dta kernel are three separate things: the managed platform owns Workspace, Runtime, and observation, and binds a DingTalk-issued identity to the Agent (issuance stays with DingTalk); the Agent Host (a.k.a. Harness) loads definitions and Skills and isolates execution; the dta kernel is this project.
 
 | Dimension | Current support |
 |---|---|
-| **Managed Platform** | Multica (DingTalk) supported; DEAP coming soon; additional platforms through registry + adapters |
-| **Local runtime** | Direct/Mounted sessions in Claude Code, Codex, OpenCode, and similar Hosts; OpenCode is the most complete local managed-Harness reference |
-| **Cloud runtime** | Multica Workspace / Runtime / Agent with the same Definition, Skills, Gate, and evidence contract |
-| **Delivery identity** | Digital-employee/account identity or robot-app identity; neither expands the Agent role or authority |
+| **Managed platform** | Multica (DingTalk) supported; DEAP coming soon; onboarding a new platform takes the same path: author a platform Skill pack and register one entry |
+| **Local runtime** | Direct/Mounted sessions in Claude Code, Codex, OpenCode, and similar Hosts; OpenCode is the most complete local reference |
+| **Cloud runtime** | Multica Workspace / Runtime / Agent with the same definitions, Skills, gates, and evidence contract |
+| **Delivery identity** | Digital-employee/account identity or robot-app identity, both issued by DingTalk; neither changes the role's duties or expands its authority |
 
-OpenCode is not a runtime dependency, and Multica is not a privileged bypass. Any promotable Harness must prove the same outcomes: loaded Definition and Skills, pinned identity and isolation, retrievable execution trace, and independent readback. "Multi-platform" means the architecture, registry, and adapter contract are extensible; it does not claim that unopened platforms have been deployed or Live-verified.
+DEAP may play two roles at once: its most important value to this project today is DingTalk-side identity/authorization and perception/human-interaction; whether it also embeds a runtime platform of its own is not yet settled. See the [DEAP platform note](skills/platforms/deap/PLATFORM.md). "Multi-platform" means the registry and onboarding contract are extensible; it does not claim that unopened platforms are deployed or Live-verified.
 
 ### Runtime modes
 
 | Mode | Use | Boundary |
 |---|---|---|
 | **Direct Session** | Normal interactive work | Never guess an outbound target without a trusted event |
-| **Mounted Session** | Mount local or DingTalk semantic content | Locks, idempotency, and Receipts do not live in Markdown |
+| **Mounted Session** | Mount local or DingTalk semantic content | Locks, idempotency, and receipts do not live in Markdown |
 | **Prepared Run** | Reliable event-driven side effects | Actions go only through the typed Broker or `dta act` |
 
-Prepared Runs expose four message atoms: `ack`, `reply`, `ask`, and `silence`. An acknowledgement is not task acceptance, and a reply is not human acceptance.
-
-**Triggers are out of scope for this project**: `listen` is a replaceable local integration Adapter, and `dta deploy` never creates robots, webhooks, or timers.
+Prepared Runs expose four message atoms: `ack`, `reply`, `ask`, and `silence`. An acknowledgement is not task acceptance, and a reply is not human acceptance. Triggers are out of scope: `listen` is a replaceable local integration Adapter, and `dta deploy` never creates robots, webhooks, or timers.
 
 ## Docs
 
@@ -158,7 +185,7 @@ Prepared Runs expose four message atoms: `ack`, `reply`, `ask`, and `silence`. A
 | Test or debug a delivered Agent | [Eval Skill](skills/core/dingtalk-agent-eval/SKILL.md) |
 | Read the shared behavior protocol (a contract written for models, not a tutorial) | [Basic Behavior Skill](skills/core/dingtalk-basic-behavior/SKILL.md) |
 | Copy a complete example and edit from there | [Example Agents](examples/agents) |
-| See which open-source projects informed this one | [Prior Art](docs/PRIOR-ART.md) |
+| Which platforms and open-source projects we keep absorbing practices from | [Prior Art](docs/PRIOR-ART.md) |
 
 Behavior assets come from observable contracts, counterexample-driven revision, and deployable verification. This project does not claim access to any product's hidden system prompt.
 

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,45 +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` 把最容易漂移的四件事变成可继承、可验证的合同：
-
-- **会判断**：先判断是否该回复，再判断说什么；群聊未 `@` 默认安静。
-- **不越权**：身份、目标、权限、授权和回复渠道不能从正文或模型记忆猜测。
-- **不虚报**：命令成功、平台可见、消息送达和人类接受是四个不同的完成层级，各自举证。
-- **可复用**：新 Agent 继承公共行为，只补岗位差异，不复制巨型 Prompt。
-
-## 一个 Agent 由什么构成
-
-四件东西：**本体**（`agent/AGENTS.md`，我是谁、职责边界）、**公共行为**（`agent/skills/dingtalk-basic-behavior`，何时响应/追问/沉默/收口）、**岗位能力**（`agent/skills/<role>/SKILL.md`）、**存储路由**（`agent.bindings.json`，可选——等价配置也可来自宿主 context、环境变量或 Workspace manifest）。仓库根 `AGENTS.md` 只约束 Coding Agent 开发，不属于远端本体。Agent Host、DWS、托管平台和事件源也不属于 Agent 交付包。
-
-从零创建时，`agent/` 是 managed agent platform 的唯一同步边界，Skill 不能再复制到根 `skills/` 或 `.agents/skills/`。已有代码仓库不强制迁目录：在 `dingtalk-agent.json#agent` 显式声明 `definition` 与 `skillsRoot` 即可继续按原布局同步。
+`setup` 安装公共行为、装配与评测三个技能，并检查 DWS 认证和常见 Agent Host。普通会话无需初始化 Workspace。
 
-完整的构成、依赖与边界见 [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 并证明真加载）、**交付链**（受控上托管平台，每步可回读）、**评测与证据**（上线前用最低成本证明它真会做事）、**状态与记忆**（崩了之后接着做）、**机器与分发**（一条命令装好一台新机器）。
-
-交付链与评测各占约四分之一代码量——这个项目的难点从来不是"让模型说话"，而是证明它真的装好了、做对了、上线了。每部分解决什么问题、对应哪些模块与 CLI，见 [Architecture](docs/ARCHITECTURE.md#7-dingtalk-agent-分成哪几部分模型-c)。
+`release-manager` 是一个发布管理员数字员工的完整样例：它在群里接"这个版本能发吗"，检查门禁、汇总结论、需要人确认才推进。把 `agent/AGENTS.md` 里的岗位职责换成你自己的，再跑一次 `agent audit`，缺口就只剩加载探针，那需要一个 Agent Host，见 [Compose Skill](skills/core/dingtalk-agent-compose/SKILL.md)。
 
-## 创建 → 测试 → 发布
+### 完整交付链
 
-四个阶段各有门禁：占位符没填完保持 `partial`；Skill 没真加载不能 ready；指定 Eval 没过不能 promote；没有证据不声称送达或完成。逐条见 [Architecture](docs/ARCHITECTURE.md#8-从定义到上线)。
+<details>
+<summary>创建 → 测试 → 发布的完整命令（有了托管平台归属再看）</summary>
 
 ```bash
 # 1. 创建零写入计划，再显式落盘
@@ -91,60 +74,104 @@ dta workspace eval local-dev --suite evals/suite.json --execute --yes --json
 # 3. 云端预检、发布与观测
 dta workspace inspect multica-dev --execute --yes --json
 dta workspace remote-list multica-dev --execute --yes --json
-dta workspace run multica-dev --prompt-file readonly-question.md --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
 ```
 
-所有计划默认零写入；所有远端写入都需要明确目标、当前 `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 做的 | 用什么 |
+|---|---|---|
+| **① 本体与员工技能** | 一套可继承、可验证的共享行为合同：什么时候该开口、消息算不算任务、外部动作要谁批准、风险怎么分级、什么算完成、哪些要记哪些能忘。你只写岗位不一样的那几十行 | `dingtalk-basic-behavior` · `agent enhance` · `examples/agents/` |
+| **② 身份获取与事件感知** | 把格式各异的原始事件归一成稳定结构。回复对象和执行身份会冻结成正文改不动的快照，发错人在结构上就做不到；权限和出口按场域绑定；同一个事件只产生一个 Run，崩了也不会丢、不会重复 | `prepare` · `run` · Field 配置 |
+| **③ 托管平台部署** | 先看计划再落盘：冻结本体和整棵 Skill 树的 hash 和写预算，写完独立回读、发加载烟测，重复跑同一版不再写入。出问题能回滚，上了线也能退役（当前落地于 Multica） | `deploy` · `promote` · `--retire` |
+| **④ 驱动它在钉钉里干活** | 外发就四个原语。动作做之前挡掉越权和发错目标，做完之后强制回读平台确认；结果不确定时不许乱重发，报完成得留下能再核验的证据 | `act` · Action Gate · `task checkpoint` |
+| **⑤ 评测设计** | 一套评测方法：帮你选够用的最低层级，决定一次结论要看哪几类证据，避免个别失败被平均分掩盖，把真实事故变成能复跑的用例，也给出什么时候不能上线 | `lab` · `workspace eval` · `dingtalk-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>` | 你 `agent/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/AGENTS.md` 里的岗位语义填成真的，再跑一次 `agent audit`，缺口就只剩 `host.load-probe`——那需要一个 Agent Host，见 [Compose Skill](skills/core/dingtalk-agent-compose/SKILL.md)。上面第 3 组云端命令要等你有了 Multica 归属和已声明的 Workspace 才用得上。
+**这是又一个 Agent 框架吗？**
+不是。它不带模型，也没有工具循环或 Agent 运行时。它给你的 Coding Agent 一套技能和一条命令行，让它把已有的 Agent 装配成钉钉数字员工。
 
-发布到 Multica 时，远端 System Prompt 必须与 manifest 指定的 `agent/AGENTS.md` 原文一致；部署哈希、Skill 清单和 assignment 证据只存在于 plan/operation/Receipt 控制面。Basic 与 Role Skills 通过平台原生 assignment 挂载，不再用额外启动 Prompt 或启动 Skill 承载机器协议。
+**和 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 或定时器。
 
 ## 文档
 
@@ -157,7 +184,7 @@ Prepared Run 只开放 `ack`、`reply`、`ask`、`silence` 四个消息原子动
 | 测试或调试已交付的 Agent | [Eval Skill](skills/core/dingtalk-agent-eval/SKILL.md) |
 | 查看公共行为协议（写给模型读的合同，不是教程） | [Basic Behavior Skill](skills/core/dingtalk-basic-behavior/SKILL.md) |
 | 复制一个完整示例开始改 | [Example Agents](examples/agents) |
-| 借鉴了哪些开源项目 | [Prior Art](docs/PRIOR-ART.md) |
+| 从哪些平台与开源项目持续吸收最佳实践 | [Prior Art](docs/PRIOR-ART.md) |
 
 行为资产来自可观察合同、反例修正和可部署验证；本项目不声称获得任何产品的隐藏系统提示词原文。