这是 ZStack Support Agent 的 Codex 插件分发仓库。仓库本身负责插件安装、MCP 连接器声明、环境诊断和发布校验；真正的支持分析能力在 plugins/zstack-support 插件内。
插件面向 ZStack 支持工程场景，内置事件分析、源码查证、环境配置、连通检查、变更方案、故障报告、BBS 经验回流、交接摘要、脱敏检查和 ZStack Support Knowledge 知识库。GitHub、Tavily、Jira/Confluence 以及 BBS 查询能力保持只读；BBS 另开放一个需要审批的经验帖发布工具。
先做本机依赖检查。脚本只输出组件状态、路径和格式判断，不打印 Token、Authorization 或 base64 明文。
powershell -NoProfile -ExecutionPolicy Bypass -File .\plugins\zstack-support\scripts\check-local-dependencies.ps1安装或升级插件：
powershell -ExecutionPolicy Bypass -File .\plugins\zstack-support\scripts\install.ps1升级时安装脚本会先移除已安装的同名插件，再从当前 marketplace 重新安装，并校验 zstack-bbs-support 已注册新地址、ZSTACK_BBS_AUTHORIZATION 和 5 个批准工具。BBS 继续使用原有账号密码生成的 Basic Authorization，无需迁移凭据变量。
如果诊断脚本提示裸 codex 命令命中 WindowsApps 包路径或不可执行，使用诊断输出的可用 Codex 路径：
powershell -ExecutionPolicy Bypass -File .\plugins\zstack-support\scripts\install.ps1 -CodexExe "C:\path\to\codex.exe"安装插件：
./plugins/zstack-support/scripts/install-macos.sh安装时同时录入连接器变量：
./plugins/zstack-support/scripts/install-macos.sh --configure-env只打开可见 Terminal 配置窗口，不重复安装插件：
./plugins/zstack-support/scripts/open-env-config-window-macos.sh安装后请重启 Codex，或打开一个新线程再运行：
ZStackSupport:连通检查
插件不保存任何账号、密码或 Token。每位同事需要在自己的本机用户环境中配置以下变量：
| 环境变量 | 用途 | 格式 |
|---|---|---|
GITHUB_MCP_TOKEN |
GitHub MCP，只读查询 ZStack 公开源码 | 原始 token |
ZSTACK_BBS_AUTHORIZATION |
ZStack 知识社区(BBS) 查询与受控经验回流 | Basic <base64(username:password)> |
TAVILY_HIKARI_TOKEN |
Tavily Hikari 外部 Web/厂商资料查询 | 原始 token |
ATLASSIAN_AUTHORIZATION |
Jira/Confluence 只读查询 | Basic <base64(username:password)> |
推荐在 Codex 中使用环境配置技能：
ZStackSupport:环境配置 快照当前配置
ZStackSupport:环境配置 帮我录入连接器变量
ZStackSupport:环境配置 只补充缺失变量
不要把 Token、密码、Authorization 或 base64 值粘贴到聊天、文档、截图或工单里。详细获取方式和故障定位见 CONNECTORS.md。
| 目标 | 命令 |
|---|---|
| 分析具体支持事件 | ZStackSupport:事件分析 <客户反馈、告警、错误日志或截图转写> |
| 查源码机制 | ZStackSupport:源码查证 <类名、API、配置键、错误文本或日志关键词> |
| 生成变更方案 | ZStackSupport:变更方案 基于上面的分析生成标准变更方案 |
| 生成故障报告 | ZStackSupport:故障报告 基于上面的分析生成标准故障报告 |
| 回流处理经验 | ZStackSupport:BBS经验回流 审核刚才问题的处理细节并生成 BBS 回流稿 |
| 快照或录入连接器变量 | ZStackSupport:环境配置 快照当前配置 |
| 检查 MCP 连通性 | ZStackSupport:连通检查 |
| 生成交接文档 | ZStackSupport:交接摘要 基于上面的分析生成交接摘要 |
| 检查可分享性 | ZStackSupport:脱敏检查 检查这份交接摘要 |
多轮追问建议继续带上技能名，例如：
ZStackSupport:事件分析 继续上一个问题，查一下这个修复有没有合到 4.8.x
Codex 的技能触发由宿主控制，普通追问不一定会自动重新加载插件技能。
- 低风险概念问题可以直接回答，不默认查询 MCP。
- 具体 ZStack 支持事件先整理当前事件证据并提取去标识化的最小故障指纹，再把 BBS、Jira 和 Confluence 作为内部知识系统放入首批查证。
- 涉及源码、机制、调用链、字段下发、版本合入或修复确认时，同一首批必须包含 GitHub；不得等内部三源查完后才开始源码查证，GitHub 未完成时不能下源码或版本线定论。
- 低风险概念问题、用户明确限定单一来源或尚无有效故障指纹时不强制查询内部三源；查询失败必须写“查证未完成”，不能写成“未命中”。
- 产品版本未知且会影响操作、兼容或限制结论时，先询问版本；概览场景可并列版本，但不能默认按 V5 下结论。
- 需要多 agent 并行时，用户必须显式写“用多 agent 并行深查”；普通事件分析默认由主 agent 查证汇总。
- Tavily、BBS、Jira 和 Confluence 结果属于参考证据，不能单独关闭当前客户事件。
完整方法论见 workflow-methodology.md 和 evidence-routing.md。
输出必须先确定受众。事件分析未指定受众时生成明确标注为 internal 的内部草稿，不视为可直接发给客户。内部查证命中 BBS、Jira 或 Confluence 时，必须输出标题摘要和 Markdown 可点击直达链接：
[帖子标题](http://bbs.zstack.io/forum.php?mod=viewthread&tid=14121)
[TIC-5786](http://jira.zstack.io/browse/TIC-5786)
[Confluence 文档标题](<MCP 返回的完整 URL>)
Confluence 只使用 MCP 返回的完整 URL；完整 URL 不可得时写“直达链接未返回”，不得猜测或输出相对/伪链接。面向客户的输出以及 internal 分析中的“客户回复口径”不得保留内部链接、内部端点和内部编号。两种受众都禁止输出账号、Token、Authorization、原始页面正文、评论原文、附件、客户原始日志、客户截图、许可证、内部原始 MCP 载荷或未脱敏材料。提交前按 security-policy.md 检查。
ZStackSupport:变更方案 和 ZStackSupport:故障报告 基于公司标准 Word 模板生成 DOCX，不从空白文档重造。
脚本只负责把 AI 已完成判断的 JSON 内容稳定写入模板，不负责补业务逻辑、根因、风险或步骤：
安装脚本会使用 Python 3.10+，把固定版本的 python-docx 依赖安装到当前用户的私有目录；也可以通过 ZSTACK_SUPPORT_PYTHONPATH 指定目录。LibreOffice/soffice 只用于自动 PDF/PNG 视觉 QA，不是生成 DOCX 的硬依赖。
检查依赖和环境变量状态：
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 或 Atlassian 远端 MCP：
powershell -NoProfile -ExecutionPolicy Bypass -File .\plugins\zstack-support\scripts\check-local-dependencies.ps1 -CheckBbsInitialize
powershell -NoProfile -ExecutionPolicy Bypass -File .\plugins\zstack-support\scripts\check-local-dependencies.ps1 -CheckAtlassianInitialize完整离线验证要求 Python 3.10+，并已通过安装脚本安装固定依赖，或由 ZSTACK_SUPPORT_PYTHONPATH 指向该依赖目录。Windows 入口覆盖全部一致性和安装失败夹具：
powershell -NoProfile -ExecutionPolicy Bypass -File .\plugins\zstack-support\scripts\test-plugin.ps1该入口依次验证 MCP 严格配置、技能与文档语义、模板元数据、恶意配置拒绝、安装失败传播、固定 Python 依赖和 DOCX 生成器回归。任一检查失败都会返回非零。
macOS 核心离线入口不访问 MCP 远端、不安装依赖、不修改 Keychain 或持久环境：
bash ./plugins/zstack-support/scripts/test-plugin-macos.sh --python /path/to/python3该入口覆盖 Bash 语法、macOS MCP validator 的恶意配置拒绝、私有依赖来源和 DOCX 回归。Keychain 与 LaunchAgent 的实际登录会话生命周期仍必须在真实 macOS 上做发布验收。
本地开发更新时，修改插件后刷新 plugin.json 里的 cachebuster 版本，例如：
2.9.6+codex.local-YYYYMMDDHHMMSS
然后重新执行安装脚本。安装器会强制刷新插件注册并验证 BBS MCP，避免旧缓存继续保留 4 个只读工具：
powershell -ExecutionPolicy Bypass -File .\plugins\zstack-support\scripts\install.ps1更新后新开 Codex 线程测试，避免旧线程继续使用旧缓存。
- 插件说明：plugins/zstack-support/README.md
- MCP 连接器说明：plugins/zstack-support/CONNECTORS.md
- 连通检查技能：plugins/zstack-support/skills/连通检查/SKILL.md
- 事件分析方法论：workflow-methodology.md
- 查证路由规则：evidence-routing.md
- 日志路径基准：log-paths.md
- 安全策略：security-policy.md