makaron-persona-look-cli 0.5.2 → 0.5.3

package/README.md

@@ -4,7 +4,7 @@
 
 ## What an Agent gets
 
-`find` is the no-generation delivery route for a single library result: `--kind persona` returns one matched Persona image, and `--kind look` returns one matched Look image. 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 sends those private inputs to the caller's authenticated Makaron CLI and writes exactly one full-body front/right-side/back turnaround sheet. 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` 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.
 
 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.
 
@@ -44,17 +44,22 @@ personlib remote sync --library ./private-library --json
 Once setup and `remote doctor` succeed, use the route that matches the request:
 
 ```bash
-# Persona-only: return one matching library image; no Makaron request.
-personlib remote find --kind persona --brief '我要一个长相高冷的女生' --output-dir ./personlib-persona --json
+# Persona-only: return matching library image(s); no Makaron request.
+personlib remote find --kind persona --brief '3个长相高冷的亚洲女生' --count 3 --output-dir ./personlib-personas --json
 
-# Look-only: return one matching library image; no Makaron request.
-personlib remote find --kind look --brief '我要一套 Y2K 的妆造' --output-dir ./personlib-look --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
 
-# Persona + Look: render the fused three-view image.
-personlib remote render --brief '我要一个嘻哈风格的亚洲女生' --output-dir ./personlib-turnaround --json
+# Persona + Look: create locked selections internally, then render each exact selection.
+personlib remote render --brief '3个都市风格的亚洲女生' --count 3 --output-dir ./personlib-turnarounds --dry-run --json
+personlib remote render --brief '3个都市风格的亚洲女生' --count 3 --output-dir ./personlib-turnarounds --json
 ```
 
-The third route is a paid external generation action. In the owner-approved direct-delivery mode, a combined Persona + Look request authorizes exactly one Makaron submission, so the Agent generates and returns the turnaround without a second confirmation step. The result is `turnaround.png` (or `.jpg`/`.webp`), plus `turnaround-plan.json`, `prompt_used.md`, and `qc_report.md`. 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` only to inspect the exact prompt and matching IDs without downloading inputs or submitting anything, or `--no-wait` to keep the returned Makaron run ID 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 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.
+
+`亚洲女生` 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.
+
+`都市`, `urban`, `city`, `city chic`, and `downtown` all retrieve the urban/commute/editorial Look family; users do not need to rewrite `都市风格` as `都市通勤`.
 
 For an explicit free Persona + Look source-reference pack, retain `preview`:
 
@@ -67,6 +72,7 @@ personlib remote preview --brief '20 秒嘻哈说唱女 rapper 舞台视频，
 ```bash
 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 recommend --brief '请使用人物资产库，为一个 15 秒高端美妆广告找一位 25 岁左右、东亚、干净冷感的女性人物。' --library ./private-library --json
 node bin/personlib.mjs fetch --brief '请为一个 15 秒成年女性地铁皮夹克通勤广告找一套都市造型。' --output-dir ./selection --library ./private-library --json
@@ -88,6 +94,8 @@ 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.
+
 ## Test
 
 ```bash

package/bin/personlib.mjs

@@ -100,6 +100,18 @@ function validate(manifest, root) {
     for (const forbidden of ["hair", "makeup", "wardrobe", "accessories"]) {
       if (Object.hasOwn(identity, forbidden)) errors.push(`${persona.id}: identity may not contain ${forbidden}`);
     }
+    const appearanceTags = persona.appearance_tags;
+    const appearanceReview = persona.appearance_tags_review;
+    if (appearanceTags !== undefined) {
+      if (!Array.isArray(appearanceTags) || !appearanceTags.length || appearanceTags.some((tag) => typeof tag !== "string" || !tag.trim())) {
+        errors.push(`${persona.id}: appearance_tags must be a non-empty string array when present`);
+      }
+      if (appearanceReview?.state !== "owner-reviewed" || !appearanceReview?.reviewed_by || !appearanceReview?.reviewed_at) {
+        errors.push(`${persona.id}: appearance_tags require owner-reviewed provenance`);
+      }
+    } else if (appearanceReview !== undefined) {
+      errors.push(`${persona.id}: appearance_tags_review requires appearance_tags`);
+    }
   }
   const lookIds = new Set();
   for (const lookRecord of manifest.looks || []) {
@@ -124,6 +136,38 @@ function validate(manifest, root) {
   return errors;
 }
 
+function requestedAppearanceTags(brief = "") {
+  const query = String(brief).toLowerCase();
+  const tags = new Set();
+  if (/亚洲|亚裔|asian|东亚|east\s*asian/.test(query)) tags.add("east_asian");
+  if (/韩系|韩国|korean/.test(query)) {
+    tags.add("east_asian");
+    tags.add("korean_style_compatible");
+  }
+  return [...tags].sort();
+}
+
+function requestedPresentation(brief = "") {
+  const query = String(brief).toLowerCase();
+  if (/女生|女性|女人|女模特|女rapper|女说唱|female|woman|women/.test(query)) return "feminine adult";
+  if (/男生|男性|男人|男模特|男rapper|男说唱|male|man|men/.test(query)) return "masculine adult";
+  return null;
+}
+
+function reviewedAppearanceTags(persona) {
+  if (persona?.appearance_tags_review?.state !== "owner-reviewed" || !Array.isArray(persona?.appearance_tags)) return [];
+  return [...new Set(persona.appearance_tags.map((tag) => String(tag).trim()).filter(Boolean))].sort();
+}
+
+function appearanceMatches(persona, requiredTags) {
+  const tags = new Set(reviewedAppearanceTags(persona));
+  return requiredTags.every((tag) => tags.has(tag));
+}
+
+function presentationMatches(persona, required) {
+  return !required || persona?.identity?.presentation === required;
+}
+
 function intake() {
   const root = rootPath();
   const image = option("--image");
@@ -193,6 +237,33 @@ function intake() {
   output({ ok: true, [into]: record });
 }
 
+function reviewPersonaAppearance() {
+  const root = rootPath();
+  const personaId = option("--persona");
+  const rawTags = option("--appearance-tags");
+  const reviewedBy = option("--reviewed-by");
+  if (!personaId || !rawTags || !reviewedBy || !has("--owner-confirmed")) {
+    throw new Error("usage: personlib review-persona --persona P-001 --appearance-tags east_asian,korean_style_compatible --reviewed-by NAME --owner-confirmed --library PATH");
+  }
+  const tags = [...new Set(rawTags.split(",").map((tag) => tag.trim()).filter(Boolean))].sort();
+  if (!tags.length || tags.some((tag) => !/^[a-z][a-z0-9_]*$/.test(tag))) throw new Error("appearance tags must be lowercase underscore identifiers");
+  const manifest = readManifest(root);
+  const persona = (manifest.personas || []).find((entry) => entry.id === personaId);
+  if (!persona) throw new Error(`persona not found: ${personaId}`);
+  if (persona.status !== "private-staged") throw new Error(`persona is not ready for owner appearance review: ${personaId}`);
+  persona.appearance_tags = tags;
+  persona.appearance_tags_review = {
+    state: "owner-reviewed",
+    reviewed_by: reviewedBy,
+    reviewed_at: new Date().toISOString(),
+    method: "manual-owner-review-not-runtime-inference"
+  };
+  const errors = validate(manifest, root);
+  if (errors.length) throw new Error(`library validation failed: ${errors.join("; ")}`);
+  saveManifest(root, manifest);
+  output({ ok: true, persona: { id: persona.id, appearance_tags: tags, appearance_tags_review: persona.appearance_tags_review } });
+}
+
 function buildRenderBrief(persona, look) {
   const identity = persona.identity;
   const identityLock = [
@@ -314,29 +385,39 @@ function temporaryLookFromBrief(brief) {
 }
 
 function recommendationForBrief(manifest, brief) {
+  const requiredAppearanceTags = requestedAppearanceTags(brief);
+  const requiredPresentation = requestedPresentation(brief);
   const candidates = (manifest.personas || [])
     .filter((persona) => persona.status === "private-staged")
+    .filter((persona) => appearanceMatches(persona, requiredAppearanceTags))
+    .filter((persona) => presentationMatches(persona, requiredPresentation))
     .map((persona) => ({ persona, score: scorePersonaForBrief(persona, brief) }))
     .sort((a, b) => b.score - a.score || a.persona.id.localeCompare(b.persona.id));
-  if (!candidates.length) throw new Error("no staged Persona records available for recommendation");
+  if (!candidates.length) {
+    if (requiredAppearanceTags.length) throw new Error(`BLOCKED: no Persona matched owner-reviewed appearance tags: ${requiredAppearanceTags.join(", ")}`);
+    if (requiredPresentation) throw new Error(`BLOCKED: no Persona matched required presentation: ${requiredPresentation}`);
+    throw new Error("no staged Persona records available for recommendation");
+  }
   const selected = candidates[0].persona;
   const catalogMatch = catalogLookForBrief(manifest, brief);
   const selectedLook = catalogMatch?.look || temporaryLookFromBrief(brief);
   const ageRequested = /(?:25\s*岁|25\s*year|twenty[- ]?five)/i.test(brief);
-  const eastAsiaRequested = /东亚|east\s*asian/i.test(brief);
   return {
     request: brief,
     persona: {
       id: selected.id,
       display_name: selected.display_name,
+      appearance_tags: reviewedAppearanceTags(selected),
+      presentation: selected.identity?.presentation || null,
       match_reason: "Selected from explicit adult Persona metadata and structure-level clean/cool signals; style is not used as identity evidence."
     },
     alternatives: candidates.slice(1, 3).map(({ persona, score }) => ({ id: persona.id, display_name: persona.display_name, score })),
     look: selectedLook,
     look_match: catalogMatch ? { source: catalogMatch.source, score: catalogMatch.score } : { source: "temporary-text-derived", score: 0 },
+    requested_appearance_tags: requiredAppearanceTags,
+    requested_presentation: requiredPresentation,
     constraints_not_verified_from_portrait: [
-      ...(ageRequested ? ["exact age is not stored; the selected Persona is only recorded as an adult"] : []),
-      ...(eastAsiaRequested ? ["East Asian identity is not inferred from the portrait; it requires explicit owner-provided metadata before it can be a hard filter"] : [])
+      ...(ageRequested ? ["exact age is not stored; the selected Persona is only recorded as an adult"] : [])
     ],
     render_brief: buildRenderBrief(selected, selectedLook),
     preview: {
@@ -460,6 +541,7 @@ try {
   if (command === "setup") await runBootstrapSetup(argv.slice(1), { output });
   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 === "recommend") recommend();
   else if (command === "fetch") fetchReferencePack();
   else if (command === "compose") compose();
@@ -487,7 +569,7 @@ try {
     output({ ok: errors.length === 0, errors });
     if (errors.length) process.exitCode = 1;
   } else {
-    output("Usage: personlib <setup|intake|list|show|recommend|fetch|compose|validate|remote> [--library PATH] [--json]");
+    output("Usage: personlib <setup|intake|review-persona|list|show|recommend|fetch|compose|validate|remote> [--library PATH] [--json]");
     process.exitCode = command ? 1 : 0;
   }
 } catch (error) {

package/cloudflare-worker/README.md

@@ -20,6 +20,8 @@ npx wrangler secret put OWNER_SYNC_TOKEN
 npx wrangler deploy
 ```
 
+`schema.sql` is additive and includes the `render_selections` table used to bind a recommendation to one Agent for 24 hours. Run the schema command again before deploying this release so existing D1 databases receive that table.
+
 The owner then uses an ephemeral `PERSONLIB_REMOTE_ENDPOINT` plus `PERSONLIB_OWNER_SYNC_TOKEN` to upload the reviewed source library from the project root:
 
 ```bash
@@ -27,6 +29,15 @@ personlib remote sync --library ./private-library --dry-run --json
 personlib remote sync --library ./private-library --json
 ```
 
+Before syncing a Persona as eligible for a region- or presentation-specific request, the owner must manually review it locally and record tags with provenance. For example, after human review only:
+
+```bash
+personlib review-persona --persona P-001 --appearance-tags east_asian --reviewed-by owner-name --owner-confirmed --library ./private-library --json
+personlib remote sync --library ./private-library --json
+```
+
+The Worker never infers these tags. A request such as `亚洲女生` blocks unless the stored Persona has owner-reviewed `east_asian` and `presentation: feminine adult`; it never falls back to a different gender or region.
+
 After deployment, put the resulting **HTTPS Worker URL** in `package.json` under `personlib.default_api_url`; `npm publish` is intentionally blocked until this value is present. A released CLI then supports the expected Agent bootstrap:
 
 ```bash

package/cloudflare-worker/schema.sql

@@ -24,3 +24,14 @@ CREATE TABLE IF NOT EXISTS assets (
   sha256 TEXT NOT NULL,
   mime_type TEXT NOT NULL
 );
+
+CREATE TABLE IF NOT EXISTS render_selections (
+  id TEXT PRIMARY KEY,
+  agent_id TEXT NOT NULL,
+  selection_json TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  expires_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS render_selections_agent_expiry
+  ON render_selections(agent_id, expires_at);