docs: doc-compact 压缩标识与导航强化

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: x0c

AGENTS.md

@@ -19,12 +19,11 @@ npm run build
 
 ## 文档导航
 
-> 以下文档在涉及对应领域的开发、评审或排查时先读取。
-
-- `~/.config/agentsync/docs/CHROME_EXTENSION_DEVELOPMENT_KNOWLEDGE_BASE.md`：Chrome 扩展本地开发 / 热更新装载 / MV3 约束 / 自动化测试 / 商店审核前必读；**禁止用脚本或调试协议碰日常 Chrome 配置**
-- `docs/REQUEST_RECORDING_KNOWLEDGE_BASE.md`：录制状态、事件配对、body 捕获、SW 生命周期、过滤机制、会话管理
-- `docs/REQUEST_EXPORT_KNOWLEDGE_BASE.md`：导出格式转换、Header 分组过滤、复制偏好、高级复制弹窗
-- `docs/PAGE_ANNOTATION_KNOWLEDGE_BASE.md`：页面标注模式、圈选拦截、元素线索包、双 world 源码定位、任务书生成、站点代码目录映射；改标注/任务书任何逻辑前必读
+- `~/.config/agentsync/docs/CHROME_EXTENSION_DEVELOPMENT_KNOWLEDGE_BASE.md`：Chrome 扩展本地开发 / 热更新 / MV3 / 自动化测试 / 商店审核前**必读**。不读会用脚本或调试协议碰日常 Chrome 配置。
+- `docs/REQUEST_RECORDING_KNOWLEDGE_BASE.md`：改、评审或排查录制状态、事件配对、body 捕获、SW 生命周期、过滤或会话管理前**必读**。
+- `docs/REQUEST_EXPORT_KNOWLEDGE_BASE.md`：改导出格式、Header 分组过滤、复制偏好或高级复制弹窗前**必读**。
+- `docs/PAGE_ANNOTATION_KNOWLEDGE_BASE.md`：改标注模式、圈选、线索包、双 world 定位、任务书或站点代码目录映射前**必读**。不读会破坏标注/任务书契约。
+- `docs/OPENDESIGN_RESEARCH.md`：规划新手引导、导出预设、会话标记等体验优化前先读；含已验证可借鉴模式。
 
 ## 领域地图（doc-init）
 

TASKBOARD.md

@@ -1,4 +1,6 @@
-# 协作看板
+# TASKBOARD — 多 Agent 并行协作看板
 
-| 任务 | 状态 | 影响范围 | 开始时间 | 负责人 |
-|------|------|----------|----------|--------|
+> 规则见 agentsync 全局 docs/AGENT_TASKBOARD_GUIDE.md。只编辑自己的条目；完成后删除。
+
+| 任务 | 状态 | 影响范围 | 开始 | 最近更新 | 备注 |
+|---|---|---|---|---|---|

docs/OPENDESIGN_RESEARCH.md

@@ -0,0 +1,136 @@
+# OpenDesign 调研报告
+
+> 调研日期：2026-08-19 · 方式：浅克隆主仓 `nexu-io/open-design`（末次提交 2026-08-18）通读 README / docs / 关键源码实现，非仅看宣传页。
+> 调研目的：为 Request Recorder 的用户体验优化寻找可借鉴的模式。本文是调研结论，不含实施承诺。
+
+## 1. OpenDesign 是什么
+
+- **定位**：开源的「AI 设计工作台」，Claude Design（Anthropic 闭源产品）的社区替代。本地优先（local-first）、BYOK（自带模型密钥）、Apache-2.0 协议。
+- **形态**：macOS / Windows 桌面应用 + Web 界面 + 本地守护进程 + 命令行（`od`）+ 浏览器剪藏扩展（clipper）。
+- **体量**（官网与第三方口径）：约 86K GitHub star、402 贡献者、447+ 插件、152+ 设计系统；首个提交后 8 周即达 5.7 万 star，增长极快。
+- **发布节奏**：周更（CHANGELOG 目录 v0.14.1 → v0.19.1 连续推进），渠道分 beta / prerelease / preview / stable。
+- **一句话总结**：它把「提示词 → 生成设计稿 → 查看 → 修改 → 导出」这个闭环，做成了一组文件系统上的可组合资产（技能、模板、设计系统、插件），让任意 AI 编程代理（Claude Code、Codex、26 种 CLI）都能当渲染引擎用。
+
+## 2. 架构总览（对我们有参考价值的部分）
+
+```text
+浏览器 / Electron 渲染层
+        │ 同源 HTTP + SSE
+        ▼
+Next.js Web 应用 ──── 静态 UI / 预览状态
+        │ /api/* 代理
+        ▼
+Express 守护进程（产品唯一业务权威）
+   ├─ SQLite 状态 + 项目文件
+   ├─ 技能 / 设计模板 / 设计系统 / 插件 注册表
+   └─ 运行时注册表 → 拉起 CLI 或 ACP 子进程
+```
+
+关键设计决策（源自 `docs/architecture.md`）：
+
+- **Web UI 和 CLI 调同一套守护进程 API**。CLI 不是第二套业务实现，而是同一能力的机器可读面。避免双端逻辑漂移。
+- **早期架构草案被实现推翻**（Vercel tunnel、浏览器直连、WebSocket 会话总线等均被 HTTP/SSE + SQLite 守护进程取代），且文档明确标注「这些不是当前承诺」——对历史决策留痕、不误导后来者。
+- **守护进程只监听回环地址 127.0.0.1**，本机程序才能访问；网页无法伪造扩展源。这是 clipper 扩展「免配对、免令牌」安全模型的基础。
+
+## 3. 核心体验机制拆解（本次调研重点）
+
+### 3.1 版本「时光机」（v0.14 主打）
+
+**他们怎么做**：每个生成文件自动保留全部历史版本；每个版本可单独预览、单独导出（文件名自动带 `-v3` 后缀）；版本带来源标签——`AI 生成` / `手动保存` / `从历史还原` 三类，视觉上用不同颜色区分。内容用 SHA-256 摘要做身份比对（`apps/web/src/artifacts/version-origin.ts`）。
+
+**为什么好**：0.14 发布说明的原话——「太多好想法消失在流程里：一张有希望的草图、一个更好的早期版本」。设计工作天然是迭代型的，线性覆盖等于持续丢资产。来源标签还回答了「这一版是谁改的」。
+
+### 3.2 首次使用闭环引导（onboarding first-loop）
+
+**他们怎么做**（`apps/web/src/onboarding/first-loop.ts` 等）：明确定义新手闭环「写需求 → 生成 → 查看 → 修改 → 导出/分享」，只有用户**真正走完交付那一步**才记「引导完成」；每一步的达成顺序被记录成台账；全程按项目 ID 隔离，A 项目交付不会误关 B 项目的环。另有一个「第一个作品生成好了」的一次性提示（`first-artifact-hint.ts`）：新用户面对第一个生成结果不知道能看/能改/能导，该提示**每个浏览器终身至多出现一次**，用 localStorage 持久化「已看过」标记，存储被拒时静默降级。
+
+**为什么好**：引导的完成定义是「用户拿到成果」，不是「用户看完教程」；一次性纪律防止引导变成骚扰。
+
+### 3.3 入门模板三件套 + 永不空白兜底
+
+**他们怎么做**（`apps/web/src/onboarding/starter-copy.ts`）：首页每个入门模板配三样——标题、一句话说明、**可直接使用的第一条提示词**（点一下就开跑，解决「不知道怎么开口」）；文案键是 TypeScript 字面量类型，缺翻译直接编译报错而非运行时空白；未知模板 ID 回退到通用模板，未来版本先行发布的 ID 也不会渲染成空白。
+
+**为什么好**：把「冷启动成本」压到一次点击；兜底策略保证升级/回滚/数据错位时界面永不出现空洞。
+
+### 3.4 升级后的「有什么新功能」卡片
+
+**他们怎么做**（`docs/whats-new.md`）：升级重启后在首页右下角出现一次性卡片。内容是一份远端人工维护的 JSON，**按内容身份（id 字段）去重**而非按应用版本——客户端记住上次展示过的 id，id 变了才再次弹出；发空对象即可整体下线卡片；开发版和 CI 构建永远不请求、不打扰测试。
+
+**为什么好**：新版触达不依赖应用商店审核，也不会对已看过的用户反复弹；「内容身份去重」比「版本号去重」更可控（运营想再推一次改 id 即可）。
+
+### 3.5 过程透明：实时进度面板
+
+**他们怎么做**：生成过程中右侧有常驻面板（TerminalViewer、AgentDiagnosticRow 等组件）：正在执行的任务清单、流式的工具调用过程、实时可打断。用户不用盯 spinner 猜「它是不是卡了」。
+
+**为什么好**：长任务的最大体验杀手是不确定性；把过程摊开，等待就从「黑盒焦虑」变成「可观察的进度」。
+
+### 3.6 Clipper 浏览器扩展（与我们同类，重点参考）
+
+**他们怎么做**（`clipper/`，MV3，无构建步骤，原生文件直接装载）：
+
+- **零配置连接**：不配对、不输令牌。弹窗实时显示「● Connected」，检测到本地守护进程在跑就能直接用；安全前提是上文提到的回环监听 + 源信任。
+- **DevTools 风格元素拾取器**：「选取元素」模式下悬停高亮任意元素，点击即存为一个**自包含 HTML 快照**（保留页面级联样式、元素图片内联为 data URI、其余裁掉），Esc 取消。存下来的就是单个 HTML 文件，可直接打开分享，预览下方标注选择器与尺寸。
+- **图片批量选取网格**：页面上所有图片变成带复选框的覆盖网格，全选/清空/「保存 N 张」，精确选择而非全量抓取。
+- **高质量整页快照**：「捕获页面」产出可读样式内联、图片内联、脚本剥离的单文件 HTML。
+- **跨浏览器**：一份 manifest 同时适配 Chrome/Edge（service_worker）与 Firefox（background.scripts），18 种语言目录。
+
+### 3.7 DESIGN.md 设计系统契约
+
+**他们怎么做**（`docs/design-systems.md`）：一个设计系统是一个**包**而非一份文档：`manifest.json`（发现元数据）+ `DESIGN.md`（给代理读的设计散文）+ `tokens.css`（编译好的 CSS 变量）三件缺一不可；允许从品牌参考网页自动提取生成。所有技能在声明 `design_system.requires: true` 时自动注入当前激活的完整设计系统上下文。
+
+**为什么好**：把「风格」从提示词里抽离成可版本化、可复用、可自动注入的资产；品牌一致性由契约保证而不是靠每次口头叮嘱。
+
+### 3.8 技能协议：兼容已有生态而非另造格式
+
+**他们怎么做**（`docs/skills-protocol.md`）：技能 = 一个含 `SKILL.md` 的目录，**完全兼容 Claude Code 的 Agent Skills 格式，不做任何修改即可被读用**；在此之上提供可选的 `od:` 扩展元数据（模式、场景分类、示例提示词、是否需要设计系统、评审策略等）解锁自家 UI 特性。
+
+**为什么好**：站在已有生态的 distribution 上冷启动（别人的技能仓库直接可用），扩展元数据纯增量、不破坏可移植性。
+
+### 3.9 国际化与文案纪律
+
+- README 12 种语言，Web 应用与 clipper 扩展各 18 种语言目录。
+- 文案键为字面量类型联合（`keyof Dict`），缺翻译是**类型错误**不是运行时问题。
+- 所有兜底路径显式设计（未知 ID 回退通用模板、存储被拒静默降级、时区格式化失败回退默认）。
+
+### 3.10 观测与埋点
+
+埋点自成目录（`apps/web/src/analytics/`）：事件契约、错误码分类（导出/部署/供应商分别有独立错误码枚举）、敏感信息擦除（scrub）、会话身份、来源归因（入口面/外部插件/工作流逐级记）。「用户从哪来、在哪一步失败」是产品的一等公民数据。
+
+## 4. 对 Request Recorder 的借鉴对照
+
+| # | OpenDesign 模式 | 映射到 Request Recorder | 价值 | 成本 |
+|---|---|---|---|---|
+| 1 | 版本时光机 + 来源标签 | 会话内标记点：录制中允许打「动作标记」（如「准备点提交了」），回看时请求列表按标记分段，配合现有页面标注功能形成「动作 → 请求」因果视图 | 高（调试排障的核心痛点） | 中 |
+| 2 | 首次闭环引导 + 终身一次提示 | 新手闭环「录制 → 查看 → 筛选 → 复制导出」，走完交付步才算完成；首次录制成功的提示终身只出现一次 | 高（直接决定留存） | 低 |
+| 3 | 模板三件套（说明 + 现成的第一步） | 导出场景一键预设：「只看失败请求」「只要这个域名」「转成可直接跑的命令」；空状态配「试一试」示例会话 | 中高 | 低 |
+| 4 | 过程透明面板 | 录制中弹窗的现场感：实时捕获计数、进行中的请求、被过滤规则挡掉的数量 | 中 | 低 |
+| 5 | ● Connected 实时连接状态 | 录制服务/内容脚本注入状态的实时自检显示，异常时弹窗直接说「哪里断了、怎么恢复」而不是静默失效 | 中 | 低 |
+| 6 | What's New 内容身份去重卡片 | 版本更新后的新功能介绍：按内容 id 去重、远端可下线、开发构建不弹 | 中（用户量上来后更有价值） | 低 |
+| 7 | 元素拾取器交互细节 | 已有圈选标注可参考：悬停高亮 + Esc 取消 + 保存自包含快照的交互打磨 | 中 | 低 |
+| 8 | 文案键类型化 + 永不空白兜底 | 新增界面文案走字面量键联合类型；未知值回退显式设计 | 中（长期卫生） | 低 |
+| 9 | 单一业务权威 + 多端同源 | 录制逻辑只在后台服务一处，弹窗/历史页/标注面板全部消费同一状态源（现状已基本如此，保持纪律即可） | 中 | 低 |
+
+**不建议借鉴**：AI 模型市场与云计费（云端增值业务，与我们场景无关）、多代理运行时适配层（我们是单一职责工具）、多人协作。
+
+## 5. 结论
+
+OpenDesign 增长神话背后的体验方法论可以归纳为三条，全部可直接迁移：
+
+1. **不丢任何工作成果**（版本时光机）——线性覆盖即持续丢资产；
+2. **引导以「交付成果」为完成定义，且终身只打扰一次**（闭环引导 + 一次性提示）；
+3. **冷启动压到一次点击**（模板自带第一步、零配置连接、永不空白的兜底）。
+
+对 Request Recorder 而言，性价比最高的组合是 **#2 新手闭环引导 + #3 导出预设**（成本低、覆盖新用户全生命周期），差异化收益最大的是 **#1 会话内标记分段**（解决「这个动作到底发了哪些请求」的排障本质问题）。
+
+## 附：调研证据索引
+
+- 仓库：`github.com/nexu-io/open-design`（Apache-2.0，克隆于 /tmp/ref-open-design，末次提交 2026-08-18）
+- 版本历史：`docs/CHANGELOG/`、GitHub Releases（v0.19.1 最新）
+- 架构：`docs/architecture.md`
+- 技能协议：`docs/skills-protocol.md`；设计系统：`docs/design-systems.md`
+- 引导闭环：`apps/web/src/onboarding/first-loop.ts`、`first-artifact-hint.ts`、`starter-copy.ts`
+- 版本身份：`apps/web/src/artifacts/version-origin.ts`；版本 UI：`apps/web/src/components/FileViewer.tsx`（版本来源标签、单版本导出、方向键翻页）
+- What's New：`docs/whats-new.md`
+- Clipper 扩展：`clipper/README.md`、`clipper/manifest.json`
+
+<!-- 该文档整理/压缩于 2026-09-05 -->

docs/PAGE_ANNOTATION_KNOWLEDGE_BASE.md

@@ -131,3 +131,5 @@ sequenceDiagram
 - 界面文案仅中文；公开渠道分发前需按多语言规范补英文兜底（整个扩展的历史遗留）
 
 <!-- 该文档整理于 2026-08-17；定位：AI 修改页面标注/任务书逻辑前的快速参考 -->
+
+<!-- 该文档整理/压缩于 2026-09-05 -->

docs/REQUEST_EXPORT_KNOWLEDGE_BASE.md

@@ -149,3 +149,5 @@
 - 待补充：Postman Collection 导入实际兼容性验证；各格式转换器边界 case 单元测试（URL 含单引号、非标准 URL、Header value 为 undefined 等）；响应 CORS 头的分组归属是否需调整
 
 <!-- 该文档由 doc-init 生成于 2026-07-17；定位：AI 修改请求导出逻辑前的快速参考文档 -->
+
+<!-- 该文档整理/压缩于 2026-09-05 -->

docs/REQUEST_RECORDING_KNOWLEDGE_BASE.md

@@ -282,3 +282,5 @@ webRequest API 和 page-patcher 各自独立上报事件，配对规则：
 ⚠️ 未覆盖：SW 挂起唤醒（同浏览器会话内 SW 被杀再唤醒）走 `resumed` 分支恢复录制——Playwright 的 Worker 对象无 `close()`，无法在自动化中可靠触发 SW 重启，该分支仅经代码审查。
 
 <!-- 该文档由 doc-init 生成于 2026-07-17；定位：AI 修改请求录制逻辑前的快速参考文档 -->
+
+<!-- 该文档整理/压缩于 2026-09-05 -->