# IMA Skill 权限说明文档

## 概述

本技能用于IMA笔记和知识库管理，需要访问用户配置的凭证和网络服务来完成相关操作。

## 所需权限

### 1. 配置文件访问

**访问路径：**
- `~/.config/ima/client_id` (可选)
- `~/.config/ima/api_key` (可选)

**用途：**
- 读取IMA API客户端ID和API密钥
- 用于身份验证和授权访问IMA服务

**说明：**
- 这些文件是可选的，优先使用环境变量
- 如果用户已配置环境变量，不会读取配置文件
- 配置文件仅用于存储凭证，不包含其他敏感信息

### 2. 网络访问

**访问域名：**
- `ima.qq.com` - IMA主要API服务
- `*.myqcloud.com` - 腾讯云COS文件上传服务

**用途：**
- `ima.qq.com`：访问IMA笔记和知识库API
- `*.myqcloud.com`：上传文件到腾讯云对象存储

**说明：**
- 所有网络请求均通过HTTPS加密传输
- 凭证仅发送到ima.qq.com进行身份验证
- COS服务仅用于文件上传，不存储或处理凭证

## 凭证安全

### 存储建议

1. **环境变量（推荐）**
   ```bash
   export IMA_OPENAPI_CLIENTID="your_client_id"
   export IMA_OPENAPI_APIKEY="your_api_key"
   ```

2. **配置文件**
   ```bash
   mkdir -p ~/.config/ima
   echo "your_client_id" > ~/.config/ima/client_id
   echo "your_api_key" > ~/.config/ima/api_key
   chmod 600 ~/.config/ima/*
   ```

### 安全措施

1. **凭证保护**
   - COS凭证（secret_id/secret_key/token）不再打印到stdout
   - 临时凭证文件在使用后自动清理
   - 所有敏感操作通过HTTPS加密传输

2. **访问控制**
   - 仅访问用户授权的笔记和知识库
   - 不会修改或删除用户未明确指定的内容
   - 所有操作需要用户明确授权

## COS服务说明

### 为什么需要COS服务

1. **文件上传**
   - IMA使用腾讯云COS作为文件存储后端
   - 上传文件需要COS临时凭证
   - COS提供可靠、安全的文件存储服务

2. **凭证使用**
   - COS凭证由IMA API动态生成
   - 凭证具有时间限制和权限限制
   - 仅用于单次文件上传操作

### 安全保障

1. **凭证最小化**
   - COS凭证仅具有上传权限
   - 凭证有效期通常为1小时
   - 不能用于访问其他腾讯云服务

2. **传输安全**
   - 所有请求通过HTTPS加密
   - 凭证不存储在日志中
   - 临时文件使用后立即删除

## 使用建议

1. **定期轮换凭证**
   - 建议定期更新IMA API密钥
   - 使用环境变量而非配置文件时，重启服务后生效

2. **权限监控**
   - 定期检查IMA账户活动日志
   - 发现异常活动及时处理

3. **安全环境**
   - 在受信任的环境中使用本技能
   - 避免在公共或共享系统上存储凭证

## 故障排除

### 常见问题

1. **凭证错误**
   - 检查环境变量或配置文件是否正确
   - 确认凭证未过期

2. **上传失败**
   - 检查文件大小是否超过限制
   - 确认网络连接正常

3. **权限不足**
   - 确认凭证具有足够权限
   - 检查目标知识库是否存在且可访问

### 联系支持

如遇到安全相关问题，请联系：
- IMA官方支持：https://ima.qq.com
- 安全问题反馈：security@ima.qq.com