@thinkingai/ae-cli 1.0.24 → 1.0.28

package/skills/ae-kb/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: ae-kb
+version: 1.0.0
+description: "AE/TE knowledge base CLI manual for creating, querying, deterministic index/grep/read retrieval, checking status, uploading, compiling, schema generation, URL sources, source deletion, and knowledge base deletion. Use when the user asks to manage TE/AE/ThinkingEngine knowledge bases, upload documents or URLs to a knowledge base, query knowledge, 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. Must use ae-cli kb commands and must not guess knowledge base names, scopes, page paths, source display names, JSON payload shapes, or URL formats."
+---
+
+# ae-kb
+
+AE CLI (`ae-cli`) knowledge base commands are invoked through:
+
+```bash
+ae-cli kb +<command> [options]
+```
+
+## Global Rules
+
+- Use this skill for TE/AE knowledge base tasks: create, query, inspect indexes, grep pages, read pages, check status, upload sources, add URL sources, generate schema, compile, remove source files, and delete knowledge bases.
+- 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 display names, or JSON payloads. Ask the user or query known context when values are missing.
+- JSON flags must be valid JSON strings, usually wrapped in single quotes in shell commands.
+- Successful commands return JSON by default. Use `--format table` only when a table is easier for a human to scan.
+- `--host <url>` overrides the active AE host. It is available on every command and may be placed after the subcommand, e.g. `ae-cli kb +<command> --host <url>`.
+- For external-agent retrieval, prefer the deterministic flow `+index` -> `+grep` -> `+read`: inspect navigation, locate candidate pages, then open the exact page or line window.
+
+## Commands
+
+| Command | Risk | Purpose |
+|---|---:|---|
+| `+query` | read | Query one or more knowledge bases with a natural-language question. |
+| `+index` | read | List accessible knowledge bases and their `index.md` navigation maps. |
+| `+grep` | read | Keyword-search knowledge base pages and return matched lines with context. |
+| `+read` | read | Read a full knowledge base page or a line window. |
+| `+new` | write | Create a new personal or company knowledge base. |
+| `+add` | write | Upload local files, a non-recursive directory, or HTTP(S) pages converted to markdown. |
+| `+url` | write | Upload a URL source directly with optional display name and parsing instruction. |
+| `+schema` | write | Generate the compile schema for a knowledge base. |
+| `+compile` | write | Compile a knowledge base in incremental or full mode. |
+| `+status` | read | Query the current status of a knowledge base. |
+| `+rm-source` | write | Delete one source file from a knowledge base by display name. |
+| `+remove` | write | Delete an entire knowledge base. |
+
+## Common Workflows
+
+### Create a Knowledge Base
+
+Use `+new` with name. `--scope` is optional and defaults to `company`; valid scopes are `personal` and `company`.
+
+```bash
+ae-cli kb +new \
+  --scope company \
+  --name engineering-handbook \
+  --description "Engineering handbook" \
+  --tags '["engineering","handbook"]'
+```
+
+Optional fields:
+
+- `--scope`: scope, defaults to `company`.
+- `--description`: description, up to 200 characters.
+- `--tags`: JSON array, max 2 tags, each up to 15 characters.
+- `--project-id`: optional project ID to bind.
+- `--project-name`: optional project display name.
+
+### Upload Files or Directories
+
+Use `+add` when sources are local files, local directories, or pages that should be fetched and converted to markdown before upload.
+
+```bash
+ae-cli kb +add \
+  --name engineering-handbook \
+  --files '["./README.md","./docs","https://example.com/guide"]'
+```
+
+Input rules:
+
+- `--files` must be a JSON array of strings.
+- Local directory reading is non-recursive.
+- URL entries must start with `http://` or `https://`.
+- Supported extensions include markdown/text, office documents, PDFs, spreadsheets, presentations, and common images. Local files are uploaded as multipart file blobs; HTTP(S) pages are fetched and converted to markdown before upload.
+- Duplicate filenames are automatically suffixed as `name-1.ext`, `name-2.ext`, etc.
+
+### Add a URL Source
+
+Use `+url` when adding one URL source and optionally passing a display name or parsing instruction.
+
+```bash
+ae-cli kb +url \
+  --name engineering-handbook \
+  --url https://example.com/guide \
+  --display-name guide \
+  --parse-instruction "Keep headings and code blocks"
+```
+
+`--url` must be `http(s)`.
+
+### Generate Schema and Compile
+
+Generate the schema first when the knowledge base needs a compile schema.
+
+```bash
+ae-cli kb +schema --name engineering-handbook
+```
+
+Use `--force` only to recover a stuck `generating` status. Use `--model` only when the user provides the model display name.
+
+Compile after sources and schema are ready:
+
+```bash
+ae-cli kb +compile --name engineering-handbook --mode incremental
+```
+
+Valid compile modes are `incremental` and `full`; default is `incremental`.
+
+### Check Knowledge Base Status
+
+Use `+status` to inspect the current status of a knowledge base.
+
+```bash
+ae-cli kb +status --name engineering-handbook
+```
+
+### Query Knowledge
+
+Use `+query` with a natural-language question and a JSON array of source refs.
+
+```bash
+ae-cli kb +query \
+  --query "How do we release a dashboard?" \
+  --sources '[{"scope":"company","name":"engineering-handbook"}]'
+```
+
+`--sources` entries require:
+
+- `scope`: knowledge base scope such as `personal` or `company`.
+- `name`: knowledge base name.
+
+### Explore Knowledge Base Pages
+
+Use the deterministic retrieval primitives when an agent needs to explore knowledge base content like a code repository. These endpoints do not call an LLM on the server side.
+
+Start with `+index` to see accessible knowledge bases and navigation maps:
+
+```bash
+ae-cli kb +index \
+  --sources '[{"scope":"company","name":"engineering-handbook"}]'
+```
+
+Then use `+grep` to locate likely pages and line numbers:
+
+```bash
+ae-cli kb +grep \
+  --query "sandbox configuration" \
+  --sources '[{"scope":"company","name":"engineering-handbook"}]' \
+  --top-k 10
+```
+
+Finally use `+read` to open the exact page, optionally with a line window:
+
+```bash
+ae-cli kb +read \
+  --source '{"scope":"company","name":"engineering-handbook"}' \
+  --path "wiki/sandbox.md" \
+  --offset 1 \
+  --limit 200
+```
+
+Retrieval rules:
+
+- `+index` accepts optional `--sources` and `--locale`; omit `--sources` to list all accessible knowledge bases.
+- `+grep` requires `--query` / `-q`; optional `--sources`, `--top-k` (1-50, default 10), and `--locale`.
+- `+read` requires `--source` pointing to exactly one knowledge base and `--path` relative to the knowledge base root; optional `--offset`, `--limit` (1-2000), and `--locale`.
+- Do not guess a `--path`; get it from `+index` or `+grep` results.
+
+### Remove One Source
+
+Use `+rm-source` only when the source display name is known exactly.
+
+```bash
+ae-cli kb +rm-source \
+  --name engineering-handbook \
+  --display-name kb-1780046712-guide.md
+```
+
+If the user only gives a loose source name, do not guess. Ask for the exact uploaded display name.
+
+### Delete a Knowledge Base
+
+Use `+remove` for deleting the entire knowledge base. Confirm the target name with the user if there is any ambiguity.
+
+```bash
+ae-cli kb +remove --name engineering-handbook
+```
+
+## Command Reference
+
+### `+query`
+
+```bash
+ae-cli kb +query --query "<question>" --sources '[{"scope":"company","name":"kb-name"}]'
+```
+
+- `--query`, alias `-q`: required natural-language question.
+- `--sources`: required JSON array of knowledge base refs.
+
+### `+index`
+
+```bash
+ae-cli kb +index [--sources '[{"scope":"company","name":"kb-name"}]'] [--locale zh|en|ja|ko]
+```
+
+- `--sources`: optional JSON array of knowledge base refs. Omit to list all accessible knowledge bases.
+- `--locale`: optional locale: `zh`, `en`, `ja`, or `ko`.
+
+### `+grep`
+
+```bash
+ae-cli kb +grep --query "<keywords>" [--sources '[{"scope":"company","name":"kb-name"}]'] [--top-k 10] [--locale zh|en|ja|ko]
+```
+
+- `--query`, alias `-q`: required keywords to search across knowledge bases.
+- `--sources`: optional JSON array of knowledge base refs. Omit to search all accessible knowledge bases.
+- `--top-k`: optional max number of hits, 1-50, default 10.
+- `--locale`: optional locale: `zh`, `en`, `ja`, or `ko`.
+
+### `+read`
+
+```bash
+ae-cli kb +read --source '{"scope":"company","name":"kb-name"}' --path "index.md" [--offset 1] [--limit 200] [--locale zh|en|ja|ko]
+```
+
+- `--source`: required JSON object pointing to exactly one knowledge base.
+- `--path`: required page path relative to the knowledge base root, such as `index.md` or `wiki/concepts/data-model.md`.
+- `--offset`: optional 1-based start line.
+- `--limit`: optional max line count, 1-2000.
+- `--locale`: optional locale: `zh`, `en`, `ja`, or `ko`.
+
+### `+new`
+
+```bash
+ae-cli kb +new --name "<name>" [--scope personal|company] [--description "..."] [--tags '["t1","t2"]'] [--project-id "..."] [--project-name "..."]
+```
+
+### `+add`
+
+```bash
+ae-cli kb +add --name "<name>" --files '["./a.md","./docs","https://example.com/page"]'
+```
+
+### `+url`
+
+```bash
+ae-cli kb +url --name "<name>" --url "https://example.com/page" [--display-name "..."] [--parse-instruction "..."]
+```
+
+### `+schema`
+
+```bash
+ae-cli kb +schema --name "<name>" [--force] [--model "<model displayName>"]
+```
+
+### `+compile`
+
+```bash
+ae-cli kb +compile --name "<name>" [--mode incremental|full]
+```
+
+### `+status`
+
+```bash
+ae-cli kb +status --name "<name>"
+```
+
+### `+rm-source`
+
+```bash
+ae-cli kb +rm-source --name "<name>" --display-name "<uploaded source display name>"
+```
+
+### `+remove`
+
+```bash
+ae-cli kb +remove --name "<name>"
+```

package/skills/ae-team/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: ae-team
+version: 1.0.0
+description: "AE/TE/ThinkingEngine/ThinkingAI ae-cli manual for AI Agent Team tasks: managing teams (list, create, update, delete, AI-generate, templates) and executing TeamRuns (start, chat, cancel, reply, result, artifacts). Use when the user asks to find a team, run a team task, check run status, retrieve results or artifacts, or set up multi-agent workflows. Must use ae-cli, read the matching references/<command>.md before composing commands, and never guess team IDs, run IDs, config structures, or parameter formats."
+---
+
+# ae-team
+
+> **CRITICAL — Before running any `+<command>` command, you MUST first read the corresponding `references/<command>.md`.** The reference filename equals the command name without the leading `+`, for example `+run-start` → `references/run-start.md`.
+> **CRITICAL — Never guess team IDs, run IDs, or config JSON structures.** Always use `+list` or `+list-templates` to discover real resources first.
+> **CRITICAL — For the core Agent workflow (find → start → poll → artifacts), follow Workflow A in the Typical Workflows section below.**
+
+## Global AE CLI Rules
+
+AE CLI (`ae-cli`) is the command-line tool for the AE / TE / ThinkingEngine analysis platform.
+
+Global parameters:
+
+| Parameter | Description |
+|---|---|
+| `--format <json\|table>` | Output format. Default is JSON. |
+| `--jq <expr>` | jq filter expression for JSON output. |
+| `--host <url>` | Override the active AE host. Available on every command and may be placed after the subcommand, e.g. `ae-cli team +<command> --host <url>`. |
+| `--yes` | Skip confirmation for write operations. |
+| `--dry-run` | Show request details without executing. |
+
+Output and errors:
+- Successful commands return machine-readable JSON by default.
+- Failed commands return `{ "ok": false, "error": { "type": "...", "message": "...", "hint": "..." } }` and exit non-zero.
+
+Safety constraints:
+- Read commands (`+list`, `+list-templates`, `+list-projects`, `+run-result`, `+run-artifacts`, `+ai-generate`) can execute directly once required IDs are known.
+- Write commands require explicit user intent and keep the confirmation prompt by default. Pass `--yes` only in fully automated pipelines.
+- Never invent team IDs, run IDs, `agentId` values, `mcpServerIds`, `skillIds`, `knowledgeBaseIds`, project IDs, or any resource identifiers. Discover them with list commands or accept them from the user.
+
+## When to Use
+
+Use `ae-team` for all AI Agent Team work:
+
+- **Team management**: list available teams, create/update/delete a team, generate a team config draft with AI, browse templates.
+- **TeamRun execution**: start a run, interact in chat mode, cancel a run, reply to a waiting run, poll result until completion, retrieve artifacts.
+
+If the user's intent is data analysis, audience management, metadata governance, or DataOps, switch to `ae-analysis` / `ae-dataops` / `ae-engage`.
+
+## Command Format
+
+```bash
+ae-cli team +<command> [options]
+```
+
+All commands live under the `team` service. Quick help:
+
+```bash
+ae-cli team --help
+ae-cli team +list --help
+ae-cli team +run-start --help
+```
+
+## Tool Groups (13)
+
+### Team Management (7)
+
+- `+list` ([doc](references/list.md)) — list all visible teams
+- `+create` ([doc](references/create.md)) — create a new team with a TeamConfig
+- `+update` ([doc](references/update.md)) — patch one or more fields of an existing team
+- `+delete` ([doc](references/delete.md)) — delete a team (409 if runs are active)
+- `+ai-generate` ([doc](references/ai-generate.md)) — AI-generate a team config draft from a goal description
+- `+list-templates` ([doc](references/list-templates.md)) — browse built-in team templates
+- `+list-projects` ([doc](references/list-projects.md)) — list projects available to the current user
+
+### TeamRun Execution (7)
+
+- `+run-start` ([doc](references/run-start.md)) — start a new TeamRun
+- `+run-watch` ([doc](references/run-watch.md)) — stream a TeamRun via SSE (preferred over polling)
+- `+run-chat` ([doc](references/run-chat.md)) — chat with a team (multi-turn, auto-resume)
+- `+run-cancel` ([doc](references/run-cancel.md)) — cancel a running TeamRun
+- `+run-reply` ([doc](references/run-reply.md)) — reply to a run in `waiting_user` state
+- `+run-result` ([doc](references/run-result.md)) — get the full result of a TeamRun (fallback polling)
+- `+run-artifacts` ([doc](references/run-artifacts.md)) — list artifacts produced by a TeamRun
+
+## TeamRun Status Reference
+
+| Status | Description |
+|---|---|
+| `pending` | Queued, waiting to start |
+| `running` | Actively executing |
+| `waiting_user` | Paused — `+run-watch` exits with code 2; read `pendingQuestion` from stdout, present to user, then call `+run-reply` |
+| `waiting_approval` | Paused — waiting for approval |
+| `paused` | Manually paused |
+| `completed` | Finished successfully |
+| `failed` | Execution failed |
+| `cancelled` | Cancelled by user |
+
+Terminal statuses: `completed`, `failed`, `cancelled`. Poll `+run-result` until one of these is reached.
+
+## Typical Workflows
+
+### Workflow A — Start an existing team and wait for results
+
+```bash
+# 1. Discover available teams
+ae-cli team +list
+
+# 2. (Optional) Discover project IDs if needed
+ae-cli team +list-projects
+
+# 3. Start a run
+ae-cli team +run-start --team-id <team_id> --input "分析上周用户留存数据" --yes
+
+# 4. Stream until done (blocks; no polling needed)
+ae-cli team +run-watch --id <run_id>
+# exit 0 → completed/partial_success → go to step 5
+# exit 1 → failed/cancelled → inspect errorMessage in output, report to user
+# exit 2 → waiting_user → go to step 4a
+
+# 4a. Handle waiting_user: read pendingQuestion from stdout, get user's answer, reply, re-watch
+ae-cli team +run-reply --id <run_id> --input "<user_answer>" --yes
+ae-cli team +run-watch --id <run_id>   # repeat until exit 0 or 1
+
+# 5. Retrieve artifacts
+ae-cli team +run-artifacts --id <run_id> --include-content true
+```
+
+### Workflow B — AI-generate a config, then create and run
+
+```bash
+# 1. Generate a draft config
+ae-cli team +ai-generate --prompt "需要一个分析用户行为并自动生成留存报告的团队"
+
+# 2. Create the team (paste / adjust the returned config)
+ae-cli team +create --name "留存分析团队" --config '<config_json>' --yes
+
+# 3. Start a run
+ae-cli team +run-start --team-id <new_team_id> --input "分析本月留存" --yes
+```
+
+### Workflow C — Multi-turn chat
+
+```bash
+# First turn
+ae-cli team +run-chat --team-id <team_id> --input "帮我分析DAU趋势" --yes
+
+# If run status is waiting_user, reply:
+ae-cli team +run-reply --id <run_id> --input "请重点分析周末下降原因" --yes
+
+# Continue same session
+ae-cli team +run-chat --team-id <team_id> --session-id <session_id> --input "给出优化建议" --yes
+```
+
+### Workflow D — Use a template to create a team
+
+```bash
+# 1. Browse templates
+ae-cli team +list-templates --locale zh
+
+# 2. Create from a template's config
+ae-cli team +create --name "我的分析团队" --config '<template_config>' --yes
+```
+
+## Quick Verification
+
+```bash
+ae-cli team --help
+```

package/skills/ae-team/references/ai-generate.md

@@ -0,0 +1,39 @@
+# team +ai-generate (AI-Generate Team Config Draft)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Team management / config generation**
+
+## Use Cases
+- Given a plain-language description of a team's goal, generate a draft `{ name, description, members[] }` that can be reviewed and passed to `+create --config`.
+- Useful when the user has a goal but does not know how to write a TeamConfig manually.
+
+## Mandatory Rules (MUST)
+- `--prompt` is required (1–2000 chars). Pass the user's goal description as-is; do not pad it with generic boilerplate.
+- The returned draft is a **suggestion only** — always show it to the user for review before calling `+create`. Do not auto-create without user confirmation.
+- Do not fabricate `agentId` values; if the draft contains placeholder IDs, the user must replace them with real agent IDs before creating the team.
+
+## Command
+```bash
+ae-cli team +ai-generate --prompt "需要一个能分析用户留存并生成周报的团队"
+ae-cli team +ai-generate --prompt "A team that monitors DAU trends and sends alerts" --model <model_id>
+ae-cli team +ai-generate --dry-run --prompt "test"
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--prompt` | Yes | Team goal description (1–2000 chars) |
+| `--model` | No | Model ID to use for generation |
+
+## Decision Rules
+- If the user says "help me create a team" or "generate a team for [goal]", call this command first rather than jumping to `+create`.
+- Present the returned `name`, `description`, and `members` to the user. Ask them to confirm or adjust before proceeding.
+- If the user already has a config in mind, skip this command and go directly to `+create`.
+
+## Next Steps on Failure
+- Empty or low-quality result: ask the user to refine the prompt with more specific goals, roles, or steps.
+- Model error: try omitting `--model` to use the default.
+
+## Recommended Chaining
+- `+ai-generate` → user reviews and adjusts draft → `+create`

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

@@ -0,0 +1,94 @@
+# team +create (Create Team)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Team management / write**
+
+## Use Cases
+- Create a new AI Agent team with a given name and TeamConfig.
+- Returns the newly created team object including its `id`.
+
+## Mandatory Rules (MUST)
+- `--config` must be a valid TeamConfig JSON (see structure below). Do not invent `agentId`, `mcpServerIds`, `skillIds`, or `knowledgeBaseIds` — obtain real IDs from the user or the appropriate resource discovery commands.
+- `--name` must be 1–100 characters.
+- `--description` must be ≤2000 characters if provided.
+- `--scope` must be `personal` or `company` if provided; defaults to `personal` on the server.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## TeamConfig Structure
+
+```json
+{
+  "version": 1,
+  "mode": "serial | parallel | leader",
+  "steps": [
+    {
+      "id": "s1",
+      "name": "Step name",
+      "agentId": "<real agent ID>",
+      "prompt": "Step instructions (≤50000 chars)",
+      "role": "agent | leader | reviewer",
+      "retryLimit": 2,
+      "dependencies": [],
+      "resourceOverride": {
+        "mcpServerIds": [],
+        "skillIds": [],
+        "knowledgeBaseIds": [],
+        "model": null
+      }
+    }
+  ],
+  "maxConcurrency": 5,
+  "output": {
+    "format": "markdown | json | xlsx | pptx | pdf | docx"
+  }
+}
+```
+
+**Mode constraints:**
+- `serial` / `parallel`: `steps` ≥ 1
+- `leader`: `steps` ≥ 2 (all `role: "agent"`), requires `leaderConfig`
+
+**leaderConfig** (required when `mode: "leader"`):
+```json
+"leaderConfig": {
+  "agentId": "<leader agent ID>",
+  "maxIterations": 10,
+  "availableAgents": [
+    { "id": "a1", "agentId": "...", "name": "...", "description": "...", "capabilities": "..." }
+  ]
+}
+```
+
+## Command
+```bash
+ae-cli team +create \
+  --name "日报分析团队" \
+  --config '{"version":1,"mode":"serial","steps":[{"id":"s1","name":"分析师","agentId":"xxx","prompt":"分析数据","role":"agent"}]}'
+
+ae-cli team +create --name "My Team" --config '...' --scope company --yes
+ae-cli team +create --dry-run --name "Test" --config '{}'
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--name` | Yes | Team name (1–100 chars) |
+| `--config` | Yes | TeamConfig JSON object |
+| `--description` | No | Description (≤2000 chars) |
+| `--scope` | No | `personal` (default) \| `company` |
+| `--enabled` | No | `true` (default) \| `false` |
+
+## Decision Rules
+- If the user provides a goal description instead of a config, call `+ai-generate` first to get a draft, then ask the user to review before calling `+create`.
+- If the user wants to base a team on a template, call `+list-templates` first to get the template config.
+- Always use `--dry-run` first when building a complex config to verify the request shape before executing.
+
+## Next Steps on Failure
+- `Invalid JSON`: check TeamConfig structure, especially `version`, `mode`, `steps[].id`, `steps[].agentId`.
+- `400 / validation error`: verify that `mode` constraints are satisfied (e.g. `leader` requires `leaderConfig`).
+- After success, capture the returned `id` for subsequent `+run-start` calls.
+
+## Recommended Chaining
+- `+ai-generate` → review draft → `+create` → `+run-start`
+- `+list-templates` → pick template config → `+create` → `+run-start`

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

@@ -0,0 +1,39 @@
+# team +delete (Delete Team)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Team management / write**
+
+## Use Cases
+- Permanently delete a team by ID.
+- Returns `{ "ok": true }` on success.
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real team ID via `+list` — do not guess.
+- If the team has running tasks, the server returns **409**. Cancel or wait for active runs before retrying.
+- This is an irreversible operation — confirm with the user before executing.
+
+## Command
+```bash
+ae-cli team +delete --id <team_id>
+ae-cli team +delete --id <team_id> --yes
+ae-cli team +delete --dry-run --id <team_id>
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Team ID |
+
+## Decision Rules
+- Always call `+list` first to confirm the `id` and that the user is targeting the correct team.
+- If the server returns 409, call `+run-result` on active runs to check their status, then use `+run-cancel` to cancel any `running` or `waiting_user` runs.
+- Do not retry delete until all active runs have reached a terminal status.
+
+## Next Steps on Failure
+- `409 Conflict`: cancel active runs first (`+run-cancel --id <run_id> --yes`), then retry.
+- `404`: team already deleted or wrong ID — re-run `+list` to verify.
+
+## Recommended Chaining
+- `+list` → confirm target → `+delete`
+- `+run-cancel` (clear active runs) → `+delete`

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

@@ -0,0 +1,45 @@
+# team +list-projects (List Available Projects)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Project discovery**
+
+## Use Cases
+- List all projects the current user has access to, sourced from the authentication endpoint.
+- Returns an array of `{ projectId, projectName }` objects.
+- Use this before `+run-start` when you need to populate `--project-ids` or `--project-names` but don't know the available project IDs.
+
+## Mandatory Rules (MUST)
+- Do not guess project IDs or project names. Call `+list-projects` first to discover real values.
+- If the user references a project by name, match it against the returned list before passing it to `+run-start`.
+
+## Command
+```bash
+ae-cli team +list-projects
+ae-cli team +list-projects --format table
+ae-cli team +list-projects --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| None | — | No parameters required |
+
+## Response Shape
+```json
+[
+  { "projectId": 1, "projectName": "项目A" },
+  { "projectId": 2, "projectName": "项目B" }
+]
+```
+
+## Decision Rules
+- When the user wants to start a run and mentions a project by name or says "关联项目", call `+list-projects` first to resolve the correct `projectId`.
+- Once project IDs are confirmed in the current conversation, reuse them without calling `+list-projects` again unless the user switches projects.
+
+## Next Steps on Failure
+- Empty result: the current account may have no associated projects; confirm account permissions with the administrator.
+- Auth error: run `ae-cli auth login`.
+
+## Recommended Chaining
+- `+list-projects` → user confirms `projectId` → `+run-start --project-ids '[<id>]'`