Skip to content

docs: add English README #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
webbrain-one wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add English README #2

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
194 changes: 194 additions & 0 deletions README.en-US.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <base64(username:password)>` |
| `TAVILY_HIKARI_TOKEN` | Tavily Hikari external web/vendor information query | Raw token |
| `ATLASSIAN_AUTHORIZATION` | Jira/Confluence read-only query | `Basic <base64(username:password)>` |

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 <customer feedback, alarm, error log, or screenshot transcription>` |
| Source code verification mechanism | `ZStackSupport:Source Code Verification <class name, API, configuration key, error text, or log keyword>` |
| 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](<Full URL returned by MCP>)
```

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)