wiki-generate

# 文件站產生器 從原始碼、CLAUDE.md、`doc/` 既有文件與專案結構分析，產生雙語靜態文件站（`wiki-worker/public/docs/`），並提供 `wiki-worker/build.js` 將 markdown 編譯為可直接部署的 HTML。 **SEO / AEO 搭配 `/seo-optimize`。** `build.js` 範本內建 title、description、JSON-LD、OG/Twitter、h1、hreflang、sitemap、robots、llms.txt 與可見作者署名的輸出，生成時只填入專案值；研究、關鍵字與優化由 Step 8 交給 `/seo-optimize`，未安裝時詢問是否下載，否決則依基本方式完成。 ## 指令語法 ``` /wiki-generate [REPO_PATH] [--only <pages>] [--pages <list>] ``` ### 參數（全部選填） | 參數 | 格式 | 範例 | 行為 | | ---------------- | --------------------------- | ------------------------------------------- | ---------------------------- | | `REPO_PATH` | `github.com/{owner}/{repo}` | `github.com/foo/bar` | 覆蓋預設 owner / repo | | `--only <pages>` | 逗號分隔 | `--only home,configuration` | 僅重生指定頁；其他頁不讀不寫 | | `--pages <list>` | 逗號分隔 | `--pages getting-started,api-reference,faq` | 覆蓋自動推導的頁面清單 | **參數識別規則：** 順序獨立，依路徑模式 / `--flag` 解析。 ### `--only` vs `--pages` | 場景 | 使用 | | ----------------------------- | ------------------------------ | | 已生成文件站，只想刷新 1–2 頁 | `--only` | | 第一次生成、想自定頁面集合 | `--pages` | | 預設 | 不傳；分析專案後自動推導頁面集 | `--only` 模式下： - 未指定的頁面 **不得讀取、不得覆寫** - Home 若不在 `--only` 內也不動（即使有新頁面被加入也不更新 Home 導覽） - `REPO_PATH` 仍套用至重生的頁面 - `--only` 後仍須重跑 `node wiki-worker/build.js`（NAV 未變動時新頁 HTML 不受影響，但確保輸出一致） --- ## Step 0：作者設定（共用 readme-generate config） **文件站生成需要的作者資訊（name / email / url / github_owner）與 readme-generate 相同，刻意共用一份 config 避免重複設定。腳本本身已隨 skill 複製一份至本地，不依賴 readme-generate 是否安裝。** ### 設定檔 ``` ~/.skill-readme-generate.json ``` （檔名沿用 readme-generate 命名以保持兩 skill 共用同一份 config，避免使用者在兩處重複輸入相同資料。） ### 執行協議 下文指令中的 `{skill_dir}` 為本 `SKILL.md` 所在目錄的絕對路徑，依當前執行環境實際載入位置代入。 **Step 0.1：檢查設定** ```bash python3 {skill_dir}/scripts/setup_config.py check ``` | Exit Code | stdout | 動作 | | --------- | --------- | ----------------- | | `0` | 單行 JSON | 解析後跳到 Step 1 | | `1` | （無） | 進入 Step 0.2 | **Step 0.2：收集輸入（缺檔時）** 向使用者依序詢問四欄位：`author_name` / `author_email` / `author_url` / `github_owner`，再呼叫： ```bash python3 {skill_dir}/scripts/setup_config.py write \ "{author_name}" "{author_email}" "{author_url}" "{github_owner}" ``` **Step 0.3：站台元資料設定（新專案第一次生成時額外詢問）** 先檢查 `<project_root>/wiki-worker/.doc/seo/config.json`：存在且欄位完整 → 載入並向使用者複述一行；缺失 → 向使用者詢問下表缺少的欄位後寫入該檔。 | 欄位 | 用途 | 預設 fallback | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `site_name` | 文件站顯示名稱（`<title>` 品牌段、JSON-LD `name`、署名列、llms.txt 標題）。**套件／函式庫／CLI 一律用 `{owner}/{repo}`**（如 `pardnchiu/go-bot`）；只有具獨立品牌名的產品（Agenvoy、ToriiDB、KuraDB）才用品牌名本身 | `{owner}/{repo}` | | `domain` | 正式部署網域（`https://example.com`，用於 canonical / sitemap / llms.txt，不含結尾斜線） | 從 `wrangler.toml` routes、GitHub repo homepage 推得；推不出就問，**不得填佔位網域** | | `gtag_id` | Google Analytics 量測 ID，留空則不注入 | 空字串 | | `person_id` / `person_name` / `person_alt_names` | JSON-LD Person 節點 | 先抓 `author_url` 頁面的 JSON-LD：已宣告 Person 就**沿用其 `@id` 與 `name`**（跨站實體歸戶）；沒有則 `@id = {author_url}#person`、`name = author_name` | | `same_as` | Person `sameAs` 與署名列外部連結 | **以 `~/.skill-readme-generate.json` 的 `same_as` 為必含清單，逐項全數放入、不得刪減**（使用者 2026-10-02 指定，含作者網站本身）；專案可再加，組織帳號另放 `org_same_as`。共用設定缺 `same_as` 時詢問使用者並寫回該檔 | | `org_name` / `org_name_zh` | Organization 節點與署名列組織段，EN／ZH 頁各用自己語言的正式名稱（另一語言進 `alternateName`）；**逐字採用使用者寫法**（含標點） | 空字串＝無組織，不產生 Organization | | `org_same_as` | Organization `sameAs`（如組織的 GitHub org） | 空陣列 | | `tagline` | 署名列與 llms.txt 的定位文字（如 `Taiwan · Infrastructure Engineering`），不產生任何 schema 實體 | 空字串＝不輸出 | | `favicon` | 全站 favicon，存成 `public/favicon.png`，`FAVICON` 填 `/favicon.png` | 來源同 `og_image` 候選；須 1:1、至少 48x48（建議 48 的倍數，如 192x192），以 `sips -z 192 192 <src> -s format png --out public/favicon.png` 轉成 PNG（Google 支援 PNG／ICO 等，不列 SVG）；找不到可驗證的 1:1 圖就留空 | | `og_image` | 全站 `og:image`／`twitter:image` | 候選：`author_url` 網站的 logo、`https://github.com/{github_owner}.png`；**必須 `curl -sIL` 驗證 200 且為 image/***，否則留空 | | `brand_keywords` | 每頁 `<meta name="keywords">` 尾端補上的品牌詞（人名、帳號、組織名），已存在於該頁 keywords 者不重複 | 空陣列 | | `x_default` | hreflang `x-default` 指向的語言：`en`／`zh`／空字串（不輸出） | 空字串；只在使用者明確指定時填值 | 關鍵字、AI 使用偏好等 SEO 設定由 `/seo-optimize` 管理於 `<project_root>/.doc/seo-optimize/config.json`，本 skill 不詢問、不寫入。 **Step 0.4：覆蓋優先序** | 來源 | 優先 | | ------------------------------- | -------------------- | | `REPO_PATH` 指令參數 | 最高（owner / repo） | | `~/.skill-readme-generate.json` | 次高（其他作者欄位） | | `git remote get-url origin` | 第三 | | 資料夾名稱 | fallback | --- ## Step 1：分析專案 ### Step 1.1：執行 analyzer 取得符號清單（粗掃） ```bash python3 {skill_dir}/scripts/analyze_project.py /path/to/project ``` **輸出**：language / files / functions / types / dependencies 的 JSON 摘要。 **用途**：作為「該讀哪些檔」的索引，**不**作為文件內容生成的依據。analyzer 用 regex 抽符號，會遺漏： - 函式 body 內的實際邏輯／流程／錯誤分支 - 巢狀 type 與 closure 中的隱含介面 - 跨檔依賴的真實呼叫關係 - 註解中的設計決策、TODO、限制 - mermaid／表格／範例所需的完整 context ### Step 1.2：讀取完整檔案（強制） **文件生成不可只靠 analyzer 摘要**。針對每個將生成的頁面，**必須完整讀取**對應的原始碼檔案與既有文件。 | 頁面類型 | 必讀檔案 | | ----------------------------------- | ------------------------------------------------------------------------------------------------------ | | **任何頁** | `CLAUDE.md`（根，整份） | | **Architecture** | `doc/architecture.md`（整份）+ `analyze_project.py` 列出的核心模組所有 `.go` / `.py` / `.ts` 檔 | | **Core-Concepts** | 主要 entry point（`main.go` / `cmd/*/main.*` / `index.ts`）+ 核心 dispatch / loop 檔（整檔，不抓片段） | | **Configuration** | `.env.example` 整份 + 所有 `os.Getenv` / `process.env` 呼叫所在檔（用 grep 定位後整檔讀） | | **CLI-Reference** | `main.*` + flag / cobra / argparse 註冊處所在檔（整檔）+ `makefile` | | **API-Reference** | 所有 exported types / functions 所在的檔案（整檔，不只看 signature） | | **Skill-System / Tools / 子系統頁** | 對應 `extensions/skills/*/SKILL.md` 整份 + 對應實作檔 | | **Getting-Started** | `README.md` + `Makefile` + `Dockerfile`（如有）+ entry point | **為何：** 1. **文件是 source of truth**：讀者打開文件是要學整個系統運作，分支邏輯／邊界條件不能漏。analyzer 只看符號名，講不清楚「這個函式的 retry 策略是什麼」、「這個 dispatch 有幾種 path」 2. **避免幻覺**：未讀的檔案不能寫進文件。寫入前 grep 一次確認 symbol 存在、簽名正確 3. **Mermaid 結構真實性**：架構圖的 box / arrow 必須對應實際 import / call graph，僅靠 type 名稱會編造關係 **操作建議：** - 讀取檔案時不截斷範圍；單次讀取有行數上限時才分段讀取至完整檔案 - 多檔讀取**並行呼叫**，不要序列化 - 讀過的檔案在生成時可引用 `path:line` 讓讀者跳轉 - 若檔案過大（> 2000 行）→ 拆段讀完整檔，禁止只讀前 N 行就下結論 - 寫入或修改前，先讀取目標內容比對；內容已相同時跳過寫入 ### Step 1.3：頁面結構額外來源 | 路徑 | 用途 |