Skip to content

Commit 5910694

Browse files
authored
Merge pull request #203 from JiusiServe/kb/direct-routing-multirepo
Route Direct knowledge by per-repo data and a per-request knowledge view
2 parents 695a3c4 + 93ac5bb commit 5910694

16 files changed

Lines changed: 1033 additions & 268 deletions

File tree

‎doc/architecture/SPEC/direct_routing.md‎

Lines changed: 26 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,14 @@
11
# direct_routing.py —— 规范
22

3-
<!-- verified-against: 2026-09-10 -->
3+
<!-- verified-against: 2026-09-28 -->
44

5-
`LOC ~917 · Direct 模式完整策略包与知识路由 · refactor-status: known-debt`
5+
`LOC ~880 · Direct 模式完整策略包与仓库中立的知识路由 · refactor-status: stable`
66

77
## 职责
8-
Direct 模式的知识路由:owner/model 路由表和选路机制。从
9-
`thin_mcp_server.py` **逐字迁出**(下游曾经 `importlib` 拿它的私有名),
10-
公开面由 `contract.py` 再导出。它显式携带仓库专属知识 —— 这正是
11-
`contract.py` 必须保持中立而这里不必的原因;把表外置到
12-
`adapters/<repo>/` 是**未被这次搬迁改变的既有欠账**。
8+
Direct 模式的知识路由**机制**。模块中不出现任何被服务仓库的名字:每个仓库的
9+
owner/model 路由表是知识数据 `knowledge/repos/<repo>/_routes.yaml`,仓库别名
10+
来自 `adapters/<repo>/manifest.yaml` 的 `repo.full_name`/`repo.aliases`。
11+
公开面由 `contract.py` 再导出。
1312

1413
## 公开契约
1514
经 `contract.py` 再导出的五个名字:`direct_review_plan`(完整、一次性的
@@ -29,9 +28,15 @@ Direct policy bundle)、`direct_knowledge_routes`、
2928
又不许看"不是)。
3029
- adapter-backed changed-file 路由同样拆开 `(quick_map, status)`,绝不把 tuple
3130
当成文本跨边界,也绝不把 unavailable 误报成无需读取。
32-
- knowledge/adapters 根由 `sdk._resources` 的 `importlib.resources` 解析,editable
33-
source 与安装 wheel 走同一标记校验;仓库路径只留在本模块内部的旧版 dict,
34-
`sdk.v1.DirectClient` 对外转换为 document ID。
31+
- **每请求一个 `KnowledgeView`**:入口函数在开始时解析一次视图(未设置
32+
`KNOWLEDGE_ROOT` 时为打包知识;设置时为激活快照的真实目录并按清单校验),
33+
本请求内所有读取经同一视图。模块不再在导入期缓存知识根;`_KNOWLEDGE` 只保留
34+
为模块级 `__getattr__` 惰性别名。
35+
- **路由选择按数据而非仓库名**:仓库有非空 `_routes.yaml` → title/body owner
36+
路由 + 模型路由 + scope fallback;否则有 adapter → changed-file 路由;否则
37+
`unsupported_exact_router`。`_routes.yaml` 引用的页面不存在时 fail-closed。
38+
- `repo` 必填:空值抛 `ValueError`,不再默认某个仓库;形似路径的仓库名直接
39+
视为不支持。
3540
- **changed files 校验选择、绝不静默替换选择**:title/body 选 owner,
3641
diff 只报告支持或矛盾;scope-fallback 是最后手段且永远显式
3742
(`status="scope_fallback"`)。
@@ -46,23 +51,26 @@ Direct policy bundle)、`direct_knowledge_routes`、
4651
(`test_contract.py::test_direct_routing_does_not_import_a_server_module`)。
4752

4853
## 边界 —— 不属于这里
49-
不执行、不调模型;只有路由表 + 机制。多 adapter 桥接经
54+
不执行、不调模型;只有机制,路由表在知识数据里。多 adapter 桥接经
5055
`_normalize_repo`/`_adapter_for_repo` 走 `adapters/`。
5156

5257
## 依赖(允许)
53-
stdlib + `.adapters`(AdapterError / AdapterRegistry / RepoAdapter)+
54-
`.sdk._resources`。
58+
stdlib + PyYAML + `.adapters`(AdapterError / AdapterRegistry / RepoAdapter)+
59+
`.knowledge_view` + `.sdk._resources`。
5560
位于 `contract.py` 和 `thin_mcp_server.py` 之下。
5661

5762
## 扩展点
58-
新 owner 路由/模型规则 → 表数据;跨仓库通用化 → 外置进
59-
`adapters/<repo>/routing`(既有欠账的正解,不是在这里再长表)。
63+
新 owner 路由/模型规则 → 改对应仓库的 `_routes.yaml`(schema_version 1:
64+
`owners[{owner, path, signals, scope_prefixes}]`、可选 `models{dir, page}`);
65+
新仓库 → 提供 adapter 与 `_routes.yaml`,不改 `src/`。
6066

6167
## 测试
62-
`test_contract.py`(公开家、import 方向、中立性豁免);
68+
`test_knowledge_view_routing.py`(150 个真实 vllm-omni PR 的黄金路由输出、
69+
第二仓库经自身 `_routes.yaml` 路由、快照切换下一请求生效、快照篡改 fail-closed、
70+
SDK 完成校验钉住计划时快照、模块源码不含仓库名);`test_contract.py`(公开家、import 方向、中立性豁免);
6371
`test_thin_mcp_server.py` / `test_thin_mcp.py`(经新家继续锻炼全部
6472
下划线函数:路由、预算、完成门)。
6573

6674
## 重构备注
67-
768 行里约 500 行是表数据。`known-debt` 指的就是表:机制是稳定的,
68-
表的归宿在 adapter 数据面(见结构重组计划 Stage 8 的 routing.yaml 方案)。
75+
原 `_DIRECT_OWNER_ROUTES`/`_REPO_ALIASES` 已外置(`known-debt` 清零),
76+
`test_v2_p0.py` 与 `test_repo_vocabulary.py` 中本模块的泄漏上限随之移除。

‎doc/architecture/SPEC/knowledge_docs.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# knowledge_docs.py —— 规范
22

3-
<!-- verified-against: 2026-08-18 -->
3+
<!-- verified-against: 2026-09-28 -->
44

55
`LOC ~122 · 供 MCP 面使用的只读知识检索 · refactor-status: ok`
66

@@ -30,3 +30,6 @@
3030
## 重构备注
3131
**保持它不含模型**:这是 Direct MCP 路径与工具桥共用的**唯一**知识读取器,
3232
在这里加一次模型调用,等于把第二个模型塞进了"server 不跑模型"这条保证里面。
33+
34+
## 2026-09-28 快照校验
35+
可选 `verify(rel)` 回调在 `read`/`search` 读取每个文件前调用;MCP 传入 `KnowledgeView.path`,快照中缺失或被改动的文件使读取/搜索 fail-closed。
Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# knowledge_view.py —— 规范
2+
3+
<!-- verified-against: 2026-09-28 -->
4+
5+
`LOC ~170 · 每请求的知识树视图(打包知识或激活快照) · refactor-status: stable`
6+
7+
## 职责
8+
为每个请求解析**一个**知识根,并让本请求内所有读取经过它。知识服务通过原子
9+
切换符号链接激活新快照;导入期常量会一直服务旧树(包括已退役规则)直到进程
10+
重启,因此视图必须在请求开始时解析。
11+
12+
## 公开契约
13+
- `KnowledgeView.current()`:`KNOWLEDGE_ROOT` 未设置 → 打包知识,
14+
`snapshot="packaged"`;已设置 → 对其 `realpath` **只取一次**。含
15+
`MANIFEST.json` 的目录是激活快照,根为其 `knowledge/`;只含 `AGENTS.md` 的
16+
目录作为开发用未校验树(`snapshot="unverified:<path>"`);其余 fail-closed。
17+
- `view.path(rel)` / `view.read_text(rel)`:拒绝逃逸与缺失;快照模式下文件必须
18+
在清单中且 sha256 一致,否则抛 `KnowledgeViewError`。
19+
- `view.relative(path)`:绝对路径 → 知识相对 id。
20+
- `build_manifest(root, snapshot)`:生成 schema_version 1 清单
21+
(`files` 逐文件 sha256、`tree_sha256`)。
22+
23+
## 不变量
24+
- 一个请求不混用两棵树:解析后使用真实目录,不再经过符号链接。
25+
- 快照首次加载时校验:磁盘文件集合与清单完全一致、`tree_sha256` 与文件列表
26+
一致;每次读取再校验单文件 sha256。
27+
- 快照不可变,因此按解析后的目录缓存加载结果是安全的:新激活是另一个目录。
28+
29+
## 依赖(允许)
30+
stdlib + `.sdk._resources`。叶子模块。
31+
32+
## 测试
33+
`test_knowledge_view_routing.py`。

‎doc/architecture/SPEC/sdk.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# sdk/ —— 规范
22

3-
<!-- verified-against: 2026-09-26 -->
3+
<!-- verified-against: 2026-09-28 -->
44

55

66
`Python SDK v1 · 跨仓库唯一 typed 边界 · refactor-status: ok`
@@ -118,3 +118,6 @@ knowledge checkout,不改仓库真实 `knowledge/`。
118118
## Carried finding rechecks
119119

120120
Direct 1.1 / Strict 1.3 accept typed `CarriedFinding` inputs (unique IDs, source head, severity, location, title and evidence). Direct binds the carried set into its issued context and validates `FindingRecheck` answers. Strict passes the set through the policy allowlist, performs a read-only recheck against the frozen PR head, and persists answers for the public structured result. Every carried ID needs an explicit outcome: `fixed`, `still_affected`, or `unverified`. Missing evidence is never a fix.
121+
122+
## 2026-09-28 知识视图
123+
`DirectClient` 每次 `plan` 解析一个 `KnowledgeView`,文档引用与 `resource_revision` 均取自该视图;`validate` 按计划时钉住的知识根校验资源未变,激活新快照不会使进行中的 review 失效;`diagnostics.knowledge_snapshot` 报告所用快照。`read_document(..., review_context_id=...)` 从该 review 计划时钉住的知识树读取(含分页),未签发的 context id 被拒绝;不带 context id 时读当前激活树。

‎doc/architecture/SPEC/thin_mcp_server.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# thin_mcp_server.py —— 规范
22

3-
<!-- verified-against: 2026-08-31 -->
3+
<!-- verified-against: 2026-09-28 -->
44

55
`LOC ~490 · 默认 MCP:Direct 门面 + Strict 入口 · refactor-status: ok`
66

@@ -82,3 +82,6 @@ stdlib + `mcp` extra + `.direct_routing`(下划线别名 re-import)+
8282
迁到 `direct_routing`,避免 MCP 和 Python SDK 各拼一份协议。
8383
拆分保住了"server 不跑模型"—— 它仍是 Direct 模式的产品承诺;
8484
后续增长优先落到 `direct_routing`/adapter 数据面,不回到这里。
85+
86+
## 2026-09-28 知识视图
87+
知识根改为每次调用经 `KnowledgeView.current()` 解析;`_KNOWLEDGE` 仅为惰性别名。
Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Direct-mode owner routing for vllm-omni. Read by the repo-neutral router in
2+
# src/infermatrix_copilot/direct_routing.py; nothing in src/ names this repo.
3+
#
4+
# owners: the PR's title/body is matched against `signals` (word-bounded, case-
5+
# and separator-insensitive) to pick owner pages; `scope_prefixes` report which
6+
# owners the changed files touch, and select them only as a last resort.
7+
# models: every <dir>/<page> under `dir` is a model route matched by name.
8+
# Order of `owners` is the tie-break order and must stay stable.
9+
schema_version: 1
10+
owners:
11+
- owner: configuration
12+
path: repos/vllm-omni/components/configuration/rules.md
13+
signals: [config, configuration, yaml, registry, deploy, pipeline, override, default, cli flag, topology]
14+
scope_prefixes: [vllm_omni/config/, vllm_omni/deploy/]
15+
- owner: serving
16+
path: repos/vllm-omni/components/serving/rules.md
17+
signals: [serving, server, endpoint, openai, request, response, http, chat completion, completion endpoint, speech api, sse, websocket, sleep, wake, partial wake, engine lifecycle, idempotency, ack]
18+
scope_prefixes: [vllm_omni/entrypoints/openai/, vllm_omni/entrypoints/api_server.py, vllm_omni/entrypoints/async_omni.py]
19+
- owner: model-executor
20+
path: repos/vllm-omni/components/model-executor/rules.md
21+
signals: [model executor, loader, checkpoint, tokenizer, processor, stage input, stage handoff, runtime info, runtime_info, batch, sampling]
22+
scope_prefixes: [vllm_omni/model_executor/, vllm_omni/inputs/]
23+
- owner: diffusion
24+
path: repos/vllm-omni/components/diffusion/rules.md
25+
signals: [diffusion, image generation, text to image, image to image, lora, vae, dit, ulysses, cache dit]
26+
scope_prefixes: [vllm_omni/diffusion/, vllm_omni/model_executor/models/diffusers/]
27+
- owner: distributed
28+
path: repos/vllm-omni/components/distributed/_index.md
29+
signals: [distributed, tensor parallel, data parallel, replica, collective, rpc]
30+
scope_prefixes: [vllm_omni/distributed/, vllm_omni/worker/, vllm_omni/entrypoints/async_omni.py]
31+
- owner: scheduler
32+
path: repos/vllm-omni/components/scheduler/rules.md
33+
signals: [scheduler, scheduling, prefix cache, token budget, queue, side stream]
34+
scope_prefixes: [vllm_omni/core/sched/]
35+
models:
36+
dir: repos/vllm-omni/models
37+
page: rules.md

0 commit comments

Comments
 (0)