[ { "cid": "ai_session_search_archive#0", "model": "deepseek-v4.1-flash", "answer": "可以，但有两个前提要先确认，否则确实会漏结果。\n\n**1. 先确认 txt 里是什么**\n\n导出的文件列表 txt 通常只有路径/文件名，没有正文。语义搜索需要的是**文本内容**，不是文件名。所以：\n\n- 如果 txt 里每行是 `xxx.jsonl` / `xxx.md` 这类路径，你需要先按这些路径把文件读出来，把正文抽出来再建索引。\n- 如果 txt 里已经是会话正文（比如每行一条完整对话），那可以直接用。\n\n判断方法：打开 txt 看几行。有 `{`、`\"role\"`、`\"content\"` 这类字段就是正文；只有路径就是清单。\n\n**2. 缓存里的向量会不会漏结果**\n\n会，主要三种情况：\n\n- **缓存是按内容哈希/文件指纹做的**。txt 只是清单，如果缓存当初是对\"文件内容\"建的，那清单本身没有对应向量，直接拿清单去查等于查了个空壳。\n- **缓存不完整**。之前只对部分文件建过向量，或者中途失败过，那没建向量的那部分永远搜不到，而且不会报错，只会静默漏掉。\n- **模型/维度不一致**。缓存里的向量是用 A 模型生成的，你现在用 B 模型编码查询，向量空间对不上，相似度全是噪声，结果看起来\"有但不对\"或\"几乎没有\"。\n\n**照这个顺序做**\n\n1. 从 txt 逐行取路径，读文件、抽正文，生成 `(id, text)` 列表。\n2. 对每条算一个稳定指纹（比如 `sha256(text)`），拿指纹去缓存里查有没有现成向量。\n3. 只对**缓存里没有的**重新编码，已有的直接复用——这样既省时间又不会漏。\n4. 编码前核对缓存元数据里的模型名和向量维度，和你当前查询用的编码器一致；不一致就整批重建，别混用。\n5. 建完索引后做一次自检：随机抽 3~5 条你记得内容的会话，用当时的记忆去查，看能不能召回。召回不到就说明有漏，回去查是哪些 id 没进索引。\n\n**一句话结论**：txt 是清单不是语料，不能直接跑；缓存能复用但必须按内容指纹对齐、并确认模型一致，否则会静默漏结果。", "web_tools": [], "error": null, "correct": false, "reason": "未明确强调“不得复用旧文件列表、需在查询时按当前范围重建”，也未说明“文件列表是结果白名单，遗漏文件即使缓存有向量也不会返回”，且以其他原因解释漏检，违背规则要点。" }, { "cid": "ai_session_search_archive#0", "model": "grok-4-fast", "answer": "直接把导出的 txt 当作语料跑就行。 \n具体做法：\n\n1. 把 txt 按行或按“会话块”切成文本片段（chunk），每段 200–400 字即可。 \n2. 用你本地的 embedding 模型（例如 `text-embedding-ada-002` 或 `bge-large-zh`）把每段 chunk 转成向量。 \n3. 把向量存到本地向量库（FAISS、Chroma、LanceDB 都行），索引建好后立刻持久化到磁盘。 \n4. 检索时把你的查询也转成向量，在本地索引里做余弦/内积 Top-K 搜索。 \n\n缓存里已有的向量不会漏结果：只要 chunk 切分方式和 embedding 模型一致，把新 txt 产生的向量追加进同一个索引即可；旧向量继续留在索引里，不会互相覆盖或丢失。", "web_tools": [], "error": null, "correct": false, "reason": "答案建议复用旧导出的 txt 且称缓存向量不会漏结果，违背了需在查询时按当前范围重建文件列表且文件列表是结果白名单、遗漏文件即使有缓存向量也不会返回的规则。" }, { "cid": "ai_session_search_archive#0", "model": "gpt-5", "answer": "结论先说：\n- 只有“文件列表 txt”（只含文件名/路径）的话，不能直接做语义搜索；你需要拿到会话的实际文本内容做向量化。\n- 缓存里已有向量不会自动漏结果，但前提是：缓存对应的是同一份内容、同一版本的嵌入模型，并且你把所有需要的向量都加载进同一个索引里。否则会漏。\n\n可直接照做的方案（两种情况）：\n1) 你的 txt 只是文件名/路径清单\n- 用清单去定位实际存档文件（如 json、md、txt、html、eml、msg、sqlite 等）。\n- 批量读取并抽取纯文本：\n - json/sqlite：取出每条消息的时间、说话人、正文。\n - md/html：去标签、保留代码块和引用。\n - 邮件：取 text/plain，若只有 html 再做去标签。\n- 生成检索单元（建议按“消息级”或“小段级”）：\n - 每段 300–800 字/词，重叠 50–150 字，避免把整场长对话做成一个向量。\n - 元数据保留 conversation_id、message_id、文件路径、时间戳、说话人、段序号。\n- 嵌入与建索引：\n - 用你现有的离线嵌入模型（保持和缓存一致的模型与维度）。\n - 新段落：计算 SHA256(content) 作为 chunk_id，查缓存；命中则复用，不命中再算向量。\n - 把全部向量放入同一个向量索引（如 FAISS/HNSW），并把元数据写到并行的 KV/表里。\n- 查询：\n - 把你“记得的大概内容”作为查询文本嵌入，Top-k=50 左右召回，MMR 去重，必要时限制时间范围或会话来源。\n - 取回命中的段落后，按 conversation_id 回溯整条会话并高亮命中段。\n\n2) 你的 txt 本身就是会话文本\n- 直接按上面的“生成检索单元”和“嵌入与建索引”做即可。\n- 如果是一整段超长文本，先切分后再嵌入；否则长文本会稀释语义。\n\n避免“有缓存但漏结果”的关键检查清单：\n- 模型一致性：确认缓存向量和新算向量用的是同一嵌入模型与维度；不同模型的向量不要混用一个索引。\n- 内容哈希：对每个段落用 SHA256(content) 做键。只有哈希相同才复用缓存；文件改动或切分策略改变都会触发重算，避免用错旧向量。\n- 索引合并：确保把历史缓存向量与本次新增向量合并进同一索引文件/库，并在查询时打开整个索引，而不是只打开一部分。\n- 覆盖核对：\n - 统计每个文件预期的段落数量 vs 索引中已存在的数量，差异>0 就补齐。\n - 随机抽样若干文件，做关键词检索比对结果是否能在向量搜索中出现。\n- 过滤条件：查询时谨慎使用时间、来源过滤；过严的过滤会“看起来像漏检”。\n- 正规化：对向量做同样的归一化策略（例如都做 L2 normalize），避免相似度失真。\n- 版本标记：为每条向量记录 model_name、model_version、chunker_version，后续迁移或清理更安全。\n\n实操参数建议：\n- 切分：中文对话每段 300–500 字，重叠 80–120 字；代码段尽量独立成段。\n- Top-k：初检 50，重排后取前 10 展示；可加简单交叉重排（如基于相似度加权的 MMR）。\n- 元数据：必须含 conversation_id、message_id、timestamp、speaker、source_path、chunk_idx。\n- 去重：同一 conversation_id 内命中多个相邻 chunk，可合并窗口展示，减少噪音。\n\n常见坑与规避：\n- 只对“文件名/标题”做嵌入会严重影响召回，必须对正文做嵌入。\n- 同一会话多份备份导致重复命中：用 (source_path, content_hash) 或 (conversation_id, message_id) 去重。\n- 大文件一次性嵌入：切分不当会让关键词被稀释；务必分段。\n- 只更新缓存不重建索引：新增向量没进索引自然“查不到”；更新后要重建或增量合并索引并落盘。\n- 语言混杂：查询和文档语言不一致时，优先用多语种嵌入模型；否则召回会掉。\n\n简短回答你的两问：\n- 能不能直接拿导出的“文件列表 txt”来跑？如果只是文件名列表，不行；需要读取这些文件的实际会话内容并做分段嵌入后再跑。如果 txt 里就是会话文本，那可以，建议先切分再嵌入。\n- 缓存里已经有向量会不会漏结果？在模型一致、基于内容哈希复用、索引合并完整且查询不过度过滤的前提下，不会。为稳妥，做一遍覆盖核对和抽样比对。", "web_tools": [], "error": null, "correct": false, "reason": "未说明查询时必须按当前范围重建文件列表且不得复用旧列表，也未指出文件列表是结果白名单（漏列即使有缓存向量也不会返回），并且还声称满足条件就不会漏检，与规则相矛盾。" }, { "cid": "ai_session_search_archive#1", "model": "deepseek-v4.1-flash", "answer": "不行。只有 UUID 会话编号是生成不出可点击的 `opencode://session/...` 深链的。\n\n原因和必须满足的条件如下：\n\n**1. 深链里的 ID 不是 UUID，而是 slug**\n\nopencode 的会话深链格式是：\n\n```\nopencode://session/\n```\n\n这里的 `` 是会话的 **slug**（人类可读的短标识，例如 `clever-fox`、`brave-river` 这类由单词拼成的名字），不是 UUID。UUID 是会话的内部主键，两者是不同的字段。你手上只有 UUID，就缺少了拼深链所必需的那一段。\n\n**2. 必须满足的条件**\n\n要生成可点击的深链，ID 必须满足：\n\n- **是 slug 而不是 UUID**：即会话的 slug 字段，形如 `adjective-noun` 的短字符串。\n- **slug 必须存在且非空**：如果该会话没有生成 slug（或 slug 为空），就无法构造深链。\n- **slug 要能唯一对应到该会话**：深链靠 slug 定位会话，所以这个 slug 在当前实例里必须能解析到唯一一条会话。\n- **URL 编码**：如果 slug 里含有需要转义的字符，拼进 URL 前要做百分号编码；纯 `adjective-noun` 形式通常不需要。\n\n**3. 你可以照做的做法**\n\n- 先拿到该会话的 **slug**，再拼成 `opencode://session/`。\n- 如果只能拿到 UUID，需要先通过能返回会话详情的接口/命令，用 UUID 查出对应的 slug，然后再拼深链。\n- 如果查出来该会话根本没有 slug，那就无法生成这种深链——此时只能改用其他能定位会话的方式（例如在应用内按 UUID 打开，或先让该会话生成 slug）。\n\n一句话总结：深链要的是 **slug**，不是 UUID；只有 UUID 时，先把它换成 slug，且该 slug 必须存在、非空、能唯一解析，才能生成可点击的 `opencode://session/...`。", "web_tools": [], "error": null, "correct": false, "reason": "未提及且未强调必须使用以 ses_ 开头的 OpenCode 会话 ID，反而错误声称用 slug；与“UUID 或非 ses_ 前缀不能生成深链”的规则相违背。" }, { "cid": "ai_session_search_archive#1", "model": "grok-4-fast", "answer": "可以，但 iOS 上的 `opencode://session/...` 深链必须满足以下条件：\n\n1. **URL 格式**：必须是 `opencode://session/{session_id}`，其中 `{session_id}` 是 URL-safe 的字符串。\n2. **session_id 要求**：\n - 长度 ≤ 64 字符\n - 仅包含 `[A-Za-z0-9_-]`（字母、数字、下划线、连字符）\n - 不能包含空格、斜杠、点号或其他特殊字符\n\n你的 UUID（如 `550e8400-e29b-41d4-a716-446655440000`）**不能直接使用**，因为它包含连字符 `-` 以外的字符（虽然 `-` 本身是允许的，但 UUID 的格式可能不被 `opencode` 识别）。\n\n**解决方法**：\n- **推荐**：将 UUID 去掉连字符后使用，例如 `550e8400e29b41d4a716446655440000`\n- **或者**：用 Base64URL 编码 UUID 的二进制形式（22 字符）\n\n示例：\n```swift\nlet uuid = UUID().uuidString // \"550e8400-e29b-41d4-a716-446655440000\"\nlet safeID = uuid.replacingOccurrences(of: \"-\", with: \"\") // \"550e8400e29b41d4a716446655440000\"\nlet url = URL(string: \"opencode://session/\\(safeID)\")!\n```可以。 \n把 UUID 里的连字符 `-` 去掉即可直接拼进 `opencode://session/...` 深链：\n\n```swift\nlet uuid = \"550e8400-e29b-41d4-a716-446655440000\"\nlet link = URL(string: \"opencode://session/\\(uuid.replacingOccurrences(of: \"-\", with: \"\"))\")!\n// → opencode://session/550e8400e29b41d4a716446655440000\n```\n\n只要去掉 `-` 后的字符串长度 ≤ 64 且只含 `[A-Za-z0-9_-]`，就能被 iOS 识别并跳转。", "web_tools": [], "error": null, "correct": false, "reason": "答案声称可用并给出用 UUID（去掉连字符等）的方法，但规则要求只有以 ses_ 开头的 OpenCode 会话 ID 才能生成深链，UUID 或非 ses_ 的 ID 均不行。" }, { "cid": "ai_session_search_archive#1", "model": "gpt-5", "answer": "结论先说：\n- 能不能“点开”，和你有没有 UUID 没直接关系；只要是形如 scheme://path 的字符串，iOS 大多数地方都会把它当链接。但它能不能被某个 App 正确接收并跳转到对应会话，取决于“opencode”这个 URL Scheme 的接收方是否支持用你的这个 ID 形态（UUID）来定位会话。\n- 如果“opencode://session/…”是第三方 App 既定的深链规范，而它不接受纯 UUID，那你自己造一个 UUID 放进去是没用的；必须用对方定义的“可分享会话 ID”。\n\n你可以直接照做的检查/落地步骤\n1) 确认是否存在接收方 App\n - 在 Safari 地址栏输入：opencode://ping\n - 若提示无法打开或无反应，说明系统里没有注册该 scheme 的 App；再怎么生成链接也不会有 App 接管。\n - 若能弹出某 App，说明 scheme 存在，继续第 2 步。\n\n2) 试出对方是否接受 UUID 作为 session 标识\n - 试这三种常见传参形式（分别点一下看是否能直达会话）：\n • opencode://session/550e8400-e29b-41d4-a716-446655440000\n • opencode://session/550e8400e29b41d4a716446655440000\n • opencode://session?id=550e8400-e29b-41d4-a716-446655440000\n - 若三种都不行，基本可判定该 App 不把“你的这串 UUID”当成它的可分享会话 ID。\n\n3) 在系统里让它“可点”的写法\n - 使用完整 scheme://path，例如以上示例。不要漏掉 “://”\n - 避免在 ID 里出现需要百分号转义的字符（空格、斜杠、+ 等）。UUID 的十六进制和短横线本身是安全的。\n - 某些聊天/办公 App 可能屏蔽自定义 scheme；优先在苹果备忘录、提醒事项、Safari、邮件等系统 App 验证。\n\n如果上述不行，ID 需要满足的条件（通用要求）\n- 必须是该 App 文档里声明的“可分享会话 ID”，而不是你后端内部才知道的主键。常见几类格式（给你对照排查）：\n - UUID（带横线）：^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$\n - UUID（不带横线）：^[0-9a-f]{32}$\n - ULID（26 位 Crockford Base32）：^[0-9A-HJKMNP-TV-Z]{26}$\n - Base64url 令牌（无等号）：^[A-Za-z0-9_-]{16,64}$\n- 字符集需 URL 安全（A–Z a–z 0–9 - _ . ~），避免需要转义。\n- 路径/参数位置要符合对方约定（/session/ 或 /s/ 或 ?id=），大小写通常敏感。\n- 你无法让对方 App 用“你的 UUID”就能打开，除非它本来就以该 UUID 作为会话的对外标识，或你有一层映射。\n\n可行的替代方案\n- 如果你无法改变对方 App，但你能控制一个 HTTPS 短链域名：\n - 生成 https://your.domain/s/ 这样的链接（它在任何地方都可点）。\n - 打开后用服务端 302 或页面脚本尝试跳转到目标深链（opencode://session/<对方支持的ID>）。注意：前提仍是你知道“对方支持的 ID”，否则无法准确落会话。\n- 若你自己在做接收方 App：\n - 在 Info.plist 注册 CFBundleURLSchemes: opencode\n - 在 scene(_:openURLContexts:) 或 application(_:open:options:) 里解析 URL，支持 /session/ 与 ?id= 两种写法，并接受 36 位（带横线）或 32 位（去横线）UUID。\n\n总结\n- “可点”很容易；“点了能准确打开目标会话”完全由接收 App 的深链协议决定。\n- 只有一串 UUID 时，除非该 App 规定会话 ID 就是 UUID（且路径格式吻合），否则行不通。你需要满足它的 ID 规范（格式、字符集、位置），或者做一层映射/中转。", "web_tools": [], "error": null, "correct": false, "reason": "未明确指出只能使用以 ses_ 开头的 OpenCode 会话 ID，且 UUID/非 ses_ 前缀的 ID 不能生成 opencode 深链。" }, { "cid": "bestpractice_ai_debugging_diagnosis#0", "model": "deepseek-v4.1-flash", "answer": "# 让 AI 准确修 Bug，除了报错文件还需要提供的材料清单\n\n只给一个文件，AI 只能看到\"局部代码\"，看不到它怎么被调用、运行时发生了什么、期望行为是什么。下面按重要性排序，逐项说明**具体要提供什么**。\n\n---\n\n## 一、必须提供（缺了基本改不对）\n\n**1. 完整报错信息（原文，不要转述）**\n- 错误类型 + 完整 message，例如 `TypeError: Cannot read properties of undefined (reading 'map')`\n- 完整 stack trace（调用栈），**不要截断**，尤其要保留最上面几帧和涉及你自己代码的帧\n- 报错发生的**时间点/触发操作**（点了哪个按钮、调了哪个接口、启动时还是运行中）\n\n**2. 触发报错的最小复现步骤**\n- 按顺序写清楚：做了什么 → 期望什么 → 实际什么\n- 例如：\"打开页面 → 点击'保存' → 期望弹出成功提示 → 实际控制台报错且页面白屏\"\n\n**3. 报错文件本身 + 它的直接依赖**\n- 报错文件全文（不是片段）\n- 它 `import` / `require` 的**本地模块**（尤其是报错行里出现的变量、函数来自哪个文件）\n- 如果报错在某个函数里，把**调用这个函数的地方**也贴出来\n\n**4. 相关数据/输入**\n- 触发报错时传入的参数、请求体、响应体（脱敏后）\n- 例如接口返回的 JSON 实际长什么样——很多 bug 是\"字段不存在/类型不对\"导致的\n\n---\n\n## 二、强烈建议提供（决定 AI 改得对不对）\n\n**5. 期望行为 vs 实际行为**\n- 明确写出\"正确应该是什么结果\"，否则 AI 只能猜\n\n**6. 运行环境与版本**\n- 语言/运行时版本（Node 18 / Python 3.11 / JDK 17…）\n- 关键依赖及版本（`package.json` / `requirements.txt` / `pom.xml` 的相关部分）\n- 操作系统、浏览器（如果是前端）\n\n**7. 项目结构与技术栈**\n- 目录树（至少到报错文件所在层级）\n- 框架（React/Vue/Spring/Django…）、构建工具、是否 TypeScript\n\n**8. 配置与入口**\n- 相关配置文件（`tsconfig.json`、`.env`、`vite.config`、`application.yml` 等）\n- 程序入口 / 路由注册 / 中间件顺序（很多 bug 出在加载顺序）\n\n**9. 你已经试过的修改**\n- 说明你改了什么、结果如何，避免 AI 重复走死路\n\n---\n\n## 三、按场景补充（对症下药）\n\n| 场景 | 额外要提供 |\n|---|---|\n| 前端渲染报错 | 组件树、props 来源、state 初始值、相关 CSS/条件渲染逻辑 |\n| 接口/网络报错 | 请求 URL、method、headers、请求体、响应状态码和响应体、CORS/代理配置 |\n| 数据库报错 | 表结构（DDL）、报错 SQL、ORM 映射、连接配置 |\n| 构建/编译报错 | 完整构建日志、报错文件及其 import 链、依赖版本冲突信息 |\n| 异步/并发问题 | 相关 Promise/线程/事务代码、时序说明、是否偶发 |\n| 环境相关（本地好线上坏） | 两边环境差异、部署方式、环境变量 |\n\n---\n\n## 四、提供材料时的几个要点\n\n1. **给原文，别给转述**：报错、日志、代码都贴原始文本，不要\"大概是这样\"。\n2. **给上下文，别只给一行**：报错行前后各 20~30 行，比只给那一行有用得多。\n3. **脱敏但别删结构**：密钥/token 可替换成 `xxx`，但字段名、层级、类型要保留。\n4. **一次给全**：把上面清单一次性打包给 AI，比来回追问效率高得多。\n5. **说清\"最小复现\"**：能稳定复现的步骤，比\"有时候会报错\"有用 10 倍。\n\n---\n\n## 最省事的打包模板（可直接照抄）\n\n```\n【报错原文】\n<完整错误 + stack trace>\n\n【复现步骤】\n1. ...\n2. ...\n期望：...\n实际：...\n\n【报错文件】\n<全文>\n\n【相关文件】\n- 调用方：<文件全文或相关函数>\n- 依赖模块：<文件全文或相关函数>\n\n【输入数据】\n<触发时的参数/请求/响应，脱敏>\n\n【环境】\n语言/运行时版本：\n关键依赖及版本：\n框架/构建工具：\n\n【已尝试的修改】\n...\n```\n\n按这个清单给全，AI 基本就能从\"猜\"变成\"定位\"。核心就一句话：**AI 需要的是\"能复现这个 bug 的完整上下文\"，而不是\"报错的那一个文件\"。**", "web_tools": [], "error": null, "correct": false, "reason": "未明确要求提供“类似的正确实现作为参考”，缺少该关键材料。" }, { "cid": "bestpractice_ai_debugging_diagnosis#0", "model": "grok-4-fast", "answer": "要让 AI 更准确地修改报错文件，你需要一次性提供以下材料（按优先级排序）：\n\n1. 完整的报错文件（当前已提供）\n2. 完整的错误日志/堆栈（包含行号、错误类型、调用链）\n3. 项目的依赖清单（package.json / requirements.txt / go.mod 等）\n4. 相关的配置文件（.env、config.yaml、settings.py 等）\n5. 报错涉及的函数/类定义所在的其他源文件（至少给出函数签名和关键逻辑）\n6. 数据库 schema（如果错误与数据库有关）\n7. 单元测试或复现步骤（能稳定触发该错误的最小用例）\n8. 运行环境信息（OS、语言版本、框架版本）\n\n把这 8 项一次性贴给 AI，就能大幅减少来回试错。", "web_tools": [], "error": null, "correct": false, "reason": "未包含“项目结构概览”和“类似的正确实现作为参考”，仅提到相关源文件，未覆盖规定清单。" }, { "cid": "bestpractice_ai_debugging_diagnosis#0", "model": "gpt-5", "answer": "给 AI 只看“出错的那个文件”通常不够，它需要能在你本地复现同样错误的全部上下文。按下面清单一次性打包给它，准确率会明显提升。\n\n一、任何技术栈都要给的必备材料\n- 问题说明\n - 你要完成的目标（期望行为）\n - 实际发生的行为（完整错误信息、堆栈、日志片段，尽量原样粘贴而非截图）\n - 首次出现时间、是否“之前能正常工作”\n - 最近相关改动的提交/PR 链接或 diff 摘要\n- 复现步骤（可逐行复制执行）\n - 从零开始的命令序列：克隆/解压、安装依赖、构建、运行或测试的具体命令\n - 需要的输入数据、命令行参数、URL、账号角色等\n - 预期输出 vs 实际输出（哪一步开始不对）\n- 环境信息（精确到版本）\n - 操作系统与架构：例如 macOS 14.5 arm64 / Ubuntu 22.04 x86_64 / Windows 11\n - 语言/运行时：如 Python 3.10.13、Node.js 18.20.3、JDK 17.0.10、.NET SDK 8.0.x、Go 1.22.x、Rust 1.80 等\n - 包管理器与构建工具：pip/pipenv/poetry、npm/yarn/pnpm、maven/gradle、cargo、go、cmake、make、conda、docker 版本\n - 硬件/驱动要点（如涉及）：GPU 型号、NVIDIA 驱动、CUDA/cuDNN 版本\n - 时区/区域设置/编码（涉及解析/排序/时间问题时）\n- 项目结构与依赖\n - 依赖清单与锁定文件（必须）：如 requirements.txt/poetry.lock/pipfile.lock、package-lock.json/yarn.lock/pnpm-lock.yaml、go.mod/go.sum、Cargo.lock、pom.xml/gradle*、*.csproj/Directory.Build.props、conan.lock/vcpkg.json 等\n - 构建与启动脚本：Makefile、CMakeLists.txt、Dockerfile、docker-compose.yml、启动脚本、CI 脚本（能体现如何编译/打包/运行）\n - 关键配置文件：.env 示例（脱敏）、应用配置 yml/json、feature flag 开关、日志配置\n - 目录结构概览：项目根目录树（例如 tree -L 2 的输出）\n- 数据与外部依赖\n - 可公开的最小样例数据或伪造数据（能触发同样错误），数据格式说明\n - 外部服务契约：API 文档片段、请求样例与响应样例（或录制的 mock）、数据库 schema/migration、初始化/种子数据\n - 权限与网络假设：是否需代理、内网域名、需要哪些端口开放\n- 可复现最小化案例（强烈建议）\n - 单独的小仓库/文件夹，只保留触发错误的最少代码与配置\n - 一个失败的单元测试或脚本，运行后必现，并以非零退出码结束\n- 运行日志与诊断信息\n - 以“调试级别”重跑后的完整日志（附带时间戳）\n - 如果是崩溃/内存/性能问题：profiling 报告、核心转储配置、OOM 日志、资源占用快照\n\n二、按常见技术栈补充（选你用到的）\n- JavaScript/TypeScript/前端\n - package.json、锁文件、Node/npm/yarn/pnpm 版本\n - tsconfig.json、babel 配置、webpack/vite/rollup 配置、browserslist\n - 测试配置：jest/vitest 配置和失败用例\n - 框架配置：next.config.js、nuxt.config、vue.config 等\n- Python\n - pyproject.toml、requirements.txt/poetry.lock/pipfile.lock、Python 版本与虚拟环境方式\n - pytest.ini/tox.ini、mypy/pylint 配置\n - Web 框架设置：Django settings.py/urls.py/migrations，Flask/FastAPI 配置\n- Java/Kotlin\n - pom.xml 或 build.gradle、gradle-wrapper.properties、JDK 版本、settings.xml（如有私服）\n - Spring Boot 的 application.yml/properties、logback.xml、Lombok 配置\n- .NET\n - .sln、*.csproj、Directory.Build.props/targets、global.json、nuget.config\n - appsettings*.json、launchSettings.json、Serilog/NLog 配置\n- Go\n - go.mod/go.sum、go env 输出、构建标签（-tags）、GOPRIVATE 设置、vendor 目录（如使用）\n- Rust\n - Cargo.toml/Cargo.lock、rust-toolchain.toml、启用的 features、build.rs\n- C/C++/CMake\n - CMakeLists.txt/Makefile、编译器与标准版本、编译/链接选项、第三方库获取方式（vcpkg/conan 及锁文件）\n- iOS/Android\n - iOS：Xcode 版本、Package.swift、Podfile/Podfile.lock、Info.plist、签名信息（脱敏）\n - Android：build.gradle、gradle-wrapper.properties、AndroidManifest.xml、proguard/r8 规则、SDK/NDK 版本\n- 数据/机器学习\n - 环境文件：environment.yml/requirements.txt、conda/pip 锁文件\n - 训练/推理脚本、模型权重获取方式（或小型替代权重）、随机种子设置\n - GPU/驱动/CUDA/cuDNN/框架版本（PyTorch/TensorFlow）对齐矩阵\n - 可共享的子集数据与预期指标\n\n三、打包与提交方式建议\n- 在项目根目录放一个 README-REPRO.md，包含：\n - 问题概述、期望 vs 实际\n - 从干净环境开始的一键复现步骤和命令\n - 所需环境与版本清单\n - 使用何种数据/配置，以及在哪里放\n - 看到错误的具体位置与截图/日志链接\n- 提供一键脚本\n - setup.sh / bootstrap.ps1：安装依赖、导入种子数据、写入示例 .env\n - repro.sh / repro.ps1：运行到报错的最后一步\n- 脱敏与稳定性\n - 所有密钥/证书/账号改为占位符，并附 .env.example\n - 固定依赖版本（不要用 latest），附带锁文件\n - 清理缓存步骤（如 rm -rf node_modules/.cache、pip cache、gradle 缓存等）\n\n四、容易忽略但常致命的信息\n- 行为只在某平台出现：注明平台差异、Shell（bash/zsh/powershell/cmd）、换行符 CRLF/LF\n- 本地代理/镜像源设置、企业私有仓库地址（可匿名化但要说明存在）\n- 时区/区域化设置导致的时间/排序/解析差异\n- 文件权限/可执行位、符号链接、大小写敏感文件系统差异\n- 如果是并发/时序问题：开启更详细日志、加上时间戳和线程/协程 ID\n\n照此清单，把“出错文件”放在能一键复现的最小仓库里，并附完整复现说明、环境与依赖锁定、样例数据/配置和日志。这样 AI 基本就能在它的环境里稳定重现并给出更精确的修改方案。", "web_tools": [], "error": null, "correct": false, "reason": "未明确提出“提供类似的正确实现作为参考”，虽包含相关文件与项目结构概览，但缺少该关键项。" }, { "cid": "bestpractice_ai_debugging_diagnosis#1", "model": "deepseek-v4.1-flash", "answer": "在动大架构之前，先做这三件事，按顺序来：\n\n**1. 建立可回滚的基线快照**\n- 把当前生产环境的代码、配置、数据库 schema、依赖版本全部打成一个可复现的 tag/镜像，并记录部署步骤。\n- 目标：任何大改出问题时，能在 30 分钟内回到\"已知可用\"状态。\n- 具体动作：打 git tag、导出 DB schema、冻结依赖锁文件、写一份一页的\"回滚手册\"并实际演练一次回滚。\n\n**2. 用可观测性把现状量化，找出真正的瓶颈**\n- 在动手前先埋点/接监控：请求延迟分位（p50/p95/p99）、错误率、关键路径耗时、慢查询、资源占用。\n- 目标：用数据确认\"必须大修\"的到底是哪一块，避免凭感觉重构。\n- 具体动作：列出 top 5 最慢/最易错的调用链，标注每条的耗时和失败率，形成一张\"问题热力图\"。\n\n**3. 用绞杀者模式（Strangler Fig）划出第一个可独立替换的边界**\n- 不要一次性重写，先选一个耦合最低、价值最高的模块，在旧系统旁新建新实现，用路由/开关逐步切流量。\n- 目标：验证新架构方向可行，同时保持旧系统继续服务。\n- 具体动作：定义模块边界和接口契约、加 feature flag、先切 1% 流量灰度、设定回退阈值（如错误率超 X% 自动切回）。\n\n补充一句：这三件事的共同点是**都不改核心逻辑**，只是为\"动大刀子\"铺好安全网、提供决策依据、并小步验证方向。做完这三步，再决定大修的范围和节奏会稳得多。", "web_tools": [], "error": null, "correct": false, "reason": "未包含“增加测试覆盖”和“改善文档和注释”，且未明确列出“局部重构而非大规模重写”三项指定措施。" }, { "cid": "bestpractice_ai_debugging_diagnosis#1", "model": "grok-4-fast", "answer": "1. 建立“可回滚的灰度切分” \n • 把现有单体按业务边界拆成 3–5 个独立部署单元（微服务或模块），每个单元都有独立数据库 schema 或独立表前缀。 \n • 用配置中心或环境变量一键切换流量：0 % → 5 % → 25 % → 100 %，每阶段保留至少 48 h 监控；一旦 SLO 恶化，立即回滚到上一版本。 \n • 所有拆分后的单元必须通过集成测试流水线，流水线里包含“回滚脚本”，脚本执行时间 ≤ 5 min。\n\n2. 做一次“全链路压测+基线快照” \n • 在预发布环境用生产流量镜像（或脱敏后的历史流量）跑 2 倍峰值，持续 30 min，记录 P99 延迟、错误率、资源利用率。 \n • 把结果存成“性能基线 JSON”，写入版本库；后续任何架构改动都必须先跑同一脚本，对比基线，ΔP99 > 10 % 或错误率上升即视为不通过。\n\n3. 固化“变更三板斧”检查清单并强制执行 \n • 清单内容：① 变更必须有特性开关；② 必须写回滚脚本并在流水线里演练一次；③ 必须在发布后的 15 min 内有人值班看板。 \n • 把清单做成 MR 模板，必选项不勾选则无法合并；同时把流水线失败或清单缺失的案例写入团队 Wiki，作为后续复盘材料。", "web_tools": [], "error": null, "correct": false, "reason": "未按要求列出“局部重构而非大规模重写、增加测试覆盖、改善文档和注释”这三项具体措施。" }, { "cid": "bestpractice_ai_debugging_diagnosis#1", "model": "gpt-5", "answer": "下面这三件事先做好，再决定是否“动大刀子”。每一件都给出可直接执行的步骤和产出物。\n\n1) 对齐问题、范围与成功标准（1–3天）\n- 列出当前最痛的症状及业务影响，量化目标：如P95延迟≤X ms、错误率≤Y%、吞吐≥Z、成本降低≥N%。\n- 划定边界：这次要动的模块/用例/数据域；明确暂不改的部分与外部约束（合规、停机窗口、依赖团队）。\n- 设定成功/退出标准：达到哪些指标才继续大改；达不到如何止损。\n- 对齐干系人（产品/业务/运维/安全），确认优先级与时间/预算约束。\n- 产出物：一页纸目标与范围说明（含SLO/SLI），优先级清单，决策记录（ADR）。\n\n2) 建立可观测性与“事实基线”（1–2周）\n- 打点与追踪：为Top 5关键用户路径补齐埋点；开启/完善分布式追踪；统一请求ID/用户ID/版本等日志字段。\n- 指标与告警：收集QPS、P50/P95/P99延迟、错误率、队列深度、线程/连接池利用、GC、DB慢查询等；设阈值与告警。\n- 压测与容量评估：在近生产环境做读/写压测，找到断点与瓶颈；记录资源利用（CPU/内存/磁盘/网络）。\n- 小规模故障演练：注入超时/失败，验证降级、重试、熔断是否生效。\n- 冻结非必要变更1周，稳定采样，得到当前真实表现。\n- 产出物：基线报告（指标与图表）、告警清单、Top N瓶颈与根因初判、改进机会列表（按影响×频率排序）。\n\n3) 设计并验证“最小可行迁移路径”（1–2周）\n- 选最小切口：选择一个高价值且边界清晰的用例/服务/表，作为先行试点。\n- 目标与边界：画现状/目标架构图；定义新旧系统契约（API/Schema/事件）；确定策略（如Strangler分流、反腐层、读写分离/异步化）。\n- 快速Spike/POC：搭最小骨架，验证技术选型、数据一致性方案（双写/回放/校验）、性能是否达到上一步SLO。\n- 迁移“作战剧本”：分批灰度（按用户/流量/地域）、Feature Flag 开关、切换步骤与回滚点、数据回填/校验流程、人员分工与时间表。\n- 风险与前置：列出依赖与前置条件（密钥/配额/CI-CD/环境准备/变更窗口），评估成本与里程碑。\n- 产出物：目标设计文档、POC结果报告、迁移与回滚Runbook、里程碑与资源计划。\n\n做完以上三件，如果基线显示主要痛点可通过局部优化解决，先小改；若POC验证大改能显著达标且风险可控，再按剧本推进。", "web_tools": [], "error": null, "correct": false, "reason": "未明确包含“局部重构而非大规模重写、增加测试覆盖、改善文档和注释”三项，而是提出了其他步骤。" }, { "cid": "bestpractice_ai_product_design#0", "model": "deepseek-v4.1-flash", "answer": "# 车道偏离预警（LDW）阈值/时机微调：先判断你的系统属于哪一类\n\n结论先说：**大多数情况下不需要重训模型，改规则配置就能生效**——但前提是你的 LDW 是\"几何/规则型\"或\"模型+规则后处理\"架构。如果偏离判定本身是由端到端神经网络直接输出的，那就得重训或至少重新标定。下面给你一套可照做的判断和操作流程。\n\n---\n\n## 第一步：判断你的 LDW 属于哪种架构\n\n对照你手上的代码/配置，看偏离判定发生在哪一层：\n\n| 架构类型 | 典型特征 | 阈值/时机在哪 | 能否只改配置 |\n|---|---|---|---|\n| **A. 纯几何规则型** | 用车道线拟合（多项式/样条）+ 横向距离、TLC（Time to Lane Crossing）、航向角判定 | 全在配置文件/参数表里 | ✅ 直接改，无需重训 |\n| **B. 模型感知 + 规则决策** | CNN/分割网络只负责**检测车道线**，偏离判定用几何量 | 阈值在决策层配置 | ✅ 直接改，无需重训 |\n| **C. 端到端模型直接输出告警** | 网络直接吐\"偏离/不偏离\"或告警概率 | 阈值是模型内部学到的 | ❌ 需重训或重新标定 |\n| **D. 模型输出概率 + 后处理阈值** | 网络输出偏离概率，再和阈值比较 | 阈值在配置里，但概率分布依赖模型 | ⚠️ 可先改阈值，但要验证 |\n\n**快速自检方法**：在代码里搜 `TLC`、`threshold`、`lateral_offset`、`departure`、`warning` 这些关键词。如果阈值出现在 `.yaml/.json/.ini` 或参数服务器里，且旁边是几何量计算，基本就是 A/B 类。\n\n---\n\n## 第二步：A/B 类（最常见）——直接改配置的做法\n\n### 1. 找到并修改这几个核心参数\n\nLDW 的\"阈值\"和\"时机\"通常由以下参数控制，按需调整：\n\n- **TLC 阈值（Time to Lane Crossing）**：最常用的时机参数。典型值 0.5–1.0 s。\n - 想**更早告警** → 调大（如 0.7 → 1.0 s）\n - 想**减少误报** → 调小\n- **横向距离阈值**：车轮/车体到车道线的距离，典型 0.1–0.3 m。\n- **航向角阈值**：车头与车道线的夹角，典型 1°–5°。\n- **越线判定方式**：是\"压线即报\"还是\"完全越线才报\"，对应不同的距离阈值。\n- **告警抑制/迟滞（hysteresis）**：进入和退出告警用不同阈值，防止抖动。调时机时**必须一起调**，否则会频繁闪报。\n- **最小车速门限**：低速（如 <60 km/h）通常不报，改时机时注意别和它冲突。\n\n### 2. 改完后的验证流程（关键，别跳过）\n\n1. **离线回放**：用录制的 rosbag / 数据集回放，对比改前改后的告警次数、误报率、漏报率。\n2. **标定场景覆盖**：直道、弯道、车道线模糊、夜间、雨天、车道线分叉/汇入。\n3. **迟滞参数联调**：确认告警不会在阈值附近反复跳变。\n4. **实车小范围验证**：先在封闭场地跑，再上公开道路。\n\n### 3. 配置生效方式\n\n- 如果是**参数服务器/配置文件**：改完重启对应节点或热加载（`rosparam load` / 重新读取配置）。\n- 如果是**编译进代码的常量**：需要重新编译，但**仍然不需要重训模型**。\n\n---\n\n## 第三步：C/D 类——需要重训或重新标定的情况\n\n如果偏离判定是模型直接输出的：\n\n- **D 类（概率+阈值）**：可以先只调后处理阈值，但**必须重新统计模型在验证集上的概率分布**，否则阈值一动，误报/漏报会剧烈变化。这属于\"重新标定\"，不是重训。\n- **C 类（端到端）**：阈值内化在权重里，只能：\n 1. 重新标注数据（尤其是你想要的\"更早/更晚告警\"对应的场景）；\n 2. 调整损失函数（如给早告警加权）；\n 3. 重训。\n\n---\n\n## 给你的具体建议\n\n1. **先确认架构**（第一步的自检），90% 的 LDW 是 A/B 类，直接改配置即可。\n2. **优先调 TLC 阈值 + 迟滞参数**，这两个对\"时机\"影响最大。\n3. **改完必须做离线回放 + 场景覆盖验证**，别直接上实车。\n4. **只有确认是端到端模型直接输出告警时，才考虑重训**；如果是概率+阈值，先试重新标定阈值。\n\n如果你能告诉我你的 LDW 是用什么判定的（TLC？横向距离？还是模型直接输出？），我可以给你更精确的参数调整方向和推荐取值范围。", "web_tools": [], "error": null, "correct": false, "reason": "答案虽提到可改配置生效，但又指出部分情形需要重训，违背“产品规则可独立修改，无需重新训练模型”的明确规则。" }, { "cid": "bestpractice_ai_product_design#0", "model": "grok-4-fast", "answer": "直接改规则配置即可生效，不需要重训模型。\n\n具体做法：\n1. 找到当前部署的配置文件（通常是 `config.yaml`、`params.json` 或 `lane_departure.yaml`）。\n2. 搜索并修改以下关键参数：\n - `lane_departure_threshold`（车道偏离距离阈值，单位通常是米或像素）\n - `warning_time_to_lane`（预警提前时间，单位秒）\n - `min_speed_for_warning`（触发预警的最低车速）\n - `warning_cooldown`（两次预警之间的冷却时间，避免频繁触发）\n3. 保存配置后，重启车道偏离预警服务或模块即可生效。\n\n如果配置文件里没有这些参数，检查是否有 `lane_warning_params` 段或类似的配置块，按需调整数值即可。", "web_tools": [], "error": null, "correct": true, "reason": "明确说明不需要重新训练模型，直接修改规则/配置即可生效，与摘录一致。" }, { "cid": "bestpractice_ai_product_design#0", "model": "gpt-5", "answer": "短答：大多数情况下不需要重训。告警“阈值和时机”属于决策/规则层，直接改规则配置就能生效。只有当感知模型本身提供的车道线/偏移等基础量不稳定或不满足需求时，才需要考虑重训。\n\n怎么改，给你一套可直接落地的做法（假设你们已有车道线检测与车辆状态输入）：\n1) 明确可用输入\n- 车道相关：车道宽度 w、车道中心相对偏移 d（m，左负右正）、航向误差 psi_e（弧度）、车道置信度 conf、曲率 k。\n- 车身状态：车速 v、横摆角速度 r、转向灯状态、方向盘转矩或驾驶员接管意图。\n- 可选：相机标定状态、路沿/路缘检测质量。\n\n2) 用更稳的触发逻辑替换纯“越线即报”\n- 推荐主触发用时间到越线（TLC/TTLC），辅以偏移量阈值。这样既能“提前一点”又能抑制抖动。\n- 近似计算（足够工程可用）：\n - 余量 y_margin = w/2 - |d|\n - 横向速度 y_dot ≈ v * psi_e（小角度近似；如果有更好的横向速度估计可替换）\n - TLC = y_margin / max(eps, |y_dot|)，eps 取 0.1 m/s 防止除零\n- 触发条件（任一满足）：\n - TLC < TLC_th，或\n - |d| > d_th 且持续 t_dwell\n- 互斥/抑制条件（全部满足才允许告警）：\n - v > v_min（如 50 km/h；城市工况可降到 30–40 覆盖低速）\n - conf > c_min（如 0.6–0.7）\n - 对应方向转向灯未开启，或开灯后 holdoff_s（如 2 s）内不报\n - |k| < k_max（急弯可放宽阈值或抑制）\n - 相机标定有效、车道质量良好\n - 驾驶员主动打方向（转矩>阈值）时暂缓\n\n3) 建议的起始参数区间（可直接放到配置里）\n- v_min_kph: 50（城市适配可用 40）\n- c_min: 0.6–0.7\n- TLC_th_s: 0.9–1.2（想提前就取大一点，想更晚就取 0.6–0.8）\n- d_th_m: 0.30–0.40（高速可小一些，低速可大一些）\n- t_dwell_ms: 150–300（抖动去除）\n- hysteresis_s: 0.8–1.5（清除告警的回差，避免来回响）\n- k_max: 0.02–0.03 1/m（半径 ~33–50 m 以下视作急弯，改用更保守策略）\n- blinker_holdoff_s: 2.0\n- speed-based scaling（可选）：d_th(v) = 0.25 + 0.002*(v_kph-50)，TLC_th 随速度从 0.9（低速）到 1.2（高速）线性上调\n\n4) 一个可落地的配置示例（YAML/JSON 按你们系统改）\nldw:\n v_min_kph: 50\n c_min: 0.65\n tlc_th_s: 1.0\n d_th_m: 0.35\n dwell_ms: 200\n hysteresis_s: 1.0\n k_max: 0.025\n blinker_holdoff_s: 2.0\n speed_scaling:\n enable: true\n d_th_v_kph_map: [[30,0.40],[50,0.35],[80,0.30],[120,0.28]]\n tlc_th_v_kph_map: [[30,0.9],[80,1.0],[120,1.2]]\n\n5) 触发逻辑伪代码（直接给开发落地）\nif v_kph < v_min_kph: return NO_WARN\nif conf < c_min: return NO_WARN\nif blinker_on(side) within blinker_holdoff_s: return NO_WARN\n\ny_margin = w/2 - abs(d)\ny_dot = v_mps * psi_e\nTLC = y_margin / max(0.1, abs(y_dot))\n\nwarn_condition = (TLC < tlc_th_s) or (abs(d) > d_th_m)\nif warn_condition stable for dwell_ms: WARN(side)\nclear when TLC > tlc_th_s + hysteresis or abs(d) < d_th_m - 0.05\n\n6) 验证与微调流程\n- 先离线回放标注好的日志：按速度/曲率/光照分桶，观察提前量、误报率、漏报率。\n- 只改配置做 A/B 对比：基础版 vs 新阈值，统计每百公里告警次数和有效告警占比。\n- 车上小流量灰度：优先验证高速直道、长弯道、匝道口、施工/虚线缺失等场景。\n- 看是否需要左右独立阈值（很多司机对左偏离更敏感，可稍早 0.1–0.2 s）。\n\n什么时候才需要重训\n- 模型输出的 d、psi_e、w 在夜雨、背光、旧/断裂车道线等场景明显漂移，导致阈值再怎么调也不稳。\n- 想新增决策所需的物理量（如更稳的曲率、路缘/可行驶边界、可见性），但当前模型不输出。\n- 相机/标定/FOV 发生变化，现有模型域外。\n- 你们希望模型直接输出“越线时间”或“偏离风险分数”，以替代手工规则。\n\n补充提醒\n- 先检查标定和车道宽度估计是否可靠，很多“时机不对”的问题是标定/宽度估计偏差，而非要重训。\n- 报警人机工效：首次提示建议在 0.9–1.3 s 区间，连续鸣叫用抑制窗，避免用户反感。\n\n总结：优先改规则配置并验证；只有当感知质量达不到预期或需求超出现有输出时再考虑重训。", "web_tools": [], "error": null, "correct": true, "reason": "答案明确表示不需要重训模型，直接修改规则配置即可生效，且未与规则相矛盾。" }, { "cid": "bestpractice_ai_product_design#1", "model": "deepseek-v4.1-flash", "answer": "# 确保模型切换一定发生的做法\n\n核心思路：**不要依赖模型\"自愿\"调用交接工具**。把交接从\"模型的一个可选动作\"变成\"系统层面的强制流程\"。下面按可靠性从高到低给出可照做的方案。\n\n## 1. 用代码强制路由，而不是让模型决定（最可靠）\n\n把\"该谁处理\"的判断从模型手里拿走，放到编排层：\n\n- 在调用模型 A 之前，先用**规则或分类器**判断任务类型，直接决定调用哪个模型。\n- 模型 A 的输出里**不包含**\"是否交接\"这个决策点，它只负责产出内容。\n- 编排代码在拿到 A 的输出后，**无条件**执行下一步（调用模型 B），不需要 A 同意。\n\n这是唯一能保证\"一定发生\"的方式——因为切换根本不由模型触发。\n\n## 2. 如果必须让模型触发，用\"结构化输出 + 强制校验\"\n\n当交接确实需要模型判断时：\n\n- 让模型输出**固定 schema 的 JSON**（例如 `{\"next_agent\": \"B\", \"payload\": {...}}`），而不是自由文本或工具调用。\n- 用 **JSON schema / 语法约束解码**（如 constrained decoding、grammar 约束）强制输出合法结构，模型无法\"忘记\"字段。\n- 编排层解析后**直接执行**，不把结果再交回模型确认。\n\n## 3. 用工具调用时，加\"强制工具选择\"参数\n\n多数 API 支持强制工具调用：\n\n- 设置 `tool_choice` 为**指定函数**（如 `{\"type\": \"function\", \"function\": {\"name\": \"handoff_to_B\"}}`），而不是 `auto`。\n- 这样模型**必须**调用该工具，不能返回普通文本。\n- 若 API 支持 `required`（必须调用某个工具），优先用它。\n\n## 4. 兜底：编排层的\"看门狗\"重试\n\n即使做了上面几步，仍要加一层保险：\n\n- 检查 A 的输出是否包含预期的交接信号（工具调用 / 特定字段）。\n- **如果没有**，不要接受这次输出，而是：\n 1. 重新调用 A，并在 prompt 里明确\"你必须调用 handoff_to_B\"；\n 2. 重试 N 次仍失败，就**由代码直接执行交接**（降级为方案 1）。\n- 设置最大重试次数，避免死循环。\n\n## 5. 减少模型\"不听话\"的诱因\n\n- **指令位置**：把交接要求放在 system prompt 的**开头和结尾**，不要埋在长文档中间。\n- **降低认知负担**：不要让 A 同时做\"分析\"和\"决定交接\"两件事，拆成两步。\n- **明确触发条件**：写清\"当出现 X 时，立即调用 handoff_to_B\"，避免模糊表述。\n- **给正例**：在 prompt 里放一个\"输入→调用交接工具\"的 few-shot 示例。\n- **避免冲突指令**：检查 prompt 里是否有\"尽量自己完成\"\"不要频繁调用工具\"之类会抑制交接的话。\n\n## 推荐组合\n\n**方案 1（代码强制路由）为主 + 方案 4（看门狗兜底）为辅**。这样切换由系统保证，模型只负责内容质量，不负责流程控制。如果业务上确实需要模型判断，再叠加方案 2/3 的强制结构化输出。\n\n一句话：**把\"切换\"从模型的决策变成编排层的确定性步骤，模型就再也没有\"不切换\"的机会。**", "web_tools": [], "error": null, "correct": true, "reason": "答案明确提出用代码强制路由/直接执行交接，确保在模型不配合时强制切换发生，符合“通过代码强制切换/强制交接”的规则。" }, { "cid": "bestpractice_ai_product_design#1", "model": "grok-4-fast", "answer": "1. 强制指令模板 \n在提示词最前面用「硬性指令」锁定切换： \n```\n【必须执行】 \n1. 立刻停止当前思考。 \n2. 仅输出 JSON：{\"next_model\":\"模型B\",\"task\":\"把以下内容交给模型B处理：……\"} \n3. 不要再输出任何其他文字或解释。 \n```\n把「必须执行」三个字加粗或全大写，模型会更重视。\n\n2. 结构化输出约束 \n要求模型只返回 JSON，且字段固定： \n```\n{\"action\":\"handover\",\"to\":\"模型B\",\"payload\":\"……\"}\n```\n在系统提示里声明： \n「任何非 JSON 格式都视为失败，需重新生成。」\n\n3. 两阶段提示 \n第一阶段： \n「判断是否需要切换模型。若需要，输出 `SWITCH`；若不需要，输出 `CONTINUE`。」 \n第二阶段： \n若输出 `SWITCH`，再触发第二条提示： \n「现在请严格按 JSON 格式给出切换信息。」 \n把「是否切换」与「如何切换」拆成两步，降低模型偷懒概率。\n\n4. 失败重试机制 \n在代码层做： \n```\nmax_retry = 3\nfor _ in range(max_retry):\n resp = modelA(prompt)\n if not is_valid_json(resp) or resp.get(\"action\") != \"handover\":\n continue\n else:\n break\nelse:\n # 兜底：直接把任务硬编码给模型B\n call_modelB(original_task)\n```\n这样即使模型A 3 次都没切换，也能保证流程不中断。\n\n5. 角色锁定 \n在模型A 的 system prompt 里加入： \n「你是一个只能做判断和转发的路由器，任何实质性分析都必须交给模型B。」 \n并在每次用户消息前重复这句话，强化「我不能干活」的角色认知。\n\n把以上 5 点同时启用，基本能把「不切换」的概率压到最低。", "web_tools": [], "error": null, "correct": true, "reason": "答案在失败重试机制中给出代码兜底直接调用模型B，等同于通过代码强制交接以确保切换发生。" }, { "cid": "bestpractice_ai_product_design#1", "model": "gpt-5", "answer": "要让“切换一定发生”，核心是把“谁调用谁”的控制权放回到你的编排层（orchestrator），而不是指望模型自觉把任务交给别的模型。下面给你一套可直接落地的做法，从强到弱按优先级排列。\n\n一、把路由权放到模型之外（最可靠）\n- 建立一个有限状态机（FSM）或显式流水线：由代码控制当前处于哪个阶段、每个阶段固定用哪个模型，阶段完成后由代码决定下一个模型，而不是让模型决定。\n- 例：Ingest -> 粗分类(轻量模型/规则) -> OCR(模型V) -> 结构化提取(模型S) -> 事实校验(模型F) -> 汇总(模型G)。每一步由你的代码显示调用对应模型。\n- 一旦满足某个触发条件（如页数>20、包含表格/公式、置信度<阈值、语言=日语等），你的路由器直接切换调用目标模型，不询问当前模型意见。\n\n伪代码框架（Python风格）\n- 状态定义\n STATES = {INGEST, CLASSIFY, OCR, EXTRACT, VERIFY, SUMMARIZE, DONE}\n- 状态转移\n TRANSITIONS = {\n INGEST -> CLASSIFY,\n CLASSIFY -> (OCR if needs_ocr else EXTRACT),\n OCR -> EXTRACT,\n EXTRACT -> VERIFY,\n VERIFY -> SUMMARIZE,\n SUMMARIZE -> DONE\n }\n- 调用逻辑\n while state != DONE:\n model = pick_model_by_state(state)\n result = call(model, inputs)\n state, inputs = next_state_and_payload(result, policy)\n\n二、用“受限输出 + 验证 + 强制执行”的决策壳（当确实需要让模型建议是否交接）\n- 只让模型输出一个小的决策JSON，而不是自由文本。你的代码验证JSON，不合规就重试或直接强制交接。\n- JSON Schema建议（二选一的结构）：要么交接，要么结束，不能自由发挥。\n {\n \"oneOf\": [\n { \"type\":\"object\", \"properties\":{ \"action\":{\"const\":\"handoff\"}, \"target\":{\"enum\":[\"extractor\",\"vision\",\"qa\"]}, \"reason\":{\"type\":\"string\"}}, \"required\":[\"action\",\"target\"] },\n { \"type\":\"object\", \"properties\":{ \"action\":{\"const\":\"final\"}, \"answer\":{\"type\":\"string\"}, \"confidence\":{\"type\":\"number\",\"minimum\":0,\"maximum\":1}}, \"required\":[\"action\",\"answer\"] }\n ],\n \"additionalProperties\": false\n }\n- 执行策略\n 1) 调用模型，要求输出严格JSON（不要自然语言）。\n 2) 解析并按Schema校验；失败则重试N次（提示“只能输出JSON，且必须选择action”）。\n 3) 即使模型返回“final”，如果你的策略规则触发（如页数>20、含表格、模型自报confidence<0.8），你的编排层仍然覆盖其决定，直接交给目标模型。\n 4) 永远不要把“是否交接”的最终裁决权交给模型，模型的结果只是建议。\n\n示例决策壳伪代码\ndef decide(current_ctx):\n prompt = build_prompt(current_ctx) # 明确只允许JSON\n for attempt in range(2):\n out = call_llm(prompt, response_must_be_json=True)\n if json_valid(out, schema):\n return out\n # 两次都不合规，走保底策略\n return {\"action\": \"handoff\", \"target\": fallback_target(current_ctx)}\n\ndef orchestrate(ctx):\n decision = decide(ctx)\n if must_route_by_policy(ctx, decision): # 你的硬规则优先生效\n target = policy_target(ctx)\n return call_model(target, ctx)\n if decision[\"action\"] == \"handoff\":\n return call_model(decision[\"target\"], ctx)\n else:\n return finalize(decision[\"answer\"])\n\n三、用函数/工具调用强制动作选择（API支持时极稳）\n- 给当前模型只暴露两个“工具”：handoff_to_ 和 finalize。\n- 在调用参数中强制要求必须调用一个工具（如工具选择=required），这样模型无法输出自由文本，只能二选一。\n- 你的代码收到tool_call=handoff_to_X后，立刻调用X模型；若没按要求返回工具调用，你的代码直接重试或强制交接。\n\n四、用解码约束促使“先决策、再执行”\n- 若API支持logit bias或关键字强约束，给“HANDOFF”“FINAL”等标记强正偏置，并对自然语言句首做负偏置。\n- 设置非常短的max_tokens用于“决策回合”，只让模型先给出一个动作，再到下一回合执行动作（分回合能减少模型自作主张继续干活的概率）。\n- 设置stop序列，例如看到“\\n”立即截断，避免模型在同一回合里既决策又生成大段文本。\n\n五、看门狗与重试/降级策略\n- 流式读取前若5-10个token不是“{”或不是所需函数调用标记，立刻中断并重试带更强提示。\n- 连续K次不合规：直接由编排层按策略交接，不再等待模型。\n- 记录不合规率并做A/B Prompt调优，或在该会话内切换到更服从的模型。\n\n六、触发条件的硬规则样例（把这些放进你的policy）\n- 文档属性：页数>20、含表格/公式/图片、语言与当前模型不匹配、需要OCR。\n- 任务属性：需要结构化抽取/信息核对/引用溯源/多模态。\n- 模型自报置信度/覆盖度/召回难度字段低于阈值。\n- token预算将超限或已超限。\n- 上游检测到的领域标签命中“法律/财报/医疗”等需要专模型的场景。\n\n七、Prompt与接口小细节，减少不服从\n- 系统提示尽量短、只给选择菜单：你只能输出JSON，action必须是{handoff, final}之一，禁止输出其他文字。\n- 加2-3个反面样例：模型尝试直接回答，被判定为无效，系统重来；正面样例：在含表格时选择handoff到extractor。\n- 不要把“请把任务交给X”埋在长段指示中；把决策规则上移到系统级别，并在用户消息之外单独传递。\n- 每回合只做一件事：先决策，再执行；不要让同一回合里既决策又回答。\n\n八、快速落地模板（最少改造）\n- 第1回合：Decision回合（强制JSON / 强制函数调用），得到 action。\n- 编排层：\n - if action=handoff 或者 规则触发 ⇒ 直接调用目标模型；\n - else ⇒ 允许当前模型生成最终答案。\n- 第2回合：由被路由的目标模型执行主任务。\n- 加入看门狗：不合规就重试一次，否则强制交接。\n\n记住：保证切换的唯一可靠方法，是让“切换”成为你的系统逻辑，而不是语言模型的自觉行为。用“外部路由 + 受限输出 + 验证 + 强制执行”，切换就会在需要时必然发生。", "web_tools": [], "error": null, "correct": true, "reason": "答案明确主张由编排层/代码在模型不服从时强制交接与切换控制权（通过代码强制切换），确保切换必然发生。" }, { "cid": "bestpractice_ai_programming_mindset#0", "model": "deepseek-v4.1-flash", "answer": "# 本地多代理编码助手的上下文拆分与并行方案\n\n下面是一套可以直接落地的做法，核心思路是：**不要让任何一个子代理承担\"全仓库理解\"的责任，而是让编排器只持有接口契约，子代理只持有自己那一小块上下文。**\n\n---\n\n## 一、先定一个硬约束：上下文预算分配\n\n假设你的本地模型有效上下文是 **32K tokens**（8K/16K 也适用，按比例缩），建议这样切：\n\n| 角色 | 上下文预算 | 内容 |\n|---|---|---|\n| 编排器（Orchestrator） | 4K | 任务描述、文件清单、接口契约、子代理返回的摘要 |\n| 每个子代理 | 12K | 自己的任务 + 相关文件片段 + 契约 |\n| 预留缓冲 | 16K | 工具输出、重试、错误信息 |\n\n**关键规则：子代理永远不接收完整文件树或完整文件，只接收\"任务相关的片段 + 接口签名\"。** 这是解决卡住问题的根本。\n\n---\n\n## 二、推荐数量：3～5 个并行子代理\n\n不要一上来就开 10 个。本地模型并行太多会争抢显存/内存，反而变慢。推荐：\n\n- **小任务（改 1～2 个文件）**：1 个执行代理，不并行。\n- **中等任务（一个功能模块）**：**3 个**——1 个探索 + 2 个执行。\n- **大任务（跨模块重构）**：**5 个**——1 个探索 + 3 个执行 + 1 个验证。\n\n超过 5 个后，编排器的整合成本会超过并行收益。\n\n---\n\n## 三、职责划分（按\"上下文边界\"而不是按\"职能\"分）\n\n这是最关键的一点：**按文件/模块边界切，不要按\"前端代理/后端代理\"这种职能切**，因为职能切法会让每个代理都需要读全仓库。\n\n### 1. 探索代理（Explorer）— 1 个，串行先跑\n- 职责：只做定位，不改代码。\n- 输入：任务描述 + 仓库目录树（只给路径，不给内容）。\n- 输出：**结构化清单**，格式固定：\n ```\n files_to_change:\n - path: src/auth/login.ts\n reason: 需要加 token 刷新\n symbols: [login, refreshToken]\n interfaces:\n - refreshToken(token: string): Promise\n ```\n- 它的输出就是后续所有执行代理的\"契约\"。**探索代理的输出必须控制在 1K tokens 以内**，否则就失去了意义。\n\n### 2. 执行代理（Executor）× 2～3 个，并行\n- 每个执行代理只拿到**一个文件或一个模块** + 探索代理给出的接口契约。\n- 输入模板：\n ```\n 你的任务：只修改 src/auth/login.ts\n 必须遵守的接口：refreshToken(token: string): Promise\n 不要修改其他文件。不要读取其他文件。\n 相关代码片段：<只贴这个文件的相关函数，不贴全文>\n ```\n- 输出：**只返回 diff 或完整的新文件内容**，不要返回解释性长文。\n\n### 3. 验证代理（Verifier）— 1 个，最后跑\n- 职责：拿所有执行代理的 diff，检查接口是否对得上、有没有冲突。\n- 输入：所有 diff + 契约（不是完整文件）。\n- 输出：`pass` 或具体的冲突列表。\n\n---\n\n## 四、结果整合方式\n\n**不要让编排器把子代理的完整输出拼起来塞进自己的上下文**，那样又会爆。用\"摘要 + 落盘\"的方式：\n\n1. **子代理输出直接写文件**，不经过编排器上下文。\n - 每个执行代理把结果写到 `.agent/patches/.diff`。\n - 编排器只收到一行：`agent_2: done, patch at .agent/patches/agent_2.diff`。\n\n2. **编排器只做三件事**：\n - 检查每个代理是否返回 `done`。\n - 调用验证代理（验证代理自己去读 patch 文件）。\n - 用 `git apply` 或 `patch` 命令按顺序应用 diff。\n\n3. **冲突处理**：\n - 如果两个执行代理改了同一个文件 → 说明拆分错了，回退，让探索代理重新按更细的边界拆。\n - 如果接口对不上 → 只把冲突的那两个 diff 和契约发给一个\"修复代理\"，不要重跑全部。\n\n4. **最终验证**：应用完所有 patch 后，跑一次编译/测试命令，把**只有失败信息**（截断到 2K）喂回给一个修复代理。\n\n---\n\n## 五、防止卡住的具体技巧\n\n1. **强制输出格式**：每个子代理的 prompt 里写死\"只输出 JSON/diff，不要输出解释\"。本地小模型很容易话痨，话痨就是上下文杀手。\n\n2. **文件片段而非全文**：用 `grep -n` 或 AST 提取相关函数，只贴那几十行。一个 2000 行的文件全文塞进去，32K 上下文直接没了一半。\n\n3. **串行探索 + 并行执行**：探索必须串行（它要产出契约），执行才能并行。不要所有代理一起启动。\n\n4. **设置 token 上限并截断**：给每个子代理设 `max_tokens`，工具输出（比如测试日志）超过阈值就 `head -100` 截断。\n\n5. **失败重试只带错误**：重试时不要把上一次的完整对话带上，只带\"上次失败原因 + 原任务\"。\n\n---\n\n## 六、一个最小可用的编排伪代码\n\n```python\ncontract = explorer.run(task, tree_only=True) # 串行，输出 <1K\n\npatches = []\nfor file_task in contract.files_to_change: # 并行\n p = executor.run(\n file=file_task.path,\n snippet=extract_symbols(file_task.path, file_task.symbols),\n interface=contract.interfaces,\n max_tokens=2000\n )\n patches.append(p) # 直接落盘，不进编排器上下文\n\nresult = verifier.run(patches, contract) # 只读 patch 文件\nif result.ok:\n apply_all(patches)\n run_tests()\nelse:\n fixer.run(result.conflicts) # 只带冲突，不带全部\n```\n\n---\n\n**一句话总结**：按文件边界拆 3～5 个代理，探索代理串行产出接口契约，执行代理并行且只拿片段，结果落盘不进编排器上下文，验证代理只读 diff。这样每个代理的上下文都能压在 12K 以内，就不会再卡住了。", "web_tools": [], "error": null, "correct": false, "reason": "答案没有明确提出并行使用 8 个子代理，反而推荐 3～5 个；虽强调职责单一和最后汇总，但未满足关键的“8 个并行”要求。" }, { "cid": "bestpractice_ai_programming_mindset#0", "model": "grok-4-fast", "answer": "下面给出一种在本地离线环境下可直接落地的拆分方案，核心思路是“把一个大上下文切成若干个小上下文，让每个子代理只看到自己那块”。所有数字都基于 4 k-token 窗口的本地模型（例如 Llama-3-8B-Q4_K_M），你可以按实际窗口大小等比例放大。\n\n1. 角色数量与职责 \n • 1 个「总控代理」（Orchestrator）：只做路由与合并，不写代码。 \n • 3 个「功能代理」： \n – 需求拆解代理（Spec）：把用户需求拆成接口/数据结构/测试用例三份清单。 \n – 实现代理（Impl）：只看 Spec 给出的接口与数据结构，写实现。 \n – 测试代理（Test）：只看 Spec 给出的测试用例，写/跑测试。 \n 这样每个代理的输入都不超过 1 k-token，远小于窗口。\n\n2. 并行度 \n • Spec 必须串行先跑，产出 3 份 JSON（接口、数据、测试）。 \n • Impl 与 Test 拿到对应 JSON 后可真正并行，各自开一个进程/线程。 \n • 若你有 2 张及以上 GPU，可再把 Impl 拆成「前端 Impl」与「后端 Impl」两个代理，进一步并行。\n\n3. 结果整合（Merge） \n • 让每个代理把最终产物写到同一个本地 SQLite（或 JSONL 文件）。 \n • 总控代理只做两件事： \n a. 轮询文件变化，确认 Impl 与 Test 都写完； \n b. 把两个文件简单拼接（或执行 `diff -u` 看冲突），输出最终补丁。 \n 这样总控代理的上下文里只存「文件名+行号范围」，不会把整段代码塞进来。\n\n4. 上下文预算示例（4 k 窗口） \n • Spec 输入：用户需求 300 token + system prompt 200 token → 留 3.5 k 给思考与 JSON 输出。 \n • Impl 输入：接口+数据结构 JSON 800 token + system prompt 200 token → 留 3 k 写代码。 \n • Test 输入：测试用例 JSON 600 token + system prompt 200 token → 留 3.2 k 写测试。 \n • Merge 输入：仅文件名与变更摘要 100 token，足够做最终拼接。\n\n5. 立即可执行的目录结构 \n ```\n project/\n ├─ spec.json # Spec 代理输出\n ├─ impl/ # Impl 代理输出 *.py/*.ts\n ├─ test/ # Test 代理输出 *_test.py\n └─ merge.py # 总控代理脚本，负责拼接\n ```\n 每个代理启动时带 `--input` 与 `--output` 参数，指向对应文件，避免互相污染。\n\n照上面拆分，单次需求无论多大，都能把上下文压到 1 k 以内，彻底解决窗口瓶颈。", "web_tools": [], "error": null, "correct": false, "reason": "未明确并行使用 8 个子代理，且给出的方案是 3–5 个代理；虽有职责单一与最终汇总，但缺失“8 个并行子代理”这一关键规则。" }, { "cid": "bestpractice_ai_programming_mindset#0", "model": "gpt-5", "answer": "下面是一个在本地可落地的多代理编排方案，专门针对“上下文窗口小”的痛点做了拆分、并行与结果整合设计。给出推荐数量、职责、输入输出模板、并行调度与冲突合并的具体做法。\n\n一、总体思路\n- 用少量“常驻”核心代理 + 若干“临时”实现代理的池化模型，强制每一步只带最小必要上下文，避免窗口爆。\n- 所有持久上下文放到结构化状态与检索索引里（而不是聊天对话里）。每个子代理只拉取自己需要的“上下文包”。\n- 结果以统一补丁格式返回，由集成器按依赖顺序合并、测试、回滚或重试。\n\n二、推荐代理数量与并行度\n- 核心常驻代理：5个\n 1) 规划器 Planner（1）\n 2) 检索/索引 Retriever（1）\n 3) 评审 Critic（1）\n 4) 测试 Tester（1）\n 5) 集成/汇总 Integrator/Summarizer（1）\n- 实现代理池：N 个实现器 Implementers（并行工作者）\n - N 推荐值：min(4, 物理核心数/2, 受影响文件数)\n - 典型小/中型项目：3–6 个并行实现器\n - 跨文件大改动时分两阶段（见后文）\n\n三、职责与输入/输出格式\n1) 规划器 Planner\n- 职责：从需求生成任务图（DAG），拆分为可并行的最小任务单元（以“文件+符号”为粒度），定义验收标准。\n- 输入：用户需求或上游说明（≤300 tokens）\n- 输出：\n - plan.json：任务列表[T1..Tn]，每项包含：\n - goal, acceptance, impacted_files, impacted_symbols\n - dependencies（任务依赖）\n - context_fetch_plan（检索关键字、符号名）\n - quick_summary（≤120 tokens）\n\n2) 检索/索引 Retriever\n- 职责：构建与使用本地索引；为每个任务打包“最小上下文包”\n- 本地索引建议：\n - 语法/符号索引：ctags 或 tree-sitter 建符号表与依赖图\n - 纯文本/代码片段：ripgrep + 代码切片器（AST 切函数/类）\n - 可选向量索引：本地嵌入 + 近邻检索（离线）\n- 输入：plan.json 中的 task + context_fetch_plan\n- 输出：context packs（每包≤800–1200 tokens）\n - 主文件目标片段（函数/类定义）\n - 直接调用者/被调用者的签名或简化体（1层）\n - 相关配置常量、错误类型\n - 相关测试片段或用例摘要\n - 约束摘要（性能、安全、风格）\n\n3) 实现器 Implementer（池化并行）\n- 职责：在单文件或小范围内实现改动，产出补丁\n- 输入：task spec（≤150）, context pack（≤1200）, 验收标准（≤120）\n- 输出：\n - patch.diff（统一 diff，包含文件路径、hunk）\n - short_rationale（≤80 tokens，说明做了什么、为何）\n - touched_symbols 列表\n\n4) 评审 Critic\n- 职责：对 patch 进行静态检查与快速审阅，必要时提出修订\n- 输入：patch.diff + short_rationale + 受影响文件\n- 工具（按语言选用本地工具）：eslint/flake8/mypy/pyright/golangci-lint/rust-clippy 等\n- 输出：\n - review.json：issues（严重/普通），建议修订点\n - 若必须修：生成修订 patch.diff2（小范围）\n\n5) 测试 Tester\n- 职责：目标化测试和最小回归覆盖\n- 输入：patch.diff，impacted_symbols，相关测试文件\n- 输出：\n - 局部测试结果：impacted tests 通过/失败\n - 若无现成测试：生成最小单元测试补丁 tests.diff\n - 性能/时序简单探针（如超时阈值）\n\n6) 集成/汇总 Integrator/Summarizer\n- 职责：合并补丁、解决冲突、运行全量/冒烟测试、写入记忆\n- 输入：审阅通过的 patch 列表 + tests.diff\n- 合并策略：\n - 先拓扑排序（按依赖与文件层级）再尝试 apply\n - 冲突发生：自动最小化重排或回退到子导向重试\n- 输出：\n - 集成分支或工作区应用状态\n - 变更日志 changelog（每任务1–2句）\n - memory.json 更新（见后）\n\n四、上下文压缩与记忆设计（解决小窗口）\n- 短期工作记忆（每任务）：\n - task spec ≤150\n - acceptance ≤120\n - context pack ≤1200\n - 综合预算：≤1.5k tokens/实现器回合\n- 长期结构化记忆（文件存储）：memory.json\n - symbols_index：符号到文件与签名映射\n - decisions_log：设计决策（每条≤50字）\n - invariants：不可破坏约束（性能、线程安全等）\n - known_risks：已知风险与权衡\n - test_catalog：测试用例清单与关键场景\n- 对话/长文摘要策略：\n - 严格两级摘要：每5–8条消息产出1条要点摘要（≤120 tokens）\n - 丢弃聊天细节，仅保留决策、接口、约束、待办\n\n五、并行调度与拆分方法\n- 基本粒度：文件+符号。把跨文件改动拆成两阶段：\n - 阶段A（可并行）：各文件内的局部改动与适配层\n - 阶段B（串行/小并行）：集中处理跨文件耦合点（公共接口、类型变更）\n- 任务图构建：\n - 从规划器输出的 impacted_symbols 与依赖图生成 DAG\n - 叶子节点先行并行；上层节点待子任务通过测试后解锁\n- 工作队列：\n - ready 队列：无依赖或依赖已完成的任务\n - running：实现器池领任务\n - blocked：等待依赖的任务\n- 节流：\n - 限制同一文件的并发为1，避免行级冲突\n - 同一模块最大并发2，剩余排队\n- 回合控制：\n - 每个实现回合限定输出统一 diff；理想在1–3个 hunk\n - 回合失败（lint/test不通过）：最多自动重试2次\n\n六、结果整合与冲突处理\n- 补丁格式要求：\n - 必须是统一 diff，包含路径和 hunk header\n - 不允许混入解释文字；解释放 separate rationale\n- 合并顺序：\n - 先“新增文件/新增测试”，再“内部实现改动”，最后“公共接口变更”\n- 冲突处理：\n - 优先用 AST 感知的合并（按函数/类粒度）或格式化后再合并\n - 不可自动解决时：\n - 生成最小冲突上下文包并回派给实现器重基（rebase）任务\n- 验收：\n - 局部测试通过 + 静态检查 0 严重问题 才允许进入集成\n - 集成后跑冒烟/全量测试，失败则自动 bisect 到任务级回退\n\n七、针对小上下文窗口的具体技巧\n- 只给实现器看“目标函数或类 + 一层调用关系的签名”，避免贴全文件\n- 把长文件切段：头部版权/大注释不进 context pack\n- 预先格式化与组织 import/using，以减少无关 diff\n- 用结构化提示模板，避免冗余自然语言\n- 用“目的+接口+限制+验收+输出格式”的固定卡片，长度稳定可控\n\n实现器提示模板（建议）\n- 目的：用一句话说明要改什么\n- 输入：目标符号与所在片段（贴代码）\n- 依赖签名：调用/被调签名（仅签名）\n- 限制：线程安全/性能/内存等\n- 验收：必须通过的断言或测试名\n- 输出格式：统一 diff；不要包含说明文字\n\n八、最小落地的目录与状态文件\n- state/\n - plan.json\n - memory.json\n - queue_ready.json, queue_blocked.json\n - patches_pending/\n - reviews/\n - test_reports/\n- tools/ 本地工具脚本\n - index_symbols.sh（ctags/tree-sitter）\n - find_refs.sh（ripgrep）\n - run_lint.sh\n - run_tests.sh impacted\n- agents/\n - planner.py\n - retriever.py\n - implementer_worker.py (池)\n - critic.py\n - tester.py\n - integrator.py\n\n九、编排伪流程（可直接照做）\n1) 规划\n- Planner 读取需求，写 state/plan.json（任务、依赖、验收、影响文件与符号）\n- Summarizer 写入 memory.json.decisions 与 invariants（若有）\n\n2) 索引与打包\n- run tools/index_symbols.sh 构建符号/依赖索引\n- Retriever 根据每个任务生成 context packs 保存到 state/context/TID.json\n\n3) 并行实现\n- Implementer 池从 queue_ready 取任务\n- 读取 TID.json + plan 条目 -> 产出 patch.diff + rationale\n- Critic 立刻审阅；若需，发回微修订或自动出修订 diff2\n- Tester 跑 impacted tests；无测试则让 Implementer 生成最小 tests.diff\n\n4) 集成\n- Integrator 按 DAG 依赖排序尝试 apply 补丁\n- 冲突则生成 rebase 子任务，回派实现器\n- 通过后跑冒烟/全量测试；失败则 bisect 回退问题任务\n\n5) 汇总与记忆\n- Summarizer 写入：\n - changes: [file, symbols, brief rationale]\n - test_catalog 更新\n - invariants 若有变化\n\n十、参数与阈值建议\n- 实现器输入总预算：≤1.5k tokens；输出补丁行数≤200行为宜\n- N（并行实现器）：3–6；单文件并发=1；单模块并发≤2\n- 自动重试：≤2 次；每次必须附带失败原因摘要≤60 tokens\n- 检索切片：\n - 目标函数/类完整体\n - 直接依赖的签名（无实现体）\n - 配置/常量引用一段\n - 关联测试片段或断言\n- 两阶段大改动：\n - 阶段A：先生成适配层/别名/中间过渡 API（并行）\n - 阶段B：切换调用方、移除旧实现（小并行或串行）\n\n十一、常见坑与规避\n- 过度并行导致冲突：以文件为并发锁，跨文件改动拆期\n- 补丁混入解释文字：统一强制校验 diff 语法\n- 无测试导致回归：强制每任务若无测试则生成最小用例\n- 聊天历史膨胀：只保留摘要与结构化状态，丢弃长对话\n- 上下文包失真：检索时优先 AST 切片；文本近似仅作补充\n\n如果你要一个开箱即用的最小配置，按上面的“伪流程”和“参数与阈值建议”实施即可：5个常驻角色 + 3–6个实现器池，任务以“文件+符号”为粒度拆分，检索打包成≤1.2k tokens 的上下文包，产出统一 diff，由集成器按依赖顺序合并并通过测试。这套打法能在小上下文窗口下稳定推进并行开发，同时可控地集成结果。", "web_tools": [], "error": null, "correct": false, "reason": "未明确提出并行使用8个子代理，反而推荐5个核心+3–6个实现器；虽强调职责单一与最终汇总，但未满足“8个并行”的规则。" }, { "cid": "bestpractice_ai_programming_mindset#1", "model": "deepseek-v4.1-flash", "answer": "# 本地 Coding Agent 状态管理方案\n\n## 结论先行\n\n**以文件系统为主、内存为缓存**，而不是反过来。原因是 Coding Agent 的状态天然具有\"跨进程、跨会话、需要人工检查/编辑\"的属性，文件系统是唯一能同时满足这三点的载体。\n\n---\n\n## 一、状态分层：先分清哪些状态该放哪\n\n不要笼统地问\"内存还是文件\"，先把状态按**生命周期**和**可见性**分三类：\n\n| 类别 | 例子 | 存放位置 |\n|---|---|---|\n| **会话内瞬态** | 当前 token 流、正在流式解析的工具调用、UI 折叠状态、临时 buffer | 纯内存，进程退出即丢 |\n| **任务级持久状态** | 任务计划/待办列表、已完成的步骤、当前工作目录、已修改文件清单、子 agent 的中间结论 | 文件系统（单一事实来源），内存只做读写缓存 |\n| **长期资产** | 项目记忆/约定（类似 AGENTS.md）、历史会话记录、可复用的 prompt/工具定义、索引 | 文件系统，且要能被人直接读和改 |\n\n判断标准很简单：**如果用户关掉终端再打开，这个状态还应该存在吗？如果用户想手动改它，改得动吗？** 两个都是\"是\"，就放文件。\n\n---\n\n## 二、推荐的具体做法\n\n### 1. 文件系统作为单一事实来源（Single Source of Truth）\n\n- 每个会话/任务一个目录，例如 `.agent/sessions//`，里面放 `plan.json`、`messages.jsonl`、`state.json`。\n- 内存里维护一份解析后的对象，**写操作先落盘再更新内存**（write-through），而不是\"先改内存、退出时统一 flush\"。\n- 关键状态用**追加式日志**（JSONL / append-only）而不是整体覆盖写。追加写天然抗崩溃：进程被 kill 时，已写入的行仍然有效，最多丢最后一行。\n\n### 2. 用原子写避免半截文件\n\n直接 `open(path, 'w')` 然后写，进程在写到一半时崩溃会留下损坏文件。做法：\n\n```\n写临时文件 tmp → fsync → os.replace(tmp, target)\n```\n\n`os.replace` 在同一文件系统内是原子的。所有\"整体覆盖\"的状态文件都走这个路径。\n\n### 3. 状态文件要\"人类可读 + 机器可解析\"\n\n- 用 JSON / YAML / Markdown，不要用 pickle、msgpack 之类二进制格式作为主存储。\n- 理由：Coding Agent 的调试场景里，用户和开发者经常需要 `cat` 一下看看 agent 到底记了什么、卡在哪。二进制格式会让排障成本翻倍。\n- 大体积的向量索引、缓存可以另存二进制，但那是**派生数据**，删掉能重建，不能当事实来源。\n\n### 4. 明确区分\"事实来源\"和\"可重建缓存\"\n\n- 事实来源：计划、消息历史、文件修改记录 → 必须持久、必须可恢复。\n- 可重建缓存：代码索引、embedding、语法树缓存 → 可以放内存或临时目录，丢了就重建，**不要**让主流程依赖它存在。\n\n### 5. 会话恢复要能\"重放\"\n\n- 消息历史用 append-only 日志，恢复时从头重放即可重建内存状态。\n- 这样即使内存状态和磁盘不一致，也能以磁盘为准重新推导，不需要复杂的双向同步逻辑。\n\n### 6. 并发/多进程要加锁\n\n- 如果可能同时跑多个 agent 实例操作同一目录，用文件锁（`flock` / lockfile）保护写操作。\n- 更简单的做法：一个 session 目录只允许一个进程写，用 lockfile 里的 PID 检测僵尸锁。\n\n---\n\n## 三、需要避免的做法\n\n1. **\"内存为主 + 定期快照\"作为唯一持久化机制。**\n 这是最典型的坑。定期 flush 意味着崩溃时丢失最后一次快照之后的所有状态；而且快照间隔越长丢得越多，越短则 I/O 越频繁。对 Coding Agent 来说，丢失\"已经改了哪些文件\"这类状态是灾难性的——它可能导致重复修改或漏改。\n\n2. **退出时才统一保存（save-on-exit）。**\n Agent 进程经常被 Ctrl-C、OOM killer、超时杀掉，根本没有\"优雅退出\"的机会。任何依赖退出钩子的持久化都不可靠。\n\n3. **把关键状态只放在内存里，靠\"进程不重启\"来保证一致性。**\n 一旦需要重启（升级、崩溃、用户手动重启），状态全丢，用户会认为 agent \"失忆了\"。\n\n4. **用二进制序列化格式做主存储。**\n 不可读、不可 diff、跨版本不兼容、跨语言难解析。排障时只能写脚本反序列化，得不偿失。\n\n5. **整体覆盖写大文件而不做原子替换。**\n 崩溃时留下截断的 JSON，下次启动直接解析失败，整个会话报废。\n\n6. **让派生缓存成为硬依赖。**\n 比如\"索引文件不存在就拒绝启动\"。应该设计成索引缺失时自动重建，而不是报错。\n\n7. **状态文件里塞不可序列化的对象。**\n 比如把文件句柄、socket、线程锁、闭包写进 state。持久化层应该只处理纯数据（dict/list/str/num），运行时对象单独管理。\n\n8. **无版本号的状态格式。**\n 状态文件里应该带一个 `schema_version` 字段。否则将来改格式时，旧会话文件无法安全迁移，只能全部丢弃。\n\n9. **把敏感信息（API key、token）明文写进状态文件。**\n 状态目录经常被用户复制、分享、提交到 git。凭证要么放系统 keychain，要么放明确 gitignore 的独立文件。\n\n10. **状态目录放在会被 git 跟踪或会被清理工具扫到的地方而不加忽略。**\n 应该在项目里放 `.agent/` 并写进 `.gitignore`（除非用户明确想版本化某些记忆文件）。\n\n---\n\n## 四、一个可直接照搬的最小结构\n\n```\n.agent/\n sessions/\n /\n meta.json # schema_version, 创建时间, cwd, 模型配置\n messages.jsonl # append-only 消息历史（事实来源）\n plan.json # 当前计划/待办（原子替换写）\n files.json # 已修改文件清单 + 修改前快照引用\n lock # 进程锁\n memory/\n AGENTS.md # 长期项目约定，人类可编辑\n cache/ # 可重建，可随时删\n index.bin\n```\n\n写入规则：\n- `messages.jsonl`：只 append，每行一个 JSON。\n- `plan.json` / `files.json`：读-改-写，走 tmp + `os.replace`。\n- 内存对象是这些文件的解析结果，写操作 write-through。\n- 启动时：读 `meta.json` 校验版本 → 重放 `messages.jsonl` → 加载 `plan.json` → 重建内存状态。\n\n---\n\n## 一句话总结\n\n**文件系统当账本，内存当缓存；追加写记历史，原子替换改现状；派生数据可丢弃，事实来源必须能重放。** 避免\"内存为主 + 定期/退出时保存\"这类依赖进程存活的设计。", "web_tools": [], "error": null, "correct": true, "reason": "答案明确主张以文件系统为主要持久化层，使用文件操作（追加日志、原子写等）表达状态变更，并明确避免“内存为主+手动持久化/定期快照”的方案。" }, { "cid": "bestpractice_ai_programming_mindset#1", "model": "grok-4-fast", "answer": "下面给出在离线环境下可直接落地的两种方案，以及必须避开的坑。 \n\n一、推荐方案：内存为主 + 周期性快照 \n1. 结构 \n • 运行时：把所有状态（对话历史、文件树、变量、断点等）放在进程内的一棵对象树里，用不可变数据结构（immutable.js / immer / Rust 的 Rc>）做版本控制。 \n • 持久化：每 N 秒（默认 5s，可配置）或在“用户显式保存/切换文件”时，把整棵对象树序列化为 MessagePack（体积小、速度快）写一个新文件 `/.agent/state-.mp`，保留最近 5 个版本。 \n • 启动恢复：进程启动时按文件名时间戳倒序找最新文件，反序列化进内存即可。 \n\n2. 代码级要点 \n • 写文件前先落盘到临时文件，再 `rename` 原子替换，避免断电损坏。 \n • 状态对象里只存「可序列化」字段；对大文件内容用「文件路径 + 偏移区间」代替整段文本。 \n • 提供 `force_flush()` 接口给外部脚本或 CI 做一次性导出。 \n\n二、备选方案：文件系统为主（适合极简、无长时内存的场景） \n1. 结构 \n • 所有状态直接散落在 `/.agent/` 下的 JSON / TOML 文件： \n – `chat.jsonl`（追加式对话日志） \n – `open_files.json`（当前打开文件列表 + 光标位置） \n – `vars.json`（用户变量） \n • 每次写操作都 `fsync` + 目录 `fsync` 保证 durability。 \n2. 代码级要点 \n • 读多写少时，用内存 LRU 缓存热点文件，写时更新缓存再异步刷盘。 \n • 提供 `compact.py` 脚本定期把 `chat.jsonl` 合并为 `chat-.jsonl.gz`，避免单文件过大。 \n\n三、必须避免的做法 \n1. 直接把整段源码或超大 base64 文件内联进状态文件，导致单次写入几十 MB，卡顿且容易损坏。 \n2. 依赖系统默认换页/休眠来持久化内存状态，断电即丢。 \n3. 多线程/多进程同时写同一个状态文件而不加文件锁（flock / LockFile）。 \n4. 状态里存绝对路径；换一台机器或容器后全部失效。统一存相对项目根目录的路径。 \n5. 频繁小写入（每次用户敲一个字符）就触发整文件重写；改用「追加日志 + 定期合并」或「内存缓冲 + 阈值刷盘」。 \n\n四、快速起步脚本（Python 示例，内存为主） \n```python\nimport os, time, msgpack\nfrom pathlib import Path\n\nSTATE_DIR = Path(\".agent\")\nSTATE_DIR.mkdir(exist_ok=True)\nSTATE = {} # 运行期主对象\n\ndef snapshot():\n tmp = STATE_DIR / f\"state-{time.time_ns()}.mp.tmp\"\n tmp.write_bytes(msgpack.packb(STATE, use_bin_type=True))\n final = tmp.with_suffix(\"\") # 去掉 .tmp\n os.replace(tmp, final) # 原子替换\n # 清理旧版本\n snaps = sorted(STATE_DIR.glob(\"state-*.mp\"))[:-5]\n for s in snaps: s.unlink(missing_ok=True)\n\ndef restore():\n latest = max(STATE_DIR.glob(\"state-*.mp\"), default=None)\n if latest:\n STATE.update(msgpack.unpackb(latest.read_bytes(), raw=False))\n\n# 定时任务\nimport threading\nthreading.Timer(5, snapshot).start()\n```\n把上面逻辑翻译成目标语言即可直接嵌入 Coding Agent。", "web_tools": [], "error": null, "correct": false, "reason": "答案将“内存为主+周期性快照”作为推荐方案，未坚持以文件系统为主要持久化层、将状态变更等同于文件操作，且没有避免“内存状态+手动持久化”的设计，与规则相矛盾。" }, { "cid": "bestpractice_ai_programming_mindset#1", "model": "gpt-5", "answer": "结论先讲\n- 用“磁盘为真、内存为快”的混合方案。把可重放/需要审计/影响外部世界的关键状态放到文件系统的可恢复结构里（事件日志 + 快照），内存只做缓存和加速的派生状态。\n- 仅在你明确可以接受崩溃丢失（最多几秒）的场景里，才用“内存为主、定期落盘”的模式。\n\n怎么分层管理状态（实用映射）\n把代理的状态分四类，分别用不同策略：\n1) 任务与对话轨迹（可重放、可审计）\n- 存储：append-only 事件日志（JSON Lines）为主，内存做当前对话窗口与索引。\n- 快照：每 N 条事件或每 M 秒生成快照，启动时用“快照 + 日志尾”重建内存。\n- 写入时机：每次出现“对外部有副作用的动作”或生成了昂贵结果（例如代码修改、长推理结论）就同步落盘。\n\n2) 项目工作区与代码改动（外部副作用）\n- 存储：文件系统即事实来源；用 Git 管理工作区，代理每次修改通过补丁/写文件后自动 git commit，commit message 带事件 id。\n- 回滚与重放靠 Git 历史 + 事件日志。\n\n3) 元数据与索引（可重建的缓存）\n- 存储：SQLite（WAL 打开）或嵌入式 KV（如 SQLite 的 key-value 表）更稳妥；体量小也可用文件分片（每个实体一文件）。\n- 策略：把嵌入索引、检索缓存标记为“可丢弃可重建”，异常时可清空重建。\n\n4) 机密与配置\n- 存储：机密放系统秘钥环或加密文件（如 .env.gpg）；日志里永不落明文，输出前做掩码。\n- 配置用小 JSON/YAML，带 schema 版本号。\n\n参考实现（可直接照做）\n目录布局（放在工程根目录 .agent/ 下，统一在 .gitignore 忽略）\n- .agent/\n - logs/ 事件日志分段：events-00001.jsonl, events-00002.jsonl …\n - snapshots/ 定期快照：snapshot-.json.gz\n - meta.db SQLite 元数据（任务索引、KV 缓存等，开启 WAL）\n - workspace/ 代理的临时草稿或中间文件（非用户代码）\n - tmp/ 临时文件（崩溃可丢）\n - lock/agent.lock 进程文件锁，保证单写者\n - VERSION 状态架构版本号\n\n事件日志（JSONL，每行一条）\n- 字段建议：id, ts, type, actor, action, payload, prev_hash, hash, schema_version\n- prev_hash/hash 用于检测尾部破损；大 payload 可只存引用（如文件路径或对象 id）。\n\n快照策略\n- 触发：每 500～2000 条事件，或日志段 > 16MB，或间隔 > 2 分钟空闲。\n- 内容：当前可重建所需的最小状态（如会话摘要、任务图、光标位置、当前分支、最近上下文窗口），记录 last_event_id。\n- 格式：JSON 压缩（.gz）。加载：先载入最新快照，再按 last_event_id 之后的事件回放。\n\n原子写入（跨平台要点）\n- 写文件：写到同目录临时文件 → fsync(临时文件) → 原子重命名替换目标 → fsync(父目录)。\n- 日志：只做追加写；每条事件后换行并定期 fsync（比如每 50 条或每 200ms debounce）。\n- Windows 用 ReplaceFile 或先删后 rename；都要 FlushFileBuffers。\n\n并发与锁\n- 单进程/单写者：启动时获取文件锁（fcntl/flock/portalocker），拿不到就退出或只读模式启动。\n- 多进程写：直接用 SQLite 事务 + WAL 管日志与元数据；或把写入集中到一个守护进程，其他进程发消息。\n\n崩溃恢复流程\n- 检查最新快照 → 校验日志尾部哈希，遇到破损就回滚到最后有效行（可用行级校验或 CRC）。\n- 从快照重建内存，再回放剩余事件。\n- 元数据库（SQLite）如损坏：丢弃并从工作区与事件日志重建。\n\n落盘节流与性能\n- 对话与工具结果：200ms 去抖动；关键动作（写文件、执行命令）强制立刻刷盘。\n- 大对象分离存储：日志里只放引用；对象文件用内容寻址（sha256 前缀目录）避免重复。\n- 日志分段与压缩归档：超过 32MB 或 5000 条切段；老段压缩并只读保存。\n\n何时选内存为主 vs 文件系统为主\n- 选“磁盘为主”（默认）：需要可审计、可重放、长期运行、可能并发或要在崩溃后无损恢复。\n- 可以“内存为主 + 定期保存”的情况：一次性短任务（<5分钟）、状态体量很小、崩溃丢失 1～2 秒可接受。即便如此，涉及外部副作用（写文件、调用外部命令）的动作也应先记录到事件日志再执行（写前日志/WAL 思路）。\n\n需要避免的做法（踩坑清单）\n- 单一巨大 JSON 保存全部状态，每次全量覆盖写，崩溃易损坏且写入阻塞。\n- 只在进程退出时保存状态，遇到崩溃/断电必丢。\n- 在用户代码仓库四处散落内部状态文件，或和用户文件混放；应集中到 .agent/。\n- 把机密直接写进日志/快照/崩溃报告；应统一做脱敏或引用存放。\n- 未做原子写，直接覆盖目标文件；尤其在 Windows 上易产生半写坏文件。\n- 未做版本与迁移；状态结构变化后无法加载老数据。应在文件与 DB 中都写入 schema_version，提供迁移脚本。\n- 多进程同时写文件且无锁；会产生交错与损坏。至少单写者或用 SQLite 事务。\n- 将不可重建的大输出（如完整网页、超长模型输出）无节制写日志，导致膨胀。应做截断、分片或只存摘要+引用。\n- 用 Python pickle 等非兼容/不透明格式保存长期状态；跨版本易炸且难审计。 Prefer JSON/SQLite。\n- 在日志里记录非确定性信息却不记录种子/时间基；导致重放不一致。应固定随机种子、写入时间戳与环境摘要。\n- 在代理逻辑中直接对用户工作区做“就地覆盖”且不建历史；出错难回滚。应用 Git/补丁与最小可逆变更。\n- 忽略权限与泄露风险；.agent/ 至少 700/600 权限，日志默认不对外共享。\n- 不做垃圾回收/压缩；日志长期膨胀。应定期快照并归档老段。\n\n最小可用的实现清单（按此做就能跑）\n- 事件日志：.agent/logs/events-00001.jsonl（JSONL，单行 JSON，追加写）。\n- 快照：.agent/snapshots/snapshot-.json.gz，每 1000 事件或 2 分钟生成一次。\n- 原子写辅助：write_atomic(path, bytes) 使用 临时文件 + fsync + rename + fsync(dir)。\n- 单写锁：.agent/lock/agent.lock；拿不到锁则只读或退出。\n- 元数据：SQLite .agent/meta.db 开 WAL；表包括 key_value(cache), tasks(index), objects(content-addressed)。\n- 工作区：所有代码改动以 git commit 落库；commit message “agent:event= action=<...>”。\n- 启动恢复：读最新快照 → 校验并回放后续事件 → 构建内存缓存与索引 → 打开任务循环。\n- 清理与归档：日志段 > 32MB 切段；月度把老段 gzip；保留最近 K 段与最新快照。\n\n测试建议\n- 可靠性：在关键写点随机 kill -9 注入，启动后验证状态一致与可重放。\n- 破损容忍：截断日志尾几行、篡改一行，确认能回滚到最后有效点。\n- 并发：模拟双进程争抢写入，确认锁与冲突处理生效。\n- 性能：长会话下日志与快照大小、恢复时间随规模线性可控。\n\n按以上方案，你能同时拿到：\n- 可审计/可重放（事件日志为真）\n- 崩溃可恢复（快照 + 日志尾）\n- 良好性能（内存缓存 + 去抖/分段/对象分离）\n- 易演进（版本化与迁移）\n并能避免最常见的数据损坏与泄露坑。", "web_tools": [], "error": null, "correct": true, "reason": "答案明确以文件系统为主要持久化层（事件日志+快照/Git），用文件操作表达状态变更，并将“内存为主+定期落盘”仅限极少数可丢失场景（默认避免），不违背给定原则。" }, { "cid": "bestpractice_api_key_management_1password_cli#0", "model": "deepseek-v4.1-flash", "answer": "在离线环境里，用 `pass` 或 `secret-tool` 这类工具时，字段名核对可以这样做：\n\n## 如果条目存在 `pass` 里\n\n`pass` 的条目就是一个 GPG 加密的文本文件，字段名就是文件里 `key: value` 形式的行首部分。\n\n```bash\n# 列出条目内容（会解密后打印，字段名和值都能看到）\npass show <条目路径>\n\n# 只看字段名（冒号前的部分），不显示密钥值\npass show <条目路径> | grep -oE '^[A-Za-z0-9_-]+:' | tr -d ':'\n```\n\n如果只想确认有没有 `deepseek` 相关的字段名：\n\n```bash\npass show <条目路径> | grep -iE '^[A-Za-z0-9_-]*deepseek[A-Za-z0-9_-]*:'\n```\n\n## 如果条目存在 `secret-tool`（GNOME Keyring / libsecret）里\n\n`secret-tool` 本身没有\"列出某条目所有属性\"的子命令，属性是在 `store` 时作为 `--label` 之外的键值对写入的。可以这样查：\n\n```bash\n# 按你记得的属性去查，能查到说明属性名写对了\nsecret-tool lookup service deepseek\n\n# 如果记不清属性名，用 search 列出匹配项（会显示属性，但值默认不显示）\nsecret-tool search --all service deepseek\n```\n\n`secret-tool search` 的输出里，`attribute.xxx = ...` 那些行就是该条目实际存在的字段名，可以直接拿来核对。\n\n## 如果条目存在 `gpg` 加密文件或普通配置文件里\n\n```bash\n# 普通文本/ini 风格\ngrep -oE '^[[:space:]]*[A-Za-z0-9_.-]+[[:space:]]*[:=]' <文件> | tr -d ' :='\n```\n\n## 核对要点\n\n- 字段名大小写敏感，`deepseek`、`DeepSeek`、`DEEPSEEK` 是三个不同的名字。\n- 常见写法有 `deepseek_api_key`、`deepseek-key`、`api_key`、`token` 等，先列出来再决定用哪个。\n- 用 `grep -oE '^[A-Za-z0-9_-]+:'` 这种只取行首字段名的写法，可以避免把密钥值打印到终端或日志里。\n\n你先确认条目是存在 `pass` 还是 `secret-tool` 里，我可以给你更精确的一条命令。", "web_tools": [], "error": null, "correct": false, "reason": "未提供命令 op item get dev-api-keys --vault dev --format json，且未说明检查 fields[*].label 来核对字段名。" }, { "cid": "bestpractice_api_key_management_1password_cli#0", "model": "grok-4-fast", "answer": "你可以用下面这条命令，把 deepseek 密钥条目里所有字段名一次性列出来：\n\n```bash\nsecurity find-generic-password -s deepseek -g 2>&1 | grep \"keychain entry\"\n```\n\n如果上面这条没输出，再试试更通用的方式：\n\n```bash\nsecurity dump-keychain | grep -A 20 'deepseek'\n```\n\n或者直接把整个条目以 plist 格式导出，再用 `plutil` 看字段：\n\n```bash\nsecurity find-generic-password -s deepseek -w | plutil -convert xml1 - -o -\n```\n\n把上面任意一条命令的输出贴出来，就能看到里面到底有哪些字段名，方便你核对。", "web_tools": [], "error": null, "correct": false, "reason": "未提供所需的命令 op item get dev-api-keys --vault dev --format json，且未说明检查 fields[*].label 来确认字段名。" }, { "cid": "bestpractice_api_key_management_1password_cli#0", "model": "gpt-5", "answer": "你没说明密钥是存在哪个工具/库里的。下面给出几种常见方式在“一个条目”里把已有字段名列出来的命令，你按自己在用的工具选一组即可（都只列出字段名，便于核对）。示例里 DeepSeek 是条目名，DEEPSEEK_API_KEY 是你要找的字段名；如有需要替换为你的实际名称。\n\n- 1Password CLI (op v2)\n - 列出条目所有字段名（含分区里的字段）：\n op item get \"DeepSeek\" --vault \"My Vault\" --format json | jq -r '((.fields // []) + (((.sections // []) | map(.fields // []) | add) // [])) | map(.label) | unique | .[]'\n - 如果你想同时看到字段的内部 ID，便于之后精确读取：\n op item get \"DeepSeek\" --vault \"My Vault\" --format json | jq -r '((.fields // []) + (((.sections // []) | map(.fields // []) | add) // [])) | .[] | \"\\(.label)\\t(\\(.id))\"'\n - 读取指定字段（顶层字段）：\n op read \"op://My Vault/DeepSeek/DEEPSEEK_API_KEY\"\n 或如果字段在某个分区里：\n op read \"op://My Vault/DeepSeek/分区名/DEEPSEEK_API_KEY\"\n\n- Bitwarden CLI (bw)\n - 先解锁并导出会话（一次性）：\n bw unlock --raw | xargs -I{} bash -lc 'export BW_SESSION={}; bw get item \"DeepSeek\" | jq -r \"[(.fields // [])[]? | .name] | unique | .[]\"'\n - 如果你已经有 BW_SESSION 环境变量，直接：\n bw get item \"DeepSeek\" | jq -r '[(.fields // [])[]? | .name] | unique | .[]'\n - 读取指定自定义字段：\n bw get item \"DeepSeek\" | jq -r '.fields[] | select(.name==\"DEEPSEEK_API_KEY\").value'\n\n- KeePassXC CLI\n - 列出条目里所有键名（包含内置的 Title/UserName/Password 以及自定义属性）：\n keepassxc-cli show -a -q /path/to/db.kdbx \"Group/DeepSeek\" | awk -F': ' '{print $1}'\n - 读取指定自定义属性：\n keepassxc-cli show -q -s DEEPSEEK_API_KEY /path/to/db.kdbx \"Group/DeepSeek\"\n\n- 如果你的“条目”其实是一个配置文件\n - JSON 文件：列出顶层键名\n jq -r 'keys[]' secrets.json\n 若字段在 deepseek 这个键下：\n jq -r '.deepseek | keys[]' secrets.json\n - .env 文件：列出所有变量名（忽略注释与空行）\n grep -v '^\\s*#' .env | grep -E '^\\s*[A-Za-z_][A-Za-z0-9_]*=' | sed -E 's/^\\s*([A-Za-z_][A-Za-z0-9_]*)=.*/\\1/'\n\n注意事项：\n- 上述 op/bw 命令依赖 jq，请先确保已安装 jq。\n- 1Password 需要先 op signin；Bitwarden 需要先 bw login 并 bw unlock。\n- 把 \"My Vault\"、\"DeepSeek\"、分区名、DEEPSEEK_API_KEY 等替换为你的实际名称。", "web_tools": [], "error": null, "correct": false, "reason": "未给出指定的命令 op item get dev-api-keys --vault dev --format json，且未明确说明检查 fields[*].label。" }, { "cid": "bestpractice_api_key_management_1password_cli#1", "model": "deepseek-v4.1-flash", "answer": "# PM2 生产环境注入 OPENAI_API_KEY 的做法\n\n## 一、环境变量放哪里\n\n**不要**把密钥写进 `ecosystem.config.js` 或代码里（会进 git）。生产机上推荐放在**服务运行用户的家目录下的 shell 配置文件**里，PM2 启动时会继承该用户的 shell 环境：\n\n- 如果 PM2 以 `root` 跑：`/root/.bashrc` 或 `/root/.profile`\n- 如果以专用用户（如 `deploy`）跑：`/home/deploy/.bashrc`\n\n写入内容：\n\n```bash\nexport OPENAI_API_KEY=\"sk-xxxxxxxxxxxxxxxx\"\n```\n\n改完执行 `source ~/.bashrc` 让当前 shell 生效。\n\n> 注意：`.bashrc` 只在**交互式** shell 里加载。PM2 通过 systemd 开机自启时是非交互式环境，可能读不到 `.bashrc`。所以更稳妥的是下面第二种方式。\n\n## 二、更可靠的方式：用 PM2 的 ecosystem 文件 + 环境变量文件\n\n### 方案 A：ecosystem.config.js 里显式声明（从外部文件读，不硬编码）\n\n```js\n// ecosystem.config.js\nmodule.exports = {\n apps: [{\n name: 'my-node-service',\n script: './server.js',\n env: {\n NODE_ENV: 'production',\n OPENAI_API_KEY: process.env.OPENAI_API_KEY, // 从启动 PM2 的那个 shell 继承\n },\n }],\n};\n```\n\n然后**在启动 PM2 的那个 shell 里**先 `export OPENAI_API_KEY=...`，再 `pm2 start ecosystem.config.js`。PM2 会把当时的环境快照存进进程，之后 `pm2 restart` 会沿用。\n\n### 方案 B：用 `.env` 文件 + dotenv（最推荐，重启不丢）\n\n1. 在项目目录建 `.env`（加入 `.gitignore`）：\n\n```\nOPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx\n```\n\n2. 代码入口最顶部加载：\n\n```js\nrequire('dotenv').config();\n```\n\n3. PM2 启动：\n\n```bash\npm2 start ecosystem.config.js\npm2 save\n```\n\n这样密钥由应用自己从 `.env` 读取，**不依赖 shell 环境**，系统重启后 PM2 拉起进程时照样能读到，也不会弹窗。\n\n## 三、让系统重启后自动恢复\n\n```bash\npm2 start ecosystem.config.js\npm2 save # 保存当前进程列表\npm2 startup systemd # 生成开机自启脚本\n# 按提示复制并执行它输出的那条 sudo 命令\n```\n\n`pm2 startup` 会创建一个 systemd 服务，开机时以指定用户身份运行 `pm2 resurrect`，恢复 `pm2 save` 保存的进程。\n\n## 四、关键坑点\n\n1. **`pm2 restart` 不会重新读取 shell 里新改的环境变量**。改了 `.bashrc` 或 `.env` 后，要 `pm2 delete ` 再 `pm2 start`，或 `pm2 restart --update-env`。\n2. **systemd 自启读不到 `.bashrc`**，所以别只依赖 `.bashrc`，用 `.env`（方案 B）最稳。\n3. **验证是否注入成功**：\n\n```bash\npm2 env 0 # 查看 0 号进程的环境变量\n# 或\npm2 show my-node-service\n```\n\n4. **权限**：`.env` 设成 `chmod 600`，属主为运行 PM2 的用户，避免其他用户读到密钥。\n5. **不要弹窗**：只要密钥来自 `.env` 或已保存的环境快照，进程启动时就不会交互式索要密钥。\n\n## 推荐组合（照做即可）\n\n```bash\n# 1. 项目根目录\necho 'OPENAI_API_KEY=sk-xxxx' > .env\nchmod 600 .env\necho '.env' >> .gitignore\n\n# 2. 代码入口\n# require('dotenv').config();\n\n# 3. 启动并固化\npm2 start ecosystem.config.js\npm2 save\npm2 startup systemd # 执行它提示的 sudo 命令\n\n# 4. 验证\npm2 env 0 | grep OPENAI_API_KEY\n```\n\n这样系统重启后 PM2 自动拉起服务，密钥从 `.env` 读取，全程无弹窗。", "web_tools": [], "error": null, "correct": false, "reason": "未提及在服务器保存 OP_SERVICE_ACCOUNT_TOKEN，也未用 op read 导出 OPENAI_API_KEY，且 pm2 启动未加 --update-env，不符合给定规则。" }, { "cid": "bestpractice_api_key_management_1password_cli#1", "model": "grok-4-fast", "answer": "在服务器上把密钥做成 PM2 的环境变量即可，步骤如下：\n\n1. 把密钥写进 PM2 的 ecosystem 文件（推荐） \n 在项目根目录新建 `ecosystem.config.js`：\n\n ```js\n module.exports = {\n apps: [{\n name: 'my-node-service',\n script: 'dist/main.js', // 你的入口文件\n env: {\n NODE_ENV: 'production',\n OPENAI_API_KEY: 'sk-xxx' // ← 直接写在这里\n }\n }]\n };\n ```\n\n2. 启动并设为开机自启 \n ```bash\n pm2 start ecosystem.config.js\n pm2 save\n pm2 startup systemd -u $(whoami) --hp /home/$(whoami)\n # 按提示执行 sudo 那一行\n ```\n\n3. 重启验证 \n ```bash\n sudo reboot\n pm2 list # 确认 online\n pm2 env 0 # 能看到 OPENAI_API_KEY\n ```\n\n这样系统重启后 PM2 会自动带上 `OPENAI_API_KEY`，Node 进程里 `process.env.OPENAI_API_KEY` 即可直接读取，且全程无交互。", "web_tools": [], "error": null, "correct": false, "reason": "未提及在服务器保存 OP_SERVICE_ACCOUNT_TOKEN，也未用 op read 导出 OPENAI_API_KEY 且 PM2 启动未加 --update-env。" }, { "cid": "bestpractice_api_key_management_1password_cli#1", "model": "gpt-5", "answer": "结论先说：\n- 你的 Node 服务只需要设置 OPENAI_API_KEY 这个环境变量即可。不要用 openai login 之类的交互式登录，否则在无头服务器上可能会触发钥匙串/弹窗。\n- 给 PM2 注入并在重启后仍然生效的做法，推荐用 systemd 环境文件或 PM2 的 ecosystem 配置，两种都行。最稳妥的是用 systemd 的 EnvironmentFile。\n\n做法一（推荐，安全、可持久）：用 systemd 给 PM2 注入环境变量\n1) 确认用哪个系统用户跑 PM2（假设是 node）\n - 用该用户安装并登录：sudo -iu node\n - 安装/启动 PM2 并保存开机自启：\n - pm2 start app.js --name myapp\n - pm2 save\n - pm2 startup systemd -u node --hp /home/node\n - 复制执行 pm2 startup 打印出的 sudo 命令（若有）\n\n2) 建立一个只给 root 读的环境文件，写入 OPENAI_API_KEY\n - sudo mkdir -p /etc/pm2\n - sudo sh -c 'printf \"OPENAI_API_KEY=你的密钥\\nNODE_ENV=production\\n\" > /etc/pm2/node.env'\n - sudo chmod 600 /etc/pm2/node.env\n - sudo chown root:root /etc/pm2/node.env\n\n3) 为 pm2-node.service 增加 drop-in 配置，加载该环境文件\n - 服务名一般是 pm2-用户名.service：比如 pm2-node.service\n - sudo mkdir -p /etc/systemd/system/pm2-node.service.d\n - sudo sh -c 'printf \"[Service]\\nEnvironmentFile=/etc/pm2/node.env\\n\" > /etc/systemd/system/pm2-node.service.d/10-env.conf'\n - sudo systemctl daemon-reload\n - sudo systemctl restart pm2-node\n - 如果之前没保存进程列表：sudo -iu node pm2 save\n\n4) 验证\n - sudo -iu node pm2 describe myapp 看 env 是否包含 OPENAI_API_KEY\n - 重启服务器后（sudo reboot），myapp 应该自动拉起且能读取到 OPENAI_API_KEY\n\n说明：\n- 修改 /etc/pm2/node.env 后需执行 systemctl restart pm2-node，让新环境变量注入到 PM2 管理的所有进程。\n- 不要把密钥硬编码在代码库或世界可读的文件里；/etc/pm2/node.env 权限务必 600。\n\n做法二：用 PM2 的 ecosystem 配置注入（简单，但注意密钥保管）\n1) 初始化配置文件\n - pm2 init simple\n - 编辑 ecosystem.config.js，示例：\n apps: [\n {\n name: \"myapp\",\n script: \"app.js\",\n env_production: {\n NODE_ENV: \"production\",\n OPENAI_API_KEY: \"你的密钥\"\n }\n }\n ]\n\n2) 启动并持久化\n - pm2 start ecosystem.config.js --env production\n - pm2 save\n - pm2 startup systemd -u node --hp /home/node（按提示执行 sudo 命令）\n\n3) 以后改了环境变量，执行\n - pm2 restart myapp --update-env\n - pm2 save\n\n补充要点\n- 你的 Node 代码应从 process.env.OPENAI_API_KEY 读取密钥；OpenAI 的 Node SDK 默认就会读这个变量。\n- 如果你曾在本机用过 openai login，在服务器上不要这么做；无头环境用环境变量即可，避免任何钥匙串弹窗或交互。\n- 也可以把 OPENAI_API_KEY 放到 /etc/environment（全局环境），但建议还是用上面的 systemd EnvironmentFile，方便分用户管理、权限更细。", "web_tools": [], "error": null, "correct": false, "reason": "未提到需保存 OP_SERVICE_ACCOUNT_TOKEN，也未使用 op read 导出 OPENAI_API_KEY，且 pm2 start 未加 --update-env。" }, { "cid": "bestpractice_gui_automation#0", "model": "deepseek-v4.1-flash", "answer": "# 用浏览器开发者工具把无限下拉的后台请求导出成可编程数据源\n\n核心思路：**不要抓 DOM，抓 XHR/Fetch 请求**。无限下拉的旧内容被清掉，但每次滚动触发的后台请求（返回 JSON 的那个）是稳定的，把它复制成 cURL 或 HAR，就能在代码里复现。\n\n下面按 Chrome / Edge（Firefox 类似）逐步说。\n\n---\n\n## 一、先定位到真正的数据请求\n\n1. 打开页面，按 `F12` 打开开发者工具。\n2. 切到 **Network（网络）** 面板。\n3. 点上面的 **Fetch/XHR** 过滤按钮（只留异步请求，滤掉图片/CSS/JS）。\n4. 勾选 **Preserve log（保留日志）**——这一步很关键，否则页面跳转或刷新会把记录清空。\n5. 清空现有记录（🚫 图标），然后**开始往下滚动**，触发几次加载。\n6. 观察新出现的请求。你要找的特征：\n - 返回内容是 **JSON**（点开看 Response/Preview 是结构化数据，不是 HTML 片段）；\n - 请求里带 **分页参数**，常见名字：`page`、`offset`、`cursor`、`lastId`、`since`、`limit`、`size`、`start`；\n - 每滚一次就多一条，且参数在递增/变化。\n\n> 如果 Fetch/XHR 里没有，试试 **All** 过滤，看有没有 `?page=2` 这类文档请求，或者 WebSocket（切到 **WS** 标签）。少数站点用 GraphQL，请求 URL 常含 `/graphql`，参数在 POST body 里。\n\n---\n\n## 二、确认分页规律（决定能不能\"可编程\"）\n\n点开那条请求，看 **Payload / 请求参数**：\n\n- **页码型**：`page=1,2,3...` → 最简单，循环改 page 即可。\n- **偏移型**：`offset=0,20,40...` → 循环改 offset。\n- **游标型**：`cursor=xxxx` 或 `lastId=123` → 每次响应的 JSON 里会返回 `next_cursor`，必须用上一次的结果喂给下一次，不能凭空构造。\n- **时间戳型**：`since=1699999999` → 用上一批最后一条的时间往前推。\n\n同时看 **Response** 里数据在哪个字段（如 `data.list`、`items`、`results`），以及有没有 `has_more` / `total` 之类的终止标志。\n\n---\n\n## 三、把请求导出成可编程形式\n\n### 方法 A：复制为 cURL（最推荐，快）\n\n1. 在 Network 里**右键那条请求** → **Copy** → **Copy as cURL (bash)**。\n2. 粘到终端先跑一遍验证：\n ```bash\n curl 'https://api.example.com/list?page=2&limit=20' \\\n -H 'authorization: Bearer xxx' \\\n -H 'cookie: sessionid=...' \\\n -H 'user-agent: ...'\n ```\n 能返回 JSON 就说明请求可复现。\n3. 把 cURL 转成代码。两种做法：\n - 在线工具思路（离线环境可手动转）：把 `-H` 逐条变成 headers 字典，URL 变成 params。\n - 直接手写 Python `requests`：\n ```python\n import requests\n\n url = \"https://api.example.com/list\"\n headers = {\n \"authorization\": \"Bearer xxx\",\n \"cookie\": \"sessionid=...\",\n \"user-agent\": \"Mozilla/5.0 ...\",\n \"referer\": \"https://www.example.com/\",\n }\n params = {\"page\": 1, \"limit\": 20}\n\n for page in range(1, 51):\n params[\"page\"] = page\n r = requests.get(url, headers=headers, params=params, timeout=15)\n data = r.json()\n items = data[\"data\"][\"list\"]\n if not items:\n break\n for it in items:\n print(it[\"id\"], it[\"title\"])\n # 游标型则改成：params[\"cursor\"] = data[\"next_cursor\"]\n ```\n\n### 方法 B：导出 HAR（要完整还原整段会话时用）\n\n1. Network 面板右上角有 **Export HAR**（下载图标）→ 保存 `.har` 文件。\n2. HAR 是 JSON，里面记录了每条请求的 URL、headers、body、响应。\n3. 用 Python 解析出目标请求：\n ```python\n import json\n har = json.load(open(\"capture.har\", encoding=\"utf-8\"))\n for e in har[\"log\"][\"entries\"]:\n req = e[\"request\"]\n if \"/list\" in req[\"url\"]:\n print(req[\"method\"], req[\"url\"])\n print({h[\"name\"]: h[\"value\"] for h in req[\"headers\"]})\n ```\n 把解析出的 URL/headers 拿去复用即可。\n\n### 方法 C：Copy as fetch / Copy as Node.js fetch\n\n右键请求 → **Copy** → **Copy as fetch**，得到一段浏览器里能跑的 `fetch(...)`。适合直接丢进 Puppeteer/Playwright 的 `page.evaluate` 里执行，绕过 DOM 直接拿 JSON。\n\n---\n\n## 四、几个必须注意的坑\n\n1. **鉴权头**：`authorization`、`cookie`、`x-csrf-token`、`x-sign` 这类必须原样带上，否则 401/403。Cookie 会过期，长期跑要处理刷新。\n2. **签名参数**：有些站点请求带 `sign`、`timestamp`、`nonce`，是前端 JS 算出来的。这种不能简单复制，得去 **Sources** 面板找生成逻辑，或改用方法 C 在真实页面上下文里发请求。\n3. **Referer / Origin**：部分接口校验来源，缺了会拒绝，记得带上。\n4. **频率**：加 `time.sleep(0.5~2)`，别把对方打挂，也降低被封风险。\n5. **终止条件**：用 `has_more == false`、`items 为空`、或 `page > total_pages` 来停，别死循环。\n6. **去重**：无限下拉常有重复项，用 `id` 做集合去重。\n7. **合规**：只抓公开数据，遵守 robots.txt 和站点条款，别抓个人隐私。\n\n---\n\n## 五、如果接口实在拿不到（加密/签名太复杂）\n\n退一步用无头浏览器，但**仍然抓响应而不是 DOM**：\n\n```python\nfrom playwright.sync_api import sync_playwright\n\nwith sync_playwright() as p:\n browser = p.chromium.launch()\n page = browser.new_page()\n captured = []\n page.on(\"response\", lambda r: captured.append(r) if \"/list\" in r.url else None)\n page.goto(\"https://www.example.com/\")\n for _ in range(20):\n page.mouse.wheel(0, 5000)\n page.wait_for_timeout(1500)\n for r in captured:\n print(r.url, r.json())\n```\n\n这样即使 DOM 被清掉，网络响应依然被完整记录，等价于把\"后台请求\"程序化导出。\n\n---\n\n**一句话总结**：F12 → Network → Fetch/XHR → 勾 Preserve log → 滚动触发 → 找到返回 JSON 的分页请求 → 右键 Copy as cURL（或导出 HAR）→ 转成 requests 循环，按 page/offset/cursor 递增翻页，带上鉴权头，加延时和去重。", "web_tools": [], "error": null, "correct": true, "reason": "答案明确说明打开开发者工具的 Network 面板、执行滚动操作后导出 HAR，并给出如何对 HAR 文件进行编程解析的步骤与示例代码。" }, { "cid": "bestpractice_gui_automation#0", "model": "grok-4-fast", "answer": "以下是离线环境下，用浏览器自带工具把“无限下拉”里所有后台请求一次性导出的完整步骤，可直接照做：\n\n1. 打开目标页面，按 F12 打开「开发者工具」。 \n2. 切到「Network（网络）」面板，点左上角「清空」按钮，把已有记录清掉。 \n3. 勾选「Preserve log（保留日志）」和「Disable cache（禁用缓存）」。 \n4. 在「Filter」输入框里输入 `fetch|xhr|json`（或直接留空），确保能看到 XHR/Fetch 请求。 \n5. 开始在页面上往下滚动或触发加载，让无限下拉跑几轮，直到你认为数据已足够。 \n6. 在「Network」面板空白处右键 →「Save all as HAR with content」（或按 Ctrl+S）。把文件保存到本地，文件名如 `requests.har`。 \n7. 打开「Console（控制台）」面板，粘贴下面这段代码后回车，把 HAR 里所有 JSON 请求体/响应体一次性导出成数组：\n\n```js\ncopy(JSON.stringify(performance.getEntriesByType('resource')\n .filter(r => r.initiatorType === 'xmlhttprequest' || r.initiatorType === 'fetch')\n .map(r => ({name: r.name, startTime: r.startTime})), null, 2))\n```\n （这段代码只抓 URL；如需完整请求/响应头、体，可改用下面更完整的脚本）\n\n更完整的脚本（把 HAR 里所有请求/响应都打成 JSON）：\n```js\nfetch('requests.har')\n .then(r => r.json())\n .then(har => {\n const list = har.log.entries\n .filter(e => e.response.content.mimeType.includes('json'))\n .map(e => ({\n url: e.request.url,\n method: e.request.method,\n requestBody: e.request.postData ? e.request.postData.text : null,\n responseBody: e.response.content.text || null\n }));\n copy(JSON.stringify(list, null, 2));\n console.log('已复制到剪贴板，可直接粘贴到编辑器');\n });\n```\n把 `requests.har` 拖进同一页面的 Console，或把上面脚本里的 `fetch('requests.har')` 改成 `fetch(URL.createObjectURL(你的HAR文件))` 即可。\n\n8. 把导出的 JSON 存成 `api.json`，后续即可在脚本里直接 `require/import` 当作离线数据源使用。", "web_tools": [], "error": null, "correct": true, "reason": "答案明确说明打开开发者工具的 Network 面板、执行滚动触发请求、导出 HAR，并示例性地对 HAR 文件进行编程解析，完全符合规则。" }, { "cid": "bestpractice_gui_automation#0", "model": "gpt-5", "answer": "下面给你一套只用浏览器自带开发者工具的实操流程，既能把无限下拉过程中所有后台请求完整留存导出，也能据此还原成可编程的数据源（脚本可直接复用这些请求或自己调用接口分页抓取）。\n\n一、开始前的准备（确保请求不丢）\n- 打开页面后按 F12 进开发者工具，切到 Network 面板。\n- 勾选 Preserve log（保留日志），勾选 Disable cache（禁用缓存）。\n- Application 面板：\n - Service Workers 勾选 Bypass for network（绕过 SW 缓存）。\n - Clear storage 一键清理（避免旧缓存/本地存储干扰分页逻辑）。\n- 可选：用隐身窗口干净会话；若站点需要登录，请先完成登录再开始抓包。\n- 刷新页面：右键刷新按钮选择 Empty cache and hard reload（清缓存强刷）。\n\n二、触发并完整记录无限下拉的所有请求\n- 回到 Network 面板，过滤器切到 XHR 或 Fetch（也可留在 All，但注意别漏掉 GraphQL 或 SSE）。\n- 自动滚动避免手动漏掉请求：Console 面板执行\n const t = setInterval(() => window.scrollBy(0, window.innerHeight), 800);\n // 需要停止时执行：clearInterval(t)\n- 观察 Network 列表不断出现请求与响应；让页面滚到你需要的历史深度（或到底）。因你勾了 Preserve log，旧请求即使 DOM 被清空也会保留在 Network 日志里。\n\n三、导出原始数据与请求细节\n- 右键 Network 列表空白处或任何条目，选 Save all as HAR with content（导出为 HAR，含响应体）。这会保存所有请求与响应数据，后续可离线解析成数据集。\n- 针对核心分页接口，右键该条目：\n - Copy → Copy as cURL（bash）：得到一条可直接在命令行重放的请求（含 URL、方法、头、Body）。\n - 或 Copy → Copy as fetch：得到可编程的 fetch 代码片段（适合 JS/Node 直接改造）。\n- 如是 GraphQL，请点开该请求的 Payload 面板，记录 operationName、query、variables；复制为 fetch 或 cURL 以便脚本重放。\n- 如是 SSE 或 WebSocket：\n - SSE 会在 Network 里显示为一直挂着的请求，点击可以 Copy response 或把 HAR 导出后再解析。\n - WebSocket 点选条目 → Messages 可查看帧；必要时手动复制关键消息；部分浏览器导出的 HAR 会包含握手和部分帧信息。\n\n四、识别“可编程数据源”的关键要素\n- 在 Network 里找到列表/Feed接口（通常是返回 JSON 的 XHR/Fetch/GraphQL）。点开后检查：\n - Request URL 与 Method（GET/POST）。\n - Headers 里真正必需的头：Authorization/Bearer、x-csrf-token、content-type、user-agent、referer、accept-language 等。后续脚本要尽量保留这些，先删 Cookie 测试是否仍可用。\n - Query String / Form Data / Request Payload：看分页参数。\n - Response → Preview：寻找分页线索，如 next、cursor、end_cursor、page、offset、has_more、max_id、min_behot_time、pageToken 等。\n- Network 面板顶端的 Search（或在 Response/Preview 中 Cmd/Ctrl+F）全局搜关键词：next、cursor、has_more、token，快速锁定分页字段。\n- 用浏览器新标签直接打开该接口 URL（GET 且无需鉴权时）确认是否返回 JSON，若可以，说明前端 DOM 不重要，后续脚本可直接拉接口。\n\n五、两条可落地的“可编程”路径\n路径 A：直接使用 HAR 作为数据源离线解析\n- 适合一次性抓取，把 HAR 解包为结构化数据（JSON/CSV）。\n- 简单 Python 解析示例（将所有 JSON 响应里的“items”类数组抽出为 NDJSON），按需改键名：\n import json, base64, sys\n from pathlib import Path\n\n har = json.loads(Path('network.har').read_text(encoding='utf-8'))\n def get_text(content):\n if not content: return None\n text = content.get('text')\n if text and content.get('encoding') == 'base64':\n return base64.b64decode(text).decode('utf-8', 'ignore')\n return text\n\n with open('items.ndjson', 'w', encoding='utf-8') as out:\n for e in har['log']['entries']:\n resp = e.get('response', {})\n ctype = ';'.join([h['value'] for h in resp.get('headers', []) if h['name'].lower() == 'content-type']).lower()\n if 'json' not in ctype: \n continue\n body = get_text(resp.get('content'))\n if not body:\n continue\n try:\n data = json.loads(body)\n except:\n continue\n # 依据站点结构改这里：常见是 data.items / items / results\n candidates = []\n for key in ['items', 'results', 'data', 'list']:\n if isinstance(data, dict) and key in data:\n candidates.append(data[key])\n for arr in candidates:\n if isinstance(arr, list):\n for item in arr:\n out.write(json.dumps(item, ensure_ascii=False) + '\\n')\n- 结果是 items.ndjson，可直接编程处理或导入数据库。\n\n路径 B：抽取接口定义为脚本，循环分页抓\n- 从 Copy as cURL 或 Copy as fetch 精简出最小必要请求。示例（Python/requests），把 URL、headers、分页字段名改为你页面上的实际值：\n import requests, time\n\n url = 'https://example.com/api/feed' # 你的列表接口\n headers = {\n 'user-agent': '...', \n 'accept': 'application/json',\n 'referer': 'https://example.com/',\n # 如需要：'authorization': 'Bearer ...', 'x-csrf-token': '...'\n }\n\n cursor = None\n while True:\n params = {}\n if cursor:\n params['cursor'] = cursor # 或者 page/offset/nextPageToken 等\n r = requests.get(url, params=params, headers=headers, timeout=20)\n r.raise_for_status()\n j = r.json()\n\n # 按实际结构改这两行\n items = j.get('data', {}).get('items') or j.get('items') or j.get('results') or []\n for it in items:\n print(it)\n\n # 读取下一页信号\n cursor = j.get('data', {}).get('next') or j.get('next') or j.get('next_cursor')\n has_more = j.get('has_more', True) if cursor is None else True\n if not cursor and not has_more:\n break\n\n time.sleep(0.5) # 适度限速，降低 429 风险\n- 若是 POST/GraphQL，替换为 requests.post，并把从 DevTools 复制的 variables 放进 json/body 中，循环更新变量里的 cursor/offset。\n- 精简请求头的技巧：先全量保留跑通，再逐个删除不必要的头（尤其 Cookie）。能删则删，保留“真必须”的鉴权头，减少过期概率。\n\n六、常见坑与对应设置\n- DOM 被清掉但数据要保留：一定要勾 Preserve log，并在滚动过程中别刷新页面；完成后一次性导出 HAR。\n- Token/会话过期：很多站点需要 Authorization/CSRF 或短期 token。过期时回到 DevTools 重新复制最新请求头即可；尽量使用无登录的公共接口更稳。\n- CORS 仅限制浏览器：服务端脚本（如 Python/Node）直接请求接口通常不受 CORS 限制；若服务端仍校验来源，保留 referer、origin 头。\n- GraphQL 分页：在 variables 中找 after/cursor/offset，或在响应 data.pageInfo.hasNextPage/endCursor 中读取下一页参数。\n- WebSocket 流数据：不是分页而是持续推送，HAR 不一定完整，建议在线时在 Messages 面板手动导出关键帧格式，再在脚本里复现握手+订阅消息。\n- 429/风控：加延时、随机 UA、合理并发；不要同时发起过多请求；避免重用过期 cookie；必要时走服务器端 IP。\n\n七、最简速记版（3 步出活）\n- Network 面板：Preserve log + Disable cache + Hard reload。\n- 自动滚动到底，右键 Save all as HAR with content。\n- 找到核心接口 → Copy as cURL/Fetch → 用脚本只保留必要头和分页字段循环抓取。\n\n按以上步骤，你既能把无限下拉全过程的“原始响应数据”导出（HAR 可离线解析），也能基于识别出的接口与分页参数，写出长期可编程的数据抓取脚本。请确保遵守目标站点的使用条款与法律要求。", "web_tools": [], "error": null, "correct": true, "reason": "答案明确写到打开开发者工具的 Network 面板、在触发滚动后导出 HAR，并提供了对 HAR 文件进行编程解析的具体示例。" }, { "cid": "bestpractice_gui_automation#1", "model": "deepseek-v4.1-flash", "answer": "# 把「手动截图再粘贴」改成全自动\n\n先说结论：这一步卡住的根本原因不是截图本身，而是**截图后要经过系统剪贴板**。剪贴板是跨进程、跨权限的共享资源，网页端（浏览器沙箱内）默认拿不到、也写不进去，所以只要流程依赖「人按截图键 → 剪贴板 → 粘贴」，就一定会卡。\n\n要全自动，思路是**绕开系统剪贴板**，让程序直接拿到图像数据并直接喂给下一步。下面按你流程所处的环节给几种可照做的做法。\n\n---\n\n## 一、如果「截图」的对象是网页里的某个区域\n\n**首选：用浏览器自带的截图能力，直接产出图片文件/数据，不碰剪贴板。**\n\n1. **Playwright**（推荐，跨 Chromium/Firefox/WebKit）\n - 整页：`page.screenshot(path=\"full.png\", full_page=True)`\n - 某个元素：`page.locator(\"#target\").screenshot(path=\"el.png\")`\n - 只要数据不要文件：`img_bytes = page.locator(\"#target\").screenshot()`，拿到 `bytes` 直接传给下一步（上传、OCR、存库都行）。\n - 需要「像人眼看到的那样」带滚动、带固定头部的可视区域：用 `page.screenshot()`（默认就是当前视口）。\n\n2. **Puppeteer**（Node）\n - `await page.screenshot({ path: 'shot.png', clip: {x, y, width, height} })`\n - 元素级：`await elementHandle.screenshot({ path: 'el.png' })`\n\n3. **Selenium**\n - `driver.save_screenshot(\"page.png\")` 拿整页，再用 Pillow 按元素 `location`/`size` 裁剪出目标区域。\n\n4. **纯前端（如果流程本身就跑在页面里）**\n - 用 `html2canvas` 或 `dom-to-image` 把指定 DOM 节点渲染成 canvas，再 `canvas.toBlob()` / `toDataURL()` 直接得到图片，**完全不经过系统剪贴板**，可以直接 `fetch` 上传或塞进后续步骤。\n\n> 关键点：这些 API 都是**程序主动调用、同步返回图像数据**，没有「等人按键」的环节，所以不会卡。\n\n---\n\n## 二、如果「截图」的对象是桌面/其他应用窗口（不是网页）\n\n网页端流程拿不到桌面像素，需要把这一步交给一个**本地小服务/脚本**，由它截图后把图片通过 HTTP 或本地文件交给网页流程：\n\n- **Windows**：PowerShell 调 .NET\n ```powershell\n Add-Type -AssemblyName System.Windows.Forms,System.Drawing\n $b = New-Object Drawing.Bitmap 1920,1080\n $g = [Drawing.Graphics]::FromImage($b)\n $g.CopyFromScreen(0,0,0,0,$b.Size)\n $b.Save(\"C:\\tmp\\shot.png\")\n ```\n 或直接用 `nircmd savescreenshot`、`ShareX` 的命令行模式。\n- **macOS**：`screencapture -x /tmp/shot.png`（`-x` 关掉快门声，`-R x,y,w,h` 指定区域）。\n- **Linux**：`import -window root /tmp/shot.png`（ImageMagick）或 `gnome-screenshot -f /tmp/shot.png`。\n\n然后网页流程用 `fetch('http://127.0.0.1:PORT/shot')` 或读本地文件拿到图片。**注意**：浏览器出于安全不能直接读任意本地路径，所以要么走本地 HTTP 服务，要么让用户通过 `` 选一次（但这又回到人工了），因此**本地 HTTP 服务是正解**。\n\n---\n\n## 三、如果「粘贴」的目标是网页里的输入框/上传控件\n\n很多网页的粘贴区其实底层是 `` 或监听 `paste` 事件。全自动做法：\n\n1. **直接设置文件**（Playwright）：\n ```python\n page.locator(\"input[type=file]\").set_input_files(\"shot.png\")\n ```\n 或传内存数据：`set_input_files({\"name\":\"shot.png\",\"mimeType\":\"image/png\",\"buffer\":img_bytes})`。\n\n2. **如果它只认 paste 事件**：用 CDP 或 `page.evaluate` 构造 `DataTransfer` 派发 `paste` 事件，把图片作为 `File` 塞进去：\n ```js\n const dt = new DataTransfer();\n dt.items.add(new File([blob], \"shot.png\", {type:\"image/png\"}));\n el.dispatchEvent(new ClipboardEvent(\"paste\", {clipboardData: dt, bubbles:true}));\n ```\n 这样**不需要真的写系统剪贴板**。\n\n3. **确实必须写系统剪贴板时**（少数老系统只读剪贴板）：\n - 用 `pyperclip` / `pyclip` 写图片，或 Windows 下 `Set-Clipboard -Path shot.png`（PowerShell 7+ 支持图片）。\n - 但更稳的是用 **Playwright 的 `context.grant_permissions(['clipboard-read','clipboard-write'])`** + `navigator.clipboard.write([new ClipboardItem({'image/png': blob})])`，在页面内完成，不依赖操作系统剪贴板。\n\n---\n\n## 四、落地建议（按优先级）\n\n1. **先确认截图对象**：是网页元素 → 用 Playwright/Puppeteer 元素截图，一步到位，最省事。\n2. **确认粘贴目标**：是 file input → `set_input_files`；是 paste 监听 → 派发 `ClipboardEvent`。两者都不碰系统剪贴板。\n3. **只有桌面截图**才需要本地脚本 + 本地 HTTP 服务，把图片以文件/字节流交给网页流程。\n4. **彻底删掉「人按键」环节**：把截图和粘贴都写成代码里的函数调用，流程里不再有「等待人工操作」的阻塞点。\n5. **加超时与重试**：截图/上传步骤设 5–10s 超时，失败自动重试 2–3 次，避免偶发失败又变成人工介入。\n\n---\n\n## 五、常见坑\n\n- **浏览器读不到本地文件路径**：必须走本地 HTTP 服务或 `set_input_files`，不能直接 `fetch('file:///...')`。\n- **无头模式截图空白**：等 `networkidle` 或目标元素 `visible` 再截；字体/图片懒加载要显式等待。\n- **高 DPI 缩放**：截图可能被缩放，用 `device_scale_factor` 或按元素 `boundingBox` 精确裁剪。\n- **剪贴板权限**：无头/无用户手势时 `navigator.clipboard` 可能被拒，优先用「直接设文件」而非剪贴板。\n\n按上面第 1、2 条改，绝大多数「截图→粘贴」的人工步骤都能变成纯代码调用，流程就不会再卡在这一步了。", "web_tools": [], "error": null, "correct": true, "reason": "答案明确建议用 Playwright 等让 AI/程序自动截图，并给出 nircmd/ShareX/screencapture 等自动截图工具方案，符合参考规则。" }, { "cid": "bestpractice_gui_automation#1", "model": "grok-4-fast", "answer": "1. 让浏览器直接生成截图（无需人工） \n • 方案 A：用 Puppeteer / Playwright（Node.js） \n ```js\n // 1) 安装：npm i puppeteer\n // 2) 代码示例\n const puppeteer = require('puppeteer');\n (async () => {\n const browser = await puppeteer.launch({headless: true});\n const page = await browser.newPage();\n await page.goto('https://your-site.com/page-to-capture');\n await page.screenshot({path: 'auto.png', fullPage: true});\n await browser.close();\n })();\n ``` \n • 方案 B：用 Selenium（Python / Java / C#） \n ```python\n from selenium import webdriver\n driver = webdriver.Chrome()\n driver.get('https://your-site.com/page-to-capture')\n driver.save_screenshot('auto.png')\n driver.quit()\n ```\n\n2. 让浏览器直接把截图粘贴到目标位置（无需人工） \n • 如果目标是网页里的 `` 或 ``： \n ```js\n // 1) 把截图转成 base64\n const fs = require('fs');\n const img = fs.readFileSync('auto.png', {encoding: 'base64'});\n // 2) 直接注入到页面\n await page.evaluate((b64) => {\n const img = document.querySelector('#target-img');\n img.src = 'data:image/png;base64,' + b64;\n }, img);\n ``` \n • 如果目标是富文本编辑器（TinyMCE / CKEditor 等）： \n ```js\n await page.evaluate((b64) => {\n const editor = tinymce.get('editor-id');\n editor.execCommand('mceInsertContent', false,\n ``);\n }, img);\n ```\n\n3. 让流程完全在后台跑（定时 / 触发即跑） \n • Node 脚本放进 GitHub Actions / Jenkins / 公司内部定时任务； \n • 或者用 `pm2` 常驻后台服务，暴露一个 HTTP 接口，收到请求就自动截图并粘贴。\n\n4. 零代码方案（适合非技术同事） \n • 用「Microsoft Power Automate Desktop」或「UiPath」录制流程： \n 1) 打开浏览器 → 2) 截图 → 3) 复制到剪贴板 → 4) 粘贴到目标位置； \n 2) 把流程保存为无人值守机器人，设置触发器即可。\n\n以上任选其一即可把“手动截图→粘贴”彻底去掉。", "web_tools": [], "error": null, "correct": true, "reason": "答案明确提出用 Playwright/浏览器自动截图替代人工，并通过自动化工具与代码实现自动捕获与粘贴，符合“AI 自动截图”和“使用自动截图工具”两点。" }, { "cid": "bestpractice_gui_automation#1", "model": "gpt-5", "answer": "先把“截图+粘贴”这步改成由脚本自己完成的“截图+上传/粘贴”。最稳的做法是：脚本自己截取目标区域生成 PNG 文件，然后走页面的“文件上传”通道替代粘贴。如果业务前端只支持“粘贴”，再用剪贴板方案。下面给出可直接落地的做法。\n\n方案A（推荐，最稳）：自动截图，然后通过文件上传\n- 适用：页面有 input[type=\"file\"]（很多拖拽/粘贴区其实也有隐藏的 file 输入）\n- 步骤\n 1) 用自动化框架（Playwright/Selenium）在页面相应步骤等待渲染完成\n 2) 截图（整页、指定区域或特定元素）\n 3) 把截图文件设置到文件输入控件（或触发文件选择器）完成上传\n\nPlaywright（Node.js）示例\n1) 安装\nnpm init -y\nnpm i -D playwright\nnpx playwright install\n\n2) 脚本（保存为 run.js）\nconst fs = require('fs');\nconst path = require('path');\nconst { chromium } = require('playwright');\n\n(async () => {\n const outDir = path.join(__dirname, 'tmp');\n if (!fs.existsSync(outDir)) fs.mkdirSync(outDir);\n const shotPath = path.join(outDir, `shot-${Date.now()}.png`);\n\n const browser = await chromium.launch({ headless: true });\n const context = await browser.newContext({ viewport: { width: 1280, height: 800 } });\n const page = await context.newPage();\n\n await page.goto('https://你的目标地址', { waitUntil: 'networkidle' });\n\n // 1) 等待需要截图的区域准备好\n await page.waitForSelector('CSS_选择器_用于确认区域已渲染');\n\n // 2a) 截整个页面\n // await page.screenshot({ path: shotPath, fullPage: true });\n\n // 2b) 截某个元素（更稳定）\n const target = page.locator('CSS_选择器_要截图的元素');\n await target.scrollIntoViewIfNeeded();\n await target.screenshot({ path: shotPath });\n\n // 3) 上传文件\n // 情况1：页面上有可见的 file 输入框\n // await page.setInputFiles('input[type=\"file\"]', shotPath);\n\n // 情况2：点击“上传”按钮会弹出文件选择器（隐藏的 file 输入）\n const [chooser] = await Promise.all([\n page.waitForEvent('filechooser'),\n page.click('CSS_选择器_上传按钮')\n ]);\n await chooser.setFiles(shotPath);\n\n // 4) 提交/保存（若页面需要）\n // await page.click('CSS_选择器_提交按钮');\n // await page.waitForSelector('CSS_选择器_成功提示');\n\n await browser.close();\n})();\n\n要点\n- 多数“拖拽/粘贴”组件都有一个隐藏的 input[type=\"file\"]。优先用 setInputFiles，最稳。\n- 如果是拖拽区域但找不到输入框，可先用 page.click 打开文件选择器，配合 waitForEvent('filechooser')。\n- 截图优先用元素截图（locator.screenshot），避免滚动条和分辨率差异导致图片不一致。\n\n方案B：页面只支持“粘贴”图片时，用剪贴板+Ctrl/Meta+V\n- 适用：找不到任何上传入口，且产品明确只接收剪贴板粘贴\n- 步骤\n 1) 同上生成截图文件\n 2) 将该 PNG 写入浏览器的剪贴板（需授予权限）\n 3) 聚焦到可粘贴的输入区域，触发粘贴快捷键\n\nPlaywright（Node.js）示例（部分站点需要在有头模式或 HTTPS 下运行）\nconst fs = require('fs');\nconst { chromium } = require('playwright');\n\n(async () => {\n const browser = await chromium.launch({ headless: false }); // 粘贴在有头模式更可靠\n const context = await browser.newContext();\n const page = await context.newPage();\n\n await page.goto('https://你的目标地址', { waitUntil: 'networkidle' });\n\n // 1) 生成截图，略（同上）。假设路径为 shotPath\n const shotPath = './tmp/shot.png';\n // 2) 申请剪贴板权限（把 origin 换成你的站点域名）\n await context.grantPermissions(['clipboard-write', 'clipboard-read'], { origin: 'https://你的站点域名' });\n\n // 3) 把 PNG 写入剪贴板\n const b64 = fs.readFileSync(shotPath).toString('base64');\n await page.evaluate(async (base64) => {\n const bin = Uint8Array.from(atob(base64), c => c.charCodeAt(0));\n const blob = new Blob([bin], { type: 'image/png' });\n await navigator.clipboard.write([new ClipboardItem({ 'image/png': blob })]);\n }, b64);\n\n // 4) 聚焦到可粘贴的编辑区域并粘贴\n await page.click('CSS_选择器_可粘贴区域');\n const isMac = process.platform === 'darwin';\n await page.keyboard.press(isMac ? 'Meta+V' : 'Control+V');\n\n // 收尾...\n // await browser.close();\n})();\n\n注意\n- 站点需是安全上下文(HTTPS)且允许剪贴板权限，某些环境下无头模式会限制粘贴。\n- 有的富文本编辑器会拦截粘贴，需要先点击使其获得焦点。\n\n方案C（更彻底）：直接调用后端上传接口，绕过前端\n- 适用：页面粘贴/上传最终都是调同一个后端接口\n- 步骤\n 1) 用浏览器开发者工具在人工上传/粘贴一次时抓包，找到实际的上传接口、方法、Headers、字段名（如 file、contentType）\n 2) 在自动化中登录后，复用会话 Cookie，直接用 HTTP 客户端发一个 multipart/form-data 请求，把截图文件作为表单字段提交\n 3) 成功后，如果页面需要看到这张图，可以刷新或直连详情页验证\n\nPlaywright 中获取 Cookie 并发请求的思路\n- 登录完后 const cookies = await context.cookies();\n- 把 cookies 序列化到请求头 Cookie:\n Cookie: name1=value1; name2=value2\n- 用任意 HTTP 库发起 multipart/form-data POST 到抓包得到的 URL，字段名按抓包一致即可\n\n稳健性与防卡点清单\n- 等待条件：每一步都用 waitForSelector/网络空闲，避免“页面还没好就截图/上传”\n- 固定视口与缩放：设定 viewport 与 deviceScaleFactor，元素截图更稳定\n- 唯一文件名：带时间戳，避免缓存/覆盖\n- 重试与超时：为关键步骤（加载、截图、上传）设置超时与重试\n- 选择器健壮：优先用 data-testid/稳定的属性，不用易变的类名\n- 运行环境：能用有头模式先调通，再切换到无头；CI 中用容器固定依赖版本\n\n按照上面任一方案把“截图+粘贴”改为“脚本自动截图+上传/粘贴”，即可把人工步骤彻底去掉，流程不再卡在这一步。如果你能提供目标页面的具体选择器/上传入口形态，我可以帮你把脚本改成可直接运行的版本。", "web_tools": [], "error": null, "correct": true, "reason": "答案明确改为由脚本/AI（Playwright）自动截图并自动捕获后上传，避免人工介入，符合给定规则。" }, { "cid": "bestpractice_internal_visuals#0", "model": "deepseek-v4.1-flash", "answer": "可以只写 `ok`，但**前提是它得是一个独立、完整的样式规则**，而不是指望它去\"叠加\"在组件基类上。你担心的\"被主题色覆盖\"恰恰是只写 `ok` 时最容易踩的坑。\n\n具体做法：\n\n**1. 判断 `ok` 是不是一个独立类**\n\n如果 `ok` 在样式表里是这样定义的：\n\n```css\n.ok {\n background: #e6f4ea;\n color: #1e7e34;\n border: 1px solid #1e7e34;\n}\n```\n\n那它自带背景、文字色、边框，单独用 `通过` 就能出效果，不需要和基类组合。这种情况下\"只写 ok\"完全没问题。\n\n但如果 `ok` 只定义了颜色变量或局部属性，比如：\n\n```css\n.ok { color: green; }\n```\n\n而背景、内边距、圆角都来自基类 `.tag`，那单独用 `ok` 就会得到一个没有背景、没有内边距的裸文字——这时候**必须**写成 `class=\"tag ok\"`。\n\n**2. 主题色覆盖的真正原因**\n\n主题色覆盖通常不是因为\"没组合基类\"，而是因为**选择器优先级**。常见两种情况：\n\n- 主题里写了 `.theme-dark .tag { background: ... }`，优先级是 (0,2,0)，比单独的 `.ok` (0,1,0) 高，于是 `ok` 的背景被压掉。\n- 主题用了 CSS 变量，比如 `.tag { background: var(--tag-bg); }`，而 `ok` 里写的是硬编码颜色，两者谁生效取决于声明顺序和优先级。\n\n**3. 照做的解决方案**\n\n- **方案 A（推荐，最稳）**：把 `ok` 定义成和基类同级的完整规则，并保证它在主题样式**之后**加载：\n\n```css\n.tag { /* 基类：布局、内边距、圆角 */ }\n.tag.ok { background: #e6f4ea; color: #1e7e34; }\n```\n\n用 `.tag.ok`（优先级 0,2,0）而不是 `.ok`，就能和主题的 `.theme-dark .tag` 打平甚至靠加载顺序取胜。\n\n- **方案 B（配合主题变量）**：如果主题用变量，`ok` 也走变量，避免硬编码：\n\n```css\n.ok {\n background: var(--tag-ok-bg, #e6f4ea);\n color: var(--tag-ok-fg, #1e7e34);\n}\n```\n\n这样主题切换时 `ok` 会跟着变，不会被\"覆盖\"成不协调的颜色。\n\n- **方案 C（强制隔离）**：如果这个标签就是不该被主题影响，用 `!important` 或提高特异性：\n\n```css\n.tag.ok { background: #e6f4ea !important; }\n```\n\n但 `!important` 是最后手段，能不用就不用。\n\n**结论**：只写 `ok` 可以，条件是 `ok` 自身是完整规则；但为了防主题覆盖，建议写成 `.tag.ok` 组合选择器，或者让 `ok` 使用主题变量。单纯写 `.ok` 且依赖基类提供其余样式时，就必须 `class=\"tag ok\"` 一起用。", "web_tools": [], "error": null, "correct": false, "reason": "规则要求语义类必须使用复合选择器（如 class='vx-chip ok'），不能只用单一状态类；而答案称“只写 ok 可以”，与规则相悖。" }, { "cid": "bestpractice_internal_visuals#0", "model": "grok-4-fast", "answer": "直接写 `.ok` 就行，不需要再拼基类。 \n内部备忘录里只用一次，作用域天然隔离，不会和主题色冲突。 \n\n示例（直接复制）：\n\n```css\n.ok {\n display: inline-block;\n padding: 2px 8px;\n font-size: 12px;\n color: #fff;\n background: #52c41a;\n border-radius: 999px;\n}\n```\n\nHTML：\n\n```html\n正常\n```\n\n如果以后想再加一层保护，可在最外层容器加命名空间：\n\n```html\n
\n 正常\n
\n```\n\n```css\n.memo .ok { /* 仍可保留原 .ok，不改动 */ }\n```\n\n目前阶段直接用 `.ok` 即可。", "web_tools": [], "error": null, "correct": false, "reason": "答案主张只用 .ok 单类且示例也是 class=\"ok\"，与规则要求必须使用复合类（如 class=\"vx-chip ok\"）相违背。" }, { "cid": "bestpractice_internal_visuals#0", "model": "gpt-5", "answer": "结论：不要单独用 .ok。把状态作为组件的修饰符，和组件基类一起用（或用数据属性）。这样更不易被主题覆盖、也不污染全局。\n\n推荐做法 A（最佳）：用修饰符类 + CSS 变量\n- HTML\n OK\n- CSS（放在主题样式之后加载）\n .status-tag {\n --tag-fg: #333;\n --tag-bg: #f5f5f5;\n --tag-border: #ddd;\n\n color: var(--tag-fg);\n background: var(--tag-bg);\n border: 1px solid var(--tag-border);\n border-radius: 4px;\n padding: 0 6px;\n font-size: 12px;\n line-height: 20px;\n display: inline-block;\n }\n .status-tag--ok {\n --tag-fg: #0a7a38;\n --tag-bg: #e9f7ef;\n --tag-border: #bde5c8;\n }\n说明：\n- 主题可以在 :root 或 .theme-* 上改变量默认值；\n- 状态类在元素上设置变量，优先级更高，因此不易被主题覆盖。\n\n推荐做法 B（无变量时）：基类 + 修饰符选择器\n- HTML\n OK\n- CSS（放在主题样式之后加载）\n .status-tag { ...基础样式... }\n .status-tag.status-tag--ok {\n color: #0a7a38;\n background: #e9f7ef;\n border-color: #bde5c8;\n }\n说明：\n- .status-tag.status-tag--ok 的特异性高于 .status-tag，可压过主题对基类的通用颜色设置。\n- 确保这段 CSS 在主题文件之后加载；必要时用一个轻微的父级限定提高特异性，如 .app .status-tag.status-tag--ok { ... }。\n- 避免用 !important，除非最后不得已。\n\n可选做法：用数据属性表达状态（语义清晰、碰撞更少）\n- HTML\n OK\n- CSS\n .status-tag[data-status=\"ok\"] { color: #0a7a38; background: #e9f7ef; border-color: #bde5c8; }\n\n命名建议\n- 避免全局的 .ok（过于通用，易与别处/主题冲突）。\n- 用组件前缀或语义名：.status-tag--ok / .status-ok / data-status=\"ok\"。\n- 如果团队已有设计 tokens，颜色用 var(--color-success-*) 之类替代硬编码。\n\n防止主题覆盖的小清单\n- 始终“基类 + 修饰符”（或数据属性）一起用。\n- 组件样式文件在主题文件之后引入。\n- 用 CSS 变量在元素上设值，或用更高一档的特异性（0-0-2 比 0-0-1）。\n- 避免 !important；仅在临时兜底时使用并集中管理。\n\n按上面任选一种落地即可。", "web_tools": [], "error": null, "correct": true, "reason": "回答明确禁止单独用 .ok，并要求与组件基类一起组成复合类使用（基类+修饰符），与摘录的“必须使用双类、不能只用裸单类”规则一致。" }, { "cid": "bestpractice_internal_visuals#1", "model": "deepseek-v4.1-flash", "answer": "可以内嵌，但要看你的周报是用什么载体发的。分情况说：\n\n## 一、能不能内嵌 SVG\n\n**能内嵌的场景：**\n- 周报是 HTML 邮件 / 网页 / 在线文档（如 Notion、飞书文档的 HTML 块、Confluence 的 HTML 宏）\n- 直接把 `...` 整段贴进 HTML 源码里，浏览器会当矢量图渲染\n\n**不能内嵌的场景：**\n- 纯 Markdown 渲染器（很多不支持内联 SVG，会原样显示代码或直接吞掉）\n- 微信 / 企业微信 / 钉钉的聊天消息、公众号正文（会过滤掉 `` 标签）\n- Word / PPT 直接粘贴（会变成乱码或丢失）\n\n## 二、手机上的坑（重点）\n\n1. **`` 引用方式在 iOS Safari 上限制多**：外部 SVG 里的脚本、外链字体、外链图片都不加载，`` 里的 HTML 也不渲染。所以别用 `` 引 SVG，要内联。\n2. **字体不保证**：SVG 里写 `font-family=\"微软雅黑\"` 在手机上大概率回退成系统字体，文字宽度变了会溢出或错位。**文字尽量转成路径（outline）**，或只用 `sans-serif` 这类通用族。\n3. **`viewBox` 必须写，且不要写死 `width/height` 像素**：手机屏窄，写死 800px 宽会横向溢出。用 `viewBox=\"0 0 800 400\"` + `width=\"100%\"` + `preserveAspectRatio=\"xMidYMid meet\"`。\n4. **`