Skylos

Skylos 是什么？

Skylos 是面向 Python 项目的开源（Apache-2.0）命令行工具和 Pull Request 门禁，无需账户即可运行。skylos . 可查找无用代码：未使用的函数、类、导入项和空文件。添加 -a 可检查安全漏洞、硬编码密钥、易受攻击的依赖项、代码质量和 AI 生成代码中的错误。检查结果包含源代码位置和佐证分析；skylos done 可检查分支（通常是编码 Agent 创建的分支）是否已准备好合并。

它适用于：

• 合并来自 AI 编码 Agent 的 Pull Request 的团队，例如使用 Claude Code、Codex 和 Cursor 的团队。skylos done 会运行测试，并标记已删除或跳过的测试、放宽的 CI 测试步骤、被禁用的 lint 或类型检查，以及仅针对测试的特殊情况。
• 希望进行框架感知型无用代码、安全和密钥检查的 Python 维护者。Python 的覆盖最深入；其他语言请参阅语言支持。

pip install skylos
skylos .                  # find dead code
skylos . -a               # add security, secrets, quality, dependency and AI-code checks
skylos done --base main   # is this branch finished? runs your tests, compares with main

**实证，包括误报：**借助 Skylos 完成的 10 个无用代码清理 Pull Request 已合并到 9 个开源项目的默认分支中，其中包括 Black、NetworkX、Optuna、mitmproxy 和 pypdf。真实世界结果列出了此记录中的 26 个清理和质量修复 Pull Request，包括已关闭、已撤销或从未进入默认分支的项目。这些是获接受的清理 Pull Request，并不代表认可。

网站 | 文档 | 仓库地图 | 快速开始 | GitHub Action | VS Code 扩展 | 真实世界结果 | 基准测试 | 路线图 | 贡献指南

English | Deutsch | 简体中文 | 翻译

Skylos 默认在本地运行，也可以在 CI 中作为 Pull Request 门禁使用。需要通过一个命令检查仓库或 Pull Request 是否存在以下问题时，可使用它：

• 无用代码和未使用的文件
• 安全漏洞和危险的数据流
• 密钥和依赖项 CVE
• CI/CD 和边缘设备部署配置错误
• 复杂度、重复分支和深层嵌套等质量退化
• 常见的 AI 生成代码错误，包括缺少防护、虚假辅助函数、虚构的包 API 和不可能存在的依赖项版本
• 大模型应用风险，例如不安全地使用工具以及缺少输出验证 Skylos 支持 11 种语言：Python、TypeScript/JavaScript、Java、Go、PHP、 Rust、Dart、C#、C++、Kotlin 和 Shell。Python 的覆盖范围最广。 TypeScript/JavaScript 和 Java 也支持死代码、安全和质量检查； PHP 和 Dart 支持死代码和安全检查（Dart 安全检查涵盖命令注入、 路径遍历和 SSRF）；Rust 支持命令注入和路径遍历检查，以及实验性的 死代码检查（低于默认置信度阈值的结果会被隐藏；使用 --confidence 40 可列出）。 Go 死代码和安全检查需要原生的 skylos-go 引擎：从 4.50 开始，适用于 Linux、macOS 和 Windows（x86_64 和 arm64）的 PyPI 轮子会包含该引擎，容器镜像也包含该引擎，GitHub Action 也会构建该引擎。在其他 平台上，skylos doctor 会打印从源代码构建该引擎的命令，而 SKYLOS_GO_BIN 可用于指定 Skylos 使用单独构建的引擎。C# 支持不完整，Kotlin 死代码检查仅涵盖私有声明和导入（没有 Kotlin 安全规则），C++ 仅支持未使用的文件局部函数，而 Shell 仅支持安全检查。 Skylos 也会检查 CI/CD 和部署配置。请参阅 语言支持。

阅读结果

记住 风险、可维护性、死代码、门禁：

读数	含义
风险	最高的未解决严重性和数量。无论代码库规模多大，一条严重发现仍属于严重问题。
可维护性	建议数量、受影响的代码单元，以及测量值超过限值的程度。
死代码	带有置信度和证据的待移除候选项；删除前请检查动态调用和公共 API。
门禁	发现项是否满足已配置的限值。通过表示符合策略，并不意味着没有发现项。

发现项的 类型 与严重性不同：缺陷是具体的正确性问题模式，审查需要结合上下文判断，而建议涉及可维护性或工具。审查类发现仍可能是严重问题。建议会在规则组中显示；--expand-advice 会显示所有位置，而 JSON 会保留完整记录。分组无法改善评估结果，也无法绕过门禁。

安全发现项会在可用时显示记录的源到汇证据，并标明静态分析的不完整之处。依赖覆盖信息会列出未解析的版本，以及检查所需的受支持输入。这两种视图都不会声称依赖在运行时可被利用，也不会声称已完整掌握安装环境；JSON 会保留完整证据。

对于 uv.lock，有效的 Git、URL、路径和私有索引依赖会标记为未检查。Skylos 仍会查询受支持的公共包；仅覆盖不足不会导致退出码 2。它无法据此确认依赖评估结果完全无问题。请参阅 uv 源覆盖范围。

新的源代码扫描会以这些读数取代综合 A–F 等级。已停用的检查标记为未评估；失败的检查标记为未完成。可维护性百分比仅使用实际测量的相关单元，不猜测分母，也不使用未经校准的等级。独立的 debt 和 defend 分数含义保持不变。请参阅输出指南。

选择正确的命令

每条命令回答的问题各不相同。源代码扫描需要 PATH。 verify、suite、defend 和 clean 中方括号括起的路径默认为 当前目录。suite 和 defend 需要目录；verify 和 clean 也接受文件。

问题	命令	检查内容
这个源码树里有哪些问题？	skylos PATH	源文件和项目配置；默认检查死代码，使用 -a 检查所有主要源码分析器
这个分支在 Skylos Cloud 上表现如何？	skylos cloud [PATH]	运行所有主要源码分析器，然后上传发现的问题，并打印该分支的质量门结果及一个链接
Agent 真的完成了这个分支吗？	skylos done --base main	检查该分支自与 main 的合并基点以来的更改：Skylos 会运行测试（自动检测 pytest；其他运行器需要在 [tool.skylos.done] 中设置 test_command），并将测试、测试设置和 CI 步骤与基准进行比较；然后将凭证写入 .skylos/receipts/
此项更改涉及哪些内容，我应该先阅读什么？	skylos done map --base main	列出自合并基点以来每个有更改的 Python 或 TypeScript/JavaScript 函数，包括新旧代码、新增和移除的调用、调用方以及移除的安全检查；根据代码计算，因此相同的提交会生成相同的映射
这段代码是否包含 AI 代码错误？	skylos verify [PATH]	对所选文件或目录树进行 AI 缺陷检查，并单独比较受支持的 Python 工作区更改与 Git HEAD 的行为
是否应该让模型审查静态死代码发现？	skylos agent verify [PATH]	默认使用 LLM；可选仅使用 Jev 或使用 Jev 加 LLM 审查
综合仓库套件会报告什么？	skylos suite [DIRECTORY]	静态分析、技术债务、AI 防御和来源信息；默认仅报告本地发现的问题
Agent 实现是否具有部署防护机制？	skylos defend [DIRECTORY]	识别 Python 和 TypeScript/JavaScript LLM 集成；需要阈值标志或策略才能启用门禁
Skylos 可以移除哪些 Python 死代码？	skylos clean [PATH] --dry-run	Python 导入项/函数清理候选项；--dry-run 绝不会写入文件
这个本地 GPU 构建能否在我们要部署到的机器上运行？	skylos preflight [ARTIFACT]	本地构建文件或目录以及 .skylos/gpu-targets.yml；OCI 引用仅用于标识，在 CLI 中返回 UNKNOWN
此容器映像中有哪些漏洞？	skylos image scan IMAGE@sha256:<digest> --platform os/arch	使用单独安装的 Trivy 扫描远程镜像仓库映像；--fail-on 会将发现的问题设为门禁条件

运行 skylos --help 查看此命令选择器，运行 skylos <command> --help 查看单个命令的帮助， 运行 skylos commands 查看命令族映射。

报告命令的门禁和网络行为各不相同：

• image scan 要求在可信的 PATH 中安装 Trivy，并使用 Trivy 的远程映像 源，因此必须已具备访问镜像仓库的网络连接和任何所需的镜像仓库凭据。 如果不使用 --fail-on，扫描完成后即使报告了漏洞也会以 0 退出。
• suite 在本地进程中运行，除非设置了 --upload，否则不会上传；但其依赖项扫描 可能会查询 OSV。发现的问题仅供报告：无论问题数量多少，命令都会以 0 退出。 操作或输出失败时会以非零值退出；--upload 也可能因上传失败或 Cloud 质量门而失败。
• defend 默认仅报告防护机制相关发现。使用 --fail-on、--min-score 或显式策略中的 门禁设置后，它会启用门禁。
• 如果未使用 --dry-run 或 --apply，clean 会进入交互模式，并可能在最终确认后写入文件。 当前的代码转换工具支持 Python 导入项和函数。即使单个编辑操作打印失败， 应用操作仍会以 0 退出，因此请检查完成输出。
• done 通过时以 0 退出，阻塞性检查失败或未完成时以 1 退出，Skylos 无法运行时以 2 退出（例如，尚未获取基准提交）。它会从基准提交读取设置，因此 更改不能放宽自身的门禁条件。

60 秒快速开始

pip install skylos
skylos .            # find problems; your code and findings stay on your machine
skylos cloud        # optional: track results per branch on Skylos Cloud
skylos cicd init    # add a Skylos check to every pull request

完整流程就是这样。当 skylos . 发现问题时，它会在结束时指出下一条命令。 skylos cloud 会运行所有检查、显示检查结果、上传结果，并打印此分支的质量门禁及其链接：

✗ Quality gate on feat/login: FAILED (was PASSED on 24 Oct 15:38 UTC, 1ba9895) · 1 critical security issue
  Open: https://skylos.dev/dashboard/projects/<project>?branch=feat%2Flogin
  Next: fix the issues behind the failed gate, then run skylos cloud again.

首次运行时，浏览器会打开，让你登录并为此仓库选择项目。它会发送检查结果，其中包含文件路径和最多 7 行的代码片段（密钥不包含代码片段）、分支、提交、每个被标记代码行对应的 Git 作者邮箱，以及函数和类的映射（名称、文件、行数、大小，以及调用关系）。不会发送你的仓库。即使 Skylos Cloud 门禁未通过，命令仍会以 0 退出；添加 --gate 可让命令以 1 退出（在 CI 中使用此选项）。要通过门禁，无需密钥：修复未通过门禁的问题即可。其他 Cloud 命令请参阅 Skylos Cloud。

在 4.47.2 之前，pip install skylos 还会安装一个 Dart 解析器，该解析器需要从源代码构建，并需要 C 编译器。从 4.47.2 开始，Dart 支持改为可选的 skylos[dart] 扩展。如果安装因缺少编译器而失败，请使用容器映像。

可选的 Rust 加速功能可以从源代码构建。标准安装使用 Python 回退实现。有关加速操作及检查结果可能存在的差异，请参阅构建指南。

默认扫描侧重于死代码。使用 -a 运行所有主要源代码分析器，包括安全、密钥、质量、依赖项和 AI 缺陷检查：

skylos . -a

检查某个分支（通常是 AI Agent 的分支）是否真的已完成：

skylos done --base main

skylos done 会将分支与 main 上的合并基点进行比较，并运行你的测试。它会标记被删除或跳过的测试、放宽的测试设置和 CI 测试步骤、被关闭的 lint 或类型检查，以及专门针对测试进行特殊处理的代码；它还会提示分支中没有调用方的代码（包括未触及的文件中的代码），然后将回执写入 .skylos/receipts/。测试失败时，它会在合并基点上重新运行测试，并将每个失败标记为“引入的”或“已存在的”；默认情况下，每个失败都会阻止通过。它会自动运行 pytest；其他测试运行器需要在 [tool.skylos.done] 中添加一行 test_command。所有检查及其限制请参阅 done gate guide。

仅运行有证据支持的 AI 缺陷检查：

skylos . --ai-defects

在 Agent 提交代码供审查前，验证仓库、文件或代码范围：

skylos verify . --file src/app.py --range 40:75 --project-context

对于 . 这样的目录，AI 缺陷扫描会覆盖所选目录树。单独的 behavior 结果会根据 Git HEAD 对受支持的 Python 工作树更改进行建模；它不是 AI 缺陷扫描的范围选择器。对于路径目标，依赖项幻觉检查默认启用，并且可能会查询软件包注册表；使用 --no-dependency-hallucinations 可禁用这些查询。所选文件或代码范围内的高危／严重安全检查结果（category: "security"）和硬编码密钥（category: "secret"，值已隐藏）也会导致验证失败；使用 --no-security 可仅获取 AI 代码判定结果。 交互式终端会显示人工可读报告。重定向 stdout 和使用 -o 会生成带版本号的 JSON 结果。

skylos verify 架构版本 2 会返回 pass、fail 或 incomplete。incomplete 表示无法确立所请求的证明，例如缺少本地 TS/JS 导入、计算得出的命名空间成员、不受支持的语言本地 API 检查，或 Skylos 无法证明的解析器范围；除非设置 --no-fail，否则命令会以 2 退出。coverage 对象会列出检测到的语言、预期检查、语言支持情况、缺失检查、已完成／已跳过的检查、已检查的引用，以及确定性的跳过原因。已声明的第三方依赖项和已识别的 Node 内置模块不属于本地 TS/JS API 证明的范围；这些引用会计入 out_of_scope_references，不会导致干净的验证变为不完整。未知的裸导入仍需审查。 确定性本地/工作区 API 验证目前涵盖 Python、 TypeScript/JavaScript、Go 和 Java，且不会执行目标代码。PHP、Rust、 Dart、C#、Kotlin、C++ 和 Shell 保留现有的静态分析覆盖范围， 但其本地 API 验证会报告为不受支持，因此不完整。 请参阅 AI 代码验证覆盖范围。

为特定仓库生成代码的真实性创建本地 AI 幻觉契约。skylos verify 会自动发现 .skylos/ai-contract.yml：

skylos contract init
skylos contract inspect
skylos verify .

使用确定性的响应和工具调用场景测试正在运行的 Agent：

skylos agent init
skylos agent test --allow-contract-endpoint

创建包含阈值、忽略项和 vibe 词典扩展的项目配置：

skylos init

创建入门本地规则包：

skylos rules init
skylos rules validate .skylos/rules/local.yml
skylos rules list --json
skylos rules list cross --json
skylos rules list --packs --json
skylos cache stats

使用 --quality 或 -a 进行扫描时，会应用从被扫描文件所在位置到仓库根目录之间 .skylos/rules/ 文件夹中的所有 .yml/.yaml 规则包（同一规则 ID 以最近的规则包为准）。在 PR CI 中，与 [tool.skylos] 一样，规则包来自基准分支，因此拉取请求无法删除或编辑其自身门禁所运行的规则。无法读取的规则包会被跳过，并显示指出该规则包名称的警告。

使用 GitHub Actions 为拉取请求设置门禁。无需 Skylos 账户或令牌：

git checkout -b add-skylos-gate
skylos cicd init --no-upload
git add .github/workflows/skylos.yml
git commit -m "Add Skylos pull request gate"
git push -u origin add-skylos-gate
gh pr create --fill

生成的工作流会审查拉取请求中的变更行，并在发现你的测试时添加一个 skylos done 作业。除非使用 --no-upload，否则它还会通过 GitHub OIDC 上传到 Skylos Cloud：向默认分支推送，以及向该分支发起的拉取请求。随后，Cloud 会在列表中显示这些上传，并附带其检查结果和评论。拉取请求会作为不可信数据在没有凭据的作业中进行扫描，并由从不检出其文件的作业上传。只有在仓库安装 Skylos GitHub App 后，才能成功上传。 你的第一个 Skylos 门禁拉取请求会在约 8 分钟内带你完成整个流程，包括将检查设为必需项。

在 GitLab CI、Jenkins、Bitbucket Pipelines、Azure Pipelines 或 CircleCI 上，同样的 skylos cicd init 会为相应 CI 设置拉取请求门禁；请参阅 在任意 CI 上使用 Skylos。

门禁（skylos . --gate、skylos cicd gate 和生成的工作流）遇到任何严重安全问题、任何密钥，以及任何严重 AI 代码问题时都会失败，例如导入 PyPI 上不存在的软件包（SKY-D222），或调用从未定义或导入的函数（SKY-L012）。其他发现只有超过数量限制时才会导致失败。在 pyproject.toml 的 [tool.skylos.gate] 下更改限制：

[tool.skylos.gate]
max_high = 5          # high-severity security issues allowed
max_quality = 10      # quality issues allowed
max_ai_defects = 10   # AI-code issues allowed (defaults to max_quality)
# AI-code issues at these severities fail the gate whatever max_ai_defects
# allows. Add "HIGH" to block more; [] turns the rule off.
block_ai_defect_severities = ["CRITICAL"]

max_ai_defects 和 block_ai_defect_severities 是单独的检查；只要其中一项检查失败，门禁就会失败。在拉取请求中，skylos cicd gate --diff-base 会从基准分支读取此策略，因此拉取请求无法为自己关闭规则。从 Skylos Cloud 同步的门禁策略会替代仓库中的 [tool.skylos.gate] 部分，随后门禁会检查 Cloud 门禁所检查的内容：其模式（零个新增问题、按类别限制、按严重程度限制，或两者兼有）及其限制，结果行会显示这些限制。Skylos Cloud 只统计新增问题，因此请使用 skylos . -a --gate --diff origin/main 检查分支；完整扫描会打印一行说明。skylos sync pull 写入的 .skylos/config.yaml 会应用于 --diff 门禁，但前提是它尚未提交；仅在分支上提交的副本则不会生效。关闭 Cloud 门禁后，会使用内置限制。max_critical、max_secrets 和 fail_on_critical = false 无法放宽严重问题和密钥规则；当它们试图放宽规则，或者 rules 条目不是规则 ID 时，门禁运行会打印警告。 每次门禁运行都会以一行结论及其原因结束： Quality Gate: PASSED、Quality Gate: FAILED（退出码为 1），或 Quality Gate: INCOMPLETE — could not decide (exit 2)，表示必需的分析 未能完成，例如依赖扫描无法解析某个锁文件。 每条原因都会指出未通过的检查、遗漏的文件或依赖项数量，以及需要进行的更改。无法解析的文件会作为覆盖率警告显示在结论下方，不会导致运行停止：评估限值时会排除这些文件（在 [tool.skylos.gate.coverage] 下设置 require_complete = true 可改为失败）。 --format json 会在顶层 gate 对象中包含相同的结论；简洁、LLM、GitHub 和 GitLab 输出会将其打印到 stderr。请参阅 退出码和未完成的分析。

需要更多命令？请阅读 CLI 参考。

检查 Agent 的每次编辑（Claude Code、Codex、Cursor）

安装本地钩子，让 Agent 工作时就接受检查，而不是等到完成后：

skylos agent install-hooks            # Claude Code (.claude/settings.json)
skylos agent install-hooks --codex    # Codex (.codex/hooks.json)
skylos agent install-hooks --cursor   # Cursor (.cursor/hooks.json)

• **每次编辑后：**仅验证更改的行（安全、机密信息、AI 代码错误），并告知 Agent 需要修复的内容。
• **读取文件前：**阻止读取包含硬编码机密信息的文件。
• 安装软件包或单次运行前（pip、uvx、npx、 pnpm dlx、bunx、go run pkg@v 等）：阻止幻觉生成或拼写仿冒的软件包，并在无法验证时要求确认后再安装（git 和 URL 来源、未知注册表、查询失败）。
• **运行 git 命令前：**阻止使用 --no-verify、HUSKY=0 以及其他绕过仓库 git 钩子的方式。
• **停止时：**如果 Agent 引入的问题仍未解决，就阻止其宣告“完成”。

钩子会在检查失败时放行，但绝不会静默处理：如果 Skylos 出错，Agent 和你都会收到通知，说明该操作未经检查便已获准；stop 还会报告有多少操作未经检查。日志写入 .skylos/hook.log，并与现有钩子合并。--uninstall 只会移除 Skylos 条目。请参阅 Agent 循环钩子，了解其约定、延迟和限制。

在 Cursor 中，检查结果会在 stop 时显示，而不是在每次编辑后显示。这些钩子不是沙箱：它们会检查编辑、文件读取和软件包安装，但不会检查每条命令。请参阅钩子不会做什么。

常见工作流

目标	命令	结果	更多详情
首次死代码扫描	skylos .	查找未使用的函数、类、导入、文件，以及框架入口点错误	死代码文档
确定性清理预览	skylos clean . --dry-run --types import,function --confidence 80	显示计划移除的 Python 导入和函数，不会写入文件；添加 --apply 即可编辑文件	死代码文档
安全与质量审计	skylos . -a	增加危险流程、机密、依赖、配置、质量和 AI 缺陷检查	安全文档
综合代码仓库报告	skylos suite .	报告静态检查结果、技术债务、AI 防御和来源信息；SCA 可查询 OSV，且仅有检查结果时退出码为 0	CLI 参考
可选 Python lint	pip install "skylos[lint]" && skylos lint .	通过 Skylos CLI 运行 Ruff，使用其原生配置、输出、修复和退出码	Python lint
Agent 分支完成检查	skylos done --base origin/main	运行测试并标记已删除、跳过或弱化的测试、放宽的测试设置和 CI 测试步骤、被静默的检查及仅用于测试的特殊情况；写入回执	完成门禁
供审查的变更图	skylos done map --base origin/main	展示每个变更的 Python 或 TypeScript/JavaScript 函数的新旧代码、新增和移除的调用、调用方及其是否已更新、移除的身份验证检查、破坏性签名变更，以及应优先阅读的变更；使用 --format json 供审查 Agent 使用	变更图
MCP 变更图	change_map MCP 工具	在审查 Agent 读取差异前，以 JSON 格式提供变更图。需要免费的 Skylos API 密钥（SKYLOS_API_KEY）。skylos done map 无需密钥	变更图
需要人工批准的风险	skylos cicd risk-review --base origin/main	列出已删除或弱化的测试、移除的身份验证检查、新增或变更的依赖、弱化的 CI、被静默的检查、新增的机密、护栏设置编辑、迁移变更和超大型差异。作为必需的 GitHub 检查（skylos cicd init --risk-review）时，必须由拥有写入权限的人批准头部提交，否则检查失败；机器人批准不计入	风险审查
PR 门禁	skylos cicd init --no-upload	为 CI 设置拉取请求门禁。在 GitHub Actions 上，会写入一个工作流来拦截拉取请求，并在测试可运行时运行 skylos done；去掉 --no-upload 还会通过 GitHub OIDC 将默认分支扫描结果上传到 Skylos Cloud，且必须先在代码仓库中安装 Skylos GitHub App，否则该任务会失败。GitLab CI、Jenkins、Bitbucket Pipelines、Azure Pipelines 和 CircleCI 会配置适用于相应 CI 的门禁	首个受门禁保护的 PR，在任意 CI 上使用 Skylos
GitLab 合并请求报告	skylos . --format gitlab -o gl-code-quality-report.json	导出原生 Code Quality 报告，供 GitLab CI 工件使用	GitLab Code Quality
离线依赖 SBOM	skylos sbom . -o sbom.cdx.json	将支持的已记录依赖列为 CycloneDX 1.6 JSON，不发起网络请求	依赖扫描
SPDX SBOM + 许可证策略	skylos sbom . --format spdx-json / license_deny = ["GPL-*"]	SPDX 2.3 JSON，包含声明的许可证；-a 扫描会通过 SKY-SCA-LIC001 标记被禁止的许可证	许可证合规
已签名判定部署门禁	skylos verify-verdict verdict.json --commit "$SHA" --repository github.com/org/repo --require-repository-verified --require-trusted-upload --max-age 7d --require-passed	离线验证 Skylos Cloud 检查判定（Ed25519 DSSE、in-toto/SLSA），并确保其是针对该提交和代码仓库的近期策略通过结果，否则失败；需要 skylos[verdict]	验证已签名判定
易读的终端报告	skylos . --format pretty	按文件分组显示检查结果，并附带严重性徽标、代码片段和可复制的 file:line 位置	CLI 输出模式
单条规则审查	skylos . --select SKY-L012 --format concise	启用匹配的分析器类别，并仅报告这条规则的完整消息	CLI 输出模式
可选择的终端问题分类	skylos . --tui	打开由键盘操作的类别列表、检查结果列表和详情窗格	CLI 输出模式
IDE/测试脚本输出	skylos --format concise src/test.py	输出未截断的 file:line RULE_ID message 检查结果；存在检查结果时以非零状态退出	CLI 参考
循环内 AI 代码验证	skylos verify . --file src/app.py --range 40:75	报告少量幻觉辅助函数、未完成代码、过时引用、已禁用控件以及 API/依赖幻觉；重定向输出或使用 -o 输出时采用 JSON 格式	AI 功能
AI 幻觉契约	skylos contract init && skylos verify .	自动发现 .skylos/ai-contract.yml，并根据代码仓库专属符号、依赖、API、路由保护和测试要求验证生成的代码	AI 幻觉契约
变更行审查	skylos . -a --diff origin/main	聚焦当前工作，而非历史债务。即使变更仅删除了装饰器行，移除的安全控制（SKY-L021，例如已删除的身份验证装饰器）仍会报告	质量门禁文档
对比现有扫描器	skylos compare . --against incumbent.sarif	与当前扫描器并行运行 Skylos，并生成感知修订版本的评分卡：当前重叠项、按类别划分的原始独有检查结果，以及位于有证据支持的未使用符号中的符合条件检查结果；不会替换当前门禁	扫描器对比
运行时辅助死代码检查	skylos . --trace	使用运行时跟踪信息减少动态代码误报	智能跟踪
本地规则包	skylos rules init	创建 .skylos/rules/local.yml 框架，其中包含项目专属 YAML 检查，--quality 和 -a 扫描会应用这些检查	自定义规则
安全 Agent 快速扫描	skylos agent security-quick .	一次性大模型安全审计；兼容性别名，等同于 skylos agent scan . --security	AI 功能
安全 Agent 深度扫描	skylos agent security-deep .	三阶段安全工作流，包含威胁模型上下文、静态威胁跟踪、发现与验证，以及修复交接	AI 功能
AI 辅助审查	skylos agent scan .	静态分析，以及可选的大模型审查和修复建议	AI 功能
Agent 工具框架回放	skylos agent replay .skylos/runs/<run-id>	验证并汇总已保存的 Agent 验证阶段、工具调用、决策和预算	Agent 工具框架工件
运行时 Agent 行为测试	skylos agent init && skylos agent test --allow-contract-endpoint	根据版本化契约检查最终响应、工具选择、明确拒绝和来源 ID	Agent 行为测试
基于验证的修复	skylos agent remediate .	扫描并修复支持的检查结果，然后重新扫描，并在可用时记录验证测试元数据	AI 功能
Agent 循环钩子	skylos agent install-hooks [--codex|--cursor]	验证 Agent 的每次编辑，阻止读取机密、安装虚构的软件包和绕过 Git 钩子；对于无法验证的安装会先询问，并在新问题仍未解决时阻止标记为“完成”	Agent 循环钩子
面向 Agent 的项目标准	skylos agent install-standards --enforce SKY-L002	为 Codex、Claude Code 和 Cursor 提供项目技能，并选择可量化的质量规则用于钩子和 CI 检查	项目标准
MCP Agent 验证	verify_change MCP 工具	让 Claude、Cursor 和其他 MCP 客户端使用与 skylos verify 相同的架构，验证已编辑文件或范围。需要免费的 Skylos 项目令牌（SKYLOS_API_KEY）。skylos verify 和 Agent 循环钩子无需令牌	MCP 服务
大模型集成清单	skylos discover .	映射 Python 和 TypeScript/JavaScript 中可识别的大模型调用、Agent 工具、提示词位置和输入来源	Agent 验证
部署前 Agent 验证	skylos defend . --format md -o evidence.md	验证 Agent 护栏，评估 OWASP LLM/Agentic 覆盖情况，并生成经过证明的证据报告	Agent 验证
Agent 验证 CI 门禁	skylos defend . --fail-on critical	阻止部署未受保护的大模型集成；使用 --format sarif 可生成供代码扫描使用的 SARIF	Agent 验证
MCP Agent 预检	verify_agent MCP 工具	让编码 Agent 静态验证其构建的 Agent，并显示评分、未通过的检查和证明摘要。需要免费的 Skylos 项目令牌（SKYLOS_API_KEY）。skylos defend 无需令牌	MCP 服务
技术债务分类	skylos debt .	排定热点和债务趋势	技术债务

Skylos 能检测的问题

类别	示例	重要性
死代码	未使用的函数、类、导入、包入口点、路由处理程序	在不破坏动态框架的情况下减少维护成本
安全漏洞	SQL 注入、XSS、SSRF、路径遍历、命令注入、不安全的反序列化	在代码进入主分支前捕获可被利用的流程
密钥	API 密钥、令牌、私有凭据、高熵字符串	防止凭据通过提交和 PR 泄露
CI/CD 工作流	GitHub Actions 和 GitLab CI 中的危险触发器、未固定版本的 Actions/includes、权限过宽的令牌、OIDC 误用、缓存投毒、可变镜像	在发布任务运行前降低 CI/CD 供应链风险
边缘部署配置	Docker Compose 特权设备访问、主机网络、systemd root 服务、权限过宽、缺少沙箱	捕获由仓库控制的设置，避免应用程序漏洞演变为设备遭入侵
Kubernetes 部署暴露风险	显式对外的 Ingress 路径到达敏感的 FastAPI/Flask 路由，但缺少部署所需的保护措施；Flask --debug；或应用服务器使用 --reload	仅当资源位于同一个渲染后的配置包中，且所有部署边缘都能明确解析时才报告
GPU 发布兼容性	源码／构建契约不匹配，以及构建产物身份、所选 CUDA 架构、打包的运行时和集群检查	尽早捕获声明意图中的错误，并在发布前验证生成的本地产物
质量回归	复杂度、深层嵌套、重复分支、过长函数、不一致的返回值	防止 AI 辅助重构引入脆弱代码
AI 代码错误	幻觉出的安全调用、缺少装饰器、未完成的存根、已禁用的控制项、使用虚构 API 的真实软件包、不可能存在的 npm/Go 版本	在常见的幻觉或未完成代码路径进入审查前将其捕获
LLM 应用风险	不安全的工具使用、提示词注入风险、缺少输出验证、缺少速率限制	帮助团队在发布 AI 功能时加入防护措施

请参阅完整的规则参考。

依赖项许可证

skylos sbom . 会将声明的依赖项许可证写入 CycloneDX；skylos sbom . --format spdx-json 会写入 SPDX 2.3 SBOM。许可证信息离线来源于锁文件和已安装软件包的元数据。对于未知或含糊的值（例如 BSD），会保留为 NOASSERTION，而不会猜测。使用 --license-lookup 可选择查询 deps.dev。若要在 -a 扫描中阻止特定许可证，请设置策略：

[tool.skylos]
license_deny = ["GPL-*", "AGPL-3.0-only"]
license_severity = "HIGH"

违规项会报告为 SKY-SCA-LIC001。请参阅许可证合规。

为编码 Agent 提供项目规范

创建 .skylos/standards.md，写入希望 Agent 遵循的指导：

# Coding standards

- Keep functions focused and handle exceptions explicitly.
- Add a focused test when changing behavior.

然后安装项目技能，并选择要强制执行的任意 Skylos 质量规则：

skylos agent install-standards --enforce SKY-L002
skylos agent install-hooks --codex   # use --cursor for Cursor, or omit for Claude Code
skylos agent check-standards .       # run this project-wide check in CI

安装程序会为 Codex、Cursor 和 Claude Code 写入 SKILL.md 文件。Agent 技能提供指导；钩子和项目范围的检查则会强制执行所选的内置质量规则。有关生成的文件、规则选择和覆盖范围限制，请参阅项目规范。

在发布前验证 AI Agent

运行时防护措施是 WAF；Skylos 是 SAST。skylos discover 会扫描 Python 和 TypeScript/JavaScript，查找可识别的 LLM 集成（提供商 SDK、Agent 框架，包括 OpenAI Agents SDK、Claude Agent SDK 和 Google ADK、MCP 服务及其工具、直接调用 LLM API 或 OpenAI 兼容网关的 HTTP 请求，以及 Agent 工具、提示词位置和输入 来源）。skylos defend 会在本地进程中确定性地检查这些已检测到的 集成周围的防护措施，整个过程中不会使用模型。默认情况下，它会生成证据报告；只有在阈值 标志或策略提供了门禁标准时，才会成为 CI 门禁。

skylos discover .                               # inventory LLM integrations and agent tools
skylos defend .                                 # score guardrails (13 weighted checks)
skylos defend . --format md -o evidence.md      # auditor evidence report + attestation
skylos defend . --format sarif -o defend.sarif  # GitHub code scanning upload
skylos defend . --fail-on critical              # CI gate: exit 1 on critical gaps
skylos defend . --owasp-framework agentic       # report against OWASP Agentic ASI Top 10

这些命令不会检查其他语言中的集成。如果发现未找到受支持的集成， defend 会返回空清单；不要仅凭由此产生的评分，就认定不受支持或 未识别的 Agent 实现具有防护措施。

它会逐项集成验证：危险输出接收端（eval/exec/subprocess）、 Agent 工具范围和类型化架构、提示词注入暴露风险（分隔符、 不可信输入路径、RAG 上下文隔离）、输出验证、PII 过滤和模型固定；此外还会单独评估运维检查（日志记录、成本控制、速率 限制），因此这些检查不会抬高安全评分。

• OWASP 映射： LLM Top 10（2024/2025）和 Agentic ASI Top 10（2026）。
• 证据报告（--format md）： 集成清单、各项检查 结果、OWASP 覆盖情况、监管框架证据（EU AI Act、NIST AI RMF、ISO/IEC 42001——仅为“支持相关要求的证据”映射，绝不声称合规）， 以及修复附录。
• 证明： JSON/md/SARIF 报告包含可复现的 SHA-256 摘要，涵盖 文件内容、策略、插件集、集成清单、评分和完整检查证据——在同一代码树上 使用相同标志和 Skylos 版本重新运行，摘要必须一致。
• 原生支持 CI： skylos cicd init --defend 会生成 GitHub Actions 工作流步骤，skylos-defend pre-commit 钩子会在本地进行门禁检查，并且 Actions 会自动将评分摘要写入 $GITHUB_STEP_SUMMARY。
• 策略即代码： skylos-defend.yaml 固定门禁阈值和严重性 覆盖项（--policy）。
• 原生支持 Agent： verify_agent MCP 工具让编码 Agent 验证自己构建的 Agent——这是确定性验证，而不是让 AI 检查 AI。

静态部署前验证可补充运行时控制（网关、 策略引擎、人工审批流程），但不能取代它们。完整指南： docs/agent-verification.md。

测试 Agent 行为

Skylos 将生成代码的真实性、静态 Agent 防护措施和观察到的 运行时行为分别处理：

命令	验证问题
skylos verify	Agent 生成的代码是否有效且非幻觉？
skylos defend	Agent 实现是否包含必需的防护措施？
skylos agent test	正在运行的 Agent 是否按照其约定行事？

创建 .skylos/agent-test.yml，然后测试一个运行中的 OpenAI 兼容端点：

skylos agent init
skylos agent test --allow-contract-endpoint

或者在不发起网络请求的情况下评估已捕获的证据：

skylos agent test --observations agent-observations.json
skylos agent test --observations agent-observations.json \
  --format json --output agent-results.json

版本 1 会确定性地检查准确的响应子字符串、必需、允许和禁止的 工具调用、工具参数和调用顺序、最大调用次数、明确拒绝以及明确的来源 ID。缺失的类型化证据会标记为 incomplete，绝不会判为 pass；退出码分别为 0（通过）、1（违规）和 2 （不完整/无效）。工具选择检查和最终答案来源 ID 检查是分开的 单轮场景：Skylos 会记录可在本地重放的证据，但绝不会执行目标 Agent 返回的工具。离线观察结果会标记为 未经验证的测试样例，而非运行时证明。

对于经过身份验证的远程端点，请在可信的 CLI 调用中指定目标地址和密钥：

skylos agent test --endpoint https://agent.example.com/v1/chat/completions \
  --allow-remote --auth-env MY_AGENT_API_KEY

完整指南：docs/agent-behavior-testing.md。

Skylos 的定位

Skylos 并非要取代所有专业扫描器，而是一款以本地优先的代码仓库和 PR 检查工具，将多种常见审查检查整合到一个 CLI 中。

• 感知框架的死代码检测： FastAPI、Django、Flask、pytest、 SQLAlchemy、Next.js（App/Pages Router 文件和元数据路由）、React、 Laravel（自动发现命令、监听器、组件、工厂、数据填充器）、 Drupal（扩展 YAML 中列出的类、发现的插件、OOP 钩子、 .module/.install/.inc/.theme 文件中的过程式钩子、更新后 函数）、 工具配置文件、包入口点和常见插件模式。
• 面向 PR 的输出： 差异扫描、CI 阈值、GitHub 注释，以及用于现有问题的基线。
• 本地优先运行： 核心分析在本地执行，不会上传源代码或调用大模型。依赖项/CVE 检查可以查询 OSV 或包注册表，直接扫描容器则会通过 Trivy 联系注册表。 请参阅哪些内容会离开你的设备。
• AI 辅助变更审查： 检查生成或编辑的代码是否移除了验证、身份验证、日志记录、CSRF 防护、速率限制或超时设置，以及是否存在对真实软件包 API 的臆测等其他防护措施问题。
• Agent 循环验证： skylos verify 和 MCP verify_change 使用版本化结果架构来识别 AI 代码的可信度、安全性和机密信息问题，让编码 Agent 能在人类看到变更前自行纠正。CLI 会在终端中生成供人阅读的报告，并在输出被重定向或使用 -o 写入时生成 JSON。
• 基于证据的 AI 缺陷检测： --ai-defects 和完整扫描会将严格的 AI 代码失败检查归入 ai_defects，包括虚构引用、伪造的软件包 API、不存在的软件包、不可能的依赖版本，以及被削弱的测试断言。 类别/标签为 ai_defect；为兼容抑制规则和基线，部分规则会有意保留历史 SKY-L 或 SKY-D ID，而新的 AI 缺陷专用检查则使用 SKY-A。
• 基于验证的修复： 通过重新运行分析来检查安全修复；受支持的问题还可包含定向回归测试证明元数据。
• 项目专属规则： 添加本地 YAML 规则，并通过配置扩展提示词、凭据、敏感文件和超时字典。
• 统一命令界面： 死代码、安全、机密信息、依赖项、质量、技术债务、Agent 审查和部署前 Agent 验证命令共用同一个 CLI。

数据会离开你的设备吗

除非你运行的命令或标志表明会与 Skylos Cloud 通信，否则 Skylos 不会向 Skylos Cloud 发送任何内容： skylos cloud、--upload、skylos login、whoami、project、sync、credits、upload、ingest claude-security、verify-verdict、feedback 或 --verify 扫描选项。仅有令牌（SKYLOS_TOKEN、已保存的 skylos login、CI OIDC 令牌）不会导致命令上传扫描、发现项或运行摘要。没有更新检查，也没有分析数据收集。

• 只有在使用 --upload 时，skylos agent scan、agent verify、agent remediate 和 agent remediate --standards 才会发送运行摘要：发送一个 POST /api/agent-runs，其中包含 command、每条命令的计数、model、provider、duration_seconds、commit_hash、branch、actor 和 status。actor 是 SKYLOS_ACTOR、CI 报告的用户，或 HEAD 提交的作者；如果都没有，则为 null；绝不会是你的操作系统用户名。不会发送源代码、路径、发现项文本、提示词或模型输出。
• 有三种情况会在没有此类命令的情况下向 Skylos Cloud 发送信息，且都不会发送代码或发现项：如果能找到令牌，扫描会下载你的 Cloud 自定义规则（设置 SKYLOS_CUSTOM_RULES='[]' 可跳过）；skylos doctor 会检查你的额度余额（设置 --format json 可跳过）；使用 SKYLOS_API_KEY 启动的 MCP 服务每 15 分钟检查一次密钥，并为付费工具扣除额度。
• skylos feedback 本身不会发出请求：它会在浏览器中打开 skylos.dev 上的表单（或使用 --github 时打开 GitHub 的问题反馈表单）。页面地址中包含 Skylos 版本、操作系统、Python 版本和最后一次失败的命令，其中路径和密钥会经过屏蔽；只有点击“发送”后才会发送你的消息。
• 在其他主机上查询软件包时，会发送软件包名称和版本，绝不会发送源代码：依赖项检查会查询 OSV；对于不存在的软件包，则会查询 PyPI、npm、Go 代理和 JSR（默认在 skylos done、skylos verify、agent scan、agent pre-commit 和 Agent 钩子中启用）。依赖项检查还可能获取 GitHub 修复提交；如果设置了 GITHUB_TOKEN，则会使用它。LLM 命令会向你配置的模型提供商发送代码摘录；skylos cicd review 会通过 gh 发布 PR 评论。

每个请求、触发条件及关闭方式： docs/privacy-and-network.md。

Agent Harness 产物

skylos agent verify . 和 skylos agent test 会在 .skylos/runs/<run-id> 下记录可重放的产物，并在表格输出中打印运行目录。JSON 输出会在 harness 键下包含相同的 Harness 摘要。

使用 skylos agent replay .skylos/runs/<run-id> 可验证和检查已保存的运行记录，且不会调用 LLM。如果其他 Agent 或 CI 作业需要机器可读的状态，请添加 --format json。有效的重放以 0 退出；无效或损坏的产物集以 1 退出，并附带问题代码。重放输出包含 schema_version，以便 CI 和 Agent 检测产物契约的变化。 重放会检查内部一致性和损坏情况；产物未经过签名，因此无法证明运行目录未被有能力重写整个目录的行为者篡改。

每个运行目录包含：

• events.jsonl：按时间顺序记录运行、阶段和工具调用事件。
• state.json：完整的可观测状态，包括阶段、工具调用、决策和预算使用情况。
• summary.json：精简的状态、计数、预算和产物路径。
• behavior-results.json：规范化的运行时断言、来源信息、覆盖率，以及 skylos agent test 运行的摘要绑定证据报告。

当前的 Harness 状态可观测且经过重放验证，但目前尚不支持通过它继续被中断的验证运行。

安装选项

# Core static analysis
pip install skylos

# LLM-powered agent workflows
pip install "skylos[llm]"

# Ruff Python linting through `skylos lint`
pip install "skylos[lint]"

# Ed25519 verification for `skylos verify-verdict`
pip install "skylos[verdict]"

# Dart analysis, 4.47.2 and later (builds the Dart parser from source; needs a C compiler)
pip install "skylos[dart]"

# All published optional extras
pip install "skylos[all]"

容器镜像：

docker pull ghcr.io/duriantaco/skylos:latest
docker run --rm -v "$PWD":/work -w /work ghcr.io/duriantaco/skylos:latest . --json --no-provenance

未指定限定标签的镜像使用 Python 3.14。也会发布适用于 Python 3.11 至 3.14 的运行时专用标签，这样容器扫描就能与本地或 CI 解析器完全匹配：

docker run --rm -v "$PWD":/work -w /work ghcr.io/duriantaco/skylos:latest-python3.13 . --json --no-provenance

如果无法解析某个 Python 文件，Skylos 会将其标记为未分析、标记覆盖率不完整，并报告其他所有发现；绝不会将该文件视为干净。退出代码根据已分析的代码决定；使用 --strict 时则退出代码为 2，如果大部分代码无法分析，也会以 2 退出。请参阅退出代码和不完整分析。

有关源码安装、容器用法和可选依赖项，请参阅安装。

配置 Vibe 检查和入口点

运行 skylos init，将以下部分添加到 pyproject.toml：

[tool.skylos]
exclude = ["node_modules", "dist"]

[tool.skylos.vibe]
extra_phantom_names = ["verify_enterprise_auth"]
extra_phantom_decorators = ["tenant_admin_required"]
extra_credential_names = ["tenant_signing_secret"]
extra_network_timeout_calls = ["vendor_sdk.fetch"]

[tool.skylos.dead_code]
entrypoints = []

[[tool.skylos.dead_code.entrypoints]]
type = "method"
name = ["create", "pre_hook", "post_hook"]
parent = { name = "Main", base_classes = ["Application"] }
path = "src/**"
reason = "project framework lifecycle hook"

[tool.skylos.contribution]
collect_local_signals = false
contribute_public_corpus = false
structural_signatures_only = true
include_source = false

LLM 提示词模板不会从代码库中读取：使用 --prompt-template KIND=PATH 将可信文件传递给 skylos agent scan、agent audit、agent security-quick 或 agent security-deep（KIND 为 security、quality、security_audit 或 review）。模板会扩展 Skylos 内置提示词；不会替代仅限 JSON 的输出约定或不可信代码安全规则。Vibe 词典扩展可让团队向 Skylos 说明本地的假认证助手、项目凭据名称、敏感文件，以及必须设置超时的网络调用。 死代码入口点可让团队通过针对类型、名称、路径、装饰器、基类和父类的精确规则，将专有框架类、生命周期方法和通过装饰器注册的函数标记为活跃代码。 规则必须包含 name、decorators、base_classes 或 parent 等符号选择器；path 和 module 只能缩小匹配范围。 贡献信号默认关闭；启用后，Skylos 会在 .skylos/contribution/ 下记录本地结构化的接受／忽略／学习事件，不包含原始源码。

设置的来源。 Skylos 会从扫描路径向上遍历至代码库根目录（包含 .git 的文件夹），并在每个文件夹中读取以下文件中第一个存在的文件：

1. .skylos.toml
2. skylos.toml
3. 包含 [tool.skylos] 表的 pyproject.toml（不包含该表的 pyproject.toml 会被跳过，因此不会再遮蔽其上级的设置）

skylos.toml 在顶层使用与 [tool.skylos] 相同的键，因此 TypeScript、Go 和 Java 代码库无需 pyproject.toml：

# skylos.toml
exclude = ["generated", "dist"]

[gate]
max_security = 0

[done]
test_command = "npm test"

在单体代码库中，向上遍历时找到的每个文件都会生效：代码库根目录是基准，每个键以最靠近扫描文件夹的文件为准。包级文件中设置的键会替换根目录的值（列表会被替换，而非拼接）；[gate] 等表则会逐键合并。在包级文件中设置 root = true，即可忽略其上方的所有设置。skylos doctor 会按从最近到最远的顺序列出正在使用的文件，以及被忽略的文件。在 PR CI 中，设置仅取自基准提交，并遵循相同规则；skylos done 会将新增或编辑的 skylos.toml 报告为 Skylos 设置变更（SKY-A114）。[done] 和 [approval] 设置从代码库根目录的文件中读取。

若要使用单个文件而非自动发现，请传入 --config-file PATH 或设置 SKYLOS_CONFIG_FILE；该文件可以使用 [tool.skylos]、[skylos]，或（当文件名为 skylos.toml 时）顶层键。已同步的 Skylos Cloud 策略优先级受保护，不受代码库控制的配置影响。顶层 [tool.skylos].exclude 列表适用于主扫描以及 skylos debt、skylos clean 等命令；传入 --exclude 可添加仅对命令生效的排除项，或传入 --include-folder 以覆盖对文件夹的排除。

完整扫描会跳过生成文件和供应商文件（Django 迁移文件、static/**/lib/**、*.min.js、*.min.css、带有供应商库横幅的文件），并在一行输出中说明跳过的数量。在 [tool.skylos] 下设置 include_generated = true（或传入 --include-generated）即可扫描这些文件；请参阅完整扫描会排除哪些内容。

语言支持

语言	死代码	安全性	质量	本地 API 证明（verify）	备注
Python	是	是	是	支持	覆盖最全面；具备框架感知静态分析和可选追踪
TypeScript / JavaScript	是	是	是	支持	Tree-sitter 解析、包图可达性分析和框架约定
Java	是	是	是	支持	Tree-sitter 解析、结构化安全流分析、保守的静态成员证明
Go	是¹	部分¹	部分	支持	原生引擎状态与确定性工作区 API 证明相互独立
PHP	是	是	否	不支持	PHP 解析器覆盖、类型和 docblock 引用、Laravel 和 Drupal 约定（包括 .module/.install/.inc/.theme 文件），以及类似污点分析的安全汇点和来源（Drupal 请求和 Form API 输入进入 SQL 字符串、Markup::create() 和内联 Twig 模板）
Rust	实验性⁴	部分	否	不支持	Rust 解析器覆盖；安全检查涵盖命令注入和路径遍历
Dart	是³	部分³	否	不支持	Dart 解析器覆盖；安全检查涵盖命令注入、路径遍历和 SSRF
C#	部分	部分	部分	不支持	C# 符号、直接代码块中的不可达代码、选定的安全汇点，以及直接 NuGet 清单
C++	部分	否	否	不支持	对 .cpp、.cc、.cxx 中未使用的文件局部函数进行保守检查；解析 C++ 头文件以查找引用
Kotlin	部分²	否²	否	不支持	基于正则表达式的符号提取；仅报告私有声明和导入
Shell	否	部分	否	不支持	Shell 脚本安全检查涵盖命令注入、SSRF 和路径遍历

¹ Go 死代码和安全检查需要原生 skylos-go 引擎。从 4.50 起，Linux、macOS 和 Windows（x86_64 和 arm64）的 PyPI wheel 均包含该引擎；容器镜像也包含该引擎，官方 GitHub Action 会构建该引擎。 在其他环境中，skylos doctor 会打印构建该引擎的命令。没有该引擎时，只会运行 Go 质量检查，并将 Go 文件报告为未分析；请参见下文的 Go 引擎说明。

² Kotlin 死代码检查仅报告 private 类型和函数，以及未使用的导入；所有非私有声明均视为已使用。没有内置的 Kotlin 安全规则；机密扫描仍会覆盖 .kt 和 .kts 文件。

³ 从 4.47.2 起，Dart 检查需要可选的 skylos[dart] 扩展 （pip install "skylos[dart]"）；更早的版本默认安装 Dart 解析器。该解析器没有预构建的 wheel，因此安装时需要 C 编译器。没有该解析器时，如果扫描包含 .dart 文件，就会将这些文件报告为未分析（SKY-ANALYSIS-INCOMPLETE，覆盖不完整），而不是静默跳过；skylos doctor 会显示是否已安装 Dart 支持。

⁴ Rust 死代码检查处于实验阶段：不会解析 trait 方法调用、跨 crate 使用的 pub 项、重新导出、宏和 #[bench] 函数；对 ripgrep 进行的手动抽查未发现真阳性。Rust 候选项的置信度上限为 40，低于默认阈值，因此除非传入 --confidence 40，否则不会列出；扫描会用一行文字说明这一点。rustc 自带的 unused_imports 和 dead_code lint 可检查私有项。

“No” 表示 Skylos 没有为该语言内置此类规则。 对于 C#，死代码发现采用保守策略：在完整的可执行程序或 Web 应用扫描中，未被引用的公共类型和方法属于低置信度候选项；库 API、受保护成员以及已知的框架入口点或已配置的入口点仍可从外部访问。尚未实现 C# 源文件可达性分析。质量扫描会检测直接代码块中无条件执行 return、throw、break 或 continue 后的语句；这并非完整的控制流分析。安全覆盖范围包括选定的污点输入汇点，以及在启用 --secrets 或 -a 时对 .cs 文件进行的通用密钥扫描。目前尚未对内插原始字符串表达式进行 C# 污点分析。SCA 会盘点 .csproj 文件中的直接 NuGet PackageReference 条目。只有无条件的精确 Version 固定版本（[version]），且没有本地 Update/Remove 修改时，才能与安全公告进行核对；VersionOverride 或集中管理的版本不在此列。普通 NuGet 版本值表示最低版本界限，因此在没有已解析的锁定文件时，无法确定已安装版本及其漏洞状态。不会盘点传递依赖包。

Java 安全分析会跟踪同包文件中直接实现的请求数据辅助方法，或由精确导入或限定名在经验证的本地源根目录下标识的源文件。辅助文件读取范围受限，并会拒绝符号链接；不会执行 Java 代码或构建脚本。这并非完整的类路径分析或递归辅助方法分析。不会假定未知辅助方法是请求来源或净化器。

C++ 分析涵盖 .cpp、.cc、.cxx、.hpp、.hh 和 .hxx 文件。首个版本仅报告看似未使用的文件局部自由函数。由于没有构建配置，无法完整解析模板、重载、宏或外部用法；这些发现是保守的启发式结果，并不能证明代码已失效。含义模糊的 .h 文件和 C 文件不会作为 C++ 分析。

Java 弱哈希检查也会跟踪本地算法变量，以及通过 java.util.Properties 从字面类加载器资源加载的值。资源查找范围限于匹配的 src/main/resources 或 src/test/resources 目录。资源缺失、不受支持的加载器或目录结构、相互冲突的分支值，以及无法解析的修改，均视为未知。属性仅用作加密证据，不用于证明安全防护或选择安全分支。此分析不会解析任意运行时类路径、JAR 资源或环境覆盖项。

TypeScript 和 JavaScript 死代码分析可识别 package.json 入口字段，包括 bin。对于位于 dist/ 或 out/ 下的目标，会先检查对应的 src/ 位置，再检查软件包根目录，最后检查声明的输出位置。这也涵盖将 dist/bin/palee.js 映射到 bin/palee.ts，以及将 dist/src/index.js 映射到 src/index.ts 的情况。如果两个源位置都存在，则优先采用 src/ 映射；不会将无关文件视为入口点。

对于由软件包脚本调用的 ESM 构建脚本，Skylos 也会跟踪使用未变常量、展开语法、模板、Node 路径辅助方法和简单字面数组映射的顶层 esbuild 调用。构建脚本绝不会被执行。嵌套构建调用和由文件系统生成的入口列表目前不受支持，仍可能产生未使用文件的发现结果。

.vitepress/config.* 和 .vitepress/config/index.* 下的 VitePress 配置会被识别为 .js、.ts、.mjs 和 .mts 的开发入口点。.vitepress 中的其他文件仍需有引用或符合其他入口点规则。诸如 scripts/ 这样的现有目录约定也适用于原生 Windows 分隔符；这不会扩展为从 CI 工作流中通用发现命令。 Vue 单文件组件（.vue）会被源代码分析跳过，即使显式传入也不例外。Skylos 尚不能解析其中的 <script> 或 <script setup> 块；独立的 JavaScript、TypeScript 和后端源文件仍会接受分析。模板中现有的浏览器脚本和事件引用不受影响。

Go 死代码和安全检查需要原生 skylos-go 引擎。如果 Skylos 发现了 Go 文件，却无法运行该引擎，就会将这些文件列为未分析、标记覆盖率不完整，并且绝不会将其报告为干净。少量零散的 .go 文件会触发覆盖率警告；如果大部分代码都是 Go，扫描将以 2 退出。运行 skylos doctor 可验证引擎是否可用：它会打印与版本匹配的构建命令，而 SKYLOS_GO_BIN 可将 Skylos 指向单独构建的引擎。容器镜像包含该引擎，官方 GitHub Action 也会自动构建它。

有关规则类别和扫描范围，请参阅规则参考。

配置和部署支持

Surface	Files	Security Scope
GitHub Actions	.github/workflows/*.yml、.github/workflows/*.yaml、action.yml、action.yaml	危险触发器、令牌权限、未固定版本的 Action、模板注入、机密、OIDC、缓存和制品策略
GitLab CI	.gitlab-ci.yml	可变镜像、未固定版本的 include、明文机密、不受信任的 eval、Docker-in-Docker、OIDC、缓存、超时和 Runner 标签策略
Dockerfile	Dockerfile、Dockerfile.*、*.dockerfile	危险的 RUN 命令、未带校验和的远程 ADD，以及明文构建 ARG / ENV 机密
Edge Docker Compose	compose*.yml、compose*.yaml、docker-compose*.yml、docker-compose*.yaml	特权容器、范围过大的主机设备/控制挂载、GPU/设备运行时和主机网络
Edge systemd	*.service	以 root 运行的边缘服务、可变的 ExecStart 路径、缺少沙箱、范围过大的能力和设备访问权限
渲染后的 Kubernetes 暴露面	一个包含多个文档的 *.yml 或 *.yaml 捆绑文件，以及一个符合约定的 Python 源文件	从 Ingress 经由其 Service 和工作负载进行选择性启用的证明：Ingress 注释为 skylos.dev/network-scope: external（或 public），且 skylos.dev/backend-protocol: http；SKY-DEP001 会根据 skylos.dev/source-file 和 skylos.dev/required-guards 检查直接定义的顶层 FastAPI/Flask 路由，SKY-DEP002 会捕获生效的 Flask 调试器，SKY-DEP003 会捕获生效的重新加载模式
GPU 发布契约	.skylos/gpu-targets.yml、Dockerfile、CMake/CUDA 构建文件、TensorRT 源代码	针对驱动程序、计算架构和序列化引擎兼容性的静态目标设备集检查；不探测硬件

使用 --danger 或 -a 时，在 Git 工作树内执行目录扫描还会检查该工作树根目录下的 .github/workflows/*.yml / *.yaml 和 .gitlab-ci.yml。例如，skylos src --danger 会检查适用于 src 的 CI 配置，同时将源代码、容器和部署分析限制在 src 内。无关的已暂存或未暂存编辑不会缩小完整扫描的范围。显式差异筛选器仍会选择已更改的配置文件；单文件扫描仍仅限于该文件。请参阅扫描范围。

其他工作流

这些工作流涵盖范围更窄的任务：容器镜像、Kubernetes 部署暴露，以及 GPU 发布制品。

目标	命令	你将获得什么	更多详情
容器镜像扫描	skylos image scan IMAGE@sha256:<digest> --platform linux/amd64 --fail-on high	使用单独安装的 Trivy、注册表网络/身份验证，以及针对固定远程镜像的显式严重性门槛	容器镜像扫描
容器镜像报告导入	skylos ingest trivy --input trivy.json --sarif image.sarif	将现有的 Trivy 镜像漏洞报告转换为 Skylos JSON/SARIF；可选执行绑定摘要值的严重性检查	容器镜像扫描
Kubernetes 暴露证明	skylos . --select SKY-DEP001,SKY-DEP002,SKY-DEP003 --format concise	在单个渲染后的多文档包中检查明确对外、明确使用纯 HTTP 的 Ingress 链；路由检查会将框架的确切接线方式与工作负载声明的源文件和必需的防护措施进行比较	部署暴露规则
GPU 源码/构建意图门禁	skylos . --select SKY-GPU000,SKY-GPU001,SKY-GPU002,SKY-GPU003 --gate --format concise	在制品构建前检查声明的 CUDA 镜像、架构、驱动程序和 TensorRT 打包意图	GPU 目标契约
已构建 GPU 制品预检	skylos preflight build/app	验证确切的本地制品身份、选定的 CUDA 架构、打包的运行时路由，以及声明的集群兼容性；返回 PASS、FAIL 或 UNKNOWN	发布可靠性

检查精确的 GPU 发布制品

skylos preflight 会根据仓库声明的 GPU 设备群检查已构建的制品本身。这与 SKY-GPU* 源码扫描不同，后者会在制品生成前检查 Dockerfile、CUDA 构建设置和 TensorRT 打包意图。

声明接收同一发布版本的每台机器：

# .skylos/gpu-targets.yml
version: 1
targets:
  - name: inference-t4
    vendor: nvidia
    driver: "535.104.05"
    compute_capability: "7.5"
    platform: "linux/amd64"

规范文件名为 .skylos/gpu-targets.yml；也接受使用相同架构的 .skylos/gpu-targets.yaml。

然后检查本地构建。Skylos 使用受信任的系统 cuobjdump，创建私有快照，且绝不会加载或执行制品：

skylos preflight build/app

若要在 CI 中无需命令参数即可运行，请通过严格的发布收据将其绑定到项目相对路径下的制品：

{"version": 1, "artifact": "build/app"}

将该文件保存为 .skylos/release.json，然后运行 skylos preflight。对于能够进入报告生成阶段的请求，终端输出简洁，重定向输出则为带有架构版本的 JSON。参数或适配器错误可能以纯文本形式显示，并以 2 退出。

状态	退出码	含义
PASS	0	在声明的静态证据范围内，所有声明的目标均兼容，且已验证精确的制品身份
FAIL	1	制品证据证明至少一个声明的目标不兼容
UNKNOWN	2	所需证据缺失、有歧义、不受支持或不完整；绝不会静默地变为通过

cuobjdump 可能会报告多个代码对象组，这些组由其选定的可执行 fatbin 中的生成器标签标识。Skylos 要求每个已报告的组都有兼容路径。仅包含 PTX 的路径会保持为 UNKNOWN，因为静态检查无法证明部署驱动程序能够成功对其进行 JIT 编译。如果任何目标或必需检查失败，整体结果为 FAIL；否则，只要有任何结果未知，整体结果就是 UNKNOWN；只有所有结果均通过时，整体结果才为 PASS。

版本 1 会验证本地制品身份、Linux ELF 平台、选定的可执行 fatbin 架构路径、静态打包的 $ORIGIN CUDA 运行时路径，以及有文档记录的 CUDA 驱动程序系列兼容性。它不会验证运行时执行、工作负载正确性、内存需求、性能、未选中或可重定位的 fatbin，也不会验证每个内核的符号一致性。尚未实现 Windows PE 运行时导入验证。接受以摘要固定的 OCI 引用作为身份，但绝不会拉取或启动它们，因此 CLI 始终会对其报告 UNKNOWN；受信任的调用方可以通过 skylos.preflight.run_preflight(...) 提供与摘要绑定的检查事实。

基准测试概览

Skylos 已纳入针对死代码、安全性、质量、Agent 审查和 AI 代码缺陷的回归测试套件。这些套件是回归门禁，而非独立基准测试：测试用例由我们编写，因此我们不会将其得分作为准确率公布。随着套件扩充，用例数量会发生变化；清单是当前的权威来源。

套件	用例	运行方式
死代码	benchmarks/dead_code/manifest.json	python scripts/dead_code_benchmark.py
安全性	benchmarks/security/manifest.json	python scripts/security_benchmark.py
质量	benchmarks/quality/manifest.json	python scripts/quality_benchmark.py；也会在每个拉取请求的 CI 中运行
Agent 审查	benchmarks/agent_review/manifest.json	python scripts/agent_review_benchmark.py（需要 LLM API 密钥）
AI 代码缺陷	benchmarks/ai_code_defects/manifest.json	python scripts/ai_code_defect_benchmark.py

有关方法、带日期的结果、竞品基线和注意事项（包括冻结的 golden-v0.2 套件），请参阅 BENCHMARK.md。完成门禁基准测试 会重放已发布的 Agent 运行记录，并报告门禁遗漏的内容。

实验性的 Jev runner 可以对照已纳入仓库的死代码标签或冻结的 skylos-benchmarks 语料库，对固定版本 jev-1.13.0 的类型化决策模型进行盲测评分。它不会在请求中提供标签和审查原因，会在本地保留黄金标签 ID，以便精确比较分类结果；在不改变测试夹具语义的前提下，还会对中和了暗示答案的标识符的测试重复运行。现在，离线比较器会针对冻结的 Skylos 结果，逐个标签报告修正、回退、弃答和不安全删除。实时模式会将测试夹具源代码发送给 TypeSafe，需要显式启用标志和单独的 TYPESAFE_API_KEY；它支持有上限、可恢复的运行，并记录请求延迟与本地契约验证延迟。常规 Skylos 扫描不需要 Jev 密钥。目前为止，付费 Jev 运行规模较小，属于针对合成套件的开发运行，并非独立留出测试；在某些套件中，Jev 并未改善分类效果。死代码基准测试指南 和同次运行比较报告了这些结果及其注意事项。

死代码审查默认不启用。常规的 skylos . 扫描会在本地运行，不使用模型。skylos agent verify . 默认使用 LLM 验证器；如果要使用 Jev，请显式选择：

skylos agent verify . --format json                         # LLM only
skylos agent verify . --dead-code-review jev --format json  # Jev only
skylos agent verify . --dead-code-review jev-llm --format json  # Jev, then LLM if uncertain

仅使用 Jev 需要 TYPESAFE_API_KEY，不需要 LLM 密钥。对于置信度高的 Jev“未使用”判定，会保留静态发现结果；对于置信度高的“已使用”判定，则会将其抑制；对于不确定或无法判定的情况，会将发现结果保留为未经验证。Jev 加 LLM 模式还需要配置 LLM 提供方，并会将不确定的判定交给 LLM。单独使用 Jev 绝不会授权 --fix。如果选择任一种 Jev 模式，但未设置 TYPESAFE_API_KEY，Skylos 会停止运行并提供设置说明，而不会静默切换审查模式。请登录官方 TypeSafe 控制台获取密钥（访问可能需要邀请），然后在环境中设置 TYPESAFE_API_KEY；请勿将其放入源代码管理或命令行参数中。

Jev 会向 TypeSafe 发送有大小限制的项目源代码快照（目前最多 64 KB）。请检查其中是否嵌入机密信息，并确认已获准共享；本地文件防护功能并非机密扫描器。过大或不安全的快照无法由 Jev 判断。较早的 --jev-judge 和 --jev-precheck 标志仍可用于兼容；新工作流请使用 --dead-code-review。有关密钥设置、回退行为和限制，请参阅死代码审查指南。

真实项目回归测试

liveness_primer 由 Matthew Digman 创建并维护，是 Skylos 官方的真实项目回归测试工具。每次 PR 中，它都会将基础版本和拟议的合并结果与同一批固定版本的 Python 项目进行比较，并报告新增、移除或变更的发现。

查看 Analyzer Blast Radius 检查，了解比较结果和可下载的报告。这些结果可补充上述带标签的基准测试；仅凭发现数量的变化无法证明准确性。请参阅 liveness_primer 指南，了解测试范围、审核步骤和复现命令。

项目实践成果

在 9 个开源项目中，共有 10 个借助 Skylos 清理死代码的 PR 已合并到默认分支，包括 Black、NetworkX、Optuna、mitmproxy、pypdf 和 pdm。在我们记录的另外 16 个 PR 中，一个合并到了维护者的预发布分支，但未进入 main（Flagsmith）；一个已合并，但属于质量修复而非死代码清理；一个合并后又被回滚；四个由维护者关闭；七个由我们关闭；另有两个仍处于开放状态。这些是已接受的清理 PR，并不代表认可或采用。

候选项来自 Skylos 静态分析，通常会通过基于大模型的 skylos agent verify 进行分类，并在每个 PR 提交前由人工核查。真实项目结果 列出了记录在案的 26 个清理和质量修复 PR，以及其结果和维护者给出的原因。

集成

集成	链接	用途
GitHub Action	GitHub Action	仓库 PR 门禁，或可选的固定摘要容器镜像门禁
GitLab Code Quality	GitLab 设置	合并请求报告工件；无需发表评论的机器人或 API 令牌
Bitbucket Pipelines / Azure Pipelines	Pipeline 设置	检测 Skylos Cloud 检查的拉取请求上下文；--diff 使用 PR 目标分支
Jenkins、CircleCI 及其他 CI	在任意 CI 上使用 Skylos	skylos cicd init 会为你的 CI 写入或打印拉取请求门禁；--diff 使用 PR 目标分支
VS Code 扩展	VS Code 扩展	编辑器内发现问题并通过 AI 辅助修复
Claude Code / Codex / Cursor hooks	Agent 循环钩子	在本地检查 Agent 的每次编辑、文件读取和软件包安装
MCP 服务	MCP 设置	向 AI Agent 和编码助手提供 Skylos 扫描；analyze 无需令牌即可使用（每滚动 24 小时可调用 5 次），其他工具需要免费的 Skylos 项目令牌；经过身份验证的扫描可以使用额度
Ruff	Python 代码检查	通过 skylos lint 进行可选的 Python 代码检查
Docker 镜像	安装	无需在本地安装 Python 即可运行 Skylos
Skylos Cloud	Skylos Cloud	skylos cloud：上传发现结果，查看每个分支的质量门禁及其变化

通过命令行设置拉取请求门禁。skylos cicd init 会检测你的 CI （GitHub Actions、GitLab CI、Jenkins、Bitbucket Pipelines、Azure Pipelines、 CircleCI）并写入相应文件；如果文件已存在，则会打印需要添加的代码块。 对于其他 CI，它会提供需要添加的命令；参见 在任意 CI 上使用 Skylos。

skylos cicd init --no-upload                       # without Skylos Cloud
skylos cicd init --no-upload --scan-path apps/api  # a monorepo subproject
skylos cicd init                                   # with Skylos Cloud uploads
skylos cicd init --no-upload --risk-review         # plus the "Skylos risk review" check
skylos cicd init --ci jenkins                      # a Jenkinsfile pull request stage

在 GitHub Actions 上，生成的工作流会检查拉取请求中变更的行，并在发现测试时添加 一个 skylos done 作业。除非使用 --no-upload，它还会通过 GitHub OIDC 将完整扫描结果 上传到 Skylos Cloud，上传来源包括默认分支的推送，以及发往默认分支的拉取请求（pull_request_target： 拉取请求会作为数据进行扫描，不使用凭据；随后由一个从不检出其文件的作业上传结果）。 在仓库中安装 Skylos GitHub App 之前，上传会失败。它通过 --scan-path 支持单体仓库子项目。参见 你的第一个 Skylos 门禁拉取请求。

要使用组合 Action 扫描已构建的镜像，请在调用方作业中安装固定版本的 Trivy， 并将 image 设置为可信的 repository@sha256:<digest> 构建输出，同时设置 image-platform。此操作仅扫描镜像；mode: gate 使用 image-fail-on（默认值为 high），而 mode: scan 只报告发现结果。 参见容器镜像扫描。

文档导航

需求	阅读此文档
安装选项、从源码安装和 Docker	安装
首次扫描和核心工作流	快速入门
CLI 命令、标志和示例	CLI 参考
CLI 输出模式、美化报告和 TUI 控件	CLI 输出模式
通过 Skylos CLI 使用可选的 Ruff lint 检查	Python Lint 检查
CI 设置、PR 门禁、注释和分支保护	CI/CD
GitLab 合并请求报告和 CI 示例	GitLab 代码质量
Bitbucket Pipelines 和 Azure Pipelines 拉取请求检查	Bitbucket 和 Azure Pipelines
Jenkins、CircleCI、Buildkite、Travis CI 和其他 CI	在任何 CI 上使用 Skylos
死代码行为和框架感知	死代码检测
安全扫描和污点分析	安全分析
依赖项 CVE、uv/npm/pnpm/Poetry/Yarn lockfile、离线 SBOM 和 CI 中的 SCA	依赖项扫描
依赖项许可证、SPDX 2.3 SBOM 和许可证拒绝/允许策略	许可证合规
固定摘要的容器镜像扫描和 GitHub Action 设置	容器镜像扫描
源代码 GPU 契约和构建产物预检	发布可靠性
规则 ID 前缀和产品术语	规则词典
Agent 扫描、验证、修复和模型设置	AI 功能
AI 防御检查和大模型护栏	AI 防御
Claude Code、Codex 和 Cursor 钩子	Agent 循环钩子
Agent 变更的完成门禁（skylos done）	完成门禁
变更涉及的内容和应优先阅读的文档（skylos done map）	变更地图
拉取请求不应因机器人批准而合并的风险（skylos cicd risk-review）	风险审查
使用 GitHub Actions 创建首个受门禁保护的拉取请求	你的首个受门禁保护的 PR
MCP 服务设置	MCP 服务
每个由 Skylos 辅助完成的清理 PR 及其结果	真实案例结果
基线、筛选、抑制和白名单	配置
智能追踪	智能追踪
规则系列和语言支持	规则参考
skylos cloud、它会发送的内容及其他 Cloud 命令	Skylos Cloud
Cloud 上传和仪表盘流程	从 CLI 到仪表盘
CLI 可能发出的所有网络请求，以及如何分别关闭	哪些数据会离开你的设备
VS Code 扩展	VS Code 扩展
基准测试和方法论	BENCHMARK.md
安全策略	SECURITY.md
发布流程	RELEASE_WORKFLOW.md
贡献优先级	ROADMAP.md
贡献指南	CONTRIBUTING.md

常见问题

Skylos 会取代 Bandit、Semgrep、CodeQL 或 Vulture 吗？

不会。Skylos 可以与它们配合使用。它专注于感知框架的死代码信号、PR 门禁、AI 时代的回归检查，以及涵盖死代码、安全、机密信息、质量和 AI 缺陷检查的综合工作流。

Skylos 需要大模型吗？

不需要。核心静态分析可在本地运行，无需 API 密钥。大模型功能是可选的，可通过 skylos[llm] 和 Agent 命令使用。

Skylos 是免费的吗？

Skylos CLI 免费且开源（Apache-2.0）。Skylos Cloud 提供适用于一个项目的免费计划和 Workspace 计划；购买任意一次性额度包即可永久启用 Workspace，无需购买席位或订阅。

MCP 服务需要账户吗？

如果没有 SKYLOS_API_KEY，MCP 服务仅提供 analyze（死代码分析，每滚动 24 小时可调用五次）。在启动服务时设置 SKYLOS_API_KEY 之前，所有其他 MCP 工具（verify_change、verify_agent、security_scan、secrets_scan 等）都会返回身份验证错误；请在 Skylos Cloud 控制面板设置中创建免费密钥。未经身份验证的 analyze 调用免费。经过身份验证的 analyze、安全、质量、机密信息和来源扫描可能会消耗额度；当前费用由 Skylos Cloud 设定。remediate 目前每次生成修复方案的调用会消耗 10 个额度；试运行（默认模式）免费。对应的 CLI 命令（skylos verify、skylos defend、skylos . -a）以及 skylos agent install-hooks 都在你的计算机上运行，无需账户或密钥；它们的依赖项和软件包检查仍会查询公共注册表（参见哪些内容会离开你的计算机）。

MCP 服务能在 Docker 中运行或通过网络访问吗？

可以。skylos mcp --transport sse（或 streamable-http）会通过 HTTP 在 MCP_BIND（默认值为 127.0.0.1）和 PORT（默认值为 8080）上提供 MCP 服务，并且在未设置 SKYLOS_MCP_TOKEN（至少 16 个字符）时拒绝启动；每个客户端都必须发送此持有者令牌。由 skylos_mcp/Dockerfile 构建的镜像会设置 MCP_BIND=0.0.0.0，以便发布的端口能够访问该服务：

export SKYLOS_MCP_TOKEN="$(openssl rand -hex 24)"
docker build -f skylos_mcp/Dockerfile -t skylos-mcp .
docker run --rm -p 8080:8080 -e SKYLOS_MCP_TOKEN skylos-mcp

客户端通过 Authorization: Bearer <token> 连接到 http://localhost:8080/sse。如果服务位于代理后方，请将 SKYLOS_MCP_PUBLIC_URL 设置为客户端使用的地址。

Skylos 会取代 Ruff 吗？

不会。skylos lint 是一个可选的便捷入口，会将工作委托给 Ruff。使用 pip install "skylos[lint]" 安装；常规 Skylos 扫描不会运行 Ruff，也不会将 Ruff 违规项合并到 SKY-* 发现结果中。

我可以只检查变更过的代码吗？

可以。在本地使用 skylos . -a --diff origin/main，或配置 CI 门禁以专注于新的发现结果。即使使用 --diff，已删除的安全控制项（例如已删除的身份验证装饰器（SKY-L021））仍会报告，包括变更仅删除装饰器所在行的情况。

skylos done 能发现所有伪造变更已完成的方式吗？

不能。它会比较测试函数（pytest、unittest、JavaScript/TypeScript），因此无法发现重写自定义测试运行器脚本或从测试数据文件中删除用例的情况；而且静态断言计数无法察觉的测试弱化方式仍然存在。请参阅 done 门禁的限制和基准测试。

我该如何处理有意编写的动态代码？

使用基线、白名单、内联抑制规则或运行时跟踪。请参阅配置文档和智能跟踪文档。

贡献与支持

• 通过 SECURITY.md 报告安全问题。
• 使用 skylos feedback 私下报告问题，该命令会打开 skylos.dev/feedback 上预先填写的表单。页面地址会包含 Skylos 版本、操作系统、Python 版本和最后一条失败的命令（路径和机密信息均已隐藏）；只有在你按下“发送”后，消息才会发送。 无需账号。
• 提交公开的错误报告和误报报告，并附上最精简的复现示例（skylos feedback --github 会预先填写问题表单）。
• 查看 ROADMAP.md，了解值得参与的贡献方向。
• 提交拉取请求前，请阅读 CONTRIBUTING.md。
• 查看 QUALITY.md，了解项目质量和门槛要求。
• 加入 Discord 获取社区支持。

许可证

Skylos 根据 Apache License 2.0 授权。