# nas-deploy · AI 接入索引

这是给**使用本工具的项目 AI**的入口，不是库维护者的发包指令。安装后的路径为 `node_modules/@mingo_789/nas-deploy/AGENT_GUIDE.md`；下列文档和示例都随 npm 包发布，无需访问源码仓库。适用版本以同目录 `package.json` 为准。

首次接入先读 [公共约定](agent/common.md)，再按任务选择文档，不必一次读取整个目录。

| 任务 | 读取内容 |
| --- | --- |
| 新项目接入、调整端口/挂载/环境变量/健康检查 | [配置教程](agent/configuration.md) |
| 构建、发布到 NAS、查看状态、处理失败、清理 | [部署与恢复](agent/deployment.md) |
| 迁移 build-image.sh / deploy.sh | [迁移教程](agent/migration.md) |
| 参考项目如何选择端口、网络、健康检查和应用变量 | [使用案例](docs/使用案例.md) |
| 人工操作及完整参数表 | [README](README.md) |
| 维护 nas-deploy 本身并发布 npm 包 | [npm 发布教程](docs/npm发布.md)，需在源码仓库执行 |

## 开始前确认

1. 读取使用方的项目约定、Dockerfile、现有部署配置和包管理器；使用已安装版本的文档。
2. 将应用构建、运行环境、健康端点和数据目录留在项目层；通过配置复用 CLI，避免再次复制部署脚本。
3. 区分两个 `release`：应用内 `nas-deploy release` 是部署到 NAS；本工具源码仓库的 `npm run release` 是发布 npm 包。
4. 默认健康成功后**仅留当前版本**：`retainPrevious: 0`、`localArchive: true`、`localImages: true`。不要自行改成永久保留旧版本。
5. `--dry-run` 不是实机验收，`rollback` 不是数据库恢复；报告实际完成的验证范围。
6. init 只生成通用配置，首次接入后保存在应用仓库；后续发布复用配置。项目案例仅供阅读，不是专用初始化选项。

## 在使用方 AGENTS.md 中引用

可将以下内容加入使用方项目自己的协作说明：

```text
本项目通过 @mingo_789/nas-deploy 构建镜像并部署到 NAS。
修改部署配置或执行部署前，读取 node_modules/@mingo_789/nas-deploy/AGENT_GUIDE.md，
再按索引读取本次涉及的配置、部署或迁移文档。
遵循本项目现有授权范围，复用已安装 CLI，不再维护重复的部署 Shell 脚本。
```

维护文档时，公开参数、默认值、失败恢复行为发生变化，应同步对应页面；所有相对链接必须指向随包文件。