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

package/docs/ARCHITECTURE.md

@@ -0,0 +1,366 @@
+# dingtalk-agent 架构
+
+本文回答四个问题：**一个数字员工是什么**、**它由什么构成**、**每件事谁说了算**、**这个仓库分成哪几部分、各解决什么问题**。
+
+本文不写：安装与升级（见 [Installation](INSTALLATION.md)）、评测方法与证据分层（见 [Self-test](SELF-TEST.md)）、Agent 的行为协议（见 [Basic Behavior Skill](../skills/core/dta-basic-behavior/SKILL.md)）、发布历史（见 [CHANGELOG](../CHANGELOG.md)）、进行中的工作（见 [roadmap](roadmap/)）。
+
+![dingtalk-agent 架构总览：五个部件、五个权威，本仓库只拥有一个](architecture/dingtalk-agent-architecture.svg)
+
+上图是全貌，编号对应 §1 的五个部件：实心编号是本仓库拥有的，空心编号由外部签发或提供。下面逐层展开。
+
+---
+
+## 1. 什么是一个数字员工
+
+![数字员工的五个部件与各自的权威](architecture/digital-employee-composition.svg)
+
+一个聊天机器人只需要把输入变成输出。一个数字员工要额外成立四件事：
+
+- **稳定身份**：它是谁、受谁委托、以谁的名义在平台上留下痕迹，不随聊天内容变化；
+- **明确作用域**：这次被授权做什么、对谁、到哪一步，不由正文自行扩张；
+- **可核验的完成**：说"做完了"必须对应产物、Receipt 或独立回读，不能以回复正文自证；
+- **可丢弃的执行体**：沙箱、进程、模型可以随时换掉，事情还能接着做。
+
+**这四件事没有一件能由 Agent 自己提供——数字员工不等于 Agent。** 它是一个 Agent 装配上组织语境之后的结果：
+
+```text
+数字员工 = Agent 本体            ← 本仓库
+         + 组织身份与场域授权    ← 钉钉数字员工平台
+         + 感知通道（事件）      ← 钉钉事件中心 / DWS
+         + 平台执行能力          ← DWS
+         + 运行位置              ← Managed Agent Platform / Agent Host
+```
+
+运行时上，本仓库只提供第一项；其余四项由外部提供，本仓库不实现也不替代，但必须逐一显式建模，否则边界会悄悄溜走（见 §3）。
+
+> ⚠️ **这张等式回答的是「一个跑起来的数字员工由什么组成」，用途是界定依赖——它不是「本项目做什么」的答案。** 把两者混为一谈会严重低估本项目的范围。「本项目做什么」要换一个正交的视角看：**开发域**。
+
+**开发域：把一个 Agent 变成钉钉数字员工，要走完六段——这六段本项目全管。**
+
+| 段 | 本项目替开发者完成什么 |
+|---|---|
+| **① 本体与员工技能** | 一份可继承、可 hash、可验证的共享行为合同（响应资格、意图分级、授权模型、风险分级、证据阶梯、完成判定、记忆与遗忘），加本体与岗位骨架 |
+| **② 身份获取与事件感知** | 把来路不明的原始事件归一成稳定合同，冻结回复目标与执行身份，按 Field 绑定权限与出口，补齐现场，并保证同一事件只产生一个 Run |
+| **③ 托管平台部署** | 把手工搬运变成 plan → apply → 独立回读 → 加载烟测 → Receipt 的受控发布链，幂等、可回滚、可退役 |
+| **④ 驱动它在钉钉里干活** | 四个动作原语 + Action Gate：副作用前冻结目标身份，副作用后强制平台回读，完成必须有物证 |
+| **⑤ 评测设计** | L0–L4 证据分层方法学、四个 runner、多面证据硬门禁，以及「真实事故 → 可复跑场景」的沉淀路径 |
+| **⑥ 观测与计量** | 目前**最薄的一段**：只有把线上人工观察安全灌回评测素材的受控通道；用量计量尚未实现（见 §8） |
+
+逐段的能力、边界与缺口见 [§8 开发生命周期](#8-开发生命周期从定义到观测)。一句话概括这两个视角的关系：**运行时的底座我们不造；但把 Agent 变成数字员工的这条生产线，从头到尾是我们的。**
+
+三类东西的可变性完全不同，必须分开对待：
+
+| 类别 | 内容 | 本仓库的职责 |
+|---|---|---|
+| **外部签发** | 组织身份、场域授权、事件信封 | 冻结进 Session、全程审计，永不扩权 |
+| **可替换** | 触发端、模型、沙箱、运行位置、岗位能力 | 只要求一份可验证的加载与执行合同 |
+| **本仓库不变** | 定义、上下文、状态、闸门、效果证据 | 唯一拥有；全部设计取舍都服务于把它们从执行体里独立出来 |
+
+「外部签发」这一类最容易被漏掉：**身份既不可替换，也不由本仓库提供。**
+
+## 2. 一个 Agent 由什么构成（模型 A）
+
+三个模型互不重叠，各回答一个问题：**A 交付物由什么组成**、**B 每件事谁说了算**、**C 这个仓库自己分成哪几块**。「Skill 劝，CLI 拦，DWS 做」是贯穿三者的唯一职责口径（见 §4）。
+
+| 部件 | 回答什么 | 落在哪 | 谁生成 / 谁校验 |
+|---|---|---|---|
+| **本体 Definition** | 我是谁、服务谁、岗位底线、做事范式、常犯错误 | `agent/AGENTS.md` | `agent enhance` 生成骨架；`agent audit` 校验语义占位符是否已填 |
+| **公共行为** | 何时响应、如何追问、何时沉默、如何收口 | `agent/skills/dta-basic-behavior` | 内核内置；`agent audit --verify-load` 证明它真被加载 |
+| **岗位能力** | 某个岗位的方法、SOP、禁区、验收标准 | `agent/skills/<role>/SKILL.md` | 开发者编写；`--require-skill` 校验存在与加载 |
+| **存储路由** | 长期内容与私有控制状态各自去哪 | `agent.bindings.json`（可选） | `bootstrap` 归一成 `agent-definition@1`；缺省时按宿主 context > 环境变量 > Workspace manifest > 目录约定依次解析 |
+
+这四项不是设计出来的分类，而是从 `agent-definition@1` 直接读出来的字段（`src/agent-definition.ts`）。一个 Agent 的最小目录形态：
+
+```text
+my-agent/
+├── AGENTS.md                     仓库 Coding Agent 开发约束，不发布
+├── agent/                        managed platform 的唯一同步边界
+│   ├── AGENTS.md                 本体：角色宪法 + Basic 继承锚点
+│   └── skills/                   Basic 与 Role Skills 的唯一发布源
+├── agent.bindings.json           存储路由与 DWS authority（可选，见下）
+└── .dingtalk-agent/              私有状态、证据与 Receipt（gitignored）
+```
+
+Host 原生发现目录不是发布源。OpenCode 的 `.agents/skills/`、Claude Code 的 `.claude/skills/` 等只在 dta 创建的隔离工作区临时物化并回收，不能与 `agent/skills/` 一起提交。已有代码仓库可在 `dingtalk-agent.json` 显式声明其它 `agent.definition` 与 `agent.skillsRoot`，不因升级 CLI 被强制迁移。
+
+"文件存在"不是继承证据。`agent audit --verify-load` 把真实加载结果绑定到 Definition/Skill hash、Host 与模型版本、隔离探针和原始 run/export；任何一项漂移，旧证据即失效。
+
+## 3. 每件事谁说了算（模型 B）
+
+![dingtalk-agent 在托管平台与钉钉之间的连接层位置](architecture/agent-platform-connection-layer.svg)
+
+§1 的五个部件各有一个「谁说了算」。下表按权威归属重排，把本仓库拥有的那一项放在最后：其余四行本仓库只有约束——**写下来是为了让边界可检查，不是因为我们要做它们**：
+
+| 这件事谁说了算 | 权威 | 本仓库的边界 |
+|---|---|---|
+| **组织身份、场域与权限** | 钉钉数字员工平台 | 不发证、不改写、不扩权；只把签发结果冻结进 Session 并全程审计 |
+| **事件信封**（谁、在哪、说了什么） | 钉钉事件中心 / DWS | **不拥有触发器**（见下）；只要求信封可信、可幂等 |
+| **平台能力执行** | DWS | 不复制 DWS 命令面，只在需要冻结事务边界时包一层。`src/dws.ts` 是全仓库唯一 spawn `dws` 的地方；实战缺陷见 [DWS Field Notes](DWS-FIELD-NOTES.md) |
+| **运行位置** | Managed Agent Platform / Agent Host | 不自己做 Host、不自建 Runtime；通过 registry + adapter 连接，只要求一份可验证的加载合同 |
+| **本体、行为、状态与效果证据** | **本仓库 + Git** | 唯一拥有的一行 |
+
+**运行位置既是可替换项，也是本项目的连接面。** 接入一个平台等于「**一个平台 Skill 包 + 注册表一条记录**」，方法学不进内核也不进 CLI（目录约定见 [skills/README](../skills/README.md)）。当前 **Multica 已支持，DEAP 敬请期待**；「可扩展」指注册表与 adapter 合同可扩展，不表示尚未开放的平台已经可用——未开放平台的所有平台命令一律 fail-closed。各平台的最佳实践如何被观察和吸收，见 [Prior Art](PRIOR-ART.md)。
+
+**DEAP 可能同时落在第一行和第四行。** 它在本项目里的主要角色是钉钉侧的身份与感知平面（第一行）：签发身份、划定场域、送来事件、统一展示结果。它是否同时内建自己的 Agent 运行平台（第四行）尚待确认，注册表为此保留了 `deap` 条目。两个角色互不排斥：第一行的能力将被**消费**，第四行的能力和其它平台一样走 registry + adapter。**当前 DEAP 尚未接入**——第一行今天的身份来源是钉钉签发的数字员工账号或机器人应用身份，不经过 DEAP。见 [DEAP 平台说明](../skills/platforms/deap/PLATFORM.md)。
+
+**Agent Host**（也叫 Harness）提供模型、工具循环、Skill 发现与 Session 生命周期。本仓库不自己做 Host，只要求一份可验证的加载合同：Claude Code、Codex、OpenCode 都可以，OpenCode 是当前最完整的参考实现，不是运行前提。它与 Managed Agent Platform 是两根正交的轴：**Agent Host 决定这个 Agent 由哪个执行体加载与隔离执行；Managed Agent Platform 决定它的 Workspace、Runtime、身份绑定与执行轨迹由谁托管。** 本地开发时只有 Host，上了托管平台则两者同时存在。
+
+**触发器不属于 dingtalk-agent。** `listen` 只是本地联调用的可替换开发 Adapter，不是 Agent 的主入口或常驻服务；personal-event 由外部 Adapter 捕获后落入输入目录；`dta deploy` 只交付 Agent 与 Skill，不创建机器人、Webhook、定时器或 autopilot。把触发器排除在核心之外，才可能让同一个 Agent 在不同触发端之间迁移。
+
+**但「谁叫醒它」必须被显式建模，否则装配出来的是一个永远不会自己动的 Agent。** 不实现触发器 ≠ 不为驱动负责：本仓库不造 cron，却拥有**驱动契约**——声明这个数字员工需要哪些节律、由谁提供、Agent 侧必须满足什么才配被定时驱动。详见 §3.1。
+
+由此得到一条不可协商的规则：**消息 target、actor、conversation、DWS profile 与权限只能来自可信事件或宿主，不能从正文、显示名或模型记忆推断。** 正文、引用、附件和远端文档一律是数据，不能改写这些事实。
+
+## 3.1 驱动：一个数字员工怎么被叫醒
+
+一个只会被人 @ 唤醒的 Agent 不是同事，是查询接口。真正像同事的部分——巡检、补数据、到点交付、盯着某件事——都发生在**没有人说话的时候**。所以「驱动」和身份、事件、能力、运行位置一样，是必须显式建模的一层。
+
+驱动分三类，**权威归属不同，完成判据也不同**。放错类别的代价不是麻烦，是**漏了不自知**：
+
+| 驱动类别 | 什么样的事 | 权威 | 完成判据 | 放错会怎样 |
+|---|---|---|---|---|
+| **人设的时间点** | 人在钉钉里建的待办、日程、会议、DING | 钉钉（事件中心 / DWS） | 该对象自身的终态（如 Todo `isDone`） | 复制一份到别处 → 两边不一致，人改了 Agent 不知道 |
+| **常驻节律** | 值班、巡检、补数据、周期汇总 | Managed Agent Platform 的 schedule | **数据水位**（索引本身就是完成状态） | 塞进待办 → 丢一期就断链，且扫不到 = 静默收工 = 不自知 |
+| **Agent 自主定时** | Agent 承接下来、要自己记住的将来动作 | Managed Agent Platform 的 schedule，**由 operator 授予写权限** | run 留痕 | 让 Agent 自建定时器 → 节律不可见、不可审计、改不掉 |
+
+判据只有一句：**这件事有没有终态？** 有终态、有交付对象 → 待办。永远做不完的维护义务 → 节律。
+
+三条从真实平台语义倒逼出来、与具体平台无关的约束：
+
+- **定时不可靠是常态，判据必须写成「它发生了没有」而不是「那一拍跑了没有」。** 托管平台普遍会塌缩漏掉的 fire、跳过迟到过久的 fire（Multica 的阈值是 5 分钟）。凡是把「某时刻必须发生的事」绑定到「某一拍」的设计，一次 runtime 抖动就永久丢一期，而且事后查不出来。
+- **外发类节律的留痕在动作之后，所以它没有锁。** 两个节律落在同一分钟并发唤醒，就会把同一条消息发两遍给第三方。多节律拆分必须错开触发时刻。
+- **Agent 不自建定时器、不自改节律。** 节律是可审计的部署产物；在线 Run 只能把新节律整理成候选交给 operator，不能自己配上再宣称配好了——这与 §1「在线 Run 不能热改身份、权限或已启用 Skill」是同一条边界的延伸。
+
+**本仓库在这一层拥有什么**：不拥有 cron，拥有三件事——装配时**声明**需要哪些节律与是否允许 Agent 自主排程（`dta-agent-compose`）；部署到具体平台时**校验**该平台是否真的提供这些能力、不提供就 fail closed（平台 Skill 包 + `agent-platform` 注册表）；以及 Agent 侧被定时驱动时必须满足的**行为合同**（`dta-basic-behavior`）。**平台之间能力不同是常态**——同一个 Agent 的节律声明可以不变，能不能被满足由目标平台回答。`dta schedule show` 还会静态检两条与平台无关的不变量：**同刻并发**（按真实 occurrence 枚举判，判不准的当撞车挡住）和**缺完成判据**（声明了 cron 却没写数据派生 `completion` 的记成缺口）。
+
+## 4. 谁拦住什么：Skill 劝，CLI 拦，DWS 做
+
+![通用 Agent 行为内核拓扑](architecture/general-agent-kernel-topology.svg)
+
+- **Skill 劝**：判断该不该做、为何做、做到哪一步。这是语义判断，会被上下文影响，因此不能承担安全边界。
+- **CLI 拦**：固定身份、目标、预算、幂等、状态迁移与回读。不依赖模型自觉。
+- **DWS 做**：执行具体钉钉产品能力。
+
+一个动作**只有**在需要下列任一项时才进入 `dingtalk-agent`，否则继续直接用 DWS：
+
+1. 冻结作用域或收件人；2. 权限与授权校验；3. 幂等，且失败后不能盲重试；4. 写后必须独立回读；5. 状态迁移有合法性约束；6. 跨产品事务组合。
+
+举例：`memory operational upsert` 之所以是 CLI 命令而不是一句 DWS 调用，正因为它同时命中 3、4、6——它按 `key + scopeId` 唯一定位一行，create/update 后必须按 recordId 独立回读，匹配多行或回读不一致就进入 reconcile 而不是重试。
+
+## 5. 三种运行模式与 Prepared Run 的四个对象
+
+![持久异步运行模型](architecture/durable-async-agent-runtime.svg)
+
+| 模式 | 何时进入 | 关键边界 |
+|---|---|---|
+| **Direct Session** | 无 `CONTEXT.md`、无 Workspace | 全局 Skill 仍生效；不自动 init，不假造钉钉目标 |
+| **Mounted Session** | 有 Workspace 或显式 storage | 通过 `bootstrap` 按需水合身份、记忆与知识 |
+| **Prepared Run** | 上游提供可信事件 envelope | 冻结目标、身份、Field、Skill 与动作预算；副作用只走 typed Broker 或 `dta act` |
+
+**Field** 是一个稳定的协作与权限边界：它声明这一摊事归谁、用哪个 DWS 身份出口、允许对哪些人和会话行动。一个 Workspace 可以有多个 Field；Session 创建时从中取走冻结副本，正文和在线 Run 都改不了它。默认模板见 `templates/fields/default/field.json`。
+
+三种模式的判定顺序与检测流程由 [Basic Behavior](../skills/core/dta-basic-behavior/SKILL.md) 拥有；`init` 与 `bootstrap`、`setup` 的分工见 [Installation](INSTALLATION.md)。
+
+Prepared Run 只有四个公开对象：
+
+| 对象 | 生命周期 | 物理形态 | 作用 |
+|---|---|---|---|
+| Workspace | 长期、可选 | 一个目录或远端语义挂载 | 身份、内容、Field 和 Skill 清单 |
+| Session | 一件事 | `.dingtalk-agent/sessions/.../<sessionId>` | 工作记忆、Skill 绑定、跨消息延续 |
+| Run | 一次信号 | `Session/runs/<runId>` | 冻结输入；每次可启动新沙箱 |
+| Action | 一次效果 | intent + attempt + receipt | `ack` / `reply` / `ask` / `silence` |
+
+四个动作的语义、何时用哪一个，由 Basic Behavior 拥有，本文不复述。Wait、Event Journal、dispatch outbox 和 reply target 是宿主内部实现，不要求 Agent 学习。
+
+**Task checkpoint 是 Session 的可选业务投影，不是第五个控制对象。** 只在跨 Run、等待依赖、已产生副作用或需要换手时创建；Prepared Run 写 `$DTA_SESSION/memory/task.json`，用 revision CAS 加 durable lease 防并发覆盖，原子写后必须回读。它不接管锁、事件去重或 Receipt。
+
+与异步进程模型的对应关系：
+
+| 进程隐喻 | 实体 |
+|---|---|
+| Heap | Field/Workspace 的身份、知识、Skill |
+| Stack | Session working memory 与事项状态 |
+| 一次函数调用 | Run |
+| syscall | Action |
+| await continuation | 宿主内部 Wait |
+| interrupt | 新事件、心跳、显式取消 |
+
+`ask` 之后当前 Run 结束、沙箱释放；匹配事件产生新 Run 并回到原 Session。系统恢复的是显式 checkpoint 和外部成果，不序列化 JavaScript/LLM 隐藏栈。
+
+一个具体读法——FDE 教练实例：
+
+| 对象 | 在 FDE 教练里是什么 |
+|---|---|
+| Workspace | 菲迪身份、评价原则、学员资料 |
+| Role Skill | 生成评价、等待确认、调整、发布的方法 |
+| Session | "给张三本轮评价并等确认"这一件事 |
+| Run | 每条新信号唤醒的一次沙箱 |
+| Action | 收到、回复、追问、沉默 |
+
+FDE 的评价模板和发布流程不进入全局 Basic Behavior；否则任何钉钉员工都会被污染成教练。
+
+### 双半闸门
+
+Response Gate 是**生成前**的安全半闸门：mention/DM 获得处理 origin 的资格，ambient group 固定 silent，heartbeat 只 inspect。Perception Enricher 是**贴心**半闸门——所谓"贴心"是指补齐 Agent 本该看见的现场（而不是放宽权限）：宿主可提供可信 quote、recent messages 和 identity，内核按 conversation/actor/时间窗验证后生成 `EnrichedInvocation`；缺失、越界和截断必须显式记录。
+
+同一 eventId 的 perception input hash 是 durable 路由的一部分，重放时不能变化。Run 中的 `response-gate.json` 与 `enriched-invocation.json` 都进入 event-index 权威快照，Action Gate 产生副作用前复验。identity 的姓名、部门、职务只用于语境，权限仍取 Invocation/Definition 的可信 ID。
+
+## 6. 语义内容与控制状态必须分开
+
+| 可放 Markdown / 钉钉文档 | 必须留在宿主 state store |
+|---|---|
+| 身份、长期记忆、知识、Skill 候选、业务 task checkpoint | EventIndex、Wait、锁、generation、幂等键、Action intent/receipt |
+
+**Why：Markdown 没有可靠 CAS。** 请求超时也不能证明写失败，因此它不能承担并发控制。这是本仓库文档中该规则的唯一出处；违反它的表现形式包括把钉钉文档当锁、当幂等存储或当 Receipt。
+
+公开 Storage Provider：
+
+```text
+local-dir:<path>              直接挂载已有目录，不复制
+local-md:<path>               Workspace manifest 的单文件挂载
+dingtalk-doc:<node-or-url>    DWS 拉取在线文档的只读快照
+```
+
+远端文档先用 `doc info` probe，只有 `ALIDOC/adoc` 才用 `doc read` 拉为隐藏只读快照。`bootstrap` 用 Storage canonical identity 派生内部 `scopeId`；`contextId` 只保留为 Prepared Run 的兼容字段。
+
+## 7. dingtalk-agent 分成哪几部分（模型 C）
+
+这是一个**划分**而不是叙事：`src/` 的每个文件各归一处，没有重叠也没有遗漏。行数为近似值，用于表达重心分布。
+
+| 部分 | 解决什么问题 | `src/` 模块 | 主要 CLI | 关联 Skill | ≈行数 |
+|---|---|---|---|---|---|
+| **1 行为内核** | 把一个外部事件变成"能不能回应、回应给谁、这次允许做什么"的确定性判断，并保证同一事件不被处理两次 | `events` `invocation` `perception` `response-gate` `sessions` `waits` `actions` `fields` `config` `lease` `driver` `workspace` `skills` `types` | `prepare` `run` `dispatch` `act` `listen` | — | 4.0k |
+| **2 装配与审计** | 让一个仓库、文件夹或钉钉文档变成可 hash、可继承的 Agent，并证明 Skill 真被加载而不只是文件存在 | `agent-definition` `agent-bindings` `bootstrap` `agent-audit` `agent-enhance` `instruction-path` | `bootstrap` `agent enhance` `agent audit` `info` | `dta-agent-compose` | 3.4k |
+| **3 交付链** | 把本地通过的版本，在不改身份和权限的前提下受控放上托管平台，每一步都能独立回读 | `development-workspace` `opencode-*` `multica-*` `promotion` `agent-platform` | `agent-platform` `workspace *` `deploy` `promote` `observe` | multica 平台包 ×3 | 6.4k |
+| **4 评测与证据** | 在花钱、外发和上线之前，用最低成本的层级证明它真会做事；失败沉淀成可复跑场景而不是一次口头修正 | `lab` `robot-evals` `opencode-evals` `remote-state-evals` `remote-semantic-state-*` `personal-event-evals` `storage-evals` `eval-evidence` | `lab *` `workspace eval` | `dta-agent-eval` | 6.2k |
+| **5 状态与记忆** | 让 Run 崩了、沙箱没了、进程换了之后，事情还能接着做；同时不让 Markdown 承担它承担不了的并发控制 | `memory/*` | `task show/checkpoint` `memory operational` `memory candidate` | — | 2.6k |
+| **6 机器与分发** | 一台新机器一条命令拿到 CLI、PATH、DWS 检查和 core Skill 套装，升级不产生第二份副本；并探测本机有哪些 Coding Agent Host 以及 Skill 对它们是否可见 | `setup` `doctor` `host-detect` `upgrade` `init` `skill-manager` `version` `package-root` | `setup` `doctor` `upgrade` `skill *` `init` | — | 1.4k |
+| **平台适配** | 全仓库唯一 spawn `dws` 的地方 | `dws` | — | — | 0.5k |
+
+重心分布本身是个结论：交付链与评测各占约四分之一，合计超过一半。这个项目的难点从来不是"让模型说话"，而是**证明它真的装好了、真的做对了、真的上线了**。
+
+对照 §3 的五个权威可以看出这六部分落在分工线的哪一侧：第 1、2、5 部分实现「本体、行为、状态与效果证据」那一行，是本仓库拥有的；**第 3 部分是通往「运行位置」那一行的连接面**——每接一个平台就多一个平台 Skill 包与一条注册表记录，行为内核不变；第 4 部分负责证明前三者在任意一个平台上都同样成立。第 6 部分服务开发者的机器本身，不在分工线上。
+
+两处接缝值得诚实标注，不糊弄过去：
+
+- `init.ts` 按模块归第 6 部分，但 CLI `init` 是第 1 部分的可选前置——机器安装与 Workspace 初始化是两件事。
+- 模型 A 的"公共行为"是**交付物**，不是本仓库的一个部分。它以 Skill 形式随包分发，由第 6 部分安装、第 2 部分校验加载、第 4 部分回归。这正是过去两张"四层表"打架的根因：一个在数交付物，一个在数代码分工。
+
+各部分的模块依赖由 TypeScript import 关系直接表达，不在此维护一张会漂移的手绘边图。
+
+## 8. 开发生命周期：从定义到观测
+
+这一节是「本项目做什么」的权威清单。**每一段都同时写明做什么与不做什么**——边界说不清，价值也就说不清。
+
+### ① 本体与员工技能
+
+**做**：把「一个钉钉数字员工开口之前必须想清楚的事」沉淀成可版本化、可 hash、可机器验证继承的共享行为合同——响应资格、九类意图分级、外部动作的七字段授权、按五因素（可逆性/影响对象/数据归属/批量规模/权限范围）而非动作名的风险分级、证据阶梯与完成闸门、六类记忆与五种遗忘范围。另给本体四段骨架、岗位 Skill 五段骨架和两个已填好语义的完整样例。继承有三类机器证据：全树 hash 一致、Host 配置恰好一条强制加载、隔离副本里的随机 canary 精确回显。
+
+**不做**：不提供统一的大 System Prompt，也没有 prompt 版本管理 / A-B / 变量注入这类设施；不写岗位方法、产品字段与 API 参数；不判断填进去的岗位内容对不对（那是 ⑤）。
+
+### ② 身份获取与事件感知
+
+**做**：把形状各异的原始事件（`data` 是 JSON 字符串、`payload.body` 嵌套、命名风格混用）归一成稳定的事件合同；缺 conversation/message/sender 直接拒收而不是让 Agent 猜收件人；把回复目标与执行身份冻结成正文改不动的权威快照；按 Field 一次性绑定权限、行为包、DWS 身份与消息出口（一个 Field 只允许一个出口 owner，配错启动即失败）；生成任何内容之前判定响应资格；用三个受约束的 Enricher（引用还原 / 同人连发合并 / 身份可读化）补齐现场，每项带来源、时间、截断与置信标记；按 eventId 抢 durable lease 保证同一事件只产生一个 Run，崩溃窗口先落 durable inbox 再物化，重放与漂移一律拒绝复用。
+
+**不做**：不签发身份、不划定场域（钉钉侧的权限）；**不拥有事件订阅与触发器**——Webhook、机器人回调、定时器、autopilot 都不属于本项目，`listen` 只是本地联调 Adapter。
+
+### ③ 托管平台部署
+
+**做**：把手工搬运变成受控发布链——稳定 `planId` 冻结本体与整棵 Skill 树的 hash、原子动作清单与读写预算；apply 前重新回读身份/workspace/runtime 链，与冻结计划不一致就在任何写入之前失败；写后独立回读远端对象与 assignment，再发一个带随机 marker 的加载烟测，验证每个 Skill 真被 Host 原生加载；同源重放是零远端写的 noop；失败尽力回滚，超时进 reconciling 要求只读收敛而不是盲重试；`promote` 只接受与策略指定 suite/case/surface 精确匹配的证据 hash；`retire` 只归档那一个 Agent，保留 Skill、Issue 与产物。
+
+**不做**：不创建任何事件入口（机器人、Webhook、定时器、autopilot）；不创建远端 workspace/runtime，不做平台账号供给；不持有或代替用户登录平台凭据；不允许直接晋级到 prod。
+
+### ④ 驱动它在钉钉里干活
+
+**做**：把外发收窄成四个互斥原语（`ack`/`reply`/`ask`/`silence`），模型造不出第五种副作用；ActionRequest 里不允许出现收件人、会话与身份，写错目标在结构上不可能；副作用**前**拦掉越权、超预算、目标漂移、状态非法等情况，副作用**后**强制平台回读把「命令返回成功」与「消息真的在钉钉里」分开记录；结果不确定时进入 reconcile 而**禁止盲重发**；跨 Run、跨沙箱靠宿主的 Wait 与 Session 续做，任务进度用 revision CAS 防覆盖；「完成」必须引用宿主签发、可重新核验的证据。
+
+**不做**：不运行模型、不自带调度器、没有工作流引擎；进 Action Gate 的 typed 副作用**只有回复与表情两种**，其余钉钉动作继续直接走 DWS（判据是 §4 的六条），不受 Run 预算与 generation 约束。
+
+> ⚠️ **一处「设计完成度 > 交付完成度」的断点**：完成证据的**核验**侧已完整实现并被合同锁定，但**签发**侧（`issueCompletionEvidence`）目前只有库 API，没有接到公开 CLI——`dta task` 只有 `show` 与 `checkpoint`。只用已发布 CLI 的开发者**无法把一件事推进到 `completed`**，需要宿主以库形式集成。
+
+### ⑤ 评测设计
+
+**做**：给出「选最低够用的环境层级」的判断表与 L0–L4 分层；规定一次结论必须同时采集哪几个证据面，且回复正文永远不能自证完成；把硬门禁的判定顺序固定下来，防止安全失败被质量分平均掉；提供四个默认零副作用的 runner（真实外发需四道 gate 同时打开）；给出「真实事故 → 可复跑场景」的沉淀路径与「这条该修进 CLI 还是修进 Skill」的判别原则；仓库自身的 62 个合同即范例，**每条都成对写明证明什么、不证明什么**。
+
+**不做**：不做自然度与主观质量的自动判定，不允许用模型主观高分覆盖已实现的安全失败；不自动清理测试产物（写入授权不等于删除授权）；不支持 prod 晋级。
+
+### ⑥ 观测与计量
+
+**做**：`dta observe` 提供一条受控通道——把线上发现的一条**人工撰写**的脱敏观察，精确绑定到「线上跑的到底是哪一版」（必须与已 promoted Receipt 的 `observedHash` 逐字节相同），落成 gitignored 的 `proposed` 候选。它保证线上反馈**永远不会自动变成 Agent 的新行为**，且 CLI 会直接拒收手机号、邮箱、token 等敏感串。
+
+**⚠️ 这是当前最薄的一段，必须说清楚**：`dta observe` **不采集任何线上数据**，它不是线上观测。执行轨迹的读取能力属于托管平台（随平台包分发一个薄 HTTP wrapper，换平台即失效）。**用量计量——交互量、任务量、线上 token、成本、按人/按群的使用分布——本项目一项都没有实现。** 最接近的是托管平台按 issue 聚合的 token 直通调用，以及本地评测执行的单次 token/花费（无聚合）。反馈采集也不是自动的，靠人手写 JSON；候选从 `proposed` 进入 Eval suite 的评审流程尚未实现。
+
+**不做**：`observe` 产物不进 Git（团队间无法共享）；不把线上数据写回 Prompt/Skill/suite；在线 Run 不得自动扩大身份、权限或启用 Skill。
+
+> 计量这层 dta 不造，但**该怎么自建**有可抄的范式——运行记录账本（每 Run 一行）+ 费率折算 + 体检元节律 + L0–L4 达成度判据，见 [AGENT-IN-PRODUCTION.md](AGENT-IN-PRODUCTION.md)「观测这一层，dta 不替你造——但有可抄的范式」。
+
+---
+
+Agent Project 与 Development Workspace 的基数关系：
+
+```text
+1 Agent Project ── 0..N Development Workspaces
+1 Workspace     ── 1 Host Provider
+1 Workspace     ── N Storage Bindings
+1 Workspace     ── 0..N Sessions ── 0..N Runs
+```
+
+`dingtalk-agent.json` 是进入 Git 的期望状态；`.dingtalk-agent/state/workspaces/<name>.json` 是 Provider 回读事实。Secret、Token、cookie 和凭据不得进入任何一层，环境字段只保留 `env:VAR` 来源。
+
+**Host Provider 与 Storage Provider 正交**：OpenCode/Multica 决定"在哪里运行"，`local-md`/`local-dir`/`dingtalk-doc` 决定"语义内容放在哪里"。因此缺少某个平台 CLI 只会让对应 Workspace 变 `partial`，不会污染其它 Workspace；state 中 Provider 与声明不一致、desired hash 漂移或非 ready 状态则一律 fail closed。
+
+所有远端写入都需要明确目标、当前 `planId` 和显式确认；所有计划默认零写入。设计推演见 [Provider-bound Development Workspace](roadmap/provider-bound-development-workspace.md)。
+
+## 9. Agent 如何演进：只产生候选，不热改
+
+在线 Run 可以提出候选，但**不能热修改身份、权限、已启用 Skill 或当前 Run 的策略**。这条规则在本仓库有两个同形状的实现，它们共享同一套治理结构：
+
+| 通道 | 谁提出 | 落到哪 | 谁决定 |
+|---|---|---|---|
+| `memory candidate` | 在线 Run 从一次纠正中提取 | 绑定 scope/Run/Event/Definition hash 的候选 | 离线 reviewer，用 revision CAS approve/reject |
+| `dta observe` | 已 promote 的部署反馈 | gitignored、`proposed`、不可直接发布的 eval candidate | 人工评审后才可能进入 Eval suite |
+
+两者都：只写候选、不改本体；都要求 provenance 与 scope；都用 revision CAS 或 expected hash 防止评审期间目标漂移；发布后都只影响**后续新 Session**，不改变当前 Run。
+
+本地/Git 发布使用 target expected hash、durable lease、原子替换和回读，CLI 不自动 commit/push。钉钉文档只追加唯一 marker 并全文回读——因为 Markdown 没有可靠 CAS（§6），其回执必须显式声明 `best-effort-read-check-append` 的并发语义。
+
+W4 只在 W3 inspection 完整且未漂移时开放 `dta deploy`。plan 冻结 profile、Workspace、Runtime、Agent、Definition、完整 Skill tree hash 与 forward/rollback 最大写预算；apply 在写前重新执行 W3 scope 链回读，并先持久化 operation。Agent instructions 必须等于人类可读 Definition 原文，部署 hash 与 Skill 清单只进控制面；Basic 与 Role Skill 完整树、runtime/private mode 和唯一 assignment 都要写后独立回读。最后通过专用 Issue 直接取得每个 Skill 的 tool trace 与精确 JSON response，二者同时通过才签发本地 Receipt 并进入 `ready`：
+
+```text
+trusted W3 inspection + local Definition/Skill tree
+  → stable dry-run planId (zero Provider calls)
+  → explicit planId + yes
+  → scope reinspection → operation persisted
+  → Skill/Agent/assignment reconcile → independent readback
+  → Basic → Role load smoke
+  → Receipt + workspace-state@1 ready
+```
+
+## 10. 当前明确不做
+
+- 不把 `listen` 或任何触发器做成 Agent 主进程；
+- 不自己做 Managed Agent Platform，也不签发组织身份或场域授权；
+- 不把尚未开放的平台宣称为已支持、已部署或已 Live 验证；
+- 不自动 init 任意代码仓库；
+- 不把整个 DWS 复制成另一套 CLI；
+- 不把钉钉文档当锁或事务数据库；
+- 不序列化语言运行时栈；
+- 不允许在线 Run 自动扩大身份、权限或启用 Skill；
+- 不把本项目变成巨型 Prompt。
+
+## 11. 延伸阅读
+
+| 想做什么 | 去哪 |
+|---|---|
+| **接手一个已经在跑的 Agent**（运行视角：一天怎么转、坏起来什么样、去哪看） | [Agent in Production](AGENT-IN-PRODUCTION.md) |
+| 安装、升级与排障 | [Installation](INSTALLATION.md) |
+| 评测方法、证据分层与晋级门禁 | [Self-test](SELF-TEST.md) |
+| 创建或审计一个 Agent | [Compose Skill](../skills/core/dta-agent-compose/SKILL.md) |
+| 测试或调试已交付的 Agent | [Eval Skill](../skills/core/dta-agent-eval/SKILL.md) |
+| 公共行为协议本身 | [Basic Behavior Skill](../skills/core/dta-basic-behavior/SKILL.md) |
+| DWS 与钉钉 API 的实战缺陷 | [DWS Field Notes](DWS-FIELD-NOTES.md) |
+| 借鉴了哪些开源项目、各自取了什么 | [Prior Art](PRIOR-ART.md) |
+| 真实事故该由平台哪一层兜（护栏清单） | [Platform Guardrails](PLATFORM-GUARDRAILS.md) |
+| 尚未完成的工作 | [roadmap](roadmap/) |
+
+在本仓库工作的 Coding Agent 请先读 [AGENTS.md](../AGENTS.md)，验证命令以那里为准。

package/docs/INSTALLATION.md

@@ -69,7 +69,7 @@ npm 全局命令会被链接到 `{prefix}/bin`，但不同 Node 版本管理器
 npm install → dta setup
   → 安装当前版本到 ~/.local/bin
   → 检查并幂等补充 ~/.zshrc / ~/.bashrc PATH
-  → 安装 canonical 内置 Skill（Basic Behavior + Compose）
+  → 安装 canonical 内置 Skill（Basic Behavior、Compose、Eval）
   → 暴露给 Claude Code，验证 Codex/OpenCode 共享发现
   → 检查 DWS 版本和认证
   → 给出唯一下一条命令
@@ -124,7 +124,7 @@ dws auth login
 
 ```bash
 npx --yes --registry=https://registry.npmjs.org --package=skills@latest -- skills add \
-  <package>/skills/core/dingtalk-basic-behavior \
+  <package>/skills/core/dta-basic-behavior \
   --global --yes --agent claude-code codex opencode
 ```
 
@@ -132,9 +132,9 @@ npx --yes --registry=https://registry.npmjs.org --package=skills@latest -- skill
 
 | 客户端 | 发现方式 | 路径 |
 |---|---|---|
-| Claude Code | 相对 symlink | `~/.claude/skills/dingtalk-basic-behavior` |
-| Codex | shared Agent Skills | `~/.agents/skills/dingtalk-basic-behavior` |
-| OpenCode | shared Agent Skills | `~/.agents/skills/dingtalk-basic-behavior` |
+| Claude Code | 相对 symlink | `~/.claude/skills/dta-basic-behavior` |
+| Codex | shared Agent Skills | `~/.agents/skills/dta-basic-behavior` |
+| OpenCode | shared Agent Skills | `~/.agents/skills/dta-basic-behavior` |
 
 检查、重装当前 npm 包内版本和卸载：
 
@@ -155,11 +155,11 @@ OpenCode 官方同时支持 `.opencode/skills`、`.claude/skills` 和 `.agents/s
 ```bash
 # 有仓库权限
 npx skills add D1-2004/dingtalk-agent \
-  --skill dingtalk-basic-behavior --global --yes \
+  --skill dta-basic-behavior --global --yes \
   --agent claude-code --agent codex --agent opencode
 
 # 本地 checkout
-npx skills add ./skills/core/dingtalk-basic-behavior \
+npx skills add ./skills/core/dta-basic-behavior \
   --global --yes --agent claude-code --agent codex --agent opencode
 ```
 
@@ -194,7 +194,7 @@ dta prepare --event-file event.json --json
 
 ## 开发者 Golden Path
 
-安装完成后，一个岗位 Agent 只需要三组输入：本地 `AGENTS.md`、本地 `skills/<role>/SKILL.md`，以及从 compose Skill 模板创建的 `agent.bindings.json`。本地模板把 memory/knowledge 指向 Markdown；远端模板只把这两个语义槽路由到专用钉钉文档，产物与控制状态仍留在 Agent 根目录。
+安装完成后，一个新岗位 Agent 只需要三组输入：`agent/AGENTS.md`、`agent/skills/<name>/` 单一发布源，以及从 compose Skill 模板创建的 `agent.bindings.json`。根 `AGENTS.md` 只约束仓库开发。Host exposure 由 dta 在隔离工作区临时物化，不进入 Git；已有仓库可在 manifest 显式声明其它路径。
 
 ```bash
 # 在 Agent 根目录

package/docs/PLATFORM-GUARDRAILS.md

@@ -0,0 +1,188 @@
+# dta 平台护栏清单：哪些坑必须由工具层兜住
+
+> 2026-07-24 一夜盯一个真实生产 Agent（FDE 教练）跑，踩出六个坑。本文回答一个问题：
+> **每个坑该由谁兜——原语 / CLI 闸门 / Skill 纪律 / 文档？**
+>
+> 一条贯穿全文的判据：**凡是「dta 文档已经写过、业务方仍然逐个踩」的坑，就是该从文档下沉到 CLI 的信号。**
+>
+> ⚠️ **诚实说清本文的定位（经两轮 review 收窄）**：本文是**事故复盘 + 该由哪层兜的分析**，
+> 不是"已封死"的宣告。本次 CR 真正落到**代码**的只有【节律静态检查（同刻并发按真实 occurrence 判、
+> 完成判据存在性、计量标注）】；【AI 表格静默截断】和【完成判据分叉】这两个最核心的坑，
+> 本次只做了**文档 + Skill 纪律 + 存在性检查**，**没有**做到类型层/注册表层的硬封印——那需要
+> `completeness: proven\|unproven` 原语、`predicateRef` 注册表、no-op Receipt 合同，均已列为 follow-up issue。
+> 换句话说：**别把本文当"每个 Agent 都自动免疫了"，它是"我们知道坑在哪、部分下沉了、其余明确记账"。**
+>
+> 证据等级：**【实测】**本机只读复跑、**【读码】**对到 file:line、**【下界】**单读表格数可能偏小。
+
+---
+
+## 0. dta 今天的护栏落在哪三层
+
+`README.md` / `AGENTS.md` 的口径是 **Skill 劝 · CLI 拦 · DWS 做**。【读码】实际分布：
+
+| 层 | 位置 | 今天真拦住了什么 |
+|---|---|---|
+| Skill 劝 | `skills/core/dta-basic-behavior/SKILL.md` | 响应资格、意图、`nothing-to-save` 合法性、没 Receipt 不用完成措辞 |
+| CLI 拦 | `src/dws.ts` 六条纪律、`records()` fail-closed、`src/actions.ts` 发消息后独立回读、`src/memory/operational.ts` 按 recordId 回读 + 命中多行拒绝 | 目标冻结、四原语、写后回读、幂等 |
+| DWS 做 | `src/dws.ts`（全仓唯一 spawn `dws` 处） | — |
+| **文档层**（既不劝也不拦） | `DWS-FIELD-NOTES.md`、`AGENT-IN-PRODUCTION.md` | **什么都拦不住** |
+
+**最硬的一个判据**：`AGENT-IN-PRODUCTION.md` 早就写了"写后回读读的是同一个错误对象"、"同一个语义只留一个谓词"、"改 mode 就是在改计量口径"——**文档劝过了，业务方还是踩了**。这三条都该下沉。
+
+---
+
+## 1. 坑一 · AI 表格静默截断 → **必须是原语，不能只写进 Skill**
+
+**【实测】** 同一 `--all --page-limit 0` 全表连读 6 次得 `400/300/1300/500/1800/700`，
+pages `5/4/14/6/19/8`，**6 次全 `hasMore=false`、`partial` 键根本不存在**。单次最低 300 是并集下界的 17%。
+成功信封的全部键只有 `records/hasMore/pages`——**没有 `totalCount`，服务端不提供任何完整性凭据**。
+
+**【读码】dta 今天的状态**：
+
+- `src/dws.ts records()` 已 fail-closed 检查 `hasMore/partial`——**和 FDE 引擎 `query()` 同一道闸门、同一个漏洞**。平台谎报 `hasMore:false`，两道闸门同时被绕过。
+- **更糟**：`src/dws.ts queryAiTableRecords()`（dta 自己的 Operational Memory 读路径）**不带 `--all`、不带 `--page-limit 0`，只 `--limit 100`**——比 FDE 引擎还弱一档。
+- `DWS-FIELD-NOTES.md` 现有对策「`--all` 必配 `--page-limit 0`」**今晚实测证伪**：加了照样截断。
+
+**为什么不能留给业务方**（不是偏好）：
+1. 这是**介质属性**不是岗位知识。FDE 已严格按文档写对参数，仍被骗 → 这题在 Skill/文档层**无解**。
+2. 判据需要**跨调用状态**（多读、计数账本、水位），Skill 是无状态语义层。`AGENTS.md` 自己就写「幂等、回读、硬拒绝 → CLI/Gate，不得只写在 Prompt」。
+3. `dta-people-group-memory/references/storage-port.md` 自立原则「模型层不知道『截断』这个词」——既然模型层不该知道，就必须有人替它知道。
+
+**该做什么**：
+
+| 落层 | 改动 |
+|---|---|
+| **原语** `src/dws.ts` | `records()` 不再把 `hasMore=false` 当完整性证据。返回 `{records, completeness: 'proven'\|'unproven'}`，全量扫一律 `unproven`，调用方**编译期**绕不过去 |
+| **原语** `src/dws.ts` | 把混为一谈的读拆成三个、在类型上分开可靠性：`getByRecordIds()`（≤100 定点，【实测】7/8 正确且失败 fail-loud）／`queryByKey(filters)`（服务端筛，**仍 unproven**）／`scanAll()`（**标记不可信**） |
+| **原语** `src/memory/` | **count ledger**：写侧每次 `+1` 到 meta 表，读侧全量枚举时两数相比——**唯一**能把"读全了"变可证明的机制（服务端无 `totalCount` oracle）。诚实边界：只覆盖 dta 自己写的行，给"不少于"；对单写者表等号成立 |
+| **CLI 闸门** | 连读 K 次取 max **只提高发现截断的概率、不能证明完整**（【实测】并集到第 5 次才碰到 1800，仍是下界）。所以 K-读只作 `unproven→suspected-truncated` 降级信号，**不许当完整性证明**——写进代码注释，否则会被误当对策 |
+| **文档** | 更正 `DWS-FIELD-NOTES.md`：`--all --page-limit 0` **不足以**防截断，附今晚数据 |
+| **回归** | `evals/` 加 core 合同：fake dws stub 返回"页对齐前缀 + `hasMore:false`"，断言 CLI **拒绝**当完整 |
+
+**⚠️ 已推翻的一个说法**（复核纠正）：曾以为"`--all` 的空返回有一种 fail-loud 安全形态"。**错**——
+`--all` 路径上的空返回是 `{"hasMore":false,"pages":1,"records":null}`，`records` 键在、值为 `null`，
+两道闸门（`dws.ts` 的 `'records' in x` 和 `records || []`）都**静默**放过。`--all` 路径上**两种 0 都不安全**。
+
+---
+
+## 2. 坑二 · 写后回读读到同一个错对象 → **Action Gate 该管，今天管不到**
+
+**背景事故**：FDE 的 `write-ai` 盲写 `rows[0]`、回读也取 `rows[0]` → 永远自洽 → 写错行永远发现不了。
+根因是「业务主键不唯一 + 定位靠读」，回读只是发现手段。
+
+**【读码】dta 今天**：这条合同**已存在**——`src/memory/operational.ts` 按 recordId 独立回读、key 命中多行直接拒绝、
+创建后没拿到 recordId 就按 key 回查。`ARCHITECTURE.md` 还拿它当"为什么这必须是 CLI 命令"的范例。
+**但覆盖面几乎为零**：只作用于 `dta memory operational upsert` 一条命令；进 Action Gate 的 typed 副作用
+**只有回复与表情两种**，AI 表格写入根本不进 Gate。FDE 的 write-ai 是业务方自己写的，所以这条事故 dta 一点忙没帮上。
+
+**该落哪**：
+- **CLI 闸门（新增窄命令）**：按 `ARCHITECTURE.md` 的六条判据，业务表写入命中第 3（幂等且不能盲重试）+ 第 4（写后必须独立回读）→ **符合进 CLI 的标准**。但不做通用 CRUD（`ARCHITECTURE.md` 明禁复制 DWS 命令面）。折中：
+  `dta aitable upsert --key-field <f> --key <v> --required-nonempty <f,…>`，只做四件——按业务键定位 → 键唯一性断言 → 写 → 按 recordId 回读，其余回 DWS。
+- **为什么不留给业务方**：这个错误 **100% 静默且自洽**（写 rows[0]、回读也取 rows[0] → 永远自证成功），数据上看不出来，只有 backlog 三十小时不降才反推得到。"结构性不可观测"的错误定义上就不该由每个业务方各自发现一次。
+
+**⚠️ 一个未复现的推测**（复核纠正）：曾推测 dta 自己的 `operational.ts` 也有同族"截断到 0 → 判不存在 → create 重复"的洞。
+**在真实代码路径上未复现**：`operational.ts` 走 `--limit 100`（非 `--all`），【实测】连读 30 次里 2 次空返回都是
+带 `error` 的信封 → 进 `dws.ts` 的 `error.code` 判断 → **fail-loud（die）**，不是静默造重复。
+所以 dta 内核这条路是安全的——但**新增的 `dta aitable upsert` 若走 `--all` 定位就会引入这个洞**，设计时必须用 `getByRecordIds`/`queryByKey` 而非 `scanAll`。
+
+---
+
+## 3. 坑三 · 两个完成判据分叉 → **注册表 + 唯一入口，不是静态检查**
+
+**背景事故**：FDE 的 `duty_runlog()` 完成判据只看答案原文、`_settled()` 还要问题原话，两谓词分叉 →
+心跳先问 done、done 就不跑补录 → 补救路径 30 小时没被触发、没有任何一层报警。
+
+**【读码】现状**：`AGENT-IN-PRODUCTION.md` 已把结论写成「同一个语义只留一个谓词，两个调用方共用」；
+`AGENTS.md` 有「每条不变量只选一个 owner」的表，但管的是**内容写在哪个文件**、不是**代码谓词的唯一性**。**没有机器检查。**
+
+**能做**：
+- **装配层**：`dta-agent-compose` 的节律声明里，每条 schedule 带 `doneWhen: predicate:<id>`。
+- **CLI 闸门**：`dta schedule plan` 校验每个 predicate 在 Agent 侧可执行——`src/schedule-plan.ts` 已有
+  "平台不提供该能力就 supported:false 记缺口、绝不静默降级"的 fail-closed 骨架，**直接复用到 predicate**。
+- **回归**：同一 duty 的两个调用点必须解析到同一 predicate id，不同就红。
+
+**不能做（诚实标注）**：跨语言（FDE 引擎是 Python）**没法静态证明两个函数语义相同**。约束形式只能是「注册 + 唯一入口 + 谁绕过谁没 receipt」，不是分析。
+
+---
+
+## 4. 坑四 · 解析失败被折叠成"内容为空" → **解析失败必须留痕，拦在写入前**
+
+**背景事故**：平台改中继模板标题 → FDE 的 `_RE_ASKED` 100% 不命中 → 抠不到问题原话 → **静默写空**。
+通用形状 = **解析失败与"本来就空"不可区分**，和 `DWS-FIELD-NOTES.md` 的「读错层级 → undefined → 当成空」同族。
+
+**该落哪**：
+- **原语/Skill 纪律**：凡"从外部信封解析出字段再写入"的路径，解析失败必须产出一个**可区分于空**的标记（如 `parse-miss`），
+  而不是落一个空字符串。写入前若关键字段是 `parse-miss` → 记欠账、不写、可报警。
+- **对应 `dta-people-group-memory` 的第 3 条不变式「读失败 ≠ 不存在」**——但那条现在只针对**读**，
+  要扩到**解析**：解析失败 ≠ 字段为空。
+
+---
+
+## 5. 坑五 · ephemeral 不产 issue → 不可计量 → **观测缺口，ARCHITECTURE §8 自己承认**
+
+**【读码】** 常驻节律多是 `ephemeral`（`run_only`），平台不为它建 issue → `/api/tasks/{id}/usage` 拿不到 →
+心跳的真实 Token 拿不到。`ARCHITECTURE.md §8` 自己说观测是"最薄的一段"。
+FDE 侧实测：可见 IM 成本只是冰山一角，心跳那半平台不记账。
+
+**该落哪**：
+- **文档已对（`AGENT-IN-PRODUCTION.md` §6 写了盲区），但 dta 无计量能力**。这条不该硬造——
+  但 dta 至少该在 `dta schedule plan` 输出里**标注每条节律的 `mode` 与可计量性**，让 operator 在排期时就知道哪块看不见，
+  而不是等业务方各自发现。「改 `mode` 就是改计量口径」这句该从文档变成 `schedule plan` 的一条显式告警。
+
+---
+
+## 6. 坑六 · "无操作"不可观测 → **`nothing-to-save` 也要留痕**
+
+**背景事故**：FDE 的单聊沉淀判 `nothing-to-save` 是合法结果，但**判了 nothing-to-save 和压根没跑，在外部完全不可区分**——
+沉淀这步没跑不留痕、跑了判空也不留痕。结果是"这个能力到底在不在工作"永远回答不了。
+
+**该落哪**：
+- **Skill 纪律（`dta-basic-behavior` + `dta-people-group-memory`）**：把「无操作也是一次可观测的操作」立成通用合同——
+  判 `nothing-to-save` / `skip` / `no-op` 时**留一行结构化痕迹**（带原因），而不是静默返回。
+- 这条和 `dta-basic-behavior` 的"没 Receipt 不用完成措辞"是一体两面：完成要有证据，**不完成也要有证据**。
+
+---
+
+## 7. 对 dta-people-group-memory 四条不变式的复核
+
+这个 Skill（v0.3.0）刚进默认套装，四条不变式在**静默截断**下逐条评估：
+
+| 不变式 | 扛得住截断吗 | 说明 |
+|---|---|---|
+| ① 原始层只增不删，派生层可重建 | ✅ | 与截断无关 |
+| ② 写后必回读，success 不算数 | ⚠️ **不够** | 回读若用 `scanAll` 会被截断骗；必须限定为**按 recordId 回读**（坑二）。「回读」要在契约里写死是哪种读 |
+| ③ **读失败 ≠ 不存在** | 🔴 **最需要加强** | 现在只针对**报错的读**。而截断读**不报错**——它成功返回一个偏小的前缀。这条不变式的前提"读失败会被识别"在 `--all` 上**不成立**。必须补一句：**"成功但可能不完整"也算读失败**，全量枚举一律 `unproven`，绝不据此判"不存在"或新建重复 |
+| ④ 先写事实、后推水位 | ✅ | 与截断无关，且正确 |
+
+**核心修订**：第 ③ 条要从「读失败 ≠ 不存在」升级为「**读不完整 ≠ 不存在**，而全量枚举永远无法自证完整」。
+这正是坑一 G1 的原语要兜的——把"完整性未证明"变成一个类型层的显式状态，Skill 的第 ③ 条才有东西可依靠。
+
+---
+
+## 附：落地状态（2026-07-24 本次 CR，两轮 review 后收窄）
+
+分三档如实标：**代码闸门**（机器强制）、**文档/Skill**（劝、不强制）、**follow-up**（真封印，本次没做）。
+
+**已落代码闸门（机器强制、CI 守）**
+| 坑 | 落点 | 状态 |
+|---|---|---|
+| 坑三 判据缺失 | `schedule-plan.ts` 校验每条节律有 `completion`，缺失 `schedule show/plan` **exit 2**（json+人类都设，不 fail-open） | ✅ 代码 |
+| 坑五 计量盲区 | `schedule-plan.ts` 每条节律标 `metered`（ephemeral 不记账显式提示） | ✅ 代码 |
+| 撞车误报/漏报 | `firesCollide` 改**按真实 occurrence 判**（robfig dom/dow OR、名字字面量、闰年枚举）；判不准的（跨时区/扩展语法）进 `unverifiedPairs`，**和确认撞车一样 exit 2 挡住**——`0 9 * * *`@Asia/Shanghai 与 `0 1 * * *`@UTC 是同一时刻，证不出不撞就不许部署 | ✅ 代码 + 回归 |
+
+**已落文档/Skill 纪律（劝，不强制——这几条本次【没有】做成硬封印）**
+| 坑 | 落点 | ⚠️ 局限 |
+|---|---|---|
+| 坑一 截断 | `DWS-FIELD-NOTES` 重写 + `dws.ts` 注释 + people-memory 不变式③「读不完整≠不存在」 | `records()` 仍会接受 `hasMore:false` 的部分前缀、把 `records:null` 折成 `[]`——**没有 completeness 类型封印**（见 follow-up） |
+| 坑三 判据分叉 | `completion` 存在性检查 | **只证明"写了一句话"**，不保证运行时两个谓词引用同一个——原事故那种"各有一套判据"仍可能复发（见 follow-up） |
+| 坑四 解析失败折叠成空 | `DWS-FIELD-NOTES`「解析失败≠空」+ `parse-miss` | 是文案，没有强制的 typed action |
+| 坑六 无操作不可观测 | `dta-basic-behavior`：`nothing-to-save` 也要留痕 | 是文案，**没有** host 签发的 no-op Receipt 合同（见 follow-up） |
+| 不变式② | people-memory：写后按 recordId 回读 | ✅ 纪律清晰 |
+
+**明确 follow-up（真封印，本次没做，各开 issue）**
+1. `completeness: proven\|unproven` 读原语 + 页对齐前缀 fixture——把"未证明完整"变类型层显式状态。
+2. `predicateRef` 注册表 + 运行时引用校验——让"完成判据分叉"在编译期/运行期查得出来。
+3. host 签发的 no-op / nothing-to-save Receipt 合同——让"跑过判空"可与"没跑"区分。
+4. cron 同刻判定复用 provider（robfig）occurrence 预览，替掉本地模拟。
+
+**明确没做（避免一味增加）**：不新增 `dta aitable upsert` CLI 命令面（`ARCHITECTURE.md` 明禁复制 DWS 命令面，且无现有调用方）；`records:null` 不硬判死（dws 版本相关，硬判深耦合）；计量不进 core。