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

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 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.1 - 2026-07-20
+
+Documentation and evaluation-tooling release. **No runtime code changes** — `bin/` and `src/` behavior is identical to 0.1.4; the only `bin/` edit is a header comment. Ships on the `beta` dist-tag; `latest` stays at 0.1.4.
+
+### Changed
+
+- **Contract evaluations are tiered, and the default regression is 18 seconds instead of 12 minutes.** `npm run eval:contract` now runs only the 29 `core` scenarios (kernel behavior: Session/Run/Wait, Action Gate, response eligibility, perception, task checkpoint, completion gate). The 33 `extended` scenarios — Multica/OpenCode simulation, real tarball offline install, CLI install/upgrade, robot pool, L2/L3 memory providers, live-readiness runners — run under `npm run eval:contract:full`, which is what CI and `release:check` use. `--only=<id>` overrides the tier and can name any scenario. Four README string assertions were removed from the heaviest end-to-end scenarios; document integrity now belongs to `scripts/check-docs.mjs`, which covers every link and anchor in under a second instead of seven magic strings.
+- The `dingtalk-agent-eval` skill teaches running the smallest useful slice first. Without `--cases`, a suite runs every case on every lane, and each case costs a model call — that is time and money. The skill now gives a four-step widening order and distinguishes `--runs 1` (did it break?) from `--runs 3` (did it actually improve?).
+- The `dingtalk-agent-compose` skill no longer claims `dingtalk-agent-eval` is outside the default suite. It joined the default suite in 0.1.4-beta.17, so that sentence was telling users to install a skill they already had.
+
+### Fixed
+
+- Contract scenario 60 (`AgentEnhancement`) hardcoded a CLI version for its in-process call while the spawned CLI read the real one from `package.json`. Because the generated `dingtalk-agent.json` embeds `dtaVersion: ^${version}`, the two plans produced different `planId`s the moment the package version left the 0.1.4 line — so the scenario would have failed on *any* future version bump, not just this one. The scenario now derives the version from `package.json`, and was verified to pass under an unrelated synthetic version.
+
+- **Documentation restructured around three named models.** `docs/ARCHITECTURE.md` now answers four questions in order — what a digital employee is, what an Agent is *composed of* (model A), what it *depends on* (model B), and how this repository is *divided* (model C, six parts). Four mutually contradicting "layer" models previously coexisted across `README.md`, `docs/ARCHITECTURE.md`, `CLAUDE.md` and the `bin/` header comment; they are now one. Model C is a verified partition: every `src/` file belongs to exactly one part, with no overlap and no omission.
+- **README is a signpost, not a preview.** Three tables that were byte-identical to sections of `docs/ARCHITECTURE.md` were replaced by prose plus links, removing duplicate sources of truth. Normative rule restatements across the main documents dropped from 32 to 23, and the verification command block now has a single home in `AGENTS.md`.
+- **Scenario counts are no longer hardcoded.** Documents point at `node evals/run-contract-evals.mjs --list` instead of a number that was already stale in three places.
+- **DWS is now defined where it first appears**, and the quick start no longer calls bare `dta` before the PATH block takes effect.
+- `docs/plans/` (17 completed phase records) removed; the two unfinished items and one fixture-referenced design derivation moved to `docs/roadmap/`. `内网实相.md` → `docs/DWS-FIELD-NOTES.md`, `OPEN-SOURCE-REFERENCES.md` → `docs/PRIOR-ART.md`.
+- `examples/agents/` gained an index, and both example bodies now follow the four-block `AGENTS.md` contract that the Compose skill mandates.
+
+### Package contents
+
+- **Added**: `docs/ARCHITECTURE.md`, `docs/SELF-TEST.md`, `docs/PRIOR-ART.md`. Eight already-published files linked to the first two, so those links were broken inside the installed package.
+- **Removed**: `docs/SECOND-AGENT-ACCEPTANCE.md` (its unique content merged into `docs/SELF-TEST.md`) and six unreferenced PNG diagrams. The SVG originals remain.
+- Packed tarball drops from roughly 3.1 MB to 0.86 MB.
+
+### Added
+
+- `scripts/check-docs.mjs`, wired into `release:check`: fails on dead relative links, dead anchors, a packaged file referencing an unpackaged `docs/*.md`, or structural drift between the two READMEs. The middle check exists because that exact class of breakage had already reached the published package.
+
 ## 0.1.4 - 2026-07-20
 
 First stable release of the 0.1.4 line. It promotes the beta series to the `latest` dist-tag, which until now still pointed at 0.1.2. No code changes relative to `0.1.4-beta.19`; the entries below describe what accumulated across the beta line.

package/README.en.md

@@ -2,22 +2,24 @@
 
 # dingtalk-agent
 
-**A verifiable behavior foundation for DingTalk digital employees.**
+**Give every digital employee the same verifiable behavior foundation.**
 
 [![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) · [How it works](#how-it-works) · [Support](#support) · [Docs](#docs)
+[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)
 
-English · [简体中文](README.md)
+[简体中文](README.md) · English
 
 </div>
 
-`dingtalk-agent` (`dta`) is a **Skill-first behavior kernel and delivery toolchain** for DingTalk digital employees. It assembles role definition, shared behavior, role capabilities, and execution gates into an Agent Project that can be created, tested, promoted, and audited.
+`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.
 
-> **Skills advise. The CLI gates. DWS acts.** Skills decide when and why to act; the CLI pins identity, target, budget, idempotency, and readback; DWS executes DingTalk capabilities.
+> **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.
+
+**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.**
 
 ![The complete path from Agent definition to delivery through two identity types](docs/assets/agent-delivery-lifecycle.svg)
 
@@ -29,45 +31,53 @@ Requires Node.js 18.3+.
 npm install --global --prefix "$HOME/.local" \
   --registry=https://registry.npmjs.org @xdxer/dingtalk-agent@beta
 
+# setup writes a PATH block into ~/.zshrc or ~/.bashrc, but a child process
+# cannot change the current shell — so keep using the absolute path this round.
+# A new terminal can call `dta` directly.
 "$HOME/.local/bin/dta" setup --skip-cli-install
-dta doctor
+"$HOME/.local/bin/dta" doctor
 ```
 
-`setup` installs the Basic Behavior and Compose Skills, then checks DWS authentication and common Agent Hosts. Normal sessions do not require Workspace initialization.
+`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 can talk is not yet a reliable digital employee. `dta` turns the parts most likely to drift into inherited, verifiable contracts:
+A model that talks is not a digital employee that works reliably. `dta` turns the four most drift-prone concerns into inheritable, verifiable contracts:
 
-- **Response judgment:** decide whether to respond before deciding what to say; stay silent in an unmentioned group chat by default.
-- **Authority boundaries:** never infer identity, target, permission, authorization, or reply channel from message text or model memory.
-- **Evidence-backed completion:** command success, platform visibility, delivery, and human acceptance are different states.
-- **Reuse:** new Agents inherit shared behavior and add only role-specific differences instead of copying a giant prompt.
+- **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.
 
-## How it works
+## What an Agent is made of
 
-An Agent is assembled from four contract layers:
+Four things: the **Definition** (`AGENTS.md` — who I am, where my duties stop), **shared behavior** (the `dingtalk-basic-behavior` Skill — when to respond, ask, stay silent, close out), **role capability** (`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 Agent Host, DWS, managed platform, and event source it depends on are all outside this project.
 
-| Layer | Responsibility |
-|---|---|
-| **`AGENTS.md`** | Role, role-specific boundaries, operating pattern, common mistakes, and the Basic startup anchor |
-| **Basic Behavior** | Shared response eligibility, scope, authorization, privacy, completion, and memory behavior |
-| **Role Skills** | Domain judgment, procedure, prohibited actions, and acceptance criteria |
-| **Gate + Receipt** | Hard constraints for identity, target, budget, idempotency, state transitions, and platform readback |
+Full composition, dependencies, and boundaries: [Architecture](docs/ARCHITECTURE.md#2-一个-agent-由什么构成模型-a).
+
+**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:
+
+```bash
+dta agent audit \
+  --bindings agent.bindings.json \
+  --require-skill <role-skill-name> \
+  --verify-load --yes --json
+```
 
-The Prompt keeps only what must remain resident and precisely defined. The full behavior tree belongs in Skills. Constraints that cannot rely on model discretion belong in the Gate.
+## How this repo is divided
 
-### Create → test → promote
+**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).
 
-| Stage | Main artifact | Gate |
-|---|---|---|
-| **Create** | `AGENTS.md`, Basic, Role Skills, bindings | Unresolved placeholders keep the project `partial` |
-| **Test** | Isolated Workspace, load probe, behavior eval, four evidence surfaces | A project cannot become ready without proven Definition/Skill loading |
-| **Promote** | Platform preflight, deployment Receipt, remote readback | Missing designated Eval evidence or identity chain blocks promotion |
-| **Operate** | Digital-employee account or robot entry point, task trace | No claim of write, delivery, or completion without matching evidence |
+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).
+
+## Create → test → promote
+
+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-从定义到上线).
 
 ```bash
-# 1. Generate a zero-write plan, then apply it explicitly
+# 1. Generate a zero-write plan, then commit it explicitly
 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
@@ -77,7 +87,7 @@ dta agent audit --bindings agent.bindings.json --require-skill release-manager -
 dta workspace run local-dev --json
 dta workspace eval local-dev --json
 
-# 3. Inspect, promote, and observe
+# 3. Cloud preflight, promotion, and observation
 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
@@ -86,26 +96,39 @@ dta observe --promotion-id <promotion-id> --input <observation.json> --dry-run -
 
 Plans are zero-write by default. Remote writes require an explicit target, the current `planId`, and confirmation.
 
-## Support
+The placeholders above are not yours to invent — each has a definite source:
+
+| Placeholder | Where it comes from |
+|---|---|
+| `<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 `skills/<role>/SKILL.md` frontmatter |
+
+### Minimal runnable path (local only, three commands)
 
-### Platforms, Harnesses, and runtimes
+To see something move first, don't start with the chain above — that is the full delivery pipeline. Start here:
 
-These are separate concepts:
+```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
+```
+
+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 `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.
+
+## Support
 
-- A **Managed Agent Platform** owns Workspace, Runtime, Agent, Skill, identity binding, and observation.
-- An **Agent Harness** loads Definition/Skills, isolates execution, and captures evidence.
-- The **dta Kernel** depends on a shared contract, not a specific Harness prompt or private directory layout.
+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:
 
 | 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 current complete local managed-Harness reference |
+| **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 |
 
-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.
+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.
 
 ### Runtime modes
 
@@ -117,50 +140,20 @@ OpenCode is not a runtime dependency, and Multica is not a privileged bypass. An
 
 Prepared Runs expose four message atoms: `ack`, `reply`, `ask`, and `silence`. An acknowledgement is not task acceptance, and a reply is not human acceptance.
 
-## What a generated Agent inherits
-
-```text
-my-agent/
-├── AGENTS.md                     Role constitution + Basic inheritance anchor
-├── agent.bindings.json           Definition and storage routing
-├── dingtalk-agent.json           Agent Project desired state
-├── .agents/skills/
-│   ├── dingtalk-basic-behavior/  Complete shared behavior tree
-│   └── <role>/                   Host-discoverable Role Skill
-├── skills/<role>/SKILL.md        Versioned role capability source
-└── .dingtalk-agent/              Private state, evidence, and Receipts
-```
-
-The generated `AGENTS.md` keeps four atomic contracts: **definition, non-negotiable boundaries, operating pattern, and common mistakes**. It also says to apply `dingtalk-basic-behavior` before loading task-relevant Role Skills.
-
-File presence is not inheritance evidence. `agent audit --verify-load` binds real load results to Definition/Skill hashes, Host/model versions, isolated probes, and raw run/export evidence:
-
-```bash
-dta agent audit \
-  --bindings agent.bindings.json \
-  --require-skill <role-skill-name> \
-  --verify-load --yes --json
-```
-
-## Non-negotiable boundaries
-
-- Normal sessions never auto-run `dingtalk-agent init`.
-- Target, actor, conversation, DWS profile, and permissions come only from a trusted Host or event.
-- Prepared Run messaging goes only through a typed Broker or `dta act`; it cannot bypass the Gate.
-- An online Run may propose memory or Skill candidates, but cannot hot-modify current identity, permission, or policy.
-- Model claims, process exit 0, platform-visible writes, delivery, and human acceptance require separate evidence.
+**Triggers are out of scope for this project**: `listen` is a replaceable local integration Adapter, and `dta deploy` never creates robots, webhooks, or timers.
 
 ## Docs
 
 | Goal | Start here |
 |---|---|
-| Understand architecture and state | [Architecture](docs/ARCHITECTURE.md) |
+| Understand the Agent architecture and how the repo is divided | [Architecture](docs/ARCHITECTURE.md) |
 | Install, upgrade, or troubleshoot | [Installation](docs/INSTALLATION.md) |
 | Understand evaluation and evidence levels | [Self-test](docs/SELF-TEST.md) |
 | Create or audit an Agent | [Compose Skill](skills/core/dingtalk-agent-compose/SKILL.md) |
 | Test or debug a delivered Agent | [Eval Skill](skills/core/dingtalk-agent-eval/SKILL.md) |
-| Read the shared behavior protocol | [Basic Behavior Skill](skills/core/dingtalk-basic-behavior/SKILL.md) |
-| Copy a complete example | [Example Agents](examples/agents) |
+| 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) |
 
 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

@@ -9,7 +9,7 @@
 [![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)
 
@@ -19,6 +19,8 @@
 
 > **Skill 劝，CLI 拦，DWS 做。** Skill 判断何时、为何行动；CLI 固定身份、目标、预算、幂等与回读；DWS 执行钉钉能力。
 
+其中 **DWS 是钉钉侧的命令行工具**（独立于本项目，需单独安装并 `dws auth login`），涵盖消息、文档、AI 表格、日程、审批等约 20 类产品能力。`dta` 不复制它的命令面，只在需要冻结身份、目标、幂等或回读时包一层——**所有真实的钉钉操作最终都由 DWS 执行**。
+
 ![从 Agent 定义到两类身份交付的完整路径](docs/assets/agent-delivery-lifecycle.svg)
 
 ## 快速开始
@@ -29,42 +31,49 @@
 npm install --global --prefix "$HOME/.local" \
   --registry=https://registry.npmjs.org @xdxer/dingtalk-agent@beta
 
+# setup 会把 PATH 区块写进 ~/.zshrc 或 ~/.bashrc，但子进程改不了当前 shell，
+# 所以这一轮继续用绝对路径；之后开新终端即可直接用 `dta`。
 "$HOME/.local/bin/dta" setup --skip-cli-install
-dta doctor
+"$HOME/.local/bin/dta" doctor
 ```
 
-`setup` 安装 Basic Behavior 与 Compose Skills，并检查 DWS 认证和常见 Agent Host。普通会话无需初始化 Workspace。
+`setup` 安装 Basic Behavior、Compose 与 Eval Skills，并检查 DWS 认证和常见 Agent Host。普通会话无需初始化 Workspace。
+
+**纯本地能走多远**：装配、审计、`workspace run/eval` 与全部合同评测都不需要钉钉账号或托管平台——`doctor` 会把缺失项标成 `partial` 而不是失败。只有真实外发、远端语义状态和 `deploy`/`promote` 才需要 DWS 认证与 Multica。
 
 ## 为什么需要它
 
-模型会说话，不等于数字员工能可靠工作。`dta` 把最容易漂移的部分变成可继承、可验证的合同：
+模型会说话，不等于数字员工能可靠工作。`dta` 把最容易漂移的四件事变成可继承、可验证的合同：
 
 - **会判断**：先判断是否该回复，再判断说什么；群聊未 `@` 默认安静。
 - **不越权**：身份、目标、权限、授权和回复渠道不能从正文或模型记忆猜测。
-- **不虚报**：命令成功、平台可见、消息送达和人类接受是不同的完成层级。
+- **不虚报**：命令成功、平台可见、消息送达和人类接受是四个不同的完成层级，各自举证。
 - **可复用**：新 Agent 继承公共行为，只补岗位差异，不复制巨型 Prompt。
 
-## 工作方式
+## 一个 Agent 由什么构成
 
-一个 Agent 由四层合同组成：
+四件东西：**本体**（`AGENTS.md`，我是谁、职责边界）、**公共行为**（`dingtalk-basic-behavior` Skill，何时响应/追问/沉默/收口）、**岗位能力**（`skills/<role>/SKILL.md`）、**存储路由**（`agent.bindings.json`，可选——等价配置也可来自宿主 context、环境变量或 Workspace manifest）。它依赖的 Agent Host、DWS、托管平台和事件源都不属于本项目。
 
-| 层 | 负责什么 |
-|---|---|
-| **`AGENTS.md`** | 定义角色、岗位底线、做事范式和常犯错误；声明每轮先应用 Basic |
-| **Basic Behavior** | 所有数字员工共享的响应资格、作用域、授权、隐私、完成与记忆协议 |
-| **Role Skills** | 某个岗位的专业判断、流程、禁区和验收标准 |
-| **Gate + Receipt** | 把身份、目标、预算、幂等、状态迁移和平台回读变成硬约束 |
+完整的构成、依赖与边界见 [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
+```
 
-Prompt 只保留必须常驻、必须严格定义的内容；完整行为树进入 Skill；不能依赖模型自觉的约束进入 Gate。
+## 这个仓库分成哪几部分
 
-### 创建 → 测试 → 发布
+**行为内核**（事件 → 能否回应、回应给谁、允许做什么）、**装配与审计**（把仓库/目录/文档变成可 hash 的 Agent 并证明真加载）、**交付链**（受控上托管平台，每步可回读）、**评测与证据**（上线前用最低成本证明它真会做事）、**状态与记忆**（崩了之后接着做）、**机器与分发**（一条命令装好一台新机器）。
 
-| 阶段 | 关键产物 | 门禁 |
-|---|---|---|
-| **创建** | `AGENTS.md`、Basic、Role Skills、bindings | 占位符未补全时保持 `partial` |
-| **测试** | 隔离 Workspace、load probe、行为评测、四类证据 | Definition/Skills 没有真实加载就不能 ready |
-| **发布** | 平台预检、部署 Receipt、远端 readback | 指定 Eval 未通过或身份链不完整就不能 promote |
-| **运行** | 数字员工账号或机器人入口、task trace | 无证据不声称写入、送达或完成 |
+交付链与评测各占约四分之一代码量——这个项目的难点从来不是"让模型说话"，而是证明它真的装好了、做对了、上线了。每部分解决什么问题、对应哪些模块与 CLI，见 [Architecture](docs/ARCHITECTURE.md#7-dingtalk-agent-分成哪几部分模型-c)。
+
+## 创建 → 测试 → 发布
+
+四个阶段各有门禁：占位符没填完保持 `partial`；Skill 没真加载不能 ready；指定 Eval 没过不能 promote；没有证据不声称送达或完成。逐条见 [Architecture](docs/ARCHITECTURE.md#8-从定义到上线)。
 
 ```bash
 # 1. 创建零写入计划，再显式落盘
@@ -86,26 +95,39 @@ dta observe --promotion-id <promotion-id> --input <observation.json> --dry-run -
 
 所有计划默认零写入；所有远端写入都需要明确目标、当前 `planId` 和显式确认。
 
-## 支持范围
+上面的占位符不是让你自己编的，各有确定来源：
+
+| 占位符 | 从哪来 |
+|---|---|
+| `<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` |
+
+### 最小可运行路径（纯本地，三条命令）
 
-### 平台、Harness 与运行时
+想先看见东西动起来，不要从上面那串开始——那是完整交付链。从这里开始：
 
-这三个概念彼此独立：
+```bash
+cp -R examples/agents/release-manager my-agent && cd my-agent
+dta bootstrap --json      # 本体被识别了吗：看 definition.status 与 storage 路由
+dta agent audit --json    # 预期 partial —— 岗位语义还是模板，这是正确结果
+```
+
+到这一步不需要钉钉账号、不需要托管平台、不产生任何副作用。把 `AGENTS.md` 里的岗位语义填成真的，再跑一次 `agent audit`，缺口就只剩 `host.load-probe`——那需要一个 Agent Host，见 [Compose Skill](skills/core/dingtalk-agent-compose/SKILL.md)。上面第 3 组云端命令要等你有了 Multica 归属和已声明的 Workspace 才用得上。
+
+## 支持范围
 
-- **Managed Agent Platform** 管 Workspace、Runtime、Agent、Skill、身份绑定和观测。
-- **Agent Harness** 加载 Definition/Skills，隔离执行并采集证据。
-- **dta Kernel** 依赖统一合同，不依赖某个 Harness 的私有 Prompt 或目录结构。
+**Managed Agent Platform**（管 Workspace、Runtime、身份绑定与观测）、**Agent Host**（也叫 Harness，加载 Definition/Skills 并隔离执行）和 **dta Kernel** 三者彼此独立：
 
 | 维度 | 当前支持 |
 |---|---|
 | **Managed Platform** | Multica（DingTalk）已支持；DEAP 为 Coming soon；更多平台通过 registry + adapter 接入 |
-| **本地运行** | Claude Code、Codex、OpenCode 等 Direct/Mounted Session；OpenCode 是当前完整的本地 managed Harness 参考实现 |
+| **本地运行** | Claude Code、Codex、OpenCode 等 Direct/Mounted Session；OpenCode 是当前最完整的本地 managed Harness 参考实现 |
 | **云上运行** | Multica Workspace / Runtime / Agent；沿用相同的 Definition、Skills、Gate 与证据合同 |
 | **交付身份** | 数字员工/账号身份；机器人应用身份；两者都不能改变角色职责或扩大权限 |
 
-OpenCode 不是运行前提，Multica 也不是特殊旁路。任何 Harness 要进入可晋级路径，都必须证明同一件事：Definition 与 Skills 已加载、身份和隔离已固定、运行轨迹可取、结果可回读。
-
-“支持多平台”指架构、注册表和 adapter 合同可扩展；不把尚未开放的平台宣称为已部署或已 Live 验证。
+OpenCode 不是运行前提，Multica 也不是特殊旁路。任何 Harness 要进入可晋级路径，都必须证明同一件事：Definition 与 Skills 已加载、身份和隔离已固定、运行轨迹可取、结果可回读。"支持多平台"指架构、注册表和 adapter 合同可扩展，不把尚未开放的平台宣称为已部署或已 Live 验证。
 
 ### 三种运行模式
 
@@ -117,50 +139,20 @@ OpenCode 不是运行前提，Multica 也不是特殊旁路。任何 Harness 要
 
 Prepared Run 只开放 `ack`、`reply`、`ask`、`silence` 四个消息原子动作。`ack` 不等于接单，`reply` 不等于对方接受。
 
-## 创建出来的 Agent 会继承什么
-
-```text
-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
-```
-
-生成的 `AGENTS.md` 只保留四块原子合同：**定义、不能做的底线、做事标准范式、常犯错误**。模板同时声明每个任务先应用 `dingtalk-basic-behavior`，再按任务加载 Role Skills。
-
-“文件存在”不是继承证据。`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
-```
-
-## 不可绕过的边界
-
-- 普通 Session 不自动运行 `dingtalk-agent init`。
-- target、actor、conversation、DWS profile 与权限只来自可信宿主或事件。
-- Prepared Run 的消息副作用只走 typed Broker 或 `dta act`，不能绕过 Gate。
-- 在线 Run 可以提出记忆或 Skill 候选，但不能热修改当前身份、权限或策略。
-- 模型自述、命令退出 0、平台写入可见、消息送达与人类接受必须分别举证。
+**触发器不属于本项目**：`listen` 只是本地联调的可替换 Adapter，`dta deploy` 不创建机器人、Webhook 或定时器。
 
 ## 文档
 
 | 想做什么 | 从这里开始 |
 |---|---|
-| 理解架构与状态模型 | [Architecture](docs/ARCHITECTURE.md) |
+| 理解 Agent 架构与仓库分工 | [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) |
+| 查看公共行为协议（写给模型读的合同，不是教程） | [Basic Behavior Skill](skills/core/dingtalk-basic-behavior/SKILL.md) |
+| 复制一个完整示例开始改 | [Example Agents](examples/agents) |
+| 借鉴了哪些开源项目 | [Prior Art](docs/PRIOR-ART.md) |
 
 行为资产来自可观察合同、反例修正和可部署验证；本项目不声称获得任何产品的隐藏系统提示词原文。
 

package/dist/bin/dingtalk-agent.js

@@ -1,13 +1,17 @@
 #!/usr/bin/env node
 // dingtalk-agent —— 钉钉数字员工的标准范式（TypeScript source）。
 //
-//   CLI   = 拦   标准动作：可程序化、可强制、可验证。撞上去没得商量。
 //   Skill = 劝   判断：只有 LLM 能做的（该不该答、话题归属、怎么写点评）。
-//   本体  = 记   它是谁 + 它知道什么。git clone 就带走。
+//   CLI   = 拦   标准动作：可程序化、可强制、可验证。撞上去没得商量。
+//   DWS   = 做   真正的钉钉产品能力；本文件只在需要冻结事务边界时包一层。
 //
-// **分界线：凡是能程序化的，收进 CLI；凡是需要判断的，留在 Skill。**
+// 本体（AGENTS.md + Role Skills）负责"它是谁、它知道什么"，git clone 就带走；
+// 它是被上面三者加载和校验的对象，不是第四个执行者。
 //
+// **分界线：凡是能程序化的，收进 CLI；凡是需要判断的，留在 Skill。**
 // 因为：文档会被漏读、误读、自我说服；**撞到闸门上就没得商量。**
+//
+// 完整架构见 docs/ARCHITECTURE.md。
 import { parseArgs } from 'node:util';
 import { join, relative, resolve } from 'node:path';
 import { existsSync, readFileSync, realpathSync } from 'node:fs';