Synthos Akne Bridge

Synthos-AKNE Bridge — 双向桥接

负责 Synthos（论文管线）和 AKNE（知识图谱）之间的具体桥接操作。 与 akne-maintenance 和 akne-knowledge-manager 不同：本技能执行具体修复动作。

IO_CONTRACT

• input: graph.json: file — AKNE 知识图谱（节点/边，关系值在 link_type/key 字段而非 relation）
• input: papers_dir: path — outputs/papers/* Synthos 论文目录（Step 2 规范化为 01-manuscript/06-references/07-quality）
• input: query: str + mode: enum[simple|graph|concept|full|stats|bridge] — akne-query.sh 查询（系统 Python 3.12，非 venv 3.11）
• input: vectors.db: sqlite — 向量库（1145 源文件 + wiki，metadata 含 content_summary/content_hash）
• output: graph.json — 更新后的图谱（连接孤立论文/技能、创建 source_category 等逆向边、注入 content_summary metadata）
• output: akne-query.sh <mode> output — 结构化查询结果（entity/neighbors/BFS 节点/QueryEngine 结果/stats/bridge 审计：papers+skills connected, orphans=0）

原则 (Principles)

先诊后治，孤儿必零。 动手前以 akne-query.sh bridge 诊断连接状态，目标是孤立论文/技能归零。 双向成流，逆边必建。 只造正向边则知识单向——source_category 等逆向边须显式补齐，方有回流。 三线并行，缺一即残。 source 节点、content_summary 摘要、vectors.db 向量三线并进，任一线断则语义检索残缺。 环境各守其界。 execute_code 走 venv 3.11 处理逻辑，AKNE 查询走 terminal 系统 3.12，不越界 import。

Genes (策略基因)

紧凑策略表示。条件→策略。需要深度时参考完整文档。

• [SYNT-009] 执行桥接修复前 → 必须运行 akne-query.sh bridge 诊断连接状态，确立“先诊后治”且以孤立节点归零为最终目标
• [SYNT-010] 构建知识图谱边时 → 必须显式创建 source_category 等逆向边，确保知识流双向可达，避免单向依赖
• [SYNT-011] 执行语义检索与数据注入时 → 必须同步推进 source 节点、content_summary 摘要、vectors.db 向量三条线，任一线断裂即导致检索残缺
• [SYNT-012] 调用 Python 环境时 → 严格隔离边界，逻辑处理走 venv 3.11，AKNE 查询走系统 3.12，禁止跨环境 import
• [SYNT-013] 处理 Synthos 论文目录时 → 必须规范化为 01-manuscript/06-references/07-quality 子目录结构，以便后续图谱映射
• [SYNT-014] 连接孤立论文或技能时 → 依据领域关键词（如 BPPV、眼动、科研）手动映射至对应的 AKNE 分类及 Wiki 概念节点
• [SYNT-015] 注入源节点元数据时 → 提取前 3KB 内容生成 content_summary、content_hash 及标题层级，以支持图内内容语义搜索

当前状态（2026-06-13 全面修复后）

• Synthos 论文: 148/148 连接 (0 孤立), 116 有出边
• Synthos 技能: 25/25 连接 (0 孤立)
• 图谱总节点: 1475, 总边: 5868
• 双向路径: source→category→paper, concept↔paper, skill→domain→concept
• Wiki 污染: 0 行
• 查询引擎: QueryEngine + KnowledgeGraph + jieba 分词，6 种模式可用
• 向量搜索: vectors.db 1178 条记录 (wiki 35文件, 全部 1145 源文件已向量化)
• 守护进程: 运行中
• 内容注入: 所有 1145 个 source 节点已注入 content_summary/content_hash/word_count/h1/h2

查询引擎操作（2026-06-13 新增）

AKNE 提供6种查询模式，通过 terminal 工具执行 akne-query.sh：

# 1. 简单查询 - 实体解析 + 相关节点
~/.hermes/scripts/akne-query.sh simple "BPPV"
# 输出: entity: bppv → 5 neighbors (诊疗规范/试验/论文/解剖/医生)

# 2. 图谱遍历 - BFS depth=3
~/.hermes/scripts/akne-query.sh graph "BPPV"
# 输出: 6 nodes, depth 0-1

# 3. 概念搜索 - 相关概念节点
~/.hermes/scripts/akne-query.sh concept "眩晕"
# 输出: 398 results (source_category + sources)

# 4. 全功能查询 - graph + QueryEngine + jieba 分词增强
~/.hermes/scripts/akne-query.sh full "半规管"
# 输出: entity + neighbors + QueryEngine results + tokens

# 5. 统计 - 图谱规模
~/.hermes/scripts/akne-query.sh stats
# 输出: nodes/edges/types/vectors count

# 6. 桥接报告 - Synthos 连接状态
~/.hermes/scripts/akne-query.sh bridge
# 输出: papers/skills connected, edges by type, orphans

查询模式详解

simple — 最常用。resolve_entity → find_related(depth=2)。fallback 遍历所有 node names 做子串匹配。

graph — BFS 遍历从实体开始。适合探索知识域边界。depth=3 上限。

full — 最强大。jieba 中文分词 + 多 token 匹配（边界/路径分隔符 ×2，子串 ×1，阈值≥2）。然后 QueryEngine 搜索 + 图遍历。

bridge — 审计模式。检查 Synthos 论文/技能连接状态、知识流路径、孤儿检查。

架构约束

• venv Python 3.11: networkx 3.6.1 已安装（轻量，30ms），但无 sentence-transformers（torch 500MB+ 太大）
• 系统 Python 3.12: jieba + sentence-transformers + networkx 可用。所有 AKNE 查询通过 terminal 工具走系统 Python
• 向量覆盖: vectors.db 有 1178 条记录 (1145 source + 33 wiki)，100% 源文件已向量化
• QueryEngine: resolve_entity 用 4 级相似度（精确→子串→Token Jaccard→模糊），但多词英文查询（"eye tracking methodology"）仍无效——依赖图搜索或向量搜索

桥接操作步骤

Step 1: 诊断当前状态

# 优先用 akne-query.sh bridge（快速、结构化输出）
~/.hermes/scripts/akne-query.sh bridge

# 检查: synthos_paper_with_edges > 0, skill_connected = total, orphans = 0
# 检查: bridge_path_source_category_paper = YES, bridge_path_concept_paper = YES

注意: 旧版 python3 scripts/synthos-akne-bridge-v2.py report 仍可用，但 akne-query.sh bridge 更快、输出更结构化。

Step 2: 规范化 Synthos 论文目录

如果论文缺少 01-manuscript/06-references/07-quality，需归入子目录：

# 扫描不规范论文
SYNTHOS_DIR = "/media/yakeworld/sda2/Synthos/outputs/papers"
for d in os.listdir(SYNTHOS_DIR):
    full = SYNTHOS_DIR / d
    has_ms = (full / "01-manuscript").is_dir()
    has_ref = (full / "06-references").is_dir()
    has_qc = (full / "07-quality").is_dir()
    if not (has_ms or has_ref or has_qc):
        print(f"IMPROPER: {d}")
        # 检查文件内容决定分类
        contents = os.listdir(full)
        # 有 .tex/.pdf + 01-05 系列文件 → 01-manuscript
        # 有文献调查文件 → 06-references
        # 有质量检查文件 → 07-quality

规范化后重建目录:

mkdir -p paper/{01-manuscript,06-references,07-quality}
mv paper.tex 01-manuscript/
mv literature-survey.md 06-references/
mv qc-d8-refs.md 07-quality/

Step 3: 连接孤立论文

对 domain="其他"的论文，手动映射到 AKNE 分类:

# 在 graph.json 中为孤立论文添加 paper_source_domain 边
# 领域映射参考:
# 眼科/虹膜/眼动 → 眼动研究
# 半规管/前庭 → 半规管空间姿态研究
# BPPV/耳石/眩晕 → BPPV
# 医学AI筛查 → 投稿
# 工程/数学 → 编程
# Synthos 自身 → 科研

Step 4: 连接 Synthos 技能

每个技能需要连到:

• 2-3 个源文件分类 (skill_source_domain)
• 2-3 个 Wiki 概念 (skill_concept)

映射参考:

SKILL_TO_CATEGORIES = {
    "research": ["科研", "投稿", "论文集", "论文评审日记"],
    "knowledge-acquisition": ["科研", "投稿"],
    "hypothesis-generation": ["科研", "半规管空间姿态研究"],
    "argument-expression": ["科研", "半规管空间姿态研究", "BPPV"],
    "quality": ["BPPV", "科研", "投稿"],
    "evolution": ["科研"],
    "mlops": ["科研", "编程"],
    "patent-disclosure": ["发明创造"],
    "writing": ["投稿", "科研"],
    # ... 每个技能按名称推断领域
}

SKILL_TO_WIKI = {
    "research": ["科研课题研究", "科研论文检索系统", "llm-wiki"],
    "hypothesis-generation": ["科研课题研究", "第一性原理"],
    "argument-expression": ["科研思维层级", "模型依赖实在论"],
    "quality": ["资产审计"],
    "evolution": ["自由能原理", "模型依赖实在论"],
    # ...
}

Step 5: 创建逆向边

为双向知识流，需创建:

1. source_category (源文件→分类) — 反向 source_category_membership
2. category_paper (分类→论文) — 反向 paper_source_domain
3. concept_paper (概念→论文) — 反向 paper_concept
4. paper_category (论文→分类) — 反向 paper_source_domain

路径: source → category → paper (2跳)

Step 6: 清理 Wiki 污染

import re
garbage = re.compile(r'^\[\s*[^]]*\]\s*::.*$')
for fpath in [wiki_dir/'index.md', wiki_dir/'log.md', ROOT/'CATALOG.md']:
    lines = [l for l in fpath.read_text().split('\n') if not garbage.match(l.strip())]
    fpath.write_text('\n'.join(lines))

Step 7: 重启自动守护

pkill -f auto_evolve_daemon 2>/dev/null
sleep 0.5
cd /media/yakeworld/sda2/academic_writer/yakeworld
nohup python3 scripts/auto_evolve_daemon.py > /dev/null 2>&1 &

Step 8: 验证

~/.hermes/scripts/akne-query.sh bridge
# 检查: synthos_paper_with_edges > 0, skill_connected = total, orphans = 0

Step 9: 注入内容摘要（2026-06-13 新增）

为所有 source 节点注入内容摘要，使 KnowledgeGraph 可在图内做内容语义搜索：

import json, os, re, hashlib

# 读取每个源文件，提取内容摘要
for s in sources:  # 1145 source nodes from graph.json
    full_path = os.path.join("/media/yakeworld/sda2/academic_writer/yakeworld", s['name'])
    with open(full_path, 'r', encoding='utf-8', errors='ignore') as f:
        content = f.read(3000)  # 最多读取前3KB

    # 提取: h1, h2[:2], [科学假设], [开放问题], 前100词
    h1 = re.findall(r'^#\s+(.+)$', content, re.MULTILINE)
    h2 = re.findall(r'^##\s+(.+)$', content, re.MULTILINE)
    hypotheses = re.findall(r'\[科学假设\]\s*\n(.*?)(?=\n\[|$)', content, re.DOTALL)
    questions = re.findall(r'\[开放问题\]\s*\n(.*?)(?=\n\[|$)', content, re.DOTALL)

    # 注入到 source 节点 metadata
    s['metadata']['content_summary'] = '\n'.join(summary_parts)[:500]
    s['metadata']['content_hash'] = hashlib.md5(content[:500].encode('utf-8')).hexdigest()
    s['metadata']['word_count'] = len(content.split())
    s['metadata']['has_hypothesis'] = len(hypotheses) > 0
    s['metadata']['h1'] = h1[0] if h1 else ''

Step 10: 向量化补充（2026-06-13 新增）

向量化尚未向量化的源文件。将文件内容写入 vectors.db（metadata 包含 source/type/category/word_count/content_hash/content_summary/h1/h2）：

conn = sqlite3.connect("/media/yakeworld/sda2/academic_writer/yakeworld/.knowledge/vectors.db")
for name in unvectorized:  # 从 graph.json sources 中找出未在 vectors.db 的
    full_path = os.path.join("/media/yakeworld/sda2/academic_writer/yakeworld", name)
    with open(full_path, 'r', encoding='utf-8', errors='ignore') as f:
        content = f.read(3000)
    conn.execute(
        "INSERT INTO vectors (id, text, embedding, metadata, created_at, updated_at, chunk_index, version) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
        (name, content, b'', json.dumps(metadata), time.time(), time.time(), 0, 1)
    )
# 最终: 1145/1145 源文件已向量化，33/35 wiki 文件已向量化

常见陷阱

1. resolve_entity 在 QueryEngine，不在 KnowledgeGraph

kg.resolve_entity() 不存在！必须用 QueryEngine(graph_index=kg).resolve_entity()。所有脚本（akne-query.sh）和代码都必须通过 QueryEngine。

2. find_related() 返回 3 元组，不是 4 元组

kg.find_related(entity) 返回 [(neighbor, relation_chain, metadata), ...]，不是 4 值。切勿用 for n, r, m, d in related: 解包，会报 ValueError: too many values to unpack。

3. bridge 模式中 in_edges(data=True) 返回 3 元组，不是 4 元组

kg.graph.in_edges(p, data=True) 返回 (src, tgt, data_dict)，不是 4 值。统一用 data=True（3 值）或 data=True, keys=True（4 值），不要混用。

4. 桥接脚本跳过子目录

synthos-akne-bridge-v2.py 会跳过非论文目录（_docs, _todo 等）。需要更新排除列表:

if paper_name in ("_docs", "_archive_scripts", "_todo", "papers", "references",
                   "scripts", "lit-reviews", "gap-paper-35-neuromorphic-eye-tracking",
                   "kaggle-wdbc-classification", "pinn-operator-learning-generalization",
                   "portable-et-r2", "scale-space-feature-tensor", "01-gap_analysis",
                   "09-manuscript", "110-direction-scan"):
    continue

5. 边方向错误

source_category_membership 是 category→source（分类→源文件），不是 source→category。创建反向边时必须显式添加 source_category 类型。

6. 孤立论文域分类

_classify_paper() 只能识别6个固定领域。其他论文需手动映射到正确 AKNE 分类。

7. 非论文节点混入

子目录 papers, references, scripts 等会被桥接脚本创建为 synthos_paper 节点。需重分类为 synthos_misc 并从边中移除引用。

8. 多词/英文查询在 QueryEngine 中无效

_graph_search 使用词袋匹配，对多词英文查询（如 "eye tracking methodology"）无效。需要依赖：

• 图搜索（resolve_entity → find_related）
• 向量搜索（vectors.db，但多词英文仍无效）
• full 模式中的 jieba 分词 + 多 token 子串匹配（阈值≥2）

9. execute_code 与 AKNE 的环境隔离

execute_code 运行在 venv Python 3.11 中（networkx 3.6.1 已装，但无 sentence-transformers）。所有 AKNE 查询必须通过 terminal 工具走系统 Python 3.12。不要在 execute_code 中 import AKNE。

10. graph.json 中 edge relation 字段为空

graph.json 中所有 edge 的 relation 字段为空字符串，实际关系值存储在 link_type 或 key 字段。KnowledgeGraph._load_or_create() 会同时检查 relation 和 link_type 所以加载正确，但直接读 JSON 时需检查 link_type 字段。

参考文件

ref/synthos-akne-integration-audit.md — 修复后完整审计数据。 references/query-engine-architecture.md — QueryEngine 架构说明、API 参考、陷阱记录。 references/bridge-script-reference.md — akne-query.sh 各模式详解与输出格式。 references/enhanced-search.md — akne-enhanced-search.py 语义搜索增强（TF-IDF+jieba+融合评分）。 references/content-summary-injection.md — source 节点内容摘要注入方法和结构。 references/vectorization-completion.md — 1145 源文件向量化完成报告。

通用方法论

AKNE 桥接遵循 kg-bridge（Knowledge Graph — Agent Bridge）方法论：

验证清单 · VERIFICATION

• 先诊后治（SYNT-001）：动手修复前是否先运行 akne-query.sh bridge 诊断，且最终 orphans=0、skill_connected=total
• 逆向边成流（SYNT-002）：是否显式创建 source_category/category_paper/concept_paper/paper_category 逆向边，source→category→paper 双向路径可达
• 三线并行（SYNT-003）：source 节点、content_summary 摘要、vectors.db 向量三线是否齐全，1145 源文件已向量化
• 环境隔离（SYNT-004）：逻辑处理走 venv 3.11、AKNE 查询走系统 3.12，未在 execute_code 中 import AKNE
• 论文目录规范化（SYNT-005）：论文是否归入 01-manuscript/06-references/07-quality 子目录，无 IMPROPER 残留
• 孤立连接（SYNT-006/007）：孤立论文按领域关键词手动映射到 AKNE 分类，技能各连 2-3 源分类与 Wiki 概念
• 边方向正确：source_category_membership 为 category→source，直读 JSON 时检查 link_type/key 字段而非空的 relation
• 查询与 API 正确：resolve_entity 走 QueryEngine、find_related/in_edges 按 3 元组解包，多词英文查询用 full 模式 jieba 分词兜底
• 内容注入：source 节点 metadata 含 content_summary/content_hash/word_count/h1，Wiki 污染 0 行

约束规则 · RULES

1. 输入约束: 参数类型、范围、格式必须校验
2. 输出约束: 返回值结构、编码、命名必须一致
3. 异常约束: 错误信息必须包含上下文和恢复建议
4. 安全约束: 不执行未验证的任意代码，不暴露内部状态

Golden 集合 · GOLDEN SET

• Golden Input: 一份含孤立论文的 AKNE graph.json（关系值存于 link_type/key，relation 为空）+ 一个缺少 01-manuscript/06-references/07-quality 子目录的 outputs/papers/* 论文目录，作为"先诊后治"修复输入（SYNT-001/005）。
• Golden Output: 重跑 ~/.hermes/scripts/akne-query.sh bridge 输出 orphans=0、skill_connected=total、synthos_paper_with_edges > 0，且 source→category→paper 双向路径 = YES（显式建 source_category 等逆向边，SYNT-002）。
• Golden Error: 在 venv 3.11 的 execute_code 中 import AKNE/QueryEngine，或按 4 值解包 kg.find_related()/in_edges(data=True) → 预期 ModuleNotFoundError（无 sentence-transformers，SYNT-004）或 ValueError: too many values to unpack（陷阱 2/3，应为 3 元组）。

Golden 集合是测试的单一真理来源。所有改进必须通过 golden 测试。

违反规则的操作视为不安全，必须拒绝或隔离。

每项验证必须可执行、可记录、可复现。验证失败时记录原因和修复。

1. 查询分层：simple（<1s）→ graph（<2s）→ full（~30s）→ bridge（<1s）
2. 环境隔离：execute_code → venv Python 3.11（逻辑处理）；terminal → 系统 Python 3.12（AKNE）
3. 语义增强：jieba 分词 + 5 级评分 + TF-IDF 全文检索 + 融合评分
4. MEMORY 入口：在 MEMORY.md 中记录入口路径和关键统计
5. 完整性保证：source→content_summary→向量 三线并行，缺一不可

详见 kg-bridge/SKILL.md 获取完整方法论。

Synthos Akne Bridge---

示例 · EXAMPLES

1. 诊断后连接孤立论文（先诊后治，SYNT-001/006）→ 输入 akne-query.sh bridge 报告 N 个 orphans；在 graph.json 为孤立论文添加 paper_source_domain 边（如 BPPV/眩晕类 → "BPPV" 分类），并显式创建 source_category/category_paper 逆向边（SYNT-002，注意 source_category_membership 方向为 category→source）→ 验证：重跑 akne-query.sh bridge 输出 orphans=0 且 source→category→paper 双向路径 YES。
2. 源节点内容注入与向量化补齐（三线并行，SYNT-003/007）→ 输入未在 vectors.db 的 source 节点；读取文件前 3KB 提取 content_summary/content_hash/h1/h2 注入节点 metadata（Step 9），再向 vectors.db 写入对应向量（Step 10，走系统 Python 3.12，SYNT-004）→ 验证：vectors.db 记录数 = source 节点数（1145/1145 已向量化），akne-query.sh stats 的 vectors count 与 graph.json source 数一致。
3. 多词英文查询兜底（陷阱 8）→ 输入 "eye tracking methodology"；QueryEngine 词袋匹配 _graph_search 无效时，改用 akne-query.sh full 模式（jieba 分词 + 多 token 子串匹配，阈值≥2）并配合图搜索/向量搜索 → 验证：full 模式返回 entity + neighbors + QueryEngine results + tokens 四类结果，非空；多词查询未走 4 值解包（find_related/in_edges 按 3 元组处理，陷阱 2/3）。