diff --git a/README.en-US.md b/README.en-US.md new file mode 100644 index 0000000..697f22d --- /dev/null +++ b/README.en-US.md @@ -0,0 +1,194 @@ +# ZStack Support Agent Codex Plugin Market + +This is the Codex plugin distribution repository for ZStack Support Agent. The repository itself is responsible for plugin installation, MCP connector declarations, environment diagnostics, and release verification; the actual support analysis capabilities reside in the [plugins/zstack-support](plugins/zstack-support) plugin. + +Plugins are designed for ZStack support engineering scenarios, featuring built-in event analysis, source code verification, environment configuration, connectivity checks, change proposals, fault reports, BBS experience feedback, handover summaries, sensitivity checks, and ZStack Support Knowledge base. GitHub, Tavily, Jira/Confluence, and BBS query capabilities are read-only; BBS additionally provides a controlled experience post publication tool requiring approval. + +## Quick Start + +### Windows + +First, perform a local dependency check. The script only outputs component status, paths, and format judgments; it does not print Tokens, Authorization, or base64 plaintext. + +```powershell +powershell -NoProfile -ExecutionPolicy Bypass -File .\plugins\zstack-support\scripts\check-local-dependencies.ps1 +``` + +Install or upgrade the plugin: + +```powershell +powershell -ExecutionPolicy Bypass -File .\plugins\zstack-support\scripts\install.ps1 +``` + +During upgrade, the installation script first removes the installed plugin with the same name, then reinstalls from the current marketplace and verifies that `zstack-bbs-support` has been registered with the new address, `ZSTACK_BBS_AUTHORIZATION`, and 5 approved tools. BBS continues to use Basic Authorization generated from the original username and password; credential variables do not need migration. + +If the diagnostic script indicates that the bare `codex` command resolves to a WindowsApps package path or is not executable, use the available Codex path from the diagnostic output: + +```powershell +powershell -ExecutionPolicy Bypass -File .\plugins\zstack-support\scripts\install.ps1 -CodexExe "C:\path\to\codex.exe" +``` + +### macOS + +Install the plugin: + +```bash +./plugins/zstack-support/scripts/install-macos.sh +``` + +Register connector variables during installation: + +```bash +./plugins/zstack-support/scripts/install-macos.sh --configure-env +``` + +Only open the visible Terminal configuration window, without reinstalling the plugin: + +```bash +./plugins/zstack-support/scripts/open-env-config-window-macos.sh +``` + +After installation, restart Codex, or open a new thread and run: + +```text +ZStackSupport:Connectivity Check +``` + +## Initial Configuration + +The plugin does not store any account, password, or Token. Each colleague needs to configure the following variables on their own local user environment: + +| Environment Variable | Purpose | Format | +|----------|------|------| +| `GITHUB_MCP_TOKEN` | GitHub MCP, read-only query of ZStack public source code | Raw token | +| `ZSTACK_BBS_AUTHORIZATION` | ZStack Knowledge Community (BBS) query and controlled experience feedback | `Basic ` | +| `TAVILY_HIKARI_TOKEN` | Tavily Hikari external web/vendor information query | Raw token | +| `ATLASSIAN_AUTHORIZATION` | Jira/Confluence read-only query | `Basic ` | + +Recommended to use environment configuration skills in Codex: + +```text +ZStackSupport:Environment Configuration Snapshot current configuration +ZStackSupport:Environment Configuration Help me enter connector variables +ZStackSupport:Environment Configuration Only supplement missing variables +``` + +Do not paste Tokens, passwords, Authorization, or base64 values into chats, documents, screenshots, or tickets. See [CONNECTORS.md](plugins/zstack-support/CONNECTORS.md) for detailed acquisition methods and troubleshooting. + +## Common Commands + +| Target | Command | +|------|------| +| Analyze a specific support event | `ZStackSupport:Event Analysis ` | +| Source code verification mechanism | `ZStackSupport:Source Code Verification ` | +| Generate change proposal | `ZStackSupport:Change Proposal Generate standard change proposal based on the above analysis` | +| Generate fault report | `ZStackSupport:Fault Report Generate standard fault report based on the above analysis` | +| Feedback processing experience | `ZStackSupport:BBS Experience Feedback Review the processing details of the current issue and generate BBS feedback draft` | +| Snapshot or enter connector variables | `ZStackSupport:Environment Configuration Snapshot current configuration` | +| Check MCP connectivity | `ZStackSupport:Connectivity Check` | +| Generate handover document | `ZStackSupport:Handover Summary Generate handover summary based on the above analysis` | +| Check shareability | `ZStackSupport:Sensitivity Check Check this handover summary` | + +For multi-round follow-up questions, continue to include the skill name, for example: + +```text +ZStackSupport:Event Analysis Continue with the previous question, check whether this fix has been merged into 4.8.x +``` + +Skill triggering in Codex is controlled by the host; normal follow-up questions are not necessarily automatically reloaded with plugin skills. + +## Workflow Rules + +- Low-risk conceptual questions can be answered directly without querying MCP. +- For specific ZStack support events, first organize the current event evidence and extract the de-identified minimal fault fingerprint, then include BBS, Jira, and Confluence as internal knowledge systems in the first batch of queries. +- When involving source code, mechanisms, call chains, field delivery, version merge, or fix confirmation, GitHub must be included in the same first batch; source code verification must not wait until the three internal sources are complete before starting, and must not conclude on source code or version lines until GitHub is complete. +- Low-risk conceptual questions, cases where the user explicitly specifies a single source, or cases without valid fault fingerprints do not force queries to the three internal sources; query failures must be written as "Verification Unfinished" and must not be written as "Not Matched." +- When the product version is unknown and affects operational, compatibility, or limit conclusions, ask for the version first; overview scenarios may list multiple versions, but must not default to conclusions based on V5. +- When multi-agent parallel processing is needed, the user must explicitly write "Use multi-agent parallel deep search"; normal event analysis defaults to the main agent for verification and summarization. +- Tavily, BBS, Jira, and Confluence results are reference evidence and must not be used to close the current customer event independently. + +Full methodology see [workflow-methodology.md](plugins/zstack-support/skills/ZStack%20Support%20Knowledge/references/workflow-methodology.md) and [evidence-routing.md](plugins/zstack-support/skills/ZStack%20Support%20Knowledge/references/evidence-routing.md). + +## Output Boundaries + +Output must first determine the audience. When the event analysis does not specify the audience, generate an internal draft clearly marked as `internal`, which is not considered directly deliverable to customers. When internal verification hits BBS, Jira, or Confluence, it must output title summaries and Markdown clickable direct links: + +```text +[Post Title](http://bbs.zstack.io/forum.php?mod=viewthread&tid=14121) +[TIC-5786](http://jira.zstack.io/browse/TIC-5786) +[Confluence Document Title]() +``` + +Confluence only uses the full URL returned by MCP; when the full URL is not available, write "Direct link not returned" and must not guess or output relative/fake links. Customer-facing output and the "customer reply direction" in internal analysis must not retain internal links, internal endpoints, and internal IDs. Both audiences are prohibited from outputting accounts, Tokens, Authorization, original page content, original comments, attachments, customer's original logs, customer screenshots, licenses, original internal MCP payloads, or un-de-identified materials. Before submission, check against [security-policy.md](plugins/zstack-support/skills/ZStack%20Support%20Knowledge/references/security-policy.md). + +## Report Generation + +`ZStackSupport:Change Proposal` and `ZStackSupport:Fault Report` generate DOCX based on the company's standard Word templates, not reconstructed from blank documents. + +Scripts are only responsible for stably writing the JSON content already completed by AI into templates; they are not responsible for supplementing business logic, root causes, risks, or steps: + +- [generate_change_proposal.py](plugins/zstack-support/skills/变更方案/scripts/generate_change_proposal.py) +- [generate_fault_report.py](plugins/zstack-support/skills/故障报告/scripts/generate_fault_report.py) + +The installation script uses Python 3.10+ and installs fixed-version `python-docx` dependencies into the current user's private directory; alternatively, a directory can be specified via `ZSTACK_SUPPORT_PYTHONPATH`. LibreOffice/`soffice` is only used for automatic PDF/PNG visual QA, and is not a hard dependency for generating DOCX. + +## Maintainer Commands + +Check dependency and environment variable status: + +```powershell +powershell -NoProfile -ExecutionPolicy Bypass -File .\plugins\zstack-support\scripts\check-local-dependencies.ps1 +``` + +Check MCP remote TCP connectivity simultaneously: + +```powershell +powershell -NoProfile -ExecutionPolicy Bypass -File .\plugins\zstack-support\scripts\check-local-dependencies.ps1 -CheckNetwork +``` + +Deep check BBS or Atlassian remote MCP: + +```powershell +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 +``` + +Full offline verification requires Python 3.10+ and fixed dependencies installed via the installation script, or pointed to by `ZSTACK_SUPPORT_PYTHONPATH`. Windows entry point covers all consistency and installation failure fixtures: + +```powershell +powershell -NoProfile -ExecutionPolicy Bypass -File .\plugins\zstack-support\scripts\test-plugin.ps1 +``` + +This entry point verifies MCP strict configuration, skill and documentation semantics, template metadata, malicious configuration rejection, installation failure propagation, fixed Python dependencies, and DOCX generator regression in sequence. Any check failure will return non-zero. + +macOS core offline entry point does not access MCP remote, does not install dependencies, and does not modify Keychain or persistent environment: + +```bash +bash ./plugins/zstack-support/scripts/test-plugin-macos.sh --python /path/to/python3 +``` + +This entry point covers Bash syntax, macOS MCP validator malicious configuration rejection, private dependency source, and DOCX regression. The actual login session lifecycle of Keychain and LaunchAgent must still be verified in real macOS for release acceptance. + +When updating locally during development, modify the cachebuster version in [plugin.json](plugins/zstack-support/.codex-plugin/plugin.json), for example: + +```text +2.9.6+codex.local-YYYYMMDDHHMMSS +``` + +Then re-execute the installation script. The installer will force refresh the plugin registration and validate BBS MCP, avoiding old cache retaining 4 read-only tools: + +```powershell +powershell -ExecutionPolicy Bypass -File .\plugins\zstack-support\scripts\install.ps1 +``` + +After updating, test in a new Codex thread to avoid the old thread continuing to use old cache. + +## Documentation Map + +- Plugin description: [plugins/zstack-support/README.md](plugins/zstack-support/README.md) +- MCP connector description: [plugins/zstack-support/CONNECTORS.md](plugins/zstack-support/CONNECTORS.md) +- Connectivity check skill: [plugins/zstack-support/skills/连通检查/SKILL.md](plugins/zstack-support/skills/连通检查/SKILL.md) +- Event analysis methodology: [workflow-methodology.md](plugins/zstack-support/skills/ZStack%20Support%20Knowledge/references/workflow-methodology.md) +- Evidence routing rules: [evidence-routing.md](plugins/zstack-support/skills/ZStack%20Support%20Knowledge/references/evidence-routing.md) +- Log path standards: [log-paths.md](plugins/zstack-support/skills/ZStack%20Support%20Knowledge/references/log-paths.md) +- Security policy: [security-policy.md](plugins/zstack-support/skills/ZStack%20Support%20Knowledge/references/security-policy.md)