# ai-devops

**Repository Path**: laohoo/ai-devops

## Basic Information

- **Project Name**: ai-devops
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-29
- **Last Updated**: 2026-10-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# adev — AI Coding 工作区 DevOps 工具

**纯 SKILL 形态**的多仓工作区辅助工具：不封装、不改动、不接管任何 AI Coding 工具（Qoder / Claude Code / Trae / Codex 等）的 skill 机制，只做两件事 —— **约定文档落位** 与 **生成免 IDE 的构建/运行/验证脚本**。

零外部依赖：无 npm 包、无 pip 包、无独立 CLI、无二进制。技能本体就是 markdown + bash + PowerShell 脚本。

> 第一次用？看 [5 分钟上手 adev](docs/quick-start.md) —— 里面的命令与输出都是在 Windows + Git Bash 上真实跑出来的。

## 四个痛点分别被哪条命令消掉

| 痛点                                       | 谁来解决                                         | 落地形态                                                                                             |
| ------------------------------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| 1. AI 输入/输出文档无处安放，两周后找不回  | `adev-init`                                      | 工作区根 `.adev/` 九类用途目录 + 每目录用途说明 + `AGENTS.md` 落位规则                               |
| 2. AI 写完代码不知道怎么验证、验到哪算通过 | `adev-init` 写入的硬约束 + `adev-gen-shell` 归档 | 每次编码任务必须产出 dev 批次内的 `DEPLOY.md`（部署说明）与 `VERIFY.md`（验证说明）                  |
| 3. 只为"编译+起进程+探活"被迫开重型 IDE    | `adev-gen-shell` 生成的 `bin/adev`               | `build / run / verify / stop / stack` 能力，从批次工件直启服务、轮询端口、探活、写回结果、干净收进程 |
| 4. 部署说明、验证说明、部署工件三者分散    | `adev-gen-shell` 批次归档                        | 一个时间戳目录内齐备：工件 + 部署说明 + 验证说明 + 构建日志 + 构建清单                               |

## 使用路径

```text
一键安装到工作区 → AI 按 AGENTS.md 编码并落位文档 → 构建/运行/验证 → 批次归档（dev/testing、prod/deploy）
```

1. **安装到项目工作区**（唯一需要你记住的命令）

   没下载仓库时（一行安装，技能包常驻 `~/.adev/pkg`）：

   ```bash
   curl -fsSL https://gitee.com/laohoo/ai-devops/raw/main/bootstrap.sh | bash -s -- /path/to/workspace
   curl -fsSL https://gitee.com/laohoo/ai-devops/raw/main/bootstrap.sh | bash     # 不带路径：把当前目录当工作区
   ```

   ```powershell
   irm https://gitee.com/laohoo/ai-devops/raw/main/bootstrap.ps1 -OutFile $env:TEMP\adev-bootstrap.ps1
   & "$env:TEMP\adev-bootstrap.ps1" C:\path\to\workspace
   ```

   已把仓库 clone 到本地时（直接在仓库里跑，就地取包不下载）：

   ```bash
   bash install.sh /path/to/workspace      # Git Bash；目录不存在会自动创建
   bash install.sh                         # 不指定路径：把当前目录当工作区（进工作区目录后直接跑）
   ```

   ```powershell
   .\install.ps1 C:\path\to\workspace      # Windows 原生终端（内部转跑 install.sh，不重复两套逻辑）
   ```

   一次做完：`.adev/` 九目录契约与各目录用途说明 → `AGENTS.md` 落位规则标记区块 → `.gitignore` 卫生规则 → 把 `adev-init` / `adev-gen-shell` / `adev-update` 三个技能装进工作区项目级技能目录 → 在 `bin/` 放使用说明与 Web 界面后台启动入口 → 打印安装报告与下一步命令。**安装阶段不生成构建/运行编排脚本**（仓库清单与工作区 `bin/adev` 等由后续执行 `adev-gen-shell` 技能时生成），并把 5 分钟上手指南复制到工作区 `.adev/adev-quick-start.md`（与其他 adev 产物同一落位）。

   默认**只写项目工作区**，除 `~/.adev`（包缓存 `pkg/` 与 Web 服务代码 `web/`）外不碰用户家目录（探不到工具技能目录时落项目级 `.agents/skills`）。选项：

   - `--skills-home DIR`：额外把技能装入指定用户级技能目录
   - `--user-skills`：改用 adev-init 的探测链（项目级 → 用户级 → 通用 agents 目录）

   想分步执行（等价于上面一条命令的两段，在 AI Coding 工具里说“初始化工作区”也走同一入口）：

   ```bash
   bash skills/adev-init/scripts/adev-init.sh /path/to/workspace --project-only
   bash skills/adev-gen-shell/scripts/adev-scan.sh /path/to/workspace
   ```

   产出：`.adev/` 目录契约、`AGENTS.md` 标记区块、`.gitignore` 卫生规则区块、技能安装与安装报告；以及 `.adev/adev-repos.yaml`（仓库信息唯一事实源）、工作区 `bin/` 编排脚本与生成脚本契约卡 `bin/jobs/README.md`。

   **还差一步（必须由 AI 完成）**：在 AI Coding 工具里执行 `adev-gen-shell` 技能，它会扫描多仓生成 `.adev/adev-repos.yaml` 与工作区 `bin/` 编排脚本，再按每个仓的开发语言从 `scripts/jobs-templates/` 复制对应模板、由 AI 按真实代码填写，写出该仓的构建/启动脚本 `bin/jobs/build-<repo>.sh(.ps1)` 与 `bin/jobs/run-<repo>.sh(.ps1)`。adev 不猜构建命令：缺脚本时 `bin/adev build` 直接报错并指向该技能。

2. **免 IDE 构建 / 运行 / 验证 / 停止 / 整栈**（bash 与 PowerShell 双套同参数）

   ```bash
   bash bin/adev build  --env dev                      # 全部仓构建并归档 dev 批次
   bash bin/adev build  --env dev --repo backend-java  # 只构建一个仓
   bash bin/adev run    --env dev                      # 起服务（后台）：需工件的仓取最新批次，前端/dev 源码直启不必先 build
   bash bin/adev run    --env dev --repo backend-java --logs  # 启动后把服务日志实时打到控制台（Ctrl-C 停止查看）
   bash bin/adev run    --env dev --repo booking-web          # 前端 dev：直接源码起 dev server，**不带任何端口参数**（听哪个端口只看仓自己的配置）
   bash bin/adev verify --env dev                      # 端口轮询 + 健康检查 + 接口冒烟，结果写回 VERIFY.md
   bash bin/adev stop   --env dev                      # 干净收进程
   bash bin/adev build  --env prod                     # 生产批次 + ROLLBACK.md
   bash bin/adev stack list                            # 看服务栈划分与启动顺序
   bash bin/adev stack up --stack booking              # 微服务：按 depends_on 顺序起多个服务并等端口就绪
   bash bin/adev stack verify --stack booking           # 整栈探活
   bash bin/adev stack down --stack booking             # 逆序整栈停止（stack ps 看运行状态）
   ```

   ```powershell
   .\bin\adev.ps1 build --env dev          # 原生 Windows 终端，不依赖 Git Bash
   .\bin\adev.ps1 verify --env dev --repo backend-java
   ```

3. **（可选）本机 Web 界面**：浏览 `.adev` 产物、点按钮跑 `build/run/verify/stop`（run 后按 `--logs` 实时刷新运行日志）、生成"调用 AI 助手跑技能"的提示词。服务是随仓库提交的产品源码（`web/adev-web.js`，零 npm），安装时复制到 `~/.adev/web/` 并在工作区 `bin/` 生成后台启动入口；不使用界面时无需 node。

   ```bash
   bash bin/adev-web                 # 后台启动，浏览器打开打印出的 http://127.0.0.1:8787/（PowerShell：.\bin\adev-web.ps1）
   bash bin/adev-web --stop          # 收掉后台服务
   ```

   或在 AI 工具里说"adev web"也能获知入口：界面已在安装时就位，无需再生成。

## 安装渠道与版本

| 入口                                                | 适合谁                                                                    | 需要什么                              |
| --------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------- |
| `bootstrap.sh` / `bootstrap.ps1`                    | 第一次接触 adev、不想先 clone 的人                                        | bash + git（无 git 时自动退 tarball） |
| `install.sh` / `install.ps1`                        | 已 clone 仓库、或想指定 `--src` 的人                                      | bash（ps1 入口仅定位 bash 后转跑）    |
| `adev-init` / `adev-gen-shell` / `adev-update` 技能 | 在 AI Coding 工具里初始化工作区 / 生成构建脚本 / 新增代码库后增量纳入的人 | 已由上面任一入口装入技能目录          |

> Web 界面不是技能：它的代码随仓库提交，由安装入口复制到 `~/.adev/web/` 并在工作区 `bin/` 生成启动入口；后续更新 adev 会随包刷新。

> 之后往工作区新增代码库：在 AI 工具里执行 `adev-update` 技能，它会幂等地补契约、刷新清单与 `bin/` 编排、并只给缺脚本的新仓交给 `adev-gen-shell` 生成（不动已有仓的 `bin/jobs/*`）。可反复执行。

- **版本与更新**：`--ref <tag|branch>` 锁版本（缺省 `main`）。**重跑同一条安装命令就是检查更新**：先向包源取新包 → 取成功后删除 adev 家目录 `~/.adev` 里的旧缓存与旧 Web 服务代码并落位新包 → 用新包刷新工作区（技能副本、带 `adev:generated` 标记的 `bin/` 编排脚本与仓库清单；AI 写的 `bin/jobs/*` 不动）。结尾给出结论：`已更新: 旧版 → 新版` 或 `已是最新`。工作区侧 `.adev/adev-version.yaml` 记录装的是哪版（`bin/adev report` 会显示）。
- **缓存与离线**：包体常驻 `~/.adev/pkg`（`--pkg DIR` 可改缓存位置，`ADEV_HOME` 可改 adev 家目录）。**默认不再静默复用旧缓存**——那正是"重跑安装却更新不了"的原因。确需离线重装加 `--offline`（用现有缓存、不联网，缺缓存则报错）；联网取包失败时保留现有缓存并退回它重装（并明说可能不是最新版）。`--update` 保留为空操作以兼容旧脚本。
- **内网/离线发布**：用环境变量覆盖包源，无需改脚本：`ADEV_REPO_URL`（git 地址，缺省 `https://gitee.com/laohoo/ai-devops.git`）、`ADEV_TARBALL_URL`（任意 tar.gz，含 `file:///`）、`ADEV_PKG_REF`。Gitee 与 GitHub 的 archive 路径不同，bootstrap 已按域名区分。
- **不污染环境**：两个入口默认只写目标工作区（`--project-only`），除 adev 家目录 `~/.adev`（包缓存 `pkg/` + Web 服务代码 `web/`）外不往用户家目录放技能。
- **卸载**：删工作区的 `.adev/`、`bin/adev*`、`bin/jobs/`、项目级技能目录里的 `adev-*`，再删 adev 家目录 `~/.adev`。

## 目录契约（`.adev/`）

| 子目录          | 放什么                                   |
| --------------- | ---------------------------------------- |
| `refs/`         | 外部参考文档（规范、API 文档、平台资料） |
| `requirements/` | 需求输入（AI 任务的唯一需求源头）        |
| `plan/`         | 与 AI 质询后定稿的方案计划               |
| `guide/`        | 对外交付的使用指南                       |
| `data/`         | SQL、CSV、初始化数据、建表脚本           |
| `testing/`      | 开发环境部署+验证说明与 dev 批次工件     |
| `deploy/`       | 生产部署说明与 prod 批次工件             |
| `experience/`   | 开发规则、架构要求、踩坑摘要             |
| `other/`        | 未归类兜底                               |

**其它 SKILL 的输出目录名由该 SKILL 自身规范决定，但父目录一律落在 `.adev/` 下。** 这条规则同时写在 `.adev/README.md` 与 `AGENTS.md` 里。

## 批次内容与归档口径

- dev → `.adev/testing/<yyyyMMdd-HHmm>/`；prod → `.adev/deploy/<yyyyMMdd-HHmm>/`；两套永不混目录。
- 批次内每仓一个子目录：**工件**、**`DEPLOY.md`**（环境要求 / 构建命令 / 工件位置 / 启动步骤 / 配置项差异，prod 另含发布前置条件）、**`VERIFY.md`**（脚本自动验证结果 + 人工验证清单两节）、**`build.log`**、**`adev-job.env`**（生成脚本回报的事实，可追溯工件从哪来）；批次根有 **`manifest.yaml`**（批次时间、环境、每仓 commit、构建命令、工件 sha256 与字节大小、耗时、成功/降级/失败状态）。
- prod 批次额外产出 **`ROLLBACK.md`**，指向次新历史批次并列出其工件与校验值；首个批次明确写"无历史批次"。
- 版本库卫生：`*.md` / `*.yaml` 进版本库，构建工件与批次内的 `adev-job.env`（jar/zip/whl/exe/tar.gz 等）以及 `.adev/.runtime/` 不进版本库（由 `adev-init` 写入的 `.gitignore` 区块保证）。

## 免 IDE 验证闭环

**构建前先过版本新鲜度门**：`bin/adev build` 会对每个仓检查——若是 git 工作树且当前分支有远端跟踪分支，就 `git fetch` 比对本地是否落后；任一仓本地代码不是最新则**暂停整个构建（退出码 7）并提示 `git -C <path> pull`**，不会创建半成品批次。非 git / 无上游 / 离线取不到远端会自动放行；离线或确认无需更新时用 `--skip-git-check`（PowerShell `-SkipGitCheck`，或环境变量 `ADEV_SKIP_GIT_CHECK=1`）。`run`/`verify`/`stop`/`stack` 不受此门约束。

`run` 调该仓的 `bin/jobs/run-<repo>.sh(.ps1)`：由脚本决定如何准备运行目录、如何直启，并把可杀进程 PID 交给编排侧；`verify` 轮询端口 LISTENING → HTTP 健康检查 → 接口冒烟，把"通过/失败 + 耗时"回填进 `VERIFY.md` 的自动结果区块；`stop` 先按记录的 PID 收进程，若端口仍被占用则只杀该端口的监听进程（两项都是精确目标，不对命令行做模糊匹配）。需先安装到目标环境才能跑的类型（Python wheel）由生成脚本声明"不本机常驻"，改落为批次内的人工清单，不假装启动。无法自动验证的填到人工清单，不静默跳过、不误报通过。

**端口不参与启动**：清单里的 `port` 是扫描从项目配置解析出的**观测量**，只给 verify 探活、stop 按端口清理与 prod 静态自托管绑定用。生成脚本的 dev 分支从不读端口：既不把 `--port` 透传给包管理器（pnpm/npm 会原样交给 dev 脚本，webpack-cli 遂把 `--port` 当入口路径，报 `This dependency was not found: ..././--port`），也不导出 `PORT`（框架读到就覆盖仓自身配置）。dev server 听哪个端口永远只看仓库配置；要看真实访问地址用 `bin/adev run --logs`。

微服务架构下多服务起停用 `bin/adev stack`：栈成员与启动顺序由清单的 `arch` / `stack` / `depends_on` 决定（这三个字段由 AI 分析代码后补全，重跑扫描原样保留）。`stack up` 按依赖顺序逐个起并等端口就绪，依赖没就绪就中止而不是硬起上层；`stack down` 逆序停止；`stack list` 可先校验拓扑；循环依赖直接报错，不给出任意顺序。单体仓自成一站，同一套命令可用。

## 项目知识与机器事实的分界

| 归谁           | 内容                                                                                                                                                                                                                                                                                                                                        |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 扫描（机器）   | 识别仓库入册（Maven / Gradle / Vite / Webpack / vue-cli / Go / Python）、包管理器按 lockfile、端口与健康检查从项目配置解析（Java 多模块工程下探到主启动类模块的 `src/main/resources`）、运行时版本要求（小程序 / uni-app 不再是独立类型：Taro、uni-app 等按 package.json 归前端；Android / iOS 不再支持，扫描直接忽略该类仓）               |
| AI（生成脚本） | 从技能内 `scripts/jobs-templates/<语言>/` 复制对应模板再按真实代码填写：构建命令与 dev/prod 差异（Java/Maven 恒含 `clean`、前端 dev 不构建只跑 dev server）、工件真实路径（多模块 reactor 取主启动类模块的 jar/war）、启动方式与 `ADEV_RUN_MODE`（`artifact` 从批次工件启、`source` dev 直启源码）、平台/工具链不可用时的降级与人工执行骨架 |
| AI（清单字段） | `arch`（monolith/microservices）、`stack`（服务栈名）、`depends_on`（栈内启动顺序）                                                                                                                                                                                                                                                         |

解析不到的一律留空并标记"待人工补充"，而不是猜；构建命令这一层 adev 从不猜，缺 `bin/jobs` 脚本即报错。

## 失败与降级语义

- **失败**（缺该仓生成脚本、生成脚本非零退出、构建报错、契约未声明工件或声明的工件不存在）：原因可读、构建日志归档到 `<bucket>/.failed/<ts>/<repo>/build.log`、**不产出半成品批次目录**、整体非零退出；其余仓结果不受影响并在报告中分列。
- **降级**（生成脚本以退出码 10 声明：工件需装进目标环境、stub 仓无构建入口）：批次照常产出（含说明与人工执行骨架），状态记 `degraded` 并写明原因；**不谎报成功**，整体退出码仍为 0。

## 开发本仓库：回归与发版门

单一测试接缝 = 工作区根脚本执行。零依赖 bash 断言，只看磁盘产出与退出码：

```bash
bash tests/run-all.sh          # 全量行为回归
bash tests/run-all.sh 05       # 只跑票05
bash tests/release-check.sh    # 发版门：回归 + 脚本静态检查 + 发布物完整性 + 远端一行安装冒烟
bash tests/release-check.sh --skip-remote   # 无网/无工具链的 runner 只跑前三步
```

夹具工作区在 `fixtures/workspace/`（Maven、Maven 多模块 reactor、Gradle stub、Vite 前端、Go、Python 各一 + 一个非仓库目录），回归用的"AI 产物样本"（每仓的 build/run 生成脚本，bash 与 PowerShell 成对）在 `tests/fixtures/jobs/`。任何机器 clone 后无需真实业务仓库即可跑完整回归：回归验证的是**编排与契约**（批次、校验值、探活、起停、降级与失败路径），而非某类构建体系能否跑通——后者由本机工具链与生成脚本决定，缺工具链时相应断言自动 skip。

## 接入流水线（Gitee Go）

流水线的唯一构建命令就是 `bash tests/release-check.sh`（runner 需有 bash + git；要跑真构建则再装 JDK/Node）。

Gitee Go 的 `.workflow/*.yml` 由控制台创建流水线时回写到仓库，所以本仓库不手写模板（猜写的 schema 只会变成死文件）：仓库页 → 流水线 → 开通 Gitee Go → 选一个模板创建 → 加到代码视图把执行命令换为上面那行 → 保存后按 push 自动触发。无网络或无工具链的 runner 加 `--skip-remote`，它会只跑回归、静态检查与发布物完整性。

## 范围外（明确不做）

- 不封装、不改动、不接管任何 AI Coding 工具的 skill / agent / 配置机制。
- 不提供独立 CLI、二进制或需安装的运行时依赖（仓库根的 `install.sh` / `install.ps1` 仍是零安装依赖的引导脚本，不新增任何工具链）。
- 不接管 CI/CD：不生成流水线配置、不部署到远端、不做发布审批。
- 不做生产环境的实际部署动作（不 ssh、不 kubectl、不推镜像），只产出生产部署说明与工件归档。
- 不做 IDE 集成、插件、图形界面；不生成需求/方案文档内容（只规定它们落在哪）。
- 不处理工作区根以下的嵌套多层仓库结构；不保证无网络/无工具链环境下构建成功，只保证失败时行为可预期。
- 不猜项目知识：构建命令、工件路径、启动方式一律来自 AI 分析代码后生成的 `bin/jobs` 脚本；服务架构与启动拓扑（`arch`/`stack`/`depends_on`）也由 AI 声明，adev 只按声明执行。

## 已知限制

- 依赖安装不由 adev 代管：`package.json` 声明了依赖但 `node_modules` 不存在时，adev 明确报错并提示先执行 `<pm> install`（避免意外联网与耗时）。
- 仓库识别只看工作区根的一级子目录。
- 不支持 Android / iOS 项目：扫描阶段直接忽略这两类仓（不注册、不生成构建脚本，列入扫描输出的忽略清单）。uni-app 本质是前端项目，按 package.json 归入 frontend 正常处理。
- 扫描（`adev-scan`）与一键安装本身仍是 bash 脚本（含 `adev-init`）；`install.ps1` 是定位 bash 后转跑 `install.sh` 的薄包装（避免同一逻辑写两套后期漂移），因此 Windows 上仍需 Git for Windows。PowerShell 双胞胎覆盖的是日常运行期动作：构建、启动、验证、停止。
- 所有生成的 `.ps1` 与 `install.ps1` 均以 **UTF-8 BOM** 开头：Windows PowerShell 5.1 无 BOM 时会按 OEM 码页解脚本，中文注释会吃掉引号导致解析失败（而 pwsh 7 不报，只跑 pwsh 的测试会假通过）。技能包内的模板与共享库自身保持无 BOM，BOM 在生成时统一前置。

端到端走查记录见 `docs/walkthrough-20260928.md`。