# 重构进度 更新时间：2026-08-12 ## 已完成：M0 工程基线 - Go 1.26 模块、配置校验、结构化日志和优雅退出。 - PostgreSQL `pgx` 连接池、critical/cache 双 Redis 客户端。 - 独立且带校验和、事务和 advisory lock 的数据库迁移器。 - OpenAI 兼容入口、bootstrap key 鉴权、请求体限制、连接池和 SSE 透传。 - `healthz`、依赖感知 `readyz`、基础 Prometheus 指标。 - PostgreSQL outbox、API Key、Provider 与分区审计表的首版 schema。 - 不包含 MinIO/S3、ClickHouse 的 Docker Compose 基线。 - Art Design Pro v3.0.2 管理端与门户端，已执行官方精简流程并通过生产构建。 - OpenAPI 运行时契约和共享 TypeScript 系统客户端起点。 ## 已完成：M1 身份、Provider 与配置面 已完成： - 管理员、门户用户 schema 和独立 bootstrap 命令。 - 兼容 Python 版本 60 万轮/旧 12 万轮 PBKDF2-SHA256，并在成功登录时升级旧哈希。 - critical Redis 可撤销不透明会话、数据库 active/role 复核、失败次数原子更新和账号锁定。 - `/api/v1/admin/*`、`/api/v1/portal/*` 登录、身份、菜单、退出契约。 - 管理端与门户端 TOTP 配置、二次登录、停用、备用码重置；含临时挑战令牌、时间步原子防重放和备用码一次性消费。 - 两套 Art 登录页已接入动态验证码/备用码，并通过生产构建。 - 数据库 API Key 创建、列表、scope、过期、Redis 共享缓存和即时撤销；明文只显示一次，创建/撤销与 outbox 同事务。 - Art 管理端 API Key 页面、动态菜单入口及生产构建。 - Provider AES-256-GCM 凭据、SSRF 地址校验、revision 和事务 outbox。 - Provider 数据库运行时原子快照、默认/显式路由、能力约束、共享连接池、周期刷新和上一有效版本回退。 - Art 管理端供应商页面及生产后端权限模式。 - Provider 连接测试、模型目录同步、历史模型停用策略和 `provider.models_synced` 事务 outbox。 - Art 管理端连接测试、同步结果和模型目录查看交互。 - 版本化 KEK keyring、历史密钥解密、Provider 凭据事务轮换和管理端轮换入口。 - PostgreSQL 权威 Provider 配置、critical Redis 多实例变更通知、进程内不可变快照与周期兜底刷新。 - 管理员/门户账号管理、内置角色、直接权限字符串、权限感知动态菜单和即时数据库复核。 - bootstrap API Key 显式关闭开关及兼容入口使用量指标。 - 层级部门 CRUD、循环检测、在用停用保护、门户账号部门绑定和部门 outbox。 - OIDC 配置面、加密 Client Secret、Authorization Code + PKCE、RS256/JWKS 校验、自动开户和一次性交换码。 - SAML 配置面、SP metadata、SP-initiated Redirect/POST 流程、SHA-256+ XML 签名断言校验、RelayState/InResponseTo 绑定、断言防重放、自动开户和部门绑定。 - 旧 Python 网关 38 个持久化实体字段字典、实体去向清单、确定性 UUIDv5 生成器和幂等旧 ID 映射表。 - SAML 与 OIDC 均已通过 PostgreSQL + Redis + 本地模拟 IdP 的端到端登录、自动开户、一次性交换和重放拦截测试。 ## 已完成：M2 流量治理与路由 已完成： - API Key 级每分钟请求上限和 UTC 自然月请求配额，`0` 明确表示不限制。 - critical Redis Lua 原子准入；限流返回 `429`/`Retry-After`/`X-RateLimit-*`，配置限制时 Redis 故障失败关闭。 - API Key 限额的 PostgreSQL 权威配置、鉴权缓存传递、Art 管理表单与 OpenAPI 契约。 - PostgreSQL + Redis + 模拟上游端到端测试：RPM=2 精确放行 2 次，月配额=3 精确放行 3 次。 - API Key UTC 自然月 Token 配额：请求前按输入体积与最大输出预算原子预留，响应结束按上游 usage 原子校准。 - OpenAI/Responses/Anthropic 的 JSON 与 SSE usage 增量提取；不缓冲完整流式响应，上游未返回 usage 时按预留预算保守计量。 - Art 管理端展示当月 Token 用量并可即时调整 RPM、月请求和月 Token 配额；更新同时清除共享鉴权缓存并写入 outbox。 - Provider 级响应头超时、有限指数退避和熔断；仅 GET/HEAD 或携带 `Idempotency-Key` 的可重放请求允许重试，所有阈值均可通过环境变量配置。 - PostgreSQL 模型别名/路由规则、事务 outbox、管理 CRUD、Redis 多实例变更通知和进程内不可变路由快照。 - 按 endpoint、API Key、tenant 条件匹配；最高优先级分组内使用请求 ID 做确定性加权选择，显式 Provider 作为候选约束。 - 已登记的模型别名在条件不匹配、规则停用或显式 Provider 不属于候选集时失败关闭，避免把别名透传到默认上游绕过策略。 - 代理在命中规则时改写上游模型并返回 `X-Gateway-Model`；未配置规则时不读取请求体，保持原代理热路径性能。 - Art 管理端模型路由页面，可维护别名、上游模型、Provider、权重、优先级、条件和启停状态。 ## 已完成：M3 审计、usage、内容策略与成本 已完成： - 网关调用的有界异步审计队列、批量 PostgreSQL COPY、失败保留/重试、队列满降级和优雅停机排空。 - 请求 ID、API Key、tenant、Provider、原始/目标模型、协议、HTTP 状态、延迟及输入/输出 Token 采集。 - PostgreSQL 按日 API Key/Provider/模型 usage 聚合，不在请求热路径同步写数据库。 - `audit:read`/`usage:read` 权限、筛选查询 API、Art 管理端审计与用量页面。 - 审计 accepted/dropped/written/flush failures Prometheus 指标。 - 独立 `gateway-outbox-worker`，使用 PostgreSQL `FOR UPDATE SKIP LOCKED` 租约支持多实例并行抢占。 - Redis Lua 原子事件 ID 去重与 Stream 写入，数据库确认丢失后重投不会产生重复 Stream 消息。 - 指数退避、最大尝试次数、死信状态、`outbox:read`/`outbox:manage` 权限、管理 API 与 Art 人工重试页面。 - `event_consumptions` 与业务 handler 共用 PostgreSQL 事务的消费者幂等入口，handler 回滚时消费标记同步回滚。 - 独立 `gateway-maintenance` 周期任务，按 UTC 月预创建审计分区，事务迁移 default 分区数据，并按配置直接丢弃完整过期分区、精确清理边界月和长期 usage。 - 审计维护使用 PostgreSQL advisory lock 与表级事务锁，多副本启动时仍只有一个实例执行；重复运行保持幂等。 - PostgreSQL 内容策略 CRUD、事务 outbox、`content_policy:read/manage` 权限与多实例周期刷新；运行时使用不可变 RE2 编译快照。 - 内容策略支持 `audit`、`block`、`redact`，按 endpoint、模型和 API Key 限定范围；只遍历提示词文本字段，不改写工具 schema、图片/Base64 等非文本载荷。 - 默认敏感信息脱敏策略、阻断响应、`X-Gateway-Content-Redacted` 响应头，以及不包含原始命中值的审计标签。 - Art 管理端内容策略页面，可维护优先级、范围、规则、替换文本和启停状态。 - 带生效/失效时间的模型价格版本，支持 Provider + 精确模型或末尾 `*` 前缀，精确规则优先并使用请求时刻选择版本。 - 输入/输出价格均以“每百万 Token 的微货币单位”精确存储；usage 完成时核算请求成本，审计与按日聚合均保存 `cost_microunits`。 - `pricing:read/manage` 权限、模型价格管理 API/Art 页面，审计与用量页面展示估算成本。 ## 已完成：M4 Prompt、知识、工具、应用编排和通知 - Prompt 分类/模板和只增不改的版本，显式变量声明、必填/默认值校验、历史版本激活、管理端和 API Key 渲染接口。 - PostgreSQL 知识库保存不超过 2 MiB 的提取文本，不依赖 MinIO/S3；段落感知重叠分块，FTS 与中文二元词片混合召回，并通过 `Retriever` 接口隔离未来向量实现。 - 声明式 HTTP 工具、基础 JSON Schema 入参验证、KEK 加密请求头、注册及拨号时 SSRF 校验、禁止重定向、1 MiB 响应上限和工具调用记录。 - AI 应用草稿、引用完整性校验、不可变发布版本和运行记录；应用入口组合 Prompt/RAG/OpenAI 工具调用循环，内部每个模型请求仍走原网关全治理链路。 - 通知通道与可靠投递记录，独立 Worker 消费 outbox，精确/前缀事件订阅、HMAC-SHA256 签名、失败留痕与人工重试。 - 内容策略命中由异步审计批处理在同一事务写入 `content_policy.matched` outbox，不在模型请求热路径同步投递 Webhook，也不包含原始敏感命中值。 - Art Design Pro 管理端新增 Prompt、知识库、工具、应用和通知五个页面，权限与动态菜单均由服务端控制。 - 独立前端多阶段镜像将 Art 管理端生产构建交付给 Nginx，并同源代理管理 API、模型 API、SSE 与健康检查；Compose 可直接启动完整管理面。 ## 已完成：M5 契约、迁移与切换工程 - 通过 Python AST 自动盘点旧源码，确认实际为 201 个路由装饰器，而不是早期估算的 141 个；与 OpenAPI 生成可重复的覆盖/替代/退役/缺口矩阵。 - 可选影子中间件只复制确定性采样的非流式 JSON POST，使用独立影子 Key，不转发生产凭据；异步比较状态码和 JSON 结构签名并输出 Prometheus 指标。 - 独立 `gateway-loadtest` 支持并发、时长、超时、错误率和 p95 阈值，输出机器可读 JSON 并以退出码阻断不达标发布。 - 原子 Nginx upstream 切换脚本在目标探活、`nginx -t` 和 reload 任一步失败时恢复备份；提供明确的回退触发条件与演练手册。 - 旧 SQLite 只读 JSONL 导出、逐记录 SHA-256、确定性 UUIDv5 和 PostgreSQL 不可变暂存管道已完成；默认排除敏感列，相同快照幂等，旧记录变化失败关闭。 - 201 条旧路由已全部形成明确决策：85 条同契约覆盖、112 条由新契约替代、4 条基于安全或架构 ADR 退役、未决缺口 0；OpenAPI 0.10.0 覆盖全部 146 条 Go 字面量路由。 ## 已完成：M6 门户工作台与扩展治理 - 门户资产目录、Prompt 查看/搜索/收藏、个人审计/Token/成本统计、接入说明和模型访问申请；所有列表按登录用户与部门范围服务端过滤。 - 管理端模型申请审批、事实核验 Provider 设置、作用域策略与核验事件页面；事实核验复用 Provider 加密凭据，不重复保存 API Key/Base URL。 - 已发布应用的门户单轮入口和服务端托管会话；运行凭证使用独立 AEAD purpose 加密，明文不返回浏览器。 - 会话串行租约避免并发回答交错，用户/助手消息以不可变顺序和 SHA-256 哈希链保存，重放前验证完整性，最多 200 条消息。 - 应用目录/资产依赖分析、历史版本回滚、知识文档重新分块、Prompt 详情、运行时快照刷新、系统信息和 24 小时监控汇总。 - Art Design Pro 管理端新增模型治理页面；门户端新增资产目录、Prompt 广场、个人用量与模型权限四个生产页面。 - Compose 同时交付 API、管理端 `8081` 和门户端 `8082`；同一前端 Dockerfile 通过受限 build arg 构建两套独立 SPA。 工程实现与本地生产等价验证已关闭。正式上线仍是外部发布门禁：拿到实际旧数据库脱敏快照和旧密钥迁移授权后执行领域转换，并在真实新旧双系统与生产等价流量下完成影子观察、容量验收及切换/回退演练；这些动作不会在缺少生产数据和授权时伪造为已执行。 ## 已完成：M8 基础设施层（P1 对象存储与文件管理） - 自托管 MinIO 对象存储入基线：`internal/platform/storage`（minio-go 适配层）剥离 scheme 推导 Secure，领域层不直接依赖 S3 客户端；`S3_*` 配置默认值 + Validate（1–512 MiB 上限、endpoint 无路径）。迁移 `000023` 建 `gateway.file_objects`（uuid/object_key 唯一/sha256/scope/owner 校验 + 部分索引）。 - 文件上传/下载全部经网关代理（MinIO 不暴露主机端口）：流式 multipart 上传（`http.MaxBytesReader` + `LimitReader` 超限即拒），`PutObject` 成功后才插元数据行、失败回滚对象；下载 io.Copy 流式 + RFC 5987 `filename*`；删除先删行再 best-effort 清对象（避免孤儿阻塞删除）。 - `FileService` 个人/系统双范围：admin 文件管理（`file:read|manage` RBAC + 管理端文件管理页）与 portal 个人文件仓（严格归属隔离，跨用户读返回 404）。 - Compose（dev + production）新增 `minio` 服务与 `minio-data` 卷；nginx `client_max_body_size` 32m→256m 盖过 128 MiB 上传上限；`.env.example` / `production.env.example` 补 `S3_*`。 - 端到端验证：上传→列表→下载往返一致→删除后桶无孤儿；admin 读 portal 文件 404；`TestFileObjectLifecycle` 集成测试连真实 MinIO+PostgreSQL 通过；`go build ./...`、`go vet ./...`、全量单测通过。 - 管理端"文件管理"与门户端"文件仓库"菜单由服务端动态菜单下发。 ## 已完成：M8 基础设施层（P2 向量化与语义检索） - PostgreSQL 换 `pgvector/pgvector:pg17` 镜像（数据卷兼容，先备份再切换）；迁移 `000024` `CREATE EXTENSION vector`、`knowledge_chunks.embedding vector(1024)` 列 + HNSW 余弦索引，并把 `retrieval_mode` CHECK 放宽为 `('postgres_fts','vector','hybrid')` 三态。 - 本地 Ollama（`bge-m3`，1024 维）生成嵌入，Compose 新增 `ollama` 服务与 `ollama-models` 卷；`OllamaEmbedder` 批量调 `/api/embed`，首见 404 惰性 `/api/pull` 重试一次，按批校验维度，超时 `EMBEDDING_TIMEOUT`；`EMBEDDINGS_ENABLED=false` 可整体关闭。 - `SemanticRetriever`（`embedding <=> $1::vector` 余弦距离 + `embedding IS NOT NULL` 过滤）与 `HybridRetriever`（FTS + 语义按 chunk 去重融合）实现；`NewRetriever(service, embedder)` 按知识库 `retrieval_mode` 分发，embedder 为 nil 时自动回退纯 FTS（不因缺少 Ollama 而报错）。 - 文档入库/重新分块时在 vector/hybrid 模式下同步批量计算向量（每文档一次 `/api/embed` 收数组）；Ollama 故障时优雅降级：文档照常入库、embedding 置 NULL，并在事务内发 `knowledge_document.embedding_failed` 事件。 - 踩坑并修复：pgx v5 `CopyFrom` 对未知 OID（vector）列走二进制编码，字面量随 COPY 上传会被 `vector_recv` 误读为维度数而报 `vector cannot have more than 16000 dimensions`；改为 COPY 仅基础列，随后在同一事务内用 `UPDATE ... FROM unnest($1::uuid[], $2::text[])` 批量回填向量，避免 2 MiB 文档上千条逐条 INSERT。 - 知识库列表新增 `vectorized_chunk_count`（`count(c.embedding)`），管理端展示"已向量化切片/总切片"覆盖率；创建/编辑知识库可三态选择检索模式，未向量化分块需重新处理才被语义召回。 - `EMBEDDINGS_*` 配置（`OLLAMA_BASE_URL` 默认 `http://ollama:11434`、`EMBEDDING_MODEL` bge-m3、`EMBEDDING_DIM` 须与 `vector(1024)` 一致、批大小、超时）写入两个 `.env.example` 与 compose anchor。 - 单测 `embedder_test.go`/`retrievers_test.go`（httptest 假 Ollama：批量切分、维度不符、404→pull→重试、降级分发）与集成 `TestKnowledgeVectorLifecycle`（真 pgvector+Ollama：导入即向量化、语义命中、embedder 失败时入库 + `embedding_failed` 事件）全部通过；`go build ./...`、`go vet ./...` 通过。 ## 已完成：M8 基础设施层（P3 定时任务调度器） - 迁移 `000026` 建 `gateway.scheduled_tasks` 与 `gateway.scheduled_task_runs`：任务配置和执行历史以 PostgreSQL 为权威源；计划触发使用唯一键防重复入队，pending/running/due 部分索引支撑大队列扫描。 - 独立 `gateway-scheduler` worker 解析标准五字段 Cron 与 IANA 时区；到期任务和执行队列均使用 `FOR UPDATE SKIP LOCKED`，支持多副本并发、过期计划合并、执行租约超时回收、有限重试和最终失败事件。 - 任务可调用已发布应用或数字员工；数字员工任务可在员工已有绑定内进一步限制 Skills/MCP 子集。执行 API Key 使用 `scheduled-task-api-key` 独立 AEAD purpose 加密，明文不回显。 - 支持提示词、变量、会话 ID（保留最近五次成功回答作为上下文）和指定通知通道；完成/最终失败写入 outbox，通知 worker 可只投递指定 Webhook，同时物化为创建者站内信。 - 管理 API/页面提供创建、编辑、启停、立即执行、删除和执行历史；RBAC 新增 `scheduled_task:read/manage`，菜单由服务端动态下发。 - `TestSchedulerPostgreSQLLifecycle` 连真实 PostgreSQL + 模拟网关验证：加密凭据解密、手动与计划入队、只执行一次、响应落库、完成事件和下一运行时间推进；Cron 与数字员工绑定子集另有单元测试。 ## 已完成：M8 基础设施层（P4 站内消息） - 迁移 `000025` 建 `gateway.inbox_messages`：一条消息一个收件人（admin/portal 跨身份表、不设 FK），sender 广播逐收件人落库；部分唯一索引 `(source_event_id, recipient_kind, recipient_user_id) WHERE source_event_id IS NOT NULL`（NULLS NOT DISTINCT）实现事件重放幂等；`(recipient_kind, recipient_user_id, created_at DESC)` 收件箱索引 + 未读部分索引。 - `InboxService`：`inboxPlan` 纯函数把 outbox 事件类型映射为站内信草稿（`model_access.requested`→通知全部启用管理员、`model_access.decided`→回执申请用户、`marketplace.installed`→通知安装用户、`knowledge_document.ready/reprocessed/embedding_failed`→通知执行管理员、`scheduled_task.completed/failed`→通知创建者）；收件人解析区分直取 payload / 查 `model_access_requests` / 全部启用管理员。未读数以 PostgreSQL 为权威源，Redis 仅 PUBLISH 提示（为未来 SSE 预留）。 - 通知 worker 在同一消费循环内物化站内消息（`dispatcher.SetInbox`，为 nil 时不落库、不影响 webhook）；物化失败与 webhook 同语义留在 pending 由 reclaim 重试，幂等键保证重放不重复。 - admin HTTP：消息中心（`scope=mine/broadcasts`）、未读数、向 portal（可按部门过滤）或全部 admin 广播、单条已读、全部已读；RBAC 新增 `inbox:read`/`inbox:manage`（auditor 仅读），动态菜单下发"站内消息"入口。portal HTTP：个人收件箱、未读徽标（header bar 30s 轮询）、已读/全部已读。 - 前端：管理端 `gateway/inbox`（我的消息/已发送广播双 Tab + 广播对话框）、门户端 `portal/inbox`；门户顶栏 mail 铃铛 + 未读角标。 - 集成测试 `TestInboxMaterializeAndBroadcast` 连真实库验证：事件物化→未读计数→重放幂等→已读回执→管理员广播→broadcasts 全局列表→全部已读。 - 踩坑并修复：集成测试清理 DELETE 中同一参数同时比较 uuid 列与 jsonb text 提取，PG 无法推断类型报 `text = uuid`（SQLSTATE 42883）且 `_, _` 吞错导致重跑残留累加——改为显式 `::uuid`/`::text` 并补全按收件人删除。 ## 已完成：M9 智能体与可观测（P1 LLM Trace） - 迁移 `000027` 建 `gateway.agent_traces` 与 `gateway.agent_trace_spans`，并把 `trace_id` 关联到应用/数字员工运行记录；Trace 类型区分 application/digital_employee，span 类型覆盖 model/retrieval/tool。 - 应用和数字员工运行链路接入 Trace：每轮受治理模型调用记录 Provider、模型、HTTP 状态、Token、轮次和耗时；知识库检索记录命中数；工具/MCP 执行记录名称、轮次、调用 ID、状态、耗时和错误。调用正文、工具参数和模型回答不写入 Trace。 - Trace 写入失败是 best-effort，不改变模型调用响应；Trace 完成时同步回填运行计数、最终状态和错误，保留现有 `application_runs`/`digital_employee_runs` 查询兼容性。 - admin API：`/api/v1/admin/traces` 列表过滤（时间、目标、状态、Request ID）与 `/traces/{id}` span 详情；新增 `trace:read` 权限，operator/auditor 可读，动态菜单下发 LLM Trace 页面。 - 管理端新增 LLM Trace 时间线页面，展示模型/检索/工具链路、耗时、Token、Provider 和失败原因，明确提示不保存正文。 - 验证：`TestTracePostgreSQLLifecycle` 验证存储生命周期；`TestWorkbenchPostgreSQLLifecycle` 验证真实应用运行自动产生模型/检索 Trace。 ## 已完成：M9 智能体与可观测（P2 智能体会话） - 复用 Trace 元数据聚合统一智能体会话中心：有 `X-Gateway-Conversation-ID` 的请求按会话聚合，无状态请求按 `request:` 回退，区分 application/digital_employee。 - admin API：`/api/v1/admin/agent-sessions` 支持时间、类型、目标编码、会话 ID 和数量过滤，返回 Trace 数、最近 Trace、状态、模型/工具/检索累计计数与最近活动时间；不读取或返回对话正文。 - 管理端新增“智能体会话”页面，可查看会话聚合指标并打开最近 Trace 时间线；复用 `trace:read` 权限和动态菜单。 - 验证：`TestTracePostgreSQLLifecycle` 增加会话聚合查询断言，admin 前端生产构建通过。 ## 已完成：M9 智能体与可观测（P3 节点注册与心跳） - 迁移 `000028` 新增 `gateway.agent_nodes`：节点编码、节点类型、Endpoint、公共/私有节点池、能力/元数据、令牌哈希和最后心跳信息；令牌只在登记或轮换响应中返回一次。 - admin API：节点列表、登记、编辑、删除和令牌轮换；`agent_node:read/manage` 权限分别授予 auditor/operator，管理端新增节点监控页面。 - 节点 API：`POST /api/v1/agent/nodes/{code}/heartbeat` 校验 `X-Agent-Token`，刷新版本、能力、元数据、错误和来源 IP；根据 90 秒心跳窗口派生 pending/online/offline/disabled 状态。 - 当前 P3 明确不假装覆盖远程裸机安装、节点任务下发和真实执行路由；公共/私有池字段与能力元数据为下一阶段路由实现保留契约。 - 验证：`TestAgentNodePostgreSQLLifecycle` 覆盖登记、编辑、心跳、令牌轮换和旧令牌失效。 ## 已完成：M9 智能体与可观测（P4 节点池路由预览） - admin API：`POST /api/v1/admin/agent-nodes/route-preview` 按公有/私有池、池编码、能力标签和 90 秒在线窗口筛选候选节点。 - 选路使用 `sha256(request_key + "\x00" + node_id)` 的稳定排序，同一个 request key 在候选集合不变时会得到同一首选节点；响应同时返回候选列表、选路策略和无节点/无能力原因。 - 管理端节点页面新增“路由预览”对话框，明确展示首选节点和候选顺序；该接口只读，不访问节点 Endpoint、不创建任务，也不代表远程执行路由已经完成。 - 增加纯函数筛选/稳定性测试，并在 `TestAgentNodePostgreSQLLifecycle` 中覆盖真实在线节点的能力路由预览。