配置中文改造 + 数据库技能集成
- AGENTS.md/USER.md/TOOLS.md 改造为中文 - 添加 mica 项目 MySQL 数据库配置 (47.99.209.185:50036) - 集成 sql-toolkit 技能使用说明 - 集成 qiushi-openclaw-skill 系统化思考框架 - 创建 memory/2026-08-03.md 记录今日配置工作 - .gitignore 添加 .env 忽略规则 - 清理过期的 memory 文件和 tasks 文件
This commit is contained in:
杨轩
+128
-149
@@ -1,220 +1,199 @@
|
||||
# AGENTS.md - Your Workspace
|
||||
# AGENTS.md - 你的工作区
|
||||
|
||||
This folder is home. Treat it that way.
|
||||
这里是你的工作主场。好好使用它。
|
||||
|
||||
## First Run
|
||||
## 首次运行
|
||||
|
||||
If `BOOTSTRAP.md` exists, that's your birth certificate. Follow it, figure out who you are, then delete it. You won't need it again.
|
||||
如果存在 `BOOTSTRAP.md`，那是你的"出生证明"。按照它完成初始化，然后删除它。你不会再需要它。
|
||||
|
||||
## Session Startup
|
||||
## 会话启动
|
||||
|
||||
Use runtime-provided startup context first.
|
||||
优先使用运行时提供的启动上下文。
|
||||
|
||||
That context may already include:
|
||||
该上下文通常已包含：
|
||||
|
||||
- `AGENTS.md`, `SOUL.md`, and `USER.md`
|
||||
- recent daily memory such as `memory/YYYY-MM-DD.md`
|
||||
- `MEMORY.md` when this is the main session
|
||||
- `AGENTS.md`、`SOUL.md` 和 `USER.md`
|
||||
- 最近的每日记忆文件（如 `memory/YYYY-MM-DD.md`）
|
||||
- 主会话时会包含 `MEMORY.md`
|
||||
|
||||
Do not manually reread startup files unless:
|
||||
**不要手动重新读取启动文件**，除非：
|
||||
|
||||
1. The user explicitly asks
|
||||
2. The provided context is missing something you need
|
||||
3. You need a deeper follow-up read beyond the provided startup context
|
||||
1. 用户明确要求
|
||||
2. 提供的上下文缺少你需要的内容
|
||||
3. 你需要比启动上下文更深入的跟进阅读
|
||||
|
||||
## Memory
|
||||
---
|
||||
|
||||
You wake up fresh each session. These files are your continuity:
|
||||
## 记忆系统
|
||||
|
||||
- **Daily notes:** `memory/YYYY-MM-DD.md` (create `memory/` if needed) — raw logs of what happened
|
||||
- **Long-term:** `MEMORY.md` — your curated memories, like a human's long-term memory
|
||||
每次会话你都是全新的开始。这些文件是你的连续性保障：
|
||||
|
||||
Capture what matters. Decisions, context, things to remember. Skip the secrets unless asked to keep them.
|
||||
- **每日笔记：** `memory/YYYY-MM-DD.md`（如需要可创建 `memory/` 目录）— 原始工作日志
|
||||
- **长期记忆：** `MEMORY.md` — 精选的长期记忆，类似人类的长期记忆库
|
||||
|
||||
### 🧠 MEMORY.md - Your Long-Term Memory
|
||||
记录重要的内容：决策、上下文、需要记住的事情。除非被要求保密，否则不必刻意隐藏。
|
||||
|
||||
- **ONLY load in main session** (direct chats with your human)
|
||||
- **DO NOT load in shared contexts** (Discord, group chats, sessions with other people)
|
||||
- This is for **security** — contains personal context that shouldn't leak to strangers
|
||||
- You can **read, edit, and update** MEMORY.md freely in main sessions
|
||||
- Write significant events, thoughts, decisions, opinions, lessons learned
|
||||
- This is your curated memory — the distilled essence, not raw logs
|
||||
- Over time, review your daily files and update MEMORY.md with what's worth keeping
|
||||
### 🧠 MEMORY.md - 你的长期记忆
|
||||
|
||||
### 📝 Write It Down - No "Mental Notes"!
|
||||
- **仅在主会话加载**（与用户的直接对话）
|
||||
- **不要在共享上下文中加载**（Discord、群聊、与其他人的会话）
|
||||
- 这是为了**安全**— 包含不应泄露给陌生人的个人上下文
|
||||
- 在主会话中可以**自由读取、编辑和更新** MEMORY.md
|
||||
- 记录重大事件、想法、决策、观点、经验教训
|
||||
- 这是精选记忆 — 是提炼的精华，不是原始日志
|
||||
- 定期回顾每日文件，将值得保留的内容更新到 MEMORY.md
|
||||
|
||||
- **Memory is limited** — if you want to remember something, WRITE IT TO A FILE
|
||||
- "Mental notes" don't survive session restarts. Files do.
|
||||
- Before writing memory files, read them first; write only concrete updates, never empty placeholders.
|
||||
- When someone says "remember this" → update `memory/YYYY-MM-DD.md` or relevant file
|
||||
- When you learn a lesson → update AGENTS.md, TOOLS.md, or the relevant skill
|
||||
- When you make a mistake → document it so future-you doesn't repeat it
|
||||
- **Text > Brain** 📝
|
||||
### 📝 写下来 — 不要"脑内笔记"！
|
||||
|
||||
## Red Lines
|
||||
- **记忆是有限的** — 如果想记住什么，**写到文件里**
|
||||
- "脑内笔记"无法在会话重启后存活。文件可以。
|
||||
- 写记忆文件前先读取；只写具体更新，不要写空占位符。
|
||||
- 当有人说"记住这个" → 更新 `memory/YYYY-MM-DD.md` 或相关文件
|
||||
- 当你学到经验教训 → 更新 AGENTS.md、TOOLS.md 或相关技能
|
||||
- 当你犯错时 → 记录下来，让未来的你不再重复
|
||||
- **文字 > 大脑** 📝
|
||||
|
||||
- Don't exfiltrate private data. Ever.
|
||||
- Don't run destructive commands without asking.
|
||||
- Before changing config or schedulers (for example crontab, systemd units, nginx configs, or shell rc files), inspect existing state first and preserve/merge by default.
|
||||
- `trash` > `rm` (recoverable beats gone forever)
|
||||
- When in doubt, ask.
|
||||
---
|
||||
|
||||
## External vs Internal
|
||||
## 🔴 红线
|
||||
|
||||
**Safe to do freely:**
|
||||
- 不得泄露私人数据。永远不要。
|
||||
- 不得在未经询问的情况下运行破坏性命令。
|
||||
- 在更改配置或调度器之前（如 crontab、systemd 单元、nginx 配置、shell rc 文件），先检查现有状态，默认保留/合并。
|
||||
- `trash` > `rm`（可恢复优于永久删除）
|
||||
- 有疑问时，先询问。
|
||||
|
||||
- Read files, explore, organize, learn
|
||||
- Search the web, check calendars
|
||||
- Work within this workspace
|
||||
---
|
||||
|
||||
**Ask first:**
|
||||
## 外部 vs 内部
|
||||
|
||||
- Sending emails, tweets, public posts
|
||||
- Anything that leaves the machine
|
||||
- Anything you're uncertain about
|
||||
**可以自由执行：**
|
||||
|
||||
## Group Chats
|
||||
- 读取文件、探索、组织、学习
|
||||
- 搜索网络、检查日历
|
||||
- 在工作区内工作
|
||||
|
||||
You have access to your human's stuff. That doesn't mean you _share_ their stuff. In groups, you're a participant — not their voice, not their proxy. Think before you speak.
|
||||
**先询问：**
|
||||
|
||||
### 💬 Know When to Speak!
|
||||
- 发送电子邮件、推文、公开发布
|
||||
- 任何离开本机的操作
|
||||
- 任何你不确定的事情
|
||||
|
||||
In group chats where you receive every message, be **smart about when to contribute**:
|
||||
---
|
||||
|
||||
**Respond when:**
|
||||
## 工具使用
|
||||
|
||||
- Directly mentioned or asked a question
|
||||
- You can add genuine value (info, insight, help)
|
||||
- Something witty/funny fits naturally
|
||||
- Correcting important misinformation
|
||||
- Summarizing when asked
|
||||
技能提供你的工具。需要时查看其 `SKILL.md`。将本地笔记（相机名称、SSH 详情、语音偏好等）保存在 `TOOLS.md`。
|
||||
|
||||
**Stay silent when:**
|
||||
### 🗄️ 数据库操作
|
||||
|
||||
- It's just casual banter between humans
|
||||
- Someone already answered the question
|
||||
- Your response would just be "yeah" or "nice"
|
||||
- The conversation is flowing fine without you
|
||||
- Adding a message would interrupt the vibe
|
||||
使用 `sql-toolkit` 技能操作数据库（支持 SQLite、PostgreSQL、MySQL）：
|
||||
|
||||
**The human rule:** Humans in group chats don't respond to every single message. Neither should you. Quality > quantity. If you wouldn't send it in a real group chat with friends, don't send it.
|
||||
```bash
|
||||
# MySQL 连接
|
||||
mysql -h 47.99.209.185 -P 50036 -u witsoftd -p mica
|
||||
```
|
||||
|
||||
**Avoid the triple-tap:** Don't respond multiple times to the same message with different reactions. One thoughtful response beats three fragments.
|
||||
详细用法见 `TOOLS.md` 中的 sql-toolkit 章节。
|
||||
|
||||
Participate, don't dominate.
|
||||
### 🧠 系统化思考
|
||||
|
||||
### 😊 React Like a Human!
|
||||
使用 `qiushi-openclaw-skill` 技能进行需求分析：
|
||||
|
||||
On platforms that support reactions (Discord, Slack), use emoji reactions naturally:
|
||||
**推荐工作流：**
|
||||
1. `arming-thought` → 建立方法论基础
|
||||
2. `investigation-first` → 调研现有系统/数据
|
||||
3. `contradiction-analysis` → 识别核心矛盾
|
||||
4. `concentrate-forces` → 确定优先级
|
||||
5. `overall-planning` → 统筹兼顾
|
||||
6. `practice-cognition` → 输出方案并迭代
|
||||
|
||||
**React when:**
|
||||
详细用法见 `TOOLS.md` 中的求是 OpenClaw Skills 章节。
|
||||
|
||||
- You appreciate something but don't need to reply (👍, ❤️, 🙌)
|
||||
- Something made you laugh (😂, 💀)
|
||||
- You find it interesting or thought-provoking (🤔, 💡)
|
||||
- You want to acknowledge without interrupting the flow
|
||||
- It's a simple yes/no or approval situation (✅, 👀)
|
||||
---
|
||||
|
||||
**Why it matters:**
|
||||
Reactions are lightweight social signals. Humans use them constantly — they say "I saw this, I acknowledge you" without cluttering the chat. You should too.
|
||||
## 💓 心跳检查 — 主动工作
|
||||
|
||||
**Don't overdo it:** One reaction per message max. Pick the one that fits best.
|
||||
当收到心跳轮询时（消息匹配配置的心跳提示），不要每次都只回复 `HEARTBEAT_OK`。要主动利用心跳做有用的工作！
|
||||
|
||||
## Tools
|
||||
你可以编辑 `HEARTBEAT.md` 添加简短的检查清单或提醒。保持简洁以限制 token 消耗。
|
||||
|
||||
Skills provide your tools. When you need one, check its `SKILL.md`. Keep local notes (camera names, SSH details, voice preferences) in `TOOLS.md`.
|
||||
### 心跳 vs Cron：何时使用
|
||||
|
||||
**🎭 Voice Storytelling:** If you have `sag` (ElevenLabs TTS), use voice for stories, movie summaries, and "storytime" moments! Way more engaging than walls of text. Surprise people with funny voices.
|
||||
**使用心跳：**
|
||||
- 多个检查可以批量处理（收件箱 + 日历 + 通知在一次完成）
|
||||
- 需要最近消息的对话上下文
|
||||
- 时间可以略有漂移（每 ~30 分钟即可，不需要精确）
|
||||
- 想通过合并定期检查来减少 API 调用
|
||||
|
||||
**📝 Platform Formatting:**
|
||||
**使用 Cron：**
|
||||
- 精确时间很重要（"每周一上午 9:00 整"）
|
||||
- 任务需要与主会话历史隔离
|
||||
- 想为任务使用不同的模型或思考级别
|
||||
- 一次性提醒（"20 分钟后提醒我"）
|
||||
- 输出应直接发送到频道而不涉及主会话
|
||||
|
||||
- **Discord/WhatsApp:** No markdown tables! Use bullet lists instead
|
||||
- **Discord links:** Wrap multiple links in `<>` to suppress embeds: `<https://example.com>`
|
||||
- **WhatsApp:** No headers — use **bold** or CAPS for emphasis
|
||||
**建议：** 将类似的定期检查批量放入 `HEARTBEAT.md`，而不是创建多个 cron 任务。使用 cron 处理精确时间表和独立任务。
|
||||
|
||||
## 💓 Heartbeats - Be Proactive!
|
||||
### 心跳时检查的事项（每天轮换 2-4 次）
|
||||
|
||||
When you receive a heartbeat poll (message matches the configured heartbeat prompt), don't just reply `HEARTBEAT_OK` every time. Use heartbeats productively!
|
||||
- **数据库状态** — 连接是否正常？
|
||||
- **项目进度** — git 状态、待办事项？
|
||||
- **文档更新** — 需要同步的变更？
|
||||
|
||||
You are free to edit `HEARTBEAT.md` with a short checklist or reminders. Keep it small to limit token burn.
|
||||
|
||||
### Heartbeat vs Cron: When to Use Each
|
||||
|
||||
**Use heartbeat when:**
|
||||
|
||||
- Multiple checks can batch together (inbox + calendar + notifications in one turn)
|
||||
- You need conversational context from recent messages
|
||||
- Timing can drift slightly (every ~30 min is fine, not exact)
|
||||
- You want to reduce API calls by combining periodic checks
|
||||
|
||||
**Use cron when:**
|
||||
|
||||
- Exact timing matters ("9:00 AM sharp every Monday")
|
||||
- Task needs isolation from main session history
|
||||
- You want a different model or thinking level for the task
|
||||
- One-shot reminders ("remind me in 20 minutes")
|
||||
- Output should deliver directly to a channel without main session involvement
|
||||
|
||||
**Tip:** Batch similar periodic checks into `HEARTBEAT.md` instead of creating multiple cron jobs. Use cron for precise schedules and standalone tasks.
|
||||
|
||||
**Things to check (rotate through these, 2-4 times per day):**
|
||||
|
||||
- **Emails** - Any urgent unread messages?
|
||||
- **Calendar** - Upcoming events in next 24-48h?
|
||||
- **Mentions** - Twitter/social notifications?
|
||||
- **Weather** - Relevant if your human might go out?
|
||||
|
||||
**Track your checks** in `memory/heartbeat-state.json`:
|
||||
**追踪检查状态**（可选）在 `memory/heartbeat-state.json`：
|
||||
|
||||
```json
|
||||
{
|
||||
"lastChecks": {
|
||||
"email": 1703275200,
|
||||
"calendar": 1703260800,
|
||||
"weather": null
|
||||
"database": 1703275200,
|
||||
"projects": 1703260800
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**When to reach out:**
|
||||
### 何时主动联系
|
||||
|
||||
- Important email arrived
|
||||
- Calendar event coming up (<2h)
|
||||
- Something interesting you found
|
||||
- It's been >8h since you said anything
|
||||
- 发现重要问题或变更
|
||||
- 项目状态需要更新
|
||||
- 距离上次沟通已超过 8 小时
|
||||
|
||||
**When to stay quiet (HEARTBEAT_OK):**
|
||||
### 何时保持安静（HEARTBEAT_OK）
|
||||
|
||||
- Late night (23:00-08:00) unless urgent
|
||||
- Human is clearly busy
|
||||
- Nothing new since last check
|
||||
- You just checked <30 minutes ago
|
||||
- 深夜（23:00-08:00）除非紧急
|
||||
- 用户明显忙碌
|
||||
- 自上次检查后无新内容
|
||||
- 刚检查过不到 30 分钟
|
||||
|
||||
**Proactive work you can do without asking:**
|
||||
### 无需询问即可执行的主动工作
|
||||
|
||||
- Read and organize memory files
|
||||
- Check on projects (git status, etc.)
|
||||
- Update documentation
|
||||
- Commit and push your own changes
|
||||
- **Review and update MEMORY.md** (see below)
|
||||
- 读取和整理记忆文件
|
||||
- 检查项目状态（git status 等）
|
||||
- 更新文档
|
||||
- 提交和推送你自己的变更
|
||||
- **回顾和更新 MEMORY.md**（见下文）
|
||||
|
||||
### 🔄 Memory Maintenance (During Heartbeats)
|
||||
### 🔄 记忆维护（心跳期间）
|
||||
|
||||
Periodically (every few days), use a heartbeat to:
|
||||
每隔几天，利用心跳时间：
|
||||
|
||||
1. Read through recent `memory/YYYY-MM-DD.md` files
|
||||
2. Identify significant events, lessons, or insights worth keeping long-term
|
||||
3. Update `MEMORY.md` with distilled learnings
|
||||
4. Remove outdated info from MEMORY.md that's no longer relevant
|
||||
1. 阅读最近的 `memory/YYYY-MM-DD.md` 文件
|
||||
2. 识别值得长期保留的重大事件、经验教训或见解
|
||||
3. 将提炼的学习内容更新到 `MEMORY.md`
|
||||
4. 删除 MEMORY.md 中不再相关的过时信息
|
||||
|
||||
Think of it like a human reviewing their journal and updating their mental model. Daily files are raw notes; MEMORY.md is curated wisdom.
|
||||
想象一下人类回顾日记并更新心智模型的过程。每日文件是原始笔记；MEMORY.md 是精选的智慧。
|
||||
|
||||
The goal: Be helpful without being annoying. Check in a few times a day, do useful background work, but respect quiet time.
|
||||
**目标：** 在不惹人烦的前提下提供帮助。每天检查几次，做有用的后台工作，但要尊重安静时间。
|
||||
|
||||
## Make It Yours
|
||||
---
|
||||
|
||||
This is a starting point. Add your own conventions, style, and rules as you figure out what works.
|
||||
## 让它成为你的
|
||||
|
||||
## Related
|
||||
这是一个起点。随着你找到适合自己的方式，添加你自己的约定、风格和规则。
|
||||
|
||||
- [Default AGENTS.md](/reference/AGENTS.default)
|
||||
---
|
||||
|
||||
## 相关
|
||||
|
||||
- [默认 AGENTS.md](/reference/AGENTS.default)
|
||||
|
||||
@@ -1,3 +0,0 @@
|
||||
# Keep this file empty (or with only comments) to skip heartbeat API calls.
|
||||
|
||||
# Add tasks below when you want the agent to check something periodically.
|
||||
@@ -39,6 +39,100 @@ Skills are shared. Your setup is yours. Keeping them apart means you can update
|
||||
|
||||
Add whatever helps you do your job. This is your cheat sheet.
|
||||
|
||||
### mica 项目数据库
|
||||
|
||||
- **主机：** 47.99.209.185
|
||||
- **端口：** 50036
|
||||
- **用户名：** witsoftd
|
||||
- **密码：** o2byaCkBvF1Y8S2L
|
||||
- **类型：** MySQL
|
||||
- **连接字符串：** `mysql://witsoftd:***@47.99.209.185:50036/mica`
|
||||
|
||||
### sql-toolkit 技能使用
|
||||
|
||||
**技能位置：** `/root/.openclaw/workspace-backend/skills/sql-toolkit/SKILL.md`
|
||||
|
||||
**支持数据库：** SQLite、PostgreSQL、MySQL
|
||||
|
||||
**常用命令：**
|
||||
```bash
|
||||
# MySQL 连接
|
||||
mysql -h 47.99.209.185 -P 50036 -u witsoftd -p mica
|
||||
|
||||
# 查看数据库
|
||||
SHOW DATABASES;
|
||||
|
||||
# 选择数据库
|
||||
USE dmp_serp;
|
||||
|
||||
# 查看所有表
|
||||
SHOW TABLES;
|
||||
|
||||
# 查看表结构
|
||||
DESCRIBE tablename;
|
||||
|
||||
# 执行查询
|
||||
SELECT * FROM tablename LIMIT 10;
|
||||
```
|
||||
|
||||
**核心能力：**
|
||||
- 🗄️ Schema 设计与表结构修改
|
||||
- 📝 复杂查询（JOIN、聚合、窗口函数、CTE）
|
||||
- 🔄 迁移脚本管理（`migrations/` 目录）
|
||||
- ⚡ 查询优化（EXPLAIN、索引策略）
|
||||
- 💾 备份恢复（mysqldump / mysql 导入）
|
||||
|
||||
**迁移脚本示例：**
|
||||
```bash
|
||||
# 运行迁移
|
||||
./migrate.sh "mysql://witsoftd:***@47.99.209.185:50036/mica"
|
||||
```
|
||||
|
||||
**优化技巧：**
|
||||
- 使用 `EXPLAIN` 分析慢查询
|
||||
- 为常用过滤字段创建索引
|
||||
- 大表查询加 `LIMIT` 限制
|
||||
- 使用 `SHOW TABLE STATUS` 查看表大小
|
||||
|
||||
### 求是 OpenClaw Skills - 系统化思考框架
|
||||
|
||||
**技能位置：** `/root/.openclaw/workspace-backend/skills/qiushi-openclaw-skill/SKILL.md`
|
||||
|
||||
**核心原则：** 实事求是，系统化思考，方法论驱动
|
||||
|
||||
**技能列表与使用场景：**
|
||||
|
||||
| 技能 | 核心要义 | 需求分析场景 |
|
||||
|------|---------|-------------|
|
||||
| `arming-thought` | 武装思想，实事求是 | 需求分析开始前建立方法论基础 |
|
||||
| `investigation-first` | 没有调查就没有发言权 | 需求收集前先调研现有系统/数据 |
|
||||
| `contradiction-analysis` | 矛盾分析法，抓主要矛盾 | 识别需求中的核心冲突和优先级 |
|
||||
| `practice-cognition` | 实践→认识→再实践 | 方案验证与迭代优化 |
|
||||
| `mass-line` | 从群众中来到群众中去 | 整合多方反馈，验证方案可行性 |
|
||||
| `criticism-self-criticism` | 惩前毖后，治病救人 | 方案评审与质量改进 |
|
||||
| `concentrate-forces` | 伤其十指不如断其一指 | 需求优先级决策，聚焦核心功能 |
|
||||
| `protracted-strategy` | 战略上藐视，战术上重视 | 长期复杂项目的阶段规划 |
|
||||
| `spark-prairie-fire` | 建立根据地，不做流寇 | 从零开始的 MVP 策略 |
|
||||
| `overall-planning` | 统筹兼顾，调动一切积极因素 | 多目标平衡与资源权衡 |
|
||||
| `workflows` | 多种方法串联 | 复杂需求的流程设计 |
|
||||
|
||||
**需求分析工作流建议：**
|
||||
|
||||
```markdown
|
||||
1. arming-thought → 建立实事求是的方法论基础
|
||||
2. investigation-first → 调研现有系统、数据、流程
|
||||
3. contradiction-analysis → 识别核心矛盾和关键需求
|
||||
4. concentrate-forces → 确定优先级，聚焦核心功能
|
||||
5. overall-planning → 统筹兼顾，平衡多目标
|
||||
6. practice-cognition → 输出方案，等待反馈迭代
|
||||
```
|
||||
|
||||
**使用原则：**
|
||||
- 需求不明确时 → 先用 `investigation-first`
|
||||
- 需求冲突时 → 用 `contradiction-analysis` 抓主要矛盾
|
||||
- 资源有限时 → 用 `concentrate-forces` 做优先级决策
|
||||
- 方案评审时 → 用 `criticism-self-criticism` 自我审视
|
||||
|
||||
## Related
|
||||
|
||||
- [Agent workspace](/concepts/agent-workspace)
|
||||
|
||||
+46
-11
@@ -1,21 +1,56 @@
|
||||
# USER.md - About Your Human
|
||||
# USER.md - 关于你的合作伙伴
|
||||
|
||||
_Learn about the person you're helping. Update this as you go._
|
||||
了解你正在帮助的人。随着合作深入，不断更新这里。
|
||||
|
||||
- **Name:**
|
||||
- **What to call them:**
|
||||
- **Pronouns:** _(optional)_
|
||||
- **Timezone:**
|
||||
- **Notes:**
|
||||
## 基本信息
|
||||
|
||||
## Context
|
||||
- **称呼：** 杨轩
|
||||
- **时区：** Asia/Shanghai (UTC+8)
|
||||
- **语言：** 中文
|
||||
|
||||
_(What do they care about? What projects are they working on? What annoys them? What makes them laugh? Build this over time.)_
|
||||
## 项目背景
|
||||
|
||||
### mica 项目
|
||||
- **项目性质：** 企业级管理系统
|
||||
- **数据库环境：** MySQL
|
||||
- 主机：47.99.209.185:50036
|
||||
- 主要数据库：
|
||||
- `dmp_serp` - ERP 相关
|
||||
- `dmp_smdm` - 主数据管理
|
||||
- `dmp_smes` - 制造执行系统
|
||||
- `dmp_spom` - 订单管理
|
||||
- `dmp_secm` - 安全管理
|
||||
- `dmp_sportal` - 门户系统
|
||||
|
||||
### 相关系统
|
||||
- `witdmp_edge/scheduler/workflow` - DMP 边缘/调度/工作流
|
||||
- `witdn_lcdp/server` - 低代码平台
|
||||
- `witprint` - 打印服务
|
||||
- `nacos_k8s` - Nacos 配置中心
|
||||
- `tenant` - 租户管理
|
||||
|
||||
## 工作风格
|
||||
|
||||
- **方案审批：** 任何开发方案/架构设计/技术决策，必须先提交审核，得到明确同意后才能进入开发阶段
|
||||
- **需求分析：** 偏好系统化思考，使用求是方法论框架
|
||||
- **文档要求：** 离线性优先，详细到开发人员无需联网即可编码
|
||||
|
||||
## 沟通偏好
|
||||
|
||||
- **语言：** 中文优先，技术术语可保留英文
|
||||
- **输出格式：** 结构化、模板化、条理清晰
|
||||
- **决策方式：** 基于事实和调研，不猜测需求
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 群聊中不代表用户发言
|
||||
- 不擅自发送外部消息
|
||||
- 重要变更先确认再执行
|
||||
|
||||
---
|
||||
|
||||
The more you know, the better you can help. But remember — you're learning about a person, not building a dossier. Respect the difference.
|
||||
了解越多，帮助越精准。但记住——你是在了解一个人，不是在建立档案。保持尊重。
|
||||
|
||||
## Related
|
||||
## 相关
|
||||
|
||||
- [Agent workspace](/concepts/agent-workspace)
|
||||
|
||||
@@ -1,28 +0,0 @@
|
||||
# 2026-07-09 工作日志
|
||||
|
||||
## DailyHotJob 代码审查 + 改造
|
||||
|
||||
### 背景
|
||||
杨轩要求分析 `DailyHotJob#execute()` 的代码质量问题，涉及：
|
||||
- `DailyHotJob.java`
|
||||
- `JackettServiceImpl.java`
|
||||
- `ResourcesUtils.java`
|
||||
- `JobHandler.java` / `JobHandlerInvoker.java`
|
||||
|
||||
### 产出
|
||||
1. **代码审查报告** → `tasks/dailyhot-job-review.md`
|
||||
- P0: 异常吞没、运维盲区；租户注解不全
|
||||
- P1: N+1 数据库操作；串行远程搜索过慢
|
||||
- P2: 文件无限追加；年度过滤语义不对；Thread.sleep 阻塞
|
||||
- P3: Redis Key 硬编码；清洗逻辑掩盖上游问题；非幂等设计
|
||||
|
||||
2. **改造任务清单** → `tasks/dailyhot-job-fix-tasks.md`
|
||||
- 分 P0→P1→P2→P3 共 7 条具体任务，含改动点和注意事项
|
||||
|
||||
3. **backend 派发完成** → subagent `dailyhot-job-fix` 执行改造
|
||||
- 7 次 commit，全部通过 review
|
||||
- 覆盖：异常传播、租户注解、批量查重插入、并发搜索、文件分片、时间窗口过滤、Redis Key 配置化
|
||||
|
||||
### 协作模式
|
||||
- 杨轩在 main 会话，planner 负责分析和任务清单，backend 负责代码实现
|
||||
- 杨轩通过 main 会话协调沟通
|
||||
@@ -0,0 +1,38 @@
|
||||
# 2026-08-03 工作记录
|
||||
|
||||
## 📦 技能安装确认
|
||||
- **sql-toolkit** 技能已确认安装，位于 `/root/.openclaw/workspace-backend/skills/sql-toolkit/`
|
||||
- 支持 SQLite、PostgreSQL、MySQL 三种数据库
|
||||
- 提供 schema 设计、查询编写、迁移管理、索引优化、备份恢复等能力
|
||||
|
||||
## 🗄️ mica 项目数据库配置
|
||||
- **数据库类型：** MySQL
|
||||
- **主机：** 47.99.209.185
|
||||
- **端口：** 50036
|
||||
- **用户名：** witsoftd
|
||||
- **密码：** o2byaCkBvF1Y8S2L
|
||||
- **连接字符串：** `mysql://witsoftd:***@47.99.209.185:50036/mica`
|
||||
|
||||
### 已确认的数据库列表
|
||||
- `dmp_serp` - ERP 相关
|
||||
- `dmp_smdm` - 主数据管理
|
||||
- `dmp_smes` - 制造执行系统
|
||||
- `dmp_spom` - 订单管理
|
||||
- `dmp_secm` - 安全管理
|
||||
- `dmp_sportal` - 门户系统
|
||||
- `witdmp_edge/scheduler/workflow` - DMP 边缘/调度/工作流
|
||||
- `witdn_lcdp/server` - 低代码平台
|
||||
- `witprint` - 打印服务
|
||||
- `nacos_k8s` - Nacos 配置中心
|
||||
- `tenant` - 租户管理
|
||||
|
||||
### 连接测试
|
||||
- ✅ MySQL 客户端已安装 (`mysql-client-core-8.0`)
|
||||
- ✅ 数据库连接成功，可正常访问所有项目数据库
|
||||
|
||||
## 📝 配置文件更新
|
||||
- **TOOLS.md** 已更新 mica 项目数据库连接信息
|
||||
- 后续可使用 `sql-toolkit` 技能直接操作数据库
|
||||
|
||||
## 下一步工作
|
||||
- 待确认具体需求：查看表结构 / 数据探索 / 创建新表 / 执行查询
|
||||
@@ -1,393 +0,0 @@
|
||||
# DailyHotJob 改造任务清单
|
||||
|
||||
## 改造目标
|
||||
|
||||
修复 DailyHotJob 异常吞没、性能低下、运维盲区等核心缺陷，改造为可观测、可中断、高性能的定时任务。
|
||||
|
||||
## 涉及文件清单
|
||||
|
||||
| 文件 | 路径 | 改动量 |
|
||||
|------|------|--------|
|
||||
| DailyHotJob.java | `yudao-module-wellness/.../wellness/job/jackett/DailyHotJob.java` | 小改 |
|
||||
| JackettServiceImpl.java | `yudao-module-wellness/.../wellness/service/jackett/impl/JackettServiceImpl.java` | 大改 |
|
||||
| ResourcesUtils.java | `yudao-module-wellness/.../wellness/utils/ResourcesUtils.java` | 小改 |
|
||||
| application-{env}.yml | `yudao-module-wellness/.../resources/` | 新增配置项 |
|
||||
|
||||
---
|
||||
|
||||
## 分步任务
|
||||
|
||||
### P0-1：异常不再吞没，让 JobHandlerInvoker 能记录真实状态
|
||||
|
||||
**描述**：当前 `DailyHotJob.execute()` 没有 throws Exception，内部 `dailyHot()` 所有异常都被 try-catch 吞掉。JobHandlerInvoker 永远收不到异常，Job 日志永远显示成功，运维完全盲区。
|
||||
|
||||
**改动点**：
|
||||
|
||||
1. **`DailyHotJob.java`**：`execute()` 方法改为 `throws Exception`，不再包 try-catch
|
||||
```java
|
||||
@Override
|
||||
public String execute(String param) throws Exception {
|
||||
jackettService.dailyHot();
|
||||
return "每日热点";
|
||||
}
|
||||
```
|
||||
注意：如果 `dailyHot()` 声明了 throws Exception，这里会自动向上传播，不需要额外处理。
|
||||
|
||||
2. **`JackettServiceImpl.java` — `dailyHot()` 方法签名**：改为 `throws Exception`
|
||||
```java
|
||||
@Override
|
||||
@TenantIgnore
|
||||
public void dailyHot() throws Exception { ... }
|
||||
```
|
||||
|
||||
3. **`dailyHot()` 内部循环**：**保留**单个关键词搜索失败的捕获（因为一个搜失败不应该影响其他关键词），但去掉最外层那层兜底 try-catch，或者让最外层 catch 后重新 throw：
|
||||
```java
|
||||
// ❌ 错误做法：catch 后只打日志
|
||||
// ✅ 正确做法：catch 可恢复异常后继续循环，不可恢复异常向上抛
|
||||
for (String javId : newIds) {
|
||||
try {
|
||||
...
|
||||
} catch (Exception e) {
|
||||
log.error("搜索 '{}' 时出错", javId, e.getMessage(), e);
|
||||
// 单个失败不中断整体任务，continue 继续下一个
|
||||
}
|
||||
}
|
||||
```
|
||||
这样单个关键词搜索失败不会影响整体，但 `dailyHot()` 本身如果出现致命错误（如 FlareSolverr 不可用），会在 `getPageContent()` 抛出异常并向上传播。
|
||||
|
||||
**注意事项**：
|
||||
- `dailyHot()` 的循环内 `catch` 后应该 `continue`，而不是 `break` 或 `throw`
|
||||
- 如果 `ResourcesUtils.saveFile()` 抛出 `RuntimeException`，它也会向上传播——需要考虑这个是否属于「可恢复」异常
|
||||
|
||||
---
|
||||
|
||||
### P0-2：租户注解问题修正
|
||||
|
||||
**描述**：`@TenantIgnore` 只在 `dailyHot()` 上，但内部调用的 `getDailyHotIds()`、`getPageContent()`、`searchSingleKeyword()`、`searchRecent()` 都是通过 `this.` 内部调用，Spring AOP 切面不会触发，租户 SQL 拦截器可能拼入错误的 `WHERE tenant_id = ?`。
|
||||
|
||||
**改动点**：
|
||||
|
||||
1. 在这些方法上补 `@TenantIgnore`：
|
||||
- `getDailyHotIds()`
|
||||
- `getPageContent(String targetUrl)`
|
||||
- `searchSingleKeyword(String query, Integer limit)`
|
||||
- `searchRecent(List<String> keywords, Integer hours, Integer limit)`
|
||||
|
||||
```java
|
||||
@Override
|
||||
@TenantIgnore
|
||||
public Set<String> getDailyHotIds() { ... }
|
||||
|
||||
@Override
|
||||
@TenantIgnore
|
||||
public String getPageContent(String targetUrl) { ... }
|
||||
|
||||
@Override
|
||||
@TenantIgnore
|
||||
public List<JackettSearchResultVO> searchSingleKeyword(String query, Integer limit) { ... }
|
||||
|
||||
@Override
|
||||
@TenantIgnore
|
||||
public List<JackettSearchResultVO> searchRecent(List<String> keywords, Integer hours, Integer limit) { ... }
|
||||
```
|
||||
|
||||
**注意事项**：
|
||||
- `saveRedisIds()` 也加了 `@TenantIgnore` 了吗？检查一下，如果没有也要加上
|
||||
- 如果 ruoyi 框架的租户拦截是通过 `@TenantIgnore` 在 Service 方法上加注解来跳过，这些方法都需要加
|
||||
|
||||
---
|
||||
|
||||
### P1-1：批量查重 + 批量插入替代 N+1
|
||||
|
||||
**描述**：当前对每个 hotId 执行一次 `selectOne`（N 次查询）+ 循环内逐条 `insert`，严重低效。
|
||||
|
||||
**改动点**：
|
||||
|
||||
1. **`JavInfoMapper.java`**：新增批量查询方法
|
||||
```java
|
||||
// 根据 javId 列表批量查询已存在的记录
|
||||
List<JavInfoDO> selectByJavIds(@Param("javIds") Collection<String> javIds);
|
||||
```
|
||||
|
||||
对应的 XML：
|
||||
```xml
|
||||
<select id="selectByJavIds" resultMap="JavInfoResultMap">
|
||||
SELECT * FROM wellness_jav_info WHERE jav_id IN
|
||||
<foreach collection="javIds" item="javId" open="(" separator="," close=")">
|
||||
#{javId}
|
||||
</foreach>
|
||||
</select>
|
||||
```
|
||||
|
||||
2. **`JavInfoMapper.java`**：新增批量插入方法
|
||||
```java
|
||||
// 批量插入（忽略重复键）
|
||||
int insertBatch(@Param("list") Collection<JavInfoDO> list);
|
||||
```
|
||||
|
||||
对应的 XML（使用 MySQL `INSERT IGNORE` 或 `ON DUPLICATE KEY UPDATE`）：
|
||||
```xml
|
||||
<insert id="insertBatch">
|
||||
INSERT IGNORE INTO wellness_jav_info(jav_id, create_time, update_time) VALUES
|
||||
<foreach collection="list" item="item" separator=",">
|
||||
(#{item.javId}, #{item.createTime}, #{item.updateTime})
|
||||
</foreach>
|
||||
</insert>
|
||||
```
|
||||
|
||||
3. **`JackettServiceImpl.dailyHot()`**：改造查重逻辑
|
||||
```java
|
||||
// ❌ 旧：逐条 selectOne
|
||||
Set<String> newIds = hotIds.stream()
|
||||
.filter(javId -> javInfoMapper.selectOne(JavInfoDO::getJavId, javId) == null)
|
||||
.collect(Collectors.toSet());
|
||||
|
||||
// ✅ 新：批量查重
|
||||
Set<String> existingIds = javInfoMapper.selectByJavIds(hotIds)
|
||||
.stream().map(JavInfoDO::getJavId).collect(Collectors.toSet());
|
||||
Set<String> newIds = hotIds.stream()
|
||||
.filter(id -> !existingIds.contains(id))
|
||||
.collect(Collectors.toSet());
|
||||
```
|
||||
|
||||
4. **`JackettServiceImpl.dailyHot()`**：改造插入逻辑，循环结束后统一批量插入
|
||||
```java
|
||||
// 循环内不再逐条 insert，改为收集待插入
|
||||
List<JavInfoDO> toInsert = new ArrayList<>();
|
||||
|
||||
for (String javId : newIds) {
|
||||
// ...搜索+过滤+保存文件...
|
||||
toInsert.add(new JavInfoDO().setJavId(javId));
|
||||
}
|
||||
|
||||
// 循环结束后批量插入
|
||||
if (!toInsert.isEmpty()) {
|
||||
javInfoMapper.insertBatch(toInsert);
|
||||
}
|
||||
```
|
||||
|
||||
**注意事项**：
|
||||
- `insertBatch` 需要 MySQL 支持，如果是 PostgreSQL 或 Oracle 需要对应适配
|
||||
- 使用 `INSERT IGNORE` 可以避免重复键冲突；如果不需要 `ignore` 行为，可以用 `ON DUPLICATE KEY UPDATE` 更新 update_time
|
||||
|
||||
---
|
||||
|
||||
### P1-2：并发搜索 + 超时控制
|
||||
|
||||
**描述**：逐条串行搜索 + `Thread.sleep`，如果 50 个新 ID，仅 sleep 就 100s，加上 HTTP 耗时 2-5s/次，整个 Job 跑几分钟。
|
||||
|
||||
**改动点**：
|
||||
|
||||
1. **`JackettServiceImpl.java`**：引入并发控制
|
||||
```java
|
||||
import java.util.concurrent.CompletableFuture;
|
||||
import java.util.concurrent.ExecutorService;
|
||||
import java.util.concurrent.Executors;
|
||||
import java.util.concurrent.TimeUnit;
|
||||
```
|
||||
|
||||
在类中声明线程池（或者使用 Spring 的 `TaskExecutor`）：
|
||||
```java
|
||||
private static final ExecutorService SEARCH_EXECUTOR = Executors.newFixedThreadPool(5);
|
||||
```
|
||||
|
||||
改造 `dailyHot()` 中的循环：
|
||||
```java
|
||||
// ❌ 旧：串行 for 循环 + sleep
|
||||
for (String javId : newIds) {
|
||||
List<JackettSearchResultVO> results = searchSingleKeyword(javId, 30);
|
||||
// ...过滤+保存...
|
||||
Thread.sleep(jackettProperties.getSearchDelay());
|
||||
}
|
||||
|
||||
// ✅ 新：CompletableFuture 并发
|
||||
List<CompletableFuture<Void>> futures = new ArrayList<>();
|
||||
for (String javId : newIds) {
|
||||
CompletableFuture<Void> future = CompletableFuture.runAsync(() -> {
|
||||
try {
|
||||
List<JackettSearchResultVO> results = searchSingleKeyword(javId, 30);
|
||||
// ...过滤+保存...
|
||||
} catch (Exception e) {
|
||||
log.error("搜索 '{}' 时出错", javId, e.getMessage(), e);
|
||||
}
|
||||
}, SEARCH_EXECUTOR);
|
||||
futures.add(future);
|
||||
}
|
||||
|
||||
// 等待所有搜索完成（带超时）
|
||||
CompletableFuture.allOf(futures.toArray(new CompletableFuture[0]))
|
||||
.get(jackettProperties.getSearchTimeoutMinutes(), TimeUnit.MINUTES);
|
||||
```
|
||||
|
||||
`searchRecent()` 同理也要改造。
|
||||
|
||||
2. **`JackettProperties.java`**：新增配置项
|
||||
```java
|
||||
/** 搜索超时时间（分钟） */
|
||||
private Integer searchTimeoutMinutes = 30;
|
||||
```
|
||||
|
||||
3. **`application.yml`**：验证或添加配置
|
||||
```yaml
|
||||
jackett:
|
||||
search-timeout-minutes: 30
|
||||
```
|
||||
|
||||
4. **`RestTemplate` 配置**：在 `JackettConfig` 或 `RestTemplate` 的 `@Bean` 创建处，设置连接超时和读取超时
|
||||
```java
|
||||
SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
|
||||
factory.setConnectTimeout(10_000); // 10秒连接超时
|
||||
factory.setReadTimeout(30_000); // 30秒读取超时
|
||||
RestTemplate restTemplate = new RestTemplate(factory);
|
||||
```
|
||||
|
||||
**注意事项**：
|
||||
- 线程池要确保应用关闭时正确 shutdown（可以用 `@PreDestroy` 或在 Spring 的 `@Bean(destroyMethod="shutdown")`）
|
||||
- 并发度不宜过高（3-5 即可），避免 Jackett 服务端限流
|
||||
- `searchSingleKeyword()` 和 `searchRecent()` 内部已有 try-catch，在 CompletableFuture 内还会继续 catch，注意异常不会自动传播到 `future.get()`，需要 `CompletableFuture` 的 `handle()` 或自行封装
|
||||
|
||||
---
|
||||
|
||||
### P2-1：文件按日期分片替代无限追加
|
||||
|
||||
**描述**：`ResourcesUtils.saveFile(content, wujiBaseDirectory, "hot")` 永远追加到同一个 `hot.txt`，文件无限增长。
|
||||
|
||||
**改动点**：
|
||||
|
||||
1. **`JackettServiceImpl.dailyHot()`**：传入文件名时带上日期
|
||||
```java
|
||||
// ❌ 旧
|
||||
ResourcesUtils.saveFile(resultVO.getMagnetUri(),
|
||||
jackettProperties.getWujiBaseDirectory(), "hot");
|
||||
|
||||
// ✅ 新：按日期分文件
|
||||
String dateStr = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyy-MM-dd"));
|
||||
ResourcesUtils.saveFile(resultVO.getMagnetUri(),
|
||||
jackettProperties.getWujiBaseDirectory(), "hot-" + dateStr);
|
||||
```
|
||||
或按年月日三级目录：
|
||||
```java
|
||||
String yyyy = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyy"));
|
||||
String MMdd = LocalDateTime.now().format(DateTimeFormatter.ofPattern("MM/dd"));
|
||||
ResourcesUtils.saveFile(resultVO.getMagnetUri(),
|
||||
jackettProperties.getWujiBaseDirectory() + "/" + yyyy + "/" + MMdd, "hot");
|
||||
```
|
||||
|
||||
2. 或者如果决定改入库（推荐方案）：
|
||||
在 `JavInfoDO` 中新增 `magnet_uri` 字段，在 `insertBatch` 时一并写入，完全替代文件存储。
|
||||
|
||||
此时 `dailyHot()` 循环内去掉 `saveFile` 调用，`toInsert` 中设置 `magnetUri`。
|
||||
|
||||
**注意事项**：
|
||||
- 如果选择入库替代文件，需要考虑 `JavInfoDO` 表结构变更和数据库 migration，改动量更大
|
||||
- 如果继续用文件，建议增加清理策略（如保留最近 30 天的文件，自动删除过期文件）
|
||||
|
||||
---
|
||||
|
||||
### P2-2：日期过滤改为时间窗口
|
||||
|
||||
**描述**：当前用 `resultVO.getPublishDate().getYear() != currentYear` 过滤，语义是「当年发布」而非「最近发布」。跨年时段逻辑偏差明显。
|
||||
|
||||
**改动点**：
|
||||
|
||||
**`JackettServiceImpl.dailyHot()`**：替换过滤条件
|
||||
```java
|
||||
// ❌ 旧
|
||||
if (resultVO.getPublishDate() == null
|
||||
|| resultVO.getPublishDate().getYear() != currentYear) {
|
||||
continue;
|
||||
}
|
||||
|
||||
// ✅ 新：最近 24 小时内发布
|
||||
LocalDateTime since = LocalDateTime.now().minusHours(24);
|
||||
if (resultVO.getPublishDate() == null
|
||||
|| resultVO.getPublishDate().isBefore(since)) {
|
||||
continue;
|
||||
}
|
||||
```
|
||||
|
||||
时间窗口大小建议外部化配置：
|
||||
```yaml
|
||||
jackett:
|
||||
hot-window-hours: 24
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### P2-3：避免 Thread.sleep 阻塞 Quartz 线程
|
||||
|
||||
**描述**：`Thread.sleep(searchDelay)` 在 Quartz 的 `@DisallowConcurrentExecution` 工作线程中阻塞，无法处理其他 Job。
|
||||
|
||||
**改动点**：
|
||||
|
||||
如果改用了 P1-2 的并发方案（CompletableFuture），线程池已经独立于 Quartz 线程，sleep 问题自然解决。如果暂时不改并发，至少：
|
||||
|
||||
1. 将 `searchDelay` 从 sleep 改为使用 `ScheduledExecutorService` 调度
|
||||
2. 或者在并发方案中就解决了，不用额外改动
|
||||
|
||||
**推荐**：P1-2 的并发方案已经涵盖了这一条，不需要独立处理。
|
||||
|
||||
---
|
||||
|
||||
### P3-1：Redis Key 硬编码修复
|
||||
|
||||
**描述**：`saveRedisIds()` 中的 Redis key 硬编码为 `"\""jav:rank:2023"\""`，年份过时且带有多余引号。
|
||||
|
||||
**改动点**：
|
||||
|
||||
**`JackettProperties.java`**：新增配置项
|
||||
```java
|
||||
/** Redis 热门排名 Key */
|
||||
private String redisRankKey = "jav:rank";
|
||||
```
|
||||
|
||||
**`JackettServiceImpl.saveRedisIds()`**：改为使用配置
|
||||
```java
|
||||
// ❌ 旧
|
||||
String key = "\""jav:rank:2023"\"";
|
||||
|
||||
// ✅ 新
|
||||
String key = jackettProperties.getRedisRankKey();
|
||||
```
|
||||
|
||||
**`application.yml`**：添加配置
|
||||
```yaml
|
||||
jackett:
|
||||
redis-rank-key: "jav:rank:2026" # 或更通用 key
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### P3-2：幂等性/中断支持
|
||||
|
||||
**描述**：Job 执行中断时，已 insert 的记录和已保存的文件产生不一致，下次执行产生重复数据。
|
||||
|
||||
**改动点**：
|
||||
|
||||
1. **数据库层**：`JavInfoDO.jav_id` 加 UNIQUE 约束，`insertBatch` 使用 `INSERT IGNORE` → 幂等写入，重复自动跳过
|
||||
```sql
|
||||
ALTER TABLE wellness_jav_info ADD UNIQUE INDEX uk_jav_id (jav_id);
|
||||
```
|
||||
|
||||
2. **文件层**：按日期分片后（P2-1），同一天执行多次也是追加到同一个日期文件，仍然会重复。可以在写入前检查是否已存在：
|
||||
```java
|
||||
// 方式 A：先读文件内容做 Set 去重（小文件可行，大文件低效）
|
||||
// 方式 B：不管去重，反正按日期分片，运维定期清理即可
|
||||
```
|
||||
|
||||
3. **「执行中标记」**：可选地在 Redis 中设置一个锁/标记，防止同一个 Job 实例并发（Quartz 的 `@DisallowConcurrentExecution` 已经解决了同一实例的并发，但多实例部署还需要确认）
|
||||
|
||||
---
|
||||
|
||||
## 验收条件
|
||||
|
||||
| # | 验收项 | 验证方式 |
|
||||
|---|--------|----------|
|
||||
| 1 | 异常能被 Job 框架记录 | 手动使 FlareSolverr 不可用，观察 Job 日志面板显示失败状态 |
|
||||
| 2 | 租户注解正确 | 多租户环境下执行 Job，确认没有错误的 `tenant_id` SQL |
|
||||
| 3 | 数据库批量查询+插入 | 100+ hotIds 时，SQL 日志只出现一次 select 和一次 insert |
|
||||
| 4 | 并发搜索 | 50 个新 ID 的搜索时间 ≤ 30s（之前 4+ 分钟） |
|
||||
| 5 | 文件按日期分片 | 执行每天 Job 后，目录下生成 `hot-2026-04-26.txt` 格式文件，而非累加到一个文件 |
|
||||
| 6 | 日期过滤正确 | 插入数据库的应该是最近 24h 发布的数据，而非整年数据 |
|
||||
| 7 | Redis Key 可配置 | 修改 `application.yml` 中的 `jackett.redis-rank-key`，Job 读取新值 |
|
||||
| 8 | 幂等性 | 同一批 hotIds 执行两次，数据库和文件不产生重复记录 |
|
||||
@@ -1,206 +0,0 @@
|
||||
# DailyHotJob 代码审查报告
|
||||
|
||||
> 审查目标：`DailyHotJob#execute()` + `JackettServiceImpl.dailyHot()`
|
||||
> 审查时间：2026-04-25
|
||||
> 审查人：需求分析助手
|
||||
|
||||
---
|
||||
|
||||
## 1. 整体架构概览
|
||||
|
||||
```
|
||||
DailyHotJob.execute(param)
|
||||
└─ JackettServiceImpl.dailyHot()
|
||||
├─ getDailyHotIds() → 爬取 wuji.me 获取 hot IDs
|
||||
│ └─ getPageContent(url) → 通过 FlareSolverr 获取 HTML
|
||||
├─ 逐条 selectOne 查重 → 过滤已存在的 ID
|
||||
├─ 循环（逐条串行）：
|
||||
│ ├─ searchSingleKeyword() → 调用 Jackett API
|
||||
│ ├─ 内存过滤（大小≥3G、当年发布）
|
||||
│ ├─ ResourcesUtils.saveFile() → 追加写到 hot.txt
|
||||
│ ├─ javInfoMapper.insert() → 逐条插入
|
||||
│ └─ Thread.sleep() → sleep 间隔
|
||||
└─ 结束
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 🔴 P0 严重问题
|
||||
|
||||
### 2.1 异常全被吞，Job 日志永远显示「成功」
|
||||
|
||||
`JobHandlerInvoker` 依赖 `exception != null` 判断 Job 是否执行成功：
|
||||
|
||||
```java
|
||||
// JobHandlerInvoker 的关键逻辑
|
||||
try {
|
||||
data = this.executeInternal(jobHandlerName, jobHandlerParam);
|
||||
} catch (Throwable ex) {
|
||||
exception = ex; // 只有这里 exception 才非 null
|
||||
}
|
||||
```
|
||||
|
||||
但 `DailyHotJob.execute()` 和 `dailyHot()` 内的每一层都是：
|
||||
|
||||
```java
|
||||
// DailyHotJob
|
||||
@Override
|
||||
public String execute(String param) {
|
||||
jackettService.dailyHot(); // 没有 throws，异常全在里面吞了
|
||||
return "每日热点"; // 永远返回正常字符串
|
||||
}
|
||||
|
||||
// dailyHot() 内部
|
||||
for (...) {
|
||||
try {
|
||||
...
|
||||
} catch (Exception e) {
|
||||
log.error("搜索 '{}' 时出错", javId, e.getMessage()); // 只打日志
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**后果**：即使远程 API 完全不可用、所有搜索全失败，Job 日志面板仍然显示「成功」。运维人员无法通过框架面板感知故障。
|
||||
|
||||
### 2.2 租户注解缺失问题
|
||||
|
||||
```java
|
||||
@Override
|
||||
@TenantIgnore // ← 只有最外层加了
|
||||
public void dailyHot() { ... }
|
||||
```
|
||||
|
||||
`dailyHot()` 内部调用了 `this.getDailyHotIds()`、`this.getPageContent()`、`this.searchSingleKeyword()`，都是**内部方法调用**。
|
||||
|
||||
在 Spring AOP（JDK 动态代理）下，内部 `this.method()` 不会触发 `@TenantIgnore` 切面。如果 ruoyi 的租户 SQL 拦截器处于激活状态，可能导致这些方法执行时产生错误的 `WHERE tenant_id = ?` 过滤。
|
||||
|
||||
`saveRedisIds()` 方法也完全没加 `@TenantIgnore`，同样有风险。
|
||||
|
||||
---
|
||||
|
||||
## 3. 🟠 P1-P2 中等问题
|
||||
|
||||
### 3.1 N+1 数据库查询 + 逐条 insert
|
||||
|
||||
```java
|
||||
// N 次独立 selectOne
|
||||
Set<String> newIds = hotIds.stream()
|
||||
.filter(javId -> javInfoMapper.selectOne(JavInfoDO::getJavId, javId) == null)
|
||||
.collect(Collectors.toSet());
|
||||
|
||||
// M 次独立 insert
|
||||
for (String javId : newIds) {
|
||||
JavInfoDO javInfo = new JavInfoDO();
|
||||
javInfo.setJavId(javId);
|
||||
javInfoMapper.insert(javInfo); // 逐条
|
||||
}
|
||||
```
|
||||
|
||||
如果 hotIds 有 200 条，就是 200 次 select + 若干次 insert，数据库连接往返开销巨大。
|
||||
|
||||
**建议**：改为 `selectByJavIds(Collection)` 批量查重 + `insertBatch` 批量插入。
|
||||
|
||||
### 3.2 逐条串行远程搜索 + sleep 阻塞
|
||||
|
||||
```java
|
||||
for (String javId : newIds) {
|
||||
List<JackettSearchResultVO> results = searchSingleKeyword(javId, 30);
|
||||
// 过滤...
|
||||
Thread.sleep(jackettProperties.getSearchDelay()); // 通常 1-3s
|
||||
}
|
||||
```
|
||||
|
||||
假设只差 50 条新 ID，每次 search 耗时 3s + sleep 2s = 5s/条 → **总共 250 秒（4+ 分钟）**。如果匹配更多，耗时线性增长。
|
||||
|
||||
**建议**：使用并行流或 `CompletableFuture` 控制并发度（3-5），同时为 `RestTemplate` 配置连接/读取超时。
|
||||
|
||||
### 3.3 文件无限追加不轮转
|
||||
|
||||
```java
|
||||
ResourcesUtils.saveFile(resultVO.getMagnetUri(),
|
||||
jackettProperties.getWujiBaseDirectory(), "hot");
|
||||
```
|
||||
|
||||
每次都追加到同一个 `hot.txt`，永不清理。每天几十上百条磁力链接，一年后文件可能几十上百 MB，I/O 持续劣化。
|
||||
|
||||
**建议**：按日期分文件，如 `hot/2026-04-25.txt`；或改用数据库存储。
|
||||
|
||||
### 3.4 年度过滤器不符合「热点」语义
|
||||
|
||||
```java
|
||||
if (resultVO.getPublishDate().getYear() != currentYear) {
|
||||
continue;
|
||||
}
|
||||
```
|
||||
|
||||
如果今天是 2026-04-25，这个条件会接受 2026-01-01 到 2026-04-24 的所有结果，而不是「最近发布的结果」。
|
||||
|
||||
**建议**：改为 `isAfter(LocalDateTime.now().minusHours(N))` 时间窗口过滤。
|
||||
|
||||
---
|
||||
|
||||
## 4. 🟡 P3 潜在坑
|
||||
|
||||
### 4.1 Redis Key 硬编码且已过时
|
||||
|
||||
```java
|
||||
String key = "\"jav:rank:2023\"";
|
||||
```
|
||||
|
||||
- 2023 硬编码，距离现在已经 3 年
|
||||
- Key 带多余的双引号，实际可能是 `jav:rank:2023`
|
||||
- 如果这是保存历史 ID 的入口，2023 早已不是有效数据源
|
||||
|
||||
### 4.2 非幂等 + 中断无保护
|
||||
|
||||
Job 执行到一半时应用关闭：
|
||||
- 已插入的 `JavInfoDO` 已提交（无事务包裹）
|
||||
- 已写入文件的磁力链已持久化
|
||||
- 下次执行时已入库的 ID 被跳过，但 `hot.txt` 用 APPEND 追加，**产生重复行**
|
||||
|
||||
### 4.3 Redis 数据清洗掩盖上游 Bug
|
||||
|
||||
```java
|
||||
private String cleanString(String raw) {
|
||||
// 去首尾引号 + 转义
|
||||
String cleaned = raw;
|
||||
if (cleaned.startsWith("\"")) cleaned = cleaned.substring(1);
|
||||
if (cleaned.endsWith("\"")) cleaned = cleaned.substring(0, cleaned.length() - 1);
|
||||
cleaned = cleaned.replace("\\\"", "\"");
|
||||
return cleaned.isEmpty() ? null : cleaned;
|
||||
}
|
||||
```
|
||||
|
||||
Redis 的 Set<String> 中存储的值不应该带序列化引号或转义。出现这种情况说明**上游写入数据的方式有问题**。消费侧做清洗只是遮盖症状，不是根本解决。
|
||||
|
||||
### 4.4 `saveFile()` 两个重载路径冲突
|
||||
|
||||
```java
|
||||
// 重载1（dailyHot 调用的）
|
||||
saveFile(content, path, fileName) → Paths.get(path, fileName + ".txt")
|
||||
|
||||
// 重载2
|
||||
saveFile(content, name) → dir = "/app/daily"; Paths.get(dir, name + ".txt")
|
||||
```
|
||||
|
||||
重载2 硬编码了 `/app/daily`，如果其他调用方使用了这个重载但没有意识到路径硬编码，可能产生预期外的写入位置。
|
||||
|
||||
### 4.5 `Thread.sleep` 占用 Quartz 线程
|
||||
|
||||
`Thread.sleep` 是阻塞操作，在 Quartz 的工作线程中执行会让该线程无法处理其他 Job。虽然 `@DisallowConcurrentExecution` 避免了同 Job 并行，但如果 `JackettServiceImpl` 被多个 Job 共享，sleep 期间资源浪费更明显。
|
||||
|
||||
---
|
||||
|
||||
## 5. 改造建议优先级
|
||||
|
||||
| 优先级 | 问题 | 建议方案 |
|
||||
|--------|------|----------|
|
||||
| **P0** | 异常吞没，运维盲区 | `dailyHot()` 改为 `throws Exception`，仅捕获可恢复异常，向上传播不可恢复异常 |
|
||||
| **P0** | 租户注解内部调用不生效 | 在 `getDailyHotIds()`、`searchSingleKeyword()`、`saveRedisIds()` 上也加 `@TenantIgnore` |
|
||||
| **P1** | N+1 数据库操作 | 替换为 `selectByJavIds` 批量查重 + `insertBatch` 批量插入 |
|
||||
| **P1** | 串行远程搜索过慢 | `CompletableFuture` 并发（并发度 3-5），配置 RestTemplate 超时（connect+read） |
|
||||
| **P2** | 文件追加不轮转 | 按日期分文件：`hot/yyyy-MM-dd.txt` |
|
||||
| **P2** | 年度过滤语义不对 | 改为最近 N 小时/天的时间窗口过滤 |
|
||||
| **P2** | Thread.sleep 阻塞 | 使用 `ThreadPoolTaskScheduler` 或 `ScheduledThreadPoolExecutor` 提交异步任务 |
|
||||
| **P3** | Redis Key 硬编码 | 提取为配置项 `wuji.redis-rank-key` |
|
||||
| **P3** | 非幂等设计 | 改造为支持幂等（基于 jav_id 唯一约束的 `ON DUPLICATE KEY UPDATE`，文件去重写入） |
|
||||
Reference in New Issue
Block a user