noc-ops 0.1.0__py3-none-any.whl

noc_ops/__init__.py

@@ -0,0 +1,2 @@
+"""noc_ops —— 多云运维 ops CLI（自然语言 agent + 同步 + 看板 + MCP）。"""
+__version__ = "0.1.0"

noc_ops/agent.py

@@ -0,0 +1,486 @@
+#!/usr/bin/env python3
+"""自然语言 AWS 运维 Agent（Claude Agent SDK 实现）。
+
+用法：
+    python agent.py "重启东京的 openclaw"      # 一次性指令
+    python agent.py                              # 进入交互模式（日常运维 + 沉淀 runbook）
+
+设计：Runbook 驱动。
+- inventory.md  : 操作对象清单（实例名 → id / region / profile）
+- runbooks/*.md     : 能力库，Agent 执行前先查有没有对应剧本
+- 安全闸门          : 只读操作自动执行；写操作（启停/重启/远程命令/写文件）先确认
+"""
+import asyncio
+import json
+import os
+import re
+import subprocess
+import shlex
+import sys
+
+from claude_agent_sdk import (
+    ClaudeSDKClient,
+    ClaudeAgentOptions,
+    AssistantMessage,
+    ResultMessage,
+    TextBlock,
+    ToolUseBlock,
+    tool,
+    create_sdk_mcp_server,
+)
+from claude_agent_sdk.types import PermissionResultAllow, PermissionResultDeny
+
+from . import deploy_config
+from . import ops_log
+from . import paths
+from . import schedule_ops
+from .aws_safety import is_read_only_ssh
+from .error_patterns import annotate
+from .providers import PROVIDERS
+
+# CLI 二进制 → cloud（单一来源=Provider 注册表，加云自动跟上；别再手写字典——漏一处写操作就绕过闸门）
+_CLI_CLOUD = {p.cli: c for c, p in PROVIDERS.items() if p.cli}
+# 工具名后缀 → cloud（用于权限闸门按 provider 分类）。AWS 的工具叫 aws_cli（二进制 aws），单独映射
+_TOOL_CLOUD = {"__aws_cli": "aws", **{"__" + cli: c for cli, c in _CLI_CLOUD.items() if cli != "aws"}}
+
+MODEL = os.environ.get("OPS_MODEL") or deploy_config.model()   # env 优先，否则读 ops-config.toml
+
+# ---------------------------------------------------------------------------
+# 自定义工具
+# ---------------------------------------------------------------------------
+
+def _run_cli(binary: str, command: str) -> dict:
+    """跑一条云 CLI（binary 之后的参数）。各云 CLI 工具共用。写操作记入 ops 操作日志。"""
+    command = command.strip()
+    if command.startswith(binary + " "):
+        command = command[len(binary) + 1:]
+    cloud = _CLI_CLOUD.get(binary, binary)
+    p = PROVIDERS.get(cloud)
+    is_write = bool(p) and not p.is_read(command)   # 写操作（含重启）才记日志，只读不记
+    try:
+        argv = [binary, *shlex.split(command)]
+    except ValueError as e:
+        if is_write:
+            ops_log.record("agent", "cli", cloud=cloud, detail=command, result="parse-error")
+        return {"content": [{"type": "text", "text": f"命令解析失败: {e}"}], "is_error": True}
+    try:
+        r = subprocess.run(argv, capture_output=True, text=True, timeout=120,
+                           env={**os.environ, "AWS_PAGER": ""})
+    except subprocess.TimeoutExpired:
+        if is_write:
+            ops_log.record("agent", "cli", cloud=cloud, detail=command, result="timeout")
+        return {"content": [{"type": "text", "text": f"{binary} 命令超时(120s)"}], "is_error": True}
+    out = (r.stdout or "") + (("\n[stderr]\n" + r.stderr) if r.stderr else "")
+    if is_write:
+        ops_log.record("agent", "cli", cloud=cloud, detail=command,
+                       result="ok" if r.returncode == 0 else f"exit{r.returncode}")
+    if r.returncode != 0:
+        return {"content": [{"type": "text", "text": annotate(f"退出码 {r.returncode}\n{out}")}], "is_error": True}
+    return {"content": [{"type": "text", "text": out or "(无输出)"}]}
+
+
+@tool(
+    "aws_cli",
+    "执行一条 AWS CLI 命令。传入的是 'aws' 之后的参数（不含开头的 aws）。"
+    "必须显式带上 --profile 和 --region（取自 inventory.md）。"
+    "例如 command='ec2 describe-instances --profile <账号> --region <区域>'（账号/区域取自 inventory.md）",
+    {"command": str},
+)
+async def aws_cli(args: dict) -> dict:
+    return _run_cli("aws", args["command"])
+
+
+@tool(
+    "tccli",
+    "执行一条腾讯云 CLI (tccli) 命令，用于操作腾讯云资源（如南京 Lighthouse）。"
+    "传入 'tccli' 之后的参数，**必须带 --region**。"
+    "例：command='lighthouse DescribeInstances --region ap-nanjing'；"
+    "重启：command='lighthouse RebootInstances --InstanceIds <lhins-xxx> --region <区域>'",
+    {"command": str},
+)
+async def tccli(args: dict) -> dict:
+    return _run_cli("tccli", args["command"])
+
+
+@tool(
+    "aliyun",
+    "执行一条阿里云 CLI 命令，操作阿里云资源（如 ECS）。"
+    "传入 'aliyun' 之后的参数，**必须带 --RegionId 和 --profile**（profile/区域取自 inventory.md）。"
+    "例：command='ecs DescribeInstances --RegionId <区域> --profile <profile>'；"
+    "重启：command='ecs RebootInstance --InstanceId <i-xxx> --RegionId <区域> --profile <profile>'",
+    {"command": str},
+)
+async def aliyun(args: dict) -> dict:
+    return _run_cli("aliyun", args["command"])
+
+
+@tool(
+    "ve",
+    "执行一条火山引擎 CLI (ve) 命令，操作火山引擎资源（如 ECS）。"
+    "传入 've' 之后的参数，**必须带 --region**（区域取自 inventory.md）。列表参数用点号下标：--InstanceIds.1 <id>。"
+    "例：command='ecs DescribeInstances --region cn-beijing'；"
+    "重启：command='ecs RebootInstance --InstanceId <i-xxx> --region <区域>'",
+    {"command": str},
+)
+async def ve(args: dict) -> dict:
+    return _run_cli("ve", args["command"])
+
+
+@tool(
+    "gcloud",
+    "执行一条 Google Cloud CLI (gcloud) 命令，操作 GCP 资源（如 Compute Engine 实例）。"
+    "传入 'gcloud' 之后的参数，**必须带 --project**（项目 id 取自 inventory.md）。"
+    "例：command='compute instances list --project <项目>'；"
+    "重启(硬reset，免确认)：command='compute instances reset <名> --zone <zone> --project <项目>'；"
+    "停止/启动(需确认)：command='compute instances stop|start <名> --zone <zone> --project <项目>'",
+    {"command": str},
+)
+async def gcloud(args: dict) -> dict:
+    return _run_cli("gcloud", args["command"])
+
+
+@tool(
+    "az",
+    "执行一条 Microsoft Azure CLI (az) 命令，操作 Azure 资源（如虚拟机 VM）。"
+    "传入 'az' 之后的参数，**必须带 --subscription**（订阅 id 取自 inventory.md）。"
+    "例：command='vm list --subscription <订阅> --show-details -o json'；"
+    "重启(优雅 restart，免确认)：command='vm restart --name <名> --resource-group <rg> --subscription <订阅>'；"
+    "停止/启动(需确认)：command='vm stop|start --name <名> --resource-group <rg> --subscription <订阅>'。"
+    "注意 Azure VM 操作要 **--name + --resource-group**（不是单一 id）。",
+    {"command": str},
+)
+async def az(args: dict) -> dict:
+    return _run_cli("az", args["command"])
+
+
+# 用密码（非密钥）登录的主机：密码存 macOS Keychain，绝不写进代码/文件；命中则用 sshpass+Keychain。
+# 默认为空（密钥登录走 ssh config 别名）；如有口令登录主机在 ops-config.toml 的 [agent.password_hosts] 配置。保留机制以备将来。
+PASSWORD_HOSTS = deploy_config.password_hosts()
+
+
+@tool(
+    "ssh_exec",
+    "通过 SSH 在远程主机上执行一条命令。target 用 ~/.ssh/config 的 Host 别名 / user@host。"
+    "当前所有纳管主机均密钥登录；密码登录机制保留备用（命中 PASSWORD_HOSTS 时用 sshpass+Keychain，现为空）。"
+    "command 是要在远程执行的命令。AWS 内网实例经跳板机（ssh config 里 ProxyJump）。",
+    {"target": str, "command": str},
+)
+async def ssh_exec(args: dict) -> dict:
+    target = args["target"].strip()
+    command = args["command"]
+    env = dict(os.environ)
+    if target in PASSWORD_HOSTS:
+        h = PASSWORD_HOSTS[target]
+        pw = subprocess.run(
+            ["security", "find-generic-password", "-a", h["kc_account"], "-s", h["kc_service"], "-w"],
+            capture_output=True, text=True,
+        ).stdout.strip()
+        if not pw:
+            return {"content": [{"type": "text", "text": f"从 Keychain 取 {target} 密码失败"}], "is_error": True}
+        env["SSHPASS"] = pw  # 用 -e 走环境变量，避免密码出现在进程参数里
+        argv = ["sshpass", "-e", "ssh", "-o", "StrictHostKeyChecking=no",
+                "-o", "ConnectTimeout=10", f"{h['user']}@{h['host']}", command]
+    else:
+        argv = ["ssh", "-o", "BatchMode=yes", "-o", "ConnectTimeout=10", target, command]
+    is_write = not is_read_only_ssh(command)   # SSH 写操作才记日志
+    try:
+        r = subprocess.run(argv, capture_output=True, text=True, timeout=120, env=env)
+    except subprocess.TimeoutExpired:
+        if is_write:
+            ops_log.record("agent", "ssh", target=target, detail=command, result="timeout")
+        return {"content": [{"type": "text", "text": "ssh 命令超时(120s)"}], "is_error": True}
+    out = (r.stdout or "") + (("\n[stderr]\n" + r.stderr) if r.stderr else "")
+    if is_write:
+        ops_log.record("agent", "ssh", target=target, detail=command,
+                       result="ok" if r.returncode == 0 else f"exit{r.returncode}")
+    if r.returncode != 0:
+        return {"content": [{"type": "text", "text": annotate(f"退出码 {r.returncode}\n{out}")}], "is_error": True}
+    return {"content": [{"type": "text", "text": out or "(无输出)"}]}
+
+
+# ---------------------------------------------------------------------------
+# 计划任务（定时重启）：AWS EventBridge Scheduler，云端到点执行，本机不常驻
+# ---------------------------------------------------------------------------
+DATA_JSON = paths.data_json_path()
+
+
+def _ok(text):
+    return {"content": [{"type": "text", "text": text}]}
+
+
+def _err(text):
+    return {"content": [{"type": "text", "text": text}], "is_error": True}
+
+
+def _find_inst(id_or_name):
+    try:
+        d = json.loads(DATA_JSON.read_text())
+    except (OSError, json.JSONDecodeError):
+        return None
+    for i in d.get("instances", []):
+        if i.get("id") == id_or_name or i.get("name") == id_or_name:
+            return i
+    return None
+
+
+@tool(
+    "schedule_task",
+    "创建定时重启实例的计划任务（云端到点执行，本机不用常驻）。支持 AWS / 腾讯 / 阿里。"
+    "instance=实例名或 ID；schedule=一次性本地时间 ISO（如 2026-06-06T22:30:00，按北京时间）"
+    "或循环的 5 段标准 crontab（分 时 日 月 周，如 '30 22 * * *' 表示每天 22:30，'0 3 * * *' 每天凌晨3点）。"
+    "今天日期见系统提示；把口语时间换算成确切 ISO 或 crontab。目标解析不到或该账号未接入会如实回报。",
+    {"instance": str, "schedule": str},
+)
+async def schedule_task(args):
+    inst = _find_inst(args["instance"].strip())
+    if not inst:
+        return _err(f"未找到实例「{args['instance']}」，请先确认实例名或 ID（可先 list/Read inventory）。")
+    if not schedule_ops.is_supported(inst.get("cloud"), inst.get("profile")):
+        return _err(schedule_ops.unsupported_reason(inst.get("cloud"), inst.get("profile")))
+    sched = args["schedule"].strip()
+    one_off = bool(re.match(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}", sched))
+    ok, res = schedule_ops.create_reboot(
+        inst["cloud"], inst["profile"], inst["region"], inst["id"], inst["name"],
+        when=sched if one_off else None, crontab=None if one_off else sched)
+    kind = "一次性" if one_off else "循环"
+    ops_log.record("agent", "schedule_task", target=inst["name"], cloud=inst["cloud"],
+                   detail=f"{kind}重启 @ {sched}", result="ok" if ok else "fail")
+    if not ok:
+        return _err(annotate(f"创建定时任务失败：{res}"))
+    return _ok(f"✅ 已创建{kind}定时重启：{inst['name']} ({inst['id']}, {inst['cloud']}) "
+               f"@ {sched} [{schedule_ops.DISPLAY_TZ}]\n标识：{res}")
+
+
+@tool(
+    "list_scheduled_tasks",
+    "列出当前所有计划任务（定时重启），含目标实例 / 时间或循环表达式 / 状态。",
+    {},
+)
+async def list_scheduled_tasks(args):
+    rows = schedule_ops.list_all()
+    if not rows:
+        return _ok("当前没有计划任务。")
+    tzlabel = lambda tz: schedule_ops.DISPLAY_TZ if tz == "Asia/Shanghai" else tz
+    lines = [f"- {r['name']}：{r['kind']}重启 {r['instance']}({r['instance_id']}) "
+             f"@ {r['expr']} [{tzlabel(r['timezone'])}] {r['state']}" for r in rows]
+    return _ok("当前计划任务：\n" + "\n".join(lines))
+
+
+@tool(
+    "cancel_scheduled_task",
+    "取消（删除）一条计划任务。name 取自 list_scheduled_tasks 返回的调度名。",
+    {"name": str},
+)
+async def cancel_scheduled_task(args):
+    name = args["name"].strip()
+    row = next((r for r in schedule_ops.list_all() if r["name"] == name), None)
+    if not row:
+        return _err(f"未找到计划任务「{name}」，先用 list_scheduled_tasks 确认。")
+    ok, out = schedule_ops.delete_row(row)
+    ops_log.record("agent", "cancel_task", target=row.get("instance", name),
+                   cloud=row.get("cloud", ""), detail=name, result="ok" if ok else "fail")
+    return _ok(f"✅ 已取消计划任务 {name}") if ok else _err(annotate(f"取消失败：{out}"))
+
+
+ops_server = create_sdk_mcp_server(
+    name="ops", version="1.0.0",
+    tools=[aws_cli, tccli, aliyun, ve, gcloud, az, ssh_exec,
+           schedule_task, list_scheduled_tasks, cancel_scheduled_task])
+
+# ---------------------------------------------------------------------------
+# 权限闸门：只读自动执行，写操作先确认
+# ---------------------------------------------------------------------------
+
+AUTO_ALLOW = {"Read", "Glob", "Grep", "TodoWrite"}
+
+
+async def _confirm(summary: str, detail: str) -> bool:
+    print(f"\n\033[33m⚠️  需要确认：{summary}\033[0m")
+    print(f"    {detail}")
+    ans = (await asyncio.to_thread(input, "    执行？(y/N) ")).strip().lower()
+    return ans in ("y", "yes")
+
+
+async def can_use_tool(tool_name: str, input_data: dict, context) -> object:
+    # 纯只读内置工具：直接放行
+    if tool_name in AUTO_ALLOW:
+        return PermissionResultAllow(updated_input=input_data)
+
+    # 各云 CLI：只读 + 实例重启 自动执行；其余写操作确认（按 tool 名查 provider）
+    for suffix, cloud in _TOOL_CLOUD.items():
+        if tool_name.endswith(suffix):
+            p = PROVIDERS[cloud]
+            cmd = input_data.get("command", "")
+            if p.is_read(cmd) or p.is_reboot(cmd):
+                return PermissionResultAllow(updated_input=input_data)
+            if await _confirm(f"{p.display} 写操作", f"{p.cli} {cmd}"):
+                return PermissionResultAllow(updated_input=input_data)
+            return PermissionResultDeny(message=f"用户拒绝了该 {p.display} 写操作")
+
+    # SSH：按远程命令读/写分类
+    if tool_name.endswith("__ssh_exec"):
+        cmd = input_data.get("command", "")
+        target = input_data.get("target", "?")
+        if is_read_only_ssh(cmd):
+            return PermissionResultAllow(updated_input=input_data)
+        if await _confirm("远程命令", f"{target}: {cmd}"):
+            return PermissionResultAllow(updated_input=input_data)
+        return PermissionResultDeny(message="用户拒绝了该远程命令")
+
+    # 计划任务：列出=只读放行；创建/取消=写操作，确认（到点云端自动执行，确认机会只在此刻）
+    if tool_name.endswith("__list_scheduled_tasks"):
+        return PermissionResultAllow(updated_input=input_data)
+    if tool_name.endswith("__schedule_task"):
+        if await _confirm("创建定时任务",
+                          f"重启 {input_data.get('instance')} @ {input_data.get('schedule')}（到点云端自动执行）"):
+            return PermissionResultAllow(updated_input=input_data)
+        return PermissionResultDeny(message="用户拒绝创建定时任务")
+    if tool_name.endswith("__cancel_scheduled_task"):
+        if await _confirm("取消定时任务", input_data.get("name", "")):
+            return PermissionResultAllow(updated_input=input_data)
+        return PermissionResultDeny(message="用户拒绝取消定时任务")
+
+    # 写文件（含沉淀 runbook）：确认
+    if tool_name in ("Write", "Edit", "MultiEdit", "NotebookEdit"):
+        path = input_data.get("file_path", "?")
+        if await _confirm("写文件", path):
+            return PermissionResultAllow(updated_input=input_data)
+        return PermissionResultDeny(message="用户拒绝了写文件")
+
+    # 其它一律确认
+    if await _confirm(f"工具 {tool_name}", str(input_data)[:300]):
+        return PermissionResultAllow(updated_input=input_data)
+    return PermissionResultDeny(message="用户拒绝")
+
+
+# ---------------------------------------------------------------------------
+# 系统提示词
+# ---------------------------------------------------------------------------
+
+SYSTEM_PROMPT = """\
+你是用户的 AWS 运维助手，用自然语言指令操作其 EC2 机群。用简体中文回复，简洁直接。
+
+## 你的工作方式
+你不是固定按钮，而是有判断力的运维工程师——这正是用 LLM 做运维的意义。用户的描述可能不准确、有遗漏、甚至有错；你要用理解力推断真实意图，主动核对，信息不全或有歧义时**多轮追问澄清**，把任务问明确后再执行，用脑子兜住各种异常，而不是机械照字面执行或直接拒绝。
+这与"动手要稳"并不矛盾，把握一个平衡：**理解要大胆、动手要谨慎**——解析意图时尽量替用户想周全，但真正落到写操作前，必须确切定位目标并经确认（见下两节）。
+
+## 工作目录与资料
+当前工作目录是项目根目录。两份关键资料：
+- `inventory.md`：实例清单。**任何涉及具体实例的操作，先 Read 它**，把用户口中的实例名（如"东京的 openclaw"）解析成确切的 实例ID / region / profile。
+- `runbooks/` 目录：能力库（运维剧本）。**动手前先 Glob `runbooks/*.md` 看有没有对应剧本**，有就按剧本执行。
+
+## 可用工具
+这是**多云**运维（AWS + 腾讯云 + 阿里云 + 火山引擎 + Google Cloud + Microsoft Azure），按云选对工具（inventory 里每台实例有 `cloud` 字段 aws/tencent/aliyun/volcengine/gcp/azure 标明归属，别搞混）：
+- `aws_cli`：AWS CLI（传 aws 之后参数）。**务必带 --profile 和 --region**。
+- `tccli`：腾讯云 CLI（如 Lighthouse）。**带 --region**。重启：`lighthouse RebootInstances --InstanceIds <id> --region <区域>`。
+- `aliyun`：阿里云 CLI（如 ECS）。**带 --RegionId 和 --profile**。重启：`ecs RebootInstance --InstanceId <id> --RegionId <区域> --profile <profile>`。
+- `ve`：火山引擎 CLI（如 ECS）。**带 --region**。重启：`ecs RebootInstance --InstanceId <id> --region <区域>`；列表参数点号下标 `--InstanceIds.1 <id>`。
+- `gcloud`：Google Cloud CLI（如 Compute Engine）。**带 --project**。重启(硬reset，免确认)：`compute instances reset <名> --zone <zone> --project <项目>`；停/启(需确认)：`compute instances stop|start <名> --zone <zone> --project <项目>`。注意 GCE 用**实例名**+ zone（不是 id）。
+- `az`：Microsoft Azure CLI（如虚拟机 VM）。**带 --subscription**。重启(优雅 restart，免确认)：`vm restart --name <名> --resource-group <rg> --subscription <订阅>`；停/启(需确认)：`vm stop|start --name <名> --resource-group <rg> --subscription <订阅>`。注意 Azure VM 用**实例名 + 资源组**（不是单一 id）。
+- `ssh_exec`：经 SSH 执行命令。一律用 inventory「SSH 连接」里的 ssh config 别名（内网经跳板，全部密钥登录）。
+- 内置 Read/Glob/Grep：读 inventory、查 runbook；Write/Edit：沉淀 runbook、更新文档。
+- `schedule_task` / `list_scheduled_tasks` / `cancel_scheduled_task`：**计划任务（定时重启）**。用 AWS EventBridge Scheduler 云端到点执行，本机不常驻。
+
+## 计划任务（定时重启）
+用户说「今晚 10:30 重启 prd-docker」「每天凌晨 3 点重启 X」这类，用 `schedule_task`：
+- 把口语时间换算成确切值（今天日期见上下文，**一律北京时间 UTC+8**）：一次性→ISO 如 `2026-06-06T22:30:00`；循环→**5 段标准 crontab**（分 时 日 月 周）如 `30 22 * * *`（每天 22:30）、`0 3 * * *`（每天 03:00）、`0 4 * * 1`（每周一 04:00）。
+- **支持 AWS / 腾讯 / 阿里**，全部是**云 API 重启**：AWS 走 EventBridge Scheduler 直调；腾讯/阿里走同一个调度器触发 Lambda 调各自 RebootInstance API。未接入的账号会被工具如实拒绝——照实回报，别硬来。
+- 创建是写操作会弹确认；确认前用一句话说清「将定时重启哪台、什么时候、一次性还是循环」。到点由云端自动重启（届时无法再确认，所以此刻务必核对准目标与时间）。
+- 查/删用 `list_scheduled_tasks` / `cancel_scheduled_task`。
+
+## 目标解析与泛化（重要）
+解析操作目标时先 Read `inventory.md`；不确定可用 `aws_cli` 实时 describe 核对。
+**只有当你能唯一、确切地定位到目标（拿到 实例ID + region + profile）时才动手。**
+
+遇到下列情况，**一律停下、如实回报、请用户补充或调整，绝不猜测、绝不对不确定的对象执行操作**：
+- 用户说的实例 / 区域在 inventory 里找不到（某 region 未纳管、实例名不存在、上游 IP 反查不到归属等）；
+- 名称有歧义、可能匹配多台；
+- 缺少连接所需信息（密钥 / 用户名 / 跳板）导致无法 SSH。
+
+回报时讲清三件事：**你查了哪里、找到/没找到什么、还缺什么**，然后让用户补充信息或改一个明确的对象。
+例：「宁夏已纳管区域里没有名为 xxxx 的实例；当前只覆盖 <列出已纳管区域>。请确认实例名，或直接给我 region / 实例ID。」
+宁可多问一步，也不要对错误或不确定的机器执行写操作。
+
+## 执行规范
+1. 操作前先回显你解析出的目标（实例名 → ID / region / profile），让用户一眼能核对。
+2. 自动执行（不打断）：只读操作（describe/list/df/状态查询等）**以及实例重启**（reboot-instances / RebootInstances，低风险可逆，用户已授权免确认）。其余写操作（停止/销毁/改配置、SSH 改动、写文件）由系统拦截要用户确认。无论是否需确认，发起前都用一句话说清你要做什么、对哪台。
+3. 操作后简要回报结果，失败要给出原因和建议。命令失败时，工具输出末尾可能自动追加一段「🔎 诊断」（凭证/权限/限额/超时等的确定性判定 + 修复方向）——命中时优先采信并照建议处理；未命中再自己结合 inventory/runbook 深挖。错误码全表见 `runbooks/error-codes-quickref.md`。
+
+## 能力沉淀（重要）
+完成一项**之前没有对应 runbook 的运维任务**后，主动提议把它沉淀成 `runbooks/<kebab-name>.md`，参考 `runbooks/_TEMPLATE.md` 的结构，记录：触发意图、目标如何解析、执行步骤与命令、是否写操作、注意事项。用户同意后再写。
+写完若要让 NOC 机读清单（data.json）登记这个新剧本，跑 **`ops sync --index`**（只重扫本地 runbooks/ 与日志、零网络秒级，**不要**用全量 `ops sync`——那会重扫所有云、慢且无谓；`--local` / `--tailscale` 是刷非公网机器的，也不对口）。
+"""
+
+# ---------------------------------------------------------------------------
+# 运行
+# ---------------------------------------------------------------------------
+
+def _make_options() -> ClaudeAgentOptions:
+    return ClaudeAgentOptions(
+        system_prompt=SYSTEM_PROMPT,
+        model=MODEL,
+        cwd=str(paths.workspace_dir()),
+        mcp_servers={"ops": ops_server},
+        # 只把纯只读内置工具放进 allowed_tools（自动批准）。
+        # 写操作工具（aws_cli/ssh_exec/Write/Edit）故意不列入——它们会落到
+        # can_use_tool 回调里做读/写分类与确认。列进来会被 SDK 自动批准、绕过确认！
+        allowed_tools=["Read", "Glob", "Grep", "TodoWrite"],
+        can_use_tool=can_use_tool,
+        permission_mode="default",
+        setting_sources=[],  # 不加载用户全局 Claude Code 设置，保持独立
+        max_turns=40,
+    )
+
+
+async def _drain(client: ClaudeSDKClient) -> None:
+    """打印一轮响应里的助手文本与工具调用。"""
+    async for msg in client.receive_response():
+        if isinstance(msg, AssistantMessage):
+            for block in msg.content:
+                if isinstance(block, TextBlock) and block.text.strip():
+                    print(block.text, end="", flush=True)
+                elif isinstance(block, ToolUseBlock):
+                    name = block.name.split("__")[-1]
+                    arg = block.input.get("command") or block.input.get("file_path") or ""
+                    print(f"\n\033[36m· {name}\033[0m {arg}".rstrip(), flush=True)
+        elif isinstance(msg, ResultMessage):
+            print()  # 换行收尾
+
+
+async def run_once(prompt: str) -> None:
+    async with ClaudeSDKClient(options=_make_options()) as client:
+        await client.query(prompt)
+        await _drain(client)
+
+
+async def run_repl() -> None:
+    print("AWS 运维 Agent（交互模式）。输入指令，exit/quit 退出。\n")
+    async with ClaudeSDKClient(options=_make_options()) as client:
+        while True:
+            try:
+                user = (await asyncio.to_thread(input, "\033[32mops>\033[0m ")).strip()
+            except (EOFError, KeyboardInterrupt):
+                print()
+                break
+            if not user:
+                continue
+            if user.lower() in ("exit", "quit", "q"):
+                break
+            await client.query(user)
+            await _drain(client)
+
+
+def main() -> None:
+    if not os.environ.get("ANTHROPIC_API_KEY"):
+        print("错误：未设置 ANTHROPIC_API_KEY", file=sys.stderr)
+        sys.exit(1)
+    paths.ensure_workspace()
+    args = sys.argv[1:]
+    if args:
+        asyncio.run(run_once(" ".join(args)))
+    else:
+        asyncio.run(run_repl())
+
+
+if __name__ == "__main__":
+    main()

noc_ops/assets/ops-config.default.toml

@@ -0,0 +1,127 @@
+# ops 部署配置（单一声明式来源）——非密、可 git 跟踪、可移植。
+#
+# 安全边界：这里只放**非密**的部署专属配置——账号 ID / 区域 / SSH 别名前缀 /
+# 跳板机 / 角色 ARN / Lambda ARN / 云 profile 名 / ssh 用户名 / 私钥**文件名**。
+# **绝不**放：AWS access key、私钥内容、密码、任何 secret。
+#
+# 这是打包默认（=出厂占位模板）。`ops setup` / 首启会把它 seed 到 <workspace>/ops-config.toml，
+# 之后**编辑工作区那一份**填上你自己的账号/区域即可；本文件只是缺省回退。
+# 下方用 <尖括号> 标的都是占位符，请替换；用不到的云整段删掉即可。
+
+[agent]
+model = "claude-sonnet-4-6"            # 仍可被 OPS_MODEL 环境变量覆盖
+
+# ===== AWS =====
+[aws]
+# 仅这些 global 账号会扫 route53domains（域名）。删掉或留空表示不扫。
+route53_profiles = ["<aws-global-account-id>"]
+# 各 partition 下要扫的常用区域（按需增删）
+scan_regions_global = ["us-east-1", "us-west-2", "ap-northeast-1"]
+scan_regions_china = ["cn-northwest-1"]
+
+# 每个账号一段；profile = 你本机 `aws configure` 里的 profile 名（这里用账号 ID 当 profile 名也可）
+[[aws.accounts]]
+profile = "<aws-account-id>"
+partition = "global"          # china | global —— 决定扫哪组区域
+# [[aws.accounts]]
+# profile = "<aws-china-account-id>"
+# partition = "china"
+
+[aws.alias_prefix]           # "<profile>/<region>" = SSH 别名前缀（未列出的按区域昵称派生）
+# "<aws-account-id>/us-west-2" = "ore"
+
+[aws.jumps]                  # "<profile>/<region>" = [跳板别名, 跳板实例名]（仅无公网内网实例需要）
+# "<aws-china-account-id>/cn-northwest-1" = ["<jump-alias>", "<jump-instance-name>"]
+
+# ===== 阿里云（多账号，不用就整段删）=====
+# 每个账号一段 [[aliyun.accounts]]。只有域名、没有服务器的账号省略 regions/ssh_* 即可。
+# [[aliyun.accounts]]
+# profile = "<aliyun-cli-profile>"
+# account = "<aliyun-account-id>"
+# ssh_user = "root"
+# ssh_key = "<keyfile-name>"   # 私钥 ~/.ssh/<account>/<keyfile-name>.pem（文件名，非密钥内容）
+# [aliyun.accounts.regions]
+# "cn-hangzhou" = ["Hangzhou", "🇨🇳"]
+
+# ===== Google Cloud（多项目，只读展示 Compute/Storage/IAM，不用就整段删）=====
+# account=项目 id；认证沿用本机 gcloud（gcloud auth login / ADC），noc 不存密钥。
+# [[gcp.accounts]]
+# project = "<gcp-project-id>"
+# configuration = "default"   # 可选：gcloud 命名配置（多登录时用）
+
+# ===== Microsoft Azure（多订阅，只读展示 VM/存储/DNS/数据库/Function，VM 可重启，不用就整段删）=====
+# account=订阅 id；认证沿用本机 az（az login / service principal），noc 不存密钥。
+# [[azure.accounts]]
+# subscription = "<azure-subscription-id>"
+
+# ===== Cloudflare（DNS zone 纳入「域名」tab，只读，不用就整段删）=====
+# token 是密钥，不放配置——存 Keychain：
+#   security add-generic-password -U -s noc-cloudflare -a cloudflare -T /usr/bin/security -w
+# [[cloudflare.accounts]]
+# account = "cloudflare"             # 标签，也作 Keychain 的 account 名
+# keychain_service = "noc-cloudflare"
+
+# ===== Supabase（托管 Postgres 项目纳入「数据库」tab，只读，不用就整段删）=====
+# 账号级 PAT(Management API token) 是密钥，不放配置——存 Keychain：
+#   security add-generic-password -U -s noc-supabase -a supabase -T /usr/bin/security -w
+# [[supabase.accounts]]
+# account = "supabase"
+# keychain_service = "noc-supabase"
+
+# ===== 腾讯云（不用就整段删）=====
+# [tencent]
+# account = "<tencent-account-id>"
+# ssh_user = "ubuntu"
+# ssh_key = "<keyfile-name>"
+# [tencent.regions]
+# "ap-nanjing" = ["Nanjing", "🇨🇳"]
+
+# ===== 内网（LAN）连通性预检（可选，不配则不门控）=====
+# `ops sync --local` 会逐台 TCP 探内网机器（local/sangfor/vmware/synology）。
+# 若当前不在内网/未连 VPN，逐台探测会吃满超时、再把所有机器误标 stopped。
+# 配了 probe 后：--local 开跑前先探这几个点，全都不通即判定"不在内网"——
+# 内网机器整体沿用上次数据、不重扫。留空/删掉 = 老行为。
+# probe：host:port 列表（无端口默认 22），任一通即算在内网。选内网里最稳的点，
+# 如网关或 vCenter/HCI 管理口。
+# [local_net]
+# probe = ["<gateway-or-vcenter-ip>:443"]
+
+# ===== 网络域：内网（lan） vs Tailscale =====
+# 每个本地网络账号都属于一个网络域，分开刷、互不误伤：
+#   ops sync --local       只刷 network = "lan"       门控 = 上面的 local_net.probe
+#   ops sync --tailscale   只刷 network = "tailscale"  门控 = `tailscale status`
+# 不写 network 字段会按 url 自动推导：100.64.0.0/10 地址或 *.ts.net 名字 → "tailscale"，
+# 其余 → "lan"。只有想覆盖自动推导（如经子网路由暴露的内网地址）才需要显式写。
+# [[synology.accounts]]
+# account = "<nas-on-tailnet>"
+# url     = "https://100.x.y.z:5001"
+# network = "tailscale"
+
+# ===== 实例用途备注（人工维护，可整段删）=====
+# 键=实例 ID（不用名字，实例改名后仍对得上），值=一句话用途。渲染进 inventory.md 实例表的
+# 「用途」列 + data.json 的 instances[].note；某个区/某朵云一台都没写就不加这一列。
+# inventory.md 每次 sync 整份重写——备注只有写在这里才活得过下一次 `ops sync`。
+# [instance_notes]
+# i-0123456789abcdef0 = "Caddy 边缘入口：反代 MCP 网关 + 官网静态站"
+
+# ===== 计划任务（EventBridge Scheduler）；不用定时任务可整段删 =====
+[scheduler]
+timezone = "Asia/Shanghai"
+display_tz = "北京时间(UTC+8)"
+role_name = "noc-scheduler"  # 各账号同名角色；ARN 由 arn:{partition}:iam::{profile}:role/{role_name} 推导
+
+# 非 AWS（腾讯/阿里）派发中枢：一个 AWS 账号上的 Lambda，从 Secrets Manager 取各云凭证后调其重启 API
+# [scheduler.dispatch]
+# account = "<aws-account-id>"
+# region = "ap-northeast-1"
+# lambda_arn = "arn:aws:lambda:ap-northeast-1:<aws-account-id>:function:noc-reboot-dispatcher"
+
+# [[scheduler.dispatch_clouds]]   # 已接入派发（凭证在 Secrets Manager）的 (cloud, account)
+# cloud = "tencent"
+# account = "<tencent-account-id>"
+
+[[scheduler.accounts]]       # AWS 直重启账号（partition 用 ARN 写法 aws-cn | aws）
+profile = "<aws-account-id>"
+partition = "aws"
+regions = ["us-west-2"]
+

noc_ops/assets/runbooks/README.md

@@ -0,0 +1,18 @@
+# 可分发运维剧本包（通用版）
+
+这是一组**与具体环境无关**的运维剧本，可直接分发给其它企业用户使用。均为方法论 / 排障流程，命令用占位符（`<域名>`/`<P>`/`<region>` 等），不含任何真实账号 ID、主机名、IP、内部域名或自研工具。
+
+## 剧本清单
+
+| 剧本 | 用途 | 适用对象 |
+|---|---|---|
+| `s3-bucket-usage-check.md` | 删 S3 桶前判断它是否还在用（新鲜度 + 反查生产者） | 任何 AWS 用户 |
+| `alb-access-log-decommission.md` | 停用 ALB 访问日志并安全删除其日志桶 | 任何 AWS 用户 |
+| `ec2-public-exposure-hardening.md` | 收紧 EC2 公网暴露面（安全组收口） | 任何 AWS 用户 |
+| `certbot-renewal-troubleshooting.md` | Let's Encrypt 证书过期 / 自动续期排障 | 任何 nginx + certbot 主机 |
+| `site-access-source-stats.md` | 统计某站点的访问来源（源 IP / 地理归属） | 任何 nginx / ALB 站点 |
+
+## 约定
+- 占位符：`<域名>` 站点域名、`<P>` AWS profile、`<R>`/`<region>` 区域、`<sg>` 安全组 ID、`<alias>` SSH 别名、`<桶名>` S3 桶名。
+- 安全原则：只读操作直接做；写操作（删桶/改安全组/续删证书等）先回显计划再确认；不可逆操作（删桶）务必先核实无引用。
+- 剧本间用 `[[名称]]` 互链，均指向本目录内的其它剧本。