@thinkingai/ae-cli 1.0.22 → 1.0.27

package/skills/ae-team/references/run-result.md

@@ -0,0 +1,75 @@
+# team +run-result (Get TeamRun Result)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **TeamRun execution / read**
+
+## Use Cases
+- Retrieve the full result of a TeamRun, including all steps, events, status, and output.
+- The primary command for polling run progress after `+run-start` or `+run-chat`.
+- Returns the run object with `status`, `output`, `steps`, and `error` (if failed).
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real run ID from a previous `+run-start` or `+run-chat` response — do not guess.
+- Poll this command repeatedly until `status` reaches a terminal value: `completed`, `failed`, or `cancelled`.
+- Do not call `+run-artifacts` until status is `completed`.
+
+## Command
+```bash
+ae-cli team +run-result --id <run_id>
+ae-cli team +run-result --id <run_id> --jq '.status'
+ae-cli team +run-result --dry-run --id <run_id>
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | TeamRun ID |
+
+## Key Response Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `status` | string | Current run status |
+| `output` | string \| null | Final output (populated when `completed`) |
+| `pendingQuestion` | string \| null | The question the team is asking the user; only populated when `status = waiting_user` |
+| `error` | object \| null | Error details when `status = failed` |
+| `steps` | array | All execution steps and events |
+
+## Status Transitions
+```
+pending → running → completed
+                 → waiting_user → (reply) → running → completed
+                 → failed
+                 → cancelled
+```
+
+Terminal statuses (stop polling): `completed`, `failed`, `cancelled`
+
+Non-terminal statuses (keep polling): `pending`, `running`, `waiting_approval`, `paused`
+
+Interrupt statuses (stop polling, get user input): `waiting_user`
+
+## Decision Rules
+- Check `status` field on each poll. Continue until terminal.
+- If `status = waiting_user`: read `pendingQuestion`, present it to the user, collect the answer, then call `+run-reply --id <run_id> --input "<user_answer>"`. Resume polling after reply.
+- If `status = failed`, inspect the `error` field to diagnose the issue.
+- If `status = completed`, proceed to `+run-artifacts` to retrieve produced files/outputs.
+- Use `--jq '{status,pendingQuestion}'` when polling to get both status and the pending question in one call.
+
+## Polling Best Practice
+```bash
+# Lightweight status + pendingQuestion check
+ae-cli team +run-result --id <run_id> --jq '{status,pendingQuestion}'
+
+# Full result when completed
+ae-cli team +run-result --id <run_id>
+```
+
+## Next Steps on Failure
+- `404`: run ID not found — verify from the original start response.
+- `status = failed`: report the `error.message` to the user and ask whether to retry with `+run-start`.
+
+## Recommended Chaining
+- `+run-start` or `+run-chat` → poll `+run-result` → terminal → `+run-artifacts`
+- `+run-result` → `waiting_user` → `+run-reply` → continue polling `+run-result`

package/skills/ae-team/references/run-start.md

@@ -0,0 +1,73 @@
+# team +run-start (Start TeamRun)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **TeamRun execution / write**
+
+## Use Cases
+- Start a new TeamRun for a given team with a task input.
+- Returns the newly created run object including its `id` and initial `status`.
+- Used for one-shot task execution. For multi-turn interactive sessions, use `+run-chat` instead.
+
+## Mandatory Rules (MUST)
+- `--team-id` is required. Obtain the real team ID via `+list` — do not guess.
+- `--input` is required (1–50000 chars). Pass the user's task description verbatim; do not truncate.
+- JSON array flags (`--project-ids`, `--project-names`, `--space-ids`, etc.) must be valid JSON arrays, e.g. `'["id1","id2"]'`.
+- `--notification` must be valid JSON if provided, e.g. `'{"channels":["feishu"],"feishuChatId":"..."}'`.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+- After starting, capture the returned `id` (run ID) and use it to poll `+run-result`.
+
+## Command
+```bash
+ae-cli team +run-start --team-id <team_id> --input "分析上周用户留存情况，生成报告" --yes
+
+ae-cli team +run-start \
+  --team-id <team_id> \
+  --input "分析本月DAU趋势" \
+  --notification '{"channels":["feishu"],"feishuChatId":"oc_xxx"}' \
+  --save-to-kb-id <kb_id> \
+  --yes
+
+ae-cli team +run-start --dry-run --team-id <team_id> --input "test"
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--team-id` | Yes | Team ID |
+| `--input` | Yes | Task input text (1–50000 chars) |
+| `--conversation-id` | No | Associated conversation ID |
+| `--notification` | No | Notification config JSON `{"channels":["feishu"\|"lark"\|"slack"],...}` |
+| `--save-to-kb-id` | No | Knowledge base ID to save result to on completion |
+| `--project-ids` | No | Associated project ID list JSON, e.g. `["id1"]` |
+| `--project-names` | No | Associated project name list JSON |
+| `--space-ids` | No | Associated space ID list JSON |
+| `--space-names` | No | Associated space name list JSON |
+| `--dw-space-codes` | No | Associated DW space code list JSON |
+| `--dw-space-names` | No | Associated DW space name list JSON |
+
+## Decision Rules
+- Use `+run-start` for single-shot automation tasks where no interactive back-and-forth is needed.
+- Use `+run-chat` instead when the user wants multi-turn conversation with the team.
+- After receiving the run `id`, immediately start polling `+run-result` until status is `completed`, `failed`, or `cancelled`.
+- If the run reaches `waiting_user`, use `+run-reply` to continue.
+
+## Watching for Completion
+```bash
+# Preferred: stream via SSE (blocks until done, no polling needed)
+ae-cli team +run-watch --id <run_id>
+# exit 0 → completed/partial_success
+# exit 1 → failed/cancelled/stale
+# exit 2 → waiting_user: read pendingQuestion from stdout, reply, re-watch
+ae-cli team +run-reply --id <run_id> --input "<user_answer>" --yes
+ae-cli team +run-watch --id <run_id>
+```
+
+## Next Steps on Failure
+- `404` team not found: re-run `+list` to verify the team ID.
+- `400` validation: check `--input` length and JSON flag formats.
+- Run reaches `failed` status: inspect the `error` field in `+run-result` output.
+
+## Recommended Chaining
+- `+list` → `+run-start` → poll `+run-result` → `+run-artifacts`
+- `+run-start` → status `waiting_user` → `+run-reply` → poll `+run-result`

package/skills/ae-team/references/run-watch.md

@@ -0,0 +1,82 @@
+# team +run-watch (Stream TeamRun via SSE)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **TeamRun execution / read**
+
+## Use Cases
+- Stream real-time progress of a TeamRun without polling.
+- Blocks until the run reaches a terminal state or `waiting_user`.
+- Preferred over `+run-result` polling for all automated workflows.
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real run ID from a previous `+run-start` or `+run-chat` response.
+- Check the **exit code** to determine what happened — do not guess from output alone.
+- When exit code is `2` (`waiting_user`): read `pendingQuestion` from stdout, present it to the user, collect their answer, call `+run-reply`, then re-run `+run-watch`.
+- Network drops are handled automatically (up to 10 reconnects with 2s delay). Do NOT retry `+run-watch` on exit 1 unless you have confirmed the run itself failed via `+run-result`.
+
+## Command
+```bash
+ae-cli team +run-watch --id <run_id>
+
+# Suppress stderr log/status noise (stdout JSON is unaffected)
+ae-cli team +run-watch --id <run_id> --quiet
+
+# Reconnect after drop, skip logs already seen
+ae-cli team +run-watch --id <run_id> --after-log <lastTimestamp>
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | TeamRun ID |
+| `--after-log` | No | Reconnect: skip log events at or before this timestamp |
+| `--quiet` | No | Suppress log and status lines on stderr; stdout JSON is always emitted |
+
+## Exit Codes
+| Code | Meaning | Action |
+|---|---|---|
+| `0` | `completed` or `partial_success` | Proceed to `+run-artifacts` |
+| `1` | `failed`, `cancelled`, `stale`, or connection error | Inspect `errorMessage` in stdout JSON; report to user |
+| `2` | `waiting_user` | Read `pendingQuestion` from stdout JSON, present to user, then `+run-reply` → re-run `+run-watch` |
+
+## Output
+stdout always receives the final `TeamRunEntity` as a standard JSON envelope:
+```json
+{ "ok": true, "data": { "id": "...", "status": "...", "pendingQuestion": "...", ... } }
+```
+- Exit 0/1: the entity from the `final` SSE event (terminal state)
+- Exit 2: the entity from the `update` SSE event at the moment `waiting_user` was detected
+
+stderr receives real-time log lines and status changes (suppressed with `--quiet`).
+
+## Handling waiting_user
+```bash
+# 1. Watch the run
+ae-cli team +run-watch --id <run_id>
+# exit code 2 → waiting_user
+
+# 2. Read pendingQuestion from stdout, present to user, collect answer
+# 3. Submit the reply
+ae-cli team +run-reply --id <run_id> --input "<user_answer>" --yes
+
+# 4. Resume watching
+ae-cli team +run-watch --id <run_id>
+```
+
+## SSE Events (reference)
+| Event | Frequency | Payload |
+|---|---|---|
+| `snapshot` | Once on connect | `TeamRunEntity` |
+| `update` | Every 500ms when changed | `TeamRunEntity` |
+| `final` | On terminal state, then closes | `TeamRunEntity` |
+| `log` | Real-time (with history replay) | `{ timestamp, stepId, type, content }` |
+| `error` | On auth/read failure | `{ error: string }` |
+
+## Next Steps on Failure
+- Exit 1 + `status = failed`: read `errorMessage` in the JSON output; ask user whether to retry with `+run-start`.
+- Connection drop before `final`: re-run `+run-watch --id <run_id> --after-log <lastTimestamp>`.
+
+## Recommended Chaining
+- `+run-start` → `+run-watch` → exit 0 → `+run-artifacts`
+- `+run-watch` → exit 2 → `+run-reply` → `+run-watch`

package/skills/ae-team/references/update.md

@@ -0,0 +1,47 @@
+# team +update (Update Team)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Team management / write**
+
+## Use Cases
+- Partially update an existing team (PATCH semantics — only the fields you pass are changed).
+- Common uses: rename a team, update its config, disable/enable it, change scope.
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real team ID via `+list` — do not guess.
+- At least one optional field must be provided in addition to `--id`.
+- `--config` replaces the entire TeamConfig; provide the complete new config, not a partial patch.
+- `--scope` must be `personal` or `company` if provided.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## Command
+```bash
+ae-cli team +update --id <team_id> --name "新名称"
+ae-cli team +update --id <team_id> --enabled false
+ae-cli team +update --id <team_id> --config '<full_new_config_json>' --yes
+ae-cli team +update --dry-run --id <team_id> --name "Test"
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Team ID |
+| `--name` | No | New team name |
+| `--config` | No | New complete TeamConfig JSON |
+| `--description` | No | New description |
+| `--scope` | No | `personal` \| `company` |
+| `--enabled` | No | `true` \| `false` |
+
+## Decision Rules
+- If the user wants to modify only the name or description, pass only those flags — the server keeps all other fields unchanged.
+- If the user wants to update the config, first call `+list` with `--jq` to extract the current config, modify it, then pass the updated config to `+update`.
+- `--enabled false` disables the team without deleting it.
+
+## Next Steps on Failure
+- `404`: team ID not found — re-run `+list` to verify.
+- `409`: there may be active runs; wait for them to complete or cancel them with `+run-cancel` first.
+
+## Recommended Chaining
+- `+list` → confirm `id` → `+update`
+- `+update --enabled false` → `+delete` (when ready to delete)