添加开发文档

AGENT.md

@@ -0,0 +1,86 @@
+# Xboard 仓库 Agent 协作规范
+
+本文给自动化代理与协作者使用，目标是提升并行效率，减少回归风险。
+
+## 1. 输出与沟通
+
+- 默认使用简体中文。
+- 先给结论，再给关键证据与改动点。
+- 复杂任务必须先给执行计划，再落地改动。
+
+## 2. 执行原则
+
+1. 质量优先：不为速度牺牲正确性与可维护性。
+2. 并行优先：能并行的信息收集与文件操作尽量并行。
+3. 最小改动：仅修改与任务直接相关的文件。
+4. 可追溯：说明改了什么、为什么改、如何验证。
+
+## 3. 并行拆分规则
+
+1. 先画依赖图，区分可并行和必须串行任务。
+2. 不允许并行写同一文件或同一区域。
+3. 收集阶段可并行，分析和冲突解决阶段串行。
+4. 每轮并行结束后先汇总再进入下一轮。
+
+## 4. 仓库事实（执行前必须知道）
+
+- 技术栈：Laravel 12 + Octane + Horizon + Redis。
+- 安装命令：`php artisan xboard:install`（交互式，强依赖 Redis 可连通）。
+- 前端资产：仓库内为已编译静态资源，不是完整前端源码仓。
+- 任务调度：依赖 `schedule:work` 或 `cron + schedule:run`。
+- 当前仓库默认无 `tests/` 与 `phpunit.xml`，测试基建可能缺失。
+
+## 5. 推荐命令基线
+
+信息收集：
+
+```bash
+rg --files
+rg -n "<pattern>" app config routes docs
+```
+
+本地运行（三进程）：
+
+```bash
+php artisan octane:start --host=0.0.0.0 --port=7001 --watch
+php artisan horizon
+php artisan schedule:work
+```
+
+质量检查：
+
+```bash
+php artisan about
+php artisan migrate:status
+vendor/bin/phpstan analyse --memory-limit=1G
+```
+
+测试（若已补齐测试）：
+
+```bash
+timeout 60s php artisan test
+```
+
+## 6. 高风险操作确认
+
+以下操作必须先得到明确确认：
+
+- 删除/批量改写文件
+- `git reset --hard`、`git checkout --`、强制回滚
+- 数据库清库、结构变更、批量数据更新
+- 调用生产环境 API 或发送敏感数据
+- 全局安装/卸载依赖
+
+## 7. 仓库特殊风险提醒
+
+- `update.sh` 含 `git reset --hard origin/master`，默认禁止直接执行。
+- `xboard:update` / `xboard:install` 可能恢复 `plugins/` 下被跟踪文件，执行前需确认是否会覆盖开发中的插件改动。
+- `compose.sample.yaml` 使用 `network_mode: host`，跨平台可用性有限，必要时改端口映射。
+
+## 8. 提交前自检清单
+
+1. 变更范围最小且与需求一致。
+2. 关键路径已验证（安装/运行/队列/调度至少一项）。
+3. 质量检查命令执行结果已记录。
+4. 风险与未覆盖项已明确说明。
+