# seatable_skill

**Repository Path**: xm_recycle/seatable_skill

## Basic Information

- **Project Name**: seatable_skill
- **Description**: SeaTable Skill 是一个将 AI 能力与 SeaTable
  基表操作相结合的扩展框架，通过自然语言交互实现智能化的数据管理。项目提供模块化设计，包含四个核心技能：seatable-builder
  负责基表结构管理，支持创建删除表、添加修改列、创建表间关联；seatable-data
  专注于数据增删改查操作，实现查询、添加、更新和删除记录；seatable-analyst 提
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-22
- **Last Updated**: 2026-02-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SeaTable Skill v0.3.0

SeaTable Skill 是一个将 AI 能力与 SeaTable 基表操作相结合的扩展框架，支持通过自然语言与 SeaTable 数据进行交互。

## 技能列表

本项目包含以下四个技能：

### 1. seatable-builder（基表构建）

**功能**：创建和管理 SeaTable 基表结构

| 操作 | 说明 |
|------|------|
| 创建表 | 创建新的数据表 |
| 删除表 | 删除已有数据表 |
| 重命名表 | 修改表名称 |
| 添加列 | 向表中添加新列 |
| 修改列 | 修改列属性 |
| 删除列 | 删除表中的列 |
| 创建链接列 | 创建表间关联 |
| 列出视图 | 查看表中的视图 |

**触发关键词**：创建表、建表、添加列、删除表、表结构

### 2. seatable-data（数据处理）

**功能**：对基表数据进行增删改查操作

| 操作 | 说明 |
|------|------|
| 查询行 | 获取表中的行数据 |
| SQL 查询 | 执行 SQL 语句查询数据 |
| 添加行 | 向表中添加新记录 |
| 更新行 | 修改已有记录 |
| 删除行 | 删除记录 |

**触发关键词**：查询数据、添加记录、更新数据、删除行

### 3. seatable-analyst（数据分析）

**功能**：数据统计分析和报告生成（只读权限）

| 操作 | 说明 |
|------|------|
| SQL 分析 | 执行复杂 SQL 查询 |
| 统计分析 | 数据汇总统计 |
| 生成报告 | 生成 Markdown/HTML 报告 |

**触发关键词**：分析数据、统计报告、生成报告、数据汇总

### 4. seatable-skill-creator（技能创建器）

**功能**：创建和管理 SeaTable 业务技能

| 操作 | 说明 |
|------|------|
| 初始化技能 | 创建标准技能目录结构 |
| 获取表结构 | 从 SeaTable 获取表结构 |
| 生成 SKILL.md | 自动生成技能描述文件 |
| 生成 CRUD 脚本 | 自动生成增删改查脚本 |
| 验证技能 | 检查技能结构规范 |
| 打包技能 | 打包为 .skill 文件 |
| 更新技能 | 更新已有技能（含备份） |
| 回滚技能 | 回滚到备份版本 |

**触发关键词**：创建技能、生成技能、打包技能、技能开发

## 项目结构

```
seatable_skill/                    # 项目根目录
├── tools/                         # 共享工具库（必需）
│   └── seatable_shared_tools/
│       ├── __init__.py
│       ├── client.py              # SeaTable API 客户端
│       ├── config/                # 配置管理
│       │   ├── __init__.py
│       │   └── config_manager.py
│       ├── constants/             # 常量定义
│       │   ├── __init__.py
│       │   └── column_types.py
│       └── utils/                 # 工具函数
│           ├── __init__.py
│           ├── crypto.py          # 加密工具
│           ├── output.py          # 输出格式化
│           ├── platform.py        # 跨平台兼容
│           └── validation.py      # 参数验证
├── skills/                        # 技能目录
│   ├── seatable-builder/          # 基表构建技能
│   │   ├── SKILL.md
│   │   └── scripts/
│   ├── seatable-data/             # 数据处理技能
│   │   ├── SKILL.md
│   │   └── scripts/
│   ├── seatable-analyst/          # 数据分析技能
│   │   ├── SKILL.md
│   │   └── scripts/
│   └── seatable-skill-creator/    # 技能创建器
│       ├── SKILL.md
│       └── scripts/
├── tests/                         # 测试脚本
├── docs/                          # 文档
└── README.md                      # 本文件
```

**重要说明**：
- `tools/` 目录是共享工具库，所有技能脚本都依赖它
- `skills/` 目录包含四个独立技能
- `tools/` 和 `skills/` 必须保持在同一个父目录下，因为技能脚本通过相对路径引用工具库

## 部署指南

### 依赖安装

```bash
pip install seatable-api cryptography pyyaml
```

### 方式一：完整项目部署（推荐）

将整个项目克隆或复制到目标位置：

```bash
# 克隆项目
git clone https://gitee.com/xm_recycle/seatable_skill.git
cd seatable_skill

# 安装依赖
pip install -r requirements.txt  # 如果有
# 或
pip install seatable-api cryptography pyyaml
```

**关键**：保持 `tools/` 和 `skills/` 在同一目录下。

### 方式二：作为 Python 包使用

将项目根目录添加到 Python 路径：

```python
import sys
sys.path.insert(0, '/path/to/seatable_skill')

from tools.seatable_shared_tools.client import SeaTableClient

client = SeaTableClient(
    api_token="your_api_token",
    server_url="https://cloud.seatable.cn"
)
client.auth()
```

### 方式三：技能系统集成

如果您的系统支持技能（Skills）机制：

1. 确保项目完整部署（`tools/` + `skills/`）
2. 在系统配置中指向技能目录：
   ```bash
   # 技能目录路径
   SKILLS_PATH=/path/to/seatable_skill/skills
   ```
3. 系统加载技能时会自动解析 `SKILL.md` 文件

### 方式四：命令行直接使用

每个技能的脚本都可以直接在命令行运行：

```bash
# 进入项目目录
cd /path/to/seatable_skill

# 查询表中的记录
python skills/seatable-data/scripts/query_rows.py --table_name="任务表"

# 创建新表
python skills/seatable-builder/scripts/create_table.py --table_name="新表" --columns='[{"column_name": "名称", "column_type": "text"}]'

# 执行 SQL 查询
python skills/seatable-data/scripts/query_sql.py --sql="SELECT * FROM \`任务表\` LIMIT 10"
```

### 配置凭证

首次使用需要配置 SeaTable API Token：

1. 在 SeaTable 中打开目标基表
2. 进入「设置」→「API Token」
3. 创建一个有读写权限的 Token
4. 运行任意脚本时会提示配置

凭证保存在 `~/.seatable_skill/` 目录下（加密存储）。

## 使用示例

### Python 直接调用

```python
import sys
sys.path.insert(0, '/path/to/seatable_skill')

from tools.seatable_shared_tools.client import SeaTableClient, SeaTableError

# 初始化客户端
client = SeaTableClient(
    api_token="your_api_token",
    server_url="https://cloud.seatable.cn"
)

# 认证
client.auth()

# 获取表列表
tables = client.list_tables()
print(tables)

# 执行 SQL 查询
results = client.query("SELECT * FROM `Table1` LIMIT 10")
print(results)

# 添加行
row = client.append_row("任务表", {"名称": "新任务", "状态": "待办"})
print(row)
```

### 命令行使用

```bash
# 查看帮助
python skills/seatable-data/scripts/query_rows.py --help

# 查询数据
python skills/seatable-data/scripts/query_rows.py --table_name="任务表" --limit=20

# 添加数据
python skills/seatable-data/scripts/append_row.py --table_name="任务表" --row='{"名称": "测试任务"}'
```

## 测试

```bash
# 运行所有测试
pytest tests/ -v

# 运行 P0 优先级测试
pytest tests/ -v -m "p0"

# 生成覆盖率报告
pytest tests/ --cov=tools --cov=skills --cov-report=html
```

详见 [tests/README.md](tests/README.md)

## 文档

- [设计文档 v0.2](docs/v0.2/design_v0.2.0.md)
- [需求文档 v0.2](docs/v0.2/requirements_v0.2.0.md)
- [SeaTable API 参考](docs/references/seatable_docs/)
- [测试指南](tests/README.md)

## 版本历史

### v0.2.0 (当前)

- 重构为四个独立技能（builder、data、analyst、skill-creator）
- 新增共享工具层 `tools/seatable_shared_tools/`
- 新增 SeaTableClient 统一客户端（支持缓存）
- 完整的测试覆盖

### v0.1.0

- 初始版本
- 基础技能框架