package-ida-plugin

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Packaging IDA Pro Plugins

打包IDA Pro插件

This skill helps package IDA Pro plugins for distribution via the IDA Plugin Manager and the plugins.hex-rays.com repository. It covers creating and updating the

ida-plugin.json

manifest, packaging archives, and publishing via GitHub Releases.

本技能可帮助你为通过IDA Plugin Manager和plugins.hex-rays.com仓库分发的IDA Pro插件进行打包。内容涵盖创建和更新

ida-plugin.json

清单、打包归档文件，以及通过GitHub Releases发布插件。

Overview

概述

The IDA Plugin Manager is a self-service ecosystem for discovering, installing, and sharing IDA plugins:

Discovery: A daily indexer scans GitHub for repositories containing
```
ida-plugin.json
```
Repository: Published at plugins.hex-rays.com and github.com/HexRaysSA/plugin-repository
Client: HCLI command-line tool (
```
hcli plugin install <name>
```
)
Compatibility: IDA Pro 9.0+ (full support)

IDA Plugin Manager是一个用于发现、安装和共享IDA插件的自助生态系统：

发现：每日运行的索引器会扫描GitHub上包含
```
ida-plugin.json
```
的仓库
仓库：发布于plugins.hex-rays.com和github.com/HexRaysSA/plugin-repository
客户端：HCLI命令行工具（
```
hcli plugin install <name>
```
）
兼容性：完全支持IDA Pro 9.0及以上版本

Critical: Understanding Plugin Root Directory

关键要点：理解插件根目录

The
ida-plugin.json
file defines the root of the plugin. When a plugin is installed, only the directory containing

ida-plugin.json

(and its subdirectories) is copied to

$IDAUSR/plugins/

. Nothing outside this directory is included.

ida-plugin.json
文件定义了插件的根目录。安装插件时，只有包含

ida-plugin.json

$IDAUSR/plugins/

路径下，该目录外的任何内容都不会被包含在内。

Assessing Directory Structure Compatibility

评估目录结构兼容性

Before packaging, verify that your plugin's structure is self-contained:

undefined

打包前，请确认你的插件结构是自包含的：

undefined

GOOD: All plugin code is in the same directory as ida-plugin.json

正确示例：所有插件代码与ida-plugin.json在同一目录

my-repo/ ├── ida-plugin.json # Plugin root ├── my_plugin.py # Entry point - INCLUDED ├── my_plugin_lib/ # Supporting code - INCLUDED │ └── helpers.py ├── README.md # Plugin README - INCLUDED (shown on web) └── assets/ └── logo.png # Logo - INCLUDED

my-repo/ ├── ida-plugin.json # 插件根目录 ├── my_plugin.py # 入口文件 - 会被包含 ├── my_plugin_lib/ # 支持代码 - 会被包含 │ └── helpers.py ├── README.md # 插件说明文档 - 会被包含（将在网页展示） └── assets/ └── logo.png # 图标 - 会被包含

BAD: Plugin code outside the ida-plugin.json directory

错误示例：插件代码位于ida-plugin.json目录外

my-repo/ ├── plugin/ │ └── ida-plugin.json # Plugin root is here ├── src/ # NOT INCLUDED - outside plugin root! │ └── my_plugin.py # This file won't be installed! └── README.md # NOT INCLUDED - wrong directory!

undefined

my-repo/ ├── plugin/ │ └── ida-plugin.json # 插件根目录在此处 ├── src/ # 不会被包含！位于插件根目录外 │ └── my_plugin.py # 该文件不会被安装！ └── README.md # 不会被包含！目录位置错误！

undefined

Compatibility Checklist

兼容性检查清单

When assessing an existing plugin, verify:

Entry point location: Is
```
entryPoint
```
in the same directory as
```
ida-plugin.json
```
?
All imports resolvable: Are all Python imports within the plugin root or in
```
pythonDependencies
```
?
No parent directory references: Does the code use
```
../
```
to access files outside the plugin root?
Assets included: Are logos, data files, or resources inside the plugin root?
README placement: Is
```
README.md
```
in the plugin root (not repo root) for web display?

评估现有插件时，请确认：

入口文件位置：
```
entryPoint
```
是否与
```
ida-plugin.json
```
在同一目录？
所有导入可解析：所有Python导入是否位于插件根目录内，或已在
```
pythonDependencies
```
中声明？
无父目录引用：代码是否使用
```
../
```
访问插件根目录外的文件？
资源已包含：图标、数据文件或资源是否位于插件根目录内？
README位置：
```
README.md
```
是否在插件根目录（而非仓库根目录），以便在网页展示？

Common Restructuring Patterns

常见重构模式

Pattern 1: Plugin in subdirectory

If your plugin code is in a subdirectory like

src/

plugin/

, move

ida-plugin.json

into that directory:

undefined

模式1：插件位于子目录

如果你的插件代码位于

src/

或

plugin/

等子目录中，请将

ida-plugin.json

移动到该目录：

undefined

Before # After

重构前 # 重构后

my-repo/ my-repo/ ├── ida-plugin.json └── src/ └── src/ ├── ida-plugin.json # Moved here └── my_plugin.py ├── my_plugin.py └── README.md # Add for web


**Pattern 2: Monorepo with IDA plugin**

For projects where IDA plugin is one component (e.g., capa), place `ida-plugin.json` at the plugin code's location:

capa/ ├── capa/ │ ├── ida/ │ │ └── plugin/ │ │ ├── ida-plugin.json # Plugin root │ │ ├── capa_explorer.py # Entry point │ │ └── README.md # Plugin-specific docs │ └── main.py # Not included in IDA plugin └── README.md # Repo README - not the plugin README

undefined

my-repo/ my-repo/ ├── ida-plugin.json └── src/ └── src/ ├── ida-plugin.json # 移动至此 └── my_plugin.py ├── my_plugin.py └── README.md # 添加用于网页展示的文档


**模式2：包含IDA插件的单体仓库**

对于IDA插件只是其中一个组件的项目（如capa），请将`ida-plugin.json`放在插件代码所在位置：

capa/ ├── capa/ │ ├── ida/ │ │ └── plugin/ │ │ ├── ida-plugin.json # 插件根目录 │ │ ├── capa_explorer.py # 入口文件 │ │ └── README.md # 插件专属文档 │ └── main.py # 不会被包含在IDA插件中 └── README.md # 仓库根目录的README - 不属于插件文档

undefined

README in Plugin Root

插件根目录中的README

Place a

README.md

file in the same directory as

ida-plugin.json

to have it displayed on the plugins.hex-rays.com web interface. This is separate from your repository's root README:

my-plugin/
├── ida-plugin.json
├── my_plugin.py
└── README.md              # This README appears on plugins.hex-rays.com

The plugin README should focus on:

What the plugin does
How to use it within IDA
Configuration options (if using settings)
Screenshots or examples

It does not need installation instructions (the Plugin Manager handles that).

将

README.md

文件放在与

ida-plugin.json

相同的目录下，即可在plugins.hex-rays.com网页界面展示。该文档与仓库根目录的README是分开的：

my-plugin/
├── ida-plugin.json
├── my_plugin.py
└── README.md              # 此README会在plugins.hex-rays.com展示

插件README应重点包含：

插件功能介绍
在IDA中的使用方法
配置选项（如果使用设置功能）
截图或示例

无需包含安装说明（Plugin Manager会自动处理）。

The ida-plugin.json Manifest

ida-plugin.json清单

Every plugin requires an

ida-plugin.json

file in its root directory. This is the only required file beyond the plugin code itself. Paths in the metadata file are relative to the metadata file, because the metadata file defines the root of the plugin, even if its nested within a ZIP archive.

每个插件的根目录都需要一个

ida-plugin.json

文件。这是除插件代码外唯一必需的文件。元数据文件中的路径是相对于该元数据文件的，因为元数据文件定义了插件的根目录，即使它嵌套在ZIP归档文件中。

Complete Schema

完整Schema

json

{
  "IDAMetadataDescriptorVersion": 1,
  "plugin": {
    "name": "my-plugin",
    "version": "1.0.0",
    "entryPoint": "my_plugin.py",
    "description": "A one-line description of what this plugin does",
    "license": "MIT",
    "urls": {
      "repository": "https://github.com/org/my-plugin",
      "homepage": "https://example.com/my-plugin"
    },
    "authors": [
      {"name": "Author Name", "email": "author@example.com"}
    ],
    "maintainers": [
      {"name": "Maintainer Name", "email": "maintainer@example.com"}
    ],
    "idaVersions": ["9.0", "9.1", "9.2"],
    "platforms": ["windows-x86_64", "linux-x86_64", "macos-x86_64", "macos-aarch64"],
    "categories": ["malware-analysis"],
    "keywords": ["analysis", "automation"],
    "pythonDependencies": ["requests>=2.0", "pydantic>=2"],
    "logoPath": "assets/logo.png",
    "settings": []
  }
}

json

{
  "IDAMetadataDescriptorVersion": 1,
  "plugin": {
    "name": "my-plugin",
    "version": "1.0.0",
    "entryPoint": "my_plugin.py",
    "description": "插件功能的单行描述",
    "license": "MIT",
    "urls": {
      "repository": "https://github.com/org/my-plugin",
      "homepage": "https://example.com/my-plugin"
    },
    "authors": [
      {"name": "作者姓名", "email": "author@example.com"}
    ],
    "maintainers": [
      {"name": "维护者姓名", "email": "maintainer@example.com"}
    ],
    "idaVersions": ["9.0", "9.1", "9.2"],
    "platforms": ["windows-x86_64", "linux-x86_64", "macos-x86_64", "macos-aarch64"],
    "categories": ["malware-analysis"],
    "keywords": ["analysis", "automation"],
    "pythonDependencies": ["requests>=2.0", "pydantic>=2"],
    "logoPath": "assets/logo.png",
    "settings": []
  }
}

Required Fields

必填字段

Field	Type	Description
`IDAMetadataDescriptorVersion`	`1`	Always set to `1`
`plugin.name`	string	Unique identifier. ASCII letters, digits, underscores, hyphens only. No leading/trailing `_` or `-` . Used to derive the IDA namespace: `__plugins__my_plugin`
`plugin.version`	string	Semantic version `x.y.z` format. No leading `v`
`plugin.entryPoint`	string	Entry point filename (e.g., `my_plugin.py` ) or bare name for native plugins
`plugin.urls.repository`	string	GitHub URL: `https://github.com/org/project`
`plugin.authors` OR `plugin.maintainers`	array	At least one contact with `email` field required

字段	类型	描述
`IDAMetadataDescriptorVersion`	`1`	始终设置为 `1`
`plugin.name`	字符串	唯一标识符。仅允许ASCII字母、数字、下划线、连字符。不能以下划线或连字符开头/结尾。用于生成IDA命名空间： `__plugins__my_plugin`
`plugin.version`	字符串	语义化版本 `x.y.z` 格式。不能以 `v` 开头
`plugin.entryPoint`	字符串	入口文件名（如 `my_plugin.py` ），或原生插件的裸名称
`plugin.urls.repository`	字符串	GitHub URL： `https://github.com/org/project`
`plugin.authors` 或 `plugin.maintainers`	数组	至少需要一个包含 `email` 字段的联系人

Optional Fields

可选字段

Field	Type	Default	Description
`plugin.description`	string	none	One-line description shown in search results
`plugin.license`	string	none	License identifier (e.g., `MIT` , `Apache-2.0` , `GPL-3.0` )
`plugin.urls.homepage`	string	none	Homepage URL if different from repository
`plugin.idaVersions`	array or string	all versions	Supported IDA versions. Can be explicit list `["9.0", "9.1"]` or spec `">=7.4"`
`plugin.platforms`	array	all platforms	Supported platforms: `windows-x86_64` , `linux-x86_64` , `macos-x86_64` , `macos-aarch64`
`plugin.categories`	array	`[]`	See Categories section below
`plugin.keywords`	array	`[]`	Search terms for discoverability
`plugin.pythonDependencies`	array or `"inline"`	`[]`	PyPI packages. Use `"inline"` for PEP 723 metadata
`plugin.logoPath`	string	none	Relative path to logo image (16:9 aspect ratio recommended)
`plugin.settings`	array	`[]`	Plugin configuration options. See Settings section

字段	类型	默认值	描述
`plugin.description`	字符串	无	显示在搜索结果中的单行描述
`plugin.license`	字符串	无	许可证标识符（如 `MIT` , `Apache-2.0` , `GPL-3.0` ）
`plugin.urls.homepage`	字符串	无	若主页与仓库不同，填写主页URL
`plugin.idaVersions`	数组或字符串	所有版本	支持的IDA版本。可以是显式列表 `["9.0", "9.1"]` 或版本规范 `">=7.4"`
`plugin.platforms`	数组	所有平台	支持的平台： `windows-x86_64` , `linux-x86_64` , `macos-x86_64` , `macos-aarch64`
`plugin.categories`	数组	`[]`	请查看下方分类部分
`plugin.keywords`	数组	`[]`	用于提高可发现性的搜索关键词
`plugin.pythonDependencies`	数组或 `"inline"`	`[]`	PyPI包。使用 `"inline"` 表示采用PEP 723元数据
`plugin.logoPath`	字符串	无	图标图片的相对路径（推荐16:9宽高比）
`plugin.settings`	数组	`[]`	插件配置选项。请查看设置部分

Valid Categories

有效分类

disassembly-and-processor-modules
file-parsers-and-loaders
decompilation
debugging-and-tracing
deobfuscation
collaboration-and-productivity
integration-with-third-parties-interoperability
api-scripting-and-automation
ui-ux-and-visualization
malware-analysis
vulnerability-research-and-exploit-development
other

disassembly-and-processor-modules
file-parsers-and-loaders
decompilation
debugging-and-tracing
deobfuscation
collaboration-and-productivity
integration-with-third-parties-interoperability
api-scripting-and-automation
ui-ux-and-visualization
malware-analysis
vulnerability-research-and-exploit-development
other

Valid IDA Versions

有效IDA版本

Current/supported:

9.2

9.1

9.0sp1

9.0

, ...

Use a version specifier like

">=9.0"

to match multiple versions automatically.

当前支持版本：

9.2

9.1

9.0sp1

9.0

, ...

使用版本规范如

">=9.0"

可自动匹配多个版本。

Packaging Pure Python Plugins

打包纯Python插件

For simple Python plugins, the directory structure is minimal:

my-plugin/
├── ida-plugin.json
├── README.md             # Displayed on plugins.hex-rays.com
├── my_plugin.py          # entryPoint
└── my_plugin_lib/        # optional supporting modules
    ├── __init__.py
    └── helpers.py

对于简单的Python插件，目录结构非常简洁：

my-plugin/
├── ida-plugin.json
├── README.md             # 在plugins.hex-rays.com展示
├── my_plugin.py          # entryPoint
└── my_plugin_lib/        # 可选的支持模块
    ├── __init__.py
    └── helpers.py

Minimal Example

最简示例

json

{
  "IDAMetadataDescriptorVersion": 1,
  "plugin": {
    "name": "my-simple-plugin",
    "version": "1.0.0",
    "entryPoint": "my_plugin.py",
    "urls": {
      "repository": "https://github.com/username/my-simple-plugin"
    },
    "authors": [
      {"name": "Your Name", "email": "you@example.com"}
    ]
  }
}

json

{
  "IDAMetadataDescriptorVersion": 1,
  "plugin": {
    "name": "my-simple-plugin",
    "version": "1.0.0",
    "entryPoint": "my_plugin.py",
    "urls": {
      "repository": "https://github.com/username/my-simple-plugin"
    },
    "authors": [
      {"name": "你的姓名", "email": "you@example.com"}
    ]
  }
}

With Dependencies

包含依赖的示例

json

{
  "IDAMetadataDescriptorVersion": 1,
  "plugin": {
    "name": "capa",
    "version": "9.3.1",
    "entryPoint": "capa_explorer.py",
    "description": "Identify capabilities in executable files using FLARE's capa framework",
    "license": "Apache-2.0",
    "idaVersions": ">=7.4",
    "categories": ["malware-analysis", "api-scripting-and-automation", "ui-ux-and-visualization"],
    "pythonDependencies": ["flare-capa==9.3.1"],
    "urls": {
      "repository": "https://github.com/mandiant/capa"
    },
    "authors": [
      {"name": "Willi Ballenthin", "email": "wballenthin@hex-rays.com"},
      {"name": "Moritz Raabe", "email": "moritzraabe@google.com"}
    ],
    "keywords": ["capability-detection", "malware-analysis", "att&ck", "static-analysis"]
  }
}

json

{
  "IDAMetadataDescriptorVersion": 1,
  "plugin": {
    "name": "capa",
    "version": "9.3.1",
    "entryPoint": "capa_explorer.py",
    "description": "使用FLARE的capa框架识别可执行文件中的功能",
    "license": "Apache-2.0",
    "idaVersions": ">=7.4",
    "categories": ["malware-analysis", "api-scripting-and-automation", "ui-ux-and-visualization"],
    "pythonDependencies": ["flare-capa==9.3.1"],
    "urls": {
      "repository": "https://github.com/mandiant/capa"
    },
    "authors": [
      {"name": "Willi Ballenthin", "email": "wballenthin@hex-rays.com"},
      {"name": "Moritz Raabe", "email": "moritzraabe@google.com"}
    ],
    "keywords": ["capability-detection", "malware-analysis", "att&ck", "static-analysis"]
  }
}

PEP 723 Inline Dependencies

PEP 723内联依赖

If your plugin uses PEP 723 inline script metadata, set

pythonDependencies

"inline"

json

{
  "pythonDependencies": "inline"
}

Then in your entry point Python file:

python

undefined

如果你的插件使用PEP 723内联脚本元数据，请将

pythonDependencies

设置为

"inline"

：

json

{
  "pythonDependencies": "inline"
}

然后在你的入口Python文件中：

python

undefined

/// script

dependencies = [

"requests>=2.0",

"pydantic>=2"

]

///

import ida_kernwin

... rest of plugin

... 插件剩余代码

undefined

undefined

Packaging Native Plugins

打包原生插件

Native plugins require compiled binaries (.dll, .so, .dylib) for each target platform.

原生插件需要为每个目标平台提供编译后的二进制文件（.dll, .so, .dylib）。

Directory Structure

目录结构

my-native-plugin/
├── ida-plugin.json
├── README.md              # Displayed on plugins.hex-rays.com
├── my_plugin.dll          # Windows
├── my_plugin.so           # Linux
└── my_plugin.dylib        # macOS (universal or architecture-specific)

my-native-plugin/
├── ida-plugin.json
├── README.md              # 在plugins.hex-rays.com展示
├── my_plugin.dll          # Windows平台
├── my_plugin.so           # Linux平台
└── my_plugin.dylib        # macOS平台（通用或特定架构）

Entry Point Convention

入口文件约定

For native plugins, use a bare name without extension:

json

{
  "plugin": {
    "entryPoint": "my_plugin",
    "platforms": ["windows-x86_64", "linux-x86_64", "macos-x86_64", "macos-aarch64"]
  }
}

IDA will automatically append the correct extension (

.dll

.so

.dylib

) for the current platform.

对于原生插件，使用不带扩展名的裸名称：

json

{
  "plugin": {
    "entryPoint": "my_plugin",
    "platforms": ["windows-x86_64", "linux-x86_64", "macos-x86_64", "macos-aarch64"]
  }
}

IDA会自动为当前平台添加正确的扩展名（

.dll

.so

.dylib

）。

Fat Binary Archives

多平台二进制归档

Include all platform binaries in a single archive. The entry point uses the bare name, and the correct binary is selected at install time.

将所有平台的二进制文件包含在一个归档文件中。入口文件使用裸名称，安装时会自动选择正确的二进制文件。

Platform-Specific Archives

平台专属归档

Alternatively, create separate archives per platform with explicit extensions:

Windows archive:

json

{
  "plugin": {
    "entryPoint": "my_plugin.dll",
    "platforms": ["windows-x86_64"]
  }
}

Linux archive:

json

{
  "plugin": {
    "entryPoint": "my_plugin.so",
    "platforms": ["linux-x86_64"]
  }
}

或者，为每个平台创建单独的归档文件，并使用明确的扩展名：

Windows归档：

json

{
  "plugin": {
    "entryPoint": "my_plugin.dll",
    "platforms": ["windows-x86_64"]
  }
}

Linux归档：

json

{
  "plugin": {
    "entryPoint": "my_plugin.so",
    "platforms": ["linux-x86_64"]
  }
}

Plugin Settings

插件设置

For plugins requiring user configuration, declare settings in the manifest. Users configure these via

hcli plugin config

or the IDA GUI.

对于需要用户配置的插件，在清单中声明设置项。用户可通过

hcli plugin config

或IDA GUI进行配置。

Settings Schema

设置Schema

json

{
  "settings": [
    {
      "key": "api_key",
      "name": "API Key",
      "type": "string",
      "required": true,
      "documentation": "Your API key for the service"
    },
    {
      "key": "endpoint",
      "name": "API Endpoint",
      "type": "string",
      "required": false,
      "default": "https://api.example.com",
      "validation_pattern": "^https://.*$"
    },
    {
      "key": "log_level",
      "name": "Log Level",
      "type": "string",
      "required": false,
      "choices": ["debug", "info", "warning", "error"],
      "default": "info"
    },
    {
      "key": "enable_telemetry",
      "name": "Enable Telemetry",
      "type": "boolean",
      "required": false,
      "default": false
    }
  ]
}

json

{
  "settings": [
    {
      "key": "api_key",
      "name": "API密钥",
      "type": "string",
      "required": true,
      "documentation": "服务对应的API密钥"
    },
    {
      "key": "endpoint",
      "name": "API端点",
      "type": "string",
      "required": false,
      "default": "https://api.example.com",
      "validation_pattern": "^https://.*$"
    },
    {
      "key": "log_level",
      "name": "日志级别",
      "type": "string",
      "required": false,
      "choices": ["debug", "info", "warning", "error"],
      "default": "info"
    },
    {
      "key": "enable_telemetry",
      "name": "启用遥测",
      "type": "boolean",
      "required": false,
      "default": false
    }
  ]
}

Setting Fields

设置字段

Field	Type	Required	Description
`key`	string	yes	Code-level identifier (e.g., `api_key` )
`name`	string	yes	Human-readable label (e.g., `API Key` )
`type`	`"string"` or `"boolean"`	yes	Value type
`required`	boolean	yes	Whether user must provide a value
`documentation`	string	no	Help text for users
`default`	string or boolean	no	Default value if not configured
`validation_pattern`	string	no	Regex for validating string values
`choices`	array of strings	no	Allowed values (mutually exclusive with `validation_pattern` )

字段	类型	是否必填	描述
`key`	字符串	是	代码层面的标识符（如 `api_key` ）
`name`	字符串	是	人类可读的标签（如 `API密钥` ）
`type`	`"string"` 或 `"boolean"`	是	值类型
`required`	布尔值	是	是否要求用户提供值
`documentation`	字符串	否	面向用户的帮助文本
`default`	字符串或布尔值	否	未配置时的默认值
`validation_pattern`	字符串	否	用于验证字符串值的正则表达式
`choices`	字符串数组	否	允许的值（与 `validation_pattern` 互斥）

Accessing Settings in Plugin Code

在插件代码中访问设置

Use the

ida-settings

library:

python

from ida_settings import get_current_plugin_setting

api_key = get_current_plugin_setting("api_key")
log_level = get_current_plugin_setting("log_level")

使用

ida-settings

库：

python

from ida_settings import get_current_plugin_setting

api_key = get_current_plugin_setting("api_key")
log_level = get_current_plugin_setting("log_level")

Validation

验证

Always validate before publishing:

bash

undefined

发布前务必进行验证：

bash

undefined

Validate a directory

验证目录

hcli plugin lint /path/to/my-plugin

Validate a ZIP archive

验证ZIP归档

hcli plugin lint /path/to/my-plugin.zip


The linter checks:
- JSON syntax and schema compliance
- Required fields present
- Entry point file exists
- Logo file exists (if declared)
- Platform/binary consistency
- Path safety (no traversals)

hcli plugin lint /path/to/my-plugin.zip


检查器会验证：
- JSON语法和Schema合规性
- 必填字段是否存在
- 入口文件是否存在
- 图标文件是否存在（如果已声明）
- 平台/二进制文件一致性
- 路径安全性（无目录遍历）

Publishing to the Repository

发布到仓库

Step 1: Create a GitHub Release

步骤1：创建GitHub Release

Tag your commit:
```
git tag v1.0.0 && git push --tags
```
Create a GitHub Release from the tag
Attach your plugin archive (ZIP)

为提交打标签：
```
git tag v1.0.0 && git push --tags
```
基于该标签创建GitHub Release
附加插件归档文件（ZIP格式）

Step 2: Automatic Indexing

步骤2：自动索引

The indexer runs daily and automatically discovers:

Repositories with
```
ida-plugin.json
```
in the root
GitHub Releases with valid plugin archives

No manual registration required. Your plugin appears within 24 hours.

索引器每日运行，会自动发现：

根目录包含
```
ida-plugin.json
```
的仓库
包含有效插件归档的GitHub Release

无需手动注册。你的插件会在24小时内展示。

Step 3: Explicit Registration (Optional)

步骤3：显式注册（可选）

To expedite indexing, add your repository to

known-repositories.txt

Fork HexRaysSA/plugin-repository
Add your repo URL to
```
known-repositories.txt
```
(one per line)
Submit a pull request

如需加快索引速度，可将你的仓库添加到

known-repositories.txt

：

Fork HexRaysSA/plugin-repository
将你的仓库URL添加到
```
known-repositories.txt
```
（每行一个）
提交Pull Request

Troubleshooting Indexing

索引问题排查

Check the indexer log report for errors.

Common issues:

Invalid JSON syntax
Missing required fields (especially author email)
Repository URL doesn't match GitHub pattern
Entry point file not found in archive

查看索引器日志报告查找错误。

常见问题：

JSON语法无效
缺少必填字段（尤其是作者邮箱）
仓库URL不符合GitHub格式
归档文件中找不到入口文件

Multi-Plugin Archives

多插件归档

A single archive can contain multiple plugins, each in its own subdirectory:

multi-plugin.zip
├── plugin-a/
│   ├── ida-plugin.json
│   └── plugin_a.py
└── plugin-b/
    ├── ida-plugin.json
    └── plugin_b.py

Each subdirectory must have its own

ida-plugin.json

单个归档文件可包含多个插件，每个插件位于独立的子目录中：

multi-plugin.zip
├── plugin-a/
│   ├── ida-plugin.json
│   └── plugin_a.py
└── plugin-b/
    ├── ida-plugin.json
    └── plugin_b.py

每个子目录必须拥有自己的

ida-plugin.json

。

Version Updates

版本更新

To release a new version:

Update
```
plugin.version
```
in
```
ida-plugin.json
```
Create a new git tag matching the version
Create a GitHub Release with the new archive
The indexer will pick up the new version automatically

Users upgrade via:

hcli plugin upgrade <name>

发布新版本的步骤：

更新
```
ida-plugin.json
```
中的
```
plugin.version
```
创建与版本匹配的新git标签
创建包含新归档文件的GitHub Release
索引器会自动识别新版本

用户可通过以下命令升级：

hcli plugin upgrade <name>

Common Patterns

常见模式

Minimal Python Plugin Checklist

最简Python插件检查清单

Create
```
ida-plugin.json
```
with required fields
Ensure entry point file exists
Add author with email
Run
```
hcli plugin lint
```
Create GitHub Release with source archive

创建包含必填字段的
```
ida-plugin.json
```
确保入口文件存在
添加包含邮箱的作者信息
运行
```
hcli plugin lint
```
创建包含源码归档的GitHub Release

Adding Settings to Existing Plugin

为现有插件添加设置

Define settings array in
```
ida-plugin.json
```
Add
```
ida-settings
```
to
```
pythonDependencies
```
if using the library
Update plugin code to use
```
get_current_plugin_setting()
```
Document settings in README

在
```
ida-plugin.json
```
中定义settings数组
若使用库，将
```
ida-settings
```
添加到
```
pythonDependencies
```
更新插件代码以使用
```
get_current_plugin_setting()
```
在README中记录设置项

Converting Legacy Plugin

转换旧版插件

Assess directory structure: Verify all plugin code is self-contained
- Entry point and all imports within one directory
- No
```
../
```
  references to parent directories
- Data files and assets colocated with code
Restructure if needed: Move
```
ida-plugin.json
```
to where the plugin code lives
Create
```
ida-plugin.json
```
with required fields
Set correct
```
entryPoint
```
(relative to
```
ida-plugin.json
```
)
Add appropriate
```
idaVersions
```
(test compatibility!)
Declare
```
pythonDependencies
```
from requirements.txt
Add
```
README.md
```
in plugin root for web display
Validate and test locally:
```
hcli plugin lint
```
Create GitHub Release

评估目录结构：确认所有插件代码是自包含的
- 入口文件和所有导入都在同一目录内
- 无
```
../
```
  引用父目录
- 数据文件和资源与代码放在一起
如需则重构：将
```
ida-plugin.json
```
移动到插件代码所在位置
创建包含必填字段的
```
ida-plugin.json
```
设置正确的
```
entryPoint
```
（相对于
```
ida-plugin.json
```
）
添加合适的
```
idaVersions
```
（务必测试兼容性！）
从requirements.txt中声明
```
pythonDependencies
```
在插件根目录添加
```
README.md
```
用于网页展示
本地验证和测试：
```
hcli plugin lint
```
创建GitHub Release

HCLI Commands Reference

HCLI命令参考

bash

undefined

bash

undefined

List available plugins

列出可用插件

hcli plugin list

Search plugins

搜索插件

hcli plugin search <query>

Install a plugin

安装插件

hcli plugin install <name> hcli plugin install <name>==1.0.0

Upgrade a plugin

升级插件

hcli plugin upgrade <name>

Uninstall a plugin

卸载插件

hcli plugin uninstall <name>

List installed plugins

列出已安装插件

hcli plugin list --installed

Configure plugin settings

配置插件设置

hcli plugin config <name> set <key> <value> hcli plugin config <name> get <key>

Validate plugin

验证插件

hcli plugin lint /path/to/plugin

undefined

hcli plugin lint /path/to/plugin

undefined

Resources

资源

Plugin Repository: plugins.hex-rays.com
Documentation: hcli.docs.hex-rays.com
Repository Source: github.com/HexRaysSA/plugin-repository
HCLI Source: github.com/HexRaysSA/ida-hcli
IDA Settings Library: github.com/williballenthin/ida-settings
Support: github.com/HexRaysSA/ida-hcli/issues

插件仓库：plugins.hex-rays.com
文档：hcli.docs.hex-rays.com
仓库源码：github.com/HexRaysSA/plugin-repository
HCLI源码：github.com/HexRaysSA/ida-hcli
IDA Settings库：github.com/williballenthin/ida-settings
支持：github.com/HexRaysSA/ida-hcli/issues