From 809cd834c14b48ccce11a927f7c6c6f023039c51 Mon Sep 17 00:00:00 2001 From: avabbbb <89175608+avabbbb@users.noreply.github.com> Date: Wed, 23 Sep 2026 16:57:06 +0800 Subject: [PATCH 01/15] docs: integrate Job Workspace model into GOAL.md --- GOAL.md | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/GOAL.md b/GOAL.md index 6f8cd722..5b2a3fb9 100644 --- a/GOAL.md +++ b/GOAL.md @@ -54,7 +54,9 @@ Job / Opportunity Profile ``` -Agent 是全局能力；Memory 是 Profile 的演进机制；Resume、Role Intelligence、Research、Application Packet 和 Interview 均属于 Job Context。Today、Pipeline、Agent 不拥有独立业务事实，只投影 OfferU Domain Runtime 中同一份 Career Truth。 +其中 **Job / Opportunity 是一个持久的 Job Workspace，而不是一次聊天或单纯详情页**。Job Snapshot、Role Intelligence、Evidence Map、Resume/Application Materials、Interview 与 Timeline 都属于同一机会工作区，并逐步物化 Agent 的准备结果。 + +Agent 是全局能力；Memory 是 Profile 的演进机制；Resume、Role Intelligence、Research、Application Packet 和 Interview 均属于 Job Workspace。Today、Pipeline、Agent 不拥有独立业务事实，只投影 OfferU Domain Runtime 中同一份 Career Truth。 ## Stable Technical Boundary @@ -110,15 +112,23 @@ Event → Rule → CareerTask → Agent / Runtime → Operation ### First Run -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。 +普通用户主路径： + +Install → Launch → auto-detect local AI → 在支持时自动投影/注册 OfferU Skill → Resume + explicitly authorized memory → Profile → save first Job → create/open canonical Job Workspace → optionally connect job-search inbox → Today / Next Best Actions。 + +高级用户允许从支持的外部 Agent 通过 OfferU Skill 直接开始一个 Job，但最终必须解析/创建同一个 canonical Job Workspace，不能形成 Agent-only 第二套项目状态。 + +正常路径不得要求终端，也不得让用户理解 Skill 安装、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 的空状态必须解释原因并给出下一步。 -### Today / Pipeline / Job +### Today / Pipeline / Job Workspace - Today 从 Application、Event、CareerTask、Candidate、Interview 和 Role Intelligence 派生，展示 completed、needs attention、next best action 和 failed/blocked tasks； - Pipeline 是 Application State 的主要视图，至少展示 Job、Stage、Next action、Last event、Priority； -- Job Detail 收敛 Overview、Role Intelligence、Evidence Gap、Application Materials、Interview、Timeline； +- Job Workspace 收敛 Job Snapshot、Role Intelligence、Evidence Map、Application Materials、Interview、Timeline； +- 长任务结果应逐步物化到 Job Workspace，不得只存在 Agent 会话文本中； +- 关闭/切换 Agent 后，用户仍能从 Job Workspace 理解已完成、待审核、阻塞/失败与下一动作； - 任何页面出现不同阶段都是 Release Blocker。 ### Resume Workspace @@ -211,6 +221,7 @@ Critical E2E 必须连续 10/10 通过，不依赖 retry 染绿；核心 Journey ## Product Claims and Support - README、官网和 UI 只能宣传真实验证的能力；Live Role Intelligence 未通过时只能称岗位差异分析 Beta； +- 首屏优先表达具体用户结果：一个 Job 进入 → 角色要求 × 可验证证据 → reviewable Job Workspace；“Career OS”、Operation Registry、Reasoning Authority 等作为第二层解释，不应成为普通用户理解产品的前置条件； - README 只有 Final Release Gate 通过后才从 POC/Internal Beta 改为正式 Release claim； - Public QUICKSTART 只包含 Download、Install、Launch、Onboarding，开发者启动移至 DEVELOPMENT.md； - 用户报告“Agent 不工作”时，支持人员通过 Doctor、Diagnostic Bundle、Error ID 定位 Provider auth、Backend、DB、Network 或 Task，不要求用户截图 Terminal； From 41d84d13fa07655e80f6b83920f15fd22b8f0db7 Mon Sep 17 00:00:00 2001 From: avabbbb <89175608+avabbbb@users.noreply.github.com> Date: Wed, 23 Sep 2026 16:57:14 +0800 Subject: [PATCH 02/15] docs: integrate Job Workspace model into README.md --- README.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 66 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 4df53e6c..df2ddc14 100644 --- a/README.md +++ b/README.md @@ -5,8 +5,12 @@

OfferU

- Your local-first AI Career OS.
- Understand every job. Tailor every application. Learn from every interview. + Give OfferU a job. Get an evidence-backed application workspace.
+ See what the role really asks for, what you can prove, and what to prepare next. +

+ +

+ A local-first AI Career OS that compounds what you learn across jobs and interviews.

@@ -55,10 +59,25 @@ Most job-search tools solve one step. -Your resume lives in one place. Job research lives in another. Application tracking becomes a spreadsheet. -Interview practice starts from zero every single time. +Your JD lives in the browser. Your resume lives in a file. Research lives in another tab. Application tracking becomes a spreadsheet. Interview learning disappears into another AI chat. + +So every application starts from zero. -OfferU treats the whole search as one evolving system instead of four disconnected chores: +OfferU changes the unit of work from **a chat** to **a durable Job Workspace**: + +```text +Target Job + ↓ +What does this role really care about? + × +What can I actually prove? + ↓ +What should I prepare next? + ↓ +Evidence-backed Job Workspace +``` + +That Workspace then compounds into the larger Career OS: ```text Career Profile @@ -82,6 +101,21 @@ Debrief & Learning Instead of opening a fresh AI chat for every job, OfferU keeps one persistent, evidence-backed career context and carries what it learns across the entire search. +### One Job, one durable Workspace + +A Job is not just a detail page. It is the canonical workspace for one opportunity: + +```text +Job Snapshot +Role Intelligence +Evidence Map +Application Materials +Interview +Timeline / Next Action +``` + +Agent work progressively materializes into these objects, so closing a chat does not make the work disappear. + ### Persistent career context OfferU maintains structured career evidence — experience, achievements, skills, preferences, goals and @@ -164,7 +198,7 @@ The active agent reasons. OfferU controls capabilities, evidence, side effects a | ------------ | -------------------------------------------------------------------------------------------------- | | **Today** | What changed, what OfferU finished, what needs your attention, and what matters next | | **Pipeline** | Every opportunity, application stage, timeline and next action | -| **Job** | Research, Role Intelligence, evidence gaps, resume, application packet and interview preparation | +| **Job** | Durable Job Workspace: snapshot, Role Intelligence, Evidence Map, materials, interview and timeline | | **Profile** | Long-term career evidence, goals, preferences and reviewed learning | Memory is a mechanism for evolving Profile — not a separate product silo. @@ -176,9 +210,31 @@ same Operation Registry instead of scraping or auto-applying on its own. ## AI setup -The product direction is **Connect → Auto → Ready**. +The product has **two front doors and one Career Truth**. + +**Normal users: App-first** + +```text +Install OfferU +→ auto-detect local AI +→ project/register OfferU Skill where supported +→ save a Job +→ work appears in the canonical Job Workspace +``` + +**Power users: Skill-first** + +```text +Open Codex / Claude Code / WorkBuddy / OpenCode / OMP / another supported host +→ enable OfferU Skill +→ "analyze this job for me" +→ Agent creates/resolves the canonical Job +→ open the same Job Workspace in OfferU +``` + +The product direction remains **Connect → Auto → Ready**. -> **Beginner: connect an agent. Advanced: configure the stack.** +> **Skill is the Agent entry; Job Workspace is the user product.** Normal users should not have to understand runtimes, protocol versions, model IDs or custom endpoints. OfferU detects a local agent you already have, checks it, and consumes its own model and account: @@ -294,8 +350,10 @@ The intended public user path is: Download → Install → Auto-detect your local AI +→ Project/register OfferU Skill where supported → Resume + optional authorized AI memory → Profile → Save your first Job from the browser +→ Open the canonical Job Workspace → Optionally connect a job-search inbox → Today tells you what matters next ``` From ae55dc28368d115d3d7d0da58d5b0261f66fabd9 Mon Sep 17 00:00:00 2001 From: avabbbb <89175608+avabbbb@users.noreply.github.com> Date: Wed, 23 Sep 2026 16:57:18 +0800 Subject: [PATCH 03/15] docs: integrate Job Workspace model into README_ZH.md --- README_ZH.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 66 insertions(+), 8 deletions(-) diff --git a/README_ZH.md b/README_ZH.md index d09b827d..b63f97a6 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -5,8 +5,12 @@

OfferU

- 一个会持续理解你、自动维护求职流程的本地 AI Career OS
- 保存一个目标岗位，OfferU 围绕你的真实经历完成岗位研究、针对性材料准备、投递管理和面试训练。 + 给 OfferU 一个岗位，得到一套有证据支撑的申请工作区。
+ 看清岗位真正要什么、你实际能证明什么，以及下一步该准备什么。 +

+ +

+ 一个会把每次岗位准备和面试学习持续积累起来的本地 AI Career OS。

@@ -53,10 +57,25 @@ ## 为什么是 OfferU -多数求职工具只解决其中一步：简历在一个地方，岗位研究在另一个地方，投递记录变成一张 Excel， -面试准备每次都从零开始。 +多数求职工具只解决其中一步：JD 在浏览器，简历在文件里，岗位研究在另一个页面，投递记录变成 Excel，面试复盘又散落在另一个 AI 对话里。 + +结果是：每投一个岗位，你都像从零开始。 + +OfferU 把工作的基本单位从“一次聊天”变成一个**持久的 Job Workspace（岗位工作区）**： + +```text +目标岗位 + ↓ +这个岗位真正看重什么？ + × +我实际上能证明什么？ + ↓ +我下一步该准备什么？ + ↓ +有证据支撑的 Job Workspace +``` -OfferU 把整段求职当成一套持续演进的系统，而不是四件互不相关的杂事： +然后这套工作区再持续积累成更大的 Career OS： ```text 职业档案 @@ -80,6 +99,21 @@ OfferU 把整段求职当成一套持续演进的系统，而不是四件互不 你不需要为每一个岗位都新开一个 AI 对话。OfferU 保留一份持续积累、有证据支撑的职业上下文， 并把它学到的东西带到后续每一次申请里。 +### 一个岗位，一个持久工作区 + +Job 不只是详情页，而是一个机会的 canonical 工作区： + +```text +岗位快照 +岗位理解 +证据地图 +申请材料 +面试 +时间线 / 下一动作 +``` + +Agent 的工作会逐步物化到这些对象里，所以关掉 Agent 对话，已经完成的工作也不会消失。 + ### 持续积累的职业上下文 OfferU 维护结构化的职业证据：经历、成果、技能、偏好、目标和已审核的学习观察。 @@ -156,7 +190,7 @@ Agent 负责推理；第三方简历、招聘、面试 Skill 可以提供方法 | ------------- | -------------------------------------------------------- | | **Today** | 发生了什么变化、OfferU 完成了什么、需要你关注什么、下一步做什么 | | **Pipeline** | 所有机会、投递阶段、时间线和下一动作 | -| **Job** | 岗位研究、岗位理解、证据缺口、简历、申请材料和面试准备 | +| **Job** | 持久 Job Workspace：岗位快照、岗位理解、证据地图、申请材料、面试与时间线 | | **Profile** | 长期职业证据、目标、偏好和已审核的学习内容 | Memory 是 Profile 的演进机制，不是独立的产品孤岛。 @@ -166,9 +200,31 @@ Agent 是全局能力，不是又一个割裂的聊天窗口。 ## AI 连接 -产品方向是 **连接 → 自动 → 就绪**。 +OfferU 有**两个入口，但只有一份 Career Truth**。 + +**普通用户：App-first** + +```text +安装 OfferU +→ 自动发现本机 Agent +→ 支持时自动投影/注册 OfferU Skill +→ 保存一个岗位 +→ 工作结果进入 canonical Job Workspace +``` + +**高级用户：Skill-first** + +```text +打开 Codex / Claude Code / WorkBuddy / OpenCode / OMP / 其他支持宿主 +→ 启用 OfferU Skill +→ “帮我分析这个岗位” +→ Agent 创建/解析 canonical Job +→ 回到 OfferU 看到同一个 Job Workspace +``` + +产品方向仍然是 **连接 → 自动 → 就绪**。 -> **小白：连接一个 Agent。进阶：配置技术栈。** +> **Skill 是 Agent 的入口，Job Workspace 才是用户的产品。** 普通用户不需要理解 Runtime、协议版本、模型 ID 或自定义端点。OfferU 会检测你本机已有的 Agent、 完成检查，然后直接使用它自己的模型和账号： @@ -278,8 +334,10 @@ OfferU 还没有对外发布签名安装包。源码开发与内测请看： 下载 → 安装 → 自动发现本机 AI +→ 支持时自动投影/注册 OfferU Skill → 简历 + 可选授权 AI 记忆 → Profile → 浏览器保存第一个岗位 +→ 打开 canonical Job Workspace → 可选连接求职邮箱 → Today 主动告诉你下一步 ``` From 7de8eda9369e1ca45d2010d6f69d9b87f9952e29 Mon Sep 17 00:00:00 2001 From: avabbbb <89175608+avabbbb@users.noreply.github.com> Date: Wed, 23 Sep 2026 16:57:23 +0800 Subject: [PATCH 04/15] docs: integrate Job Workspace model into docs/README.md --- docs/README.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/README.md b/docs/README.md index 9b3ef9ea..0b65997f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -36,7 +36,7 @@ Historical audits and dated reports are evidence of what was true when they were | Area | Current document | Purpose | | --- | --- | --- | -| Product | [Current Product North Star](./product/current-product.md) | Zero-setup, Guided UX, external-first Agent, fallback Agent, Skills ecosystem, browser/email journeys | +| Product | [Current Product North Star](./product/current-product.md) | Outcome-first Job Workspace, zero-setup App-first UX, Skill-first power-user entry, Guided Today, external-first Agent | | Goal | [GOAL.md](../GOAL.md) | Public-release goal and durable release gates | | Domain | [CONTEXT.md](../CONTEXT.md) | Career Truth, candidates, evidence, applications, memory and Agent vocabulary | | Architecture | [ARCHITECTURE.md](../ARCHITECTURE.md) | Short current system boundary | @@ -50,6 +50,12 @@ Historical audits and dated reports are evidence of what was true when they were | Status | [STATUS.md](../STATUS.md) | current implementation state and blockers | | Handoff | [HANDOFF.md](../HANDOFF.md) | latest continuation context for Coding Agents | +## Product design rationale + +These explain why current product rules exist; they are references, not higher authority. + +- [Skill-first Agent Entry, Job Workspace & Product Story](./product/skill-first-job-workspace-story.md) — rationale and external reference patterns behind the now-adopted App-first / Skill-first dual entry, canonical Job Workspace and outcome-first product story. + ## Document status classes - **CURRENT AUTHORITY** — actively defines current product/architecture. @@ -87,9 +93,12 @@ Do not rewrite old eval numbers to make them look current. Preserve the result a ~~~ OfferU Desktop = primary Career OS experience +Job Workspace = durable product object for one opportunity +App-first = default normal-user front door +Skill-first = power-user Agent front door External local Agent = preferred reasoning host Built-in OfferU Agent = fallback -Agent Skills = composable methodology layer +Agent Skills = composable methodology / Agent entry layer Operation Registry = execution / permission authority Career Runtime = canonical truth Today = guided next-best-action layer From 35d4c15c2b4c866358eeb55155608ef41ced1ca5 Mon Sep 17 00:00:00 2001 From: avabbbb <89175608+avabbbb@users.noreply.github.com> Date: Wed, 23 Sep 2026 16:57:27 +0800 Subject: [PATCH 05/15] docs: integrate Job Workspace model into docs/architecture/agent-system.md --- docs/architecture/agent-system.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/architecture/agent-system.md b/docs/architecture/agent-system.md index 0a5a376e..51837705 100644 --- a/docs/architecture/agent-system.md +++ b/docs/architecture/agent-system.md @@ -37,9 +37,12 @@ Never translate binary found into supported. 4. It installs/projects the OfferU Skill where supported. 5. The host uses its own model/account. 6. OfferU exposes only the relevant Skill/tool surface. +7. Agent work resolves against canonical Profile / Job / Application state and materializes into the same Job Workspace visible in OfferU Desktop. A fallback OfferU Agent may be used if no external host is suitable. +The Skill is an **Agent entry surface**, not a second product database or project system. A power user may begin from a supported Agent, but the result must be the same governed OfferU state that the Desktop app reads. + ## Skill composition A host may activate OfferU plus third-party Career Skills. OfferU context should ground third-party methodology. Third-party output is draft/candidate material until accepted through OfferU's normal persistence path. @@ -57,9 +60,13 @@ manifest The tool surface must be evaluated with real Agent tasks. Do not optimize for a pretty tool count at the expense of task completion. -## Confirmation +## Preparation plan and confirmation + +Before broad preparation, paid model work or external side effects, the Agent should surface a compact user-facing plan when scope/cost/irreversibility makes that useful. The plan explains the intended work, evidence basis, proposal status and any known account/rate/cost boundary. + +Protected state changes still create Proposals. The Agent may request a protected mutation and wait. It may not self-confirm it. OfferU UI is the authoritative human review surface. -Protected state changes create Proposals. The Agent may request a protected mutation and wait. It may not self-confirm it. OfferU UI is the authoritative human review surface. +Do not turn this into confirmation spam: work already inside an agreed safe scope can proceed until account, cost, scope or side-effect risk materially changes. ## Native tools From 34a259c4016a1ec4009cfeac80f6c001348f5107 Mon Sep 17 00:00:00 2001 From: avabbbb <89175608+avabbbb@users.noreply.github.com> Date: Wed, 23 Sep 2026 16:57:36 +0800 Subject: [PATCH 06/15] docs: integrate Job Workspace model into docs/architecture/workbench-interaction.md --- docs/architecture/workbench-interaction.md | 31 +++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/docs/architecture/workbench-interaction.md b/docs/architecture/workbench-interaction.md index 720f81ed..8e3499ec 100644 --- a/docs/architecture/workbench-interaction.md +++ b/docs/architecture/workbench-interaction.md @@ -12,13 +12,15 @@ A local Agent may be the preferred reasoning environment, but users should not b ~~~ Install → Agent auto-discovery +→ OfferU Skill projected automatically where supported → Know Me / Profile → Save first Job +→ Open Job Workspace → Connect inbox → Today ~~~ -The default interaction is Guided, not command-first. +The default interaction is Guided, not command-first. The user enters through OfferU Desktop; Skill installation and tool routing stay behind the product unless the user explicitly enters Power Mode. ## Today @@ -42,7 +44,15 @@ Do not ask every preference on day one. Ask small contextual questions only when Normal users should not have to choose Agent Skills manually. Natural-language goals and current Career State should route to the relevant Skill. -Advanced users may open Agent/Skill/CLI controls in Power Mode. +Advanced users may open Agent/Skill/CLI controls in Power Mode, including a Skill-first lane from a supported external Agent. A Skill-first action must create or update the same canonical Job Workspace visible in OfferU Desktop; it must never create a parallel Agent-only project. + +A useful mental model is: + +~~~ +Skill = Agent entry +Job Workspace = user product +Career Runtime = shared truth +~~~ ## Skill ecosystem UX @@ -64,9 +74,24 @@ open job page After inbox connection, OfferU may proactively detect likely career updates but presents ambiguous or important changes for review. The user should see a human-readable card, not IMAP/UID/cursor terminology. +## Job Workspace + +A Job is not merely a detail page. It is the durable workspace for one opportunity. + +It should progressively collect: + +- Job Snapshot; +- Role Intelligence; +- Evidence Map; +- application materials and versions; +- interview preparation / debrief; +- canonical Timeline and next action. + +Agent work should materialize into these visible objects as it completes. If the user closes the Agent conversation, the work remains understandable and reviewable in the Workspace. + ## Focus work -Resume deep editing, interview practice and complex evidence review may use focused workspaces, but they remain part of the same Job/Profile truth. +Resume deep editing, interview practice and complex evidence review may use focused sub-workspaces, but they remain projections of the same Job/Profile truth. ## Design rule From a8a8b0cd0bdf14be96ef5841b458d3f50d505498 Mon Sep 17 00:00:00 2001 From: avabbbb <89175608+avabbbb@users.noreply.github.com> Date: Wed, 23 Sep 2026 16:57:48 +0800 Subject: [PATCH 07/15] docs: integrate Job Workspace model into GOAL.md From 5ec2969f66b8540ecf85d7552298031eaa3ba3cd Mon Sep 17 00:00:00 2001 From: avabbbb <89175608+avabbbb@users.noreply.github.com> Date: Wed, 23 Sep 2026 16:57:52 +0800 Subject: [PATCH 08/15] docs: integrate Job Workspace model into README.md From 255c764bdca09dc3726ecfdc3baf771a3b7d55cd Mon Sep 17 00:00:00 2001 From: avabbbb <89175608+avabbbb@users.noreply.github.com> Date: Wed, 23 Sep 2026 16:57:55 +0800 Subject: [PATCH 09/15] docs: integrate Job Workspace model into README_ZH.md From 122be7075bc218625c28b51d0f2cc6c6069edb2f Mon Sep 17 00:00:00 2001 From: avabbbb <89175608+avabbbb@users.noreply.github.com> Date: Wed, 23 Sep 2026 16:57:59 +0800 Subject: [PATCH 10/15] docs: integrate Job Workspace model into docs/README.md From 4c809d8ef09184084bece52c6632166695c5cd99 Mon Sep 17 00:00:00 2001 From: avabbbb <89175608+avabbbb@users.noreply.github.com> Date: Wed, 23 Sep 2026 16:58:10 +0800 Subject: [PATCH 11/15] docs: integrate Job Workspace model into docs/architecture/agent-system.md From e8854e9f38a4b2cde83fe9bad6356c32e22fcf06 Mon Sep 17 00:00:00 2001 From: avabbbb <89175608+avabbbb@users.noreply.github.com> Date: Wed, 23 Sep 2026 16:58:13 +0800 Subject: [PATCH 12/15] docs: integrate Job Workspace model into docs/architecture/workbench-interaction.md From 4c3a6db5f9cb4ffcd0853ae08c1a35dc43e117a7 Mon Sep 17 00:00:00 2001 From: avabbbb <89175608+avabbbb@users.noreply.github.com> Date: Wed, 23 Sep 2026 16:58:17 +0800 Subject: [PATCH 13/15] docs: integrate Job Workspace model into docs/product/current-product.md --- docs/product/current-product.md | 141 ++++++++++++++++++++++++++++++-- 1 file changed, 132 insertions(+), 9 deletions(-) diff --git a/docs/product/current-product.md b/docs/product/current-product.md index 5583c834..34f85d74 100644 --- a/docs/product/current-product.md +++ b/docs/product/current-product.md @@ -10,7 +10,25 @@ This document defines the current product shape of OfferU. Historical audits, da OfferU is a **local-first AI Career OS** for normal job seekers. -It should reduce both: +The category is broad; the first-use promise should be concrete: + +> **Give OfferU a job. It shows what the role really asks for, what you can prove, and prepares the application around that evidence.** + +The core product equation is: + +~~~ +Target Job + ↓ +What does this role care about? + × +What can I actually prove? + ↓ +What should I prepare next? + ↓ +Evidence-backed Job Workspace +~~~ + +OfferU should reduce both: 1. **setup burden** — users should not need Python, Node, Git, MCP, CLI, model IDs or provider configuration to start; 2. **decision burden** — users should not need to know which feature, mode, Skill or Agent command to invoke next. @@ -20,15 +38,18 @@ The default experience is: ~~~ Install → Find my local AI automatically +→ Project / register the OfferU Skill where supported → Resume + explicitly authorized AI memory → Profile → Save a real job from the browser -→ Connect a job-search inbox -→ Today tells me the next best actions -→ Agent prepares / analyzes / drafts +→ Create the canonical Job Workspace +→ Agent prepares / analyzes / drafts into that Workspace +→ Today tells me what needs attention next → User confirms important facts and irreversible actions → outcomes feed back into Profile and future decisions ~~~ +The user should experience a durable workspace, not a disposable AI conversation. + ## Product information architecture The stable top-level product model is: @@ -42,11 +63,43 @@ Profile - **Today** is the guided action layer. It answers “what matters now?” and shows at most a few primary actions. - **Pipeline** projects application state, timeline and next action from the same canonical events. -- **Job** contains role understanding, evidence gaps, resume/application material and interview preparation for one opportunity. +- **Job / Job Workspace** is the durable application workspace for one opportunity: Job Snapshot, Role Intelligence, Evidence Map, application materials, interview preparation and canonical Timeline all converge here. Agent conversations are only one way to modify this workspace. - **Profile** is the long-lived evidence-backed model of the user. Memory is an evolution mechanism for Profile, not a separate silo. Agent, Skills, Email, Browser Capture, Resume, Role Intelligence and Interview are capabilities across these surfaces, not competing top-level products. +## Two front doors, one Career Truth + +OfferU has two valid entry lanes that must converge on the same canonical state. + +### Normal user: App-first + +~~~ +Install OfferU +→ auto-detect a supported local Agent +→ project/register OfferU Skill automatically where supported +→ import resume / core evidence +→ save first Job +→ open Job Workspace +→ Guided Today handles the next decisions +~~~ + +Normal users do not need to know what a Skill, MCP server, Registry or provider topology is. + +### Power user: Skill-first + +A user already inside Codex, Claude Code, WorkBuddy/CodeBuddy, OpenCode, OMP, Pi or another supported host may start from the Agent: + +~~~ +enable OfferU Skill +→ "analyze this job for me" +→ Agent creates/resolves the canonical Job +→ governed OfferU operations prepare the role +→ open the same Job Workspace in OfferU +~~~ + +This must never become a second CLI-only product. Skill-first and App-first are two doors into the same Career Runtime, Job, Pipeline, Profile and audit trail. + ## Reasoning authority: external-first, not external-only OfferU prefers a **verified local Agent already owned by the user** — for example Codex, WorkBuddy/CodeBuddy, Claude Code, OpenCode, OMP, Pi or another supported host. @@ -104,6 +157,36 @@ References: - https://agentskills.io/ - https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills +## Job Workspace as the durable product object + +The unit of work is not a chat transcript. For every target opportunity, OfferU should materialize a persistent, reviewable Job Workspace: + +~~~ +Job Workspace + +Job Snapshot +Role Intelligence +Evidence Map +Application Materials +Interview +Timeline / Next Action +~~~ + +The Workspace progressively fills as work completes: + +~~~ +Job saved +→ Job Snapshot ready +→ Role Intelligence ready +→ Evidence Map ready +→ Resume proposals ready +→ Interview focus ready +~~~ + +Long-running Agent work should surface as product state: completed, needs review, blocked/failed, and next action. Closing an Agent chat must not make the work disappear. + +Accepted facts, user edits and approved versions are preserved. Re-analysis may update affected preparation, but it must not reset unrelated application state or silently overwrite accepted work. + ## Guided interaction The default mode is **Guided**. @@ -153,6 +236,18 @@ This is not background crawling and not an application event. BOSS CLI, scraper adapters or other source connectors may exist for research, testing or advanced user workflows, but they are not the default consumer acquisition path and must not weaken platform, privacy or anti-automation boundaries. +## Plan → Review → Execute + +Before a large preparation run, paid model work, or any external side effect, OfferU should show a compact plan at the level a normal user cares about: + +- what will be researched or generated; +- which verified evidence will be used; +- what is only a proposal; +- which external actions will **not** happen automatically; +- account / rate / estimated cost when materially relevant and known. + +This is not approval-everywhere. Work already inside an agreed safe scope may proceed; a material change of scope, cost, account or irreversible effect creates a new decision. + ## Application assistance OfferU may help prepare and fill an application, but the normal safety boundary remains: @@ -222,6 +317,32 @@ Do not reintroduce these as defaults: - a long command/mode menu as the beginner UX; - treating historical eval/audit numbers as current capability truth. +## Product story and launch order + +Product communication should start from the repeated user problem, not the internal architecture: + +1. every application starts from zero; +2. the JD, resume, research, tracker and interview learning are fragmented; +3. generic AI can optimize by inventing unless evidence and truth are separately governed; +4. OfferU turns a target Job + verified Career Profile into one reviewable Job Workspace. + +Recommended information order: + +~~~ +Concrete Job → Workspace outcome +→ complete Job-to-Workspace demo +→ Role × Evidence formula +→ why job-search AI breaks +→ Job Workspace +→ Quickstart +→ local Agent / Skill entry +→ Today / Pipeline / Profile compounding loop +→ evidence / approval model +→ architecture, security and release status +~~~ + +Operation Registry, Reasoning Authority and Career Runtime explain **why the experience can be trusted**; they are not the first reason a normal user cares. + ## Success test A new user should be able to understand OfferU without knowing what a Harness, MCP server, Operation Registry or provider is. @@ -229,11 +350,13 @@ A new user should be able to understand OfferU without knowing what a Harness, M The product is succeeding when the user experiences: ~~~ -OfferU knows my current career state -→ tells me what matters next +I give OfferU a Job +→ it shows what the role cares about +→ maps that against what I can actually prove +→ prepares work into one durable Job Workspace → uses the AI I already have -→ safely composes the Skills I already have -→ prepares work proactively +→ tells me what matters next → asks me only for decisions that genuinely require me +→ preserves accepted work → learns from confirmed outcomes ~~~ From 610577ad7c34016b73195d55cbb643ddfb5e0d97 Mon Sep 17 00:00:00 2001 From: avabbbb <89175608+avabbbb@users.noreply.github.com> Date: Wed, 23 Sep 2026 16:58:20 +0800 Subject: [PATCH 14/15] docs: preserve Skill-first Job Workspace design rationale --- .../skill-first-job-workspace-story.md | 424 ++++++++++++++++++ 1 file changed, 424 insertions(+) create mode 100644 docs/product/skill-first-job-workspace-story.md diff --git a/docs/product/skill-first-job-workspace-story.md b/docs/product/skill-first-job-workspace-story.md new file mode 100644 index 00000000..3321f436 --- /dev/null +++ b/docs/product/skill-first-job-workspace-story.md @@ -0,0 +1,424 @@ +# OfferU Skill-first Agent Entry, Job Workspace & Product Story + +Status: **DESIGN RATIONALE / DISTILLED REFERENCE** +Updated: 2026-09-23 + +This document records the external reference patterns and reasoning behind the Skill-first / Job Workspace direction. The accepted product rules have now been distilled into `GOAL.md`, `docs/product/current-product.md`, `docs/architecture/agent-system.md` and `docs/architecture/workbench-interaction.md`. Those authority documents override this rationale if wording diverges. + +The goal is to borrow useful patterns from successful Agent-first tools without copying their domain model: make the Agent entry extremely easy, materialize Agent work inside an editable workspace, and tell the product story from a repeated user pain rather than from architecture. + +## 1. Core distinction: Skill is the Agent entry; Workspace is the user product + +OfferU should not turn “install a Skill” into a requirement for ordinary users. + +The current Product North Star is correct: + +```text +normal user: +Install OfferU +→ auto-detect local AI +→ bootstrap Profile +→ save a real Job +→ OfferU prepares +→ user reviews / acts +``` + +The pattern worth borrowing is architectural: + +```text +Agent entry +OfferU Skill + ↓ +OfferU capabilities + ↓ +Operation Registry + ↓ +Career Runtime + ↓ +same Job / Profile / Application state + ↑ +OfferU Desktop Workspace +User entry +``` + +So: + +- **Skill = knowledge + capability entry for the Agent** +- **OfferU Desktop = primary product surface for the user** +- both converge on the same Career Truth; +- neither creates a hidden parallel project. + +For advanced users, a manual Skill install may remain a fast explicit path. For normal users, OfferU should auto-discover the supported Agent and project/register the Skill with minimal interaction. + +## 2. Two onboarding lanes, one product state + +### Lane A — normal user: App-first, zero-setup + +```text +Download / Install +→ Launch OfferU +→ Find supported local AI +→ OfferU prepares its Skill automatically where supported +→ Import resume / core career evidence +→ Save first Job +→ Job Workspace opens with preparation in progress +→ Today shows what needs attention next +``` + +The user should not need to know: + +- what a Skill is; +- MCP; +- Operation Registry; +- provider IDs; +- model endpoints; +- Python / Node / Git. + +### Lane B — power user: Skill-first + +When a user is already working inside Codex / Claude Code / WorkBuddy / OpenCode / OMP or another supported host: + +```text +Install / enable OfferU Skill +→ Agent checks OfferU availability +→ "Analyze this job for me" +→ Agent creates / resolves the canonical Job +→ preparation runs through governed OfferU operations +→ open the same Job Workspace in OfferU +``` + +Example desired interaction: + +```text +/offeru Use this role: + + +Compare it with my verified profile, +prepare the role intelligence and evidence gaps, +then propose the application materials. +``` + +The key rule is that this must not become a CLI-only second product. The result must appear in the same Job / Pipeline / Profile state used by the desktop UI. + +## 3. The Job Workspace is OfferU's equivalent of an editable production studio + +The user should not experience OfferU as “a chat that produced some text”. + +A Job should become a durable workspace containing the preparation state for one opportunity: + +```text +Job Workspace + +Job Snapshot +├─ source / company / role / location +├─ captured description +└─ current application state + +Role Intelligence +├─ what this role emphasizes +├─ market / cohort signals when supported +└─ distinctive requirements + +Evidence Map +├─ strong evidence +├─ weak evidence +└─ missing / unsupported claims + +Application Materials +├─ tailored resume +├─ proposal diffs +├─ application packet +└─ export / version history + +Interview +├─ focus areas +├─ practice +├─ transcript-backed debrief +└─ learning candidates + +Timeline +└─ canonical events / next action +``` + +This workspace is the durable artifact. Agent conversations are only one way to modify it. + +Recommended product framing: + +> Every job becomes an evidence-backed application workspace. + +## 4. Narrow entry story: one Job in, a prepared workspace out + +“AI Career OS” is a useful category description but is too broad to be the only first-screen story. + +Use a concrete input/output story first: + +```text +Give OfferU a job + ↓ +What does this role actually care about? + × +What can I actually prove? + ↓ +What should I prepare next? + ↓ +Evidence-backed application workspace +``` + +Candidate copy: + +> Give OfferU a job. It shows what the role really asks for, what you can prove, and prepares the application around that evidence. + +The broader Career OS story can follow: + +- the next Job reuses Profile evidence; +- interviews feed reviewed learning back into Profile; +- Timeline / Pipeline / Today stay synchronized; +- OfferU gets more useful without inventing new career facts. + +## 5. Product story should start from repeated user pain + +A strong launch narrative should be understandable without architecture terminology. + +Recommended story arc: + +### Pain 1 — every application starts from zero + +Job seekers repeatedly re-explain: + +- their experience; +- target role; +- strongest evidence; +- resume context; +- prior interview lessons. + +### Pain 2 — the work is fragmented + +```text +JD in browser +Resume in a file +Research in another tab +Application tracker in a spreadsheet +Interview notes in a chat +``` + +There is no persistent application object. + +### Pain 3 — generic AI optimizes by inventing + +A model can make a resume “match” a JD by overstating or fabricating evidence unless the product maintains a separate truth/evidence boundary. + +### Product insight + +The unit of work should not be “a chat”. + +It should be: + +```text +verified Career Profile + + +target Job + = +reviewable Job Workspace +``` + +The Agent reasons over it. OfferU controls evidence, side effects and persistent state. + +Only after this user story is clear should launch material explain: + +- Reasoning authority; +- Operation Registry; +- Career Runtime; +- proposals / approvals; +- local-first architecture. + +## 6. Plan → Review → Execute + +Before a large preparation run or any external side effect, OfferU should summarize what it intends to do. + +Example preparation plan: + +```text +Prepare this job + +Research +- analyze the saved JD +- compare against relevant roles if a live source is available + +Evidence +- map 8 requirements against verified Profile evidence +- flag unsupported claims instead of filling them in + +Materials +- propose a tailored resume version +- prepare an application packet +- prepare interview focus areas + +External actions +- no application will be submitted +- no recruiter message will be sent + +[Prepare] +``` + +For a provider-backed action, show account/cost/rate information when materially relevant and known. + +The important interaction is not “approval everywhere”. It is a compact contract before work that materially changes scope, cost or external side effects. + +## 7. Progressive results should appear in the Workspace, not only in chat + +Long-running preparation should progressively materialize: + +```text +Job saved +→ Job Snapshot ready +→ Role Intelligence ready +→ Evidence Map ready +→ Resume proposals ready +→ Interview focus ready +``` + +Today can summarize: + +- completed automatically; +- needs review; +- blocked / failed; +- next best action. + +The Job Workspace provides the detailed state. + +This lets a user close the Agent chat and still understand what OfferU did. + +## 8. “Keep what is already good” applies to career work too + +Creative tools reuse accepted generated assets. OfferU has a parallel principle: preserve accepted facts and edits. + +Examples: + +- a tailored resume version should not overwrite the Master Resume; +- a user manual edit makes an older AI proposal stale; +- accepted evidence remains stable unless explicitly superseded; +- re-analysis of a Job should update affected intelligence without resetting unrelated application state; +- interview learning should enter as a candidate, not silently rewrite Profile truth. + +User-facing principle: + +> Change the target job or evidence; OfferU updates the affected preparation without erasing work you already accepted. + +This is a product-level expression of existing truth/version boundaries. + +## 9. Hero demo contract + +Target launch demo (roughly 20–35 seconds): + +```text +1. Save / paste one real-looking Job +2. OfferU immediately creates the Job Workspace +3. Role Intelligence extracts what matters +4. Evidence Map shows: + Strong / Weak / Missing +5. Resume Workspace shows a proposal: + Before → After → Why → Evidence +6. User rejects one unsupported suggestion and accepts another +7. Application Packet becomes ready +8. Today shows the next action +``` + +Optional second beat: + +```text +Open the same Job from an external Agent +→ ask one question / request a revision +→ return to OfferU +→ the same Workspace has changed +``` + +That second beat proves the real differentiator: external Agent + OfferU workspace share one governed truth. + +## 10. README / launch information order + +Recommended order: + +```text +Concrete promise +→ one complete Job-to-Workspace demo +→ why normal job-search AI breaks +→ Role × Evidence formula +→ Job Workspace +→ Quickstart +→ local Agent / Skill entry +→ Today / Pipeline / Profile compounding loop +→ evidence + approval model +→ architecture / security / current status +``` + +Do not lead with Operation Registry or the authority model. Those are the explanation for why the experience is trustworthy, not the first reason a user cares. + +## 11. Product language + +Prefer user language: + +- Job Workspace +- what this role cares about +- what I can prove +- evidence gap +- proposal +- review +- next action +- application packet + +Keep implementation language mostly in technical sections: + +- Harness +- MCP +- Operation Registry +- Capability Gateway +- side-effect schema +- provider topology + +## 12. What to borrow, and what not to copy + +Borrow: + +- one-step Agent capability entry; +- Skill supplies domain knowledge while executable/product owns governed actions; +- reference/input-first onboarding; +- progressive preparation; +- explicit plan before meaningful paid / external work; +- editable workspace as the durable artifact; +- keep accepted work and update only what changes; +- outcome-first marketing story. + +Do not copy: + +- a domain-specific markup language OfferU does not need; +- growth claims not controlled by the product; +- terminal-first onboarding for normal users; +- Agent-owned truth; +- a Studio that duplicates the canonical OfferU Desktop state. + +## 13. External reference patterns + +Reviewed references: + +- Hypit Agent Quickstart: https://hypit.ai/quickstart/ +- Hypit Agent usage guide: https://hypit.ai/guide/skill/ +- Hypit Studio: https://hypit.ai/zh/quickstart/preview/ +- Hypit repository: https://github.com/hypit-ai/hypit + +The relevant pattern is: + +```text +Skill makes the Agent capable +→ Agent works on a durable project +→ user inspects/edits the result in a dedicated workspace +→ subsequent requests update the same project +``` + +For OfferU, adapt that to: + +```text +OfferU Skill makes the Agent career-aware +→ Agent works through governed OfferU capabilities +→ user inspects/edits the same Job Workspace +→ accepted evidence and outcomes compound into Profile +``` From b0a63607c90f12cc83617d2e23513e1e65c85364 Mon Sep 17 00:00:00 2001 From: avabbbb <89175608+avabbbb@users.noreply.github.com> Date: Wed, 23 Sep 2026 17:08:59 +0800 Subject: [PATCH 15/15] docs(agent): align repository instructions with Job Workspace model --- AGENTS.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 52 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b9c7b697..03d21dc3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,7 @@ # AGENTS.md -本文档用于约束本项目中的 AI / 自动化开发行为。开发时优先遵循本文件，其次遵循用户当前消息。 +本文档用于约束本项目中的 AI / 自动化开发行为。用户当前明确任务与更高优先级指令优先；在其范围内，本文件提供 OfferU 仓库级施工约束。遇到文档冲突时，不凭旧聊天或历史设计猜测，按下述“当前事实源”顺序裁决。 ## 角色设定 @@ -11,14 +11,46 @@ Playwright MCP 或Browser 来访问/截图/识别/探索网站的视觉和代码Context7 MCP 来查询某些技术文档(如果你需要使用到它们的话)动效丰富的部分，可以使用/web-shader-extractor进行分析 关于分析：这是个重大且复杂的工程，并且你上下文有限，你可以先进行整体分析，按模块进行顺序执行，每个模块任务的结果落盘分析文档到本地，这样即便上下文被压缩，后续也能够通过本地文档得到保证。分析思维你可以参考/duck +## 当前事实源与产品模型 + +当产品/架构文档冲突时，按以下顺序： + +```text +GOAL.md + ↓ +docs/product/current-product.md + ↓ +CONTEXT.md + ↓ +docs/adr/README.md + ↓ +ARCHITECTURE.md + current architecture topic docs + ↓ +live code / Registry / Host / generated Skill projections + ↓ +current Eval evidence +``` + +`docs/archive/**`、旧 dated report、旧 harness/DSH/Pi 方案只作历史证据，不得覆盖当前 authority。 + +当前必须保持的产品模型： + +- **App-first 是普通用户默认入口**：安装 OfferU → 自动发现可用本地 Agent → 支持时自动投影/注册 OfferU Skill → 建立 Profile → 保存 Job → 打开 canonical Job Workspace → Today 引导下一步。 +- **Skill-first 是高级用户入口**：用户可从 Codex / Claude Code / WorkBuddy / OpenCode / OMP / Pi 等支持宿主直接调用 OfferU Skill，但最终必须解析或创建同一个 canonical Job / Application 状态。 +- **Skill 是 Agent entry，不是第二套产品状态**；不得创建 Agent-only Job、隐藏 workspace、重复 Profile 或平行 Application state。 +- **Job / Opportunity 是持久 Job Workspace**：Job Snapshot、Role Intelligence、Evidence Map、Application Materials、Interview、Timeline / Next Action 都属于同一机会工作区。 +- Agent 长任务结果必须逐步物化为 OfferU 可见状态（completed / needs review / blocked / failed / next action），不得只留在聊天文本里。 +- **Career Runtime 是 Truth authority**，Operation Registry 是 execution/permission authority，当前 active Agent 是 reasoning authority；Today / Pipeline / UI 只投影同一份 Career Truth。 +- 对外产品叙事优先使用“一个 Job → 岗位要求 × 可验证证据 → evidence-backed Job Workspace”，Career OS 与三权分立是第二层解释，不应成为普通用户的理解前置条件。 + ## 基本原则 - 先读现有代码，再动手修改，优先沿用项目已有结构和写法。 - 写代码保持最少行数，能简单实现就不要引入复杂抽象。 - 标准格式、协议、解析、压缩、加密、日期等通用能力优先使用成熟稳定的库，不要手写底层实现，除非用户明确要求或项目已有实现必须沿用。 - 不要为了“兼容更多场景”写大量分支，只实现当前明确需要的功能。 -- 项目尚未上线，不需要兼容旧数据；表结构或字段调整时直接按新设计修改，不写旧字段兼容、数据迁移兜底或删除旧表的清理逻辑，除非用户明确要求。 -- 每次写完代码，不需要检查语法，不需要执行构建，用户会自己做。 +- OfferU 已进入 Public Release 准备路径，**不得再假设旧数据可以直接丢弃**。涉及 schema / persistence / version 的变更必须按 `GOAL.md` 的 migration、backup/restore、upgrade 规则处理；只有明确标记为开发 fixture/demo 的数据才能按任务要求 reset。 +- 修改代码后必须做与改动范围匹配的验证，并如实报告：后端至少运行相关 pytest；前端改动至少 typecheck + 相关 test，影响构建/路由/依赖时再跑 production build；跨层、release/security/migration 变更按 `GOAL.md` / CI 对应 gate 扩大验证。文档-only 改动不要求无意义地跑全量构建。**未运行或失败的检查必须明确写出，绝不把“看起来没问题”当 PASS。** - 不要改无关文件，不要顺手重构。 - 如果工作区已有用户改动，不要回滚，不要覆盖；只在必要范围内追加修改。 - **前端 dev 端口固定 7410，后端固定 8766**：两个端口均避开 AI/框架常用端口（3000/3300/5173/8000/8080/11434 等）与当前 winnat 动态排除段。winnat 排除段会漂移（曾见 2942-3041，后又出现 4229-4328，4321 因此 EACCES），改端口前必须先执行 `netsh interface ipv4 show excludedportrange protocol=tcp` 确认不在任何段内。改前端端口必须同步 `frontend/package.json` 的 `scripts.dev` / `scripts.start`、`frontend/vite.config.ts`（含 TAURI HMR 端口 7411）、`frontend/src-tauri/tauri.conf.json` 的 `devUrl`、`backend/app/config.py` 默认 CORS、`backend/app/routes/email.py`、`backend/app/routes/resume.py` 的 `FRONTEND_BASE_URL`、`.env.example` 与 `backend/.env`；`frontendDist` 必须继续指向静态目录 `../dist`，不能改成 localhost URL。 @@ -53,17 +85,17 @@ Issues 和 PRD 使用当前 Git remote 对应的 GitHub Issues；外部 Pull Req ## 实现 Agent 准则 -- 实现阶段以 `CONTEXT.md`、相关 ADR 和已批准实施路线为事实源；评审意见、聊天总结和旧设计与 ADR 冲突时，以最新 accepted ADR 为准。 +- 实现阶段先按“当前事实源”读取 `GOAL.md`、`docs/product/current-product.md`，再按任务读取 `CONTEXT.md`、相关 ADR / architecture docs 与 live code。评审意见、聊天总结、历史报告与当前 authority 冲突时，以当前 authority + live code/evidence 为准。 - 一次只实现一个边界明确、可独立验收的纵向切片。不要同时铺开多个模块，也不要把数据库、API、前端分别做成长期未闭环的横向工程。 - 实现 Agent 负责落地，不重新进行产品问卷或自行新增架构。只有遇到 ADR 冲突、必须扩大文件范围、会改变领域模型或需要新外部权限时，才停止并提出一个阻塞问题。 - 开工前先读取与任务直接相关的代码和文档，用不超过 10 行复述目标、修改范围和验收映射；没有真实阻塞时立即实施。 -- 用户或主 Agent 必须在任务中给出允许修改的文件范围。未经确认不得越界，不得修改无关文件、顺手重构、清理历史代码或创建新 ADR/PRD/Issue。 -- GUI、CLI、TUI、斜杠 Skill 和本地 Coding Agent 都必须通过同一 Operation Registry；不得复制业务逻辑、直接写数据库、执行隐藏 shell 或绕过 dry-run、确认、审计和数据授权。 +- 修改范围由当前任务目标决定，不要求用户预先枚举每个文件。Agent 可修改完成该纵向切片**直接必要**的相邻文件与测试，但不得借机做无关重构、历史清理或创建无关 ADR/PRD/Issue；若必须扩大到新的领域边界或外部权限，再提出阻塞问题。 +- GUI、CLI、TUI、斜杠 Skill 和本地 Coding Agent 都必须通过同一 Operation Registry；不得复制业务逻辑、直接写数据库、执行隐藏 shell 或绕过 dry-run、确认、审计和数据授权。**Skill-first 与 App-first 的结果必须落到同一 canonical Job Workspace / Profile / Pipeline。** - 本地 Coding Agent 只承担可审计重任务。CLI 参数和能力必须通过 capability probe 判断，不能把某个 Codex、Claude 或其他 CLI 版本的 argv 永久写死。 - Agent 推断、面试反馈、简历建议和投递信号不能直接成为职业事实；必须遵循学习观察、事实门、候选进展和使用者确认规则。 - 当前产品仅为本地单人版；不要引入 SaaS、多租户、`workspace_id`、组织、计费、登录或为未来需求预埋兼容层。 - 保持最小实现，优先复用成熟库和现有结构。不得用固定假分、伪造 JSON、静默降级或“返回成功但实际未执行”掩盖失败。 -- 完成后按“修改文件、验收映射、未执行命令、剩余风险”报告。遵循本文件既有规则，不运行构建、语法检查或测试，只列出建议由用户执行的命令。 +- 完成后按“修改文件、验收映射、已执行检查及结果、未执行检查、剩余风险”报告。能在当前环境执行的相关自动检查应由 Agent 自己执行；只有环境/凭据/平台限制导致无法运行时，才把命令留给用户，并说明原因。 ## 反复提醒沉淀 @@ -76,3 +108,16 @@ Issues 和 PRD 使用当前 Git remote 对应的 GitHub Issues；外部 Pull Req - **配置文件路径统一走 `llm_config_store.config_file_path()`**：该函数每次调用 `runtime_config_file()` 运行期现取（跟随 `OFFERU_DATA_DIR`），`app/routes/config.py` 与 `app/llm_config_store.py` 不再有模块级 `_CONFIG_FILE` 副本。测试隔离用 `patch("app.llm_config_store.runtime_config_file", return_value=...)` 或 `OFFERU_DATA_DIR` 环境变量，一处生效两处覆盖；不要重新引入模块级路径常量。 - **清理钥匙串时只能删自己写过的 ref**：不要按 `legacy_ref(...)` / `config_ref(...)` 这类固定 ref 批量删除。用户真实 LLM 凭据就存放在 `llm/legacy/*` 与 `llm/config/*` 下，误删会直接让用户丢失 API Key。测试用 fake vault（`unittest.mock.patch` credential_store 的同步函数），不要碰真实钥匙串。 - **API Key 只进钥匙串**：`config.json` 只允许出现 `credential_ref` 和 `env:VAR_NAME` 引用。写入钥匙串失败必须 fail-closed（`VaultUnavailableError`），绝不回退为明文落盘；读取失败不阻断启动，但必须经 `/api/config` 的 `vault_status` 暴露给用户。新增任何会写 config.json 的入口，都要经过 `llm_secret_vault.dehydrate()`。 + + +## 安全回归红线（2026-09-23 加固基线） + +这部分来自最新 critical/high/medium/low 修复后的稳定约束。后续改动不得为了“方便”退回旧行为： + +- 新增或修改远程 URL / model endpoint / fetch 路径时，必须复用当前 SSRF / scheme / host 校验与 SSL 验证边界；不得关闭证书验证，不得自行放宽到 loopback/private/metadata 等高风险目标。 +- 上传文件、PDF/HTML 渲染、导出与本地文件访问必须保持 filename/path canonicalization 与边界校验，禁止重新引入路径穿越。 +- 富文本/模板输出继续使用当前安全 sanitizer / sandbox 机制；不得用正则清 HTML 或把用户内容拼入可执行 JS/template。 +- 发往外部模型的 cover letter、interview prep 等包含个人信息的内容必须保持 desensitize → model → restore 边界；不得把 PII 明文上送作为“临时简化”。 +- API/Bridge/Operation 入口不得移除现有鉴权与权限边界；本地部署也不等于所有 endpoint 可以匿名写。 +- config、Agent run、resume/application workspace 等并发写路径必须保留当前锁、事务、idempotency / version 检查；不要用“单用户所以不会并发”作为删除并发保护的理由。 +- Secret 永远不进 repo、日志、前端持久状态或明文 config；继续遵循本文件的 keyring / credential_ref 规则。