@thinkingai/ae-cli 1.0.22 → 1.0.27

package/skills/ae-analysis/references/create_entity.md

@@ -0,0 +1,39 @@
+# analysis_meta +create_entity (Create Entity)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Entity Management**
+
+## Use Cases
+- Create a new entity that links an event property or user property as an analysis dimension.
+- Use `+list_entities` first to confirm the entity does not already exist.
+
+## Commands
+```bash
+ae-cli analysis_meta +create_entity --project_id <project_id> --entity_name "User Entity" --column_name user_id --table_type 1
+ae-cli analysis_meta +create_entity --project_id <project_id> --entity_name "Event Entity" --column_name event_col --table_type 0
+ae-cli analysis_meta +create_entity --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--entity_name` | Yes | Entity name |
+| `--column_name` | Yes | Property column name to associate with the entity |
+| `--table_type` | Yes | Table type: `0` = event property, `1` = user property |
+
+## Decision Rules
+- `--table_type` must be `0` (event property) or `1` (user property); no other values are accepted.
+- Before using `--column_name`, call `analysis_meta +list_properties` to verify it exists. If the same column name appears in **both** event properties and user properties, **stop and ask the user which table type to use** — do not guess `--table_type`. Ask every time this condition is met; never carry over the answer from a previous request.
+- For the first run, pass only the required parameters and confirm before adding others.
+- Write operations keep the confirmation prompt by default; use `--yes` only for automation.
+
+## Next Steps After Failure
+- If `PROJECT_ID_REQUIRED` or `ENTITY_NAME_REQUIRED` appears, check that all required parameters are provided.
+- If `INVALID_TABLE_TYPE` appears, verify `--table_type` is exactly `0` or `1`.
+- If the result after writing is not as expected, use `analysis_meta +list_entities` to compare before and after.
+
+## Recommended Chaining
+- `analysis_meta +list_entities` → `+create_entity`
+- `analysis_meta +list_properties` → `+create_entity`

package/skills/ae-analysis/references/create_space.md

@@ -0,0 +1,34 @@
+# analysis +create_space (Create Space)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Space Management**
+
+## Use Cases
+- Create a new space in a project to organize dashboards and assets under a named container.
+- Returns basic space information (ID, name, avatar settings).
+
+## Commands
+```bash
+ae-cli analysis +create_space --project_id <project_id> --space_name "My Space"
+ae-cli analysis +create_space --project_id <project_id> --space_name "Team Space" --space_desc "Team dashboards"
+ae-cli analysis +create_space --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--space_name` | Yes | Space name (1-64 characters) |
+| `--space_desc` | No | Optional space description (max 200 characters) |
+
+## Decision Rules
+- `--space_name` must be between 1 and 64 characters.
+- Write operations keep the confirmation prompt by default; use `--yes` only for automation.
+
+## Next Steps After Failure
+- If `SPACE_NAME_TOO_LONG` appears, shorten `--space_name` to 64 characters or fewer.
+- If the result after writing is not as expected, use `analysis +list_dashboards` to inspect the space context.
+
+## Recommended Chaining
+- `+create_space` → `+create_dashboard` (create dashboard inside the new space using `--space_id`)

package/skills/ae-analysis/references/drilldown_user_events.md

@@ -55,7 +55,7 @@ ae-cli analysis +drilldown_user_events --dry-run
 | `--entity_value` | No | Optional entity value for multi-entity scenarios |
 | `--use_cache` | No | Whether to use cache. Default: true |
 | `--page_num` | No | Start page number, default 1 |
-| `--page_size` | No | Page size, default 20, max 50 |
+| `--page_size` | No | Page size. Default: 1000, maximum: 100000 |
 | `--timeout_minutes` | No | Query timeout in minutes |
 
 ## Decision Rules

package/skills/ae-analysis/references/drilldown_users.md

@@ -55,14 +55,14 @@ ae-cli analysis +drilldown_users --dry-run
 | `--include_total` | No | Whether to query users from the total row. Default: false |
 | `--relation_val` | No | Relation value used in relation analysis scenarios |
 | `--use_cache` | No | Whether to use cache. Default: true |
-| `--limit` | No | Optional limit. Default: 20, maximum: 50. |
+| `--limit` | No | Optional limit. Default: 1000, maximum: 100000. |
 | `--offset` | No | Optional offset. Default: 0. |
 | `--timeout_minutes` | No | Query timeout in minutes. If the query exceeds this time, it will be cancelled automatically. |
 
 ## Decision Rules
 - Drilldown positioning parameters must come from upstream analysis results and must not be fabricated.
 - `qp` must not be rewritten or "simplified"; it should remain consistent with the source analysis.
-- For pagination, use `--limit` and `--offset` together. Default limit is 20.
+- For pagination, use `--limit` and `--offset` together. Default limit is 1000, maximum 100000.
 - For the first run, it is recommended to pass only the required parameters (`--project_id`, `--model_type`, `--qp`) and add optional parameters after confirming the chain works.
 - Wrap JSON parameters in single quotes (for example `--qp '{}'`, `--drilldown_groups '{}'`) to avoid shell escaping issues.
 - When dates/time ranges are involved, validate with a short range first and then expand gradually.

package/skills/ae-analysis/references/query_adhoc.md

@@ -95,7 +95,7 @@ ae-cli analysis +query_adhoc --project_id <project_id> --model_type <model_type>
 | `--is_sort_by_columns` | No | Whether to sort query results by columns. Default: false |
 | `--resolve_recent_day` | No | Whether to resolve relative time expressions such as "last 7 days". If omitted, service auto-resolves when `qp.eventView.recentDay` exists and `startTime`/`endTime` is incomplete; otherwise defaults to false. |
 | `--fields` | No | Optional fields to return. Must match column names in result. Invalid fields cause INVALID_FIELDS error. |
-| `--limit` | No | Optional limit. Default: 20, maximum: 50. |
+| `--limit` | No | Optional limit. Default: 1000, maximum: 100000. |
 | `--offset` | No | Optional offset. Default: 0. |
 | `--timeout_minutes` | No | Query timeout in minutes. If the query exceeds this time, it will be cancelled automatically. |
 
@@ -103,7 +103,8 @@ ae-cli analysis +query_adhoc --project_id <project_id> --model_type <model_type>
 - On the first run, start with only the required parameters (`--project_id`,`--model_type`,`--qp`), and add optional parameters after confirming the path works.
 - Do not call this command with placeholder QP such as `{}`. For builder-supported models, wait for builder `status=generated`; for non-builder models, build QP from verified schema/metadata first.
 - For builder-supported models, do not run metadata/schema lookup to "help" the builder. The builder is the metadata resolver.
-- For pagination, use `--limit` and `--offset` together. Default limit is 20.
+- For pagination, use `--limit` and `--offset` together. Default limit is 1000, maximum 100000.
+- For `model_type=sql`, use exactly one row limit: either put `LIMIT` in the SQL, or use `--limit`. If both are present they must be equal — `query_adhoc` rejects mismatched values to avoid silently sampled or duplicated results. When the SQL already has a trailing `LIMIT`, you may omit `--limit` and the SQL governs.
 - Use `--fields` to select specific columns for lighter response payloads.
 - `event`, `retention`, `funnel`, and `prop_analysis` must not manually craft QP with schema-first flow; call the builder and use the returned `qp`.
 - For non-builder models, `qp` must satisfy both schema structure and project metadata constraints.

package/skills/ae-analysis/references/query_entity_details.md

@@ -39,7 +39,7 @@ ae-cli analysis +query_entity_details --dry-run
 | `--properties` | No | Optional display properties JSON, for example `[{"columnName":"#user_id","tableType":"0"},{"columnName":"device_id","tableType":"0"}]`. If provided, property names should come from `analysis_meta +list_properties` in the same `project_id`. |
 | `--sort_by` | No | Optional sort field                                                                                                                                                                                                                     |
 | `--sort_order` | No | Optional sort order. Supported values: asc and desc                                                                                                                                                                                     |
-| `--limit` | No | Optional result limit. Default: 20, maximum: 50                                                                                                                                                                                         |
+| `--limit` | No | Optional result limit. Default: 1000, maximum: 100000                                                                                                                                                                                         |
 | `--zone_offset` | No | Time zone offset. For example, UTC+8 is 8                                                                                                                                                                                               |
 | `--use_cache` | No | Whether to use cache. Default: true                                                                                                                                                                                                     |
 

package/skills/ae-engage/SKILL.md

@@ -79,6 +79,12 @@ ae-cli engage +config_channel_list --project_id 1
 # Query the task list
 ae-cli engage +task_list --project_id 1 --req '{"pageNum":1,"pageSize":20}'
 
+# Build a save_task guide before composing the final req
+ae-cli engage +build_task_save_guide --project_id 1 --req '{"context":{"triggerType":2,"channelId":"channel_123"}}'
+
+# Save a task draft (create when req.taskId is omitted)
+ae-cli engage +save_task --project_id 1 --req '{"baseInfo":{"taskName":"Demo Task"},"channelConfig":{"channelType":1,"channelId":"channel_123","groupContentList":[{"contentList":[{"pushLanguageCode":"default","content":"[]"}]}]},"targetConfig":{"targetClusterType":3},"triggerConfig":{"triggerType":2},"controlConfig":{"completionIndicatorDef":{"completionIndicators":[]}}}'
+
 # Query task details
 ae-cli engage +task_detail --project_id 1 --task_id task_123
 
@@ -182,6 +188,8 @@ For more detailed generation rules, consult these references first:
 ```bash
 ae-cli --dry-run engage +channel_list --project_id 1
 ae-cli --dry-run engage +task_list --project_id 1 --req '{"pageNum":1,"pageSize":20}'
+ae-cli --dry-run engage +build_task_save_guide --project_id 1 --req '{}'
+ae-cli --dry-run engage +save_task --project_id 1 --req '{"baseInfo":{"taskName":"Demo Task"},"channelConfig":{"channelType":1,"channelId":"channel_123","groupContentList":[{"contentList":[{"pushLanguageCode":"default","content":"[]"}]}]},"targetConfig":{"targetClusterType":3},"triggerConfig":{"triggerType":2},"controlConfig":{"completionIndicatorDef":{"completionIndicators":[]}}}'
 ae-cli --dry-run engage +flow_list --project_id 1
 ```
 
@@ -190,6 +198,8 @@ ae-cli --dry-run engage +flow_list --project_id 1
 More detailed single-command guidance is available in the business-oriented `references/` directory:
 
 - `references/channel-list.md`
+- `references/build-task-save-guide.md`
+- `references/save-task.md`
 - `references/task-list.md`
 - `references/config-item-list.md`
 - `references/flow-list.md`
@@ -204,7 +214,7 @@ This split documentation structure is easier to extend later, because commands w
 
 ### task
 
-`+task_data_overview`, `+task_data_detail`, `+task_metric_detail`, `+task_experiment_report`, `+task_detail`, `+task_list`, `+task_stats`, `+manage_task`
+`+task_data_overview`, `+task_data_detail`, `+task_metric_detail`, `+task_experiment_report`, `+task_detail`, `+task_list`, `+task_stats`, `+build_task_save_guide`, `+save_task`, `+manage_task`
 
 ### config
 
@@ -225,4 +235,17 @@ The following commands are write operations. Confirm that the user intent is exp
 - Channels and config channels: `+add_channel`, `+delete_channel`, `+update_channel_status`, `+delete_config_channel`, `+update_config_channel_status`
 - Strategies and config items: `+delete_config_item`, `+copy_config_template`, `+manage_strategy`
 - Flows: `+save_flow`, `+modify_flow_base_info`, `+manage_flow`, `+delete_flow`
-- Tasks: `+manage_task`
+- Tasks: `+save_task`, `+manage_task`
+
+For task draft creation or update, use this workflow:
+
+1. `ae-cli engage +channel_list --project_id <projectId>`
+2. `ae-cli engage +build_task_save_guide --project_id <projectId> --req '{...}'`
+3. If the guide says QP-derived fields are needed, call `ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition`
+4. `ae-cli engage +save_task --project_id <projectId> --req '{...}'`
+
+`+build_task_save_guide` is a read-only helper. It returns scenario-specific required fields, channel content schema, unsupported combinations, examples, and a handoff template for `save_task`.
+
+`+save_task` only saves a draft. It does not submit approval, does not start sending, and does not trigger task execution. If `req.taskId` is omitted it creates a new draft; if `req.taskId` is present it updates an existing draft. Update mode only supports draft tasks, and omitted fields can inherit from the existing draft before validation.
+
+The audience schema query `ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition` is not a fixed preflight step. Call it only when the guide indicates that you must construct `targetConfig.qp`, `triggerConfig.triggerRule`, `clientConfig.clientQp`, or `completionIndicatorDef.event`.

package/skills/ae-engage/references/build-task-save-guide.md

@@ -0,0 +1,283 @@
+# ae-engage `+build_task_save_guide`
+
+Build a scenario-specific guide for constructing `save_task.req`.
+
+Mapped command: `ae-cli engage +build_task_save_guide`
+
+This is a read-only helper. It does not save tasks, submit approvals, or trigger execution. Its job is to tell you how to build a valid `save_task` request for the current scenario.
+
+---
+
+## 1. Recommended Workflow
+
+Use this sequence when creating or updating a task draft:
+
+1. Query channels with `ae-cli engage +channel_list --project_id <projectId>`.
+2. Call `ae-cli engage +build_task_save_guide --project_id <projectId> --req '{...}'`.
+3. If the guide says QP-derived fields are required, call:
+
+```bash
+ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
+```
+
+4. Build the final grouped `save_task.req`.
+5. Submit with `ae-cli engage +save_task --project_id <projectId> --req '{...}'`.
+
+Important:
+
+- Do not treat the audience schema query as a fixed preflight step.
+- Call it only when the guide indicates that you need to construct:
+  - `targetConfig.qp`
+  - `triggerConfig.triggerRule`
+  - `clientConfig.clientQp`
+  - `completionIndicatorDef.event`
+
+---
+
+## 2. CLI Shape
+
+The CLI call shape is:
+
+```bash
+ae-cli engage +build_task_save_guide --project_id <projectId> --req '<req-json>'
+```
+
+This CLI requires `--req`, but `{}` is valid when you want a generic guide without scenario context.
+
+Common request patterns:
+
+```bash
+ae-cli engage +build_task_save_guide --project_id 1 --req '{}'
+ae-cli engage +build_task_save_guide --project_id 1 --req '{"context":{"triggerType":2,"channelId":"channel_123"}}'
+ae-cli engage +build_task_save_guide --project_id 1 --req '{"draft":{"baseInfo":{"taskName":"Demo Task"}}}'
+```
+
+Supported request fields:
+
+- `context`
+  - a lightweight scenario selector
+  - use it when you know key dimensions such as trigger type, audience type, channel, or experiment mode
+- `draft`
+  - a partial `save_task` request
+  - use it when you already have part of the final payload and want missing fields, examples, or corrections
+- `reqDraft`
+  - alias of `draft`
+- `detailLevel`
+  - `brief`: core requirements only
+  - `full`: includes enums, unsupported cases, examples, and self-check information
+
+---
+
+## 3. `context` and `draft`
+
+### 3.1 `context`
+
+Use `context` when you want scenario-specific guidance without writing a partial `save_task.req`.
+
+Typical fields:
+
+- `triggerType`
+- `targetClusterType`
+- `channelType`
+- `channelId`
+- `channelTemplateId`
+- `enableExp`
+- `expIndicatorBizType`
+
+Example:
+
+```json
+{
+  "context": {
+    "triggerType": 2,
+    "targetClusterType": 2,
+    "channelId": "channel_123"
+  }
+}
+```
+
+### 3.2 `draft`
+
+Use `draft` when you already have a partial `save_task.req` and want the guide to tell you:
+
+- what is still missing
+- what is invalid
+- whether the payload is already close to submit-ready
+- what template or schema to use to finish it
+
+Example:
+
+```json
+{
+  "draft": {
+    "baseInfo": {
+      "taskName": "Demo Task"
+    },
+    "triggerConfig": {
+      "triggerType": 2
+    }
+  }
+}
+```
+
+---
+
+## 4. Output Structure
+
+The guide returns structured metadata rather than free-form prose. The top-level sections are:
+
+- `valid`
+- `errors`
+- `warnings`
+- `missingInputs`
+- `saveTaskContract`
+- `scenario`
+- `requiredInput`
+- `fieldRules`
+- `handoff`
+
+### 4.1 `valid`
+
+- `true` means the current scenario or draft has no structural blocking errors
+- `false` means you should inspect `errors`, `missingInputs`, and `handoff.blockingPlaceholders`
+
+### 4.2 `errors`
+
+Use `errors` for hard blockers such as:
+
+- invalid enum values
+- unsupported combinations
+- unsupported trigger types
+
+The guide may expose invalid values separately so you can correct them instead of silently dropping them.
+
+### 4.3 `warnings`
+
+Use `warnings` for non-fatal guidance, for example:
+
+- channel content schema is unavailable because no `channelId` was provided
+- click-rate experiment setup still needs a channel context
+
+### 4.4 `missingInputs`
+
+Use `missingInputs` as the to-do list for fields you still need before you can submit `save_task`.
+
+Typical examples:
+
+- missing `baseInfo.taskName`
+- missing `channelConfig.channelId`
+- missing `channelConfig.groupContentList`
+- missing `triggerConfig.triggerTime` for scheduled single tasks
+
+### 4.5 `saveTaskContract`
+
+This section describes the high-level contract:
+
+- final tool is `save_task`
+- required preflight is `query_channel_list -> build_task_save_guide`
+- QP-derived fields may require `ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition`
+- `save_task.req` must be a grouped JSON object
+
+### 4.6 `scenario`
+
+This section shows the resolved scenario, such as:
+
+- create vs update draft
+- trigger type
+- audience type
+- channel type / channel id
+- whether the scenario is unsupported
+
+### 4.7 `requiredInput`
+
+This section tells you which grouped blocks and fields are required in the current scenario.
+
+Use it to understand what must appear in:
+
+- `baseInfo`
+- `channelConfig`
+- `targetConfig`
+- `triggerConfig`
+- `controlConfig`
+- `expConfig` when experiment mode is enabled
+
+### 4.8 `fieldRules`
+
+This is the most important construction section.
+
+It includes:
+
+- grouped block rules
+- structured conditional rules
+- related-parameter rules
+- unsupported fields / values / combinations
+- `channelContentSchema`
+- enum values and wrong examples when `detailLevel=full`
+
+#### `fieldRules.channelContentSchema`
+
+Treat this as the source of truth for channel content construction.
+
+Use it to get:
+
+- valid keys
+- expected item shape
+- channel-specific examples
+- params that must be copied exactly, such as `paramType`
+
+Do not invent free-form content items such as:
+
+```json
+[{"text":"hello"}]
+```
+
+Instead, use the valid item structure and put message text into `value`.
+
+### 4.9 `handoff`
+
+This is the final section before `save_task`.
+
+Important fields:
+
+- `reqTemplate`
+  - a scenario-aware grouped request template
+  - use it as a starting point, not as unquestioned final truth
+- `readyToSubmit`
+  - `true` means the current scenario or draft has no blocking placeholders
+- `blockingPlaceholders`
+  - unresolved placeholders that still block submission
+- `selfCheckList`
+  - a final checklist before calling `save_task`
+- `successUrlRule`
+  - after `save_task` succeeds, build the task detail URL from current page origin plus the relative hash
+  - do not hardcode host, IP, or port
+
+---
+
+## 5. How to Use the Guide in Practice
+
+Recommended usage pattern:
+
+1. resolve a real `channelId` with `+channel_list`
+2. call `+build_task_save_guide`
+3. read `fieldRules.channelContentSchema`
+4. read `handoff.reqTemplate`
+5. fix everything in `blockingPlaceholders`
+6. if the guide points to QP-derived fields, call:
+
+```bash
+ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
+```
+
+7. fill those fields using the real condition schema
+8. call `+save_task`
+
+---
+
+## 6. Safety Notes
+
+- `+build_task_save_guide` is read-only; it does not save a draft
+- do not skip the guide and build `save_task.req` from memory alone
+- do not treat the audience schema query as mandatory for every task
+- do not invent `channelId`, `clusterKey`, content keys, or QP structures
+- if the guide exposes an unsupported scenario, correct it before calling `save_task`