Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions docs/features/acp-client-desktop-web-ui.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# ACP Client 能力增强(Desktop / Web UI)功能提案

> 状态:提案 / 待评审
> 仓库:BitFun-OHOS
> 相关架构入口:
> - [`src/crates/interfaces/acp/AGENTS.md`](../../src/crates/interfaces/acp/AGENTS.md)
> - [`docs/architecture/agent-runtime-services-design.md`](../architecture/agent-runtime-services-design.md)
> - [`docs/architecture/product-architecture.md`](../architecture/product-architecture.md)
> - [`src/web-ui/AGENTS.md`](../../src/web-ui/AGENTS.md)

### 功能类型
<!-- 请描述功能建议的类型 -->
- [ ] 新功能
- [x] 现有功能增强
- [ ] 用户体验优化
- [ ] 性能优化
- [ ] 接口/集成扩展
- [ ] 其他

### 优先级
<!-- 请选择功能建议的优先级 -->
- [ ] 紧急(P0 - 核心需求,强烈期望实现)
- [x] 高(P1 - 重要功能,期望尽快实现)
- [ ] 中(P2 - 有价值的功能,计划实现)
- [ ] 低(P3 - 锦上添花,有时间再做)

### 背景与动机
<!-- 请描述你为什么需要这个功能,解决了什么痛点 -->
- BitFun 已在 `src/crates/interfaces/acp` 实现 ACP Client 半区,桌面/Web UI 通过 `acp:<clientId>` agentType 把外部 ACP agent 接入 flow_chat(见 `src/web-ui/src/flow_chat/utils/acpSession.ts`)。内置 preset 当前覆盖 `opencode` / `omp` / `claude-code` / `codex`(见 `src/crates/interfaces/acp/src/client/builtin_clients.rs`),但客户端接入、健康度、远程 workspace、模型/模式目录与工具/权限交互在 Desktop/Web UI 的呈现仍较碎片化,缺少统一的「客户端健康 → 会话建立 → 运行态」闭环体验。
- 痛点:① 多客户端并发使用时缺乏统一的健康/可用性视图;② 远程 workspace 复用本地 ACP 客户端配置时,探测/安装/降级链路对用户不透明;③ 会话级 config option(如 fast-mode、thought_level)与原生 BitFun agent 的模型/模式目录存在呈现差异;④ permission RPC 与 tool card 桥接在 Web UI 上的确认/拒绝 UX 与原生工具不一致。

### 功能描述
<!-- 请详细描述你期望的功能行为 -->
- 在 Desktop/Web UI 增强并收敛 ACP Client 的端到端体验,覆盖四个环节:
1. **客户端健康与接入**:统一展示已注册客户端(builtin + 用户自定义)的可用性探测结果(`AcpClientRequirementProbe` / `RemoteAcpClientRequirementSnapshot`),缺失 npm adapter / CLI 时提供一键安装或降级提示,远程 workspace 复用本地配置并显式标注探测阶段。
2. **会话生命周期**:复用 `AcpClientService` 的 NewSession / LoadSession / ResumeSession / CloseSession 路径,在 UI 上统一「创建 ACP 会话」入口(沿用 `nav-workspace-menu-create-acp-session` testid),并补齐 load/resume 失败时的可重试临时状态提示。
3. **运行态配置**:把 `AcpSessionConfigOption`(boolean / select)与 `AcpSessionModelOption` 在会话侧栏统一呈现,使 fast-mode、thought_level 等与原生 reasoning catalog 对齐(参考 `src/web-ui/src/flow_chat/utils/acpSessionConfig.ts` 的 projection 逻辑)。
4. **工具与权限交互**:对齐 `tool_card_bridge` 的外部 agent tool 命名/结果形状与原生 tool card;permission 请求的 approve/reject + option 选择在 Web UI 上与原生工具确认流一致。
- 实现边界遵循 `src/crates/interfaces/acp/AGENTS.md`:ACP 协议/客户端生命周期、stdio/连接归属、配置持久化、远程探测、timeout 策略留在 `bitfun-acp`;只把稳定能力事实透出给 UI 层,不在 Web UI 内重定义 ACP 协议或外部 agent tool 契约(后者归 `bitfun-agent-tools`)。

### 期望效果 / 使用场景
<!-- 描述该功能在什么场景下使用,以及使用后的预期效果 -->
1. 用户在工作区菜单选择「创建 ACP 会话」,弹出客户端选择器,实时显示每个客户端的探测状态(已就绪 / 缺少依赖 / 远程探测中),缺依赖可一键安装。
2. 进入会话后,侧栏能看到当前会话的模型与配置选项(fast-mode、thought_level 等),切换后立即生效并反映在下一轮 turn 的事件流中。
3. 外部 agent 发起 tool call 或 permission 请求时,Web UI 以与原生工具一致的卡片/确认弹窗呈现,用户 approve/reject(含 option 选择)后 ACP 客户端继续 turn。
4. 切换到远程 workspace 时,ACP 客户端复用本地配置并在 UI 显式标注探测阶段与降级原因,失败时给出可重试动作而非通用错误。

### 设计草案 / 参考示例
<!-- 如有设计稿、草图或参考的产品示例,请附在此处 -->
- 客户端探测与一键安装:参考 `src/crates/interfaces/acp/src/client/requirements.rs` 的 `probe_executable` / `probe_npm_adapter` / `install_npm_cli_package` 与远程对应实现,UI 映射 `AcpClientStatus`。
- 会话配置投影:参考 `src/web-ui/src/flow_chat/utils/acpSessionConfig.ts` 的 `resolveAcpReasoningState` / `resolveAcpFastModeState`,与原生 `ReasoningCatalogProjection` 对齐。
- 工具桥接:参考 `src/crates/interfaces/acp/src/client/tool_card_bridge/`(tool_name / tool_params)与 `bitfun_agent_tools::ACP_TOOL_PREFIX`,结果形状走 `bitfun-agent-tools` 既有契约。
- 生命周期/事件:参考 `src/crates/interfaces/acp/src/client/manager.rs` 的常量(启动 60s / permission 600s / close 5s 等)与 `AcpClientStreamEvent` 投影。

### 是否愿意贡献
<!-- 是否愿意参与该功能的开发或讨论 -->
- [ ] 我愿意参与开发
- [x] 我愿意参与讨论和测试
- [ ] 仅提出建议

### 补充说明
<!-- 其他你认为有助于理解功能建议的信息,如相关 Issue 链接、文档等 -->
- 现有基线(非本需求新增):内置 preset、会话创建/列举、模型与 config option、permission 响应、tool card 桥接、远程复用本地配置的底层链路已在 `bitfun-acp` 实现。本需求聚焦 Desktop/Web UI 的体验收敛与一致性增强,不新增 ACP 协议字段,不迁移 client 生命周期归属。
- 边界约束:不得在 `core-types` / `runtime-ports` / `agent-tools` 内重定义 ACP 配置/探测;外部 agent tool 契约归 `bitfun-agent-tools`;ACP stdio/连接/通知投影留在 `interfaces/acp`。
- 验证基线:`cargo check -p bitfun-acp` / `cargo test -p bitfun-acp`(Rust 侧);Web UI 侧用 `pnpm run type-check:web` 及 `src/web-ui/src/flow_chat/utils/acpSessionConfig.test.ts` / `acpSession.test.ts` 覆盖。
- 如需更窄范围(仅某一环,如「客户端健康度面板」或「远程 workspace 探测透明化」),可拆为独立 issue。
89 changes: 89 additions & 0 deletions docs/features/agent-memory-config.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
# Agent 记忆功能配置(Memory Configuration)需求文档

> 状态:需求 / 提案
> 仓库:BitFun-OHOS
> 相关架构入口:
> - [`docs/architecture/extensions/capability-runtime-integration-design.md`](../architecture/extensions/capability-runtime-integration-design.md)(Memory 能力边界:可替换 vs 权威归属)
> - [`docs/architecture/product-architecture.md`](../architecture/product-architecture.md)(分层与平台适配边界)
> - [`docs/architecture/peer-device-mode.md`](../architecture/peer-device-mode.md)(远程 / Peer 记忆归属)
> - [`docs/features/privacy-statement.md`](privacy-statement.md)(隐私同意状态门禁)
> 现有实现参考:
> - `src/web-ui/src/locales/*/settings/memories.json`(Settings → Memory:Basics / Extraction / Consolidation 配置契约)
> - `src/crates/services/services-core/src/session/memory_workspace.rs`(记忆工作区服务)
> - `src/crates/contracts/product-domains/src/privacy.rs`(`collection_allowed` 同意状态门禁)

### 功能类型
<!-- 请描述功能建议的类型 -->
- [ ] 新功能
- [x] 现有功能增强
- [x] 用户体验优化
- [ ] 性能优化
- [ ] 接口/集成扩展
- [ ] 其他

### 优先级
<!-- 请选择功能建议的优先级 -->
- [ ] 紧急(P0 - 核心需求,强烈期望实现)
- [ ] 高(P1 - 重要功能,期望尽快实现)
- [x] 中(P2 - 有价值的功能,计划实现)
- [ ] 低(P3 - 锦上添花,有时间再做)

### 背景与动机
<!-- 请描述你为什么需要这个功能,解决了什么痛点 -->
- BitFun 已有较成熟的记忆配置(Settings → Memory:Basics / Extraction / Consolidation 三段,覆盖自动生成、使用、提取资格、外部上下文策略、空闲 / 年龄 / 限额 / 并发 / 模型、合并候选与保留),但配置面仍有缺口。
- **缺少记忆内容的检视 / 编辑 / 删除单条入口**:现有只有 `resetMemory`(全量重置),用户无法查看 / 编辑 / 删除单条记忆、无法看到来源 provenance(来自哪个会话 / 时间),治理与信任不足。
- **provenance 与审计可见性缺失**:`capability-runtime-integration-design.md` 把"记忆来源、使用范围、版本、删除 / 撤销事实、权限、审计和注入决策"列为权威归属事实,但用户侧缺少审计视图(谁 / 何时写入 / 删除 / 注入)。
- **per-scope / per-workspace 配置缺失**:现有配置似为全局;多工作区 / 多项目下记忆范围与隔离需可配置,否则 A 项目记忆可能注入 B 项目会话。
- **隐私门禁可见性不足**:记忆提取自会话 transcript,可能含敏感内容;自动生成 / 使用 / 注入应受隐私同意状态门禁(fail-closed),未同意 / 受限模式不提取、不注入、不向云端发送,且用户需能看到该门禁状态。
- **远程 / Peer 场景策略缺失**:远程控制下记忆以受控端为准;peer 主机记忆读写需 deny 表对齐,控制器不应静默读写 peer 记忆。
- **多 surface / 鸿蒙 PC 覆盖**:记忆配置与记忆数据在 CLI / Web / MobileWeb / 鸿蒙 PC 的一致性需保证。

### 功能描述
<!-- 请详细描述你期望的功能行为 -->
- **记忆检视 / 编辑 / 删除**:在 Settings → Memory 增加"查看记忆"入口,列出当前记忆条目(含来源会话、提取时间、版本);支持单条编辑、删除、撤销(标记为不使用而非物理删除,保留撤销事实);保留 `resetMemory` 全量重置。
- **provenance 与审计**:每条记忆带 provenance(来源会话 id / 时间 / 提取模型 / 版本);提供审计视图(写入 / 删除 / 注入 / 撤销事件,含操作者与时间),只读、可导出,作为治理证据。
- **per-scope 配置**:支持按工作区 / 项目配置记忆范围与隔离(哪些会话贡献、记忆是否跨工作区共享);默认本地工作区隔离,跨工作区共享需显式开启。
- **隐私门禁**:记忆的自动生成、使用、注入受隐私同意状态门禁;未同意 / 受限模式(`PrivacyNotAccepted`)fail-closed 不提取、不注入、不向云端发送;记忆重置同步清理;用户可在设置中看到该门禁状态。
- **远程 / Peer 策略**:远程控制下记忆以受控端为准;peer 记忆读写 deny 表三端(桌面 / CLI / FE)对齐,控制器不静默读写 peer 记忆;远程不可用时给出清晰不支持态提示而非静默失败。
- **外部上下文与注入控制**:扩展现有 `externalContextPolicy`;新增"注入范围"配置(哪些记忆可注入新会话、是否需确认),注入决策保留为权威归属事实,不旁路。
- **保留与版本**:保留策略可配置(`maxUnusedDays` 等),版本化记忆便于回滚;删除 / 撤销走权威归属模块,不旁路。
- **多 surface 一致**:配置语义与记忆数据在桌面 / CLI / Web / MobileWeb / 鸿蒙 PC 一致,仅暴露方式按平台适配;UI 走 adapter / infrastructure 层,不直接调 host API。
- **平台无关 + 平台适配**:记忆配置 DTO 与策略平台无关(contracts / services 层),平台适配器暴露;鸿蒙 PC 通过适配器接入,语义与桌面一致。

### 期望效果 / 使用场景
<!-- 描述该功能在什么场景下使用,以及使用后的预期效果 -->
1. 用户在 Settings → Memory 查看记忆条目列表,看到每条来源(会话 / 时间 / 提取模型),可单条编辑 / 删除 / 撤销,无需全量重置即可精细管理。
2. 用户查看审计视图,看到记忆写入 / 删除 / 注入 / 撤销事件(操作者 / 时间),可导出作为合规与治理证据。
3. 用户按工作区配置记忆范围与隔离;A 工作区记忆默认不注入 B 工作区会话,跨工作区共享需显式开启。
4. 用户未同意隐私声明 / 处于受限模式时,记忆自动生成与注入 fail-closed 不执行,不向云端发送;用户可在设置中看到该门禁状态。
5. 远程控制下,记忆以受控端为准;控制器不静默读写 peer 记忆,deny 表三端对齐,远程不可用时给出清晰提示。
6. 鸿蒙 PC 上记忆配置语义与桌面一致,通过适配器接入。

### 设计草案 / 参考示例
<!-- 如有设计稿、草图或参考的产品示例,请附在此处 -->
- **现有参考实现**:
- [`docs/architecture/extensions/capability-runtime-integration-design.md`](../architecture/extensions/capability-runtime-integration-design.md):Memory 能力边界——可替换(存储实现 / 检索器 / 排序器 / 写入候选处理器 / 保留策略)vs 权威归属(来源 / 范围 / 版本 / 删除撤销 / 权限 / 审计 / 注入决策);Memory Retriever 适用失败回退组合规则。
- `src/web-ui/src/locales/*/settings/memories.json`:Basics / Extraction / Consolidation 配置契约——本需求在其上扩展检视 / 编辑 / 审计 / per-scope / 隐私门禁 / 远程策略。
- `src/crates/services/services-core/src/session/memory_workspace.rs`:记忆工作区服务——检视 / 编辑 / 删除 / 撤销 / 审计的权威归属层。
- `src/crates/contracts/product-domains/src/privacy.rs`:`collection_allowed()` 同意状态门禁——记忆生成 / 注入须服从。
- **行业参照**:Claude Code memory(`CLAUDE.md` / 记忆文件)、Cursor 记忆、ChatGPT memory 的查看 / 编辑 / 删除与 provenance / 审计。
- **落地分层建议**(遵循仓库分层与边界):
1. Contracts(`src/crates/contracts/product-domains`):记忆条目 DTO(provenance / 版本 / 状态)、审计事件 DTO、扩展配置 DTO——平台无关、行为轻量。
2. Services(`src/crates/services/services-core` 的 `memory_workspace` + `services-integrations`):记忆检视 / 编辑 / 删除 / 撤销、审计、per-scope、保留与版本——权威归属在此,不旁路。
3. Assembly(`src/crates/assembly`):按 delivery profile 装配记忆能力与配置。
4. Interfaces / App / UI(`src/apps` + `src/web-ui`):桌面 host 暴露记忆 command;Web UI 扩展 Settings → Memory(检视 / 编辑 / 审计 / per-scope / 隐私门禁状态);UI 走 adapter / infrastructure 层,不直接调 host API。
- **关键约束**:可替换的是存储 / 检索 / 排序 / 写入候选 / 保留策略;权威归属(来源 / 范围 / 版本 / 删除撤销 / 权限 / 审计 / 注入决策)不得旁路;隐私门禁 fail-closed;远程 deny 表三端对齐;不新增第二套记忆归属模块。

### 是否愿意贡献
<!-- 是否愿意参与该功能的开发或讨论 -->
- [x] 我愿意参与开发
- [ ] 我愿意参与讨论和测试
- [ ] 仅提出建议

### 补充说明
<!-- 其他你认为有助于理解功能建议的信息,如相关 Issue 链接、文档等 -->
- 本需求为现有记忆配置的**增强**(现有 Basics / Extraction / Consolidation 已可用),聚焦检视 / 编辑 / provenance / 审计 / per-scope / 隐私门禁 / 远程策略缺口。
- 记忆内容可能含敏感信息(提取自会话 transcript),隐私门禁与审计是合规与信任前置;未同意 / 受限模式 fail-closed,不得静默提取或注入。
- 远程 / Peer 遵循仓库"远程兼容"全局规则与 deny 表三端对齐原则(参见 `computer-use-refactor-plan.md` 的 M14 修复方向)。
- 鸿蒙 PC 是平台移植目标,记忆配置通过适配器接入,不属当前桌面优先范围但需保证语义一致(见 [`docs/architecture/platform-portability-design.md`](../architecture/platform-portability-design.md))。
- 不为覆盖竞品矩阵而引入第二套记忆归属模块或 `MemoryProviderRegistry` 等空壳公共对象(见 `capability-runtime-integration-design.md` 组合规则门槛)。
Loading
Loading