From c090893e639e9796e66669790e8fde5d914d2421 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=99=88=E6=AD=86?= <2685475410@qq.com> Date: Fri, 21 Aug 2026 22:12:34 +0800 Subject: [PATCH] =?UTF-8?q?=E7=BB=9F=E4=B8=80=E6=9C=8D=E5=8A=A1=E5=90=AF?= =?UTF-8?q?=E5=8A=A8=E5=85=A5=E5=8F=A3=E8=87=B3=20Makefile=EF=BC=88dev-cor?= =?UTF-8?q?e/dev-*/db-*/test-*=EF=BC=89=EF=BC=8CAlembic=20=E8=BF=81?= =?UTF-8?q?=E7=A7=BB=E6=94=B9=E4=B8=BA=20000=20=E8=B5=B7=E4=B8=89=E4=BD=8D?= =?UTF-8?q?=E9=A1=BA=E5=BA=8F=E7=BC=96=E5=8F=B7=E5=B9=B6=E7=BB=8F=20make?= =?UTF-8?q?=20db-revision=20=E7=94=9F=E6=88=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 12 ++ Makefile | 170 ++++++++++++++---- backend/alembic.ini | 4 + ...一起点.py => 000_rewrite_1_0_baseline.py} | 2 +- bff/README.md | 12 +- docs/architecture/data-model.md | 2 +- docs/operations/rewrite-plan.md | 2 +- shenshi/README.md | 8 +- 8 files changed, 162 insertions(+), 50 deletions(-) rename backend/alembic/versions/{843abf719fde_rewrite_1_0_基线_合并既有模式为单一起点.py => 000_rewrite_1_0_baseline.py} (99%) diff --git a/AGENTS.md b/AGENTS.md index fd55baa..62e2996 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -224,6 +224,18 @@ Compose 文件不使用顶部 `version` 字段。 ## 开发命令 +### 本地开发（Makefile 统一入口） + +所有本地服务的启动、测试与数据库迁移统一经根目录 Makefile（`make help` 查看全部）： + +```bash +make dev-core # 核心三服务并行：灵台 + 神识 + 照壁 +make dev-backend # 灵台（另有 dev-shenshi / dev-bff / dev-frontend / dev-sandbox / dev-tianmu / dev-yuanqi） +make db-upgrade # Alembic 升级到 head（迁移编号 000/001/002…） +make db-revision m="说明" # 生成下一号迁移（自动编号 + autogenerate，禁手写哈希 id） +make test # 全部测试（backend / shenshi / bff / frontend） +``` + ### Docker 编排按职责解耦为两个文件，容器名统一以 `hunjing-` 开头，通过共享网络 `hunjing-net` 互通，详细说明见 `docker/README.md`： diff --git a/Makefile b/Makefile index d69f520..0987767 100644 --- a/Makefile +++ b/Makefile @@ -1,30 +1,142 @@ -# Makefile for cleaning Python cache files and empty directories -# Author: AI Assistant -# Usage: make clean or make clean-all +# ============================== +# 魂镜 · 统一开发入口（rewrite/1.0） +# 所有本地服务的启动 / 测试 / 数据库迁移统一经本文件； +# Docker 编排（基础设施与应用容器）见 AGENTS.md「开发命令」与 docker/README.md。 +# ============================== -.PHONY: clean clean-all clean-pyc clean-pytest clean-mypy clean-empty-dirs help - -# Colors for pretty output GREEN := \033[0;32m YELLOW := \033[0;33m -RED := \033[0;31m -NC := \033[0m # No Color +NC := \033[0m -# Default target +.PHONY: help \ + dev-backend dev-shenshi dev-bff dev-frontend dev-sandbox dev-tianmu dev-yuanqi dev-core dev-all \ + db-upgrade db-downgrade db-revision db-current \ + test test-backend test-shenshi test-bff test-frontend \ + vet-shenshi typecheck-bff \ + infra-up app-up app-down \ + clean clean-all clean-pyc clean-pytest clean-mypy clean-empty-dirs clean-dry-run + +# 默认目标 help: - @echo "$(GREEN)Available targets:$(NC)" - @echo " $(YELLOW)make clean$(NC) - Remove Python cache files, pytest cache, mypy cache, and empty directories" - @echo " $(YELLOW)make clean-pyc$(NC) - Remove Python cache files (__pycache__, .pyc, .pyo)" - @echo " $(YELLOW)make clean-pytest$(NC) - Remove pytest cache (.pytest_cache)" - @echo " $(YELLOW)make clean-mypy$(NC) - Remove mypy cache (.mypy_cache)" - @echo " $(YELLOW)make clean-empty-dirs$(NC) - Remove empty directories" - @echo " $(YELLOW)make clean-all$(NC) - Remove everything (cache, logs, coverage, build, dist, etc.)" + @echo "$(GREEN)魂镜统一开发入口$(NC)" + @echo "" + @echo "$(YELLOW)服务启动（开发）$(NC)" + @echo " make dev-backend 灵台（uvicorn 热重载，:8000）" + @echo " make dev-shenshi 神识（go run，:8080）" + @echo " make dev-bff 照壁（tsx watch，:3000）" + @echo " make dev-frontend 琉璃镜（next dev，:3001）" + @echo " make dev-sandbox 乾坤沙箱（cargo run，:8090）" + @echo " make dev-tianmu 天目 OCR（:8101，可选）" + @echo " make dev-yuanqi 元炁本地推理（:11434，可选）" + @echo " make dev-core 核心三服务并行（灵台+神识+照壁）" + @echo " make dev-all 前述全部并行（不含沙箱/天目/元炁）" + @echo "" + @echo "$(YELLOW)数据库（Alembic，迁移编号 000/001/002…）$(NC)" + @echo " make db-upgrade 升级到最新（head）" + @echo " make db-downgrade 回退一步" + @echo " make db-revision m=\"说明\" 生成下一号迁移（自动编号+autogenerate）" + @echo " make db-current 查看当前版本" + @echo "" + @echo "$(YELLOW)测试与检查$(NC)" + @echo " make test 全部（后端+神识+照壁+前端）" + @echo " make test-backend / test-shenshi / test-bff / test-frontend" + @echo " make vet-shenshi go vet" + @echo " make typecheck-bff tsc --noEmit" + @echo "" + @echo "$(YELLOW)Docker 编排快捷方式$(NC)" + @echo " make infra-up / app-up / app-down" + @echo "" + @echo "$(YELLOW)清理$(NC)" + @echo " make clean / clean-all / clean-dry-run" + +# ============================== 服务启动（开发） ============================== + +dev-backend: + cd backend && uv run python -m app.main + +dev-shenshi: + cd shenshi && go run . + +dev-bff: + cd bff && npm run dev + +dev-frontend: + cd frontend && pnpm dev + +dev-sandbox: + cd sandbox && cargo run + +dev-tianmu: + cd tianmu && uv run python -m src.main + +dev-yuanqi: + cd yuanqi && uv run python -m src.main + +# 核心三服务并行：灵台 + 神识 + 照壁（M0 验收链路） +dev-core: + $(MAKE) -j3 dev-backend dev-shenshi dev-bff + +dev-all: + $(MAKE) -j4 dev-backend dev-shenshi dev-bff dev-frontend + +# ============================== 数据库（Alembic） ============================== + +# 迁移约定：revision id 与文件名前缀用三位顺序号（000、001、002…），生成统一走 +# `make db-revision`（自动取最大号+1 并传 --rev-id）；不要手写哈希 id。 +db-upgrade: + cd backend && uv run alembic upgrade head + +db-downgrade: + cd backend && uv run alembic downgrade -1 + +db-revision: + @next=$$(ls backend/alembic/versions 2>/dev/null | grep -E '^[0-9][0-9][0-9]_.*\.py$$' | cut -c1-3 | sort -n | tail -1); \ + if [ -z "$$next" ]; then echo "未找到顺序编号迁移，请先确认基线 000 存在"; exit 1; fi; \ + next=$$(printf '%03d' $$((10#$$next + 1))); \ + echo "$(GREEN)生成迁移 $(NC)$$next：$(m)"; \ + cd backend && uv run alembic revision --autogenerate --rev-id $$next -m "$(m)" + +db-current: + cd backend && uv run alembic current + +# ============================== 测试与检查 ============================== + +test-backend: + cd backend && uv run pytest -q + +test-shenshi: + cd shenshi && go test ./... + +test-bff: + cd bff && npm test --silent + +test-frontend: + cd frontend && pnpm test + +test: test-backend test-shenshi test-bff test-frontend + +vet-shenshi: + cd shenshi && go vet ./... + +typecheck-bff: + cd bff && npm run type-check --silent + +# ============================== Docker 编排快捷方式 ============================== + +infra-up: + docker compose -f docker/docker-compose.infra.yml up -d + +app-up: + docker compose -f docker/docker-compose.app.yml up -d --build + +app-down: + docker compose -f docker/docker-compose.app.yml down + +# ============================== 清理（保留原有能力） ============================== -# Main clean target clean: clean-pyc clean-pytest clean-mypy clean-empty-dirs @echo "$(GREEN)✓ Cleanup completed successfully!$(NC)" -# Clean Python cache files clean-pyc: @echo "$(YELLOW)Removing Python cache files...$(NC)" @find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true @@ -33,55 +145,35 @@ clean-pyc: @find . -type f -name "*.pyd" -delete 2>/dev/null || true @echo "$(GREEN)✓ Python cache files removed$(NC)" -# Clean pytest cache clean-pytest: @echo "$(YELLOW)Removing pytest cache...$(NC)" @rm -rf .pytest_cache 2>/dev/null || true @find . -type d -name ".pytest_cache" -exec rm -rf {} + 2>/dev/null || true @echo "$(GREEN)✓ Pytest cache removed$(NC)" -# Clean mypy cache clean-mypy: @echo "$(YELLOW)Removing mypy cache...$(NC)" @rm -rf .mypy_cache 2>/dev/null || true @find . -type d -name ".mypy_cache" -exec rm -rf {} + 2>/dev/null || true @echo "$(GREEN)✓ Mypy cache removed$(NC)" -# Remove empty directories clean-empty-dirs: @echo "$(YELLOW)Removing empty directories...$(NC)" - @# Remove empty directories (including hidden ones), excluding .git and .venv @find . -type d -empty -not -path "./.git/*" -not -path "./.venv/*" -not -path "./venv/*" -not -path "./env/*" -not -path "./.env/*" -delete 2>/dev/null || true - @# Second pass to remove newly created empty parent directories @find . -type d -empty -not -path "./.git/*" -not -path "./.venv/*" -not -path "./venv/*" -not -path "./env/*" -not -path "./.env/*" -delete 2>/dev/null || true @echo "$(GREEN)✓ Empty directories removed$(NC)" -# Clean everything (extended cleanup) clean-all: clean @echo "$(YELLOW)Removing additional files...$(NC)" - @# Coverage reports @rm -rf htmlcov .coverage coverage.xml .coverage.* 2>/dev/null || true - @# Build artifacts @rm -rf build/ dist/ *.egg-info .eggs/ 2>/dev/null || true - @# Log files @find . -type f -name "*.log" -delete 2>/dev/null || true - @# Jupyter notebooks checkpoint @find . -type d -name ".ipynb_checkpoints" -exec rm -rf {} + 2>/dev/null || true - @# IDE files (optional, uncomment if needed) - # @rm -rf .vscode/ .idea/ 2>/dev/null || true @echo "$(GREEN)✓ Extended cleanup completed!$(NC)" -# Dry run - show what would be deleted (for safety) clean-dry-run: - @echo "$(YELLOW)Dry run - files that would be deleted:$(NC)" - @echo "\nPython cache files:" + @echo "$(YELLOW)Dry run - files that would be deleted (run 'make clean' to delete):$(NC)" @find . -type d -name "__pycache__" 2>/dev/null || echo "None" @find . -type f -name "*.pyc" 2>/dev/null || echo "None" - @find . -type f -name "*.pyo" 2>/dev/null || echo "None" - @echo "\nPytest cache:" @find . -type d -name ".pytest_cache" 2>/dev/null || echo "None" - @echo "\nMypy cache:" @find . -type d -name ".mypy_cache" 2>/dev/null || echo "None" - @echo "\nEmpty directories:" - @find . -type d -empty -not -path "./.git/*" -not -path "./.venv/*" 2>/dev/null || echo "None" - @echo "$(YELLOW)\nRun 'make clean' to actually delete these files$(NC)" \ No newline at end of file diff --git a/backend/alembic.ini b/backend/alembic.ini index 10e1563..617e5f5 100644 --- a/backend/alembic.ini +++ b/backend/alembic.ini @@ -15,6 +15,10 @@ script_location = %(here)s/alembic # Or organize into date-based subdirectories (requires recursive_version_locations = true) # file_template = %%(year)d/%%(month).2d/%%(day).2d_%%(hour).2d%%(minute).2d_%%(second).2d_%%(rev)s_%%(slug)s +# 魂镜迁移编号约定（rewrite/1.0）：revision id 与文件名前缀使用三位顺序号（000、001、002…）， +# 生成统一走根目录 `make db-revision m="说明"`（自动取最大号+1 并传 --rev-id），不手写哈希 id。 +file_template = %%(rev)s_%%(slug)s + # sys.path path, will be prepended to sys.path if present. # defaults to the current working directory. for multiple paths, the path separator # is defined by "path_separator" below. diff --git a/backend/alembic/versions/843abf719fde_rewrite_1_0_基线_合并既有模式为单一起点.py b/backend/alembic/versions/000_rewrite_1_0_baseline.py similarity index 99% rename from backend/alembic/versions/843abf719fde_rewrite_1_0_基线_合并既有模式为单一起点.py rename to backend/alembic/versions/000_rewrite_1_0_baseline.py index 01850e5..d23eaeb 100644 --- a/backend/alembic/versions/843abf719fde_rewrite_1_0_基线_合并既有模式为单一起点.py +++ b/backend/alembic/versions/000_rewrite_1_0_baseline.py @@ -12,7 +12,7 @@ import sqlalchemy as sa # revision identifiers, used by Alembic. -revision: str = '843abf719fde' +revision: str = '000' down_revision: Union[str, Sequence[str], None] = None branch_labels: Union[str, Sequence[str], None] = None depends_on: Union[str, Sequence[str], None] = None diff --git a/bff/README.md b/bff/README.md index 84d7d2b..2200dd8 100644 --- a/bff/README.md +++ b/bff/README.md @@ -12,13 +12,13 @@ ## 运行 -```bash -npm install -npm run dev # 开发（tsx watch） -BACKEND_URL=http://127.0.0.1:8000 BFF_PORT=3000 npm start +统一经根目录 Makefile： -npm test # vitest -npm run type-check +```bash +make dev-bff # 开发（tsx watch，:3000） +make test-bff # vitest +make typecheck-bff # tsc --noEmit +# 首次进入 bff/ 需 npm install；环境变量默认值见 src/config.ts ``` 环境变量：`BFF_PORT`（默认 3000）、`BACKEND_URL`（默认 http://127.0.0.1:8000）、`BFF_BODY_LIMIT`、`BFF_LOG_LEVEL`。 diff --git a/docs/architecture/data-model.md b/docs/architecture/data-model.md index 54cf4da..3eabad2 100644 --- a/docs/architecture/data-model.md +++ b/docs/architecture/data-model.md @@ -168,7 +168,7 @@ erDiagram **退役删除**（旧模型，开发数据随 db 丢弃）：personality、personality_emotion、personality_versions/proposals、mood_events、character_emotion_states、drive、evolution、wuxing 相关、big_cycle、goals、plans、time_anniversaries、idle_window、suspension、uncertainty_states、curiosity_questions、exploratory_subgoals、chat_sessions/chat_messages（被镜树取代）、memory_timelines/timeline_events、knowledge_documents/memory_chunks/embedding_refs（并入记忆域新表）、candidates（并入灵胚审核）、character_situational_entries、avatar 旧表（并入形仪）。 -Alembic 基线重建：丢弃现有 4 个迁移，以本模型为新基线 `0001`；迁移与退役的执行顺序见[重写执行计划](../operations/rewrite-plan.md)。 +Alembic 基线重建：丢弃现有 4 个迁移，以本模型为新基线 `000`；迁移编号使用三位顺序号（000、001、002…），生成统一经根目录 `make db-revision m="说明"`（自动编号，不手写哈希 id）；迁移与退役的执行顺序见[重写执行计划](../operations/rewrite-plan.md)。 ## 10. 隐私与删除的落库规则 diff --git a/docs/operations/rewrite-plan.md b/docs/operations/rewrite-plan.md index 66ef49d..031f12e 100644 --- a/docs/operations/rewrite-plan.md +++ b/docs/operations/rewrite-plan.md @@ -56,7 +56,7 @@ ### 3.2 数据库 -- 丢弃 Alembic 4 个旧迁移与 `db/hunjing.db` 开发数据；按[数据模型](../architecture/data-model.md) §9 清单重建基线 `0001`。 +- 丢弃 Alembic 4 个旧迁移与 `db/hunjing.db` 开发数据；按[数据模型](../architecture/data-model.md) §9 清单重建基线 `000`（三位顺序编号，经 `make db-revision` 生成）。 - 表处置以该清单为准（保留改造 / 新建 / 退役删除三列）。 ### 3.3 frontend 旧页面 → 新去处 diff --git a/shenshi/README.md b/shenshi/README.md index 03f6f77..018c165 100644 --- a/shenshi/README.md +++ b/shenshi/README.md @@ -23,9 +23,13 @@ shenshi/ ## 本地运行 +统一经根目录 Makefile： + ```bash -SHENSHI_PORT=8080 go run . -# 灵台侧配置（backend .env）：SHENSHI_BASE_URL=http://127.0.0.1:8080 +make dev-shenshi # SHENSHI_PORT=8080 +make vet-shenshi # go vet +make test-shenshi # go test ./... +# 灵台侧联调配置（根目录 .env）：SHENSHI_BASE_URL=http://127.0.0.1:8080 ``` ## 测试