docs: consolidate product PR workflow and draft update article

Keep feature inventory, user-focused prioritization, draft confirmation,
article templates, screenshot guidance and publication checks in one guide.
Use separate new-feature, improvement and bug-fix sections, with explicit
image, replacement and verification markers in drafts.

Archive the unreleased update article and its evidence review, retaining
pending screenshots and release details. Remove the split guide files and
update release-runbook references.

Validation: documentation structure, draft markers, 59 local links and
anchors, and staged whitespace checks passed. No product code changed;
product tests and builds were not run.
This commit is contained in:
mesalogo
2026-09-19 23:45:28 +08:00
parent a3b7a27045
commit ecf09f4e95
7 changed files with 601 additions and 155 deletions
+3 -3
View File
@@ -15,12 +15,12 @@ below.
Product publicity is an optional companion to a release, not a release blocker
or a replacement for the approved bilingual release notes. When requested,
follow the [PR article workflow](../pr-articles/README.md) and choose either the
[featured article](../pr-articles/featured-template.md) or
[regular update](../pr-articles/regular-template.md) template based on user value,
[featured article](../pr-articles/README.md#重点稿模板) or
[regular update](../pr-articles/README.md#常规与综合稿模板) template based on user value,
not version size or commit count.
Prepare the draft and real screenshots against the candidate commit using the
[isolated screenshot procedure](../pr-articles/screenshot-guide.md). This does
[isolated screenshot procedure](../pr-articles/README.md#截图执行步骤). This does
not waive the build, packaging, or launch restrictions below. Keep missing
materials in the article's review record without delaying the software release.
Before external publication, verify the final version, download links, upgrade
@@ -0,0 +1,136 @@
# GoodBuddy 更新预览:画布笔记、文档处理与应用管理
> **编辑标注说明(对外发布前删除):**「待补图」是图片放置位置,含必补、建议和可选三种优先级;「待替换」是尚未确定的发布信息或外发链接;「待核对」只在最终版本行为有变化时改文案。以下图片均未拍摄,文件名仅为计划,不是已有素材。
魔法笔记可以在同一页里写字、画图、放图片,也能导入 PDF 做批注。聊天和知识库中的文档则可以查看解析后的图文,选取插图继续提问,保存的附件在重启后仍能回看。
这次更新以画布笔记和文档处理为重点,同时加入应用管理、Agent 执行清单和远程 Continue。应用管理也将成为后续私有化应用市场的入口。以下内容来自尚未发布的开发版本,正式版本号和下载入口待定。
> **【待替换 R01|标题与版本信息】** 正式版本可下载后,将标题中的“更新预览”改为实际发布标题,并替换上一段最后一句。参考句式:`GoodBuddy v{桌面版本} 已于 {发布日期} 发布。下载:{正式下载链接};完整更新日志:{更新日志链接}。` 所有字段须核验后填写;仍未发布时保留原预览说明,不填推测版本。
## 新增功能
### 画布笔记:文字、手写和图片写在同一页
原有富文本笔记之外,魔法笔记新增了分页画布。打开一本笔记,在顶部输入区选择“画布”,就可以从空白、横线、方格或点阵纸张开始记录。
画笔适合随手写画,高亮笔用来标记重点。正文可以键入并跨页排版,图片和浮动文字可以放到页面上,再移动、缩放或旋转。需要新的一页时可以继续添加,图文内容一起保存在这条画布记录中。
> **【待补图 01|必补|画布笔记主图】** 在这里放保存后重新打开的真实画布,画面同时包含键入文字、手写标记和虚构示意图片,尽量带上左侧记录索引,勿只拍空白画布。计划文件:`assets/01-canvas-note.png`。
>
> 建议图注:同一页画布中混排文字、手写标记和图片,保存后仍可继续编辑。
#### 在 PDF 上批注,保存后继续编辑
PDF 可以作为底版导入,在原页面上圈画重点、补写说明。点击“保存”后,以后仍能从这条记录的“编辑”入口继续修改。需要分享时,可以导出带批注的 PDF。
> **【待补图 02|建议|PDF 批注】** 在这里放一份虚构 PDF 导入画布后的截图,展示原文、高亮和补充文字。计划文件:`assets/02-pdf-annotation.png`。若改用导出文件截图,图注须明确是导出结果,不能暗示仍有可搜索文字层。
>
> 建议图注:将 PDF 作为底版,在原页面上圈画重点并补充说明。
导出的每一页由背景、文字和批注合成图像,不保留原 PDF 的可搜索文字层;需要检索或编辑原文时请保留原文件。画布导入扫描 PDF 本身不会触发 OCR,也不保证将手写内容转换成文字。
编辑和阅读都支持 25% 到 300% 的缩放,点击百分比回到 100%。“适应宽度”会随窗口或侧栏宽度调整,只改变观看大小,不改保存内容和导出尺寸。
笔记仍需手动保存。离开或切换编辑对象时会提醒未保存内容,但不提供自动保存或崩溃后的草稿恢复。每条画布记录最多 50 页,单个导入 PDF 上限为 32 MiB,单张图片上限为 20 MiB,其他限制见[画布说明](../../../src/renderer/src/magic-canvas/README.md)。
> **【待替换 R02|画布说明链接】** 对外平台发文时,将上方仓库相对链接换成最终发布版本对应、可公开访问的完整文档链接。若仅在仓库阅读,可保留相对链接;不要编造使用文档地址。
#### 请 AI 评论画布内容
书写、保存和导出无需模型。请求 AI 评论时,默认发送当前画布的第 1 页,可在魔法笔记设置的“发送画布页数”中选择 1~8,按页面顺序发送前 N 页;不足 N 页时发送全部页。这个数量指画布页数,不是笔记记录数。支持图片的默认模型收到所选页的图像和文字;纯文字模型只分析同一范围的文字,并标注未查看笔迹、图片和布局。所选页只有图像、没有可提取文字时,需要支持图片的默认模型。
> **【待核对 C01|最终版本的画布分析页数】** 核对最终发布提交是否包含“默认 1 页、可选前 1~8 页”的设置。若行为不同,按该版本的真实行为替换上一段,不直接沿用旧稿。此处不要求补 AI 结果图;没有真实模型生成证据时,不放模拟评论截图。
可以手动分析,也可以设为保存后自动分析。画布的“即时”模式同样需要手动点击,不会每画一笔就调用模型;分析失败不会撤销已经成功的保存。内容会发给配置的模型服务,多页画布会携带多张图片,费用按该服务计算。
#### 升级前请备份笔记
这次升级会把已有笔记正文和资源迁移到本地文件,数据库继续保存目录、索引等信息。**升级前请先备份。升级后的笔记备份要同时保留数据库和相邻的 `notes/` 目录。**
建议关闭应用后备份,恢复时将两部分一起恢复。只复制数据库,无法找回新版笔记正文和图片。目前没有一键备份按钮,具体要求见[备份说明](../../features/magic-notes/technical-design.md#backup-and-restore)。
> **【待替换 R03|备份说明链接】** 对外平台发文时,将上方相对链接替换为对应发布版本的公开备份说明链接,并确认能直接定位到备份章节。保留正文中的数据库与 `notes/` 成套备份提醒,不能用一个下载链接代替。
### 文档处理:查看图文、选图提问,之后还能回看
从聊天附件或知识库打开解析结果,可以查看正文中的文字、HTML 表格和已保存的插图。“图片”页集中展示提取出的图片,“详情”页记录本次解析的配置、耗时和警告,方便对照文件检查结果。
文档中的某张图需要单独讨论,可以在预览中选取,添加到目标会话,再交给支持图片输入的模型。选图只加入草稿,由你补充问题并发送。会话保存的是独立副本,之后删除或重新解析源文档,不会影响这张图片。
> **【待补图 03|必补|文档图文预览与选图】** 在这里放正常聊天导入后的真实解析预览,显示正文/图片入口及选图加入会话的操作或实际结果;不能用没有选图能力的“设置测试”窗口替代。计划文件:`assets/03-document-to-chat.png`。若图注提到 PaddleOCR-VL,必须使用该服务实际返回的结果。
>
> 建议图注:查看文档解析出的图文,选择需要讨论的插图加入会话草稿。
聊天文件会随草稿、消息或排队请求保存。只要这些记录仍引用附件,重启后就能重新打开文件和已有解析结果,回看无需再次做 OCR。历史附件要重新解析时,可以复制到当前草稿,原消息保持不变;排队中的附件需要修改,则先恢复到草稿。
知识库文档也能使用当前设置重新解析。新结果成功后才替换正文、分块和图片,失败时保留旧结果。
附件保存从本轮版本开始生效,旧消息中原本没保存的文件不会自动补回。
#### 扫描资料可以接入团队的 PaddleOCR-VL 服务
对于扫描 PDF 和图片中的文字,本轮新增 **HTTP PaddleOCR-VL 接入**。已有这项服务的团队,可以将它用于聊天附件和知识库导入,桌面端无需为此下载本地 OCR 模型。原有本地解析仍然可用。
在“设置 → 文档解析”选择“远程服务”,填写地址,并按部署选择无需认证或 Bearer API Key。服务配置共用,聊天和知识库可以分别选择解析方式:自动模式先读 PDF 的原生文字,仅将需要 OCR 的页面交给服务;高保真模式可以发送整份 PDF;快速文本/快速索引模式不上传 OCR 内容。PPTX 保留原生文字,并按设置识别幻灯片直接引用的内嵌图片。
内容过滤可以沿用服务默认、全部保留,或自行决定是否保留页眉、页脚、页码等内容。跨页表格可启用合并,整理结果保留来源页供核对。方向分类、去扭曲、图表与印章识别、标题层级调整也有配置入口,实际效果取决于文件和服务部署。
保存后,可以从“测试解析”选择聊天或知识库场景,用实际文件检查结果。测试文件不会加入正式会话或知识库;“检查连接”只确认服务可连接,不代替解析测试。
> **【待补图 04|可选|HTTP OCR 文件测试】** 若主图 03 不足以说明服务解析效果,在这里补真实文件测试的结果图,展示实际返回的文字、表格或插图。计划文件:`assets/04-http-ocr-test.png`。不暴露服务地址或密钥,不用连接成功提示冒充解析结果。
>
> 建议图注:用实际文件测试 HTTP PaddleOCR-VL 的解析结果。若不采用此图,删除本标注即可。
普通聊天图片默认仍以图片发送。只需要文字时,可选择“提取图片文字”,也能切回发送原图。手动提取会调用已保存的 OCR 来源,即使聊天采用快速文本模式。HTTP OCR 会把需要识别的页面或图片发到配置的服务,跨页整理还会增加请求,请确认资料使用范围和服务费用。
### 应用管理:当前管理内置应用,后续连接私有应用市场
侧栏底部的应用中心提供统一入口。进入“管理应用”,可以搜索、打开内置应用,修改可选应用设置,并调整四个应用的顺序。菜单和侧栏采用同一份保存后的顺序。
知识库和智能心跳始终显示;魔法笔记、本机推理监控可以设置是否启用、是否常驻侧栏。新配置中的本机推理监控默认不常驻,需要时从应用菜单打开,已有设置会保留。
> **【待补图 05|建议|应用管理】** 在这里放真实“管理应用”界面,显示当前四个内置应用、打开/设置入口及排序操作。计划文件:`assets/05-app-management.png`。不要使用未来应用市场原型,也不要添加当前没有的安装或市场目录界面。
>
> 建议图注:在应用管理中打开、设置和排列内置应用,侧栏使用同一份保存后的顺序。
本机推理监控可以查看语音识别、OCR、向量等本地服务的状态,执行各服务实际支持的启停、重启或模型加载、释放。独立向量进程可显示 CPU 和内存占用;共享进程的服务会说明无法独立统计的原因。它不管理远程 HTTP OCR 服务,关闭监控窗口也不会停止本地服务。
**后续的应用市场将支持组织私有化部署。** 按规划,团队可以部署自己的市场,用户配置该来源后获取组织提供的应用,不必依赖公共市场。当前这一轮先提供内置应用管理;市场目录、应用获取与安装属于后续建设内容,尚未上线。应用市场来源也不会替换模型、桌面更新或 Runtime 的下载来源。
### Agent 执行清单与远程 Continue
OpenCode 和 Continue 提供的原生执行清单会显示在对话顶部,列出条目状态和完成数量,可以展开或收起。清单随对应消息保存,原来的工具活动记录仍然可查,本地和远程的 OpenCode、Continue 都支持。
清单由 Runtime 更新,用户只能查看,不能手动勾选。请求结束或取消后,条目保留实际状态,剩余事项不会自动变成“已完成”。Runtime 没有提供清单时,普通回复里的列表也不会被当成执行进度。
远程项目新增 Continue 选择。安装匹配的 GoodBuddy Agent/Runtime 包后,可以从桌面发送请求,由远程主机执行,支持 Ask、Execute、停止当前请求及应用重启后续发;取消后也能在同一对话接着使用。仅更新桌面应用还不够,正式远端包及版本组合以发布说明为准。
> **【待替换 R04|远程 Continue 的配套版本与获取方式】** 正式发布时,将上一段最后一句补为已核验的桌面版本、Agent 包版本、对应 Runtime 版本及包获取/安装说明链接。参考句式:`使用远程 Continue 需 Desktop {版本} 与 Agent {版本},配套 Continue {版本};安装说明:{链接}。` 不能将开发测试包写成可下载正式包;正式组合未确定时保持草稿状态。
> **【待补图 06|建议|远程 Continue 执行清单】** 在这里放真实远程 Continue 会话产生清单后的界面,展开顶部清单,能辨认 Runtime 和条目状态。计划文件:`assets/06-runtime-checklist.png`。使用虚构任务,不注入假事件,避免主机地址、工作目录或私人对话出现在画面中。
>
> 建议图注:远程 Continue 的执行清单显示在对话顶部,条目状态随本轮执行更新。
### 会话置顶
常用会话可以从菜单置顶,重启后仍保留,也可以随时取消置顶。
## 功能改进
### 笔记记录连续浏览
同一本笔记的文字和画布记录连续排列。左侧索引显示画布首页缩略图和页数,点击后滚动到对应记录,正在写的内容留在原处。索引与 AI 评论区可以分别收起,宽窗口下还可以调宽。保存一条新记录后,顶部输入区清空,供下一条使用。
### 常用操作更集中
应用管理采用紧凑单列列表,打开、设置和排序操作放在对应应用旁。聊天与图片预览的下载入口统一为带提示的图标按钮。顶部移除了重复的模型/Runtime 状态标记,模型选择和切换反馈保留在输入区,自动状态检查失败仍通过通知提示。
## 问题修复
- **长会话历史被截断**:修复连续发送时只保留最近 500 条消息的问题,追加消息会保留已有历史。模型的上下文窗口和既有压缩规则不变,也不会恢复此前已经丢失的内容。
- **较早会话找不到**:会话列表和搜索不再局限于最近 100 个会话,较早的未归档会话也能列出和搜索。
- **取消后紧接着发送异常**:修复 OpenCode 上一次取消影响下一次请求的问题;已结束的回复也不会因迟到的状态更新重新显示“停止”按钮。
- **弹窗遮住菜单和通知**:打开设置或其他对话框时,所属菜单和通知可以正常显示、操作,保留键盘导航和关闭后的焦点返回。
- **网页的新窗口链接无响应**:修复内置浏览器直接拦截这类链接的问题,现在会在 GoodBuddy 管理的标签中打开;AI 点击产生新标签后,后续浏览器操作会跟随新页面。
- **知识图谱抽取提前耗尽输出预算**:移除额外的固定 8192-token 限制。OpenAI 请求由模型服务决定输出上限,Anthropic 使用模型连接配置;服务自身的限制、超时和取消仍然有效。
@@ -0,0 +1,170 @@
# 综合更新稿核查记录
## 状态与范围
- 状态:**草稿,未发布,截图待补**。
- 首次建档及检查日期:2026-09-19。
- 按用户要求将原魔法笔记重点稿与常规更新稿合并,只保留一份[正文](./article.md)及本记录,原主题子目录稿件移除。
- 目标 tag:未确定,使用 `unreleased`,不推测下一版本号。
- 目标提交:`375b2159c80a56a4d76d7762f3ddcee6d7848c11`。
- 基线:正式桌面 tag `v0.13.6`,对应 `a383b2d11f1e834a30b08b0786ca0398da849d95`;比较区间 `v0.13.6..375b215`,35 个提交。
- HEAD 不在正式 tag 上;最近可达 Agent tag 为 `agent-v0.13.0`,不作为桌面比较基线,不代表新版 Agent 包已发布。
- 最初核查时工作区干净;合并前只有本轮两篇文章、核查记录与索引改动。未修改产品代码,未创建提交、推送、tag 或外部发布。
## 选题与结构
类型:按用户任务区分重点的综合 PR,沿用[常规模板](../README.md#常规与综合稿模板)组织不同功能,画布笔记与文档处理按[重点模板](../README.md#重点稿模板)展开入口、操作和结果。
按用户最终确认,正文固定为“新增功能 → 功能改进 → 问题修复”。重点排序只作用于各段内部,
问题修复在文末逐项列出,升级说明移到笔记功能旁。此前混写的“日常使用的调整”已拆分。
推荐标题:**GoodBuddy 更新预览:画布笔记、文档处理与应用管理**。
目标读者是使用 GoodBuddy 记录内容、处理资料和运行 Agent 的桌面用户。判断依据是[产品定位](../../../README.zh-CN.md)和本轮对实际任务的改变,不按代码量、技术名称或用户最近提及顺序排名。没有使用频率数据,不宣称哪类用户最多或收益最高。
| 层级 | 用户可以完成的任务 | 篇幅及边界 |
| --- | --- | --- |
| 核心重点:画布笔记 | 在分页纸张里混排文字、笔迹和图片,批注 PDF,保存后继续编辑或导出 | 完整介绍新记录方式;PDF 批注只是其中一部分。书写和保存不要求模型或 OCR 服务,因此用它开篇可直接展示工作成果,不从配置表单讲起 |
| 核心重点:文档处理 | 核对解析图文、选图提问、重启回看、重新解析;有团队 OCR 服务时接入使用 | 按资料处理流程合并预览、附件与 OCR;HTTP PaddleOCR-VL 充分展开,但不假定每位读者都先部署服务 |
| 产品方向:应用管理 | 当前管理内置应用,后续从组织私有市场获取应用 | 用户明确应用管理是未来应用市场入口,并保留私有化部署;与既有 FR-15 一致。单独成节,当前能力和规划明确分开,不降为排序按钮修复,也不宣称市场已上线 |
| Agent 用户新增能力 | 在对话里观察清单;远程项目选择 Continue | 清单与 Runtime 选择分别说明;远程功能保留主机及组件前提 |
| 简述新增:会话置顶 | 常用会话固定在前,重启保留 | 属于用户以前没有的能力,在新增功能末尾简述 |
| 功能改进 | 连续浏览笔记、常用操作布局与反馈 | 单独放入第二段,不混入故障修复 |
| 问题修复 | 历史截断、旧会话查找、取消后续发、浮层遮挡、网页链接、图谱预算 | 第三段逐项说明问题与改后行为,不因位于文末而省略 |
文档处理和画布笔记是独立入口,不暗示自动摘录、一键从附件生成笔记或跨应用自动联动。应用市场私有化是后续方向,不将此词扩展为本轮已提供服务端或任何依赖都可离线安装。
富文本笔记、待办、AI 评论和本地 OCR 原已存在,不写成本轮从零新增。HTTP 服务接入、画布和远程 Continue 是本轮新增能力。正文不宣称演示已经执行,不编造分析结果、效率数字或客户案例。
## 事实与来源
下表根据范围内 diff、最终实现及功能记录核查。提交信息用于定位,不作为唯一依据。
| 正文事实 | 提交线索 | 实现与权威说明 | 验证边界 |
| --- | --- | --- | --- |
| 分页画布、画笔、高亮、正文、图片、PDF 底版及导出 | `17186b0` | [画布 core](../../../src/renderer/src/magic-canvas/canvas-note.mjs)、[集成说明](../../../src/renderer/src/magic-canvas/README.md) | 已有 Electron core 和生产 IPC/存储记录;本轮没有重新运行 |
| 连续记录、缩略图索引、手动保存、新建后清空输入区及离开保护 | `17186b0`、`935a8f5`、`c98eb69` | [Workspace](../../../src/renderer/src/MagicNotesWorkspace.tsx)、[工作区设计](../../features/magic-notes/technical-design.md#continuous-record-workspace) | 功能级 Electron、真实数据库/文件及组件证据各自独立,不合并宣称完整 App 验收 |
| 25%–300% 缩放、适应宽度,不改变导出尺寸 | `c98eb69` | [缩放定义](../../../src/renderer/src/magic-canvas/README.md#view-zoom) | 历史记录为 41 项 Electron core 检查通过;未验证物理设备或 macOS |
| 图片 20 MiB、PDF 32 MiB、最多 50 页 | `17186b0`、`c98eb69` | [编辑限制](../../../src/renderer/src/magic-canvas/README.md#editor-limits) | 20 MiB 文件边界有 Electron 和真实文件存储测试;不能推导超大解码图片性能 |
| 按设置发送前 1~8 页(默认 1)、文字回退、手动或保存后分析 | `17186b0` 及当前工作树页数设置 | [分析器](../../../src/main/magic-notes/magic-note-analyzer.ts)、[分析契约](../../features/magic-notes/technical-design.md#canvas-analysis-and-comments) | 页数设置已通过真实 Electron 设置 UI、生产 IPC 和本地替代模型验证,覆盖显式及自动换页;真实模型调用 0 次 |
| 正文迁移到本地文件,备份需数据库和 notes | `17186b0` | [存储实现](../../../src/main/magic-notes/magic-note-storage.ts)、[备份契约](../../features/magic-notes/technical-design.md#backup-and-restore) | 有构造旧库迁移及重开证据,不是用户真实历史库迁移;没有一键备份或跨设备同步声明 |
| 附件保存、重启回看、文档选图、图片 OCR、队列恢复 | `935a8f5`、`a9b59ce`、`6f06fce` | [文档处理实现](../../features/document-processing/implementation.md)、[App](../../../src/renderer/src/App.tsx)、[解析服务](../../../src/main/document-parsing-service.ts) | 保存的是被草稿、消息等引用的资产,不是永不删除;旧历史缺失文件不自动补全 |
| HTTP PaddleOCR-VL 服务接入、解析模式、认证、图文预览、参数与文件测试 | 同上 | [数据流](../../features/document-processing/implementation.md#解析与设置)、[验证](../../features/document-processing/progress.md#2026-09-19-实现与验证)、[HTTP 设置](../../../src/renderer/src/HttpOcrSettings.tsx)、[解析设置](../../../src/renderer/src/DocumentParsingSettingsSection.tsx) | HTTP 路径不要求本地权重;快速路径不上传,显式图片 OCR 独立调用;跨页合表仅有连续两页样例证据,其他高级项只描述可配置,不保证效果 |
| 顶部执行清单、受管远程 Continue | `c7a9380` | [只读清单组件](../../../src/renderer/src/RuntimeChecklistStrip.tsx)、[清单设计](../../features/assistant-workbar/runtime-checklist-technical-design.md)、[远程记录](../../features/remote-host/runtime-checklist-validation.md) | 仅原生 OC/CN 清单;已有 Windows 桌面到共享 Linux x64 Host 记录,不代表所有平台或 Runtime 实测;正式包待确认 |
| 应用管理、共享排序、启用与常驻 | `bbae893`、`ca3c919`、`5aad0cf` | [ApplicationCenter](../../../src/renderer/src/ApplicationCenter.tsx)、[UI 定义](../../features/application-tool-navigation/ui-design.md)、[进度](../../features/application-tool-navigation/progress.md) | 知识库、智能心跳不可关闭;本机推理监控默认不常驻针对新配置或缺省配置,保留已有明确值 |
| 本机推理监控及后续私有化应用市场 | 当前功能见上行;市场方向由用户本轮确认及既有 PRD 定义 | [本机推理 UI](../../features/application-tool-navigation/ui-design.md#91-本机推理管理)、[FR-15](../../features/application-tool-navigation/prd.md#fr-15-私有化市场与-yaml-交换后续) | 监控只承载已支持的本地服务操作,不声称所有引擎有独立指标;私有市场是规划,当前没有目录获取/安装功能,不改变其他下载源 |
| 会话置顶、列表和搜索范围、发送历史 | `625182c`、`375b215` | [数据库](../../../src/main/assistant/assistant-database.ts)、[App](../../../src/renderer/src/App.tsx)、[历史存储](../../features/assistant-workbar/execution-history-storage.md) | 置顶持久化;移除数量截断不等于无限模型上下文,也不恢复已丢失历史 |
| 浏览器弹出链接、浮层菜单及通知、图片下载按钮 | `f1d7197`、`ec08109`、`b5d8204` | [浏览器设计](../../features/assistant-workbar/browser-tabs-technical-design.md)、[浮层验证](../../features/document-processing/progress.md#2026-09-19-全局浮层复验)及对应源码 diff | 仅描述交互变化,不增加“所有窗口永不遮挡”等保证 |
| OpenCode 取消后续发、已完成回复清除停止状态 | `94852ac` | [真实连续请求记录](../../features/assistant-workbar/consecutive-requests-live-2026-09-17.json)、提交中的 Runtime 与 App 差异 | 历史完整 App 验证为 Windows、本地 OpenCode、Ask,保留请求计数缺口;本轮不重跑、不推及全部 Runtime |
| 图谱抽取固定预算与顶部重复状态 | `b5d8204`、`df89d96` | [图谱请求实现](../../../src/main/knowledge/model-extractor.ts)、对应 App 差异 | 图谱保留 Provider 上限;顶部仅取消重复展示,输入区及失败通知保留 |
笔记历史验证见[功能进度](../../features/magic-notes/progress.md)。其中已被替代的单记录布局、SQLite 内嵌正文和旧按钮入口不作为现状。
## 未扩写的内容与效果边界
- 后台会话完成提示只在当前客户端运行期间保留,不能宣传成跨重启通知;最新 HEAD 有相关 App 测试失败记录,暂不作为卖点。
- 图谱取消额外 8192-token 预算已列入末尾问题修复,不写成“输出无限”:OpenAI 交由模型服务,Anthropic 使用连接配置。
- 子代理渲染、队列闪动和工具错误恢复等维护修复不展开为独立能力,不凭提交描述推导性能数字。
- 右侧资源监控和 story-graph 的规划/Demo 不算已交付产品。
- OCR 跨页表格只有特定有效样例,不宣传能恢复任意跨页表格。方向分类、去扭曲、图表、印章、标题层级调整只介绍配置入口,并说明需用实际部署确认效果。HTTP 设置里“尚未验证合并效果”的提示落后于进度记录中的连续两页样例,不据此否认已有证据,也不扩展为普遍成功;本次不修改该源码文案。
- Continue 与 DeepSeek Harness 的本轮真实图片消费未执行,不借附件流程宣传所有 Runtime 均已验证。
## 截图检查与待补素材
已读取[截图步骤](../README.md#截图执行步骤)和[Electron 自动化规范](../../quality/electron-ui-automation.md),检查结果如下:
- Windows x64,Node `v24.19.0`、Electron `43.2.0`;仓库存在 Main、Preload、Renderer 产物。
- `out` 目录时间约为 2026-09-19 21:19–21:20,目标提交时间为 21:34:42(+08:00)。时间不能证明构建是否包含当时未提交源码,未取得可核对的目标构建身份。
- `out` 标识搜索遇到两个尾点 LICENSE 路径读取错误,未将其视为完整扫描。已有独立 Electron supervisor、完整 App 驱动和视觉探针可参考,但存量图片不作为本轮素材。
- 用户明确选择“先完成文章,截图缺口记入待补清单”。未构建、未启动演示应用、未创建 profile,也未用原型替代截图。
**实际截图 0 张。** 不创建空 `assets/`,正文使用醒目的「待补图」文字标注位置,计划文件名仅作代码文本,不插入不存在的图片链接。取得并审阅图片后替换标注为相对路径图片及真实图注。
后续统一采用中文、浅色主题、100% 应用缩放、1280×800 内容区,画布缩放另记。拟用虚构的两页《示例培训安排》,包含原生文字与插图;不用私人会话或客户文件。
| 优先级 | 建议文件名 | 正常 UI 操作 | 要证明的结果/建议图注 |
| --- | --- | --- | --- |
| 必补 | `assets/01-canvas-note.png` | 新建画布,在纸张上键入正文、添加笔迹及虚构图片,保存后重开 | “同一页画布包含文字、手写标记和图片,保存后可以继续编辑。” 主图展示画布整体能力,不仅展示 PDF |
| 建议 | `assets/02-pdf-annotation.png` | 在另一条画布中导入 PDF,圈画并补文字,保存和导出 | “在 PDF 原页面添加批注。” 导出文件另拍时注明图像合成、不含可搜索文字层 |
| 必补 | `assets/03-document-to-chat.png` | 聊天正常导入虚构扫描 PDF,经真实 HTTP OCR 后打开图文预览,选图加入草稿,再重开核对结果 | “查看解析图文,选择插图加入会话。” 不用测试预览替代正式导入,不显示服务地址或密钥 |
| 可选 | `assets/04-http-ocr-test.png` | 从隔离设置执行真实文件测试,查看结果 | “用实际文件检查服务解析结果。” 配置和测试作为辅助图,不替代用户成果主图 |
| 建议 | `assets/05-app-management.png` | 从应用中心打开管理,调整顺序并重新打开核对 | “在应用管理中打开和排列内置应用。” 不放未来市场原型,不伪造安装目录 |
| 建议 | `assets/06-runtime-checklist.png` | 从远程 CN 项目的正常输入区提交最短清单任务,等待原生更新,展开顶部清单 | “远程 Continue 的执行清单显示在对话顶部。” 不注入假事件,不展示主机地址 |
取得匹配产物后隔离 userData/sessionData/日志,由生产 Main 加载真实 Preload/Renderer。保存后重开核对,等待字体和布局稳定再截图,逐张审阅文字、裁切、状态与隐私。记录构建身份、实际尺寸、输入方式和结果;保留原图,裁切另存,采用图片以相对路径插入正文。
文档主图如声明 HTTP OCR,必须来自真实解析,不用原生文本预览冒充服务结果。后续拍摄前确认可用服务和 OCR 调用授权,真实文本模型的持续授权不自动扩大为收费 OCR 授权;使用最小虚构样例并记录请求数。附件选图复用正式导入取得的结果。远程清单图遵循已有 Host 身份、专用目录及最小模型请求规则,逐次统计 dispatch。本轮仍按用户要求不拍摄、不请求服务。
AI 评论不列为必拍主图。若要展示生成效果,先解决默认模型真实路径验证,不能以 fixture 评论冒充生成结果。
### 正文中的替换与核对标注
正文已在对应位置加入四项「待替换」及一项「待核对」,不只把待办留在此记录中:
| 标注 | 待处理内容 | 完成条件 |
| --- | --- | --- |
| R01 | 标题的预览状态、版本号、发布日期、下载和完整更新日志链接 | 正式版本可下载且链接核验后替换;未发布时保留预览说明 |
| R02 | 画布说明的仓库相对链接 | 外发平台使用对应发布版本的公开完整链接;仓库内阅读可保留相对链接 |
| C01 | 画布分析默认页数及 1~8 页配置 | 按最终发布提交核对,行为变化才替换文字;不以旧基线否定并行更新 |
| R03 | 备份说明的仓库相对链接 | 外发时换为可定位备份章节的公开链接,数据库和笔记目录的备份提示保留 |
| R04 | 远程 Continue 的桌面/Agent/Runtime 版本及获取方式 | 核对正式配套版本、可获取包和安装说明,不用开发测试包替代 |
未来应用市场的规划说明不是等待改成“已上线”的占位,应按真实交付状态保留。普通演示内容、服务地址和密钥不作为正文待填字段,不要求填入组织真实资料。
图片编号按正文出现顺序统一为 01~06,其中 01、03 必补,02、05、06 建议,04 可选。图 01 可同时说明记录索引与连续浏览,不为同一界面再补一张重复图;会话置顶、通用按钮调整和六项问题修复采用文字说明,不强制配图。
发布前逐项处理所有标注:必补图片拍摄后替换,建议/可选图决定不用时删除对应标注;确认图注与实图一致,删除编辑标注说明及已处理的提示。R01 未满足时不将草稿改成正式发布稿。
## 验证与发布前检查
### 已有记录,不是本轮重跑
- 画布、持久化、缩放和布局有定向测试及 Electron 记录,部分使用替代 IPC 或模型输出。
- 文档处理含完整 App、真实服务及部分生产 IPC 场景,其全量通过结论仅对应当时快照。
- 远程 Continue 有开发联合包安装、实际输入框、清单保存、重启、取消后续发记录,不等于正式包可下载。
- 应用导航部分是组件与真实设置存储组合,部分截图尝试失败,不能概称全部 UI 通过。
- 最新 `375b215` 记录为 7 项定向测试、typecheck/lint 通过;全量测试超时前报告 App 完成提示和 WorkspacePrimitives forced-color 断言失败。不能用早期全量通过覆盖当前结论。
### 本轮工作
- 初稿已核查 Git 区间、对应代码、现行说明与验证边界;本次合并未增加功能声明,保留原事实来源与待办。
- 原两稿中文扫描均无阻断项,原 5 个 Markdown 文件的 48 个本地链接及锚点通过。该结果是合并前记录,不代替合并后检查。
- 合并后运行 `deai_scan.py --fail-on-block`:阻断项 0,复核项 3;人工复核保留未发布、PDF 文字层和清单只读/终态说明,均为必要事实边界。
- 合并后 3 个 Markdown 文件、40 个本地链接及锚点检查通过,尾随空格和 UTF-8 替换字符检查通过;`git diff --check` 通过,仅有换行转换提示。文档中无旧主题路径引用,最终改动仅含合并稿、核查记录和索引。
- 仅 Markdown 改动,未运行产品测试、typecheck、lint、构建或 Electron;模型、OCR、知识库调用均为 0,远端 Host 操作为 0。
- 未复制用户配置或启动演示应用,无本轮 profile、凭据副本或监听端口需要清理。
### deai 与功能重点调整(前一轮)
- 用户指出新增功能篇幅不足,本轮将 HTTP PaddleOCR-VL 从附件小节中的一段改为首要功能,补齐无需本地权重、共享配置与独立场景、PDF/PPTX/图片处理、图文预览、过滤及跨页整理、文件测试。远程 Continue 也改为明确的功能介绍,界面调整压缩到末尾。
- 重新核对生产实现、HTTP 设置组件、解析设置组件和远程验证记录。高级选项区分“有配置入口”和“已验证效果”,连接检查不写成解析成功。
- 按仓库 deai-writing 指引逐段润色,将“原生图片输入路径”等实现措辞改为具体操作,删去泛泛的体验描述与重复引导。复扫首次命中一句“不只是一段纯文本”的对照模板,已删去该句,直接介绍图文结果。
- 本轮仅修改宣传目录中的正文、记录及索引。润色期间工作区出现 Agent、画布、文档解析等其他未提交源码和功能文档变更,均保留,不纳入本文固定提交区间,也不修改或宣称已验证。
- 最终 `deai_scan.py --fail-on-block` 复扫:阻断项 0,复核项 2;人工复核保留未发布状态与执行清单只读/终态说明。3 个 Markdown 文件的 42 个本地链接及锚点、标题一致性、尾随空格和 UTF-8 替换字符检查通过,宣传目录 `git diff --check` 通过。
- 截图仍待补,未新增构建、模型或 OCR 请求;产品测试、typecheck 和 lint 未运行,本轮只改宣传文档。
### 用户视角重排与应用方向
- 前一轮按技术名称置顶 HTTP OCR 的结构已被本次双重点结构替代;选题主次以本文“选题与结构”为准。标题明确保留“画布笔记”,不再用 PDF 批注概括其全部能力。
- 核查产品定位、应用管理的 FR-15 及现行本机推理功能。应用市场私有化来自已有规划和用户明确指引,仅宣传为后续方向;正文保留当前四应用、实际服务操作与未来市场的区分。
- 已重新读取外部修改后的远程验证文档。其新增会话 MCP 回归属于其他未提交工作,不扩入本文固定提交范围,也不把替代图片接收端验证说成真实图片生成。
- 原文事实、升级边界及服务费用继续保留;截图计划改为画布混排、文档选图等用户操作结果优先,市场原型不作为已交付截图。
- 本次最终 deai 复扫为 0 个阻断项、3 个复核项;人工复核后保留开发版状态、市场未上线和清单只读/终态限定。3 个 Markdown 文件的 45 个本地链接及锚点、标题一致性、尾随空格和 UTF-8 替换字符检查通过,宣传目录 `git diff --check` 通过,仅有换行提示。
- 本轮仅修改文章、内部记录及索引,其他工作区变更保持不动;未运行产品测试、typecheck、lint 或构建,模型与 OCR 请求均为 0,未拍摄或对外发布。
### 固定三段与问题修复
- 用户确认顺序固定为新增功能、功能改进、问题修复,组内再按用户价值排序。已同步正文和两类模板,修复在文末;会话置顶归入新增功能,连续浏览与操作布局归入功能改进。
- 末尾列出六类具体问题:500 条历史截断、100 个会话范围、OpenCode 取消后续发和停止状态、浮层遮挡、新窗口链接、图谱额外输出预算。新增条目核对已提交差异及历史连续请求证据,不把历史测试说成本轮执行。
- 编辑期间正文的画布分析页数说明及本记录中的相应证据被并行更新,本轮保留。该项已在来源表单列为当前工作树变化,不归入 `v0.13.6..375b215` 的已提交事实;三段整理没有独立重跑其产品验证,发布前应更新目标提交。
- 文案复扫 0 个阻断项、3 个复核项,保留预览状态、市场规划和清单只读边界。6 份文档的 59 个本地链接及锚点、正文及两模板的固定三段顺序检查通过;宣传目录差异和空白检查通过。
- 本次只调整宣传文档,未运行产品测试、typecheck、lint 或构建,未拍摄或调用模型/OCR。
### 发布前仍需
- [ ] 确认最终桌面 tag、提交及可下载产物,更新目录、索引和预览状态,核验下载与完整更新日志链接。
- [ ] 确认远程 Continue 所需正式 Agent/Runtime 包及版本组合,分别记录桌面和 Agent 发布状态。
- [ ] 在最终版本补画布混排与文档选图主图,按需补 PDF 批注、应用管理和远程清单图,复核操作与界面一致;不以市场原型冒充现有功能。
- [ ] 获取最终候选验证结论,保留失败与未覆盖项,不宣称“全量通过”。
- [ ] 保留或扩大 AI 效果宣传前完成真实默认模型路径验证,不增加未经验证的效果承诺或结果截图。
- [ ] 保留备份、手动保存、导出文字层、模型发送及旧附件不补全说明。
- [ ] 仅在用户明确授权后发布正文及采用图片,不附此内部记录。
+292 -26
View File
@@ -2,6 +2,8 @@
本文件用于 GoodBuddy 项目的产品宣传文章。这里的 PR 指产品传播,不指 GitHub Pull Request。
它是项目工作约定,不属于随应用分发的 Skill,不要求修改产品代码。
本文件集中维护流程、正文模板、截图步骤和占位标注,不另设分散的流程文件。
各版本目录只保存具体文章、审校记录和实际素材。
## 触发与范围
@@ -9,11 +11,19 @@
默认交付文章和素材,不自动提交 Git、打版本 tag、发布版本或向外部平台发文。
版本发布操作遵循 [发布手册](../development/release-runbook.md)。本流程是可选配套,不阻塞软件发布。
配套文档:
本页导航:
- [重点 PR 模板](./featured-template.md):介绍一项值得专门展开的能力。
- [常规 PR 模板](./regular-template.md):介绍小功能、体验改善和维护修复。
- [截图步骤](./screenshot-guide.md):隔离环境准备、真实操作与素材取证。
- [核查与选题](#核查与选题):完整盘点、用户视角排序、讨论确认。
- [重点稿模板](#重点稿模板)、[常规与综合稿模板](#常规与综合稿模板):确认选题后起草。
- [截图执行步骤](#截图执行步骤):隔离环境准备、真实操作与素材取证。
- [草稿就地标注](#草稿就地标注):待补图、待替换和待核对。
- [交付与发布核对](#交付与发布核对):归档、链接检查和标注清理。
默认顺序是:**完整盘点新增与改动 → 从用户视角排序 → 与用户讨论并确认选题和结构 →
起草及截图 → deai 审校 → 交付**。不要跳过盘点直接写文章,也不要用已经写好的初稿代替选题讨论。
用户已明确确认的范围和结构不重复询问;用户明确要求跳过讨论直接起草时,仍先完成盘点与排序。
成稿按 **新增功能 → 功能改进 → 问题修复** 的固定顺序分段,问题修复放在最后。
用户视角排序用于各段内部的主次与篇幅,不改变这三段顺序。
先读取仓库指引、Git 状态、桌面版本 tag 和提交历史。默认比较当前分支最近的正式桌面
tag 与当前 HEAD;明确记录基线 tag、目标提交和检查日期。Agent tag 单独核对,不混作桌面基线。
@@ -24,26 +34,88 @@ tag 与当前 HEAD;明确记录基线 tag、目标提交和检查日期。Agen
## 核查与选题
提交信息和 `Release note:` 是线索,实际 diff、最终代码和验证记录是事实依据。
每项候选内容记录:
### 1. 先列全新增与改动
- 目标用户和具体任务。
- 原有行为、本轮变化及使用入口。
- 前提、限制、持久化范围、数据流向、费用和升级兼容性中实际相关的内容。
- 对应提交、代码或文档位置,以及已有验证的范围。
提交信息和 `Release note:` 是线索,实际 diff、最终代码和验证记录是事实依据。
先检查整个比较区间,再按产品功能归并,列出所有用户可感知的新增、能力扩展、行为调整、
兼容性变化和修复。不能先挑几个准备宣传的点,再只为这些点找证据。
同一功能的多次实现和修复合成一项;纯技术维护可以归组注明,不要求逐条翻译提交。
未提交改动、未完成实现和规划单列,不能混入本轮已实现功能。
盘点表使用以下信息,简短描述也必须保留事实来源:
| 功能 | 变化类型与状态 | 原来怎样/本轮变化 | 目标用户、任务与使用入口 | 使用条件与边界 | 来源与验证 |
| --- | --- | --- | --- | --- | --- |
| 按完整产品能力命名 | 新增/扩展/调整/修复;实现、验证、发布状态分别记录 | 说明真实差异,不把旧能力包装成新增 | 用户能完成什么,在哪里操作 | 相关部署、费用、数据、保存和升级要求 | 提交、代码或文档及实际验证范围 |
盘点完成后,将准备入文的内容明确归入三类:
- **新增功能**:用户以前没有的能力,包括现有模块中的新用途;例如首次提供画布记录或会话置顶。
- **功能改进**:已有功能的操作、布局、反馈或效率改善,不改变其原有用途。
- **问题修复**:在具体条件下出现错误、中断、数据遗漏或不一致,改后恢复预期行为。
按用户实际感知分类,不直接照抄提交的 `feat`/`fix` 标签。同一提交可能包含不同类别。
一项内容只作一次主介绍,不在三段重复列出;新功能中的正常使用说明不必拆成独立改进或修复。
规划另标状态,不能列为已提供的新功能。
保留能力的完整范围,不用一个子功能代替整项能力。例如,画布笔记包括分页书写、图文混排、
保存与导出,PDF 批注只是其中一部分;HTTP OCR 接入则要放在文档识别、预览和后续使用中理解。
这些例子用于防止遗漏,不固定后续每轮的选题或排序。
将已知验证记录与本轮实际运行结果分开。定向测试通过不能写成全量通过,组件 fixture
不能写成完整应用端到端通过。发现失败如实记录,不为写文章擅自修复源码。
先选择重点 PR 或常规 PR,不按版本号大小、提交数量或凑足篇幅决定类型。
重点 PR 围绕一项能力或同一使用场景展开;常规 PR 按重要性介绍本轮变化,可以只有几段。
给出类型、推荐标题和推荐理由。维护修复可以只进入更新日志;变化不足以支撑文章时,明确建议暂不单独发文。
已有能力可以作为场景背景,但不能包装成本轮新增。
### 2. 从用户视角确定主次
基于完整盘点完成分类,在三段各自内部给出推荐顺序,并解释每项为什么值得这个篇幅。判断时考虑:
- 用户因此新增了什么做法,或哪个原本受阻的任务现在可以完成。
- 对实际工作结果的影响,是新增工作方式、补齐流程,还是减少一次操作。
- 适用人群和使用前提,包括特定角色、远程主机、自建服务等;没有数据时不编造使用频率、
用户占比或效率收益。
- 是否有明确的产品方向意义。应用管理通向未来应用市场、市场支持私有化部署等已确认方向,
可以解释,但必须把当前能力和后续规划分开,不能当作已经上线的功能。
- 实现与验证是否足以支撑准备写出的结论;证据不足的内容应缩小表述或列为待确认。
据此区分各段的重点与简述项。修复按用户影响排序,数据、任务和结果问题需具体说明,
不能因为放在最后就遗漏或用“提升稳定性”概括。不设固定数量或机械评分,
也不以代码量、技术新颖程度、提交数量、用户最近提及的词决定顺序。用户指出一个遗漏或举一个例子,
应重新检查完整清单和整体主次,不自动把该项提升为第一条。
按用户任务组织相关能力,先讲动作与结果,再解释技术与设置。例如,文档预览、选图、保存与 OCR
可以构成同一资料处理场景;不能因此暗示尚未实现的自动联动。主要能力应完整展开,不能把篇幅
都用在按钮、布局和限制说明上。部署、费用、数据和升级边界仍需保留。
### 3. 先讨论选题,再写初稿
起草前,先向用户展示:
1. 完整的新增与改动清单,包括暂不推荐入文的内容。
2. 按三类分组、各组按用户视角排序的重点、推荐理由,以及待确认事实。
3. 推荐标题和提纲,各节准备说明的用户任务、结果及必要图片。
4. 拟合并介绍、简述、仅进更新日志或不写入的项目及原因。
得到用户确认后再起草;有调整时更新整体结构,不只机械换标题或移动一段文字。
这一阶段讨论的是选题、篇幅和结构,不提前交付一篇已经取舍完毕的文章。
选题确认不等于授权构建、收费调用、打 tag 或外部发布。
根据确认后的内容选择重点 PR、常规 PR 或综合更新稿,不按版本号或凑篇幅决定。
重点 PR 围绕一项能力或同一使用场景展开;常规 PR 可只有几段;综合稿可以有多个独立重点,
但仍按新增功能、功能改进、问题修复分段,主次清楚,不平均分配篇幅。只有某一类内容时不虚构
其他类别,空段可省略;重点专题只列相关变化,保留同样的相对顺序。纯维护版本可以只写修复日志,
但已经入选综合稿的用户可感知修复必须在末尾列出,不能藏入“其他改进”或只给一条日志链接。
变化不足时明确建议暂不单独发文。
在本轮 `review.md` 保存完整盘点、推荐排序及理由、用户确认的结构和取舍。讨论阶段可以只建立
该记录,不创建空 `article.md`、空素材目录或无正文的文章索引项;记录为“选题讨论”,
确认起草后再按下文交付。已有能力可作为背景,但不能包装成本轮新增。
## 自动截图与演示
截图是工作流的实际执行步骤,不能默认把任务留给用户。
按[截图步骤](./screenshot-guide.md)准备隔离环境,并遵循其中链接的项目自动化规范。
按已确认的用户任务和文章主次安排截图,不因某个技术配置页容易截图就将它作为宣传重点。
主图优先展示用户实际完成的内容或结果,配置页用作必要的接入说明;未来市场等规划不用原型
冒充已交付功能。截图是工作流的实际执行步骤,不能默认把任务留给用户。
按下方[截图执行步骤](#截图执行步骤)准备隔离环境,遵循项目自动化规范。
先检查现有应用启动、Electron 自动化和截图工具,复用已验证的机制。
根据选题编排一个短的真实操作过程,记录每张图片要证明的行为,再执行和截图。
@@ -67,11 +139,75 @@ tag 与当前 HEAD;明确记录基线 tag、目标提交和检查日期。Agen
- 调用收费模型、访问外部系统或执行写操作时,遵循当前会话已有授权及工具要求。
自动化不可用、版本不匹配或正常路径无法完成时,记录具体阻碍,继续完成独立的核查和写作。
缺少的图片写入内部待补清单,不能声称截图已完成,也不能用原型替代后隐去说明。
缺少的图片须在正文对应位置标注,并与内部待补清单对应,不能只把要求放在 `review.md`。
不能声称截图已完成,也不能用原型替代后隐去说明。
### 截图执行步骤
隔离启动和自动化实现遵循[Electron UI 自动化规范](../quality/electron-ui-automation.md#3-当前源码与隔离启动)。
目前仓库没有通用的一键完整 App 截图命令,下列步骤需要适配临时驱动,不是已经实现的 runner。
#### 1. 确认版本和素材
从仓库根目录检查 `git rev-parse HEAD`、`git status --short`、`node --version` 和
`node -p "require('electron/package.json').version"`。依赖缺失时按[开发与构建](../../BUILD.md)准备,
不重复安装已满足的依赖。在本轮 `review.md` 记录目标提交、实际构建来源、平台、语言、主题、
缩放和截图清单,优先采用 1280×800 内容区,并记录实际尺寸。
开始拍摄前应已确认选题。每张图说明操作与结果,重点稿优先连续演示,常规稿只拍有助理解的变化。
缺图按[草稿就地标注](#草稿就地标注)放在正文拟插图位置,编号、优先级及计划文件名与内部清单一致。
#### 2. 准备隔离环境
使用本轮专用临时目录保存 profile、演示工作区、驱动和原始截图,不复制整套私人会话。
只用公开或明确虚构的资料;凭据沿用已授权的安全配置方式,不写入脚本、文档或图片。
`npm start` 只预览已有产物,不自动重建或隔离数据;`npm run dev` 也不能代替隔离启动器。
`GOODBUDDY_WORKSPACE` 只指定工作区,不隔离用户数据库。不存在可直接假定有效的
`GOODBUDDY_TEST_MODE` 或 `GOODBUDDY_USER_DATA` 开关。
使用可确认属于目标版本的产物。开发场景的构建方法见自动化规范,发布准备遵循
[发布手册](../development/release-runbook.md)。宣传材料不自动授权本地生产构建、打包或
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 尽早介绍能力和使用条件,围绕真实演示展开;常规 PR 直接说明变化,
有必要才解释原来的不便。没有具体背景材料时不虚设场景,不为小改动反复解释价值。
模板中的编辑提示不能变成固定话术。不要求每篇都出现“比如你正在……”“这意味着……”或
@@ -83,7 +219,129 @@ tag 与当前 HEAD;明确记录基线 tag、目标提交和检查日期。Agen
机制范围的承诺。持久保存、当前运行期间保留、跨项目可见和跨设备同步必须准确区分。
可用时使用 `deai-writing` 技能审校正文;无该技能时人工检查空泛形容词、模板化转折、
机械排比和重复总结。审校不能删除必要的能力边界和升级提示。
机械排比和重复总结。扫描器通过不代替逐段审读,还要检查篇幅是否反映已确认的功能主次、
是否堆砌实现术语、是否把未来方向写成现有能力。审校不能删除必要的能力边界和升级提示。
先交初稿供用户讨论,按反馈修改;若反馈改变文章主次,回到完整清单重新说明排序与取舍,
不跟随最近一个关键词反复改方向。保留事实依据和截图缺口,不把编辑反馈当作产品验证。
### 草稿就地标注
初稿交付时,直接在需要补图、替换文字或核对事实的位置加入醒目的引用块,不把待办全部留到
文末或内部记录。使用下列三类标注,并在稿件开头说明它们是发布前应处理、删除的编辑提示:
| 标注 | 用途 | 必须说明 |
| --- | --- | --- |
| `【待补图 01|必补/建议/可选|主题】` | 标记实际图片插入位置 | 用户操作、画面须证明的结果、计划相对文件名、建议图注和必要的隐私/真实性要求 |
| `【待替换 R01|主题】` | 标记未确定的版本、日期、链接、包版本或暂用文字 | 要替换的具体句子/字段、填写格式及确认依据;信息未知时不编造 |
| `【待核对 C01|主题】` | 标记须与最终发布版本比对的行为或条件 | 核对对象和处理方式;只有行为变化时才改正文,不把已核实说明全部变成占位 |
补图按正文出现顺序编号,替换项用 `R01` 起编号,核对项用 `C01` 起编号。`review.md` 保存同号
清单和处理状态,计划文件名与正文一致。编号便于讨论,不规定每篇图片或标注数量。
必补图用于支撑已确认的核心演示;建议图帮助解释,可在编辑时决定不采用;可选图仅作补充,
不用时删除标注,不为凑数拍摄。未取得素材时,文件名只写为代码文本,如
`assets/01-canvas-note.png`,不要插入不存在的 Markdown 图片链接,也不要创建空 `assets/`。
取得并审阅图片后,在原位置换成相对路径图片和符合实际结果的图注。
待替换项应覆盖实际缺口,例如预览标题与正式版本信息、下载和完整更新日志链接、外发平台需要的
公开文档链接、桌面与 Agent/Runtime 配套版本。仓库内阅读有效的相对链接不必一律替换;
外发时才改为可访问的完整链接。参考句式里的 `{版本}`、`{链接}` 等字段都须核验后填写,
不能把开发包当正式包,或提前把预览改成已发布。
未来功能规划不是等待替换成“已上线”的占位。服务地址、密钥和私人资料不作为正文待填字段。
占位标注不代替实际截图与核查,也不扩大构建、收费服务调用或外部发布授权。
### 重点稿模板
用于一项值得展开的能力或同一工作场景。先完成选题确认,在 `review.md` 记录目标用户、任务、
变化、证据、条件和取舍,再使用模板。保持完整能力范围,不用一个易演示的子功能代替整项能力。
只保留与主题有关的类别,顺序仍为新增功能、功能改进、问题修复,无内容的类别可省略。
下面方括号和引用块均为编辑示例,按实际缺口填写,不规定字数或功能数量。取得图片后用真实图片
和图注替换原标注;发布前按交付核对清除编辑提示。不要编造用户经历、设计动机或演示结果。
```markdown
# [具体功能或用途,版本号可放副标题]
> **编辑标注说明(发布前删除):** 待补图标记素材位置,待替换标记未确定信息,待核对标记最终版本检查项;标注中的素材尚未取得。
[直接介绍能力、适用用户和使用条件。]
[版本、体验入口、使用文档及必要升级说明;未发布则明确预览状态。]
> **【待替换 R01|版本与链接】** [指出待替换句子、所缺字段及核验条件。]
## 新增功能
### [一个实际任务]
[用公开或明确虚构的演示资料,说明要完成的任务。]
> **【待补图 01|必补|用户任务结果】** [操作、画面应证明的结果与隐私要求。] 计划文件:`assets/01-result.png`。
>
> 建议图注:[实际操作或结果。]
[结合结果介绍完整能力,补充图中无法说明的内容。]
### [值得单独解释的能力或设计选择,可省略]
[据事实展开,保留相关前提、费用、数据流向和限制。]
> **【待核对 C01|最终行为】** [仅有实际缺口时保留,说明核对对象和变化后的处理。]
## 功能改进
[主题内已有功能的操作或结果如何改善;无内容可省略。]
## 问题修复
- [相关问题、出现条件与修复后的行为;无内容可省略,不强塞无关修复。]
```
审校重点:已确认能力是否完整,标题是否准确,演示能否支撑结论,是否重复解释价值或混入无关更新。
三类必须分开,修复在最后;配图按本页截图步骤执行。
### 常规与综合稿模板
用于不同功能的更新、体验改善和修复,也可承载经确认的多个主要新增能力。主次决定篇幅,
不强行拼成一个故事或平均分段。先确认完整盘点及组内排序,在 `review.md` 保留来源和取舍。
纯维护更新可只保留问题修复,其他空段可省略,不虚构内容凑齐三段。
```markdown
# GoodBuddy 更新:[最值得关注的变化]
> **编辑标注说明(发布前删除):** 待补图标记素材位置,待替换标记未确定信息,待核对标记最终版本检查项;标注中的素材尚未取得。
[一两句话概括变化;信息重复时省略。]
[版本、下载入口、升级说明和完整更新日志;未发布则明确预览状态。]
> **【待替换 R01|版本与链接】** [指出待替换句子、所缺字段及核验条件。]
## 新增功能
### [新能力或用户用途]
[现在能怎样操作、得到什么;必要时简述原来的不便。]
> **【待补图 01|建议|变化展示】** [操作、结果与隐私要求;按选题改为必补或可选,无需配图则删除。] 计划文件:`assets/01-change.png`。
>
> 建议图注:[实际操作或结果。]
> **【待核对 C01|最终行为】** [仅有实际缺口时保留,说明核对对象和变化后的处理。]
## 功能改进
[逐项说明已有功能如何更好用,各项按用户影响排序。]
## 问题修复
- [什么情况下出现什么问题;现在恢复怎样的行为。]
- [下一项修复,保留实际影响与必要边界,不重复新增或改进项。]
```
审校重点:主次与确认后的提纲一致,无空泛开场、虚设场景和总结口号;旧能力不包装成新增,
规划与本轮能力分开。入选修复在最后具体列出,不藏在“其他改进”或用“提升稳定性”代替。
明显界面变化可配图,其余直接说明;不用的建议/可选图删除标注,不保留缺图链接。
## 交付与发布核对
@@ -98,25 +356,33 @@ Agent 专题使用对应的 `agent-v…` tag。
不能自行推测下一版本号。同一版本同一天有多篇文章时,在该目录内按主题建立子目录。
目录只包含本轮文章与必要素材,不改产品代码。
最小交付:
初稿起草后的最小交付:
- `article.md`:文章标题、正文、相对路径配图和图注。
- `assets/`:实际取得的图片;如有处理,保留可区分的原图。
- `review.md`:草稿/待发布/已发布状态、目标 tag 与提交、比较区间、选题理由、事实来源、
截图环境与步骤、验证范围和待补事项;外部发布后补充发布日期与链接。
- `review.md`:草稿/待发布/已发布状态、目标 tag 与提交、比较区间、完整功能盘点、
用户视角排序及理由、已确认的选题结构与取舍、事实来源、截图环境与步骤、验证范围和待补事项;
外部发布后补充发布日期与链接。
没有图片时不建空目录。文章草稿中的素材占位必须醒目标注;发布用正文不得留下占位文字。
内部验证细节和编辑备注放在 `review.md`,不混入面向用户的宣传正文。
新增文章目录时,在本页末尾的文章索引登记日期、目标 tag、标题、状态及正文链接;
没有图片时不建空目录。草稿按[就地标注规则](#草稿就地标注)显示缺口;发布用正文不得留下占位文字。
内部验证细节放在 `review.md`。草稿中允许上述就地编辑标注,正式对外正文必须清除,不附内部记录。
初稿生成后,在本页末尾的文章索引登记日期、目标 tag、标题、状态及正文链接;
正式发布后同步更新状态和外部链接。对外传播正文与所需图片,不附内部核查记录。
交付前检查图片可读、相对路径存在、文章与图片一致、标题没有超出功能事实。
发布前再次确认对应版本可下载、下载链接有效、升级说明准确,且最终版本没有改变演示行为。
尚未发布时保持草稿状态,不编造版本号或上线时间。
发布前逐项核对正文和 `review.md` 中的标注:必补图须取得、审阅并插入,若要取消则先确认调整
演示方案;建议/可选图决定不用时删除其标注。填写并核验待替换字段,完成待核对项,随后删除
已处理的引用块及稿件开头的编辑标注说明。搜索“待补图”“待替换”“待核对”和模板字段,
确认发布稿无残留提示、缺图链接或未填写值。仍有必要信息未确定时保持草稿,不能仅删除标注当作完成。
最终回复提供文章和素材位置,概括推荐主题、实际截图情况及剩余阻碍。
只有得到明确发布指令后,才通过可用平台能力执行外部发布;准备文章不等于授权发布。
## 文章索引
尚无归档文章。创建首篇草稿后,以日期、版本 tag、标题、状态、正文链接和发布链接建立索引表。
| 日期 | 目标 tag | 标题 | 状态 | 正文 | 发布链接 |
| --- | --- | --- | --- | --- | --- |
| 2026-09-19 | 未确定(unreleased) | GoodBuddy 更新预览:画布笔记、文档处理与应用管理 | 草稿,截图待补 | [综合更新稿](./2026-09-19-unreleased/article.md) | 未发布 |
-35
View File
@@ -1,35 +0,0 @@
# 重点 PR 模板
适用于新增一项值得专门介绍的能力,或明显改变某种工作方式的更新,例如外部知识库接入。
围绕一个主题,用真实任务和结果说明能力。没有必要不铺背景,不编造用户经历或设计动机。
写作前在本轮 `review.md` 记录目标读者、实际任务、本轮变化、主要证据、使用条件和文章取舍。
方括号是编辑提示,发布前删除或替换。各节按内容增删,不规定字数和功能数量。
```markdown
# [具体功能或用途,版本号可放副标题]
[直接介绍本次新增的能力、适用的人和使用条件。]
## [一个实际任务]
[使用公开或明确标识的演示资料,说明准备完成什么任务。]
![说明图片内容的替代文本](assets/实际图片文件名.png)
[图注说明实际操作或结果。]
[结合操作结果介绍功能。截图能看懂的内容不重复说明,正文补充必要解释。]
## [值得单独解释的能力或设计选择,可省略]
[根据功能展开。设计原因须有依据,不虚构用户反馈或研发故事。]
[影响使用的前提、费用、数据流向或限制,按实际需要说明。]
[可用版本、体验入口、使用文档。]
[必要的升级说明。]
```
审校时检查:标题是否超出实际能力;演示是否支撑主要结论;是否混入无关的小更新;
是否重复描述同一价值。配图按[截图步骤](./screenshot-guide.md)取得,完整流程见[工作流](./README.md)。
-33
View File
@@ -1,33 +0,0 @@
# 常规 PR 模板
适用于小功能、体验改善和维护修复,例如会话置顶、完成提示和浏览器交互改善。
开头概括本轮更新,再按重要性说明变化。可以介绍不同功能,不要求拼成一个故事。
只有两三个小变化时,可以去掉小标题,用几段文字写完;纯维护更新也可只保留更新日志。
写作前在本轮 `review.md` 记录比较区间、入选变化、事实来源和使用限制。
方括号是编辑提示,发布前删除或替换。不规定字数,各项篇幅不要求一致。
```markdown
# GoodBuddy 更新:[本轮最值得关注的一两项变化]
[一两句话说明本轮更新了什么,直接进入内容;信息重复时省略。]
## [变化名称]
[说明现在能怎样操作。必要时用一句话交代原来的不便,不重复解释价值。]
[有助于理解时配实际截图和简短图注。]
## [变化名称]
[同上,按重要性排序。]
[其他小改动可合并成简短列表,不必每项单独成节。]
[可用版本与下载入口。]
[必要的升级说明,完整更新日志链接。]
```
审校时删掉空泛开场、虚设场景和总结口号。不为小修复强行写产品意义,不把旧能力写成新增。
明显的界面变化可以配图,其余直接说明。配图按[截图步骤](./screenshot-guide.md)取得,
完整流程见[工作流](./README.md)。
-58
View File
@@ -1,58 +0,0 @@
# PR 文章截图步骤
本页规定宣传素材的准备顺序。隔离启动和自动化实现以
[Electron UI 自动化规范](../quality/electron-ui-automation.md#3-当前源码与隔离启动)为准,
不重复维护另一套测试机制。目前仓库没有通用的一键完整 App 截图命令;执行者需要复用或
按规范准备临时驱动,不能将下面的流程描述当作已经实现的自动化脚本。
## 1. 确认版本和素材
从仓库根目录检查 `git rev-parse HEAD`、`git status --short`、`node --version` 和
`node -p "require('electron/package.json').version"`。依赖缺失时按
[开发与构建](../../BUILD.md)准备,不重复安装已满足的依赖。
在本轮 `review.md` 中记录目标提交、实际构建来源、平台、语言、主题、缩放和截图清单。
优先采用 1280×800 内容区、统一主题与中文界面,按演示需要调整,并记录实际尺寸。
每张图先写清要说明的动作和结果。重点 PR 优先连续演示,常规 PR 只拍需要解释的界面变化。
## 2. 准备隔离环境
使用本轮专用临时目录,包含 profile、演示工作区、驱动和原始截图。不要复制整套私人会话。
仅使用公开或明确虚构的演示资料,凭据沿用已授权的安全配置方式,不写入文档、脚本或图片。
使用可确认属于目标版本的产物。`npm start` 只预览已有产物,不自动重建,也不自动隔离数据;
`npm run dev` 同样不能代替隔离启动器。`GOODBUDDY_WORKSPACE` 只指定工作区,不隔离用户数据库。
不存在可直接假定有效的 `GOODBUDDY_TEST_MODE` 或 `GOODBUDDY_USER_DATA` 开关。
开发场景的构建方法见自动化规范;发布准备遵循[发布手册](../development/release-runbook.md),
宣传材料不自动授权本地生产构建、打包或 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;不得按进程名批量结束用户应用。
发布前核对最终版本行为是否仍与截图一致;有变化则重拍受影响部分。