savant (Ashabbir)

Savant v0.1.0

Savant是一个轻量级的Ruby框架，用于构建和运行具有自主代理功能的本地MCP服务。当前版本为 v0.1.0，将CLI、MCP服务和React UI对齐到单个版本表面。

主要特点：

• 多路复用器：来自所有引擎（Context、Git、Think、Jira、Personas、Rules）的统一MCP表面合并工具
• 代理运行时：由Redis推理工作器支持的自主推理循环
• 启动系统：具有角色加载、AMR规则和仓库检测的RuntimeContext
• React用户界面：通过代理监控、日志和路线探索进行实时诊断

系统概述：

┌──────────────────────────────────────────────────────────────┐
│                         SAVANT                               │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌────────────┐     ┌──────────────┐     ┌──────────────┐  │
│  │  React UI  │────►│  Hub (HTTP)  │────►│ Multiplexer  │  │
│  └────────────┘     └──────────────┘     └──────┬───────┘  │
│                                                   │           │
│  ┌────────────┐                          ┌───────▼───────┐  │
│  │   Agent    │◄────────────────────────►│   Engines     │  │
│  │  Runtime   │  (routes via mux)        │ Context Think │  │
│  │            │                          │ Jira Personas │  │
│  │ Reasoning Worker│                      │     Rules     │  │
│  └────────────┘                          └───────────────┘  │
│        │                                                     │
│        ▼                                                     │
│  ┌────────────────────────────────────────────────────────┐ │
│  │         Logs + Telemetry + Memory Bank                 │ │
│  │  • agent_runtime.log    • session.json                 │ │
│  │  • agent_trace.log      • multiplexer.log              │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                              │
└──────────────────────────────────────────────────────────────┘

多路复用器概述

• bin/mcp_server 默认为多路复用器。它为每个引擎生成一个stdio MCP进程(context, git, think, personas, rules, jira 默认情况下），命名空间及其工具(context.fts_search, git.diff, jira.issue.get等），并将它们提供给连接的编辑器。
• 每个引擎故障都是隔离的——如果子引擎死亡，多路复用器会删除其工具，记录事件，并在后台重新启动。
• 指标和状态写入 logs/multiplexer.log 并通过Hub浮出水面(curl / 现在包括a multiplexer 对象）和CLI帮助程序(savant engines, savant tools).

# Inspect engines + status
SAVANT_PATH=$(pwd) bundle exec ruby ./bin/savant engines

# List namespaced tools
SAVANT_PATH=$(pwd) bundle exec ruby ./bin/savant tools

此README有意保持简洁。有关分步指南，请参阅docs/getting-started.md。完整详细的文档（带图表）位于内存库中：

议会（多代理）引擎

人工智能委员会能够明确地从轻量级聊天升级到具有角色（分析师、怀疑论者、实用主义者、安全/伦理、主持人）的结构化、多代理审议。安全有硬否决权；当理事会运行完成时，会话总是会返回聊天。

• UI：打开Hub并单击Council选项卡(/council).左侧面板列出会话；右图显示了会议记录和现场会议状态。
• API：理事会在 council 通过集线器HTTP路由的引擎： /{engine}/tools/{tool}/call.
• 升级的最低要求：会话中至少有两个代理。
• 环境： COUNCIL_DEMO_MODE=1 在没有推理工人的情况下运行； COUNCIL_AUTO_AGENT_STEP=1 在聊天中的用户消息上附加自动代理步骤。

快速示例（通过Hub的HTTP）

# Create a session
curl -s -H 'content-type: application/json' -H 'x-savant-user-id: me' \
  -X POST http://localhost:9999/council/tools/council_session_create/call \
  -d '{"params": {"title": "Tech Decision", "agents": ["a1","a2"]}}'

# Append user message
curl -s -H 'content-type: application/json' -H 'x-savant-user-id: me' \
  -X POST http://localhost:9999/council/tools/council_append_user/call \
  -d '{"params": {"session_id": 1, "text": "Microservices or monolith?"}}'

# Escalate to council (starts a run and flips mode to council)
curl -s -H 'content-type: application/json' -H 'x-savant-user-id: me' \
  -X POST http://localhost:9999/council/tools/council_escalate/call \
  -d '{"params": {"session_id": 1}}'

# Run protocol (positions → debate → synthesis), then auto return to chat
curl -s -H 'content-type: application/json' -H 'x-savant-user-id: me' \
  -X POST http://localhost:9999/council/tools/council_run/call \
  -d '{"params": {"session_id": 1}}'

数据模型（Postgres）

• council_sessions(id, title, user_id, agents TEXT[], description, mode, context JSONB, artifacts JSONB, created_at, updated_at)
• council_messages(id, session_id, role, agent_name, run_id, status, text, created_at)
• council_runs(id, session_id, run_id UNIQUE, status, phase, query, context JSONB, positions JSONB, debate_rounds JSONB, synthesis JSONB, votes JSONB, veto, veto_reason, started_at, completed_at, error)

完整PRD:docs/prds/done/PRD_AI_Consicil_Combined.md

Homebrew安装（发布版本后）

brew tap    # e.g., ashabbir/savant
brew install /savant
savant version

激活（脱机）并运行：

savant activate :
savant status

备注

• 激活完全脱机。密钥在运行时本地验证。
• Brew安装默认情况下强制激活。不进行网络呼叫。
• 有关开发，请参阅下面的许可证和激活部分以了解绕过选项。

入门指南

前置条件：Ruby 3.2+Bundler，以及一个本地Postgres实例。Docker不是必需的。

仅限Postgres：不支持SQLite。Savant以Postgres为目标（在13+上测试），并依赖JSONB和GIN索引进行FTS。确保本地Postgres正在运行且可访问。

运行（Rails API+UI，无Docker）

1. 配置Postgres（示例）：

export DATABASE_URL=postgres://context:contextpw@localhost:5432/contextdb

1. 准备数据库（幂等）：

# Run migrations and ensure FTS indexes
make db-migrate
make db-fts

# Optional smoke/seed helpers
make db-smoke
make db-seed

# Seeds include default LLM providers:
# - ollama (base_url from $OLLAMA_HOST or http://127.0.0.1:11434)
# - google (Generative Language API). If $GOOGLE_API_KEY is set and $SAVANT_ENC_KEY is configured,
#   the key is stored encrypted; otherwise the provider is created without a key and you can update it later via the UI or tools.

1. 构建UI包（可选；Rails在/UI处提供静态UI）：

make ui-build-local

1. 启动开发服务器（Rails API+Vite）：

# Terminal A: Rails API on http://localhost:9999
make dev-server

# Terminal B: Frontend with HMR on http://localhost:5173
make dev-ui

笔记：

• 用户界面（开发）：http://localhost:5173（HMR；编辑立即反映）
• APIhttp://localhost:9999（安装在Rails中的集线器端点）
• 健康：GEThttp://localhost:9999/healthz
• JSON-RPC:POSThttp://localhost:9999/rpc

通过Rake（Rails）进行索引

• 所有仓库： cd server && DATABASE_URL=$DATABASE_URL bundle exec rake savant:index_all
• 单一回购： cd server && DATABASE_URL=$DATABASE_URL bundle exec rake 'savant:index[myrepo]'
• 状态： cd server && DATABASE_URL=$DATABASE_URL bundle exec rake savant:status

启动运行时（快速启动）

Boot Runtime是Savant引擎的基础。首先运行它以初始化所有核心组件：

./bin/savant run

这将启动引擎并显示运行时状态，包括会话ID、角色、驱动程序提示、AMR规则和仓库上下文。创建的文件：

• .savant/runtime.json -持久运行时状态
• logs/engine_boot.log -结构化启动日志

选项：

./bin/savant run --persona=savant-architect  # Use different persona
./bin/savant run --skip-git                  # Skip git detection
./bin/savant review                          # Boot for MR review
./bin/savant workflow                  # Boot for workflow execution

看 启动运行时文档 供完整参考。

工作流（YAML执行器）

Savant包含一个确定性的YAML工作流执行器，可以调用工具（通过多路复用器）和代理。

如何运行工作流

• CLI（启动运行时并执行工作流）：

# From project root
./bin/savant workflow  --params='{"ticket":"JIRA-123"}'

• HTTP（集线器→ 通过MCP注册器使用工作流工具）：

# List workflows known to the Workflow engine
curl -s -H 'content-type: application/json' -H 'x-savant-user-id: me' \
  -X POST http://localhost:9999/workflow/tools/workflow_list/call \
  -d '{}'

# Run a workflow by ID with params
curl -s -H 'content-type: application/json' -H 'x-savant-user-id: me' \
  -X POST http://localhost:9999/workflow/tools/workflow_run/call \
  -d '{"params": {"ticket":"JIRA-123"}, "workflow": "example_workflow"}'

保存的跑步记录和遥测数据

• 运行状态持久化为 .savant/workflow_runs/__.json.
• 每一步遥测都附加到 logs/workflow_trace.log （jsonl）。

诊断UI

• 打开诊断→ 在UI中查看工作流：

- 最近的工作流事件（包括时间、步骤和类型） - 保存的运行表，可深入查看完整跟踪

创作工作流

• 将YAML文件放入仓库 workflows/ 目录。最小架构：

steps:
  - name: diff
    tool: git.diff

  - name: summarize
    agent: summarizer
    with:
      goal: "Summarize the diff concisely"

• Think引擎附带了工作流编辑器（引擎→ 思考→ 工作流），允许图形编辑、验证、YAML预览和图表渲染。

代理运行时（推理工作者）

Agent Runtime通过将决策委托给Redis支持的推理工作器来编排自主推理循环。

架构概述：

┌─────────────────────────────────────────────────────────────┐
│                    AGENT RUNTIME LOOP                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Prompt Builder  ──► Reasoning Worker ──► Action Parser    │
│       │                                    │                │
│       ▼                                    ▼                │
│  Memory System ◄────── Multiplexer ◄── Tool Router         │
│  (Ephemeral +           (Context,                           │
│   Persistent)           Think, Jira)                        │
│                                                             │
│  Artifacts:                                                 │
│  • logs/agent_runtime.log  (execution logs + timings)       │
│  • logs/agent_trace.log    (telemetry per step)            │
│  • .savant/session.json    (persistent memory)             │
│                                                             │
│  Decisions: Reasoning Worker                               │
│  Budget:   LLM context as configured (tools may use LLM)   │
└─────────────────────────────────────────────────────────────┘

快速入门：

# Install Ollama + models
ollama pull phi3.5:latest
ollama pull llama3:latest

# Run agent session
./bin/savant run --skip-git --agent-input="Summarize recent changes"

CLI选项：

• --agent-input=TEXT 或 --agent-file=PATH 用于目标输入
• --llm=MODEL 为繁重的任务推荐法学硕士
• --max-steps=N 为循环设置上限（默认值25）
• --dry-run 模拟工具调用而不执行它们
• --quiet 将JSON日志抑制到控制台（日志仍写入文件）
• --force-tool=NAME 和 --force-args=JSON 强制第一步调用特定工具（使用完全限定名，如 think_prompts_list 或 context.fts_search)
• --force-finish 在强制工具之后立即完成（如果没有强制工具，则在步骤1完成），可选地使用 --force-final="text"
• --force-finish-only 立即完成而不执行任何工具（忽略 --force-tool)

人工产品：

• logs/agent_runtime.log –带有时间和决策的运行时日志
• logs/agent_trace.log 遥测事件（每个推理步骤一个）
• .savant/session.json –每步内存快照

Web UI诊断：

• 打开Hub UI http://localhost:9999/ui.

- 每个发动机卡现在都有快速链接：诊断（打开 /diagnostics/mcp/)和日志（打开 //logs). - 可以在诊断下访问代理页面。

http://localhost:9999/diagnostics/agent
  ├─ Timeline View    (chronological event stream)
  ├─ Grouped View     (events grouped by step)
  ├─ Live Streaming   (real-time updates)
  └─ Export           (download traces + session)

HTTP诊断和日志端点：

• 某些诊断需要用户标头。包含 x-savant-user-id: 在请求中。
• 示例：

- 每引擎诊断（Git）： curl -H 'x-savant-user-id: me' http://localhost:9999/diagnostics/mcp/git - 每引擎日志（尾部JSON）： curl -H 'x-savant-user-id: me' 'http://localhost:9999/git/logs?n=200' - 聚合事件（按引擎筛选）： curl -H 'x-savant-user-id: me' 'http://localhost:9999/logs?mcp=git&n=100' - 代理摘要： curl -H 'x-savant-user-id: me' http://localhost:9999/diagnostics/agent - 代理跟踪（纯文本）： curl -H 'x-savant-user-id: me' http://localhost:9999/diagnostics/agent/trace - SSE日志流： curl -N -H 'x-savant-user-id: me' 'http://localhost:9999/logs/stream'

看 代理运行时文档 了解详细的架构、存储系统和遥测技术。

LLM注册

LLM注册表提供对LLM提供程序、模型和代理配置的集中管理。它支持具有加密API密钥存储的多个提供商（Google Cloud、Ollama等）。

访问注册表：

• 用户界面: http://localhost:5173/llm-注册表（具有3个选项卡的Web界面：提供者、模型、代理）
• 命令行界面: ./bin/llm [options]

CLI命令：

供应商管理：

# Add a provider (Google with API key)
./bin/llm provider add --type google --name "Google Primary" --api-key YOUR_API_KEY

# Add a provider (Ollama with base URL)
./bin/llm provider add --type ollama --name "Local Ollama" --base-url http://localhost:11434

# List all providers
./bin/llm provider list

# Test a provider's connection
./bin/llm provider test --name "Google Primary"

# Delete a provider
./bin/llm provider delete --name "Google Primary"

模型管理：

# Discover available models from a provider
./bin/llm models discover --provider "Google Primary"

# Register a model for use
./bin/llm models register --provider "Google Primary" --id gemini-2.0-pro

# List all registered models
./bin/llm models list

代理管理：

# Create a new agent
./bin/llm agent add --name context-agent --description "Context analysis agent"

# Assign a model to an agent
./bin/llm agent assign --name context-agent --model-id 1

# List all agents with their assigned models
./bin/llm agent list

# Delete an agent
./bin/llm agent delete --name context-agent

配置：

# Set the encryption key (required for API key storage)
export SAVANT_ENC_KEY=$(ruby -e "require 'securerandom'; puts SecureRandom.hex(32)")

数据库：

• LLM注册表使用5个表： llm_providers, llm_models, llm_agents, llm_agent_model_assignments, llm_cache
• API密钥在存储前使用AES-256-GCM进行加密
• 运行迁移： make db-migrate

HTTP API（通过集线器）：

# List providers
curl -H 'x-savant-user-id: me' -X POST http://localhost:9999/llm/tools/llm_providers_list/call -d '{}'

# Create provider
curl -H 'x-savant-user-id: me' -X POST http://localhost:9999/llm/tools/llm_providers_create/call \
  -d '{"params": {"name": "Google", "provider_type": "google", "api_key": "KEY"}}'

# List models
curl -H 'x-savant-user-id: me' -X POST http://localhost:9999/llm/tools/llm_models_list/call -d '{}'

# Discover models
curl -H 'x-savant-user-id: me' -X POST http://localhost:9999/llm/tools/llm_models_discover/call \
  -d '{"params": {"provider_name": "Google Primary"}}'

# Create agent
curl -H 'x-savant-user-id: me' -X POST http://localhost:9999/llm/tools/llm_agents_create/call \
  -d '{"params": {"name": "my-agent", "description": "Test agent"}}'

# Assign model to agent
curl -H 'x-savant-user-id: me' -X POST http://localhost:9999/llm/tools/llm_agents_assign_model/call \
  -d '{"params": {"agent_name": "my-agent", "model_id": 1}}'

# List agents
curl -H 'x-savant-user-id: me' -X POST http://localhost:9999/llm/tools/llm_agents_list/call -d '{}'

未来：LangChain/LangGraph集成

• LLM注册表与用于代理/工作流智能的单独推理服务配对
• 看 docs/prds/langchain-graph-api.md 目的API规范和实现路线图

全栈设置

1. 数据库设置（Postgres+FTS）：

make db-migrate && make db-fts

1. 索引仓库（见config/settings.json）：

make repo-index-all

1. 离线激活

- 生产（酿造/包装）：发动机/MCP启动前需要。 - 开发（git checkout）：自动绕过；详见下文。

./bin/savant activate :
./bin/savant status

1. 用户界面

• 静态： make ui-build-local 然后打开http://localhost:9999/ui
• 开发人员： make dev-ui 然后打开http://localhost:5173（中心位于http://localhost:9999)

1. MCP多路复用器（stdio）

# Unified multiplexer (default)
SAVANT_PATH=$(pwd) bundle exec ruby ./bin/mcp_server

# Run a single engine (optional override)
MCP_SERVICE=context  SAVANT_PATH=$(pwd) bundle exec ruby ./bin/mcp_server
MCP_SERVICE=git      SAVANT_PATH=$(pwd) bundle exec ruby ./bin/mcp_server
MCP_SERVICE=jira     SAVANT_PATH=$(pwd) bundle exec ruby ./bin/mcp_server

建筑

Savant由六个主要后端模块和一个单独的前端组成：

lib/savant/
├── hub/              # MODULE 1: Hub API (HTTP routing, SSE, service management)
├── logging/          # MODULE 2: Logging & Observability (structured logging, metrics, audit)
├── framework/        # MODULE 3: Framework (MCP core, middleware, transports, config)
├── engines/          # MODULE 4: Engines (context, think, jira, personas, rules, etc.)
├── agent/            # MODULE 5: Agent Runtime (reasoning loop, prompt builder, parser, memory)
└── llm/              # MODULE 6: LLM Adapters (Ollama, Anthropic, OpenAI)

模块1：轮毂API(lib/savant/hub/)

目的：提供工具调用、诊断和引擎管理的HTTP API

关键文件:

• builder.rb -从配置构建枢纽
• router.rb -HTTP请求路由
• sse.rb -服务器发送实时流媒体事件
• service_manager.rb -发动机装载机和调度员
• connections.rb -连接注册表
• static_ui.rb -静态资产服务

关键终点: /, /routes, /diagnostics, /hub/status, /logs, /:engine/tools/:name/call

模块2：记录和观测(lib/savant/logging/)

目的：集中式日志记录、指标、审计跟踪和遥测

关键文件:

• logger.rb -带液位和计时的结构化记录仪
• event_recorder.rb -内存+文件事件存储
• metrics.rb -计数器和分配
• replay_buffer.rb -请求重播缓冲区
• exporter.rb -指标导出（Prometheus格式）
• audit/policy.rb -审核配置
• audit/store.rb -审计日志持久性

关键API: Logger.new(service:, tool:), EventRecorder.record(event), Metrics.increment(metric, labels)

模块3：框架(lib/savant/framework/)

目的：MCP框架核心、中间件、传输和共享实用程序

关键文件:

• mcp/core/ -工具规范、注册器、DSL、中间件、验证
• mcp/server.rb -MCP服务器实现
• mcp/dispatcher.rb -JSON-RPC调度器
• engine/base.rb -发动机基础等级
• engine/context.rb -运行时上下文
• middleware/ -trace.rb、logging.rb、metrics.rb、user_header.rb
• transports/http/rack_app.rb -Minimal Rack应用程序
• transports/mcp/stdio.rb -标准运输
• transports/mcp/websocket.rb -WebSocket传输
• config.rb -配置加载器
• db.rb -数据库抽象
• secret_store.rb -秘密管理
• boot.rb 独自创立
• generator.rb -代码生成

关键API: Framework::MCP::Core::DSL.build { ... }, Registrar.call(name, args, ctx:), Engine#before_call

模块4：发动机(lib/savant/engines/)

目的：所有MCP引擎实施

发动机 （根据 lib/savant/engines/):

• 上下文 (context/)：DB支持的FTS超过回购块；记忆库助手。看 memory_bank/engine_text.md
• 思考 (think/)：工作流编排(plan/next)驾驶员提示。看 memory_bank/engine_think.md
• Jira (jira/)：Jira REST v3集成。看 memory_bank/engine_jira.md
• 人物角色 (personas/)：YAML人物角色目录。看 内存库/引擎_人员.md
• 规则 (rules/)：共享护栏和最佳做法。看 memory_bank/engine_rules.md
• 索引器 (indexer/)：存储库索引和分块
• 人工智能 (ai/)：代理编排
• 抽象意义表示 (amr/)：资产管理规则

ℹ️ Boot运行时(lib/savant/framework/boot.rb)存在于Framework模块中，因为它在引擎运行之前连接了配置、角色、提示、AMR规则和运行时状态。看 memory_bank/engine_boot.md 了解全部细节。

发动机模式：每台发动机都有 engine.rb （延伸 Framework::Engine::Base), tools.rb （使用 Framework::MCP::Core::DSL)，以及 ops.rb （商业逻辑）。

模块5：代理运行时(lib/savant/agent/)

目的：自主推理循环协调LLM驱动的工具执行

关键文件:

• runtime.rb -具有步数限制和重试逻辑的核心推理循环
• prompt_builder.rb -代币预算管理和确定性提示组装
• output_parser.rb -JSON提取、模式验证、自动更正
• memory.rb -短命制国家+ .savant/session.json 持久性

关键概念:

• 推理工人决策：外部化意图选择（Redis worker）
• LLM支持：在需要时对工具输出进行深入分析
• 代币预算：LLM上下文预算，LRU削减（如适用）
• 记忆持久性：带有摘要的会话快照

关键API: Runtime.new(goal:, llm_model:).run(max_steps:, dry_run:)

看 memory_bank/运行时.md 用于具有可视化图表的完整架构。

模块6:LLM适配器(lib/savant/llm/)

目的：可插拔LLM提供程序抽象层

关键文件:

• adapter.rb -基于ENV配置的提供商委派
• ollama.rb -Ollama实现（默认，本地优先）
• anthropic.rb -Anthropic API存根（Claude型号）
• openai.rb -OpenAI API存根（GPT模型）

配置:

ENV['LLM_PROVIDER']  # ollama|anthropic|openai
# SLM_MODEL deprecated (decisions handled by Reasoning Worker)
ENV['LLM_MODEL']     # llama3:latest (default)
ENV['OLLAMA_HOST']   # http://127.0.0.1:11434 (default)

关键API: LLM::Adapter.generate(model:, prompt:, temperature:, max_tokens:)

生成器

在几秒钟内搭建一个新引擎：

ruby ./bin/savant generate engine  [--with-db] [--force]

创造 lib/savant/engines//{engine.rb,tools.rb} 然后运行 MCP_SERVICE= ruby ./bin/mcp_server.

传输层

flowchart LR
  subgraph Hub[HTTP Hub]
    R[Router]-- ServiceManager --> E[Engine Registrar]
  end
  UI[React UI] -->|HTTP JSON| R
  CLI[Editor/CLI] -->|stdio JSON-RPC| EngineProc
  EngineProc[Single MCP Process] --> E
  E -->|call tool| Ops
  Ops --> DB[(Postgres)]

• 超文本传输协议: lib/savant/framework/transports/http/rack_app.rb -Hub+UI的机架应用程序
• 主控程序: lib/savant/framework/transports/mcp/{stdio,websocket}.rb -Stdio/Webocket编辑器
• 服务管理器: lib/savant/hub/service_manager.rb -与运输无关的发动机负载
• 每个MCP过程只有一个发动机；Hub通过HTTP复用多个引擎

用户界面

• React UI下 /ui （或dev at 5173）有三个主要部分：

- 仪表盘：所有发动机和系统状态概述 - 发动机：每个引擎选项卡用于工具执行和测试 - 诊断：五个选项卡用于系统监控 - 概述：系统配置、数据库连接、仓库、角色、规则、LLM模型 - 请求：HTTP请求日志和流量统计 - 代理：实时代理运行时监控，包括时间线/分组视图、实时流媒体、跟踪导出 - 日志：带有日志级过滤的实时事件流（全部/调试/信息/警告/错误） - 路线：API路线浏览器，按模块、方法和路径进行过滤

• 页脚显示开发模式/构建模式指示器

UI一致性和测试

React UI在整个应用程序中使用紧凑的设计和一致的控件大小。

• 紧凑主题：11px基础排版；列表/表格行28-32px；紧密的围篱；6px半径。
• 控件：按钮和图标按钮默认为 size="small"；图标默认为小（~18px）。开始/结束图标间距是标准化的。
• 工具：所有引擎工具页面都使用一个工具运行器（模式驱动的表单、JSON输入、预设/历史、cURL/HTTPi副本）。
• 诊断：带过滤器的实时日志/事件流；请求检查器支持重新执行和“在工具运行器中打开”。

前端测试可用（Vitest+测试库）。

cd frontend
npm run test       # run once
npm run test:watch # watch mode

关键测试文件：

• src/theme/compact.test.ts：压缩比例+按钮/图标默认值。
• src/components/ToolRunner.test.tsx：form/json模式和工具执行。
• src/utils/tools.test.ts：模式分类、默认值、cURL/CLI帮助程序。

诊断和日志

• 聚合日志（JSON事件）： GET /logs?n=100[&mcp=context][&type=http_request]
• 现场活动流（SSE）： GET /logs/stream[?mcp=context][&type=tool_call_started]
• 每个引擎日志（文件尾部）： GET /:engine/logs?n=100 或与流 ?stream=1
• 代理诊断: GET /diagnostics/agent （事件+记忆）， GET /diagnostics/agent/trace, GET /diagnostics/agent/session
• 集线器请求统计数据： GET /hub/stats
• 连接列表： GET /diagnostics/connections
• 根据发动机诊断： GET /diagnostics/mcp/:name

存储库（详细文档）

所有详细文档（带可视化图表）均在 memory_bank/.使用上表（和下面的直接链接）跳到真相的来源：

• 框架+架构： framework.md, architecture.md

• 启动运行时： engine_boot.md -RuntimeContext、引导序列、AMR系统、CLI参考

• 代理运行时： runtime.md -推理循环、LLM适配器、存储系统、令牌预算、遥测

• 发动机： engine_context.md, engine_think.md, engine_jira.md, engine_personas.md

• 护栏+图案： engine_rules.md

这些是规范的参考文献；README保持简短，并将您指向那里。

分发和激活（MVP）

概述

• Savant通过Homebrew以单一二进制形式发货。仅使用用户名+密钥对才能脱机激活。
• 密钥在本地使用盐SHA256进行验证。未联系到许可证服务器。

命令

• savant activate : --将许可证存储在 ~/.savant/license.json.
• savant status --打印许可证是否有效以及存储的路径。
• savant deactivate --删除本地许可证文件。

Dev vs Prod行为

• 酿造/打包安装：默认情况下强制执行许可证。
• Git签出（开发）：在以下情况下会自动绕过许可证 SAVANT_PATH 指向一个包含 .git 文件夹。
• 设定目标：默认为 SAVANT_DEV=1，所以全部 make 流在没有密钥的情况下运行。
• 在dev:set中强制执行 SAVANT_ENFORCE_LICENSE=1 即使在git结账时也需要有效的许可证。

环境变量

• SAVANT_PATH：项目基本路径（本地运行所需；Brew在内部设置此路径）。
• SAVANT_DEV：当 1，绕过许可证检查。Makefile将其导出为 1 默认情况下。
• SAVANT_ENFORCE_LICENSE：当 1，即使在dev/git签出中也会强制进行许可证检查。

构建和发布（手动MVP）

• 构建/打包/校验和（工件 dist/):

- SAVANT_BUILD_SALT='' make build - make package && make checksum

• 标签+发布（需要 gh):

- make tag VERSION=v0.1.0 - make release VERSION=v0.1.0

• 自制配方：

- RELEASE_BASE_URL=https://github.com//savant/releases/download make formula - 复制 packaging/homebrew/savant.rb 进入您的公共水龙头。