@xdxer/dingtalk-agent 0.1.4-beta.7 → 0.1.4-beta.9

package/docs/SECOND-AGENT-ACCEPTANCE.md

@@ -0,0 +1,62 @@
+# 一小时复制第二个岗位 Agent
+
+## 结论
+
+第二个 Agent 不复制运行时，只复制一份 Agent kit 并替换四类绑定：`AGENTS.md`、Role Skills、Field/存储、DWS authority。事件监听不在本流程内；没有事件时 Agent 仍以 Direct/Mounted Session 正常工作，有可信事件时再进入同一个 Prepared Runtime。
+
+仓库提供两份已通过同一合同的实例：
+
+- `examples/agents/fde-coach`：FDE 教练；
+- `examples/agents/release-manager`：发布经理。
+
+两者共享 Basic Behavior、Invocation、Session/Run/Wait、双半闸门与 Receipt；Definition、Role Skill、Field、Session state、记忆和权限完全隔离。
+
+## 60 分钟执行表
+
+| 时间 | 开发者动作 | 验收标准 |
+|---|---|---|
+| 0–10 分钟 | 复制任一 example，改目录名 | 原 example 不被覆盖，新目录不含 `.dingtalk-agent` |
+| 10–20 分钟 | 改 `AGENTS.md` 的身份、服务对象、职责、交付与拒绝边界 | 另一个 Agent 能回答“我是谁、负责什么、不做什么” |
+| 20–30 分钟 | 新建/改名 `skills/<role>/SKILL.md` | 目录名等于 frontmatter `name`；只含岗位方法，不重复基础行为 |
+| 30–40 分钟 | 配置 Field、存储路由和 DWS authority | 使用可信 ID；不同 Agent 不共用 state root、业务 scope 或生产权限 |
+| 40–50 分钟 | 先 `dta bootstrap --json`，需要 Prepared Run 时再显式 `dta init` | Direct 默认 ready/partial 可解释；init 采用 `AGENTS.md` 并发现 Role Skill |
+| 50–60 分钟 | 跑合同/mock Lab，检查冻结快照和隔离 | 无可信 target 不外发；两个 Agent 的 Definition/Session/记忆/权限不串 |
+
+## 最小操作
+
+```bash
+cp -R examples/agents/release-manager /path/to/my-agent
+cd /path/to/my-agent
+
+# 先验证本体；这一步不要求 Workspace，也不产生钉钉副作用
+dta bootstrap --json
+
+# 只有需要可信事件和 Prepared Run 时才初始化一次
+dta init
+dta bootstrap --json
+```
+
+首次 `init` 会优先采用已有 `AGENTS.md`，发现 `skills/*/SKILL.md`，并保留已有 `fields/default/field.json`。初始化后新增 Skill 不会自动热启用：离线评审后把 Skill name 加入 `.dingtalk-agent/workspace.json#skills`，由新 Session 重新冻结。
+
+## 自动化验收
+
+```bash
+npm run typecheck
+npm run eval:contract
+```
+
+合同 42 会从两份 example 分别创建临时 Workspace，并检查：
+
+1. 初始化前 Direct bootstrap 可工作且没有可信 target；
+2. 初始化后 `AGENTS.md`、Role Skill 与显式 Field 被正确采用；
+3. 两个 Definition、DWS profile、Session ID 不同，共享 Basic Behavior hash；
+4. FDE 的 Task Checkpoint 与 Memory Candidate 在发布经理 state root 中不可见；
+5. 两者都通过同一 fake-DWS Lab 的 Action/Receipt/平台回读合同。
+
+2026-07-16 本地基线为 42/42，通过；双 Agent 合同自动执行约 2–3 秒。这个数字证明模板化装配和隔离可自动验证，不代表真实账号、专用群、AI 表格和钉钉文档已接通。真实 L4 仍需为每个 Agent 提供专用测试对象、allowlist 和明确 `--live --yes` 授权。
+
+## 验收边界
+
+- 通过：开发者只改本体、岗位 Skill、存储/Field/authority，即可得到第二个结构完整、状态隔离的 Agent；
+- 不包含：Webhook、定时器、personal-event listener 等触发端；
+- 不冒充：mock 平台可见不等于真实钉钉送达，真实写入必须另走 Lab L3/L4 晋级门禁。

package/docs/architecture/agent-memory-topology.svg

@@ -0,0 +1,132 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1440 900" width="1440" height="900" role="img" aria-labelledby="title desc">
+  <title id="title">dingtalk-agent 三层语义记忆与控制状态拓扑</title>
+  <desc id="desc">Agent Run 按需读写三层语义记忆：Session 工作记忆、钉钉原生业务记忆、长期知识；Wait、锁、generation、幂等和 Receipt 位于独立控制状态；Git 用于定义与 Skill 的版本发布，不作为运行时锁或 PCB。</desc>
+  <style>
+    text { font-family:'Helvetica Neue',Helvetica,Arial,'PingFang SC','Microsoft YaHei',sans-serif; }
+    .title { fill:#111827;font-size:28px;font-weight:700; }
+    .subtitle { fill:#6b7280;font-size:14px; }
+    .lane { fill:#475569;font-size:12px;font-weight:700;letter-spacing:.08em; }
+    .node-title { fill:#111827;font-size:16px;font-weight:700; }
+    .node-sub { fill:#4b5563;font-size:12px; }
+    .small { fill:#64748b;font-size:11px; }
+    .label { fill:#475569;font-size:11px;font-weight:600; }
+  </style>
+  <defs>
+    <marker id="blue" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto"><polygon points="0 0,10 3.5,0 7" fill="#2563eb"/></marker>
+    <marker id="green" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto"><polygon points="0 0,10 3.5,0 7" fill="#059669"/></marker>
+    <marker id="purple" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto"><polygon points="0 0,10 3.5,0 7" fill="#7c3aed"/></marker>
+    <marker id="rose" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto"><polygon points="0 0,10 3.5,0 7" fill="#dc2626"/></marker>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%"><feDropShadow dx="0" dy="2" stdDeviation="3" flood-color="#0f172a" flood-opacity=".10"/></filter>
+  </defs>
+
+  <rect width="1440" height="900" fill="#ffffff"/>
+  <text x="40" y="48" class="title">三层语义记忆，各归各的介质</text>
+  <text x="40" y="75" class="subtitle">语义记忆服务“想起什么”；控制状态保证“只执行一次、从正确位置继续”。两者必须分开。</text>
+
+  <rect x="30" y="105" width="300" height="620" rx="14" fill="#eff6ff" stroke="#60a5fa" stroke-width="1.6"/>
+  <text x="50" y="132" class="lane">AGENT RUNTIME</text>
+
+  <rect x="70" y="180" width="220" height="122" rx="12" fill="#ffffff" stroke="#60a5fa" stroke-width="2.2" filter="url(#shadow)"/>
+  <rect x="74" y="184" width="212" height="114" rx="9" fill="none" stroke="#60a5fa" stroke-width=".8" opacity=".5"/>
+  <text x="180" y="218" text-anchor="middle" class="node-title">Agent Run</text>
+  <text x="180" y="243" text-anchor="middle" class="node-sub">一次事件唤醒</text>
+  <text x="180" y="265" text-anchor="middle" class="node-sub">推理 · 工具 · ActionRequest</text>
+  <text x="180" y="286" text-anchor="middle" class="small">沙箱可丢弃</text>
+
+  <rect x="70" y="355" width="220" height="132" rx="10" fill="#faf5ff" stroke="#c084fc" stroke-width="1.7"/>
+  <text x="180" y="388" text-anchor="middle" class="node-title">Session</text>
+  <text x="180" y="412" text-anchor="middle" class="node-sub">一件事的稳定语义边界</text>
+  <text x="180" y="435" text-anchor="middle" class="node-sub">goal · checkpoint · next</text>
+  <text x="180" y="457" text-anchor="middle" class="node-sub">waitFor · evidence</text>
+  <text x="180" y="478" text-anchor="middle" class="small">跨 Run，不跨事项</text>
+
+  <rect x="70" y="540" width="220" height="128" rx="10" fill="#fef2f2" stroke="#f87171" stroke-width="1.8" stroke-dasharray="6 4"/>
+  <text x="180" y="572" text-anchor="middle" class="node-title">Control State Client</text>
+  <text x="180" y="596" text-anchor="middle" class="node-sub">claim · resume · commit</text>
+  <text x="180" y="619" text-anchor="middle" class="node-sub">不暴露平台凭据</text>
+  <text x="180" y="643" text-anchor="middle" class="small">通过宿主原子接口读写</text>
+
+  <path d="M180 302 L180 355" fill="none" stroke="#2563eb" stroke-width="2" marker-end="url(#blue)"/>
+  <path d="M180 487 L180 540" fill="none" stroke="#dc2626" stroke-width="1.8" marker-end="url(#rose)"/>
+
+  <rect x="365" y="105" width="645" height="620" rx="14" fill="#f8fafc" stroke="#cbd5e1" stroke-width="1.2" stroke-dasharray="7 5"/>
+  <text x="385" y="132" class="lane">THREE SEMANTIC MEMORY TIERS</text>
+
+  <rect x="405" y="165" width="565" height="138" rx="12" fill="#eff6ff" stroke="#93c5fd" stroke-width="1.8" filter="url(#shadow)"/>
+  <rect x="425" y="184" width="78" height="34" rx="17" fill="#2563eb"/><text x="464" y="207" text-anchor="middle" fill="#ffffff" font-size="13" font-weight="700">L1 短期</text>
+  <text x="525" y="205" class="node-title">Session 工作记忆</text>
+  <text x="425" y="242" class="node-sub">介质：宿主 state root / 原子本地存储；可生成 Markdown checkpoint 供人审阅</text>
+  <text x="425" y="267" class="node-sub">内容：当前目标、做到哪、下一步、在等什么、已有哪些证据</text>
+  <text x="425" y="289" class="small">高频更新 · 事项结束后归档/压缩 · 不承担锁和幂等</text>
+
+  <rect x="405" y="348" width="565" height="138" rx="12" fill="#f0fdfa" stroke="#5eead4" stroke-width="1.8" filter="url(#shadow)"/>
+  <rect x="425" y="367" width="78" height="34" rx="17" fill="#0f766e"/><text x="464" y="390" text-anchor="middle" fill="#ffffff" font-size="13" font-weight="700">L2 工作</text>
+  <text x="525" y="388" class="node-title">钉钉原生业务记忆</text>
+  <text x="425" y="425" class="node-sub">介质：AI 表格宽表 / Todo / Calendar / 业务系统的唯一事实源</text>
+  <text x="425" y="450" class="node-sub">内容：日报摘要、待办快照、互动记录、可聚合的业务热数据</text>
+  <text x="425" y="472" class="small">结构化查询 · 跨 Agent 可读 · ID 与 schema 必须显式绑定</text>
+
+  <rect x="405" y="531" width="565" height="138" rx="12" fill="#f0fdf4" stroke="#86efac" stroke-width="1.8" filter="url(#shadow)"/>
+  <rect x="425" y="550" width="78" height="34" rx="17" fill="#15803d"/><text x="464" y="573" text-anchor="middle" fill="#ffffff" font-size="13" font-weight="700">L3 长期</text>
+  <text x="525" y="571" class="node-title">知识与能力资产</text>
+  <text x="425" y="608" class="node-sub">介质：钉钉文档树 / 知识库 / Wiki；按来源、范围与版本治理</text>
+  <text x="425" y="633" class="node-sub">内容：身份、职责、Skill、SOP、人物模式、错误库、稳定知识</text>
+  <text x="425" y="655" class="small">低频写入 · 需证据与准入 · 新 Run 才加载已发布版本</text>
+
+  <path d="M405 220 L330 220" fill="none" stroke="#059669" stroke-width="1.8" marker-end="url(#green)"/>
+  <path d="M330 258 L405 258" fill="none" stroke="#059669" stroke-width="1.6" stroke-dasharray="5 3" marker-end="url(#green)"/>
+  <rect x="342" y="194" width="52" height="20" rx="5" fill="#ffffff" opacity=".96"/><text x="368" y="209" text-anchor="middle" class="label">read</text>
+  <rect x="342" y="266" width="52" height="20" rx="5" fill="#ffffff" opacity=".96"/><text x="368" y="281" text-anchor="middle" class="label">write</text>
+
+  <path d="M405 400 L330 400" fill="none" stroke="#059669" stroke-width="1.8" marker-end="url(#green)"/>
+  <path d="M330 444 L405 444" fill="none" stroke="#059669" stroke-width="1.6" stroke-dasharray="5 3" marker-end="url(#green)"/>
+  <rect x="337" y="374" width="62" height="20" rx="5" fill="#ffffff" opacity=".96"/><text x="368" y="389" text-anchor="middle" class="label">query</text>
+  <rect x="342" y="452" width="52" height="20" rx="5" fill="#ffffff" opacity=".96"/><text x="368" y="467" text-anchor="middle" class="label">write</text>
+
+  <path d="M405 583 L330 583" fill="none" stroke="#059669" stroke-width="1.8" marker-end="url(#green)"/>
+  <path d="M330 627 L405 627" fill="none" stroke="#059669" stroke-width="1.6" stroke-dasharray="5 3" marker-end="url(#green)"/>
+  <rect x="342" y="557" width="52" height="20" rx="5" fill="#ffffff" opacity=".96"/><text x="368" y="572" text-anchor="middle" class="label">load</text>
+  <rect x="335" y="635" width="66" height="20" rx="5" fill="#ffffff" opacity=".96"/><text x="368" y="650" text-anchor="middle" class="label">propose</text>
+
+  <path d="M687 303 L687 348" fill="none" stroke="#7c3aed" stroke-width="1.7" marker-end="url(#purple)"/>
+  <path d="M687 486 L687 531" fill="none" stroke="#7c3aed" stroke-width="1.7" marker-end="url(#purple)"/>
+  <rect x="700" y="316" width="78" height="20" rx="5" fill="#ffffff" opacity=".96"/><text x="739" y="331" text-anchor="middle" class="label">结构化</text>
+  <rect x="700" y="499" width="78" height="20" rx="5" fill="#ffffff" opacity=".96"/><text x="739" y="514" text-anchor="middle" class="label">验证沉淀</text>
+
+  <rect x="1045" y="105" width="365" height="320" rx="14" fill="#fef2f2" stroke="#f87171" stroke-width="1.6" stroke-dasharray="7 5"/>
+  <text x="1065" y="132" fill="#b91c1c" font-size="12" font-weight="700" letter-spacing=".08em">CONTROL PLANE · 不是记忆</text>
+  <text x="1227" y="173" text-anchor="middle" class="node-title">宿主控制状态</text>
+
+  <rect x="1080" y="200" width="295" height="176" rx="10" fill="#ffffff" stroke="#fca5a5" stroke-width="1.5"/>
+  <text x="1105" y="230" class="node-sub">• EventIndex / delivery claim</text>
+  <text x="1105" y="258" class="node-sub">• Wait / correlation / timer</text>
+  <text x="1105" y="286" class="node-sub">• lock / generation / cancellation</text>
+  <text x="1105" y="314" class="node-sub">• idempotency key / action budget</text>
+  <text x="1105" y="342" class="node-sub">• Action intent / attempt / receipt</text>
+  <text x="1227" y="366" text-anchor="middle" class="small">需要 CAS / 原子写 / 可恢复语义</text>
+
+  <path d="M1045 270 L1018 270 L1018 708 L320 708 L320 604 L290 604" fill="none" stroke="#dc2626" stroke-width="1.8" marker-end="url(#rose)"/>
+  <rect x="925" y="681" width="88" height="20" rx="5" fill="#ffffff" opacity=".96"/><text x="969" y="696" text-anchor="middle" class="label">atomic state</text>
+
+  <rect x="1045" y="465" width="365" height="260" rx="14" fill="#faf5ff" stroke="#c084fc" stroke-width="1.6"/>
+  <text x="1065" y="492" fill="#7e22ce" font-size="12" font-weight="700" letter-spacing=".08em">GIT RELEASE PLANE</text>
+  <text x="1227" y="535" text-anchor="middle" class="node-title">定义与 Skill 的版本面</text>
+  <text x="1080" y="574" class="node-sub">• Agent Definition / Skill 源码与快照</text>
+  <text x="1080" y="603" class="node-sub">• 候选改进、评审、发布、回滚</text>
+  <text x="1080" y="632" class="node-sub">• 人可干预的语义 checkpoint 导出</text>
+  <rect x="1080" y="656" width="295" height="42" rx="8" fill="#ffffff" stroke="#d8b4fe" stroke-width="1.2"/>
+  <text x="1227" y="675" text-anchor="middle" fill="#7e22ce" font-size="12" font-weight="700">Git ≠ runtime lock / Wait / PCB authority</text>
+  <text x="1227" y="692" text-anchor="middle" class="small">发布是双向的，运行控制仍归宿主</text>
+
+  <path d="M1045 585 L1000 585 L1000 600 L970 600" fill="none" stroke="#7c3aed" stroke-width="1.7" stroke-dasharray="5 3" marker-end="url(#purple)"/>
+  <rect x="980" y="556" width="63" height="20" rx="5" fill="#ffffff" opacity=".96"/><text x="1011" y="571" text-anchor="middle" class="label">publish</text>
+
+  <rect x="30" y="765" width="1380" height="78" rx="10" fill="#f8fafc" stroke="#cbd5e1" stroke-width="1"/>
+  <text x="50" y="792" fill="#111827" font-size="13" font-weight="700">介质选择原则</text>
+  <text x="50" y="821" fill="#334155" font-size="14">当前事项 → Session　｜　可统计业务事实 → 原生表/任务/日历　｜　稳定可复用知识 → 文档/Wiki　｜　并发与副作用 → Control State　｜　发布与回滚 → Git</text>
+
+  <line x1="40" y1="873" x2="76" y2="873" stroke="#059669" stroke-width="1.8" marker-end="url(#green)"/><text x="84" y="877" class="small">读取</text>
+  <line x1="150" y1="873" x2="186" y2="873" stroke="#059669" stroke-width="1.6" stroke-dasharray="5 3" marker-end="url(#green)"/><text x="194" y="877" class="small">写入</text>
+  <line x1="265" y1="873" x2="301" y2="873" stroke="#7c3aed" stroke-width="1.7" marker-end="url(#purple)"/><text x="309" y="877" class="small">压缩 / 发布</text>
+  <line x1="440" y1="873" x2="476" y2="873" stroke="#dc2626" stroke-width="1.8" marker-end="url(#rose)"/><text x="484" y="877" class="small">原子控制</text>
+</svg>

package/docs/architecture/general-agent-kernel-topology.svg

@@ -0,0 +1,149 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1440 920" width="1440" height="920" role="img" aria-labelledby="title desc">
+  <title id="title">dingtalk-agent 通用 Agent 行为内核拓扑</title>
+  <desc id="desc">外部触发器提供标准化 Invocation；Agent Definition、基础 Skill 与岗位 Skill 定义具体员工；dingtalk-agent 内核补齐感知、判断响应资格、维护 Session Run Wait 并约束 Action；DWS 负责执行钉钉产品能力。</desc>
+  <style>
+    text { font-family:'Helvetica Neue',Helvetica,Arial,'PingFang SC','Microsoft YaHei',sans-serif; }
+    .title { fill:#111827;font-size:28px;font-weight:700; }
+    .subtitle { fill:#6b7280;font-size:14px; }
+    .lane { fill:#475569;font-size:12px;font-weight:700;letter-spacing:.08em; }
+    .node-title { fill:#111827;font-size:16px;font-weight:700; }
+    .node-sub { fill:#4b5563;font-size:12px; }
+    .small { fill:#64748b;font-size:11px; }
+    .label { fill:#475569;font-size:11px;font-weight:600; }
+  </style>
+  <defs>
+    <marker id="blue" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto"><polygon points="0 0,10 3.5,0 7" fill="#2563eb"/></marker>
+    <marker id="orange" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto"><polygon points="0 0,10 3.5,0 7" fill="#ea580c"/></marker>
+    <marker id="green" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto"><polygon points="0 0,10 3.5,0 7" fill="#059669"/></marker>
+    <marker id="purple" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto"><polygon points="0 0,10 3.5,0 7" fill="#7c3aed"/></marker>
+    <marker id="gray" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto"><polygon points="0 0,10 3.5,0 7" fill="#64748b"/></marker>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%"><feDropShadow dx="0" dy="2" stdDeviation="3" flood-color="#0f172a" flood-opacity=".10"/></filter>
+  </defs>
+
+  <rect width="1440" height="920" fill="#ffffff"/>
+  <text x="40" y="48" class="title">dingtalk-agent · 从一个 Agent 泛化到所有 Agent</text>
+  <text x="40" y="75" class="subtitle">触发端可替换，模型与沙箱可替换，岗位能力可叠加；不变的是定义、上下文、状态、闸门与效果证据。</text>
+
+  <rect x="30" y="100" width="1380" height="130" rx="12" fill="#f8fafc" stroke="#cbd5e1" stroke-width="1.2" stroke-dasharray="7 5"/>
+  <text x="48" y="124" class="lane">EXTERNAL INVOCATION · 触发不属于 dta</text>
+
+  <rect x="55" y="145" width="245" height="62" rx="9" fill="#fff7ed" stroke="#fdba74" stroke-width="1.6"/>
+  <text x="177" y="171" text-anchor="middle" class="node-title">任意触发 Adapter</text>
+  <text x="177" y="192" text-anchor="middle" class="node-sub">DM · @ · ambient · heartbeat · API</text>
+
+  <rect x="385" y="137" width="300" height="78" rx="10" fill="#eff6ff" stroke="#60a5fa" stroke-width="2" filter="url(#shadow)"/>
+  <text x="535" y="166" text-anchor="middle" class="node-title">Invocation Context</text>
+  <text x="535" y="189" text-anchor="middle" class="node-sub">mode · actor · target · conversation · sessionKey</text>
+  <text x="535" y="207" text-anchor="middle" class="small">无可信事件时默认 direct；外发仍 fail closed</text>
+
+  <rect x="770" y="137" width="590" height="78" rx="10" fill="#faf5ff" stroke="#c084fc" stroke-width="1.6"/>
+  <text x="1065" y="164" text-anchor="middle" class="node-title">同一内核的不同员工实例</text>
+  <text x="1065" y="190" text-anchor="middle" class="node-sub">FDE 教练　·　招聘助理　·　运维助手　·　项目经理　·　下一位 Agent</text>
+
+  <path d="M300 176 L385 176" fill="none" stroke="#ea580c" stroke-width="1.8" stroke-dasharray="6 4" marker-end="url(#orange)"/>
+  <rect x="314" y="153" width="57" height="20" rx="5" fill="#ffffff" opacity=".96"/><text x="342" y="168" text-anchor="middle" class="label">normalize</text>
+
+  <rect x="30" y="255" width="1380" height="165" rx="12" fill="#f8fafc" stroke="#cbd5e1" stroke-width="1.2" stroke-dasharray="7 5"/>
+  <text x="48" y="280" class="lane">AGENT DEFINITION · 差异在这里叠加</text>
+
+  <rect x="55" y="305" width="345" height="86" rx="10" fill="#eff6ff" stroke="#93c5fd" stroke-width="1.7" filter="url(#shadow)"/>
+  <text x="227" y="334" text-anchor="middle" class="node-title">Agent Definition</text>
+  <text x="227" y="357" text-anchor="middle" class="node-sub">身份 · 职责 · 服务对象 · 权限 · 存储绑定</text>
+  <text x="227" y="377" text-anchor="middle" class="small">一个可版本化、可审查、可冻结的员工合同</text>
+
+  <rect x="460" y="305" width="260" height="86" rx="10" fill="#f0fdfa" stroke="#5eead4" stroke-width="1.7"/>
+  <text x="590" y="334" text-anchor="middle" class="node-title">Basic Behavior Skill</text>
+  <text x="590" y="358" text-anchor="middle" class="node-sub">所有员工共享</text>
+  <text x="590" y="378" text-anchor="middle" class="small">响应资格 · 追问 · 静默 · 验证</text>
+
+  <rect x="780" y="305" width="260" height="86" rx="10" fill="#f0fdf4" stroke="#86efac" stroke-width="1.7"/>
+  <text x="910" y="334" text-anchor="middle" class="node-title">Role / Workflow Skills</text>
+  <text x="910" y="358" text-anchor="middle" class="node-sub">按岗位叠加</text>
+  <text x="910" y="378" text-anchor="middle" class="small">FDE · 招聘 · 周报 · 事故处理</text>
+
+  <rect x="1100" y="305" width="260" height="86" rx="10" fill="#faf5ff" stroke="#c084fc" stroke-width="1.7"/>
+  <text x="1230" y="334" text-anchor="middle" class="node-title">Agent Host / Sandbox</text>
+  <text x="1230" y="358" text-anchor="middle" class="node-sub">Claude Code · Codex · 其它 Runtime</text>
+  <text x="1230" y="378" text-anchor="middle" class="small">模型与执行体可替换</text>
+
+  <rect x="30" y="445" width="1160" height="315" rx="14" fill="#f8fafc" stroke="#0f766e" stroke-width="2"/>
+  <text x="50" y="473" fill="#0f766e" font-size="13" font-weight="700" letter-spacing=".08em">DINGTALK-AGENT KERNEL · Skill 劝，CLI 拦，本体与状态各归其位</text>
+
+  <rect x="60" y="500" width="420" height="205" rx="12" fill="#f0fdfa" stroke="#5eead4" stroke-width="1.4" stroke-dasharray="6 4"/>
+  <text x="78" y="525" fill="#0f766e" font-size="12" font-weight="700">贴心半闸门 · 让 Agent 看见完整现场</text>
+
+  <rect x="85" y="550" width="165" height="112" rx="9" fill="#ffffff" stroke="#5eead4" stroke-width="1.6"/>
+  <text x="167" y="580" text-anchor="middle" class="node-title">感知预处理</text>
+  <text x="167" y="604" text-anchor="middle" class="node-sub">引用 · 群上下文 · 附件</text>
+  <text x="167" y="625" text-anchor="middle" class="node-sub">身份解析 · 连发合并</text>
+  <text x="167" y="646" text-anchor="middle" class="small">统一 Enriched Event</text>
+
+  <rect x="290" y="550" width="165" height="112" rx="9" fill="#ffffff" stroke="#5eead4" stroke-width="1.6"/>
+  <text x="372" y="580" text-anchor="middle" class="node-title">行为策略</text>
+  <text x="372" y="604" text-anchor="middle" class="node-sub">中期回执 · 安静时段</text>
+  <text x="372" y="625" text-anchor="middle" class="node-sub">会议免打扰 · 收口快照</text>
+  <text x="372" y="646" text-anchor="middle" class="small">给 Skill 可判断的提示</text>
+
+  <rect x="510" y="500" width="650" height="205" rx="12" fill="#fff7ed" stroke="#fdba74" stroke-width="1.4" stroke-dasharray="6 4"/>
+  <text x="528" y="525" fill="#c2410c" font-size="12" font-weight="700">安全半闸门 · 必须成立的约束进入代码</text>
+
+  <rect x="535" y="550" width="170" height="112" rx="9" fill="#ffffff" stroke="#fdba74" stroke-width="1.6"/>
+  <text x="620" y="580" text-anchor="middle" class="node-title">Response Gate</text>
+  <text x="620" y="604" text-anchor="middle" class="node-sub">先判断能否响应</text>
+  <text x="620" y="625" text-anchor="middle" class="node-sub">@ · DM · ambient · scope</text>
+  <text x="620" y="646" text-anchor="middle" class="small">内容生成之前</text>
+
+  <rect x="745" y="540" width="180" height="132" rx="10" fill="#eff6ff" stroke="#60a5fa" stroke-width="1.8" filter="url(#shadow)"/>
+  <text x="835" y="574" text-anchor="middle" class="node-title">Session Runtime</text>
+  <text x="835" y="598" text-anchor="middle" class="node-sub">Session · Run · Wait</text>
+  <text x="835" y="619" text-anchor="middle" class="node-sub">Skill snapshot · budget</text>
+  <text x="835" y="640" text-anchor="middle" class="node-sub">checkpoint · resume</text>
+  <text x="835" y="660" text-anchor="middle" class="small">一件事跨多次唤醒</text>
+
+  <rect x="965" y="550" width="170" height="112" rx="9" fill="#ffffff" stroke="#f87171" stroke-width="1.8"/>
+  <text x="1050" y="580" text-anchor="middle" class="node-title">Action Gate</text>
+  <text x="1050" y="604" text-anchor="middle" class="node-sub">目标 · 身份 · 权限</text>
+  <text x="1050" y="625" text-anchor="middle" class="node-sub">幂等 · 回读 · Receipt</text>
+  <text x="1050" y="646" text-anchor="middle" class="small">副作用之前</text>
+
+  <path d="M535 215 L535 238 L42 238 L42 606 L85 606" fill="none" stroke="#2563eb" stroke-width="2" marker-end="url(#blue)"/>
+  <path d="M250 606 L290 606" fill="none" stroke="#059669" stroke-width="1.8" marker-end="url(#green)"/>
+  <path d="M455 606 L535 606" fill="none" stroke="#2563eb" stroke-width="2" marker-end="url(#blue)"/>
+  <path d="M705 606 L745 606" fill="none" stroke="#2563eb" stroke-width="2" marker-end="url(#blue)"/>
+  <path d="M925 606 L965 606" fill="none" stroke="#2563eb" stroke-width="2" marker-end="url(#blue)"/>
+
+  <path d="M227 391 L227 430 L780 430 L780 540" fill="none" stroke="#7c3aed" stroke-width="1.7" marker-end="url(#purple)"/>
+  <path d="M590 391 L590 440 L810 440 L810 540" fill="none" stroke="#7c3aed" stroke-width="1.7" marker-end="url(#purple)"/>
+  <path d="M910 391 L910 440 L850 440 L850 540" fill="none" stroke="#7c3aed" stroke-width="1.7" marker-end="url(#purple)"/>
+  <path d="M1230 391 L1230 430 L895 430 L895 540" fill="none" stroke="#7c3aed" stroke-width="1.7" marker-end="url(#purple)"/>
+
+  <rect x="355" y="720" width="510" height="24" rx="6" fill="#ffffff" stroke="#d1d5db" stroke-width="1"/>
+  <text x="610" y="737" text-anchor="middle" class="small">三层语义记忆按需读取；Wait / 锁 / 幂等 / Receipt 进入独立控制状态</text>
+
+  <rect x="1230" y="520" width="160" height="92" rx="10" fill="#f0fdfa" stroke="#2dd4bf" stroke-width="2" filter="url(#shadow)"/>
+  <circle cx="1262" cy="550" r="18" fill="#1677ff"/><text x="1262" y="555" text-anchor="middle" fill="#ffffff" font-size="10" font-weight="700">DWS</text>
+  <text x="1310" y="551" text-anchor="middle" class="node-title">驱动层</text>
+  <text x="1310" y="579" text-anchor="middle" class="node-sub">标准产品能力</text>
+  <text x="1310" y="598" text-anchor="middle" class="small">CLI / 未来 SDK</text>
+
+  <rect x="1230" y="660" width="160" height="92" rx="10" fill="#eff6ff" stroke="#93c5fd" stroke-width="1.7"/>
+  <text x="1310" y="689" text-anchor="middle" class="node-title">钉钉产品</text>
+  <text x="1310" y="713" text-anchor="middle" class="node-sub">消息 · 文档 · 待办</text>
+  <text x="1310" y="734" text-anchor="middle" class="node-sub">日历 · 表格 · 审批</text>
+
+  <path d="M1135 606 L1185 606 L1185 566 L1230 566" fill="none" stroke="#2563eb" stroke-width="2.2" marker-end="url(#blue)"/>
+  <path d="M1310 612 L1310 660" fill="none" stroke="#2563eb" stroke-width="2.2" marker-end="url(#blue)"/>
+  <path d="M1230 706 L1188 706 L1188 688 L1050 688 L1050 662" fill="none" stroke="#64748b" stroke-width="1.6" stroke-dasharray="5 4" marker-end="url(#gray)"/>
+  <rect x="1082" y="676" width="82" height="20" rx="5" fill="#ffffff" opacity=".96"/><text x="1123" y="691" text-anchor="middle" class="label">平台回读</text>
+
+  <rect x="30" y="790" width="1380" height="76" rx="10" fill="#f8fafc" stroke="#cbd5e1" stroke-width="1"/>
+  <text x="50" y="816" fill="#111827" font-size="13" font-weight="700">可叠加公式</text>
+  <text x="50" y="844" fill="#334155" font-size="15">Agent Host + dta Kernel + Agent Definition + Basic Behavior + Role Skills + DWS = 一个可工作的钉钉数字员工</text>
+  <text x="940" y="844" class="small">触发、模型、沙箱、岗位与存储 Provider 均可替换</text>
+
+  <line x1="40" y1="892" x2="76" y2="892" stroke="#2563eb" stroke-width="2" marker-end="url(#blue)"/><text x="84" y="896" class="small">主处理流</text>
+  <line x1="210" y1="892" x2="246" y2="892" stroke="#ea580c" stroke-width="1.8" stroke-dasharray="6 4" marker-end="url(#orange)"/><text x="254" y="896" class="small">外部触发</text>
+  <line x1="370" y1="892" x2="406" y2="892" stroke="#059669" stroke-width="1.8" marker-end="url(#green)"/><text x="414" y="896" class="small">感知补齐</text>
+  <line x1="530" y1="892" x2="566" y2="892" stroke="#7c3aed" stroke-width="1.8" marker-end="url(#purple)"/><text x="574" y="896" class="small">定义 / Skill 注入</text>
+  <line x1="735" y1="892" x2="771" y2="892" stroke="#64748b" stroke-width="1.6" stroke-dasharray="5 4" marker-end="url(#gray)"/><text x="779" y="896" class="small">回读 / 控制反馈</text>
+</svg>

package/docs/architecture/provider-bound-development-workspace.svg

@@ -0,0 +1,141 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 820" width="1200" height="820" role="img" aria-labelledby="title desc">
+  <title id="title">dingtalk-agent Provider-bound Development Workspace 拓扑</title>
+  <desc id="desc">一个可移植 Agent Project 可以解析成多个开发 Workspace；每个 Workspace 只绑定一个 Host Provider，但可以独立绑定不同的语义 Storage。Session 和 Run 位于 Workspace 内，实际状态和回执与期望 Manifest 分开。</desc>
+  <style>
+    text { font-family: 'Helvetica Neue', Helvetica, Arial, 'PingFang SC', 'Microsoft YaHei', sans-serif; }
+    .title { font-size: 23px; font-weight: 700; fill: #111827; }
+    .subtitle { font-size: 13px; fill: #6b7280; }
+    .layer-title { font-size: 13px; font-weight: 700; fill: #374151; letter-spacing: .4px; }
+    .node-title { font-size: 15px; font-weight: 700; fill: #111827; }
+    .node-sub { font-size: 12px; fill: #6b7280; }
+    .tiny { font-size: 11px; fill: #6b7280; }
+    .edge-label { font-size: 11px; font-weight: 600; fill: #4b5563; }
+  </style>
+  <defs>
+    <marker id="arrow-blue" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+      <polygon points="0 0, 10 3.5, 0 7" fill="#2563eb"/>
+    </marker>
+    <marker id="arrow-green" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+      <polygon points="0 0, 10 3.5, 0 7" fill="#16a34a"/>
+    </marker>
+    <marker id="arrow-purple" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+      <polygon points="0 0, 10 3.5, 0 7" fill="#9333ea"/>
+    </marker>
+    <filter id="shadow" x="-10%" y="-10%" width="120%" height="130%">
+      <feDropShadow dx="0" dy="2" stdDeviation="3" flood-color="#111827" flood-opacity="0.10"/>
+    </filter>
+  </defs>
+
+  <rect width="1200" height="820" fill="#ffffff"/>
+  <text x="40" y="43" class="title">Provider-bound Development Workspace</text>
+  <text x="40" y="67" class="subtitle">Project 定义“要开发成什么”；Workspace 定义“在哪里、以什么 Provider 状态开发”；Session / Run 定义“正在做哪件事”。</text>
+
+  <!-- Developer control plane -->
+  <rect x="40" y="92" width="1120" height="108" rx="12" fill="#f9fafb" stroke="#d1d5db" stroke-width="1.5" stroke-dasharray="6 4"/>
+  <text x="58" y="116" class="layer-title">开发控制面</text>
+  <rect x="80" y="132" width="220" height="48" rx="9" fill="#eff6ff" stroke="#bfdbfe" stroke-width="1.5"/>
+  <text x="190" y="153" text-anchor="middle" class="node-title">Coding Agent / Developer</text>
+  <text x="190" y="170" text-anchor="middle" class="node-sub">Codex · OpenCode · 人</text>
+  <rect x="430" y="122" width="330" height="66" rx="10" fill="#fff7ed" stroke="#fed7aa" stroke-width="1.5" filter="url(#shadow)"/>
+  <text x="595" y="147" text-anchor="middle" class="node-title">dta Workflow Skills + CLI</text>
+  <text x="595" y="167" text-anchor="middle" class="node-sub">compose · info · eval · deploy · status</text>
+  <rect x="890" y="132" width="220" height="48" rx="9" fill="#faf5ff" stroke="#e9d5ff" stroke-width="1.5"/>
+  <text x="1000" y="153" text-anchor="middle" class="node-title">Plan / Receipt</text>
+  <text x="1000" y="170" text-anchor="middle" class="node-sub">稳定机器合同，无 Secret</text>
+  <path d="M 300 156 L 420 156" fill="none" stroke="#2563eb" stroke-width="2" marker-end="url(#arrow-blue)"/>
+  <path d="M 760 156 L 880 156" fill="none" stroke="#2563eb" stroke-width="2" marker-end="url(#arrow-blue)"/>
+
+  <!-- Project -->
+  <rect x="40" y="224" width="800" height="138" rx="12" fill="#f9fafb" stroke="#d1d5db" stroke-width="1.5" stroke-dasharray="6 4"/>
+  <text x="58" y="248" class="layer-title">可移植 Agent Project · 进入 Git</text>
+  <rect x="80" y="270" width="210" height="66" rx="9" fill="#eff6ff" stroke="#bfdbfe" stroke-width="1.5"/>
+  <text x="185" y="296" text-anchor="middle" class="node-title">dingtalk-agent.json</text>
+  <text x="185" y="317" text-anchor="middle" class="node-sub">Project + Workspace 期望状态</text>
+  <rect x="325" y="270" width="210" height="66" rx="9" fill="#f0fdf4" stroke="#bbf7d0" stroke-width="1.5"/>
+  <text x="430" y="296" text-anchor="middle" class="node-title">AGENTS.md + Skills</text>
+  <text x="430" y="317" text-anchor="middle" class="node-sub">本体、Basic、岗位能力</text>
+  <rect x="570" y="270" width="220" height="66" rx="9" fill="#faf5ff" stroke="#e9d5ff" stroke-width="1.5"/>
+  <text x="680" y="296" text-anchor="middle" class="node-title">Eval Suites</text>
+  <text x="680" y="317" text-anchor="middle" class="node-sub">成功标准与晋级门禁</text>
+  <path d="M 595 188 L 595 214 L 430 214 L 430 260" fill="none" stroke="#2563eb" stroke-width="2" marker-end="url(#arrow-blue)"/>
+
+  <!-- Storage providers -->
+  <rect x="870" y="224" width="290" height="338" rx="12" fill="#f0fdf4" stroke="#bbf7d0" stroke-width="1.5" stroke-dasharray="6 4"/>
+  <text x="890" y="248" class="layer-title">独立 Storage Providers</text>
+  <text x="890" y="269" class="tiny">只决定语义内容放哪里，不决定 Agent 在哪里运行</text>
+  <rect x="910" y="296" width="210" height="54" rx="9" fill="#ffffff" stroke="#86efac" stroke-width="1.5"/>
+  <text x="1015" y="319" text-anchor="middle" class="node-title">local-md / local-dir</text>
+  <text x="1015" y="337" text-anchor="middle" class="node-sub">本地本体、记忆、产物</text>
+  <rect x="910" y="374" width="210" height="54" rx="9" fill="#ffffff" stroke="#86efac" stroke-width="1.5"/>
+  <text x="1015" y="397" text-anchor="middle" class="node-title">dingtalk-doc</text>
+  <text x="1015" y="415" text-anchor="middle" class="node-sub">远端记忆与知识</text>
+  <rect x="910" y="452" width="210" height="54" rx="9" fill="#ffffff" stroke="#86efac" stroke-width="1.5"/>
+  <text x="1015" y="475" text-anchor="middle" class="node-title">Future typed stores</text>
+  <text x="1015" y="493" text-anchor="middle" class="node-sub">AI 表格 · Artifact store</text>
+  <text x="1015" y="538" text-anchor="middle" class="tiny">锁 / Wait / generation / Receipt 不进入这些介质</text>
+
+  <!-- Workspaces -->
+  <rect x="40" y="388" width="800" height="174" rx="12" fill="#f9fafb" stroke="#d1d5db" stroke-width="1.5" stroke-dasharray="6 4"/>
+  <text x="58" y="412" class="layer-title">Development Workspaces · 一个 Workspace 只绑定一个 Host Provider</text>
+  <rect x="75" y="436" width="220" height="94" rx="10" fill="#eff6ff" stroke="#93c5fd" stroke-width="1.8" filter="url(#shadow)"/>
+  <text x="185" y="462" text-anchor="middle" class="node-title">local-dev</text>
+  <text x="185" y="483" text-anchor="middle" class="node-sub">provider = opencode</text>
+  <text x="185" y="503" text-anchor="middle" class="node-sub">model · Basic load · local state</text>
+  <text x="185" y="519" text-anchor="middle" class="tiny">stage = dev</text>
+  <rect x="330" y="436" width="220" height="94" rx="10" fill="#fff7ed" stroke="#fdba74" stroke-width="1.8" filter="url(#shadow)"/>
+  <text x="440" y="462" text-anchor="middle" class="node-title">multica-dev</text>
+  <text x="440" y="483" text-anchor="middle" class="node-sub">provider = multica</text>
+  <text x="440" y="503" text-anchor="middle" class="node-sub">profile · scope · runtime · agentId</text>
+  <text x="440" y="519" text-anchor="middle" class="tiny">stage = dev</text>
+  <rect x="585" y="436" width="220" height="94" rx="10" fill="#faf5ff" stroke="#d8b4fe" stroke-width="1.8"/>
+  <text x="695" y="462" text-anchor="middle" class="node-title">future-workspace</text>
+  <text x="695" y="483" text-anchor="middle" class="node-sub">provider = future</text>
+  <text x="695" y="503" text-anchor="middle" class="node-sub">同一最小 Provider 合同</text>
+  <text x="695" y="519" text-anchor="middle" class="tiny">optional</text>
+  <path d="M 185 362 L 185 426" fill="none" stroke="#2563eb" stroke-width="2" marker-end="url(#arrow-blue)"/>
+  <path d="M 430 362 L 430 406 L 440 406 L 440 426" fill="none" stroke="#2563eb" stroke-width="2" marker-end="url(#arrow-blue)"/>
+  <path d="M 680 362 L 680 406 L 695 406 L 695 426" fill="none" stroke="#2563eb" stroke-width="2" marker-end="url(#arrow-blue)"/>
+  <rect x="360" y="374" width="157" height="20" rx="4" fill="#ffffff" opacity="0.96"/>
+  <text x="438" y="388" text-anchor="middle" class="edge-label">Project + Workspace overlay</text>
+
+  <!-- Storage binding arrows -->
+  <path d="M 840 454 L 856 454 L 856 323 L 900 323" fill="none" stroke="#16a34a" stroke-width="1.8" stroke-dasharray="6 4" marker-end="url(#arrow-green)"/>
+  <path d="M 840 522 L 872 522 L 872 401 L 900 401" fill="none" stroke="#16a34a" stroke-width="1.8" stroke-dasharray="6 4" marker-end="url(#arrow-green)"/>
+  <rect x="752" y="418" width="98" height="20" rx="4" fill="#ffffff" opacity="0.96"/>
+  <text x="801" y="432" text-anchor="middle" class="edge-label">storage binding</text>
+
+  <!-- Runtime actual state -->
+  <rect x="40" y="588" width="1120" height="158" rx="12" fill="#f9fafb" stroke="#d1d5db" stroke-width="1.5" stroke-dasharray="6 4"/>
+  <text x="58" y="612" class="layer-title">Provider 实际状态 · 回读后写入 gitignored state / Receipt</text>
+  <rect x="75" y="634" width="220" height="84" rx="10" fill="#111827" stroke="#374151" stroke-width="1.5"/>
+  <text x="185" y="660" text-anchor="middle" font-size="15" font-weight="700" fill="#ffffff">OpenCode Sandbox</text>
+  <text x="185" y="681" text-anchor="middle" font-size="12" fill="#d1d5db">invoke · eval · files/artifacts</text>
+  <text x="185" y="700" text-anchor="middle" font-size="11" fill="#9ca3af">Sessions → Runs → Evidence</text>
+  <rect x="330" y="634" width="220" height="84" rx="10" fill="#fff7ed" stroke="#fdba74" stroke-width="1.5"/>
+  <text x="440" y="660" text-anchor="middle" class="node-title">Multica Managed Agent</text>
+  <text x="440" y="681" text-anchor="middle" class="node-sub">Boot → Basic → Role Skills</text>
+  <text x="440" y="700" text-anchor="middle" class="tiny">agent get · skills · status · smoke</text>
+  <rect x="585" y="634" width="220" height="84" rx="10" fill="#faf5ff" stroke="#d8b4fe" stroke-width="1.5"/>
+  <text x="695" y="660" text-anchor="middle" class="node-title">Future Provider</text>
+  <text x="695" y="681" text-anchor="middle" class="node-sub">doctor · plan · apply</text>
+  <text x="695" y="700" text-anchor="middle" class="tiny">inspect · invoke · status</text>
+  <rect x="890" y="634" width="230" height="84" rx="10" fill="#f0fdfa" stroke="#99f6e4" stroke-width="1.5"/>
+  <text x="1005" y="660" text-anchor="middle" class="node-title">Workspace State / Receipt</text>
+  <text x="1005" y="681" text-anchor="middle" class="node-sub">desiredHash · observedHash</text>
+  <text x="1005" y="700" text-anchor="middle" class="tiny">operationId · evalId · no secrets</text>
+  <path d="M 185 530 L 185 624" fill="none" stroke="#2563eb" stroke-width="2" marker-end="url(#arrow-blue)"/>
+  <path d="M 440 530 L 440 624" fill="none" stroke="#2563eb" stroke-width="2" marker-end="url(#arrow-blue)"/>
+  <path d="M 695 530 L 695 624" fill="none" stroke="#2563eb" stroke-width="2" marker-end="url(#arrow-blue)"/>
+  <path d="M 805 676 L 880 676" fill="none" stroke="#9333ea" stroke-width="1.8" marker-end="url(#arrow-purple)"/>
+
+  <!-- Legend and invariant -->
+  <line x1="55" y1="780" x2="90" y2="780" stroke="#2563eb" stroke-width="2" marker-end="url(#arrow-blue)"/>
+  <text x="100" y="784" class="tiny">开发/解析/执行主路径</text>
+  <line x1="265" y1="780" x2="300" y2="780" stroke="#16a34a" stroke-width="1.8" stroke-dasharray="6 4" marker-end="url(#arrow-green)"/>
+  <text x="310" y="784" class="tiny">语义 Storage 绑定</text>
+  <line x1="455" y1="780" x2="490" y2="780" stroke="#9333ea" stroke-width="1.8" marker-end="url(#arrow-purple)"/>
+  <text x="500" y="784" class="tiny">Provider 回读与证据</text>
+  <rect x="760" y="759" width="400" height="38" rx="8" fill="#fef2f2" stroke="#fecaca"/>
+  <text x="960" y="775" text-anchor="middle" font-size="12" font-weight="700" fill="#991b1b">不变量：Provider 不从正文猜身份/目标，不拥有 Trigger</text>
+  <text x="960" y="790" text-anchor="middle" font-size="11" fill="#b91c1c">一个 Workspace 不原地改绑 Provider；新环境创建新 Workspace</text>
+</svg>