[NEDONION]

参照 lobster0 的文档组织方式，把 docs 从「6 篇平铺 + 7 条死链」补成 19 篇分层文档，10215 行，链接零失效。

目录重组

原来全平铺在 docs/ 下，改为按主题分层：

docs/
├── architecture/   系统架构与技术底座
├── modules/        各业务模块
├── reference/      API 与数据库参考
├── operations/     部署、性能、安全、排查记录
├── development/    本地开发
└── assets/         配图

文件名去掉冗余后缀（RAG_MODULE.md → modules/rag.md），目录层级本身已表达分类。移动一律用 git mv 保留历史。

新增文档（11 篇）

文档	覆盖
modules/llm.md	服务商、协议适配、高可用降级链、Token 策略
modules/mcp-tool.md	工具上架状态机、容器隔离、MCP Gateway
modules/conversation.md	消息处理器体系、完整对话链路、Agent 工作流
modules/user-auth.md	两条鉴权链路、登录开关、用户设置
modules/trace.md	两级数据模型、执行阶段、事件驱动采集
modules/task.md	工作流任务 vs 定时任务、延迟队列
architecture/infrastructure.md	19 个技术子包全景
operations/deployment.md	拓扑、配额、CI/CD、回滚、国内网络实测
operations/performance.md	线程池、超时分级、首字延迟、扩容阻塞点
operations/security.md	待修复问题清单、隔离、密钥、CI 安全
development/local-setup.md	环境、运行、风格、提交、常见问题

全部基于源码实际结构撰写，每篇含「💬 一句话人话」导读与「已知坑」章节。

🔴 撰写过程中发现的高危安全问题

服务商 API Key 的加密密钥硬编码在公开源码中，实际等同未加密。

ProviderConfigConverter 加密含 API Key 的配置落库，调用的 ValidationUtils.EncryptUtils 使用 SECRET_KEY = "1234567890123456"，且 Cipher.getInstance("AES") 默认 ECB 模式。仓库公开 ⇒ 密钥公开 ⇒ 任何拿到数据库内容的人都能解出全部用户的服务商密钥。

详见 docs/architecture/infrastructure.md 9.1 与 docs/operations/security.md P0，已给出修复方向。本 PR 只做记录，修复需单独处理。

其他发现

• ConfigEncryptor 是硬编码密钥的死代码（零调用），建议删除
• ProviderConfigConverter.getNullableResult(ResultSet, int) 未实现直接返回 null
• ToolStatus.fromCode() 返回 null 而同项目其他枚举抛异常
• conversation 模块有三个同名 Agent、两个同名 ChatContext
• 验证码与定时任务均为内存实现，构成水平扩容的两个硬阻塞点
• 仓库无任何测试代码

修正的事实错误

初始化 SQL 应用 docs/sql/01_init.sql（1129 行，35 张表），而非 deploy/init-db.sql/init.sql（73 行，仅建扩展，建表语句已注释）。按后者操作会得到一个没有表的库。README 与本地开发指南均已更正。

验证

• 链接校验脚本：167 条全部有效，0 失效（原 INDEX.md 有 7 条死链）
• 无代码改动，不影响构建与运行

🤖 Generated with Claude Code