AstrBot-Desktop/AGENTS.md

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