feat: 项目经费进度播报助手首版 v1.0.1（track-fund-progress-default）

scripts/cli/app.py

@@ -0,0 +1,249 @@
+"""CLI：argparse 与分发（项目经费进度播报助手）。
+
+只负责参数解析并转交 service；业务内核在 fund_service / project_service，
+勿在此按入口复制逻辑。
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Optional
+
+from service.task_service import (
+    cmd_add_project,
+    cmd_broadcast,
+    cmd_broadcast_monthly,
+    cmd_config_path,
+    cmd_health,
+    cmd_import_projects,
+    cmd_init_db,
+    cmd_list_projects,
+    cmd_list_reports,
+    cmd_render_html,
+    cmd_run,
+    cmd_set_rule,
+    cmd_show_report,
+    cmd_stats,
+    cmd_version,
+    cmd_view_rules,
+)
+from util.config_bootstrap import bootstrap_skill_config
+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 _cli_float_or_none(raw: Optional[str]) -> Optional[float]:
+    raw = _cli_str_or_none(raw)
+    if raw is None:
+        return None
+    try:
+        return float(raw)
+    except ValueError:
+        return None
+
+
+def _handle_run(args: argparse.Namespace) -> int:
+    tail = [str(x).strip() for x in (args.run_tail or []) if str(x).strip()]
+    if len(tail) > 2:
+        print("参数过多。")
+        print("用法：python main.py run [target [input_id]] | run [-t target] [-i input_id]")
+        return 1
+
+    t_target: Optional[str] = None
+    t_input: Optional[str] = None
+    if len(tail) == 2:
+        t_target, t_input = tail[0], tail[1]
+    elif len(tail) == 1:
+        if tail[0].isdigit():
+            t_input = tail[0]
+        else:
+            t_target = tail[0]
+
+    pick_t = _cli_str_or_none(getattr(args, "target", None))
+    pick_i = _cli_str_or_none(getattr(args, "input_id", None))
+    target = pick_t or t_target
+    input_id = pick_i or t_input
+    return cmd_run(target=target, input_id=input_id)
+
+
+def _handle_add_project(args: argparse.Namespace) -> int:
+    return cmd_add_project(
+        project_no=str(args.project_no or "").strip(),
+        name=_cli_str_or_none(args.name) or "",
+        project_type=_cli_str_or_none(args.project_type) or "",
+        pi=_cli_str_or_none(args.pi) or "",
+        department=_cli_str_or_none(args.department) or "",
+        total_approved=_cli_float_or_none(args.total_approved),
+        total_received=_cli_float_or_none(args.total_received),
+        total_spent=_cli_float_or_none(args.total_spent),
+        frozen=_cli_float_or_none(args.frozen),
+        frozen_since=_cli_str_or_none(args.frozen_since) or "",
+        start=_cli_str_or_none(args.start) or "",
+        end=_cli_str_or_none(args.end) or "",
+        status=_cli_str_or_none(args.status) or "",
+        remark=_cli_str_or_none(args.remark) or "",
+    )
+
+
+def _handle_broadcast(args: argparse.Namespace) -> int:
+    return cmd_broadcast(
+        project_no=_cli_str_or_none(args.project_no) or "",
+        pi=_cli_str_or_none(args.pi) or "",
+        as_of=_cli_str_or_none(args.as_of) or "",
+        include_all_status=bool(args.all_status),
+    )
+
+
+def _handle_list_reports(args: argparse.Namespace) -> int:
+    return cmd_list_reports(limit=int(args.limit or 20), status_tag=_cli_str_or_none(args.status_tag) or "")
+
+
+def _handle_render_html(args: argparse.Namespace) -> int:
+    report_id = getattr(args, "report_id", None)
+    return cmd_render_html(report_id=int(report_id) if report_id else None)
+
+
+def _handle_set_rule(args: argparse.Namespace) -> int:
+    return cmd_set_rule(rule_key=str(args.rule_key or "").strip(), value=float(args.value))
+
+
+def _print_full_usage() -> None:
+    print("项目经费进度播报助手（main.py）可用命令：")
+    print("  python main.py add-project --project-no X --name Y [--type 纵向] [--pi 张三] [--department 学院]")
+    print("                      [--total-approved N] [--total-received N] [--total-spent N]")
+    print("                      [--frozen N] [--frozen-since DATE] [--start DATE] [--end DATE] [--status 在研]")
+    print("  python main.py import-projects --projects-json <file|->   # 批量 upsert 台账")
+    print("  python main.py list-projects [--pi 张三] [--status 在研]")
+    print("  python main.py broadcast [--project-no X] [--pi 张三] [--as-of YYYY-MM-DD] [--all-status]")
+    print("  python main.py broadcast-monthly                          # 月度播报（定时 Action 入口）")
+    print("  python main.py list-reports [--limit N] [--status-tag 严重滞后]")
+    print("  python main.py show-report --id N")
+    print("  python main.py render-html [--report-id N]")
+    print("  python main.py view-rules")
+    print("  python main.py set-rule --rule-key lag_threshold --value 0.15")
+    print("  python main.py stats")
+    print("  python main.py run [target [input_id]] [-t target] [-i input_id]")
+    print("  python main.py health")
+    print("  python main.py config-path")
+    print("  python main.py version")
+    print("  python main.py init-db")
+
+
+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)
+
+    # add-project
+    sp = sub.add_parser("add-project", help="录入/更新项目台账（按项目编号幂等）")
+    sp.add_argument("--project-no", required=True, metavar="项目编号", dest="project_no")
+    sp.add_argument("--name", default=None, metavar="项目名称")
+    sp.add_argument("--type", default=None, metavar="项目类别(纵向/横向/其他)", dest="project_type")
+    sp.add_argument("--pi", default=None, metavar="负责人")
+    sp.add_argument("--department", default=None, metavar="所属学院")
+    sp.add_argument("--total-approved", default=None, metavar="总立项经费(元)", dest="total_approved")
+    sp.add_argument("--total-received", default=None, metavar="已到账(元)", dest="total_received")
+    sp.add_argument("--total-spent", default=None, metavar="已报销(元)", dest="total_spent")
+    sp.add_argument("--frozen", default=None, metavar="暂付款(元)")
+    sp.add_argument("--frozen-since", default=None, metavar="暂付款最早发生日", dest="frozen_since")
+    sp.add_argument("--start", default=None, metavar="执行期开始 YYYY-MM-DD")
+    sp.add_argument("--end", default=None, metavar="执行期结束 YYYY-MM-DD")
+    sp.add_argument("--status", default=None, metavar="状态(在研/已结题/暂缓)")
+    sp.add_argument("--remark", default=None, metavar="备注")
+    sp.set_defaults(handler=_handle_add_project)
+
+    # import-projects
+    sp = sub.add_parser("import-projects", help="批量导入项目台账（JSON 文件/内联/stdin）")
+    sp.add_argument("--projects-json", required=True, metavar="JSON(file|-)", dest="projects_json")
+    sp.set_defaults(handler=lambda a: cmd_import_projects(str(a.projects_json)))
+
+    # list-projects
+    sp = sub.add_parser("list-projects", help="查询项目台账")
+    sp.add_argument("--pi", default=None, metavar="负责人筛选")
+    sp.add_argument("--status", default=None, metavar="状态筛选")
+    sp.set_defaults(handler=lambda a: cmd_list_projects(pi=_cli_str_or_none(a.pi) or "", status=_cli_str_or_none(a.status) or ""))
+
+    # broadcast
+    sp = sub.add_parser("broadcast", help="经费进度播报（主命令，缺省全部在研项目）")
+    sp.add_argument("--project-no", default=None, metavar="指定项目编号", dest="project_no")
+    sp.add_argument("--pi", default=None, metavar="按负责人筛选")
+    sp.add_argument("--as-of", default=None, metavar="评估基准日 YYYY-MM-DD", dest="as_of")
+    sp.add_argument("--all-status", action="store_true", help="包含非在研项目")
+    sp.set_defaults(handler=_handle_broadcast)
+
+    # broadcast-monthly
+    sp = sub.add_parser("broadcast-monthly", help="月度播报（async Action 入口，含汇总简报）")
+    sp.set_defaults(handler=lambda _a: cmd_broadcast_monthly())
+
+    # list-reports
+    sp = sub.add_parser("list-reports", help="查询播报历史")
+    sp.add_argument("--limit", default=20, metavar="条数")
+    sp.add_argument("--status-tag", default=None, metavar="状态筛选", dest="status_tag")
+    sp.set_defaults(handler=_handle_list_reports)
+
+    # show-report
+    sp = sub.add_parser("show-report", help="查看一份播报记录详情")
+    sp.add_argument("--id", required=True, type=int, metavar="记录编号", dest="report_id")
+    sp.set_defaults(handler=lambda a: cmd_show_report(report_id=int(a.report_id)))
+
+    # render-html
+    sp = sub.add_parser("render-html", help="重建《经费执行简报》HTML（缺省最近 10 份）")
+    sp.add_argument("--report-id", default=None, metavar="记录编号", dest="report_id")
+    sp.set_defaults(handler=_handle_render_html)
+
+    # rules
+    sp = sub.add_parser("view-rules", help="查看预警阈值")
+    sp.set_defaults(handler=lambda _a: cmd_view_rules())
+
+    sp = sub.add_parser("set-rule", help="更新预警阈值")
+    sp.add_argument("--rule-key", required=True, metavar="规则键", dest="rule_key")
+    sp.add_argument("--value", required=True, type=float, metavar="新阈值")
+    sp.set_defaults(handler=_handle_set_rule)
+
+    # stats
+    sp = sub.add_parser("stats", help="播报统计")
+    sp.set_defaults(handler=lambda _a: cmd_stats())
+
+    sp = sub.add_parser("run", help="任务执行命令骨架")
+    sp.add_argument("--target", "-t", default=None, metavar="目标")
+    sp.add_argument("--input-id", "-i", default=None, metavar="输入id", dest="input_id")
+    sp.add_argument("run_tail", nargs="*", metavar="位置参数")
+    sp.set_defaults(handler=_handle_run)
+
+    sp = sub.add_parser("health", help="健康检查")
+    sp.set_defaults(handler=lambda _a: cmd_health())
+
+    sp = sub.add_parser("config-path", help="输出用户 .env 与模板路径")
+    sp.set_defaults(handler=lambda _a: cmd_config_path())
+
+    sp = sub.add_parser("version", help="版本信息(JSON)")
+    sp.set_defaults(handler=lambda _a: cmd_version())
+
+    sp = sub.add_parser("init-db", help="幂等初始化本地数据库与数据管理元数据")
+    sp.set_defaults(handler=lambda _a: cmd_init_db())
+    return p
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    argv = argv if argv is not None else sys.argv[1:]
+    bootstrap_skill_config()
+    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
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return int(args.handler(args))

scripts/db/connection.py

@@ -0,0 +1,252 @@
+"""SQLite 连接与幂等初始化（项目经费进度播报助手）。
+
+业务表 3 张：
+- fund_projects（项目台账，金额/日期/状态字段可编辑）
+- progress_reports（播报记录，只读，播报自动写入）
+- alert_rules（预警规则，阈值可编辑）
+
+表间禁止 SQLite 外键，仅存业务 id（见 references/SCHEMA.md）。
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+from db.display_metadata import (
+    init_display_metadata,
+    seed_column_metadata_batch,
+    upsert_table_metadata,
+)
+from db.seed_data import seed_all
+from db.timestamp_columns import init_updated_at_trigger
+from util.runtime_paths import get_db_path
+
+
+def get_conn() -> sqlite3.Connection:
+    return sqlite3.connect(get_db_path())
+
+
+_FUND_PROJECTS_DDL = """
+CREATE TABLE IF NOT EXISTS fund_projects (
+    id             INTEGER PRIMARY KEY AUTOINCREMENT,
+    project_no     TEXT NOT NULL UNIQUE,
+    project_name   TEXT,
+    project_type   TEXT,
+    pi_name        TEXT,
+    department     TEXT,
+    total_approved REAL,
+    total_received REAL,
+    total_spent    REAL,
+    frozen_amount  REAL,
+    frozen_since   TEXT,
+    start_date     TEXT,
+    end_date       TEXT,
+    status         TEXT NOT NULL DEFAULT '在研',
+    remark         TEXT,
+    created_at     INTEGER NOT NULL DEFAULT (unixepoch()),
+    updated_at     INTEGER NOT NULL DEFAULT (unixepoch())
+)
+"""
+
+_PROGRESS_REPORTS_DDL = """
+CREATE TABLE IF NOT EXISTS progress_reports (
+    id               INTEGER PRIMARY KEY AUTOINCREMENT,
+    batch_no         TEXT NOT NULL,
+    project_id       INTEGER,
+    project_no       TEXT,
+    project_name     TEXT,
+    pi_name          TEXT,
+    as_of            TEXT,
+    spend_rate       REAL,
+    time_progress    REAL,
+    deviation        REAL,
+    status_tag       TEXT NOT NULL,
+    summary          TEXT,
+    suggestions_json TEXT,
+    report_file      TEXT,
+    created_at       INTEGER NOT NULL DEFAULT (unixepoch())
+)
+"""
+
+_PROGRESS_REPORTS_INDEX = """
+CREATE INDEX IF NOT EXISTS idx_progress_reports_batch
+ON progress_reports(batch_no)
+"""
+
+_ALERT_RULES_DDL = """
+CREATE TABLE IF NOT EXISTS alert_rules (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    rule_key        TEXT NOT NULL UNIQUE,
+    display_name    TEXT,
+    threshold_value REAL NOT NULL,
+    description     TEXT,
+    created_at      INTEGER NOT NULL DEFAULT (unixepoch()),
+    updated_at      INTEGER NOT NULL DEFAULT (unixepoch())
+)
+"""
+
+_TS_COLUMN_NAMES = {"created_at", "updated_at"}
+
+
+def _col(column_name: str, display_name: str, description: str, **extra: object) -> dict[str, object]:
+    base: dict[str, object] = {
+        "column_name": column_name,
+        "display_name": display_name,
+        "description": description,
+        "visible": 1,
+        "searchable": 0,
+        "editable": 0,
+    }
+    base.update(extra)
+    if column_name in _TS_COLUMN_NAMES:
+        base["display_type"] = "datetime_unix_seconds"
+    return base
+
+
+_FUND_PROJECTS_COLUMNS: tuple[dict[str, object], ...] = (
+    _col("id", "编号", "主键", searchable=1),
+    _col("project_no", "项目编号", "项目唯一编号（财务/科研系统口径）。", searchable=1),
+    _col("project_name", "项目名称", "项目全称。", searchable=1, editable=1),
+    _col(
+        "project_type",
+        "项目类别",
+        "纵向 / 横向 / 其他。",
+        searchable=1,
+        editable=1,
+        options_json='[{"value":"纵向","label":"纵向"},{"value":"横向","label":"横向"},{"value":"其他","label":"其他"}]',
+    ),
+    _col("pi_name", "负责人", "项目负责人（PI）姓名。", searchable=1, editable=1),
+    _col("department", "所属学院", "二级学院/单位。", searchable=1, editable=1),
+    _col("total_approved", "总立项经费", "立项批复总经费（元）。", searchable=1, editable=1, display_type="number"),
+    _col("total_received", "已到账金额", "已到账经费（元），执行率分母。", searchable=1, editable=1, display_type="number"),
+    _col("total_spent", "已报销金额", "已报销支出（元），执行率分子。", searchable=1, editable=1, display_type="number"),
+    _col("frozen_amount", "冻结/暂付款", "冻结或暂付款金额（元）。", searchable=1, editable=1, display_type="number"),
+    _col("frozen_since", "暂付款最早发生日", "最早一笔暂付款发生日期（YYYY-MM-DD），用于账龄提醒。", editable=1),
+    _col("start_date", "执行期开始", "项目执行期开始日期（YYYY-MM-DD）。", searchable=1, editable=1),
+    _col("end_date", "执行期结束", "项目执行期结束日期（YYYY-MM-DD）。", searchable=1, editable=1),
+    _col(
+        "status",
+        "项目状态",
+        "在研 / 已结题 / 暂缓；播报默认只处理“在研”。",
+        searchable=1,
+        editable=1,
+        options_json='[{"value":"在研","label":"在研"},{"value":"已结题","label":"已结题"},{"value":"暂缓","label":"暂缓"}]',
+    ),
+    _col("remark", "备注", "维护说明。", editable=1),
+    _col("created_at", "创建时间", "记录创建时间（Unix 秒级时间戳，自动生成）。"),
+    _col("updated_at", "更新时间", "记录最后更新时间（Unix 秒级时间戳，自动维护）。"),
+)
+
+_PROGRESS_REPORTS_COLUMNS: tuple[dict[str, object], ...] = (
+    _col("id", "报告编号", "主键，播报记录编号。", searchable=1),
+    _col("batch_no", "播报批次号", "同一次播报请求的批次号。", searchable=1),
+    _col("project_id", "项目编号(id)", "关联项目台账主键。", searchable=1),
+    _col("project_no", "项目编号", "项目唯一编号。", searchable=1),
+    _col("project_name", "项目名称", "项目全称。", searchable=1),
+    _col("pi_name", "负责人", "项目负责人姓名。", searchable=1),
+    _col("as_of", "评估基准日", "本次播报的数据截止日期（YYYY-MM-DD）。", searchable=1),
+    _col("spend_rate", "实际支出率", "已报销/已到账（小数）。", searchable=1, display_type="number"),
+    _col("time_progress", "序时进度", "已过天数/总执行天数（小数）。", searchable=1, display_type="number"),
+    _col("deviation", "偏差", "实际支出率 − 序时进度（小数，正=偏快，负=偏慢）。", searchable=1, display_type="number"),
+    _col(
+        "status_tag",
+        "执行状态",
+        "严重滞后 / 支出异常偏快 / 正常 / 待补录 / 未到账。",
+        searchable=1,
+        options_json='[{"value":"严重滞后","label":"🔴 严重滞后"},{"value":"支出异常偏快","label":"🟠 支出异常偏快"},{"value":"正常","label":"🟢 正常"},{"value":"待补录","label":"⚪ 待补录"},{"value":"未到账","label":"⚪ 未到账"}]',
+    ),
+    _col("summary", "播报摘要", "三段式播报文本（现状/诊断/建议）。", visible=0, display_type="textarea"),
+    _col("suggestions_json", "建议清单", "建议条目（JSON 数组，默认隐藏）。", visible=0, display_type="textarea"),
+    _col("report_file", "简报文件", "《经费执行简报》HTML 文件路径。", visible=0),
+    _col("created_at", "创建时间", "报告创建时间（Unix 秒级时间戳，自动生成）。"),
+)
+
+_ALERT_RULES_COLUMNS: tuple[dict[str, object], ...] = (
+    _col("id", "编号", "主键", searchable=1),
+    _col("rule_key", "规则键", "阈值键名（lag_threshold / overshoot_threshold / pending_aging_days / closing_warn_days）。", searchable=1),
+    _col("display_name", "名称", "阈值中文名。", searchable=1),
+    _col("threshold_value", "阈值", "阈值数值（比例为小数，天数为正整数）。", searchable=1, editable=1, display_type="number"),
+    _col("description", "说明", "阈值口径说明。", searchable=1, editable=1),
+    _col("created_at", "创建时间", "记录创建时间（Unix 秒级，自动生成）。"),
+    _col("updated_at", "更新时间", "记录最后更新时间（Unix 秒级，自动维护）。"),
+)
+
+
+def _init_fund_projects_metadata(cursor) -> None:
+    cursor.execute(_FUND_PROJECTS_DDL)
+    init_updated_at_trigger(cursor, "fund_projects")
+    upsert_table_metadata(
+        cursor,
+        table_name="fund_projects",
+        display_name="项目台账",
+        description="PI 名下项目的基础台账：立项/到账/报销/暂付款与执行周期；播报的数据源。",
+        grid_help="金额单位为元；顶栏按钮可录入项目，行内可直接编辑金额与日期；播报默认只处理“在研”项目。",
+        visible=1,
+        readonly=0,
+        default_sort_json='[{"column":"id","direction":"desc"}]',
+        default_visible_columns_json='["project_no","project_name","pi_name","department","total_approved","total_received","total_spent","status"]',
+    )
+    seed_column_metadata_batch(
+        cursor,
+        table_name="fund_projects",
+        columns=_FUND_PROJECTS_COLUMNS,
+        valid_column_names=[str(c["column_name"]) for c in _FUND_PROJECTS_COLUMNS],
+    )
+
+
+def _init_progress_reports_metadata(cursor) -> None:
+    cursor.execute(_PROGRESS_REPORTS_DDL)
+    cursor.execute(_PROGRESS_REPORTS_INDEX)
+    upsert_table_metadata(
+        cursor,
+        table_name="progress_reports",
+        display_name="播报记录",
+        description="每次播报的项目执行状态、偏差与三段式摘要；可重建 HTML 简报。",
+        grid_help="“严重滞后/支出异常偏快”的行建议由科研秘书或财务处跟进；简报可用顶栏按钮重建。",
+        visible=1,
+        readonly=1,
+        default_sort_json='[{"column":"id","direction":"desc"}]',
+        default_visible_columns_json='["id","as_of","project_no","project_name","pi_name","spend_rate","time_progress","deviation","status_tag"]',
+    )
+    seed_column_metadata_batch(
+        cursor,
+        table_name="progress_reports",
+        columns=_PROGRESS_REPORTS_COLUMNS,
+        valid_column_names=[str(c["column_name"]) for c in _PROGRESS_REPORTS_COLUMNS],
+    )
+
+
+def _init_alert_rules_metadata(cursor) -> None:
+    cursor.execute(_ALERT_RULES_DDL)
+    init_updated_at_trigger(cursor, "alert_rules")
+    upsert_table_metadata(
+        cursor,
+        table_name="alert_rules",
+        display_name="预警规则",
+        description="偏差诊断与提醒阈值（严重滞后/异常偏快/暂付款账龄/结题预警）。",
+        grid_help="比例为小数（0.10=10个百分点），天数为正整数；修改后下一次播报即生效。",
+        visible=1,
+        readonly=0,
+    )
+    seed_column_metadata_batch(
+        cursor,
+        table_name="alert_rules",
+        columns=_ALERT_RULES_COLUMNS,
+        valid_column_names=[str(c["column_name"]) for c in _ALERT_RULES_COLUMNS],
+    )
+
+
+def init_db() -> dict[str, int]:
+    """幂等创建/迁移本地 SQLite、数据管理元数据与业务种子，返回种子统计。"""
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        init_display_metadata(cur)
+        _init_fund_projects_metadata(cur)
+        _init_progress_reports_metadata(cur)
+        _init_alert_rules_metadata(cur)
+        seeded = seed_all(cur)
+        conn.commit()
+        return seeded
+    finally:
+        conn.close()

scripts/db/display_metadata.py

@@ -0,0 +1,324 @@
+"""匠厂数据管理展示元数据（_jiangchang_tables / _jiangchang_columns）。
+
+SQLite 无原生表/字段 COMMENT；中文展示名称通过这两张元数据表提供给宿主「数据管理」页面。
+字段在界面上的顺序由 CREATE TABLE / PRAGMA table_info(cid) 决定，**不**使用 display_order 排序。
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+# 宿主会隐藏这些表，不作为业务表展示（见 jiangchang electron/data-management/types.ts）
+INTERNAL_METADATA_TABLES = frozenset({"_jiangchang_tables", "_jiangchang_columns"})
+LEGACY_METADATA_TABLES = frozenset({"_schema_meta"})
+METADATA_TABLES = INTERNAL_METADATA_TABLES | LEGACY_METADATA_TABLES
+
+DATETIME_UNIX_SECONDS = "datetime_unix_seconds"
+STANDARD_TIMESTAMP_COLUMNS = frozenset({"created_at", "updated_at"})
+
+_JIANGCHANG_TABLES_DDL = """
+CREATE TABLE IF NOT EXISTS _jiangchang_tables (
+    table_name TEXT PRIMARY KEY,
+    display_name TEXT NOT NULL,
+    description TEXT,
+    grid_help TEXT,
+    sort_order INTEGER,
+    visible INTEGER NOT NULL DEFAULT 1,
+    readonly INTEGER NOT NULL DEFAULT 0,
+    default_sort_json TEXT,
+    default_visible_columns_json TEXT
+)
+"""
+
+_JIANGCHANG_COLUMNS_DDL = """
+CREATE TABLE IF NOT EXISTS _jiangchang_columns (
+    table_name TEXT NOT NULL,
+    column_name TEXT NOT NULL,
+    display_name TEXT NOT NULL,
+    description TEXT,
+    grid_help TEXT,
+    display_order INTEGER,
+    visible INTEGER NOT NULL DEFAULT 1,
+    searchable INTEGER NOT NULL DEFAULT 1,
+    editable INTEGER NOT NULL DEFAULT 1,
+    display_type TEXT,
+    options_json TEXT,
+    PRIMARY KEY (table_name, column_name)
+)
+"""
+
+def _pragma_column_names(cursor, table_name: str) -> set[str]:
+    cursor.execute(f"PRAGMA table_info({table_name!r})")
+    return {str(row[1]) for row in cursor.fetchall()}
+
+
+def _ensure_jiangchang_tables_columns(cursor) -> None:
+    """旧库补列：CREATE IF NOT EXISTS 不会给已有表加新字段。"""
+    cols = _pragma_column_names(cursor, "_jiangchang_tables")
+    if "default_sort_json" not in cols:
+        cursor.execute("ALTER TABLE _jiangchang_tables ADD COLUMN default_sort_json TEXT")
+    if "default_visible_columns_json" not in cols:
+        cursor.execute(
+            "ALTER TABLE _jiangchang_tables ADD COLUMN default_visible_columns_json TEXT"
+        )
+    if "grid_help" not in cols:
+        cursor.execute("ALTER TABLE _jiangchang_tables ADD COLUMN grid_help TEXT")
+
+
+def _ensure_jiangchang_columns_columns(cursor) -> None:
+    cols = _pragma_column_names(cursor, "_jiangchang_columns")
+    if "grid_help" not in cols:
+        cursor.execute("ALTER TABLE _jiangchang_columns ADD COLUMN grid_help TEXT")
+
+
+def init_display_metadata_tables(cursor) -> None:
+    cursor.execute(_JIANGCHANG_TABLES_DDL)
+    cursor.execute(_JIANGCHANG_COLUMNS_DDL)
+    _ensure_jiangchang_tables_columns(cursor)
+    _ensure_jiangchang_columns_columns(cursor)
+
+
+def upsert_table_metadata(
+    cursor,
+    *,
+    table_name: str,
+    display_name: str,
+    description: str | None = None,
+    grid_help: str | None = None,
+    visible: int = 1,
+    readonly: int = 0,
+    default_sort_json: str | None = None,
+    default_visible_columns_json: str | None = None,
+) -> None:
+    """写入表级元数据。
+
+    default_sort_json: 宿主数据管理默认排序，JSON 数组，例如
+    '[{"column":"sent_at","direction":"desc"},{"column":"id","direction":"desc"}]'
+    为空则宿主回退到 updated_at → created_at → 主键。
+
+    default_visible_columns_json: 宿主数据管理默认展示列，JSON 字符串数组，例如
+    '["stat_type","period","stage"]'
+    为空则全显；用户改过「列」后以本机偏好为准（软默认，区别于 visible=0 硬隐藏）。
+
+    grid_help: 数据管理表格上方说明；空则不出横幅。与表单用的 description 独立，禁止互拷。
+    """
+    cursor.execute(
+        """
+        INSERT INTO _jiangchang_tables (
+            table_name, display_name, description, grid_help, visible, readonly,
+            default_sort_json, default_visible_columns_json
+        )
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(table_name) DO UPDATE SET
+            display_name = excluded.display_name,
+            description = excluded.description,
+            grid_help = excluded.grid_help,
+            visible = excluded.visible,
+            readonly = excluded.readonly,
+            default_sort_json = excluded.default_sort_json,
+            default_visible_columns_json = excluded.default_visible_columns_json
+        """,
+        (
+            table_name,
+            display_name,
+            description,
+            grid_help,
+            visible,
+            readonly,
+            default_sort_json,
+            default_visible_columns_json,
+        ),
+    )
+
+
+def upsert_column_metadata(
+    cursor,
+    *,
+    table_name: str,
+    column_name: str,
+    display_name: str,
+    description: str | None = None,
+    grid_help: str | None = None,
+    visible: int = 1,
+    searchable: int = 1,
+    editable: int = 1,
+    display_type: str | None = None,
+    options_json: str | None = None,
+) -> None:
+    # display_order 保留为 NULL：宿主按 PRAGMA table_info cid 展示字段，不读 display_order。
+    # grid_help: 表头「?」；空则不出。与表单用的 description 独立，禁止互拷。
+    cursor.execute(
+        """
+        INSERT INTO _jiangchang_columns (
+            table_name, column_name, display_name, description, grid_help,
+            display_order, visible, searchable, editable, display_type, options_json
+        )
+        VALUES (?, ?, ?, ?, ?, NULL, ?, ?, ?, ?, ?)
+        ON CONFLICT(table_name, column_name) DO UPDATE SET
+            display_name = excluded.display_name,
+            description = excluded.description,
+            grid_help = excluded.grid_help,
+            display_order = NULL,
+            visible = excluded.visible,
+            searchable = excluded.searchable,
+            editable = excluded.editable,
+            display_type = excluded.display_type,
+            options_json = excluded.options_json
+        """,
+        (
+            table_name,
+            column_name,
+            display_name,
+            description,
+            grid_help,
+            visible,
+            searchable,
+            editable,
+            display_type,
+            options_json,
+        ),
+    )
+
+
+def seed_column_metadata_batch(
+    cursor,
+    *,
+    table_name: str,
+    columns: Iterable[dict[str, object]],
+    valid_column_names: Iterable[str] | None = None,
+) -> None:
+    """批量 upsert 字段元数据；传入 valid_column_names 时会在 upsert 后清理陈旧字段元数据。"""
+    for column in columns:
+        upsert_column_metadata(
+            cursor,
+            table_name=table_name,
+            column_name=str(column["column_name"]),
+            display_name=str(column["display_name"]),
+            description=str(column["description"]) if column.get("description") else None,
+            grid_help=str(column["grid_help"]) if column.get("grid_help") else None,
+            visible=int(column.get("visible", 1)),
+            searchable=int(column.get("searchable", 1)),
+            editable=int(column.get("editable", 1)),
+            display_type=str(column["display_type"]) if column.get("display_type") else None,
+            options_json=str(column["options_json"]) if column.get("options_json") else None,
+        )
+    if valid_column_names is not None:
+        prune_stale_column_metadata(cursor, table_name, valid_column_names)
+
+
+def prune_stale_column_metadata(cursor, table_name: str, valid_column_names: Iterable[str]) -> None:
+    """删除表中已不存在物理字段的元数据行（幂等初始化后不得残留旧字段）。"""
+    valid = set(valid_column_names)
+    cursor.execute(
+        "SELECT column_name FROM _jiangchang_columns WHERE table_name = ?",
+        (table_name,),
+    )
+    for (column_name,) in cursor.fetchall():
+        if str(column_name) not in valid:
+            cursor.execute(
+                "DELETE FROM _jiangchang_columns WHERE table_name = ? AND column_name = ?",
+                (table_name, column_name),
+            )
+
+
+def get_table_readonly(cursor, table_name: str) -> int | None:
+    cursor.execute(
+        "SELECT readonly FROM _jiangchang_tables WHERE table_name = ?",
+        (table_name,),
+    )
+    row = cursor.fetchone()
+    if not row:
+        return None
+    return int(row[0] or 0)
+
+
+def get_column_editable(cursor, table_name: str, column_name: str) -> int | None:
+    cursor.execute(
+        """
+        SELECT editable FROM _jiangchang_columns
+        WHERE table_name = ? AND column_name = ?
+        """,
+        (table_name, column_name),
+    )
+    row = cursor.fetchone()
+    if not row:
+        return None
+    return int(row[0] or 0)
+
+
+def list_editable_business_columns(cursor, table_name: str) -> list[str]:
+    """返回 editable=1 的业务字段名（不含宿主侧主键/generated 等二次过滤）。"""
+    physical = list_physical_column_names(cursor, table_name)
+    cursor.execute(
+        """
+        SELECT column_name, editable
+        FROM _jiangchang_columns
+        WHERE table_name = ?
+        """,
+        (table_name,),
+    )
+    editable_set = {
+        str(column_name)
+        for column_name, editable in cursor.fetchall()
+        if editable is not None and int(editable) == 1
+    }
+    return [name for name in physical if name in editable_set]
+
+
+def table_allows_manual_create(cursor, table_name: str) -> bool:
+    """表级 readonly=0 且至少有一个 editable=1 字段时，宿主才应提供空白新增表单。"""
+    readonly = get_table_readonly(cursor, table_name)
+    if readonly is None or int(readonly) != 0:
+        return False
+    return bool(list_editable_business_columns(cursor, table_name))
+
+
+def init_display_metadata(cursor) -> None:
+    init_display_metadata_tables(cursor)
+
+
+def drop_deprecated_user_table(
+    cursor,
+    table_name: str,
+    *,
+    triggers: Iterable[str] | None = None,
+) -> None:
+    """永久退役用户可见表：删 trigger、DROP 物理表、清理展示元数据（幂等）。
+
+    用于废弃 task_logs 等旧表。禁止只删元数据而保留物理表。
+    见 references/SCHEMA.md「表增删改与退役」。
+    """
+    for trigger_name in triggers or ():
+        cursor.execute(f"DROP TRIGGER IF EXISTS {trigger_name}")
+    default_updated_at = f"{table_name}_set_updated_at"
+    cursor.execute(f"DROP TRIGGER IF EXISTS {default_updated_at}")
+    cursor.execute(f"DROP TABLE IF EXISTS {_quote_identifier(table_name)}")
+    cursor.execute(
+        "DELETE FROM _jiangchang_columns WHERE table_name = ?",
+        (table_name,),
+    )
+    cursor.execute(
+        "DELETE FROM _jiangchang_tables WHERE table_name = ?",
+        (table_name,),
+    )
+
+
+def iter_user_tables(cursor) -> Iterable[str]:
+    cursor.execute(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name"
+    )
+    for (name,) in cursor.fetchall():
+        if name in METADATA_TABLES:
+            continue
+        yield str(name)
+
+
+def _quote_identifier(name: str) -> str:
+    return '"' + name.replace('"', '""') + '"'
+
+
+def list_physical_column_names(cursor, table_name: str) -> list[str]:
+    cursor.execute(f"PRAGMA table_info({_quote_identifier(table_name)})")
+    rows = cursor.fetchall()
+    rows.sort(key=lambda row: int(row[0]))
+    return [str(row[1]) for row in rows]

scripts/db/display_metadata_validator.py

@@ -0,0 +1,592 @@
+"""数据管理展示元数据校验（模板开发自检，不依赖宿主）。"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sqlite3
+from dataclasses import dataclass, field
+
+from db.display_metadata import (
+    DATETIME_UNIX_SECONDS,
+    METADATA_TABLES,
+    STANDARD_TIMESTAMP_COLUMNS,
+    iter_user_tables,
+    list_editable_business_columns,
+    list_physical_column_names,
+    table_allows_manual_create,
+)
+from db.timestamp_columns import has_updated_at_trigger
+from util.constants import SKILL_SLUG
+from util.slug_naming import LEGACY_EXEMPT_SLUGS, validate_slug_semantics
+
+_TEMPLATE_PLACEHOLDER_SLUGS = frozenset({"your-skill-slug", "your_skill_slug"})
+_ENGLISH_PLACEHOLDER_NAME_PATTERNS = (
+    re.compile(r"^my\s+skill$", re.I),
+    re.compile(r"^your[-_\s]?skill", re.I),
+    re.compile(r"^skill[-_\s]?template$", re.I),
+    re.compile(r"^[a-z0-9_-]+$"),
+)
+_KEBAB_SLUG = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+_CJK_RE = re.compile(r"[\u4e00-\u9fff]")
+_FK_DDL_PATTERN = re.compile(r"\bFOREIGN\s+KEY\b|\bREFERENCES\b", re.I)
+
+
+@dataclass
+class ValidationReport:
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+
+def _has_cjk(text: str) -> bool:
+    return bool(_CJK_RE.search(text))
+
+
+def _looks_like_raw_physical_name(display_name: str, physical_name: str) -> bool:
+    if not display_name.strip():
+        return True
+    if display_name.strip().lower() == physical_name.strip().lower():
+        return True
+    compact = display_name.replace(" ", "").replace("_", "").lower()
+    if compact == physical_name.replace("_", "").lower():
+        return True
+    return False
+
+
+def _parse_frontmatter_field(text: str, field_name: str) -> str:
+    parts = text.split("---", 2)
+    if len(parts) < 2:
+        return ""
+    for line in parts[1].splitlines():
+        match = re.match(rf"^{re.escape(field_name)}:\s*(.+)\s*$", line.strip())
+        if match:
+            return match.group(1).strip().strip("\"'")
+    return ""
+
+
+def _parse_openclaw_slug(text: str) -> str:
+    parts = text.split("---", 2)
+    if len(parts) < 2:
+        return ""
+    lines = parts[1].splitlines()
+    for index, line in enumerate(lines):
+        if re.match(r"^\s+openclaw:\s*$", line):
+            for inner in lines[index + 1 :]:
+                if inner.strip() and inner[0] not in (" ", "\t"):
+                    break
+                match = re.match(r"^(\s+)slug:\s*(.+)\s*$", inner)
+                if match:
+                    return match.group(2).strip().strip("\"'")
+    return ""
+
+
+def parse_skill_frontmatter(skill_root: str) -> dict[str, str]:
+    path = os.path.join(skill_root, "SKILL.md")
+    with open(path, encoding="utf-8") as f:
+        text = f.read()
+    return {
+        "name": _parse_frontmatter_field(text, "name"),
+        "slug": _parse_openclaw_slug(text),
+    }
+
+
+def validate_skill_frontmatter(skill_root: str, *, allow_template_placeholders: bool = True) -> ValidationReport:
+    report = ValidationReport()
+    data = parse_skill_frontmatter(skill_root)
+    name = str(data.get("name") or "").strip()
+    slug = str(data.get("slug") or "").strip()
+
+    if not name:
+        report.errors.append("SKILL.md frontmatter.name 缺失")
+    elif not _has_cjk(name):
+        if allow_template_placeholders and slug in _TEMPLATE_PLACEHOLDER_SLUGS:
+            report.warnings.append("SKILL.md frontmatter.name 建议使用清晰的中文业务名称（模板占位可暂保留）")
+        else:
+            report.errors.append("SKILL.md frontmatter.name 应使用用户可见的中文业务名称")
+    else:
+        for pattern in _ENGLISH_PLACEHOLDER_NAME_PATTERNS:
+            if pattern.fullmatch(name):
+                if allow_template_placeholders and slug in _TEMPLATE_PLACEHOLDER_SLUGS:
+                    report.warnings.append(f"SKILL.md frontmatter.name 仍为占位风格：{name!r}")
+                else:
+                    report.errors.append(f"SKILL.md frontmatter.name 不应为英文占位名：{name!r}")
+                break
+
+    if not slug:
+        report.errors.append("SKILL.md metadata.openclaw.slug 缺失")
+    elif not _KEBAB_SLUG.fullmatch(slug):
+        report.errors.append(f"metadata.openclaw.slug 必须为 kebab-case：{slug!r}")
+    elif slug in _TEMPLATE_PLACEHOLDER_SLUGS and not allow_template_placeholders:
+        report.errors.append(f"metadata.openclaw.slug 仍为模板占位：{slug!r}")
+
+    constants_slug = SKILL_SLUG.strip()
+    if slug and constants_slug and slug != constants_slug:
+        report.warnings.append(
+            f"SKILL.md slug ({slug!r}) 与 util.constants.SKILL_SLUG ({constants_slug!r}) 不一致"
+        )
+
+    if slug and slug not in LEGACY_EXEMPT_SLUGS and _KEBAB_SLUG.fullmatch(slug):
+        naming_errors, naming_warnings = validate_slug_semantics(
+            slug,
+            strict=not allow_template_placeholders,
+        )
+        report.errors.extend(naming_errors)
+        report.warnings.extend(naming_warnings)
+
+    return report
+
+
+def _quote_identifier(name: str) -> str:
+    return '"' + name.replace('"', '""') + '"'
+
+
+def _table_column_info(cursor, table_name: str) -> dict[str, dict[str, object]]:
+    cursor.execute(f"PRAGMA table_info({_quote_identifier(table_name)})")
+    info: dict[str, dict[str, object]] = {}
+    for row in cursor.fetchall():
+        info[str(row[1])] = {
+            "cid": int(row[0]),
+            "name": str(row[1]),
+            "type": str(row[2] or ""),
+            "notnull": int(row[3] or 0),
+            "dflt_value": row[4],
+            "pk": int(row[5] or 0),
+        }
+    return info
+
+
+def _table_column_xinfo(cursor, table_name: str) -> dict[str, dict[str, object]]:
+    """PRAGMA table_xinfo 可识别 generated/hidden 字段（SQLite 3.31+）。"""
+    cursor.execute(f"PRAGMA table_xinfo({_quote_identifier(table_name)})")
+    info: dict[str, dict[str, object]] = {}
+    for row in cursor.fetchall():
+        hidden = int(row[6] or 0) if len(row) > 6 else 0
+        info[str(row[1])] = {
+            "cid": int(row[0]),
+            "name": str(row[1]),
+            "type": str(row[2] or ""),
+            "notnull": int(row[3] or 0),
+            "dflt_value": row[4],
+            "pk": int(row[5] or 0),
+            "hidden": hidden,
+        }
+    return info
+
+
+def _is_generated_column(xinfo: dict[str, object]) -> bool:
+    hidden = int(xinfo.get("hidden") or 0)
+    return hidden in (2, 3)
+
+
+def _is_blob_column(column_info: dict[str, object]) -> bool:
+    return "BLOB" in str(column_info.get("type") or "").upper()
+
+
+def _default_uses_unixepoch(default_value: object) -> bool:
+    if default_value is None:
+        return False
+    text = str(default_value).strip().lower()
+    return "unixepoch" in text
+
+
+def validate_options_json(options_json: str | None) -> tuple[list[str], list[str]]:
+    """校验 options_json：静态枚举数组，或 lookup 对象。"""
+    errors: list[str] = []
+    warnings: list[str] = []
+    if options_json is None or str(options_json).strip() == "":
+        return errors, warnings
+    try:
+        parsed = json.loads(str(options_json))
+    except json.JSONDecodeError as exc:
+        errors.append(f"options_json 不是合法 JSON：{exc}")
+        return errors, warnings
+
+    if isinstance(parsed, dict):
+        for key in ("ref_table", "value_column", "label_column"):
+            if not str(parsed.get(key) or "").strip():
+                errors.append(f"options_json lookup 必须包含非空 {key}")
+        ident = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+        for key in ("ref_table", "value_column", "label_column", "filter_column"):
+            raw = parsed.get(key)
+            if raw is None or raw == "":
+                continue
+            if not ident.match(str(raw)):
+                errors.append(f"options_json.{key} 必须是安全标识符，当前为 {raw!r}")
+        if parsed.get("filter_column") not in (None, "") and "filter_value" not in parsed:
+            warnings.append("options_json lookup 声明了 filter_column 但未提供 filter_value")
+        if "multiple" in parsed and not isinstance(parsed.get("multiple"), bool):
+            errors.append("options_json lookup.multiple 必须是布尔值")
+        return errors, warnings
+
+    if not isinstance(parsed, list):
+        errors.append("options_json 必须是 JSON 数组（静态枚举）或对象（lookup）")
+        return errors, warnings
+    for index, item in enumerate(parsed):
+        if not isinstance(item, dict):
+            errors.append(f"options_json[{index}] 必须是对象")
+            continue
+        if "value" not in item or "label" not in item:
+            errors.append(f"options_json[{index}] 必须包含 value 与 label")
+    return errors, warnings
+
+
+def validate_filter_search_metadata(
+    cursor,
+    table_name: str,
+) -> tuple[list[str], list[str]]:
+    """对可见但未开启 searchable 的枚举 / boolean 列给出软建议。"""
+    warnings: list[str] = []
+    cursor.execute(
+        """
+        SELECT column_name, visible, searchable, display_type, options_json
+        FROM _jiangchang_columns
+        WHERE table_name = ?
+        """,
+        (table_name,),
+    )
+    for column_name, visible, searchable, display_type, options_json in cursor.fetchall():
+        if visible is not None and int(visible) == 0:
+            continue
+        if searchable is not None and int(searchable) != 0:
+            continue
+
+        display_type_norm = str(display_type or "").strip()
+        is_boolean = display_type_norm == "boolean"
+
+        has_enum = False
+        if options_json is not None and str(options_json).strip():
+            opt_errors, _ = validate_options_json(options_json)
+            if not opt_errors:
+                try:
+                    parsed = json.loads(str(options_json))
+                except json.JSONDecodeError:
+                    parsed = None
+                has_enum = isinstance(parsed, list) and len(parsed) > 0
+
+        if not has_enum and not is_boolean:
+            continue
+
+        warnings.append(
+            f"{table_name}.{column_name}: 枚举/状态类列建议 searchable=1，"
+            "以便宿主列筛选与按中文 label 全局搜索（见 references/SCHEMA.md）"
+        )
+
+    return [], warnings
+
+
+def validate_column_permissions(
+    cursor,
+    table_name: str,
+    *,
+    physical_columns: list[str] | None = None,
+) -> tuple[list[str], list[str]]:
+    """校验常见系统字段 editable=0，并识别技术上可写但不适合手工新增的表。"""
+    errors: list[str] = []
+    warnings: list[str] = []
+    ordered = physical_columns or list_physical_column_names(cursor, table_name)
+    column_info = _table_column_info(cursor, table_name)
+    column_xinfo = _table_column_xinfo(cursor, table_name)
+
+    cursor.execute(
+        """
+        SELECT column_name, editable, options_json
+        FROM _jiangchang_columns
+        WHERE table_name = ?
+        """,
+        (table_name,),
+    )
+    meta_by_column = {
+        str(row[0]): {"editable": row[1], "options_json": row[2]}
+        for row in cursor.fetchall()
+    }
+
+    for column_name, meta in meta_by_column.items():
+        physical = column_info.get(column_name) or {}
+        xinfo = column_xinfo.get(column_name) or physical
+        if not physical and column_name not in column_xinfo:
+            continue
+
+        pk = int(physical.get("pk") or xinfo.get("pk") or 0)
+        editable = meta["editable"]
+        if pk and editable is not None and int(editable) != 0:
+            errors.append(f"{table_name}.{column_name} 是主键，editable 应为 0")
+
+        if column_name == "id" and editable is not None and int(editable) != 0:
+            errors.append(f"{table_name}.id 的 editable 应为 0（自增主键）")
+
+        if _is_generated_column(xinfo) and editable is not None and int(editable) != 0:
+            errors.append(f"{table_name}.{column_name} 是 generated 字段，editable 应为 0")
+
+        if _is_blob_column(physical or xinfo) and editable is not None and int(editable) != 0:
+            errors.append(f"{table_name}.{column_name} 是 BLOB 字段，editable 应为 0")
+
+        opt_errors, _ = validate_options_json(meta.get("options_json"))
+        for item in opt_errors:
+            errors.append(f"{table_name}.{column_name}: {item}")
+
+    cursor.execute(
+        "SELECT readonly FROM _jiangchang_tables WHERE table_name = ?",
+        (table_name,),
+    )
+    readonly_row = cursor.fetchone()
+    readonly = int(readonly_row[0]) if readonly_row else None
+    editable_columns = list_editable_business_columns(cursor, table_name)
+    if readonly == 0 and not editable_columns:
+        warnings.append(
+            f"{table_name}: 表级 readonly=0 但所有字段 editable=0，"
+            "宿主不应打开空白新增表单；数据应由技能业务流程产生"
+        )
+    if readonly == 1 and editable_columns:
+        warnings.append(
+            f"{table_name}: 表级 readonly=1 但存在 editable=1 字段，"
+            "宿主应以表级只读为准"
+        )
+
+    return errors, warnings
+
+
+def _expected_timestamp_display_name(column_name: str) -> str:
+    if column_name == "created_at":
+        return "创建时间"
+    if column_name == "updated_at":
+        return "更新时间"
+    return ""
+
+
+def validate_standard_timestamp_columns(
+    cursor,
+    table_name: str,
+    *,
+    physical_columns: list[str] | None = None,
+) -> tuple[list[str], list[str]]:
+    errors: list[str] = []
+    warnings: list[str] = []
+    ordered = physical_columns or list_physical_column_names(cursor, table_name)
+    column_info = _table_column_info(cursor, table_name)
+
+    for column_name in STANDARD_TIMESTAMP_COLUMNS:
+        if column_name not in ordered:
+            continue
+
+        physical = column_info.get(column_name)
+        if not physical:
+            errors.append(f"{table_name}.{column_name} 缺少物理字段定义")
+            continue
+
+        if "INT" not in str(physical["type"]).upper():
+            errors.append(
+                f"{table_name}.{column_name} 字段类型应为 INTEGER（Unix 秒级时间戳），当前为 {physical['type']!r}"
+            )
+
+        if column_name == "created_at" and not _default_uses_unixepoch(physical["dflt_value"]):
+            errors.append(
+                f"{table_name}.created_at 应设置数据库默认值 DEFAULT (unixepoch())，当前默认值为 {physical['dflt_value']!r}"
+            )
+        if column_name == "updated_at" and not _default_uses_unixepoch(physical["dflt_value"]):
+            errors.append(
+                f"{table_name}.updated_at 应设置数据库初始默认值 DEFAULT (unixepoch())，当前默认值为 {physical['dflt_value']!r}"
+            )
+
+        cursor.execute(
+            """
+            SELECT display_name, display_type, editable, searchable, display_order
+            FROM _jiangchang_columns
+            WHERE table_name = ? AND column_name = ?
+            """,
+            (table_name, column_name),
+        )
+        meta_row = cursor.fetchone()
+        if not meta_row:
+            errors.append(f"{table_name}.{column_name} 缺少 _jiangchang_columns 元数据")
+            continue
+
+        display_name, display_type, editable, searchable, display_order = meta_row
+        expected_name = _expected_timestamp_display_name(column_name)
+        if str(display_name or "").strip() != expected_name:
+            errors.append(
+                f"{table_name}.{column_name} 的 display_name 应为 {expected_name!r}，当前为 {display_name!r}"
+            )
+        if str(display_type or "").strip() != DATETIME_UNIX_SECONDS:
+            errors.append(
+                f"{table_name}.{column_name} 的 display_type 应为 {DATETIME_UNIX_SECONDS!r}，当前为 {display_type!r}"
+            )
+        if editable is None or int(editable) != 0:
+            errors.append(f"{table_name}.{column_name} 的 editable 应为 0（系统时间字段不可编辑）")
+        if display_order is not None:
+            errors.append(f"{table_name}.{column_name} 的 display_order 应为 NULL")
+        if searchable is not None and int(searchable) != 0:
+            warnings.append(f"{table_name}.{column_name} 的时间字段通常不必开启 searchable")
+
+    if "created_at" in ordered and "updated_at" in ordered:
+        if ordered.index("updated_at") < ordered.index("created_at"):
+            warnings.append(f"{table_name}: updated_at 不应出现在 created_at 之前")
+
+    if "updated_at" in ordered and not has_updated_at_trigger(cursor, table_name):
+        errors.append(
+            f"{table_name}.updated_at 缺少自动维护 trigger（期望 {table_name}_set_updated_at）"
+        )
+
+    return errors, warnings
+
+
+def column_order_warnings(table_name: str, ordered_names: list[str]) -> list[str]:
+    warnings: list[str] = []
+    if "id" in ordered_names and ordered_names.index("id") != 0:
+        warnings.append(f"{table_name}: 字段 id 通常应定义在 CREATE TABLE 的第一列")
+    if "created_at" in ordered_names:
+        idx = ordered_names.index("created_at")
+        trailing = ordered_names[idx + 1 :]
+        if trailing and trailing != ["updated_at"]:
+            warnings.append(
+                f"{table_name}: created_at 之后通常只应跟 updated_at，不应再放置其他业务字段"
+            )
+    if "updated_at" in ordered_names and "created_at" in ordered_names:
+        if ordered_names.index("updated_at") < ordered_names.index("created_at"):
+            warnings.append(f"{table_name}: updated_at 不应出现在 created_at 之前")
+    return warnings
+
+
+def _table_exists(cursor, table_name: str) -> bool:
+    cursor.execute(
+        "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ? LIMIT 1",
+        (table_name,),
+    )
+    return cursor.fetchone() is not None
+
+
+def validate_no_sqlite_foreign_keys(cursor) -> tuple[list[str], list[str]]:
+    """业务表 DDL 不得含 FOREIGN KEY / REFERENCES（关联走 repository/service）。"""
+    errors: list[str] = []
+    cursor.execute(
+        """
+        SELECT name, sql FROM sqlite_master
+        WHERE type = 'table' AND name NOT LIKE 'sqlite_%'
+        """
+    )
+    for table_name, sql in cursor.fetchall():
+        if table_name in METADATA_TABLES:
+            continue
+        ddl = str(sql or "")
+        if ddl and _FK_DDL_PATTERN.search(ddl):
+            errors.append(
+                f"业务表 {table_name!r} 的 DDL 含 SQLite FOREIGN KEY/REFERENCES；"
+                "请改为业务 id 列 + repository/service 逻辑关联（见 references/SCHEMA.md）"
+            )
+    return errors, []
+
+
+def validate_display_metadata(conn: sqlite3.Connection, *, check_column_order: bool = True) -> ValidationReport:
+    report = ValidationReport()
+    cur = conn.cursor()
+
+    has_tables_meta = _table_exists(cur, "_jiangchang_tables")
+    has_columns_meta = _table_exists(cur, "_jiangchang_columns")
+    if not has_tables_meta:
+        report.errors.append("缺少数据管理元数据表 _jiangchang_tables")
+    if not has_columns_meta:
+        report.errors.append("缺少数据管理元数据表 _jiangchang_columns")
+    if not has_tables_meta or not has_columns_meta:
+        return report
+
+    fk_errors, _ = validate_no_sqlite_foreign_keys(cur)
+    report.errors.extend(fk_errors)
+
+    for table_name in iter_user_tables(cur):
+        cur.execute(
+            "SELECT display_name FROM _jiangchang_tables WHERE table_name = ?",
+            (table_name,),
+        )
+        row = cur.fetchone()
+        if not row or not str(row[0] or "").strip():
+            report.errors.append(f"业务表 {table_name!r} 缺少 _jiangchang_tables.display_name")
+        elif not _has_cjk(str(row[0])):
+            report.errors.append(f"业务表 {table_name!r} 的 display_name 应使用中文业务名称")
+
+        physical_columns = list_physical_column_names(cur, table_name)
+        if check_column_order:
+            report.warnings.extend(column_order_warnings(table_name, physical_columns))
+
+        for column_name in physical_columns:
+            cur.execute(
+                """
+                SELECT display_name, visible
+                FROM _jiangchang_columns
+                WHERE table_name = ? AND column_name = ?
+                """,
+                (table_name, column_name),
+            )
+            col_row = cur.fetchone()
+            if not col_row:
+                report.errors.append(
+                    f"字段 {table_name}.{column_name} 缺少 _jiangchang_columns 元数据"
+                )
+                continue
+            display_name = str(col_row[0] or "").strip()
+            visible = col_row[1] is None or int(col_row[1]) != 0
+            if visible and not display_name:
+                report.errors.append(f"字段 {table_name}.{column_name} 的 display_name 为空")
+            elif visible and _looks_like_raw_physical_name(display_name, column_name):
+                report.errors.append(
+                    f"字段 {table_name}.{column_name} 的 display_name 不应直接等于英文物理名：{display_name!r}"
+                )
+            elif visible and not _has_cjk(display_name):
+                report.errors.append(
+                    f"字段 {table_name}.{column_name} 的 display_name 应使用中文：{display_name!r}"
+                )
+
+        ts_errors, ts_warnings = validate_standard_timestamp_columns(
+            cur,
+            table_name,
+            physical_columns=physical_columns,
+        )
+        report.errors.extend(ts_errors)
+        report.warnings.extend(ts_warnings)
+
+        perm_errors, perm_warnings = validate_column_permissions(
+            cur,
+            table_name,
+            physical_columns=physical_columns,
+        )
+        report.errors.extend(perm_errors)
+        report.warnings.extend(perm_warnings)
+
+        _, filter_warnings = validate_filter_search_metadata(cur, table_name)
+        report.warnings.extend(filter_warnings)
+
+    cur.execute("SELECT table_name, column_name FROM _jiangchang_columns")
+    for table_name, column_name in cur.fetchall():
+        if table_name in METADATA_TABLES:
+            continue
+        cur.execute(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name = ?",
+            (table_name,),
+        )
+        if not cur.fetchone():
+            report.errors.append(f"元数据引用了不存在的表：{table_name!r}")
+            continue
+        physical = list_physical_column_names(cur, str(table_name))
+        if str(column_name) not in physical:
+            report.errors.append(f"元数据引用了不存在的字段：{table_name}.{column_name}")
+
+    cur.execute("SELECT table_name FROM _jiangchang_tables")
+    for (table_name,) in cur.fetchall():
+        if table_name in METADATA_TABLES:
+            continue
+        cur.execute(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name = ?",
+            (table_name,),
+        )
+        if not cur.fetchone():
+            report.errors.append(f"元数据引用了不存在的表：{table_name!r}")
+
+    return report
+
+
+def validate_template_database(conn: sqlite3.Connection) -> ValidationReport:
+    """模板自检入口：校验展示元数据完整性，并扫描业务表 DDL 是否含 SQLite 外键。"""
+    return validate_display_metadata(conn)

scripts/db/seed_data.py

@@ -0,0 +1,63 @@
+"""业务种子数据：预警规则阈值。
+
+init-db 幂等写入（存在即跳过，不覆盖管理员修改）。
+阈值缺省口径来自《核心建设内容：各部门"Skill"深度需求规格书》财务处 Skill 002：
+低于序时进度 10% 记"严重滞后"，高于 20% 记"支出异常偏快"；暂付款账龄 90 天。
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+from util.timeutil import now_unix
+
+# (rule_key, display_name, threshold_value, description)
+_SEED_ALERT_RULES: tuple[tuple[str, str, float, str], ...] = (
+    (
+        "lag_threshold",
+        "严重滞后阈值",
+        0.10,
+        "实际支出率低于序时进度该比例（小数，0.10=10个百分点）时标记“严重滞后”。",
+    ),
+    (
+        "overshoot_threshold",
+        "支出异常偏快阈值",
+        0.20,
+        "实际支出率高于序时进度该比例（小数，0.20=20个百分点）时标记“支出异常偏快”，预警年底突击花钱。",
+    ),
+    (
+        "pending_aging_days",
+        "暂付款账龄提醒天数",
+        90.0,
+        "暂付款自最早发生日起超过该天数（天）时提醒及时冲销。",
+    ),
+    (
+        "closing_warn_days",
+        "结题临近预警天数",
+        90.0,
+        "距执行期结束不足该天数（天）且支出率低于 80% 时提醒尽快完成报销。",
+    ),
+)
+
+
+def seed_alert_rules(cursor: sqlite3.Cursor) -> int:
+    """幂等写入预警规则种子，返回新增条数。"""
+    inserted = 0
+    for rule_key, display_name, threshold_value, description in _SEED_ALERT_RULES:
+        cursor.execute("SELECT COUNT(*) FROM alert_rules WHERE rule_key = ?", (rule_key,))
+        if int(cursor.fetchone()[0]) > 0:
+            continue
+        cursor.execute(
+            """
+            INSERT INTO alert_rules (rule_key, display_name, threshold_value, description, created_at, updated_at)
+            VALUES (?, ?, ?, ?, ?, ?)
+            """,
+            (rule_key, display_name, threshold_value, description, now_unix(), now_unix()),
+        )
+        inserted += 1
+    return inserted
+
+
+def seed_all(cursor: sqlite3.Cursor) -> dict[str, int]:
+    """写入全部业务种子，返回各类新增条数。"""
+    return {"alert_rules": seed_alert_rules(cursor)}

scripts/db/timestamp_columns.py

@@ -0,0 +1,50 @@
+"""标准时间字段：Unix 秒级时间戳、默认值与 updated_at 自动维护。
+
+业务表若包含 created_at / updated_at，在 CREATE TABLE 后调用
+``init_updated_at_trigger(cursor, table_name)``。模板默认不建业务表。
+"""
+
+from __future__ import annotations
+
+STANDARD_TIMESTAMP_COLUMNS = frozenset({"created_at", "updated_at"})
+DATETIME_UNIX_SECONDS = "datetime_unix_seconds"
+
+
+def updated_at_trigger_name(table_name: str) -> str:
+    return f"{table_name}_set_updated_at"
+
+
+def _quote_identifier(name: str) -> str:
+    return '"' + name.replace('"', '""') + '"'
+
+
+def init_updated_at_trigger(cursor, table_name: str) -> None:
+    """幂等创建 {table}_set_updated_at：业务字段 UPDATE 后刷新 updated_at。"""
+    trigger = updated_at_trigger_name(table_name)
+    quoted = _quote_identifier(table_name)
+    quoted_trigger = _quote_identifier(trigger)
+    cursor.execute(
+        f"""
+CREATE TRIGGER IF NOT EXISTS {quoted_trigger}
+AFTER UPDATE ON {quoted}
+FOR EACH ROW
+BEGIN
+    UPDATE {quoted}
+    SET updated_at = unixepoch()
+    WHERE id = NEW.id AND updated_at = OLD.updated_at;
+END
+"""
+    )
+
+
+def has_updated_at_trigger(cursor, table_name: str) -> bool:
+    trigger_name = updated_at_trigger_name(table_name)
+    cursor.execute(
+        """
+        SELECT 1 FROM sqlite_master
+        WHERE type = 'trigger' AND name = ? AND tbl_name = ?
+        LIMIT 1
+        """,
+        (trigger_name, table_name),
+    )
+    return cursor.fetchone() is not None

scripts/main.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+skill-template CLI 入口。
+
+复制为新技能后，请修改注释与常量，但保留当前分层结构：
+cli（argv）→ service（业务编排）→ db（持久化）→ util（通用工具）。
+
+jiangchang_skill_core 来自宿主共享 Python runtime 安装的 jiangchang-platform-kit，
+不在技能仓库内 vendored。
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+if sys.platform == "win32":
+    import io
+
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
+    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding="utf-8", errors="replace")
+
+_scripts_dir = os.path.dirname(os.path.abspath(__file__))
+if _scripts_dir not in sys.path:
+    sys.path.insert(0, _scripts_dir)
+
+from jiangchang_skill_core.runtime_env import apply_cli_local_defaults
+
+apply_cli_local_defaults()
+
+from util.config_bootstrap import bootstrap_skill_config
+
+bootstrap_skill_config()
+
+from cli.app import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/service/entitlement_service.py

@@ -0,0 +1,46 @@
+"""在线鉴权（可选模板）。"""
+
+from __future__ import annotations
+
+from typing import Tuple
+
+import requests
+from jiangchang_skill_core import config
+
+
+def check_entitlement(skill_slug: str) -> Tuple[bool, str]:
+    auth_base = (config.get("JIANGCHANG_AUTH_BASE_URL") or "").strip().rstrip("/")
+    if not auth_base:
+        return True, ""
+    user_id = (config.get("JIANGCHANG_USER_ID") or "").strip()
+    if not user_id:
+        return False, "鉴权失败：缺少用户身份（JIANGCHANG_USER_ID）"
+
+    auth_api_key = (config.get("JIANGCHANG_AUTH_API_KEY") or "").strip()
+    timeout = int((config.get("JIANGCHANG_AUTH_TIMEOUT_SECONDS") or "5").strip())
+    headers = {"Content-Type": "application/json"}
+    if auth_api_key:
+        headers["Authorization"] = f"Bearer {auth_api_key}"
+    payload = {
+        "user_id": user_id,
+        "skill_slug": skill_slug,
+        "trace_id": (config.get("JIANGCHANG_TRACE_ID") or "").strip(),
+        "context": {"entry": "main.py"},
+    }
+    try:
+        res = requests.post(f"{auth_base}/api/entitlements/check", json=payload, headers=headers, timeout=timeout)
+    except requests.RequestException as exc:
+        return False, f"鉴权请求失败：{exc}"
+    if res.status_code != 200:
+        return False, f"鉴权服务异常：HTTP {res.status_code}"
+    try:
+        body = res.json()
+    except ValueError:
+        return False, "鉴权服务异常：返回非 JSON"
+    code = body.get("code")
+    data = body.get("data") or {}
+    if code != 200:
+        return False, str(body.get("msg") or "鉴权失败")
+    if not data.get("allow", False):
+        return False, str(data.get("reason") or "未购买或已过期")
+    return True, ""

scripts/service/fund_service.py

@@ -0,0 +1,511 @@
+"""项目经费执行监测与播报内核（唯一业务内核）。
+
+三步计算（对齐《核心建设内容：各部门"Skill"深度需求规格书》财务处 Skill 002）：
+  Step 1 执行率计算：实际支出率 = 已报销/已到账；序时进度 = 已过天数/总执行天数
+  Step 2 偏差诊断：低于序时进度超 lag_threshold → 严重滞后；高于 overshoot_threshold → 支出异常偏快
+  Step 3 提醒与建议：暂付款账龄、结题临近、三段式播报摘要（规则模板，数字全部本地计算，不编造）
+
+阈值存 alert_rules 表（管理员可调）；播报结果写 progress_reports 并生成《经费执行简报》。
+播报仅作提醒，请以财务系统账面为准。
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import uuid
+from datetime import date
+from typing import Any, Optional
+
+from db.connection import get_conn, init_db
+from util.logging_config import get_skill_logger
+from util.timeutil import now_unix
+
+STATUS_LAG = "严重滞后"
+STATUS_OVERSHOOT = "支出异常偏快"
+STATUS_NORMAL = "正常"
+STATUS_INCOMPLETE = "待补录"
+STATUS_NO_FUND = "未到账"
+
+_DEFAULT_RULES = {
+    "lag_threshold": 0.10,
+    "overshoot_threshold": 0.20,
+    "pending_aging_days": 90.0,
+    "closing_warn_days": 90.0,
+}
+
+_KEY_ALIASES = {
+    "projectNo": ("project_no", "项目编号", "编号"),
+    "projectName": ("project_name", "项目名称", "名称"),
+    "projectType": ("project_type", "项目类别", "类别"),
+    "piName": ("pi_name", "负责人", "pi"),
+    "department": ("department", "所属学院", "学院"),
+    "totalApproved": ("total_approved", "总立项经费", "立项经费"),
+    "totalReceived": ("total_received", "已到账金额", "已到账", "到账金额"),
+    "totalSpent": ("total_spent", "已报销金额", "已报销", "报销金额"),
+    "frozenAmount": ("frozen_amount", "冻结/暂付款", "暂付款金额", "冻结金额"),
+    "frozenSince": ("frozen_since", "暂付款最早发生日", "暂付款日期"),
+    "startDate": ("start_date", "执行期开始", "开始日期"),
+    "endDate": ("end_date", "执行期结束", "结束日期"),
+    "status": ("status", "项目状态", "状态"),
+    "remark": ("remark", "备注"),
+}
+
+_STATUS_RANK = {STATUS_INCOMPLETE: 0, STATUS_NO_FUND: 1, STATUS_NORMAL: 2, STATUS_OVERSHOOT: 3, STATUS_LAG: 4}
+
+
+def _log():
+    try:
+        return get_skill_logger()
+    except RuntimeError:
+        return None
+
+
+def _norm_project(raw: dict[str, Any]) -> dict[str, Any]:
+    """归一化台账键（兼容 camelCase / snake_case / 常见中文键）。"""
+    out: dict[str, Any] = {}
+    for key, value in raw.items():
+        camel = _camel(key)
+        if camel in _KEY_ALIASES:
+            out.setdefault(camel, value)
+            continue
+        matched = False
+        for canonical, aliases in _KEY_ALIASES.items():
+            if key in aliases:
+                out.setdefault(canonical, value)
+                matched = True
+                break
+        if not matched:
+            out.setdefault(camel, value)
+    return out
+
+
+def _camel(name: str) -> str:
+    parts = re.split(r"[\s_]+", str(name).strip())
+    if len(parts) <= 1:
+        return str(name)
+    head, *rest = parts
+    return head + "".join(p[:1].upper() + p[1:] for p in rest)
+
+
+def _to_float(value: Any) -> Optional[float]:
+    if value is None or value == "":
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    text = re.sub(r"[元,，\s]", "", str(value).strip())
+    try:
+        return float(text)
+    except ValueError:
+        return None
+
+
+def _parse_date(value: Any) -> Optional[date]:
+    if value is None or value == "":
+        return None
+    if isinstance(value, date):
+        return value
+    text = str(value).strip()
+    for pattern in ("%Y-%m-%d", "%Y/%m/%d", "%Y.%m.%d", "%Y年%m月%d日"):
+        try:
+            from datetime import datetime
+
+            return datetime.strptime(text, pattern).date()
+        except ValueError:
+            continue
+    return None
+
+
+def _fmt_date(value: Optional[date]) -> str:
+    return value.isoformat() if value else ""
+
+
+def _wan(value: Optional[float]) -> str:
+    if value is None:
+        return "—"
+    return f"{value / 10000:.2f} 万元"
+
+
+def _pct(value: Optional[float]) -> str:
+    return "—" if value is None else f"{value * 100:.1f}%"
+
+
+def load_rules() -> dict[str, float]:
+    """读取预警阈值（缺失时回退缺省值）。"""
+    rules = dict(_DEFAULT_RULES)
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        cur.execute("SELECT rule_key, threshold_value FROM alert_rules")
+        for rule_key, threshold_value in cur.fetchall():
+            try:
+                rules[str(rule_key)] = float(threshold_value)
+            except (TypeError, ValueError):
+                continue
+    finally:
+        conn.close()
+    return rules
+
+
+def _item(rule_id: str, name: str, level: str, detail: str, suggestion: str = "") -> dict[str, str]:
+    return {"rule_id": rule_id, "name": name, "level": level, "detail": detail, "suggestion": suggestion}
+
+
+def _time_progress(start: Optional[date], end: Optional[date], as_of: date) -> Optional[float]:
+    if not start or not end or end <= start:
+        return None
+    if as_of <= start:
+        return 0.0
+    if as_of >= end:
+        return 1.0
+    return round((as_of - start).days / (end - start).days, 4)
+
+
+def compute_project(project: dict[str, Any], rules: dict[str, float], as_of: date) -> dict[str, Any]:
+    """对单个项目执行三步计算，返回播报结果（不落库）。"""
+    items: list[dict[str, str]] = []
+    project_no = str(project.get("projectNo") or "").strip() or "未编号"
+    project_name = str(project.get("projectName") or "").strip() or project_no
+
+    total_received = _to_float(project.get("totalReceived"))
+    total_spent = _to_float(project.get("totalSpent"))
+    total_approved = _to_float(project.get("totalApproved"))
+    start = _parse_date(project.get("startDate"))
+    end = _parse_date(project.get("endDate"))
+
+    # C3 台账完整性
+    missing = [
+        label
+        for key, label in (
+            ("totalApproved", "总立项经费"),
+            ("totalReceived", "已到账金额"),
+            ("totalSpent", "已报销金额"),
+            ("startDate", "执行期开始"),
+            ("endDate", "执行期结束"),
+        )
+        if (
+            _to_float(project.get(key)) is None
+            if key.startswith("total")
+            else project.get(key) in (None, "")
+        )
+    ]
+    if missing:
+        items.append(
+            _item(
+                "C3",
+                "台账完整性",
+                "warn",
+                f"以下台账字段缺失：{'、'.join(missing)}，本期数字可能失真，请补录。",
+                "请在数据管理“项目台账”中补齐后重新播报。",
+            )
+        )
+
+    # C1 实际支出率
+    spend_rate: Optional[float] = None
+    if total_received is not None and total_received <= 0:
+        items.append(
+            _item(
+                "C1",
+                "实际支出率",
+                "warn",
+                "经费尚未到账，无法计算执行率。",
+                "到账后自动纳入正常播报；如长期未到账请联系财务处核实拨款进度。",
+            )
+        )
+    elif total_received is not None and total_spent is not None:
+        spend_rate = round(total_spent / total_received, 4)
+
+    # C2 序时进度
+    time_progress = _time_progress(start, end, as_of)
+    if time_progress is None:
+        items.append(
+            _item(
+                "C2",
+                "序时进度",
+                "warn",
+                "执行期起止缺失或无效，无法计算序时进度。",
+                "请在项目台账补录执行期起止日期。",
+            )
+        )
+
+    # D1/D2/D3 偏差诊断
+    status_tag = STATUS_NORMAL
+    deviation: Optional[float] = None
+    if spend_rate is not None and time_progress is not None:
+        deviation = round(spend_rate - time_progress, 4)
+        lag = float(rules.get("lag_threshold", _DEFAULT_RULES["lag_threshold"]))
+        overshoot = float(rules.get("overshoot_threshold", _DEFAULT_RULES["overshoot_threshold"]))
+        if deviation < -lag:
+            status_tag = STATUS_LAG
+            items.append(
+                _item(
+                    "D1",
+                    "严重滞后",
+                    "alert",
+                    f"实际支出率 {_pct(spend_rate)} 低于序时进度 {_pct(time_progress)} 超过 {_pct(lag)}，偏差 {_pct(deviation)}。",
+                    "请对照研究计划排查滞后原因；如确需调整，请尽早与财务处沟通预算调剂或申请延期。",
+                )
+            )
+        elif deviation > overshoot:
+            status_tag = STATUS_OVERSHOOT
+            items.append(
+                _item(
+                    "D2",
+                    "支出异常偏快",
+                    "warn",
+                    f"实际支出率 {_pct(spend_rate)} 高于序时进度 {_pct(time_progress)} 超过 {_pct(overshoot)}，偏差 +{_pct(deviation)}，存在年底经费不足风险。",
+                    "请合理安排后续支出节奏，避免年底突击花钱或经费提前耗尽。",
+                )
+            )
+        else:
+            status_tag = STATUS_NORMAL
+            items.append(
+                _item(
+                    "D3",
+                    "执行正常",
+                    "pass",
+                    f"实际支出率 {_pct(spend_rate)} 与序时进度 {_pct(time_progress)} 基本匹配（偏差 {_pct(deviation)}）。",
+                    "",
+                )
+            )
+
+    # N1 暂付款账龄
+    frozen_amount = _to_float(project.get("frozenAmount"))
+    frozen_since = _parse_date(project.get("frozenSince"))
+    if frozen_amount is not None and frozen_amount > 0:
+        aging_days = (as_of - frozen_since).days if frozen_since else None
+        pending_days = float(rules.get("pending_aging_days", _DEFAULT_RULES["pending_aging_days"]))
+        if aging_days is None:
+            items.append(
+                _item(
+                    "N1",
+                    "暂付款冲销提醒",
+                    "info",
+                    f"项目有暂付款 {_wan(frozen_amount)}，但台账未登记最早发生日，无法计算账龄。",
+                    "请补录暂付款发生日期，以便跟踪冲销时限。",
+                )
+            )
+        elif aging_days > pending_days:
+            items.append(
+                _item(
+                    "N1",
+                    "暂付款冲销提醒",
+                    "info",
+                    f"暂付款 {_wan(frozen_amount)} 最早发生于 {frozen_since.isoformat()}，账龄已 {aging_days} 天（超 {pending_days:.0f} 天）。",
+                    "请及时办理暂付款冲销或核销手续。",
+                )
+            )
+
+    # N2 结题临近
+    if end:
+        days_left = (end - as_of).days
+        closing_days = float(rules.get("closing_warn_days", _DEFAULT_RULES["closing_warn_days"]))
+        if days_left < 0:
+            items.append(
+                _item(
+                    "N2",
+                    "结题决算提醒",
+                    "info",
+                    f"项目执行期已于 {end.isoformat()} 结束。",
+                    "请尽快完成支出归集与结题决算。",
+                )
+            )
+        elif days_left <= closing_days and (spend_rate is None or spend_rate < 0.8):
+            rate_text = _pct(spend_rate) if spend_rate is not None else "暂无支出率"
+            items.append(
+                _item(
+                    "N2",
+                    "结题临近提醒",
+                    "info",
+                    f"距执行期结束（{end.isoformat()}）仅剩 {days_left} 天，当前支出率 {rate_text}。",
+                    "请尽快完成剩余科目报销，避免结题时经费大量沉淀。",
+                )
+            )
+
+    # 状态修正：无法计算时归为未到账/待补录
+    if spend_rate is None and status_tag == STATUS_NORMAL:
+        has_no_fund = any(i["rule_id"] == "C1" for i in items)
+        status_tag = STATUS_NO_FUND if has_no_fund else STATUS_INCOMPLETE
+
+    suggestions = [i["suggestion"] for i in items if i.get("suggestion")]
+    summary = _build_summary(project_no, project_name, total_approved, total_received, total_spent, as_of, spend_rate, time_progress, status_tag, items)
+
+    return {
+        "project_no": project_no,
+        "project_name": project_name,
+        "pi_name": str(project.get("piName") or "").strip(),
+        "department": str(project.get("department") or "").strip(),
+        "project_type": str(project.get("projectType") or "").strip(),
+        "total_approved": total_approved,
+        "total_received": total_received,
+        "total_spent": total_spent,
+        "frozen_amount": frozen_amount,
+        "frozen_since": _fmt_date(frozen_since),
+        "start_date": _fmt_date(start),
+        "end_date": _fmt_date(end),
+        "as_of": as_of.isoformat(),
+        "spend_rate": spend_rate,
+        "time_progress": time_progress,
+        "deviation": deviation,
+        "status_tag": status_tag,
+        "items": items,
+        "suggestions": suggestions,
+        "summary": summary,
+    }
+
+
+def _join_sentences(segments: list[str]) -> str:
+    """拼接句子：去掉各段尾部句号，统一以“；”分隔并以“。”结尾。"""
+    cleaned = [s.strip().rstrip("。").strip() for s in segments if s and s.strip()]
+    return "；".join(cleaned) + "。" if cleaned else ""
+
+
+def _build_summary(
+    project_no: str,
+    project_name: str,
+    total_approved: Optional[float],
+    total_received: Optional[float],
+    total_spent: Optional[float],
+    as_of: date,
+    spend_rate: Optional[float],
+    time_progress: Optional[float],
+    status_tag: str,
+    items: list[dict[str, str]],
+) -> str:
+    """三段式播报摘要（模板注入，数字全部来自计算）。"""
+    part1 = (
+        f"您负责的《{project_name}》（{project_no}）：总立项经费 {_wan(total_approved)}，"
+        f"已到账 {_wan(total_received)}，已报销 {_wan(total_spent)}，"
+        f"截至 {as_of.isoformat()} 实际支出率 {_pct(spend_rate)}，序时进度 {_pct(time_progress)}，"
+        f"执行状态{status_tag}。"
+    )
+    diagnostics = [i for i in items if i["rule_id"] in ("D1", "D2", "D3", "N1", "N2", "C1", "C3")]
+    if diagnostics:
+        part2 = "诊断：" + _join_sentences([i["detail"] for i in diagnostics])
+    else:
+        part2 = "诊断：暂无特别事项。"
+    suggestions = [i["suggestion"] for i in items if i.get("suggestion")]
+    if suggestions:
+        part3 = "建议：" + _join_sentences(suggestions[:3])
+    else:
+        part3 = "建议：按研究计划均衡安排支出，保持执行进度与时间进度匹配。"
+    return f"{part1}\n{part2}\n{part3}"
+
+
+def _validate_projects(projects: list[dict[str, Any]]) -> None:
+    if not projects:
+        raise ValueError("项目台账为空：请先录入项目（add-project / import-projects）")
+    if len(projects) > 500:
+        raise ValueError(f"单次播报项目数过多（{len(projects)} 个），上限 500 个")
+    for idx, project in enumerate(projects):
+        if not isinstance(project, dict):
+            raise ValueError(f"第 {idx + 1} 个项目不是 JSON 对象")
+
+
+def _write_report(result: dict[str, Any], batch_no: str) -> str:
+    from service.report_service import write_report_for_kernel
+
+    return write_report_for_kernel(result=result, batch_no=batch_no)
+
+
+def run_broadcast(projects_raw: list[dict[str, Any]], as_of: date, *, batch_no: str = "") -> dict[str, Any]:
+    """播报内核：逐项目三步计算 → 写库 → 生成《经费执行简报》。"""
+    from service.report_service import build_monthly_brief
+
+    log = _log()
+    init_db()
+    projects = [_norm_project(p) for p in projects_raw]
+    _validate_projects(projects)
+
+    batch_no = batch_no or now_unix().to_bytes(5, "big").hex() + uuid.uuid4().hex[:6]
+    rules = load_rules()
+
+    if log:
+        log.info("broadcast_kernel_start batch_no=%s count=%s as_of=%s stage=kernel", batch_no, len(projects), as_of.isoformat())
+
+    results = []
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        for project in projects:
+            result = compute_project(project, rules, as_of)
+            cur.execute(
+                """
+                INSERT INTO progress_reports
+                    (batch_no, project_no, project_name, pi_name, as_of, spend_rate,
+                     time_progress, deviation, status_tag, summary, suggestions_json)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    batch_no,
+                    result["project_no"],
+                    result["project_name"],
+                    result["pi_name"],
+                    result["as_of"],
+                    result["spend_rate"],
+                    result["time_progress"],
+                    result["deviation"],
+                    result["status_tag"],
+                    result["summary"],
+                    json.dumps(result["suggestions"], ensure_ascii=False),
+                ),
+            )
+            report_id = int(cur.lastrowid)
+            result["report_id"] = report_id
+            result["batch_no"] = batch_no
+            report_file = _write_report(result, batch_no)
+            cur.execute("UPDATE progress_reports SET report_file = ? WHERE id = ?", (report_file, report_id))
+            result["report_file"] = report_file
+            results.append(result)
+        conn.commit()
+    finally:
+        conn.close()
+
+    counts: dict[str, int] = {}
+    for result in results:
+        counts[result["status_tag"]] = counts.get(result["status_tag"], 0) + 1
+    brief_file = build_monthly_brief(batch_no=batch_no, results=results, as_of=as_of)
+
+    payload = {
+        "ok": True,
+        "batch_no": batch_no,
+        "as_of": as_of.isoformat(),
+        "count": len(results),
+        "status_counts": counts,
+        "brief_file": brief_file,
+        "disclaimer": "播报仅作提醒，金额与执行进度请以财务系统账面为准。",
+        "reports": results,
+    }
+    if log:
+        log.info(
+            "broadcast_kernel_done batch_no=%s count=%s lag=%s overshoot=%s stage=kernel",
+            batch_no,
+            len(results),
+            counts.get(STATUS_LAG, 0),
+            counts.get(STATUS_OVERSHOOT, 0),
+        )
+    return payload
+
+
+def query_projects(project_no: str = "", pi_name: str = "", include_all_status: bool = False) -> list[dict[str, Any]]:
+    """从台账取待播报项目（缺省全部在研；可按项目编号/负责人筛选）。"""
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        sql = "SELECT * FROM fund_projects WHERE 1=1"
+        params: list[Any] = []
+        if not include_all_status:
+            sql += " AND status = '在研'"
+        if project_no:
+            sql += " AND project_no = ?"
+            params.append(project_no)
+        if pi_name:
+            sql += " AND pi_name LIKE ?"
+            params.append(f"%{pi_name}%")
+        sql += " ORDER BY id"
+        cur.execute(sql, params)
+        columns = [d[0] for d in cur.description]
+        rows = [dict(zip(columns, row)) for row in cur.fetchall()]
+    finally:
+        conn.close()
+    return rows

scripts/service/html_page_service.py

@@ -0,0 +1,78 @@
+"""技能 HTML 报告页：写入 `{skill_data}/html/*.html`（宿主扫描预览）。
+
+契约要点（权威说明见 `references/ACTIONS.md`「HTML 页面报告」）：
+
+- 目录：仅一层 `html/*.html`（非递归）
+- 重新生成 Action id 必须为 `render-html`（宿主硬编码）
+- 页面布局底线见 `references/ACTIONS.md`「宿主预览布局」；模板壳 `assets/html/example-report.html`
+- 成功后建议 `steps: refreshCatalog` 以重扫侧栏
+- 本模块只提供路径/模板/原子写；业务 KPI/表格由各技能自行填充
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import Mapping
+
+from util.logging_config import get_skill_logger
+from util.runtime_paths import get_html_dir, get_skill_root
+
+# Host Data Management looks up this exact Skill Action id for「重新生成」.
+HOST_HTML_RENDER_ACTION_ID = "render-html"
+
+_UNSAFE_NAME = re.compile(r"[\\/]|^\.\.|\.\.$")
+
+
+def _log():
+    try:
+        return get_skill_logger()
+    except RuntimeError:
+        return None
+
+
+def assert_html_filename(filename: str) -> str:
+    name = (filename or "").strip()
+    if not name.lower().endswith(".html"):
+        raise ValueError(f"html filename must end with .html: {filename!r}")
+    if _UNSAFE_NAME.search(name) or "/" in name or "\\" in name:
+        raise ValueError(f"html filename must be a basename only: {filename!r}")
+    if len(name) > 200:
+        raise ValueError(f"html filename too long: {filename!r}")
+    return name
+
+
+def html_page_path(filename: str, *, create_dir: bool = True) -> str:
+    return os.path.join(get_html_dir(create=create_dir), assert_html_filename(filename))
+
+
+def load_html_template(relative_under_skill_root: str) -> str:
+    """Load UTF-8 template from skill root (e.g. ``assets/html/example-report.html``)."""
+    rel = (relative_under_skill_root or "").strip().replace("\\", "/")
+    if not rel or rel.startswith("/") or ".." in rel.split("/"):
+        raise ValueError(f"invalid template path: {relative_under_skill_root!r}")
+    path = os.path.join(get_skill_root(), *rel.split("/"))
+    with open(path, encoding="utf-8") as f:
+        return f.read()
+
+
+def render_html_placeholders(template: str, mapping: Mapping[str, str]) -> str:
+    """Replace ``{{KEY}}`` tokens. Unknown keys are left as-is."""
+    page = template
+    for key, value in mapping.items():
+        page = page.replace("{{" + str(key) + "}}", str(value))
+    return page
+
+
+def write_html_page(filename: str, html: str) -> str:
+    """Atomically write UTF-8 HTML under ``html/``. Returns absolute path."""
+    dest = html_page_path(filename, create_dir=True)
+    tmp = dest + ".tmp"
+    text = html if isinstance(html, str) else str(html)
+    with open(tmp, "w", encoding="utf-8", newline="\n") as f:
+        f.write(text)
+    os.replace(tmp, dest)
+    log = _log()
+    if log:
+        log.info("html_page_written path=%s bytes=%s", dest, len(text.encode("utf-8")))
+    return dest

scripts/service/project_service.py

@@ -0,0 +1,322 @@
+"""项目台账维护：录入（upsert）、批量导入、查询。
+
+台账是播报的唯一数据源；金额单位元，日期 YYYY-MM-DD。
+project_no 唯一，重复导入按项目编号幂等更新（不覆盖未提供字段）。
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from db.connection import get_conn, init_db
+from service.fund_service import _norm_project, _parse_date, _to_float
+from util.logging_config import get_skill_logger
+from util.timeutil import now_unix
+
+_DATE_FIELDS = ("frozen_since", "start_date", "end_date")
+_NUMERIC_FIELDS = ("total_approved", "total_received", "total_spent", "frozen_amount")
+_TEXT_FIELDS = ("project_name", "project_type", "pi_name", "department", "status", "remark")
+
+
+def _log():
+    try:
+        return get_skill_logger()
+    except RuntimeError:
+        return None
+
+
+def _snake(name: str) -> str:
+    """camelCase → snake_case（_norm_project 输出 canonical camelCase 键）。"""
+    return "".join("_" + ch.lower() if ch.isupper() else ch for ch in str(name)).lstrip("_")
+
+
+def upsert_project(fields: dict[str, Any]) -> dict[str, Any]:
+    """按 project_no 幂等写入台账；未提供的字段不覆盖已有值。"""
+    project_no = str(fields.get("project_no") or "").strip()
+    if not project_no:
+        raise ValueError("项目编号（project_no）不能为空")
+
+    values: dict[str, Any] = {"project_no": project_no}
+    for key in _NUMERIC_FIELDS:
+        if key in fields and fields[key] not in (None, ""):
+            number = _to_float(fields[key])
+            if number is None or number < 0:
+                raise ValueError(f"字段 {key} 必须是非负数字：{fields[key]}")
+            values[key] = number
+    for key in _DATE_FIELDS:
+        if key in fields and fields[key] not in (None, ""):
+            parsed = _parse_date(fields[key])
+            if parsed is None:
+                raise ValueError(f"字段 {key} 日期格式无效（应为 YYYY-MM-DD）：{fields[key]}")
+            values[key] = parsed.isoformat()
+    for key in _TEXT_FIELDS:
+        if key in fields and fields[key] is not None:
+            values[key] = str(fields[key]).strip()
+    if values.get("status") and values["status"] not in ("在研", "已结题", "暂缓"):
+        raise ValueError(f"status 只接受 在研/已结题/暂缓：{values['status']}")
+    if values.get("start_date") and values.get("end_date") and values["end_date"] <= values["start_date"]:
+        raise ValueError("执行期结束日期必须晚于开始日期")
+
+    init_db()
+    log = _log()
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        cur.execute("SELECT id FROM fund_projects WHERE project_no = ?", (project_no,))
+        row = cur.fetchone()
+        if row:
+            project_id = int(row[0])
+            set_clause = ", ".join(f"{key} = ?" for key in values if key != "project_no")
+            params = [values[key] for key in values if key != "project_no"] + [now_unix(), project_id]
+            cur.execute(
+                f"UPDATE fund_projects SET {set_clause}, updated_at = ? WHERE id = ?",
+                params,
+            )
+            action = "updated"
+        else:
+            columns = ", ".join(values.keys())
+            placeholders = ", ".join("?" for _ in values)
+            cur.execute(
+                f"INSERT INTO fund_projects ({columns}, created_at, updated_at) VALUES ({placeholders}, ?, ?)",
+                list(values.values()) + [now_unix(), now_unix()],
+            )
+            project_id = int(cur.lastrowid)
+            action = "created"
+        conn.commit()
+    finally:
+        conn.close()
+    if log:
+        log.info("project_upserted project_no=%s action=%s stage=project", project_no, action)
+    return {"ok": True, "project_no": project_no, "id": project_id, "action": action}
+
+
+def import_projects(projects_raw: list[dict[str, Any]]) -> dict[str, Any]:
+    """批量导入台账（upsert），返回统计。"""
+    if not isinstance(projects_raw, list) or not projects_raw:
+        raise ValueError("导入内容应为非空 JSON 数组")
+    if len(projects_raw) > 500:
+        raise ValueError(f"单次导入项目数过多（{len(projects_raw)}），上限 500 个")
+    results = []
+    for idx, raw in enumerate(projects_raw):
+        if not isinstance(raw, dict):
+            raise ValueError(f"第 {idx + 1} 个项目不是 JSON 对象")
+        normalized = {_snake(canonical): value for canonical, value in _norm_project(raw).items()}
+        results.append(upsert_project(normalized))
+    return {
+        "ok": True,
+        "count": len(results),
+        "created": sum(1 for r in results if r["action"] == "created"),
+        "updated": sum(1 for r in results if r["action"] == "updated"),
+        "projects": results,
+    }
+
+
+def list_projects(pi_name: str = "", status: str = "") -> list[dict[str, Any]]:
+    init_db()
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        sql = "SELECT * FROM fund_projects WHERE 1=1"
+        params: list[Any] = []
+        if pi_name:
+            sql += " AND pi_name LIKE ?"
+            params.append(f"%{pi_name}%")
+        if status:
+            sql += " AND status = ?"
+            params.append(status)
+        sql += " ORDER BY id"
+        cur.execute(sql, params)
+        columns = [d[0] for d in cur.description]
+        rows = [dict(zip(columns, row)) for row in cur.fetchall()]
+    finally:
+        conn.close()
+    return rows
+
+
+def get_project_by_id(project_id: int) -> dict[str, Any]:
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        cur.execute("SELECT * FROM fund_projects WHERE id = ?", (project_id,))
+        row = cur.fetchone()
+        if not row:
+            raise ValueError(f"项目不存在：{project_id}")
+        columns = [d[0] for d in cur.description]
+        return dict(zip(columns, row))
+    finally:
+        conn.close()
+
+
+def parse_projects_json(raw: str) -> list[dict[str, Any]]:
+    """解析导入 JSON：'-'（stdin）/ 文件路径 / 内联数组或 {"projects": [...]} 包装。"""
+    import os
+    import sys
+
+    text = (raw or "").strip()
+    if not text:
+        raise ValueError("缺少导入 JSON（--projects-json）")
+    if text == "-":
+        text = sys.stdin.read().strip()
+    elif text.startswith(("[", "{")):
+        pass
+    elif os.path.isfile(text):
+        with open(text, encoding="utf-8") as f:
+            text = f.read().strip()
+    else:
+        raise ValueError(f"--projects-json 不是有效文件路径或 JSON：{text[:80]}")
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"导入 JSON 解析失败：{exc}") from exc
+    if isinstance(payload, dict) and isinstance(payload.get("projects"), list):
+        payload = payload["projects"]
+    if not isinstance(payload, list):
+        raise ValueError("导入 JSON 应为对象数组或 {\"projects\": [...]}")
+    return payload
+
+
+def list_reports(limit: int = 20, status_tag: str = "") -> list[dict[str, Any]]:
+    init_db()
+    limit = max(1, min(int(limit), 200))
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        if status_tag:
+            cur.execute(
+                """
+                SELECT id, batch_no, as_of, project_no, project_name, pi_name,
+                       spend_rate, time_progress, deviation, status_tag, summary, report_file, created_at
+                FROM progress_reports WHERE status_tag = ? ORDER BY id DESC LIMIT ?
+                """,
+                (status_tag, limit),
+            )
+        else:
+            cur.execute(
+                """
+                SELECT id, batch_no, as_of, project_no, project_name, pi_name,
+                       spend_rate, time_progress, deviation, status_tag, summary, report_file, created_at
+                FROM progress_reports ORDER BY id DESC LIMIT ?
+                """,
+                (limit,),
+            )
+        columns = [d[0] for d in cur.description]
+        rows = [dict(zip(columns, row)) for row in cur.fetchall()]
+    finally:
+        conn.close()
+    return rows
+
+
+def get_report(report_id: int) -> dict[str, Any]:
+    init_db()
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        cur.execute("SELECT * FROM progress_reports WHERE id = ?", (report_id,))
+        row = cur.fetchone()
+        if not row:
+            raise ValueError(f"播报记录不存在：{report_id}")
+        columns = [d[0] for d in cur.description]
+        report = dict(zip(columns, row))
+    finally:
+        conn.close()
+    try:
+        report["suggestions"] = json.loads(report.get("suggestions_json") or "[]")
+    except (TypeError, ValueError):
+        report["suggestions"] = []
+    return report
+
+
+def view_rules() -> list[dict[str, Any]]:
+    init_db()
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        cur.execute(
+            "SELECT id, rule_key, display_name, threshold_value, description, updated_at FROM alert_rules ORDER BY id"
+        )
+        columns = [d[0] for d in cur.description]
+        rows = [dict(zip(columns, row)) for row in cur.fetchall()]
+    finally:
+        conn.close()
+    return rows
+
+
+_KNOWN_RULE_KEYS = ("lag_threshold", "overshoot_threshold", "pending_aging_days", "closing_warn_days")
+
+
+def set_rule(rule_key: str, threshold_value: float) -> dict[str, Any]:
+    """按 rule_key 更新阈值（须为已知规则键，数值须为正）。"""
+    rule_key = (rule_key or "").strip()
+    if rule_key not in _KNOWN_RULE_KEYS:
+        raise ValueError(f"未知规则键：{rule_key}（可选：{'、'.join(_KNOWN_RULE_KEYS)}）")
+    threshold_value = float(threshold_value)
+    if threshold_value <= 0 or threshold_value >= 1.5:
+        raise ValueError(f"阈值必须是 0～1.5 之间的正数：{threshold_value}")
+    init_db()
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        cur.execute("SELECT id FROM alert_rules WHERE rule_key = ?", (rule_key,))
+        row = cur.fetchone()
+        if not row:
+            raise ValueError(f"规则键尚未初始化：{rule_key}（请先执行 init-db）")
+        cur.execute(
+            "UPDATE alert_rules SET threshold_value = ?, updated_at = ? WHERE id = ?",
+            (threshold_value, now_unix(), int(row[0])),
+        )
+        conn.commit()
+    finally:
+        conn.close()
+    log = _log()
+    if log:
+        log.info("rule_updated rule_key=%s value=%s stage=rules", rule_key, threshold_value)
+    return {"ok": True, "rule_key": rule_key, "threshold_value": threshold_value}
+
+
+def stats() -> dict[str, Any]:
+    init_db()
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        cur.execute("SELECT COUNT(*) FROM fund_projects")
+        project_total = int(cur.fetchone()[0])
+        cur.execute("SELECT status, COUNT(*) FROM fund_projects GROUP BY status")
+        by_status = {str(r[0]): int(r[1]) for r in cur.fetchall()}
+        cur.execute("SELECT status_tag, COUNT(*) FROM progress_reports GROUP BY status_tag")
+        reports_by_tag = {str(r[0]): int(r[1]) for r in cur.fetchall()}
+        cur.execute("SELECT COUNT(*) FROM progress_reports")
+        report_total = int(cur.fetchone()[0])
+        cur.execute(
+            """
+            SELECT project_no, project_name, pi_name, status_tag, spend_rate, time_progress, as_of
+            FROM progress_reports
+            WHERE status_tag = '严重滞后'
+            ORDER BY deviation ASC LIMIT 5
+            """
+        )
+        lag_top = [
+            {
+                "project_no": r[0],
+                "project_name": r[1],
+                "pi_name": r[2],
+                "status_tag": r[3],
+                "spend_rate": r[4],
+                "time_progress": r[5],
+                "as_of": r[6],
+            }
+            for r in cur.fetchall()
+        ]
+        cur.execute("SELECT COALESCE(SUM(frozen_amount), 0) FROM fund_projects WHERE status = '在研'")
+        frozen_total = float(cur.fetchone()[0])
+    finally:
+        conn.close()
+    return {
+        "ok": True,
+        "project_total": project_total,
+        "projects_by_status": by_status,
+        "report_total": report_total,
+        "reports_by_tag": reports_by_tag,
+        "lag_top": lag_top,
+        "frozen_total": frozen_total,
+    }

scripts/service/report_service.py

@@ -0,0 +1,251 @@
+"""《经费执行简报》HTML 组装。
+
+- 每项目一份 `report-{report_id}.html`（含执行率 vs 序时进度 CSS 柱状图）
+- 月度播报另生成汇总页 `brief-{batch_no}.html`
+写入 `{skill_data}/html/`，宿主数据管理侧栏可预览；重建走固定 Action id `render-html`。
+`{{BODY}}` 内数据一律经 html.escape 转义。
+"""
+
+from __future__ import annotations
+
+import html
+import json
+from typing import Any
+
+from service.html_page_service import load_html_template, render_html_placeholders, write_html_page
+from util.logging_config import get_skill_logger
+from util.timeutil import unix_to_iso
+
+_PROGRESS_TEMPLATE_REL = "assets/html/progress-report.html"
+_BRIEF_TEMPLATE_REL = "assets/html/monthly-brief.html"
+
+_STATUS_BADGE = {
+    "严重滞后": "tag-lag",
+    "支出异常偏快": "tag-overshoot",
+    "正常": "tag-normal",
+    "待补录": "tag-gray",
+    "未到账": "tag-gray",
+}
+
+
+def _esc(value: Any) -> str:
+    return html.escape(str(value if value is not None else "—"), quote=True)
+
+
+def _pct(value: Any) -> str:
+    try:
+        return f"{float(value) * 100:.1f}%"
+    except (TypeError, ValueError):
+        return "—"
+
+
+def _wan(value: Any) -> str:
+    try:
+        return f"{float(value) / 10000:.2f} 万元"
+    except (TypeError, ValueError):
+        return "—"
+
+
+def _bar(label: str, value: Any, fill_class: str) -> str:
+    """CSS 柱状图行：纯 div 宽度百分比，iframe 安全无 JS。"""
+    try:
+        ratio = max(0.0, min(float(value), 1.0))
+        width = f"{ratio * 100:.1f}%"
+    except (TypeError, ValueError):
+        width = "0%"
+    return (
+        f'<div class="bar-row"><span class="bar-label">{_esc(label)}</span>'
+        f'<div class="bar-track"><div class="bar-fill {fill_class}" style="width:{width}"></div></div>'
+        f'<span class="bar-value">{_pct(value)}</span></div>'
+    )
+
+
+def _suggestion_list(suggestions: Any) -> str:
+    if isinstance(suggestions, str):
+        try:
+            suggestions = json.loads(suggestions)
+        except (TypeError, ValueError):
+            suggestions = []
+    if not suggestions:
+        return '<p class="muted">暂无特别建议。</p>'
+    rows = "".join(f"<li>{_esc(s)}</li>" for s in suggestions)
+    return f"<ol>{rows}</ol>"
+
+
+def _project_info_table(result: dict[str, Any]) -> str:
+    fields = (
+        ("项目编号", "project_no"),
+        ("项目类别", "project_type"),
+        ("负责人", "pi_name"),
+        ("所属学院", "department"),
+        ("总立项经费", None),
+        ("已到账金额", None),
+        ("已报销金额", None),
+        ("冻结/暂付款", "frozen_amount"),
+        ("执行期", None),
+    )
+    rows = []
+    for label, key in fields:
+        if label == "总立项经费":
+            value = _wan(result.get("total_approved"))
+        elif label == "已到账金额":
+            value = _wan(result.get("total_received"))
+        elif label == "已报销金额":
+            value = _wan(result.get("total_spent"))
+        elif label == "执行期":
+            value = f"{result.get('start_date') or '—'} ~ {result.get('end_date') or '—'}"
+        else:
+            value = result.get(key) or "—"
+        rows.append(f"<tr><th>{_esc(label)}</th><td>{_esc(value)}</td></tr>")
+    return f'<table class="info">{"".join(rows)}</table>'
+
+
+def build_progress_html(result: dict[str, Any], batch_no: str = "") -> str:
+    """组装单个项目的《经费执行简报》HTML 文本。"""
+    status = str(result.get("status_tag") or "")
+    badge = _STATUS_BADGE.get(status, "tag-gray")
+    mark = {"严重滞后": "🔴 严重滞后", "支出异常偏快": "🟠 支出异常偏快", "正常": "🟢 正常"}.get(status, f"⚪ {status}")
+    summary = str(result.get("summary") or "")
+    parts = [p for p in summary.split("\n") if p.strip()]
+    summary_html = "".join(f'<p class="para">{_esc(p)}</p>' for p in parts)
+
+    body = f"""
+    <div class="verdict-line">
+      <span class="tag {badge}">{mark}</span>
+      <span class="muted">批次 {_esc(batch_no or result.get("batch_no"))} · 评估基准日 {_esc(result.get("as_of"))}</span>
+    </div>
+    <div class="section"><h2>执行进度对比</h2>
+      {_bar("实际支出率", result.get("spend_rate"), "fill-spend")}
+      {_bar("序时进度", result.get("time_progress"), "fill-time")}
+      <p class="muted">偏差 = 实际支出率 − 序时进度 = {_esc(_pct(result.get("deviation")))}</p>
+    </div>
+    <div class="section"><h2>项目信息</h2>{_project_info_table(result)}</div>
+    <div class="section"><h2>播报摘要</h2>{summary_html}</div>
+    <div class="section"><h2>建议</h2>{_suggestion_list(result.get("suggestions"))}</div>
+    <footer>本简报由项目台账数据自动生成，仅作提醒；金额与执行进度请以财务系统账面为准。</footer>
+    """
+
+    template = load_html_template(_PROGRESS_TEMPLATE_REL)
+    return render_html_placeholders(
+        template,
+        {
+            "TITLE": f"经费执行简报 · {result.get('project_name') or result.get('project_no') or ''}",
+            "GENERATED_AT": "",
+            "BODY": body,
+        },
+    )
+
+
+def write_report_for_kernel(*, result: dict[str, Any], batch_no: str) -> str:
+    """内核路径：用内存数据直接组装并写出单项目简报，返回文件路径。"""
+    html_text = build_progress_html(result, batch_no)
+    log = get_skill_logger()
+    path = write_html_page(f"report-{result['report_id']}.html", html_text)
+    log.info("progress_report_written report_id=%s path=%s stage=report", result["report_id"], path)
+    return path
+
+
+def build_report_for_report_id(report_id: int) -> str:
+    """按播报记录 id 从库中取数并重写 HTML（重建入口用）。"""
+    from db.connection import get_conn
+
+    log = get_skill_logger()
+    log.info("report_render_start report_id=%s stage=render", report_id)
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        cur.execute("SELECT * FROM progress_reports WHERE id = ?", (report_id,))
+        row = cur.fetchone()
+        if not row:
+            raise ValueError(f"播报记录不存在：{report_id}")
+        columns = [d[0] for d in cur.description]
+        record = dict(zip(columns, row))
+    finally:
+        conn.close()
+    result = _record_to_result(record)
+    html_text = build_progress_html(result)
+    path = write_html_page(f"report-{report_id}.html", html_text)
+    log.info("report_render_done report_id=%s path=%s stage=render", report_id, path)
+    return path
+
+
+def _record_to_result(record: dict[str, Any]) -> dict[str, Any]:
+    """把播报记录行还原为简报渲染所需的结果结构（金额从台账补齐）。"""
+    from service.project_service import get_project_by_id
+
+    result = dict(record)
+    try:
+        project = get_project_by_id(int(record.get("project_id")))
+    except (TypeError, ValueError):
+        project = {}
+    for key in (
+        "project_type",
+        "department",
+        "total_approved",
+        "total_received",
+        "total_spent",
+        "frozen_amount",
+        "start_date",
+        "end_date",
+    ):
+        result.setdefault(key, project.get(key))
+    try:
+        result["suggestions"] = json.loads(record.get("suggestions_json") or "[]")
+    except (TypeError, ValueError):
+        result["suggestions"] = []
+    return result
+
+
+def build_monthly_brief(*, batch_no: str, results: list[dict[str, Any]], as_of: Any) -> str:
+    """月度播报汇总页：全部项目的执行率/序时进度柱状图一览。"""
+    log = get_skill_logger()
+    rows = []
+    order = {"严重滞后": 0, "支出异常偏快": 1, "正常": 2, "待补录": 3, "未到账": 4}
+    for result in sorted(results, key=lambda r: order.get(str(r.get("status_tag")), 9)):
+        status = str(result.get("status_tag") or "")
+        badge = _STATUS_BADGE.get(status, "tag-gray")
+        rows.append(
+            "<tr>"
+            f'<td class="nowrap">{_esc(result.get("project_no"))}</td>'
+            f'<td>{_esc(result.get("project_name"))}<br/><span class="muted">{_esc(result.get("pi_name"))}</span></td>'
+            f'<td class="nowrap"><span class="tag {badge}">{_esc(status)}</span></td>'
+            f'<td>{_bar("支出", result.get("spend_rate"), "fill-spend")}{_bar("序时", result.get("time_progress"), "fill-time")}</td>'
+            f'<td class="nowrap">{_esc(_pct(result.get("deviation")))}</td>'
+            "</tr>"
+        )
+    if not rows:
+        rows.append('<tr><td colspan="5" class="muted">本期无可播报项目。</td></tr>')
+
+    counts: dict[str, int] = {}
+    for result in results:
+        counts[str(result.get("status_tag"))] = counts.get(str(result.get("status_tag")), 0) + 1
+    chips = " ".join(
+        f'<span class="tag {_STATUS_BADGE.get(tag, "tag-gray")}">{_esc(tag)} × {num}</span>'
+        for tag, num in sorted(counts.items(), key=lambda kv: order.get(kv[0], 9))
+    )
+
+    body = f"""
+    <div class="verdict-line">
+      {chips or '<span class="muted">无</span>'}
+      <span class="muted">批次 {_esc(batch_no)} · 评估基准日 {_esc(as_of)}</span>
+    </div>
+    <div class="section"><h2>全部项目进度一览（按状态排序）</h2>
+      <table>
+        <tr><th>项目编号</th><th>项目 / 负责人</th><th>状态</th><th>进度对比</th><th>偏差</th></tr>
+        {"".join(rows)}
+      </table>
+    </div>
+    <footer>本汇总由月度播报自动生成，仅作提醒；金额与执行进度请以财务系统账面为准。</footer>
+    """
+    template = load_html_template(_BRIEF_TEMPLATE_REL)
+    page = render_html_placeholders(
+        template,
+        {
+            "TITLE": "月度经费执行汇总简报",
+            "GENERATED_AT": str(as_of),
+            "BODY": body,
+        },
+    )
+    path = write_html_page(f"brief-{batch_no}.html", page)
+    log.info("monthly_brief_written batch_no=%s path=%s stage=report", batch_no, path)
+    return path

scripts/service/sibling_bridge.py

@@ -0,0 +1,57 @@
+"""兄弟技能 CLI 调用工具。
+
+通过子进程调用同级其他 skill 的 main.py，并解析 JSON 输出。
+具体调用哪些兄弟技能，由复制后的业务 skill 在 service 层按需决定。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from typing import Any, Dict, List, Optional
+
+from util.logging_config import subprocess_env_with_trace
+from util.runtime_paths import get_skills_root
+
+
+def call_sibling_json(skill_slug: str, args: List[str]) -> Optional[Dict[str, Any]]:
+    """通用兄弟技能调用器。
+
+    Args:
+        skill_slug: 兄弟技能的 slug（即同级目录名）。
+        args: 传给 main.py 的命令行参数列表。
+
+    Returns:
+        若兄弟技能输出可解析的 JSON 对象则返回 dict；否则返回 None。
+    """
+    script_path = os.path.join(get_skills_root(), skill_slug, "scripts", "main.py")
+    if not os.path.isfile(script_path):
+        return None
+    proc = subprocess.run(
+        [sys.executable, script_path, *args],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        env=subprocess_env_with_trace(),
+    )
+    raw = (proc.stdout or "").strip()
+    if not raw or raw.startswith("ERROR"):
+        return None
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def get_sibling_main_path(skill_slug: str) -> str:
+    """获取兄弟技能的 main.py 绝对路径。
+
+    使用示例（在 task_service.py 中）：
+        from service.sibling_bridge import get_sibling_main_path, call_sibling_json
+        result = call_sibling_json("account-manager", ["list", "--limit", "10"])
+    """
+    return os.path.join(get_skills_root(), skill_slug, "scripts", "main.py")

scripts/service/task_run_support.py

@@ -0,0 +1,84 @@
+"""任务运行辅助：录屏信息组装与 CLI 输出（通用模板，无业务逻辑）。"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+def build_video_info(
+    video_summary: dict[str, Any],
+    compose_context_before: Optional[dict[str, Any]] = None,
+    compose_context_after: Optional[dict[str, Any]] = None,
+) -> dict[str, Any]:
+    """将 RpaVideoSession.summary() 转为 finish() / CLI 可用的 video 块。"""
+    return {
+        "enabled": video_summary.get("enabled", False),
+        "path": video_summary.get("path"),
+        "capture_path": video_summary.get("capture_path"),
+        "record_log_path": video_summary.get("record_log_path"),
+        "warnings": list(video_summary.get("warnings") or []),
+        "voiceover_path": video_summary.get("voiceover_path"),
+        "music_path": video_summary.get("music_path"),
+        "audio_warnings": list(video_summary.get("audio_warnings") or []),
+        "compose_context": {
+            **(compose_context_before or {}),
+            "after_compose": compose_context_after or {},
+        },
+    }
+
+
+def merge_video_into_result_summary(
+    payload: dict[str, Any],
+    video_info: Optional[dict[str, Any]],
+) -> dict[str, Any]:
+    """把 video artifact 字段写入 finish() 结果对象（video / video_path 等）。"""
+    if not video_info:
+        return payload
+    payload = dict(payload)
+    payload["video"] = video_info
+    payload["video_path"] = video_info.get("path")
+    payload["raw_video"] = video_info.get("capture_path")
+    payload["video_log"] = video_info.get("record_log_path")
+    payload["video_warnings"] = list(video_info.get("warnings") or [])
+    payload["voiceover_path"] = video_info.get("voiceover_path")
+    payload["music_path"] = video_info.get("music_path")
+    payload["audio_warnings"] = list(video_info.get("audio_warnings") or [])
+    return payload
+
+
+def _print_video_summary(video_block: Optional[dict[str, Any]]) -> None:
+    """任务完成后在 CLI 打印录屏路径、日志与诊断信息。"""
+    if not isinstance(video_block, dict) or not video_block.get("enabled"):
+        return
+    record_log = video_block.get("record_log_path")
+    if record_log:
+        print(f"录屏日志：{record_log}")
+    path = video_block.get("path")
+    if path:
+        print(f"录屏路径：{path}")
+    else:
+        print("录屏路径：未生成")
+        warnings = video_block.get("warnings") or []
+        if warnings:
+            print(f"视频诊断：{'; '.join(str(w) for w in warnings)}")
+        capture = video_block.get("capture_path")
+        if capture:
+            print(f"原始录屏路径：{capture}")
+    voiceover = video_block.get("voiceover_path")
+    if voiceover:
+        print(f"旁白路径：{voiceover}")
+    music = video_block.get("music_path")
+    if music:
+        print(f"背景音乐：{music}")
+    audio_warnings = video_block.get("audio_warnings") or []
+    if audio_warnings:
+        print(f"音频诊断：{'; '.join(str(w) for w in audio_warnings)}")
+    compose_ctx = video_block.get("compose_context")
+    if isinstance(compose_ctx, dict):
+        print(
+            "视频合成上下文："
+            f"media_assets_root={compose_ctx.get('media_assets_root', '')}; "
+            f"ffmpeg_path={compose_ctx.get('ffmpeg_path', '')}; "
+            f"background_music_issue={compose_ctx.get('background_music_issue') or ''}; "
+            f"background_music_sample_path={compose_ctx.get('background_music_sample_path', '')}"
+        )

scripts/service/task_service.py

@@ -0,0 +1,620 @@
+"""任务编排层：job_context / emit / finish、鉴权与错误转换。
+
+领域业务在 ``service/fund_service.py``（播报内核）、
+``service/project_service.py``（台账/规则/统计）、
+``service/report_service.py``（HTML 简报），由本模块调用；
+多入口（CLI / Action / 对话 / cron）复用同一内核，禁止按入口分叉业务。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import uuid
+from typing import Any, Optional
+
+from jiangchang_skill_core import collect_runtime_diagnostics, config, format_runtime_health_lines
+from jiangchang_skill_core.activity import JobStopped, emit, finish, job_context
+
+from jiangchang_skill_core.rpa.video_session import RpaVideoSession
+from service.entitlement_service import check_entitlement
+from service.task_run_support import (
+    _print_video_summary,
+    build_video_info,
+    merge_video_into_result_summary,
+)
+from util.constants import LOG_LOGGER_NAME, PLATFORM_KIT_MIN_VERSION, SKILL_SLUG, SKILL_VERSION
+from util.logging_config import get_skill_logger, setup_skill_logging
+from util.runtime_paths import get_db_path, get_skill_root
+from db.connection import init_db
+
+
+def _get_task_logger():
+    try:
+        return get_skill_logger()
+    except RuntimeError:
+        setup_skill_logging(SKILL_SLUG, LOG_LOGGER_NAME)
+        return get_skill_logger()
+
+
+def _print_json(payload: dict[str, Any]) -> None:
+    print(json.dumps(payload, ensure_ascii=False))
+
+
+# ---------------------------------------------------------------------------
+# 模板演示入口（保留：满足 POLICY-RPA-003 录屏集成与 CLI run 契约；不承载本技能业务）
+# ---------------------------------------------------------------------------
+
+async def _run_template_demo(target: Optional[str], input_id: Optional[str]) -> tuple[int, dict[str, Any]]:
+    """最小 RpaVideoSession 示范：不启动浏览器、不执行业务，仅演示录屏包裹范式。"""
+    batch_id = uuid.uuid4().hex[:12]
+    data_dir = get_skill_root()
+
+    async with RpaVideoSession(
+        skill_slug=SKILL_SLUG,
+        skill_data_dir=data_dir,
+        batch_id=batch_id,
+        title="开始执行示例任务",
+        closing_title="示例任务执行完成",
+    ) as video:
+        video.add_step("准备执行示例任务")
+        if target:
+            video.add_step(f"接收目标参数：{target}")
+        if input_id:
+            video.add_step(f"接收输入标识：{input_id}")
+        video.add_step("示例任务执行完成")
+
+    video_summary = video.summary()
+    video_info = build_video_info(video_summary, {}, {})
+    return 1, video_info
+
+
+def cmd_run(target: Optional[str] = None, input_id: Optional[str] = None) -> int:
+    """模板演示入口：本技能主能力请使用 broadcast 等业务命令。"""
+    log = _get_task_logger()
+    task_type = "demo"
+
+    with job_context(skill=SKILL_SLUG):
+        log.info(
+            "task_start task_type=%s target_id=%s input_id=%s stage=run",
+            task_type,
+            target,
+            input_id,
+        )
+        emit("开始处理任务", skill=SKILL_SLUG, stage="run")
+        try:
+            ok, reason = check_entitlement(SKILL_SLUG)
+            if not ok:
+                log.warning(
+                    "entitlement_failed task_type=%s stage=auth error_code=ENTITLEMENT_DENIED",
+                    task_type,
+                )
+                emit("鉴权失败，已记录诊断信息", type="warn", skill=SKILL_SLUG, stage="auth")
+                finish(
+                    status="failed",
+                    message=reason,
+                    skill=SKILL_SLUG,
+                    error_code="ENTITLEMENT_DENIED",
+                    stage="auth",
+                )
+                print(f"ERROR:ENTITLEMENT_DENIED {reason}")
+                return 1
+
+            log.info("entitlement_ok task_type=%s stage=auth", task_type)
+            log.info("rpa_start stage=demo_prepare task_type=%s", task_type)
+            log.info("task_run_demo_start target_id=%s input_id=%s stage=demo_prepare", target, input_id)
+            rc, video_info = asyncio.run(_run_template_demo(target, input_id))
+            log.info("rpa_done stage=demo_prepare status=ok")
+            log.info(
+                "task_run_demo_done target_id=%s input_id=%s stage=demo_finish status=failed",
+                target,
+                input_id,
+            )
+            _print_video_summary(video_info)
+
+            summary_payload = merge_video_into_result_summary(
+                {
+                    "template_demo": True,
+                    "target": target,
+                    "input_id": input_id,
+                },
+                video_info,
+            )
+
+            log.warning(
+                "task_failed task_type=%s stage=demo_finish error_code=TEMPLATE_STUB",
+                task_type,
+            )
+            finish(
+                status="failed",
+                message="模板演示入口未承载本技能业务",
+                skill=SKILL_SLUG,
+                error_code="TEMPLATE_STUB",
+                **summary_payload,
+            )
+            print("ERROR:TEMPLATE_STUB 这是模板演示入口，请使用 broadcast 命令执行经费进度播报。")
+            return rc
+        except JobStopped:
+            raise
+        except Exception:
+            log.exception(
+                "task_failed task_type=%s target_id=%s input_id=%s",
+                task_type,
+                target,
+                input_id,
+            )
+            emit("任务失败，已记录诊断信息", type="warn", skill=SKILL_SLUG, stage="run")
+            finish(
+                status="failed",
+                message="任务执行异常，详见统一日志",
+                skill=SKILL_SLUG,
+                stage="run",
+            )
+            return 1
+
+
+# ---------------------------------------------------------------------------
+# 基础命令
+# ---------------------------------------------------------------------------
+
+def cmd_config_path() -> int:
+    example_path = os.path.join(get_skill_root(), ".env.example")
+    env_path = config.get_env_file_path() or ""
+    _print_json(
+        {
+            "skill": SKILL_SLUG,
+            "env_path": env_path,
+            "example_path": os.path.abspath(example_path),
+        }
+    )
+    return 0
+
+
+def cmd_health() -> int:
+    runtime = collect_runtime_diagnostics(
+        skill_slug=SKILL_SLUG,
+        platform_kit_min_version=PLATFORM_KIT_MIN_VERSION,
+        skill_root=get_skill_root(),
+    )
+    example_path = os.path.join(get_skill_root(), ".env.example")
+    env_path = config.get_env_file_path() or ""
+    env_exists = bool(env_path and os.path.isfile(env_path))
+
+    health_status = "failed" if runtime.has_fatal_issues else "ok"
+    lines = [
+        f"{SKILL_SLUG} health: {health_status}",
+        *format_runtime_health_lines(runtime),
+        f"env_path: {env_path}",
+        f"env_exists: {env_exists}",
+        f"example_path: {os.path.abspath(example_path)}",
+    ]
+    for line in lines:
+        print(line)
+    return 1 if runtime.has_fatal_issues else 0
+
+
+def cmd_version() -> int:
+    _print_json({"version": SKILL_VERSION, "skill": SKILL_SLUG})
+    return 0
+
+
+def cmd_init_db() -> int:
+    """幂等创建/迁移本地 SQLite 与数据管理元数据（宿主 install/upgrade 可调用）。"""
+    log = _get_task_logger()
+    try:
+        seeded = init_db()
+    except Exception as exc:  # noqa: BLE001 — CLI 边界，统一成可机读失败
+        print(
+            json.dumps(
+                {"ok": False, "skill": SKILL_SLUG, "error": str(exc)},
+                ensure_ascii=False,
+            )
+        )
+        return 1
+    _print_json(
+        {
+            "ok": True,
+            "skill": SKILL_SLUG,
+            "db_path": get_db_path(),
+            "seeded": seeded,
+        }
+    )
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# 项目台账
+# ---------------------------------------------------------------------------
+
+def cmd_add_project(
+    *,
+    project_no: str,
+    name: str = "",
+    project_type: str = "",
+    pi: str = "",
+    department: str = "",
+    total_approved: Optional[float] = None,
+    total_received: Optional[float] = None,
+    total_spent: Optional[float] = None,
+    frozen: Optional[float] = None,
+    frozen_since: str = "",
+    start: str = "",
+    end: str = "",
+    status: str = "",
+    remark: str = "",
+) -> int:
+    log = _get_task_logger()
+    from service.project_service import upsert_project
+
+    with job_context(skill=SKILL_SLUG):
+        log.info("task_start task_type=add_project project_no=%s stage=project", project_no)
+        emit("开始写入项目台账", skill=SKILL_SLUG, stage="project")
+        try:
+            ok, reason = check_entitlement(SKILL_SLUG)
+            if not ok:
+                log.warning("entitlement_failed task_type=add_project stage=auth")
+                finish(status="failed", message=reason, skill=SKILL_SLUG, error_code="ENTITLEMENT_DENIED", stage="auth")
+                log.error("add_project_denied stage=auth")
+                print(f"ERROR:ENTITLEMENT_DENIED {reason}")
+                return 1
+            fields: dict[str, Any] = {"project_no": project_no}
+            if name:
+                fields["project_name"] = name
+            if project_type:
+                fields["project_type"] = project_type
+            if pi:
+                fields["pi_name"] = pi
+            if department:
+                fields["department"] = department
+            for key, value in (
+                ("total_approved", total_approved),
+                ("total_received", total_received),
+                ("total_spent", total_spent),
+                ("frozen_amount", frozen),
+            ):
+                if value is not None:
+                    fields[key] = value
+            for key, value in (("frozen_since", frozen_since), ("start_date", start), ("end_date", end), ("status", status), ("remark", remark)):
+                if value:
+                    fields[key] = value
+            payload = upsert_project(fields)
+            _print_json(payload)
+            finish(status="success", message=f"项目 {project_no} 已{'更新' if payload['action'] == 'updated' else '录入'}", skill=SKILL_SLUG, stage="project")
+            return 0
+        except ValueError as exc:
+            log.warning("task_failed task_type=add_project error_code=PROJECT_INVALID detail=%s", exc)
+            finish(status="failed", message=str(exc), skill=SKILL_SLUG, error_code="PROJECT_INVALID", stage="project")
+            print(f"ERROR:PROJECT_INVALID {exc}")
+            return 1
+        except JobStopped:
+            raise
+        except Exception:
+            log.exception("task_failed task_type=add_project stage=project")
+            finish(status="failed", message="台账写入异常，详见统一日志", skill=SKILL_SLUG, stage="project")
+            return 1
+
+
+def cmd_import_projects(projects_json: str) -> int:
+    log = _get_task_logger()
+    from service.project_service import import_projects, parse_projects_json
+
+    with job_context(skill=SKILL_SLUG):
+        log.info("task_start task_type=import_projects stage=project")
+        emit("开始批量导入项目台账", skill=SKILL_SLUG, stage="project")
+        try:
+            ok, reason = check_entitlement(SKILL_SLUG)
+            if not ok:
+                log.warning("entitlement_failed task_type=import_projects stage=auth")
+                finish(status="failed", message=reason, skill=SKILL_SLUG, error_code="ENTITLEMENT_DENIED", stage="auth")
+                log.error("import_projects_denied stage=auth")
+                print(f"ERROR:ENTITLEMENT_DENIED {reason}")
+                return 1
+            projects = parse_projects_json(projects_json)
+            payload = import_projects(projects)
+            _print_json(payload)
+            finish(status="success", message=f"导入完成：新增 {payload['created']}，更新 {payload['updated']}", skill=SKILL_SLUG, stage="project")
+            return 0
+        except ValueError as exc:
+            log.warning("task_failed task_type=import_projects error_code=PROJECT_INVALID detail=%s", exc)
+            finish(status="failed", message=str(exc), skill=SKILL_SLUG, error_code="PROJECT_INVALID", stage="project")
+            print(f"ERROR:PROJECT_INVALID {exc}")
+            return 1
+        except JobStopped:
+            raise
+        except Exception:
+            log.exception("task_failed task_type=import_projects stage=project")
+            finish(status="failed", message="台账导入异常，详见统一日志", skill=SKILL_SLUG, stage="project")
+            return 1
+
+
+def cmd_list_projects(pi: str = "", status: str = "") -> int:
+    log = _get_task_logger()
+    from service.project_service import list_projects
+
+    with job_context(skill=SKILL_SLUG):
+        log.info("task_start task_type=list_projects pi=%s status=%s", pi, status)
+        try:
+            projects = list_projects(pi_name=pi, status=status)
+            _print_json({"ok": True, "count": len(projects), "projects": projects})
+            return 0
+        except Exception:
+            log.exception("task_failed task_type=list_projects")
+            print("ERROR:QUERY_FAILED 台账查询异常，详见统一日志")
+            return 1
+
+
+# ---------------------------------------------------------------------------
+# 播报主命令
+# ---------------------------------------------------------------------------
+
+def cmd_broadcast(
+    *,
+    project_no: str = "",
+    pi: str = "",
+    as_of: str = "",
+    include_all_status: bool = False,
+) -> int:
+    """经费进度播报（同步）：全部在研项目或指定项目。"""
+    log = _get_task_logger()
+    from datetime import date
+
+    from service.fund_service import query_projects, run_broadcast
+
+    with job_context(skill=SKILL_SLUG):
+        log.info("task_start task_type=broadcast project_no=%s pi=%s stage=broadcast", project_no, pi)
+        emit("开始经费进度播报", skill=SKILL_SLUG, stage="broadcast")
+        try:
+            ok, reason = check_entitlement(SKILL_SLUG)
+            if not ok:
+                log.warning("entitlement_failed task_type=broadcast stage=auth")
+                finish(status="failed", message=reason, skill=SKILL_SLUG, error_code="ENTITLEMENT_DENIED", stage="auth")
+                log.error("broadcast_denied stage=auth")
+                print(f"ERROR:ENTITLEMENT_DENIED {reason}")
+                return 1
+
+            as_of_date = date.fromisoformat(as_of) if as_of else date.today()
+            projects = query_projects(project_no=project_no, pi_name=pi, include_all_status=include_all_status)
+            if not projects:
+                message = "没有可播报的项目：请先录入台账（在研项目为空或筛选条件不匹配）"
+                log.warning("task_failed task_type=broadcast error_code=NO_PROJECTS stage=broadcast")
+                finish(status="failed", message=message, skill=SKILL_SLUG, error_code="NO_PROJECTS", stage="broadcast")
+                log.error("broadcast_no_projects stage=broadcast")
+                print(f"ERROR:NO_PROJECTS {message}")
+                return 1
+
+            result = run_broadcast(projects, as_of_date)
+            payload = {k: v for k, v in result.items() if k != "reports"}
+            payload["reports_brief"] = [
+                {k: r[k] for k in ("report_id", "project_no", "project_name", "pi_name", "status_tag", "spend_rate", "time_progress", "deviation", "report_file")}
+                for r in result["reports"]
+            ]
+            _print_json(payload)
+            emit(
+                f"播报完成 {result['count']} 个项目：严重滞后 {result['status_counts'].get('严重滞后', 0)}，"
+                f"异常偏快 {result['status_counts'].get('支出异常偏快', 0)}",
+                skill=SKILL_SLUG,
+                stage="broadcast",
+            )
+            finish(
+                status="success",
+                message=f"播报完成 {result['count']} 个项目，简报已生成",
+                skill=SKILL_SLUG,
+                stage="broadcast",
+                batch_no=result["batch_no"],
+            )
+            return 0
+        except JobStopped:
+            raise
+        except ValueError as exc:
+            log.warning("task_failed task_type=broadcast error_code=PROJECT_INVALID detail=%s", exc)
+            finish(status="failed", message=str(exc), skill=SKILL_SLUG, error_code="PROJECT_INVALID", stage="broadcast")
+            print(f"ERROR:PROJECT_INVALID {exc}")
+            return 1
+        except Exception:
+            log.exception("task_failed task_type=broadcast stage=broadcast")
+            emit("播报失败，已记录诊断信息", type="warn", skill=SKILL_SLUG, stage="broadcast")
+            finish(status="failed", message="播报执行异常，详见统一日志", skill=SKILL_SLUG, stage="broadcast")
+            return 1
+
+
+def cmd_broadcast_monthly() -> int:
+    """月度播报（async Action 入口）：全部在研项目逐项播报 + 汇总简报，任务中心可见进度。"""
+    log = _get_task_logger()
+    from datetime import date
+
+    from service.fund_service import query_projects, run_broadcast
+
+    with job_context(skill=SKILL_SLUG):
+        log.info("task_start task_type=broadcast_monthly stage=monthly")
+        emit("开始月度经费播报", skill=SKILL_SLUG, stage="monthly")
+        try:
+            ok, reason = check_entitlement(SKILL_SLUG)
+            if not ok:
+                log.warning("entitlement_failed task_type=broadcast_monthly stage=auth")
+                finish(status="failed", message=reason, skill=SKILL_SLUG, error_code="ENTITLEMENT_DENIED", stage="auth")
+                log.error("broadcast_monthly_denied stage=auth")
+                print(f"ERROR:ENTITLEMENT_DENIED {reason}")
+                return 1
+
+            projects = query_projects()
+            if not projects:
+                message = "台账中没有“在研”项目，月度播报跳过"
+                log.warning("task_failed task_type=broadcast_monthly error_code=NO_PROJECTS stage=monthly")
+                finish(status="failed", message=message, skill=SKILL_SLUG, error_code="NO_PROJECTS", stage="monthly")
+                log.error("broadcast_monthly_no_projects stage=monthly")
+                print(f"ERROR:NO_PROJECTS {message}")
+                return 1
+
+            result = run_broadcast(projects, date.today())
+            for index, report in enumerate(result["reports"], start=1):
+                emit(
+                    f"[{index}/{len(result['reports'])}] {report['project_name']}：{report['status_tag']}",
+                    skill=SKILL_SLUG,
+                    stage="monthly",
+                )
+            _print_json(
+                {
+                    "ok": True,
+                    "batch_no": result["batch_no"],
+                    "as_of": result["as_of"],
+                    "count": result["count"],
+                    "status_counts": result["status_counts"],
+                    "brief_file": result["brief_file"],
+                    "reports_brief": [
+                        {k: r[k] for k in ("report_id", "project_no", "project_name", "pi_name", "status_tag", "summary")}
+                        for r in result["reports"]
+                    ],
+                }
+            )
+            finish(
+                status="success",
+                message=f"月度播报完成：{result['count']} 个项目，严重滞后 {result['status_counts'].get('严重滞后', 0)} 个",
+                skill=SKILL_SLUG,
+                stage="monthly",
+                batch_no=result["batch_no"],
+            )
+            return 0
+        except JobStopped:
+            raise
+        except Exception:
+            log.exception("task_failed task_type=broadcast_monthly stage=monthly")
+            emit("月度播报失败，已记录诊断信息", type="warn", skill=SKILL_SLUG, stage="monthly")
+            finish(status="failed", message="月度播报执行异常，详见统一日志", skill=SKILL_SLUG, stage="monthly")
+            return 1
+
+
+# ---------------------------------------------------------------------------
+# 播报记录与阈值
+# ---------------------------------------------------------------------------
+
+def cmd_list_reports(limit: int = 20, status_tag: str = "") -> int:
+    log = _get_task_logger()
+    from service.project_service import list_reports
+
+    with job_context(skill=SKILL_SLUG):
+        log.info("task_start task_type=list_reports limit=%s status_tag=%s", limit, status_tag)
+        try:
+            reports = list_reports(limit=limit, status_tag=status_tag)
+            _print_json({"ok": True, "count": len(reports), "reports": reports})
+            return 0
+        except Exception:
+            log.exception("task_failed task_type=list_reports")
+            print("ERROR:QUERY_FAILED 播报记录查询异常，详见统一日志")
+            return 1
+
+
+def cmd_show_report(report_id: int) -> int:
+    log = _get_task_logger()
+    from service.project_service import get_report
+
+    with job_context(skill=SKILL_SLUG):
+        log.info("task_start task_type=show_report report_id=%s", report_id)
+        try:
+            report = get_report(int(report_id))
+            _print_json({"ok": True, "report": report})
+            return 0
+        except ValueError as exc:
+            log.warning("task_failed task_type=show_report error_code=REPORT_NOT_FOUND detail=%s", exc)
+            print(f"ERROR:REPORT_NOT_FOUND {exc}")
+            return 1
+        except Exception:
+            log.exception("task_failed task_type=show_report")
+            print("ERROR:QUERY_FAILED 播报记录查询异常，详见统一日志")
+            return 1
+
+
+def cmd_render_html(report_id: Optional[int] = None) -> int:
+    log = _get_task_logger()
+    from service.report_service import build_report_for_report_id
+    from service.project_service import list_reports
+
+    with job_context(skill=SKILL_SLUG):
+        log.info("task_start task_type=render_html report_id=%s stage=render", report_id)
+        try:
+            if report_id:
+                targets = [int(report_id)]
+            else:
+                targets = [r["id"] for r in list_reports(limit=10)]
+            if not targets:
+                log.warning("task_failed task_type=render_html error_code=REPORT_NOT_FOUND stage=render")
+                finish(status="failed", message="暂无可重建的播报记录", skill=SKILL_SLUG, error_code="REPORT_NOT_FOUND", stage="render")
+                print("ERROR:REPORT_NOT_FOUND 暂无可重建的播报记录")
+                return 1
+            written = [{"report_id": rid, "path": build_report_for_report_id(rid)} for rid in targets]
+            _print_json({"ok": True, "count": len(written), "reports": written})
+            finish(status="success", message=f"已重建 {len(written)} 份经费执行简报", skill=SKILL_SLUG, stage="render")
+            return 0
+        except JobStopped:
+            raise
+        except ValueError as exc:
+            log.warning("task_failed task_type=render_html error_code=REPORT_NOT_FOUND detail=%s", exc)
+            finish(status="failed", message=str(exc), skill=SKILL_SLUG, error_code="REPORT_NOT_FOUND", stage="render")
+            print(f"ERROR:REPORT_NOT_FOUND {exc}")
+            return 1
+        except Exception:
+            log.exception("task_failed task_type=render_html stage=render")
+            finish(status="failed", message="简报重建异常，详见统一日志", skill=SKILL_SLUG, stage="render")
+            return 1
+
+
+def cmd_view_rules() -> int:
+    log = _get_task_logger()
+    from service.project_service import view_rules
+
+    with job_context(skill=SKILL_SLUG):
+        log.info("task_start task_type=view_rules stage=rules")
+        try:
+            _print_json({"ok": True, "rules": view_rules()})
+            return 0
+        except Exception:
+            log.exception("task_failed task_type=view_rules")
+            print("ERROR:QUERY_FAILED 预警规则查询异常，详见统一日志")
+            return 1
+
+
+def cmd_set_rule(rule_key: str, value: float) -> int:
+    log = _get_task_logger()
+    from service.project_service import set_rule
+
+    with job_context(skill=SKILL_SLUG):
+        log.info("task_start task_type=set_rule rule_key=%s value=%s stage=rules", rule_key, value)
+        emit("开始更新预警阈值", skill=SKILL_SLUG, stage="rules")
+        try:
+            ok, reason = check_entitlement(SKILL_SLUG)
+            if not ok:
+                log.warning("entitlement_failed task_type=set_rule stage=auth")
+                finish(status="failed", message=reason, skill=SKILL_SLUG, error_code="ENTITLEMENT_DENIED", stage="auth")
+                log.error("set_rule_denied stage=auth")
+                print(f"ERROR:ENTITLEMENT_DENIED {reason}")
+                return 1
+            payload = set_rule(rule_key, float(value))
+            _print_json(payload)
+            finish(status="success", message=f"阈值 {rule_key} 已更新为 {value}", skill=SKILL_SLUG, stage="rules")
+            return 0
+        except ValueError as exc:
+            log.warning("task_failed task_type=set_rule error_code=RULE_INVALID detail=%s", exc)
+            finish(status="failed", message=str(exc), skill=SKILL_SLUG, error_code="RULE_INVALID", stage="rules")
+            print(f"ERROR:RULE_INVALID {exc}")
+            return 1
+        except JobStopped:
+            raise
+        except Exception:
+            log.exception("task_failed task_type=set_rule stage=rules")
+            finish(status="failed", message="阈值更新异常，详见统一日志", skill=SKILL_SLUG, stage="rules")
+            return 1
+
+
+def cmd_stats() -> int:
+    log = _get_task_logger()
+    from service.project_service import stats
+
+    with job_context(skill=SKILL_SLUG):
+        log.info("task_start task_type=stats")
+        try:
+            _print_json(stats())
+            return 0
+        except Exception:
+            log.exception("task_failed task_type=stats")
+            print("ERROR:QUERY_FAILED 统计查询异常，详见统一日志")
+            return 1

scripts/util/argparse_zh.py

@@ -0,0 +1,12 @@
+"""argparse 中文错误说明。"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+class ZhArgumentParser(argparse.ArgumentParser):
+    def error(self, message: str) -> None:
+        print(f"参数错误：{message}\n请执行：python main.py -h 查看帮助", file=sys.stderr)
+        self.exit(2)

scripts/util/config_bootstrap.py

@@ -0,0 +1,19 @@
+"""技能配置初始化：.env.example 落盘与用户 .env 缺失项合并。"""
+
+from __future__ import annotations
+
+import os
+
+from jiangchang_skill_core import config
+
+from util.constants import SKILL_SLUG, SKILL_VERSION
+from util.runtime_paths import get_skill_root
+
+
+def bootstrap_skill_config() -> str:
+    """确保用户数据目录 .env 存在，并追加 .env.example 中的新配置项。"""
+    example_path = os.path.join(get_skill_root(), ".env.example")
+    env_path = config.ensure_env_file(SKILL_SLUG, example_path)
+    comment = f"{SKILL_SLUG} v{SKILL_VERSION}" if SKILL_VERSION else None
+    config.merge_missing_env_keys(example_path, env_path, comment_skill=comment)
+    return env_path

scripts/util/constants.py

@@ -0,0 +1,6 @@
+"""技能标识、版本与平台公共库约束（项目经费进度播报助手）。"""
+
+SKILL_SLUG = "track-fund-progress-default"
+SKILL_VERSION = "1.0.1"
+LOG_LOGGER_NAME = "openclaw.skill.track_fund_progress_default"
+PLATFORM_KIT_MIN_VERSION = "1.2.11"

scripts/util/logging_config.py

@@ -0,0 +1,21 @@
+"""Re-export unified logging (implementation: jiangchang_skill_core.unified_logging)."""
+
+from jiangchang_skill_core.unified_logging import (
+    attach_unified_file_handler,
+    ensure_trace_for_process,
+    get_skill_log_file_path,
+    get_skill_logger,
+    get_unified_logs_dir,
+    setup_skill_logging,
+    subprocess_env_with_trace,
+)
+
+__all__ = [
+    "attach_unified_file_handler",
+    "ensure_trace_for_process",
+    "get_skill_log_file_path",
+    "get_skill_logger",
+    "get_unified_logs_dir",
+    "setup_skill_logging",
+    "subprocess_env_with_trace",
+]

scripts/util/runtime_paths.py

@@ -0,0 +1,155 @@
+"""数据根、技能目录、兄弟技能根路径与用户数据子目录解析。"""
+
+from __future__ import annotations
+
+import os
+
+from jiangchang_skill_core.runtime_env import get_data_root, get_sibling_skills_root, get_user_id
+
+from util.constants import SKILL_SLUG
+
+_SCRIPTS_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+# 用户可见的上行/下行目录（数据管理「输入/输出」文件浏览器）
+STANDARD_SUBDIR_INPUT = "input"
+STANDARD_SUBDIR_OUTPUT = "output"
+
+# 宿主扫描的 HTML 报告页（数据管理侧栏 htmlPages，非 input/output 文件浏览器）
+STANDARD_SUBDIR_HTML = "html"
+
+# 内部/可选目录（不上侧栏）
+STANDARD_SUBDIR_UPLOADS = "uploads"
+STANDARD_SUBDIR_CACHE = "cache"
+STANDARD_SUBDIR_TEMP = "temp"
+STANDARD_SUBDIR_RPA_ARTIFACTS = "rpa-artifacts"
+STANDARD_SUBDIR_VIDEOS = "videos"
+
+CONFIG_KEY_INPUT_DIR = "SKILL_INPUT_DIR"
+CONFIG_KEY_OUTPUT_DIR = "SKILL_OUTPUT_DIR"
+CONFIG_KEY_UPLOAD_DIR = "SKILL_UPLOAD_DIR"
+CONFIG_KEY_CACHE_DIR = "SKILL_CACHE_DIR"
+CONFIG_KEY_TEMP_DIR = "SKILL_TEMP_DIR"
+
+
+def get_skill_root() -> str:
+    return os.path.dirname(_SCRIPTS_DIR)
+
+
+def get_openclaw_root() -> str:
+    return get_sibling_skills_root(_SCRIPTS_DIR)
+
+
+def get_skills_root() -> str:
+    return get_sibling_skills_root(_SCRIPTS_DIR)
+
+
+def get_skill_data_dir() -> str:
+    path = os.path.join(get_data_root(), get_user_id(), SKILL_SLUG)
+    os.makedirs(path, exist_ok=True)
+    return path
+
+
+def get_db_path(filename: str | None = None) -> str:
+    name = filename or f"{SKILL_SLUG}.db"
+    return os.path.join(get_skill_data_dir(), name)
+
+
+def _normalize_subdir(value: str) -> str:
+    cleaned = value.strip().strip("/\\")
+    if not cleaned or cleaned.startswith(".."):
+        raise ValueError(f"invalid skill data subdir: {value!r}")
+    return cleaned.replace("/", os.sep).replace("\\", os.sep)
+
+
+def resolve_data_path(
+    config_key: str | None,
+    default_subdir: str,
+    *,
+    create: bool = True,
+) -> str:
+    """解析技能拥有路径：空配置 → 数据目录下 default_subdir；相对 → 相对数据目录；绝对 → 原样。"""
+    from jiangchang_skill_core import config
+
+    base = get_skill_data_dir()
+    raw = (config.get(config_key) or "").strip() if config_key else ""
+    if not raw:
+        path = os.path.join(base, _normalize_subdir(default_subdir))
+    elif os.path.isabs(raw):
+        path = os.path.abspath(os.path.expanduser(raw))
+    else:
+        path = os.path.join(base, _normalize_subdir(raw))
+
+    if create:
+        os.makedirs(path, exist_ok=True)
+    return path
+
+
+def resolve_input_path(raw_path: str, *, create_parent: bool = False) -> str:
+    """解析 CLI 输入路径：绝对路径原样；相对路径相对 {skill_data_dir}/input/。"""
+    text = (raw_path or "").strip()
+    if not text:
+        return text
+    expanded = os.path.expanduser(text)
+    if os.path.isabs(expanded):
+        return os.path.abspath(expanded)
+    input_dir = get_input_dir(create=create_parent)
+    return os.path.abspath(os.path.join(input_dir, os.path.normpath(expanded)))
+
+
+def get_input_dir(*, create: bool = True) -> str:
+    """上行：用户/Agent 放入的待处理文件（清单、CSV、产品表等）。"""
+    return resolve_data_path(CONFIG_KEY_INPUT_DIR, STANDARD_SUBDIR_INPUT, create=create)
+
+
+def get_output_dir(*, create: bool = True) -> str:
+    """下行：技能/宿主交给用户拿走的文件（视频、报表、导出 CSV 等）。"""
+    return resolve_data_path(CONFIG_KEY_OUTPUT_DIR, STANDARD_SUBDIR_OUTPUT, create=create)
+
+
+def get_uploads_dir(*, create: bool = True) -> str:
+    return resolve_data_path(CONFIG_KEY_UPLOAD_DIR, STANDARD_SUBDIR_UPLOADS, create=create)
+
+
+def get_cache_dir(*, create: bool = True) -> str:
+    return resolve_data_path(CONFIG_KEY_CACHE_DIR, STANDARD_SUBDIR_CACHE, create=create)
+
+
+def get_temp_dir(*, create: bool = True) -> str:
+    return resolve_data_path(CONFIG_KEY_TEMP_DIR, STANDARD_SUBDIR_TEMP, create=create)
+
+
+def get_rpa_artifacts_dir(batch_id: str, *, create: bool = True) -> str:
+    batch = (batch_id or "").strip() or "default"
+    path = os.path.join(get_skill_data_dir(), STANDARD_SUBDIR_RPA_ARTIFACTS, batch)
+    if create:
+        os.makedirs(path, exist_ok=True)
+    return path
+
+
+def get_videos_dir(*, create: bool = True) -> str:
+    path = os.path.join(get_skill_data_dir(), STANDARD_SUBDIR_VIDEOS)
+    if create:
+        os.makedirs(path, exist_ok=True)
+    return path
+
+
+def get_html_dir(*, create: bool = True) -> str:
+    """HTML 报告页目录：宿主扫描 `{skill_data}/html/*.html`（一层、非递归）。"""
+    path = os.path.join(get_skill_data_dir(), STANDARD_SUBDIR_HTML)
+    if create:
+        os.makedirs(path, exist_ok=True)
+    return path
+
+
+def list_resolved_data_paths() -> dict[str, str]:
+    """供 health / config-path 输出已解析的数据子目录（不创建目录）。"""
+    return {
+        "skill_data_dir": get_skill_data_dir(),
+        "input_dir": get_input_dir(create=False),
+        "output_dir": get_output_dir(create=False),
+        "html_dir": get_html_dir(create=False),
+        "uploads_dir": get_uploads_dir(create=False),
+        "cache_dir": get_cache_dir(create=False),
+        "temp_dir": get_temp_dir(create=False),
+        "videos_dir": get_videos_dir(create=False),
+    }

scripts/util/slug_naming.py

@@ -0,0 +1,227 @@
+"""技能 slug 语义校验（verb-noun-platform 规范，见 development/NAMING.md）。"""
+
+from __future__ import annotations
+
+import os
+import re
+
+_KEBAB_SLUG = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+_MAX_SLUG_LENGTH = 48
+_MIN_SEGMENTS = 3
+_MAX_SEGMENTS = 5
+_MAX_NOUN_SEGMENTS = 3
+
+_SKILL_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+_NAMING_DIR = os.path.join(_SKILL_ROOT, "assets", "naming")
+
+_BUILTIN_VERBS = frozenset(
+    {
+        "scrape",
+        "receive",
+        "download",
+        "export",
+        "add",
+        "fill",
+        "enter",
+        "bind",
+        "withdraw",
+        "reconcile",
+        "verify",
+        "submit",
+        "query",
+        "process",
+        "reply",
+        "generate",
+        "draft",
+        "review",
+        "confirm",
+        "track",
+        "upload",
+        "match",
+        "triage",
+        "ship",
+        "reprice",
+    }
+)
+_BUILTIN_PLATFORMS = frozenset(
+    {
+        "amazon",
+        "shopee",
+        "xinghang",
+        "alibaba",
+        "kingdee",
+        "icbc",
+        "pingpong",
+        "worldfirst",
+        "paypal",
+        "lianlian",
+        "single-window",
+        "export-rebate",
+        "etax",
+    }
+)
+_BUILTIN_SCOPES = frozenset({"all", "batch", "multi", "default"})
+
+LEGACY_EXEMPT_SLUGS: frozenset[str] = frozenset(
+    {
+        "account-manager",
+        "skill-template",
+        "your-skill-slug",
+        "your_skill_slug",
+    }
+)
+
+
+def load_wordlist(filename: str) -> frozenset[str]:
+    """从 assets/naming/{filename} 加载词表；文件不存在时 fallback 内置集合。"""
+    fallbacks = {
+        "verbs.txt": _BUILTIN_VERBS,
+        "platforms.txt": _BUILTIN_PLATFORMS,
+        "scopes.txt": _BUILTIN_SCOPES,
+    }
+    fallback = fallbacks.get(filename, frozenset())
+    path = os.path.join(_NAMING_DIR, filename)
+    if not os.path.isfile(path):
+        return fallback
+    words: set[str] = set()
+    with open(path, encoding="utf-8") as f:
+        for line in f:
+            word = line.strip()
+            if word and not word.startswith("#"):
+                words.add(word)
+    return frozenset(words) if words else fallback
+
+
+def parse_slug_segments(slug: str) -> list[str]:
+    """按 '-' 分割；非法字符由上层 kebab 校验处理。"""
+    slug = slug.strip()
+    if not slug:
+        return []
+    return slug.split("-")
+
+
+def _match_platform_suffix(
+    segments: list[str],
+    platforms: frozenset[str],
+) -> tuple[str, int] | None:
+    """返回 (platform_name, platform_part_count) 或 None。"""
+    for platform in sorted(platforms, key=lambda item: (-item.count("-"), item)):
+        parts = platform.split("-")
+        part_count = len(parts)
+        if len(segments) < part_count + 2:
+            continue
+        if segments[-part_count:] == parts:
+            return platform, part_count
+    return None
+
+
+def classify_slug_form(segments: list[str], *, slug: str = "") -> str:
+    """
+    返回: 'legacy_exempt' | 'standard' | 'scope' | 'invalid'
+
+    - legacy_exempt: slug in LEGACY_EXEMPT_SLUGS
+    - standard: 末段匹配 platforms, 首段 in verbs, 3<=len<=5
+    - scope: 末段 in scopes, 首段 in verbs, 3<=len<=5
+    - invalid: 其他
+    """
+    if slug in LEGACY_EXEMPT_SLUGS:
+        return "legacy_exempt"
+
+    if not segments or not (_MIN_SEGMENTS <= len(segments) <= _MAX_SEGMENTS):
+        return "invalid"
+
+    verbs = load_wordlist("verbs.txt")
+    platforms = load_wordlist("platforms.txt")
+    scopes = load_wordlist("scopes.txt")
+
+    if segments[0] not in verbs:
+        return "invalid"
+
+    if segments[-1] in scopes:
+        return "scope"
+
+    if _match_platform_suffix(segments, platforms) is not None:
+        return "standard"
+
+    return "invalid"
+
+
+def validate_slug_semantics(
+    slug: str,
+    *,
+    strict: bool = True,
+) -> tuple[list[str], list[str]]:
+    """返回 (errors, warnings)。"""
+    slug = slug.strip()
+    if slug in LEGACY_EXEMPT_SLUGS:
+        return [], []
+
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    if not _KEBAB_SLUG.fullmatch(slug):
+        msg = f"slug 必须为 kebab-case（小写字母、数字、连字符）：{slug!r}"
+        (errors if strict else warnings).append(msg)
+        return errors, warnings
+
+    if len(slug) > _MAX_SLUG_LENGTH:
+        msg = f"slug 长度不得超过 {_MAX_SLUG_LENGTH} 字符（当前 {len(slug)}）：{slug!r}"
+        (errors if strict else warnings).append(msg)
+
+    segments = parse_slug_segments(slug)
+    segment_count = len(segments)
+
+    if segment_count < _MIN_SEGMENTS:
+        msg = (
+            f"slug 段数应为 {_MIN_SEGMENTS}～{_MAX_SEGMENTS}（verb-noun-platform），"
+            f"当前为 {segment_count} 段：{slug!r}；新技能禁止 2 段无平台形态（如 reconcile-finance）"
+        )
+        (errors if strict else warnings).append(msg)
+        return errors, warnings
+
+    if segment_count > _MAX_SEGMENTS:
+        msg = f"slug 段数不得超过 {_MAX_SEGMENTS}（当前 {segment_count}）：{slug!r}"
+        (errors if strict else warnings).append(msg)
+
+    verbs = load_wordlist("verbs.txt")
+    platforms = load_wordlist("platforms.txt")
+    scopes = load_wordlist("scopes.txt")
+
+    if segments[0] in platforms and segments[0] not in verbs:
+        msg = f"平台名不应放在 slug 最前：{slug!r}（应为 verb-noun-platform）"
+        (errors if strict else warnings).append(msg)
+
+    if segments[0] not in verbs:
+        msg = f"slug 首段应为动词白名单中的词：{segments[0]!r}（slug={slug!r}）"
+        (errors if strict else warnings).append(msg)
+
+    form = classify_slug_form(segments, slug=slug)
+    if form == "scope":
+        if segments[-1] not in scopes:
+            msg = f"slug 末段应为 scope 白名单中的词：{segments[-1]!r}（slug={slug!r}）"
+            (errors if strict else warnings).append(msg)
+        noun_count = segment_count - 2
+    elif form == "standard":
+        platform_match = _match_platform_suffix(segments, platforms)
+        if platform_match is None:
+            msg = f"slug 末段应匹配平台白名单：{slug!r}"
+            (errors if strict else warnings).append(msg)
+            noun_count = 0
+        else:
+            _platform_name, platform_part_count = platform_match
+            noun_count = segment_count - 1 - platform_part_count
+    else:
+        if segment_count >= _MIN_SEGMENTS:
+            if segments[-1] not in scopes:
+                platform_match = _match_platform_suffix(segments, platforms)
+                if platform_match is None:
+                    msg = f"slug 末段应匹配平台或 scope 白名单：{slug!r}"
+                    (errors if strict else warnings).append(msg)
+        noun_count = 0
+
+    if noun_count > _MAX_NOUN_SEGMENTS:
+        warnings.append(
+            f"slug 中间名词段建议不超过 {_MAX_NOUN_SEGMENTS} 个词（当前 {noun_count}）：{slug!r}"
+        )
+
+    return errors, warnings

scripts/util/timeutil.py

@@ -0,0 +1,20 @@
+"""时间戳与 ISO 展示。"""
+
+from __future__ import annotations
+
+import time
+from datetime import datetime
+from typing import Optional
+
+
+def now_unix() -> int:
+    return int(time.time())
+
+
+def unix_to_iso(ts: Optional[int]) -> Optional[str]:
+    if ts is None:
+        return None
+    try:
+        return datetime.fromtimestamp(int(ts)).isoformat(timespec="seconds")
+    except (ValueError, OSError, OverflowError):
+        return None