From 2cc3ee94a4ad147c0a2750d4c2a0c5eaa0bafe9d Mon Sep 17 00:00:00 2001 From: Mike Chen Date: Thu, 19 Nov 2026 16:02:14 +0800 Subject: [PATCH] feat(ugc): staff-only Creator Sourcing reads; prepare v3.1.0 `ugc sourcing +list`, `+forms --id` and `+works --id` call the internal Creator Sourcing page's own routes, addressed by the organization: the filtered, sorted list of everyone who joined the community or applied, each person's forms, and their newest works with views. Staff only, recorded as `required_roles: staff` and `resource_policy: staff_with_organization_creator_read`; the server enforces it (museon D-133). Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 10 + README.md | 2 +- README.zh-CN.md | 2 +- contracts/command-catalog.json | 540 +++++++++++++++++- contracts/task-index.yaml | 9 + docs/agent-discoverability.md | 5 +- docs/domain-command-framework.md | 5 +- docs/guide.md | 14 +- docs/install.md | 12 +- docs/llms.txt | 4 +- museoncli/domains/__init__.py | 2 + museoncli/domains/ugc_creator_sourcing.py | 194 +++++++ pyproject.toml | 2 +- skills/museon-content-workflow-base/SKILL.md | 2 +- .../references/task-index.md | 3 +- tests/test_coverage_batch1_reads.py | 62 ++ tests/test_surface_conventions.py | 5 + uv.lock | 2 +- 18 files changed, 857 insertions(+), 18 deletions(-) create mode 100644 museoncli/domains/ugc_creator_sourcing.py diff --git a/CHANGELOG.md b/CHANGELOG.md index ab12bb5..52a7978 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,16 @@ Museon CLI follows semantic versioning for its package and command contract. +## 3.1.0 + +Creator Sourcing for MuseOn staff, matching the internal `/creator-sourcing` page. Other domains are unchanged. + +- `ugc sourcing +list` finds creators for a new project: everyone who joined the community or applied, with how they joined, what they declared, their projects and performance. It takes the page's filters (country, language, topic, content type, platform, how they joined, cooperation, project, last post, note, minimum average views and followers, viral only), its sorts and offset paging. +- `ugc sourcing +forms --id` reads every form one person filled in: the community registration form and each project application. +- `ugc sourcing +works --id` reads their newest works in our projects with views, stills and media links. +- All three are staff only (`required_roles: staff`, `resource_policy: staff_with_organization_creator_read`). The CLI records that and does not enforce it: the server checks that the key's holder is staff and the key's organization holds creator read. The team's notes stay in the web. +- The command contract revision moves with the package to 3.1.0. Sync the API's vendored `agent_cli_command_catalog.json` to this revision before tagging. + ## 3.0.1 Staff-only HTML document management, matching the admin UI. Other domains are unchanged. diff --git a/README.md b/README.md index 263cd60..af8af01 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.0.1/museoncli-3.0.1-py3-none-any.whl" +uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v3.1.0/museoncli-3.1.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 c530324..e405312 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.0.1/museoncli-3.0.1-py3-none-any.whl" +uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v3.1.0/museoncli-3.1.0-py3-none-any.whl" ``` 安装成功后继续配置 Skills 和浏览器授权: diff --git a/contracts/command-catalog.json b/contracts/command-catalog.json index e9279d5..e1a656b 100644 --- a/contracts/command-catalog.json +++ b/contracts/command-catalog.json @@ -18425,6 +18425,87 @@ "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-list", + "cli": "museoncli ugc sourcing +list", + "domain": "ugc", + "execution": "direct", + "name": "ugc.sourcing-list", + "requires_confirmation": false, + "resource": "sourcing", + "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.", + "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-forms", + "cli": "museoncli ugc sourcing +forms", + "domain": "ugc", + "execution": "direct", + "name": "ugc.sourcing-forms", + "requires_confirmation": false, + "resource": "sourcing", + "risk_level": "read", + "shortcut": "+forms", + "stability": "stable", + "summary": "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.", + "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-works", + "cli": "museoncli ugc sourcing +works", + "domain": "ugc", + "execution": "direct", + "name": "ugc.sourcing-works", + "requires_confirmation": false, + "resource": "sourcing", + "risk_level": "read", + "shortcut": "+works", + "stability": "stable", + "summary": "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.", + "supports_dry_run": false, + "transport": "agent_cli_api" + }, { "authorization": { "authentication_required": true, @@ -18529,7 +18610,7 @@ "html-documents" ] }, - "contract_revision": "3.0.1", + "contract_revision": "3.1.0", "package": "museoncli", "schema_version": 3, "schemas": { @@ -89068,6 +89149,463 @@ "supports_dry_run": true, "transport": "agent_cli_api" }, + "ugc.sourcing-forms": { + "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-forms", + "cli": "museoncli ugc sourcing +forms", + "domain": "ugc", + "examples": [ + "museoncli ugc sourcing +forms --id " + ], + "execution": "direct", + "input_schema": { + "additionalProperties": false, + "properties": { + "id": { + "description": "UGC creator id from sourcing +list.", + "format": "uuid", + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "name": "ugc.sourcing-forms", + "output_schema": { + "description": "creator_id and the forms (items).", + "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": "+forms", + "stability": "stable", + "summary": "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.", + "supports_dry_run": false, + "transport": "agent_cli_api" + }, + "ugc.sourcing-list": { + "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-list", + "cli": "museoncli ugc sourcing +list", + "domain": "ugc", + "examples": [ + "museoncli ugc sourcing +list --country US --language en --platform tiktok --sort avg-views --page-size 20" + ], + "execution": "direct", + "input_schema": { + "additionalProperties": false, + "properties": { + "activity": { + "description": "When they last posted in our projects.", + "enum": [ + "all", + "within-7", + "within-30", + "within-90", + "inactive-30", + "inactive-90", + "never" + ], + "type": "string" + }, + "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.", + "items": { + "description": "Primary topic they declared, e.g. technology. Repeatable.", + "maxLength": 80, + "minLength": 1, + "type": "string" + }, + "maxItems": 50, + "minItems": 0, + "type": "array" + }, + "content_type": { + "description": "Content type they declared, e.g. tutorials. Repeatable.", + "items": { + "description": "Content type they declared, e.g. tutorials. Repeatable.", + "maxLength": 80, + "minLength": 1, + "type": "string" + }, + "maxItems": 50, + "minItems": 0, + "type": "array" + }, + "cooperation": { + "description": "Worked with us before or not.", + "enum": [ + "all", + "cooperated", + "working", + "never", + "pending" + ], + "type": "string" + }, + "country": { + "description": "ISO country code they declared, e.g. US. Repeatable.", + "items": { + "description": "ISO country code they declared, e.g. US. Repeatable.", + "maxLength": 80, + "minLength": 1, + "type": "string" + }, + "maxItems": 50, + "minItems": 0, + "type": "array" + }, + "language": { + "description": "Language tag they speak, e.g. en. Repeatable.", + "items": { + "description": "Language tag they speak, e.g. en. Repeatable.", + "maxLength": 80, + "minLength": 1, + "type": "string" + }, + "maxItems": 50, + "minItems": 0, + "type": "array" + }, + "min_avg_views": { + "description": "Average views of their confirmed posts at least this.", + "minimum": 0, + "type": "integer" + }, + "min_followers": { + "description": "Largest follower count at least this.", + "minimum": 0, + "type": "integer" + }, + "note": { + "description": "Whether the team wrote a note.", + "enum": [ + "all", + "with", + "without" + ], + "type": "string" + }, + "page": { + "description": "Page number, starting at 1.", + "minimum": 1, + "type": "integer" + }, + "page_size": { + "description": "Records per page (1-100, default 50).", + "maximum": 100, + "minimum": 1, + "type": "integer" + }, + "platform": { + "description": "Has an account on this platform. Repeatable.", + "items": { + "description": "Has an account on this platform. Repeatable.", + "enum": [ + "instagram", + "tiktok", + "youtube", + "facebook", + "x" + ], + "type": "string" + }, + "maxItems": 5, + "minItems": 0, + "type": "array" + }, + "search": { + "description": "Name, handle or note contains this.", + "maxLength": 200, + "minLength": 1, + "type": "string" + }, + "sort": { + "description": "Order (default newest).", + "enum": [ + "newest", + "avg-views", + "viral", + "followers", + "last-post", + "posts" + ], + "type": "string" + }, + "source": { + "description": "How they joined. Repeatable.", + "items": { + "description": "How they joined. Repeatable.", + "enum": [ + "community", + "community-referral", + "recruitment-link", + "creator-referral", + "apply-page", + "invitation", + "discord", + "import", + "unknown" + ], + "type": "string" + }, + "maxItems": 9, + "minItems": 0, + "type": "array" + }, + "viral_only": { + "description": "Only people with a confirmed post past 10,000 views.", + "type": "boolean" + } + }, + "required": [], + "type": "object" + }, + "name": "ugc.sourcing-list", + "output_schema": { + "description": "A page of creators (items), total, offset, limit and notes_visible.", + "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": "+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.", + "supports_dry_run": false, + "transport": "agent_cli_api" + }, + "ugc.sourcing-works": { + "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-works", + "cli": "museoncli ugc sourcing +works", + "domain": "ugc", + "examples": [ + "museoncli ugc sourcing +works --id " + ], + "execution": "direct", + "input_schema": { + "additionalProperties": false, + "properties": { + "id": { + "description": "UGC creator id from sourcing +list.", + "format": "uuid", + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "name": "ugc.sourcing-works", + "output_schema": { + "description": "creator_id, the works (items) and limit.", + "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": "+works", + "stability": "stable", + "summary": "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.", + "supports_dry_run": false, + "transport": "agent_cli_api" + }, "ugc.task-claim": { "authorization": { "authentication_required": true, diff --git a/contracts/task-index.yaml b/contracts/task-index.yaml index 20cb4e7..31e523a 100644 --- a/contracts/task-index.yaml +++ b/contracts/task-index.yaml @@ -442,6 +442,15 @@ chapters: - ugc.creator-get: "Profile, accounts and Campaigns of one person (UGC creator id)." - ugc.enrollment-list: "Their enrollment in one Campaign: --creator-id --detail for contract and Discord state." 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", "创作者寻源", "找创作者", "报名表", "大群注册表", "作品"] + 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-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] - id: ugc-settlement-reads title: Read settlement, payouts and payments (reads only) when: ["settlement", "payout", "payments", "how much to pay", "结算", "打款", "付款", "支付"] diff --git a/docs/agent-discoverability.md b/docs/agent-discoverability.md index d7633e0..e2f0484 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. -501 commands across 18 domains (source of truth: `museoncli schema`). +504 commands across 18 domains (source of truth: `museoncli schema`). ### research @@ -547,6 +547,9 @@ 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 +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. | | `ugc client-report +get` | read | — | — | direct | Read one client report in full: its Markdown, language variants, data scope, history and the actions the caller may take. Same visibility as client-report +list. | | `ugc client-report-config +get` | read | — | — | direct | Read a Campaign's client report settings: which reports are on, the client and internal groups they go to, schedule and language, with the settings' version that a settings write needs. Same visibility as client-report +list. | diff --git a/docs/domain-command-framework.md b/docs/domain-command-framework.md index a5834b5..5121157 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 -501 commands across 18 domains (source of truth: `museoncli schema`). +504 commands across 18 domains (source of truth: `museoncli schema`). ### research @@ -584,6 +584,9 @@ 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 +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. | | `ugc client-report +get` | read | — | — | direct | Read one client report in full: its Markdown, language variants, data scope, history and the actions the caller may take. Same visibility as client-report +list. | | `ugc client-report-config +get` | read | — | — | direct | Read a Campaign's client report settings: which reports are on, the client and internal groups they go to, schedule and language, with the settings' version that a settings write needs. Same visibility as client-report +list. | diff --git a/docs/guide.md b/docs/guide.md index 9b0d2e5..576e6c8 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -1,6 +1,6 @@ -# Museon CLI task guide (3.0.1) +# Museon CLI task guide (3.1.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. @@ -350,6 +350,18 @@ A report goes draft → request review → approve → send, or skip. Editing an 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; 创作者寻源; 找创作者; 报名表; 大群注册表; 作品 + +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. + +See: `creator-ids` + ### Read settlement, payouts and payments (reads only) `museoncli guide ugc-settlement-reads` · when: settlement; payout; payments; how much to pay; 结算; 打款; 付款; 支付 diff --git a/docs/install.md b/docs/install.md index 4eb9792..90f7cc8 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.0.1/museoncli-3.0.1-py3-none-any.whl" + uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v3.1.0/museoncli-3.1.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.0.1/skills/museon-content-workflow-base -https://github.com/Museon-AI/museon-cli/tree/v3.0.1/skills/museon-research -https://github.com/Museon-AI/museon-cli/tree/v3.0.1/skills/museon-content-workflow-hireaicreator -https://github.com/Museon-AI/museon-cli/tree/v3.0.1/skills/museon-content-workflow-ai-slideshow -https://github.com/Museon-AI/museon-cli/tree/v3.0.1/skills/museon-content-workflow-campaigns +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 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 c4a7ce6..1d0045c 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -7,13 +7,13 @@ 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.0.1). +- [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). - Offline, the CLI answers the same: `museoncli guide`, `museoncli guide `, `museoncli guide --search `, `museoncli schema `. ## Tasks - [0. Start here](https://www.museon.ai/cli/guide.md#0-start-here): Sign in, choose the organization, find a command, keep the CLI and its Skills current. Tasks: `login`, `choose-organization`, `find-a-command`, `keep-cli-current`. -- [1. Run a UGC Campaign](https://www.museon.ai/cli/guide.md#1-run-a-ugc-campaign): A UGC Campaign in the order the work happens: create and set it up, recruit, approve applications, contract, run the day's tasks and messages, review content, decide what counts, report to the client and read settlement. Tasks: `find-campaign`, `ugc-create-campaign`, `ugc-read-setup`, `ugc-change-setup`, `ugc-lifecycle`, `ugc-formats`, `ugc-personas`, `ugc-assign-formats`, `ugc-recruit`, `ugc-approve-applications`, `ugc-contract`, `ugc-manage-roster`, `ugc-daily-tasks`, `ugc-message-creator`, `ugc-nudge-creators`, `ugc-broadcast`, `ugc-team-reminders`, `ugc-review-content`, `ugc-counting`, `ugc-client-reports`, `ugc-creator-directory`, `ugc-settlement-reads`. +- [1. Run a UGC Campaign](https://www.museon.ai/cli/guide.md#1-run-a-ugc-campaign): A UGC Campaign in the order the work happens: create and set it up, recruit, approve applications, contract, run the day's tasks and messages, review content, decide what counts, report to the client and read settlement. Tasks: `find-campaign`, `ugc-create-campaign`, `ugc-read-setup`, `ugc-change-setup`, `ugc-lifecycle`, `ugc-formats`, `ugc-personas`, `ugc-assign-formats`, `ugc-recruit`, `ugc-approve-applications`, `ugc-contract`, `ugc-manage-roster`, `ugc-daily-tasks`, `ugc-message-creator`, `ugc-nudge-creators`, `ugc-broadcast`, `ugc-team-reminders`, `ugc-review-content`, `ugc-counting`, `ugc-client-reports`, `ugc-creator-directory`, `ugc-creator-sourcing`, `ugc-settlement-reads`. - [2. Track content (content tracking Campaigns)](https://www.museon.ai/cli/guide.md#2-track-content-content-tracking-campaigns): A content tracking Campaign follows creators' and posts' performance without applications or review. Tasks: `tracking-create`, `tracking-remove`, `tracking-performance`, `account-and-post-history`. - [3. Read Campaign analytics and boards](https://www.museon.ai/cli/guide.md#3-read-campaign-analytics-and-boards): The web Campaign Dashboard, tab by tab, keyed by the Campaign id; breakdowns by Format, persona and tag; the organization's analytics; multi-Campaign boards. Tasks: `dashboard`, `breakdown`, `org-analytics`, `boards`. - [4. Manage social accounts, publishing and cloud phones](https://www.museon.ai/cli/guide.md#4-manage-social-accounts-publishing-and-cloud-phones): The organization's own social accounts: connect, tag, read performance, edit profiles, publish videos and photo sets, and run the cloud phones and IPs behind them. Tasks: `accounts-list`, `accounts-connect`, `accounts-tags`, `accounts-performance`, `accounts-profile`, `publish-posts`, `cloud-phone-session`, `cloud-phone-fleet`, `cloud-phone-apps`, `cloud-phone-proxies`, `cloud-phone-recovery`. diff --git a/museoncli/domains/__init__.py b/museoncli/domains/__init__.py index 55368df..e3ee99c 100644 --- a/museoncli/domains/__init__.py +++ b/museoncli/domains/__init__.py @@ -73,6 +73,7 @@ ugc_campaign_setup, ugc_conversations, ugc_creators, + ugc_creator_sourcing, ugc_client_reports, analytics_boards, organization_settings, @@ -122,6 +123,7 @@ ugc_campaign_setup, ugc_conversations, ugc_creators, + ugc_creator_sourcing, ugc_client_reports, analytics_boards, organization_settings, diff --git a/museoncli/domains/ugc_creator_sourcing.py b/museoncli/domains/ugc_creator_sourcing.py new file mode 100644 index 0000000..2714412 --- /dev/null +++ b/museoncli/domains/ugc_creator_sourcing.py @@ -0,0 +1,194 @@ +"""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 +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 +holder is staff and that the key's organization holds creator read, and answers +not found otherwise. The team's notes are edited in a signed-in browser only. +""" + +from __future__ import annotations + +from dataclasses import replace +from typing import Any + +from museoncli.domains._model import CommandSpec, Domain +from museoncli.domains._org_reads import Route, choice, read, text, uuid +from museoncli.domains.hireaicreator import arr + +EXECUTORS: dict[str, Any] = {} + +LIBRARY = "/ugc/agency/{organization_id}/creator-library" +STAFF = " MuseOn staff only, as in the web." +#: Staff, with the organization's creator read: the page's own rule (museon D-133). The CLI +#: records it and does not enforce it; a caller who is not staff is the server's refusal. +STAFF_POLICY = "staff_with_organization_creator_read" + + +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} + + +def _list_route(a: dict[str, Any]) -> Route: + return Route( + LIBRARY, + { + "q": a.get("search"), + "sort": a.get("sort"), + "countries": a.get("country"), + "languages": a.get("language"), + "categories": a.get("category"), + "content_types": a.get("content_type"), + "platforms": a.get("platform"), + "sources": a.get("source"), + "cooperation": a.get("cooperation"), + "campaign_id": a.get("campaign_id"), + "activity": a.get("activity"), + "note": a.get("note"), + "min_avg_views": a.get("min_avg_views"), + "min_followers": a.get("min_followers"), + "viral_only": a.get("viral_only"), + }, + ) + + +def specs() -> list[CommandSpec]: + return [_staff(spec) for spec in _specs()] + + +def _specs() -> list[CommandSpec]: + return [ + read( + EXECUTORS, + Domain.UGC, + "sourcing", + "list", + 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 + ), + properties={ + "search": text("Name, handle or note contains this."), + "sort": choice( + "Order (default newest).", + "newest", + "avg-views", + "viral", + "followers", + "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."), + "platform": _choices( + "Has an account on this platform. Repeatable.", + "instagram", + "tiktok", + "youtube", + "facebook", + "x", + ), + "source": _choices( + "How they joined. Repeatable.", + "community", + "community-referral", + "recruitment-link", + "creator-referral", + "apply-page", + "invitation", + "discord", + "import", + "unknown", + ), + "cooperation": choice( + "Worked with us before or not.", + "all", + "cooperated", + "working", + "never", + "pending", + ), + "campaign_id": uuid("Only people in this project (UGC Campaign id)."), + "activity": choice( + "When they last posted in our projects.", + "all", + "within-7", + "within-30", + "within-90", + "inactive-30", + "inactive-90", + "never", + ), + "note": choice("Whether the team wrote a note.", "all", "with", "without"), + "min_avg_views": { + "type": "integer", + "minimum": 0, + "description": "Average views of their confirmed posts at least this.", + }, + "min_followers": { + "type": "integer", + "minimum": 0, + "description": "Largest follower count at least this.", + }, + "viral_only": { + "type": "boolean", + "description": "Only people with a confirmed post past 10,000 views.", + }, + }, + route=_list_route, + paging="offset", + example=( + "museoncli ugc sourcing +list --country US --language en --platform tiktok " + "--sort avg-views --page-size 20" + ), + output="A page of creators (items), total, offset, limit and notes_visible.", + ), + read( + EXECUTORS, + Domain.UGC, + "sourcing", + "forms", + summary=( + "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." + STAFF + ), + properties={"id": uuid("UGC creator id from sourcing +list.")}, + required=("id",), + route=lambda a: Route(LIBRARY + "/{id}/applications"), + example="museoncli ugc sourcing +forms --id ", + output="creator_id and the forms (items).", + ), + read( + EXECUTORS, + Domain.UGC, + "sourcing", + "works", + summary=( + "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." + STAFF + ), + properties={"id": uuid("UGC creator id from sourcing +list.")}, + required=("id",), + route=lambda a: Route(LIBRARY + "/{id}/works"), + example="museoncli ugc sourcing +works --id ", + output="creator_id, the works (items) and limit.", + ), + ] diff --git a/pyproject.toml b/pyproject.toml index 8171df3..38db4ca 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "museoncli" -version = "3.0.1" +version = "3.1.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 21b586d..d865093 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.0.1/museoncli-3.0.1-py3-none-any.whl" +uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v3.1.0/museoncli-3.1.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 d781a6b..147359c 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.0.1) +# Task index (Museon CLI 3.1.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,6 +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` - **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 34518d0..1da6e71 100644 --- a/tests/test_coverage_batch1_reads.py +++ b/tests/test_coverage_batch1_reads.py @@ -226,6 +226,68 @@ def assert_organization_only(request: httpx.Request) -> None: f"/api/v2/ugc/agency/{ORG}/creators/{CREATOR}", {}, ), + ( + ["ugc", "sourcing", "+list"], + f"/api/v2/ugc/agency/{ORG}/creator-library", + {"offset": ["0"], "limit": ["50"]}, + ), + ( + [ + "ugc", + "sourcing", + "+list", + "--search", + "maya", + "--sort", + "avg-views", + "--country", + "US", + "--country", + "BR", + "--language", + "en", + "--platform", + "tiktok", + "--source", + "community-referral", + "--activity", + "within-30", + "--min-avg-views", + "1000", + "--viral-only", + "--campaign-id", + CAMPAIGN, + "--page", + "2", + "--page-size", + "20", + ], + f"/api/v2/ugc/agency/{ORG}/creator-library", + { + "q": ["maya"], + "sort": ["avg_views"], + "countries": ["US", "BR"], + "languages": ["en"], + "platforms": ["tiktok"], + "sources": ["community_referral"], + "campaign_id": [CAMPAIGN], + "activity": ["within_30"], + "min_avg_views": ["1000"], + "viral_only": ["true"], + "offset": ["20"], + "limit": ["20"], + }, + ), + ( + ["ugc", "sourcing", "+forms", "--id", CREATOR], + f"/api/v2/ugc/agency/{ORG}/creator-library/{CREATOR}/applications", + {}, + ), + ( + ["ugc", "sourcing", "+works", "--id", CREATOR], + f"/api/v2/ugc/agency/{ORG}/creator-library/{CREATOR}/works", + {}, + ), ( ["analytics", "board", "+list"], "/api/v1/analytics-dashboards", diff --git a/tests/test_surface_conventions.py b/tests/test_surface_conventions.py index d9eb914..3ccada7 100644 --- a/tests/test_surface_conventions.py +++ b/tests/test_surface_conventions.py @@ -191,6 +191,7 @@ def test_command_specs_publish_auth_and_capability_metadata() -> None: spec.schema_name in STAFF_COMMANDS or spec.resource_policy == "staff_global_cloud_phone_management" or spec.resource_policy == "staff_with_organization_asset_access" + or spec.resource_policy == "staff_with_organization_creator_read" ): assert spec.required_roles == ("staff",) elif spec.schema_name in ADMIN_OR_STAFF_COMMANDS: @@ -200,6 +201,10 @@ def test_command_specs_publish_auth_and_capability_metadata() -> None: if spec.resource_policy == "staff_with_organization_asset_access": assert spec.domain.value == "html-documents" assert spec.organization_bound is True + elif spec.resource_policy == "staff_with_organization_creator_read": + assert spec.schema_name.startswith("ugc.sourcing-") + assert spec.risk_level == "read" + assert spec.organization_bound is True elif spec.resource_policy == "staff_global_cloud_phone_management": assert spec.organization_bound == ( spec.resource == "recovery" diff --git a/uv.lock b/uv.lock index f520074..335fee5 100644 --- a/uv.lock +++ b/uv.lock @@ -330,7 +330,7 @@ wheels = [ [[package]] name = "museoncli" -version = "3.0.1" +version = "3.1.0" source = { editable = "." } dependencies = [ { name = "anyio" },