noc-ops 0.1.0__tar.gz

noc_ops-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+# 工作区运行时数据（sync 生成的看板数据 + 状态/快照/日志，含 IP/账号/命令，勿外泄）
+/data.json
+/local-servers.toml
+/.state/
+
+# 本地 Claude Code 设置（机器本地，不入库）
+.claude/settings.local.json
+
+# Python 打包/缓存
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+build/
+dist/
+
+# macOS
+.DS_Store
+
+# 混淆分发构建产物（PyArmor，由 scripts/build-obfuscated.sh 生成）
+/build_obf/
+
+# 测试夹具工作区：只保留匿名化的 ops-config.toml，其余运行时产物不入库
+/tests/fixtures/workspace/.state/
+/tests/fixtures/workspace/runbooks/
+/tests/fixtures/workspace/data.json
+/tests/fixtures/workspace/inventory.md
+/tests/fixtures/workspace/local-servers.toml
+
+# 工作区本体（仓根目录=作者的真实工作区）：部署配置 / 清单 / 剧本都是机器特定数据，不入库
+# 2026-10-25 起停止跟踪（此前被跟踪过，公开本仓前须 orphan 新仓重建历史）
+/ops-config.toml
+/inventory.md
+/runbooks/
+# 本机 Claude Code 项目级 MCP 配置与渠道能力目录（含个人路径）
+/.mcp.json
+/capabilities.toml
+# 无关的飞书文档草稿缓存
+/draft_*_folder/

noc_ops-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

noc_ops-0.1.0/NOTICE

@@ -0,0 +1,18 @@
+noc-ops — 多云运维 ops CLI
+Copyright 2026 Fenghuang
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+Bundled third-party components (src/noc_ops/dashboard/vendor/):
+  - AG Grid Community — MIT License, Copyright (c) AG Grid Ltd
+  - Inter font — SIL Open Font License 1.1, Copyright (c) The Inter Project Authors

noc_ops-0.1.0/PKG-INFO

@@ -0,0 +1,275 @@
+Metadata-Version: 2.5
+Name: noc-ops
+Version: 0.1.0
+Summary: 多云运维 ops CLI —— 9 朵云（AWS / 阿里云 / 腾讯云 / 火山引擎 / GCP / Azure / Oracle / Cloudflare / Supabase）+ 本地网络机器：清单同步、运维看板、定时重启、Claude Code / Codex skill；可选自然语言 agent 与 MCP
+Project-URL: Homepage, https://github.com/pholex/noc-ops
+Project-URL: Repository, https://github.com/pholex/noc-ops
+Project-URL: Skill, https://github.com/pholex/multicloud-ops
+Author: Fenghuang
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: aliyun,aws,azure,claude-code,devops,gcp,multicloud,noc,oci,ops,skill,tencent-cloud
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Provides-Extra: agent
+Requires-Dist: claude-agent-sdk<0.3,>=0.2.156; extra == 'agent'
+Provides-Extra: all
+Requires-Dist: claude-agent-sdk<0.3,>=0.2.156; extra == 'all'
+Requires-Dist: mcp<3,>=2.2.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: claude-agent-sdk<0.3,>=0.2.156; extra == 'dev'
+Requires-Dist: mcp<3,>=2.2.0; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: pyyaml; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.2.0; extra == 'mcp'
+Provides-Extra: sangfor
+Requires-Dist: pycryptodome; extra == 'sangfor'
+Description-Content-Type: text/markdown
+
+# NOC — 多云运维 ops CLI
+
+用自然语言指令运维多云机群（AWS / 阿里云 / 腾讯云 / 火山引擎 / Google Cloud / Azure / Oracle，另只读纳管 Cloudflare / Supabase）的 `ops` CLI，基于 [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/python)。
+一次安装就接好多个 LLM 客户端：**`ops` CLI 本体 + Claude Code skill + Codex MCP**，共享 `providers + sync + aws_safety + schedule_ops` 这套底座。
+能力随日常运维不断**沉淀**：每做一项新运维，就存成一个 runbook，攒一段时间后接管大部分日常工作。
+
+## 代码与工作区（分离）
+
+**代码**（pip/uv 装进 venv，只读）：
+```
+src/noc_ops/
+├── cli.py            # `ops` 入口：分发 sync/noc/doctor/setup，默认走 agent
+├── agent.py          # 自然语言 agent（交互/一次性两种模式）
+├── sync.py           # 扫实例/域名/RDS/S3/Lambda/CloudFront/IAM/AI 密钥(Bedrock key)/SQS·SNS·SES·EventBridge/成本/账务额度，生成 inventory+data.json+ssh config
+├── mcp_server.py     # MCP server（`ops-mcp` 入口，给 Codex 等）
+├── schedule_ops.py   # 计划任务（定时重启，EventBridge + Lambda 派发）
+├── aws_safety.py     # 读/写操作分类器（权限闸门）
+├── ops_log.py        # 操作日志（写操作审计流水）
+├── paths.py          # 工作区路径解析（代码↔数据分离）
+├── doctor.py / setup_clients.py   # 体检 / 多客户端一键安装
+├── providers/        # 多云驱动：base + aws/aliyun/tencent/volcengine/gcp/azure/oracle/cloudflare/supabase/synology/vmware/sangfor/local
+├── dashboard/        # 看板前端（server.py + index.html + 自托管 ag-Grid/字体）
+├── skill/SKILL.md.tmpl            # Claude Code skill 模板（setup 时渲染安装）
+└── assets/runbooks/  # 全新安装的种子 runbook
+```
+
+**工作区**（可变数据，默认 `~/.noc`，可用 `NOC_HOME` 或 `ops setup --workspace` 指定）：
+```
+<workspace>/
+├── inventory.md      # 实例+域名+账务额度清单（人读，sync 生成）
+├── data.json         # 机读数据（sync 生成，看板/MCP 用）
+├── runbooks/*.md     # 能力库（用户沉淀，随用增长；升级不丢）
+└── .state/           # 运行时状态（ssh 用户缓存 / 快照 / 操作日志）
+```
+
+## 安装与运行
+
+支持 macOS / Linux（纯 Python 包）。一行装（推荐）：`curl -fsSL https://<host>/install.sh | sh`（自动装 uv + 从 PyPI 装 + 接入客户端）。或手动：
+
+```bash
+uv tool install noc-ops                     # 或 pipx install noc-ops；开发者：uv tool install <本仓路径>
+uv tool install --force 'noc-ops[agent]'    # 可选：终端自然语言 agent（需 ANTHROPIC_API_KEY）
+uv tool install --force 'noc-ops[mcp]'      # 可选：ops-mcp，仅无 shell 的 GUI 客户端（Claude Desktop）需要
+ops setup [--workspace ~/Developer/noc]    # 记工作区 + 经 `skills` CLI 把 skill 扇出到所有已装客户端（skill 优先）
+ops init                                    # 交互式生成配置（发现账号/区域/SSH key，免手编 TOML）
+ops doctor --fix                            # 体检：云 CLI 依赖 / 凭证 / 工作区 / 客户端；--fix 自动修
+
+ops "宁夏有几台 EC2 在运行"                 # 一次性指令（任意目录可跑）
+ops                                         # 进入交互模式（推荐：边做边沉淀）
+ops sync                                    # 同步实例清单 + SSH 配置（新增实例后跑）
+ops sync --account=<账号>                   # 只刷某一个云账号（AWS 账号 ID / 阿里云 profile 名）
+ops noc                                     # 启动 NOC 运维看板（默认后台；status/stop/restart 管理）
+```
+
+前置：用到哪朵云就装好对应 CLI 并配好凭证（`aws` / `aliyun` / `tccli` / `ve` / `gcloud` / `az` / `oci`；`ops doctor` 会逐项检查，没装 CLI 的云 `ops sync` 自动跳过）。
+渠道 **skill 优先**；无 shell 的 GUI 客户端（如 Claude Desktop）才需 `ops setup --with-mcp`（外包 `npx add-mcp`，含 Claude Desktop）。
+
+## ops noc — NOC 运维看板
+
+`ops noc` 启动本地服务（默认 `http://127.0.0.1:8765`），用 **ag-Grid**（社区版，MIT）密集表格
+呈现全部实例：状态灯、账号、区域（旗帜）、类型、IP、实例 ID（点击复制）、登录用户、直连/跳板/SSM（无密钥对的 AWS 实例视为仅 SSM Session Manager 可达，不配 SSH）。
+顶部标签页分类展示 **实例 / 域名 / 数据库 / 存储 / 函数 / CDN / IAM / AI 密钥 / 消息·事件 / 成本 / 计划任务 / 剧本 / 操作日志** 十三类；「剧本」页列出 `runbooks/` 全部剧本（标题/沉淀时间/是否写操作/触发意图），点剧本名即在新页打开其 markdown（`/runbook?name=<名>`，限定在 runbooks 目录内）。
+支持按账号/区域/状态筛选、关键字搜索、点表头排序、列宽拖拽/重排、每列筛选菜单、**导出 CSV**。
+Quartz 主题跟随系统明暗。右上「刷新」触发一次 `ops sync`（重扫 AWS + 探测新机器）再重载。
+数据来自 `<workspace>/data.json`（由 `ops sync` 生成）。
+
+> 账号级的**账务/额度**（`credits` 键：信用余额、免费额度到期、超额保护、预算告警）没有独立 tab——它是账号状态而非资源清单，渲染在 `inventory.md` 的「💳 云账务 / 额度」节，刷新用 `ops sync --kind=credits`。与「成本」tab 的分工：credits 是「还剩多少、超额会怎样」，billing 是「花了多少」的流水。
+
+> 「AI 密钥」tab 只盘点**元数据**（限定到哪个 API、绑定的服务账号、客户端限制、创建时间），**永远不取密钥串**（不调 `get-key-string`，data.json / inventory 里不会出现 key 本体）。目前接了两朵云：GCP 的 Cloud API Keys（AI Studio 的 Gemini key 与 Vertex AI Express key 本质都是它，按 `apiTargets` 标成「Gemini API」/「Vertex AI」，只盘 AI 用途；无限制 key 标红，Google 已在封禁闲置的无限制 key；项目需启用 `apikeys.googleapis.com`）和 AWS 的 Bedrock 长期 API key（IAM 服务专用凭证，含 Claude Platform on AWS key；只盘全球区（`--all-users` 一次列全；中国区不支持该参数，直接跳过）；短期 12h key 本地签出、不可列）。阿里云百炼 key 没有列表 OpenAPI，暂未纳管。刷新 `ops sync --kind=apikeys`。
+
+ag-Grid 的 JS、Inter 字体均**本地自托管在 `src/noc_ops/dashboard/vendor/`、不走第三方 CDN**（遵全局规则）；
+看板服务用 Python stdlib 起、运行期不拉外部包。
+（注：这里说的是「看板运行期」的取舍——不是全工程教条。`ops setup` 装 skill 时会按需调用
+`skills` CLI（`npx skills`，节点级工具）做多客户端扇出；用对的成熟工具优先于死守零依赖。）
+
+**生命周期**：`ops noc` **默认后台守护启动**（detach，关终端不死，日志写 `<workspace>/.state/noc.log`），立即返回。
+- `ops noc status` — 看在不在跑（PID / URL）
+- `ops noc stop` — 停掉（只杀 noc 自己的监听进程，非 noc 占用仅告警）
+- `ops noc restart` — 停旧启新
+- `ops noc -f` — 前台跑（占终端、Ctrl+C 退出，调试用）
+
+选项：`ops noc --port 9000 --no-open`（可与上面组合）。
+
+## ops sync — 实例清单/SSH 配置同步
+
+新增或变更 EC2 后跑 `ops sync`，它会全量扫描、对比快照、报告 新增/变更/删除，并重新生成
+`inventory.md` 与 `~/.ssh/config`（marker 段）。私钥按约定 `~/.ssh/<profile>/<KeyName>.pem`
+自动推导；登录用户名（ec2-user / ubuntu / centos）对未缓存实例自动探测一次并缓存（幂等，日常只探新机器）。
+
+不必每次都全量重扫，可按两个维度收窄（都是 patch 式合并写回 `data.json`，不整份覆盖）：
+
+```bash
+ops sync --kind=instances                          # 按资源类型收窄（看板「按 tab 单刷」），扫所有账号
+ops sync --account=123456789012                    # 按 AWS 账号收窄：只扫该账号（~25s vs 全量一两分钟）
+ops sync --account=123456789012 --kind=instances   # 两者组合：只刷该账号的实例（~3s）
+ops sync --account=<aliyun-profile>                          # 阿里云账号也认（profile 名或账号 ID，~2s）
+ops sync --probe=<实例名|ID>                       # 只探这一台 AWS 实例的 SSH 登录用户名并回写 config（零云 API，几秒）
+```
+
+`--account=` 只重扫指定账号，同云其它账号 / 其它云的行原样沿用；`~/.ssh/config` 的托管段虽是整段
+重写，但沿用账号的 Host 会一并还原写回（产出与全账号刷新逐字节一致）。`inventory.md` 与实例快照
+是全量产物、两条收窄路径都不动它们。
+
+账号名按云解析：**AWS** 用账号 ID，**阿里云**用 CLI profile 名（如 `<profile>`）或账号 ID 都行。
+各云能按账号刷的资源类型不同（AWS 九类；阿里云 = 实例/存储/域名，即 provider 真会产出的），
+点名了该云没有的类型会直接拒绝并列出可用值。
+
+非公网机器（VMware / Sangfor HCI / 群晖 / 本地物理机）**不参与全量 sync**（连不上时不该被误判
+"已删除"），按**网络域**分两条命令单刷，各有各的门控，互不覆盖：
+
+```bash
+ops sync --local        # 只刷内网机器（network=lan）；门控 = local_net.probe 内网探针
+ops sync --tailscale    # 只刷 Tailscale 组网上的机器；门控 = `tailscale status`
+ops sync --index        # 只刷 runbooks/操作日志索引进 data.json（零网络，秒级）
+```
+
+网络域按端点地址自动推导（`100.64.0.0/10` 或 `*.ts.net` → tailscale，其余 → lan），
+账号里显式写 `network = "tailscale"` 可覆盖。两个域**故意不合并**——"连不上"的含义不同：
+内网看人在不在内网，Tailscale 看 tailscaled 跑没跑、对端节点是否 Online。详见
+`runbooks/sync-inventory.md` 与 `src/noc_ops/netprobe.py`。
+账号在 `src/noc_ops/providers/aws.py` 的 `ACCOUNTS` 维护；别名前缀/跳板在 `src/noc_ops/sync.py` 的 `ALIAS_PREFIX`/`JUMPS`。详见 `runbooks/sync-inventory.md`。
+
+可选环境变量：`OPS_MODEL`（默认 `claude-sonnet-4-6`）。
+
+## ops reboot — 重启一台实例（公有云 + 本地 HCI 同一入口）
+
+```bash
+ops reboot <实例名|ID>            # 重启：按 cloud 自动选通道
+ops reboot <实例名|ID> --status   # 只查实时状态（只读），重启后隔 ~40 秒用它复查
+ops reboot <实例名|ID> --dry-run  # 只打印将要执行的命令
+```
+
+通道按 `cloud` 走 `Provider.reboot_argv`：AWS `aws ec2 reboot-instances`、腾讯 `RebootInstances`、
+阿里 `RebootInstance`、火山 `ecs RebootInstance`（优雅）、GCP `instances reset`（硬）、Azure `vm restart`、Oracle `SOFTRESET`，
+**VMware 走 vCenter REST、深信服 HCI 走 SCP 管控 API**（两者都是 Token 认证 + Keychain 取密码，
+CLI 拼不出来——这也是本命令存在的理由：以前只有 MCP server 接了这条通道，走 skill 的
+Claude Code / Codex 够不着）。群晖 / ESXi 宿主 / Cloudflare / Supabase 没有管控 API，
+会**如实拒绝并给出该走哪条路**（DSM、SSH 别名、控制台），不抛异常。
+
+> ⚠️ **深信服目前只有 `--status` 可用**：这版 SCP 不认现有重启端点（实测 404），命令会如实报错
+> 并指向替代路径（Linux 走 SSH、Windows 去控制台）。端点考古与下一步见「待办」。
+
+目标解析由严到宽：精确 ID → 精确名 → 忽略大小写 → 唯一子串；**匹配到多台一律列出来让你挑**
+（`srv07/srv08`、`泛微OA 应用/数据库` 这类同前缀名太多，猜错就是重启错生产机）。
+重启属低风险可逆，按安全模型**免二次确认**直接执行，并自动记一条操作日志（`--source` 声明调用方）。
+
+## 安全模型
+
+| 操作类型 | 行为 |
+|---|---|
+| 只读（describe/list/get、df/状态查询等） | **自动执行**，不打扰 |
+| 实例重启（`ops reboot`、各云 reboot API） | **自动执行**，低风险可逆；自动记审计日志 |
+| 其它写操作（启停/销毁/改配置、远程改动、写文件） | **先弹确认**，y 才执行 |
+
+分类逻辑在 `src/noc_ops/aws_safety.py`，保守原则：**拿不准一律当写操作、要确认**。
+
+> ⚠️ 关键实现点：写操作工具**不能**放进 `ClaudeAgentOptions.allowed_tools`——那会被 SDK 自动批准、绕过确认回调。只有纯只读内置工具（Read/Glob/Grep）放 allowed_tools，其余都走 `can_use_tool` 闸门。
+
+## 怎么加一项新能力（沉淀 runbook）
+
+1. 在交互模式里和 Agent 一起把某项运维做完。
+2. Agent 会主动问要不要沉淀；同意后它按 `_TEMPLATE.md` 在 `runbooks/` 生成剧本。
+3. 下次遇到同类需求，Agent 会先 Glob 到这个剧本、照着执行。
+
+**加能力 ≈ 写一个 markdown，不用改代码。**
+
+## 开发 / 测试
+
+改本仓代码时的约定见 `CLAUDE.md`（给 LLM 客户端读的简版）；下面是完整版。
+
+### 改完 src/ 必须重装全局 ops
+全局 `ops` 是 `uv tool` 装的 wheel **拷贝**，不跟随 `src/`。改完源码（尤其新增子命令）立刻：
+
+```bash
+uv tool install --force --no-cache '<本仓绝对路径>[all]'   # [all] 带上 agent+mcp 可选依赖，别把本机 agent 弄丢
+```
+
+漏这步的典型症状是「代码明明改好了、跑起来还是旧行为」，排查成本极高。
+
+### 测试（两层）
+
+```bash
+uv run --extra dev pytest -m unit -q     # Tier 1：离线、零 LLM、秒级，改完就跑
+uv run --extra dev pytest -m eval -q     # Tier 2：agent 行为评测，真调 LLM（要 ANTHROPIC_API_KEY，花钱）
+uv run --extra dev pytest -q             # 全部（没设 key 时 Tier 2 自动跳过）
+```
+
+日常只跑 `-m unit`。Tier 2 用 stub 挡住执行层（`agent._run_cli` / `agent._confirm`）+ 冻结的 fixtures 工作区，**绝不碰真云**；细节见 `tests/README.md`。
+
+### 新增 provider / 资源种类 / 看板 tab 的同步清单
+这几处必须一起改，漏一处就出现「看板有、agent 不知道」：
+
+1. `src/noc_ops/providers/<cloud>.py` + `sync.py` —— 扫出来、并进 `data.json`
+2. `src/noc_ops/dashboard/index.html` —— tab 与列
+3. `src/noc_ops/skill/SKILL.md.tmpl` —— agent 靠它才知道查什么、怎么查（公开 skill 仓 pholex/multicloud-ops 里 `skills/multicloud-ops/SKILL.md` 的云列表同步）
+4. `README.md` —— tab 列表与能力描述
+5. 改完跑 `ops setup` 重扇出 skill，再按上面重装全局 `ops`
+
+### 数据文件不入库
+仓根目录同时**就是**当前工作区，所以混着两类东西：`data.json` / `inventory.md` / `.state/` / `local-servers.toml` 都是 `ops sync` 等生成的产物，**不手改、不入库**（已在 `.gitignore`；含 IP/账号/命令，勿外泄）。要改内容，改生成它们的代码。
+真实的 `ops-config.toml` 与 `runbooks/` 同样是工作区数据、不入库；单测读的是匿名化夹具 `tests/fixtures/workspace/ops-config.toml`。
+
+秘密（token / PAT / 密码）走 macOS Keychain 或 Parameter Store，**不进仓库、也不进 `ops-config.toml`**。
+
+### 分发构建
+分发形态（2026-10-25 定）：**skill 免费公开 + CLI 发 PyPI（纯 `py3-none-any`，macOS / Linux）+ 收费只圈 pro 场景**。
+
+```bash
+uv build                     # dist/noc_ops-<版本>-py3-none-any.whl + sdist
+uv publish                   # 推 PyPI（token 走环境变量 UV_PUBLISH_TOKEN，不进仓库）
+```
+
+发布前在干净环境过一遍 `INSTALL.md`（本地 Docker：`python:3.12-slim` 装 wheel → `ops setup` → `ops doctor` → `ops sync` → `ops noc`）。
+`scripts/build-obfuscated.sh`（PyArmor 混淆、仅 arm64 Mac）保留但不再是默认分发路径。
+
+## 插件子命令（entry point）
+
+公司 / 团队专属的子命令不进公开 wheel，放在自己的私有包里，经 entry point 组 `noc_ops.commands` 挂回 `ops`：
+
+```toml
+# 私有包的 pyproject.toml
+[project]
+dependencies = ["noc-ops"]
+[project.entry-points."noc_ops.commands"]
+litellm = "noc_ops_internal.litellm_cli:main"      # 被调函数签名 main(argv) -> int | None
+```
+
+装法：`uv tool install 'noc-ops[all]' --with <私有包路径或名>`。`ops help` 末尾会列出已装的插件命令；内建命令名不可被插件覆盖；插件加载失败只报该命令、不影响 `ops` 其余功能。插件读自己的配置段用 `deploy_config.section("<段名>")`。
+
+## 待办 / 后续
+
+- [ ] SSH 通道：配置 `~/.ssh/config`（跳板机 ProxyJump + key 文件），登录元数据进 inventory，私钥/密码不进明文。
+- [ ] 把常用运维逐步沉淀成 runbooks。
+- [ ] 提交前固定跑 `uv run --extra dev pytest -m unit -q`（当前 739 例 / ~2s）；有条件再接进 pre-commit hook 或 CI 自动化，别靠人记。
+- [ ] **深信服 HCI 的重启端点未探明**（2026-09-18 实测）：provider 里写的 `POST /janus/20180725/servers/{id}/action` 本机 SCP 返回 404，从来没调通过；`ops reboot` 对 sangfor 只有 `--status` 可用（读没问题）。已探明：真口疑似批量的 `POST /janus/20180725/servers/action`，必传 `server_ids` + `server_action`（dict，`{}` 能过校验但 503），但其字段名 36 个候选全被拒、appliance 无 swagger/doc。**最省事的解法**：在 SCP 控制台点一次「重启」，devtools 抓那条 XHR 的 path+payload，照着改 `providers/sangfor.py` 的 `_reboot_server` 即可（考古记录在该文件头注）。在那之前：Linux VM 走 SSH 别名 `reboot`，Windows 去控制台点。
+
+## 许可
+
+Apache License 2.0，见 `LICENSE` 与 `NOTICE`。看板自托管的第三方前端组件（AG Grid Community / Inter 字体）各随其原许可（MIT / OFL 1.1）。