docs: standardize skill-template and add development guide

scripts/cli/app.py

@@ -0,0 +1,104 @@
+"""CLI：argparse 与分发模板。"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Optional
+
+from service.publish_service import (
+    cmd_health,
+    cmd_log_get,
+    cmd_logs,
+    cmd_publish,
+    cmd_version,
+)
+from util.argparse_zh import ZhArgumentParser
+from util.constants import LOG_LOGGER_NAME, SKILL_SLUG
+from util.logging_config import get_skill_logger, setup_skill_logging
+
+
+def _cli_str_or_none(raw: Optional[str]) -> Optional[str]:
+    if raw is None:
+        return None
+    v = str(raw).strip()
+    return v or None
+
+
+def _handle_publish(args: argparse.Namespace) -> int:
+    tail = [str(x).strip() for x in (args.publish_tail or []) if str(x).strip()]
+    if len(tail) > 2:
+        print("❌ 参数过多。")
+        print("用法：python main.py publish [账号id [文章id]] | publish [-a 账号id] [-i 文章id]")
+        return 1
+
+    t_acc: Optional[str] = None
+    t_art: Optional[str] = None
+    if len(tail) == 2:
+        t_acc, t_art = tail[0], tail[1]
+    elif len(tail) == 1:
+        if tail[0].isdigit():
+            t_art = tail[0]
+        else:
+            t_acc = tail[0]
+
+    pick_a = _cli_str_or_none(getattr(args, "account_id", None))
+    pick_i = _cli_str_or_none(getattr(args, "article_id", None))
+    acc = pick_a or t_acc
+    art = pick_i or t_art
+    return cmd_publish(account_id=acc, article_id=art)
+
+
+def _print_full_usage() -> None:
+    print("模板技能（main.py）可用命令：")
+    print("  python main.py publish [账号id [文章id]] [-a 账号] [-i 文章id]")
+    print("  python main.py logs [--limit N] [--status s] [--account-id a]")
+    print("  python main.py log-get <log_id>")
+    print("  python main.py health")
+    print("  python main.py version")
+
+
+def build_parser() -> ZhArgumentParser:
+    p = ZhArgumentParser(
+        prog="main.py",
+        description="模板技能：发布命令骨架、日志查询、健康检查、版本输出。",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    sub = p.add_subparsers(dest="cmd", required=True, parser_class=ZhArgumentParser)
+
+    sp = sub.add_parser("publish", help="发布型技能命令骨架")
+    sp.add_argument("--account-id", "-a", default=None, metavar="账号id")
+    sp.add_argument("--article-id", "-i", default=None, metavar="文章id")
+    sp.add_argument("publish_tail", nargs="*", metavar="位置参数")
+    sp.set_defaults(handler=_handle_publish)
+
+    sp = sub.add_parser("logs", help="查看发布记录")
+    sp.add_argument("--limit", type=int, default=10)
+    sp.add_argument("--status", default=None)
+    sp.add_argument("--account-id", default=None)
+    sp.set_defaults(handler=lambda a: cmd_logs(limit=a.limit, status=a.status, account_id=a.account_id))
+
+    sp = sub.add_parser("log-get", help="按 log_id 查看单条发布记录(JSON)")
+    sp.add_argument("log_id")
+    sp.set_defaults(handler=lambda a: cmd_log_get(a.log_id))
+
+    sp = sub.add_parser("health", help="健康检查")
+    sp.set_defaults(handler=lambda _a: cmd_health())
+
+    sp = sub.add_parser("version", help="版本信息(JSON)")
+    sp.set_defaults(handler=lambda _a: cmd_version())
+    return p
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    argv = argv if argv is not None else sys.argv[1:]
+    setup_skill_logging(SKILL_SLUG, LOG_LOGGER_NAME)
+    get_skill_logger().info("cli_start argv=%s", sys.argv)
+    if not argv:
+        _print_full_usage()
+        return 1
+    if len(argv) == 2 and argv[0] not in {"publish", "logs", "log-get", "health", "version", "-h", "--help"}:
+        return cmd_publish(account_id=argv[0], article_id=argv[1])
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return int(args.handler(args))