HefestoAI

HefestoAI — AI 生成代码的发布真实性引擎

English | 简体中文 | 日本語

HefestoAI 在 AI 助手编写代码之后、代码发布之前运行。它会检查项目声明的内容（依赖项、配置、安装产物）是否与实际情况一致，并对代码本身执行安全性和复杂度检查。

快速开始（GitHub Action）

针对 Agent 编写代码的确定性通过／失败检查。 它会将仓库声明的内容（依赖项、README、pyproject.toml、CHANGELOG、action.yml、CI）与实际情况进行比较，并标记机密信息和有风险的 IaC。输入相同，结果相同。

# .github/workflows/hefesto.yml
name: HefestoAI
on: [pull_request, push]
permissions:
  contents: read
  security-events: write
jobs:
  hefesto:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: artvepa80/Agents-Hefesto@v4
        with:
          fail_on: HIGH
          sarif: 'true'

检查结果会显示在 Security > Code scanning 中，也会作为拉取请求注释显示。公共仓库可按所示方式使用；未启用 GitHub Code Security 的私有仓库请设置 upload_sarif: 'false'（仍会写入 SARIF 文件）。@v4 会跟随所有 4.x 版本发布，包括次要版本（4.16.0 会使未分析任何文件的运行无法通过检查）。如需固定版本，请指定 artvepa80/[email protected] 或某个提交 SHA。该 Action 使用与 hefesto analyze 相同的格式：Python 加上 YAML、Terraform、Shell、Dockerfile、SQL、PowerShell、JSON、TOML、Makefile、Groovy、COBOL、CloudFormation、ARM、Helm 和 Serverless，以及漂移检查。TypeScript、JavaScript、Java、Go、Rust 和 C# 需要使用 CLI 并运行 pip install "hefesto-ai[multilang]"。

免费且采用 MIT 许可证。PRO（每位用户每月 $8）和 OMEGA（每月 $19）：套餐。

---

运行真实性分析器（v4.20.4）

这些分析器会查找项目声明的内容与实际执行内容之间的漂移。每次运行 hefesto analyze 时都会执行。它们查找的问题不会只存在于某个单独文件中，因此逐文件的代码检查工具或安全扫描器不会报告这些问题：只有比较两个文件时才能发现。

分析器	检查内容	规则 ID
导入与依赖项	未在 pyproject.toml 或 requirements.txt 中声明的 Python 导入	OT-IMPORTS-001
文档与入口点	README 中缺少 [project.scripts] 里声明的 CLI 脚本	OT-DOCS-001
打包一致性	pyproject.toml、CHANGELOG 和 README 徽章之间的版本不一致	OT-PKG-001/002
安装产物一致性	未使用的 action.yml 输入；缺失的 Dockerfile COPY 源文件	OT-INSTALL-001/002
CI 配置漂移	本地与 CI 工作流之间的 Python 版本或 flake8 配置不一致	OT-CI-001/002/003

# All operational truth findings appear in standard output
hefesto analyze . --severity MEDIUM

---

快速开始

pip install hefesto-ai
cd your-project
hefesto analyze . --fail-on critical

# PR review (added in v4.10.0) — analyze only changed code
hefesto pr-review
hefesto pr-review --strict        # include file-level context
hefesto pr-review --post --pr 42  # post inline comments via gh CLI

---

为什么选择 Hefesto？AI 代码问题

Claude Code、GitHub Copilot 和 Cursor 等助手编写代码的速度，已经超过任何人逐行审查代码的速度。其中一些代码虽然能通过代码检查工具，却依然很危险：

• os.system(user_input) → 命令注入
• f"SELECT * FROM {table}" → SQL 注入
• 能运行但会悄悄改变行为的代码，例如拼错的属性名，或被捕获后丢弃的异常（在 Python 中检查）

Hefesto 会在提交前、推送前和 CI 中进行检查，让这些问题在代码进入生产环境之前就显现出来。

---

Hefesto 检测的问题

问题	严重程度	描述
HARDCODED_SECRET	CRITICAL	代码中的 API 密钥、密码（已知的公开客户端密钥，例如 PostHog phc_ 和 Stripe pk_live_/pk_test_，会报告为 LOW）
SQL_INJECTION_RISK	HIGH	查询中的字符串拼接
COMMAND_INJECTION	HIGH	不安全的 shell 命令执行
PICKLE_USAGE	HIGH	import pickle / cPickle 行（会标记导入；不会单独报告 pickle.loads() 调用）
UNDECLARED_DEPENDENCY	MEDIUM	使用了导入项，但未在 pyproject.toml 中声明
PACKAGING_VERSION_DRIFT	MEDIUM	pyproject/CHANGELOG/README 之间的版本不一致
CI_CONFIG_DRIFT	MEDIUM-HIGH	本地环境与 CI 配置不一致
INSTALL_ARTIFACT_DRIFT	MEDIUM-HIGH	action.yml 输入项或 Dockerfile COPY 未同步
HIGH_COMPLEXITY	HIGH	圈复杂度 > 10
DEEP_NESTING	HIGH	嵌套深度 > 4 层
GOD_CLASS	HIGH	类超过 500 行
LONG_FUNCTION	MEDIUM	函数超过 50 行
LONG_PARAMETER_LIST	MEDIUM	函数参数超过 5 个

# Hefesto catches:
password = "admin123"  # HARDCODED_SECRET
query = f"SELECT * FROM users WHERE id={id}"  # SQL_INJECTION_RISK
os.system(f"rm {user_input}")  # COMMAND_INJECTION

# Hefesto suggests:
password = os.getenv("PASSWORD")
cursor.execute("SELECT * FROM users WHERE id=?", (id,))
subprocess.run(["rm", user_input], check=True)

---

GitHub Action

steps:
  - uses: actions/checkout@v4
  - name: Run Hefesto Guardian
    uses: artvepa80/Agents-Hefesto@v4
    with:
      target: '.'
      fail_on: 'CRITICAL'

@v4 是一个浮动标签，覆盖整个 4.x 系列，包括次要版本：每次发布 v4.x.y 都会移动该标签，因此工作流无需修改即可获得修复，也会获得行为变更，例如 4.16.0 中的变更：当没有可分析文件时，运行会因 --fail-on 而失败（退出码为 1；--allow-no-files 可选择不启用此行为）。如需确保版本完全固定，请指定确切的发布标签，例如 artvepa80/[email protected]（确切标签不会移动），或指定提交 SHA，然后自行升级。

使用 SARIF 上传到 GitHub 代码扫描（检测结果会显示在 Security > Code scanning 下，并作为拉取请求注释）：

jobs:
  hefesto:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write   # upload-sarif
      actions: read            # private repositories only
    steps:
      - uses: actions/checkout@v4
      - uses: artvepa80/Agents-Hefesto@v4   # SARIF needs v4.15.0 or later
        with:
          target: '.'
          fail_on: 'CRITICAL'
          sarif: 'true'

此 Action 是一个复合 Action：它会从 Action 自身的检出目录将 HefestoAI 安装到私有虚拟环境中（运行器需要 python3 >= 3.10；ubuntu-latest 已包含该版本），运行 hefesto analyze，并在 sarif: 'true' 时使用 github/codeql-action/upload-sarif@v4 上传 SARIF 文件，即使 fail_on 门槛检查失败也会上传。完整参考：docs/github-action.md。

输入项：

输入项	描述	默认值
target	要分析的路径（文件或目录）	.
fail_on	若发现达到或超过此严重程度的問題，则以错误退出	CRITICAL
allow_no_files	true：传递 --allow-no-files，因此在 fail_on 生效时，若运行未分析任何文件，仍以退出码 0 结束（目标为空是有意为之）；仍会打印警告	false
allow_not_analyzed	true：传递 --allow-not-analyzed，因此发现的文件若无法分析，不会导致 fail_on 失败；该文件仍会列在“Not analyzed”中，并显示警告	false
min_severity	要报告的最低严重程度（CRITICAL、HIGH、MEDIUM、LOW）	LOW
format	打印到日志中的输出格式（text、json、html、sarif）	text
sarif	true：同时生成 SARIF 2.1.0 文件并将其上传到代码扫描（需要 security-events: write）	false
sarif_file	SARIF 文件的路径	hefesto.sarif
upload_sarif	当 sarif: true 时，上传该文件；false 则仅生成文件	true
sarif_category	上传内容的代码扫描类别	hefesto
telemetry	选择加入。仅 1 或 true 会启用遥测：此 Action 每次运行发送一次匿名 ping，CLI 也会发送其使用情况事件。任何其他值（包括默认值 0）都不会发送遥测（CLI 仍会检查 pypi.org 上是否有更新版本）；参见 docs/telemetry.md	0

输出项：

输出项	描述
exit_code	CLI 的退出码（0 = 未超出阈值，1 = 超出 fail_on 阈值或发生运行时错误；参见 退出码）
sarif_file	SARIF 文件的路径；仅当 sarif 为 true 且文件已生成时提供

AI 生成代码防护（Pre-commit + MCP）

HefestoAI 可以作为 pre-commit 检查运行，也可以由 AI Agent 通过 MCP 调用，从而在合并前标记风险更高的变更。

添加为 MCP 服务：

npx @smithery/cli@latest mcp add artvepa80/hefestoai

添加到 Cursor（一键操作）：

该按钮会通过 cursor.com/link 打开 Cursor 的安装提示（GitHub 不会渲染 cursor:// 链接）。直接 deeplink：cursor://anysphere.cursor-deeplink/mcp/install?name=hefestoai&config=eyJ1cmwiOiJodHRwczovL2hlZmVzdG9haS5uYXJhcGFsbGMuY29tL2FwaS9tY3AtcHJvdG9jb2wifQ%3D%3D。同一服务也配置在仓库根目录的 .mcp.json 中（{"mcpServers":{"hefestoai":{"url":"https://hefestoai.narapallc.com/api/mcp-protocol"}}}）。无需 API 密钥。

API 端点：

端点	协议	路径
MCP	JSON-RPC 2.0	/api/mcp-protocol
托管分析	HTTP POST	/api/analyze
REST	HTTP GET/POST	/api/mcp
OpenAPI	OpenAPI 3.0	/api/openapi.json
问答	自然语言	/api/ask
更新日志	JSON	/api/changelog.json
常见问题	JSON	/api/faq.json

MCP analyze 工具（以及 POST /api/analyze）会在你发送的文件上运行开源引擎（hefesto analyze --no-config；托管 MCP 运行的是近期发布的 hefesto-ai 版本）：最多 20 个文件，每个文件 100 KB，总计 256 KB，耗时 20 秒。它会返回包含规则 ID、严重级别、行号和 SARIF 指纹的发现结果。也支持 TypeScript、JavaScript、Java、Go、Rust 和 C#（multilang 语法；在全新的服务实例上，首次此类请求会慢几秒）。不会存储任何内容。如需分析整个仓库，请在本地运行 hefesto analyze .。

托管 MCP 服务为闭源，由 Narapa LLC 运营。server.json 将 repository 指向此公开仓库，因为其中包含 analyze 运行所用的开源 hefesto-ai 引擎。

---

PR 审查（v4.20.4）

仅分析拉取请求中变更的代码，并在变更行上发布行内评论。每个发现结果都带有确定性的去重键，因此工作流可以跳过已发布过的发现结果（下方的去重模板会执行此操作；简单模板则不会）。

# Generate review as JSON (default — no network, no token needed)
hefesto pr-review

# Post inline comments via gh CLI (convenience mode)
hefesto pr-review --post --pr 42 --repo owner/name

# Include file-level context findings (not just changed lines)
hefesto pr-review --strict

工作原理：

1. 解析 base 与 head 之间的 git diff（自动检测 origin/main 或 GITHUB_BASE_REF）
2. 仅对有改动的文件运行完整分析器套件
3. 将发现结果筛选到变更行（默认）或整个文件（--strict）。函数级发现结果（复杂度、函数过长、嵌套过深）会报告在 def 行；只要函数内有任意新增行，就视为有变更。其 line 仍指向 def 行，因此去重键不会变动；anchor_line 则是行内评论所指向的新增行（在变更块之外时为 null）
4. 输出 JSON，并为每个发现结果生成 SHA256 去重键

GitHub Actions 工作流模板位于 examples/github-actions/：

模板	使用场景	是否幂等？
hefesto-pr-review-simple.yml	快速上手、小型仓库	否（重复运行会产生重复项）
hefesto-pr-review-deduped.yml	生产 CI、团队	是（通过 jq 去重管道实现）

请参阅 examples/github-actions/README.md 了解设置说明。

---

语言支持

代码语言

语言	解析器	状态
Python	Native AST	完全支持
TypeScript	TreeSitter	支持¹
JavaScript	TreeSitter	支持¹
Java	TreeSitter	支持¹
Go	TreeSitter	支持¹
Rust	TreeSitter	支持¹
C#	TreeSitter	支持¹

¹ TreeSitter 语言需要安装 [multilang] 附加组件： pip install "hefesto-ai[multilang]"。如果未安装，解析时会跳过这些语言的文件，Hefesto 会输出 stderr 警告，提示安装命令（该信息也会通过 JSON 输出中的 report.meta.parser_failures 提供）。

DevOps 与配置

格式	分析器	规则	状态	是否由 hefesto analyze 运行
YAML	YamlAnalyzer	通用 YAML 安全性	v4.4.0	是
Terraform	TerraformAnalyzer	与 TfSec 对齐的规则	v4.4.0	是
Shell	ShellAnalyzer	与 ShellCheck 对齐	v4.4.0	是
Dockerfile	DockerfileAnalyzer	与 Hadolint 对齐	v4.4.0	是
SQL	SqlAnalyzer	SQL 注入防护	v4.4.0	是
PowerShell	PS001-PS006	6 条安全规则	v4.5.0	是
JSON	J001, J002, J004, J005	4 条安全规则	v4.5.0	是
TOML	T001-T003	3 条安全规则	v4.5.0	是
Makefile	MF001-MF005	5 条安全规则	v4.5.0	是
Groovy	GJ001-GJ005	5 条安全规则	v4.5.0	是
COBOL	CobolGovernanceAnalyzer	COBOL001-COBOL016（16 条免费规则）²	v4.12.0	是

云基础设施

格式	分析器	重点	状态	是否由 hefesto analyze 运行
CloudFormation	CloudFormationAnalyzer	AWS IaC 安全性	v4.7.0	是
ARM Templates	ArmAnalyzer	Azure IaC 安全性	v4.7.0	是
Helm Charts	HelmAnalyzer	Kubernetes 安全性	v4.7.0	是
Serverless	ServerlessAnalyzer	Serverless Framework	v4.7.0	是

总计：该软件包为 22 种格式提供分析器（7 种代码语言 + 11 种 DevOps 格式 + 4 种云格式）。hefesto analyze（GitHub Action 和 pre-push hook 调用的命令）会运行全部 22 个分析器。如果某个后缀匹配多种格式，则由 docs/design/devops-analyzers-wiring.md 中的优先级表选择分析器。

² COBOL：全部 16 条规则均免费，无需许可证。分析器基于正则表达式（不使用完整的 COBOL 解析器），会读取 .cbl、.cob、.cobol、.cpy 和 .pco 文件（不区分大小写），还会读取被扫描程序 COPY 或 EXEC SQL INCLUDE 并包含 COBOL 数据定义的 .dcl、.copy、.cbk 及无扩展名文件（copybook 仅应用数据规则 COBOL004/COBOL008/COBOL009/COBOL016，以及用于检查其自身嵌套 COPY 的 COBOL007 和 COBOL015；不应用其他规则）。

COBOL 详情（源格式、各规则行为、COPY 展开、实测召回率、性能、SARIF）：docs/cobol.md。

---

安装

# FREE tier
pip install hefesto-ai

# Required for TypeScript, JavaScript, Java, Go, Rust, and C# analysis
pip install "hefesto-ai[multilang]"

# Optional: Black, for `hefesto analyze --format-check`
pip install "hefesto-ai[format]"

pip install hefesto-ai 仅安装 FREE 层级。购买 PRO 或 OMEGA 后，Narapa 会向你发送激活码，并附上激活说明。

---

CLI 参考（v4.20.4）

# Analyze code
hefesto analyze <path>
hefesto analyze . --severity HIGH
hefesto analyze . --output json
hefesto analyze . --format sarif > hefesto.sarif   # SARIF 2.1.0 (--format is an alias of --output)
hefesto analyze . --sarif-file hefesto.sarif       # text report + SARIF file
hefesto analyze . --format-check   # opt-in: also report Black formatting drift
hefesto analyze . --config ci/hefesto.yaml    # explicit config file (see Configuration)
hefesto analyze . --no-config                 # ignore .hefesto.yaml
hefesto analyze src/ --copybook-path ../copylib  # COBOL copybooks outside the scan
hefesto analyze . --include-vendored  # also analyze vendored/minified JS (skipped by default)

# PR review (added in v4.10.0)
hefesto pr-review                              # JSON to stdout
hefesto pr-review --base main --head HEAD      # explicit refs
hefesto pr-review --strict                     # file-level findings too
hefesto pr-review --post --pr 42 --repo o/r    # post via gh CLI

# Check status
hefesto status

# Install/update git hook
hefesto install-hooks

# Start API server (PRO)
hefesto serve --port 8000

# Telemetry (on by default)
hefesto telemetry disable

JSON 输出

hefesto analyze . --output json          # stdout = pure JSON, banners -> stderr
hefesto analyze . --output json 2>/dev/null | jq .  # pipe-safe

SARIF 输出

hefesto analyze . --format sarif > hefesto.sarif   # stdout = pure SARIF, banners -> stderr
hefesto analyze . --sarif-file out/hefesto.sarif   # any --output, plus a SARIF file

hefesto analyze 报告的每条发现都采用 SARIF 2.1.0 格式（涵盖运行的所有分析器，包括 COBOL，以及 Operational Truth 和提供方发现），并在测试中根据 OASIS 架构进行验证：

• 每个规则 ID 对应一条规则（COBOL004、DOCKER010 等；若分析器没有 ID，则使用问题类型，例如 HARDCODED_SECRET），包含名称、描述、帮助信息、帮助 URI 和默认级别；
• level：CRITICAL/HIGH → error，MEDIUM → warning，LOW → note；安全规则（机密、注入、不安全命令等）还会设置 security-severity（9.5 / 8.0 / 5.5 / 3.0），因此 GitHub 会将其评为 Critical/High/Medium/Low；
• CWE 使用统一映射（CWE 列表 4.20）：GitHub code scanning 会读取规则标签 external/cwe/cwe-N（不补零）。同一 ID 也会作为 run.taxonomies 中的 CWE 条目（组织为 MITRE），并在规则上通过 relationships 标注关系类型（equal、superset 或 relevant）。Python：机密 798、SQL 注入 89、命令注入 78、eval/exec 95、裸 except 396、pickle 导入 502（relevant，精度为 low，因为仅标记了导入）。Assert 没有 CWE。发现的 metadata.cwe 会覆盖该映射表；现有 COBOL 标签（cwe-798、cwe-20）保持原样。映射表：docs/ANALYSIS_RULES.md；
• 使用相对于仓库的 URI（%SRCROOT%，即当前目录的 git 顶层目录），并根据规则、文件和被标记行的文本生成 partialFingerprints，因此即使上方代码移动，告警也能保持原有标识；
• GitHub 上传限制：最多 25,000 条结果（保留严重程度最高的结果），压缩后不超过 10 MB；被丢弃的内容会在日志的工具通知中报告。

不会报告列号（仅报告起始行）。

格式偏差（可选）

hefesto analyze 默认不检查格式。使用 --format-check 时，它还会以检查模式运行 Black（在进程内运行，不会修改文件），检查所分析的 Python 文件：

pip install "hefesto-ai[format]"                    # or: pip install black
hefesto analyze . --format-check                    # report drift
hefesto analyze . --format-check --fail-on LOW      # fail the gate on drift

• 每个 Black 会重新格式化的文件都会产生一条 FORMAT_DRIFT 发现，严重程度为 LOW。由于此检查为可选，即使 --severity 高于 LOW，也会显示这些发现。--fail-on 和 --exclude-types 同样适用于它们，因此 --fail-on MEDIUM（或更高）不会因格式偏差而触发。
• Black 设置取自你的 pyproject.toml 中的 [tool.black] 表，查找方式与 black CLI 相同（line-length、target-version、skip-string-normalization、preview、extend-exclude / force-exclude 等）。如果 required-version 与已安装的 Black 版本不匹配，Hefesto 会发出警告。
• JSON 输出会在 code_snippet 中附带统一差异（前 60 行），并在 metadata 中附带 lines_added / lines_removed。
• 如果未安装 Black，Hefesto 会打印一行警告并继续运行；退出码不受影响。
• 仅支持 Black；不会运行 isort 和 flake8。

退出码

代码	含义
0	分析完成（未设置 --fail-on，或未达到阈值）
1	门禁失败（达到 --fail-on 阈值，或在设置 --fail-on 时没有分析任何文件），或运行时错误
2	命令行用法无效，或 .hefesto.yaml 无效

门禁示例

hefesto analyze . --fail-on high         # exit 1 if HIGH+ found
hefesto analyze . --fail-on critical     # exit 1 only if CRITICAL found
hefesto analyze .                        # always exit 0 (report only)
hefesto analyze . --fail-on high --allow-no-files   # an empty run keeps exit 0
hefesto analyze . --fail-on high --allow-not-analyzed  # a file that failed does not fail the gate

如果一次运行没有分析任何文件（目录为空、只有不受支持的文件，或所有文件都被排除），则绝不会报告为通过：报告会显示“No files were analyzed”，stderr 会输出一条注明路径的警告；使用 --fail-on 时，门禁会以退出码 1 失败。如果文件因属于 vendored JavaScript 而被排除，警告会注明文件数量，并建议使用 --include-vendored。

对于有意不分析任何文件的运行（例如，PR 只修改了 Markdown 文件的仅分析变更文件任务，或 monorepo 矩阵中的某个条目没有受支持的源文件），请传入 --allow-no-files（Action 的 allow_no_files: 'true' 输入会自动为你传入该参数）。只有退出码会发生变化：运行仍以退出码 0 结束，并打印“Gate skipped: no files were analyzed (--allow-no-files)”，同时仍会打印“Files analyzed: 0”、“No files were analyzed”以及 stderr 警告。这只是命令行标志：.hefesto.yaml 无法设置它（allow_no_files 键会被判定为未知，退出码为 2），因此共享配置永远不会关闭此检查。

不是有效 UTF-8 的文件会使用 latin-1 作为回退编码读取并进行分析（其发现项会计入统计）；文本报告会在“Decoded with fallback (latin-1)”下列出该文件，--output json 会在 meta.decoded_with_fallback 中包含该文件，SARIF 会为其生成 warning 通知，stderr 也会发出警告。

运行找到但无法分析的文件（无法读取，或其分析器引发错误）绝不会被静默忽略：文本报告会在“Not analyzed”下列出该文件和原因；--output json 会在 meta.not_analyzed 中包含该文件（path、language、reason：read_error 或 analyzer_error，以及 exception）；SARIF 会在 invocations[0].toolExecutionNotifications 中为其生成 error 通知；stderr 也会发出警告（即使使用 --quiet 也如此）。使用 --fail-on 时，此类文件会使门禁失败，并显示“Gate failure: N file(s) could not be analyzed (exit 1)”，即使设置了 --allow-no-files 也是如此。--allow-not-analyzed（Action 的 allow_not_analyzed: 'true' 输入）可选择不因这类文件而失败：此时门禁只根据发现项作出判断，该文件仍会列出并发出警告。与 --allow-no-files 一样，它也只是命令行标志。

---

推送前钩子

在你自己的项目中，hefesto install-hooks 会安装随包提供的钩子：pre-commit 会分析暂存文件（--fail-on HIGH），pre-push 会分析代码仓库（--fail-on CRITICAL）。这些钩子会调用运行 install-hooks 时所用的 Python 解释器（python -m hefesto）；如果找不到，则回退到 PATH 上的 hefesto；如果两者都找不到，则会显示消息并失败（请重新安装钩子，或设置 SKIP_HEFESTO_HOOKS=1）。钩子会安装到 git rev-parse --git-path hooks 指定的位置，因此 worktree 和子模块都可正常使用；如果设置了 core.hooksPath（Husky、lefthook 等），则不会写入任何内容，命令会以退出码 1 结束：请从该钩子管理器调用 python -m hefesto analyze，或使用 hefesto-analyze pre-commit 框架钩子（参见 pre-commit 钩子）。如果没有安装任何钩子（例如，已有钩子且未使用 --force），命令也会以退出码 1 结束。限制：pre-commit 钩子分析的是暂存文件在工作树中的副本，而不是暂存区（索引）中的内容。下文所述的 scripts/git-hooks/ 贡献者钩子仅用于 Agents-Hefesto 的克隆（根目录 pyproject.toml 中的 name = "hefesto-ai"）；命令会说明安装了哪一组钩子。

每次在此代码仓库中执行 git push 前都会自动进行验证：

# Install the same hooks and print the plans link (PRO $8/mo, OMEGA $19/mo)
hefesto init

# Install/update hook (copies scripts/git-hooks/pre-push -> .git/hooks/pre-push)
hefesto install-hooks

# Update an existing hook
hefesto install-hooks --force

# Bypass temporarily
SKIP_HEFESTO_HOOKS=1 git push

该钩子会运行两道门禁：

1. 安全门禁 — 使用 --fail-on CRITICAL --exclude-types VERY_HIGH_COMPLEXITY,LONG_FUNCTION 运行 hefesto analyze（阻止安全问题，忽略复杂度债务）
2. 快速 lint/测试门禁 — Black、isort、Flake8 和一套最小测试

**注意：**钩子仅安装在你的本地计算机上，不会提交到 git。克隆后，或每当 scripts/git-hooks/pre-push 更新时，请运行 hefesto install-hooks。

---

各等级功能

功能	FREE	PRO（$8/月/用户）	OMEGA（$19/月）
静态分析	是	是	是
安全扫描	基础	高级	高级
推送前钩子	是	是	是
语言和格式支持（详情）	是	是	是
ML 增强	否	是	是
REST API	否	是	是
IRIS 监控	否	否	是
生产环境关联	否	否	是

• PRO（$8/月/用户）和 OMEGA（$19/月）：套餐和结账

Hefesto PRO 可选功能

Hefesto OSS 可独立运行。如果已安装 Hefesto PRO，OSS 可选择启用： 为 hefesto serve 加固 Patch C API、范围门控（默认仅限第一方）、TS/JS 符号发现，以及安全的确定性增强（优先采用架构、经过掩码处理且有界）。 参见 docs/PRO_OPTIONAL_FEATURES.md。

---

REST API（PRO）、OMEGA Guardian 和 IRIS

hefesto serve（PRO）通过 HTTP 提供分析器：docs/rest-api.md。OMEGA Guardian 和 IRIS 生产监控 Agent：docs/omega-iris.md。

---

CI/CD 集成

GitHub Actions — 完整仓库分析

name: Hefesto

on: [push, pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Hefesto
        run: pip install hefesto-ai
      - name: Run Analysis
        run: hefesto analyze . --severity HIGH

GitHub Actions — 使用 CLI 进行代码扫描（SARIF）

jobs:
  analyze:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - run: pip install hefesto-ai
      - run: hefesto analyze . --severity LOW --fail-on CRITICAL --sarif-file hefesto.sarif
      - if: always()
        uses: github/codeql-action/upload-sarif@v4
        with:
          sarif_file: hefesto.sarif
          category: hefesto

GitHub Actions — 使用内联评论进行 PR 审查（v4.20.4）

name: Hefesto PR Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: pip install hefesto-ai
      - name: Review changed code
        env:
          GITHUB_BASE_REF: ${{ github.event.pull_request.base.ref }}
          GITHUB_SHA: ${{ github.event.pull_request.head.sha }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: hefesto pr-review --post --pr ${{ github.event.pull_request.number }} --repo ${{ github.repository }}

如需在生产环境中使用去重功能（重跑时不产生重复评论），请参见 examples/github-actions/ 中的工作流模板。

pre-commit 钩子

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/artvepa80/Agents-Hefesto
    rev: v4.20.4
    hooks:
      - id: hefesto-analyze

GitLab CI

hefesto:
  stage: test
  script:
    - pip install hefesto-ai
    - hefesto analyze . --severity HIGH

---

配置

hefesto analyze 从命令行标志（参见上文的 CLI 参考）以及可选的 .hefesto.yaml 文件（如下）中获取选项。分析选项（如严重性或输出 格式）没有对应的环境变量。

环境变量

# Telemetry (see Telemetry below)
export HEFESTO_TELEMETRY=0                            # Disable usage events

# PRO/OMEGA only (read by the private distribution, ignored by the FREE tier)
export HEFESTO_LICENSE_KEY="your-key"

# API Security (PRO, v4.7.0) -- used by `hefesto serve`
export HEFESTO_API_KEY="your-api-key"                # Enable API key auth
export HEFESTO_RATE_LIMIT_PER_MINUTE=60               # Enable rate limiting
export HEFESTO_CORS_ORIGINS="https://app.example.com" # Restrict CORS
export HEFESTO_EXPOSE_DOCS=1                          # Enable /docs, /redoc
export HEFESTO_WORKSPACE_ROOT="/srv/code"              # Path sandbox root
export HEFESTO_CACHE_MAX_SIZE=1000                     # Cache size limit
export HEFESTO_CACHE_TTL_SECONDS=300                   # Cache entry TTL

配置文件（.hefesto.yaml）

将每次运行时都需要重复指定的 hefesto analyze 选项放入 .hefesto.yaml（或 .hefesto.yml）文件中，通常放在仓库根目录：

# .hefesto.yaml -- every key is optional and maps to a `hefesto analyze` flag
severity: MEDIUM            # --severity      LOW | MEDIUM | HIGH | CRITICAL
fail_on: HIGH               # --fail-on       LOW | MEDIUM | HIGH | CRITICAL
output: text                # --output        text | json | html
exclude:                    # --exclude       list or "a/,b/" string
  - tests/
  - node_modules/
exclude_types:              # --exclude-types list or comma-separated string
  - VERY_HIGH_COMPLEXITY
  - LONG_FUNCTION
quiet: false                # --quiet
max_issues: 50              # --max-issues
format_check: true          # --format-check  (needs: pip install "hefesto-ai[format]")
enable_memory_budget_gate: false  # --enable-memory-budget-gate
copybook_paths:             # --copybook-path (COBOL copybook directories outside the scan)
  - ../copylib              # relative paths are resolved from this file's directory
include_vendored: false     # --include-vendored (analyze vendored/minified JavaScript too)

• 默认排除： .venv/、venv/、.tox/、node_modules/、.git/、__pycache__/、dist/、build/、.mypy_cache/、.pytest_cache/、.eggs/、*.egg-info/（分析路径下的整个路径组件），以及供应商提供和经过压缩的 JavaScript（.js、.mjs、.cjs）：*.min.js / *-min.js 文件、vendor/、vendors/、bower_components/ 或 jspm_packages/ 下的文件，以及 static/、assets/、public/ 或 wwwroot/ 内的 lib/、libs/、plugins/、third_party/ 或 thirdparty/ 目录下的文件（例如 static/js/libs/jquery.js）。 顶层的 lib/ 属于项目自身代码，仍会纳入分析；vendor/ 下的非 JavaScript 文件（Go、PHP）也一样。--include-vendored（或 include_vendored: true）会重新分析这些 JavaScript 文件；在命令行中指定的单个文件始终会被分析。 摘要会说明有多少文件被排除（N files skipped as vendored (use --include-vendored)；JSON 中为 meta.vendored_skipped，SARIF 中为工具通知）。

• critical_tests（预览）： 可选部分，用于将需求映射到 pytest 测试，以供关键测试回归保护使用。hefesto analyze 会验证此部分，但不会以其他方式使用它；请参阅 docs/critical-tests.md。

• exclude 条目是路径片段，而不是 glob 模式。 每个条目都匹配分析路径下的完整路径组件（tests/fixtures/ 会跳过 tests/fixtures/...）；* 和 ** 会按字面处理，因此 tests/fixtures/** 或 *.json 什么也匹配不到，尽管“Excluding: ...”中会列出它们。在命令行中明确指定的文件或目录不会被 exclude 过滤。

• 发现配置文件： Hefesto 从传给 hefesto analyze 的第一个路径开始（若为文件，则从其所在目录开始），向上查找到仓库根目录（第一个包含 .git 的目录）；若不在仓库中，则查找到文件系统根目录。使用距离最近的配置文件。同一目录中同时存在 .hefesto.yaml 和 .hefesto.yml 会报错。指定多个路径时，第一个路径对应的配置会应用于整个运行过程（如果其他路径会选用不同文件，Hefesto 会发出警告）。

• 优先级： 显式标志 > 配置文件 > 内置默认值。即使标志的值与默认值相同，也算显式指定（--severity MEDIUM 会覆盖 severity: LOW）。列表会被替换，而不是合并： --exclude docs/ 会忽略文件中的 exclude。

• 标志： --config PATH 使用指定文件，而不进行搜索；--no-config 忽略配置文件。两者不能同时使用。

• 验证： 未知键、无效值和无效 YAML 会使运行终止，退出代码为 2，并显示指出问题的消息，例如： Error: invalid Hefesto config in /repo/.hefesto.yaml: 'severity' must be one of LOW, MEDIUM, HIGH, CRITICAL (got 'urgent')。 键可以使用 - 或 _（fail-on 或 fail_on）；null 表示“未设置”。

• 正在使用的文件会显示为 Config: <path>（使用 --output json 时输出到 stderr；使用 --quiet 时隐藏）。

• 只有 hefesto analyze 会读取此文件（pr-review 和 GitHub Action 输入不会）。规则阈值（圈复杂度等）、--save-html 以及 PRO 范围/增强标志不能通过此文件配置。

---

与竞品对比

标准	Hefesto	Semgrep	CodeRabbit	Qodo	Snyk
专注于 AI 生成的代码	✅ 主要用途	通用	✅ 是	✅ 是	通用
声明与实际不一致的检测	✅ 核心功能	❌	❌	❌	❌
运行状态真实情况分析器	✅ 5 个分析器	❌	❌	❌	❌
支持的语言	CLI 分析 22 种格式（详情）	多种	多种	多种	多种
设置时间	< 5 分钟，无需配置	配置繁琐	注册云服务	注册云服务	注册云服务
运行位置	本地 CLI / GitHub Action / pre-commit / MCP	本地 / 云端	仅云端	仅云端	云端 / CLI
价格（截至 2026 年 10 月）	免费 OSS / $8/月 PRO / $19/月 OMEGA	免费套餐 / Teams $30/贡献者/月（Code）*	公共仓库免费 / $24/开发者/月（年付）	按点数计费，$0.012/点；无永久免费套餐	免费 / Team $25/月**

*Semgrep Supply Chain 和 Secrets 单独定价。 **Snyk Team 最多支持 10 名开发者；Enterprise 按点数计费。价格来自各供应商的官方定价页面，核查日期为 2026 年 10 月；价格经常变动。

HefestoAI 的定位： 大多数工具会检查代码是否符合其语言规则。HefestoAI 还会检查项目是否符合自身声明：导入项是否与声明的依赖项一致，pyproject.toml、CHANGELOG 和 README 中的版本是否一致，以及 action.yml 和 Dockerfile 是否与其引用的文件一致。

---

自我试用（如实记录）

每次推送到 main 时，我们都会用 HefestoAI 的严格门禁检查 HefestoAI 自身代码。自 2026-04-29 起，门禁一直为 GREEN；达到这一状态花了六周多时间：我们于 2026-03-17 记录了检查结果。

在严格模式下，门禁在我们自己的门禁内部代码中标出了 12 项复杂度问题（2 项 CRITICAL，10 项 HIGH）。我们考虑了三种处理方式：忽略这些问题（否决——这恰恰是我们批评的不一致），永久接受覆盖（否决——理由相同），或从根因着手重构（采纳）。开始着手后，根因重构本身很快就完成了：一个 PR，历时两天编写（2026-04-27 和 04-28），并于 2026-04-29 合并。过程中，我们还在自己的定位文档中发现了一处声明与实际不一致的问题，并记录下来以便修复。

完整的审计和重构历史记录在我们的内部私有仓库中。重构将两个 CRITICAL 函数的圈复杂度从 33 → 1 和 25 → 6，所有辅助函数的复杂度均低于 10。10 项 HIGH 问题由临时覆盖处理，其机制和撤销标准均有文档记录。

---

遥测

CLI 默认会向 PostHog 发送匿名使用事件（随机 ID；analyze 还会发送文件数和问题数、耗时、退出代码、版本、OS、Python，以及 ci/docker/dogfood 和 pypi 或 editable——不包含代码、文件路径、检查结果或仓库名称，且负载中不包含 IP 字段）。可通过 hefesto telemetry disable、HEFESTO_TELEMETRY=0 或 DO_NOT_TRACK=1 关闭。除非设置 telemetry: 1，否则 GitHub Action 不会发送使用事件。另外，hefesto analyze 会向 pypi.org 查询最新版本（超时 1.5 秒，缓存 24 小时）。hefesto telemetry disable 不会停止该检查。从 4.20.3 开始，可通过以下设置跳过检查；4.20.2 及更早版本没有禁用该检查的设置。详情：docs/telemetry.md。

当 HEFESTO_NO_UPDATE_CHECK 设置为 1、true、yes 或 on，当 HEFESTO_TELEMETRY 设置为 0、false、no 或 off，或当 DO_NOT_TRACK 设置为 1、true、yes 或 on 时，将跳过 PyPI 新版本检查，不发送请求，也不写入缓存。使用事件默认仍会启用。Action 的默认值 telemetry: 0 会导出 HEFESTO_TELEMETRY=0，因此不会在运行器上执行该检查。

更新日志

发布历史：CHANGELOG.md。

---

联系方式

• 企业与许可：[email protected]
• 支持与 Bug 报告：[email protected]
• 一般咨询：[email protected]
• GitHub Issues：artvepa80/Agents-Hefesto/issues
• 网站：hefestoai.narapallc.com

许可证

此仓库中的代码采用 MIT License 授权。付费的 PRO 和 OMEGA 功能（单独分发的 hefesto_pro 插件）受 LICENSE-COMMERCIAL.md 中的单独商业条款约束。有关许可的问题，请联系：[email protected]。

---

(c) 2026 Narapa LLC，佛罗里达州迈阿密