feat:项目接口调整

shuishen

2 days ago dc6860d3f666ea9d826f699ef324de9a41a1c379

feat:项目接口调整

 PROJECT_CONTEXT.md

@@ -78,6 +78,14 @@
| `15-trajectory-analysis` | Runnable CPU Demo verified | C capability consuming timestamped tracks: spatial metrics, DBSCAN and explicit behavior rules; not a built-in `geoai-py` function. |
| `02` through `14`, `16` through `18` | Directory and initial README only | No verified local Demo yet. Start each one through `$geoai-capability-builder`. |

## 项目算法方案层

- 新增 `solutions/`：它是 C 类项目算法编排层，引用 `capabilities/` 中已验证的原子能力，不复制模型实现。
- 新增 `solutions/mining-inspection/`：对应瑶岗仙二期巡查需求，当前只建立两个试点骨架：`01-person-safety` 和 `02-drainage-blockage`。
- 两个试点均为 `scaffold`，没有运行脚本、模型下载或产品告警接入；它们明确记录了引用能力、数据前提、阻塞条件、预期输出和非目标。
- `shared/configs/solution-result.schema.json` 规定项目算法输出必须区分模型观察结果与供人工复核的事件候选。
- 其余矿山需求先保留在 `solutions/mining-inspection/README.md` 索引中，待基础能力和现场数据满足条件后再创建专项目录。

## Object Detection Snapshot

Target classes: people, vehicles, and trees.

 README.md

@@ -12,6 +12,7 @@
geoai-workbench/
|-- apps/             # 本地实验控制台等独立界面
|-- capabilities/     # 一个能力一个目录
|-- solutions/        # 多能力组合的项目算法方案
|-- requirements/     # 跨能力共享的 Python 依赖
|-- scripts/          # 环境初始化和检查脚本
|-- shared/           # 数据、模型、配置和输出
@@ -80,6 +81,13 @@

完整映射见 `capabilities/README.md` 和规划工作簿中的“能力映射”工作表。

## 项目算法方案层

`capabilities/` 维护可独立验证的原子能力；`solutions/` 维护面向业务场景的组合
算法方案。一个方案可以引用检测、分割、变化、测量和风险规则等多个能力，但不重复
复制模型代码。当前已建立 `solutions/mining-inspection/`，优先准备人员安全识别和
排洪沟堵塞识别两个试点骨架。

## 新对话继续工作

新建 Codex 对话时，把工作目录选择为本项目根目录，然后使用个人 Skill

 shared/configs/README.md

@@ -2,3 +2,6 @@

存放坐标系、业务类别、风险等级、数据字段映射等跨能力配置。

`solution-result.schema.json` 定义项目算法方案层的统一结果顶层字段。它要求每次
运行保留模型/环境限制、原始观察结果、供人工复核的事件候选，以及可查看的结果
文件路径；不把算法事件直接表述为最终业务或安全结论。

 shared/configs/solution-result.schema.json

New file
@@ -0,0 +1,81 @@
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "GeoAI Project Solution Result",
  "description": "Project-solution orchestration result. Events are candidates for human review, not final safety or compliance conclusions.",
  "type": "object",
  "required": [
    "run_metadata",
    "observations",
    "events",
    "artifacts"
  ],
  "properties": {
    "run_metadata": {
      "type": "object",
      "required": [
        "solution_id",
        "created_at",
        "input_count",
        "device",
        "limitations"
      ],
      "properties": {
        "solution_id": { "type": "string" },
        "created_at": { "type": "string", "format": "date-time" },
        "input_count": { "type": "integer", "minimum": 0 },
        "device": { "type": "string" },
        "capability_versions": { "type": "object" },
        "elapsed_seconds": { "type": "number", "minimum": 0 },
        "limitations": {
          "type": "array",
          "items": { "type": "string" }
        }
      }
    },
    "observations": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["observation_id", "class_name", "confidence"],
        "properties": {
          "observation_id": { "type": "string" },
          "class_name": { "type": "string" },
          "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
          "geometry": { "type": "object" },
          "properties": { "type": "object" }
        }
      }
    },
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["event_id", "status", "rule_hits"],
        "properties": {
          "event_id": { "type": "string" },
          "status": { "const": "candidate_for_review" },
          "severity": { "type": "string" },
          "rule_hits": {
            "type": "array",
            "items": { "type": "string" }
          },
          "observation_ids": {
            "type": "array",
            "items": { "type": "string" }
          }
        }
      }
    },
    "artifacts": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["kind", "path"],
        "properties": {
          "kind": { "type": "string" },
          "path": { "type": "string" }
        }
      }
    }
  }
}

 solutions/README.md

New file
@@ -0,0 +1,49 @@
# 项目算法方案层

`solutions/` 用于组织面向具体业务场景的项目算法。它不重复实现模型，也不替代
`capabilities/` 中的原子能力，而是定义多个能力如何按固定输入、输出和规则组合。

## 与能力库的关系

```text
capabilities/  -> 可独立验证的原子能力
solutions/     -> 组合能力形成的项目算法方案
apps/          -> 本地实验控制台或后续产品接入界面
```

项目算法通常属于 C 类产品能力：它会消费 A 类直接能力（检测、分割、分类、变化
检测）和 B 类组合能力（测量、三维、异常检测）的结果，再经空间规则生成事件建议。
不得将整个项目算法表述为 `geoai-py` 的单一内置接口。

## 目录约定

```text
solutions/
`-- <业务域>/
    |-- README.md             # 场景、需求映射和成熟度
    `-- <编号>-<项目算法>/
        |-- README.md         # 方案说明、数据前提和验收标准
        `-- solution.json     # 能力依赖、步骤、输入、输出和边界
```

`solution.json` 是编排声明，不代表该算法已可运行。只有引用的能力已通过样本验证，
并且输入数据、空间规则和输出协议齐备后，才可以为方案增加实际运行脚本或控制台入口。

## 统一结果协议

所有项目算法组合应遵循 `shared/configs/solution-result.schema.json` 的顶层字段：

- `run_metadata`：方案、版本、模型、设备、输入和运行限制。
- `observations`：模型或空间分析发现的原始对象/图斑。
- `events`：依据业务规则生成的告警候选，不等同于最终人工确认结论。
- `artifacts`：标注图、GeoJSON、掩膜、报告等可查看产物。

## 当前方案

| 业务域 | 方案 | 状态 |
| --- | --- | --- |
| 矿山巡检 | 人员安全识别 | 试点骨架，等待安全帽样本、危险区域和告警规则。 |
| 矿山巡检 | 排洪沟堵塞识别 | 试点骨架，等待沟道边界、堵塞样本和严重度口径。 |

索道安全、爆破警戒热成像、边坡、尾矿库渗漏、竖井和另一类排洪沟需求仍保留在
矿山巡检方案索引中，待基础能力和现场数据满足条件后再创建专项目录。

 solutions/mining-inspection/01-person-safety/README.md

New file
@@ -0,0 +1,37 @@
# 人员安全识别

## 业务目标

从无人机巡检影像中识别人员，判断是否佩戴安全帽，并结合危险区域或禁入区域生成
人工复核用的安全事件候选。

## 方案分类

- A 类直接能力：人员和安全帽目标检测、影像切片、结果导出。
- B 类组合能力：小目标切片、坐标转换、人员与区域的空间关系判断。
- C 类项目编排：未佩戴安全帽/进入危险区域的事件规则、告警等级和平台处置。

## 当前成熟度

`01-object-detection` 已验证普通 RGB 无人机影像中的人员候选检测，但尚未具备
安全帽类别模型，也未具备地理坐标和危险区域规则。因此本方案当前仅为可追溯的
编排骨架，不可用于正式告警。

## 必需输入

- 正常、未佩戴和遮挡情况下的人员/安全帽原始图片或视频。
- 图片对应的拍摄高度、GSD 和相机信息。
- 危险区域或禁入区域 GeoJSON；若只需影像告警，可暂不提供。
- 告警等级、允许漏报/误报范围和人工复核流程。

## 预期输出

- 带人员和安全帽框的标注图。
- `observations`：人员、安全帽、位置、置信度和关联关系。
- `events`：疑似未佩戴安全帽、疑似进入危险区域等事件候选及命中规则。
- `artifacts`：标注图、JSON，以及有地理坐标时的 GeoJSON。

## 验收前提

先使用固定的真实正负样本集，分别统计人员检出率、安全帽识别率、误报、漏报和
单图/目录处理耗时；未完成这项评估前不得接入正式安全告警。

 solutions/mining-inspection/01-person-safety/solution.json

New file
@@ -0,0 +1,58 @@
{
  "solution_id": "mining-inspection.person-safety",
  "name": "人员安全识别",
  "status": "scaffold",
  "classification": "C",
  "capability_references": [
    {
      "id": "01-object-detection",
      "role": "人员与安全帽候选检测",
      "status": "partial",
      "note": "当前仅验证人员候选；安全帽类别尚未实现。"
    },
    {
      "id": "03-attribute-classification",
      "role": "安全帽佩戴状态判定",
      "status": "planned"
    },
    {
      "id": "06-spatial-reasoning",
      "role": "人员与危险区域的包含、距离和归属判断",
      "status": "planned"
    },
    {
      "id": "07-risk-rule-engine",
      "role": "事件候选、告警等级和命中原因生成",
      "status": "planned"
    }
  ],
  "inputs": [
    "无人机 RGB 图片或视频帧",
    "可选：有效坐标系的正射影像与危险区域 GeoJSON",
    "安全帽类别样本与业务告警规则"
  ],
  "pipeline": [
    "影像质量检查与切片",
    "人员/安全帽目标检测",
    "人员与安全帽关联",
    "可选：空间围栏判断",
    "风险规则计算与人工复核事件输出"
  ],
  "outputs": [
    "run_metadata",
    "observations",
    "events",
    "artifacts"
  ],
  "blocking_conditions": [
    "缺少安全帽正负样本",
    "缺少危险区域边界或像素区域定义",
    "缺少告警阈值与人工复核流程"
  ],
  "out_of_scope": [
    "无人机自动悬停",
    "机载喊话",
    "工单派发",
    "最终违规或安全责任认定"
  ]
}

 solutions/mining-inspection/02-drainage-blockage/README.md

New file
@@ -0,0 +1,36 @@
# 排洪沟堵塞识别

## 业务目标

识别排洪沟、箱涵口及其周边的杂草、淤泥、砂石、建筑垃圾或漂浮物等疑似堵塞物，
结合沟道边界、堵塞面积和严重度规则，生成汛期巡检的维护事件候选。

## 方案分类

- A 类直接能力：语义/实例分割、目标检测、变化检测、影像切片和结果导出。
- B 类组合能力：沟道与堵塞物面积测量、连续区段合并、地理坐标转换和多期对比。
- C 类项目编排：堵塞严重度、汛期风险等级、告警和维护建议。

## 当前成熟度

`02-semantic-mapping`、`04-spatial-measurement` 和 `07-risk-rule-engine` 尚未实现
本地 Demo。因此该方案不运行模型，只固化后续需要连接的能力、数据和结果协议。

## 必需输入

- 排洪沟和箱涵口的 RGB 原图，优先提供正射 GeoTIFF。
- 沟道、箱涵口和巡检范围的 GeoJSON 或测绘边界。
- 正常、轻度、中度、重度堵塞的历史照片及人工标注。
- 堵塞面积、长度、覆盖比例或箱涵口遮挡比例等严重度口径。

## 预期输出

- 沟道/箱涵口分割掩膜、疑似堵塞区域和标注图。
- `observations`：堵塞物类别、面积、长度、覆盖比例和置信度。
- `events`：疑似堵塞事件、严重等级、命中阈值和维护建议。
- `artifacts`：掩膜、GeoJSON、标注图、统计 JSON 和运行元数据。

## 验收前提

应固定一组正常与不同严重度堵塞样本，分别评估沟道分割、堵塞检出、严重度分级、
面积误差、漏报、误报和单次巡检处理时长。

 solutions/mining-inspection/02-drainage-blockage/solution.json

New file
@@ -0,0 +1,62 @@
{
  "solution_id": "mining-inspection.drainage-blockage",
  "name": "排洪沟堵塞识别",
  "status": "scaffold",
  "classification": "C",
  "capability_references": [
    {
      "id": "02-semantic-mapping",
      "role": "沟道、箱涵口和疑似堵塞区域分割",
      "status": "planned"
    },
    {
      "id": "01-object-detection",
      "role": "垃圾、漂浮物和大型障碍物候选检测",
      "status": "partial",
      "note": "当前目标类别不包含项目堵塞物。"
    },
    {
      "id": "00-change-detection",
      "role": "多期沟道与堵塞范围变化对比",
      "status": "existing_product_only"
    },
    {
      "id": "04-spatial-measurement",
      "role": "堵塞面积、长度、覆盖比例和影响范围计算",
      "status": "planned"
    },
    {
      "id": "07-risk-rule-engine",
      "role": "严重度分级、汛期风险和维护建议生成",
      "status": "planned"
    }
  ],
  "inputs": [
    "无人机 RGB 图片或正射 GeoTIFF",
    "沟道、箱涵口和巡检范围边界",
    "堵塞正负样本、严重度标注与业务阈值"
  ],
  "pipeline": [
    "影像质量检查与正射/切片准备",
    "沟道和箱涵口分割",
    "堵塞物检测或异常区域分割",
    "多期变化和面积/长度测量",
    "严重度规则计算与人工复核事件输出"
  ],
  "outputs": [
    "run_metadata",
    "observations",
    "events",
    "artifacts"
  ],
  "blocking_conditions": [
    "缺少沟道和箱涵口边界",
    "缺少不同严重度的历史堵塞样本",
    "缺少堵塞分级和告警阈值"
  ],
  "out_of_scope": [
    "实际疏通作业控制",
    "工单派发",
    "防洪安全责任认定"
  ]
}

 solutions/mining-inspection/README.md

New file
@@ -0,0 +1,35 @@
# 矿山巡检项目算法方案

本目录对应《瑶岗仙二期巡查需求分析表》中的矿山巡检需求。每一项方案以无人机
影像或地理空间数据为输入，组合 GeoAI 原子能力、空间判断和业务规则，输出可供
平台展示和人工复核的事件候选。

## 需求映射

| 需求算法 | 主要组合能力 | 当前状态 |
| --- | --- | --- |
| 人员安全识别 | `01-object-detection` + `03-attribute-classification` + `06-spatial-reasoning` + `07-risk-rule-engine` | 已创建试点骨架 |
| 索道安全感知 | 缺陷分割 + 异常检测 + 三维测量 + 资产健康 | 待明确检测对象和采集方式 |
| 爆破警戒热成像巡查 | 热成像人员检测 + 空间围栏 + 风险规则 | 待取得热成像样本和警戒区 |
| 边坡监测 | `00-change-detection` + 三维点云 + 空间测量 | 待修正需求描述并提供样本 |
| 排洪沟巡查 | `02-semantic-mapping` + 检测 + 测量 + 风险规则 | 已创建堵塞识别试点骨架 |
| 尾矿库矿浆渗漏识别 | 水体分割/分类 + 异常/变化检测 | 待取得真实渗漏样本和传感器条件 |
| 竖井堵塞及损坏识别 | 检测/分割 + 异常检测 + 三维测量 | 待界定设施范围与损坏定义 |
| 排洪沟堵塞识别 | `02-semantic-mapping` + `00-change-detection` + `04-spatial-measurement` + `07-risk-rule-engine` | 与排洪沟巡查共建 |

## 统一处理链路

```text
无人机采集 / 正射影像 / 热成像 / 三维数据
    -> 原子能力：检测、分割、分类、变化、测量、异常
    -> 空间判断：位置、围栏、面积、距离、归属
    -> 业务规则：阈值、严重等级、事件建议
    -> 结果协议：标注图、JSON、GeoJSON、事件候选、运行元数据
```

## 方案实施规则

- 先验证原子能力，再连接方案步骤；禁止用未验证模型直接批处理项目数据。
- 事件是算法候选，除非业务明确授权，不应直接表述为事故、违规或最终安全结论。
- JPEG 输出为像素坐标；需要地图定位、电子围栏或面积计算时，必须提供有效坐标系的 GeoTIFF/GeoJSON/测绘数据。
- 自动悬停、喊话、告警推送、工单和飞行任务调整属于产品集成范围，不在本目录直接实现。