@thinkingai/ae-cli 6.1.20 → 6.1.21

package/skills/ae-engage/references/task-metric-update.md

@@ -0,0 +1,151 @@
+# Task metric update
+
+Use this reference to configure, add, or replace effect metric settings for an operation task.
+
+Mapped CLI command: `ae-cli engage-task metric update`
+
+Mapped capability: `engage-task.metric.update`
+
+## Required input
+
+- `--project-id`
+- `--task-id`
+- `--metric-map '<metric_map_json>'`
+
+## Workflow and parameter guidance
+
+1. Create/save the task first and obtain its `task_id`. The task-save request does not configure global effect metrics through `metricMap`.
+2. Read task details with `ae-cli engage-task task get --project-id <project_id> --task-id <task_id>` and use the grouped `metric_map` as the update baseline. `metric list` returns a flat list without group membership, so it cannot reconstruct this map. If the grouped configuration is unavailable, do not guess groups or treat the flat list as an empty configuration.
+3. Build the complete desired `metric_map`. This is a clean-and-insert update: omitted settings may be deleted, so preserve each binding's original group, all other desired metrics, and existing `metricSettingId` values. Select the binding to change by its setting ID, not by its display name.
+4. Use `--dry-run` on the assembled request before applying the explicitly requested configuration change. After applying, read task details again and compare the groups, binding IDs, and window fields with the intended configuration.
+
+`metric_map` is an object with target-user group keys `trigger`, `view`, and `click`, each containing an array of Hermes metric DTOs. Use native camelCase DTO fields: `metricSettingId`, `metricType`, `metricName`, `metricQp`, `metricWindowNum`, `metricWindowTimeUnit`, `timeCycleDef`, `displayName`, `orderId`, `note`, and `metricParams`. Nested snake_case fields are also accepted at the CLI boundary.
+
+For a custom metric use `metricType: 2`, a complete verified `metricQp` JSON string, the window fields, `displayName`, and `orderId`; Hermes creates the custom metric name. For preset metrics use `metricType: 1` and a real `metricName` from `engage-setting common-metric list/get`. Do not invent event names, metric names, QP structures, or binding IDs. Both custom and preset bindings require `displayName` and `orderId`. Do not use `metricId` in place of `metricSettingId`.
+
+```bash
+ae-cli --dry-run engage-task metric update \
+  --project-id <project_id> \
+  --task-id <task_id> \
+  --metric-map '<complete_metric_map_json>'
+```
+
+Replace the placeholders with discovered IDs and the complete desired JSON map. Apply the same command without `--dry-run` only for an authorized configuration change.
+
+## Custom metric window semantics
+
+Choose the window from the user's intent, not from the number alone:
+
+| User intent | `metricWindowNum` | `metricWindowTimeUnit` | `timeCycleDef` |
+| --- | --- | --- | --- |
+| One day / 24 hours / rolling one day | `1` | `"day"` | Omit |
+| Until the end of the attribution event's calendar day | `1` | `"day"` | `{"startTime":"00:00"}` |
+| Until the end of the attribution event's calendar week | `1` | `"week"` | `{"startDay":1,"startTime":"00:00"}` |
+| Until the end of the attribution event's calendar month | `1` | `"month"` | `{"startDay":1}` |
+
+`timeCycleDef` selects a natural calendar attribution window. The attribution event (such as a trigger, delivery, or click, according to the metric group) anchors the window; conversions must occur after that event and before the next configured cycle boundary. The boundary is exclusive. `1` + `day` alone remains a rolling one-day window. Resolve calendar boundaries in the task's configured timezone (`tzOffset`), falling back to the backend default when absent. The report display timezone does not redefine the cycle.
+
+For example, with Monday at midnight as the week boundary, a Wednesday 15:00 attribution event counts subsequent conversions before the following Monday 00:00. It does not count Monday or Tuesday conversions before that event. With midnight as the day boundary, a 23:00 attribution event has only the remainder of that day, rather than 24 hours.
+
+Interpret "today", "this week", or "this month" as these windows only when the user means the attribution event's day, week, or month. A request to view results for the current reporting period belongs to report date filters and does not by itself authorize changing metric configuration.
+
+Treat an unqualified "one day" as the existing rolling window. Use midnight, Monday, and the first day of the month for the calendar defaults above. Honor an explicitly requested valid cycle start. "Daily", "weekly", and "monthly" can describe task execution frequency: resolve the context and ask for clarification only when the metric window intent remains ambiguous.
+
+Natural window constraints:
+
+- `metricWindowNum` must be `1`; the unit must be `day`, `week`, or `month`.
+- Day: require `startTime` in 24-hour `HH:mm`; omit `startDay`.
+- Week: require `startDay` from `1` (Monday) to `7` (Sunday) and `startTime` in `HH:mm`.
+- Month: require `startDay` from `1` to `28`; omit `startTime` or use `"00:00"`.
+- An empty `timeCycleDef: {}` is invalid. Without `timeCycleDef`, only rolling `minute`, `hour`, and `day` units are accepted.
+- When switching rolling to calendar, add the matching `timeCycleDef` and set the number/unit together. When switching back, remove `timeCycleDef` entirely and use a valid rolling unit. Preserve the binding's `metricSettingId` and all other desired metrics.
+- These options apply to custom metrics (`metricType: 2`) through `metric update`. Do not use `engage-setting common-metric create/update` to create natural windows.
+- Task support requires a backend deployment containing the task natural-window feature. Do not silently replace an unsupported calendar window with a rolling duration.
+
+### Custom metric payload examples
+
+Each JSON block is a complete illustrative `--metric-map` value for a configuration containing only that metric. The `purchase` event and QP below are examples, not discovered project metadata: substitute a verified project metric QP (as a JSON string) before use. For an existing configuration, merge the chosen metric into the complete current map and preserve existing binding IDs; do not submit these single-metric examples over other configured metrics.
+
+Rolling one day:
+
+```json
+{
+  "trigger": [
+    {
+      "metricType": 2,
+      "metricQp": "{\"type\":0,\"eventName\":\"purchase\",\"analysis\":\"A100\",\"filts\":[]}",
+      "metricWindowNum": 1,
+      "metricWindowTimeUnit": "day",
+      "displayName": "Purchase - Rolling one day",
+      "orderId": 1
+    }
+  ]
+}
+```
+
+Current calendar day:
+
+```json
+{
+  "trigger": [
+    {
+      "metricType": 2,
+      "metricQp": "{\"type\":0,\"eventName\":\"purchase\",\"analysis\":\"A100\",\"filts\":[]}",
+      "metricWindowNum": 1,
+      "metricWindowTimeUnit": "day",
+      "displayName": "Purchase - Current calendar day",
+      "orderId": 1,
+      "timeCycleDef": {
+        "startTime": "00:00"
+      }
+    }
+  ]
+}
+```
+
+Current calendar week:
+
+```json
+{
+  "trigger": [
+    {
+      "metricType": 2,
+      "metricQp": "{\"type\":0,\"eventName\":\"purchase\",\"analysis\":\"A100\",\"filts\":[]}",
+      "metricWindowNum": 1,
+      "metricWindowTimeUnit": "week",
+      "displayName": "Purchase - Current calendar week",
+      "orderId": 1,
+      "timeCycleDef": {
+        "startDay": 1,
+        "startTime": "00:00"
+      }
+    }
+  ]
+}
+```
+
+Current calendar month:
+
+```json
+{
+  "trigger": [
+    {
+      "metricType": 2,
+      "metricQp": "{\"type\":0,\"eventName\":\"purchase\",\"analysis\":\"A100\",\"filts\":[]}",
+      "metricWindowNum": 1,
+      "metricWindowTimeUnit": "month",
+      "displayName": "Purchase - Current calendar month",
+      "orderId": 1,
+      "timeCycleDef": {
+        "startDay": 1
+      }
+    }
+  ]
+}
+```
+
+## Related interfaces
+
+- [Task save](save-task.md): create or update the task draft before configuring effect metrics.
+- [Flow metric update](flow-metric-update.md): the equivalent flow canvas configuration.
+- [Task metric detail](task-metric-detail.md): query metric reports; this is separate from configuration.

package/skills/ae-experiment/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ae-experiment
-version: 1.0.1
-description: "Use when managing Atlas AB experiments, traffic layers, Features, metrics, buckets, and experiment reports through ae-cli"
+version: 1.0.2
+description: "Use when managing Atlas AB or external experiments, traffic layers, Features, metrics, buckets, and experiment reports through ae-cli"
 ---
 
 # ae-experiment
@@ -61,10 +61,11 @@ Naming and response boundary:
    - `experiment metric save`
 3. Create or patch the experiment draft with `experiment experiment save`.
    Use `experiment experiment update-metrics` when replacing metric bindings or assigning guardrail roles.
-4. Check readiness with `experiment experiment ready-check`.
-5. For a non-mutex traffic layer, run `experiment experiment conflict-check` before submit (needs `feature_key_list` from context or `experiment get`).
-6. Move status with `experiment experiment manage`.
-7. Query reports with `experiment report summary`, `experiment report sample-size`, and `experiment report metric-trend`.
+4. For an external experiment, use `experiment external-experiment save-submit` instead. It submits directly and does not use Features, traffic layers, allocation, targeting, or experiment cycles.
+5. Check readiness with `experiment experiment ready-check`.
+6. For a non-mutex traffic layer, run `experiment experiment conflict-check` before submit (needs `feature_key_list` from context or `experiment get`).
+7. Move status with `experiment experiment manage`.
+8. Query reports with `experiment report summary`, `experiment report sample-size`, and `experiment report metric-trend`.
 
 If an experiment save returns `error_code: METRIC_NOT_FOUND`, list metrics for the same project. Create and verify the metric before retrying; never retry with another invented ID. Metric deletion returns `error_code: METRIC_IN_USE` while an active experiment binding exists.
 
@@ -98,10 +99,16 @@ Read [`save_build_guide.md`](references/save_build_guide.md) and
 
 ### Experiment
 
-`experiment experiment save`, `experiment experiment update-metrics`, `capability run experiment.experiment.save-submit`, `experiment experiment list`, `experiment experiment list-archived`, `experiment experiment get`, `experiment experiment ready-check`, `experiment experiment conflict-check`, `experiment experiment manage`, `experiment experiment update-group`, `experiment experiment batch-delete`, `experiment operation-log query`
+`experiment experiment save`, `experiment experiment update-metrics`, `experiment external-experiment save-submit`, `capability run experiment.experiment.save-submit`, `experiment experiment list`, `experiment experiment list-archived`, `experiment experiment get`, `experiment experiment ready-check`, `experiment experiment conflict-check`, `experiment experiment manage`, `experiment experiment update-group`, `experiment experiment batch-delete`, `experiment operation-log query`
 
 Read [`manage_guardrail_metrics.md`](references/manage_guardrail_metrics.md) before assigning or replacing metric roles.
 
+### External Experiment
+
+`experiment external-experiment save-submit`
+
+Read [`save_submit_external_experiment.md`](references/save_submit_external_experiment.md) before creating or updating an external experiment.
+
 ### Traffic Layer and Buckets
 
 `experiment traffic-layer save`, `experiment traffic-layer get`, `experiment traffic-layer list`, `experiment traffic-layer batch-delete`, `experiment bucket list`

package/skills/ae-experiment/references/save_submit_external_experiment.md

@@ -0,0 +1,52 @@
+# experiment external-experiment save-submit
+
+Create or update and submit an external experiment. This is the typed L2 wrapper for
+`experiment.experiment.save-submit`; it always sends `expType: "external"`.
+
+```bash
+ae-cli experiment external-experiment save-submit \
+  --project-id 1 \
+  --exp-name "Partner onboarding test" \
+  --bucket-id "#user_id" \
+  --start-time "2026-09-01T00:00:00+08:00" \
+  --end-time "2026-09-15T00:00:00+08:00" \
+  --supposition "The new onboarding improves activation." \
+  --groups '[{"expGroupName":"control","isControl":1},{"expGroupName":"variant","isControl":0}]' \
+  --metrics '[{"metricId":"activation_rate","metricRole":"primary"}]' \
+  --dry-run
+```
+
+`--dry-run` validates the external submit shape without persisting: required
+time bounds, Feature-only fields that are forbidden here, group shape, and
+primary metric presence. The final submit also checks that metric IDs exist and
+that each metric event supports the selected bucket property.
+
+External experiments are evaluated from exposure events reported by the caller. They
+do not configure Features, traffic layers, allocation, targeting, or `expCycle`.
+Choose an existing `bucket_id` whose property is available in the events used by every
+bound metric. The server requires at least two named groups, exactly one control group,
+and at least one existing primary metric.
+
+Status is calculated from the submitted time range: a future start time becomes
+`pending`, a current range becomes `running`, and an elapsed end time becomes `ended`.
+No `end_time` creates a long-running experiment. When the scheduled job is active, a
+pending experiment enters `running` at its start time and a running experiment enters
+`ended` at its end time. `experiment experiment manage` permits only
+`pending → running`, `running → ended`, and `ended → archive`; manually entering
+`running` or `ended` replaces the corresponding time boundary with the current time.
+
+For an update, first call `experiment experiment get`. An already submitted external
+experiment can be updated only while `pending` or `running`; its hypothesis and time
+range may change, and group descriptions may change. Keep its name, business group,
+description, bucket, metric bindings, group count, group names, control markers,
+allocations, and group values unchanged. Include every returned group unchanged,
+including its `expGroupId`, `allocation`, and `expGroupValue`; the CLI rejects an
+update that omits a group ID. Omitting `--end-time` represents a long-running
+experiment, so preserve the current end time whenever it should remain scheduled.
+
+Transition status: L2
+Owning module: Hermes Atlas experiment capability gateway
+Current transport: Capability Gateway `experiment.experiment.save-submit`
+Gateway target: `experiment.experiment.save-submit`
+Review after: 2027-02-28
+Exit condition: Remove this wrapper if the Gateway exposes a dedicated external-experiment capability or the typed fields no longer match the Atlas external-experiment contract.

package/skills/ae-experiment-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ae-experiment-design
-description: "Design AE/TE A/B experiments from a business goal through a reviewable draft. Use when the user asks to form an experiment hypothesis, assess metric readiness, choose or create metrics and Features, design groups or traffic, estimate sample size or duration, create an experiment draft, or run readiness and conflict checks. SDK guidance is a conditional branch: enter it only when the user explicitly asks about an A/B experiment SDK, client SDK integration, experiment SDK code generation, or SDK troubleshooting; do not include SDK work in an ordinary experiment-design or draft-creation request."
+description: "Design AE A/B experiments from a business goal through a reviewable draft. Use when the user asks to form an experiment hypothesis, assess metric readiness, choose or create metrics and Features, design groups or traffic, estimate sample size or duration, create an experiment draft, or run readiness and conflict checks. SDK guidance is a conditional branch: enter it only when the user explicitly asks about an A/B experiment SDK, client SDK integration, experiment SDK code generation, or SDK troubleshooting; do not include SDK work in an ordinary experiment-design or draft-creation request."
 ---
 
 # AE Experiment Design and Integration
@@ -9,7 +9,7 @@ Turn a business objective into an evidence-backed experiment design, an implemen
 
 ## Hard boundaries
 
-- Use `ae-cli` for every AE/TE platform interaction. Do not substitute raw HTTP, browser automation, direct database queries, or application SDKs.
+- Use `ae-cli` for every AE platform interaction. Do not substitute raw HTTP, browser automation, direct database queries, or application SDKs.
 - Do not infer an SDK request from the fact that an experiment needs implementation. Load SDK references only when the user explicitly asks about an A/B experiment SDK or client SDK integration.
 - Do not copy general tracking SDK documentation into this Skill. Route generic initialization, event reporting, `track`, user identity, user properties, data upload, LogBus, and REST questions to `ae-data-integration-helper` when that Skill is available.
 - Use only the event-metric calculation contracts defined in
@@ -24,7 +24,7 @@ Read only the references needed for the current request:
 
 | Request | Required references |
 |---|---|
-| Any AE/TE platform read or write | [`references/platform-operations.md`](references/platform-operations.md) |
+| Any AE platform read or write | [`references/platform-operations.md`](references/platform-operations.md) |
 | Create or reuse an experiment draft | [`references/experiment-creation.md`](references/experiment-creation.md) and [`references/platform-operations.md`](references/platform-operations.md) |
 | Metric selection, feasibility, or creation | [`references/metric-readiness.md`](references/metric-readiness.md) |
 | Explicit A/B experiment SDK or client SDK integration request | [`references/sdk-integration.md`](references/sdk-integration.md) |

package/skills/ae-experiment-design/references/platform-operations.md

@@ -1,6 +1,6 @@
 # Platform Operations
 
-Read this reference before any AE/TE platform interaction.
+Read this reference before any AE platform interaction.
 
 ## Hard boundary
 

package/skills/ae-experiment-insight/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ae-experiment-insight
-description: "Diagnose and interpret AE/TE A/B experiments from configuration and report evidence through a defensible decision. Use when the user asks what an experiment means, whether it can roll out, why a result is not significant, why group sizes or exposure are wrong, why treatment results conflict, whether the report is trustworthy, or what to do next. Covers SRM, duration sufficiency, novelty effects, metric conflicts, missing or anomalous data, design reasonableness, data reliability, metric interpretation, trend and segment analysis, root-cause hypotheses, and rollout recommendations. All platform discovery and reads must use ae-cli."
+description: "Diagnose and interpret AE A/B experiments from configuration and report evidence through a defensible decision. Use when the user asks what an experiment means, whether it can roll out, why a result is not significant, why group sizes or exposure are wrong, why treatment results conflict, whether the report is trustworthy, or what to do next. Covers SRM, duration sufficiency, novelty effects, metric conflicts, missing or anomalous data, design reasonableness, data reliability, metric interpretation, trend and segment analysis, root-cause hypotheses, and rollout recommendations. All platform discovery and reads must use ae-cli."
 ---
 
 # AE Experiment Insight and Diagnosis
@@ -9,7 +9,7 @@ Validate the evidence before interpreting the effect. Produce a decision only wh
 
 ## Platform and reference routing
 
-Use `ae-cli` for every AE/TE platform interaction and follow
+Use `ae-cli` for every AE platform interaction and follow
 [`references/platform-operations.md`](references/platform-operations.md);
 never substitute another platform access path.
 

package/skills/ae-experiment-insight/references/platform-operations.md

@@ -1,6 +1,6 @@
 # Platform Operations
 
-Read this reference before retrieving any AE/TE experiment evidence.
+Read this reference before retrieving any AE experiment evidence.
 
 ## Hard boundary
 

package/skills/ae-generate-tracking-code/SKILL.md

@@ -299,6 +299,7 @@ From the plan file, read:
 - `meta.client_sdk_type` — client SDK type (if `client_only` or `both`)
 - `meta.server_language` — server language (if `server_only` or `both`)
 - `meta.user_identity` — user identity config (used to generate `login()` / `identify()` calls)
+- `user_properties` — user property pool (each entry's `name` + `update_type`, used to generate `user_set` / `user_setOnce` / `user_add` calls)
 
 **Determine list of platforms to generate code for**:
 ```
@@ -639,7 +640,7 @@ Validation steps:
 ### After validation passes
 
 - Remind user to commit changes (if any `insert` was used)
-- Remind user to call `login()` / `identify()` in code to associate user IDs
+- Remind user to call `login()` / `identify()` (associate user IDs) and `user_set` / `user_setOnce` / `user_add` (set user properties) at the right business moments
 - Remind user to copy daemon.json to LogBus2 conf/ directory
 
 ### Validation failure

package/skills/ae-generate-tracking-code/references/client-sdk-insert.md

@@ -111,7 +111,7 @@ Wait for user confirmation, then proceed to Stage 1.
 
 ## User Properties
 - File: <path>:<line>
-- user_set / user_setOnce / user_add
+- user_set / user_setOnce / user_add / user_append
 
 ## Event Group: <tag>
 - <event_name>: <file>:<line> [Business action: <business meaning>]

package/skills/ae-generate-tracking-code/references/datax-config.md

@@ -1,6 +1,6 @@
 # Mode D — DataX job.json
 
-> **Terminology**: 数据源类型 = data source type | 连接信息 = connection info | 库表名 = database/table name | 查询条件 = query condition | reader 插件 = reader plugin | columnMapping = column-to-property mapping | push_url = TE receiver URL
+> **Terminology**: 数据源类型 = data source type | 连接信息 = connection info | 库表名 = database/table name | 查询条件 = query condition | reader 插件 = reader plugin | columnMapping = column-to-property mapping | push_url = AE receiver URL
 
 ## Ask User
 1. Data source type (MySQL / Oracle / PostgreSQL / OSS / HDFS / Other)

package/skills/ae-generate-tracking-code/references/logbus-config.md

@@ -1,6 +1,6 @@
 # LogBus2 Configuration Generation
 
-> **Terminology**: LogBus2 = log sync tool (Go-based, v2) | LoggerConsumer = writes events to local log files | 日志同步工具 = log sync tool | daemon.json = LogBus2 config file | push_url = TE receiver/data ingestion URL | app_id = AE project APP_ID | file_patterns = glob patterns for log files | unit_remove = file deletion unit (day/hour) | offset_remove = file deletion offset | 重命名 = rename (causes re-upload) | runtime 目录 = runtime directory (stores progress snapshots) | JSON line = JSONL format (one JSON per line)
+> **Terminology**: LogBus2 = log sync tool (Go-based, v2) | LoggerConsumer = writes events to local log files | 日志同步工具 = log sync tool | daemon.json = LogBus2 config file | push_url = AE receiver/data ingestion URL | app_id = AE project APP_ID | file_patterns = glob patterns for log files | unit_remove = file deletion unit (day/hour) | offset_remove = file deletion offset | 重命名 = rename (causes re-upload) | runtime 目录 = runtime directory (stores progress snapshots) | JSON line = JSONL format (one JSON per line)
 
 LogBus2 is AE's official log sync tool, used together with LoggerConsumer (server-side SDK).
 

package/skills/ae-generate-tracking-code/references/modes.md

@@ -18,7 +18,7 @@ Server-side always gets the following regardless of `insert` or `snippet`:
 | Deliverable | Description |
 |---|---|
 | LoggerConsumer code | Server SDK writes to local log files |
-| `.ae-cli/output/daemon.json` | LogBus2 config (reads logs and uploads to TE) |
+| `.ae-cli/output/daemon.json` | LogBus2 config (reads logs and uploads to AE) |
 
 **Note: LogBus v1 is deprecated. Use LogBus2 for all scenarios.**
 

package/skills/ae-generate-tracking-code/references/server-sdk-insert.md

@@ -1,6 +1,6 @@
 # Server-side Code Insertion (LoggerConsumer + LogBus2)
 
-> **Terminology**: 服务端 SDK = server-side SDK | 代码插入 = code insertion/injection | LoggerConsumer = writes events to local log files (recommended for production) | LogBus2 = log sync tool that reads local logs and uploads to TE | 架构 = architecture | 异步上报 = async upload | 批量上传 = batch upload | 重试策略 = retry strategy | 公共属性 = super property (公共事件属性; never "超级属性") | 用户属性 = user property | 依赖管理 = dependency management
+> **Terminology**: 服务端 SDK = server-side SDK | 代码插入 = code insertion/injection | LoggerConsumer = writes events to local log files (recommended for production) | LogBus2 = log sync tool that reads local logs and uploads to AE | 架构 = architecture | 异步上报 = async upload | 批量上传 = batch upload | 重试策略 = retry strategy | 公共属性 = super property (公共事件属性; never "超级属性") | 用户属性 = user property | 依赖管理 = dependency management
 
 ## Architecture
 
@@ -91,7 +91,7 @@ Wait for user confirmation, then proceed to Stage 1.
 
 ## User Properties
 - File: <path>:<line>
-- user_set / user_setOnce / user_add
+- user_set / user_setOnce / user_add / user_append
 
 ## Event Group: <tag>
 - <event_name>: <file>:<symbol> or SKIP (already present)
@@ -120,9 +120,9 @@ Insertion point: entry file static block / start of main function
 
 ### Batch 2: Super Properties + User Properties
 
-Generate based on `meta.user_identity`:
-- `user_set` / `user_setOnce`: user property upload
-- `login()` call: on user login
+Generate:
+- `user_set` / `user_setOnce` / `user_add` / `user_append`: user property upload, based on `draft.user_properties[]` (each entry's `name` + `update_type`)
+- `login()` call: on user login, based on `meta.user_identity`
 
 ### Batch 3..N: Events grouped by event_tag
 

package/skills/ae-generate-tracking-code/references/snippet-delivery.md

@@ -69,7 +69,7 @@ You must call the corresponding API to **enable** them after or during initializ
 
 ```<lang>
 // Call after user login
-<user_set / user_setOnce code>
+<user_set / user_setOnce / user_add / user_append code>
 ```
 ```
 
@@ -161,7 +161,7 @@ Show each event individually, each as its own block for easy copying.
 <setSuperProperties code>
 
 // ==================== User Properties ====================
-<user_set code>
+<user_set / user_setOnce / user_add / user_append code>
 
 // ==================== Event Group: <tag> ====================
 // <event_name> - <event_desc>
@@ -280,7 +280,7 @@ If upload succeeds, report that the files are available from the file/attachment
    - **Integrate SDK** section (npm package name / CDN URL / integration methods)
    - **Initialization** section (init API signature and example code)
    - **Track** section (event upload API and examples)
-   - **User Properties** section (user_set / user_setOnce / user_add API)
+   - **User Properties** section (user_set / user_setOnce / user_add / user_append API)
 
 3. **⚠️ Do not skip Step 0** — even if you've generated code for the same platform before, must re-read latest docs every time
 

package/skills/ae-generate-tracking-plan/SKILL.md

@@ -640,7 +640,7 @@ Draft
 }
 ```
 
-> `update_type` is one of: `user_set` (overwrite), `user_setOnce` (first-set-only), `user_add` (numeric accumulate).
+> `update_type` is one of: `user_set` (overwrite), `user_setOnce` (first-set-only), `user_add` (numeric accumulate), `user_append` (array append).
 
 **User identity fields (`meta.user_identity`)**:
 
@@ -1359,7 +1359,7 @@ AE_LANG=<user_lang> ae-cli tracking plan upload --project <projectId> --xlsx .ae
 #### Auto-fix Flow
 
 CLI auto-executes:
-1. Upload xlsx to TE
+1. Upload xlsx to AE
 2. Check if `eventErrorMap` has errors
 3. Fixable errors → auto-fix draft.json → regenerate xlsx → re-upload
 4. Loop up to 3 times; prompt user for manual intervention if exceeded

package/skills/ae-generate-tracking-plan/references/te-api.md

@@ -124,6 +124,7 @@ Upload is a two-step capability-gateway flow:
 | `user_set` | 覆盖赋值 |
 | `user_setOnce` | 仅首次赋值 |
 | `user_add` | 数值累加 |
+| `user_append` | 列表追加 |
 
 ## v2（暂未实现）
 

package/skills/ae-generate-tracking-plan/references/xlsx-schema.md

@@ -119,10 +119,11 @@ A-E 在 writer 里用 `mergeCells` 合并。
 | `user_set` | 覆盖赋值（默认） |
 | `user_setOnce` | 仅首次赋值 |
 | `user_add` | 数值累加 |
+| `user_append` | 列表追加 |
 
 xlsx 里填写英文 canonical 值本身，不翻译。
 
-官方文档提及 `user_append`（字符串数组追加），样本中无实例，暂不实现。
+官方模板 `#用户数据` 隐藏说明行「更新方式：取值user_set、user_setOnce、user_add、user_append」已确认 `user_append` 在方案枚举内。`user_unset`（删除属性）不在方案枚举内——它是数据接入层 `#type` 的操作（见 data-rules.md），不是方案声明。
 
 ---
 
@@ -150,5 +151,5 @@ xlsx 里填写英文 canonical 值本身，不翻译。
 ## 开放问题（记一下，不影响 v1）
 
 1. ~~AE 后端是否区分 `object`（单对象）与 `array_row`（对象数组）~~ —— 已确认：AE 支持，wiki/te-docs/raw/preparations-before-data-ingestion.md 明确区分两种类型
-2. `user_append` updateType 是否真的可用 —— 待构造测试
+2. ~~`user_append` updateType 是否真的可用~~ —— 已确认：官方模板 `#用户数据` 隐藏说明行「更新方式：取值user_set、user_setOnce、user_add、user_append」，枚举含 `user_append`（`user_unset` 不在方案枚举内）
 3. 严格错误码 —— 所有校验失败目前都是 `return_code=0 success` + 静默丢弃，无法从响应区分成功/失败；UI 上传才显示错误文案

package/skills/ae-kb/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ae-kb
 version: 1.0.0
-description: 'AE/TE knowledge base CLI manual for creating, importing read-only compiled snapshots, querying, LLM-powered ask, listing accessible knowledge bases and their sources, deterministic index/grep/read retrieval, checking status, ZIP source upload and directory management, raw child-file reading, revision-checked child updates and deletion, compiling, schema generation, URL sources, source deletion, and knowledge base deletion. Use when the user asks to manage TE/AE/ThinkingEngine knowledge bases, import a compiled Markdown ZIP snapshot, upload documents or URLs to a knowledge base, query knowledge, ask knowledge bases with an LLM, list accessible knowledge bases or source metadata, inspect knowledge base indexes, search knowledge base pages, read a specific knowledge base page, check knowledge base status, generate schemas, compile knowledge, remove sources, or delete a knowledge base. To choose which knowledge base is worth searching, use the ae-kb-discovery skill first; this skill runs the retrieval once a target is chosen. Must use ae-cli kb commands and must not guess knowledge base names, scopes, page paths, source IDs, source display names, JSON payload shapes, or URL formats.'
+description: 'AE knowledge base CLI manual for creating, importing read-only compiled snapshots, querying, LLM-powered ask, listing accessible knowledge bases and their sources, deterministic index/grep/read retrieval, checking status, ZIP source upload and directory management, raw child-file reading, revision-checked child updates and deletion, compiling, schema generation, URL sources, source deletion, file/ZIP source draft replacement and restoration, and knowledge base deletion. Use when the user asks to manage AE (Agentic Engine) knowledge bases, import a compiled Markdown ZIP snapshot, upload documents or URLs to a knowledge base, query knowledge, ask knowledge bases with an LLM, list accessible knowledge bases or source metadata, inspect knowledge base indexes, search knowledge base pages, read a specific knowledge base page, check knowledge base status, generate schemas, compile knowledge, remove sources, or delete a knowledge base. To choose which knowledge base is worth searching, use the ae-kb-discovery skill first; this skill runs the retrieval once a target is chosen. Must use ae-cli kb commands and must not guess knowledge base names, scopes, page paths, source IDs, source display names, JSON payload shapes, or URL formats.'
 ---
 
 # ae-kb
@@ -10,12 +10,14 @@ AE CLI (`ae-cli`) knowledge base commands are invoked through:
 
 ```bash
 ae-cli kb +<command> [options]
+ae-cli kb source <replace|restore|preview|commit|cancel|check-updates> [options]
 ```
 
 ## Global Rules
 
-- Use this skill for TE/AE knowledge base tasks: create, import a compiled snapshot, query, ask with LLM, list accessible knowledge bases and their sources, inspect indexes, grep pages, read pages, check status, upload sources, add URL sources, generate schema, compile, remove source files, and delete knowledge bases.
+- Use this skill for AE knowledge base tasks: create, import a compiled snapshot, query, ask with LLM, list accessible knowledge bases and their sources, inspect indexes, grep pages, read pages, check status, upload sources, add URL sources, generate schema, compile, remove source files, and delete knowledge bases.
 - **Searching a knowledge base for an answer is the most common task. If that is what you are doing, go straight to [Explore Knowledge Base Pages](#explore-knowledge-base-pages) and read [`references/query-workflow.md`](references/query-workflow.md) first — it is the retrieval procedure. The other commands below are for managing knowledge bases, not answering from them.**
+- **When retrieved pages will guide project-scoped business data analysis, read and follow [`references/analysis-workflow.md`](references/analysis-workflow.md) before running any data query. This is mandatory after a KB hit identifies a saved asset, definition, parameter, time rule, conflict, or decision boundary; do not jump directly to ad-hoc analysis or SQL.**
 - Read operations can run directly after required inputs are known. Write operations require explicit user intent and normally keep the confirmation prompt unless the user asks to bypass it.
 - Prefer `--dry-run` before destructive or broad writes when the user has not already validated the target.
 - Do not invent knowledge base names, scopes, source IDs, source display names, or JSON payloads. Ask the user or query known context when values are missing.
@@ -30,6 +32,7 @@ ae-cli kb +<command> [options]
 
 | Command | Risk | Purpose |
 |---|---:|---|
+| `source check-updates` | write | Check one compiled Feishu source with the scheduled detector; mark changes without compiling. |
 | `+ask` | read | LLM-powered Q&A over knowledge bases; for multi-page synthesis or multi-hop questions. |
 | `+ask-status` | read | Query the current status of an ask execution by `--execution-id` without polling. |
 | `+list` | read | List accessible knowledge bases filtered by buildStatus (default: compiled). |
@@ -64,6 +67,20 @@ Use the nine version commands described in [`references/versions.md`](references
 | `+rollback` | high-risk-write | Restore an earlier version and create a new version. |
 | `+rollback-status` | read | Query a persisted rollback Operation without polling. |
 
+## Source Draft Replacement and Restoration
+
+Use [`references/source-mutations.md`](references/source-mutations.md) for file/ZIP source replacement and restoration. These new commands use `kb source <action>`; `+rollback` remains a whole-KB publication operation.
+
+| Command | Risk | Purpose |
+|---|---|---|
+| `source replace` | write | Replace an ordinary file draft, or prepare a ZIP archive replacement preview. |
+| `source restore` | write | Restore a file draft from a published version, or prepare a ZIP source/child restore preview. |
+| `source preview` | read | Read a page of ZIP candidate changes before confirmation. |
+| `source commit` | high-risk-write | Confirm a reviewed ZIP candidate, including any deletions. |
+| `source cancel` | high-risk-write | Discard an uncommitted ZIP candidate. |
+
+Require exact `--name`, `--scope`, current `--id`, and a current `--expected-revision` for mutations. File replacements keep the original format but allow different filenames. ZIP requires `.zip`. URL/Feishu and deleted parent sources are not supported. Updates affect the draft only; publication still requires compilation. ZIP previews must not be auto-committed. Do not retry uncertain writes.
+
 ## ZIP Directory Sources
 
 Use `+add --files '["./sources.zip"]'` to upload one ZIP as one editable parent source, preserving its internal hierarchy. Archive validation and limits are enforced by the server. This is different from `+import`, which creates a read-only compiled snapshot. Passing a local directory to `+add` still uploads only its immediate supported files; it does not recursively package that directory.
@@ -533,3 +550,25 @@ ae-cli kb +rm-source --name "<name>" --id "<source-id>" [--scope personal|compan
 ```bash
 ae-cli kb +remove --name "<name>" [--scope personal|company]
 ```
+
+## Check a Feishu source for updates
+
+```bash
+ae-cli kb source check-updates --name "Engineering Handbook" --id "<source-id>" --scope company --dry-run
+ae-cli kb source check-updates --name "Engineering Handbook" --id "<source-id>" --scope company
+```
+
+Copy the ID from `kb +list-sources`. Requires source write permission. Only compiled, non-deleted Feishu URL sources are eligible. The API uses the same detector as the scheduled task, including existing pending-change skips and source-owner sandbox credentials. It never starts compilation or clears pending changes.
+
+The synchronous response contains `sourceId`, `scanned`, `updated`, `failed`, `urlChangeState`, and `updateStatus`. `scanned` counts candidates, not completed content comparisons; `updated` counts newly marked sources. Zero updates can mean unchanged content, an already pending change, unavailable old raw, or a concurrent state change. It must not be reported as proof that all content is identical. Failed checks return a non-2xx response and a CLI error. A timeout does not prove completion or cancellation; read `kb +list-sources` before deciding whether to retry.
+
+Transport: `POST /agent/api/external/knowledge-bases/sources/check-updates`, body `{name, sourceId, scope?}`. `--dry-run` only previews the request and does not authenticate or check remote permissions.
+
+### Admission record: source check-updates
+
+- Classification: Transitional (no Gateway equivalent for this new detector trigger).
+- Owning module: te-claude knowledge-base source management.
+- Current transport: KB external REST through `kbApi` and CLI token.
+- Gateway target: TBD; reuse an equivalent source update-check capability when available.
+- Review after: 2026-10-16.
+- Exit condition: once the Gateway exposes equivalent authorization and detector semantics, migrate the typed command to L2 or use L3 if it adds no value.