name: qa description: “在提交前运行QA检查。在编写代码后、提交前或CI可能失败时使用。”
在本地运行项目的QA流水线，以便在问题到达CI之前发现它们。
运行前
- 检查变更内容：运行
git diff --name-only查看哪些文件被修改；这决定了要运行哪些检查（见下面的“何时运行什么”） - 先构建：运行
CGO_ENABLED=0 go build -o /dev/null ./cmd/ctx以在运行完整流水线前捕获编译错误
何时使用
- 编写或修改Go代码后
- 提交前（在本地发现问题，而不是在CI中）
- 当CI失败且需要在本地复现时
- 依赖项变更或重构后
何时不使用
- 当只有文档、Markdown或配置文件更改时（未触及Go代码）
- 当用户明确表示“跳过QA”或“不检查就提交”时
- 开发中途，代码有意不完整时；等到一个逻辑停止点
使用示例
/qa
/qa (重构recall命令后)
运行什么
按顺序运行这些检查；每个都依赖于前一个检查通过：
1. 格式化
gofmt -l .
如果列出文件，则它们需要格式化。使用 gofmt -w . 修复，并将格式化后的文件包含在提交中。
2. 代码检查
CGO_ENABLED=0 go vet ./...
3. 代码规范检查
golangci-lint run --timeout=5m
4. 测试
CGO_ENABLED=0 CTX_SKIP_PATH_CHECK=1 go test ./...
5. 冒烟测试（如果CLI行为已更改）
make smoke
在临时目录中构建二进制文件并执行 ctx init、ctx status、ctx agent、ctx drift、ctx add task 和 ctx recall list。
快捷方式
make audit 按顺序运行步骤1-4。当您想要一个简单的通过/失败答案时使用它。
何时运行什么
| 变更内容 | 最低检查要求 |
|---|---|
任何 .go 文件 |
make audit |
| CLI命令行为 | make audit + make smoke |
| 仅文档/配置 | 无 |
| 模板文件更改 | go build (嵌入必须有效) |
失败时
当检查失败时，在修复前先推理错误原因：阅读输出，追踪原因，然后修复。不要盲目重试或应用想到的第一个修复方法。
常见失败
| 失败原因 | 修复方法 |
|---|---|
gofmt -l 列出文件 |
gofmt -w . |
CLI代码中出现 fmt.Printf |
使用 cmd.Printf (由AST测试强制执行) |
| golangci-lint 未使用变量 | 删除它；不要重命名为 _ |
测试需要 CTX_SKIP_PATH_CHECK |
已在 make test 和 make audit 中设置 |
internal/context 覆盖率低于70% |
添加测试；使用 make test-coverage 检查 |
输出格式
运行检查后，报告：
- 结果：通过或失败
- 失败项：什么失败了以及如何修复（如果有）
- 触及的文件：自动格式化的文件列表
质量检查清单
在报告QA结果之前，请验证：
- [ ] 为变更内容运行了适当的检查（不多也不少）
- [ ] 修复了可自动修复的问题（gofmt），而不是仅仅报告它们
- [ ] 所有失败项都有明确的修复操作（不仅仅是“它失败了”）
- [ ] 如果需要冒烟测试（CLI行为已更改），则已运行