# 安全与权限

> Shoplazza AI Toolkit 如何管住智能体的写操作：预览—复述—确认的安全协议、业务域与 OAuth 作用域，以及只读授权的用法。

当 AI 智能体代你操作 CLI 时，每条命令都有真实后果——建商品、给买家退款、删折扣。AI Toolkit 的设计让智能体始终待在你可控的护栏内。

## 安全协议

地基技能 `shoplazza-common` 为**破坏性**（取消、删除）、**批量**以及**动钱**的写操作（如退款、收费）规定了以下协议：

1. **预览** —— 用 `--dry-run` 运行命令，只打印请求而不发送。
2. **复述** —— 概述该操作会改动什么。
3. **确认** —— 等你明确确认后再执行。

其他写操作，比如用 `+` 快捷命令建商品或建折扣，在必填值确认后直接执行。只读命令(`+search`、`+count`、`list`、`get`)无需确认。

```
/shoplazza-orders 订单 660011 给买家退 15.50
```

智能体先用 `--dry-run` 预览退款，复述金额与库存退回，等你说"确认"后再真正执行。

在交互式终端里，CLI 自身也会请人确认破坏性命令：`orders +refund` 要求你重新输入订单 ID，`products +unpublish`、所有 `delete` / `cancel` 命令以及 `auth logout` 会询问是否继续。智能体、管道、CI 和 `--dry-run` 都不会出现这些提示，所以在智能体会话里，守住每次写操作的是上面的协议。

## Scope 限定智能体能做什么

认证按业务域授权。智能体只能触及你登录时授予的域：

```shell
shoplazza auth login --store-domain my-store.myshoplaza.com --domain products,orders
```

上面的命令让智能体能管理商品与订单，但碰不到客户、折扣或店铺设置。若要精细控制 OAuth scope:

```shell
shoplazza auth login --store-domain my-store.myshoplaza.com --scope read_product,read_order
```

只授予 `read_*` scope 即让智能体对该域**只读**。超出已授予 scope 的调用会被拒绝（HTTP 403），CLI 将其报为 `auth` 错误，并提示用 `--domain` 或 `--scope` 重新登录。见[认证 → 作用域映射](/zh-CN/docs/app/developer-tools/shoplazza-cli/authentication#作用域映射)。

## 实用护栏

* **最小权限** —— 只授予任务所需的域和 scope。报表类智能体只需 `read_*`。
* **执行前审查** —— 写操作保留确认环节；批准前读一遍被复述的命令。
* **凭据加密存储** —— token 以 AES-256-GCM 加密后存放在 CLI 的配置目录中，不以明文写进配置文件。
* **区分店铺** —— 先让智能体指向开发店；用 `shoplazza auth store use` 切换。
* **CI 密钥** —— 自动化运行时把 UAT 作为加密密钥传入，绝不写进指令或源码。见[无头与 CI](./headless-ci)。

## 参见

* [Agent Skills → 安全协议](./skills#安全协议)
* [认证](/zh-CN/docs/app/developer-tools/shoplazza-cli/authentication)
* [排错](./troubleshooting)