commit 5e6e8d5ca2221ac38469819cca08d16ab4070479 Author: YokiiroBW Date: Sat Jul 18 20:21:19 2026 +0800 docs(project): add architecture and implementation specifications diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..8cd66ea --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,460 @@ +# AstrBot Desktop 项目开发规则 + +## 1. 项目目标 + +本项目开发 AstrBot Windows 桌面客户端。 + +当前产品范围包括: + +* 双 AstrBot 实例同时在线 +* 陪伴实例与运维实例 +* 独立双对话框与单面板切换 +* 文字聊天 +* 语音交互 +* 主动消息 +* 游戏陪伴 +* 本机只读诊断 +* 受控文件整理 +* NAS 安全归档 +* 系统托盘、单实例、自动更新 +* 安全凭据存储 +* 日志与连接诊断 + +本项目不包含: + +* 项目工作区 +* IDE 或代码编辑器 +* Codex 集成 +* VM 开发任务交付 +* Git 图形客户端 +* 通用终端 +* 任意 PowerShell 或 CMD 执行 +* 无限制桌面控制 +* 无确认的破坏性文件操作 + +## 2. 权威文档 + +开发前必须完整阅读: + +1. `docs/01_Architecture_Design.md` +2. `docs/02_Codex_Implementation_Tasks.md` + +优先级顺序: + +1. 本文件 `AGENTS.md` +2. `docs/01_Architecture_Design.md` +3. `docs/02_Codex_Implementation_Tasks.md` +4. 当前用户明确指令 +5. 现有实现 + +如果文档之间存在冲突: + +* 不要静默选择其中一个方案; +* 将冲突记录到 `docs/decisions/pending-decisions.md`; +* 优先选择安全、简单、符合 MVP 范围的方案; +* 对会影响协议、安全模型、数据库结构或公开接口的冲突,暂停相关实现并明确报告。 + +## 3. 技术基线 + +默认技术栈: + +* Tauri 2 +* React +* TypeScript +* Vite +* Rust +* SQLite +* Windows Credential Manager +* REST + SSE +* Rust 本机能力层 + +未经明确批准,不得更换: + +* 桌面框架 +* 前端主框架 +* 数据库 +* 通信主方案 +* 凭据存储方案 + +允许在不改变总体架构的前提下选择成熟的小型依赖。 + +新增依赖前必须说明: + +* 使用目的 +* 是否仍在维护 +* 是否具有替代方案 +* 是否涉及原生编译 +* 是否扩大权限或攻击面 + +## 4. 架构边界 + +React 前端负责: + +* UI +* 用户交互 +* 状态展示 +* 表单 +* 流式消息渲染 +* 操作确认界面 + +Rust 层负责: + +* Token 和凭据访问 +* REST 与 SSE 长连接 +* 文件系统操作 +* NAS 文件事务 +* 窗口枚举 +* 进程检测 +* UI Automation +* Windows 事件日志 +* 系统托盘 +* 单实例 +* 自动更新 +* 本地日志 +* 安全策略检查 + +禁止: + +* React 直接读取系统凭据; +* React 直接获得任意文件系统权限; +* React 直接保存 Token; +* UI 直接调用 AstrBot 原始内部接口; +* AstrBot 服务端请求绕过本地权限策略; +* 使用字符串参数暴露任意 PowerShell、CMD 或 Shell 执行。 + +## 5. 双实例规则 + +MVP 支持多个已保存连接配置,但最多同时激活两个连接槽位: + +* `companion` +* `operations` + +两个槽位必须拥有独立的: + +* REST 客户端 +* SSE 连接 +* Token +* 重连状态 +* 会话 +* 消息 +* 未读数量 +* 主动通知 +* 错误状态 + +所有服务端数据必须至少使用以下字段隔离: + +* `profile_id` +* `server_instance_id` +* `conversation_id` + +不得只使用 `conversation_id` 作为本地唯一标识。 + +陪伴实例默认不能调用本机运维工具。 + +只有被用户指定为 `operations` 角色的实例,才能提出本机诊断或文件操作提案。 + +## 6. 本机工具安全规则 + +AstrBot 发来的工具调用只是操作提案,不是可直接执行的命令。 + +每个操作必须经过: + +1. Schema 校验 +2. 工具白名单校验 +3. Profile 角色校验 +4. 路径范围校验 +5. 风险等级判断 +6. 用户授权判断 +7. 本地执行 +8. 结果审计 + +禁止实现: + +* `execute_command(string)` +* `run_powershell(string)` +* `run_cmd(string)` +* `delete_any_path(string)` +* `write_any_registry_key(string)` +* 任意鼠标键盘脚本执行 + +必须使用参数明确、边界有限的工具。 + +例如: + +* `inspect_foreground_window` +* `query_recent_event_logs` +* `inspect_process` +* `check_port` +* `check_network_target` +* `read_authorized_log_file` +* `plan_file_transfer` +* `execute_approved_file_transfer` + +破坏性操作不得进入首版。 + +## 7. 文件与 NAS 事务规则 + +跨设备文件整理不得直接执行不可恢复的 Move。 + +必须使用: + +1. 生成计划 +2. Dry Run +3. 用户确认 +4. 复制至临时文件 +5. 校验大小 +6. 校验哈希 +7. 原子提交目标名称 +8. 处理源文件 +9. 保存操作记录 + +NAS 中断时必须保留源文件。 + +默认冲突策略为: + +* 询问 +* 重命名 +* 跳过 + +不得默认覆盖。 + +## 8. 敏感信息规则 + +禁止将以下内容写入普通配置、SQLite 普通字段、日志、测试快照或提交记录: + +* Access Token +* Refresh Token +* 密码 +* API Key +* Cookie +* 私钥 +* NAS 凭据 +* 完整 Authorization Header + +敏感信息必须保存在 Windows Credential Manager 或经过批准的安全存储中。 + +日志必须脱敏。 + +示例: + +```text +Bearer abcdefghijklmnop +``` + +只能记录为: + +```text +Bearer abcd…mnop +``` + +或: + +```text +[REDACTED] +``` + +## 9. Git 分支规则 + +采用简化的主干开发方式。 + +长期分支: + +* `main`:始终保持可构建、可运行 +* 不建立长期 `develop` 分支 + +每个开发阶段从 `main` 创建独立分支: + +```text +feat/p01-foundation +feat/p02-dual-connections +feat/p03-chat +feat/p04-local-diagnostics +feat/p05-nas-transfer +feat/p06-voice-game +chore/p07-release +``` + +修复分支: + +```text +fix/<简短问题名称> +``` + +文档分支: + +```text +docs/<简短主题> +``` + +禁止: + +* 直接在 `main` 上进行大型开发; +* 对已共享分支执行强制推送; +* 将多个无关阶段塞入同一个提交; +* 提交构建产物、Token、密码或本地缓存。 + +## 10. 提交规则 + +使用 Conventional Commits: + +```text +feat(scope): description +fix(scope): description +refactor(scope): description +test(scope): description +docs(scope): description +chore(scope): description +build(scope): description +ci(scope): description +``` + +示例: + +```text +feat(connection): add independent companion and operations slots +feat(diagnostics): add read-only Windows event log query +fix(sse): prevent duplicate events after reconnect +test(storage): cover profile data isolation +docs(protocol): document event acknowledgement flow +``` + +每个提交必须: + +* 聚焦单一逻辑目标; +* 可以独立解释; +* 不包含无关格式化; +* 在提交前运行相关检查; +* 不提交失败测试; +* 不使用含糊信息,例如 `update files`、`fix stuff`。 + +## 11. 阶段完成规则 + +每个阶段完成前必须: + +1. 运行格式化; +2. 运行 lint; +3. 运行类型检查; +4. 运行 Rust 检查; +5. 运行单元测试; +6. 运行适用的集成测试; +7. 完成生产构建; +8. 更新 `docs/progress.md`; +9. 更新相关架构或协议文档; +10. 创建阶段总结。 + +阶段未通过验收时不得合并到 `main`。 + +## 12. 版本规则 + +使用语义化版本。 + +建议阶段版本: + +* 基础骨架完成:`v0.1.0-alpha.1` +* 双实例连接完成:`v0.1.0-alpha.2` +* 文字聊天完成:`v0.1.0-alpha.3` +* 本机诊断完成:`v0.2.0-alpha.1` +* NAS 文件事务完成:`v0.2.0-alpha.2` +* 语音与游戏 MVP:`v0.3.0-alpha.1` +* 内部测试版:`v0.5.0-beta.1` +* 首个公开稳定版:`v1.0.0` + +标签只能在: + +* 相关阶段全部验收通过; +* `main` 可构建; +* CHANGELOG 已更新; +* 没有未提交修改; + +时创建。 + +## 13. 开发过程记录 + +必须维护: + +```text +docs/implementation-plan.md +docs/progress.md +docs/decisions/ +CHANGELOG.md +``` + +`docs/progress.md` 至少记录: + +* 当前阶段 +* 已完成任务 +* 正在进行的任务 +* 未完成任务 +* 阻塞问题 +* 测试状态 +* 当前分支 +* 最近提交 +* 下一步 + +重大技术决策使用 ADR: + +```text +docs/decisions/ADR-0001-*.md +``` + +ADR 内容包括: + +* 背景 +* 可选方案 +* 最终选择 +* 选择理由 +* 代价 +* 后续影响 + +## 14. 工作方式 + +开始编码前必须: + +1. 阅读权威文档; +2. 检查当前仓库状态; +3. 确认当前分支; +4. 生成实施计划; +5. 找出阻塞性不确定项; +6. 先完成必要 Spike; +7. 再开始正式编码。 + +开发过程中: + +* 按任务清单顺序推进; +* 不要一次性生成整个项目; +* 每完成一个可验证增量就测试和提交; +* 可以自主处理普通实现细节; +* 不得自主扩大产品范围; +* 不得跳过高风险 Spike; +* 不得因后续功能提前过度抽象。 + +## 15. 停止条件 + +遇到以下情况必须停止相关修改并报告: + +* 文档在安全模型上冲突; +* 需要修改 AstrBot 核心代码; +* 需要开放任意命令执行; +* 需要绕过 Windows 权限; +* 需要禁用 TLS 校验; +* 需要存储明文凭据; +* 数据库迁移可能导致数据丢失; +* 需要执行不可恢复的批量文件操作; +* 测试持续失败且原因无法确认; +* 实现会明显偏离 MVP。 + +普通编译错误、类型错误、测试缺失和小型设计细节不属于停止条件,应自行解决。 + +## 16. 完成定义 + +一个任务只有同时满足以下条件才算完成: + +* 功能实现完成; +* 错误路径已处理; +* 权限边界已验证; +* 测试已添加; +* 相关检查已通过; +* 文档已更新; +* 没有敏感信息泄露; +* 已使用规范提交; +* 工作区干净。 diff --git a/AstrBot_Desktop_Codex_Forgejo_Predevelopment_Workflow.md b/AstrBot_Desktop_Codex_Forgejo_Predevelopment_Workflow.md new file mode 100644 index 0000000..f209d07 --- /dev/null +++ b/AstrBot_Desktop_Codex_Forgejo_Predevelopment_Workflow.md @@ -0,0 +1,934 @@ +# AstrBot Desktop:Codex 前期开发与 Forgejo 版本控制流程 + +## 0. 使用目标 + +本流程用于让 Codex 在 Windows 本地完成 AstrBot Desktop 的前期开发,包括: + +- Git 仓库初始化与规范化 +- Tauri 2 + React + TypeScript + Rust 工程骨架 +- 双 AstrBot 连接架构的前置验证 +- 本机诊断能力的技术验证 +- NAS 文件事务的技术验证 +- 基础协议、数据模型、Mock Gateway +- 测试、文档、提交记录和 Forgejo 分支推送 +- 为后续正式功能开发建立稳定基线 + +前期阶段不要求完成完整聊天、语音、游戏陪伴和本机运维功能。 + +--- + +# 一、你需要先做的事情 + +## 1. 在 Forgejo 创建仓库 + +建议设置: + +- 仓库名:`astrbot-desktop` +- 可见性:私有 +- 默认分支:`main` +- 不勾选初始化 README +- 不勾选初始化 `.gitignore` +- 不勾选初始化 License + +这样避免 Forgejo 远程仓库与本地初始提交发生冲突。 + +## 2. 准备 Git 远程地址 + +优先使用 SSH。 + +标准 SSH 端口: + +```text +git@:/astrbot-desktop.git +``` + +非标准 SSH 端口: + +```text +ssh://git@://astrbot-desktop.git +``` + +HTTPS 备用地址: + +```text +http:////astrbot-desktop.git +``` + +不要把 Forgejo 密码或访问令牌直接写入远程 URL。 + +## 3. 准备本地项目目录 + +建议: + +```text +D:\Projects\AstrBot-Desktop +``` + +放入: + +```text +AstrBot-Desktop/ +├─ AGENTS.md +└─ docs/ + ├─ 01_Architecture_Design.md + └─ 02_Codex_Implementation_Tasks.md +``` + +对应已有文件: + +- `01_AstrBot_Desktop_Dual_Instance_and_Local_Assistant_Design.md` +- `02_AstrBot_Desktop_Codex_Implementation_Tasks.md` + +建议重命名后放入 `docs/`。 + +## 4. 用 Codex 打开整个项目目录 + +不要只上传两份文档。 + +在 Codex Desktop 中选择: + +```text +D:\Projects\AstrBot-Desktop +``` + +然后粘贴本文第六部分的“Codex 总控口令”。 + +--- + +# 二、推荐 Git 与 Forgejo 策略 + +## 1. 分支模型 + +长期分支: + +```text +main +``` + +阶段分支: + +```text +feat/p00-bootstrap +feat/p01-foundation +feat/p02-dual-connections +feat/p03-chat +feat/p04-local-diagnostics +feat/p05-nas-transfer +feat/p06-voice-game +chore/p07-release +``` + +修复分支: + +```text +fix/ +``` + +文档分支: + +```text +docs/ +``` + +## 2. main 分支规则 + +初始基线推送成功后,在 Forgejo 中保护 `main`: + +- 禁止强制推送 +- 禁止删除分支 +- 正式开发不直接推送 `main` +- 功能分支通过 Pull Request 合并 +- 合并前要求基础检查通过 +- 只有你本人拥有最终合并权限 + +Codex负责: + +- 创建功能分支 +- 提交 +- 推送功能分支 +- 生成 PR 标题和正文 + +你负责: + +- 在 Forgejo 创建 PR +- 查看变更 +- 决定是否合并 + +## 3. 提交格式 + +使用 Conventional Commits: + +```text +docs(project): add architecture and implementation specifications +chore(repo): initialize repository and ignore rules +chore(tauri): scaffold Tauri React TypeScript application +test(connection): verify two independent SSE clients +test(windows): verify UI Automation access +feat(protocol): add gateway protocol schemas +feat(mock): add mock companion gateway +fix(sse): prevent duplicate events after reconnect +``` + +禁止使用: + +```text +update +fix +changes +complete +final +``` + +--- + +# 三、Codex 前期开发范围 + +## P00:仓库与工程底座 + +必须完成: + +- Git 初始化 +- `main` 初始基线 +- Forgejo `origin` 配置 +- 初始文档提交 +- `.gitignore` +- `README.md` +- `CHANGELOG.md` +- `AGENTS.md` +- `docs/implementation-plan.md` +- `docs/progress.md` +- `docs/decisions/` +- `docs/spikes/` +- `docs/protocol/` +- `.forgejo/workflows/ci.yml` + +## P01:Tauri 工程骨架 + +必须完成: + +- Tauri 2 +- React +- TypeScript +- Vite +- Rust +- 前端与 Rust IPC 最小验证 +- Windows 开发构建 +- 基础生产构建 +- 基础错误边界 +- 基础日志接口 +- 配置目录初始化 + +暂不实现完整 UI。 + +## P02:双实例连接 Spike + +验证: + +- 两个独立 REST Client +- 两个独立 SSE Client +- 独立连接状态 +- 独立重连 +- 独立取消 +- 独立事件去重 +- 一个实例断线不影响另一个 +- `companion` 和 `operations` 槽位模型 +- Mock Gateway 可同时模拟两个 AstrBot + +## P03:安全存储 Spike + +验证: + +- Windows Credential Manager 或可接受的 Windows 安全凭据方案 +- Token 不进入 React 状态 +- Token 不进入 SQLite 普通字段 +- Token 不进入日志 +- 凭据引用模型 +- 凭据创建、读取、更新、删除 +- 错误状态处理 + +## P04:Windows 本机能力 Spike + +分别验证: + +- 当前前台窗口信息 +- 标准弹窗 UI Automation 文本 +- 指定窗口截图 +- 进程信息 +- Windows Event Log 只读查询 +- 端口占用检测 +- 网络目标检测 +- 普通日志文件尾部读取 +- 配置文件解析 +- 本地脱敏 + +每个 Spike 必须独立,不要直接耦合到正式业务。 + +## P05:NAS 文件事务 Spike + +验证: + +- UNC 路径访问 +- 文件列表 +- 临时文件复制 +- 大小校验 +- 哈希校验 +- 最终重命名 +- 同名冲突处理 +- NAS 中断后的恢复 +- 不删除源文件 +- Dry Run 计划 + +测试只能使用用户明确提供的测试目录。 + +## P06:协议与 Mock Gateway + +建立: + +- `ConnectionProfile` +- `ConnectionSlot` +- `ConnectionState` +- `ProtocolEnvelope` +- `GatewayEvent` +- `ToolProposal` +- `ToolResult` +- `DiagnosticBundle` +- `FileTransferPlan` +- `ServerCapabilities` +- `ClientCapabilities` + +Mock Gateway 至少支持: + +- 健康检查 +- 服务信息 +- 能力列表 +- 模拟鉴权 +- 模拟 SSE +- 模拟断线 +- 模拟重复事件 +- 模拟陪伴消息 +- 模拟运维工具提案 + +--- + +# 四、前期阶段验收标准 + +必须真实运行并记录: + +## 前端 + +```text +format +lint +typecheck +unit tests +production build +``` + +## Rust + +```text +cargo fmt --check +cargo clippy -- -D warnings +cargo test +cargo check +``` + +## Tauri + +```text +开发模式启动 +Windows 生产构建 +``` + +代码签名、正式更新服务器和安装包发布密钥在前期可以标记为待配置,但不能伪造成功结果。 + +## Git + +必须满足: + +- 工作区干净 +- 无敏感文件 +- 提交粒度清晰 +- 当前功能分支已推送 Forgejo +- 不执行 force push +- 不自动合并 `main` +- 输出提交列表 +- 输出 PR 标题和正文 + +--- + +# 五、Forgejo Actions + +Codex应创建: + +```text +.forgejo/workflows/ci.yml +``` + +CI至少规划: + +- 前端格式检查 +- lint +- TypeScript 检查 +- 前端测试 +- Rust fmt +- Rust clippy +- Rust test + +Tauri Windows 完整构建通常需要 Windows Runner,因此: + +- 如果 Forgejo 已有 Windows Runner,则加入 Windows 构建任务 +- 如果只有 Linux/Docker Runner,则先运行跨平台检查 +- 将 Windows 构建标记为本地必检或待配置 Runner +- 不得声称没有 Runner 的工作流已成功运行 + +--- + +# 六、交给 Codex 的总控口令 + +使用前替换: + +- `` +- `` +- `` +- `` + +--- + +你现在负责 AstrBot Windows 桌面客户端的前期工程建设和技术验证。 + +项目目录: + +```text + +``` + +Forgejo 远程仓库: + +```text + +``` + +Forgejo 仓库标识: + +```text +/ +``` + +项目根目录中的以下文件是权威开发依据: + +```text +AGENTS.md +docs/01_Architecture_Design.md +docs/02_Codex_Implementation_Tasks.md +``` + +请完整阅读这些文件,并严格遵守项目范围、架构边界、安全要求和任务顺序。 + +本轮目标不是一次性完成整个客户端,而是完成: + +1. 仓库和版本控制底座; +2. Tauri 2 + React + TypeScript + Rust 工程骨架; +3. 双 AstrBot 独立连接的前置验证; +4. Windows 安全凭据存储的前置验证; +5. 本机诊断能力的前置验证; +6. NAS 安全文件事务的前置验证; +7. 协议 Schema 与 Mock Gateway; +8. 测试、文档、CI 和 Forgejo 分支推送。 + +## A. 开始前检查 + +先检查: + +- 当前目录和已有文件; +- Git 是否已经初始化; +- 当前分支; +- Git 用户名和邮箱是否已配置; +- `origin` 是否存在; +- Forgejo SSH 或 HTTPS 认证是否可用; +- Node.js、包管理器、Rust、Cargo、Git; +- Tauri 2 Windows 构建依赖; +- WebView2; +- Visual Studio C++ Build Tools; +- 当前 Windows 环境能否完成 Tauri 构建。 + +禁止在日志、文档、提交或终端回显中暴露: + +- Forgejo 密码; +- Access Token; +- SSH 私钥; +- AstrBot Token; +- NAS 密码; +- API Key。 + +如果系统级依赖缺失且需要管理员权限: + +- 明确列出缺失项和安装命令; +- 继续完成不依赖该项的任务; +- 不要虚构验证结果; +- 不要因为一个非阻塞依赖而停止全部工作。 + +## B. Git 和 Forgejo 初始化 + +如果当前目录还不是 Git 仓库: + +```text +初始化 Git +默认分支设为 main +``` + +如果 `origin` 不存在: + +```text +添加 为 origin +``` + +如果 `origin` 已存在: + +- 检查它是否指向正确的 Forgejo 仓库; +- 不要静默覆盖错误 remote; +- 记录并修正明显错误; +- 不在 remote URL 中嵌入密码或 Token。 + +创建仓库基础文件: + +```text +.gitignore +README.md +CHANGELOG.md +AGENTS.md +docs/implementation-plan.md +docs/progress.md +docs/decisions/pending-decisions.md +docs/spikes/ +docs/protocol/ +``` + +将架构文档、任务清单和仓库规则作为基线提交。 + +建议基线提交: + +```text +docs(project): add architecture and implementation specifications +chore(repo): initialize repository and development rules +``` + +如果远程 `main` 为空,完成首次: + +```text +git push -u origin main +``` + +不要覆盖已有远程历史。 + +首次基线推送后,从最新 `main` 创建: + +```text +feat/p00-bootstrap +``` + +后续前期开发全部在该分支进行。 + +## C. 文档审查与执行计划 + +完整阅读权威文档,然后: + +1. 提取全部阶段、依赖和验收条件; +2. 识别矛盾、缺失和过度设计; +3. 普通问题记录到: + `docs/decisions/pending-decisions.md` +4. 重大设计选择使用 ADR: + `docs/decisions/ADR-xxxx-*.md` +5. 将本轮计划写入: + `docs/implementation-plan.md` +6. 将当前状态写入: + `docs/progress.md` + +不得自行加入: + +- 项目工作区; +- Codex 集成; +- VM 任务系统; +- Git 图形客户端; +- 任意 PowerShell/CMD/Shell; +- 无确认文件删除; +- 全盘扫描; +- 无限制桌面控制。 + +## D. 建立工程骨架 + +建立并验证: + +```text +Tauri 2 +React +TypeScript +Vite +Rust +``` + +要求: + +- 前端只负责 UI、交互和状态展示; +- Rust 负责网络、安全存储、文件操作和 Windows 原生能力; +- Token 不得进入 React; +- UI 不得获得任意文件系统权限; +- 不直接依赖 AstrBot 内部 API; +- 不提前实现完整业务页面; +- 不进行无用途的过度抽象。 + +建立推荐目录: + +```text +src/ +src/features/ +src/services/ +src/stores/ +src/types/ +src-tauri/src/ +src-tauri/src/networking/ +src-tauri/src/secure_store/ +src-tauri/src/diagnostics/ +src-tauri/src/file_transfer/ +src-tauri/src/policy/ +docs/ +tests/ +``` + +完成最小前端到 Rust IPC 测试。 + +## E. 完成 P0 技术验证 + +在 `docs/spikes/` 中为每个验证建立独立报告。 + +每份报告必须包含: + +- 目标; +- 环境; +- 最小验证实现; +- 实际执行结果; +- 日志摘要; +- 已知限制; +- 安全影响; +- 是否阻塞 MVP; +- 推荐正式实现方案。 + +必须验证: + +### 1. 双连接 + +- 两个独立 REST 客户端; +- 两个独立 SSE 客户端; +- 陪伴槽位和运维槽位; +- 独立连接状态; +- 独立取消; +- 独立重连; +- 事件 ID 去重; +- 一个连接断开不影响另一个。 + +### 2. 安全凭据 + +- Windows 安全存储; +- 创建、读取、更新、删除; +- 只在 Rust 层访问; +- 普通配置只保存 credential reference; +- 日志自动脱敏。 + +### 3. 本机只读诊断 + +- 前台窗口; +- UI Automation 标准弹窗文字; +- 指定窗口截图; +- 进程信息; +- Windows Event Log; +- 端口检测; +- 网络检测; +- 日志文件尾部读取; +- JSON/YAML/TOML/INI 基础解析; +- Token、密码、Cookie、API Key 脱敏。 + +### 4. NAS 文件事务 + +只对用户指定测试目录操作: + +- UNC 路径检查; +- 临时文件复制; +- 大小校验; +- 哈希校验; +- 最终提交; +- 同名冲突; +- 网络中断; +- Dry Run; +- 默认保留源文件。 + +### 5. 更新和发布条件 + +验证或记录: + +- Tauri Updater 集成条件; +- Windows 代码签名条件; +- 安装包构建条件; +- 当前缺失的证书或发布基础设施。 + +不得使用临时密钥冒充正式发布配置。 + +## F. 协议与 Mock Gateway + +建立稳定的协议类型和 Mock Gateway。 + +至少包含: + +```text +ConnectionProfile +ConnectionSlot +ConnectionState +ServerCapabilities +ClientCapabilities +ProtocolEnvelope +GatewayEvent +ToolProposal +ToolResult +DiagnosticBundle +FileTransferPlan +``` + +Mock Gateway 必须支持两个实例同时运行,并可模拟: + +- 健康检查; +- 服务信息; +- 能力列表; +- 鉴权成功和失败; +- SSE 流; +- 主动消息; +- 断线重连; +- 重复事件; +- 陪伴消息; +- 运维工具提案。 + +## G. 测试和 CI + +创建本地脚本,使以下检查可以通过统一命令运行: + +```text +前端 format +前端 lint +TypeScript typecheck +前端 test +前端 build +cargo fmt --check +cargo clippy -- -D warnings +cargo test +cargo check +Tauri 开发构建 +Tauri Windows 生产构建 +``` + +创建: + +```text +.forgejo/workflows/ci.yml +``` + +先检查 Forgejo Runner 条件。 + +- 有可用 Runner:配置并验证能够运行的任务; +- 没有 Runner:仍然提交工作流,但在进度文档明确标记“等待 Runner”; +- 不要声称未执行的 CI 已通过; +- 不要在 CI 中放入长期 Token; +- 不要在日志中回显 secrets。 + +## H. 提交和推送规则 + +使用 Conventional Commits。 + +每完成一个可验证增量: + +1. 运行相关检查; +2. 更新 `docs/progress.md`; +3. 提交; +4. 推送当前功能分支到 Forgejo。 + +推送: + +```text +git push -u origin feat/p00-bootstrap +``` + +后续使用普通: + +```text +git push +``` + +禁止: + +- force push; +- 自动覆盖远程历史; +- 将所有修改压成一个大提交; +- 将测试失败的版本合并 main; +- 将构建产物、缓存、凭据提交; +- 自动合并 Forgejo 的 main。 + +本轮完成后,不直接合并 `main`。 + +生成一份 Forgejo Pull Request 建议,包括: + +- PR 标题; +- PR 正文; +- 完成范围; +- 提交列表; +- 测试结果; +- 未验证项目; +- 风险; +- 后续阶段。 + +## I. 前期阶段完成定义 + +只有满足以下条件,才能声明本轮完成: + +- 权威文档已阅读; +- Git 和 Forgejo 远程正确; +- 基线 main 已存在; +- `feat/p00-bootstrap` 已推送; +- Tauri 工程可构建; +- 前端与 Rust IPC 可工作; +- 双连接 Spike 有实际结果; +- 安全存储 Spike 有实际结果; +- Windows 诊断 Spike 有实际结果; +- NAS Spike 有实际结果或清晰记录环境阻塞; +- 协议 Schema 已建立; +- Mock Gateway 已建立; +- 测试已运行; +- 文档已更新; +- 无敏感信息进入仓库; +- 工作区干净; +- 提供 PR 建议。 + +## J. 最终报告格式 + +完成后输出: + +```text +1. 当前分支 +2. Forgejo 远程 +3. 已推送分支 +4. 提交列表 +5. 已完成内容 +6. Spike 结果 +7. 构建结果 +8. 测试结果 +9. CI 状态 +10. 未完成和阻塞项 +11. 安全检查结果 +12. PR 标题 +13. PR 正文 +14. 下一阶段建议 +``` + +普通编译、类型和测试问题自行解决,不要频繁询问。 + +遇到以下情况才停止相关部分并明确报告: + +- 需要任意命令执行接口; +- 需要明文凭据; +- 需要绕过 Windows 安全; +- 需要关闭 TLS 校验; +- 需要对真实文件执行不可恢复操作; +- 需要修改 AstrBot 核心但文档没有授权; +- 现有远程仓库包含无法安全合并的历史; +- 数据库迁移存在数据丢失风险。 + +现在开始执行仓库检查、Forgejo 连接验证、文档审查、Git 初始化和前期工程建设。不要只输出计划;在当前环境中实际完成所有能够安全完成的任务。 + +--- + +# 七、你在 Codex 完成后需要做的事情 + +## 1. 检查 Forgejo + +应该看到: + +```text +main +feat/p00-bootstrap +``` + +以及清晰的多条提交。 + +## 2. 检查 Codex 最终报告 + +重点确认: + +- 是否真的运行构建和测试 +- 是否有未验证项 +- 是否泄露敏感信息 +- NAS 测试是否只用了测试目录 +- 是否没有自动合并 main +- 是否给出 PR 标题和正文 + +## 3. 创建 Forgejo PR + +在 Forgejo 中创建: + +```text +feat/p00-bootstrap → main +``` + +审查通过后合并。 + +## 4. 开启 main 分支保护 + +进入: + +```text +仓库设置 → 分支 → 保护规则 +``` + +保护: + +```text +main +``` + +建议: + +- 禁止 force push +- 禁止删除 +- 要求通过 PR 合并 +- 只有你可以最终合并 + +## 5. 下一阶段 + +合并后让 Codex: + +```text +更新本地 main +从 main 创建 feat/p01-foundation +继续执行文档中的下一阶段 +完成后推送 Forgejo并生成 PR 说明 +``` + +--- + +# 八、日常继续开发的短口令 + +```text +继续 AstrBot Desktop 的下一开发阶段。 + +先读取 AGENTS.md、docs/implementation-plan.md、docs/progress.md 和两份权威设计文档。 + +执行前: + +1. 获取 Forgejo origin 最新状态; +2. 确认当前工作区干净; +3. 切换并更新 main; +4. 根据任务清单创建本阶段功能分支; +5. 不直接在 main 开发; +6. 按最小可验证增量实现、测试、提交和推送; +7. 不扩大 MVP; +8. 不实现任意命令执行; +9. 不自动合并 main; +10. 完成后生成 Forgejo PR 标题和正文。 + +先检查上阶段遗留问题,再开始当前阶段。所有实际运行结果写入 docs/progress.md。 +``` diff --git a/docs/01_Architecture_Design.md b/docs/01_Architecture_Design.md new file mode 100644 index 0000000..5c39092 --- /dev/null +++ b/docs/01_Architecture_Design.md @@ -0,0 +1,1613 @@ +# 01|桌面客户端双实例陪伴与本机运维系统 + +> 文档名称:`01_桌面客户端双实例陪伴与本机运维系统.md` +> 项目:AstrBot Windows 桌面客户端 +> 文档状态:架构重构版,可交给 Codex 分阶段开发 +> 日期:2026-07-18 +> 目标读者:Codex、桌面客户端开发者、AstrBot 插件开发者、测试与发布人员 + +--- + +## 1. 执行摘要 + +本项目不再建设项目工作区、VM 任务投递、代码编辑、Git 管理或 Codex 控制台。上述开发工作继续由桌面 Codex 与 VM 交付流程承担。 + +桌面客户端重新定位为: + +> **AstrBot 的 Windows 陪伴与本机助手客户端。** + +核心能力包括: + +1. 文字聊天与多会话; +2. 语音聊天; +3. 主动消息与桌面通知; +4. 游戏陪伴与有限窗口感知; +5. 用户主动发起的电脑问题诊断; +6. 受控的本地文件整理与 NAS 归档; +7. 同时连接两个 AstrBot 实例,一个作为陪伴实例,一个作为运维实例。 + +最终推荐技术方案: + +```text +Tauri 2 +React + TypeScript + Vite +Rust Native Core +SQLite +Windows Credential Manager / DPAPI +REST + SSE(MVP) +WebSocket(连续语音或高频事件的后续扩展) +``` + +双实例的产品规则为: + +```text +可保存多个 ConnectionProfile +MVP 最多同时激活两个连接槽位 +├─ Companion Slot:陪伴实例 +└─ Operations Slot:运维实例 +``` + +两个实例可以: + +- 并排显示为两个对话框; +- 切换为单面板标签模式; +- 分别保持连接、会话、未读状态和主动消息; +- 使用不同的 AstrBot 地址、账号、人格和插件; +- 在本地数据层完全隔离。 + +重要安全结论: + +> 只有运维实例可以申请本机诊断和文件操作;服务端请求只是操作提案,最终是否执行由客户端本地策略引擎和用户确认决定。 + +--- + +## 2. 产品定位与范围调整 + +### 2.1 新定位 + +```text +AstrBot Companion Desktop +├─ 陪伴沟通 +├─ 主动交互 +├─ 游戏陪伴 +├─ 电脑问题诊断 +└─ 安全文件助手 +``` + +### 2.2 不再承担的职责 + +以下内容从桌面客户端项目中删除: + +- 项目工作区; +- 代码编辑器; +- VM 任务投递; +- Codex 对话与开发任务管理; +- Git 仓库管理; +- 内置终端; +- 通用 Agent 编排控制台; +- 代码补丁审查; +- 项目文件同步; +- 开发环境远程执行。 + +### 2.3 与 Codex 的边界 + +```text +桌面 Codex + VM +负责: +- 编程 +- Git +- 构建与部署 +- 插件开发 +- 项目任务 + +AstrBot Desktop +负责: +- 文字和语音交流 +- 主动陪伴 +- 游戏陪伴 +- 日常电脑诊断 +- 文件与 NAS 整理 +``` + +两个系统不需要在首版互相嵌入。 + +--- + +## 3. 需求审视与关键修正 + +### 3.1 双 AstrBot 不应实现成两个独立客户端进程 + +推荐在一个桌面客户端内维护两个独立连接槽位,而不是启动两个应用实例。 + +原因: + +- 单实例、托盘和自动更新更简单; +- 麦克风、通知和窗口捕获权限不会冲突; +- 可以统一管理本机工具授权; +- 用户可以并排查看,也可以快速切换; +- 避免两个客户端同时读取或移动同一文件。 + +### 3.2 “两个实例同时在线”不等于“无限多实例同时在线” + +MVP 允许保存任意数量的连接配置,但只允许两个活动连接槽位。 + +```text +Saved Profiles:N 个 +Active Slots:最多 2 个 +``` + +后续若确有需求,再考虑增加更多活动连接。 + +### 3.3 陪伴实例和运维实例必须权限隔离 + +不能仅依赖提示词区分角色。 + +必须在客户端本地绑定: + +```text +profile_id +role +server_instance_id +certificate_fingerprint +local_tool_policy_id +``` + +陪伴实例默认无本机工具权限。运维实例也只能申请本地工具白名单中的操作。 + +### 3.4 电脑诊断不等于任意电脑控制 + +MVP 支持: + +- 读取用户选择的日志和配置; +- 读取当前报错窗口文字; +- 查询进程、端口、服务、磁盘和网络; +- 查询相关 Windows 事件日志; +- 生成诊断报告; +- 规划并执行可恢复的文件复制或移动。 + +MVP 不支持: + +- 任意 PowerShell; +- 任意 CMD; +- 自动接受 UAC; +- 任意注册表修改; +- 无确认安装或卸载; +- 进程注入; +- 游戏内存读取; +- 无人值守永久删除。 + +### 3.5 REST + SSE 足以支撑双实例 MVP + +双连接不强制要求自定义 WebSocket。 + +每个活动实例维护: + +- 一个 REST Client; +- 一个独立 SSE Event Stream; +- 独立 Token 和刷新周期; +- 独立断线重连状态机; +- 独立 `last_event_id`; +- 独立消息去重集合。 + +连续全双工语音或高频游戏事件出现后,再为对应能力增加 WebSocket。 + +--- + +## 4. 技术选型结论 + +### 4.1 桌面框架 + +继续采用 **Tauri 2**。 + +理由: + +- 客户端会长期驻留托盘; +- 游戏运行时需要控制内存和 CPU 占用; +- 本地诊断、窗口枚举、文件系统和安全存储需要原生层; +- Rust 适合实现有限、强类型的本地工具; +- 前端仍可使用 React 生态。 + +### 4.2 前端技术栈 + +```text +React +TypeScript +Vite +Zustand +TanStack Query +Zod +React Router +Vitest +Playwright +``` + +前端负责: + +- 双面板与标签切换; +- 会话展示; +- 连接状态; +- 工具操作提案; +- 用户授权和执行进度; +- 语音、游戏模式和通知设置。 + +### 4.3 Rust 层职责 + +Rust Core 负责: + +- 双连接管理; +- REST 和 SSE; +- Token 与证书处理; +- SQLite; +- Windows Credential Manager; +- 单实例、托盘、自启; +- 窗口和进程检查; +- 日志与配置读取; +- Windows 事件日志查询; +- NAS 文件事务; +- 本地工具策略与授权; +- 自动更新和诊断包。 + +### 4.4 不应放在前端的能力 + +- Token 和密码读取; +- SQLite 直接访问; +- 任意文件系统访问; +- 注册表访问; +- Windows 事件日志访问; +- 进程和服务控制; +- NAS 凭据; +- 原始截图捕获; +- 本机工具最终执行; +- TLS 证书例外处理。 + +--- + +## 5. 客户端总体架构 + +```text +┌──────────────────────────────────────────────┐ +│ React Desktop UI │ +│ ├─ Companion Chat Panel │ +│ ├─ Operations Chat Panel │ +│ ├─ Diagnostic Review │ +│ ├─ File Transfer Review │ +│ └─ Settings / Permissions │ +└───────────────────────┬──────────────────────┘ + │ typed Tauri IPC +┌───────────────────────▼──────────────────────┐ +│ Application Services │ +│ ├─ ConversationApplicationService │ +│ ├─ MultiConnectionApplicationService │ +│ ├─ LocalActionApplicationService │ +│ ├─ VoiceApplicationService │ +│ └─ GameCompanionApplicationService │ +└───────────────────────┬──────────────────────┘ + │ +┌───────────────────────▼──────────────────────┐ +│ Rust Desktop Core │ +│ ├─ MultiConnectionManager │ +│ │ ├─ Companion Gateway Client │ +│ │ └─ Operations Gateway Client │ +│ ├─ LocalPolicyEngine │ +│ ├─ DiagnosticService │ +│ ├─ FileTransactionService │ +│ ├─ NativeWindowsService │ +│ ├─ SecureCredentialService │ +│ ├─ SQLite Repository │ +│ ├─ Diagnostics / Logging │ +│ └─ Updater / Lifecycle │ +└──────────────┬───────────────────┬───────────┘ + │ │ + REST + SSE A REST + SSE B + │ │ +┌──────────────▼──────┐ ┌────────▼────────────┐ +│ AstrBot Companion │ │ AstrBot Operations │ +│ Gateway │ │ Gateway │ +└─────────────────────┘ └─────────────────────┘ +``` + +--- + +## 6. 模块职责边界 + +### 6.1 UI 层 + +只负责展示和收集用户操作。 + +不得: + +- 直接请求 AstrBot; +- 直接执行本机工具; +- 直接读取凭据; +- 根据服务端参数绕过确认。 + +### 6.2 Application Services + +负责把 UI 意图转换成领域操作: + +```text +发送消息 +切换实例 +打开双面板 +开始诊断 +批准工具操作 +取消文件事务 +``` + +不包含 Windows API 和网络实现。 + +### 6.3 MultiConnectionManager + +负责两个连接槽位: + +- 创建和销毁 GatewayClient; +- 管理连接状态; +- 管理 SSE; +- 路由入站事件; +- 限制最多两个活动连接; +- 保证实例切换不混淆事件; +- 网络恢复后分别重连。 + +### 6.4 GatewayClient + +每个连接配置对应一个独立客户端实例。 + +GatewayClient 只描述稳定接口,不依赖 AstrBot 内部实现。 + +### 6.5 LocalPolicyEngine + +负责判断服务端工具提案是否允许进入执行流程。 + +判断内容包括: + +- 发起请求的 `profile_id` 是否为运维实例; +- 服务器身份是否与已绑定指纹一致; +- 工具是否在白名单; +- 路径是否在授权范围; +- 是否访问敏感目录; +- 是否需要用户确认; +- 请求是否过期; +- 是否与另一个文件事务冲突。 + +### 6.6 DiagnosticService + +负责只读诊断采集和脱敏。 + +### 6.7 FileTransactionService + +负责 NAS 文件计划、复制、校验、提交、恢复和回滚。 + +--- + +## 7. 双 AstrBot 连接设计 + +### 7.1 连接槽位 + +```typescript +export type ActiveSlotKind = "companion" | "operations"; + +export interface ActiveConnectionSlot { + slot: ActiveSlotKind; + profileId: string | null; + state: ConnectionState; + activeConversationId?: string; + unreadCount: number; + lastEventId?: string; + lastConnectedAt?: string; +} +``` + +规则: + +- 一个 Profile 同时只能占用一个槽位; +- 一个槽位同一时刻只有一个 Profile; +- 切换槽位 Profile 前先停止该槽位的感知会话; +- 运维工具操作执行中禁止切换运维 Profile; +- 陪伴槽位断线不影响运维槽位; +- 运维槽位断线不影响陪伴槽位。 + +### 7.2 Profile 角色 + +```typescript +export type AstrBotProfileRole = + | "companion" + | "operations" + | "general"; +``` + +- `companion`:默认不允许本机工具; +- `operations`:可以申请本机诊断工具; +- `general`:用户可放入任一槽位,但本机工具默认关闭。 + +角色本身不是安全授权。真正授权仍由 `LocalToolPolicy` 决定。 + +### 7.3 UI 布局 + +支持三种布局: + +```typescript +export type ChatLayoutMode = + | "split" + | "single-with-tabs" + | "focus-companion" + | "focus-operations"; +``` + +#### Split 模式 + +```text +┌──────────────────────┬──────────────────────┐ +│ 陪伴 AstrBot │ 运维 AstrBot │ +│ 聊天 / 主动消息 │ 诊断 / 文件操作 │ +│ │ │ +└──────────────────────┴──────────────────────┘ +``` + +适合宽屏和同时观察。 + +#### Single with Tabs 模式 + +```text +[陪伴 2] [运维 1] + +当前实例对话区 +``` + +适合窗口较窄或游戏时使用。 + +### 7.4 消息来源识别 + +所有消息必须绑定: + +```text +profile_id +slot +server_instance_id +conversation_id +message_id +``` + +通知必须显示实例名称,例如: + +```text +[小夜·陪伴] 你已经玩两个小时了,要不要休息一下? +[家用运维] NAS 文件复制已完成,共 42 个文件。 +``` + +### 7.5 多实例数据隔离 + +本地唯一键建议: + +```text +(profile_id, conversation_id, message_id) +``` + +不得只以 `conversation_id` 或 `message_id` 作为全局唯一键。 + +所有本地缓存、Outbox、事件游标、附件和诊断记录都必须带 `profile_id`。 + +--- + +## 8. 连接协议与通信方式 + +### 8.1 MVP 建议:REST + SSE + +每个活动 Profile 独立维护: + +```text +GatewaySession +├─ REST Client +├─ SSE Event Stream +├─ Authentication State +├─ Retry State +├─ last_event_id +└─ Deduplication Cache +``` + +### 8.2 REST 用途 + +```text +GET /desktop/v1/health +GET /desktop/v1/server-info +GET /desktop/v1/capabilities +POST /desktop/v1/devices/register +POST /desktop/v1/auth/login +POST /desktop/v1/auth/refresh +POST /desktop/v1/auth/revoke +GET /desktop/v1/conversations +GET /desktop/v1/conversations/{conversation_id}/messages +POST /desktop/v1/messages +POST /desktop/v1/messages/{request_id}/stop +POST /desktop/v1/attachments +POST /desktop/v1/events/{event_id}/ack +POST /desktop/v1/local-actions/{action_id}/accepted +POST /desktop/v1/local-actions/{action_id}/rejected +POST /desktop/v1/local-actions/{action_id}/progress +POST /desktop/v1/local-actions/{action_id}/result +POST /desktop/v1/context-events +``` + +### 8.3 SSE 用途 + +```text +GET /desktop/v1/events/stream +``` + +支持: + +- 文本流式输出; +- 消息结束; +- 主动消息; +- 简化 Agent 状态; +- 工具状态; +- 本机工具提案; +- 文件计划建议; +- TTS 准备完成; +- 游戏陪伴事件; +- 服务端能力变化; +- 错误和兼容性事件。 + +### 8.4 通用事件信封 + +```typescript +export interface GatewayEventEnvelope { + protocolVersion: string; + eventType: string; + eventId: string; + requestId?: string; + profileId?: string; + serverInstanceId: string; + conversationId?: string; + messageId?: string; + sessionId?: string; + timestamp: string; + sequence?: number; + payload: T; +} +``` + +客户端接收到事件后,必须以当前连接对象绑定的 `profile_id` 为准,不能信任服务端自行声明的本地 Profile ID。 + +### 8.5 双连接事件路由 + +```text +SSE Stream A + ↓ bind profile_A +Event Router + ↓ +Companion Store + +SSE Stream B + ↓ bind profile_B +Event Router + ↓ +Operations Store +``` + +不得把两个 SSE Stream 合并后再靠 `conversation_id` 推断来源。 + +### 8.6 SSE 重连 + +每个连接单独采用: + +```text +1s → 2s → 4s → 8s → 15s → 30s +``` + +带随机抖动。 + +重连携带: + +```text +Last-Event-ID +client_id +device_id +``` + +客户端使用 `event_id` 去重,服务端短期保存未 ACK 的重要事件。 + +### 8.7 WebSocket 的后续使用范围 + +只在以下场景增加: + +- 连续全双工语音; +- 边说边识别; +- 服务端打断 TTS; +- 高频游戏事件; +- 亚秒级互动。 + +普通文字、诊断和文件事务不需要 WebSocket。 + +--- + +## 9. GatewayClient 接口 + +```typescript +export interface CompanionGatewayClient { + connect(profileId: string): Promise; + disconnect(): Promise; + + getServerInfo(): Promise; + getCapabilities(): Promise; + + listConversations(): Promise; + getConversationMessages( + conversationId: string, + cursor?: string + ): Promise; + + sendMessage(request: SendMessageRequest): Promise; + stopGeneration(requestId: string): Promise; + + uploadAttachment(request: UploadAttachmentRequest): Promise; + + sendVoiceTurn(request: VoiceTurnRequest): Promise; + + startCompanionMode( + request: StartCompanionModeRequest + ): Promise; + + stopCompanionMode(sessionId: string): Promise; + + sendContextEvent(event: ContextEvent): Promise; + + subscribeEvents( + options: EventSubscriptionOptions + ): AsyncIterable; + + acknowledgeEvent(eventId: string): Promise; + + submitLocalActionDecision( + decision: LocalActionDecision + ): Promise; + + submitLocalActionProgress( + progress: LocalActionProgress + ): Promise; + + submitLocalActionResult( + result: LocalActionResult + ): Promise; +} +``` + +首版只实现: + +```text +AstrBotCompanionGatewayAdapter +MockGatewayAdapter +``` + +Mock 仅用于开发和测试,不进入正式连接列表。 + +--- + +## 10. 连接配置数据模型 + +```typescript +export interface ConnectionProfile { + id: string; + displayName: string; + role: AstrBotProfileRole; + + baseUrl: string; + eventStreamUrl?: string; + + authenticationType: "device-token" | "api-key"; + credentialReference?: string; + + allowInsecureHttp: boolean; + pinnedCertificateFingerprint?: string; + + autoConnectSlot?: ActiveSlotKind; + autoConnect: boolean; + + serverInstanceId?: string; + serverVersion?: string; + protocolVersion?: string; + + localToolPolicyId?: string; + + lastConnectedAt?: string; + createdAt: string; + updatedAt: string; +} +``` + +### 10.1 多连接规则 + +- 可保存多个 Profile; +- 最多两个 `autoConnect=true`; +- 两个自动连接 Profile 的 `autoConnectSlot` 不得相同; +- 相同 `serverInstanceId` 被添加两次时提示用户; +- 相同地址但证书或服务端实例 ID 改变时,要求重新确认; +- 删除 Profile 时默认保留聊天缓存选项,但删除凭据; +- 用户可选择同时删除该 Profile 的所有本地数据。 + +--- + +## 11. 本机电脑诊断系统 + +### 11.1 能力范围 + +电脑诊断可以读取: + +- 用户明确选择的日志文件; +- 用户明确选择的配置文件; +- 已知软件的标准日志目录; +- 当前报错窗口标题和 UI Automation 文本; +- 用户授权的单次窗口截图; +- 相关进程信息; +- 最近相关 Windows 事件日志; +- 端口、服务、磁盘、网络和 DNS 状态; +- Docker 容器状态与用户选定的日志; +- 文件存在性和权限状态。 + +### 11.2 不允许默认读取 + +- 浏览器密码和 Cookie; +- Credential Manager 内容; +- SSH 私钥; +- 完整用户目录; +- 聊天数据库; +- 密码管理器; +- 内存转储全文; +- 与当前问题无关的个人文件; +- 其他 Windows 用户的数据。 + +### 11.3 DiagnosticService + +```text +DiagnosticService +├─ ForegroundWindowInspector +├─ UIAutomationReader +├─ SelectedWindowCapture +├─ ProcessInspector +├─ EventLogReader +├─ FileReader +├─ ConfigParser +├─ LogCollector +├─ PortInspector +├─ NetworkInspector +├─ ServiceInspector +├─ RedactionEngine +└─ DiagnosticBundleBuilder +``` + +### 11.4 支持的首批格式 + +```text +.log +.txt +.json +.yaml / .yml +.toml +.ini +.xml +.env(强制脱敏) +``` + +### 11.5 文件读取策略 + +默认: + +- 先读取元数据; +- 日志优先读取尾部; +- 按错误时间截取上下文; +- 限制单文件最大读取量; +- 二进制文件不直接读取; +- 用户可预览将发送的内容; +- 上传前执行自动脱敏。 + +### 11.6 脱敏规则 + +字段名匹配: + +```text +token +api_key +apikey +secret +password +passwd +private_key +cookie +authorization +refresh_token +access_token +``` + +值模式匹配: + +- Bearer Token; +- 常见 API Key; +- PEM 私钥; +- URL 中用户名和密码; +- 数据库连接串密码; +- NAS 凭据。 + +敏感字段发送形式: + +```json +{ + "api_key_present": true, + "api_key_length": 48, + "api_key_value": "[REDACTED]" +} +``` + +### 11.7 诊断适配器 + +支持针对常用软件扩展: + +```text +DiagnosticAdapter +├─ AstrBotAdapter +├─ DockerAdapter +├─ ComfyUIAdapter +├─ BlenderAdapter +├─ SynologyConnectionAdapter +└─ GenericWindowsAppAdapter +``` + +专用适配器只封装日志位置和安全检查,不获得无限文件权限。 + +--- + +## 12. 本机工具提案与执行安全 + +### 12.1 信任模型 + +```text +用户消息:可信意图来源 +服务端模型:不可信操作建议来源 +屏幕内容:不可信数据 +文件内容:不可信数据 +本地策略引擎:最终授权边界 +用户确认:写操作最终授权 +``` + +### 12.2 本地操作提案 + +```typescript +export interface LocalActionProposal { + actionId: string; + profileId: string; + toolName: string; + reason: string; + riskLevel: "read" | "reversible-write" | "destructive"; + arguments: Record; + requestedAt: string; + expiresAt: string; + requiresApproval: boolean; +} +``` + +### 12.3 权限等级 + +#### L0:低敏只读 + +可根据用户开启的“自动诊断”策略执行: + +- 客户端版本; +- 系统版本; +- 磁盘空间; +- AstrBot 连接测试; +- NAS 可达性; +- 客户端自身日志。 + +#### L1:受控只读 + +需用户发起或会话级授权: + +- 当前窗口文字; +- 指定窗口截图; +- 指定应用日志; +- 指定配置; +- Windows 事件日志; +- 指定目录文件列表。 + +#### L2:可恢复写操作 + +必须显示计划并确认: + +- 创建目录; +- 复制文件; +- 重命名; +- NAS 归类; +- 源文件移入回收站; +- 修改用户级非敏感配置。 + +#### L3:破坏性或系统级操作 + +MVP 不实现: + +- 永久删除; +- 覆盖系统文件; +- 修改注册表; +- 修改防火墙; +- 安装驱动; +- 管理员命令; +- 格式化磁盘。 + +### 12.4 运维实例专属限制 + +`tool.proposal` 只有在以下条件全部满足时才进入 UI: + +```text +事件来自 operations slot +Profile 角色允许运维 +server_instance_id 匹配 +证书指纹或已确认身份匹配 +LocalToolPolicy 允许该工具 +请求未过期 +``` + +陪伴实例发来的本机工具请求直接拒绝,并记录安全审计事件。 + +--- + +## 13. NAS 文件整理与事务系统 + +### 13.1 NAS 目标模型 + +```typescript +export interface NasTarget { + id: string; + displayName: string; + uncPath: string; + credentialReference?: string; + allowedDestinations: string[]; + conflictPolicy: "ask" | "rename" | "skip"; + verifyAfterCopy: boolean; + createdAt: string; + updatedAt: string; +} +``` + +### 13.2 文件事务流程 + +```text +用户选择源文件或目录 + ↓ +客户端只读取元数据 + ↓ +生成归类计划 + ↓ +用户预览并确认 + ↓ +复制到 NAS 临时文件 + ↓ +大小和哈希校验 + ↓ +原子重命名为目标文件 + ↓ +记录事务清单 + ↓ +源文件保留 / 回收站 / 删除(按用户选择) +``` + +### 13.3 禁止直接 Move + +跨本机与 NAS 操作必须采用: + +```text +copy → verify → commit → source cleanup +``` + +NAS 断线时不得删除源文件。 + +### 13.4 FileTransferPlan + +```typescript +export interface FileTransferPlan { + planId: string; + profileId: string; + sourceSelectionId: string; + nasTargetId: string; + items: FileTransferPlanItem[]; + totalBytes: number; + conflictCount: number; + warningCount: number; + sourceCleanupPolicy: "keep" | "recycle"; + expiresAt: string; +} +``` + +```typescript +export interface FileTransferPlanItem { + sourcePathToken: string; + displaySourcePath: string; + destinationRelativePath: string; + sizeBytes: number; + categoryReason: string; + conflictAction: "copy" | "rename" | "skip" | "ask"; +} +``` + +服务端不应接收可任意拼接的完整本地路径。客户端使用短期 `sourcePathToken` 映射到用户选择的真实路径。 + +### 13.5 自动分类阶段 + +#### MVP + +- 文件名; +- 扩展名; +- 创建和修改时间; +- 大小; +- 来源目录; +- 用户定义规则。 + +#### 后续 + +- 图片缩略图分析; +- PDF 和 Office 标题提取; +- 媒体元数据; +- 文档摘要; +- 项目名称识别。 + +内容分析必须单独提示用户。 + +--- + +## 14. 语音、游戏与主动消息边界 + +### 14.1 语音 MVP + +```text +按键录音 +→ 上传音频 +→ STT +→ 文本回复 +→ 可选 TTS +``` + +麦克风默认只绑定当前聚焦实例。 + +若当前为双面板: + +- 按住说话时显示目标实例; +- 支持快捷键切换目标; +- 不允许同一段音频同时发送给两个实例,除非用户显式选择“同时发送”。 + +### 14.2 游戏陪伴 + +游戏模式默认绑定 Companion Slot。 + +运维 Slot 不自动接收游戏截图、窗口状态或游戏事件。 + +### 14.3 主动消息 + +两个实例都可以主动推送,但: + +- 陪伴实例使用普通陪伴通知; +- 运维实例使用操作与告警通知; +- 通知必须标明来源; +- 文件操作完成通知只能来自运维实例; +- 通知点击后打开对应槽位和会话。 + +--- + +## 15. 本地存储与敏感凭据 + +### 15.1 SQLite 保存 + +- ConnectionProfile 非敏感部分; +- 活动槽位; +- 会话缓存; +- 消息缓存; +- SSE 游标; +- 未确认事件; +- 工具提案; +- 诊断记录摘要; +- 文件事务清单; +- NAS 目标非敏感部分; +- 设置与迁移版本。 + +### 15.2 Credential Manager 保存 + +- Access Token; +- Refresh Token; +- API Key; +- NAS 用户名和密码; +- 设备密钥引用; +- 其他连接凭据。 + +SQLite 只保存: + +```text +credential_reference +``` + +### 15.3 Profile 数据隔离 + +所有表中涉及服务端数据的记录必须带: + +```text +profile_id +server_instance_id +``` + +本机诊断和文件事务还要带: + +```text +initiating_profile_id +initiating_slot +``` + +--- + +## 16. 状态机 + +### 16.1 每个连接槽位的状态机 + +```text +DISCONNECTED + ↓ +CONNECTING + ↓ +AUTHENTICATING + ↓ +SYNCING + ↓ +CONNECTED +``` + +异常状态: + +```text +RECONNECTING +AUTH_EXPIRED +INCOMPATIBLE +SERVER_UNAVAILABLE +OFFLINE +CERTIFICATE_CHANGED +FATAL_ERROR +``` + +两个槽位状态独立。 + +### 16.2 应用运行状态 + +```text +FOREGROUND +BACKGROUND_TRAY +LOCKED +UPDATING +EXITING +``` + +### 16.3 本地操作状态机 + +```text +PROPOSED + ↓ +POLICY_CHECKING + ├─ REJECTED_BY_POLICY + ↓ +AWAITING_USER_APPROVAL + ├─ REJECTED_BY_USER + ↓ +APPROVED + ↓ +EXECUTING + ├─ PAUSED + ├─ FAILED + ├─ ROLLING_BACK + ↓ +COMPLETED +``` + +### 16.4 文件事务状态机 + +```text +PLANNED + ↓ +APPROVED + ↓ +COPYING + ↓ +VERIFYING + ↓ +COMMITTING + ↓ +SOURCE_CLEANUP + ↓ +COMPLETED +``` + +异常: + +```text +PAUSED_NETWORK_LOST +CONFLICT_WAITING +VERIFY_FAILED +ROLLBACK_REQUIRED +CANCELLED +FAILED +``` + +--- + +## 17. 推荐目录结构 + +```text +astrbot-companion-desktop/ +├─ apps/ +│ └─ desktop/ +│ ├─ src/ +│ │ ├─ app/ +│ │ ├─ features/ +│ │ │ ├─ chat/ +│ │ │ ├─ connections/ +│ │ │ ├─ dual-panel/ +│ │ │ ├─ voice/ +│ │ │ ├─ game-companion/ +│ │ │ ├─ diagnostics/ +│ │ │ ├─ local-actions/ +│ │ │ ├─ file-transfer/ +│ │ │ ├─ notifications/ +│ │ │ └─ settings/ +│ │ ├─ application/ +│ │ ├─ stores/ +│ │ ├─ shared/ +│ │ └─ types/ +│ └─ src-tauri/ +│ ├─ src/ +│ │ ├─ app/ +│ │ ├─ connection/ +│ │ │ ├─ manager.rs +│ │ │ ├─ slot.rs +│ │ │ ├─ rest_client.rs +│ │ │ ├─ sse_client.rs +│ │ │ └─ retry.rs +│ │ ├─ gateway/ +│ │ ├─ diagnostics/ +│ │ ├─ local_policy/ +│ │ ├─ local_tools/ +│ │ ├─ file_transactions/ +│ │ ├─ nas/ +│ │ ├─ secure_store/ +│ │ ├─ database/ +│ │ ├─ windows/ +│ │ ├─ tray/ +│ │ ├─ updater/ +│ │ └─ logging/ +│ └─ migrations/ +├─ packages/ +│ ├─ protocol-types/ +│ ├─ ui-components/ +│ └─ test-fixtures/ +└─ docs/ +``` + +--- + +## 18. MVP 范围 + +### 18.1 MVP-A:客户端与双连接基础 + +必须: + +- Tauri 2 Windows 客户端; +- 多个 Profile; +- 两个活动槽位; +- 两个独立 REST + SSE 连接; +- 双面板和标签切换; +- 独立会话与未读状态; +- 安全凭据; +- 托盘、单实例和基础更新; +- 基础日志和连接诊断。 + +### 18.2 MVP-B:文字陪伴与主动消息 + +必须: + +- 文本发送; +- 流式回复; +- 停止生成; +- 历史消息; +- 主动消息; +- 来源明确的通知; +- 陪伴实例默认绑定游戏模式。 + +### 18.3 MVP-C:只读电脑诊断 + +必须: + +- 当前前台窗口信息; +- 用户选择的窗口截图; +- 指定日志和配置文件读取; +- Windows 事件日志查询; +- 进程、端口、服务、磁盘和网络检查; +- 自动脱敏; +- 用户预览诊断包; +- 运维实例专属权限。 + +### 18.4 MVP-D:安全 NAS 文件归档 + +建议纳入首个可用正式版本,但晚于只读诊断: + +- NAS 目标登记; +- Credential Manager 凭据; +- 用户选择源文件; +- 基于元数据的归类计划; +- Dry Run; +- 复制、校验、提交; +- 冲突处理; +- 网络断开暂停; +- 源文件保留或回收站; +- 操作审计。 + +### 18.5 MVP 暂不实现 + +- 无限活动连接; +- 同一实例多个本机工具并行写操作; +- 任意 Shell; +- 自动 UAC; +- 永久删除; +- 实时全双工语音; +- 唤醒词; +- 高频视频分析; +- 项目工作区; +- Codex 集成; +- macOS 和 Linux 正式支持。 + +--- + +## 19. 分阶段开发顺序 + +### 阶段 0:高风险验证 + +1. Tauri 双 SSE 长连接后台运行; +2. Windows Credential Manager; +3. UI Automation 读取标准弹窗; +4. Windows Event Log 查询; +5. UNC 路径复制和断线恢复; +6. SQLite 双 Profile 隔离。 + +### 阶段 1:项目骨架 + +- React + Tauri; +- IPC 类型; +- SQLite 迁移; +- Profile CRUD; +- 单实例和托盘。 + +### 阶段 2:双连接管理 + +- MultiConnectionManager; +- Companion / Operations Slot; +- REST Client; +- SSE Client; +- 重连和去重; +- 双面板状态。 + +### 阶段 3:聊天 + +- 会话; +- 消息; +- 流式输出; +- 主动消息; +- 通知跳转。 + +### 阶段 4:安全策略 + +- LocalPolicyEngine; +- Profile 权限; +- 工具白名单; +- 用户确认卡片; +- 操作审计。 + +### 阶段 5:电脑诊断 + +- 窗口和进程; +- 日志、配置; +- 事件日志; +- 网络和端口; +- 脱敏与诊断包。 + +### 阶段 6:NAS 文件事务 + +- NasTarget; +- 文件计划; +- 复制、哈希、提交; +- 冲突和暂停恢复; +- 回收站策略。 + +### 阶段 7:语音和游戏陪伴 + +- 按键说话; +- TTS; +- 游戏窗口绑定; +- 时长事件; +- 手动和低频截图。 + +### 阶段 8:发布 + +- Updater; +- 签名; +- 崩溃恢复; +- 安装包; +- Beta 验收。 + +--- + +## 20. 风险与规避措施 + +| 风险 | 严重度 | 概率 | 规避方案 | MVP 必须解决 | +|---|---:|---:|---|---| +| 两个实例消息混淆 | 高 | 中 | 所有记录绑定 profile_id;每条 SSE 在连接层绑定来源 | 是 | +| 陪伴实例越权申请工具 | 高 | 中 | 本地按槽位、Profile、服务端身份拒绝 | 是 | +| 服务端被入侵后控制电脑 | 高 | 低到中 | 工具白名单、本地策略、用户确认、无任意 Shell | 是 | +| 日志泄露 Token | 高 | 中 | 本地脱敏、预览、敏感文件禁止默认读取 | 是 | +| NAS 断线导致源文件丢失 | 高 | 中 | copy-verify-commit,不直接 move | 是 | +| 同名文件覆盖 | 中 | 高 | ask/rename/skip;默认不覆盖 | 是 | +| 双 SSE 占用或重连风暴 | 中 | 中 | 分别退避、抖动、网络状态统一协调 | 是 | +| 同一个服务被配置两次 | 中 | 中 | server_instance_id 检测和提示 | 是 | +| UI Automation 读不到自绘窗口 | 中 | 中 | 单次窗口截图降级 | 否,但需降级 | +| 管理员程序无法读取 | 中 | 中 | 不常驻管理员;提示权限边界 | 是 | +| Windows Defender 误报 | 中 | 中 | 代码签名、不注入、不 Hook、透明权限 | 正式版 | +| 数据库异常退出损坏 | 高 | 低 | WAL、事务、迁移备份、启动恢复 | 是 | +| 两实例同时发声 | 中 | 中 | 全局音频仲裁器、当前实例优先 | 是 | + +--- + +## 21. 验收标准 + +### 21.1 双实例 + +- 可以保存至少 5 个 Profile; +- 可选择两个不同 Profile 同时连接; +- 两个实例分别显示连接状态; +- 任一实例断线不影响另一个实例; +- 可并排显示两个对话框; +- 可切换单面板标签; +- 主动消息正确进入来源面板; +- 通知点击后进入正确会话; +- 两个实例相同 conversation_id 时不混淆数据。 + +### 21.2 权限隔离 + +- 陪伴实例请求本机工具时客户端拒绝; +- 运维实例请求只读工具时显示采集范围; +- 写操作未确认不得执行; +- 远程 payload 不能传入任意本地路径执行; +- 工具请求过期后不能再次批准; +- 服务端身份改变后工具权限自动冻结。 + +### 21.3 电脑诊断 + +- 能读取标准错误弹窗文字; +- 读取失败时可单次选择窗口截图; +- 能读取用户选择的日志与配置; +- 能查询指定进程相关事件日志; +- Token、密码和私钥被脱敏; +- 用户可以预览实际发送内容; +- 诊断结束不保留原始截图,除非用户选择保存。 + +### 21.4 NAS 文件事务 + +- 能登记 UNC 共享; +- 凭据不进入 SQLite 明文字段; +- 复制前显示完整计划; +- NAS 断线时源文件不丢失; +- 校验失败时不执行源清理; +- 同名冲突不会静默覆盖; +- 操作结束生成事务报告; +- 用户选择回收站时可以恢复源文件。 + +### 21.5 稳定性 + +- 主窗口关闭到托盘后两个连接继续在线; +- 网络切换后分别恢复 SSE; +- 客户端重启后恢复活动槽位和未完成文件事务; +- 日志不包含完整 Token、密码、私钥、聊天全文或截图。 + +--- + +## 22. 需要其他专题配合的接口清单 + +### 22.1 AstrBot Gateway 专题 + +需要提供: + +- 设备注册; +- Token 刷新; +- ServerInfo; +- Capabilities; +- 会话和消息接口; +- SSE 事件流; +- 主动消息 ACK; +- 本机工具提案协议; +- 诊断结果回传协议; +- 服务端实例唯一 ID。 + +### 22.2 聊天专题 + +需要确认: + +- 会话数据结构; +- 消息内容块; +- 附件格式; +- 流式消息合并规则; +- 停止生成行为。 + +### 22.3 语音专题 + +需要确认: + +- STT 和 TTS 提供者; +- 音频格式; +- 目标实例选择; +- 两实例语音仲裁。 + +### 22.4 游戏陪伴专题 + +需要确认: + +- 游戏模式事件; +- 截图频率; +- 捕获权限提示; +- 默认绑定 Companion Slot。 + +### 22.5 本机助手专题 + +需要进一步细化: + +- 首批 DiagnosticAdapter; +- 本机工具注册表; +- 每项工具风险等级; +- 日志脱敏规则测试集; +- 文件分类规则; +- NAS 恢复和回滚细节。 + +--- + +## 23. 最终决策摘要 + +```text +项目定位: +AstrBot Windows 陪伴与本机助手客户端 + +桌面框架: +Tauri 2 + React + TypeScript + Rust + +通信: +MVP 使用 REST + SSE +连续语音等后续使用 WebSocket + +多实例: +保存多个 Profile +最多两个活动连接 +陪伴槽位 + 运维槽位 +支持双面板和切换 + +电脑诊断: +允许读取用户授权的文件、配置、日志和系统诊断信息 +本地脱敏后发送给运维 AstrBot + +本机操作: +服务端只提交提案 +客户端本地策略引擎最终裁决 +写操作需要用户确认 +不提供任意 Shell + +NAS 文件整理: +copy → verify → commit → source cleanup +禁止直接跨设备 Move + +权限: +陪伴实例默认无本机工具权限 +运维实例按白名单申请本机工具 +``` + +该方案同时满足: + +- 日常陪伴; +- 运维问题咨询; +- 两个 AstrBot 同时在线; +- 双对话框或快速切换; +- 电脑日志和配置诊断; +- 安全的 NAS 文件归档; +- 不重新引入项目工作区和 Codex 开发平台复杂度。 diff --git a/docs/02_Codex_Implementation_Tasks.md b/docs/02_Codex_Implementation_Tasks.md new file mode 100644 index 0000000..25ed884 --- /dev/null +++ b/docs/02_Codex_Implementation_Tasks.md @@ -0,0 +1,291 @@ +# 01|Codex 实施任务清单:双 AstrBot 与本机助手 + +> 配套文档:`01_桌面客户端双实例陪伴与本机运维系统.md` + +--- + +## 执行原则 + +1. 每个批次必须能独立运行和测试。 +2. 不允许先实现任意 Shell 再补安全限制。 +3. 所有服务端事件必须在 Rust 连接层绑定 `profile_id`。 +4. 所有本机写操作必须经过 LocalPolicyEngine。 +5. 未通过高风险 Spike 前,不进入完整 UI 开发。 + +--- + +## Batch 0:技术 Spike + +### 0.1 双 SSE 后台连接 + +目标: + +- Tauri 同时维护两个 SSE; +- 主窗口隐藏后继续收事件; +- 分别断线和重连; +- 事件不串流。 + +验收: + +- Mock A 每秒发 A 事件; +- Mock B 每秒发 B 事件; +- 连续 30 分钟无串流; +- 单独关闭任一服务不影响另一个。 + +### 0.2 Windows Credential Manager + +目标: + +- 写入、读取、删除测试凭据; +- SQLite 只保存引用。 + +### 0.3 UI Automation 与窗口截图 + +目标: + +- 读取标准 Windows 弹窗文字; +- 读不到时选择窗口截图; +- 不要求客户端常驻管理员权限。 + +### 0.4 Windows Event Log + +目标: + +- 按 Provider、时间范围和进程筛选; +- 返回结构化摘要; +- 不导出无关日志全文。 + +### 0.5 NAS 文件事务 + +目标: + +- UNC 路径复制; +- 中途断网; +- 恢复复制; +- SHA-256 校验; +- 校验成功后再清理源。 + +--- + +## Batch 1:工程骨架 + +- 创建 Tauri 2 + React + TypeScript; +- 建立 workspace; +- 建立 IPC 类型包; +- 引入 SQLite 和迁移; +- 实现日志脱敏基础库; +- 实现托盘、单实例和退出流程; +- 建立单元测试与 Playwright。 + +完成条件: + +- 应用可启动、隐藏到托盘并恢复; +- SQLite 自动迁移; +- Rust 与 TypeScript IPC 类型可校验。 + +--- + +## Batch 2:Profile 与双连接槽位 + +实现: + +- ConnectionProfile CRUD; +- Companion Slot; +- Operations Slot; +- 最多两个活动连接限制; +- 自动连接配置校验; +- Profile 切换保护; +- server_instance_id 重复提示。 + +测试: + +- 保存 5 个 Profile; +- 任意两个进入不同槽位; +- 禁止同 Profile 同时占两个槽位; +- 运维任务运行时禁止切换 Operations Profile。 + +--- + +## Batch 3:REST + SSE GatewayClient + +实现: + +- REST Client; +- SSE Client; +- Token 刷新; +- Last-Event-ID; +- 指数退避和抖动; +- 事件去重; +- 两个连接独立状态机; +- MockGatewayAdapter。 + +测试: + +- A/B 流式消息同时输出; +- 单连接断网恢复; +- 重放相同 event_id 不产生重复消息; +- Token 过期只影响对应 Profile。 + +--- + +## Batch 4:双对话框 UI + +实现: + +- Split 布局; +- Single with Tabs; +- Focus Companion; +- Focus Operations; +- 各自会话列表; +- 未读数量; +- 来源标签; +- 通知跳转。 + +测试: + +- 两实例相同 conversation_id 不串数据; +- 切换布局不丢流式内容; +- 通知点击打开正确槽位。 + +--- + +## Batch 5:本地策略引擎 + +实现: + +- LocalActionProposal; +- 工具注册表; +- L0-L3 风险等级; +- Profile 角色检查; +- Operations Slot 检查; +- 服务器身份检查; +- 请求过期; +- 用户确认卡片; +- 审计日志。 + +必须测试: + +- Companion Profile 的工具提案必定拒绝; +- 未确认写操作不能执行; +- 任意未知 tool_name 拒绝; +- 任意路径字符串不能绕过路径授权。 + +--- + +## Batch 6:只读诊断服务 + +实现: + +- ForegroundWindowInspector; +- UIAutomationReader; +- SelectedWindowCapture; +- ProcessInspector; +- EventLogReader; +- PortInspector; +- ServiceInspector; +- NetworkInspector; +- FileReader; +- ConfigParser; +- LogCollector; +- DiagnosticBundleBuilder。 + +脱敏: + +- Token; +- API Key; +- Password; +- Cookie; +- Authorization; +- PEM 私钥; +- URL 凭据; +- 数据库连接串。 + +测试: + +- 使用含假 Token 的 fixture; +- 发送前输出不得包含原值; +- 用户可以预览诊断包; +- 截图默认诊断后删除。 + +--- + +## Batch 7:NAS 与文件事务 + +实现: + +- NasTarget; +- Credential Manager 凭据; +- 用户文件选择; +- sourcePathToken; +- 元数据分类; +- Dry Run; +- 临时文件; +- 校验; +- 原子提交; +- 冲突处理; +- 网络中断暂停; +- 事务恢复; +- 源文件保留或回收站。 + +测试: + +- NAS 断网不删除源; +- 哈希失败不提交; +- 同名文件不覆盖; +- 重启客户端后可以恢复未完成事务。 + +--- + +## Batch 8:语音、游戏和主动消息 + +实现: + +- 按键说话; +- 目标实例选择; +- TTS 音频仲裁; +- 游戏模式默认绑定 Companion Slot; +- 游戏开始、结束和时长事件; +- 主动消息来源区分。 + +--- + +## Batch 9:稳定性与发布 + +- 自动更新; +- Windows 签名; +- 崩溃恢复; +- 诊断包导出; +- 日志滚动; +- 数据迁移备份; +- Defender 误报检查; +- Beta 发布流程。 + +--- + +## 首个 Codex 执行口令 + +```text +请先阅读: +1. docs/01_桌面客户端双实例陪伴与本机运维系统.md +2. docs/01_Codex实施任务清单_双实例与本机助手.md + +本次只执行 Batch 0,不开发正式业务 UI。 + +任务: +1. 创建最小 Tauri 2 Spike 工程; +2. 实现两个独立 SSE 客户端,分别连接 Mock A 和 Mock B; +3. 每个 SSE 事件在 Rust 层绑定固定 profile_id,不采用服务端传入的 profile_id; +4. 主窗口隐藏到托盘后保持连接; +5. 单独关闭 Mock A 或 Mock B,验证另一个连接不受影响; +6. 实现各自指数退避重连和 event_id 去重; +7. 输出测试记录和资源占用结果; +8. 不实现任意 Shell、文件操作、真实 AstrBot 接入或正式聊天页面。 + +交付: +- Spike 源码; +- README; +- 自动化测试; +- 测试结果; +- 风险结论; +- 是否可以进入 Batch 1 的建议。 +```