skill

Author: biliww

.agents/skills/yunyu-admin-operator/references/connection-management.md

@@ -4,13 +4,18 @@
 
 ## 一、连接信息组成
 
-调用后台接口前，至少需要以下两个字段：
+调用后台接口前，至少需要以下字段：
 
 1. `baseUrl`
-   目标后台域名或基础地址，例如：
+   目标后端域名或基础地址，例如：
    - `http://127.0.0.1:20000`
-   - `https://admin.example.com`
-2. `token`
+   - `https://yunyu-server-native.ideaflow.top`
+2. `frontendBaseUrl`（可选，文章操作时需要）
+   目标前端域名或基础地址，用于调用前端提供的 Markdown 渲染接口，例如：
+   - `http://127.0.0.1:19999`
+   - `https://yunyu.ideaflow.top`
+   仅在新增或编辑文章时需要；纯数据操作（分类/标签/配置管理等）不需要此字段。
+3. `token`
    后台登录后的 Bearer token，不需要手动加 `Bearer ` 前缀时，由调用方按实际请求格式处理。
 
 ## 二、本地保存位置
@@ -26,6 +31,7 @@
 ```json
 {
   "baseUrl": "http://127.0.0.1:20000",
+  "frontendBaseUrl": "http://127.0.0.1:19999",
   "token": "<SECRET>",
   "updatedAt": "2026-04-27T00:00:00+08:00"
 }
@@ -34,6 +40,7 @@
 说明：
 
 - `baseUrl` 和 `token` 是必填。
+- `frontendBaseUrl` 是选填，仅在需要 Markdown 渲染（创建/编辑文章）时使用。
 - `updatedAt` 用于记录最后一次更新连接信息的时间，便于排查失效问题。
 - 该文件只用于本地 skill 运行，不应提交到仓库。
 
@@ -47,7 +54,7 @@
 2. 如果存在有效 `baseUrl` 和 `token`，优先直接使用。
 3. 如果文件不存在、字段缺失或用户明确要求切换环境，再向用户索要新的 `baseUrl` 和 `token`。
 4. 收到新的连接信息后，覆盖写回本地连接文件，供后续复用：
-   `bash .agents/skills/yunyu-admin-operator/scripts/admin_connection.sh set --base-url <URL> --token <TOKEN>`
+   `bash .agents/skills/yunyu-admin-operator/scripts/admin_connection.sh set --base-url <URL> --token <TOKEN> [--frontend-base-url <URL>]`
 
 ## 四、脚本用法
 
@@ -57,7 +64,8 @@
 bash .agents/skills/yunyu-admin-operator/scripts/admin_connection.sh show
 bash .agents/skills/yunyu-admin-operator/scripts/admin_connection.sh get baseUrl
 bash .agents/skills/yunyu-admin-operator/scripts/admin_connection.sh get token
-bash .agents/skills/yunyu-admin-operator/scripts/admin_connection.sh set --base-url <URL> --token <TOKEN>
+bash .agents/skills/yunyu-admin-operator/scripts/admin_connection.sh get frontendBaseUrl
+bash .agents/skills/yunyu-admin-operator/scripts/admin_connection.sh set --base-url <URL> --token <TOKEN> [--frontend-base-url <URL>]
 bash .agents/skills/yunyu-admin-operator/scripts/admin_connection.sh clear
 ```
 

.agents/skills/yunyu-admin-operator/references/post-management.md

@@ -2,6 +2,58 @@
 
 本文档用于指导 agent 通过后台接口完成文章新增、编辑与相关 AI 辅助操作。
 
+## 前置：Markdown 渲染接口
+
+新增或编辑文章正文时，必须先调用前端提供的 Markdown 渲染接口，拿到与后台编辑器一致的 HTML 和目录 JSON，再提交给后端。
+
+**渲染接口地址：**
+```
+POST {frontendBaseUrl}/api/render-markdown
+Content-Type: application/json
+```
+
+**请求体：**
+```json
+{ "markdown": "# 标题\n\n正文内容" }
+```
+
+**响应体：**
+```json
+{
+  "html": "<h1 id=\"...\">标题</h1>\n<p>正文内容</p>\n",
+  "toc": [{ "id": "...", "text": "标题", "level": 1 }],
+  "tocJson": "[{\"id\":\"...\",\"text\":\"标题\",\"level\":1}]",
+  "plainText": "标题 正文内容",
+  "readingMinutes": 1
+}
+```
+
+**说明：**
+- `html` → 对应后端接口的 `contentHtml` 字段
+- `tocJson` → 对应后端接口的 `contentTocJson` 字段
+- `frontendBaseUrl` 从本地连接文件中读取；如果不存在，可向用户索要
+- 前端渲染接口与后台编辑器使用完全相同的 `markdown-it` + Shiki 管线，保证渲染结果一致**
+
+**完整流程：**
+
+```text
+1. 取文章本地 Markdown 内容
+        │
+        ▼
+2. POST {frontendBaseUrl}/api/render-markdown
+   body: { markdown: "..." }
+        │
+        ▼
+3. 拿到 html + tocJson
+        │
+        ▼
+4. POST /api/admin/posts（创建）或 PUT /api/admin/posts/{id}（编辑）
+   body: { contentMarkdown, contentHtml, contentTocJson, ...其他字段 }
+
+⚠️ 创建文章时，html + tocJson 必须和基础字段一起在 POST 中提交，
+   不要先创建再 PUT 补全。一次完成，不要分两步。
+```
+
 ## 零、统一前置步骤
 
 在查询或写入文章相关后台接口前，先处理连接信息：
@@ -20,46 +72,53 @@
 建议按以下顺序操作：
 
 1. 先确认用户是否已经提供文章标题和正文。
-2. 如果用户没有指定分类或标签，先查询可用列表：
+2. 如果在创建前需要生成正文的 HTML 和目录，先调用渲染接口：
+   - `POST {frontendBaseUrl}/api/render-markdown`
+   - 传入正文 Markdown，拿到 `html`、`tocJson` 等字段
+   - 后续提交时一并传给后端
+3. 如果用户没有指定分类或标签，先查询可用列表：
    - `GET /api/admin/categories`
    - `GET /api/admin/tags`
-3. 根据文章标题和正文语义，从已有分类、标签里挑选最合适的项：
+4. 根据文章标题和正文语义，从已有分类、标签里挑选最合适的项：
    - 若确实存在明显匹配项，应自动选中对应分类 / 标签
    - 若没有明显匹配项，可以留空，不要为了凑字段乱选
-4. 专题默认视为“不设置”：
+5. 专题默认视为"不设置"：
    - 只有用户明确说本次也要挂专题时，才查询 `GET /api/admin/topics`
    - 用户未指定时，不调用专题相关接口
-5. `slug`、`summary`、`seoTitle`、`seoDescription`：
+6. `slug`、`summary`、`seoTitle`、`seoDescription`：
    - 如果用户已提供，优先使用用户提供值。
    - 如果用户未提供，优先由当前 AI agent 根据标题和正文直接生成。
    - 默认不要为了补这些字段再额外调用 `POST /api/admin/posts/ai/meta/generate`。
    - 只有当用户明确要求使用后台 AI 元信息生成能力，或需要和后台内置生成结果保持一致时，才考虑调用该接口。
    - 调用该接口时优先传 `title` 与 `contentMarkdown`；后端会统一组装提示词并返回 OpenAI Chat 风格结果。
-6. 文章状态默认建议：
+7. 文章状态默认建议：
    - 若用户没有明确要求立即发布，默认传 `DRAFT`
-   - 若用户明确说“直接发布”，传 `PUBLISHED`
-   - 若用户明确说“保存但先下线”，传 `OFFLINE`
-7. 布尔默认建议：
+   - 若用户明确说"直接发布"，传 `PUBLISHED`
+   - 若用户明确说"保存但先下线"，传 `OFFLINE`
+8. 布尔默认建议：
    - `isTop=false`
    - `isRecommend=false`
    - `allowComment=true`
-8. 内容权限默认不启用。
-   - 应主动提示用户：“当前默认不启用内容权限，要不要开启文章访问控制或隐藏内容权限？”
-9. 若用户不启用内容权限：
+9. 内容权限默认不启用。
+   - 应主动提示用户："当前默认不启用内容权限，要不要开启文章访问控制或隐藏内容权限？"
+10. 若用户不启用内容权限：
    - 仍建议提交默认的禁用结构，保持与当前后台编辑器一致。
-10. 若用户启用整篇文章访问控制：
+11. 若用户启用整篇文章访问控制：
    - 至少选择一个规则：`LOGIN` / `WECHAT_ACCESS_CODE` / `ACCESS_CODE`
    - 若包含 `ACCESS_CODE`，必须同时填写：
      - `articleAccessCode`
      - `articleAccessCodeHint`
-11. 若用户启用尾部隐藏内容：
-    - 必须填写：
-      - `tailHiddenAccess.enabled=true`
-      - `tailHiddenAccess.title`
-      - `tailHiddenAccess.ruleTypes`
-      - `tailHiddenContentMarkdown`
-12. 创建文章最终调用：
+12. 若用户启用尾部隐藏内容：
+   - 必须填写：
+     - `tailHiddenAccess.enabled=true`
+     - `tailHiddenAccess.title`
+     - `tailHiddenAccess.ruleTypes`
+     - `tailHiddenContentMarkdown`
+13. 创建文章最终调用：
     - `POST /api/admin/posts`
+    - 请求体中应包含从渲染接口获取的 `contentHtml` 和 `contentTocJson`
+    - **⚠️ 关键约束：渲染结果（contentHtml、contentTocJson）必须一次性带入 POST 请求，禁止先创建再 PUT 补全。**
+      创建时只传基础字段后续再 PUT 补充渲染结果属于冗余请求，既浪费 token 也无必要；POST 创建本就支持所有字段同时提交。
 
 ## 二、编辑文章
 
@@ -70,12 +129,18 @@
 1. 先定位目标文章。
 2. 用 `GET /api/admin/posts/{postId}` 读取当前完整详情。
 3. 在原详情基础上合并本次修改。
-4. 因为更新接口要求很多字段保留完整语义，不能只传一个零散字段然后丢掉其他字段。
-5. 若用户只说“改摘要”或“改标题”：
+4. 如果本次修改涉及正文内容，先调用渲染接口获取新的 HTML 和目录：
+   - `POST {frontendBaseUrl}/api/render-markdown`
+   - 传入新的正文 Markdown，拿到 `html` 和 `tocJson`
+   - 在最终提交时替换 `contentHtml` 和 `contentTocJson`
+5. 如果本次修改不涉及正文（只改状态、封面、标签等），**不需要调用渲染接口**。
+   - `contentMarkdown` 设置为 `null` 即可，后端不会清空已有正文（详见后端增量更新逻辑）
+6. 因为更新接口要求很多字段保留完整语义，不能只传一个零散字段然后丢掉其他字段。
+7. 若用户只说"改摘要"或"改标题"：
    - 也应该先获取原文详情
    - 再仅修改目标字段
    - 其余字段保持原值
-6. 更新文章最终调用：
+8. 更新文章最终调用：
    - `PUT /api/admin/posts/{postId}`
 
 ## 三、文章创建与编辑时的重点字段

.agents/skills/yunyu-admin-operator/scripts/admin_connection.sh

@@ -16,12 +16,13 @@ usage() {
   bash .agents/skills/yunyu-admin-operator/scripts/admin_connection.sh show
   bash .agents/skills/yunyu-admin-operator/scripts/admin_connection.sh get baseUrl
   bash .agents/skills/yunyu-admin-operator/scripts/admin_connection.sh get token
-  bash .agents/skills/yunyu-admin-operator/scripts/admin_connection.sh set --base-url <URL> --token <TOKEN>
+  bash .agents/skills/yunyu-admin-operator/scripts/admin_connection.sh get frontendBaseUrl
+  bash .agents/skills/yunyu-admin-operator/scripts/admin_connection.sh set --base-url <URL> --token <TOKEN> [--frontend-base-url <URL>]
   bash .agents/skills/yunyu-admin-operator/scripts/admin_connection.sh clear
 
 说明：
   show            展示当前连接信息，token 会做脱敏处理。
-  get <field>     读取指定字段，支持 baseUrl / token / updatedAt。
+  get <field>     读取指定字段，支持 baseUrl / token / frontendBaseUrl / updatedAt。
   set             保存或覆盖连接信息。
   clear           删除本地连接信息文件。
 USAGE
@@ -86,13 +87,17 @@ mask_token() {
 # 展示当前连接信息。
 show_connection() {
   require_connection_file
-  local base_url token updated_at masked_token
+  local base_url frontend_base_url token updated_at masked_token
   base_url="$(read_field baseUrl)"
+  frontend_base_url="$(read_field frontendBaseUrl 2>/dev/null || true)"
   token="$(read_field token)"
   updated_at="$(read_field updatedAt 2>/dev/null || true)"
   masked_token="$(mask_token "$token")"
 
   echo "baseUrl: $base_url"
+  if [[ -n "$frontend_base_url" ]]; then
+    echo "frontendBaseUrl: $frontend_base_url"
+  fi
   echo "token: $masked_token"
   if [[ -n "$updated_at" ]]; then
     echo "updatedAt: $updated_at"
@@ -102,6 +107,7 @@ show_connection() {
 # 保存连接信息。
 set_connection() {
   local base_url=""
+  local frontend_base_url=""
   local token=""
 
   while [[ $# -gt 0 ]]; do
@@ -110,6 +116,10 @@ set_connection() {
         base_url="${2:-}"
         shift 2
         ;;
+      --frontend-base-url)
+        frontend_base_url="${2:-}"
+        shift 2
+        ;;
       --token)
         token="${2:-}"
         shift 2
@@ -132,15 +142,16 @@ set_connection() {
   fi
 
   ensure_local_dir
-  python3 - "$CONNECTION_FILE" "$base_url" "$token" <<'PY'
+  python3 - "$CONNECTION_FILE" "$base_url" "$frontend_base_url" "$token" <<'PY'
 import json
 import sys
 from datetime import datetime, timezone, timedelta
 from pathlib import Path
 
 file_path = Path(sys.argv[1])
 base_url = sys.argv[2]
-token = sys.argv[3]
+frontend_base_url = sys.argv[3] or None
+token = sys.argv[4]
 shanghai = timezone(timedelta(hours=8))
 updated_at = datetime.now(shanghai).isoformat(timespec="seconds")
 
@@ -149,6 +160,8 @@ payload = {
     "token": token,
     "updatedAt": updated_at,
 }
+if frontend_base_url:
+    payload["frontendBaseUrl"] = frontend_base_url
 file_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
 PY
 

docs/前端/README.md

@@ -26,6 +26,7 @@
 - `12-封面古诗词打字机组件接入方案.md`
 - `14-前台轻动态装饰组件方案.md`
 - `15-后台列表公共组件技术方案.md`
+- `16-前台多主题页面架构方案.md`
 - `ui/01-基础视觉与交互规范.md`
 - `ui/02-文章内容展示UI规范.md`
 - `ui/03-后台布局与工作台规范.md`

yunyu-server/src/main/java/com/ideaflow/yunyu/module/post/admin/service/AdminPostService.java

@@ -304,7 +304,13 @@ private void saveOrUpdatePostContent(Long postId,
                                          ContentAccessConfig contentAccessConfig,
                                          String tailHiddenContentMarkdown,
                                          String tailHiddenContentHtml) {
-        String markdown = contentMarkdown == null ? "" : contentMarkdown.trim();
+        // 如果 contentMarkdown 为 null，说明调用方只更新主表字段（如状态/封面），
+        // 不打算修改正文，跳过整个正文更新，避免 null 被当作 "" 覆盖数据库已有内容。
+        if (contentMarkdown == null) {
+            return;
+        }
+
+        String markdown = contentMarkdown.trim();
         String html = contentHtml == null || contentHtml.isBlank() ? markdown : contentHtml.trim();
         String tocJson = contentTocJson == null || contentTocJson.isBlank() ? null : contentTocJson.trim();
         String normalizedVideoUrl = normalizeOptionalValue(videoUrl);