InstructionX

Download

InstructionX

Release Notes

Alpha 1.0.5

InstructionX Alpha 1.0.5 (Pre-release)

一、多语言（i18n）子系统（全新功能）

本版本引入了完整的多语言支持体系，框架界面与插件均具备多语言能力：

  • 新增 core/i18n 多语言子系统：XML 语言文件（一个语言一个文件）+ 取词回退链（当前语言 → 默认语言 → 错误提示）+ 插件语言注册表 + 配置存储（config/i18n.json / config/plugin_languages.json，原子写、损坏自动备份重建）；默认语言为中文（开发者设定）
  • 界面语言实时切换：新增语言选择对话框与「语言」菜单入口，选中即全局生效，无需重启
  • 框架语言文件：新增默认语言 ui/text/zh.xml（375+ 键）与英文 ui/text/en.xml（402 键，键集合与默认语言一致）
  • 全部界面文案迁移至 i18n 取词：主窗口 / 标题栏 / 技能面板 / 工作区、托盘与关闭确认对话框、用量面板、插件管理对话框、GitHub 安装 / 许可 / 关于 / 字体管理对话框、LLM 设置对话框，均支持语言实时刷新（_retranslate_ui）
  • 插件多语言机制：插件经 PluginServices.localization 注入取词门面（ILocalizationFacade）；插件语言包目录 text/ 自动扫描注册，加载 / 卸载 / 热重载全程挂钩；支持每插件语言覆盖（插件管理对话框新增「语言」设置入口与状态行）；IXPlugin.json 的 name / description 支持多语言字典形式（旧字符串形式兼容）
  • LLM 模型能力标签改为 i18n 运行时取词（保留 CAPABILITY_LABELS 兼容）
  • 新增 i18n 完整性校验脚本（scripts/check_i18n_completeness.py）：默认语言必须覆盖源码全部取词键，其他语言缺键 / 孤立键给出警告
  • 菜单项「界面语言…」简化为「语言」

二、InstructionX_UIKit 组件库同步（上游 alpha-v1.0.1 → alpha-v1.0.2）

  • 同步上游 alpha-v1.0.2：新增 MarkdownView Markdown 渲染组件（含 matplotlib LaTeX 公式异步渲染中枢）、mermaid/ 子包（官方 mermaid.js WebEngine 渲染 + 自绘降级 + 交互查看器）、chat_conversation 流式对话布局（气泡操作条 / 流式追加 / 自定义文案），以及 components / charts / anim / theme / layouts / blueprint 六模块审计修复（公共 API 零变化）
  • 蓝图画布 GPU 加速渲染（alpha-v1.0.1 同步）：GL/软件双绘制视口，网格 / 边路径缓存与视口裁剪，选中阴影改画布层自绘
  • 蓝图 GL 视口预热：主窗口构造期预创建隐藏蓝图画布，修复打开蓝图插件时顶层窗口原生句柄重建导致的闪烁
  • 修复窗口化模式下蓝图 GL 视口呈现冻结导致的拖拽卡顿（首帧重绘 + 手势期全体节点位图代理）
  • main.py 统一顶层窗口图形 API 为 OpenGL（QApplication 创建前设置）：蓝图 GL 视口与 Mermaid WebEngine 查看器同窗口混用的前置条件，避免 “Failed to get a QRhi” 与窗口闪烁

三、插件开发约定文档修正

  • IXRepo.json 描述修正：由「仅插件集需要」更正为所有插件仓库（含单插件仓库）均需仓库索引文件，并补充旧式扁平单插件仓库的兼容性说明（与安装器实际行为一致）
  • 插件语言包目录 text/ 由可选改为必需（框架对存量无语言包插件保持兼容）

四、安全修复（Dependabot）

  • 升级 7 个依赖，修复全部 24 项 GitHub Dependabot 安全预警（11 高 / 8 中 / 5 低）：
    • mcp 1.27.0 → 1.29.1：3 项高危（HTTP 会话请求不校验身份、实验性任务处理器越权访问/取消他方任务、WebSocket 传输缺 Host/Origin 校验）——框架内置 MCP Server 直接相关
    • cryptography 47.0.0 → 50.0.0（Bleichenbacher oracle、证书路径构建指数爆炸、捆绑 OpenSSL 漏洞等 4 项）
    • pyjwt 2.12.1 → 2.13.0（公钥 JWK 被当作 HMAC 密钥伪造令牌、算法白名单绕过等 5 项）
    • starlette 1.0.0 → 1.6.0（StaticFiles UNC 路径 NTLM 凭证窃取等 5 项）
    • python-multipart 0.0.26 → 0.0.32（multipart 解析 DoS、参数走私等 5 项）
    • idna 3.13 → 3.19、pydantic-settings 2.14.0 → 2.15.0
  • mcp 依赖约束调整为 >=1.28.1,<2：mcp 2.x 移除了框架使用的 mcp.server.fastmcp.FastMCP 导入路径，故锁定 1.x 修复线（pyproject.toml 与 requirements.txt 同步）；修复后 MCP 冒烟 23/23 通过、全量测试套件 788 例全绿

五、工程与元信息

  • 框架版本号升级为 Alpha 1.0.5（core/version.py 单一来源）
  • 应用组织名由 LumenThread 改为 KKPIP-Tech（与 GitHub 组织一致；QSettings 旧组织键不再读取，LLM 设置对话框「上次选中的实例」记忆重置一次）
  • .gitignore 忽略 plugin/ 目录顶层文件（插件仓库根的 IXRepo.json/README.md 等属插件仓库内容）

六、测试

  • 全部改动均通过验证：pytest 套件 788 例全绿（test 分支），新增版本号 / 应用标识 / UIKit 同步守卫测试 24 例；上游 UIKit 自身离屏测试 32/32 通过；i18n 完整性校验通过；6 个冒烟脚本全部通过；实机启动无异常
  • 依赖安全升级专项回归：MCP 真实 SDK 冒烟 23/23 通过（mcp 1.x 修复线），升级后全量套件复跑 788 例全绿，实机启动无异常；本地锁文件经 24 条预警的漏洞版本范围逐条比对，0 条仍受影响

七、插件兼容性说明

  • 面向插件的公开接口（IPlugin / IPluginInfo / PluginServices 等）保持向后兼容：PluginServices 末尾追加 localization 字段，IPluginInfo 新增可选 default_language 声明，存量插件无需改动即可运行
  • 存量插件未提供 text/ 语言包目录时行为与旧版本完全一致（优雅降级）；但新开发插件须遵循「text/ 必需、IXRepo.json 必需」的最新约定

▎ ⚠️ 测试版本声明
▎ 当前版本为预发布测试版（Pre-release），仅供开发者和早期体验者使用。核心功能已完成实现，但尚未经过全面生产环境验证。部分内部 API 签名、配置格式及插件接口可能在未来版本中发生破坏性变更（Breaking Changes），请勿将其用于生产环境的关键业务。

⚠️ 已知限制与注意事项

  1. API 不稳定：IPlugin、IPluginInfo、PluginServices 等核心接口以及 core/llm、core/mcp 模块的 API 签名可能在后续版本中调整，插件开发者需留意变更日志。
  2. 配置格式可能变更：config/llm_providers.json、config/mcp_config.json、config/plugin_order.json 等配置文件的结构尚未冻结。
  3. LLM Provider 适配待完善：部分 Provider 的流式解析、缓存适配和价格计算为初始实现，可能存在边界 case 处理不足。
  4. 文档持续迭代：开发者文档与代码实现正在同步更新，部分章节可能滞后于最新代码。
Alpha 1.0.4

InstructionX Alpha 1.0.4 (Pre-release)

一、字体管理（全新子系统）

  • 框架不再捆绑第三方字体：移除内置的 5 个字体家族（约 90MB）与 FontMap 静态注册表
  • 新增 core/font 字体管理子系统：字体安装/卸载（应用级注册，不写系统字体目录）、注册表持久化（data/fonts/）、启动自动恢复
  • 完善的系统字体回退机制：get_font/resolve_family 按「请求字体 → 自定义回退 → 系统默认字体」链解析，字体缺失时界面自动使用系统字体
  • 插件开发者接口：PluginServices.font_manager（增量扩展，向后兼容）或 get_font_manager()，插件可安装、查询、使用字体
  • 新增字体管理对话框（编辑 → 字体管理…）：已安装/系统字体分组浏览、实时效果预览（示例文本可编辑、字号可调）、安装/卸载、回退提示

二、系统托盘与关闭行为（全新）

  • 新增系统托盘子系统（ui/tray，门面 + 平台后端注册表）：关窗可转入托盘继续运行，托盘菜单含显示主窗口/正在运行的插件/后台正在运行的任务/退出四项，状态子菜单动态重建
  • 新增关闭确认对话框：每次关闭询问「退出程序 / 最小化到托盘 / 取消」（无记忆选项，Esc/叉号等价取消）
  • Windows 注销/关机时静默直退，不弹窗、不阻塞系统关机

三、InstructionX_UIKit 主题体系全面落地

  • 引入 InstructionX_UIKit 组件库（设计令牌 + 57 组件 + 12 布局 + 原生图表引擎 + 蓝图节点图），移除旧 StyleQSS 主题系统
  • 全局主题统一为 UIKit 令牌驱动（light/dark/auto），全部对话框与面板完成迁移：关于、许可、GitHub 安装、插件管理、LLM 设置、用量面板；QMessageBox 全量替换为 UIKit Dialog/Message
  • LLM 设置对话框主题实时跟随应用换肤
  • 蓝图节点注册表新增 owner 命名空间隔离：跨插件同名节点类型可共存

四、用量查询面板升级

  • 趋势图由折线图改为日历热力图（GitHub 贡献图风格），基于 UIKit 原生图表引擎，随主题自动换肤
  • 范围档调整为近半年/近一年/自定义，面板高度随热力图自然高度自适应
  • 修复跨年月份标签缺失与悬停不显示日期的问题

五、插件系统增强

  • 插件安装体验补全：安装后自动刷新、Release 升级/降级、卸载、自定义分组与排序
  • 插件依赖安装优先使用 uv，uv 不可用或失败时回退 pip

六、后台任务修复

  • 修复禁用态定时任务无法注销（僵尸记录）的问题
  • 修复已停止长期任务无法删除的存储残留问题
  • 托盘后台任务菜单改用运行时表判定长期任务运行态，修复任务从托盘消失的问题

七、LLM 更新

  • 预设模型清单更新：GLM 新增 glm-5.2 / glm-5.1 / glm-5v-turbo / glm-ocr / autoglm-phone；MiniMax 新增 MiniMax-M3（支持 1M 上下文）

八、界面与文案调整

  • 「许可信息」窗口更名「开源组件许可」，移除全部字体许可条目（框架不再提供第三方字体）
  • 移除菜单栏「用户中心」（CE 版本不提供该功能）
  • 技能面板官方/第三方切换按钮紧凑化

九、文档与工程

  • 新增 AGENTS-for-PLUGIN-DEV.md：插件开发专用 Agent 规范（开发模式、目录边界、分支约定、编码硬性原则）
  • 文档与代码全量一致性校验：40 篇文档逐条核对，修正 MCP 工具命名、接口签名、行为描述等 90 余处错误/过时内容
  • 版本号升级至 Alpha 1.0.4（core/version.py 单一来源）

▎ ⚠️ 测试版本声明
▎ 当前版本为预发布测试版（Pre-release），仅供开发者和早期体验者使用。核心功能已完成实现，但尚未经过全面生产环境验证。部分内部 API 签名、配置格式及插件接口可能在未来版本中发生破坏性变更（Breaking Changes），请勿将其用于生产环境的关键业务。

⚠️ 已知限制与注意事项

  1. API 不稳定：IPlugin、IPluginInfo、PluginServices 等核心接口以及 core/llm、core/mcp 模块的 API 签名可能在后续版本中调整，插件开发者需留意变更日志。
  2. 配置格式可能变更：config/llm_providers.json、config/mcp_config.json、config/plugin_order.json 等配置文件的结构尚未冻结。
  3. LLM Provider 适配待完善：部分 Provider 的流式解析、缓存适配和价格计算为初始实现，可能存在边界 case 处理不足。
  4. 文档持续迭代：开发者文档与代码实现正在同步更新，部分章节可能滞后于最新代码。
Alpha 1.0.3

InstructionX Alpha 1.0.3 (Pre-release)

自 alpha-v1.0.2 以来，框架经历了一轮全模块深度审计与修复（Major_Fix / Framework_Fix 系列）、一次 LLM 框架 v2 架构重构，以及 LLM 设置对话框与用量面板的 UI 全面重写。以下为按功能模块分类的完整改动汇总。

⚠️ 重要变更提示（插件开发者必读）

  • ILLMService 插件接口破坏性重构：接口改为契约式显式继承，ProviderInfo 重构消除密钥泄漏风险，删除底层泄漏方法与 provider_extension 死代码。使用 LLM 插件服务的第三方插件需按新接口适配。
  • LLM 配置 schema v1 → v2 自动迁移：config/llm_providers.json 首次启动自动迁移并生成 .bak 备份，无需手动干预。
  • 定价字段迁移：定价单位统一为「元/百万 tokens」，旧 per_1k 键加载时自动 ×1000 兼容，只写新键 per_1m。
  • API 密钥存储格式升级：统一为跨平台 Base64 编码存储（b64: 前缀，编码非加密），旧明文配置自动升级。

LLM 框架（v2 架构重构）

  • 新增统一模型 schema：能力闭集与互斥规则、normalize 兼容两种历史 schema、三路合并接口
  • 新增 Provider 预设目录（catalog）：5 家预设元数据与预设模型目录，随程序发布只读
  • 配置层 schema v2 迁移与 LLMConfig 单例化：ProviderConfig 新增 preset_id/adapter/order，配置变更订阅/版本号通知
  • 适配器注册表改造：注册表语义改为 adapter 分发，新增 openai-compatible 兜底适配器，自定义 OpenAI 兼容实例零代码接入
  • 消息与工具调用类型体系重构：ToolCall 类型化、StreamChunk 字段实填、chat_with_tools 返回 ToolChatResult、新增 ToolDefinition/register_typed
  • LLMProvider 运行时增强：按 adapter 分发实例支持同厂商多实例，新增 check_provider/check_model/get_default_provider_id 与配置版本惰性刷新，空配置优雅降级
  • 用量记录查询新增按时间倒序返回参数（descending），倒序在分页之前生效

LLM 稳定性修复（全面审计）

  • LLMProvider 核心重写：stream_chat 真实迭代生成器、None 参数双层过滤防 API 400、default 自动选择+粘性缓存、健康跟踪与错误留痕
  • 对话管理：上下文 token 估算与截断、孤儿消息修复、会话持久化原子写、线程安全
  • 工具调用：并行工具调用合法序列化、非法 arguments JSON 不再静默执行、流式 tool_calls 分片聚合、max_turns 用尽清理
  • providers 基座加固：429/5xx/连接/超时指数退避重试（Retry-After 优先）、超时分级、Session 线程安全、last_error 错误留痕
  • 各厂商适配补齐：GLM/MiniMax/Ollama 补齐 tool_calls 解析、Vision 统一 OpenAI 兼容 content 数组、generate_image/TTS 端点实现
  • 用量存储优化：单后台写线程+防抖合并，消除每记录全量重写的平方级 IO，超万条自动 prune
  • 定价合并层支持 input/output 简写与 per_1m 标准键双通道，消除三方口径差
  • LLMProvider 启动加载模型缓存时兼容 TTL 时间戳信封格式
  • AuthenticationError 补充构造参数，消除 401 处理器自身 TypeError

UI 界面

  • LLM 设置对话框全新 UI 包（ui/dialog/llm_settings/）：主题 token 视觉迁移、品牌 SVG 图标、自动保存语义、连接检测、模型分组管理与批量删除、健康检查与模型同步对话框，删除旧 1800 行单文件实现
  • LLM 设置页面像素级重构：搜索栏、ON/OFF 开关、模型分组、模型编辑对话框紧凑布局与样式渲染一致性
  • 用量查询面板迁移至新版设计：拆分为 ui/usage_panel 包，KPI 卡片新增同比，趋势图改用 QtCharts 平滑折线，使用历史按时间倒序展示
  • 修复模型服务窗口停用模型后跳回首个供应商且模型列表丢失、二次打开报悬挂回调错误的问题
  • 修复编辑模型类型后 Model List 不同步显示、切换 Provider 后模型列表边框级联和残影问题
  • 主窗口与标题栏：删除 15 个未使用导入（启动提速）、边缘缩放窗口漂移修复、插件加载失败可重试、安装成功双弹窗去重
  • 用量面板：QThread 泄漏修复、matplotlib dpi 适配高分屏、图表标签中文化、UTC 时间戳本地转换、分页优化
  • 各对话框主题色统一与硬编码色清理、技能面板英文计数中文化与键盘焦点恢复
  • 删除 882 行死代码 llm_model_service_dialog.py 与 ui/style 空壳目录

MCP 协议

  • Server 对齐 mcp 1.27.0 SDK，工具注册改真实 API（失败显式记 error）
  • Client 事件循环在专用 daemon 线程常驻运行，修复连接超时与会话即建即关问题
  • 工具名净化对齐 OpenAI 规范，重名先注销再注册
  • 新增 auth_token/exposed_plugins 配置，HTTP 加 Bearer 中间件认证，bridge 按白名单过滤暴露
  • stdio 模式 bridge sync 时序修复、stop() 真实关停传输层、is_running 状态机可信
  • 令牌混淆存储、恒定时间比较与暴露面失败关闭

插件系统

  • PluginManager：重复注册检查、reload 通知 MCP 注销、新增 sanitize_tool_name 工具名净化、Service 实例化改签名分析
  • PluginIdentity：增加 data/plugin_identity 回退持久化，只读插件目录下 UUID 保持稳定
  • PluginVersion 改 frozen 可哈希、total_ordering 重构比较协议
  • GitHub 安装器安全加固：路径穿越防护、zip-slip 校验+大小数量上限、流式下载、升级前 .bak 备份可回滚
  • 插件依赖安装增加白名单校验，版本约束改 packaging.SpecifierSet 支持复合约束
  • 插件顺序保存改原子写

数据层与后台任务

  • DataProvider：修复订阅回调持锁死锁、load_data 竞态、save_asset 路径穿越消毒、JSON 深拷贝一致性
  • SQLite 后端：迁移改显式 BEGIN IMMEDIATE 真事务、schema 版本容错、专用 SQL 消除全表扫描
  • sql_map DDL 单一来源拼接、PRAGMA table_info 表白名单加固
  • 后台任务：shutdown 限时等待不再无限阻塞、长期任务记录不再误删、取消竞态修复、自动重启指数退避+上限 10 次
  • 任务存储：读盘失败备份 .corrupt.bak 防覆盖、写失败置脏重试、新增 cleanup_old_tasks（30 天）自动清理
  • 修复资产路径逃逸、任务存储并发竞态与关闭后幽灵注册

工具模块与接口层

  • 新增 thread_utils 线程编组工具（is_ui_thread/run_in_ui_thread/run_in_ui_thread_sync，无 QApp 安全降级）
  • 日志系统加固：module_name 缺失容错、get_name 按文件名缓存、新增 INSTRUCTIONX_LOG_LEVEL/INSTRUCTIONX_LOG_DIR 环境变量、main.py 增加 sys.excepthook 兜底
  • style_qss 修复：url 截断、箭头 PNG 写用户缓存目录、键盘焦点可见性、样式优先级单一来源
  • font_map 日文字重 weight=0 改显式哨兵对象，消除与 None 的语义冲突
  • 接口层自包含化：import core.interfaces 不再牵入 PySide6/core.plugin，DataNamespace 与 TaskType/TaskStatus 枚举单一来源化

构建 / CI / 杂项

  • 版本号更新为 Alpha 1.0.3（core/version.py 单一来源）
  • 版本号单一来源化：core.version.VERSION 为唯一事实来源，pyproject 动态读取
  • pyproject 补全全部运行依赖，收敛 requirements.txt 与其同步，修复 pytest 版本双轨矛盾
  • 新增 GitHub Actions pytest 工作流（windows + Python 3.14）
  • 修复 .gitignore 无效规则，取消跟踪用户运行态文件
  • README 中英文版许可证表述与 LICENSE（InstructionX Commercial Source License）统一
  • 新增 LLM/task/MCP/utils 修复冒烟验证脚本（scripts/）

文档

  • 同步 LLM Provider v2 架构文档与 AGENTS.md（预设目录/实例化/适配器注册表/配置 schema v2/ILLMService 接口/UI 新包结构）
  • 二次审计文档收尾：接口返回值、组件表与过期示例同步
  • 同步依赖清单与目录树文档，许可清单补齐
  • 恢复插件开发文档中 service.py/information.py/config 为必需文件的说明
  • 同步 README 与核心模块文档（LLM/task/MCP 接口与 docstring 对齐实现）
  • 明确 Commit 信息格式规范

▎ ⚠️ 测试版本声明
▎ 当前版本为预发布测试版（Pre-release），仅供开发者和早期体验者使用。核心功能已完成实现，但尚未经过全面生产环境验证。部分内部 API 签名、配置格式及插件接口可能在未来版本中发生破坏性变更（Breaking Changes），请勿将其用于生产环境的关键业务。

⚠️ 已知限制与注意事项

  1. API 不稳定：IPlugin、IPluginInfo、PluginServices 等核心接口以及 core/llm、core/mcp 模块的 API 签名可能在后续版本中调整，插件开发者需留意变更日志。
  2. 配置格式可能变更：config/llm_providers.json、config/mcp_config.json、config/plugin_order.json 等配置文件的结构尚未冻结。
  3. LLM Provider 适配待完善：部分 Provider 的流式解析、缓存适配和价格计算为初始实现，可能存在边界 case 处理不足。
  4. 文档持续迭代：开发者文档与代码实现正在同步更新，部分章节可能滞后于最新代码。
Alpha 1.0.2

InstructionX Alpha 1.0.2 (Pre-release)

本次更新内容：

  1. 数据后端从原子化 Json 文件读写改为 SQLite 数据库读写，配合LRU缓存，大幅增加读写数据性能；
  2. Json 自动迁移，无需手动从 Json 数据文件迁移至 SQLite 数据库；
  3. DataProvider 修复缓存污染、跨模块枚举比较、锁顺序等并发问题；
  4. DataProvider 新增插件注销时结构化数据级联清理，订阅关系同步移除；

▎ ⚠️ 测试版本声明
▎ 当前版本为预发布测试版（Pre-release），仅供开发者和早期体验者使用。核心功能已完成实现，但尚未经过全面生产环境验证。部分内部 API 签名、配置格式及插件接口可能在未来版本中发生破坏性变更（Breaking Changes），请勿将其用于生产环境的关键业务。

⚠️ 已知限制与注意事项

  1. API 不稳定：IPlugin、IPluginInfo、PluginServices 等核心接口以及 core/llm、core/mcp 模块的 API 签名可能在后续版本中调整，插件开发者需留意变更日志。
  2. 配置格式可能变更：config/llm_providers.json、config/mcp_config.json、config/plugin_order.json 等配置文件的结构尚未冻结。
  3. LLM Provider 适配待完善：部分 Provider 的流式解析、缓存适配和价格计算为初始实现，可能存在边界 case 处理不足。
  4. 文档持续迭代：开发者文档与代码实现正在同步更新，部分章节可能滞后于最新代码。

安装

克隆仓库
git clone https://github.com/KKPIP-Tech/InstructionX.git
cd InstructionX
安装依赖（推荐 uv）
uv pip install -r requirements.txt
启动
uv run main.py

首次运行自动创建 config/ 和 data/ 目录。

InstructionX Team
2026-06-27

Alpha 1.0.1

InstructionX Alpha 1.0.1 (Pre-release)

本次更新内容：

  1. 添加了 OpenAI 兼容 API 的支持；
  2. 提供了单独的 OpenAI Provider；
  3. 为 MiniMax 添加了 M2.7 及 M2.7 Highspeed 版本支持；

▎ ⚠️ 测试版本声明
▎ 当前版本为预发布测试版（Pre-release），仅供开发者和早期体验者使用。核心功能已完成实现，但尚未经过全面生产环境验证。部分内部 API 签名、配置格式及插件接口可能在未来版本中发生破坏性变更（Breaking Changes），请勿将其用于生产环境的关键业务。

主要功能

插件式桌面应用框架

  • 官方插件（plugin/）与第三方插件（custom_plugin/）双轨管理
  • 基于 entrance.py + service.py + information.py 的标准化插件结构
  • GitHub URL 一键安装与依赖自动解析
  • 插件 Widget 懒加载缓存，切换时状态完整保持

数据持久化与通信

  • DataProvider 单例：原子写入、PRIVATE/PUBLIC 双命名空间、Pub/Sub 发布订阅
  • 跨插件同步 API 调用（call_plugin_method）与数据共享

后台任务系统

  • 四种任务类型：Sync / Async / Scheduled / Long Running
  • 线程池执行，支持取消、持久化与工厂恢复

LLM 集成

  • 多厂商统一适配：MiniMax、SiliconFlow、GLM、Ollama
  • 对话管理、流式输出、工具调用自动循环、向量嵌入
  • 用量记录持久化与统计面板

MCP 协议支持（实验功能）

  • 内置 MCP Host Server（stdio / streamable-http）
  • 外部 MCP Client 连接，工具命名空间隔离
  • 插件 service_api 自动暴露为 MCP 工具

UI 与主题

  • 无边框主窗口 + 自定义标题栏，8 方向边缘缩放
  • SkillsPanel 官方/第三方插件切换，WorkArea 动态承载
  • StyleQSS 动态主题系统，支持 Light / Dark / Auto

⚠️ 已知限制与注意事项

  1. API 不稳定：IPlugin、IPluginInfo、PluginServices 等核心接口以及 core/llm、core/mcp 模块的 API 签名可能在后续版本中调整，插件开发者需留意变更日志。
  2. 配置格式可能变更：config/llm_providers.json、config/mcp_config.json、config/plugin_order.json 等配置文件的结构尚未冻结。
  3. LLM Provider 适配待完善：部分 Provider 的流式解析、缓存适配和价格计算为初始实现，可能存在边界 case 处理不足。
  4. 文档持续迭代：开发者文档与代码实现正在同步更新，部分章节可能滞后于最新代码。

安装

克隆仓库
git clone https://github.com/KKPIP-Tech/InstructionX.git
cd InstructionX
安装依赖（推荐 uv）
uv pip install -r requirements.txt
启动
uv run main.py

首次运行自动创建 config/ 和 data/ 目录。

InstructionX Team
2026-05-07

Alpha 1.0.0

InstructionX Alpha 1.0.0 (Pre-release)

▎ ⚠️ 测试版本声明
▎ 当前版本为预发布测试版（Pre-release），仅供开发者和早期体验者使用。核心功能已完成实现，但尚未经过全面生产环境验证。部分内部 API 签名、配置格式及插件接口可能在未来版本中发生破坏性变更（Breaking Changes），请勿将其用于生产环境的关键业务。

主要功能

插件式桌面应用框架

  • 官方插件（plugin/）与第三方插件（custom_plugin/）双轨管理
  • 基于 entrance.py + service.py + information.py 的标准化插件结构
  • GitHub URL 一键安装与依赖自动解析
  • 插件 Widget 懒加载缓存，切换时状态完整保持

数据持久化与通信

  • DataProvider 单例：原子写入、PRIVATE/PUBLIC 双命名空间、Pub/Sub 发布订阅
  • 跨插件同步 API 调用（call_plugin_method）与数据共享

后台任务系统

  • 四种任务类型：Sync / Async / Scheduled / Long Running
  • 线程池执行，支持取消、持久化与工厂恢复

LLM 集成

  • 多厂商统一适配：MiniMax、SiliconFlow、GLM、Ollama
  • 对话管理、流式输出、工具调用自动循环、向量嵌入
  • 用量记录持久化与统计面板

MCP 协议支持（实验功能）

  • 内置 MCP Host Server（stdio / streamable-http）
  • 外部 MCP Client 连接，工具命名空间隔离
  • 插件 service_api 自动暴露为 MCP 工具

UI 与主题

  • 无边框主窗口 + 自定义标题栏，8 方向边缘缩放
  • SkillsPanel 官方/第三方插件切换，WorkArea 动态承载
  • StyleQSS 动态主题系统，支持 Light / Dark / Auto

⚠️ 已知限制与注意事项

  1. API 不稳定：IPlugin、IPluginInfo、PluginServices 等核心接口以及 core/llm、core/mcp 模块的 API 签名可能在后续版本中调整，插件开发者需留意变更日志。
  2. 配置格式可能变更：config/llm_providers.json、config/mcp_config.json、config/plugin_order.json 等配置文件的结构尚未冻结。
  3. LLM Provider 适配待完善：部分 Provider 的流式解析、缓存适配和价格计算为初始实现，可能存在边界 case 处理不足。
  4. 文档持续迭代：开发者文档与代码实现正在同步更新，部分章节可能滞后于最新代码。

安装

克隆仓库
git clone https://github.com/KKPIP-Tech/InstructionX.git
cd InstructionX
安装依赖（推荐 uv）
uv pip install -r requirements.txt
启动
uv run main.py

首次运行自动创建 config/ 和 data/ 目录。

InstructionX Team
2026-05-02