简单的Rag Writer
Simple Rag Writer是一个测试驱动的写作助手框架，它：
- 通过以下方式协调多个LLM提供商（OpenAI、OpenRouter、Gemini等）
litellm.
- 使用MCP服务器作为文档/参考检索层。
- 提供交互式规划REPL(
srw -c config.yaml plan)与
用于模型切换、知识浏览和上下文的斜线命令 注射。
- 从YAML执行声明性编写任务以进行批处理生成
(srw -c config.yaml run path/to/tasks/*.yaml).
- 使用注入的MCP上下文回放过去的计划回合(
srw -c config.yaml replay --log --turn).
该项目有意最小化：每个功能都由测试涵盖，MCP 交互被固定装置打断，避免了真正的网络调用，除非 明确要求。
安装
python -m venv .venv
source .venv/bin/activate
pip install -e .这将安装 srw，这只是一个薄薄的包裹 simple_rag_writer 包裹。您可以从存储库根目录运行 ./srw ... 或依靠垫片 添加 src/ 到 PYTHONPATH.
配置概览
CLI需要一个配置YAML文件来定义模型、提供者、MCP 服务器和日志/提示策略。至少，您必须提供默认型号 以及您计划使用的提供商/模型条目。
default_model: "openai:gpt-4.1-mini"
providers:
openai:
type: "openai"
api_key_env: "OPENAI_API_KEY"
model_defaults:
temperature: 0.3
models:
- id: "openai:gpt-4.1-mini"
provider: "openai"
model_name: "gpt-4.1-mini"
mcp_servers:
- id: "notes"
command: ["mcp-notes-server"]
mcp_prompt_policy:
default_mode: "raw_capped"
raw_capped:
max_items_per_reference: 3
max_chars_per_item: 800
max_total_chars: 8000
summary:
summarizer_model: "openai:gpt-4.1-mini"
max_items_per_reference: 5
summary_max_tokens: 512
logging:
planning:
enabled: true
dir: "logs"
include_mcp_events: true
mcp_inline: true关键配置部分：
providers：将提供程序名称映射到type,api_key，以及可选覆盖
(base_url, model_prefix等等）。
models：列表ModelConfig条目（id、提供者、模型名、可选
params, label, tags，以及 max_context_tokens).
model_defaults：在每次请求之前合并共享生成参数。mcp_servers：每台服务器都需要id,command（可执行文件+参数），以及
可选的 auto_startMCP客户端发出命令，执行 JSON-RPC握手，并通过缓存发现的工具 tools/list.
mcp_prompt_policy：控制检索方式NormalizedItems被转化
注射前。 raw_capped 修剪和截断，而 summary 使用一个 汇总器型号和每种类型提示。
logging.planning：允许规划成绩单、内联MCP部分，以及
输出位置。
添加MCP服务器
- 选择一个
id您将参考/use ...在REPL和
从 references 任务YAML中的条目。
- 确定启动MCP服务器的确切命令，并将其拆分为
argv样式列表。配置 必须 列出其中的每个参数 command.
- 在下面添加服务器
mcp_servers，可选择翻转auto_start到
false 如果您希望提前手动启动服务器。
示例(uv tool run arxiv-mcp-server --storage-path ...):
mcp_servers:
- id: "arxiv"
command:
- "uv"
- "tool"
- "run"
- "arxiv-mcp-server"
- "--storage-path"
- "/home/you/.cache/arxiv-papers"
auto_start: true保存配置后，您可以运行 srw -c config.yaml plan，使用 /sources 到 验证服务器是否已列出，然后调用 /use arxiv "query" 以获取数据。相同 arxiv id可以从自动任务YAML中引用 通过 references 条目。
MCP服务器
有关默认MCP服务器的文档，请参阅以下内容 config.yaml
模型
有关默认LLM模型的文档，请参阅以下内容 config.yaml
用法
srw 公开了三个高级命令。
规划模式(srw -c config.yaml plan)
交互式计划模式会启动一个REPL，记录历史、记录转弯和 使用可选的MCP上下文构建提示。Slash命令包括：
/models：列出已配置的型号，标记活动型号。/model：切换当前型号。/sources：显示配置的MCP服务器以及发现的工具名称和
描述。
/use "query" [limit]：调用MCP工具并显示结果。
您还可以提供键/值参数，如 query:"text" paper_id:"1234" 到 将多个参数传递给工具。
- 计划和任务提示现在包括
call_mcp_tool函数提示，因此
模型可以自行请求额外的MCP数据。该工具需要JSON server, tool，可选 params，REPL/runner将输出结果 自动回到对话中。
/inject：将选定的MCP项注入内部上下文
缓冲器。
/context：预览将添加到的累积MCP上下文
下一个提示。
/url [label]：获取一个URL，对其进行规范化，并使其可用于
注射。
/quit//q：退出计划模式。
repl维护一个历史窗口（默认5圈）并记录MCP注射 通过以下方式完成 PlanningLogWriter. /context 显示了组合块 你可以查看将要添加的内容。
自动化任务(srw -c config.yaml run tasks/*.yaml)
执行YAML定义的任务，描述要写什么以及引用什么 决心。每个任务都可以声明：
id,title,description：提示和日志中使用的元数据。context：可选大纲引用（TODO:大纲加载器）。model以（权力）否决config.default_model.model_params：每个任务参数覆盖。references：列表McpReference或UrlReference指定的条目
要获取的服务器/工具或URL。MCP参考可以设置 item_type 提示。
mcp_error_mode:"skip_with_warning"（默认）或"fail_task".output：生成的Markdown草稿的路径。
run_tasks_for_paths:
- 展开CLI上提供的glob模式。
- 加载每个任务并解析MCP/URL引用，规范有效载荷，以及
应用配置的提示策略。
- 使用引用构建最终提示并调用ModelRegistry。
- 将Markdown写入
output路径并通过Rich报告进度。
回放模式(srw -c config.yaml replay --log --turn )
重播通过以下方式重新补充计划回合：
- 解析Markdown日志头以获取配置/模型元数据。
- 重建历史（至
HISTORY_WINDOW)以及MCPmcp-yaml
块。
- 完全按照最初发送的方式重建提示（包括插入的提示）
上下文），以便您可以检查或重新运行它(--show-prompt, --run-model).
MCP集成
MCP服务器位于 AppConfig.mcp_servers。每个条目必须与 id 引用于 /sources, /use，以及任务引用。客户：
- 通过生成配置的命令
anyio/mcp.client.stdio. - 执行
initialize,tools/list，以及tools/callJSON-RPC
谈判。
- 从中提取文本/结构化有效载荷
CallToolResult并使其正常化
他们通过 normalize_payload 在迅速的政策之前。
工具发现填充 /sources 带有工具描述和标题的表格， 和那个 /use 命令会自动注入获取的项目以供以后使用。 MCP错误向REPL报告并得到尊重 mcp_error_mode 在自动化过程中 跑。
您还可以通过以下方式将本地LLM作为MCP工具公开： llm_tool 并将该入口连接到运行的进程 python -m simple_rag_writer.mcp.llm_tool --config config.yamlThe llm_tool 部分将技能关键字映射到单个配置的模型(skills: {reason: or-qwen3-235b-a22b})并限制了工具可能调用的模型。匹配的MCP 服务器条目可以简单到：
llm_tool:
id: "llm"
tool_name: "llm-complete"
title: "LLM skill completions"
skills:
reason: "or-qwen3-235b-a22b"
summarize: "or-kimi-k2"
default_skill: "reason"
max_tokens_limit: 2048
mcp_servers:
- id: "llm"
command:
- "python"
- "srw_llm_tool.py"
- "--config"
- "config.yaml"服务器将发布广告 skill 作为枚举 tools/list，并致电 tool 在MCP协议中可以请求 skill: "summarize" 仅确保 允许的模型会收到该提示。
开发与测试
这个repo遵循严格的TDD。对于每一个变化：
- 从验收测试开始
tests/（没有新功能
测试）。
- 模拟/固定MCP服务器；
tests/mcp_fixtures/notes_server.py展示
一个轻量级的JSON-RPC服务器 /statuses 和 /call.
- 跑
pytest（该套件通过模拟来避免真实的网络活动litellm
完成和HTTP请求）。
- 更新
codex/TASKS/*.yaml只有在明确指示的情况下——这些描述
主规范。
命令：
pytest # runs everything捐款应尊重项目结构(src/simple_rag_writer/ 为了 逻辑， tests/ 行为）并保持格式一致（2空格缩进 适用于Python/YAML）。