@tencentcloudadp/cli 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# @tencentcloudadp/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Command-line interface for [Tencent Cloud Agent Development Platform](https://cloud.tencent.com/document/product/1759/132555) (product 1759, API `2026-05-20`).
+
+Package: `@tencentcloudadp/cli`  
+Binary: `adp`
+
+## Install
+
+### Global install via npm
+
+```bash
+npm install -g @tencentcloudadp/cli
+```
+
+Requires Node.js 20+.
+
+### Upgrade
+
+```bash
+adp version --format json   # installed vs. newest release on npm
+adp upgrade --yes           # global install with the detected package manager
+```
+
+### Local install from source
+
+If you are developing locally or installing from source:
+
+```bash
+# Clone the repository
+git clone https://github.com/TencentCloud/adp-cli.git
+cd adp-cli
+
+# Install dependencies, build bundle, and symlink adp globally
+make install-local
+```
+
+This installs dependencies (via pnpm), bundles the CLI and JSON schemas, and symlinks `adp` into your global npm binary path (`$(npm prefix -g)/bin/adp`). To uninstall:
+
+```bash
+make uninstall-local
+```
+
+## Quick start
+
+Get a **CAM** SecretId / SecretKey (starts with `AKID`) from [API Key Management](https://console.cloud.tencent.com/cam/capi). SecretKey is shown only once. This CLI is public cloud only (`adp.tencentcloudapi.com`); independent-site keys are not accepted.
+
+```bash
+export TENCENTCLOUD_SECRET_ID=...
+export TENCENTCLOUD_SECRET_KEY=...
+adp login
+adp whoami --format json
+adp init --name demo --space-id <space> --model-id <model> --create-remote
+adp deploy --dry-run
+adp deploy
+```
+
+Knowledge-base documents (same CAM keys; default KB id = `app_id`):
+
+```bash
+adp kb doc import --file ./faq.md
+adp kb doc list --format json
+```
+
+Do not pass secrets as CLI flags. On a TTY, `adp login` prints the CAM URLs and can prompt instead of env vars.
+
+After install, put the companion skill on the coding agent:
+
+```bash
+adp skills install --yes
+```
+
+Look up official ADP docs without guessing numeric slugs:
+
+```bash
+adp docs search ModifyApp --format json
+adp docs get 132502 --format json
+adp docs config --format json
+```
+
+## Output contract
+
+`adp` serves humans and agents with one binary.
+
+| stdout is a TTY | `--format` | Result |
+| --- | --- | --- |
+| yes | `auto` (default) | tables on stdout, progress on stderr |
+| no (pipe / `CI=1`) | `auto` | JSON envelope on stdout |
+| any | `json` / `--json` | JSON envelope |
+| any | `text` | tables even when piped |
+
+Failures print a JSON envelope as the last line of stderr. Exit codes: `0` ok, `2` usage, `3` not found, `4` auth, `5` conflict, `1` other.
+
+Discover commands without auth:
+
+```bash
+adp --version
+adp schema --format json
+```
+
+`adp schema` includes `global_flags`. In a pipe (or with `--format json`, or under a detected coding agent), `adp` with no subcommand also prints that schema. On a TTY it prints `--help`. Either way a bare `adp` never takes over the terminal.
+
+## Global flags
+
+`--config` `--cwd` `--env` `--region` `--format` `--yes` `--quiet` `--limit` `--fields` `--dry-run`
+
+`--json` is an alias for `--format json`. Resource IDs prefer named flags (`--app-id`) over positionals.
+
+## Make targets
+
+`make check` is the same gate CI runs: install, format, architecture-check, sdk-baseline-check, secrets-check, knip, typecheck, test, build.
+
+`make install-local` builds and installs `adp` onto this machine. `make uninstall-local` removes it.
+
+## Docs
+
+- **[User Documentation](docs/user/README.md)**: Full user guide (quickstart, authentication, configuration, app modes, workflows, knowledge base, commands, debugging, and troubleshooting).
+- **[Architecture & Developer Docs](docs/README.md)**: Internal architecture, DDD layers, design decisions, and contribution guide.
+- **[CLAUDE.md](CLAUDE.md)**: Instructions and constraints for AI coding agents.

package/bin/adp.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+
+await import(fileURLToPath(new URL("../dist/cli.js", import.meta.url)));

package/config-schema.json

@@ -0,0 +1,319 @@
+{
+  "$ref": "#/definitions/AdpConfig",
+  "definitions": {
+    "AdpConfig": {
+      "type": "object",
+      "properties": {
+        "$schema": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "app_mode": {
+          "type": "number",
+          "enum": [
+            1,
+            2,
+            3,
+            4
+          ],
+          "default": 2
+        },
+        "region": {
+          "type": "string",
+          "minLength": 1,
+          "default": "ap-guangzhou"
+        },
+        "space_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "app_id": {
+          "type": "string"
+        },
+        "agent_id": {
+          "type": "string"
+        },
+        "avatar": {
+          "type": "string"
+        },
+        "greeting": {
+          "type": "object",
+          "properties": {
+            "greeting": {
+              "type": "string",
+              "minLength": 1
+            },
+            "opening_question_list": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "required": [
+            "greeting"
+          ],
+          "additionalProperties": false
+        },
+        "role_description": {
+          "type": "string"
+        },
+        "memory": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean"
+            },
+            "long_memory_day": {
+              "type": "integer"
+            },
+            "prompt_content": {
+              "type": "string"
+            },
+            "prompt_mode": {
+              "type": "integer"
+            }
+          },
+          "required": [
+            "enabled"
+          ],
+          "additionalProperties": false
+        },
+        "web_search": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean"
+            },
+            "provider": {
+              "type": "string"
+            },
+            "top_n": {
+              "type": "integer"
+            },
+            "api_key": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "enabled"
+          ],
+          "additionalProperties": false
+        },
+        "mode": {
+          "type": "object",
+          "properties": {
+            "multi_agent": {
+              "type": "object",
+              "properties": {
+                "collaboration_mode": {
+                  "type": "integer"
+                },
+                "workflow_id": {
+                  "type": "string"
+                },
+                "workflow_name": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "collaboration_mode"
+              ],
+              "additionalProperties": false
+            },
+            "single_workflow": {
+              "type": "object",
+              "properties": {
+                "workflow_id": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "workflow_name": {
+                  "type": "string"
+                },
+                "async_workflow": {
+                  "type": "boolean"
+                },
+                "enabled": {
+                  "type": "boolean"
+                },
+                "workflow_description": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "workflow_id"
+              ],
+              "additionalProperties": false
+            },
+            "claw": {
+              "type": "object",
+              "properties": {
+                "team_enabled": {
+                  "type": "boolean"
+                },
+                "team_prompt": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        },
+        "shared_kb_ids": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "agent": {
+          "type": "object",
+          "properties": {
+            "profile": {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "description": {
+                  "type": "string"
+                },
+                "icon_url": {
+                  "type": "string"
+                },
+                "role": {
+                  "type": "integer"
+                }
+              },
+              "required": [
+                "name"
+              ],
+              "additionalProperties": false
+            },
+            "instructions": {
+              "type": "string"
+            },
+            "instructions_file": {
+              "type": "string"
+            },
+            "model": {
+              "type": "object",
+              "properties": {
+                "model_id": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "alias": {
+                  "type": "string"
+                },
+                "context_words_limit": {
+                  "type": "number"
+                },
+                "instructions_words_limit": {
+                  "type": "number"
+                }
+              },
+              "required": [
+                "model_id"
+              ],
+              "additionalProperties": false
+            },
+            "skill_ids": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "plugin_ids": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "connector_ids": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "tools": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "plugin_id": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "tool_id": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "tool_source": {
+                    "type": "integer"
+                  },
+                  "description": {
+                    "type": "string"
+                  },
+                  "is_disabled": {
+                    "type": "boolean"
+                  }
+                },
+                "required": [
+                  "plugin_id",
+                  "tool_id"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "plugins": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "plugin_id": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "auth_type": {
+                    "type": "integer"
+                  },
+                  "enable_cam_role_auth": {
+                    "type": "boolean"
+                  },
+                  "oauth_consent": {
+                    "type": "integer"
+                  }
+                },
+                "required": [
+                  "plugin_id"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "max_reasoning_round": {
+              "type": "number"
+            }
+          },
+          "required": [
+            "profile",
+            "model"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "name",
+        "space_id",
+        "agent"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}