给 ContextForge Core 套一个**本地优先（local-first）**的可视化控制台 —— 把「索引 → 检索 → rerank → memory → Agent 回答 → citation → eval」整条链路可视化、可操作、可观测。
ContextForge Console 是一个面向自建 ContextForge Core 的个人开发者与 1-5 人 AI 应用团队的领域专属控制平面。 它不是通用 LLM observability 平台，而是以 workspace / index job / source file / source chunk / retrieval method / rerank result / memory item / agent scope / citation / eval run / Core adapter 为一等对象， 帮助开发者：
- 把单 query 召回排查从 10-20 分钟降到 < 3 分钟
- Agent 答错时 1 分钟内下钻到对应 retrieval trace / citation / source chunk
- 新成员半天内跑通 workspace / index / search / eval 基础流程
v1.0 产品形态为 Local Console / 单用户模式（团队成员各自本地运行）；不做公网 SaaS / 多用户 RBAC / SSO / 移动原生。
- Workspace & Index 控制平面 —— 触发并监控索引任务，展示 parse / chunk / embed / index 阶段进度
- Search Lab（核心 happy path）—— 端到端检索调试，vector / keyword / hybrid 对比 + rerank 前后排名
- MemoryOps 记忆治理 —— pin / deprecate / soft delete，破坏性操作二次确认
- Eval 评估报告 —— 默认对比最近 5 次 run，指标 recall@k / precision + 用例级 diff
- 统一可观测性 —— SSE 实时推送，版本化 Core Integration Contract v1 + 多 Adapter 隔离
| 层 | 技术 |
|---|---|
前端 console-web/ |
Next.js 16 + React 19 + TypeScript 6.0 + Tailwind CSS v4 + Radix UI + TanStack Query |
后端 console-api/ |
Go 1.26 + Gin + PostgreSQL（lib/pq）+ Redis（go-redis）+ OpenAPI 3.0.3（kin-openapi 程序化生成） |
| 编排边界 | coreadapter —— Console ↔ Core 唯一适配层（mock / http / grpc / cli 四形态，ADR-001） |
| 测试 | Go testify + Vitest + Playwright（Mock Adapter 作 Core 替身，ADR-006） |
| 部署 | Docker Compose 一键起全栈（ADR-007）；后端 distroless 静态镜像，前端 Node alpine |
cp .env.example .env # 按需修改（POSTGRES_PASSWORD 等）
docker compose up -d # 起 postgres + redis + core-mock + console-api + console-web打开 http://localhost:3000 即可访问控制台。服务拓扑：
| 服务 | 端口（仅 localhost bind） | 说明 |
|---|---|---|
console-web |
3000 | Next.js 前端 |
console-api |
8080 | Gin BFF，默认 mock 模式 |
postgres |
—（内部） | 持久化（store=pg 时消费） |
redis |
—（内部） | ADR-003 预留（v1.0 尚未消费） |
core-mock |
—（内部） | 占位服务 |
接真实 ContextForge daemon（默认不启）：编辑 .env 设 CONSOLE_API_CORE_MODE=http +
CONSOLE_API_CORE_HTTP_BASE_URL=http://contextforge:48181，然后：
docker compose --profile contextforge pull contextforge
docker compose --profile contextforge up -d contextforge
docker compose up -d console-api console-web首启会在挂载的
console-tokenvolume 生成 local access token（crypto/rand，权限 0600）。
# 后端 BFF（默认 mock 模式，:8080）
cd console-api
go run ./cmd/console-api
# 前端（:3000，热更新）
cd console-web
pnpm install
pnpm dev环境变量详见 .env.example（每个变量均有用途与默认值注释）。
ContextForge-Console/
├── console-api/ # Go BFF 后端（Gin + coreadapter 单一边界）
│ ├── cmd/console-api/ # 程序入口（main 装配序）
│ └── internal/ # coreadapter / httpapi / jobs / memory / eval / search / workspace
│ # / store / security / observability / platform
├── console-web/ # Next.js + React 前端
│ └── src/ # app (App Router) / features / components / hooks / lib
├── docs/ # PRD / ADR / phase & task specs / 设计与集成文档
├── test/ # 跨模块 BDD features/*.feature + fixtures
├── tools/ # s2v 聚合脚本（install / typecheck / unit-test）
├── docker-compose.yml # 一键起全栈
└── AGENTS.md # 协作约定（S2V 方法论 + worktree + PR 规范）
bash tools/s2v-install.sh # 前后端依赖安装
bash tools/s2v-typecheck.sh # go vet + tsc --noEmit
bash tools/s2v-unit-test.sh # go test + vitest（强制 required）CI（.github/workflows/ci.yml）在 PR / push 到 master 时自动跑这三步。
cd console-web
pnpm test # Vitest 单元测试
pnpm exec playwright test # Playwright e2e（需先起 stack + 配 PLAYWRIGHT_TOKEN）| 文档 | 说明 |
|---|---|
docs/prds/contextforge-console.prd.md |
产品需求文档（Vision / Users / Core Capabilities / Out-of-Scope） |
| 架构决策（ADR） | |
docs/decisions/adr-001-coreadapter-single-boundary.md |
coreadapter 单一边界 |
docs/decisions/adr-002-frontend-go-stack.md |
前端 Next.js/React + 后端 Go/Gin 选型 |
docs/decisions/adr-003-postgres-redis-persistence.md |
PostgreSQL + migration + schema_version / Redis 任务态 |
docs/decisions/adr-004-rest-openapi-sse.md |
REST + OpenAPI + SSE 协议选型 |
docs/decisions/adr-005-secure-by-default.md |
secure-by-default 默认收敛 |
docs/decisions/adr-006-test-toolchain-mock.md |
测试工具链 + Mock Adapter |
docs/decisions/adr-007-docker-compose-release.md |
v1.0 主发布 Docker Compose |
docs/decisions/adr-008-contract-v1-adapters.md |
Contract v1 + 四 Adapter 形态 |
| 规格（SDD/BDD/TDD） | |
docs/specs/phases/ |
7 个 Phase spec（foundation → platform-baseline → workspace-index → search-lab → memory-ops → eval-reports → integration） |
docs/specs/tasks/ |
24 个 Task spec（每个含 AC / Behavior Contract / Traceability / Verification Plan） |
docs/s2v-adapter.md |
S2V 适配层（项目结构 / 命令 / Task 总索引） |
本项目使用 S2V（Spec-Driven + Behavior-Driven + TDD） 方法论，协作档位 solo-autonomous。
任何 Agent / 贡献者进入本仓库第一件事：读完 AGENTS.md（worktree 隔离 + R1-R7 铁律 +
PR-only merge gate + commit 节律）。简要：
- 分支命名：
feat/<phase>-<name>/feat/task-<X.Y>-<name>/chore/<scope>/fix/<scope> - PR-only：所有改动经 PR
merge --no-ff合入master，禁止主 repo 直接 commit - worktree 隔离：实施在独立 worktree（
ContextForge-Console-wt-<scope>/），主 repo HEAD 恒在master - 三段 commit：RED（test）→ GREEN（feat）→ REFACTOR + docs 回填