qiaoqichaoandClaude Code
d56c699ce6
按 docs/v2/05-implementation-plan.md §1 候选迁移表与 claude_use/T00 白名单， 从 55e2cdb 抽取 224 个文件（2.48 MB）到独立目录 F:/mini-OpenClaw-v2。 - 排除：凭据(.env/server-deploy.conf/旧DELIVERY.md)、运行数据(xingbang_data 等 4 个 SQLite)、依赖(venv/node_modules 符号链接)、归档(_backup*/test-evidence/ ori_file)、Office 临时文件 - 目标目录独立 git 仓库，初始恢复点；Gitea 远程与分支待 OQ-06 Q2 定案 - 未部署、未启动服务、未调用模型 Co-Authored-By: Claude Code <noreply@anthropic.com>
82 lines
7.3 KiB
Markdown
82 lines
7.3 KiB
Markdown
# AGENTS.md — mini-OpenClaw 兴邦金租 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 工作区 + 会话历史**里,不在本文件里。
|
|
> 每次会话开始,按顺序对齐"我现在改到哪",再决定动什么 —— **不要**凭 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迁移后改用其独立路径和已确认端口。
|
|
|
|
```powershell
|
|
# 后端：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_*` 文档,遇到"这是什么/怎么拼"先去读,别臆造。
|