沈永佳周文档

backend/requirements.txt

@@ -2,6 +2,7 @@ fastapi
 uvicorn[standard]
 SQLAlchemy
 asyncpg
+psycopg2-binary
 python-dotenv
 passlib[bcrypt]
 bcrypt==3.2.0

doc/process/weekly/week-12/members/shenyongjia-weekly-summary-12.md

@@ -0,0 +1,29 @@
+# 第十二周周总结（沈永佳）
+
+## 本周完成
+- 试用 Cloudflare 本地隧道进行联调，打通外网访问本地开发环境的通道，便于跨网络接口验证与前后端联动。
+- 设计与实现智能体循环（Agent Loop）的基本流程，明确状态管理、消息传递与中断/重试策略，支持可扩展的工具调用。
+- 定义日志体系与基础命令工具：统一日志结构与级别；抽象通用命令执行工具（基础命令、远程调用），为后续可观测与审计打底。
+- 接入 AI 路由模块：根据任务类型/优先级选择合适的推理路径与工具组合，初步打通从路由到工具调用的链路。
+- 模型 API 接入方案评审：梳理 OpenAI/本地推理的接入差异与鉴权策略，明确配置项与容错要求。
+
+## 细节与参考
+- Cloudflare Tunnel：为本地服务提供临时公网入口，便于第三方或外网环境联调；对隧道重连与心跳做基线测试。
+- 智能体循环：将任务拆分为感知、决策、执行三个阶段，提供上下文迭代与错误恢复机制；保留钩子以接入不同模型。
+- 日志与命令工具：统一日志字段（时间、级别、traceId、actor、action、结果）；命令工具支持超时、重试与结果结构化。
+- AI 路由：根据输入意图与安全策略选择模型与工具，路由降级到基础命令或手工回退；预留并发与节流控制。
+- 模型 API：形成配置模板（base_url、api_key、超时、重试），评估对话与函数调用（tools/functions）能力差异。
+
+## 问题与风险
+- 网络连通性不稳定：隧道在特定网络环境下存在中断风险，需要增加健康探测与自动重连策略。
+- 模型 API 依赖外部服务：需在鉴权、配额与速率限制上做好容错与降级，避免影响核心业务链路。
+- 日志吞吐与敏感信息：规范日志级别与脱敏策略，避免将凭据与隐私数据写入持久化存储。
+
+## 下周计划
+- 完成模型 API 的实际接入与联调，补齐鉴权、错误处理与重试逻辑，打通端到端调用闭环。
+- 扩展 AI 路由规则，基于任务特征与历史反馈优化选择策略，引入简单学习/记忆模块。
+- 提升日志可观测性：接入聚合/检索工具，完善指标与告警；为命令工具增加更细粒度的执行度量。
+- 完成隧道与本地服务的稳定性验证，增加断线重连与心跳监测，收敛跨网联调的常见故障。
+
+## 结论
+- 已完成隧道联调、智能体循环骨架、日志与基础命令工具定义、AI 路由的初步打通；模型 API 方案明确，待下一周完成实际接入与端到端验证。

doc/process/weekly/week-13/members/shenyongjia-weekly-plan-13.md

@@ -0,0 +1,41 @@
+# 第十三周周计划（沈永佳）
+
+## 目标与产出
+- 完成模型 API 接入与联调，形成可复用的配置与调用封装（支持超时、重试、错误分类）。
+- 扩展 AI 路由策略，基于任务类型与风险等级选择模型/工具，支持降级与熔断。
+- 加强日志与基础命令工具度量，完善字段与采样策略，支持链路追踪与失败复盘。
+- 提升 Cloudflare 本地隧道稳定性，加入健康探测与自动重连，验证跨网联调的可用性。
+- 打通“注册集群”端到端流程，在可达网络环境下完成 UUID 采集与持久化，输出联调案例与文档。
+
+## 任务拆分
+- 模型 API
+  - 封装调用层：统一 `base_url/api_key/timeout/retry` 等配置；实现错误分类（网络、鉴权、配额、语义）。
+  - 接口适配：支持对话与函数调用（tools/functions），返回结构标准化。
+  - 联调与回归：编写最小用例集，覆盖成功、超时、速率限制与服务不可用。
+- AI 路由
+  - 策略扩展：根据任务意图、复杂度、敏感级别路由到不同模型或工具。
+  - 降级方案：工具不可用/模型失败时回退到基础命令或手工提示，记录降级原因。
+  - 性能与配额：加入节流与并发控制，避免突发请求压垮外部服务。
+- 日志与命令工具
+  - 字段统一：时间、级别、traceId、actor、action、args、result、duration、error。
+  - 指标采集：为命令执行增加耗时、成功率、重试次数与错误类型统计。
+  - 观测接入：整理聚合/查询方案，形成查询示例与故障排查手册。
+- 隧道稳定性
+  - 健康检查：周期性心跳与重连；对中断/抖动场景进行基线测试。
+  - 安全与访问：整理访问控制与临时授权流程，避免泄露内部端点。
+- 集群注册联调
+  - 网络打通：在可达网络环境验证 SSH 连接与 HDFS `VERSION` 读取。
+  - 接口脚本：提供 `curl/httpx` 脚本与演示数据，记录常见失败与处理建议。
+  - 文档与案例：更新 README 与联调用例，明确前置条件与错误码语义。
+
+## 验收标准
+- 模型 API：完成至少 6 个场景的联调（成功/超时/配额/鉴权/不可达/降级），全部用例通过。
+- AI 路由：三类任务（信息检索、运维命令、数据加工）均可正确路由与降级，记录路由决策与耗时。
+- 日志与工具：日志字段完整且有样例；命令工具导出基础指标并可检索。
+- 隧道：连续运行 24 小时稳定，断线重连成功率 ≥ 95%，提供问题清单与改进建议。
+- 集群注册：在可达环境下完成一次成功注册，含 UUID 采集与后续指标采集启动。
+
+## 风险与应对
+- 外部模型服务不稳定：增加重试与降级策略，关键路径旁路到基础命令。
+- 网络不可达：准备本地可达环境或内网代理，避免联调阻塞；记录替代流程。
+- 日志敏感信息：严格脱敏与分级，限制密钥与密码进入持久化存储。

doc/process/weekly/week-13/members/shenyongjia-weekly-summary-13.md

@@ -0,0 +1,31 @@
+# 第十三周周总结（沈永佳）
+
+## 本周完成
+- **AI/Cat 基础功能前后端联调**：
+  - 完成了后端 `/api/v1/ai/chat` 与前端界面的对接，实现了流式对话或基础问答的闭环。
+  - 接入了 LLMClient（支持 OpenAI/SiliconFlow/DeepSeek），并支持 `LLM_SIMULATE` 模式以便于本地开发。
+- **用户-角色-权限映射优化**：
+  - 优化了 `user_cluster_mapping` 表结构与逻辑，在注册集群时自动绑定当前用户为管理员（admin），并支持 `role_id` 写入。
+  - 修正了集群注册时的权限校验逻辑，仅允许 admin/ops 角色操作。
+- **AI 聊天架构优化**：
+  - 统一了 LLM 调用入口，支持多 Provider 配置（OpenAI/DeepSeek等），并对 Endpoint 进行了规范化处理。
+  - 为诊断代理（DiagnosisAgent）预留了工具调用接口（Tools），支持后续扩展自动修复能力。
+- **第二测试集群部署**：
+  - 完成了第二个 Hadoop 测试集群的部署与纳管，验证了多集群管理功能的稳定性。
+
+## 细节与参考
+- AI 路由实现：`backend/app/routers/ai.py:57-66`
+- LLM 客户端封装：`backend/app/services/llm.py:43-80`
+- 角色映射逻辑：`backend/app/routers/clusters.py:177`
+
+## 问题与解决
+- **问题**：部分国内模型 API 端点路径不一致（如 `/v1` 后缀差异）。
+- **解决**：在 `LLMClient` 中增加了 `_normalize_endpoint` 逻辑，自动适配不同厂商的 URL 规范。
+
+## 下周计划
+- 推进 AI 自动诊断与修复（Agent）的深层逻辑实现，从“模拟输出”转向真实工具调用。
+- 完善前端对 Markdown/Code Block 的渲染支持，提升 AI 回复的可读性。
+- 针对多集群场景进行压力测试，观察 MetricsCollector 的性能表现。
+
+## 结论
+- 本周重点打通了 AI 基础链路与多集群管理闭环，后端架构对多模型支持更加灵活。下周将聚焦于智能体的“执行力”（Tool Calling）与前端体验优化。

doc/process/weekly/week-14/members/shenyongjia-weekly-plan-14.md

@@ -0,0 +1,36 @@
+# 第十四周周计划（沈永佳）
+
+## 核心目标
+- **系统功能收尾**：完成剩余的所有核心功能模块开发，确保系统具备完整的业务闭环能力。
+- **集群访问攻坚**：彻底解决跨网段/跨环境下的集群访问与通信问题（如 SSH 超时、UUID 探测失败）。
+- **智能体工具链**：打通 AI Agent 的工具调用（Tool Calling）链路，实现“诊断-修复”自动化。
+- **页面深度联调**：完成前端页面与后端接口的深度对接，修复交互体验问题。
+
+## 详细计划
+### 1. 系统功能收尾
+- **任务内容**：
+  - 梳理并补全尚未实现的 API 接口（如高级监控查询、批量运维操作）。
+  - 完善异常处理机制，确保所有 500 错误均有对应的友好提示。
+- **验收标准**：后端接口覆盖率达到 95% 以上，关键业务流程无阻断性 Bug。
+
+### 2. 集群访问问题解决
+- **任务内容**：
+  - 排查并修复后端服务器到 Hadoop 节点的网络连通性问题（端口转发/路由配置）。
+  - 优化 `ssh_utils` 中的超时重试机制，增加对网络抖动的容忍度。
+- **验收标准**：`telnet` 与 `ssh` 连接稳定，集群注册成功率 100%。
+
+### 3. AI 工具调用实现
+- **任务内容**：
+  - 在 `DiagnosisAgent` 中实现真实的工具执行逻辑（如 `exec_command`, `fetch_logs`）。
+  - 调试 LLM 对 Function Calling 的响应格式，确保参数解析准确。
+- **验收标准**：AI 能准确识别用户意图并调用对应工具，输出执行结果。
+
+### 4. 页面深度联调
+- **任务内容**：
+  - 配合前端修复数据展示延迟、状态不同步等 UI 问题。
+  - 验证 AI 对话组件的流式输出与 Markdown 渲染效果。
+- **验收标准**：前端页面操作流畅，控制台无报错，用户体验符合预期。
+
+## 风险与应对
+- **网络环境复杂**：若物理网络不可达，需准备反向代理或 VPN 方案作为备选。
+- **LLM 响应不可控**：增加 Prompt 约束与后处理校验，防止 AI 幻觉导致错误操作。