@xdxer/dingtalk-agent 0.1.4-beta.18 → 0.1.4-beta.19

package/skills/core/dingtalk-agent-compose/references/host-loading-contract.md

@@ -0,0 +1,58 @@
+# Host 无关加载合同
+
+本文件定义任何 Agent Host 都必须满足的加载不变量与证据形态。它是判据，不是某个 Host 的配置手册；具体机制写在 `references/hosts/<host>.md`。Host 换了，不变量不变；证据的绑定项换。
+
+## 两个目录面
+
+```text
+skills/<role>/SKILL.md          dta Definition / Git 发布源
+<host-exposure-dir>/<name>/     该 Host 的运行时 exposure
+```
+
+`skills/` 是发布源，Host 原生目录是运行时可见面。exposure 目录名由 Host 决定，不由本合同规定；两面都存在才算装配，只写一句「请应用某 Skill」或只把 `SKILL.md` 放进目录都不是完成。exposure 目录之间不互相蕴含：一个 Host 的 exposure 通过，不代表另一个 Host 已经加载。
+
+## 四条不变量
+
+### 1. Definition 由 Host 的原生 project rule 加载，且不得重复进入 custom instructions
+
+Agent 本体走 Host 自己的项目规则通道，不由 dta 再注入一遍。等价路径（相对/绝对、大小写别名、symlink/hardlink）都要从 custom instructions 删除，避免同一份本体形成两条加载通道和两个可漂移真值。Host 若没有原生 project rule 通道，由该 Host 的 adapter 声明替代机制并说明它为什么等价；没有替代机制就不是可用 Host，不是「可以退化成注入」。
+
+受管本体当前只认项目根 `AGENTS.md`。Definition 指向其它文件时装配阻塞，由开发者先统一本体来源；不静默制造双真值。
+
+### 2. Basic Skill 的正文是每 Session 唯一的 resolved 强制指令，不是「可发现」
+
+`dingtalk-basic-behavior` 必须无条件进入每个 Session 的 resolved 指令集，且在 resolved 结果中只命中一次。目录存在、Skill 名可枚举、模型说得出 Skill 名，都不是加载证据——那是可发现，不是已加载。多个等价路径要去重成唯一规范值；glob/extglob 只有在可证明不命中受管本体与 Basic 及其 alias 时才保留，无法证明时阻塞并要求收窄。
+
+### 3. Basic exposure 必须整树物化，tree hash 与 canonical 一致
+
+物化 `SKILL.md`、`references/`、`assets/` 全树，文件清单与 tree hash 都对齐 canonical source。只对入口 `SKILL.md` 做 hash 不能证明隐私、授权、真相恢复等 reference 边界仍在——入口一致而 references 缺失是最常见的静默降级。装配时记录源路径、目标路径与 hash；源升级后重新物化并重新评测，不留两份独立维护的内容。
+
+### 4. Role Skill 可发现且已授权，但不进强制加载集
+
+岗位 Skill 暴露到该 Host 的 exposure 目录并在权限面允许，按任务触发。不默认加入全局强制指令；只有明确要求该岗位方法贯穿每个 Session 时才升级为 required，并在 Definition 中记录原因。把 Role Skill 塞进强制集会稀释 Basic 的唯一性，也让加载证据失去判别力。
+
+## 三类加载证据
+
+证据必须由模型实际产出，不能由静态检查推断。
+
+1. **Definition 零工具 canary 精确回显**：在隔离 Workspace 中给根 `AGENTS.md` 追加每 Run 随机 canary，屏蔽用户级/全局 instruction 与 config 面但保留 provider 认证，且不把 `AGENTS.md` 加入 custom instructions；Host 仍必须通过原生 rule 零工具精确回显该值。用了工具去读文件即失败——那证明的是文件可读，不是本体已加载。
+2. **Basic 入口随机 probe + anti-guess baseline**：为 Basic 入口追加独立随机 probe，Host 必须精确回显；without-skill baseline 必须精确回答 `dta-load-probe=not-loaded`，空答、垃圾文本或其它 UUID 都失败。两组 run 数、随机 challenge、resolved 指令数与目录都从明细重算，不复用声明值。缺 baseline 的单边 probe 不成立——它无法区分「加载了」和「猜对了」。
+3. **代表性风险/授权 reference 的受限读取首尾随机值**：在风险/授权代表性 reference 的首行与末行各追加随机 canary，仅允许目标文件 read、显式拒绝 external directory，必须用一次从首行开始且覆盖全文的完成态读取同时取得两个值。任何额外 read、越界 read、无路径 read 或 tail read 都失败。
+
+三类证据都通过才可能 `ready`；任一失败只能 `partial`。行为题不在 `AGENTS.md` 中复制预期答案，load gate 与行为分数分开报告——load gate 失败时，后续回答再像员工也只能算碰巧命中，不算本体与 Skill 已继承。
+
+## 证据通用，绑定项由 adapter 提供
+
+三类证据的形态与判据对所有 Host 相同。变的是绑定项：**Host 名、Host 版本、模型/provider、原始轨迹**（run 与 session export 的 stdout/stderr hash、精确 session ID、Session directory）由该 Host 的 adapter 提供并写进报告。没有绑定项的证据不可复核，等于没有证据。
+
+复用报告时从原始记录重算回答、工具轨迹与 Session directory，重新读取当前 Host 版本，签发前再次计算 live source hash，并复验 Definition、Bindings、Host config 与 Skill 未漂移——防止重放、版本漂移或长调用期间形成混合快照。普通 SHA 提供本地证据自洽性，不是抗主动伪造的宿主签名 Receipt。
+
+证据边界必须拆开：全树 hash 证明 `SKILL.md`、全部 references 与 assets 没有缺失或漂移；入口 probe 证明 Basic 无条件加载；一个高风险 representative reference canary 只证明该目标文件的受限完整 read 链路可工作。它不是全路由验证，也不声称其它每个 reference 的场景路由都已逐项通过模型探针；这些覆盖由相应 shadow eval 的 `required_reads` 与行为断言承担。
+
+## 没有 adapter 的 Host 只能 partial
+
+Host 没有 adapter，就取不到上述三类证据的绑定项，结论**只能是 `partial`**，并列出缺失的证据项与该 Host 的 adapter 状态。
+
+用户未选定 Host、或选了「暂不指定」，同样只能 `partial`。**绝不能因为「没声明 Host」就跳过加载检查拿到 `ready`**——没有 Host 就没有加载面，没有加载面就没有加载证据，这是缺证据，不是「无需检查」。把未声明当作豁免，会让所有 `ready` 结论失去含义。
+
+当前 `references/hosts/opencode.md` 是唯一有完整 adapter、可签发三类证据的 Host。其它 Host 的合同文件描述加载机制与已知事实，但在其 adapter 落地前，按本节判为 `partial`。

package/skills/core/dingtalk-agent-compose/references/hosts/claude-code.md

@@ -0,0 +1,48 @@
+# Claude Code Agent Host 加载合同
+
+四条不变量与三类证据见 [host-loading-contract.md](../host-loading-contract.md)。本文件只写 Claude Code 的机制差异与当前实现状态。
+
+**adapter 状态：未实现。** Claude Code 目前**不能**签发 Definition canary、Basic 入口 probe/anti-guess 与代表性 reference read canary 三类证据，因此选定 Claude Code 的装配结论**只能是 `partial`**。下文的机制描述是配置指引，不是「已验收」的声明。不要把本文件读成 Claude Code adapter 已经可用。
+
+## Definition：Claude Code 不原生读取 AGENTS.md
+
+这是与 OpenCode 最关键的差异。OpenCode 与 Codex 都把项目根 `AGENTS.md` 当原生 project rule；**Claude Code 不读 `AGENTS.md`**，它的原生 project rule 文件是 `CLAUDE.md`。直接把 `AGENTS.md` 放在根目录，Claude Code 的 Session 里不会有本体正文——目录看起来完全正确，本体却从未加载。
+
+两条可选接法，都保持 `AGENTS.md` 为唯一本体真值：
+
+```text
+CLAUDE.md 内含 @AGENTS.md 引用      Claude Code 解析该引用并把 AGENTS.md 正文纳入 project rule
+CLAUDE.md -> AGENTS.md（符号链接）   同一份文件，两个 Host 各按自己的约定发现
+```
+
+两条路都不得把 `AGENTS.md` 的正文复制进 `CLAUDE.md`——复制会产生第二个可漂移真值，违反不变量 1 的等价路径去重要求。同理，`AGENTS.md` 及其等价路径不得再出现在任何 custom instruction 面。
+
+受管本体仍只认项目根 `AGENTS.md`；`CLAUDE.md` 在这里是 Claude Code 的加载通道，不是本体的第二个来源。
+
+## Skill exposure：`.claude/skills`，不与 `.agents/skills` 共享
+
+```text
+.claude/skills/dingtalk-basic-behavior/    Claude Code 必需 Basic exposure
+.claude/skills/<role>/SKILL.md             Role Skill exposure
+```
+
+`.claude/skills` 是 Claude Code 独有的目录约定。`.agents/skills` 由 Codex 与 OpenCode 共享，**Claude Code 不读它**——已有 `.agents/skills` 的仓库切到 Claude Code 时必须另行物化到 `.claude/skills`，不能假设已有 exposure 可以复用。
+
+Basic exposure 按不变量 3 整树物化（`SKILL.md`、`references/`、`assets/`），tree hash 对齐 canonical source；只复制入口即视为未装配。目录名必须等于 frontmatter `name`。Role Skill 按不变量 4 暴露但不进强制加载集。
+
+## 尚未实现的证据级别
+
+以下能力在 Claude Code adapter 落地前都不存在，装配报告必须如实标注为缺失，不得以「机制上应该可行」代替证据：
+
+- **Definition 零工具 canary 精确回显**：未实现。没有隔离 Workspace 探针，也没有屏蔽用户级/全局 `CLAUDE.md` 与 config 面的运行方式，无法证明本体经原生 rule 加载而非模型读文件得来。
+- **Basic 入口随机 probe + anti-guess baseline**：未实现。Claude Code 没有等价于 `opencode debug config` / `debug skill` 的 resolved 指令与 Skill 发现路径导出通道，resolved 强制加载集与 Skill `location` 无法被静态复核，双组 run 也无从重算。
+- **代表性 reference 受限读取 canary**：未实现。缺少按 run 限定「仅允许目标文件 read、拒绝 external directory」的沙箱化工具权限面，无法判定越界 read 与 tail read 失败。
+- **版本与轨迹绑定**：未实现。Host 版本、精确 session ID、run/export 原始 stdout/stderr hash 的采集通道尚未接入 `dta agent audit --verify-load`。
+
+`--verify-load` 当前只对 OpenCode 生效。对 Claude Code 运行它不会产生证据，也不要把 OpenCode 上取得的 load evidence 转述成 Claude Code 的结论——证据绑定 Host，跨 Host 不迁移。
+
+## 当前可做与不可做
+
+可做：按上面两条接法之一把 `AGENTS.md` 接入 `CLAUDE.md`；把 Basic 与 Role Skill 整树物化到 `.claude/skills`；跑静态 `dta agent audit` 检查 Definition 语义、Storage 与文件完整性。
+
+不可做：宣称 Basic Skill 每 Session 已加载；签发或复用三类加载证据；给出 `ready`。静态审计通过的上限是 `partial`，缺口写成「Claude Code adapter 未实现，三类加载证据不可得」，而不是「无需检查」。

package/skills/core/dingtalk-agent-compose/references/{opencode-host-contract.md → hosts/opencode.md}

@@ -1,5 +1,9 @@
 # OpenCode Agent Host 加载合同
 
+四条不变量与三类证据见 [host-loading-contract.md](../host-loading-contract.md)。本文件写 OpenCode 的具体机制与验收命令，可从 [opencode.template.json](../../assets/hosts/opencode/opencode.template.json) 裁剪配置。
+
+**adapter 状态：完整。** OpenCode 是当前唯一能签发 Definition canary、Basic 入口 probe/anti-guess 与代表性 reference read canary 三类证据、从而支持 `ready` 的 Host。
+
 ## 两个目录面
 
 ```text

package/skills/core/dingtalk-agent-eval/SKILL.md

@@ -3,7 +3,7 @@ name: dingtalk-agent-eval
 description: 当用户要设计、运行、审计或扩展 dingtalk-agent/数字员工评测时使用，尤其是 OpenCode/DeepSeek、专用机器人、Agent Workspace、AGENTS.md + Skills、本地或钉钉文档状态、文件与产物断言、历史事故回归和 Live 晋级门禁。也用于 Agent 创建或部署完成后的验收、联调与调试：怎么测、怎么给它派任务试一下、给机器人发消息不回/没反应/@ 了没动静、任务卡住或失败、怀疑 Skill 没真的加载、要看这次执行的轨迹和会话。负责把场景归类、证明 Basic Skill 真实加载、采集多证据面并给出可复验结论；不负责事件触发器或生产业务写入。
 compatibility: Requires dingtalk-agent on PATH; model evals require the selected Agent Host; DingTalk readback requires authenticated dws.
 metadata:
-  version: "0.7.0"
+  version: "0.7.1"
 ---
 
 # 评测一个真正能工作的 Agent

package/skills/core/dingtalk-agent-eval/assets/eval-catalog.template.json

@@ -12,7 +12,7 @@
       "caseRefs": [
         { "suite": "path/to/suite.json", "ids": ["basic-skill-load"] }
       ],
-      "sourceRefs": ["skills/core/dingtalk-agent-compose/references/opencode-host-contract.md"]
+      "sourceRefs": ["skills/core/dingtalk-agent-compose/references/hosts/opencode.md"]
     }
   ]
 }