Skip to content

Keeper 项目完善：架构重构 + 功能增强 + 生产就绪度提升#2

Merged
seventhocean merged 16 commits into
mainfrom
feature/improvements
May 16, 2026
Merged

Keeper 项目完善：架构重构 + 功能增强 + 生产就绪度提升#2
seventhocean merged 16 commits into
mainfrom
feature/improvements

Conversation

@kiro-agent

@kiro-agent kiro-agent Bot commented May 15, 2026

Copy link
Copy Markdown

This pull request was generated by @kiro-agent 👻

Comment with /kiro fix to address specific feedback or /kiro all to address everything.
Learn about Kiro autonomous agent

概述

根据项目分析报告中发现的不足之处，进行了系统性的完善和增强，涵盖 3 个 P0（架构必修）、4 个 P1（功能增强）、2 个 P2（工程改进）共 9 项改进。

变更内容

P0 — 架构必修

  • 拆分 core/agent.py — 将 2038 行单文件拆为 core/agent.py (549行) + core/handlers/ (10个模块)，按功能域划分
  • 接入 InspectionHistory — inspect_server 巡检成功后自动写入 SQLite，为 Comparator/CapacityPredictor 提供数据源
  • 配置文件锁 — 引入 fcntl.flock (Linux) / msvcrt (Windows) 防止并发读写冲突

P1 — 功能增强

  • 记忆主动注入 — 会话首次对话时自动向 LLM 注入最近 3 条操作记忆（实现 memory-roadmap P0）
  • Plugin 扩展机制 — 支持 ~/.keeper/plugins/ 目录下自定义工具的自动发现和加载
  • Graceful Shutdown — 信号处理器 + 清理函数注册，确保中断时安全退出
  • 审计日志轮转 — 默认 10MB 上限，保留 5 个归档文件，写入前自动检查

P2 — 工程改进

  • 依赖版本上限 — 为所有 19 个依赖添加版本约束，防止未来破坏性更新
  • 测试 fixture 统一 — 新增 conftest.py (15+ fixture) + pytest.ini + integration 标记

新增文件

  • keeper/core/handlers/ — 10 个 handler 模块
  • keeper/agent/plugins.py — 插件系统
  • keeper/utils/shutdown.py — 优雅停机管理器
  • tests/conftest.py — 统一测试 fixture
  • pytest.ini — pytest 标记配置

测试

  • 所有新增代码通过语法验证
  • ShutdownManager / Plugin 系统 / 文件锁 / 审计轮转 均通过独立功能测试
  • 未修改已有测试逻辑，仅添加标记

kiro-agent and others added 16 commits May 15, 2026 17:19
@kiro-agent @seventhocean
refactor(core): 拆分 agent.py 为 handlers 模块
844691c 
将 2038 行的单文件拆分为:
- core/agent.py (549行): 路由逻辑、确认处理、辅助方法
- core/handlers/ (10个模块): 按功能域划分的意图处理器
  - inspect.py: 服务器巡检
  - k8s.py: K8s 集群管理
  - docker.py: Docker 容器管理
  - network.py: 网络诊断
  - security.py: 安全扫描 & 证书
  - fix.py: 自动修复
  - logs.py: 日志查询
  - notify.py: 通知推送
  - schedule.py: 定时任务
  - misc.py: 帮助/导出/配置等

Co-authored-by: GAO YUAN <147985989+seventhocean@users.noreply.github.com>
@kiro-agent @seventhocean
feat(storage): inspect_server 执行后自动写入 InspectionHistory
c5da8d0 
- Agent Loop 的 inspect_server 工具执行成功后自动保存到 SQLite
- 经典模式的 inspect handler 同样接入历史写入
- 批量巡检时每台主机分别写入历史
- 写入失败不影响巡检结果（静默 pass）
- 为后续 Comparator/CapacityPredictor 提供数据源

Co-authored-by: GAO YUAN <147985989+seventhocean@users.noreply.github.com>
@kiro-agent @seventhocean
feat(config): 增加文件锁防止并发读写冲突
b24e918 
- 引入 _file_lock 上下文管理器（跨平台：Linux fcntl / Windows msvcrt）
- load() 使用共享锁（LOCK_SH），允许并发读
- save() 和 save_llm_config() 使用排他锁（LOCK_EX），防止并发写
- save_llm_config() 改为先读后写（read-modify-write），避免覆盖其他配置
- save() 现在也保存 timeouts 配置（之前遗漏）
- 锁文件使用 .lock 后缀，不污染配置文件本身

Co-authored-by: GAO YUAN <147985989+seventhocean@users.noreply.github.com>
@kiro-agent @seventhocean
feat(memory): 会话启动时主动注入最近记忆摘要到 LLM
aaab6af 
- 增加 _first_turn 标志追踪首次对话
- 首次 process() 时主动从 AgentMemory 读取最近 3 条记忆
- 格式化为 [上次工作回顾] 注入 LLM 上下文
- 后续对话保持原有的关键词匹配被动注入机制
- 实现 memory-roadmap.md 中 P0 项的需求

Co-authored-by: GAO YUAN <147985989+seventhocean@users.noreply.github.com>
@kiro-agent @seventhocean
feat(plugins): 添加用户自定义工具扩展机制
b55bfe4 
新增 keeper/agent/plugins.py 插件系统：
- 自动发现 ~/.keeper/plugins/ 目录下的 .py 文件
- 动态导入并收集 TOOLS 列表中的工具
- 支持自动发现带 @tool 装饰器的函数
- 加载失败时记录警告，不影响主流程
- 提供 list_plugins/format_plugins_info 用于展示

集成变更：
- tools_registry.py: ALL_TOOLS 列表末尾自动加载插件工具
- hybrid.py: 新增 /plugins 命令查看已安装插件
- 包含完整的插件编写文档和示例

Co-authored-by: GAO YUAN <147985989+seventhocean@users.noreply.github.com>
@kiro-agent @seventhocean
feat(shutdown): 增加 Graceful Shutdown 优雅停机机制
009fe04 
新增 keeper/utils/shutdown.py:
- ShutdownManager 管理信号处理和清理函数
- 支持 SIGINT/SIGTERM 信号捕获
- running_task() 上下文管理器标记当前任务
- 清理函数 LIFO 顺序执行
- 第二次 Ctrl+C 强制退出
- 全局单例 get_shutdown_manager()

CLI 集成：
- start_agent_chat() 安装信号处理器
- 注册 agent 清理函数（保存记忆、标记停止）
- REPL 循环中检查 is_shutting_down 标志
- 第一次 Ctrl+C 提示用户而非静默继续

Co-authored-by: GAO YUAN <147985989+seventhocean@users.noreply.github.com>
@kiro-agent @seventhocean
feat(audit): 审计日志增加自动轮转和大小限制
27ee479 
- 默认单文件上限 10MB，超限时自动轮转
- 保留最近 5 个归档文件 (audit.log.1 ~ .5)
- 轮转策略：rename chain (N → N+1)，最旧的删除
- log_turn() 写入前自动检查是否需要轮转
- 轮转/写入失败不抛异常，不影响主流程
- 新增 get_log_info() 方法用于诊断日志状态
- 支持自定义 max_size_bytes 和 max_backups 参数

Co-authored-by: GAO YUAN <147985989+seventhocean@users.noreply.github.com>
@kiro-agent @seventhocean
chore(deps): 为所有依赖添加版本上限约束
63593e1 
防止未来破坏性版本更新导致不兼容：
- langchain 全家桶: <1.0（0.x 到 1.0 可能有大量 breaking changes）
- pydantic: <3.0
- click: <9.0
- prompt-toolkit: <4.0
- psutil: <7.0（宽松，稳定库）
- httpx: <1.0
- kubernetes SDK: <32.0
- fastapi/uvicorn: <1.0
- 开发依赖: 适度宽松的上限

Co-authored-by: GAO YUAN <147985989+seventhocean@users.noreply.github.com>
@kiro-agent @seventhocean
test: 增加 integration 标记和统一 mock fixture
e8586ca 
新增 tests/conftest.py:
- 注册 markers: integration, slow, requires_llm
- mock_config / mock_config_no_llm: 隔离的配置 fixture
- mock_server_status / mock_server_status_critical: 服务器状态 mock
- tmp_audit_logger: 临时审计日志
- mock_nlu_engine: NLU 引擎 mock
- mock_agent_memory: 临时记忆
- mock_subprocess_success/failure: subprocess mock
- has_docker / has_nmap / has_llm_key: 环境检测跳过

新增 pytest.ini:
- --strict-markers 防止拼写错误
- 标记文档化

标记应用:
- test_integration.py: pytestmark = pytest.mark.integration
- test_agent_e2e.py: pytestmark = pytest.mark.integration

用法: pytest -m 'not integration' 跳过集成测试

Co-authored-by: GAO YUAN <147985989+seventhocean@users.noreply.github.com>
@kiro-agent
feat(api): API 服务全面增强
59e7cb1 
- WebSocket /ws/query: 流式输出 Agent 工具调用过程
- Rate Limiting 中间件: 每分钟 60 次/IP，429 响应 + Retry-After
- Bearer Token 认证: 已有基础上增强错误提示
- OpenAPI 文档完善: 每个接口添加 description、Field 说明、examples、tags 分组
- 新增接口: /api/v1/audit（审计日志）、/api/v1/memory（Agent 记忆）
- Runbook 执行改为 run_in_executor 避免阻塞事件循环
- CORS 支持环境变量配置 KEEPER_CORS_ORIGINS
- Rate Limit 支持环境变量 KEEPER_RATE_LIMIT 自定义
- X-RateLimit-Limit/Remaining 响应头
@kiro-agent
feat(async): 异步并发支持模块
6b1a27e 
新增 keeper/utils/async_utils.py:
- run_in_thread(): 将同步函数包装为 asyncio 友好的异步调用
- async_ping_hosts(): 并发 ping 多台主机（Semaphore 限流）
- async_check_ports(): 并发端口检测
- async_batch_inspect(): 异步批量服务器巡检
- AsyncBatchExecutor: 通用异步批量执行器
- get_executor(): 全局复用线程池

API Server 新增异步批量接口:
- POST /api/v1/batch/ping: 并发 ping 多台主机
- POST /api/v1/batch/inspect: 异步批量巡检
- POST /api/v1/batch/ports: 并发端口检测
@kiro-agent
feat(i18n): 国际化支持 — 中英文切换
45415a8 
新增 keeper/i18n/ 模块：
- __init__.py: t() 翻译函数、set_language()/get_language()
- packs/zh.py: 中文语言包（system prompt、帮助、CLI 文本、错误消息）
- packs/en.py: 英文语言包

集成变更：
- agent/loop.py: AGENT_SYSTEM_PROMPT 改为动态获取（优先 i18n）
- agent/hybrid.py: _get_help_text() 优先从 i18n 获取
- config.py: 新增 language 字段，保存/加载时持久化

使用方式：
- 环境变量: KEEPER_LANG=en keeper
- 配置文件: language: en
- 代码: from keeper.i18n import set_language; set_language('en')
@kiro-agent
feat(tools): 接入 Comparator 和 CapacityPredictor 到 Agent Loop
409b4b4 
新增 2 个 Agent 工具（总数 21→23）：
- compare_inspection: 巡检历史对比（与上次 diff + 7 天趋势）
- predict_capacity: 容量预测（线性回归预测何时达到阈值）

增强 inspect_server 工具：
- 巡检完成后自动与上次对比，异常变化时追加摘要提示

触发场景：
- '和上次对比变化大吗' → compare_inspection
- '磁盘还能用多久' → predict_capacity
- '检查本机' → inspect_server（自动追加对比信息）
@kiro-agent
feat(memory): /memory command enhanced with filtering
121b910
@kiro-agent
test: 迁移测试到使用 conftest.py 统一 fixture
9f0640c 
test_audit.py:
- 使用 tmp_audit_logger fixture 替代手动创建 AuditLogger
- 新增 test_log_rotation 和 test_log_info 测试
- 减少样板代码（不再重复 log_file = tmp_path / 'audit.log'）

test_agent_safety.py:
- 移除 sys.path.insert 手动路径注入（conftest 已处理）

后续可继续迁移其他测试文件使用 mock_config、
mock_server_status 等 fixture。
@kiro-agent
chore(deps): 添加 requirements.lock 精确版本锁定
9630a03 
新增文件：
- requirements.lock: 所有依赖的精确版本锁定（含传递依赖）
- scripts/lock-deps.sh: 一键重新生成锁定文件

用途：
- 生产部署: pip install -r requirements.lock（100% 可复现）
- 开发环境: pip install -e '.[dev]'（使用范围约束）
- 更新依赖: ./scripts/lock-deps.sh

锁定版本基于 2026-05-15 最新兼容版本。
可选依赖（k8s/api/dev）以注释形式包含，按需启用。
@seventhocean
seventhocean merged commit 9630a03 into main May 16, 2026
0 of 8 checks passed
@seventhocean
seventhocean deleted the feature/improvements branch May 30, 2026 07:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@seventhocean @kiro-agent