mosage 0.1.0

package/skills/outline/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: outline
+description: 訂定書名與大綱、建立章節骨架。立項訪談完成後（stage 為 outline），或作者說「幫我想書名」「列大綱」「調整章節架構」「重新編排章節」「拆成兩章」「outline」時使用。提出書名候選與 2–3 種章節架構，定案後建立每章的骨架檔並寫入 book.yaml，請作者在 MoSage 介面的「大綱」頁拖曳編排；寫作途中調整大綱也用這個 skill。
+---
+
+# 書名與大綱
+
+## 前置
+
+- 確定是哪一本書（見 AGENTS.md）。
+- 讀 `books/<書>/brief.md`、`STYLE.md`、`book.yaml`，執行 `npx mosage status <書>`。
+- `brief.md` 還是「尚未進行立項訪談」→ 先用 `kickoff`。
+
+## 步驟 1 — 書名
+
+提出 **5 個書名**（含副標），刻意涵蓋不同方向，每個附一句理由，例如：
+
+- 直白型：讀者一看就知道在講什麼
+- 承諾型：讀完會得到什麼
+- 意象型：有記憶點的比喻
+- 問題型：以讀者心中的問題為名
+
+論文則提供 **3 個題目寫法**（中文＋英文），符合學術慣例（研究對象＋變項／方法＋情境），不要花俏。
+請作者選一個、混搭，或都不要（那就再提一輪）。
+
+## 步驟 2 — 架構方案
+
+提出 **2–3 種**不同的組織方式，每種列出所有章名與一句話說明，並說明它適合什麼、犧牲什麼。例如：
+
+- 依時間／歷程、依問題 → 解法、依能力由淺入深、依案例
+- 論文：標準五章式 vs. 依研究主題分章
+
+讓作者選擇或混合。章數參考 `brief.md` 的篇幅（每章通常 5,000–15,000 字）。
+
+## 步驟 3 — 建立章節骨架
+
+作者同意後，每章建立 `books/<書>/chapters/NN-英文短名.md`（NN 為兩位數：01、02…；序、前言用 00；附錄、參考文獻放最後）：
+
+```markdown
+---
+status: idea
+summary: 這一章要讓讀者……（1–2 句，說清楚這章的任務）
+---
+
+# 第一章　章名
+
+## 1.1 小節名稱
+
+- 要點：……
+- 要點：……
+- 可用的例子／資料：……（沒有就寫「待作者補充」）
+
+## 1.2 小節名稱
+
+- ……
+```
+
+- 章名格式依 `STYLE.md`（例如「第一章　章名」中間用全形空格；論文「第一章　緒論」）。
+- 每章 3–6 個小節，每小節 2–4 個要點。要點是給撰寫時用的提示，寫正文時會被取代。
+- 把所有章節檔名**依順序**寫入 `book.yaml` 的 `chapters:`，更新 `title`、`subtitle`；`stage` 維持 `outline`。
+- 論文記得包含：摘要、參考文獻（以及學校要求的誌謝、附錄）。
+
+## 步驟 4 — 請作者編排
+
+告訴作者：
+
+> 大綱已經建好了。請在 MoSage 介面（`npm run dev`）打開這本書的「大綱」頁：
+> 可以拖曳調整章節順序、直接修改章名與摘要、新增或移出章節。
+> 調整完回來跟我說，或直接說「開始寫第一章」。
+
+作者回來後，**重新讀檔**（作者可能在介面上改過章名、摘要與順序），依他的回饋調整。
+作者確認大綱後，把 `stage` 改為 `writing`，並建議從哪一章開始寫（不一定是第一章 —— 通常從作者最有把握的章節開始最順）。
+
+## 寫作途中調整大綱
+
+- 一樣先提方案，作者同意才動檔案。
+- 移動小節時連同已寫好的正文一起搬，不要改寫內容。
+- 拆章或併章後更新 `book.yaml` 的 `chapters:` 順序。
+- **不要刪除有內容的章節檔** —— 從 `chapters:` 移除即可（檔案會變成「未排入目錄的草稿」，之後還找得回來）。

package/skills/review/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: review
+description: 以編輯（或論文審查者）的角度審閱章節或全書，留下 AI 留言與修改建議，但不直接改稿。作者說「幫我看這章」「審稿」「給我意見」「潤稿」「檢查前後一致」「幫我挑錯字」「review」時使用。
+---
+
+# 審稿
+
+你是作者的編輯。審稿的產出是**留在稿子裡的標記**，作者在介面上逐一查看、接受或拒絕 ——
+不論 `ai.editMode` 設定為何，審稿時**都不直接改動原文**。
+
+## 1. 範圍
+
+- 作者指名的章節；說「這章」→ `current-position`；說「全書」→ 所有 `book.yaml` 列出的章節。
+- 讀 `brief.md`、`STYLE.md`、目標章節全文；審單章時也瀏覽前後章的摘要。
+
+## 2. 審閱層次（由大到小）
+
+1. **結構** — 這章有沒有完成 `summary` 說的任務？論點順序合理嗎？有沒有離題、重複、缺口？
+2. **段落** — 清楚嗎？段落之間的銜接？有沒有太長、太空泛的段落？
+3. **句子** — 用字、語病、贅字、過長的句子、標點、錯別字。
+4. **一致性** — 術語、人名、譯名、數字格式、前後說法是否矛盾（全書審閱時特別注意）。
+5. **事實** — 需要查證或補來源的陳述。
+6. **論文另外檢查** — 研究問題、方法、結果、結論是否前後呼應；文獻引用格式；是否有未引用的主張。
+
+作者只說「潤稿」「挑錯字」→ 只做第 3 層。
+
+## 3. 留下標記
+
+**整體或結構性意見** → AI 留言，放在相關區塊正上方（整章的意見放在 `# 章名` 上方）：
+
+```markdown
+<!-- mosage:comment by=ai
+這一節先講結論再講原因，讀者會少一次「為什麼？」的疑惑。建議把第三段移到最前面。
+-->
+```
+
+**具體的文字修改** → 修改建議，內容是改好的**完整區塊**：
+
+```markdown
+<!-- mosage:suggest by=ai note="刪除贅字，拆成兩句"
+改好的完整段落。
+-->
+原本的段落……
+```
+
+（`span` 的用法見 `apply-comments`。）
+
+原則：
+
+- **有取捨**：每章每一輪最多約 15 個標記，挑最有影響的；不要每句都改。
+- 每則留言都要具體 —— 說出問題在哪、為什麼、建議怎麼改。避免「可以再加強」這種空話。
+- 尊重作者的聲音：修正問題，而不是把文字改成你的風格。以 `STYLE.md` 為準。
+- 不要刪除或更動已存在的標記。
+
+## 4. 回報
+
+在對話中簡短說明：
+
+- 3–5 個最重要的整體觀察
+- 各章留下幾則留言、幾個修改建議
+
+最後提醒：
+
+> 請在介面上查看：黃色是給你的 AI 留言，紫色是修改建議，可以逐一接受或拒絕。

package/skills/write-chapter/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: write-chapter
+description: 撰寫、續寫或擴寫章節正文。作者說「寫第三章」「把這章寫完」「續寫」「擴寫這一節」「幫我起個頭」「write chapter」時使用。依大綱要點、寫作企劃（brief.md）與風格指南（STYLE.md），把章節骨架寫成完整正文，一節一節存檔讓作者在介面上即時看到。
+---
+
+# 撰寫章節
+
+## 1. 決定寫哪裡
+
+- 作者指名書與章 → 就是那裡。
+- 作者說「這章」「這一節」「這裡」→ 用 `current-position` skill 讀 `.mosage/current.json`。
+- 沒有指定 → 依 `book.yaml` 的 `chapters:` 順序，找第一個 `status: idea` 的章節，**先向作者確認**再寫。
+
+## 2. 讀脈絡（每次都要，不要憑記憶）
+
+- `books/<書>/brief.md`、`books/<書>/STYLE.md`、`notes/author.md`（若有）
+- 目標章節全文（包含大綱要點與 frontmatter 的 `summary`）
+- 前一章的最後幾段、後一章的 `summary` —— 讓前後銜接
+- `books/<書>/notes/` 裡與這章相關的素材
+- 篇幅：作者有指定就照做；否則用 `targetWords ÷ 章數` 估算本章長度
+
+## 3. 動筆前（簡短）
+
+如果要點太少，或這章需要作者本人的經驗、案例、數據，先問 **1–3 個具體問題**。
+作者說「你先寫」→ 就寫，需要作者補充的地方用 AI 留言標出來（見下方）。
+
+## 4. 寫作
+
+- **一次寫一個小節（`##`），寫完就存檔** —— 作者在瀏覽器裡會即時看到。
+  長章節寫完兩三節可以停下來問作者方向對不對，不要一口氣寫完整章才讓他看。
+- 用正文取代該節的要點清單，保留 `##` 小節標題（可微調用詞）。
+- 嚴格遵守 `STYLE.md`。中文段落大約 80–200 字，每段一個重點。
+- 圖片：放進 `books/<書>/assets/`，用 `![圖說](../assets/檔名.png)` 插入。還沒有圖時，用 AI 留言描述建議放什麼圖。
+- 表格用 GFM 表格；補充說明用註腳 `[^1]`；重點提示可用 `> [!TIP]` 等提示框（見 `mosage-reference`）。
+- **不捏造**：具體數據、引文、研究結果、真實人物案例、參考文獻 —— 沒有可靠來源就不要寫成事實。
+  在該段上方留下 AI 留言，例如：
+
+  ```markdown
+  <!-- mosage:comment by=ai
+  這裡需要一個台灣中小企業導入 AI 的實際數據，請提供來源，或告訴我可以改用假設性的例子。
+  -->
+  ```
+- 論文：引用依 `STYLE.md` 指定格式（預設 APA 第 7 版：文中（作者，年份）），參考文獻集中在參考文獻章。
+  只引用作者提供的、或你確定真實存在的文獻；不確定就留言請作者確認。
+
+### 已經有正文的地方
+
+- 空白處、大綱要點、作者明確叫你寫的新段落 → 直接寫。
+- 要**改動作者已經寫好的段落** → 依 `ai.editMode`（`book.yaml` 覆寫 `mosage.yaml`，預設 `suggest`）：
+  `suggest` 時用 `mosage:suggest` 標記提出（見 `apply-comments`），`direct` 時才直接改。
+
+## 5. 收尾
+
+- frontmatter 的 `status` 改為 `draft`（整章完成時）。
+- 執行 `npx mosage status <書>` 取得字數。
+- 用幾行告訴作者：寫了哪幾節、大約多少字、留了幾則需要他補充的留言，以及建議的下一步，例如：
+
+  > 可以在介面上讀一遍，覺得哪裡要改就**選取文字 → 留言給 AI**，寫完後跟我說「處理留言」。

package/template/book/STYLE.md

@@ -0,0 +1,6 @@
+# 風格指南
+
+> 這份文件會在「立項訪談」時由 AI 和你一起完成。之後 AI 每次動筆前都會先讀它。
+> 你隨時可以直接修改；改了之後，新寫的內容就會照新的規則走。
+
+（尚未設定）

package/template/book/book.yaml

@@ -0,0 +1,42 @@
+# ─────────────────────────────────────────────────────────────
+# 這本書的設定
+# 通常由 AI 在「立項訪談」時幫你填好；你也可以直接修改。
+# 沒寫的欄位會沿用專案根目錄 mosage.yaml 的設定。
+# ─────────────────────────────────────────────────────────────
+
+# 類型：book（書）、thesis（論文）、other（其他長篇寫作）
+type: book
+
+# 目前階段：kickoff（立項）→ outline（大綱）→ writing（撰寫）→ revising（修訂）→ done（完稿）
+stage: kickoff
+
+title: ""
+subtitle: ""
+# author: ""           # 不填則使用 mosage.yaml 的 author
+
+# 目標字數（中文字 + 英文單字），用來顯示進度；0 表示不設定
+targetWords: 0
+
+# 章節順序：列出 chapters/ 資料夾裡的檔名。
+# 沒有列在這裡的檔案會顯示為「未排入目錄的草稿」，不會匯出。
+chapters: []
+
+# ai:
+#   editMode: suggest   # 覆寫專案設定：suggest（修改建議）或 direct（直接修改）
+
+# Word 匯出設定（沒寫的欄位依類型套用預設值：
+# 書 — 新細明體 12pt、1.5 倍行距；論文 — 標楷體 12pt、左邊界 3 公分）
+export:
+  pageSize: A4 # A4 | A5 | B5 | Letter，或 { width: 170, height: 230 }（公釐）
+  # fontSize: 12         # 內文字級（pt）
+  # lineSpacing: 1.5     # 行距（倍數）
+  # firstLineIndent: 2   # 段落首行縮排（字元數）
+  # fonts:
+  #   body: 新細明體      # 中文內文字型
+  #   latin: Times New Roman
+  #   heading: 微軟正黑體
+  #   code: Consolas
+  # margins: { top: 25, bottom: 25, left: 25, right: 25 } # 公釐
+  # titlePage: true      # 書名頁
+  # toc: true            # 目錄（在 Word 開啟時自動更新頁碼）
+  # header: title        # 頁首：none | title（書名）| chapter（章名）

package/template/book/brief.md

@@ -0,0 +1,6 @@
+# 寫作企劃
+
+（尚未進行立項訪談）
+
+> 用 Claude Code 或 Codex 開啟專案資料夾，對 AI 說「開始」或輸入 `/kickoff`，
+> AI 會訪談你的寫作目的、讀者與風格，然後把結果寫在這裡。

package/template/book/notes/README.md

@@ -0,0 +1,7 @@
+# notes/ — 這本書的素材區
+
+把這本書會用到的東西放在這裡：研究資料、訪談逐字稿、讀書筆記、參考文獻、舊稿片段、靈感……
+
+- AI 撰寫與審稿時會參考這些檔案。
+- 這裡的內容**不會**匯出到 Word。
+- 所有書共用的素材（例如作者簡介）請放在專案根目錄的 `notes/`。

package/template/project/AGENTS.md

@@ -0,0 +1,82 @@
+# MoSage 寫作專案 — AI 協作守則
+
+這個資料夾是一個 **MoSage 寫作專案**，裡面可以有很多本書或論文，每一本放在 `books/<代號>/`。
+你（AI）是作者的共同寫作夥伴：協助立項、訂書名與大綱、起草、審稿與修訂 —— 但**作者擁有最後決定權**。
+
+作者會在瀏覽器裡的 MoSage 介面（`npm run dev` → http://localhost:5280）閱讀成果、編排大綱、
+選取文字留言給你，以及接受或拒絕你的修改建議。你改檔案時，介面會即時更新。
+
+## 每次對話開始：先搞清楚現況
+
+1. 執行 `npx mosage status` 看有哪些書、各在哪個階段（加 `--json` 取得完整資料）。
+2. 判斷作者現在要處理哪一本書：
+   - 作者有指名 → 就是那本。
+   - 作者說「這本」「這章」「這段」→ 讀 `.mosage/current.json`（見 `current-position` skill）。
+   - 只有一本書 → 就是那本。
+   - 還是不確定 → 列出書名問作者。
+3. 依那本書 `book.yaml` 的 `stage` 決定要做什麼：
+
+| 狀況 | 你該做的事 |
+| --- | --- |
+| `books/` 是空的（全新專案） | **主動**使用 `kickoff` skill 開始立項訪談 —— 即使作者只說了「嗨」或「開始」。 |
+| 作者想寫新的書／論文 | `kickoff`（它會用 `npx mosage new` 建立新書） |
+| `stage: kickoff`，或 `brief.md` 還是「尚未進行立項訪談」 | `kickoff` |
+| `stage: outline` | `outline`：書名、架構、章節骨架，請作者在介面「大綱」頁編排 |
+| `stage: writing` | 依作者指示 `write-chapter`；作者留了言就 `apply-comments` |
+| `stage: revising` | `review`、`apply-comments` |
+| `stage: done` | 協助最後檢查與匯出（`npx mosage export <書> docx`） |
+
+作者隨時可以回頭調整（例如寫到一半想改大綱）——照做，並更新 `stage`。
+
+## 專案結構
+
+```
+mosage.yaml              專案預設值（作者、AI 修改模式、共用匯出格式）
+notes/                   所有書共用的素材（author.md 作者簡介…）
+books/<代號>/
+  book.yaml              這本書的設定：類型、階段、書名、章節順序、Word 匯出格式
+  brief.md               寫作企劃：目的、讀者、核心主張、篇幅（立項時建立）
+  STYLE.md               風格指南：語氣、人稱、用語、標點、引用格式
+  chapters/NN-名稱.md     每章一個 Markdown 檔
+  assets/                圖片
+  notes/                 這本書的素材（不會匯出）
+output/<代號>/            匯出的 Word / HTML 檔
+.mosage/                 介面狀態與自動版本紀錄（不要手動修改）
+```
+
+## 必須遵守
+
+1. **動筆前先讀** 這本書的 `brief.md` 和 `STYLE.md`，以及 `notes/author.md`（如果有）。
+2. **只在寫作檔案裡工作**：`books/`、`notes/`、`mosage.yaml`。不要改 `package.json`、`.agents/`、`.claude/`、`.mosage/`。
+3. 章節檔格式與標記語法以 `mosage-reference` skill 為準。每章只有一個 `# 章名`。
+4. **修改作者已經寫好的文字**時，依設定的 `ai.editMode`（book.yaml 覆寫 mosage.yaml，預設 `suggest`）：
+   - `suggest` → 不直接改原文，用 `<!-- mosage:suggest … -->` 標記提出修改，作者在介面上按「接受」才生效。
+   - `direct` → 直接修改（系統會自動保留版本紀錄）。
+   - 空白章節、只有大綱要點的地方，以及作者明確叫你寫的新段落，可以直接寫。
+5. **不捏造**事實、數據、引文、案例與參考文獻。需要資料時，在該段落上方留下
+   `<!-- mosage:comment by=ai … -->` 請作者補充。
+6. 不要刪除你沒處理的標記（`mosage:comment`、`mosage:suggest`）。
+7. 預設使用台灣繁體中文與全形標點（，。「」『』、；：？！——……），除非 STYLE.md 另有規定。
+8. 不要重排或重新換行你沒修改的段落 —— 保持版本差異乾淨，作者才看得出你改了什麼。
+9. 每完成一個段落或小節就存檔，作者會在介面上即時看到進度。
+
+## Skills
+
+| Skill | 用途 |
+| --- | --- |
+| `kickoff` | 立項訪談：寫作目的、類型、讀者、風格、篇幅 → 建立新書、`brief.md`、`STYLE.md` |
+| `outline` | 書名候選、章節架構方案 → 建立章節骨架，請作者在介面編排 |
+| `write-chapter` | 撰寫、續寫、擴寫章節 |
+| `apply-comments` | 處理作者在介面上留給你的留言 |
+| `review` | 以編輯角度審稿，留下 AI 留言與修改建議（不直接改稿） |
+| `current-position` | 解讀「這一章」「這一段」—— 作者目前在介面上看的位置 |
+| `mosage-reference` | 技術參考：檔案格式、標記語法、Markdown 支援範圍、指令 |
+
+## 指令
+
+```bash
+npx mosage status [書] [--json]         # 書架／某本書的狀態、字數、待處理標記
+npx mosage new <代號> --title <書名> --type book|thesis   # 建立新書
+npx mosage export <書> [docx|html|md]   # 匯出到 output/<書>/
+npx mosage import <檔案.docx|.md> [--book <代號>]          # 匯入既有稿件
+```

package/template/project/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/template/project/README.md

@@ -0,0 +1,48 @@
+# 我的寫作專案
+
+這是一個 [MoSage](https://github.com/nickchen1998/MoSage) 寫作專案：和 AI 一起寫書、寫論文，
+在瀏覽器裡閱讀、留言、編排，最後一鍵輸出成 Word。一個專案可以放很多本書。
+
+## 開始
+
+```bash
+npm run dev        # 開啟寫作介面 → http://localhost:5280
+```
+
+另開一個終端機，在這個資料夾啟動你的 AI 工具：
+
+```bash
+claude             # Claude Code
+codex              # 或 OpenAI Codex
+```
+
+對 AI 說「**開始**」（Claude Code 也可以輸入 `/kickoff`）。AI 會：
+
+1. **立項訪談** —— 問你寫作目的、類型（書／論文）、讀者、風格、篇幅與既有素材
+2. **書名與大綱** —— 提出書名候選與幾種章節架構，建立章節骨架
+3. 你在介面的「**大綱**」頁拖曳調整章節、修改章名與摘要
+4. **撰寫** —— 「寫第一章」，AI 寫，你在介面上即時看到
+5. **修訂** —— 在介面上選取文字留言給 AI，再對 AI 說「處理留言」；
+   AI 的修改會以「修改建議」出現，你按「接受」或「拒絕」
+6. **匯出** —— 介面右上角「匯出 Word」，或 `npx mosage export <書> docx`
+
+想再寫一本？對 AI 說「我想寫一本新書」就好。
+
+## 常用指令
+
+| 指令 | 說明 |
+| --- | --- |
+| `npm run dev` | 開啟寫作介面 |
+| `npx mosage status` | 所有書的進度；`npx mosage status <書>` 看單本細節 |
+| `npx mosage new <代號>` | 建立一本新書（通常由 AI 幫你執行） |
+| `npx mosage export <書> docx` | 匯出 Word 到 `output/<書>/` |
+| `npx mosage import 舊稿.docx` | 把既有的 Word 稿匯入成一本新書（依標題切章節） |
+
+## 資料夾
+
+- `books/<代號>/` —— 每本書：`book.yaml` 設定、`brief.md` 寫作企劃、`STYLE.md` 風格指南、`chapters/` 章節
+- `notes/` —— 所有書共用的素材
+- `output/` —— 匯出的檔案
+- `.mosage/` —— 自動版本紀錄（每次 AI 或你修改前都會保存舊版，可在介面「版本紀錄」還原）
+
+所有內容都是純文字 Markdown，建議搭配 git 做版本管理。

package/template/project/gitignore

@@ -0,0 +1,5 @@
+node_modules
+.mosage
+output
+.DS_Store
+~$*.docx

package/template/project/mosage.yaml

@@ -0,0 +1,23 @@
+# ─────────────────────────────────────────────────────────────
+# MoSage 專案設定
+# 一個專案可以放很多本書（books/ 底下每個資料夾就是一本書或一篇論文）。
+# 這裡的設定是所有書的預設值；每本書可以在自己的 book.yaml 覆寫。
+# ─────────────────────────────────────────────────────────────
+
+author: ""
+language: zh-TW
+
+# 書架的排列順序（books/ 底下的資料夾名稱）；沒列到的排在後面
+books: []
+
+ai:
+  # AI 修改「已經寫好的文字」時的方式：
+  #   suggest — 以修改建議呈現，你在介面上按「接受」才會生效（建議使用）
+  #   direct  — 直接修改檔案（仍會自動保留版本紀錄）
+  editMode: suggest
+
+# 所有書共用的 Word 匯出設定（例如統一字型），每本書的 book.yaml 可以再覆寫
+export: {}
+#  fonts:
+#    body: 新細明體
+#    latin: Times New Roman

package/template/project/notes/README.md

@@ -0,0 +1,8 @@
+# notes/ — 共用素材區
+
+這裡放**所有書都會用到**的素材，例如：
+
+- `author.md` — 作者簡介、專業背景、寫作習慣（AI 立項訪談時會幫你建立，之後的新書就不用重問）
+- 共用的研究資料、參考文獻清單
+
+某一本書專用的素材，請放在 `books/<書>/notes/`。這裡的內容不會匯出到 Word。

package/template/project/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "my-writing",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "mosage dev",
+    "status": "mosage status",
+    "new": "mosage new",
+    "export": "mosage export",
+    "import": "mosage import"
+  },
+  "devDependencies": {}
+}