460 行
8.9 KiB
Markdown
460 行
8.9 KiB
Markdown
# 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. 完成定义
|
||
|
||
一个任务只有同时满足以下条件才算完成:
|
||
|
||
* 功能实现完成;
|
||
* 错误路径已处理;
|
||
* 权限边界已验证;
|
||
* 测试已添加;
|
||
* 相关检查已通过;
|
||
* 文档已更新;
|
||
* 没有敏感信息泄露;
|
||
* 已使用规范提交;
|
||
* 工作区干净。
|