CSDN Auto Publisher Easy — 使用手册

把本地 Markdown 一键发布到 CSDN 博客的全流程说明。

2026-06-22 优化版:直连 MD 编辑器 + 全局 Copilot skill 集成

---

目录

1. 项目是什么
2. 前置准备
3. 三种使用方式(按推荐顺序)
   • [方式 A:聊天框斜杠命令 /publish-to-csdn](#方式 A:聊天框斜杠命令 /publish-to-csdn)
   • [方式 B:Agent 模式自定义 Agent](#方式 B:Agent 模式自定义 Agent)
   • [方式 C:命令行 CLI](#方式 C:命令行 CLI)
4. [Cookie 管理(必须读)](#Cookie 管理(必须读))
5. 发布方式详解
6. [MCP 服务(Cline / Claude Desktop / Cursor)](#MCP 服务(Cline / Claude Desktop / Cursor))
7. 故障排查
8. [常见问题 FAQ](#常见问题 FAQ)
9. 附录:文件清单

---

1. 项目是什么

CSDN Auto Publisher Easy 是一个把本地 Markdown 自动发布到 CSDN 博客的工具。

核心特性:

• ✅ 完全模拟真实用户操作(Playwright 浏览器自动化),无封号风险
• ✅ 直连 MD 编辑器,跳过创作中心菜单,整流程 30 秒左右
• ✅ 支持命令行 / HTTP API / MCP / 全局 Copilot skill 四种调用方式
• ✅ Cookie 复用,30 天内不用重登(实测可更长)

已验证成功案例:

文章 ID	标题	方式	时间
162210496	Vue 3 核心 API 与实战要点速览	完整流程	2026-06-22 19:00
162213558	Playwright 选择器失效的 3 个排查思路	直连模式(新)	2026-06-22 23:28

---

2. 前置准备

2.1 安装 Python 依赖

cd 'C:\Users\28190\Desktop\csdnAutoP\CsdnAutoPublisherEasy'
pip install -r requirements.txt
python -m playwright install chromium

💡 第一次运行会下载 Chromium 浏览器 (~150MB),请耐心等待。

2.2 登录 CSDN 拿 Cookie(一次性)

python main.py login

会弹出一个 Chromium 浏览器窗口:

1. 在浏览器里手动登录 mp.csdn.net (扫码 / 账号密码都行)
2. 登录成功后,直接关闭浏览器窗口
3. Cookie 自动保存到 config/accounts/csdn_cookies.json

⚠️ 这是唯一需要人工介入的步骤。后续发布全自动,无需任何手动操作。

2.3 验证准备就绪

python main.py health

正常输出:

📊 CSDN Auto Publisher Easy 健康状态
   - Cookie 有效: True        ← 必须是 True
   - 剩余分钟: 120.5
   - Cookie 数量: 109
   - 用户: lexiangqicheng

如果 Cookie 有效: False,回到 2.2 重新登录。

---

3. 三种使用方式(按推荐顺序)

方式 A:聊天框斜杠命令 /publish-to-csdn ⭐推荐

适用场景: 日常使用,最省心。任何工作区都能用。

一次性安装(已完成可跳过)

cd 'C:\Users\28190\Desktop\csdnAutoP\CsdnAutoPublisherEasy'
.\install_skill.ps1

输出:

📦 安装 CSDN Publisher skill 到 VS Code 全局...
  ✅ publish-to-csdn.prompt.md → \prompts
  ✅ csdn-publisher.agent.md → \agents
  ✅ csdn-publisher.instructions.md → \csdn-publisher
  ✅ csdn-mcp.json → \
🎉 安装完成!

重启 VS Code 让指令生效(Ctrl+Shift+P → "Developer: Reload Window")。

使用流程

1. 打开 VS Code,进入任意工作区
2. 打开聊天框 (Ctrl+Shift+I)
3. 输入 /publish-to-csdn (会变成命令按钮)
4. 在弹出的输入框里:
   • 粘贴或描述你想发布的文章内容
   • 或直接说"刚才那段关于 xxx 的对话发 CSDN"
5. Copilot 会自动:
   • 整理 Markdown(标题/分节/标签)
   • 写到 storage/notes/YYYYMMDD_<slug>.md
   • 调用 python main.py publish --file ... 发布
   • 返回文章 URL

触发词参考(就算不打 /publish-to-csdn,AI 也会识别)

在聊天框说以下任一, AI 都会主动建议发布:

• "发到 CSDN" / "发布到博客" / "发布到 CSDN"
• "把这段对话发到 CSDN" / "整理成文章"
• "这个 bug 帮我整理成文章"
• "我刚发现 xxx, 记一下发 CSDN"

方式 B:Agent 模式自定义 Agent

适用场景: 多轮对话式发布,需要 AI 主动引导。

怎么用

1. 打开聊天框,点击顶部 "Agent" 模式切换按钮
2. 在模型选择下拉框旁边,找 "CSDN Publisher" 自定义 Agent
3. 选中后,输入你的内容即可

和斜杠命令的区别

	斜杠命令	自定义 Agent
触发方式	必须输入 /publish-to-csdn	选 Agent 后,自然语言触发
适合场景	一次性明确任务	多轮对话(AI 会主动追问缺什么)
主导权	用户主导	AI 主导

方式 C:命令行 CLI

适用场景: 写脚本批处理、调试、定时任务。

3.1 发布本地 md 文件

cd 'C:\Users\28190\Desktop\csdnAutoP\CsdnAutoPublisherEasy'
python main.py publish --file storage\notes\20260618_playwright_tips.md

会弹浏览器(看发布过程),完成后输出:

🎉 文章 URL: https://blog.csdn.net/xxx/article/details/XXX

3.2 后台静默发布

加 --headless 参数,不弹浏览器:

python main.py publish --file storage\notes\xxx.md --headless

3.3 直接传内容(不用写文件)

python main.py publish --title "我的标题" --markdown "## 背景
正文内容..." --tags Python --tags 自动化

3.4 完整参数说明

python main.py publish --help

Options:
  --file PATH                 本地 md 文件路径
  --title TEXT                文章标题 (与 --markdown 一起用)
  --markdown TEXT             Markdown 正文
  --tags TEXT                 标签, 可多次传入
  --status [draft|publish]    保存为草稿还是直接发布 (默认 publish)
  --method [ui|http|auto]     ui=Playwright (稳), http=直接调 API (快但 503)
  --headless / --no-headless  Playwright 是否无头 (默认不无头)
  --full-flow / --direct      UI 模式: full-flow=走完整菜单 (调试用),
                              direct=直连 MD 编辑器 (默认, 推荐)

3.5 推荐参数组合

场景	推荐命令
日常发布	python main.py publish --file xxx.md
后台批处理	python main.py publish --file xxx.md --headless
调试 UI 改版	python main.py publish --file xxx.md --full-flow
快速试错(不真发)	(暂无 dry-run,先 --headless 看效果)

---

4. Cookie 管理(必须读)

4.1 Cookie 过期机制

CSDN 的 dc_session_id 是短期会话凭证,官方文档说 30 分钟过期。

实测经验:

• 普通 CookieManager.is_valid() 判定偏严格,经常误报过期
• 真正过期 的标志是直接调 editor.csdn.net/md/ 被踢回登录页
• 实测:cookie 文件里 dc_session_id.expires 显示 4.3 天前过期,但仍能正常发布(article 162213558)

4.2 续期 Cookie

方法 A:重新跑 login(最简单)

python main.py login

方法 B:从浏览器手动导出

1. 在浏览器打开 mp.csdn.net 并登录
2. F12 → Application → Cookies → 选 https://mp.csdn.net
3. 全选所有 cookie,导出 JSON
4. 覆盖 CsdnAutoPublisherEasy\config\accounts\csdn_cookies.json

4.3 Cookie 健康检查

python main.py health

如果返回 Cookie 有效: False,但你确认浏览器还能用,可以直接发布试试(代码里有软警告机制)。

---

5. 发布方式详解

5.1 UI 模式(默认,推荐)

走 Playwright 浏览器自动化,完全模拟真实用户操作。

direct=True(默认):

打开 editor.csdn.net/md/?not_from_app=true&type=ai_editor
  → 填标题 (React native value setter)
  → 切 Markdown (顶 tab 默认激活)
  → 上传 .md (走 #import-markdown-file-input)
  → 点 "发布文章" 底栏按钮 → 弹窗
  → 弹窗里填标签 → 点 "发布文章" 红色按钮
  → 监听 saveArticle 接口 → 拿到 URL

耗时: ~30 秒(headless 模式)

direct=False(--full-flow):

打开 mp.csdn.net/mp_blog/manage/article (创作中心)
  → 点 "创作" 红色按钮 (新 page)
  → 进入 creation/editor
  → 点 "使用 MD 编辑器" 工具栏按钮 (新 page)
  → 进入 editor.csdn.net/md/
  → ... (后续同上)

耗时: ~50 秒(多 3 次新 page 跳转)

对比:

	direct=True	direct=False (full-flow)
速度	30s	50s
稳定性	✅ 高(一次跳转)	⚠️ 中(可能被新 page 弹窗拦)
调试价值	低(看不到创作中心)	✅ 高(选择器全验证)
适用	日常发布	UI 改版排查

5.2 HTTP 模式(--method http)

直接调 bizapi.csdn.net 后端,不走浏览器。

优势: 速度快(秒级)

劣势:

• ⚠️ CSDN 后端对 bizapi 经常返回 503 (name resolution failed)
• 需要自己实现签名算法(本项目 csdn_signer.py 已实现)
• 失效风险更高(CSDN 后端微服务不稳定)

适用: 知道 HTTP 接口稳定时(目前不是)

5.3 auto 模式(--method auto)

默认走 UI,失败回退 HTTP。当前实现等同 UI,未来可扩展智能切换。

---

6. MCP 服务(Cline / Claude Desktop / Cursor)

如果你的 IDE 支持 MCP 协议,会自动发现 publish_to_csdn 工具。

6.1 安装 MCP 依赖

pip install mcp playwright

6.2 配置

VS Code --- settings.json 或 .vscode/mcp.json:

{
  "servers": {
    "csdn-publisher": {
      "command": "python",
      "args": ["-m", "publish_skill_mcp"],
      "cwd": "C:\\Users\\28190\\Desktop\\csdnAutoP\\CsdnAutoPublisherEasy",
      "type": "stdio"
    }
  }
}

💡 CsdnAutoPublisherEasy\csdn-mcp.json 已经写好,VS Code 会自动加载。

Claude Desktop --- %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "csdn-publisher": {
      "command": "python",
      "args": ["-m", "publish_skill_mcp"],
      "cwd": "C:\\Users\\28190\\Desktop\\csdnAutoP\\CsdnAutoPublisherEasy"
    }
  }
}

6.3 可用工具

工具名	作用	示例调用
publish_to_csdn	发布一篇 Markdown	publish_to_csdn(title="...", markdown="...", tags=["Python"])
check_csdn_cookie	检查 Cookie 状态	check_csdn_cookie() → "ok: 109 cookies, 剩余 120 分钟"

---

7. 故障排查

7.1 /publish-to-csdn 命令没出现

排查:

1. 检查文件存在:

   ls $env:APPDATA\Code\User\prompts\publish-to-csdn.prompt.md

2. 重启 VS Code:Ctrl+Shift+P → "Developer: Reload Window"

3. 确认 VS Code 版本 ≥ 1.95

7.2 发布失败:Cookie 已过期

症状: python main.py health 返回 Cookie 有效: False

解决: python main.py login 重登(见 4.2)

7.3 发布失败:找不到 "创作" 按钮 / "发布文章" 按钮

症状: 截图见 logs/publish_ui/,日志有 no_create_btn / no_publish_btn

原因: CSDN UI 改版,选择器失效

解决:

1. 用 --full-flow 看 UI 真实路径:

   python main.py publish --file xxx.md --full-flow

2. 看 logs/publish_ui/ 里的截图

3. 更新 publish_ui.py 里的 locate_first() 选择器

4. 提交 PR / 记录到 runbook

7.4 发布失败:CSDN 后端 503

症状: body 包含 name resolution failed

原因: CSDN 自己的微服务挂了,与你无关

解决:

• 等待几分钟再试
• 切换到 UI 模式(浏览器会走另一条链路,通常不会 503)

7.5 浏览器没装

症状: playwright._impl._errors.Error: Executable doesn't exist

解决:

python -m playwright install chromium

7.6 端口被占用(API 服务模式)

症状: uvicorn 启动失败,Address already in use

解决: 改端口:

python main.py serve --port 8766

---

8. 常见问题 FAQ

Q1:能批量发布吗?

A: 当前需要循环调用 CLI:

Get-ChildItem storage\notes\*.md | ForEach-Object {
    python main.py publish --file $_.FullName --headless
}

未来会加 batch 命令。

Q2:能定时发布吗?

A: 配合 Windows 任务计划程序:

# 创建任务,每天 8 点发布
schtasks /Create /SC DAILY /TN "CSDN-Publish" /TR "python main.py publish --file xxx.md --headless" /ST 08:00

Q3:能用其他 AI 生成文章吗?

A: 可以。CsdnAutoPublisher/v1 项目有 core/note_generator.py 调 DeepSeek。本项目暂未集成。

Q4:发布后文章是私密还是公开?

A: 默认 publish(公开)。想存草稿: --status draft。

Q5:能修改已发布的文章吗?

A: 当前不支持,只能新建。要修改请去 CSDN 后台手动编辑。

Q6:能加自定义域名吗?

A: CSDN 文章 URL 由其平台决定,本项目无法自定义。

Q7:能发布到 CSDN 之外(掘金/知乎/简书)吗?

A: 当前只支持 CSDN。架构上 publisher/csdn.py 可扩展,但需要为每个平台实现一套 Playwright 选择器。

Q8:Cookie 文件可以共享给其他项目吗?

A: 可以。config/accounts/csdn_cookies.json 是标准 Playwright cookie JSON 格式。

Q9:为什么 AI 提示"不要用 v1 的 CsdnAutoPublisher"?

A: v1 项目(CsdnAutoPublisher/)用的是 2023 年旧路径 editor.csdn.net/md/ + 老选择器,已被 CSDN 改版失效。v2 Easy 项目用 2026 年新路径验证过。

---

9. 附录:文件清单

9.1 项目根目录

文件	作用
main.py	CLI 入口 (login / publish / health / serve)
publish_ui.py	⭐ 核心发布器,Playwright UI 自动化
publish_skill_mcp.py	MCP stdio 包装(给 Cline/Cursor 用)
publish_via_browser.py / publish_via_browser2.py	历史版本,不再维护
csdn_api.py	CSDN bizapi HTTP 客户端(签名算法实现)
csdn_signer.py	CSDN 后端 HMAC 签名
cookie_manager.py	Cookie 加载/检查/管理
api_server.py	FastAPI HTTP 服务(给外部程序调用)
config/	配置目录
storage/notes/	待发布的 md 文件
storage/output/	发布记录 (JSON)
logs/publish_ui/	截图存档
install_skill.ps1	一键安装全局 skill

9.2 skill/ 目录(全局 Copilot 集成)

文件	部署位置
skill/publish-to-csdn.prompt.md	%APPDATA%\Code\User\prompts\
skill/csdn-publisher.agent.md	%APPDATA%\Code\User\agents\
skill/csdn-publisher.instructions.md	%APPDATA%\Code\User\csdn-publisher\
skill/csdn-mcp.json	%APPDATA%\Code\User\
skill/README.md	(不部署,仅本地参考)

9.3 关键路径速查

# 项目目录
$PROJ = 'C:\Users\28190\Desktop\csdnAutoP\CsdnAutoPublisherEasy'

# Cookie 文件
$COOKIE = "$PROJ\config\accounts\csdn_cookies.json"

# 待发布笔记
$NOTES = "$PROJ\storage\notes"

# 发布记录
$OUTPUT = "$PROJ\storage\output"

# 截图存档
$SHOTS = "$PROJ\logs\publish_ui"

# 全局 skill 目录
$SKILL = "$env:APPDATA\Code\User"

---

更新日志

2026-06-22 (v0.2.0)

• ✅ 新增 direct=True 直连 MD 编辑器模式,默认开启
• ✅ main.py publish 新增 --method / --headless / --full-flow/--direct 参数
• ✅ 新增 publish_skill_mcp.py MCP 包装
• ✅ 新增 4 个全局 Copilot skill 文件 + install_skill.ps1 一键安装脚本
• ✅ 实测 article_id 162213558 直连模式端到端成功(headless)

2026-06-22 (v0.1.0)

• 完整流程版本:创作中心 → 创作 → MD 编辑器
• 实测 article_id 162210496 端到端成功

---

反馈

遇到问题:

1. 看 [7. 故障排查](#7. 故障排查)
2. 看 logs/publish_ui/ 里的截图
3. 记录到 CsdnAutoPublisherEasy/storage/output/

---

📌 提示:本文档随项目更新。最新版查看 CsdnAutoPublisherEasy/USAGE.md。