mirrord-config

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Mirrord Configuration Skill

Mirrord配置技能

Purpose

目的

Generate and validate

mirrord.json

configuration files:

Generate valid configs from natural language descriptions
Validate user-provided configs against schema
Fix invalid configurations with explanations
Explain configuration options and patterns

生成并验证

mirrord.json

配置文件：

生成：根据自然语言描述生成有效的配置
验证：对照规范校验用户提供的配置
修复：修复无效配置并给出解释
解释：说明配置选项和模式

Critical First Steps

关键初始步骤

Step 1: Load references Read BOTH reference files from this skill's

references/

directory:

```
references/schema.json
```
- Authoritative JSON Schema
```
references/configuration.md
```
- Configuration reference

If using absolute paths, these are located relative to this skill's installation directory. Search for them if needed using patterns like

**/mirrord-config/references/*

Step 2: Install mirrord CLI (if not present)

bash

undefined

步骤1：加载参考文件 读取本技能

references/

目录下的两个参考文件：

```
references/schema.json
```
- 权威JSON规范
```
references/configuration.md
```
- 配置参考文档

如果使用绝对路径，这些文件位于本技能安装目录的相对路径下。必要时可使用

**/mirrord-config/references/*

这类模式搜索。

步骤2：安装mirrord CLI（若未安装）

bash

undefined

Check if installed

检查是否已安装

which mirrord || brew install metalbear-co/mirrord/mirrord || curl -fsSL https://raw.githubusercontent.com/metalbear-co/mirrord/main/scripts/install.sh | bash


**Step 3: Validate before presenting**
After generating any config, ALWAYS run:
```bash
mirrord verify-config /path/to/config.json

If validation fails, fix the config and re-validate
Only present configs that pass validation
Include validation output in your response

which mirrord || brew install metalbear-co/mirrord/mirrord || curl -fsSL https://raw.githubusercontent.com/metalbear-co/mirrord/main/scripts/install.sh | bash


**步骤3：展示前先验证**
生成任何配置后，务必运行：
```bash
mirrord verify-config /path/to/config.json

若验证失败，修复配置并重新验证
仅展示通过验证的配置
在响应中包含验证输出

Request Types

请求类型

Generate new config

生成新配置

User describes what they want without providing JSON.

Extract target (pod/deployment), namespace, features needed
Create minimal valid config using only schema-defined keys
Default to minimal configs; mirrord has sensible defaults

用户用自然语言描述需求但未提供JSON。

提取目标（Pod/Deployment）、命名空间、所需功能
使用规范定义的键创建最小化有效配置
默认采用最小化配置；mirrord有合理的默认值

Validate existing config

验证现有配置

User provides JSON to check.

Parse strictly (catch trailing commas, comments, invalid syntax)
Validate against schema
List issues by severity: Errors → Warnings → Suggestions
Provide corrected version

用户提供JSON进行检查。

严格解析（捕获尾随逗号、注释、无效语法）
对照规范验证
按严重程度列出问题：错误 → 警告 → 建议
提供修正后的版本

Modify existing config

修改现有配置

User wants changes to their config.

Validate first, then apply requested changes
Ensure modifications maintain schema conformance

用户希望对其配置进行修改。

先验证，再应用所需修改
确保修改后仍符合规范

Response Format

响应格式

For generation or fixes:

生成或修复场景：

Brief summary (1-2 sentences)
Valid JSON config in code block
Validation output from
```
mirrord verify-config
```
:

json

{
  "type": "Success",
  "warnings": [],
  "compatible_target_types": [...]
}

Short explanation of key sections (if validation passed)

简短概述（1-2句话）
代码块形式的有效JSON配置
```
mirrord verify-config
```
的验证输出：

json

{
  "type": "Success",
  "warnings": [],
  "compatible_target_types": [...]
}

关键部分的简短说明（若验证通过）

For validation:

验证场景：

Errors (schema violations - will cause failures)
Warnings (valid but potentially wrong behavior)
Suggestions (optional improvements)
Corrected JSON config

错误（违反规范 - 会导致运行失败）
警告（配置有效但可能行为不符合预期）
建议（可选的优化项）
修正后的JSON配置

Configuration Guidelines

配置指南

Common patterns (verify exact keys in schema):

常见模式（需对照规范确认确切的键）：

Target selection:

"target": "pod/name"

{"path": "pod/name", "namespace": "staging"}

Set
```
operator
```
if using operator mode
Specify
```
kube_context
```
if needed

Features:

```
"env": true
```
- Mirror environment variables
```
"env": {"include": "VAR1;VAR2"}
```
- Selective inclusion
```
"fs": "read"
```
- Read-only filesystem access
```
"network": true
```
- Enable network mirroring

"network": {"incoming": {"mode": "steal"}}

- Steal incoming traffic

Network modes:

Check schema for valid
```
incoming.mode
```
values (e.g., "steal", "mirror", "off")
Configure HTTP filters, port mapping, localhost handling

Templating:

mirrord uses Tera templates

Example:

"target": "{{ get_env(name=\"TARGET\", default=\"pod/fallback\") }}"

Templates must remain valid JSON

目标选择：

"target": "pod/name"

或

{"path": "pod/name", "namespace": "staging"}

若使用operator模式，设置
```
operator
```
必要时指定
```
kube_context
```

功能配置：

```
"env": true
```
- 镜像环境变量
```
"env": {"include": "VAR1;VAR2"}
```
- 选择性包含
```
"fs": "read"
```
- 只读文件系统访问
```
"network": true
```
- 启用网络镜像

"network": {"incoming": {"mode": "steal"}}

- 窃取入站流量

网络模式：

查看规范确认有效的
```
incoming.mode
```
值（如"steal"、"mirror"、"off"）
配置HTTP过滤器、端口映射、本地主机处理

模板功能：

mirrord使用Tera模板

示例：

"target": "{{ get_env(name=\"TARGET\", default=\"pod/fallback\") }}"

模板必须保持有效的JSON格式

Validation Rules

验证规则

Must enforce:

Strict JSON parsing (no comments, no trailing commas)
All keys must exist in schema
Correct types (string vs object, enums, etc.)
Required fields present
No
```
additionalProperties
```
where schema forbids them

Path notation for errors: Use JSON Pointer style:

/feature/network/incoming/mode

必须强制执行：

严格JSON解析（不允许注释、尾随逗号）
所有键必须存在于规范中
类型正确（字符串 vs 对象、枚举等）
必要字段已提供
在规范禁止的位置不得有
```
additionalProperties
```

错误的路径表示法： 使用JSON指针格式：

/feature/network/incoming/mode

Common Pitfalls

常见陷阱

User pastes YAML/TOML → Explain JSON required, offer to convert structure
User requests unsupported key → Say it's not in schema, suggest alternatives
Overly complex configs → Prefer minimal configs with only requested settings
Conflicting settings → Identify based on configuration.md semantics

用户粘贴YAML/TOML → 说明需要JSON格式，可提供结构转换
用户请求不支持的键 → 说明该键不在规范中，建议替代方案
过于复杂的配置 → 优先采用仅包含所需设置的最小化配置
冲突的设置 → 根据configuration.md的语义识别冲突

What to Ask (only if critical)

需要询问的信息（仅在关键时）

If request is under-specified, ask for ONE detail:

Target identity (pod name, namespace)
Incoming network behavior (steal vs mirror)
Operator usage (yes/no)
Specific ports to map/ignore

Otherwise provide safe defaults and note assumptions.

若请求信息不明确，仅询问一个细节：

目标标识（Pod名称、命名空间）
入站网络行为（窃取 vs 镜像）
是否使用Operator
需要映射/忽略的特定端口

否则提供安全的默认值并注明假设。

Automatic Validation Workflow

自动验证流程

Every generated or modified config MUST be validated before presentation:

Save config to temporary file
Run
```
mirrord verify-config <file>
```
If validation fails:
- Parse error messages
- Fix the config
- Re-validate until success
Present config with validation output

Never skip validation - it catches schema errors we might miss manually.

所有生成或修改后的配置在展示前必须经过验证：

将配置保存到临时文件
运行
```
mirrord verify-config <file>
```
若验证失败：
- 解析错误信息
- 修复配置
- 重新验证直至成功
展示配置及验证输出

绝不能跳过验证——它能捕获我们手动可能遗漏的规范错误。

Quality Requirements

质量要求

✓ Schema-first: Output must conform to

schema.json

✓ No hallucination: Only use documented keys
✓ Valid JSON: Always parseable, no comments
✓ Actionable feedback: Clear explanations of what to fix and why
✓ Minimal configs: Don't set unnecessary options

✓ 规范优先：输出必须符合

schema.json

✓ 无虚构内容：仅使用文档中已有的键
✓ 有效的JSON：始终可解析，无注释
✓ 可操作的反馈：清晰说明需要修复的内容及原因
✓ 最小化配置：不设置不必要的选项

Example Scenarios

示例场景

"Connect to pod api-7c8d9 in staging, steal traffic on port 8080, exclude secret env vars" → Read references, generate minimal config with target, network.incoming, env.exclude

User provides invalid JSON with trailing comma → Parse error → Fix syntax → Validate against schema → Explain issues → Provide corrected config

"Is my config valid?" + JSON provided → Check syntax → Validate all keys/types against schema → List violations → Suggest fixes

"连接到staging命名空间下的pod api-7c8d9，窃取8080端口的流量，排除秘密环境变量" → 读取参考文件，生成包含目标、network.incoming、env.exclude的最小化配置

用户提供带有尾随逗号的无效JSON → 解析错误 → 修复语法 → 对照规范验证 → 说明问题 → 提供修正后的配置

"我的配置有效吗？" + 提供的JSON → 检查语法 → 对照规范校验所有键/类型 → 列出违规项 → 建议修复方案