Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

tool-creator

/tool-creator

Tworzy moduły narzędzi w Pythonie dla AnimaWorks, z integracjami Web API, poświadczeniami i uprawnieniami.

Repozytorium
animaworks ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
10.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
2
Przestarzałość

Brak sygnałów. Repozytorium zmienione 10.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Tworzy moduły narzędzi w Pythonie dla AnimaWorks, z integracjami Web API, poświadczeniami i uprawnieniami.

Oryginalny opis (EN)

为AnimaWorks创建Python外部工具模块的元技能。core/integrations处理集成、get_credential、permissions。 Use when: core/integrations需要新增模块、实现Web API包装器、开发从animaworks-tool调用的自定义工具时。

Jak działa

  1. 概述
  2. 执行路径(LLM如何调用)
  3. 步骤
  4. 必需接口
  5. 调用与schema名
  6. schema规范化
  7. permissions(toolcreation·外部工具)
  8. EXECUTIONPROFILE
  9. 在仓库中添加核心工具时
  10. 验证检查清单
Sekcje z nagłówków SKILL.md, w oryginale · 305 linii, 957 słów
Podgląd SKILL.md
---
name: tool-creator
description: >-
  为AnimaWorks创建Python外部工具模块的元技能。core/integrations处理集成、get_credential、permissions。
  Use when: core/integrations需要新增模块、实现Web API包装器、开发从animaworks-tool调用的自定义工具时。
---


# tool-creator

## 概述

AnimaWorks的工具分为3类:

| 类型 | 放置位置 | 发现方法 |
|------|--------|----------|
| **核心工具** | `core/integrations/*.py`(排除`_`前缀的文件) | `discover_core_tools()` → `TOOL_MODULES`(包 import) |
| **共享工具** | `{data_dir}/common_tools/*.py` | `discover_common_tools()` |
| **个人工具** | `{anima_dir}/tools/*.py` | `discover_personal_tools()` |

`{data_dir}` 通常为 `~/.animaworks/`。

- **分发**:`ExternalToolDispatcher` 废除了 `_DISPATCH_TABLE`,统一为各模块的 `dispatch(name, args)`(或与schema名同名的函数)(`core/tooling/dispatch.py`)。
- **合并**:`AgentCore` 启动时的 `_discover_personal_tools()` 和 `refresh_tools` 均按 **共享→个人** 的顺序合并,**个人覆盖同名项**(`{**common, **personal}`)。合并结果保存在 `ExternalToolDispatcher` 的 `_personal_tools` 中(名称是historical但**也包含共享工具**)。
- **与核心的冲突**:与核心 `TOOL_MODULES` 同名的文件在发现共享·个人工具时会被**跳过**(仅记录警告日志)。
- **工具文件写入**:在 `write_memory_file` 中写入 `tools/*.py` 时,必须满足 `permissions`(**优先 `permissions.json`**)的 **tool_creation.personal**(`core/tooling/handler_memory.py`)。

## 执行路径(LLM如何调用)

| 模式 | 典型路径 |
|--------|-----------|
| **A(LiteLLM 等)** | 集成工具 **`use_tool(tool_name, action, args)`** → 模块的 `dispatch`(`core/tooling/handler.py`)。详细设计为在 **`read_memory_file`** 中读取各工具的技能(`core/tooling/schemas/skill.py` 的 `USE_TOOL`)。 |
| **S(Agent SDK)** | 通过 Claude Code 内置 **Bash** 执行 `animaworks-tool <ツール> …`,或经由 MCP(MCP 上仅加载精选子集。参见下文「向仓库添加核心工具时」)。 |
| **Anthropic 回退等** | `build_tool_list` 中可能存在 `include_use_tool=False` 的配置 → 外部以 **Bash + animaworks-tool** 或技能为前提。 |

启动时上述合并后的映射会传给 `ToolHandler`,因此**在进程启动前放置的**共享·个人工具从一开始就能通过 `use_tool` / `ExternalToolDispatcher` 引用。**仅在会话中新增的** `.py`,如果不通过 `refresh_tools` 重新扫描,`use_tool` 就无法识别工具名(因为映射未更新)。

## 步骤

### Step 1: 工具设计

1. 确定工具名(模块名)(snake_case,例:`my_api_tool`)。它将成为 `animaworks-tool my_api_tool …` 的第1个参数。
2. 确定**动作**(子命令)。schema名原则上为 **`{tool_name}_{action}`**(例:`myapi_query`)。在 `use_tool` 中为 `tool_name="myapi"`, `action="query"`。
3. 用 JSON Schema 定义参数(`input_schema` 或 `parameters`)。

### Step 2: 创建模块文件

#### 单动作示例

```python
from __future__ import annotations

import logging
from typing import Any

logger = logging.getLogger(__name__)


def get_tool_schemas() -> list[dict]:
    """ツールスキーマを返す。個人・共有ツールでは必須推奨(スキーマ読み込み・ログ用)。"""
    return [
        {
            "name": "my_tool_action",
            "description": "このツールが何をするかの説明",
            "input_schema": {
                "type": "object",
                "properties": {
                    "param1": {
                        "type": "string",
                        "description": "パラメータの説明",
                    },
                    "param2": {
                        "type": "integer",
                        "description": "オプションパラメータ",
                        "default": 10,
                    },
                },
                "required": ["param1"],
            },
        }
    ]


def dispatch(name: str, args: dict[str, Any]) -> Any:
    """スキーマ名に応じた処理を実行する(推奨)。"""
    args.pop("anima_dir", None)  # フレームワークから注入。必要なら Path(anima_dir) で利用
    if name == "my_tool_action":
        return _do_action(
            param1=args["param1"],
            param2=args.get("param2", 10),
        )
    raise ValueError(f"Unknown tool: {name}")


def _do_action(param1: str, param2: int = 10) -> dict[str, Any]:
    return {"result": f"Processed {param1} with {param2}"}
```

若要从 `animaworks-tool` 调用,之后**必须实现 `cli_main`**(参见下文「`cli_main`」节)。

#### 多动作 + 认证(API 集成)

`get_credential(credential_name, tool_name, key_name="api_key", env_var=...)` 的解析顺序为 **`config.json` 的 `credentials.{credential_name}`**(`api_key` 或 `keys[key_name]`)→ **`vault.json` 的 `shared` 节**(键名为通过参数 `env_var` 传入的字符串)→ **`shared/credentials.json`(legacy,键为 `env_var`)** → **环境变量 `env_var`**(`core/credentials.py`)。

```python
from __future__ import annotations

import logging
from typing import Any

logger = logging.getLogger(__name__)


def get_tool_schemas() -> list[dict]:
    return [
        {
            "name": "myapi_query",
            "description": "APIにクエリを送信して結果を取得する",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "検索クエリ"},
                    "limit": {"type": "integer", "description": "最大件数", "default": 10},
                },
                "required": ["query"],
            },
        },
        {
            "name": "myapi_post",
            "description": "APIにデータを送信する",
            "input_schema": {
                "type": "object",
                "properties": {
                    "data": {"type": "string", "description": "送信データ"},
                },
                "required": ["data"],
            },
        },
    ]


class MyAPIClient:
    def __init__(self) -> None:
        from core.credentials import get_credential

        self._api_key = get_credential(
            "myapi",
            "myapi_tool",
            env_var="MYAPI_KEY",
        )

    def query(self, query: str, limit: int = 10) -> list[dict]:
        import httpx

        resp = httpx.get(
            "https://api.example.com/search",
            params={"q": query, "limit": limit},
            headers={"Authorization": f"Bearer {self._api_key}"},
            timeout=30.0,
        )
        resp.raise_for_status()
        return resp.json()["results"]

    def post(self, data: str) -> dict:
        import httpx

        resp = httpx.post(
            "https://api.example.com/data",
            json={"data": data},
            headers={"Authorization": f"Bearer {self._api_key}"},
            timeout=30.0,
        )
        resp.raise_for_status()
        return resp.json()


def dispatch(name: str, args: dict[str, Any]) -> Any:
    args.pop("anima_dir", None)
    client = MyAPIClient()
    if name == "myapi_query":
        return client.query(query=args["query"], limit=args.get("limit", 10))
    if name == "myapi_post":
        return client.post(data=args["data"])
    raise ValueError(f"Unknown tool: {name}")
```

**Per-Anima 认证**(Chatwork 等):存在从 `args.get("anima_dir")` 获取 Anima 名,并通过 `resolve_env_style_credential(...)` 解析 `CHATWORK_API_TOKEN__{anima_name}` 这类 **Anima 专用键**的模式(`core/integrations/_chatwork_identity.py` 的 `resolve_identity` 等。未注册时不回退而是报错)。自定义工具也可使用同样的键命名方式。

#### `cli_main`(用于 animaworks-tool)

`animaworks-tool <tool_name> …` 无论核心·共享·个人,**若模块中没有 `cli_main` 则无法通过 CLI 执行**(`cli/tool_dispatch.py` 的 `cli_dispatch`)。常见做法是在 `argparse` 中解析子命令,内部调用 `dispatch(f"{tool}_{action}", args_dict)`。若想从 schema 生成用法,也可参考 `core/integrations/_base.py` 的 `auto_cli_guide`。

### Step 3: 保存文件

个人工具:

```
write_memory_file(path="tools/my_tool.py", content=<コード>)
```

需允许 `tool_creation.personal`。

### Step 4: 启用工具(热重载)

仅在进程启动**后**新增或修改了 `tools/*.py` 或 `common_tools/*.py` 时:

```
refresh_tools()
```

同一会话内 `ExternalToolDispatcher` 的基于文件的映射会被重新扫描,`use_tool` 可解析新的模块名(启动前已存在的文件通常不需要)。

### Step 5: 共享(可选)

```
share_tool(tool_name="my_tool")
```

会被复制到 `~/.animaworks/common_tools/`。需要 `tool_creation.shared`。其他 Anima 各自需要 `refresh_tools`(或重启时的自动发现)。

## 必需接口

| 函数 / 常量 | 必需 | 说明 |
|-------------|------|------|
| `get_tool_schemas()` | 个人·共享中**强烈推荐** | 用于schema读取·指南生成。核心中也有空列表的模块(例:`web_search` 为 `[]`)。**重要**:`ExternalToolDispatcher.dispatch`(在 `tool_use` 中直接传入schema名的路径)对于核心,**仅匹配 `get_tool_schemas()` 的 `name` 列表中包含的schema**。空模块在该路径下不会命中核心侧。另一方面,**`use_tool`** 会从 `TOOL_MODULES` 直接 import 模块并调用 `dispatch`,因此**即使schema列表为空,只要有 `dispatch` 就能执行**。自定义工具需兼顾两条路径,通常定义schema更安全。 |
| `dispatch(name, args)` | **推荐** | `ExternalToolDispatcher._call_module` 优先使用。 |
| 与schema名同名的函数 | 替代 | 当没有 `dispatch` 时使用 `getattr(mod, name)(**args)`。 |
| `cli_main(argv)` | **使用 CLI 时必需** | `animaworks-tool` 入口。 |
| `EXECUTION_PROFILE` | 任意 | `expected_seconds`, `background_eligible`,在核心工具中可通过 **`gated: True`** 将发送类等设为必须的允许列表(`core/tooling/permissions.py`)。 |

## 调用与schema名

- **`use_tool`**:通过 `schema_name = f"{tool_name}_{action}"` 传给模块的 `dispatch`(或同名函数)。允许判定为 **核心**:`tool_registry`(`get_permitted_tools` 的结果中包含 `tool_name`),**基于文件(共享·个人)**:合并后的 `_personal_tools` 中存在 `tool_name`(`core/tooling/handler.py` 的 `_handle_use_tool`)。
- **`animaworks-tool`**:若第1个token为 `submit` 则后台提交(见下文)。**核心**从 `TOOL_MODULES` import 并 `cli_main`,**共享·个人**从文件加载并 `cli_main`。未知的第1个参数有时会回退到主 CLI(`animaworks`)(`cli/tool_dispatch.py`)。
- **带门控的子命令(仅核心)**:若 `EXECUTION_PROFILE` 的对应动作有 `"gated": True`,则当 `permissions` 的允许集合中不包含 **`{tool_name}_{action}`**(例:`gmail_send`)时,CLI / 分发两者都会被阻止。**基于文件的个人·共享工具**没有 `TOOL_MODULES`,因此不在此门控机制范围内。

## schema规范化

`core/tooling/schemas/loader.py` 的 `_normalise_schema` 接收 `input_schema` / `parameters`,在内部表示中统一为 `parameters`。

## permissions(tool_creation·外部工具)

- **读取**:`load_permissions(anima_dir)`(`core/config/schemas.py`)。**优先 `permissions.json`**。仅在没有时解析 `permissions.md` 并生成·迁移 JSON(`migrate_permissions_md_to_json`)。
- **工具创建**(JSON 示例):

```json
{
  "version": 1,
  "tool_creation": {
    "personal": true,
    "shared": false
  }
}
```

Markdown 的「工具创建」节(`個人ツール` / `共有ツール` 行)在迁移时也会变为相同结构。

- **外部工具(核心)**:`external_tools` 在 `get_permitted_tools` 中收集 **核心 `TOOL_MODULES` 的模块名** 以及用于解除门控的 **`{tool}_{action}`** 字符串(例:`gmail_send`)。在 `use_tool` 中,核心工具使用进入该集合的名称在 `tool_registry` 侧使用,**个人·共享工具**若在启动时合并或 `refresh_tools` 后的 **`_personal_tools` 中有名称**,则即使不在核心集合内也能执行(与核心同名的文件在发现时会被跳过,因此不会冲突)。

## EXECUTION_PROFILE

- **`background_eligible: True`**:`animaworks-tool submit <tool> <subcommand> …` 将 `task_type="command"` 的输入注册到 TaskStore,`PendingTaskExecutor` 获取尝试并执行(`cli/tool_dispatch.py` 的 `_handle_submit`)。执行结果也会保存到 `state/background_tasks/{task_id}.json`。profile 引用仅对**可 import 的核心模块**执行(文件工具容易成为 submit 时的警告对象之外)。
- **`gated: True`**:对于核心工具的对应动作,需要在 permissions 中显式允许 `tool_action`。

```python
EXECUTION_PROFILE: dict[str, dict[str, object]] = {
    "pipeline": {"expected_seconds": 1800, "background_eligible": True},
    "send": {"expected_seconds": 15, "background_eligible": False, "gated": True},
}
```

## 在仓库中添加核心工具时

1. 添加 `core/integrations/{name}.py`(以 `_` 开头的内容不在扫描范围内)。
2. `TOOL_MODULES` 会通过 `discover_core_tools()` 自动注册。无需维护 `core/integrations/__init__.py` 手动列表。
3. MCP 的精选允许列表位于 `core/tooling/surface.py` 的 `MCP_TOOL_NAMES`。`resolve_tool_surface` 会根据 MCP 使用模式(S / C / D / G / X),按触发条件和角色进行筛选。示例:`search_memory`、`read_memory_file`、`write_memory_file`、`archive_memory_file`、`send_message`、`call_human`、`delegate_task`、`submit_tasks`、`update_task`、`create_skill`。Board 的读取和发布通过 Bash(`animaworks-tool board read/post`)进行。**Slack / Gmail / `web_search` 等外部服务类核心工具不会出现在 MCP 中**——通常通过 **`use_tool` / Bash(`animaworks-tool`)/ 技能** 路径使用。
4. 将测试添加到 `tests/`。如果会自动生成架构或参考文档,也请检查 `scripts/generate_reference.py` 中的相关内容。
5. 对于破坏性操作,请考虑更新 `gated: True` 和 permissions 一侧的说明。

## 验证检查清单

- [ ] 文件名:snake_case、`.py`、开头无 `_`(以便纳入扫描对象)
- [ ] 在开头添加 `from __future__ import annotations`(项目规范)
- [ ] `get_tool_schemas()` 返回正确的schema名(个人·共享)
- [ ] 通过 `dispatch` 或schema名函数处理所有schema
- [ ] 若不使用 `anima_dir`,则通过 `args.pop("anima_dir", None)` 避免副作用
- [ ] 实现 `cli_main` 并通过 `animaworks-tool` 确认运行
- [ ] 外部 HTTP 添加 `timeout=`
- [ ] 认证使用 `get_credential`(或与核心同型的 per-anima 解析)
- [ ] 日志推荐使用 `logging.getLogger(__name__)`

## 安全

1. 不要将机密信息嵌入代码。使用 `get_credential` / vault / config。
2. 不要触碰其他 Anima 的目录。
3. 核心中「写入·发送」类需将 `gated` 与 permissions 配套设计。

## 参考实现

- 薄入口 + `_client` / `_cli` 拆分:`core/integrations/chatwork.py`, `slack.py`, `discord.py`
- 认证・API:`core/integrations/gmail.py`, `github.py`, `notion.py`, `google_calendar.py`, `google_tasks.py`
- 长时间・管道:`core/integrations/image_gen.py`(门面、`image/` 子包 + `EXECUTION_PROFILE`)
- 搜索・本地 LLM:`core/integrations/web_search.py`(`get_tool_schemas` 为空 → `ExternalToolDispatcher.dispatch` 的核心路径中不匹配。`use_tool` 可在 `dispatch` 中实现)、`x_search.py`, `local_llm.py`
- 调度器・CLI 入口:`core/tooling/dispatch.py`, `cli/tool_dispatch.py`(`cli_dispatch` / `_handle_submit`)

## 注意事项

- 工具是可执行的 Python。与技能(Markdown)是两回事。
- 仅在**启动后**添加的工具需要 **`refresh_tools`**(启动前已存在的文件已在启动时扫描)。
- 与核心同名的个人・共享文件不会被采用。

Wersje

RepozytoriumWynikLicencja
Ta strona · xuiltul/animaworks100Apache-2.0
xuiltul/animaworks100Apache-2.0
xuiltul/animaworks100Apache-2.0
xuiltul/animaworks100Apache-2.0
aws-samples/aws-ai-ml-workshop-kr100MIT

Migawka bazy z 13.11.2026 · wersja paczki 758f61d2c5cb (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100skill-creator
    Pomaga stworzyć nowy skill dla agenta AI albo poprawić istniejący, z wiedzą, procesem pracy i integracjami narzędzi.
  • 100skill-creator
    Prowadzi przez tworzenie i aktualizację skilli dla agentów AI, zgodnych z Claude Code i OpenCode, z wiedzą i integracjami narzędzi.
  • 100api-reference-creator
    Prawdopodobnie tworzy dokumentację referencyjną API i uruchamia się automatycznie na frazy związane z kreatorem referencji w kategorii dokumentacji technicznej.
  • 100orchardcore-module-creator
    Tworzy nowe moduły Orchard Core ze strukturą, manifestem, częściami treści, panelami admina i endpointami minimal API.
  • 100animaworks-guide
    Podaje pełną referencję CLI animaworks do obsługi serwera, zarządzania Anima, modeli, zadań, konfiguracji, indeksów RAG, zasobów i zewnętrznych narzędzi.
  • 100animaworks-guide
    Podaje składnię poleceń animaworks: start i stop serwera, tworzenie Anima, modele, zadania, konfigurację, RAG i logi.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.