Level 1  api       最细粒度: 单个 API 调用      "map.put(k, v)"
                   → 锁 receiver 类型(HashMap) → 该类中与调用意图最匹配的成员
                   → 产出该调用的 suggest

Level 2  statement 中间粒度: 整行语句          "map.put(k, v);"
                   → NL 检索,对应 Cangjie 的一个或几个 API
                   → 用于 receiver 类型不可锁定时的降级

Level 3  function  最粗粒度: 整个代码块         "public void copyFile(...) {...}"
                   → NL "copy a file",检索整个功能模块
                   → 只生成一个块级 suggest(兜底)

输入: BufferedReader reader = new BufferedReader(new InputStreamReader(System.in));
      String line = reader.readLine();
│
├─ extract_types() 拆出每个调用(含构造调用 `new Xxx(...)` 与 `new HashMap<>()`)
│    calls = [reader.readLine, new BufferedReader, new InputStreamReader, ...]
│
├─ 对每个 call 独立解析:
│    ┌─ L1 api: 锁 receiver 类型(查 x2cangjie 映射表 / BM25 类名兜底)
│    │    → 该类成员按该调用的 NL 意图重排(含 rerank)→ 返回 top-k 成员
│    │    (map.put → HashMap 的 add/contains/...;reader.readLine → StringReader 的 readln/...
│    │     new BufferedReader → StringReader 的 init(T)/lines/... ← 构造调用单独建议)
│    ├─ L2 statement: receiver 类型无法锁定(如 System.out.println)时,
│    │    用整行语句 NL 检索 → 返回候选 API 列表
│    └─ L3 function: 整个块仍无法解析时,生成一个块级 suggest(兜底)
│
└─ 输出 suggestions[]: 每个调用一个建议

cangjie-knowledge-mcp/
├── config.yaml                  # 语料路径、索引参数、LLM 配置(api_key 走环境变量)
├── Dockerfile                   # MCP server 容器化镜像
├── opencode.json                # opencode MCP 注册配置
├── src/cjkb/
│   ├── models.py                # ApiRecord / ExampleRecord / JavaMapping 数据模型
│   ├── config.py                # 配置加载(支持环境变量覆盖)
│   ├── java_types.py            # Java 类型提取器(声明/泛型/调用接收者/构造调用/强转)
│   ├── nl_generator.py          # Java 代码 → 中英双语 NL 描述(LLM 或启发式)
│   ├── layered_search.py        # per-call 解析:类型锁定 + 分层 NL + 升降级 → suggestions[]
│   ├── reranker.py              # (可选)LLM 语义 rerank 层
│   ├── collector/
│   │   ├── corpus_parser.py     # 解析 CangjieCorpus 官方文档 → API/示例记录
│   │   ├── j2cj_parser.py       # 解析 j2cjlib shim + 术语表 → Java→Cangjie 映射
│   │   └── example_writer.py    # (可选)LLM 为缺少示例的 API 生成示例
│   ├── index/
│   │   ├── bm25.py              # 纯标准库 BM25(字段加权, 驼峰/下划线/中文 unigram 分词)
│   │   └── searcher.py          # 检索 API(相似度 + 精确名 + Java 术语扩展)
│   └── mcp_server.py            # MCP stdio 服务器(零第三方依赖)
├── scripts/
│   ├── build_kb.py              # 收集 + 建索引 → data/
│   ├── import_type_mappings.py  # 导入 x2cangjie 类型翻译产物
│   ├── install_kb.py            # 一键就绪:校验数据 + 自动重建索引
│   ├── generate_examples.py     # (可选)LLM 补写缺失示例
│   └── query_demo.py            # 命令行检索演示
├── tests/                       # 单元测试 + 综合端到端测试
└── data/                        # 知识库(JSONL 入库, pkl 派生不入库)

CangjieCorpus(官方文档)   x2cangjie 类型翻译产物   j2cjlib shim + 术语表
        │                        │                      │
        v                        v                      v
  corpus_parser.py        import_type_mappings.py   j2cj_parser.py
        └────────────────────────┼──────────────────────┘
                                 v
                        KnowledgeBase(JSONL) ──> BM25 索引 ──> MCP server
                                 │                              (stdio, 9 个工具)
                                 v
               Java 代码 → extract_types → resolve_java_code(per-call)

# 1. clone + 安装依赖(仅 PyYAML;索引核心零依赖)
git clone https://github.com/sskacc/cangjie-knowledge-mcp.git
pip install -r requirements.txt

# 2. 一键就绪:校验数据 + 自动重建索引(首次运行会自动完成,可跳过)
python scripts/install_kb.py

# 3. 命令行试一下
python scripts/query_demo.py "HashMap put key value"
python scripts/query_demo.py --class-members ArrayList
python scripts/query_demo.py --java "java.util.List"

# 4. 启动 MCP 服务器(stdio)
python -m cjkb.mcp_server --data-dir data

# 构建镜像(打包源码 + 知识库 + PyYAML)
docker build -t cangjie-knowledge-mcp .

# 直接运行 MCP server(stdio)
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test"}}}' \
  | docker run -i --rm cangjie-knowledge-mcp

// opencode.json(已随仓库提供)
{
  "mcp": {
    "cangjie-knowledge": {
      "type": "local",
      "command": ["docker", "run", "-i", "--rm", "cangjie-knowledge-mcp"],
      "enabled": true
    }
  }
}

{
  "mcp": {
    "cangjie-knowledge": {
      "type": "local",
      "command": ["python", "-m", "cjkb.mcp_server"],
      "enabled": true
    }
  }
}

# 1. 编辑 data/*.jsonl(增删 API 记录 / 示例 / Java 映射)
#    直接编辑 jsonl 即可,不必重跑 build_kb.py(重跑会覆盖手动改动)

# 2. 重建索引(改了 jsonl 后必须做,否则检索用旧索引)
python scripts/install_kb.py    # 或直接启动 MCP,load 时检测到 jsonl 更新会自动重建

# 3. 提交推送
git add data/*.jsonl
git commit -m "kb: add HashMap add/replace examples"
git push

python scripts/build_kb.py \
  --corpus <x2cangjie路径>/misc/CangjieCorpus \
  --j2cjlib <x2cangjie路径>/misc/j2cjlib \
  --terms <x2cangjie路径>/configs/java_cangjie_terms.yaml

# 重建后导入 x2cangjie 类型翻译产物(类型锁定靠它)
python scripts/import_type_mappings.py \
  --type-resolution <x2cangjie路径>/data/java/type_resolution

import sys
sys.path.insert(0, "src")
from cjkb.config import load_config
from cjkb.index.searcher import Searcher

cfg = load_config("config.yaml")
s = Searcher.load(cfg["output"]["data_dir"], cfg)

for r in s.search_api("HashMap put key value"):
    print(r.name, r.module, r.signature)

for m in s.java_to_cangjie("java.util.List"):
    print(m.java_symbol, "->", m.cangjie_symbol)

export OPENAI_API_KEY="..."
export OPENAI_BASE_URL="https://api.deepseek.com"    # 可选
export OPENAI_MODEL="deepseek-v4-flash"               # 可选

export OPENAI_API_KEY="..."

python scripts/generate_examples.py --dry-run      # 看有多少 API 缺示例
python scripts/generate_examples.py --limit 50     # 生成前 50 条(断点续跑)
python scripts/generate_examples.py --limit 0      # 生成全部缺失的

# 单元测试 + 综合端到端测试(需 Docker,或本机 Python + PyYAML)
docker run --rm -v "$(pwd):/app" -w /app cjkb-test:latest python -m pytest -q
# 或本机:
pip install pytest
python -m pytest -q