campus-copilot: Instructions file for Codex

CampusCopilot Repo Agent Notes

这份文件是 repo-local 工作边界，用来补充全局 agent 规范。
它不重写根规则，只回答这个仓库里最容易写偏的地方。

先接受的事实

• 这不是“先做聊天框”的项目。
• 这是一个 本地优先的学习信息整理工作台。
• 正确顺序始终是：
  • 先 schema
  • 先 adapter
  • 先真实数据链路
  • 先工作台与导出
  • 最后才是 AI

当前正式主线

• 支持站点：Canvas / Gradescope / EdStem / MyUW
• extension 主链已接通四站最小同步
• AI 已进入最小问答闭环，但仍然只走：
  • OpenAI api_key
  • Gemini api_key
• Gemini OAuth / Anthropic / web_session / 多 provider 自动路由 仍然不是正式主路径

绝对不要写偏的地方

• 不要让 AI 直接读取网页、DOM、cookie 或 raw adapter payload
• 不要把 exporter 直接绑到站点原始响应
• 不要把 private/internal request 路径包装成“已经官方稳定”
• 不要引入自动提交、自动发帖、自动写操作
• 不要扩大权限到 cookies

当前事实层和展示层

• Dexie 是 canonical local entities
• storage read-model 是工作台真相源
• TanStack Query 不是本仓库主真相源
• sidepanel/popup/options 都应该消费统一 schema + read model

当前推荐门禁

任何声称“本地默认 gate 已完成”的改动，至少要附带这些新鲜结果：

pnpm verify

如果改动触及 extension 的用户可见交互，或你要对齐 GitHub-hosted required lane，再补：

pnpm verify:hosted

如果碰到 BFF 或 API 入口，再补 targeted 证据：

pnpm --filter @campus-copilot/api test
bash scripts/api-healthcheck.sh

当前 live / profile / auth 纪律

• 做真实 campus-site live/browser/session 推进时，当前 repo 的 canonical Chrome 根目录不再是默认系统根，而是：
  • ~/.cache/campus-copilot/browser/chrome-user-data/
• 当前 repo 的 canonical profile directory 是：
  • Profile 1
• 当前 repo 的 canonical 显示名是：
  • campus-copilot
• 旧世界里默认 Chrome 根目录下的 Profile 13 只再承担一件事：
  • 一次性迁移源
• 默认系统 Chrome 根目录：
  • $HOME/Library/Application Support/Google/Chrome 不再是当前 repo 的运行真相面。
• live/browser 脚本不允许再偷偷回退到默认系统根目录；缺少 repo-owned browser root 或 repo-owned instance 时，应直接报：
  • browser_root_not_bootstrapped
  • browser_attach_missing_repo_instance
• probe:live / diagnose:live / support:bundle 只允许读取 repo-owned Chrome lane 的 CDP / DevTools target 控制面。
• 严禁再用 AppleScript / JXA / System Events / GUI 坐标点击去读取或推动任意桌面 Chrome 窗口、标签页或系统前台会话。
• 如果当前缺少 repo-owned 控制面，必须直接 fail fast；不要再回退到“扫桌面上现有 Chrome 标签”的 global fallback。
• 当前 live runtime 的正式登录态口径必须是确定性的：
  • authenticated: true | false
  • authBoundary: authenticated | session_resumable | mfa_required | logged_out | not_open | profile_mismatch | attach_failed
• 不要再把 likely_authenticated / public_or_unknown 当成当前 operator-facing 真相面。
• browser:launch 现在还要维护当前 canonical lane 的人眼身份锚点：
  • .runtime-cache/browser-identity/index.html
  • title / favicon / accent 应明显可识别
  • 可以提示用户手工 pin 一次
  • 但不要去写 Chrome 私有 avatar/theme/pinned-tab 偏好
• 对 Canvas / Gradescope / EdStem / MyUW 的默认工作假设必须是：
  • 如果用了正确的 repo-owned Profile 1（显示名 campus-copilot），要么已有登录态；
  • 要么密码管理器已经能自动填充；
• agent 应先继续推动登录 / SSO / 会话续接，而不是一看到 session_resumable 或 mfa_required 就停。
• 只有在正确 profile 下确认：
  • 没有现成登录态；
  • 没有密码自动填充；
  • 且继续操作后仍无法前进； 才允许把它归类成真实 external / human-only 边界。
• 如果四站确实需要账号密码，最后兜底只允许使用本地 .env 中的 ACCOUNT_ID / PASSWORD 这两个变量；只允许读取变量名和使用它们完成登录，严禁在日志、回复、截图标注或文档里扩散具体值。
• Gradescope 的默认登录推进假设要写死：
  • 先点 Log In
  • 或直接走 https://www.gradescope.com/auth/saml/uw
  • 优先复用 Canvas / MyUW 已存在的 UW SSO 会话
  • 若 MyUW / Canvas 已在同一 profile 中完成认证，则应优先沿学校 SSO 链继续，不要把它过早报成 blocker。