From 8ebcc11a8ab9f62f61294f22e5348f5231f1d49c 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:07:39 +0800 Subject: [PATCH] =?UTF-8?q?M0=EF=BC=9A=E7=BC=96=E6=8E=92=E6=8E=A5=E5=85=A5?= =?UTF-8?q?=E7=A5=9E=E8=AF=86=E4=B8=8E=E7=85=A7=E5=A3=81=EF=BC=88=E5=A4=A9?= =?UTF-8?q?=E9=97=A8=20/api=20=E6=94=B9=E7=BB=8F=E7=85=A7=E5=A3=81?= =?UTF-8?q?=EF=BC=89=E3=80=81.env.example=20=E6=96=B0=E5=A2=9E=E9=85=8D?= =?UTF-8?q?=E7=BD=AE=E6=AE=B5=E3=80=81SSE=20=E5=A5=91=E7=BA=A6=E8=B7=AF?= =?UTF-8?q?=E5=BE=84=E5=AF=B9=E9=BD=90=20/stream=E3=80=81=E8=83=BD?= =?UTF-8?q?=E5=8A=9B=E7=9F=A9=E9=98=B5=E4=B8=8E=E6=89=A7=E8=A1=8C=E8=AE=A1?= =?UTF-8?q?=E5=88=92=E8=90=BD=20M0=20=E8=AF=81=E6=8D=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .env.example | 25 ++++++++++++++++ docker/docker-compose.app.yml | 45 ++++++++++++++++++++++++++++ docker/nginx/nginx.conf | 12 ++++---- docs/contracts/api-contracts.md | 5 ++-- docs/operations/capability-matrix.md | 8 ++--- docs/operations/rewrite-plan.md | 3 +- 6 files changed, 85 insertions(+), 13 deletions(-) diff --git a/.env.example b/.env.example index 396270b..803f39f 100644 --- a/.env.example +++ b/.env.example @@ -665,3 +665,28 @@ SAFETY_POLICY_PATH=config/safety.yaml # BACKEND_URL=http://localhost:8000 （本地开发，跨公网须 https://） # Docker 部署由 docker-compose.app.yml 写死为 http://hunjing-backend:8000 # 浏览器所有请求同源走 BFF（/api/proxy、/api/sse、/api/auth），客户端不需要后端地址。 + + +# ===================================================================== +# 神识 · 模型网关（Go，rewrite/1.0 M0） — 灵台唯一模型出口 +# ===================================================================== +# 神识服务地址；为空时灵台 Kernel 使用进程内回声桩（仅骨架验证，不出真实模型流）。 +# 本地开发：SHENSHI_BASE_URL=http://127.0.0.1:8080（先 shenshi/ 目录 `go run .`） +# Docker 部署由 docker-compose.app.yml 写死为 http://hunjing-shenshi:8080 +SHENSHI_BASE_URL= +# 灵台 → 神识服务令牌（两边一致）；为空时神识开发档放行不校验 +SHENSHI_SERVICE_TOKEN= +# 神识流式调用超时（秒） +SHENSHI_TIMEOUT_SECONDS=120.0 +# 神识服务监听端口（shenshi 服务自身） +SHENSHI_PORT=8080 + + +# ===================================================================== +# 照壁 · BFF（Fastify，rewrite/1.0 M0） — 鉴权透传 / SSE 直通 +# ===================================================================== +# 照壁监听端口 +BFF_PORT=3000 +# 照壁转发的灵台地址；本地开发默认 http://127.0.0.1:8000 +# Docker 部署由 docker-compose.app.yml 写死为 http://hunjing-backend:8000 +BACKEND_URL=http://127.0.0.1:8000 diff --git a/docker/docker-compose.app.yml b/docker/docker-compose.app.yml index a4999ad..45af47c 100644 --- a/docker/docker-compose.app.yml +++ b/docker/docker-compose.app.yml @@ -56,6 +56,8 @@ services: NEBULAGRAPH_HOST: hunjing-nebula-graphd MINIO_ENDPOINT: http://hunjing-minio:9000 STORAGE_PROVIDER: ${STORAGE_PROVIDER:-local} + # rewrite/1.0：模型出口走神识网关（覆盖 .env 默认空值；令牌经 env_file 注入） + SHENSHI_BASE_URL: http://hunjing-shenshi:8080 volumes: # bind mount 到 /app 下的对应目录，使 .env 相对路径 ../logs ../db ../storage ../config 生效。 - ../logs:/app/logs @@ -71,6 +73,47 @@ services: limits: { memory: 1G } reservations: { memory: 256M } + # ============================== 神识 · 模型网关（Go，rewrite/1.0 M0） ============================== + # 灵台唯一模型出口：IR 入站 → 适配器（当前 stub，云 Provider/元炁按 M4 接入）→ SSE 出站。 + # 鉴权：SHENSHI_SERVICE_TOKEN 经 env_file 注入；未配置时开发档放行。 + hunjing-shenshi: + build: + context: ../shenshi + dockerfile: ../docker/shenshi/Dockerfile + image: hunjing-shenshi:latest + container_name: hunjing-shenshi + restart: unless-stopped + networks: [hunjing-net] + env_file: + - ../.env + environment: + SHENSHI_PORT: "8080" + deploy: + resources: + limits: { memory: 256M } + reservations: { memory: 64M } + + # ============================== 照壁 · BFF（Fastify，rewrite/1.0 M0） ============================== + # 客户端与灵台之间的无状态通道：鉴权透传、SSE 直通、响应透传。无业务规则、无权威数据。 + hunjing-bff: + build: + context: ../bff + dockerfile: ../docker/bff/Dockerfile + image: hunjing-bff:latest + container_name: hunjing-bff + restart: unless-stopped + networks: [hunjing-net] + environment: + BFF_PORT: "3000" + BACKEND_URL: http://hunjing-backend:8000 + depends_on: + hunjing-backend: + condition: service_started + deploy: + resources: + limits: { memory: 256M } + reservations: { memory: 64M } + # ============================== 琉璃镜 · 前端 Next.js（Frontend） ============================== hunjing-frontend: build: @@ -228,6 +271,8 @@ services: depends_on: hunjing-backend: condition: service_started + hunjing-bff: + condition: service_started hunjing-frontend: condition: service_started deploy: diff --git a/docker/nginx/nginx.conf b/docker/nginx/nginx.conf index 588dc0f..22073e3 100644 --- a/docker/nginx/nginx.conf +++ b/docker/nginx/nginx.conf @@ -1,9 +1,9 @@ # 天门 · 魂镜统一入口反向代理（Nginx，可选，profile: nginx）。 -# 对外只暴露 80：/api/* 与 SSE 走后端，其余走前端 Next.js。 -# 启用前需先启动 backend 与 frontend；详见 docker/README.md。 +# 对外只暴露 80：/api/* 与 SSE 经照壁（BFF）走灵台，其余走前端 Next.js。 +# 启用前需先启动 backend、bff 与 frontend；详见 docker/README.md。 -upstream hunjing_backend { - server hunjing-backend:8000; +upstream hunjing_bff { + server hunjing-bff:3000; keepalive 32; } @@ -19,9 +19,9 @@ server { # 适配人物资料 / 感知文件上传（IMPORT_MAX_FILE_MB 等）。 client_max_body_size 64m; - # ============================== 后端 API 与 SSE 流 ============================== + # ============================== API 与 SSE 流（经照壁） ============================== location /api/ { - proxy_pass http://hunjing_backend; + proxy_pass http://hunjing_bff; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; diff --git a/docs/contracts/api-contracts.md b/docs/contracts/api-contracts.md index 8f88012..2f8bee7 100644 --- a/docs/contracts/api-contracts.md +++ b/docs/contracts/api-contracts.md @@ -74,9 +74,10 @@ POST /api/v1/nodes/{id}/citations # 建立引文锚 ```text POST /api/v1/runs # 发起前台 Run（问节应答等）；命台忙返回 HJ-1101+队列位 GET /api/v1/runs/{id} # 状态与轨迹（可读摘要、证据、工具轨迹） +GET /api/v1/runs/{id}/events # JSON 事件时间线（读模型，按 sequence 升序） +GET /api/v1/runs/{id}/stream # SSE 事件流（见 §4） POST /api/v1/runs/{id}/steer # 运行中插话（入队，下一 turn 生效） POST /api/v1/runs/{id}/cancel -GET /api/v1/runs/{id}/events # SSE（见 §4） GET /api/v1/characters/{id}/queue # 前台队列 ``` @@ -140,7 +141,7 @@ GET /api/v1/me/usage # 用量与成本 ## 4. SSE 协议 -- 端点：`GET /api/v1/runs/{id}/events`（运行流）；镜树页可另订阅树级合并流 `GET /api/v1/trees/{id}/events`。 +- 端点：`GET /api/v1/runs/{id}/stream`（运行流；与既有前端约定一致）；`GET /runs/{id}/events` 为 JSON 事件时间线读模型；镜树页后续可另订阅树级合并流 `GET /api/v1/trees/{id}/stream`。 - 帧格式： ```text diff --git a/docs/operations/capability-matrix.md b/docs/operations/capability-matrix.md index 98ec2cc..533ce7d 100644 --- a/docs/operations/capability-matrix.md +++ b/docs/operations/capability-matrix.md @@ -19,18 +19,18 @@ | 能力 | 里程碑 | 当前状态 | 说明与缺口 | | --- | --- | --- | --- | -| 灵台 Kernel 与插件运行时 | M0 | 未实现 | 事件溯源、投影、插件装配、硬核不变量均待建；旧 runtime 模块待退役 | +| 灵台 Kernel 与插件运行时 | M0 | 局部实现 | M0 骨架已验证（本地开发档，2026-08-21）：`backend/tests/test_kernel.py` 5 用例（事件序列/命台串行/否决/不变量/SSE），Kernel 经 DbEventStore 事件溯源；投影仍为占位，九枢插件与禁域裁决待 M2+/M5 | | 镜生闭环（灵胚/启镜/魂籍/命台） | M1 | 未实现 | 旧 characters 表将重建；命台唯一性无实现 | | 镜树对话（问节/候答/采用/归真/引文/移栽） | M2 | 未实现 | 现有 chat 为线性会话，将被替换删除 | | 三级记忆（微痕/明忆/重忆/实录/心痕） | M3 | 未实现 | 旧 memory/extraction 模块待退役；新管线未建 | -| 神识 Go 网关 | M4 | 未实现 | 现为 Python ai_provider 过渡承载，重写期间一次性替换 | +| 神识 Go 网关 | M4 | 局部实现 | M0 骨架已上线（2026-08-21）：IR 入站/SSE 出站/stub 适配器/服务令牌/健康检查，`go test` 5 用例，与灵台 HttpShenshiClient 联调通过；云 Provider 与元炁端点、路由冷却计量待 M4 | | 百工与司命（授契/行契/请命/禁域/行动账） | M5 | 局部实现 | 乾坤沙箱（HMAC/进程隔离）已有工程与测试；能力注册与四维裁决待重写 | | 缘契/人格演进/河图世界 | M6 | 未实现 | 旧 personality/drive/evolution/world 待退役 | | 形仪与语音（真形/Live2D/TTS/ASR/通感） | M7 | 局部实现 | 天目 OCR、元炁本地推理可用；形仪域未建 | | 天工阁/叩心/辰正 | M8 | 未实现 | 旧 agent/knocking/time_sense 待退役重实现 | -| 照壁 BFF | M0 | 未实现 | Fastify 骨架待建 | +| 照壁 BFF | M0 | 局部实现 | M0 骨架已验证（2026-08-21）：头透传/SSE 直通/错误映射 4 用例；登录→占位 Run→SSE 三服务（照壁/灵台/神识）E2E 冒烟通过；响应裁剪与聚合待 M2+ | | 镜匣桌面壳 | M9 | 未实现 | Tauri 最小壳待建 | -| 基础设施复用（auth/RBAC/审计/事件/幂等/SSE） | M0 | 局部实现 | 旧实现可用，待重组入 `infra/` 并对接六域 | +| 基础设施复用（auth/RBAC/审计/事件/幂等/SSE） | M0 | 局部实现 | auth/事件存储/SSE 已被 Kernel 复用（POST /runs 验收链路）；重组入 `infra/` 待后续里程碑 | | 乾坤沙箱 | M5 | 局部实现 | 隔离执行/HMAC/超时取消已有；设备安全与双裁决待扩 | | 博闻 MCP 搜索 | M5 | 局部实现 | 多引擎/密钥池/熔断/缓存可用；待登记入百工 | | 天目 / 元炁 | M4/M7 | 局部实现 | 服务可用；元炁待接入神识 Endpoint，天目待接通感 | diff --git a/docs/operations/rewrite-plan.md b/docs/operations/rewrite-plan.md index 798d7f1..66ef49d 100644 --- a/docs/operations/rewrite-plan.md +++ b/docs/operations/rewrite-plan.md @@ -77,10 +77,11 @@ > 编号为实施顺序；每个里程碑末尾的"验收"是进入下一个的硬门。 -### M0 地基（骨架先行） +### M0 地基（骨架先行）— ✅ 已完成（2026-08-21） - 交付：Kernel 骨架（不变量裁决器/命台控制/事件日志接口/循环骨架）、事件总线与插件加载、`shenshi_client` 边界（先指向临时 stub）、BFF 骨架（鉴权透传+SSE 代理）、神识骨架（ingress/transform 占位实现 + 元炁 endpoint）、Alembic 新基线、Compose 更新（+hunjing-bff/+hunjing-shenshi）。 - 验收：登录（复用 auth）→ 创建占位 Run → SSE 端到端流到浏览器（经照壁）；"模型可见即可重建"断言在 stub 上可跑；旧 chat/memory 模块仍可用但不再新增调用。 +- 证据：`backend/tests/test_kernel.py` 5 用例（事件序列/命台串行/否决/不变量/流式）；`shenshi` `go test` 5 用例；`bff` vitest 4 用例；三服务（照壁 18100 / 灵台 18000 / 神识 18081）真实进程 E2E 冒烟：注册→登录→POST /api/v1/runs→SSE 流读至 run.finished，模型流经 Go 神识 stub（"【神识回声桩】"前缀可证）；全量后端回归 925 passed（另有 20 个预存失败，根因本地缺 `config/models.yaml`，与本次改动无关，stash 验证）；Alembic 基线合并为单一迁移（41 表，空库 upgrade 干净）。 ### M1 镜生闭环（灵胚→启镜→魂籍→命台）