superun-ai-cli 0.1.0

package/INSTALL.md

@@ -0,0 +1,118 @@
+# superun-ai-cli 安装与配置指南
+
+[English README](README.en.md) | [中文 README](README.md)
+
+本指南供 AI Agent 协助用户安装和配置 CLI。请使用用户的语言说明进度，只完成安装、登录和只读验证，不自动创建、修改或发布项目。
+
+- npm 包名：`superun-ai-cli`。
+- 命令名：`superun-ai`。
+- 官方仓库：<https://github.com/AiGuangInc/superun-ai-cli>。
+- 默认服务：<https://superun.com>。不要擅自指定其他服务地址。
+
+## 1. 检查环境
+
+```bash
+node --version
+npm --version
+```
+
+需要 Node.js 22 或更新版本和 npm。缺少依赖或版本不满足时，说明问题并征得用户同意后再安装或升级；不要擅自更换用户的 Node.js 管理方式、修改全局配置或使用 `sudo`。
+
+如果 `superun-ai` 已存在，先检查其路径及 `superun-ai version`，区分 npm 安装和源码目录链接。保留现有凭据及用户未提交的代码，不卸载或覆盖其他工具。
+
+## 2. 确认可用的安装方式
+
+当前仓库尚未正式发布到 npm。执行安装时应重新查询，避免依赖过时的发布状态：
+
+```bash
+npm view superun-ai-cli name version repository.url dist.tarball --registry=https://registry.npmjs.org --json
+```
+
+- 查询成功：核对包名和官方仓库归属后，使用 npm 安装。若包归属无法确认，先停止并说明，不安装同名的未知来源包。
+- 明确返回该包的 `E404`：说明 npm 安装尚不可用。有官方仓库访问权限时，从源码安装；没有权限时，请用户提供可访问的官方源码或等待发布。
+- 网络、证书、认证或其他错误：保留真实错误并先排查，不把它们当成“包未发布”，也不要反复重试安装。
+
+### 已发布：从 npm 安装
+
+```bash
+npm install -g superun-ai-cli --registry=https://registry.npmjs.org
+```
+
+### 未发布：从源码安装
+
+需要 Git 和仓库访问权限。先确认安装目录；若已有本仓库，复用该目录并检查 `git status` 和 remote，不覆盖未提交改动、不强制切换分支。
+
+新目录安装示例：
+
+```bash
+git clone https://github.com/AiGuangInc/superun-ai-cli.git
+cd superun-ai-cli
+npm ci
+npm run build
+npm install -g .
+```
+
+逐条执行，失败即停。仓库访问失败时，说明需要的访问权限，不索取 GitHub 凭据明文。不要修改 `private`、包名或版本号，不执行 `npm publish`，也不要绕过发行版的版本校验。
+
+源码安装可能把全局命令链接到当前目录，因此应保留源码目录。以后更新源码时，先确认工作区干净再同步代码、安装匹配依赖并重新构建；全局命令若不是源码链接，再执行 `npm install -g .`。不要用 `superun-ai update` 获取尚未发布的版本。
+
+## 3. 单独验证命令安装
+
+安装完成后再运行帮助和版本命令：
+
+```bash
+superun-ai --help
+superun-ai version
+```
+
+确认命令可以启动。若提示找不到命令，检查当前终端的 `PATH`、所用 Node.js 安装及 npm 全局目录；不要把它误判为业务登录失败。不要通过全量打印环境变量来排查，避免泄露凭据。
+
+## 4. 引导用户登录
+
+先查询本地配置状态：
+
+```bash
+superun-ai auth status
+```
+
+- 返回 `CONFIGURED`：复用已有 PAT，不先执行 `auth logout`，也不要求用户重复登录。
+- 明确提示未配置 PAT：执行下面的登录命令，让用户本人在浏览器完成登录。
+- 提示凭据文件异常、版本检查失败或其他错误：说明错误，等待用户决定如何处理，不删除凭据或无限循环登录。
+
+```bash
+superun-ai auth login
+```
+
+CLI 会打开 Superun 登录页面，完成后领取 PAT 并保存到本地。浏览器未自动打开时，把 CLI 打印的登录地址提供给用户。保持登录命令运行，等它返回成功；不要另起重复登录流程。等待期间告诉用户需要完成网页登录，超时或取消时如实说明。
+
+如果用户明确要导入已有 PAT，请让用户在自己的交互式终端执行：
+
+```bash
+superun-ai auth login --pat
+```
+
+`--pat` 后不能跟凭据值，由终端隐藏读取。不要让用户把 PAT 发到聊天里，也不要读取或展示凭据文件内容。已安全设置 `SUPERUN_PAT` 的自动化环境可直接复用；需要持久化时可通过 `auth login --stdin` 输入，但不得回显或记录秘密。
+
+## 5. 只读验证线上访问
+
+登录完成后执行：
+
+```bash
+superun-ai session list --limit 1
+```
+
+返回 `ok: true`、`state: COMPLETED` 表示查询成功；空列表也是正常结果，不要为了验证自动创建项目。`auth status` 只证明本地有配置，不能替代本次实际访问校验。
+
+如果返回鉴权错误，先说明现有 PAT 或权限校验未通过，由用户决定是否重新登录；不要自动清除 PAT、切换账号或更换服务地址。其他网络或业务错误也应如实反馈。
+
+## 6. 向用户交付结果
+
+简要告知安装来源、实际版本、命令是否可用、登录与只读验证结果，并给出下一步入口：
+
+```bash
+superun-ai --help
+```
+
+只在用户随后提出创作需求时才调用 `chat create`。安装配置本身不代表用户授权创建项目、启用插件、发布应用、改变站点可见性或发 npm 包。
+
+<!-- @author xiuyu.yi -->

package/README.en.md

@@ -0,0 +1,257 @@
+# superun-ai-cli
+
+[English](README.en.md) | [中文](README.md)
+
+superun-ai-cli is a command-line tool for project management, conversational creation, interactive questions, plugins, and application publishing. People and automation use the same commands; business results are returned as JSON.
+
+## Installation
+
+Requires Node.js 22 or newer and npm.
+
+> The package has not yet been officially published to npm. Users with repository access can install from source now; registry installation will be available after publication.
+
+### 🤖 Install and configure with an AI agent (recommended)
+
+Send the following prompt to Claude Code, Codex, or another AI coding agent. The agent will follow the [installation guide](INSTALL.md) to check your environment, install the CLI, and guide you through login and verification:
+
+```text
+Read https://raw.githubusercontent.com/AiGuangInc/superun-ai-cli/refs/heads/main/INSTALL.md and help me install and configure superun-ai-cli. Check which installation method is available first. Let me complete login in my browser; do not request or display my PAT in plain text.
+```
+
+If the agent already has this repository open, ask it to read `INSTALL.md` in the repository root.
+
+### Manual installation
+
+Source installation currently requires Git and repository access. Run these commands in the directory where you want to keep the source:
+
+```bash
+git clone https://github.com/AiGuangInc/superun-ai-cli.git
+cd superun-ai-cli
+npm ci
+npm run build
+npm install -g .
+```
+
+If you already have a local checkout, use that directory and preserve any uncommitted changes.
+
+After the package is published to npm, install it directly without cloning or compiling the source:
+
+```bash
+npm install -g superun-ai-cli
+```
+
+`-g` installs the package globally. Once the global command directory is on your `PATH`, you can run `superun-ai` from any directory.
+
+The package name is `superun-ai-cli`; the shell command is `superun-ai`.
+
+## Help
+
+After installation, run help separately. These commands do not start login or create a project:
+
+```bash
+superun-ai --help
+superun-ai chat --help
+superun-ai chat style generate --help
+```
+
+## Command tree
+
+The tree below lists command groups, positional arguments, and their purpose. Replace required arguments written as `<...>` with actual values. Use each command's `--help` to see its options and requirements.
+
+```text
+superun-ai
+├── auth                                         # Manage PAT login
+│   ├── login                                    # Sign in and save a PAT
+│   ├── status                                   # Check local PAT configuration
+│   └── logout                                   # Remove the locally saved PAT
+├── session                                      # Query projects
+│   ├── list                                     # List projects
+│   └── get <sessionId>                          # Get project details
+├── chat                                         # Conversational creation
+│   ├── create                                   # Create a project and send a request
+│   ├── send <sessionId>                         # Continue the conversation
+│   ├── state <sessionId>                        # Inspect the task and interactions
+│   ├── wait <sessionId>                         # Wait for input or a task result
+│   ├── stop <sessionId>                         # Stop the remote task
+│   ├── style                                    # Manage creative styles
+│   │   ├── generate <sessionId>                 # Generate style candidates
+│   │   ├── list <sessionId>                     # List style batches
+│   │   └── select <sessionId> <choiceId>        # Choose a completed style
+│   ├── demo <sessionId>                         # View the demo and record it as viewed
+│   ├── develop <sessionId>                      # Keep the demo and plan development
+│   ├── interaction                              # Answer or skip interactions
+│   │   ├── reply <sessionId> <interactionId>    # Submit an answer
+│   │   └── skip <sessionId> <interactionId>     # Skip an eligible interaction
+│   ├── plugin                                   # Query, enable, and disable plugins
+│   │   ├── list <sessionId>                     # List available plugins
+│   │   ├── status <sessionId> <pluginId>        # Inspect a plugin
+│   │   ├── enable <sessionId> <pluginId>        # Enable a plugin
+│   │   └── disable <sessionId> <pluginId>       # Disable a plugin
+│   └── publish                                  # Publish applications and manage visibility
+│       ├── status <sessionId>                   # Query versions and deployment progress
+│       ├── start <sessionId> <encryptedId>      # Publish a specific version
+│       └── visibility <sessionId> <visibility>  # Make the site public or private
+├── update                                       # Check and install the required version
+└── version                                      # Show local and output-schema versions
+```
+
+## PAT login
+
+```bash
+superun-ai auth login
+superun-ai auth status
+superun-ai auth logout
+```
+
+`auth login` reuses an existing PAT. If none is configured, it opens the Superun website so you can sign in and obtain a PAT, then saves it locally without requiring you to copy it. When you first run a business command in an interactive terminal without a PAT, the CLI uses the same login flow and then resumes the original command.
+
+Browser login waits for up to five minutes. Press Ctrl+C to cancel. If the browser does not open automatically, use the URL printed in the terminal. The website login token is only used to obtain a PAT and is not stored locally.
+
+To import an existing PAT manually:
+
+```bash
+superun-ai auth login --pat
+```
+
+`--pat` reads hidden input from the terminal, even if `SUPERUN_PAT` is already set. It is an input-mode switch: do not put the PAT after it, and do not combine it with `--stdin`.
+
+Automated business commands without a PAT fail instead of opening a browser. Set `SUPERUN_PAT` or log in using standard input:
+
+```bash
+printf '%s\n' "$SUPERUN_PAT" | superun-ai auth login --stdin
+```
+
+The CLI prefers `SUPERUN_PAT`, then `~/.config/superun-ai-cli/credentials.json`. The file uses `0600` permissions. Logging out removes the local credential without revoking the server-side PAT. Never put a PAT in command-line arguments, source control, or logs.
+
+`auth status` only checks local credential configuration. It does not open a browser or request a PAT. `CONFIGURED` means a credential is configured locally; its validity and project permissions are checked by actual business requests. An expired or disabled PAT, or a damaged credential file, results in an error rather than an automatic login or overwrite.
+
+`auth logout` deletes the saved PAT. If `SUPERUN_PAT` is set, it remains effective until you remove it from your shell:
+
+```bash
+unset SUPERUN_PAT
+```
+
+Help, `version`, `update`, and `auth logout` do not require an existing PAT. With `SUPERUN_PAT` set, you can call business commands without first running login again.
+
+## Common commands
+
+```bash
+superun-ai session list --limit 20
+superun-ai session get <sessionId>
+superun-ai chat create --message "Build a promotional website for a coffee shop"
+superun-ai chat send <sessionId> --message "Add a membership benefits section"
+superun-ai chat state <sessionId>
+superun-ai chat wait <sessionId> --timeout 120
+superun-ai chat stop <sessionId>
+```
+
+Write commands support `--no-wait`, returning as soon as the request is accepted. `chat wait` waits for input, a selection, or task completion. When an explicit local waiting limit is reached, it returns the current state with `waitTimedOut: true`; you can continue querying. Ctrl+C only ends local waiting. Use `chat stop` explicitly to stop a remote task.
+
+The CLI connects to Superun by default. Use the global `--endpoint <URL>` option to specify an API endpoint and `--locale <language>` to choose the response language.
+
+## Answering interactions
+
+When the CLI returns `NEEDS_INPUT`, read the questions, allowed `actions`, and `answerSchema` in `interactions`. Always reply using the `interactionId` from that result.
+
+```json
+{
+  "action": "SUBMIT",
+  "answers": [
+    { "questionId": "q0", "selectedIndices": [0], "otherValue": "" }
+  ]
+}
+```
+
+```bash
+superun-ai chat interaction reply <sessionId> <interactionId> --input ./answer.json
+superun-ai chat interaction skip <sessionId> <interactionId>
+```
+
+Selection indices start at `0`. Skip only when the interaction allows `SKIP`. Completing the requirements questionnaire starts style generation directly; omit `action` or use `GENERATE_STYLES`. The `SUBMIT` example above applies to ordinary questions. Stage transitions, database approvals, and other interactions use their own returned actions.
+
+For secret input, submit `{"values":{"requested-key":"secret-value"}}` with only the requested keys. Values are not echoed. Stale or ambiguous interactions are rejected; query the current state again.
+
+`chat interaction reply --no-wait` controls waiting for subsequent creation after the reply has been processed. Some plugin configuration steps must finish in the foreground before submitting their interaction result; this option does not skip those steps. After an interruption, check the plugin and conversation states first.
+
+## Styles, plugins, and publishing
+
+Interactions, styles, plugins, and publishing belong under `chat`. Use `chat interaction`, `chat style`, `chat plugin`, and `chat publish`; they are not top-level commands.
+
+```bash
+superun-ai chat style generate <sessionId> --content "Create a clean brand style" --count 2
+superun-ai chat style list <sessionId>
+superun-ai chat style select <sessionId> <choiceId>
+
+superun-ai chat plugin list <sessionId>
+superun-ai chat plugin status <sessionId> <pluginId>
+superun-ai chat plugin enable <sessionId> <pluginId>
+superun-ai chat plugin disable <sessionId> <pluginId>
+
+superun-ai chat publish status <sessionId>
+superun-ai chat publish start <sessionId> <encryptedId>
+superun-ai chat publish visibility <sessionId> public
+superun-ai chat publish visibility <sessionId> private
+```
+
+Style generation defaults to two candidates and supports one to four. Use the returned `choiceId` to select a style. Publishing uses the returned `encryptedId` and tracks the selected version's deployment. Plugin IDs come from `chat plugin list`.
+
+After the user explicitly asks to launch the site, use `chat publish status <sessionId> --for-launch` to get the latest pending version from the publishing panel. Show its `changeLog` unchanged, then follow the returned publishing command without a second confirmation. For a deployment already in progress, only track progress. If deployment is complete but the site is not public, finish the visibility step and return the public URL. `status` is always read-only; an ordinary status query does not grant publishing authorization.
+
+`chat publish start --indexing allow|deny` controls search-engine indexing, not visitor access. Change site visibility with `chat publish visibility`. If the service requires acknowledgment of cloud costs, review them before explicitly passing `--acknowledge-cloud-fee`.
+
+## Attachments
+
+`chat create/send` accepts repeated `--file <path>` options. Small text files may be included directly in the message; other files are uploaded and approved before the message is sent. The per-file limit is 20 MB.
+
+`session get --include-attachments` returns visible attachments. `chat state --include-file <name>` reads a named visible file. System files and secret configuration are not returned as result attachments.
+
+## Output and errors
+
+Business commands write one JSON result to stdout. Diagnostics and update progress go to stderr.
+
+```json
+{
+  "schemaVersion": "1",
+  "ok": true,
+  "data": {
+    "state": "RUNNING",
+    "sessionId": "session_id",
+    "messages": [],
+    "progress": [],
+    "interactions": []
+  }
+}
+```
+
+| Exit code | Meaning |
+|---|---|
+| 0 | Query succeeded, request accepted, running, input needed, or completed |
+| 2 | Invalid arguments or input |
+| 3 | Missing or invalid PAT, or access denied |
+| 4 | Version check or update failed |
+| 5 | Business failure, stale or ambiguous interaction, or uncertain write outcome |
+| 6 | Interaction unsupported by this CLI version |
+| 7 | Timeout for an attachment or auxiliary operation |
+| 8 | Network or response-protocol error |
+| 130 | Local command interrupted |
+
+`OUTCOME_UNKNOWN` means a request may have been accepted. Do not immediately retry the write. Query the returned session ID first. If a create request did not return a session ID, check the project list before deciding what to do next.
+
+## Updates
+
+Published releases check the required version before business commands and install it when needed, then resume the command. If an update or verification fails, the CLI stops; resolve the reported issue before retrying. Help, `version`, and `auth logout` work offline.
+
+For the current source installation, rebuild in the source directory. If the global command is not linked to that checkout, run `npm install -g .` again. Do not use `superun-ai update` to retrieve an unpublished version.
+
+```bash
+superun-ai version
+superun-ai update
+```
+
+## Uninstalling
+
+```bash
+npm uninstall -g superun-ai-cli
+```
+
+<!-- @author xiuyu.yi -->

package/README.md

@@ -0,0 +1,255 @@
+# superun-ai-cli
+
+[English](README.en.md) | [中文](README.md)
+
+superun-ai-cli 命令行工具，支持项目管理、对话创作、交互问答、插件管理和应用发布。人和自动化程序使用同一组命令；业务结果以 JSON 输出。
+
+## 安装
+
+需要 Node.js 22 或更新版本，以及 npm。
+
+> 当前版本尚未在 npm 正式发布。有仓库访问权限的用户可以先从源码安装；npm 安装方式在正式发布后可用。
+
+### 🤖 通过 AI Agent 安装配置（推荐）
+
+把下面这段话发给 Claude Code、Codex 或其他 AI 编码 Agent，它会根据[安装指南](INSTALL.md)检查环境、安装 CLI，并引导你完成登录与验证：
+
+```text
+请阅读 https://raw.githubusercontent.com/AiGuangInc/superun-ai-cli/refs/heads/main/INSTALL.md，帮我安装并配置 superun-ai-cli。请先确认可用的安装方式，登录时让我在浏览器完成操作，不要索取或展示 PAT 明文。
+```
+
+如果 Agent 已经打开本仓库，也可以直接让它阅读根目录的 `INSTALL.md`。
+
+### 手动安装
+
+当前从源码安装需要 Git 和仓库访问权限。在准备存放代码的目录执行：
+
+```bash
+git clone https://github.com/AiGuangInc/superun-ai-cli.git
+cd superun-ai-cli
+npm ci
+npm run build
+npm install -g .
+```
+
+如果本地已有仓库，请使用已有目录，不要覆盖未提交的改动。
+
+正式发布到 npm 后，可直接安装，无需源码和自行编译：
+
+```bash
+npm install -g superun-ai-cli
+```
+
+`-g` 表示全局安装。全局命令目录在 `PATH` 中时，可以在任意目录使用 `superun-ai`。
+
+安装包名为 `superun-ai-cli`，使用时的命令名为 `superun-ai`。
+
+## 查看帮助
+
+安装完成后，单独执行以下命令查看帮助；这些命令不会发起登录或创作：
+
+```bash
+superun-ai --help
+superun-ai chat --help
+superun-ai chat style generate --help
+```
+
+## 命令树
+
+下面列出完整命令层级、位置参数和用途。`<...>` 表示需要替换的必填位置参数；选项参数及其要求可通过各命令的 `--help` 查看。
+
+```text
+superun-ai
+├── auth                                         # 管理 PAT 登录
+│   ├── login                                    # 登录 Superun 并保存 PAT
+│   ├── status                                   # 查看本地 PAT 配置状态
+│   └── logout                                   # 清除本地 PAT
+├── session                                      # 查询项目
+│   ├── list                                     # 查询项目列表
+│   └── get <sessionId>                          # 查询项目详情
+├── chat                                         # 对话创作
+│   ├── create                                   # 新建项目并发送需求
+│   ├── send <sessionId>                         # 继续项目创作
+│   ├── state <sessionId>                        # 查询当前任务和交互
+│   ├── wait <sessionId>                         # 等待当前交互或任务结果
+│   ├── stop <sessionId>                         # 停止远端任务
+│   ├── style                                    # 管理创作风格
+│   │   ├── generate <sessionId>                 # 生成风格候选
+│   │   ├── list <sessionId>                     # 查询全部风格批次
+│   │   └── select <sessionId> <choiceId>        # 选择已完成的风格
+│   ├── demo <sessionId>                         # 查看演示快照并记录已查看状态
+│   ├── develop <sessionId>                      # 保留演示，进入研发并生成规划
+│   ├── interaction                              # 回答或跳过交互
+│   │   ├── reply <sessionId> <interactionId>    # 提交回答
+│   │   └── skip <sessionId> <interactionId>     # 跳过当前交互
+│   ├── plugin                                   # 查询、启用和禁用插件
+│   │   ├── list <sessionId>                     # 查询可用插件
+│   │   ├── status <sessionId> <pluginId>        # 查询插件状态
+│   │   ├── enable <sessionId> <pluginId>        # 启用插件
+│   │   └── disable <sessionId> <pluginId>       # 禁用插件
+│   └── publish                                  # 发布应用和管理站点状态
+│       ├── status <sessionId>                   # 查询发布版本与部署进度
+│       ├── start <sessionId> <encryptedId>      # 发布指定版本
+│       └── visibility <sessionId> <visibility>  # 设置站点上线或下线状态
+├── update                                       # 检查并安装指定版本
+└── version                                      # 显示本地版本与输出协议版本
+```
+
+## PAT 登录
+
+```bash
+superun-ai auth login
+superun-ai auth status
+superun-ai auth logout
+```
+
+已有 PAT 时，`auth login` 直接复用；没有时自动打开 Superun 网页，完成登录后领取 PAT 并保存到本地，无需手动复制。首次在交互终端执行业务命令时，如果没有 PAT，也会自动进入同一登录流程，完成后继续执行原命令。
+
+网页登录最多等待 5 分钟，按 Ctrl+C 可取消。浏览器未自动打开时，可以手动打开终端提示的地址。网页登录 Token 只用于申请 PAT，不会保存到本地。
+
+如果已经有 PAT，也可以手动导入：
+
+```bash
+superun-ai auth login --pat
+```
+
+`--pat` 会在终端隐藏读取输入，即使已设置 `SUPERUN_PAT` 也会要求重新输入。它是输入方式开关，后面不能直接跟 PAT 明文，并且不能与 `--stdin` 同时使用。
+
+自动化脚本中缺少 PAT 时会报错，不会自动打开浏览器。可以设置 `SUPERUN_PAT`，也可以通过标准输入登录：
+
+```bash
+printf '%s\n' "$SUPERUN_PAT" | superun-ai auth login --stdin
+```
+
+凭据优先级为 `SUPERUN_PAT` 环境变量，其次是 `~/.config/superun-ai-cli/credentials.json`。文件权限为 `0600`；退出登录只清除本地保存的凭据，不撤销服务端 PAT。请勿将 PAT 写进命令行参数、仓库或日志。
+
+`auth status` 只查看本地凭据配置，不会打开浏览器或申请 PAT。返回 `CONFIGURED` 表示本地已配置凭据；已有 PAT 是否有效、是否有权访问项目，会在实际业务请求时校验。PAT 过期、禁用或本地文件损坏时会报错，不会自动重新登录或覆盖凭据。
+
+`auth logout` 会删除本地保存的 PAT，下次使用时重新登录。若设置了 `SUPERUN_PAT`，环境变量仍然有效，需要在终端手动清除：
+
+```bash
+unset SUPERUN_PAT
+```
+
+帮助、`version`、`update` 和清除本地凭据的 `auth logout` 不要求已有 PAT。提供 `SUPERUN_PAT` 即可直接调用业务命令，无需重复执行登录命令。
+
+## 常用命令
+
+```bash
+superun-ai session list --limit 20
+superun-ai session get <sessionId>
+superun-ai chat create --message "为咖啡店制作一个活动网站"
+superun-ai chat send <sessionId> --message "增加会员权益介绍"
+superun-ai chat state <sessionId>
+superun-ai chat wait <sessionId> --timeout 120
+superun-ai chat stop <sessionId>
+```
+
+写命令支持 `--no-wait`：请求被接受后立即返回。`chat wait` 等待到需要输入、需要选择或任务结束；达到本地等待时限后返回当前状态和 `waitTimedOut: true`，可以继续查询。按 Ctrl+C 只结束本地等待；远端停止需要显式执行 `chat stop`。
+
+默认连接 Superun 服务。全局参数 `--endpoint <URL>` 可指定 API 地址，`--locale <language>` 可指定响应语言。
+
+## 回答交互
+
+当返回 `NEEDS_INPUT` 时，读取 `interactions` 中的问题、允许的 `actions` 和 `answerSchema`。每次回复都使用该结果中的 `interactionId`。
+
+```json
+{
+  "action": "SUBMIT",
+  "answers": [
+    { "questionId": "q0", "selectedIndices": [0], "otherValue": "" }
+  ]
+}
+```
+
+```bash
+superun-ai chat interaction reply <sessionId> <interactionId> --input ./answer.json
+superun-ai chat interaction skip <sessionId> <interactionId>
+```
+
+选择下标从 `0` 开始。只有交互声明支持 `SKIP` 时才可跳过。需求问卷答齐后直接生成风格，`action` 可省略或填写 `GENERATE_STYLES`；上面的 `SUBMIT` 示例适用于普通问答。阶段交接、数据库变更确认等交互应使用各自返回的动作。
+
+密钥输入使用 `{"values":{"请求的键名":"密钥值"}}`，只提交当前交互要求的键；内容不会回显。过期或存在歧义的交互会被拒绝，请重新查询状态。
+
+`chat interaction reply --no-wait` 控制回答处理完成后的创作等待。部分插件配置需要在前台等待配置结束并提交交互结果，这一步不会因该选项被省略；中断后应先查询插件与会话状态。
+
+## 风格、插件和发布
+
+交互、风格、插件和发布均归属对话创作，统一使用 `chat interaction`、`chat style`、`chat plugin` 和 `chat publish`，不提供对应顶层入口。
+
+```bash
+superun-ai chat style generate <sessionId> --content "生成简洁的品牌风格" --count 2
+superun-ai chat style list <sessionId>
+superun-ai chat style select <sessionId> <choiceId>
+
+superun-ai chat plugin list <sessionId>
+superun-ai chat plugin status <sessionId> <pluginId>
+superun-ai chat plugin enable <sessionId> <pluginId>
+superun-ai chat plugin disable <sessionId> <pluginId>
+
+superun-ai chat publish status <sessionId>
+superun-ai chat publish start <sessionId> <encryptedId>
+superun-ai chat publish visibility <sessionId> public
+superun-ai chat publish visibility <sessionId> private
+```
+
+风格默认生成 2 个，支持 1～4 个；使用查询结果中的 `choiceId`。发布使用查询结果中的 `encryptedId`，按目标版本跟踪部署状态。插件 ID 以 `chat plugin list` 返回值为准。
+
+用户明确回复“上线运营”后，使用 `chat publish status <sessionId> --for-launch` 获取 Glow 发布面板的最新待发布版本，原样展示该版本的 `changeLog`，再按返回的命令直接发布，无需二次确认。发布中的版本只跟踪进度；部署后尚未公开的站点继续执行上线动作，完成后返回正式链接。`status` 始终只读，普通状态查询不会自动获得发布授权。
+
+`chat publish start --indexing allow|deny` 控制搜索引擎索引，不限制用户访问；站点上下线使用 `chat publish visibility`。若服务端要求确认云服务费用，了解费用后可显式传入 `--acknowledge-cloud-fee`。
+
+## 附件
+
+`chat create/send` 支持重复传入 `--file <path>`。小型文本文件可以直接作为内容输入，其余文件上传并完成审核后才发送消息。单文件上限 20MB。
+
+`session get --include-attachments` 返回可见附件清单；`chat state --include-file <name>` 读取指定可见附件正文。系统文件和密钥配置文件不会作为结果附件返回。
+
+## 输出与错误
+
+业务命令在 stdout 输出一条 JSON，诊断和更新进度写入 stderr。
+
+```json
+{
+  "schemaVersion": "1",
+  "ok": true,
+  "data": {
+    "state": "RUNNING",
+    "sessionId": "session_id",
+    "messages": [],
+    "progress": [],
+    "interactions": []
+  }
+}
+```
+
+| 退出码 | 含义 |
+|---|---|
+| 0 | 查询成功、请求已接受、仍在运行、需要输入或任务完成 |
+| 2 | 参数或输入格式错误 |
+| 3 | PAT 缺失、无效或访问被拒绝 |
+| 4 | 版本检查或更新失败 |
+| 5 | 业务失败、交互过期/歧义或写请求结果不确定 |
+| 6 | 当前版本不支持所需交互 |
+| 7 | 附件等辅助操作等待超时 |
+| 8 | 网络或响应协议错误 |
+| 130 | 本地命令被中断 |
+
+`OUTCOME_UNKNOWN` 表示请求可能已被接受，不能直接重试写操作。先使用返回的会话 ID 查询状态；创建请求若未取得会话 ID，应查询项目列表确认。
+
+## 更新
+
+正式发行版会在执行业务命令前检查版本，需要更新时自动安装指定版本后继续执行。更新或校验失败时会停止执行，请根据错误提示处理后重试。帮助、`version` 和 `auth logout` 可离线使用。
+
+当前从源码安装的版本，请在源码目录重新构建；如果全局命令不是链接到该目录，再执行 `npm install -g .`。不要使用 `superun-ai update` 获取尚未发布的版本。
+
+```bash
+superun-ai version
+superun-ai update
+```
+
+## 卸载
+
+```bash
+npm uninstall -g superun-ai-cli
+```

package/dist/api/agent-command-api.d.ts

@@ -0,0 +1,39 @@
+/** 对话创建、工具回复和项目内容更新。@author xiuyu.yi */
+import type { ApiClient } from '../transport/api-client.js';
+import type { JsonObject } from '../contracts/value.js';
+export type ChatInput = {
+    sessionId?: string;
+    content: string;
+    model?: string;
+    minDuration?: number;
+    previewVersionId?: number;
+    workspaceId?: string;
+    mode?: number;
+    framework?: number;
+    sessionExtra?: Record<string, string>;
+    roundExtra?: Record<string, string>;
+    businessParams?: JsonObject;
+    preReplyMessageId?: string;
+    parallelSelectRequest?: JsonObject;
+    excludedInheritedRoundExtraKeys?: Array<string>;
+    attachments?: Array<JsonObject>;
+};
+export declare class AgentCommandApi {
+    private readonly client;
+    constructor(client: ApiClient);
+    chat(input: ChatInput): Promise<JsonObject>;
+    parallel(input: JsonObject): Promise<JsonObject>;
+    viewDemo(sessionId: string): Promise<JsonObject>;
+    stop(sessionId: string, scope: 'own' | 'all', messageId?: string): Promise<void>;
+    reply(sessionId: string, toolId: string, toolResult?: unknown): Promise<JsonObject>;
+    replySingle(input: JsonObject): Promise<JsonObject>;
+    messageExtra(sessionId: string, messageId: string, extra: JsonObject): Promise<void>;
+    saveAttachment(sessionId: string, name: string, content: unknown, replyMessageId?: string): Promise<void>;
+    contentExtra(input: {
+        sessionId: string;
+        messageId: string;
+        contentId: string;
+        extra: JsonObject;
+    }): Promise<void>;
+    sessionExtra(sessionId: string, extra: Record<string, string>): Promise<void>;
+}