Metadata-Version: 2.4
Name: qvc-overseer
Version: 0.6.5
Summary: QVC - AI Agent code quality external overseer. Review only, never modify.
Project-URL: Homepage, https://github.com/ericwuname/qvc-overseer
Project-URL: Repository, https://github.com/ericwuname/qvc-overseer
Author: QVC Team
License: MIT
Keywords: ai-agent,bug-detection,code-review,quality-assurance,static-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# QVC — AI Agent Code Quality External Overseer

<p align="center">
  <img src="https://img.shields.io/pypi/v/qvc-overseer?color=a6e3a1&label=PyPI" alt="PyPI">
  <img src="https://img.shields.io/pypi/pyversions/qvc-overseer?color=89b4fa" alt="Python">
  <img src="https://img.shields.io/pypi/l/qvc-overseer?color=f9e2af" alt="License MIT">
  <img src="https://img.shields.io/badge/code--review-external%20overseer-cba6f7" alt="External Overseer">
</p>

<p align="center"><b>只审查，不修改。你的 AI Agent 写代码，QVC 在外围盯着。</b></p>

---

## 30 秒看懂 QVC

![Demo](docs/QVC_terminal_demo.html)

`ash
pip install qvc-overseer
cd your-project
qvc scan .          # 扫描 -> 出报告
qvc fix             # 生成 AI 修复指令 -> 丢给 Agent 修
`

**QVC 不做的事**：修改代码、生成补丁、替代 AI Agent。
**QVC 只做一件事**：告诉你的 AI Agent "你看这里有问题"。

## 为什么需要 QVC？

AI Agent 写代码后自审，存在**结构性盲区**：

| 盲区 | AI Agent 为什么看不到 | QVC 为什么能看到 |
|------|---------------------|----------------|
| 跨文件遗忘 | 审文件A时忘了文件B | 全量扫描，建立引用图 |
| 记忆残留 | 生成时的逻辑记忆覆盖自审 | 无生成记忆，只看最终代码 |
| 边界盲区 | 倾向检查主路径 | 规则专门针对边界条件 |

> **实测数据**：ai-corp V7.1 项目，AI 自审漏报率 = **100%**（0/4 个真 bug）

## 功能

- **全项目扫描** — Python / JavaScript / TypeScript / React / Go
- **三层置信引擎** — 确定性规则 / 模式匹配 / 启发式推断
- **外部监工摘要** — AI 自审漏报率、盲区分类
- **AI 修复指令** — qvc fix 生成可直接丢给 AI Agent 的修复提示词
- **任务池** — 扫描→派发→验证闭环
- **自我进化** — 每次扫描自动学习新指纹
- **社区基因池** — 共享/同步指纹库

## 快速开始

### 安装

`ash
pip install qvc-overseer
`

### 第一次扫描

`ash
cd your-project
qvc scan .
`

输出：
`
Scanning: .
Found 120 files, 19,705 lines
Done! 1.1s, 4 bugs

  [AHA] Your AI cannot see these
  [90%] create_session() signature mismatch (22 sites)
  [85%] Silent exception swallowing (23 sites)
  AI missed rate: 100%
`

### 让 AI Agent 修复

`ash
qvc fix              # 生成 fix-instructions.md
# 复制内容 -> 粘贴到 AI Agent -> 回车
`

### 更多命令

`ash
qvc scan . --full               # 全项目扫描（含建议级）
qvc scan . --self-review-report agent-review.md  # 对比 AI 自审报告
qvc diff                         # 只扫描变更文件
qvc watch                        # 后台监听，自动扫描
qvc tasks                        # 管理任务池
qvc contribute                   # 贡献指纹到社区基因池
qvc update                       # 同步社区基因池
qvc guide                        # 打开使用指南
`

## 对比：QVC vs 其他工具

| | QVC | ESLint/Pylint | SonarQube | CodeQL |
|---|---|---|---|---|
| 定位 | AI Agent 外部监工 | 代码风格 | 代码质量平台 | 安全分析 |
| 跨文件一致性 | ✅ | ❌ | 部分 | ❌ |
| AI 自审漏报率 | ✅ 可量化 | ❌ | ❌ | ❌ |
| AI 修复指令 | ✅ | ❌ | ❌ | ❌ |
| 自我进化 | ✅ 指纹学习 | ❌ | ❌ | ❌ |
| 安装 | pip install | 
pm/pip | Docker | 复杂 |

## 项目状态

QVC 目前在 **V6.1**，已发布到 PyPI。后续规划见 [项目执行指导书](docs/项目执行指导书_V6.md)。

## 贡献

欢迎贡献规则、指纹、文档。详见 [CONTRIBUTING.md](CONTRIBUTING.md)。

## License

MIT © QVC Team
