# 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） |