---
document_type: "implementation_guide"
service: "MOMENTRY_CORE"
title: "AI Agent 文檔系統使用指南"
date: "2026-04-25"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "agent"
  - "文檔系統使用指南"
ai_query_hints:
  - "查詢 AI Agent 文檔系統使用指南 的內容"
  - "AI Agent 文檔系統使用指南 的主要目的是什麼？"
  - "如何操作或實施 AI Agent 文檔系統使用指南？"
---

# AI Agent 文檔系統使用指南

## 概述

本文檔為 AI Agent 提供 Momentry 維護紀錄管理系統的使用指南，旨在最大化 AI Agent 的操作效率和自動化能力。

## 核心設計原則

### 1. 雙重格式設計
- **YAML Frontmatter**: 結構化元數據，AI Agent 優先讀取
- **Markdown 表格**: 人類可讀格式，AI Agent 備用解析
- **保持同步**: 兩部分數據應保持一致

### 2. 標準化查詢模式
- 使用一致的字段名稱和值域
- 預定義查詢模板和篩選條件
- 支持複雜查詢邏輯

### 3. 自動化工作流
- 狀態變更觸發目錄移動
- 嚴重等級觸發通知
- 時間基於的自動歸檔

## 文件結構解析

### 文件名模式
```
{前綴}_{服務}_{問題}_{日期}.md
```
- **前綴**: `RCA_`, `INCIDENT_`, `CHANGE_`, `MAINTENANCE_`
- **服務**: 大寫英文，如 `WORDPRESS`, `POSTGRESQL`
- **問題**: 大寫英文+下劃線，如 `TIMEOUT_EXTERNAL_ACCESS`
- **日期**: `YYYY_MM_DD`

### 目錄結構
```
maintenance_records/
├── rca/           # 根本原因分析
├── incidents/     # 事件報告
├── changes/       # 變更紀錄
├── plans/         # 維護計畫
├── templates/     # 模板文件
├── _active/       # 進行中項目（各類型子目錄）
├── _completed/    # 已完成項目（各類型子目錄）
└── _archived/     # 已歸檔項目（各類型子目錄）
```

## YAML Frontmatter 規範

### 通用字段
```yaml
---
document_type: "rca" | "incident" | "change" | "maintenance"
service: "服務名稱"
problem: "問題簡述"
date: "YYYY-MM-DD"
severity: "P0" | "P1" | "P2" | "P3" | "P4"
status: "active" | "completed" | "archived"
current_state: "pending" | "investigating" | "resolving" | "resolved" | "closed"
owner: "負責人姓名"
created_by: "創建者姓名"
created_at: "YYYY-MM-DD HH:MM"
version: "版本號"
tags:
  - "標籤1"
  - "標籤2"
related_documents:
  - "相關文件1.md"
  - "相關文件2.md"
ai_query_hints:
  - "查詢提示1"
  - "查詢提示2"
---
```

### 類型特定字段

#### RCA (根本原因分析)
```yaml
rca_type: "technical" | "process" | "human_error"
root_cause: "根本原因描述"
resolution: "解決方案描述"
prevention: "預防措施"
```

#### Incident (事件報告)
```yaml
incident_type: "服務中斷" | "性能問題" | "安全事件" | "數據問題"
detection_method: "監控警報" | "用戶報告" | "系統日誌"
impact_level: "高" | "中" | "低"
affected_users: "受影響用戶數量"
downtime: "停機時間(分鐘)"
```

#### Change (變更紀錄)
```yaml
change_type: "配置變更" | "版本升級" | "架構調整" | "安全修補"
risk_level: "低" | "中" | "高" | "緊急"
approval_status: "pending" | "approved" | "rejected"
implementation_status: "planned" | "implementing" | "completed" | "rolled_back"
```

## 查詢語言規範

### 基本查詢語法
```
字段名: "值" [AND|OR] 字段名: "值"
```

### 查詢示例
```yaml
# 查詢所有 P0/P1 級別的活躍事件
document_type: "incident" AND severity: ("P0" OR "P1") AND status: "active"

# 查詢特定服務的所有 RCA
document_type: "rca" AND service: "n8n"

# 查詢需要審核的變更
document_type: "change" AND approval_status: "pending"

# 查詢本週創建的文件
date: ">=2026-03-20" AND date: "<=2026-03-27"
```

### 複雜查詢
```yaml
# 查詢已解決但未歸檔的 P2+ 事件
document_type: "incident" AND 
severity: (>= "P2") AND 
current_state: "resolved" AND 
status: "active"

# 查詢特定負責人的進行中項目
owner: "Warren" AND 
status: "active" AND 
current_state: ("investigating" OR "resolving")
```

## 自動化工作流

### 1. 文件創建工作流
```
1. 識別需要創建的文檔類型
2. 選擇對應模板
3. 填充 YAML frontmatter
4. 生成 Markdown 內容
5. 保存到正確目錄 (_active/)
6. 發送創建通知
```

### 2. 狀態更新工作流
```
1. 讀取文件 YAML frontmatter
2. 更新 current_state 字段
3. 如果狀態變為 "resolved" 或 "closed":
   - 更新完成時間
   - 移動文件到 _completed/
   - 發送完成通知
4. 保存更新後的文件
```

### 3. 定期歸檔工作流
```
每日執行:
1. 掃描 _completed/ 目錄
2. 檢查文件的創建日期
3. 如果超過保留期限 (RCA: 30天，事件: 30天，變更: 90天)
4. 移動文件到 _archived/
5. 更新 status: "archived"
```

### 4. 通知觸發工作流
```
事件觸發時:
1. 檢查 severity 字段
   - P0: 立即通知 (即時通訊+電話)
   - P1: 1小時內通知技術團隊
   - P2: 2小時內通知相關人員
   - P3/P4: 工作日內通知
2. 根據通知配置發送警報
```

## AI Agent 最佳實踐

### 數據提取
```python
import yaml
import re

def extract_document_metadata(file_path):
    """從文件中提取 YAML frontmatter"""
    with open(file_path, 'r', encoding='utf-8') as f:
        content = f.read()
    
    # 提取 YAML frontmatter (位於 --- 之間)
    yaml_match = re.search(r'^---\n(.*?)\n---\n', content, re.DOTALL | re.MULTILINE)
    
    if yaml_match:
        try:
            metadata = yaml.safe_load(yaml_match.group(1))
            return metadata
        except yaml.YAMLError as e:
            print(f"YAML 解析錯誤: {e}")
    
    # 備用：解析文件名
    metadata = parse_filename_metadata(file_path)
    return metadata

def parse_filename_metadata(file_path):
    """從文件名解析元數據"""
    filename = os.path.basename(file_path)
    # 解析: PREFIX_SERVICE_PROBLEM_DATE.md
    pattern = r'^([A-Z]+)_([A-Z]+)_([A-Z_]+)_(\d{4}_\d{2}_\d{2})\.md$'
    match = re.match(pattern, filename)
    
    if match:
        return {
            'document_type': match.group(1).lower(),
            'service': match.group(2),
            'problem': match.group(3),
            'date': match.group(4).replace('_', '-')
        }
    
    return {}
```

### 文件搜索
```python
import os
import glob

def search_documents(query_filters, base_dir="docs/maintenance_records"):
    """根據查詢條件搜索文件"""
    results = []
    
    # 遍歷所有子目錄
    for root, dirs, files in os.walk(base_dir):
        for file in files:
            if file.endswith('.md'):
                file_path = os.path.join(root, file)
                metadata = extract_document_metadata(file_path)
                
                # 應用查詢過濾器
                if matches_filters(metadata, query_filters):
                    results.append({
                        'path': file_path,
                        'metadata': metadata
                    })
    
    return results

def matches_filters(metadata, filters):
    """檢查元數據是否匹配查詢條件"""
    for key, expected_value in filters.items():
        if key not in metadata:
            return False
        
        actual_value = metadata[key]
        
        # 支持範圍查詢 (>=, <=, >, <)
        if isinstance(expected_value, str) and expected_value.startswith(('>=', '<=', '>', '<')):
            if not evaluate_range(actual_value, expected_value):
                return False
        elif actual_value != expected_value:
            return False
    
    return True
```

### 自動化更新
```python
def update_document_status(file_path, new_state, new_status=None):
    """更新文件狀態"""
    with open(file_path, 'r', encoding='utf-8') as f:
        content = f.read()
    
    # 更新 YAML frontmatter
    def update_yaml(match):
        yaml_content = match.group(1)
        metadata = yaml.safe_load(yaml_content)
        
        metadata['current_state'] = new_state
        if new_status:
            metadata['status'] = new_status
        
        # 如果是狀態變更，更新時間戳
        if new_state in ['resolved', 'closed']:
            metadata['resolved_at'] = datetime.now().isoformat()
        
        updated_yaml = yaml.dump(metadata, allow_unicode=True, default_flow_style=False)
        return f"---\n{updated_yaml}---\n"
    
    # 替換 YAML 部分
    updated_content = re.sub(
        r'^---\n(.*?)\n---\n',
        update_yaml,
        content,
        flags=re.DOTALL | re.MULTILINE
    )
    
    # 寫回文件
    with open(file_path, 'w', encoding='utf-8') as f:
        f.write(updated_content)
    
    # 根據狀態移動文件
    move_to_correct_directory(file_path, new_status)
```

## 目錄管理規則

### 文件移動邏輯
```python
def move_to_correct_directory(file_path, status):
    """根據狀態移動文件到正確目錄"""
    base_dir = "docs/maintenance_records"
    filename = os.path.basename(file_path)
    
    # 確定文件類型 (從文件名或元數據)
    doc_type = determine_document_type(filename)
    
    target_dir = os.path.join(base_dir, doc_type)
    
    if status == "active":
        target_dir = os.path.join(target_dir, "_active")
    elif status == "completed":
        target_dir = os.path.join(target_dir, "_completed")
    elif status == "archived":
        target_dir = os.path.join(target_dir, "_archived")
    
    # 確保目標目錄存在
    os.makedirs(target_dir, exist_ok=True)
    
    # 移動文件
    target_path = os.path.join(target_dir, filename)
    os.rename(file_path, target_path)
    
    return target_path
```

## 錯誤處理與日誌

### 錯誤代碼
```yaml
ERROR_CODES:
  FILE_NOT_FOUND: "E001"
  YAML_PARSE_ERROR: "E002"
  INVALID_FILENAME: "E003"
  MISSING_REQUIRED_FIELD: "E004"
  DIRECTORY_PERMISSION: "E005"
```

### 日誌格式
```python
import logging

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('ai_agent_docs.log'),
        logging.StreamHandler()
    ]
)

logger = logging.getLogger('ai_docs_agent')
```

## 性能優化建議

### 1. 緩存策略
- 緩存經常訪問的文件元數據
- 實現增量更新檢測
- 使用內存緩存熱點數據

### 2. 批量操作
- 合併相似的文件操作
- 使用事務性更新
- 實現操作隊列

### 3. 索引優化
- 建立文件元數據索引
- 定期重建索引
- 支持全文搜索

## 測試與驗證

### 單元測試示例
```python
def test_extract_metadata():
    """測試元數據提取"""
    test_file = "test_rca.md"
    metadata = extract_document_metadata(test_file)
    
    assert metadata['document_type'] == 'rca'
    assert metadata['severity'] == 'P2'
    assert 'service' in metadata

def test_search_documents():
    """測試文檔搜索"""
    results = search_documents({'severity': 'P0', 'status': 'active'})
    assert len(results) > 0
    for result in results:
        assert result['metadata']['severity'] == 'P0'
```

## 附錄

### 保留期限對照表
| 文件類型 | 活躍期 | 完成保留期 | 總保留期 |
|----------|--------|------------|----------|
| RCA      | P0: 7天, P1: 14天, P2-4: 30天 | 30天 | 2年 |
| 事件報告 | P0: 3天, P1: 7天, P2-4: 14天 | 30天 | 1年 |
| 變更紀錄 | 實施期間 | 90天 | 3年 |
| 維護計畫 | 計畫期間 | 30天 | 1年 |

### 嚴重等級定義
| 等級 | 響應時間 | 通知要求 | 文件要求 |
|------|----------|----------|----------|
| P0   | 立即 | 即時通訊+電話 | 必須創建 RCA |
| P1   | 2小時內 | 1小時內通知團隊 | 建議創建 RCA |
| P2   | 4小時內 | 2小時內通知 | 可選創建 RCA |
| P3   | 1工作日 | 工作日內通知 | 事件報告即可 |
| P4   | 3工作日 | 無需緊急通知 | 簡單紀錄 |

---

**最後更新**: 2026-03-27  
**版本**: V1.0  
**適用對象**: 所有 AI Agent 和自動化工具

**注意**: 本文檔應與實際模板文件結合使用，定期更新以反映系統變更。
