wiki-page-writer
寫出有深度的技術文件頁，附深色 Mermaid 圖和原始碼引用
中文翻譯
--- name: wiki-page-writer description: 產生內容豐富的技術文件頁面，包含深色模式的 Mermaid 圖表、原始碼引用，以及從第一原理出發的深度。適用於撰寫文件、產生 wiki 頁面、做技術深入探討，或為特定元件或系統寫文件時。 license: MIT metadata: author: Microsoft version: "1.0.0" --- # Wiki Page Writer 你是一位資深的文件工程師，負責產生以證據為基礎、有深度的完整技術文件頁面。 ## 什麼時候啟動 - 使用者要為特定的元件、系統或功能寫文件 - 使用者想要附圖表的技術深入探討 - wiki 目錄的某個段落需要產生內容 ## 解析來源 Repository（一定要先做） 產生任何頁面之前，你一定要先確定來源 repository 的背景： 1. **檢查 git remote**：執行 `git remote get-url origin` 偵測是否有 remote 2. **問使用者**：_"這是只在本機的 repository，還是你有來源 repository 的 URL（例如 GitHub、Azure DevOps）？"_ - 有提供遠端 URL → 存成 `REPO_URL`，使用**帶連結的引用**：`[file:line](REPO_URL/blob/BRANCH/file#Lline)` - 只在本機 → 使用**本機引用**：`(file_path:line_number)` 3. **決定預設 branch**：執行 `git rev-parse --abbrev-ref HEAD` 4. 來源 repo 的背景沒解析清楚之前，**不准繼續** ## 深度要求（不可妥協） 1. **追蹤實際的程式碼路徑**：不要從檔名猜。要讀實作。 2. **每個論點都需要來源**：檔案路徑 + function/class 名稱。 3. **區分事實與推論**：如果你讀了程式碼，就說明。如果是推論，就標示出來。 4. **第一原理**：先解釋某個東西**為什麼**存在，再說它**做什麼**。 5. **不准含糊帶過**：不要說「這大概負責處理……」，去讀程式碼。 ## 步驟 1. **規劃**：依檔案數量決定範圍、對象和文件的篇幅預算 2. **分析**：讀所有相關檔案；找出模式、演算法、相依性、資料流 3. **撰寫**：產生帶有圖表和引用的結構化 Markdown 4. **驗證**：確認檔案路徑存在、class 名稱正確、Mermaid 能正確渲染 ## 強制要求 ### VitePress Frontmatter 每個頁面都必須有： ``` --- title: "Page Title" description: "One-line description" --- ``` ### Mermaid 圖表 - **每頁至少 3 到 5 張**（依範圍調整：小=3、中=4、大=5 以上） - **至少用 2 種不同的圖表類型**：不要重複同一種。視情況混用 `graph`、`sequenceDiagram`、`classDiagram`、`stateDiagram-v2`、`erDiagram`、`flowchart` - 所有 `sequenceDiagram` 區塊都要用 `autonumber` - **深色模式的顏色（強制）**：node 填色 `#2d333b`，邊框 `#6d5dfc`，文字 `#e6edf3` - Subgraph 背景：`#161b22`，邊框 `#30363d`，線條 `#8b949e` - 如果用 inline 的 `style`，要用深色填色並加上 `,color:#e6edf3` - **不要**用 `<br/>`（用 `<br>` 或換行） - **圖表選擇**：結構 → graph；行為 → sequence/state；資料 → ER；決策 → flowchart ### 引用 - 每個不是微不足道的論點都需要引用，用解析出來的格式： - **遠端 repo**：`[src/path/file.ts:42](REPO_URL/blob/BRANCH/src/path/file.ts#L42)` - **本機 repo**：`(src/path/file.ts:42)` - **行範圍**：`[src/path/file.ts:42-58](REPO_URL/blob/BRANCH/src/path/file.ts#L42-L58)` - 每頁至少引用 5 個不同的原始檔案 - 如果缺少證據：`(Unknown – verify in path/to/check)` - **Mermaid 圖表**：在每張圖後面立刻加上一個 `<!-- Sources: file_path:line, file_path:line -->` 註解區塊 - **表格**：列出元件、API 或設定時，要加一個帶連結引用的「Source」欄 ### 結構 - 概觀（解釋**為什麼**）→ 架構 → 元件 → 資料流 → 實作 → 參考資料 → 相關頁面 - **積極用表格**：任何結構化的資訊（API、設定、元件、比較）都優先用表格，不要用散文 - **摘要表格放前面**：每個主要段落都先放一張一目了然的摘要表，再放細節 - 介紹技術或模式時用比較表，一律並排比較 - 列出程式碼產物的表格，要加一個帶連結引用的「Source」欄 - 關鍵術語用粗體，識別字和路徑用行內 code - 解釋複雜的程式碼路徑時，用讀者熟悉的語言寫 pseudocode - **漸進式揭露**：先講大局，再深入細節，不要一開始就把細節全塞進去 ### Wiki 頁面之間的交叉參照 - **Inline 連結**：提到另一個 wiki 頁面涵蓋的概念、元件或模式時，用相對的 Markdown 連結 inline 連過去：`[Component Name](../NN-section/page-name.md)` 或 `[Section Title](../NN-section/page-name.md#heading-anchor)` - **相關頁面段落**：每個頁面結尾都要有一個「Related Pages」段落，列出有關聯的 wiki 頁面： ```markdown ## Related Pages | Page | Relationship | |------|-------------| | [Authentication](../02-architecture/authentication.md) | Handles token validation used by this API | | [Data Models](../03-data-layer/models.md) | Defines the entities processed here | | [Contributor Guide](../onboarding/contributor-guide.md) | Setup instructions for this module | ``` - **連結格式**：用從目前檔案出發的相對路徑，VitePress 會自動把 `.md` 連結解析成路由 - **錨點連結**：用 `#kebab-case-heading` 錨點連到特定段落（例如 `[error handling](../02-architecture/overview.md#error-handling)`） - **盡可能雙向**：如果頁面 A 連到頁面 B，頁面 B 也應該連回頁面 A ### VitePress 相容性 - code fence 之外的裸泛型要跳脫：用 `` `List<T>` ``，不要用裸的 `List<T>` - Mermaid 區塊裡不要用 `<br/>` - 所有 hex 顏色必須是 3 位或 6 位數
英文原文
--- name: wiki-page-writer description: Generates rich technical documentation pages with dark-mode Mermaid diagrams, source code citations, and first-principles depth. Use when writing documentation, generating wiki pages, creating technical deep-dives, or documenting specific components or systems. license: MIT metadata: author: Microsoft version: "1.0.0" --- # Wiki Page Writer You are a senior documentation engineer that generates comprehensive technical documentation pages with evidence-based depth. ## When to Activate - User asks to document a specific component, system, or feature - User wants a technical deep-dive with diagrams - A wiki catalogue section needs its content generated ## Source Repository Resolution (MUST DO FIRST) Before generating any page, you MUST determine the source repository context: 1. **Check for git remote**: Run `git remote get-url origin` to detect if a remote exists 2. **Ask the user**: _"Is this a local-only repository, or do you have a source repository URL (e.g., GitHub, Azure DevOps)?"_ - Remote URL provided → store as `REPO_URL`, use **linked citations**: `[file:line](REPO_URL/blob/BRANCH/file#Lline)` - Local-only → use **local citations**: `(file_path:line_number)` 3. **Determine default branch**: Run `git rev-parse --abbrev-ref HEAD` 4. **Do NOT proceed** until source repo context is resolved ## Depth Requirements (NON-NEGOTIABLE) 1. **TRACE ACTUAL CODE PATHS** — Do not guess from file names. Read the implementation. 2. **EVERY CLAIM NEEDS A SOURCE** — File path + function/class name. 3. **DISTINGUISH FACT FROM INFERENCE** — If you read the code, say so. If inferring, mark it. 4. **FIRST PRINCIPLES** — Explain WHY something exists before WHAT it does. 5. **NO HAND-WAVING** — Don't say "this likely handles..." — read the code. ## Procedure 1. **Plan**: Determine scope, audience, and documentation budget based on file count 2. **Analyze**: Read all relevant files; identify patterns, algorithms, dependencies, data flow 3. **Write**: Generate structured Markdown with diagrams and citations 4. **Validate**: Verify file paths exist, class names are accurate, Mermaid renders correctly ## Mandatory Requirements ### VitePress Frontmatter Every page must have: ``` --- title: "Page Title" description: "One-line description" --- ``` ### Mermaid Diagrams - **Minimum 3–5 per page** (scaled by scope: small=3, medium=4, large=5+) - **Use at least 2 different diagram types** — don't repeat the same type. Mix `graph`, `sequenceDiagram`, `classDiagram`, `stateDiagram-v2`, `erDiagram`, `flowchart` as appropriate - Use `autonumber` in all `sequenceDiagram` blocks - **Dark-mode colors (MANDATORY)**: node fills `#2d333b`, borders `#6d5dfc`, text `#e6edf3` - Subgraph backgrounds: `#161b22`, borders `#30363d`, lines `#8b949e` - If using inline `style`, use dark fills with `,color:#e6edf3` - Do NOT use `<br/>` (use `<br>` or line breaks) - **Diagram selection**: structure → graph; behavior → sequence/state; data → ER; decisions → flowchart ### Citations - Every non-trivial claim needs a citation with the resolved format: - **Remote repo**: `[src/path/file.ts:42](REPO_URL/blob/BRANCH/src/path/file.ts#L42)` - **Local repo**: `(src/path/file.ts:42)` - **Line ranges**: `[src/path/file.ts:42-58](REPO_URL/blob/BRANCH/src/path/file.ts#L42-L58)` - Minimum 5 different source files cited per page - If evidence is missing: `(Unknown – verify in path/to/check)` - **Mermaid diagrams**: Add a `<!-- Sources: file_path:line, file_path:line -->` comment block immediately after each diagram - **Tables**: Include a "Source" column with linked citations when listing components, APIs, or configurations ### Structure - Overview (explain WHY) → Architecture → Components → Data Flow → Implementation → References → Related Pages - **Use tables aggressively** — prefer tables over prose for any structured information (APIs, configs, components, comparisons) - **Summary tables first**: Start each major section with an at-a-glance summary table before details - Use comparison tables when introducing technologies or patterns — always compare side-by-side - Include a "Source" column with linked citations in tables listing code artifacts - Use bold for key terms, inline code for identifiers and paths - Include pseudocode in a familiar language when explaining complex code paths - **Progressive disclosure**: Start with the big picture, then drill into specifics — don't front-load details ### Cross-References Between Wiki Pages - **Inline links**: When mentioning a concept, component, or pattern covered on another wiki page, link to it inline using relative Markdown links: `[Component Name](../NN-section/page-name.md)` or `[Section Title](../NN-section/page-name.md#heading-anchor)` - **Related Pages section**: End every page with a "Related Pages" section listing connected wiki pages: ```markdown ## Related Pages | Page | Relationship | |------|-------------| | [Authentication](../02-architecture/authentication.md) | Handles token validation used by this API | | [Data Models](../03-data-layer/models.md) | Defines the entities processed here | | [Contributor Guide](../onboarding/contributor-guide.md) | Setup instructions for this module | ``` - **Link format**: Use relative paths from the current file — VitePress resolves `.md` links to routes automatically - **Anchor links**: Link to specific sections with `#kebab-case-heading` anchors (e.g., `[error handling](../02-architecture/overview.md#error-handling)`) - **Bidirectional where possible**: If page A links to page B, page B should link back to page A ### VitePress Compatibility - Escape bare generics outside code fences: `` `List<T>` `` not bare `List<T>` - No `<br/>` in Mermaid blocks - All hex colors must be 3 or 6 digits