From 88b9c019a732550cffd50e6160f2cd1388436259 Mon Sep 17 00:00:00 2001
From: ZhangJia <comeonzhj@gmail.com>
Date: Mon, 9 Mar 2026 12:28:51 +0800
Subject: [PATCH] optimize skill: private-by-default, sketch theme, references
 docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- publish_xhs.py: 默认改为仅自己可见（is_private=True），--private 改为 --public 标志
- render_xhs.py: 默认主题从 default 改为 sketch
- SKILL.md: 重构为精简规范格式，引用 references/params.md
- references/params.md: 新增完整参数参考文档（渲染/发布/Markdown格式）
- README.md: 顶部添加一句话 Agent 安装指引，更新项目结构说明

Made-with: Cursor
---
 README.md              |  14 ++-
 SKILL.md               | 215 ++++++++++++-----------------------------
 references/params.md   | 156 ++++++++++++++++++++++++++++++
 scripts/publish_xhs.py |  20 ++--
 scripts/render_xhs.py  |   4 +-
 5 files changed, 240 insertions(+), 169 deletions(-)
 create mode 100644 references/params.md

diff --git a/README.md b/README.md
index 9af5d28..ef3e941 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,10 @@
 ## 📕 Auto-Redbook-Skills（已重构版）
 
+> **一句话安装此技能**：让你的 Agent 说：「拉取下面的项目，安装其中的技能：https://github.com/comeonzhj/Auto-Redbook-Skills 」
+
+---
+
+
 > 自动撰写小红书笔记、生成多主题卡片、可选自动发布的 Skills  
 > 当前版本对渲染脚本和样式系统做了**一次完整重构**，感谢 Cursor 的辅助开发 🙌
 
@@ -146,7 +151,7 @@ python scripts/publish_xhs.py \
 
 | 参数 | 说明 |
 |------|------|
-| `--private` | 设为私密笔记 |
+| `--public` | 公开发布（默认仅自己可见） |
 | `--post-time "2024-01-01 12:00:00"` | 定时发布 |
 | `--api-mode` | 通过 xhs-api 服务发布 |
 | `--dry-run` | 仅验证，不实际发布 |
@@ -162,6 +167,8 @@ Auto-Redbook-Skills/
 ├── requirements.txt      # Python 依赖
 ├── package.json          # Node.js 依赖
 ├── env.example.txt       # Cookie 配置示例
+├── references/           # 技能参考文档
+│   └── params.md         # 完整参数参考（主题/模式/发布参数）
 ├── assets/
 │   ├── cover.html        # 封面 HTML 模板
 │   ├── card.html         # 正文卡片 HTML 模板
@@ -185,9 +192,10 @@ Auto-Redbook-Skills/
 │   ├── Sketch/
 │   └── terminal/
 └── scripts/
-    ├── render_xhs.py     # Python 渲染脚本（支持主题 + 分页模式）
+    ├── render_xhs.py     # Python 渲染脚本（8 主题 + 4 分页模式）
+    ├── render_xhs_v2.py  # Python 渲染脚本 V2（7 渐变色彩风格）
     ├── render_xhs.js     # Node.js 渲染脚本
-    └── publish_xhs.py    # 小红书发布脚本
+    └── publish_xhs.py    # 小红书发布脚本（默认仅自己可见）
 ```
 
 ---
diff --git a/SKILL.md b/SKILL.md
index ef7ce0f..d53407c 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -1,212 +1,119 @@
 ---
 name: xhs-note-creator
-description: 小红书笔记素材创作技能。当用户需要创建小红书笔记素材时使用这个技能。技能包含：根据用户的需求和提供的资料，撰写小红书笔记内容（标题+正文），生成图片卡片（封面+正文卡片），以及发布小红书笔记。
+description: 小红书笔记素材创作技能。当用户需要创建小红书笔记素材时使用这个技能。技能包含：根据用户的需求和提供的资料，撰写小红书笔记内容（标题+正文），生成图片卡片（封面+正文卡片），以及发布小红书笔记。支持 8 种精美排版主题和 4 种智能分页模式。
 ---
 
 # 小红书笔记创作技能
 
-这个技能用于创建专业的小红书笔记素材，包括内容撰写、图片卡片生成和笔记发布。
+根据用户提供的资料或需求，创作小红书笔记内容、生成精美图片卡片，并可选择发布到小红书。
 
-## 使用场景
+> 详细参数文档见 `references/params.md`
 
-- 用户需要创建小红书笔记时
-- 用户提供资料需要转化为小红书风格内容时
-- 用户需要生成精美的图片卡片用于发布时
+---
 
 ## 工作流程
 
 ### 第一步：撰写小红书笔记内容
 
-根据用户需求和提供的资料，创作符合小红书风格的内容：
+根据用户需求和资料，创作符合小红书风格的内容：
 
-#### 标题要求
-- 不超过 20 字
-- 吸引眼球，制造好奇心
-- 可使用数字、疑问句、感叹号增强吸引力
-- 示例：「5个让效率翻倍的神器推荐！」「震惊！原来这样做才对」
+**标题**：不超过 20 字，吸引眼球，可用数字/疑问句/感叹号增强吸引力。
 
-#### 正文要求
-- 使用良好的排版，段落清晰
-- 点缀少量 Emoji 增加可读性（每段 1-2 个即可）
-- 使用简短的句子和段落
-- 结尾给出 SEO 友好的 Tags 标签（5-10 个相关标签）
+**正文**：段落清晰，点缀少量 Emoji（每段 1-2 个），短句短段，结尾附 5-10 个 SEO 标签。
 
-### 第二步：生成 Markdown 文档
-
-**注意：这里生成的 Markdown 文档是用于渲染卡片的，必须专门生成，禁止直接使用上一步的笔记正文内容。**
-
-Markdown 文件，文件应包含：
-
-1. YAML 头部元数据（封面信息）：
-```yaml
 ---
-emoji: "🚀"           # 封面装饰 Emoji
-title: "大标题"        # 封面大标题（不超过15字）
-subtitle: "副标题文案"  # 封面副标题（不超过15字）
----
-```
 
-2. 用于渲染卡片的 Markdown 文本内容：
-   - 当待渲染内容必须严格切分为独立的数张图片时，可使用 `---` 分割线主动将正文分隔为多个卡片段落（每个段落文本控制在 200 字左右），输出图片时使用参数`-m separator`
-   - 当待渲染内容无需严格分割，生成正常 Markdown 文本即可，跟下方分页模式参数规则按需选择
+### 第二步：生成渲染用 Markdown 文档
 
-完整 Markdown 文档内容示例：
+**注意：此 Markdown 专为图片渲染设计，禁止直接使用上一步的笔记正文。**
+
+文档结构：
 
 ```markdown
 ---
-emoji: "💡"
-title: "5个效率神器让工作效率翻倍"
-subtitle: "对着抄作业就好了，一起变高效"
+emoji: "🚀"
+title: "封面大标题（≤15字）"
+subtitle: "封面副标题（≤15字）"
 ---
 
-# 📝 神器一：Notion
+# 正文内容...
 
-> 全能型笔记工具，支持数据库、看板、日历等多种视图...
-
-## 特色功能
-
-- 特色一
-- 特色二
-
-# ⚡ 神器二：Raycast
-
-\`\`\`
-可使用代码块来增加渲染后图片的视觉丰富度
-\`\`\`
-
-## 推荐原因
-
-- 原因一
-- 原因二
-- ……
-
-
-# 🌈 神器三：Arc
-
-全新理念的浏览器，侧边栏标签管理...
-
-...
+---
 
+# 第二张卡片内容...（使用 --- 手动分隔时）
 ```
 
-### 第三步：渲染图片卡片
+分页策略选择：
+- 内容需精确切分 → 用 `---` 手动分隔，配合 `-m separator`
+- 内容长短不稳定 → 生成普通 Markdown，使用 `-m auto-split`
 
-将 Markdown 文档渲染为图片卡片。使用以下脚本渲染：
+---
+
+### 第三步：渲染图片卡片
 
 ```bash
 python scripts/render_xhs.py <markdown_file> [options]
 ```
 
-- 默认输出目录为当前工作目录
-- 生成的图片包括：封面（cover.png）和正文卡片（card_1.png, card_2.png, ...）
+**默认主题**：`sketch`（手绘素描风格）  
+**默认分页**：`separator`（按 `---` 分隔）
 
-#### 渲染参数（Python）
-
-| 参数 | 简写 | 说明 | 默认值 |
-|---|---|---|---|
-| `--output-dir` | `-o` | 输出目录 | 当前工作目录 |
-| `--theme` | `-t` | 排版主题 | `default` |
-| `--mode` | `-m` | 分页模式 | `separator` |
-| `--width` | `-w` | 图片宽度 | `1080` |
-| `--height` |  | 图片高度（`dynamic` 下为最小高度） | `1440` |
-| `--max-height` |  | `dynamic` 最大高度 | `4320` |
-| `--dpr` |  | 设备像素比（清晰度） | `2` |
-
-#### 排版主题（`--theme`）
-
-- `default`：默认简约浅灰渐变背景（`#f3f3f3 -> #f9f9f9`）
-- `playful-geometric`：活泼几何（Memphis）
-- `neo-brutalism`：新粗野主义
-- `botanical`：植物园自然
-- `professional`：专业商务
-- `retro`：复古怀旧
-- `terminal`：终端命令行
-- `sketch`：手绘素描
-
-#### 分页模式（`--mode`）
-
-- `separator`：按 `---` 分隔符分页（适合内容已手动控量）
-- `auto-fit`：固定尺寸下自动缩放文字，避免溢出/留白（适合封面+单张图片但尺寸固定的情况）
-- `auto-split`：按渲染后高度自动切分分页（适合切分不影响阅读的长文内容）
-- `dynamic`：根据内容动态调整图片高度（注意：图片最高 4320，字数超过 550 的不建使用此模式）
-
-#### 常用示例
+常用示例：
 
 ```bash
-# 1) 默认主题 + 手动分隔分页
-python scripts/render_xhs.py content.md -m separator
+# 默认（sketch 主题 + 手动分页）
+python scripts/render_xhs.py content.md
 
-# 2) 固定 1080x1440，自动缩放文字，尽量填满画面
-python scripts/render_xhs.py content.md -m auto-fit
-
-# 3) 自动切分分页（推荐：内容长短不稳定）
+# 自动分页（推荐内容长短不定时）
 python scripts/render_xhs.py content.md -m auto-split
 
-# 4) 动态高度（允许不同高度卡片）
-python scripts/render_xhs.py content.md -m dynamic --max-height 4320
-
-# 5) 切换主题
+# 切换主题
 python scripts/render_xhs.py content.md -t playful-geometric -m auto-split
+
+# 固定尺寸自动缩放
+python scripts/render_xhs.py content.md -m auto-fit
 ```
 
-#### Node.js 渲染（可选）
+生成结果：`cover.png`（封面）+ `card_1.png`、`card_2.png`...（正文卡片）
 
-```bash
-node scripts/render_xhs.js content.md -t default -m separator
-```
+**可用主题**（`-t`）：`sketch`、`default`、`playful-geometric`、`neo-brutalism`、`botanical`、`professional`、`retro`、`terminal`
 
-Node.js 参数与 Python 基本一致：`--output-dir/-o`、`--theme/-t`、`--mode/-m`、`--width/-w`、`--height`、`--max-height`、`--dpr`。
+**分页模式**（`-m`）：`separator`、`auto-fit`、`auto-split`、`dynamic`
+
+> 完整参数说明见 `references/params.md`
+
+---
 
 ### 第四步：发布小红书笔记（可选）
 
-使用发布脚本将生成的图片发布到小红书：
+**前置条件**：配置好 `.env` 文件中的 `XHS_COOKIE`（详见 `references/params.md`）
 
 ```bash
-python scripts/publish_xhs.py --title "笔记标题" --desc "笔记描述" --images card_1.png card_2.png cover.png
+# 默认仅自己可见（推荐先预览确认）
+python scripts/publish_xhs.py --title "笔记标题" --desc "笔记描述" \
+  --images cover.png card_1.png card_2.png
+
+# 确认无误后公开发布
+python scripts/publish_xhs.py --title "笔记标题" --desc "笔记描述" \
+  --images cover.png card_1.png card_2.png --public
 ```
 
-**前置条件**：
+> **默认以「仅自己可见」发布**，加 `--public` 参数才会公开。
 
-1. 需配置小红书 Cookie：
-```
-XHS_COOKIE=your_cookie_string_here
-```
-
-2. Cookie 获取方式：
-   - 在浏览器中登录小红书（https://www.xiaohongshu.com）
-   - 打开开发者工具（F12）
-   - 在 Network 标签中查看请求头的 Cookie
-
-## 图片规格说明
-
-### 封面卡片
-- 尺寸比例：3:4（小红书推荐比例）
-- 基准尺寸：1080×1440px
-- 包含：Emoji 装饰、大标题、副标题
-- 样式：渐变背景 + 圆角内容区
-
-### 正文卡片
-- 尺寸比例：3:4
-- 基准尺寸：1080×1440px
-- 支持：标题、段落、列表、引用、代码块、图片
-- 样式：白色卡片 + 渐变背景边框
+---
 
 ## 技能资源
 
-### 脚本文件
-- `scripts/render_xhs.py` - Python 渲染脚本
-- `scripts/render_xhs.js` - Node.js 渲染脚本
-- `scripts/publish_xhs.py` - 小红书发布脚本
+### 脚本
+- `scripts/render_xhs.py` — 渲染脚本（主推，8 主题 + 4 分页模式）
+- `scripts/render_xhs_v2.py` — 渲染脚本 V2（备用，7 种渐变色彩风格）
+- `scripts/publish_xhs.py` — 发布脚本
 
-### 资源文件
-- `assets/cover.html` - 封面 HTML 模板
-- `assets/card.html` - 正文卡片 HTML 模板
-- `assets/styles.css` - 共用样式表
+### 模板与样式
+- `assets/cover.html` — 封面 HTML 模板
+- `assets/card.html` — 正文卡片 HTML 模板
+- `assets/styles.css` — 公共容器样式
+- `assets/themes/` — 各主题 CSS 文件
 
-## 注意事项
-
-1. Markdown 文件应保存在工作目录，渲染后的图片也保存在工作目录
-2. 技能目录 (`md2Redbook/`) 仅存放脚本和模板，不存放用户数据
-3. 图片尺寸会根据内容自动调整，但保持 3:4 比例
-4. Cookie 有有效期限制，过期后需要重新获取
-5. 发布功能依赖 xhs 库，需要安装：`pip install xhs`
+### 参考文档
+- `references/params.md` — 完整参数参考（主题/模式/发布参数）
diff --git a/references/params.md b/references/params.md
new file mode 100644
index 0000000..d7f2c2b
--- /dev/null
+++ b/references/params.md
@@ -0,0 +1,156 @@
+# 参数参考文档
+
+## 渲染脚本（render_xhs.py）
+
+```bash
+python scripts/render_xhs.py <markdown_file> [options]
+```
+
+### 参数列表
+
+| 参数 | 简写 | 说明 | 默认值 |
+|---|---|---|---|
+| `--output-dir` | `-o` | 输出目录 | 当前工作目录 |
+| `--theme` | `-t` | 排版主题 | `sketch` |
+| `--mode` | `-m` | 分页模式 | `separator` |
+| `--width` | `-w` | 图片宽度（px） | `1080` |
+| `--height` | | 图片高度（`dynamic` 下为最小高度） | `1440` |
+| `--max-height` | | `dynamic` 模式下的最大高度 | `4320` |
+| `--dpr` | | 设备像素比（清晰度） | `2` |
+
+### 排版主题（`--theme`）
+
+| 值 | 名称 | 说明 |
+|---|---|---|
+| `sketch` | 手绘素描 | 手绘风格，默认 |
+| `default` | 默认简约 | 浅灰渐变背景（`#f3f3f3 → #f9f9f9`） |
+| `playful-geometric` | 活泼几何 | Memphis 设计风格 |
+| `neo-brutalism` | 新粗野主义 | 粗框线条、强对比 |
+| `botanical` | 植物园自然 | 自然绿植风格 |
+| `professional` | 专业商务 | 简洁商务蓝 |
+| `retro` | 复古怀旧 | 暖色复古感 |
+| `terminal` | 终端命令行 | 深色代码终端风格 |
+
+### 分页模式（`--mode`）
+
+| 值 | 说明 | 适用场景 |
+|---|---|---|
+| `separator` | 按 `---` 分隔符分页 | 内容已手动控量，需要精确分页 |
+| `auto-fit` | 固定尺寸，自动整体缩放内容 | 封面 + 单张图，尺寸固定不溢出 |
+| `auto-split` | 根据渲染后高度自动切分 | 内容长短不稳定，推荐通用选择 |
+| `dynamic` | 根据内容动态调整图片高度 | 允许不同高度卡片，字数 ≤550 |
+
+### 常用命令示例
+
+```bash
+# 默认：sketch 主题 + 手动分隔分页
+python scripts/render_xhs.py content.md
+
+# 自动分页（推荐内容不稳定时使用）
+python scripts/render_xhs.py content.md -m auto-split
+
+# 固定尺寸自动缩放
+python scripts/render_xhs.py content.md -m auto-fit
+
+# 切换主题
+python scripts/render_xhs.py content.md -t playful-geometric -m auto-split
+
+# 自定义尺寸
+python scripts/render_xhs.py content.md -t retro -m dynamic --width 1080 --height 1440 --dpr 2
+```
+
+---
+
+## 发布脚本（publish_xhs.py）
+
+```bash
+python scripts/publish_xhs.py --title "标题" --desc "描述" --images img1.png img2.png
+```
+
+### 参数列表
+
+| 参数 | 简写 | 说明 | 默认值 |
+|---|---|---|---|
+| `--title` | `-t` | 笔记标题（不超过 20 字） | 必填 |
+| `--desc` | `-d` | 笔记描述/正文内容 | `""` |
+| `--images` | `-i` | 图片文件路径（可多个） | 必填 |
+| `--public` | | 公开发布（默认仅自己可见） | `False` |
+| `--post-time` | | 定时发布（格式：`2024-01-01 12:00:00`） | 立即发布 |
+| `--api-mode` | | 通过 xhs-api 服务发布 | 本地模式 |
+| `--api-url` | | API 服务地址 | `http://localhost:5005` |
+| `--dry-run` | | 仅验证，不实际发布 | `False` |
+
+> **注意**：默认以「仅自己可见」发布，确认内容无误后再用 `--public` 公开。
+
+### 常用命令示例
+
+```bash
+# 默认（仅自己可见，用于预览确认）
+python scripts/publish_xhs.py --title "标题" --desc "描述" --images cover.png card_1.png card_2.png
+
+# 公开发布
+python scripts/publish_xhs.py --title "标题" --desc "描述" --images cover.png card_1.png --public
+
+# 定时发布
+python scripts/publish_xhs.py --title "标题" --desc "描述" --images *.png --post-time "2024-12-01 10:00:00" --public
+
+# API 模式
+python scripts/publish_xhs.py --title "标题" --desc "描述" --images *.png --api-mode
+
+# 仅验证不发布
+python scripts/publish_xhs.py --title "标题" --desc "描述" --images *.png --dry-run
+```
+
+### 环境变量配置（.env）
+
+```bash
+cp env.example.txt .env
+```
+
+编辑 `.env`：
+
+```env
+# 必需：小红书 Cookie
+XHS_COOKIE=your_cookie_string_here
+
+# 可选：API 模式服务地址
+XHS_API_URL=http://localhost:5005
+```
+
+**Cookie 获取方式**：浏览器登录小红书 → F12 → Network → 任意请求的 Cookie 头，复制完整字符串。
+
+---
+
+## Markdown 文档格式
+
+### YAML 头部元数据
+
+```yaml
+---
+emoji: "🚀"           # 封面装饰 Emoji
+title: "大标题"        # 封面大标题（不超过 15 字）
+subtitle: "副标题文案"  # 封面副标题（不超过 15 字）
+---
+```
+
+### 分页分隔符
+
+使用 `---` 手动分割卡片（配合 `-m separator` 使用）：
+
+```markdown
+---
+emoji: "💡"
+title: "工具推荐"
+subtitle: "提升效率的 5 个神器"
+---
+
+# 神器一：Notion
+
+> 全能笔记工具...
+
+---
+
+# 神器二：Raycast
+
+快捷启动工具...
+```
diff --git a/scripts/publish_xhs.py b/scripts/publish_xhs.py
index 0271365..7da6be8 100644
--- a/scripts/publish_xhs.py
+++ b/scripts/publish_xhs.py
@@ -155,7 +155,7 @@ class LocalPublisher:
             return None
     
     def publish(self, title: str, desc: str, images: List[str], 
-                is_private: bool = False, post_time: str = None) -> Dict[str, Any]:
+                is_private: bool = True, post_time: str = None) -> Dict[str, Any]:
         """发布图文笔记"""
         print(f"\n🚀 准备发布笔记（本地模式）...")
         print(f"  📌 标题: {title}")
@@ -268,7 +268,7 @@ class ApiPublisher:
             return None
     
     def publish(self, title: str, desc: str, images: List[str], 
-                is_private: bool = False, post_time: str = None) -> Dict[str, Any]:
+                is_private: bool = True, post_time: str = None) -> Dict[str, Any]:
         """发布图文笔记"""
         print(f"\n🚀 准备发布笔记（API 模式）...")
         print(f"  📌 标题: {title}")
@@ -317,15 +317,15 @@ def main():
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog='''
 示例:
-  # 基本用法
+  # 基本用法（默认仅自己可见）
   python publish_xhs.py -t "我的标题" -d "正文内容" -i cover.png card_1.png card_2.png
   
+  # 公开发布
+  python publish_xhs.py -t "我的标题" -d "正文内容" -i *.png --public
+  
   # 使用 API 模式
   python publish_xhs.py -t "我的标题" -d "正文内容" -i *.png --api-mode
   
-  # 设为私密笔记
-  python publish_xhs.py -t "我的标题" -d "正文内容" -i *.png --private
-  
   # 定时发布
   python publish_xhs.py -t "我的标题" -d "正文内容" -i *.png --post-time "2024-12-01 10:00:00"
 '''
@@ -347,9 +347,9 @@ def main():
         help='图片文件路径（可以多个）'
     )
     parser.add_argument(
-        '--private',
+        '--public',
         action='store_true',
-        help='是否设为私密笔记'
+        help='公开发布（默认为仅自己可见）'
     )
     parser.add_argument(
         '--post-time',
@@ -393,7 +393,7 @@ def main():
         print(f"  📌 标题: {args.title}")
         print(f"  📝 描述: {args.desc}")
         print(f"  🖼️ 图片: {valid_images}")
-        print(f"  🔒 私密: {args.private}")
+        print(f"  🔒 私密: {not args.public}")
         print(f"  ⏰ 定时: {args.post_time or '立即发布'}")
         print(f"  📡 模式: {'API' if args.api_mode else '本地'}")
         print("\n✅ 验证通过，可以发布")
@@ -414,7 +414,7 @@ def main():
             title=args.title,
             desc=args.desc,
             images=valid_images,
-            is_private=args.private,
+            is_private=not args.public,
             post_time=args.post_time
         )
     except Exception as e:
diff --git a/scripts/render_xhs.py b/scripts/render_xhs.py
index 8cd24a9..be251eb 100644
--- a/scripts/render_xhs.py
+++ b/scripts/render_xhs.py
@@ -669,8 +669,8 @@ def main():
     parser.add_argument(
         '--theme', '-t',
         choices=AVAILABLE_THEMES,
-        default='default',
-        help='排版主题（默认: default）'
+        default='sketch',
+        help='排版主题（默认: sketch）'
     )
     parser.add_argument(
         '--mode', '-m',