[PRD] 首次目标选择、Agent 目录与既有配置接管

[NongHua123]

PRD：首次目标选择、Agent 目录与既有配置接管

状态：产品决策已确认，待设计与实现 · P0 · v0.4.0

DRI：@python-rust
关联 Issue：#22、#34、#46、#47
更新规则：本 Issue 是这一组需求的唯一决策与进度入口。设计变化、实现 PR、阻塞和验收证据都回写这里；单个子 Issue 只维护自身交付，不复制整份 PRD。

一句话决策

首次用户先说明目标，FyAgent 再依据版本化 Agent 目录展示真实可用的 Agent 与接入方式；已有安装默认保持不动，只回读稳定的本机观测，任何配置变更都进入可见、可回读、可恢复的本机 apply job。

用户问题

当前四个 Issue 分别描述目录、接入意图、首次目标和已有配置，但存在三处产品风险：

1. [G2-01] 首次进入先问目标，再按目录给出 Agent 与接入方式 #34 与 [G3-01] 已合并至 #34：首次打开先问目标 #46 重复拥有首次进入流程，容易产生两套入口和状态。
2. 目录中的“出现”容易被前端误写成“已支持”，进而展示无法完成的安装或配置选项。
3. [G3-02] 为已有安装和配置提供“保持并回读”路径 #47 的“验证”仍可能被理解为主动联网、发送模型请求或逐 Agent runner，与已冻结边界冲突。

已冻结边界

• [G2-02] 建立凭据引用与本机/硬件可插拔后端 #35：仅使用 secretRef 与本机 keyring；未来允许硬件后端，但不建设云端托管密钥产品。
• [G2-08] 让配置应用过程可见、可回读、可恢复 #41：配置应用是一笔可见、可回读、可恢复的本机 apply job；主流程不主动联网、不发送模型请求；无真实证据时显示“尚未观察到”。
• [G3-04] 为 CLI Agent 定义最小真实请求合同 #49：已按 not planned 关闭；不新增 CLI challenge、runner 或逐 Agent 验证 adapter。
• [G3-05] 编写 WorkBuddy 首次使用与排障文档 #50：仅保留 WorkBuddy 截图化首次使用与排障文档；不建设软件内首任务验证器或 user_confirmed 证据。
• [G3-06] 保存能证明路由正确、又不过度采集的成功证据 #51：机器验证只服务具备稳定机器观测合同的 Agent；WorkBuddy 与人工尝试不进入机器验证证据。

上述边界是本 PRD 的输入，不在本组重新讨论。

目标用户与入口

A. 首次使用者

触发条件：fresh install，或尚未选择目标 Agent。

流程：

1. 先问“今天想用 AI 完成什么”，允许跳过并直接浏览 Agent。
2. 将目标映射为筛选条件，不把推荐结果写成能力证明。
3. 从 [G1-01] 建立 Agent 目录事实合同并驱动可用选项 #22 的目录事实合同读取可用 Agent、平台限制和动作能力。
4. 只展示当前 Agent 真正可达的接入方式；不先暴露 endpoint、model ID、headers 等实现字段。
5. 用户选择会产生配置变更时，交给 [G2-08] 让配置应用过程可见、可回读、可恢复 #41 的 apply job；未选择变更时不写入。

B. 已有安装或配置的用户

触发条件：稳定机器观测合同发现已有安装或非秘密配置。

流程：

1. 先展示“已观察到什么”和“尚未观察到什么”，不推断认证、额度或真实模型可用性。
2. 默认动作是“保持现状并回读”；该动作不写配置、不联网、不发送模型请求。
3. 另提供“导入非秘密配置”和“计划替换”，但只有目录合同允许时才显示。
4. 任何写入都必须先形成 apply job，包含变更预览、执行结果、回读结果和恢复入口。

状态所有权

状态	唯一所有者	前端使用规则
Agent 名单、平台与动作支持	版本化 Agent 目录（#22）	只能渲染目录允许的选项
本机安装和非秘密配置事实	稳定机器观测合同	只显示已观察字段，缺失即“尚未观察到”
用户目标与筛选	首次进入 UI（#34，吸收 #46）	用于排序/解释，不升级支持状态
配置变更、回读与恢复	apply job（#41）	UI 不直接写配置
凭据	secretRef + 本机 keyring（#35）	不进入普通配置、日志或 PRD 证据

前后端合同

1. Agent 目录条目

每个条目至少提供：

• 稳定 agent_id、显示名、支持平台与已审查版本范围；
• 总体目录状态：installable、detect_only、manual_install、platform_unsupported、pending_verification、withdrawn；
• 分动作能力：安装、检测、配置、回读分别声明状态和原因；
• 证据来源与 reviewed_at；未获得真实证据时不得填成支持。

规则：候选、仅检测、待验证和已撤回均不计入“已支持”数量；前端不得根据品牌名、Logo 或本机出现自行推导支持。

2. 本机观测结果

观测结果至少区分：

• observed：由稳定合同实际读到；
• not_observed：已执行观测但未发现；
• not_supported：当前 Agent/平台没有机器观测合同；
• unknown：未执行、失败或证据不足。

观测不得被命名为 verified，也不得暗示认证有效、模型可用、额度充足或目标 Agent 已完成真实请求。

3. UI 可用选项

UI 选项由“用户目标 + 目录动作能力 + 本机观测”派生：

• 目录不支持的动作不生成表单；
• 只有公开合同或运行时证据支持的动作才能自动配置；
• 手动/引导式路径必须明确跳转目标、用户动作和 FyAgent 不会代做的部分；
• 费用归属要明确为官方订阅、API 账户或对应 Provider，不使用模糊的“免费”。

Issue 职责

• [G1-01] 建立 Agent 目录事实合同并驱动可用选项 #22：目录事实合同、状态枚举、动作能力与前端消费规则。
• [G2-01] 首次进入先问目标，再按目录给出 Agent 与接入方式 #34：首次目标询问、Agent 选择和接入方式的一条完整 UI 流程；吸收 [G3-01] 已合并至 #34：首次打开先问目标 #46。
• [G3-01] 已合并至 #34：首次打开先问目标 #46：作为重复职责关闭，不再独立实现，也不创建“首成 session”或任务验证器。
• [G3-02] 为已有安装和配置提供“保持并回读”路径 #47：已有安装的“保持并回读 / 导入非秘密配置 / 计划替换”路径。

依赖顺序

1. [G1-01] 建立 Agent 目录事实合同并驱动可用选项 #22 先冻结最小目录合同和前端禁用规则。
2. [G2-01] 首次进入先问目标，再按目录给出 Agent 与接入方式 #34 与 [G3-02] 为已有安装和配置提供“保持并回读”路径 #47 可并行产出 UI 原型和状态文案，但不得先于目录合同承诺支持。
3. [G3-02] 为已有安装和配置提供“保持并回读”路径 #47 复用 [G1-11] 安装后必须通过真实健康探测 #32 的发现能力和 [G2-08] 让配置应用过程可见、可回读、可恢复 #41 的 apply job；“保持并回读”本身不依赖主动验证。
4. 实现 PR 必须分别回链对应 Issue 和本 PRD。

验收标准

• 新用户首先看到目标问题或“跳过并浏览 Agent”，不会先看到 Provider 技术表单。
• 所有 Agent 选项均可追溯到同一目录条目与动作状态。
• 候选、仅检测、待验证或平台不支持的 Agent 不进入完整安装/配置路径，不计入支持数量。
• 已有配置默认保持不变；“保持并回读”不写入、不联网、不发送模型请求。
• 无机器证据时诚实显示“尚未观察到”或“不支持机器观测”，不显示“验证成功”。
• 用户选择写入时只通过 [G2-08] 让配置应用过程可见、可回读、可恢复 #41 apply job，且具备预览、结果、回读和恢复入口。
• 凭据只以 secretRef 引用，不进入普通配置、日志或 Issue 证据。
• WorkBuddy 的机器证据边界符合 [G3-05] 编写 WorkBuddy 首次使用与排障文档 #50/[G3-06] 保存能证明路由正确、又不过度采集的成功证据 #51，不把截图或人工尝试升级为机器验证。

非目标

• 云端托管密钥、团队密钥中心或重型密钥产品；
• CLI challenge、runner、逐 Agent 主动验证 adapter；
• 软件内首任务验证器、模型请求或 user_confirmed 证据；
• 为无稳定观测合同的 Agent 伪造机器验证；
• 第三方自由上架目录；
• 将 Linux 重新纳入 FyAgent 官方运行平台。

更新与交付要求

@python-rust 作为 DRI，请在以下事件发生时直接更新本 Issue：目录合同冻结、UI 原型可评审、后端方案可评审、实现 PR 创建、出现阻塞、验收证据形成。每次更新需区分 产品决策 / 设计完成 / 代码完成 / 本机运行证据 / 用户验收，不得用 HTTP 200、任务创建或评论发布替代工程完成。

[NongHua123]

已完成首轮治理同步：#22 已收敛为目录事实合同，#34 已吸收 #46，#46 已按重复职责关闭，#47 已收窄为“保持并回读”。@python-rust 已设为本 PRD、#22、#34、#47 的 DRI。此处记录的是产品与任务治理完成，不代表设计、代码、运行证据或用户验收完成。

[NongHua123]

已完成首轮治理同步：#22 已收敛为目录事实合同，#34 已吸收 #46，#46 已按重复职责关闭，#47 已收窄为“保持并回读”。@python-rust 已设为本 PRD、#22、#34、#47 的 DRI。此处记录的是产品与任务治理完成，不代表设计、代码、运行证据或用户验收完成。

[NongHua123]

W33 今日执行切片（2026-08-13）

DRI：赖永杰；联调输入：徐焜

今日结果：6 个页面均可进入；每页至少一个关键动作接到真实后端或明确的受控降级路径；提交同一基线 SHA 的启动方式、运行截图/日志和未接通清单。同步审阅 #25–#28、#34、#47、#101，逐项标 adopted / changed / deferred 及原因。

16:00 仍无可运行纵切时，在本 Issue 回报阻塞与最小降级范围；18:00 提交可运行证据。静态 mock 或仅页面截图不算联调完成。

[NongHua123]

v0.4.2 发布对账（2026-08-24）

发布基线：v0.4.2，source SHA d8ab2a2。

结论：产品决策已记录，但设计/实现验收未完成，保持 OPEN。

该 Issue 已完成 PRD 和职责治理：#22 目录事实、#34 首次目标、#47 保持并回读、#41 apply job、#35 secretRef 的边界写得清楚；这属于 planning/governance evidence。

v0.4.2 仍直接落到 Agent directory；#22 名单/总体状态未满足正文，#34/#47 流程未实现，#35/#41 未进入发布，WorkBuddy 也未接共享 apply job。因此 PRD 的 8 条运行验收没有发布证据。

证据等级：planning + exact-source code_audit；无完整 runtime/UAT。处理：保留 OPEN。

[NongHua123]

2026-08-24 priority review

This Issue is now P1 / status:queued in v0.5.0｜Multi-Agent MVP.

Directory, installation, and onboarding remain valuable, but they no longer compete with #35 and the UCP mainline. Existing mitigation is preserved; the Issue remains open until its own AC and required runtime evidence are complete.