austin
/
assistant
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
assistant/docs/archive/DESIGN-school-2026-10-28.md

19 KiB
Raw Blame History

智能办事助手：产品定义、架构与决策

这份文档回答"我们在做什么、为什么这样做、接下来做什么"。里程碑和实测数据见 PROGRESS.md。 每次做出新的设计决策，在「已定决策」追加一条并写日期；改变方向时改这里，不要只改对话。

1. 一句话定义

一个像 Codex 桌面端的办事 Agent：用户对着聊天框说一句"我要办某件事"，助手识别业务、追问缺的资料、以对应角色登录学校的网页系统、自主找入口填表、在提交前逐项列出请用户确认，办完后记录结果，并把过程中学到的经验沉淀下来让下一次更快。

2. 目标用户与角色

角色 用什么 做什么
学校里的办事人（学生、辅导员、管理员） 桌面端 说需求、补资料、在关键节点确认。不参与知识审核
我们团队 后台管理（待做） 写出厂 YAML、审核各校沉淀的经验、看运行监控、维护密码本、交付

3. 产品原则

  1. 只在业务允许的域名内活动。
  2. 登录凭据来自密码本或用户手动，模型永远看不到明文（browser-use sensitive_data）。
  3. 任何正式提交前必须用户确认；用户取消就不提交。
  4. 不猜学校没有明说的规则，宁可停下来问。
  5. 全程可审计：每步截图、progress.md、run_logs。
  6. 经验先成草稿再生效，用户端无感，审核由我们或规则完成。

4. 架构

4.1 现状（2026-09-17）

Electron 桌面端（renderer 聊天 + 右侧状态/截图/时间线）
   │ IPC
Python FastAPI 后端（Electron 拉起并独占，端口 8788）
   ├─ nlu.py            意图识别 + 字段抽取（DeepSeek / 千问，一次调用，JSON）
   ├─ orchestrator.py   状态机、按业务路由、prompt 组装、暂停/续跑、沉淀触发
   ├─ browser/runner.py browser-use Agent，独立 Chrome，会话保活，每步截图
   ├─ learning.py       任务成功后生成 learned 草稿
   └─ db/database.py    psycopg 3，所有学校数据带 school_id
PostgreSQL 17（Docker，127.0.0.1:15433）
   knowledge / tasks / run_logs / system_accounts / learned_entries / skills / settings

桌面端直连 PostgreSQL，一台机器一所学校（.env 的 SCHOOL_ID）。

4.2 目标形态

桌面端（编排 + 浏览器，必须在本机）  ──HTTPS──▶  服务端 API  ◀──  后台管理（我们团队，跨学校）
                                                    │
                                              中心 MySQL（按 school_id 隔离）+ 向量库（手册）
  • 桌面端只保留必须在本机跑的部分：编排、browser-use、Chrome。知识、learned、账号、任务记录都走服务端接口。
  • 后台管理和桌面端用同一套接口。
  • 学校可以一校一库，也可以共库按 school_id 隔离，数据模型两种都支持。

5. 知识的三层

层 内容 存在哪 谁维护 状态
出厂配置 系统入口、登录方式、业务定义（角色、必填项、步骤、规则） 编写格式是 knowledge/*.yaml，启动时灌入 knowledge 表，运行时读表 我们，来源是学校手册 + 调研；将来后台直接改表，文件只做导入导出 已有
经验 learned 入口路径、控件技巧、前置阻断、踩过的坑 learned_entries 表，draft → verified / rejected，带 school_id、类别、观察次数、来源任务；YAML 里的 learned 只是出厂基线 任务成功后自动生成草稿，按内容判重归并；控件技巧 / 入口路径类被 ≥2 个任务观察到自动生效，系统规则类由我们后台人审，用户不参与 已有；后台审核队列待做
参考资料 学校手册、通知、FAQ 向量库（可复用已有 Qdrant），按学校 / 系统打标 我们导入 待做

YAML 文件与数据库的关系：文件是给人读写的格式，表是运行时副本。现阶段文件是源头；后台做出来之后反过来，表是源头，文件用于交付。

有后台之后（2026-09-17 确认）：业务定义在后台维护（表单编辑 / YAML 文本编辑 / 上传导入 / 手册生成草稿），带学校、版本、发布状态；桌面端启动时从服务端拉本校已发布的定义并本地缓存，不再随安装包带文件；仓库里只保留模板（自家学工系统出厂模板、常见第三方系统骨架），给新学校开户时从模板复制进库再改；导出仍产出 YAML，用于备份、迁移和把 A 校审核过的 learned 打包给 B 校。过渡期加一个"知识来源 = 文件 / 服务端"的配置，服务端模式下启动不再用文件覆盖库，只在该校一条业务都没有时用模板初始化一次。

有手册：模型读手册生成 YAML 业务草稿（结构化，价值最高）；手册切块进向量库，给 Agent 一个 lookup_manual 工具按需查"字段是什么意思、有什么前提"。 没手册：上线前按角色做一次建图扫描（枚举菜单、页面、表单字段），生成业务草稿；使用中靠 learned 沉淀；交付前预热多跑几遍，把慢的阶段藏起来。

6. 执行模型

用户一句话
 → nlu 识别业务、抽字段（今天/明天换算成日期）
 → 缺必填项：对话追问（模型生成追问语），用户下一句再抽取合并
 → 角色准入：业务 role 与用户在该系统密码本账号的 role 不一致 → 直接告知办不了
 → 浏览器 profile 按 人 × 系统 × 角色；任务涉及各系统的凭据按域名分组进 sensitive_data（占位符带系统后缀），没有账号的系统按 YAML fallback（测试环境快捷登录 / 请用户手动）
 → 业务的全部启用步骤按顺序在同一个浏览器会话里执行，前一步产物注入下一步
 → 执行业务的启用步骤：prompt = 业务 + 目标 + 资料 + 登录方式 + 规则 + learned（YAML 基线 + 库里 verified）+ 步骤要求
 → Agent 需要用户时调 ask_user：以 is_done 结束本轮，浏览器保活，状态 paused；用户回答后 add_new_task 续跑同一 Agent
 → 遇到系统提示「必须先办另一件事」时调 report_blocker：按 YAML 声明的 resolution 处理。self = 问用户要不要顺带办，同意则同一会话切去办前置业务再回来；other_role / manual = 说明要找谁怎么办，用户说已处理就重试，说取消就进 blocked（可稍后继续）
 → 提交类步骤：填完 ask_user 逐项确认 → 确认后提交，保存 submitted_record / result_message → 状态 submitted
                                       → 取消则保存 cancelled → 状态 completed（不算提交）
 → 成功后 learning.draft_learned 生成草稿
 → submitted 任务按 next_check_at 由调度循环拉起只读回查步骤：approval_status 归类 → completed / rejected / 继续排期

判定规则：success_artifacts_any 覆盖 Agent 自评；submitted_artifacts_any 决定是否算提交；cancelled 优先。

7. 已定决策（按时间）

日期 决策 原因 / 备注
09-16 产品形态像 Codex 桌面端；一定是桌面端 浏览器和登录态在本机，隐私好
09-16 账号由我们按角色从库里取，自动登录 用户不该反复输密码；用 sensitive_data 防泄露
09-16 知识由我们维护交付学校；手册是来源 学校只管用
09-16 模型 Key 先放 .env，不做用户级 Key 阿里 / DeepSeek Key 由我们持有
09-16 学工系统是自家产品，先拿它练 快捷登录等便利只在自家系统有，注意别依赖
09-16 skill / learned 全校受益；数据层用 MySQL（Docker） 为中心化做准备
09-16 提交后跟踪要做，但排在链路走通之后 提交不等于办完
09-17 演示业务从留校申请换成辅导员查课日志填报 测试环境学生端没有留校申请模块
09-17 学校之间数据隔离（school_id） 不是每所学校都用我们的系统
09-17 用户端不出现采纳 / 忽略；审核靠自动晋升 + 我们后台 办事人不该做知识审核
09-17 后台管理和服务端层要做，但桌面端先夯实 顺序：真实提交 → 第二业务 → 后台
09-17 learned 判重按内容不按 key；自动晋升只对控件技巧 / 入口路径类，系统规则类必须人审 模型每次起的 key 不同；记错规则代价大
09-17 有后台后 YAML 只做模板和导入导出，表是源头，桌面端从服务端拉配置 见第 5 节
09-17 前置阻断做成标准机制：同角色能办的顺带办（同一会话切换目标再回来），别的角色 / 线下的说明处理方式后 blocked 等待 请假被返校核验拦住是真实样例
09-17 桌面端登录走学校统一身份认证；业务系统登录配方要支持「统一认证跳转」，允许域名含认证中心域名 用户 09-17 确认
09-17 密码本只服务未接统一认证的系统：学校配发账号由后台导入，个人账号才需要用户绑定。开发期手动维护密码本是权宜之计。「绑定账号界面」从演示版拿掉，换成登录配方支持 sso（登录态在 profile 里复用，缺时请用户完成一次） 用户 09-17 指出
09-17 前置阻断需要别的角色处理时，是另一个人在自己的端上用自己的账号办（如辅导员办「核实学生返校」），不是同一用户切角色；两端联动（协办请求 / 完成通知 / 自动续跑）走服务端，现阶段学生手动点「继续」 纠正此前「跨角色闭环」的说法
09-17 目标系统自身的问题（如测试数据、缺功能）不纠结、不绕过：如实报告并 blocked，等系统方处理。我们会面对各种系统，链路跑通优先 学生请假被后端规则拦住是首例
09-17 跨人联动（通知辅导员、协办请求、自动续跑）本阶段不做，归服务端层 用户 09-17 决定
09-17 对照同事 PenguinUniOS 后的四项决定：桌面端按其形态重做并连打包链一起对齐；数据库切 PostgreSQL 17；继续独立仓库；执行路线保持 browser-use run() + learned 用户 09-17 拍板，见 REFERENCE_PENGUINUNIOS.md
09-17 身份模型：一个人在一个系统里只有一个身份，跨系统身份可不同。密码本按「人 × 系统」存账号并记录该账号在该系统的角色；业务的 role 是准入条件而不是登录依据；跨系统任务用 browser-use 按域名分组的 sensitive_data，一个会话依次登录各系统 用户 09-17 指出；这是跨系统操作的前提
10-28 学校工程整体移入 browser_use/school-assistant/，与独立获客项目 browser_use/assistant/ 并列；各自保留独立 Git 仓库，外层只作工作区导航 用户要求分开两个项目，避免代码、配置和文档混在工作区根目录

8. 待做设计（按建议顺序）

  1. 真实提交验证（09-17 完成：两条查课日志真实提交成功，状态 submitted，日期校验无问题）。
  2. 第二个业务（09-17 完成：每周谈心谈话）。前置阻断机制（09-17 完成：report_blocker + self / other_role 两条路径 + blocked 状态）。学生请假在测试环境被「返校核验」拦住；09-17 以辅导员和系统管理员探索后确认界面上没有任何角色能解开（后端业务规则作用于历史未返校记录），需学工团队清测试数据或补功能。业务 counselor_return_verify 已建，等系统侧有入口再补填报步骤；学生请假填报步骤同样等待。
  3. 防重复提交（09-17 完成：两个填报步骤提交前先查已有记录，重复时 ask_user）。
  4. learned 自动晋升（09-17 完成：按内容判重，≥2 任务观察且为控件技巧 / 入口路径类自动生效，系统规则类人审；OPERATOR_MODE 控制草稿面板）。失败驱动的自动降级待做。
  5. 浏览器展开 / 收起：CDP 停靠 + 最小化 / 恢复（09-17 完成，暂停确认时自动展开）；下一步验证 Electron WebContentsView + cdp_url 真正内嵌。
  6. 密码本升级（跨系统地基）：本地部分 09-17 完成（role 列、角色准入、按系统分 profile、域名分组凭据）。目标形态是"用户登录桌面端 → 服务端按人返回他有账号的系统及角色、据此过滤可办业务、密码本条目清单（无密码）→ 任务开始时按需取该任务涉及系统的凭据，用完即丢并记审计"。密码本来源两条：学校配发账号由后台批量导入；个人账号由用户在桌面端「绑定账号」一次写入。当前阶段先做本地能做的部分：system_accounts 加 role 列；业务执行前做角色准入检查（当前用户在该系统的账号角色 ≠ 业务 role 就直接告知办不了）；浏览器 profile 按「人 × 系统」而非「人 × 角色」；多系统凭据按域名分组装进 sensitive_data，占位符带系统后缀（x_username_lib / x_password_lib），登录说明按系统分段；每系统登录配方（表单 / 统一认证 / 扫码）；生产环境放中心库并经服务端按任务取用、审计日志。
  7. 多步串行执行器（09-17 完成：步骤顺序执行、每步可声明系统、产物跨步传递、同一会话 keep_session、允许域名取并集；跨系统登录待第二个系统接入后实测）。
  8. 提交后跟踪（09-17 完成：YAML tracking、调度循环、track-now / track-stop、状态 rejected、桌面端提示；真实任务实测两次回查）。后续：回查时静默运行。
  9. 手册导入 / 建图扫描：手册 → YAML 草稿；手册 → 向量库 + lookup_manual 工具；无手册时按角色扫描菜单和表单生成草稿。
  10. 后台管理 + 服务端层（审核队列部分 09-17 完成，见 PROGRESS D17）：已做——server/（FastAPI，独立库 school_assistant_hub）+ console/（React 审核台），各校桌面端带凭证上报草稿、中心按内容跨校合并、智能预审（规则层 + 模型层）、人工采纳 / 驳回 / 改写、按「仅来源学校 / 所有学校」发布、桌面端按版本号增量拉回并落成本地 verified / rejected；backend/hub_sync.py 全后台异步，没配 HUB_URL 就是单机模式。智能采纳（09-17，PROGRESS D18）：类别硬门槛只放行控件技巧 / 入口路径，证据够硬或模型背书两条路，模型建议改写则留人，自动驳回可复活，先干跑再执行。待做——运行监控（成功率 / 步数 / 时长趋势、失败截图）、知识与密码本管理、按学校分组推送、后台多人账号；桌面端统一身份认证登录、按人过滤业务、按需取凭据；跨人协办：一个人的任务被别的角色的前置事项拦住时，向对应角色发协办请求，对方办完后通知并自动续跑。
  11. UI 往 Codex 形态靠（09-17 完成：三栏布局、任务列表与回放、确认 / 阻断 / 结果卡片、我来接管）。后续：嵌入式浏览器面板。
  12. 登录配方支持统一认证：login.mode: sso | form | quick_login | manual；允许域名含认证中心；有登录态直接过，没有则请用户完成一次登录后复用 profile 登录态。测试环境无 SSO，先做配置与提示词，接真实学校再验。绑定账号界面推迟到真遇到非 SSO 的个人账号系统。
  13. 测试集（09-17 完成，见 PROGRESS D16）：npm test 288 个用例 3.4 秒，覆盖 nlu 退路、状态判定、learned 规则与数据库生命周期、角色准入、凭据分组、阻断问句、执行结果判定、Key 兜底。@pytest.mark.db 的用例用一次性 pytest_xxx 学校隔离，PostgreSQL 不可达时自动跳过。写测试时挖出并修掉两个缺陷：关键词退路要求整段短语原样出现（模型不可用时真实说法全部误判为通用探索）、单字肯定词在句中任意位置命中（补充资料被当成同意先办前置事项）。
  14. 桌面端对齐同事的 PenguinUniOS 形态（09-17 完成，见 PROGRESS D13 / D14）（见 docs/REFERENCE_PENGUINUNIOS.md）：已做——React/TS/Vite 渲染层、TS 主进程、WebContentsView 内嵌浏览器（browser-use 经 CDP 连 Electron 自带 Chromium，界面页走 app://ui 协议、主机名 ui 进白名单，不展示的视图停到窗口边缘外留 2px 在窗内而不能隐藏，否则截图挂死）、任务卡 / 确认卡 / 状态词汇对齐、Lucide 与其视觉规范、uv + PyInstaller + electron-builder 打包链（npm run package:win → release/win-unpacked，后端冻结成 exe 放 resources/backend，userData 放 .env / data / profiles）。待做——NSIS 安装器 / 图标 / 签名、Pydantic 契约生成 TS。已决：数据库已切 PostgreSQL（09-17 完成迁移）；仓库独立；打包态只支持内嵌浏览器，不带 Chromium。

9. 实测基线

场景 配置 结果
学生端只读探索 无 learned，3 次 1 成功 2 自评失败（产物齐全），31 步 / 181 秒
学生端只读探索 修判定 + learned，2 次 2/2 成功，23 步 / 99 秒
辅导员查课日志填报到确认 首次 47 步 / 372 秒
辅导员查课日志填报到确认 控件技巧 + 每步 6 动作，干跑 2 次 2/2，18 步 / 158 秒
暂停续跑 强制先 ask_user 15 秒暂停，回答后 21 秒完成，同一会话
辅导员谈心谈话填报到确认 首次即带 learned，干跑 1 次 15 步 / 81 秒；一句话四个必填全抽出，无追问
辅导员谈心谈话填报到确认 第二次干跑 11 步 / 61 秒
查课日志真实提交 用户操作，2 次 均「填报成功」，状态 submitted
前置阻断 other_role（学生请假） 真实环境 25 秒识别拦截、标准化提问，取消后 blocked
前置阻断 self（模拟） 临时业务 切子目标并回到原目标完成，约 35 秒
两步串行（模拟，同系统） 临时业务 54 秒，一个会话，第二步使用第一步产物
提交后跟踪回查 真实提交的查课日志 立即回查 73 秒读到「未审批」+ 审批轨迹；调度自动回查 77 秒完成并排期

10. 目录与关键文件

学校项目根目录为 browser_use/school-assistant/（2026-10-28 从工作区根目录整体移入，含独立 Git 历史）。同级 browser_use/assistant/ 为独立 AI 获客项目。以下路径均相对学校项目根目录。

backend/nlu.py                  意图识别与字段抽取
backend/orchestrator/orchestrator.py  状态机、路由、prompt、暂停续跑、沉淀触发
backend/browser/runner.py       browser-use 执行器、会话保活、每步截图
backend/browser/tools.py        ask_user / save_artifact
backend/learning.py             learned 草稿生成
backend/security.py             密码本加解密（Fernet，ACCOUNT_ENC_KEY）
backend/db/schema.sql           MySQL 表结构（含 school_id）
backend/db/database.py          数据层与旧库迁移
knowledge/xuegong_demo.yaml     出厂业务定义 + 基线 learned
scripts/eval_run.py             评测（默认干跑）
electron/main.js                后端唯一所有者、旧后端接管
renderer/app.js                 三栏 UI：任务列表与回放、对话与卡片、状态 / 截图 / 时间线 / 沉淀草稿；无 Electron 时回退 fetch 便于自测
docs/PROGRESS.md                里程碑与实测