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

package/docs/architecture/task-completion-gate.svg

@@ -0,0 +1,191 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 840" role="img" aria-labelledby="title desc">
+  <title id="title">数字员工任务闭环与完成闸门</title>
+  <desc id="desc">展示任务从可信上下文、理解、条件澄清、计划、执行、验证到完成闸门的流程，以及运行时状态约束和四类证据。</desc>
+  <defs>
+    <style>
+      text { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #0f172a; }
+      .title { font-size: 28px; font-weight: 750; }
+      .subtitle { font-size: 14px; fill: #475569; }
+      .section { font-size: 13px; font-weight: 700; letter-spacing: .8px; fill: #475569; }
+      .node-title { font-size: 15px; font-weight: 750; }
+      .node-sub { font-size: 12px; fill: #475569; }
+      .small { font-size: 11px; fill: #64748b; }
+      .label { font-size: 12px; font-weight: 650; }
+    </style>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="3" stdDeviation="5" flood-color="#0f172a" flood-opacity="0.10"/>
+    </filter>
+    <marker id="arrow-blue" markerWidth="10" markerHeight="8" refX="9" refY="4" orient="auto">
+      <path d="M0,0 L10,4 L0,8 Z" fill="#2563eb"/>
+    </marker>
+    <marker id="arrow-orange" markerWidth="10" markerHeight="8" refX="9" refY="4" orient="auto">
+      <path d="M0,0 L10,4 L0,8 Z" fill="#ea580c"/>
+    </marker>
+    <marker id="arrow-green" markerWidth="10" markerHeight="8" refX="9" refY="4" orient="auto">
+      <path d="M0,0 L10,4 L0,8 Z" fill="#059669"/>
+    </marker>
+    <marker id="arrow-stop" markerWidth="10" markerHeight="8" refX="9" refY="4" orient="auto">
+      <path d="M0,0 L10,4 L0,8 Z" fill="#dc2626"/>
+    </marker>
+  </defs>
+
+  <rect width="1200" height="840" fill="#f8fafc"/>
+  <text x="54" y="48" class="title">数字员工任务闭环与完成闸门</text>
+  <text x="54" y="76" class="subtitle">澄清是条件分支；完成是证据结论。Skill 引导语义判断，CLI 固定状态边界，DWS / 文件系统提供可回读事实。</text>
+
+  <rect x="50" y="104" width="1100" height="106" rx="18" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.5" stroke-dasharray="7 5"/>
+  <text x="72" y="130" class="section">可信现场 · TRUSTED CONTEXT</text>
+
+  <rect x="72" y="146" width="304" height="46" rx="12" fill="#eff6ff" stroke="#93c5fd"/>
+  <circle cx="98" cy="169" r="10" fill="#2563eb"/>
+  <path d="M93 169 l4 4 l7 -8" fill="none" stroke="#ffffff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+  <text x="118" y="166" class="node-title">Origin + Continuation</text>
+  <text x="118" y="182" class="small">当前消息、线程与明确续接</text>
+
+  <rect x="448" y="146" width="304" height="46" rx="12" fill="#fff7ed" stroke="#fdba74"/>
+  <path d="M470 160 h18 v18 h-18 z M474 156 h10 v5 h-10 z" fill="none" stroke="#ea580c" stroke-width="1.8"/>
+  <text x="502" y="166" class="node-title">Definition + Authority</text>
+  <text x="502" y="182" class="small">身份、职责、作用域与权限</text>
+
+  <rect x="824" y="146" width="304" height="46" rx="12" fill="#f0fdf4" stroke="#86efac"/>
+  <path d="M848 158 h17 l6 6 v14 h-23 z M865 158 v7 h7" fill="none" stroke="#059669" stroke-width="1.8" stroke-linejoin="round"/>
+  <text x="884" y="166" class="node-title">Workspace + Role Skills</text>
+  <text x="884" y="182" class="small">附件、知识、已有 checkpoint</text>
+
+  <path d="M600 210 V236" fill="none" stroke="#ea580c" stroke-width="2" marker-end="url(#arrow-orange)"/>
+
+  <text x="50" y="251" class="section">员工任务主流程 · EMPLOYEE LOOP</text>
+
+  <rect x="50" y="272" width="146" height="78" rx="16" fill="#ffffff" stroke="#60a5fa" stroke-width="2" filter="url(#shadow)"/>
+  <circle cx="78" cy="298" r="13" fill="#dbeafe"/>
+  <path d="M72 298 h12 M78 292 v12" stroke="#2563eb" stroke-width="2" stroke-linecap="round"/>
+  <text x="101" y="299" class="node-title">UNDERSTAND</text>
+  <text x="73" y="326" class="node-sub">形成内部任务合同</text>
+  <text x="73" y="342" class="small">goal · deliverable · doneWhen</text>
+
+  <path d="M196 311 H228" fill="none" stroke="#2563eb" stroke-width="2.2" marker-end="url(#arrow-blue)"/>
+
+  <path d="M300 268 L370 311 L300 354 L230 311 Z" fill="#fff7ed" stroke="#fb923c" stroke-width="2" filter="url(#shadow)"/>
+  <text x="300" y="306" text-anchor="middle" class="node-title">存在阻塞缺口？</text>
+  <text x="300" y="326" text-anchor="middle" class="small">会改变结果 / 权限 / 副作用</text>
+
+  <path d="M370 311 H406" fill="none" stroke="#2563eb" stroke-width="2.2" marker-end="url(#arrow-blue)"/>
+  <rect x="374" y="288" width="28" height="18" rx="5" fill="#f8fafc" opacity="0.96"/>
+  <text x="388" y="301" text-anchor="middle" class="label" fill="#2563eb">否</text>
+
+  <rect x="406" y="272" width="132" height="78" rx="16" fill="#ffffff" stroke="#60a5fa" stroke-width="2"/>
+  <text x="472" y="301" text-anchor="middle" class="node-title">PLAN</text>
+  <text x="472" y="324" text-anchor="middle" class="node-sub">2–5 个检查点</text>
+  <text x="472" y="341" text-anchor="middle" class="small">单步任务可省略</text>
+
+  <path d="M538 311 H570" fill="none" stroke="#2563eb" stroke-width="2.2" marker-end="url(#arrow-blue)"/>
+
+  <rect x="570" y="272" width="132" height="78" rx="16" fill="#ffffff" stroke="#60a5fa" stroke-width="2"/>
+  <text x="636" y="301" text-anchor="middle" class="node-title">EXECUTE</text>
+  <text x="636" y="324" text-anchor="middle" class="node-sub">最小充分动作</text>
+  <text x="636" y="341" text-anchor="middle" class="small">副作用前重核对象</text>
+
+  <path d="M702 311 H734" fill="none" stroke="#2563eb" stroke-width="2.2" marker-end="url(#arrow-blue)"/>
+
+  <rect x="734" y="272" width="132" height="78" rx="16" fill="#ffffff" stroke="#34d399" stroke-width="2"/>
+  <text x="800" y="301" text-anchor="middle" class="node-title">VERIFY</text>
+  <text x="800" y="324" text-anchor="middle" class="node-sub">检查真实状态</text>
+  <text x="800" y="341" text-anchor="middle" class="small">生成 ≠ 保存 ≠ 送达</text>
+
+  <path d="M866 311 H898" fill="none" stroke="#2563eb" stroke-width="2.2" marker-end="url(#arrow-blue)"/>
+
+  <rect x="898" y="252" width="252" height="118" rx="18" fill="#fffbeb" stroke="#f59e0b" stroke-width="2.5" filter="url(#shadow)"/>
+  <rect x="918" y="270" width="52" height="24" rx="12" fill="#f59e0b"/>
+  <text x="944" y="287" text-anchor="middle" font-size="11" font-weight="750" fill="#ffffff">CLI GATE</text>
+  <text x="1024" y="289" class="node-title">COMPLETION GATE</text>
+  <text x="920" y="316" class="small">① status = verifying</text>
+  <text x="1038" y="316" class="small">② doneWhen 有证据</text>
+  <text x="920" y="337" class="small">③ waitingFor = null</text>
+  <text x="1038" y="337" class="small">④ nextAction 为空</text>
+  <text x="920" y="356" class="small">回复正文不能证明自己的完成声明</text>
+
+  <path d="M1024 370 V412" fill="none" stroke="#2563eb" stroke-width="2.4" marker-end="url(#arrow-blue)"/>
+  <rect x="1032" y="383" width="58" height="20" rx="6" fill="#f8fafc" opacity="0.96"/>
+  <text x="1061" y="398" text-anchor="middle" class="label" fill="#2563eb">全部通过</text>
+
+  <rect x="940" y="414" width="168" height="70" rx="18" fill="#ecfdf5" stroke="#10b981" stroke-width="2.5" filter="url(#shadow)"/>
+  <circle cx="972" cy="443" r="14" fill="#10b981"/>
+  <path d="M965 443 l5 5 l9 -11" fill="none" stroke="#ffffff" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"/>
+  <text x="1041" y="442" text-anchor="middle" class="node-title">COMPLETE</text>
+  <text x="1024" y="466" text-anchor="middle" class="node-sub">结果 · 证据 · 遗留 · owner</text>
+
+  <path d="M300 354 V396 H196" fill="none" stroke="#ea580c" stroke-width="2" marker-end="url(#arrow-orange)"/>
+  <rect x="306" y="366" width="28" height="18" rx="5" fill="#f8fafc" opacity="0.96"/>
+  <text x="320" y="379" text-anchor="middle" class="label" fill="#ea580c">是</text>
+
+  <rect x="50" y="396" width="146" height="72" rx="16" fill="#fff7ed" stroke="#fb923c" stroke-width="2"/>
+  <text x="123" y="425" text-anchor="middle" class="node-title">CLARIFY</text>
+  <text x="123" y="447" text-anchor="middle" class="node-sub">只问一个阻塞问题</text>
+  <text x="123" y="462" text-anchor="middle" class="small">信息足够时不出现</text>
+
+  <path d="M196 432 H230" fill="none" stroke="#ea580c" stroke-width="2" marker-end="url(#arrow-orange)"/>
+  <rect x="230" y="396" width="146" height="72" rx="16" fill="#fff7ed" stroke="#fb923c" stroke-width="2"/>
+  <text x="303" y="425" text-anchor="middle" class="node-title">WAIT</text>
+  <text x="303" y="447" text-anchor="middle" class="node-sub">记录恢复条件</text>
+  <text x="303" y="462" text-anchor="middle" class="small">释放沙箱，不轮询</text>
+
+  <path d="M303 468 V516 H78 V350" fill="none" stroke="#7c3aed" stroke-width="1.8" marker-end="url(#arrow-blue)"/>
+  <rect x="154" y="505" width="98" height="20" rx="6" fill="#f8fafc" opacity="0.96"/>
+  <text x="203" y="519" text-anchor="middle" class="small" fill="#7c3aed">新事件恢复原 Session</text>
+
+  <path d="M898 338 H884 V448 H836" fill="none" stroke="#dc2626" stroke-width="2" marker-end="url(#arrow-stop)"/>
+  <rect x="846" y="424" width="26" height="18" rx="5" fill="#f8fafc" opacity="0.96"/>
+  <text x="859" y="437" text-anchor="middle" class="label" fill="#dc2626">失败</text>
+  <rect x="646" y="414" width="190" height="70" rx="16" fill="#fef2f2" stroke="#f87171" stroke-width="2"/>
+  <text x="741" y="441" text-anchor="middle" class="node-title">返工 / 等待 / 阻塞</text>
+  <text x="741" y="463" text-anchor="middle" class="node-sub">准确报告，不说“已完成”</text>
+  <path d="M646 449 H620 V350" fill="none" stroke="#dc2626" stroke-width="1.8" marker-end="url(#arrow-stop)"/>
+
+  <rect x="50" y="550" width="1100" height="222" rx="20" fill="#ffffff" stroke="#bbf7d0" stroke-width="1.5" stroke-dasharray="7 5"/>
+  <text x="72" y="579" class="section">证据平面 · EVIDENCE PLANE</text>
+  <text x="72" y="600" class="small">每条 doneWhen 绑定至少一种可定位事实；质量分不能覆盖缺失证据。</text>
+
+  <rect x="72" y="624" width="230" height="104" rx="16" fill="#f0fdf4" stroke="#86efac"/>
+  <path d="M94 643 h24 l7 7 v24 h-31 z M118 643 v8 h8" fill="none" stroke="#059669" stroke-width="2" stroke-linejoin="round"/>
+  <text x="140" y="654" class="node-title">文件系统</text>
+  <text x="94" y="684" class="node-sub">路径存在 · 内容匹配</text>
+  <text x="94" y="705" class="node-sub">大小 / sha256 可核验</text>
+
+  <rect x="328" y="624" width="230" height="104" rx="16" fill="#f0fdf4" stroke="#86efac"/>
+  <rect x="350" y="643" width="32" height="25" rx="3" fill="none" stroke="#059669" stroke-width="2"/>
+  <path d="M350 651 h32 M357 647 h2 M363 647 h2" stroke="#059669" stroke-width="1.5" stroke-linecap="round"/>
+  <text x="396" y="654" class="node-title">Workspace / Artifact</text>
+  <text x="350" y="684" class="node-sub">Definition / manifest 有效</text>
+  <text x="350" y="705" class="node-sub">声明产物逐项存在</text>
+
+  <rect x="584" y="624" width="230" height="104" rx="16" fill="#f0fdf4" stroke="#86efac"/>
+  <circle cx="610" cy="656" r="14" fill="none" stroke="#059669" stroke-width="2"/>
+  <path d="M603 656 l5 5 l10 -12" fill="none" stroke="#059669" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+  <text x="636" y="654" class="node-title">Receipt + Readback</text>
+  <text x="606" y="684" class="node-sub">Intent / Attempt / Verification</text>
+  <text x="606" y="705" class="node-sub">平台独立回读可见</text>
+
+  <rect x="840" y="624" width="230" height="104" rx="16" fill="#f0fdf4" stroke="#86efac"/>
+  <circle cx="866" cy="652" r="9" fill="none" stroke="#059669" stroke-width="2"/>
+  <path d="M850 672 c2 -11 30 -11 32 0" fill="none" stroke="#059669" stroke-width="2" stroke-linecap="round"/>
+  <text x="896" y="654" class="node-title">人工确认 / 审批</text>
+  <text x="862" y="684" class="node-sub">明确接受或业务状态变更</text>
+  <text x="862" y="705" class="node-sub">未确认时保持 verifying</text>
+
+  <path d="M187 624 V606 H1168 V325 H1150" fill="none" stroke="#059669" stroke-width="1.8" marker-end="url(#arrow-green)"/>
+  <path d="M443 624 V606" fill="none" stroke="#059669" stroke-width="1.8"/>
+  <path d="M699 624 V606" fill="none" stroke="#059669" stroke-width="1.8"/>
+  <path d="M955 624 V606" fill="none" stroke="#059669" stroke-width="1.8"/>
+  <rect x="1006" y="590" width="82" height="20" rx="6" fill="#ffffff" opacity="0.96"/>
+  <text x="1047" y="604" text-anchor="middle" class="small" fill="#059669">证据汇入 Gate</text>
+
+  <line x1="72" y1="805" x2="106" y2="805" stroke="#2563eb" stroke-width="2.2" marker-end="url(#arrow-blue)"/>
+  <text x="116" y="809" class="small">主流程</text>
+  <line x1="198" y1="805" x2="232" y2="805" stroke="#ea580c" stroke-width="2" marker-end="url(#arrow-orange)"/>
+  <text x="242" y="809" class="small">条件 / 控制</text>
+  <line x1="354" y1="805" x2="388" y2="805" stroke="#059669" stroke-width="2" marker-end="url(#arrow-green)"/>
+  <text x="398" y="809" class="small">独立证据</text>
+  <line x1="500" y1="805" x2="534" y2="805" stroke="#dc2626" stroke-width="2" marker-end="url(#arrow-stop)"/>
+  <text x="544" y="809" class="small">闸门失败 / 返回</text>
+  <text x="1128" y="809" text-anchor="end" class="small">Skill 劝 · CLI 拦 · DWS 做</text>
+</svg>

package/docs/schemas/agent-audit-load-evidence.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/D1-2004/dingtalk-agent/docs/schemas/agent-audit-load-evidence.schema.json",
+  "title": "dingtalk-agent Agent Audit Load Evidence",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["$schema", "targetHash", "reportPath", "reportHash"],
+  "properties": {
+    "$schema": { "const": "dingtalk-agent/agent-audit-load-evidence@1" },
+    "targetHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "reportPath": { "type": "string", "minLength": 1 },
+    "reportHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+  }
+}

package/docs/schemas/agent-audit.schema.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/D1-2004/dingtalk-agent/docs/schemas/agent-audit.schema.json",
+  "title": "dingtalk-agent Agent Audit Report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "$schema", "status", "ready", "sideEffect", "dingtalkSideEffect", "root",
+    "bindings", "definition", "storageMode", "requiredSkills", "checks", "missing",
+    "repairs", "verification"
+  ],
+  "properties": {
+    "$schema": { "const": "dingtalk-agent/agent-audit@1" },
+    "status": { "enum": ["ready", "partial"] },
+    "ready": { "type": "boolean" },
+    "sideEffect": { "enum": [false, "local-opencode-eval"] },
+    "dingtalkSideEffect": { "const": false },
+    "root": { "type": "string", "minLength": 1 },
+    "bindings": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["path", "hash"],
+          "properties": {
+            "path": { "type": "string" },
+            "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+          }
+        }
+      ]
+    },
+    "definition": { "type": "object" },
+    "storageMode": { "enum": ["local", "remote", "mixed"] },
+    "requiredSkills": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "checks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "surface", "level", "blocking", "summary", "evidence"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "surface": { "enum": ["definition", "skills", "storage", "authority", "host", "load"] },
+          "level": { "enum": ["pass", "warn", "fail"] },
+          "blocking": { "type": "boolean" },
+          "summary": { "type": "string", "minLength": 1 },
+          "evidence": { "type": "object" }
+        }
+      }
+    },
+    "missing": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "repairs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "why", "actions"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "why": { "type": "string", "minLength": 1 },
+          "actions": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string", "minLength": 1 }
+          }
+        }
+      }
+    },
+    "verification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["loadReport", "remoteReport", "commands"],
+      "properties": {
+        "loadReport": { "type": "string" },
+        "remoteReport": { "type": "string" },
+        "commands": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/docs/schemas/agent-bindings.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/D1-2004/dingtalk-agent/docs/schemas/agent-bindings.schema.json",
+  "title": "dingtalk-agent Agent Bindings",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "$schema",
+    "agent",
+    "skills",
+    "memory",
+    "knowledge",
+    "artifacts",
+    "stateDir",
+    "authority"
+  ],
+  "properties": {
+    "$schema": { "const": "dingtalk-agent/agent-bindings@1" },
+    "agent": {
+      "type": "string",
+      "pattern": "^local-dir:.+$"
+    },
+    "skills": {
+      "type": "string",
+      "pattern": "^(local-dir|local-md):.+$"
+    },
+    "memory": {
+      "type": "string",
+      "pattern": "^(local-md|dingtalk-doc):.+$"
+    },
+    "knowledge": {
+      "type": "string",
+      "pattern": "^(local-md|dingtalk-doc):.+$"
+    },
+    "artifacts": {
+      "type": "string",
+      "pattern": "^local-dir:.+$"
+    },
+    "stateDir": {
+      "type": "string",
+      "minLength": 1,
+      "not": { "pattern": "^[A-Za-z][A-Za-z0-9-]*:" }
+    },
+    "authority": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["profile", "expectedUserId"],
+      "properties": {
+        "profile": { "type": "string" },
+        "expectedUserId": { "type": "string" }
+      }
+    }
+  }
+}

package/docs/schemas/agent-definition.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://dingtalk-agent.dev/schemas/agent-definition.schema.json",
+  "title": "dingtalk-agent AgentDefinition",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["$schema", "id", "source", "body", "skills", "storage", "authority", "configuration", "status", "missing", "hash"],
+  "properties": {
+    "$schema": { "const": "dingtalk-agent/agent-definition@1" },
+    "id": { "type": "string", "minLength": 1 },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "uri", "revision"],
+      "properties": {
+        "kind": { "enum": ["local-folder", "git-checkout", "dingtalk-doc", "workspace"] },
+        "uri": { "type": "string", "minLength": 1 },
+        "revision": { "type": "string" }
+      }
+    },
+    "body": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["path", "hash"],
+          "properties": {
+            "path": { "type": "string", "minLength": 1 },
+            "hash": { "type": "string", "minLength": 1 }
+          }
+        }
+      ]
+    },
+    "skills": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "version", "source", "path", "hash"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "version": { "type": "string" },
+          "source": { "type": "string" },
+          "path": { "type": "string" },
+          "hash": { "type": "string" }
+        }
+      }
+    },
+    "storage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["memory", "knowledge", "artifacts", "state"],
+      "properties": {
+        "memory": { "type": "string" },
+        "knowledge": { "type": "string" },
+        "artifacts": { "type": "string" },
+        "state": { "type": "string" }
+      }
+    },
+    "authority": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["dwsProfile", "expectedUserId"],
+      "properties": {
+        "dwsProfile": { "type": "string" },
+        "expectedUserId": { "type": "string" }
+      }
+    },
+    "configuration": {
+      "type": "object",
+      "additionalProperties": { "enum": ["explicit", "context", "environment", "workspace", "convention"] }
+    },
+    "status": { "enum": ["ready", "partial"] },
+    "missing": { "type": "array", "items": { "type": "string" } },
+    "hash": { "type": "string", "minLength": 1 }
+  }
+}

package/docs/schemas/agent-enhancement-plan.schema.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/D1-2004/dingtalk-agent/docs/schemas/agent-enhancement-plan.schema.json",
+  "title": "dingtalk-agent Agent Enhancement Plan",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "$schema", "planId", "ready", "status", "sideEffect", "dingtalkSideEffect",
+    "triggerSideEffect", "root", "source", "projectName", "roleSkills", "bindings",
+    "baselineHash", "desiredHash", "operations", "blockers", "warnings",
+    "semanticReview", "apply", "verification"
+  ],
+  "properties": {
+    "$schema": { "const": "dingtalk-agent/agent-enhancement-plan@1" },
+    "planId": { "type": "string", "pattern": "^aep_[a-f0-9]{32}$" },
+    "ready": { "type": "boolean" },
+    "status": { "enum": ["ready", "blocked"] },
+    "sideEffect": { "const": false },
+    "dingtalkSideEffect": { "const": false },
+    "triggerSideEffect": { "const": false },
+    "root": { "type": "string", "minLength": 1 },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "revision"],
+      "properties": {
+        "kind": { "enum": ["git-checkout", "local-folder"] },
+        "revision": { "type": "string" }
+      }
+    },
+    "projectName": { "type": "string" },
+    "roleSkills": {
+      "type": "array", "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "bindings": { "type": "string", "minLength": 1 },
+    "baselineHash": { "$ref": "#/$defs/hash" },
+    "desiredHash": { "$ref": "#/$defs/hash" },
+    "operations": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/operation" }
+    },
+    "blockers": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+    "warnings": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+    "semanticReview": {
+      "type": "object", "additionalProperties": false,
+      "required": ["required", "files", "why"],
+      "properties": {
+        "required": { "type": "boolean" },
+        "files": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+        "why": { "type": "string", "minLength": 1 }
+      }
+    },
+    "apply": {
+      "type": "object", "additionalProperties": false,
+      "required": ["command", "requiresCurrentPlanId"],
+      "properties": {
+        "command": { "type": "string", "minLength": 1 },
+        "requiresCurrentPlanId": { "const": true }
+      }
+    },
+    "verification": {
+      "type": "object", "additionalProperties": false,
+      "required": ["commands"],
+      "properties": {
+        "commands": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }
+      }
+    }
+  },
+  "$defs": {
+    "name": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$" },
+    "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "hashOrEmpty": { "type": "string", "pattern": "^(?:[a-f0-9]{64})?$" },
+    "operation": {
+      "type": "object", "additionalProperties": false,
+      "required": ["id", "kind", "path", "beforeHash", "afterHash", "backupRequired", "reason"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "kind": { "enum": ["create-file", "update-file", "create-directory", "replace-directory", "preserve"] },
+        "path": { "type": "string", "minLength": 1 },
+        "beforeHash": { "$ref": "#/$defs/hashOrEmpty" },
+        "afterHash": { "$ref": "#/$defs/hash" },
+        "backupRequired": { "type": "boolean" },
+        "reason": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/docs/schemas/agent-enhancement-receipt.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/D1-2004/dingtalk-agent/docs/schemas/agent-enhancement-receipt.schema.json",
+  "title": "dingtalk-agent Agent Enhancement Receipt",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "$schema", "status", "operationId", "planId", "sideEffect", "dingtalkSideEffect",
+    "triggerSideEffect", "root", "backupRoot", "idempotent", "changes", "audit"
+  ],
+  "properties": {
+    "$schema": { "const": "dingtalk-agent/agent-enhancement-receipt@1" },
+    "status": { "const": "applied" },
+    "operationId": { "type": "string", "pattern": "^agent_enhance_[0-9]+_[a-f0-9]{8}$" },
+    "planId": { "type": "string", "pattern": "^aep_[a-f0-9]{32}$" },
+    "sideEffect": { "const": "local-files-only" },
+    "dingtalkSideEffect": { "const": false },
+    "triggerSideEffect": { "const": false },
+    "root": { "type": "string", "minLength": 1 },
+    "backupRoot": { "type": "string" },
+    "idempotent": { "type": "boolean" },
+    "changes": {
+      "type": "array",
+      "items": { "$ref": "agent-enhancement-plan.schema.json#/$defs/operation" }
+    },
+    "audit": {
+      "type": "object", "additionalProperties": false,
+      "required": ["status", "ready", "missing", "commands"],
+      "properties": {
+        "status": { "enum": ["ready", "partial"] },
+        "ready": { "type": "boolean" },
+        "missing": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+        "commands": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      }
+    }
+  }
+}

package/docs/schemas/enriched-invocation.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://dingtalk-agent.dev/schemas/enriched-invocation.schema.json",
+  "title": "EnrichedInvocation",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["$schema", "invocation", "message", "enrichments", "missing", "hash"],
+  "properties": {
+    "$schema": { "const": "dingtalk-agent/enriched-invocation@1" },
+    "invocation": { "type": "object" },
+    "message": {
+      "type": "object",
+      "required": ["originalText", "effectiveText"],
+      "properties": {
+        "originalText": { "type": "string" },
+        "effectiveText": { "type": "string" }
+      }
+    },
+    "enrichments": {
+      "type": "object",
+      "required": ["quote", "burst", "identity"],
+      "properties": {
+        "quote": { "$ref": "#/$defs/item" },
+        "burst": { "$ref": "#/$defs/item" },
+        "identity": { "$ref": "#/$defs/item" }
+      }
+    },
+    "missing": { "type": "array", "items": { "type": "string" } },
+    "hash": { "type": "string" }
+  },
+  "$defs": {
+    "item": {
+      "type": "object",
+      "required": ["status", "source", "fetchedAt", "confidence", "truncated", "reason", "data"],
+      "properties": {
+        "status": { "enum": ["available", "missing", "rejected"] },
+        "source": { "type": "string" },
+        "fetchedAt": { "type": ["string", "null"] },
+        "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+        "truncated": { "type": "boolean" },
+        "reason": { "type": "string" },
+        "data": { "type": ["object", "null"] }
+      }
+    }
+  }
+}