feat: 结题报告初稿助手首版 v1.0.1(draft-closing-report-default)
All checks were successful
技能自动化发布 / release (push) Successful in 6s

This commit is contained in:
chenfuqiang
2026-09-13 16:04:01 +08:00
commit 7b24521b43
206 changed files with 29892 additions and 0 deletions

View File

@@ -0,0 +1,625 @@
"""任务编排层:job_context / emit / finish、鉴权与错误转换。
领域业务在 ``service/draft_service.py``(初稿内核)、
``service/ledger_service.py``(台账/记录)、``service/docx_service.py``(Word 渲染)、
``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 这是模板演示入口,请使用 draft-report 命令生成结题报告初稿。")
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:
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()})
return 0
# ---------------------------------------------------------------------------
# 台账维护
# ---------------------------------------------------------------------------
def _parse_json_arg(raw: str, label: str) -> list[dict[str, Any]]:
import sys
text = (raw or "").strip()
if not text:
raise ValueError(f"缺少导入 JSON({label})")
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"{label} 不是有效文件路径或 JSON:{text[:80]}")
try:
payload = json.loads(text)
except json.JSONDecodeError as exc:
raise ValueError(f"导入 JSON 解析失败:{exc}") from exc
if isinstance(payload, dict):
for key in ("projects", "achievements", "expenses", "items"):
if isinstance(payload.get(key), list):
payload = payload[key]
break
else:
payload = [payload]
if not isinstance(payload, list):
raise ValueError(f"{label} 应为对象数组")
return payload
def cmd_add_project(
*,
project_no: str,
name: str = "",
pi: str = "",
department: str = "",
program: str = "",
start: str = "",
end: str = "",
expected_json: str = "",
excerpt: str = "",
status: str = "",
) -> int:
log = _get_task_logger()
from service.ledger_service import upsert_project
with job_context(skill=SKILL_SLUG):
log.info("task_start task_type=add_project project_no=%s stage=ledger", project_no)
emit("开始写入结题项目", skill=SKILL_SLUG, stage="ledger")
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")
print(f"ERROR:ENTITLEMENT_DENIED {reason}")
return 1
fields: dict[str, Any] = {"project_no": project_no}
for key, value in (("project_name", name), ("pi_name", pi), ("department", department), ("program", program), ("start_date", start), ("end_date", end), ("expected_json", expected_json), ("annual_report_excerpt", excerpt), ("status", status)):
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="ledger")
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="ledger")
print(f"ERROR:PROJECT_INVALID {exc}")
return 1
except JobStopped:
raise
except Exception:
log.exception("task_failed task_type=add_project stage=ledger")
finish(status="failed", message="项目写入异常,详见统一日志", skill=SKILL_SLUG, stage="ledger")
return 1
def cmd_add_achievement(
*,
project_no: str,
ach_type: str,
title: str,
venue: str = "",
date: str = "",
representative: str = "",
note: str = "",
) -> int:
log = _get_task_logger()
from service.ledger_service import upsert_achievement
with job_context(skill=SKILL_SLUG):
log.info("task_start task_type=add_achievement project_no=%s stage=ledger", project_no)
emit("开始写入成果", skill=SKILL_SLUG, stage="ledger")
try:
ok, reason = check_entitlement(SKILL_SLUG)
if not ok:
log.warning("entitlement_failed task_type=add_achievement stage=auth")
finish(status="failed", message=reason, skill=SKILL_SLUG, error_code="ENTITLEMENT_DENIED", stage="auth")
print(f"ERROR:ENTITLEMENT_DENIED {reason}")
return 1
payload = upsert_achievement(
{"project_no": project_no, "achievement_type": ach_type, "title": title, "venue_or_no": venue, "ach_date": date, "is_representative": representative, "note": note}
)
_print_json(payload)
finish(status="success", message=f"成果已录入:{title[:20]}", skill=SKILL_SLUG, stage="ledger")
return 0
except ValueError as exc:
log.warning("task_failed task_type=add_achievement error_code=PROJECT_INVALID detail=%s", exc)
finish(status="failed", message=str(exc), skill=SKILL_SLUG, error_code="PROJECT_INVALID", stage="ledger")
print(f"ERROR:PROJECT_INVALID {exc}")
return 1
except JobStopped:
raise
except Exception:
log.exception("task_failed task_type=add_achievement stage=ledger")
finish(status="failed", message="成果写入异常,详见统一日志", skill=SKILL_SLUG, stage="ledger")
return 1
def cmd_add_expense(*, project_no: str, category: str, amount: float, date: str = "", description: str = "") -> int:
log = _get_task_logger()
from service.ledger_service import upsert_expense
with job_context(skill=SKILL_SLUG):
log.info("task_start task_type=add_expense project_no=%s stage=ledger", project_no)
emit("开始写入决算明细", skill=SKILL_SLUG, stage="ledger")
try:
ok, reason = check_entitlement(SKILL_SLUG)
if not ok:
log.warning("entitlement_failed task_type=add_expense stage=auth")
finish(status="failed", message=reason, skill=SKILL_SLUG, error_code="ENTITLEMENT_DENIED", stage="auth")
print(f"ERROR:ENTITLEMENT_DENIED {reason}")
return 1
payload = upsert_expense({"project_no": project_no, "category": category, "amount": amount, "occurred_date": date, "description": description})
_print_json(payload)
finish(status="success", message=f"决算明细已录入:{category} {payload['amount']} 元", skill=SKILL_SLUG, stage="ledger")
return 0
except ValueError as exc:
log.warning("task_failed task_type=add_expense error_code=PROJECT_INVALID detail=%s", exc)
finish(status="failed", message=str(exc), skill=SKILL_SLUG, error_code="PROJECT_INVALID", stage="ledger")
print(f"ERROR:PROJECT_INVALID {exc}")
return 1
except JobStopped:
raise
except Exception:
log.exception("task_failed task_type=add_expense stage=ledger")
finish(status="failed", message="决算写入异常,详见统一日志", skill=SKILL_SLUG, stage="ledger")
return 1
def cmd_import(projects_json: str = "", achievements_json: str = "", expenses_json: str = "") -> int:
"""统一导入入口:projects/achievements/expenses 三类 JSON(至少提供一个)。"""
log = _get_task_logger()
from service.ledger_service import import_achievements, import_expenses, import_projects
with job_context(skill=SKILL_SLUG):
log.info("task_start task_type=import stage=ledger")
emit("开始批量导入结题数据", skill=SKILL_SLUG, stage="ledger")
try:
ok, reason = check_entitlement(SKILL_SLUG)
if not ok:
log.warning("entitlement_failed task_type=import stage=auth")
finish(status="failed", message=reason, skill=SKILL_SLUG, error_code="ENTITLEMENT_DENIED", stage="auth")
print(f"ERROR:ENTITLEMENT_DENIED {reason}")
return 1
summary: dict[str, Any] = {"ok": True}
if projects_json:
summary["projects"] = import_projects(_parse_json_arg(projects_json, "--projects-json"))
if achievements_json:
summary["achievements"] = import_achievements(_parse_json_arg(achievements_json, "--achievements-json"))
if expenses_json:
summary["expenses"] = import_expenses(_parse_json_arg(expenses_json, "--expenses-json"))
if len(summary) == 1:
raise ValueError("至少提供一个导入 JSON(--projects-json / --achievements-json / --expenses-json)")
_print_json(summary)
finish(status="success", message="批量导入完成", skill=SKILL_SLUG, stage="ledger")
return 0
except ValueError as exc:
log.warning("task_failed task_type=import error_code=PROJECT_INVALID detail=%s", exc)
finish(status="failed", message=str(exc), skill=SKILL_SLUG, error_code="PROJECT_INVALID", stage="ledger")
print(f"ERROR:PROJECT_INVALID {exc}")
return 1
except JobStopped:
raise
except Exception:
log.exception("task_failed task_type=import stage=ledger")
finish(status="failed", message="批量导入异常,详见统一日志", skill=SKILL_SLUG, stage="ledger")
return 1
def cmd_list(kind: str = "projects", project_no: str = "", status: str = "") -> int:
log = _get_task_logger()
from service.ledger_service import list_achievements, list_expenses, list_projects
with job_context(skill=SKILL_SLUG):
log.info("task_start task_type=list kind=%s project_no=%s", kind, project_no)
try:
if kind == "achievements":
rows = list_achievements(project_no)
elif kind == "expenses":
rows = list_expenses(project_no)
else:
rows = list_projects(status=status)
_print_json({"ok": True, "count": len(rows), "rows": rows})
return 0
except Exception:
log.exception("task_failed task_type=list")
print("ERROR:QUERY_FAILED 台账查询异常,详见统一日志")
return 1
# ---------------------------------------------------------------------------
# 初稿生成
# ---------------------------------------------------------------------------
def cmd_draft_report(*, project_no: str) -> int:
"""结题报告初稿(主命令,同步):指定项目生成 Word 初稿 + HTML 预览。"""
log = _get_task_logger()
from service.draft_service import query_pending_projects, run_draft
with job_context(skill=SKILL_SLUG):
log.info("task_start task_type=draft_report project_no=%s stage=draft", project_no)
emit("开始生成结题报告初稿", skill=SKILL_SLUG, stage="draft")
try:
ok, reason = check_entitlement(SKILL_SLUG)
if not ok:
log.warning("entitlement_failed task_type=draft_report stage=auth")
finish(status="failed", message=reason, skill=SKILL_SLUG, error_code="ENTITLEMENT_DENIED", stage="auth")
print(f"ERROR:ENTITLEMENT_DENIED {reason}")
return 1
projects = query_pending_projects(project_no=project_no)
if not projects:
message = f"未找到该项目(编号 {project_no})或项目状态不是“待结题”"
log.warning("task_failed task_type=draft_report error_code=PROJECT_NOT_FOUND stage=draft")
finish(status="failed", message=message, skill=SKILL_SLUG, error_code="PROJECT_NOT_FOUND", stage="draft")
print(f"ERROR:PROJECT_NOT_FOUND {message}")
return 1
project = projects[0]
achievements = []
expenses = []
from service.ledger_service import list_achievements, list_expenses
achievements = list_achievements(project_no)
expenses = list_expenses(project_no)
result = run_draft(project, achievements, expenses)
_print_json(result)
finish(
status="success",
message=f"初稿已生成:{result['draft_file']}",
skill=SKILL_SLUG,
stage="draft",
batch_no=result["batch_no"],
)
return 0
except JobStopped:
raise
except ValueError as exc:
log.warning("task_failed task_type=draft_report error_code=PROJECT_INVALID detail=%s", exc)
finish(status="failed", message=str(exc), skill=SKILL_SLUG, error_code="PROJECT_INVALID", stage="draft")
print(f"ERROR:PROJECT_INVALID {exc}")
return 1
except Exception:
log.exception("task_failed task_type=draft_report stage=draft")
emit("初稿生成失败,已记录诊断信息", type="warn", skill=SKILL_SLUG, stage="draft")
finish(status="failed", message="初稿生成异常,详见统一日志", skill=SKILL_SLUG, stage="draft")
return 1
def cmd_draft_batch_pending() -> int:
"""批量初稿(async Action 入口):为全部“待结题”项目生成初稿,任务中心可见进度。"""
log = _get_task_logger()
from service.draft_service import query_pending_projects, run_draft
from service.ledger_service import list_achievements, list_expenses
with job_context(skill=SKILL_SLUG):
log.info("task_start task_type=draft_batch stage=batch")
emit("开始批量生成结题初稿", skill=SKILL_SLUG, stage="batch")
try:
ok, reason = check_entitlement(SKILL_SLUG)
if not ok:
log.warning("entitlement_failed task_type=draft_batch stage=auth")
finish(status="failed", message=reason, skill=SKILL_SLUG, error_code="ENTITLEMENT_DENIED", stage="auth")
print(f"ERROR:ENTITLEMENT_DENIED {reason}")
return 1
projects = query_pending_projects()
if not projects:
message = "没有“待结题”状态的项目,批量生成跳过"
log.warning("task_failed task_type=draft_batch error_code=PROJECT_NOT_FOUND stage=batch")
finish(status="failed", message=message, skill=SKILL_SLUG, error_code="PROJECT_NOT_FOUND", stage="batch")
print(f"ERROR:PROJECT_NOT_FOUND {message}")
return 1
drafts = []
for index, project in enumerate(projects, start=1):
emit(f"[{index}/{len(projects)}] {project.get('project_name') or project.get('project_no')}", skill=SKILL_SLUG, stage="batch")
try:
result = run_draft(project, list_achievements(project["project_no"]), list_expenses(project["project_no"]))
drafts.append({"draft_id": result["draft_id"], "project_no": result["project_no"], "draft_file": result["draft_file"]})
except Exception:
log.exception("draft_batch_item_failed project_no=%s", project.get("project_no"))
_print_json({"ok": True, "count": len(drafts), "drafts": drafts})
finish(status="success", message=f"批量初稿完成 {len(drafts)}/{len(projects)} 个项目", skill=SKILL_SLUG, stage="batch")
return 0
except JobStopped:
raise
except Exception:
log.exception("task_failed task_type=draft_batch stage=batch")
emit("批量初稿失败,已记录诊断信息", type="warn", skill=SKILL_SLUG, stage="batch")
finish(status="failed", message="批量初稿执行异常,详见统一日志", skill=SKILL_SLUG, stage="batch")
return 1
# ---------------------------------------------------------------------------
# 记录与统计
# ---------------------------------------------------------------------------
def cmd_list_drafts(limit: int = 20) -> int:
log = _get_task_logger()
from service.ledger_service import list_drafts
with job_context(skill=SKILL_SLUG):
log.info("task_start task_type=list_drafts limit=%s", limit)
try:
drafts = list_drafts(limit=limit)
_print_json({"ok": True, "count": len(drafts), "drafts": drafts})
return 0
except Exception:
log.exception("task_failed task_type=list_drafts")
print("ERROR:QUERY_FAILED 初稿记录查询异常,详见统一日志")
return 1
def cmd_show_draft(draft_id: int) -> int:
log = _get_task_logger()
from service.ledger_service import get_draft
with job_context(skill=SKILL_SLUG):
log.info("task_start task_type=show_draft draft_id=%s", draft_id)
try:
draft = get_draft(int(draft_id))
_print_json({"ok": True, "draft": draft})
return 0
except ValueError as exc:
log.warning("task_failed task_type=show_draft error_code=DRAFT_NOT_FOUND detail=%s", exc)
print(f"ERROR:DRAFT_NOT_FOUND {exc}")
return 1
except Exception:
log.exception("task_failed task_type=show_draft")
print("ERROR:QUERY_FAILED 初稿记录查询异常,详见统一日志")
return 1
def cmd_render_html(report_id: Optional[int] = None) -> int:
log = _get_task_logger()
from service.ledger_service import list_drafts
from service.report_service import build_preview_for_draft_id
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 = [d["id"] for d in list_drafts(limit=10)]
if not targets:
log.warning("task_failed task_type=render_html error_code=DRAFT_NOT_FOUND stage=render")
finish(status="failed", message="暂无可重建的初稿记录", skill=SKILL_SLUG, error_code="DRAFT_NOT_FOUND", stage="render")
print("ERROR:DRAFT_NOT_FOUND 暂无可重建的初稿记录")
return 1
written = [{"draft_id": did, "path": build_preview_for_draft_id(did)} for did in targets]
_print_json({"ok": True, "count": len(written), "previews": 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=DRAFT_NOT_FOUND detail=%s", exc)
finish(status="failed", message=str(exc), skill=SKILL_SLUG, error_code="DRAFT_NOT_FOUND", stage="render")
print(f"ERROR:DRAFT_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_stats() -> int:
log = _get_task_logger()
from service.ledger_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