#开发指南 (Development Guide)

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

架构设计与系统原理：Framework

QA 与发布流水线：QA Pipeline

工程变更日志：Engineering Changelog

#目录

环境搭建
项目结构
开发工作流
后端开发
前端开发
数据库迁移
前后端对接
环境变量管理
验证与质量门禁
常见陷阱与故障排查
参考文献

#1. 环境搭建

#1.1 前置依赖

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

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

后端引擎

类别	技术选型
语言	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

前端应用

类别	技术选型
框架	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 栈一致）：

hljs bash

# 安装 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 供裸机后端连接 ——
hljs bash
docker compose up -d postgres        # 仅起数据库容器
./dev native                         # 裸机后端连接容器 DB（默认 NE_DB_URL 即 localhost:5432）

创建用户与数据库：

hljs bash

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;"

验证：

hljs bash

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 后端安装与首次启动

hljs bash

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

#1.4 前端安装与首次启动

hljs bash

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

#2. 项目结构

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

hljs sh

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. 开发工作流

日常开发循环：

后端代码修改后，ADK Web 自动通过 uv run negentropy serve（内部 --reload_agents src）热重载
前端代码修改后，Next.js 自动热重载
前后端通过 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 启动命令

hljs bash

cd apps/negentropy

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

# FastAPI 独立模式
uv run fastapi dev

#4.3 测试

hljs bash

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

#4.4 代码质量

hljs bash

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 启动命令

hljs bash

cd apps/negentropy-ui

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

#5.3 测试矩阵

hljs bash

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

#5.4 代码质量

hljs bash

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

#5.5 关键事实源

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

应用入口：app/page.tsx
BFF 代理层：app/api/agui/route.ts
ADK 事件转换：lib/adk.ts
AG-UI 类型定义：types/agui.ts
全局布局：app/layout.tsx
服务后端配置：config/services.py（后端侧，通过环境变量切换 Session/Memory/Artifact 后端）

#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 已设置

验证步骤：

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

#6. 数据库迁移

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

唯一信源 (Source of Truth)：src/negentropy/models/ 中的领域模型定义
脚本位置：apps/negentropy/src/negentropy/db/migrations/
Schema 分域设计：详见 Framework §8

#6.1 首次初始化

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

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

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

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

hljs bash

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）下执行：

hljs bash

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/ 中的领域模型发生变更时，需生成对应的迁移脚本：

hljs bash

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

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

#应用变更 (Apply)

hljs bash

uv run alembic upgrade head

#版本回溯 (Rollback)

hljs bash

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

#6.6 状态观测与审计

hljs bash

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

#6.7 模型开发规范

#字段定义

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

hljs python

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() 辅助函数简化外键定义：

hljs python

# 推荐
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 中间件：

hljs python

from fastapi.middleware.cors import CORSMiddleware

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

#8. 环境变量管理

#8.1 YAML 分层加载策略

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

Shell 环境变量（最高优先级，支持 env_nested_delimiter="__" 覆盖深层嵌套字段）
config.local.yaml（cwd 相对路径，已 gitignore，用于本地密钥/覆盖）
CLI 指定 YAML（NE_CONFIG_PATH 环境变量或 -c 参数）
~/.negentropy/config.yaml（用户级配置，由 negentropy init 生成）
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="__" 覆盖深层嵌套字段。

hljs bash

# 首次使用：生成用户级配置文件
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]。

hljs bash

# 服务端（仅 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 最低门禁

lint / test / build / typecheck 必须在 CI 通过
详细 CI/CD 配置请参见 QA 与发布流水线文档

#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 后端启动失败

hljs bash

# 检查 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)

hljs bash

# 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 前端启动失败

hljs bash

# 清理缓存
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

#开发指南 (Development Guide)

#目录

#1. 环境搭建

#1.1 前置依赖

#1.2 PostgreSQL 初始化

#1.3 后端安装与首次启动

#1.4 前端安装与首次启动

#2. 项目结构

#职责边界

#3. 开发工作流

#4. 后端开发

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

#4.2 启动命令

#4.3 测试

#4.4 代码质量

#5. 前端开发

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

#5.2 启动命令

#5.3 测试矩阵

#5.4 代码质量

#5.5 关键事实源

#5.6 验证路径（流式交互）

#6. 数据库迁移

#6.1 首次初始化

#6.2 环境准备

#6.3 基础设施元定义

#6.4 pgvector 类型识别

#6.5 演进工作流

#捕捉变更 (Capture)

#应用变更 (Apply)

#版本回溯 (Rollback)

#6.6 状态观测与审计

#6.7 模型开发规范

#字段定义

#外键引用

#可用 Mixin

#自定义类型

#7. 前后端对接

#7.1 对接原则

#7.2 BFF 路由表

#7.3 关键环境变量

#7.4 跨域处理

#8. 环境变量管理

#8.1 YAML 分层加载策略

#8.2 后端配置

#8.3 前端环境变量

#8.4 安全约束

#9. 验证与质量门禁

#9.1 提交前检查清单

#9.2 CI 最低门禁

#10. 常见陷阱与故障排查

#10.1 常见陷阱 (二阶思维)

#10.2 后端启动失败

#10.3 PostgreSQL 启动或连接失败

#10.4 前端启动失败

#10.5 跨域请求问题

#11. 参考文献

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

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