将 RAGRAF 接入 SagaAI

SagaAI 平台

开放的 AI 员工团队平台：聊天助手、自治协调器、知识库（RAG）与内置开发智能体 DevAgent — 在同一个 Web 界面（Streamlit）中，运行在自己的电脑或服务器上。MIT 许可；1.x 线保持公共 API、界面与数据格式向后兼容。界面提供俄文、英文与中文。本指南的全部事实已对照 TVD2100/sagaai-platform 仓库代码核实（v1.13.1）。

安装与启动

平台是普通的 Python 应用：依赖来自 requirements.txt（streamlit、requests、sqlalchemy、cryptography；可选文档解析器与 SSH 用的 paramiko），以 streamlit run app.py 启动。若命令找不到 streamlit — python -m streamlit run app.py。启动后在「设置」页配置各服务的 API 密钥。

git clone https://github.com/TVD2100/sagaai-platform SagaAI
cd SagaAI
pip install -r requirements.txt
streamlit run app.py        # → http://localhost:8501

RAGRAF 如何接入

为什么这样可行

run_code 是平台的「万能备用出口」：安装包、执行 shell 命令与脚本、任何没有专用工具的操作。RAGRAF CLI（tools/ragraf.py）是普通 Python 脚本：智能体像在任何外壳中一样调用它，并自己阅读响应文本 — 无需解释 JSON-RPC 模式。ragraf-core 技能规定顺序：先 ensure，然后用索引操作代替读文件。

RAGRAF 不替代也不冲突于 SagaAI 内置知识库：平台知识库检索文档（bm25/vector/hybrid），RAGRAF 是代码事实图谱（符号、关系、修订、索引新鲜度、写入控制）。员工可以两者并用：文档走 rag_search，代码走 RAGRAF CLI。

接入 — 四个步骤

1. 1安装 RAGRAF 并构建语料RAGRAF 标准安装（install.ps1 或 pip -e .），然后对项目目录执行 ensure。一个语料供全体员工使用：索引对智能体只读，多个对话与协调器可同时工作。
2. 2把 ragraf-core 技能装入技能库技能库页面 → 从 GitHub URL、ZIP 包或本地文件夹安装（数据目录中的 skills/skills.json 登记；限额：单包 200 MB、5000 个文件、单文件 50 MB，解包受 path traversal 防护）。第三方技能获得 developer=unknown、adapted=False，在适配完成前不会进入系统提示词的 Available skills 块：「适配」按钮把任务交给 DevAgent（Skill Developer），完成后调用 mark_skill_adapted。
3. 3把规程写入指令将通用 AGENTS.md 片段（「集成」页）加入协调器指令（指令跨重启保留）或项目的 AGENT.md — DevAgent 维护该文件并在工作目录中读取。「先问索引 → 检查信封 → 任何写入前 write_check」的顺序是强制的：没有规程时智能体会退回 search_in_files，这在 RAGRAF 调用统计中立即可见。
4. 4在对话中以调用验证请员工经 run_code 执行：catalog（预期为语料清单），然后 ensure <目录>（预期 status: actual）。智能体用 get_skill_file 读取技能文件 — 工作区工具（read_file、verify_file）会拒绝项目外路径：「Path escapes project root」。

# инструменты агента (run_code) вызывают CLI RAGRAF как обычную команду:
python <repo>\tools\ragraf.py catalog
python <repo>\tools\ragraf.py ensure <каталог проекта>
python <repo>\tools\ragraf.py -p <repo>\config\<корпус>.yaml query symbol --name <имя>
python <repo>\tools\ragraf.py -p <repo>\config\<корпус>.yaml check
python <repo>\tools\ragraf.py -p <repo>\config\<корпус>.yaml usage --agent saga-worker

平台安全

已在 v1.13.1 代码中核实 — 这些机制决定智能体将如何与 RAGRAF 协作：

• run_code 在隔离子进程中执行任意代码（超时 300 秒，run_test — 180 秒）；含危险模式（破坏性命令、系统修改、网络操作）的代码在用户于 UI 明确确认前被阻止。
• path traversal 防护：工具不越出工作文件夹；活动文件夹绑定到对话并在重新打开时恢复。
• 不可信数据被标记（结果净化、[DATA_FROM_WEB_SEARCH] 标签），启发式 prompt-injection 防护。
• API 密钥安全存储（或经环境变量设置且不写入数据库）；TLS 校验默认开启；密钥不在界面中显示。
• DevAgent 的修改有版本管理：文件备份、项目快照与完整回滚 — 智能体的行为可逆。

遥测

每次 CLI 调用都带 --agent <员工名>（saga-worker、saga-reviewer 等）：usage_call 会在共用 kind=external 下按智能体拆分调用画像。健康画像的特征是 symbol/search/write_check 占主导、整读文件为零。与平台「统计」页（按期间、供应商与模型的 token 消耗）交叉核对：导航上的节省在两个指标中都可见。

MCP 展望

若平台将来加入 MCP 客户端，RAGRAF 契约不变：stdio 服务器、JSON-RPC、24 个 ragraf_* 工具。届时只需注册启动 — 配置见下。--project 可省略：语料经开发项目登记簿按工作目录解析，切换到其他项目用 ragraf_use_project 工具。

{
  "mcpServers": {
    "ragraf": {
      "command": "python",
      "args": [
        "<repo>/tools/ragraf-mcp.py",
        "--agent", "saga-worker",
        "--agent-kind", "external"
      ]
    }
  }
}

平台事实已对照 github.com/TVD2100/sagaai-platform 代码核实（v1.13.1，MIT）：MCP 客户端检索、工具目录（dev_agent/tool_executor.py、universal_agent.py）、技能库（core/skills_library.py）、确认规则（core/dangerous.py）、README 与 AGENT.md。RAGRAF × SagaAI 的对接按平台机制描述；未进行真实会话实测 — 与 AutoClaw 及 DeepSeek Harness 不同。