# ai-module

**Repository Path**: txshare/ai-module

## Basic Information

- **Project Name**: ai-module
- **Description**: AI会话
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-28
- **Last Updated**: 2026-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ai-module

基于 [Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk/overview) 的 AI 调用库。
独立、无宿主依赖，可在任意 Python 项目中复用。

## 结构

| 模块 | 职责 |
|------|------|
| `client.py` | `run_claude` / `stop_claude` / `is_claude_running` 入口，线程 + asyncio 驱动 SDK |
| `config.py` | `ClaudeConfig` 数据类（一次调用全部可选项） |
| `options_builder.py` | `ClaudeAgentOptions` 构建（会话 resume、auth env 注入等） |
| `message_handler.py` | SDK 流消息 → `on_output(text, subtype)` 回调 |
| `skills.py` | **技能扩展**：提示词模板注册表（`{{变量}}` 渲染，按名注入） |
| `actions.py` | **动作扩展**：宿主 Python 函数 → 进程内 MCP 工具（`mcp__ai_actions__*`） |
| `ask_user_tool.py` | AskUserQuestion MCP 工具（AI 反向提问 UI） |
| `permission_tool.py` | can_use_tool 权限桥（白名单外工具 → UI 批准） |
| `task_queue.py` | Task* 工具事件 → 任务列表快照回调 |

## 安装

```bash
pip install -e path/to/ai-module
```

依赖：`claude-agent-sdk`，本机需有 `claude` CLI。

## 快速开始

```python
import ai_module

ai_module.run_claude(
    "总结这个项目的结构",
    ai_module.ClaudeConfig(cwd="/path/to/project"),
    on_output=lambda text, subtype: print(f"[{subtype}] {text}"),
)
```

## 技能扩展（skills）

```python
from ai_module import get_skill_registry

reg = get_skill_registry()
reg.register_file("prompts/review.md")          # 文件名即技能名

ai_module.run_claude(
    "帮我评审这段代码",
    ai_module.ClaudeConfig(
        cwd=".",
        skills=["review"],                       # 注入到 prompt 前部
        skill_variables={"lang": "python"},      # 渲染 {{lang}}
    ),
    on_output=lambda t, s: print(t, end=""),
)
```

## 动作扩展（actions）

```python
from ai_module import get_action_registry

reg = get_action_registry()

@reg.register("query_kline", description="查询股票日K线")
def query_kline(code: str, days: int = 60) -> dict:
    return {"code": code, "days": days}

# ClaudeConfig.enable_actions 默认开：注册表非空即自动挂载为 MCP 工具，
# agent 以 mcp__ai_actions__query_kline 调用
```

同步动作自动放线程池执行（不阻塞 SDK 事件循环），单个动作超时 300s，
失败以 JSON 文本回传（agent 可自行调整重试），不中断整轮。