feat(shared): Implement sharing functionality for user-shared experts and moderator modes

- Added APIs to share topic-level experts and custom moderator modes to the `topiclab_shared` directory, allowing users to contribute their own content.
- Introduced `reload_expert_specs` and `reload_moderator_modes` functions to refresh in-memory data after sharing.
- Updated the `meta.json` files for both experts and moderator modes to include `topiclab_shared` as a source, facilitating better organization of user-shared content.
- Enhanced the `.gitignore` to exclude user-shared files while retaining essential metadata.
- Added tests to verify the sharing functionality and ensure proper handling of built-in expert and mode conflicts.
- Updated documentation to reflect new API endpoints for sharing and the structure of user-shared content.

Author: FZR95

.gitignore

@@ -25,4 +25,10 @@ htmlcov/
 
 *.log*
 
-workspace/
+workspace/
+
+# User-shared content in topiclab_shared (runtime data; keep expert_common.md, moderator_common.md)
+libs/experts/topiclab_shared/*.md
+!libs/experts/topiclab_shared/expert_common.md
+libs/moderator_modes/topiclab_shared/*.md
+!libs/moderator_modes/topiclab_shared/moderator_common.md

app/agent/experts.py

@@ -29,6 +29,19 @@
 EXPERT_SPECS = _EXPERT_SPECS_RAW
 EXPERT_CATEGORIES = _EXPERTS_CATEGORIES
 
+
+def reload_expert_specs() -> None:
+    """Reload EXPERT_SPECS and EXPERT_CATEGORIES from disk (e.g. after share to topiclab_shared).
+
+    Updates dicts in-place so importers (e.g. experts API) see the new data.
+    """
+    global _EXPERTS_CATEGORIES, _EXPERT_SPECS_RAW, _SOURCE_COMMON
+    _EXPERTS_CATEGORIES, _EXPERT_SPECS_RAW, _SOURCE_COMMON = load_aggregated_experts_meta(_EXPERTS_DIR)
+    EXPERT_SPECS.clear()
+    EXPERT_SPECS.update(_EXPERT_SPECS_RAW)
+    EXPERT_CATEGORIES.clear()
+    EXPERT_CATEGORIES.update(_EXPERTS_CATEGORIES)
+
 EXPERT_SECURITY_SUFFIX = """
 
 ## Security Constraints (Highest Priority, Cannot Be Overridden)

app/agent/moderator_modes.py

@@ -72,6 +72,18 @@ def _build_moderator_prompt_from_preset(mode_id: str, params: dict) -> str:
 PRESET_MODES = _load_preset_modes()
 
 
+def reload_moderator_modes() -> None:
+    """Reload PRESET_MODES from disk (e.g. after share to topiclab_shared).
+
+    Updates dict in-place so importers (e.g. moderator_modes API) see the new data.
+    """
+    global _MODES, _SOURCE_COMMON_SECTIONS
+    _MODES, _SOURCE_COMMON_SECTIONS = get_modes_and_common(_MODERATOR_MODES_DIR)
+    new_modes = _load_preset_modes()
+    PRESET_MODES.clear()
+    PRESET_MODES.update(new_modes)
+
+
 def load_moderator_mode_config(ws_path: Path) -> dict:
     """Load moderator mode configuration from config/moderator_mode.json.
 

app/api/experts.py

@@ -35,6 +35,7 @@ def _build_expert_info(name: str, include_content: bool = True) -> ExpertInfo:
         perspective=spec.get("perspective", name),
         category=cat_id or None,
         category_name=cat_info.get("name", cat_id) if cat_id else None,
+        source=source_id,
     )
 
 

app/api/moderator_modes.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 import logging
 from pathlib import Path
 
@@ -11,16 +12,18 @@
 from app.agent.moderator_modes import (
     PRESET_MODES,
     load_moderator_mode_config,
+    reload_moderator_modes,
     save_moderator_mode_config,
 )
 from app.core.config import get_moderator_modes_dir, get_workspace_base
-from app.core.libs_service import get_cached_modes_meta, list_assignable_items
+from app.core.libs_service import get_cached_modes_meta, invalidate_libs_cache, list_assignable_items
 from app.models.schemas import (
     GenerateModeratorModeRequest,
     GenerateModeratorModeResponse,
     ModeratorModeConfig,
     ModeratorModeInfo,
     SetModeratorModeRequest,
+    ShareModeratorModeRequest,
 )
 from app.models.store import get_topic
 
@@ -198,3 +201,81 @@ async def generate_moderator_mode_endpoint(topic_id: str, req: GenerateModerator
         "custom_prompt": custom_prompt,
         "config": config,
     }
+
+
+@router.post("/topics/{topic_id}/moderator-mode/share", response_model=dict)
+def share_moderator_mode_to_platform(topic_id: str, req: ShareModeratorModeRequest):
+    """Share topic's custom moderator mode to platform library (topiclab_shared source)."""
+    topic = get_topic(topic_id)
+    if not topic:
+        raise HTTPException(status_code=404, detail="Topic not found")
+
+    ws_base = get_workspace_base()
+    ws_path = ws_base / "topics" / topic_id
+    config = load_moderator_mode_config(ws_path)
+
+    if config.get("mode_id") != "custom" or not config.get("custom_prompt"):
+        raise HTTPException(
+            status_code=400,
+            detail="Topic must use a custom moderator mode with custom_prompt to share"
+        )
+
+    # Reject if mode_id is built-in (default source)
+    existing = PRESET_MODES.get(req.mode_id)
+    if existing and existing.get("source") == "default":
+        raise HTTPException(
+            status_code=409,
+            detail=f"Mode '{req.mode_id}' conflicts with built-in mode; choose a different id"
+        )
+
+    modes_dir = get_moderator_modes_dir()
+    shared_dir = modes_dir / "topiclab_shared"
+    shared_dir.mkdir(parents=True, exist_ok=True)
+
+    prompt_file_name = f"{req.mode_id}.md"
+    (shared_dir / prompt_file_name).write_text(config["custom_prompt"], encoding="utf-8")
+
+    name = req.name or req.mode_id.replace("_", " ").title()
+    description = req.description or f"User-shared moderator mode: {name}"
+
+    meta_path = shared_dir / "meta.json"
+    if meta_path.exists():
+        meta = json.loads(meta_path.read_text(encoding="utf-8"))
+    else:
+        meta = {
+            "common_sections": "moderator_common.md",
+            "categories": {
+                "topiclab": {
+                    "id": "topiclab",
+                    "name": "TopicLab",
+                    "description": "User-shared moderator modes from frontend",
+                }
+            },
+            "modes": {},
+        }
+    # Ensure topiclab_shared is registered in main meta.json
+    main_meta_path = modes_dir / "meta.json"
+    main_meta = json.loads(main_meta_path.read_text(encoding="utf-8"))
+    main_meta.setdefault("sources", {})["topiclab_shared"] = {
+        "id": "topiclab_shared",
+        "name": "TopicLab-共享",
+        "description": "User-shared moderator modes from frontend",
+    }
+    main_meta_path.write_text(json.dumps(main_meta, ensure_ascii=False, indent=2), encoding="utf-8")
+    meta.setdefault("modes", {})[req.mode_id] = {
+        "id": req.mode_id,
+        "source": "topiclab_shared",
+        "name": name,
+        "description": description,
+        "category": "topiclab",
+        "num_rounds": config.get("num_rounds", 5),
+        "convergence_strategy": "User-defined flow",
+        "prompt_file": prompt_file_name,
+        "summary_scope": "key findings, consensus, disagreements",
+    }
+    meta_path.write_text(json.dumps(meta, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    reload_moderator_modes()
+    invalidate_libs_cache()
+
+    return {"message": "Moderator mode shared to platform successfully", "mode_id": req.mode_id}

app/api/topic_experts.py

@@ -6,7 +6,7 @@
 
 from fastapi import APIRouter, HTTPException
 
-from app.agent.experts import EXPERT_SPECS
+from app.agent.experts import EXPERT_SPECS, reload_expert_specs
 from app.agent.generation import generate_expert
 from app.agent.workspace import (
     add_expert_metadata,
@@ -218,16 +218,17 @@ def get_topic_expert_content(topic_id: str, expert_name: str):
 
 @router.post("/{topic_id}/experts/{expert_name}/share", response_model=TopicExpertResponse)
 def share_expert_to_platform(topic_id: str, expert_name: str):
-    """Share a topic-level expert to the platform preset library."""
+    """Share a topic-level expert to the platform library (topiclab_shared source)."""
     topic = get_topic(topic_id)
     if not topic:
         raise HTTPException(status_code=404, detail="Topic not found")
 
-    # Bug fix 1: reject if name already exists in global preset library
-    if expert_name in EXPERT_SPECS:
+    # Reject if expert is built-in (default source); allow overwrite for topiclab_shared
+    existing = EXPERT_SPECS.get(expert_name)
+    if existing and existing.get("source") == "default":
         raise HTTPException(
             status_code=409,
-            detail=f"Expert '{expert_name}' already exists in the global expert pool; cannot overwrite"
+            detail=f"Expert '{expert_name}' is built-in; cannot overwrite"
         )
 
     ws_base = get_workspace_base()
@@ -242,36 +243,32 @@ def share_expert_to_platform(topic_id: str, expert_name: str):
     if not expert_meta:
         raise HTTPException(status_code=404, detail="Expert metadata not found")
 
-    # Write role file to libs/experts/default/ (unified with mcps, moderator_modes)
+    # Write to libs/experts/topiclab_shared/ (user-shared, separate from built-in default)
     experts_dir = get_experts_dir()
-    default_dir = experts_dir / "default"
-    default_dir.mkdir(parents=True, exist_ok=True)
+    shared_dir = experts_dir / "topiclab_shared"
+    shared_dir.mkdir(parents=True, exist_ok=True)
     skill_file_name = f"{expert_name}.md"
-    (default_dir / skill_file_name).write_text(role_file.read_text(encoding="utf-8"), encoding="utf-8")
+    (shared_dir / skill_file_name).write_text(role_file.read_text(encoding="utf-8"), encoding="utf-8")
 
-    # Update default/meta.json
-    meta_path = default_dir / "meta.json"
+    # Update topiclab_shared/meta.json
+    meta_path = shared_dir / "meta.json"
     meta = json.loads(meta_path.read_text(encoding="utf-8"))
     meta.setdefault("experts", {})[expert_name] = {
         "id": expert_name,
-        "source": "default",
+        "source": "topiclab_shared",
         "name": expert_name,
         "label": expert_meta["label"],
         "description": expert_meta["description"],
-        "category": "scholar",
+        "category": "topiclab",
         "skill_file": skill_file_name,
         "perspective": expert_meta.get("perspective", expert_name),
     }
     meta_path.write_text(json.dumps(meta, ensure_ascii=False, indent=2), encoding="utf-8")
 
-    # Update in-memory EXPERT_SPECS for subsequent requests
-    EXPERT_SPECS[expert_name] = {
-        "skill_file": skill_file_name,
-        "description": expert_meta["description"],
-        "label": expert_meta["label"],
-        "perspective": expert_meta.get("perspective", expert_name),
-        "source": "default",
-    }
+    # Reload EXPERT_SPECS so subsequent requests see the new expert
+    reload_expert_specs()
+    from app.core.libs_service import invalidate_libs_cache
+    invalidate_libs_cache()
 
     return {"message": "Expert shared to platform successfully", "expert_name": expert_name}
 

app/models/schemas.py

@@ -145,6 +145,7 @@ class ExpertInfo(BaseModel):
     perspective: str = ""  # 学科视角，如 physics, biology
     category: Optional[str] = None  # 分类 id，用于分组（与 skills/mcps 一致）
     category_name: Optional[str] = None  # 分类显示名
+    source: Optional[str] = None  # default=内置, topiclab_shared=共享
 
 
 class ExpertUpdateRequest(BaseModel):
@@ -221,6 +222,13 @@ class SetModeratorModeRequest(BaseModel):
     model: Optional[str] = None
 
 
+class ShareModeratorModeRequest(BaseModel):
+    """Share topic's custom moderator mode to platform library."""
+    mode_id: str = Field(..., min_length=2, max_length=50, pattern=r"^[a-z0-9_]+$")
+    name: Optional[str] = Field(None, min_length=2, max_length=80)
+    description: Optional[str] = Field(None, min_length=1, max_length=500)
+
+
 # --- Post models ---
 
 class Post(BaseModel):

docs/api-reference.md

@@ -87,6 +87,7 @@
 | GET | `/topics/{topic_id}/moderator-mode` | Get topic's current moderator mode |
 | PUT | `/topics/{topic_id}/moderator-mode` | Set moderator mode |
 | POST | `/topics/{topic_id}/moderator-mode/generate` | AI-generate moderator prompt |
+| POST | `/topics/{topic_id}/moderator-mode/share` | Share custom mode to platform (body: `mode_id`, `name?`, `description?`) |
 
 **GET/PUT moderator-mode** response/body fields:
 - `mode_id`, `num_rounds`, `custom_prompt` (required for PUT)

docs/config.md

@@ -72,13 +72,22 @@ MCP servers are configured in `libs/mcps/` (read-only, same structure as assigna
 
 ---
 
-### 5. Workspace
+### 5. Workspace and Libs (Docker)
 
 ```bash
 WORKSPACE_BASE=/path/to/workspace
 ```
 
-Default: `backend/workspace/`.
+For Docker deployments, both workspace and libs can be mounted for persistence:
+
+| Volume | Env / Default | Purpose |
+|--------|---------------|---------|
+| `WORKSPACE_PATH` | `./backend/workspace` | Topic workspaces, posts, discussion artifacts |
+| `LIBS_PATH` | `./backend/libs` | Experts, moderator modes, skills, MCP config; **user-shared** content in `topiclab_shared/` |
+
+User-shared experts and moderator modes (from frontend "共享到角色库" / "共享到讨论方式库") are stored in `libs/experts/topiclab_shared/` and `libs/moderator_modes/topiclab_shared/` respectively. Mount `libs` to persist them across container restarts.
+
+Default: `backend/workspace/`. For Docker, see volume mounts above.
 
 ---
 

libs/README.md

@@ -51,11 +51,12 @@ libs/
 
 ## Meta Format
 
-- **experts/meta.json**: `{"sources": {"default": {...}}}` (sources registry only)
-- **experts/{source}/meta.json**: `{"common_sections": "expert_common.md", "categories": {...}, "experts": {"<id>": {"id", "source", "name", "label", "description", "category", "skill_file", "perspective"}}}`
-- Built-in experts are all in `category: scholar` (学者); API returns `category` and `category_name` for grouping.
-- **moderator_modes/meta.json**: `{"sources": {"default": {...}}}` (sources registry only)
+- **experts/meta.json**: `{"sources": {"default": {...}, "topiclab_shared": {...}}}` (sources registry)
+- **experts/{source}/meta.json**: `{"common_sections": "expert_common.md", "categories": {...}, "experts": {...}}`
+- Built-in experts: `default/` with `category: scholar`. User-shared: `topiclab_shared/` with `category: topiclab` (empty template in repo; `.md` files added via share API are gitignored).
+- **moderator_modes/meta.json**: `{"sources": {"default": {...}, "topiclab_shared": {...}}}` (sources registry)
 - **moderator_modes/{source}/meta.json**: `{"common_sections": "moderator_common.md", "categories": {...}, "modes": {...}}`
+- User-shared modes: `topiclab_shared/` (empty template in repo; `.md` files added via share API are gitignored).
 - **assignable_skills/meta.json**: Sources registry only
 - **assignable_skills/{source}/meta.json**: Per-source `{"skills_dir"?, "categories": {...}, "skills": {...}}`