Markdown 知識庫系統設計

# 類型（type）
types = ["context", "knowledge", "operations", "reference"]

# 分類（category）
categories = ["technical", "business", "management"]

# 範圍（scope）
scopes = ["global", "personal", "project"]

# 搜尋技術類型、工程師適用的知識
results = search_knowledge(
    category="technical",
    role="engineer",
    level="intermediate",
)

class KnowledgeMetadata(BaseModel):
    """知識元資料（對應 YAML Front Matter）"""

    id: str
    title: str
    type: str = "knowledge"
    category: str = "technical"
    scope: str = "global"
    owner: str | None = None       # 擁有者（personal 用）
    project_id: str | None = None  # 專案 ID（project 用）
    tags: KnowledgeTags = Field(default_factory=KnowledgeTags)
    source: KnowledgeSource = Field(default_factory=KnowledgeSource)
    related: list[str] = Field(default_factory=list)
    attachments: list[KnowledgeAttachment] = Field(default_factory=list)
    author: str = "system"
    created_at: date
    updated_at: date

class KnowledgeTags(BaseModel):
    """知識標籤"""

    projects: list[str] = Field(default_factory=list)
    roles: list[str] = Field(default_factory=list)
    topics: list[str] = Field(default_factory=list)
    level: str | None = None

class KnowledgeAttachment(BaseModel):
    """知識附件"""

    type: str          # image, video, document, etc.
    path: str          # 相對路徑或 NAS 路徑
    size: str | None = None
    description: str | None = None

class KnowledgeIndex(BaseModel):
    """知識庫索引"""

    version: int = 1
    last_updated: str | None = None
    next_id: int = 1
    entries: list[IndexEntry] = Field(default_factory=list)
    tags: TagsResponse = Field(default_factory=...)

class IndexEntry(BaseModel):
    """索引中的知識項目"""

    id: str
    title: str
    filename: str
    type: str
    category: str
    scope: str = "global"
    owner: str | None = None
    project_id: str | None = None
    tags: KnowledgeTags
    author: str
    created_at: str
    updated_at: str

def _parse_front_matter(content: str) -> tuple[dict[str, Any], str]:
    """解析 YAML Front Matter

    Returns:
        (metadata_dict, markdown_content)
    """
    if not content.startswith("---"):
        return {}, content

    # 找到第二個 ---
    end_match = re.search(r"\n---\s*\n", content[3:])
    if not end_match:
        return {}, content

    yaml_content = content[3 : end_match.start() + 3]
    markdown_content = content[end_match.end() + 3 :].strip()

    try:
        metadata = yaml.safe_load(yaml_content)
        return metadata or {}, markdown_content
    except yaml.YAMLError:
        return {}, content

def _generate_front_matter(metadata: dict[str, Any]) -> str:
    """產生 YAML Front Matter"""
    yaml_content = yaml.dump(
        metadata,
        default_flow_style=False,
        allow_unicode=True,
        sort_keys=False,
    )
    return f"---\n{yaml_content}---\n\n"

def search_knowledge(
    query: str | None = None,
    project: str | None = None,
    category: str | None = None,
    scope: str | None = None,
    current_username: str | None = None,
) -> KnowledgeListResponse:
    """搜尋知識"""
    index = _load_index()
    results: list[KnowledgeListItem] = []

    # 用 ripgrep 搜尋內容
    matching_files: set[str] | None = None
    snippets: dict[str, str] = {}

    if query:
        try:
            # 搜尋檔名
            result = subprocess.run(
                [
                    "rg",
                    "-i",           # 不分大小寫
                    "-l",           # 只輸出檔名
                    "--type", "md",
                    query,
                    str(ENTRIES_PATH),
                ],
                capture_output=True,
                text=True,
                timeout=10,
            )

            matching_files = set()
            if result.returncode == 0:
                for line in result.stdout.strip().split("\n"):
                    if line:
                        matching_files.add(Path(line).name)

            # 取得匹配片段（用於顯示摘要）
            result_context = subprocess.run(
                [
                    "rg",
                    "-i",
                    "-C", "1",      # 前後各 1 行
                    "--type", "md",
                    query,
                    str(ENTRIES_PATH),
                ],
                capture_output=True,
                text=True,
                timeout=10,
            )

            # 解析片段...

        except subprocess.TimeoutExpired:
            pass  # 搜尋逾時，回退到全部列出

    # 遍歷索引，套用過濾條件
    for entry in index.entries:
        # 檔案內容過濾
        if matching_files is not None and entry.filename not in matching_files:
            continue

        # Scope 過濾
        if entry.scope == "personal" and entry.owner != current_username:
            continue

        # 其他過濾條件...

        results.append(...)

    return KnowledgeListResponse(items=results, total=len(results), query=query)

def create_knowledge(
    data: KnowledgeCreate,
    owner: str | None = None,
    project_id: str | None = None,
) -> KnowledgeResponse:
    """建立新知識"""
    index = _load_index()

    # 分配 ID
    kb_id = f"kb-{index.next_id:03d}"
    index.next_id += 1

    # 產生 slug（URL 友善名稱）
    slug = data.slug or _slugify(data.title)
    if not slug:
        slug = f"knowledge-{index.next_id}"

    # 確保 slug 唯一
    existing_slugs = {e.filename.split("-", 2)[-1].replace(".md", "") for e in index.entries}
    while slug in existing_slugs:
        slug = f"{slug}-{counter}"
        counter += 1

    # 檔名：kb-001-my-knowledge.md
    filename = f"{kb_id}-{slug}.md"
    file_path = ENTRIES_PATH / filename

    # 準備元資料
    today = date.today()
    metadata = {
        "id": kb_id,
        "title": data.title,
        "type": data.type,
        "category": data.category,
        "scope": data.scope,
        "owner": owner if data.scope == "personal" else None,
        "project_id": project_id if data.scope == "project" else None,
        "tags": {...},
        "author": data.author,
        "created_at": today.isoformat(),
        "updated_at": today.isoformat(),
    }

    # 產生檔案內容
    front_matter = _generate_front_matter(metadata)
    file_content = front_matter + data.content

    # 寫入檔案
    with open(file_path, "w", encoding="utf-8") as f:
        f.write(file_content)

    # 更新索引
    index.entries.append(IndexEntry(...))
    _save_index(index)

    return get_knowledge(kb_id)

def get_history(kb_id: str) -> HistoryResponse:
    """取得知識的版本歷史"""
    file_path = _find_knowledge_file(kb_id)
    if not file_path:
        raise KnowledgeNotFoundError(f"知識 {kb_id} 不存在")

    try:
        result = subprocess.run(
            [
                "git", "log",
                "--format=%H|%an|%ai|%s",  # hash|author|date|message
                "--",
                str(file_path),
            ],
            capture_output=True,
            text=True,
            cwd=KNOWLEDGE_BASE_PATH,
        )

        entries = []
        for line in result.stdout.strip().split("\n"):
            if line:
                parts = line.split("|", 3)
                entries.append(HistoryEntry(
                    commit=parts[0],
                    author=parts[1],
                    date=parts[2],
                    message=parts[3] if len(parts) > 3 else "",
                ))

        return HistoryResponse(id=kb_id, entries=entries)

    except Exception as e:
        raise KnowledgeError(f"取得歷史失敗：{e}") from e

def get_version(kb_id: str, commit: str) -> VersionResponse:
    """取得知識的特定版本內容"""
    file_path = _find_knowledge_file(kb_id)

    result = subprocess.run(
        ["git", "show", f"{commit}:{file_path.name}"],
        capture_output=True,
        text=True,
        cwd=ENTRIES_PATH,
    )

    return VersionResponse(
        id=kb_id,
        commit=commit,
        content=result.stdout,
    )