goodbuddy/docs/pr-articles

GoodBuddy PR 宣传文章工作流

本文件用于 GoodBuddy 项目的产品宣传文章。这里的 PR 指产品传播，不指 GitHub Pull Request。 它是项目工作约定，不属于随应用分发的 Skill，不要求修改产品代码。 本文件集中维护流程、正文模板、截图步骤和占位标注，不另设分散的流程文件。 各版本目录只保存具体文章、审校记录和实际素材。

触发与范围

用户说“准备本轮 PR”“按上一个 tag 写发布文章”或要求重点功能宣传时，执行本流程。 默认交付文章和素材，不自动提交 Git、打版本 tag、发布版本或向外部平台发文。 版本发布操作遵循 发布手册。本流程是可选配套，不阻塞软件发布。

本页导航：

• 核查与选题：完整盘点、用户视角排序、讨论确认。
• 重点稿模板、常规与综合稿模板：确认选题后起草。
• 截图执行步骤：隔离环境准备、真实操作与素材取证。
• 草稿就地标注：待补图、待替换和待核对。
• 交付与发布核对：归档、链接检查和标注清理。

默认顺序是：完整盘点新增与改动 → 从用户视角排序 → 与用户讨论并确认选题和结构 → 起草及截图 → deai 审校 → 交付。不要跳过盘点直接写文章，也不要用已经写好的初稿代替选题讨论。 用户已明确确认的范围和结构不重复询问；用户明确要求跳过讨论直接起草时，仍先完成盘点与排序。 成稿按 新增功能 → 功能改进 → 问题修复 的固定顺序分段，问题修复放在最后。 用户视角排序用于各段内部的主次与篇幅，不改变这三段顺序。

先读取仓库指引、Git 状态、桌面版本 tag 和提交历史。默认比较当前分支最近的正式桌面 tag 与当前 HEAD；明确记录基线 tag、目标提交和检查日期。Agent tag 单独核对，不混作桌面基线。 若 HEAD 已位于正式 tag，先根据用户所指的发布版本确定比较区间，不能默默换成另一轮发布。

未提交改动单列，不将设计文档、原型、计划或仅有接口的实现算作已交付能力。 保留用户工作区改动。全文不得把候选提交写成已经发布或可以下载的版本。

核查与选题

1. 先列全新增与改动

提交信息和 Release note: 是线索，实际 diff、最终代码和验证记录是事实依据。 先检查整个比较区间，再按产品功能归并，列出所有用户可感知的新增、能力扩展、行为调整、 兼容性变化和修复。不能先挑几个准备宣传的点，再只为这些点找证据。 同一功能的多次实现和修复合成一项；纯技术维护可以归组注明，不要求逐条翻译提交。 未提交改动、未完成实现和规划单列，不能混入本轮已实现功能。

盘点表使用以下信息，简短描述也必须保留事实来源：

功能	变化类型与状态	原来怎样／本轮变化	目标用户、任务与使用入口	使用条件与边界	来源与验证
按完整产品能力命名	新增／扩展／调整／修复；实现、验证、发布状态分别记录	说明真实差异，不把旧能力包装成新增	用户能完成什么，在哪里操作	相关部署、费用、数据、保存和升级要求	提交、代码或文档及实际验证范围

盘点完成后，将准备入文的内容明确归入三类：

• 新增功能：用户以前没有的能力，包括现有模块中的新用途；例如首次提供画布记录或会话置顶。
• 功能改进：已有功能的操作、布局、反馈或效率改善，不改变其原有用途。
• 问题修复：在具体条件下出现错误、中断、数据遗漏或不一致，改后恢复预期行为。

按用户实际感知分类，不直接照抄提交的 feat／fix 标签。同一提交可能包含不同类别。 一项内容只作一次主介绍，不在三段重复列出；新功能中的正常使用说明不必拆成独立改进或修复。 规划另标状态，不能列为已提供的新功能。

保留能力的完整范围，不用一个子功能代替整项能力。例如，画布笔记包括分页书写、图文混排、 保存与导出，PDF 批注只是其中一部分；HTTP OCR 接入则要放在文档识别、预览和后续使用中理解。 这些例子用于防止遗漏，不固定后续每轮的选题或排序。

将已知验证记录与本轮实际运行结果分开。定向测试通过不能写成全量通过，组件 fixture 不能写成完整应用端到端通过。发现失败如实记录，不为写文章擅自修复源码。

2. 从用户视角确定主次

基于完整盘点完成分类，在三段各自内部给出推荐顺序，并解释每项为什么值得这个篇幅。判断时考虑：

• 用户因此新增了什么做法，或哪个原本受阻的任务现在可以完成。
• 对实际工作结果的影响，是新增工作方式、补齐流程，还是减少一次操作。
• 适用人群和使用前提，包括特定角色、远程主机、自建服务等；没有数据时不编造使用频率、 用户占比或效率收益。
• 是否有明确的产品方向意义。应用管理通向未来应用市场、市场支持私有化部署等已确认方向， 可以解释，但必须把当前能力和后续规划分开，不能当作已经上线的功能。
• 实现与验证是否足以支撑准备写出的结论；证据不足的内容应缩小表述或列为待确认。

据此区分各段的重点与简述项。修复按用户影响排序，数据、任务和结果问题需具体说明， 不能因为放在最后就遗漏或用“提升稳定性”概括。不设固定数量或机械评分， 也不以代码量、技术新颖程度、提交数量、用户最近提及的词决定顺序。用户指出一个遗漏或举一个例子， 应重新检查完整清单和整体主次，不自动把该项提升为第一条。

按用户任务组织相关能力，先讲动作与结果，再解释技术与设置。例如，文档预览、选图、保存与 OCR 可以构成同一资料处理场景；不能因此暗示尚未实现的自动联动。主要能力应完整展开，不能把篇幅 都用在按钮、布局和限制说明上。部署、费用、数据和升级边界仍需保留。

3. 先讨论选题，再写初稿

起草前，先向用户展示：

1. 完整的新增与改动清单，包括暂不推荐入文的内容。
2. 按三类分组、各组按用户视角排序的重点、推荐理由，以及待确认事实。
3. 推荐标题和提纲，各节准备说明的用户任务、结果及必要图片。
4. 拟合并介绍、简述、仅进更新日志或不写入的项目及原因。

得到用户确认后再起草；有调整时更新整体结构，不只机械换标题或移动一段文字。 这一阶段讨论的是选题、篇幅和结构，不提前交付一篇已经取舍完毕的文章。 选题确认不等于授权构建、收费调用、打 tag 或外部发布。

根据确认后的内容选择重点 PR、常规 PR 或综合更新稿，不按版本号或凑篇幅决定。 重点 PR 围绕一项能力或同一使用场景展开；常规 PR 可只有几段；综合稿可以有多个独立重点， 但仍按新增功能、功能改进、问题修复分段，主次清楚，不平均分配篇幅。只有某一类内容时不虚构 其他类别，空段可省略；重点专题只列相关变化，保留同样的相对顺序。纯维护版本可以只写修复日志， 但已经入选综合稿的用户可感知修复必须在末尾列出，不能藏入“其他改进”或只给一条日志链接。 变化不足时明确建议暂不单独发文。

在本轮 review.md 保存完整盘点、推荐排序及理由、用户确认的结构和取舍。讨论阶段可以只建立 该记录，不创建空 article.md、空素材目录或无正文的文章索引项；记录为“选题讨论”， 确认起草后再按下文交付。已有能力可作为背景，但不能包装成本轮新增。

自动截图与演示

按已确认的用户任务和文章主次安排截图，不因某个技术配置页容易截图就将它作为宣传重点。 主图优先展示用户实际完成的内容或结果，配置页用作必要的接入说明；未来市场等规划不用原型 冒充已交付功能。截图是工作流的实际执行步骤，不能默认把任务留给用户。 按下方截图执行步骤准备隔离环境，遵循项目自动化规范。 先检查现有应用启动、Electron 自动化和截图工具，复用已验证的机制。 根据选题编排一个短的真实操作过程，记录每张图片要证明的行为，再执行和截图。

优先使用对应版本的运行应用或已有构建，并使用独立演示配置与公开、虚构的测试资料。 记录应用版本或构建提交；已有构建落后于目标源码时，不能把截图标为目标版本。 不要为截图修改应用源码、产品默认配置、用户数据库或用户正在工作的会话。 确需临时自动化脚本时放在独立临时目录，不加入产品实现或分发目录。 构建与打包遵循仓库约定，不能为了截图绕过发布流程中的本地构建限制。

可用的浏览器工具可用于可访问的网页与 Web 演示；桌面应用截图使用已有 Electron 自动化能力或其他实际可用的桌面工具。不能假定网页浏览器工具能控制 Electron 应用。

截图要求：

• 使用真实界面和实际结果；不修改 DOM、伪造任务状态或拼接理想答案冒充实测。
• 产品主截图优先来自正常 UI 到真实实现的完整路径。组件 fixture 或原型只作明确标注的辅助图。
• 操作后等待页面加载、目标状态和布局稳定，再截图。逐张读取图片，检查可读性、裁切和状态。
• 避免真实客户信息、私人会话、凭据和内部地址。优先重新使用演示数据拍摄，必要脱敏须注明。
• 裁切、缩放和标注不能改变产品含义；保存原图，并区分原图与发布用图片。
• 使用统一窗口大小、主题和演示命名。图注说明操作与结果，避免只写“功能截图”。
• 调用收费模型、访问外部系统或执行写操作时，遵循当前会话已有授权及工具要求。

自动化不可用、版本不匹配或正常路径无法完成时，记录具体阻碍，继续完成独立的核查和写作。 缺少的图片须在正文对应位置标注，并与内部待补清单对应，不能只把要求放在 review.md。 不能声称截图已完成，也不能用原型替代后隐去说明。

截图执行步骤

隔离启动和自动化实现遵循Electron UI 自动化规范。 目前仓库没有通用的一键完整 App 截图命令，下列步骤需要适配临时驱动，不是已经实现的 runner。

1. 确认版本和素材

从仓库根目录检查 git rev-parse HEAD、git status --short、node --version 和 node -p "require('electron/package.json').version"。依赖缺失时按开发与构建准备， 不重复安装已满足的依赖。在本轮 review.md 记录目标提交、实际构建来源、平台、语言、主题、 缩放和截图清单，优先采用 1280×800 内容区，并记录实际尺寸。

开始拍摄前应已确认选题。每张图说明操作与结果，重点稿优先连续演示，常规稿只拍有助理解的变化。 缺图按草稿就地标注放在正文拟插图位置，编号、优先级及计划文件名与内部清单一致。

2. 准备隔离环境

使用本轮专用临时目录保存 profile、演示工作区、驱动和原始截图，不复制整套私人会话。 只用公开或明确虚构的资料；凭据沿用已授权的安全配置方式，不写入脚本、文档或图片。

npm start 只预览已有产物，不自动重建或隔离数据；npm run dev 也不能代替隔离启动器。 GOODBUDDY_WORKSPACE 只指定工作区，不隔离用户数据库。不存在可直接假定有效的 GOODBUDDY_TEST_MODE 或 GOODBUDDY_USER_DATA 开关。

使用可确认属于目标版本的产物。开发场景的构建方法见自动化规范，发布准备遵循 发布手册。宣传材料不自动授权本地生产构建、打包或 packaged-app 探测；没有匹配产物时记录缺口，继续准备其他材料，不将旧产物标成新版本。

3. 启动与操作

准备独立 Node supervisor 和 Electron bootstrap：

1. 在 Electron ready 之前设置专用 userData、sessionData 和日志路径，再动态导入对应产物的 out/main/index.js，由生产 Main 创建窗口并加载真实 Preload、Renderer。
2. supervisor 从仓库解析 Electron，清除子进程环境中的 ELECTRON_RUN_AS_NODE，设置有限期限。 检查最终用户数据路径仍在临时目录，避免便携模式覆盖隔离配置。
3. 适配完成后执行 node "<本轮临时目录>/run.mjs"。这是驱动命令模板，不是仓库现成入口。 记录驱动来源、实际命令、入口文件与构建身份。
4. 从正常 UI 创建演示项目、会话和配置，通过 Electron 输入 API 操作。等待目标状态、字体与布局 稳定后使用 capturePage().toPNG() 截图，不注入完成事件或假答案替代真实任务。

现有 node build/run-browser-tabs-electron-e2e.cjs 可参考启动与进程监督方式，但它是浏览器服务 集成测试，不是完整应用截图命令。网页浏览器工具不能直接当作桌面控制器；组件 fixture 只能作为 明确标注的辅助图，不证明主功能完成。

4. 审阅与归档

逐张打开原图，检查文字、裁切、遮挡、状态与隐私。原生浏览器视图等复合界面需确认画面真正包含 展示内容，不能仅凭 PNG 文件存在判定成功。保存原图，裁切或标注另存，处理不得改变产品含义。

将采用的图片归档到 assets/，在正文原「待补图」位置换成相对路径图片及核实后的图注。 review.md 同号记录操作、文件、实际结果、图片审阅及模型／服务调用情况。失败时保留标注、 失败阶段和脱敏诊断；不采用的建议／可选图删除标注，必补图取消需先确认调整演示方案。

先归档必要材料，再停止本轮进程和服务，清理临时 profile；不得按进程名批量结束用户应用。 发布前核对最终版本与图片一致，有变化则重拍受影响部分。

写作与审校

按确认后的提纲采用所选模板，不在写作中悄悄遗漏已确认重点或把完整能力缩成一个子功能。 正文固定分为“新增功能”“功能改进”“问题修复”，段内按用户价值安排篇幅。问题修复逐项写清 “什么情况下遇到什么问题 → 修复后怎样”，不只写技术机制或“优化稳定性”。未经验证的修复效果 不写成确定结果，也不承诺找回此前已丢失的数据。入口、版本和升级提醒放在开头或相关功能旁， 不在末尾修复段之后再开一段混合更新。 先说明谁能做什么、得到什么，再写使用入口及必要条件，避免把产品文章写成技术名词和配置项清单。 重点 PR 尽早介绍能力和使用条件，围绕真实演示展开；常规 PR 直接说明变化， 有必要才解释原来的不便。没有具体背景材料时不虚设场景，不为小改动反复解释价值。

模板中的编辑提示不能变成固定话术。不要求每篇都出现“比如你正在……”“这意味着……”或 “如果你经常……可以试试”。不强行总结、升华或配平段落；常规 PR 可省略小标题。 篇幅按内容决定，图片用于说明具体变化，不为装饰而凑数。 升级风险集中放在体验入口附近，详细修复链接到完整更新日志。

不编造效率数字、用户评价、客户案例或测试结果。不使用“永不错过”“完全避免”等超出 机制范围的承诺。持久保存、当前运行期间保留、跨项目可见和跨设备同步必须准确区分。

可用时使用 deai-writing 技能审校正文；无该技能时人工检查空泛形容词、模板化转折、 机械排比和重复总结。扫描器通过不代替逐段审读，还要检查篇幅是否反映已确认的功能主次、 是否堆砌实现术语、是否把未来方向写成现有能力。审校不能删除必要的能力边界和升级提示。

先交初稿供用户讨论，按反馈修改；若反馈改变文章主次，回到完整清单重新说明排序与取舍， 不跟随最近一个关键词反复改方向。保留事实依据和截图缺口，不把编辑反馈当作产品验证。

草稿就地标注

初稿交付时，直接在需要补图、替换文字或核对事实的位置加入醒目的引用块，不把待办全部留到 文末或内部记录。使用下列三类标注，并在稿件开头说明它们是发布前应处理、删除的编辑提示：

标注	用途	必须说明
【待补图 01｜必补／建议／可选｜主题】	标记实际图片插入位置	用户操作、画面须证明的结果、计划相对文件名、建议图注和必要的隐私／真实性要求
【待替换 R01｜主题】	标记未确定的版本、日期、链接、包版本或暂用文字	要替换的具体句子／字段、填写格式及确认依据；信息未知时不编造
【待核对 C01｜主题】	标记须与最终发布版本比对的行为或条件	核对对象和处理方式；只有行为变化时才改正文，不把已核实说明全部变成占位

补图按正文出现顺序编号，替换项用 R01 起编号，核对项用 C01 起编号。review.md 保存同号 清单和处理状态，计划文件名与正文一致。编号便于讨论，不规定每篇图片或标注数量。

必补图用于支撑已确认的核心演示；建议图帮助解释，可在编辑时决定不采用；可选图仅作补充， 不用时删除标注，不为凑数拍摄。未取得素材时，文件名只写为代码文本，如 assets/01-canvas-note.png，不要插入不存在的 Markdown 图片链接，也不要创建空 assets/。 取得并审阅图片后，在原位置换成相对路径图片和符合实际结果的图注。

待替换项应覆盖实际缺口，例如预览标题与正式版本信息、下载和完整更新日志链接、外发平台需要的 公开文档链接、桌面与 Agent／Runtime 配套版本。仓库内阅读有效的相对链接不必一律替换； 外发时才改为可访问的完整链接。参考句式里的 {版本}、{链接} 等字段都须核验后填写， 不能把开发包当正式包，或提前把预览改成已发布。

未来功能规划不是等待替换成“已上线”的占位。服务地址、密钥和私人资料不作为正文待填字段。 占位标注不代替实际截图与核查，也不扩大构建、收费服务调用或外部发布授权。

重点稿模板

用于一项值得展开的能力或同一工作场景。先完成选题确认，在 review.md 记录目标用户、任务、 变化、证据、条件和取舍，再使用模板。保持完整能力范围，不用一个易演示的子功能代替整项能力。 只保留与主题有关的类别，顺序仍为新增功能、功能改进、问题修复，无内容的类别可省略。

下面方括号和引用块均为编辑示例，按实际缺口填写，不规定字数或功能数量。取得图片后用真实图片 和图注替换原标注；发布前按交付核对清除编辑提示。不要编造用户经历、设计动机或演示结果。

# [具体功能或用途，版本号可放副标题]

> **编辑标注说明（发布前删除）：** 待补图标记素材位置，待替换标记未确定信息，待核对标记最终版本检查项；标注中的素材尚未取得。

[直接介绍能力、适用用户和使用条件。]
[版本、体验入口、使用文档及必要升级说明；未发布则明确预览状态。]

> **【待替换 R01｜版本与链接】** [指出待替换句子、所缺字段及核验条件。]

## 新增功能

### [一个实际任务]

[用公开或明确虚构的演示资料，说明要完成的任务。]

> **【待补图 01｜必补｜用户任务结果】** [操作、画面应证明的结果与隐私要求。] 计划文件：`assets/01-result.png`。
>
> 建议图注：[实际操作或结果。]

[结合结果介绍完整能力，补充图中无法说明的内容。]

### [值得单独解释的能力或设计选择，可省略]

[据事实展开，保留相关前提、费用、数据流向和限制。]

> **【待核对 C01｜最终行为】** [仅有实际缺口时保留，说明核对对象和变化后的处理。]

## 功能改进

[主题内已有功能的操作或结果如何改善；无内容可省略。]

## 问题修复

- [相关问题、出现条件与修复后的行为；无内容可省略，不强塞无关修复。]

审校重点：已确认能力是否完整，标题是否准确，演示能否支撑结论，是否重复解释价值或混入无关更新。 三类必须分开，修复在最后；配图按本页截图步骤执行。

常规与综合稿模板

用于不同功能的更新、体验改善和修复，也可承载经确认的多个主要新增能力。主次决定篇幅， 不强行拼成一个故事或平均分段。先确认完整盘点及组内排序，在 review.md 保留来源和取舍。 纯维护更新可只保留问题修复，其他空段可省略，不虚构内容凑齐三段。

# GoodBuddy 更新：[最值得关注的变化]

> **编辑标注说明（发布前删除）：** 待补图标记素材位置，待替换标记未确定信息，待核对标记最终版本检查项；标注中的素材尚未取得。

[一两句话概括变化；信息重复时省略。]
[版本、下载入口、升级说明和完整更新日志；未发布则明确预览状态。]

> **【待替换 R01｜版本与链接】** [指出待替换句子、所缺字段及核验条件。]

## 新增功能

### [新能力或用户用途]

[现在能怎样操作、得到什么；必要时简述原来的不便。]

> **【待补图 01｜建议｜变化展示】** [操作、结果与隐私要求；按选题改为必补或可选，无需配图则删除。] 计划文件：`assets/01-change.png`。
>
> 建议图注：[实际操作或结果。]

> **【待核对 C01｜最终行为】** [仅有实际缺口时保留，说明核对对象和变化后的处理。]

## 功能改进

[逐项说明已有功能如何更好用，各项按用户影响排序。]

## 问题修复

- [什么情况下出现什么问题；现在恢复怎样的行为。]
- [下一项修复，保留实际影响与必要边界，不重复新增或改进项。]

审校重点：主次与确认后的提纲一致，无空泛开场、虚设场景和总结口号；旧能力不包装成新增， 规划与本轮能力分开。入选修复在最后具体列出，不藏在“其他改进”或用“提升稳定性”代替。 明显界面变化可配图，其余直接说明；不用的建议／可选图删除标注，不保留缺图链接。

交付与发布核对

文章及草稿统一归档在工作流所在目录下，使用 docs/pr-articles/YYYY-MM-DD-<版本tag>/，例如 docs/pr-articles/2026-09-16-v0.13.6/。 日期采用本轮材料首次建立的日期；版本 tag 指文章介绍的目标版本，不是比较区间的起点。 Agent 专题使用对应的 agent-v… tag。

草稿与正式稿沿用同一目录，不再单设 drafts/；发布时更新正文和状态，保留图片相对路径， 方便整目录交付与传播。目录名不表示版本已经发布，实际状态记录在 review.md。 目标版本尚未确定时暂用 YYYY-MM-DD-unreleased/，确定后改为目标 tag 并更新文档链接， 不能自行推测下一版本号。同一版本同一天有多篇文章时，在该目录内按主题建立子目录。 目录只包含本轮文章与必要素材，不改产品代码。

初稿起草后的最小交付：

• article.md：文章标题、正文、相对路径配图和图注。
• assets/：实际取得的图片；如有处理，保留可区分的原图。
• review.md：草稿／待发布／已发布状态、目标 tag 与提交、比较区间、完整功能盘点、 用户视角排序及理由、已确认的选题结构与取舍、事实来源、截图环境与步骤、验证范围和待补事项； 外部发布后补充发布日期与链接。

没有图片时不建空目录。草稿按就地标注规则显示缺口；发布用正文不得留下占位文字。 内部验证细节放在 review.md。草稿中允许上述就地编辑标注，正式对外正文必须清除，不附内部记录。 初稿生成后，在本页末尾的文章索引登记日期、目标 tag、标题、状态及正文链接； 正式发布后同步更新状态和外部链接。对外传播正文与所需图片，不附内部核查记录。

交付前检查图片可读、相对路径存在、文章与图片一致、标题没有超出功能事实。 发布前再次确认对应版本可下载、下载链接有效、升级说明准确，且最终版本没有改变演示行为。 尚未发布时保持草稿状态，不编造版本号或上线时间。

发布前逐项核对正文和 review.md 中的标注：必补图须取得、审阅并插入，若要取消则先确认调整 演示方案；建议／可选图决定不用时删除其标注。填写并核验待替换字段，完成待核对项，随后删除 已处理的引用块及稿件开头的编辑标注说明。搜索“待补图”“待替换”“待核对”和模板字段， 确认发布稿无残留提示、缺图链接或未填写值。仍有必要信息未确定时保持草稿，不能仅删除标注当作完成。

最终回复提供文章和素材位置，概括推荐主题、实际截图情况及剩余阻碍。 只有得到明确发布指令后，才通过可用平台能力执行外部发布；准备文章不等于授权发布。

文章索引

日期	目标 tag	标题	状态	正文	发布链接
2026-09-19	未确定（unreleased）	GoodBuddy 更新预览：画布笔记、文档处理与应用管理	草稿，截图待补	综合更新稿	���发布
2026-09-26（10-05 更新）	v0.15.11（78afec77）及之后截至 e50ca6d1；汇总 v0.13.8 起的变化	GoodBuddy 更新：故事图谱、Obsidian接入、Runtime原生终端	草稿，已补 Telegram 私聊、统一执行、项目会话菜单、文件导入、自定义回顾日期、监督模型与会话图谱开关、临时失败重试、3D 和性能改进；Telegram 实际联调、生产配图及公开发布信息待核验	综合更新稿	未发布