rka (Infinitywings)

研究知识代理（RKA）


用于人工智能辅助调查的持久研究记忆。

RKA为你的研究项目提供了一个在两次会议之间不会忘记的大脑。它将每一个发现、决策、假设和文献参考都存储在一个具有完整来源链的结构化知识库中。大脑（克劳德）处理所有的知识丰富——不需要本地法学硕士学位。

RKA architecture and operational mechanism

A. 三个角色-- 研究员 （框架和批准）， 脑 （Claude Desktop综合文献并提出结构化选项）， 执行者 （Claude Code，实现有界任务）——共享一个类型化的、来源感知的知识库。四个控制属性锚定了架构：可追溯性、可逆性、可见的分歧、人类认可的承诺。 B 一个操作周期：研究人员制定目标；大脑重申意图（确认简报），检索上下文，并提出结构化选项；研究人员批准了一项决定；向执行人派遣特派团；执行人实施并报告；大脑整合结果并打开下一个决策周期。

 Month 1                    Month 3                    Month 6
 ┌──────────┐              ┌──────────┐              ┌──────────┐
 │ "We found │              │ "Based on │              │ "We can   │
 │  that..." │              │  3 months │              │  trace    │
 │           │   ┌─────┐   │  of evi-  │   ┌─────┐   │  every    │
 │ (lost     │──▶│ RKA │──▶│  dence..."│──▶│ RKA │──▶│  decision │
 │  next     │   └─────┘   │           │   └─────┘   │  back to  │
 │  session) │              │ (all here)│              │  its why" │
 └──────────┘              └──────────┘              └──────────┘
  Without RKA               With RKA                  With RKA v2
  Findings vanish            Everything persists        Knowledge self-organizes

专为北卡罗来纳大学夏洛特分校的CS/IoT/CPS安全研究而设计。

纸张

描述RKA架构、设计原则和评估的工作草案以PDF格式提供： RKA-paper.pdf — *框架是人：人工智能辅助研究的研究者-大脑-执行者架构*.

上图为草案中的图1；它提供了架构的概览（面板a）和一个操作决策周期（面板B）。本自述的其余部分是实用的、动手操作的伴侣：设置、CLI、MCP工具、RESTneneneba API和web仪表板。关于概念论证和评估，请阅读草案。

______________________________________________________________________

运作原理

三个参与者通过共享知识库进行协作：

graph LR
    PI["🧑‍🔬 PI
Human researcher"]
    Brain["🧠 Brain
Claude Desktop"]
    Executor["⚡ Executor
Claude Code"]
    RKA["📚 RKA
Shared knowledge base"]

    PI -->|supervises| Brain
    PI -->|supervises| Executor
    Brain -->|"strategy, decisions"| RKA
    Executor -->|"findings, reports"| RKA
    RKA -->|"context, evidence"| Brain
    RKA -->|"missions, guidance"| Executor

    style RKA fill:#E1F5EE,stroke:#0F6E56,color:#04342C
    style Brain fill:#EEEDFE,stroke:#534AB7,color:#26215C
    style Executor fill:#E6F1FB,stroke:#185FA5,color:#042C53
    style PI fill:#F1EFE8,stroke:#5F5E5A,color:#2C2C2A

• 脑 （克劳德桌面）——战略层。解释研究结果，确定研究方向，审查证据集群，解决矛盾。
• 执行者 （Claude Code）——实现层。运行实验、编写代码、收集数据。接收任务，提交报告，在被阻止时设置检查站。
• 圆周率 （人类研究人员）——监督两者，解决升级问题，提供领域专业知识。
• 俄罗斯联邦航天局 --共享的记忆。存储所有内容，为需要它的人提供上下文。维护清单检测来源缺口，供大脑修复。

______________________________________________________________________

知识管道

原始观察不会保持原始状态。在维护过程中，大脑将日记条目提炼为结构化知识：

graph TD
    Entry["📝 Journal entries
note · log · directive"]
    Claims["🔍 Claims
hypothesis · evidence · method
result · observation · assumption"]
    Clusters["🗂️ Evidence clusters
Grouped claims with
Brain-written synthesis"]
    Map["🗺️ Research map
Research questions →
clusters → claims"]

    Entry -->|"Brain extracts"| Claims
    Claims -->|"Brain clusters"| Clusters
    Clusters -->|"Brain synthesizes"| Map

    style Entry fill:#E6F1FB,stroke:#185FA5,color:#042C53
    style Claims fill:#EEEDFE,stroke:#534AB7,color:#26215C
    style Clusters fill:#FAEEDA,stroke:#854F0B,color:#412402
    style Map fill:#E1F5EE,stroke:#0F6E56,color:#04342C

每个声明都通过字符偏移链接回其源条目。每个集群都与其组成的主张相关联。整个来源链总是可以穿越的。

______________________________________________________________________

来源链

RKA中的每个实体都知道它为什么存在。类型化的交叉引用形成了一个完整的推理链：

graph LR
    Lit["📄 Literature
MQTT benchmarks"]
    Dec1["🔀 Decision
Test broker limits"]
    Mis["📋 Mission
Stress test at scale"]
    Entry["📝 Finding
12% packet loss"]
    Claim["💡 Claim
Threshold at 400"]
    Dec2["🔀 Decision
Implement sharding"]

    Lit -->|informed| Dec1
    Dec1 -->|motivated| Mis
    Mis -->|produced| Entry
    Entry -->|derived| Claim
    Claim -->|justified| Dec2

    style Lit fill:#F1EFE8,stroke:#5F5E5A,color:#2C2C2A
    style Dec1 fill:#EEEDFE,stroke:#534AB7,color:#26215C
    style Mis fill:#E6F1FB,stroke:#185FA5,color:#042C53
    style Entry fill:#E1F5EE,stroke:#0F6E56,color:#04342C
    style Claim fill:#FAEEDA,stroke:#854F0B,color:#412402
    style Dec2 fill:#EEEDFE,stroke:#534AB7,color:#26215C

12种类型的链接： informed_by · justified_by · motivated · produced · cites · references · supports · contradicts · supersedes · resolved_as · derived_from · builds_on

______________________________________________________________________

你可以用RKA做什么

记录并整理：

Brain:    rka_add_note("12% packet loss above 400 connections", type="note")
          rka_add_decision("Use horizontal sharding", related_journal=["jrn_..."])
          rka_create_mission("Test sharding", motivated_by_decision="dec_...")

Executor: rka_add_note("Ran 500-connection stress test", type="log")
          rka_submit_report(mission_id, findings="Sharding reduced loss to 2%")
          rka_submit_checkpoint("Need PI input on replication factor")

导航和搜索：

rka_get_research_map()         → Three-level view: RQs → clusters → claims
rka_trace_provenance(id)       → Literature → decision → mission → finding → claim
rka_get_review_queue()         → Items flagged for Brain's deep reasoning
rka_search("MQTT scalability") → Entries, decisions, literature, claims
rka_get_context(topic="...")   → Importance-ranked context package
rka_multi_hop_retrieval(query="...")  → Query-anchored ranked subgraph

______________________________________________________________________

主要特点

______________________________________________________________________

目录

• 纸张
• 建筑
• 关键概念
• 安装
• 快速开始
• 技能插件
• 多项目支持
• CLI参考
• 配置
• MCP工具参考
• REST API参考
• Web仪表板
• 数据模型
• 搜索和上下文引擎
• 知识丰富
• 发展
• 构建阶段

______________________________________________________________________

建筑

大脑/执行者模型

RKA实现了三方合作：

graph TD
    subgraph Clients
        CD["Claude Desktop
Brain — MCP stdio"]
        CC["Claude Code
Executor — MCP stdio"]
        WEB["Web Dashboard
localhost:9712"]
    end

    subgraph "RKA Server"
        MCP["MCP Server — 75+ tools"]
        API["REST API — FastAPI"]
        SVC["Service Layer — shared logic"]
        DB["SQLite + FTS5 + sqlite-vec"]
        WORKER["Background Worker
Embeddings only"]
    end

    CD --> MCP
    CC --> MCP
    WEB --> API
    MCP --> SVC
    API --> SVC
    SVC --> DB
    WORKER --> DB

• 脑 （Claude Desktop）：战略决策——研究什么，采取哪个方向，如何解释研究结果，以及要解决哪些审查队列项目。通过MCP工具进行通信。
• 执行者 （Claude Code）：实现——运行实验、编写代码、收集数据。接收任务、提交报告、设置检查站。
• 圆周率 （人）：监督进度，解决检查点，提供领域专业知识。

四层设计

1. MCP工具层 --薄型适配器暴露 rka_* stdio上的工具。保持轻量级的每个会话状态，用于输出压缩和摘要，但没有核心业务逻辑。
2. REST API层 --FastAPI端点位于 /api.相同的薄型适配器模式，委托给服务。
3. 服务层 --所有的商业逻辑。CRUD操作、自动富集、事件排放、上下文准备、蒸馏管道。MCP和REST共享相同。
4. 基础设施层 --数据库（SQLite+FTS5+SQLite-vec）、嵌入（FastEmbed）、文件存储。可选的LiteLLM网关供电 rka_ask / rka_generate_summary 仅当用户连接cloud-LLM API密钥时。

三过程模型

RKA以三个进程运行：

REST API和后台工作程序共享相同的SQLite数据库文件和服务层代码。后台工作程序处理嵌入生成，以便MCP和REST调用立即返回。知识丰富（索赔提取、聚类综合、来源链接）由大脑在维护会话期间处理，不需要本地LLM。

MCP服务器通过stdio（stdin/stdout）进行通信，并将所有调用代理到位于的REST API RKA_API_URL （默认值： http://localhost:9712).

______________________________________________________________________

关键概念

实体类型

日记账条目类型

v2.0将日记账分录类型简化为三个规范类别：

v1的遗留类型(finding, insight, idea, observation, hypothesis, methodology, pi_instruction, exploration, summary)被接受为输入，并自动映射到最接近的v2.0类型。

渐进式蒸馏管道

蒸馏管道是由大脑驱动的。大脑在维护过程中提取索赔、汇总证据并撰写综合报告：

Journal Entries (note / log / directive)
    |
    | [Brain: claim extraction during maintenance]
    v
Claims (clm_)
  hypothesis | evidence | method | result | observation | assumption
    |
    | [Brain: clustering and synthesis]
    v
Evidence Clusters (ecl_)
  Brain-written synthesis of related claims
    |
    | [Brain: research question assignment]
    v
Research Map
  Research Questions --> Clusters --> Claims

rka_get_pending_maintenance() 检测需要蒸馏的条目和其他来源缺口。大脑在会话开始时处理这些信息 rka_extract_claims, rka_create_cluster，以及 rka_assign_claims_to_cluster.

基于ULID的ID

所有实体都使用类型前缀的ULID（例如。， dec_01HXYZ...).ULID是全局唯一的，可按创建时间排序，前缀使读取日志或数据库行时的调试更容易。

任务生命周期

Brain creates mission --> Executor picks up (active) --> Work proceeds
    --> Checkpoint raised if blocked --> Brain/PI resolves
    --> Executor submits report --> Brain reviews
    --> Mission marked complete/partial/blocked

审核队列

审查队列收集了需要大脑关注的项目：低置信度声明、声明之间的矛盾以及需要叙事综合的集群。大脑可以批准、拒绝、合并或覆盖每个项目。

决策替代

当一项决定被新证据取代时，RKA会将旧决定标记为被取代，并将其与替代决定联系起来，并可选择对引用旧决定的索赔重新进行蒸馏。这保留了完整的审计跟踪，同时保持了活跃的研究地图的最新状态。

来源链

每个实体都可以通过键入链接到其源 link_ 交叉引用。常见的链接类型包括 derived_from, contradicts, supports, supersedes，以及 cites这些边构成了知识图谱页面中可见的出处图。

上下文排名（v2.4+）

上下文引擎返回一个单排名的条目列表——没有令牌预算截断，没有温度波动。排序是确定的，在SQL时间计算：

1. journal.importance — critical > high > normal > low > archived.PI来源的条目在其重要性范围内略有提升。
2. entity_links 中心性 --入站边缘+出站边缘之和；高度连接的节点首先在重要性带内出现。
3. created_at DESC --新事物是决定性因素。

早期的RKA版本（≤v2.3）在日阈值上使用热/暖/冷温度跳跃加上令牌预算。这两个都在v2.4中被删除了（参见 dec_01KQQPD6Y6B362T3K08368BDMP)：日阈值系统地排除了较旧的相关内容，前沿模型上下文窗口使簿记员强加的预算变得没有必要。

对于多跳问题，答案取决于连接的实体——从种子开始的多跳，请参见 rka_multi_hop_retrieval --它使用具有每个关系权重的类型化边缘词汇表返回一个查询锚定的相关性排名子图。

______________________________________________________________________

安装

选项A:Docker（推荐）

先决条件：

git clone https://github.com/infinitywings/rka.git
cd rka
docker compose up -d

就是这样。打开 http://localhost:9712 在您的浏览器中。

连接克劳德桌面和克劳德代码（MCP）：

两个客户都通过同一个小 rka stdio二进制文件。在Docker之外安装一次，这样Claude应用程序就可以直接启动它：

UV_CACHE_DIR=/tmp/uv-cache uv tool install --force .

双星降落在 ~/.local/bin/rka 船舶角色技能提示(brain_skill, executor_skill, pi_skill)Claude可以加载以获取完整的工作流程指导。

然后在每个客户端的MCP配置中注册它——完整的分步设置在 快速入门§2 下面，包括推荐 env.RKA_PROJECT 块（v2.3.2+）固定您的主项目，以便新会话正确解析，而不是默默地写入 proj_default.

无需法学硕士学位。 大脑（克劳德桌面）在正常会话期间处理所有知识丰富——索赔提取、聚类综合、矛盾解决。除了Docker和MCP二进制文件之外，没有什么可配置的。

MCP二进制文件是无状态的-它代理对Docker容器的REST API的所有调用 RKA_API_URL.

代码更改后，始终重新安装MCP二进制文件：

uv tool uninstall rka
rm -rf /tmp/uv-cache
UV_CACHE_DIR=/tmp/uv-cache uv tool install --force --reinstall .

平原 uv tool install --force . 使用缓存的控制盘，可能无法获取更改。

选项B：来源（开发）

先决条件：

• Python 3.11+
• Node.js 18+（用于web仪表板）

git clone https://github.com/infinitywings/rka.git
cd rka

# Create venv and install
python -m venv .venv
source .venv/bin/activate
pip install -e ".[academic,workspace]"

# Build web UI
cd web && npm install && npm run build && cd ..

# Start the server (REST API + background worker)
rka serve

连接克劳德桌面/代码（MCP）：

# Install the MCP binary via uv tool (avoids macOS sandbox issues)
UV_CACHE_DIR=/tmp/uv-cache uv tool install --force .

在每个Claude客户中注册 快速入门§2 下面——推荐的JSON包括 env.RKA_PROJECT 将您的主要项目固定在会话之间的块。

______________________________________________________________________

快速开始

1.启动服务器

# Docker (recommended)
docker compose up -d

# Or from source
rka serve

web仪表板位于 http://localhost:9712.API文件位于 http://localhost:9712/docs.

2.连接克劳德桌面和克劳德代码

RKA通过MCP（模型上下文协议）到达两个Claude应用程序。你安装一个小的二进制文件，并在每个应用程序中注册它。

为什么是两个APP？ 大脑（战略、综合）运行 克劳德桌面版执行器（实现、编码）在 克劳德代码。它们共享相同的RKA知识库，因此上下文在会话和角色之间得以保留。 ⚠️ MCP在上不可用 claude.ai 网站——你需要原生的Claude Desktop应用程序和Claude Code扩展/CLI。

步骤2a——安装RKA MCP二进制文件 （一次性，在Docker之外运行，因此Claude应用程序可以直接启动它）：

UV_CACHE_DIR=/tmp/uv-cache uv tool install --force .

这个地方 rka 在 ~/.local/bin/rka.验证 ~/.local/bin/rka --version.

步骤2b——配置克劳德桌面（大脑）。 打开克劳德桌面→ 设置→ 开发者→ 编辑配置，或直接编辑文件：

添加（或合并）--替换 ` 使用您的实际用户名；路径必须是 **绝对的**，不 ~.Set RKA_PROJECT` 添加到主项目的id，以便每个新会话都在该项目中开始（请参阅下面的“固定默认项目”）：

{
  "mcpServers": {
    "rka": {
      "command": "/Users//.local/bin/rka",
      "args": ["mcp"],
      "env": {
        "RKA_PROJECT": "prj_01ABC..."
      }
    }
  }
}

保存和 完全退出克劳德桌面 （macOS上的Cmd+Q/右键单击托盘图标→ 在Windows上退出），然后重新打开。RKA工具现在可以在任何新的对话中使用。

步骤2c——配置克劳德代码（执行器）。 通过VS Code扩展 MCP服务器 UI，或通过创建 .claude/mcp.json 在您的repo根目录中：

{
  "mcpServers": {
    "rka": {
      "command": "/Users//.local/bin/rka",
      "args": ["mcp"],
      "env": {
        "RKA_PROJECT": "prj_01ABC..."
      }
    }
  }
}

重新加载VS代码窗口： Cmd+Shift+P （macOS）/ Ctrl+Shift+P （Windows/Linux）→ “开发人员：重新加载窗口”.

如果您使用Claude Code CLI而不是VS Code扩展，则会使用相同的配置 ~/.claude/settings.json 在...之下 mcpServers.

固定默认项目（推荐）。 设置 RKA_PROJECT= 在MCP中 env 块（或API进程的外壳环境）使两个MCP _session.project_id 以及在每个新会话上对该项目的API侧回退解析。没有它，新的MCP子流程默认为 proj_default 如果大脑和执行者都不召唤，它就会默默地写下来 rka_set_project() 第一。要查找您的项目id，请运行 rka_list_projects() 在任何会话中一次，或检查 http://localhost:9712 在仪表板URL栏中。

步骤2d——验证。 在每个应用程序中，询问：

“列出我的RKA项目”

每个克劳德都应该打电话 rka_list_projects() 并返回一个列表（新安装时为空）。

步骤2e——加载角色技能 （建议每届新会议）。主控程序 提示 船用二进制；他们教克劳德会话开始协议、归因规则和出处规则。

在Claude Desktop中，问： *“发挥你的脑力。”* 在克劳德代码中，问： *“发挥你的执行技能。”* 或者通过以下方式明确调用 / 斜线菜单→ rka → 脑技能 / 执行者技能.

有关包括故障排除在内的完整设置演练，请参阅 用法\_ GIDE.md.

MCP传输模式

这 rka mcp 二进制支持两种传输模式：

• 标准（默认） — rka mcp 没有争论。Claude Desktop和Claude Code将二进制文件作为子进程生成，并通过stdin/stdout进行通信。这是上面安装说明配置的模式。
• 流式HTTP（选择加入，v2.2+） — rka mcp --transport http --port 9713 在上运行服务器 http://127.0.0.1:9713/mcp。可用于远程访问、多客户端场景或基于mitmproxy的协议调试。通过启用 --transport http 旗帜或 RKA_MCP_TRANSPORT=http envvar.身份验证尚未实现——在未来的任务添加OAuth 2.1之前，仅将HTTP模式视为dev/internal。

不同运输工具的刀具表面相同。Docker的默认命令仍然启动stdio，没有任何变化。

3.生成入职指令（可选）

跑 rka_generate_claude_md 从克劳德桌面或点击 GET /api/generate-claude-md?role=executor 生成自定义 CLAUDE.md 对于当前的项目和角色。这为新的会议提供了关于项目目标、惯例和积极工作的即时背景。

4.尝试示例项目（可选）

RKA附带了一个示例知识包—— rka_development 该项目曾用于自行构建RKA。导入它以探索一个包含80个日记条目、22个决策、10个文献参考、3个任务和279个交叉引用的完整知识库：

curl -X POST http://localhost:9712/api/projects/import \
  -F "file=@examples/rka_development.rka-pack.zip"

或者使用网络仪表板：打开 仪表板 → 导入包 → 选择 examples/rka_development.rka-pack.zip.

导入后，切换到侧栏中的项目，浏览决策树、知识图和研究图，看看真实项目的外观。

5.开始研究

使用web UI进行浏览和问答，或使用Claude Desktop/Code和MCP工具进行完整的Brain/Executor工作流程。仪表板允许您选择活动项目、浏览研究地图、管理审查队列，并将活动项目导出为知识包。

______________________________________________________________________

技能插件——角色特定工作流指南

RKA附带了针对特定角色的技能指南，教克劳德如何有效地使用这些工具。这些与MCP二进制文件打包在一起，并作为MCP提示提供。

可用技能

技能是如何加载的

MCP服务器指令告诉Claude在会话开始时加载适当的技能提示。Claude桌面加载 brain_skill；克劳德代码加载 executor_skillPI可以读取 skills/pi/SKILL.md 直接。

关键工作流程

大脑会话开始：

1. rka_set_project() → rka_get_changelog(since="yesterday") → rka_get_research_map()
2. 安静地处理多达10个维护项目
3. 问候用户

执行者任务拾取：

1. rka_get_mission() → read motivated_by_decision → 阅读上下文链接
2. 提交背景简报（计划摘要、假设、风险）
3. 开始前等待Brain批准

验证门（通过/不通过检查点）：

1. rka_create_gate(mission_id, gate_type, deliverables, pass_criteria)
2. 工作继续进行→ 已创建可交付成果
3. rka_evaluate_gate(gate_id, verdict, notes, assumption_status)
4. 如果假设无效→ 陈旧性通过知识图谱级联

______________________________________________________________________

多项目支持

多项目管理可通过MCP和REST实现：

• MCP工具: rka_list_projects 列出所有项目。 rka_set_project 按名称或ID切换活动项目。 rka_create_project 在不离开MCP会话的情况下创建新项目。
• REST API和web仪表板：了解项目。仪表板在本地存储活动项目并注入 X-RKA-Project 自动处理API请求。
• 知识包：使用导出活动项目 GET /api/projects/export.导入以前导出的包 POST /api/projects/import.Import创建一个单独的项目，重新映射项目范围的实体ID，并重写内部引用。
• 工作区引导：CLI引导命令针对当前数据库/默认项目。对于多项目数据库中特定于项目的引导，请使用 POST /api/workspace/scan 和 POST /api/workspace/ingest 随着 X-RKA-Project.

______________________________________________________________________

CLI参考

rka init

初始化一个新的RKA工作区并为默认项目设置种子。

rka init "IoT Security Analysis" --description "Systematic review of CPS vulnerabilities"

rka serve

启动REST API+web仪表板服务器和后台工作程序。

rka serve --port 9712 --reload

rka mcp

启动Claude Desktop或Claude Code的MCP stdio服务器。MCP服务器是无状态的-它代理对位于的REST API的所有调用 RKA_API_URL.

rka mcp

无选项--根据MCP协议通过stdin/stdout进行通信。

rka status

显示当前项目状态。

rka status

显示：项目名称、当前阶段、活动任务、打开的检查点、实体计数。

rka backup

备份SQLite数据库。

rka backup --output ./backups/rka-backup.db

rka migrate

运行挂起的数据库迁移。

rka migrate

rka bootstrap scan

扫描工作区文件夹并对文件进行分类，以便纳入知识库。

rka bootstrap scan ~/research/project_files --no-llm

rka bootstrap ingest

扫描工作区文件夹并将其摄取到知识库中。

rka bootstrap ingest ~/research/project_files --phase phase_1 --tags bootstrap -y

这些CLI引导命令针对当前数据库/默认项目。在多项目部署中，使用 POST /api/workspace/scan 和 POST /api/workspace/ingest 随着 X-RKA-Project 引导一个特定的项目。

______________________________________________________________________

配置

所有设置都使用环境变量 RKA_ 前缀。把它们放在一个 .env 项目目录中的文件。

核心设置

嵌入设置

上下文引擎设置

v2.4上下文引擎没有可调的环境变量——排名是SQL时间重要性×中心性×新近性、确定性和簿记员。遗产 RKA_CONTEXT_HOT_DAYS, RKA_CONTEXT_WARM_DAYS，以及 RKA_CONTEXT_DEFAULT_MAX_TOKENS 在v2.4中删除了env变量（请参阅上面的“上下文排名”一节）。

______________________________________________________________________

MCP工具参考

所有工具都以前缀 rka_ 并可通过MCP stdio接口访问。MCP服务器在中定义 rka/mcp/server.py.

项目

备注

决策

文学

任务

检查站（升级）

研究地图（v2.0）

集群管理（v2.1）

查看队列（v2.0）

知识新鲜度（v2.1）

验证门（v2.1）

研究员经验（v2.1）

搜索和上下文

图

学术导入与丰富

工作区引导

会话

入职培训（v2.0）

出口

______________________________________________________________________

REST API参考

基本URL: http://localhost:9712/api

交互式API文档可在 http://localhost:9712/docs （Swagger用户界面）。

大多数实体端点都是项目范围的。通过 X-RKA-Project: 以特定项目为目标。如果省略，服务器将回退到 DEFAULT_PROJECT_ID，从 RKA_PROJECT 服务器启动时的环境变量（v2.3.2+） proj_default 如果未设置。通过导出来固定您的主项目 RKA_PROJECT= 在API过程的环境中（或在您的MCP中 env block——请参阅上面的“固定默认项目”）。

请求验证（v2.3.1+）

八个核心实体更新模型(DecisionUpdate, MissionUpdate, JournalEntryUpdate, LiteratureUpdate, ClaimUpdate, EvidenceClusterUpdate, TopicUpdate, ProjectStateUpdate)使用Pydantic extra="forbid".POST/PUT请求携带未在相应模型中声明的字段，现在返回 HTTP 422 而不是默默地剥去它们。在-2.3.1之前，该条是一个记录在案的bug(承诺 02d7348 引入约束）。任何在更新端点上将意外的422一分为二的人都应该在该提交处着陆。

MissionUpdate 之前比读取投影窄（3个声明字段）。现在它也接受 phase, context, acceptance_criteria, scope_boundaries, checkpoint_triggers, depends_on, parent_mission_id, motivated_by_decision，以及 tags.通过REST PUT写入这些字段现在将保持不变（并且 motivated_by_decision 写作也实现了相应的 motivated 实体链接）。 DecisionUpdate 类似地添加 assumptions.

注释（日记条目）

决策

文学

任务

检查点

索赔（v2.0）

证据集群（v2.0）

主题（v2.0）

研究地图（v2.0）

查看队列（v2.0）

研究员工具（v2.1）

知识新鲜度（v2.1）

搜索和上下文

项目和知识包

嵌入式配置（v2.4.0）

完整参考： docs/embedding_backends.md.

LLM路由（保留；v2.4.0未配置）

这 /api/llm/* 路线和 rka_ask / rka_generate_summary MCP工具仍保留在代码库中，但不再出现在 web UI。v2.4.0根据PI指令删除了LLM配置旋钮 jrn_01KRNZBS50K250HHHHEC58E4GC；未来的版本将重新连接LLM 通过编排器的Claude Code SDK路径实现功能。

笔记本（问答+总结）

知识图谱

文物和数字

事件和标签

审核日志

工作区引导

学术导入

入职培训（v2.0）

______________________________________________________________________

Web仪表板

web仪表板提供了一个可视化界面，用于在不使用MCP工具或原始API调用的情况下检查项目状态。它具有项目意识，包括项目选择和知识包导出/导入控制。

构建仪表板

cd web
npm install
npm run build

构建输出将转到 web/dist/.何时 rka serve 启动时，它会自动检测并提供此目录 http://localhost:9712.Docker在以下过程中自动构建仪表板 docker build.

发展模式

# Terminal 1: API server + background worker
rka serve

# Terminal 2: Vite dev server with HMR
cd web
npm run dev

Vite-dev服务器运行在 http://localhost:5173 并将API调用代理到 :9712.

页面

技术栈

• React 19+TypeScript 5.9与Vite 7
• 顺风CSS 4+shadcn/ui（v5）
• TanStack查询5服务器状态
• @xyflow/react用于决策树、知识图和研究图可视化

______________________________________________________________________

数据模型

SQLite架构

所有数据都存在于一个单一的 rka.db 文件。该架构包括：

• 核心表: projects, project_states, decisions, literature, journal_entries, missions, checkpoints, events, artifacts
• v2.0表格: claims, claim_edges, evidence_clusters, topics, review_queue, entity_links, jobs
• 连接表: tags --用于跨实体标记查询的实体类型/实体id/标记三元组
• JSON列: options （决定）， authors （文学）， tasks （任务）， key_findings （文学）
• FTS5虚拟表：内容字段上的全文搜索索引
• sqlite-vec虚拟表：用于语义搜索的向量嵌入（可选）

ID格式

所有ID都遵循以下模式： {type_prefix}_{ulid}

事件溯源

每次写入操作都会向发出一个事件 events 桌子上有：

• event_type --创建、更新、解决、提炼、取代等。
• entity_type + entity_id --发生了什么变化
• actor --谁做出了改变（大脑、执行者、pi、llm、webui、系统）
• caused_by --触发事件的因果链
• metadata --带有更改详细信息的JSON blob

有效的参与者值： brain | executor | pi | llm | web_ui | system

这将创建完整的审计跟踪，并在时间线页面中实现因果链可视化。

______________________________________________________________________

搜索和上下文引擎

混合搜索

RKA使用交互秩融合（RRF）结合了两种搜索策略：

1. FTS5（关键字搜索） --SQLite内置的全文搜索功能。重量：0.3
2. sqlite-vec（语义搜索） --使用嵌入的向量相似性。重量：0.7

混合方法可以捕获精确匹配和语义相关的内容。如果sqlite-vec不可用，系统将仅回退到FTS5。

嵌入

• 模型: nomic-ai/nomic-embed-text-v1.5 （768尺寸）
• 运行时：FastEmbed（ONNX，完全本地，无API调用）
• 存储：sqlite-vec虚拟表

当创建或更新条目时，嵌入由后台工作器异步生成。

上下文引擎（v2.4）

上下文引擎为给定主题构建一个重要性排名包。管道为：

1. 搜索 --混合FTS5+矢量搜索为候选池播种。
2. 中心性注释 --每位候选人获得 entity_links 学位计数。
3. SQL时间排名 — journal.importance （案例4..0）×中心性× created_at DESC，PI来源的入口有+0.5升程。
4. 可选叙述 --通行证 depth="detailed" 要求LLM（如果已配置）在排名列表上综合连贯的叙述。

没有代币预算截断；返回完整的排名列表。对于多跳问题，如果答案取决于连接的实体——从种子开始的多跳，请使用 rka_multi_hop_retrieval 相反。

请求上下文包：

curl -X POST http://localhost:9712/api/context \
  -H 'Content-Type: application/json' \
  -d '{"topic": "evaluation methodology"}'

______________________________________________________________________

知识丰富

脑驱动强化（v2.0+）

在正常会话期间，所有知识丰富都由大脑（克劳德桌面）处理。没有本地LLM，没有后台AI工作者，也没有要配置的LLM API密钥。后台工作者仅处理用于语义搜索的嵌入作业。

大脑在维护过程中会做什么：

• 从日记账分录中提取索赔
• 将相关主张分为证据组
• 为证据集群撰写综合叙述
• 解决索赔之间的矛盾
• 为研究问题分配证据集群
• 修复缺失的来源链接

维护清单： rka_get_pending_maintenance() 使用纯SQL查询检测所有来源缺口。启动时，大脑每次会话最多处理10个项目。

审核队列

审查队列收集标记为Brain关注的项目：

• 需要验证的低置信度声明
• 索赔之间的矛盾
• 需要综合的证据集

大脑通过以下方式解析项目 rka_review_cluster, rka_review_claims，以及 rka_resolve_contradiction.

______________________________________________________________________

发展

运行测试

# Docker (recommended)
docker compose exec rka pytest

# Verbose output
docker compose exec rka pytest -v

测试套件涵盖数据库架构、CRUD操作、FTS5搜索、上下文引擎、LLM丰富、事件发射、多项目范围界定、知识包导入/导出、API端点、工作区引导、图形服务、回填服务、摘要/QA服务、蒸馏管道、声明、集群、主题、审查队列、研究地图和入职。

项目结构

rka/
+-- skills/                     # MCP skill prompts (packaged with binary)
|   +-- SKILL.md                # Router: detects role, directs to sub-skill
|   +-- brain/SKILL.md          # Brain workflow guide (~450 lines)
|   +-- executor/SKILL.md       # Executor workflow guide (~150 lines)
|   +-- pi/SKILL.md             # PI quick reference
+-- rka/                        # Python package
|   +-- cli.py                  # Click CLI (init, serve, mcp, status, backup, migrate, bootstrap)
|   +-- config.py               # Pydantic settings (RKAConfig)
|   +-- models/                 # Pydantic models for all entities
|   +-- services/               # Business logic (shared by MCP + REST)
|   |   +-- base.py             # BaseService with emit_event()
|   |   +-- project.py          # Project metadata + per-project status
|   |   +-- notes.py            # Journal entry CRUD + enrichment
|   |   +-- decisions.py        # Decision tree CRUD + superseding
|   |   +-- literature.py       # Literature CRUD
|   |   +-- missions.py         # Mission lifecycle
|   |   +-- checkpoints.py      # Checkpoint CRUD + resolution
|   |   +-- claims.py           # Claim extraction, CRUD, provenance
|   |   +-- clusters.py         # Evidence cluster CRUD + synthesis
|   |   +-- topics.py           # Hierarchical topic taxonomy
|   |   +-- research_map.py     # Three-level research map assembly
|   |   +-- review_queue.py     # Review queue CRUD + resolution
|   |   +-- onboarding.py       # CLAUDE.md generation
|   |   +-- worker.py           # Background worker + job queue
|   |   +-- search.py           # Hybrid FTS5 + vector search
|   |   +-- context.py          # Context engine (importance-ranked retrieval; v2.4)
|   |   +-- graph.py            # Entity relationship graph
|   |   +-- audit.py            # Audit log queries and counts
|   |   +-- academic.py         # BibTeX import, DOI enrichment, Mermaid export
|   |   +-- artifacts.py        # Artifact registration + figure extraction
|   |   +-- knowledge_pack.py   # Project export/import packs (categorized table registry)
|   |   +-- researcher_tools.py # Changelog, evidence assembly, cluster split/merge, paper processing, RQ lifecycle
|   |   +-- workspace.py        # Workspace bootstrap (scan, classify, ingest)
|   |   +-- jobs.py             # Job queue primitives
|   |   +-- summary.py          # Q&A + summary generation
|   +-- infra/                  # Infrastructure
|   |   +-- database.py         # SQLite + FTS5 + sqlite-vec
|   |   +-- llm.py              # LiteLLM + Instructor wrapper
|   |   +-- embeddings.py       # FastEmbed service
|   +-- mcp/                    # MCP server
|   |   +-- server.py           # FastMCP tool + prompt definitions (all rka_* tools)
|   +-- api/                    # FastAPI
|       +-- app.py              # Application factory + static serving
|       +-- deps.py             # Dependency injection
|       +-- routes/             # Route modules (one per entity type)
|           +-- notes.py
|           +-- decisions.py
|           +-- literature.py
|           +-- missions.py
|           +-- checkpoints.py
|           +-- claims.py
|           +-- clusters.py
|           +-- topics.py
|           +-- research_map.py
|           +-- review_queue.py
|           +-- onboarding.py
|           +-- search.py
|           +-- context.py
|           +-- graph.py
|           +-- audit.py
|           +-- academic.py
|           +-- artifacts.py
|           +-- workspace.py
|           +-- project.py
|           +-- llm.py
|           +-- summary.py
|           +-- researcher_tools.py  # Changelog, evidence assembly, split/merge, process paper, advance RQ, integrity
|           +-- events.py
|           +-- tags.py
+-- web/                        # React dashboard (Vite + TypeScript)
|   +-- src/
|   |   +-- api/                # Fetch client + TypeScript types
|   |   +-- hooks/              # TanStack Query hooks
|   |   +-- components/         # UI components (shadcn + layout + shared)
|   |   +-- pages/              # Page components (12 pages)
|   |   +-- lib/                # Utilities
|   +-- dist/                   # Production build (served by FastAPI)
+-- tests/                      # Pytest test suite
+-- pyproject.toml              # Python project config
+-- docker-compose.yml          # Docker Compose configuration
+-- Dockerfile                  # Docker image (builds web UI + installs Python package)
+-- .env                        # Project configuration

添加新实体类型

1. 在中创建Pydantic模型 rka/models/
2. 添加服务类扩展 BaseService 在 rka/services/
3. 在中添加路由模块 rka/api/routes/
4. 在中注册路线 rka/api/app.py
5. 在中添加MCP工具功能 rka/mcp/server.py
6. 在中添加架构DDL rka/infra/database.py
7. 在中添加TypeScript类型 web/src/api/types.ts
8. 在中添加TanStack查询挂钩 web/src/hooks/
9. 在中添加页面组件 web/src/pages/ 如有需要

______________________________________________________________________

构建阶段

______________________________________________________________________

许可证

私人研究工具。目前尚未在开源许可证下发布。