AL-world · Python + MoonBit 混编自进化 AI 绘画知识库

确定性向量检索 · 二路融合分类 · 知识自进化与投票反馈闭环
MoonBit 计算核心（零运行时依赖，编译为 WASM）+ Python 编排层（CLI / 视觉桥 / 未来 Web API）

AL-world 是一个自进化的 AI 绘画提示词知识库引擎。给定一段查询（中文/英文标签、提示词片段，或一张图的分析结果），它可以：

语义检索——在已有知识库中返回带相似度分数的候选条目；
自动分类——把新内容归类到具体知识库（如 hanfu-culture、figure-drawing、art-prompts）及其子类别；
自进化沉淀——把新知识保存，并自动注册进向量索引、类别映射、标签倒排索引、同义词表；
投票反馈闭环——人工评分直接改变该条目在后续检索中的排序权重。

本项目是原始 Python 版（见「与原 Python 版的差异」）的转译 + 混编重构：核心计算引擎用 MoonBit 重写（确定性、WASM 取向、零加密依赖），编排与多模态视觉部分用 Python 重写（替代原 Node vision-bridge.js）。

📌 本目录是一个独立子项目，与原始 C:\Users9207\.agents\skills\AL-world 互不干扰：数据（knowledge/、index/）为本项目独立拷贝，MoonBit 代码全部在 src/ 内。

一、特性
二、系统架构
三、目录结构
四、环境要求
五、安装与构建
六、快速开始
七、使用指南
八、命令参考
九、数据格式与文件约定
十、自进化闭环
十一、确定性说明
十二、与原 Python 版的差异
十三、设计决策
十四、扩展指南
十五、开发测试
十六、路线图
十七、许可证
十八、致谢

一、特性

🧮 确定性向量引擎：基于 FNV-1a 64 位哈希把 token 稳定映射到 128 维向量，相同输入必得相同向量，结果可复现，无需 GPU/外部模型。
🔀 二路融合分类：向量语义检索（权重 0.6）+ 标签精确/模糊/LCS 匹配（权重 0.4）融合打分，输出 {kb, sub, confidence}。
🔎 语义检索：向量余弦相似度 + 标签 Jaccard 相似度 + vote_score 质量加权的联合排序。
🌱 知识自进化：save 一次完成 prompts.json 写入 + 向量索引增量 + 类别映射/标签索引/同义词表注册，全部为进程内函数调用，无 subprocess。
🗳️ 投票反馈闭环：feedback 修改 vote_score 并实时同步进向量索引权重，无需重建即可影响检索排序。
🖼️ 多模态视觉桥（Python）：替代原 Node vision-bridge.js，支持 OpenAI 兼容视觉端点，未配置密钥时自动进入 mock 模式。
🔌 渐进式集成协议：核心暴露单一 invoke JSON 入口，当前用子进程桥接，未来可无缝切换为 wasmtime 进程内调用，协议不变。
📦 零加密依赖：用 FNV-1a 替代 hashlib.md5，更精简、更适合嵌入 WASM 运行时。

二、系统架构

                         ┌──────────────────────────────────────┐
   查询 / 图片 / JSON ──▶ │            Python 编排层              │
                         │  cli.py · vision.py · bridge.py       │
                         │   • 解析参数 / 视觉分析 / IO 包装       │
                         └───────────────┬──────────────────────┘
                                         │ 子进程 + 单入口 JSON 协议
                                         │ moon run src -- invoke '{...}'
                                         ▼
                         ┌──────────────────────────────────────┐
                         │        MoonBit 计算核心 (src/)         │
                         │  util · embedding · vector_index      │
                         │  classify · pipeline · main(invoke)   │
                         │   确定性计算：向量 / 检索 / 分类 / 进化  │
                         └───────────────┬──────────────────────┘
                                         │ 读写
                                         ▼
                   ┌────────────────────────────────────────────┐
                   │   共享数据（JSON，本项目独立拷贝）            │
                   │   knowledge/<kb>/prompts.json               │
                   │   index/{vector,category,tag,synonyms}.json │
                   └────────────────────────────────────────────┘

职责分工（精简冗余）：

层	职责	关键文件
MoonBit 核心	确定性计算：embedding、向量检索、二路融合分类、自进化流水线、投票同步	`src/*.mbt`
Python 编排	命令行入口、文件调度、多模态视觉分析、未来 Web API	`python/alworld/*.py`
共享数据	知识条目与四类索引，纯 JSON，与计算层解耦	`knowledge/`、`index/`

原 Python 版用 importlib 循环 import + subprocess 调自己更新索引，既脆弱又冗余；本版 MoonBit 单包内函数调用完成全部索引注册，Python 只做一次桥接调用。

三、目录结构

AL-world-moonbit/
├── moon.mod                     # MoonBit 模块声明（alworld_moonbit）
├── config.json                  # 项目配置（知识库列表、维度、阈值等）
├── README.md                    # 本文件
├── SKILL.md                     # 智能体 / Skill 调用说明
├── LICENSE                      # MIT
│
├── src/                         # MoonBit 计算核心
│   ├── moon.pkg                 # 包声明（含 options("is-main": true)）
│   ├── util.mbt                 # Ctx/Cleaned、Json 读写、字符串/哈希/向量辅助
│   ├── embedding.mbt            # FNV-1a 确定性向量、同义词扩展、自进化
│   ├── vector_index.mbt         # 向量索引重建/增量、语义检索、register_new_category
│   ├── classify.mbt             # 向量 + 标签二路融合分类
│   ├── pipeline.mbt             # save_and_evolve / record_feedback 自进化闭环
│   └── main.mbt                 # CLI 入口 + 单入口 invoke 协议
│
├── python/                      # Python 编排层
│   ├── pyproject.toml           # 包元数据（alworld）
│   ├── requirements.txt         # 依赖（仅实时视觉模式需要 requests）
│   └── alworld/
│       ├── __init__.py
│       ├── bridge.py            # 子进程桥接：调 moon run src -- invoke '<json>'
│       ├── vision.py            # HTTP 多模态视觉分析（替代 vision-bridge.js）
│       └── cli.py               # argparse CLI（镜像全部命令 + vision 流水线）
│
├── knowledge/                   # 知识库数据（独立拷贝，含 prompts.json）
│   ├── hanfu-culture/
│   ├── figure-drawing/
│   └── art-prompts/
│
└── index/                       # 衍生索引（重建/自进化产物）
    ├── vector-index.json        # 向量索引（检索核心）
    ├── category-map.json        # 类别映射 + 别名
    ├── tag-index.json           # 标签倒排索引
    └── synonyms.json            # 自进化同义词表

四、环境要求

工具	版本	用途
MoonBit 工具链 (`moon`)	≥ `0.1.20260703`	构建/运行 MoonBit 核心
Python	≥ 3.10	Python 编排层（CLI、视觉桥）
Node.js	任意（已安装即可）	`moon run` 默认 wasm-gc 目标经 Node 执行
`requests`（可选）	—	仅实时视觉模式需要；mock 模式零依赖

⚠️ 关于原生目标：当前环境若无 C 编译器，moon build --target native 会失败。默认构建目标为 wasm-gc，运行经 moon run（即 Node）。所有命令均可通过 moon run src -- <cmd> 或 Python CLI 执行，无需原生二进制。

五、安装与构建

# 1) 克隆 / 进入项目
cd AL-world-moonbit

# 2) 构建 MoonBit 核心（默认 wasm-gc 目标，零运行时依赖）
moon build

# 3) （可选）安装 Python 编排层依赖
cd python
pip install -e .          # 或: pip install -r requirements.txt

构建成功后，moon build 输出应无 error / warning。

六、快速开始

# 方式一：直接用 MoonBit CLI
moon run src -- status
moon run src -- search --query "唐装 汉服 唐代" --top-k 3

# 方式二（推荐）：用 Python CLI
cd python
python -m alworld.cli status
python -m alworld.cli search --query "唐装 汉服 唐代" --top-k 3

# 一条命令完成「看图 → 分析 → 沉淀为知识」
python -m alworld.cli vision --image artwork.png --auto

真实输出示例（status）：

[AL-world] 向量索引状态:
  条目数: 23
  维度: 128
  - hanfu-culture: 9 条
  - figure-drawing: 8 条
  - art-prompts: 6 条

七、使用指南

7.1 MoonBit CLI

moon run src -- <command> [options]

示例：

moon run src -- rebuild
moon run src -- search --query "唐装 汉服 唐代" --top-k 5
moon run src -- classify --query "古风 明代 襦裙"
moon run src -- classify --input vision.json
moon run src -- save --input vision.json --auto
moon run src -- feedback --ref "hanfu-culture:prompts.json:foo" --score +1

原 Python 版的交互式保存菜单在 MoonBit 版中以「--auto 自动 / --kb + --sub 显式」两种非交互模式替代，更易于脚本化与测试。

7.2 Python CLI（推荐入口）

cd python
python -m alworld.cli <command> [options]

常用示例：

# 语义检索
python -m alworld.cli search --query "唐装 汉服 唐代" --top-k 3

# 文本分类（二路融合）
python -m alworld.cli classify --query "古风 汉服 明代 襦裙"

# 用视觉分析结果 JSON 分类
python -m alworld.cli classify --input vision.json

# 保存并自进化（自动按分类落库）
python -m alworld.cli save --input vision.json --auto

# 显式指定知识库与子类别
python -m alworld.cli save --input vision.json --kb hanfu-culture --sub tang_ruqun

# 图片 → 视觉分析 → 自动沉淀为知识（一步到位）
python -m alworld.cli vision --image artwork.png --auto

# 手动添加条目并注册全部索引
python -m alworld.cli add-entry --kb figure-drawing --prompt-id my_test \
    --tags 赛博 霓虹 --en "cyberpunk test" --zh "测试"

# 投票反馈（同步向量权重）
python -m alworld.cli feedback --ref "hanfu-culture:prompts.json:foo" --score +1

# 索引维护
python -m alworld.cli rebuild
python -m alworld.cli status
python -m alworld.cli list

路径约定：所有文件路径参数（如 --input、--image）相对项目根目录解析（MoonBit 核心以项目根为工作目录）。也可用绝对路径，更稳妥。

7.3 Python API（编程调用）

from alworld.bridge import MoonBitCore

core = MoonBitCore(root="/path/to/AL-world-moonbit")

# 状态
print(core.status())

# 检索
results = core.search("唐装 汉服 唐代", top_k=3)
for r in results:
    print(r["score"], r["entry"]["id"])

# 分类
cat = core.classify(query="古风 汉服 明代 襦裙")
print(cat["kb"], cat["sub"], cat["confidence"])

# 保存（视觉结果 JSON 文件路径）
core.save("vision.json", auto=True)

# 反馈
core.feedback("hanfu-culture:prompts.json:foo", score=1)

MoonBitCore 在调用失败时抛出 MoonBitCoreError（核心返回 ok=false 或进程异常）。

7.4 单入口 `invoke` JSON 协议

MoonBit 核心对外暴露统一入口，便于任意编排层（Python、未来的 wasmtime、甚至其他语言）集成：

moon run src -- invoke '{"cmd":"search","query":"唐装 汉服","top_k":3}'
# → {"ok":true,"cmd":"search","data":[ ... ]}     # 在 stdout 最后一行

请求：{"cmd": "<命令>", ...参数}
响应：成功 {"ok": true, "cmd": "<命令>", "data": <结果>}；失败 {"ok": false, "error": "<信息>"}
注意：引擎内部诊断打印（如「已保存至 …」「索引已进化 …」）会出现在 stdout 前部，调用方取最后一行 JSON 即可，不影响解析（Python bridge.py 已实现该逻辑）。

支持 cmd：rebuild / status / search / classify / list / add-entry / save / feedback，参数与 CLI 对应（见命令参考）。

渐进式设计：当前用子进程桥接（零新依赖、立即可用）。核心已是单入口 invoke，未来无需改协议即可平滑切换为 wasmtime 直接调用（把 src/ 编译为 wasm 目标、Python 用 wasmtime 加载、传 JSON 字符串），获得更快的调用速度与进程内集成。

八、命令参考

8.1 MoonBit / Python 通用命令

命令	必填参数	可选参数	作用
`rebuild`	—	—	完全重建向量索引（同步 `vote_score`）
`status`	—	—	索引状态与各知识库条目数
`search`	`--query`	`--top-k`（默认 5）	语义搜索（向量 + 标签融合 + 质量加权）
`classify`	`--query` 或 `--input`	—	二路融合分类（文本或视觉结果 JSON）
`list`	—	—	列出全部分类条目（标签索引 + 向量索引去重合并）
`add-entry`	`--kb`, `--prompt-id`, `--tags`	`--sub`, `--en`, `--zh`, `--comp`, `--color`	手动添加条目并注册全部索引
`save`	`--input`	`--auto`, `--kb`, `--sub`, `--prompt-id`	保存视觉结果并自进化
`feedback`	`--ref`, `--score`	—	评分反馈，同步向量权重

8.2 Python 专属命令

命令	必填参数	可选参数	作用
`vision`	`--image`	`--auto`, `--kb`, `--sub`, `--prompt-id`	视觉分析 → 临时结果 → `save` 自进化

8.3 `search` 返回结构

[
  {
    "score": 0.30038149882159515,
    "entry": {
      "id": "figure-drawing:prompts.json:prone_compression_wedge",
      "kb": "figure-drawing",
      "sub": "prone_compression_wedge",
      "vector": [0.1001, 0.0250, ...],
      "tags": ["pose", "compression", "..."],
      "en_preview": "a figure in prone ...",
      "vote_score": 0.0
    },
    "vote_score": 0.0
  }
]

8.4 `classify` 返回结构

{
  "kb": "hanfu-culture",
  "sub": "tang_ruqun",
  "confidence": 0.42,
  "reason": "hanfu-culture:prompts.json:tang_ruqun",
  "vector_matches": [ ... ]
}

kb / sub 为 null 表示无足够证据分类（置信度 0）。

8.5 `ref` 格式

feedback 的 --ref（以及 invoke 的 ref 参数）统一为：

<kb>:prompts.json:<prompt_id>
# 例： hanfu-culture:prompts.json:tang_ruqun

九、数据格式与文件约定

9.1 视觉结果 schema（`vision` / `save` 的输入）

vision.py 输出，或任何外部流程生成，交给 save 消费：

{
  "ai_prompts": {
    "key_tags": ["汉服", "唐风", "齐胸襦裙"],
    "en": "tang dynasty hanfu high-waist ruqun",
    "zh": "唐代齐胸襦裙"
  },
  "composition": "full body centered",
  "color_lighting": "soft natural light",
  "style_technique": "guofeng line art",
  "mood_narrative": "elegant serene"
}

9.2 `knowledge/<kb>/prompts.json`

每条知识的核心存储，自进化时由 save_and_evolve 写入：

{
  "name": "hanfu-culture",
  "prompts": {
    "<prompt_id>": {
      "en": "tang dynasty hanfu ...",
      "zh": "唐代齐胸襦裙",
      "tags": ["汉服", "唐风", "齐胸襦裙"],
      "composition": "full body centered",
      "color_lighting": "soft natural light",
      "style_technique": "guofeng line art",
      "mood_narrative": "elegant serene",
      "category": "tang_ruqun",
      "source": "vision-analysis",
      "vote_score": 0.0,
      "quality": "untracked"
    }
  }
}

prompt_id 自动去重：相同 id 会追加 -1、-2 序号。
vote_score 经 feedback 修改；quality 依阈值导出：≥3→high，≥0→medium，<0→low。

9.3 `index/vector-index.json`

检索主索引，rebuild / save 维护：

{
  "name": "AL-world 向量检索索引",
  "version": "3.0.0",
  "dim": 128,
  "entries": [
    {
      "id": "hanfu-culture:prompts.json:tang_ruqun",
      "kb": "hanfu-culture",
      "sub": "tang_ruqun",
      "vector": [0.1, 0.025, ...],
      "tags": ["汉服", "唐风"],
      "en_preview": "tang dynasty hanfu ...",
      "vote_score": 0.0
    }
  ]
}

9.4 `index/category-map.json` / `tag-index.json` / `synonyms.json`

category-map.json：mappings（kb-sub → 元数据 + auto_generated）、aliases（子类别别名）。
tag-index.json：index（标签 → 引用数组 ["<kb>:prompts.json:<pid>", ...]），用于分类的标签融合。
synonyms.json：自进化同义词表（tag → [tag, ...]），save 时新增标签自动并入。

9.5 `config.json`

{
  "version": "1.0.0",
  "knowledge_dir": "knowledge",
  "index_dir": "index",
  "classify_threshold": 0.5,
  "embedding_dim": 128,
  "quality_boost": 0.2,
  "knowledge_bases": ["hanfu-culture", "figure-drawing", "art-prompts"],
  "tmp_dir": "tmp"
}

字段	含义	默认值
`knowledge_dir` / `index_dir`	数据与索引相对根目录的路径	`knowledge` / `index`
`embedding_dim`	向量维度	`128`
`classify_threshold`	`save --auto` 自动落库的置信度阈值	`0.5`
`quality_boost`	`vote_score` 对检索排序的影响系数	`0.2`
`knowledge_bases`	知识库列表（`save` 校验 kb 合法性）	三项

十、自进化闭环

视觉分析 / 文本
    │
    ▼
 save --auto ──► do_save(): 分类 → 若 conf ≥ 阈值则自动落库
    │
    ├─► prompts.json       写入新条目（含 vote_score=0）
    ├─► vector-index.json  增量 add_entry（向量 + 标签 + en_preview）
    ├─► category-map.json  注册 kb-sub 映射 + 别名
    ├─► tag-index.json     标签倒排索引追加引用
    └─► synonyms.json      新标签并入同义词表（供后续 expand_tags）
    │
    ▼
 feedback --ref --score ──► record_feedback()
    ├─► prompts.json       修改 vote_score，导出 quality(high/medium/low)
    └─► vector-index.json  sync_vector_vote() 同步 vote_score
                              ↓
                          search 排序实时受 vote_score 影响（boost * clamp(vote/3, -1, 1)）

所有索引更新均为进程内函数调用，无 subprocess、无重复加载。

十一、确定性说明

向量确定性：文本经 tokenize 切分后，每个 token 用 FNV-1a 64 位哈希稳定映射到向量槽位（seed 经 ((h%dim)+dim)%dim 保证非负），再加前缀权重与 L2 归一化。相同输入必得相同向量。
检索/分类可复现：不依赖随机性或外部模型（视觉桥除外），同一查询多次结果一致。
反馈即时生效：vote_score 经 clamp(vote/3, -1, 1) * boost 实时影响检索排序，无需重建索引（sync_vector_vote 同步进 vector-index.json，持久化）。

十二、与原 Python 版的差异

原项目 C:\Users9207\.agents\skills\AL-world 仍是功能完整版。本混编版将其核心引擎以 MoonBit 实现、以 Python 编排。

模块	原 Python 文件	本版实现	说明
向量引擎 + 索引进化	`services/vector-engine.py`	`src/embedding.mbt`, `src/vector_index.mbt`	确定性哈希向量、检索、索引自进化
分类引擎	`services/classify.py`	`src/classify.mbt`	向量 + 标签二路融合
知识流水线 + 反馈	`services/knowledge-pipeline.py`	`src/pipeline.mbt`	保存自进化、投票反馈、权重同步
共享工具 / JSON IO	散落各处	`src/util.mbt`	零外部依赖工具层
多模态视觉桥	`services/vision-bridge.js`（Node）	`python/alworld/vision.py`	用 Python 重写，HTTP 调视觉模型
CLI / 编排	`scripts/al-*..sh`	`src/main.mbt` + `python/alworld/cli.py`	双入口：MoonBit CLI 与 Python CLI

关键差异（精简 + 适配）

三文件循环依赖（importlib + subprocess）合并为单包函数调用（无进程间通信）。
哈希实现：FNV-1a 64 位 替代 hashlib.md5（目的相同：token → 稳定整数，零加密依赖）。
交互式保存 → 非交互双模式（--auto 阈值判定 / --kb + --sub 显式）。
变量名规避保留字（ref→ref_id、override→pid_override、final→final_score）。
新增 Python 视觉桥与统一 invoke JSON 协议，便于嵌入 WASM 运行时或未来 Web API。

十三、设计决策

为什么 MoonBit 做核心：确定性计算、编译为 WASM、零运行时依赖，适合嵌入浏览器/边缘/智能体运行时；FNV-1a 哈希向量免去外部 embedding 服务依赖。
为什么 Python 做编排：文件调度、HTTP 多模态、CLI/测试、未来 Web API 在 Python 生态更顺手；且 subprocess + JSON 协议门槛极低，零新依赖即可运行。
**为什么单入口 invoke**：把核心收敛为一个稳定协议，外部编排层（Python 现在、wasmtime 未来）都只需「传 JSON、收 JSON」，演进不破坏接口。
为什么不一次性 WASM FFI：当前环境缺 C 编译器、且子进程已能零依赖运行；先落地可用版本，协议预留演进空间（符合「渐进式」原则）。

十四、扩展指南

新增一个知识库

在 config.json 的 knowledge_bases 追加新库名（如 cyber-art）；
创建目录 knowledge/cyber-art/ 并放入 prompts.json（可空 {"name":"cyber-art","prompts":{}}）；
moon run src -- rebuild（或 Python rebuild）。

也可直接用 save --kb cyber-art --sub <子类> --input vision.json 自动初始化。

替换 embedding 后端

Embedding::embed_text（src/embedding.mbt）是唯一决定向量形态的函数。要接入真实向量模型（如 bge-m3 / text2vec），只需替换其实现；dim 由 config.json 的 embedding_dim 控制，索引读写已按 dim 参数化，无需改动其他模块。

切换到 wasmtime 进程内调用

核心已是单入口 invoke 协议。把 src/ 以 moon build --target wasm 编译为 wasm，用 wasmtime-py 加载并传入请求 JSON 字符串、取回响应 JSON 即可，协议与 Python bridge.py 完全不变。

十五、开发测试

# 1) MoonBit 核心构建（应无 error/warning）
moon build

# 2) 冒烟测试（Python CLI）
cd python
python -m alworld.cli status
python -m alworld.cli search --query "唐装 汉服" --top-k 2
python -m alworld.cli classify --query "古风 汉服 明代 襦裙"

# 3) 自进化闭环验证
python -m alworld.cli save --input vision.json --auto
python -m alworld.cli feedback --ref "<kb>:prompts.json:<pid>" --score +1

# 4) 视觉桥（mock 模式，无需密钥）
python -m alworld.cli vision --image dummy.png --auto

建议：修改 src/*.mbt 后先 moon build 确认零警告；测试产生的数据可在 knowledge/、index/ 重置（重新从源拷贝或 rebuild）。

十六、路线图

wasmtime 进程内 FFI，替代子进程桥接（协议不变）。
可选 FastAPI Web 服务，供前端/智能体远程调用。
真实 embedding 后端接入（替换 embed_text）。
跨语言同义词展开（当前 expand_tags 仅匹配同语言 key）。
单元测试（MoonBit moon test + Python pytest）。

十七、许可证

本项目以 MIT License 发布。详见 LICENSE。

十八、致谢

核心架构与设计灵感来自原始 Python 版 AL-world（自进化 AI 绘画知识库）。
MoonBit 提供确定性、WASM 取向的编程语言与工具链。