@luban-code/luban-code 1.66.1 → 1.100.0

package/registry/README.md

@@ -0,0 +1,160 @@
+# registry/ —— Luban 插件 / 技能可信索引（L0 + L1）
+
+```
+registry/
+  registry.json        索引本体（entries[]）
+  entry.schema.json    条目字段规范（L0 发现性字段 + L1 权限/签名/审核）
+  keys/<keyId>.pub     验签公钥（JSON: {keyId, algo, publicKey(base64 DER SPKI)}）
+```
+
+## 用法
+
+```bash
+# 插件 / 技能源码仓（monorepo）：https://github.com/eppen/luban-plugins
+#   插件结构 plugins/<name>/，技能结构 skills/<name>/，tag 都是 <name>-v<version>
+
+# 算 sourceSha256（目录的确定性哈希，任何人 clone 后都能复算出同一个值）
+node scripts/registry-tool.mjs hash ../luban-plugins/plugins/demo
+node scripts/registry-tool.mjs hash ../luban-plugins/skills/changelog-draft
+
+# 生成签名密钥（私钥写到仓库外，勿提交；别放 /tmp，重启会被清掉）
+node scripts/registry-tool.mjs keygen dev-1 --out '~/.luban-keys'
+
+# 修改条目后重新签名（改 permissions/tools/install/sourceSha256 都必须重签）
+node scripts/registry-tool.mjs sign demo --key '~/.luban-keys/dev-1.priv.json'
+
+# 校验：字段规范 + 命名空间冲突 + 签名 + 与已装包一致性
+node scripts/registry-tool.mjs verify            # 离线：警告不阻断（断网 / 内网也能跑）
+node scripts/registry-tool.mjs verify --strict   # 除错误外，一个签名都没有也算失败
+node scripts/registry-tool.mjs verify --remote   # 按 install 来源拉包，比对包内清单与 sourceSha256
+
+# 客户端：按索引装（验签 → 审核状态 → 按 tag 拉包 → 校对 sourceSha256 → 落盘）
+luban plugin add demo --dry-run                  # 只校验不落盘
+luban plugin add demo                            # 装进 ~/.luban/plugins/demo
+luban plugin remove demo                         # 移进回收站，可还原
+
+luban skill list                                 # 只看 type=skill 的条目
+luban skill add changelog-draft --dry-run        # 技能同样先校验
+luban skill add changelog-draft                  # 装进 ~/.luban/skills/changelog-draft
+luban skill remove changelog-draft               # 移进 ~/.luban/skills-trash/，可还原
+```
+
+> `luban plugin …` 与 `luban skill …` 是同一份索引的两个视角（等价于 `--type plugin` / `--type skill`）。
+> 两个前缀都显式带上 `--type`，所以 `luban plugin add <技能名>` 会明确报「是技能，不是插件」——
+> 不会出现「以为装插件、其实装进了技能目录」。
+
+## 条目与源码仓的对应
+
+插件源码不在本仓，在 [eppen/luban-plugins](https://github.com/eppen/luban-plugins)：
+
+| 字段 | 值 |
+|---|---|
+| `repo` | `https://github.com/eppen/luban-plugins`（monorepo 根） |
+| `install` | `{ type: "git", url: "git@github.com:eppen/luban-plugins.git", subdir: "plugins/<name>", target: "global" }` |
+| tag | `<name>-v<version>`，例如 `demo-v0.1.0`、`changelog-draft-v0.1.0` |
+| `sourceSha256` | 见下方算法；插件对 `plugins/<name>` 算、技能对 `skills/<name>` 算 |
+
+技能条目把这些字段换掉即可（其余字段一致，验签逻辑完全相同）：
+
+| 字段 | 技能的值 |
+|---|---|
+| `type` | `"skill"` |
+| `install.subdir` | `skills/<name>` |
+| `tools` | `[]`（技能不给模型新增工具） |
+| `permissions` | `{}`（纯 Markdown，没有执行能力） |
+| 包内清单 | `SKILL.md` 的 frontmatter：`name` 必须等于条目名、`version` 可选但写了就要一致 |
+
+```
+sourceSha256 算法（目录哈希，与机器 / 时间无关）
+  1. 遍历目录，跳过 node_modules / .git / .DS_Store，符号链接跳过并告警；
+  2. 文件按相对路径（用 / 分隔）的 UTF-8 字节序升序排序；
+  3. 对每个文件算 sha256 hex，向总哈希喂入 `<相对路径>\0<文件 sha256 hex>\n`；
+  4. 总哈希的 hex 即 sourceSha256。
+```
+
+复算方式（证明可复现）：
+
+```bash
+git clone --depth 1 https://github.com/eppen/luban-plugins.git /tmp/lp
+node scripts/registry-tool.mjs hash /tmp/lp/plugins/demo
+# 应等于 registry.json 里 demo 条目的 sourceSha256
+```
+
+## 校验会挡住什么
+
+| 检查 | 级别 | 说明 |
+|---|---|---|
+| 条目前提字段 / semver / ctxApi 区间 | error | 索引本身不可用 |
+| `name` 重复 | error | 工具前缀 `pl__<name>__` 会冲突 |
+| 工具名不合规（大写、连字符） | error | 生成出的工具名无法调用 |
+| `permissions` 出现未知权限键 | error | 防止悄悄扩权绕过展示 |
+| 签名与内容不符 | error | 改了权限却没重签 = 篡改 |
+| 索引 tools ≠ 已安装 plugin.json | error | 防「先上架后换包」 |
+| `type=skill` 却声明了 `tools` | error | 技能不新增工具，声明了说明字段用错 |
+| `type=skill` 却声明了 `permissions` | warn | 忽略即可；技能没有执行能力 |
+| 索引 name / version ≠ 已安装 `SKILL.md` 的 frontmatter | error | 技能侧的「先上架后换包」检查 |
+| 未签名 / `review.status=pending` | warn | L0 可用，L1 未达标 |
+| 工具全 readOnly 但 `shell/net/fsWrite` 为真 | warn | **需人工核对实现**，签名无法证明行为 |
+| 缺 `sourceSha256` | warn | 安装不可复现 |
+
+## 贡献者 vs 维护者：谁签名
+
+签名是**维护者合并 PR 后补的工序**，不是贡献者的责任。私钥只在维护者手里，从不进仓库。
+
+| 角色 | 做什么 | 需要私钥 |
+|---|---|---|
+| 贡献者 | fork luban-plugins → 加插件/技能 → 在本仓 `registry.json` 加条目（**不写 `signature`**）→ 提 PR | ❌ |
+| 维护者 | 审核代码 → 合并 → `sign <name>` 补签名 → 推送 | ✅ |
+
+贡献者侧（无私钥）：
+
+```bash
+# 算好 sourceSha256 填进条目，条目里不要有 signature 字段
+node scripts/registry-tool.mjs hash /path/to/their-plugin
+# 提 PR。未签名条目在 verify 里只是 WARN，不阻断 CI
+```
+
+维护者侧（合并后补签）：
+
+```bash
+git pull origin main
+node scripts/registry-tool.mjs sign their-plugin --key '~/.luban-keys/dev-2.priv.json'
+git add registry/registry.json
+git commit -m "chore(registry): sign their-plugin"
+git push origin main
+```
+
+未签名条目 `verify` 报 `WARN [xxx] 未签名（L0 可接受，L1 要求签名后才算可信）`，
+退出码只看 `errors.length`，警告不影响 CI 通过。所以「贡献者没私钥」是正常且预期的。
+
+多人维护时可按发布者分 `keyId`（`keygen maintainer-alice`），每个签名条目的
+`signature.keyId` 指向对应维护者的公钥；吊销某维护者只需从 `signingKeys` 移除其 keyId，
+不用动条目本身。
+
+## 约定
+
+- 签名对象：去掉 `signature` 后按键名递归排序的紧凑 JSON（见 `scripts/registry-tool.mjs` 的 `canonical()`）。
+- 私钥永不入库；`keys/` 下只放公钥。轮换时新增 `keyId`，旧条目保留旧签名，不追溯重签。
+- `review.status = revoked` 的下架条目保留在索引里（供已安装用户告警），不删除。
+- 改任何内容（`permissions` / `tools` / `install` / `sourceSha256`）都要重签，否则 `verify` 报签名校验失败。
+- `name` 建立索引即冻结：它决定工具前缀 `pl__<name>__`，换名等于换一个新插件。
+
+## 注意事项
+
+- `keygen --out` 与 `sign --key` 都会展开 `~`；路径含空格时用引号。
+- `verify` 默认**离线**：`sourceSha256` 只校验格式，「索引 tools ≠ plugin.json」读的是**本机**
+  `~/.luban/plugins/<name>/plugin.json`（作者本机有装就比，没装就跳过；技能同理读
+  `~/.luban/skills/<name>/SKILL.md`）。这是为了「断网 / 内网 / CI 也能跑」。
+- `verify --remote` 走网络：按 `install` 字段拉一次包（与 `luban plugin add` / `luban skill add`
+  同一条链路，共用 `registry-client.js` 的 `fetchSource`），比对包内清单（`plugin.json` 或
+  `SKILL.md` 的 frontmatter）、目录哈希与索引是否一致，不依赖作者本机有没有装。
+  **发版前、审核时、CI 里都应该跑这条。**
+  拉包失败（tag 不存在 / 仓库里没这个 `subdir` / 没有 git）会直接报 ERROR 而不是跳过。
+- 技能装进 `~/.luban/skills/<name>`（项目级 `luban skill add --target project` → `<repo>/.luban/skills/<name>`），
+  **不需要信任表**：纯 Markdown 不给模型新增执行能力，装完下一轮就被 `skills.js` 扫到。
+  已装清单写在 `<skills 根>/.installed.json` 而**不写进技能目录** —— 写进去就成了包内容，
+  `sourceSha256` 复算必然不符（与插件回收站元数据写同级 `<条目>.json` 同一个理由）。
+- 当前三个条目（`demo` / `changelog-draft` / `cc-safety-net`）都用开发密钥 `dev-2` 签名
+  （私钥在 `~/.luban-keys/dev-2.priv.json`，不入库）。
+  早期的 `dev-1` 私钥已丢失，其公钥 `keys/dev-1.pub` 仅作历史保留，不再列入 `signingKeys`。
+  面向公众发布前应重新 `keygen` 一个新 `keyId` 并重签。

package/registry/entry.schema.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://luban.local/schemas/registry-entry-v1.json",
+  "title": "Luban 插件 / 技能索引条目（L0 + L1）",
+  "description": "L0 = 可发现（名称/版本/来源/校验和）；L1 = 可信任（声明权限 + 签名 + 审核状态）。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["name", "displayName", "description", "type", "version", "author", "license", "install", "ctxApi"],
+  "properties": {
+    "type": {
+      "enum": ["plugin", "skill"],
+      "description": "plugin = 会执行代码的本地插件；skill = 纯文本说明书，无需权限声明"
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]{1,39}$",
+      "description": "唯一标识，也是工具名前缀（插件工具名 = pl__<name>__<tool>），建立索引即固定，不允许复用"
+    },
+    "displayName": { "type": "string", "minLength": 1, "maxLength": 60 },
+    "description": { "type": "string", "minLength": 8, "maxLength": 200 },
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" },
+    "author": { "type": "string", "minLength": 1 },
+    "license": { "type": "string", "minLength": 1 },
+    "repo": { "type": "string", "format": "uri" },
+    "homepage": { "type": "string", "format": "uri" },
+    "tags": {
+      "type": "array",
+      "maxItems": 8,
+      "items": { "type": "string", "maxLength": 20 }
+    },
+    "install": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type"],
+      "properties": {
+        "type": { "enum": ["git", "tarball", "local"] },
+        "url": { "type": "string" },
+        "subdir": { "type": "string" },
+        "target": {
+          "enum": ["global", "project"],
+          "description": "global = ~/.luban/plugins/<name>；project = <repo>/.luban/plugins/<name>"
+        }
+      }
+    },
+    "sourceSha256": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$",
+      "description": "安装包 / 目录归档的 sha256。git 方式下为 tag 对应归档的哈希；缺失则视为不可复现安装"
+    },
+    "ctxApi": {
+      "type": "string",
+      "description": "兼容的 ctx API 版本区间，例如 >=0.1 <1.0；宿主超出区间应拒绝加载并提示"
+    },
+    "tools": {
+      "type": "array",
+      "description": "工具清单，必须与包内 plugin.json 逐字一致（校验脚本比对）",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "description", "readOnly", "parameters"],
+        "properties": {
+          "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" },
+          "description": { "type": "string", "minLength": 4 },
+          "readOnly": { "type": "boolean" },
+          "parameters": { "type": "object" }
+        }
+      }
+    },
+    "permissions": {
+      "type": "object",
+      "description": "L1 核心：作者自报的实际能力。readOnly 只是工具语义，不能推翻这里；审核以本块为准",
+      "additionalProperties": false,
+      "properties": {
+        "fsRead": { "type": "boolean" },
+        "fsWrite": { "type": "boolean" },
+        "shell": { "type": "boolean" },
+        "net": { "type": "boolean" },
+        "env": { "type": "boolean" }
+      }
+    },
+    "review": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status"],
+      "properties": {
+        "status": { "enum": ["pending", "reviewed", "flagged", "revoked"] },
+        "reviewedBy": { "type": "string" },
+        "reviewedAt": { "type": "string", "format": "date-time" },
+        "notes": { "type": "string", "maxLength": 500 }
+      }
+    },
+    "signature": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["algo", "keyId", "sig"],
+      "properties": {
+        "algo": { "enum": ["ed25519"] },
+        "keyId": { "type": "string" },
+        "sig": { "type": "string", "description": "base64，签名对象 = 去掉 signature 字段后按键名排序的紧凑 JSON" }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "type": { "const": "plugin" } }, "required": ["type"] },
+      "then": { "required": ["permissions", "tools", "review"] }
+    },
+    {
+      "if": { "properties": { "type": { "const": "skill" } }, "required": ["type"] },
+      "then": {
+        "properties": { "permissions": { "const": {} }, "tools": { "maxItems": 0 } }
+      }
+    }
+  ]
+}

package/registry/keys/dev-1.pub

@@ -0,0 +1,5 @@
+{
+  "keyId": "dev-1",
+  "algo": "ed25519",
+  "publicKey": "MCowBQYDK2VwAyEAPJU7fBUY0MX4PLF4tTMkbmIDOoXzszD88EhpZZqXpeo="
+}

package/registry/keys/dev-2.pub

@@ -0,0 +1,5 @@
+{
+  "keyId": "dev-2",
+  "algo": "ed25519",
+  "publicKey": "MCowBQYDK2VwAyEAR7DVIZXc2iTA6VWff1zX7MZzcitb+zxcW7Kx6zgVuCM="
+}

package/registry/keys/registry-ci.pub

@@ -0,0 +1,5 @@
+{
+  "keyId": "registry-ci",
+  "algo": "ed25519",
+  "publicKey": "MCowBQYDK2VwAyEAQyDIHcIn6RghXIGReR7E78sK80IFX5gnPDGfgKx7OAg="
+}

package/registry/registry.json

@@ -0,0 +1,178 @@
+{
+  "registryVersion": 1,
+  "updatedAt": "2026-11-13T13:53:13Z",
+  "schema": "./entry.schema.json",
+  "signingKeys": [
+    {
+      "keyId": "dev-2",
+      "algo": "ed25519",
+      "publicKey": "keys/dev-2.pub"
+    },
+    {
+      "keyId": "registry-ci",
+      "algo": "ed25519",
+      "publicKey": "keys/registry-ci.pub"
+    }
+  ],
+  "entries": [
+    {
+      "name": "demo",
+      "displayName": "Demo 小工具",
+      "description": "Luban 本地插件示例：本机时间与工作区磁盘剩余空间",
+      "type": "plugin",
+      "version": "0.1.0",
+      "author": "liuhualiang",
+      "license": "MIT",
+      "repo": "https://github.com/eppen/luban-plugins",
+      "tags": [
+        "demo",
+        "system"
+      ],
+      "install": {
+        "type": "git",
+        "url": "git@github.com:eppen/luban-plugins.git",
+        "subdir": "plugins/demo",
+        "target": "global"
+      },
+      "sourceSha256": "f806fcc5d33aa49dda38b9dc19936d635adef498f0960987a08bd9b1d32c61cb",
+      "ctxApi": ">=0.1 <1.0",
+      "tools": [
+        {
+          "name": "now",
+          "description": "返回本机当前时间（ISO 8601 与时区）",
+          "readOnly": true,
+          "parameters": {
+            "type": "object",
+            "properties": {}
+          }
+        },
+        {
+          "name": "disk_free",
+          "description": "返回工作区所在磁盘的剩余空间",
+          "readOnly": true,
+          "parameters": {
+            "type": "object",
+            "properties": {}
+          }
+        }
+      ],
+      "permissions": {
+        "fsRead": false,
+        "fsWrite": false,
+        "shell": true,
+        "net": false,
+        "env": false
+      },
+      "review": {
+        "status": "reviewed",
+        "reviewedBy": "liuhualiang",
+        "reviewedAt": "2026-11-12T14:30:00Z",
+        "notes": "两个工具声明 readOnly，但 disk_free 通过 execFile 调用 df -k（只读取磁盘统计，未写盘/联网），与声明一致；shell=true 已如实声明。"
+      },
+      "signature": {
+        "algo": "ed25519",
+        "keyId": "registry-ci",
+        "sig": "rXVMOvPMaJVt5nLUHz+So/q3kYOMyKVNacH9AXUiyA69mwRzV3++kAO0Wvcw65EVBqfNuML/8f/xGlJtK2NfAg=="
+      }
+    },
+    {
+      "name": "changelog-draft",
+      "displayName": "CHANGELOG 起草",
+      "description": "按提交历史起草 CHANGELOG 条目：先读现有写法再取 git log，输出分类草稿，默认不改文件",
+      "type": "skill",
+      "version": "0.1.0",
+      "author": "liuhualiang",
+      "license": "MIT",
+      "repo": "https://github.com/eppen/luban-plugins",
+      "tags": [
+        "git",
+        "docs"
+      ],
+      "install": {
+        "type": "git",
+        "url": "git@github.com:eppen/luban-plugins.git",
+        "subdir": "skills/changelog-draft",
+        "target": "global"
+      },
+      "sourceSha256": "807f066342c0c90b9accd011d6f009b5650c1e093eab9765585c1710eaee7a6b",
+      "ctxApi": ">=0.1 <1.0",
+      "tools": [],
+      "permissions": {},
+      "review": {
+        "status": "reviewed",
+        "reviewedBy": "liuhualiang",
+        "reviewedAt": "2026-11-12T14:56:13Z",
+        "notes": "技能无执行能力；正文只要求 read_file / git log / git show / git describe 这类只读命令，并明确禁止 reset/checkout/stash、禁止 commit/push、禁止在用户未确认时改文件。description 与正文一致。"
+      },
+      "signature": {
+        "algo": "ed25519",
+        "keyId": "registry-ci",
+        "sig": "kOGvBF7aNY2qmRyV8FS7UYqIHermnhVecumvVhmPgNgACxLbTLW4pubtccT0hGFlPHAJiK8Q9gHK8k+YaCt7DQ=="
+      }
+    },
+    {
+      "name": "cc-safety-net",
+      "displayName": "命令安全守卫",
+      "description": "执行前命令守卫：解析命令意图，拦截破坏性 Git/文件命令与敏感文件（SSH key / .env / ~/.aws）访问。移植自 kenryu42/cc-safety-net 的 checkCommand 库 API。",
+      "type": "plugin",
+      "version": "0.1.0",
+      "author": "liuhualiang",
+      "license": "MIT",
+      "repo": "https://github.com/eppen/luban-plugins",
+      "tags": [
+        "safety",
+        "git",
+        "shell"
+      ],
+      "install": {
+        "type": "git",
+        "url": "git@github.com:eppen/luban-plugins.git",
+        "subdir": "plugins/cc-safety-net",
+        "target": "global"
+      },
+      "sourceSha256": "7fde042d9442b826d6b1d78ed1757dbb0be5ecb89867f7cd8ced9413c51c94c0",
+      "ctxApi": ">=0.1 <1.0",
+      "tools": [
+        {
+          "name": "check_command",
+          "description": "检查一条 shell 命令是否危险（破坏性 Git 操作、rm -rf、curl|bash、敏感文件访问等）。返回 allow 或 deny（带原因与规则 ID）。在真正执行前调用它做一次前置判断。",
+          "readOnly": true,
+          "parameters": {
+            "type": "object",
+            "properties": {
+              "command": {
+                "type": "string",
+                "description": "要检查的完整 shell 命令"
+              },
+              "cwd": {
+                "type": "string",
+                "description": "执行命令的工作目录（绝对路径），缺省用当前工作区根"
+              }
+            },
+            "required": [
+              "command"
+            ]
+          }
+        }
+      ],
+      "permissions": {
+        "fsRead": false,
+        "fsWrite": false,
+        "shell": true,
+        "net": false,
+        "env": false
+      },
+      "review": {
+        "status": "reviewed",
+        "reviewedBy": "liuhualiang",
+        "reviewedAt": "2026-11-13T00:59:49Z",
+        "notes": "工具声明 readOnly，但 permissions.shell=true 已如实声明（实现通过 execFile 调用 git，只读检查不写盘/联网）。依赖外部 npm 包 cc-safety-net，安装时需 npm install cc-safety-net --prefix <插件目录>。"
+      },
+      "signature": {
+        "algo": "ed25519",
+        "keyId": "registry-ci",
+        "sig": "vvpXf4ApzGh1JpT7B7GuLe4n75s/71GAznRNijP2j3u4LZhkhBZBa36ZjqnhA2mvJrRYyBWSlthujANuelMABA=="
+      }
+    }
+  ]
+}