diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 7d825690..e1b1f487 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,70 +1,125 @@ -# OfferU 架构边界 - -```text -TypeScript React UI / Client Interaction - │ typed HTTP API - ▼ -Python FastAPI Career Runtime - Profile · Job · Application · Artifact - Event · Candidate · CareerTask - │ Operation Registry - ▼ -External Agent Runtime - Pi · Replay · Codex · DSH adapter - -Tauri / Rust = desktop shell and process lifecycle only -``` + +# OfferU Architecture + +Status: **CURRENT ARCHITECTURE AUTHORITY** +Updated: 2026-09-23 + +OfferU is a local-first Career OS. The desktop product is the primary user experience; local Agents are replaceable reasoning engines attached to the same deterministic career control plane. + +## System boundary + +~~~ + OfferU Desktop + Today · Pipeline · Job · Profile + │ + guided intent / user action + │ + ┌──────────┴──────────┐ + │ │ + External local Agent OfferU fallback Agent + (preferred) (optional) + │ │ + └──────────┬──────────┘ + │ + OfferU Skill + optional Career Skills + │ + Agent Tool Surface + │ + Operation Registry + schema · permission · proposal + idempotency · audit + │ + Career Runtime + Profile · Job · Application · Resume + Interview · Evidence · Events · Memory + │ + local SQLite / files +~~~ + +Browser capture, email sync, automation and direct human UI actions join the same control plane; they do not maintain parallel business truth. + +## Four authorities + +- **Reasoning authority** — exactly one active Agent per Agent Run. Prefer a verified local Agent already owned by the user; OfferU may provide a fallback. +- **Execution authority** — the Operation Registry controls governed capabilities, validation, side effects, proposals, idempotency and audit. +- **Truth authority** — the Python Career Runtime owns persistent career state. +- **High-risk approval authority** — the user or an explicit deterministic product policy. An Agent cannot approve its own protected mutation. + +## Agent hosts and Skills + +Agent hosts may be Codex, WorkBuddy/CodeBuddy, Claude Code, OpenCode, OMP, Pi, Gemini or future compatible hosts. + +OfferU detects host capability from code/probes rather than assuming parity. A host may be a Skill host, a hosted runtime/executor, both, unavailable or only partially compatible. + +When the host supports Agent Skills, OfferU projects its Skill and allows composition with installed resume/recruiting/interview/career Skills. Third-party Skills provide methodology; OfferU remains the state and side-effect authority. + +## Tool surface + +The broad Operation Registry is **not** the model-facing tool list. + +~~~ +Operation Registry + └─ Agent Tool Surface + └─ Active Skill Surface +~~~ + +Agents discover compact Skill metadata first and load the relevant operation schemas on demand. Developer/audit paths may expose the full Registry, but beginner Agent flows should not. + +See [Tool Surface V2](./docs/architecture/2026-09-22-tool-surface-v2.md). ## Truth flow -```text +~~~ Observe ↓ -Event / Candidate +Event / Evidence / Candidate ↓ -Career Runtime understands state +Career Runtime validates / associates ↓ -CareerTask plans work +Agent or deterministic policy recommends next action ↓ -Operation executes or proposes +Operation executes or creates Proposal ↓ -verified state / artifact is committed +review / confirmation when required ↓ -Today and Pipeline project the same state -``` - -Agent 负责 reasoning、planning、tool selection 和研究编排；不能直接拥有职业事实。Operation Registry 负责 capability、权限、dry-run、确认和审计。Python Domain Runtime 是 Career Truth 的唯一来源。自然语言“我已更新”不是成功证明，只有成功提交的 Operation 才能改变正式状态。 +verified state / artifact + ↓ +Today / Pipeline / Job / Profile re-project the same truth +~~~ -## 领域对象 +Natural-language “done” is never the proof of completion. -优先围绕 `Profile`、`Job`、`Application`、`Artifact`、`Event`、`Candidate`、`CareerTask` 表达需求。Today、Pipeline 和 Agent UI 是 projection 或执行界面，不复制同一业务状态。 +## Browser and email -## Resume Workspace +Default job acquisition is explicit current-page capture. Smart Fill may assist safe fields after review but never silently submits an application. -岗位简历工作区复用现有 `Resume`、`ResumeSection`、`ResumeOptimizationProposal` 和 `ResumeVersion`，不创建平行的文档状态： +Email and other authorized channels create evidence/signals and reviewable progress candidates. They do not directly overwrite Pipeline state. -```text -Career Evidence / Profile - ↓ -Master Resume - ↓ source_resume_id + target_job_id -Job Tailored Resume - ↓ -Application Packet projection -``` +## Built-in runtime code -编辑器、实时预览和 PDF 都读取同一份结构化 Resume 内容。AI 只生成 Proposal；逐条接受/拒绝、手动编辑、排序、可见性和模板修改都通过 Resume Operation Registry。`workspace_snapshot_hash` 用于阻止过期 Proposal 覆盖用户最新修改，`ResumeVersion` 保存可回看的岗位版本与来源。 +Legacy/internal runtime workers may remain for fallback, replay, compatibility or bounded executor use. Their existence does not make them the Career Truth owner or the mandatory product shell. -OfferU 不创建 `ResumeAgent`。岗位简历准备是 `CareerTask`，由现有 Agent Runtime 选择受控 Operation 执行。Job Detail 是进入 Workspace 的主要入口，Today / Pipeline 只投影同一 Application、Event 和 Packet 状态。 +## Stable technology boundary -## 自动化 +~~~ +React / TypeScript = product UI +Python / FastAPI = Career Runtime + Operation Registry + deterministic policy +Tauri / Rust = desktop shell, lifecycle, installer and OS integration +Agent hosts/runtimes = replaceable reasoning/execution engines +SQLite = local career data +~~~ -```text -Event → Rule → CareerTask → Agent / deterministic runtime → Operation -``` +Do not introduce a second business backend or duplicate Career Truth to match an Agent framework. -低风险读取、研究、计算和候选生成可以自动执行；正式 Career Truth 变更仍经过事实门和用户确认；外部不可逆动作始终需要明确用户操作。 +## Safety invariants -## Provider 与数据来源 +- Agent output is candidate/draft until accepted through the correct path. +- Important state mutations are reviewable and auditable. +- External irreversible actions remain user-controlled. +- No Agent may self-confirm a protected proposal. +- Credentials do not enter Agent context. +- Provider/host failures are explicit. +- Browser/email integrations cannot create hidden business state. +- Historical eval or fixture success cannot be presented as current live capability. -Replay/Fixture 是显式的合成数据模式，必须在 UI 和产物中标记，不能冒充实时市场数据。Live Provider 失败时保留失败或 blocked 状态，允许用户改用 Fixture 验证本地产品链，但不能静默降级成成功。 +Current product interaction authority: [Current Product North Star](./docs/product/current-product.md). diff --git a/CONTEXT.md b/CONTEXT.md index c6ca6fa1..80c5ee77 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -1,377 +1,128 @@ -# OfferU 求职运营 +# OfferU Context -OfferU 帮助使用者持续维护职业档案，并围绕岗位研究、材料定制、投递跟进和面试训练推进求职过程。 +Status: **CURRENT DOMAIN AUTHORITY** +Updated: 2026-09-23 -## Language +OfferU is a local-first AI Career OS. This glossary keeps only concepts that should guide current product and Agent behavior. -**主控 Agent**: -由使用者选择并经能力探测通过的外部 Coding Agent Harness 承载，是理解目标、自然语言推理、任务规划和选择 OfferU Operation 的唯一智能主体。它不能拥有业务事实、授予自身权限或绕过 OfferU 操作控制面执行副作用。 -_Avoid_: OfferU 内置 Agent、操作员 Agent、第二主脑、业务后端 +Historical terminology is preserved in [the archived context](./docs/archive/architecture/context-pre-2026-09-23.md). -**OfferU 操作控制面**: -OfferU 内部不含 LLM loop 的确定性运行边界，负责工作台状态、上下文投影、权限、确认、Operation 执行、幂等、事件和审计。它接收主控 Agent 的类型化调用，但不理解开放式目标、不规划任务，也不选择下一项 Operation。 -_Avoid_: 内置 Agent、主 Agent 运行时、Pi Core、Harness Agent、第二主脑 +## Core authorities -**操作守卫**: -在主控 Agent 的 Operation 调用前后执行阶段检查、风险提醒和记忆候选提取的确定性策略集合。它不能选择或执行业务 Operation，也不拥有独立对话、工具循环或记忆事实。 -_Avoid_: Main Agent Guardian、Harness Agent、规则 Agent、第二 Agent、工具路由器 +**Career Runtime** +The canonical domain runtime for Profile, Evidence, Jobs, Applications, Resumes, Interviews, Events and durable Memory state. -**本地深度执行器**: -由主控 Agent 按需委托，用于完成边界明确的深度研究或批量分析任务的本地智能执行能力。它不拥有业务事实源，也不能绕过使用者确认独立改变求职状态。 -_Avoid_: 主控 Agent、系统主脑、自治 Worker +**Operation Registry** +The governed execution surface for business capabilities. It owns validation, permission checks, side-effect classification, Proposal/HITL routing, idempotency and audit. The Registry is not identical to the Agent tool catalog. -**执行器适配器**: -把一种本地深度执行能力的会话、事件、审批、取消和恢复语义映射为 OfferU 托管执行会话契约的边界。它不包含求职业务逻辑，也不能扩大任务能力授权。 -_Avoid_: CLI Wrapper、Agent 后端、Provider、业务插件 +**Reasoning Authority** +The single active Agent for a given Agent Run. Prefer a verified local external Agent already used by the user; OfferU may provide a fallback Agent. The reasoning authority plans and selects capabilities but does not own Career Truth or approval. -**托管执行会话**: -由 OfferU 操作控制面根据主控 Agent 的类型化请求为一个可审计重任务创建，并持有任务边界、权限、生命周期与审计责任的一次本地深度执行过程。会话可以中断恢复，完成后封存且不跨任务继承隐藏上下文；底层执行能力可以替换，但不能因此取得主控权或业务事实写入权。 -_Avoid_: Codex 会话、Claude 会话、外部 Agent 对话、独立 Agent 任务 +**Agent Host** +A local application/runtime capable of hosting the active Agent or OfferU Skill, such as Codex, WorkBuddy/CodeBuddy, Claude Code, OpenCode, OMP, Pi or another supported host. Detected does not mean verified. -**任务能力授权**: -OfferU 操作控制面依据使用者授权为一个托管执行会话签发的 Operation 与数据范围白名单，只允许完成当前可审计重任务所需的最小能力。它随会话结束失效，不授予业务事实写入权，也不能由主控 Agent、Skill 或执行器自行扩大。 -_Avoid_: Agent 权限、全局工具权限、Prompt 白名单、用户角色 +**Agent Run** +One auditable execution attached to a user goal. A Run records selected Skill, inputs, tool events, proposals, outputs and terminal state. Hidden model context is not Career Truth. -**Run 工件工作区**: -一个 Agent Run 独占的隔离文件空间，用于主控 Harness 处理显式输入、中间文件和候选产物。它不是职业事实源或跨 Run 记忆，不能包含 OfferU 数据库、配置、源码或未授权职业数据；其中产物必须经审核和 Operation 才能进入正式业务状态。 -_Avoid_: 项目工作区、OfferU 仓库、Agent 记忆目录、共享临时目录 +## Skills and tools -**Run 工具授权**: -OfferU 操作控制面依据所选 Skill 和使用者授权，为一个 Agent Run 限定可调用的 Operation、数据范围、Run 工件工作区和外部网络能力。授权随 Run 结束失效，主控 Harness 或接入包不能自行扩大，也不能把原生 Coding Agent 工具变成业务写路径。 -_Avoid_: 全局工具权限、Harness 默认权限、项目级 Shell、自动授权 +**OfferU Skill** +The portable instructions that teach a compatible Agent host how to discover OfferU capabilities and respect OfferU's truth, permission and confirmation boundaries. -**可审计重任务**: -可以取消、重放并检查输入、工具调用、输出和来源的长耗时任务。第一阶段包括公司/岗位深度调研、批量 JD 评估和已登记工作源的变化摘要；其结果必须经过 OfferU 的事实门和使用者确认后才能影响领域数据。 -_Avoid_: Agent 自动化、后台任务、Profile 自动更新 +**Third-party Career Skill** +An independently installed resume, recruiting, interview, negotiation or career-coaching Skill. It may contribute methodology or draft content but cannot directly mutate OfferU truth or weaken safety rules. -**统一控制台**: -让使用者或本地 Coding Agent 通过 GUI、机器 CLI、交互式 TUI 或斜杠 Skill 命令操控 OfferU 的多入口控制面。所有入口都调用同一 Operation Registry，并共享参数 schema、权限、确认、审计、数据授权和错误语义；控制台本身不实现业务逻辑。 -_Avoid_: CLI 后端、TUI 应用、第二套控制系统 +**Agent Tool Surface** +The intentional subset of Registry Operations exposed to Agents. -**机器 CLI 契约**: -OfferU 向主控 Agent 和本地自动化公开的唯一机器控制契约，以结构化能力探测、manifest、Operation schema、dry-run、执行、提案状态、取消和事件定义可调用表面。Harness 接入包可以包装该契约，但不能确认自身提案，也不能另建 MCP、原始 HTTP、数据库或任意 shell 业务入口。 -_Avoid_: MCP 业务接口、REST 自动化后端、Shell 脚本协议、固定 Provider argv +**Active Skill Surface** +The smallest task-specific set of Operations loaded after a Skill is selected. -**OfferU Agent Bridge**: -外部主控 Harness 将自身会话关联到 OfferU Agent Run，并取得当前任务上下文和已授权 Operation 的唯一确定性连接面。主会话、推理和工具循环属于外部 Harness；Bridge 不规划任务、不拥有业务事实，也不成为第二个 Agent。 -_Avoid_: OfferU Harness Host、内置 Agent Runtime、MCP Host、第二主脑 +**Capability Gap** +A user goal for which no legal public OfferU Operation path exists, even assuming an ideal Agent. -**OfferU Agent Runtime**: -由 `AgentRuntimeProvider` 暴露的 provider-neutral 执行边界，负责 thread、turn、event、Skill/Plugin 发现、审批中断、取消和恢复等 Harness 生命周期。Codex App Server 是首个主 Provider，Pi/Replay 适配器用于当前本地兼容与确定性验收，其他 Provider 必须通过同一契约后才能标记支持；该边界不拥有 Career Truth，也不能替代 Operation Registry。 -_Avoid_: Career Runtime、业务 Agent、第二套 Operation Registry、Codex Core Fork +**Tool Discovery Failure** +A legal capability exists, but the active Agent fails to find or select it. -**CareerTask**: -OfferU 控制面持久化的长任务执行信封，记录 task type、目标、provider、输入契约、状态、事件、checkpoint、结果引用和显式失败。它与可见的求职任务、主控 Agent Run 和 Hosted Executor Session 不同；其结果仍是候选或提案，不能直接成为职业事实。 -_Avoid_: Job、求职任务、Agent Run、后台字符串调用、事实表 +## Career truth and learning -**Agent Provider Health**: -OfferU 对 Agent Runtime provider 保存的脱敏健康快照，至少表达 available、authenticated、blocked、版本、协议和最后错误。Codex 401 属于 Provider Health/G2B live 验收阻塞，不是 Role Intelligence 业务事实，也不能触发静默换凭据或换 Provider。 -_Avoid_: API Key、Auth Token、Career status、LLM 业务结果 +**Career Profile** +The long-lived, evidence-backed representation of the user's experience, achievements, skills, preferences and goals. -**OfferU Capability Plugin**: -通过自有版本化 Manifest 组合 CLI、Skill、capability、side effect、权限和输出契约的本地能力包。安装改变 Agent 能力发现，卸载只禁用能力；CLI 输出必须是 JSON，插件不能直连数据库、拥有 Career Truth 或绕过 Operation Registry。首个真实公开源实现是 `job-search`；fixture 插件只能用于 replay/验收，不能伪装成 live source。 -_Avoid_: Codex Fork、Marketplace 业务契约、插件数据库、自由 Shell 入口 +**Career Evidence** +A fact or source-backed statement that can support resume, matching or interview work. -**AutomationEvent**: -OfferU 控制面接收的可幂等外部或内部信号，例如 `JOB_SAVED`、邮箱进展和面试完成。事件只触发明确的 Automation Rule，不直接修改 Career Truth；分发失败、Provider 阻塞和结果引用都必须持久化。 -_Avoid_: 无限 Agent Loop、隐式触发器、聊天消息、静默状态变更 +**Observation / Candidate** +New information that may be relevant but is not yet canonical truth. Sources include resumes, user statements, authorized Agent memory, email, browser receipts and interview/debrief learning. -**Automation Inbox**: -从 AutomationEvent、CareerTask 和候选提案派生的使用者处理队列，按 needs approval、needs review、FYI、completed、failed 分类。它是注意力投影，不是新的事实表；关闭项目不会代替 Operation 确认或 Career Memory 提交。 -_Avoid_: 弹窗风暴、自动批准、第二套任务数据库、直接写 Profile +**Learning Observation** +A reviewable signal produced by outcomes, user corrections, interview performance or repeated behavior. It can propose a Profile change but does not silently become fact. -**Harness 接入包**: -安装到一种外部 Coding Agent Harness 中、把 OfferU Skill、上下文、Operation、Agent Run 事件和人类控制界面投影为该宿主原生能力的薄集成。支持 UI 扩展的宿主使用 host/client 双面插件：host half 连接 CLI-first Bridge，client half 注册原生 OfferU 工作区；它只适配宿主差异，不包含求职业务逻辑，也不能扩大权限或形成独立事实源。 -_Avoid_: Harness Driver、CLI Wrapper、Provider 业务后端、iframe 应用、MCP 插件 +**Progressive Profiling** +Ask the minimum during onboarding and request additional information only when it helps a current decision. -**Harness 主界面**: -使用者与主控 Agent 对话并管理其原生会话的 Harness 界面，是本地 Coding Agent 使用者的默认产品外壳。它拥有提示输入和会话交互，但不拥有 OfferU 业务事实、Operation 确认或求职状态。 -_Avoid_: OfferU 聊天框、第二工作台、Agent 控制面、业务事实界面 +## Job and application flow -**OfferU 工作区**: -由 OfferU 拥有并通过统一领域投影、交互状态机与 Operation 合约投影到 Harness 主界面的人类控制表面。各 Harness 使用自身原生组件和视觉语言渲染，不共享同一套 React 页面；它可以按宿主能力拆成全局入口、全局确认界面和任务内主视图，用于浏览求职流程、事实、证据、Run、提案和结果，大画布任务则在同一状态边界下弹出 OfferU 专注窗口。它不要求宿主提供一个永远占据中央区域的全局页面，不提供第二个 Agent 提示输入，也不把全局领域数据变成一个全局模型会话。 -_Avoid_: 独立主应用、OfferU Agent 聊天、Harness 侧栏替代品、嵌入网页副本 +**Job Capture** +User-triggered import of the currently viewed job page into OfferU. It is not background crawling and does not mean the user has applied. -**宿主原生工作区渲染器**: -Harness 接入包 client half 中只负责把 OfferU 的类型化领域投影和交互状态映射为该宿主原生组件、布局、令牌与可访问性行为的薄渲染层。它不拥有领域状态机、Operation 规则或确认决策，也不能为了复用视觉而嵌入共享 React 页面、复制 OfferU SPA 或维护第二份业务状态。 -_Avoid_: 共享 UI 包、品牌微前端、主题皮肤、iframe 页面、宿主无关 React 页面 +**Job Context** +The opportunity-specific workspace containing the job, research/role signals, evidence gaps, resume/application material, application state, interview preparation and timeline. -**OfferU 任务视图**: -OfferU 工作区在当前求职任务与 Harness session 内的主操作表面，首先让使用者看清任务状态、下一动作、待确认事项和已产出结果；上下文、Run、Operation、证据与候选工件都从该任务进入。它可以读取全局职业数据与流程导航，但任何 Agent 动作都绑定当前任务、Run、授权和事件流；切换任务必须切换或恢复对应 Harness session。 -_Avoid_: 全局 Agent 面板、全局 OfferU 首页、聊天流插卡、第二聊天页、跨 Session 控制台、工作台 iframe +**Application Attempt** +One real application to a job/opportunity. Re-applying may create another attempt. -**任务视图主状态**: -OfferU 任务视图首屏在任一时刻只突出一个最需要使用者理解或处理的状态，固定优先级为待确认、失败或断连、正在执行、下一动作、最近完成。它是从提案、连接、Run、任务和 outcome 派生的注意力投影，不覆盖底层事实；未成为主状态的信息仍可在详情和时间线中查看。 -_Avoid_: 并列仪表盘、多个同权主按钮、AI 在线、卡片堆砌、用最近完成遮住待确认 +**External Progress Signal** +An email or other authorized message that suggests something changed. It is evidence, not the stage itself. -**任务会话绑定**: -OfferU 工作区的入口和领域数据可以全局可达；只有完全空白且尚未绑定的 Harness session，才能在使用者通过 OfferU 入口显式选择或创建求职任务后建立一次绑定，一条 session 只能绑定一个求职任务且绑定后不可改绑。已有聊天或工具历史、或需要切换任务时，必须新建或恢复对应 session，并同时切换推理上下文、授权和事件流，不能把多个岗位继续写入同一隐藏模型上下文。 -_Avoid_: 全局 Agent Session、Session 改绑、历史会话补绑、跨任务隐藏记忆、按页面建 Session、共享 Run +**ApplicationProgressCandidate** +A proposed progress interpretation awaiting review or an explicit safe policy decision. -**Harness 支持目录**: -OfferU 明确维护的外部主控 Harness 集合，包含 Codex、DeepSeek Harness、Claude Code、OpenCode 与 Pi；Codex 和 DeepSeek Harness 是首批优先接入目标。目录声明产品目标，某台设备上的实际可用性仍由对应 Harness 接入包实时探测，不能用假能力或静默替代伪造支持。 -_Avoid_: Provider 列表、模型列表、固定命令表、自动降级链 +**ApplicationStageEvent** +The durable event representing a confirmed application-stage transition. -**主控 Harness 一致性契约**: -Codex、DeepSeek Harness、Claude Code、OpenCode 与 Pi 被标记为“支持”前必须共同满足的完整业务行为契约，包括创建与恢复会话、追加指令与运行中转向、中断与取消、通过 CLI-first Agent Bridge 调用 OfferU Operation、暂停并恢复使用者确认、输出统一事件流，以及显式报告完成或失败。宿主可以按能力使用原生嵌入工作区或 OfferU companion window，但不得因此缩减业务能力、改用一次性问答或隐藏降级；Codex 和 DeepSeek Harness 仅决定实现优先级，不降低其他三种的最终验收门槛。 -_Avoid_: 基础可用、实验性支持、兼容模式、最低公分母协议 +**External Submit** +The user's irreversible action on a recruitment site. OfferU may prepare or fill safe fields, but does not silently perform final submit. -**Harness 交接**: -当前主控 Harness 无法恢复时，由使用者显式选择另一 Harness，并用原 Run 的已确认事实、可审计产物、未决提案和可公开执行摘要创建新 Agent Run 的转换。原 Run 保持中断或失败终态，隐藏会话、未记录推理和原生进程状态不得冒充可移植上下文。 -_Avoid_: 自动 Failover、跨 Harness 恢复、Session 迁移、同 Run 换 Provider +## Interaction model -**受控 CLI Broker**: -OfferU Agent Bridge 内部接收主控 Agent 提交的结构化 JSON/JSONL 命令，在绑定当前 Agent Run、Run 工具授权和幂等信息后分派到对应 Operation，再把标准结果返回主控会话的边界。它不接收 shell 字符串、管道、重定向、任意可执行文件或绕过确认的调用，也不把 Harness argv 变成业务契约。 -_Avoid_: Shell Tool、Bash/PowerShell 代理、MCP Tool、通用 subprocess、动态业务 API +**Today / Next Best Action** +The guided projection of what matters now. It is derived from Career State and is not a second task truth store. -**OfferU 确认**: -使用者在 OfferU 拥有的嵌入工作区或专注窗口中核对 Operation 提案、影响和证据后作出的批准或拒绝，是提案获得执行授权的唯一来源。Harness 原生 approval、接入包和模型可调用 CLI 只能请求并等待，不能代表使用者作出决定。 -_Avoid_: Agent 确认、Harness Approval、CLI confirm、模型自批、聊天回复确认 +**Guided Mode** +Default beginner experience. OfferU recommends at most a few high-value next actions and explains why they matter now. -**斜杠 Skill 命令**: -在主控 Agent 对话入口或 TUI 输入框中显式激活一个版本化 Skill 的命令形式。`/offeru` 打开技能菜单，`/skill-id` 或已声明 alias 直接进入具体 Skill；两种入口都从 Skill Registry 自动生成并解析到同一 Skill ID，只选择协议与允许操作集合，不执行 shell，也不绕过领域事实门。 -_Avoid_: Slash Command、快捷命令、Shell 命令 +**Power Mode** +Advanced access to Agent chat, Skills, CLI, batch workflows and diagnostics. It must not be required for normal onboarding. -**Skill Registry**: -OfferU 可用求职技能的唯一版本化目录，定义每个 Skill 的身份、适用目标、允许操作和确认边界。主控 Agent、斜杠 Skill 命令与其他控制入口都引用这一目录，不分别维护技能事实。 -_Avoid_: Skill 文件夹、Prompt 列表、命令表、外部 Agent 手册 +**Zero Setup** +The user installs OfferU and reaches useful value without installing Python/Node/Git or manually configuring Agent protocols. -**操作员 TUI**: -通过 `offeru tui` 启动的本地交互式终端界面，用于浏览投递、Agent Run、研究档案、记忆收件箱、提案和审计，并通过统一 Operation Registry 发起操作。它是人类控制面，不拥有独立数据库或业务写路径。 -_Avoid_: Agent TUI、Dashboard、Terminal App、后台控制台 +**Zero Figure-It-Out** +The user does not need to understand which mode/Skill/tool to invoke next; OfferU proactively guides the next action. -**本地个人工作区**: -由一名使用者拥有并在个人设备上运行的完整求职工作空间。第一阶段的所有数据、记忆和自动化均服务于这个唯一拥有者。 -_Avoid_: 默认用户、全局账号、单例用户 +## Safety vocabulary -**本地单人边界**: -第一阶段只有一个本地拥有者和一份本地数据空间。领域数据可以明确依赖这一产品约束，不引入 workspace、tenant、organization、登录、计费或租户权限等 SaaS 概念；若未来出现 SaaS 需求，重新进行独立架构设计。 -_Avoid_: SaaS 演进边界、预留多租户、默认用户兼容层 +**Proposal / HITL** +A protected mutation pauses for review before execution. -**Python 业务后端**: -第一阶段承载 Agent、记忆、简历、调研、投递、邮箱和面试领域逻辑的唯一业务运行时。Tauri/Rust 只负责桌面壳、系统托盘、钥匙串和进程管理等系统桥接，不与 Python 双写业务事实。 -_Avoid_: Python Worker、临时后端、Rust 迁移过渡层 +**False Success** +The Agent claims a task succeeded when trustworthy execution/outcome evidence does not show success. -**垂直交付阶段**: -从用户触发、Agent 或确定性处理、领域事实、审核界面到最终可见结果组成的可独立使用闭环。第一阶段按共同底座、投递进度、岗位调研与简历、AI 面试的顺序推进，不按数据库、API、前端等技术层横向铺开。 -_Avoid_: 模块开发、后端阶段、功能列表 +**Protected State** +Career records or external actions whose mutation requires explicit policy/confirmation safeguards. -**任务优先工作区**: -OfferU 工作区的统一交互模型，以使用者当前处理的求职对象、状态与下一动作作为主体；无论嵌入 Harness 还是弹出专注窗口都共享同一领域状态。 -_Avoid_: 营销式模块首页、页面 Hero、独立视觉工作室、第二聊天应用 +## Product surfaces -**求职流程导航**: -任务优先工作区按今日、机会、材料、进展与面试五个求职阶段组织内部入口；档案和设置是支持入口，主控 Agent 的连接状态贯穿各阶段而不是成为并列业务模块。 -_Avoid_: 平铺模块导航、功能清单导航、Agent 独立模块 +The stable top-level surfaces are: -**求职任务**: -使用者围绕一个求职目标持续推进的可见工作单元，可以关联领域对象、对话记录、Agent Run、待确认动作、证据与结果。对话是任务内的交互记录，Agent Run 是任务的一次执行，两者都不代表任务本身。 -_Avoid_: 对话、页面、Agent Run、后台任务 +~~~ +Today +Pipeline +Job / Opportunity +Profile +~~~ -**Agent Run**: -主控 Agent 在一个求职任务内进行的一次可暂停、可恢复和可审计执行，记录输入、选定 Skill、事件、Operation 调用、待确认动作与结果。每次 Run 的底层 Harness 会话只服务该 Run、可以从已保存状态重建且不能跨 Run 继承隐藏上下文；Run 不拥有任务目标或领域事实，完成后成为该求职任务的执行记录。 -_Avoid_: 求职任务、对话、Agent Session、后台任务、工作流 +Agent, Email, Browser Capture, Resume, Interview and Memory are cross-cutting capabilities, not separate competing products. -**Agent Run 事件**: -Agent Run 内按单调序号追加的 provider-neutral 生命周期记录，用于表达 Skill 选择、消息增量、Operation 提案与执行、外部执行器状态、审核点和 Run 终态。界面与恢复逻辑只消费这层标准事件；Pi、Codex 或 Claude 的原始事件可以进入审计 trace，但不能成为产品状态的唯一来源。 -_Avoid_: Provider JSONL、聊天消息、审计日志、前端通知 - -**今日行动队列**: -从待确认动作、临近截止、进行中求职任务和建议下一步派生的当日处理视图。它帮助使用者决定现在做什么，但不是求职状态或职业事实的来源。 -_Avoid_: 数据看板、统计首页、任务事实表 - -**移动端轻操作**: -任务优先工作区在手机尺寸下提供查看、确认、投递进展更新和主控 Agent 续接，不承担简历深度编辑或面试训练。它与桌面端共享领域事实和操作契约，但不追求界面能力完全对等。 -_Avoid_: 全端功能一致、移动端只读、手机版工作台 - -### 使用者模型 - -**使用者职业模型**: -OfferU 对使用者职业现状与发展可能性的分层表达，由职业证据、求职偏好、职业假设和学习观察共同组成。它不是一份简历，也不是可以被 Agent 整体重写的单一 Profile 文本。 -_Avoid_: 总 Profile、用户画像、优化记忆 - -**职业模型演进**: -使用者职业模型因新的已确认事实、显式偏好和经验证的求职学习而发生的长期变化，通过可追溯提案增补、纠正、取代或失效其中的组成部分。它改善模型的完整性、时效性、证据质量和决策适用性，但不美化职业证据、不把 Agent 推断改写成事实，也不整体重写一个单一 Profile 文本。 -_Avoid_: Profile 进化、用户画像优化、人格成长、自动改写 Profile - -**职业模型变更账本**: -按条目追加记录每次已接受或已撤销职业模型变化的长期历史，保留变化前后、来源、理由、影响和取代关系，并从仍有效的条目派生当前职业模型。它使单项撤销、变化解释和下游材料过期判断成为同一演进链的一部分。 -_Avoid_: Profile 快照、当前 Profile、编辑日志、提案列表 - -**岗位职业投影**: -面向一个具体岗位，从使用者职业模型中选择相关职业证据、偏好和已验证方向，并组织成当前岗位所需叙事的临时视图。它不修改长期职业模型；可跨岗位复用的新发现必须重新经过学习观察与审核后才能回流。 -_Avoid_: 岗位 Profile、定制用户画像、Profile 分支、事实改写 - -**职业证据**: -由使用者确认、能够追溯到具体来源的教育、经历、项目、技能或成果事实。它是简历、岗位匹配和面试回答可以直接引用的事实基础。 -_Avoid_: Profile 内容、用户画像、AI 推断 - -**求职偏好**: -使用者当前对岗位、地点、行业、工作方式或求职节奏的可变选择。使用者明确陈述的偏好本身构成确认；行为信号或 Agent 推断只能形成待审核更新提案，且无论如何都不构成职业经历事实。 -_Avoid_: 职业证据、永久性格、硬性事实 - -**职业假设**: -主控 Agent 根据职业证据、岗位研究或行为信号提出的待验证发展可能性。它必须与职业证据隔离，只有经过验证和使用者确认后才能成为目标方向。 -_Avoid_: 目标岗位、既定能力、Profile 事实 - -**学习观察**: -AI 面试、简历优化、岗位研究或投递进展产生的一条可追溯行为信号，例如使用者采纳的改写、反复出现的回答缺口或某类岗位的阶段结果。它可以触发职业模型更新建议，但本身不是职业证据。 -_Avoid_: 记忆、事实、用户标签 - -**学习证据门**: -区分可以支撑策略更新的强证据与只能形成待验证学习观察的弱信号。使用者的明确纠正、采纳或拒绝以及经确认的求职结果属于强证据；点击、停留、跳过、改写等隐式行为和 Agent 推断不能单独形成长期结论。 -_Avoid_: 行为画像、隐式学习、统一置信分 - -**记忆巩固**: -在 OfferU 空闲时对学习观察进行去重、冲突识别、过期判断和长期更新建议生成的过程。它不能静默创建职业证据，也不能自行修改 OfferU 的政策、权限或事实门规则。 -_Avoid_: 自动学习、夜间重写、Profile 优化 - -**记忆收件箱**: -集中呈现使用者职业模型变更建议的审核界面。每条建议展示变更前后差异、理由、来源和影响范围，并支持接受、拒绝、稍后处理与撤销；未处理建议不能静默成为职业证据或已验证职业假设。 -_Avoid_: Profile 通知、记忆列表、对话确认弹窗 - -**职业策略学习循环**: -将岗位推进、材料采纳、投递结果和面试反馈先记录为学习观察，经证据化复盘形成可检验的策略假设，再以待审核更新提案影响后续求职任务的跨任务学习过程。系统可以自动采集、分析和提出变更，但长期职业结论、程序性策略与助手工作风格只有经使用者确认后才能永久生效。 -_Avoid_: 自我进化、自动学习、人格重写、复盘报告 - -**工作源**: -使用者明确登记并授权 OfferU 只读同步的代码仓库、作品目录或文档集合。工作源中的变化可以形成学习观察或待确认职业证据，但未完成内容不自动等于履历成果。 -_Avoid_: 工作区、项目目录、本机扫描 - -**来源级联失效**: -原始来源被删除或撤销授权时，使该来源及其派生学习观察、候选证据、档案结论和下游引用立即退出检索、提示词、评分和记忆巩固的过程。系统只保留不含原始内容的最小审计外壳；其他独立有效来源提供的支持不受影响。 -_Avoid_: 软删除、停止同步、删除全部历史 - -### 岗位研究 - -**岗位采集**: -使用者在浏览器中显式触发，从当前有权访问的岗位详情页读取公司、职位、JD、来源链接等信息，并形成待导入 OfferU 的本地岗位候选。岗位采集及其后的岗位入库都不代表使用者已经申请该岗位，也不创建投递尝试。 -_Avoid_: 后台爬虫、自动投递、收藏即投递 - -**站点规则包**: -由 OfferU 维护并随浏览器扩展版本化发布的只读适配数据，描述某类招聘页面的识别信号、岗位字段定位、表单结构、受支持控件和提交回执证据。规则包只能引用扩展内置的已知控件驱动，不能携带或下载任意可执行代码；未经 fixture 与真实浏览器验收的规则只能用于诊断，不能启用填表。 -_Avoid_: 牛客规则同步、远程脚本、站点特例代码堆、万能选择器 - -**用户授权只读研究**: -使用者主动发起并监督的本机浏览器研究会话，用于读取其本人当前有权访问的登录态内容。该会话只能形成带来源的研究证据，不能代表使用者发布、联系、投递或改变外部账号状态。 -_Avoid_: 自动爬虫、后台采集、账号托管 - -**公司档案**: -围绕一家公司的业务、产品、组织环境、文化信号、招聘风险和时效性动态持续维护的来源化研究集合。它可以被该公司的多个岗位复用。 -_Avoid_: 公司简介、一次性调研报告 - -**岗位档案**: -围绕某家公司的一项具体岗位持续维护的研究集合，包含 JD 证据、团队线索、工作内容、面经、参考材料和求职策略。它引用公司档案，但不把其他岗位的信息混入当前岗位事实。 -_Avoid_: Job、JD 摘要、公司档案 - -**岗位推进闭环**: -使用者围绕一个高意向真实岗位，从导入、投前判断和调研推进到取得可审核材料与明确投递待办的一次端到端求职任务；外部提交仍由使用者完成。它是 OfferU 第一阶段的首要价值边界，不等于覆盖岗位发现、面试、Offer 与长期职业陪伴的全程求职系统。 -_Avoid_: 全程求职 OS、自动投递流水线、岗位自动申请 - -**有效推进效率**: -衡量一个岗位推进闭环从岗位导入到使用者批准材料与投递待办所消耗的使用者主动时间。只有职业事实准确、产物经审核可采用且返工处于约定边界内的闭环才算有效；模型生成速度、Agent 运行时长和投递数量都不能替代它。 -_Avoid_: 生成速度、Agent 耗时、投递吞吐、效率分 - -**投前决策**: -主控 Agent 基于当前岗位、已确认职业证据和已完成岗位调研提出的可复核建议，建议值只能是投、有条件投、不投或证据不足。它必须展示理由、缺口和来源；使用者最终选择与 Agent 建议分别保存，只有使用者确认投或有条件投后，投前决策闭环才允许生成该岗位的简历提案。 -_Avoid_: 岗位匹配分、Agent 评分、自动投递结论 - -**投前决策闭环**: -从选定真实岗位开始，依次检查职业证据、岗位调研和投前决策，在可持久化的人工确认点暂停，并在使用者确认投或有条件投后生成可审核简历提案的垂直交付阶段。调研进行中、证据不足与不投都是可解释退出状态；闭环不创建投递尝试，也不提交外部申请。 -_Avoid_: 求职自动流水线、简历生成流程、投递自动化 - -**调研证据等级**: -决定调研结论可如何表述的来源质量与交叉验证规则。公司业务、岗位要求等硬事实优先由官网、招聘官网和正式公告支撑；团队氛围、面经等主观信号需要至少两个独立近期来源，否则只能标为单一信号或未知。每条结论必须可追溯到具体来源。 -_Avoid_: 来源数量、AI 可信度、统一置信分 - -**简历表达模式**: -从公开且允许使用的参考材料中提炼出的匿名化结构、能力表达方式和量化方法。它保留来源与授权状态，但不保存或复刻真实候选人的完整简历，也不能作为使用者经历或成果的事实来源。 -_Avoid_: 模范简历、简历库、优秀候选人简历 - -### 投递进展 - -**投递表单填写**: -使用者完成投前判断后，由浏览器扩展从 OfferU 的已确认职业事实生成可审核填写计划，并在使用者再次确认后只填写当前外部表单中的空白、非敏感字段。它不覆盖网页已有值，不填写身份证明、薪资、工作许可、授权同意等敏感或承诺性字段，不点击最终提交，也不因填写完成而创建投递尝试；牛客或其他第三方云简历不能成为该流程的职业事实源。 -_Avoid_: 一键投递、自动申请、牛客云简历同步、填完即已投 - -**外部提交**: -使用者在招聘网站核对整份申请后亲自执行的最终提交动作。它会改变外部账号或申请状态，浏览器扩展和 Agent 都不得代替使用者触发；OfferU 只能在动作之后读取回执或成功页面作为待确认的提交证据。 -_Avoid_: 二次确认代提交、无人值守提交、表单填写完成 - -**提交候选证据**: -浏览器扩展在使用者亲自提交后，从成功页面或回执中提取的最小证据候选，例如公司、岗位、申请编号、发生时间和来源页面。它在使用者确认前不能创建投递尝试或改变正式投递阶段；使用者确认后，OfferU 才通过统一 Operation Registry 原子创建投递尝试及其初始 Submitted 阶段事件。 -_Avoid_: 已投递状态、自动记账、完整页面快照 - -**投递尝试**: -使用者在特定招聘批次中向一个具体岗位进行的一次独立申请。重复申请同一岗位会产生新的投递尝试，并保留各自的材料、渠道、状态和阶段时间线。 -_Avoid_: 投递记录、表格行、公司岗位 - -**外部进展信号**: -从邮箱、短信或其他授权渠道同步到 OfferU 的原始求职相关消息及其解析结果。它证明收到了一条消息，但不自动证明某项投递已经进入对应阶段。 -_Avoid_: 投递状态、面试事件、通知 - -**消息证据快照**: -为解释外部进展信号的来源、关联与阶段判断而保存的最小邮件证据，包括消息和线程标识、发送者、时间、主题、相关片段与正文哈希。完整正文默认只在同步和解析期间短暂使用，除非使用者对单封消息显式选择保存。 -_Avoid_: 邮件原文、邮箱缓存、通知正文 - -**短信转发导入**: -由使用者主动分享、粘贴或转发到 OfferU 的短信内容，并作为外部进展信号处理。第一阶段不要求 OfferU 直接读取手机短信库。 -_Avoid_: 短信同步、手机短信接入 - -**本地同步服务**: -在 OfferU 已启动并驻留系统托盘期间运行的个人消息同步能力。它负责发现外部进展信号并提醒使用者，使用者明确退出 OfferU 后即停止。 -_Avoid_: 云端同步、系统守护进程、后台爬虫 - -**系统凭据引用**: -OfferU 数据库中指向操作系统钥匙串条目的不透明标识，连同账号元数据和授权范围使用。OAuth token、IMAP 应用密码等原始密钥只存在 Windows Credential Manager、macOS Keychain 或 Linux Secret Service 中，不进入数据库、配置文件、日志或 Agent 上下文。 -_Avoid_: 加密密码字段、Token 配置、邮箱登录信息 - -**本地加密边界**: -由操作系统钥匙串保护主密钥，并覆盖数据库、简历附件、使用者显式保存的邮件正文、搜索索引、缓存与备份的统一静态加密范围。应用解锁后可以透明读取，但不得产生未受保护的旁路副本。 -_Avoid_: 仅数据库加密、依赖 BitLocker、附件加密 - -**云端数据授权**: -使用者针对具体模型供应商和数据类别授予的发送许可。OfferU 优先在本地解析与脱敏，并在运行前展示将发送的简历、邮件、面试转写或其他敏感数据类别；配置 API Key 只建立连接，不等于授权发送所有数据。 -_Avoid_: API Key 授权、模型权限、隐私开关 - -**候选进展**: -主控 Agent 根据外部进展信号提出的待确认关联与阶段变化。使用者确认前，它不能改变正式投递状态。 -_Avoid_: 正式状态、自动更新、提醒 - -**投递关联建议**: -Agent 从外部进展信号中识别公司、岗位、招聘批次、申请编号和邮件线程，并对可能对应的投递尝试进行排序与解释。确定性标识可以建立候选进展；存在多个合理候选或只有语义相似时必须由使用者选择，Agent 本身没有正式关联和阶段写入权。 -_Avoid_: AI 自动关联、邮件分类、自动推进 - -**投递阶段事件**: -使用者确认后记录的一次投递阶段变化，包含发生时间、来源和前后阶段。它构成投递时间线，并派生当前状态。 -_Avoid_: 状态字段、邮件分类、候选进展 - -**岗位生命周期里程碑轨道**: -OfferU 任务视图对一个已绑定真实岗位的生命周期投影，沿用 `prepared`、`applied`、`written_test`、`assessment`、`interview_1`、`interview_2`、`interview_hr`、`offer`、`rejected` 九个现有业务状态，但不把它们解释为九步线性完成度。笔试、测评和各轮面试可以未发生或被跳过；`offer` 与 `rejected` 是互斥终态分支，拒绝可以从任一投递后阶段发生。投前选择“不投”只结束投前任务，不伪造成 `rejected`，也不创建投递尝试。 -_Avoid_: 九步进度条、完成百分比、跳过即完成、Offer 后再拒绝、用 rejected 表示不投 - -**投递概览**: -从投递尝试及其阶段事件派生的紧凑表格工作区，是投递页的默认主视图，默认呈现当前阶段、下一动作和下一时间，并允许按需显示具体阶段列；进度看板只是同一批数据的辅助视图。它不是投递进展的事实源。 -_Avoid_: 投递表、宽表事实、阶段数据库 - -### 面试训练 - -**面试内容评价**: -基于面试问题、使用者回答、职业证据和岗位档案，对回答质量与岗位能力证据形成的解释性评价。它不使用摄像头信号推断人格或录用概率。 -_Avoid_: 面试总分、AI 打分、综合表现 - -**表达行为反馈**: -基于本地摄像头或音频派生的可观察行为，对姿态稳定、手势次数、语速或停顿等表达方式形成的反馈。它与面试内容评价分开，不代表性格、诚信、情绪或岗位胜任力。 -_Avoid_: 肢体语言分、情绪识别、人格评分 - -**面试评分规则**: -定义面试评价维度、权重、证据要求、阈值、提示和聚合方式的版本化声明。它只能引用明确授权的面试证据，不能执行任意代码或改变面试事实。 -_Avoid_: 评分 Skill、评分 Prompt、打分算法 - -**表达行为事件**: -本地视觉或音频分析识别出的一段可观察行为，包含事件类型、时间范围、置信度和检测器版本。它不包含原始视频、截图或逐帧关键点，也不携带人格或情绪推断。 -_Avoid_: 摄像头数据、Landmarks、肢体语言结论 - -**轮次式语音面试**: -主控 Agent 逐题提问，使用者逐题录音作答，并允许切换到文字输入的面试交互方式。每轮在本地完成端点检测并转写，默认只保存转写、题目时间范围和派生表达行为事件，不保存原始音频。 -_Avoid_: 实时语音面试、全双工面试、录音存档 +For product behavior see [Current Product North Star](./docs/product/current-product.md). \ No newline at end of file diff --git a/GOAL.md b/GOAL.md index 7bac5b08..6f8cd722 100644 --- a/GOAL.md +++ b/GOAL.md @@ -31,7 +31,7 @@ Public Release 指一个可公开分发的 local-first 个人 Career OS。陌生 ## Product North Star -OfferU 是 local-first 自动化 Career OS。它持续知道用户是谁、正在投什么、当前发生了什么、岗位真正看重什么以及下一步最值得做什么。系统自动完成研究、整理和准备；用户负责事实确认、关键决策和真实世界不可逆行为。 +OfferU 是 local-first 自动化 Career OS。它持续知道用户是谁、正在投什么、当前发生了什么、岗位真正看重什么以及下一步最值得做什么。系统同时减少 setup burden 与 decision burden：优先复用用户已有本地 Agent，并主动给出 Next Best Action；用户负责事实确认、关键决策和真实世界不可逆行为。 每个进入本 Release 的改动都必须明显改善至少一项： @@ -62,7 +62,7 @@ Agent 是全局能力；Memory 是 Profile 的演进机制；Resume、Role Intel TypeScript / React = UI、交互、本地 client state Python / FastAPI = Career Domain Runtime、Operation Registry、Automation、Data、Business State Tauri / Rust = Desktop shell、进程生命周期、OS 集成、Installer / Update boundary -AgentRuntimeProvider = Pi / Codex / DSH / future harness 的 provider-neutral seam +Agent Host / Runtime = Codex / WorkBuddy / Claude Code / OpenCode / OMP / Pi / future hosts；external-first，OfferU built-in fallback ``` - 不进行 Python → TypeScript 全量重写； @@ -73,7 +73,7 @@ AgentRuntimeProvider = Pi / Codex / DSH / future harness 的 provider-neutral se ## Stable Authority Model ```text -Agent Runtime = Reasoning Authority +Active Agent = Reasoning Authority（external local Agent preferred; OfferU fallback allowed） Operation Registry = Capability / Execution Control OfferU Domain Runtime = Career Truth User = High-risk Approval Authority @@ -110,7 +110,7 @@ Event → Rule → CareerTask → Agent / Runtime → Operation ### First Run -Launch → Welcome → explain OfferU → create/import Profile → add first Job → automatic preparation → Today。正常路径不得要求终端，也不得让用户理解 MCP、Operation Registry、Codex、Pi、DSH、FastAPI 或 SQLite。 +Install → Launch → auto-detect local AI → Resume + explicitly authorized memory → Profile → save first Job → optionally connect job-search inbox → Today / Next Best Actions。正常路径不得要求终端，也不得让用户理解 MCP、Operation Registry、Provider、Harness、FastAPI 或 SQLite。 Onboarding Golden Path 必须 100% 通过，并达到 0 uncaught exception、0 blank page、0 developer-only blocker。Today、Pipeline、Profile、Job、Resume 的空状态必须解释原因并给出下一步。 diff --git a/HANDOFF.md b/HANDOFF.md index cc61b438..90df4b7b 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -1,93 +1,66 @@ -# Closure Pass Report — 2026-09-17 +# OfferU Handoff -## Summary +Updated: 2026-09-23 -Four half-finished items from the previous goal are now closed: +Read these first: -| Item | Before | After | Evidence | -| --- | --- | --- | --- | -| Backend test suite | "52/52 relevant" (subset) | **621 passed, 9 skipped, 0 failed** | `pytest tests/ -q` via `hub start name=pytest-full-verify`, 3m42s | -| OpenAPI codegen | Generated file existed, not wired | **8 endpoints wired** | `Schemas`/`Ops` for request bodies + query params in `api.ts` + `agentConnection.tsx` | -| Job-preparation progress | Static text in "Next preparation" card | **Dynamic checklist** | Driven by `CareerTask.progress.stage` + `preApplication.stage` + `resumeProposal` presence; retry button on failed tasks | -| Demo media | Placeholder static-frame GIF | **Real recorded WebM→GIF** | 13.5s, 6.4MB, real click-through on showcase workspace | +1. docs/product/current-product.md +2. CONTEXT.md +3. ARCHITECTURE.md +4. STATUS.md +5. docs/architecture/2026-09-22-tool-surface-v2.md -## OpenAPI wiring details +Do **not** use archived DSH/Pi/Main-Agent designs as current product authority. -**8 endpoints** now use generated types for request bodies / query params: +## Current main direction -| Endpoint | Type | Location | -| --- | --- | --- | -| `agentRuntimeApi.syncContext` | `Schemas["AgentContextRequest"]` | `api.ts` line ~965 | -| `jobsApi.patch` | `Schemas["JobPatchRequest"]` | `api.ts` line ~182 | -| `jobsApi.patchBatch` | `Schemas["JobBatchPatchRequest"]` | `api.ts` line ~185 | -| `jobsApi.list` | `Ops["list_jobs_api_jobs__get"]["parameters"]["query"]` | `api.ts` line ~172 | -| `poolsApi.create` | `Partial & {name: string}` | `api.ts` line ~196 | -| `poolsApi.update` | `Schemas["PoolUpdateRequest"]` | `api.ts` line ~199 | -| `roleBenchmarkApi.build` | `Partial> & {runtime_id?: union}` | `api.ts` line ~809 | -| `preApplicationApi.review` | `Omit & {final_decision: PreApplicationDecisionChoice}` | `api.ts` line ~1208 | +OfferU is a local-first Career OS for non-technical job seekers. -**Response types stay hand-written** — FastAPI emits `unknown` for most response bodies in OpenAPI, so generated types are only useful for request bodies + query params. +~~~ +OfferU Desktop / Guided UX +→ external local Agent preferred, built-in fallback allowed +→ OfferU Skill + optional third-party Career Skills +→ Agent Tool Surface +→ Operation Registry / Proposal / Audit +→ Career Runtime / Career Truth +~~~ -**New file**: `src/lib/api-typed.ts` — facade re-exporting all wired request types + `JobsListQuery` + the API objects. +## Recently completed -## Progress projection details +- #14 Assisted Apply / connector foundation +- #17 Tool Surface V2 +- #19 Guided Next Best Actions + Skill composition contract -**Location**: `frontend/src/app/jobs/[id]/page.tsx` — "Next preparation" card, after the header. +## Active branch / PR to continue -**Data sources**: -- `useCareerTasks(50)` — finds `task_type==="role_intelligence" && target_type==="job" && target_id===String(jobId)` -- `preApplication.stage` — `resume_proposal_ready` / `decision_ready` → decision done -- `resumeProposal` — presence → proposal done -- `research` — presence → benchmark done +- #16 Real OMP RPC Eval — Draft. Use it to validate autonomous tool discovery and real task completion before further Tool Surface compression. -**Stages rendered dynamically** (not a state machine — derived from real state): -1. `saved` — always done (we're on the page) -2. `task` — `queued`/`running`/`completed`/`failed`/`blocked` from `CareerTask.status` -3. `benchmark` — `hasBenchmark` or `benchmarkDone` → done; `running`/`queued` → active -4. `decision` — `preApplication.stage` mapped to human-readable label -5. `proposal` — `resumeProposal` presence → done +## Next product milestone -**Retry**: when `preparationTask.status === "failed" && preparationTask.retryable`, a "重试准备任务" button calls `controlCareerTask(task_id, "retry")` via dynamic import. +Zero-Setup Golden Path: -## Demo video details +~~~ +native install +→ auto-detect a ready local Agent +→ Resume + explicitly authorized memory → Profile T0 +→ user-triggered browser capture of first Job +→ optional read-only inbox connection +→ useful Today / Next Best Action +~~~ -**Source**: Real click-through on `http://127.0.0.1:7412` (showcase vite with `VITE_SHOWCASE=true`). +## Non-negotiable boundaries -**Script**: `frontend/scripts/record-demo.mjs` — Playwright `recordVideo` on managed Chromium at `H:/tmp/offeru/pw-browsers/chromium-1243/chrome-win64/chrome.exe`. +- Career Runtime owns truth. +- Protected writes remain behind Registry / Proposal / user review. +- Third-party Skills are methodology/drafting layers, not truth or permission authorities. +- Browser capture is user-triggered by default; no beginner background crawler. +- Smart Fill never silently performs final submit. +- Email creates progress candidates before formal stage changes. +- Do not add a second Agent loop or second business backend just to support another host. +- Do not optimize Tool count without real Eval evidence. -**Flow**: Today → Jobs → Job Detail → Role Intelligence → Resume Proposal → Pipeline → Today (13.5s). +## Documentation rule -**Output**: `asset/demo/offeru-demo.gif` (6.4MB, 12fps, 1280px, palette-optimized). Original WebM kept at `H:/tmp/offeru/demo-video/page@*.webm`. +If a document conflicts with the current Product North Star, CONTEXT or ARCHITECTURE, archive the old document rather than creating another numbered decision layer. -**Console errors**: 0. - -## Verification - -| Check | Result | -| --- | --- | -| `npx tsc --noEmit` | 0 errors (excluding generated file) | -| `npx vitest run` | 16/16 pass | -| `npm run build` | ✓ built in 8.77s | -| Browser smoke (`#/jobs/1`, `#/jobs/353`) | Progress checklist renders; all cards present | -| `git diff --check` | Clean (CRLF warnings only) | - -## Files changed - -- `frontend/src/lib/api.ts` — 8 endpoints wired to `Schemas`/`Ops` -- `frontend/src/lib/api-typed.ts` — **new** facade for generated types -- `frontend/src/lib/agentConnection.tsx` — `AgentContextRequest` type alias + typed payload -- `frontend/src/lib/hooks.ts` — `JobFilters.pool_id` → `string` (generated schema says `string | null`) -- `frontend/src/app/jobs/page.tsx` — `scopedPoolFilter` → `String(selectedPoolFilter)` -- `frontend/src/app/optimize/components/OptimizeWorkspace.tsx` — `poolIdForQuery` → `String(poolFilter)` -- `frontend/src/app/jobs/[id]/page.tsx` — `useCareerTasks` + `preparationTask` + `preparationProgress` memo + checklist render + retry button -- `frontend/src/components/jobs/RoleIntelligencePanel.tsx` — `PREPARATION_STAGES` projection (from prior session) -- `asset/demo/offeru-demo.gif` — replaced placeholder with real recording -- `STATUS.md` — closure pass table added -- `frontend/scripts/record-demo.mjs` — **new** recording script - -## Remaining risks - -- `useCareerTasks(50)` fetches all tasks — fine for 50 tasks, may need pagination later. -- The `benchmark` stage detection uses `preparationTask.result_ref.includes("role_benchmark")` — if the backend changes the ref format, this breaks. The `RoleIntelligencePanel` has its own `benchmark.status` check which is more reliable. -- The demo video is 6.4MB — acceptable for a README GIF but not ideal for web. A hosted MP4/WebM would be smaller. -- The `pool_id` type correction (`number | "ungrouped"` → `string`) is a real drift find — the backend expects string. Verified no callers pass raw numbers. +Previous handoff preserved at docs/archive/HANDOFF-2026-09-17.md. \ No newline at end of file diff --git a/INTERNAL_BETA.md b/INTERNAL_BETA.md index 48686de0..73fee74b 100644 --- a/INTERNAL_BETA.md +++ b/INTERNAL_BETA.md @@ -1,3 +1,6 @@ +> [!NOTE] +> **HISTORICAL INTERNAL-BETA WALKTHROUGH.** Keep this for regression/demo archaeology. It is not the current onboarding or product authority; use `docs/product/current-product.md`, `STATUS.md`, and `HANDOFF.md` for current direction. + # OfferU Internal Beta > [!IMPORTANT] diff --git a/README.md b/README.md index fda176a6..4df53e6c 100644 --- a/README.md +++ b/README.md @@ -136,12 +136,16 @@ Previous Interview Learning OfferU generates targeted focus areas, runs turn-based practice, challenges vague answers, produces transcript-backed debriefs and turns useful observations into reviewable learning candidates. -### A controlled agent, not a black box +### Your AI, with a controlled Career OS -OfferU lets an AI agent reason and use tools, but the model never owns business truth. +OfferU prefers the local AI agent you already use and allows a built-in fallback, but no model owns business truth. ```text -Agent Runtime +External local Agent (preferred) / OfferU fallback + ↓ +OfferU Skill + optional Career Skills + ↓ +Agent Tool Surface ↓ Operation Registry ↓ @@ -150,8 +154,7 @@ Proposal / Approval Career Runtime ``` -The agent reasons. The Operation Registry controls capabilities and side effects. The Career Runtime -owns persisted truth. You remain the approval authority for sensitive changes and irreversible actions. +The active agent reasons. OfferU controls capabilities, evidence, side effects and persistent truth. Third-party resume/interview/recruiting Skills may contribute methodology, while sensitive changes and irreversible actions remain under OfferU and user control. --- @@ -187,10 +190,11 @@ OfferU detects a local agent you already have, checks it, and consumes its own m ↓ Auto Detect ↓ -┌───────┼───────┐ -Codex Claude OpenCode +┌────────────┼────────────┐ +Codex WorkBuddy Claude OMP / others ↓ OfferU Skill + + compatible Career Skills ↓ OfferU Bridge ↓ @@ -289,11 +293,11 @@ The intended public user path is: ```text Download → Install -→ Launch -→ Connect your AI agent -→ Build Profile -→ Save a Job -→ Let OfferU prepare the rest +→ Auto-detect your local AI +→ Resume + optional authorized AI memory → Profile +→ Save your first Job from the browser +→ Optionally connect a job-search inbox +→ Today tells you what matters next ``` > If you find an `OfferU.exe` in the repository root, it is a legacy `0.1.0` binary, not the current @@ -331,11 +335,11 @@ These commands only validate their own scope; they do not mean "ready for beta" Current priorities are productization, not more top-level features: -1. **Zero-friction AI setup** — connect once, detect capabilities, default to Auto. -2. **Live Role Intelligence** — validate at least one real external research path end to end. -3. **Public desktop release** — signed installer, clean-machine setup, migration, backup, restore, upgrade. -4. **Privacy & security hardening** — finish the remaining security and privacy gates. -5. **Real-user feedback** — use it in actual job searches and fix the highest-impact issues. +1. **Zero-Setup onboarding** — native install, local-Agent auto-discovery, Profile bootstrap, first Job, inbox, useful Today. +2. **Real external-Agent Eval** — validate autonomous tool discovery and complete user journeys before further tool compression. +3. **Browser + inbox productization** — one-click job capture and beginner-friendly read-only progress sync. +4. **Public desktop release** — signed installer, clean-machine setup, migration, backup, restore and upgrade. +5. **Privacy, security and real-user iteration** — keep trust gates hard while reducing user effort. --- diff --git a/README_ZH.md b/README_ZH.md index 816bf034..d09b827d 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -128,12 +128,16 @@ Today、Pipeline、Job Detail 和 Timeline 读的是同一份底层职业状态 OfferU 会生成针对性的面试重点，进行多轮对话训练，追问含糊的回答，产出基于转写的复盘， 并把有价值的观察变成可审核的学习候选。 -### 受控的 Agent，不是黑盒 +### 用你已有的 AI，但让 Career OS 管住事实与执行 -OfferU 允许 AI Agent 推理和使用工具，但模型不掌握业务事实。 +OfferU 优先复用你本机已经在用的 Agent，也允许 OfferU 内置能力作为兜底；无论使用哪个模型，都不能直接拥有业务事实或绕过确认。 ```text -Agent Runtime +本地 Agent（优先）/ OfferU fallback + ↓ +OfferU Skill + 可组合求职 Skills + ↓ +Agent Tool Surface ↓ Operation Registry ↓ @@ -142,8 +146,7 @@ Operation Registry Career Runtime ``` -Agent 负责推理；Operation Registry 负责控制能力与副作用；Career Runtime 负责持有持久化事实。 -敏感变更和不可逆动作的最终批准权始终在你手里。 +Agent 负责推理；第三方简历、招聘、面试 Skill 可以提供方法论；OfferU 负责真实职业上下文、能力边界、副作用和持久化事实。 --- @@ -177,10 +180,11 @@ Agent 是全局能力，不是又一个割裂的聊天窗口。 ↓ 自动检测 ↓ -┌─────┼─────┐ -Codex Claude OpenCode +┌──────────┼──────────┐ +Codex WorkBuddy Claude OMP / 其他 ↓ OfferU Skill + + 可组合 Career Skills ↓ OfferU Bridge ↓ @@ -273,11 +277,11 @@ OfferU 还没有对外发布签名安装包。源码开发与内测请看： ```text 下载 → 安装 -→ 启动 -→ 连接你的 AI Agent -→ 建立职业档案 -→ 保存一个岗位 -→ 剩下的交给 OfferU 准备 +→ 自动发现本机 AI +→ 简历 + 可选授权 AI 记忆 → Profile +→ 浏览器保存第一个岗位 +→ 可选连接求职邮箱 +→ Today 主动告诉你下一步 ``` > 如果仓库根目录存在 `OfferU.exe`，那是历史 `0.1.0` 二进制，不是当前 Release Candidate，不要运行。 @@ -314,11 +318,11 @@ npm run build 当前优先级是产品化，而不是继续堆顶层功能： -1. **零摩擦 AI 接入** —— 连接一次，自动检测能力，默认 Auto。 -2. **真实可用的 Role Intelligence** —— 至少打通一条真实的外部研究链路。 -3. **公开桌面版发布** —— 签名安装包、clean-machine 安装、迁移、备份、恢复与升级验证。 -4. **隐私与安全加固** —— 完成剩余的安全与隐私 Gate。 -5. **真实用户反馈** —— 在真实求职流程中使用，修掉影响最大的问题。 +1. **Zero-Setup Onboarding** —— 原生安装、自动发现 Agent、建档、首个岗位、邮箱、可用 Today。 +2. **真实外部 Agent Eval** —— 先证明 Agent 能自主发现并使用 OfferU Tools 跑完真实流程，再继续压缩工具面。 +3. **浏览器 + 邮箱产品化** —— 一键保存岗位、只读进度同步、低门槛审核。 +4. **公开桌面版发布** —— 签名安装包、clean-machine 安装、迁移、备份、恢复与升级验证。 +5. **隐私、安全和真实用户迭代** —— 保持硬安全门，同时持续减少用户操作成本。 --- diff --git a/STATUS.md b/STATUS.md index c14ae835..17611919 100644 --- a/STATUS.md +++ b/STATUS.md @@ -1,105 +1,60 @@ # OfferU Status -Updated: 2026-09-17 +Updated: 2026-09-23 ## Verdict -```text +~~~ OFFERU_PUBLIC_RELEASE_NOT_READY -``` +~~~ -Internal Beta quality bar is largely met; Public Release still requires signed installer, live external Role Intelligence, real Gmail OAuth, clean-machine verification, and the remaining security/privacy residuals. +OfferU has converged on a local-first Career OS with a guided desktop experience, external-local-Agent-first reasoning, a shared Operation Registry, and evidence-backed Career Truth. ## Current phase -```text -AUTONOMOUS_PRODUCTION_READINESS -``` +~~~ +ZERO_SETUP_AND_AGENT_NATIVE_PRODUCTIZATION +~~~ -Ports: frontend `http://127.0.0.1:7410`, backend `http://127.0.0.1:8766`. The optional local llama.cpp endpoint `8080` is never a web entry point. +Current product authority: [docs/product/current-product.md](./docs/product/current-product.md). -## Gate dashboard +## Recently landed -| Gate | Status | Notes | -| --- | --- | --- | -| Core Product | PARTIAL | 10/10 composite, 50/50 first-run, interview learning smoke pass; lacks independent stranger acceptance | -| Data Safety | PASS | R43–R49, R76 covered | -| Security | PARTIAL | 3 legacy email bodies, artifact/PII scrub, retention policy, real OAuth, code signing remain | -| Reliability | PARTIAL | 100-cycle worker, RSS threshold, dual-process claim, retry/restart contracts pass; full matrix missing | -| Architecture / Control | PARTIAL | Static audit 0 findings; dynamic browser/legacy runtime audit and remote CI missing | -| Packaging | PARTIAL | Tauri bundle, sidecar, install lifecycle pass; installer unsigned, upgrade/clean-machine unverified | -| Live Runtime | PASS (staged) | Packaged Pi Agent verified in isolated config; live Role Intelligence still blocked on external provider | -| E2E | PARTIAL | Local managed-Chromium smoke passes; remote runner, clean-machine, migration matrix missing | - -## Next actions +- #14 Assisted Apply / ApplicationActionConnector foundation merged to main. +- #17 Tool Surface V2 merged: Registry breadth is separated from Agent-facing and active-Skill surfaces. +- #19 Guided Today + composable local Career Skills merged: Today can surface up to three Next Best Actions; OfferU Skill may safely compose with third-party resume/recruiting/interview Skills. +- Documentation authority reset: old DSH/Pi/Main-Agent architecture has been archived and removed from the default Agent reading path. -1. **Security/Privacy residual** — decide fate of 3 legacy email bodies; finish artifact/PII/retention audit. -2. **Release engineering** — signing certificate, previous-release upgrade/migration, CI runner, clean-machine UI, RC artifact. -3. **Reliability matrix** — cross-process provider/network/restart coverage. -4. **Live Role Intelligence** — configure a real provider and run the 10-role matrix; current `deepseek-v4-flash-free` returns model unavailable. +## Active work -## Trust-boundary pass (2026-09-19) +- #16 Real OMP RPC Eval remains Draft and is the current path for validating real external-Agent tool use. +- Zero-Setup consumer flow is the next product milestone: native installer → Agent auto-discovery → Profile bootstrap → first Job → inbox → useful Today. +- Tool Surface V2 should be optimized further only from real Agent traces, not by arbitrary tool-count targets. -`TRUST_BOUNDARY_P0_CLOSED`. Apple-Bar adversarial review found real trust defects; -this pass closed the verified P0s. Full report: `docs/review/apple-bar/00-SYNTHESIS.md`. +## Current product gates -| Item | Root cause | Fix | -| --- | --- | --- | -| Test DB isolation | Tests/scripts could resolve `DATABASE_URL` → real `djm.db`; conftest had no DB guard | `conftest.py` now sets `OFFERU_DATA_DIR` → isolated tmp before any app import + fail-closed path guard; 2 scripts repointed to isolated tmp. Verified: real `djm.db` md5 unchanged across full suite | -| Studio preview SSRF | `/api/studio/resumes/{id}/preview` served `html_content` on API origin; iframe unsandboxed → generated HTML could call privileged APIs | Restrictive CSP `sandbox` (empty = no scripts/forms/popups/same-origin) + `X-Content-Type-Options` on endpoint; `sandbox=""` on `