@my-life-buddies/cli 0.10.0 → 0.13.0

package/dist/web/app.css

@@ -513,3 +513,41 @@
     *, *::before, *::after { animation-duration: 120ms !important; animation-iteration-count: 1 !important; transition-duration: 120ms !important; }
   }
 }
+
+.message-avatar img { width: 100%; height: 100%; object-fit: contain; border-radius: inherit; }
+#buddy-profile-avatar { width: 32px; height: 32px; object-fit: contain; border-radius: 50%; }
+#buddy-profile-avatar[hidden] { display: none; }
+
+/* The hosted console keeps debugger and simulator side by side, including narrow panels. */
+body[data-hosted-preview] { min-width:700px; height:100dvh; min-height:0; display:flex; flex-direction:column; overflow-x:auto; overflow-y:hidden; }
+body[data-hosted-preview] .brand { display:none; }
+body[data-hosted-preview] .app-shell { flex:1; min-height:0; display:flex; flex-direction:column; }
+body[data-hosted-preview] .sidebar { position:static; flex:none; width:auto; padding:8px 16px; border-inline-end:0; border-bottom:1px solid var(--color-rule); }
+body[data-hosted-preview] .sidebar-section { margin:0; }
+body[data-hosted-preview] .sidebar-label { display:none; }
+body[data-hosted-preview] .debug-tabs { display:flex; flex-wrap:wrap; gap:8px; }
+body[data-hosted-preview] .debug-tabs button { width:auto; }
+body[data-hosted-preview] .application { margin-inline-start:0; flex:1; min-height:0; display:flex; flex-direction:column; }
+body[data-hosted-preview] .topbar { display:contents; }
+body[data-hosted-preview] .project-heading { display:none; }
+body[data-hosted-preview] .debugger > .sidebar { position:sticky; top:0; z-index:var(--z-sticky); }
+body[data-hosted-preview] .workspace { flex:1; min-height:0; grid-template-columns:minmax(340px,1fr) clamp(340px,40%,520px); overflow:hidden; }
+body[data-hosted-preview] .debugger { overflow-y:auto; overscroll-behavior:contain; }
+body[data-hosted-preview] .simulator-area { position:relative; inset:auto; height:100%; min-height:0; max-height:none; border-block-start:0; border-inline-start:1px solid var(--color-rule); }
+body[data-hosted-preview] .run-strip { padding:20px 24px 0; }
+body[data-hosted-preview] .run-metrics { margin-top:20px; }
+body[data-hosted-preview] .debug-panel { padding:24px; }
+body[data-hosted-preview] #dev-control[data-action="stop"] { background:var(--color-paper-raised); color:var(--color-ink); border:1px solid var(--color-rule); }
+.local-connection { flex:none; padding:10px 20px; border-bottom:1px solid var(--color-rule); background:var(--color-paper-raised); font-size:13px; }
+.local-connection-heading { display:grid; grid-template-columns:minmax(0,1fr) auto; align-items:center; gap:8px 12px; }
+.local-connection-heading strong { grid-column:1 / -1; min-width:0; overflow-wrap:anywhere; font-size:12px; font-weight:500; }
+.local-connection pre { padding:14px; border-radius:8px; background:var(--color-paper); white-space:pre-wrap; overflow-wrap:anywhere; user-select:all; }
+.local-connection p { line-height:1.7; }
+#connect-instructions { max-height:250px; overflow-y:auto; }
+@media (max-width:900px) {
+  body[data-hosted-preview] .workspace { grid-template-columns:minmax(340px,1fr) 320px; }
+  body[data-hosted-preview] .run-heading { flex-direction:column; gap:12px; }
+  body[data-hosted-preview] .run-identity, body[data-hosted-preview] .run-controls { flex:auto; width:100%; }
+  body[data-hosted-preview] .run-strip, body[data-hosted-preview] .debug-panel { padding-inline:16px; }
+  body[data-hosted-preview] .run-metrics { gap:8px; }
+}

package/dist/web/app.js

@@ -1,6 +1,17 @@
 (() => {
   "use strict";
 
+  const hosted = document.body?.hasAttribute?.("data-hosted-preview") === true;
+  const hostedBuddyId = hosted ? new URL(location.href).searchParams.get("buddyId") : "";
+  const connectionUrl = hosted ? new URL(`../api/buddies/${encodeURIComponent(hostedBuddyId)}/preview`, location.href) : undefined;
+  let connectionInstance = "", connectionReady = !hosted, connectionBusy = false, devPollBusy = false;
+  function previewApiUrl(path) {
+    if (!hosted) return path;
+    const url = new URL(connectionUrl.href + path);
+    url.searchParams.set("instance", connectionInstance);
+    return url.href;
+  }
+  window.previewApiUrl = previewApiUrl;
   const $ = (selector) => document.querySelector(selector);
   const elements = {
     projectName: $("#project-name"),
@@ -88,7 +99,8 @@
   }
 
   async function api(path, options = {}) {
-    const response = await fetch(path, {
+    const instance = connectionInstance;
+    const response = await fetch(previewApiUrl(path), {
       ...options,
       headers: {
         Accept: "application/json",
@@ -97,8 +109,9 @@
       },
     });
     const value = await response.json().catch(() => ({}));
+    if (hosted && (!connectionReady || instance !== connectionInstance)) throw new Error("本地连接已改变，请等待重新连接");
     if (!response.ok) {
-      const error = new Error(value?.error?.message || `请求失败（HTTP ${response.status}）`);
+      const error = new Error((typeof value?.error === "string" ? value.error : value?.error?.message) || `请求失败（HTTP ${response.status}）`);
       error.code = value?.error?.code || "PREVIEW_REQUEST_FAILED";
       error.status = response.status;
       throw error;
@@ -159,15 +172,23 @@
       class: `message-avatar ${role === "user" ? "person-avatar" : "buddy-message-avatar"}`,
       "aria-hidden": "true",
     });
-    if (role !== "user") avatar.textContent = "搭";
+    if (role !== "user") {
+      const picture = (state.dev.ready?.buddy || state.buddy)?.avatarPreview;
+      if (picture) {
+        const image = node("img", {src: picture, alt: ""});
+        image.addEventListener("error", () => { avatar.textContent = "搭"; }, {once: true});
+        avatar.append(image);
+      } else avatar.textContent = "搭";
+    }
     return avatar;
   }
 
   function phaseCopy(phase) {
     return {
-      idle: "未启动",
+      idle: hosted ? "已连接但 DEV 未启动" : "未启动",
+      disconnected: "未连接本地工程",
       starting: "正在启动",
-      ready: "DEV 在线",
+      ready: "DEV 运行中",
       stopping: "正在停止",
       failed: "启动失败",
     }[phase] || phase;
@@ -207,6 +228,12 @@
     elements.projectName.textContent = name;
     elements.buddyName.textContent = name;
     elements.buddyName.title = buddy?.tagline || "";
+    const picture = document.querySelector("#buddy-profile-avatar");
+    if (picture) {
+      picture.hidden = !buddy?.avatarPreview;
+      if (buddy?.avatarPreview) picture.src = buddy.avatarPreview;
+      else picture.removeAttribute("src");
+    }
     const note = document.querySelector(".preview-note");
     if (note) note.textContent = buddy ? (buddy.isDev ? "开发预览版 · 仅你可见" : "搭搭 App") : "搭搭 App · DEV";
     elements.environmentRuntime.textContent = "Node.js · Buddy Runtime";
@@ -217,11 +244,11 @@
   let pairingRequest = 0;
 
   function renderDev() {
-    const phase = state.dev.phase;
+    const phase = connectionReady ? state.dev.phase : "disconnected";
     if (!elements.pairingPanel.hidden && pairingRevision !== state.dev.revision) void togglePairing(true);
     elements.connectionState.dataset.phase = phase;
-    elements.connectionLabel.textContent = phaseCopy(phase);
-    elements.devControl.disabled = phase === "starting" || phase === "stopping";
+    elements.connectionLabel.textContent = phase === "disconnected" ? "未连接本地工程" : phaseCopy(phase);
+    elements.devControl.disabled = !connectionReady || phase === "starting" || phase === "stopping";
     elements.devControl.dataset.action = phase === "ready" ? "stop" : "start";
     elements.devControl.textContent = phase === "ready" ? "停止 DEV" : phase === "starting" ? "正在启动…" : phase === "stopping" ? "正在停止…" : "启动 DEV";
     elements.environmentAgent.textContent = phase === "ready"
@@ -525,17 +552,17 @@
   }
 
   function syncPolling() {
-    if (state.dev.phase === "ready" && state.polling === undefined) {
+    if (connectionReady && state.dev.phase === "ready" && state.polling === undefined) {
       void refreshSimulator();
       state.polling = window.setInterval(() => void refreshSimulator(), 1200);
-    } else if (state.dev.phase !== "ready" && state.polling !== undefined) {
+    } else if ((!connectionReady || state.dev.phase !== "ready") && state.polling !== undefined) {
       window.clearInterval(state.polling);
       state.polling = undefined;
     }
   }
 
   async function controlDev() {
-    if (state.dev.phase === "starting" || state.dev.phase === "stopping") return;
+    if (!connectionReady || state.dev.phase === "starting" || state.dev.phase === "stopping") return;
     elements.devControl.disabled = true;
     try {
       const path = state.dev.phase === "ready" ? "/api/dev/stop" : "/api/dev/start";
@@ -725,6 +752,7 @@
   }
 
   async function boot() {
+    if (hosted && !connectionReady) { void refreshConnection(); return; }
     try {
       const [project, dev, debug] = await Promise.all([
         api("/api/project"),
@@ -735,7 +763,7 @@
       state.dev = dev.state;
       state.debug = debug.debug;
       renderAll();
-      connectEvents();
+      if (!hosted) connectEvents();
       // Load the cloud profile independently of Agent startup. If it fails,
       // the local project and DEV controls remain usable and show the error.
       const { buddy } = await api("/api/buddy");
@@ -746,6 +774,69 @@
     }
   }
 
+  function disconnected(message = "未连接本地工程") {
+    connectionReady = false;
+    state.dev = { phase: "idle", revision: -1 };
+    state.simulatorRequest++;
+    widgets?.reset();
+    void togglePairing(false);
+    renderDev(); syncPolling();
+    $("#local-status").textContent = message;
+  }
+
+  async function refreshConnection() {
+    if (connectionBusy) return;
+    connectionBusy = true;
+    try {
+      const response = await fetch(connectionUrl, { signal: AbortSignal.timeout(5000) });
+      const value = await response.json();
+      if (!response.ok) throw new Error(value.error || "连接状态读取失败");
+      $("#connect-command").textContent = value.command;
+      $("#copy-connect-command").disabled = false;
+      if (!value.connected) { disconnected(); return; }
+      const changed = connectionInstance !== value.instanceId;
+      const newlyConnected = !connectionReady || changed;
+      connectionInstance = value.instanceId;
+      connectionReady = true;
+      $("#local-status").textContent = ["已连接本地工程", value.machineName, value.projectRoot].filter(Boolean).join(" · ");
+      if (newlyConnected) {
+        state.dev = { phase: "idle", revision: -1 };
+        if (changed) {
+          state.simulator = { messages: [] }; state.debug = { runs: [], events: [], messages: [] };
+          state.selectedRunId = ""; pendingSend = undefined; state.buddy = undefined;
+        }
+        elements.errorBanner.hidden = true;
+        await boot();
+      }
+    } catch (cause) { disconnected(cause.message || "连接已中断，正在重试…"); }
+    finally { connectionBusy = false; }
+  }
+
+  async function pollHostedDev() {
+    if (!connectionReady || devPollBusy) return;
+    devPollBusy = true;
+    try {
+      const [dev, debug] = await Promise.all([api("/api/dev"), api("/api/debug")]);
+      applyDevState(dev.state); state.debug = debug.debug; renderAll();
+    } catch (cause) { showError(cause); }
+    finally { devPollBusy = false; }
+  }
+
+  if (hosted) {
+    renderDev();
+    $("#get-connect-command").addEventListener("click", () => {
+      $("#connect-instructions").hidden = !$("#connect-instructions").hidden;
+      void refreshConnection();
+    });
+    $("#copy-connect-command").addEventListener("click", async () => {
+      try { await navigator.clipboard.writeText($("#connect-command").textContent); toast("连接指令已复制，请在当前搭子的工程目录执行"); }
+      catch { showError(new Error("请手动复制下方的完整连接指令")); }
+    });
+    const statusTimer = window.setInterval(() => void refreshConnection(), 2000);
+    const devTimer = window.setInterval(() => void pollHostedDev(), 1200);
+    window.addEventListener("pagehide", () => { window.clearInterval(statusTimer); window.clearInterval(devTimer); window.clearInterval(state.polling); });
+  }
+
   elements.resetConversation.addEventListener("click", () => void resetConversation());
   elements.latestMessages.addEventListener("click", followLatestMessages);
   elements.chatMessages.addEventListener("scroll", () => {

package/dist/web/index.html

@@ -197,7 +197,7 @@
                   <button class="back-chevron" type="button" aria-label="返回（预览中不可用）" disabled>
                     <svg aria-hidden="true" viewBox="0 0 24 24"><path d="m15 18-6-6 6-6"/></svg>
                   </button>
-                  <div class="buddy-identity"><h3 id="buddy-name">我的搭子</h3><p id="buddy-status" class="sr-only">DEV 未连接</p></div>
+                  <img id="buddy-profile-avatar" alt="搭子头像" hidden><div class="buddy-identity"><h3 id="buddy-name">我的搭子</h3><p id="buddy-status" class="sr-only">DEV 未连接</p></div>
                   <div class="chat-navigation-actions" aria-hidden="true">
                     <button class="chat-more" type="button" aria-label="更多（预览中不可用）" disabled tabindex="-1">
                       <svg viewBox="0 0 24 24"><circle cx="5" cy="12" r="1.3"/><circle cx="12" cy="12" r="1.3"/><circle cx="19" cy="12" r="1.3"/></svg>

package/dist/web/widgets.js

@@ -1,5 +1,6 @@
 /* Client reference: my-life-buddies-ios dev 547818d, DadaConversationWidgets / DadaHostedWidgetPage. */
 (() => {
+  const previewUrl = path => window.previewApiUrl?.(path) ?? path;
   const el = (tag, className, text) => { const n = document.createElement(tag); n.className = className; if (text !== undefined) n.textContent = text; return n; };
   window.createSimulatorWidgets = ({ api, avatar }) => {
     const shortcut = document.querySelector('#widget-shortcut');
@@ -30,7 +31,7 @@
         for (const item of items) { const b = button(item.title + ' ›', () => { choices.remove(); pill.setAttribute('aria-expanded', 'false'); void open(item); }); b.setAttribute('role', 'menuitem'); choices.append(b); }
         shortcut.append(choices); pill.setAttribute('aria-expanded', 'true'); choices.firstChild?.focus();
       }, 'widget-pill');
-      const image = avatar(); image.textContent = ''; image.classList.add('widget-pill-avatar');
+      const image = avatar(); image.classList.add('widget-pill-avatar');
       pill.append(image, el('span', 'widget-pill-title', items.length === 1 ? items[0].title : '全部小挂件'));
       if (items.length > 1) { pill.append(el('span', 'widget-chevron', '⌄')); pill.setAttribute('aria-haspopup', 'menu'); pill.setAttribute('aria-expanded', 'false'); }
       shortcut.append(pill);
@@ -77,7 +78,7 @@
       for (const child of phone.children) if (child !== overlay) child.inert = true;
       dismiss.focus();
       try {
-        const url = `/api/simulator/widgets/${encodeURIComponent(item.id)}`;
+        const url = previewUrl(`/api/simulator/widgets/${encodeURIComponent(item.id)}`);
         // Probe errors in the parent; actual HTML executes only inside the opaque sandbox document.
         const response = await fetch(url, { credentials: 'same-origin' });
         if (!response.ok) { const error = await response.json(); throw new Error(error.error?.message || error.error || '小挂件暂时无法打开'); }
@@ -117,7 +118,7 @@
       card(item) {
         const card = el('div', 'widget-entry'); card.append(el('h4', '', item.title));
         const details = el('div', 'widget-entry-details');
-        if (item.type && item.imageMediaId) { const image = el('img', 'widget-entry-photo'); image.alt = `${item.title}的照片`; image.src = `/api/simulator/widgets/${encodeURIComponent(item.id)}/image?mediaId=${encodeURIComponent(item.imageMediaId)}`; image.addEventListener('error', () => { image.hidden = true; }); details.append(image); }
+        if (item.type && item.imageMediaId) { const image = el('img', 'widget-entry-photo'); image.alt = `${item.title}的照片`; image.src = previewUrl(`/api/simulator/widgets/${encodeURIComponent(item.id)}/image?mediaId=${encodeURIComponent(item.imageMediaId)}`); image.addEventListener('error', () => { image.hidden = true; }); details.append(image); }
         details.append(el('p', '', item.type ? item.summary?.trim() || '打开查看最新内容' : '此小挂件已删除或不可用')); card.append(details);
         if (item.type) card.append(button('去查看', () => open(item), 'widget-entry-open'));
         return card;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@my-life-buddies/cli",
-  "version": "0.10.0",
+  "version": "0.13.0",
   "type": "module",
   "description": "搭搭 Developer Platform 命令行工具",
   "publishConfig": {
@@ -39,7 +39,7 @@
     "ws": "8.21.3"
   },
   "devDependencies": {
-    "@buddy/cli-core": "0.10.0",
-    "@buddy/preview": "0.10.0"
+    "@buddy/cli-core": "0.13.0",
+    "@buddy/preview": "0.13.0"
   }
 }

package/resources/dada-object-avatar/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: dada-object-avatar
+description: "Generate or revise Dada-style retro object avatars from a companion name and Emoji. Use when the user wants the current unified object-character system: recognizable semantic object, varied coordinated eyes, two lateral three-digit hands, restrained retro material, circular-crop-safe composition, and a genuine transparent PNG."
+---
+
+# 搭搭复古物件头像
+
+把搭子名字与 Emoji 转译成一个可辨认的物件角色。保留“人”的眼神与姿态，同时避免真人头像和写实动物身体。
+
+## Workflow
+
+1. Read [references/style-system.md](references/style-system.md). Treat its invariants as the current accepted style.
+2. For a new subject, read [references/subject-design.md](references/subject-design.md) and choose one primary object plus at most two identity details.
+3. Before generation, allocate the character's shared gaze direction with `python3 scripts/choose_gaze.py --recent <directions>`. Pass recent gallery directions so neighboring characters do not repeat.
+4. Read [references/prompt-template.md](references/prompt-template.md), fill the subject, palette, gaze and detail hierarchy fields, then invoke the built-in image generation tool. Use the closest retained asset from `assets/examples/` as the style reference. For revisions, also include the exact previous subject image as the first reference and state which properties must remain locked.
+5. Inspect the result on both light and dark backgrounds and inside a centered circular crop. Confirm recognizable identity, coordinated gaze, hand anatomy, detail spacing and continuous body volume.
+6. Deliver a genuine RGBA PNG. Run `python3 scripts/validate_png.py <image.png>` after any matte removal or alpha reconstruction. A checkerboard drawn into RGB pixels is not transparency.
+7. When the user gives feedback, record the concrete trigger, failure and accepted correction with `python3 scripts/record_example.py ...`. Use [references/training-record.schema.json](references/training-record.schema.json) as the stable training format.
+
+For later style training and promotion of new canonical examples, follow [references/training-guide.md](references/training-guide.md).
+
+## Generation invariants
+
+- One square image contains one character. The central body continues naturally through the bottom edge; the top retains transparent breathing room.
+- The semantic object remains legible at avatar size. Do not replace it with an unrelated blob or generic person.
+- Volume comes from continuous geometry, overlap, structural turns and plausible attachment. Lighting only explains the geometry. Do not add seams to simulate thickness.
+- Use ivory embedded eye whites and black pupils. Both whites and pupils vary in size, aspect ratio, tilt and local position. Assign one shared gaze vector per character; neighboring characters use different directions.
+- Add exactly two small lateral hands below eye level. Each hand has exactly three digits total: one broad thumb and two smaller fingers.
+- Nearby handles, lugs, clasps, symbols and ornaments remain secondary. If near a hand, make them roughly 60–75% of hand width and separate them vertically by at least half a hand height.
+- No eyebrows, mouth or nose by default. No legs or feet. No realistic anatomy, dirty texture, dense skin grain, text or watermark.
+- Use genuine transparency around the silhouette and through real openings. Eye whites and subject remain opaque.
+
+## Iteration boundary
+
+Lock accepted properties. If feedback concerns only gaze, edit only the eyes. If it concerns volume, keep silhouette, identity details and proportions unless the user explicitly requests a redesign. Generate one corrected candidate per subject before expanding the family.
+
+For scoring or dataset curation, read [references/evaluation-rubric.md](references/evaluation-rubric.md).

package/resources/dada-object-avatar/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "搭搭复古物件头像"
+  short_description: "生成带随机协调眼神、三指侧手和透明背景的复古物件头像"
+  default_prompt: "使用 $dada-object-avatar 根据名字和 Emoji 生成一张复古物件表情头像。"

package/resources/dada-object-avatar/references/evaluation-rubric.md

@@ -0,0 +1,22 @@
+# Evaluation rubric
+
+Score each category 0–2. Accept only when all hard gates pass and the total is at least 13/16.
+
+| Category | 0 | 1 | 2 |
+|---|---|---|---|
+| Semantic identity | unclear/generic | recognizable with explanation | instantly recognizable at avatar size |
+| Structural volume | flat, seam-based | partial believable depth | continuous plausible solid volume |
+| Eye morphology | mirrored/uniform | one layer varies | whites and pupils both vary |
+| Gaze | crossed/repeated family direction | coordinated but generic | coordinated and distinct from neighbors |
+| Hands | wrong count/anatomy | minor ambiguity | exactly two lateral three-digit hands |
+| Detail hierarchy | crowded/equal scale | acceptable spacing | clear 60–75% secondary scale and separation |
+| Circular framing | clipped/blank bottom | usable | safe details and natural 6-o'clock fill |
+| Material/color | dirty or wrong association | acceptable | restrained texture and intentional semantics |
+
+Hard gates:
+
+- genuine RGBA transparency;
+- four transparent corners;
+- subject reaches the lower-center band;
+- no checkerboard embedded in output;
+- no extra fingers, legs, mouth, nose, eyebrows, text or watermark.

package/resources/dada-object-avatar/references/examples.json

@@ -0,0 +1,8 @@
+[
+  {"file":"assets/examples/cat.png","subject":"短毛猫铲屎官","gaze":"right","role":"seamless animal-object volume, thin ears, prop interaction"},
+  {"file":"assets/examples/cooking.png","subject":"小涂阿姨","gaze":"lower-left","role":"small high lugs separated from lower hands"},
+  {"file":"assets/examples/relationship.png","subject":"情感专家","gaze":"left","role":"bright coral semantic color and complete heart silhouette"},
+  {"file":"assets/examples/doctor.png","subject":"林医生","gaze":"lower-right","role":"semantic gaze toward a small medical symbol"},
+  {"file":"assets/examples/work.png","subject":"工作那些事","gaze":"left","role":"compact clasps and horizontal gaze"},
+  {"file":"assets/examples/divination.png","subject":"塔罗星人","gaze":"upper-left","role":"secondary ornament and distinct gaze"}
+]

package/resources/dada-object-avatar/references/prompt-template.md

@@ -0,0 +1,27 @@
+# Prompt template
+
+Use the closest accepted example as the style reference. For an edit, make the current subject the first reference.
+
+```text
+Create a square Dada-style retro object avatar for {NAME} {EMOJI}.
+
+SUBJECT
+Use {PRIMARY_OBJECT} as the recognizable primary silhouette. Preserve/add only {DETAIL_1} and {DETAIL_2}. Use {PALETTE} with restrained {MATERIAL}. Avoid {UNWANTED_ASSOCIATION}.
+
+VOLUME
+Build one continuous believable volume with rounded structural turns, overlap and physically plausible attachment. Do not add seams, panel lines or exaggerated highlights to fake thickness.
+
+EYES
+Use embedded warm-ivory eye whites and matte-black pupils. Do not mirror the pair. Make the whites differ by about 8–18% in size/aspect and 4–10 degrees in tilt. Make the pupils differ by about 10–18% in size/aspect and place them differently within their whites. Assign the whole character a coordinated {GAZE_DIRECTION} gaze; both pupils follow that vector without crossing or diverging. This direction must differ from neighboring gallery characters.
+
+HANDS AND DETAILS
+Add exactly two small lateral hands below eye level. Each has exactly three digits total: one broad thumb plus two smaller rounded fingers. Hand width is about 12–15% of body width. Any nearby handle, lug, clasp, symbol or ornament is 60–75% of hand width and at least half a hand-height away. Keep details secondary and unobstructed.
+
+FRAMING
+One character, 1:1. About 88% visual scale. Keep every hand, handle and prop inside a centered circular crop. The central body continues naturally through the bottom edge; no transparent strip or floating base.
+
+OUTPUT
+Genuine RGBA transparent PNG. Alpha 0 outside the silhouette and through real openings. Eye whites and subject remain opaque. No checkerboard, backdrop, floor, external shadow, mouth, nose, eyebrows, legs, feet, text or watermark.
+```
+
+For an eye-only revision, explicitly say: `Preserve every non-eye pixel and change only eye whites, pupils and gaze.` Then specify one direction rather than asking for generic randomness.

package/resources/dada-object-avatar/references/style-system.md

@@ -0,0 +1,54 @@
+# Style system
+
+## 1. Identity
+
+Start from the companion role, not the literal title. Convert it to a familiar object silhouette:
+
+- cooking → rounded enamel pot
+- health/doctor → first-aid case
+- work → briefcase
+- divination → tarot card
+- pet care → simplified cat-shaped object with one litter scoop
+- relationship → complete graphic heart
+- travel → suitcase
+- fitness → kettlebell
+
+Use one dominant silhouette and no more than two secondary identity details. A user-provided mapping overrides this list.
+
+## 2. Shape and volume
+
+Use orderly, softly rounded geometry. Show thickness through front/side relationships, overlap, rim depth and believable attachment. Do not use a decorative center seam, panel line or strong gradient as a substitute for form. Thin structures such as cat ears must stay physically plausible and naturally join the body.
+
+## 3. Materials and color
+
+Use restrained retro resin, enamel, soft metal or leather-like material with sparse fine grain. Prefer warm Memphis-adjacent colors: cream, teal, tomato red, coral, mustard, cocoa, plum and charcoal. Check semantic associations: a heart should use bright coral or tomato red rather than dark liver-like burgundy.
+
+## 4. Eye system
+
+Eye whites are warm ivory and slightly embedded; pupils are matte black.
+
+For each pair:
+
+- white size or aspect difference: approximately 8–18%
+- white tilt difference: approximately 4–10 degrees
+- pupil size or aspect difference: approximately 10–18%
+- pupil local placement: different within each white, but both follow one shared gaze vector
+
+Choose one vector from `front`, `left`, `right`, `upper-left`, `upper-right`, `lower-left`, `lower-right`. Do not repeat the same or near-identical vector on neighboring gallery cards. Do not default the family to upper-right. Both pupils must remain coordinated; avoid crossed or divergent eyes.
+
+## 5. Hands and detail hierarchy
+
+Place one hand on each outer side below eye level. Use very short arms. Each hand has exactly three digits total: one broad thumb, about 1.4 times a small finger, and two rounded smaller fingers. Hand width is about 12–15% of body width. Hands turn slightly sideways; no front-facing open palm.
+
+When a handle, lug, clasp or ornament approaches a hand:
+
+- reduce the detail to roughly 60–75% of hand width;
+- separate it by at least half a hand height;
+- move it to a different vertical zone if crowding remains;
+- preserve recognizability before decoration.
+
+## 6. Framing and alpha
+
+Use a 1:1 master. Target roughly 88% of the prior oversized-object scale. Keep hands, handles and identity props inside a centered circle. The main body passes naturally through the square bottom edge and fills the circle at 6 o'clock. Leave no transparent horizontal strip below the body and no floating base.
+
+Export true RGBA. All four corners should be alpha 0. Real handle openings and enclosed gaps should be transparent. Never render a checkerboard as background pixels.

package/resources/dada-object-avatar/references/subject-design.md

@@ -0,0 +1,23 @@
+# Subject design
+
+Use this decision order for a new companion:
+
+1. **Role verb:** what does this companion help the user do?
+2. **Primary object:** which single object communicates that action fastest at 64 px?
+3. **Identity details:** choose one or two details that disambiguate the object.
+4. **Conflict check:** compare every detail with the hands. Reduce or move any feature with similar size and proximity.
+5. **Palette check:** confirm the color evokes the intended emotion rather than food, anatomy or danger by accident.
+6. **Gaze:** allocate a direction that differs from the neighboring examples and, when useful, points toward a semantic detail.
+
+Keep the primary silhouette stable through revisions. Character variation comes from object shape, palette, eye morphology, gaze and one meaningful pose, rather than extra facial features.
+
+## Existing accepted assignments
+
+| Subject | Primary object | Details | Gaze |
+|---|---|---|---|
+| 短毛猫铲屎官 | cream cat-shaped object | thin ears, coral scoop | toward scoop |
+| 小涂阿姨 | tomato enamel pot | cream lid, small high lugs | attentive inward/downward |
+| 情感专家 | bright coral heart | complete rounded lobes | gentle side glance |
+| 林医生 | cream first-aid case | teal handle/band, coral cross | lower-right toward cross |
+| 工作那些事 | cocoa briefcase | compact handle, small brass clasps | horizontal left |
+| 塔罗星人 | plum tarot card | thin gold border, small crescent | upper-left |

package/resources/dada-object-avatar/references/training-guide.md

@@ -0,0 +1,14 @@
+# Iterative style training
+
+Treat training as controlled prompt-and-reference refinement:
+
+1. Save every candidate prompt and output path.
+2. Record the user's verdict and exact visible failure with `scripts/record_example.py`; avoid vague labels such as “bad style”.
+3. On revision, list the accepted properties that must remain locked and change only the rejected property.
+4. Promote an image to `assets/examples/` only after it passes the rubric and the user accepts the direction.
+5. Add the promoted image to `references/examples.json` with its subject, gaze and the single rule it demonstrates best.
+6. Keep complementary examples. Do not retain several samples that teach the same gaze and silhouette while leaving other cases uncovered.
+7. Before changing a global rule, confirm the same failure appears in more than one subject. Keep one-off feedback in the subject prompt.
+8. Re-run `scripts/validate_png.py` on every retained PNG and forward-test one unseen companion after a global rule change.
+
+A useful JSONL record contains the original prompt, output, verdict, concrete feedback, failure tags, accepted correction and locked properties. This supports later retrieval, preference modeling or manual dataset conversion without mixing rejected and accepted examples.

package/resources/dada-object-avatar/references/training-record.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Dada Object Avatar Training Record",
+  "type": "object",
+  "required": ["timestamp", "subject", "prompt", "output", "verdict"],
+  "properties": {
+    "timestamp": {"type": "string", "format": "date-time"},
+    "subject": {"type": "string"},
+    "emoji": {"type": "string"},
+    "gaze": {"enum": ["front", "left", "right", "upper-left", "upper-right", "lower-left", "lower-right"]},
+    "prompt": {"type": "string"},
+    "output": {"type": "string"},
+    "verdict": {"enum": ["accepted", "rejected", "needs-revision"]},
+    "feedback": {"type": "string"},
+    "failure_tags": {"type": "array", "items": {"type": "string"}},
+    "accepted_correction": {"type": "string"},
+    "locked_properties": {"type": "array", "items": {"type": "string"}}
+  },
+  "additionalProperties": false
+}

package/resources/dada-object-avatar/scripts/choose_gaze.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""Choose a coordinated gaze direction that differs from recent gallery items."""
+import argparse, hashlib, json, math, random
+
+VECTORS = {
+    "front": (0.0, 0.0), "left": (-1.0, 0.0), "right": (1.0, 0.0),
+    "upper-left": (-0.707, -0.707), "upper-right": (0.707, -0.707),
+    "lower-left": (-0.707, 0.707), "lower-right": (0.707, 0.707),
+}
+
+def near(a, b):
+    if a == b: return True
+    if "front" in (a, b): return False
+    ax, ay = VECTORS[a]; bx, by = VECTORS[b]
+    return ax * bx + ay * by > 0.70
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--recent", default="", help="Comma-separated recent directions")
+    ap.add_argument("--seed", default="", help="Optional reproducible seed")
+    args = ap.parse_args()
+    recent = [x.strip() for x in args.recent.split(",") if x.strip()]
+    unknown = [x for x in recent if x not in VECTORS]
+    if unknown: ap.error(f"unknown directions: {', '.join(unknown)}")
+    last = recent[-1] if recent else None
+    candidates = [d for d in VECTORS if not any(near(d, previous) for previous in recent[-3:])]
+    if not candidates: candidates = [d for d in VECTORS if d != last]
+    rng = random.Random(int(hashlib.sha256(args.seed.encode()).hexdigest(), 16) if args.seed else None)
+    direction = rng.choice(candidates)
+    print(json.dumps({
+        "direction": direction,
+        "vector": VECTORS[direction],
+        "prompt": f"Assign one coordinated {direction.upper()} gaze to this character; both pupils follow this vector without crossing or diverging."
+    }, ensure_ascii=False))
+
+if __name__ == "__main__": main()

package/resources/dada-object-avatar/scripts/record_example.py

@@ -0,0 +1,22 @@
+#!/usr/bin/env python3
+"""Append one structured feedback example to a JSONL training log."""
+import argparse, datetime, json
+from pathlib import Path
+
+def split(value): return [x.strip() for x in value.split(',') if x.strip()]
+
+def main():
+    ap=argparse.ArgumentParser()
+    ap.add_argument('--log',required=True); ap.add_argument('--subject',required=True); ap.add_argument('--emoji',default='')
+    ap.add_argument('--gaze',choices=['front','left','right','upper-left','upper-right','lower-left','lower-right'])
+    ap.add_argument('--prompt-file',required=True); ap.add_argument('--output',required=True)
+    ap.add_argument('--verdict',required=True,choices=['accepted','rejected','needs-revision'])
+    ap.add_argument('--feedback',default=''); ap.add_argument('--failure-tags',default=''); ap.add_argument('--accepted-correction',default=''); ap.add_argument('--locked-properties',default='')
+    a=ap.parse_args()
+    record={"timestamp":datetime.datetime.now(datetime.timezone.utc).isoformat(),"subject":a.subject,"emoji":a.emoji,"prompt":Path(a.prompt_file).read_text(),"output":a.output,"verdict":a.verdict,"feedback":a.feedback,"failure_tags":split(a.failure_tags),"accepted_correction":a.accepted_correction,"locked_properties":split(a.locked_properties)}
+    if a.gaze: record['gaze']=a.gaze
+    log=Path(a.log); log.parent.mkdir(parents=True,exist_ok=True)
+    with log.open('a',encoding='utf-8') as f: f.write(json.dumps(record,ensure_ascii=False)+'\n')
+    print(json.dumps(record,ensure_ascii=False,indent=2))
+
+if __name__=='__main__': main()