From 092b03d1313894b4bbab60789674e00ab310c908 Mon Sep 17 00:00:00 2001 From: Mike Chen Date: Thu, 19 Nov 2026 20:37:49 +0800 Subject: [PATCH] feat(ugc): sourcing reads form answers; refuse values that match nobody; v3.2.0 - `ugc sourcing +questions` lists the form questions people answered, with how many answered each and each choice's count. - `ugc sourcing +list --answer 'QUESTION::VALUE'` narrows by the latest answer; rows carry form_answers, sample_videos and creator_link, and --search matches answers too. - --category and --content-type take only the creator form's values; --country and --language take only codes (country in any case). A misspelt value used to answer an empty page; it is now refused with what to type instead. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 9 + README.md | 2 +- README.zh-CN.md | 2 +- contracts/command-catalog.json | 196 ++++++++++++++++-- contracts/task-index.yaml | 5 +- docs/agent-discoverability.md | 5 +- docs/domain-command-framework.md | 5 +- docs/guide.md | 11 +- docs/install.md | 12 +- docs/llms.txt | 2 +- museoncli/domains/ugc_creator_sourcing.py | 139 +++++++++++-- pyproject.toml | 2 +- skills/museon-content-workflow-base/SKILL.md | 2 +- .../references/task-index.md | 4 +- tests/test_coverage_batch1_reads.py | 62 ++++++ uv.lock | 2 +- 16 files changed, 395 insertions(+), 65 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 52a7978..baa5873 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,15 @@ Museon CLI follows semantic versioning for its package and command contract. +## 3.2.0 + +Creator Sourcing reads what people wrote on their forms. Other domains are unchanged. + +- `ugc sourcing +questions` lists the form questions people answered, most answered first, with how many answered each and, for a choice question, how many chose each value. +- `ugc sourcing +list --answer 'QUESTION::VALUE'` narrows by their latest answer to a question (the same question on every project's form counts as one). Values of one question match any; different questions must all match. Each row now carries `form_answers`, `sample_videos` and `creator_link`, and `--search` also matches answer text. +- `--category` and `--content-type` take only the creator form's values, and `--country` / `--language` take only codes (`US`, `en`, `zh-Hant`; country in any case). A misspelt value used to match nobody without a word; it is now refused with the accepted values. +- The command contract revision moves with the package to 3.2.0. Sync the API's vendored `agent_cli_command_catalog.json` to this revision before tagging. + ## 3.1.0 Creator Sourcing for MuseOn staff, matching the internal `/creator-sourcing` page. Other domains are unchanged. diff --git a/README.md b/README.md index af8af01..bc76561 100644 --- a/README.md +++ b/README.md @@ -154,7 +154,7 @@ If you prefer to install the CLI yourself, use Python 3.11+, `uv`, and the exact wheel from the official GitHub release: ```bash -uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v3.1.0/museoncli-3.1.0-py3-none-any.whl" +uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v3.2.0/museoncli-3.2.0-py3-none-any.whl" ``` Then continue with Skill setup and browser authorization: diff --git a/README.zh-CN.md b/README.zh-CN.md index e405312..446fc2d 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -122,7 +122,7 @@ MuseOn 只有组织:访问权限由组织角色加 Campaign 范围决定。每 固定版本的 wheel: ```bash -uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v3.1.0/museoncli-3.1.0-py3-none-any.whl" +uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v3.2.0/museoncli-3.2.0-py3-none-any.whl" ``` 安装成功后继续配置 Skills 和浏览器授权: diff --git a/contracts/command-catalog.json b/contracts/command-catalog.json index e1a656b..822c869 100644 --- a/contracts/command-catalog.json +++ b/contracts/command-catalog.json @@ -18448,7 +18448,34 @@ "risk_level": "read", "shortcut": "+list", "stability": "stable", - "summary": "Find creators for a new project: everyone who joined the community or applied to a project, filtered and sorted, with how they joined, what they declared, their projects, performance (posts, average and best views, viral posts, last post), latest stills and the team's note. Total in `total`. MuseOn staff only, as in the web.", + "summary": "Find creators for a new project: everyone who joined the community or applied to a project, filtered and sorted, with how they joined, what they declared, their latest form answers (`form_answers`), sample videos and work link, their projects, performance (posts, average and best views, viral posts, last post), latest stills and the team's note. Total in `total`. Narrow by form answers with --answer; `sourcing +questions` lists the questions and choices. MuseOn staff only, as in the web.", + "supports_dry_run": false, + "transport": "agent_cli_api" + }, + { + "authorization": { + "authentication_required": true, + "enforcement": "museon_server", + "organization_bound": true, + "required_roles": [ + "staff" + ], + "required_scopes": [ + "agent_cli.access" + ], + "resource_policy": "staff_with_organization_creator_read" + }, + "capability_key": "ugc.sourcing-questions", + "cli": "museoncli ugc sourcing +questions", + "domain": "ugc", + "execution": "direct", + "name": "ugc.sourcing-questions", + "requires_confirmation": false, + "resource": "sourcing", + "risk_level": "read", + "shortcut": "+questions", + "stability": "stable", + "summary": "List the form questions creators in scope answered, most answered first: each question's label and type, how many people answered it, and for a choice question how many chose each value. Use a label and value with `sourcing +list --answer 'QUESTION::VALUE'`. MuseOn staff only, as in the web.", "supports_dry_run": false, "transport": "agent_cli_api" }, @@ -18610,7 +18637,7 @@ "html-documents" ] }, - "contract_revision": "3.1.0", + "contract_revision": "3.2.0", "package": "museoncli", "schema_version": 3, "schemas": { @@ -89265,7 +89292,7 @@ "cli": "museoncli ugc sourcing +list", "domain": "ugc", "examples": [ - "museoncli ugc sourcing +list --country US --language en --platform tiktok --sort avg-views --page-size 20" + "museoncli ugc sourcing +list --country US --language en --answer 'Which of these have you done before?::3D design' --sort avg-views --page-size 20" ], "execution": "direct", "input_schema": { @@ -89284,32 +89311,66 @@ ], "type": "string" }, + "answer": { + "description": "Their latest answer to a form question holds this value, written QUESTION::VALUE with the question and value exactly as `sourcing +questions` lists them (question in any case). Repeatable: values of one question match any, different questions must all match.", + "items": { + "description": "Form answer filter.", + "maxLength": 300, + "minLength": 1, + "type": "string" + }, + "maxItems": 50, + "minItems": 0, + "type": "array" + }, "campaign_id": { "description": "Only people in this project (UGC Campaign id).", "format": "uuid", "type": "string" }, "category": { - "description": "Primary topic they declared, e.g. technology. Repeatable.", + "description": "Primary topic they declared. Repeatable.", "items": { - "description": "Primary topic they declared, e.g. technology. Repeatable.", - "maxLength": 80, - "minLength": 1, + "description": "Primary topic they declared. Repeatable.", + "enum": [ + "beauty", + "fashion", + "food", + "pets", + "technology", + "gaming", + "home", + "fitness", + "travel", + "parenting", + "lifestyle", + "other", + "exploring" + ], "type": "string" }, - "maxItems": 50, + "maxItems": 13, "minItems": 0, "type": "array" }, "content_type": { - "description": "Content type they declared, e.g. tutorials. Repeatable.", + "description": "Content type they declared. Repeatable.", "items": { - "description": "Content type they declared, e.g. tutorials. Repeatable.", - "maxLength": 80, - "minLength": 1, + "description": "Content type they declared. Repeatable.", + "enum": [ + "tutorial", + "review", + "unboxing", + "vlog", + "comedy", + "testimonial", + "screen-recording", + "other", + "exploring" + ], "type": "string" }, - "maxItems": 50, + "maxItems": 9, "minItems": 0, "type": "array" }, @@ -89325,10 +89386,10 @@ "type": "string" }, "country": { - "description": "ISO country code they declared, e.g. US. Repeatable.", + "description": "Two-letter ISO country code they declared, e.g. US. Repeatable.", "items": { - "description": "ISO country code they declared, e.g. US. Repeatable.", - "maxLength": 80, + "description": "Two-letter ISO country code they declared, e.g. US. Repeatable.", + "maxLength": 40, "minLength": 1, "type": "string" }, @@ -89337,10 +89398,10 @@ "type": "array" }, "language": { - "description": "Language tag they speak, e.g. en. Repeatable.", + "description": "Language code they speak, e.g. en, es, zh-Hant (not a language name). Repeatable.", "items": { - "description": "Language tag they speak, e.g. en. Repeatable.", - "maxLength": 80, + "description": "Language code they speak, e.g. en, es, zh-Hant (not a language name). Repeatable.", + "maxLength": 40, "minLength": 1, "type": "string" }, @@ -89354,7 +89415,7 @@ "type": "integer" }, "min_followers": { - "description": "Largest follower count at least this.", + "description": "Largest follower count at least this, among the accounts they post with in our projects (the accounts on their forms are not measured).", "minimum": 0, "type": "integer" }, @@ -89396,7 +89457,7 @@ "type": "array" }, "search": { - "description": "Name, handle or note contains this.", + "description": "Name, handle, note or any form answer contains this.", "maxLength": 200, "minLength": 1, "type": "string" @@ -89503,7 +89564,98 @@ "risk_level": "read", "shortcut": "+list", "stability": "stable", - "summary": "Find creators for a new project: everyone who joined the community or applied to a project, filtered and sorted, with how they joined, what they declared, their projects, performance (posts, average and best views, viral posts, last post), latest stills and the team's note. Total in `total`. MuseOn staff only, as in the web.", + "summary": "Find creators for a new project: everyone who joined the community or applied to a project, filtered and sorted, with how they joined, what they declared, their latest form answers (`form_answers`), sample videos and work link, their projects, performance (posts, average and best views, viral posts, last post), latest stills and the team's note. Total in `total`. Narrow by form answers with --answer; `sourcing +questions` lists the questions and choices. MuseOn staff only, as in the web.", + "supports_dry_run": false, + "transport": "agent_cli_api" + }, + "ugc.sourcing-questions": { + "authorization": { + "authentication_required": true, + "enforcement": "museon_server", + "organization_bound": true, + "required_roles": [ + "staff" + ], + "required_scopes": [ + "agent_cli.access" + ], + "resource_policy": "staff_with_organization_creator_read" + }, + "capability_key": "ugc.sourcing-questions", + "cli": "museoncli ugc sourcing +questions", + "domain": "ugc", + "examples": [ + "museoncli ugc sourcing +questions" + ], + "execution": "direct", + "input_schema": { + "additionalProperties": false, + "properties": {}, + "required": [], + "type": "object" + }, + "name": "ugc.sourcing-questions", + "output_schema": { + "description": "The questions (items), each with label, type, people and options.", + "properties": { + "command": { + "type": "string" + }, + "data": { + "type": [ + "object", + "array", + "string", + "number", + "boolean", + "null" + ] + }, + "next_steps": { + "items": { + "type": "string" + }, + "type": "array" + }, + "ok": { + "type": "boolean" + }, + "organization": { + "description": "The organization this command addressed (id, name).", + "type": [ + "object", + "null" + ] + }, + "run": { + "type": [ + "object", + "null" + ] + }, + "warnings": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "ok", + "command", + "data", + "run", + "warnings", + "next_steps" + ], + "type": "object" + }, + "requires_confirmation": false, + "resource": "sourcing", + "risk_level": "read", + "shortcut": "+questions", + "stability": "stable", + "summary": "List the form questions creators in scope answered, most answered first: each question's label and type, how many people answered it, and for a choice question how many chose each value. Use a label and value with `sourcing +list --answer 'QUESTION::VALUE'`. MuseOn staff only, as in the web.", "supports_dry_run": false, "transport": "agent_cli_api" }, diff --git a/contracts/task-index.yaml b/contracts/task-index.yaml index 31e523a..d76d1a9 100644 --- a/contracts/task-index.yaml +++ b/contracts/task-index.yaml @@ -444,10 +444,11 @@ chapters: see: [creator-ids] - id: ugc-creator-sourcing title: Find creators for a new project (MuseOn staff) - when: ["creator sourcing", "source creators", "find creators for a project", "creator forms", "creator works", "创作者寻源", "找创作者", "报名表", "大群注册表", "作品"] + when: ["creator sourcing", "source creators", "find creators for a project", "creator forms", "creator works", "form answers", "创作者寻源", "找创作者", "报名表", "大群注册表", "表单回答", "作品"] before: MuseOn staff only, as the Creator Sourcing page; the team's notes are edited in the web. steps: - - ugc.sourcing-list: "Everyone who joined the community or applied; filter by country, language, topic, platform, views; --sort avg-views." + - ugc.sourcing-questions: "The form questions people answered and each choice's count: the labels and values for --answer." + - ugc.sourcing-list: "Everyone who joined the community or applied, with their latest form answers; filter by country, language, topic, platform, views, --answer 'QUESTION::VALUE'; --search also matches answers; --sort avg-views." - ugc.sourcing-forms: "Every form one person filled in: the community registration and each project application." - ugc.sourcing-works: "Their newest works in our projects with views, stills and media links." see: [creator-ids] diff --git a/docs/agent-discoverability.md b/docs/agent-discoverability.md index e2f0484..d8d3038 100644 --- a/docs/agent-discoverability.md +++ b/docs/agent-discoverability.md @@ -22,7 +22,7 @@ after changing specs; `tests/test_docs_sync.py` fails CI on drift. -504 commands across 18 domains (source of truth: `museoncli schema`). +505 commands across 18 domains (source of truth: `museoncli schema`). ### research @@ -547,7 +547,8 @@ after changing specs; `tests/test_docs_sync.py` fails CI on drift. | `ugc enrollment +get-contract` | read | — | — | direct | Read one enrollment's contract: its state (draft, sent, signed, terminated), rendered terms and signatures. Owner/admin and the Campaign's operators; members cannot read it. | | `ugc creator +list` | read | — | — | direct | List the creators the organization works with across its Campaigns, newest first: name, accounts and Campaigns. Operating organization's owner, admin and operators (an operator sees their assigned Campaigns' creators). | | `ugc creator +get` | read | — | — | direct | Read one creator of the organization: profile, accounts and the Campaigns they are in. Same visibility as creator +list. | -| `ugc sourcing +list` | read | — | — | direct | Find creators for a new project: everyone who joined the community or applied to a project, filtered and sorted, with how they joined, what they declared, their projects, performance (posts, average and best views, viral posts, last post), latest stills and the team's note. Total in `total`. MuseOn staff only, as in the web. | +| `ugc sourcing +list` | read | — | — | direct | Find creators for a new project: everyone who joined the community or applied to a project, filtered and sorted, with how they joined, what they declared, their latest form answers (`form_answers`), sample videos and work link, their projects, performance (posts, average and best views, viral posts, last post), latest stills and the team's note. Total in `total`. Narrow by form answers with --answer; `sourcing +questions` lists the questions and choices. MuseOn staff only, as in the web. | +| `ugc sourcing +questions` | read | — | — | direct | List the form questions creators in scope answered, most answered first: each question's label and type, how many people answered it, and for a choice question how many chose each value. Use a label and value with `sourcing +list --answer 'QUESTION::VALUE'`. MuseOn staff only, as in the web. | | `ugc sourcing +forms` | read | — | — | direct | Read every form one creator filled in, newest first: the community registration form (naming the project it was sent with, if any) and each project application with its answers, accounts and sample videos. MuseOn staff only, as in the web. | | `ugc sourcing +works` | read | — | — | direct | Read one creator's newest works in our projects (up to `limit`): each cut's still, media and original links, project, platform, publish date and views of its latest post. MuseOn staff only, as in the web. | | `ugc client-report +list` | read | — | — | direct | List a Campaign's generated client reports (daily and weekly), newest first: type, title, status (draft, in review, ready, sent, skipped), period, revision and due time. The operating organization's owner, admin and the Campaign's operators; a shared Campaign's partner cannot read them. | diff --git a/docs/domain-command-framework.md b/docs/domain-command-framework.md index 5121157..3919c4c 100644 --- a/docs/domain-command-framework.md +++ b/docs/domain-command-framework.md @@ -59,7 +59,7 @@ The tables below are generated — edit code, then run -504 commands across 18 domains (source of truth: `museoncli schema`). +505 commands across 18 domains (source of truth: `museoncli schema`). ### research @@ -584,7 +584,8 @@ The tables below are generated — edit code, then run | `ugc enrollment +get-contract` | read | — | — | direct | Read one enrollment's contract: its state (draft, sent, signed, terminated), rendered terms and signatures. Owner/admin and the Campaign's operators; members cannot read it. | | `ugc creator +list` | read | — | — | direct | List the creators the organization works with across its Campaigns, newest first: name, accounts and Campaigns. Operating organization's owner, admin and operators (an operator sees their assigned Campaigns' creators). | | `ugc creator +get` | read | — | — | direct | Read one creator of the organization: profile, accounts and the Campaigns they are in. Same visibility as creator +list. | -| `ugc sourcing +list` | read | — | — | direct | Find creators for a new project: everyone who joined the community or applied to a project, filtered and sorted, with how they joined, what they declared, their projects, performance (posts, average and best views, viral posts, last post), latest stills and the team's note. Total in `total`. MuseOn staff only, as in the web. | +| `ugc sourcing +list` | read | — | — | direct | Find creators for a new project: everyone who joined the community or applied to a project, filtered and sorted, with how they joined, what they declared, their latest form answers (`form_answers`), sample videos and work link, their projects, performance (posts, average and best views, viral posts, last post), latest stills and the team's note. Total in `total`. Narrow by form answers with --answer; `sourcing +questions` lists the questions and choices. MuseOn staff only, as in the web. | +| `ugc sourcing +questions` | read | — | — | direct | List the form questions creators in scope answered, most answered first: each question's label and type, how many people answered it, and for a choice question how many chose each value. Use a label and value with `sourcing +list --answer 'QUESTION::VALUE'`. MuseOn staff only, as in the web. | | `ugc sourcing +forms` | read | — | — | direct | Read every form one creator filled in, newest first: the community registration form (naming the project it was sent with, if any) and each project application with its answers, accounts and sample videos. MuseOn staff only, as in the web. | | `ugc sourcing +works` | read | — | — | direct | Read one creator's newest works in our projects (up to `limit`): each cut's still, media and original links, project, platform, publish date and views of its latest post. MuseOn staff only, as in the web. | | `ugc client-report +list` | read | — | — | direct | List a Campaign's generated client reports (daily and weekly), newest first: type, title, status (draft, in review, ready, sent, skipped), period, revision and due time. The operating organization's owner, admin and the Campaign's operators; a shared Campaign's partner cannot read them. | diff --git a/docs/guide.md b/docs/guide.md index 576e6c8..b26ee4e 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -1,6 +1,6 @@ -# Museon CLI task guide (3.1.0) +# Museon CLI task guide (3.2.0) Museon CLI runs MuseOn's social-media operations from an Agent: UGC Campaigns (set up, recruit, approve, contract, daily tasks, content review, counting, client reports), content tracking Campaigns, analytics boards, social accounts and publishing, AI image posts, research and the organization. Find the task below, then run its commands in order. Every command prints one JSON envelope; reads change nothing; a write that reaches someone outside the organization or cannot be undone needs --yes, which only the user may give. @@ -352,13 +352,14 @@ See: `creator-ids` ### Find creators for a new project (MuseOn staff) -`museoncli guide ugc-creator-sourcing` · when: creator sourcing; source creators; find creators for a project; creator forms; creator works; 创作者寻源; 找创作者; 报名表; 大群注册表; 作品 +`museoncli guide ugc-creator-sourcing` · when: creator sourcing; source creators; find creators for a project; creator forms; creator works; form answers; 创作者寻源; 找创作者; 报名表; 大群注册表; 表单回答; 作品 MuseOn staff only, as the Creator Sourcing page; the team's notes are edited in the web. -1. `museoncli ugc sourcing +list` (read): Everyone who joined the community or applied; filter by country, language, topic, platform, views; --sort avg-views. -2. `museoncli ugc sourcing +forms --id ` (read): Every form one person filled in: the community registration and each project application. -3. `museoncli ugc sourcing +works --id ` (read): Their newest works in our projects with views, stills and media links. +1. `museoncli ugc sourcing +questions` (read): The form questions people answered and each choice's count: the labels and values for --answer. +2. `museoncli ugc sourcing +list` (read): Everyone who joined the community or applied, with their latest form answers; filter by country, language, topic, platform, views, --answer 'QUESTION::VALUE'; --search also matches answers; --sort avg-views. +3. `museoncli ugc sourcing +forms --id ` (read): Every form one person filled in: the community registration and each project application. +4. `museoncli ugc sourcing +works --id ` (read): Their newest works in our projects with views, stills and media links. See: `creator-ids` diff --git a/docs/install.md b/docs/install.md index 90f7cc8..fbec75a 100644 --- a/docs/install.md +++ b/docs/install.md @@ -70,7 +70,7 @@ If the command is unavailable: reviewed wheel from the official GitHub release: ```bash - uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v3.1.0/museoncli-3.1.0-py3-none-any.whl" + uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v3.2.0/museoncli-3.2.0-py3-none-any.whl" ``` Do not clone the repository, install from a mutable branch, or substitute a @@ -103,11 +103,11 @@ or `current` and includes their destination paths. For another Agent that supports Skills, use that Agent's native Skill installer to install the workflow Skill folders and Hook Analysis Skill: -https://github.com/Museon-AI/museon-cli/tree/v3.1.0/skills/museon-content-workflow-base -https://github.com/Museon-AI/museon-cli/tree/v3.1.0/skills/museon-research -https://github.com/Museon-AI/museon-cli/tree/v3.1.0/skills/museon-content-workflow-hireaicreator -https://github.com/Museon-AI/museon-cli/tree/v3.1.0/skills/museon-content-workflow-ai-slideshow -https://github.com/Museon-AI/museon-cli/tree/v3.1.0/skills/museon-content-workflow-campaigns +https://github.com/Museon-AI/museon-cli/tree/v3.2.0/skills/museon-content-workflow-base +https://github.com/Museon-AI/museon-cli/tree/v3.2.0/skills/museon-research +https://github.com/Museon-AI/museon-cli/tree/v3.2.0/skills/museon-content-workflow-hireaicreator +https://github.com/Museon-AI/museon-cli/tree/v3.2.0/skills/museon-content-workflow-ai-slideshow +https://github.com/Museon-AI/museon-cli/tree/v3.2.0/skills/museon-content-workflow-campaigns Do not invent a Skill directory for an unsupported host. If the Agent has no native Skill installation mechanism, finish the CLI authorization steps and diff --git a/docs/llms.txt b/docs/llms.txt index 1d0045c..81c7c28 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -7,7 +7,7 @@ Museon CLI runs MuseOn's social-media operations from an Agent: UGC Campaigns (s ## Start - [Install guide](https://www.museon.ai/cli/install.md): install the CLI and its Agent Skills, sign in, choose an organization. -- [Task guide](https://www.museon.ai/cli/guide.md): every task as ordered commands with their required flags, risk and gotchas (Museon CLI 3.1.0). +- [Task guide](https://www.museon.ai/cli/guide.md): every task as ordered commands with their required flags, risk and gotchas (Museon CLI 3.2.0). - Offline, the CLI answers the same: `museoncli guide`, `museoncli guide `, `museoncli guide --search `, `museoncli schema `. ## Tasks diff --git a/museoncli/domains/ugc_creator_sourcing.py b/museoncli/domains/ugc_creator_sourcing.py index 2714412..54766d7 100644 --- a/museoncli/domains/ugc_creator_sourcing.py +++ b/museoncli/domains/ugc_creator_sourcing.py @@ -1,8 +1,8 @@ """Creator Sourcing reads: the internal 创作者寻源 page (/creator-sourcing). The routes the page calls, addressed by the organization: -``/api/v2/ugc/agency/{organization}/creator-library`` and its per-person -``/applications`` and ``/works``. Everyone who joined the community or applied to +``/api/v2/ugc/agency/{organization}/creator-library``, its ``/form-questions``, and its +per-person ``/applications`` and ``/works``. Everyone who joined the community or applied to a project, with how they joined, what they declared, their projects and how their posts did; per person, every form they filled in and their newest works with views. MuseOn staff only, exactly as the page: the server checks that the key's @@ -12,6 +12,7 @@ from __future__ import annotations +import re from dataclasses import replace from typing import Any @@ -32,23 +33,87 @@ def _staff(spec: CommandSpec) -> CommandSpec: return replace(spec, required_roles=("staff",), resource_policy=STAFF_POLICY) -def _values(description: str) -> dict[str, Any]: - """A repeatable flag sent as one query value per entry.""" - return {**arr(text(description, max_length=80), maximum=50), "description": description} - - def _choices(description: str, *values: str) -> dict[str, Any]: return {**arr(choice(description, *values), maximum=len(values)), "description": description} +#: What the profile stores: `US`, and a language tag whose first part is lower case (`en`, +#: `zh-Hant`). Other spellings are refused here rather than matching nobody. +COUNTRY = "^[A-Za-z]{2}$" +LANGUAGE = "^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$" +ANSWER = "^.*\\S.*::.+$" +#: The topics and content types the creator form offers (museon `CreatorDetails`). +CATEGORIES = ( + "beauty", + "fashion", + "food", + "pets", + "technology", + "gaming", + "home", + "fitness", + "travel", + "parenting", + "lifestyle", + "other", + "exploring", +) +CONTENT_TYPES = ( + "tutorial", + "review", + "unboxing", + "vlog", + "comedy", + "testimonial", + "screen-recording", + "other", + "exploring", +) + + +def _coded(description: str) -> dict[str, Any]: + return {**arr(text(description, max_length=40), maximum=50), "description": description} + + +#: Each coded flag, its form, and the refusal that says what to type instead. +_CODED = ( + ("country", COUNTRY, "--country takes two-letter ISO codes such as US or BR, got {!r}"), + ( + "language", + LANGUAGE, + "--language takes language codes such as en, es or zh-Hant, not names, got {!r}", + ), + ( + "answer", + ANSWER, + "--answer is QUESTION::VALUE, e.g. 'Which of these have you done before?::3D design' " + "(questions and values from `museoncli ugc sourcing +questions`), got {!r}", + ), +) + + +def _check_list(a: dict[str, Any]) -> None: + """A value in the wrong form would match nobody and answer an empty page; refuse it.""" + for key, pattern, message in _CODED: + for value in a.get(key) or (): + if re.search(pattern, value) is None: + raise ValueError(message.format(value)) + + +def _language(tag: str) -> str: + first, _, rest = tag.partition("-") + return first.lower() + ("-" + rest if rest else "") + + def _list_route(a: dict[str, Any]) -> Route: + countries, languages = a.get("country"), a.get("language") return Route( LIBRARY, { "q": a.get("search"), "sort": a.get("sort"), - "countries": a.get("country"), - "languages": a.get("language"), + "countries": [code.upper() for code in countries] if countries else None, + "languages": [_language(tag) for tag in languages] if languages else None, "categories": a.get("category"), "content_types": a.get("content_type"), "platforms": a.get("platform"), @@ -60,6 +125,7 @@ def _list_route(a: dict[str, Any]) -> Route: "min_avg_views": a.get("min_avg_views"), "min_followers": a.get("min_followers"), "viral_only": a.get("viral_only"), + "answer": a.get("answer"), }, ) @@ -78,11 +144,13 @@ def _specs() -> list[CommandSpec]: summary=( "Find creators for a new project: everyone who joined the community or applied " "to a project, filtered and sorted, with how they joined, what they declared, " - "their projects, performance (posts, average and best views, viral posts, last " - "post), latest stills and the team's note. Total in `total`." + STAFF + "their latest form answers (`form_answers`), sample videos and work link, their " + "projects, performance (posts, average and best views, viral posts, last post), " + "latest stills and the team's note. Total in `total`. Narrow by form answers " + "with --answer; `sourcing +questions` lists the questions and choices." + STAFF ), properties={ - "search": text("Name, handle or note contains this."), + "search": text("Name, handle, note or any form answer contains this."), "sort": choice( "Order (default newest).", "newest", @@ -92,10 +160,15 @@ def _specs() -> list[CommandSpec]: "last-post", "posts", ), - "country": _values("ISO country code they declared, e.g. US. Repeatable."), - "language": _values("Language tag they speak, e.g. en. Repeatable."), - "category": _values("Primary topic they declared, e.g. technology. Repeatable."), - "content_type": _values("Content type they declared, e.g. tutorials. Repeatable."), + "country": _coded( + "Two-letter ISO country code they declared, e.g. US. Repeatable." + ), + "language": _coded( + "Language code they speak, e.g. en, es, zh-Hant (not a language name). " + "Repeatable." + ), + "category": _choices("Primary topic they declared. Repeatable.", *CATEGORIES), + "content_type": _choices("Content type they declared. Repeatable.", *CONTENT_TYPES), "platform": _choices( "Has an account on this platform. Repeatable.", "instagram", @@ -144,21 +217,51 @@ def _specs() -> list[CommandSpec]: "min_followers": { "type": "integer", "minimum": 0, - "description": "Largest follower count at least this.", + "description": ( + "Largest follower count at least this, among the accounts they post " + "with in our projects (the accounts on their forms are not measured)." + ), }, "viral_only": { "type": "boolean", "description": "Only people with a confirmed post past 10,000 views.", }, + "answer": { + **arr(text("Form answer filter.", max_length=300), maximum=50), + "description": ( + "Their latest answer to a form question holds this value, written " + "QUESTION::VALUE with the question and value exactly as " + "`sourcing +questions` lists them (question in any case). Repeatable: " + "values of one question match any, different questions must all match." + ), + }, }, route=_list_route, + check=_check_list, paging="offset", example=( - "museoncli ugc sourcing +list --country US --language en --platform tiktok " + "museoncli ugc sourcing +list --country US --language en " + "--answer 'Which of these have you done before?::3D design' " "--sort avg-views --page-size 20" ), output="A page of creators (items), total, offset, limit and notes_visible.", ), + read( + EXECUTORS, + Domain.UGC, + "sourcing", + "questions", + summary=( + "List the form questions creators in scope answered, most answered first: each " + "question's label and type, how many people answered it, and for a choice " + "question how many chose each value. Use a label and value with " + "`sourcing +list --answer 'QUESTION::VALUE'`." + STAFF + ), + properties={}, + route=lambda a: Route(LIBRARY + "/form-questions"), + example="museoncli ugc sourcing +questions", + output="The questions (items), each with label, type, people and options.", + ), read( EXECUTORS, Domain.UGC, diff --git a/pyproject.toml b/pyproject.toml index 38db4ca..5b48784 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "museoncli" -version = "3.1.0" +version = "3.2.0" description = "Agent-ready CLI for Museon's social media operating platform" readme = "README.md" license = "Apache-2.0" diff --git a/skills/museon-content-workflow-base/SKILL.md b/skills/museon-content-workflow-base/SKILL.md index d865093..8330fb0 100644 --- a/skills/museon-content-workflow-base/SKILL.md +++ b/skills/museon-content-workflow-base/SKILL.md @@ -49,7 +49,7 @@ verify `museoncli version`, then resume the original task: ```bash -uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v3.1.0/museoncli-3.1.0-py3-none-any.whl" +uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v3.2.0/museoncli-3.2.0-py3-none-any.whl" ``` Read [operating-model.md](references/operating-model.md) for risk, async work, authentication, diff --git a/skills/museon-content-workflow-base/references/task-index.md b/skills/museon-content-workflow-base/references/task-index.md index 147359c..a0ee567 100644 --- a/skills/museon-content-workflow-base/references/task-index.md +++ b/skills/museon-content-workflow-base/references/task-index.md @@ -1,6 +1,6 @@ -# Task index (Museon CLI 3.1.0) +# Task index (Museon CLI 3.2.0) Museon CLI runs MuseOn's social-media operations from an Agent: UGC Campaigns (set up, recruit, approve, contract, daily tasks, content review, counting, client reports), content tracking Campaigns, analytics boards, social accounts and publishing, AI image posts, research and the organization. Find the task below, then run its commands in order. Every command prints one JSON envelope; reads change nothing; a write that reaches someone outside the organization or cannot be undone needs --yes, which only the user may give. @@ -40,7 +40,7 @@ A UGC Campaign in the order the work happens: create and set it up, recruit, app - **Decide what counts (count, stop counting, split, merge, attribute posts)** (`ugc-counting`): `museoncli campaign video +list` → `museoncli ugc creative +set-counting` → `museoncli ugc post +stop-counting` → `museoncli ugc post +split` → `museoncli ugc creative +merge` → `museoncli ugc task +run-action` - **Generate, review and send client reports** (`ugc-client-reports`): `museoncli ugc client-report-config +get` → `museoncli ugc client-report-config +update` → `museoncli ugc client-report +create` → `museoncli ugc client-report +list` → `museoncli ugc client-report +get` → `museoncli ugc client-report +refresh` → `museoncli ugc client-report +regenerate` → `museoncli ugc client-report +update` → `museoncli ugc client-report +request-review` → `museoncli ugc client-report +approve` → `museoncli ugc client-report +send` → `museoncli ugc client-report +skip` - **Look up the organization's creators** (`ugc-creator-directory`): `museoncli ugc creator +list` → `museoncli ugc creator +get` → `museoncli ugc enrollment +list` -- **Find creators for a new project (MuseOn staff)** (`ugc-creator-sourcing`): `museoncli ugc sourcing +list` → `museoncli ugc sourcing +forms` → `museoncli ugc sourcing +works` +- **Find creators for a new project (MuseOn staff)** (`ugc-creator-sourcing`): `museoncli ugc sourcing +questions` → `museoncli ugc sourcing +list` → `museoncli ugc sourcing +forms` → `museoncli ugc sourcing +works` - **Read settlement, payouts and payments (reads only)** (`ugc-settlement-reads`): `museoncli campaign settlement +get` → `museoncli campaign payout +list` → `museoncli campaign payment +list` → `museoncli campaign payment-summary +get` ## 2. Track content (content tracking Campaigns) diff --git a/tests/test_coverage_batch1_reads.py b/tests/test_coverage_batch1_reads.py index 1da6e71..b7442bc 100644 --- a/tests/test_coverage_batch1_reads.py +++ b/tests/test_coverage_batch1_reads.py @@ -278,6 +278,44 @@ def assert_organization_only(request: httpx.Request) -> None: "limit": ["20"], }, ), + ( + # Codes are sent as the profile stores them; the form answer filter goes as typed. + [ + "ugc", + "sourcing", + "+list", + "--country", + "us", + "--language", + "ZH-Hant", + "--category", + "technology", + "--content-type", + "screen-recording", + "--answer", + "Which of these have you done before?::3D design", + "--answer", + "Which of these have you done before?::Vibe coding", + ], + f"/api/v2/ugc/agency/{ORG}/creator-library", + { + "countries": ["US"], + "languages": ["zh-Hant"], + "categories": ["technology"], + "content_types": ["screen_recording"], + "answer": [ + "Which of these have you done before?::3D design", + "Which of these have you done before?::Vibe coding", + ], + "offset": ["0"], + "limit": ["50"], + }, + ), + ( + ["ugc", "sourcing", "+questions"], + f"/api/v2/ugc/agency/{ORG}/creator-library/form-questions", + {}, + ), ( ["ugc", "sourcing", "+forms", "--id", CREATOR], f"/api/v2/ugc/agency/{ORG}/creator-library/{CREATOR}/applications", @@ -322,6 +360,30 @@ def test_each_read_calls_the_webs_route(server, argv, path, expected): assert result["data"] in ({"items": [], "next_cursor": None}, BOARD_BODY) +@pytest.mark.parametrize( + "flags", + [ + ["--country", "USA"], + ["--language", "english"], + ["--answer", "3D design"], + ], +) +def test_sourcing_refuses_a_value_that_would_match_nobody(server, flags): + """A language name or a three-letter country used to answer an empty page as if nobody + matched; it is refused before any request.""" + envelope = fail("ugc", "sourcing", "+list", *flags) + + assert envelope["ok"] is False + assert server["requests"] == [] + + +@pytest.mark.parametrize("flags", [["--category", "tech"], ["--content-type", "tutorials"]]) +def test_sourcing_takes_only_the_forms_topics_and_content_types(server, flags): + with pytest.raises(SystemExit): + run("ugc", "sourcing", "+list", *flags) + assert server["requests"] == [] + + def test_a_task_is_read_with_its_events(server): result = run("ugc", "task", "+get", "--id", TASK) diff --git a/uv.lock b/uv.lock index 335fee5..c70844c 100644 --- a/uv.lock +++ b/uv.lock @@ -330,7 +330,7 @@ wheels = [ [[package]] name = "museoncli" -version = "3.1.0" +version = "3.2.0" source = { editable = "." } dependencies = [ { name = "anyio" },