技能管理

技能（Skills）是 PM7 平台中由 AI Agent 调用的一种自动化工具。技能可以独立完成特定任务（如查询数据、生成报告），也可以组合使用以完成复杂业务场景。

技能列表

技能列表展示了所有已创建的分析技能，包括技能名称、描述、状态等信息。

技能工具

技能工具是技能调用的底层能力，主要包括：

工具类型	说明	调用方式
API 工具	后端业务 API	通过 Skills 程序调用
MCP 工具	外部服务集成	直接由 LLM 调用
Agent 工具	AI Agent 能力	对话式交互

MCP 服务器

MCP（Model Context Protocol）服务器是外部工具的接入协议，支持：

• 网页检索：通过 Tavily 进行网页搜索和内容提取
• 文件处理：文档解析和数据提取
• 第三方集成：与外部系统对接

MCP 工具调用规则

1. 工具名格式：mcp:server_tool（如 mcp:tavily_tavily_search）
2. 参数必须符合 JSON Schema 规范
3. 每次调用需明确输出格式和错误处理

技能状态

状态	说明	能否被调用
草稿	技能正在编写中	否
验证中	技能正在验证	否
已激活	技能已启用	是
已禁用	技能已停用	否
错误	技能存在错误	否

操作

上传技能

创建新的分析技能，需要提供：

• 技能标识（slug）：唯一标识符，建议使用小写字母和短横线
• 技能名称：显示名称
• 技能描述：功能说明，便于 AI 理解何时调用
• 技能文件：SKILL.md（提示词）或 SKILL.md + main.py（程序型）

技能文件规范

SKILL.md 结构

---
name: skill-name
version: 1.0.0
description: 技能描述
api_whitelist:           # 可选，需要调用的 API 列表
  - api_name
parameters:              # 输入参数定义
  type: object
  properties:
    param1:
      type: string
      description: 参数说明
  required:
    - param1
outputs:                 # 输出格式定义
  type: object
  properties:
    result:
      type: object
business_rules:          # 业务规则说明
  - 规则1
  - 规则2
---
# 使用说明

技能的具体使用说明...

main.py 结构（程序型技能）

"""技能名称"""

def main(api, context):
    """主函数

    Args:
        api: API 调用代理，提供各种业务 API
        context: 上下文信息，包含参数和配置

    Returns:
        dict: 执行结果
    """
    params = context.get("params", {}) or {}
    # 业务逻辑
    return {"result": "..."}

业务规则

1. 多租户隔离

• 所有技能执行时自动携带租户信息（tenant_id）
• API 调用受 RLS（行级安全策略）保护
• 技能无法访问其他租户的数据

2. 参数验证

参数类型	格式要求	错误处理
UUID	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	提示格式错误
日期	ISO 8601 格式	自动转换或报错
分页	page ≥ 1, page_size ≤ 100	自动限制范围

3. 调用限制

资源	限制	说明
API 调用	60次/分钟/租户	超出后限流
MCP 调用	30次/分钟/租户	超出后限流
输入长度	根据技能定义	超出时提示用户

4. 错误处理

错误码	说明	用户提示
400	参数错误	检查输入格式
401	未认证	请先登录
403	权限不足	需要相关权限
404	资源不存在	检查 ID 是否正确
429	请求过多	请稍后再试
500	服务器错误	记录并重试

5. 数据最小化原则

• 默认只发送结构化摘要给 AI
• 原始数据需要脱敏处理
• 敏感字段（手机号、身份证等）必须隐藏

MCP 管理

添加客户端

1. 点击"添加 MCP 客户端"
2. 填写服务器配置信息
3. 测试连接是否正常
4. 保存并同步工具

刷新连接

• 定期刷新检查 MCP 服务器状态
• 连接异常时显示错误信息
• 可手动触发重新连接

同步工具

• 将 MCP 服务器的工具同步到平台
• 同步后工具即可被 Agent 调用
• 建议在添加新工具后执行同步

搜索与筛选

• 搜索：支持按技能名称、标识搜索
• 状态筛选：按技能状态（草稿/验证中/已激活/已禁用/错误）筛选
• 批量操作：支持批量启用、禁用、删除

最佳实践

1. 单一职责：每个技能只完成一个明确的任务
2. 清晰描述：技能描述应说明适用场景和调用条件
3. 错误处理：提供明确的错误提示和解决建议
4. 参数验证：在技能层面验证输入参数格式
5. 安全第一：敏感操作需要二次确认