Agent Instructions

项目边界

这是 UKEN Web3 Agent 的后端项目。开发时保持 app/ 内的 retrieval、services、prompts、agents、tools、security、evaluation、observability 等边界清晰，不要把业务逻辑塞进 FastAPI 入口。

本仓库当前处于基础脚手架阶段：优先保持结构清晰、命名稳定、文件少而明确。不要因为架构示例而批量创建没有实际内容的业务文件。

Python 中文注释规范

注释精简为主，只在关键位置添加中文注释。

必须注释：

复杂业务流程的步骤标注。
公开 API、导出函数、导出类的 docstring。
非显而易见的业务规则。
临时方案或技术债务，例如 # TODO:、# FIXME:。

禁止注释：

显而易见的代码。
重复代码本身的描述。
每行都加注释。

复杂业务流程使用步骤编号：

async def execute_trading_cycle(self, state: AgentState) -> AgentState:
    """执行交易周期"""

    # 1. 加载交易上下文
    context = await self._load_context(state)

    # 2. 执行风险检查
    risk_result = await self._check_risk(context)
    if risk_result.blocked:
        return state

    # 3. 调用交易工具
    return await self._execute_trade(state, context)

行内注释只解释非显而易见的逻辑：

tolerance = max_trade_usd * Decimal("0.01")  # 允许 1% 误差，避免精度问题

命名规范

新增业务域优先放在 app/modules/<domain>/，标准文件为 client.py、schemas.py、service.py。
agents/nodes/ 下新增业务节点文件必须命名为 xxx_node.py，类名使用 XxxNode。
agents/graphs/ 下新增业务图文件必须命名为 xxx_graph.py，类名使用 XxxGraph。
Agent 工具统一放在 app/agents/tools/，不要新增顶层 app/tools/。
app/agents/tools/ 下按 wallet、nft、defi、chain、market、user 等业务大类归组。
与业务相关的命名不要拆得过细，优先按大类表达职责。
通用工具、基础类型、注册表、策略类可以使用清晰的通用命名，例如 base.py、registry.py。

架构规则

app/main.py 只做应用入口和路由注册，不放业务流程。
app/config.py 统一承载配置读取。
app/models.py 只放跨模块共享的轻量模型。
app/modules/ 负责具体业务域，标准结构为 client.py、schemas.py、service.py。
app/agents/ 负责 Agent 状态、节点和图编排。
app/agents/tools/ 负责 Agent 可调用工具和外部能力封装。
app/services/ 保留跨模块编排和 RAG 占位，不作为新增业务域的默认位置。
app/components/ 负责可替换的通用能力，例如缓存、检索、改写、评分、重排序。
app/prompts/ 负责 prompt 模板、版本和注册，不要在 service 或 agent 中硬编码 prompt。
app/security/ 负责认证、权限、工具策略、输入输出安全和 Prompt 防护。

RAG 占位

当前仓库已有 RAG 相关占位文件，例如 retrieval、reranker、semantic cache、query rewriting、document grading、web/code search 等。它们先保留，后续根据真实业务链路决定接入、重命名或替换。

新增 Web3 Agent 代码时，不要破坏现有 RAG 占位边界。

业务模块示例

市场行情模块使用以下结构：

app/modules/market/
  client.py
  schemas.py
  service.py

client.py：HTTP 或 SDK 客户端，只负责调用第三方 API。
schemas.py：Pydantic 数据结构，包含 HTTP 返回结构和 service 输出结构。
service.py：业务逻辑，负责缓存、清洗、聚合和标准化输出。

FilesExpand file tree

AGENTS.md

Latest commit

History