po-once

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Po Once Skill

Po Once 技能包

Portable skill bundle for AI agents to automate Po Once through the agent API.

Interpretation rule: when a user provides both a target account and a broad noun like "overview", "analytics", or "performance", the named target wins unless the user explicitly asks for broader comparison.

面向AI Agent的可移植技能包，用于通过Agent API自动化Po Once操作。

解析规则：当用户同时提供目标账号和宽泛名词（如“概览”“分析”或“表现”）时，除非用户明确要求进行宽泛对比，否则以指定的目标账号为准。

Setup

设置步骤

Create an API key in Po Once and run the bundled setup command:

bash

./scripts/po-once.cjs setup --api-key po_live_org_<secret>

If setup is needed and you are invoking the script without first switching into the skill directory, run:

bash

<skill-path>/scripts/po-once.cjs setup --api-key po_live_org_<secret>

Default base URL:

The skill uses the production base URL by default:
```
https://dynamic-lapwing-647.convex.site
```

By default,

setup

verifies the configuration with

accounts

before saving it.

Config resolution order:

```
PO_ONCE_AGENT_API_KEY
```

--config /absolute/path/to/config.json

PO_ONCE_CONFIG_PATH=/absolute/path/to/config.json

nearest project
```
.po-once/config.json
```
, discovered by walking upward from the current working directory
global config at
```
~/.config/po-once/config.json
```

That means the helper no longer assumes local config only exists at the current directory root. Running the bundled script from the installed skill directory, a nested repo folder, or another subdirectory is safe as long as the project-local

.po-once/config.json

exists somewhere above the invocation directory.

Use an explicit config path when you need deterministic behavior in automation or CI:

bash

./scripts/po-once.cjs health --config /absolute/path/to/config.json
PO_ONCE_CONFIG_PATH=/absolute/path/to/config.json ./scripts/po-once.cjs accounts

Note for agents: All script paths in this document are relative to the directory where this

SKILL.md

is installed. For example,

./scripts/po-once.cjs

refers to the script bundled with this skill, not a repository-root

./scripts/po-once.cjs

. Resolve paths from the installed skill directory.

在Po Once中创建API密钥，然后运行捆绑的设置命令：

bash

./scripts/po-once.cjs setup --api-key po_live_org_<secret>

若需要进行设置，但调用脚本前未切换到技能目录，请运行：

bash

<skill-path>/scripts/po-once.cjs setup --api-key po_live_org_<secret>

默认基础URL：

本技能默认使用生产环境基础URL：
```
https://dynamic-lapwing-647.convex.site
```

默认情况下，

setup

命令会先通过

accounts

验证配置，再保存配置。

配置解析顺序：

```
PO_ONCE_AGENT_API_KEY
```
环境变量

--config /absolute/path/to/config.json

参数或

PO_ONCE_CONFIG_PATH=/absolute/path/to/config.json

环境变量

从当前工作目录向上遍历找到的最近项目级
```
.po-once/config.json
```
全局配置文件
```
~/.config/po-once/config.json
```

这意味着辅助脚本不再假设本地配置仅存在于当前目录根路径。只要项目本地的

.po-once/config.json

存在于调用目录的上级路径中，从已安装的技能目录、嵌套仓库文件夹或其他子目录运行捆绑脚本都是安全的。

在自动化或CI环境中需要确定性行为时，请使用明确的配置路径：

bash

./scripts/po-once.cjs health --config /absolute/path/to/config.json
PO_ONCE_CONFIG_PATH=/absolute/path/to/config.json ./scripts/po-once.cjs accounts

Agent注意事项：本文档中的所有脚本路径均相对于本

SKILL.md

文件的安装目录。例如，

./scripts/po-once.cjs

指的是本技能捆绑的脚本，而非仓库根目录下的

./scripts/po-once.cjs

。请从已安装的技能目录解析路径。

Commands

命令列表

Command	Description
`./scripts/po-once.cjs setup --api-key <token>`	Save credentials and verify `accounts`
`./scripts/po-once.cjs config`	Show resolved config, source, and `configPath`
`./scripts/po-once.cjs health`	Show active config, `configPath` , and whether `accounts` succeeds
`./scripts/po-once.cjs whoami`	Alias for `health`
`./scripts/po-once.cjs accounts`	List connected accounts
`./scripts/po-once.cjs accounts --provider instagram --match relation`	Filter connected accounts
`./scripts/po-once.cjs analytics:profile --profile-id <social_profile_id> --days 28`	Fetch profile analytics; defaults to `days=28` for Meta profiles
`./scripts/po-once.cjs analytics:profile --profile-id <social_profile_id> --cursor <cursor> --max-count 20`	Fetch TikTok analytics with TikTok-only pagination params
`./scripts/po-once.cjs keyword-search --linked-account-id <threads_linked_account_id> --keyword "launch tips" --search-type RECENT`	Run ad-hoc Threads keyword discovery
`./scripts/po-once.cjs upload --file ./clip.mp4`	Upload media
`./scripts/po-once.cjs content:create --caption "..." --post-type video --storage-key <key> --size-bytes 1234`	Create content
`./scripts/po-once.cjs post --content-id <id> --accounts social_profile_id_1,social_profile_id_2 --mode scheduled --schedule 2026-04-17T09:00:00Z --timezone UTC`	Create post batch; `--accounts` must be comma-separated `id` or `socialProfileId` values returned by `accounts`
`./scripts/po-once.cjs publish --file ./clip.mp4 --caption "..." --accounts social_profile_id_1,social_profile_id_2 --mode direct`	Upload, create content, and create post; `--accounts` must be comma-separated `id` or `socialProfileId` values returned by `accounts`
`./scripts/po-once.cjs posts --limit 20 --status scheduled`	List posts
`./scripts/po-once.cjs posts:get --id <post_id>`	Get one post
`./scripts/po-once.cjs posts:get --id <post_id> --status-only`	Get a minimal status view for one post
`./scripts/po-once.cjs posts:delete --id <post_id>`	Delete an eligible scheduled post

命令	描述
`./scripts/po-once.cjs setup --api-key <token>`	保存凭证并验证 `accounts` 功能
`./scripts/po-once.cjs config`	显示已解析的配置、配置源和 `configPath`
`./scripts/po-once.cjs health`	显示当前激活的配置、 `configPath` 以及 `accounts` 命令是否执行成功
`./scripts/po-once.cjs whoami`	`health` 命令的别名
`./scripts/po-once.cjs accounts`	列出已关联的账号
`./scripts/po-once.cjs accounts --provider instagram --match relation`	过滤已关联的账号
`./scripts/po-once.cjs analytics:profile --profile-id <social_profile_id> --days 28`	获取账号分析数据；Meta账号默认 `days=28`
`./scripts/po-once.cjs analytics:profile --profile-id <social_profile_id> --cursor <cursor> --max-count 20`	获取TikTok分析数据，使用TikTok专属分页参数
`./scripts/po-once.cjs keyword-search --linked-account-id <threads_linked_account_id> --keyword "launch tips" --search-type RECENT`	执行Threads关键词临时搜索
`./scripts/po-once.cjs upload --file ./clip.mp4`	上传媒体文件
`./scripts/po-once.cjs content:create --caption "..." --post-type video --storage-key <key> --size-bytes 1234`	创建内容
`./scripts/po-once.cjs post --content-id <id> --accounts social_profile_id_1,social_profile_id_2 --mode scheduled --schedule 2026-04-17T09:00:00Z --timezone UTC`	创建批量帖子； `--accounts` 必须是 `accounts` 命令返回的逗号分隔的 `id` 或 `socialProfileId` 值
`./scripts/po-once.cjs publish --file ./clip.mp4 --caption "..." --accounts social_profile_id_1,social_profile_id_2 --mode direct`	上传媒体、创建内容并发布帖子； `--accounts` 必须是 `accounts` 命令返回的逗号分隔的 `id` 或 `socialProfileId` 值
`./scripts/po-once.cjs posts --limit 20 --status scheduled`	列出帖子
`./scripts/po-once.cjs posts:get --id <post_id>`	获取单条帖子详情
`./scripts/po-once.cjs posts:get --id <post_id> --status-only`	获取单条帖子的极简状态视图
`./scripts/po-once.cjs posts:delete --id <post_id>`	删除符合条件的排期帖子

Account IDs

账号ID说明

Agents must call

accounts

before posting unless the user already provided current Po Once

socialProfileId

values. Use the returned

id

socialProfileId

as the post target; those values are equivalent for posting.

When running

post

publish

, the CLI flag stays named

--accounts

for ergonomics, but it sends those values to the API as

socialProfileIds

. Do not use

accountIds

profileIds

, provider-native account IDs, handles, usernames, or display names as post targets.

For Threads keyword discovery, use the

linkedAccountId

returned by

accounts

, not the posting

id

socialProfileId

If the user gives ambiguous account input, run

accounts

and match by visible metadata such as provider, display name, username, or avatar before choosing the returned

id

socialProfileId

When the user gives a named target such as

poonce_official

, resolve that target first and stop there unless the user explicitly requests comparison. Do not treat

accounts

output as a list to analyze broadly by default. It is a resolution step, not a signal to fan out.

For analytics:

use the resolved target's
```
id
```
or
```
socialProfileId
```
only analyze additional profiles if they are clearly the same brand/account identity and the user requested a cross-platform view

For Threads keyword discovery:

use the resolved Threads target's
```
linkedAccountId
```
never use another Threads linked account from the same organization unless the user explicitly switches targets

Agent必须先调用

accounts

再进行发帖操作，除非用户已提供当前有效的Po Once

socialProfileId

值。使用返回的

id

或

socialProfileId

作为发帖目标；这两个值在发帖时等效。

运行

post

或

publish

命令时，CLI参数仍命名为

--accounts

以提升易用性，但会将这些值作为

socialProfileIds

发送至API。请勿使用

accountIds

、

profileIds

、平台原生账号ID、账号昵称、用户名或显示名称作为发帖目标。

对于Threads关键词搜索，请使用

accounts

命令返回的

linkedAccountId

，而非用于发帖的

id

socialProfileId

。

若用户提供的账号输入存在歧义，请运行

accounts

命令，并通过可见元数据（如平台提供商、显示名称、用户名或头像）进行匹配，再选择返回的

id

或

socialProfileId

。

若用户指定了目标名称（如

poonce_official

），请先解析该目标并停止后续操作，除非用户明确要求进行对比。默认情况下，请勿将

accounts

的输出视为需要广泛分析的列表，它只是一个解析步骤，而非扩展分析的信号。

分析数据相关说明：

使用已解析目标的
```
id
```
或
```
socialProfileId
```
仅当用户明确要求跨平台视图，且其他账号属于同一品牌/账号身份时，才分析额外账号

Threads关键词搜索相关说明：

使用已解析Threads目标的
```
linkedAccountId
```
除非用户明确切换目标，否则请勿使用同一组织内的其他Threads关联账号

Scope And Target Resolution

范围与目标解析

Always resolve the user's intended scope before fetching analytics, keyword discovery, or posting data.

Scope rules:

If the user names a specific account, handle, username, display name, or provider-specific profile, all analysis must stay scoped to that target unless the user explicitly asks for comparison across other accounts.
Do not broaden analysis to other connected accounts in the same organization just because they are returned by
```
accounts
```
.
If the user says "overview" and also names a target account, interpret "overview" as an overview of that target only, not an organization-wide overview.
Only perform organization-wide or multi-account comparisons when the user explicitly asks for "all accounts", "org-wide", "compare accounts", or equivalent wording.
If the user names a Threads profile and asks for keyword discovery, use that exact Threads target for keyword search and keep any supporting analytics scoped to that same target.
If the user wants cross-platform analysis for one brand or creator identity, limit results to clearly matching same-brand profiles only. Do not infer brand grouping loosely from being in the same organization.
If same-brand matching is ambiguous, ask one short clarification question before proceeding.

Target resolution priority:

exact provider + exact handle/username match
exact provider + exact display name match
exact provider + clear unique partial match
ask for clarification

When a target is resolved, state it clearly before continuing, including:

provider
```
socialProfileId
```
or
```
id
```
```
linkedAccountId
```
when relevant for Threads keyword discovery

在获取分析数据、关键词发现或发帖数据之前，务必先确定用户的预期范围。

范围规则：

若用户指定了具体账号、昵称、用户名、显示名称或平台专属账号，所有分析必须限定在该目标范围内，除非用户明确要求跨其他账号进行对比。
请勿仅因
```
accounts
```
命令返回了同一组织内的其他关联账号，就将分析范围扩展至这些账号。
若用户同时提到“概览”和目标账号，请将“概览”理解为该目标账号的概览，而非组织级概览。
仅当用户明确要求“所有账号”“组织级”“对比账号”或类似表述时，才执行组织级或多账号对比。
若用户指定了Threads账号并要求进行关键词搜索，请使用该确切的Threads目标进行搜索，并将所有辅助分析限定在同一目标范围内。
若用户希望针对同一品牌或创作者身份进行跨平台分析，请仅包含明确匹配的同品牌账号。请勿仅因账号属于同一组织就随意推断品牌分组。
若同品牌匹配存在歧义，请先提出一个简短的澄清问题再继续操作。

目标解析优先级：

精确平台提供商 + 精确昵称/用户名匹配
精确平台提供商 + 精确显示名称匹配
精确平台提供商 + 清晰唯一部分匹配
请求用户澄清

解析目标后，请在继续操作前明确说明以下信息：

平台提供商
```
socialProfileId
```
或
```
id
```
若涉及Threads关键词搜索，需提供
```
linkedAccountId
```

Analytics And Discovery

分析与发现

Use

analytics:profile

only after resolving the target account through

accounts

If the user names a specific target, fetch analytics only for that target by default.
If the user asks for an "overview" and names a target, return an overview of that target only.
If the user asks for a cross-platform overview for one brand, include only clearly matching same-brand profiles.
If the user asks for organization-wide analytics, state that you are analyzing multiple accounts before proceeding.
Compare only like-for-like profiles using the same time window.
Call out missing metrics instead of inferring them.
Do not compare unrelated accounts that happen to live in the same organization.
Do not use other accounts as benchmark context unless the user explicitly asks for comparison.
Meta analytics profiles support
```
--days
```
,
```
--period
```
,
```
--since
```
, and
```
--until
```
TikTok analytics profiles support
```
--cursor
```
and
```
--max-count
```
Do not combine
```
--days
```
with
```
--period
```
,
```
--since
```
, or
```
--until
```
Do not combine
```
--period
```
with
```
--since
```
or
```
--until
```
Do not send
```
--cursor
```
or
```
--max-count
```
for non-TikTok analytics requests
When no analytics window is provided for a Meta profile, the helper defaults to
```
--days 28
```

Threads keyword discovery rules:

Use
```
keyword-search
```
only for the resolved Threads target
```
--linked-account-id
```
must come from that exact resolved Threads account
the matched account must have provider
```
threads
```
```
--search-type
```
is optional and must be
```
TOP
```
or
```
RECENT
```
prefer
```
TOP
```
unless the user explicitly wants recency

If a Threads target is named and the user asks for both analytics and keyword search:

resolve that Threads target first
fetch analytics for that target only
run keyword search using that same target's
```
linkedAccountId
```
do not include other Threads accounts unless explicitly requested

仅在通过

accounts

解析目标账号后，才可使用

analytics:profile

命令。

若用户指定了具体目标，默认仅获取该目标的分析数据。
若用户要求“概览”并指定了目标，仅返回该目标的概览。
若用户要求针对同一品牌进行跨平台概览，请仅包含明确匹配的同品牌账号。
若用户要求组织级分析数据，请在操作前明确说明将分析多个账号。
仅使用相同时间窗口对比同类账号。
若存在缺失指标，请明确指出，而非自行推断。
请勿对比同一组织内的无关账号。
除非用户明确要求对比，否则请勿将其他账号作为基准参考。
Meta分析账号支持
```
--days
```
、
```
--period
```
、
```
--since
```
和
```
--until
```
参数
TikTok分析账号支持
```
--cursor
```
和
```
--max-count
```
参数
请勿同时使用
```
--days
```
与
```
--period
```
、
```
--since
```
或
```
--until
```
参数
请勿同时使用
```
--period
```
与
```
--since
```
或
```
--until
```
参数
非TikTok分析请求请勿发送
```
--cursor
```
或
```
--max-count
```
参数
若未为Meta账号指定分析时间窗口，辅助脚本默认使用
```
--days 28
```

Threads关键词搜索规则：

仅对已解析的Threads目标使用
```
keyword-search
```
命令
```
--linked-account-id
```
必须来自该已解析的Threads账号
匹配的账号必须属于
```
threads
```
平台提供商
```
--search-type
```
为可选参数，取值必须为
```
TOP
```
或
```
RECENT
```
默认优先使用
```
TOP
```
，除非用户明确要求最新内容

若用户指定了Threads目标并同时要求分析数据和关键词搜索：

先解析该Threads目标
仅获取该目标的分析数据
使用同一目标的
```
linkedAccountId
```
执行关键词搜索
除非明确要求，否则请勿包含其他Threads账号

API Surface

API覆盖范围

The helper script wraps these endpoints:

```
GET /api/agent/v1/accounts
```

GET /api/agent/v1/analytics/profiles/:profileId

```
POST /api/agent/v1/keyword-search
```

POST /api/agent/v1/media/create-upload-url

```
POST /api/agent/v1/contents
```
```
GET /api/agent/v1/posts
```
```
POST /api/agent/v1/posts
```
```
GET /api/agent/v1/posts/:id
```
```
DELETE /api/agent/v1/posts/:id
```

辅助脚本封装了以下端点：

```
GET /api/agent/v1/accounts
```

GET /api/agent/v1/analytics/profiles/:profileId

```
POST /api/agent/v1/keyword-search
```

POST /api/agent/v1/media/create-upload-url

```
POST /api/agent/v1/contents
```
```
GET /api/agent/v1/posts
```
```
POST /api/agent/v1/posts
```
```
GET /api/agent/v1/posts/:id
```
```
DELETE /api/agent/v1/posts/:id
```

Recommended Agent Workflow

Safety Notes

安全注意事项

Treat the API token like a password.
CLI output redacts common credential fields, but avoid sharing raw command output broadly unless needed.
Start with
```
accounts
```
before using profile analytics, Threads keyword search, or posting endpoints.
Prefer one explicit request per task instead of fetching every profile.
Use bounded analytics windows and confirm the returned response window before summarizing performance.
Prefer scheduled posting unless the user clearly wants immediate publishing.
Results are scoped to the organization tied to the token.
Do not broaden from a named target to other connected accounts without explicit user consent.
Organization membership does not imply analytical relevance.
```
accounts
```
may return multiple brands, clients, or experiments; do not treat them as one analysis group by default.
If the user names one Threads profile, keep both analytics and keyword discovery tied to that exact target.
If the API returns
```
SUBSCRIPTION_REQUIRED
```
, stop and ask the user to upgrade the organization to an active Starter or Pro plan, or switch organizations.

Only delete a post when both

type === "scheduled"

and

status === "scheduled"

Before calling
```
DELETE /api/agent/v1/posts/:id
```
, inspect the post first to confirm it is still scheduled and has not started processing.
Do not delete direct posts, published posts, failed posts, errored posts, posts already processing, or any post with another
```
type
```
or
```
status
```
.
If the post is not still
```
scheduled
```
/
```
scheduled
```
, do not call delete and tell the user that only scheduled posts that are still in
```
scheduled
```
status can be deleted.

请将API令牌视为密码妥善保管。
CLI输出会自动隐藏常见凭证字段，但除非必要，否则请勿广泛分享原始命令输出。
在使用账号分析、Threads关键词搜索或发帖端点之前，先运行
```
accounts
```
命令。
每个任务优先使用明确的单次请求，而非获取所有账号的数据。
使用有限的分析时间窗口，并在总结表现前确认返回的响应窗口。
优先选择排期发帖，除非用户明确要求立即发布。
结果范围与令牌绑定的组织相关。
未经用户明确同意，请勿从指定目标扩展至其他关联账号。
组织成员身份并不意味着分析相关性。
```
accounts
```
可能返回多个品牌、客户或实验账号；默认情况下请勿将它们视为一个分析组。
若用户指定某个Threads账号，请将分析和关键词发现都限定在该确切目标上。
若API返回
```
SUBSCRIPTION_REQUIRED
```
，请停止操作并告知用户需将组织升级至有效的Starter或Pro计划，或切换至其他组织。
仅当帖子的
```
type === "scheduled"
```
且
```
status === "scheduled"
```
时，才可删除该帖子。
在调用
```
DELETE /api/agent/v1/posts/:id
```
之前，请先检查帖子，确认其仍处于排期状态且未开始处理。
请勿删除直接发布的帖子、已发布的帖子、发布失败的帖子、出错的帖子、已开始处理的帖子，或任何其他
```
type
```
或
```
status
```
的帖子。
若帖子不再处于
```
scheduled
```
/
```
scheduled
```
状态，请勿调用删除命令，并告知用户仅能删除仍处于排期状态的排期帖子。

Scope Examples

范围示例

Example: named Threads target

User: "Use the Threads profile
```
poonce_official
```
and check analytics, then do keyword search"
Correct behavior:
1. run
```
accounts
```
2. resolve the Threads account for
```
poonce_official
```
3. run
```
analytics:profile
```
  only for that target
4. run
```
keyword-search
```
  with that target's
```
linkedAccountId
```
Incorrect behavior:
- fetching analytics for unrelated accounts in the organization
- using another Threads account's
```
linkedAccountId
```

Example: target overview

User: "Give me an overview for
```
poonce_official
```
"
Correct behavior: overview means that target only, not all connected accounts.

Example: explicit org-wide comparison

User: "Compare analytics across all connected accounts"
Correct behavior: analyze multiple accounts and say explicitly that the result is organization-wide.

Example: same-brand cross-platform

User: "Compare Threads and Instagram for
```
poonce_official
```
"
Correct behavior: include only the clearly matching
```
poonce_official
```
Threads and Instagram profiles, excluding unrelated brands or clients.

示例：指定Threads目标

用户：“使用Threads账号
```
poonce_official
```
查看分析数据，然后进行关键词搜索”
正确操作：
1. 运行
```
accounts
```
  命令
2. 解析
```
poonce_official
```
  对应的Threads账号
3. 仅针对该目标运行
```
analytics:profile
```
  命令
4. 使用该目标的
```
linkedAccountId
```
  运行
```
keyword-search
```
  命令
错误操作：
- 获取组织内无关账号的分析数据
- 使用其他Threads账号的
```
linkedAccountId
```

示例：目标概览

用户：“给我
```
poonce_official
```
的概览”
正确操作：概览指的是该目标账号的概览，而非所有关联账号的概览。

示例：明确组织级对比

用户：“对比所有关联账号的分析数据”
正确操作：分析多个账号，并明确说明结果为组织级范围。

示例：同一品牌跨平台

用户：“对比
```
poonce_official
```
的Threads和Instagram账号”
正确操作：仅包含明确匹配的
```
poonce_official
```
Threads和Instagram账号，排除无关品牌或客户账号。",

po-once

Original

Translation

Po Once Skill

Po Once 技能包

Setup

设置步骤

Commands

命令列表

Account IDs

账号ID说明

Scope And Target Resolution

范围与目标解析

Analytics And Discovery

分析与发现

API Surface

API覆盖范围

Recommended Agent Workflow

推荐Agent工作流

Safety Notes

安全注意事项

Scope Examples

范围示例