voike (Rishhhhh)

VOIKE🌊

FLOW原生AI平台

一切都通过FLOW。构建、部署、查询和进化——所有这些都在FLOW中完成。

安装

pip install voike --upgrade

快速开始

# Create new project
voike init my-ai-app

# Build
voike build

# Run tests
voike test

# Ask AI agent
voike agent ask "What is VOIKE?"

# Ingest data
voike ingest data.csv

# Deploy
voike deploy production

什么是FLOW？

FLOW是VOIKE用于AI操作的声明性语言。VOIKE中的所有内容——从数据摄取到代理编排再到系统部署——都表示为FLOW。

示例流程：

FLOW "My First Flow"

INPUTS
  text question
END INPUTS

STEP ask_agent =
  CALL FLOW "flows/lib/ai/agents.flow"
    WITH {
      "question": question
    }

STEP output =
  OUTPUT_TEXT ask_agent.answer

END FLOW

特性

• 并行执行 -独立操作同时运行（速度提高3.5倍）
• VASM集成 -编译组装的热路径
• 自我寄宿 -VOIKE通过FLOW进行自我管理
• 代理本地 -AI代理可以直接修改流
• 热可重新加载 -更改流程而不重新启动
• pip可安装 -一个安装命令

建筑

VOIKE
├── FLOW Runtime (parallel execution)
├── VASM (assembly execution)
├── VVM (virtual machine deployment)
└── Everything is FLOW

文档

• FLOW语言指南
• api参考
• 示例

许可证

麻省理工学院

______________________________________________________________________

一切都在流动。 🌊 核心•人工智能•聊天

一个后端，一个API密钥，三个功能。 VOIKE 核心 存储数据和blob并运行计算。 大AI 从这些数据中学习，并建议更好的流程。 VOIKE聊天 是由知识结构驱动的每个项目的副驾驶。

Clients / CLI / SDK
        │
        ▼
HTTP API + MCP Tools ──► Kernels + Truth Ledger
        │
        ▼
Hybrid DB + BlobGrid + Compute Grid

1.声音一瞥

一切都由 X-VOIKE-API-Key.为每个项目分配自己的密钥。无跨项目泄漏。

______________________________________________________________________

2.快速入门（5分钟）

2.1 小船

Genesis节点（Linux，第一台服务器）

使用Genesis only compose文件，以便规范节点在其他节点连接之前与自己的本地Postgres进行通信：

git clone https://github.com/Rishhhhh/voike.git
cd voike
cp .env.example .env   # set GENESIS_* + VOIKE_PUBLIC_* as needed
docker compose -f deploy/compose/voike-genesis.compose.yml up -d --build

其他节点（Mac/Windows/Linux）

所有其他节点都指向Genesis节点上运行的共享Postgres（默认为 voike.supremeuf.com:5432 在 .env.example):

git clone https://github.com/Rishhhhh/voike.git
cd voike
cp .env.example .env   # edit any overrides
docker compose up -d --build

就是这样。每个依赖项（后端、Postgres、POP堆栈）都在Docker内部构建——没有本地 npm install，没有额外的种子，没有手动脚本。一旦组合堆叠完成， / 提供文档登录页面和 /info 暴露与JSON相同的有效载荷。带 .env 有了你（或在原地编辑），完全相同的命令在NAT、笔记本电脑、裸机、隧道、静态IP、AWS、GCP——任何有Docker和出站互联网的地方——都能工作。

在Windows（PowerShell）上：

git clone https://github.com/Rishhhhh/voike.git
cd voike
powershell -ExecutionPolicy Bypass -File scripts\run_voike_windows.ps1

想要完整的建筑叙事吗？阅读 docs/whitepaper.md.需要API级别的详细信息？看 docs/api.md.

文档地图

2.1.1共享Postgres（多节点）

如果你想让多个VOIKE节点（Mac+Linux，edge+core）共享同一个控制平面数据库，请在启动Docker之前在每台机器上运行辅助脚本：

# Replace the URL with your managed/remote Postgres instance
VOIKE_SHARED_DATABASE_URL=postgres://user:pass@host:5432/voikex \
node scripts/set_shared_db.js

这改写了 .env 指向 DATABASE_URL 在共享实例中 /mesh/nodes 和 /grid/jobs 跨节点同步。

2.2获取API密钥（游乐场路线）

curl -X POST http://localhost:8080/admin/projects \
  -H 'content-type: application/json' \
  -H 'x-voike-admin-token: ' \
  -d '{ "organizationName": "demo", "projectName": "playground", "keyLabel": "primary" }'

响应包括 project.id + apiKey.key。对每个受保护的端点使用该密钥。

2.3摄取+查询

VOIKE_API_KEY=

curl -X POST http://localhost:8080/ingest/file \
  -H "x-voike-api-key: $VOIKE_API_KEY" \
  -H "content-type: multipart/form-data" \
  -F "file=@examples/demo.csv"

curl -X POST http://localhost:8080/query \
  -H "x-voike-api-key: $VOIKE_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "kind": "hybrid", "sql": "SELECT * FROM demo WHERE score > 90" }'

VOIKE检测格式，创建表，混合查询结合SQL+语义搜索。

2.4询问知识结构

curl -X POST http://localhost:8080/ai/ask \
  -H "x-voike-api-key: $VOIKE_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "question": "What changed this week?" }'

AI使用从摄取/查询/blob/grid/分类账事件中提取的摘要进行回复。通过以下方式控制可见性 /ai/policy.

2.5聊天

curl -X POST http://localhost:8080/chat \
  -H "x-voike-api-key: $VOIKE_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "message": "Show me top customers this month" }'

退货：

{ "sessionId": "...", "reply": "...", "policy": "summaries", "answers": [...] }

后续消息包括 sessionId 保持上下文。VOIKE存储记录和动作。

2.6第1阶段——Genesis/控制平面引导

在规范节点上运行一次此操作（例如。， voike.supremeuf.com)用权威的DNS+解析器元数据为控制平面Postgres种子。每一个未来 docker compose up -d --build 然后将通过以下方式读取状态 GENESIS_BOOTSTRAP=1.

# assumes GENESIS_ADMIN_TOKEN/VOIKE_ADMIN_TOKEN is set
node scripts/genesis_seed.js \
  --core-url https://voike.supremeuf.com \
  --zones config/vdns-zones.json \
  --endpoints config/snrl-endpoints.json

播种后，对控制平面进行烟雾测试：

curl -H "x-voike-admin-token: $GENESIS_ADMIN_TOKEN" https://voike.supremeuf.com/vdns/zones
curl -H "x-voike-admin-token: $GENESIS_ADMIN_TOKEN" https://voike.supremeuf.com/snrl/endpoints
curl -H "x-voike-api-key: 
" -d '{ "domain": "api.voike.com" }' \
  https://voike.supremeuf.com/snrl/resolve

节点与 GENESIS_BOOTSTRAP=1 现在，在为流量提供服务之前，自动获取种子区域/端点。

2.7第4阶段-自动引导+自动注册（永远只需一个命令）

第一阶段完成后，每个额外的VOIKE节点（后端+POP堆栈）都可以通过一个命令启动和注册：

docker compose up -d --build

Genesis的后端会自动水合(GENESIS_BOOTSTRAP=1)，为自己做广告(GENESIS_REGISTER=1)，POP容器立即开始为DoH/UDP/TCP提供服务。看 docs/phase4_auto-bootstrap.md 用于验证提示和环境覆盖。

2.8第5阶段——代理自我进化+CI/CD

• flows/voike-self-evolve.flow 现在对完整的Planner进行编码→ 代码生成→ 测试员→ 基础设施→ 产品循环。使用它将任何Markdown规范转换为编排步骤。
• 特工们跑过去 EvolutionAgentService，所以每 RUN AGENT 呼叫创建/更新 /orchestrator/tasks 自动记录（无存根处理程序）。规划师阅读 docs/phase5_agents.md 默认情况下；通过 featureSpecOverride 从CI流式传输内联规范。
• .github/workflows/agentic-flow.yml 调用 /flow/plan + /flow/execute 使用游乐场API。配置 VOIKE_API_URL, VOIKE_API_KEY，以及 VOIKE_PROJECT_ID secrets和工作流会在每次推送/PR上打印产品代理摘要。
• 检测仪解析已更改 .flow 通过FLOW编译器编译文件，并确保引用的文件存在；Infra发出部署/胶囊命令，因此演示可以通过单个命令保持可重复性 docker compose up -d --build.
• 看 docs/phase5_agents.md 对于规范模板、curl示例和游乐场提示。
• 新的代理注册表端点(POST /agents, GET /agents, GET /agents/:id, GET /agents/classes)让您为每个项目持久化模块2代理定义。 GET /agents/classes 返回的规范功能/工具 system, kernel, network, database, file, security, developer，以及 user 类，这样Codex/LLM就可以自动填充注册表项。
• 模块3运行时带来 POST /agents/:id/run （加 GET /agents/tools)因此，注册代理可以调用规范工具(log.emit, ai.ask, flow.execute, grid.submit)通过中描述的Supervisor/Router/Worker循环 docs/voike-agents-module3.md.

2.9第6阶段——部署工具和CI/CD（游乐场或DIY）

• 两份专门的部署指南(docs/deployment_docker.md, docs/deployment_baremetal.md)浏览Compose/Helm集群或裸机安装——选择“与我们一起运行VOIKE”（连接到游乐场）或“自己运行VOIKE“并自动加入去中心化网络。
• .env.example 现在列出每个 VOIKE_NODE_*Genesis、POP和SNRL变量是自动引导/注册所必需的，因此即插即用节点从零猜测开始。
• 参考模板已上线 deploy/compose/voike-playground.compose.yml 和 deploy/helm/voike/ （部署+服务+价值观）。将它们放入Docker或Kubernetes中，以快速启动FLOW/VASM/VVM堆栈。
• 辅助脚本(scripts/make_capsule_snapshot.py, scripts/export_ledger.py, scripts/verify_pop.py)从笔记本电脑或CI处理胶囊快照、分类账导出和POP验证。
• 其他GitHub操作(flow-tests.yml, snapshot-ci.yml)显示如何直接针对游乐场API运行FLOW计划检查和Capsule快照。复制它们以保持你自己的仓库同步。

每个部署故事（云、裸机、NAT、隧道）仍然减少到 复制 .env → docker compose up -d --build.中的默认值 .env.example 使新节点从Genesis和自注册中水合，这样您就永远不会运行额外的引导命令。

2.10第7阶段-多平台适配器（Firebase/Supabase、Flask、React、Rust、Postgres）

• 新适配器模板位于 adapters/ 带有Firebase/Supabase、Flask、React、Rust和Postgres的专用README/代码。
• 每个适配器都演示了双写、影子模式和故障转移逻辑（包括VDNS/SNRL查找），因此您可以在不停机的情况下通过VOIKE重新路由现有应用程序。
• docs/migration_guides.md 解释如何推出双写→ 阴影→ 跨堆栈的故障转移阶段，参考提供的适配器。
• 模板包括回退缓存（React钩子+Flask蓝图）、worker模式（Rust）和SQL触发器（Postgres），因此“与我们一起运行VOIKE”或“自己运行VOIKE）只需一次复制/粘贴即可。

2.11第8阶段——弹性工具和离线运营

• 新的账本回放+锚定API(POST /ledger/replay, POST /ledger/anchor)驱动快照、审计和回滚循环。
• CLI帮助程序(scripts/ledger_replay.py, scripts/offline_sync.py)重播仅附加账簿，离线同步缓存，并与配对 docs/resilience_playbooks.md 以获取完整的停机剧本。
• 胶囊快照工具+ snapshot-ci.yml 将可复制的工件放在手边；混沌指南（第8阶段文档）展示了如何模拟DNS/云中断，并在之后验证POP健康状况。
• README+文档涵盖了回滚/回放+离线说明，因此运维团队可以在需要时完全断开连接运行VOIKE。

______________________________________________________________________

3.VOIKE核心（数据•块•计算）

3.1摄入/查询

• POST /ingest/file –检测格式，创建表，记录作业。
• GET /ingest/{jobId} –状态/摘要。
• POST /query SQL、语义或混合查询；返回更正的查询+指标。
• GET /kernel/state –VAR能量、DAI提示和查询限制。
• GET /ledger/recent / GET /ledger/{id} –每个项目的真相分类账条目。

3.2 BlobGrid

• POST /blobs –上传（复制或擦除编码）。
• GET /blobs/{id}/manifest –块+存储元数据。
• GET /blobs/{id}/stream –返回文件（缓存的针脚+远程块）。
• /blobgrid 自动馈送IRX+边缘缓存；上传视频是一个很棒的游乐场演示（在一个客户端上传，从另一个客户端流式传输）。

3.3网格作业/VVM/胶囊

• POST /grid/jobs –提交 llm.infer, media.transcode, query.analytics，定制工作。
• GET /grid/jobs/{id} –状态/结果/日志。
• POST /vvm + POST /vvm/{id}/build –包装工作负载并构建工件。
• POST /capsules / GET /capsules/{id} / POST /capsules/{id}/restore –快照和恢复整个宇宙（模式+blobs+VVM）。

3.4无限与网格（适用于作战团队）

• GET /infinity/nodes, /infinity/pools –参见提供商/地区/成本元数据；使用选择器/策略创建池。
• GET /mesh/self, /mesh/nodes, /genesis –检查节点标识和集群配置。

______________________________________________________________________

4.VOIKE AI（知识结构）

人工智能被动地监视摄取、查询、blob、网格和分类账流。它构建：

• 知识地图集 (/ai/atlas, /ai/atlas/table/:table)
• 知识结构问答 (/ai/policy, /ai/ask)
• 行动分流 (/ai/ops/triage)提供runbook建议
• IRX热图 (/ai/irx/*)
• 管道方案 (/ai/pipelines/analyze)
• 胶囊叙事 (/ai/capsule/summary, /ai/capsule/timeline)
• 建议 (/ai/suggestions 批准/拒绝）

通过以下方式更改数据可见性 /ai/policy (none, metadata, summaries, full).默认值为 summaries.

遥测接线：

• /ingest + /query + /blobs + /grid/jobs + /ledger 事件自动创建知识节点(ai_knowledge_nodes).
• 使用 python scripts/voike_heartbeat.py 用于快速健康探测（核心+AI端点）。
• 跑 python scripts/voike_regression.py 用于全烟测试（摄入→ 怎么翻译→ MCP → AI → 网眼）。脚本会自动加载 .env 因此，在每个节点上，相同的管理/项目令牌用于账簿回放、FLOW、SNRL和VDNS检查。

______________________________________________________________________

5. VOIKE聊天

聊天会话存储在 chat_sessions + chat_messages.每个 POST /chat 呼叫：

1. 确保会话存在（如果不存在，则创建一个会话）。
2. 保存用户消息。
3. 呼叫 /ai/ask 获取知识结构答案。
4. 保存助理回复（包含策略+操作）。

终点：

• POST /chat –发送消息（可选 sessionId).
• GET /chat/sessions –列出最近的会话。
• GET /chat/sessions/{id}/messages –获取成绩单（角色、动作）。

使用聊天数据发现重复出现的模式；AI已经使用它来建议HyperFlows通过 /ai/pipelines/analyze → /ai/suggestions.

______________________________________________________________________

6.语音流（语义计划）

• FLOW将长格式代码（Python/C++/SQL/TF）转换为紧凑的、基于步骤的计划。
• REST/APIX端点：

- POST /flow/parse → 验证FLOW源（返回AST+警告）。 - POST /flow/plan → 将FLOW源代码编译成计划图（按项目存储，返回 planId +节点/边）。 - POST /flow/execute → 运行计划同步或异步（网格作业；返回输出/指标或异步 jobId). - GET /flow/plans, GET /flow/plans/{id}, DELETE /flow/plans/{id} –管理计划。 - GET /flow/ops → 发现可用的FLOW op合同； GET /flow/ops/{name} → 检查特定操作。

• 打开 /playground/flow-ui 在VOIKE部署中获得Tailwind FLOW游乐场（粘贴API键，点击Parse/Plan/Execute，请参见AST/Plan/outputs）。配合使用效果很好 VOIKE_PLAYGROUND_API_KEY 用于演示。
• LLM代理使用FLOW规范+APIX操作自动生成计划。

堆栈概述

1. 适配器/源 –Python、C/C++、Rust、SQL、TypeScript、TF图、ONNX、笔记本电脑、自然语言规范。适配器解析这些并发出FLOW。
2. 流动 –声明性、基于步骤的计划(*.flow).语法简洁，易于人类/LLM。
3. 执行计划图 –FLOW编译成具有IRX/调度元数据的图节点（FLOW_OP、VASM块、VVM作业）。
4. VASM –微小的、与架构无关的VM指令（算术、控制流、VOIKE系统调用）。
5. 硬件/网格 –由VOIKE（Infinity Fabric，IRX遥测）编排的CPU/GPU/边缘节点。

关键概念

• FLOW操作码 涵盖语义动作(LOAD CSV, FILTER, GROUP, RUN_JOB, RUN_AGENT).操作已版本化(OP@MAJOR.MINOR)因此，计划保持稳定。
• 元编排操作 (APX_EXEC, BUILD_VPKG, DEPLOY_SERVICE, OUTPUT_TEXT)在FLOW中可用，因此相同的计划可以直接通过VOIKE描述仓库引导、打包和部署。
• 代理编排 – EvolutionAgentService 权力 planner, codegen, tester, infra，以及 product 代理人使用 flows/voike-self-evolve.flow。每次通话记录到 /orchestrator/tasks 在以下情况下自动并可选地使用GPT OPENAI_API_KEY 提供。
• VVM 描述符 用环境要求和IO模式包装外部运行时（Python、C++、TF-Service等）。
• 代理 通过调用APIX贡献FLOW(flow.parse/plan/execute, agent.* ops）并登录到 /orchestrator/tasks.
• 胶囊 快照流+计划+再现性工件。
• flows/voike-regression.flow 是完整回归运行的编码版本：它接收样本数据，运行混合查询，分派网格斐波那契作业，构建VPKG，部署服务，并捕获一个capsule，这样您就可以通过VOIKE本身重放整个烟雾测试。
• 这 APX_EXEC "source.readFile" target从repo根读取规范并回退到内联文本(featureSpecOverride)因此，CI/CD作业可以在不挂载文件系统的情况下流式传输规范。

目标

• 通用：任何语言/框架都会变成FLOW计划+VPKG部署。
• 紧凑：大型命令式代码压缩为约10-20个FLOW步骤。
• 安全稳定：操作是版本化的；只有当你选择加入时，计划才会改变。
• 可优化的：计划图元数据允许IRX/DAI/AI Fabric调度和改进工作流程。

动态语言运行时（VVM+容器）

FLOW不要求主机操作系统提供每个SDK。相反：

• 每次运行时构建瘦容器映像（例如。， mcr.microsoft.com/dotnet/sdk:8.0)并将其注册为环境描述符(voike env add examples/vvm/dotnet-env.yaml).后端已经在macOS+Linux上通过Docker隧道传输描述符，因此相同的映像可以在任何地方运行。
• 创建一个VVM描述符，通过名称/ID引用环境变量，并对运行的命令进行编码(examples/vvm/dotnet-vvm.json).描述符列出了VOIKE应注入容器的项目文件/工件。
• 当流量（或 /vvm/:id/build)需要运行时，网格作业会拉取声明的映像，执行命令，并返回日志/工件——不需要主机级的dotnet/python/java安装。
• 通过交换基本image/命令，对Python、Java、npm等重复上述操作；FLOW+VVM保持合约一致，而Docker保证笔记本电脑之间的对等性+ voike.supremeuf.com.

7.CLI、脚本和VPKG

• npm run lint –TypeScript类型检查（tsc--noEmit）。
• npm run regression –TypeScript回归工具（CSV摄取→ 怎么翻译→ 内核/分类账）。
• python scripts/voike_regression.py –完整的Python回归（摄取、查询、MCP、blob、VVM、Ops、APIX、AI、网格）。
• python scripts/voike_full_system_regression.py –模块1-9回归（核心健康/网格/起源、SNRL/超网格/信任、全摄入、混合查询、流和具有节点并行性检查的分割网格斐波那契）。
• python scripts/voike_heartbeat.py –轻量级的Core+AI检查（健康、查询、AI策略/请求、IRX、管道分析）。
• npm run seed –可选种子脚本（确保迁移+示例数据）。
• CLI（in cli/)现在包括：

- voike build –将当前回购打包成 .vpkg 捆绑（读 vpkg.yaml).添加 --publish 推动您的VOIKE项目或 --vvm 以触发遗留网格构建。 - voike get @ –下载捆绑包（HTTP或本地缓存 ~/.voike/registry)并提取文件以进行快速引导。 - voike launch –上传捆绑包并配置应用程序(/apps/:id)不用碰Docker。

• voike env add/list –管理环境描述符(/env/descriptors)描述Docker或裸机构建；VOIKE荣誉 VOIKE_NODE_MODE 挑选合适的跑步者。
• voike task create/list/show/run-agent –与编排器交互(/orchestrator/tasks, /orchestrator/tasks/:id/run-agent)种子任务和触发计划器/代码生成器/测试器代理。
• voike peacock build/launch/evolve –孔雀构建器的辅助命令（打包 peacock/ VPKG，通过以下方式启动 /vpkgs/launch，并调用FLOW计划生成网站）。
• voike agent answer --question "..." –点击数 /agents/fast-answer 演示快速多代理FLOW管道。
• voike app onboard --project --source-type repo --identifier –阅读 flows/onboard-foreign-app.flow，计划它，执行它，并打印入职总结。
• python scripts/grid.py --mode split --n 10000 --show-segments –向网格调度器提交一个分割的斐波那契作业，跨节点生成子作业，并打印哪个节点处理了每个分段（非常适合验证网格/并行计算）。
• python scripts/voike_regression.py --grid-fib 2000 –端到端回归工具，现在包括一个网格斐波那契作业（脚本可以通过以下方式包装到VPKG中 voike wrap scripts/voike_regression.py 并像任何其他工作负载一样启动）。
• python scripts/make_capsule_snapshot.py --memo "Nightly" ... –捕获Capsule快照（由快照CI工作流调用）。
• python scripts/export_ledger.py --output ledger.json ... –导出真相分类账条目以进行审核/备份。
• python scripts/verify_pop.py --domain api.voike.com ... –在您有cURL访问权限的任何地方确认POP/SNRL/VDNS运行状况。
• python scripts/ledger_replay.py --since "..."

–回放仅在本地附加分类账条目，并在回滚前验证虚拟能源变化。

• python scripts/offline_sync.py --interval 0 --capsules

–将分类账/胶囊数据预取到本地缓存中，以便应用程序在云依赖关系变暗时继续运行。

• python scripts/rpc.py --grid 5000 --show-segments -打印网格/集群摘要、路由元数据，并（可选）运行分割斐波那契网格作业，以确认分段分布在节点上。
• 现有助手(voike init, voike wrap, voike status, voike logs)仍在运送脚手架。

要在本地安装CLI，请执行以下操作 voike 在您的PATH中可用：

cd cli
npm install    # once, if deps change
npm run build  # compile TypeScript into dist/
npm link       # registers the `voike` binary globally

发布后，您还可以从npm安装Node CLI：

npm install -g voike

并从PyPI或此仓库安装Python包装器：

pip install voike      # when published
# or, from the repo root:
pip install .

链接后，通过管理令牌创建项目+API密钥的快速方法是：

export VOIKE_ADMIN_TOKEN=...  # or ADMIN_TOKEN
voike create project ios apple

这相当于打电话 POST /admin/projects 随着 { "organizationName": "ios", "projectName": "apple", "keyLabel": "primary" } 也将更新 ~/.voike/config.json 使用新的项目+密钥。

6.1 SNRL+V-DNS（第一阶段基础）

• /snrl/resolve 使用新的FLOW计划返回任何域的已签名端点建议 flows/snrl-semantic.flow解析器通过FLOW运行→ APX → SnrlService，因此您可以在不重新部署二进制文件的情况下迭代计划。
• config/snrl-endpoints.json 为初始POP元数据添加种子。更新它或从MCP获取信息，以反映真实的持久性有机污染物。
• 模块4通过管理端点公开预测和信任数据：

- GET /snrl/predictions –检查预测缓存（域、区域、首选项、置信度），以便验证模块4的零传播路由。 - GET /snrl/insights –来自语义解析器遥测的聚合（顶级域、区域负载、信任锚）。 - GET /snrl/failures –返回故障计数器+最近的故障日志条目，以确认自动处罚和恢复流程。

• 信任锚+失败计数器持续存在 config/snrl-state.json，因此签名在重启过程中保持稳定（混合信任链的基础）。
• `node scripts/set_shared_db.js --url

` 将两个Mac+Linux节点配置为共享一个Postgres控制平面，以便网格状态、网格作业和SNRL流保持同步。

例子：

curl -X POST http://localhost:8080/snrl/resolve \
  -H 'content-type: application/json' \
  -H 'x-voike-api-key: 
' \
  -d '{ "domain": "api.voike.com", "client": { "region": "ap-sg", "capabilities": ["http","gpu"] } }'

答复：

{
  "domain": "api.voike.com",
  "candidates": [ ... ],
  "signature": "",
  "issuedAt": "2025-11-18T10:00:00Z",
  "ttl": 30
}

6.2 VDNS区域管理（第2阶段）

• 区域定义位于 config/vdns-zones.json。每次记录更新都会自动碰撞区域序列。
• flows/vdns-zone-sync.flow 通过FLOW/APX自动化区域导出+记录插入，因此您可以对DNS操作进行版本控制。
• HTTP管理端点：

- GET /vdns/zones –列出区域。 - GET /vdns/zones/:id/export –发出BIND/Knot兼容区域文本。 - POST /vdns/records –附加DNS记录({ zoneId, record }).

示例：添加A记录和导出区域

curl -X POST http://localhost:8080/vdns/records \
  -H 'content-type: application/json' \
  -H 'x-voike-admin-token: ' \
  -d '{ "zoneId": "voike-com", "record": { "type": "A", "name": "edge.voike.com.", "value": "203.0.113.55" } }'

curl -s http://localhost:8080/vdns/zones/voike-com/export \
  -H 'x-voike-admin-token: '

使用导出的区域文件为SNRL POP中的Knot/NSD权威服务器提供数据。结合 /snrl/resolve，VOIKE现在控制语义解析和权威DNS区域状态。

6.3第三阶段POP部署（DoH/DoT+权威DNS）

第3阶段将上述控制平面部件转换为可运行的解析器POP，以便您可以停用Cloudflare并提供服务 voike.supremeuf.com 直接从VOIKE管理的基础设施。

1. SNRL POP – services/snrl-pop 是终止DoH的Fastify+DNS堆栈(/dns-query)UDP/TCP端口53和可选DoT（端口853）。它将请求代理到 /snrl/resolve，缓存响应，并发出带有SNRL签名的TXT/SRV元数据。通过以下方式进行配置：

- SNRL_API_KEY –VOIKE项目API密钥，可访问 /snrl/resolve. - SNRL_POP_REGION / SNRL_POP_CAPABILITIES –用于语义路由的广告元数据。 - 可选的 SNRL_DOT_CERT_PATH + SNRL_DOT_KEY_PATH 如果你除了DoH之外还想要基于TLS的DoT。 - 在本地启动它 docker compose up snrl-pop （港口：DoH 8053，UDP/TCP 1053，DoT 8853 默认情况下）。

1. VDNS小学/中学 – services/vdns-primary （结）和 services/vdns-secondary （NSD）从以下位置获取导出的区域文本 /vdns/zones/:id/export 使用 VOIKE_ADMIN_TOKEN 并将其权威地送达53号港口。每个集装箱只需要 VDNS_ZONE_ID + VDNS_ZONE_DOMAIN （默认值见 .env.example).启动它们 docker compose up vdns-primary vdns-secondary 获取主（端口 2053)和次要（端口 3053)名称服务器。
2. POP推出工作流程 –记录在 docs/phase3_pop.md：run scripts/set_shared_db.js 要确保每个节点共享控制平面Postgres，请在Mac/Linux节点上启动POP容器，验证DoH响应(curl -H 'accept: application/dns-message' --data-binary @query.bin http://localhost:8053/dns-query)DNS应答(dig @127.0.0.1 -p 1053 voike.supremeuf.com).健康后，将注册商胶水/NS记录更新到您的POP IP，等待TTL到期，然后禁用Cloudflare。

这些服务现在位于仓库内，因此AI代理或运维工程师可以直接从VOIKE构建/发布POP图像。未来的增强功能（DNSSEC、Anycast/BGP自动化、POP健康探测）将叠加在此基线之上，而无需重新配置。

6.4第4阶段（Genesis引导+自动注册）

• GENESIS_BOOTSTRAP=1 --启用后，后端同步 config/vdns-zones.json 和 config/snrl-endpoints.json 来自规范的Genesis部署(GENESIS_URL + GENESIS_ADMIN_TOKEN)在服务初始化之前，确保每个节点都以最新的POP+DNS状态启动。
• GENESIS_REGISTER=1 --启动后，VOIKE使用以下命令在Genesis中自动注册节点（SNRL端点+AAA/NS记录） VOIKE_PUBLIC_* envs（主机名、IP、地区、功能、TTL）。每 docker compose up -d --build run now自动注册主机 voike.supremeuf.com 因此，发现永远不需要手动步骤。
• VDNS容器轮询 /vdns/zones/:id/export 在一段时间内(VDNS_REFRESH_SECONDS，默认60秒），并在区域更改时热重新加载旋钮/NSD。在以下情况下不需要手动重新启动 /vdns/records 更新Genesis的火力。
• 编写布线，提供所有必需的环境默认值(GENESIS_*, VOIKE_PUBLIC_*, SNRL_*, VDNS_*)，因此启动新服务器只需要编辑 .env 跑步 docker compose up -d --build。后端、解析器、POP和注册循环都包括在内。

6.5模块4–AI边缘解析器示例

• services/snrl-ai-edge/ 为ARN-DNS边缘节点添加了FastAPI+dnslib参考实现。它嵌入请求的域，通过Qdrant本地模式运行相似性搜索，并回答UDP DNS查询 EDGE_DNS_PORT （默认值 1053).
• 每次查找首先检查内存中的TTL缓存，然后检查语义存储，最后 /snrl/resolve预测的点击量永远不会离开POP，仍然包括模块4签名/信任锚元数据。
• 控制平面端点(GET /, /metrics, /cache, /predictions)公开通过以下方式集中显示的相同预测缓存信息 /snrl/predictions 和 /snrl/insights 因此，操作系统可以区分边缘行为和核心行为。
• 通过环境变量进行配置(VOIKE_API_KEY, VOIKE_API_URL, EDGE_REGION, EDGE_CAPABILITIES, EDGE_SEMANTIC_THRESHOLD等）并在本地运行 uvicorn app:app --host 0.0.0.0 --port 8000 或通过Docker(docker build -t voike/snrl-ai-edge services/snrl-ai-edge).
• 使用已发布的指标+持续的指标 config/snrl-state.json 信任锚点，以确认即使在重新启动后，AI节点也会与规范预测缓存保持同步。

6.6模块5–Hypermesh+UOR发动机

• src/hypermesh/ 介绍了HypermeshService：它对本地CPU/RAM进行采样，计算PerfWatch/MashSurgeon/HyperRoute建议，将其持久化在Postgres中，并公开 /hypermesh/status, /hypermesh/routes, /hypermesh/events, /hypermesh/agents 用于仪表板+FLOW计划。
• PerfWatch使运行时保持舒适（CPU睡眠状态、INT4压缩提示、内存碎片整理建议）。MeshSurgeon记录自愈行为/预测产卵；HyperRoute发出按带宽+语义关联度排序的低延迟路由表。
• 指标流入 hypermesh_nodes + hypermesh_events 表和重用 config/snrl-state.json 信任锚，因此模块4+5数据共享来源。
• services/uor-engine/ 发送Rust/Tokio微内核样本（WASM加载器存根，warp /status 端点），因此POP或Raspberry Pi目标可以承载\1百万事件/秒）、代理路由、检查点和混合查询桥。

LLM配置

• 集 OPENAI_API_KEY, OPENAI_BASE_URL （默认值 https://api.openai.com)，以及 OPENAI_MODEL (gpt-5.1 默认情况下） .env 实现真正的GPT支持流(/agents/fast-answer, flows/* 随着 RUN AGENT).
• 看 flow/docs/VPKG-spec.md 了解清单格式以及每个捆绑包中包含的文件。
• 集 VOIKE_NODE_MODE=docker （默认）或 VOIKE_NODE_MODE=baremetal 控制env描述符的运行方式。Docker模式通过以下方式封装命令 docker run；baremetal使用您的系统包在本地执行命令。

______________________________________________________________________

8.运营/行政

• 等候名单和配置: POST /waitlist, GET /admin/waitlist, POST /admin/waitlist/:id/approve, POST /admin/projects.
• 生成器身份验证: /auth/check-whitelist, /auth/setup-password, /auth/login, /user/*.
• 操作SLO: GET/PUT /ops/slos, GET /ops/advisories.
• 混沌测试：环境变量(CHAOS_ENABLED, CHAOS_FAULT_PROBABILITY等等）向压力摄取/查询路径注入故障。
• 指标: GET /metrics 用于仪表/计数器；网络套接字 /events 用于实时遥测。

______________________________________________________________________

9.游乐场和登录页面提示

• 创建游乐场项目/API密钥并将其发布在文档中(VOIKE_PLAYGROUND_API_KEY).在登录页面上使用它来显示：

- 最近摄取的作业和查询。 - Blob上传（例如，实时流式传输视频）。 - AI Atlas条目和知识结构响应。 - 聊天记录（公共/安全样本数据）。

• 医生着陆(GET /)已经包括一本顺风手册；定制它以显示实时API响应（健康、指标、人工智能、聊天）。
• 对于演示文稿（例如，向谷歌），请浏览：

1. /ingest/file （CSV）→ /query. 1. /blobs 上传→ /blobs/{id}/stream. 1. /ai/atlas + /ai/ask 知识结构。 1. /ai/pipelines/analyze 显示自动HyperFlow建议。 1. /chat 对话引用新摄入的数据。

______________________________________________________________________

10.保持嗓音健康

1. 心跳日程 python scripts/voike_heartbeat.py 每隔几分钟。如果操场没有反应，它很快就会失败。
2. 回归：run python scripts/voike_full_system_regression.py （或 python scripts/voike_regression.py 在发布或重大升级之前，请进行更轻松的检查。
3. 遥测：观看 /metrics, /ops/advisories, /ai/ops/triage.AI分类表面运行手册。
4. 胶囊：创建定期快照(POST /capsules)在危险部署之前。
5. 文档：更新 docs/api.md, docs/regression_playground.md, docs/ai_fabric.md 在添加新端点时，使外部团队保持一致。

对于不同环境的快速检查：

• bash scripts/test_genesis.sh –使用中的令牌在Genesis游乐场上运行心跳+回归 .env.
• bash scripts/test_local.sh –运行心跳+回归 http://localhost:8080；set VOIKE_LOCAL_API_KEY 在 .env 创建本地项目后，它使用本地API密钥而不是Genesis游乐场密钥。

______________________________________________________________________

11.VOIKE 3.0编排器（预览版）

VOIKE开始自行运行。编排器现在在Postgres中持久化一个完整的项目图，并公开 /orchestrator/* API，以便代理（或人类）可以：

• POST /orchestrator/projects + GET /orchestrator/projects/:id –注册/检查项目（包括 voike-core).
• POST /orchestrator/projects/:id/graph –上传在仓库扫描期间发现的模块、依赖关系和端点； GET /.../graph 返回地图。
• POST /orchestrator/agents / GET /orchestrator/agents –声明规划者/编码员/测试员/基础设施人员。
• POST /orchestrator/tasks / GET /orchestrator/tasks / GET /orchestrator/tasks/:id –创建和跟踪编排运行（每个运行都有步骤/状态/历史）。
• flow/docs/ORCH-FLOW.md FLOW配置文件代理遵循的文档(RUN AGENT, RUN JOB, ASK_AI等），因此Planner/Codegen/Tester/Infra步骤保持一致。
• flows/fast-agentic-answer.flow 搭配 /agents/fast-answer / voike agent answer 演示多智能体规划器→ 推理→ 事实→ code → 批评→ 缝合循环（记录的所有步骤 /orchestrator/tasks).
• flows/onboard-foreign-app.flow 对Lovable/Replit/Supabase导入管道进行编码；通过运行它 voike app onboard （使用 /flow/plan + /flow/execute)观看 /orchestrator/tasks 捕获每个迁移步骤。
• flows/voike-meta.flow 描述了如何引导VOIKE本身（DB/内核/VASM/envs/VVM/peack/等），而 flows/voike-self-evolve.flow 捕捉规划师/编码员/测试员/基础设施/产品代理如何端到端地发展VOIKE。

第5阶段将RUN_AGENT调用连接到新的 EvolutionAgentService.Planner/Codegen/Tester/Infra/产品代理自动：

• 确保编排器项目存在（重新使用VOIKE项目UUID）。
• 创建/更新 /orchestrator/tasks 并附加带有摘要、差异和部署命令的结构化步骤。
• 解析FLOW规范(source.readFile 支持内联覆盖），因此CI/CD作业可以重放本地使用的确切功能简介。
• 喂养 .github/workflows/agentic-flow.yml 管道，锻炼操场 /flow/plan + /flow/execute 并在配置机密时在每次推送/PR期间打印产品摘要。

即将到来的阶段将为每个任务附加Capsule，连接CLI助手(voike task, voike evolve)，让FLOW驱动整个进化循环。

记住VOIKE 3.0的咒语：

*VOIKE的整个开发、部署和演变过程 通过 VOIKE，由FLOW、VPKG和代理驱动。人类掌舵；VOIKE磨。*

12.模块5–Hypermesh网络和UOR引擎

• HypermeshService(src/hypermesh) –发布新的模块5 API。PerfWatch采样CPU/RAM+量化比率；MeshSurgeon写信给 hypermesh_eventsHyperRoute每5秒刷新一次路由表。
• 应用程序编程接口 – GET /hypermesh/status, /hypermesh/routes, /hypermesh/events, /hypermesh/agents 共享遥测数据，以便CI/ops仪表板可以确认空闲占用空间（\<30 MB）并查看预测性生成指南。所有端点都需要管理员令牌。
• 数据库表 – hypermesh_nodes 存储每个节点的统计数据， hypermesh_events 记录警告/自愈操作。这两个表都同步到Genesis+模块4的信任锚，以便重播。
• UOR发动机（服务/UOR发动机） –Rust+Tokio微服务，演示了超优化的运行时概念：无缝调度、WASM加载器存根、LMDB就绪存储和 /status POP部署的指标。
• FLOW挂钩（下） –模块5代理公开元数据，因此FLOW/GRID规划者可以将作业偏向最健康的微节点。看 docs/voike-agents-module5.md 了解规格和路线图。

13.模块6-全球信任、PQC和安全优化规则

• 管理API: GET /trust/status （完整的PQC/DTC/PTA快照）， /trust/anchors （不可变密钥历史）， /trust/events （安全日志）， /trust/sessions （当前节点到节点隧道）， /trust/pta （异常预测）。它们需要管理员令牌，并且从不公开私钥。
• 允许的性能调整(✅)：启用SIMD/WASM加速、压缩遥测、冷加载PQC模块、调整Hypermesh采样间隔、添加只读可观察性。这些路径在 /trust/status.policy.safeOps.allowed.
• 更改前询问(⚠️)：PQC参数集、DTC阈值、网格复制因子、PTA评分权重。策略blob将它们标记为 requiresApproval.
• 永远不要(🚫)：绕过PQC验证、修改节点ID、禁用异常检测、将机密存储在git中或发送未签名的代理。策略将这些操作列在 forbidden.
• 工作流程：PerfWatch+PTA加薪 trust_events 每当CPU/RAM峰值威胁到PQC响应时。MeshSurgeon使用这些事件生成副本，HyperRoute避免不安全的节点，Module 4的信任锚点保持签名一致。

14.模块7-语音与谷歌反重力

• 反重力快照：谷歌的Gemini 3驱动IDE允许代理控制浏览器/终端/编辑器并发出工件（InfoWorld、印度时报、The Verge）。Reddit的报道强调了预览版本中的破坏性编辑和隐私担忧。
• VOIKE优势：UI-OFDB使用流解析器、自动模式推理、转换规划、嵌入和混合存储（SQL+向量+图）摄取任意文件。谱系+PQC记录意味着每次摄入都是可重复的并有标记的。
• 工件风格洞察: /ingestion/lineage 为审计员和仪表板构建者提供类似的“工件”证明（计划数组、模式预览、嵌入元数据）。
• 我们在哪里学习：Antigravity的Manager/Artifact UX激发了即将到来的摄入仪表板+反馈循环，因此人类可以快速批准模式/转换计划。

15.模块8-混合查询与反重力/Supabase/TigerData

• /hybrid/query 回报 { plan, result, cacheHit } 因此，代理或人类可以在执行之前检查计划。计划包括矢量/SQL/图形步骤以及成本估算。
• /hybrid/plans, /hybrid/cache, /hybrid/profiles 行为类似于反重力“工件”，但用于查询计划；它们公开缓存+延迟配置文件，而不公开私有数据。
• 查询解析代理使用启发式方法（关键字，提供SQL/图有效载荷）来最小化LLM/令牌的使用；只有模糊的NL意图需要LLM升级。
• 未来的工作：将模块5仪表板插入这些端点，供实时查询检查器使用，并让FLOW代理在接收更新时重新运行缓存的计划。

16.模块9-流与Supabase/TigerData/反重力

• /streams/:id/events 保持原始有效载荷不可变，而代理处理器将派生数据发送到模块7表中。
• /streams/:id/profile 为仪表板提供快速查看指标（延迟、吞吐量）；模块5的Hypermesh UI可以将其与之一起获取 /hypermesh/status.
• 检查点确保确定性回放+背压；未来的Flow操作可以从上次处理的序列中恢复流。

17.模块10——生产和部署准备（预览）

• 最终模块（可选）将捆绑强化部署调优：容器/K8s清单、机密管理、CI/CD护栏、扩展策略、DR/备份和开发人员入职运行手册。模块1-9中的架构基础已经完成；模块10将侧重于操作抛光。