waqwaq

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="noun-tree-dark.png"> <img src="noun-tree-light.png" alt="" width="84"> </picture> </p> # 工具列表 ## Waqwaq 简介 Waqwaq 是一个单一目录的 OKF markdown 读取工具，可以通过 MCP、网页视图和终端视图三种方式访问。所有表面都解析为相同的无状态操作，操作对象是相同的 files，因此它们永远不会出现不一致的情况。 ## Waqwaq 是什么 Waqwaq 提供了一个 git-backed 文件夹的 [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) markdown 文件，并通过一个二进制文件提供了三种访问方式：代理的 MCP 端点、人员的网页视图和终端读取器。OKF 包是带有少量 YAML 前置字段的 markdown 目录（`type`、`description`、`resource`、`tags`、`timestamp`）。`wiki/` 目录下的页面是真实的；指向 waqwaq 一个没有 `wiki/` 子目录的文件夹，它将直接提供该文件夹的内容。 waqwaq 有自己的意见：它是 OKF 服务器，并强制执行该格式。它拒绝提供不符合 OKF 标准的包（每个概念页面必须带有 `type`，按照规范）。要提供不符合 OKF 标准的纯 markdown，请使用 `--lenient` 或在配置中添加 `"lenient": true`。 这是一个只读基准。没有任何写入路径：没有编辑、上传或变异工具。它的价值在于许多读者看到一个一致的知识库，而不需要它们之间的协调，因为核心是无状态的，并且在每次调用时根据文件系统和 git 重新导出每个答案。 ## 安装 ```bash go install github.com/msradam/waqwaq@latest # 或：go build -o waqwaq . ``` 纯 Go，无 cgo。可以使用普通的 `go build` 交叉编译到任何 `GOOS`/`GOARCH`（使用 `CGO_ENABLED=0` 验证）。git 历史记录通过 go-git 在进程中读取，因此主机上不需要 `git` 二进制文件。 ## 用法 ```bash waqwaq serve examples/okf-demo # 网页视图 + MCP 在一个端口上 ``` 网页视图位于 `http://127.0.0.1:8000/`，MCP 端点位于 `/mcp`。使用 `.mcp.json` 连接代理： ```json { "mcpServers": { "wiki": { "type": "http", "url": "http://127.0.0.1:8000/mcp" } } } ``` 或者，在没有运行服务器的情况下，作为 stdio 子进程： ```json { "mcpServers": { "wiki": { "command": "waqwaq", "args": ["mcp", "/path/to/wiki"] } } } ``` 其他命令： ```bash waqwaq tui <dir> 在终端读取器中浏览 waqwaq doctor <dir> 检查设置和 MCP 状态 waqwaq validate <dir> [--json] [--strict] 检查 OKF 合规性和链接，用于 CI（问题时返回非零） waqwaq toc <dir> 列出页面为 slug<tab>标题 waqwaq recent <dir> [--limit] 按 OKF 时间戳列出页面，最新的优先 waqwaq grep <query> <dir> 全文搜索；--regex, --type, --tag waqwaq cat <slug> <dir> 打印页面；--render 用于终端 markdown waqwaq init <dir> 搭建一个小型 OKF wiki ``` ## 文档 - [docs/mcp.md](docs/mcp.md) — MCP 参考：资源、每个工具、参数和对象形状、导航流程。 - [docs/architecture.md](docs/architecture.md) — 架构：核心接口、缓存设计、数据流和权衡。 - [BASELINE-NOTES.md](BASELINE-NOTES.md) — 决策历史和早期版本的内容。 ## 表面 所有三个读取表面共享一个无状态的核心，因此它们的答案是相同的。 - **MCP** (`serve`，或 `mcp` 通过 stdio)。资源是主要的读取接口：模板 `wiki://page/{slug}` 读取任何页面的正文，`resources/list` 枚举每个概念页面。工具涵盖了真正的查询：`wiki_info`（确认连接的 wiki），`wiki_list`（按前缀、类型、标签过滤；分页带有 `total`/`truncated`），`wiki_read`（正文加上内联的出站和入站链接，每个都有标题和类型），`wiki_search`（关键字 AND，或正则表达式，按类型和标签缩小范围），`wiki_backlinks`，`wiki_neighbors`，`wiki_tags`，`wiki_hubs`，`wiki_recent`（按 OKF 时间戳的页面，最新的优先），`wiki_graph`，`wiki_history`。每个工具都被注释为只读；没有变异工具。为了导航，优先使用 `wiki_read` 而不是原始资源：它还返回解析的前置字段和解析的链接。 - **网页视图** (`serve`)。浏览，读取渲染的 markdown，带有目录和链接侧栏，搜索，客户端强制有向图，按 OKF 类型着色。内置样式表，无需配置。 - **终端读取器** (`tui`)。浏览，模糊过滤，全文搜索，读取渲染的页面，遍历页面的链接。 `wiki_read` 和 `wiki://page/{slug}` 资源返回相同的数据；该工具适用于没有资源原语的客户端。 ## OKF 支持 Waqwaq 读取 OKF 前置字段，并在每个表面上公开它们： - `wiki_list` 和 `wiki_search` 接受 `type` 过滤器，因此代理可以询问所有 `BigQuery Table` 或所有 `Metric` 页面。 - `wiki_read` 和页面资源内联每个邻居的 slug、标题和类型，因此代理在无需读取每个邻居的情况下进行导航。 - 图形视图按类型使用开放调色板着色节点，因此生产者定义的任意类型（任何字符串，通常是多词）无需固定词汇即可渲染。 - 链接解析器理解 `[[wikilinks]]` 和相对 `.md` 链接（`[Orders](../tables/orders.md)`），这是上游 OKF 包表示边的常用方式，因此真正的 Google 包图形正确。 - `resource` 前置字段被视为指向底层资产的外部深层链接，与页面之间的链接不同。 - `index.md` 和 `log.md` 是保留的：免于类型要求，不被视为概念页面。`index.md` 是自然的入口点。 - OKF 合规性（每个概念页面上的 `type`）默认强制执行：`serve` 和 `mcp` 拒绝在非合规包上启动，`waqwaq validate` 报告违规者。 Waqwaq 遵循 [OKF 规范](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) v0.1：`type` 是唯一必需的字段，未知类型和额外的前置字段被保留，保留文件被视为导航而不是概念。 ### 示例 `examples/` 下有四个 OKF 包： - `okf-crypto-bitcoin/` 和 `okf-ga4/` 是从 Google 的 [knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog) （Apache 2.0，参见 [examples/NOTICE.md](examples/NOTICE.md)）直接获取的真实包。它们锻炼了真正的互操作性：概念通过相对 `.md` 路径链接，前置字段少的 `index.md` 目录列表，以及 `BigQuery Table` 和 `Reference` 等 `type` 值。 - `okf-demo/` 是一个小型手工数据目录，用作确定性的测试装置。 - `waqwaq-myth/` 是一个非数据目录领域的 OKF 包（中世纪 Waq-Waq 传奇），展示开放类型词汇（`Legend`、`Place`、`Reference`）。 ```bash waqwaq serve examples/okf-crypto-bitcoin # 真实的 Google OKF 包 ``` ### 验证包 `waqwaq validate` 检查包是否符合 OKF 规范（每个非保留概念页面都有一个非空 `type`）并报告损坏的链接： ```bash waqwaq validate examples/okf-ga4 # 规范一致性：需要 type waqwaq validate --strict examples/okf-ga4 # 还需要 description、timestamp ``` 默认设置与规范一致（仅需要 `type`；损坏的链接是警告，因为规范禁止因它们而拒绝包）。`--strict` 还需要 Google 参考丰富代理发出推荐字段。`serve`/`mcp` 在启动时运行相同的合规性检查，拒绝提供不符合规范的包。 没有官方的可运行 OKF 验证器（参考工具是 Python 且需要 Google Cloud 账户），因此直接在 Go 中实现了规范的一致性规则，通过 `core.Validate` 为库使用公开。 ### 测试对抗上游包 `hack/fetch-upstream-bundles.sh` 获取 Google 的真实 OKF 包（crypto_bitcoin、ga4、stackoverflow）到 `examples/upstream/` （gitignored），以便您可以验证和提供真实的第三方 OKF 数据： ```bash ./hack/fetch-upstream-bundles.sh waqwaq validate examples/upstream/stackoverflow waqwaq serve examples/upstream/stackoverflow ``` ## 规模 核心在结果上是无状态的（每次调用都反映当前的文件系统），但缓存派生的工作，以便在大型 wiki 上保持良好。它 memoized 了每个文件的解析前置字段（按 mtime 和大小键控）和派生的链接图（按 corpus 签名键控），仅重建更改的内容。刷新窗口（默认一秒）允许突发读取共享单个文件系统遍历；`serve` 在后台预热缓存，以便第一个请求不冷。 在 100,000 个页面（darwin/arm64）上测量：一个温暖的 `List` 或 `Read` 远小于一毫秒；整个语料库的一次性冷解析需要几秒钟，并在 `serve` 上后台进行。 生成一个大型 OKF wiki 进行测试： ```bash go run ./hack/genokf -out /tmp/bigwiki -pages 100000 waqwaq serve /tmp/bigwiki ``` 作为库： ```go import "github.com/msradam/waqwaq/core" c, _ := core.New("/path/to/okf-bundle", true, core.WithRefreshInterval(0)) pages, _ := c.List(ctx, "", "BigQuery Table", "", 50, 0) ``` `core.Core` 是每个表面（MCP、web、TUI）解析到的只读接口。 ## 配置 可选设置位于 `<dir>/.waqwaq/config.json` 中，所有字段都是可选的： ```json { "title": "Acme 数据目录", "mcp_description": "Acme 的内部数据目录：数据集、表格和指标", "addr": "127.0.0.1:8000" } ``` - `title`：显示名称和 MCP 服务器标识。MCP 客户端将其视为服务器名称，而不是“waqwaq”。 - `mcp_description`：MCP 指令中向代理显示的一行。 - `addr`：`serve` 的默认监听地址（`--addr` 标志覆盖它）。 - `lenient`：当 `true` 时，禁用 OKF 强制执行，以便 waqwaq 提供不符合 OKF 标准的纯 markdown。默认关闭（waqwaq 强制执行 OKF）。 如果 wiki 根目录下存在 `CLAUDE.md`，则将其作为 MCP 指令提供给代理。 ## 测试 通过 [ocarina](https://github.com/msradam/ocarina) 运行确定性 MCP 检查，该检查通过 YAML 剧本重放到实时服务器，无需模型参与： ```bash go build -o waqwaq . ocarina play perf/smoke.yaml # 13 步导航检查，基于 okf-demo ocarina play perf/okf-bundle.yaml # 与真实的 crypto_bitcoin 包互操作检查 ocarina load perf/load.yaml --vus 8 --threshold p95<500ms ``` `perf/smoke.yaml` 和 `perf/okf-bundle.yaml` 同时用作 CI 烟雾测试和退出非零的断言失败。核心和表面单元测试使用 `go test ./...` 运行。 ## 尚未重新连接 此基准版故意删除了早期版本具有的功能。它们被剪切，而不是隐藏，并且每个功能都将作为自己的更改返回： - **任何写入路径**：编辑、上传、审查和提案工作流、webhooks、令牌和代理头身份验证、角色。所有这些都存在以支持写入。重新连接写入意味着重新引入核心 `Write`/`Delete` 方法以及单个受信任/不受信任令牌区别，设计和审查其自身，而不是在这里半构建。 - **SQLite 全文索引**：被 in-process `internal/search` 替换（字面字符串加 RE2 正则表达式，并行遍历）。 - **代码库到 wiki 扫描器** (`scan`)：从 Go 导入图生成 wiki。 - **独立 JSON API** (`/api/*`)：MCP 现在是机器可读的表面。网页视图的 `/graph.json` 是图形视图内部的，而不是公共 API。 - **静态导出** (`export`)：一个独立的 HTML 站点。 - **网页主题**：强调和股票配置、`custom.css`、模板覆盖。 - **多 wiki 农场模式**：在 `/w/<name>/` 下提供多个 wiki。 参见 [BASELINE-NOTES.md](BASELINE-NOTES.md)，了解已转移的内容、已剪切的内容以及依赖项和接口选择背后的判断。 ## 开发 ```bash go test ./... CGO_ENABLED=0 go build -o waqwaq . ``` 使用 AI 辅助开发。 ## 许可证 MIT。参见 [LICENSE](LICENSE)。 树图标由 [Noun Project](https://thenounproject.com) 的 JK KIM 提供。