ai-project-manage-cli 6.0.53 → 6.0.55

package/template/deploy/deploy.py

@@ -0,0 +1,564 @@
+#!/usr/bin/env python3
+"""自动部署脚本"""
+
+from __future__ import annotations
+
+import json
+import posixpath
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+import time
+import zipfile
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import paramiko
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+PROJECT_ROOT = SCRIPT_DIR.parent.parent
+APM_CONFIG_PATH = PROJECT_ROOT / ".apm" / "apm.config.json"
+DEPLOY_CACHE_DIR = SCRIPT_DIR / ".deploy_cache"
+MANIFEST_FILE = DEPLOY_CACHE_DIR / "manifest.json"
+SPRINGBOOT_SCRIPT = "springboot.sh"
+MAVEN_MODULE = "jeecg-module-system/jeecg-system-start"
+MAVEN_PROFILE = "dev"
+
+if sys.platform == "win32" and hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+    sys.stderr.reconfigure(encoding="utf-8")
+
+
+def log(message: str) -> None:
+    print(f"[{datetime.now().strftime('%H:%M:%S')}] {message}")
+
+
+def fail(message: str, code: int = 1) -> None:
+    log(f"ERROR: {message}")
+    sys.exit(code)
+
+
+def expand_path(path_str: str) -> Path:
+    return Path(path_str).expanduser().resolve()
+
+
+def load_apm_config(apm_path: Path) -> dict[str, Any]:
+    with apm_path.open("r", encoding="utf-8") as handle:
+        data = json.load(handle)
+
+    name = str(data["name"]).strip()
+    deploy = data["wisdomDeploy"]
+    health = data["healthCheck"]
+
+    jar_path = str(deploy["jarPath"]).strip()
+    remote_app_dir = posixpath.dirname(jar_path)
+
+    return {
+        "project_name": name,
+        "host": deploy["host"],
+        "port": deploy["port"],
+        "username": deploy["username"],
+        "password": deploy["password"],
+        "remote_vue_dist_dir": str(deploy["remotePath"]).strip(),
+        "remote_app_dir": remote_app_dir,
+        "remote_lib_dir": posixpath.join(remote_app_dir, "lib"),
+        "startup_jar": posixpath.basename(jar_path),
+        "package_name": f"{name}.jar.zip",
+        "maven_local_repo": str(deploy["mavenLocalRepo"]).strip(),
+        "health_check_port": health["port"],
+        "health_check_context": health["context"],
+        "health_check_timeout": health["timeout"],
+    }
+
+
+def load_config() -> dict[str, Any]:
+    return load_apm_config(APM_CONFIG_PATH)
+
+
+def get_target_dir() -> Path:
+    return PROJECT_ROOT / MAVEN_MODULE / "target"
+
+
+def get_maven_local_repo(config: dict[str, Any]) -> Path:
+    return expand_path(str(config["maven_local_repo"]).strip())
+
+
+@dataclass
+class UpdateEntry:
+    path: Path
+    arcname: str
+    reason: str
+
+
+def relative_key(path: Path) -> str:
+    return path.resolve().relative_to(PROJECT_ROOT.resolve()).as_posix()
+
+
+def file_signature(path: Path) -> dict[str, float | int]:
+    stat = path.stat()
+    return {"size": int(stat.st_size), "mtime": float(stat.st_mtime)}
+
+
+def load_manifest() -> dict[str, dict[str, float | int]]:
+    if not MANIFEST_FILE.exists():
+        return {}
+    with MANIFEST_FILE.open("r", encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def save_manifest(manifest: dict[str, dict[str, float | int]]) -> None:
+    DEPLOY_CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    with MANIFEST_FILE.open("w", encoding="utf-8") as handle:
+        json.dump(manifest, handle, ensure_ascii=False, indent=2)
+
+
+def is_project_lib_jar(jar_name: str) -> bool:
+    return jar_name.startswith("jeecg-")
+
+
+def list_lib_files_to_upload(
+    local_lib_dir: Path,
+    remote_stats: dict[str, paramiko.SFTPAttributes],
+    *,
+    manifest: dict[str, dict[str, float | int]] | None = None,
+) -> list[UpdateEntry]:
+    entries: list[UpdateEntry] = []
+    for jar_file in sorted(local_lib_dir.glob("*.jar")):
+        remote_attr = remote_stats.get(jar_file.name)
+        should_upload, reason = should_upload_lib_file(
+            jar_file,
+            remote_attr,
+            manifest,
+        )
+        if should_upload:
+            entries.append(
+                UpdateEntry(
+                    path=jar_file,
+                    arcname=jar_file.name,
+                    reason=reason,
+                )
+            )
+    return entries
+
+
+def create_update_package(entries: list[UpdateEntry], package_name: str) -> Path:
+    DEPLOY_CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    zip_path = DEPLOY_CACHE_DIR / package_name
+
+    log(f"创建更新包: {zip_path.name}（{len(entries)} 个文件）")
+    with zipfile.ZipFile(zip_path, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+        for entry in entries:
+            archive.write(entry.path, arcname=entry.arcname)
+            log(f"  打包: {entry.arcname} ({entry.reason})")
+
+    return zip_path
+
+
+def upload_update_package(
+    sftp: paramiko.SFTPClient,
+    zip_path: Path,
+    config: dict[str, Any],
+) -> str:
+    remote_dir = config["remote_vue_dist_dir"]
+    remote_path = f"{remote_dir}/{zip_path.name}"
+
+    log(f"上传更新包 -> {remote_path}")
+
+    try:
+        sftp.put(str(zip_path), remote_path)
+        log("更新包上传成功")
+    except OSError as exc:
+        fail(f"更新包上传失败: {exc}")
+
+    return remote_path
+
+
+def update_manifest_entries(
+    manifest: dict[str, dict[str, float | int]],
+    entries: list[UpdateEntry],
+) -> dict[str, dict[str, float | int]]:
+    for entry in entries:
+        manifest[relative_key(entry.path)] = file_signature(entry.path)
+    return manifest
+
+
+def get_remote_file_stats(
+    sftp: paramiko.SFTPClient,
+    remote_dir: str,
+) -> dict[str, paramiko.SFTPAttributes]:
+    stats: dict[str, paramiko.SFTPAttributes] = {}
+    try:
+        for attr in sftp.listdir_attr(remote_dir):
+            if attr.filename.endswith(".jar"):
+                stats[attr.filename] = attr
+    except FileNotFoundError:
+        pass
+    return stats
+
+
+def should_upload_lib_file(
+    local_path: Path,
+    remote_attr: paramiko.SFTPAttributes | None,
+    manifest: dict[str, dict[str, float | int]] | None = None,
+) -> tuple[bool, str]:
+    if remote_attr is None:
+        return False, "远程不存在，跳过"
+
+    local_size = int(local_path.stat().st_size)
+    remote_size = int(remote_attr.st_size)
+    if local_size != remote_size:
+        return True, f"大小变化 {remote_size} -> {local_size}"
+
+    if is_project_lib_jar(local_path.name) and manifest is not None:
+        key = relative_key(local_path)
+        current = file_signature(local_path)
+        previous = manifest.get(key)
+        if previous is None:
+            return True, "项目模块未记录"
+        if int(previous["size"]) != current["size"]:
+            return True, "项目模块大小变化"
+        if float(previous["mtime"]) < current["mtime"]:
+            return True, "项目模块重新构建"
+
+    return False, "大小一致，跳过"
+
+
+def get_mvn_executable() -> str:
+    candidates = ("mvn.cmd", "mvn.bat", "mvn") if sys.platform == "win32" else ("mvn",)
+    for name in candidates:
+        found = shutil.which(name)
+        if found:
+            return found
+    fail("未找到 mvn 命令，请确认 Maven 已安装并加入 PATH")
+
+
+def run_maven_build(config: dict[str, Any]) -> None:
+    profile = MAVEN_PROFILE
+    maven_repo = get_maven_local_repo(config)
+    cmd = [
+        get_mvn_executable(),
+        "clean",
+        "package",
+        f"-P{profile}",
+        f"-Dmaven.repo.local={maven_repo}",
+        "-DskipTests",
+    ]
+
+    log(f"开始 Maven 构建: {' '.join(cmd)}")
+    log(f"Maven 本地仓库: {maven_repo}")
+    result = subprocess.run(
+        cmd,
+        cwd=PROJECT_ROOT,
+    )
+    if result.returncode != 0:
+        fail(f"Maven 构建失败，退出码: {result.returncode}")
+
+
+def locate_lib_dir() -> Path:
+    target_dir = get_target_dir()
+    if not target_dir.exists():
+        fail(f"构建产物目录不存在: {target_dir}")
+
+    lib_dir = target_dir / "lib"
+    if not lib_dir.is_dir():
+        fail(f"lib 目录不存在: {lib_dir}")
+
+    lib_jars = list(lib_dir.glob("*.jar"))
+    if not lib_jars:
+        fail(f"lib 目录下没有依赖 JAR: {lib_dir}")
+
+    log(f"定位 lib 产物: {len(lib_jars)} 个")
+    return lib_dir
+
+
+def connect_ssh(config: dict[str, Any]) -> paramiko.SSHClient:
+    client = paramiko.SSHClient()
+    client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
+
+    log(f"连接服务器 {config['username']}@{config['host']}:{config['port']}")
+    connect_kwargs: dict[str, Any] = {
+        "hostname": config["host"],
+        "port": int(config["port"]),
+        "username": config["username"],
+        "password": config["password"],
+        "timeout": 30,
+        "allow_agent": False,
+        "look_for_keys": False,
+    }
+
+    try:
+        client.connect(**connect_kwargs)
+    except Exception as exc:
+        fail(f"SSH 连接失败: {exc}")
+
+    return client
+
+
+def read_channel_stream(channel: paramiko.Channel) -> str:
+    """流式读取 SSH 通道输出，避免长时间命令无回显。"""
+    chunks: list[str] = []
+    while not channel.closed:
+        if channel.recv_ready():
+            data = channel.recv(4096)
+            if not data:
+                break
+            text = data.decode("utf-8", errors="replace")
+            chunks.append(text)
+            print(text, end="", flush=True)
+        elif channel.exit_status_ready():
+            while channel.recv_ready():
+                data = channel.recv(4096)
+                if data:
+                    text = data.decode("utf-8", errors="replace")
+                    chunks.append(text)
+                    print(text, end="", flush=True)
+            break
+        else:
+            time.sleep(0.2)
+
+    combined = "".join(chunks)
+    if combined and not combined.endswith("\n"):
+        print()
+    return combined.strip()
+
+
+def run_remote_command(
+    client: paramiko.SSHClient,
+    command: str,
+    *,
+    check: bool = True,
+    get_pty: bool = False,
+    stream: bool = False,
+    timeout_secs: float | None = None,
+) -> tuple[int, str, str]:
+    log(f"远程执行: {command}")
+    _, stdout, stderr = client.exec_command(command, get_pty=get_pty)
+    channel = stdout.channel
+    if timeout_secs is not None:
+        channel.settimeout(timeout_secs)
+
+    if stream:
+        out = read_channel_stream(channel)
+        err = ""
+    else:
+        out = stdout.read().decode("utf-8", errors="replace").strip()
+        err = "" if get_pty else stderr.read().decode("utf-8", errors="replace").strip()
+
+    exit_code = channel.recv_exit_status()
+
+    if not stream:
+        if out:
+            print(out)
+        if err:
+            print(err, file=sys.stderr)
+
+    if check and exit_code != 0:
+        fail(f"远程命令失败 (exit {exit_code}): {command}")
+
+    return exit_code, out, err
+
+
+def extract_update_package_on_remote(
+    client: paramiko.SSHClient,
+    config: dict[str, Any],
+    remote_zip_path: str,
+) -> int:
+    """解压更新包到 lib 目录，仅覆盖远程已存在的 JAR。"""
+    remote_lib_dir = config["remote_lib_dir"]
+    quoted_zip = shlex.quote(remote_zip_path)
+    quoted_lib = shlex.quote(remote_lib_dir)
+
+    script = f"""
+set -e
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+unzip -oq {quoted_zip} -d "$TMP"
+updated=0
+while IFS= read -r -d '' src; do
+  name=$(basename "$src")
+  dest={quoted_lib}/"$name"
+  if [ -f "$dest" ]; then
+    cp -f "$src" "$dest"
+    echo "覆盖: $name"
+    updated=$((updated + 1))
+  else
+    echo "跳过(远程不存在): $name"
+  fi
+done < <(find "$TMP" -name '*.jar' -type f -print0)
+echo "UPDATED_COUNT=$updated"
+"""
+
+    _, out, _ = run_remote_command(client, script)
+    match = re.search(r"UPDATED_COUNT=(\d+)", out)
+    if not match:
+        fail(f"远程解压失败，未获取更新数量\n输出: {out or '(空)'}")
+
+    updated = int(match.group(1))
+    log(f"lib 解压完成: 覆盖 {updated} 个")
+    return updated
+
+
+def springboot_output_indicates_success(action: str, combined: str) -> bool:
+    """springboot.sh 经 SSH 执行时 exit code 不可靠，需结合输出判断。"""
+    lower = combined.lower()
+    if action == "health":
+        return "健康检查通过" in combined
+    if action in {"start", "restart"}:
+        return "is starting" in combined or "is running" in lower
+    if action == "stop":
+        return (
+            "is stopping" in combined
+            or "not running" in lower
+            or "please check it" in lower
+        )
+    if action == "status":
+        return "running" in lower or "not running" in lower
+    return True
+
+
+def run_springboot_action(
+    client: paramiko.SSHClient,
+    config: dict[str, Any],
+    action: str,
+    *args: str,
+) -> str:
+    if action in {"start", "restart"}:
+        if not args:
+            fail(f"远程 {action} 缺少 jar 参数")
+        jar = args[0].strip().splitlines()[0].strip()
+        if not jar:
+            fail(f"无效的 jar 名称: {args[0]!r}")
+
+    command = " && ".join(
+        [
+            f"cd {shlex.quote(config['remote_app_dir'])}",
+            " ".join(
+                [f"./{SPRINGBOOT_SCRIPT}", *map(shlex.quote, (action, *args))]
+            ),
+        ]
+    )
+    exit_code, out, err = run_remote_command(
+        client,
+        command,
+        check=False,
+    )
+    combined = f"{out}\n{err}".strip()
+    output_ok = springboot_output_indicates_success(action, combined)
+    if action == "health":
+        if exit_code != 0 or not output_ok:
+            fail(
+                f"健康检查失败\n"
+                f"命令: {command}\n输出: {combined or '(空)'}"
+            )
+        return combined
+    if exit_code != 0 and not output_ok:
+        fail(f"远程 {action} 失败: {' '.join(args)}\n{combined}")
+    if action in {"start", "restart"} and not output_ok:
+        fail(
+            f"远程 {action} 未成功: {' '.join(args)}\n"
+            f"命令: {command}\n输出: {combined or '(空)'}"
+        )
+    return combined
+
+
+def get_running_jar(
+    client: paramiko.SSHClient,
+    app_dir: str,
+    config: dict[str, Any],
+) -> str | None:
+    combined = run_springboot_action(
+        client, config, "status", config["startup_jar"]
+    )
+    text = re.sub(r"\x1b\[[0-?]*[ -/]*[@-~]", "", combined).strip().lower()
+    if "not running" in text:
+        return None
+    if "running" in text:
+        return config["startup_jar"]
+    return None
+
+
+def health_check_service(
+    client: paramiko.SSHClient,
+    config: dict[str, Any],
+) -> None:
+    port = str(int(config["health_check_port"]))
+    context = str(config["health_check_context"]).strip()
+    timeout = str(int(config["health_check_timeout"]))
+    log(f"健康检查: springboot.sh health {port} {context} {timeout}")
+    run_springboot_action(client, config, "health", port, context, timeout)
+
+
+def main() -> None:
+    config = load_config()
+
+    log(f"=== 自动部署: {config['project_name']} ===")
+    log(f"配置文件: {APM_CONFIG_PATH}")
+    log(f"项目根目录: {PROJECT_ROOT}")
+
+    run_maven_build(config)
+
+    lib_dir = locate_lib_dir()
+    manifest = load_manifest()
+
+    client = connect_ssh(config)
+    need_restart = False
+    lib_upload_entries: list[UpdateEntry] = []
+    try:
+        sftp = client.open_sftp()
+        try:
+            app_dir = config["remote_app_dir"]
+            remote_lib_stats = get_remote_file_stats(sftp, config["remote_lib_dir"])
+
+            log("收集 JAR 更新...")
+            lib_upload_entries = list_lib_files_to_upload(
+                lib_dir,
+                remote_lib_stats,
+                manifest=manifest,
+            )
+
+            updated = 0
+            if lib_upload_entries:
+                zip_path = create_update_package(
+                    lib_upload_entries,
+                    config["package_name"],
+                )
+                remote_zip_path = upload_update_package(sftp, zip_path, config)
+                log("远程解压 lib 目录（仅覆盖已有 JAR）...")
+                updated = extract_update_package_on_remote(
+                    client,
+                    config,
+                    remote_zip_path,
+                )
+            else:
+                log("无 JAR 需要更新，跳过更新包上传")
+
+            running_jar = get_running_jar(client, app_dir, config)
+            need_restart = updated > 0
+            if not need_restart and not running_jar:
+                log("服务未运行，需要启动")
+                need_restart = True
+            elif not need_restart:
+                log("没有文件需要更新，跳过重启")
+
+            if need_restart:
+                log("重启服务...")
+                run_springboot_action(client, config, "restart", config["startup_jar"])
+
+            health_check_service(client, config)
+
+            if lib_upload_entries:
+                save_manifest(update_manifest_entries(manifest, lib_upload_entries))
+        finally:
+            sftp.close()
+    finally:
+        client.close()
+
+    log("部署完成")
+
+
+if __name__ == "__main__":
+    main()

package/template/rules/write_doc.md

@@ -21,7 +21,10 @@
 固定文件名: `SQL.md`
 保存位置: `.apm/sessions/<会话 ID>/docs/SQL.md`
 适用场景: 后端开发涉及 SQL 改动（DDL/DML、表结构、Mapper/XML 中 SQL 等）时必须产出或追加更新，详见 `.apm/skills/apm-dev/SKILL.md` 中「后端 SQL 变更文档」章节。
-格式要求: 待执行的 SQL 语句须放在 ` ```sql ` 代码块中，按执行顺序逐条列出。
+格式要求:
+
+- 须标注**目标数据库**（库名/实例名、类型如 MySQL；同一变更涉及多库时分别标注）
+- 待执行的 SQL 语句须放在 ` ```sql ` 代码块中，按执行顺序逐条列出
 
 ## 文档同步
 

package/template/skills/apm-dev/SKILL.md

@@ -5,7 +5,7 @@
 ### 步骤 1: 获取实现计划与协作内容
 
 1. 用 **Read** 工具阅读本端计划：前端读 `.apm/sessions/<会话ID>/docs/FRONTEND-PLAN.md`，后端读 `docs/BACKEND-PLAN.md`；计划不存在则退出流程并回复说明（兼容旧流程：若存在 `PRD.md` + `FRONTEND.md` / `BACKEND.md` + `API.md`，按旧文档执行）。
-2. 前端涉及接口对接时，以后端计划中的「API 契约」章节为准，**不等后端部署完成**；契约没写清的字段 `@后端` 确认，禁止自行猜测。
+2. 前端涉及接口对接时，以 `docs/API.md` 为唯一契约来源，**不等后端部署完成**；`API.md` 不存在或字段没写清时 `@后端` 补充，禁止自行猜测或在计划中重复编写接口定义。
 3. **假设门禁（开发前必须检查）**：查看计划「依据与假设」章节——
    - 「假设」仍有未确认项：**Read** `.apm/sessions/<会话ID>/messages.xml`，查找项目经理是否已回复确认；
    - 项目经理已回复：先按 `.apm/skills/apm-write-plan/SKILL.md` 步骤 5 把确认结果**回填进计划文档并同步**（确认的假设移入「依据」，否定的修订实现步骤与白名单），然后再开发；
@@ -50,6 +50,7 @@
 
 若本次改动涉及 SQL（DDL/DML、表结构、索引、数据修复、Mapper/XML 中新增或修改 SQL 语句等），开发阶段必须 **Write** `.apm/sessions/<会话ID>/docs/SQL.md`，内容包括：
 
+- **目标数据库**（库名/实例名、类型如 MySQL；同一变更涉及多库时分别标注）
 - 变更摘要（改了什么表/数据、为什么）
 - 完整 SQL 语句（按执行顺序排列；**每条须放在 ` ```sql ` 代码块中**，便于复制执行）
 - 执行环境说明（测试/生产是否一致、是否需人工执行）
@@ -58,6 +59,10 @@
 示例：
 
 ````markdown
+## 目标数据库
+
+`oxc_platform`（MySQL 8.x）
+
 ## 变更摘要
 
 为 inspection_class 表新增 is_project_add 字段。
@@ -84,6 +89,6 @@ ALTER TABLE inspection_class ADD COLUMN is_project_add VARCHAR(1) DEFAULT '0';
 2. **发布测试环境**：**Read** `.apm/skills/apm-deploy/SKILL.md` 并按其流程部署；**后端**涉及 SQL 变更时，须在回复中引用 `docs/SQL.md`，并写明待执行的 SQL 文件名或执行顺序。
 3. **白名单对账**：在回复中逐文件列出本次改动与计划白名单的对应关系。
 
-**注意：不做联调。** 前后端各自按 API 契约交付，接口对不上属于契约或实现问题，由 diff 评审与人工验收暴露后打回修复；禁止自行发起「联调」「接口实测」类的开放式动作。
+**注意：不做联调。** 前后端各自按 `API.md` 交付，接口对不上属于契约或实现问题，由 diff 评审与人工验收暴露后打回修复；禁止自行发起「联调」「接口实测」类的开放式动作。
 
 完成后用 `append_message` 回复：改动概述 + 白名单对账 + 构建结果 + 测试环境地址，并 `@` 评审角色进行 diff 评审。

package/template/skills/apm-diff-review/SKILL.md

@@ -18,12 +18,12 @@
 
 ### 步骤 2：四项检查
 
-| 检查项         | 判定                                                                                                                      |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| **白名单对账** | diff 中出现白名单之外的文件，且计划未更新说明 → **不通过**                                                                |
-| **需求相关性** | 存在与本需求无关的改动（顺手重构、改格式、动了无关逻辑）→ **不通过**                                                      |
-| **计划落实**   | 计划「实现步骤」中的关键点在 diff 中找不到对应实现 → **不通过**                                                           |
-| **SQL 文档**   | **仅后端**：diff 涉及 SQL 改动（DDL/DML、表结构、Mapper/XML 中 SQL 等），但 `docs/SQL.md` 缺失或与改动不一致 → **不通过** |
+| 检查项         | 判定                                                                                                                                          |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| **白名单对账** | diff 中出现白名单之外的文件，且计划未更新说明 → **不通过**                                                                                    |
+| **需求相关性** | 存在与本需求无关的改动（顺手重构、改格式、动了无关逻辑）→ **不通过**                                                                          |
+| **计划落实**   | 计划「实现步骤」中的关键点在 diff 中找不到对应实现 → **不通过**                                                                               |
+| **SQL 文档**   | **仅后端**：diff 涉及 SQL 改动（DDL/DML、表结构、Mapper/XML 中 SQL 等），但 `docs/SQL.md` 缺失、未标注目标数据库、或与改动不一致 → **不通过** |
 
 注意事项：