8.9 KiB
AstrBot Desktop 项目开发规则
1. 项目目标
本项目开发 AstrBot Windows 桌面客户端。
当前产品范围包括:
- 双 AstrBot 实例同时在线
- 陪伴实例与运维实例
- 独立双对话框与单面板切换
- 文字聊天
- 语音交互
- 主动消息
- 游戏陪伴
- 本机只读诊断
- 受控文件整理
- NAS 安全归档
- 系统托盘、单实例、自动更新
- 安全凭据存储
- 日志与连接诊断
本项目不包含:
- 项目工作区
- IDE 或代码编辑器
- Codex 集成
- VM 开发任务交付
- Git 图形客户端
- 通用终端
- 任意 PowerShell 或 CMD 执行
- 无限制桌面控制
- 无确认的破坏性文件操作
2. 权威文档
开发前必须完整阅读:
docs/01_Architecture_Design.mddocs/02_Codex_Implementation_Tasks.md
优先级顺序:
- 本文件
AGENTS.md docs/01_Architecture_Design.mddocs/02_Codex_Implementation_Tasks.md- 当前用户明确指令
- 现有实现
如果文档之间存在冲突:
- 不要静默选择其中一个方案;
- 将冲突记录到
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 支持多个已保存连接配置,但最多同时激活两个连接槽位:
companionoperations
两个槽位必须拥有独立的:
- REST 客户端
- SSE 连接
- Token
- 重连状态
- 会话
- 消息
- 未读数量
- 主动通知
- 错误状态
所有服务端数据必须至少使用以下字段隔离:
profile_idserver_instance_idconversation_id
不得只使用 conversation_id 作为本地唯一标识。
陪伴实例默认不能调用本机运维工具。
只有被用户指定为 operations 角色的实例,才能提出本机诊断或文件操作提案。
6. 本机工具安全规则
AstrBot 发来的工具调用只是操作提案,不是可直接执行的命令。
每个操作必须经过:
- Schema 校验
- 工具白名单校验
- Profile 角色校验
- 路径范围校验
- 风险等级判断
- 用户授权判断
- 本地执行
- 结果审计
禁止实现:
execute_command(string)run_powershell(string)run_cmd(string)delete_any_path(string)write_any_registry_key(string)- 任意鼠标键盘脚本执行
必须使用参数明确、边界有限的工具。
例如:
inspect_foreground_windowquery_recent_event_logsinspect_processcheck_portcheck_network_targetread_authorized_log_fileplan_file_transferexecute_approved_file_transfer
破坏性操作不得进入首版。
7. 文件与 NAS 事务规则
跨设备文件整理不得直接执行不可恢复的 Move。
必须使用:
- 生成计划
- Dry Run
- 用户确认
- 复制至临时文件
- 校验大小
- 校验哈希
- 原子提交目标名称
- 处理源文件
- 保存操作记录
NAS 中断时必须保留源文件。
默认冲突策略为:
- 询问
- 重命名
- 跳过
不得默认覆盖。
8. 敏感信息规则
禁止将以下内容写入普通配置、SQLite 普通字段、日志、测试快照或提交记录:
- Access Token
- Refresh Token
- 密码
- API Key
- Cookie
- 私钥
- NAS 凭据
- 完整 Authorization Header
敏感信息必须保存在 Windows Credential Manager 或经过批准的安全存储中。
日志必须脱敏。
示例:
Bearer abcdefghijklmnop
只能记录为:
Bearer abcd…mnop
或:
[REDACTED]
9. Git 分支规则
采用简化的主干开发方式。
长期分支:
main:始终保持可构建、可运行- 不建立长期
develop分支
每个开发阶段从 main 创建独立分支:
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
修复分支:
fix/<简短问题名称>
文档分支:
docs/<简短主题>
禁止:
- 直接在
main上进行大型开发; - 对已共享分支执行强制推送;
- 将多个无关阶段塞入同一个提交;
- 提交构建产物、Token、密码或本地缓存。
10. 提交规则
使用 Conventional Commits:
feat(scope): description
fix(scope): description
refactor(scope): description
test(scope): description
docs(scope): description
chore(scope): description
build(scope): description
ci(scope): description
示例:
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. 阶段完成规则
每个阶段完成前必须:
- 运行格式化;
- 运行 lint;
- 运行类型检查;
- 运行 Rust 检查;
- 运行单元测试;
- 运行适用的集成测试;
- 完成生产构建;
- 更新
docs/progress.md; - 更新相关架构或协议文档;
- 创建阶段总结。
阶段未通过验收时不得合并到 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. 开发过程记录
必须维护:
docs/implementation-plan.md
docs/progress.md
docs/decisions/
CHANGELOG.md
docs/progress.md 至少记录:
- 当前阶段
- 已完成任务
- 正在进行的任务
- 未完成任务
- 阻塞问题
- 测试状态
- 当前分支
- 最近提交
- 下一步
重大技术决策使用 ADR:
docs/decisions/ADR-0001-*.md
ADR 内容包括:
- 背景
- 可选方案
- 最终选择
- 选择理由
- 代价
- 后续影响
14. 工作方式
开始编码前必须:
- 阅读权威文档;
- 检查当前仓库状态;
- 确认当前分支;
- 生成实施计划;
- 找出阻塞性不确定项;
- 先完成必要 Spike;
- 再开始正式编码。
开发过程中:
- 按任务清单顺序推进;
- 不要一次性生成整个项目;
- 每完成一个可验证增量就测试和提交;
- 可以自主处理普通实现细节;
- 不得自主扩大产品范围;
- 不得跳过高风险 Spike;
- 不得因后续功能提前过度抽象。
15. 停止条件
遇到以下情况必须停止相关修改并报告:
- 文档在安全模型上冲突;
- 需要修改 AstrBot 核心代码;
- 需要开放任意命令执行;
- 需要绕过 Windows 权限;
- 需要禁用 TLS 校验;
- 需要存储明文凭据;
- 数据库迁移可能导致数据丢失;
- 需要执行不可恢复的批量文件操作;
- 测试持续失败且原因无法确认;
- 实现会明显偏离 MVP。
普通编译错误、类型错误、测试缺失和小型设计细节不属于停止条件,应自行解决。
16. 完成定义
一个任务只有同时满足以下条件才算完成:
- 功能实现完成;
- 错误路径已处理;
- 权限边界已验证;
- 测试已添加;
- 相关检查已通过;
- 文档已更新;
- 没有敏感信息泄露;
- 已使用规范提交;
- 工作区干净。