@luoyi-dsh/instagram-scroll 1.0.0 → 1.0.3

package/README.md

@@ -1,158 +1,202 @@
-# DSH Instagram 滾動瀏覽與探索插件 (`@luoyi-dsh/instagram-scroll`)
-
-![Banner](assets/banner.png)
-
-> **DeepSeek Harness (DSH)** 專屬的 Instagram 動態探索、智慧推坑與日報生成外掛。  
-> 具備核心能力：**定時或手動替主人刷一輪 Instagram 首頁動態與主題標籤、逐條閱讀內文評估主人興趣、自動點讚與留言推坑，並自動彙整生成每日 Markdown 探索日報**。
-
----
-
-## 🌟 核心特性
-
-1. **自動動態探索巡查 (Scroll Duty)**：
-   - 定期輪詢首頁動態牆 (Timeline Feed) 與指定主題標籤 (Hashtags)。
-   - 逐則貼文抓取標題、作者、標籤與完整內文。
-2. **LLM 價值評估與推坑 (AI Recommendation)**：
-   - 由大語言模型依據主人的興趣 Prompt 深度分析貼文內容與價值評分。
-   - 若達標（預設 > 75 分），自動在貼文下點讚並留言 `@目標用戶` 附上真誠自然的推薦語。
-3. **每日探索日報 (Daily Markdown Report)**：
-   - 自動將今日瀏覽之所有精選貼文、摘要與推薦紀錄整理為 Markdown 日報。
-   - 儲存於 `data/reports/YYYY-MM-DD.md`，可隨時在 Web 面板查看與回溯。
-4. **狀態帳本與嚴格去重控制**：
-   - `data/scroll_ledger.json` 記錄已看貼文 PK 與今日推坑次數，避免重複推坑或重複閱讀，並防止觸發風控。
-5. **DSH Web 瀏覽器端介面 (`client.js`)**：
-   - 提供直觀動態牆瀑布流預覽、即時手動觸發刷動態按鈕、日報閱讀器與自訂設定面板。
-
----
-
-## 📦 安裝方式
-
-使用 DSH CLI 安裝插件：
-
-```bash
-dsh plugin --profile web add @luoyi-dsh/instagram-scroll
-```
-
-或透過 npm 安裝：
-
-```bash
-npm install @luoyi-dsh/instagram-scroll
-```
-
----
-
-## 🛠️ 提供之 DSH Tools
-
-| 工具名稱 | 說明 | 參數 |
-| :--- | :--- | :--- |
-| **`ig_run_scroll_duty_now`** | 立即手動替主人刷一輪 Instagram 動態與探索，讀取貼文進行評估、點讚與留言推坑 | 無 |
-| **`ig_scroll_feed`** | 滾動讀取 Instagram 時間軸最新動態貼文（含作者、讚數、內文摘要） | `limit` (number，預設 15，最大 50) |
-| **`ig_explore_topics`** | 依照指定主題或探索標籤滾動閱讀熱門貼文 | `tag` (string，必填), `limit` (number，預設 15) |
-| **`ig_like_feed_post`** | 在滾動瀏覽過程中對感興趣的 Instagram 貼文按讚 | `media_pk` (string，必填) |
-
----
-
-## 💻 使用範例
-
-### 1. DSH AI 自然語言直接調用
-
-在 DSH 對話中，主模型可直接以自然語言執行滾動探索或瀏覽：
-
-```text
-💬 範例 1：執行一輪完整的動態探索與推坑
-「請立刻替我刷一輪 Instagram 動態牆，看看有沒有適合我的技術新貼文並推薦給我」
--> AI 將調用：ig_run_scroll_duty_now()
-
-💬 範例 2：滾動瀏覽首頁動態貼文
-「幫我刷最新 10 則 Instagram 動態」
--> AI 將調用：ig_scroll_feed(limit=10)
-
-💬 範例 3：探索特定主題標籤
-「探索 Instagram 上 #deepseek 標籤的熱門貼文」
--> AI 將調用：ig_explore_topics(tag="deepseek", limit=15)
-```
-
----
-
-### 2. 透過 HTTP REST API 調用 (DSH Web 路由)
-
-> 💡 **提示**：DSH Web 預設埠號為 **3080**。插件已註冊官方 REST API（前綴 `/api/instagram/scroll`）：
-
-#### 1. 手動觸發滾動一輪 (`POST /api/instagram/scroll/run`)
-```bash
-curl -X POST http://127.0.0.1:3080/api/instagram/scroll/run
-```
-
-#### 2. 獲取當前滾動狀態與今日統計 (`GET /api/instagram/scroll/status`)
-```bash
-curl http://127.0.0.1:3080/api/instagram/scroll/status
-```
-
-#### 3. 讀取今日探索日報內容 (`GET /api/instagram/scroll/report`)
-```bash
-curl http://127.0.0.1:3080/api/instagram/scroll/report
-```
-
-#### 4. 讀取與更新設定 (`GET / POST /api/instagram/scroll/config`)
-```bash
-# 取得設定
-curl http://127.0.0.1:3080/api/instagram/scroll/config
-
-# 更新設定
-curl -X POST http://127.0.0.1:3080/api/instagram/scroll/config \
-  -H "Content-Type: application/json" \
-  -d '{"masterUsername":"your_username","minScore":80}'
-```
-
----
-
-## ⚙️ 設定參數說明 (Settings)
-
-可於 DSH 設定面板或插件目錄下的 `data/config.json` 中配置：
-
-| 欄位名稱 | 型別 | 預設值 | 說明 |
-| :--- | :--- | :--- | :--- |
-| **`masterUsername`** | string | `""` | 主人的 Instagram 使用者名稱（達標時在留言區 @主人 推薦） |
-| **`interestTags`** | array | `["ai", "deepseek", "coding", "tech"]` | 主人感興趣的主題標籤或領域關鍵字清單 |
-| **`personaPrompt`** | string | *預設人設提示詞* | 評估貼文趣味度與撰寫 @主人 推薦語的人設 Prompt |
-| **`minScore`** | number | `75` | 推坑門檻分數（0-100，達標才在貼文下留言推薦） |
-| **`dailyRecommendCap`** | number | `5` | 每日向主人推坑留言的上限則數（防止過度打擾與風控） |
-| **`scrollIntervalMinutes`**| number | `60` | 自動巡查刷動態牆的時間週期（分鐘） |
-| **`autoScrollEnabled`** | boolean| `true` | 是否啟用背景定時自動刷動態牆任務 |
-| **`likeOnRecommend`** | boolean| `true` | 決定推薦給主人時是否順便對該貼文點讚 |
-| **`batchSize`** | number | `15` | 每輪滾動瀏覽抓取的貼文筆數 (10-30) |
-
----
-
-## 📁 目錄結構
-
-```text
-dsh-instagram-scroll/
-├── cordis.patch.yml               # DSH bundle patch 宣告
-├── package.json                   # 模組定義與依賴
-├── tsconfig.json                  # TypeScript 編譯設定
-├── assets/
-│   └── banner.png                 # 宣傳橫幅
-├── client.js                      # DSH Web 前端面板 (動態瀏覽、手動觸發、日報查看)
-├── data/
-│   ├── config.json                # 本地設定檔
-│   ├── scroll_ledger.json         # 瀏覽去重與統計帳本
-│   └── reports/                   # 每日日報儲存目錄 (YYYY-MM-DD.md)
-└── src/
-    ├── index.ts                   # Cordis 外掛入口、排程定時器與 Web API
-    ├── config.ts                  # Schemastery 設定模型
-    ├── types.d.ts                 # 型別宣告
-    ├── core/
-    │   └── scrollDuty.ts          # 滾動瀏覽、大模型評估、點讚與推坑核心邏輯
-    ├── lib/
-    │   ├── hostdeps.ts            # DSH 宿主相容層
-    │   └── ledger.ts              # 日報生成與歷史去重帳本管理器
-    └── tools/
-        └── scrollTools.ts         # 向 DSH Tools 註冊之專用滾動瀏覽工具
-```
-
----
-
-## 📄 授權條款
-
-本專案採用 [MIT License](LICENSE) 開源授權。
+# DSH Instagram Scroll Feed & Exploration Plugin (`@luoyi-dsh/instagram-scroll`)
+
+<div align="center">
+
+![DSH Instagram Scroll Banner](assets/banner.png)
+
+**[English](README.md) | [繁體中文](README.zh-Hant.md)**
+
+</div>
+
+> Dedicated Instagram feed exploration, AI recommendation, and daily digest plugin for **DeepSeek Harness (DSH)**.  
+> Core capabilities: **Automatically or manually browse Instagram timeline feeds and topic hashtags on behalf of the user, evaluate post relevance against the owner's interests using LLMs, like and leave authentic recommendation comments, and aggregate highlights into daily Markdown reports**.
+
+> [!CAUTION]
+> ### ⚠️ CRITICAL WARNING & DISCLAIMER
+> 1. **Violation of Instagram Terms of Service & Community Guidelines**:
+>    This plugin and its automated feed browsing, liking, and commenting routines operate via unofficial APIs, which **expressly violates Instagram / Meta's Terms of Use and Community Guidelines**.
+> 2. **DO NOT USE YOUR PERSONAL / PRIMARY ACCOUNT**:
+>    **Never run this plugin using your personal, primary, or business Instagram account!** Automated browsing and repeated comment posting are quickly flagged by Instagram's anti-scraping and bot-detection heuristics, resulting in: **Action Blocks, Challenge Checkpoints, temporary locks, and PERMANENT ACCOUNT SUSPENSION / BANNING**.
+> 3. **Use Dedicated Burner / Alt Accounts & Clean Proxies**:
+>    Only run this plugin on disposable secondary accounts (burner/alt accounts) with dedicated residential proxies. Avoid sudden geographic IP changes.
+> 4. **Built-in Anti-Risk Safeguards**:
+>    - **Per-Run Action Cap**: Strictly limits recommendations to at most 1 per scroll run (`maxRecommendsPerRun: 1`) to avoid burst posting.
+>    - **Humanized Reading Delays**: Injects randomized 3–7s reading delays between scanning candidate posts (`minPostReadDelaySeconds: 3, maxPostReadDelaySeconds: 7`).
+>    - **Action Jitter**: Enforces 6–15s randomized delays before executing comments or likes.
+>    - **Circuit Breaker Cooldown**: Automatically pauses all exploration for 30 minutes if an Action Block or rate limit is encountered.
+> 5. **Disclaimer**:
+>    This project is provided strictly for educational and technical research purposes. The developers and contributors accept **no responsibility or liability** for any account bans, suspensions, or losses resulting from its use. Use entirely at your own risk!
+
+---
+
+## 🌟 Key Features
+
+1. **Automated Feed Browsing (Scroll Duty)**:
+   - Periodically polls timeline feeds and configured topic hashtags.
+   - Extracts post caption, author, tags, and media metadata.
+2. **Deep Content Inspection & User Preference Alignment**:
+   - **No Superficial Recommendations**: Abandons simple hashtag-only / high-like criteria; threshold raised to score 80.
+   - **Caption & Tag Separation**: Dissects raw captions to separate genuine body text from trailing hashtags and mentions. Posts with substantive body text shorter than `minCaptionLength` (30 chars) are discarded.
+   - **Hashtag Spam / Farm Detection**: Flags and drops posts where tags dominate over meaningful content.
+   - **Body Topic Verification**: Mandates that master's interest keywords/topics genuinely appear within the post body (`requireBodyMatch`).
+   - **Negative / Spam Filtering**: Instantly filters out giveaways, mutual-follows, dropshipping, gambling, emotional clickbait, and superficial selfie/meme posts.
+   - **LLM Semantic Review & Tailored Hook**: Evaluates true content substance via LLM or robust heuristic review, synthesizing custom authentic recommendation comments.
+3. **Daily Markdown Digest (`data/reports/YYYY-MM-DD.md`)**:
+   - Automatically organizes reviewed posts, summaries, and recommendation trails into clean Markdown daily digests.
+   - Viewable directly in the web console.
+4. **State Ledger & Deduplication**:
+   - `data/scroll_ledger.json` keeps track of inspected media PKs and daily quotas to prevent repetitive actions and avoid rate limits.
+5. **DSH Web Control Panel (`client.js`)**:
+   - Provides an intuitive feed waterfall preview, manual duty execution button, daily report reader, and settings inspector.
+
+---
+
+## 📦 Installation
+
+Install via DSH Plugin CLI:
+
+```bash
+dsh plugin --profile web add @luoyi-dsh/instagram-scroll
+```
+
+Or via standard npm:
+
+```bash
+npm install @luoyi-dsh/instagram-scroll
+```
+
+---
+
+## 🛠️ Provided DSH Tools
+
+| Tool Name | Description | Parameters |
+| :--- | :--- | :--- |
+| **`ig_run_scroll_duty_now`** | Trigger an immediate exploration duty cycle (evaluate posts, like & recommend) | None |
+| **`ig_scroll_feed`** | Read timeline feed posts (author, like count, caption excerpt) | `limit` (number, default 15, max 50) |
+| **`ig_explore_topics`** | Explore popular posts under a specific topic or hashtag | `tag` (string, required), `limit` (number, default 15) |
+| **`ig_like_feed_post`** | Like an Instagram post during browsing | `media_pk` (string, required) |
+
+---
+
+## 💻 Usage Examples
+
+### 1. Natural Language Invocation in DSH Chat
+
+```text
+💬 Example 1: Run full exploration and recommendation duty
+"Please check my Instagram feed right now and recommend any interesting technical posts."
+-> AI calls: ig_run_scroll_duty_now()
+
+💬 Example 2: Read timeline posts
+"Browse the latest 10 posts on my Instagram feed."
+-> AI calls: ig_scroll_feed(limit=10)
+
+💬 Example 3: Explore a hashtag
+"Explore top posts under #deepseek on Instagram."
+-> AI calls: ig_explore_topics(tag="deepseek", limit=15)
+```
+
+---
+
+### 2. Via HTTP REST API (DSH Web Routes)
+
+> 💡 **Tip**: Default DSH Web port is **3080**.
+
+#### 1. Manually Trigger Duty Cycle (`POST /api/instagram/scroll/run`)
+```bash
+curl -X POST http://127.0.0.1:3080/api/instagram/scroll/run
+```
+
+#### 2. Get Current Status & Daily Stats (`GET /api/instagram/scroll/status`)
+```bash
+curl http://127.0.0.1:3080/api/instagram/scroll/status
+```
+
+#### 3. Read Today's Markdown Digest (`GET /api/instagram/scroll/report`)
+```bash
+curl http://127.0.0.1:3080/api/instagram/scroll/report
+```
+
+#### 4. Read & Update Configuration (`GET / POST /api/instagram/scroll/config`)
+```bash
+# Read config
+curl http://127.0.0.1:3080/api/instagram/scroll/config
+
+# Update config
+curl -X POST http://127.0.0.1:3080/api/instagram/scroll/config \
+  -H "Content-Type: application/json" \
+  -d '{"masterUsername":"your_username","minScore":80}'
+```
+
+---
+
+## ⚙️ Configuration Parameters (Settings)
+
+> 💡 **Tip**: No need to configure Instagram credentials here; it automatically inherits session state from `@luoyi-dsh/instagram-mcp`.
+
+| Field | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| **`masterUsername`** | string | `""` | Master's Instagram username (mentioned in comments when recommended) |
+| **`userInterests`** | string | *Default persona description* | Detailed description of owner's topics, taste, and technical expectations |
+| **`positiveKeywords`** | array | `["ai", "deepseek", ...]` | High-priority positive topic keywords required in post body |
+| **`negativeKeywords`** | array | `["互粉", "代購", "抽獎", ...]` | Negative / spam blacklist words to immediately reject |
+| **`minCaptionLength`** | number | `30` | Minimum character length of genuine post body (excluding hashtags) |
+| **`requireBodyMatch`** | boolean| `true` | Body text must substantiate owner's preferences (rejects tag-only matches) |
+| **`strictContentCheck`**| boolean| `true` | Enables deep content inspection pipeline before commenting |
+| **`interestTags`** | array | `["ai", "deepseek", "coding", "tech", "gadgets"]` | Exploration starting tags (not sole recommendation criteria) |
+| **`personaPrompt`** | string | *Default persona prompt* | Persona prompt guiding post analysis and recommendation copywriting |
+| **`minScore`** | number | `80` | Recommendation score threshold (0-100; elevated to avoid spam) |
+| **`dailyRecommendCap`** | number | `5` | Maximum recommendation comments allowed per day |
+| **`maxRecommendsPerRun`**| number | `1` | Max recommendations per duty run to prevent bursting |
+| **`minPostReadDelaySeconds`** | number | `3` | Minimum human reading pacing delay between posts |
+| **`maxPostReadDelaySeconds`** | number | `7` | Maximum human reading pacing delay between posts |
+| **`cooldownOnBlockMinutes`** | number | `30` | Automatic circuit breaker cooldown minutes upon action blocks |
+| **`scrollIntervalMinutes`**| number | `60` | Background exploration duty interval in minutes |
+| **`autoScrollEnabled`** | boolean| `true` | Whether background automated exploration duty is enabled |
+| **`likeOnRecommend`** | boolean| `true` | Automatically like post upon recommending to master |
+| **`batchSize`** | number | `15` | Number of posts inspected per scroll duty round (10-30) |
+
+---
+
+## 📁 Directory Structure
+
+```text
+dsh-instagram-scroll/
+├── cordis.patch.yml               # DSH bundle patch manifest
+├── package.json                   # Module definitions and dependencies
+├── tsconfig.json                  # TypeScript compiler configuration
+├── CHANGELOG.md                   # Version release notes
+├── README.md                      # English documentation (This file)
+├── README.zh-Hant.md              # Traditional Chinese documentation
+├── assets/
+│   ├── banner.png                 # Promotional banner
+│   └── zh-Hant.md                 # Localized documentation
+├── client.js                      # DSH Web UI panel
+├── data/                          # [Runtime generated, ignored in Git]
+│   ├── config.json                # Local configuration
+│   ├── scroll_ledger.json         # Deduplication and quota ledger
+│   └── reports/                   # Daily reports folder (YYYY-MM-DD.md)
+└── src/
+    ├── index.ts                   # Cordis plugin entrypoint and Web API
+    ├── config.ts                  # Schemastery config schema
+    ├── types.d.ts                 # Type definitions
+    ├── core/
+    │   └── scrollDuty.ts          # Scroll duty execution, LLM evaluation, likes & comments
+    ├── lib/
+    │   ├── hostdeps.ts            # DSH runtime compatibility layer
+    │   └── ledger.ts              # Daily digest and history ledger manager
+    └── tools/
+        └── scrollTools.ts         # Dedicated DSH tools registration
+```
+
+---
+
+## 📜 Releases & Changelog
+
+For detailed release history and changes, please refer to [CHANGELOG.md](CHANGELOG.md).
+
+---
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).

package/README.zh-Hant.md

@@ -0,0 +1,204 @@
+# DSH Instagram 滾動瀏覽與探索插件 (`@luoyi-dsh/instagram-scroll`)
+
+<div align="center">
+
+![DSH Instagram Scroll Banner](assets/banner.png)
+
+**[English](README.md) | [繁體中文](README.zh-Hant.md)**
+
+</div>
+
+> **DeepSeek Harness (DSH)** 專屬的 Instagram 動態探索、智慧推坑與日報生成外掛。  
+> 具備核心能力：**定時或手動替主人刷一輪 Instagram 首頁動態與主題標籤、逐條閱讀內文評估主人興趣、自動點讚與留言推坑，並自動彙整生成每日 Markdown 探索日報**。
+
+> [!CAUTION]
+> ### ⚠️ 重要風險警告與免責聲明 (CRITICAL DISCLAIMER)
+> 1. **違反 Instagram 社群守則與使用條款**：
+>    本插件及其背後的自動化刷動態、自動按讚與自動 @主人推坑留言機制，**明確違反了 Instagram / Meta 的《服務條款 (Terms of Use)》及《社群守則 (Community Guidelines)》**。
+> 2. **切勿使用本人主要帳號運行 (DO NOT USE YOUR PRIMARY ACCOUNT)**：
+>    **強烈嚴禁使用您個人的日常主要帳號、官方認證帳號或重要商業帳號！** Instagram 擁有極為敏銳的反機器人檢測演算法，持續的動態滾動、頻繁讀取及自動留評極易觸發官方風控，導致：**功能限制 (Action Blocked)、強制安全挑戰 (Challenge Checkpoint)、帳號臨時鎖定、甚至永久停權封號 (Permanent Ban)**！
+> 3. **測試與備用小號原則**：
+>    若需測試本外掛，請務必使用**無重要資料的測試用小號 (Burner / Alt Account)**，並強烈建議配置**優質純淨的住宅代理伺服器 (Residential Proxy)**，切勿在短時間內切換不同國家/地區的 IP。
+> 4. **內建防風控安全機制**：
+>    - **單輪推坑上限**：每輪滾動瀏覽最多僅推薦 1 則內容 (`maxRecommendsPerRun: 1`)，杜絕短時間密集推坑。
+>    - **擬真閱讀微延遲**：每掃描一則貼文前隨機等待 3~7 秒 (`minPostReadDelaySeconds: 3, maxPostReadDelaySeconds: 7`)，模擬真人滑動與停留閱讀。
+>    - **動作抖動延遲**：留言與點讚動作注入 6~15 秒隨機抖動等待 (Jitter)。
+>    - **風控熔斷保護**：遇到官方 Action Block / 頻率限制異常時，自動觸發 30 分鐘冷卻保護模式，暫停一切自動化推薦。
+> 5. **免責宣告**：
+>    本專案純屬程式技術研究與開源通訊協定評估用途。使用者因安裝、運行或配置本外掛所導致之任何帳號停權、封禁、資料損失或相關責任，**開發者一概不負任何法律與連帶賠償責任**，使用時請務必審慎評估並自負風險！
+
+---
+
+## 🌟 核心特性
+
+1. **自動動態探索巡查 (Scroll Duty)**：
+   - 定期輪詢首頁動態牆 (Timeline Feed) 與指定主題標籤 (Hashtags)。
+   - 逐則貼文抓取標題、作者、標籤與完整內文。
+2. **正文深度審查與用戶偏好推薦 (Content Inspection Pipeline)**：
+   - **絕不隨便推薦**：徹底拋棄僅看 tag 與點讚數的粗糙過濾，門檻提高至 80 分。
+   - **正文與標籤徹底分離**：自動分離真實正文與文末 `#標籤`，有效字數過短或僅有單一 emoji 者直接判定為無實質內容過濾。
+   - **標籤農場攔截**：偵測標籤堆砌蹭熱度（Hashtag Spamming），杜絕空洞蹭流量貼文。
+   - **正文主題實質核驗**：正文必須切實探討主人喜愛的領域與關鍵詞，禁止僅在文末掛標籤蹭熱度。
+   - **負向廣告與垃圾過濾**：自動排除互粉、代購、抽獎、博彩、微商、心靈雞湯與純自拍娛樂等無效內容。
+   - **LLM / 語義深度質檢與客製化推坑詞**：結合主人喜好描述，由 LLM 或深度啟發式引擎審查真實主旨，並針對貼文亮點生成專屬真誠推薦詞，在留言區 `@主人`。
+3. **每日探索日報 (Daily Markdown Report)**：
+   - 自動將今日瀏覽之所有精選貼文、摘要與推薦紀錄整理為 Markdown 日報。
+   - 儲存於 `data/reports/YYYY-MM-DD.md`，可隨時在 Web 面板查看與回溯。
+4. **狀態帳本與嚴格去重控制**：
+   - `data/scroll_ledger.json` 記錄已看貼文 PK 與今日推坑次數，避免重複推坑或重複閱讀，並防止觸發風控。
+5. **DSH Web 瀏覽器端介面 (`client.js`)**：
+   - 提供直觀動態牆瀑布流預覽、即時手動觸發刷動態按鈕、日報閱讀器與自訂設定面板。
+
+---
+
+## 📦 安裝方式
+
+使用 DSH CLI 安裝插件：
+
+```bash
+dsh plugin --profile web add @luoyi-dsh/instagram-scroll
+```
+
+或透過 npm 安裝：
+
+```bash
+npm install @luoyi-dsh/instagram-scroll
+```
+
+---
+
+## 🛠️ 提供之 DSH Tools
+
+| 工具名稱 | 說明 | 參數 |
+| :--- | :--- | :--- |
+| **`ig_run_scroll_duty_now`** | 立即手動替主人刷一輪 Instagram 動態與探索，讀取貼文進行評估、點讚與留言推坑 | 無 |
+| **`ig_scroll_feed`** | 滾動讀取 Instagram 時間軸最新動態貼文（含作者、讚數、內文摘要） | `limit` (number，預設 15，最大 50) |
+| **`ig_explore_topics`** | 依照指定主題或探索標籤滾動閱讀熱門貼文 | `tag` (string，必填), `limit` (number，預設 15) |
+| **`ig_like_feed_post`** | 在滾動瀏覽過程中對感興趣的 Instagram 貼文按讚 | `media_pk` (string，必填) |
+
+---
+
+## 💻 使用範例
+
+### 1. DSH AI 自然語言直接調用
+
+在 DSH 對話中，主模型可直接以自然語言執行滾動探索或瀏覽：
+
+```text
+💬 範例 1：執行一輪完整的動態探索與推坑
+「請立刻替我刷一輪 Instagram 動態牆，看看有沒有適合我的技術新貼文並推薦給我」
+-> AI 將調用：ig_run_scroll_duty_now()
+
+💬 範例 2：滾動瀏覽首頁動態貼文
+「幫我刷最新 10 則 Instagram 動態」
+-> AI 將調用：ig_scroll_feed(limit=10)
+
+💬 範例 3：探索特定主題標籤
+「探索 Instagram 上 #deepseek 標籤的熱門貼文」
+-> AI 將調用：ig_explore_topics(tag="deepseek", limit=15)
+```
+
+---
+
+### 2. 透過 HTTP REST API 調用 (DSH Web 路由)
+
+> 💡 **提示**：DSH Web 預設埠號為 **3080**。
+
+#### 1. 手動觸發滾動一輪 (`POST /api/instagram/scroll/run`)
+```bash
+curl -X POST http://127.0.0.1:3080/api/instagram/scroll/run
+```
+
+#### 2. 獲取當前滾動狀態與今日統計 (`GET /api/instagram/scroll/status`)
+```bash
+curl http://127.0.0.1:3080/api/instagram/scroll/status
+```
+
+#### 3. 讀取今日探索日報內容 (`GET /api/instagram/scroll/report`)
+```bash
+curl http://127.0.0.1:3080/api/instagram/scroll/report
+```
+
+#### 4. 讀取與更新設定 (`GET / POST /api/instagram/scroll/config`)
+```bash
+# 取得設定
+curl http://127.0.0.1:3080/api/instagram/scroll/config
+
+# 更新設定
+curl -X POST http://127.0.0.1:3080/api/instagram/scroll/config \
+  -H "Content-Type: application/json" \
+  -d '{"masterUsername":"your_username","minScore":80}'
+```
+
+---
+
+## ⚙️ 設定參數說明 (Settings)
+
+> 💡 **提示**：本外掛**不用輸入帳號密碼**，會直接沿用依賴的 `@luoyi-dsh/instagram-mcp` 獲取之 Session 與登入狀態。
+
+| 欄位名稱 | 型別 | 預設值 | 說明 |
+| :--- | :--- | :--- | :--- |
+| **`masterUsername`** | string | `""` | 主人的 Instagram 使用者名稱（達標時在留言區 @主人 推薦） |
+| **`userInterests`** | string | *預設偏好詳述* | 主人喜歡的內容風格與領域詳細描述（供 AI 深度比對正文語義） |
+| **`positiveKeywords`** | array | `["ai", "deepseek", ...]` | 正文必須提及或重點加分的領域關鍵字清單 |
+| **`negativeKeywords`** | array | `["互粉", "代購", "抽獎", ...]` | 負向排除關鍵字（命中時直接判定不推薦，杜絕廣告與廢文） |
+| **`minCaptionLength`** | number | `30` | 正文有效文字最小字數門檻（扣除 #標籤 後過短者直接過濾） |
+| **`requireBodyMatch`** | boolean| `true` | 正文實質內容必須命中主人偏好主題（拒絕僅在文末蹭 tag） |
+| **`strictContentCheck`**| boolean| `true` | 啟用 @ 前深度正文審查機制（結合 LLM / 正文語義深度質檢） |
+| **`interestTags`** | array | `["ai", "deepseek", "coding", "tech", "gadgets"]` | 探索抓取的主題標籤（僅作為探索起點，非推薦唯一標準） |
+| **`personaPrompt`** | string | *預設人設提示詞* | 評估貼文趣味度與撰寫 @主人 推薦語的人設 Prompt |
+| **`minScore`** | number | `80` | 推坑門檻分數（0-100，達標才在貼文下留言推薦，提高門檻避免隨便推薦） |
+| **`dailyRecommendCap`** | number | `5` | 每日向主人推坑留言的上限則數（防止過度打擾與風控） |
+| **`maxRecommendsPerRun`**| number | `1` | 單次滾動瀏覽最多推坑留言則數（避免短時間連發觸發官方風控） |
+| **`minPostReadDelaySeconds`** | number | `3` | 每讀取一則貼文前人造擬真閱讀微延遲最小秒數 |
+| **`maxPostReadDelaySeconds`** | number | `7` | 每讀取一則貼文前人造擬真閱讀微延遲最大秒數 |
+| **`cooldownOnBlockMinutes`** | number | `30` | 遇到 Action Block / 頻率限制時自動熔斷暫停分鐘數 |
+| **`scrollIntervalMinutes`**| number | `60` | 自動巡查刷動態牆的時間週期（分鐘） |
+| **`autoScrollEnabled`** | boolean| `true` | 是否啟用背景定時自動刷動態牆任務 |
+| **`likeOnRecommend`** | boolean| `true` | 決定推薦給主人時是否順便對該貼文點讚 |
+| **`batchSize`** | number | `15` | 每輪滾動瀏覽抓取的貼文筆數 (10-30) |
+
+---
+
+## 📁 目錄結構
+
+```text
+dsh-instagram-scroll/
+├── cordis.patch.yml               # DSH bundle patch 宣告
+├── package.json                   # 模組定義與依賴
+├── tsconfig.json                  # TypeScript 編譯設定
+├── CHANGELOG.md                   # 版本更新紀錄
+├── README.md                      # 英文說明文件
+├── README.zh-Hant.md              # 繁體中文說明文件
+├── assets/
+│   ├── banner.png                 # 宣傳橫幅
+│   └── zh-Hant.md                 # 本地化說明文件
+├── client.js                      # DSH Web 前端面板 (動態瀏覽、手動觸發、日報查看)
+├── data/
+│   ├── config.json                # 本地設定檔
+│   ├── scroll_ledger.json         # 瀏覽去重與統計帳本
+│   └── reports/                   # 每日日報儲存目錄 (YYYY-MM-DD.md)
+└── src/
+    ├── index.ts                   # Cordis 外掛入口、排程定時器與 Web API
+    ├── config.ts                  # Schemastery 設定模型
+    ├── types.d.ts                 # 型別宣告
+    ├── core/
+    │   └── scrollDuty.ts          # 滾動瀏覽、大模型評估、點讚與推坑核心邏輯
+    ├── lib/
+    │   ├── hostdeps.ts            # DSH 宿主相容層
+    │   └── ledger.ts              # 日報生成與歷史去重帳本管理器
+    └── tools/
+        └── scrollTools.ts         # 向 DSH Tools 註冊之專用滾動瀏覽工具
+```
+
+---
+
+## 📜 版本發布紀錄 (Releases)
+
+詳細版本演進與更新紀錄，請參閱 [CHANGELOG.md](CHANGELOG.md)。
+
+---
+
+## 📄 授權條款
+
+本專案採用 [MIT License](LICENSE) 開源授權。