assistant/docs/DESIGN.md

# 橘子拓客：当前设计与实施范围

> 2026-10-28 用户明确将本项目从学校办事助手转为 AI 拓客助手，首个平台为小红书。本窗口只开发此项目；同级 `assistant/` 独立保留。
> 原学校设计见 [历史归档](archive/DESIGN-school-2026-10-28.md)，其中查课、谈话、角色准入、填报、审批与回查链路退出当前运行入口。

> 用户已明确要求开始实现 [AI 拓客助手优化方案 v0.1](AI拓客助手优化方案-v0.1.md)。以下记录本次实施状态；真实平台与业务效果的验收另列，不由本地测试替代。

> 2026-10-29 用户已批准执行 [结果交付与知识复用优化方案 v0.3](橘子拓客结果交付与知识复用优化方案-v0.3.md)。结果交付、必要字段、程序验收、独立证据排名及知识界面已首轮实现；实际跨任务复用、完整平台链路与业务效果继续待验收，不能由本地样本推导。

> 2026-10-30 按用户《橘子拓客 纠偏方案 v1》调整方向：以正常规模候选交付的真实调用、token及时间衡量主链路，不继续D44回复直接父归属或预检专项。用户确认继续后已执行P1基线，实际交付2/10位并按取证停滞停止，等待监督确认后才进入P2；以下D20–D44记录作为历史，不作为继续专项开发或复测的授权。

### P0：默认关闭实验性回复关系与预检

`Settings.reply_relation_preflight_enabled`（环境变量 `REPLY_RELATION_PREFLIGHT_ENABLED`）默认 `False`，统一控制两个模型工具 `inspect_reply_relations` / `resolve_reply_target`、预检正则路由、编排、提示、执行gate及交付投影。默认不调用 `compile_preflight_policy` 改写意图；显式开启时保留原实现。续跑时也从已有Agent移除关闭工具并刷新动作Schema，保留实际浏览器及2px park规则。开关是后端启动配置，本轮未重启桌面端，不能把新进程离线审计说成现有进程已重载。

`save_source` 仍逐字核对真实独立容器并先持久化来源；成功只证明原话核验及保存，不再因回复父关系未知记为unknown。`parent_resolution`、父/根引用、诊断及 `relations_checked` 独立保留，不猜父关系；工具下一步与默认提示不再要求补父容器、重存回复。用户明确要求关系时的交付条件仍独立校验，不能由保存success推出关系完整或整条获客链已完成。`evidence.json` 恢复及历史事实不回填。旧知识方法的同版本定义不可变，P0不改库或迁移旧文案；其保存成功不得解释成父关系成功，流程定义与成本口径留待P3按新版本处理。

本机验证覆盖默认关闭、显式开启、历史投影、旧会话续跑、未知父关系保存与逐字核验。另以既有真实发现任务只读重建当前模型契约，确认25个动作中两个实验工具均不存在；证据为 `data/ui-verification/p0-default-tool-schema.json`。此为当前代码将发送的Schema审计，未发模型请求，不是历史请求或真实上游收到的回执；严格真实请求侧验收尚待取得。

P1已重新启动当前代码，补齐P0真实请求侧核对：`task_76d551192d7e` 的44份出站动作Schema均关联同call_id的供应商response及succeeded；实际24个动作，两个实验工具均不存在。此回执属于P1新任务，不补写P0离线审计或历史任务。

### P1：装修服务主链路基线（已测量，业务未达标）

用户明确商品为装修服务，目标客户为近期要装修的用户，无地区限制；目标10位，只读，不设篇数或评论数上限。桌面创建独立任务 `task_76d551192d7e`，输入已有“10位去重候选”仍重复追问，按同一目标填10后继续，未修解析或调参。新增的代码仅为程序测量：真实模型出站契约的安全元数据、实际工具边界事件及 `scripts/measure-prospecting-baseline.py`；不记录参数、提示、Key或完整Schema，不改变请求和业务控制。

任务以 `evidence_stalled` 停止：实际访问4篇，3篇取得核验摘录，保存正文3、评论6、回复0；分析9条后保留2位稳定来源身份候选，身份未知候选0，尚缺8位。单候选23.5次调用、570242.5 tokens、98.885秒；总47次调用/1140485 tokens/44个步骤/50次实际工具调用/197.77秒。实际总时间包括人数补问；供应商usage完整，缓存命中858496输入tokens，未换算费用账单。任务内 `baseline.json` 和PROGRESS保存分阶段指标及工具分布，不能将未达10位当作完整业务闭环或降本成功。

已确认检查18次与保存12次占实际50次调用的60%；保存校验拒绝3次，末尾连续3次来源容器检查失败触发原保护；4次评论区推进中3条有记录的尝试均not_moved，展开0。最底层容器失败分支尚无法从持久化记录确认。P2应围绕这些实测问题将当前笔记内的推进、读取、逐字保存与展开程序化，保留原校验及真实失败原因；不继续回复父归属专项，不增加未经本轮失败支持的新约束。P1缺少10位完整基线，后续不能宣称已取得同等10位交付的50%降本验收。

## 1. 产品与首个闭环

用户用一段自然语言描述目标 → 模型识别意图、提取已有条件并生成关键词 → 必要缺项才追问 → 按阶段搜索/检查指定页面 → 阅读笔记、评论及回复 → 核对主页或整理导出 → 独立复盘与用户评价。对话支持在同一任务修订标准和继续，目标版本、来源和动作历史保留。

当前首版交付：蓝灰玻璃面板的单段持续对话、可收放历史与设置抽屉、按需展开的执行浏览器、可展开理解卡、无默认阅读配额、真实停止原因、评论与回复取证、主页身份核对、CSV名单导出、点赞点踩与单条纠正、独立经验复盘、受授权的关注/私信工具及账号动作账本。继续保留页面证据、人工登录/验证、模型设置和可选公开资料工具。

用户进一步指定按小鹅网页复刻视觉与动效；布局、粒子轮廓、翻转关键帧和验证范围见 [界面参考记录](UI_REFERENCE_PENGUIN.md)。动画与真实任务状态关联，减少动态时静态呈现，不用演示数据或动画冒充任务成功。

用户已批准实施 [UI 优化方案](UI优化方案-v0.2.md)。当前已分离默认品牌粒子、对话粒子和结果组装，并接入必要补充、真实阶段、来源核验、名单表格、文件交付及受限后的独立路线。补充卡和路线提交校验任务及结果版本；文字与卡片回答沿同一任务接续，旧卡保留只读历史。精确粒子轨迹仍需参考连续画面对照，现为独立流动实现。

2026-10-29 用户进一步指定品牌为类似“小火花”的造型：界面标识和默认粒子已改为共享圆润火花轮廓、独立浮滴和白色笑脸，使用贴合玻璃面板的银蓝配色，不使用用户提供的红色JPG。对话流动粒子和结果方阵继续独立保留；参考网页只指导布局及交互表现，不再沿用其品牌形象。

同日正式改名为“橘子拓客”，助手昵称“小橘”。窗口、页面、关于面板及产品元信息统一名称；应用图标沿用现有银蓝小火花并加浅蓝圆角底，提供SVG、1024透明PNG、macOS ICNS和Windows ICO，源码运行时设置Dock/窗口图标，打包配置引用相同资源。npm包名、appId及既有用户数据目录保持稳定，改名不创建空配置或丢失历史；图标由 `scripts/generate-app-icons.mjs` 从已有SPARK路径离线生成，普通构建使用仓库内成品，不新增运行依赖。

同日D39按实际任务状态调整输入框：消息提交中或当前任务 `running` 时，右侧显示转圈状态；HTTP提交返回后仍以持续任务状态展示，不因一次请求结束恢复发送箭头。执行中仍能输入并发送补充说明，停止沿用任务内按钮；暂停、等待补充及结束状态恢复发送图标，减少动态时保留静态进度图标。macOS窗口使用 `hiddenInset` 保留原生三个窗口按钮，40px浅蓝灰可拖动栏在按钮右侧显示标题；Windows/Linux保留原生标题栏，普通浏览器预览不显示桌面栏。内容及原生浏览器插槽按实际DOM边界下移，不改2px park或视图缩放。隔离界面已验证提交后持续转圈、补充、完成与停止的切换，真实原生标题栏核对见D39运行记录。

`max_notes/max_comments_per_note` 默认 null，仅用户明确指定时生效。新拓客任务及迁移后续跑不使用60步或600秒总量终止；单次工具/模型超时仍保留。框架按无限执行范围运行，屏蔽预算收尾提示并保留消息压缩、用户中断和无进展保护。累计操作台账保留，损坏台账不重置为0。

2026-10-29 用户补充：不能没有终点一直跑。发现候选以用户明确的 `target_candidates` 为交付目标，未给人数、指定页面、明确篇数或“先做一轮”范围时，只补问“这次先整理多少位候选？”。纯数字卡片/对话确认直接接续同一任务，不再调用意图模型。人数与笔记/评论条数分别处理；程序检查用户原话，不接受模型擅猜10位或20位。复杂/中文数字表达暂保守补问，不能自动猜值。检查、研究、导出及明确跟进范围不强求候选人数。

候选按来源作者主页的稳定身份合并，同名不合并；只有线索里的昵称/链接推测不算身份证据。身份未知来源单列，不计达标；主页可见小红书号仍需独立核对。逐步保存后按剩余目标分段分析，达标时在下一次网页/模型调用前停止；关键词未遍历范围继续如实保留。未达标、采集失败或同页反复取证无新增时交付阶段结果，用户决定调整数量/方向或继续，不自动换路线无限跑。人数按本次必要条件统计，不等于有效客户或成交数。修改标准后旧结果保留但不计当前达标，数量单独修改可复用已判断资料。

v0.3由 `delivery.py` 与 `people.py` 统一交付和人数口径：运行状态、目标满足、文件产物分别计算，保留原浏览器失败与停止原因。可选字段缺失不阻止交付；用户明确要求的本人需求、地区、可见账号号和CSV才成为必要条件。地区须本人该来源原话支持，IP或父评论不能代填。有限范围需实际成功采集、逐来源判断及覆盖依据，未取得资料不能称零需求。结果逐项展示需求、身份、地区、账号、跟进及可选用户后续反馈，补充来源/未知身份另列，不再统一要求人工待复核；CSV沿同一口径保留全部证据与缺项。

## 2. 复用与重做

复用 Electron/React 桌面壳、内嵌 WebContentsView、browser-use CDP 执行器、暂停/续跑/接管、逐步截图与进度记录、PostgreSQL 持久化、经验试用与回执数据结构。新增独立 `backend/prospecting/` 编排和 API；当前入口不挂载学校业务路由，不调用学校 NLU、填报或审批状态机。

商家条件、拓客阶段、来源结果、业务判断与验收全部重做。原学校知识 YAML 仅作为历史资料保留；新运行只加载小红书拓客知识，使用独立租户作用域隔离旧学校任务和经验。兼容数据层的 `school_id/student_id` 暂保留为内部租户/操作者字段，界面不出现学校身份。

## 3. 业务判断和证据

- 商品/客户/地区按任务需要提取，不统一设为必填；关键词可由助手生成并在计划中说明推断。地区未提供即未知，不擅自补成全国。
- 作者、首层评论者和每位回复者分别判断，保存父/根/回复对象关系；分享、教程和一般咨询不等于正在购买服务。“正在装修”与“明确找服务”作为不同判断维度，不能擅自缩窄目标。
- 每条候选保留来源 URL、来源类型、原话、理由、观察时间；按已有证据具体说明字段状态，不自动确认客户身份或成交意向。
- 名单与CSV共用按人分组，合并同人的全部原话、来源和纠正；身份待核记录另列。增量分析保留正文/父根上下文，按note_id或已观察笔记路径关联，不因临时签名链接变化丢失讨论背景。
- 小红书阅读以实际页面为准，登录/验证码/访问限制暂停请用户处理；不把未读评论记为空，也不以搜索摘要代替已读笔记。
- 来源完整 URL 由程序从当前页面读取，不要求模型寻找 canonical 或重建签名链接。先观察当前可见来源容器及原文，再逐条保存；候选容器仅来自当前真实 DOM。
- 浏览器会话结束后，右侧切换为标明只读的最后截图及结束原因；不保留已销毁原生视图的空区域，也不把截图称为可操作网页。
- 发现与整理不自动授权触达。关注/私信先只读核对账号与对象，再由用户选择具体批次；私信另需确定内容。实际动作必须使用受约束工具，核对发送账号、目标和输入内容，先持久记账再操作；已关注跳过，结果未知不重发。跟进执行配置关闭通用click/input/send_keys，避免绕过账本。
- 私信出现红色失败标记或未知结果，持久暂停该账号后续私信；仅页面明确每日限制时标记当日上限。重新核对页面且无已知限制、用户明确确认后才解除，保留历史且不自动重放未知动作。此次开发没有对真实账号执行关注或私信。
- 检索覆盖来自实际观察到的搜索页URL，分别记录已观察和未核对关键词；未核对范围不冒充已读。相同页面、相同动作且无新增来源连续重复时停止无进展操作。停止原因由程序记录，模型总结另存，不能用模型“预算耗尽”解释真实终态。
- 已保存资料复核完成不等于网页采集完成。`done(success=False)`保留失败原因，复核同时检查原浏览器结果；旧误标任务通过只读投影展示阶段结果，原日志与数据库保留。检索覆盖接受实际观察到的`search_result_ai`路径并有限解码，不推断未观察的访问或全文阅读。

## 4. 学习闭环

操作能力、阶段模板、业务反馈与本次任务资料分层保存。阶段结束、暂停或异常后独立运行复盘；模型可提出探索候选，不能自报成功。`knowledge.py` 使用工作区隔离的 `prospecting_methods`、`prospecting_validation_events`、`prospecting_business_feedback` 保存方法版本、不可变事件和反馈；`verification.py` 将程序动作事实同步为方法及验收回执。旧通用经验表兼容保留，当前召回改用结构化方法，不再靠模型相符回执升级旧草稿。

程序验收接保存独立来源、展开当前父讨论的新增回复、匹配来源作者的主页号及当前结果文件；只有完整前后引用、程序验证方式与实际后置条件才能计成功。无新增、加载慢、归属不明记未知；受阻、程序故障和未使用分别记录，不冒充方法反证。详细前后快照只保存在对应任务证据，共享事件保存引用和对象摘要。知识界面按原验证事件取对应动作前后快照，阶段证据不能用单一动作的快照替代。

复用先检查平台、阶段、能力、来源类型、适配器版本、依赖版本及授权，再按独立证据和内部样本修正指标排序。首版至少3个独立任务、3个不同对象且没有未解决反证才进入优先复用；一次成功为可试用，无证据为探索候选。任务/对象最大独立匹配去重，同对象重试、恢复与重复导出不能抬分；修订以新事件关联原记录，依赖失效会重算阶段状态。高等级方法遇相关反证仍暂停。规则 `independent-evidence-v1` 是选择规则，不是成功/成交概率。

当前参数化阶段仅验收同篇正文与一条独立评论/回复均保存的实际分支，依赖真实操作事件；没有把各动作拼成已验证的完整搜索/主页/触达链路。`xhs_visible_dom_v1` 是当前DOM适配器版本，不是平台所有页面变体分类，每次操作仍需现场入口与归属核对。更细页面变体、其他阶段组合及业务策略排名继续待真实样本积累。

2026-10-29 首个新版真实任务审计（D37）：正文保存及CSV导出各形成1次有程序依据的独立成功，两方法均可试用；本次召回为空，尚未证明跨任务复用。评论/回复/主页链路未跑通。实际长句还暴露人数识别、账号可选及明确需求条件的程序提取缺陷，悬浮卡反复点击与8次动作结构错误导致部分交付；新建内嵌会话分支漏传目标版本，不能回填历史猜值。这些为当时待修问题，优先修复并沿原任务小范围验收，再继续不同对象的复用测试。

同日D38已实现上述首轮修复并通过本地回归：长修饰语的人数绑定到候选对象，跨逗号可选账号不变必填、明确需求单独校验；旧任务仅在用户明确继续时按原话重核编译字段，保留后确认人数及原证据/文件版本。评论未进视口有明确状态，新增受约束的 `advance_comments` 原生点击/滚动及 `open_source_profile` 来源作者入口；重核稳定评论ID、原话与真实唯一链接，悬浮卡原地无推进不能反复点，不猜URL。导航观察仅留任务事实，不直接新增方法成功。

无进展保护按页面、操作目标与真实新增累计，临时节点索引、悬浮卡、等待、空滚动、失败导航或未知展开日志不能清零；真实页面/滚动/来源变化才算推进。Schema失败仅记录程序声明字段路径和标准错误类型，供正常下一步纠正，不额外调用修复模型；连续失败保留程序原因，401/402/429保留实际具体类别。新内嵌会话也传目标版本，旧缺失不回填。知识页区分本阶段不适用与相关反证暂停，不显示跨阶段的误导性零成功。真实平台兼容和复用仍需下一次已授权任务验收，不能由本地夹具直接判为已修通整链路。

同日D39只读复查用户已续跑的原任务：条件已按原话修正为CSV及本人明确需求，保留用户后来确认的1位，目标版本3；新增1篇有实际作者主页锚点关联的需求正文后，程序以 `target_reached` 在1/1停止并交付。当前2条正文中1位达标、1组身份未知，CSV保留两者。任务内召回正文保存方法，并新增具有目标版本及可读取前后快照的保存/导出事件；这仍是同任务续跑，两方法各只有1个独立成功任务，不算跨任务复用。评论、回复展开及完整主页打开均未执行：正文先达目标，不能据此称评论/主页新工具已通过真实验收。下一次验证应给指定笔记及有限讨论阅读范围，避免候选人数达标提前结束这一专项检查。

同日D40按用户授权由CUA新建有限只读验证任务：指定1篇笔记、inspect、评论与回复合计最多8条，不继承候选人数；实际取得正文1、评论5、回复3，无触达。回复的父根及回复对象字段为空，3次回复操作验收正确保持unknown；无专用展开调用或展开事件，不能判完整讨论链路通过。当前completed对用户明确的展开及归属要求表达过强：先修回复归属，再补范围完成校验，随后重做同类有限验证；旧来源不补造父根。已观察到正文方法在新任务召回并再次执行，保持trial，不把同篇对象重查当作新对象覆盖。原生浅色左标题栏已取得真实截图，窗口按钮仅AX存在、像素未核实，拖动及全屏仍未验收；运行与结束按钮标签切换已在真实任务核对，持续旋转像素仍沿用隔离验证范围。

同日D41已修复正文候选与保存观察对`.content > .note-text`的定位差异，支持明确讨论组内根评论与回复列表为兄弟节点的结构；平级回复存在明确回复对象但缺少唯一评论引用时，只确认根讨论、保留直接父评论未知。展开入口按当前真实讨论组观察，支持div文字入口、已渲染但未进入视口的定位及白名单筛选计数；按实际位置先推进视口，使用专用展开工具核对同组完整前后回复集合，不能由5条取证批量或其他讨论新增冒充展开。指定页面的inspect/research任务仅从用户直接要求提取评论、回复、展开及关系条件，缺项时交付阶段成果；阅读上限不当作最低条数，不由模型done宣告全部完成。两次同组有限实测均取得正文1、评论1、回复1，根关联已恢复；第二次专用展开有同owner新增1条及完整快照的程序成功，直接父评论仍未知。真实合法摘录与展开全文指纹存在严格匹配假阴性，离线精确核对已确认该新增摘录，但程序归属修复的最终状态见D41记录；不补写历史来源或事件，不据此升级整链路。现已增加程序观察的完整容器规范指纹：保存原话校验与展开后新增容器采用相同规范，按当前目标版本及真实保存事实绑定合法摘录；额外只读观察失败保留未知，不重试点击或模型。1017项本地回归通过，未补旧指纹、未启动第三轮付费任务。后续正常任务验证新绑定和直接父评论与回复对象；无须为凑成功重复运行相同范围。浅色左标题及原生三个窗口按钮已取得真实截图，拖动和全屏仍未测试。

同日D42继续修复实际目标头部/标记/主页身份与同组唯一父回复的核对，缺唯一依据或冲突仍未知。新增真实用户会话驱动的第一组/一组范围，在检查与保存两侧约束根key，续跑只刷新正式请求及目标版本，不覆盖未落盘证据；归属要求支持完整回复链及直接父回复等自然说法，显式回复父回复的新增子回复另有独立深度条件，不能用根→直接回复代替。浏览器paint/hit测试核对当前可命中点后使用原生mouse，不按旧坐标盲点。`resolve_reply_target`从实际前缀入口原生移入，重新核对来源及命中点后单击；只有真实主页身份、原生返回及原来源重新核对都成立，才以本轮短期依据匹配同组唯一父回复，同作者多条发言仍未知。宿主仅允许页面实际触发的小红书HTTPS主页弹窗在同一视图打开，诊断只保留白名单分类和动作，不拼URL。

DeepSeek浏览器适配改为标准端点强制命名函数提交完整输出并本地校验，保留图像、usage及关闭思考；结构拒绝内部422，安全纠错提示随正常下一步，不增独立修复调用。D42两任务及同篇续跑累计111次实际调用，110次成功、1次连接错误、Schema错误0；未知连接原因和未返回usage不推断为格式、欠费或零消耗。工程上全后端1209项、Node弹窗11项、TypeScript及桌面构建通过；真实业务上明确组范围、专用同组展开及容器绑定取得验证，但目标子回复仍为直接父未知，关系3/4、二级分支0/1。手动实际作者头部链接可打开完整主页，回复前缀点击仍无导航或弹窗，返回未成功；不能用作者主页替代回复目标身份或宣称整链路通过。目标版本2追加网页回查误走已有来源分析，现已按真实追加指令在意图落地、准备与执行处纠正：明确网页核对优先进入浏览器，已保存/不新增来源只限制范围；纯离线复核仍复用。回查从当前页与原生历史起步，明确禁止分析时保留旧判断及版本，不增加收尾分析调用。该路由修复通过本地回归，尚无修正后的实页回执。旧目标展开不能计入新目标，交付继续partial；同篇续跑不增加独立对象排名。详细实测、用量及资料完整性见D42记录。官方协议依据：[Tool Calls](https://api-docs.deepseek.com/zh-cn/guides/tool_calls/)、[Chat Completions](https://api-docs.deepseek.com/zh-cn/api/create-chat-completion/)。

同日D43本人登录后，在新笔记做首组只读验收。首个当前页续跑曾误导航应用UI，后增加task→view→target锁、上下文和逐act状态边界及显式当前页修订时的view保护；丢失或错误业务目标不猜地址恢复。标准JSON Schema导出补minItems与单动作项属性数约束，仍完整校验，不修坏JSON或补动作。1251项后端、TypeScript、构建及Node弹窗11项通过；保留liveview的修订竞态仅有本地回归，不用显式入口的实页结果替代。初始目标版本1候选浏览最多2篇，版本2/3明确只当前新笔记第一组，范围为正文最多1条、评论与回复合计最多4条；三版属于同一任务，不按修订次数加独立分。最终目标版本3实测正确新业务页、正文1/评论1/回复2、专用同组展开新增2和规范容器绑定、无名单分析或触达；首条普通回复父根正确，明确二级子回复仍只有根讨论和可见目标文字，无唯一目标主页身份，实际目标点击not_moved，主页返回重核未验。当前UI为4条阶段资料、部分交付，关系1/2、二级0/1。整任务25调用含早期1结构拒绝，最后13调用零结构错误，不称全轮零错误。正文方法有3独立任务/3对象而进入preferred，其它相关操作2/2仍trial、阶段链paused；新笔记不等于二级身份已可核对，不为凑通过追加同类付费续跑。

同日D44开始将样本预检与取证分开：`inspect_reply_relations`只读当前可见组，只有稳定且唯一的直接父为另一条回复才为eligible；需要原生身份、冲突和未知均不合格，预检不自动展开、保存、打开目标或形成方法成功。首个有限任务13次调用全部成功，但实际打开两篇新笔记及一篇排除旧笔记，且预检原始计数未持久化，不能认可严格范围或把模型报告的0/0当程序验收。随后增加独立安全预检遥测、当前run/目标版本的实际访问gate及预检专属交付：确认可见且范围完整时，零合格也可作为“预检完成，未发现合格样本”；未到视口、访问记录缺失、越界或未知继续保留限制，不能假称读完。纯预检应跳过保存方法召回、名单分析及知识成功验收。第二个独立任务6次调用全部成功，程序确有0/0未到视口及1/0未知的遥测，实际仅一篇指定笔记、无保存或触达；但“独立做一轮只读预检”未被策略解析识别，访问gate、专属交付及知识过滤未启用，仍落到普通无来源blocked。1400项后端、TypeScript、构建及4项SSR检查是该修正阶段的本机结果，不能覆盖真实措辞漏识别。正在补实际原话回归；第三次独立实测前先离线确认active、最多1篇及排除2篇，不改写前两个任务的失败、用量或知识事件。二级归属与跨任务方法执行仍待真正合格样本，不用预检计数代替成功事实。

个人昵称、评论原话、用户资料和临时搜索词不作为跨任务操作经验。只召回当前小红书作用域，旧学校知识不注入。👍/👎关联任务、结果快照和目标版本，单条纠正保留原证据；方法反馈独立提交，不改写任务目标或重跑浏览器。用户可选记录已回复/确认需求/合作/无回复/不匹配，明确标为用户反馈、归因未证实；满意度和业务结果不增加方法技术成功数。替代路线按已有成果提供：复核已保存资料只调用独立分析，不新增网页操作；导出生成本地名单。路线提交校验当前目标与结果版本，保留账号暂停及未知动作记录。尚无真实获客效果排名。

2026-10-29 对最近跟妆任务只读审计：任务保存正文/评论/回复3类取证操作草稿，共享库只有1条draft、0条verified，试用回执0；当前任务未召回旧经验。这些草稿只覆盖可见容器检查和原话保存，尚不包含已验证的完整搜索、详情、展开回复、主页及交付链路。历史通用文本判重把相似的三类模板误合并，旧采集空快照还可能覆盖复盘后候选列表。

后续程序操作合同使用 `xhs_operation_{capability}_{source_kind}_v{version}` 稳定身份，在本小红书作用域按能力、来源类型和版本区分，独立于历史 `xhs_visible_*`；同合同重复复盘不重复累计观察。本轮有真实来源依据的合同内容由程序生成，不能被模型同key候选覆盖。恢复学习候选和回执保留数据库与快照两边的独有项，冲突保留数据库主值并留下双方依据，不把冲突重复算成多次验证。历史错配行保留审计，不自动修写或升为verified；实际可复用性仍须下一次不同对象的真实任务产生逐条回执。

界面投影由 `backend/prospecting/cards.py` 从任务与实际证据生成，前端仅渲染固定卡片。界面、路线和导出使用同一恢复后的来源版本；来源和主页按来源ID合并，较新观察优先，未知或相同时间保留数据库记录。导出使用独立文件清单保存版本与时间，不被后续旧任务快照抹去；文件缺失或路径不属于任务目录时不能打开。

## 5. 模型和公开资料工具

2026-10-28 核实官方文档：默认 `deepseek-flash`（DeepSeek-V4.1-Flash-1017，支持图像输入），可选 `deepseek-v4-pro`（文本复核，当前不支持图像）。保持 browser-use 锁定 0.13.10，按该版本实际接口适配截图和结构化输出；不无依据升级整个执行框架。

DeepSeek Search/Fetch 作为可选公开网页工具，使用相同 DeepSeek Key；Search 搜索公开材料、Fetch 返回 Markdown。此工具不复用小红书登录态，不保证可读登录后正文或评论，不将第三方摘要升级为已验证线索。默认不开启，用户显式选择或主动使用资料检索入口才调用。

**后续讨论事项（2026-10-29，用户要求先记录、暂不实施）**：当前Search会保存公开检索结果，Fetch已有独立API，但公开资料尚未接入关键词优化和后续任务规划，开关的实际辅助价值有限。后续讨论按需接成“检索业务背景 → 阅读公开正文 → 展示来源与依据 → 优化搜索方向 → 到实际小红书页面核验”。先跑稳小红书主链路，再讨论启用时机、资料展示、效果验证和复用方式；不把公开摘要混入实际读取的客户证据，不自动启用或立即扩展功能。

**用量与重复调用优化（2026-10-29 已实现）**：保持deepseek-flash和关闭思考。在供应商响应返回时、结构校验前记录实际usage，按任务及意图/网页/上下文整理/增量分析/复核阶段累计模型、输入输出、缓存及校验状态；旧历史缺项、未知/部分用量与存储异常单独展示，不推算为0、不当供应商费用账单，也不建立自有余额或用量配额。日志不保存Key、原始提示/响应或签名链接。存储异常不触发模型重试。

相同来源、标准和模型复用已核验判断，只分析新增/变化资料；正文/父根、纠正、业务标准或模型变化会令相关缓存失效。普通资料复核优先复用，另设“重新分析（新增模型用量）”明确强制重做。过程输出要求简短；同一笔记、同一已保存来源量下三次容器/原文取证失败，当步停止并保留资料，不继续付费空转。这里是无进展保护，非任务总量配额。实际节省费用及真实平台表现待后续任务对照验证，旧任务用量无法补造。

官方依据：[模型](https://api-docs.deepseek.com/zh-cn/quick_start/pricing/) / [视觉](https://api-docs.deepseek.com/zh-cn/guides/vision/) / [Search/Fetch](https://api-docs.deepseek.com/zh-cn/guides/search/)。

## 6. 运行与验证

当前目录保留 `school-assistant/` 名称，应用显示“橘子拓客”。独立 PostgreSQL 使用原端口 15433，不触碰同级 assistant 的库、浏览器登录态或服务。启动前检查端口归属，不关闭其他项目的进程。

先验证依赖、类型/构建、后端测试和本地完整流程，再启动桌面应用。缺 Key 时界面可运行并明确提示未配置；真实模型、Search/Fetch 和小红书登录后链路分别验证，不用本地夹具代替真实成功。

## 7. 当前实施顺序

本轮已实现以上对话、阅读、导出、授权、反馈及复盘合同，并完成本地测试和桌面启动核对。旧任务59/60步与51/60步、已保存来源和失败历史各自保留，未自动续跑或追加真实平台采集。

当前顺序以用户纠偏阶段为准，各阶段汇报后须获监督确认才进入下一阶段：

1. P0冻结止损：默认关闭实验工具与全部预检路径、保存成功与父关系分离；不继续D44桌面复测。本机验证完成，P1首轮44个真实浏览模型请求已补齐工具列表回执。
2. P1主链路基线：用户已确认装修服务及近期准备装修用户，真实只读discover目标10位、不加篇数上限，实际2/10位后按原取证停滞规则停止。任务目录已输出 `baseline.json`，完整指标见当前P1记录；未达标缺8位，不调参凑数、不续跑美化基线。测量阶段完成，业务未达标，等待监督确认后进入P2。
3. P2确定性动作程序化：按实测瓶颈实现 `harvest_note(max_items)`、`list_search_notes(keyword)`，保留原话校验及去重；与P1同任务规模对比单候选调用及token下降至少50%，用数据评估非判断步骤关闭视觉。
4. P3用可执行工具序列及参数沉淀流程，真实台账填成本，同类第二任务衡量节省量；保留 `independent-evidence-v1`，停止未验证方法的浏览器提示注入。
5. P4模型结构化提取、理解卡确认后程序执行；盘点并替换直接改意图/范围的自然语言正则，正则只作确认提示。P5在P2完成后按职责纯搬移tools，归档D20–D44并将主PROGRESS控制在200行内；P0不提前拆分或归档。

同一做法失败两次即停下查根因换思路；登录、验证码、平台限制、余额或鉴权问题立即暂停并如实报告。真实触达及任何提交代码须另获用户明确同意，当前不commit/push。未授权关注、评论、私信的边界、四个独立端口及内嵌park约定保持。

细粒度JSON错误诊断等未单独验收的事项继续保留，不用本次UI更新替代。截图连续稳定性按后续真实批次记录，不从本地夹具推出全局保证。

每轮按“问题出在哪 → 怎么修复及验证结果 → 接下来怎么走”收尾，保留未解决事项，具体约定见项目 CLAUDE.md。