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

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

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

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

git status --short → 看 未提交的改动 / 已删除的文件。本项目常有页面级重构(删一批 src/app/*、合并进 *-workbench),删除了就是用户正在做的整合,别当成"误删"去恢复。
git log --oneline -6 → 接到最近提交那条线上(当前主线:兴邦四 Agent v2 / xingbang 工作台整合)。
当前处于**_重构进行中**:src/app/ 下多个独立页正在向 xingbang-workbench / review-workbench / report-workbench / collateral-workbench / data-access / trajectory 等合并。改代码前先确认该页还在不在、已合并到哪里,别对旧页做无效修改。
每次行为修改必须新增或更新对应测试，并运行 python scripts/verify.py。测试计划和完整日志保留在 test-evidence/；失败时不允许发布镜像。

⚠️ 关键惯例:本项目也是「多轮迭代、每步有 _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/

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

# 后端(必须用项目虚拟环境,下同)
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/… 看路由响应

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

最小改动:只改本次任务直接相关的范围。禁止顺手重构、重排、重命名、改格式;看到能优化的代码先不动,除非它挡事。
改动前先读调用方:改任何函数/API/工具前,先搜它的全部调用方(backend/、src/ 内 grep),确认改动不影响别的调用方。认不准就退回先问。
前后端联动意识:改后端 API 或字段时,同时确认前端 src/app/ 对应页(可能已迁移到 workbench 页)是否受影响。牵一发动全身,先查再改。
改后必跑验证:见「启动与开发」的命令,跑通再继续;拿不准就还原、只保留最小可验证改动。
改完自查 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_* 文档,遇到"这是什么/怎么拼"先去读,别臆造。

5.2 KiB Raw Permalink Blame History

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

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

项目是什么

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

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

已知坑(务必遵守)

代码风格与目录约定

说明

5.2 KiB

Raw Permalink Blame History