warren/momentry_core
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 2 Wiki Activity
Files
main
momentry_core/docs_v1.0/STANDARDS/DOCS_STANDARD.md

25 KiB
Raw Permalink Blame History

document_type, service, title, date, version, status, owner, created_by, tags, ai_query_hints, related_documents
document_type service title date version status owner created_by tags ai_query_hints related_documents
standard_doc MOMENTRY_CORE 文件創建規範 2026-04-27 V2.1 active Warren OpenCode
docs-standard
ai-agent-friendly
yaml-frontmatter
rag-optimization
查詢 文件創建規範 的內容
文件創建規範 的主要目的是什麼？
如何操作或實施 文件創建規範？
AI Agent 友好規範要求
YAML Frontmatter 必需字段
ai_query_hints 编寫規範
tags 编寫規範
document_type 完整類型列表
STANDARDS/DOCS_STANDARD_IMPROVEMENT_PROPOSAL_2026_03_27.md

文件創建規範

項目 內容
建立者 Warren
建立時間 2026-03-18
文件版本 V2.0

UUID 命名規範

API 路徑、查詢參數、JSON key、程式碼變數中禁止使用裸 uuid：

情境 必須使用 禁止使用
影片/檔案資源 file_uuid uuid
身份資源 identity_uuid uuid
查詢參數 file_uuid=, identity_uuid= uuid=
路由路徑 :file_uuid, :identity_uuid :uuid
JSON key "file_uuid", "identity_uuid" "uuid"

例外：資料庫內部 primary key（如 identities.uuid 欄位）可保留原名。

版本歷史

版本 日期 目的 操作人 工具/模型
V2.1 2026-05-14 新增 UUID 命名規範 M5 OpenCode
V2.0 2026-04-27 添加 AI Agent 友好完整規範（10.6-10.12） OpenCode GLM-5

本文檔定義 Momentry Core 專案中文件的命名規範、格式標準和結構要求。

1. 檔案命名規範

命名模式

所有文件必須使用以下命名模式：

文件類型 模式 範例
安裝指南 INSTALL_<NAME>.md INSTALL_POSTGRESQL.md
開發指南 DEVELOP_<NAME>.md DEVELOP_API.md
API 參考 API_REFERENCE.md API_REFERENCE.md
規格文件 <NAME>_SPEC.md CHUNK_SPEC.md
設計文件 <NAME>_DESIGN.md CHUNK_DESIGN.md
服務總覽 SERVICES.md SERVICES.md
其他文件 <NAME>.md README.md

命名規則

  • 使用 大駝峰 (PascalCase) 命名法
  • 服務名稱使用 全大寫 (e.g., POSTGRESQL, SFTPGO)
  • 英文優先，縮寫保持大寫
  • 使用底線 _ 作為單詞分隔符
  • 副檔名統一使用 .md (Markdown)

禁止事項

  • 不允許使用中文檔名
  • 不允許空格
  • 不允許混合大小寫 (如 Install_PostgreSQL.md)

2. 文件結構模板

安裝指南結構

# <服務名稱> 安裝指南 (部署類型)

## 概述

本文檔說明如何...

---

## 當前狀態

| 項目 | 狀態 |
|------|------|
| <服務名> | ✅ 已安裝 v<版本號> |
| Port | <端口號> |
| ... | ... |

---

## 安裝步驟

### Step 1: <步驟名稱>

<說明內容>

```bash
# 代碼範例
command --option value

Step 2: <步驟名稱>

...

卸載步驟

Step 1: <步驟名稱>

...

故障排除

<問題名稱>

<解決方案>

檔案位置

類型 路徑 說明
安裝 /path/to/install 說明
...

常用指令

# 驗證
command verify

# 查看版本
command --version

版本資訊

  • 版本: <版本號>
  • 安裝日期: <日期>

---

### 規格文件結構

```markdown
# <名稱> 規格文件

## 概述

<簡短描述>

---

## 詳細規格

### 1. <功能模組>

#### 欄位定義

| 欄位 | 類型 | 必填 | 說明 |
|------|------|------|------|
| field1 | string | Yes | 說明 |

#### 資料結構

```json
{
  "example": "data"
}

限制條件

  • <限制1>
  • <限制2>

相關文件

  • RELATED_FILE.md - 相關說明

---

## 3. 格式標準

### Markdown 格式

| 項目 | 標準 |
|------|------|
| 標題層級 | H1 (`#`) → H2 (`##`) → H3 (`###`) |
| 水平線 | 使用 `---` 分隔主要章節 |
| 程式碼區塊 | 使用三個反引號 ``` 並標註語言 |
| 表格 | 使用 `|` 和 `-` 對齊 |
| 強調 | 使用 `**粗體**` 和 `*斜體*` |

### 程式碼區塊語言標註

```bash
# Bash
```bash
command

# JSON
```json
{"key": "value"}

# Rust
```rust
fn main() {}

# YAML
key: value

表格格式

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

列表格式

  • 使用 - 作為無序列表標記
  • 使用數字 1. 作為有序列表標記
  • 縮進使用 2 個空格

4. 語言規範

標題語言

區域 語言
主要內容 繁體中文
技術術語 英文保留
命令和代碼 英文
文件標題 繁體中文

常用術語對照

英文 中文
Install 安裝
Configure/Config 配置/設定
Uninstall 卸載
Troubleshooting 故障排除
Status 狀態
Documentation 文件
Guide 指南
Overview 概述
Specification 規格
Current Status 當前狀態
Default 預設
Required 必填
Optional 選填
Example 範例

標點符號

  • 中文內容使用全形標點：，、。、：、（、）
  • 英文/程式內容使用半形標點：:、(、)
  • 命令行使用 `command` 格式

5. 內容要求

必需章節

每份文件必須包含：

  1. 標題 - 文件名稱
  2. 概述 - 檔案用途說明
  3. 版本/狀態資訊 - 當前狀態
  4. 檔案位置 - 重要路徑列表
  5. 常用指令 - 基本操作命令

版本資訊格式

每份文件頂部必須包含以下資訊：

| 項目 | 內容 |
|------|------|
| 建立者 | <姓名> |
| 建立時間 | <YYYY-MM-DD> |
| 文件版本 | V1.0 |

版本歷史表：

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-18 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |

版本資訊章節格式

---

## 版本資訊

- 版本: <版本號>
- 安裝日期: <YYYY-MM-DD>
- 文件更新: <YYYY-MM-DD>

狀態標記

狀態 標記
已安裝 ✅ 已安裝 v<x.x.x>
未安裝 ❌ 未安裝
可選 ⚙️ 可選
進行中 🔄 進行中

6. 示例文件

正確範例

# PostgreSQL 安裝指南 (本地部署)

| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-18 |
| 文件版本 | V1.0 |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-18 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |

---

## 概述

本文檔說明如何在 macOS 上安裝 PostgreSQL...

---

## 當前狀態

| 項目 | 狀態 |
|------|------|
| PostgreSQL | ✅ 已安裝 v16.2 |
| Port | 5432 |

---

## 安裝步驟

### Step 1: 安裝 PostgreSQL

```bash
brew install postgresql@16

Step 2: 啟動服務

brew services start postgresql@16

檔案位置

類型 路徑
配置文件 /path/to/config
數據目錄 /path/to/data

版本資訊

  • 版本: 16.2
  • 安裝日期: 2026-03-01

### 錯誤範例

❌ PostgreSQL安裝.md # 中文檔名 ❌ install-postgresql.md # 全部小寫 ❌ Install PostgreSQL.md # 空格 ❌ postgresql_install.md # 非標準命名


---

## 7. 文件審查清單

創建新文件時，請確認：

- [ ] 檔案命名符合 `INSTALL_*.md` 或其他標準模式
- [ ] 文件包含頂部資訊表（建立者、建立時間、版本）
- [ ] 文件包含版本歷史表
- [ ] 文件包含概述章節
- [ ] 文件包含當前狀態/版本資訊
- [ ] 文件包含檔案位置章節
- [ ] 文件包含常用指令章節
- [ ] 使用統一的 Markdown 格式
- [ ] 使用繁體中文作為主要語言
- [ ] 程式碼區塊標註語言類型
- [ ] 表格格式正確
- [ ] 章節使用 `---` 分隔

### 頂部資訊表範本

```markdown
| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-18 |
| 文件版本 | V1.0 |

版本歷史表範本

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-18 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |

8. 更新現有文件

當更新現有文件時：

  1. 更新 版本資訊 中的日期
  2. 如有必要，更新版本號
  3. 記錄重大變更於 CHANGELOG.md 或 DEVELOPMENT_LOG.md

9. 運維紀錄標準

9.1 事件嚴重等級定義

等級 代碼 影響描述 處理時間目標 通知要求
P0 緊急 服務完全中斷，影響所有用戶 立即處理，1小時內解決 立即通知所有相關人員
P1 高 主要功能不可用，影響多數用戶 2小時內開始處理，4小時內解決 1小時內通知負責人
P2 中 次要功能問題，影響部分用戶 4小時內開始處理，8小時內解決 2小時內通知負責人
P3 低 輕微問題，不影響核心功能 1個工作日內處理 工作日內通知
P4 資訊 諮詢、建議或非緊急問題 3個工作日內回應 無需緊急通知

9.2 事件狀態標記

狀態 標記 說明
新報告 ⏳ 待處理 事件剛被報告，尚未分配
調查中 🔍 調查中 正在調查根本原因
處理中 🔧 處理中 正在實施解決方案
已解決 ✅ 已解決 問題已解決，待驗證
已關閉 📁 已關閉 事件完全關閉
已歸檔 🗄️ 已歸檔 事件已歸檔

9.3 RCA 文件結構模板

必需章節

  1. 頂部資訊表 - 建立者、時間、版本、嚴重等級
  2. 版本歷史 - 文件變更紀錄
  3. 事件摘要 - 問題概述和影響
  4. 調查過程 - 詳細調查步驟和發現
  5. 根本原因分析 - 主要和次要原因
  6. 解決方案與實施 - 具體修復措施
  7. 預防措施 - 短期、中期、長期改進
  8. 影響評估 - 直接和間接影響
  9. 經驗教訓 - 學到的教訓和最佳實踐
  10. 相關文件 - 相關參考文件
  11. 簽核 - 相關人員確認

可選章節

  • 技術細節附錄
  • 測試腳本詳解
  • 配置參數說明
  • 監控指標定義

9.4 文件生命周期管理

階段 目錄 說明
進行中 [類型]/_active/ 正在處理的事件/變更 (類型: rca, incidents, changes, plans)
已完成 [類型]/_completed/ 已完成的處理項目 (類型: rca, incidents, changes, plans)
已歸檔 [類型]/_archived/ 超過保留期限的文件 (類型: rca, incidents, changes, plans)

保留政策

文件類型 保留期限 歸檔策略
RCA 文件 2 年 年度歸檔
事件報告 1 年 季度歸檔
變更紀錄 3 年 年度歸檔
維護計畫 1 年 完成後歸檔

附錄：文件類型參考

前綴 用途 位置
INSTALL_ 服務安裝指南 /docs/
DEVELOP_ 開發指南 /docs/
*_SPEC.md 規格定義 /docs/
*_DESIGN.md 設計文件 /docs/
API_REFERENCE.md API 參考文件 /docs/
README.md 專案總覽 /
AGENTS.md AI 代理指令 /
CHANGELOG.md 變更日誌 /

運維紀錄文件類型（新增）

前綴 用途 位置 語言 狀態標記
RCA_ 根本原因分析 /docs/maintenance_records/rca/ 繁體中文 P0-P4
INCIDENT_ 事件報告 /docs/maintenance_records/incidents/ 繁體中文 ✅/⏳/❌
CHANGE_ 變更紀錄 /docs/maintenance_records/changes/ 繁體中文 ✅/🔧/⚠️
MAINTENANCE_ 維護計畫 /docs/maintenance_records/plans/ 繁體中文 📅/🔧/✅
TEMPLATE_ 文件模板 /docs/maintenance_records/templates/ 繁體中文 -

運維紀錄目錄結構

docs/maintenance_records/
├── rca/            # 根本原因分析 (RCA_*.md)
│   ├── _active/    # 正在處理的 RCA
│   ├── _completed/ # 已完成的 RCA
│   └── _archived/  # 已歸檔的 RCA
├── incidents/      # 事件報告 (INCIDENT_*.md)
│   ├── _active/    # 正在處理的事件
│   ├── _completed/ # 已完成的事件
│   └── _archived/  # 已歸檔的事件
├── changes/        # 變更紀錄 (CHANGE_*.md)
│   ├── _active/    # 正在處理的變更
│   ├── _completed/ # 已完成的變更
│   └── _archived/  # 已歸檔的變更
├── plans/          # 維護計畫 (MAINTENANCE_*.md)
│   ├── _active/    # 正在處理的計畫
│   ├── _completed/ # 已完成的計畫
│   └── _archived/  # 已歸檔的計畫
└── templates/      # 文件模板 (TEMPLATE_*.md)

文件名稱格式

  • RCA 文件: RCA_<服務名稱>_<問題簡述>_<日期>.md

    • 範例: RCA_WORDPRESS_TIMEOUT_EXTERNAL_ACCESS_2026_03_27.md

  • 事件報告: INCIDENT_<服務名稱>_<事件類型>_<日期>.md

    • 範例: INCIDENT_POSTGRESQL_CONNECTION_ISSUE_2026_03_26.md

  • 變更紀錄: CHANGE_<服務名稱>_<變更類型>_<日期>.md

  • 維護計畫: MAINTENANCE_<服務名稱>_<計畫類型>_<日期>.md

10. AI Agent 友好規範

10.1 雙重格式設計

所有新創建的文件必須包含 YAML Frontmatter 和 Markdown 內容 兩種格式，以確保 AI Agent 能高效解析，同時人類用戶也能方便閱讀。

格式 用途 優先級
YAML Frontmatter AI Agent 結構化元數據解析 高 (AI 優先)
Markdown 內容 人類可讀展示 中 (人類備用)

10.2 YAML Frontmatter 規範

文件頂部必須包含標準化的 YAML Frontmatter，位於文件開頭的 --- 之間：

---
document_type: "design" | "spec" | "guide" | "plan" | "rca" | "incident"
service: "MOMENTRY_CORE" | "服務名稱"
title: "文件標題"
date: "YYYY-MM-DD"
status: "active" | "completed" | "archived"
current_state: "draft" | "review" | "approved"
owner: "負責人姓名"
created_by: "OpenCode / 姓名"
created_at: "YYYY-MM-DD"
version: "V1.0"
tags:
  - "標籤1"
  - "標籤2"
related_documents:
  - "相關文件.md"
ai_query_hints:
  - "查詢提示1"
  - "查詢提示2"
---

10.3 標準化字段定義

字段 類型 必填 說明
document_type string Yes 文件類型 (design, spec, guide, plan, rca, etc.)
service string Yes 服務名稱 (全大寫)
title string Yes 文件標題
date string Yes 建立/更新日期
status string Yes 生命週期狀態 (active, completed, archived)
owner string Yes 負責人
created_by string Yes 建立者
version string Yes 版本號
tags list No 搜尋標籤 (建議填寫以優化 AI 檢索)
ai_query_hints list No AI 查詢提示 (說明文件核心內容，優化 RAG 檢索)

10.4 同步要求

YAML Frontmatter 與文件內部的 Markdown 頂部資訊表必須保持數據同步。 當更新文件時，必須同時更新 YAML Frontmatter 和 Markdown 表格。

10.5 文件審查清單更新

創建新文件時，除了原有的檢查項目，還必須確認：

  • 文件包含標準 YAML Frontmatter
  • 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 範例

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 範例

tags:
  - "jsonb"
  - "processing-status"
  - "progress-tracking"
  - "processor"
  - "rule"
  - "agent"

10.9 RAG 檢索優化建議

10.9.1 文件內容結構優化

建議 說明
標題清晰 使用明確的標題描述文件內容
段落分明 使用 --- 分隔主要章節，提升段落識別
表格標準 使用標準表格格式，避免嵌套表格
代碼標註 代碼區塊標註語言類型（提升代碼檢索）
避免冗余 删除重複內容，降低向量噪音

10.9.2 关键术语定义表

建議在文件中包含關鍵術語定義表，提升術語檢索效果：

## 關鍵術語定義

| 術語 | 定義 |
|------|------|
| 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 範例

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 友好規範的完整文件範例：

---
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）
  • 使用標準表格格式
  • 代碼區塊標註語言類型
  • 段落使用 --- 分隔
  • 術語使用一致（無混用）
Reference in New Issue View Git Blame Copy Permalink