# AGENTS.md — mini-OpenClaw 兴邦金租 AI 评审平台

> 本文件是仓库唯一事实来源,供 Codex / Claude / 其他 AI 编码代理读取。
> **先读本文件,再动手;开发全程遵守「改动纪律」,尤其是有序验证命令。**

## ▶️ 接手当前进度(每次新对话/会话开始时先做,别当新项目从零写)

> 本文件写的是**规则,不是进度**。你的进度在**代码 + git 工作区 + 会话历史**里,不在本文件里。
> 每次会话开始,按顺序对齐"我现在改到哪",再决定动什么 —— **不要**凭 AGENTS.md 脑补项目全貌。

1. `git status --short` → 看 **未提交的改动 / 已删除的文件**。本项目常有页面级重构(删一批 `src/app/*`、合并进 `*-workbench`),删除了就是用户正在做的整合,别当成"误删"去恢复。
2. `git log --oneline -6` → 接到最近提交那条线上(当前主线:兴邦四 Agent v2 / xingbang 工作台整合)。
3. 当前处于**_重构进行中**:`src/app/` 下多个独立页正在向 **xingbang-workbench / review-workbench / report-workbench / collateral-workbench / data-access / trajectory** 等合并。**改代码前先确认该页还在不在、已合并到哪里,别对旧页做无效修改。**

⚠️ 关键惯例:本项目也是「多轮迭代、每步有 `_backup_pre_*` 备份目录」。**改哪里先确认现状,不破坏已跑通逻辑;大改动前默认应该先在你的分支/工作区留能回滚的点。**

## 项目是什么

兴邦金租 AI Native 智能评审决策系统(四 Agent:审查 / 风控 risk / 协调 coordination / 报告 report)。前后端分离:

- `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/`

## 启动与验证命令(改动后必跑)

```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

# 前端(另开终端)
cd /f/mini-OpenClaw
npm run dev                         # 前端 http://localhost:3000

# 自测(改动相关模块后至少跑相关测试)
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/… 看路由响应
```

## 🛑 变更纪律(核心。防止把已跑通的逻辑改坏)

1. **最小改动**:只改本次任务直接相关的范围。禁止顺手重构、重排、重命名、改格式;看到能优化的代码**先不动**,除非它挡事。
2. **改动前先读调用方**:改任何函数/API/工具前,先搜它的全部调用方(`backend/`、`src/` 内 grep),确认改动不影响别的调用方。认不准就退回先问。
3. **前后端联动意识**:改后端 API 或字段时,同时确认前端 `src/app/` 对应页(可能已迁移到 workbench 页)是否受影响。**牵一发动全身,先查再改。**
4. **改后必跑验证**:见「启动与开发」的命令,跑通再继续;拿不准就还原、只保留最小可验证改动。
5. **改完自查 diff**: `git status` + `git diff --stat`,确认没多动无关文件。有"顺手动到/删到"的,**改回或向我确认**,尤其不要误删要保留的页面。

## 已知坑(务必遵守)

- **系统代理 127.0.0.1:7890**:后端 `llm`/网络调用会被全局代理干扰,`Connection error / 代理错误` 时用项目自带启动脚本(已自动禁用代理)或 `no_proxy`。别手动留代理变量。
- **端口占用**:8002 被占 → `netstat -ano | findstr :8002` + `taskkill /F /PID <PID>`;前端 3000 冲突同理。
- **必须用 `backend/venv` 虚拟环境**,别用系统 Python。LlamaIndex/依赖都在这个 venv 里。
- **节点 3000 前端是 Next.js**:改页面后不如鉴是 Node build;SSR/客户端组件区别,别引入后端跑不动的代码。

## 代码风格与目录约定

- `backend/` 用 Python,`src/` 用 TypeScript/React(Next.js App Router)。
- 业务 Agent 各在独立文件(review/risk/coordination/report),新逻辑就近放对应模块,**不要**堆进某个巨大文件。
- 重构建议:先把目标拆清(前端页面的整合去向、后端 API 是否仍有调用),再动手删/并,别让旧页"幽灵残留"引用报错。
- 提交用中文、一句话说清「改了做什么→结果」;大变化先看 `git status` 确认删的都是该删的。

## 说明

- 项目有完整 `ARCHITECTURE.md` / `DEV_*` 文档,遇到"这是什么/怎么拼"先去读,别臆造。