zhuiguangaikf/zhuiguang-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 首次推送到Gitea - 完整项目代码 + 安全加固 + 知识库

Browse Source
This commit is contained in:
ZhuiGuangAI Dev
2026-10-02 18:52:49 +08:00
parent b44601bb66
commit 8205ae709c
1185 changed files with 49841 additions and 12802 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.trae/rules/README.md
+61
View File
@@ -0,0 +1,61 @@
# 追光AI — 规则体系索引
> 版本: v1.0 | 更新: 2026-10-01 | 所有 `.trae` 内容均在代码仓库 `zhuiguang-ai/.trae/` 内，跟着 git 走
## 一、这套规则解决什么问题
AI 代理**每次会话都是无状态的**（不记得上次讨论）。规则与知识库的唯一作用，就是把跨会话的持久上下文注入进来。
没有它们，AI 每次都会重新问、重新猜、重复踩坑 —— 迭代效率无法复利。
## 二、四层结构（单一事实源，互不复制）
| 层 | 载体 | 内容 | 何时加载 |
|----|------|------|---------|
| **L0 方法论** | `.trae/ai_coding_knowledge.json` | AI 编程效率的方法/工具/工作流/原则/反模式（**机器可解析**，不写业务） | 每次任务开始前 |
| **L1 协作规则** | `.trae/rules/ai_agent_rules.md`<br>`.trae/rules/ai_collaboration.md` | 启动加载顺序、小任务豁免、Plan-first 流程、验收标准、完成自动记录 | 每次任务开始前 / 收尾时 |
| **L2 工程标准** | `.trae/rules/project_rules.md` | 技术栈、数据获取、导航图片、无障碍、安全、定时任务、部署等硬规范 | 写代码时按需 |
| **L3 项目事实** | `.trae/knowledge_graph.jsonl`（MCP 源）<br>`.trae/knowledge_graph.json`（渲染版）<br>`.trae/knowledge/*`（能力/过程/成果自动记录） | 模块、部署、定时任务、仓库、约定、巡检问题等**事实** | 需要项目具体知识时 |
> ⚠️ **禁止跨层复制**：同一事实只允许有一个权威载体，其余位置只写引用。复制必然漂移（见反模式 `divergent-copies`）。
## 三、快速导航
| 我要… | 读哪个 |
|-------|--------|
| 开始一个开发任务 | [ai_agent_rules.md](ai_agent_rules.md) §0 |
| 知道怎么和 AI 协作、怎么算做完 | [ai_collaboration.md](ai_collaboration.md) |
| 查 AI 编程方法论 / 选工具 | `.trae/ai_coding_knowledge.json` |
| 查项目某个模块/部署/定时任务的事实 | `.trae/knowledge_graph.jsonl` |
| 查编码硬规范（安全/API/图片/无障碍） | [project_rules.md](project_rules.md) |
| 部署、运维、容器 | [project_rules.md](project_rules.md) §14–15（工程侧见 [specs/modules/09-devops.md](../specs/modules/09-devops.md)） |
## 四、自动化闭环
```
开发完成
│
├─ npm run knowledge:update ← 手动/收尾执行
└─ git post-commit hook ← 本机自动触发
│
▼
scripts/update-knowledge.mjs
│
├─ .trae/knowledge/capabilities.json 能力特征（API/页面/组件/模型/脚本/任务/依赖）
├─ .trae/knowledge/dev_process.jsonl 开发过程（按提交追加）
├─ .trae/knowledge/artifacts.jsonl 模型成果（迁移/脚本/提交统计）
└─ .trae/knowledge_graph.json / .jsonl 事实层增量 upsert
```
## 五、维护规则
1. **方法/工具层变化** → 改 `.trae/ai_coding_knowledge.json`，同步 [ai_collaboration.md](ai_collaboration.md)
2. **协作流程变化** → 改 [ai_collaboration.md](ai_collaboration.md)，同步更新 `ai_coding_knowledge.json` 中对应 `workflow:*`
3. **项目事实变化** → 跑 `npm run knowledge:update`，或直接维护 `.trae/knowledge_graph.jsonl`
4. **工程标准变化** → 改 [project_rules.md](project_rules.md)
5. **废弃而非删除**：用 `> **已废弃 (date)**` 标注并写明替代方案，保留至少一个大版本周期
## 六、版本历史
| 日期 | 版本 | 变更 |
|------|------|------|
| 2026-10-01 | v1.0 | 初始版本：建立四层结构；新增 AI 编程知识库、AI 代理规则、AI 协作流程、自动记录脚本 |
.trae/rules/ai_agent_rules.md
+88
View File
@@ -0,0 +1,88 @@
# AI Agent 规则（启动与查询）
> 版本: v1.0 | 更新: 2026-10-01
> 相关: [README.md](README.md) · [ai_collaboration.md](ai_collaboration.md) · `../ai_coding_knowledge.json`
目的：让 AI 在本项目中**每次任务开始前按固定顺序加载上下文**，开工前就知道方法、规范与既有事实，避免重复交代与重复踩坑。
---
## §0 启动加载顺序（最高优先级）
```
1. .trae/rules/README.md ← 索引：先看有哪些层
2. .trae/ai_coding_knowledge.json ← 方法层：按 entity.type 过滤（principle/method/workflow/anti_pattern/tool）
3. .trae/rules/ai_collaboration.md ← 流程层：Plan-first / 验收标准 / 完成自动记录
4. .trae/knowledge_graph.jsonl ← 事实层：按 name / observations 关键词检索相关实体（按需，不要全量读）
5. .trae/rules/project_rules.md ← 工程标准：与本次改动相关的章节
6. 具体源码（只读相关文件）
```
**原则**：上下文是预算（见 `principle:context-budget`）。第 4、5 步**按需**加载，不要一次性灌入全部历史。
## §1 小任务豁免清单
以下任务**无需**走完整启动流程，可直接执行：
| 豁免类型 | 示例 |
|---------|------|
| 拼写修正 | 修改变量名拼写 |
| 注释/文案 | 增删注释、改中文提示文案 |
| 格式调整 | 缩进、空行、引号风格 |
| 单值配置 | 改端口号、超时时间等单个常量 |
| 纯查询 | 「XX 在哪」「XX 是什么意思」（不改代码） |
| 已给完整方案 | 用户已提供明确的文件+改法 |
## §2 非小任务：强制先查知识库
不属于 §1 的任务，开工前**必须**先检索事实层：
```
步骤1 读 .trae/rules/README.md 确定应查哪一层
步骤2 在 .trae/knowledge_graph.jsonl 中按关键词检索（name / observations）
优先匹配：实体名 > observations 关键词 > entityType 批量
步骤3 命中则读取该实体 observations，确认规范/部署/踩坑/约束
步骤4 再开始 Explore → Plan → Implement → Verify（见 ai_collaboration.md）
```
### 检索优先级
| 优先级 | 方式 | 场景 |
|--------|------|------|
| 1 | 实体名精确匹配（如 `追光AI:容器化部署`） | 已知目标实体 |
| 2 | observations 关键词（如 `cron`、`8301`、`Prisma`） | 知道主题 |
| 3 | entityType 批量（如全部 `Issue`、全部 `ScheduledTask`） | 需要某类全貌 |
### 若 Knowledge Graph Memory MCP 不可用
直接读/写 `.trae/knowledge_graph.jsonl`（JSONL，一行一实体或关系）。改动后用 `npm run knowledge:update` 同步渲染版 `.json`。
## §3 查询后输出格式
命中实体时，在回复中简述（便于复核）：
```
[KG] 命中 N 条:
- Module: 追光AI:模块(09-运维与部署)
- Issue : 追光AI:巡检问题与处理(2026-10-01)
```
## §4 行为约束
### 必须
1. 非豁免任务**必须先检索知识库**再动手
2. 发现代码与已记录规范/事实冲突时**必须指出**，不得静默按代码走
3. 遇到新踩坑/新约束，**必须**在收尾时写入知识库（见 ai_collaboration.md §4）
4. 改动涉及部署/定时任务/数据模型时，**必须**同步更新对应实体
### 禁止
1. 禁止跳过检索直接改业务代码（豁免项除外）
2. 禁止把同一事实**复制**到多个文件（只写一处 + 其余引用）
3. 禁止忽略知识库中已记录的 `Issue` 实体而重复踩同一坑
4. 禁止在未跑门禁（`npx tsc --noEmit` + `npx vitest run`）的情况下声称完成
## §5 版本历史
| 日期 | 版本 | 变更 |
|------|------|------|
| 2026-10-01 | v1.0 | 初始版本：§0 启动加载顺序 + §1 豁免 + §2 强制检索 + §4 行为约束 |
.trae/rules/ai_collaboration.md
+110
View File
@@ -0,0 +1,110 @@
# AI 协作流程规范
> 版本: v1.0 | 更新: 2026-10-01
> 相关: [README.md](README.md) · [ai_agent_rules.md](ai_agent_rules.md) · `../ai_coding_knowledge.json`
定义 AI 在本项目中的**协作流程**：怎么规划、怎么验证、怎么收尾、怎么沉淀。目标 —— 产出可验证、经验可复利。
---
## §0 三条不可协商的原则
1. **不一次性生成大量代码** —— 任务必须可拆解（`anti_pattern:one-shot-big`）
2. **没有验收标准不开工** —— 否则无法判断何时完成（`method:acceptance-criteria`）
3. **不审查 diff 不算完成** —— AI 的自我描述可信度低于实际改动（`method:review-diff`）
## §1 主工作流：Explore → Plan → Implement → Verify
| 阶段 | 做什么 | 产出 |
|------|--------|------|
| **Explore** | 读相关源码 / 规格 / 知识图谱实体，确认现状与约束 | 现状结论 + 涉及文件清单 |
| **Plan** | 输出结构化步骤（步骤 + 依赖 + 验收标准）；复杂任务**先给计划再动手** | 计划（TodoWrite 跟踪） |
| **Implement** | 按计划分步实现，**一步一验证**，不攒到最后一起验 | 可增量验证的改动 |
| **Verify** | 跑门禁；失败回到 Implement | 门禁通过证据 |
> 复杂任务（跨 3 个以上模块 / 涉及数据模型 / 涉及部署）**必须先出计划并等确认**。
## §2 任务拆解铁律
- **窄范围 > 大而模糊**：`修 /api/tools 分页 total 字段` 优于 `改进工具模块`
- 每步定义**输入**（依赖文件/数据）与**输出**（验收标准）
- 状态机驱动：`Pending → Running → Blocked → Done / Failed`
- 单任务改动建议 ≤15 个文件；超出则重新拆解
## §3 验收标准（每个任务开工前必须明确）
| 任务类型 | 验收标准 |
|---------|---------|
| 功能开发 | `npx tsc --noEmit` 零错误 + `npx vitest run` 全绿 + 新功能可用 + 无回归 |
| Bug 修复 | 复现路径通过 + 相关测试通过 |
| 重构 | 行为不变 + 测试全绿 + 无性能回归 |
| 数据/脚本 | 输出格式正确 + 样例验证通过 + 幂等可重跑 |
| 部署/运维 | 部署后自检清单全通过（见 project_rules.md §15.3） |
本项目**双门禁**：`npx tsc --noEmit` + `npx vitest run`（缺一不可）。
## §4 代码审查：看 diff 不看对话
- 用 `git diff` 逐行审查**实际改动**
- 对照 `§3 验收标准` 核验，而不是对照 AI 的说法
- 重点排查：臆造的 API/字段、被静默删除的逻辑、异常处理缺失、硬编码密钥
## §5 失败分型（先分型，再优化）
| 失败类型 | 表现 | 优化方向 |
|---------|------|---------|
| 规划失败 | 任务拆解不合理、范围失控 | 重新拆解任务 |
| 执行失败 | 命令/环境/依赖报错 | 修工具、环境、依赖 |
| 质量失败 | 结果不满足验收标准 | 收紧验收标准或加门禁 |
> 禁止把所有失败都归因为「模型不够强」（`anti_pattern:model-is-everything`）。
## §6 完成流程：自动记录（关键，不可跳过）
开发完成并通过门禁后，**必须**运行：
```bash
npm run knowledge:update
# 等价于：node scripts/update-knowledge.mjs（可加 --dry-run 预览，不写文件）
```
脚本自动捕获三类信息并沉淀：
| 捕获内容 | 来源 | 落盘位置 |
|---------|------|---------|
| **能力特征** | 扫描 `src/app/api/**/route.ts`、`src/app/**/page.tsx`、`src/components/**`、`prisma/schema.prisma`、`scripts/**`、`crontab.txt`、`package.json`、`data/bot-characters.json` | `.trae/knowledge/capabilities.json` |
| **开发过程** | `git log`（最近提交：hash/时间/主题/改动文件数） | `.trae/knowledge/dev_process.jsonl`（按提交追加） |
| **模型成果** | 本次交付物：新增迁移、新增/变更脚本、提交统计 | `.trae/knowledge/artifacts.jsonl`（追加） |
并**增量 upsert**（按实体名，同名替换 observations，未出现的旧实体原样保留，永不删除）：
- `.trae/knowledge_graph.json`（渲染版，人类可读 + 权威）
- `.trae/knowledge_graph.jsonl`（MCP Knowledge Graph Memory 读取的源文件）
**自动化触发**：本机已装 `git post-commit` 钩子（`.git/hooks/post-commit`），每次提交后自动执行同一脚本（静默 + 后台，不阻断、不拖慢提交），无需手动记得。
> **换机 / 新克隆后重装钩子**（`.git/hooks/` 不随 git 传递）——在仓库根执行：
> ```bash
> printf '#!/bin/sh\nROOT=$(git rev-parse --show-toplevel) || exit 0\n[ -f "$ROOT/scripts/update-knowledge.mjs" ] || exit 0\ncommand -v node >/dev/null 2>&1 || exit 0\n( cd "$ROOT" && node scripts/update-knowledge.mjs --quiet >/dev/null 2>&1 & )\nexit 0\n' > .git/hooks/post-commit
> ```
> 卸载：删除 `.git/hooks/post-commit` 即可（脚本本身仍可手动运行）。
> 未运行记录脚本就结束任务，视为**流程未完成**。
## §7 反模式（禁止）
| 反模式 | 替代做法 |
|--------|---------|
| 一次性生成大量代码 | 任务拆解（§2） |
| 无验收标准 | 先定义验收标准（§3） |
| 不审查 AI 代码 | 看 diff + 双门禁（§4） |
| 一次性灌入冗余上下文 | 上下文预算，按需加载 |
| 把「模型更强」当「系统更稳」 | 模型 + 编排 + 门禁三层闭环 |
| 同一知识多份副本 | 单一事实源 + 引用 |
| 知识库只写不更新 | §6 自动记录 + 定期一致性巡检 |
## §8 版本历史
| 日期 | 版本 | 变更 |
|------|------|------|
| 2026-10-01 | v1.0 | 初始版本：Plan-first 四阶段 + 验收标准 + 完成自动记录（§6） |
.trae/rules/project_rules.md
+134 -26
View File
@@ -1,5 +1,10 @@
# 追光AI 项目开发规则
> **本文件是 L2 工程标准层**（四层结构索引见 [README.md](README.md)）。其他层：
> - L0 方法论：[../ai_coding_knowledge.json](../ai_coding_knowledge.json)（AI 编程效率方法库，机器可解析）
> - L1 协作规则：[ai_agent_rules.md](ai_agent_rules.md)（启动加载）· [ai_collaboration.md](ai_collaboration.md)（Plan-first + 自动记录）
> - L3 项目事实：[../knowledge_graph.jsonl](../knowledge_graph.jsonl)（知识图谱）· [../knowledge/](../knowledge/)（能力/过程/成果自动记录）
## 端口规范
- 应用端口范围: **8301-8310**（预留扩展）
- 默认端口: **8301**
@@ -9,9 +14,9 @@
## 服务器连接信息（重要！总是需要）
- **IP地址**: 119.45.242.239
- **登录用户**: ubuntu
- **SSH密钥**: `C:\SGP_KF\ZhuiGuangAI\zhuiguang-ai\Pem\zg.pem`
- **SSH命令**: `ssh -i "C:\SGP_KF\ZhuiGuangAI\zhuiguang-ai\Pem\zg.pem" ubuntu@119.45.242.239`
- **SCP示例**: `scp -i "C:\SGP_KF\ZhuiGuangAI\zhuiguang-ai\Pem\zg.pem" localfile ubuntu@119.45.242.239:/home/ubuntu/zhuiguang-ai/`
- **SSH密钥**: `C:\SSH\zhuiguang-ai\zg.pem`（2026-10-02 校正；旧值 `E:\0.Center-S2\S890-V3\pem\zg.pem` 已迁移）
- **SSH命令**: `ssh -i "C:\SSH\zhuiguang-ai\zg.pem" ubuntu@119.45.242.239`
- **SCP示例**: `scp -i "C:\SSH\zhuiguang-ai\zg.pem" localfile ubuntu@119.45.242.239:/home/ubuntu/zhuiguang-ai/`
## 服务器与基础设施
- **域名**: www.zhuig.com (HTTPS，SSL证书自动续期)
@@ -19,8 +24,10 @@
- **访问地址**: https://www.zhuig.com (HTTP自动跳转HTTPS)
- **数据库**: 阿里云RDS MySQL — rm-0jlbgr2rv6dj3t6jngo.mysql.rds.aliyuncs.com:3306
- **Redis**: 云服务器上已有(Docker容器redis-cache:6379)，与其他项目共用，有密码认证
- **本地Git同步目录**: K:\git-repos
- **开发机**: E:\ZG_Dev\ZhuiGuangAI\zhuiguang-ai
- **工作区/开发目录**: `E:\KF_7\ZhuiGuangAI\zhuiguang-ai`（master，当前唯一活跃工作副本）
- **本地裸仓镜像（备份入口）**: `K:\git-repos\zhuiguang-ai.git`（bare，2026-10-01 新建。源仓库 remote 需指向它才能持续备份）
- **已停用副本**: `E:\ZG_Dev\ZhuiGuangAI\zhuiguang-ai`（停在 2026-05-23，无 remote）与 `K:\git-repos\zhuiguang-ai`（非裸仓旧工作副本，同样停在 2026-05-23）
- **远端现状**: 源仓库 remote `local` 仍指向已不存在的 `c:\gitbf\zhuiguang-ai.git`；云端 Gitea（119.45.242.239:3000）无本项目仓库
- **Docker管理**: `docker ps` / `docker logs zhuiguang-ai-app` / `docker restart zhuiguang-ai-app`
### ⚠️ 多项目共存服务器（更新/部署铁律）
@@ -142,9 +149,87 @@ docker logs --tail 50 zhuiguang-ai-cron # Cron 容器日志
## 构建与检查
- 修改代码后必须运行 `npx tsc --noEmit` 确认零错误
- 修改代码后必须运行 `npx vitest run` 确认所有测试通过
- 本地开发服务器: `npm run dev` (端口8301)
- 生产构建: `docker build -t zhuiguang-ai:latest .`
- 部署: `docker stop/rm` 旧容器 → `docker run` 新容器
- **打包分析**: `ANALYZE=true npm run build` 启用 `@next/bundle-analyzer` 分析包体积
## 测试规范
- 测试框架: Vitest
- 配置文件: `vitest.config.ts` + `vitest.setup.ts`
- 测试目录: `src/__tests__/`，文件名匹配 `*.test.ts`
- 覆盖率目标: **80%+**（行/分支/函数/语句）
- tsconfig 需包含 `"types": ["vitest/globals"]` 以启用全局 test/expect/describe
- 测试类别:
- 工具函数单元测试（lib 目录下的纯函数）
- API 路由集成测试
- 组件渲染测试（配合 @testing-library/react）
- 禁止跳过测试（`.skip`）除非有明确的 TODO 注释说明原因
## 图片优化规范
- **强制使用 LazyImage 组件** (`src/components/ui/LazyImage.tsx`)，禁止使用原生 `<img>` 标签
- LazyImage 特性:
- 基于 next/image 的懒加载包装器
- 内置骨架屏加载状态（Skeleton loading state）
- 错误回退占位图（Error fallback）
- 支持 `referrerPolicy` 属性（用于跨域图片场景）
- 支持 `width`/`height` 或 `fill` 模式
- 用法示例:
```tsx
import LazyImage from "@/components/ui/LazyImage";
// 固定尺寸
<LazyImage src={url} alt="描述" width={32} height={32} />
// 响应式
<LazyImage src={url} alt="描述" fill className="object-cover" />
// 跨域图片
<LazyImage src={url} alt="描述" width={48} height={48} referrerPolicy="no-referrer" />
```
- 必须提供有意义的 `alt` 文本
- 装饰性图片使用 `alt=""` 配合 `role="presentation"`
## 导航规范（Link vs router.push）
- 所有静态页面内导航必须使用 Next.js `<Link>` 组件
- 禁止使用 `<button onClick={() => router.push(...)}>` 进行页面跳转
- 适用场景:
- 分页按钮 → `<Link>`
- 侧边栏筛选 → `<Link>`（含查询参数）
- 面包屑 → `<Link>`
- 卡片/列表项 → `<Link>`
- "清除筛选"按钮 → `<Link href="/base-path">`
- 仅外部链接使用 `<a>`（需加 `target="_blank" rel="noopener noreferrer"`）
## API 响应格式规范
- 列表接口统一使用 `total`（不是 `totalCount`）表示总数
- 返回格式: `{ data, total, page, pageSize }` 或 `{ success, error }`
- 前端消费端也同步使用 `total` 字段
- 已统一接口: `/api/notifications`, `/api/forum/topics`, `/api/comments`, `/api/user/points`
## 并行查询规范
- 多个独立的 Prisma 查询必须使用 `Promise.all` 并行执行
- 严禁串行 await 多个无依赖的数据库查询
```typescript
// ✅ 正确：并行查询
const [tool, relatedTools, reviewCount] = await Promise.all([
prisma.tool.findUnique({ where: { slug } }),
prisma.tool.findMany({ where: { categoryId }, take: 6 }),
prisma.review.count({ where: { toolId } }),
]);
```
## 无障碍规范（WCAG 2.1）
- 所有交互元素（div onClick）必须添加 `role` + `aria-*` 属性 + 键盘事件（`onKeyDown`）
- 搜索输入框必须添加 `aria-label` 属性
- 装饰性图片添加 `role="presentation"`（不暴露给屏幕阅读器）
- 根布局必须提供跳过导航链接（Skip-link）
- 主内容区域使用 `<main id="main-content" tabIndex={-1}>`
## TypeScript 类型规范
- 禁止使用 `any` 类型
- 泛型函数使用 `<T>` 约束（参考 `src/lib/cache.ts` 的 `cachedResponse<T>`）
- API 回调函数使用明确的参数类型
- 内联对象类型使用 interface 而非匿名类型字面量
- `src/lib/admin-auth.ts`: 使用 Prisma 严格类型，id 字段统一为 `number`
## 数据库
- 云数据库: 阿里云RDS MySQL
@@ -236,16 +321,19 @@ docker logs --tail 50 zhuiguang-ai-cron # Cron 容器日志
- OPENAI_API_KEY: OpenAI API Key（Bot活动引擎使用，生成论坛内容）
## 数字人Bot系统
- **角色定义文件**: `data/bot-characters.json` — 112个Bot角色定义，所有Bot脚本和前端工具依赖此文件
- **Bot头像目录**: `public/bot-avatars/` — 程序化SVG头像（112个，~2.5KB/个）
- **角色定义文件**: `data/bot-characters.json` — 当前 **6 个**「行业情报官」角色（cb_intel / fi_ins_intel / fi_stock_intel / brand_intel / ai_intel / ct_intel）；旧 112 角色「模拟真人互刷」体系已于 2026-09-05 退役
- **Bot头像目录**: `public/bot-avatars/` — SVG 头像 178 个（含历史角色头像）
- **会员头像库**: `public/avatars/` — SVG 头像 530 个，会员可在个人中心选择或自定义上传
- **头像生成脚本**: `scripts/generate-avatar-library.mjs` — 批量生成头像库，支持按性别/主题/数量筛选
- **头像上传目录**: `public/uploads/avatars/` — 用户自定义上传头像存储
- **Bot用户标记**: User表中 `isBot: true` 标识Bot用户，与真人的互动数据分别统计
- **Bot活动时段**: 9:00-23:00每小时运行，15轮/天，论坛内容不干扰深夜用户体验
- **Bot活动时段**: 旧「模拟真人互刷」体系已停用（`bot-activity` 等任务在 `crontab.txt` 中已注释，2026-09-05 退役）；现由行业情报官引擎承担
- **Bot数据库**: 12张Bot专用表（BotConfig/BotMemory/BotDailyStat/BotSkill/BotWeeklyReview/BotPersona/BotPersonaVariant/BotPersonaExperiment/BotPersonaAssignment/BotPersonaMetric/BotAdversarialLearning/BotCrossForumAffinity）
## 定时任务调度系统
- **后台管理**: `/admin/tasks`（任务中心）、`/admin/tasks/logs`（执行日志）、`/admin/tasks/[taskKey]`（单任务详情+统计）
- **数据模型**: TaskConfig（任务配置，含enabled/cronExpr/config）、TaskLog（执行历史，含status/duration/result/error）
- **种子数据**: `scripts/seed-task-configs.mjs` 初始化6个任务配置
- **种子数据**: `scripts/seed-task-configs.mjs` 初始化 29 个任务配置（含已停用任务，与 `crontab.txt` 存在漂移，见下）
- **手动触发**: `/admin/tasks` 页支持每个任务运行，也可通过 POST `/api/admin/tasks/run` 触发
- **API**:
- `GET/PUT /api/admin/tasks/configs` — 任务配置查询/更新
@@ -253,25 +341,42 @@ docker logs --tail 50 zhuiguang-ai-cron # Cron 容器日志
- `POST /api/admin/tasks/run` — 手动触发任务执行
### 定时任务（Supercronic 容器调度）
所有定时任务由 `zhuiguang-ai-cron` 容器内的 supercronic 调度，配置文件 `crontab.txt`。不再使用主机 crontab + cron-wrapper.sh。
所有定时任务由 `zhuiguang-ai-cron` 容器内的 supercronic 调度，配置文件 `crontab.txt`（**唯一准绳**）。不再使用主机 crontab。
| 时间 | 任务 | 脚本 | TaskKey | 说明 |
|------|------|------|---------|------|
| 01:00 | Task5 更新星值 | `scripts/task5-update-stars.mjs` | task5-update-stars | 更新所有GitHub技能Stars数+日/周/月变化 |
| 03:00 | Task3 工具巡检 | `scripts/task3-check-tools.mjs` | task3-check-tools | 检查网站/Logo可访问性+自动发布合格待审核工具 |
| 04:00 | Bot技能结晶 | `scripts/bot-skill-crystallize.mjs` | bot-skill-crystallize | 扫过去14天高互动Bot话题→DeepSeek解构共性→入库BotSkill（usageCount驱动调用）；末尾回收7天前成熟技能更新successRate（<30%且使用≥3次自动isActive=false） |
| 05:00 | Bot亲和度与画像 | `scripts/bot-affinity-update.mjs` | bot-affinity-update | 刷BotCrossForumAffinity（affinity=min(1, samples/total/4)）和BotPersona（avgReplyLength/questionRatio/stanceKeywords/topHumanUsers/topTopicTypes/lastTopicTitles，bot-activity发帖时注入prompt） |
| 04:00 | Task6 评测热门 | `scripts/task6-review-hot.mjs` | task6-review-hot | 评测2个最热未评测GitHub技能(五维评测) |
| 05:00 | Task4 发现技能 | `scripts/daily-discover.mjs` | task4-discover-skills | GitHub搜索≥1000 stars项目→DeepSeek预评测→入库PendingSkill |
| 06:00 | Task1 发现工具 | `scripts/task1-discover-tools.mjs` | task1-discover-tools | 36kr/IT之家/开源中国RSS→DeepSeek提取工具→入库PendingTool |
| 07:30 | AI日报 | `scripts/daily-news.mjs` | daily-news | 多源搜索真实新闻+DeepSeek整理格式→发布日报 |
| 21:30 | Bot反馈闭环 | `scripts/bot-feedback-loop.mjs` | bot-feedback-loop | 扫描Bot自己帖子下的新回复→存反馈记忆→按概率触发二次回复（仅expert bots，配额high=6/medium=3/low=1） |
| 周日02:00 | Bot周度复盘 | `scripts/bot-weekly-review.mjs` | bot-weekly-review | 算engagementScore→生成REFLECTION记忆→决定下周配额tier（写入BotWeeklyReview.nextWeekQuota，bot-activity下次跑时动态覆盖） |
| 08:00 | Task7 新闻推社区 | `scripts/task7-news-to-community.mjs` | task7-news-to-community | 将当日日报新闻分发到社区4个板块（AI工具推荐/AI资讯/技术探讨/观点讨论） |
> ⚠️ supercronic 在容器内按 **UTC** 执行（TZ 环境变量不生效），下表时刻均为 UTC，括号外已换算为北京时间（UTC + 8h）。
> ⚠️ 2026-10-01 巡检确认：`crontab.txt` 已注释停用大量 Bot/行业情报 AI 任务，但 `scripts/seed-task-configs.mjs` 仍写 `enabled: true`、`scripts/health-check.mjs` 仍把它们列入期望键 —— **三方漂移会产生误告警**，新增/停用任务时必须同步这三处。
**启用中（19 个）**
| UTC | 北京时间 | 任务 | 脚本 | TaskKey |
|-----|---------|------|------|---------|
| 0 1 | 09:00 | Task5 更新星值 | `scripts/task5-update-stars.mjs` | task5-update-stars |
| 0 3 | 11:00 | Task3 工具巡检 | `scripts/task3-check-tools.mjs` | task3-check-tools |
| 0 4 | 12:00 | Task6 评测热门 | `scripts/task6-review-hot.mjs` | task6-review-hot |
| 0 4 * * 0 | 周日 12:00 | 工具数据补全 | `scripts/enrich-tool-data.mjs` | enrich-tool-data |
| 30 4 | 12:30 | 日志清理 | `scripts/cleanup-logs.mjs` | cleanup-logs |
| 0 5 | 13:00 | Task4 发现技能 | `scripts/daily-discover.mjs` | task4-discover-skills |
| 0 6 | 14:00 | Task1 发现工具 | `scripts/task1-discover-tools.mjs` | task1-discover-tools |
| 30 6 | 14:30 | task_log 清理 | `scripts/cleanup-task-logs.mjs` | cleanup-task-logs |
| 30 7 | 15:30 | AI 日报 | `scripts/daily-news.mjs` | daily-news |
| 0 8 | 16:00 | Task7 新闻推社区 | `scripts/task7-news-to-community.mjs` | task7-news-to-community |
| 0 8 1 * * | 每月 1 日 16:00 | 断签保护卡发放 | `scripts/grant-freeze-cards.mjs` | grant-freeze-cards |
| 30 8 | 16:30 | 任务健康检查 | `scripts/health-check.mjs` | health-check |
| 0 9 | 17:00 | 通知摘要生成 | `scripts/notification-digest.mjs` | notification-digest |
| 0 9 * * 1 | 周一 17:00 | 竞品工具数监测 | `scripts/competitor-monitor.mjs` | competitor-monitor |
| 0 10 | 18:00 | 行业趋势监测 | `scripts/trend-alert.mjs` | trend-alert |
| 0 10 * * 1 | 周一 18:00 | 周刊生成 | `scripts/newsletter-generate.mjs` | newsletter-generate |
| 30 10 * * 1 | 周一 18:30 | 每周推荐邮件 | `scripts/weekly-recommend-email.mjs` | weekly-recommend-email |
| 15 */6 | 每 6 小时 | 点赞计数对账 | `scripts/reconcile-like-counts.mjs` | reconcile-like-counts |
| 5 23,3,7,11,15 | 每日 7/11/15/19/23 点 | 行业素材采集 | `scripts/industry-thinktank.mjs collect --all` | industry-thinktank |
**已注释停用**：`bot-activity`、`bot-skill-crystallize`、`bot-affinity-update`、`bot-weekly-review`、`bot-feedback-loop`、`bot-adversarial-learning-run`、`bot-persona-experiment-run`、`bot-roundtable`、`industry-thinktank weekly/respond`、`industry-daily daily/respond`
（原因：2026-09-05 旧 Bot「模拟真人互刷」体系退役；2026-09-26 按要求关闭全部 AI 生成功能，行业情报改为需登录访问）
- 调度配置: `crontab.txt`（supercronic 格式），修改后需重建 cron 容器生效
- 日志目录: 容器内 `/app/logs/`（挂载到 Docker volume `zhuiguang_ai_bot_logs`）
- 日志目录: 容器内 `/app/logs/`；实际 Docker 卷名为 `zhuiguang-ai_bot-logs`（旧文档写 `zhuiguang_ai_bot_logs`，已过时）
- 定时任务脚本从 `scripts/` 目录直接执行，环境变量由容器 entrypoint 注入
- **新增任务必须同步四处**：`crontab.txt` + `scripts/<task>.mjs` + `scripts/seed-task-configs.mjs` + `scripts/health-check.mjs`
## AI日报新闻源
- **36kr** RSS (https://36kr.com/feed) — 国内科技资讯
@@ -300,6 +405,7 @@ docker logs --tail 50 zhuiguang-ai-cron # Cron 容器日志
- 敏感信息（密钥、密码、Token）必须使用环境变量，禁止硬编码
- `.env` 文件已被加入 `.gitignore`，仅 `.env.example` 模板可提交
- HTTP 响应必须包含安全头：CSP、HSTS、X-Content-Type-Options、X-Frame-Options
- CSP 的 `script-src` 必须包含 `'unsafe-inline'`（Next.js App Router 水合依赖内联 `self.__next_f` 脚本），禁止 `'unsafe-eval'`；详见 workspace 规则 7.1
- 文件上传/下载必须限制大小（最大 5MB）和类型，SVG 内容需消毒 script/iframe/on-event 标签
- Logo 文件名使用 SHA256 哈希（不使用 MD5）
- VIP 用户不能访问管理后台（/admin/* 和 /api/admin/*）
@@ -318,8 +424,10 @@ docker logs --tail 50 zhuiguang-ai-cron # Cron 容器日志
- 修改项目架构/技术栈/部署配置 → 更新 `追光AI` 或对应 `Module` 实体
- 新增/修改实体间关系 → 更新 Knowledge Graph 关系
- **同步时机**：在代码修改完成并通过检查后、提交代码前执行同步
- **同步方法**：使用 `mcp_Knowledge_Graph_Memory_create_entities`（新增实体）、`mcp_Knowledge_Graph_Memory_add_observations`（追加观察）、`mcp_Knowledge_Graph_Memory_update_entities`（更新实体）、`mcp_Knowledge_Graph_Memory_create_relations`（新增关系）、`mcp_Knowledge_Graph_Memory_delete_entities`/`delete_relations`/`delete_observations`（删除）
- **查询优先**：在开始任何开发任务前，先通过 `mcp_Knowledge_Graph_Memory_search_nodes` 或 `mcp_Knowledge_Graph_Memory_open_nodes` 查询图谱，利用已有知识加速开发
- **图谱存储**：`.trae/knowledge_graph.jsonl`（MCP 源文件，JSONL，一行一实体/关系）；`.trae/knowledge_graph.json` 为渲染版（`project` / `version` / `updated_at` / `entities` / `relations`）
- **MCP 配置**：`.trae/mcp.json` 注册 `Knowledge Graph Memory` 服务（`npx -y @itseasy21/mcp-knowledge-graph`，`MEMORY_FILE_PATH=.trae/knowledge_graph.jsonl`）
- **同步方法**：优先使用 `create_entities` / `add_observations` / `update_entities` / `create_relations` / `delete_entities` 等工具；若 MCP 未挂载，直接维护 `.trae/knowledge_graph.jsonl`
- **查询优先**：在开始任何开发任务前，先通过 `search_nodes` / `open_nodes` 查询图谱，利用已有知识加速开发
### 7. 可靠性原则
- 所有外部 API 调用（GitHub、DeepSeek 等）必须设置超时和重试