# 见字工作台上手指南

先选一种运行方式,再按本页完成首次配置和内容流程。第一次使用不用先装齐所有采集器:RSSHub、Chrome、Python 和第三方搜索/CDN 都可以等需要时再启用。
| 你要做什么 | 从这里开始 | 需要准备什么 |
|---|---|---|
| 直接在 Windows 使用 | 下载并安装 [Windows 桌面版](https://github.com/shiker1996/wechat-editroom/releases/latest) | 不需要单独安装 Node.js |
| 从源码运行或接入 Agent | 按“源码版安装”运行初始化脚本 | Node.js 24;初始化脚本会检查运行环境 |
| 先了解界面 | 打开[在线界面导览](https://wechat-newsroom-guide.vercel.app/) | 不需要安装,也不需要模型密钥 |
## 本页导航
[安装与启动](#1-安装与启动) · [首次配置](#2-首次配置) · [采集热点](#4-每日热点工作流) · [文章与图文](#5-从选题到文章) · [备份与清理](#10-数据备份与清理) · [常见问题](#11-常见问题)
## 1. 安装与启动
### 1.1 Windows 桌面版(推荐)
1. 从 [GitHub Releases](https://github.com/shiker1996/wechat-editroom/releases/latest) 下载最新 Windows 安装包。
2. 安装并启动见字,按应用内引导配置模型和工作区。
3. 先添加一个 RSS/Atom 来源并测试,再开始第一批采集。
桌面版自带运行环境,普通用户不需要安装 Node.js。使用内置 AI 时需要模型服务商和 API Key;若通过 Codex、WorkBuddy 或 DSH 等外部 Agent 生成内容,见字内部模型可以不配置。
### 1.2 源码版安装(用于开发或接入 Agent)
源码版要求 Node.js 24。初始化入口会检查系统环境,并引导完成依赖和本地配置;首次安装可能下载约 1–2 GB 的依赖和渲染组件。RSSHub、Chrome、Python 及第三方搜索/CDN 服务按需安装。
双击 `setup-workbench.cmd/sh`。向导会检查 Node.js、安装依赖、创建本地配置并引导模型设置。步骤失败后可以重复运行,不会重复破坏已完成配置。
如果不想双击,也可以在项目根目录运行引导脚本:
```powershell
setup-workbench.cmd
```
### 1.3 启动与停止
配置完成后,双击 `start-workbench.cmd`/`start-workbench.sh`,或在项目根目录运行对应脚本:
```powershell
start-workbench.cmd
```
服务默认位于 `http://127.0.0.1:4317`。重复启动会检测已有实例。停止时关闭启动脚本对应的终端窗口,或按 `Ctrl+C`。
### 1.4 演示模式
```powershell
start-workbench.cmd -Demo
```
演示模式写入独立数据库,适合先了解页面和内容链路。它不模拟真实模型调用。
如果需要在本机查看生产库最近的真实批次,可使用明确的只读快照模式:
```powershell
start-workbench.cmd -DemoProduction -NoBrowser
```
启动时会将 `data/workbench.db` 复制到独立的 `data/demo-production.db`,所有 HTTP 写入接口都会被拒绝,不会改动生产库。生产内容仅用于本机检查,不应带入公开截图、GIF 或演示链接。
## 2. 首次配置
### 2.1 模型接入
进入“运行与配置 → 模型接入”:
1. 选择或添加服务商。
2. 填写 Base URL、模型名和 API Key。
3. 保存后执行最小连接测试。
4. 至少保留一个已启用且测试成功的默认服务商。
项目使用 OpenAI 兼容接口。DeepSeek 链路经过完整验证;MiniMax 与 Kimi 已内置配置结构,但仍应以连接测试为准。
### 2.2 账号与写作配置
在配置中心维护账号定位、内容支柱、受众、选题分类和评分偏好。先填写公众号名称与简介,可展开默认收起的 AI 对话助手。助手按核心读者、内容支柱、选题分类、写作边界、关注理由与内容承接、分类评分偏好的顺序逐轮确认,每轮只更新当前阶段;草案同步到常驻展开的表单,不会自动保存,需人工检查并主动保存。分类支持按公众号设置名称与定义,后续热点打标和分类榜会读取当前配置;更改分类后,后续批次按新分类重新标注,历史批次仍按生成时的分类显示。评分偏好支持通用分类分和按国内/全球/国外范围设置的分类加分,配置格式见[账号配置说明](configuration.md)。文章类型由锁定简报和选题属性推导,并加载对应的类型提示词;模型、工具和阶段路由在执行环境配置中维护。每次生成都会冻结实际 Prompt、模型与工具快照。
### 2.3 信息工具
在“技能与插件 / 能力路由”检查网页读取、网络搜索、仓库分析、本地知识库和本地项目读取是否有可用实现。未配置的可选能力只影响对应环节,不应阻断基础工作台。
## 3. 管理采集源
“采集源”页面由左侧添加区和右侧来源台账组成。顶部显示全部、正常、异常和暂停数量;可按名称/地址搜索,并按来源类型与状态筛选。
### 3.1 RSS / Atom
选择“直连 RSS / Atom”,填写 Feed 地址和可选显示名称,先测试连接,再保存。测试会显示条数和前几条预览。
### 3.2 RSSHub 与 X
RSSHub 来源填写路由;X 来源由 RSSHub 兼容入口处理。工作台默认探测 `http://127.0.0.1:1200`,必要时按配置启动本地 RSSHub。
### 3.3 Reddit
Reddit 使用专用 Chrome Profile。首次使用运行:
```powershell
powershell -File .\plugins\reddit\scripts\start-chrome.ps1
```
在打开的窗口登录 Reddit。手动窗口与批次采集统一使用 `data/reddit-chrome-profile`,Cookie 会持续保留。然后在采集源中填写 subreddit 并测试。
### 3.4 网页自动采集
选择“更多采集器 → 网页自动采集”:
1. 填写新闻、公告、博客或榜单的列表页 URL。
2. 页面有多个列表时,可填写“采集意图”,例如“只采集政策文件列表”。
3. 点击“识别并预览采集规则”。
4. 系统先验证静态 HTML;没有可靠列表时自动使用隔离浏览器渲染。
5. AI 只在多个候选接近时按意图排序,并从白名单选择摘要、作者、日期字段。
6. 每个候选都经过真实提取复验。选择候选、测试连接,再保存。
普通用户不需要判断静态或动态。高级用户仍可选择底层采集器并手工填写 Selector。验证码、复杂登录或多步骤交互可能需要人工配置或暂不支持。
### 3.5 来源维护
- “测试”只验证,不保存配置。
- 开关用于暂停/启用;暂停不会删除来源。
- 删除前会要求确认。
- 每个来源单独记录最近成功、条数和错误;单源失败不会拖垮整批采集。
## 4. 每日热点工作流
### 4.1 创建批次
在“今日值班 / 每日批次”创建当日批次。批次是热点、事件、候选和产物的归属边界。
### 4.2 采集
启动采集后,系统按来源并行执行并保存健康记录。若存在失败,页面会显示原因和可重试入口;确认可忽略的失败后才能继续下游阶段。
### 4.3 打标、事件卡和研判
可以逐步执行,也可以使用一键流程:
```text
采集 → 热点打标 → 事件卡 → 研判与候选池
```
事件按语义指纹聚类;文章候选和图文候选拥有独立评分与轨道。热点全景用于检查来源覆盖、地域相关度和重复报道。
### 4.4 处理失败
失败面板支持重试、跳过和重新打开。下游不会在关键失败未处理时悄悄继续。服务重启后运行中任务会标记为 `interrupted`,可从对应阶段重新执行。
## 5. 从选题到文章
### 5.1 进入文章池
在文章池查看评分、历史覆盖和来源信息。可以从单一热点建立候选,也可以把多个相关热点组合成综合候选。
### 5.2 编辑会
编辑会一次追问一个关键问题。你可以补充观点、作者实践或外部链接;链接会被抓取为候选级来源,并将成功正文回填资源目录,后续段落检索通过资源 ID 读取同一份资料。每条抓取成功或失败结果都会写入对话。底稿完整后,成稿预检只检查底稿、来源正文和文章路线是否足以启动流程,不生成事实基座;最终确认成稿后,成稿链才会按锁定简报和当前来源生成事实基座并执行事实、证据门禁。
编辑室、自主写作和自定义图文共享同一套对话 Agent,可按需组合网页抓取、段落检索、联网搜索和表单更新。默认预算与覆盖方式见[安全默认值](./safety-defaults.md)。工具失败、模型输出异常或达到预算时,页面会在对应消息中显示失败原因;已有的部分内容不会被静默清空,达到本轮限制时会保留继续对话的提示。
### 5.3 成稿
内部 AI 成稿链记录五个阶段:事实基座、直写、审稿、超出配置字数范围时的长度调整,以及标题锁定。直写阶段根据锁定简报和事实基座组织文章,不单独生成大纲;`05-full-edited.md` 与 `05-humanized.md` 是为兼容旧产物读取方保留的透传文件,不代表执行了全篇编辑或去 AI。当前自动成稿链不执行 SEO 改写;SEO 相关能力仅在用户单独选择时使用。系统门禁失败会阻止流程完成;仍需作者处理的问题会保留为待编辑修订,用户修订并保存后再排版。中间产物保存在候选工作目录,可用于审计与恢复。阶段定义见[成稿运行阶段契约](../skills/wechat-mp-topic-to-article/references/runtime-stage-contracts.md)。
### 5.4 编辑与版本
文章编辑器支持保存修订、查看历史版本和恢复。恢复会创建新的当前版本,不直接抹除历史记录。
### 5.5 配图、封面与排版
- 配图工作台区分来源图、自备图和可生成结构图。
- 封面每次先根据文章内容生成并校验设计方案,再由文本模型生成 HTML/CSS、本地 Chromium 截图;不调用文生图模型,也没有标准封面模式。生成或截图失败时任务直接失败。
- AI 视觉封面的 HTML 和截图产物保存在文章 `images/` 目录中,可从封面页查看 HTML;生成方案与阶段记录用于追踪本次结果。
- 排版链把 Markdown 和每篇文章的设计方案交给 AI 生成公众号 HTML,再规范化为内联样式并执行结构门禁。
- Mermaid / ECharts 可转 PNG;失败时保留原围栏并阻止错误交付。
## 6. 图文生产
图文入口包括工具项目、热点事件和自定义图文。每次生成都先根据故事板生成独立视觉方案并校验页数、角色、配色、字阶和版式范围;AI 随后生成 HTML/CSS,并在生成过程中调用浏览器审计工具逐页检查溢出、按反馈修改后复审,再截图并登记交付。
可选择微信公众号或小红书渠道,并逐页修改版式。输出位于 `social-cards/`,通常包含 `card-plan.json`、文案、HTML、布局报告和 `output/page-*.png`。
## 7. 自主写作
自主写作支持“心得经验”和“使用教程”,与编辑室共享交互 Agent 预算。先通过对话说明主题、读者与真实材料,再检查事实表单。
使用教程可导入本地项目或单个文本文件:填写项目文件夹,或 `.txt`、`.md`、`.markdown` 文件的绝对路径并点击“读取素材”。读取器只读支持的文本,跳过依赖、构建目录、秘密文件、二进制和符号链接。读取到的代码只能作为材料,不能写成“已经运行成功”的证明。
资料链接抓取失败会阻止成稿,避免模型在缺少事实时补写。
## 8. 批次早报与突发任务
- 批次早报按主体、动作、地区或场合关系选择事件,生成批次级文章,不要求先创建普通候选。
- 突发任务创建独立批次,允许补充多个素材链接、执行专项事实分析,再选择文章或图文路线。
## 9. 技能与插件
技能决定 Prompt、输入输出契约和工具权限;工具插件提供可执行能力;采集器插件提供来源类型和采集结果。安装第三方扩展前应检查权限摘要。开发方式见[插件开发指南](./plugin-development.md)。
## 10. 数据、备份与清理
- 数据库:`data/workbench.db`
- 文章:`articles/`
- 选题与事件资料:`topics/`
- 图文:`social-cards/`
- 日志:`logs/`
“设置与数据 → 备份与恢复”可导出完整 ZIP。恢复前会校验清单和 SHA-256,并自动生成恢复前快照。凭据、浏览器 Profile 和外部服务 Cookie 不进入备份。
“任务日志”中的 Run Trace 可按运行查看模型调用、工具执行、步骤、事件和 checkpoint;历史运行使用启动时冻结的模型、技能、工具与预算快照。
批次可先归档,再执行带影响范围预览的彻底删除。清缓存只删除可重建的 GitHub 与来源正文缓存。
## 11. 常见问题
### 编辑室 AI 没有回复
先查看会话内的失败提示,再到“任务日志”打开对应 Run Trace。常见原因是模型输出不符合工具契约、工具资源未找到、达到 Agent 步骤 / 工具预算或模型服务商超时。达到预算时可继续发送下一条消息;新回合使用当前默认预算,原运行的 checkpoint 仍保留原快照。
### 模型测试失败
检查 Base URL、模型名、API Key、代理和服务商余额。模型支持 JSON Mode 或联网搜索的方式不同,应以配置中心测试为准。
### Reddit 没有登录状态
必须在专用脚本打开的 Chrome 中登录;不要使用日常 Chrome 窗口。确认 Profile 位于 `data/reddit-chrome-profile`,并检查 CDP 端口与配置一致。
### 网页识别不到列表
确认填写的是列表页而非详情页;补充明确采集意图。系统会自动尝试动态渲染,但验证码、复杂登录、无限交互和反爬挑战不会被绕过。
### RSSHub 无法启动
检查 `RSSHub/` 是否存在、1200 端口是否占用以及依赖是否安装。可以重新运行 `setup-workbench.cmd`;RSSHub 的额外依赖仍按向导提示处理。
### 任务一直显示运行中
刷新任务状态。若服务曾重启,任务应转为 `interrupted`;从失败面板或对应阶段重新执行。不要直接编辑数据库状态。
### 如何彻底重置
先停止服务并备份,再删除运行时目录 `data/`、`articles/`、`topics/`、`social-cards/` 和 `logs/`。这会不可恢复地清除本地工作区,不要在服务运行中操作。
## 12. 安全提醒
工作台没有公网鉴权,不要修改监听地址并公开部署。`x-admin-confirm` 和 `x-restore-confirm` 只用于防误触,不是访问控制。外部上传、远程插件和模型调用会把对应内容发送给第三方,具体数据流见[data-flow.md](./data-flow.md)。