---
doc_id: QAT-002
title: "project-health-check-SKILL"
owner: 文档治理团队
approver: 业务与技术负责人
status: active
version: 1.0.0
classification: internal
last_reviewed: 2026-08-25
next_review: 2027-02-21
---

# 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