AstrBot-Desktop/AstrBot_Desktop_Codex_Forgejo_Predevelopment_Workflow.md

935 行
18 KiB
Markdown

# 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。
```