| name | deepseek-coding-manual |
| description | DeepSeek V4 Pro 编程思维手册。触发条件：需求拆解、项目搭建规划、技术选型分析、多模块任务分解、系统架构设计。不匹配排错调试和代码编写等执行层任务，这些任务由其他专属Skill处理。 |
DeepSeek V4 Pro 全能编程专属SKILL规则手册
核心原则：本手册是完整复刻 DeepSeek V4 Pro 全部思考逻辑、解题思路、排错经验、编码习惯、项目搭建逻辑的专属行为准则。
使用对象：推理弱、思路乱、调试低效、只会盲目试错的低配AI模型（通义灵码、轻量模型等）。
强制要求：低配AI拿到本手册后，执行任何匹配场景任务时，彻底抛弃自身混乱思维，全程1:1照搬本手册思维模式做事。如需编写测试脚本或使用截图功能，一律保存到 test/ 目录。
第一部分：SKILL触发调用机制
1.1 自动触发关键词与场景
只要用户下发需求包含以下任意一个关键词或场景，必须立刻启用本全套SKILL，禁止使用自身原有思维：
A类：编程开发（最高优先级触发）
| 触发词 | 典型需求示例 |
|---|
| Python脚本 | "写一个Python脚本"、"帮我写个py文件" |
| 自动化程序 | "自动化发布"、"批量处理"、"定时任务" |
| Playwright | "浏览器操控"、"网页自动化"、"Playwright脚本" |
| 爬虫开发 | "爬取网页"、"数据采集"、"网页抓取" |
| API开发 | "写个接口"、"FastAPI服务"、"后端接口" |
B类：AI模型相关
| 触发词 | 典型需求示例 |
|---|
| 模型路由 | "模型中转"、"API转发"、"多模型调度" |
| 模型对接 | "对接大模型"、"接入新模型"、"网页版模型" |
| IDE代理 | "Cursor配置"、"Trae代理"、"IDE接入" |
| 聚合调度 | "多模型聚合"、"统一API"、"模型池" |
C类：网络与部署
| 触发词 | 典型需求示例 |
|---|
| 内网穿透 | "ngrok配置"、"公网暴露"、"隧道" |
| 端口进程 | "端口占用"、"进程排查"、"端口冲突" |
| 服务部署 | "部署服务"、"启动服务"、"后台运行" |
| 环境配置 | "环境变量"、".env配置"、"依赖安装" |
1.2 关闭规则
以下场景自动停用本SKILL，恢复普通对话模式：
- 日常闲聊、问好
- 生活问答（天气、饮食、旅游等）
- 文案娱乐（写诗、讲故事、笑话等）
- 纯理论探讨（不涉及实际编码）
- 非技术开发类需求
1.3 低配AI强制使用规范
- 拿到本SKILL后，执行任何匹配场景任务时，优先通读对应章节流程
- 严格按照手册内既定顺序、既定思路、既定方案执行
- 禁止自主创新思路 — 手册没写的方案不要用
- 禁止随意简化步骤 — 手册标注"必做"的步骤一个不能少
- 禁止凭自身浅薄认知乱修改写法 — 手册给的代码模板直接套用
1.4 优先级规则
手册内写明的最优方案、排查顺序、避坑方法，优先级高于低配AI自身所有认知，必须严格遵守，不得质疑。
第二部分：标准需求拆解思维
2.1 需求理解流程（接到任何需求后，按此顺序思考）
步骤1：确认输入输出
├→ 输入是什么？（文件？URL？用户输入？API请求？）
├→ 输出是什么？（文件？打印？API响应？数据库写入？）
└→ 中间需要经过哪些转换？
步骤2：确认边界条件
├→ 数据量多大？（几个文件还是几万个？）
├→ 频率多高？（一次性的还是持续运行？）
├→ 容错要求？（失败了重试还是跳过？）
└→ 性能要求？（毫秒级还是分钟级？）
步骤3：确认已有资源
├→ 项目里有没有类似代码可以参考？
├→ 有没有现成的库/工具可以用？
└→ 有没有配置文件/环境变量需要读取？
步骤4：确认技术选型
├→ 优先用项目已有的库和框架
├→ 不要引入新依赖除非必要
└→ 简单优先：能用一个脚本解决的不建项目
2.2 模块拆分方法
拆分原则：
├→ 单一职责：一个函数只做一件事
├→ 输入输出明确：函数签名一看就懂
├→ 可测试：每个函数可以独立测试
└→ 可复用：相似逻辑不写两遍
拆分示例（以"网页内容采集"为例）：
├→ fetch_page(url) → 获取网页HTML
├→ parse_content(html) → 解析提取正文
├→ extract_images(html) → 提取图片
├→ clean_text(text) → 清洗文本
├→ save_article(data) → 保存结果
└→ main() → 串联上述步骤
2.3 主次划分原则
优先级排序（从高到低）：
1. 核心功能（必须能跑通） — 先实现，先测试
2. 错误处理（不能崩溃） — 核心功能跑通后加
3. 日志记录（方便排查） — 错误处理后加
4. 性能优化（快一点） — 最后做，非必要不做
5. 代码美化（好看一点） — 永远不做，除非用户明确要求
判断标准：
├→ 没有这个功能，整个程序能不能跑？
│ ├→ 不能 → 核心功能，先做
│ └→ 能 → 锦上添花，后做
└→ 这个功能用户明确要求了吗？
├→ 是 → 必须做
└→ 否 → 不做（YAGNI原则）
2.4 技术选型决策树
需要存储数据？
├→ 少量配置 → .env 或 config.yaml
├→ 中等量结构化数据 → JSON文件
├→ 大量数据需要查询 → SQLite
└→ 高并发读写 → PostgreSQL/MySQL
需要HTTP服务？
├→ 简单API（<5个接口） → FastAPI单文件
├→ 复杂API → FastAPI + Router分模块
└→ 静态文件服务 → nginx 或 python -m http.server
需要浏览器自动化？
├→ 简单爬取 → requests + BeautifulSoup
├→ 需要JS渲染 → Playwright
└→ 需要登录态 → Playwright + storage_state
需要定时任务？
├→ Windows → 任务计划程序 + bat脚本
├→ Linux → cron + shell脚本
└→ 跨平台 → Python + schedule库
第三部分：全场景项目落地思路
3.1 从零新建项目思路
步骤顺序（严格按此执行）：
1. 确认需求边界
├→ 问清楚：输入什么？输出什么？运行环境？
└→ 不确定就问，不要猜
2. 搜索项目内是否有类似代码
├→ 用 SearchCodebase 搜索关键词
├→ 用 Glob 搜索相似文件名
└→ 有类似代码 → 复制模板再改（改动>30%必须复制）
3. 确定文件位置
├→ 单脚本 → 放在相关功能目录中
├→ 多文件模块 → 新建子目录
└→ 测试脚本 → 必须放 test/ 目录
4. 先写核心逻辑（最小可用版本）
├→ 不写错误处理
├→ 不写日志
├→ 不写配置
└→ 只写核心功能，跑通再说
5. 核心跑通后，逐步加：
├→ 错误处理（try-except）
├→ 日志记录（logger.info/error）
├→ 配置化（.env / config）
└→ 边界情况处理
6. 测试验证
├→ 正常情况测试
├→ 异常情况测试
└→ 边界情况测试
3.2 残缺代码补全思路
1. 先理解现有代码在做什么
├→ 读函数名和参数
├→ 读注释（如果有）
└→ 追踪调用链
2. 找到缺口
├→ 哪个函数没实现？
├→ 哪个步骤被跳过了？
└→ 哪个变量没定义？
3. 参考项目内类似实现
├→ 搜索相似函数名
├→ 搜索相似功能代码
└→ 复制最接近的实现再修改
4. 补全后验证
├→ 检查导入是否完整
├→ 检查类型是否匹配
└→ 运行测试
3.3 旧项目重构优化思路
重构三原则：
1. 不改变外部行为（输入输出不变）
2. 小步快跑（一次只改一个模块）
3. 每步可验证（改完立刻测试）
重构步骤：
1. 先写测试（保证改后行为不变）
2. 提取重复代码为函数
3. 统一命名风格
4. 拆分大函数
5. 移除无用代码
6. 统一配置管理
3.4 批量模板化开发思路
适用场景：需要创建多个结构相似的脚本/模块
步骤：
1. 先做好一个完整模板（能跑通）
2. 提取可变部分（选择器、URL、类名等）
3. 复制模板文件 → 改名 → 修改可变部分
4. 规则：改动>30%必须复制模板，不允许手写
示例（新增浏览器模型Provider）：
copy deepseek.py → doubao.py
修改：类名、URL、选择器常量
不改：navigate()、submit_prompt()、extract_streaming() 等核心逻辑
第四部分：高频疑难问题全套解决方案
4.1 端口占用问题
现象：启动服务报 Address already in use 或 端口被占用
排查：
netstat -ano | findstr "端口号"
解决：
taskkill /F /PID 进程ID
预防：启动前检查端口，写进启动脚本
4.2 进程残留问题
现象：上次关闭了但进程还在跑，端口被占
排查：
tasklist | findstr "python"
tasklist | findstr "node"
解决：
taskkill /F /IM python.exe
taskkill /F /IM node.exe
预防：脚本加信号处理，确保 Ctrl+C 能正常退出
4.3 编码乱码问题
现象：中文显示为乱码、问号、方块
成因：文件编码与读取编码不一致
解决：
- Python 文件第一行加
# -*- coding: utf-8 -*-
- 读写文件时显式指定
encoding='utf-8'
- PowerShell 脚本首行加
chcp 65001
- 不要用 PowerShell 的
Set-Content 写中文文件，用 Python 写
预防：所有文件统一 UTF-8 无 BOM
4.4 环境变量未加载
现象：os.environ.get('KEY') 返回 None
排查：
from dotenv import load_dotenv
load_dotenv(override=True)
print(os.environ.get('KEY'))
解决：确认 .env 文件在运行目录下，格式为 KEY=VALUE（不要引号）
4.5 依赖缺失/版本冲突
现象：ModuleNotFoundError 或 ImportError
排查：
pip list | findstr "包名"
解决：
pip install -r requirements.txt
pip install 包名 --upgrade
预防：用 requirements.txt 锁定版本，用虚拟环境隔离
4.6 Playwright 浏览器未安装
现象：BrowserType.launch: Executable doesn't exist
解决：
playwright install chromium
4.7 Playwright 选择器超时
现象：TimeoutError: Waiting for selector "xxx" failed
排查顺序：
- 手动打开网页，F12检查选择器是否正确
- 检查元素是否在 iframe 内
- 检查是否需要先登录
- 检查页面加载是否完成（
wait_until="networkidle"）
解决：增加超时时间，或改用 page.wait_for_selector(selector, timeout=30000)
4.8 CSS :hover 不触发
现象：用 dispatchEvent(new MouseEvent('mouseover')) 无法触发 hover 效果
成因：CSS :hover 伪类只响应真实鼠标移动，不响应 JS 事件
解决：使用 page.mouse.move(x, y) 模拟真实鼠标移动
4.9 SVG 元素点击失败
现象：svgElement.click() 报错或无效
成因：SVG 元素不支持 click() 方法
解决：使用 dispatchEvent(new MouseEvent('click', {bubbles: true}))
4.10 会话/状态污染
现象：多次运行后行为异常，数据混乱
成因：上次运行的会话、cookie、localStorage 残留
解决：
- Playwright：每次启动用新的
browser_context，或 context.clear_cookies()
- 网页模型：每次运行前清理旧会话
- 数据文件：运行前检查并清理临时文件
4.11 请求超时
现象：TimeoutError 或请求卡住不动
排查顺序：
- 检查网络连通性（ping 目标地址）
- 检查代理/VPN 是否正常
- 检查防火墙是否拦截
- 增加超时时间测试
解决：设置合理的超时 + 重试机制（最多3次，指数退避）
4.12 并发/队列异常
现象：多任务并发时结果混乱、丢失
解决：
- 使用
asyncio.Semaphore 限制并发数
- 使用
asyncio.Queue 管理任务队列
- 关键操作加锁
asyncio.Lock
第五部分：专属业务定向思路
5.1 本项目核心架构速查
lama-puppeteer: f:\myclaw\lama-puppeteer
├→ API Key: sk-lamapuppeteer-admin-key-2026
├→ new-api端口: 3000
├→ new-api账号: admin / admin123456
└→ 启动: start_all.bat
data_collector: f:\myclaw\data_collector
├→ tracking: output/tracking (≤7天文章)
├→ knowledge_base: output/knowledge_base/external (>7天文章)
│ ├→ archive (临时仓库)
│ ├→ base (基础库)
│ ├→ incremental (增量库)
│ └→ permanent_archive (永久归档)
└→ ID规则: MD5(URL)[:12]
self_evolving_engine: f:\myclaw\multi-platform-automation\self_evolving_engine
├→ 模板: output/evolution/patterns/writing_templates.json
├→ 分类器: content_classifier.py (统一分类入口)
└→ 调度器: task_scheduler.py
5.2 本项目关键规则
- 分类统一入口：所有分类逻辑必须通过
content_classifier.py 的 ContentClassifier 类
- ID生成规则：12位ID = MD5(URL)[:12]，全项目统一
- 知识库四层架构：新文章 → archive → organize() → base/incremental
- 增量分发覆盖更新：
external_dispatch.py 处理增量文章，覆盖同名文件更新互动数据
- 基础库分发不覆盖：
classify_external_articles.py 处理基础库文章，跳过已存在文章
- 模板选择：调度器通过聚类提炼生成的
writing_templates.json 选择模板
- 双轨纠错：对比本周与上周数据，评估内容质量趋势（已启用）
- 范式提炼：暂不启用，作为聚类提炼的备选方案
5.3 本项目常用命令
python --version
pip list
pip install -r requirements.txt
pip install 包名 --upgrade
netstat -ano | findstr "端口号"
tasklist | findstr "PID"
taskkill /F /PID PID号
taskkill /F /IM python.exe
playwright install chromium
playwright codegen URL
ngrok config check
ngrok config add-authtoken TOKEN
ngrok http 端口号 --log=stdout
curl http://127.0.0.1:4040/api/tunnels
git status
git diff
git log -n 5
curl http://localhost:9091/health
curl http://localhost:3000/api/
附录：避坑速查表
| 序号 | 坑点 | 正确做法 |
|---|
| 1 | 用 PowerShell Set-Content 写中文 | 用 Python open() 写文件 |
| 2 | 用 dispatchEvent 触发 hover | 用 page.mouse.move() |
| 3 | 在 SVG 上直接 .click() | 用 dispatchEvent(MouseEvent) |
| 4 | 不等待页面加载就操作 | 用 wait_for_selector 等待 |
| 5 | 不检查返回值类型 | 用 isinstance() 检查 |
| 6 | 静默吞掉异常 | 至少 logger.error 记录 |
| 7 | 硬编码路径和配置 | 用 .env 或 config 文件 |
| 8 | IDE URL 加 /v1 后缀 | new-api自动追加，不要手动加 |
| 9 | 不清理旧会话就运行 | 每次运行前清理 |
| 10 | 不检查端口就启动 | 启动前 netstat 检查 |
