docs: update docs_v1.0/ documentation

- Fix markdown lint issues (MD030, MD047, MD051, MD028, MD005)
- Update AI agents, architecture, implementation docs
- Add new identity, face recognition, and API documentation
- Remove deprecated face/person API guides
This commit is contained in:
Warren
2026-04-30 15:10:41 +08:00
parent 8f05a7c188
commit 4d75b2e251
185 changed files with 21071 additions and 1605 deletions

View File

@@ -198,4 +198,4 @@ The ASR processor (`scripts/asr_processor.py`) serves as the reference implement
### Version 1.0 (2025-03-27)
- Initial contract definition
- Based on ASR processor refactoring experience
- Based on ASR processor refactoring experience

View File

@@ -250,4 +250,4 @@ python3 verify_processor_compliance.py --output report.md
- Initial compliance checklist created
- 3/5 processors at 100% compliance
- Automated verification tool created
- Comprehensive documentation structure established
- Comprehensive documentation structure established

View File

@@ -39,17 +39,17 @@ ai_query_hints:
為確保所有處理器ASR, OCR, Face, YOLO, Cut產出的時間軸精確且一致本規範定義以下核心原則
1. **幀為本位 (Frame-Based)**
* 所有時間計算的**唯一權威來源**是幀編號 (`frame_number`)。
* 開始時間、結束時間、長度皆以幀為單位 (`start_frame`, `end_frame`, `length_frames`)。
1. **幀為本位 (Frame-Based)**
* 所有時間計算的**唯一權威來源**是幀編號 (`frame_number`)。
* 開始時間、結束時間、長度皆以幀為單位 (`start_frame`, `end_frame`, `length_frames`)。
2. **秒數為參考 (Timestamp is Derived)**
* 秒數 (`timestamp_sec`, `start_time_sec`) 僅供人類閱讀與外部 API 參考。
* 計算公式:`time = frame / fps`
* FPS 資訊必須與 `ffprobe` 探針結果嚴格一致。
2. **秒數為參考 (Timestamp is Derived)**
* 秒數 (`timestamp_sec`, `start_time_sec`) 僅供人類閱讀與外部 API 參考。
* 計算公式:`time = frame / fps`
* FPS 資訊必須與 `ffprobe` 探針結果嚴格一致。
3. **結構統一**
* 產出分為兩大層級:**Frame (單幀檢測)** 與 **Pre-Chunk (時間區間聚合)**
3. **結構統一**
* 產出分為兩大層級:**Frame (單幀檢測)** 與 **Pre-Chunk (時間區間聚合)**
---
@@ -121,8 +121,8 @@ ai_query_hints:
### 2.1 ASR (語音識別) -> Pre-Chunk
ASR 產出主要是文字片段,因此歸類為 `Pre-Chunk`
* **輸出檔名**: `{uuid}_asr.json`
* **結構**: Array of Pre-Chunk
* **輸出檔名**: `{uuid}_asr.json`
* **結構**: Array of Pre-Chunk
```json
[
@@ -144,8 +144,8 @@ ASR 產出主要是文字片段,因此歸類為 `Pre-Chunk`。
### 2.2 Face (人臉偵測) -> Frame
人臉位置可能每幀微動,因此以 `Frame` 記錄最精確。
* **輸出檔名**: `{uuid}_faces.json`
* **結構**: Object containing Array of Frames
* **輸出檔名**: `{uuid}_faces.json`
* **結構**: Object containing Array of Frames
```json
{
@@ -170,8 +170,8 @@ ASR 產出主要是文字片段,因此歸類為 `Pre-Chunk`。
### 2.3 OCR (文字辨識) -> Frame
通常以抽樣 (Sample) 方式進行 (如每 30 幀抽 1 幀)。
* **輸出檔名**: `{uuid}_ocr.json`
* **結構**: Array of Frames
* **輸出檔名**: `{uuid}_ocr.json`
* **結構**: Array of Frames
```json
[
@@ -191,8 +191,8 @@ ASR 產出主要是文字片段,因此歸類為 `Pre-Chunk`。
### 2.4 Cut (鏡頭切割) -> Pre-Chunk
鏡頭切割定義了場景的邊界,是典型的 Pre-Chunk。
* **輸出檔名**: `{uuid}_cuts.json`
* **結構**: Array of Pre-Chunk
* **輸出檔名**: `{uuid}_cuts.json`
* **結構**: Array of Pre-Chunk
```json
[
@@ -215,10 +215,10 @@ ASR 產出主要是文字片段,因此歸類為 `Pre-Chunk`。
為確保產出符合規範,寫入資料庫前需執行以下檢查:
1. **FPS 校驗**: JSON 中的 `fps` 必須等於 `assets` 表中 `media_info->fps` 的值。誤差允許範圍 `±0.01`
2. **幀邊界**: `start_frame` 必須 `>= 0``end_frame` 必須 `<= total_frames`
3. **時間換算驗證**:
* `abs(timestamp_sec - (frame_number / fps)) < 0.001`
1. **FPS 校驗**: JSON 中的 `fps` 必須等於 `assets` 表中 `media_info->fps` 的值。誤差允許範圍 `±0.01`
2. **幀邊界**: `start_frame` 必須 `>= 0``end_frame` 必須 `<= total_frames`
3. **時間換算驗證**:
* `abs(timestamp_sec - (frame_number / fps)) < 0.001`
---
@@ -227,9 +227,9 @@ ASR 產出主要是文字片段,因此歸類為 `Pre-Chunk`。
Processor 產出的是 **Raw Data (Pre-chunk / Frames)**
後續的 **Chunk Strategy (Rule 1/2/3)** 會讀取這些 Raw Data 並進行聚合,生成最終的 `chunks` 表記錄。
* **Input**: 多個 Pre-chunks / Frames
* **Process**: 合併 (Merge)、摘要 (Summarize)、嵌入 (Embedding)
* **Output**: `chunks` 表 (具備語意向量)
* **Input**: 多個 Pre-chunks / Frames
* **Process**: 合併 (Merge)、摘要 (Summarize)、嵌入 (Embedding)
* **Output**: `chunks` 表 (具備語意向量)
```mermaid
graph LR

View File

@@ -490,4 +490,4 @@ pub mod ocr {
*Template Version: 1.0*
*Last Updated: 2026-03-27*
*Based on: AI-Driven Processor Contract v1.0*
*Based on: AI-Driven Processor Contract v1.0*