Skip to content

development.md

Latest commit

 

History

History
695 lines (500 loc) · 31.2 KB

development.md

File metadata and controls

695 lines (500 loc) · 31.2 KB
Raw
sidebar_position 1
title 开发指南 · Development Guide

开发指南 (Development Guide)

本文档是 Negentropy 系统的开发操作单一参考，覆盖环境搭建、日常开发工作流、数据库迁移、前后端对接及故障排查。

目录

  1. 环境搭建
  2. 项目结构
  3. 开发工作流
  4. 后端开发
  5. 前端开发
  6. 数据库迁移
  7. 前后端对接
  8. 环境变量管理
  9. 验证与质量门禁
  10. 常见陷阱与故障排查
  11. 参考文献

1. 环境搭建

1.1 前置依赖

高层技术栈概览与应用边界详见 Framework §2.2。以下为环境搭建所需的完整依赖清单。

Docker 部署：如需通过 Docker Compose 一键部署全套服务（非原生开发），请参阅 Docker Compose 运维指引。

  1. 后端引擎
类别 技术选型
语言 Python 3.13+
Python 包管理 uv[1]
Agent 框架 Google ADK
LLM 接口 LiteLLM (统一 100+ LLM 接入)
Web 框架 FastAPI (通过 ADK Web Server)
ORM SQLAlchemy 2.0 (async, asyncpg)
数据库 PostgreSQL 17+ (pgvector)
迁移 Alembic
沙箱 MCP + MicroSandbox
可观测性 structlog + OpenTelemetry + Langfuse
配置 Pydantic Settings (正交配置域)
包管理 uv
  1. 前端应用
类别 技术选型
框架 Next.js 16+
UI React 19, TypeScript, Tailwind CSS
AI 集成 AG-UI Protocol (CopilotKit)
图谱可视化 D3.js (Force Graph)
图表渲染 Mermaid
测试 Vitest (单元/集成), Playwright (E2E)
包管理 pnpm

1.2 PostgreSQL 初始化

首次运行后端之前，必须确保 PostgreSQL 服务运行正常且所需扩展已安装。./dev（Docker 路径）已内置 pgvector Postgres，可跳过本节。

安装与启动（以 Homebrew macOS 为例；推荐 PG17，与 Docker 栈一致）：

# 安装 PostgreSQL 17 与 pgvector 扩展
brew install postgresql@17 pgvector

# 启动服务
brew services start postgresql@17
pg_isready -h localhost -p 5432        # 验证：accepting connections

pg_cron 不再需要：自迁移 0042 起，Skill 调度与 Memory 自动化已迁入进程内 Unified Scheduler（skill_scheduler.py / engine/schedulers/），不再依赖 pg_cron 扩展 —— 无需编译安装，无需在 postgresql.conf 配置 shared_preload_libraries。uuid-ossp 与 vector 扩展由应用启动时自动 CREATE EXTENSION（见 docker/postgres/init.sql 与迁移 env.py）。

更省事：若仅本地开发，可只起 Docker 内的 Postgres 供裸机后端连接 ——

docker compose up -d postgres        # 仅起数据库容器
./dev native                         # 裸机后端连接容器 DB（默认 NE_DB_URL 即 localhost:5432）

创建用户与数据库：

psql -d postgres -c "CREATE USER aigc"
psql -d postgres -c "CREATE DATABASE negentropy OWNER aigc"
psql -d negentropy -c "GRANT ALL ON DATABASE negentropy TO aigc; GRANT ALL ON SCHEMA public TO aigc;"

验证：

psql -h localhost -U aigc -d negentropy -c "SELECT version();"
# 应返回 PostgreSQL 17.x 版本信息

连接配置默认值为 postgresql+asyncpg://aigc:@localhost:5432/negentropy，如需覆盖可通过 config.local.yaml 或 NE_DB_URL 环境变量。参见 §8 环境变量管理。

1.3 后端安装与首次启动

cd apps/negentropy
uv sync --dev                          # 安装全部依赖（含开发依赖）
uv run alembic upgrade head            # 应用数据库迁移至最新版本
uv run negentropy serve  # 启动引擎（封装 adk web，自动锚定正确 agents_dir，默认端口 3292）

1.4 前端安装与首次启动

cd apps/negentropy-ui
pnpm install                           # 安装依赖
pnpm run dev                           # 启动开发服务器 (localhost:3192)

2. 项目结构

架构设计原理（三层架构视图、设计模式等）详见 Framework §2。本节聚焦目录布局与开发操作视角。

negentropy/
├── .gitignore                         # Git 忽略规则
├── .mcp.json                          # MCP 服务配置
├── AGENTS.md                          # AI 协作协议
├── LICENSE                            # 许可协议
├── README.md                          # 项目自述
├── docs/                              # 项目文档
│   ├── development.md                 # 本文档
│   ├── framework.md                   # 架构设计方案
│   └── ...
├── apps/                              # 应用根目录
│   ├── negentropy/                    # Python 后端 (uv 管理)
│   │   ├── pyproject.toml             # uv 项目配置
│   │   ├── uv.lock                    # uv 锁文件（提交至版本库）
│   │   ├── .python-version            # Python 版本锚定
│   │   ├── alembic.ini                # Alembic 全局配置
│   │   ├── src/negentropy/            # 主包
│   │   │   ├── agents/                # 智能体编排（一核五翼）
│   │   │   ├── engine/                # 引擎层（API/工厂/适配器/沙箱）
│   │   │   ├── config/                # 配置管理（YAML 分层 + Pydantic 正交域）
│   │   │   │   └── config.default.yaml  # 包级默认 YAML（单一事实源）
│   │   │   ├── models/                # 数据模型（ORM）
│   │   │   ├── knowledge/             # 知识管理
│   │   │   ├── auth/                  # 认证与授权
│   │   │   ├── interface/             # Interface 模块（Models / SubAgents / MCP / Skills）
│   │   │   ├── storage/               # 存储抽象层
│   │   │   └── db/migrations/         # 数据库迁移
│   │   ├── tests/                     # 测试目录
│   │   │   ├── unit_tests/
│   │   │   ├── integration_tests/
│   │   │   └── performance_tests/
│   │   └── scripts/                   # 后端专用脚本
│   ├── negentropy-ui/                 # 前端 (pnpm 管理)
│   │   ├── package.json               # pnpm 项目配置
│   │   ├── pnpm-lock.yaml             # pnpm 锁文件（提交至版本库）
│   │   ├── .env.example               # 环境变量模板（前端）
│   │   ├── app/                       # Next.js App Router 页面与 API 路由
│   │   ├── components/                # 通用可复用 UI 组件
│   │   ├── features/                  # 按功能域组织的业务组件
│   │   ├── hooks/                     # 自定义 React Hooks
│   │   ├── lib/                       # 核心工具库
│   │   ├── utils/                     # 纯函数工具集
│   │   ├── types/                     # TypeScript 类型定义
│   │   ├── config/                    # 前端配置常量
│   │   ├── public/                    # 静态资源
│   │   ├── tests/                     # 测试目录
│   │   │   ├── e2e/
│   │   │   ├── integration/
│   │   │   └── unit/
│   │   └── scripts/                   # 前端专用脚本
│   └── negentropy-wiki/               # Wiki 应用 (pnpm 管理)
└── .temp/                             # 临时文件（自动清理）

职责边界

维度 Backend (uv) Frontend (pnpm)
包管理器 uv[1] pnpm
锁文件 uv.lock pnpm-lock.yaml
依赖安装 uv sync pnpm install
开发命令 uv run adk web[5] pnpm run dev[6]
测试命令 uv run pytest pnpm run test
代码格式化 ruff eslint / prettier

前后端仅通过 HTTP/JSON 契约交互，严禁源码互引。详见 Framework §2.2。

3. 开发工作流

flowchart LR
    Start[克隆项目] --> SetupBE[后端: uv sync --dev]
    Start --> SetupFE[前端: pnpm install]

    SetupBE --> DevBE[后端: uv run negentropy serve]
    SetupFE --> DevFE[前端: pnpm run dev<br>localhost:3192]

    DevBE --> |热重载| DevBE
    DevFE --> |热重载| DevFE

    DevBE --> |AG-UI Protocol| DevFE

    classDef dev fill:#FEF3C7,stroke:#92400E,color:#000

    class SetupBE,SetupFE,DevBE,DevFE dev
Loading

日常开发循环：

  1. 后端代码修改后，ADK Web 自动通过 uv run negentropy serve（内部 --reload_agents src）热重载
  2. 前端代码修改后，Next.js 自动热重载
  3. 前后端通过 AG-UI Protocol（SSE/HTTP）进行通信

4. 后端开发

4.1 核心配置：apps/negentropy/pyproject.toml

  • 锚定 Python 版本（requires-python >= "3.13,<3.14"）
  • 运行依赖与开发依赖分离（[dependency-groups] dev = [...]）
  • 锁文件 uv.lock 必须提交到版本库

4.2 启动命令

cd apps/negentropy

# ADK Web 模式（推荐，支持 AG-UI Protocol，默认端口 3292）
uv run negentropy serve

# FastAPI 独立模式
uv run fastapi dev

4.3 测试

uv run pytest                          # 运行全部测试
uv run pytest tests/unit_tests/        # 仅单元测试
uv run pytest tests/integration_tests/ # 仅集成测试

4.4 代码质量

uv run ruff check .                    # Lint 检查
uv run ruff format .                   # 代码格式化

5. 前端开发

5.1 核心配置：apps/negentropy-ui/package.json

  • 明确 dev / build / test / lint / typecheck 脚本
  • 锁文件 pnpm-lock.yaml 必须提交到版本库

5.2 启动命令

cd apps/negentropy-ui

pnpm run dev                           # 开发启动 (localhost:3192)
pnpm run build                         # 生产构建
pnpm run start                         # 生产启动

5.3 测试矩阵

pnpm run test                          # 单元/集成测试 (Vitest)
pnpm run test:coverage                 # 覆盖率报告
pnpm run test:e2e                      # E2E 测试 (Playwright)

5.4 代码质量

pnpm run lint                          # ESLint 检查
pnpm run typecheck                     # TypeScript 类型检查

5.5 关键事实源

前端开发中需关注的核心文件参考点：

5.6 验证路径（流式交互）

确保 UI → BFF → ADK → AG-UI 全链路可用。

前置条件：

  • 后端 ADK 已启动，AGUI_BASE_URL 可访问
  • 前端已启动：http://localhost:3192
  • .env.local 中 NEXT_PUBLIC_AGUI_APP_NAME 与 NEXT_PUBLIC_AGUI_USER_ID 已设置

验证步骤：

  1. 打开 /：三栏布局显示（Session 列表 / 对话区 / 状态+事件）
  2. 点击 New Session：左栏新增会话
  3. 发送指令，期望结果：
    • 中栏出现用户消息与 Agent 回应（逐步更新）
    • 右栏 Event Timeline 出现文本/工具/状态/Artifact 卡片
    • 连接状态 connecting → streaming → idle 变化可见
  4. 若后端触发工具调用：右栏展示工具卡片（名称/入参/结果/状态）
  5. 切换左侧已有 Session：中栏加载历史消息，右栏加载历史事件

6. 数据库迁移

数据库迁移是系统数据架构演进的版本控制机制。本项目采用 Alembic 确保数据库 Schema 能够随同领域模型有序迭代。

6.1 首次初始化

完整的 PostgreSQL 安装与配置请参见 §1.2 PostgreSQL 初始化。本节聚焦数据库层面（Schema / Extension）的初始化逻辑。

alembic upgrade head 首次执行时，env.py 会自动完成以下操作：

  1. 创建 Schema：CREATE SCHEMA IF NOT EXISTS negentropy（所有业务表归属此 schema）
  2. 启用 pgvector：CREATE EXTENSION IF NOT EXISTS vector（向量检索 / embedding 列依赖）
  3. 应用迁移链：按版本顺序执行 versions/ 下所有迁移脚本

因此首次初始化只需确保 PostgreSQL 运行 + 连接配置正确，然后执行：

cd apps/negentropy
uv run alembic upgrade head
uv run alembic current               # 验证：应显示最新 revision

运行时扩展（非迁移必需，但应用功能依赖）：

扩展 安装方式 依赖模块 是否需要 shared_preload_libraries
pgvector brew install pgvector Knowledge / Embedding 向量检索 否
uuid-ossp 随 PostgreSQL 自带 UUID 生成 否

pg_cron 已废弃：自迁移 0042 起，Skill 调度与 Memory 自动化改由进程内 Unified Scheduler 驱动，不再依赖 pg_cron，无需安装、无需 shared_preload_libraries、无需重启 PostgreSQL。pgvector / uuid-ossp 由应用启动时自动 CREATE EXTENSION。

6.2 环境准备

所有迁移操作必须在应用根目录（apps/negentropy）下执行：

cd apps/negentropy
uv sync --dev                          # 确保本地环境与 pyproject.toml 一致

确保 PostgreSQL 服务运行中（pg_isready -h localhost -p 5432），连接配置（database_url）已在 config.local.yaml 或 config/database.py 中正确加载。

6.3 基础设施元定义

组件 文件 作用
演进模板 script.py.mako 生成新迁移脚本的蓝图，定义标准代码结构
全局配置 alembic.ini Alembic CLI 入口配置（脚本路径、连接字符串、时区、日志）
运行时上下文 env.py 加载模型元数据、读取数据库连接配置、驱动异步迁移

6.4 pgvector 类型识别

当数据库启用 pgvector 且模型使用 Vector 类型时，env.py 中已注册 vector 的反射映射，并在 compare_type 中做等价比较，从源头消除不必要的类型告警。

关键约束：

  • 不屏蔽告警：保留 Alembic 正常提示机制，仅让 vector 类型能够被正确识别
  • 不改变运行时逻辑：只影响 Alembic 反射与比对行为

6.5 演进工作流

捕捉变更 (Capture)

当 src/negentropy/models/ 中的领域模型发生变更时，需生成对应的迁移脚本：

uv run alembic revision --autogenerate -m "描述变更内容"

关键步骤：自动生成的脚本位于 src/negentropy/db/migrations/versions/。务必人工审查生成的 Python 脚本，确保其精准反映变更意图，且不包含意外的破坏性操作。

应用变更 (Apply)

uv run alembic upgrade head

版本回溯 (Rollback)

uv run alembic downgrade -1             # 回退至上一版本
uv run alembic downgrade base           # 重置至初始状态

6.6 状态观测与审计

uv run alembic current                  # 确认当前数据库版本
uv run alembic history                  # 追溯架构演进路线

6.7 模型开发规范

字段定义

使用 SQLAlchemy 2.0 的 Mapped[] 类型注解风格：

from sqlalchemy import String, UniqueConstraint
from sqlalchemy.orm import Mapped, mapped_column
from negentropy.models.base import Base, UUIDMixin, TimestampMixin, fk

class MyModel(Base, UUIDMixin, TimestampMixin):
    __tablename__ = "my_model"

    name: Mapped[str] = mapped_column(String(255), nullable=False)
    thread_id: Mapped[UUID] = mapped_column(fk("threads", ondelete="CASCADE"))

    __table_args__ = (
        UniqueConstraint("name", name="uq_my_model_name"),
        {"schema": NEGENTROPY_SCHEMA},
    )

外键引用

使用 fk() 辅助函数简化外键定义：

# 推荐
thread_id: Mapped[UUID] = mapped_column(fk("threads", ondelete="CASCADE"))

# 避免
thread_id: Mapped[UUID] = mapped_column(
    ForeignKey(f"{NEGENTROPY_SCHEMA}.threads.id", ondelete="CASCADE")
)

可用 Mixin

Mixin 提供字段
UUIDMixin id: UUID (主键)
TimestampMixin created_at, updated_at

自定义类型

类型 用途
Vector(dim) pgvector 向量类型，如 Vector(1536)

7. 前后端对接

7.1 对接原则

  • 不侵入后端核心逻辑：前端通过 AG-UI Protocol 与 ADK 服务通信
  • 复用现有运行入口：使用 uv run negentropy serve（默认端口 3292）
  • BFF 代理层：前端在 app/api/agui/ 下设置 Route Handler 作为代理，解决 CORS/鉴权/统一路由问题

7.2 BFF 路由表

路径 方法 目的 实现位置
/api/agui POST 发送用户输入并返回 SSE 流 app/api/agui/route.ts
/api/agui/sessions POST 创建 Session app/api/agui/sessions/route.ts
/api/agui/sessions/list GET 拉取 Session 列表 app/api/agui/sessions/list/route.ts
/api/agui/sessions/:id GET 获取 Session 详情（含 events，用于回放） app/api/agui/sessions/[sessionId]/route.ts
/api/health GET UI 运行自检 app/api/health/route.ts

BFF 代理层仅做连接与头部注入，不做协议语义改写，避免"二次真值源"。

7.3 关键环境变量

变量 作用域 说明
AGUI_BASE_URL 服务端 后端地址（默认 http://localhost:3292）
NEXT_PUBLIC_AGUI_APP_NAME 客户端 应用名称标识
NEXT_PUBLIC_AGUI_USER_ID 客户端 用户标识

7.4 跨域处理

若前后端不通过 BFF 代理通信（直连模式），需在后端配置 CORS 中间件：

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3192"],
    allow_methods=["*"],
    allow_headers=["*"],
)

8. 环境变量管理

8.1 YAML 分层加载策略

后端按以下优先级加载配置（高优先级覆盖低优先级）：

  1. Shell 环境变量（最高优先级，支持 env_nested_delimiter="__" 覆盖深层嵌套字段）
  2. config.local.yaml（cwd 相对路径，已 gitignore，用于本地密钥/覆盖）
  3. CLI 指定 YAML（NE_CONFIG_PATH 环境变量或 -c 参数）
  4. ~/.negentropy/config.yaml（用户级配置，由 negentropy init 生成）
  5. config.default.yaml（包级默认值，单一事实源，提交至版本库）

密钥/敏感项严禁写入 YAML 文件或提交到仓库，应通过 shell 环境变量或 config.local.yaml（仅本地）提供。

8.2 后端配置

后端配置以 apps/negentropy/src/negentropy/config/config.default.yaml 为单一事实源。密钥/敏感项通过 shell 环境变量或 config.local.yaml 覆盖。支持 env_nested_delimiter="__" 覆盖深层嵌套字段。

# 首次使用：生成用户级配置文件
uv run negentropy init    # 写入 ~/.negentropy/config.yaml

# 本地覆盖：创建 config.local.yaml（已被 .gitignore 排除）
cp src/negentropy/config/config.default.yaml config.local.yaml
# 编辑 config.local.yaml 填入本地配置

# 核心配置（通过 shell 环境变量覆盖 YAML 默认值）
export NE_DB_URL=postgresql+asyncpg://localhost:5432/negentropy
export NE_ENV=development

# 深层嵌套覆盖示例（使用 __ 分隔符）
export NE_KNOWLEDGE_DEFAULT_EXTRACTOR_ROUTES__URL__PRIMARY__TIMEOUT_MS=90000

# 密钥类变量（严禁写入 YAML 或提交到仓库）
export OPENAI_API_KEY=...
export ANTHROPIC_API_KEY=...
export GEMINI_API_KEY=...

8.3 前端环境变量

使用 apps/negentropy-ui/.env.example 作为模板。仅 NEXT_PUBLIC_ 前缀变量暴露给客户端[7]。

# 服务端（仅 Route Handler 可用）
AGUI_BASE_URL=http://localhost:3292

# 客户端（浏览器可见）
NEXT_PUBLIC_AGUI_APP_NAME=negentropy
NEXT_PUBLIC_AGUI_USER_ID=dev-user

8.4 安全约束

  • 后端配置默认值由 config.default.yaml 承载；密钥仅通过 shell 环境变量或 config.local.yaml 提供，严禁写入版本库
  • config.local.yaml 仅用于本地覆盖，已 .gitignore 排除，不得提交
  • 前端 .env.example 仅作模板，.env.local / .env.production 用于环境覆盖
  • .gitignore 必须排除 config.local.yaml、.env、.env.local、.env.*.local

9. 验证与质量门禁

9.1 提交前检查清单

  • 锁文件已更新并提交（uv.lock、pnpm-lock.yaml）
  • 所有测试通过（uv run pytest + pnpm run test）
  • Linter 无报错（ruff check + pnpm run lint）
  • 类型检查通过（pnpm run typecheck）
  • 后端默认配置已同步（config.default.yaml），前端环境变量模板已同步（.env.example）；后端本地覆盖通过 config.local.yaml
  • .gitignore 正确排除敏感文件
  • 文档已同步更新

9.2 CI 最低门禁

10. 常见陷阱与故障排查

10.1 常见陷阱 (二阶思维)

陷阱 表象 根因 防范措施
依赖版本漂移 本地可运行，CI 失败 锁文件未提交或不同步 强制提交 uv.lock 与 pnpm-lock.yaml
端口冲突 Address already in use 多实例并发或未正确清理 脚本中增加端口检测与自动清理逻辑
环境变量泄漏 密钥出现在日志中 配置文件误提交 .gitignore 严格排除 config.local.yaml，Pre-commit Hook 检查
跨域问题 浏览器报错 CORS 开发环境未配置代理 后端启用 CORS 中间件，前端配置 BFF 代理
虚拟环境丢失 uv run 找不到模块 .venv 被 .gitignore 忽略 执行 uv sync 恢复

10.2 后端启动失败

# 检查 Python 版本
cd apps/negentropy
python --version  # 应与 .python-version 一致

# 重新同步依赖
uv sync --reinstall

# 检查端口占用
lsof -i :3292

10.3 PostgreSQL 启动或连接失败

症状：alembic upgrade head 报 OSError: [Errno 61] Connect call failed ('127.0.0.1', 5432)

# 1. 检查 PostgreSQL 运行状态
pg_isready -h localhost -p 5432
brew services info postgresql@17

# 2. 若服务未运行，尝试启动
brew services restart postgresql@17

# 3. 若启动失败，查看日志定位原因
/opt/homebrew/opt/postgresql@17/bin/pg_ctl \
  -D /opt/homebrew/var/postgresql@17 \
  -l /tmp/pg_debug.log start
cat /tmp/pg_debug.log

常见启动失败原因：

错误信息 根因 修复
could not access file "pg_cron" 旧版残留：postgresql.conf 仍配置了 shared_preload_libraries = 'pg_cron'，而 pg_cron 已不再需要 注释/删除 postgresql.conf 中的 shared_preload_libraries 配置项并重启 PostgreSQL（pg_cron 自迁移 0042 起已废弃）
extension "vector" does not exist pgvector 扩展未安装 brew install pgvector（或使用 Docker 内置 pgvector Postgres）
port 5432 already in use 端口被其他 PG 实例或进程占用 lsof -i :5432 定位并处理占用进程
data directory was initialized by PostgreSQL version X 数据目录版本与 PG 版本不匹配 使用 pg_upgrade 迁移或重新 initdb

10.4 前端启动失败

# 清理缓存
cd apps/negentropy-ui
rm -rf node_modules pnpm-lock.yaml
pnpm install

# 检查 Node 版本
node --version
pnpm --version

10.5 跨域请求问题

确认后端 FastAPI 已配置 CORS 中间件（参见 §7.4），或确认前端 BFF 代理层（/api/agui）正常工作。

11. 参考文献

[1] Astral, "uv: A very fast Python package installer," Python Packaging Authority, 2024. [Online]. Available: https://github.com/astral-sh/uv

[2] Astral, "uv CLI Reference," uv Documentation, 2025. [Online]. Available: https://docs.astral.sh/uv/reference/cli/#uv-run

[3] M. Community, "npm best practices," npm Documentation, 2024. [Online]. Available: https://docs.npmjs.com/cli/v9/using-npm/best-practices

[4] S. Ramirez, "First Steps," FastAPI Documentation, 2025. [Online]. Available: https://fastapi.tiangolo.com/tutorial/first-steps/

[5] S. Ramirez, "FastAPI Documentation," FastAPI, 2025. [Online]. Available: https://fastapi.tiangolo.com/

[6] Vercel, "Installation," Next.js Documentation, 2025. [Online]. Available: https://nextjs.org/docs/app/getting-started/installation

[7] Vercel, "Environment Variables," Next.js Documentation, 2025. [Online]. Available: https://nextjs.org/docs/app/guides/environment-variables

[8] Vercel, "next CLI," Next.js Documentation, 2025. [Online]. Available: https://nextjs.org/docs/app/api-reference/cli/next