gen-system 发布：用解析器为本地 LLM 提供代码事实并生成 Go 服务

解析代码库的事实，以及来自本地模型的 Go 服务，这些服务必须在发布前编译通过。

为现有系统编写代码的模型必须对其做出猜测。这个例程调用了什么？它写入了哪些数据？一个 COBOL 段落从 copybook 中引入了什么？gen-system 用解析器回答这些问题，为 Go、带 copybook 的 COBOL、CA Gen、Java、TypeScript 和 Python 各手写一个解析器。它们构建每个例程的语法树、符号索引、调用图和控制流图。没有模型参与这一步，因此相同的代码总是给出相同的图。

对于每个例程，gen-system 随后列出输入、调用、它写入的数据以及其名称所暗示的操作。它将每一行称为一个信念。本地模型可以添加声明，而 gen-system 会标记任何与解析器矛盾的声明，并永不使用它。你可以纠正任何信念。只有经过人工验证的信念才会引导生成。

生成部分使用 qwen3:14b 规划一个 Go 服务，并使用 qwen2.5-coder:14b 编写每个操作。每个操作在进入服务文件之前必须能够独立编译。经过两次修复后仍然失败的函数体会变成一个 not implemented 桩，运行会将其计入。然后 go vet、go build 和 go test 在整个服务上运行，解析器再次读取结果。

我在 2026-09-09 测量了解析器，在四个固定到某个提交的公共仓库上：405 个文件，其中 268 个是 COBOL。它们实现了 0 个解析错误，并解析了每个项目自身符号之间 100% 的调用。它们构建了 1,302 个控制流图，没有一个有问题。在 60 个 SWE-bench Verified 任务上，gen-system 获取每个 issue 中的名称，并通过调用图走了两跳。该遍历到达了真实修复所触及文件的 0.674，每个任务中位数为 422 个文件。这是定位召回率，不是解决率：gen-system 不编写修复。原始文件在 results/2026-09-09/ 中。

你将获得

程序	它做什么
`understand-server`	浏览器中的 Studio：架构、符号搜索、调用图、控制流图、源代码和信念。就地纠正一个信念。只读，无模型
`understand-mcp`	为 Claude Code、Codex、Cursor 或任何 MCP 客户端提供相同的事实
`gen-enrich`	要求本地模型描述每个例程，并将答案存储为模型声明
`gen`	`idea` 规划并生成一个服务；`continue` 和 `evolve` 修改一个；`style` 测量并检查团队风格配置；`migrate` 应用数据库更改
`gen-server`	Studio 加上生成部分
`genbench`	测量数据：解析速度、调用解析、模型速度、生成

只读部分（understand-server、understand-mcp）不链接任何生成代码和模型客户端。如果这一点发生变化，架构测试（internal/archtest）会使构建失败。

安装

你需要 Go 1.25 或更新版本。生成部分还需要 Ollama 和一个具有 16 GB 显存的 GPU。我在 RTX 4060 Ti 16 GB 上运行它，在 Linux 和 Windows 上均可。

git clone https://github.com/hpdkhoa/gen-system.git
cd gen-system
./install.sh                # Go, Ollama, the two models, optional Postgres and Node
./install.sh --understand   # only the read only half, for an air gapped review

安装程序会拉取两个默认模型：

ollama pull qwen3:14b           # plans
ollama pull qwen2.5-coder:14b   # writes code

genbench model 显示 Ollama 是否启动、模型是否加载以及是否保持驻留。在测量任何内容之前运行它。

读取代码库

understand-server --root ./your-repo

打开 http://localhost:28080/。gen-system 将信念写入 ./your-repo/.gen/beliefs.json。在 Studio 中纠正一个，或 POST 到 /api/present/beliefs/correct。你的纠正从那时起生效。如果之后源代码发生变化，gen-system 会将信念标记为过时，并在新值旁边显示你的值。

Python 文件需要主机上安装 python3 3.9 或更新版本。其他五个解析器是纯 Go 的。解析器无法建模的构造会变成一个携带原因的未知节点。

为你的代理提供事实（MCP）

claude mcp add gen-understand -- npx -y gen-understand --root ./your-repo

或者，使用 Go 且无需 npm：

go install github.com/hpdkhoa/gen-system/generator/cmd/understand-mcp@latest
claude mcp add gen-understand -- understand-mcp --root ./your-repo

工具	回答
`architecture`	语言、热门包、入口点、调用解析，以及解析器无法建模的部分
`search_symbols`	按名称排序的符号，以及其他工具所需的 id
`call_graph`	从一个符号出发遍历调用边；无法解析的被调用方显示为外部节点
`control_flow`	一个函数的基本块、它们的边以及每个块中的源代码行
`source`, `file_symbols`	一个符号的代码；一个文件中的所有符号
`effects`	按所触及的内容分组：数据库、文件、网络、纯函数或未知
`beliefs`	带有来源（解析器、模型或人）的信念记录，可按例程、类型或验证状态过滤

correct_belief 仅在你以 --allow-corrections 启动服务器时存在。服务器在本地运行，不向任何地方发送数据。docs/mcp.md 涵盖了 Codex、Cursor、标志和协议。

生成服务

gen idea --out ./generated-app "a library lending service with members, books and loans"

每次模型调用都使用温度 0 和种子 42。gen-system 附加项目中每种语言的标准库，因此最终检查在读取输出时能识别 net/http 和 encoding/json。--stdlib none 会关闭该功能，--stdlib go,java=/opt/jdk/java.base 指定根目录。

团队风格配置将你的约定放入每个提示中。解析器随后对输出检查相同的规则：

gen style derive ~/code/team-repo --out gen-style.json   # measure a repo, with evidence per rule
gen idea --style gen-style.json --style-mode gate "a support ticket tracker"
gen style check ./generated-app/backend --profile gen-style.json

一个能编译但违反规则的操作会带着规则名称返回给模型。只有编译门可以将操作变成桩。docs/style-gate.md 列出了配置可以表达的内容。

设置

将 gen-system.env.example 复制到 .env。shell 中的变量优先于文件。

变量	含义
`OLLAMA_HOST`	Ollama 地址；默认 `http://127.0.0.1:11434`
`OLLAMA_MODEL_PLAN`, `OLLAMA_MODEL_CODE`	规划模型和代码模型
`OLLAMA_KEEP_ALIVE`	Ollama 在调用之间保持模型加载的时长
`OLLAMA_TIMEOUT`	每次模型调用的秒数
`GEN_STDLIB`	标准库根目录，采用 `--stdlib` 形式
`GEN_COBOL_COPYBOOK_PATH`	COBOL 解析器查找 copybook 的位置

工作原理

source ─▶ parsers ─▶ symbol index ─▶ call graph ─▶ control flow graphs ─▶ effects
                                         │
                                  parser beliefs ◀── model claims (checked against the parser)
                                         │
                                  your corrections (the only beliefs that steer)
                                         │
plan ─▶ generate ─▶ compile each operation ─▶ vet, build, test ─▶ the parsers read the result

generator/internal/ast：每种语言一个解析器，全部输出为一种树格式。
generator/internal/symbols, flow：符号索引、调用解析和控制流图。
generator/internal/belief：信念记录、模型声明、修正和过期。
generator/internal/presentation：Studio 和 MCP 服务器共享的 API。
generator/internal/engine, agent, planner_v2：规划、生成和门。
generator/internal/ai：通往模型的唯一路径。

两个模型依次运行。Ollama 在调用之间保持模型加载，在 2026-09-09 的运行中，两者之间切换大约需要 2 秒。

测试

make test

它在 generator/ 中运行 go test ./...。若干测试会在它们解析的代码旁边写入 .gen/ast_cache 文件夹；如果你想要干净的目录树，请在副本上运行它们。

基准测试

bench/ 包含测试框架、任务集和驱动程序。我在任何运行之前提交任务集。

./bench/freeze-env.sh    # record the commit, GPU, driver and model list
./bench/run-all.sh       # the full campaign
python3 bench/attest.py --results results/<date>

每次活动以 results/<date>/ATTESTATION.md 结束。它记录运行了什么、在哪个提交和机器上运行，以及测试框架丢弃了哪些运行及原因。MANIFEST.sha256 列出每个原始文件及其 SHA-256。bench/README.md 解释了每个驱动程序。

能编译的服务在这里是一个弱信号。两次未通过编译门的主体变成桩，而桩能编译。请阅读桩率和修复计数。

限制

一个 GPU。不支持多 GPU 或多节点。
六种语言。其他文件解析为未知节点，没有符号解析。
主体重写仅适用于 Go 和 Python。其他语言返回 not implemented 错误。
模型的安全审查只警告，从不阻止。
CLI 仅按服务汇总信念。模块和项目摘要的代码存在但尚未运行。

文档

docs/understand-pipeline.md：从源文件到控制流图。
docs/beliefs.md：信念记录、一个完整示例，以及过期如何传播。
docs/model-contact.md：通往模型的唯一路径及其设置。
docs/style-gate.md：风格配置和风格门。
docs/mcp.md：MCP 服务器。
docs/adding-a-language.md：如何添加解析器。

贡献

提交 issue 并附上 belief 文件（.gen/beliefs.json）。它会显示 gen-system 在哪里读错了代码。

许可证

Apache-2.0。参见 LICENSE 和 NOTICE。唯一的外部 Go 依赖是 github.com/lib/pq（MIT）。COBOL 基线在运行时会在固定的 commit 上拉取 CobolCraft（MIT）。