48 lines
6.0 KiB
Markdown
48 lines
6.0 KiB
Markdown
# 项目协作约定
|
||
|
||
## 当前项目
|
||
|
||
本目录 `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。普通确认/说明只需简述，不为凑格式虚构故障、改动或验证，也不因此启动额外业务任务。
|