wb-agent 0.1.0__tar.gz

wb_agent-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: wb-agent
+Version: 0.1.0
+Summary: Workbench Agent SDK — base classes for custom agents and skills
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: openai>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: pytest-mock>=3.14; extra == "dev"

wb_agent-0.1.0/README.md

@@ -0,0 +1,534 @@
+# wb-agent SDK 用户指南
+
+把你的项目变成 CodeAgent。
+
+---
+
+## 一、SDK 提供了什么
+
+安装 `wb-agent` 后，你可以从 `wb_agent` 包 import 以下内容：
+
+### 1. Agent 基类
+
+| import | 用途 |
+|--------|------|
+| `CodeAgent` | 你的 Agent 继承这个类，实现 `run()` 方法 |
+| `AgentContext` | 平台注入的运行时上下文（替代 CodeAgent 的另一种方式） |
+| `BaseSkill`, `param` | 用 Python 类的方式定义 Skill（可选） |
+| `AgentRunner` | `CodeAgent` 别名，向后兼容 |
+
+### 2. 全局函数（核心 API）
+
+| import | 用途 |
+|--------|------|
+| `call_llm(prompt)` | 调用平台模型。在 `run()`、skill 脚本、测试脚本里都能用 |
+| `async_call_llm(prompt)` | `call_llm` 的异步版本 |
+| `call_llm_stream(prompt)` | 流式调用 LLM |
+| `use_skills(message)` | 自动编排：LLM 自主选择 skill 循环调用，直到完成 |
+| `use_skill(name, **params)` | 直接调用指定 skill |
+| `bind_agent(agent)` | 绑定当前 agent 到上下文变量（由 `CodeAgent.__init__()` 自动调用） |
+| `log(msg)` | 发送日志事件 |
+| `progress(cur, total)` | 发送进度事件 |
+| `send_stream(content)` | 发送流式文本 |
+| `send_text(text)` | 发送最终结果（文本） |
+| `send_result(dict)` | 发送最终结果（结构化） |
+| `emit_usage(prompt, completion, total)` | 上报 token 用量 |
+| `set_debug(True)` | 开启彩色终端日志 |
+
+### 3. 本地开发工具
+
+| 命令 | 用途 |
+|------|------|
+| `wb-agent-dev /path/to/project` | 启动本地 Web 测试服务，自动读取 `manifest.yaml` 渲染输入界面 |
+| `python -m wb_agent.dev /path/to/project` | 同上 |
+
+`wb-agent dev` 会在浏览器中打开一个测试界面，配置模型参数和输入后点"运行"，实时看到 Agent 输出。不需要部署到平台就能调试。
+
+### 4. 平台模型工具（测试 / 独立环境用）
+
+| import / method | 用途 |
+|--------|------|
+| `agent.set_model_config(config)` | CodeAgent 方法，注入模型配置到当前进程和子进程环境 |
+| `call_via_env(prompt)` | 仅靠 `AGENT_*` 环境变量调用模型 |
+| `make_client()` | 从环境变量创建 OpenAI 客户端 |
+| `make_bound_call_llm(config)` | 绑定配置的 call_llm 工厂 |
+| `wb_agent.platform_model.env_model_config()` | 读取当前 `AGENT_*` 环境变量 |
+| `wb_agent.platform_model.inject_model_env(config)` | 将配置写入 `AGENT_*` 环境变量 |
+
+### 5. Skill 执行器
+
+| import | 用途 |
+|--------|------|
+| `SkillExecutor` | 执行器抽象基类 |
+| `SkillResult` | 执行结果（stdout, stderr, exit_code） |
+| `ExecutionContext` | 执行上下文（env, timeout, skill_dir） |
+| `CliSkillExecutor` | 以子进程方式执行 CLI 脚本 |
+| `PythonSkillExecutor` | 用 `exec()` 执行内联 Python skill |
+| `PlatformToolExecutor` | 包装平台 tool._invoke() |
+| `get_executor(type_name)` | 按类型名获取执行器实例 |
+
+`register_skills()` 和 `use_skill()` 自动按 skill 类型选择对应执行器。一般不需要直接使用。
+
+### 6. 部署 & 其他工具
+
+| import | 用途 |
+|--------|------|
+| `register_agent(...)` | 将 Agent 打包为 tar.gz 并上传到 Workbench 平台 |
+| `execute_shell_commands_in_prompt(...)` | 在 skill prompt 中嵌入 shell 命令执行 |
+| `ShellPermissionError` | shell 命令被拒绝时的异常类型 |
+
+---
+
+## 二、改造指南：5 步把你的项目变成 CodeAgent
+
+### Step 1：`pyproject.toml` — 加依赖
+
+如果你的项目还没有 `pyproject.toml`，新增一个：
+
+```toml
+[project]
+name = "my-agent"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = ["wb-agent"]
+
+# （本地开发时）如果 SDK 在本地路径
+[tool.uv.sources]
+wb-agent = { path = "../../backend/sdk", editable = true }
+```
+
+如果已有 `pyproject.toml`，只需要在 `dependencies` 里加一行 `"wb-agent"`。
+
+**对照参考：** `self_agents/numina-lean-agent-main/pyproject.toml`
+
+---
+
+### Step 2：`run.py` — 创建 Agent 入口
+
+这是核心文件，需要新增。最小骨架：
+
+```python
+from wb_agent import CodeAgent
+
+class MyAgent(CodeAgent):
+    async def run(self):
+        # 1. 获取输入
+        prompt = self.input_message
+
+        # 2. 调 LLM 处理
+        result = await self.call_llm(prompt)
+
+        # 3. 返回结果
+        self.send_text(result)
+```
+
+完整版本（带 skill 注册和系统提示词）：
+
+```python
+from pathlib import Path
+from wb_agent import CodeAgent, log
+
+class MyAgent(CodeAgent):
+    def __init__(self):
+        super().__init__()
+        root = Path(__file__).resolve().parent
+        self.register_skills(str(root / "skills"))
+        self._load_system_prompt()
+
+    def _load_system_prompt(self):
+        prompt_file = Path(__file__).resolve().parent / "prompts" / "main.md"
+        if prompt_file.exists():
+            self._system_prompt = prompt_file.read_text(encoding="utf-8")
+
+    async def run(self):
+        prompt = self.input_message
+        if not prompt:
+            return "请输入内容"
+        log(f"处理输入: {prompt[:50]}...")
+
+        if self._skill_map:
+            # 让 LLM 自主选择 skill
+            result = await self.use_skills(prompt, max_iterations=10)
+        else:
+            result = await self.call_llm(prompt)
+
+        self.send_text(result)
+        return result
+```
+
+**关键说明：**
+
+| 方法 | 作用 |
+|------|------|
+| `self.input_message` | 从平台获取用户输入（字符串） |
+| `self.input_file` | 从平台获取输入文件路径 |
+| `await self.call_llm(prompt)` | 调用平台模型，返回文本 |
+| `await self.use_skills(prompt)` | 让 LLM 自动选 skill 循环调用 |
+| `self.send_text(text)` | 输出结果到平台 |
+| `self.log(msg)` | 写日志 |
+
+如果你不想写 `async` 函数，有同步版：
+
+```python
+def run(self):                      # 同步版 run()
+    result = self.call_llm_sync(...)
+    result = self.use_skills_sync(...)
+    result = self.use_skill_sync(...)
+    self.send_text(result)
+```
+
+**对照参考：** `self_agents/numina-lean-agent-main/run.py`
+
+---
+
+### Step 3：`skills/` — 将你的工具函数包装成 Skill（可选）
+
+Skill 是 LLM 可以调用的工具。有两种格式：
+
+#### 格式 A：CLI Skill（推荐，最常用）
+
+需要两个文件：
+
+**① `skills/cli/<name>.py` — 可执行脚本**
+
+SDK 用 AST 解析脚本中的 `argparse` 参数，自动生成 LLM 的 function calling schema。
+
+```python
+#!/usr/bin/env python3
+"""一个简短描述，LLM 会根据它决定何时调用。"""
+import argparse
+
+parser = argparse.ArgumentParser()
+parser.add_argument("input", help="输入参数")
+parser.add_argument("--verbose", action="store_true", help="详细输出")
+args = parser.parse_args()
+
+# 调用你的现有业务逻辑
+# from your_module import your_func
+# result = your_func(args.input)
+
+print(result)  # 标准输出作为 skill 返回值
+```
+
+**② `skills/reference-<name>.md` — 描述文件**
+
+```markdown
+# <name>
+
+一句话描述这个 skill 的用途和何时调用。
+```
+
+**注册原理：** `register_skills("skills/")` 扫描所有 `reference-*.md`，在 `cli/` 下找同名脚本，AST 解析 `argparse.add_argument()` 定义参数。
+
+**对照参考：** `skills/cli/bash.py` + `skills/reference-bash.md`
+
+#### 格式 B：Python Skill（SKILL.md 新格式）
+
+所有定义在一个文件里：
+
+```markdown
+---
+name: <skill-name>
+description: LLM 看到的 skill 描述
+parameters:
+  - name: input
+    type: string
+    description: 输入说明
+    required: true
+  - name: verbose
+    type: boolean
+    description: 是否详细输出
+    required: false
+---
+
+```python
+def <skill-name>(input: str, verbose: bool = False) -> dict:
+    """函数的 docstring 不会影响 LLM，描述在 YAML 里。"""
+    # 调用你的现有逻辑
+    # from your_module import your_func
+    # return your_func(input)
+    return {"result": ...}
+```
+```
+
+**注册原理：** SDK 解析 YAML frontmatter 获取参数 schema，提取 ` ```python ` 代码块作为 `exec()` 执行的源码。
+
+---
+
+### Step 4：测试
+
+#### 方式一：全局函数测试（最轻量，任意环境）
+
+```python
+# test_quick.py
+import os
+os.environ["AGENT_BASE_URL"] = "https://api.xxx.com/v1"
+os.environ["AGENT_API_KEY"] = "sk-xxx"
+os.environ["AGENT_MODEL"] = "your-model"
+
+from wb_agent import call_llm, use_skill, set_debug
+
+set_debug(True)
+
+# 测试 LLM 调用
+result = call_llm("你好")
+print(result)
+
+# 测试单个 skill
+result = use_skill("my-skill", input="test")
+print(result)
+```
+
+#### 方式二：Agent 实例测试
+
+```python
+# test_agent.py
+import os
+from run import MyAgent
+
+agent = MyAgent()
+agent.set_model_config({
+    "base_url": "https://api.xxx.com/v1",
+    "api_key": "sk-xxx",
+    "model_name": "your-model",
+})
+
+os.environ["PLATFORM_INPUT_MESSAGE"] = "你的测试输入"
+
+agent.set_debug(True)
+result = agent.run()
+print(result)
+```
+
+`set_model_config()` 会将配置写入 `AGENT_*` 环境变量，确保子进程 skill 也能调用同一模型。
+
+#### 方式三：模拟平台注入测试（最贴近生产）
+
+```python
+# test_with_fake_llm.py
+import os, asyncio
+from openai import AsyncOpenAI
+
+class FakeLLM:
+    def __init__(self):
+        self.client = AsyncOpenAI(
+            api_key="sk-xxx",
+            base_url="https://api.xxx.com/v1",
+        )
+    async def invoke_llm(self, messages, tools=None, **kwargs):
+        r = await self.client.chat.completions.create(
+            model="your-model", messages=messages, tools=tools or None,
+        )
+        msg = r.choices[0].message
+        class _R:
+            content = msg.content or ""
+        return _R()
+
+async def test():
+    from run import MyAgent
+    agent = MyAgent()
+    agent._llm = FakeLLM()
+    os.environ["PLATFORM_INPUT_MESSAGE"] = "测试输入"
+    await agent.run()
+
+asyncio.run(test())
+```
+
+**对照参考：** `self_agents/numina-lean-agent-main/test_local.py`
+
+---
+
+### Step 5：`manifest.yaml` — 部署到 Workbench 平台（可选）
+
+```yaml
+name: 你的 Agent 名称
+description: "简短描述"
+entrypoint: "run.py"
+avatar: "🤖"
+max_iteration: 20
+input:
+  type: text
+output:
+  type: text
+```
+
+然后使用 SDK 的打包命令上传：
+
+```python
+from wb_agent import register_agent
+register_agent(
+    api_url="http://your-platform.com",
+    name="My Agent",
+    project_dir=".",
+)
+```
+
+**对照参考：** `self_agents/numina-lean-agent-main/manifest.yaml`
+
+---
+
+## 三、使用 wb-agent dev 工具
+
+SDK 提供了一个本地开发服务，让你在浏览器中测试 Agent，不需要部署到 Workbench 平台。
+
+### 启动
+
+```bash
+# 在 Agent 项目目录中
+wb-agent-dev .
+
+# 或指定目录和端口
+wb-agent-dev /path/to/my-agent/ --port 8080
+```
+
+### 工作原理
+
+```
+wb-agent-dev ./my-agent/
+         │
+         ├── 读取 manifest.yaml → 确定输入类型 (text / file)
+         ├── 启动 HTTP 服务 (http://localhost:8080)
+         │
+         ▼
+    ┌─────────────────────────────────────┐
+    │  浏览器打开 http://localhost:8080    │
+    │                                     │
+    │  ┌─ 模型配置 ─────────────────┐     │
+    │  │ Base URL / API Key / Model │     │
+    │  └────────────────────────────┘     │
+    │  ┌─ 输入 ─────────────────────┐     │
+    │  │ text: textarea             │     │
+    │  │ file: 文件选择器            │     │
+    │  └────────────────────────────┘     │
+    │  [▶ 运行]                           │
+    │                                     │
+    │  ┌─ 输出 (实时 SSE) ──────────┐     │
+    │  │ ℹ 正在启动...              │     │
+    │  │ ⚙ Tool: lean_check(...)   │     │
+    │  │ ✔ Result: ...             │     │
+    │  └────────────────────────────┘     │
+    └─────────────────────────────────────┘
+         │
+         ▼
+   后端: 生成 wrapper → 设置 AGENT_* env
+        → 子进程运行 run.py
+        → stdout JSON 事件 → SSE → 前端
+```
+
+### 它做了什么
+
+| 步骤 | 说明 |
+|------|------|
+| 1 | 读取 `manifest.yaml`，根据 `input.type` 渲染 textarea 或文件选择器 |
+| 2 | 用户填入 Base URL / API Key / Model，点运行 |
+| 3 | 设置 `AGENT_*` 环境变量，生成一个临时 wrapper 脚本 |
+| 4 | 子进程执行 wrapper → 导入 `run.py` → 找到 `CodeAgent` 子类 → 实例化 → 调用 `run()` |
+| 5 | Agent 输出的 JSON 事件通过 SSE 实时推送到浏览器 |
+| 6 | 运行结束后自动清理临时文件 |
+
+### 注意事项
+
+- **不要在生产环境使用** — 仅用于本地开发调试
+- `manifest.yaml` 中的 `entrypoint` 必须指向包含 `CodeAgent` 子类的文件
+- 模型配置也可以在终端中通过 `AGENT_*` 环境变量预设，这样浏览器打开时自动填入
+
+---
+
+## 四、函数速查表
+
+### CodeAgent 方法
+
+| 方法 | 说明 |
+|------|------|
+| `__init__(debug=False)` | 初始化，自动绑定全局引用 |
+| `run()` | **必须重写**。Agent 主逻辑 |
+| `call_llm(prompt)` | 异步调用平台 LLM |
+| `call_llm_stream(prompt)` | 异步流式调用 LLM |
+| `call_llm_sync(prompt)` | 同步版 call_llm |
+| `use_skills(message, max_iterations=10)` | 异步 auto-invoke 循环 |
+| `use_skills_sync(message, max_iterations=10)` | 同步版 use_skills |
+| `use_skill(name, **params)` | 异步调用指定 skill |
+| `use_skill_sync(name, **params)` | 同步版 use_skill |
+| `set_model_config(config)` | 注入模型配置到进程和子进程环境 |
+| `register_skills(path)` | 批量注册 skill 目录 |
+| `register_skill(path)` | 注册单个 skill 目录 |
+| `watch_skills(path)` | 热重载 skill |
+| `list_skills()` | 列出已注册 skill |
+| `set_debug(enabled=True)` | 开启/关闭调试日志 |
+| `send_text(text)` | 输出纯文本结果 |
+| `send_result(dict)` | 输出结构化结果 |
+| `send_stream(content)` | 输出流式文本片段 |
+| `send_thought(thought, ...)` | 输出思考过程 |
+| `log(message, level)` | 输出日志 |
+| `progress(current, total)` | 输出进度 |
+| `emit_usage(p, c, t)` | 上报 token 用量 |
+| `write_file(filename, content)` | 写入输出文件 |
+| `write_output(filename, content)` | `write_file` 的别名 |
+| `reset_conversation()` | 清空对话历史 |
+| `bind_agent(agent)` | 绑定 agent 到上下文变量（全局函数能用） |
+
+### CodeAgent 属性
+
+| 属性 | 说明 |
+|------|------|
+| `input_message` | 用户输入文本 |
+| `input_file` | 用户输入文件路径 |
+| `input_files` | 多文件输入路径列表 |
+| `output_dir` | 输出目录路径 |
+| `conversation` | 当前对话历史列表 |
+
+### 全局函数
+
+| 函数 | 说明 |
+|------|------|
+| `call_llm(prompt)` | 调用平台模型。自动检测上下文（CodeAgent / 独立环境） |
+| `async_call_llm(prompt)` | 异步版 call_llm |
+| `call_llm_stream(prompt)` | 流式版 call_llm |
+| `use_skills(message)` | auto-invoke 编排 |
+| `use_skill(name, **params)` | 调用指定 skill |
+| `bind_agent(agent)` | 绑定当前 agent 到上下文变量 |
+| `log(message)` | 发送日志 |
+| `progress(current, total)` | 发送进度 |
+| `send_stream(content)` | 发送流式文本 |
+| `send_text(text)` | 发送文本结果 |
+| `send_result(dict)` | 发送结构化结果 |
+| `emit_usage(p, c, t)` | 上报用量 |
+| `set_debug(True)` | 开启调试输出 |
+
+### 环境变量
+
+| 变量 | 说明 | 设置方 |
+|------|------|--------|
+| `AGENT_BASE_URL` | LLM API 地址 | `set_model_config()` 或平台注入 |
+| `AGENT_API_KEY` | LLM API Key | 同上 |
+| `AGENT_MODEL` | 模型名称 | 同上 |
+| `PLATFORM_INPUT_MESSAGE` | 用户输入文本 | Workbench 平台 |
+| `PLATFORM_INPUT_FILE` | 用户输入文件路径 | Workbench 平台 |
+| `PLATFORM_INPUT_FILES` | 多文件路径（分号分隔） | Workbench 平台 |
+| `PLATFORM_OUTPUT_DIR` | 输出目录 | Workbench 平台 |
+
+---
+
+### 推荐的项目结构（完整示例）
+
+```
+my-agent/
+├── pyproject.toml          # 依赖声明
+├── run.py                  # CodeAgent 入口
+├── manifest.yaml           # 平台部署配置（可选）
+├── prompts/
+│   └── main.md             # 系统提示词
+├── skills/
+│   ├── reference-my_tool.md    # CLI skill 描述
+│   ├── reference-another.md
+│   ├── cli/
+│   │   ├── my_tool.py          # CLI skill 脚本
+│   │   └── another.py
+│   ├── python-skill/           # Python skill（SKILL.md 格式）
+│   │   └── SKILL.md
+│   └── .../
+├── tests/
+│   └── test_agent.py
+├── your_module.py          # 你现有的业务代码
+└── ...
+```

wb_agent-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=64.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wb-agent"
+version = "0.1.0"
+description = "Workbench Agent SDK — base classes for custom agents and skills"
+requires-python = ">=3.12"
+dependencies = [
+    "httpx>=0.27.0",
+    "pyyaml>=6.0",
+    "openai>=1.0.0",
+]
+
+[project.scripts]
+wb-agent-dev = "wb_agent.dev:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-mock>=3.14",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

wb_agent-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+