kb-agent CLAUDE.md

项目记忆 · KB-Agent

身份

你是 KB-Agent（内部 + Partner 共享 Agent 知识平台）的架构助手。任何改动前先给计划，等用户确认再执行。

项目一句话

面向内部员工与外部 Partner 的共享 Agent 知识平台：管理员上传文档 → Agent 自动归类/总结沉淀为可检索知识 → 用户通过对话查询知识并获取原文；架构预留 Skill 插拔框架（未来接入 SCM 等 skill，可在人工确认后下发 PANW 产品配置）。

技术栈（禁止中途更换，如需变更走 /design 流程）

• Backend: Python 3.12 + FastAPI（async），Pydantic v2
• 数据库: PostgreSQL 16（元数据 + 全文检索 tsvector）；MVP 不引入向量库（检索走结构化元数据 + 关键词，把原文交给 LLM 回答以降低幻觉）
• 文件存储: MVP 用本地文件系统（保持架构简单）；通过 StorageProtocol 抽象封装，未来可换云对象存储而不动业务层
• 正文/归类: 交给 Claude CLI 直接读原文（Word/PDF/图片/Excel/PPT 等常见格式 CLI 原生支持），归类时一趟调用同时产出 {分类, 摘要, 标签, 可搜正文 content_text}，MVP 不自己写解析库
• Agent 引擎: 封装 CLI 子进程，通过 EngineProtocol 抽象层调用；已实现 ClaudeCliEngine（claude 子进程）和 CodexCliEngine（codex exec 子进程）；预留 OpenClaw 等未来后端
• 认证: 自建用户表 + 邮箱密码，注册时按 域名后缀白名单 控制准入；access token（JWT，默认 60 分钟）+ sliding refresh token（httpOnly cookie，30 天，rotate on use）实现无感续期
• 异步处理: 归类走 后台任务（含处理任务表 + 详细日志 + 失败可重试）
• 前端: Next.js（App Router）+ TypeScript + Tailwind。只对用户暴露一个端口——Next.js 作统一入口，经 rewrites 把 /api/* 反代到后端 FastAPI，用户不直接访问后端端口
• 部署: 云上部署（本地开发用 Docker Compose；对象存储 MVP 暂用本地路径）

目录约定

backend/
  app/
    api/          # 路由层：只做参数校验、鉴权、转发，禁止业务逻辑
    services/     # 业务逻辑，单一职责（doc_service / search_service / classify_service ...）
    models/       # SQLAlchemy ORM 模型
    schemas/      # Pydantic 请求/响应 schema
    core/         # 配置、DB 连接、鉴权中间件、异常处理
    engine/       # 【唯一 LLM 出口】EngineProtocol + ClaudeCliEngine + CodexCliEngine，预留 OpenClawEngine
    skills/       # 【预留】skill 插拔框架：SkillBase 抽象 + registry
    storage/      # StorageProtocol + LocalStorage（MVP 本地路径），未来加 S3/OSS 实现
    tasks/        # 后台任务：归类 worker、任务状态与重试
  tests/
frontend/         # Next.js（App Router）+ TS + Tailwind，用户唯一入口
  app/            # 路由页面：login/chat/documents/admin/users/settings/stats/whatsnew/account
  lib/            # api client（统一走 /api，含 stream SSE）、auth、useAuthGuard
  components/     # NavBar(RBAC 显隐) / MessageBubble / Markdown / FolderTree
                  # / TaskLogPanel / admin(WorkspaceAdmin/SystemSettings/CategoryManager/UserAdmin/PromptsTab/StatsTab)
  next.config.js  # rewrites: /api/* -> 后端 FastAPI（单端口暴露）
infra/
  postgres/
    init.sql          # CREATE EXTENSION
    migrations/       # 001_m1_auth … 037_refresh_tokens，按序应用（backend 启动时 migrate.py 自动幂等执行）
scripts/          # dev.sh / test.sh(独立库 kbagent_test) / lint.sh / e2e.sh
docs/                 # PRD / DESIGN / ROADMAP / WORKFLOW / SECURITY
prompts/              # 分步系统提示词