Xboard/AGENT.md

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. 推荐命令基线

信息收集：

rg --files
rg -n "<pattern>" app config routes docs

本地运行（三进程）：

php artisan octane:start --host=0.0.0.0 --port=7001 --watch
php artisan horizon
php artisan schedule:work

质量检查：

php artisan about
php artisan migrate:status
vendor/bin/phpstan analyse --memory-limit=1G

测试（若已补齐测试）：

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. 风险与未覆盖项已明确说明。