Skip to content

README.md

Latest commit

 

History

History
338 lines (239 loc) · 20.7 KB

README.md

File metadata and controls

338 lines (239 loc) · 20.7 KB
Raw

ZStack Support Agent（支持分析）

ZStack Support Agent（支持分析）基于证据优先方法论，结合 ZStack知识社区(BBS) 历史参考、Jira/Confluence 内部只读参考、GitHub 源码分析（zstack + zstack-utility）和 Tavily 外部 Web/厂商论坛参考。具体事件先整理当前事件证据并提取去标识化的最小故障指纹，再把 BBS、Jira 和 Confluence 作为内部知识系统放入首批查证。涉及源码、机制、调用链、字段下发、版本合入或修复确认时，同一首批必须包含 GitHub。需要并行时请显式要求“用多 agent 并行深查”。内置 E0-E5 证据成熟度、4 类中文公开标签和多维闭环决策。

Disclaimer: 本套件辅助技术支持分析，所有输出应由工程师审核确认后再用于客户沟通。

适用角色

  • 渠道工程师 — 快速分析 ZStack 支持事件，优先结合 BBS、Jira、Confluence 内部知识并按硬约束查证源码
  • 技术支持工程师 — 按照标准化流程输出结构化的分析报告和交接文档
  • 技术支持团队负责人 — 通过统一的分析框架确保团队输出质量和一致性

快速命令

命令 说明
@ZStackSupport:事件分析 粘贴已脱敏的事件描述、错误信号或截图转写，优先查证内部知识系统并给出闭环决策
@ZStackSupport:环境配置 快照或录入 GitHub、BBS、Tavily、Jira/Confluence 连接器变量，不输出密钥值
@ZStackSupport:变更方案 根据事件分析结果和变更内容，基于标准 Word 模板生成运维变更方案 DOCX
@ZStackSupport:故障报告 根据事件分析结果，基于标准 Word 模板生成企业版故障分析报告 DOCX
@ZStackSupport:BBS经验回流 问题处理完成后审核关键细节、查重和脱敏，生成并确认 BBS 经验回流稿
@ZStackSupport:交接摘要 从当前分析结果生成渠道安全的交接文档
@ZStackSupport:脱敏检查 明确 internal 或 customer 受众后，检查内容、元数据和证据可追溯性

使用方式

使用方式 示例 行为
直接问 L3 网络是什么？ 直接中文回答，不查 MCP
具体支持事件 客户升级后云主机迁移失败，错误信号如下... 当前事件证据优先；形成最小脱敏指纹后首批查 BBS、Jira、Confluence，源码/版本类同批查 GitHub
轻量证据答复 这个报错能忽略吗？怎么回复客户？ 查询足以支撑当前断言的关键来源，不以固定来源数量代替证据质量
单点查证 这个 API 在源码里怎么走？ / 有没有类似历史案例？ 只查对应来源
完整事件分析 升级后云主机迁移失败，帮我分析根因和下一步 先结构化 Intake，再按内部知识优先规则查证和闭环
环境配置 快照当前配置 / 帮我录入连接器变量 只显示变量存在性、作用域和格式状态；录入密钥时打开可见 PowerShell 配置窗口

多轮追问建议继续带上技能名，例如：

ZStackSupport:事件分析 继续上一个问题，查一下这个修复有没有合到 4.8.x

Codex 的技能触发由宿主控制，普通追问不一定会自动重新加载插件技能；继续指定 事件分析 可以避免多轮会话掉出工作流。

技能列表

技能 说明
事件分析 核心技能。低风险概念问题直接答；具体事件提取去标识化的最小故障指纹后首批查证内部知识系统；复杂事件输出 Intake、证据映射、安全行动建议和多维闭环决策
源码查证 单点源码求证路径，默认只查 GitHub 源码、commit、tag、release branch、调用链和版本差异
环境配置 快照和引导录入插件 MCP 连接器环境变量，禁止在聊天中收集或输出真实密钥
连通检查 显式触发的只读 MCP 烟测，检查 GitHub、BBS、Tavily、Jira/Confluence 是否注入和可查询
变更方案 基于公司标准 Word 模板生成 ZStack 运维变更方案，保留模板结构并填充概述、步骤、风险、回退、应急预案和变更计划
故障报告 基于公司标准 Word 模板生成 ZStack 企业版故障分析报告，保留模板结构并填充故障基本信息、分析处理过程、原因分析和后续改进预防方案
BBS经验回流 从已完成问题中提炼可复用经验，按知识正确性审核完整性和适用边界，精准追问关键缺口，查重、脱敏并在明确确认后回流 BBS
交接摘要 从分析结果中提取问题摘要、影响范围、时间线、最强证据、已排除方向和下一步行动，生成渠道安全的交接文档
脱敏检查 按 internal/customer 受众逐项检查凭证、许可证、客户原始数据、内部引用、文档元数据、证据可追溯性和无依据根因声明

显式并行深查

进入多来源查证、修复版本/回合确认、正式根因分析、来源冲突或深查路径时，事件分析默认由主 agent 查证汇总。需要并行时请在请求中明确写“用多 agent 并行深查”；若宿主未暴露或不允许 subagent，会明确降级为主 agent 查证。

以下只是可选分组。具体支持事件的内部三源查证由“历史案例”和“内部跟踪/口径”组覆盖；源码/版本类同批增加源码组。低风险直答、明确单点求证或无有效指纹时只派实际需要且能独立查证的组：

源码/版本 agent：只查 GitHub 源码、commit、tag、release branch、调用链、版本差异；不得查询 Jira/Confluence/BBS/Tavily。
历史案例 agent：ZStack知识社区(BBS) 相似案例、差异、可复用验证动作。
内部跟踪/口径 agent：Jira 缺陷/需求状态、影响版本、修复版本、关联项；同时查 Confluence 内部说明、版本边界和口径。
文档/外部 agent：官网文档、Confluence 文档边界、Tavily 厂商/OS/外部生态资料。

内部链接输出策略

插件默认生成明确标注为 internal 的内部分析草稿；只有用户明确要求直接客户输出时才切换为 customer。内部查证命中 BBS、Jira 或 Confluence 时，必须返回标题摘要和 Markdown 可点击直达链接。BBS 格式为 [帖子标题](http://bbs.zstack.io/forum.php?mod=viewthread&tid=14121)；Jira/TIC 格式为 [TIC-5786](http://jira.zstack.io/browse/TIC-5786)；Confluence 使用 MCP 返回的完整 URL。完整 URL 不可得时写“直达链接未返回”，不得猜测、使用相对链接或输出只有 tid/key/pageId 的伪链接。customer 输出和 internal 分析里的“客户回复口径”都禁止内部链接、端点、编号和原始内部内容。所有受众仍禁止输出账号、Token、Authorization、原始页面正文、评论原文、附件、客户原始日志和原始 MCP 载荷。

快速上手：配置 MCP 连接器

本套件通过 MCP 连接器对接 GitHub、ZStack知识社区(BBS)、Tavily 和 Atlassian，实现源码查证、历史参考、经验回流、外部 Web/厂商论坛参考和内部只读工单/文档参考。Windows 使用用户环境变量，macOS 使用用户级持久化环境配置；插件配置只引用变量名，不保存凭据。客户端通过 .mcp.json.enabled_tools 暴露批准工具；除 bbs_create_thread 外均为只读工具。

需要配置的环境变量

GITHUB_MCP_TOKEN
ZSTACK_BBS_AUTHORIZATION
TAVILY_HIKARI_TOKEN
ATLASSIAN_AUTHORIZATION

ATLASSIAN_AUTHORIZATION 需要手动配置为完整 Header 值：Basic <base64(username:password)>。

Jira/Confluence 现在只需要 1 个变量：ATLASSIAN_AUTHORIZATION。不再要求分别配置 JIRA_USERNAME、JIRA_PASSWORD、CONFLUENCE_USERNAME、CONFLUENCE_PASSWORD，也不推荐继续使用旧的 ATLASSIAN_BASIC_AUTH。

每个凭据怎么获取

环境变量 获取方式 填写格式
GITHUB_MCP_TOKEN 在 GitHub 个人设置中创建 Personal Access Token：Settings → Developer settings → Personal access tokens。优先使用 fine-grained token；用于公开 ZStack 源码查证时，只需只读仓库元数据和内容权限。如果团队有 GitHub/Copilot MCP 统一要求，以管理员要求为准。 原始 token，例如 github_pat_...
ZSTACK_BBS_AUTHORIZATION 使用 BBS 用户名和密码生成 Basic Authorization。 Basic <base64(username:password)>
TAVILY_HIKARI_TOKEN 向 Tavily Hikari MCP 网关维护者获取。当前插件连接的是团队网关 https://tavily.zopen1.com/mcp，不要默认把公网 Tavily token 当成可用值。 原始 token
ATLASSIAN_AUTHORIZATION 使用 Jira/Confluence 账号，服务地址为 http://jira.zstack.io 和 http://confluence.zstack.io。将 username:password 转成 base64，再加 Basic 前缀。 Basic <base64(username:password)>

Basic Auth 怎么编码

在 PowerShell 中执行：

$pair = 'username:password'
$base64 = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($pair))
$base64

然后这样使用：

ZSTACK_BBS_AUTHORIZATION=Basic <base64(username:password)>
ATLASSIAN_AUTHORIZATION=Basic <base64>

Atlassian 特别注意：ATLASSIAN_AUTHORIZATION 要填完整 Header 值，必须包含 Basic 前缀。旧环境如果还配置了 ATLASSIAN_BASIC_AUTH=<base64>，安装脚本会兼容迁移，但新安装不再推荐使用旧变量。

环境配置技能怎么用

环境配置 是专门用来配置和检查连接器变量的技能。它不会要求你把 Token、密码、Authorization 或 base64 值粘贴到聊天里，也不会在输出里打印真实密钥。

常用聊天命令：

ZStackSupport:环境配置 快照当前配置
ZStackSupport:环境配置 帮我录入连接器变量
ZStackSupport:环境配置 只补充缺失变量

使用建议：

  1. 先发 ZStackSupport:环境配置 快照当前配置，确认四个变量是否存在、作用域在哪里、格式是否正确。
  2. 如果缺变量，发 ZStackSupport:环境配置 帮我录入连接器变量。Codex 会打开一个可见 PowerShell 配置窗口，你在窗口里输入密钥；不要把密钥发到聊天里。
  3. 如果只想补缺失项，发 ZStackSupport:环境配置 只补充缺失变量，已有变量会保留。
  4. 窗口录入完成后，重启 Codex 或打开新线程。
  5. 再运行 ZStackSupport:环境配置 快照当前配置 和 ZStackSupport:连通检查 验证。

快照输出只包含变量名、是否存在、作用域、格式检查和修复建议。录入窗口会写入 Windows 用户变量，并尽量同步到当前进程；但 MCP 工具注入通常仍需要重启 Codex 或新开线程。

如果你不通过聊天技能，也可以从 marketplace 仓库根目录手动打开同一个可见配置窗口。

本机依赖检查

从 marketplace 仓库根目录运行只读诊断脚本。脚本只输出组件状态、路径和格式判断，不打印 Token、Authorization 或 base64 明文。

powershell -NoProfile -ExecutionPolicy Bypass -File .\plugins\zstack-support\scripts\check-local-dependencies.ps1

需要同时检查 MCP 远端 TCP 连通性时：

powershell -NoProfile -ExecutionPolicy Bypass -File .\plugins\zstack-support\scripts\check-local-dependencies.ps1 -CheckNetwork

需要同时检查 BBS 远端 MCP initialize、tools/list 和只读 bbs_latest 时：

powershell -NoProfile -ExecutionPolicy Bypass -File .\plugins\zstack-support\scripts\check-local-dependencies.ps1 -CheckBbsInitialize

需要同时检查 Atlassian 共享远端 MCP initialize 和 Jira/Confluence tools/list 时：

powershell -NoProfile -ExecutionPolicy Bypass -File .\plugins\zstack-support\scripts\check-local-dependencies.ps1 -CheckAtlassianInitialize

诊断重点：

  • Codex CLI 优先使用 %LOCALAPPDATA%\OpenAI\Codex\bin\*\codex.exe；裸 codex 命令如果命中 WindowsApps 包路径并报“拒绝访问”，按诊断脚本给出的可用路径运行安装脚本的 -CodexExe <path>。
  • 系统 python 可能只是 Windows Store alias；安装脚本会寻找 Python 3.10+，并把报告依赖安装到用户私有目录。可以用 -PythonExe 和 ZSTACK_SUPPORT_PYTHONPATH 显式指定。
  • LibreOffice/soffice 只用于自动 PDF/PNG 视觉 QA，不是生成 DOCX 的硬依赖。
  • 新环境只使用 ATLASSIAN_AUTHORIZATION；若旧变量 ATLASSIAN_BASIC_AUTH 仍存在，确认不再需要后手动清理。
  • 如果 BBS 远端 initialize/tools/list/bbs_latest 全部通过，但当前聊天仍没有 bbs_* 工具，说明远端、网络和认证基本可用，问题在 Codex 当前会话的 MCP 工具发现/注入层；完全退出 Codex 后重开新线程，并检查日志中的 zstack-bbs-support 工具加载记录。
  • 如果 Atlassian 远端 initialize/tools/list 全部通过，但当前聊天仍没有 Jira/Confluence 工具，说明远端、网络、认证和工具 schema 基本可用，问题在 Codex 当前会话的 MCP 工具发现/注入层；完全退出 Codex 后重开新线程，并检查日志中的 zstack_atlassian_shared 工具加载记录。

手动录入环境变量

推荐先用技能快照当前配置：

ZStackSupport:环境配置 快照当前配置

推荐方式：从 marketplace 仓库根目录打开可见 PowerShell 配置窗口，一次录入四个变量。脚本只写入 Windows 用户变量，不打印密钥内容。

powershell -NoProfile -ExecutionPolicy Bypass -File .\plugins\zstack-support\scripts\open-env-config-window.ps1

如果只想补充缺失变量，保留已有变量：

powershell -NoProfile -ExecutionPolicy Bypass -File .\plugins\zstack-support\scripts\open-env-config-window.ps1 -SkipExisting

也可以使用下面的一次性 PowerShell 模板。把尖括号内容替换成自己的值后执行；注意这类命令会进入本机命令历史，公共电脑上更推荐使用上面的可见配置窗口。

$githubToken = '<github-token>'
$tavilyToken = '<tavily-token>'
$bbsUser = '<bbs-username>'
$bbsPassword = '<bbs-password>'
$atlassianUser = '<jira-confluence-username>'
$atlassianPassword = '<jira-confluence-password>'

$bbsAuth = 'Basic ' + [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("$bbsUser`:$bbsPassword"))
$atlassianAuth = 'Basic ' + [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("$atlassianUser`:$atlassianPassword"))

[Environment]::SetEnvironmentVariable('GITHUB_MCP_TOKEN', $githubToken, 'User')
[Environment]::SetEnvironmentVariable('TAVILY_HIKARI_TOKEN', $tavilyToken, 'User')
[Environment]::SetEnvironmentVariable('ZSTACK_BBS_AUTHORIZATION', $bbsAuth, 'User')
[Environment]::SetEnvironmentVariable('ATLASSIAN_AUTHORIZATION', $atlassianAuth, 'User')

手动 PowerShell 用户变量方式：

[Environment]::SetEnvironmentVariable('GITHUB_MCP_TOKEN', '<github-token>', 'User')
[Environment]::SetEnvironmentVariable('ZSTACK_BBS_AUTHORIZATION', 'Basic <bbs-base64>', 'User')
[Environment]::SetEnvironmentVariable('TAVILY_HIKARI_TOKEN', '<tavily-token>', 'User')
[Environment]::SetEnvironmentVariable('ATLASSIAN_AUTHORIZATION', 'Basic <atlassian-base64>', 'User')

Windows 图形界面方式：

  1. 打开开始菜单。
  2. 搜索“编辑账户的环境变量”。
  3. 点击“环境变量”。
  4. 在“用户变量”中新增上面四个变量。
  5. 保存后重启 Codex 或打开新线程。

录入后，从 marketplace 仓库根目录安装或升级：

powershell -ExecutionPolicy Bypass -File .\plugins\zstack-support\scripts\install.ps1

升级时安装脚本会执行同名插件的移除和重装，并通过 codex mcp get zstack-bbs-support 校验新地址、ZSTACK_BBS_AUTHORIZATION 和 5 个批准工具。BBS 继续使用原有账号密码生成的 Basic Authorization，无需迁移凭据变量。安装完成后必须完全退出 Codex 并新建线程，既有线程不会动态增加 MCP 工具。

如果诊断脚本提示裸 codex 入口不可执行，但发现了可用 Codex 本地路径：

powershell -ExecutionPolicy Bypass -File .\plugins\zstack-support\scripts\install.ps1 -CodexExe "C:\path\to\codex.exe"

不打印密钥的检查方式

$names = @(
  'GITHUB_MCP_TOKEN',
  'ZSTACK_BBS_AUTHORIZATION',
  'TAVILY_HIKARI_TOKEN',
  'ATLASSIAN_AUTHORIZATION'
)

foreach ($name in $names) {
  [pscustomobject]@{
    Name = $name
    Present = [bool](
      [Environment]::GetEnvironmentVariable($name, 'User') -or
      [Environment]::GetEnvironmentVariable($name, 'Machine') -or
      [Environment]::GetEnvironmentVariable($name, 'Process')
    )
  }
} | Format-Table -AutoSize

GitHub 连接器

使用 GitHub 官方远程 MCP 服务器：

  1. 设置 Windows 用户或机器环境变量 GITHUB_MCP_TOKEN
  2. 重启 Codex 或打开新线程
  3. 运行 codex mcp list，确认 github 为 enabled；如果裸 codex 命令不可执行，先运行本机依赖检查脚本定位可用 Codex 路径

不要把真实 Token 写入 .mcp.json 或插件仓库。

详细配置、ZStack知识社区(BBS) 和 Tavily 连接器说明参见 CONNECTORS.md。

连接器能力一览

连接器 增强能力 安装要求
GitHub 自动只读查询 zstackio/zstack 和 zstackio/zstack-utility 源码，解释 API/配置/调用路径等产品机制 用户环境变量 GITHUB_MCP_TOKEN
ZStack知识社区(BBS) 查询历史相似事件；在完整性、查重、脱敏和用户确认通过后发布经验帖 独立连接器 zstack-bbs-support；用户环境变量 ZSTACK_BBS_AUTHORIZATION=Basic <base64(username:password)>
Tavily 搜索外部公开 Web、OS/厂商文档和论坛，辅助分析 Linux、Windows、Red Hat、Ubuntu、内核、QEMU/KVM、libvirt、Ceph、GPU 驱动等非 ZStack 问题 用户环境变量 TAVILY_HIKARI_TOKEN
Atlassian 只读查询 Jira 工单和 Confluence 内部文档。Jira 用于已知缺陷、需求编号、修复状态、影响/修复版本；Confluence 用于内部说明、版本边界、操作规范、兼容性矩阵和产品口径 共享远端 MCP zstack_atlassian_shared；用户环境变量 ATLASSIAN_AUTHORIZATION=Basic <base64(username:password)>

不连接任何连接器也可基于当前事件证据分析，但需要外部来源的断言必须标注“MCP 查询未完成”。来源类型与 E0-E5 成熟度相互独立；BBS、Tavily、Jira、Confluence 或 GitHub 都不能仅凭来源身份替代当前事件证据或单独闭环事件。

Word 模板生成依赖

变更方案 和 故障报告 技能通过 Python 脚本把 AI 写好的结构化内容写入标准 Word 模板。脚本只做模板渲染，不生成业务内容、不硬编码根因、风险或步骤。

安装脚本使用 Python 3.10+，把固定版本的 python-docx 及其依赖安装到当前用户私有目录；ZSTACK_SUPPORT_PYTHONPATH 可覆盖默认位置。生成器会校验输入、模板结构和输出路径，原子写入 DOCX，并清理模板遗留的作者、应用历史和自定义属性。LibreOffice/soffice 不是生成 DOCX 的硬依赖，只用于自动把 DOCX 渲染成 PDF/PNG 做视觉 QA。未安装 LibreOffice 时，应说明“DOCX 已生成，未完成自动视觉渲染 QA”，不要写成生成失败。

维护者在安装固定依赖后运行离线验证；使用自定义依赖目录时先设置 ZSTACK_SUPPORT_PYTHONPATH。Windows 完整入口：

powershell -NoProfile -ExecutionPolicy Bypass -File .\plugins\zstack-support\scripts\test-plugin.ps1

该入口不连接 MCP 远端，也不修改用户环境；MCP 配置、技能语义、模板元数据、安全拒绝路径、固定依赖和 DOCX 回归任一失败都会返回非零。

macOS 核心入口：

bash ./plugins/zstack-support/scripts/test-plugin-macos.sh --python /path/to/python3

macOS 入口覆盖 Bash 语法、MCP 恶意配置拒绝、私有依赖来源和 DOCX 回归，但不会操作真实 Keychain/LaunchAgent；登录会话持久化仍需在 macOS 发布机验收。

ZStack 日志路径基准

事件分析涉及日志收集时必须使用内置日志路径基准，避免生成不存在的路径。当前默认只认可以下常用路径：

管理节点：/usr/local/zstack/apache-tomcat/logs/management-server.log*
计算节点：/var/log/zstack/zstack-kvmagent.log*

不要默认使用这些幻觉路径：

/var/log/zstack/management-server.log*
/var/log/zstack/kvmagent.log*

组件或部署方式不确定时，先让用户执行只读定位命令：

find /usr/local/zstack /var/log/zstack -maxdepth 6 -type f \
  \( -name '*management-server*.log*' -o -name '*kvmagent*.log*' -o -name '*zstack*.log*' \) \
  2>/dev/null | sort