flowchart LR
    START([START]) --> G["guard<br/>注入防护"]
    G -->|"命中注入"| F["finalize<br/>收敛"]
    G -->|"放行"| R["recall<br/>记忆召回"]
    R --> C["classify<br/>意图识别"]
    C -->|"no_reply"| F
    C -->|"price / tech / default"| A["agent<br/>专家推理"]
    A -->|"需要工具"| T["tools<br/>工具执行"]
    T --> A
    A -->|"生成草稿"| K["critic<br/>审核 Agent"]
    K -->|"驳回→重写"| A
    K -->|"通过"| F
    F --> E([END])

2026-09-11 21:14:34.352 | INFO | koiagent.agent.graph:__init__:180 - KoiAgent 图已编译完成，工具: ['get_bargain_policy', 'search_knowledge_base', 'get_current_time'], 最大推理步数: 4
2026-09-11 21:14:34.353 | INFO | koiagent.rag.knowledge:reload:202 - RAG 运行于【关键词检索】模式，已加载 2 个知识片段
2026-09-11 21:14:34.364 | INFO | koiagent.agent.graph:_classify:282 - [classify] 意图=price（路由: rule）
2026-09-11 21:14:34.367 | INFO | koiagent.agent.graph:_agent:322 - [agent] step=1, tool_calls=无
2026-09-11 21:14:34.371 | INFO | koiagent.agent.graph:_critic:366 - [critic] 草稿审核通过
2026-09-11 21:14:34.388 | WARNING | koiagent.agent.graph:_guard:227 - [guard] 拦截疑似 Prompt 注入 (score=10, 命中=['指令覆盖', '提示词探测'])

──────── KoiAgent 运行指标 ────────
总运行次数   : 3
错误次数     : 0 (错误率 0.00%)
平均耗时     : 10.63 ms
P95 耗时     : 20.16 ms
意图分布     : {'price': 1, 'tech': 2}
拦截注入     : 1
────────────────────────────────────

1. 克隆仓库
git clone https://github.com/Xiao-Snake123/KoiAgent.git
cd KoiAgent

2. 安装依赖
pip install -r requirements.txt

3. 配置环境变量
复制 .env.example 为 .env，并填写以下内容：

# 必配配置
API_KEY=apikey通过模型平台获取
COOKIES_STR=填写网页端获取的cookie
MODEL_BASE_URL=模型地址
MODEL_NAME=模型名称

# 可选配置
TOGGLE_KEYWORDS=接管模式切换关键词，默认为句号（输入句号切换为人工接管，再次输入则切换AI接管）
SIMULATE_HUMAN_TYPING=False  # 模拟人工回复延迟

# Agent 编排（可选）
AGENT_MAX_STEPS=4       # ReAct 最大推理步数
AGENT_MAX_MESSAGES=20   # 单次送入模型的最大历史消息数
AGENT_MAX_REFLECTIONS=1 # 审核驳回后的最大返工轮数
CRITIC_ENABLED=true     # 是否启用审核 Agent
KNOWLEDGE_DIR=knowledge # 本地知识库目录

# RAG 向量检索（可选，留空 EMBEDDING_MODEL 则自动使用关键词检索）
EMBEDDING_MODEL=        # 如 text-embedding-v3
EMBEDDING_BASE_URL=     # 留空回退 MODEL_BASE_URL
EMBEDDING_API_KEY=      # 留空回退 API_KEY
RAG_TOP_K=3             # 返回片段数
RAG_CHUNK_SIZE=300      # 切片长度
RAG_CHUNK_OVERLAP=60    # 切片重叠

# 输入侧 Prompt 注入防护（可选）
GUARD_ENABLED=true      # 关闭注入防护
GUARD_BLOCK_SCORE=5     # 拦截阈值（命中权重累加）
GUARD_MAX_INPUT=1000    # 最大输入长度，超出截断

# 可靠性（可选）
LLM_MAX_CONCURRENCY=4        # LLM 并发上限
CIRCUIT_FAILURE_THRESHOLD=5  # 连续失败几次后熔断
CIRCUIT_RESET_TIMEOUT=60     # 熔断冷却秒数
FALLBACK_REPLY=稍等，我确认下再回复您  # 降级兜底话术
DEDUP_TTL=300                # 消息去重窗口（秒）
MEMORY_MAX_THREADS=500       # 会话记忆最大 thread 数
MEMORY_TTL=7200              # 会话记忆空闲淘汰（秒）

# 可观测性与稳定性（可选）
TRACE_ENABLED=true      # 关闭追踪
TRACE_DIR=logs          # Trace 与指标输出目录
LLM_TIMEOUT=30          # 单次 LLM 请求超时（秒）
LLM_MAX_RETRIES=2       # LLM 请求失败重试次数
HEALTH_FILE=data/health.json  # 健康检查心跳文件

4. 准备提示词文件
prompts/*_prompt.txt 可直接删除模板名称中的 _example 得到，否则默认读取四个提示词模板中的内容

python -m koiagent     # 推荐
# 或（等价）
python main.py

KoiAgent/
├── koiagent/                     # 主包
│   ├── __init__.py               # 包元信息（__version__ / 分层说明）
│   ├── __main__.py               # 入口：python -m koiagent
│   ├── app.py                    # 应用装配：WebSocket 长连 / 心跳 / Token 刷新 / 人工接管
│   ├── config.py                 # 配置加载 / 声明式 schema 校验 / 缺失配置交互式补全
│   ├── agent/                    # Agent 编排层
│   │   ├── graph.py              #   LangGraph 状态图 guard→recall→classify→agent⇄tools→critic
│   │   ├── tools.py              #   Function Calling 工具集（接入工具记忆缓存）
│   │   ├── guard.py              #   输入侧 Prompt 注入防护
│   │   └── bargain.py            #   议价策略（JSON 驱动 + 热更新）
│   ├── memory/                   # 记忆系统
│   │   ├── store.py              #   SQLite 存储层（memories / user_profiles / tool_calls）
│   │   ├── short_term.py         #   短期记忆：窗口 + 增量摘要压缩
│   │   ├── long_term.py          #   长期记忆：事实抽取 / 相关度召回 / 衰减淘汰
│   │   ├── profile.py            #   用户画像：结构化属性 + 增量合并
│   │   ├── tool_memory.py        #   工具记忆：会话级结果缓存 + 调用记录
│   │   └── manager.py            #   门面：recall / remember / 上下文渲染
│   ├── rag/
│   │   └── knowledge.py          # RAG 检索层（向量 / 关键词双模式 + 缓存 + 热更新）
│   ├── platform/
│   │   ├── api.py                #   平台 HTTP 接口（登录 / Token / 商品）
│   │   └── protocol.py           #   协议工具（Cookie / 签名 / MessagePack 解码）
│   ├── infra/
│   │   ├── observability.py      #   全链路 Trace（含轮转）/ 指标聚合 / Token 与成本
│   │   ├── resilience.py         #   幂等去重 / 熔断 / 并发限流 / 记忆治理 / 出站限速
│   │   ├── text.py               #   共享文本工具（分词 / 归一化 / 稳定哈希）
│   │   └── prompts.py            #   提示词加载（自定义 → 示例 → 内置默认）
│   ├── storage/
│   │   └── context.py            #   SQLite 业务数据（议价次数 / 商品缓存）
│   ├── mcp/
│   │   └── server.py             #   MCP Server
│   └── ops/
│       ├── healthcheck.py        #   容器健康检查
│       └── order_events.py       #   订单事件钩子（待付款 / 关闭 / 待发货）
├── main.py                       # 兼容入口（等价于 python -m koiagent）
├── config/
│   └── bargain_policy.json       # 议价阶梯策略（可改，热更新生效）
├── docs/                         # 设计文档
│   ├── ARCHITECTURE.md           #   架构说明与设计决策
│   └── INTERVIEW_QA.md           #   设计问答手册
├── knowledge/                    # 本地知识库（供 search_knowledge_base 检索）
├── prompts/                      # 提示词模板（专家角色 / 审核 / 记忆抽取）
├── eval/                         # 评估 Harness（评估集 + runner + 报告）
├── tests/                        # pytest 单元测试
├── .github/workflows/            # CI 流水线（编译 + 测试 + 评估门禁）
├── images/                       # 演示图片
├── pyproject.toml                # 工具配置（pytest）
├── requirements.txt              # 运行时依赖
├── requirements-dev.txt          # 开发/测试依赖
├── Dockerfile
└── docker-compose.yml

# 先准备 .env 与 prompts/*.txt
docker compose up -d

python -m koiagent.mcp.server                             # stdio（桌面客户端默认）
python -m koiagent.mcp.server --transport streamable-http # HTTP 传输

{
  "mcpServers": {
    "koi-agent": {
      "command": "python",
      "args": ["-m", "koiagent.mcp.server"],
      "cwd": "/path/to/KoiAgent"
    }
  }
}

pip install -r requirements-dev.txt
pytest

python eval/run_eval.py             # 离线：规则路由 + RAG 检索
python eval/run_eval.py --with-llm  # 追加 LLM 路由兜底评估（需 API_KEY）