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