add-coder 0.1.0

package/templates/core/reports/code-review-fix-verification-report.md

@@ -0,0 +1,505 @@
+# {{projectName}} Code Review 修复验证对照报告
+
+> 生成时间：2026-06-30（第十一次验证，修正 #20a）  
+> 源报告：`code-review-combined-report.md`（24 个问题）  
+> 验证方式：逐文件读取当前代码实际状态，精确对比
+
+---
+
+## 总览
+
+| 状态 | 数量 | 占比 |
+|------|------|------|
+| ✅ 已修复 | 12 | 50.0% |
+| ⚠️ 部分修复 | 2 | 8.3% |
+| ❌ 仍存在 | 10 | 41.7% |
+| **总计** | **24** | **100%** |
+
+---
+
+## 逐条对照
+
+---
+
+### 一、安全风险（2 项）
+
+#### #1 JWT 硬编码默认密钥 → ✅ 已修复
+
+- **文件**: [src/lib/auth.ts:3-10](file://{{projectRoot}}/src/lib/auth.ts#L3-L10)
+- **原问题**:
+
+  ```ts
+  const JWT_SECRET = process.env.JWT_SECRET || "dev-secret-key"
+  ```
+  生产环境漏配环境变量将使用可预测的弱密钥
+
+- **当前代码**:
+
+  ```ts
+  const JWT_SECRET = (() => {
+    const secret = process.env.JWT_SECRET
+    if (!secret) {
+      if (process.env.NODE_ENV === "production") {
+        throw new Error("FATAL: JWT_SECRET must be set in production environment")
+      }
+      return "dev-secret-key"
+    }
+    return secret
+  })()
+  ```
+  生产环境缺失时直接拒绝启动，开发环境使用 `"dev-secret-key"`
+
+- **判定**: ✅ 已修复
+
+---
+
+#### #2 QWeather JWT 签名是占位符 → ✅ 已修复
+
+- **文件**: [src/lib/farm-server-client.ts:68-86](file://{{projectRoot}}/src/lib/farm-server-client.ts#L68-L86)
+- **原问题**: EdDSA 签名写死为 `"PLACEHOLDER_SIGNATURE"`，生产环境会导致认证失败
+- **当前代码**: 增加占位符检测逻辑，检测到占位符时：
+  1. 记录审计日志（`fsClientAudit` + `writeFsClientAudit`）
+  2. `throw new Error("QWeather EdDSA signing not implemented — cannot use placeholder in production")`
+- **判定**: ✅ 已修复
+
+---
+
+### 二、代码重复 / 架构问题（7 项）
+
+#### #3 LLM 模块重复（`llm.ts` vs `llm/index.ts`） → ✅ 已修复
+
+- **原问题**: 旧版 `src/lib/llm.ts` 与新版 `src/lib/llm/index.ts` 并存，旧文件成死代码
+- **当前状态**: `src/lib/llm.ts` 文件不存在，仅保留 `src/lib/llm/index.ts`
+- **判定**: ✅ 已修复
+
+---
+
+#### #4 Chroma 客户端重复（`chroma.ts` vs `chroma-client.ts`） → ✅ 已修复
+
+- **原问题**: 两个 ChromaDB 客户端实现，一个用 `chromadb` npm 包，一个用原生 HTTP fetch，功能重叠
+- **当前状态**: `src/lib/chroma.ts` 已删除，仅保留 `src/lib/chroma-client.ts`
+- **判定**: ✅ 已修复
+
+---
+
+#### #5 `extractTokenFromRequest` 重复定义 → ✅ 已修复
+
+- **原问题**: 同一函数在 `auth.ts` 和 `auth-gateway.ts` 中各定义一次
+- **当前代码** ([src/caijuehub/strategies/auth-gateway.ts:15](file://{{projectRoot}}/src/caijuehub/strategies/auth-gateway.ts#L15)):
+
+  ```ts
+  import { getUserFromRequest, extractTokenFromRequest, type JWTPayload } from "@/lib/auth"
+  ```
+  已改为从 `auth.ts` 导入，`auth-gateway.ts` 中不再有 `function extractTokenFromRequest` 的定义
+
+- **判定**: ✅ 已修复
+
+---
+
+#### #6 8+ 个日志模块共享相同代码模式 → ❌ 仍存在
+
+- **当前状态**: 8 个日志模块各自独立，每个都有重复的 `ensureLogDir()` / `writeToFile()` 实现：
+
+  | 文件 | ensureLogDir + writeToFile |
+  |------|---------------------------|
+  | `log/audit.ts`（新增，替代 agent-audit-logger.ts） | 重复 |
+  | `agent-gateway-dev-logger.ts` | 重复 |
+  | `audit-logger.ts` | 重复 |
+  | `chat-persistence-logger.ts` | 重复 |
+  | `chat-stats-logger.ts` | 重复 |
+  | `model-config-logger.ts` | 重复 |
+  | `stream-bus-logger.ts` | 重复 |
+  | `stream-chat-logger.ts` | 重复 |
+
+  共 67 处 `ensureLogDir`/`writeToFile` 调用分散在 8 个文件中，未提取公共模块。注意：`agent-audit-logger.ts` 已删除，其审计日志逻辑迁移至 `src/lib/log/audit.ts`，但 `ensureLogDir`/`writeToFile` 仍在 `audit.ts` 中重复实现
+
+- **判定**: ❌ 仍存在
+
+---
+
+#### #7 `agent-gateway-dev-logger.ts` 与 `agent-gateway-audit.ts` 行为不一致 → ❌ 仍存在
+
+- **文件**: [src/lib/agent-gateway-dev-logger.ts](file://{{projectRoot}}/src/lib/agent-gateway-dev-logger.ts) / [src/lib/agent-gateway-audit.ts](file://{{projectRoot}}/src/lib/agent-gateway-audit.ts)
+- **当前状态**: 两个模块仍独立存在
+  - `agent-gateway-dev-logger.ts`：仅在 `NODE_ENV=development` 时输出，写文件日志
+  - `agent-gateway-audit.ts`：始终输出，写 AuditLog 表（已改用 `import { writeAuditLog } from "@/lib/log"`）
+  - 功能重叠但行为不一致，类型定义也各自独立
+- **判定**: ❌ 仍存在
+
+---
+
+#### #8 `audit-log.ts` 内存存储审计日志 → ❌ 仍存在
+
+- **文件**: [src/services/audit-log.ts:33](file://{{projectRoot}}/src/services/audit-log.ts#L33)
+- **当前代码**:
+
+  ```ts
+  const auditLogs: AuditLogEntry[] = []
+
+  export async function createAuditLog(entry) {
+    auditLogs.push(log)
+    // 仅在开发环境 console.log
+  }
+  ```
+  仍只存内存数组，进程重启全部丢失。对比 `src/lib/log/audit.ts` 已用 Prisma DB 持久化
+
+- **判定**: ❌ 仍存在
+
+---
+
+#### #9 `agents/index.ts` 职责过大 → ❌ 仍存在
+
+- **文件**: [src/agents/index.ts](file://{{projectRoot}}/src/agents/index.ts)
+- **当前状态**: 500 行（原报告 468 行），仍混含 StateGraph、ToolNode 包装器、审计包装器、`runAgent`/`streamAgent` 入口、Tracer 管理、`buildPartialState`，未拆分
+- **判定**: ❌ 仍存在
+
+---
+
+### 三、健壮性 / 边界条件（5 项）
+
+#### #10 LLM 单例竞态条件 → ❌ 仍存在
+
+- **文件**: [src/lib/llm/index.ts:225-249](file://{{projectRoot}}/src/lib/llm/index.ts#L225-L249)
+- **当前代码**:
+
+  ```ts
+  export function setLLMConfig(config) {
+    runtimeConfigOverride = { ... }
+    resetLLM()  // 将 llmInstance 置为 null
+    // ...
+  }
+  ```
+  并发请求携带不同 `modelConfig` 时，A 请求的 `resetLLM()` 可能影响 B 请求正在使用的 `llmInstance`，竞态风险未消除
+
+- **判定**: ❌ 仍存在
+
+---
+
+#### #11 `activeTracers` Map 潜在内存泄漏 → ✅ 已修复
+
+- **文件**: [src/agents/index.ts:239-257](file://{{projectRoot}}/src/agents/index.ts#L239-L257)
+- **当前代码**:
+
+  ```ts
+  const tracerCreateTimes = new Map<string, number>()
+  const TRACER_TTL_MS = 30 * 60 * 1000  // 30 分钟 TTL
+
+  function cleanupExpiredTracers(): void {
+    const now = Date.now()
+    for (const [traceId, createTime] of tracerCreateTimes) {
+      if (now - createTime > TRACER_TTL_MS) {
+        activeTracers.delete(traceId)
+        tracerCreateTimes.delete(traceId)
+      }
+    }
+  }
+  ```
+  `cleanupExpiredTracers()` 在 `startChainTrace()` 和 `wrapNodeWithAudit()` 中均被调用，Tracer 30 分钟后自动过期清理
+
+- **判定**: ✅ 已修复
+
+---
+
+#### #12 审计日志静默吞错 → ✅ 已修复
+
+- **原文件**: `src/lib/agent-audit-logger.ts`（已删除）
+- **新文件**: [src/lib/log/audit.ts:193-237](file://{{projectRoot}}/src/lib/log/audit.ts#L193-L237)
+- **原问题**: catch 只做 `console.error`，DB 不可用时所有审计记录静默丢失
+- **当前代码**: 审计日志模块已重构为 `src/lib/log/` 目录结构：
+
+  ```ts
+  } catch (error) {
+    auditLogWriteFailCount++
+    const isAlert = auditLogWriteFailCount % AUDIT_LOG_FAIL_ALERT_INTERVAL === 0  // 每 100 次
+
+    // 三通道输出：console + file（agentAudit 写 file）
+    agentAudit("AUDIT_LOG_WRITE_FAIL", ...)
+
+    // 外部告警通道：多渠道路由（企微 / 飞书 / 钉钉）
+    if (isAlert) {
+      void sendAlert({
+        title: "{{projectName}} 审计日志 DB 写入异常",
+        level: "error",
+        content: `**累计失败次数**：${auditLogWriteFailCount} 次\n...`,
+      })
+    }
+  }
+  ```
+
+  已完整实现，且比原版更强：
+  - 失败计数器 `auditLogWriteFailCount`（可追踪丢失量）
+  - 每 100 次失败触发告警
+  - 三通道输出：console + file + agentAudit
+  - 多渠道路由告警：
+    - `src/lib/log/notify/control.ts` — 告警控制中心
+    - `src/lib/log/notify/channels/wecom.ts` — 企微群机器人
+    - `src/lib/log/notify/channels/feishu.ts` — 飞书群机器人
+    - `src/lib/log/notify/channels/dingtalk.ts` — 钉钉群机器人
+  - 旧 `wecom-notify.ts` 已删除，升级为多通道 `sendAlert`
+
+- **判定**: ✅ 已修复
+
+---
+
+#### #13 缺少请求体运行时校验 → ❌ 仍存在
+
+- **文件**: [src/app/api/agent/chat/route.ts:20](file://{{projectRoot}}/src/app/api/agent/chat/route.ts#L20)
+- **当前代码**:
+
+  ```ts
+  const body: ChatRequest & { intent?: string; userId?: string } = await request.json()
+  ```
+  直接做类型断言，无 Zod 等运行时校验，格式错误的请求体会在深层抛出不友好的异常
+
+- **判定**: ❌ 仍存在
+
+---
+
+#### #14 Model config 使用 `require()` 动态加载 → ❌ 仍存在
+
+- **文件**: [src/lib/llm/index.ts:245-246](file://{{projectRoot}}/src/lib/llm/index.ts#L245-L246)
+- **当前代码**:
+
+  ```ts
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { modelConfigAudit } = require("@/lib/model-config-logger")
+  ```
+  仍使用 `require()` 动态加载，ESM 环境下可能不稳定
+
+- **判定**: ❌ 仍存在
+
+---
+
+### 四、代码整洁（7 项）
+
+#### #15 大量 `as any` / `as unknown as` 类型断言 → ⚠️ 部分修复
+
+- **原问题**: 约 119 处 `any` 使用
+- **当前状态**: 66 处（-44.5%），分布在 28 个文件中
+- **判定**: ⚠️ 部分修复 — 数量显著减少，但仍存在较多
+
+---
+
+#### #16 `knowledge-indexer.ts` 遗留调试日志 → ❌ 仍存在
+
+- **文件**: [src/services/knowledge-indexer.ts:568-576](file://{{projectRoot}}/src/services/knowledge-indexer.ts#L568-L576)
+- **当前代码**:
+
+  ```ts
+  console.log(`[RAG-DEBUG] 开始搜索: query="..."`)
+  console.log(`[RAG-DEBUG] 嵌入配置: provider=...`)
+  console.log(`[RAG-DEBUG] 查询嵌入完成: 维度=...`)
+  ```
+  `[RAG-DEBUG]` 前缀的 `console.log` 仍存在，生产环境也会输出
+
+- **判定**: ❌ 仍存在
+
+---
+
+#### #17 未完成的 TODO → ❌ 仍存在
+
+- **文件**: [src/agents/policy-update-loop.ts:149](file://{{projectRoot}}/src/agents/policy-update-loop.ts#L149)
+- **当前代码**:
+
+  ```ts
+  // TODO: 根据 pathMetrics 定制提示语——第 7 轮设计 reserve 但未实现
+  // if (pathMetrics.dominantAction === "relax_evidence_filter") { ... }
+  // else if (pathMetrics.dominantAction === "activate_expert") { ... }
+  const hintText = "信息可能存在缺口，建议扩大检索范围并交叉验证多源数据"
+  ```
+
+- **判定**: ❌ 仍存在
+
+---
+
+#### #18 `AgentAuditPhase` 类型过于庞大 → ✅ 已修复
+
+- **原文件**: `src/lib/agent-audit-logger.ts`（已删除）
+- **新文件**: [src/lib/log/phase.ts:12-211](file://{{projectRoot}}/src/lib/log/phase.ts#L12-L211)
+- **当前状态**: 已从 117 个成员的扁平联合类型，拆分为 **11 个业务域子类型**：
+
+  | 子类型 | 业务域 | 成员数 |
+  |--------|--------|--------|
+  | `ChatPhase` | 会话生命周期 | ~16 |
+  | `NodePhase` | 图节点生命周期 | 7 |
+  | `RetrievalPhase` | 检索与 RAG | ~23 |
+  | `ReportPhase` | 报告生成 | 4 |
+  | `OSKernelPhase` | OS Kernel 管线 | 8 |
+  | `ReasoningPhase` | 推理节点 | 7 |
+  | `DisciplinePhase` | 知识分类体系 | 8 |
+  | `StreamingPhase` | 流式追踪 | 6 |
+  | `H5APIPhase` | H5 REST API | 14 |
+  | `InfraPhase` | 基础设施 | ~29 |
+  | `ACAPhase` | ACA Graph | 4 |
+
+  ```ts
+  export type AgentAuditPhase =
+    | ChatPhase
+    | NodePhase
+    | RetrievalPhase
+    | ReportPhase
+    | OSKernelPhase
+    | ReasoningPhase
+    | DisciplinePhase
+    | StreamingPhase
+    | H5APIPhase
+    | InfraPhase
+    | ACAPhase
+  ```
+
+  每个子类型不超过 20 个成员，新增 Phase 只需定位到对应域即可
+
+- **判定**: ✅ 已修复
+
+---
+
+#### #19 脚本目录过于庞大（60+ 文件） → ❌ 仍存在
+
+- **路径**: `scripts/`
+- **当前状态**: 64 个文件，含一次性迁移脚本（`backfill-projectId.ts`、`fix-knowledge-data.js`、`restore-from-dump.js`、`restore-docs.js` 等）和 `.bat`/`.sh` 双份，未归档
+- **判定**: ❌ 仍存在
+
+---
+
+#### #20 Prisma 多文件 Schema 注释与实际路径不一致 → ✅ 已修复
+
+- **文件**: [prisma/schema.prisma:10-17](file://{{projectRoot}}/prisma/schema.prisma#L10-L17)
+- **当前代码**:
+
+  ```
+  // prisma/
+  //   ├── schema.prisma   — 入口（datasource + generator）
+  //   ├── main.prisma     — 现有模型（User/Chat/RAG/Knowledge/Seed 等）
+  //   └── nongqing.prisma — 农情报告域（ProductionPlan/GrowthStage/FarmTask）
+  ```
+  注释已修正为实际路径
+
+- **判定**: ✅ 已修复
+
+---
+
+#### #21 项目中大量 `console.log` → ⚠️ 部分修复
+
+- **原问题**: 842+ 处，散落在 100+ 个文件中
+- **当前状态**: 410 处（-51.3%），分布在 87 个文件中
+- **判定**: ⚠️ 部分修复 — 数量大幅减少，但仍存在大量直接使用
+
+---
+
+### 五、基础设施 / 运维（2 项）
+
+#### #22 Chroma 端口未绑定 localhost → ✅ 已修复
+
+- **文件**: [docker-compose.yml:50](file://{{projectRoot}}/docker-compose.yml#L50)
+- **原问题**: Chroma 端口映射为 `"8000:8000"`，没有绑定到 `127.0.0.1`，公网部署时暴露在外
+- **当前代码**:
+
+  ```yaml
+  chromadb:
+    ports:
+      - "127.0.0.1:8000:8000"
+  ```
+  已改为绑定 `127.0.0.1`，与 PostgreSQL（`"127.0.0.1:5433:5432"`）保持一致
+
+- **判定**: ✅ 已修复
+
+---
+
+#### #23 Docker Compose 资源限制被注释 → ❌ 仍存在
+
+- **文件**: [docker-compose.yml:30-36](file://{{projectRoot}}/docker-compose.yml#L30-L36) / [docker-compose.yml:60-67](file://{{projectRoot}}/docker-compose.yml#L60-L67)
+- **当前代码**: PostgreSQL 和 Chroma 的 `deploy.resources` 全部仍被注释：
+
+  ```yaml
+  # deploy:
+  #   resources:
+  #     limits:
+  #       memory: 2G
+  #       cpus: '1'
+  #     reservations:
+  #       memory: 512M
+  ```
+
+- **判定**: ❌ 仍存在
+
+---
+
+### 六、附加发现
+
+#### #20a `prisma/dev.db` SQLite 文件 → ✅ 已修复
+
+- **文件**: `prisma/dev.db`
+- **原问题**: Schema 注释已修正为 PostgreSQL，但 `dev.db` SQLite 文件未清理，说明开发环境曾混用 SQLite 和 PostgreSQL
+- **当前状态**: `prisma/dev.db` 文件已不存在，已清理
+- **判定**: ✅ 已修复
+
+---
+
+## 状态汇总表
+
+| # | 分类 | 问题 | 当前文件 | 状态 |
+|---|------|------|------|------|
+| 1 | 安全 | JWT 硬编码默认密钥 | auth.ts | ✅ 已修复 |
+| 2 | 安全 | QWeather JWT 占位签名 | farm-server-client.ts | ✅ 已修复 |
+| 3 | 代码重复 | LLM 模块重复 | llm.ts（已删除） | ✅ 已修复 |
+| 4 | 代码重复 | Chroma 客户端重复 | chroma.ts（已删除） | ✅ 已修复 |
+| 5 | 代码重复 | extractTokenFromRequest 重复 | auth-gateway.ts | ✅ 已修复 |
+| 6 | 代码重复 | 8 个日志模块重复 ensureLogDir | 8 个 logger 文件 | ❌ 仍存在 |
+| 7 | 代码重复 | gateway-dev-logger vs gateway-audit | 2 个 gateway 文件 | ❌ 仍存在 |
+| 8 | 代码重复 | audit-log 内存存储 | services/audit-log.ts | ❌ 仍存在 |
+| 9 | 代码重复 | agents/index.ts 职责过大 | agents/index.ts | ❌ 仍存在 |
+| 10 | 健壮性 | LLM 单例竞态条件 | llm/index.ts | ❌ 仍存在 |
+| 11 | 健壮性 | activeTracers 内存泄漏 | agents/index.ts | ✅ 已修复 |
+| 12 | 健壮性 | 审计日志静默吞错 | log/audit.ts（重构后） | ✅ 已修复 |
+| 13 | 健壮性 | 缺少请求体运行时校验 | agent/chat/route.ts | ❌ 仍存在 |
+| 14 | 健壮性 | Model config require() | llm/index.ts | ❌ 仍存在 |
+| 15 | 整洁 | 大量 as any 断言（119→66） | 28 个文件 | ⚠️ 部分修复 |
+| 16 | 整洁 | knowledge-indexer 调试日志 | knowledge-indexer.ts | ❌ 仍存在 |
+| 17 | 整洁 | 未完成 TODO | policy-update-loop.ts | ❌ 仍存在 |
+| 18 | 整洁 | AgentAuditPhase 117 个成员 | log/phase.ts | ✅ 已修复 |
+| 19 | 整洁 | scripts/ 64 个文件 | scripts/ | ❌ 仍存在 |
+| 20 | 整洁 | Prisma schema 注释 | schema.prisma | ✅ 已修复 |
+| 21 | 整洁 | console.log（842→410） | 87 个文件 | ⚠️ 部分修复 |
+| 22 | 运维 | Chroma 端口未绑定 | docker-compose.yml | ✅ 已修复 |
+| 23 | 运维 | Docker 资源限制注释 | docker-compose.yml | ❌ 仍存在 |
+| 20a | 附加 | prisma/dev.db 未清理 | prisma/dev.db（已删除） | ✅ 已修复 |
+
+---
+
+## 本验证周期发现的重构变化
+
+| 变化 | 旧文件 | 新文件 |
+|------|--------|--------|
+| 审计日志模块重构 | `src/lib/agent-audit-logger.ts`（已删除） | `src/lib/log/audit.ts` |
+| 通知模块多通道升级 | `src/lib/wecom-notify.ts`（已删除） | `src/lib/log/notify/`（企微/飞书/钉钉） |
+| Phase 类型独立 | `agent-audit-logger.ts` 内嵌 | `src/lib/log/phase.ts` |
+| 统一入口 | 分散 import | `import { ... } from "@/lib/log"` |
+
+---
+
+## 修复优先级
+
+| 优先级 | 问题 | 说明 |
+|--------|------|------|
+| ~~P0~~ | ~~#1, #2, #4, #12, #22~~ | ~~已修复~~ |
+| P1 | #10 LLM 竞态条件 | 并发场景下 LLM 实例可能被意外重置 |
+| P2 | #6, #7, #8, #9, #13, #14 | 架构重复、缺少校验、动态 require |
+| P3 | #15, #16, #17, #19, #21, #23 | 技术债务、基础设施配置 |
+
+---
+
+## 修复趋势
+
+| 维度 | 进展 |
+|------|------|
+| 安全 | JWT + QWeather 全部修复 ✅ |
+| 网络暴露 | Chroma 端口已绑定 127.0.0.1 ✅ |
+| 代码重复 | LLM 模块、Chroma 客户端、extractTokenFromRequest 已统一 ✅ |
+| 内存泄漏 | activeTracers TTL 机制已上线 ✅ |
+| 审计告警 | 三通道输出 + 多渠道路由（企微/飞书/钉钉）已上线 ✅ |
+| 模块化 | 审计日志从单体文件重构为 `log/` 目录结构 ✅ |
+| SQLite 清理 | `prisma/dev.db` 已删除，完全迁移至 PostgreSQL ✅ |
+| 类型安全 | `as any` 断言 119→66（-44.5%）⚠️ |
+| Phase 拆分 | AgentAuditPhase 117 成员 → 11 个业务域子类型 ✅ |
+| 日志规范 | `console.log` 842→410（-51.3%）⚠️ |
+| 核心遗留 | 日志模块 ensureLogDir 重复、LLM 竞态、审计持久化、Docker 资源限制 ❌ |

package/templates/core/reports/code-review-suggestions.md

@@ -0,0 +1,66 @@
+# {{projectName}} 项目代码审查建议
+
+## 1. 重复的 LLM 模块
+
+`src/lib/llm.ts` 和 `src/lib/llm/index.ts` 两个文件同时存在，功能重叠。旧版 `llm.ts` 使用 `globalForLLM` 模式 + IIFE 的 `llmWithTools`，新版 `index.ts` 使用 `AuditedLLM` 包装类 + 延迟初始化。`agents/index.ts` 实际引用的是 `@/lib/llm/index`，旧文件成了死代码，建议删除避免混淆。
+
+## 2. LLM 单例存在竞态条件
+
+`src/lib/llm/index.ts` 中 `setLLMConfig()` 会调用 `resetLLM()` 将 `llmInstance` 置为 `null`，而 `getLLM()` 在 `null` 时会重建。如果两个并发请求携带不同的 `modelConfig`，A 请求的重置可能影响 B 请求正在使用的实例。建议改为按请求/线程隔离的 LLM 实例，或使用请求级缓存。
+
+## 3. 大量 `as any` 类型断言
+
+`src/agents/index.ts` 中存在大量 `as any`、`as unknown as` 类型断言，特别是消息类型转换（如 `state.messages as unknown as Array<Record<string, unknown>>`）、toolResults 赋值（`toolResults: toolResults as any`）等。这些绕过了 TypeScript 类型检查，建议逐步用类型守卫或 zod schema 替代。
+
+## 4. QWeather JWT 签名是占位符
+
+`src/lib/farm-server-client.ts` 第 71 行的 `createQWeatherJwt()` 函数中，EdDSA 签名写死了 `"PLACEHOLDER_SIGNATURE"`。注释说"实际迁移 co-agent 天气工具时会携带完整的 JWT 签名实现"，说明这是未完成的功能，生产环境会导致认证失败。
+
+## 5. 审计日志静默吞错
+
+`src/lib/agent-audit-logger.ts` 中 `writeAuditLog()` 的 catch 块只做了 `console.error`，`ensureLogDir()` 的 catch 完全忽略。这意味着当 DB 不可用时，所有审计记录会静默丢失，没有告警机制。建议至少增加一个失败计数器或 metric 上报。
+
+## 6. JWT 硬编码默认密钥
+
+`src/lib/auth.ts` 第 4 行 `JWT_SECRET = process.env.JWT_SECRET || "dev-secret-key"`。在生产环境中如果忘记设置环境变量，会使用可预测的默认密钥，存在安全风险。建议在生产环境强制要求配置，缺失时直接拒绝启动。
+
+## 7. `activeTracers` Map 潜在内存泄漏
+
+`src/agents/index.ts` 第 239 行 `activeTracers` Map 的清理依赖 `endChainTrace()` 被调用。如果流式请求异常中断（客户端断开），`endChainTrace` 可能不会被调用，导致 Map 持续增长。建议增加 TTL 过期机制或定期清理。
+
+## 8. 缺少请求体校验
+
+`src/app/api/agent/chat/route.ts` 直接用 `await request.json()` 后做类型断言，没有用 Zod 或类似库做运行时校验。如果客户端发送了格式错误的请求体，错误会在深层抛出不友好的异常。
+
+## 9. 脚本目录过于庞大（50+ 脚本）
+
+`scripts/` 目录下有 50+ 个脚本，包含大量一次性迁移脚本（如 `backfill-projectId.ts`、`fix-knowledge-data.js`、`restore-from-dump.js`），还有 Windows `.bat` 和 Unix `.sh` 双份。建议将一次性脚本归档到单独目录，减少维护负担。
+
+## 10. 大文件职责混杂
+
+`src/agents/index.ts`（468 行）同时包含了：StateGraph 定义、ToolNode 包装器、审计包装器 `wrapNodeWithAudit`、`runAgent`/`streamAgent` 入口、Tracer 管理、`buildPartialState`。建议拆分为多个文件：
+
+- `graph.ts` — 图定义
+- `tool-node-wrapper.ts` — ToolNode 包装器
+- `audit-wrapper.ts` — 审计包装器
+- `agent-runner.ts` — runAgent/streamAgent 入口
+
+## 11. Chroma 端口未绑定 localhost
+
+`docker-compose.yml` 中 Chroma 端口映射为 `"8000:8000"`，没有绑定到 `127.0.0.1`，而 PostgreSQL 是 `"127.0.0.1:5433:5432"`。如果部署在公网机器上，Chroma 的 8000 端口会暴露在外，建议统一绑定到 `127.0.0.1`。
+
+## 12. Docker Compose 中资源限制被注释
+
+`docker-compose.yml` 中 PostgreSQL 和 Chroma 的 `deploy.resources` 全部被注释掉了。在生产环境中没有资源限制，某个服务 OOM 可能影响整个宿主机。建议根据实际负载启用 resource limits。
+
+## 13. `pnpm-lock.yaml` 和 `package-lock.json` 同时存在
+
+项目根目录同时存在 `pnpm-lock.yaml` 和 `package-lock.json`，说明可能在 npm 和 pnpm 之间切换过。建议统一使用一种包管理器，删除另一个 lock 文件。
+
+## 14. Model config 切换使用 `require()` 动态加载
+
+`src/lib/llm/index.ts` 第 246-247 行使用 `require("@/lib/model-config-logger")` 动态加载，这在 ESM 环境下可能不稳定。注释 `// Logger unavailable in server context` 也说明这有已知问题。建议改为静态 import 或明确的依赖注入。
+
+## 15. Prisma 多文件 Schema 路径不一致
+
+`schema.prisma` 注释说子文件在 `prisma/schema/` 目录下，但实际 `main.prisma` 和 `nongqing.prisma` 在 `prisma/` 根目录。而且 `prisma/` 下还有一个 `dev.db`（SQLite 文件），说明开发环境可能混用了 SQLite 和 PostgreSQL。

package/templates/core/reports/index.md

@@ -0,0 +1,57 @@
+# Reports 总览
+
+> 自动生成: 2026-07-01 11:41:22 | 共 6 份 Report | 下次更新: 每天 2:10 AM
+>
+> 扫描范围: `.qoder/reports/`（Plan Review 在 `.qoder/reviews/`，由 Plan 管线管理）
+
+---
+
+## 快速导航
+
+| 类型 | 说明 | 入口 |
+|------|------|------|
+| combined-report | 综合代码审查报告 | [code-review-combined-report.md](./code-review-combined-report.md) |
+| fix-verify | 修复验证对照报告 | [code-review-fix-verification-report.md](./code-review-fix-verification-report.md) |
+| suggestions | 审查建议（历史） | [code-review-suggestions.md](./code-review-suggestions.md) |
+| runtime-report | 运行时报告（按子系统） | [{{projectName}}-runtime-report/](./{{projectName}}-runtime-report/) |
+| boundary | Runtime Report ↔ 静态 Report 边界 | [boundary-runtime-report.md](./boundary-runtime-report.md) |
+| workflow | Report 工作流 | [REPORT-WORKFLOW.md](./REPORT-WORKFLOW.md) |
+
+---
+
+## 修复概览
+
+| 状态 | 数量 |
+|------|:----:|
+| ✅ 已修复 | 34 |
+| ⚠️ 部分修复 | 7 |
+| ❌ 仍存在 | 34 |
+
+---
+
+## Report 文件
+
+| 日期 | 类型 | 文件 | 标题 |
+|------|------|------|------|
+| 2026-07-01 | `issue-draft` | [runtime-issue-20260622-01.md](./runtime-issue-20260622-01.md) | RUNTIME-20260622-01 |
+| 2026-07-01 | `issue-draft` | [runtime-issue-20260624-01.md](./runtime-issue-20260624-01.md) | RUNTIME-20260624-01 |
+| 2026-07-01 | `runtime-gateway` | [{{projectName}}-runtime-report/gateway.md](./{{projectName}}-runtime-report/gateway.md) | {{projectName}} 运行时报告 — gateway |
+| 2026-06-29 | `combined-report` | [code-review-combined-report.md](./code-review-combined-report.md) | {{projectName}} 项目代码审查综合报告 |
+| 2026-06-30 | `suggestions` | [code-review-suggestions.md](./code-review-suggestions.md) | {{projectName}} 项目代码审查建议 |
+| 2026-06-30（第十一次验证，修正 #20a） | `fix-verify` | [code-review-fix-verification-report.md](./code-review-fix-verification-report.md) | {{projectName}} Code Review 修复验证对照报告 |
+
+---
+
+## 运行时报告（按子系统分类）
+
+> `{{projectName}}-runtime-report/{subsystem}.md`，每份报告对应一个子系统。
+> 由各子系统自动追加，去重后每条 Finding 对应一条记录。
+
+| 日期 | 子系统 | 文件 | 标题 |
+|------|--------|------|------|
+| 2026-07-01 | `gateway` | [{{projectName}}-runtime-report/gateway.md](./{{projectName}}-runtime-report/gateway.md) | {{projectName}} 运行时报告 — gateway |
+
+---
+
+*索引由 `scripts/gen-report-index.sh` 自动生成，勿手动编辑*
+*最后更新: 2026-07-01 11:41:22*