jumpserver-skills 是一个面向 JumpServer V4.10 的查询、审计分析与模板化使用报告 skill 仓库，适用于对象查询、权限回看、审计调查、治理巡检、访问分析，以及某一天或某一段时间的堡垒机使用报告。它更像一套可复用的 skill 规则与正式入口封装，而不是要求使用者手动拼接脚本命令的 CLI 教程。

仓库内部会按请求类型自动路由到 jms_query.py、jms_diagnose.py、jms_report.py 三类正式入口。默认保持只读，仅允许本地运行时写入 .env 和当前组织上下文，不执行 JumpServer 业务写操作。

English

1. 把这个 skill 接到你的 agent 或 Codex 环境里。仓库中的 agents/openai.yaml 可以直接作为接入描述使用。
2. 直接用自然语言初始化配置，例如“帮我生成 .env，JumpServer 地址是 https://jump.example.com，我用 AK/SK 登录”。
3. 然后继续直接提需求，例如“查某某用户在 Default 组织下有哪些资产”或“看看昨天使用情况”。

第一次使用时，优先推荐走“自然语言对话生成 .env”这条路径，通常比手动改模板更快。

1. 准备环境文件。在仓库根目录创建 .env，有两种方式：

手动方式：

cp .env.example .env

对话方式：

如果本地配置不完整，运行时也可以直接通过自然语言对话帮你生成 .env。它会按固定顺序收集 JMS_API_URL、认证方式、组织、超时和 TLS 配置，回显脱敏摘要后写入本地 .env。例如：

• “帮我生成 .env，JumpServer 地址是 https://jump.example.com，我用 AK/SK 登录。”
• “帮我初始化 JumpServer 配置，我用用户名密码登录，不校验证书。”

2. 把这个 skill 接到你的 agent 或 Codex 环境里使用。仓库中的 agents/openai.yaml 提供了一个现成的 skill 接入描述，可作为引用或注册该 skill 的入口之一。

3. 直接用自然语言描述需求，不需要手动拼接脚本命令。例如“查某某用户在 Default 组织下有哪些资产”“看看昨天使用情况”“看某条授权规则详情”。

4. 根据返回结果继续补充上下文。如果结果提示 candidate_orgs、switchable_orgs、候选对象或缺少时间范围，就按提示补充组织、对象名称、平台或时间窗口。组织必须先选时，返回里还会带 reason_code、user_message、action_hint、suggested_commands 和 candidate_org_count，方便直接按提示继续。

使用时不需要记住具体执行命令。这个 skill 会先做预检，再按路由规则自动选择正式入口，并在需要时提示你补充组织、对象或时间范围。

如果你希望直接手动执行正式入口，推荐按下面的顺序使用参数：

1. 优先使用显式参数，例如 --org-name、--name、--days、--user
2. 需要补充少量高级字段时，再重复传入 --filter key=value
3. 只有兼容旧命令时，才使用 --filters '{"key":"value"}'

推荐写法：

python3 scripts/jumpserver_api/jms_diagnose.py select-org --org-name Default
python3 scripts/jumpserver_api/jms_diagnose.py user-assets --org-name Default --username example.user
python3 scripts/jumpserver_api/jms_query.py object-list --resource organization --name Default
python3 scripts/jumpserver_api/jms_query.py audit-analyze --capability session-record-query --days 7 --user example.user
python3 scripts/jumpserver_api/jms_diagnose.py inspect --capability hot-assets-ranking --days 30 --top 10
python3 scripts/jumpserver_api/jms_diagnose.py reports --report-type account-statistic --days 30

兼容写法：

python3 scripts/jumpserver_api/jms_query.py object-list --resource organization --filters '{"name":"Default"}'
python3 scripts/jumpserver_api/jms_query.py audit-analyze --capability session-record-query --filter user=example.user --filter days=7

列表型和分析型命令默认会自动翻页抓取并返回查询范围内的全部结果，不再支持 --limit/--offset。

仓库根目录下提供了 .env.example 作为模板。实际使用时，需要在仓库根目录准备 .env 文件；可以直接复制模板后修改，也可以参考模板手动新建。

如果不想手动编辑，也可以直接通过自然语言对话生成 .env。当检测到配置缺失或不完整时，skill 会按顺序收集必要字段，并通过正式入口把配置写入本地 .env。

如果你想一次把信息说清，通常准备下面这些就够了：

• JMS_API_URL
• 一组完整认证方式：JMS_ACCESS_KEY_ID/JMS_ACCESS_KEY_SECRET 或 JMS_USERNAME/JMS_PASSWORD
• JMS_ORG_ID，不确定时可以先留空
• JMS_TIMEOUT，不填则使用默认值
• JMS_VERIFY_TLS，不填时默认 false

环境变量规则：

• 必须提供 JMS_API_URL。
• 认证方式至少完整提供一组：JMS_ACCESS_KEY_ID/JMS_ACCESS_KEY_SECRET 或 JMS_USERNAME/JMS_PASSWORD。
• .env 会被运行时自动加载。
• 如果 .env 缺失或不完整，可以直接通过自然语言对话补齐，运行时会在确认后生成或覆盖本地 .env。
• 首次使用前，需要确保地址、认证方式、组织、超时和 TLS 配置齐全。
• 如果切换了 JumpServer、账号、组织或 .env 内容，应重新执行完整预检。

• “查一下 Demo-User 这个用户的详情。”
• “看看名为 Demo-Node 的资产节点里有哪些资产。”
• “帮我看 Linux 平台下有哪些可用资产。”
• “查某某用户在 Default 组织下有哪些资产。”
• “看这条授权规则详情，顺便告诉我它影响哪些用户和资产。”
• “谁能访问这台资产？”
• “查最近一周的登录审计。”
• “看某个用户的会话记录和异常中断情况。”
• “帮我排查昨天的高危命令和文件传输审计。”
• “看看某天使用情况。”
• “帮我分析下某天堡垒机器的使用情况。”
• “帮我看昨天登录情况。”
• “想看上周谁登录最多。”
• “过一下 3 月上旬哪些资产最活跃。”
• “看某天登录日志明细。”
• “导出某天命令记录详情。”

这类边界尤其重要：

• 某某用户在 Default 组织下有哪些资产、某某用户有哪些节点、某某用户在某资产下有哪些账号 这类结果型问法，属于用户有效访问范围，优先返回资产 / 节点 / 账号范围结果，不回退成授权规则说明。
• 某某用户为什么能访问某资产、某条授权规则详情 这类原因型问法，属于权限关系或访问分析。
• 这台资产授权给了谁、谁被授权到这台资产 默认回答授权主体，不默认把超级管理员算进去；只有用户明确要求“实际可访问者（含超管）”时才补充超级管理员集合。
• 某天登录情况、某天会话概览、某时间段谁最多 这类表达，属于报告/使用分析。
• 某天登录日志、某天命令记录、某条会话详情 这类表达，属于审计调查。

只要请求的核心对象是某一天或某一段时间内的 JumpServer 使用数据分析，就会优先走模板化报告流程。这包括：

• 使用报告、日报、周报、月报
• 使用情况、使用分析、使用统计、使用汇总、使用概览
• 审计分析、某天发生了什么
• 某天登录 / 会话 / 命令 / 传输情况
• 某时间段的排行、TOP、谁最多、哪些资产最活跃

这类请求默认直接产出完整 HTML 报告，不先回退成自由文本摘要。只有当用户明确说“不要生成报告，直接分析”“先简单说下”“只给我结论”“不用模板”时，才允许跳过模板直接给简短分析。

日期表达速查：

• 某天 只是占位说法，用户不需要真的输入“某天”。常见自然语言表达包括：
  • 昨天
  • 20260310
  • 2026-03-10
  • 2026/03/10
  • 3月10号
  • 3 月 10 日
  • 2026年3月10日
• 某时间段 也只是占位说法。常见自然语言表达包括：
  • 上周
  • 本月
  • 3月上旬
  • 2026-03-10 到 2026-03-24
  • 2026/03/10 到 2026/03/24
  • 3月10号到3月24号
• 用户自然语言会先被归一化，再进入正式入口。正式入口最终统一落到 --date、--period 或 --date-from/--date-to。

时间表达会先归一化为明确时间窗：

• “昨天” -> 前一天 00:00:00 ~ 23:59:59
• 20260310 -> 2026-03-10 00:00:00 ~ 23:59:59
• 2026-03-10 / 2026/03/10 / 3月10号 / 3 月 10 日 / 2026年3月10日 -> 同一天 00:00:00 ~ 23:59:59
• “上周” -> 上一个自然周，周一 00:00:00 ~ 周日 23:59:59
• “本月” -> 本月 1 日 00:00:00 到当前日期或月末 23:59:59

常见归一化结果示例：

• 帮我分析下20260310的堡垒机使用情况 -> date_from=2026-03-10 00:00:00，date_to=2026-03-10 23:59:59
• 帮我分析下3月10号的堡垒机器使用情况 -> date_from=当日 00:00:00，date_to=当日 23:59:59
• 帮我分析下上周的堡垒机使用情况 -> period=上周，最终归一化为上周周一 00:00:00 到周日 23:59:59
• 帮我分析下2026-03-10到2026-03-24的堡垒机使用情况 -> 最终归一化为 date_from=2026-03-10 00:00:00，date_to=2026-03-24 23:59:59

报告固定输出到 reports/JumpServer-YYYY-MM-DD.html。如果请求里涉及命令审计字段，报告会按既定规则处理可访问的 command storage 汇总，不需要使用者手动选择内部取数逻辑。 报告成功时，默认先回显“报告已生成”，并附上报告文件路径、文件存在性/大小、模板路径、字段元数据路径、时间范围、组织和 validation_summary；简短摘要只能作为补充，不能替代这些报告产物信息。

• 用户显式指定组织时，按用户指定组织执行；user-assets / user-nodes / user-asset-access 优先使用命令级 --org-id / --org-name 临时限定组织，不写回 .env。
• 报告或使用分析请求未指定组织，或用户明确说“所有组织”“全局组织”时，默认优先尝试全局组织 00000000-0000-0000-0000-000000000000。
• 普通查询请求未指定组织时，会按现有组织规则处理；如果无法自动确定组织，会返回 candidate_orgs，并通过 user_message / action_hint 明确要求先选择查询组织。
• 当前组织已生效但仍有其他可切换组织时，结果会继续回显 switchable_orgs，并通过 org_context_hint 明确说明当前查询范围固定在哪个组织。
• 如果当前组织是 A、目标对象在 B，不会自动跨组织继续执行。

出现下面这些情况时，skill 会先阻塞，而不是继续猜测执行：

• 配置或鉴权不完整
• 组织不明确，且不能自动确定
• 对象名称重名或平台不明确
• 查询结果跨组织
• 报告请求的全局组织不可访问
• 用户试图绕过正式入口或跳过预检

其中组织阻塞响应会额外返回这些结构化字段：

• reason_code=organization_selection_required
• user_message：明确提示“继续前必须先选择一个组织”
• action_hint：给出安全下一步命令模板
• suggested_commands：给出 1 到 3 条可直接复制的后续命令
• candidate_org_count：当前候选组织数量
• org_selection_policy=required_before_query_when_multiple_accessible_orgs

• 资产、平台、节点、账号、用户、用户组、组织的创建、更新、删除、解锁。
• 权限创建、更新、追加关系、移除关系、删除。
• 跳过预检直接执行业务动作。
• 临时 SDK/HTTP 脚本绕过正式入口。
• 报告类请求绕过 jms_report.py 正式入口，改用现场临时拼装逻辑。
• 在对象不明确、组织不明确或跨组织场景下继续猜测执行。