makaron-persona-look-cli 0.5.3 → 0.5.5

package/README.md

@@ -4,7 +4,7 @@
 
 ## What an Agent gets
 
-`find` is the no-generation delivery route: `--kind persona` returns matched Persona library images, and `--kind look` returns matched Look library images. `--count N` returns exactly N different references or `BLOCKED`; it does not expose IDs or selection metadata. `preview` downloads the selected Persona source/approved auxiliary views and the Look source, plus a safe `selection.json` render brief. It is intentionally a **source-reference pack**, not a synthesized image. `render` is the combined Persona + Look delivery route: it creates a locked selection for each requested result, sends those private inputs to the caller's authenticated Makaron CLI, and writes one full-body front/right-side/back turnaround sheet per selection. The Persona is the only identity reference; the Look image's face is excluded.
+`find` is the no-generation delivery route: `--kind persona` returns matched Persona library images, and `--kind look` returns matched Look library images. `--count N` (default `1`) returns exactly N different references or `BLOCKED`; `--exclude ID[,ID...]` omits prior internal selections, including records that share their source image. It does not expose IDs or selection metadata to the end user. `preview` downloads the selected Persona source/approved auxiliary views and the Look source, plus a safe `selection.json` render brief. It is intentionally a **source-reference pack**, not a synthesized image. `render` is the combined Persona + Look delivery route: it creates a locked selection for each requested result, sends those private inputs to the caller's authenticated Makaron CLI, and writes one full-body front/right-side/back turnaround sheet per selection. The Persona is the only identity reference; the Look image's face is excluded.
 
 The raw `private-library/` is ignored by Git and is never included in the npm package. D1 holds catalog metadata, private R2 holds approved source bytes, and a Worker issues an individual credential to each enrolling Agent. The individual credential is stored only in the Agent's local mode-600 config file and is never printed by the CLI.
 
@@ -47,6 +47,9 @@ Once setup and `remote doctor` succeed, use the route that matches the request:
 # Persona-only: return matching library image(s); no Makaron request.
 personlib remote find --kind persona --brief '3个长相高冷的亚洲女生' --count 3 --output-dir ./personlib-personas --json
 
+# Follow-up internal search: exclude the previous records without exposing their IDs to an end user.
+personlib remote find --kind persona --brief '长相高冷的亚洲女生' --count 2 --exclude P-001,P-002 --output-dir ./personlib-personas-next --json
+
 # Look-only: return matching library image(s); no Makaron request.
 personlib remote find --kind look --brief '3套 Y2K 的妆造' --count 3 --output-dir ./personlib-looks --json
 
@@ -55,7 +58,7 @@ personlib remote render --brief '3个都市风格的亚洲女生' --count 3 --ou
 personlib remote render --brief '3个都市风格的亚洲女生' --count 3 --output-dir ./personlib-turnarounds --json
 ```
 
-The third route is a paid external generation action. `render --brief` first creates Agent-bound, 24-hour selection tokens containing the exact Persona plus catalog Look or a complete temporary Look specification, then resolves those exact tokens; it never reranks or silently swaps a result after selection. A pre-confirmed single selection can also be rendered with `--selection`. In the owner-approved direct-delivery mode, an Agent keeps tokens internal and makes exactly one Makaron submission per selection without a second user confirmation. A batch writes `turnaround-01/`, `turnaround-02/`, and so on; each directory contains one turnaround image (or a pending run ID with `--no-wait`), `turnaround-plan.json`, `prompt_used.md`, and `qc_report.md`. If fewer than `--count` distinct eligible Personas or Looks exist, the CLI returns `BLOCKED` with the available count and submits nothing. The CLI removes only brand identifiers: visible logos, wordmarks, brand names, protected monograms, recognizable trademark symbols, and brand/team crests. Ordinary stripes, numbers, abstract graphics, and shoe construction remain part of the Look. The CLI never automatically retries a paid job. Use `--dry-run` to inspect every locked request and complete prompt without downloading inputs or submitting anything, or `--no-wait` to keep returned Makaron run IDs for later retrieval.
+The third route is a paid external generation action. `render --brief` first creates Agent-bound, 24-hour selection tokens containing the exact Persona plus catalog Look or a complete temporary Look specification, then resolves those exact tokens; it never reranks or silently swaps a result after selection. A pre-confirmed single selection can also be rendered with `--selection`. In the owner-approved direct-delivery mode, an Agent keeps tokens internal and makes exactly one Makaron submission per selection without a second user confirmation. A batch writes `turnaround-01/`, `turnaround-02/`, and so on; each directory contains one turnaround image (or a pending run ID with `--no-wait`), `turnaround-plan.json`, `prompt_used.md`, and `qc_report.md`. If a `find` request has fewer than `--count` distinct eligible records after exclusions, it returns `BLOCKED`, `insufficient_matches: true`, and the available count without downloading partial or duplicate images. The CLI removes only brand identifiers: visible logos, wordmarks, brand names, protected monograms, recognizable trademark symbols, and brand/team crests. Ordinary stripes, numbers, abstract graphics, and shoe construction remain part of the Look. The CLI never automatically retries a paid job. Use `--dry-run` to inspect every locked request and complete prompt without downloading inputs or submitting anything, or `--no-wait` to keep returned Makaron run IDs for later retrieval.
 
 `亚洲女生` is a hard retrieval and render condition, not a visual guess. The Worker requires both an owner-reviewed `east_asian` appearance tag and the Persona metadata `presentation: "feminine adult"`; no matching record returns `BLOCKED` before Makaron is called. `韩国女生` additionally requires `korean_style_compatible`. Appearance tags are never inferred by the running model. The current library needs owner review before any existing Persona is made eligible for these requests.
 
@@ -74,6 +77,7 @@ node bin/personlib.mjs list --library ./private-library --json
 node bin/personlib.mjs show --persona P-001 --library ./private-library --json
 node bin/personlib.mjs review-persona --persona P-001 --appearance-tags east_asian,korean_style_compatible --reviewed-by owner-name --owner-confirmed --library ./private-library --json
 node bin/personlib.mjs show --look L-001 --library ./private-library --json
+node bin/personlib.mjs review-look --look L-001 --family 'adult hip-hop streetwear' --silhouette 'relaxed low-rise layered proportion' --garments 'unbranded color-block jacket, cropped top, baggy denim and retro sneakers' --palette 'red, blue, ivory and indigo' --materials 'nylon, cotton jersey and washed denim' --accessories 'minimal metal chain' --scene 'neutral adult music-fashion studio' --reviewed-by owner-name --owner-confirmed --library ./private-library --json
 node bin/personlib.mjs recommend --brief '请使用人物资产库，为一个 15 秒高端美妆广告找一位 25 岁左右、东亚、干净冷感的女性人物。' --library ./private-library --json
 node bin/personlib.mjs fetch --brief '请为一个 15 秒成年女性地铁皮夹克通勤广告找一套都市造型。' --output-dir ./selection --library ./private-library --json
 node bin/personlib.mjs compose --persona P-003 --look L-011 --library ./private-library --json
@@ -94,7 +98,7 @@ node bin/personlib.mjs intake \
 
 `intake` records neither facial nor styling assertions automatically. A human/vision-review step adds Persona or Look fields. A Look always carries a source-face exclusion and brand-sanitization rule.
 
-`review-persona` is an owner-only manual-audit command. It writes the reviewed tags plus reviewer/time provenance; do not run it from an image model, an automatic classifier, or an Agent guess. Follow it with owner `remote sync` so the Worker receives the audited metadata.
+`review-persona` is an owner-only manual-audit command. It writes the reviewed tags plus reviewer/time provenance; do not run it from an image model, an automatic classifier, or an Agent guess. `review-look` is the equivalent owner-only gate for a new Look: all seven structured styling fields, source-face exclusion, source-brand replacement, and reviewer/time provenance are required before it can become `private-staged`. Follow either review with owner `remote sync` so the Worker receives only approved metadata and private source bytes.
 
 ## Test
 

package/bin/personlib.mjs

@@ -132,6 +132,11 @@ function validate(manifest, root) {
     } else if (lookRecord.look?.review_state !== "needs-structured-review") {
       errors.push(`${lookRecord.id}: intake-review records must declare look.review_state`);
     }
+    if (lookRecord.look_review !== undefined) {
+      if (lookRecord.status !== "private-staged" || lookRecord.look_review?.state !== "owner-reviewed" || !lookRecord.look_review?.reviewed_by || !lookRecord.look_review?.reviewed_at) {
+        errors.push(`${lookRecord.id}: look_review requires private-staged owner-reviewed provenance`);
+      }
+    }
   }
   return errors;
 }
@@ -264,6 +269,36 @@ function reviewPersonaAppearance() {
   output({ ok: true, persona: { id: persona.id, appearance_tags: tags, appearance_tags_review: persona.appearance_tags_review } });
 }
 
+function reviewLook() {
+  const root = rootPath();
+  const lookId = option("--look");
+  const reviewedBy = option("--reviewed-by");
+  const fields = ["family", "silhouette", "garments", "palette", "materials", "accessories", "scene"];
+  const look = Object.fromEntries(fields.map((field) => [field, option(`--${field}`)?.trim()]));
+  if (!lookId || !reviewedBy || !has("--owner-confirmed") || fields.some((field) => !look[field])) {
+    throw new Error("usage: personlib review-look --look L-001 --family TEXT --silhouette TEXT --garments TEXT --palette TEXT --materials TEXT --accessories TEXT --scene TEXT --reviewed-by NAME --owner-confirmed --library PATH");
+  }
+  const manifest = readManifest(root);
+  const record = (manifest.looks || []).find((entry) => entry.id === lookId);
+  if (!record) throw new Error(`look not found: ${lookId}`);
+  if (!["intake-review", "private-staged"].includes(record.status)) throw new Error(`look is not ready for owner review: ${lookId}`);
+  record.status = "private-staged";
+  record.look = look;
+  record.identity_policy = "do-not-use-source-face";
+  record.brand_policy = "replace-source-logos-and-wordmarks";
+  record.look_review = {
+    state: "owner-reviewed",
+    reviewed_by: reviewedBy,
+    reviewed_at: new Date().toISOString(),
+    method: "manual-owner-review-source-face-excluded"
+  };
+  record.cloud_sync = "not-started";
+  const errors = validate(manifest, root);
+  if (errors.length) throw new Error(`library validation failed: ${errors.join("; ")}`);
+  saveManifest(root, manifest);
+  output({ ok: true, look: { id: record.id, status: record.status, look: record.look, brand_policy: record.brand_policy, look_review: record.look_review } });
+}
+
 function buildRenderBrief(persona, look) {
   const identity = persona.identity;
   const identityLock = [
@@ -542,6 +577,7 @@ try {
   else if (command === "remote") await runRemote(argv.slice(1), { output, readManifest });
   else if (command === "intake") intake();
   else if (command === "review-persona") reviewPersonaAppearance();
+  else if (command === "review-look") reviewLook();
   else if (command === "recommend") recommend();
   else if (command === "fetch") fetchReferencePack();
   else if (command === "compose") compose();
@@ -569,7 +605,7 @@ try {
     output({ ok: errors.length === 0, errors });
     if (errors.length) process.exitCode = 1;
   } else {
-    output("Usage: personlib <setup|intake|review-persona|list|show|recommend|fetch|compose|validate|remote> [--library PATH] [--json]");
+    output("Usage: personlib <setup|intake|review-persona|review-look|list|show|recommend|fetch|compose|validate|remote> [--library PATH] [--json]");
     process.exitCode = command ? 1 : 0;
   }
 } catch (error) {

package/cloudflare-worker/src/worker.mjs

@@ -18,6 +18,14 @@ function requestedCount(value) {
   return count;
 }
 
+function requestedExcludedIds(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new Error("exclude_ids must be an array of record IDs");
+  const ids = [...new Set(value.map((id) => String(id || "").trim()).filter(Boolean))];
+  if (!ids.length) throw new Error("exclude_ids must contain at least one record ID when supplied");
+  return ids;
+}
+
 async function sha256(value) {
   const input = typeof value === "string" ? encoder.encode(value) : value;
   const hash = await crypto.subtle.digest("SHA-256", input);
@@ -162,6 +170,13 @@ function distinctSourceCandidates(candidates) {
   });
 }
 
+function excludeRecordCandidates(candidates, excludeIds) {
+  if (!excludeIds.length) return candidates;
+  const excluded = new Set(excludeIds);
+  const excludedSources = new Set(candidates.filter(({ record }) => excluded.has(record.id)).map(({ record }) => record.source_asset_id).filter(Boolean));
+  return candidates.filter(({ record }) => !excluded.has(record.id) && !excludedSources.has(record.source_asset_id));
+}
+
 function buildRenderBrief(persona, look) {
   const identity = persona.identity || {};
   const direction = look.look || look;
@@ -223,17 +238,20 @@ async function selectSingle(env, { kind, brief }) {
   return selected.records[0];
 }
 
-async function selectSingles(env, { kind, brief, count = 1 }) {
+async function selectSingles(env, { kind, brief, count = 1, excludeIds = [] }) {
   if (!['persona', 'look'].includes(kind)) throw new Error("kind must be persona or look");
   const requested = requestedCount(count);
   if (kind === "persona") {
-    const selected = await selectPersonas(env, { brief, count: requested });
+    const selected = await selectPersonas(env, { brief, count: requested, excludeIds });
     return { records: selected.personas, available_count: selected.available_count };
   }
-  const candidates = distinctSourceCandidates((await records(env, "look_records"))
+  const scored = (await records(env, "look_records"))
     .map((record) => ({ record, score: scoreLook(record, brief) }))
     .filter(({ score }) => score >= 6)
-    .sort((a, b) => b.score - a.score || a.record.id.localeCompare(b.record.id)));
+    .sort((a, b) => b.score - a.score || a.record.id.localeCompare(b.record.id));
+  const unexcludedCandidates = distinctSourceCandidates(scored);
+  const candidates = distinctSourceCandidates(excludeRecordCandidates(scored, excludeIds));
+  if (excludeIds.length && unexcludedCandidates.length && candidates.length < requested) throw insufficientCandidatesBlocked("Look", requested, candidates.length);
   if (candidates.length < requested) throw insufficientCandidatesBlocked("Look", requested, candidates.length);
   return { records: candidates.slice(0, requested).map(({ record }) => record), available_count: candidates.length };
 }
@@ -247,7 +265,7 @@ async function selectPersona(env, { brief, personaId }) {
   };
 }
 
-async function selectPersonas(env, { brief, personaId, count = 1 }) {
+async function selectPersonas(env, { brief, personaId, count = 1, excludeIds = [] }) {
   const requested = requestedCount(count);
   const personas = await records(env, "persona_records");
   const requiredAppearanceTags = requestedAppearanceTags(brief || "");
@@ -256,10 +274,18 @@ async function selectPersonas(env, { brief, personaId, count = 1 }) {
   if (!available.length) throw new Error(personaId ? `persona not found: ${personaId}` : "no Persona records available");
   const presentationCandidates = available.filter((record) => presentationMatches(record, requiredPresentation));
   if (!presentationCandidates.length && requiredPresentation) throw presentationBlocked(requiredPresentation, { requestedCount: requested, availableCount: 0 });
-  const candidates = distinctSourceCandidates(presentationCandidates
+  const scored = presentationCandidates
     .filter((record) => appearanceMatches(record, requiredAppearanceTags))
     .map((record) => ({ record, score: scorePersona(record, brief || "") }))
-    .sort((a, b) => b.score - a.score || a.record.id.localeCompare(b.record.id)));
+    .sort((a, b) => b.score - a.score || a.record.id.localeCompare(b.record.id));
+  const unexcludedCandidates = distinctSourceCandidates(scored);
+  const candidates = distinctSourceCandidates(excludeRecordCandidates(scored, excludeIds));
+  if (excludeIds.length && unexcludedCandidates.length && candidates.length < requested) {
+    throw insufficientCandidatesBlocked("Persona", requested, candidates.length, {
+      required_appearance_tags: requiredAppearanceTags,
+      required_presentation: requiredPresentation
+    });
+  }
   if (!candidates.length && requiredAppearanceTags.length) throw appearanceBlocked(requiredAppearanceTags, requiredPresentation, { requestedCount: requested, availableCount: 0 });
   if (!candidates.length && requiredPresentation) throw presentationBlocked(requiredPresentation, { requestedCount: requested, availableCount: 0 });
   if (!candidates.length) throw new Error(personaId ? `persona not found: ${personaId}` : "no Persona records available");
@@ -403,6 +429,7 @@ function blocked(cause, status = 409) {
     kind: cause?.kind || null,
     requested_count: cause?.requested_count || null,
     available_count: cause?.available_count ?? null,
+    insufficient_matches: cause?.code === "insufficient-candidates",
     error: cause?.message || "request blocked"
   }, status);
 }
@@ -533,12 +560,14 @@ async function route(request, env) {
     try {
       const kind = String(body.kind || "");
       const count = requestedCount(body?.count);
-      const selected = await selectSingles(env, { kind, brief: String(body.brief), count });
+      const excludeIds = requestedExcludedIds(body?.exclude_ids);
+      const selected = await selectSingles(env, { kind, brief: String(body.brief), count, excludeIds });
       return json({
         kind: `${kind}-reference`,
         image_status: "library-reference-not-generated",
         requested_count: count,
         available_count: selected.available_count,
+        returned_count: selected.records.length,
         assets: selected.records.map((record, index) => ({
           role: kind,
           ...(count > 1 ? { index: index + 1 } : {}),

package/cloudflare-worker/test/worker.test.mjs

@@ -85,7 +85,8 @@ test("owner sync, self-registration, recommendation, compose, and private previe
       { id: "P-000", display_name: "Adult Man", status: "private-staged", identity: { presentation: "masculine adult", face_shape: "square", brows: "straight", eyes: "round", nose: "straight", mouth: "thin", skin: "natural", stable_marks: "none" }, appearance_tags: ["east_asian"], appearance_tags_review: { state: "owner-reviewed", reviewed_by: "test-owner", reviewed_at: "2026-09-04T00:00:00.000Z" }, source_asset_id: "P-000:source", identity_references: [] },
       { id: "P-001", display_name: "Adult One", status: "private-staged", identity: { presentation: "feminine adult", face_shape: "oval", brows: "straight", eyes: "almond", nose: "straight", mouth: "soft", skin: "natural", stable_marks: "none" }, appearance_tags: ["east_asian"], appearance_tags_review: { state: "owner-reviewed", reviewed_by: "test-owner", reviewed_at: "2026-09-04T00:00:00.000Z" }, source_asset_id: "P-001:source", identity_references: [] },
       { id: "P-002", display_name: "Adult Two", status: "private-staged", identity: { presentation: "feminine adult", face_shape: "long oval", brows: "arched", eyes: "hooded", nose: "compact", mouth: "full", skin: "neutral", stable_marks: "freckle" }, appearance_tags: ["east_asian"], appearance_tags_review: { state: "owner-reviewed", reviewed_by: "test-owner", reviewed_at: "2026-09-04T00:00:00.000Z" }, source_asset_id: "P-002:source", identity_references: [] },
-      { id: "P-003", display_name: "Adult Three", status: "private-staged", identity: { presentation: "feminine adult", face_shape: "heart", brows: "soft", eyes: "narrow", nose: "straight", mouth: "centered", skin: "even", stable_marks: "beauty mark" }, appearance_tags: ["east_asian"], appearance_tags_review: { state: "owner-reviewed", reviewed_by: "test-owner", reviewed_at: "2026-09-04T00:00:00.000Z" }, source_asset_id: "P-003:source", identity_references: [] }
+      { id: "P-003", display_name: "Adult Three", status: "private-staged", identity: { presentation: "feminine adult", face_shape: "heart", brows: "soft", eyes: "narrow", nose: "straight", mouth: "centered", skin: "even", stable_marks: "beauty mark" }, appearance_tags: ["east_asian"], appearance_tags_review: { state: "owner-reviewed", reviewed_by: "test-owner", reviewed_at: "2026-09-04T00:00:00.000Z" }, source_asset_id: "P-003:source", identity_references: [] },
+      { id: "P-004", display_name: "Adult One Duplicate Record", status: "private-staged", identity: { presentation: "feminine adult", face_shape: "oval", brows: "straight", eyes: "almond", nose: "straight", mouth: "soft", skin: "natural", stable_marks: "none" }, appearance_tags: ["east_asian"], appearance_tags_review: { state: "owner-reviewed", reviewed_by: "test-owner", reviewed_at: "2026-09-04T00:00:00.000Z" }, source_asset_id: "P-001:source", identity_references: [] }
     ],
     looks: [
       { id: "L-115", display_name: "Hip-Hop Rap", status: "private-staged", look: { family: "hip-hop rap y2k", silhouette: "baggy", garments: "unbranded jersey and cargo trousers", palette: "red black", materials: "denim", accessories: "chain", scene: "neutral studio" }, source_asset_id: "L-115:source" },
@@ -180,6 +181,21 @@ test("owner sync, self-registration, recommendation, compose, and private previe
   assert.equal(personaBatch.available_count, 3);
   assert.deepEqual(personaBatch.assets.map((asset) => asset.index), [1, 2, 3]);
   assert.deepEqual(new Set(personaBatch.assets.map((asset) => asset.asset_id)), new Set(["P-001:source", "P-002:source", "P-003:source"]));
+  response = await worker.fetch(request("/v1/find", { method: "POST", headers, body: JSON.stringify({ kind: "persona", brief: "长相高冷的亚洲女生", count: 2, exclude_ids: ["P-001"] }) }), env);
+  const excludedPersonaBatch = await response.json();
+  assert.equal(response.status, 200);
+  assert.equal(excludedPersonaBatch.requested_count, 2);
+  assert.equal(excludedPersonaBatch.available_count, 2);
+  assert.equal(excludedPersonaBatch.returned_count, 2);
+  assert.deepEqual(excludedPersonaBatch.assets.map((asset) => asset.asset_id), ["P-002:source", "P-003:source"]);
+  response = await worker.fetch(request("/v1/find", { method: "POST", headers, body: JSON.stringify({ kind: "persona", brief: "长相高冷的亚洲女生", count: 3, exclude_ids: ["P-001"] }) }), env);
+  const insufficientPersonaBatch = await response.json();
+  assert.equal(response.status, 409);
+  assert.equal(insufficientPersonaBatch.state, "BLOCKED");
+  assert.equal(insufficientPersonaBatch.insufficient_matches, true);
+  assert.equal(insufficientPersonaBatch.requested_count, 3);
+  assert.equal(insufficientPersonaBatch.available_count, 2);
+  assert.equal(Object.hasOwn(insufficientPersonaBatch, "assets"), false);
   response = await worker.fetch(request("/v1/find", { method: "POST", headers, body: JSON.stringify({ kind: "look", brief: "3套 Y2K 的妆造", count: 3 }) }), env);
   const lookBatch = await response.json();
   assert.equal(response.status, 200);
@@ -187,6 +203,10 @@ test("owner sync, self-registration, recommendation, compose, and private previe
   assert.equal(lookBatch.available_count, 3);
   assert.deepEqual(lookBatch.assets.map((asset) => asset.index), [1, 2, 3]);
   assert.deepEqual(new Set(lookBatch.assets.map((asset) => asset.asset_id)), new Set(["L-115:source", "L-116:source", "L-117:source"]));
+  response = await worker.fetch(request("/v1/find", { method: "POST", headers, body: JSON.stringify({ kind: "look", brief: "3套 Y2K 的妆造", count: 2, exclude_ids: ["L-115"] }) }), env);
+  const excludedLookBatch = await response.json();
+  assert.equal(response.status, 200);
+  assert.deepEqual(excludedLookBatch.assets.map((asset) => asset.asset_id), ["L-116:source", "L-117:source"]);
   response = await worker.fetch(request("/v1/recommend", { method: "POST", headers, body: JSON.stringify({ brief: "3个都市风格的亚洲女生", count: 3 }) }), env);
   const urbanBatch = await response.json();
   assert.equal(response.status, 200);

package/lib/remote-client.mjs

@@ -28,6 +28,14 @@ function countOption(args) {
   return count;
 }
 
+function excludeIdsOption(args) {
+  const value = getOption(args, "--exclude");
+  if (value === undefined) return [];
+  const ids = [...new Set(value.split(",").map((id) => id.trim()).filter(Boolean))];
+  if (!ids.length) throw new Error("--exclude must be a comma-separated list of record IDs");
+  return ids;
+}
+
 function jsonOption(args, name) {
   const value = getOption(args, name);
   if (!value) return undefined;
@@ -252,14 +260,15 @@ async function downloadReferencePack(remote, payload, destination, args, { roles
 
 async function find(args, output) {
   const kind = getOption(args, "--kind");
-  if (!['persona', 'look'].includes(kind)) throw new Error("usage: personlib remote find --kind <persona|look> --brief TEXT --output-dir PATH");
+  if (!['persona', 'look'].includes(kind)) throw new Error("usage: personlib remote find --kind <persona|look> --brief TEXT [--count N] [--exclude ID[,ID...]] --output-dir PATH");
   const brief = getOption(args, "--brief");
   if (!brief) throw new Error("personlib remote find requires --brief TEXT");
   const destination = getOption(args, "--output-dir");
   if (!destination) throw new Error("personlib remote find requires --output-dir PATH so it can return an image");
   const count = countOption(args);
+  const excludeIds = excludeIdsOption(args);
   const remote = agentConnection(args);
-  const { response, payload } = await request(remote.endpoint, "/v1/find", { token: remote.token, method: "POST", json: { kind, brief, count }, allowError: true });
+  const { response, payload } = await request(remote.endpoint, "/v1/find", { token: remote.token, method: "POST", json: { kind, brief, count, ...(excludeIds.length ? { exclude_ids: excludeIds } : {}) }, allowError: true });
   if (!response.ok) {
     if (payload?.state === "BLOCKED") return jsonOutput(payload, output, args);
     throw new Error(`remote request failed (${response.status}): ${payload?.error || "find failed"}`);
@@ -267,7 +276,7 @@ async function find(args, output) {
   const absoluteDestination = resolve(destination);
   const files = await downloadReferencePack(remote, payload, absoluteDestination, args, { roles: [kind], writeSelection: false });
   if (files.length !== count) throw new Error(`library search expected ${count} ${kind} images, received ${files.length}`);
-  jsonOutput({ ok: true, retrieval: { kind: `${kind}-reference`, image_status: "library-reference-not-generated", requested_count: count, available_count: payload.available_count, output_dir: absoluteDestination, files: files.map(({ path }) => path) } }, output, args);
+  jsonOutput({ ok: true, retrieval: { kind: `${kind}-reference`, image_status: "library-reference-not-generated", requested_count: count, available_count: payload.available_count, returned_count: files.length, output_dir: absoluteDestination, files: files.map(({ path }) => path) } }, output, args);
 }
 
 async function preview(args, output) {

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "makaron-persona-look-cli",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "Portable Persona and Look library for Makaron agents",
   "private": false,
   "type": "module",
   "bin": {
-    "personlib": "bin/personlib.mjs",
-    "makaron-persona-look-cli": "bin/personlib.mjs"
+    "makaron-persona-look-cli": "bin/personlib.mjs",
+    "personlib": "bin/personlib.mjs"
   },
   "files": [
     "bin",

package/skills/makaron-persona-look/SKILL.md

@@ -12,10 +12,10 @@ Persona is the stable identity reference: face structure, natural skin traits, s
 ## Natural-language routing
 
 - Search-only rule: requests that ask only for a Persona or only for a Look do not authorize image generation. Return the matched reference image only—never expose IDs, match scores, or internal selection metadata—and do not call Makaron or `remote render`.
-- “我要一个长相高冷的女生” is Persona-only search: use `personlib remote find --kind persona --brief TEXT --output-dir PATH --json`, then return only the Persona reference image. Do not generate a three-view image. If the request says `3个` (or another quantity), pass `--count N`; return exactly N different references or report `BLOCKED`, never fewer.
-- “我要一套 Y2K 的妆造” is Look-only search: use `personlib remote find --kind look --brief TEXT --output-dir PATH --json`, then return only the Look reference image. Do not generate a three-view image. If the request says `3套` (or another quantity), pass `--count N`; return exactly N different references or report `BLOCKED`, never fewer.
+- “我要一个长相高冷的女生” is Persona-only search: use `personlib remote find --kind persona --brief TEXT --output-dir PATH --json`, then return only the Persona reference image. Do not generate a three-view image. If the request says `3个` (or another quantity), pass `--count N`; return exactly N different references or report `BLOCKED`, never fewer. For a follow-up search, the Agent may pass internal prior record IDs as `--exclude ID[,ID...]`; never expose those IDs to the end user.
+- “我要一套 Y2K 的妆造” is Look-only search: use `personlib remote find --kind look --brief TEXT --output-dir PATH --json`, then return only the Look reference image. Do not generate a three-view image. If the request says `3套` (or another quantity), pass `--count N`; return exactly N different references or report `BLOCKED`, never fewer. For a follow-up search, the Agent may pass internal prior record IDs as `--exclude ID[,ID...]`; never expose those IDs to the end user.
 - “这张图进 Persona 库” is an owner-only intake request. Require clear owner authorization, then use `personlib intake --into persona --rights authorized`.
-- “这张图进 Look 库” is an owner-only intake request. Use `personlib intake --into look --rights authorized`; extract only clothing, hair, makeup, accessory, palette, material, and scene information. Never use the source face as a new Persona.
+- “这张图进 Look 库” is an owner-only intake request. Use `personlib intake --into look --rights authorized`; extract only clothing, hair, makeup, accessory, palette, material, and scene information. Never use the source face as a new Persona. Before an intake Look can be searched remotely, the owner must use `personlib review-look` with all structured Look fields and `--owner-confirmed`; it preserves source-face exclusion and removes only source brand identifiers in future output.
 - “找一个人物” and “为广告找一个人物” are Persona-only searches: use `personlib remote find --kind persona --brief TEXT --output-dir PATH --json`, then return only the Persona reference image. Do not expose the selected ID or create a temporary Look.
 - A request that combines a person and a style—such as “我要一个嘻哈风格的亚洲女生”—is an image request. Run `personlib remote render --brief TEXT --output-dir PATH --json`; it creates and resolves a locked internal selection before submitting, so it never reranks after selection. Never expose the internal selection ID to the user. For `3个都市风格的亚洲女生`, pass `--count 3`: dry-run must return three independent plans, and a real run submits exactly three Makaron jobs—one front/right-side/back sheet per distinct Persona. If the library has fewer than the requested number, return `BLOCKED`; do not silently deliver fewer images or submit any job. A pre-confirmed single selection may use `remote render --selection`. Explicit wording such as “生成三视图”, “出图”, “生成这个人物”, or “做视频出图” follows the same route. The default engine is Makaron and each output is exactly one full-body front/right-side/back turnaround sheet of one adult Persona in one unchanged Look. In the owner-approved direct-delivery mode, that request authorizes exactly one paid submission per selected result: do not pause to display Persona/Look or request a second confirmation. Return the finished turnaround and QC result directly. Use `--dry-run` only when the user asks to preview the locked selection(s) without generating.
 - “只看看匹配的参考” should use `personlib remote preview --brief TEXT --output-dir PATH --json`. This is free retrieval of the private Persona + Look reference pack, not a synthesized image.
@@ -30,10 +30,10 @@ Persona is the stable identity reference: face structure, natural skin traits, s
 
 ## Access boundary
 
-Any enrolled OpenClaw Agent may use credentialed `remote doctor`, `remote find`, `remote recommend`, `remote compose`, `remote preview`, and `remote render`. It may not call `remote sync`, upload source images, manually apply appearance tags, delete assets, or publish the bundle. `remote render` additionally needs the Agent's own already-authenticated Makaron CLI. In owner-approved direct-delivery mode, a combined Persona + Look request is approval for exactly one paid submission per locked selection; do not ask a second confirmation. Open enrollment is an owner-selected access rule; never request or print API keys, Agent tokens, owner tokens, or Makaron credentials. `find --count N` returns N library images without IDs; `preview` returns source references only; `render --count N` returns N turnarounds plus one plan, prompt, run ID, and QC record per result.
+Any enrolled OpenClaw Agent may use credentialed `remote doctor`, `remote find`, `remote recommend`, `remote compose`, `remote preview`, and `remote render`. It may not call `remote sync`, upload source images, manually apply appearance tags, delete assets, or publish the bundle. `remote render` additionally needs the Agent's own already-authenticated Makaron CLI. In owner-approved direct-delivery mode, a combined Persona + Look request is approval for exactly one paid submission per locked selection; do not ask a second confirmation. Open enrollment is an owner-selected access rule; never request or print API keys, Agent tokens, owner tokens, or Makaron credentials. `find --count N` returns N library images without IDs; its internal-only `--exclude ID[,ID...]` prevents a previously selected record or its matching source image from returning again. On shortfall it returns `BLOCKED` with `insufficient_matches: true` and a count, never a duplicate. `preview` returns source references only; `render --count N` returns N turnarounds plus one plan, prompt, run ID, and QC record per result.
 
 ## Current local-admin milestone
 
-The current package supports local Persona and Look intake, owner-reviewed appearance tags, list, show, integrity validation, `recommend --brief TEXT`, `fetch --brief TEXT --output-dir PATH`, `compose --persona P-xxx --look L-xxx`, and no-generation `remote find --kind persona|look --brief TEXT --count N --output-dir PATH`; it also ships the remote Worker/client implementation. The `find` route returns exactly the requested number of distinct reference images, with no IDs or selection metadata, or `BLOCKED` with the available count. The remote commands need a deployed private Worker and a successful top-level `setup` before use; do not claim that the current host is live until `remote doctor` succeeds against its Worker URL. `remote render --brief TEXT --count N` creates and resolves N locked selections just in time, calls Makaron exactly N times after a passing dry-run, and asks for one neutral-studio front/right-side/back turnaround per selection. It retains the Look's silhouette, palette, materials, energy, ordinary stripes, numbers, abstract graphics, and shoe construction. It removes only brand identifiers: logos, wordmarks, brand names, protected monograms, recognizable trademark symbols, and brand/team crests. It keeps internal inputs in `_internal_references/` for traceability but only the finished turnaround is customer-ready. Reject an output that is not one three-view adult turnaround, mixes identities or Looks, uses the Look source face, fails an owner-reviewed requested appearance tag or presentation, or includes a brand identifier. Record `PASS`, `REROLL`, or `BLOCKED`; do not submit a hidden retry.
+The current package supports local Persona and Look intake, owner-reviewed Persona appearance tags, owner-reviewed structured Looks (`review-look`), list, show, integrity validation, `recommend --brief TEXT`, `fetch --brief TEXT --output-dir PATH`, `compose --persona P-xxx --look L-xxx`, and no-generation `remote find --kind persona|look --brief TEXT --count N --output-dir PATH`; it also ships the remote Worker/client implementation. The `find` route returns exactly the requested number of distinct reference images, with no IDs or selection metadata, or `BLOCKED` with the available count. The remote commands need a deployed private Worker and a successful top-level `setup` before use; do not claim that the current host is live until `remote doctor` succeeds against its Worker URL. `remote render --brief TEXT --count N` creates and resolves N locked selections just in time, calls Makaron exactly N times after a passing dry-run, and asks for one neutral-studio front/right-side/back turnaround per selection. It retains the Look's silhouette, palette, materials, energy, ordinary stripes, numbers, abstract graphics, and shoe construction. It removes only brand identifiers: logos, wordmarks, brand names, protected monograms, recognizable trademark symbols, and brand/team crests. It keeps internal inputs in `_internal_references/` for traceability but only the finished turnaround is customer-ready. Reject an output that is not one three-view adult turnaround, mixes identities or Looks, uses the Look source face, fails an owner-reviewed requested appearance tag or presentation, or includes a brand identifier. Record `PASS`, `REROLL`, or `BLOCKED`; do not submit a hidden retry.
 
 When a source has preppy, uniform-adjacent, or youth-coded styling, store only an adult office-core/editorial interpretation. Do not use a student identity, school context, or sexualized youth styling.