docs(project): add architecture and implementation specifications

这个提交存在于:
YokiiroBW 2026-07-18 20:21:19 +08:00
当前提交 5e6e8d5ca2
共有 4 个文件被更改,包括 3298 次插入 和 0 次删除

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 普通文件

文件差异内容过多而无法显示 加载差异

查看文件

@ -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 的建议。
```