feat: MarkBase initial version

Phase 1 (Infrastructure): - Docs: README.md, AGENTS.md, CHANGELOG.md - Tests: 26 tests (modes_test, filetree_api_test) - Examples: examples/sample.md, sample.json - CI/CD: .gitea/workflows/test.yml, release.yml - Runner: configuration scripts and guides Phase 2 (Quality): - Code quality: rustfmt/clippy config - Security: environment variables - Test coverage: 62 tests (+36) - Documentation: CONTRIBUTING.md, docs/api.yaml - Showcase: demo_features.md, developer_quickstart.md Test coverage: 75% Test pass rate: 100%
2026-05-16 15:37:37 +08:00
commit e3d6b60825
50 changed files with 7758 additions and 0 deletions
--- a/examples/demo_features.md
+++ b/examples/demo_features.md
@@ -0,0 +1,133 @@
+# MarkBase功能展示範例
+
+## 一、Markdown渲染功能
+
+### 1.1標題支援
+
+# H1標題
+## H2標題
+### H3標題
+#### H4標題
+##### H5標題
+###### H6標題
+
+### 1.2文字格式
+
+**粗體文字**
+*斜體文字*
+**_粗體斜體_**
+~~刪除線~~
+
+### 1.3列表功能
+
+**無序列表：**
+-項目 1
+-項目 2
+  -子項目 2.1
+  -子項目 2.2
+-項目 3
+
+**有序列表：**
+1.第一項
+2.第二項
+3.第三項
+
+### 1.4表格支援
+
+|功能 |狀態 |說明 |
+|------|------|------|
+|表格 |✅支援 |標準 Markdown表格 |
+| Footnote | ✅支援 |腳註功能[^1] |
+| Tasklist | ✅支援 |待辦事項列表 |
+
+### 1.5代碼區塊
+
+```rust
+fn main() {
+    println!("Hello, MarkBase!");
+}
+```
+
+```python
+def hello():
+    print("Hello, MarkBase!")
+```
+
+---
+
+##二、檔案樹管理功能
+
+### 2.1 REST API範例
+
+```bash
+#取得檔案樹
+curl http://localhost:11438/api/v2/tree/demo?mode=tree
+
+#建立資料夾節點
+curl -X POST http://localhost:11438/api/v2/tree/demo/node \
+  -H "Content-Type: application/json" \
+  -d '{"label":"Videos", "node_type":"folder"}'
+
+#更新節點別名
+curl -X PATCH http://localhost:11438/api/v2/tree/demo/node/<node_id>/alias \
+  -H "Content-Type: application/json" \
+  -d '{"lang":"zh_tw", "value":"影片"}'
+```
+
+### 2.2顯示模式
+
+|模式 |說明 |用途 |
+|------|------|------|
+| tree |樹狀顯示 |層級結構展示 |
+| list |列表顯示 |簡潔列表展示 |
+| grid_sm |小格狀顯示 |緊湊格狀展示 |
+| grid_lg |大格狀顯示 |寬鬆格狀展示 |
+
+---
+
+##三、macOS音訊功能
+
+### 3.1音訊裝置API
+
+```bash
+#列出所有音訊裝置
+curl http://localhost:11438/devices
+
+#取得音量
+curl http://localhost:11438/volume
+
+#切換音訊裝置（透過command API）
+curl -X POST http://localhost:11438/command \
+  -H "Content-Type: application/json" \
+  -d '{"cmd":"test_voice", "val":"zh_TW", "out":"Display Audio"}'
+```
+
+---
+
+##四、Mermaid圖表支援
+
+```mermaid
+graph TD
+    A[MarkBase入口] --> B[CLI解析]
+    B --> C[Display伺服器]
+    B --> D[Render工具]
+    C --> E[REST API]
+    E --> F[檔案樹管理]
+    E --> G[音訊控制]
+```
+
+---
+
+##五、多語別別名範例
+
+|節點 |英文 |中文 |日文 |
+|------|------|------|------|
+| Videos | Videos |影片 |動画 |
+| Movies | Movies |電影 |映画 |
+| Marketing | Marketing |行銷 |マーケティング |
+
+---
+
+**MarkBase展示範例完成！**
+
+[^1]: 這是一個腳註範例。
--- a/examples/developer_quickstart.md
+++ b/examples/developer_quickstart.md
@@ -0,0 +1,248 @@
+# 開發者快速展示指南
+
+##目的
+
+本文件提供MarkBase核心功能的快速展示範例。
+
+---
+
+##一、基礎展示（3分鐘）
+
+### 1.1啟動伺服器
+
+```bash
+cargo run -- display
+```
+
+**預期結果：**
+-伺服器啟動在 http://localhost:11438
+-瀏覽器自動開啟
+-顯示 MarkBase主頁
+
+### 1.2顯示範例文件
+
+```bash
+cargo run -- display examples/demo_features.md
+```
+
+**預期結果：**
+-顯示完整功能展示文檔
+-支援表格、列表、代碼區塊
+
+---
+
+##二、檔案樹展示（5分鐘）
+
+### 2.1查看 Demo資料
+
+```bash
+curl http://localhost:11438/api/v2/tree/demo?mode=tree
+```
+
+**預期結果：**
+-返回 JSON格式的檔案樹結構
+- 50個節點（5 Folder + 45 File）
+
+### 2.2不同顯示模式
+
+```bash
+#列表模式
+curl http://localhost:11438/api/v2/tree/demo?mode=list
+
+#小格狀模式
+curl http://localhost:11438/api/v2/tree/demo?mode=grid_sm
+
+#大格狀模式
+curl http://localhost:11438/api/v2/tree/demo?mode=grid_lg
+```
+
+### 2.3建立新節點
+
+```bash
+curl -X POST http://localhost:11438/api/v2/tree/demo/node \
+  -H "Content-Type: application/json" \
+  -d '{"label":"展示資料夾", "node_type":"folder"}'
+```
+
+**預期結果：**
+-返回 node_id
+-狀態碼 201（CREATED）
+
+---
+
+##三、音訊功能展示（macOS）
+
+### 3.1列出音訊裝置
+
+```bash
+curl http://localhost:11438/devices
+```
+
+**預期結果：**
+-列出所有輸出裝置
+-列出所有輸入裝置
+-顯示當前選用裝置
+
+### 3.2語音測試
+
+```bash
+curl -X POST http://localhost:11438/command \
+  -H "Content-Type: application/json" \
+  -d '{"cmd":"test_voice", "val":"zh_TW"}'
+```
+
+**預期結果：**
+-播放中文語音「語音測試一二三」
+
+---
+
+##四、渲染功能展示
+
+### 4.1渲染 Markdown檔案
+
+```bash
+cargo run -- render examples/demo_features.md
+```
+
+**預期結果：**
+-輸出 HTML到 stdout
+
+### 4.2輸出到檔案
+
+```bash
+cargo run -- render examples/demo_features.md -o demo_output.html
+```
+
+**預期結果：**
+-生成 demo_output.html檔案
+
+---
+
+##五、測試展示
+
+### 5.1執行所有測試
+
+```bash
+cargo test --all
+```
+
+**預期結果：**
+- 62個測試全部通過
+-執行時間 ~1秒
+
+### 5.2特定模組測試
+
+```bash
+cargo test filetree
+cargo test modes
+cargo test api_logic
+```
+
+---
+
+##六、代碼品質展示
+
+### 6.1格式化檢查
+
+```bash
+cargo fmt -- --check
+```
+
+**預期結果：**
+-無差異（代碼已格式化）
+
+### 6.2 Clippy檢查
+
+```bash
+cargo clippy --all-targets
+```
+
+**預期結果：**
+-少數次要警告（可忽略）
+-主要警告已修復
+
+---
+
+##七、 Runner展示
+
+### 7.1啟動 Runner
+
+```bash
+cd /Users/accusys/markbase
+./scripts/start_runner.sh
+```
+
+**預期結果：**
+- Runner連接遠端 Gitea
+-日誌輸出到/tmp/gitea-runner.log
+
+### 7.2驗證 Runner狀態
+
+```bash
+./scripts/verify_runner.sh
+```
+
+**預期結果：**
+-顯示 Runner配置狀態
+-顯示環境準備度
+
+---
+
+##八、展示腳本整合
+
+###完整展示流程
+
+```bash
+# 1.建構專案
+cargo build
+
+# 2.啟動伺服器
+cargo run -- display examples/demo_features.md
+
+# 3.測試檔案樹API
+curl http://localhost:11438/api/v2/tree/demo
+
+# 4.測試音訊功能
+curl http://localhost:11438/devices
+
+# 5.執行測試
+cargo test --all
+
+# 6.代碼品質檢查
+cargo clippy
+
+# 7. Runner驗證
+./scripts/verify_runner.sh
+```
+
+---
+
+##九、展示檔案位置
+
+```
+examples/
+├── demo_features.md         # 功能展示文檔
+├── developer_quickstart.md  #開發者快速指南
+├── sample.md                #基本範例
+├── sample.json              # JSON範例
+└── files/
+    ├── example_video.mp4    #影片範例（待補充）
+    ├── example_audio.mp3    #音訊範例（待補充）
+    └── example_image.jpg    #圖片範例（待補充）
+```
+
+---
+
+##十、展示檢查清單
+
+展示前確認：
+
+- [ ] cargo build成功
+- [ ] cargo test全部通過
+- [ ] SwitchAudioSource已安裝（macOS）
+- [ ] demo.sqlite資料完整（50節點）
+- [ ] Runner已啟動（若展示 CI/CD）
+
+---
+
+**展示指南完成！**
--- a/examples/sample.json
+++ b/examples/sample.json
@@ -0,0 +1,42 @@
+{
+  "title": "MarkBase範例 JSON",
+  "version": "1.0.0",
+  "features": [
+    {
+      "name": "Markdown渲染",
+      "status": "active",
+      "description": "支援完整 Markdown語法"
+    },
+    {
+      "name": "檔案樹管理",
+      "status": "active",
+      "description": "SQLite持久化檔案樹"
+    },
+    {
+      "name": "REST API",
+      "status": "active",
+      "description": "18+ RESTful路由"
+    },
+    {
+      "name": "音訊控制",
+      "status": "active",
+      "description": "macOS音訊裝置管理"
+    }
+  ],
+  "config": {
+    "port": 11438,
+    "db_dir": "data/users",
+    "cache_dir": "data/cache"
+  },
+  "display_modes": [
+    "tree",
+    "list",
+    "grid_sm",
+    "grid_lg"
+  ],
+  "metadata": {
+    "author": "MarkBase Team",
+    "created_at": "2026-05-16",
+    "updated_at": "2026-05-16"
+  }
+}
--- a/examples/sample.md
+++ b/examples/sample.md
@@ -0,0 +1,100 @@
+# MarkBase範例文件
+
+## 概述
+
+這是一個範例 Markdown檔案，展示 MarkBase的渲染能力。
+
+## 功能展示
+
+###表格支援
+
+|功能 |狀態 |說明 |
+|------|------|------|
+|表格 |✅支援 |標準 Markdown表格 |
+| Footnote | ✅支援 |腳註功能[^1] |
+| Tasklist | ✅支援 |待辦事項列表 |
+| Strikethrough | ✅支援 |~~刪除線~~ |
+
+###待辦事項列表
+
+- [x]已完成項目
+- [ ]待完成項目
+- [ ]另一個待完成項目
+
+###代碼區塊
+
+```rust
+fn main() {
+    println!("Hello, MarkBase!");
+}
+```
+
+```python
+def hello():
+    print("Hello, MarkBase!")
+```
+
+###標題層級
+
+# H1標題
+## H2標題
+### H3標題
+#### H4標題
+##### H5標題
+###### H6標題
+
+###列表
+
+**無序列表：**
+-項目 1
+- 項目 2
+  -子項目 2.1
+  - 子項目 2.2
+-項目 3
+
+**有序列表：**
+1.第一項
+2. 第二項
+3. 第三項
+
+###連結與圖片
+
+**連結：**
+- [MarkBase GitHub](https://github.com/example/markbase)
+- [Rust官方](https://www.rust-lang.org/)
+
+**圖片：**
+（需提供實際圖片路徑）
+
+###引用
+
+> 這是一個引用區塊。
+> 
+> 可以包含多行文字。
+
+###分隔線
+
+---
+
+###強調
+
+**粗體文字**
+*斜體文字*
+**_粗體斜體_**
+~~刪除線~~
+
+---
+
+## Mermaid圖表（支援）
+
+```mermaid
+graph TD
+    A[開始] --> B[處理]
+    B --> C{決策}
+    C -->|是| D[結束]
+    C -->|否| B
+```
+
+---
+
+[^1]: 這是一個腳註範例。