# astralpha

**Repository Path**: ximo-ai4s/astralpha

## Basic Information

- **Project Name**: astralpha
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-27
- **Last Updated**: 2026-10-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# astralpha（星元）

星元的工程仓库。质链 Agent 是其中一项功能，处理商业航天任务的技术状态与验证证据，代码在 `backend/app/qca/`。

当前推进第 5–6 轮技术链与原貌材料验证。已建立原生办理依据、不可变阶段记录、调查请求与报告，连接事实、批准判据、双指标确定性核验和专业签认接口。不完整材料可以从当前修订创建原文调查依据，引用标记为未确认摘录；人工确认调查建议不创建事实，缺失专业输入仍阻断评估。Agent 通过可删执行插件和 `llm.default` 执行，原生后台提供对应工作流页面。A/B/C 四份原貌业务材料（用户确认）用于有限来源子集的技术复跑；真实模型未配置，真实专业人员与浏览器业务办理尚未验收。飞轮条件定义现经公开版本契约绑定原生批准判据；具体未满足条件由专业人员确认后派发，后继显式承接同一义务，补证登记核对实际新原件且不要求后继先整体准备通过。独立批准的成功判据、关闭责任权限和人工关闭仍缺，条件继承继续限制整体准备，第5–6轮尚未完成业务验收。整体业务状态保持尚未评估，范围见设计方案第 6、9 节。

解析由正式 Run 的 Worker 从登记原件回读后执行，受材料开关控制。独立 HTTP 解析/OCR 提交入口仍返回统一 503 与尚未评估说明，不在 Web 请求进程中执行解析；Provider 注册不计为业务能力完成。

第一批办理辅助沿用现有权限、事务、Run/outbox、Celery/Beat 和 Vben 页面：上传同事务登记解析任务，支持上传请求键重试；候选按实际原文字段和值整理重复及差异，预检查仅核对材料和正式执行前提。原文调查依据可明确发起来源受限辅助调查，自动冻结可见摘录及覆盖限制，不推进人工阶段。集中待办、连续办理引导和带逐件摘要的 JSON 审核包根据原生记录生成，不另存一套任务。关键事实、专业批准、条件关闭和最终签认均由人工负责；自动化默认关闭，真实模型与浏览器测试登录仍待授权。技术范围与验证见设计方案第 9.3 节。

QCA单次工作台复用现有工作流路由、菜单和人工动作，提供事项与六阶段上下文、实际任务与待办、原文候选对照、补证证据登记和审核包；独立关闭及最终签认保持禁用。生产页面读取真实API，不包含设计演示数据。技术实现与Git就绪性记录见设计方案第 9.4 节；浏览器登录、真实模型和专业业务验收仍待完成。

## 当前组成

| 路径 | 内容 |
| --- | --- |
| `backend/` | 星元平台后端，上游基线 v1.15.1（`a0b3f02`，2026-08-16） |
| `ui/` | 星元平台前端，上游基线 `9f4040c`（2026-09-20），应用 `apps/web-antdv-next` |
| `backend/app/qca/` | 审查内核接口、业务 Model/CRUD/Service、资格与审计、正式 Run；内存 RunStore 仅供测试 |
| `backend/plugin/` | 平台自带插件，以及 `llm_gateway`、`agent_agno`、`parser_mineru`、`minio_originals`、`qca_reaction_wheel`；未配置时跳过能力注册 |
| `ui/apps/web-antdv-next/src/views/qca/` | 质链分组内的审查工作台、项目登记、材料事实、集中待办与能力状态；首次办理引导、来源核对、候选确认、不可变修订、六阶段办理和审核包；领域表单在对应插件目录，展示文案取业务术语表 |
| [重构开发计划](docs/plan/astralpha重构开发计划.md) | 当前工程建设、历史进度与验收记录 |
| [总体技术框架草案](docs/plan/星元总体技术框架与集成方案.md) | 从旧工作树保全的未来本体接入方案，已对齐平台分层与 RabbitMQ；尚未实施 |
| [公共本体与 Semantica 接入草案](docs/plan/公共本体服务与Semantica接入设计方案.md) | 未来模型、契约、适配与验收设计；不表示已有本体或 Semantica 运行能力 |
| `temp/qca/` | qca `feat/usability@b4d013f` 的只读导出，`.gitignore` 已排除 |

远程：<https://gitee.com/ximo-ai4s/astralpha.git>

## 依赖边界

`.importlinter` 里有七条契约：内核不导入插件、平台层不导入插件、插件之间互不导入，以及内核最低层、中层方向、同层独立性和业务持久化分层。平台已有的可选插件引用只按具体边排除；内核复用 JWT 时沿用同样的间接引用例外。插件在前三条契约里逐个列出，新增插件时同步维护。

```bash
uv sync
uv run lint-imports
uv run pytest backend/app/qca/tests -q
uv run python backend/scripts/check_plugin_removal.py
```

插件专用依赖保留在各自的 `requirements.txt`，执行涉及插件的检查前需安装相应依赖。正式 Run、材料链、专业核验、工作流、办理辅助与能力插件默认关闭（`QCA_RUN_ENABLED=false`、`QCA_MATERIAL_ENABLED=false`、`QCA_DOMAIN_ENABLED=false`、`QCA_WORKFLOW_ENABLED=false`、`QCA_AUTOMATION_ENABLED=false`、插件配置 `QCA_REACTION_WHEEL_ENABLED=false`、`AGENT_AGNO_ENABLED=false`），必须先完成数据库迁移、私有桶和解析配置与两层授权；部署与回退步骤见设计方案第 9.1 节。删目录脚本的快速层不连接真实数据库或消息代理；生产服务、登录与前端构建验证见 `AGENTS.md`。

A/B 技术状态对照在质链分组的专业核验页内，也可从审查工作台进入。先在同一项目事项上传两侧原件、实际解析并人工确认事实，再明确当前/参考对象、材料分类及事实对应，冻结不可变比较集；没有专业输入时仍可回查原值、差异和实际来源。专业规则与批准判据齐备后，逐项呈现要求、设计、验证、单位、有限容差、六维核验与原生专业记录。字面相同、单项候选和技术完整性均不替代专业签认、条件关闭或总体准出；缺项、取消、能力缺失和旧修订保留真实状态。比较表属于内核持久化，使用原生增量迁移 `20261005_qca_comparison`，不依赖可删除插件保存。

## 启动平台层

环境变量样例在 `backend/.env.example`，数据库默认 PostgreSQL。下列命令在仓库根目录执行。

整栈（PostgreSQL、Redis、后端及其他 compose 服务）：

```bash
docker compose up -d
```

全新开发库在准备好 PostgreSQL 和 Redis 后，可执行 `uv run astralpha init`（交互确认后会重建库表），再执行 `uv run astralpha run`。已有生产库使用原生 Alembic 增量迁移，不能执行重建初始化。

`astralpha init` 一次完成可用状态，不再需要手工 `alembic stamp`：

1. 平台与插件表由 `create_all` 建立，**不含 QCA 内核表**，随后写入平台基础数据（`init_test_data.sql`）。
2. 自动执行 `alembic upgrade head`：QCA 内核表、不可变触发器、QCA 菜单（质链目录、审查工作台、集中待办及隐藏的登记/材料页和按钮权限）与预置角色“质量审查员”都由迁移链建立，`alembic_version` 位于 head。新库与已有库走同一条迁移路径，不会出现“表已存在后再 stamp”的基线错位；再次初始化会一并清理版本表和触发器函数。
3. 执行迁移后脚本：测试审查员账号，以及各插件 SQL（如 `qca_reaction_wheel` 为该角色补充自有菜单授权）。

QCA 内核只支持 PostgreSQL；其他数据库初始化时只建平台表并给出警告，不创建缺少不可变保护的审查记录表。迁移链有新增版本时，已有库执行 `uv run astralpha alembic upgrade --revision head`。

**质链全流程授权**：当前迁移 head 为 `20261008_qca_full_review`，在质链目录下增加隐藏的“质链全流程审查”权限项（`qca:*`），并授予预置角色“质量审查员”。给用户的原生角色授予这一项，即可在默认范围内连续办理上传、材料核对、事实确认、判据批准、专业核验与后续责任环节，无需另开后台管理 `is_staff` 或逐项目配置 `reviewer`；实际判据批准和结论签认仍由本人执行。默认项目范围为**所在部门及本人创建的质链项目**，明细和原件访问随父项目校验。此授权不授予系统管理、其他部门项目或平台全数据权限；停用角色、停用权限项或撤销授权后，后续办理与后台执行重新校验。

原有分项菜单权限（如 `qca:original:add`、`qca:fact:confirm`）、平台数据范围与逐项目业务资格继续兼容。质量审查员角色仍保持数据过滤，`qca:*` 的默认范围只用于质链业务，不解除其他平台接口的数据限制。插件能力仍需安装、配置和启用；删除专业插件时相关步骤保持“尚未评估”。迁移幂等，降级只清理其记录的初始授权；管理员为其他角色附加的授权保留。

**测试账号**：开发初始化另含账号 `reviewer`（密码与 `test` 测试用户相同，已绑定“质量审查员”及“全模型本部门数据权限”）。它不具备超级管理员或平台后台管理权限；自增与雪花主键模式均关联实际测试部门。仅限开发测试，生产环境不要沿用。

**QCA 开关**：`backend/.env.example` 中的 `QCA_*_ENABLED` 默认全为 `false`，对应接口返回 503“尚未启用”，相关步骤保持“尚未评估”。办理一份审查按阶段至少需要：`QCA_RUN_ENABLED`（项目、事项、原件与执行单，是全部 QCA 接口的前提）；`QCA_MATERIAL_ENABLED`（材料解析与事实确认）；`QCA_DOMAIN_ENABLED` 加插件 `QCA_REACTION_WHEEL_ENABLED`（专业输入、判据与比较，缺插件时如实降级）；`QCA_WORKFLOW_ENABLED`（六阶段办理，同时依赖 `QCA_DOMAIN_ENABLED`）；`QCA_AUTOMATION_ENABLED`（审查工作台与集中待办）。`QCA_AGENT_PLAN_ENABLED`、`QCA_CALCULATION_ENABLED`、`AGENT_AGNO_ENABLED` 为可选能力，另需各自的模型与计算配置。开关之外还需私有对象存储、解析 Provider、Celery Worker 与 RabbitMQ 等运行条件，部署与回退见设计方案第 9.1 节；开启开关或授予角色本身不等于业务验收。

前端：

```bash
cd ui
pnpm install
pnpm --filter @vben/web-antdv-next dev
```

平台层许可证为 MIT，见 `LICENSE`。

2026-10-06 首批增量：已建立[能力迁移台账](docs/plan/astralpha-qca-migration-ledger.md)。核心新增不可变 DocumentIR 与原生迁移 `20261006_qca_document_ir`；同一原件可显式按确认事实/来源区域分侧，前端展示真实区域坐标及观测置信度。规则 0.6.0 增加严格方向与 degC；带来源区间只保存和展示，未批准的比较仍尚未评估。A/B/C 37 份原件、其中 12 份离线 OCR 已贯通上传/解析/来源；图意、逐数字人工核对和专业接受尚待验收，见[本轮记录](docs/validation/astralpha-qca-b1-20261006.md)。