Openbot

与 moltbot 中 pi-coding-agent 类似的 Agent Skill 逻辑：从路径加载技能（SKILL.md / .md），格式化为系统提示，并支持传入提示词运行（可选调用 LLM）。

环境

• Node.js >= 20
• 可选：OPENAI_API_KEY 用于实际调用 OpenAI 兼容 API

安装与构建

cd openbot
npm install
npm run build

作为 npm 包使用（库）

其他应用可通过 npm 安装并调用 openbot 的核心能力：加载技能、组装提示、运行 LLM（含工具轮）。

安装

npm install openbot

API 示例

import {
  loadSkillsFromPaths,
  run,
  getOpenbotAgentDir,
  ensureDefaultAgentDir,
} from "openbot";

// 1. 加载技能（目录或单个 .md）
const skills = loadSkillsFromPaths(["./skills"]);

// 2. 可选：确保默认 agent 目录存在（~/.openbot/agent）
const agentDir = getOpenbotAgentDir();
ensureDefaultAgentDir(agentDir);

// 3. 运行：组装 system/user，调用 LLM，执行工具
const result = await run({
  skills,
  userPrompt: "总结一下当前有哪些技能",
  // 可选：model, provider, apiKey, agentDir, maxToolTurns, dryRun 等
});

console.log(result.assistantContent);

导出 API 一览

| 导出 | 说明 | |------|------| | loadSkillsFromDir(options) | 从单目录加载技能（{ dir, source }） | | loadSkillsFromPaths(paths, source?) | 从多路径加载技能（目录或 .md 文件） | | formatSkillsForPrompt(skills) | 将技能列表格式化为系统提示片段 | | run(options) | 执行一次运行：组装 system/user，可选调 LLM + 工具轮；返回 RunResult | | getOpenbotAgentDir() | 获取默认 agent 配置目录（受 OPENBOT_AGENT_DIR 影响） | | ensureDefaultAgentDir(agentDir) | 确保默认目录存在并写入缺省 models.json | | Skill, RunOptions, RunResult, LoadSkillsFromDirOptions | 类型（TypeScript） |

环境变量与 CLI 一致（如 OPENAI_API_KEY、DEEPSEEK_API_KEY；OPENBOT_ALLOW_RUN_CODE 缺省 1，OPENBOT_MAX_TOOL_TURNS 缺省 30）；run() 的 RunOptions 可覆盖 model、provider、apiKey、agentDir、maxToolTurns、dryRun 等。

用法（CLI）

# 不传 -s 时使用安装目录下的 skills（包内 skills 目录）
openbot "总结一下当前有哪些技能"

# 指定 skill 路径（目录或单个 .md）+ 提示词
node dist/cli.js --skill-path ./skills "总结一下当前有哪些技能"

# 多路径、--prompt、dry-run（只打印组装内容，不调 LLM）
node dist/cli.js -s ./skills -s ./extra --prompt "用 weather 技能查北京天气" --dry-run

# 使用 bin（需先 npm link 或 npm install -g .）
openbot -s ./skills "有哪些技能可用？"

参数

| 选项 | 说明 | |------|------| | -s, --skill-path <path> | Skill 目录或单个 .md 文件，可多次指定；不传则从应用安装目录的 skills 加载 | | -p, --prompt <text> | 用户提示词（与位置参数二选一） | | --dry-run | 只输出 system/user 内容，不调用 LLM | | --model <id> | 模型 ID，默认 deepseek-chat | | --provider <name> | Provider（pi ModelRegistry），默认 deepseek；可选 dashscope、openai | | --agent-dir <path> | Agent 配置目录，默认 ~/.openbot/agent | | --api-key <key> | API Key（可覆盖环境变量） | | -h, --help | 显示帮助 |

缺省 Agent 目录（模仿 moltbot）

• 缺省路径：~/.openbot/agent（可通过 OPENBOT_AGENT_DIR 或 --agent-dir 覆盖）
• 首次使用：若该目录或其中的 models.json 不存在，会自动创建并写入缺省 models.json（与 pi-coding-agent 的 ModelRegistry 格式一致）
• 缺省 models.json 内容：
  • deepseek（默认）：OpenAI 兼容，baseUrl 为 https://api.deepseek.com，apiKey 支持 DEEPSEEK_API_KEY 或 OPENAI_API_KEY；内置模型 deepseek-chat、deepseek-reasoner
  • dashscope（阿里千问）：DashScope 兼容 OpenAI，baseUrl 为 https://dashscope.aliyuncs.com/compatible-mode/v1；apiKey 支持 OPENAI_API_KEY 或 DASHSCOPE_API_KEY；内置模型 qwen-max-latest、qwen-turbo-latest
  • openai：baseUrl 默认 https://api.openai.com/v1，apiKey 为 OPENAI_API_KEY
• 可直接编辑 ~/.openbot/agent/models.json 增删模型或改 baseUrl；环境变量 key 可写 "apiKey": "DEEPSEEK_API_KEY"、"OPENAI_API_KEY"、"DASHSCOPE_API_KEY" 等

环境变量

• DEEPSEEK_API_KEY：默认 provider 为 deepseek 时使用；不设时回退到 OPENAI_API_KEY
• OPENAI_API_KEY：通用 API Key；不设则 --dry-run 行为
• DASHSCOPE_API_KEY：可选，provider=dashscope 时使用；不设时回退到 OPENAI_API_KEY
• OPENAI_BASE_URL：可选，在 pi 未找到模型时使用的 endpoint
• OPENBOT_AGENT_DIR：可选，缺省 agent 目录，默认 ~/.openbot/agent
• OPENBOT_ALLOW_RUN_CODE：缺省 1（启用 run_python）；设为 0 关闭。有安全风险，仅限可信环境
• OPENBOT_TIMING=1 或 --timing：打印每轮 LLM / 工具耗时到 stderr

多轮与工具调用（pi-ai 行为说明）

• pi-ai / pi-coding-agent 支持多轮：每轮可返回 tool_calls，本 CLI 会执行工具并把结果追加到对话，再请求下一轮，最多 30 轮（可设 OPENBOT_MAX_TOOL_TURNS 或 --max-tool-turns）。
• 为何有时 skill 没被调用：大模型有时用纯文字回复（如「我将调用 read_skill…」）而不发起真正的 tool_calls，此时会直接返回该段文字并结束。为减少这种情况，系统提示会要求「需要工具时必须在当轮发起 tool 调用」；若检测到「说了要调用但没调用」，会自动追加一条用户消息再跑一轮。
• 为何生成的 Python 代码没有执行：默认有 read_skill（及可选的 run_agent_browser）等工具；run_python 缺省启用（OPENBOT_ALLOW_RUN_CODE 默认 1）。（1）会多出 run_python 工具，模型可调用 run_python(code) 执行；（2）后备逻辑：若模型只把代码写在回复里（未调用 run_python），我们会自动从回复中提取第一个 ```python ... ``` 块并执行，将执行结果追加到输出末尾，从而仍能生成 PDF 等文件。设为 OPENBOT_ALLOW_RUN_CODE=0 可关闭 run_python。
• agent-browser：随 openbotx 一起安装（npm 依赖 agent-browser）。run_agent_browser 会优先使用同装的可执行路径；若未安装则回退到 PATH 中的 agent-browser。安装 openbotx 后首次使用 agent-browser 技能时，可执行 npx agent-browser install 下载 Chromium（或使用包内同装的 agent-browser 的 postinstall）。

Skill 格式

与 Agent Skills 风格一致：

• 发现规则：目录下直接子文件 .md，或子目录下递归的 SKILL.md
• Frontmatter：YAML 块，需包含 name、description

示例 skills/weather/SKILL.md：

---
name: weather
description: 查询指定城市的天气（示例技能）
---

# Weather Skill

使用方式：告诉助手城市名即可查询天气。

项目结构

openbot/
├── package.json
├── tsconfig.json
├── src/
│   ├── cli.ts      # 命令行入口
│   ├── index.ts    # 库入口
│   ├── run.ts      # 组装 system/user、调用 LLM
│   └── skills.ts   # 加载技能、formatSkillsForPrompt
├── skills/         # 示例技能目录（可选）
│   └── demo/
│       └── SKILL.md
└── README.md

与 pi-coding-agent 的对应关系

| 能力 | pi-coding-agent | Openbot | |------|-----------------|-----------| | Skill 类型 | Skill (name, description, filePath, baseDir, source) | 同构 | | 发现 | loadSkillsFromDir（根 .md + 子目录 SKILL.md） | loadSkillsFromDir / loadSkillsFromPaths | | 格式化 | formatSkillsForPrompt(skills) → XML 风格 | 同逻辑 | | 运行 | 由 pi 的 Agent + read 工具等执行 | 本 CLI：组装 system + user，可选调用 OpenAI 兼容 API |

本仓库不依赖 pi-mono，仅复用相同的技能发现与提示组装思路，便于本地试验和扩展。