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
2026-04-30 15:10:41 +08:00
parent 8f05a7c188
commit 4d75b2e251
185 changed files with 21071 additions and 1605 deletions
--- a/docs_v1.0/STANDARDS/DOCS_STANDARD.md
+++ b/docs_v1.0/STANDARDS/DOCS_STANDARD.md
@@ -2,17 +2,27 @@
 document_type: "standard_doc"
 service: "MOMENTRY_CORE"
 title: "文件創建規範"
-date: "2026-03-18"
-version: "V1.0"
+date: "2026-04-27"
+version: "V2.0"
 status: "active"
 owner: "Warren"
 created_by: "OpenCode"
 tags:
-  - "文件創建規範"
+  - "docs-standard"
+  - "ai-agent-friendly"
+  - "yaml-frontmatter"
+  - "rag-optimization"
 ai_query_hints:
  - "查詢 文件創建規範 的內容"
  - "文件創建規範 的主要目的是什麼？"
  - "如何操作或實施 文件創建規範？"
+  - "AI Agent 友好規範要求"
+  - "YAML Frontmatter 必需字段"
+  - "ai_query_hints 编寫規範"
+  - "tags 编寫規範"
+  - "document_type 完整類型列表"
+related_documents:
+  - "STANDARDS/DOCS_STANDARD_IMPROVEMENT_PROPOSAL_2026_03_27.md"
 ---

 # 文件創建規範
@@ -21,7 +31,7 @@ ai_query_hints:
 |------|------|
 | 建立者 | Warren |
 | 建立時間 | 2026-03-18 |
-| 文件版本 | V1.0 |
+| 文件版本 | V2.0 |

 ---

@@ -30,6 +40,7 @@ ai_query_hints:
 | 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
 |------|------|------|--------|-----------|
 | V1.0 | 2026-03-18 | 創建文件規範 | Warren | OpenCode / MiniMax M2.5 |
+| V2.0 | 2026-04-27 | 添加 AI Agent 友好完整規範（10.6-10.12） | OpenCode | GLM-5 |

 ---

@@ -668,3 +679,312 @@ YAML Frontmatter 與文件內部的 Markdown 頂部資訊表必須保持數據
 - [ ] `document_type` 和 `service` 已正確設定
 - [ ] `tags` 和 `ai_query_hints` 已填寫相關內容
 - [ ] YAML Frontmatter 與 Markdown 頂部資訊表內容一致
+
+---
+
+### 10.6 document_type 完整類型列表
+
+文件類型必須使用以下標準化枚舉值：
+
+| document_type | 中文說明 | 適用場景 | 範例檔名 |
+|---------------|----------|----------|----------|
+| `standard_doc` | 規範文件 | 定義標準、規則、流程 | `DOCS_STANDARD.md` |
+| `architecture_design` | 架構設計 | 系統架構、模組設計 | `JOB_WORKER_IMPLEMENTATION_PLAN.md` |
+| `reference_doc` | 參考文件 | API 參考、字段規格 | `PROCESSING_STATUS_JSONB_SPEC.md` |
+| `install_guide` | 安裝指南 | 服務安裝步驟 | `INSTALL_POSTGRESQL.md` |
+| `develop_guide` | 開發指南 | 開發流程、最佳實踐 | `DEVELOP_API.md` |
+| `plan` | 計畫文件 | 實作計畫、時程規劃 | `*_PLAN.md` |
+| `rca` | 根本原因分析 | 事件調查、根因分析 | `RCA_*.md` |
+| `incident` | 事件報告 | 問題報告、處理紀錄 | `INCIDENT_*.md` |
+| `change` | 變更紀錄 | 配置變更、版本更新 | `CHANGE_*.md` |
+| `template` | 模板文件 | 文件模板、範本 | `TEMPLATE_*.md` |
+| `spec` | 規格文件 | 技術規格、接口定義 | `*_SPEC.md` |
+| `design` | 設計文件 | 功能設計、方案設計 | `*_DESIGN.md` |
+
+---
+
+### 10.7 ai_query_hints 编寫規範
+
+#### 10.7.1 编寫原则
+
+| 原則 | 說明 |
+|------|------|
+| **覆蓋核心問題** | 查詢提示應覆蓋文件的核心內容和常見問題 |
+| **使用自然語言** | 提示應使用用戶可能問的自然語言句式 |
+| **包含關鍵術語** | 提示應包含文件中的關鍵術語和專有名詞 |
+| **多角度覆蓋** | 提示應從不同角度描述文件內容（目的、操作、結構） |
+
+#### 10.7.2 提示句式範本
+
+| 句式類型 | 範本 | 範例 |
+|----------|------|------|
+| **內容查詢** | `查詢 <文件標題> 的內容` | `查詢 processing_status JSONB 字段規範的內容` |
+| **目的查詢** | `<文件標題> 的主要目的是什麼？` | `processing_status JSONB 字段規範的主要目的是什麼？` |
+| **操作查詢** | `如何操作或實施 <文件標題>？` | `如何查詢 processing_status JSONB 字段？` |
+| **結構查詢** | `<文件標題> 的結構定義` | `processing_status JSONB 結構定義` |
+| **字段查詢** | `<關鍵字段> 說明` | `pre_chunks_summary 結構說明` |
+| **流程查詢** | `<流程名稱> 流程` | `Agent 進度追蹤流程` |
+
+#### 10.7.3 数量建议
+
+| 项目 | 数量 |
+|------|------|
+| 最少數量 | 3-5 個查詢提示 |
+| 建議數量 | 5-8 個查詢提示 |
+| 最多數量 | 10 個查詢提示（避免冗余） |
+
+#### 10.7.4 範例
+
+```yaml
+ai_query_hints:
+  - "查詢 processing_status JSONB 字段規範的內容"
+  - "processing_status JSONB 結構定義"
+  - "如何查詢 processing_status JSONB 字段"
+  - "pre_chunks_summary 結構說明"
+  - "chunks_summary 結構說明"
+  - "Agent 進度追蹤字段"
+  - "processing_status SQL 查詢範例"
+  - "processing_status Rust 實作範例"
+```
+
+---
+
+### 10.8 tags 编寫規範
+
+#### 10.8.1 标签选择原则
+
+| 原則 | 說明 |
+|------|------|
+| **核心主题** | 标签应反映文件的核心主题 |
+| **关键术语** | 标签应包含文件中的关键术语 |
+| **分类标签** | 标签应包含文件类型分类（如 `规范`, `设计`, `API`） |
+| **技术栈** | 标签应包含涉及的技术栈（如 `rust`, `postgresql`, `jsonb`） |
+| **关联模块** | 标签应包含关联的系统模块（如 `processor`, `rule`, `agent`） |
+
+#### 10.8.2 标签命名规范
+
+| 规范 | 說明 |
+|------|------|
+| **使用小写英文** | 标签统一使用小写英文（便于检索） |
+| **使用连字符** | 多词标签使用连字符分隔（如 `ai-agent`） |
+| **避免中文标签** | 不建议使用中文标签（AI 检索效率低） |
+
+#### 10.8.3 标签分类建议
+
+| 分类 | 範例标签 |
+|------|----------|
+| **文件类型** | `standard`, `spec`, `design`, `guide`, `plan`, `rca`, `template` |
+| **技术栈** | `rust`, `postgresql`, `redis`, `mongodb`, `qdrant`, `jsonb`, `vector` |
+| **系统模块** | `processor`, `rule`, `agent`, `chunk`, `embedding`, `api`, `worker` |
+| **核心概念** | `processing-status`, `progress-tracking`, `resume`, `checkpoint` |
+| **数据结构** | `pre-chunks`, `chunks`, `frames`, `vectors` |
+
+#### 10.8.4 数量建议
+
+| 项目 | 数量 |
+|------|------|
+| 最少數量 | 3-5 個标签 |
+| 建議數量 | 5-8 個标签 |
+| 最多數量 | 10 個标签（避免冗余） |
+
+#### 10.8.5 範例
+
+```yaml
+tags:
+  - "jsonb"
+  - "processing-status"
+  - "progress-tracking"
+  - "processor"
+  - "rule"
+  - "agent"
+```
+
+---
+
+### 10.9 RAG 檢索優化建議
+
+#### 10.9.1 文件內容結構優化
+
+| 建議 | 說明 |
+|------|------|
+| **標題清晰** | 使用明確的標題描述文件內容 |
+| **段落分明** | 使用 `---` 分隔主要章節，提升段落識別 |
+| **表格標準** | 使用標準表格格式，避免嵌套表格 |
+| **代碼標註** | 代碼區塊標註語言類型（提升代碼檢索） |
+| **避免冗余** | 删除重複內容，降低向量噪音 |
+
+#### 10.9.2 关键术语定义表
+
+建議在文件中包含關鍵術語定義表，提升術語檢索效果：
+
+```markdown
+## 關鍵術語定義
+
+| 術語 | 定義 |
+|------|------|
+| processing_status | JSONB 字段，追蹤處理進度 |
+| phase | 當前階段（PROCESSING, COMPLETED, FAILED） |
+| pre_chunks_summary | pre_chunks 表絕計（按處理器） |
+| chunks_summary | chunks 表絕計（按 Rule） |
+```
+
+#### 10.9.3 语义一致性
+
+| 建議 | 說明 |
+|------|------|
+| **術語統一** | 同一概念使用相同術語（如 `processing_status` 不混用 `status`） |
+| **缩写统一** | 同一缩写使用相同形式（如 `ASR` 不混用 `asr`） |
+| **避免歧义** | 避免使用多義詞，或明確定義多義詞 |
+
+#### 10.9.4 向量化效果优化
+
+| 建議 | 說明 |
+|------|------|
+| **段落长度适中** | 单段落建议 100-500 字，避免过长段落 |
+| **关键信息前置** | 将关键信息放在段落开头 |
+| **避免空内容** | 删除空白章节或占位内容 |
+
+---
+
+### 10.10 related_documents 字段（建議）
+
+#### 10.10.1 字段定义
+
+| 字段 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `related_documents` | list | No | 相關文件列表（建議填寫以建立知識圖谱） |
+
+#### 10.10.2 编寫规范
+
+| 规范 | 說明 |
+|------|------|
+| **使用相对路径** | 使用相对路径引用文件（如 `REFERENCE/PROCESSING_STATUS_JSONB_SPEC.md`） |
+| **包含说明** | 每个引用包含简要说明（可选） |
+| **数量适中** | 建议 3-5 个相关文件引用 |
+
+#### 10.10.3 範例
+
+```yaml
+related_documents:
+  - "ARCHITECTURE/JOB_WORKER_IMPLEMENTATION_PLAN.md"
+  - "REFERENCE/VIDEO_PROCESSING_SPEC.md"
+  - "ARCHITECTURE/PROCESSING_PIPELINE.md"
+  - "AI_AGENTS/CORE/AGENT_SPEC.md"
+```
+
+---
+
+### 10.11 AI Agent 友好完整範例
+
+以下為符合 AI Agent 友好規範的完整文件範例：
+
+```yaml
+---
+document_type: "reference_doc"
+service: "MOMENTRY_CORE"
+title: "processing_status JSONB 字段規範"
+date: "2026-04-27"
+version: "V1.2"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+tags:
+  - "jsonb"
+  - "processing-status"
+  - "progress-tracking"
+  - "processor"
+  - "rule"
+  - "agent"
+ai_query_hints:
+  - "查詢 processing_status JSONB 字段規範的內容"
+  - "processing_status JSONB 結構定義"
+  - "如何查詢 processing_status JSONB 字段"
+  - "pre_chunks_summary 結構說明"
+  - "chunks_summary 結構說明"
+  - "Agent 進度追蹤字段"
+  - "processing_status SQL 查詢範例"
+  - "processing_status Rust 實作範例"
+related_documents:
+  - "ARCHITECTURE/JOB_WORKER_IMPLEMENTATION_PLAN.md"
+  - "REFERENCE/VIDEO_PROCESSING_SPEC.md"
+  - "ARCHITECTURE/PROCESSING_PIPELINE.md"
+---
+
+# processing_status JSONB 字段規範
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-04-27 |
+| 文件版本 | V1.2 |
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.2 | 2026-04-27 | 從 VARCHAR 改為 JSONB，支持多層級進度追蹤 | OpenCode | GLM-5 |
+
+---
+
+## 概述
+
+從 V1.2 起，`videos` 表的 `processing_status` 字段改為 **JSONB** 格式。
+
+---
+
+## 關鍵術語定義
+
+| 術語 | 定義 |
+|------|------|
+| processing_status | JSONB 字段，追蹤處理進度 |
+| phase | 當前階段（PROCESSING, COMPLETED, FAILED） |
+| pre_chunks_summary | pre_chunks 表絕計（按處理器） |
+| chunks_summary | chunks 表絕計（按 Rule） |
+
+---
+
+## 1. JSONB 結構定義
+
+...
+```
+
+---
+
+### 10.12 文件審查清單（AI Agent 友好完整版）
+
+創建新文件時，必須確認以下所有檢查項目：
+
+#### 必需項目（P0）
+
+- [ ] 文件包含標準 YAML Frontmatter（位於文件開頭）
+- [ ] `document_type` 使用標準化枚舉值（見 10.6）
+- [ ] `service` 設為 `MOMENTRY_CORE` 或服務名稱（全大寫）
+- [ ] `title` 清晰描述文件內容
+- [ ] `date` 使用 YYYY-MM-DD 格式
+- [ ] `status` 設為 `active` | `completed` | `archived`
+- [ ] `owner` 設為負責人姓名
+- [ ] `created_by` 設為建立者姓名
+- [ ] `version` 使用 V1.0 格式
+
+#### 建議項目（P1）
+
+- [ ] `tags` 包含 5-8 個標籤（見 10.8）
+- [ ] `ai_query_hints` 包含 5-8 個查詢提示（見 10.7）
+- [ ] `related_documents` 包含 3-5 個相關文件（見 10.10）
+
+#### 同步要求（P0）
+
+- [ ] YAML Frontmatter 與 Markdown 頂部資訊表內容一致
+- [ ] YAML `title` 與 Markdown `#` 標題一致
+- [ ] YAML `version` 與 Markdown 文件版本一致
+- [ ] YAML `date` 與 Markdown 建立時間一致
+
+#### RAG 優化（P1）
+
+- [ ] 包含關鍵術語定義表（見 10.9.2）
+- [ ] 使用標準表格格式
+- [ ] 代碼區塊標註語言類型
+- [ ] 段落使用 `---` 分隔
+- [ ] 術語使用一致（無混用）