935 行
18 KiB
Markdown
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。
|
|||
|
|
```
|