docs(xingbang): 适配项目开发流程并建立经验驱动预审新版文档

AGENTS.md

@@ -1,8 +1,18 @@
 # AGENTS.md — mini-OpenClaw 兴邦金租 AI 评审平台
 
-> 本文件是仓库唯一事实来源,供 Codex / Claude / 其他 AI 编码代理读取。
+> 本文件是仓库开发规则的统一入口，供 Codex / Claude / 其他 AI 编码代理读取；运行事实以代码、测试和已核验记录为准。
 > **先读本文件,再动手;开发全程遵守「改动纪律」,尤其是有序验证命令。**
 
+## 项目开发流程（强制）
+
+1. 所有需求、修复、重构、UI、接口与交付工作，先读 [项目流程](docs/project-process/README.md) 和 [兴邦适配说明](docs/project-process/XINGBANG-ADAPTATION.md)，进入阶段前再读对应的 `01` 至 `08` 章节。
+2. 按「需求与规格 → 架构 → 详细设计 → UI Spec → 实现 → 验证 → 交付 → 沉淀」执行。阶段完成条件没有证据时标记未完成；可以记录后续阶段的候选设计，但不得把草案当成已过门禁并开始业务实现。
+3. 需求须有稳定的 `BR-*` / `E-*` / `AC-*` 编号；异常绑定错误码和用户文案，验收使用 Given/When/Then。编号只追加，废弃保留编号并标记 withdrawn。小改动可走流程中的轻量路径并记录理由。
+4. `docs/project-process` 正文已适配兴邦 Next.js + FastAPI 项目，按各章实际目录、契约、测试和部署要求执行；适配记录说明来源和未建设的机制。不得引用不存在的命令或把规划当实现。本文件的兴邦硬约束继续有效。
+5. 新版需求与设计入口是 [docs/v2/README.md](docs/v2/README.md)。该目录保存入库评审草案及后续基线；必须区分已实现、规划、模拟演示和真实验证，不能用文件存在证明功能已完成。
+6. 行为改动沿用本文件的测试与 `backend/venv` 要求，必须运行 `python scripts/verify.py` 并保存 `test-evidence/`。文档改动至少检查链接、编号覆盖、事实来源及 `git diff --check`；不得声称未接入的 CI、Jev 或概率模型已生效。
+7. 提交使用 Conventional Commits 类型前缀加中文一句话说明；默认分支从 Gitea 实际读取，不照搬来源项目的 `build`。备份分支只代表恢复点，不等于评审通过、合并或发布。
+
 ## ▶️ 接手当前进度(每次新对话/会话开始时先做,别当新项目从零写)
 
 > 本文件写的是**规则,不是进度**。你的进度在**代码 + git 工作区 + 会话历史**里,不在本文件里。
@@ -22,28 +32,28 @@
 
 - `src/` — **Next.js 前端**(默认端口 **3000**),页面/组件在 `src/app/`、`src/components/`
 - `backend/` — **FastAPI 后端**(默认端口 **8002**),Python + LangChain,工具在 `backend/tools/`、Agent 调度在 `backend/graph/`、API 路由在 `backend/api/`
-- 关键业务模块:`review_assist.py`(评审提效)、`risk_*`(风控)、`coordination_agent.py`(协调)、`report_agent.py`(报告)、`graph/risk_task.py`,数据在 `backend/backend/xingbang_data/`
+- 关键业务模块:`review_assist.py`(评审提效)、`risk_*`(风控)、`coordination_agent.py`(协调)、`report_agent.py`(报告)、`graph/risk_task.py`,当前项目助手数据在 `backend/xingbang_data/project_assistant.sqlite3`（见 `backend/services/project_assistant.py`）；旧目录需按实际调用确认，不能作为默认迁移源
 
-## 启动与验证命令(改动后必跑)
+## 启动与验证命令（项目实际入口）
 
-```bash
-# 后端(必须用项目虚拟环境,下同)
-cd /f/mini-OpenClaw/backend
-source venv/Scripts/activate        # git-bash;  Windows CMD 用 venv\Scripts\activate.bat
-./start_backend.sh                  # 或 start_backend.bat ; 后端 http://localhost:8002 (docs 在 /docs)
-# 或直接: uvicorn backend.backend.main:app --port 8002
+以下为当前旧版工作区的 PowerShell 命令；v2迁移后改用其独立路径和已确认端口。
 
-# 前端(另开终端)
-cd /f/mini-OpenClaw
-npm run dev                         # 前端 http://localhost:3000
+```powershell
+# 后端：start_backend.bat 使用 backend/venv 并禁用进程内代理
+Set-Location F:\mini-OpenClaw-local-stable\backend
+.\start_backend.bat
+# 实际应用是 app.py；需要指定隔离端口时使用项目venv的 uvicorn app:app
 
-# 自测(改动相关模块后至少跑相关测试)
-cd /f/mini-OpenClaw/backend && source venv/Scripts/activate
-python test_risk_agent_completion.py
-python test_review_assist.py 2>/dev/null || echo "无该测试,视改动定"
-# API 自检: curl http://localhost:8002/docs / 或 /api/… 看路由响应
+# 前端：另开终端
+Set-Location F:\mini-OpenClaw-local-stable
+npm run dev
+
+# 行为改动后的统一验证，包含后端测试、前端构建和Compose配置
+.\backend\venv\Scripts\python.exe scripts/verify.py
 ```
 
+后端默认8002，前端开发默认3000；API健康检查为 `/api/xingbang/health`。验证日志在 `test-evidence/`；失败不得发布镜像。端口占用先核对进程归属，不能为启动v2停止旧版或其他任务。
+
 ## 🛑 变更纪律(核心。防止把已跑通的逻辑改坏)
 
 1. **最小改动**:只改本次任务直接相关的范围。禁止顺手重构、重排、重命名、改格式;看到能优化的代码**先不动**,除非它挡事。
@@ -55,7 +65,7 @@ python test_review_assist.py 2>/dev/null || echo "无该测试,视改动定"
 ## 已知坑(务必遵守)
 
 - **系统代理 127.0.0.1:7890**:后端 `llm`/网络调用会被全局代理干扰,`Connection error / 代理错误` 时用项目自带启动脚本(已自动禁用代理)或 `no_proxy`。别手动留代理变量。
-- **端口占用**:8002 被占 → `netstat -ano | findstr :8002` + `taskkill /F /PID <PID>`;前端 3000 冲突同理。
+- **端口占用**：先用 `netstat -ano | findstr :8002` 确认占用与进程归属；仅停止本任务明确可停止的进程，否则为v2选择隔离端口并同步代理与测试配置。前端3000同理。
 - **必须用 `backend/venv` 虚拟环境**,别用系统 Python。LlamaIndex/依赖都在这个 venv 里。
 - **节点 3000 前端是 Next.js**:改页面后不如鉴是 Node build;SSR/客户端组件区别,别引入后端跑不动的代码。