# qca

**Repository Path**: ximo-aipc/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**: 7
- **Forks**: 3
- **Created**: 2026-08-02
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: ai

**Tags**: None

## README

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

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

系统规约见[技术方案](docs/plan/质链Agent技术方案.md)，可运行组成见[工程架构与技术方案](docs/plan/工程架构与技术方案.md)，现行办理与验收范围见[六阶段办理与验收](docs/plan/六阶段办理与验收.md)。本 README 是仓库入口，不替代上述文档。

当前界面已接入六阶段导航、核验和补充验证表单，但完整原始材料浏览器验收尚未完成；不得把代码、回归或材料子集走查写成完整业务流程验收。详见[提交事实基线](docs/submission/提交事实基线.md)和[六阶段办理与验收](docs/plan/六阶段办理与验收.md)。

## 背景与业务场景

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

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

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

## 要解决的问题

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

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

## 怎么解决

对外主路径是六个业务阶段：材料准备 → 关键事实确认 → 跨专业联审 → 联审发现确认 → 适用性核验与确认 → 补充验证与再审。核验、专业人员决定、验证义务和再审均按当前范围办理；跨专业联审是必要阶段，不是可选旁路。

技术上按这条主链落地：异构材料先做格式预检和本地解析，收成可回链的来源块与版本化来源索引；再抽出要求／设计／验证／交付实测四层待确认事实；可选的受控 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/`，点击「新建跨星审查任务」进入正式办理页：先在 `/competition/run/<run_id>/process?view=materials` 上传参考任务星与当前任务星原始业务材料，再按页面上的六个业务阶段连续办理，不需要切换到另一套工作台。

浏览器只保留两类入口：正式审查任务和 `/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)。

历史演进记录通过 Git 记录追溯，不作为当前实现或验收入口；当前范围以[提交事实基线](docs/submission/提交事实基线.md)为准，六阶段后续整改以[业务主流程与支线解耦改进方案](docs/plan/六阶段业务主流程与支线解耦改进方案.md)为依据。

## 当前能力

- 受控来源包：接入 PDF、DOCX、XLSX／XLS、CSV、JSON、Parquet、PNG 与 JPG，形成带块、表格单元格、JSON 指针或系统记录坐标的版本化 `SourceIndex`；同时把已登记身份规范化为 `DevelopmentTechnicalDocument`、`TestReportRecord` 与 `TestDatasetRecord`，不从自由文本猜测指标或结论。
- Agent 事实主流程：计划器按六维影响启动主 Agent、受影响专项、质疑与结果汇总；只形成待确认事实、缺项与冲突。失败后可在同一 Run 重试。人工确认后追加不可变 `InputRevision`，未经确认的模型文本不影响确定性核验。
- 核心指标必查：完整专业审查中强制安排最大输出力矩与角动量容量的四层事实核对、比较和完成检查；整体尚未评估时保留独立诊断。清单、专业知识、字段映射和批准判据分别冻结，原文遗漏与阶段限制不虚记完成。实现及本轮 A/B 原件验收边界见[有效结论增强计划第 14 节](docs/plan/验证证据适用性有效结论形成原因剖析与通用增强计划.md#14-核心指标必查清单首轮实现与验收记录2026-09-17)。
- 外部领域配置：统一位于 `config/`，按领域或产品分子目录；通过 `QCA_DOMAIN_CONFIG_FILE` 指定单一 JSON，直接配置必查清单、专业知识、字段映射及独立批准判据的路径。生成新计划时重新读取，报告与核验冻结当次依据。默认文件为 [`domain.v1.json`](config/reaction_wheel/domain.v1.json)，用法见[领域配置说明](config/reaction_wheel/README.md#外部领域配置-json)。
- 飞轮适用性：变化事件、对象身份、六维比较、证据级五类候选与证据谱系；同一次 `SYN-FW → SYN-FW-B` 变化可因历史证据不同形成继承类、差异验证、重新验证、不可判定或尚未评估状态。
- 跨专业复用：热控、结构、电子单机以合成规则薄插件复用同一六维公共内核；这证明代码级扩展方式，不代表三个专业已形成完整产品或批准判据。
- 企业数据准备：PLM、MES、TDM 与质量管理系统已有只读离线快照契约和合成夹具；尚未连接生产系统，也不回写源系统。
- 义务与复算：义务建议、受控隔离执行、回填与受影响部分再审。
- 人工责任与评测：独立签发身份、人工决定记录、操作链、产物完整性校验和比赛评测报告；没有专家冻结参考答案、人工基线或授权真实任务时，业务效果保持 `NOT_EVALUATED`。

## 目录

```text
backend/       飞轮 API、应用服务、领域判据与保留的解析底座
web/           首页、六阶段正式办理页与只读可视化回放
tests/         当前飞轮组成的自动化测试
benchmark/     飞轮 W9 五项验收评分
examples/      飞轮材料、合成试点与企业系统离线快照
scripts/       启动、演示、披露与验证脚本
docs/          当前方案、交付说明与历史冻结件
.runtime/      Run 产物、日志与缓存（不入 Git）
```

## 验证

```bash
# 首次安装；声明与锁文件不一致时退出，不改锁
bash scripts/install_locked.sh

# 验证已安装环境：锁文件、后端全量/W9、前端类型/静态检查/测试/构建
bash scripts/verify.sh
```

可用 `--backend` 或 `--web` 只检查一侧；验证不会安装依赖，结果和环境指纹写入 `.runtime/verification/`。如需使用独立 Python 环境，通过 `UV_PROJECT_ENVIRONMENT` 指定。浏览器原始材料验收从 `scripts/acceptance/run_rw_six_stage_acceptance.sh preflight` 开始，按脚本 `--help` 列出的检查点顺序执行；材料与覆盖范围见 [部署说明](docs/submission/DEPLOYMENT.md)。

缺少授权语料、专家冻结参考答案或有效 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)。