mini-openclaw-v2/AGENTS.md

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

本文件是仓库开发规则的统一入口，供 Codex / Claude / 其他 AI 编码代理读取；运行事实以代码、测试和已核验记录为准。 先读本文件,再动手;开发全程遵守「改动纪律」,尤其是有序验证命令。

项目开发流程（强制）

1. 所有需求、修复、重构、UI、接口与交付工作，先读 项目流程 和 兴邦适配说明，进入阶段前再读对应的 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。该目录保存入库评审草案及后续基线；必须区分已实现、规划、模拟演示和真实验证，不能用文件存在证明功能已完成。
6. 行为改动沿用本文件的测试与 backend/venv 要求，必须运行 python scripts/verify.py 并保存 test-evidence/。文档改动至少检查链接、编号覆盖、事实来源及 git diff --check；不得声称未接入的 CI、Jev 或概率模型已生效。
7. 提交使用 Conventional Commits 类型前缀加中文一句话说明；默认分支从 Gitea 实际读取，不照搬来源项目的 build。备份分支只代表恢复点，不等于评审通过、合并或发布。

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

本文件写的是规则,不是进度。你的进度在代码 + 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 等合并。改代码前先确认该页还在不在、已合并到哪里,别对旧页做无效修改。

4. 每次行为修改必须新增或更新对应测试，并运行 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/xingbang_data/project_assistant.sqlite3（见 backend/services/project_assistant.py）；旧目录需按实际调用确认，不能作为默认迁移源

启动与验证命令（项目实际入口）

以下为当前旧版工作区的 PowerShell 命令；v2迁移后改用其独立路径和已确认端口。

# 后端：start_backend.bat 使用 backend/venv 并禁用进程内代理
Set-Location F:\mini-OpenClaw-local-stable\backend
.\start_backend.bat
# 实际应用是 app.py；需要指定隔离端口时使用项目venv的 uvicorn app:app

# 前端：另开终端
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. 最小改动:只改本次任务直接相关的范围。禁止顺手重构、重排、重命名、改格式;看到能优化的代码先不动,除非它挡事。
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。别手动留代理变量。
• 端口占用：先用 netstat -ano | findstr :8002 确认占用与进程归属；仅停止本任务明确可停止的进程，否则为v2选择隔离端口并同步代理与测试配置。前端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_* 文档,遇到"这是什么/怎么拼"先去读,别臆造。