docs(project): add architecture and implementation specifications
这个提交存在于:
当前提交
5e6e8d5ca2
共有 4 个文件被更改,包括 3298 次插入 和 0 次删除
460
AGENTS.md
普通文件
460
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. 完成定义
|
||||
|
||||
一个任务只有同时满足以下条件才算完成:
|
||||
|
||||
* 功能实现完成;
|
||||
* 错误路径已处理;
|
||||
* 权限边界已验证;
|
||||
* 测试已添加;
|
||||
* 相关检查已通过;
|
||||
* 文档已更新;
|
||||
* 没有敏感信息泄露;
|
||||
* 已使用规范提交;
|
||||
* 工作区干净。
|
||||
|
|
@ -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@<FORGEJO_HOST>:<FORGEJO_USER>/astrbot-desktop.git
|
||||
```
|
||||
|
||||
非标准 SSH 端口:
|
||||
|
||||
```text
|
||||
ssh://git@<FORGEJO_HOST>:<SSH_PORT>/<FORGEJO_USER>/astrbot-desktop.git
|
||||
```
|
||||
|
||||
HTTPS 备用地址:
|
||||
|
||||
```text
|
||||
http://<FORGEJO_HOST>/<FORGEJO_USER>/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/<issue-name>
|
||||
```
|
||||
|
||||
文档分支:
|
||||
|
||||
```text
|
||||
docs/<topic-name>
|
||||
```
|
||||
|
||||
## 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 的总控口令
|
||||
|
||||
使用前替换:
|
||||
|
||||
- `<LOCAL_PROJECT_PATH>`
|
||||
- `<FORGEJO_REMOTE_URL>`
|
||||
- `<FORGEJO_HOST>`
|
||||
- `<FORGEJO_REPOSITORY>`
|
||||
|
||||
---
|
||||
|
||||
你现在负责 AstrBot Windows 桌面客户端的前期工程建设和技术验证。
|
||||
|
||||
项目目录:
|
||||
|
||||
```text
|
||||
<LOCAL_PROJECT_PATH>
|
||||
```
|
||||
|
||||
Forgejo 远程仓库:
|
||||
|
||||
```text
|
||||
<FORGEJO_REMOTE_URL>
|
||||
```
|
||||
|
||||
Forgejo 仓库标识:
|
||||
|
||||
```text
|
||||
<FORGEJO_HOST>/<FORGEJO_REPOSITORY>
|
||||
```
|
||||
|
||||
项目根目录中的以下文件是权威开发依据:
|
||||
|
||||
```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
|
||||
添加 <FORGEJO_REMOTE_URL> 为 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。
|
||||
```
|
||||
1613
docs/01_Architecture_Design.md
普通文件
1613
docs/01_Architecture_Design.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 的建议。
|
||||
```
|
||||
正在加载…
添加表格
在新工单中引用