# qca

**Repository Path**: yanmind/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-09-14
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

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

能力定位是**验证证据适用性**：判断参考任务星已归档的验证证据，对并行研制的当前任务星是否仍然适用。首期切片是反作用飞轮的「跨星飞轮验证证据复用审查」。固件版本变化是跨星审查中的一种变化事件，在 Run 工作区内部登记，不是首页并列入口。

系统如何落地见 [技术方案](docs/plan/质链Agent技术方案.md)；设计取舍见 [端到端技术路线论证](docs/plan/从材料输入到最终结论的端到端技术路线论证.md)。本 README 是仓库入口，不替代上述两份文档。

## 背景与业务场景

商业卫星普遍是平台型谱复用加任务定制：星座分批部署、客户任务滚动进入，多颗任务星会同时处在设计、总装、试验或问题整改。同一平台上的星仍会因轨道、载荷、单机实物、软件与参数、器件批次和研制进度不同，形成各自的设计构型、装星实态、试验时技术状态。

现场材料也不是一份整齐报告，而是研制技术文档、技术验收报告、测试数据，以及 PDF、DOCX、XLSX、数字扫描件和图片混在一起。总问题不是「有没有历史报告」，而是：**这份历史证据的适用域，是否还覆盖当前任务星、当前阶段、当前对象和当前批准要求？**

全部重验会吃掉平台复用的价值；未经核对就整份继承，又可能把旧对象、旧版本或旧工况的结论带进当前任务。

## 要解决的问题

- **材料异构**：表格、单元格、段落、扫描件和图片坐标不统一，扩展名还可能对不上真实容器。
- **事实未确认**：从材料抽出的指标、图号、工况如果直接进判定，模型和解析噪声会污染结论。
- **跨星对象易糊**：设计图号、单机编号、批次混用时，A 星证据会被错绑到 B 星对象。
- **模型不宜直接定级**：大模型可以找线索，但不能用语义相似度决定「能不能继承」。
- **责任必须可追溯**：专家要看到原文位置、六维差在哪、候选从哪条判据来，而不是一段不可回放的摘要。

系统给出的是带原文引用的**五类适用性候选**（直接继承／条件继承／差异验证／重新验证／不可判定）、缺项说明和验证义务建议。这些输出不替代专业人员确认，不是合格结论，也不等于可以进入授权决策。

## 怎么解决

对外主路径是五步过程：上传与解析 → 用途与角色 → Agent 协作 → 冲突确认 → 证据链。**核验结果是审签出口，不是第六步。** Agent 协作可选。

技术上按这条主链落地：异构材料先做格式预检和本地解析，收成可回链的来源块与版本化来源索引；再抽出要求／设计／验证／交付实测四层待确认事实；可选的受控 Agent 只查缺项与冲突，**不产五类**；人工确认后追加不可变输入修订。跨星侧以设计图号为主键，按 `要求 × 证据项` 做六维确定性核验（任务与工况／环境与寿命／接口与集成／构型与实物／软件与参数／验证与问题），用最弱项锁定唯一五类。验证义务建议只从差异验证、重新验证，或条件继承中未满足的条件派生。

四条固定技术路线贯穿全程：正式飞轮路径与库内增强解析路径分开；确定性核验优先、受控大模型只辅助调查；全链路内容寻址、追加写入；最弱维单向悲观降级，禁止加权平均。事实不齐保持尚未评估；判据未批准或覆盖不足显示存在阻断项。尚未评估不等于不可判定。

## 用了哪些技术

| 层 | 做什么 | 关键技术 |
| --- | --- | --- |
| 材料摄入 | 能打开、能定位、预览与正式提交不漂移 | 魔数／ZIP 容器校验；正式路径本地解析 Office／数字 PDF；DOCX 按文档序抽表；XLSX 表＋A1 单元格双层块；两阶段预解析提交绑定 |
| 来源与事实 | 异构材料变成可哈希对象 | `SourceBlock` 内容寻址（`sasset_`／`sblk_`）；四层事实分字段；验证证据须声明产品级鉴定或实物绑定 |
| 调查与确认 | 模型找线索，人做入口 | Agent Harness（智能体配置、工具白名单）；调查来源投影只读已绑定条目；全集确认／拒绝；同 Run 写锁与 CAS；不可变 `InputRevision` |
| 跨星核验 | 逐证据比适用域 | 飞轮编号规则与身份索引；跨星对象选择器；`case × 要求 × 证据项` 种子；六维包络比对；项目批准判据覆盖校验；最弱项聚合 |
| 出口与审计 | 给人可签发的依据 | 固定五类候选；验证义务建议派生；专业人员确认位；操作链与产物哈希。前端文案一律走 `web/src/lib/aeroTerminology.ts` |

架构是微内核（`applicability_kernel`）加领域配置，再由飞轮应用服务编排。热控／结构／电子单机目前只是合成规则薄插件，用来证明内核可挂接，不代表这三个专业已形成完整产品。正式路径的 Office／数字 PDF 使用本地解析；PNG／JPG 按声明的 OCR 数据通道或 VLM 语义通道调用已配置的图片 Provider，结果仍须人工确认。未配置或调用失败时保留解析需复核项，不补造事实。正式路径不调 MinerU，不自动对扫描 PDF 逐页 OCR，也不抽 DOCX 嵌入图；库内增强解析路径仍在仓库里，但不被正式来源包消费。图片 Provider 已完成代码接入，在线稳定性和专业提取能力尚未完成评测。当前演示与回归以合成／脱敏夹具为主，不是授权真实型号验证结果。

## 快速开始

在仓库根目录执行：

```bash
# 安装与飞轮冒烟检查
bash scripts/bootstrap_fresh_env.sh

# 终端 1：飞轮 API（默认 8080）
./scripts/dev.sh backend

# 终端 2：比赛前端（默认 3000）
./scripts/dev.sh frontend
```

打开 `http://127.0.0.1:3000/`，点击「新建跨星审查 Run」进入正式 Run 工作区：先在 `/competition/run/<run_id>/process?view=materials` 上传参考任务星与当前任务星材料，再回到 `/competition/run/<run_id>` 业务工作台查看六维核验与五类适用性候选。作品说明页为 `/project-pitch`。

浏览器产品界面的唯一官方入口是 `web` 服务的 3000 端口；`/competition/demo` 与 `/visual-demo` 只能由用户显式进入，并保持只读，不会作为正式 Run 读取或导出失败时的替代数据源。`./scripts/dev.sh` 与 `./scripts/dev.sh frontend` 会按需构建 `/visual-demo` 静态产物（`SKIP_VISUAL_DEMO=1` 可跳过）。

完全离线的合成试点可执行：

```bash
bash scripts/demo/rw_pilot_demo.sh --offline
```

公开／模板化／脱敏材料的真实任务模式脚本：

```bash
uv run python scripts/demo/rw_real_task_run.py --score
uv run python scripts/demo/rw_real_task_run.py --verify-gates
```

## 比赛组成

默认且唯一支持的后端组成是 `backend.apps.flywheel_app:app`。`QCA_APP_COMPOSITION` 未设置时默认为 `flywheel`，其他值会被拒绝。

此分支已物理删除旧 Super Agent、Review-Plus（文件组审查）、综合审查、GNC 专项审查及全量兼容组成。`main` 为现行发布版本，完整历史实现保留在归档基线 `archive/main-before-lightweight-20260830`。详见 [比赛版应用组成](docs/submission/competition/比赛版应用组成.md)。

## 当前能力

- 受控来源包：接入 PDF、DOCX、XLSX／XLS、CSV、JSON、Parquet、PNG 与 JPG，形成带块、表格单元格、JSON 指针或系统记录坐标的版本化 `SourceIndex`；同时把已登记身份规范化为 `DevelopmentTechnicalDocument`、`TestReportRecord` 与 `TestDatasetRecord`，不从自由文本猜测指标或结论。
- Agent 事实主链：计划器按六维影响启动主 Agent、受影响专项、质疑与收成；只形成待确认事实、缺项与冲突。失败后可在同一 Run 重试。人工确认后追加不可变 `InputRevision`，未经确认的模型文本不影响确定性核验。
- 飞轮适用性：变化事件、对象身份、六维比较、证据级五类候选与证据谱系；同一次 `SYN-FW → SYN-FW-B` 变化可因历史证据不同形成继承类、差异验证、重新验证、不可判定或尚未评估状态。
- 跨专业复用：热控、结构、电子单机以合成规则薄插件复用同一六维公共内核；这证明代码级扩展方式，不代表三个专业已形成完整产品或批准判据。
- 企业数据准备：PLM、MES、TDM 与质量管理系统已有只读离线快照契约和合成夹具；尚未连接生产系统，也不回写源系统。
- 义务与复算：义务建议、受控隔离执行、回填与受影响部分再审。
- 人工责任与评测：独立签发身份、人工决定记录、操作链、产物完整性校验和比赛评测报告；没有专家冻结参考答案、人工基线或授权真实任务时，业务效果保持 `NOT_EVALUATED`。

## 目录

```text
backend/       飞轮 API、应用服务、领域判据与保留的解析底座
web/           首页、跨星过程工作台、Run 四区、作品说明、只读 demo 与视觉原型
tests/         当前飞轮组成的自动化测试
benchmark/     飞轮 W9 五项验收评分
examples/      飞轮材料、合成试点与企业系统离线快照
scripts/       启动、演示、披露与验证脚本
docs/          当前方案、比赛材料与历史冻结件
.runtime/      Run 产物、日志与缓存（不入 Git）
```

## 验证

```bash
uv run pytest -q tests
uv run python benchmark/run_rw_pilot_score.py

cd web
bun run test
bun run build
```

缺少授权语料、专家冻结参考答案或有效 Provider 时，必须保留 `NOT_EVALUATED` 或显式阻断状态，不得用基础回归结果替代。

## 文档

- [参赛提交物索引](docs/submission/competition/README.md)
- [评审快速使用说明](docs/submission/competition/使用说明.md)
- [当前 API](docs/submission/API.md)
- [部署与运行](docs/submission/DEPLOYMENT.md)
- [质链 Agent 技术方案](docs/plan/质链Agent技术方案.md)（正式方案书：架构、分系统、关键技术与交付边界）
- [端到端技术路线论证](docs/plan/从材料输入到最终结论的端到端技术路线论证.md)（设计取舍与可行性）
- [工程组成速览](docs/plan/工程架构与技术方案.md)（可运行目录与启动组成，不是方案书）
- [统一业务术语清单](docs/standards/统一业务术语清单.md)
- [文档总索引](docs/README.md)

`docs/submission/stages/01-preliminary/frozen-v2.8/` 与 `docs/submission/preliminary-*` 是已发生的历史提交／操作记录，不改写为当前实现。赛段入口见 [docs/submission/README.md](docs/submission/README.md)。