Skip to content

Commit 8a07586

Browse files
authored
Deliver bounded feature knowledge to reviews and update init workflow (#288)
Direct plans previously returned owner rule maps while feature-depth prose remained behind manual search/read. This change returns the most relevant explanatory knowledge automatically in Direct MCP, SDK and Agent review, using one repository-scoped reader with a two-document/6,000-character limit. Results expose source pins, missing depth facets and bounded followup reads; SDK references retain the plan snapshot and agent injection respects briefing ablation. Initialization now writes reviewed feature/entry-point/glob hints without changing accepted prose or checkpoint proofs. Existing JiuwenSwarm feature pages receive the same hints, and init/review skills, Cursor instructions, playbook and specs include offline retrieval acceptance. Knowledge bodies and hard-rule routes are unchanged. The workflow checker also recognizes the heading-form rule IDs used by the owner rules. Measured against merged baseline 2b66967: description+path probes deliver 79/79 feature explanations and 77/77 existing depth pages; paths-only probes deliver 77/79 features (ttse/worktree remain ambiguous). All 79 rule routes stay identical. Maximum background is 5,571 characters; local median retrieval overhead is about 1.9 seconds. These are catalog delivery measurements, not real PR recall or RQS gains. Breadth remains 2,043/2,199 files and checked depth 173/553 facets. Validation: full offline `python -m pytest -q`; post-review proof/depth/SDK/Agent regressions; CI knowledge-checker tests; both KB validators; doc links/citations and strict SPEC freshness; independent pinned-source audit; 158 actual Direct acceptance probes. Independent complete-diff review and `--require-clean` passed after fixing malformed proof digest/path acceptance. Final whole-tree validation also runs in PR CI. The 156 generated metadata-only page edits preserve original bodies. Generated audit JSON is intentionally included for reproducibility and is exempt from the production code-size budget; runtime source adds 256 lines, plus two checker lines and the offline audit tool. No new model provider, retrieval model call, extraction stage or persistent index is introduced. Chinese report and reproducible evidence: `eval/knowledge-depth/jiuwenswarm-retrieval-improvement-cn.md`, `jiuwenswarm-retrieval-acceptance-20261002.json`, `jiuwenswarm-retrieval-baseline-20261002.json`, `jiuwenswarm-retrieval-depth-audit-20261002.json`, and `retrieval-independent-review-20261002.md`.
1 parent 2b66967 commit 8a07586

197 files changed

Lines changed: 14702 additions & 45 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎doc/architecture/SPEC/direct_routing.md‎

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

3-
<!-- verified-against: 2026-10-01 -->
3+
<!-- verified-against: 2026-10-02 -->
44

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

@@ -11,6 +11,11 @@ owner/model 路由表是知识数据 `knowledge/repos/<repo>/_routes.yaml`,仓
1111
公开面由 `contract.py` 再导出。
1212

1313
## 公开契约
14+
15+
`direct_review_plan` 另返回 `related_knowledge`:从本次 `KnowledgeView` 按 diff 路径和描述
16+
检索的有限解释性正文。`navigation_policy.related_document_read_paths` 只列截断背景页,
17+
每页增加一次 `execution_budget.knowledge_file_reads`;完整内嵌内容不需要再读文件。
18+
owner/model 路由仍先按描述选择,路径仍用于路由范围校验;背景检索不增补硬规则路由。
1419
经 `contract.py` 再导出的五个名字:`direct_review_plan`(完整、一次性的
1520
Direct policy bundle)、`direct_knowledge_routes`、
1621
`direct_execution_budget`、`direct_completion_result`、

‎doc/architecture/SPEC/engine/agent_runtime.md‎

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

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

55
`LOC ~1690(7 个文件) · 引擎(受治理的 agent 运行时) · refactor-status: ok`
66

77
## 职责
8+
9+
开启 `profile_briefing_enabled` 且证据包含 `pr_diff` 时,runner 使用既有 diff parser 提取
10+
路径,通过 `doc_related` 在首个模型调用前注入同一有界知识背景。内容放入 untrusted
11+
围栏并转义标签;`review_knowledge_context` 记录命中页面、状态和正文长度。
12+
关闭 briefing 时自动背景注入也关闭;无关路径不补入知识。Agent 可按需调用该只读工具。
813
每个 `kind == "agent"` step 的**唯一**受治理入口,外加评审质量 ensemble。
914
它是全库信息密度最高、杠杆最大的子系统 —— 曾经是一个 685 行的模块,
1015
现在是一个把底座(dispatch/knowledge/utils)与两个入口(runner/ensemble)分开的包。

‎doc/architecture/SPEC/kb_service.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -677,3 +677,13 @@ PR 描述只展示前 20 个升级及总数,完整来源留在 commit trailers
677677
模型失败、findings 或远程 head 变化均保持阻塞;人仍负责合并。
678678
dry run 为旧快照建本地临时 baseline,再生成相同升级串与全量 Codex 审阅,落盘预览和 `COMMITS.json`,不写 GitHub。
679679
全程不打开服务账本。测试:`test_kb_init_history.py`、`test_kb_init_config.py`、`test_imkbinit_skill.py`。
680+
681+
682+
## 2026-10-02 初始化与检索验收
683+
684+
`knowledge` 与有 accepted depth 的 `knowledge-deepen` 从 coverage policy 更新现存功能解释页
685+
的 `feature`、`entry_points`、`source_globs`;同一 writer 保留正文和来源。深读 checkpoint
686+
仍绑定 accepted 原文哈希,恢复后再生成提示,不改已接受证明。全部被拒绝时不写 metadata-only
687+
变更,保持 empty 阶段语义。提示不会增加 coverage、创建规则或改 owner 路由。
688+
完成合并后的完整 checkout 用 `tools/audit_review_retrieval.py` 验收 Direct 上下文交付,
689+
同时报告描述+路径与仅路径结果。报告在 eval/本地状态,与 breadth/depth 审计分开;不是 RQS 或缺陷召回率。

‎doc/architecture/SPEC/knowledge_docs.md‎

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

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

5-
`LOC ~122 · 供 MCP 面使用的只读知识检索 · refactor-status: ok`
5+
`LOC ~280 · 供 Direct 与 Agent 共用的只读知识检索 · refactor-status: ok`
66

77
## 职责
88
对那棵精选 Markdown 知识库的跨平台、按仓库限定的**只读访问** ——
9-
`doc_search`/`doc_read` 的底座。
9+
`doc_search`/`doc_read`/`doc_related` 的底座。
1010

1111
## 公开契约
12-
`KnowledgeDocs`(search、read)、`KnowledgeDocsError`。
12+
`KnowledgeDocs`(search、read、related)、`KnowledgeDocsError`。
1313

1414
## 不变量(**C1**、**D1**)
1515
- **限定在切片内**:general 切片加上**单个**仓库的切片。知识根之外的路径一律拒绝
@@ -22,10 +22,20 @@
2222
不撰写知识、不提 candidate、不在代码里放仓库专属规则(那棵树是数据面)。
2323

2424
## 依赖(允许)
25-
仅 stdlib。
25+
stdlib 与 `knowledge_service.lifecycle` 的页面/完整深读正文解析;不依赖模型、配置或 server。
2626

2727
## 测试
28-
`test_knowledge_source.py`、`test_thin_mcp_server.py`。
28+
`test_knowledge_source.py`、`test_knowledge_retrieval.py`、`test_thin_mcp_server.py`。
29+
30+
## 有界审查背景
31+
32+
`related(changed_files, query=...)` 只选当前 repo 的 architecture/guide;规则页、索引与
33+
结构化接口卡不进入背景。确定性优先级为固定来源路径、生产入口、源码 glob,再结合
34+
功能 ID/标题和正文词命中;相同 feature 去重,完整深读优先于基础功能页。
35+
最多返回两页、每页 3,000 字符、总计 6,000 字符;优先完整 facet,超长单 facet 仍提供
36+
截断片段并标 `more_available`。返回来源 pin、命中路径、已有/缺失 facet,不验证 PR head。
37+
深读正文哈希、证明形状或重复 facet 有问题时不提供该块;上游证据验证仍属于 init/audit。
38+
所有读取前调用同一 `verify`,包括最终被排除的接口卡;激活快照校验失败直接阻断。
2939

3040
## 重构备注
3141
**保持它不含模型**:这是 Direct MCP 路径与工具桥共用的**唯一**知识读取器,

‎doc/architecture/SPEC/knowledge_service.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# knowledge_service/ — provider curation components
22

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

55
The provider owns knowledge curation beneath the public SDK v1 facade.
66
`KnowledgeCurator` composes four domain components over one explicit work
@@ -20,6 +20,9 @@ contracts across the move.
2020

2121
Knowledge Ops API 2.0 sits beside the v1 curator and does not change it:
2222
`lifecycle` parses rule pages (byte-exact) and their `kb:rule` footers,
23+
and owns the shared depth format, intact-prose reader and safe source-path
24+
syntax used by retrieval and init/audit; upstream proof verification stays in
25+
`kb_service.knowledge_depth`.
2326
`ops.apply_operations` applies typed add / edit_same_meaning / replace / retire
2427
/ purge changes with their mechanical consequences, and `l1` is the
2528
deterministic half of the quality gate (`check_tree`, `check_changeset`). The

‎doc/architecture/SPEC/knowledge_service/lifecycle.md‎

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

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

55
`LOC ~330 · 规则页数据模型与生命周期尾注 · refactor-status: stable`
66

@@ -10,6 +10,10 @@
1010
reason、evidence、supersedes、superseded_by、protected);无尾注即 active。
1111

1212
## 公开契约
13+
14+
`DEPTH_FACETS`、`DEPTH_BLOCK` 和 `depth_sections` 是 init/audit 与检索共享的深读数据格式。
15+
后者只返回正文哈希完整、facet 唯一且 proof evidence 形状合法的段落,隐藏 proof 注释,
16+
不重新读取上游证据。固定源码验证仍由 `kb_service.knowledge_depth` 负责。
1317
`Page.parse/render`、`Page.rules/rule/replace_section/append_section`、
1418
`Page.sources/with_sources`(按页面原风格写 flow 或 block 列表)、`Section.footer/
1519
with_footer/body_without_footer/content_sha256/citations`、`Footer.parse/render/check`、

‎doc/architecture/SPEC/sdk.md‎

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

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

55

66
`Python SDK v1 · 跨仓库唯一 typed 边界 · refactor-status: ok`
77

88
## 职责
99

10+
`DirectReviewPlan.related_knowledge` 是有默认空字典的增量字段,与 MCP 提供同一有界背景。
11+
每个相关文档另带内容寻址的 `document` 引用,路径保持知识相对 ID;后续读取使用原
12+
`review_context_id`,不混入激活切换后的另一快照。正文 pin 与 PR head 分别记录。
13+
1014
给 ReviewBot 等嵌入式宿主提供一个版本化、可序列化、wheel-safe 的公开 API:
1115
`infermatrix_copilot.sdk.v1`。宿主不得再 import `mcp_server`、`config`、
1216
`thin_mcp_server` 或其私有 helper。

‎doc/knowledge/SCHEMA.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,13 @@ validation 六个维度。它生成的非规则段使用 `kb:knowledge` HTML 注
4040
实现知识;旧标记、静态接口卡、规则和索引不计入此深度。正文或证据改变、pin 不符或重复
4141
facet 均失效。页面仍使用既有 architecture/guide 类型,设计推断与未验证测试明确标出。
4242

43+
功能解释页可声明 `feature`(功能 ID)、`entry_points`(生产入口路径列表)和
44+
`source_globs`(所属源码 glob 列表)。`knowledge`/`knowledge-deepen` 从同一份已审阅
45+
coverage policy 生成这些匹配提示,刷新时保留正文、来源和深读证明。提示只选择审查背景,
46+
不增加文件或行为覆盖率;旧页仍可通过 `sources` 中的固定源码路径匹配。
47+
Direct 的 `related_knowledge` 与 Agent 的 `doc_related` 共用确定性检索,最多提供两页、
48+
共 6,000 字符,附来源 pin、已有/缺失 facet 和截断状态;它不把推断变成硬规则。
49+
4350
`check_wiki_lint.py` 强制的只有前五项(`title`、`created`、`updated`、`type`、
4451
非空 `tags`);其余为约定字段,写了就必须合法(`confidence` 只能取三值)。
4552

0 commit comments

Comments
 (0)