# Project Health Check｜项目状态自动检测

目标

用“证据优先（Evidence First）”方式自动判断项目的真实状态，而不是相信 README、任务看板、口头描述或文件夹名称。

本 Skill 的核心输出必须回答：

1. 这是什么项目？
2. 当前真正做到哪一步？
3. 能否构建、测试、运行、发布？
4. 哪些能力是真实实现，哪些只是 UI / mock / placeholder / stub？
5. 当前最严重的阻塞是什么？
6. 下一步唯一最值得做的动作是什么？

默认模式

默认：只读检查（READ-ONLY）。

除非用户明确授权，否则禁止：

• 修改源码
• 安装或升级依赖
• 删除、移动、重命名文件
• 写数据库
• 修改配置或环境变量
• Git commit / push / reset / clean
• 启动会影响生产数据的服务
• 登录生产环境
• 执行部署
• 自动修复

允许：

• 枚举目录
• 读取代码与配置
• 检查 Git 状态
• 读取已有构建、测试、日志与发布产物
• 运行明确无副作用的只读命令
• 在用户明确允许时运行本地 build/test/typecheck/lint

无法验证的事实必须标记：UNVERIFIED。

输入

至少需要以下之一：

• 项目路径
• 仓库
• 压缩包
• 已上传项目文件
• 当前工作目录

可选输入：

• 用户认为的当前阶段
• 目标发布平台
• 已知问题
• 是否允许运行测试
• 是否允许联网
• 是否允许检查生产环境

阶段模型

统一使用以下阶段，不只使用百分比：

• S0 Idea：仅想法、需求或文档
• S1 Design：产品/UI/架构设计存在
• S2 Prototype：可运行原型或 Demo
• S3 Functional：核心功能真实可用
• S4 Integrated：主要模块完成集成
• S5 Release Candidate：达到发布候选
• S6 Production：已有生产部署并验证
• S7 Mature：长期稳定运行并持续维护

如需要可附完成度百分比，但阶段判断优先。

工作流

Step 1：识别项目身份

检查：

• 根目录
• Git 仓库
• README / PRD / HANDOFF / ROADMAP
• package.json
• pyproject.toml / requirements.txt
• Cargo.toml
• go.mod
• pom.xml
• build.gradle / settings.gradle
• hvigorfile / build-profile.json5
• tauri.conf
• electron-builder
• Dockerfile / compose
• next.config / astro.config / vite.config
• CI 配置
• release / dist / bundle / artifacts

输出：

• 产品名称
• 项目类型
• 技术栈
• 主入口
• 运行方式
• 发布目标

Step 2：建立事实清单

从代码和真实产物验证：

• 主模块是否存在
• API 是否真实实现
• 数据库 schema 是否存在
• 鉴权是否真实存在
• 模型调用是否真实存在
• 文件/网络/设备操作是否真实
• UI 是否只是占位
• 是否存在 mock / stub / placeholder
• 是否存在 hardcoded response
• 是否存在 TODO / FIXME / not implemented
• 是否存在真实 release 产物

重点搜索：

TODO FIXME PLACEHOLDER MOCK STUB NOT_IMPLEMENTED COMING_SOON example response hardcoded throw new Error("Not implemented")

不能把“有界面”判定为“功能完成”。

Step 3：检查 Git 与版本健康

记录：

• 当前 branch
• HEAD commit
• 是否 dirty
• 未跟踪文件
• worktree
• tag
• 最近提交
• 是否存在多条实现路线
• README、构建产物和源码是否一致

不得自动修改 Git。

Step 4：检查工程健康

检查已有证据：

• typecheck
• lint
• unit test
• integration test
• E2E
• build
• packaging
• installer
• dependency audit
• license/security docs
• CI

如果用户允许实际执行，只运行项目已有标准命令，不擅自发明破坏性命令。

执行失败必须记录：

• 命令
• exit code
• 最小错误摘要
• 属于代码、环境还是依赖问题

Step 5：检查运行与发布状态

判断：

• 本地能否启动
• 主进程是否健康
• 端口是否正常
• 是否有安装包
• 是否签名
• 是否经过干净环境安装
• 是否验证升级/卸载
• 是否有回滚
• 是否有备份
• 是否有生产部署证据

生产运行仅在用户明确授权下复验。

Step 6：检查风险

至少检查：

• 明文 secret 指示文件是否存在
• .env / .pem / .key / credentials 文件名
• 过宽权限
• 192.0.2.10 暴露
• debug 配置进入生产
• 硬编码路径
• 硬编码主机/IP
• 用户数据混入源码
• 大型构建产物混入仓库
• 重复 node_modules / venv / target
• 旧版本覆盖主线
• 源码/README/产物不一致

禁止输出真实 secret 内容。

Step 7：给出健康结论

健康状态仅使用：

• HEALTHY
• HEALTHY_WITH_WARNINGS
• AT_RISK
• BLOCKED
• UNKNOWN

并给出置信度：

• High
• Medium
• Low

Step 8：给出唯一 NEXT ACTION

最终必须给出一个最重要的下一步。

格式：

NEXT ACTION：<唯一动作>

禁止一次给十几个行动项。

输出格式

Project Health Report

1. Executive Summary

• Product:
• Stage:
• Health:
• Confidence:
• Verified:
• Unverified:
• Release status:

2. Evidence

事实	证据	状态

3. Build / Test / Run Matrix

Gate	Status	Evidence

状态只能使用：

PASS / FAIL / PENDING / UNVERIFIED / N/A

4. Functional Reality Check

能力	UI存在	真实逻辑	验证状态

5. Risks

按严重度：

• P0 Blocking
• P1 High
• P2 Medium
• P3 Low

6. Current Blocker

只写当前最主要阻塞。

7. NEXT ACTION

只允许一个动作。

最终检查

完成前确认：

• 没有因为 README 宣称完成就直接判完成
• 没有把 UI 当成功能
• 没有把构建成功当成生产可用
• 没有把旧产物当成当前版本
• 没有泄露 secrets
• 所有无法验证的事实都标记 UNVERIFIED
• 给出了唯一 NEXT ACTION