@thinkingai/ae-cli 1.0.24 → 1.0.28

package/skills/ae-team/references/list-templates.md

@@ -0,0 +1,38 @@
+# team +list-templates (List Team Templates)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Team management / discovery**
+
+## Use Cases
+- Browse built-in team templates provided by the platform.
+- Each template includes a ready-to-use `config` that can be passed directly to `+create --config`.
+- Supports locale-specific template names and descriptions.
+
+## Mandatory Rules (MUST)
+- Do not fabricate template names or configs. Always call this command first and present the real list to the user.
+- `--locale` must be one of `zh`, `en`, `ja`, `ko` if provided.
+
+## Command
+```bash
+ae-cli team +list-templates
+ae-cli team +list-templates --locale en
+ae-cli team +list-templates --locale zh --format table
+ae-cli team +list-templates --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--locale` | No | `zh` (default) \| `en` \| `ja` \| `ko` |
+
+## Decision Rules
+- When the user says "show me team templates" or "I want to create a team from a template", call this command first.
+- Extract the `config` field from the chosen template and pass it to `+create --config`.
+- If the user asks for templates in a specific language, pass the corresponding `--locale`.
+
+## Next Steps on Failure
+- Empty list: the platform may not have templates configured for the current environment.
+
+## Recommended Chaining
+- `+list-templates` → user picks template → `+create --name "..." --config '<template.config>'`

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

@@ -0,0 +1,39 @@
+# team +list (List Teams)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Team discovery**
+
+## Use Cases
+- List all AI Agent teams visible to the current user.
+- Returns an array of team summaries; key fields include `id`, `name`, `description`, `scope`, `enabled`, `config`.
+- Use this as the first step before any run or update operation to confirm the target `team_id`.
+
+## Mandatory Rules (MUST)
+- Do not guess team IDs. Always call `+list` first to discover real team IDs.
+- If the user references a team by name, match the name against the returned list before proceeding.
+
+## Command
+```bash
+ae-cli team +list
+ae-cli team +list --format table
+ae-cli team +list --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| None | — | No parameters required |
+
+## Decision Rules
+- When the user says "show me the teams", "what teams do I have", or needs a `team_id` for a subsequent command and none is in context, call this first.
+- If many teams are returned, summarize by `id`, `name`, `scope`, and `enabled` to help the user pick the right one.
+- Once a team is confirmed in the current conversation, reuse its ID without calling `+list` again unless the user switches teams.
+
+## Next Steps on Failure
+- Empty result: confirm account permissions and host environment.
+- Auth error: run `ae-cli auth login`.
+
+## Recommended Chaining
+- `+list` → user confirms `team_id` → `+run-start` or `+run-chat`
+- `+list` → `+update` or `+delete`

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

@@ -0,0 +1,51 @@
+# team +run-artifacts (List TeamRun Artifacts)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **TeamRun execution / read**
+
+## Use Cases
+- List all artifacts (output files, reports, documents) produced by a completed TeamRun.
+- By default, returns metadata only (no content). Use `--include-content true` to fetch full artifact content.
+- Supports filtering by artifact type.
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real run ID from a previous `+run-start` or `+run-chat` response — do not guess.
+- Only call this command after `+run-result` confirms `status = completed`. Artifacts may be incomplete for non-terminal runs.
+
+## Command
+```bash
+# List artifact metadata (no content)
+ae-cli team +run-artifacts --id <run_id>
+
+# Include full content
+ae-cli team +run-artifacts --id <run_id> --include-content true
+
+# Filter by type
+ae-cli team +run-artifacts --id <run_id> --artifact-type report
+
+# Combine
+ae-cli team +run-artifacts --id <run_id> --artifact-type markdown --include-content true
+
+ae-cli team +run-artifacts --dry-run --id <run_id>
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | TeamRun ID |
+| `--artifact-type` | No | Filter by artifact type (e.g. `report`, `markdown`, `xlsx`) |
+| `--include-content` | No | `true` to include full artifact content (default: `false`) |
+
+## Decision Rules
+- First call without `--include-content` to get the list and sizes. Then decide whether to fetch content.
+- Use `--include-content true` only when the user explicitly wants the artifact body (e.g. to display a report, extract data, or forward the content).
+- If the run has not yet completed, call `+run-result` first and wait for terminal status.
+
+## Next Steps on Failure
+- `404`: run ID not found — verify from the original start response.
+- Empty list: the run completed but produced no artifacts; inspect `+run-result` output for any inline results.
+
+## Recommended Chaining
+- `+run-result` (confirm `completed`) → `+run-artifacts`
+- `+run-artifacts` → user reviews metadata → `+run-artifacts --include-content true` (fetch content for specific artifact)

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

@@ -0,0 +1,38 @@
+# team +run-cancel (Cancel TeamRun)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **TeamRun execution / write**
+
+## Use Cases
+- Cancel a TeamRun that is in `pending`, `running`, or `waiting_user` state.
+- After cancellation, the run transitions to `cancelled` (a terminal status).
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real run ID from a previous `+run-start` or `+run-chat` response — do not guess.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+- Cancellation is irreversible. To re-run the same task, call `+run-start` again.
+
+## Command
+```bash
+ae-cli team +run-cancel --id <run_id>
+ae-cli team +run-cancel --id <run_id> --yes
+ae-cli team +run-cancel --dry-run --id <run_id>
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | TeamRun ID |
+
+## Decision Rules
+- Before cancelling, verify the run status with `+run-result` to confirm it is not already in a terminal state (`completed`, `failed`, `cancelled`).
+- If the user wants to delete a team that has active runs, cancel all active runs first, then call `+delete`.
+
+## Next Steps on Failure
+- `404`: run ID not found — verify the run ID from the original start response.
+- Already terminal: the run has already completed, failed, or been cancelled — no action needed.
+
+## Recommended Chaining
+- `+run-result` (verify status) → `+run-cancel --yes`
+- `+run-cancel` (clear active runs) → `+delete` (team)

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

@@ -0,0 +1,57 @@
+# team +run-chat (Chat with Team)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **TeamRun execution / write**
+
+## Use Cases
+- Send a message to a team in a multi-turn conversational session.
+- If the current session has a run in `waiting_user` state, the platform automatically resumes it.
+- Returns the session object (including `session.id`) and the new run object (including `run.id` and `status`).
+
+## Mandatory Rules (MUST)
+- `--team-id` is required. Obtain the real team ID via `+list` — do not guess.
+- `--input` is required. Pass the user's message verbatim.
+- To continue an existing session, pass `--session-id` with the `session.id` from the previous turn.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+- After each turn, capture `session.id` and `run.id` for subsequent turns or replies.
+
+## Command
+```bash
+# First turn (starts a new session)
+ae-cli team +run-chat --team-id <team_id> --input "帮我分析最近的DAU趋势" --yes
+
+# Continue the same session
+ae-cli team +run-chat --team-id <team_id> --session-id <session_id> --input "继续上次的分析" --yes
+
+ae-cli team +run-chat --dry-run --team-id <team_id> --input "test"
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--team-id` | Yes | Team ID |
+| `--input` | Yes | User message |
+| `--session-id` | No | Existing session ID for multi-turn continuation |
+
+## Decision Rules
+- Use `+run-chat` when the task requires interactive back-and-forth (e.g. the team may ask clarifying questions).
+- Use `+run-start` instead for fully automated, single-shot tasks.
+- Always persist `session.id` from the response and pass it on subsequent turns with `--session-id`.
+- If a run enters `waiting_user` state, use `+run-reply` (not another `+run-chat`) to respond.
+
+## Waiting User Flow
+```
++run-chat → run.status = waiting_user
+→ +run-reply --id <run_id> --input "..." --yes
+→ poll +run-result until terminal
+→ optionally continue with +run-chat --session-id <session_id>
+```
+
+## Next Steps on Failure
+- `404` team not found: re-run `+list` to verify the team ID.
+- Session state confusion: if unsure of current session state, call `+run-result --id <run_id>` to check status.
+
+## Recommended Chaining
+- `+list` → `+run-chat` → `+run-reply` (if waiting_user) → `+run-result` → `+run-artifacts`
+- `+run-chat` (turn 1) → capture `session.id` → `+run-chat --session-id ...` (turn 2+)

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

@@ -0,0 +1,41 @@
+# team +run-reply (Reply to Waiting TeamRun)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **TeamRun execution / write**
+
+## Use Cases
+- Provide a user reply to a TeamRun that is paused in `waiting_user` state.
+- After reply, the run resumes execution automatically.
+
+## Mandatory Rules (MUST)
+- `--id` is required. The run **must be in `waiting_user` state** — sending a reply to a run in any other state will fail.
+- `--input` is required (1–50000 chars). Pass the user's reply verbatim.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+- After replying, poll `+run-result` until the run reaches a terminal status.
+
+## Command
+```bash
+ae-cli team +run-reply --id <run_id> --input "请继续，使用方案A" --yes
+ae-cli team +run-reply --id <run_id> --input "好的，请重点分析周末下降原因" --yes
+ae-cli team +run-reply --dry-run --id <run_id> --input "test"
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | TeamRun ID (must be in `waiting_user` state) |
+| `--input` | Yes | User reply content (1–50000 chars) |
+
+## Decision Rules
+- Before calling `+run-reply`, always verify the run is in `waiting_user` state via `+run-result`.
+- If the run is in `running` state (not yet paused), wait and poll again — do not send a reply prematurely.
+- If the run is in a terminal state, it cannot be replied to — start a new run if needed.
+
+## Next Steps on Failure
+- `400` / wrong state: check the run status with `+run-result` first.
+- `404`: run ID not found — verify from the original start response.
+
+## Recommended Chaining
+- `+run-result` (confirm `waiting_user`) → `+run-reply` → poll `+run-result` → `+run-artifacts`
+- In chat mode: `+run-chat` → status `waiting_user` → `+run-reply` → `+run-chat` (next turn)

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)