admin/momentry_core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4686c5abc4a9fe388529558a2ccd2a01f4be5075
momentry_core/docs_v1.0/STANDARDS/DOCS_STANDARD.md

15 KiB
Raw Blame History

document_type, service, title, date, version, status, owner, created_by, tags, ai_query_hints
document_type service title date version status owner created_by tags ai_query_hints
standard_doc MOMENTRY_CORE 文件創建規範 2026-03-18 V1.0 active Warren OpenCode
文件創建規範
查詢 文件創建規範 的內容
文件創建規範 的主要目的是什麼？
如何操作或實施 文件創建規範？

文件創建規範

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

版本歷史

版本 日期 目的 操作人 工具/模型
V1.0 2026-03-18 創建文件規範 Warren OpenCode / MiniMax M2.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 頂部資訊表內容一致
Reference in New Issue View Git Blame Copy Permalink