# qca

**Repository Path**: qirizhang/qca

## Basic Information

- **Project Name**: qca
- **Description**:  质链 Agent（QualityChain-Agent）
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 6
- **Created**: 2026-08-30
- **Last Updated**: 2026-09-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 质链 Agent · 商业航天任务技术状态与验证证据智能体

质链 Agent 将 PDF、Word、Excel、PPT、图片和文本材料转换为可定位的结构化证据，判断历史验证证据对当前任务星是否仍然适用，并组织问题闭环、人工复核和可审计交付。

当前产品主线是“平台复用下的任务构型验证证据适用性判定”；环境／可靠性发射准备证据审查与 GNC 专项是按适用性触发的垂直切片。系统输出是审查底稿、五类适用性建议和待确认问题，不替代专家签署、实物检测、仿真或授权决策。

## 快速开始（评审）

评审机从零安装、启动与离线演示按下面四步。端口、环境变量与故障处置见 [部署与环境](docs/submission/preliminary-20260828-rw-demo/部署与环境.md)；干净环境实测见 [干净环境复现报告](docs/submission/preliminary-20260828-rw-demo/干净环境复现报告.md)；冻结指纹见 [复现证据](docs/submission/preliminary-20260828-rw-demo/复现证据.md)。

```bash
# 1. 一键引导：前置检查、锁定依赖、后端可导入、飞轮冒烟、安装环境指纹
bash scripts/bootstrap_fresh_env.sh

# 2. 启动后端（默认 8080）
./scripts/dev.sh backend

# 3. 启动前端（默认 3000）
./scripts/dev.sh frontend

# 4. 飞轮试点 Demo（离线）
bash scripts/demo/rw_pilot_demo.sh --offline
```

演示脚本说明见 [演示脚本说明](docs/submission/preliminary-20260828-rw-demo/演示脚本说明.md)。入口为 `scripts/demo/rw_pilot_demo.sh`。离线演示可在启动时加 `QCA_OFFLINE_DEMO=1`。

## 快速开始

```bash
pip install -e ".[dev]"
cp .env.example .env
uvicorn backend.main:app --host 0.0.0.0 --port 8080
```

启动后：

- 健康检查：`http://127.0.0.1:8080/health`
- Swagger：`http://127.0.0.1:8080/docs`
- ReDoc：`http://127.0.0.1:8080/redoc`

前端工作台：

```bash
cd web
cp .env.example .env.local
bun install
bun run dev
```

访问 `http://127.0.0.1:3000/super-agent`。完全离线演示可执行 `QCA_OFFLINE_DEMO=1 ./scripts/prod.sh`。

## 核心能力

- 多格式解析：统一 `ParsedDocument`、`DocumentIR`、章节树和证据池，PDF 支持 MinerU 与本地兜底。
- 场景路由：Super Agent 根据材料、目标和 Profile 选择 Review-Plus、GNC、SMART 或商业航天准备性审查路径。
- 专业审查：Agent Profile、Harness Profile、Skill Bundle 与确定性核验协同，配置在运行创建时固化。
- 可信闭环：证据引用、跨文档问题、人工处置、再审、报告、事件和运行轨迹可追溯。
- 稳定交付：SQLite 控制面、JSON／内容寻址产物、Golden、语义评测和 release acceptance 分层。

Review-Plus 阶段数由运行 profile 决定：基础流程 11 阶段，工程验证开启后 12 阶段，专项验收可使用独立 7 阶段 profile。不要把它笼统描述成固定十步或固定十一步。

## 目录

```text
backend/       后端源码与随包 resources
web/           Next.js 前端
tests/         自动化测试
benchmark/     Golden、语料与评测工具
examples/      竞赛样例、业务案例和作者参考金标
scripts/       启动、迁移、验证与生成脚本
docs/          架构、部署、竞赛提交与历史记录
.runtime/      上传、运行产物、日志、PID 和缓存（不入 Git）
```

领域配置、知识和模板统一位于 `backend/resources/`，随 Python 包发布。运行数据默认写入 `.runtime/`；可通过 `QCA_RUNTIME_DIR`、`DATA_AGENT_RUNS_DIR` 等变量覆盖。

## 验证

```bash
# 核心测试
pytest -q

# 离线 Golden 验收
uv run python benchmark/run_golden.py --fail-on-gate

# 商业航天合成回归
UV_CACHE_DIR=/tmp/qca-uv-cache uv run --frozen python \
  scripts/run_commercial_space_benchmark.py
```

外部模型、在线解析和真实业务效果有独立验收条件；缺少授权语料、专家金标或有效 Provider 时必须保留 `NOT_EVALUATED`／`BLOCKED`，不能由基础回归通过替代。

## 文档入口

- [文档总索引](docs/README.md)
- [工程架构](docs/plan/工程架构与技术方案.md)
- [部署与运行](docs/submission/DEPLOYMENT.md)
- [竞赛 API](docs/submission/API.md)
- [评审快速使用说明](docs/submission/competition/使用说明.md)
- [分阶段提交状态](docs/submission/stages/)
- [提交事实基线](docs/submission/final/提交事实基线.md)
- [示例总入口](examples/README.md)
- [Benchmark](benchmark/README.md)

初赛材料位于 `docs/submission/final/`：当前有效提交版本是比赛 V2.8。