开发 · 命令参考
qzx diagnoseProject
作用
无需执行项目脚本即可检查技术、依赖、验证流程、Git 状态、代码质量和大文件。
命令成熟度：Alpha
可用于真实使用和反馈，但其接口与行为仍可能继续演进。 这是当前开发 checkout 的评估。未来每个不可变发布标签都会保留该版本中包含的准确评估。 可在 PyPI 0.2.2.0.9 使用。文档对应 alpha checkout 0.2.2.0.9。
行为与内置保护
只检查，不改变状态
此操作直接执行
需要时使用原生工具
无需网络即可运行
设计为无需提权即可运行
这是只读检查。它可能调用 Git 查询，但绝不会执行项目定义的测试、linter、类型检查器、build、包脚本、hook 或安装器。检测到的流程会作为建议命令返回，并明确保持未验证状态。
此安全分类由 OpenAI ChatGPT 于 2026-09-04 对照实现摘要 sha256:7ab0d09029e88f1ebe52be85698694204a7a20e60a5aa79c52c4725161922e99 审阅。
准确语法
qzx diagnoseProject [path] --json参数
滑动或使用横向滚动条查看所有列。
| 名称 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| path | str | 否 | "." | 要诊断的项目目录路径（默认值：'.'） |
输入示例
qzx diagnoseProject无需执行脚本即可诊断当前目录中的项目
qzx diagnoseProject C:/my/project诊断指定路径的项目
要获得完整结构化载荷，请添加 --json： qzx diagnoseProject [path] --json
实测输出示例
使用 Windows 11 上的 QZX 0.2.2.0.9 捕获；退出码 0。依赖主机的值和耗时可能不同。
示例命令： qzx diagnoseProject ../artifacts/qzx-evidence/project-doctor --json
{
"success": true,
"message": "Project diagnosis completed with 1 observed issue. 2 configured validation workflows were discovered but not executed; run the suggested commands before treating the project as release-ready.",
"details": {
"path": "C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\project-doctor",
"technologies": [
"Python"
],
"dependencies": {
"manifest_count": 1,
"manifests_found": [
"pyproject.toml"
],
"total_declaration_count": 1,
"unique_declared_package_count": 1,
"unique_packages": [
"httpx"
],
"parse_errors": [],
"manifests": [
{
"path": "pyproject.toml",
"ecosystem": "python",
"status": "parsed",
"declaration_count": 1,
"group_counts": {
"runtime": 1
},
"packages": [
"httpx"
]
}
],
"counting_note": "Declaration totals include repeated packages across manifests and dependency groups; unique_declared_package_count deduplicates normalized package names."
},
"environment": {
"local_files": [],
"template_files": [],
"local_configuration_present": false,
"template_present": false,
"values_inspected": false,
"note": "Only environment filenames are reported; diagnoseProject never reads or returns environment values."
},
"validation": {
"execution_policy": "discovery_only",
"execution_note": "diagnoseProject never executes project-owned tests, linters, type checkers, builds, package scripts, hooks, or installers.",
"tests": {
"configured": true,
"status": "configured_not_run",
"tools": [
"pytest"
],
"configs": [
"tests",
"pyproject.toml [tool.pytest]"
],
"commands": [
"python -m pytest"
]
},
"lint": {
"configured": true,
"status": "configured_not_run",
"tools": [
"ruff"
],
"configs": [
"pyproject.toml [tool.ruff]"
],
"commands": [
"python -m ruff check ."
]
},
"type_checking": {
"configured": false,
"status": "not_configured",
"tools": [],
"configs": [],
"commands": []
},
"build": {
"configured": false,
"status": "not_configured",
"tools": [],
"configs": [],
"commands": []
}
},
"version_control": {
"status": "not_repository",
"reason": "Git did not identify a repository for this path."
},
"source_analysis": {
"unused_code": {
"status": "passed",
"candidate_symbols_count": 0,
"candidate_symbols": [],
"interpretation": "Candidates have no statically visible references; review dynamic uses before removal."
},
"circular_imports": {
"status": "passed",
"cycles_count": 0,
"cycles": []
}
},
"file_scan": {
"scanned_file_count": 3,
"maximum_file_count": 5000,
"scan_complete": true,
"error_count": 0,
"large_file_threshold_bytes": 1048576,
"large_file_threshold_formatted": "1.00 MB",
"large_file_count": 0,
"large_files": []
},
"summary": {
"status": "review",
"issue_count": 1,
"informational_count": 0,
"issue_counts_by_severity": {
"high": 0,
"medium": 0,
"low": 1,
"info": 0
},
"issues": [
{
"code": "git_not_detected",
"severity": "low",
"title": "Git repository not detected",
"description": "The inspected path is not inside a Git working tree.",
"remediation": "Use version control for maintained source projects or confirm that this directory is intentionally unversioned."
}
],
"verification": {
"level": "partial",
"release_readiness": "not_assessed",
"verified_areas": [
"technology and manifest discovery",
"dependency declaration inventory",
"Git working-tree state when Git is available",
"static unused-code candidates",
"static circular-import analysis",
"bounded large-file scan"
],
"configured_but_not_run": [
"tests",
"lint"
],
"suggested_commands": [
"python -m pytest",
"python -m ruff check ."
],
"reason": "The command performs read-only inspection and never executes project-owned validation or build scripts."
}
}
},
"report": "PROJECT BRIEFING\nPath: C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\project-doctor\nTechnologies: Python\nDependencies: 1 unique declared package in 1 manifest\nGit: repository not detected\nFile scan: 3 files; complete; 0 larger than 1.00 MB\n\nFINDINGS - Review recommended\n1 issues; 0 informational observations\n1. [LOW] Git repository not detected\n Next: Use version control for maintained source projects or confirm that this\n directory is intentionally unversioned.\n\nVALIDATION - DISCOVERED, NOT RUN\nTests: configured, not run\nLint: configured, not run\nType checks: not detected\nBuild: not detected\n\nReview the project scripts before running these commands.\nRun from: C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\project-doctor\n python -m pytest\n python -m ruff check .\n\nRelease readiness: NOT ASSESSED. Inspection is not a test run.\nUse --json for the full structured evidence and finding descriptions.",
"meta": {
"command": "diagnoseProject",
"command_maturity": {
"stage": "alpha",
"label": "Alpha",
"sequence": 2,
"public_executable": true,
"stability": "interface_may_change",
"summary": "Available for real use and feedback while its interface and behavior can still evolve.",
"promotion_review_required": false,
"assessment_scope": "development_checkout"
},
"duration_ms": 138.716,
"schema_version": 1
}
}查看 JSON 结果契约
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"success",
"message",
"meta"
],
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"meta": {
"type": "object",
"required": [
"command",
"command_maturity",
"duration_ms",
"schema_version"
],
"properties": {
"command": {
"type": "string"
},
"command_maturity": {
"type": "object",
"required": [
"stage",
"label",
"sequence",
"public_executable",
"stability",
"summary",
"promotion_review_required",
"assessment_scope"
],
"properties": {
"stage": {
"type": "string"
},
"label": {
"type": "string"
},
"sequence": {
"type": "integer"
},
"public_executable": {
"type": "boolean"
},
"stability": {
"type": "string"
},
"summary": {
"type": "string"
},
"promotion_review_required": {
"type": "boolean"
},
"assessment_scope": {
"type": "string"
},
"note": {
"type": "string"
},
"review": {
"type": "object",
"required": [
"reviewed_on",
"rationale",
"evidence"
],
"properties": {
"reviewed_on": {
"type": "string",
"format": "date"
},
"rationale": {
"type": "string"
},
"evidence": {
"type": "array",
"minItems": 1,
"items": {
"type": "string"
}
},
"replacement": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": true
},
"duration_ms": {
"type": "number"
},
"schema_version": {
"type": "integer"
}
},
"additionalProperties": true
},
"details": {
"type": "object",
"properties": {
"path": [],
"technologies": [],
"dependencies": [],
"environment": [],
"validation": [],
"version_control": [],
"source_analysis": [],
"file_scan": [],
"summary": []
},
"additionalProperties": true
},
"error": {
"type": "string"
},
"report": []
},
"additionalProperties": true
}错误与限制
公开契约要求失败时返回 success=false 和具有描述性的 message。此目录尚未为每个命令声明专门的错误分类；请检查结果，不要推断不存在的错误码。
QZX 仍处于 alpha 阶段。可选依赖、权限和主机能力可能影响结果。
{
"success": false,
"error": "Path '../artifacts/qzx-evidence/missing-golden-core-path' does not exist.",
"message": "Cannot diagnose the project because '../artifacts/qzx-evidence/missing-golden-core-path' does not exist.",
"meta": {
"command": "diagnoseProject",
"command_maturity": {
"stage": "alpha",
"label": "Alpha",
"sequence": 2,
"public_executable": true,
"stability": "interface_may_change",
"summary": "Available for real use and feedback while its interface and behavior can still evolve.",
"promotion_review_required": false,
"assessment_scope": "development_checkout"
},
"duration_ms": 3.356,
"schema_version": 1
}
}捕获的命令: qzx diagnoseProject ../artifacts/qzx-evidence/missing-golden-core-path --json
证据流程：已捕获并通过摘要验证。
证据与来源
- 文档渠道
- 开发文档 0.2.2.0.9 · main · sha256:cfba936e39931c286ca23add0ae546693db17d8b316e7cbc3891d26642d9b7e8
- 可用性
- 0.2.2.0.9 或更早
继续探索
相关命令
这些命令同样属于 开发 类别。对比它们，选择最适合解决任务的操作。