AGENTS.md · diff
git:20260317.4aebbdf to git:20260403.ba40108
30 added, 75 removed. Audit A to A.
# AI 助手开发协作指南 (AGENTS.md)
本文件定义了 **xops-cli** 项目的开发流程、质量标准和协作规范。所有 AI 助手（包括当前及未来的会话）在执行任务前必须仔细阅读并严格遵守。
- ---
-
- ## 🚀 1. 开发工作流 (Workflow)
-
- 项目采用 **"研究 -> 思考 -> 拆解 -> 执行 -> 验证"** 的闭环开发流程。AI 在执行任何代码修改前，必须展现清晰的逻辑链条。
-
- ### 阶段一：研究与分析 (Research)
-
- - **环境探索**：必须首先确认当前环境状态。
- - **上下文检索**：使用 `grep` 或其他工具深度分析受影响的代码上下文。
-
- ### 阶段二：深度思考 (Think & Strategy)
-
- - **禁止无脑输出**：在写代码之前，必须先输出具体的修改策略。
- - **全局评估**：方案必须说明对项目依赖、架构设计的兼容性与潜在影响。
-
- ### 阶段三：任务拆分 (Task Breakdown)
-
- - **原子化执行**：将复杂需求拆解为多个独立、可验证的子任务（例如：1. 定义接口 -> 2. 实现逻辑 -> 3. 编写测试）。
- - **逐步推进**：一次只专注于一个子任务，完成并验证后再进行下一步。
-
- ### 阶段四：执行与验证 (Execution & Validation) - 🔴 核心红线
-
- - **强制要求测试**：**必须**为所有新增功能、核心逻辑或修复的 Bug 编写对应的测试用例（Unit Test 或 Integration Test）。拒绝任何无测试覆盖的代码修改。
- - **强制校验规范**：在任何 `git push` 或提交 PR 之前，必须在本地终端执行并成功通过以下命令：
- 1. `go build ./...` (确保编译通过)
- 2. `go test ./...` (确保逻辑正确且测试通过)
- 3. `golangci-lint run ./...` (确保代码质量 0 Issues)
- - **配置校验**：修改 `.golangci.yml` 后，必须运行 `golangci-lint config verify` 进行格式检查。
-
- ### 阶段五：文档同步 (Documentation Sync) - 🔴 核心红线
-
- - **代码即文档**：更新代码的同时，**必须**同步更新相关的文档。这包括但不限于：`README.md`、CLI 命令的帮助信息 (`help text`)、关键函数的代码注释等。
- - 未更新文档的任务将被视为未完成。
-
- ---
-
- ## 🛠️ 2. 技术栈与环境 (Tech Stack)
-
- - **语言**：Go 1.26+ (严禁降级)
- - **Linter**：golangci-lint v2.x (遵循版本字符串格式 `version: "2"`)
- - **配置管理**：`.golangci.yml`
- - **自动化**：GitHub Actions (CI/CD), GitHub Dependabot
-
- ---
-
- ## 🎨 3. 代码规范 (Coding Standards)
-
- ### 3.1 命名规范 (Naming)
-
- - 遵循 Go 社区的缩写命名惯例：**ID, URL, SSH, CLI, SFTP, TCP** 必须全大写。
- - **禁止使用**：`nodeId`, `hostId`, `identityId`。
- - **必须使用**：`nodeID`, `hostID`, `identityID`。
-
- ### 3.2 错误处理 (Error Handling)
+ ## 🚀 1. 项目开发规范 (Development Standards)
- - **不准静默失败**：所有返回 `error` 的函数必须被检查。
- - **显式忽略**：若确定无需检查（如 CLI 的 `Flush` 或 `Close`），必须使用 `_ =` 或 `_, _ =` 显式标记，禁止直接留空。
- - **错误字符串**：不应以标点符号（如 `!` 或 `.`）或换行符结尾。
+ 项目采用 **"研究 -> 思考 -> 拆解 -> 执行 -> 验证"** 的闭环开发流程。在执行任何代码修改前，必须展现清晰的逻辑链条。
- ### 3.3 变量赋值
+ - **研究与分析**：首先确认当前环境状态，使用工具深度分析受影响的代码上下文。
+ - **深度思考**：在写代码之前，必须先输出具体的修改策略，评估对项目依赖和架构设计的兼容性。
+ - **任务拆分**：将复杂需求拆解为多个独立、可验证的子任务，逐步推进。
+ - **文档同步 (核心红线)**：更新代码的同时，**必须**同步更新相关的文档（如 `README.md`、CLI 帮助信息、代码注释等）。未更新文档的任务视为未完成。
- - 避免 **Ineffectual Assignment**：若变量赋值后不再使用，必须删除或使用下划线忽略。
+ ## 🎨 2. 编码规范 (Coding Standards)
- ---
+ - **语言版本**：Go 1.26+ (严禁降级)。
+ - **命名规范**：遵循 Go 社区的缩写命名惯例，**ID, URL, SSH, CLI, SFTP, TCP** 必须全大写（例如：使用 `nodeID`，禁止使用 `nodeId`）。
+ - **错误处理**：
+ - **不准静默失败**：所有返回 `error` 的函数必须被检查。
+ - **显式忽略**：若确定无需检查，必须使用 `_ =` 或 `_, _ =` 显式标记，禁止直接留空。
+ - 错误字符串不应以标点符号（如 `!` 或 `.`）或换行符结尾。
+ - **变量赋值**：避免无效赋值，若变量赋值后不再使用，必须删除或使用下划线忽略。
- ## 📦 4. 依赖与仓库管理
+ ## 📦 3. Git 规范 (Git Standards)
- - **Dependabot**：本项目启用了每周一次的依赖自动更新。AI 助手在处理 Dependabot PR 时应优先进行本地 `go build` 验证。
- - **Commit 规范**：
+ - **Commit 规范**：提交信息必须遵循以下格式：
- `feat: ...` (新功能)
- `fix: ...` (修复)
- `chore: ...` (配置/维护)
- `ci: ...` (流水线修改)
- `docs: ...` (文档更新)
- `test: ...` (测试用例)
- - **Bypass 权限**：仓库设置了强制 PR 规则，但在紧急修复 Lint 或 CI 配置文件时，可利用管理员 Bypass 权限直接推送到 `master`。
-
- ---
+ - **分支与合并**：仓库设置了强制 PR 规则，紧急修复 Lint 或 CI 配置文件时，可利用管理员 Bypass 权限直接推送到 `master`。
- ## 🔧 5. 常用命令清单 (Commands)
+ ## 🛠️ 4. 测试、构建与 CI (Testing, Building & CI)
- | 命令 | 用途 |
- | --- | --- |
- | make build | 本地编译二进制文件 |
- | make test | 运行 pkg 目录下所有测试 |
- | golangci-lint run ./... | 运行全量代码扫描 |
- | golangci-lint run --fix ./... | 自动修复可修正的 Lint 问题 |
- | gh pr list --author "app/dependabot" | 查看当前的依赖更新 PR |
+ - **强制要求测试 (核心红线)**：**必须**为所有新增功能、核心逻辑或修复的 Bug 编写对应的测试用例（Unit Test 或 Integration Test）。拒绝任何无测试覆盖的代码修改。
+ - **强制校验规范**：在任何 `git push` 或提交 PR 之前，必须在本地终端执行并成功通过：
+ 1. `go build ./...` (确保编译通过)
+ 2. `go test ./...` (确保逻辑正确且测试通过)
+ 3. `golangci-lint run ./...` (确保代码质量 0 Issues)
+ - **Linter 配置**：使用 golangci-lint v2.x。修改 `.golangci.yml` 后，必须运行 `golangci-lint config verify` 进行格式检查。
+ - **常用命令**：
+ - `make build`：本地编译二进制文件
+ - `make test`：运行所有测试
+ - `golangci-lint run ./...`：运行全量代码扫描
+ - `golangci-lint run --fix ./...`：自动修复可修正的 Lint 问题
+ - **CI/CD**：依赖 GitHub Actions 进行 CI/CD，启用 Dependabot 进行依赖自动更新。处理 Dependabot PR 时优先本地 `go build` 验证。
---
**提示**：在任何时候，代码的“干净程度”优于实现的“速度”。