Beacon — 产品与技术实施总方案¶

状态 产品范围与设计基线（2026-10-11 用户定版收编）

上游任务书 · 定位

关系与 RFC-001 并行的产品基线；冲突处以本文档「差异审计」（mvp-issues 批3-补26）与用户拍板为准

术语对照 已拍板（2026-10-11 批3-补27①）：RFC-001 编号为产品唯一口径（L0=钉选悬浮组件 / L1=胶囊 / L2=Quick Panel / L3=详情）；本文档 §3 的 L0/L1/L2 仅为原文行文，阅读映射：本文 L0=胶囊→RFC L1，本文 L1=面板→RFC L2，本文 L2=详情→RFC L3

核心原则：Signal + Action，而不是 Dashboard + Automation。 版本：1.0 · 目标平台：Windows 10 / Windows 11 · 技术栈：C#、WinUI 3、.NET 10 · 仓库：https://github.com/cuihairu/beacon

1. 项目目标¶

1.1 产品定位¶

Beacon 是一个常驻 Windows 桌面的轻量开发者状态与操作中心。

它聚合开发者最需要关注的状态，在异常发生时提供提醒，并允许用户通过少量操作查看详情或执行简单操作。

Beacon 不替代 GitHub、CI/CD 平台或公司的打包工具，也不建设一套新的开发管理平台。

核心价值：

不必反复切换窗口，就能知道重要任务的状态。
发生失败时，能够及时发现问题。
从通知到问题详情的路径尽可能短。
日常运行时占用空间小，不干扰正常开发。
不需要额外服务器、用户系统或云端服务。

1.2 设计原则¶

Small by default：默认界面尽可能小。
Signal over noise：只突出重要状态，不制造通知噪声。
Local first：配置、状态缓存和必要的历史数据保存在本地。
Provider-based：数据源通过统一接口接入。
Native Windows experience：充分利用 Windows 原生窗口、托盘和通知能力。
No reinvention：复杂操作直接跳转原始平台。
Incremental delivery：先保证真实数据和桌面体验可靠，再扩展数据源。

2. 功能范围¶

2.1 第一优先级：开发任务与 GitHub¶

开发任务状态

首要目标是监控公司现有打包工具。

需要支持的能力由实际打包工具提供的数据决定：

当前是否运行。
任务成功、失败、排队或取消。
任务开始时间和耗时。
最近一次成功或失败。
可获取的错误摘要。
打开原始任务详情。
在工具支持且权限允许时重试任务。

Beacon 不负责实现打包逻辑，不负责构建编排，不重新实现打包工具的日志系统。

具体打包工具的 API、认证方式、状态字段和操作能力，需要在接入时根据实际接口确认。

GitHub 状态

查看指定仓库的 GitHub Actions 最近运行状态。
查看关注的 Pull Request。
显示失败、运行中、成功等状态。
重要状态变化时通知。
打开 PR、Workflow Run 和原始日志。
在权限允许时重跑失败的 Workflow。

GitHub Provider 继续使用现有实现，避免重复建设。

2.2 可选功能：AI 使用额度¶

AI 使用额度属于可选 Provider，不是 MVP 的阻塞条件。

仅在存在可靠数据来源时提供：

当前可查询的使用额度。
重置时间。
数据更新时间。
接近阈值时的通知。

如果无法获取官方或可靠的额度数据，明确显示未知或暂不支持。

不建设 AI 模型路由、API 代理、账号管理、模型调用面板或额度购买功能。

2.3 明确不做¶

以下内容不属于 Beacon 的产品目标：

自定义脚本和命令执行平台。
通用任务调度或 Workflow Engine。
Docker、服务器和远程机器管理。
AI Agent 管理。
多设备控制中心或云同步。
第三方插件市场。
复杂图表和分析报表。
GitHub 的完整替代客户端。
通用监控平台。
账号注册、团队协作和独立后端。
多个独立桌面小组件组成的复杂桌面仪表盘。

以上边界是长期产品约束，而不只是暂缓实现的事项。

3. 整体交互设计¶

Beacon 采用渐进式信息展示。

用户平时只看到小型状态入口；只有主动查看或出现重要异常时，才展开更多内容。

3.1 L0：桌面状态胶囊¶

这是 Beacon 最重要的视觉入口。

常驻屏幕右下角附近，用户可以移动位置，并在设置中调整显示行为。

建议展示：

Beacon 状态指示。
当前是否存在需要关注的问题。
必要时显示异常数量。
点击打开悬浮面板。
右键打开托盘菜单或常用设置。

默认状态不显示大量文字、图表或任务列表。

视觉状态：

状态	表现
正常	低干扰的中性色或成功状态
运行中	轻量运行指示
需要注意	黄色或其他警示状态
存在失败	明确的错误状态
数据源离线	灰色状态，同时保留最后更新时间

颜色只是一种辅助信息，不能仅依赖颜色表达状态。图标、文字和可访问性标签也应传达含义。

关键要求：胶囊不能抢夺键盘焦点。

它不应影响鼠标点击其他应用、全屏游戏、IDE 输入或正常窗口操作。

3.2 L1：悬浮 Quick Panel¶

这是 Beacon 的核心界面。

点击状态胶囊或按全局快捷键 Ctrl+Alt+B 后，显示一个紧凑的悬浮面板。

推荐布局：

┌─────────────────────────────────────┐
│ Beacon                         ⚙  × │
│                                     │
│ 需要关注                         2  │
│ ─────────────────────────────────── │
│ ● Client Build                     │
│   构建失败 · 3 分钟前                │
│   [查看详情] [重试]                  │
│                                     │
│ ◐ Backend Build                    │
│   构建中 · 已运行 4 分钟             │
│                                     │
│ ● Pull Requests                    │
│   1 个 PR 等待处理                   │
│                                     │
│ ─────────────────────────────────── │
│ 最近状态更新 · 20 秒前               │
└─────────────────────────────────────┘

以上为示意布局，不代表真实数据。

面板只需要三个信息区域：

需要关注：失败、超时或需要人工处理的事项。
正在运行：当前重要任务。
最近状态：必要的成功、状态变化或待处理事项。

不需要把所有 Widget、仓库和统计数据都放在首页。

交互规则¶

点击事件打开详情。
有明确且安全的操作时才显示操作按钮。
失败任务可以提供查看详情、重试等操作。
普通成功任务优先提供跳转，而不是增加一组管理按钮。
点击外部或按 ESC 可以关闭面板。
点击面板内部时不应因为失焦事件导致面板立即关闭。
操作执行期间保留必要的进度反馈。
操作完成后更新状态，不假设操作已经成功。
刷新失败时展示最后更新时间，而不是清空原有状态。

建议初始尺寸约为 360–420 DIP 宽、420–560 DIP 高。实际高度根据内容动态调整，并设置最大高度和滚动区域。

已拍板落地（2026-10-11 批3-补27④）：三分区以 NEEDS ATTENTION / RUNNING / RECENT EVENTS 实现（RECENT EVENTS 即「最近状态」，OVERVIEW 计数与通知中心保留），初始宽 380 DIP（带内取中）；「需要关注」判定 = Warning 及以上 / 数据过期 / 连接断（Core QuickPanelSections，10 例单测）。

面板应支持 Windows 缩放、多显示器、任务栏位置变化和屏幕边缘约束。

3.3 L2：详情¶

不需要为每个数据源开发完整的详情管理系统。

详情只显示当前事项必要的信息：

名称和来源。
当前状态。
开始时间与耗时。
分支、仓库或任务标识。
可获取的错误摘要。
最近更新时间。
可执行的少量操作。
打开原始详情的链接。

如果原始平台已经拥有完整日志、诊断信息或操作界面，应直接跳转到原始平台。

L2 的职责是解释状态，不是复制原平台。

3.4 系统托盘¶

托盘用于生命周期管理和全局设置。

建议菜单：

打开 Beacon。
刷新状态。
连接与数据源设置。
通知设置。
关于 Beacon。
退出。

不在托盘菜单中堆放所有任务操作。

3.5 快捷键¶

默认全局快捷键为 Ctrl+Alt+B。

要求：

可以在设置中关闭或更改。
注册失败时明确提示，不影响应用启动。
快捷键冲突不能导致应用崩溃。
重复按下时应切换面板的显示状态，而不是创建多个窗口。

3.6 默认形态（2026-10-11 拍板修订）¶

不默认把桌面铺成「多独立窗口小仪表盘」：默认形态是单宿主面板（每显示器一个透明置顶宿主窗，单窗多 tile， RFC §6.2.4），桌面常驻物至多叠加：状态胶囊（默认关）、快捷面板（按呼出）、详情窗（按需）。

用户令优先于本方案原稿（2026-10-11 用户令「数量悬浮窗默认开状态胶囊默认关」）：数量/额度类钉选组件默认以独立悬浮框上桌（numericFloatingEnabled=true，设置可关=桌面零残留）；胶囊默认关（showCapsule=false）。独立悬浮框形态（每组件一窗）是用户显式选择（设置「悬浮形态」二选一，重启生效），不随安装默认整体铺开—— 原稿「只留胶囊+面板+详情」据此修订，窗口管理复杂度顾虑由「panel 默认 + floating 须显式切换 + 准入策略（信息密度门槛）」化解。

原因是它会增加窗口管理、布局配置、拖动、显示器适配和状态同步的复杂度，也容易让桌面变成一块小型仪表盘。

4. 技术架构¶

4.1 总体架构¶

采用单进程、模块化的 Windows 桌面应用。

Beacon.App
├── Tray / Hotkey
├── Status Capsule
├── Quick Panel
├── Detail View
└── Settings
        │
        ▼
Beacon.Core
├── State Aggregator
├── Refresh Scheduler
├── Event Lifecycle
├── Notification Policy
├── Action Dispatcher
└── Domain Models
        │
        ├── Beacon.Connections
        │   ├── GitHub
        │   └── Company Build
        │
        ├── Beacon.Actions
        │   ├── Open URL
        │   └── Supported Provider Actions
        │
        └── Beacon.Storage
            ├── Local Configuration
            ├── State Cache
            └── Secure Credential References

AI Usage Provider 可以在未来以同样的方式接入，但不影响第一版发布。

4.2 技术选型¶

项目	选择
编程语言	C#
桌面 UI	WinUI 3
运行时	.NET 10
架构	MVVM + 模块化 Core
配置	JSON
凭据	Windows DPAPI 或 Windows Credential Manager
测试	现有测试框架与项目规范
CI	GitHub Actions，Windows Runner
发布	安装包与便携包
后端	无
数据库	第一版不需要数据库

如果现有项目已经采用其他成熟的内部抽象，应优先复用，而不是为了符合文档名称而大规模重构。

4.3 核心架构原则¶

UI 不直接请求远端数据源。

所有状态刷新统一经过 Core 调度和 Provider 接口。

Provider 只负责数据适配。

Provider 将外部系统的数据转换为统一领域模型，不负责窗口展示、托盘颜色和通知弹窗。

Action Dispatcher 只执行有限的原子操作。

它不是脚本执行器或任务编排系统。

Storage 只保存必要信息。

配置、凭据引用、必要的状态缓存和轻量历史足够支撑产品。

不增加后台服务进程。

除非后续有明确、不可替代的技术需求，否则保持单进程架构。

5. 核心领域模型¶

5.1 Severity¶

全产品使用统一严重程度：

Info
Success
Warning
Error
Critical

离线和刷新失败应通过连接健康状态与数据新鲜度表达，不应简单地把所有网络异常都映射成 Critical。

5.2 LifecycleState¶

任务生命周期：

Queued
Running
Success
Failed
Cancelled
Skipped
Unknown

外部 Provider 必须将源系统的状态映射到统一枚举。

5.3 WidgetState¶

每个状态项至少包含：

WidgetState
├── Id
├── ProviderId
├── Title
├── Severity
├── LifecycleState
├── Summary
├── DetailUrl
├── UpdatedAt
├── LastSuccessfulFetchAt
├── IsStale
└── ConnectionHealth

详细错误信息和外部响应不应无限制地保存在状态对象中。

5.4 Activity¶

Activity 用于表达值得关注的状态变化，而不是每次轮询都生成一条事件。

Activity
├── Id
├── SourceId
├── SubjectId
├── Kind
├── Severity
├── Summary
├── OccurredAt
├── FirstSeenAt
├── LastSeenAt
├── AcknowledgedAt
└── Fingerprint

事件去重应基于稳定标识或指纹，而不是只比较显示文本。

第一版只需要支持：

新事件。
已查看或已确认。
已解决。
同一事件更新时合并。

不建设复杂的事件编排、工作流或事件分析引擎。

落地状态（2026-10-11 审计补记）：Activity/Fingerprint 未作为一等类型实现（src 全域零命中）。当前以三段现有机制承载其语义：NotificationRecord（notifications.json 落盘，含 read 已读态，滚动保留 200 条） + NotificationEngine 去重（阈值跨越语义 = 同一段 Warning 只提醒一次，或时间冷却） + RecentEvent（L2 面板会话内事件流，无持久化）。指纹级去重未实现，事件合并未实现——待真机验收后排期。

5.5 Provider 接口¶

继续沿用现有 Provider 抽象，概念上提供：

public interface IWidgetProvider
{
    string Id { get; }

    Task<WidgetState> GetStateAsync(
        WidgetConfig config,
        CancellationToken cancellationToken);
}

实际接口以仓库现有实现为准，不要因为示例而重复定义。

每个 Provider 还应明确：

支持哪些状态。
支持哪些操作。
推荐刷新间隔。
认证方式。
失败后的重试策略。
数据是否可能过期。

Provider 可以是内置模块，不需要动态程序集加载或插件发现机制。

6. 状态刷新与通知¶

6.1 刷新机制¶

采用缓存优先、后台刷新。

打开面板时：

立即显示最后一次有效状态。
在后台执行必要的刷新。
获取结果后增量更新 UI。
如果刷新失败，保留旧状态并标记过期。

不要让打开面板的操作等待所有网络请求完成。

6.2 刷新频率¶

刷新间隔按 Provider 和接口限额调整，不设置一个全局固定的高频轮询。

初始建议：

PR：60–120 秒。
CI 状态：20–60 秒。
公司打包工具：依据实际接口能力，初始可采用 15–30 秒。
AI 额度：依据来源的更新频率，通常不需要高频查询。

这些是初始策略，不是固定承诺。

必须实现：

请求取消。
同一数据源避免重复并发刷新。
失败退避。
请求超时。
GitHub ETag / 条件请求。
GitHub Rate Limit 感知。
应用恢复后刷新。
网络不可用时保留缓存。

6.3 通知策略¶

通知只用于值得打断用户的事件：

构建失败。
重要任务从运行中变为失败。
关键状态发生变化。
用户明确配置的阈值触发。

默认不通知：

每次刷新。
每次轮询。
普通成功状态。
没有实质变化的重复失败。
可通过胶囊安静展示的常规运行状态。

同一事件应去重。用户已确认的事件在没有实质状态变化时不应反复提醒。

通知内容应包含来源、事件摘要和打开详情的入口。

通知点击后必须定位到对应事件，不能只打开一个没有上下文的首页。

7. 操作执行与安全¶

7.1 允许的操作¶

第一版只提供必要操作：

打开原始详情。
刷新状态。
重试受支持的任务。
执行来源平台提供的简单、明确操作。

不提供任意 shell、PowerShell、批处理脚本执行功能。

例外（2026-10-11 拍板③）：已落地的 local.command Action 保留——默认执行前确认弹窗、命令在设置中明文可见、带超时与输出捕获（RFC §13）。它不是脚本执行平台（无编排/无批量/无编辑器），是 mission 原案 [Build][Test][Deploy] 快捷动作的承载。不再扩展脚本能力；新操作类型一律按「来源平台提供的简单、明确操作」原则评审。

7.2 操作结果¶

每个 Action 应返回明确结果：

Succeeded
Failed
Cancelled
TimedOut
Unsupported

执行请求成功提交，不等于底层任务执行成功。

例如 GitHub 接受重跑请求后，Beacon 应显示已提交重跑请求，并继续刷新实际运行状态。

7.3 凭据安全¶

普通 JSON 只保存凭据引用。
Token 使用 DPAPI 或 Windows Credential Manager 保护。
日志不得包含完整 Token、Authorization Header 或敏感响应。
设置界面不得在普通文本框中回显已保存的完整凭据。
不需要管理员权限运行。
不需要开放本地监听端口。
不建立远程控制通道。

GitHub Token 应遵循最小权限原则。需要写操作时才申请相应写权限，纯状态读取优先使用只读权限。

7.4 失败隔离¶

一个 Provider 失败，不应影响其他 Provider 或桌面 UI。

网络错误、认证失败、权限不足、限额耗尽和服务端错误应有不同的用户提示。

错误日志应支持定位问题，但不记录秘密信息。

8. 本地配置与数据存储¶

沿用现有配置体系，避免新增不必要的存储技术。

建议将用户数据保存在 %AppData%\Beacon\ 下。

逻辑上包括：

config.json：全局设置。
connections.json：连接信息和凭据引用。
widgets.json：需要展示的状态项。
cache.json：必要的轻量状态缓存。
history.json：有限的事件历史。

如果当前仓库已经存在不同的配置文件划分，不必强行改名。重点是保持职责清晰，并提供向后兼容的配置迁移。

落地状态（2026-10-11 审计补记）：实际文件划分与上表逻辑名不同，按「不必强行改名」执行—— %AppData%\Beacon\ 下 config.json（全局设置）、connections.json、widgets.json、pins.json、actions.json、 notifications.json（本方案无对应逻辑名；已读态落盘，滚动 200 条）、cache\{connId}\states.json（缓存按连接分目录，非 cache.json）、 secrets.bin（DPAPI 密钥，唯一密钥落点）。损坏原件留档 *.corrupt 并记录 LoadErrors，不阻断启动。

要求：

文件写入采用安全的原子替换策略。
配置损坏时能给出明确提示。
首次启动自动创建默认配置。
不存在的可选配置使用默认值。
无效配置不能导致整个应用无法启动。
事件历史有上限，并定期清理旧数据。

第一版不需要 SQLite。只有当真实使用证明 JSON 在查询、并发写入或历史容量方面无法满足需求时，才重新评估。

9. Windows 桌面体验与生命周期¶

必须覆盖以下场景：

单实例启动。
托盘图标创建和销毁。
开机自启。
用户主动退出。
悬浮窗口显示与隐藏。
ESC 关闭面板。
全局热键注册与冲突。
高 DPI 与多显示器。
显示器断开或分辨率变化。
Explorer 重启后恢复托盘图标。
锁屏、解锁与系统睡眠恢复。
网络断开与恢复。
应用异常退出后的诊断。

悬浮窗口应尽可能使用原生 Windows 能力实现，不引入 WebView 或其他 UI 框架来重复实现桌面外壳。

需要特别验证窗口不会无意抢焦点、无法关闭或跑到屏幕外。

开机自启应允许用户关闭。安装和卸载过程不应要求管理员权限，除非 Windows 系统本身或特定安装方式另有要求。

10. 设置界面¶

设置只保留四类内容：

通用¶

开机自启。
全局快捷键。
胶囊显示与位置。
面板行为。
退出行为。

连接¶

GitHub 连接。
公司打包工具连接。
凭据管理。
连接测试。
数据源启用或禁用。

通知¶

是否启用通知。
失败通知。
阈值设置。
静默或合并重复通知。

关于¶

版本信息。
日志位置。
开源许可证。
检查更新或打开项目主页。

不要设置独立的插件管理器、命令管理器或复杂规则编辑器。

落地状态（2026-10-11 审计补记；2026-10-14 增量复核更新计数）：通用（胶囊/面板/外观/热键/自启/检查频率）、连接（GitHub + HTTP 通用 + 12 家 AI 额度（含 2026-10-13 商汤 SenseNova Token Plan 积分池）+ 凭据 + 连接测试 + 模块启停，共 17 类，含 Jenkins/本机/Herald）、通知（规则/阈值/冷却去重）均已落地；公司打包工具槽位由 Jenkins Provider 落位（开源标准 JSON API，任意实例可配）。「关于」现有版本行（InformationalVersion）与日志位置提示；开源许可证、检查更新/项目主页入口（2026-10-12 批3-补46/47 已补齐，见下）。（2026-10-12 批3-补46 已补齐：「关于」增 Apache-2.0 许可证行 + 项目主页/检查更新（nightly 下载页）入口，系统浏览器打开、失败落运行日志。2026-10-12 批3-补47 再补真比较：三行 = 当前版本/远程最新版本/检查结果（GitHub releases/latest 与本地 InformationalVersion 比，Core 纯函数 SemVer 比较；启动 20s 自检一次并缓存，手动按钮强刷；断网/超时/非 200 一律「无法检查更新 + 时间」不弹异常框；有新版本时给「打开下载页」按钮。版本口径：csproj Version 为唯一权威基准，daily-build 发布时注入日期版本 + SHA 滚 nightly tag（--latest=false）；仓库无正式发版 workflow，正式发版 tag 注入待用户首次令发版时建。）「退出行为」在托盘 Exit（唯一退出路径），不在设置页。

11. 测试策略¶

11.1 单元测试¶

覆盖：

状态映射。
严重程度聚合。
事件指纹和去重。
状态过期。
通知规则。
刷新调度。
请求取消。
Action 执行结果。
配置读写和迁移。
凭据引用。
GitHub 限额处理。

11.2 集成测试¶

覆盖：

GitHub API 响应映射。
Token 无效和权限不足。
API 限额耗尽。
网络超时。
Provider 部分失败。
旧缓存显示。
重试操作的完整生命周期。
数据源恢复后状态重新同步。

公司打包工具应提供可重复使用的测试样本或模拟响应，避免每次测试都依赖真实公司环境。

11.3 Windows 真机测试¶

必须在 Windows 机器上验证：

安装包安装、启动、卸载。
便携包启动。
托盘和悬浮面板。
快捷键。
多显示器与缩放。
通知点击。
开机自启。
Explorer 重启。
系统睡眠与唤醒。
应用关闭后不残留意外后台进程。

11.4 干净环境测试¶

在没有预先安装开发环境的 Windows 虚拟机中测试发布包。

验证自包含运行时、缺失依赖提示、配置初始化、凭据存储、日志生成和升级行为。

CI 构建通过不等于产品验收通过。

12. 性能与质量目标¶

以下作为首版工程目标，而不是未经测量的性能承诺。

启动后尽快出现托盘和胶囊，不等待所有网络请求。
打开 Quick Panel 时优先显示缓存，避免明显的空白等待。
空闲状态下尽量降低 CPU 占用和网络请求。
不持续高频刷新所有数据源。
一个连接超时不能冻结 UI。
长时间运行不应不断积累事件、窗口或后台任务。
关闭面板不应导致整个应用退出。
退出应用后不应残留意外进程。
任何凭据都不得进入日志或普通配置文件。

性能验收应通过实际测量记录，而不是仅根据代码推测。

13. 实施计划¶

当前仓库已经完成部分核心模块，因此采用增量实施，不从零搭建。

M0：范围冻结与现状核对¶

以本方案更新 docs/mission.md。
更新 docs/rfc/RFC-001-technical-design.md。
对照现有实现检查状态胶囊、Quick Panel、Provider 和 Action 的真实行为。
删除与本方案冲突的未来规划。
记录尚未完成的真实环境验证。

验收：产品范围与代码实施计划一致。

M1：桌面 Shell¶

复用现有托盘、单实例、快捷键、开机自启和窗口生命周期实现。

验收：桌面入口稳定，不抢焦点，不产生重复窗口。

M2：Core 状态机制¶

复用现有刷新调度、状态聚合、缓存、事件总线和通知规则。

验收：缓存优先、增量更新、状态过期和错误隔离正常。

M3：GitHub¶

复用现有 PR、Actions Provider 和限额感知实现。

验收：真实数据可读取、状态映射准确、失败通知去重、跳转和重试行为正确。

M4：Quick Panel¶

重点完成悬浮面板的视觉和交互：

需要关注。
正在运行。
最近状态。
必要的上下文操作。
错误和离线提示。
面板关闭与焦点行为。

验收：面板小巧、信息清晰，用户不必打开浏览器就能理解发生了什么。

M5：发布与验收¶

Windows 真机走查。
干净虚拟机安装验证。
安装包与便携包验证。
日志和故障排查验证。
性能与长时间运行测试。
更新 README 与安装说明。

验收：不依赖开发机环境即可正常安装、启动和使用。

后续可选：公司打包工具 Provider¶

落地状态（2026-10-11 批3-补31）：该槽位由 Jenkins Provider（jenkins.build + jenkins 连接）以开源标准 JSON API 落位——任意实例可配，凭据匿名或 user:apiToken，Folder 路径转义，一次请求按 color 判级。下文「取得真实 API 后再接入」口径仍适用于厂商私有打包工具（非开源标准 API 需按其实际接口评估，不建设常驻 Agent 或远程控制系统）。

（本项已关闭：Jenkins Provider 已按开源标准 JSON API 落位——见上「落地状态」注；厂商私有打包工具按其实际接口评估，不建设常驻 Agent 或远程控制系统。）

后续可选：AI Usage Provider（2026-10-11 批3-补41 评估收口，已关闭）¶

仅在数据来源可靠、维护成本合理时实现；不能为了支持更多服务商而影响核心桌面体验和维护成本。

落地状态（2026-10-11 批3-补41 评估收口）：条件已满足且早已超出——本项关闭。本项写入时是条件门控占位；此后 positioning P0 #5 将 AI Usage 提为首发 P0，2026-10-08 起逐家落地 13 种组件类型/11 家 （bigmodel/ark/claude/kimi/deepseek/mimo/codex/copilot/opencode/qwen/moonshot + http.status/quota 通用面）。数据源可靠性三档：① 官方稳定 API 六家（deepseek /v1/users/me/balance、moonshot balance、bigmodel 监控 quota/limit、ark 管控面 OpenAPI V4 签名、copilot 官方扩展同款配额端点、opencode Console Budgets——key 长效无会话态）； ② 本机零网络两家（claude/codex 读本机会话 jsonl，绝对可靠零维护，codex 标注非官方口径）； ③ 会话 cookie 两家（kimi/mimo 控制台口，端点稳定但会话过期是常态——401 明示+重录指引在卡面）+ qwen 官方额度口未开放（如实降级链：自定义端点→配额探针→模型目录，不造数）。维护成本实测：两次形状漂移（kimi F-50、mimo F-51）均被「单文件多类 + 防御解析 fail-loud + 如实降级」隔离、当日收口；刷新失败不清缓存（§14.5），单家漂移不伤核心桌面体验。残余维护面 = 两家 cookie 偶发重录（用户侧动作，有指引）。

14. MVP 验收标准¶

Beacon 第一版只有满足以下条件才算完成：

Windows 登录后能够按用户设置启动。
托盘和状态胶囊可以稳定运行。
全局快捷键能正常打开悬浮面板。
面板能够展示真实 GitHub 状态。
Provider 刷新失败时不会清空有效缓存。
重要失败事件能够触发通知，重复事件不会持续打扰用户。
用户能够查看详情或跳转原始平台。
支持的操作有明确的执行结果反馈。
凭据得到安全保存，日志中不存在明文秘密。
安装包和便携包能够在干净 Windows 环境运行。
没有意外后台进程、明显资源泄漏或窗口生命周期问题。
核心体验不依赖独立后端服务。

公司打包工具的集成可以作为紧随 MVP 的重要里程碑，但必须基于真实接口进行验收，不能用模拟数据代替真实集成结果。

15. 给 Code Agent 的实施约束¶

开始修改代码前，必须先阅读：

README.md
docs/mission.md
docs/rfc/RFC-001-technical-design.md
docs/solution-structure.md
docs/mvp-issues.md

随后检查当前源码和测试，列出现有实现、缺失功能、重复抽象和与本方案冲突的部分。

实施要求：

复用现有成熟实现，不重写已经完成的模块。
不因为本方案中的示例代码而重复定义已有接口。
不引入数据库、后端服务、脚本执行器、复杂插件系统或工作流引擎。
不新增未经验证的外部依赖。
不用模拟数据宣称真实集成已完成。
每次修改都必须配套测试或说明无法自动化验证的原因。
更新文档中的功能状态，不能把待真机验证的功能标记为完全验收。
优先解决窗口交互、状态准确性、资源占用和错误处理。
如果现有架构与本方案冲突，先提交差异分析和最小改造建议，不直接进行大规模重构。
所有新增功能都必须符合 Beacon 的轻量定位。

16. 最终产品定义¶

Beacon 是一个小巧、常驻、可靠的 Windows 开发者状态中心。

它的核心体验是：

托盘感知状态 → 胶囊提醒异常 → 悬浮面板解释问题 → 简单操作或跳转原始工具。

它不需要成为开发者的万能控制台，也不需要接管其他工具的工作。

成功标准不是功能数量，而是用户每天开发时几乎感觉不到它的存在，却能在真正需要关注的问题出现时及时发现并快速处理。

产品原则：Keep it small. Stay useful. Never get in the way.

附：落地路径（2026-10-11 用户附言）¶

先不立即大规模改代码：先对照本方案与当前仓库做一次差异审计——尤其核对现有 RFC 中的多 Widget 固定布局、 Quick Panel 交互、Provider 边界和当前 M5 验收状态——之后只修改真正冲突的部分。最大限度复用已完成的 M1–M5 工作，不为新方案再制造一轮重构。


状态	产品范围与设计基线（2026-10-11 用户定版收编）
上游	任务书 · 定位
关系	与 RFC-001 并行的产品基线；冲突处以本文档「差异审计」（mvp-issues 批3-补26）与用户拍板为准
术语对照	已拍板（2026-10-11 批3-补27①）：RFC-001 编号为产品唯一口径（L0=钉选悬浮组件 / L1=胶囊 / L2=Quick Panel / L3=详情）；本文档 §3 的 L0/L1/L2 仅为原文行文，阅读映射：本文 L0=胶囊→RFC L1，本文 L1=面板→RFC L2，本文 L2=详情→RFC L3