@thinkingai/ae-cli 6.0.31 → 6.0.33

package/skills/ae-engage/references/activity-activity.md

@@ -0,0 +1,70 @@
+# engage-activity activity
+
+> Capability ids: `engage-activity.activity.{create,update,delete,list,get,pause,end,stats,info-list}` · Domain: `engage`.
+
+运营活动 - 活动主体管理。`create`/`update` 使用 `--payload` 直传后端 DTO（原生 camelCase 结构，`project_id` 单独作为参数）。
+
+## Commands
+
+```bash
+# Create an activity (draft)
+ae-cli engage-activity activity create --project-id <project_id> \
+  --payload '{"activityName":"a1","activityType":"other_type","tzOffset":99,"periodType":0}'
+
+# Update an activity
+ae-cli engage-activity activity update --project-id <project_id> \
+  --payload '{"activityId":"act-1","activityName":"a1","activityType":"other_type","tzOffset":99,"periodType":0}'
+
+# Delete an activity (draft/denied/ended only, high-risk)
+ae-cli engage-activity activity delete --project-id <project_id> --activity-id <activity_id> --yes
+
+# List activities
+ae-cli engage-activity activity list --project-id <project_id> [--fuzzy-field <text>] [--page 1] [--page-size 20]
+
+# Get an activity detail
+ae-cli engage-activity activity get --project-id <project_id> --activity-id <activity_id>
+
+# Pause / End an activity (write, no dry-run)
+ae-cli engage-activity activity pause --project-id <project_id> --activity-id <activity_id>
+ae-cli engage-activity activity end --project-id <project_id> --activity-id <activity_id>
+
+# Activity status distribution statistics
+ae-cli engage-activity activity stats --project-id <project_id> [--fuzzy-field <text>]
+
+# Query an activity's topics + standalone tasks
+ae-cli engage-activity activity info-list --project-id <project_id> --activity-id <activity_id>
+```
+
+## Parameters
+
+| Command | Required flags | Notes |
+|---|---|---|
+| create | `--project-id`, `--payload` | payload = `ActivityAddDTO`. |
+| update | `--project-id`, `--payload` | payload = `ActivityDTO` (`activityId` + base fields). |
+| delete | `--project-id`, `--activity-id` | high-risk; requires `--yes`; no dry-run. |
+| list | `--project-id` | `--fuzzy-field` / `--page` / `--page-size` optional. |
+| get | `--project-id`, `--activity-id` | read. |
+| pause | `--project-id`, `--activity-id` | write; no dry-run. |
+| end | `--project-id`, `--activity-id` | write; no dry-run. |
+| stats | `--project-id` | read; `--fuzzy-field` optional. |
+| info-list | `--project-id`, `--activity-id` | read. |
+
+## Output
+
+- `create` / `update`: `data.activity_id`.
+- `list`: `data.status_count`, `data.activity_list`, `data.pager_result`.
+- `get`: `data.activity`.
+- `stats`: `data.status_count`.
+- `info-list`: `data.info` with `taskList` (standalone tasks) and `topicList` (topics under the activity).
+- `delete` / `pause` / `end`: `data.success`.
+
+## Timezone (`tzOffset`)
+
+When the project has **timezone disabled**, use `tzOffset: 99` (server default sentinel) on create/update. Using `8` or other offsets returns `PROJECT_TIME_ZONE_NONE` when creating topics/tasks under the activity.
+
+When timezone is enabled, `tzOffset` must match one of the project's configured offsets. Keep activity `tzOffset` aligned with tasks/topics created under it.
+
+## Decision Rules
+
+- `delete` is `high-risk-write` and requires `--yes`; `pause`/`end` are state-changing `write` (no `--yes`) and do not support dry-run.
+- Discover real activity IDs via `list` first; never invent IDs.

package/skills/ae-engage/references/activity-approval.md

@@ -0,0 +1,53 @@
+# engage-activity approval
+
+> Capability ids: `engage-activity.approval.{submit,approve,reject,cancel}` · Domain: `engage`.
+
+运营活动 - 活动审批流。所有操作均针对活动（`ApprovalActivityIdDealDTO`：`projectId` + `activityId` + `reason`），均为状态变更 `write`，不支持 dry-run。`reject` 的 `reason` 必填；其余操作 `reason` 可选。
+
+## Commands
+
+```bash
+# Submit an activity for approval
+ae-cli engage-activity approval submit --project-id <project_id> --activity-id <activity_id>
+
+# Approve an activity
+ae-cli engage-activity approval approve --project-id <project_id> --activity-id <activity_id>
+
+# Reject an activity (reason required)
+ae-cli engage-activity approval reject --project-id <project_id> --activity-id <activity_id> --reason <reason>
+
+# Cancel/withdraw a submitted approval
+ae-cli engage-activity approval cancel --project-id <project_id> --activity-id <activity_id>
+```
+
+## Parameters
+
+| Command | Required flags | Notes |
+|---|---|---|
+| submit | `--project-id`, `--activity-id` | `--reason` optional. |
+| approve | `--project-id`, `--activity-id` | `--reason` optional. |
+| reject | `--project-id`, `--activity-id`, `--reason` | `--reason` required, max 72 characters. |
+| cancel | `--project-id`, `--activity-id` | `--reason` optional. |
+
+## Output
+
+- All actions: `data.success`.
+
+## Decision Rules
+
+- All approval actions are `write` (real state changes) and do not support dry-run; they do not require `--yes` (only `high-risk-write` does).
+- Approve/reject require the caller to be a valid approver of the activity (enforced server-side).
+
+## Common Errors
+
+| code | when |
+|---|---|
+| `ACTIVITY_NOT_FOUND` | activity id missing in project |
+| `ACTIVITY_NO_APPROVAL_TASK` | submit with no standalone/topic tasks |
+| `ACTIVITY_STATUS_INVALID` | activity not in draft/pending |
+| `APPROVAL_NOT_PENDING` | no under-approval record |
+| `NOT_APPROVER` | caller is not a project approver |
+| `REASON_REQUIRED` | reject without `--reason` |
+| `REASON_TOO_LONG` | reject reason longer than 72 characters |
+| `CAPABILITY_PERMISSION_DENIED` | cancel caller is neither owner nor ops-manage-other-assets |
+| `TOO_FREQUENT` | concurrent approve/submit lock conflict |

package/skills/ae-engage/references/activity-task.md

@@ -0,0 +1,87 @@
+# engage-activity task
+
+> Capability ids: `engage-activity.task.{get,copy}` · Domain: `engage`.
+>
+> Temporarily disabled: `task create` / `task update` (command registration + skill guidance).
+
+运营活动 - 独立任务（活动下不属于主题的任务）。`copy` 读取源任务详情、改名后重新创建（无后端复制 API）。
+
+## Commands
+
+```bash
+# Get a standalone task detail
+ae-cli engage-activity task get --project-id <project_id> --task-id <task_id>
+
+# Copy a standalone task (loads detail, renames, re-creates)
+ae-cli engage-activity task copy --project-id <project_id> --task-id <task_id> [--new-name <name>]
+```
+
+<!-- Temporarily disabled: task create / task update
+```bash
+# Create a standalone task under an activity (webhook + existing cluster)
+ae-cli engage-activity task create --project-id <project_id> \
+  --payload '{ ... }'
+
+# Update a standalone task
+ae-cli engage-activity task update --project-id <project_id> \
+  --payload '{"taskId":"task-1","taskName":"t1", ...}'
+```
+-->
+
+## Parameters
+
+| Command | Required flags | Notes |
+|---|---|---|
+| get | `--project-id`, `--task-id` | read. |
+| copy | `--project-id`, `--task-id` | `--new-name` optional (default source name + `_copy`). |
+
+<!-- Temporarily disabled
+| create | `--project-id`, `--payload` | payload = `OperationTaskOpDTO`; set `activityId`, leave `topicId` empty. |
+| update | `--project-id`, `--payload` | payload = `OperationTaskOpDTO` including `taskId`. |
+-->
+
+## Output
+
+- `get`: `data.task`.
+- `copy`: `data.task_id`, optional `data.trigger_time_stale` (true when source schedule-single time is already past).
+
+## Payload notes (for copy / detail shape)
+
+### Channel content
+
+- `channelType` `1` = webhook, `2` = app_push, `3` = client_push, `4` = wechat, `5` = dou_yin`.
+- `groupContentList[].contentList[].content` must be a JSON **array string**.
+- **TEXT (rich text) params** must include both `value` and `config` (Slate.js JSON **string**). If `config` is missing, Hermes copy auto-fills  
+  `config = [{"type":"paragraph","children":[{"text":"<value>"}]}]` as a JSON string.
+
+### Audience (`targetClusterType`)
+
+| Value | Required | Notes |
+|---|---|---|
+| `2` (existed) | `clusterKey` | From `analysis user-cluster list/get`. |
+| `1` (custom) | `qp` | JSON object string. |
+| `3` (all) | — | Do not pass `clusterKey` or `qp`. |
+
+## Decision Rules
+
+- Discover a real `task_id` via `get`/activity `info-list` first; never invent IDs.
+- `copy` duplicates the editable task config (not runtime/trigger state).
+- `copy` saves via **draft** add (`draft=true`), so a past schedule-single `triggerTime` is allowed; output may include `trigger_time_stale=true`. Update the time before `approval submit`.
+- Standalone tasks must **not** include `topicId`; topic tasks use `engage-activity topic copy` (topic create/update are temporarily disabled).
+
+## Copy errors
+
+`copy` = get detail → rename → draft `add` (no dedicated copy API). Prefer actionable codes over `INVALID_CAPABILITY_REQUEST`:
+
+| code | when |
+|---|---|
+| `TASK_NOT_FOUND` | source `task_id` missing |
+| `TASK_PROJECT_MISMATCH` | task exists but not in `--project-id` |
+| `TOPIC_TASK_FORBIDDEN` | source has `topicId` (use `topic copy`) |
+| `ACTIVITY_ID_REQUIRED` | source has no `activityId` (not a standalone activity task) |
+| `TRIGGER_TIME_REQUIRED` | schedule-single missing `triggerTime` |
+| `CHANNEL_NOT_FOUND` | source channel missing / type mismatch |
+| `TASK_COUNT_LIMIT` | project task count limit exceeded |
+| `RCC_SERVER_REQUIRED` | client push (`channelType=3`) but RCC server is not installed |
+
+Past `triggerTime` no longer fails copy; check `data.trigger_time_stale` and fix before approval. Unmapped domain `PARAMETER_ERROR` may still return `INVALID_CAPABILITY_REQUEST` with a readable fallback message.

package/skills/ae-engage/references/activity-topic.md

@@ -0,0 +1,98 @@
+# engage-activity topic
+
+> Capability ids: `engage-activity.topic.{remove-task,delete,get,copy}` · Domain: `engage`.
+>
+> Temporarily disabled: `topic create` / `topic update` (command registration + skill guidance).
+
+Activity topics and tasks under a topic. `copy` loads the source topic, renames it, and re-creates (no dedicated backend copy API).
+
+## Commands
+
+```bash
+# Remove a task from its topic (high-risk)
+ae-cli engage-activity topic remove-task --project-id <project_id> --task-id <task_id> --yes
+
+# Delete a topic (high-risk)
+ae-cli engage-activity topic delete --project-id <project_id> --topic-id <topic_id> --yes
+
+# Get a topic detail
+ae-cli engage-activity topic get --project-id <project_id> --topic-id <topic_id>
+
+# Copy a topic (loads detail, renames, re-creates)
+ae-cli engage-activity topic copy --project-id <project_id> --topic-id <topic_id> [--new-name <name>]
+```
+
+<!-- Temporarily disabled: topic create / topic update
+```bash
+# Create a topic and its tasks under an activity
+ae-cli engage-activity topic create --project-id <project_id> --payload '{ ... }'
+
+# Update a topic and its task relations
+ae-cli engage-activity topic update --project-id <project_id> --payload '{"topicId":"topic-1", ...}'
+```
+-->
+
+## Parameters
+
+| Command | Required flags | Notes |
+|---|---|---|
+| remove-task | `--project-id`, `--task-id` | high-risk; requires `--yes`; no dry-run. Only tasks with a non-empty `topicId`. |
+| delete | `--project-id`, `--topic-id` | high-risk; requires `--yes`; no dry-run. |
+| get | `--project-id`, `--topic-id` | read. |
+| copy | `--project-id`, `--topic-id` | `--new-name` optional (default source name + `_copy`). |
+
+<!-- Temporarily disabled
+| create | `--project-id`, `--payload` | payload = `TopicAddDTO` (camelCase). |
+| update | `--project-id`, `--payload` | payload = `TopicModifyReq` (`topicId` + fields + task lists). |
+-->
+
+## Notes for get / copy
+
+TEXT (rich text) params inside `groupContentList[].contentList[].content` need both `value` and Slate `config` (JSON string). If `config` is omitted, Hermes copy auto-fills  
+`[{"type":"paragraph","children":[{"text":"<value>"}]}]`. See `activity-task.md` Channel content.
+
+Topic-level audience uses `topicClusterKey` / `topicQp`; do **not** pass task-level `clusterKey` at topic root.
+
+## Output
+
+- `get`: `data.topic` (includes `topicClusterKey` for topic audience).
+- `remove-task` / `delete` / `copy`: `data.success`.
+- `copy` may include `data.trigger_time_stale=true` when source schedule-single time is already past.
+
+## Decision Rules
+
+- `remove-task` and `delete` are `high-risk-write` — require `--yes`, no dry-run.
+- `remove-task` only deletes **topic tasks** (`topicId` present). Standalone tasks → use `engage-task task delete`.
+- `copy` duplicates the editable topic config and its tasks (not runtime/approval state).
+- `copy` saves via **draft** add (`isDraft=true`), so a past schedule-single `triggerTime` is allowed; output may include `trigger_time_stale=true`. Update the time before `approval submit`.
+- Prefer `topic get` as a template when inspecting channel/content fields.
+
+## Copy errors
+
+`copy` = get topic detail → rename → draft `addTopicAndTask` (no dedicated copy API). Prefer actionable codes over `INVALID_CAPABILITY_REQUEST` / mismatched i18n text like "Campaign does not exist.":
+
+| code | when |
+|---|---|
+| `TOPIC_NOT_FOUND` | source `topic_id` missing |
+| `TOPIC_PROJECT_MISMATCH` | topic exists but not in `--project-id` |
+| `ACTIVITY_ID_REQUIRED` | source topic detail has no `activityId` |
+| `ACTIVITY_NOT_FOUND` | parent activity missing / deleted / wrong project |
+| `TOPIC_TASKS_REQUIRED` | source topic has no tasks |
+| `ACTIVITY_STATUS_INVALID` | parent activity is approving/working/complete |
+| `TOPIC_COUNT_LIMIT` | activity topic count limit exceeded |
+| `CHANNEL_NOT_FOUND` | source channel missing / type mismatch |
+| `TASK_COUNT_LIMIT` | project task count limit exceeded |
+| `RCC_SERVER_REQUIRED` | client push (`channelType=3`) but RCC server is not installed |
+| `TRIGGER_TIME_REQUIRED` | schedule-single missing `triggerTime` |
+
+Past `triggerTime` no longer fails copy; check `data.trigger_time_stale` and fix before approval.
+
+## remove-task errors
+
+| code | when |
+|---|---|
+| `TASK_NOT_FOUND` | `--task-id` missing |
+| `TASK_PROJECT_MISMATCH` | task exists but not in `--project-id` |
+| `NOT_TOPIC_TASK` | task has no `topicId` (standalone); use `engage-task task delete` |
+| `TASK_WORKING` | topic task `mappingStatus=working`; pause/end first |
+| `TASK_APPROVING` | topic task pending approval; withdraw first |

package/skills/ae-engage/references/approval-approver-delete.md

@@ -0,0 +1,26 @@
+# engage-setting approval-approver delete
+
+> Capability id: `engage-setting.approval-approver.delete` · Domain: `engage`.
+
+## Command
+
+```bash
+ae-cli engage-setting approval-approver delete --project-id <project_id> --approver <open_id> --yes
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--approver` | Yes | OpenID of the approver to remove. |
+
+## Output
+
+- `data.success`: whether the approver was removed.
+
+## Decision Rules
+
+- Use this command when the user asks to remove/delete an approver from a project.
+- Discover the real approver OpenID with `ae-cli engage +approver_list --project_id <project_id>` first; never invent an OpenID.
+- Risk is `high-risk-write`; the CLI confirmation gate requires `--yes` (or interactive confirmation) before executing.

package/skills/ae-engage/references/channel-test-send.md

@@ -0,0 +1,37 @@
+# engage-setting channel test-send
+
+> Capability id: `engage-setting.channel.test-send` · Domain: `engage`.
+
+## Command
+
+```bash
+ae-cli engage-setting channel test-send \
+  --project-id <project_id> --channel-id <channel_id> --push-id <send_id> \
+  --content-list '[{"key":"title","value":"hello"}]' \
+  [--user-params-list '<json_array>'] [--push-environment dev|pro] \
+  [--mock-push] [--channel-template-id <id>]
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--channel-id` | Yes | Channel ID to test. |
+| `--push-id` | Yes | Recipient send ID (e.g. a test device id). |
+| `--content-list` | Yes | JSON array of key/value content pairs, e.g. `[{"key":"title","value":"hello"}]`. |
+| `--user-params-list` | No | JSON array of custom user params for the test push. |
+| `--push-environment` | No | Push environment: `dev` or `pro`. |
+| `--mock-push` | No | Mock the push (build request only, do not send). |
+| `--channel-template-id` | No | WeChat channel template ID. |
+
+## Output
+
+- `data.push_succeeded`: whether the test push succeeded.
+
+## Decision Rules
+
+- Use this command when the user asks to send a test message to a channel / verify channel delivery.
+- Discover the real channel id with `ae-cli engage +channel_list` first; never invent a channel id.
+- `--mock-push` is useful to inspect the request body/headers without actually delivering a message.
+- Risk is `write`; sending a real test push to a recipient is a write action.

package/skills/ae-engage/references/channel-touch-limits-batch-update.md

@@ -0,0 +1,28 @@
+# engage-setting channel-touch-limits batch-update
+
+> Capability id: `engage-setting.channel-touch-limits.batch-update` · Domain: `engage`.
+
+## Command
+
+```bash
+ae-cli engage-setting channel-touch-limits batch-update \
+  --project-id <project_id> \
+  --items '[{"rule_id":"r1","enable":true,"rule_def":"[]"},{"rule_id":"r2","enable":false,"rule_def":"[]"}]'
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--items` | Yes | JSON array of rule updates. Each item: `rule_id`, `enable` (boolean), `rule_def` (rule definition JSON string). |
+
+## Output
+
+- `data.success`: whether the batch update succeeded.
+
+## Decision Rules
+
+- Use this command when the user asks to batch edit/update multiple touch-limit (fatigue-control) rules at once.
+- Discover existing rule IDs with `ae-cli engage-setting channel-touch-limits list --project-id <project_id>` first; never invent rule IDs.
+- Risk is `write`; ordinary update, no confirmation gate.

package/skills/ae-engage/references/channel-touch-limits-save.md

@@ -0,0 +1,37 @@
+# engage-setting channel-touch-limits save
+
+> Capability id: `engage-setting.channel-touch-limits.save` · Domain: `engage`.
+
+## Command
+
+```bash
+# Create a new touch-limit rule (omit --rule-id)
+ae-cli engage-setting channel-touch-limits save \
+  --project-id <project_id> --channel-biz-type <biz_type> \
+  --rule-def '<rule_def_json>' --enable true
+
+# Update an existing touch-limit rule (provide --rule-id)
+ae-cli engage-setting channel-touch-limits save \
+  --project-id <project_id> --channel-biz-type <biz_type> \
+  --rule-def '<rule_def_json>' --enable false --rule-id <rule_id>
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--channel-biz-type` | Yes | Channel business type the rule belongs to. |
+| `--rule-def` | Yes | Touch-limit rule definition (JSON string, see ChannelTouchLimitRuleDTO). |
+| `--enable` | Yes | Whether the touch-limit rule is enabled. |
+| `--rule-id` | No | Existing rule ID. When omitted a new rule is created. |
+
+## Output
+
+- `data.success`: whether the save succeeded.
+
+## Decision Rules
+
+- Use this command when the user asks to create or update a single touch-limit (fatigue-control) rule.
+- For updates, discover the real rule ID with `ae-cli engage-setting channel-touch-limits list --project-id <project_id>` first.
+- Risk is `write`; ordinary write, no confirmation gate.

package/skills/ae-engage/references/channel-touch-limits-toggle.md

@@ -0,0 +1,28 @@
+# engage-setting channel-touch-limits toggle
+
+> Capability id: `engage-setting.channel-touch-limits.toggle` · Domain: `engage`.
+
+## Command
+
+```bash
+ae-cli engage-setting channel-touch-limits toggle \
+  --project-id <project_id> --rule-id <rule_id> --enable <true|false>
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--rule-id` | Yes | Touch-limit rule ID to enable/disable. |
+| `--enable` | Yes | Whether the touch-limit rule is enabled. |
+
+## Output
+
+- `data.success`: whether the toggle succeeded.
+
+## Decision Rules
+
+- Use this command when the user asks to enable or disable a single touch-limit (fatigue-control) rule.
+- Discover the real rule ID with `ae-cli engage-setting channel-touch-limits list --project-id <project_id>` first.
+- Risk is `write`; ordinary update, no confirmation gate.

package/skills/ae-engage/references/channel-update-config.md

@@ -0,0 +1,36 @@
+# engage-setting channel update-config
+
+> Capability id: `engage-setting.channel.update-config` · Domain: `engage`.
+
+## Command
+
+```bash
+ae-cli engage-setting channel update-config \
+  --project-id <project_id> --channel-id <channel_id> --enable-touch-event <0|1> \
+  [--channel-name <name>] [--push-id-type <prop>] [--config '<json_string>'] \
+  [--touch-event-source <src>] [--event-delivery-name <name>] [--event-click-name <name>]
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--channel-id` | Yes | Channel ID to update. |
+| `--enable-touch-event` | Yes | Reach funnel toggle: `1` enabled, `0` disabled. |
+| `--channel-name` | No | New channel name. |
+| `--push-id-type` | No | User property used as the push ID. |
+| `--config` | No | Channel-specific JSON config string (see ChannelConfigDTO). |
+| `--touch-event-source` | No | Reach event source. |
+| `--event-delivery-name` | No | Actual delivery event name. |
+| `--event-click-name` | No | Click event name. |
+
+## Output
+
+- `data.success`: whether the channel config was updated.
+
+## Decision Rules
+
+- Use this command when the user asks to edit/update an existing channel's name, config, push-id type, or reach-funnel settings.
+- `--config` is the channel-specific JSON config; discover the existing config with `ae-cli engage +channel_detail` first rather than inventing it.
+- Risk is `write`; ordinary update, no confirmation gate.

package/skills/ae-engage/references/client-param.md

@@ -0,0 +1,58 @@
+# engage-setting client-param
+
+> Capability ids: `engage-setting.client-param.{update,delete,list}` · Domain: `engage`. (`create` temporarily disabled in CLI.)
+
+## Commands
+
+```bash
+# Update a custom client param
+ae-cli engage-setting client-param update \
+  --project-id <project_id> --column-name <name> --column-type <type> --select-type <select> \
+  [--column-desc <desc>]
+
+# Delete a custom client param (high-risk)
+ae-cli engage-setting client-param delete --project-id <project_id> --column-name <name> --yes
+
+# List custom client params
+ae-cli engage-setting client-param list --project-id <project_id>
+```
+
+## Parameters
+
+### update
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--column-name` | Yes | Client param column name. |
+| `--column-type` | Yes | Column type (see ColumnTypeEnum). |
+| `--select-type` | Yes | Select type (see SelectTypeEnum). |
+| `--column-source` | No | Param source: preset or custom. |
+| `--column-desc` | No | Display name of the param. Defaults to an empty string. |
+| `--column-remark` | No | Description/remark for the param. |
+| `--alternative-val` | No | JSON array of alternative values. |
+| `--system-id-param` | No | Whether this is a system identifier param. |
+
+### delete
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--column-name` | Yes | Client param column name to delete. |
+
+### list
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+
+## Output
+
+- `update`: `data.success` — whether the operation succeeded.
+- `delete`: `data.success` and `data.task_list` (tasks still referencing the param, which block deletion; each item has `task_id`, `task_name`).
+- `list`: `data.items` (each with `column_name`, `column_type`, `select_type`, `column_source`, `column_desc`, `column_remark`, `alternative_val`, `system_id_param`) and `data.total`.
+
+## Decision Rules
+
+- Use these commands when the user asks to manage custom client params (客户端参数).
+- `delete` is `high-risk-write` and requires `--yes` (or interactive confirmation). When `data.success` is false, `data.task_list` lists tasks that still reference the param — report them instead of forcing deletion.

package/skills/ae-engage/references/common-metric.md

@@ -0,0 +1,75 @@
+# engage-setting common-metric
+
+> Capability ids: `engage-setting.common-metric.{list,get,update,delete}` · Domain: `engage`. (`create` temporarily disabled in CLI.)
+
+## Commands
+
+```bash
+# List common metrics
+ae-cli engage-setting common-metric list --project-id <project_id>
+
+# Get a common metric detail
+ae-cli engage-setting common-metric get --project-id <project_id> --metric-name <name>
+
+# Update a common metric
+ae-cli engage-setting common-metric update \
+  --project-id <project_id> --metric-type <type> --metric-name <name> --metric-qp <qp> \
+  --metric-window-num <num> --metric-window-time-unit DAY --display-name <display>
+
+# Delete a common metric (high-risk)
+ae-cli engage-setting common-metric delete --project-id <project_id> --metric-name <name> --yes
+```
+
+## Parameters
+
+### list
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+
+### get / delete
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--metric-name` | Yes | Metric name. |
+
+### update
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--metric-type` | Yes | Metric type (see MetricTypeEunm). |
+| `--metric-name` | Yes | Metric name. |
+| `--metric-qp` | Yes | Metric qp (event/property expression). |
+| `--metric-window-num` | Yes | Metric window number. |
+| `--metric-window-time-unit` | Yes | Metric window time unit (MINUTE/HOUR/DAY). |
+| `--display-name` | Yes | Display name of the metric. |
+| `--note` | No | Metric note/remark. |
+| `--order-id` | No | Sort order id. |
+| `--metric-setting-id` | No | Metric setting id (when binding to a setting). |
+| `--metric-params` | No | Metric params JSON string. |
+
+## Output
+
+- `list`: `data.items` (each with `project_id`, `metric_type`, `metric_name`, `metric_qp`, `metric_window_num`, `metric_window_time_unit`, `note`, `last_editer`, `last_update_time`, `order_id`, `display_name`, `metric_setting_id`, `metric_params`) and `data.total`.
+- `get`: `data.metric` — a single metric object with the same fields, or `null`.
+- `update` / `delete`: `data.success`.
+
+## Preflight for config-metric batch-add
+
+`engage-scene config-metric batch-add --ta-metric-ids` requires TA common metrics to exist in the project. List them first:
+
+```bash
+ae-cli engage-setting common-metric list --project-id <project_id>
+```
+
+If `items` is empty, common metrics must be created in the Engage console before binding them to a config item, or treat the case as environment-blocked.
+
+## Decision Rules
+
+- Use these commands when the user asks to manage common metrics (常用指标) for the analysis workbench.
+- Discover existing metric names with `common-metric list` first; never invent names for `get`/`update`/`delete`.
+- `--metric-qp` must be a complete metric QP expression; do not pass `{}` as a placeholder.
+- `delete` is `high-risk-write` and requires `--yes` (or interactive confirmation).