@luoyi-dsh/instagram-scroll 1.0.1 → 1.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (20) hide show
  1. package/AGENTS.md +92 -0
  2. package/README.md +77 -172
  3. package/README.zh-Hant.md +73 -174
  4. package/client.js +261 -33
  5. package/dist/config.d.ts +13 -0
  6. package/dist/config.d.ts.map +1 -1
  7. package/dist/config.js +156 -9
  8. package/dist/config.js.map +1 -1
  9. package/dist/core/scrollDuty.d.ts +30 -1
  10. package/dist/core/scrollDuty.d.ts.map +1 -1
  11. package/dist/core/scrollDuty.js +563 -74
  12. package/dist/core/scrollDuty.js.map +1 -1
  13. package/dist/index.d.ts.map +1 -1
  14. package/dist/index.js +21 -2
  15. package/dist/index.js.map +1 -1
  16. package/dist/lib/ledger.d.ts +73 -10
  17. package/dist/lib/ledger.d.ts.map +1 -1
  18. package/dist/lib/ledger.js +402 -22
  19. package/dist/lib/ledger.js.map +1 -1
  20. package/package.json +4 -3
package/AGENTS.md ADDED
@@ -0,0 +1,92 @@
1
+ # AGENTS.md — `@luoyi-dsh/instagram-scroll` 操作指南與工具調用規範
2
+
3
+ 本文件為 AI Agent、DeepSeek Harness (DSH) 主模型與開發者提供 `@luoyi-dsh/instagram-scroll` 的完整操作方法、DSH 工具清單、REST API 路由、AIGC 過濾規則與設定參數說明。
4
+
5
+ ---
6
+
7
+ ## 🧠 1. 核心運作規範
8
+
9
+ 1. **自動沿用 MCP 帳號設定**：
10
+ - 機器人登入會話 (`username`) 與推坑目標主人帳號 (`masterUsername`) 直接從 `@luoyi-dsh/instagram-mcp` 自動讀取與同步，無須在本插件額外輸入。
11
+ 2. **嚴格排除 AI 生成內容 (AIGC Filter)**：
12
+ - 滾動探索與主題搜尋時，自動過濾 AI 生成的影片、AI 動畫、AI 繪圖或 AI 生成農場文章（包含 `#aiart`, `#aivideo`, `#aianimation`, `#sora`, `#midjourney`, `#runwayml`, `#klingai`, `AI生成`, `AI影片`, `AI動畫` 等）。
13
+ 3. **共享外部插件 LLM 訂閱額度**：
14
+ - 深度語義審核優先調用 `@luoyi-dsh/instagram-plugin` 掛載之統一推理引擎 (`__DSH_INSTAGRAM_LLM__`) 與 DSH 宿主 `ctx.llm`，支援 `dsh-plugin-subscriptions` 外部訂閱額度。
15
+ 4. **【第一條件】去 AI 味與兼容 `dsh-feiyu-mood` 心情指標**：
16
+ - 自動共享 `ANTI_AI_FLAVOR_PRIMARY_RULE` 與 `dsh-feiyu-mood` 心情指標 (`~/.dsh/feiyu-mood/state.json`)，確保生成的 `@主人` 推坑留言自然口語、毫無 AI 客服腔與罐頭感。
17
+
18
+ ---
19
+
20
+ ## 🛠️ 2. 提供之 DSH Tools 清單
21
+
22
+ | 工具名稱 | 說明 | 參數 |
23
+ | :--- | :--- | :--- |
24
+ | **`ig_run_scroll_duty_now`** | 立即手動替主人刷一輪 Instagram 動態與模糊搜尋主題，進行正文審查、過濾 AIGC、點讚與留言 `@主人` 推坑 | 無 |
25
+ | **`ig_scroll_feed`** | 滾動讀取 Instagram 時間軸最新動態貼文（含作者、讚數、內文摘要，已過濾 AIGC） | `limit` (number，預設 15，最大 50) |
26
+ | **`ig_explore_topics`** | 依照指定主題關鍵字進行模糊搜尋 (`igFuzzySearchPosts`) 與標籤探索熱門貼文（已過濾 AIGC） | `tag` (string，必填), `limit` (number，預設 15) |
27
+ | **`ig_like_feed_post`** | 在滾動瀏覽過程中對感興趣的 Instagram 貼文按讚 | `media_pk` (string，必填) |
28
+
29
+ ---
30
+
31
+ ## 💻 3. 工具與 API 調用方式
32
+
33
+ ### 1. DSH AI 自然語言直接調用
34
+
35
+ ```text
36
+ 💬 範例 1：執行一輪完整的動態探索與推坑
37
+ 「請立刻替我刷一輪 Instagram 動態牆，看看有沒有適合我的技術新貼文並推薦給我」
38
+ -> 調用：ig_run_scroll_duty_now()
39
+
40
+ 💬 範例 2：滾動瀏覽首頁動態貼文
41
+ 「幫我刷最新 10 則 Instagram 動態」
42
+ -> 調用：ig_scroll_feed(limit=10)
43
+
44
+ 💬 範例 3：探索特定主題關鍵字
45
+ 「探索 Instagram 上關於 deepseek 的熱門貼文」
46
+ -> 調用：ig_explore_topics(tag="deepseek", limit=15)
47
+ ```
48
+
49
+ ### 2. 透過 HTTP REST API 調用 (DSH Web 路由，預設埠 3080)
50
+
51
+ ```bash
52
+ # 1. 手動觸發滾動一輪 (POST /api/instagram/scroll/run)
53
+ curl -X POST http://127.0.0.1:3080/api/instagram/scroll/run
54
+
55
+ # 2. 獲取當前滾動狀態與今日統計 (GET /api/instagram/scroll/status)
56
+ curl http://127.0.0.1:3080/api/instagram/scroll/status
57
+
58
+ # 3. 讀取今日 Markdown 探索日報內容 (GET /api/instagram/scroll/report)
59
+ curl http://127.0.0.1:3080/api/instagram/scroll/report
60
+
61
+ # 4. 讀取與更新設定 (GET / POST /api/instagram/scroll/config)
62
+ curl http://127.0.0.1:3080/api/instagram/scroll/config
63
+
64
+ curl -X POST http://127.0.0.1:3080/api/instagram/scroll/config \
65
+ -H "Content-Type: application/json" \
66
+ -d '{"minScore":80,"dailyRecommendCap":5}'
67
+ ```
68
+
69
+ ---
70
+
71
+ ## ⚙️ 4. 設定參數說明 (`data/config.json`)
72
+
73
+ | 欄位名稱 | 型別 | 預設值 | 說明 |
74
+ | :--- | :--- | :--- | :--- |
75
+ | **`userInterests`** | string | *預設偏好詳述* | 主人喜歡的內容風格與領域詳細描述（供 AI 深度比對正文語義） |
76
+ | **`positiveKeywords`** | array | `["ai", "deepseek", ...]` | 正文必須提及或重點加分的領域關鍵字清單 |
77
+ | **`negativeKeywords`** | array | `["互粉", "代購", "ai生成", ...]` | 負向排除關鍵字（含 AIGC 關鍵詞，命中時直接過濾） |
78
+ | **`minCaptionLength`** | number | `30` | 正文有效文字最小字數門檻（扣除 `#標籤` 後過短者直接過濾） |
79
+ | **`requireBodyMatch`** | boolean| `true` | 正文實質內容必須命中主人偏好主題（拒絕僅在文末蹭 tag） |
80
+ | **`strictContentCheck`**| boolean| `true` | 啟用 `@` 前深度正文審查機制 |
81
+ | **`interestTags`** | array | `["ai", "deepseek", "coding", "tech", "gadgets"]` | 模糊搜尋與探索抓取的主題關鍵字清單 |
82
+ | **`personaPrompt`** | string | *預設人設提示詞* | 評估貼文趣味度與撰寫 `@主人` 推薦語的人設 Prompt |
83
+ | **`minScore`** | number | `80` | 推坑門檻分數（0-100，達標才在貼文下留言推薦） |
84
+ | **`dailyRecommendCap`** | number | `5` | 每日向主人推坑留言的上限則數 |
85
+ | **`maxRecommendsPerRun`**| number | `1` | 單次滾動瀏覽最多推坑留言則數 |
86
+ | **`minPostReadDelaySeconds`** | number | `3` | 每讀取一則貼文前人造擬真閱讀微延遲最小秒數 |
87
+ | **`maxPostReadDelaySeconds`** | number | `7` | 每讀取一則貼文前人造擬真閱讀微延遲最大秒數 |
88
+ | **`cooldownOnBlockMinutes`** | number | `30` | 遇到 Action Block / 頻率限制時自動熔斷暫停分鐘數 |
89
+ | **`scrollIntervalMinutes`**| number | `60` | 自動巡查刷動態牆的時間週期（分鐘） |
90
+ | **`autoScrollEnabled`** | boolean| `true` | 是否啟用背景定時自動刷動態牆任務 |
91
+ | **`likeOnRecommend`** | boolean| `true` | 決定推薦給主人時是否順便對該貼文點讚 |
92
+ | **`batchSize`** | number | `15` | 每輪滾動瀏覽抓取的貼文筆數 (10-30) |
package/README.md CHANGED
@@ -1,172 +1,77 @@
1
- # DSH Instagram Scroll Feed & Exploration Plugin (`@luoyi-dsh/instagram-scroll`)
2
-
3
- <div align="center">
4
-
5
- ![DSH Instagram Scroll Banner](assets/banner.png)
6
-
7
- **[English](README.md) | [繁體中文](README.zh-Hant.md)**
8
-
9
- </div>
10
-
11
- > Dedicated Instagram feed exploration, AI recommendation, and daily digest plugin for **DeepSeek Harness (DSH)**.
12
- > 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**.
13
-
14
- ---
15
-
16
- ## 🌟 Key Features
17
-
18
- 1. **Automated Feed Browsing (Scroll Duty)**:
19
- - Periodically polls timeline feeds and configured topic hashtags.
20
- - Extracts post caption, author, tags, and media metadata.
21
- 2. **LLM Evaluation & Smart Recommendation**:
22
- - Analyzes post relevance and scores content (0-100) based on master's interest prompt.
23
- - Automatically likes posts and writes authentic recommendation comments mentioning master (`@masterUsername`) when score meets criteria (default > 75).
24
- 3. **Daily Markdown Digest (`data/reports/YYYY-MM-DD.md`)**:
25
- - Automatically organizes reviewed posts, summaries, and recommendation trails into clean Markdown daily digests.
26
- - Viewable directly in the web console.
27
- 4. **State Ledger & Deduplication**:
28
- - `data/scroll_ledger.json` keeps track of inspected media PKs and daily quotas to prevent repetitive actions and avoid rate limits.
29
- 5. **DSH Web Control Panel (`client.js`)**:
30
- - Provides an intuitive feed waterfall preview, manual duty execution button, daily report reader, and settings inspector.
31
-
32
- ---
33
-
34
- ## 📦 Installation
35
-
36
- Install via DSH Plugin CLI:
37
-
38
- ```bash
39
- dsh plugin --profile web add @luoyi-dsh/instagram-scroll
40
- ```
41
-
42
- Or via standard npm:
43
-
44
- ```bash
45
- npm install @luoyi-dsh/instagram-scroll
46
- ```
47
-
48
- ---
49
-
50
- ## 🛠️ Provided DSH Tools
51
-
52
- | Tool Name | Description | Parameters |
53
- | :--- | :--- | :--- |
54
- | **`ig_run_scroll_duty_now`** | Trigger an immediate exploration duty cycle (evaluate posts, like & recommend) | None |
55
- | **`ig_scroll_feed`** | Read timeline feed posts (author, like count, caption excerpt) | `limit` (number, default 15, max 50) |
56
- | **`ig_explore_topics`** | Explore popular posts under a specific topic or hashtag | `tag` (string, required), `limit` (number, default 15) |
57
- | **`ig_like_feed_post`** | Like an Instagram post during browsing | `media_pk` (string, required) |
58
-
59
- ---
60
-
61
- ## 💻 Usage Examples
62
-
63
- ### 1. Natural Language Invocation in DSH Chat
64
-
65
- ```text
66
- 💬 Example 1: Run full exploration and recommendation duty
67
- "Please check my Instagram feed right now and recommend any interesting technical posts."
68
- -> AI calls: ig_run_scroll_duty_now()
69
-
70
- 💬 Example 2: Read timeline posts
71
- "Browse the latest 10 posts on my Instagram feed."
72
- -> AI calls: ig_scroll_feed(limit=10)
73
-
74
- 💬 Example 3: Explore a hashtag
75
- "Explore top posts under #deepseek on Instagram."
76
- -> AI calls: ig_explore_topics(tag="deepseek", limit=15)
77
- ```
78
-
79
- ---
80
-
81
- ### 2. Via HTTP REST API (DSH Web Routes)
82
-
83
- > 💡 **Tip**: Default DSH Web port is **3080**.
84
-
85
- #### 1. Manually Trigger Duty Cycle (`POST /api/instagram/scroll/run`)
86
- ```bash
87
- curl -X POST http://127.0.0.1:3080/api/instagram/scroll/run
88
- ```
89
-
90
- #### 2. Get Current Status & Daily Stats (`GET /api/instagram/scroll/status`)
91
- ```bash
92
- curl http://127.0.0.1:3080/api/instagram/scroll/status
93
- ```
94
-
95
- #### 3. Read Today's Markdown Digest (`GET /api/instagram/scroll/report`)
96
- ```bash
97
- curl http://127.0.0.1:3080/api/instagram/scroll/report
98
- ```
99
-
100
- #### 4. Read & Update Configuration (`GET / POST /api/instagram/scroll/config`)
101
- ```bash
102
- # Read config
103
- curl http://127.0.0.1:3080/api/instagram/scroll/config
104
-
105
- # Update config
106
- curl -X POST http://127.0.0.1:3080/api/instagram/scroll/config \
107
- -H "Content-Type: application/json" \
108
- -d '{"masterUsername":"your_username","minScore":80}'
109
- ```
110
-
111
- ---
112
-
113
- ## ⚙️ Configuration Parameters (Settings)
114
-
115
- > 💡 **Tip**: No need to configure Instagram credentials here; it automatically inherits session state from `@luoyi-dsh/instagram-mcp`.
116
-
117
- | Field | Type | Default | Description |
118
- | :--- | :--- | :--- | :--- |
119
- | **`masterUsername`** | string | `""` | Master's Instagram username (mentioned in comments when recommended) |
120
- | **`interestTags`** | array | `["ai", "deepseek", "coding", "tech"]` | Topic hashtags and keywords matching the owner's interest |
121
- | **`personaPrompt`** | string | *Default persona prompt* | Persona prompt guiding post analysis and recommendation copywriting |
122
- | **`minScore`** | number | `75` | Recommendation score threshold (0-100) |
123
- | **`dailyRecommendCap`** | number | `5` | Maximum recommendation comments allowed per day |
124
- | **`scrollIntervalMinutes`**| number | `60` | Background exploration duty interval in minutes |
125
- | **`autoScrollEnabled`** | boolean| `true` | Whether background automated exploration duty is enabled |
126
- | **`likeOnRecommend`** | boolean| `true` | Automatically like post upon recommending to master |
127
- | **`batchSize`** | number | `15` | Number of posts inspected per scroll duty round (10-30) |
128
-
129
- ---
130
-
131
- ## 📁 Directory Structure
132
-
133
- ```text
134
- dsh-instagram-scroll/
135
- ├── cordis.patch.yml # DSH bundle patch manifest
136
- ├── package.json # Module definitions and dependencies
137
- ├── tsconfig.json # TypeScript compiler configuration
138
- ├── CHANGELOG.md # Version release notes
139
- ├── README.md # English documentation (This file)
140
- ├── README.zh-Hant.md # Traditional Chinese documentation
141
- ├── assets/
142
- │ ├── banner.png # Promotional banner
143
- │ └── zh-Hant.md # Localized documentation
144
- ├── client.js # DSH Web UI panel
145
- ├── data/ # [Runtime generated, ignored in Git]
146
- │ ├── config.json # Local configuration
147
- │ ├── scroll_ledger.json # Deduplication and quota ledger
148
- │ └── reports/ # Daily reports folder (YYYY-MM-DD.md)
149
- └── src/
150
- ├── index.ts # Cordis plugin entrypoint and Web API
151
- ├── config.ts # Schemastery config schema
152
- ├── types.d.ts # Type definitions
153
- ├── core/
154
- │ └── scrollDuty.ts # Scroll duty execution, LLM evaluation, likes & comments
155
- ├── lib/
156
- │ ├── hostdeps.ts # DSH runtime compatibility layer
157
- │ └── ledger.ts # Daily digest and history ledger manager
158
- └── tools/
159
- └── scrollTools.ts # Dedicated DSH tools registration
160
- ```
161
-
162
- ---
163
-
164
- ## 📜 Releases & Changelog
165
-
166
- For detailed release history and changes, please refer to [CHANGELOG.md](CHANGELOG.md).
167
-
168
- ---
169
-
170
- ## 📄 License
171
-
172
- This project is licensed under the [MIT License](LICENSE).
1
+ # DSH Instagram Scroll Feed & Exploration Plugin (`@luoyi-dsh/instagram-scroll`)
2
+
3
+ <div align="center">
4
+
5
+ ![DSH Instagram Scroll Banner](assets/banner.png)
6
+
7
+ **[English](README.md) | [繁體中文](README.zh-Hant.md) | [Agent & Operational Guide](AGENTS.md)**
8
+
9
+ </div>
10
+
11
+ > Dedicated Instagram feed exploration, AI content review, and daily digest plugin for **DeepSeek Harness (DSH)**.
12
+ > Automatically inherits Bot and Master accounts from `@luoyi-dsh/instagram-mcp`, browses Instagram timeline feeds and fuzzy-searched topics, strictly filters out AI-generated videos/animations/articles (AIGC), evaluates post substance against the owner's interests via LLM, leaves authentic `@master` recommendation comments, and compiles daily Markdown reports.
13
+
14
+ > [!CAUTION]
15
+ > ### ⚠️ CRITICAL WARNING & DISCLAIMER
16
+ > 1. **Violation of Instagram Terms of Service & Community Guidelines**:
17
+ > This plugin operates via unofficial APIs, which **expressly violates Instagram / Meta's Terms of Use and Community Guidelines**.
18
+ > 2. **DO NOT USE YOUR PERSONAL / PRIMARY ACCOUNT**:
19
+ > **Never run this plugin using your personal, primary, or business Instagram account!** Use disposable test accounts paired with clean residential proxies.
20
+ > 3. **Disclaimer**:
21
+ > This project is provided strictly for educational and technical research purposes. Use entirely at your own risk!
22
+
23
+ ---
24
+
25
+ ## 🌟 Key Features
26
+
27
+ 1. **Zero-Config Account Inheritance**:
28
+ - Automatically inherits both the Bot session (`username`) and Master account (`masterUsername`) from `@luoyi-dsh/instagram-mcp`.
29
+ 2. **Automated Feed & Fuzzy Topic Exploration (Scroll Duty)**:
30
+ - Periodically polls timeline feeds and fuzzy-searches configured topics (`igFuzzySearchPosts` + hashtag fallback).
31
+ 3. **Strict Anti-AIGC & Deep Content Inspection**:
32
+ - Automatically rejects AI-generated videos, animations, images, and content-farm articles, as well as hashtag spam, giveaways, and superficial posts.
33
+ - Evaluates genuine body text via LLM (supporting external `dsh-plugin-subscriptions` quota) before recommending to the master.
34
+ 4. **Daily Markdown Digest (`data/reports/YYYY-MM-DD.md`)**:
35
+ - Organizes reviewed posts, summaries, and recommendation trails into daily Markdown reports viewable in the Web UI.
36
+
37
+ ---
38
+
39
+ ## 📦 Installation
40
+
41
+ ```bash
42
+ # Via DSH Plugin CLI
43
+ dsh plugin --profile web add @luoyi-dsh/instagram-scroll
44
+
45
+ # Or via npm
46
+ npm install @luoyi-dsh/instagram-scroll
47
+ ```
48
+
49
+ ---
50
+
51
+ ## 📖 Operational Guide & Tool Reference
52
+
53
+ For complete DSH tool definitions, natural language prompts, HTTP REST API routes, and configuration parameters, please refer to **[AGENTS.md](AGENTS.md)**.
54
+
55
+ ---
56
+
57
+ ## 📁 Directory Structure
58
+
59
+ ```text
60
+ dsh-instagram-scroll/
61
+ ├── cordis.patch.yml # DSH bundle patch manifest
62
+ ├── package.json # Module definitions and dependencies
63
+ ├── tsconfig.json # TypeScript compiler configuration
64
+ ├── AGENTS.md # Operational & Agent Tool Guide
65
+ ├── CHANGELOG.md # Version release notes
66
+ ├── README.md # English overview (This file)
67
+ ├── README.zh-Hant.md # Traditional Chinese overview
68
+ ├── client.js # DSH Web UI panel
69
+ └── src/ # Core scroll duty, ledger/report manager, and DSH tools
70
+ ```
71
+
72
+ ---
73
+
74
+ ## 📜 Releases & License
75
+
76
+ - See [CHANGELOG.md](CHANGELOG.md) for release history.
77
+ - Licensed under the [MIT License](LICENSE).
package/README.zh-Hant.md CHANGED
@@ -1,174 +1,73 @@
1
- # DSH Instagram 滾動瀏覽與探索插件 (`@luoyi-dsh/instagram-scroll`)
2
-
3
- <div align="center">
4
-
5
- ![DSH Instagram Scroll Banner](assets/banner.png)
6
-
7
- **[English](README.md) | [繁體中文](README.zh-Hant.md)**
8
-
9
- </div>
10
-
11
- > **DeepSeek Harness (DSH)** 專屬的 Instagram 動態探索、智慧推坑與日報生成外掛。
12
- > 具備核心能力：**定時或手動替主人刷一輪 Instagram 首頁動態與主題標籤、逐條閱讀內文評估主人興趣、自動點讚與留言推坑，並自動彙整生成每日 Markdown 探索日報**。
13
-
14
- ---
15
-
16
- ## 🌟 核心特性
17
-
18
- 1. **自動動態探索巡查 (Scroll Duty)**：
19
- - 定期輪詢首頁動態牆 (Timeline Feed) 與指定主題標籤 (Hashtags)。
20
- - 逐則貼文抓取標題、作者、標籤與完整內文。
21
- 2. **LLM 價值評估與推坑 (AI Recommendation)**：
22
- - 由大語言模型依據主人的興趣 Prompt 深度分析貼文內容與價值評分。
23
- - 若達標（預設 > 75 分），自動在貼文下點讚並留言 `@目標用戶` 附上真誠自然的推薦語。
24
- 3. **每日探索日報 (Daily Markdown Report)**：
25
- - 自動將今日瀏覽之所有精選貼文、摘要與推薦紀錄整理為 Markdown 日報。
26
- - 儲存於 `data/reports/YYYY-MM-DD.md`，可隨時在 Web 面板查看與回溯。
27
- 4. **狀態帳本與嚴格去重控制**：
28
- - `data/scroll_ledger.json` 記錄已看貼文 PK 與今日推坑次數，避免重複推坑或重複閱讀，並防止觸發風控。
29
- 5. **DSH Web 瀏覽器端介面 (`client.js`)**：
30
- - 提供直觀動態牆瀑布流預覽、即時手動觸發刷動態按鈕、日報閱讀器與自訂設定面板。
31
-
32
- ---
33
-
34
- ## 📦 安裝方式
35
-
36
- 使用 DSH CLI 安裝插件：
37
-
38
- ```bash
39
- dsh plugin --profile web add @luoyi-dsh/instagram-scroll
40
- ```
41
-
42
- 或透過 npm 安裝：
43
-
44
- ```bash
45
- npm install @luoyi-dsh/instagram-scroll
46
- ```
47
-
48
- ---
49
-
50
- ## 🛠️ 提供之 DSH Tools
51
-
52
- | 工具名稱 | 說明 | 參數 |
53
- | :--- | :--- | :--- |
54
- | **`ig_run_scroll_duty_now`** | 立即手動替主人刷一輪 Instagram 動態與探索，讀取貼文進行評估、點讚與留言推坑 | 無 |
55
- | **`ig_scroll_feed`** | 滾動讀取 Instagram 時間軸最新動態貼文（含作者、讚數、內文摘要） | `limit` (number，預設 15，最大 50) |
56
- | **`ig_explore_topics`** | 依照指定主題或探索標籤滾動閱讀熱門貼文 | `tag` (string，必填), `limit` (number，預設 15) |
57
- | **`ig_like_feed_post`** | 在滾動瀏覽過程中對感興趣的 Instagram 貼文按讚 | `media_pk` (string，必填) |
58
-
59
- ---
60
-
61
- ## 💻 使用範例
62
-
63
- ### 1. DSH AI 自然語言直接調用
64
-
65
- 在 DSH 對話中，主模型可直接以自然語言執行滾動探索或瀏覽：
66
-
67
- ```text
68
- 💬 範例 1：執行一輪完整的動態探索與推坑
69
- 「請立刻替我刷一輪 Instagram 動態牆，看看有沒有適合我的技術新貼文並推薦給我」
70
- -> AI 將調用：ig_run_scroll_duty_now()
71
-
72
- 💬 範例 2：滾動瀏覽首頁動態貼文
73
- 「幫我刷最新 10 則 Instagram 動態」
74
- -> AI 將調用：ig_scroll_feed(limit=10)
75
-
76
- 💬 範例 3：探索特定主題標籤
77
- 「探索 Instagram 上 #deepseek 標籤的熱門貼文」
78
- -> AI 將調用：ig_explore_topics(tag="deepseek", limit=15)
79
- ```
80
-
81
- ---
82
-
83
- ### 2. 透過 HTTP REST API 調用 (DSH Web 路由)
84
-
85
- > 💡 **提示**：DSH Web 預設埠號為 **3080**。
86
-
87
- #### 1. 手動觸發滾動一輪 (`POST /api/instagram/scroll/run`)
88
- ```bash
89
- curl -X POST http://127.0.0.1:3080/api/instagram/scroll/run
90
- ```
91
-
92
- #### 2. 獲取當前滾動狀態與今日統計 (`GET /api/instagram/scroll/status`)
93
- ```bash
94
- curl http://127.0.0.1:3080/api/instagram/scroll/status
95
- ```
96
-
97
- #### 3. 讀取今日探索日報內容 (`GET /api/instagram/scroll/report`)
98
- ```bash
99
- curl http://127.0.0.1:3080/api/instagram/scroll/report
100
- ```
101
-
102
- #### 4. 讀取與更新設定 (`GET / POST /api/instagram/scroll/config`)
103
- ```bash
104
- # 取得設定
105
- curl http://127.0.0.1:3080/api/instagram/scroll/config
106
-
107
- # 更新設定
108
- curl -X POST http://127.0.0.1:3080/api/instagram/scroll/config \
109
- -H "Content-Type: application/json" \
110
- -d '{"masterUsername":"your_username","minScore":80}'
111
- ```
112
-
113
- ---
114
-
115
- ## ⚙️ 設定參數說明 (Settings)
116
-
117
- > 💡 **提示**：本外掛**不用輸入帳號密碼**，會直接沿用依賴的 `@luoyi-dsh/instagram-mcp` 獲取之 Session 與登入狀態。
118
-
119
- | 欄位名稱 | 型別 | 預設值 | 說明 |
120
- | :--- | :--- | :--- | :--- |
121
- | **`masterUsername`** | string | `""` | 主人的 Instagram 使用者名稱（達標時在留言區 @主人 推薦） |
122
- | **`interestTags`** | array | `["ai", "deepseek", "coding", "tech"]` | 主人感興趣的主題標籤或領域關鍵字清單 |
123
- | **`personaPrompt`** | string | *預設人設提示詞* | 評估貼文趣味度與撰寫 @主人 推薦語的人設 Prompt |
124
- | **`minScore`** | number | `75` | 推坑門檻分數（0-100，達標才在貼文下留言推薦） |
125
- | **`dailyRecommendCap`** | number | `5` | 每日向主人推坑留言的上限則數（防止過度打擾與風控） |
126
- | **`scrollIntervalMinutes`**| number | `60` | 自動巡查刷動態牆的時間週期（分鐘） |
127
- | **`autoScrollEnabled`** | boolean| `true` | 是否啟用背景定時自動刷動態牆任務 |
128
- | **`likeOnRecommend`** | boolean| `true` | 決定推薦給主人時是否順便對該貼文點讚 |
129
- | **`batchSize`** | number | `15` | 每輪滾動瀏覽抓取的貼文筆數 (10-30) |
130
-
131
- ---
132
-
133
- ## 📁 目錄結構
134
-
135
- ```text
136
- dsh-instagram-scroll/
137
- ├── cordis.patch.yml # DSH bundle patch 宣告
138
- ├── package.json # 模組定義與依賴
139
- ├── tsconfig.json # TypeScript 編譯設定
140
- ├── CHANGELOG.md # 版本更新紀錄
141
- ├── README.md # 英文說明文件
142
- ├── README.zh-Hant.md # 繁體中文說明文件
143
- ├── assets/
144
- │ ├── banner.png # 宣傳橫幅
145
- │ └── zh-Hant.md # 本地化說明文件
146
- ├── client.js # DSH Web 前端面板 (動態瀏覽、手動觸發、日報查看)
147
- ├── data/
148
- │ ├── config.json # 本地設定檔
149
- │ ├── scroll_ledger.json # 瀏覽去重與統計帳本
150
- │ └── reports/ # 每日日報儲存目錄 (YYYY-MM-DD.md)
151
- └── src/
152
- ├── index.ts # Cordis 外掛入口、排程定時器與 Web API
153
- ├── config.ts # Schemastery 設定模型
154
- ├── types.d.ts # 型別宣告
155
- ├── core/
156
- │ └── scrollDuty.ts # 滾動瀏覽、大模型評估、點讚與推坑核心邏輯
157
- ├── lib/
158
- │ ├── hostdeps.ts # DSH 宿主相容層
159
- │ └── ledger.ts # 日報生成與歷史去重帳本管理器
160
- └── tools/
161
- └── scrollTools.ts # 向 DSH Tools 註冊之專用滾動瀏覽工具
162
- ```
163
-
164
- ---
165
-
166
- ## 📜 版本發布紀錄 (Releases)
167
-
168
- 詳細版本演進與更新紀錄，請參閱 [CHANGELOG.md](CHANGELOG.md)。
169
-
170
- ---
171
-
172
- ## 📄 授權條款
173
-
174
- 本專案採用 [MIT License](LICENSE) 開源授權。
1
+ # DSH Instagram 滾動瀏覽與探索插件 (`@luoyi-dsh/instagram-scroll`)
2
+
3
+ <div align="center">
4
+
5
+ ![DSH Instagram Scroll Banner](assets/banner.png)
6
+
7
+ **[English](README.md) | [繁體中文](README.zh-Hant.md) | [操作方法與 Agent 指南](AGENTS.md)**
8
+
9
+ </div>
10
+
11
+ > **DeepSeek Harness (DSH)** 專屬的 Instagram 動態探索、智慧推坑與日報生成外掛。
12
+ > 自動沿用 `@luoyi-dsh/instagram-mcp` 設定之機器人帳號與主人帳號，定時或手動替主人刷 Instagram 首頁動態與模糊搜尋主題、嚴格過濾 AI 生成的影片/動畫/文章 (AIGC)、逐條深度審查正文評估主人興趣、自動點讚與留言 `@主人` 推坑，並自動彙整生成每日 Markdown 探索日報。
13
+
14
+ > [!CAUTION]
15
+ > ### ⚠️ 重要風險警告與免責聲明 (CRITICAL DISCLAIMER)
16
+ > 1. **違反 Instagram 社群守則與使用條款**：本插件採用非官方 API 進行自動化操作，明確違反 Instagram / Meta 的服務條款與社群守則。
17
+ > 2. **切勿使用本人主要帳號運行**：嚴禁使用個人主要帳號或重要商業帳號！請務必使用測試小號並搭配純淨住宅代理。
18
+ > 3. **免責宣告**：本專案純屬技術研究用途，任何帳號停權或損失由使用者自負風險。
19
+
20
+ ---
21
+
22
+ ## 🌟 核心特色
23
+
24
+ 1. **自動沿用 MCP 帳號設定**：
25
+ - 機器人登入帳號與推坑目標主人帳號 (`masterUsername`) 直接從 `@luoyi-dsh/instagram-mcp` 自動讀取與同步，無須重複設定。
26
+ 2. **自動動態牆與模糊關鍵字探索 (Scroll Duty)**：
27
+ - 結合首頁動態牆與多階段模糊搜尋 (`igFuzzySearchPosts`)，徹底解決單純標籤搜尋返回 0 則貼文的問題。
28
+ 3. **嚴格排除 AI 生成內容 (AIGC) 與正文深度審查**：
29
+ - 自動攔截 AI 生成影片、AI 動畫、AI 繪圖與 AI 農場文章，並分離正文與 `#標籤`，結合外部訂閱插件 (`dsh-plugin-subscriptions`) AI 額度進行深度語義審查，絕不隨便推坑。
30
+ 4. **每日探索日報 (`data/reports/YYYY-MM-DD.md`)**：
31
+ - 自動將今日瀏覽之精選貼文、摘要與推薦紀錄整理為 Markdown 日報，可隨時於 Web 面板閱讀。
32
+
33
+ ---
34
+
35
+ ## 📦 安裝方式
36
+
37
+ ```bash
38
+ # 使用 DSH CLI 安裝插件
39
+ dsh plugin --profile web add @luoyi-dsh/instagram-scroll
40
+
41
+ # 或透過 npm 安裝
42
+ npm install @luoyi-dsh/instagram-scroll
43
+ ```
44
+
45
+ ---
46
+
47
+ ## 📖 插件操作方法與工具調用說明
48
+
49
+ 完整的 DSH 工具清單、自然語言調用範例、HTTP REST API 端點與設定參數表，請參閱 **[AGENTS.md](AGENTS.md)**。
50
+
51
+ ---
52
+
53
+ ## 📁 目錄結構
54
+
55
+ ```text
56
+ dsh-instagram-scroll/
57
+ ├── cordis.patch.yml # DSH bundle patch 宣告
58
+ ├── package.json # 模組定義與依賴
59
+ ├── tsconfig.json # TypeScript 編譯設定
60
+ ├── AGENTS.md # 插件操作方法與 Agent 調用指南
61
+ ├── CHANGELOG.md # 版本更新紀錄
62
+ ├── README.md # 英文介紹文件
63
+ ├── README.zh-Hant.md # 繁體中文介紹文件 (本檔案)
64
+ ├── client.js # DSH Web 前端面板
65
+ └── src/ # 滾動探索核心、日報帳本管理與工具註冊
66
+ ```
67
+
68
+ ---
69
+
70
+ ## 📜 版本紀錄與授權條款
71
+
72
+ - 詳細版本演進與更新紀錄，請參閱 [CHANGELOG.md](CHANGELOG.md)。
73
+ - 本專案採用 [MIT License](LICENSE) 開源授權。