Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

docs: add CDP screenshot privacy guide and browser snippet

fmfsaisaie5909a67b83d
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 49966b3918..97dac0f84d 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -35,7 +35,9 @@ type:feat / fix / refactor / perf / chore / docs / test / revert / build / ci
`--compare` 出改前/改后对照),再运行 `pnpm ui:check:publish`,它把截图发到作者 fork 的
`pr-assets/<分支>`,输出带图片链接的本段内容,原样贴到这里。涉及登录、发送、跨设备等单页验证
覆盖不到的变化,仍附完整 Cindy 截图;设计系统 PR 的证据要求见
-docs/design-rules/design-governance.md §6。 -->
+docs/design-rules/design-governance.md §6。
+公开截图只展示证明改动所需的界面,不公开能认出真实的人、电脑、账号的信息或别人的私密内容,
+数值和界面状态照常展示;操作见 docs/dev-rules/desktop-development.md「公开截图与 CDP 操作指南」。 -->
- 引用的设计规范:
diff --git a/apps/desktop/scripts/cdp-screenshot-mask.js b/apps/desktop/scripts/cdp-screenshot-mask.js
new file mode 100644
index 0000000000..a31d9c3304
--- /dev/null
+++ b/apps/desktop/scripts/cdp-screenshot-mask.js
@@ -0,0 +1,43 @@
+/* global document, NodeFilter, MutationObserver */
+// 通过 CDP 执行本文件,再保存 restore = __cindyScreenshotMask({ 原文: '示例' })。
+// 截完(或失败)调用 restore();输入值/编辑区不改,远程 img 模糊。
+// 不覆盖 canvas、嵌入内容、窗口标题栏和系统弹窗;发出前人工检查。
+globalThis.__cindyScreenshotMask = (pairs) => {
+ const entries = Object.entries(pairs).filter(([key]) => key).sort((a, b) => b[0].length - a[0].length);
+ const escaped = entries.map(([key]) => key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+ const pattern = escaped.length ? new RegExp(escaped.join('|'), 'gu') : /(?!)/g;
+ const replacements = new Map(entries), saved = new Map();
+ const attrs = ['title', 'aria-label', 'alt', 'placeholder'];
+ const skip = 'script,style,[contenteditable],input:focus,textarea:focus';
+ const read = (node, key) => key === '#text' ? node.nodeValue : node.getAttribute(key);
+ const write = (node, key, value) => key === '#text' ? node.nodeValue = value : node.setAttribute(key, value);
+ const replace = (node, key) => {
+ const before = read(node, key);
+ if (before === null || saved.get(node)?.get(key)?.[1] === before) return;
+ const after = before.replace(pattern, (match) => replacements.get(match));
+ if (after === before) return;
+ if (!saved.has(node)) saved.set(node, new Map());
+ saved.get(node).set(key, [before, after]);
+ write(node, key, after);
+ };
+ const blur = document.createElement('style');
+ blur.textContent = 'img[src^="https://"],img[src^="http://"] { filter: blur(12px) !important; }';
+ document.head.append(blur);
+ const scan = () => {
+ observer.disconnect(); // 不观察自己的改动,避免循环。
+ const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+ for (let node; (node = walker.nextNode()); )
+ if (!node.parentElement?.closest(skip + ',textarea')) replace(node, '#text');
+ for (const el of document.body.querySelectorAll('*'))
+ if (!el.closest(skip)) for (const key of attrs) replace(el, key);
+ observer.observe(document.body, { subtree: true, childList: true, characterData: true, attributes: true });
+ };
+ const observer = new MutationObserver(scan);
+ scan();
+ return () => {
+ observer.disconnect(); blur.remove();
+ for (const [node, fields] of saved) for (const [key, [before, after]] of fields)
+ if (read(node, key) === after) write(node, key, before);
+ saved.clear();
+ };
+};
diff --git a/docs/dev-rules/desktop-development.md b/docs/dev-rules/desktop-development.md
index 0cef248fc7..a0ea28561a 100644
--- a/docs/dev-rules/desktop-development.md
+++ b/docs/dev-rules/desktop-development.md
@@ -259,6 +259,50 @@ pnpm ui:check:selftest
改前/改后数值,原样写进 PR 正文。登录、发送、跨设备等单页验证覆盖不到的变化,仍按原方式附
完整 Cindy 截图。
+### 公开截图与 CDP 操作指南
+
+公开截图(PR 正文、评论、发到 fork 的图)的原则:能证明改动就够,不公开能认出真实的人、
+电脑、账号的信息,以及别人的私密内容;数值和界面状态照常展示。
+
+- 优先用 `ui:check` 或 `--mock`;`--mock` 只在没登录过账号的模拟沙箱里生效,登录过就换
+ 一个新的 `--isolated=<名字>`,见 [UI 模拟数据](ui-mock-data.md)。
+- 发到 fork 的图按提交 SHA 仍能公开访问,删分支撤不回。
+
+必须用真实账号截完整 Desktop 时,只连接开发版,按以下步骤操作:
+
+1. **确认实例和端口**:给自己启动的实例显式设置 `XDT_CDP_PORT`,例如
+ `XDT_CDP_PORT=19247 pnpm restart:desktop:remote --region=global -- --isolated=<名字>`。
+ 多开时每个 worktree 用不同端口和沙箱。用 `curl http://127.0.0.1:19247/json/list` 核对
+ 主窗口页面地址,Vite 端口必须与自己的启动日志一致;不一致或没有目标就停止,别猜。
+2. 用任意 CDP 客户端连接这个主窗口:Playwright `connectOverCDP`、agent-browser、
+ Chrome DevTools 或最小的 WebSocket 调用均可。仓内 `scripts/cdp-eval.mjs` 写死了 CDP
+ `9222` 和页面 `5173`,只适合确认过地址的单实例。
+3. 在该页面用 `Runtime.evaluate` 执行 [cdp-screenshot-mask.js](../../apps/desktop/scripts/cdp-screenshot-mask.js),
+ 再执行 `window.undoScreenshotMask = __cindyScreenshotMask({ "原文": "示例" })`(保存返回的还原函数)。
+ 昵称、邮箱、电脑名、分享者、分享链接、本机路径和私密内容按当前页面补齐;真实对照表
+ 不进提交、命令参数或日志。短昵称用完整显示文本作键,避免误改其他文字。
+4. 等悬停提示/页面刷新完成后,用 `Page.captureScreenshot`,参数 `{ "format": "png" }`;
+ 只需局部时加 `clip: { x, y, width, height, scale: 1 }`(页面 CSS 坐标)。将返回的
+ `data` 按 base64 解码,只保存到 Git 忽略的 `tmp/desktop-screenshots/` 等本地目录。
+5. 在 `finally` 中再次 `Runtime.evaluate` 执行 `window.undoScreenshotMask?.()`;异常断连
+ 就刷新该页面(先保护未保存的草稿)。发出前再看一眼,确认没有漏掉真实信息。
+
+片段只改 DOM 显示,按字面、区分大小写匹配,长词优先;页面变化监听会处理 React 重绘和
+后来出现的提示。**不改输入框的值、正在编辑的输入框和富文本编辑区**,有敏感值时先退出编辑或裁剪。
+默认模糊远程 `<img>`(包括头像,可按页面缩小 CSS 选择器);不覆盖 canvas、嵌入内容、
+窗口标题栏、系统弹窗,以及跨节点拆开的文字。这些地方要避开或裁剪;这不是自动隐私检查。
+截图期间不要编辑或保存,结束后立即还原;再次替换前先还原上一次。
+
+执行文件的客户端示例(先按步骤 1、2 选定自己的主窗口,随后调用替换函数):
+
+```bash
+node scripts/cdp-eval.mjs eval apps/desktop/scripts/cdp-screenshot-mask.js # 仅上述单实例
+agent-browser --cdp 19247 eval "$(cat apps/desktop/scripts/cdp-screenshot-mask.js)"
+```
+
+Playwright:`await page.evaluate(await fs.readFile("apps/desktop/scripts/cdp-screenshot-mask.js", "utf8"))`
+(`fs` 为 `node:fs/promises`,`page` 为核对后的主窗口)。
+
`ui:check` 通过只说明列出的场景在真实组件上渲染正确;报告里 `not covered` 列出的行为仍须按
对应流程验收,正式 PR 前的真实运行验收要求不变。