企业官网建设流程全解析

aislop是一款面向 AI 编码助手代码的确定性代码质量检查工具，其aislop ci命令正是为 CI 质量门禁设计的：在 GitHub Actions 中运行后，它会给代码打出 0–100 的质量分，一旦分数低于阈值（默认 70）或存在 error 级别问题，CI 就会以非零退出码失败，从而自动拦截低分 PR。整个扫描过程秒级完成，不依赖任何 LLM，分数完全可复现。

为什么需要 aislop ci 质量门禁

AI 编码工具生成的代码常常"能编译、测试通过"，但混入了叙述式注释、吞掉的异常、as any强转、幻觉导入、死代码等"AI 味"问题。aislop 内置 50+ 条确定性规则，覆盖 TypeScript、Python、Go、Rust 等 10 种语言目标，通过 6 个引擎（格式、Lint、代码质量、AI Slop、安全、架构）并行检查并汇总为单一评分。把aislop ci接入 CI，相当于给每次 PR 装上一道自动质量闸门。

它如何判定失败（逻辑见 src/commands/ci.ts 与 src/commands/scan-exit-code.ts）：

• 分数低于ci.failBelow（默认 70）→ 退出码 1；
• 存在任一 error 级别诊断 → 退出码 1；
• 配置了基线后，出现任何基线外的新发现→ 退出码 1；
• 配置failOnMissingTools: true且缺少必要工具 → 退出码 1。

一键安装：aislop init 最快配置方法

最快的接入路径只需一条命令：

npx aislop init

对 GitHub Actions workflow 提示选择 "yes"，它会自动生成两个文件并提交即可生效：

• .aislop/config.yml—— 策略文件：阈值、引擎开关、评分权重都在这里；
• .github/workflows/aislop.yml—— CI 工作流文件。

默认的 workflow 内容极简（见 src/config/defaults.ts 中的DEFAULT_GITHUB_WORKFLOW_YAML）：

name: aislop on: push: branches: [main] pull_request: jobs: quality-gate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: scanaislop/aislop@v1 with: version: latest

GitHub Actions 手动配置：两种等价写法

如果不想用init，也可以手动添加 workflow。

写法一：npx 自包含运行（docs/ci.md 推荐方式，永远跑最新 CLI，无需升级版本号）：

# .github/workflows/aislop.yml jobs: quality-gate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 24 - run: npx --yes aislop@latest ci

写法二：Marketplace Action（action.yml 定义的 composite action，内部自动完成 setup-node 与版本解析）：

- uses: actions/checkout@v4 - uses: scanaislop/aislop@v0.18.1 # 锁定版本，可复现构建

版本对应关系（自 v0.18.1 起）：uses:引用 release tag（如@v0.18.1）或 commit SHA 时运行对应 CLI 版本；@v1、@main等其他引用则运行最新发布版。显式传入version输入总是优先。锁定 tag 或 SHA 后，Dependabot 的github-actions更新会同时升级 Action 与 CLI，没有额外的版本号要维护。

配置质量门禁阈值：failBelow 与 failOnMissingTools

核心开关都在.aislop/config.yml（默认值见 src/config/defaults.ts）：

ci: failBelow: 70 # 分数低于 70 即让 CI 失败 format: json # CI 输出结构化 JSON，便于解析 failOnMissingTools: true # 缺少必要工具时直接失败，而不是出"部分扫描"分数

关于failOnMissingTools：Python/Go/C/C++/C# 等语言的部分检查依赖ruff、golangci-lint、cppcheck等外部工具。默认情况下缺工具时对应检查静默跳过、分数不含这些维度；在 CI 中你通常希望"缺工具 = 扫描不完整 = 失败"，此时将其设为true更稳妥。扫描输出会列出缺失的工具名，aislop doctor能告诉你如何安装。

评分本身如何计算（错误计 3.0 分、警告计 1.0 分，按引擎权重与规则影响力分层加权，再做密度归一化），详见 docs/scoring.md。分数标签：75–100 为 Healthy，50–74 为 Needs Work，0–49 为 Critical。

PR 级精准门禁：只检查本次改动的文件

存量项目里全量扫描可能包含大量历史问题。ci与scan一样支持--changes和--base，可以只对本次 PR 触碰的文件评分：

npx aislop ci --changes --base origin/main

注意一个常见坑：在 CI 中 PR 的改动已经提交，裸--changes（对比HEAD）什么都看不到，必须显式传--base <目标分支>。base 引用必须能在 checkout 中解析：完整克隆时origin/main直接可用；浅克隆或单分支克隆需要先git fetch origin main再传--base FETCH_HEAD。若--base解析失败，运行会直接报错而不是"空扫描静默通过"。分数门禁与退出码行为与全量ci完全一致。

老项目平滑接入：baseline 只对新增问题失败

接手一个老代码库，不可能要求"先修完所有问题才开门禁"。aislop 的 baseline 机制让 CI只对新增发现失败：

aislop baseline write # 把当前所有发现记录到 .aislop/ci-baseline.json

提交该文件并在配置中指向它：

ci: baseline: .aislop/ci-baseline.json

之后aislop ci的行为是（机制见 src/baseline/ 与 docs/ci.md）：

• 发现按"规则 + 文件 + 该行文本"匹配基线，不按行号匹配——文件里别处增删行不会误报；
• 任何不在基线中的发现（无论严重级别）都会让 CI 失败；仅包含已接受发现则通过；
• 分数仍统计全部发现，所以分数门禁依旧生效；
• 不再出现的条目会被报告为 stale，运行aislop baseline prune可清理——prune 只会删除、从不新增，基线随修复不断缩小。

解析 CI 结果：JSON 输出与 SARIF 上报

aislop ci默认输出结构化 JSON（人类可读用--human），包含评分、标签、各引擎耗时与发现数、完整诊断列表：

{ "schemaVersion": "1", "score": 87, "label": "Healthy", "engines": { "format": { "issues": 0, "skipped": false }, "ai-slop": { "issues": 2, "skipped": false }, "security": { "issues": 0, "skipped": false } }, "diagnostics": [] }

被基线接受的诊断会带"baselined": true标记，另有一个baseline对象报告accepted/new/stale计数，方便在 CI 日志中直观判断失败原因。

若想让发现进入 GitHub Security 标签页，改用 SARIF 输出并上传：

- run: npx aislop@latest scan . --sarif > aislop.sarif - uses: github/codeql-action/upload-sarif@v3 with: sarif_file: aislop.sarif

常见问题速查

小结

aislop ci用一条命令就把"AI 代码质量门禁"装进了 CI：aislop init一键生成 workflow 与配置，failBelow控制分数阈值，--changes --base精准卡 PR 改动，baseline 机制让存量项目平滑过渡，JSON/SARIF 输出方便二次消费与上报。配合本地aislop scan --staged的 pre-commit 检查（同样见 docs/ci.md），低分 PR 就再也进不了主干。