assistant/CLAUDE.md

项目协作约定

当前项目

本目录 browser_use/school-assistant/ 已转为 橘子拓客（browser-use 桌面实验版），首个平台小红书。同级 assistant/ 是独立项目，不能把其运行结果或验证状态算到本项目。

新会话先读 docs/DESIGN.md 与 docs/PROGRESS.md。旧学校产品设计/启动说明归档在 docs/archive/；历史学校任务、NLU、角色准入、填报与审批状态机不接入新入口。

当前技术路线

Electron + React/TypeScript + FastAPI + browser-use 0.13.10 + PostgreSQL 17。backend/prospecting/ 是当前业务编排与 API，backend/browser/ 提供通用执行和页面取证；只保留 backend/orchestrator/progress_doc.py 的通用进度记录能力，不调用原学校 Orchestrator。

链路：自然语言委托 → 意图与必要追问 → 分阶段搜索/笔记及讨论回复取证 → 独立分析/主页核对/导出或明确授权的跟进 → 独立复盘与评价。操作经验与个人来源分开；同一任务可修订目标，记录目标版本、保留来源及动作记录，不自动重放已成功或结果未知的动作。

命令

• npm ci / npm run backend:setup / npm run db:up：安装前后端与启动独立数据库。
• npm start：构建并启动桌面应用。
• npm run check / npm run build / npm test：类型、构建和后端测试；编排修改要跑完整后端测试。
• npm run backend：单独启动本项目后端。
• npm run backend:lock：以 universal 模式更新跨平台 Python 哈希锁，不能只在 Windows 冻结出无平台标记的依赖。

约定

• Key 由本项目 .env 或应用设置提供，不从其他项目复制，不输出到日志、对话或版本库。默认 deepseek-flash，图像输入和JSON输出适配以实际官方文档和测试为准。
• 小红书登录由用户在实际页面完成；登录、验证码或平台限制要暂停。不把网页登录状态或私有接口凭据交给模型。
• 当前用户授权开发和运行应用，未授权实际关注、评论或私信触达；不实现自动触达为默认行为。
• 默认无篇数/评论数/总步数业务配额，无自建余额。用户明确数量才约束；单次请求超时不代表整个任务结束。真实上游限流/欠费/平台限制准确汇报，程序停止事件优先于模型总结。
• 发现候选须有明确交付终点：沿用用户给出的候选人数；未给人数或指定页面/篇数/明确一轮范围时，只补问“这次先整理多少位候选？”。人数按有稳定来源身份的人去重，身份未知单列不凑数。达标当步停止；未达标或无进展交付阶段结果，不无限重复。模型不能替用户猜目标数量。
• 相同来源、标准和模型复用已有判断，新增/变化来源增量分析；明确“重新分析”才强制重做。按任务/阶段累计供应商实际usage，解析失败已返回的用量也保留；未知用量与历史缺项不能写成0或当完整账单。
• 跟进工具需批次授权、已核对的账号/对象和确定的私信内容；红色失败标记或结果未知暂停当前账号全部后续私信。解除须新页面核对和用户明确确认，不自动重发。开发方案批准不等于真实触达测试授权。
• save_source 逐字核对实际来源容器，evidence.json 为任务来源恢复快照。待核不等于已确认客户；mock、本机夹具、模型连通和真实平台表现分别报告。
• 交付状态、必要字段与知识可靠性分开：仅用户明确要求的字段计达标；不统一要求人工复核。新知识依据程序前后证据自动验收，模型报告与用户👍/👎不增加技术成功数；重复任务/对象不能重复抬分，明确相关反证暂停相应场景。历史缺失统计标未记录，不迁移补成功。方法与事件按工作区隔离，原话/账号留在任务证据，跨任务只保存通用方法及引用；目前无真实跨任务优先方法或获客效果结论。
• 旧编译字段只在明确继续时重核，保留后来确认的人数和旧目标/证据/文件版本，不在读取或启动时自动修改。评论数量不代表已读；评论区推进及作者主页使用受约束工具和当前真实入口，悬浮卡无推进不反复点。Schema诊断仅留程序声明字段路径/标准错误类型，不保存input/msg/原始响应；具体连续失败原因不能被笼统done覆盖，程序错误不充当方法反证。新建内嵌及续跑均须带当时目标版本，旧缺失不补造。
• 两套历史数据库字段暂保留兼容，新任务/经验以 prospecting_workspace 作用域隔离。中心学校审核服务不由当前桌面入口自动运行。
• 每次完成阶段同步 DESIGN/PROGRESS。保护已有改动，未获明确要求不提交或推送。
• 数据库15433、API8788、CDP9333、控制8797；不关停其他项目服务。Electron内嵌视图不直接隐藏，按原park保留窗内2px，避免截图挂起。

每轮结束汇报（用户 2026-10-28 明确要求）

每次结束都用简短、具体的语言交代以下内容，成功、失败或受阻均适用：

1. 问题出在哪：说明现象、已确认的原因与依据；尚未确认的原因明确标为待查。
2. 怎么修复、结果如何：说明实际修改与验证结果，区分本机测试、真实模型、真实平台；业务任务写明实际来源/线索及未完成范围。未修好的问题必须保留，不能只报测试通过。
3. 接下来怎么走：按优先级列出下一步具体动作、目的和验收依据；需要用户补充的资料明确指出。沿用用户明确范围、既有结果和累计进度，不因总结或改轮次清空任务或动作记录。

汇报同时留下可复用的方法或规则；没有可沉淀经验时如实说明。实际开发、修复和工程验证同步到 PROGRESS，已定方案与实施顺序同步到 DESIGN。普通确认/说明只需简述，不为凑格式虚构故障、改动或验证，也不因此启动额外业务任务。