设备联动封禁智能体

设备联动封禁智能体

这是一个基于 FastMCP 最新版本构建的 AiPy 扩展脚手架，用于后续接入 AF 设备联动封禁能力。

项目结构

• device_block_agent/：核心 Python 源码与 MCP 工具实现。
• docs/：API 整理文档、方案文档与原始 PDF。
• assets/：图标等静态资源。
• examples/：白名单样例和参考素材。
• 根目录：保留 main.py、manifest.json、requirements.txt、README.md 等项目入口文件。

当前状态

• 已接入 FastMCP 3.2.4。
• 已提供 Streamable HTTP MCP 服务入口，默认暴露路径为 /mcp。
• 已提供 AiPy 要求的 addition-system-instruction prompt。
• 已提供 auth_login、auth_keepalive、auth_logout 三个认证工具。
• 已提供 block_list_temp、block_list_business、block_get_total_count、block_get_block_time 四个只读查询工具。
• 已提供白名单规则加载与人工确认判定模块，可供后续写操作工具直接复用。
• 已提供 block_add_business、block_delete_temp、block_delete_business、block_clear_attackers、block_clear_temp、block_clear_business、block_set_block_time 七个写操作工具。
• 已提供本地 JSONL 审计日志与按操作类型细化的回检结果。
• 已支持通过本地 JSON 文件持久化登录会话，用于跨进程复用登录态。
• 已支持本地会话超时判断与临近过期自动 keepalive。
• 已支持默认 AF 账号与连接配置，认证和封禁工具可直接复用。
• 已提供最小工具 agent_info，用于验证 AiPy 到 MCP 服务的发现链路。
• 已接入首版业务级回检策略，block_clear_attackers 已升级为前后基线对比判定。

本地运行

1. 安装依赖：pip install -r requirements.txt
2. 启动服务：python main.py
3. 服务启动后会在标准输出打印随机端口号。

风控配置

1. examples/whitelist.sample.json 提供本地白名单示例。
2. confirm_mode 支持 manual 和 auto 两种模式。
3. WHITELIST_FILE 和 CONFIRM_MODE 可通过 manifest.json 的 user_config 注入运行环境。
4. 清空类操作始终要求显式确认；批量新增、批量删除在 manual 模式下要求显式确认。
5. LOG_FILE 可用于指定本地 JSONL 审计日志路径。
6. SESSION_FILE 可用于指定本地 JSON 会话持久化路径。
7. SESSION_TIMEOUT_SECONDS 和 SESSION_REFRESH_WINDOW_SECONDS 可用于控制本地会话超时与自动保活窗口。

账号配置

1. af_host 用于配置默认 AF 主机地址。
2. af_namespace 用于配置默认命名空间，默认 public。
3. af_username 和 af_password 用于配置默认登录账号。
4. af_verify_tls 用于配置默认 HTTPS 证书校验开关。
5. 配置完成后，auth_login、auth_keepalive、auth_logout 以及封禁相关工具都可直接复用这些默认值。

当前已实现工具

1. agent_info
2. auth_login
3. auth_keepalive
4. auth_logout
5. account_config_status
6. block_list_temp
7. block_list_business
8. block_get_total_count
9. block_get_block_time
10. block_add_business
11. block_delete_temp
12. block_delete_business
13. block_clear_attackers
14. block_clear_temp
15. block_clear_business
16. block_set_block_time

下一步实现

1. 如需生产落地，再补日志轮转和敏感字段分级脱敏。
2. 如需更强回检能力，再补基于业务记录 ID 或操作结果对象的精确比对。
3. 如需长期运行，再补 token 失效后的自动重新认证策略。