自述清单规范

本文档定义了 KnotLink 节点系统的 自述清单文件 结构。节点类型由文件名决定：

• 插入式节点（由平台管理生命周期）使用 plugin_manifest.json
• 独立式节点（自行管理进程）使用 standalone_manifest.json

插入式节点必须提供清单文件。独立式节点清单有两个用途：

1. 放在应用安装目录下，供 KnotHub 运行时读取（含 auto_start、exe_path）
2. 提交到 KNodeIndex，供节点索引展示（含 download_url）

顶层结构

插入式（plugin_manifest.json）

{
  "app_id": "com.example.myplugin",
  "plugin_name": "消息提醒",
  "author": "HXH",
  "version": "v1.0.0",
  "description": "在屏幕顶端弹出消息通知窗口",
  "download_url": "https://github.com/your-org/your-repo/releases/latest",
  "auto_start": "false",
  "exe_path": "MsgNotification.exe"
}

独立式（standalone_manifest.json）

{
  "app_id": "com.example.myapp",
  "app_name": "我的桌面应用",
  "author": "开发者名称",
  "version": "v1.0.0",
  "description": "一个独立运行的桌面应用",
  "download_url": "https://github.com/your-org/your-repo/releases/latest"
}

独立式节点自行管理进程，不需要 auto_start 和 exe_path 字段。

字段	类型	必填	适用文件	描述
app_id	string	是	两者	节点的全局唯一标识符（倒置域名格式，如 com.example.myapp）
plugin_name	string	是	仅 plugin	插入式节点的显示名称，与 FuncList 的 appName 一致
app_name	string	是	仅 standalone	独立式节点的显示名称，与 FuncList 的 appName 一致
version	string	是	两者	节点版本号，建议遵循 语义化版本 规范
author	string	是	两者	节点作者或组织名称
description	string	是	两者	节点功能描述，建议简洁清晰
download_url	string	否	两者	下载地址，指向 GitHub Releases 等发布页面
auto_start	string	否	仅 plugin	是否在 KnotLinkService 启动时自动加载。"true" 或 "false"，默认 "false"
exe_path	string	是	仅 plugin	可执行文件的路径（相对于清单文件所在目录）

---

字段详细说明

app_id（应用标识符）

• 类型：string
• 格式：倒置域名法（如 com.example.myapp），或以 0x 开头后跟 8 位十六进制数字（旧格式，兼容）。
• 唯一性：整个 KnotLink 生态中必须唯一。
• 示例："com.example.myapp"

---

plugin_name（插入式节点名称）

• 类型：string
• 适用文件：仅 plugin_manifest.json
• 描述：插入式节点的显示名称，用于节点索引和网站展示。应与 FuncList 中的 appName 保持一致。
• 限制：应避免特殊字符，建议使用字母、数字、空格和下划线。
• 示例："消息提醒"、"Everything 搜索节点"

---

app_name（独立式节点名称）

• 类型：string
• 适用文件：仅 standalone_manifest.json
• 描述：独立式节点的显示名称，用于节点索引和网站展示。应与 FuncList 中的 appName 保持一致。
• 限制：应避免特殊字符，建议使用字母、数字、空格和下划线。
• 示例："ClassIsland"、"Ink Canvas"

---

version（版本号）

• 类型：string
• 描述：节点版本号，用于升级管理和兼容性检查。
• 格式：建议遵循 语义化版本 2.0.0 规范，如 "1.0.0"，前缀 v 可选（"v1.0.0" 也是合法版本号）。
• 示例："1.2.3"、"v2.0.0"

---

author（作者）

• 类型：string
• 描述：节点作者或组织的名称，可包含空格和特殊字符。
• 示例："KnotLink Team"

---

auto_start（自动启动）

• 类型：string
• 适用文件：仅 plugin_manifest.json
• 描述：控制是否在 KnotLinkService 启动时自动启动该节点。
• 取值："true" 或 "false"（字符串，大小写敏感，建议使用小写）
• 默认值：如果未提供，视为 "false"。
• 注意：独立式节点自行管理生命周期，此字段不适用。

---

download_url（下载地址）

• 类型：string
• 必填：否（但建议填写）
• 描述：节点的下载地址，通常指向 GitHub Releases 等发布页面。
• 示例："https://github.com/your-org/your-repo/releases/latest"

---

description（描述）

• 类型：string
• 描述：节点的简短功能说明，有助于用户了解节点用途。
• 最大长度：建议不超过 200 字符。
• 示例："在屏幕顶端弹出消息通知窗口"

---

exe_path（可执行文件路径）

• 类型：string
• 适用文件：仅 plugin_manifest.json
• 描述：节点可执行文件的相对路径（相对于清单文件所在目录）。
• 支持：可以是 .exe（Windows）、可执行脚本（Linux/macOS）或任何可运行文件。
• 示例：
  • Windows："bin/plugin.exe"
  • Linux："bin/plugin"
• 注意：路径分隔符建议使用 / 以保证跨平台兼容性。独立式节点自行管理进程，不需要此字段。

---

---

完整示例

插入式节点（plugin_manifest.json）：

{
  "app_id": "com.example.monitor",
  "plugin_name": "系统监控",
  "author": "KnotLink Contributors",
  "version": "v2.1.0",
  "description": "KnotLink system monitor plugin",
  "download_url": "https://github.com/example/monitor/releases/latest",
  "auto_start": "true",
  "exe_path": "bin/monitor.exe"
}

独立式节点（standalone_manifest.json）：

{
  "app_id": "com.example.myapp",
  "app_name": "我的桌面应用",
  "author": "开发者名称",
  "version": "v1.0.0",
  "description": "一个独立运行的桌面应用",
  "download_url": "https://github.com/example/myapp/releases/latest"
}

---

独立式节点的注册表注册

独立式节点由 KnotHub 通过 Windows 注册表 发现。应用安装时需写入：

HKCU\Software\KnotLink\StandaloneNodes

每条记录为一个注册表值：

• 值名称 = app_id（与 standalone_manifest.json 中的一致）
• 值数据 = 应用安装目录的完整路径（该目录下包含 standalone_manifest.json）

示例（PowerShell）：

Set-ItemProperty -Path "HKCU:\Software\KnotLink\StandaloneNodes" `
  -Name "com.example.myapp" `
  -Value "C:\Program Files\MyApp"

KnotHub 启动时扫描此注册表键，读取每个应用的 standalone_manifest.json 和 FuncList.json，将其注册为可发现的独立式节点。

插入式节点不需要写注册表——KnotHub 直接扫描 Plugins/ 目录下的 plugin_manifest.json。

---

注意事项

1. JSON 格式严格性 清单文件必须是合法的 JSON，不得包含注释（除非使用支持注释的解析器，但建议保持标准 JSON）。
2. 字段大小写敏感 所有字段名均为 小写 + 下划线 风格（如 app_id、plugin_name），解析器应区分大小写。
3. 节点类型由文件名决定 plugin_manifest.json 表示插入式节点，standalone_manifest.json 表示独立式节点。文件名本身就是类型声明，无需 node_type 字段。
4. 扩展性 未来可能增加 dependencies、permissions 等字段，解析器应忽略未知字段以确保向前兼容。
5. 路径安全 exe_path 不应包含 .. 等危险路径，防止目录遍历攻击。建议仅允许相对路径且限定在节点目录内。
6. 版本比较 建议使用语义化版本进行升级判断，推荐使用 semver 库进行版本比较。
7. 校验建议 加载节点前，KnotLink 应对清单进行校验：
   • 检查 app_id 是否唯一
   • 检查 plugin_name 与 FuncList 的 appName 是否一致
   • 检查 exe_path 是否存在且可执行（仅 plugin）
   • 检查必填字段是否缺失

---

版本历史

版本	日期	变更说明
v2.0	2026-07-22	用文件名区分节点类型（plugin_manifest.json / standalone_manifest.json），移除 node_type 字段；保留 plugin_name（不改为 name）；auto_start 保持字符串类型；新增 download_url 字段
v1.1	2026-07-07	新增 node_type 字段，plugin_name 改为 name，auto_start 改为 boolean（已被 v2.0 推翻）
v1.0	2026-06-21	初始版本

---

如有疑问，请联系开发团队。