# AGENTS

## ROADMAP

- 只记录**未完成**的事项，已完成的及时删除
- 按 P0-P3 优先级分组
- 基本假设放在末尾，不随版本迭代删除
- 新增需求先定优先级再放入对应分组

## AI 操作原则

### 禁止随意删除文件

AI 不得在不读取文件内容的情况下删除文件。删除前必须：

1. 读取文件内容，确认用途
2. 判断文件是否属于项目代码、文档、配置
3. 如不确定，保留文件并向人询问

特别地，`docs/` 下所有文件优先视为项目文档，非代码文件不因"不认识"而删除。

`git add -A` 会捡到陌生文件，AI 应当在 commit 前 review 变更清单，而不是 commit 后再去 amend 清理。

## 开发规范

### 发布工作纪律

**工作纪律 1：AI 禁止直接 publish**

AI 的 git 操作止步于 `commit && push`。tag、stage、publish 由人执行（或经人确认后 AI 可执行 `stage`/`publish` 命令，但 tag 必须指向已提交的代码）。

```
❌ AI 不应直接运行：
   git tag cli/v0.3.0 && git push origin cli/v0.3.0
   qtcloud-devops publish -v cli/v0.3.0 -y

✅ AI 可以做的事：
   edit Cargo.toml + CHANGELOG → git commit && git push
   → 由人打 tag 或确认后 AI 执行 stage/publish
```

**工作纪律 2：发布前预验证**

push 之前，运行预验证脚本：

```bash
./scripts/preflight.sh
```

脚本内容应至少包含：

```bash
cargo build --release                    # 确认编译通过
cargo test                               # 确认测试通过
cargo publish --dry-run --registry crates-io  # 确认 crates.io 发布可行
maturin build --release --out dist       # 确认 wheel 构建可行
```

preflight 不通过不发布。

**工作纪律 3：最少预发布版本数**

一次 rc 应承载完整的 CI 验证（构建 + 发布），而不是分多次。需要验证的三件事：

1. **操作系统兼容性**：Linux / macOS / Windows
2. **注册源发布**：crates.io + PyPI
3. **版本元数据**：license、路径、CHANGELOG

如果一次 rc 因为某个问题失败，修复后应预期其余步骤不受影响（而不是出现新的问题）。出现新问题说明本地预验证不足。

**工作纪律 4：测试与发布分离**

- 单元测试在 push/PR 时由 test CI 执行（待建立）
- build/publish CI 不运行测试，避免环境问题阻塞发布

## 提交消息

- `feat:` — 新功能
- `chore:` — 版本号变更、配置更新
- `docs:` — 文档更新
- `fix:` — 修 bug
- `test:` — 测试

## CLI 设计规则

### `code` 子命令行为

```
qtcloud-devops code status [path]                # 三路 commit 比对 + 聚合统计
qtcloud-devops code sync [name] [--repo path]    # 同步子模块指针到父仓库
qtcloud-devops code retire <name> [--repo path]  # 退役子模块
```

### 规则

- `status`：路径默认为当前目录 `.`
- `sync`：`name` 省略时同步全部子模块
- `retire`：`name` 为必填参数
- 所有命令由 Rust 直接实现，无 Python 封装层

### release 命令行为

```bash
qtcloud-devops stage -v <version>        # 标记版本，进入 Staged 状态
qtcloud-devops publish -v <version> [-y] # Staged → Published（标签 + GitHub Release）
qtcloud-devops cancel -v <version>       # Staged → Cancelled
qtcloud-devops retire -v <version>       # Published → Retired
```

### 规则

- 版本号格式：`vX.Y.Z` 或 `scope/vX.Y.Z`（如 `cli/v0.3.0`）
- scope 前缀用于多仓库场景，CI 通过 `startsWith(github.ref, 'refs/tags/scope/')` 过滤
- 发布流程：`stage` → `publish`（两步）。`stage` 只校验版本号，`publish` 执行 tag + GitHub Release
- 回滚：`create_tag` 失败无副作用；`push_tag` 失败删本地 tag；GitHub Release 失败删本地+远程 tag
- 仓库自动检测：从 `git remote get-url origin` 解析 GitHub 仓库名（`get_remote_repo()`）

## 测试

```sh
cargo test          # 全部 129 测试
cargo test --test release  # 仅 release 集成测试
cargo test --test code     # 仅 code 集成测试
```

## CI 工作流

| 工作流 | 触发 | 行为 |
|--------|------|------|
| `build-cli` | `release: [published]` + tag `cli/*` | 版本校验 → 三平台构建 → wheel 构建 |
| `publish-cli` | `workflow_run` (build-cli 成功) | publish-crate + publish-pypi（独立 job） |
