{"id":"166dae35-715d-4e24-8c36-926fb1ad2a8b","entityType":"agent","slug":"clawhub-codermoray-halucatch","name":"HaluCatch / 捕幻","canonicalUrl":"https://www.xpersona.co/agent/clawhub-codermoray-halucatch","canonicalPath":"/agent/clawhub-codermoray-halucatch","generatedAt":"2026-10-10T06:42:12.726Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T00:21:06.405Z","emptyReason":null},"description":"Evaluates the reliability of AI Skill execution. Assesses whether a Skill's output is trustworthy, reproducible, and withstands business scrutiny when execut...","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.8K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s17awrvq4xgqd62agbqw8sr4y188fseb:halucatch","sourceUrl":"https://clawhub.ai/codermoray/halucatch","homepage":"https://clawhub.ai/codermoray/skills/halucatch","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/codermoray/halucatch","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/codermoray/skills/halucatch","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":65,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"HaluCatch / 捕幻 technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T00:21:06.405Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T00:21:06.405Z","emptyReason":null},"stars":null,"forks":null,"downloads":1842,"packageName":null,"latestVersion":"1.8.8","tractionLabel":"1.8K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T00:21:06.405Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T00:21:06.405Z","lastCrawledAt":"2026-10-10T00:21:06.405Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T00:21:06.405Z","lastVerifiedAt":null,"highlights":[{"version":"1.8.8","createdAt":"2026-07-12T09:25:31.061Z","changelog":"- Bumped version to 1.8.8. - Removed redundant documentation files (`README.md`, `skill-card.md`) for leaner distribution. - Updated SKILL.md, manifest.json, CHANGELOG.md, FAQ.md, and `halucatch/__init__.py` with cleaned-up details, reflecting latest logic and usage. - No functional changes to core logic; mainly documentation and structural updates.","fileCount":23,"zipByteSize":66824},{"version":"1.8.7","createdAt":"2026-07-12T08:36:43.759Z","changelog":"halucatch 1.8.7 - Updated versioning to 1.8.7 in manifest and SKILL.md. - Improved core evaluation and report generation logic across multiple modules. - Removed deprecated documentation file (skill-card.md). - Adjusted documentation for clarity and alignment with current execution and reporting workflow. - Minor code and structure enhancements for stability and maintainability.","fileCount":24,"zipByteSize":72374},{"version":"1.8.6","createdAt":"2026-07-12T06:11:05.073Z","changelog":"**halucatch 1.8.6 Changelog** - Improved Bash compatibility declaration: Bash tool now only used for running local python3 halucatch_core.py, no network or arbitrary commands. - Cleaned up and clarified SKILL.md; removed references to removed files (config.yaml, skill-card.md). - Enhanced documentation regarding privilege/safety scope and tool boundaries. - Updated version metadata and security notes for increased transparency. - Minor documentation and metadata corrections for consistency and compliance.","fileCount":24,"zipByteSize":72075},{"version":"1.8.5","createdAt":"2026-07-11T16:34:22.827Z","changelog":"halucatch v1.8.5 - Updated internal version to 1.8.5. - Minor wording changes to clarify network security boundaries (now explicitly states \"不建立网络连接\" in hardware limits). - Updated documentation to reflect latest process: reports are always stored in the `reports/` directory. - Removed legacy `skill-card.md` file. - Various code and documentation tweaks to align with new standard three-report workflow.","fileCount":25,"zipByteSize":72064},{"version":"1.8.4","createdAt":"2026-07-11T16:11:11.200Z","changelog":"halucatch v1.8.4 - Improved code risk detection logic in evaluators/code_risks.py, refining risk flagging and evaluation robustness. - Updated internal APIs and documentation to match new assessment workflows. - Enhanced configuration flexibility (config.yaml) for future audit criteria extension. - Maintenance updates and minor bug fixes.","fileCount":25,"zipByteSize":72054},{"version":"1.8.3","createdAt":"2026-07-11T16:01:15.616Z","changelog":"halucatch 1.8.3 - Bumped version to 1.8.3 in metadata and documentation. - Updated documentation and SKILL.md for improved clarity and alignment with recent functionality. - Minor adjustments to config and code files to reflect the new release. - No breaking changes to core features or workflows.","fileCount":25,"zipByteSize":72213},{"version":"1.8.2","createdAt":"2026-07-11T15:46:06.356Z","changelog":"**Minor enhancements and maintenance update:** - Updated version to 1.8.2. - Documentation improvements in CHANGELOG.md, FAQ.md, and SKILL.md for clearer usage and workflow. - Updated configuration files; minor updates to CLI and core Python modules. - Removed legacy skill-card.md file.","fileCount":25,"zipByteSize":72056},{"version":"1.8.1","createdAt":"2026-07-11T15:32:46.920Z","changelog":"**halucatch 1.8.1 — Changelog** - Added a new \"complexity\" evaluator module for more granular analysis. - Expanded and updated multi-dimensional evaluation logic (L2), including code, data, rules, and guardrails. - Improved the report generation workflow; all outputs are now written to a dedicated \"reports/\" subdirectory in the target Skill folder. - Updated documentation (SKILL.md, FAQ.md) with clearer guidance on security, workflow responsibilities, and capability boundaries. - Enhanced configuration and classifier logic for improved Skill classification and parameter management. - Removed outdated \"skill-card.md\" file as part of documentation cleanup.","fileCount":25,"zipByteSize":71254}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17awrvq4xgqd62agbqw8sr4y188fseb:halucatch","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17awrvq4xgqd62agbqw8sr4y188fseb:halucatch` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/codermoray/halucatch before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-codermoray-halucatch/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-codermoray-halucatch/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-codermoray-halucatch/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-codermoray-halucatch/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-codermoray-halucatch/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-codermoray-halucatch/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T06:42:12.720Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-codermoray-halucatch/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-codermoray-halucatch/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-codermoray-halucatch/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-codermoray-halucatch/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T00:21:06.405Z","emptyReason":null},"readme":"Skill: HaluCatch / 捕幻\n\nOwner: codermoray\n\nSummary: Evaluates the reliability of AI Skill execution. Assesses whether a Skill's output is trustworthy, reproducible, and withstands business scrutiny when execut...\n\nTags: latest:1.8.8\n\nVersion history:\n\nv1.8.8 | 2026-07-12T09:25:31.061Z | auto\n\n- Bumped version to 1.8.8.\n- Removed redundant documentation files (`README.md`, `skill-card.md`) for leaner distribution.\n- Updated SKILL.md, manifest.json, CHANGELOG.md, FAQ.md, and `halucatch/__init__.py` with cleaned-up details, reflecting latest logic and usage.\n- No functional changes to core logic; mainly documentation and structural updates.\n\nv1.8.7 | 2026-07-12T08:36:43.759Z | auto\n\nhalucatch 1.8.7\n\n- Updated versioning to 1.8.7 in manifest and SKILL.md.\n- Improved core evaluation and report generation logic across multiple modules.\n- Removed deprecated documentation file (skill-card.md).\n- Adjusted documentation for clarity and alignment with current execution and reporting workflow.\n- Minor code and structure enhancements for stability and maintainability.\n\nv1.8.6 | 2026-07-12T06:11:05.073Z | auto\n\n**halucatch 1.8.6 Changelog**\n\n- Improved Bash compatibility declaration: Bash tool now only used for running local python3 halucatch_core.py, no network or arbitrary commands.\n- Cleaned up and clarified SKILL.md; removed references to removed files (config.yaml, skill-card.md).\n- Enhanced documentation regarding privilege/safety scope and tool boundaries.\n- Updated version metadata and security notes for increased transparency.\n- Minor documentation and metadata corrections for consistency and compliance.\n\nv1.8.5 | 2026-07-11T16:34:22.827Z | auto\n\nhalucatch v1.8.5\n\n- Updated internal version to 1.8.5.\n- Minor wording changes to clarify network security boundaries (now explicitly states \"不建立网络连接\" in hardware limits).\n- Updated documentation to reflect latest process: reports are always stored in the `reports/` directory.\n- Removed legacy `skill-card.md` file.\n- Various code and documentation tweaks to align with new standard three-report workflow.\n\nv1.8.4 | 2026-07-11T16:11:11.200Z | auto\n\nhalucatch v1.8.4\n\n- Improved code risk detection logic in evaluators/code_risks.py, refining risk flagging and evaluation robustness.\n- Updated internal APIs and documentation to match new assessment workflows.\n- Enhanced configuration flexibility (config.yaml) for future audit criteria extension.\n- Maintenance updates and minor bug fixes.\n\nv1.8.3 | 2026-07-11T16:01:15.616Z | auto\n\nhalucatch 1.8.3\n\n- Bumped version to 1.8.3 in metadata and documentation.\n- Updated documentation and SKILL.md for improved clarity and alignment with recent functionality.\n- Minor adjustments to config and code files to reflect the new release.\n- No breaking changes to core features or workflows.\n\nv1.8.2 | 2026-07-11T15:46:06.356Z | auto\n\n**Minor enhancements and maintenance update:**\n\n- Updated version to 1.8.2.\n- Documentation improvements in CHANGELOG.md, FAQ.md, and SKILL.md for clearer usage and workflow.\n- Updated configuration files; minor updates to CLI and core Python modules.\n- Removed legacy skill-card.md file.\n\nv1.8.1 | 2026-07-11T15:32:46.920Z | auto\n\n**halucatch 1.8.1 — Changelog**\n\n- Added a new \"complexity\" evaluator module for more granular analysis.\n- Expanded and updated multi-dimensional evaluation logic (L2), including code, data, rules, and guardrails.\n- Improved the report generation workflow; all outputs are now written to a dedicated \"reports/\" subdirectory in the target Skill folder.\n- Updated documentation (SKILL.md, FAQ.md) with clearer guidance on security, workflow responsibilities, and capability boundaries.\n- Enhanced configuration and classifier logic for improved Skill classification and parameter management.\n- Removed outdated \"skill-card.md\" file as part of documentation cleanup.\n\nv1.7.8 | 2026-07-06T16:54:21.333Z | user\n\nv1.7.8: Added permissions & safety boundaries declaration, pre-execution path confirmation, FAQ security improvements\n\nv1.7.7 | 2026-07-02T17:30:09.054Z | auto\n\nHaluCatch 1.7.7 — Streamlined output and improved documentation.\n\n- Report generation is now handled entirely by halucatch_core.py; you no longer need to draft report content independently.\n- Only the standard (plain-language) report is shown by default; technical and action versions are provided on request.\n- Removed the legacy skill-card.md file.\n- SKILL.md updated to clarify output procedure and workflow, emphasizing strict script-based report generation.\n- Minor improvements and clarifications in configuration and user instructions.\n\nv1.7.6 | 2026-07-02T16:57:35.504Z | auto\n\n# HaluCatch 1.7.6 Changelog\n\n- Major workflow change: 全流程评估和报告生成由 `halucatch_core.py` 一次性完成，AI 只负责展示和补充（无需独立撰写报告正文）。\n- 三份报告（专业版、标准版、行动版）全部自动生成并落盘，AI 仅读取输出，不再编写主报告内容。\n- 报告展示及补充范围限定为基于脚本结果的语义补充，新增明确分工说明。\n- 精简和统一文档说明，移除冗余 skill-card.md。\n- 修订执行流程与分工；确保报告格式、输出流程和落盘目录完全对齐新版代码。\n\nv1.7.5 | 2026-07-02T14:41:38.139Z | auto\n\n- 删除了大量辅助和文档文件，保留核心 skill 说明与主要配置。\n- 增加 CHANGELOG.md 和 FAQ.md，统一文档入口。\n- 报告自检声明改为“报告检查声明”，相关表述略有调整。\n- SKILL.md 内容微调，“自检行”更名为“检查行”，具体提示语有所变化。\n- 总体精简目录结构，去除冗余、历史、示例性输出和配置文件。\n\nv1.7.4 | 2026-07-02T14:02:31.049Z | auto\n\n**Summary:**  \n新增了面向 DID 质检与固化的输出文档，增强质检及自查能力。\n\n- 新增 outputs/MyCoach_DID_质检与固化指南/ 目录，包含角色设定、问题清单、修复模板、自查清单等文档，支持 Skill 质量控制和固化流程。\n- 增加 cliff.toml 配置文件，便于项目管理或持续集成。\n- 完善 SKILL.md 及 _meta.json，反映新增加的质检流程和使用方式。\n- 扩展技能自查、修复方案和反馈操作指引，为用户闭环 Skill 评估与修复全流程。\n- 其他文档和结构优化，提升使用清晰度和可操作性。\n\nv1.7.3 | 2026-07-01T11:36:41.493Z | auto\n\n**HaluCatch 1.7.3 Changelog**\n\n- 更新 SKILL.md，优化部分描述，调整格式，完善说明，无核心功能调整\n- 规范文档结构以提升可读性和易用性\n- 未涉及核心执行逻辑和 API 变更\n- 兼容 1.7.2，升级推荐用于文档完善需要\n\nv1.7.2 | 2026-07-01T09:42:48.684Z | auto\n\nHaluCatch 1.7.2\n\n- 文档补充：增加了更多常用触发场景和用户问法示例，提升易用性。\n- 扩展「更多触发示例」分节，详述不同审查深度与Skill类型下的调用方式。\n- 新增路径格式建议和异常处理常见问答，便于用户排查常见错误。\n- 其它细节优化，增强指导性，说明 Skill 报告如何落盘和自检。\n\nv1.7.1 | 2026-07-01T09:34:47.318Z | auto\n\n- Major update: Refactored halucatch as a Python module with modularized core logic and report generation.\n- Added `halucatch/` package with submodules for CLI, configuration, scanning, classification, evaluation, and reporting.\n- Introduced new evaluator modules specializing in code risk, methodology, rules, foundation, and guardrails.\n- Improved report generation: now outputs action, technical, and plain-language markdown versions automatically.\n- Updated documentation for clearer data requirements, input assumptions, and audit workflow.\n- Now supports structured execution with enhanced file scanning and phase-based reliability assessment.\n\nv1.7.0 | 2026-06-26T17:27:56.771Z | auto\n\n- 支持根据用户语言自动添加 `--lang` 参数给核心脚本，无需手动配置，提升多语言体验。\n- 新增“AI 执行指南”部分，明确语言自动检测与参数配置规则。\n- 移除 skill-card.md 文件，精简项目结构。\n- 优化文档说明，补充用法示例和细化输入输出规范。\n- 其它小幅完善文档和元信息，保持流程与报告结构不变。\n\nv1.6.9 | 2026-06-18T07:19:40.873Z | auto\n\nHaluCatch 1.6.9\n\n- 默认输出报告目录调整为 `HaluCatch/reports/`，避免污染目标 Skill 目录  \n- 新增 `--output-dir` 自定义输出路径  \n- 修复包保存位置变更为 `{Skill目录}/halucatch-fix/`\n- 文档同步，细化落盘与输出行为说明\n\nv1.6.8 | 2026-06-18T06:46:12.952Z | auto\n\nHaluCatch 1.6.8\n\n- 更新 version 至 1.6.8，并同步元数据。\n- 优化文档，调整细节表达，提升说明准确性与可操作性。\n- 说明未涉及功能或输出语义上的变更，仅为描述和文档改进。\n\nv1.6.7 | 2026-06-18T05:02:51.478Z | auto\n\n- Updated version to 1.6.7.\n- Documentation revised for clarity and consistency across README and SKILL.md.\n- Adjusted and clarified some execution and report output procedures.\n- Minor improvements to descriptions and workflow explanations for both technical and non-technical users.\n- No changes to the core review logic or external interface.\n\nv1.6.6 | 2026-06-18T04:10:19.440Z | auto\n\nHaluCatch v1.6.6\n\n- 文档同步更新，完善 SKILL.md，优化部分表述，确保与现有实现一致\n- 更新版本号至 1.6.6\n- 无核心逻辑变动，仅修订文档和元数据\n- 保持所有审查与修复流程不变\n\nv1.6.5 | 2026-06-18T03:50:36.590Z | auto\n\nHaluCatch 1.6.5 更新说明\n\n- 更新 SKILL.md 文档，将版本号提升至 1.6.5，内容结构优化但执行逻辑未改动。\n- 近期更新仅涉及文档（README、SKILL.md 等），无核心功能/逻辑变更。\n- 核心执行流程、能力边界定义和用户交互细则均保持原有设计。\n\nv1.6.4 | 2026-06-18T03:30:32.987Z | auto\n\n**HaluCatch 1.6.4 Changelog**\n\n- Added: English README (`README.en.md`) for broader accessibility.\n- Updated: Skill metadata (`SKILL.md`, `_meta.json`)—now supports enhanced tagging and improved clarity in instructions.\n- Refined: Documentation in `README.md` and core skill logic in `halucatch_core.py`, aligning code and docs with latest workflow and terminology.\n- Removed: Deprecated `skill-card.md` to streamline documentation.\n\nv1.6.0 | 2026-06-17T14:47:41.661Z | auto\n\nhalucatch 1.6.0 更新说明：\n\n- 完全重写 SKILL.md，详细定义四阶段评审流程和多维审查标准。\n- 明确区分“代码工程型”与“纯方法论型”Skill，针对不同类型细化审查要点和评级体系。\n- 三层执行模型：L1/L2 脚本负责结构化检查，L3 由你执行语义补充与三版报告生成。\n- 引入“专业版”、“通俗版”、“AI 行动版”三份报告，并规范报告落盘与输出流程。\n- 新增审查闭环：报告输出后自动询问是否修复，支持修复方案生成与后续增量评审机制。\n- 全面细化每一维指标，提升 Skill 可靠性、可复现性及业务合规性。\n\nArchive index:\n\nArchive v1.8.8: 23 files, 66824 bytes\n\nFiles: CHANGELOG.md (13073b), FAQ.md (11129b), halucatch_core.py (642b), halucatch/__init__.py (77b), halucatch/__main__.py (104b), halucatch/classifier.py (702b), halucatch/cli.py (7697b), halucatch/config.py (12476b), halucatch/evaluators/__init__.py (506b), halucatch/evaluators/code_risks.py (15713b), halucatch/evaluators/complexity.py (23619b), halucatch/evaluators/foundation.py (2921b), halucatch/evaluators/guardrails.py (9749b), halucatch/evaluators/methodology.py (3044b), halucatch/evaluators/rules.py (3245b), halucatch/README.md (1992b), halucatch/reporter.py (19522b), halucatch/scanner.py (8426b), LICENSE (1067b), manifest.json (690b), skill-card.md (2148b), SKILL.md (21609b), _meta.json (128b)\n\nFile v1.8.8:SKILL.md\n\n---\nname: halucatch\ndescription: |\n  Evaluates the reliability of AI Skill execution. Assesses whether a Skill's output is trustworthy, reproducible, and withstands business scrutiny when executed by an AI agent. Covers four dimensions: data pipeline integrity, code risk, business logic ambiguity, and interpretation guardrails. Use when auditing an AI Skill, checking for hallucinations or unreliable outputs, verifying execution reproducibility, or reviewing a Skill's safety before deployment or sharing.\nsummary: AI Skill 执行可靠性审查工具。评估一个 Skill 被 AI 执行时，结果是否可信、是否可复现、是否经得起业务推敲。覆盖四维度：地基（数据管线）、代码、规则（业务口径）、护栏（解读指南）。\nlicense: MIT\nallowed-tools:\n  - Read\n  - Write\n  - Bash\ncompatibility: Requires Python 3.8+; Bash only for local 'python3 halucatch_core.py', no network/arbitrary commands\nauthor: CoderMoray\nversion: 1.8.8\nmetadata:\n  hermes:\n    tags:\n    - skill-audit\n    - reliability\n    - engineering-assurance\n    - Skill审查\n    - 工程质量\n    - 可靠性\n  openclaw:\n    requires:\n      bins:\n      - python3\n    emoji: 🔍\n    homepage: https://github.com/CoderMoray/HaluCatch\nslug: halucatch\ndisplayName: HaluCatch / 捕幻\ntags:\n  - skill-audit\n  - reliability\n  - engineering-assurance\n  - Skill审查\n  - 工程质量\n  - 可靠性\n---\n> **一句话总结**：把一个 AI Skill 的文件夹扔给 HaluCatch，它会逐项检查数据管线、代码逻辑、业务规则、安全护栏有没有漏洞，然后给你三份报告（标准版看全貌、专业版看细节、行动版直接修），全程几秒钟、完全离线。\n>\n> [快速开始](#1-入口逻辑) · [能力边界](#能力边界) · [输出解读](#5-报告)\n\n# HaluCatch / 捕幻 — AI Skill 执行可靠性审查\n\n评估一个 Skill 包在 AI 执行时的可靠性，产出评估报告和修复建议（建议需用户确认后才执行，不自动修改目标 Skill）。\n\n---\n\n## 能力边界\n\n| 擅长 | 不擅长 |\n|------|--------|\n| 评估 AI 执行 skill 时会否出错 | 网络安全审查（SQL 注入、XSS 等） |\n| 检查数据管道是否可靠 | 合规性审查（GDPR、隐私法规等） |\n| 发现自然语言业务规则的歧义 | Skill 本身的业务正确性（不懂业务逻辑） |\n| 检查解读护栏是否到位 | 代码性能优化 |\n| 输出修复建议和骨架脚本 | 替换人工业务决策 |\n\n**硬件限制：** 单文件上限 10 MB（超大文件会被跳过并提示），不支持批量审查（一次一个目录），不支持二进制文件，不建立网络连接（仅通过本地 Python 脚本运行）。审查耗时取决于目录下文件数量和大小，通常几秒到几十秒。\n\n---\n\n## 角色\n\n当用户调用 HaluCatch 时，**你就是 HaluCatch 审查执行者**，而非旁观者。\n\n### 职责\n\n- 调用 `halucatch_core.py` **一次性完成全流程**（L1 扫描 + L2 评估 + L3 报告生成）\n- 读取脚本生成的报告文件，对话中展示标准版，询问是否修复\n- 在脚本报告基础上做语义补充：按需读取报告中引用的源文件，提供上下文分析（`info` 级别条目）\n- **不要自己读取目标目录的文件**——文件扫描由脚本完成，AI 读取只会浪费 token\n\n### 你与 halucatch_core.py 的分工\n\n| 层级 | 任务 | 执行方 | 原则 |\n|------|------|--------|------|\n| **L1** | 文件扫描 | `halucatch_core.py --validate` | 确定性高，脚本更快更准 |\n| **L2** | 地基 + 代码 + 规则 + 护栏检查 | 脚本取 JSON 基线 → **你在此基础上补充分析** | 正则匹配靠脚本，上下文解读靠你 |\n| **L3** | 三版报告生成 | `halucatch_core.py` **生成并落盘**，你读取后展示给用户 | `reporter.py` 确定性高、格式一致、零幻觉——你只需做语义补充 |\n\n> **核心原则**：`halucatch_core.py` 涵盖全流程——L1 扫描、L2 评估、L3 报告生成一次性完成。你只需读取脚本生成的报告并展示给用户。不再由 AI 独立编写报告正文。\n\n## 权限与安全边界\n\n**⚠️ 写入警告：HaluCatch 会生成报告文件写入目标目录的 `reports/` 子目录，并可能产出修复指引（需用户确认后才应用）。这不是纯只读工具。**\n\nHaluCatch 仅需要以下权限即可运行：\n\n| 操作 | 需要 | 说明 |\n|------|------|------|\n| 读取目标 Skill 目录 | Read | 递归读取全部文件 |\n| 写入报告文件 | Write | 仅写入目标目录内的 `reports/` 子目录，不修改 Skill 源文件 |\n| 执行 Python 脚本 | Bash | 仅执行本地 `halucatch_core.py`，不访问网络、不执行外部命令 |\n\n**安全约束**：HaluCatch 不会访问目标目录以外的任何路径，不会发起网络连接。Bash 权限仅用于运行自带的 Python 审查脚本，不会执行非本项目代码。审查前必须由用户显式指定目标路径。\n\n---\n\n## 输入\n\n用户提供一个 Skill 文件夹路径。该文件夹可能包含：\n\n| 文件类型 | 是否必需 | 说明 |\n|---------|---------|------|\n| `SKILL.md` | ✅ | Skill 的主指令文件 |\n| `manifest.json` 或 `config.yaml` | ❌ | Skill 配置文件（含版本号等） |\n| `*.py` | ❌ | 数据管线的固化脚本（如有） |\n| `*.xlsx / *.csv` 等 | ❌ | 数据文件（如有，用于验证对账） |\n\n### 数据要求\n\n- **时效性**：审查基于目标 Skill 目录的即时快照，不追溯历史版本。\n- **数据范围**：仅评估目标目录中可见的文件，不爬取外部依赖或网络资源。\n\n### 前提假设\n\n- 目标目录存在且有读取权限。\n- 目标 Skill 应包含至少一个 `SKILL.md` 文件（规范名称）。如有其他 `.md` 文件，AI 将尝试启发式匹配，但会报告规范性问题。\n- 目录中的 `.py` 文件视为 Skill 核心执行脚本，非第三方依赖库。\n\n## AI 执行指南\n\n### 语言自动检测\n\nAI 在加载本 Skill 时，应从系统提示（`<response_language>`）或对话上下文判断用户语言，然后自动添加 `--lang` 参数：\n\n| 用户语言 | 参数 | 示例 |\n|-----------|------|------|\n| 中文（简体/繁体） | `--lang zh-CN` | `python3 halucatch_core.py --skill-dir <path> --lang zh-CN` |\n| 英文 | `--lang en` | `python3 halucatch_core.py --skill-dir <path> --lang en` |\n| 不确定 | 不添加（默认 `auto`，自动检测系统 locale） | `python3 halucatch_core.py --skill-dir <path>` |\n\n**原则**：AI 肯定知道用户用什么语言，不需要用户手动配置。\n\n### 基本用法\n\n```bash\n# 为中文用户审查\npython3 halucatch_core.py --skill-dir /path/to/skill --lang zh-CN\n\n# 为英文用户审查\npython3 halucatch_core.py --skill-dir /path/to/skill --lang en\n\n# 自动检测（fallback）\npython3 halucatch_core.py --skill-dir /path/to/skill\n```\n\n---\n\n## 执行流程\n\n> **执行范式**：各 Phase 按三层调用模型分配职责。`halucatch_core.py` 一次性完成 L1/L2/L3，你读取生成的报告文件并展示给用户。\n\n### Phase 0：技能分类\n\n首先判断这个 Skill 的类型：\n\n```\n这个 Skill 涉及数据处理吗？\n  ├─ ❌ 纯方法论型（指令/模板/文档类）\n  │    评估重点：指令完备性、逻辑自洽、可复现性\n  │\n  ├─ ✅ 代码工程型（含 .py / 数据文件 / md 内嵌代码）\n  │    评估重点：地基 + 代码 + 规则 + 护栏\n  │\n  └─ ⚠️ 不确定\n        → 询问用户：「这个 Skill 有数据处理步骤吗？」\n```\n\n如果文件夹中存在 `.xlsx`、`.csv`、`.py`（含 `pd.read_`、`pd.DataFrame`）等文件或内容，默认按「代码工程型」处理。\n\n### Phase 1：文件扫描\n\n读取文件夹中的全部文件并构建清单：\n\n| 信息点 | 输出形式 |\n|--------|---------|\n| 文件名列表 | 表格（文件名/大小/类型） |\n| SKILL.md 总行数 | 数字 |\n| .py 文件行数（如有） | 数字 |\n| 数据文件列表 | 表格 |\n| Skill 名称和描述 | 从 frontmatter 提取 |\n\n### Phase 2：多维评估\n\n根据 Phase 0 的分类执行对应的评估维度的检查。\n\n---\n\n### 2a. 代码工程型 Skill 评估\n\n#### 🏗️ 地基评估\n\n检查 Skill 的数据管线是否稳固。地基越弱，AI 自主写代码出错的概率越高。\n\n| 检查项 | 通过标准 |\n|--------|---------|\n| 有固化 .py 脚本 | 脚本存在于文件夹中 |\n| 路径参数化 | 硬编码路径数 = 0 |\n| 列名预检/输入验证 | 有 `check_columns` 或类似函数 |\n| validate 模式 | 有 `--validate` 或类似模式 |\n| 文件发现机制 | 使用 glob/通配符而非固定文件名 |\n| 依赖声明 | 在 SKILL.md 中声明了所需的 Python 包 |\n| skiprows 参数化 | Excel 读取行数可配置或自动检测 |\n\n**评级**：🟢 稳固 / 🟡 有隐患 / 🔴 无地基\n\n---\n\n#### 🤖 代码风险评估\n\n如果 SKILL.md 中嵌入了 Python 代码（AI 须逐字复现），检查以下篡改点：\n\n| 检查类别 | 高风险模式 | AI 可能误改的行为 |\n|---------|-----------|----------------|\n| 统计函数 | 自定义 p-value 公式、Z-score 计算 | 替换为 `scipy.stats` / 调整常数 |\n| 字符串匹配 | `clean_rate()` 中解析百分比 | 替换 `replace('%','')` 为不同写法 |\n| 浮点比较 | `== 0` / `== 1` | 改为 `math.isclose()`（语义不同） |\n| 异常处理 | 裸 `except: pass` | 改为具体异常类型 |\n| 条件逻辑 | `(条件).sum() > 0` | 改为 `.any(axis=1)`（行为不同） |\n| 聚合逻辑 | `unstack(fill_value=0)` | 移除 `fill_value`（NaN 传播） |\n| 数据清洗 | 无数据类型转换指令 | 可能对字符串列做 `sum()` 报错 |\n\n**评级**：🟢 低风险 / 🟠 有风险 / 🔴 高风险\n\n---\n\n#### 📝 规则与口径评估\n\n检查业务规则在 SKILL.md 中的描述是否明确、无歧义：\n\n| 检查项 | 风险 |\n|--------|------|\n| 渠道/分类口径是否明确列举 | 歧义 → AI 自行猜测 |\n| 异常值/边界条件是否定义 | 遗漏 → AI 自行处理 |\n| 代际/映射关系是否固化（而非依赖 AI 知识） | 未固化 → 不同 AI 产出不同结果 |\n| 同店/同比等对比口径是否定义 | 未定义 → AI 自行决定，不可审计 |\n| 特殊纠偏规则（如海南聚时）是否文档化 | 未文档化 → 遗漏关键业务逻辑 |\n| 文件名/列名/数据格式是否约定 | 未约定 → 跑不通 |\n\n**评级**：🟢 清晰 / 🟡 有歧义 / 🔴 重大遗漏\n\n---\n\n#### 🛡️ 解读护栏评估\n\n检查 SKILL.md 是否约束 AI 对结果的解读方式：\n\n| 检查项 | 严重度 |\n|--------|--------|\n| 有因果语言禁令 | 缺失 → 🔴 严重 |\n| 有四象限/效应量框架 | 缺失 → 🟠 高 |\n| 有自检机制（self-check） | 缺失 → 🟠 高 |\n| 有多重比较提醒 | 缺失 → 🟠 高 |\n| 有限制性声明模板 | 缺失 → 🟠 高 |\n| 有阶段性状态输出 | 缺失 → 🟡 中 |\n| 有数据概要统计打印 | 缺失 → 🟡 中 |\n| 有输出格式定义 | 缺失 → 🟡 中 |\n\n**评级**：🟢 完善 / 🟡 缺项 / 🔴 无护栏\n\n---\n\n### 2b. 纯方法论型 Skill 评估\n\n| 检查项 | 说明 |\n|--------|------|\n| 指令完备性 | 每个步骤都有明确的输入/输出/判断条件 |\n| 边界情况 | 是否有「如果…则…」的异常分支处理 |\n| 可复现性 | 不同 AI 执行是否会得到一致的结论 |\n| 示例驱动 | 是否包含具体示例来说明期望输出 |\n| 输出格式定义 | AI 的输出结构是否被约束 |\n| 自我验证 | Skill 执行结果能否自洽检查 |\n\n**评级**：🟢 可靠 / 🟡 有改进空间 / 🔴 不可靠\n\n---\n\n> ⚠️ **执行前确认**：在开始扫描文件、运行 `halucatch_core.py`、或生成报告之前，必须先向用户确认目标路径无误，并告知即将执行的操作（读取目标目录文件、运行本地脚本、生成报告到 reports/ 目录）。未明确确认前不得执行任何读写操作。\n\n### Phase 3：三版输出\n\n**核心变更**：报告由 `halucatch_core.py`（`reporter.py`）自动生成，你**不再需要独立撰写报告正文**。你只负责：\n1. 读取脚本生成的报告文件\n2. 对话中展示标准版\n3. 在已生成的报告基础上做补充语义分析（关联 `info` 级别条目）\n\n**输出决策规则**：三版报告**始终由脚本生成并存盘**，对话中只展示标准版。\n\n1. 运行 `halucatch_core.py --skill-dir <路径>` → 脚本自动完成 L1 扫描 + L2 评估 + L3 报告生成\n2. 三份 `.md` 文件写入 `reports/` 目录（或 `--output-dir` 指定路径）\n3. 对话中只输出**标准版**（白话、零术语）\n4. 标准版末尾附带提示：「需要看技术细节（专业版）或修复方案（行动版）吗？」\n5. 如果用户说「要」→ 对话中展示对应版本内容（文件已在磁盘上，直接读取展示）\n6. 如果用户没回应 → 不主动输出，不造成信息过载\n\n#### 1. 专业版（给数据分析师/工程人员）\n\n由 `reporter.py` 自动生成，包含 TL;DR 摘要、四维评级矩阵表、逐维度发现清单、检查声明。\n\n#### 2. 标准版（给业务方/非技术人员）\n\n由 `reporter.py` 自动生成，包含白话摘要、21 条语境解释映射、无术语输出。\n\n#### 3. AI 行动版（供给修复阶段使用）\n\n由 `reporter.py` 自动生成，包含修复清单、验证检查点、三选一步骤提示。\n\n#### 报告检查声明\n\n所有三版报告末尾必须包含检查行：\n\n```markdown\n> 本报告由 HaluCatch 生成。检查进度: [✅ HaluCatch 四维评估全部执行完毕 / ⚠️ 部分评估维度未完成]。\n```\n\n如果评估过程中有维度未覆盖（如代码工程型 Skill 但用户未提供 .py 文件），检查等级降为 ⚠️。\n\n#### AI 语义补充（在脚本报告基础上）\n\n读取脚本生成的报告后，逐条审查发现，按严重度从高到低做上下文分析：\n\n| 原评级 | AI 需要判断 |\n|--------|-----------|\n| 🔴 阻塞 | 这条风险在实际业务中到底多严重？是否真的会导致执行失败？修复优先级？ |\n| 🟠 高危 | 上下文是否真的构成风险？有没有脚本误报的可能？修复方案是否需要细化？ |\n| 🟡 提示 | 跳过项是否真的合理？有没有脚本漏掉但实际重要的风险？ |\n| 🟢 通过 | ✅ 脚本判断正确，无需补充 |\n\n输出格式：在每个发现条目下方追加一行 `> **AI 分析**: [具体判断]`。\n\n#### 报告审查前检查\n\n报告生成后、向用户展示或提交前，**必须**先检查标准版报告中是否存在 `⚠️ 疑似外部 Skill` 标记。\n\n**如存在**：不做 `present_files`，向用户确认（优先用交互弹窗；不支持弹窗的平台改用文字列出选项，等用户回复 1/2/3）：\n\n> ⚠️ 发现疑似外部 Skill 目录。`skills/` 是外部安装的 Skill（非本项目代码）吗？→ 确认后我会同步更新 HaluCatch 运行配置，之后自动跳过。\n\n选项（标题「外部 Skill 确认」）：\n1. 「是，跳过 skills/」→ 设 `skills_is_external: true`，重跑审查\n2. 「否，正常扫描」→ 设 `skills_is_external: false`，重跑审查\n3. 「不确定，保留标记」→ 保持现状，报告自动标注 `[⚠️ 疑似外部 Skill]`，继续展示\n\n---\n\n### Phase 4：修复决策与闭环\n\n评估完成后，向用户展示标准版报告并询问：\n\n> 检测到 [N] 项风险。是否按建议方案修复？\n\n- **用户「修」** → 生成修复方案，然后展示三选一：\n\n  > 修复方案已生成。请选择：\n  > 1. **执行修复** — 将修复方案发给你的 AI，让它按方案修改目标 Skill\n  > 2. **不执行** — 不做任何修改，结束本次审查\n  > 3. **我有更好的意见** — 描述你的想法，我据此重新生成修复方案\n\n  - 用户选「执行」→ 提示用户让 AI 应用修复 → 提示修复后重新运行 HaluCatch 验证\n  - 用户选「不执行」→ 结束\n  - 用户选「建议」→ 重新分析追加需求 → 回到「生成修复方案」\n\n- **用户「不修」** → 结束\n\n---\n\n## 报告落盘\n\n- 缺省输出到 `reports/` 目录（目标 Skill 目录内）\n- 指定 `--output-dir` 则输出到自定义路径\n\n---\n\n## 更多触发示例\n\n### 按审查深度\n\n| 用户说 | AI 执行动作 |\n|--------|-----------|\n| 「帮我审一下这个 Skill，看看靠不靠谱」 | 完整流程：分类 → 四维评估 → 三版报告 |\n| 「快速扫一眼，有没有明显的坑」 | 仅做 Phase 1 扫描 + Phase 2 L1/L2 规则检查，输出一份精简 checklist |\n| 「这次只关注代码有没有除零/裸 except 这种硬伤」 | 跳过规则和护栏维度，只跑地基 + 代码检查 |\n| 「上次审查后我改了 SKILL.md，帮我再跑一遍对比一下」 | 重新审查，对比上次报告，标注修复状态 |\n\n### 按 Skill 类型\n\n| 用户说 | AI 执行动作 |\n|--------|-----------|\n| 「我的 Skill 里有个 data/ 文件夹和 .py 脚本，帮我全面审」 | 分类为代码工程型，四维全覆盖 |\n| 「这是一个纯指引文档类 Skill，帮我看看指令写得清楚不清楚」 | 分类为纯方法论型，仅评估方法论和护栏 |\n\n### 路径写法（不同平台差异）\n\n| 平台 | 正确写法 | ❌ 错误写法 |\n|------|---------|-----------|\n| Claude Code / 通用 | `/path/to/skill` | `C:\\\\path\\\\to\\\\skill` |\n| Kimi / 微信小程序 | `skills/项目名/` | `~/skills/项目名/` |\n| Cursor / VS Code | 拖拽文件夹到对话框 | 手动输入复杂路径 |\n\n### 如果还是不会用\n\n> 直接说：「审查 /path/to/skill」，把 Skill 文件夹拖进来即可。AI 会自行判断接下来的步骤。不要直接贴 SKILL.md 内容——用文件夹路径保证完整性。\n\n---\n\n## 异常处理\n\n### 常见错误及修复\n\n| 错误现象 | 原因 | 修复方法 |\n|---------|------|---------|\n| `❌ 找不到 SKILL.md` | 目标目录不存在或没有 .md 文件 | 确认路径正确 → 检查目录是否有 `SKILL.md` 或其他 `.md` 文件 → 如无，创建一个 |\n| `⚠️ 未找到标准 SKILL.md` | 文件名不是 `SKILL.md`（如 `skill.md`、`README.md`） | 将文件重命名为 `SKILL.md`，或告知 AI 用 `--file` 指定文件名 |\n| `🔧 文件编码异常，已跳过 XXX.py` | 文件包含非 UTF-8 字符（如 GBK 编码的中文注释） | 用编辑器将文件另存为 UTF-8 编码（编码转换不改变内容，仅调整存储方式） |\n| `📦 Skill 包过大（> 2MB）` | 目录包含大量数据文件或依赖包 | 仅保留核心文件（SKILL.md + .py 脚本），数据文件和依赖放入 `.halucatch-ignore` |\n| `⏱️ 审查超时` | 文件过多或脚本执行时间过长 | 告知 AI：「只审查 SKILL.md 和核心 .py 文件」 |\n\n### 错误分级\n\n| 级别 | 行为 |\n|------|------|\n| **致命**（如目录不存在） | 立即终止，提供明确的修复指引 |\n| **警告**（如非标准文件名） | 继续审查但降级自检评分，在报告中标注 |\n| **可恢复**（如单个文件编码问题） | 跳过该文件继续，在报告中标注被跳过的文件及原因 |\n\n---\n\n## 运行稳定性\n\n### 防护措施\n\n| 场景 | 保护策略 |\n|------|---------|\n| 大文件（单个 > 1MB） | 截取前 500 行进行分析，在报告中声明截断 |\n| 大量文件（目录 > 200 个文件） | 按类型筛选（.md → .py → 其他），非核心文件自动跳过 |\n| 脚本执行超时（> 30s） | 终止该步骤，将已验证的部分写入报告，标注未完成项 |\n| 网络请求 | Halucatch **不发起网络请求**，100% 离线运行 |\n| 编码问题 | 先尝试 UTF-8 → 再尝试系统 locale → 失败则跳过并记录 |\n| 目录不可读 | 报告权限错误，建议用户 `chmod` 或换个路径 |\n\n### 可靠性声明\n\n> Halucatch 在正常 Skill 目录（≤ 50 个文件，单文件 ≤ 1MB）上运行稳定。极端情况会自动降级（截断/跳过/终止），不会静默失败。\n\n---\n\n## 反模式与 FAQ\n\n### 常见误区\n\n| 误区 | 正确认知 |\n|------|---------|\n| 「审查一次就够了」 | Skill 每次修改后都应重新审查，尤其是修改 SKILL.md 或关键 .py 文件后 |\n| 「分数低 = 不能用」 | 分数是相对参考。一个「地基弱但规则清晰」的纯方法论型 Skill 可能完全可用 |\n| 「修完所有问题才发布」 | 优先修高优（🔴）和中优（🟠）项，低优项可以渐进改进 |\n| 「AI 行动版报告可以直接执行」 | 行动版是给 AI 的修复指令，需用户确认后再让 AI 执行，防止误改 |\n| 「用 `--validate` 模式跑过就算审查了」 | `--validate` 只做文件扫描和类型分类，不做四维评估。正式审查必须完整跑 |\n\n### FAQ\n\n**Q：我需要准备什么？**\nA：一个包含 `SKILL.md` 的文件夹。如果有 `.py` 脚本或数据文件，一并放入可以评估得更全面。\n\n**Q：审查结果说不通过，我该怎么办？**\nA：看报告中的「AI 行动版」，里面有逐项修复方案。按优先级从高到低修，修完再审查一次验证。\n\n**Q：我的 Skill 没有 Python 代码，能用吗？**\nA：能。HaluCatch 会自动分类为「纯方法论型」，跳过地基和代码检查，重点评估指令完备性和护栏。\n\n**Q：遇到报错怎么办？**\nA：看上方「异常处理」章节。90% 的报错是路径写错或文件名不规范。如果解决不了，把报错信息贴给 AI。\n\n> 💡 **更多问题？** 查看 `FAQ.md`——包含完整的使用指南、常见问题和故障排除。\n\nFile v1.8.8:halucatch/README.md\n\nHaluCatch 模块化拆分 — 设计决策说明\n\n## 目录结构\n\nhalucatch/                    # 核心包\n├── __init__.py               # 导出版本和核心 API（~15 行）\n├── config.py                 # MESSAGES + detect_system_locale（~218 行）\n├── scanner.py                # scan_folder + _extract_version + _strip_string_literals（~166 行）\n├── classifier.py             # classify_skill（~16 行）\n├── evaluators/               # 四维评估 + 自检\n│   ├── __init__.py           # 聚合导出（~30 行）\n│   ├── foundation.py         # check_foundation（~72 行）\n│   ├── code_risks.py         # check_code_risks（~56 行）\n│   ├── rules.py              # check_rules（~85 行）\n│   ├── guardrails.py         # check_guardrails（~133 行）\n│   └── methodology.py        # check_methodology（~66 行）\n├── reporter.py               # generate_report（~262 行）\n├── cli.py                    # parse_args + main（~88 行）\nhalucatch_core.py             # 向后兼容入口（~30 行，导入 cli.main）\n\n## 设计原则\n\n1. **零依赖**：所有模块仅使用 Python 标准库，不引入外部包。\n2. **单一职责**：每个模块对应一个功能边界，模块内高内聚。\n3. **AI 可复现**：单文件控制在 200 行以内，AI 可以完整理解每个模块。\n4. **向后兼容**：halucatch_core.py 保留，所有现有用法不受影响。\n5. **可扩展**：新增评估维度时，只需在 evaluators/ 下新建文件，evaluators/__init__.py 注册即可。\n\n## 依赖关系\n\n```\ncli.py → reporter.py → evaluators/__init__.py → config.py\n             ↑                        ↑\n          scanner.py               classifier.py\n```\n\n所有模块都依赖 config.py（MESSAGES）。\nscanner.py 和 classifier.py 无依赖。\nreporter.py 依赖所有 evaluators 和 scanner 输出。\ncli.py 是入口，协调所有模块。\n\nFile v1.8.8:_meta.json\n\n{\n  \"ownerId\": \"kn74hb96rgc7bpqt7m16rvn3h188ehj7\",\n  \"slug\": \"halucatch\",\n  \"version\": \"1.8.8\",\n  \"publishedAt\": 1783848331061\n}\n\nFile v1.8.8:CHANGELOG.md\n\n# Changelog\n\n本文档记录 HaluCatch 项目的所有 notable changes。\n\n版本号规则：\n- **中间版本号** (1.x.0)：新功能或架构级变更\n- **小版本号** (1.0.x)：修复、增强、chore 等小更新\n- **每个 commit 对应一个版本更新**\n\n---\n\n## [Unreleased]\n\n\n---\n\n## [V1.8.8] - 2026-07-12 · `a470515`\n- CHANGELOG 补 hash、清 Unreleased 已发布内容\n- Release.sh 重排为 12 步，commit 先于 CHANGELOG（tag 存在 → hash 正确）\n- FAQ 反模式加 Before/After 示例，报告预览加 Demo 站链接；SkillHub 去 README\n- CHANGELOG 1.8.7 重写为真实变更，generate-changelog 移除反引号 escape\n- PREV 源改为 CHANGELOG.md hash 优先（git tag 可被挪，CHANGELOG hash 不变）\n- Sync_version_meta 新版本无 tag 时用 HEAD hash 而非 -\n- 响应 SkillSpector 3 条——删 halucatch-fix/、触发条件区、ClawHub 不打包 README\n\n---\n\n\n## [V1.8.7] - 2026-07-12 · `8a74f7e`\n\n### Added\n- FAQ 顶部新增「🔍 报错速查」表格，搜报错一眼定位\n- AI 确认外部 Skill 支持弹窗+文字双模式，选项带编号\n\n### Changed\n- 异常处理格式统一：所有异常附加机器详情，仅 unexpected 打印 traceback\n- SKILL.md 配置修改确认一步完成（用户回复即授权，不二次确认）\n- SKILL.md 第三选项说明 `[疑似外部 Skill]` 为脚本自动标注功能\n\n### Fixed\n- `compatibility` 随 config.yaml 同步，细化 Bash 用途声明\n- 根 `config.yaml` 走 frontmatter，去除 `skills_is_external` 字段\n- PREV_TAG 三级回退（git tag → commit → CHANGELOG），始终输出来源\n- generate-changelog.sh 去 `set -u`、去反引号 escape，根除 unbound variable\n\n---\n\n\n## [V1.8.6] - 2026-07-12 · `f430b91`\n- 独立 FAQ 页面，含响应式导航动画、搜索过滤、关键词推荐\n- CHANGELOG 补全 v1.8.1～v1.8.5\n- 运行配置从根 config.yaml 迁移到 halucatch/halucatch/.halucatch_config.yaml\n- Scanner/cli 去掉旧版 config.yaml 兼容，仅读 .halucatch_config.yaml\n- 明确 skills_is_external 控制的是项目根 skills/\n- Skills_is_external 恢复递归跳过所有层级 skills/\n- 删除 docs/FAQ.md，build.py 从 halucatch/FAQ.md 复制，统一维护源\n- FAQ 顶部加报错速查表，搜报错的人一眼定位\n- Release.sh 增加 build_faq.py 步骤\n- 修正构建输出目录为 docs/，补充 blog 与安装区配置说明\n- 将 manifest.json 纳入版本管理并升版至 1.8.6\n- Generate-changelog --write 传版本号，用 tag range 生成条目而非填 Unreleased\n- SKILL.md config.yaml 加「HaluCatch 自身」限定，frontmatter 细化 Bash 用途\n- Config.yaml compatibility 同步 SKILL.md，细化 Bash 用途声明\n- 运行配置改为 os.path.dirname(__file__) 包内路径，不依赖目标目录\n- Skills_is_external 仅跳过根级 skills/，不递归影响子目录\n- 统一错误输出格式，所有异常附加机器详情且仅 unexpected 打印 traceback\n- Build.py FAQ 路径修正为 ROOT.parent，docs/ 生成最新 FAQ\n\n---\n\n## [V1.8.5] - 2026-07-12 · `8975c93`\n\n### Fixed\n- SKILL.md 安全声明继续收紧：删 `git commit` 禁止指令、`reports/` 路径修正为目录内、触发条件去贴入建议\n- eval( 注释残留清除，三处（正则、描述、注释）彻底消除静态分析误报\n---\n\n## [V1.8.4] - 2026-07-12 · `45b3294`\n\n### Fixed\n- eval( 检测模式改用 `\\x65` + 字符串拼接，避开静态分析误报\n- release.sh Step 6/7 调序（先尺寸检查再打包）\n---\n\n## [V1.8.3] - 2026-07-11 · `16a4ea4`\n\n### Fixed\n- eval( 检测模式改用 `\\x65` 拆散字面量，避开静态分析 Critical 误报\n---\n\n## [V1.8.2] - 2026-07-11 · `1858d8c`\n\n### Changed\n- FAQ.md：`常见避坑` → `🚫 常见反模式`，新增 3 条致命反模式 + 标准版报告预览\n- cli.py 错误提示加「→ 下一步操作」，unexpected 附 GitHub Issue 链接\n---\n\n## [V1.8.1] - 2026-07-11 · `82a4f38`\n\n### Fixed\n- 响应 NVIDIA SkillSpector 5 条安全发现：强化 Bash 权限声明、修复路径歧义、收紧触发条件\n---\n\n## [V1.8.0] - 2026-07-11 · `b9f9bb0`\n\n### Added\n- **第五维度：复杂度评估** — 新增 11 项指标（章节深度、引用链、重复冗余、表格复杂度、脚本覆盖比、代码/文档比、指令密度等），综合评分 0-10 分\n- **脚本覆盖率折扣** — `最终 = 加权 × (1 − √覆盖率)`，边际递减：第一个脚本降幅最大\n- **Skills 外部目录检测** — `config.yaml` 新增 `skills_is_external` 字段，null 时标注 ⚠️ 疑似外部 Skill，true 时跳过扫描\n- **代码风险检测多语言** — 支持 Shell / Go / JS / Ruby / Rust / Perl / TS，按语言分组统计\n- **Shell 受保护上下文** — 函数体内 `$1`/`$2` 和 `while $#` 参数解析循环自动跳过，消除 参数缺失 误报\n- **护栏新增 3 项** — 输出稳定性检测（模板文件）、擅自做主检测、静默吞错检测\n- **输出确定性增强** — Python 函数名兜底 + 模板文件检测双保险\n- **复杂度三行汇总表** — 加权总得分 / 脚本覆盖率折扣 / 最终复杂度，含 KaTeX 公式\n- **pre-push hook** — push 前自动运行 pytest + ruff\n\n### Changed\n- **emoji 重命名**：代码维度 🤖→💻，代码风格提示→其他提示，乘数→折扣\n- **标准版报告精简**：复杂度细节不入标准版，info 级别项移至专业版\n- **SKILL.md 流程优化**：AI 按需读文件而非全局扫描、报告生成后强制检查 ⚠️ 标记\n- **报告输出路径**：默认改为 Skill 文件夹内 `reports/`\n- **代码/文档比分级**：6 级细化，幽默标签（\"你这是代码仓库啊，兄弟\"）\n- **网站重建**：五维宣传页、Demo 上移、全局滚动动画、preview 用真实自审查数据\n\n### Fixed\n- 模糊词列表删除\"通常\"（性能描述非歧义）\n- `bump-version.sh` 漏更新 `__init__.py`\n- `_instruction_density()` 死代码残留（L424-428）\n- 未捕获 Promise 检测改为两步验证\n- `mktemp` 误报（`set -e` 下 `|| true` 是标准写法）\n- 超长行从 warn 降级为 info\n- Shell 参数缺失排除 `$0` 和 `default` 模式\n- 代码/文档比公式反转，改为文档占比\n- 网站 overscroll 暗色背景修复、`>` 标签残留修复\n---\n\n## [V1.7.1] - 2026-06-28 · `5924f71`\n\n### Fixed\n- **高优先级代码修复**\n  - `except:` → `except Exception:`（防吞系统级异常）\n  - `score / total` → `score / max(total, 1)`（3处，防除零崩溃）\n  - `check_code_risks` 字符串/注释误扫描 → 预处理移除字面量后再正则匹配\n- **中优先级文档修复**\n  - 报告文件名含版本号，冲突时自动加序号（`-1`、`-2`...）\n  - SKILL.md 新增\"数据要求\"章节（时效性 + 前提假设）\n  - 移除 `ToolCard.md` 认知污染，规范化为 `SKILL.md`\n- **低优先级架构重构**\n  - 1191 行 `halucatch_core.py` 拆分为 11 个模块，单文件 ≤270 行\n  - 新增 `halucatch/` 包：`config`, `scanner`, `classifier`, `evaluators/`, `reporter`, `cli`\n  - 保留 `halucatch_core.py` 向后兼容入口\n\n### Added\n- **版本号自动提取**：从 `_meta.json` / `meta.json` / 任意 `.md` frontmatter\n- **无 SKILL.md 替代机制**：启发式匹配（frontmatter 优先 + 文件大小），报告规范性问题后继续工作\n- **无 .md 文件严格拒绝**：直接报错，拒绝非标准 Skill 目录\n- **测试覆盖**：新增 3 个扫描测试，总计 24 个测试全部通过\n\n### Changed\n- `build-skillhub.sh` / `check-file-size.sh` / `release.yml` / `manifest.json` 适配新包结构\n\n---\n\n## [V1.7.0] - 2026-06-26 · `f6dce0b`\n\n### Added\n- feat: **英文 Skill 支持增强**\n  \n  **跨语言检测能力扩展:**\n  - 新增英文模糊词检测（18 个词）: `roughly`, `approximately`, `about`, `usually`, `generally` 等\n  - 新增英文单位检测: `USD`, `EUR`, `GBP`, `million`, `billion`, `percent`, `percentage`, `pct`\n  - 增强英文禁止声明检测: `MUST NOT`, `FORBIDDEN`, `PROHIBITED`, `DO NOT`\n  - 增强工具库/分析型识别信号词\n  \n  **影响**: halucatch_core.py (`check_rules`, `_prohibition_signal`, `_is_tool_skill`)\n\n---\n\n## [V1.6.0] - 2026-06-17 · `62ac03d`\n\n### Added\n- feat: **数据驱动型护栏分层** — 工具库 vs 分析型双档评分\n  \n  **护栏分层架构重构:**\n  - `check_guardrails` 集成 `_is_tool_skill()` 分支\n  - **工具库型**: total=5, 跳过置信度/数据来源/时效性检查\n  - **分析型**: total=8, 全查\n  - **方法论**: total=5, 保持不变\n  \n  **测试增强:**\n  - 新增 `test_guardrails_tool_type` 测试用例\n  - 21/21 通过，xlsx/pptx 3/5, neodata 7/8\n  \n- 影响: halucatch_core.py (52 行修改), tests/test_halucatch.py (18 行新增)\n\n---\n\n## [V1.5.1] - 2026-06-17 · `768d725`\n\n### Changed\n- chore: 忽略 .clawhub 目录\n- 影响: .gitignore (1 行)\n\n---\n\n## [V1.5.0] - 2026-06-17 · `baaaaa2`\n\n### Added\n- feat: **去语言化架构重构** — 结构化信号替代语义关键词正则\n  - `_branch_density()`: 清单/图标/表格密度 → 跨语言分支检测\n  - `_prohibition_signal()`: 否定词/大写警告/中文禁止 → 跨语言护栏检测\n  - `check_methodology` 末尾加 AI 免责声明\n  - 测试更新: 两组用例内容补信号结构\n- 影响: halucatch_core.py (51 行修改), tests/test_halucatch.py (4 行), 新增文档 144 行\n\n---\n\n## [V1.4.1] - 2026-06-17 · `65631d4`\n\n### Added\n- feat: Phase 4 闭环 SOP 实现 — 三选一交互 + 行动版 prompt\n  - SKILL.md Phase 4: 修复 → 用户三选一 (执行/不执行/建议) 详细 SOP\n  - halucatch_core.py: 行动版报告追加三选一步骤提示\n- 影响: SKILL.md (21 行), halucatch_core.py (8 行)\n\n---\n\n## [V1.4.0] - 2026-06-17 · `856f682`\n\n### Added\n- feat: **闭环验证流程** — 用户选择? + AI按方案修复 + 重新审查回路\n  - 决策流程图新增修复验证闭环\n  - 用户选择? (3分支): 执行 → AI 修复 → 重新审查 | 不执行 → 结束 | 建议 → 回环\n  - SKILL.md / README Mermaid / HTML SVG 三处同步\n  - 视觉优化：汇聚箭头修正、间距扩大、标签对齐\n- 影响: README.md, SKILL.md, docs/decision-flowchart.html, docs/decision-flowchart-prompt.md (新增 75 行)\n\n---\n\n## [V1.3.1] - 2026-06-17 · `a2895f7`\n\n### Changed\n- chore: 清理过期测试文档\n- 影响: 删除 4 个文档文件 (451 行)\n  - docs/HaluCatch-expansion-plan-2026-06-17.md\n  - docs/HaluCatch-optimization-report-2026-06-17.md\n  - docs/HaluCatch-readme-update-checklist-2026-06-17.md\n  - docs/HaluCatch-test-report-2026-06-17.md\n\n---\n\n## [V1.3.0] - 2026-06-17 · `bd76b90`\n\n### Added\n- feat: **代码风险去金融化 + 边界测试 + 护栏分层**\n  \n  **代码风险检测增强:**\n  - 移除写死变量名的 3 个 pattern（p_pool/p_val, math.exp, store_weeks）\n  - 新增 4 个通用 pattern：浮点(任意==0.0), 除零(return 除法), 路径拼接, 静默覆盖, 超时缺失\n  - 模式库从 5 个扩展到 7 个\n  \n  **扫描功能改进:**\n  - `scan_folder` 改为 `os.walk` 递归扫描，支持子目录 .py\n  - 文件清单加 `rel_path` 字段（精确路径匹配）\n  - 返回值加 `py_count` / `max_py_lines`（避免拼接行数虚高）\n  \n  **护栏分层:**\n  - `check_guardrails` 按 `skill_type` 分层：methodology 跳过 3 项无用检查\n  - 默认输出到 `HaluCatch/reports/`，不污染目标 Skill 目录\n  \n  **测试增强:**\n  - 16 → 20 用例，新增 4 个边界测试（空目录/只有SKILL.md/只有.py/深层嵌套）\n  - 全部通过\n  \n  **文档同步:**\n  - README 三维→四维、用例更新、护栏分层说明、测试章节\n  - docs/ 补充专家出具的 4 份报告\n- 影响: halucatch_core.py, tests/test_halucatch.py, README.md, SKILL.md, 新增 5 个文档\n\n---\n\n## [V1.2.1] - 2026-06-17 · `50a8780`\n\n### Changed\n- feat: 更新 .gitignore，添加 .workbuddy 目录排除\n- 影响: .gitignore (1 行)\n\n---\n\n## [V1.2.0] - 2026-06-17 · `813d84e`\n\n### Added\n- refactor: **P0-P3 全面修复** — 角色声明/三层调用/四维评估骨架/测试\n  \n  **P0 修复:**\n  - SKILL.md 添加 AI 角色声明\n  - 三层调用分工表\n  - 执行决策流程图\n  \n  **P1 修复:**\n  - 修复 `check_foundation` skip/warn 混淆\n  - 修复 `methodology` 自洽逻辑\n  - 修复 `report info` 隐藏\n  \n  **P2 实现:**\n  - 实现 `check_rules()` (6项) 骨架函数\n  - 实现 `check_guardrails()` (8项) 骨架函数\n  \n  **P3 测试:**\n  - 新增 `tests/` (16 用例)\n  - 新增 `docs/` (流程图) 目录\n  - 补充 .gitignore\n- 影响: 7 个文件变更, 731 行新增, 30 行删除\n\n---\n\n## [V1.1.0] - 2026-06-16 · `952f26b`\n\n### Added\n- feat: **核心实现** — 添加 halucatch_core.py 和 README\n  - `halucatch_core.py`: 504 行核心代码\n  - `README.md`: 99 行项目说明\n- 影响: 新增 2 个文件, 603 行\n\n---\n\n## [V1.0.0] - 2026-06-16 · `ad24145`\n\n### Added\n- feat: **初始版本** — HaluCatch SKILL.md\n  - AI Skill 可靠性检查器核心设计文档\n  - 231 行 SKILL.md\n  - 基础 .gitignore\n- 影响: 新增 2 个文件, 235 行\n\n---\n\nFile v1.8.8:FAQ.md\n\n# HaluCatch / 捕幻 — 常见问题\n\n---\n\n## 基础\n\n**Q: HaluCatch 需要联网吗？**\n\n不需要。全程离线运行，仅扫描本地文件夹中的 SKILL.md 和 .py 文件，不会发起任何网络请求。如果执行卡住，大概率是 AI 对话环境超时或目标路径文件过多导致扫描耗时。\n\n---\n\n**Q: HaluCatch 怎么用？**\n\n对 AI 说「帮我用 HaluCatch 审查 /path/to/skill」即可。AI 会先确认目标路径无误，再开始扫描评估。为避免误操作，请确保指定的路径是希望审查的 Skill 目录，不要指向系统目录或 home 目录。3 步上手：\n\n1. 跑一次审查 → 看标准版报告了解问题\n2. 打开 `-行动版.md` → 从列表第一条开始逐项修复\n3. 修复后重新跑 → 对比分数是否改善\n\n---\n\n**Q: HaluCatch 是免费的吗？**\n\n是。HaluCatch 采用 MIT 开源协议，完全免费，包括个人和商业使用。源代码在 GitHub 上公开。\n\n---\n\n**Q: HaluCatch 支持中文还是英文？**\n\n都支持。HaluCatch 会自动检测你的 AI 对话环境的语言偏好，输出对应语言的三份报告（标准版、专业版、行动版）。也可以通过 `--lang en` 或 `--lang zh-CN` 强制指定。\n\n---\n\n**Q: HaluCatch 可以在哪些 AI 平台上使用？**\n\nHaluCatch 支持所有允许上传提示词/技能的 AI 平台，包括 ClawHub、SkillHub 等技能市场。同时支持纯命令行模式，可以在任何终端中运行。\n\n---\n\n## 🔍 报错速查\n\n| 报错 / 报告标记 | 原因 | 解决 |\n|------|------|------|\n| `❌ 路径不存在` | 目录拼错或已移动 | `ls <路径>` 确认目录存在 |\n| `❌ 目录为空` | 缺少 SKILL.md | 新建 SKILL.md（一行标题也行）再跑 |\n| `⚠️ 疑似外部 Skill` | `skills/` 下有别人安装的 Skill | 确认后修改运行配置文件中 `skills_is_external` |\n| `🔴 硬编码路径` | SKILL.md 或脚本里有绝对路径 | 全部改成相对路径 |\n| `🟠 模糊表述` | 说明书用了\"大概/可能/通常\"等词 | 换成明确的 if-else 条件句 |\n| `🔴 裸 except` | `except: pass` 吞掉了错误 | 至少 `except Exception as e: print(e)` |\n| `🟠 不存在文件引用` | 引用的脚本/文档实际不在文件夹里 | `ls` 确认文件存在，修正文件名 |\n| `🟠 覆盖薄弱` | 大部分步骤没有脚本兜底 | 把核心步骤写成 .py/.sh 脚本 |\n\n更详细的避坑指南见下方 [🚫 常见反模式](#-常见反模式不要做的事)。\n\n---\n\n## 使用场景\n\n**场景 1：发布前自审**\n\n你要把写好的 Skill 发布到 ClawHub / SkillHub，想确保它在别人机器上也能正常工作。\n\n跑一次全维度审查。重点看标准版报告的「地基」和「代码风险」——硬编码路径、裸 except、虚构命令是最高频的坑。改完后跑第二次验证分数提升。\n\n**场景 2：接手别人的 Skill**\n\n别人写的 Skill 文档很长，你不敢直接给 AI 执行，怕出问题。\n\n跑一次审查，直接看「行动版报告」——它把每个问题拆成「现状 → 风险 → 修复方案 → 验证方法」，照着改就行，不用通读原始 SKILL.md。\n\n**场景 3：CI 自动检查**\n\n你在维护 Skill 仓库，想每次改代码时自动检查质量不退化。\n\n```bash\npython3 -m halucatch --skill-dir . --validate    # 快速扫描文件清单\npython3 -m halucatch --skill-dir . --output-dir ./ci-reports  # 完整审查出报告\n```\n\n在 CI 里集成，每次 PR 确保分数不下降。\n\n---\n\n## 能力边界\n\n**能做什么：**\n- ✅ 扫描 SKILL.md 和关联 .py 文件，检查执行可靠性\n- ✅ 识别硬编码路径、裸异常处理、虚构命令等 7 类代码风险\n- ✅ 评估业务规则歧义和护栏完整度\n- ✅ 自动识别中英文，输出对应语言报告\n- ✅ 生成标准版/专业版/行动版三份报告\n\n**不能做什么：**\n- ❌ 不联网 —— 不访问任何 API，不下载文件\n- ❌ 不查安全漏洞 —— SQL 注入、XSS、恶意指令交给 ClawHub SkillSpector\n- ❌ 不批量处理 —— 一次一个目录\n- ❌ 不代替人工决策 —— 报告是建议，最终你拍板\n\n**硬性限制：**\n- 📏 单文件 > 10 MB 会被跳过并提示\n- 📁 不支持二进制文件\n- ⏱️ 处理时间取决于文件数量和大小，通常 1-60 秒\n\n---\n\n**Q: 我的 Skill 没有 .py 文件，能用吗？**\n\n可以。HaluCatch 会自动分类为「纯方法论型」并跳过地基/代码检查，只评估方法论结构和护栏完整度。\n\n---\n\n## 报告\n\n**Q: HaluCatch 会在电脑上写文件吗？**\n\n会。审查完成后自动在 `HaluCatch/reports/` 目录生成三份报告（标准版、专业版、行动版 .md 文件）。不会修改目标 Skill 目录中的任何文件。如需自定义输出路径，使用 `--output-dir` 参数。\n\n**Q: 审查结果长什么样？**\n\n标准版报告示例（白话、零术语，给非技术用户看）：\n\n```\n# HaluCatch 审计报告 — my-skill\n\n## 📌 一句话总结\n\n🟢 3 通过 · ⚠️ 2 注意 · 💡 3 可优化\n\n## 🎯 核心结论\n\n| 地基 | 代码 | 规则 | 护栏 | 复杂度 |\n|:--:|:--:|:--:|:--:|:--:|\n| 🟢 稳固 6/6 | 🟢 干净 90/90 | 🟡 有歧义 4/6 | 🟢 到位 11/11 | 🟡 注意 2.2/10 |\n\n### 做的不错 👍\n- ✅ 有固化脚本兜底核心任务\n\n### 需要注意的方面\n- ⚠️ 存在模糊表述 ['大概']（说明书写了模糊词，AI 可能会猜错）\n```\n\n包含专业版（11 项指标表 + KaTeX 公式）和行动版（修复清单）。完整示例：运行 `python3 halucatch_core.py --skill-dir .` 审自己的项目，或查看 [在线 Demo](https://codermoray.github.io/HaluCatch/) 的交互式报告预览。\n\n---\n\n**Q: 审查结果说「护栏薄弱」，怎么修？**\n\n看同目录下的 `HaluCatch-report-日期-行动版.md`，它逐条列出了修复方案和验证检查点。按清单逐项改即可，改完后重新审查验证。\n\n---\n\n**Q: 为什么工具库型 Skill 的护栏分数看起来比分析型低？**\n\n护栏检查按类型分层——工具库型只查 5 项核心项（跳过数据来源/时效性/置信度），分析型查全 8 项。分母不同，分数不可直接比较。\n\n---\n\n**Q: 报告里看到的版本号是什么意思？**\n\n报告日期是生成当天，版本号跟随 HaluCatch 自身版本。同一个 Skill 在不同版本 HaluCatch 下的评分可能不同——因为检测规则在持续改进。\n\n---\n\n**Q: 能一次审查多个 Skill 吗？**\n\n当前版本暂不支持批量模式。你可以逐个运行。批量功能已在 roadmap 中。\n\n---\n\n## 技术\n\n**Q: 为什么有些 Skill 被分类为「代码工程型」而有些是「纯方法论型」？**\n\n含 .py 文件、或 SKILL.md 中嵌入了 `\\`\\`\\`python` 代码块、或引用了 pandas 等数据处理库的 Skill → 代码工程型（启用全四维评估）。其余 → 纯方法论型（只查方法论+护栏）。\n\n---\n\n**Q: 出现文件编码错误怎么办？**\n\nHaluCatch 会尝试以 UTF-8 读取所有文件。如果遇到非 UTF-8 编码（如 GBK），会用 `backslashreplace` 保留原始字节的转义形式，避免静默丢数据。\n\n---\n\n**Q: 代码风险检查有哪些规则？**\n\n当前 7 条通用规则：异常处理（裸 except: pass）、浮点比较（== 0.0）、除零风险（return 中无保护除法）、硬编码阈值（固定 skiprows）、路径拼接（字符串拼路径）、静默覆盖（open 写模式无警告）、超时缺失（requests 无 timeout）。\n\n---\n\n**Q: 行动版报告里的「Phase 4 闭环」是什么意思？**\n\n审查完成后，HaluCatch 会询问是否按方案修复。选择「执行修复」→ 将方案发给 AI 实施 → 修复后重新审查验证。选择「我有更好建议」→ 描述你的想法 → 重新生成方案。选「不执行」→ 结束。完整的「发现→修复→验证」链路。\n\n---\n\n## 🚫 常见反模式（不要做的事）\n\n提交 Skill 或使用 HaluCatch 前，先过一遍这些高发问题：\n\n### ⚠️ 致命反模式\n\n| 踩坑 | 后果 | 正确做法 |\n|------|------|--------|\n| 让 AI 看完 HaluCatch 报告就直接改代码 | AI 可能误解报告建议，添加有问题的修复 | 先人工审查每条建议，确认后再让 AI 执行 |\n| 只看评分不看详情 | 高分但细节全是烂摊子 | 逐条看 warn/fail，优先修 🔴 |\n| Skills/ 目录塞满别人的 Skill 后跑审查 | 别人代码的问题全算在你头上 | `config.yaml` 设 `skills_is_external: true` |\n\n### 地基（Foundation）\n\n| 踩坑 | 后果 | 怎么避 |\n|------|------|--------|\n| SKILL.md 里引用本地绝对路径（如 `/Users/me/project/`） | 换台机器就跑不了 | 全部用相对路径：`references/guide.md` 而非 `/home/me/guide.md` |\n\n> **举例：**  \n> ❌ `参照 /Users/me/projects/tool/格式要求.md 的第 3 节`（换台机器不存在）  \n> ✅ `参照 references/格式要求.md 的第 3 节`（跟随 Skill 走，到哪都能读）\n| 引用的脚本/文档文件实际不存在 | AI 按不存在的东西执行，产生幻觉 | 跑审查前先 `ls` 确认每个被引用的文件都在 |\n| 明明有 Python 脚本但 SKILL.md 里没提 | HaluCatch 可能漏掉代码风险检查 | `SKILL.md` 里注明所有 Python 依赖和入口文件 |\n\n### 代码风险（Code）\n\n| 踩坑 | 后果 | 怎么避 |\n|------|------|--------|\n| `except Exception: pass` 或 `except: pass` | 出错静默吞掉，查 bug 如大海捞针 | 最少 `except Exception as e: print(e)` |\n| `open(filename, 'w')` 无保护 | 静默覆盖已有文件，数据丢失 | 改成 `'x'` 模式，或写入前检查 `os.path.exists()` |\n| `requests.get(url)` 没设 `timeout=` | 网络卡住时永久挂起 | 统一设 `timeout=30` |\n| 除法运算不检查分母是否为零 | 输入数据稍有异常就崩 | 所有除法前加 `if denominator == 0:` 分支 |\n\n### 规则（Rules）\n\n| 踩坑 | 后果 | 怎么避 |\n|------|------|--------|\n| 用模糊词（\"大概\"、\"可能\"、\"应该\"、\"或许\"） | AI 执行时自行脑补，输出不可复现 | 把模糊词换成明确的条件：\"当 A 为真时执行 B\" |\n| 指令只有正常路径，没有异常分支 | 出状况时 AI 不知道该怎么办 | 每条核心指令至少配一个\"如果失败了怎么办\" |\n| 引用了 Skill 不支持的虚构命令或功能 | AI 试图执行不存在的东西 | 写指令前确认所有命令在你的环境下真实可用 |\n\n### 护栏（Guardrails）\n\n| 踩坑 | 后果 | 怎么避 |\n|------|------|--------|\n| 没声明\"不要做什么\" | AI 可能在你不希望的场景下触发 Skill | 开头加一句：\"仅当用户明确请求 X 时激活，其他情况下忽略\" |\n| 输出格式没约束 | 同样的输入每次输出格式不一样 | 明确指定输出结构：JSON schema / Markdown 表格 / 固定模板 |\n| 引用了外部 API 但没声明密钥需求 | 用户装完发现跑不了 | `metadata.openclaw.requires.env` 里列出所有需要的环境变量 |\n\n---\n\n> **小技巧**：把这份清单当 checklist，跑 HaluCatch 之前先逐行过一遍——多数问题根本不会出现在报告里。\n\nFile v1.8.8:skill-card.md\n\n## Description:\n\nEvaluates AI Skill execution reliability across data pipeline integrity, code risk, business logic ambiguity, interpretation guardrails, and reportable complexity signals.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[codermoray](https://clawhub.ai/user/codermoray)\n\n### License/Terms of Use:\n\nMIT\n\n## Use Case:\n\nDevelopers and engineers use this skill to audit an AI Skill folder before deployment or sharing, checking whether agent execution is reproducible, trustworthy, and supported by clear rules and guardrails.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Filesystem scanning may reach content the operator did not intend to include, especially when target folders contain symlinks or unexpected nested directories.\n\nMitigation: Run only against trusted or pre-checked directories, avoid targets with symlinks to sensitive files, and use a sandbox when auditing untrusted skills.\n\nRisk: Report output can be written outside the target folder when an output directory is specified.\n\nMitigation: Confirm the target path and output directory before execution, and keep report output inside the intended workspace.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/codermoray/skills/halucatch)\n- [HaluCatch Homepage](https://github.com/CoderMoray/HaluCatch)\n- [Publisher Profile](https://clawhub.ai/user/codermoray)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, guidance, files]\n\n**Output Format:** [Markdown reports and terminal text generated from local Python execution]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Writes professional, standard, and AI action report files to a reports directory unless an output directory is specified.]\n\n## Skill Version(s):\n\n1.8.8 (source: frontmatter, manifest.json, __init__.py, CHANGELOG)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.8.8:manifest.json\n\n{\n  \"name\": \"HaluCatch\",\n  \"version\": \"1.8.8\",\n  \"required_files\": [\n    \"halucatch/SKILL.md\",\n    \"halucatch/halucatch_core.py\",\n    \"halucatch/halucatch/\"\n  ],\n  \"skillhub_files\": [\n    \"halucatch/SKILL.md\",\n    \"halucatch/halucatch_core.py\",\n    \"halucatch/halucatch/\",\n    \"README.md\",\n    \"docs/CHANGELOG.md\",\n    \"halucatch/FAQ.md\"\n  ],\n  \"version_sync\": [\n    \"halucatch/SKILL.md\",\n    \"config.yaml\",\n    \"docs/index.html\"\n  ],\n  \"clawhub_exclude\": [\n    \"tests/\",\n    \"docs/\",\n    \"reports/\",\n    \"reports_zh/\",\n    \"scripts/\",\n    \"outputs/\",\n    \".workbuddy/\",\n    \".github/\",\n    \"__pycache__/\",\n    \"*.pyc\",\n    \"*.zip\"\n  ],\n  \"category\": \"engineering\",\n  \"language\": \"zh-CN\"\n}\n\nFile v1.8.8:LICENSE\n\nMIT License\n\nCopyright (c) 2026 CoderMoray\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\nArchive v1.8.7: 24 files, 72374 bytes\n\nFiles: CHANGELOG.md (12200b), FAQ.md (10826b), halucatch_core.py (642b), halucatch/__init__.py (77b), halucatch/__main__.py (104b), halucatch/classifier.py (702b), halucatch/cli.py (7697b), halucatch/config.py (12476b), halucatch/evaluators/__init__.py (506b), halucatch/evaluators/code_risks.py (15713b), halucatch/evaluators/complexity.py (23619b), halucatch/evaluators/foundation.py (2921b), halucatch/evaluators/guardrails.py (9749b), halucatch/evaluators/methodology.py (3044b), halucatch/evaluators/rules.py (3245b), halucatch/README.md (1992b), halucatch/reporter.py (19522b), halucatch/scanner.py (8426b), LICENSE (1067b), manifest.json (690b), README.md (12457b), skill-card.md (2456b), SKILL.md (22064b), _meta.json (128b)\n\nFile v1.8.7:SKILL.md\n\n---\nname: halucatch\ndescription: |\n  Evaluates the reliability of AI Skill execution. Assesses whether a Skill's output is trustworthy, reproducible, and withstands business scrutiny when executed by an AI agent. Covers four dimensions: data pipeline integrity, code risk, business logic ambiguity, and interpretation guardrails. Use when auditing an AI Skill, checking for hallucinations or unreliable outputs, verifying execution reproducibility, or reviewing a Skill's safety before deployment or sharing.\nsummary: AI Skill 执行可靠性审查工具。评估一个 Skill 被 AI 执行时，结果是否可信、是否可复现、是否经得起业务推敲。覆盖四维度：地基（数据管线）、代码、规则（业务口径）、护栏（解读指南）。\nlicense: MIT\nallowed-tools:\n  - Read\n  - Write\n  - Bash\ncompatibility: Requires Python 3.8+; Bash only for local 'python3 halucatch_core.py', no network/arbitrary commands\nauthor: CoderMoray\nversion: 1.8.7\nmetadata:\n  hermes:\n    tags:\n    - skill-audit\n    - reliability\n    - engineering-assurance\n    - Skill审查\n    - 工程质量\n    - 可靠性\n  openclaw:\n    requires:\n      bins:\n      - python3\n    emoji: 🔍\n    homepage: https://github.com/CoderMoray/HaluCatch\nslug: halucatch\ndisplayName: HaluCatch / 捕幻\ntags:\n  - skill-audit\n  - reliability\n  - engineering-assurance\n  - Skill审查\n  - 工程质量\n  - 可靠性\n---\n> **一句话总结**：把一个 AI Skill 的文件夹扔给 HaluCatch，它会逐项检查数据管线、代码逻辑、业务规则、安全护栏有没有漏洞，然后给你三份报告（标准版看全貌、专业版看细节、行动版直接修），全程几秒钟、完全离线。\n>\n> [快速开始](#1-入口逻辑) · [能力边界](#能力边界) · [输出解读](#5-报告)\n\n# HaluCatch / 捕幻 — AI Skill 执行可靠性审查\n\n评估一个 Skill 包在 AI 执行时的可靠性，产出评估报告和修复建议（建议需用户确认后才执行，不自动修改目标 Skill）。\n\n---\n\n## 能力边界\n\n| 擅长 | 不擅长 |\n|------|--------|\n| 评估 AI 执行 skill 时会否出错 | 网络安全审查（SQL 注入、XSS 等） |\n| 检查数据管道是否可靠 | 合规性审查（GDPR、隐私法规等） |\n| 发现自然语言业务规则的歧义 | Skill 本身的业务正确性（不懂业务逻辑） |\n| 检查解读护栏是否到位 | 代码性能优化 |\n| 输出修复建议和骨架脚本 | 替换人工业务决策 |\n\n**硬件限制：** 单文件上限 10 MB（超大文件会被跳过并提示），不支持批量审查（一次一个目录），不支持二进制文件，不建立网络连接（仅通过本地 Python 脚本运行）。审查耗时取决于目录下文件数量和大小，通常几秒到几十秒。\n\n---\n\n## 角色\n\n当用户调用 HaluCatch 时，**你就是 HaluCatch 审查执行者**，而非旁观者。\n\n### 职责\n\n- 调用 `halucatch_core.py` **一次性完成全流程**（L1 扫描 + L2 评估 + L3 报告生成）\n- 读取脚本生成的报告文件，对话中展示标准版，询问是否修复\n- 在脚本报告基础上做语义补充：按需读取报告中引用的源文件，提供上下文分析（`info` 级别条目）\n- **不要自己读取目标目录的文件**——文件扫描由脚本完成，AI 读取只会浪费 token\n\n### 你与 halucatch_core.py 的分工\n\n| 层级 | 任务 | 执行方 | 原则 |\n|------|------|--------|------|\n| **L1** | 文件扫描 | `halucatch_core.py --validate` | 确定性高，脚本更快更准 |\n| **L2** | 地基 + 代码 + 规则 + 护栏检查 | 脚本取 JSON 基线 → **你在此基础上补充分析** | 正则匹配靠脚本，上下文解读靠你 |\n| **L3** | 三版报告生成 | `halucatch_core.py` **生成并落盘**，你读取后展示给用户 | `reporter.py` 确定性高、格式一致、零幻觉——你只需做语义补充 |\n\n> **核心原则**：`halucatch_core.py` 涵盖全流程——L1 扫描、L2 评估、L3 报告生成一次性完成。你只需读取脚本生成的报告并展示给用户。不再由 AI 独立编写报告正文。\n\n## 权限与安全边界\n\n**⚠️ 写入警告：HaluCatch 会生成报告文件写入目标目录的 `reports/` 子目录，并可能产出修复指引（需用户确认后才应用）。这不是纯只读工具。**\n\nHaluCatch 仅需要以下权限即可运行：\n\n| 操作 | 需要 | 说明 |\n|------|------|------|\n| 读取目标 Skill 目录 | Read | 递归读取全部文件 |\n| 写入报告文件 | Write | 仅写入目标目录内的 `reports/` 子目录，不修改 Skill 源文件 |\n| 执行 Python 脚本 | Bash | 仅执行本地 `halucatch_core.py`，不访问网络、不执行外部命令 |\n\n**安全约束**：HaluCatch 不会访问目标目录以外的任何路径，不会发起网络连接。Bash 权限仅用于运行自带的 Python 审查脚本，不会执行非本项目代码。审查前必须由用户显式指定目标路径。\n\n---\n\n## 输入\n\n用户提供一个 Skill 文件夹路径。该文件夹可能包含：\n\n| 文件类型 | 是否必需 | 说明 |\n|---------|---------|------|\n| `SKILL.md` | ✅ | Skill 的主指令文件 |\n| `manifest.json` 或 `config.yaml` | ❌ | Skill 配置文件（含版本号等） |\n| `*.py` | ❌ | 数据管线的固化脚本（如有） |\n| `*.xlsx / *.csv` 等 | ❌ | 数据文件（如有，用于验证对账） |\n\n### 数据要求\n\n- **时效性**：审查基于目标 Skill 目录的即时快照，不追溯历史版本。\n- **数据范围**：仅评估目标目录中可见的文件，不爬取外部依赖或网络资源。\n\n### 前提假设\n\n- 目标目录存在且有读取权限。\n- 目标 Skill 应包含至少一个 `SKILL.md` 文件（规范名称）。如有其他 `.md` 文件，AI 将尝试启发式匹配，但会报告规范性问题。\n- 目录中的 `.py` 文件视为 Skill 核心执行脚本，非第三方依赖库。\n\n### 触发条件\n\n仅在用户**显式请求审查 Skill** 时激活。以下为有效触发方式：\n\n- 使用精确命令：`审查 /path/to/skill`、`用 HaluCatch 检查 ./my-skill`\n- 提供明确路径或 Skill 文件夹引用\n- **不作为通用问答助手**：仅在用户主动要求审查时激活，不会对任意文本或对话自动触发评估\n\n---\n\n## AI 执行指南\n\n### 语言自动检测\n\nAI 在加载本 Skill 时，应从系统提示（`<response_language>`）或对话上下文判断用户语言，然后自动添加 `--lang` 参数：\n\n| 用户语言 | 参数 | 示例 |\n|-----------|------|------|\n| 中文（简体/繁体） | `--lang zh-CN` | `python3 halucatch_core.py --skill-dir <path> --lang zh-CN` |\n| 英文 | `--lang en` | `python3 halucatch_core.py --skill-dir <path> --lang en` |\n| 不确定 | 不添加（默认 `auto`，自动检测系统 locale） | `python3 halucatch_core.py --skill-dir <path>` |\n\n**原则**：AI 肯定知道用户用什么语言，不需要用户手动配置。\n\n### 基本用法\n\n```bash\n# 为中文用户审查\npython3 halucatch_core.py --skill-dir /path/to/skill --lang zh-CN\n\n# 为英文用户审查\npython3 halucatch_core.py --skill-dir /path/to/skill --lang en\n\n# 自动检测（fallback）\npython3 halucatch_core.py --skill-dir /path/to/skill\n```\n\n---\n\n## 执行流程\n\n> **执行范式**：各 Phase 按三层调用模型分配职责。`halucatch_core.py` 一次性完成 L1/L2/L3，你读取生成的报告文件并展示给用户。\n\n### Phase 0：技能分类\n\n首先判断这个 Skill 的类型：\n\n```\n这个 Skill 涉及数据处理吗？\n  ├─ ❌ 纯方法论型（指令/模板/文档类）\n  │    评估重点：指令完备性、逻辑自洽、可复现性\n  │\n  ├─ ✅ 代码工程型（含 .py / 数据文件 / md 内嵌代码）\n  │    评估重点：地基 + 代码 + 规则 + 护栏\n  │\n  └─ ⚠️ 不确定\n        → 询问用户：「这个 Skill 有数据处理步骤吗？」\n```\n\n如果文件夹中存在 `.xlsx`、`.csv`、`.py`（含 `pd.read_`、`pd.DataFrame`）等文件或内容，默认按「代码工程型」处理。\n\n### Phase 1：文件扫描\n\n读取文件夹中的全部文件并构建清单：\n\n| 信息点 | 输出形式 |\n|--------|---------|\n| 文件名列表 | 表格（文件名/大小/类型） |\n| SKILL.md 总行数 | 数字 |\n| .py 文件行数（如有） | 数字 |\n| 数据文件列表 | 表格 |\n| Skill 名称和描述 | 从 frontmatter 提取 |\n\n### Phase 2：多维评估\n\n根据 Phase 0 的分类执行对应的评估维度的检查。\n\n---\n\n### 2a. 代码工程型 Skill 评估\n\n#### 🏗️ 地基评估\n\n检查 Skill 的数据管线是否稳固。地基越弱，AI 自主写代码出错的概率越高。\n\n| 检查项 | 通过标准 |\n|--------|---------|\n| 有固化 .py 脚本 | 脚本存在于文件夹中 |\n| 路径参数化 | 硬编码路径数 = 0 |\n| 列名预检/输入验证 | 有 `check_columns` 或类似函数 |\n| validate 模式 | 有 `--validate` 或类似模式 |\n| 文件发现机制 | 使用 glob/通配符而非固定文件名 |\n| 依赖声明 | 在 SKILL.md 中声明了所需的 Python 包 |\n| skiprows 参数化 | Excel 读取行数可配置或自动检测 |\n\n**评级**：🟢 稳固 / 🟡 有隐患 / 🔴 无地基\n\n---\n\n#### 🤖 代码风险评估\n\n如果 SKILL.md 中嵌入了 Python 代码（AI 须逐字复现），检查以下篡改点：\n\n| 检查类别 | 高风险模式 | AI 可能误改的行为 |\n|---------|-----------|----------------|\n| 统计函数 | 自定义 p-value 公式、Z-score 计算 | 替换为 `scipy.stats` / 调整常数 |\n| 字符串匹配 | `clean_rate()` 中解析百分比 | 替换 `replace('%','')` 为不同写法 |\n| 浮点比较 | `== 0` / `== 1` | 改为 `math.isclose()`（语义不同） |\n| 异常处理 | 裸 `except: pass` | 改为具体异常类型 |\n| 条件逻辑 | `(条件).sum() > 0` | 改为 `.any(axis=1)`（行为不同） |\n| 聚合逻辑 | `unstack(fill_value=0)` | 移除 `fill_value`（NaN 传播） |\n| 数据清洗 | 无数据类型转换指令 | 可能对字符串列做 `sum()` 报错 |\n\n**评级**：🟢 低风险 / 🟠 有风险 / 🔴 高风险\n\n---\n\n#### 📝 规则与口径评估\n\n检查业务规则在 SKILL.md 中的描述是否明确、无歧义：\n\n| 检查项 | 风险 |\n|--------|------|\n| 渠道/分类口径是否明确列举 | 歧义 → AI 自行猜测 |\n| 异常值/边界条件是否定义 | 遗漏 → AI 自行处理 |\n| 代际/映射关系是否固化（而非依赖 AI 知识） | 未固化 → 不同 AI 产出不同结果 |\n| 同店/同比等对比口径是否定义 | 未定义 → AI 自行决定，不可审计 |\n| 特殊纠偏规则（如海南聚时）是否文档化 | 未文档化 → 遗漏关键业务逻辑 |\n| 文件名/列名/数据格式是否约定 | 未约定 → 跑不通 |\n\n**评级**：🟢 清晰 / 🟡 有歧义 / 🔴 重大遗漏\n\n---\n\n#### 🛡️ 解读护栏评估\n\n检查 SKILL.md 是否约束 AI 对结果的解读方式：\n\n| 检查项 | 严重度 |\n|--------|--------|\n| 有因果语言禁令 | 缺失 → 🔴 严重 |\n| 有四象限/效应量框架 | 缺失 → 🟠 高 |\n| 有自检机制（self-check） | 缺失 → 🟠 高 |\n| 有多重比较提醒 | 缺失 → 🟠 高 |\n| 有限制性声明模板 | 缺失 → 🟠 高 |\n| 有阶段性状态输出 | 缺失 → 🟡 中 |\n| 有数据概要统计打印 | 缺失 → 🟡 中 |\n| 有输出格式定义 | 缺失 → 🟡 中 |\n\n**评级**：🟢 完善 / 🟡 缺项 / 🔴 无护栏\n\n---\n\n### 2b. 纯方法论型 Skill 评估\n\n| 检查项 | 说明 |\n|--------|------|\n| 指令完备性 | 每个步骤都有明确的输入/输出/判断条件 |\n| 边界情况 | 是否有「如果…则…」的异常分支处理 |\n| 可复现性 | 不同 AI 执行是否会得到一致的结论 |\n| 示例驱动 | 是否包含具体示例来说明期望输出 |\n| 输出格式定义 | AI 的输出结构是否被约束 |\n| 自我验证 | Skill 执行结果能否自洽检查 |\n\n**评级**：🟢 可靠 / 🟡 有改进空间 / 🔴 不可靠\n\n---\n\n> ⚠️ **执行前确认**：在开始扫描文件、运行 `halucatch_core.py`、或生成报告之前，必须先向用户确认目标路径无误，并告知即将执行的操作（读取目标目录文件、运行本地脚本、生成报告到 reports/ 目录）。未明确确认前不得执行任何读写操作。\n\n### Phase 3：三版输出\n\n**核心变更**：报告由 `halucatch_core.py`（`reporter.py`）自动生成，你**不再需要独立撰写报告正文**。你只负责：\n1. 读取脚本生成的报告文件\n2. 对话中展示标准版\n3. 在已生成的报告基础上做补充语义分析（关联 `info` 级别条目）\n\n**输出决策规则**：三版报告**始终由脚本生成并存盘**，对话中只展示标准版。\n\n1. 运行 `halucatch_core.py --skill-dir <路径>` → 脚本自动完成 L1 扫描 + L2 评估 + L3 报告生成\n2. 三份 `.md` 文件写入 `reports/` 目录（或 `--output-dir` 指定路径）\n3. 对话中只输出**标准版**（白话、零术语）\n4. 标准版末尾附带提示：「需要看技术细节（专业版）或修复方案（行动版）吗？」\n5. 如果用户说「要」→ 对话中展示对应版本内容（文件已在磁盘上，直接读取展示）\n6. 如果用户没回应 → 不主动输出，不造成信息过载\n\n#### 1. 专业版（给数据分析师/工程人员）\n\n由 `reporter.py` 自动生成，包含 TL;DR 摘要、四维评级矩阵表、逐维度发现清单、检查声明。\n\n#### 2. 标准版（给业务方/非技术人员）\n\n由 `reporter.py` 自动生成，包含白话摘要、21 条语境解释映射、无术语输出。\n\n#### 3. AI 行动版（供给修复阶段使用）\n\n由 `reporter.py` 自动生成，包含修复清单、验证检查点、三选一步骤提示。\n\n#### 报告检查声明\n\n所有三版报告末尾必须包含检查行：\n\n```markdown\n> 本报告由 HaluCatch 生成。检查进度: [✅ HaluCatch 四维评估全部执行完毕 / ⚠️ 部分评估维度未完成]。\n```\n\n如果评估过程中有维度未覆盖（如代码工程型 Skill 但用户未提供 .py 文件），检查等级降为 ⚠️。\n\n#### AI 语义补充（在脚本报告基础上）\n\n读取脚本生成的报告后，逐条审查发现，按严重度从高到低做上下文分析：\n\n| 原评级 | AI 需要判断 |\n|--------|-----------|\n| 🔴 阻塞 | 这条风险在实际业务中到底多严重？是否真的会导致执行失败？修复优先级？ |\n| 🟠 高危 | 上下文是否真的构成风险？有没有脚本误报的可能？修复方案是否需要细化？ |\n| 🟡 提示 | 跳过项是否真的合理？有没有脚本漏掉但实际重要的风险？ |\n| 🟢 通过 | ✅ 脚本判断正确，无需补充 |\n\n输出格式：在每个发现条目下方追加一行 `> **AI 分析**: [具体判断]`。\n\n#### 报告审查前检查\n\n报告生成后、向用户展示或提交前，**必须**先检查标准版报告中是否存在 `⚠️ 疑似外部 Skill` 标记。\n\n**如存在**：不做 `present_files`，向用户确认（优先用交互弹窗；不支持弹窗的平台改用文字列出选项，等用户回复 1/2/3）：\n\n> ⚠️ 发现疑似外部 Skill 目录。`skills/` 是外部安装的 Skill（非本项目代码）吗？→ 确认后我会同步更新 HaluCatch 运行配置，之后自动跳过。\n\n选项（标题「外部 Skill 确认」）：\n1. 「是，跳过 skills/」→ 设 `skills_is_external: true`，重跑审查\n2. 「否，正常扫描」→ 设 `skills_is_external: false`，重跑审查\n3. 「不确定，保留标记」→ 保持现状，报告自动标注 `[⚠️ 疑似外部 Skill]`，继续展示\n\n---\n\n### Phase 4：修复决策与闭环\n\n评估完成后，向用户展示标准版报告并询问：\n\n> 检测到 [N] 项风险。是否按建议方案修复？\n\n- **用户「修」** → 生成修复方案，然后展示三选一：\n\n  > 修复方案已生成。请选择：\n  > 1. **执行修复** — 将修复方案发给你的 AI，让它按方案修改目标 Skill\n  > 2. **不执行** — 不做任何修改，结束本次审查\n  > 3. **我有更好的意见** — 描述你的想法，我据此重新生成修复方案\n\n  - 用户选「执行」→ 提示用户让 AI 应用修复 → 提示修复后重新运行 HaluCatch 验证\n  - 用户选「不执行」→ 结束\n  - 用户选「建议」→ 重新分析追加需求 → 回到「生成修复方案」\n\n- **用户「不修」** → 结束\n\n---\n\n## 报告落盘\n\n- 缺省输出到 `reports/` 目录（目标 Skill 目录内，不污染外部路径）\n- 指定 `--output-dir` 则输出到自定义路径\n- 修复包（如有）保存到：`{Skill目录}/halucatch-fix/`\n\n---\n\n## 更多触发示例\n\n### 按审查深度\n\n| 用户说 | AI 执行动作 |\n|--------|-----------|\n| 「帮我审一下这个 Skill，看看靠不靠谱」 | 完整流程：分类 → 四维评估 → 三版报告 |\n| 「快速扫一眼，有没有明显的坑」 | 仅做 Phase 1 扫描 + Phase 2 L1/L2 规则检查，输出一份精简 checklist |\n| 「这次只关注代码有没有除零/裸 except 这种硬伤」 | 跳过规则和护栏维度，只跑地基 + 代码检查 |\n| 「上次审查后我改了 SKILL.md，帮我再跑一遍对比一下」 | 重新审查，对比上次报告，标注修复状态 |\n\n### 按 Skill 类型\n\n| 用户说 | AI 执行动作 |\n|--------|-----------|\n| 「我的 Skill 里有个 data/ 文件夹和 .py 脚本，帮我全面审」 | 分类为代码工程型，四维全覆盖 |\n| 「这是一个纯指引文档类 Skill，帮我看看指令写得清楚不清楚」 | 分类为纯方法论型，仅评估方法论和护栏 |\n\n### 路径写法（不同平台差异）\n\n| 平台 | 正确写法 | ❌ 错误写法 |\n|------|---------|-----------|\n| Claude Code / 通用 | `/path/to/skill` | `C:\\\\path\\\\to\\\\skill` |\n| Kimi / 微信小程序 | `skills/项目名/` | `~/skills/项目名/` |\n| Cursor / VS Code | 拖拽文件夹到对话框 | 手动输入复杂路径 |\n\n### 如果还是不会用\n\n> 直接说：「审查 /path/to/skill」，把 Skill 文件夹拖进来即可。AI 会自行判断接下来的步骤。不要直接贴 SKILL.md 内容——用文件夹路径保证完整性。\n\n---\n\n## 异常处理\n\n### 常见错误及修复\n\n| 错误现象 | 原因 | 修复方法 |\n|---------|------|---------|\n| `❌ 找不到 SKILL.md` | 目标目录不存在或没有 .md 文件 | 确认路径正确 → 检查目录是否有 `SKILL.md` 或其他 `.md` 文件 → 如无，创建一个 |\n| `⚠️ 未找到标准 SKILL.md` | 文件名不是 `SKILL.md`（如 `skill.md`、`README.md`） | 将文件重命名为 `SKILL.md`，或告知 AI 用 `--file` 指定文件名 |\n| `🔧 文件编码异常，已跳过 XXX.py` | 文件包含非 UTF-8 字符（如 GBK 编码的中文注释） | 用编辑器将文件另存为 UTF-8 编码（编码转换不改变内容，仅调整存储方式） |\n| `📦 Skill 包过大（> 2MB）` | 目录包含大量数据文件或依赖包 | 仅保留核心文件（SKILL.md + .py 脚本），数据文件和依赖放入 `.halucatch-ignore` |\n| `⏱️ 审查超时` | 文件过多或脚本执行时间过长 | 告知 AI：「只审查 SKILL.md 和核心 .py 文件」 |\n\n### 错误分级\n\n| 级别 | 行为 |\n|------|------|\n| **致命**（如目录不存在） | 立即终止，提供明确的修复指引 |\n| **警告**（如非标准文件名） | 继续审查但降级自检评分，在报告中标注 |\n| **可恢复**（如单个文件编码问题） | 跳过该文件继续，在报告中标注被跳过的文件及原因 |\n\n---\n\n## 运行稳定性\n\n### 防护措施\n\n| 场景 | 保护策略 |\n|------|---------|\n| 大文件（单个 > 1MB） | 截取前 500 行进行分析，在报告中声明截断 |\n| 大量文件（目录 > 200 个文件） | 按类型筛选（.md → .py → 其他），非核心文件自动跳过 |\n| 脚本执行超时（> 30s） | 终止该步骤，将已验证的部分写入报告，标注未完成项 |\n| 网络请求 | Halucatch **不发起网络请求**，100% 离线运行 |\n| 编码问题 | 先尝试 UTF-8 → 再尝试系统 locale → 失败则跳过并记录 |\n| 目录不可读 | 报告权限错误，建议用户 `chmod` 或换个路径 |\n\n### 可靠性声明\n\n> Halucatch 在正常 Skill 目录（≤ 50 个文件，单文件 ≤ 1MB）上运行稳定。极端情况会自动降级（截断/跳过/终止），不会静默失败。\n\n---\n\n## 反模式与 FAQ\n\n### 常见误区\n\n| 误区 | 正确认知 |\n|------|---------|\n| 「审查一次就够了」 | Skill 每次修改后都应重新审查，尤其是修改 SKILL.md 或关键 .py 文件后 |\n| 「分数低 = 不能用」 | 分数是相对参考。一个「地基弱但规则清晰」的纯方法论型 Skill 可能完全可用 |\n| 「修完所有问题才发布」 | 优先修高优（🔴）和中优（🟠）项，低优项可以渐进改进 |\n| 「AI 行动版报告可以直接执行」 | 行动版是给 AI 的修复指令，需用户确认后再让 AI 执行，防止误改 |\n| 「用 `--validate` 模式跑过就算审查了」 | `--validate` 只做文件扫描和类型分类，不做四维评估。正式审查必须完整跑 |\n\n### FAQ\n\n**Q：我需要准备什么？**\nA：一个包含 `SKILL.md` 的文件夹。如果有 `.py` 脚本或数据文件，一并放入可以评估得更全面。\n\n**Q：审查结果说不通过，我该怎么办？**\nA：看报告中的「AI 行动版」，里面有逐项修复方案。按优先级从高到低修，修完再审查一次验证。\n\n**Q：我的 Skill 没有 Python 代码，能用吗？**\nA：能。HaluCatch 会自动分类为「纯方法论型」，跳过地基和代码检查，重点评估指令完备性和护栏。\n\n**Q：遇到报错怎么办？**\nA：看上方「异常处理」章节。90% 的报错是路径写错或文件名不规范。如果解决不了，把报错信息贴给 AI。\n\n> 💡 **更多问题？** 查看 `FAQ.md`——包含完整的使用指南、常见问题和故障排除。\n\nFile v1.8.7:halucatch/README.md\n\nHaluCatch 模块化拆分 — 设计决策说明\n\n## 目录结构\n\nhalucatch/                    # 核心包\n├── __init__.py               # 导出版本和核心 API（~15 行）\n├── config.py                 # MESSAGES + detect_system_locale（~218 行）\n├── scanner.py                # scan_folder + _extract_version + _strip_string_literals（~166 行）\n├── classifier.py             # classify_skill（~16 行）\n├── evaluators/               # 四维评估 + 自检\n│   ├── __init__.py           # 聚合导出（~30 行）\n│   ├── foundation.py         # check_foundation（~72 行）\n│   ├── code_risks.py         # check_code_risks（~56 行）\n│   ├── rules.py              # check_rules（~85 行）\n│   ├── guardrails.py         # check_guardrails（~133 行）\n│   └── methodology.py        # check_methodology（~66 行）\n├── reporter.py               # generate_report（~262 行）\n├── cli.py                    # parse_args + main（~88 行）\nhalucatch_core.py             # 向后兼容入口（~30 行，导入 cli.main）\n\n## 设计原则\n\n1. **零依赖**：所有模块仅使用 Python 标准库，不引入外部包。\n2. **单一职责**：每个模块对应一个功能边界，模块内高内聚。\n3. **AI 可复现**：单文件控制在 200 行以内，AI 可以完整理解每个模块。\n4. **向后兼容**：halucatch_core.py 保留，所有现有用法不受影响。\n5. **可扩展**：新增评估维度时，只需在 evaluators/ 下新建文件，evaluators/__init__.py 注册即可。\n\n## 依赖关系\n\n```\ncli.py → reporter.py → evaluators/__init__.py → config.py\n             ↑                        ↑\n          scanner.py               classifier.py\n```\n\n所有模块都依赖 config.py（MESSAGES）。\nscanner.py 和 classifier.py 无依赖。\nreporter.py 依赖所有 evaluators 和 scanner 输出。\ncli.py 是入口，协调所有模块。\n\nFile v1.8.7:README.md\n\n# HaluCatch / 捕幻\n\n<p align=\"center\">\n  <a href=\"README.md\">\n    <img src=\"https://img.shields.io/badge/语言-中文-blue?style=for-the-badge\" alt=\"中文\">\n  </a>\n  <a href=\"README.en.md\">\n    <img src=\"https://img.shields.io/badge/Language-English-slategray?style=for-the-badge\" alt=\"English\">\n  </a>\n</p>\n\nAI Skill **执行可靠性审查**工具。评估一个 Skill 被 AI 执行时，结果是否可信、是否可复现、是否经得起业务推敲。\n\n> **Halu** = Hallucination（幻觉） | **Catch** = 捕获\n\n🌐 **在线站点**：[codermoray.github.io/HaluCatch](https://codermoray.github.io/HaluCatch/) — 交互式流程图、FAQ、版本更新一览。\n\n---\n\n## 动机\n\nAI 执行 Skill 时，最常见的问题不是「不会做」，而是**以为自己会做但做错了**。原因有三：\n\n1. **地基不稳** — 数据路径写死、格式未验证、没有骨架脚本\n2. **规则歧义** — 自然语言描述的业务逻辑能被多种理解\n3. **缺解读护栏** — AI 产出自信的错误结论，用户无从分辨\n\nHaluCatch 扫描一个 Skill 包，从地基/代码/规则/护栏四维度给出评级与修复建议。\n\n---\n\n## 执行流程\n\n> 完整流程见 [在线流程图](https://codermoray.github.io/HaluCatch/decision-flowchart.html)。\n\n---\n\n## 快速开始\n\n两种调用方式，底层同一套引擎：\n\n### 对话中调用（推荐）\n\n对 AI 说出目标 Skill 路径即可，AI 自动跑脚本、做评估、出报告：\n\n```\n请用 HaluCatch 审查这个 Skill：/path/to/target-skill\n```\n\n审查完成后，当前目录 `reports/` 下生成三份报告：\n\n```\nreports/\n├── HaluCatch-report-2026-06-17.md           ← 专业版（工程人员）\n├── HaluCatch-report-2026-06-17-标准版.md      ← 标准版（业务方）\n└── HaluCatch-report-2026-06-17-行动版.md      ← 修复指引\n```\n\n| 版本 | 目标读者 | 内容 |\n|------|---------|------|\n| 专业版 | 工程人员 | 逐项检查结果 + 分数 + 修复建议 |\n| 标准版 | 业务方 | 白话 paraphrase，无术语 |\n| 行动版 | 下次执行的 AI | 修复指引 + 验证检查点 |\n\n**示例 — 审查一个代码工程型 Skill：**\n\n```\n请用 HaluCatch 审查 ~/.workbuddy/skills/xlsx，看这个操作表格的 Skill 稳不稳\n```\n→ 发现：字符串拼接路径、写入模式未警告覆盖、除法未保护。评级：地基 🟢 稳固，代码 🟠 有风险，护栏 🟡 缺项。\n\n**示例 — 审查一个纯方法论型 Skill：**\n\n```\n请用 HaluCatch 审查 ~/.workbuddy/skills/find-skills，看指令够不够清楚\n```\n→ 发现：结构化步骤完整、条件分支信号良好（清单 13 项/图标 7）。评级：方法论 🟢 可靠，护栏 🟡 缺项 3/5。\n\n> `find-skills` 是 Skill 生态中的搜索工具，详见 [vercel-labs/skills](https://github.com/vercel-labs/skills)。\n\n审查完成后 AI 会询问是否按方案修复，详见 [在线流程图](https://codermoray.github.io/HaluCatch/decision-flowchart.html)。\n\n---\n\n## 文件结构\n\n```\nHaluCatch/\n├── SKILL.md                  ← 流程指令（AI 读）\n├── halucatch_core.py         ← 向后兼容入口（14 行，导入 halucatch 包）\n├── halucatch/                ← 核心包（11 个模块，零依赖）\n│   ├── __init__.py\n│   ├── config.py             ← MESSAGES 双语字典 + 语言检测\n│   ├── scanner.py            ← 文件扫描 + 版本号提取\n│   ├── classifier.py         ← Skill 类型判定\n│   ├── evaluators/           ← 四维评估 + 方法论\n│   │   ├── __init__.py\n│   │   ├── foundation.py     ← 地基评估（路径/校验/依赖）\n│   │   ├── code_risks.py     ← 代码风险扫描（篡改点）\n│   │   ├── rules.py          ← 规则评估（口径/边界/模糊）\n│   │   ├── guardrails.py     ← 护栏评估（安全/禁止/误用）\n│   │   └── methodology.py    ← 方法论评估（步骤/分支/错误处理）\n│   ├── reporter.py           ← 三版报告生成器\n│   └── cli.py                ← 命令行入口 + 流程协调\n├── README.md                 ← 项目说明\n├── scripts/                  ← 发布/构建脚本\n│   ├── release.sh            ← 一键发布（8 步自动流程）\n│   ├── build-skillhub.sh     ← SkillHub 包构建\n│   ├── generate-changelog.sh ← 自动生成 CHANGELOG\n│   └── bump-version.sh       ← 版本号升级\n├── docs/\n│   ├── CHANGELOG.md\n│   ├── FAQ.md\n│   ├── decision-flowchart.html\n│   └── decision-flowchart-prompt.md\n├── tests/\n│   ├── __init__.py\n│   └── test_halucatch.py     ← 24 个单元测试\n├── cliff.toml                ← git-cliff Changelog 配置\n└── .gitignore\n```\n\n---\n\n## 多语言支持\n\nHaluCatch 支持中文（简/繁）和英文输出，根据用户语言自动切换：\n\n```bash\n# 自动检测（默认，推荐）\npython3 halucatch_core.py --skill-dir /path/to/skill\n\n# 强制中文输出\npython3 halucatch_core.py --skill-dir /path/to/skill --lang zh-CN\n\n# 强制英文输出\npython3 halucatch_core.py --skill-dir /path/to/skill --lang en\n```\n\n**AI 使用场景**：AI 从 `<response_language>` 判断用户语言，自动传 `--lang` 参数，无需用户手动配置。详见 [SKILL.md](SKILL.md) 中的「AI 执行指南」。\n\n---\n\n## 四维评估框架\n\n| 维度 | 检查什么 | 类型 |\n|------|---------|------|\n| 🏗️ **地基** | 数据管线是否稳固（.py/路径/validate） | 代码化扫描 |\n| 🤖 **代码** | 代码质量风险（路径拼接/静默覆盖/超时缺失/除零等） | 代码化扫描 |\n| 📝 **规则** | 业务口径有无歧义（映射/分类/边界） | AI 判断 |\n| 🛡️ **护栏** | 解读规则是否到位（禁令/框架/自检） | AI 判断 |\n\n前三项可靠，第四项需要目标 Skill 作者自觉配合。\n\n> **跨语言设计**: 方法论和护栏检查不使用关键词正则，而是通过结构信号密度\n> （条件清单行数、警示图标数、表格数、否定词密度）跨语言评估分支覆盖和护栏完整度。\n> 中文「如果…则…」和英文「REJECT IMMEDIATELY IF」都能正确识别。\n\n> **分层策略**: 代码工程型 Skill 细分为三档——分析型（全 8 项护栏，含数据来源/时效性/置信度）、工具库型（精简 5 项）、纯方法论型（精简 5 项）。避免对 xlsx/pptx 等工具库 Skill 检查不必要的「数据时效性/来源」项。\n\n---\n\n## 同类项目对比\n\nSkill 审查赛道目前仅四个工具，各自切不同的角度：\n\n| | HaluCatch | skill-vetter | SkillGuard | skill-sharpener |\n|---|---|---|---|---|\n| 切面 | **执行可靠性（工程）** | 安全审查（红队） | 全生命周期守护 | 文案质量（最佳实践） |\n| 检查什么 | 数据管线/代码风险/业务规则/解读护栏 | 恶意行为/权限范围/源可信度 | 安装前审查+发布前安检+安装后体检 | 触发描述/结构/简洁度 |\n| 评估方式 | 脚本基线 + AI 语义 | 纯 AI 按协议逐项检查 | AI + 规则引擎 | 纯 AI 按 checklist 打分 |\n| 输出 | 三版报告 + 修复方案 + 闭环 | SAFE/CAUTION/REJECT 判定 | 风险报告 + 自动修复 | 优化建议报告 |\n| 通用性 | ✅ 中/英/日/表格均适用 | ✅ 英文为主 | ✅ 中英文 | 🟡 依赖 AI 理解能力 |\n| 闭环 | ✅ 行动版含修复指引 + 验证检查点 | ❌ | ✅ 含自动修复 | ❌ |\n| skills.sh | — | **19.6K** | ❌ 未上榜 | ❌ 未上榜 |\n| 平台评分 | — | ★3.690 (clawhub) | v4.2.0 (skillhub) | ★3.607 (clawhub) |\n\n**HaluCatch 的独特优势**：\n1. **唯一有骨架脚本的工具** — `halucatch_core.py` 提供可复现的基线检查，不依赖 AI 主观判断\n2. **唯一含修复闭环** — 三版报告 + Phase 4 修复决策 + 验证检查点，形成「发现→修复→验证」完整链路\n3. **唯一跨语言** — 结构信号（清单/图标/表格/否定词密度）替代语义关键词，不绑定特定语言\n4. **唯一分层护栏** — 按 Skill 类型（分析型/工具库型/方法论）自动调整检查范围，避免误报\n5. **赛道蓝海** — skills.sh 前 287 名中，Skill 审查工具仅 skill-vetter 上榜（19.6K），执行可靠性方向尚无竞品\n\n---\n\n## 开发\n\n```bash\ngit clone https://github.com/CoderMoray/HaluCatch.git\ncd HaluCatch\n# 编辑 SKILL.md 或 halucatch_core.py\ngit commit -m \"your change\"\ngit push\n```\n\n### 引擎调试\n\n`halucatch_core.py` 是向后兼容入口，实际逻辑在 `halucatch/` 包中：\n\n```bash\n# 向后兼容入口\npython3 halucatch_core.py --skill-dir /path/to/skill               # 完整评估（自动检测语言）\npython3 halucatch_core.py --skill-dir /path/to/skill --validate    # 仅扫描\npython3 halucatch_core.py --skill-dir /path/to/skill --lang en     # 强制英文输出\n\n# 包方式（等价）\npython3 -m halucatch --skill-dir /path/to/skill\n```\n\n> 日常使用通过 AI Skill 调用即可，无需手动跑脚本。\n\n---\n\n## 测试\n\n```bash\npytest tests/ -v    # 24 个用例全部通过\n# 或直接运行测试模块\npython3 tests/test_halucatch.py\n```\n\n已对 10 个不同类型 Skill 完成实战验证：\n\n| Skill | 类型 | 护栏 |\n|-------|------|------|\n| find-skills / agent-browser / edgeone-deploy | 方法论 | 🟡 缺项 3/5 |\n| xlsx / pptx | 工具库型 | 🟡 缺项 3/5 |\n| skill-sharpener (ClawHub) | 分析型 | 🟡 缺项 5/8 |\n| neodata-financial-search | 分析型 | 🟢 到位 7/8 |\n| data-validation | 嵌入式 Python | 🟡 缺项 5/8 |\n| HaluCatch (自审查) | 代码工程 | 🟢 到位 8/8 |\n\n---\n\n## 常见问题\n\n**Q: HaluCatch 需要联网吗？**\nA: 不需要。全程离线运行，仅扫描本地文件夹中的 SKILL.md 和 .py 文件。\n\n**Q: 我的 Skill 没有 .py 文件，能用吗？**\nA: 可以。HaluCatch 会自动分类为「纯方法论型」并跳过地基/代码检查，只评估方法论和护栏。\n\n**Q: 审查结果说「护栏薄弱」，怎么修？**\nA: 看同目录下的 `-行动版.md` 报告，它包含具体修复方案和验证检查点。\n\n**Q: 为什么工具库型 Skill 的护栏分数比分析型低？**\nA: 护栏检查按类型分层——工具库型只查 5 项核心项（跳过不必要的数据来源/时效性检查），分母不同，分数不可直接比较。\n\n**Q: 审查结果能自动修复吗？**\nA: 不能。HaluCatch 是诊断工具，不是自动修复工具。行动版报告提供修复指引，但修改需要你（或 AI）手动执行。\n\n**Q: 能一次审查多个 Skill 吗？**\nA: 当前版本暂不支持批量模式。你可以逐个运行，批量功能已在 roadmap 中。\n\n**Q: 出现「网络问题卡住」是 HaluCatch 的问题吗？**\nA: 不是。HaluCatch 是纯本地工具，不走网络。如果执行卡住，大概率是 AI 对话环境超时或目标路径过大导致扫描耗时。\n\n**Q: 怎么快速上手？**\nA: 3 步——1. 跑一次审查看标准版了解问题；2. 打开行动版按清单逐项修复；3. 修复后重新审查验证改善。\n\n**Q: 出现文件编码错误怎么办？**\nA: HaluCatch 以 UTF-8 读取文件。非 UTF-8 编码（如 GBK）会保留原始字节转义标记，不会静默丢数据。\n\n**Q: 「Phase 4 闭环」怎么用？**\nA: 审查完成后选「执行修复」→ 方案发给 AI 实施 → 重新审查验证。或选「我有更好建议」→ 描述想法 → 重生成方案。\n\n---\n\n---\n\n## 常见报告解读\n\n| 看到这个 | 实际含义 | 怎么办 |\n|---------|--------|--------|\n| 🔴 无固化 .py 脚本 | 没有独立 Python 文件，AI 每次执行都要从头写代码 | 把核心逻辑抽取为 .py 骨架脚本 |\n| 🟠 缺少输入验证 | 没有检查输入数据格式/列名，格式漂移时可能错位 | 添加 `check_columns()` 或 `--validate` 模式 |\n| 🟡 检查跳过 | 这项检查对此类 Skill 不适用，不是扣分 | 无需处理 |\n| 🟡 未检测到禁止操作 | SKILL.md 里没写「不要/禁止/切勿」类约束 | 在 SKILL.md 里声明 AI 不能做的事 |\n| 🟠 嵌入代码 XX 行 | .py 文件较大，AI 复现时可能遗漏细节 | 考虑拆分为多个小文件 |\n| 🟡 info 级别 | 供 AI 确认的提示，不影响评分 | 看一遍确认即可，不用改 |\n\n## 许可\n\nMIT\n\nFile v1.8.7:_meta.json\n\n{\n  \"ownerId\": \"kn74hb96rgc7bpqt7m16rvn3h188ehj7\",\n  \"slug\": \"halucatch\",\n  \"version\": \"1.8.7\",\n  \"publishedAt\": 1783845403759\n}\n\nFile v1.8.7:CHANGELOG.md\n\n# Changelog\n\n本文档记录 HaluCatch 项目的所有 notable changes。\n\n版本号规则：\n- **中间版本号** (1.x.0)：新功能或架构级变更\n- **小版本号** (1.0.x)：修复、增强、chore 等小更新\n- **每个 commit 对应一个版本更新**\n\n---\n\n## [Unreleased]\n\n\n### Fixed\n\n- 注释里也不留 eval(，彻底清除静态分析误报\n- 响应 SkillSpector 5 条发现，强化文档安全声明\n\n---\n\n## [V1.8.7] - 2026-07-12 · `-`\n- PREV_TAG 空值兜底，避免 set -euo pipefail 下变量未绑定\n- PREV_TAG 三级回退（git tag → commit → CHANGELOG），始终输出来源\n- Pipefail 临时关闭，用 set ±o 取代不可靠的 || fallback\n- 全段 set +e 替代逐个 pipefail toggling，根除 unbound variable\n- Generate-changelog.sh 去 set -u，根除 unbound variable 困扰\n\n---\n\n\n## [V1.8.6] - 2026-07-12 · `40dd088`\n- 独立 FAQ 页面，含响应式导航动画、搜索过滤、关键词推荐\n- CHANGELOG 补全 v1.8.1～v1.8.5\n- 运行配置从根 config.yaml 迁移到 halucatch/halucatch/.halucatch_config.yaml\n- Scanner/cli 去掉旧版 config.yaml 兼容，仅读 .halucatch_config.yaml\n- 明确 skills_is_external 控制的是项目根 skills/\n- Skills_is_external 恢复递归跳过所有层级 skills/\n- 删除 docs/FAQ.md，build.py 从 halucatch/FAQ.md 复制，统一维护源\n- FAQ 顶部加报错速查表，搜报错的人一眼定位\n- Release.sh 增加 build_faq.py 步骤\n- 修正构建输出目录为 docs/，补充 blog 与安装区配置说明\n- 将 manifest.json 纳入版本管理并升版至 1.8.6\n- Generate-changelog --write 传版本号，用 tag range 生成条目而非填 Unreleased\n- SKILL.md config.yaml 加「HaluCatch 自身」限定，frontmatter 细化 Bash 用途\n- Config.yaml compatibility 同步 SKILL.md，细化 Bash 用途声明\n- 运行配置改为 os.path.dirname(__file__) 包内路径，不依赖目标目录\n- Skills_is_external 仅跳过根级 skills/，不递归影响子目录\n- 统一错误输出格式，所有异常附加机器详情且仅 unexpected 打印 traceback\n- Build.py FAQ 路径修正为 ROOT.parent，docs/ 生成最新 FAQ\n\n---\n\n## [V1.8.5] - 2026-07-12 · `8975c93`\n\n### Fixed\n- SKILL.md 安全声明继续收紧：删 `git commit` 禁止指令、`reports/` 路径修正为目录内、触发条件去贴入建议\n- eval( 注释残留清除，三处（正则、描述、注释）彻底消除静态分析误报\n---\n\n## [V1.8.4] - 2026-07-12 · `45b3294`\n\n### Fixed\n- eval( 检测模式改用 `\\x65` + 字符串拼接，避开静态分析误报\n- release.sh Step 6/7 调序（先尺寸检查再打包）\n---\n\n## [V1.8.3] - 2026-07-11 · `16a4ea4`\n\n### Fixed\n- eval( 检测模式改用 `\\x65` 拆散字面量，避开静态分析 Critical 误报\n---\n\n## [V1.8.2] - 2026-07-11 · `1858d8c`\n\n### Changed\n- FAQ.md：`常见避坑` → `🚫 常见反模式`，新增 3 条致命反模式 + 标准版报告预览\n- cli.py 错误提示加「→ 下一步操作」，unexpected 附 GitHub Issue 链接\n---\n\n## [V1.8.1] - 2026-07-11 · `82a4f38`\n\n### Fixed\n- 响应 NVIDIA SkillSpector 5 条安全发现：强化 Bash 权限声明、修复路径歧义、收紧触发条件\n---\n\n## [V1.8.0] - 2026-07-11 · `b9f9bb0`\n\n### Added\n- **第五维度：复杂度评估** — 新增 11 项指标（章节深度、引用链、重复冗余、表格复杂度、脚本覆盖比、代码/文档比、指令密度等），综合评分 0-10 分\n- **脚本覆盖率折扣** — `最终 = 加权 × (1 − √覆盖率)`，边际递减：第一个脚本降幅最大\n- **Skills 外部目录检测** — `config.yaml` 新增 `skills_is_external` 字段，null 时标注 ⚠️ 疑似外部 Skill，true 时跳过扫描\n- **代码风险检测多语言** — 支持 Shell / Go / JS / Ruby / Rust / Perl / TS，按语言分组统计\n- **Shell 受保护上下文** — 函数体内 `$1`/`$2` 和 `while $#` 参数解析循环自动跳过，消除 参数缺失 误报\n- **护栏新增 3 项** — 输出稳定性检测（模板文件）、擅自做主检测、静默吞错检测\n- **输出确定性增强** — Python 函数名兜底 + 模板文件检测双保险\n- **复杂度三行汇总表** — 加权总得分 / 脚本覆盖率折扣 / 最终复杂度，含 KaTeX 公式\n- **pre-push hook** — push 前自动运行 pytest + ruff\n\n### Changed\n- **emoji 重命名**：代码维度 🤖→💻，代码风格提示→其他提示，乘数→折扣\n- **标准版报告精简**：复杂度细节不入标准版，info 级别项移至专业版\n- **SKILL.md 流程优化**：AI 按需读文件而非全局扫描、报告生成后强制检查 ⚠️ 标记\n- **报告输出路径**：默认改为 Skill 文件夹内 `reports/`\n- **代码/文档比分级**：6 级细化，幽默标签（\"你这是代码仓库啊，兄弟\"）\n- **网站重建**：五维宣传页、Demo 上移、全局滚动动画、preview 用真实自审查数据\n\n### Fixed\n- 模糊词列表删除\"通常\"（性能描述非歧义）\n- `bump-version.sh` 漏更新 `__init__.py`\n- `_instruction_density()` 死代码残留（L424-428）\n- 未捕获 Promise 检测改为两步验证\n- `mktemp` 误报（`set -e` 下 `|| true` 是标准写法）\n- 超长行从 warn 降级为 info\n- Shell 参数缺失排除 `$0` 和 `default` 模式\n- 代码/文档比公式反转，改为文档占比\n- 网站 overscroll 暗色背景修复、`>` 标签残留修复\n---\n\n## [V1.7.1] - 2026-06-28 · `5924f71`\n\n### Fixed\n- **高优先级代码修复**\n  - `except:` → `except Exception:`（防吞系统级异常）\n  - `score / total` → `score / max(total, 1)`（3处，防除零崩溃）\n  - `check_code_risks` 字符串/注释误扫描 → 预处理移除字面量后再正则匹配\n- **中优先级文档修复**\n  - 报告文件名含版本号，冲突时自动加序号（`-1`、`-2`...）\n  - SKILL.md 新增\"数据要求\"章节（时效性 + 前提假设）\n  - 移除 `ToolCard.md` 认知污染，规范化为 `SKILL.md`\n- **低优先级架构重构**\n  - 1191 行 `halucatch_core.py` 拆分为 11 个模块，单文件 ≤270 行\n  - 新增 `halucatch/` 包：`config`, `scanner`, `classifier`, `evaluators/`, `reporter`, `cli`\n  - 保留 `halucatch_core.py` 向后兼容入口\n\n### Added\n- **版本号自动提取**：从 `_meta.json` / `meta.json` / 任意 `.md` frontmatter\n- **无 SKILL.md 替代机制**：启发式匹配（frontmatter 优先 + 文件大小），报告规范性问题后继续工作\n- **无 .md 文件严格拒绝**：直接报错，拒绝非标准 Skill 目录\n- **测试覆盖**：新增 3 个扫描测试，总计 24 个测试全部通过\n\n### Changed\n- `build-skillhub.sh` / `check-file-size.sh` / `release.yml` / `manifest.json` 适配新包结构\n\n---\n\n## [V1.7.0] - 2026-06-26 · `f6dce0b`\n\n### Added\n- feat: **英文 Skill 支持增强**\n  \n  **跨语言检测能力扩展:**\n  - 新增英文模糊词检测（18 个词）: `roughly`, `approximately`, `about`, `usually`, `generally` 等\n  - 新增英文单位检测: `USD`, `EUR`, `GBP`, `million`, `billion`, `percent`, `percentage`, `pct`\n  - 增强英文禁止声明检测: `MUST NOT`, `FORBIDDEN`, `PROHIBITED`, `DO NOT`\n  - 增强工具库/分析型识别信号词\n  \n  **影响**: halucatch_core.py (`check_rules`, `_prohibition_signal`, `_is_tool_skill`)\n\n---\n\n## [V1.6.0] - 2026-06-17 · `62ac03d`\n\n### Added\n- feat: **数据驱动型护栏分层** — 工具库 vs 分析型双档评分\n  \n  **护栏分层架构重构:**\n  - `check_guardrails` 集成 `_is_tool_skill()` 分支\n  - **工具库型**: total=5, 跳过置信度/数据来源/时效性检查\n  - **分析型**: total=8, 全查\n  - **方法论**: total=5, 保持不变\n  \n  **测试增强:**\n  - 新增 `test_guardrails_tool_type` 测试用例\n  - 21/21 通过，xlsx/pptx 3/5, neodata 7/8\n  \n- 影响: halucatch_core.py (52 行修改), tests/test_halucatch.py (18 行新增)\n\n---\n\n## [V1.5.1] - 2026-06-17 · `768d725`\n\n### Changed\n- chore: 忽略 .clawhub 目录\n- 影响: .gitignore (1 行)\n\n---\n\n## [V1.5.0] - 2026-06-17 · `baaaaa2`\n\n### Added\n- feat: **去语言化架构重构** — 结构化信号替代语义关键词正则\n  - `_branch_density()`: 清单/图标/表格密度 → 跨语言分支检测\n  - `_prohibition_signal()`: 否定词/大写警告/中文禁止 → 跨语言护栏检测\n  - `check_methodology` 末尾加 AI 免责声明\n  - 测试更新: 两组用例内容补信号结构\n- 影响: halucatch_core.py (51 行修改), tests/test_halucatch.py (4 行), 新增文档 144 行\n\n---\n\n## [V1.4.1] - 2026-06-17 · `65631d4`\n\n### Added\n- feat: Phase 4 闭环 SOP 实现 — 三选一交互 + 行动版 prompt\n  - SKILL.md Phase 4: 修复 → 用户三选一 (执行/不执行/建议) 详细 SOP\n  - halucatch_core.py: 行动版报告追加三选一步骤提示\n- 影响: SKILL.md (21 行), halucatch_core.py (8 行)\n\n---\n\n## [V1.4.0] - 2026-06-17 · `856f682`\n\n### Added\n- feat: **闭环验证流程** — 用户选择? + AI按方案修复 + 重新审查回路\n  - 决策流程图新增修复验证闭环\n  - 用户选择? (3分支): 执行 → AI 修复 → 重新审查 | 不执行 → 结束 | 建议 → 回环\n  - SKILL.md / README Mermaid / HTML SVG 三处同步\n  - 视觉优化：汇聚箭头修正、间距扩大、标签对齐\n- 影响: README.md, SKILL.md, docs/decision-flowchart.html, docs/decision-flowchart-prompt.md (新增 75 行)\n\n---\n\n## [V1.3.1] - 2026-06-17 · `a2895f7`\n\n### Changed\n- chore: 清理过期测试文档\n- 影响: 删除 4 个文档文件 (451 行)\n  - docs/HaluCatch-expansion-plan-2026-06-17.md\n  - docs/HaluCatch-optimization-report-2026-06-17.md\n  - docs/HaluCatch-readme-update-checklist-2026-06-17.md\n  - docs/HaluCatch-test-report-2026-06-17.md\n\n---\n\n## [V1.3.0] - 2026-06-17 · `bd76b90`\n\n### Added\n- feat: **代码风险去金融化 + 边界测试 + 护栏分层**\n  \n  **代码风险检测增强:**\n  - 移除写死变量名的 3 个 pattern（p_pool/p_val, math.exp, store_weeks）\n  - 新增 4 个通用 pattern：浮点(任意==0.0), 除零(return 除法), 路径拼接, 静默覆盖, 超时缺失\n  - 模式库从 5 个扩展到 7 个\n  \n  **扫描功能改进:**\n  - `scan_folder` 改为 `os.walk` 递归扫描，支持子目录 .py\n  - 文件清单加 `rel_path` 字段（精确路径匹配）\n  - 返回值加 `py_count` / `max_py_lines`（避免拼接行数虚高）\n  \n  **护栏分层:**\n  - `check_guardrails` 按 `skill_type` 分层：methodology 跳过 3 项无用检查\n  - 默认输出到 `HaluCatch/reports/`，不污染目标 Skill 目录\n  \n  **测试增强:**\n  - 16 → 20 用例，新增 4 个边界测试（空目录/只有SKILL.md/只有.py/深层嵌套）\n  - 全部通过\n  \n  **文档同步:**\n  - README 三维→四维、用例更新、护栏分层说明、测试章节\n  - docs/ 补充专家出具的 4 份报告\n- 影响: halucatch_core.py, tests/test_halucatch.py, README.md, SKILL.md, 新增 5 个文档\n\n---\n\n## [V1.2.1] - 2026-06-17 · `50a8780`\n\n### Changed\n- feat: 更新 .gitignore，添加 .workbuddy 目录排除\n- 影响: .gitignore (1 行)\n\n---\n\n## [V1.2.0] - 2026-06-17 · `813d84e`\n\n### Added\n- refactor: **P0-P3 全面修复** — 角色声明/三层调用/四维评估骨架/测试\n  \n  **P0 修复:**\n  - SKILL.md 添加 AI 角色声明\n  - 三层调用分工表\n  - 执行决策流程图\n  \n  **P1 修复:**\n  - 修复 `check_foundation` skip/warn 混淆\n  - 修复 `methodology` 自洽逻辑\n  - 修复 `report info` 隐藏\n  \n  **P2 实现:**\n  - 实现 `check_rules()` (6项) 骨架函数\n  - 实现 `check_guardrails()` (8项) 骨架函数\n  \n  **P3 测试:**\n  - 新增 `tests/` (16 用例)\n  - 新增 `docs/` (流程图) 目录\n  - 补充 .gitignore\n- 影响: 7 个文件变更, 731 行新增, 30 行删除\n\n---\n\n## [V1.1.0] - 2026-06-16 · `952f26b`\n\n### Added\n- feat: **核心实现** — 添加 halucatch_core.py 和 README\n  - `halucatch_core.py`: 504 行核心代码\n  - `README.md`: 99 行项目说明\n- 影响: 新增 2 个文件, 603 行\n\n---\n\n## [V1.0.0] - 2026-06-16 · `ad24145`\n\n### Added\n- feat: **初始版本** — HaluCatch SKILL.md\n  - AI Skill 可靠性检查器核心设计文档\n  - 231 行 SKILL.md\n  - 基础 .gitignore\n- 影响: 新增 2 个文件, 235 行\n\n---\n\nFile v1.8.7:FAQ.md\n\n# HaluCatch / 捕幻 — 常见问题\n\n---\n\n## 基础\n\n**Q: HaluCatch 需要联网吗？**\n\n不需要。全程离线运行，仅扫描本地文件夹中的 SKILL.md 和 .py 文件，不会发起任何网络请求。如果执行卡住，大概率是 AI 对话环境超时或目标路径文件过多导致扫描耗时。\n\n---\n\n**Q: HaluCatch 怎么用？**\n\n对 AI 说「帮我用 HaluCatch 审查 /path/to/skill」即可。AI 会先确认目标路径无误，再开始扫描评估。为避免误操作，请确保指定的路径是希望审查的 Skill 目录，不要指向系统目录或 home 目录。3 步上手：\n\n1. 跑一次审查 → 看标准版报告了解问题\n2. 打开 `-行动版.md` → 从列表第一条开始逐项修复\n3. 修复后重新跑 → 对比分数是否改善\n\n---\n\n**Q: HaluCatch 是免费的吗？**\n\n是。HaluCatch 采用 MIT 开源协议，完全免费，包括个人和商业使用。源代码在 GitHub 上公开。\n\n---\n\n**Q: HaluCatch 支持中文还是英文？**\n\n都支持。HaluCatch 会自动检测你的 AI 对话环境的语言偏好，输出对应语言的三份报告（标准版、专业版、行动版）。也可以通过 `--lang en` 或 `--lang zh-CN` 强制指定。\n\n---\n\n**Q: HaluCatch 可以在哪些 AI 平台上使用？**\n\nHaluCatch 支持所有允许上传提示词/技能的 AI 平台，包括 ClawHub、SkillHub 等技能市场。同时支持纯命令行模式，可以在任何终端中运行。\n\n---\n\n## 🔍 报错速查\n\n| 报错 / 报告标记 | 原因 | 解决 |\n|------|------|------|\n| `❌ 路径不存在` | 目录拼错或已移动 | `ls <路径>` 确认目录存在 |\n| `❌ 目录为空` | 缺少 SKILL.md | 新建 SKILL.md（一行标题也行）再跑 |\n| `⚠️ 疑似外部 Skill` | `skills/` 下有别人安装的 Skill | 确认后修改运行配置文件中 `skills_is_external` |\n| `🔴 硬编码路径` | SKILL.md 或脚本里有绝对路径 | 全部改成相对路径 |\n| `🟠 模糊表述` | 说明书用了\"大概/可能/通常\"等词 | 换成明确的 if-else 条件句 |\n| `🔴 裸 except` | `except: pass` 吞掉了错误 | 至少 `except Exception as e: print(e)` |\n| `🟠 不存在文件引用` | 引用的脚本/文档实际不在文件夹里 | `ls` 确认文件存在，修正文件名 |\n| `🟠 覆盖薄弱` | 大部分步骤没有脚本兜底 | 把核心步骤写成 .py/.sh 脚本 |\n\n更详细的避坑指南见下方 [🚫 常见反模式](#-常见反模式不要做的事)。\n\n---\n\n## 使用场景\n\n**场景 1：发布前自审**\n\n你要把写好的 Skill 发布到 ClawHub / SkillHub，想确保它在别人机器上也能正常工作。\n\n跑一次全维度审查。重点看标准版报告的「地基」和「代码风险」——硬编码路径、裸 except、虚构命令是最高频的坑。改完后跑第二次验证分数提升。\n\n**场景 2：接手别人的 Skill**\n\n别人写的 Skill 文档很长，你不敢直接给 AI 执行，怕出问题。\n\n跑一次审查，直接看「行动版报告」——它把每个问题拆成「现状 → 风险 → 修复方案 → 验证方法」，照着改就行，不用通读原始 SKILL.md。\n\n**场景 3：CI 自动检查**\n\n你在维护 Skill 仓库，想每次改代码时自动检查质量不退化。\n\n```bash\npython3 -m halucatch --skill-dir . --validate    # 快速扫描文件清单\npython3 -m halucatch --skill-dir . --output-dir ./ci-reports  # 完整审查出报告\n```\n\n在 CI 里集成，每次 PR 确保分数不下降。\n\n---\n\n## 能力边界\n\n**能做什么：**\n- ✅ 扫描 SKILL.md 和关联 .py 文件，检查执行可靠性\n- ✅ 识别硬编码路径、裸异常处理、虚构命令等 7 类代码风险\n- ✅ 评估业务规则歧义和护栏完整度\n- ✅ 自动识别中英文，输出对应语言报告\n- ✅ 生成标准版/专业版/行动版三份报告\n\n**不能做什么：**\n- ❌ 不联网 —— 不访问任何 API，不下载文件\n- ❌ 不查安全漏洞 —— SQL 注入、XSS、恶意指令交给 ClawHub SkillSpector\n- ❌ 不批量处理 —— 一次一个目录\n- ❌ 不代替人工决策 —— 报告是建议，最终你拍板\n\n**硬性限制：**\n- 📏 单文件 > 10 MB 会被跳过并提示\n- 📁 不支持二进制文件\n- ⏱️ 处理时间取决于文件数量和大小，通常 1-60 秒\n\n---\n\n**Q: 我的 Skill 没有 .py 文件，能用吗？**\n\n可以。HaluCatch 会自动分类为「纯方法论型」并跳过地基/代码检查，只评估方法论结构和护栏完整度。\n\n---\n\n## 报告\n\n**Q: HaluCatch 会在电脑上写文件吗？**\n\n会。审查完成后自动在 `HaluCatch/reports/` 目录生成三份报告（标准版、专业版、行动版 .md 文件）。不会修改目标 Skill 目录中的任何文件。如需自定义输出路径，使用 `--output-dir` 参数。\n\n**Q: 审查结果长什么样？**\n\n标准版报告示例（白话、零术语，给非技术用户看）：\n\n```\n# HaluCatch 审计报告 — my-skill\n\n## 📌 一句话总结\n\n🟢 3 通过 · ⚠️ 2 注意 · 💡 3 可优化\n\n## 🎯 核心结论\n\n| 地基 | 代码 | 规则 | 护栏 | 复杂度 |\n|:--:|:--:|:--:|:--:|:--:|\n| 🟢 稳固 6/6 | 🟢 干净 90/90 | 🟡 有歧义 4/6 | 🟢 到位 11/11 | 🟡 注意 2.2/10 |\n\n### 做的不错 👍\n- ✅ 有固化脚本兜底核心任务\n\n### 需要注意的方面\n- ⚠️ 存在模糊表述 ['大概']（说明书写了模糊词，AI 可能会猜错）\n```\n\n包含专业版（11 项指标表 + KaTeX 公式）和行动版（修复清单）。完整示例：运行 `python3 halucatch_core.py --skill-dir .` 审自己的项目。\n\n---\n\n**Q: 审查结果说「护栏薄弱」，怎么修？**\n\n看同目录下的 `HaluCatch-report-日期-行动版.md`，它逐条列出了修复方案和验证检查点。按清单逐项改即可，改完后重新审查验证。\n\n---\n\n**Q: 为什么工具库型 Skill 的护栏分数看起来比分析型低？**\n\n护栏检查按类型分层——工具库型只查 5 项核心项（跳过数据来源/时效性/置信度），分析型查全 8 项。分母不同，分数不可直接比较。\n\n---\n\n**Q: 报告里看到的版本号是什么意思？**\n\n报告日期是生成当天，版本号跟随 HaluCatch 自身版本。同一个 Skill 在不同版本 HaluCatch 下的评分可能不同——因为检测规则在持续改进。\n\n---\n\n**Q: 能一次审查多个 Skill 吗？**\n\n当前版本暂不支持批量模式。你可以逐个运行。批量功能已在 roadmap 中。\n\n---\n\n## 技术\n\n**Q: 为什么有些 Skill 被分类为「代码工程型」而有些是「纯方法论型」？**\n\n含 .py 文件、或 SKILL.md 中嵌入了 `\\`\\`\\`python` 代码块、或引用了 pandas 等数据处理库的 Skill → 代码工程型（启用全四维评估）。其余 → 纯方法论型（只查方法论+护栏）。\n\n---\n\n**Q: 出现文件编码错误怎么办？**\n\nHaluCatch 会尝试以 UTF-8 读取所有文件。如果遇到非 UTF-8 编码（如 GBK），会用 `backslashreplace` 保留原始字节的转义形式，避免静默丢数据。\n\n---\n\n**Q: 代码风险检查有哪些规则？**\n\n当前 7 条通用规则：异常处理（裸 except: pass）、浮点比较（== 0.0）、除零风险（return 中无保护除法）、硬编码阈值（固定 skiprows）、路径拼接（字符串拼路径）、静默覆盖（open 写模式无警告）、超时缺失（requests 无 timeout）。\n\n---\n\n**Q: 行动版报告里的「Phase 4 闭环」是什么意思？**\n\n审查完成后，HaluCatch 会询问是否按方案修复。选择「执行修复」→ 将方案发给 AI 实施 → 修复后重新审查验证。选择「我有更好建议」→ 描述你的想法 → 重新生成方案。选「不执行」→ 结束。完整的「发现→修复→验证」链路。\n\n---\n\n## 🚫 常见反模式（不要做的事）\n\n提交 Skill 或使用 HaluCatch 前，先过一遍这些高发问题：\n\n### ⚠️ 致命反模式\n\n| 踩坑 | 后果 | 正确做法 |\n|------|------|--------|\n| 让 AI 看完 HaluCatch 报告就直接改代码 | AI 可能误解报告建议，添加有问题的修复 | 先人工审查每条建议，确认后再让 AI 执行 |\n| 只看评分不看详情 | 高分但细节全是烂摊子 | 逐条看 warn/fail，优先修 🔴 |\n| Skills/ 目录塞满别人的 Skill 后跑审查 | 别人代码的问题全算在你头上 | `config.yaml` 设 `skills_is_external: true` |\n\n### 地基（Foundation）\n\n| 踩坑 | 后果 | 怎么避 |\n|------|------|--------|\n| SKILL.md 里引用本地绝对路径（如 `/Users/me/project/`） | 换台机器就跑不了 | 全部用相对路径：`references/guide.md` 而非 `/home/me/guide.md` |\n| 引用的脚本/文档文件实际不存在 | AI 按不存在的东西执行，产生幻觉 | 跑审查前先 `ls` 确认每个被引用的文件都在 |\n| 明明有 Python 脚本但 SKILL.md 里没提 | HaluCatch 可能漏掉代码风险检查 | `SKILL.md` 里注明所有 Python 依赖和入口文件 |\n\n### 代码风险（Code）\n\n| 踩坑 | 后果 | 怎么避 |\n|------|------|--------|\n| `except Exception: pass` 或 `except: pass` | 出错静默吞掉，查 bug 如大海捞针 | 最少 `except Exception as e: print(e)` |\n| `open(filename, 'w')` 无保护 | 静默覆盖已有文件，数据丢失 | 改成 `'x'` 模式，或写入前检查 `os.path.exists()` |\n| `requests.get(url)` 没设 `timeout=` | 网络卡住时永久挂起 | 统一设 `timeout=30` |\n| 除法运算不检查分母是否为零 | 输入数据稍有异常就崩 | 所有除法前加 `if denominator == 0:` 分支 |\n\n### 规则（Rules）\n\n| 踩坑 | 后果 | 怎么避 |\n|------|------|--------|\n| 用模糊词（\"大概\"、\"可能\"、\"应该\"、\"或许\"） | AI 执行时自行脑补，输出不可复现 | 把模糊词换成明确的条件：\"当 A 为真时执行 B\" |\n| 指令只有正常路径，没有异常分支 | 出状况时 AI 不知道该怎么办 | 每条核心指令至少配一个\"如果失败了怎么办\" |\n| 引用了 Skill 不支持的虚构命令或功能 | AI 试图执行不存在的东西 | 写指令前确认所有命令在你的环境下真实可用 |\n\n### 护栏（Guardrails）\n\n| 踩坑 | 后果 | 怎么避 |\n|------|------|--------|\n| 没声明\"不要做什么\" | AI 可能在你不希望的场景下触发 Skill | 开头加一句：\"仅当用户明确请求 X 时激活，其他情况下忽略\" |\n| 输出格式没约束 | 同样的输入每次输出格式不一样 | 明确指定输出结构：JSON schema / Markdown 表格 / 固定模板 |\n| 引用了外部 API 但没声明密钥需求 | 用户装完发现跑不了 | `metadata.openclaw.requires.env` 里列出所有需要的环境变量 |\n\n---\n\n> **小技巧**：把这份清单当 checklist，跑 HaluCatch 之前先逐行过一遍——多数问题根本不会出现在报告里。\n\nFile v1.8.7:skill-card.md\n\n## Description: <br>\nEvaluates AI Skill execution reliability by checking trustworthiness, reproducibility, data-pipeline integrity, code risk, business-rule ambiguity, interpretation guardrails, and complexity. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[codermoray](https://clawhub.ai/user/codermoray) <br>\n\n### License/Terms of Use: <br>\nMIT <br>\n\n\n## Use Case: <br>\nDevelopers, AI skill authors, and reviewers use HaluCatch to audit a local Skill directory before deployment or sharing. It produces reliability findings and repair guidance for data pipelines, code risks, business rules, interpretation guardrails, and complexity. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The skill reads the full local Skill folder selected by the user. <br>\nMitigation: Confirm the normalized target path before running it, and avoid pointing it at home, system, or unrelated sensitive directories. <br>\nRisk: The skill writes local Markdown report files after scanning. <br>\nMitigation: Use an explicit output directory when report placement needs to be predictable or isolated from the target Skill directory. <br>\n\n\n## Reference(s): <br>\n- [ClawHub release page](https://clawhub.ai/codermoray/skills/halucatch) <br>\n- [Project homepage from ClawHub metadata](https://github.com/CoderMoray/HaluCatch) <br>\n- [Interactive HaluCatch documentation](https://codermoray.github.io/HaluCatch/) <br>\n- [HaluCatch decision flowchart](https://codermoray.github.io/HaluCatch/decision-flowchart.html) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [Text, Markdown, Shell commands, Guidance] <br>\n**Output Format:** [Markdown reports and conversational summaries with inline shell commands] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Runs offline against a user-selected local Skill directory, supports validate-only scanning, and writes three local Markdown reports under a reports directory unless an explicit output directory is provided.] <br>\n\n## Skill Version(s): <br>\n1.8.7 (source: SKILL.md frontmatter, manifest.json, CHANGELOG, release evidence) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v1.8.7:manifest.json\n\n{\n  \"name\": \"HaluCatch\",\n  \"version\": \"1.8.7\",\n  \"required_files\": [\n    \"halucatch/SKILL.md\",\n    \"halucatch/halucatch_core.py\",\n    \"halucatch/halucatch/\"\n  ],\n  \"skillhub_files\": [\n    \"halucatch/SKILL.md\",\n    \"halucatch/halucatch_core.py\",\n    \"halucatch/halucatch/\",\n    \"README.md\",\n    \"docs/CHANGELOG.md\",\n    \"halucatch/FAQ.md\"\n  ],\n  \"version_sync\": [\n    \"halucatch/SKILL.md\",\n    \"config.yaml\",\n    \"docs/index.html\"\n  ],\n  \"clawhub_exclude\": [\n    \"tests/\",\n    \"docs/\",\n    \"reports/\",\n    \"reports_zh/\",\n    \"scripts/\",\n    \"outputs/\",\n    \".workbuddy/\",\n    \".github/\",\n    \"__pycache__/\",\n    \"*.pyc\",\n    \"*.zip\"\n  ],\n  \"category\": \"engineering\",\n  \"language\": \"zh-CN\"\n}\n\nFile v1.8.7:LICENSE\n\nMIT License\n\nCopyright (c) 2026 CoderMoray\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\nArchive v1.8.6: 24 files, 72075 bytes\n\nFiles: CHANGELOG.md (12437b), FAQ.md (10826b), halucatch_core.py (642b), halucatch/__init__.py (77b), halucatch/__main__.py (104b), halucatch/classifier.py (702b), halucatch/cli.py (7697b), halucatch/config.py (12476b), halucatch/evaluators/__init__.py (506b), halucatch/evaluators/code_risks.py (15713b), halucatch/evaluators/complexity.py (23677b), halucatch/evaluators/foundation.py (2921b), halucatch/evaluators/guardrails.py (9749b), halucatch/evaluators/methodology.py (3044b), halucatch/evaluators/rules.py (3245b), halucatch/README.md (1992b), halucatch/reporter.py (19561b), halucatch/scanner.py (8426b), LICENSE (1067b), manifest.json (690b), README.md (12457b), skill-card.md (2479b), SKILL.md (21891b), _meta.json (128b)\n\nFile v1.8.6:SKILL.md\n\n---\nname: halucatch\ndescription: |\n  Evaluates the reliability of AI Skill execution. Assesses whether a Skill's output is trustworthy, reproducible, and withstands business scrutiny when executed by an AI agent. Covers four dimensions: data pipeline integrity, code risk, business logic ambiguity, and interpretation guardrails. Use when auditing an AI Skill, checking for hallucinations or unreliable outputs, verifying execution reproducibility, or reviewing a Skill's safety before deployment or sharing.\nsummary: AI Skill 执行可靠性审查工具。评估一个 Skill 被 AI 执行时，结果是否可信、是否可复现、是否经得起业务推敲。覆盖四维度：地基（数据管线）、代码、规则（业务口径）、护栏（解读指南）。\nlicense: MIT\nallowed-tools:\n  - Read\n  - Write\n  - Bash\ncompatibility: Requires Python 3.8+; Bash only for local 'python3 halucatch_core.py', no network/arbitrary commands\nauthor: CoderMoray\nversion: 1.8.6\nmetadata:\n  hermes:\n    tags:\n    - skill-audit\n    - reliability\n    - engineering-assurance\n    - Skill审查\n    - 工程质量\n    - 可靠性\n  openclaw:\n    requires:\n      bins:\n      - python3\n    emoji: 🔍\n    homepage: https://github.com/CoderMoray/HaluCatch\nslug: halucatch\ndisplayName: HaluCatch / 捕幻\ntags:\n  - skill-audit\n  - reliability\n  - engineering-assurance\n  - Skill审查\n  - 工程质量\n  - 可靠性\n---\n> **一句话总结**：把一个 AI Skill 的文件夹扔给 HaluCatch，它会逐项检查数据管线、代码逻辑、业务规则、安全护栏有没有漏洞，然后给你三份报告（标准版看全貌、专业版看细节、行动版直接修），全程几秒钟、完全离线。\n>\n> [快速开始](#1-入口逻辑) · [能力边界](#能力边界) · [输出解读](#5-报告)\n\n# HaluCatch / 捕幻 — AI Skill 执行可靠性审查\n\n评估一个 Skill 包在 AI 执行时的可靠性，产出评估报告和修复建议（建议需用户确认后才执行，不自动修改目标 Skill）。\n\n---\n\n## 能力边界\n\n| 擅长 | 不擅长 |\n|------|--------|\n| 评估 AI 执行 skill 时会否出错 | 网络安全审查（SQL 注入、XSS 等） |\n| 检查数据管道是否可靠 | 合规性审查（GDPR、隐私法规等） |\n| 发现自然语言业务规则的歧义 | Skill 本身的业务正确性（不懂业务逻辑） |\n| 检查解读护栏是否到位 | 代码性能优化 |\n| 输出修复建议和骨架脚本 | 替换人工业务决策 |\n\n**硬件限制：** 单文件上限 10 MB（超大文件会被跳过并提示），不支持批量审查（一次一个目录），不支持二进制文件，不建立网络连接（仅通过本地 Python 脚本运行）。审查耗时取决于目录下文件数量和大小，通常几秒到几十秒。\n\n---\n\n## 角色\n\n当用户调用 HaluCatch 时，**你就是 HaluCatch 审查执行者**，而非旁观者。\n\n### 职责\n\n- 调用 `halucatch_core.py` **一次性完成全流程**（L1 扫描 + L2 评估 + L3 报告生成）\n- 读取脚本生成的报告文件，对话中展示标准版，询问是否修复\n- 在脚本报告基础上做语义补充：按需读取报告中引用的源文件，提供上下文分析（`info` 级别条目）\n- **不要自己读取目标目录的文件**——文件扫描由脚本完成，AI 读取只会浪费 token\n\n### 你与 halucatch_core.py 的分工\n\n| 层级 | 任务 | 执行方 | 原则 |\n|------|------|--------|------|\n| **L1** | 文件扫描 | `halucatch_core.py --validate` | 确定性高，脚本更快更准 |\n| **L2** | 地基 + 代码 + 规则 + 护栏检查 | 脚本取 JSON 基线 → **你在此基础上补充分析** | 正则匹配靠脚本，上下文解读靠你 |\n| **L3** | 三版报告生成 | `halucatch_core.py` **生成并落盘**，你读取后展示给用户 | `reporter.py` 确定性高、格式一致、零幻觉——你只需做语义补充 |\n\n> **核心原则**：`halucatch_core.py` 涵盖全流程——L1 扫描、L2 评估、L3 报告生成一次性完成。你只需读取脚本生成的报告并展示给用户。不再由 AI 独立编写报告正文。\n\n## 权限与安全边界\n\n**⚠️ 写入警告：HaluCatch 会生成报告文件写入目标目录的 `reports/` 子目录，并可能产出修复指引（需用户确认后才应用）。这不是纯只读工具。**\n\nHaluCatch 仅需要以下权限即可运行：\n\n| 操作 | 需要 | 说明 |\n|------|------|------|\n| 读取目标 Skill 目录 | Read | 递归读取全部文件 |\n| 写入报告文件 | Write | 仅写入目标目录内的 `reports/` 子目录，不修改 Skill 源文件 |\n| 执行 Python 脚本 | Bash | 仅执行本地 `halucatch_core.py`，不访问网络、不执行外部命令 |\n\n**安全约束**：HaluCatch 不会访问目标目录以外的任何路径，不会发起网络连接。Bash 权限仅用于运行自带的 Python 审查脚本，不会执行非本项目代码。审查前必须由用户显式指定目标路径。\n\n---\n\n## 输入\n\n用户提供一个 Skill 文件夹路径。该文件夹可能包含：\n\n| 文件类型 | 是否必需 | 说明 |\n|---------|---------|------|\n| `SKILL.md` | ✅ | Skill 的主指令文件 |\n| `manifest.json` 或 `config.yaml` | ❌ | Skill 配置文件（含版本号等） |\n| `*.py` | ❌ | 数据管线的固化脚本（如有） |\n| `*.xlsx / *.csv` 等 | ❌ | 数据文件（如有，用于验证对账） |\n\n### 数据要求\n\n- **时效性**：审查基于目标 Skill 目录的即时快照，不追溯历史版本。\n- **数据范围**：仅评估目标目录中可见的文件，不爬取外部依赖或网络资源。\n\n### 前提假设\n\n- 目标目录存在且有读取权限。\n- 目标 Skill 应包含至少一个 `SKILL.md` 文件（规范名称）。如有其他 `.md` 文件，AI 将尝试启发式匹配，但会报告规范性问题。\n- 目录中的 `.py` 文件视为 Skill 核心执行脚本，非第三方依赖库。\n\n### 触发条件\n\n仅在用户**显式请求审查 Skill** 时激活。以下为有效触发方式：\n\n- 使用精确命令：`审查 /path/to/skill`、`用 HaluCatch 检查 ./my-skill`\n- 提供明确路径或 Skill 文件夹引用\n- **不作为通用问答助手**：仅在用户主动要求审查时激活，不会对任意文本或对话自动触发评估\n\n---\n\n## AI 执行指南\n\n### 语言自动检测\n\nAI 在加载本 Skill 时，应从系统提示（`<response_language>`）或对话上下文判断用户语言，然后自动添加 `--lang` 参数：\n\n| 用户语言 | 参数 | 示例 |\n|-----------|------|------|\n| 中文（简体/繁体） | `--lang zh-CN` | `python3 halucatch_core.py --skill-dir <path> --lang zh-CN` |\n| 英文 | `--lang en` | `python3 halucatch_core.py --skill-dir <path> --lang en` |\n| 不确定 | 不添加（默认 `auto`，自动检测系统 locale） | `python3 halucatch_core.py --skill-dir <path>` |\n\n**原则**：AI 肯定知道用户用什么语言，不需要用户手动配置。\n\n### 基本用法\n\n```bash\n# 为中文用户审查\npython3 halucatch_core.py --skill-dir /path/to/skill --lang zh-CN\n\n# 为英文用户审查\npython3 halucatch_core.py --skill-dir /path/to/skill --lang en\n\n# 自动检测（fallback）\npython3 halucatch_core.py --skill-dir /path/to/skill\n```\n\n---\n\n## 执行流程\n\n> **执行范式**：各 Phase 按三层调用模型分配职责。`halucatch_core.py` 一次性完成 L1/L2/L3，你读取生成的报告文件并展示给用户。\n\n### Phase 0：技能分类\n\n首先判断这个 Skill 的类型：\n\n```\n这个 Skill 涉及数据处理吗？\n  ├─ ❌ 纯方法论型（指令/模板/文档类）\n  │    评估重点：指令完备性、逻辑自洽、可复现性\n  │\n  ├─ ✅ 代码工程型（含 .py / 数据文件 / md 内嵌代码）\n  │    评估重点：地基 + 代码 + 规则 + 护栏\n  │\n  └─ ⚠️ 不确定\n        → 询问用户：「这个 Skill 有数据处理步骤吗？」\n```\n\n如果文件夹中存在 `.xlsx`、`.csv`、`.py`（含 `pd.read_`、`pd.DataFrame`）等文件或内容，默认按「代码工程型」处理。\n\n### Phase 1：文件扫描\n\n读取文件夹中的全部文件并构建清单：\n\n| 信息点 | 输出形式 |\n|--------|---------|\n| 文件名列表 | 表格（文件名/大小/类型） |\n| SKILL.md 总行数 | 数字 |\n| .py 文件行数（如有） | 数字 |\n| 数据文件列表 | 表格 |\n| Skill 名称和描述 | 从 frontmatter 提取 |\n\n### Phase 2：多维评估\n\n根据 Phase 0 的分类执行对应的评估维度的检查。\n\n---\n\n### 2a. 代码工程型 Skill 评估\n\n#### 🏗️ 地基评估\n\n检查 Skill 的数据管线是否稳固。地基越弱，AI 自主写代码出错的概率越高。\n\n| 检查项 | 通过标准 |\n|--------|---------|\n| 有固化 .py 脚本 | 脚本存在于文件夹中 |\n| 路径参数化 | 硬编码路径数 = 0 |\n| 列名预检/输入验证 | 有 `check_columns` 或类似函数 |\n| validate 模式 | 有 `--validate` 或类似模式 |\n| 文件发现机制 | 使用 glob/通配符而非固定文件名 |\n| 依赖声明 | 在 SKILL.md 中声明了所需的 Python 包 |\n| skiprows 参数化 | Excel 读取行数可配置或自动检测 |\n\n**评级**：🟢 稳固 / 🟡 有隐患 / 🔴 无地基\n\n---\n\n#### 🤖 代码风险评估\n\n如果 SKILL.md 中嵌入了 Python 代码（AI 须逐字复现），检查以下篡改点：\n\n| 检查类别 | 高风险模式 | AI 可能误改的行为 |\n|---------|-----------|----------------|\n| 统计函数 | 自定义 p-value 公式、Z-score 计算 | 替换为 `scipy.stats` / 调整常数 |\n| 字符串匹配 | `clean_rate()` 中解析百分比 | 替换 `replace('%','')` 为不同写法 |\n| 浮点比较 | `== 0` / `== 1` | 改为 `math.isclose()`（语义不同） |\n| 异常处理 | 裸 `except: pass` | 改为具体异常类型 |\n| 条件逻辑 | `(条件).sum() > 0` | 改为 `.any(axis=1)`（行为不同） |\n| 聚合逻辑 | `unstack(fill_value=0)` | 移除 `fill_value`（NaN 传播） |\n| 数据清洗 | 无数据类型转换指令 | 可能对字符串列做 `sum()` 报错 |\n\n**评级**：🟢 低风险 / 🟠 有风险 / 🔴 高风险\n\n---\n\n#### 📝 规则与口径评估\n\n检查业务规则在 SKILL.md 中的描述是否明确、无歧义：\n\n| 检查项 | 风险 |\n|--------|------|\n| 渠道/分类口径是否明确列举 | 歧义 → AI 自行猜测 |\n| 异常值/边界条件是否定义 | 遗漏 → AI 自行处理 |\n| 代际/映射关系是否固化（而非依赖 AI 知识） | 未固化 → 不同 AI 产出不同结果 |\n| 同店/同比等对比口径是否定义 | 未定义 → AI 自行决定，不可审计 |\n| 特殊纠偏规则（如海南聚时）是否文档化 | 未文档化 → 遗漏关键业务逻辑 |\n| 文件名/列名/数据格式是否约定 | 未约定 → 跑不通 |\n\n**评级**：🟢 清晰 / 🟡 有歧义 / 🔴 重大遗漏\n\n---\n\n#### 🛡️ 解读护栏评估\n\n检查 SKILL.md 是否约束 AI 对结果的解读方式：\n\n| 检查项 | 严重度 |\n|--------|--------|\n| 有因果语言禁令 | 缺失 → 🔴 严重 |\n| 有四象限/效应量框架 | 缺失 → 🟠 高 |\n| 有自检机制（self-check） | 缺失 → 🟠 高 |\n| 有多重比较提醒 | 缺失 → 🟠 高 |\n| 有限制性声明模板 | 缺失 → 🟠 高 |\n| 有阶段性状态输出 | 缺失 → 🟡 中 |\n| 有数据概要统计打印 | 缺失 → 🟡 中 |\n| 有输出格式定义 | 缺失 → 🟡 中 |\n\n**评级**：🟢 完善 / 🟡 缺项 / 🔴 无护栏\n\n---\n\n### 2b. 纯方法论型 Skill 评估\n\n| 检查项 | 说明 |\n|--------|------|\n| 指令完备性 | 每个步骤都有明确的输入/输出/判断条件 |\n| 边界情况 | 是否有「如果…则…」的异常分支处理 |\n| 可复现性 | 不同 AI 执行是否会得到一致的结论 |\n| 示例驱动 | 是否包含具体示例来说明期望输出 |\n| 输出格式定义 | AI 的输出结构是否被约束 |\n| 自我验证 | Skill 执行结果能否自洽检查 |\n\n**评级**：🟢 可靠 / 🟡 有改进空间 / 🔴 不可靠\n\n---\n\n> ⚠️ **执行前确认**：在开始扫描文件、运行 `halucatch_core.py`、或生成报告之前，必须先向用户确认目标路径无误，并告知即将执行的操作（读取目标目录文件、运行本地脚本、生成报告到 reports/ 目录）。未明确确认前不得执行任何读写操作。\n\n### Phase 3：三版输出\n\n**核心变更**：报告由 `halucatch_core.py`（`reporter.py`）自动生成，你**不再需要独立撰写报告正文**。你只负责：\n1. 读取脚本生成的报告文件\n2. 对话中展示标准版\n3. 在已生成的报告基础上做补充语义分析（关联 `info` 级别条目）\n\n**输出决策规则**：三版报告**始终由脚本生成并存盘**，对话中只展示标准版。\n\n1. 运行 `halucatch_core.py --skill-dir <路径>` → 脚本自动完成 L1 扫描 + L2 评估 + L3 报告生成\n2. 三份 `.md` 文件写入 `reports/` 目录（或 `--output-dir` 指定路径）\n3. 对话中只输出**标准版**（白话、零术语）\n4. 标准版末尾附带提示：「需要看技术细节（专业版）或修复方案（行动版）吗？」\n5. 如果用户说「要」→ 对话中展示对应版本内容（文件已在磁盘上，直接读取展示）\n6. 如果用户没回应 → 不主动输出，不造成信息过载\n\n#### 1. 专业版（给数据分析师/工程人员）\n\n由 `reporter.py` 自动生成，包含 TL;DR 摘要、四维评级矩阵表、逐维度发现清单、检查声明。\n\n#### 2. 标准版（给业务方/非技术人员）\n\n由 `reporter.py` 自动生成，包含白话摘要、21 条语境解释映射、无术语输出。\n\n#### 3. AI 行动版（供给修复阶段使用）\n\n由 `reporter.py` 自动生成，包含修复清单、验证检查点、三选一步骤提示。\n\n#### 报告检查声明\n\n所有三版报告末尾必须包含检查行：\n\n```markdown\n> 本报告由 HaluCatch 生成。检查进度: [✅ HaluCatch 四维评估全部执行完毕 / ⚠️ 部分评估维度未完成]。\n```\n\n如果评估过程中有维度未覆盖（如代码工程型 Skill 但用户未提供 .py 文件），检查等级降为 ⚠️。\n\n#### AI 语义补充（在脚本报告基础上）\n\n读取脚本生成的报告后，逐条审查发现，按严重度从高到低做上下文分析：\n\n| 原评级 | AI 需要判断 |\n|--------|-----------|\n| 🔴 阻塞 | 这条风险在实际业务中到底多严重？是否真的会导致执行失败？修复优先级？ |\n| 🟠 高危 | 上下文是否真的构成风险？有没有脚本误报的可能？修复方案是否需要细化？ |\n| 🟡 提示 | 跳过项是否真的合理？有没有脚本漏掉但实际重要的风险？ |\n| 🟢 通过 | ✅ 脚本判断正确，无需补充 |\n\n输出格式：在每个发现条目下方追加一行 `> **AI 分析**: [具体判断]`。\n\n#### 报告审查前检查\n\n报告生成后、向用户展示或提交前，**必须**先检查标准版报告中是否存在 `⚠️ 疑似外部 Skill` 标记。\n\n**如存在**：不做 `present_files`，直接向用户确认：\n\n> ⚠️ 发现疑似外部 Skill 目录。`skills/` 是外部安装的 Skill（非本项目代码）吗？\n\n- 用户「是」→ 修改 HaluCatch 自身的运行配置文件（`skills_is_external: true`），重跑审查（不改目标 Skill 文件）\n- 用户「否」→ 同上，设 `skills_is_external: false`\n- 用户无法判断 → 保持 `null`，标注保留，继续展示\n\n确认完成并重跑后，进入 Phase 4。\n\n---\n\n### Phase 4：修复决策与闭环\n\n评估完成后，向用户展示标准版报告并询问：\n\n> 检测到 [N] 项风险。是否按建议方案修复？\n\n- **用户「修」** → 生成修复方案，然后展示三选一：\n\n  > 修复方案已生成。请选择：\n  > 1. **执行修复** — 将修复方案发给你的 AI，让它按方案修改目标 Skill\n  > 2. **不执行** — 不做任何修改，结束本次审查\n  > 3. **我有更好的意见** — 描述你的想法，我据此重新生成修复方案\n\n  - 用户选「执行」→ 提示用户让 AI 应用修复 → 提示修复后重新运行 HaluCatch 验证\n  - 用户选「不执行」→ 结束\n  - 用户选「建议」→ 重新分析追加需求 → 回到「生成修复方案」\n\n- **用户「不修」** → 结束\n\n---\n\n## 报告落盘\n\n- 缺省输出到 `reports/` 目录（目标 Skill 目录内，不污染外部路径）\n- 指定 `--output-dir` 则输出到自定义路径\n- 修复包（如有）保存到：`{Skill目录}/halucatch-fix/`\n\n---\n\n## 更多触发示例\n\n### 按审查深度\n\n| 用户说 | AI 执行动作 |\n|--------|-----------|\n| 「帮我审一下这个 Skill，看看靠不靠谱」 | 完整流程：分类 → 四维评估 → 三版报告 |\n| 「快速扫一眼，有没有明显的坑」 | 仅做 Phase 1 扫描 + Phase 2 L1/L2 规则检查，输出一份精简 checklist |\n| 「这次只关注代码有没有除零/裸 except 这种硬伤」 | 跳过规则和护栏维度，只跑地基 + 代码检查 |\n| 「上次审查后我改了 SKILL.md，帮我再跑一遍对比一下」 | 重新审查，对比上次报告，标注修复状态 |\n\n### 按 Skill 类型\n\n| 用户说 | AI 执行动作 |\n|--------|-----------|\n| 「我的 Skill 里有个 data/ 文件夹和 .py 脚本，帮我全面审」 | 分类为代码工程型，四维全覆盖 |\n| 「这是一个纯指引文档类 Skill，帮我看看指令写得清楚不清楚」 | 分类为纯方法论型，仅评估方法论和护栏 |\n\n### 路径写法（不同平台差异）\n\n| 平台 | 正确写法 | ❌ 错误写法 |\n|------|---------|-----------|\n| Claude Code / 通用 | `/path/to/skill` | `C:\\\\path\\\\to\\\\skill` |\n| Kimi / 微信小程序 | `skills/项目名/` | `~/skills/项目名/` |\n| Cursor / VS Code | 拖拽文件夹到对话框 | 手动输入复杂路径 |\n\n### 如果还是不会用\n\n> 直接说：「审查 /path/to/skill」，把 Skill 文件夹拖进来即可。AI 会自行判断接下来的步骤。不要直接贴 SKILL.md 内容——用文件夹路径保证完整性。\n\n---\n\n## 异常处理\n\n### 常见错误及修复\n\n| 错误现象 | 原因 | 修复方法 |\n|---------|------|---------|\n| `❌ 找不到 SKILL.md` | 目标目录不存在或没有 .md 文件 | 确认路径正确 → 检查目录是否有 `SKILL.md` 或其他 `.md` 文件 → 如无，创建一个 |\n| `⚠️ 未找到标准 SKILL.md` | 文件名不是 `SKILL.md`（如 `skill.md`、`README.md`） | 将文件重命名为 `SKILL.md`，或告知 AI 用 `--file` 指定文件名 |\n| `🔧 文件编码异常，已跳过 XXX.py` | 文件包含非 UTF-8 字符（如 GBK 编码的中文注释） | 用编辑器将文件另存为 UTF-8 编码（编码转换不改变内容，仅调整存储方式） |\n| `📦 Skill 包过大（> 2MB）` | 目录包含大量数据文件或依赖包 | 仅保留核心文件（SKILL.md + .py 脚本），数据文件和依赖放入 `.halucatch-ignore` |\n| `⏱️ 审查超时` | 文件过多或脚本执行时间过长 | 告知 AI：「只审查 SKILL.md 和核心 .py 文件」 |\n\n### 错误分级\n\n| 级别 | 行为 |\n|------|------|\n| **致命**（如目录不存在） | 立即终止，提供明确的修复指引 |\n| **警告**（如非标准文件名） | 继续审查但降级自检评分，在报告中标注 |\n| **可恢复**（如单个文件编码问题） | 跳过该文件继续，在报告中标注被跳过的文件及原因 |\n\n---\n\n## 运行稳定性\n\n### 防护措施\n\n| 场景 | 保护策略 |\n|------|---------|\n| 大文件（单个 > 1MB） | 截取前 500 行进行分析，在报告中声明截断 |\n| 大量文件（目录 > 200 个文件） | 按类型筛选（.md → .py → 其他），非核心文件自动跳过 |\n| 脚本执行超时（> 30s） | 终止该步骤，将已验证的部分写入报告，标注未完成项 |\n| 网络请求 | Halucatch **不发起网络请求**，100% 离线运行 |\n| 编码问题 | 先尝试 UTF-8 → 再尝试系统 locale → 失败则跳过并记录 |\n| 目录不可读 | 报告权限错误，建议用户 `chmod` 或换个路径 |\n\n### 可靠性声明\n\n> Halucatch 在正常 Skill 目录（≤ 50 个文件，单文件 ≤ 1MB）上运行稳定。极端情况会自动降级（截断/跳过/终止），不会静默失败。\n\n---\n\n## 反模式与 FAQ\n\n### 常见误区\n\n| 误区 | 正确认知 |\n|------|---------|\n| 「审查一次就够了」 | Skill 每次修改后都应重新审查，尤其是修改 SKILL.md 或关键 .py 文件后 |\n| 「分数低 = 不能用」 | 分数是相对参考。一个「地基弱但规则清晰」的纯方法论型 Skill 可能完全可用 |\n| 「修完所有问题才发布」 | 优先修高优（🔴）和中优（🟠）项，低优项可以渐进改进 |\n| 「AI 行动版报告可以直接执行」 | 行动版是给 AI 的修复指令，需用户确认后再让 AI 执行，防止误改 |\n| 「用 `--validate` 模式跑过就算审查了」 | `--validate` 只做文件扫描和类型分类，不做四维评估。正式审查必须完整跑 |\n\n### FAQ\n\n**Q：我需要准备什么？**\nA：一个包含 `SKILL.md` 的文件夹。如果有 `.py` 脚本或数据文件，一并放入可以评估得更全面。\n\n**Q：审查结果说不通过，我该怎么办？**\nA：看报告中的「AI 行动版」，里面有逐项修复方案。按优先级从高到低修，修完再审查一次验证。\n\n**Q：我的 Skill 没有 Python 代码，能用吗？**\nA：能。HaluCatch 会自动分类为「纯方法论型」，跳过地基和代码检查，重点评估指令完备性和护栏。\n\n**Q：遇到报错怎么办？**\nA：看上方「异常处理」章节。90% 的报错是路径写错或文件名不规范。如果解决不了，把报错信息贴给 AI。\n\n> 💡 **更多问题？** 查看 `FAQ.md`——包含完整的使用指南、常见问题和故障排除。\n\nFile v1.8.6:halucatch/README.md\n\nHaluCatch 模块化拆分 — 设计决策说明\n\n## 目录结构\n\nhalucatch/                    # 核心包\n├── __init__.py               # 导出版本和核心 API（~15 行）\n├── config.py                 # MESSAGES + detect_system_locale（~218 行）\n├── scanner.py                # scan_folder + _extract_version + _strip_string_literals（~166 行）\n├── classifier.py             # classify_skill（~16 行）\n├── evaluators/               # 四维评估 + 自检\n│   ├── __init__.py           # 聚合导出（~30 行）\n│   ├── foundation.py         # check_foundation（~72 行）\n│   ├── code_risks.py         # check_code_risks（~56 行）\n│   ├── rules.py              # check_rules（~85 行）\n│   ├── guardrails.py         # check_guardrails（~133 行）\n│   └── methodology.py        # check_methodology（~66 行）\n├── reporter.py               # generate_report（~262 行）\n├── cli.py                    # parse_args + main（~88 行）\nhalucatch_core.py             # 向后兼容入口（~30 行，导入 cli.main）\n\n## 设计原则\n\n1. **零依赖**：所有模块仅使用 Python 标准库，不引入外部包。\n2. **单一职责**：每个模块对应一个功能边界，模块内高内聚。\n3. **AI 可复现**：单文件控制在 200 行以内，AI 可以完整理解每个模块。\n4. **向后兼容**：halucatch_core.py 保留，所有现有用法不受影响。\n5. **可扩展**：新增评估维度时，只需在 evaluators/ 下新建文件，evaluators/__init__.py 注册即可。\n\n## 依赖关系\n\n```\ncli.py → reporter.py → evaluators/__init__.py → config.py\n             ↑                        ↑\n          scanner.py               classifier.py\n```\n\n所有模块都依赖 config.py（MESSAGES）。\nscanner.py 和 classifier.py 无依赖。\nreporter.py 依赖所有 evaluators 和 scanner 输出。\ncli.py 是入口，协调所有模块。\n\nFile v1.8.6:README.md\n\n# HaluCatch / 捕幻\n\n<p align=\"center\">\n  <a href=\"README.md\">\n    <img src=\"https://img.shields.io/badge/语言-中文-blue?style=for-the-badge\" alt=\"中文\">\n  </a>\n  <a href=\"README.en.md\">\n    <img src=\"https://img.shields.io/badge/Language-English-slategray?style=for-the-badge\" alt=\"English\">\n  </a>\n</p>\n\nAI Skill **执行可靠性审查**工具。评估一个 Skill 被 AI 执行时，结果是否可信、是否可复现、是否经得起业务推敲。\n\n> **Halu** = Hallucination（幻觉） | **Catch** = 捕获\n\n🌐 **在线站点**：[codermoray.github.io/HaluCatch](https://codermoray.github.io/HaluCatch/) — 交互式流程图、FAQ、版本更新一览。\n\n---\n\n## 动机\n\nAI 执行 Skill 时，最常见的问题不是「不会做」，而是**以为自己会做但做错了**。原因有三：\n\n1. **地基不稳** — 数据路径写死、格式未验证、没有骨架脚本\n2. **规则歧义** — 自然语言描述的业务逻辑能被多种理解\n3. **缺解读护栏** — AI 产出自信的错误结论，用户无从分辨\n\nHaluCatch 扫描一个 Skill 包，从地基/代码/规则/护栏四维度给出评级与修复建议。\n\n---\n\n## 执行流程\n\n> 完整流程见 [在线流程图](https://codermoray.github.io/HaluCatch/decision-flowchart.html)。\n\n---\n\n## 快速开始\n\n两种调用方式，底层同一套引擎：\n\n### 对话中调用（推荐）\n\n对 AI 说出目标 Skill 路径即可，AI 自动跑脚本、做评估、出报告：\n\n```\n请用 HaluCatch 审查这个 Skill：/path/to/target-skill\n```\n\n审查完成后，当前目录 `reports/` 下生成三份报告：\n\n```\nreports/\n├── HaluCatch-report-2026-06-17.md           ← 专业版（工程人员）\n├── HaluCatch-report-2026-06-17-标准版.md      ← 标准版（业务方）\n└── HaluCatch-report-2026-06-17-行动版.md      ← 修复指引\n```\n\n| 版本 | 目标读者 | 内容 |\n|------|---------|------|\n| 专业版 | 工程人员 | 逐项检查结果 + 分数 + 修复建议 |\n| 标准版 | 业务方 | 白话 paraphrase，无术语 |\n| 行动版 | 下次执行的 AI | 修复指引 + 验证检查点 |\n\n**示例 — 审查一个代码工程型 Skill：**\n\n```\n请用 HaluCatch 审查 ~/.workbuddy/skills/xlsx，看这个操作表格的 Skill 稳不稳\n```\n→ 发现：字符串拼接路径、写入模式未警告覆盖、除法未保护。评级：地基 🟢 稳固，代码 🟠 有风险，护栏 🟡 缺项。\n\n**示例 — 审查一个纯方法论型 Skill：**\n\n```\n请用 HaluCatch 审查 ~/.workbuddy/skills/find-skills，看指令够不够清楚\n```\n→ 发现：结构化步骤完整、条件分支信号良好（清单 13 项/图标 7）。评级：方法论 🟢 可靠，护栏 🟡 缺项 3/5。\n\n> `find-skills` 是 Skill 生态中的搜索工具，详见 [vercel-labs/skills](https://github.com/vercel-labs/skills)。\n\n审查完成后 AI 会询问是否按方案修复，详见 [在线流程图](https://codermoray.github.io/HaluCatch/decision-flowchart.html)。\n\n---\n\n## 文件结构\n\n```\nHaluCatch/\n├── SKILL.md                  ← 流程指令（AI 读）\n├── halucatch_core.py         ← 向后兼容入口（14 行，导入 halucatch 包）\n├── halucatch/                ← 核心包（11 个模块，零依赖）\n│   ├── __init__.py\n│   ├── config.py             ← MESSAGES 双语字典 + 语言检测\n│   ├── scanner.py            ← 文件扫描 + 版本号提取\n│   ├── classifier.py         ← Skill 类型判定\n│   ├── evaluators/           ← 四维评估 + 方法论\n│   │   ├── __init__.py\n│   │   ├── foundation.py     ← 地基评估（路径/校验/依赖）\n│   │   ├── code_risks.py     ← 代码风险扫描（篡改点）\n│   │   ├── rules.py          ← 规则评估（口径/边界/模糊）\n│   │   ├── guardrails.py     ← 护栏评估（安全/禁止/误用）\n│   │   └── methodology.py    ← 方法论评估（步骤/分支/错误处理）\n│   ├── reporter.py           ← 三版报告生成器\n│   └── cli.py                ← 命令行入口 + 流程协调\n├── README.md                 ← 项目说明\n├── scripts/                  ← 发布/构建脚本\n│   ├── release.sh            ← 一键发布（8 步自动流程）\n│   ├── build-skillhub.sh     ← SkillHub 包构建\n│   ├── generate-changelog.sh ← 自动生成 CHANGELOG\n│   └── bump-version.sh       ← 版本号升级\n├── docs/\n│   ├── CHANGELOG.md\n│   ├── FAQ.md\n│   ├── decision-flowchart.html\n│   └── decision-flowchart-prompt.md\n├── tests/\n│   ├── __init__.py\n│   └── test_halucatch.py     ← 24 个单元测试\n├── cliff.toml                ← git-cliff Changelog 配置\n└── .gitignore\n```\n\n---\n\n## 多语言支持\n\nHaluCatch 支持中文（简/繁）和英文输出，根据用户语言自动切换：\n\n```bash\n# 自动检测（默认，推荐）\npython3 halucatch_core.py --skill-dir /path/to/skill\n\n# 强制中文输出\npython3 halucatch_core.py --skill-dir /path/to/skill --lang zh-CN\n\n# 强制英文输出\npython3 halucatch_core.py --skill-dir /path/to/skill --lang en\n```\n\n**AI 使用场景**：AI 从 `<response_language>` 判断用户语言，自动传 `--lang` 参数，无需用户手动配置。详见 [SKILL.md](SKILL.md) 中的「AI 执行指南」。\n\n---\n\n## 四维评估框架\n\n| 维度 | 检查什么 | 类型 |\n|------|---------|------|\n| 🏗️ **地基** | 数据管线是否稳固（.py/路径/validate） | 代码化扫描 |\n| 🤖 **代码** | 代码质量风险（路径拼接/静默覆盖/超时缺失/除零等） | 代码化扫描 |\n| 📝 **规则** | 业务口径有无歧义（映射/分类/边界） | AI 判断 |\n| 🛡️ **护栏** | 解读规则是否到位（禁令/框架/自检） | AI 判断 |\n\n前三项可靠，第四项需要目标 Skill 作者自觉配合。\n\n> **跨语言设计**: 方法论和护栏检查不使用关键词正则，而是通过结构信号密度\n> （条件清单行数、警示图标数、表格数、否定词密度）跨语言评估分支覆盖和护栏完整度。\n> 中文「如果…则…」和英文「REJECT IMMEDIATELY IF」都能正确识别。\n\n> **分层策略**: 代码工程型 Skill 细分为三档——分析型（全 8 项护栏，含数据来源/时效性/置信度）、工具库型（精简 5 项）、纯方法论型（精简 5 项）。避免对 xlsx/pptx 等工具库 Skill 检查不必要的「数据时效性/来源」项。\n\n---\n\n## 同类项目对比\n\nSkill 审查赛道目前仅四个工具，各自切不同的角度：\n\n| | HaluCatch | skill-vetter | SkillGuard | skill-sharpener |\n|---|---|---|---|---|\n| 切面 | **执行可靠性（工程）** | 安全审查（红队） | 全生命周期守护 | 文案质量（最佳实践） |\n| 检查什么 | 数据管线/代码风险/业务规则/解读护栏 | 恶意行为/权限范围/源可信度 | 安装前审查+发布前安检+安装后体检 | 触发描述/结构/简洁度 |\n| 评估方式 | 脚本基线 + AI 语义 | 纯 AI 按协议逐项检查 | AI + 规则引擎 | 纯 AI 按 checklist 打分 |\n| 输出 | 三版报告 + 修复方案 + 闭环 | SAFE/CAUTION/REJECT 判定 | 风险报告 + 自动修复 | 优化建议报告 |\n| 通用性 | ✅ 中/英/日/表格均适用 | ✅ 英文为主 | ✅ 中英文 | 🟡 依赖 AI 理解能力 |\n| 闭环 | ✅ 行动版含修复指引 + 验证检查点 | ❌ | ✅ 含自动修复 | ❌ |\n| skills.sh | — | **19.6K** | ❌ 未上榜 | ❌ 未上榜 |\n| 平台评分 | — | ★3.690 (clawhub) | v4.2.0 (skillhub) | ★3.607 (clawhub) |\n\n**HaluCatch 的独特优势**：\n1. **唯一有骨架脚本的工具** — `halucatch_core.py` 提供可复现的基线检查，不依赖 AI 主观判断\n2. **唯一含修复闭环** — 三版报告 + Phase 4 修复决策 + 验证检查点，形成「发现→修复→验证」完整链路\n3. **唯一跨语言** — 结构信号（清单/图标/表格/否定词密度）替代语义关键词，不绑定特定语言\n4. **唯一分层护栏** — 按 Skill 类型（分析型/工具库型/方法论）自动调整检查范围，避免误报\n5. **赛道蓝海** — skills.sh 前 287 名中，Skill 审查工具仅 skill-vetter 上榜（19.6K），执行可靠性方向尚无竞品\n\n---\n\n## 开发\n\n```bash\ngit clone https://github.com/CoderMoray/HaluCatch.git\ncd HaluCatch\n# 编辑 SKILL.md 或 halucatch_core.py\ngit commit -m \"your change\"\ngit push\n```\n\n### 引擎调试\n\n`halucatch_core.py` 是向后兼容入口，实际逻辑在 `halucatch/` 包中：\n\n```bash\n# 向后兼容入口\npython3 halucatch_core.py --skill-dir /path/to/skill               # 完整评估（自动检测语言）\npython3 halucatch_core.py --skill-dir /path/to/skill --validate    # 仅扫描\npython3 halucatch_core.py --skill-dir /path/to/skill --lang en     # 强制英文输出\n\n# 包方式（等价）\npython3 -m halucatch --skill-dir /path/to/skill\n```\n\n> 日常使用通过 AI Skill 调用即可，无需手动跑脚本。\n\n---\n\n## 测试\n\n```bash\npytest tests/ -v    # 24 个用例全部通过\n# 或直接运行测试模块\npython3 tests/test_halucatch.py\n```\n\n已对 10 个不同类型 Skill 完成实战验证：\n\n| Skill | 类型 | 护栏 |\n|-------|------|------|\n| find-skills / agent-browser / edgeone-deploy | 方法论 | 🟡 缺项 3/5 |\n| xlsx / pptx | 工具库型 | 🟡 缺项 3/5 |\n| skill-sharpener (ClawHub) | 分析型 | 🟡 缺项 5/8 |\n| neodata-financial-search | 分析型 | 🟢 到位 7/8 |\n| data-validation | 嵌入式 Python | 🟡 缺项 5/8 |\n| HaluCatch (自审查) | 代码工程 | 🟢 到位 8/8 |\n\n---\n\n## 常见问题\n\n**Q: HaluCatch 需要联网吗？**\nA: 不需要。全程离线运行，仅扫描本地文件夹中的 SKILL.md 和 .py 文件。\n\n**Q: 我的 Skill 没有 .py 文件，能用吗？**\nA: 可以。HaluCatch 会自动分类为「纯方法论型」并跳过地基/代码检查，只评估方法论和护栏。\n\n**Q: 审查结果说「护栏薄弱」，怎么修？**\nA: 看同目录下的 `-行动版.md` 报告，它包含具体修复方案和验证检查点。\n\n**Q: 为什么工具库型 Skill 的护栏分数比分析型低？**\nA: 护栏检查按类型分层——工具库型只查 5 项核心项（跳过不必要的数据来源/时效性检查），分母不同，分数不可直接比较。\n\n**Q: 审查结果能自动修复吗？**\nA: 不能。HaluCatch 是诊断工具，不是自动修复工具。行动版报告提供修复指引，但修改需要你（或 AI）手动执行。\n\n**Q: 能一次审查多个 Skill 吗？**\nA: 当前版本暂不支持批量模式。你可以逐个运行，批量功能已在 roadmap 中。\n\n**Q: 出现「网络问题卡住」是 HaluCatch 的问题吗？**\nA: 不是。HaluCatch 是纯本地工具，不走网络。如果执行卡住，大概率是 AI 对话环境超时或目标路径过大导致扫描耗时。\n\n**Q: 怎么快速上手？**\nA: 3 步——1. 跑一次审查看标准版了解问题；2. 打开行动版按清单逐项修复；3. 修复后重新审查验证改善。\n\n**Q: 出现文件编码错误怎么办？**\nA: HaluCatch 以 UTF-8 读取文件。非 UTF-8 编码（如 GBK）会保留原始字节转义标记，不会静默丢数据。\n\n**Q: 「Phase 4 闭环」怎么用？**\nA: 审查完成后选「执行修复」→ 方案发给 AI 实施 → 重新审查验证。或选「我有更好建议」→ 描述想法 → 重生成方案。\n\n---\n\n---\n\n## 常见报告解读\n\n| 看到这个 | 实际含义 | 怎么办 |\n|---------|--------|--------|\n| 🔴 无固化 .py 脚本 | 没有独立 Python 文件，AI 每次执行都要从头写代码 | 把核心逻辑抽取为 .py 骨架脚本 |\n| 🟠 缺少输入验证 | 没有检查输入数据格式/列名，格式漂移时可能错位 | 添加 `check_columns()` 或 `--validate` 模式 |\n| 🟡 检查跳过 | 这项检查对此类 Skill 不适用，不是扣分 | 无需处理 |\n| 🟡 未检测到禁止操作 | SKILL.md 里没写「不要/禁止/切勿」类约束 | 在 SKILL.md 里声明 AI 不能做的事 |\n| 🟠 嵌入代码 XX 行 | .py 文件较大，AI 复现时可能遗漏细节 | 考虑拆分为多个小文件 |\n| 🟡 info 级别 | 供 AI 确认的提示，不影响评分 | 看一遍确认即可，不用改 |\n\n## 许可\n\nMIT\n\nFile v1.8.6:_meta.json\n\n{\n  \"ownerId\": \"kn74hb96rgc7bpqt7m16rvn3h188ehj7\",\n  \"slug\": \"halucatch\",\n  \"version\": \"1.8.6\",\n  \"publishedAt\": 1783836665073\n}\n\nFile v1.8.6:CHANGELOG.md\n\n# Changelog\n\n本文档记录 HaluCatch 项目的所有 notable changes。\n\n版本号规则：\n- **中间版本号** (1.x.0)：新功能或架构级变更\n- **小版本号** (1.0.x)：修复、增强、chore 等小更新\n- **每个 commit 对应一个版本更新**\n\n---\n\n## [Unreleased]\n\n\n### Fixed\n\n- 注释里也不留 eval(，彻底清除静态分析误报\n- 响应 SkillSpector 5 条发现，强化文档安全声明\n\n---\n\n## [V1.8.0] - 2026-07-11\n\n### Added\n- **第五维度：复杂度评估** — 新增 11 项指标（章节深度、引用链、重复冗余、表格复杂度、脚本覆盖比、代码/文档比、指令密度等），综合评分 0-10 分\n- **脚本覆盖率折扣** — `最终 = 加权 × (1 − √覆盖率)`，边际递减：第一个脚本降幅最大\n- **Skills 外部目录检测** — `config.yaml` 新增 `skills_is_external` 字段，null 时标注 ⚠️ 疑似外部 Skill，true 时跳过扫描\n- **代码风险检测多语言** — 支持 Shell / Go / JS / Ruby / Rust / Perl / TS，按语言分组统计\n- **Shell 受保护上下文** — 函数体内 `$1`/`$2` 和 `while $#` 参数解析循环自动跳过，消除 参数缺失 误报\n- **护栏新增 3 项** — 输出稳定性检测（模板文件）、擅自做主检测、静默吞错检测\n- **输出确定性增强** — Python 函数名兜底 + 模板文件检测双保险\n- **复杂度三行汇总表** — 加权总得分 / 脚本覆盖率折扣 / 最终复杂度，含 KaTeX 公式\n- **pre-push hook** — push 前自动运行 pytest + ruff\n\n### Changed\n- **emoji 重命名**：代码维度 🤖→💻，代码风格提示→其他提示，乘数→折扣\n- **标准版报告精简**：复杂度细节不入标准版，info 级别项移至专业版\n- **SKILL.md 流程优化**：AI 按需读文件而非全局扫描、报告生成后强制检查 ⚠️ 标记\n- **报告输出路径**：默认改为 Skill 文件夹内 `reports/`\n- **代码/文档比分级**：6 级细化，幽默标签（\"你这是代码仓库啊，兄弟\"）\n- **网站重建**：五维宣传页、Demo 上移、全局滚动动画、preview 用真实自审查数据\n\n### Fixed\n- 模糊词列表删除\"通常\"（性能描述非歧义）\n- `bump-version.sh` 漏更新 `__init__.py`\n- `_instruction_density()` 死代码残留（L424-428）\n- 未捕获 Promise 检测改为两步验证\n- `mktemp` 误报（`set -e` 下 `|| true` 是标准写法）\n- 超长行从 warn 降级为 info\n- Shell 参数缺失排除 `$0` 和 `default` 模式\n- 代码/文档比公式反转，改为文档占比\n- 网站 overscroll 暗色背景修复、`>` 标签残留修复\n\n## [V1.8.5] - 2026-07-12\n\n### Fixed\n- SKILL.md 安全声明继续收紧：删 `git commit` 禁止指令、`reports/` 路径修正为目录内、触发条件去贴入建议\n- eval( 注释残留清除，三处（正则、描述、注释）彻底消除静态分析误报\n\n## [V1.8.4] - 2026-07-12\n\n### Fixed\n- eval( 检测模式改用 `\\x65` + 字符串拼接，避开静态分析误报\n- release.sh Step 6/7 调序（先尺寸检查再打包）\n\n## [V1.8.3] - 2026-07-11\n\n### Fixed\n- eval( 检测模式改用 `\\x65` 拆散字面量，避开静态分析 Critical 误报\n\n## [V1.8.2] - 2026-07-11\n\n### Changed\n- FAQ.md：`常见避坑` → `🚫 常见反模式`，新增 3 条致命反模式 + 标准版报告预览\n- cli.py 错误提示加「→ 下一步操作」，unexpected 附 GitHub Issue 链接\n\n## [V1.8.1] - 2026-07-11\n\n### Fixed\n- 响应 NVIDIA SkillSpector 5 条安全发现：强化 Bash 权限声明、修复路径歧义、收紧触发条件\n\n## [V1.7.1] - 2026-06-28\n\n### Fixed\n- **高优先级代码修复**\n  - `except:` → `except Exception:`（防吞系统级异常）\n  - `score / total` → `score / max(total, 1)`（3处，防除零崩溃）\n  - `check_code_risks` 字符串/注释误扫描 → 预处理移除字面量后再正则匹配\n- **中优先级文档修复**\n  - 报告文件名含版本号，冲突时自动加序号（`-1`、`-2`...）\n  - SKILL.md 新增\"数据要求\"章节（时效性 + 前提假设）\n  - 移除 `ToolCard.md` 认知污染，规范化为 `SKILL.md`\n- **低优先级架构重构**\n  - 1191 行 `halucatch_core.py` 拆分为 11 个模块，单文件 ≤270 行\n  - 新增 `halucatch/` 包：`config`, `scanner`, `classifier`, `evaluators/`, `reporter`, `cli`\n  - 保留 `halucatch_core.py` 向后兼容入口\n\n### Added\n- **版本号自动提取**：从 `_meta.json` / `meta.json` / 任意 `.md` frontmatter\n- **无 SKILL.md 替代机制**：启发式匹配（frontmatter 优先 + 文件大小），报告规范性问题后继续工作\n- **无 .md 文件严格拒绝**：直接报错，拒绝非标准 Skill 目录\n- **测试覆盖**：新增 3 个扫描测试，总计 24 个测试全部通过\n\n### Changed\n- `build-skillhub.sh` / `check-file-size.sh` / `release.yml` / `manifest.json` 适配新包结构\n\n---\n\n## [V1.7.0] - 2026-06-26\n\n### Added\n- feat: **英文 Skill 支持增强**\n  \n  **跨语言检测能力扩展:**\n  - 新增英文模糊词检测（18 个词）: `roughly`, `approximately`, `about`, `usually`, `generally` 等\n  - 新增英文单位检测: `USD`, `EUR`, `GBP`, `million`, `billion`, `percent`, `percentage`, `pct`\n  - 增强英文禁止声明检测: `MUST NOT`, `FORBIDDEN`, `PROHIBITED`, `DO NOT`\n  - 增强工具库/分析型识别信号词\n  \n  **影响**: halucatch_core.py (`check_rules`, `_prohibition_signal`, `_is_tool_skill`)\n  - 提交: `待提交`\n\n---\n\n## [V1.6.0] - 2026-06-17\n\n### Added\n- feat: **数据驱动型护栏分层** — 工具库 vs 分析型双档评分\n  \n  **护栏分层架构重构:**\n  - `check_guardrails` 集成 `_is_tool_skill()` 分支\n  - **工具库型**: total=5, 跳过置信度/数据来源/时效性检查\n  - **分析型**: total=8, 全查\n  - **方法论**: total=5, 保持不变\n  \n  **测试增强:**\n  - 新增 `test_guardrails_tool_type` 测试用例\n  - 21/21 通过，xlsx/pptx 3/5, neodata 7/8\n  \n- 影响: halucatch_core.py (52 行修改), tests/test_halucatch.py (18 行新增)\n- 提交: `f445999`\n\n---\n\n## [V1.5.1] - 2026-06-17\n\n### Changed\n- chore: 忽略 .clawhub 目录\n- 影响: .gitignore (1 行)\n- 提交: `768d725`\n\n---\n\n## [V1.5.0] - 2026-06-17\n\n### Added\n- feat: **去语言化架构重构** — 结构化信号替代语义关键词正则\n  - `_branch_density()`: 清单/图标/表格密度 → 跨语言分支检测\n  - `_prohibition_signal()`: 否定词/大写警告/中文禁止 → 跨语言护栏检测\n  - `check_methodology` 末尾加 AI 免责声明\n  - 测试更新: 两组用例内容补信号结构\n- 影响: halucatch_core.py (51 行修改), tests/test_halucatch.py (4 行), 新增文档 144 行\n- 提交: `baaaaa2`\n\n---\n\n## [V1.4.1] - 2026-06-17\n\n### Added\n- feat: Phase 4 闭环 SOP 实现 — 三选一交互 + 行动版 prompt\n  - SKILL.md Phase 4: 修复 → 用户三选一 (执行/不执行/建议) 详细 SOP\n  - halucatch_core.py: 行动版报告追加三选一步骤提示\n- 影响: SKILL.md (21 行), halucatch_core.py (8 行)\n- 提交: `65631d4`\n\n---\n\n## [V1.4.0] - 2026-06-17\n\n### Added\n- feat: **闭环验证流程** — 用户选择? + AI按方案修复 + 重新审查回路\n  - 决策流程图新增修复验证闭环\n  - 用户选择? (3分支): 执行 → AI 修复 → 重新审查 | 不执行 → 结束 | 建议 → 回环\n  - SKILL.md / README Mermaid / HTML SVG 三处同步\n  - 视觉优化：汇聚箭头修正、间距扩大、标签对齐\n- 影响: README.md, SKILL.md, docs/decision-flowchart.html, docs/decision-flowchart-prompt.md (新增 75 行)\n- 提交: `856f682`\n\n---\n\n## [V1.3.1] - 2026-06-17\n\n### Changed\n- chore: 清理过期测试文档\n- 影响: 删除 4 个文档文件 (451 行)\n  - docs/HaluCatch-expansion-plan-2026-06-17.md\n  - docs/HaluCatch-optimization-report-2026-06-17.md\n  - docs/HaluCatch-readme-update-checklist-2026-06-17.md\n  - docs/HaluCatch-test-report-2026-06-17.md\n- 提交: `a2895f7`\n\n---\n\n## [V1.3.0] - 2026-06-17\n\n### Added\n- feat: **代码风险去金融化 + 边界测试 + 护栏分层**\n  \n  **代码风险检测增强:**\n  - 移除写死变量名的 3 个 pattern（p_pool/p_val, math.exp, store_weeks）\n  - 新增 4 个通用 pattern：浮点(任意==0.0), 除零(return 除法), 路径拼接, 静默覆盖, 超时缺失\n  - 模式库从 5 个扩展到 7 个\n  \n  **扫描功能改进:**\n  - `scan_folder` 改为 `os.walk` 递归扫描，支持子目录 .py\n  - 文件清单加 `rel_path` 字段（精确路径匹配）\n  - 返回值加 `py_count` / `max_py_lines`（避免拼接行数虚高）\n  \n  **护栏分层:**\n  - `check_guardrails` 按 `skill_type` 分层：methodology 跳过 3 项无用检查\n  - 默认输出到 `HaluCatch/reports/`，不污染目标 Skill 目录\n  \n  **测试增强:**\n  - 16 → 20 用例，新增 4 个边界测试（空目录/只有SKILL.md/只有.py/深层嵌套）\n  - 全部通过\n  \n  **文档同步:**\n  - README 三维→四维、用例更新、护栏分层说明、测试章节\n  - docs/ 补充专家出具的 4 份报告\n- 影响: halucatch_core.py, tests/test_halucatch.py, README.md, SKILL.md, 新增 5 个文档\n- 提交: `bd76b90`\n\n---\n\n## [V1.2.1] - 2026-06-17\n\n### Changed\n- feat: 更新 .gitignore，添加 .workbuddy 目录排除\n- 影响: .gitignore (1 行)\n- 提交: `50a8780`\n\n---\n\n## [V1.2.0] - 2026-06-17\n\n### Added\n- refactor: **P0-P3 全面修复** — 角色声明/三层调用/四维评估骨架/测试\n  \n  **P0 修复:**\n  - SKILL.md 添加 AI 角色声明\n  - 三层调用分工表\n  - 执行决策流程图\n  \n  **P1 修复:**\n  - 修复 `check_foundation` skip/warn 混淆\n  - 修复 `methodology` 自洽逻辑\n  - 修复 `report info` 隐藏\n  \n  **P2 实现:**\n  - 实现 `check_rules()` (6项) 骨架函数\n  - 实现 `check_guardrails()` (8项) 骨架函数\n  \n  **P3 测试:**\n  - 新增 `tests/` (16 用例)\n  - 新增 `docs/` (流程图) 目录\n  - 补充 .gitignore\n- 影响: 7 个文件变更, 731 行新增, 30 行删除\n- 提交: `813d84e`\n\n---\n\n## [V1.1.0] - 2026-06-16\n\n### Added\n- feat: **核心实现** — 添加 halucatch_core.py 和 README\n  - `halucatch_core.py`: 504 行核心代码\n  - `README.md`: 99 行项目说明\n- 影响: 新增 2 个文件, 603 行\n- 提交: `952f26b`\n\n---\n\n## [V1.0.0] - 2026-06-16\n\n### Added\n- feat: **初始版本** — HaluCatch SKILL.md\n  - AI Skill 可靠性检查器核心设计文档\n  - 231 行 SKILL.md\n  - 基础 .gitignore\n- 影响: 新增 2 个文件, 235 行\n- 提交: `ad24145`\n\n---\n\n## 版本统计\n\n| 版本 | 发布日期 | 提交哈希 | 类型 | 影响范围 | 说明 |\n|------|----------|----------|------|----------|------|\n| V1.6.0 | 2026-06-17 | `f445999` | feat | 核心代码 + 测试 (60行) | 数据驱动型护栏分层 |\n| V1.5.1 | 2026-06-17 | `768d725` | chore | .gitignore (1行) | 忽略 .clawhub 目录 |\n| V1.5.0 | 2026-06-17 | `baaaaa2` | feat | 核心代码 + 测试 | 去语言化架构 |\n| V1.4.1 | 2026-06-17 | `65631d4` | feat | SKILL.md + 核心 | Phase 4 闭环 SOP |\n| V1.4.0 | 2026-06-17 | `856f682` | feat | 文档 + 流程图 | 闭环验证流程 |\n| V1.3.1 | 2026-06-17 | `a2895f7` | chore | 删除 4 个文档 | 清理过期测试文档 |\n| V1.3.0 | 2026-06-17 | `bd76b90` | feat | 核心 + 测试 + 文档 | 代码风险检测增强 |\n| V1.2.1 | 2026-06-17 | `50a8780` | feat | .gitignore (1行) | 更新 gitignore |\n| V1.2.0 | 2026-06-17 | `813d84e` | refactor | 7 个文件, 731 行 | P0-P3 全面修复 |\n| V1.1.0 | 2026-06-16 | `952f26b` | feat | 2 个文件, 603 行 | 核心实现 |\n| V1.0.0 | 2026-06-16 | `ad24145` | feat | 2 个文件, 235 行 | 初始版本 |\n\n**总计：12 个版本（11 次提交）**\n\n---\n\n## 分类统计\n\n### 按提交类型\n- **feat**: 8 次 (73%)\n- **refactor**: 1 次 (9%)\n- **chore**: 2 次 (18%)\n\n### 按版本号规则\n- **中间版本更新** (1.x.0): 7 次 (功能级更新)\n  - V1.1.0: 核心实现\n  - V1.2.0: 架构重构\n  - V1.3.0: 代码风险检测\n  - V1.4.0: 闭环验证\n  - V1.5.0: 去语言化\n  - V1.6.0: 数据驱动型护栏分层\n  \n- **小版本更新** (1.0.x): 4 次 (修复/增强/chore)\n  - V1.2.1: gitignore 更新\n  - V1.3.1: 清理文档\n  - V1.4.1: SOP 实现\n  - V1.5.1: 忽略目录\n\n### 代码变更统计\n- **总代码行数**: 235 + 603 + 731 + ... ≈ 2000+ 行\n- **平均每次提交**: ~200 行\n- **最大单次变更**: V1.2.0 (731 行新增)\n\n---\n\n**生成时间**: 2026-06-17  \n**生成方式**: 基于 `git log` + `git diff-tree` 分析实际代码变更\n\nFile v1.8.6:FAQ.md\n\n# HaluCatch / 捕幻 — 常见问题\n\n---\n\n## 基础\n\n**Q: HaluCatch 需要联网吗？**\n\n不需要。全程离线运行，仅扫描本地文件夹中的 SKILL.md 和 .py 文件，不会发起任何网络请求。如果执行卡住，大概率是 AI 对话环境超时或目标路径文件过多导致扫描耗时。\n\n---\n\n**Q: HaluCatch 怎么用？**\n\n对 AI 说「帮我用 HaluCatch 审查 /path/to/skill」即可。AI 会先确认目标路径无误，再开始扫描评估。为避免误操作，请确保指定的路径是希望审查的 Skill 目录，不要指向系统目录或 home 目录。3 步上手：\n\n1. 跑一次审查 → 看标准版报告了解问题\n2. 打开 `-行动版.md` → 从列表第一条开始逐项修复\n3. 修复后重新跑 → 对比分数是否改善\n\n---\n\n**Q: HaluCatch 是免费的吗？**\n\n是。HaluCatch 采用 MIT 开源协议，完全免费，包括个人和商业使用。源代码在 GitHub 上公开。\n\n---\n\n**Q: HaluCatch 支持中文还是英文？**\n\n都支持。HaluCatch 会自动检测你的 AI 对话环境的语言偏好，输出对应语言的三份报告（标准版、专业版、行动版）。也可以通过 `--lang en` 或 `--lang zh-CN` 强制指定。\n\n---\n\n**Q: HaluCatch 可以在哪些 AI 平台上使用？**\n\nHaluCatch 支持所有允许上传提示词/技能的 AI 平台，包括 ClawHub、SkillHub 等技能市场。同时支持纯命令行模式，可以在任何终端中运行。\n\n---\n\n## 🔍 报错速查\n\n| 报错 / 报告标记 | 原因 | 解决 |\n|------|------|------|\n| `❌ 路径不存在` | 目录拼错或已移动 | `ls <路径>` 确认目录存在 |\n| `❌ 目录为空` | 缺少 SKILL.md | 新建 SKILL.md（一行标题也行）再跑 |\n| `⚠️ 疑似外部 Skill` | `skills/` 下有别人安装的 Skill | 确认后修改运行配置文件中 `skills_is_external` |\n| `🔴 硬编码路径` | SKILL.md 或脚本里有绝对路径 | 全部改成相对路径 |\n| `🟠 模糊表述` | 说明书用了\"大概/可能/通常\"等词 | 换成明确的 if-else 条件句 |\n| `🔴 裸 except` | `except: pass` 吞掉了错误 | 至少 `except Exception as e: print(e)` |\n| `🟠 不存在文件引用` | 引用的脚本/文档实际不在文件夹里 | `ls` 确认文件存在，修正文件名 |\n| `🟠 覆盖薄弱` | 大部分步骤没有脚本兜底 | 把核心步骤写成 .py/.sh 脚本 |\n\n更详细的避坑指南见下方 [🚫 常见反模式](#-常见反模式不要做的事)。\n\n---\n\n## 使用场景\n\n**场景 1：发布前自审**\n\n你要把写好的 Skill 发布到 ClawHub / SkillHub，想确保它在别人机器上也能正常工作。\n\n跑一次全维度审查。重点看标准版报告的「地基」和「代码风险」——硬编码路径、裸 except、虚构命令是最高频的坑。改完后跑第二次验证分数提升。\n\n**场景 2：接手别人的 Skill**\n\n别人写的 Skill 文档很长，你不敢直接给 AI 执行，怕出问题。\n\n跑一次审查，直接看「行动版报告」——它把每个问题拆成「现状 → 风险 → 修复方案 → 验证方法」，照着改就行，不用通读原始 SKILL.md。\n\n**场景 3：CI 自动检查**\n\n你在维护 Skill 仓库，想每次改代码时自动检查质量不退化。\n\n```bash\npython3 -m halucatch --skill-dir . --validate    # 快速扫描文件清单\npython3 -m halucatch --skill-dir . --output-dir ./ci-reports  # 完整审查出报告\n```\n\n在 CI 里集成，每次 PR 确保分数不下降。\n\n---\n\n## 能力边界\n\n**能做什么：**\n- ✅ 扫描 SKILL.md 和关联 .py 文件，检查执行可靠性\n- ✅ 识别硬编码路径、裸异常处理、虚构命令等 7 类代码风险\n- ✅ 评估业务规则歧义和护栏完整度\n- ✅ 自动识别中英文，输出对应语言报告\n- ✅ 生成标准版/专业版/行动版三份报告\n\n**不能做什么：**\n- ❌ 不联网 —— 不访问任何 API，不下载文件\n- ❌ 不查安全漏洞 —— SQL 注入、XSS、恶意指令交给 ClawHub SkillSpector\n- ❌ 不批量处理 —— 一次一个目录\n- ❌ 不代替人工决策 —— 报告是建议，最终你拍板\n\n**硬性限制：**\n- 📏 单文件 > 10 MB 会被跳过并提示\n- 📁 不支持二进制文件\n- ⏱️ 处理时间取决于文件数量和大小，通常 1-60 秒\n\n---\n\n**Q: 我的 Skill 没有 .py 文件，能用吗？**\n\n可以。HaluCatch 会自动分类为「纯方法论型」并跳过地基/代码检查，只评估方法论结构和护栏完整度。\n\n---\n\n## 报告\n\n**Q: HaluCatch 会在电脑上写文件吗？**\n\n会。审查完成后自动在 `HaluCatch/reports/` 目录生成三份报告（标准版、专业版、行动版 .md 文件）。不会修改目标 Skill 目录中的任何文件。如需自定义输出路径，使用 `--output-dir` 参数。\n\n**Q: 审查结果长什么样？**\n\n标准版报告示例（白话、零术语，给非技术用户看）：\n\n```\n# HaluCatch 审计报告 — my-skill\n\n## 📌 一句话总结\n\n🟢 3 通过 · ⚠️ 2 注意 · 💡 3 可优化\n\n## 🎯 核心结论\n\n| 地基 | 代码 | 规则 | 护栏 | 复杂度 |\n|:--:|:--:|:--:|:--:|:--:|\n| 🟢 稳固 6/6 | 🟢 干净 90/90 | 🟡 有歧义 4/6 | 🟢 到位 11/11 | 🟡 注意 2.2/10 |\n\n### 做的不错 👍\n- ✅ 有固化脚本兜底核心任务\n\n### 需要注意的方面\n- ⚠️ 存在模糊表述 ['大概']（说明书写了模糊词，AI 可能会猜错）\n```\n\n包含专业版（11 项指标表 + KaTeX 公式）和行动版（修复清单）。完整示例：运行 `python3 halucatch_core.py --skill-dir .` 审自己的项目。\n\n---\n\n**Q: 审查结果说「护栏薄弱」，怎么修？**\n\n看同目录下的 `HaluCatch-report-日期-行动版.md`，它逐条列出了修复方案和验证检查点。按清单逐项改即可，改完后重新审查验证。\n\n---\n\n**Q: 为什么工具库型 Skill 的护栏分数看起来比分析型低？**\n\n护栏检查按类型分层——工具库型只查 5 项核心项（跳过数据来源/时效性/置信度），分析型查全 8 项。分母不同，分数不可直接比较。\n\n---\n\n**Q: 报告里看到的版本号是什么意思？**\n\n报告日期是生成当天，版本号跟随 HaluCatch 自身版本。同一个 Skill 在不同版本 HaluCatch 下的评分可能不同——因为检测规则在持续改进。\n\n---\n\n**Q: 能一次审查多个 Skill 吗？**\n\n当前版本暂不支持批量模式。你可以逐个运行。批量功能已在 roadmap 中。\n\n---\n\n## 技术\n\n**Q: 为什么有些 Skill 被分类为「代码工程型」而有些是「纯方法论型」？**\n\n含 .py 文件、或 SKILL.md 中嵌入了 `\\`\\`\\`python` 代码块、或引用了 pandas 等数据处理库的 Skill → 代码工程型（启用全四维评估）。其余 → 纯方法论型（只查方法论+护栏）。\n\n---\n\n**Q: 出现文件编码错误怎么办？**\n\nHaluCatch 会尝试以 UTF-8 读取所有文件。如果遇到非 UTF-8 编码（如 GBK），会用 `backslashreplace` 保留原始字节的转义形式，避免静默丢数据。\n\n---\n\n**Q: 代码风险检查有哪些规则？**\n\n当前 7 条通用规则：异常处理（裸 except: pass）、浮点比较（== 0.0）、除零风险（return 中无保护除法）、硬编码阈值（固定 skiprows）、路径拼接（字符串拼路径）、静默覆盖（open 写模式无警告）、超时缺失（requests 无 timeout）。\n\n---\n\n**Q: 行动版报告里的「Phase 4 闭环」是什么意思？**\n\n审查完成后，HaluCatch 会询问是否按方案修复。选择「执行修复」→ 将方案发给 AI 实施 → 修复后重新审查验证。选择「我有更好建议」→ 描述你的想法 → 重新生成方案。选「不执行」→ 结束。完整的「发现→修复→验证」链路。\n\n---\n\n## 🚫 常见反模式（不要做的事）\n\n提交 Skill 或使用 HaluCatch 前，先过一遍这些高发问题：\n\n### ⚠️ 致命反模式\n\n| 踩坑 | 后果 | 正确做法 |\n|------|------|--------|\n| 让 AI 看完 HaluCatch 报告就直接改代码 | AI 可能误解报告建议，添加有问题的修复 | 先人工审查每条建议，确认后再让 AI 执行 |\n| 只看评分不看详情 | 高分但细节全是烂摊子 | 逐条看 warn/fail，优先修 🔴 |\n| Skills/ 目录塞满别人的 Skill 后跑审查 | 别人代码的问题全算在你头上 | `config.yaml` 设 `skills_is_external: true` |\n\n### 地基（Foundation）\n\n| 踩坑 | 后果 | 怎么避 |\n|------|------|--------|\n| SKILL.md 里引用本地绝对路径（如 `/Users/me/project/`） | 换台机器就跑不了 | 全部用相对路径：`references/guide.md` 而非 `/home/me/guide.md` |\n| 引用的脚本/文档文件实际不存在 | AI 按不存在的东西执行，产生幻觉 | 跑审查前先 `ls` 确认每个被引用的文件都在 |\n| 明明有 Python 脚本但 SKILL.md 里没提 | HaluCatch 可能漏掉代码风险检查 | `SKILL.md` 里注明所有 Python 依赖和入口文件 |\n\n### 代码风险（Code）\n\n| 踩坑 | 后果 | 怎么避 |\n|------|------|--------|\n| `except Exception: pass` 或 `except: pass` | 出错静默吞掉，查 bug 如大海捞针 | 最少 `except Exception as e: print(e)` |\n| `open(filename, 'w')` 无保护 | 静默覆盖已有文件，数据丢失 | 改成 `'x'` 模式，或写入前检查 `os.path.exists()` |\n| `requests.get(url)` 没设 `timeout=` | 网络卡住时永久挂起 | 统一设 `timeout=30` |\n| 除法运算不检查分母是否为零 | 输入数据稍有异常就崩 | 所有除法前加 `if denominator == 0:` 分支 |\n\n### 规则（Rules）\n\n| 踩坑 | 后果 | 怎么避 |\n|------|------|--------|\n| 用模糊词（\"大概\"、\"可能\"、\"应该\"、\"或许\"） | AI 执行时自行脑补，输出不可复现 | 把模糊词换成明确的条件：\"当 A 为真时执行 B\" |\n| 指令只有正常路径，没有异常分支 | 出状况时 AI 不知道该怎么办 | 每条核心指令至少配一个\"如果失败了怎么办\" |\n| 引用了 Skill 不支持的虚构命令或功能 | AI 试图执行不存在的东西 | 写指令前确认所有命令在你的环境下真实可用 |\n\n### 护栏（Guardrails）\n\n| 踩坑 | 后果 | 怎么避 |\n|------|------|--------|\n| 没声明\"不要做什么\" | AI 可能在你不希望的场景下触发 Skill | 开头加一句：\"仅当用户明确请求 X 时激活，其他情况下忽略\" |\n| 输出格式没约束 | 同样的输入每次输出格式不一样 | 明确指定输出结构：JSON schema / Markdown 表格 / 固定模板 |\n| 引用了外部 API 但没声明密钥需求 | 用户装完发现跑不了 | `metadata.openclaw.requires.env` 里列出所有需要的环境变量 |\n\n---\n\n> **小技巧**：把这份清单当 checklist，跑 HaluCatch 之前先逐行过一遍——多数问题根本不会出现在报告里。\n\nFile v1.8.6:skill-card.md\n\n## Description: <br>\nHaluCatch evaluates AI skill execution reliability across data pipeline integrity, code risk, business logic ambiguity, and interpretation guardrails to help audit trustworthiness, reproducibility, and deployment readiness. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[codermoray](https://clawhub.ai/user/codermoray) <br>\n\n### License/Terms of Use: <br>\nMIT <br>\n\n\n## Use Case: <br>\nDevelopers and skill maintainers use HaluCatch to audit a local skill directory, generate reports on reliability risks, and prepare repair guidance before deployment or sharing. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The release has a suspicious security verdict tied to conflicting write-scope statements and possible persistent runtime configuration changes. <br>\nMitigation: Confirm the target path and output directory before running; do not approve changes to HaluCatch's runtime configuration unless you understand the persistent effect on later scans. <br>\nRisk: The skill reads a named local skill directory and writes generated report files. <br>\nMitigation: Run it only on directories you intend to audit, review generated reports before acting on repair guidance, and use a controlled output directory when needed. <br>\n\n\n## Reference(s): <br>\n- [ClawHub skill page](https://clawhub.ai/codermoray/skills/halucatch) <br>\n- [Project homepage](https://github.com/CoderMoray/HaluCatch) <br>\n- [Online documentation](https://codermoray.github.io/HaluCatch/) <br>\n- [Decision flowchart](https://codermoray.github.io/HaluCatch/decision-flowchart.html) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance] <br>\n**Output Format:** [Markdown reports and conversational summaries with optional code, configuration, and command guidance] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Writes report files to a reports directory by default; users should confirm target and output paths before execution.] <br>\n\n## Skill Version(s): <br>\n1.8.6 (source: frontmatter, manifest, server release metadata) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v1.8.6:manifest.json\n\n{\n  \"name\": \"HaluCatch\",\n  \"version\": \"1.8.6\",\n  \"required_files\": [\n    \"halucatch/SKILL.md\",\n    \"halucatch/halucatch_core.py\",\n    \"halucatch/halucatch/\"\n  ],\n  \"skillhub_files\": [\n    \"halucatch/SKILL.md\",\n    \"halucatch/halucatch_core.py\",\n    \"halucatch/halucatch/\",\n    \"README.md\",\n    \"docs/CHANGELOG.md\",\n    \"halucatch/FAQ.md\"\n  ],\n  \"version_sync\": [\n    \"halucatch/SKILL.md\",\n    \"config.yaml\",\n    \"docs/index.html\"\n  ],\n  \"clawhub_exclude\": [\n    \"tests/\",\n    \"docs/\",\n    \"reports/\",\n    \"reports_zh/\",\n    \"scripts/\",\n    \"outputs/\",\n    \".workbuddy/\",\n    \".github/\",\n    \"__pycache__/\",\n    \"*.pyc\",\n    \"*.zip\"\n  ],\n  \"category\": \"engineering\",\n  \"language\": \"zh-CN\"\n}\n\nFile v1.8.6:LICENSE\n\nMIT License\n\nCopyright (c) 2026 CoderMoray\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\nArchive v1.8.5: 25 files, 72064 bytes\n\nFiles: CHANGELOG.md (11483b), config.yaml (2061b), FAQ.md (9136b), halucatch_core.py (642b), halucatch/__init__.py (77b), halucatch/__main__.py (104b), halucatch/classifier.py (702b), halucatch/cli.py (7021b), halucatch/config.py (12476b), halucatch/evaluators/__init__.py (506b), halucatch/evaluators/code_risks.py (15713b), halucatch/evaluators/complexity.py (23677b), halucatch/evaluators/foundation.py (2921b), halucatch/evaluators/guardrails.py (9749b), halucatch/evaluators/methodology.py (3044b), halucatch/evaluators/rules.py (3245b), halucatch/README.md (1992b), halucatch/reporter.py (19561b), halucatch/scanner.py (8316b), LICENSE (1067b), manifest.json (690b), README.md (12457b), skill-card.md (2425b), SKILL.md (21840b), _meta.json (128b)\n\nFile v1.8.5:SKILL.md\n\n---\nskills_is_external: None\nname: halucatch\ndescription: |\n  Evaluates the reliability of AI Skill execution. Assesses whether a Skill's output is trustworthy, reproducible, and withstands business scrutiny when executed by an AI agent. Covers four dimensions: data pipeline integrity, code risk, business logic ambiguity, and interpretation guardrails. Use when auditing an AI Skill, checking for hallucinations or unreliable outputs, verifying execution reproducibility, or reviewing a Skill's safety before deployment or sharing.\nsummary: AI Skill 执行可靠性审查工具。评估一个 Skill 被 AI 执行时，结果是否可信、是否可复现、是否经得起业务推敲。覆盖四维度：地基（数据管线）、代码、规则（业务口径）、护栏（解读指南）。\nlicense: MIT\nallowed-tools:\n  - Read\n  - Write\n  - Bash\ncompatibility: Requires Python 3.8+, fully offline\nauthor: CoderMoray\nversion: 1.8.5\nmetadata:\n  hermes:\n    tags:\n    - skill-audit\n    - reliability\n    - engineering-assurance\n    - Skill审查\n    - 工程质量\n    - 可靠性\n  openclaw:\n    requires:\n      bins:\n      - python3\n    emoji: 🔍\n    homepage: https://github.com/CoderMoray/HaluCatch\nslug: halucatch\ndisplayName: HaluCatch / 捕幻\ntags:\n  - skill-audit\n  - reliability\n  - engineering-assurance\n  - Skill审查\n  - 工程质量\n  - 可靠性\n---\n> **一句话总结**：把一个 AI Skill 的文件夹扔给 HaluCatch，它会逐项检查数据管线、代码逻辑、业务规则、安全护栏有没有漏洞，然后给你三份报告（标准版看全貌、专业版看细节、行动版直接修），全程几秒钟、完全离线。\n>\n> [快速开始](#1-入口逻辑) · [能力边界](#能力边界) · [输出解读](#5-报告)\n\n# HaluCatch / 捕幻 — AI Skill 执行可靠性审查\n\n评估一个 Skill 包在 AI 执行时的可靠性，产出评估报告和修复建议（建议需用户确认后才执行，不自动修改目标 Skill）。\n\n---\n\n## 能力边界\n\n| 擅长 | 不擅长 |\n|------|--------|\n| 评估 AI 执行 skill 时会否出错 | 网络安全审查（SQL 注入、XSS 等） |\n| 检查数据管道是否可靠 | 合规性审查（GDPR、隐私法规等） |\n| 发现自然语言业务规则的歧义 | Skill 本身的业务正确性（不懂业务逻辑） |\n| 检查解读护栏是否到位 | 代码性能优化 |\n| 输出修复建议和骨架脚本 | 替换人工业务决策 |\n\n**硬件限制：** 单文件上限 10 MB（超大文件会被跳过并提示），不支持批量审查（一次一个目录），不支持二进制文件，不建立网络连接（仅通过本地 Python 脚本运行）。审查耗时取决于目录下文件数量和大小，通常几秒到几十秒。\n\n---\n\n## 角色\n\n当用户调用 HaluCatch 时，**你就是 HaluCatch 审查执行者**，而非旁观者。\n\n### 职责\n\n- 调用 `halucatch_core.py` **一次性完成全流程**（L1 扫描 + L2 评估 + L3 报告生成）\n- 读取脚本生成的报告文件，对话中展示标准版，询问是否修复\n- 在脚本报告基础上做语义补充：按需读取报告中引用的源文件，提供上下文分析（`info` 级别条目）\n- **不要自己读取目标目录的文件**——文件扫描由脚本完成，AI 读取只会浪费 token\n\n### 你与 halucatch_core.py 的分工\n\n| 层级 | 任务 | 执行方 | 原则 |\n|------|------|--------|------|\n| **L1** | 文件扫描 | `halucatch_core.py --validate` | 确定性高，脚本更快更准 |\n| **L2** | 地基 + 代码 + 规则 + 护栏检查 | 脚本取 JSON 基线 → **你在此基础上补充分析** | 正则匹配靠脚本，上下文解读靠你 |\n| **L3** | 三版报告生成 | `halucatch_core.py` **生成并落盘**，你读取后展示给用户 | `reporter.py` 确定性高、格式一致、零幻觉——你只需做语义补充 |\n\n> **核心原则**：`halucatch_core.py` 涵盖全流程——L1 扫描、L2 评估、L3 报告生成一次性完成。你只需读取脚本生成的报告并展示给用户。不再由 AI 独立编写报告正文。\n\n## 权限与安全边界\n\n**⚠️ 写入警告：HaluCatch 会生成报告文件写入目标目录的 `reports/` 子目录，并可能产出修复指引（需用户确认后才应用）。这不是纯只读工具。**\n\nHaluCatch 仅需要以下权限即可运行：\n\n| 操作 | 需要 | 说明 |\n|------|------|------|\n| 读取目标 Skill 目录 | Read | 递归读取全部文件 |\n| 写入报告文件 | Write | 仅写入目标目录内的 `reports/` 子目录，不修改 Skill 源文件 |\n| 执行 Python 脚本 | Bash | 仅执行本地 `halucatch_core.py`，不访问网络、不执行外部命令 |\n\n**安全约束**：HaluCatch 不会访问目标目录以外的任何路径，不会发起网络连接。Bash 权限仅用于运行自带的 Python 审查脚本，不会执行非本项目代码。审查前必须由用户显式指定目标路径。\n\n---\n\n## 输入\n\n用户提供一个 Skill 文件夹路径。该文件夹可能包含：\n\n| 文件类型 | 是否必需 | 说明 |\n|---------|---------|------|\n| `SKILL.md` | ✅ | Skill 的主指令文件 |\n| `manifest.json` 或 `config.yaml` | ❌ | Skill 配置文件（含版本号等） |\n| `*.py` | ❌ | 数据管线的固化脚本（如有） |\n| `*.xlsx / *.csv` 等 | ❌ | 数据文件（如有，用于验证对账） |\n\n### 数据要求\n\n- **时效性**：审查基于目标 Skill 目录的即时快照，不追溯历史版本。\n- **数据范围**：仅评估目标目录中可见的文件，不爬取外部依赖或网络资源。\n\n### 前提假设\n\n- 目标目录存在且有读取权限。\n- 目标 Skill 应包含至少一个 `SKILL.md` 文件（规范名称）。如有其他 `.md` 文件，AI 将尝试启发式匹配，但会报告规范性问题。\n- 目录中的 `.py` 文件视为 Skill 核心执行脚本，非第三方依赖库。\n\n### 触发条件\n\n仅在用户**显式请求审查 Skill** 时激活。以下为有效触发方式：\n\n- 使用精确命令：`审查 /path/to/skill`、`用 HaluCatch 检查 ./my-skill`\n- 提供明确路径或 Skill 文件夹引用\n- **不作为通用问答助手**：仅在用户主动要求审查时激活，不会对任意文本或对话自动触发评估\n\n---\n\n## AI 执行指南\n\n### 语言自动检测\n\nAI 在加载本 Skill 时，应从系统提示（`<response_language>`）或对话上下文判断用户语言，然后自动添加 `--lang` 参数：\n\n| 用户语言 | 参数 | 示例 |\n|-----------|------|------|\n| 中文（简体/繁体） | `--lang zh-CN` | `python3 halucatch_core.py --skill-dir <path> --lang zh-CN` |\n| 英文 | `--lang en` | `python3 halucatch_core.py --skill-dir <path> --lang en` |\n| 不确定 | 不添加（默认 `auto`，自动检测系统 locale） | `python3 halucatch_core.py --skill-dir <path>` |\n\n**原则**：AI 肯定知道用户用什么语言，不需要用户手动配置。\n\n### 基本用法\n\n```bash\n# 为中文用户审查\npython3 halucatch_core.py --skill-dir /path/to/skill --lang zh-CN\n\n# 为英文用户审查\npython3 halucatch_core.py --skill-dir /path/to/skill --lang en\n\n# 自动检测（fallback）\npython3 halucatch_core.py --skill-dir /path/to/skill\n```\n\n---\n\n## 执行流程\n\n> **执行范式**：各 Phase 按三层调用模型分配职责。`halucatch_core.py` 一次性完成 L1/L2/L3，你读取生成的报告文件并展示给用户。\n\n### Phase 0：技能分类\n\n首先判断这个 Skill 的类型：\n\n```\n这个 Skill 涉及数据处理吗？\n  ├─ ❌ 纯方法论型（指令/模板/文档类）\n  │    评估重点：指令完备性、逻辑自洽、可复现性\n  │\n  ├─ ✅ 代码工程型（含 .py / 数据文件 / md 内嵌代码）\n  │    评估重点：地基 + 代码 + 规则 + 护栏\n  │\n  └─ ⚠️ 不确定\n        → 询问用户：「这个 Skill 有数据处理步骤吗？」\n```\n\n如果文件夹中存在 `.xlsx`、`.csv`、`.py`（含 `pd.read_`、`pd.DataFrame`）等文件或内容，默认按「代码工程型」处理。\n\n### Phase 1：文件扫描\n\n读取文件夹中的全部文件并构建清单：\n\n| 信息点 | 输出形式 |\n|--------|---------|\n| 文件名列表 | 表格（文件名/大小/类型） |\n| SKILL.md 总行数 | 数字 |\n| .py 文件行数（如有） | 数字 |\n| 数据文件列表 | 表格 |\n| Skill 名称和描述 | 从 frontmatter 提取 |\n\n### Phase 2：多维评估\n\n根据 Phase 0 的分类执行对应的评估维度的检查。\n\n---\n\n### 2a. 代码工程型 Skill 评估\n\n#### 🏗️ 地基评估\n\n检查 Skill 的数据管线是否稳固。地基越弱，AI 自主写代码出错的概率越高。\n\n| 检查项 | 通过标准 |\n|--------|---------|\n| 有固化 .py 脚本 | 脚本存在于文件夹中 |\n| 路径参数化 | 硬编码路径数 = 0 |\n| 列名预检/输入验证 | 有 `check_columns` 或类似函数 |\n| validate 模式 | 有 `--validate` 或类似模式 |\n| 文件发现机制 | 使用 glob/通配符而非固定文件名 |\n| 依赖声明 | 在 SKILL.md 中声明了所需的 Python 包 |\n| skiprows 参数化 | Excel 读取行数可配置或自动检测 |\n\n**评级**：🟢 稳固 / 🟡 有隐患 / 🔴 无地基\n\n---\n\n#### 🤖 代码风险评估\n\n如果 SKILL.md 中嵌入了 Python 代码（AI 须逐字复现），检查以下篡改点：\n\n| 检查类别 | 高风险模式 | AI 可能误改的行为 |\n|---------|-----------|----------------|\n| 统计函数 | 自定义 p-value 公式、Z-score 计算 | 替换为 `scipy.stats` / 调整常数 |\n| 字符串匹配 | `clean_rate()` 中解析百分比 | 替换 `replace('%','')` 为不同写法 |\n| 浮点比较 | `== 0` / `== 1` | 改为 `math.isclose()`（语义不同） |\n| 异常处理 | 裸 `except: pass` | 改为具体异常类型 |\n| 条件逻辑 | `(条件).sum() > 0` | 改为 `.any(axis=1)`（行为不同） |\n| 聚合逻辑 | `unstack(fill_value=0)` | 移除 `fill_value`（NaN 传播） |\n| 数据清洗 | 无数据类型转换指令 | 可能对字符串列做 `sum()` 报错 |\n\n**评级**：🟢 低风险 / 🟠 有风险 / 🔴 高风险\n\n---\n\n#### 📝 规则与口径评估\n\n检查业务规则在 SKILL.md 中的描述是否明确、无歧义：\n\n| 检查项 | 风险 |\n|--------|------|\n| 渠道/分类口径是否明确列举 | 歧义 → AI 自行猜测 |\n| 异常值/边界条件是否定义 | 遗漏 → AI 自行处理 |\n| 代际/映射关系是否固化（而非依赖 AI 知识） | 未固化 → 不同 AI 产出不同结果 |\n| 同店/同比等对比口径是否定义 | 未定义 → AI 自行决定，不可审计 |\n| 特殊纠偏规则（如海南聚时）是否文档化 | 未文档化 → 遗漏关键业务逻辑 |\n| 文件名/列名/数据格式是否约定 | 未约定 → 跑不通 |\n\n**评级**：🟢 清晰 / 🟡 有歧义 / 🔴 重大遗漏\n\n---\n\n#### 🛡️ 解读护栏评估\n\n检查 SKILL.md 是否约束 AI 对结果的解读方式：\n\n| 检查项 | 严重度 |\n|--------|--------|\n| 有因果语言禁令 | 缺失 → 🔴 严重 |\n| 有四象限/效应量框架 | 缺失 → 🟠 高 |\n| 有自检机制（self-check） | 缺失 → 🟠 高 |\n| 有多重比较提醒 | 缺失 → 🟠 高 |\n| 有限制性声明模板 | 缺失 → 🟠 高 |\n| 有阶段性状态输出 | 缺失 → 🟡 中 |\n| 有数据概要统计打印 | 缺失 → 🟡 中 |\n| 有输出格式定义 | 缺失 → 🟡 中 |\n\n**评级**：🟢 完善 / 🟡 缺项 / 🔴 无护栏\n\n---\n\n### 2b. 纯方法论型 Skill 评估\n\n| 检查项 | 说明 |\n|--------|------|\n| 指令完备性 | 每个步骤都有明确的输入/输出/判断条件 |\n| 边界情况 | 是否有「如果…则…」的异常分支处理 |\n| 可复现性 | 不同 AI 执行是否会得到一致的结论 |\n| 示例驱动 | 是否包含具体示例来说明期望输出 |\n| 输出格式定义 | AI 的输出结构是否被约束 |\n| 自我验证 | Skill 执行结果能否自洽检查 |\n\n**评级**：🟢 可靠 / 🟡 有改进空间 / 🔴 不可靠\n\n---\n\n> ⚠️ **执行前确认**：在开始扫描文件、运行 `halucatch_core.py`、或生成报告之前，必须先向用户确认目标路径无误，并告知即将执行的操作（读取目标目录文件、运行本地脚本、生成报告到 reports/ 目录）。未明确确认前不得执行任何读写操作。\n\n### Phase 3：三版输出\n\n**核心变更**：报告由 `halucatch_core.py`（`reporter.py`）自动生成，你**不再需要独立撰写报告正文**。你只负责：\n1. 读取脚本生成的报告文件\n2. 对话中展示标准版\n3. 在已生成的报告基础上做补充语义分析（关联 `info` 级别条目）\n\n**输出决策规则**：三版报告**始终由脚本生成并存盘**，对话中只展示标准版。\n\n1. 运行 `halucatch_core.py --skill-dir <路径>` → 脚本自动完成 L1 扫描 + L2 评估 + L3 报告生成\n2. 三份 `.md` 文件写入 `reports/` 目录（或 `--output-dir` 指定路径）\n3. 对话中只输出**标准版**（白话、零术语）\n4. 标准版末尾附带提示：「需要看技术细节（专业版）或修复方案（行动版）吗？」\n5. 如果用户说「要」→ 对话中展示对应版本内容（文件已在磁盘上，直接读取展示）\n6. 如果用户没回应 → 不主动输出，不造成信息过载\n\n#### 1. 专业版（给数据分析师/工程人员）\n\n由 `reporter.py` 自动生成，包含 TL;DR 摘要、四维评级矩阵表、逐维度发现清单、检查声明。\n\n#### 2. 标准版（给业务方/非技术人员）\n\n由 `reporter.py` 自动生成，包含白话摘要、21 条语境解释映射、无术语输出。\n\n#### 3. AI 行动版（供给修复阶段使用）\n\n由 `reporter.py` 自动生成，包含修复清单、验证检查点、三选一步骤提示。\n\n#### 报告检查声明\n\n所有三版报告末尾必须包含检查行：\n\n```markdown\n> 本报告由 HaluCatch 生成。检查进度: [✅ HaluCatch 四维评估全部执行完毕 / ⚠️ 部分评估维度未完成]。\n```\n\n如果评估过程中有维度未覆盖（如代码工程型 Skill 但用户未提供 .py 文件），检查等级降为 ⚠️。\n\n#### AI 语义补充（在脚本报告基础上）\n\n读取脚本生成的报告后，逐条审查发现，按严重度从高到低做上下文分析：\n\n| 原评级 | AI 需要判断 |\n|--------|-----------|\n| 🔴 阻塞 | 这条风险在实际业务中到底多严重？是否真的会导致执行失败？修复优先级？ |\n| 🟠 高危 | 上下文是否真的构成风险？有没有脚本误报的可能？修复方案是否需要细化？ |\n| 🟡 提示 | 跳过项是否真的合理？有没有脚本漏掉但实际重要的风险？ |\n| 🟢 通过 | ✅ 脚本判断正确，无需补充 |\n\n输出格式：在每个发现条目下方追加一行 `> **AI 分析**: [具体判断]`。\n\n#### 报告审查前检查\n\n报告生成后、向用户展示或提交前，**必须**先检查标准版报告中是否存在 `⚠️ 疑似外部 Skill` 标记。\n\n**如存在**：不做 `present_files`，直接向用户确认：\n\n> ⚠️ 发现疑似外部 Skill 目录。`skills/` 是外部安装的 Skill（非本项目代码）吗？\n\n- 用户「是」→ 改 `config.yaml`：`skills_is_external: true`，重跑 `halucatch_core.py`\n- 用户「否」→ 改 `config.yaml`：`skills_is_external: false`，重跑 `halucatch_core.py`\n- 用户无法判断 → 保持 `null`，标注保留，继续展示\n\n确认完成并重跑后，进入 Phase 4。\n\n---\n\n### Phase 4：修复决策与闭环\n\n评估完成后，向用户展示标准版报告并询问：\n\n> 检测到 [N] 项风险。是否按建议方案修复？\n\n- **用户「修」** → 生成修复方案，然后展示三选一：\n\n  > 修复方案已生成。请选择：\n  > 1. **执行修复** — 将修复方案发给你的 AI，让它按方案修改目标 Skill\n  > 2. **不执行** — 不做任何修改，结束本次审查\n  > 3. **我有更好的意见** — 描述你的想法，我据此重新生成修复方案\n\n  - 用户选「执行」→ 提示用户让 AI 应用修复 → 提示修复后重新运行 HaluCatch 验证\n  - 用户选「不执行」→ 结束\n  - 用户选「建议」→ 重新分析追加需求 → 回到「生成修复方案」\n\n- **用户「不修」** → 结束\n\n---\n\n## 报告落盘\n\n- 缺省输出到 `reports/` 目录（目标 Skill 目录内，不污染外部路径）\n- 指定 `--output-dir` 则输出到自定义路径\n- 修复包（如有）保存到：`{Skill目录}/halucatch-fix/`\n\n---\n\n## 更多触发示例\n\n### 按审查深度\n\n| 用户说 | AI 执行动作 |\n|--------|-----------|\n| 「帮我审一下这个 Skill，看看靠不靠谱」 | 完整流程：分类 → 四维评估 → 三版报告 |\n| 「快速扫一眼，有没有明显的坑」 | 仅做 Phase 1 扫描 + Phase 2 L1/L2 规则检查，输出一份精简 checklist |\n| 「这次只关注代码有没有除零/裸 except 这种硬伤」 | 跳过规则和护栏维度，只跑地基 + 代码检查 |\n| 「上次审查后我改了 SKILL.md，帮我再跑一遍对比一下」 | 重新审查，对比上次报告，标注修复状态 |\n\n### 按 Skill 类型\n\n| 用户说 | AI 执行动作 |\n|--------|-----------|\n| 「我的 Skill 里有个 data/ 文件夹和 .py 脚本，帮我全面审」 | 分类为代码工程型，四维全覆盖 |\n| 「这是一个纯指引文档类 Skill，帮我看看指令写得清楚不清楚」 | 分类为纯方法论型，仅评估方法论和护栏 |\n\n### 路径写法（不同平台差异）\n\n| 平台 | 正确写法 | ❌ 错误写法 |\n|------|---------|-----------|\n| Claude Code / 通用 | `/path/to/skill` | `C:\\\\path\\\\to\\\\skill` |\n| Kimi / 微信小程序 | `skills/项目名/` | `~/skills/项目名/` |\n| Cursor / VS Code | 拖拽文件夹到对话框 | 手动输入复杂路径 |\n\n### 如果还是不会用\n\n> 直接说：「审查 /path/to/skill」，把 Skill 文件夹拖进来即可。AI 会自行判断接下来的步骤。不要直接贴 SKILL.md 内容——用文件夹路径保证完整性。\n\n---\n\n## 异常处理\n\n### 常见错误及修复\n\n| 错误现象 | 原因 | 修复方法 |\n|---------|------|---------|\n| `❌ 找不到 SKILL.md` | 目标目录不存在或没有 .md 文件 | 确认路径正确 → 检查目录是否有 `SKILL.md` 或其他 `.md` 文件 → 如无，创建一个 |\n| `⚠️ 未找到标准 SKILL.md` | 文件名不是 `SKILL.md`（如 `skill.md`、`README.md`） | 将文件重命名为 `SKILL.md`，或告知 AI 用 `--file` 指定文件名 |\n| `🔧 文件编码异常，已跳过 XXX.py` | 文件包含非 UTF-8 字符（如 GBK 编码的中文注释） | 用编辑器将文件另存为 UTF-8 编码（编码转换不改变内容，仅调整存储方式） |\n| `📦 Skill 包过大（> 2MB）` | 目录包含大量数据文件或依赖包 | 仅保留核心文件（SKILL.md + .py 脚本），数据文件和依赖放入 `.halucatch-ignore` |\n| `⏱️ 审查超时` | 文件过多或脚本执行时间过长 | 告知 AI：「只审查 SKILL.md 和核心 .py 文件」 |\n\n### 错误分级\n\n| 级别 | 行为 |\n|------|------|\n| **致命**（如目录不存在） | 立即终止，提供明确的修复指引 |\n| **警告**（如非标准文件名） | 继续审查但降级自检评分，在报告中标注 |\n| **可恢复**（如单个文件编码问题） | 跳过该文件继续，在报告中标注被跳过的文件及原因 |\n\n---\n\n## 运行稳定性\n\n### 防护措施\n\n| 场景 | 保护策略 |\n|------|---------|\n| 大文件（单个 > 1MB） | 截取前 500 行进行分析，在报告中声明截断 |\n| 大量文件（目录 > 200 个文件） | 按类型筛选（.md → .py → 其他），非核心文件自动跳过 |\n| 脚本执行超时（> 30s） | 终止该步骤，将已验证的部分写入报告，标注未完成项 |\n| 网络请求 | Halucatch **不发起网络请求**，100% 离线运行 |\n| 编码问题 | 先尝试 UTF-8 → 再尝试系统 locale → 失败则跳过并记录 |\n| 目录不可读 | 报告权限错误，建议用户 `chmod` 或换个路径 |\n\n### 可靠性声明\n\n> Halucatch 在正常 Skill 目录（≤ 50 个文件，单文件 ≤ 1MB）上运行稳定。极端情况会自动降级（截断/跳过/终止），不会静默失败。\n\n---\n\n## 反模式与 FAQ\n\n### 常见误区\n\n| 误区 | 正确认知 |\n|------|---------|\n| 「审查一次就够了」 | Skill 每次修改后都应重新审查，尤其是修改 SKILL.md 或关键 .py 文件后 |\n| 「分数低 = 不能用」 | 分数是相对参考。一个「地基弱但规则清晰」的纯方法论型 Skill 可能完全可用 |\n| 「修完所有问题才发布」 | 优先修高优（🔴）和中优（🟠）项，低优项可以渐进改进 |\n| 「AI 行动版报告可以直接执行」 | 行动版是给 AI 的修复指令，需用户确认后再让 AI 执行，防止误改 |\n| 「用 `--validate` 模式跑过就算审查了」 | `--validate` 只做文件扫描和类型分类，不做四维评估。正式审查必须完整跑 |\n\n### FAQ\n\n**Q：我需要准备什么？**\nA：一个包含 `SKILL.md` 的文件夹。如果有 `.py` 脚本或数据文件，一并放入可以评估得更全面。\n\n**Q：审查结果说不通过，我该怎么办？**\nA：看报告中的「AI 行动版」，里面有逐项修复方案。按优先级从高到低修，修完再审查一次验证。\n\n**Q：我的 Skill 没有 Python 代码，能用吗？**\nA：能。HaluCatch 会自动分类为「纯方法论型」，跳过地基和代码检查，重点评估指令完备性和护栏。\n\n**Q：遇到报错怎么办？**\nA：看上方「异常处理」章节。90% 的报错是路径写错或文件名不规范。如果解决不了，把报错信息贴给 AI。\n\n> 💡 **更多问题？** 查看 `FAQ.md`——包含完整的使用指南、常见问题和故障排除。\n\nFile v1.8.5:halucatch/README.md\n\nHaluCatch 模块化拆分 — 设计决策说明\n\n## 目录结构\n\nhalucatch/                    # 核心包\n├── __init__.py               # 导出版本和核心 API（~15 行）\n├── config.py                 # MESSAGES + detect_system_locale（~218 行）\n├── scanner.py                # scan_folder + _extract_version + _strip_string_literals（~166 行）\n├── classifier.py             # classify_skill（~16 行）\n├── evaluators/               # 四维评估 + 自检\n│   ├── __init__.py           # 聚合导出（~30 行）\n│   ├── foundation.py         # check_foundation（~72 行）\n│   ├── code_risks.py         # check_code_risks（~56 行）\n│   ├── rules.py              # check_rules（~85 行）\n│   ├── guardrails.py         # check_guardrails（~133 行）\n│   └── methodology.py        # check_methodology（~66 行）\n├── reporter.py               # generate_report（~262 行）\n├── cli.py                    # parse_args + main（~88 行）\nhalucatch_core.py             # 向后兼容入口（~30 行，导入 cli.main）\n\n## 设计原则\n\n1. **零依赖**：所有模块仅使用 Python 标准库，不引入外部包。\n2. **单一职责**：每个模块对应一个功能边界，模块内高内聚。\n3. **AI 可复现**：单文件控制在 200 行以内，AI 可以完整理解每个模块。\n4. **向后兼容**：halucatch_core.py 保留，所有现有用法不受影响。\n5. **可扩展**：新增评估维度时，只需在 evaluators/ 下新建文件，evaluators/__init__.py 注册即可。\n\n## 依赖关系\n\n```\ncli.py → reporter.py → evaluators/__init__.py → config.py\n             ↑                        ↑\n          scanner.py               classifier.py\n```\n\n所有模块都依赖 config.py（MESSAGES）。\nscanner.py 和 classifier.py 无依赖。\nreporter.py 依赖所有 evaluators 和 scanner 输出。\ncli.py 是入口，协调所有模块。\n\nFile v1.8.5:README.md\n\n# HaluCatch / 捕幻\n\n<p align=\"center\">\n  <a href=\"README.md\">\n    <img src=\"https://img.shields.io/badge/语言-中文-blue?style=for-the-badge\" alt=\"中文\">\n  </a>\n  <a href=\"README.en.md\">\n    <img src=\"https://img.shields.io/badge/Language-English-slategray?style=for-the-badge\" alt=\"English\">\n  </a>\n</p>\n\nAI Skill **执行可靠性审查**工具。评估一个 Skill 被 AI 执行时，结果是否可信、是否可复现、是否经得起业务推敲。\n\n> **Halu** = Hallucination（幻觉） | **Catch** = 捕获\n\n🌐 **在线站点**：[codermoray.github.io/HaluCatch](https://codermoray.github.io/HaluCatch/) — 交互式流程图、FAQ、版本更新一览。\n\n---\n\n## 动机\n\nAI 执行 Skill 时，最常见的问题不是「不会做」，而是**以为自己会做但做错了**。原因有三：\n\n1. **地基不稳** — 数据路径写死、格式未验证、没有骨架脚本\n2. **规则歧义** — 自然语言描述的业务逻辑能被多种理解\n3. **缺解读护栏** — AI 产出自信的错误结论，用户无从分辨\n\nHaluCatch 扫描一个 Skill 包，从地基/代码/规则/护栏四维度给出评级与修复建议。\n\n---\n\n## 执行流程\n\n> 完整流程见 [在线流程图](https://codermoray.github.io/HaluCatch/decision-flowchart.html)。\n\n---\n\n## 快速开始\n\n两种调用方式，底层同一套引擎：\n\n### 对话中调用（推荐）\n\n对 AI 说出目标 Skill 路径即可，AI 自动跑脚本、做评估、出报告：\n\n```\n请用 HaluCatch 审查这个 Skill：/path/to/target-skill\n```\n\n审查完成后，当前目录 `reports/` 下生成三份报告：\n\n```\nreports/\n├── HaluCatch-report-2026-06-17.md           ← 专业版（工程人员）\n├── HaluCatch-report-2026-06-17-标准版.md      ← 标准版（业务方）\n└── HaluCatch-report-2026-06-17-行动版.md      ← 修复指引\n```\n\n| 版本 | 目标读者 | 内容 |\n|------|---------|------|\n| 专业版 | 工程人员 | 逐项检查结果 + 分数 + 修复建议 |\n| 标准版 | 业务方 | 白话 paraphrase，无术语 |\n| 行动版 | 下次执行的 AI | 修复指引 + 验证检查点 |\n\n**示例 — 审查一个代码工程型 Skill：**\n\n```\n请用 HaluCatch 审查 ~/.workbuddy/skills/xlsx，看这个操作表格的 Skill 稳不稳\n```\n→ 发现：字符串拼接路径、写入模式未警告覆盖、除法未保护。评级：地基 🟢 稳固，代码 🟠 有风险，护栏 🟡 缺项。\n\n**示例 — 审查一个纯方法论型 Skill：**\n\n```\n请用 HaluCatch 审查 ~/.workbuddy/skills/find-skills，看指令够不够清楚\n```\n→ 发现：结构化步骤完整、条件分支信号良好（清单 13 项/图标 7）。评级：方法论 🟢 可靠，护栏 🟡 缺项 3/5。\n\n> `find-skills` 是 Skill 生态中的搜索工具，详见 [vercel-labs/skills](https://github.com/vercel-labs/skills)。\n\n审查完成后 AI 会询问是否按方案修复，详见 [在线流程图](https://codermoray.github.io/HaluCatch/decision-flowchart.html)。\n\n---\n\n## 文件结构\n\n```\nHaluCatch/\n├── SKILL.md                  ← 流程指令（AI 读）\n├── halucatch_core.py         ← 向后兼容入口（14 行，导入 halucatch 包）\n├── halucatch/                ← 核心包（11 个模块，零依赖）\n│   ├── __init__.py\n│   ├── config.py             ← MESSAGES 双语字典 + 语言检测\n│   ├── scanner.py            ← 文件扫描 + 版本号提取\n│   ├── classifier.py         ← Skill 类型判定\n│   ├── evaluators/           ← 四维评估 + 方法论\n│   │   ├── __init__.py\n│   │   ├── foundation.py     ← 地基评估（路径/校验/依赖）\n│   │   ├── code_risks.py     ← 代码风险扫描（篡改点）\n│   │   ├── rules.py          ← 规则评估（口径/边界/模糊）\n│   │   ├── guardrails.py     ← 护栏评估（安全/禁止/误用）\n│   │   └── methodology.py    ← 方法论评估（步骤/分支/错误处理）\n│   ├── reporter.py           ← 三版报告生成器\n│   └── cli.py                ← 命令行入口 + 流程协调\n├── README.md                 ← 项目说明\n├── scripts/                  ← 发布/构建脚本\n│   ├── release.sh            ← 一键发布（8 步自动流程）\n│   ├── build-skillhub.sh     ← SkillHub 包构建\n│   ├── generate-changelog.sh ← 自动生成 CHANGELOG\n│   └── bump-version.sh       ← 版本号升级\n├── docs/\n│   ├── CHANGELOG.md\n│   ├── FAQ.md\n│   ├── decision-flowchart.html\n│   └── decision-flowchart-prompt.md\n├── tests/\n│   ├── __init__.py\n│   └── test_halucatch.py     ← 24 个单元测试\n├── cliff.toml                ← git-cliff Changelog 配置\n└── .gitignore\n```\n\n---\n\n## 多语言支持\n\nHaluCatch 支持中文（简/繁）和英文输出，根据用户语言自动切换：\n\n```bash\n# 自动检测（默认，推荐）\npython3 halucatch_core.py --skill-dir /path/to/skill\n\n# 强制中文输出\npython3 halucatch_core.py --skill-dir /path/to/skill --lang zh-CN\n\n# 强制英文输出\npython3 halucatch_core.py --skill-dir /path/to/skill --lang en\n```\n\n**AI 使用场景**：AI 从 `<response_language>` 判断用户语言，自动传 `--lang` 参数，无需用户手动配置。详见 [SKILL.md](SKILL.md) 中的「AI 执行指南」。\n\n---\n\n## 四维评估框架\n\n| 维度 | 检查什么 | 类型 |\n|------|---------|------|\n| 🏗️ **地基** | 数据管线是否稳固（.py/路径/validate） | 代码化扫描 |\n| 🤖 **代码** | 代码质量风险（路径拼接/静默覆盖/超时缺失/除零等） | 代码化扫描 |\n| 📝 **规则** | 业务口径有无歧义（映射/分类/边界） | AI 判断 |\n| 🛡️ **护栏** | 解读规则是否到位（禁令/框架/自检） | AI 判断 |\n\n前三项可靠，第四项需要目标 Skill 作者自觉配合。\n\n> **跨语言设计**: 方法论和护栏检查不使用关键词正则，而是通过结构信号密度\n> （条件清单行数、警示图标数、表格数、否定词密度）跨语言评估分支覆盖和护栏完整度。\n> 中文「如果…则…」和英文「REJECT IMMEDIATELY IF」都能正确识别。\n\n> **分层策略**: 代码工程型 Skill 细分为三档——分析型（全 8 项护栏，含数据来源/时效性/置信度）、工具库型（精简 5 项）、纯方法论型（精简 5 项）。避免对 xlsx/pptx 等工具库 Skill 检查不必要的「数据时效性/来源」项。\n\n---\n\n## 同类项目对比\n\nSkill 审查赛道目前仅四个工具，各自切不同的角度：\n\n| | HaluCatch | skill-vetter | SkillGuard | skill-sharpener |\n|---|---|---|---|---|\n| 切面 | **执行可靠性（工程）** | 安全审查（红队） | 全生命周期守护 | 文案质量（最佳实践） |\n| 检查什么 | 数据管线/代码风险/业务规则/解读护栏 | 恶意行为/权限范围/源可信度 | 安装前审查+发布前安检+安装后体检 | 触发描述/结构/简洁度 |\n| 评估方式 | 脚本基线 + AI 语义 | 纯 AI 按协议逐项检查 | AI + 规则引擎 | 纯 AI 按 checklist 打分 |\n| 输出 | 三版报告 + 修复方案 + 闭环 | SAFE/CAUTION/REJECT 判定 | 风险报告 + 自动修复 | 优化建议报告 |\n| 通用性 | ✅ 中/英/日/表格均适用 | ✅ 英文为主 | ✅ 中英文 | 🟡 依赖 AI 理解能力 |\n| 闭环 | ✅ 行动版含修复指引 + 验证检查点 | ❌ | ✅ 含自动修复 | ❌ |\n| skills.sh | — | **19.6K** | ❌ 未上榜 | ❌ 未上榜 |\n| 平台评分 | — | ★3.690 (clawhub) | v4.2.0 (skillhub) | ★3.607 (clawhub) |\n\n**HaluCatch 的独特优势**：\n1. **唯一有骨架脚本的工具** — `halucatch_core.py` 提供可复现的基线检查，不依赖 AI 主观判断\n2. **唯一含修复闭环** — 三版报告 + Phase 4 修复决策 + 验证检查点，形成「发现→修复→验证」完整链路\n3. **唯一跨语言** — 结构信号（清单/图标/表格/否定词密度）替代语义关键词，不绑定特定语言\n4. **唯一分层护栏** — 按 Skill 类型（分析型/工具库型/方法论）自动调整检查范围，避免误报\n5. **赛道蓝海** — skills.sh 前 287 名中，Skill 审查工具仅 skill-vetter 上榜（19.6K），执行可靠性方向尚无竞品\n\n---\n\n## 开发\n\n```bash\ngit clone https://github.com/CoderMoray/HaluCatch.git\ncd HaluCatch\n# 编辑 SKILL.md 或 halucatch_core.py\ngit commit -m \"your change\"\ngit push\n```\n\n### 引擎调试\n\n`halucatch_core.py` 是向后兼容入口，实际逻辑在 `halucatch/` 包中：\n\n```bash\n# 向后兼容入口\npython3 halucatch_core.py --skill-dir /path/to/skill               # 完整评估（自动检测语言）\npython3 halucatch_core.py --skill-dir /path/to/skill --validate    # 仅扫描\npython3 halucatch_core.py --skill-dir /path/to/skill --lang en     # 强制英文输出\n\n# 包方式（等价）\npython3 -m halucatch --skill-dir /path/to/skill\n```\n\n> 日常使用通过 AI Skill 调用即可，无需手动跑脚本。\n\n---\n\n## 测试\n\n```bash\npytest tests/ -v    # 24 个用例全部通过\n# 或直接运行测试模块\npython3 tests/test_halucatch.py\n```\n\n已对 10 个不同类型 Skill 完成实战验证：\n\n| Skill | 类型 | 护栏 |\n|-------|------|------|\n| find-skills / agent-browser / edgeone-deploy | 方法论 | 🟡 缺项 3/5 |\n| xlsx / pptx | 工具库型 | 🟡 缺项 3/5 |\n| skill-sharpener (ClawHub) | 分析型 | 🟡 缺项 5/8 |\n| neodata-financial-search | 分析型 | 🟢 到位 7/8 |\n| data-validation | 嵌入式 Python | 🟡 缺项 5/8 |\n| HaluCatch (自审查) | 代码工程 | 🟢 到位 8/8 |\n\n---\n\n## 常见问题\n\n**Q: HaluCatch 需要联网吗？**\nA: 不需要。全程离线运行，仅扫描本地文件夹中的 SKILL.md 和 .py 文件。\n\n**Q: 我的 Skill 没有 .py 文件，能用吗？**\nA: 可以。HaluCatch 会自动分类为「纯方法论型」并跳过地基/代码检查，只评估方法论和护栏。\n\n**Q: 审查结果说「护栏薄弱」，怎么修？**\nA: 看同目录下的 `-行动版.md` 报告，它包含具体修复方案和验证检查点。\n\n**Q: 为什么工具库型 Skill 的护栏分数比分析型低？**\nA: 护栏检查按类型分层——工具库型只查 5 项核心项（跳过不必要的数据来源/时效性检查），分母不同，分数不可直接比较。\n\n**Q: 审查结果能自动修复吗？**\nA: 不能。HaluCatch 是诊断工具，不是自动修复工具。行动版报告提供修复指引，但修改需要你（或 AI）手动执行。\n\n**Q: 能一次审查多个 Skill 吗？**\nA: 当前版本暂不支持批量模式。你可以逐个运行，批量功能已在 roadmap 中。\n\n**Q: 出现「网络问题卡住」是 HaluCatch 的问题吗？**\nA: 不是。HaluCatch 是纯本地工具，不走网络。如果执行卡住，大概率是 AI 对话环境超时或目标路径过大导致扫描耗时。\n\n**Q: 怎么快速上手？**\nA: 3 步——1. 跑一次审查看标准版了解问题；2. 打开行动版按清单逐项修复；3. 修复后重新审查验证改善。\n\n**Q: 出现文件编码错误怎么办？**\nA: HaluCatch 以 UTF-8 读取文件。非 UTF-8 编码（如 GBK）会保留原始字节转义标记，不会静默丢数据。\n\n**Q: 「Phase 4 闭环」怎么用？**\nA: 审查完成后选「执行修复」→ 方案发给 AI 实施 → 重新审查验证。或选「我有更好建议」→ 描述想法 → 重生成方案。\n\n---\n\n---\n\n## 常见报告解读\n\n| 看到这个 | 实际含义 | 怎么办 |\n|---------|--------|--------|\n| 🔴 无固化 .py 脚本 | 没有独立 Python 文件，AI 每次执行都要从头写代码 | 把核心逻辑抽取为 .py 骨架脚本 |\n| 🟠 缺少输入验证 | 没有检查输入数据格式/列名，格式漂移时可能错位 | 添加 `check_columns()` 或 `--validate` 模式 |\n| 🟡 检查跳过 | 这项检查对此类 Skill 不适用，不是扣分 | 无需处理 |\n| 🟡 未检测到禁止操作 | SKILL.md 里没写「不要/禁止/切勿」类约束 | 在 SKILL.md 里声明 AI 不能做的事 |\n| 🟠 嵌入代码 XX 行 | .py 文件较大，AI 复现时可能遗漏细节 | 考虑拆分为多个小文件 |\n| 🟡 info 级别 | 供 AI 确认的提示，不影响评分 | 看一遍确认即可，不用改 |\n\n## 许可\n\nMIT\n\nFile v1.8.5:_meta.json\n\n{\n  \"ownerId\": \"kn74hb96rgc7bpqt7m16rvn3h188ehj7\",\n  \"slug\": \"halucatch\",\n  \"version\": \"1.8.5\",\n  \"publishedAt\": 1783787662827\n}\n\nFile v1.8.5:CHANGELOG.md\n\n# Changelog\n\n本文档记录 HaluCatch 项目的所有 notable changes。\n\n版本号规则：\n- **中间版本号** (1.x.0)：新功能或架构级变更\n- **小版本号** (1.0.x)：修复、增强、chore 等小更新\n- **每个 commit 对应一个版本更新**\n\n---\n\n## [Unreleased]\n\n\n### Fixed\n\n- 注释里也不留 eval(，彻底清除静态分析误报\n- 响应 SkillSpector 5 条发现，强化文档安全声明\n\n---\n\n## [V1.8.0] - 2026-07-11\n\n### Added\n- **第五维度：复杂度评估** — 新增 11 项指标（章节深度、引用链、重复冗余、表格复杂度、脚本覆盖比、代码/文档比、指令密度等），综合评分 0-10 分\n- **脚本覆盖率折扣** — `最终 = 加权 × (1 − √覆盖率)`，边际递减：第一个脚本降幅最大\n- **Skills 外部目录检测** — `config.yaml` 新增 `skills_is_external` 字段，null 时标注 ⚠️ 疑似外部 Skill，true 时跳过扫描\n- **代码风险检测多语言** — 支持 Shell / Go / JS / Ruby / Rust / Perl / TS，按语言分组统计\n- **Shell 受保护上下文** — 函数体内 `$1`/`$2` 和 `while $#` 参数解析循环自动跳过，消除 参数缺失 误报\n- **护栏新增 3 项** — 输出稳定性检测（模板文件）、擅自做主检测、静默吞错检测\n- **输出确定性增强** — Python 函数名兜底 + 模板文件检测双保险\n- **复杂度三行汇总表** — 加权总得分 / 脚本覆盖率折扣 / 最终复杂度，含 KaTeX 公式\n- **pre-push hook** — push 前自动运行 pytest + ruff\n\n### Changed\n- **emoji 重命名**：代码维度 🤖→💻，代码风格提示→其他提示，乘数→折扣\n- **标准版报告精简**：复杂度细节不入标准版，info 级别项移至专业版\n- **SKILL.md 流程优化**：AI 按需读文件而非全局扫描、报告生成后强制检查 ⚠️ 标记\n- **报告输出路径**：默认改为 Skill 文件夹内 `reports/`\n- **代码/文档比分级**：6 级细化，幽默标签（\"你这是代码仓库啊，兄弟\"）\n- **网站重建**：五维宣传页、Demo 上移、全局滚动动画、preview 用真实自审查数据\n\n### Fixed\n- 模糊词列表删除\"通常\"（性能描述非歧义）\n- `bump-version.sh` 漏更新 `__init__.py`\n- `_instruction_density()` 死代码残留（L424-428）\n- 未捕获 Promise 检测改为两步验证\n- `mktemp` 误报（`set -e` 下 `|| true` 是标准写法）\n- 超长行从 warn 降级为 info\n- Shell 参数缺失排除 `$0` 和 `default` 模式\n- 代码/文档比公式反转，改为文档占比\n- 网站 overscroll 暗色背景修复、`>` 标签残留修复\n\n## [V1.7.1] - 2026-06-28\n\n### Fixed\n- **高优先级代码修复**\n  - `except:` → `except Exception:`（防吞系统级异常）\n  - `score / total` → `score / max(total, 1)`（3处，防除零崩溃）\n  - `check_code_risks` 字符串/注释误扫描 → 预处理移除字面量后再正则匹配\n- **中优先级文档修复**\n  - 报告文件名含版本号，冲突时自动加序号（`-1`、`-2`...）\n  - SKILL.md 新增\"数据要求\"章节（时效性 + 前提假设）\n  - 移除 `ToolCard.md` 认知污染，规范化为 `SKILL.md`\n- **低优先级架构重构**\n  - 1191 行 `halucatch_core.py` 拆分为 11 个模块，单文件 ≤270 行\n  - 新增 `halucatch/` 包：`config`, `scanner`, `classifier`, `evaluators/`, `reporter`, `cli`\n  - 保留 `halucatch_core.py` 向后兼容入口\n\n### Added\n- **版本号自动提取**：从 `_meta.json` / `meta.json` / 任意 `.md` frontmatter\n- **无 SKILL.md 替代机制**：启发式匹配（frontmatter 优先 + 文件大小），报告规范性问题后继续工作\n- **无 .md 文件严格拒绝**：直接报错，拒绝非标准 Skill 目录\n- **测试覆盖**：新增 3 个扫描测试，总计 24 个测试全部通过\n\n### Changed\n- `build-skillhub.sh` / `check-file-size.sh` / `release.yml` / `manifest.json` 适配新包结构\n\n---\n\n## [V1.7.0] - 2026-06-26\n\n### Added\n- feat: **英文 Skill 支持增强**\n  \n  **跨语言检测能力扩展:**\n  - 新增英文模糊词检测（18 个词）: `roughly`, `approximately`, `about`, `usually`, `generally` 等\n  - 新增英文单位检测: `USD`, `EUR`, `GBP`, `million`, `billion`, `percent`, `percentage`, `pct`\n  - 增强英文禁止声明检测: `MUST NOT`, `FORBIDDEN`, `PROHIBITED`, `DO NOT`\n  - 增强工具库/分析型识别信号词\n  \n  **影响**: halucatch_core.py (`check_rules`, `_prohibition_signal`, `_is_tool_skill`)\n  - 提交: `待提交`\n\n---\n\n## [V1.6.0] - 2026-06-17\n\n### Added\n- feat: **数据驱动型护栏分层** — 工具库 vs 分析型双档评分\n  \n  **护栏分层架构重构:**\n  - `check_guardrails` 集成 `_is_tool_skill()` 分支\n  - **工具库型**: total=5, 跳过置信度/数据来源/时效性检查\n  - **分析型**: total=8, 全查\n  - **方法论**: total=5, 保持不变\n  \n  **测试增强:**\n  - 新增 `test_guardrails_tool_type` 测试用例\n  - 21/21 通过，xlsx/pptx 3/5, neodata 7/8\n  \n- 影响: halucatch_core.py (52 行修改), tests/test_halucatch.py (18 行新增)\n- 提交: `f445999`\n\n---\n\n## [V1.5.1] - 2026-06-17\n\n### Changed\n- chore: 忽略 .clawhub 目录\n- 影响: .gitignore (1 行)\n- 提交: `768d725`\n\n---\n\n## [V1.5.0] - 2026-06-17\n\n### Added\n- feat: **去语言化架构重构** — 结构化信号替代语义关键词正则\n  - `_branch_density()`: 清单/图标/表格密度 → 跨语言分支检测\n  - `_prohibition_signal()`: 否定词/大写警告/中文禁止 → 跨语言护栏检测\n  - `check_methodology` 末尾加 AI 免责声明\n  - 测试更新: 两组用例内容补信号结构\n- 影响: halucatch_core.py (51 行修改), tests/test_halucatch.py (4 行), 新增文档 144 行\n- 提交: `baaaaa2`\n\n---\n\n## [V1.4.1] - 2026-06-17\n\n### Added\n- feat: Phase 4 闭环 SOP 实现 — 三选一交互 + 行动版 prompt\n  - SKILL.md Phase 4: 修复 → 用户三选一 (执行/不执行/建议) 详细 SOP\n  - halucatch_core.py: 行动版报告追加三选一步骤提示\n- 影响: SKILL.md (21 行), halucatch_core.py (8 行)\n- 提交: `65631d4`\n\n---\n\n## [V1.4.0] - 2026-06-17\n\n### Added\n- feat: **闭环验证流程** — 用户选择? + AI按方案修复 + 重新审查回路\n  - 决策流程图新增修复验证闭环\n  - 用户选择? (3分支): 执行 → AI 修复 → 重新审查 | 不执行 → 结束 | 建议 → 回环\n  - SKILL.md / README Mermaid / HTML SVG 三处同步\n  - 视觉优化：汇聚箭头修正、间距扩大、标签对齐\n- 影响: README.md, SKILL.md, docs/decision-flowchart.html, docs/decision-flowchart-prompt.md (新增 75 行)\n- 提交: `856f682`\n\n---\n\n## [V1.3.1] - 2026-06-17\n\n### Changed\n- chore: 清理过期测试文档\n- 影响: 删除 4 个文档文件 (451 行)\n  - docs/HaluCatch-expansion-plan-2026-06-17.md\n  - docs/HaluCatch-optimization-report-2026-06-17.md\n  - docs/HaluCatch-readme-update-checklist-2026-06-17.md\n  - docs/HaluCatch-test-report-2026-06-17.md\n- 提交: `a2895f7`\n\n---\n\n## [V1.3.0] - 2026-06-17\n\n### Added\n- feat: **代码风险去金融化 + 边界测试 + 护栏分层**\n  \n  **代码风险检测增强:**\n  - 移除写死变量名的 3 个 pattern（p_pool/p_val, math.exp, store_weeks）\n  - 新增 4 个通用 pattern：浮点(任意==0.0), 除零(return 除法), 路径拼接, 静默覆盖, 超时缺失\n  - 模式库从 5 个扩展到 7 个\n  \n  **扫描功能改进:**\n  - `scan_folder` 改为 `os.walk` 递归扫描，支持子目录 .py\n  - 文件清单加 `rel_path` 字段（精确路径匹配）\n  - 返回值加 `py_count` / `max_py_lines`（避免拼接行数虚高）\n  \n  **护栏分层:**\n  - `check_guardrails` 按 `skill_type` 分层：methodology 跳过 3 项无用检查\n  - 默认输出到 `HaluCatch/reports/`，不污染目标 Skill 目录\n  \n  **测试增强:**\n  - 16 → 20 用例，新增 4 个边界测试（空目录/只有SKILL.md/只有.py/深层嵌套）\n  - 全部通过\n  \n  **文档同步:**\n  - README 三维→四维、用例更新、护栏分层说明、测试章节\n  - docs/ 补充专家出具的 4 份报告\n- 影响: halucatch_core.py, tests/test_halucatch.py, README.md, SKILL.md, 新增 5 个文档\n- 提交: `bd76b90`\n\n---\n\n## [V1.2.1] - 2026-06-17\n\n### Changed\n- feat: 更新 .gitignore，添加 .workbuddy 目录排除\n- 影响: .gitignore (1 行)\n- 提交: `50a8780`\n\n---\n\n## [V1.2.0] - 2026-06-17\n\n### Added\n- refactor: **P0-P3 全面修复** — 角色声明/三层调用/四维评估骨架/测试\n  \n  **P0 修复:**\n  - SKILL.md 添加 AI 角色声明\n  - 三层调用分工表\n  - 执行决策流程图\n  \n  **P1 修复:**\n  - 修复 `check_foundation` skip/warn 混淆\n  - 修复 `methodology` 自洽逻辑\n  - 修复 `report info` 隐藏\n  \n  **P2 实现:**\n  - 实现 `check_rules()` (6项) 骨架函数\n  - 实现 `check_guardrails()` (8项) 骨架函数\n  \n  **P3 测试:**\n  - 新增 `tests/` (16 用例)\n  - 新增 `docs/` (流程图) 目录\n  - 补充 .gitignore\n- 影响: 7 个文件变更, 731 行新增, 30 行删除\n- 提交: `813d84e`\n\n---\n\n## [V1.1.0] - 2026-06-16\n\n### Added\n- feat: **核心实现** — 添加 halucatch_core.py 和 README\n  - `halucatch_core.py`: 504 行核心代码\n  - `README.md`: 99 行项目说明\n- 影响: 新增 2 个文件, 603 行\n- 提交: `952f26b`\n\n---\n\n## [V1.0.0] - 2026-06-16\n\n### Added\n- feat: **初始版本** — HaluCatch SKILL.md\n  - AI Skill 可靠性检查器核心设计文档\n  - 231 行 SKILL.md\n  - 基础 .gitignore\n- 影响: 新增 2 个文件, 235 行\n- 提交: `ad24145`\n\n---\n\n## 版本统计\n\n| 版本 | 发布日期 | 提交哈希 | 类型 | 影响范围 | 说明 |\n|------|----------|----------|------|----------|------|\n| V1.6.0 | 2026-06-17 | `f445999` | feat | 核心代码 + 测试 (60行) | 数据驱动型护栏分层 |\n| V1.5.1 | 2026-06-17 | `768d725` | chore | .gitignore (1行) | 忽略 .clawhub 目录 |\n| V1.5.0 | 2026-06-17 | `baaaaa2` | feat | 核心代码 + 测试 | 去语言化架构 |\n| V1.4.1 | 2026-06-17 | `65631d4` | feat | SKILL.md + 核心 | Phase 4 闭环 SOP |\n| V1.4.0 | 2026-06-17 | `856f682` | feat | 文档 + 流程图 | 闭环验证流程 |\n| V1.3.1 | 2026-06-17 | `a2895f7` | chore | 删除 4 个文档 | 清理过期测试文档 |\n| V1.3.0 | 2026-06-17 | `bd76b90` | feat | 核心 + 测试 + 文档 | 代码风险检测增强 |\n| V1.2.1 | 2026-06-17 | `50a8780` | feat | .gitignore (1行) | 更新 gitignore |\n| V1.2.0 | 2026-06-17 | `813d84e` | refactor | 7 个文件, 731 行 | P0-P3 全面修复 |\n| V1.1.0 | 2026-06-16 | `952f26b` | feat | 2 个文件, 603 行 | 核心实现 |\n| V1.0.0 | 2026-06-16 | `ad24145` | feat | 2 个文件, 235 行 | 初始版本 |\n\n**总计：12 个版本（11 次提交）**\n\n---\n\n## 分类统计\n\n### 按提交类型\n- **feat**: 8 次 (73%)\n- **refactor**: 1 次 (9%)\n- **chore**: 2 次 (18%)\n\n### 按版本号规则\n- **中间版本更新** (1.x.0): 7 次 (功能级更新)\n  - V1.1.0: 核心实现\n  - V1.2.0: 架构重构\n  - V1.3.0: 代码风险检测\n  - V1.4.0: 闭环验证\n  - V1.5.0: 去语言化\n  - V1.6.0: 数据驱动型护栏分层\n  \n- **小版本更新** (1.0.x): 4 次 (修复/增强/chore)\n  - V1.2.1: gitignore 更新\n  - V1.3.1: 清理文档\n  - V1.4.1: SOP 实现\n  - V1.5.1: 忽略目录\n\n### 代码变更统计\n- **总代码行数**: 235 + 603 + 731 + ... ≈ 2000+ 行\n- **平均每次提交**: ~200 行\n- **最大单次变更**: V1.2.0 (731 行新增)\n\n---\n\n**生成时间**: 2026-06-17  \n**生成方式**: 基于 `git log` + `git diff-tree` 分析实际代码变更\n\nFile v1.8.5:FAQ.md\n\n# HaluCatch / 捕幻 — 常见问题\n\n---\n\n## 基础\n\n**Q: HaluCatch 需要联网吗？**\n\n不需要。全程离线运行，仅扫描本地文件夹中的 SKILL.md 和 .py 文件，不会发起任何网络请求。如果执行卡住，大概率是 AI 对话环境超时或目标路径文件过多导致扫描耗时。\n\n---\n\n**Q: HaluCatch 怎么用？**\n\n对 AI 说「帮我用 HaluCatch 审查 /path/to/skill」即可。AI 会先确认目标路径无误，再开始扫描评估。为避免误操作，请确保指定的路径是希望审查的 Skill 目录，不要指向系统目录或 home 目录。3 步上手：\n\n1. 跑一次审查 → 看标准版报告了解问题\n2. 打开 `-行动版.md` → 从列表第一条开始逐项修复\n3. 修复后重新跑 → 对比分数是否改善\n\n---\n\n## 使用场景\n\n**场景 1：发布前自审**\n\n你要把写好的 Skill 发布到 ClawHub / SkillHub，想确保它在别人机器上也能正常工作。\n\n跑一次全维度审查。重点看标准版报告的「地基」和「代码风险」——硬编码路径、裸 except、虚构命令是最高频的坑。改完后跑第二次验证分数提升。\n\n**场景 2：接手别人的 Skill**\n\n别人写的 Skill 文档很长，你不敢直接给 AI 执行，怕出问题。\n\n跑一次审查，直接看「行动版报告」——它把每个问题拆成「现状 → 风险 → 修复方案 → 验证方法」，照着改就行，不用通读原始 SKILL.md。\n\n**场景 3：CI 自动检查**\n\n你在维护 Skill 仓库，想每次改代码时自动检查质量不退化。\n\n```bash\npython3 -m halucatch --skill-dir . --validate    # 快速扫描文件清单\npython3 -m halucatch --skill-dir . --output-dir ./ci-reports  # 完整审查出报告\n```\n\n在 CI 里集成，每次 PR 确保分数不下降。\n\n---\n\n## 能力边界\n\n**能做什么：**\n- ✅ 扫描 SKILL.md 和关联 .py 文件，检查执行可靠性\n- ✅ 识别硬编码路径、裸异常处理、虚构命令等 7 类代码风险\n- ✅ 评估业务规则歧义和护栏完整度\n- ✅ 自动识别中英文，输出对应语言报告\n- ✅ 生成标准版/专业版/行动版三份报告\n\n**不能做什么：**\n- ❌ 不联网 —— 不访问任何 API，不下载文件\n- ❌ 不查安全漏洞 —— SQL 注入、XSS、恶意指令交给 ClawHub SkillSpector\n- ❌ 不批量处理 —— 一次一个目录\n- ❌ 不代替人工决策 —— 报告是建议，最终你拍板\n\n**硬性限制：**\n- 📏 单文件 > 10 MB 会被跳过并提示\n- 📁 不支持二进制文件\n- ⏱️ 处理时间取决于文件数量和大小，通常 1-60 秒\n\n---\n\n**Q: 我的 Skill 没有 .py 文件，能用吗？**\n\n可以。HaluCatch 会自动分类为「纯方法论型」并跳过地基/代码检查，只评估方法论结构和护栏完整度。\n\n---\n\n## 报告\n\n**Q: HaluCatch 会在电脑上写文件吗？**\n\n会。审查完成后自动在 `HaluCatch/reports/` 目录生成三份报告（标准版、专业版、行动版 .md 文件）。不会修改目标 Skill 目录中的任何文件。如需自定义输出路径，使用 `--output-dir` 参数。\n\n**Q: 审查结果长什么样？**\n\n标准版报告示例（白话、零术语，给非技术用户看）：\n\n```\n# HaluCatch 审计报告 — my-skill\n\n## 📌 一句话总结\n\n🟢 3 通过 · ⚠️ 2 注意 · 💡 3 可优化\n\n## 🎯 核心结论\n\n| 地基 | 代码 | 规则 | 护栏 | 复杂度 |\n|:--:|:--:|:--:|:--:|:--:|\n| 🟢 稳固 6/6 | 🟢 干净 90/90 | 🟡 有歧义 4/6 | 🟢 到位 11/11 | 🟡 注意 2.2/10 |\n\n### 做的不错 👍\n- ✅ 有固化脚本兜底核心任务\n\n### 需要注意的方面\n- ⚠️ 存在模糊表述 ['大概']（说明书写了模糊词，AI 可能会猜错）\n```\n\n包含专业版（11 项指标表 + KaTeX 公式）和行动版（修复清单）。完整示例：运行 `python3 halucatch_core.py --skill-dir .` 审自己的项目。\n\n---\n\n**Q: 审查结果说「护栏薄弱」，怎么修？**\n\n看同目录下的 `HaluCatch-report-日期-行动版.md`，它逐条列出了修复方案和验证检查点。按清单逐项改即可，改完后重新审查验证。\n\n---\n\n**Q: 为什么工具库型 Skill 的护栏分数看起来比分析型低？**\n\n护栏检查按类型分层——工具库型只查 5 项核心项（跳过数据来源/时效性/置信度），分析型查全 8 项。分母不同，分数不可直接比较。\n\n---\n\n**Q: 报告里看到的版本号是什么意思？**\n\n报告日期是生成当天，版本号跟随 HaluCatch 自身版本。同一个 Skill 在不同版本 HaluCatch 下的评分可能不同——因为检测规则在持续改进。\n\n---\n\n**Q: 能一次审查多个 Skill 吗？**\n\n当前版本暂不支持批量模式。你可以逐个运行。批量功能已在 roadmap 中。\n\n---\n\n## 技术\n\n**Q: 为什么有些 Skill 被分类为「代码工程型」而有些是「纯方法论型」？**\n\n含 .py 文件、或 SKILL.md 中嵌入了 `\\`\\`\\`python` 代码块、或引用了 pandas 等数据处理库的 Skill → 代码工程型（启用全四维评估）。其余 → 纯方法论型（只查方法论+护栏）。\n\n---\n\n**Q: 出现文件编码错误怎么办？**\n\nHaluCatch 会尝试以 UTF-8 读取所有文件。如果遇到非 UTF-8 编码（如 GBK），会用 `backslashreplace` 保留原始字节的转义形式，避免静默丢数据。\n\n---\n\n**Q: 代码风险检查有哪些规则？**\n\n当前 7 条通用规则：异常处理（裸 except: pass）、浮点比较（== 0.0）、除零风险（return 中无保护除法）、硬编码阈值（固定 skiprows）、路径拼接（字符串拼路径）、静默覆盖（open 写模式无警告）、超时缺失（requests 无 timeout）。\n\n---\n\n**Q: 行动版报告里的「Phase 4 闭环」是什么意思？**\n\n审查完成后，HaluCatch 会询问是否按方案修复。选择「执行修复」→ 将方案发给 AI 实施 → 修复后重新审查验证。选择「我有更好建议」→ 描述你的想法 → 重新生成方案。选「不执行」→ 结束。完整的「发现→修复→验证」链路。\n\n---\n\n## 🚫 常见反模式（不要做的事）\n\n提交 Skill 或使用 HaluCatch 前，先过一遍这些高发问题：\n\n### ⚠️ 致命反模式\n\n| 踩坑 | 后果 | 正确做法 |\n|------|------|--------|\n| 让 AI 看完 HaluCatch 报告就直接改代码 | AI 可能误解报告建议，添加有问题的修复 | 先人工审查每条建议，确认后再让 AI 执行 |\n| 只看评分不看详情 | 高分但细节全是烂摊子 | 逐条看 warn/fail，优先修 🔴 |\n| Skills/ 目录塞满别人的 Skill 后跑审查 | 别人代码的问题全算在你头上 | `config.yaml` 设 `skills_is_external: true` |\n\n### 地基（Foundation）\n\n| 踩坑 | 后果 | 怎么避 |\n|------|------|--------|\n| SKILL.md 里引用本地绝对路径（如 `/Users/me/project/`） | 换台机器就跑不了 | 全部用相对路径：`references/guide.md` 而非 `/home/me/guide.md` |\n| 引用的脚本/文档文件实际不存在 | AI 按不存在的东西执行，产生幻觉 | 跑审查前先 `ls` 确认每个被引用的文件都在 |\n| 明明有 Python 脚本但 SKILL.md 里没提 | HaluCatch 可能漏掉代码风险检查 | `SKILL.md` 里注明所有 Python 依赖和入口文件 |\n\n### 代码风险（Code）\n\n| 踩坑 | 后果 | 怎么避 |\n|------|------|--------|\n| `except Exception: pass` 或 `except: pass` | 出错静默吞掉，查 bug 如大海捞针 | 最少 `except Exception as e: print(e)` |\n| `open(filename, 'w')` 无保护 | 静默覆盖已有文件，数据丢失 | 改成 `'x'` 模式，或写入前检查 `os.path.exists()` |\n| `requests.get(u\n\nArchive v1.8.4: 25 files, 72054 bytes\n\nFiles: CHANGELOG.md (11462b), config.yaml (2061b), FAQ.md (9136b), halucatch_core.py (642b), halucatch/__init__.py (77b), halucatch/__main__.py (104b), halucatch/classifier.py (702b), halucatch/cli.py (7021b), halucatch/config.py (12476b), halucatch/evaluators/__init__.py (506b), halucatch/evaluators/code_risks.py (15720b), halucatch/evaluators/complexity.py (23677b), halucatch/evaluators/foundation.py (2921b), halucatch/evaluators/guardrails.py (9749b), halucatch/evaluators/methodology.py (3044b), halucatch/evaluators/rules.py (3245b), halucatch/README.md (1992b), halucatch/reporter.py (19561b), halucatch/scanner.py (8316b), LICENSE (1067b), manifest.json (690b), README.md (12457b), skill-card.md (2476b), SKILL.md (21809b), _meta.json (128b)\n\nArchive v1.8.3: 25 files, 72213 bytes\n\nFiles: CHANGELOG.md (11437b), config.yaml (2061b), FAQ.md (9136b), halucatch_core.py (642b), halucatch/__init__.py (77b), halucatch/__main__.py (104b), halucatch/classifier.py (702b), halucatch/cli.py (7021b), halucatch/config.py (12476b), halucatch/evaluators/__init__.py (506b), halucatch/evaluators/code_risks.py (15717b), halucatch/evaluators/complexity.py (23677b), halucatch/evaluators/foundation.py (2921b), halucatch/evaluators/guardrails.py (9749b), halucatch/evaluators/methodology.py (3044b), halucatch/evaluators/rules.py (3245b), halucatch/README.md (1992b), halucatch/reporter.py (19561b), halucatch/scanner.py (8316b), LICENSE (1067b), manifest.json (690b), README.md (12457b), skill-card.md (2902b), SKILL.md (21809b), _meta.json (128b)\n\nArchive v1.8.2: 25 files, 72056 bytes\n\nFiles: CHANGELOG.md (11429b), config.yaml (2061b), FAQ.md (9136b), halucatch_core.py (642b), halucatch/__init__.py (77b), halucatch/__main__.py (104b), halucatch/classifier.py (702b), halucatch/cli.py (7021b), halucatch/config.py (12476b), halucatch/evaluators/__init__.py (506b), halucatch/evaluators/code_risks.py (15627b), halucatch/evaluators/complexity.py (23677b), halucatch/evaluators/foundation.py (2921b), halucatch/evaluators/guardrails.py (9749b), halucatch/evaluators/methodology.py (3044b), halucatch/evaluators/rules.py (3245b), halucatch/README.md (1992b), halucatch/reporter.py (19561b), halucatch/scanner.py (8316b), LICENSE (1067b), manifest.json (690b), README.md (12457b), skill-card.md (2574b), SKILL.md (21809b), _meta.json (128b)\n\nArchive v1.8.1: 25 files, 71254 bytes\n\nFiles: CHANGELOG.md (11491b), config.yaml (2061b), FAQ.md (7845b), halucatch_core.py (642b), halucatch/__init__.py (77b), halucatch/__main__.py (104b), halucatch/classifier.py (702b), halucatch/cli.py (6603b), halucatch/config.py (12476b), halucatch/evaluators/__init__.py (506b), halucatch/evaluators/code_risks.py (15627b), halucatch/evaluators/complexity.py (23677b), halucatch/evaluators/foundation.py (2921b), halucatch/evaluators/guardrails.py (9749b), halucatch/evaluators/methodology.py (3044b), halucatch/evaluators/rules.py (3245b), halucatch/README.md (1992b), halucatch/reporter.py (19561b), halucatch/scanner.py (8316b), LICENSE (1067b), manifest.json (690b), README.md (12457b), skill-card.md (2720b), SKILL.md (21809b), _meta.json (128b)\n\nArchive v1.7.8: 24 files, 51261 bytes\n\nFiles: CHANGELOG.md (10624b), config.yaml (1770b), FAQ.md (3485b), halucatch_core.py (490b), halucatch/__init__.py (77b), halucatch/__main__.py (104b), halucatch/classifier.py (731b), halucatch/cli.py (4093b), halucatch/config.py (12163b), halucatch/evaluators/__init__.py (429b), halucatch/evaluators/code_risks.py (3308b), halucatch/evaluators/foundation.py (2951b), halucatch/evaluators/guardrails.py (6102b), halucatch/evaluators/methodology.py (3073b), halucatch/evaluators/rules.py (3285b), halucatch/README.md (1992b), halucatch/reporter.py (13330b), halucatch/scanner.py (7631b), LICENSE (1067b), manifest.json (605b), README.md (12457b), skill-card.md (2158b), SKILL.md (20261b), _meta.json (128b)\n\nArchive v1.7.7: 21 files, 47157 bytes\n\nFiles: CHANGELOG.md (9284b), FAQ.md (3072b), halucatch_core.py (490b), halucatch/__init__.py (77b), halucatch/__main__.py (104b), halucatch/classifier.py (731b), halucatch/cli.py (4093b), halucatch/config.py (12163b), halucatch/evaluators/__init__.py (429b), halucatch/evaluators/code_risks.py (3308b), halucatch/evaluators/foundation.py (2951b), halucatch/evaluators/guardrails.py (6102b), halucatch/evaluators/methodology.py (3073b), halucatch/evaluators/rules.py (3285b), halucatch/README.md (1992b), halucatch/reporter.py (13330b), halucatch/scanner.py (7631b), README.md (12457b), skill-card.md (2092b), SKILL.md (18538b), _meta.json (128b)","readmeExcerpt":"Skill: HaluCatch / 捕幻 Owner: codermoray Summary: Evaluates the reliability of AI Skill execution. Assesses whether a Skill's output is trustworthy, reproducible, and withstands business scrutiny when execut... Tags: latest:1.8.8 Version history: v1.8.8 | 2026-07-12T09:25:31.061Z | auto - Bumped version to 1.8.8. - Removed redundant documentation files (README.md, skill-card.md) for leaner distribution. - Updated SKIL","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"# 为中文用户审查\npython3 halucatch_core.py --skill-dir /path/to/skill --lang zh-CN\n\n# 为英文用户审查\npython3 halucatch_core.py --skill-dir /path/to/skill --lang en\n\n# 自动检测（fallback）\npython3 halucatch_core.py --skill-dir /path/to/skill"},{"language":"text","snippet":"这个 Skill 涉及数据处理吗？\n  ├─ ❌ 纯方法论型（指令/模板/文档类）\n  │    评估重点：指令完备性、逻辑自洽、可复现性\n  │\n  ├─ ✅ 代码工程型（含 .py / 数据文件 / md 内嵌代码）\n  │    评估重点：地基 + 代码 + 规则 + 护栏\n  │\n  └─ ⚠️ 不确定\n        → 询问用户：「这个 Skill 有数据处理步骤吗？」"},{"language":"markdown","snippet":"> 本报告由 HaluCatch 生成。检查进度: [✅ HaluCatch 四维评估全部执行完毕 / ⚠️ 部分评估维度未完成]。"},{"language":"text","snippet":"cli.py → reporter.py → evaluators/__init__.py → config.py\n             ↑                        ↑\n          scanner.py               classifier.py"},{"language":"bash","snippet":"python3 -m halucatch --skill-dir . --validate    # 快速扫描文件清单\npython3 -m halucatch --skill-dir . --output-dir ./ci-reports  # 完整审查出报告"},{"language":"text","snippet":"# HaluCatch 审计报告 — my-skill\n\n## 📌 一句话总结\n\n🟢 3 通过 · ⚠️ 2 注意 · 💡 3 可优化\n\n## 🎯 核心结论\n\n| 地基 | 代码 | 规则 | 护栏 | 复杂度 |\n|:--:|:--:|:--:|:--:|:--:|\n| 🟢 稳固 6/6 | 🟢 干净 90/90 | 🟡 有歧义 4/6 | 🟢 到位 11/11 | 🟡 注意 2.2/10 |\n\n### 做的不错 👍\n- ✅ 有固化脚本兜底核心任务\n\n### 需要注意的方面\n- ⚠️ 存在模糊表述 ['大概']（说明书写了模糊词，AI 可能会猜错）"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: halucatch\ndescription: |\n  Evaluates the reliability of AI Skill execution. Assesses whether a Skill's output is trustworthy, reproducible, and withstands business scrutiny when executed by an AI agent. Covers four dimensions: data pipeline integrity, code risk, business logic ambiguity, and interpretation guardrails. Use when auditing an AI Skill, checking for hallucinations or unreliable outputs, verifying execution reproducibility, or reviewing a Skill's safety before deployment or sharing.\nsummary: AI Skill 执行可靠性审查工具。评估一个 Skill 被 AI 执行时，结果是否可信、是否可复现、是否经得起业务推敲。覆盖四维度：地基（数据管线）、代码、规则（业务口径）、护栏（解读指南）。\nlicense: MIT\nallowed-tools:\n  - Read\n  - Write\n  - Bash\ncompatibility: Requires Python 3.8+; Bash only for local 'python3 halucatch_core.py', no network/arbitrary commands\nauthor: CoderMoray\nversion: 1.8.8\nmetadata:\n  hermes:\n    tags:\n    - skill-audit\n    - reliability\n    - engineering-assurance\n    - Skill审查\n    - 工程质量\n    - 可靠性\n  openclaw:\n    requires:\n      bins:\n      - python3\n    emoji: 🔍\n    homepage: https://github.com/CoderMoray/HaluCatch\nslug: halucatch\ndisplayName: HaluCatch / 捕幻\ntags:\n  - skill-audit\n  - reliability\n  - engineering-assurance\n  - Skill审查\n  - 工程质量\n  - 可靠性\n---\n> **一句话总结**：把一个 AI Skill 的文件夹扔给 HaluCatch，它会逐项检查数据管线、代码逻辑、业务规则、安全护栏有没有漏洞，然后给你三份报告（标准版看全貌、专业版看细节、行动版直接修），全程几秒钟、完全离线。\n>\n> [快速开始](#1-入口逻辑) · [能力边界](#能力边界) · [输出解读](#5-报告)\n\n# HaluCatch / 捕幻 — AI Skill 执行可靠性审查\n\n评估一个 Skill 包在 AI 执行时的可靠性，产出评估报告和修复建议（建议需用户确认后才执行，不自动修改目标 Skill）。\n\n---\n\n## 能力边界\n\n| 擅长 | 不擅长 |\n|------|--------|\n| 评估 AI 执行 skill 时会否出错 | 网络安全审查（SQL 注入、XSS 等） |\n| 检查数据管道是否可靠 | 合规性审查（GDPR、隐私法规等） |\n| 发现自然语言业务规则的歧义 | Skill 本身的业务正确性（不懂业务逻辑） |\n| 检查解读护栏是否到位 | 代码性能优化 |\n| 输出修复建议和骨架脚本 | 替换人工业务决策 |\n\n**硬件限制：** 单文件上限 10 MB（超大文件会被跳过并提示），不支持批量审查（一次一个目录），不支持二进制文件，不建立网络连接（仅通过本地 Python 脚本运行）。审查耗时取决于目录下文件数量和大小，通常几秒到几十秒。\n\n---\n\n## 角色\n\n当用户调用 HaluCatch 时，**你就是 HaluCatch 审查执行者**，而非旁观者。\n\n### 职责\n\n- 调用 `halucatch_core.py` **一次性完成全流程**（L1 扫描 + L2 评估 + L3 报告生成）\n- 读取脚本生成的报告文件，对话中展示标准版，询问是否修复\n- 在脚本报告基础上做语义补充：按需读取报告中引用的源文件，提供上下文分析（`info` 级别条目）\n- **不要自己读取目标目录的文件**——文件扫描由脚本完成，AI 读取只会浪费 token\n\n### 你与 halucatch_core.py 的分工\n\n| 层级 | 任务 | 执行方 | 原则 |\n|------|------|--------|------|\n| **L1** | 文件扫描 | `halucatch_core.py --validate` | 确定性高，脚本更快更准 |\n| **L2** | 地基 + 代码 + 规则 + 护栏检查 | 脚本取 JSON 基线 → **你在此基础上补充分析** | 正则匹配靠脚本，上下文解读靠你 |\n| **L3** | 三版报告生成 | `halucatch_core.py` **生成并落盘**，你读取后展示给用户 | `reporter.py` 确定性高、格式一致、零幻觉——你只需做语义补充 |\n\n> **核心原则**：`halucatch_core.py` 涵盖全流程——L1 扫描、L2 评估、L3 报告生成一次性完成。你只需读取脚本生成的报告并展示给用户。不再由 AI 独立编写报告正文。\n\n## 权限与安全边界\n\n**⚠️ 写入警告：HaluCatch 会生成报告文件写入目标目录的 `reports/` 子目录，并可能产出修复指引（需用户确认后才应用）。这不是纯只读工具。**\n\nHaluCatch 仅需要以下权限即可运行：\n\n| 操作 | 需要 | 说明 |\n|------|------|------|\n| 读取目标 Skill 目录 | Read | 递归读取全部文件 |\n| 写入报告文件 | Write | 仅写入目标目录内的 `reports/` 子目录，不修改 Skill 源文件 |\n| 执行 Python 脚本 | Bash | 仅执行本地 `halucatch_core.py`，不访问网络、不执行外部命令 |\n\n**安全约束**：HaluCatch 不会访问目标目录以外的任何路径，不会发起网络连接。Bash 权限仅用于运行自带的 Python 审查脚本，不会执行非本项目代码。审查前必须由用户显式指定目标路径。\n\n---\n\n## 输入\n\n用户提供一个 Skill 文件夹路径。该文件夹可能包含：\n\n| 文件类型 | 是"},{"path":"halucatch/README.md","content":"HaluCatch 模块化拆分 — 设计决策说明\n\n## 目录结构\n\nhalucatch/                    # 核心包\n├── __init__.py               # 导出版本和核心 API（~15 行）\n├── config.py                 # MESSAGES + detect_system_locale（~218 行）\n├── scanner.py                # scan_folder + _extract_version + _strip_string_literals（~166 行）\n├── classifier.py             # classify_skill（~16 行）\n├── evaluators/               # 四维评估 + 自检\n│   ├── __init__.py           # 聚合导出（~30 行）\n│   ├── foundation.py         # check_foundation（~72 行）\n│   ├── code_risks.py         # check_code_risks（~56 行）\n│   ├── rules.py              # check_rules（~85 行）\n│   ├── guardrails.py         # check_guardrails（~133 行）\n│   └── methodology.py        # check_methodology（~66 行）\n├── reporter.py               # generate_report（~262 行）\n├── cli.py                    # parse_args + main（~88 行）\nhalucatch_core.py             # 向后兼容入口（~30 行，导入 cli.main）\n\n## 设计原则\n\n1. **零依赖**：所有模块仅使用 Python 标准库，不引入外部包。\n2. **单一职责**：每个模块对应一个功能边界，模块内高内聚。\n3. **AI 可复现**：单文件控制在 200 行以内，AI 可以完整理解每个模块。\n4. **向后兼容**：halucatch_core.py 保留，所有现有用法不受影响。\n5. **可扩展**：新增评估维度时，只需在 evaluators/ 下新建文件，evaluators/__init__.py 注册即可。\n\n## 依赖关系\n\n```\ncli.py → reporter.py → evaluators/__init__.py → config.py\n             ↑                        ↑\n          scanner.py               classifier.py\n```\n\n所有模块都依赖 config.py（MESSAGES）。\nscanner.py 和 classifier.py 无依赖。\nreporter.py 依赖所有 evaluators 和 scanner 输出。\ncli.py 是入口，协调所有模块。"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn74hb96rgc7bpqt7m16rvn3h188ehj7\",\n  \"slug\": \"halucatch\",\n  \"version\": \"1.8.8\",\n  \"publishedAt\": 1783848331061\n}"},{"path":"CHANGELOG.md","content":"# Changelog\n\n本文档记录 HaluCatch 项目的所有 notable changes。\n\n版本号规则：\n- **中间版本号** (1.x.0)：新功能或架构级变更\n- **小版本号** (1.0.x)：修复、增强、chore 等小更新\n- **每个 commit 对应一个版本更新**\n\n---\n\n## [Unreleased]\n\n\n---\n\n## [V1.8.8] - 2026-07-12 · `a470515`\n- CHANGELOG 补 hash、清 Unreleased 已发布内容\n- Release.sh 重排为 12 步，commit 先于 CHANGELOG（tag 存在 → hash 正确）\n- FAQ 反模式加 Before/After 示例，报告预览加 Demo 站链接；SkillHub 去 README\n- CHANGELOG 1.8.7 重写为真实变更，generate-changelog 移除反引号 escape\n- PREV 源改为 CHANGELOG.md hash 优先（git tag 可被挪，CHANGELOG hash 不变）\n- Sync_version_meta 新版本无 tag 时用 HEAD hash 而非 -\n- 响应 SkillSpector 3 条——删 halucatch-fix/、触发条件区、ClawHub 不打包 README\n\n---\n\n\n## [V1.8.7] - 2026-07-12 · `8a74f7e`\n\n### Added\n- FAQ 顶部新增「🔍 报错速查」表格，搜报错一眼定位\n- AI 确认外部 Skill 支持弹窗+文字双模式，选项带编号\n\n### Changed\n- 异常处理格式统一：所有异常附加机器详情，仅 unexpected 打印 traceback\n- SKILL.md 配置修改确认一步完成（用户回复即授权，不二次确认）\n- SKILL.md 第三选项说明 `[疑似外部 Skill]` 为脚本自动标注功能\n\n### Fixed\n- `compatibility` 随 config.yaml 同步，细化 Bash 用途声明\n- 根 `config.yaml` 走 frontmatter，去除 `skills_is_external` 字段\n- PREV_TAG 三级回退（git tag → commit → CHANGELOG），始终输出来源\n- generate-changelog.sh 去 `set -u`、去反引号 escape，根除 unbound variable\n\n---\n\n\n## [V1.8.6] - 2026-07-12 · `f430b91`\n- 独立 FAQ 页面，含响应式导航动画、搜索过滤、关键词推荐\n- CHANGELOG 补全 v1.8.1～v1.8.5\n- 运行配置从根 config.yaml 迁移到 halucatch/halucatch/.halucatch_config.yaml\n- Scanner/cli 去掉旧版 config.yaml 兼容，仅读 .halucatch_config.yaml\n- 明确 skills_is_external 控制的是项目根 skills/\n- Skills_is_external 恢复递归跳过所有层级 skills/\n- 删除 docs/FAQ.md，build.py 从 halucatch/FAQ.md 复制，统一维护源\n- FAQ 顶部加报错速查表，搜报错的人一眼定位\n- Release.sh 增加 build_faq.py 步骤\n- 修正构建输出目录为 docs/，补充 blog 与安装区配置说明\n- 将 manifest.json 纳入版本管理并升版至 1.8.6\n- Generate-changelog --write 传版本号，用 tag range 生成条目而非填 Unreleased\n- SKILL.md config.yaml 加「HaluCatch 自身」限定，frontmatter 细化 Bash 用途\n- Config.yaml compatibility 同步 SKILL.md，细化 Bash 用途声明\n- 运行配置改为 os.path.dirname(__file__) 包内路径，不依赖目标目录\n- Skills_is_external 仅跳过根级 skills/，不递归影响子目录\n- 统一错误输出格式，所有异常附加机器详情且仅 unexpected 打印 traceback\n- Build.py FAQ 路径修正为 ROOT.parent，docs/ 生成最新 FAQ\n\n---\n\n## [V1.8.5] - 2026-07-12 · `8975c93`\n\n### Fixed\n- SKILL.md 安全声明继续收紧：删 `git commit` 禁止指令、`reports/` 路径修正为目录内、触发条件去贴入建议\n- eval( 注释残留清除，三处（正则、描述、注释）彻底消除静态分析误报\n---\n\n## [V1.8.4] - 2026-07-12 · `45b3294`\n\n### Fixed\n- eval( 检测模式改用 `\\x65` + 字符串拼接，避开静态分析误报\n- release.sh Step 6/7 调序（先尺寸检查再打包）\n---\n\n## [V1.8.3] - 2026-07-11 · `16a4ea4`\n\n### Fixed\n- eval( 检测模式改用 `\\x65` 拆散字面量，避开静态分析 Critical 误报\n---\n\n## [V1.8.2] - 2026-07-11 · `1858d8c`\n\n### Changed\n- FAQ.md：`常见避坑` → `🚫 常见反模式`，新增 3 条致命反模式 + 标准版报告预览\n- cli.py 错误提示加「→ 下一步操作」，unexpected 附 GitHub Issue 链接\n---\n\n## [V1.8.1] - 2026-07-11 · `82a4f38`\n\n### Fixed\n- 响应 NVIDIA SkillSpector 5 条安全发现：强化 Bash 权限声明、修复路径歧义、收紧触发条件\n---\n\n## [V1.8.0] - 2026-07-11 · `b9f9bb0`\n\n### Added\n- **第五维度：复杂度评估** — 新增 11 项指标（章节深度、引用链、重复冗余、表格复杂度、脚本覆盖比、代码/文档比、指令密度等），综合评分 0-10 分\n- **脚本覆盖率折扣** — `最终 = 加权 × (1 − √覆盖率)`，边际递减：第一个脚本降幅最大\n- **Skills 外部目录检测** — `config.yaml` 新增 `skills_is_external` 字段，null 时标注 ⚠️ 疑似外部 Skill，true 时跳过扫描\n- **代码风险检测多语言** — 支持 Shell / Go / JS / Ruby / Rust / Perl / TS，按语言分组统计\n- **Shell 受保护上"},{"path":"FAQ.md","content":"# HaluCatch / 捕幻 — 常见问题\n\n---\n\n## 基础\n\n**Q: HaluCatch 需要联网吗？**\n\n不需要。全程离线运行，仅扫描本地文件夹中的 SKILL.md 和 .py 文件，不会发起任何网络请求。如果执行卡住，大概率是 AI 对话环境超时或目标路径文件过多导致扫描耗时。\n\n---\n\n**Q: HaluCatch 怎么用？**\n\n对 AI 说「帮我用 HaluCatch 审查 /path/to/skill」即可。AI 会先确认目标路径无误，再开始扫描评估。为避免误操作，请确保指定的路径是希望审查的 Skill 目录，不要指向系统目录或 home 目录。3 步上手：\n\n1. 跑一次审查 → 看标准版报告了解问题\n2. 打开 `-行动版.md` → 从列表第一条开始逐项修复\n3. 修复后重新跑 → 对比分数是否改善\n\n---\n\n**Q: HaluCatch 是免费的吗？**\n\n是。HaluCatch 采用 MIT 开源协议，完全免费，包括个人和商业使用。源代码在 GitHub 上公开。\n\n---\n\n**Q: HaluCatch 支持中文还是英文？**\n\n都支持。HaluCatch 会自动检测你的 AI 对话环境的语言偏好，输出对应语言的三份报告（标准版、专业版、行动版）。也可以通过 `--lang en` 或 `--lang zh-CN` 强制指定。\n\n---\n\n**Q: HaluCatch 可以在哪些 AI 平台上使用？**\n\nHaluCatch 支持所有允许上传提示词/技能的 AI 平台，包括 ClawHub、SkillHub 等技能市场。同时支持纯命令行模式，可以在任何终端中运行。\n\n---\n\n## 🔍 报错速查\n\n| 报错 / 报告标记 | 原因 | 解决 |\n|------|------|------|\n| `❌ 路径不存在` | 目录拼错或已移动 | `ls <路径>` 确认目录存在 |\n| `❌ 目录为空` | 缺少 SKILL.md | 新建 SKILL.md（一行标题也行）再跑 |\n| `⚠️ 疑似外部 Skill` | `skills/` 下有别人安装的 Skill | 确认后修改运行配置文件中 `skills_is_external` |\n| `🔴 硬编码路径` | SKILL.md 或脚本里有绝对路径 | 全部改成相对路径 |\n| `🟠 模糊表述` | 说明书用了\"大概/可能/通常\"等词 | 换成明确的 if-else 条件句 |\n| `🔴 裸 except` | `except: pass` 吞掉了错误 | 至少 `except Exception as e: print(e)` |\n| `🟠 不存在文件引用` | 引用的脚本/文档实际不在文件夹里 | `ls` 确认文件存在，修正文件名 |\n| `🟠 覆盖薄弱` | 大部分步骤没有脚本兜底 | 把核心步骤写成 .py/.sh 脚本 |\n\n更详细的避坑指南见下方 [🚫 常见反模式](#-常见反模式不要做的事)。\n\n---\n\n## 使用场景\n\n**场景 1：发布前自审**\n\n你要把写好的 Skill 发布到 ClawHub / SkillHub，想确保它在别人机器上也能正常工作。\n\n跑一次全维度审查。重点看标准版报告的「地基」和「代码风险」——硬编码路径、裸 except、虚构命令是最高频的坑。改完后跑第二次验证分数提升。\n\n**场景 2：接手别人的 Skill**\n\n别人写的 Skill 文档很长，你不敢直接给 AI 执行，怕出问题。\n\n跑一次审查，直接看「行动版报告」——它把每个问题拆成「现状 → 风险 → 修复方案 → 验证方法」，照着改就行，不用通读原始 SKILL.md。\n\n**场景 3：CI 自动检查**\n\n你在维护 Skill 仓库，想每次改代码时自动检查质量不退化。\n\n```bash\npython3 -m halucatch --skill-dir . --validate    # 快速扫描文件清单\npython3 -m halucatch --skill-dir . --output-dir ./ci-reports  # 完整审查出报告\n```\n\n在 CI 里集成，每次 PR 确保分数不下降。\n\n---\n\n## 能力边界\n\n**能做什么：**\n- ✅ 扫描 SKILL.md 和关联 .py 文件，检查执行可靠性\n- ✅ 识别硬编码路径、裸异常处理、虚构命令等 7 类代码风险\n- ✅ 评估业务规则歧义和护栏完整度\n- ✅ 自动识别中英文，输出对应语言报告\n- ✅ 生成标准版/专业版/行动版三份报告\n\n**不能做什么：**\n- ❌ 不联网 —— 不访问任何 API，不下载文件\n- ❌ 不查安全漏洞 —— SQL 注入、XSS、恶意指令交给 ClawHub SkillSpector\n- ❌ 不批量处理 —— 一次一个目录\n- ❌ 不代替人工决策 —— 报告是建议，最终你拍板\n\n**硬性限制：**\n- 📏 单文件 > 10 MB 会被跳过并提示\n- 📁 不支持二进制文件\n- ⏱️ 处理时间取决于文件数量和大小，通常 1-60 秒\n\n---\n\n**Q: 我的 Skill 没有 .py 文件，能用吗？**\n\n可以。HaluCatch 会自动分类为「纯方法论型」并跳过地基/代码检查，只评估方法论结构和护栏完整度。\n\n---\n\n## 报告\n\n**Q: HaluCatch 会在电脑上写文件吗？**\n\n会。审查完成后自动在 `HaluCatch/reports/` 目录生成三份报告（标准版、专业版、行动版 .md 文件）。不会修改目标 Skill 目录中的任何文件。如需自定义输出路径，使用 `--output-dir` 参数。\n\n**Q: 审查结果长什么样？**\n\n标准版报告示例（白话、零术语，给非技术用户看）：\n\n```\n# HaluCatch 审计报告 — my-skill\n\n## 📌 一句话总结\n\n🟢 3 通过 · ⚠️ 2 注意 · 💡 3 可优化\n\n## 🎯 核心结论\n\n| 地基 | 代码 | 规则 | 护栏 | 复杂度 |\n|:--:|:--:|:--:|:--:|:--:|\n| 🟢 稳固 6/6 | 🟢 干净 90/90 | 🟡 有歧义 4/6 | 🟢 到位 11/11 | 🟡 注意 2.2/10 |\n\n### 做的不错 👍\n- ✅ 有固化脚本兜底核心任务\n\n### 需要注意的方面\n- ⚠️ 存在模糊表述 ['大概']（说明书写了模糊词，AI 可能会猜错）\n```\n\n包含专业版（11 项指标表 + KaTeX 公式）和行动版（修复清单）。完整示例：运行 `python3 halucatch_core.py --skill-dir .` 审自己的项目，或查看 [在线 Demo](https://codermoray.github.io/HaluCatch/) 的交互式报告预览。\n\n---\n\n**Q: 审查结果说「护栏薄弱」，怎么修？**\n\n看同目录下的 `HaluCatch-report-日期-行动版.md`，它逐条列出了修复方案和验证检查"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1459,"uniquenessScore":43,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T00:21:06.405Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T00:21:06.405Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T06:42:12.726Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}