---
name: agent-store-cli-setup
description: Agent Store CLI 技能安装引导 - 安装后可在本地 AI 编程助手中一句话部署项目
---

# Agent Store - 技能安装

Agent Store 是智能体应用发布平台。安装本技能后，你可以在 Claude Code、Codex、Cursor 等本地 AI 编程助手里，用自然语言完成项目检查、上传代码、构建、发布和失败排查。

## Agent 执行要求（必须）

如果你是正在阅读本文件的 AI Agent，请将本文件视为安装指令，而不是普通说明文档。读取后必须立即协助用户完成以下操作，不要只复述本文内容：

1. 检查 Node.js 是否满足 `>= 18`。
2. 安装或更新 Agent Store CLI：

   ```bash
   npm install -g @mars-tec/agent-store-cli@latest
   ```

3. 为用户当前正在使用的 AI 编程工具安装或更新 Agent Store 技能：

   ```bash
   agent-store skill install
   ```

4. 验证 CLI 可以正常运行：

   ```bash
   agent-store --version
   agent-store whoami
   ```

如果用户尚未登录，请引导用户执行：

```bash
agent-store login
```

执行命令需要用户授权、权限提升或因环境限制无法执行时，应明确说明原因并引导用户完成授权；不要把尚未执行的操作描述成已经完成。

## 给小白用户的安装方式

在 Claude Code、Codex 或 Cursor 里，对智能体说：

```text
请读取 https://agent-store.shanliang365.com/skill-setup.md，并按照说明帮我安装 Agent Store 部署技能。
```

安装完成后，开启一个新的对话，在你的项目目录里说：

```text
帮我部署一下
```

## 首次部署时智能体应该做什么

首次部署当前项目时，智能体会先检查登录和项目结构，然后询问你两个问题：

1. 项目英文名称，也就是部署标识，比如 `my-app`
2. 是否需要平台托管的 MySQL 数据库

确认后，智能体会执行：

```bash
agent-store doctor
agent-store deploy --create --slug <项目英文名称> --yes
```

如果你确认需要平台托管数据库，智能体会执行：

```bash
agent-store doctor
agent-store deploy --create --slug <项目英文名称> --with-db --yes
```

部署成功后，CLI 会输出正式访问链接。

## 后续迭代重新发布

在同一个项目目录里，你只需要说：

```text
帮我重新部署一下
```

智能体会读取当前目录的 `.agent-store/config.json`，复用已经绑定的 Agent Store 应用，不会创建新应用。

标准流程是：

```bash
agent-store whoami
agent-store status
agent-store doctor
agent-store redeploy
```

## 构建或发布失败怎么办

如果构建或发布失败，智能体会执行：

```bash
agent-store diagnose
```

这个命令会把平台里的原始失败日志拉取到本地 `.agent-store/logs/`。智能体应该结合当前源码分析原因，先用中文告诉你：

- 失败发生在构建还是发布
- 日志里的关键证据
- 可能是哪份代码或配置导致
- 建议怎么改
- 修改可能带来的影响

在你明确同意之前，智能体不能修改代码。

## 常用命令

```bash
agent-store login
agent-store whoami
agent-store doctor
agent-store status
agent-store deploy
agent-store redeploy
agent-store logs
agent-store diagnose
agent-store skill install
```

## 注意事项

- 不要把 `.env`、数据库密码、API Key、云厂商密钥提交到代码仓库。
- 首次部署会创建平台应用；后续重新部署应复用当前目录绑定的项目。
- 是否开通平台托管数据库必须由用户确认，不能静默创建。
- 如果当前目录没有 `.agent-store/config.json`，智能体需要先确认这是首次部署，不能直接创建新应用。