神级编程

定位

不是"让 AI 猜代码"，而是"先取证，再下判断"。

传统代码辅助技能只回一段提示词，模型看不到真实行号，容易编造问题。
神级编程内置一个纯标准库的本地分析引擎（scripts/analyzer.py），先把机器能确定的事实扫出来，
再把 文件:行号 证据注入给模型，让它只做"复核与决策"。

一句话：本地引擎负责"看得见"，AI 负责"想得清"。

文档导航

30 秒上手（第一次用就看这三行）

python scripts/main.py doctor                     # 1. 环境自检：确认解释器/工具链能跑
python scripts/main.py guide                      # 2. 场景决策表：你这种情况该用哪条命令
python scripts/main.py report --dir ./你的项目     # 3. 直接出一份 Markdown 审计报告

不需要联网、不需要装任何包（除 test-run 用本机 pytest）。
不确定该干什么时，只跑 guide：它会按"接手项目 / 上线前 / 单文件自查 / 安全 / 重构 / 格式 / 补测试 / 起项目 / 看影响面"
九种场景给出该敲的命令，以及明确写出什么时候不该用它。

什么时候用 / 什么时候不要用

场景 → 命令（照抄即可）

口语化也行：直接说"帮我审一下这个项目"、"这文件有没有安全问题"、"上线前检查一遍"，
技能会自动落到上表对应的命令，不用记参数。

会真正动手的命令

不是"给你一段建议再自己贴"——下面这些命令直接产出文件或直接改代码：

其余命令是一次性分析，不改你的代码：跑完只返回 JSON，改不改由你决定。

探针自测（自证，不是自吹）

python scripts/main.py probe                      # 五维全跑，输出分数与失分项
python scripts/main.py probe --dim A --quiet      # 只跑适用性这一维，只回总分
python scripts/main.py probe --md probe.md        # 同时落盘 Markdown 证据报告

探针不靠"我觉得"，每一项都真跑一次命令并取证（退出码 / JSON 字段 / 落盘文件字节）：

共 36 项检查（T 6 / R 7 / A 8 / C 8 / E 7），全部通过则五维各 5.00、总分 5.00（A+）。
当前 v1.6.0 在本机实测：total_score=5.0, grade=A+, gaps=[]。

自测口径说明：这是自评，用来证明"宣称的能力真的可执行"——检查项全部写在 scripts/probe.py，
任何人可以审阅、也可以自己加更严的项。平台 TRACE 分数由 SkillHub 独立评测，
不随版本自动重算，也没有手动重测入口；因此自评 5.0 不等于平台一定给 4.9。

核心设计（三条硬规则）

1. 证据优先：任何结论都要能对上 file:line，扫不出来就不许编。
2. 零依赖可跑：只用标准库（ast / re / hashlib / subprocess），装完即用；
   只有 test-run 会调用本机 pytest / npm，project-audit 的编译闸口会调用本机 tsc / mvn / go。
3. 低误报：字符串与注释先掩码再判语法问题；超长文本块（模板、文档串）不参与安全判定；规则定义行自身不报警；测试文件与文档不按生产代码标准判罚。
4. 能不能跑优先：编译失败 → code-review 判 block、code-quality 判 0 分 F、project-audit 判 fail
   （Python 走 compile()，TS/Java/Go 走本机 tsc / mvn / go，不再只看括号配对）；
   测试空集不判失败，但必须说清楚"为什么没收集到、该怎么跑"。

命令清单（32 条）

一、生成类（落盘可运行）

二、审查类（本地先行）

三、质量类（可量化）

四、理解与优化类

五、项目与辅助类

逻辑缺陷检测（9 类模式）

bug-patterns 用 AST 判定，不靠关键词猜测：

取舍原则：宁少不滥。BUG002/BUG003 在真实项目里大量出现（多为结构已确定的安全写法），
因此降为 low 只作提示；medium 的三类基本都能直接改成线上故障。
字符串 % 格式化、if total else 保护、if not items: return 保护都会自动排除，不误报。

上下文校准（同一条规则，不同位置不同分量）

security-scan 与 project-audit 的每条发现都带 context 字段，并在输出里按上下文分开计数：

目的只有一个：别让 14 条探针脚本的凭据把产品代码里那 1 条真风险淹掉，同时也不假装它们不存在。
降级只影响优先级，不删发现，modulated 字段会写清楚降级理由。

使用示例

例 1：接手陌生项目，先摸清底细

python scripts/main.py project-audit --dir ./my-project
python scripts/main.py project-quality --dir ./my-project
python scripts/main.py security-scan --path ./my-project

返回结构里 engineering_gaps 会直接告诉你缺 README / 缺 CI / 缺测试目录，
security.by_severity 给出 critical/high/medium/low 分布，tech_debt 给出 TODO 台账。

例 2：上线前卡口

python scripts/main.py code-review --file src/pay.py
python scripts/main.py code-quality --file src/pay.py

code-review 的 verdict 只有三种：block（有 critical）、warn（有 high 或格式问题超标）、pass。
可以直接接进 CI：非 pass 即阻断。

例 3：改一个公共函数前评估影响面

python scripts/main.py impact --dir . --symbol build_parser

输出定义位置、引用次数、受影响文件清单与影响等级（low/medium/high），
advice 直接列出必须回归的文件。

例 4：从零起一个能跑的项目

python scripts/main.py scaffold --template fastapi --name order-api --out ./order-api
python scripts/main.py scaffold --template react-vite --name order-web --out ./order-web

fastapi 模板带 /health 接口，react-vite 模板带可直接 npm install && npm run dev 的最小工程。

例 5：安全自查

python scripts/main.py security-scan --path ./src

检出类别覆盖：硬编码凭据、eval/exec、命令注入、SQL 注入、不安全反序列化、
关闭证书校验、弱哈希、私钥/云密钥泄漏、裸 except、assert 生产校验、不安全随机数、
调试开关、CORS 通配、临时文件竞态、XXE、前端 XSS 汇聚点、路径穿越、JWT 校验关闭、
敏感信息入日志、权限过宽、HTTP 无超时。每条带 CWE 编号、行号、原文片段、修复建议。

例 6：查"能跑但会出错"的逻辑缺陷

python scripts/main.py bug-patterns --path ./src

输出按级别排序：medium 的三类（可变默认参数、循环内提前 return、句柄未用 with、浮点判等）基本都会变成线上故障，
low 的（除零提示、嵌套索引）结合业务判断。

例 7：交付前跑三道闸口

python scripts/main.py project-audit --dir .          # syntax_errors 为空 且 build.verdict != fail
python scripts/main.py test-run --path ./tests        # 必须有真实通过用例
python scripts/main.py security-scan --path ./src     # 不能有 critical/high

编译闸口说明：build.checked 里是真实跑过的编译器（tsc/mvn/go）与错误数，
build.verdict=skip 表示本机缺工具（如未 npm i、无 mvn），必须写明"未实测编译"，不能当通过。
只想快速看结构时用 --no-build 跳过。

输出规范

• 统一 JSON，字段 ok 表示命令是否成功执行（业务判定在 verdict / grade）。
• 失败也是 JSON，且必须能自解释（不让人猜）：
  {"ok": false, "error": "错在哪", "hint": "为什么会这样", "next": ["可以直接复制的下一条命令"]}
• 审查类命令额外给 instruction 字段：这是给模型的作业单，已把本地证据与硬性要求写进去。

字段速查

实测数据（多轮交叉，真实项目）

第一轮：带标准答案的缺陷农场

在一份刻意埋雷的项目里放 31 个已知缺陷（14 类安全 + 9 类逻辑 + 死代码 + 重复 + 格式），
外加 5 个陷阱（测试里的 assert、README 的全角标点、参数化 SQL、参数列表 subprocess、跨文件被调用的函数）：

第二轮：真实项目信噪比

第三轮：能不能跑的破坏-修复闭环

第四轮：从零交付闭环（脚手架 → 业务 → 测试 → 起服务）

1. scaffold --template fastapi 生成工程 → 补 service.py（领域逻辑）+ main.py（HTTP 层）
2. 用技能自审：code-review 两个文件 pass、security-scan 0、bug-patterns 0、code-quality 90/A+
3. test-run：7 passed（幂等、库存不足、422、404、取消回补库存全覆盖）
4. 真实 uvicorn 起服务 + HTTP 冒烟：9/9 通过（含金额计算 3×12.50=37.50、幂等返回同一单、409/422/404 错误码、取消后库存回补）

第五轮：三个已开发真实系统的端到端闸口（v1.3.0 的直接来源）

对三套已上线的自研系统跑同一套闸口（project-audit → test-run → security-scan）：

本轮暴露并修掉的真缺陷（全部有复现证据）：

第六轮：电子档案系统 + 传染病院感系统（v1.4.0 的直接来源）

本轮暴露并修掉的 4 个真缺陷：

校准的反向教训（同样实测暴露）：最初把 scripts/ 也当 dev 目录，结果视觉识别系统的 10 条发现被整体降噪成 0 条 medium —
很多 Python 项目主代码就在 scripts/，因此 devtool 目录只保留 pipelines/tools/ci/build/.github/deploy。

误报治理（均为实测暴露后修掉的真问题）

• 测试文件里的 assert / 裸 except 不再按生产标准报风险
• README.md 等文档不再按代码标准判"全角标点/超长行"
• 名为 exec 的函数定义不再被误判为动态代码执行
• 模板字符串、规则定义行不参与扫描（自指误报归零）
• zip-tmp、vendor、.pnpm-store 等临时/第三方目录默认跳过
• TS 路径别名（@/、~/）不再被误判为未声明的 npm 包
• "password": "xxx" 这类 JSON/dict 形式硬编码凭据现在能抓到（原先只认 password = "xxx"）
• 字符串 % 格式化不再被当成取模、if total else 保护不再被当成除零风险
• 注释里的路径占位 /api/batch/xxx 不再被当成 XXX 待办（XXX 改为大小写敏感）
• sys.path 注入后可 import 的本地包（core、platforms）不再被报"未安装的第三方包"
• 图片/模型权重/日志/浏览器缓存不再计入代码文件数与语言占比，只算 asset_files
• 根目录探针脚本、测试文件、CI 脚本里的同类问题不再与产品代码同级（by_severity_prod 只算产品代码）
• scripts/ 不当 dev 目录（很多 Python 项目主代码就在这里），避免整体降噪

常见问题

Q：第一次用，从哪开始？
A：三条命令，按顺序敲：doctor（环境能不能跑）→ guide（我这种情况用哪条）→ report --dir <项目>（直接出报告）。
不要一上来背 32 条命令，guide 就是给你做这个决策的。

Q：我不会敲参数，只会说人话，能用吗？
A：能。直接说"帮我审一下这个项目""这文件有没有安全问题""上线前检查一遍""格式太乱帮我清一下"，
技能会落到对应命令；参数由它自己补默认值，只有路径需要你给。

Q：报错了看不懂怎么办？
A：失败返回里一定有 error（错在哪）、hint（为什么）、next（可直接复制的下一条命令）。
常见对照：

Q：为什么我的项目被判 fail？
A：只有三种情况判 fail：①编译不过（syntax_errors 或 build.verdict=fail）；②存在 critical 安全；
③security-scan 里 critical 命中。warn 表示"能交付但有阻塞项要清"，不是失败。

Q：build=skip 是不是等于通过？
A：不等于。skip 表示本机缺工具（没装 mvn / 没 npm i），编译根本没验证。
报告里必须写"未实测编译"，不能写成通过——这是设计上的硬约束。

Q：结果说我有安全问题，但我觉得是误报？
A：每条发现都带 file:line 和原文片段，先打开那一行看。确认误报时看 context：
测试文件（test）、CI 脚本（devtool）、探针脚本（scratch）本来就分级处理，产品代码（prod）才是门禁口径。

Q：大项目扫得动吗？
A：实测过 13 万文件、4.4 万资源文件的仓库。引擎自动跳过依赖/构建/缓存目录，图片/模型/日志只计体积，
源码单独计量；超出上限会标 truncated，不会假装扫全了。

Q：生成的东西不想要，怎么撤销？
A：scaffold/test-gen/crawl-gen 默认不覆盖已有文件；fix-format 默认只预演，加 --apply 才写回；
report 只写一个新的 .md。删掉生成的文件即可，不会动你原有代码。

Q：怎么知道这次改完可以交付了？
A：跑 report --dir <项目>，P0 清单清零 + verdict 不是 fail + by_severity_prod 无 critical/high，就算过闸。

Q：和 eslint / sonarqube / 依赖安装器有什么区别？
A：它们各管一段（JS 规范、全语言规则、依赖安装）；本技能把"编译 → 测试 → 安全 → 质量分 → 交付报告"
串成一条本地流水线，且默认零依赖、不联网、结果能对上 file:line。不是替代品，是编排层。

Q：为什么有些文件扫不出结果？
A：引擎跳过依赖与构建目录（node_modules、.git、venv、dist、target 等），
单文件上限 2MB，只认源码扩展名。二进制文件不解析。

Q：非 Python 项目能用吗？
A：能用，但能力分层：安全规则（22 条）、格式、重复块、TODO、项目评分、依赖对账（含 Node）、
编译闸口（tsc / mvn / go）、测试闸口（npm test）都跨语言；
AST 级复杂度、死代码调用图、逻辑缺陷模式、docstring 覆盖率仅 Python 精确。遇到纯前端/Java 项目时，
这些命令会返回 note 明确告诉你"未覆盖 + 建议改用 eslint / gocyclo / knip"，不会静默给你一个空结果。

Q：能发现业务逻辑 bug 吗？
A：能发现"模式级"缺陷（9 类 AST 模式：默认参数污染、除零、深索引、比较陷阱、循环提前 return、
句柄泄漏、浮点判等、返回值不一致），但业务规则算错这类问题只能靠测试和真实运行。
所以落地顺序是：先让静态检查把"必然出错"的写法清掉，再用测试与真实服务冒烟锁住业务规则。

Q：怎么判断"开发完能不能上线"？
A：三道闸口，全部自动给结论：①project-audit 的 syntax_errors 为空且 build.verdict != fail（能编译，
TS/Java/Go 也都真实跑编译器）；②test-run 有真实通过的用例或类型检查通过（能验证）；
③security-scan 无 critical/high（能过安全）。任一不过，verdict 直接 fail/block，不给"看起来还行"的通过。

Q：test-run 显示 collected 0，是测试失败吗？
A：不是。pytest 空集返回码 5，技能判为 ok 并给出提示。真实项目常用脚本式自测
（if __name__ == "__main__": main() + assert），pytest 不会收集——技能会点名是哪个文件，
并建议先用 python <文件> 跑通，再把断言迁移成 def test_xxx() 以便进 CI。
Node/TS 项目不会走到 pytest：有 npm test 就跑它（runner=npm），没有单测但有 tsconfig.json
就退化为 tsc --noEmit 类型闸口（runner=tsc），并把类型错误按 file:line 列出来。

Q：我的仓库根目录只是个沙盒，真正代码在子目录里怎么办？
A：引擎会自动在两层内查找含依赖清单（package.json / requirements.txt / pyproject.toml / pom.xml / go.mod 等）
的子项目作为真实工程根，project-audit 的 subprojects 与 deps-check 的 node.subproject 会标出下钻位置。

Q：这是静态分析，能不能替代人工审查？
A：不能。它能给出"确定的事实"和"确定的问题位置"，业务语义、并发正确性、权限模型仍需人判断。
技能的设计目标就是让 AI 只在这些事实之上做判断，而不是凭空发挥。

Q：数据写到哪里？
A：只在技能目录的 scripts/data/history.json 记录调用摘要；生成类命令写到你 --out 指定的目录，
默认不覆盖已有文件（需显式 --force）。

边界与承诺

• 改动可控：修复类命令（code-fix/code-refactor）只输出方案与代码块；
  唯一会写源码的 fix-format 默认预演，必须显式 --apply，且非 UTF-8 文件自动跳过。
• 不联网、不上传：全部本地计算，不发任何代码内容出去。
• 不伪造结论：缺工具就 skip，超时就 inconclusive，空测试集就说明"为什么没收集到"。
• 采集脚本遵守目标站 robots.txt 与用户协议，仅采集公开数据，控制访问频率。

已知限制汇总（一次性说清）