lua-plugin-creator

Files (1)

• SKILL.md

SKILL.md (first lines)

# LUA 插件创造指南（Lua Plugin Creator）

本技能指导你（DSC 的 Agent）**自己创造 DSC LUA 插件**：当现有工具无法满足需求时，编写一个 DSC 专属的 LUA 脚本，由 `tool-lua-host` 加载后注册为新工具，**无需修改宿主主程序，无需请求开发人员介入**。

---

## 1. 架构理解：你写的脚本如何变成工具

```
你写文件：  scripts/<脚本名>/main.lua
      │   tool-lua-host（空壳插件）每秒轮询脚本目录，发现新脚本/变更自动加载或重载
      ▼
  脚本执行：  dsc.register_tool("my_tool", spec, handler)
      │   注册名自动加脚本名前缀 → 宿主可见工具名 = <脚本名>_my_tool
      ▼
宿主调用：  Agent 或任意工具经宿主流水线调用 <脚本名>_my_tool → 转发到 tool-lua-host
      │   → 在你的脚本 VM 上执行 handler(args)，返回结果文本
```

关键特性：
- **独立 VM**：每个脚本一个独立的 LUA 状态机，脚本之间隔离，崩溃互不影响。
- **沙箱**：VM 不提供 `os`/`io` 库——脚本**无法直接读写文件系统、执行进程、访问网络**。需要这类能力时用 `dsc.tool.call` 调用宿主已有工具（如 `shell`、`str_replace_editor`）。
- **热加载**：脚本目录每 2 秒轮询一次。新增/修改 `main.lua` 后无需重启，自动生效；删除脚本目录则工具自动卸载。
- **类型检查**：脚本加载前经静态类型检查器校验（语法错误会阻止加载，类型诊断会打印警告但不阻止运行）。**给代码写类型注解，让问题在加载前暴露**。

---

## 2. 何时创造 LUA 插件（决策准则）

| 情形 | 行动 |
|---|---|
| 现有工具组合可满足（如先 `str_replace_editor` 再 `shell`） | **优先组合，不创造** |
| 需要多步骤、有状态、可复用的流程 | **创造插件**（脚本内可自由编排 dsc API） |
| 需要跨工具共享状态 | 用 `dsc.store` |
| 需要在宿主工具执行前后干预（拦截/改写参数/结果） | 用 `dsc.hook` |
| 需要后台长任务 | 用 `dsc.job` |
| 需要调用宿主 LLM 做推理/生成 | 用 `dsc.llm.chat` |

创造插件的回报：**一次编写，全宿主可用**——任何会话、任何 Agent、任何其他插件都能调用你注册的工具。

---

## 3. dsc API 完整参考

所有能力以全局 `dsc` 表暴露。参数/返回值均为 LUA 原生类型（table / string / number / boolean）。

### 3.1 工具注册

```
dsc.register_tool(name: string, spec: table, handler: function) -> nil
```

- `name`：工具名（小写、下划线分词）。对外暴露为 `<脚本名>_<name>`——前缀是**脚本名本身**（`scripts/` 下的目录名），故模型从工具名即可看出它出自哪个脚本，脚本一多也不会失去归属。脚本内引用自身工具名时用 `dsc.script.name` 拼前缀（见 3.8），别把带前缀的名字写死。
- `spec`：`{ description = string, parameters = <JSON Schema> }`。`parameters` 用 JSON Schema 描述参数（`type=object`、`properties`、`required`）。
- `handler`：`function(args: table) -> string | table | nil`。返回字符串直接作为工具结果；返回 table 会序列化为 JSON；返回 nil 结果为空。
- 重复注册同名工具会报错。

```lua
dsc.register_tool("greet", {
    description = "生成问候语",
    parameters = {
        type = "object",
        properties = { who = { type = "string", description = "问候对象" } },
        required = { "who" }
    }
}, function(args)
    return "你好，" .. args.who .. "！"
end)
-- 脚本目录名为 demo 时，宿主侧工具名：demo_greet
```

### 3.2 LLM（宿主聚合，含多 provider 路由）

```
dsc.llm.chat({ system?: string, user: string, max_tokens?: number }) -> string
```

- 经宿主聚合 LLM 服务（primary → fallback 路由），与主 Agent 同源。
- **必须用流式路径**，thinking 模式下普通调用可能返回空文本；本函数已内部处理。
- `system` 可选；`max_tokens` 省略用服务端默认。

```lua
local summary: string = dsc.llm.chat({
    system = "你是一位简洁的摘要助手。",
    user = "请摘要这段文本：..." ,
    max_tokens = 200
})
```

### 3.3 调用其他工具（宿主转发）

```
dsc.tool.call(name: string, args?: table) -> string
dsc.tool.list() -> { {name, description}, ... }
```

- 经宿主完整工具流水线执行（含策略拦截、钩子、超时），**与 Agent 直接调用完全一致**。
- 适合编排：脚本作为"编排层"，把 shell / str_replace_editor / str_replace_editor 组合成复合工具。
- 参数用 table 传入（与目标工具的 JSON Schema 对应）。

```lua
local out: string = dsc.tool.call("shell", { command = "dir /b ." })
```

### 3.4 事件发布

```
dsc.notify.emit(name: string, data?: table) -> nil
```

- 发布事件到宿主事件总线：宿主内任何订阅者（TUI 唤醒、其他插件的 `on_event` 钩子）都能收到。
- `name` 建议用命名空间式：`<脚本名>/<事件>`（如 `myplugin/done`）。

```lua
dsc.notify.emit("myplugin/done", { task = "sync", ok = true })
```

### 3.5 共享存储（进程内 KV，脚本间共享）

From naamfung/dsc, Apache-2.0.

More from naamfung/dsc