docs: standardize skill-template and add development guide

scripts/jiangchang_skill_core/__init__.py

@@ -0,0 +1 @@
+# Vendored from jiangchang-platform-kit/sdk/jiangchang_skill_core/ — keep runtime_env + unified_logging in sync.

scripts/jiangchang_skill_core/runtime_env.py

@@ -0,0 +1,113 @@
+"""
+JIANGCHANG_* 数据根与用户目录：解析规则 + 可选本地 CLI 默认值。
+
+模板复制后通常无需大改；如组织环境不同，再按项目实际调整。
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+CLI_LOCAL_DEV_ENABLED = True
+DEFAULT_LOCAL_USER_ID = "10032"
+WIN_DEFAULT_DATA_ROOT = r"D:\jiangchang-data"
+WIN_DEFAULT_JIANGCHANG_APP_ROOT = r"D:\AI\jiangchang"
+
+
+def platform_default_data_root() -> str:
+    if sys.platform == "win32":
+        return WIN_DEFAULT_DATA_ROOT
+    return os.path.join(os.path.expanduser("~"), ".jiangchang-data")
+
+
+def get_data_root() -> str:
+    env = (
+        os.getenv("CLAW_DATA_ROOT")
+        or os.getenv("JIANGCHANG_DATA_ROOT")
+        or ""
+    ).strip()
+    if env:
+        return env
+    return platform_default_data_root()
+
+
+def get_user_id() -> str:
+    return (
+        os.getenv("CLAW_USER_ID")
+        or os.getenv("JIANGCHANG_USER_ID")
+        or ""
+    ).strip() or "_anon"
+
+
+def _looks_like_skills_root(path: str) -> bool:
+    if not path or not os.path.isdir(path):
+        return False
+    for marker in (
+        "llm-manager",
+        "content-manager",
+        "account-manager",
+        "sohu-publisher",
+        "toutiao-publisher",
+        "gongzhonghao-publisher",
+        "weibo-publisher",
+        "skill-template",
+    ):
+        if os.path.isdir(os.path.join(path, marker)):
+            return True
+    return False
+
+
+def get_skills_root() -> str:
+    for key in ("JIANGCHANG_SKILLS_ROOT", "CLAW_SKILLS_ROOT"):
+        v = (os.getenv(key) or "").strip()
+        if v:
+            return os.path.normpath(v)
+
+    app = (os.getenv("JIANGCHANG_APP_ROOT") or "").strip()
+    if sys.platform == "win32" and not app:
+        app = WIN_DEFAULT_JIANGCHANG_APP_ROOT
+    if app:
+        nested = os.path.join(app, "skills")
+        if _looks_like_skills_root(nested):
+            return os.path.normpath(nested)
+        if _looks_like_skills_root(app):
+            return os.path.normpath(app)
+
+    if sys.platform == "win32":
+        nested = os.path.join(WIN_DEFAULT_JIANGCHANG_APP_ROOT, "skills")
+        if _looks_like_skills_root(nested):
+            return os.path.normpath(nested)
+        if _looks_like_skills_root(WIN_DEFAULT_JIANGCHANG_APP_ROOT):
+            return os.path.normpath(WIN_DEFAULT_JIANGCHANG_APP_ROOT)
+
+    return os.path.normpath(os.path.join(os.path.expanduser("~"), ".openclaw", "skills"))
+
+
+def get_sibling_skills_root(skill_scripts_dir: str | None = None) -> str:
+    if skill_scripts_dir:
+        scripts = os.path.abspath(skill_scripts_dir)
+        skill_root = os.path.dirname(scripts)
+        inferred = os.path.dirname(skill_root)
+        if _looks_like_skills_root(inferred):
+            return os.path.normpath(inferred)
+
+    for key in ("JIANGCHANG_SKILLS_ROOT", "CLAW_SKILLS_ROOT"):
+        v = (os.getenv(key) or "").strip()
+        if v:
+            return os.path.normpath(v)
+
+    return get_skills_root()
+
+
+def apply_cli_local_defaults() -> None:
+    enabled = CLI_LOCAL_DEV_ENABLED
+    if not enabled:
+        v = (os.getenv("JIANGCHANG_CLI_LOCAL_DEV") or "").strip().lower()
+        enabled = v in ("1", "true", "yes", "on")
+    if not enabled:
+        return
+    if not (os.getenv("CLAW_DATA_ROOT") or os.getenv("JIANGCHANG_DATA_ROOT") or "").strip():
+        os.environ["JIANGCHANG_DATA_ROOT"] = platform_default_data_root()
+    if not (os.getenv("CLAW_USER_ID") or os.getenv("JIANGCHANG_USER_ID") or "").strip():
+        os.environ["JIANGCHANG_USER_ID"] = DEFAULT_LOCAL_USER_ID.strip()

scripts/jiangchang_skill_core/unified_logging.py

@@ -0,0 +1,137 @@
+"""
+统一文件日志：{DATA_ROOT}/{USER_ID}/logs/jiangchang.log
+按日轮转；行内带 trace_id 与 skill_slug，便于跨技能排查。
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+import uuid
+from logging.handlers import TimedRotatingFileHandler
+from typing import Optional
+
+from .runtime_env import get_data_root, get_user_id
+
+_skill_slug: str = ""
+_logger_name: str = ""
+
+
+def get_unified_logs_dir() -> str:
+    path = os.path.join(get_data_root(), get_user_id(), "logs")
+    os.makedirs(path, exist_ok=True)
+    return path
+
+
+def get_skill_log_file_path() -> str:
+    override = (os.getenv("JIANGCHANG_LOG_FILE") or "").strip()
+    if override:
+        parent = os.path.dirname(os.path.abspath(override))
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        return os.path.abspath(override)
+    return os.path.join(get_unified_logs_dir(), "jiangchang.log")
+
+
+def ensure_trace_for_process() -> str:
+    existing = (os.getenv("JIANGCHANG_TRACE_ID") or "").strip()
+    if existing:
+        return existing
+    tid = uuid.uuid4().hex[:12]
+    os.environ["JIANGCHANG_TRACE_ID"] = tid
+    return tid
+
+
+def subprocess_env_with_trace(environ: Optional[dict] = None) -> dict:
+    ensure_trace_for_process()
+    tid = (os.getenv("JIANGCHANG_TRACE_ID") or "").strip() or ensure_trace_for_process()
+    base = os.environ if environ is None else environ
+    return {**base, "JIANGCHANG_TRACE_ID": tid}
+
+
+class _SkillContextFilter(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        record.trace_id = (os.getenv("JIANGCHANG_TRACE_ID") or "").strip() or "-"
+        record.skill_slug = _skill_slug or "-"
+        return True
+
+
+_FORMAT = "%(asctime)s | %(levelname)-8s | %(trace_id)s | %(skill_slug)s | %(name)s | %(message)s"
+_DATEFMT = "%Y-%m-%dT%H:%M:%S"
+
+
+def _log_level_from_env() -> int:
+    v = (os.getenv("JIANGCHANG_LOG_LEVEL") or "INFO").strip().upper()
+    return getattr(logging, v, None) or logging.INFO
+
+
+def _backup_count() -> int:
+    try:
+        n = int((os.getenv("JIANGCHANG_LOG_BACKUP_COUNT") or "30").strip())
+        return max(1, min(n, 365))
+    except ValueError:
+        return 30
+
+
+def setup_skill_logging(skill_slug: str, logger_name: str) -> None:
+    global _skill_slug, _logger_name
+    ensure_trace_for_process()
+    _skill_slug = skill_slug
+    _logger_name = logger_name
+
+    log = logging.getLogger(logger_name)
+    if log.handlers:
+        return
+    log.setLevel(_log_level_from_env())
+    path = get_skill_log_file_path()
+    fh = TimedRotatingFileHandler(
+        path,
+        when="midnight",
+        interval=1,
+        backupCount=_backup_count(),
+        encoding="utf-8",
+        delay=True,
+    )
+    fmt = logging.Formatter(_FORMAT, datefmt=_DATEFMT)
+    fh.setFormatter(fmt)
+    fh.addFilter(_SkillContextFilter())
+    log.addHandler(fh)
+    if (os.getenv("JIANGCHANG_LOG_TO_STDERR") or "").strip().lower() in ("1", "true", "yes", "on"):
+        sh = logging.StreamHandler(sys.stderr)
+        sh.setLevel(logging.WARNING)
+        sh.setFormatter(fmt)
+        sh.addFilter(_SkillContextFilter())
+        log.addHandler(sh)
+    log.propagate = False
+
+
+def get_skill_logger() -> logging.Logger:
+    if not _logger_name:
+        raise RuntimeError("get_skill_logger: call setup_skill_logging first")
+    return logging.getLogger(_logger_name)
+
+
+def attach_unified_file_handler(
+    log_path: str,
+    *,
+    skill_slug: str,
+    logger_name: str,
+    level: int = logging.DEBUG,
+) -> logging.Logger:
+    global _skill_slug
+    ensure_trace_for_process()
+    _skill_slug = skill_slug
+    lg = logging.getLogger(logger_name)
+    lg.handlers.clear()
+    lg.setLevel(level)
+    parent = os.path.dirname(os.path.abspath(log_path))
+    if parent:
+        os.makedirs(parent, exist_ok=True)
+    fh = logging.FileHandler(log_path, encoding="utf-8")
+    fmt = logging.Formatter(_FORMAT, datefmt=_DATEFMT)
+    fh.setFormatter(fmt)
+    fh.addFilter(_SkillContextFilter())
+    lg.addHandler(fh)
+    lg.propagate = False
+    return lg