# ahccli-python

**Repository Path**: imagescience/ahccli-python

## Basic Information

- **Project Name**: ahccli-python
- **Description**: AHCCLI Python 是一个运行在终端里的 AI Agent CLI，面向真实项目开发场景：读写文件、搜索代码、执行命令、联网检索、调用 MCP 工具、保存记忆、生成快照、恢复现场，并通过 Runtime API 对外提供线程、turn、事件和后台任务能力。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-11
- **Last Updated**: 2026-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AHCCLI-Python

> 运行在终端里的 AI Agent CLI —— 基于 ReAct 推理循环、Plan-and-Execute 模式、三层记忆系统、RAG 代码检索、Multi-Agent 团队编排、三层安全防线、项目快照、可扩展 Skill 技能系统与 Runtime HTTP 开放 API，让大模型在命令行中安全地自主思考、调用工具、完成任务，全部能力亦可经 HTTP 服务供外部程序调用。

[English](README.en.md) | 中文

---

## 项目简介

AHCCLI Python 是一个面向真实项目开发场景的终端 AI Agent。它提供两种工作模式：

- **ReAct 模式** — 通过 ReAct（Reasoning + Acting）推理循环驱动大语言模型，使模型在终端中自主思考、判断是否需要调用工具、执行工具并将结果回填至模型进行下一轮推理，直至得出最终答案。
- **Plan-and-Execute 模式** — 先将复杂需求拆解为结构化子任务计划，经用户审查确认后按依赖拓扑并发执行，支持失败重试与错误反馈纠正。
- **三层记忆系统** — 短期会话缓冲、长期 SQLite 持久化存储、关键词索引检索，支持 Agent 在推理中主动搜索和保存记忆。
- **RAG 代码检索** — Python AST 三级分片 + 多语言滑动窗口切分，SQLite BLOB 向量存储，三路加权混合检索（语义 + 关键词 + 类型权重），代码关系图谱可视化。
- **Multi-Agent 多智能体编排** — Planner→Worker→Reviewer 三段流水线，规划者拆解需求、工作者并行执行、审核者校验质量，工具白名单按角色隔离。
- **三层安全防线与 HITL 人工审批** — 危险命令黑名单拦截、路径守卫限制文件访问范围、高危工具调用强制人工确认，全量审计日志（SQLite + 日志文件）。
- **项目快照（增量备份与一键回滚）** — 任务/Plan 执行前自动创建快照，SHA-256 清单增量备份仅存变更文件，一键回滚任意历史节点，不污染 Git 版本管理。
- **可扩展 Skill 技能系统** — SKILL.md 技能规范绑定本地工具 + MCP 工具 + 专属 Prompt 模板 + 执行前置校验规则；Agent 按需求语义自动匹配并懒加载技能（启动仅预缓存元数据），技能 Prompt 注入 per-session 会话上下文；安装/卸载/启用/禁用生命周期与多 Agent 技能白名单，加载全程集成快照、HITL 审批与审计日志。
- **Runtime HTTP 开放 API** — Starlette + uvicorn 异步 HTTP 服务，外部程序经 API 密钥鉴权调用全部 Agent 能力：会话问答（同步问答 + SSE 流式推理输出）、Plan 后台任务（进度轮询/协作终止）、记忆检索 / RAG 代码查询 / 快照回滚 / 技能加载资源接口、MCP 服务控制与浏览器自动化（与终端同一条安全链路）；前台独占与 CLI + API 双运行两种启动模式，全部 API 请求写入全局审计日志并在 Rich 终端实时展示流量。
- **MCP 外部工具生态接入** — 基于 Anthropic 官方 MCP SDK，stdio 本地 + Streamable HTTP 远程双传输，mcp.json 配置驱动自动扫描加载，外部工具以 `mcp__{server}__{tool}` 命名注册进全局工具池统一调度，与本地工具共享 HITL 高危审批；高级扩展（v0.11.0）提供工具权限隔离、资源/Prompt SQLite 缓存、批量并行调用、心跳检测与离线降级/崩溃自动重启、每服务 API 密钥/超时/代理/快照开关独立配置；增量能力含资源双通路/虚拟资源、服务端通知被动路由与事件驱动缓存失效、@提及展开与补全、ESC//cancel 任务取消；Chrome 浏览器自动化（v0.12.0）对接标准 Chrome DevTools MCP（页面打开/点击/输入/截图/JS 执行/网络捕获），浏览器操作强制 HITL 审批 + URL 黑名单校验，青色 Rich 可视化渲染与 chrome-mcp 管理命令；CDP 会话池与浏览器状态缓存（v0.13.0）提供常驻连接复用、并发隔离、空闲回收与登录会话恢复。

## 核心特性

### ReAct 模式
- **ReAct 推理循环** — 标准 Think → Act → Observe 迭代流程，自动判断何时调用工具、何时输出最终答案
- **流式 SSE 解析** — 基于 `httpx.AsyncClient` 异步流，兼容 OpenAI 兼容接口（智谱 GLM 等）的流式输出
- **Rich 终端可视化** — 推理步骤、工具调用、观察结果、最终答案均以彩色面板实时展示
- **迭代安全控制** — 可配置最大迭代轮次，防止推理死循环

### Plan-and-Execute 模式
- **LLM 任务分解** — 自动将复杂需求拆解为带依赖关系的结构化子任务
- **拓扑排序 + 并发执行** — 按依赖层级分组，同层任务并发执行，跨层按序调度
- **E/S/C 审查流程** — 生成计划后用户可选择执行（Execute）、补充（Supplement）或取消（Cancel）
- **失败重试 + 错误反馈** — 任务失败自动重试，失败结果反馈给 LLM 生成纠正计划
- **OS 感知** — 自动检测操作系统，指导 LLM 生成兼容的 Shell 命令

### 三层记忆系统
- **短期记忆** — 内存级会话缓冲，会话结束时自动持久化到 SQLite
- **长期记忆** — SQLite 存储事实（facts），支持手动保存、对话提取、Agent 推理保存
- **关键词索引** — 中英文分词 + 二元组（bigram）索引，AND 多条件检索
- **Agent 工具集成** — `search_memory` 和 `save_memory` 工具供 LLM 在推理中主动调用
- **REPL 命令** — `/memory` 查看状态、`/save` 保存事实等交互命令
- **数据库自修复** — 自动检测损坏并备份重建

### RAG 代码检索
- **Python AST 三级解析** — FILE → CLASS → FUNCTION 结构化分片，提取导入、基类、方法、参数、调用等元数据
- **多语言支持** — 内置 11 种编程语言检测，非 Python 文件按 2000 字符滑动窗口切分
- **向量存储** — float 向量转 Little-Endian BLOB 存入 SQLite，无需外部向量数据库
- **三路混合检索** — 语义向量相似度 × 0.6 + jieba 关键词匹配 × 0.3 + 代码类型权重 × 0.1
- **API 降级容错** — Embedding API 不可用时自动切换为纯关键词检索模式
- **代码关系图谱** — 双轮 AST 遍历提取 IMPORTS/EXTENDS/IMPLEMENTS/CONTAINS/CALLS 五类关系，Rich 树形渲染
- **增量扫描** — 基于文件哈希的增量索引，仅重新解析变更文件
- **Agent 工具集成** — `search_code` 工具 + MUST/NEVER 强制检索提示词
- **智能检索策略** — RAG 开启且已索引时使用 `search_code`，否则自动切换为 `glob_files` + `grep_code` + `read_file` 工具链
- **REPL 命令** — `/index` 索引项目、`/search` 语义搜索、`/graph` 关系图谱、`/rag on|off` 开关 RAG

### Multi-Agent 多智能体编排
- **四大核心组件** — AgentMessage 消息、AgentRole 角色、SubAgent 子智能体、AgentOrchestrator 编排器
- **Planner→Worker→Reviewer 三段编排** — 规划者拆解需求、工作者并行执行、审核者校验质量
- **串行流水线 + 并行子任务** — 三阶段串行推进，阶段内子任务批量并发执行（信号量控并发）
- **异常重试 + 审核解析** — 审核未通过时携带反馈意见重试工作者，容错解析 JSON 结论
- **httpx 异步消息总线** — MessageBus 按名称路由消息，支持本地投递与远程 httpx 扩展
- **独立记忆/工具/模型** — 每个智能体持有独立记忆缓冲、受限工具集与角色级模型配置
- **工具白名单隔离** — ToolRegistry 按角色过滤工具：规划者禁用、工作者全量、审核者只读
- **三层缓冲渲染** — BufferedRenderer 隔离推理/输出/后置推理，避免流式内容交错污染
- **Rich 进度可视化** — 区分智能体名称、角色、任务状态实时展示编排进度
- **默认单 Agent 模式** — 保留原有单智能体为默认，`/team` 命令显式触发多智能体编排

### 三层安全防线与 HITL 人工审批
- **防线 1：命令拦截器** — 内置 19 条危险命令黑名单正则（rm -rf /、mkfs、format c:、diskpart、fork 炸弹、curl|sh 等），命中直接拦截拒绝执行
- **防线 2：路径守卫** — 所有文件读写工具仅限允许目录（默认项目根目录）内操作，.ssh/.aws/Windows 等系统敏感路径双重拦截
- **防线 3：HITL 人工审批** — 高危工具（execute_command/write_file）调用时弹出确认面板，展示工具名、入参与风险提示，支持确认/拒绝/永久放行/会话放行
- **安全中间件** — SecureToolExecutor 继承 ToolExecutor 全局拦截所有工具调用，不侵入 ReAct/Multi-Agent/RAG 核心逻辑
- **审计日志系统** — 工具调用、审批操作、拦截记录全量双写 SQLite + 日志文件，`/audit` 支持类型/工具/状态筛选与 Rich 表格查询
- **配置化管控** — `security.json` 自定义高危工具清单、危险命令黑名单、允许目录白名单，环境变量 `AHCCLI_HITL_ENABLED` 控制开关
- **REPL 命令** — `/hitl on|off|status` 开关 HITL（默认关闭）、`/audit` 审计查询与统计

### 多厂商大模型统一适配层
- **五大厂商原生支持** — DeepSeek、Qwen（通义千问）、智谱 GLM、Kimi（月之暗面）、阶跃 Step，仅对接云端 API
- **统一模型抽象** — BaseLLMModel 基类标准化推理请求、流式 SSE 解析、token 计数、前缀缓存接口，各厂商子类隔离差异化逻辑
- **超长上下文适配** — 适配百万级上下文窗口（qwen-long 10M），超窗自动裁剪（保留 system 前缀与最新输入），CJK 感知 token 估算
- **输入前缀缓存** — automatic 模式保持 system 前缀稳定命中服务端缓存，cache_control 模式（GLM）显式标注；按厂商专属 usage 字段统计缓存命中 token
- **配置化切换** — 仅修改 provider/model 字段（.env 或 `/model` 命令）即可无缝切换，接口地址/密钥按厂商目录自动推导，业务代码零改动
- **全链路复用** — ReAct、Plan-and-Execute、Multi-Agent、RAG 统一走 create_llm_model 构建入口，自动适配对应厂商 API 格式
- **用量统计** — UsageTracker 记录每次调用的 token 消耗与耗时，`/context` 输出会话级聚合统计
- **命令** — `/model` 切换、`/models` 模型列表、`/context` 上下文状态，Typer 子命令 `ahccli model list|current|use`

### 项目快照（增量备份与一键回滚）
- **自动快照钩子** — Plan 执行前、修改代码的高危调用成功执行且项目确有改动后（ReAct/Plan 全阶段，失败或无改动不触发）、Multi-Agent 各子阶段自动创建快照，钩子异常永不中断主流程
- **增量备份** — 每个快照保存全量 SHA-256 文件清单，仅物理存储相对上一快照变更的文件，不完整拷贝整个项目
- **一键回滚** — 沿快照时间链回溯恢复每个文件的对应版本，回滚前自动创建 pre_rollback 安全快照（可撤销）
- **存储规范** — 快照统一存放于 `./.AHCCLI/snapshots/`，按「时间戳_任务阶段」命名，不污染 Git 版本管理
- **安全兼容** — 快照扫描与回滚受路径守卫管控，不备份系统目录；回滚操作触发 HITL 人工确认审批
- **约束边界** — 仅管理本地项目源码文件，SQLite 记忆/索引数据库（.AHCCLI）与 .git 等目录一律排除
- **配置化开关** — `snapshot.json` 控制总开关/自动快照/保留数量/排除规则，环境变量 `AHCCLI_SNAPSHOT_ENABLED` 覆盖
- **命令** — `ahccli snapshot list|create|rollback|clean` Typer 子命令，REPL `/snapshot` 命令，Rich 渲染时间/任务描述/文件变更统计

### 网页搜索与抓取（Agent 联网能力）
- **两个联网内置工具** — `web_search` 网页综合搜索（标题/摘要/链接）、`web_fetch` 网页正文抓取（过滤广告/导航栏），均标记网络 IO 与并发安全
- **双搜索引擎自动降级** — DuckDuckGo 首选，不可达时自动降级 Bing，进程级粘性记住成功引擎，`search_provider` 可显式指定
- **统一网络层** — 全局 httpx 异步客户端复用（事件循环切换自动重建），统一超时/代理配置，滑动窗口请求限流防止 API 限流
- **URL 安全拦截** — UrlGuard 黑名单拦截恶意高危网站，协议白名单（仅 http/https）+ 内网地址防护（防 SSRF），路径守卫不干预网络工具
- **HITL 高危确认** — 高危域名（如短链接服务）抓取触发人工确认审批，全部网络请求记入审计日志
- **Agent 自动补充** — 用户提问缺少本地代码/历史记忆信息时，Agent 自动联网搜索并抓取页面注入推理上下文
- **约束边界** — 仅纯 HTTP 请求抓取（不接入浏览器自动化），网页内容仅临时存入短期记忆（不做 RAG 持久化）
- **命令** — `ahccli web search|fetch|audit` Typer 子命令，REPL `/web` 命令，web.json 配置化开关

### MCP 客户端（外部工具生态接入）
- **Anthropic 官方 MCP SDK** — 基于官方 mcp SDK（>=2.0）实现标准 MCP 基础规范，不开发浏览器相关 MCP 扩展
- **双传输连接** — stdio 本地 MCP 服务（启动命令 + 参数 + 环境变量）、Streamable HTTP 远程 MCP 服务（服务地址 + 鉴权请求头）
- **配置驱动** — mcp.json 配置服务启动命令、服务地址、鉴权参数、超时与重连策略，程序启动自动扫描加载全部启用的 MCP 服务，`AHCCLI_MCP_ENABLED` / `AHCCLI_MCP_FILE` 环境变量可覆盖
- **工具自动发现** — 连接时读取 MCP 服务暴露的外部工具清单，以 `mcp__{server}__{tool}` 命名规则注册进全局工具池，与本地内置工具统一调度
- **调用转发与接口封装** — Agent 调用 MCP 工具时经 SDK 透明转发并接收返回结果；另封装资源读取（Resource）与 Prompt 模板拉取基础接口
- **后台会话保持** — 独立后台事件循环线程持有长连接，会话跨 REPL 多次 asyncio.run() 持续存活；连接异常退避自动重连，调用失败自动断开重连并重试一次
- **安全兼容** — ReAct/Plan/Multi-Agent/HITL 对 MCP 工具与本地工具无差别适配，高危 MCP 工具（`high_risk_tools` 配置）同样触发人工审批，连接日志记入审计模块
- **权限隔离（v0.11.0）** — 服务级工具白名单（`allowed_tools`）注册阶段过滤；Multi-Agent 角色白名单支持 `mcp__{server}` 服务级条目，自动展开为该服务全部已注册工具
- **资源缓存（v0.11.0）** — MCP 远程资源与 Prompt 模板缓存至本地 SQLite（TTL 惰性过期），命中后不再发起网络请求；工具调用不进缓存
- **批量并行调用（v0.11.0）** — 一次并发调用多个 MCP 外部工具，Semaphore 限流 + gather 调度（复用 Plan 执行器并发模式），`batch_max_concurrent` 可调
- **心跳与容错（v0.11.0）** — 周期心跳探测（list_tools），连续失败达阈自动离线降级（不影响主程序），后续周期对离线服务崩溃自动重启；可单独禁用故障服务
- **高级配置（v0.11.0）** — 每服务独立 API 密钥（http 注入 Authorization / stdio 注入 MCP_API_KEY）、服务级超时、代理、自动快照开关（`snapshot_enabled`）
- **日志细化（v0.11.0）** — 审计日志区分本地内置/MCP 外部调用来源；MCP 调用以 Rich 品红分栏面板渲染服务/工具/参数详情
- **资源双通路与虚拟资源（v0.11.0 增量）** — McpResourceHub 双通路资源访问（本地虚拟资源优先 + 远程服务通道），进程内注册虚拟资源（provider 回调生成内容，无需真实服务）
- **被动通知路由（v0.11.0 增量）** — 会话 message_handler 聚合服务端通知（notifications/*）全局路由分发；监听资源变更事件，被动驱动本地缓存精准失效（精确 URI + 父级前缀）
- **@提及（v0.11.0 增量）** — `@服务:引用` 快速引用资源/工具/Prompt，发送前自动展开为实际内容注入查询，支持 REPL 输入补全
- **任务取消（v0.11.0 增量）** — CancellationToken 协作式取消贯穿 ReAct/Plan/Multi-Agent 安全点；Agent 后台线程运行，任务运行中按 ESC 或输入 `/cancel` 即可取消
- **Chrome 浏览器自动化（v0.12.0）** — 对接标准 Chrome DevTools MCP（stdio/HTTP 双协议），页面打开/元素点击/输入文本/页面截图/JS 执行/网络请求捕获统一适配并按操作类别渲染；浏览器工具全部纳入高危清单强制 HITL 审批（不受全局开关影响），访问 URL 同步经过项目 URL 黑名单校验；快照不备份浏览器状态，仅操作记录入审计；`--isolated` 模式每个会话独立浏览器上下文（多会话隔离基础）
- **CDP 浏览器会话池（v0.13.0）** — 常驻 chrome-devtools-mcp 连接会话池（`browser_pool_enabled` 启用）：复用浏览器实例避免重复启动、多并发会话隔离、空闲保活巡检与超时自动回收、异常会话自动销毁重建、最大并发排队与获取超时、可选浏览器内存占用告警；上层 Agent/工具调用逻辑零改动透明分发至池；会话创建/销毁写入审计日志；配套浏览器状态缓存（`/chrome state save|restore`）将 Cookie/localStorage 持久化至本地文件，重启后可恢复登录会话（默认关闭，兼容 v0.12.x 单会话行为）
- **浏览器共享模式（v0.13.2）** — isolated/shared 双运行模式（`/browser status` 查询）：默认隔离模式独立浏览器实例；`/browser connect [url]` 切换共享模式复用本机已启动的远程调试 Chrome 实例（底层 chrome-devtools-mcp 原生 `--browserUrl`/`--autoConnect`，Chrome 144+ 在 chrome://inspect/#remote-debugging 勾选 Allow remote debugging 后可免端口自动发现），直接继承已有登录会话；未检测到远程调试时自动回退隔离模式并输出开启提示；`browser_login_auto_switch` 开启后检测到需要登录自动尝试切换共享模式重试一次（默认关闭），模式切换均写入审计日志（v0.13.3 已适配新版 chrome-devtools-mcp 的 pageId 必填要求：`/chrome state save|restore` 导航报缺 pageId 时自动回退 `new_page` 打开并解析选中页编号，后续脚本执行/刷新均携带 pageId，旧版服务端行为不变）
- **命令** — `ahccli mcp status|restart|logs|disable|enable|call|batch|cache|resources|prompts` 与 `ahccli chrome-mcp status|start|stop|restart|pages|do|pool|state`、`ahccli browser status|connect|disconnect` Typer 子命令，REPL `/mcp`、`/chrome`、`/browser` 与 `/cancel` 命令，mcp.json 配置化开关

### 可扩展 Skill 技能系统
- **SKILL.md 技能规范** — 元数据头（零依赖 YAML 子集 / JSON 双形态）+ Prompt 正文；一个技能绑定一组本地工具 / MCP 工具、专属 Prompt 模板（`{query}` 占位符运行时渲染）与执行前置校验规则（file_exists / dir_exists / env / tool_available）
- **全局技能仓库** — 内置技能随包发布，本地自定义与第三方 MCP 配套技能安装至 `./.AHCCLI/skills/<name>/SKILL.md`；同名自定义覆盖内置，单个技能解析失败仅记入错误清单不阻断其余技能
- **Agent 自动技能匹配** — jieba 分词加权词元重叠评分（关键词/名称命中 ×3、描述命中 ×1），评分 ≥0.5 自动加载并注入会话上下文，≥0.25 以提示块推荐由 Agent 自行加载，零网络零 LLM 确定性离线匹配，任何异常降级不阻断主流程
- **两级懒加载** — 启动仅扫描预缓存全部技能元数据（不读正文，降低启动耗时与内存占用）；Prompt 正文首次 `load_skill` 时才读盘并缓存，`/skill reload` 热重载配置与资源无需重启
- **技能生命周期** — 安装/卸载/启用/禁用（`skills.json` 持久化，即时生效），禁用技能对匹配检索与加载完全不可见、技能间互不干扰；支持为多 Agent 分配独立技能白名单（`RoleConfig.skill_whitelist`，与工具白名单同构）
- **集成现有能力** — 声明 `hitl_required` 的技能加载前走 HITL 人工审批，声明 `auto_snapshot` 的技能加载前自动创建项目快照，加载/拦截/启停/装卸全生命周期写审计日志；技能执行中间可直接调用 RAG（search_code）、记忆（search_memory）与浏览器 MCP（mcp__chrome-devtools__*）
- **per-session 会话上下文** — SkillContextBuffer 按会话隔离缓冲已加载技能，自动注入下一轮用户消息（注入后清空），保证单会话技能状态连续、多会话相互隔离
- **CLI 交互** — REPL `/skill`（≡ list）`/skill list|show|on|off|install|uninstall|test|reload|help` 与 `ahccli skill` Typer 子命令组；内置 code-review / commit-message / web-research 三个示例技能模板；作为上层封装不重构底层 Tool/MCP/浏览器核心代码

### Runtime HTTP 开放 API（v0.15.0）
- **异步 HTTP 服务** — Starlette + uvicorn 异步栈，服务运行于独立线程的独立事件循环，不阻塞终端 CLI
- **会话接口** — 创建对话会话、多轮历史自动注入下一轮推理、同步问答返回完整推理事件轨迹、SSE 流式输出推理过程（含心跳与终止帧）
- **任务接口** — 长耗时 Plan 任务入后台任务队列执行（与 `ahccli plan run` 同源：规划 → 自动快照 → 拓扑并发执行），API 轮询进度、协作式终止（CancellationToken 透传）
- **资源接口** — 记忆检索/保存、RAG 语义代码查询、快照创建/列表/回滚（HITL 审批结果同步至响应体）、技能列表/加载（返回技能 Prompt）
- **MCP/浏览器接口** — MCP 服务状态/重启/禁用/启用，MCP 工具与浏览器自动化调用一律经 SecureToolExecutor 执行（命令拦截/路径守卫/HITL 审批/审计与终端完全同一链路）
- **API 密钥鉴权** — `Authorization: Bearer` / `X-API-Key` 双请求头，hmac.compare_digest 恒定时间比对，密钥未配置拒绝启动（不存在无鉴权运行模式）
- **统一审计与流量展示** — 每个 API 请求写入全局审计日志（event_type=api_call），双运行模式下 Rich 终端实时打印请求流量（方法/路径/状态码）
- **双运行模式** — `ahccli runtime start` 前台独占运行；REPL 内 `/runtime start|stop|status` 后台启动实现 CLI + API 双运行
- **命令** — `ahccli runtime start|status` Typer 子命令，REPL `/runtime` 命令，环境变量自定义监听地址/端口/访问密钥/并发上限，接口文档见 `docs/runtime-api.md`

### 通用
- **工具抽象框架** — 通用 `Tool` 基类，预留名称、描述、入参 Schema、只读标记、并发安全标记、网络 IO 标记字段，扩展简单
- **15 个内置工具 + MCP 动态工具** — 时间查询、回声、文件读写（支持分段）、目录列表、文件名 glob 搜索、代码关键字/正则搜索、Shell 命令执行、项目创建、记忆搜索、记忆保存、代码搜索、网页搜索、网页抓取、技能加载（load_skill）；另有 MCP 外部工具以 `mcp__{server}__{tool}` 命名动态注册
- **Typer CLI 框架** — 支持单次查询和交互式 REPL 两种运行模式
- **prompt-toolkit** — 交互模式支持上下箭头历史浏览
- **.env 配置文件** — 支持从 `.env` 文件加载配置，优先级：命令行参数 > 环境变量 > .env 文件 > 内置默认值

## 版本信息

| 版本号 | 发布日期 | 说明 |
|--------|----------|------|
| **v0.15.0** | 2026-08-28 | **Phase 15 — Runtime HTTP 开放 API**：新增 runtime/api 子包（RuntimeConfig 配置/ApiKeyAuthMiddleware API 密钥鉴权中间件/SessionManager 会话管理/TaskQueue 后台任务队列/EventRenderer 事件双写渲染器/全套 RESTful 路由/RuntimeServer 服务主程序七大组件），异步 HTTP 服务供外部程序调用全部 Agent 能力——会话接口（创建会话/多轮历史注入/同步问答返回推理事件轨迹/SSE 流式输出推理过程）、任务接口（Plan 任务后台执行/进度轮询/协作终止）、资源接口（记忆检索保存/RAG 代码查询/快照创建回滚/技能加载）、MCP 与浏览器接口（服务管理 + 工具调用经 SecureToolExecutor 同一安全链路）；后台任务队列 asyncio 信号量并发限流 + CancellationToken 协作式取消透传；API 密钥鉴权（hmac 恒定时间比对，密钥缺失拒绝启动），全部 API 请求写入全局审计日志（event_type=api_call）并 Rich 终端实时展示流量；`ahccli runtime start` 前台独占与 REPL `/runtime start` CLI + API 双运行两种启动模式，环境变量自定义监听地址/端口/密钥/并发上限；API 完全复用 ReAct/Plan/安全防线/MCP/快照/技能核心模块，零重复业务逻辑，接口文档 docs/runtime-api.md，1159 项单元测试 |
| **v0.14.1** | 2026-08-26 | **技能卸载修复**：修复 `/skill uninstall` 提示“已卸载”但 `/skill` 列表仍显示该技能的问题——旧实现以 `ignore_errors=True` 删除技能目录，Windows 上文件被占用或只读导致删除静默失败，重扫后技能原样复现；现卸载改用强制删除（只读文件自动去除只读属性后重试），删除失败或目录仍存在时抛出明确错误提示（不修改启用状态、不虚报成功），删除成功后重扫并校验同名技能不再以自定义来源残留（同名内置技能正常回退），1100 项单元测试 |
| **v0.14.0** | 2026-08-26 | **Phase 14 — 可扩展 Skill 技能系统**：新增 skill 模块（SKILL.md 规范解析加载器/技能注册表与生命周期/自动技能匹配检索器/load_skill 工具与 per-session SkillContextBuffer/skill Typer 子命令组与 REPL /skill 命令六大组件）——技能绑定一组本地工具 + MCP 工具、专属 Prompt 模板（{query} 占位符渲染）与执行前置校验规则（file_exists/dir_exists/env/tool_available）；全局技能仓库：内置技能随包发布 + 本地自定义/第三方 MCP 配套技能安装至 ./.AHCCLI/skills/<name>/SKILL.md（同名自定义覆盖内置）；启动仅预缓存技能元数据，Prompt 正文经 load_skill 按需懒加载并缓存，/skill reload 热重载无需重启；Agent 按需求语义自动匹配（jieba 加权词元评分：≥0.5 自动预加载注入会话上下文，≥0.25 提示块推荐，异常一律降级）；生命周期：安装/卸载/启用/禁用（skills.json 持久化、即时生效）+ 技能隔离 + 多 Agent 独立技能白名单（RoleConfig.skill_whitelist）；集成现有能力：声明标记的技能加载前触发 HITL 审批与自动快照，装卸/启停/加载/拦截全链路审计，技能执行中间可调用 RAG/记忆/浏览器 MCP；内置 code-review/commit-message/web-research 三个示例技能；约束：仅作上层封装不重构底层 Tool/MCP/浏览器核心，1098 项单元测试 |
| **v0.13.3** | 2026-08-26 | **状态缓存新版适配修复**：修复 `/chrome state save|restore` 在最新版 chrome-devtools-mcp 上报 `MCP error -32602: Required at pageId` 无法打开页面的问题——新版服务端的 navigate_page/evaluate_script 强制要求 `pageId` 参数；现状态缓存导航报缺 pageId 时自动回退 `new_page` 打开目标页面并从页面清单（`N: 标题 (url) [selected]`）解析选中页编号（兜底 `list_pages`），后续导出/回注/刷新均携带 pageId（刷新用 type=url 形态）；旧版服务端仍按仅 url 导航，行为不变，1034 项单元测试 |
| **v0.13.2** | 2026-08-25 | **浏览器共享模式（CDP 会话复用）**：补齐 Phase 13 遗留功能，基于 chrome-devtools-mcp 原生 `--browserUrl`/`--autoConnect` 参数对接已运行的 Chrome 实例——`/browser status` 查询当前运行模式（isolated 隔离/shared 共享），`/browser connect [url]` 切换共享模式直接复用本机登录会话（缺省 autoConnect 自动发现，Chrome 144+ 在 chrome://inspect/#remote-debugging 勾选 Allow remote debugging 后可用；或以 `--remote-debugging-port` 启动后指定调试地址），`/browser disconnect` 切回隔离模式；切换以 list_pages 探测真实可用性，未开启远程调试时自动回退隔离模式并输出开启提示；`browser_login_auto_switch`（默认关闭）开启后优先隔离模式执行，检测到需要登录自动切换共享模式重试一次；模式切换均写入审计日志，1029 项单元测试 |
| **v0.13.1** | 2026-08-25 | **登录态恢复修复**：修复 `/chrome state restore` 恢复后站点仍显示未登录的问题——保存时改用 `cookieStore` API 捕获 Cookie 的 domain/path/expires 属性（旧格式仅 name/value，根域 Cookie 被错误地以 host-only 回注）；恢复时按原始属性回注并在注入后自动刷新页面让服务端重新渲染（旧实现不刷新，页面停留在未登录态）；新增 `browser_profile_dir` 配置：指定后 Chrome 使用持久化用户数据目录（`--userDataDir`），登录态含 HttpOnly 会话票据跨重启完整保留（临时档案下 JS 无法恢复），997 项单元测试 |
| **v0.13.0** | 2026-08-24 | **CDP 浏览器会话池**：新增常驻 CDP 连接会话池（mcp.json `browser_pool_enabled` 启用，默认关闭）——复用浏览器实例避免每次自动化重启浏览器、多并发会话隔离（`browser_pool_max_sessions` 上限，超出排队等待）、空闲保活巡检与超时自动回收、异常会话自动销毁重建（创建/销毁均入审计）、可选浏览器内存占用告警（`browser_pool_memory_limit_mb`）；上层 Agent/工具调用透明分发至池零改动；新增浏览器状态缓存（`/chrome state save|restore|list|clear`）将 Cookie/localStorage 持久化至本地，重启后可恢复登录会话，986 项单元测试 |
| **v0.12.3** | 2026-08-24 | **浏览器截图保存修复**：修复 take_screenshot 带 filePath 报 “Access denied ... not within any of the configured workspace roots”、不带参数时截图（ImageContent）被丢弃无法查看保存的问题——MCP 会话现通过 roots 能力将当前工作目录声明为工作区根（list_roots_callback 动态跟随 cwd），浏览器文件写入类工具据此获得项目目录写入权限；同时 MCP 结果格式化对图片内容块解码落盘（mcp_image_时间戳.png）并在结果中回传保存路径，941 项单元测试 |
| **v0.12.2** | 2026-08-24 | **模型目录修复与默认模型升级**：修复可用模型列表（/models）未收录智谱最新旗舰 `glm-4.7` 的问题——配置该模型时 /model 上下文窗口显示“未知 tokens”且无法自动裁剪超窗上下文；现将 `glm-4.7`（200K 上下文）纳入厂商目录，并将项目默认模型由 `glm-4.6v` 升级为 `glm-4.7`（同步更新 .env/.env.example 与双语文档），938 项单元测试 |
| **v0.12.1** | 2026-08-24 | **Phase 12 缺陷修复**：修复 `/chrome start`（及 /mcp enable）对已连接服务重复建连的问题——重复进入 stdio/HTTP 连接上下文会覆盖旧会话的清理句柄，泄漏的异步生成器被 GC 终结时在不同任务中退出 anyio 取消作用域，抛出 `Attempted to exit cancel scope in a different task` 异常并泄漏浏览器子进程；现连接幂等：已连接服务复用现有会话（_connect_server 幂等守卫 + /chrome start 已在运行时直接短路提示），937 项单元测试 |
| **v0.12.0** | 2026-08-21 | **Phase 12 — Chrome DevTools MCP 浏览器接入**：新增 mcp/browser 子包（ChromeMcpToolAdapter 专用适配器强制非只读 + 操作类别标签、BrowserToolGuard 浏览器工具权限拦截器、Rich 青色可视化渲染、chrome-mcp 管理子命令与 REPL /chrome），对接标准 Chrome DevTools MCP（stdio/HTTP 双协议，npx chrome-devtools-mcp 默认配置自动注入），页面打开/元素点击/输入文本/页面截图/JS 执行/网络请求捕获统一适配；安全管控：浏览器工具全部纳入高危清单强制 HITL 人工审批（不受全局 hitl_enabled 影响，先于审批执行 URL 黑名单校验），访问 URL 同步经过项目 URL 黑名单（协议白名单 + 正则黑名单）；调度兼容：ReAct/Multi-Agent 自动调用浏览器 MCP 完成网页自动化，快照机制不备份浏览器状态（仅操作记录入审计日志）；约束：不实现 CDP 会话复用（--isolated 每次操作独立上下文），仅对接标准 CDP MCP 不自研浏览器控制逻辑，935 项单元测试 |
| **v0.11.0** | 2026-08-21 | **Phase 11 — MCP 高级扩展**：新增 MCP 缓存管理器（资源/Prompt 缓存至本地 SQLite，TTL 惰性过期，仅缓存成功结果）、心跳检测组件（周期 list_tools 探测，连续失败达阈离线降级 + 后续周期崩溃自动重启，单独禁用故障服务不影响主程序）、多服务权限隔离模块（服务级 allowed_tools 白名单注册过滤 + Multi-Agent 角色白名单支持 mcp__{server} 服务级条目展开）、批量并行调用（Semaphore 限流 + gather，复用 Plan 执行器并发模式）；配置增强：每服务独立 API 密钥/调用与连接超时/代理/自动快照开关（snapshot_enabled），全局心跳间隔与阈值、缓存开关与 TTL、批量并发数；日志细化：审计区分本地内置/MCP 外部调用来源，MCP 调用 Rich 品红分栏面板渲染服务/工具/参数详情；新增 /mcp call\|batch\|cache 命令，不接入 Chrome 浏览器 MCP/CDP，836 项单元测试 |
| **v0.10.1** | 2026-08-20 | **Phase 10 缺陷修复**：修复 Windows 下 stdio MCP 服务启动命令为批处理/脚本（如 npx/npx.cmd，含 which 解析到无扩展名 git-bash 脚本的场景）时 CreateProcess 报 `WinError 193` 连接失败的问题（启动命令规范化：.cmd/.bat 自动改写为 `cmd /c` 执行，无扩展名命令按 PATHEXT 回退查找 .exe/.cmd 同名可执行文件）；修复工作区配置真实 mcp.json 时工具数断言测试被动态 MCP 工具污染的问题（测试隔离 MCP 开关），795 项单元测试 |
| **v0.10.0** | 2026-08-20 | **Phase 10 — MCP 基础客户端能力**：新增 mcp 模块（McpConfig 配置解析/McpClientManager 客户端管理器/McpToolAdapter 工具注册适配器/mcp 系列 Typer 子命令与 /mcp REPL 命令四大组件），接入 Anthropic 官方 MCP SDK（mcp>=2.0），stdio 本地 + Streamable HTTP 远程双传输，mcp.json 配置驱动（启动命令/服务地址/鉴权请求头/超时重连参数）启动自动扫描连接全部 MCP 服务，外部工具自动发现并以 mcp__{server}__{tool} 命名注册进全局工具池统一调度，SDK 调用转发 + 资源读取 + Prompt 模板拉取接口封装，后台事件循环线程会话持久化 + 连接异常退避自动重连 + 调用失败自动重连重试，ReAct/Plan/Multi-Agent/HITL 无差别适配且高危 MCP 工具同样触发人工审批，连接日志记入审计模块，仅标准 MCP 基础规范不开发浏览器相关扩展，mcp.json 配置化开关，788 项单元测试 |
| **v0.9.2** | 2026-08-19 | **Phase 9 展示缺陷修复**：修复搜索结果表格链接列被 Rich 省略号截断导致复制后访问 404 的问题（链接列改为 fold 换行完整展示），742 项单元测试 |
| **v0.9.1** | 2026-08-19 | **Phase 9 缺陷修复**：web_search 新增 Bing 备用搜索引擎（DuckDuckGo 不可达时自动降级，进程级粘性优选，`search_provider` 配置项显式指定）；修复全局 WebClient 跨 asyncio.run() 事件循环复用旧连接导致的 `Event loop is closed` 崩溃（事件循环切换自动重建客户端与限流器）；修复 httpx 超时异常 str() 为空导致的空错误提示（超时/错误提示补全异常类型与代理配置指引），741 项单元测试 |
| **v0.9.0** | 2026-08-19 | **Phase 9 — 网页搜索与抓取联网能力**：新增 web 模块（WebConfig 配置解析/WebClient 全局 httpx 客户端 + 滑动窗口限流/UrlGuard URL 安全拦截器/HTML 正文提取与搜索结果解析/web_search 与 web_fetch 双内置工具/web 系列 Typer 子命令六大组件），Agent 缺少本地信息时自动联网搜索补充，统一超时/代理/请求限流，URL 黑名单拦截恶意高危网站 + 内网地址防护（防 SSRF），高危域名抓取触发 HITL 人工确认，全部网络请求记入审计日志，网页内容仅临时存入短期记忆不做 RAG 持久化，仅纯 HTTP 抓取不接入浏览器自动化，web.json 配置化开关，733 项单元测试 |
| **v0.8.0** | 2026-08-19 | **Phase 8 — 项目快照 Snapshot 模块**：新增 snapshot 模块（SnapshotConfig 配置解析/SHA-256 文件差异扫描引擎/SnapshotManager 快照管理器/SnapshotHooks 自动快照钩子/ snapshot 系列 Typer 子命令五大组件），Plan 执行前、修改代码的高危调用成功执行且确有改动后（ReAct/Plan 全阶段）、Multi-Agent 子阶段自动快照，全量清单 + 增量物理副本存储（不完整拷贝项目），快照链回溯一键回滚（自动 pre_rollback 安全快照），中间快照删除副本自动合并，过期快照清理，快照路径受路径守卫管控、回滚触发 HITL 人工审批，仅管理源码文件不备份 SQLite 数据库，snapshot.json 配置化开关，不污染 Git 版本管理，675 项单元测试 |
| **v0.7.0** | 2026-08-18 | **Phase 7 — 多厂商大模型统一适配层**：新增 providers 模块（BaseLLMModel 统一抽象/OpenAICompatibleModel 通用实现/五大厂商子类/厂商目录/配置解析/注册工厂/UsageTracker 用量追踪七大组件），原生支持 DeepSeek、Qwen、智谱 GLM、Kimi、阶跃 Step 五大厂商，百万级超长上下文适配与超窗自动裁剪，输入前缀缓存（automatic/cache_control 双模式），provider/model 配置化无缝切换，全链路（ReAct/Plan/Multi-Agent/RAG）复用统一接口，`/model` `/models` `/context` 交互命令与 `ahccli model` Typer 子命令，621 项单元测试 |
| **v0.6.0** | 2026-08-18 | **Phase 6 — HITL 人机交互人工审批安全模块**：新增 security 模块（SecurityConfig 配置解析/CommandInterceptor 命令拦截器/PathGuard 路径守卫/HitlApprover 审批组件/AuditLogger 审计日志/SecureToolExecutor 安全中间件六大组件）、三层安全防线全局拦截、prompt-toolkit 交互式确认面板、SQLite + 日志文件双写审计、`/hitl on|off|status` 与 `/audit` 交互命令、security.json 配置化管控，564 项单元测试 |
| **v0.5.0** | 2026-08-17 | **Phase 5 — Multi-Agent 多智能体编排**：新增 team 模块（AgentMessage/AgentRole/SubAgent/AgentOrchestrator/MessageBus/ToolRegistry 六大组件）、Planner→Worker→Reviewer 三段编排、并行子任务批量执行、异常重试审核解析、httpx 异步消息总线、工具白名单权限隔离、三层缓冲流式渲染、`/team` 交互命令、Rich 进度可视化，484 项单元测试 |
| **v0.4.0** | 2026-08-13 | **Phase 4 — RAG 代码检索**：新增 RAG 模块（Python AST 三级分片 + 多语言滑动窗口、SQLite BLOB 向量存储、三路加权混合检索、代码关系图谱）、`search_code` Agent 工具、`glob_files`/`grep_code` 工具、`read_file` 分段读取、`/index` `/search` `/graph` `/rag on|off` REPL 命令、智能代码检索策略、MUST/NEVER 强制检索提示词、jieba 分词、API 降级容错、增量扫描，433 项单元测试 |
| **v0.3.0** | 2026-08-12 | **Phase 3 — 三层记忆系统**：新增记忆模块（短期缓冲 + 长期 SQLite + 关键词索引）、`search_memory` 和 `save_memory` Agent 工具、`/memory` 和 `/save` REPL 命令、prompt-toolkit 历史浏览、数据库自修复，252 项单元测试 |
| **v0.2.0** | 2026-08-12 | **Phase 2 — Plan-and-Execute 阶段**：新增 Plan-and-Execute 模式（LLM 任务分解、拓扑排序、并发执行、E/S/C 审查）、7 个内置工具（文件读写/Shell/项目创建）、`/plan` 交互命令、OS 感知、失败重试与错误反馈纠正、帮助系统，167 项单元测试 |
| **v0.1.1** | 2026-08-11 | **配置管理**：新增 `.env` 配置文件支持，集中化配置模块 (`config.py`)，支持 `.env` 文件自动发现与加载，配置优先级链：CLI > 环境变量 > .env > 默认值 |
| **v0.1.0** | 2026-08-11 | **Phase 1 — ReAct & Tool Call 基础阶段**：完成 ReAct 推理循环、Tool 抽象基类、LLM 流式请求封装、ToolExecutor 工具调度、Rich 终端渲染、Typer CLI 入口框架，附带 42 项单元测试 |

## 技术栈

| 组件 | 技术选型 |
|------|----------|
| 语言 | Python 3.11+ |
| 异步网络 | httpx (AsyncClient) |
| MCP 协议 | mcp (Anthropic 官方 Python SDK) |
| CLI 框架 | Typer |
| 终端渲染 | Rich |
| 数据模型 | Pydantic v2 |
| 配置管理 | python-dotenv (.env 文件) |
| 记忆存储 | SQLite (stdlib) |
| 代码分词 | jieba |
| 交互输入 | prompt-toolkit |
| HTTP 服务 | starlette + uvicorn（Runtime API） |
| 包管理 | uv |
| 构建工具 | hatchling |
| 默认模型 | 智谱 GLM-4.7 (`https://open.bigmodel.cn/api/paas/v4`) |
| 测试框架 | pytest + pytest-asyncio |

## 项目结构

```
ahccli-python/
├── pyproject.toml              # 项目配置 & 依赖声明
├── .env.example                # 配置文件模板（复制为 .env 使用）
├── snapshot.json               # 项目快照策略配置（Phase 8）
├── web.json                    # 网页联网策略配置（Phase 9）
├── mcp.json                    # MCP 外部服务配置（Phase 10）
├── mcp.example.json            # MCP 配置示例（stdio + http）
├── src/ahccli/
│   ├── __init__.py             # 包入口 & 版本号
│   ├── __main__.py             # python -m ahccli 入口
│   ├── cli.py                  # Typer CLI 命令定义（含 /plan 交互命令）
│   ├── config.py               # 集中化配置管理 (.env 加载)
│   ├── models.py               # 数据模型 (Message, ToolCall, LLMResponse)
│   ├── tool.py                 # Tool 抽象基类
│   ├── tool_executor.py        # 工具注册 & 调度执行器
│   ├── llm.py                  # LLM 异步客户端 & SSE 流式解析
│   ├── agent.py                # ReAct 推理循环控制器（含 OS 感知）
│   ├── renderer.py             # Rich 终端可视化渲染器
│   ├── plan/                   # Plan-and-Execute 模块
│   │   ├── __init__.py
│   │   ├── models.py           # 任务/计划数据模型 & 状态管理
│   │   ├── planner.py          # LLM 任务规划器
│   │   ├── executor.py         # 拓扑排序 & 并发任务执行器
│   │   └── renderer.py         # 计划 Rich 可视化渲染器
│   ├── memory/                 # 三层记忆系统模块
│   │   ├── __init__.py
│   │   ├── db.py               # SQLite 初始化 & 自修复
│   │   ├── manager.py          # 三层 MemoryManager 单例
│   │   ├── memory_tool.py      # search_memory & save_memory 工具
│   │   └── commands.py         # /memory & /save REPL 命令
│   ├── cli_parser.py           # REPL 交互命令解析器 (CliCommandParser)
│   ├── rag/                    # RAG 代码检索模块
│   │   ├── __init__.py
│   │   ├── config.py           # RAG 配置管理
│   │   ├── db.py               # RAG SQLite 初始化
│   │   ├── vectors.py          # 向量序列化 & 余弦相似度
│   │   ├── embedding.py        # Qwen Embedding 客户端 & 降级
│   │   ├── languages.py        # 11 种语言检测
│   │   ├── python_parser.py    # Python AST 三级解析器
│   │   ├── generic_parser.py   # 滑动窗口分片器
│   │   ├── chunker.py          # 索引编排器
│   │   ├── relationships.py    # 代码关系图谱
│   │   ├── search_engine.py    # 三路混合检索引擎
│   │   ├── prompt.py           # MUST/NEVER 提示词
│   │   ├── code_tool.py        # search_code 工具
│   │   └── commands.py         # /index & /search & /graph 命令
│   ├── team/                   # Multi-Agent 多智能体编排模块
│   │   ├── __init__.py
│   │   ├── message.py          # AgentMessage 消息模型
│   │   ├── roles.py            # AgentRole 角色 & RoleRegistry
│   │   ├── base.py             # BaseAgent 抽象基类 & 独立记忆
│   │   ├── sub_agent.py        # SubAgent 子智能体
│   │   ├── bus.py              # httpx 异步消息总线 MessageBus
│   │   ├── orchestrator.py     # AgentOrchestrator 三段编排器
│   │   ├── tool_registry.py    # ToolRegistry 工具白名单注册中心
│   │   ├── renderer.py         # TeamRenderer 进度可视化
│   │   ├── factory.py          # build_team 团队装配工厂
│   │   └── commands.py         # /team 命令处理器
│   ├── security/               # 三层安全防线 & HITL 人工审批模块
│   │   ├── __init__.py
│   │   ├── config.py           # SecurityConfig 配置 & security.json 解析
│   │   ├── interceptor.py      # 防线 1：CommandInterceptor 危险命令拦截
│   │   ├── path_guard.py       # 防线 2：PathGuard 路径守卫
│   │   ├── hitl.py             # 防线 3：HitlApprover 人工审批组件
│   │   ├── audit.py            # AuditLogger 审计日志（SQLite + 日志文件）
│   │   ├── middleware.py       # SecureToolExecutor 安全中间件
│   │   └── commands.py         # /hitl & /audit 命令 & 运行时单例
│   ├── providers/              # 多厂商大模型统一适配层
│   │   ├── __init__.py
│   │   ├── base.py             # BaseLLMModel 抽象基类 & OpenAI 兼容实现（SSE/token/前缀缓存）
│   │   ├── catalog.py          # 五大厂商目录（接口地址/模型清单/上下文窗口）
│   │   ├── vendors.py          # DeepSeek/Qwen/GLM/Kimi/Step 厂商子类
│   │   ├── config.py           # provider/model/key/url/timeout/temperature 配置解析
│   │   ├── registry.py         # create_llm_model 工厂 & 运行时切换单例
│   │   ├── usage_tracker.py    # UsageTracker token 消耗与耗时统计
│   │   └── commands.py         # /model & /models & /context 命令 & Typer 子命令
│   ├── snapshot/               # 项目快照模块（增量备份与一键回滚）
│   │   ├── __init__.py
│   │   ├── config.py           # SnapshotConfig 配置 & snapshot.json 解析
│   │   ├── diff.py             # SHA-256 文件差异扫描引擎
│   │   ├── manager.py          # SnapshotManager 创建/列表/回滚/删除/清理
│   │   ├── hooks.py            # SnapshotHooks 自动快照钩子中间件
│   │   └── commands.py         # snapshot Typer 子命令 & /snapshot REPL 命令
│   ├── web/                    # 网页搜索与抓取模块（Agent 联网能力）
│   │   ├── __init__.py
│   │   ├── config.py           # WebConfig 配置 & web.json 解析
│   │   ├── client.py           # 全局 httpx 客户端 & 滑动窗口限流器
│   │   ├── guard.py            # UrlGuard URL 黑名单拦截 & 高危域名识别
│   │   ├── parser.py           # HTML 正文提取 & 搜索结果解析
│   │   ├── tools.py            # WebSearchTool / WebFetchTool 联网工具
│   │   └── commands.py         # web Typer 子命令 & /web REPL 命令
│   ├── mcp/                    # MCP 外部服务客户端模块（Phase 10/11/12）
│   │   ├── __init__.py
│   │   ├── config.py           # McpConfig 配置 & mcp.json 解析（含 v0.11.0 高级字段）
│   │   ├── client_manager.py   # McpClientManager 客户端管理器（stdio/HTTP 双传输 + 自动重连 + 缓存/批量/心跳接入）
│   │   ├── tool_adapter.py     # McpToolAdapter 工具注册适配器（mcp__{server}__{tool}）
│   │   ├── cache_store.py      # McpCacheStore 资源/Prompt SQLite 缓存管理器（v0.11.0）
│   │   ├── heartbeat.py        # McpHeartbeatMonitor 心跳检测/离线降级/崩溃自动重启（v0.11.0）
│   │   ├── permissions.py      # 多服务权限隔离：工具白名单过滤与服务级条目展开（v0.11.0）
│   │   ├── notifications.py    # NotificationRouter 服务端通知全局路由（v0.11.0 增量）
│   │   ├── resources.py        # McpResourceHub 双通路/虚拟资源与事件驱动缓存失效（v0.11.0 增量）
│   │   ├── mention.py          # @提及解析/展开/补全（v0.11.0 增量）
│   │   ├── browser/            # Chrome DevTools MCP 浏览器接入子包（v0.12.0）
│   │   │   ├── __init__.py
│   │   │   ├── adapter.py      # ChromeMcpToolAdapter 专用适配器 & 工具操作类别归类
│   │   │   ├── guard.py        # BrowserToolGuard URL 黑名单校验 & 高危工具同步
│   │   │   ├── renderer.py     # 浏览器操作 Rich 青色可视化渲染
│   │   │   ├── session_pool.py # CDP 会话池：常驻连接复用/排队/保活回收/内存告警（v0.13.0）
│   │   │   ├── state_cache.py  # 浏览器状态缓存：Cookie/localStorage 持久化（v0.13.0）
│   │   │   ├── share.py        # 共享模式会话复用：isolated/shared 切换/探测降级/登录自动切换（v0.13.2）
│   │   │   └── commands.py     # chrome-mcp/browser Typer 子命令 & /chrome /browser REPL 命令
│   │   └── commands.py         # mcp Typer 子命令 & /mcp REPL 命令 & 管理器单例
│   ├── skill/                  # 可扩展 Skill 技能系统模块（Phase 14）
│   │   ├── __init__.py
│   │   ├── config.py           # SKILL.md 规范解析 & 执行前置校验规则
│   │   ├── loader.py           # 技能扫描预缓存 & 正文懒加载（内置/自定义双源）
│   │   ├── registry.py         # SkillManager 注册表 & 生命周期（skills.json 状态持久化）
│   │   ├── matcher.py          # Agent 自动技能匹配（加权词元重叠评分）
│   │   ├── context.py          # SkillContextBuffer per-session 会话上下文注入
│   │   ├── tool.py             # load_skill 工具 & 查询级技能管道（自动匹配/预加载/推荐）
│   │   ├── commands.py         # skill Typer 子命令 & /skill REPL 命令
│   │   └── builtin_skills/     # 内置示例技能（code-review/commit-message/web-research）
│   ├── runtime/
│   │   ├── __init__.py
│   │   ├── cancellation.py     # CancellationToken 取消令牌与后台可取消执行（ESC//cancel；v0.11.0 增量）
│   │   └── api/                # Runtime HTTP 开放 API（Phase 15）
│   │       ├── __init__.py
│   │       ├── config.py       # RuntimeConfig 配置（地址/端口/密钥/并发上限）
│   │       ├── auth.py         # ApiKeyAuthMiddleware API 密钥鉴权中间件 + 审计流量展示
│   │       ├── sessions.py     # SessionManager 多轮对话会话管理
│   │       ├── queue.py        # TaskQueue 后台任务队列（信号量限流/协作式取消）
│   │       ├── renderer.py     # EventRenderer 推理事件双写（Rich 终端 + SSE 事件队列）
│   │       ├── routes.py       # 全套 RESTful 路由（会话/任务/资源/MCP/浏览器/SSE）
│   │       └── server.py       # RuntimeServer 服务主程序（前台/双运行双模式启动）
│   └── tools/
│       ├── __init__.py
│       ├── builtin.py          # 内置工具 (GetCurrentTime, Echo)
│       ├── file_tools.py       # 文件工具 (ReadFile, WriteFile, ListDir)
│       ├── shell_tool.py       # Shell 命令执行工具（OS 感知）
│       └── project_tool.py     # 项目创建工具
└── tests/                      # 单元测试（1159 项）
    ├── test_agent.py
    ├── test_cli_help.py
    ├── test_config.py
    ├── test_file_tools.py
    ├── test_llm.py
    ├── test_mcp.py
    ├── test_mcp_advanced.py
    ├── test_mcp_browser.py
    ├── test_mcp_extensions.py
    ├── test_memory_commands.py
    ├── test_memory_db.py
    ├── test_memory_manager.py
    ├── test_memory_tool.py
    ├── test_models.py
    ├── test_plan_executor.py
    ├── test_plan_flow.py
    ├── test_plan_models.py
    ├── test_plan_planner.py
    ├── test_project_tool.py
    ├── test_providers.py
    ├── test_runtime_api.py
    ├── test_security.py
    ├── test_shell_tool.py
    ├── test_skill.py
    ├── test_snapshot.py
    ├── test_team.py
    ├── test_tool.py
    ├── test_tool_executor.py
    └── test_web.py
```

## 安装

### 前置要求

- Python 3.11 或更高版本
- [uv](https://docs.astral.sh/uv/) 包管理器

### 安装步骤

```bash
# 1. 克隆项目
git clone https://gitee.com/your-repo/ahccli-python.git
cd ahccli-python

# 2. 使用 uv 安装依赖（自动创建虚拟环境）
uv sync --all-extras

# 3. 创建配置文件
cp .env.example .env
# 编辑 .env 文件，填入你的 API Key
```

## 使用方法

### 配置 API Key

AHCCLI 默认使用智谱 AI 的 GLM-4.7 模型，支持三种配置方式（优先级从高到低）：

**方式一：`.env` 配置文件（推荐）**

```bash
# 复制模板并编辑
cp .env.example .env
```

在 `.env` 文件中填写配置：

```ini
AHCCLI_API_KEY=your-api-key-here
AHCCLI_BASE_URL=https://open.bigmodel.cn/api/paas/v4
AHCCLI_MODEL=glm-4.7
AHCCLI_MAX_ITERATIONS=10
```

**方式二：环境变量**

```bash
export AHCCLI_API_KEY="your-api-key"
```

**方式三：命令行参数**

```bash
ahccli run "你的问题" --api-key your-api-key
```

> **配置优先级**：命令行参数 > 系统环境变量 > `.env` 文件 > 内置默认值

### 单次查询模式（ReAct）

```bash
# 使用默认模型 (GLM-4.7)
uv run ahccli run "现在几点了？"

# 指定其他模型和接口
uv run ahccli run "Hello" \
  --base-url https://api.openai.com/v1 \
  --model gpt-4o \
  --api-key sk-xxx

# 限制最大推理轮次
uv run ahccli run "复杂问题" --max-iterations 5

# 切换厂商（五大厂商：deepseek/qwen/glm/kimi/step）
uv run ahccli run "Hello" --provider deepseek

# 模型管理子命令
uv run ahccli model list      # 列出全部可用模型
uv run ahccli model current   # 查看当前配置
uv run ahccli model use kimi  # 校验并切换到 Kimi
```

### 交互式 REPL 模式

```bash
uv run ahccli run -i
# 或
uv run ahccli run --interactive

# 进入交互模式后，直接输入问题即可
> 现在几点了？
> echo 测试消息
> exit
```

#### 交互模式命令

| 命令 | 说明 |
|------|------|
| `/memory` | 显示记忆系统状态 |
| `/memory facts` | 列出所有长期事实 |
| `/memory search <关键词>` | 搜索历史记忆 |
| `/memory delete <id>` | 删除指定事实 |
| `/memory clear` | 清空所有长期事实 |
| `/save` | 保存最近助手回复为事实 |
| `/save <文本>` | 直接保存文本为事实 |
| `/plan` | 设置下一命令使用 Plan-and-Execute 模式 |
| `/plan <文本>` | 立即以 Plan-and-Execute 模式执行 |
| `/index [路径]` | 索引项目代码（默认当前目录） |
| `/search <关键词>` | 语义代码检索 |
| `/graph [类名]` | 展示代码关系树形图谱 |
| `/rag on` | 开启 RAG 代码检索模式 |
| `/rag off` | 关闭 RAG 代码检索模式，使用工具链检索 |
| `/team <需求>` | Multi-Agent 团队编排（Planner→Worker→Reviewer） |
| `/hitl on\|off\|status` | 开启/关闭/查看 HITL 人工审批（默认关闭） |
| `/audit [筛选]` | 查询审计日志（类型/工具/状态筛选，stats 统计） |
| `/model [provider] [model]` | 查看/切换当前厂商与模型（deepseek/qwen/glm/kimi/step） |
| `/models` | 列出五大厂商全部可用模型与上下文窗口 |
| `/context [clear]` | 查看上下文状态与 token 消耗/耗时统计 |
| `/snapshot [list\|create\|rollback\|delete\|clean\|help]` | 项目快照管理（列表/手动创建/回滚/删除/清理过期/帮助） |
| `/mcp [restart\|logs\|disable\|enable\|call\|batch\|cache\|resources\|prompts\|help]` | MCP 外部服务管理（状态/重启/日志/禁用/启用/调用/批量/缓存/资源/Prompt 清单） |
| `/chrome [start\|stop\|restart\|pages\|do\|pool\|state\|help]` | Chrome 浏览器 MCP 管理（启停/页面清单/手动操作/会话池/状态缓存，强制 HITL 审批） |
| `/skill [list\|show\|on\|off\|install\|uninstall\|test\|reload\|help]` | Skill 技能系统管理（市场列表/详情/启用/禁用/安装/卸载/测试运行/热重载，无参等价 list） |
| `/runtime [start\|stop\|status\|help]` | Runtime HTTP 开放 API 管理（后台启动/停止/状态探测，实现 CLI + API 双运行） |
| `/cancel` | 取消当前运行中的任务（任务运行中按 ESC 亦可取消） |
| `help` | 显示所有可用命令和工具 |
| `exit` / `quit` | 退出交互模式 |

### Plan-and-Execute 模式

```bash
# 方式 1：CLI 子命令
uv run ahccli plan run "创建项目并编写测试"

# 方式 2：交互模式中使用 /plan
> /plan
[Plan-and-Execute] Next command will use Plan-and-Execute mode.
> 创建一个 Java Web 项目

# 方式 3：交互模式中直接内联执行
> /plan 创建项目并编写测试
```

计划执行流程：
1. **生成计划** — LLM 将需求拆解为结构化子任务
2. **审查计划** — 用户选择 E（执行）/ S（补充）/ C（取消）
3. **执行计划** — 按依赖拓扑并发执行任务
4. **错误纠正** — 失败任务的结果反馈给 LLM 生成纠正计划

### 三层记忆系统

AHCCLI 内置三层记忆系统，在交互模式下自动管理对话历史与长期知识：

```bash
# 进入交互模式
uv run ahccli run -i

# 查看记忆系统状态
> /memory

# 查看所有长期事实
> /memory facts

# 按关键词搜索历史记忆
> /memory search 数据库

# 删除指定事实
> /memory delete <id>

# 清空所有长期事实
> /memory clear
```

#### 保存记忆

```bash
# 保存最近一次助手回复中的关键信息为长期事实
> /save

# 直接保存自定义文本为事实
> /save Python 项目使用 uv 作为包管理器
```

记忆系统在每次对话中自动检索相关历史，帮助 LLM 保持上下文连贯性。长期事实持久化存储在本地 SQLite 数据库中，跨会话保留。

### RAG 代码检索

AHCCLI 支持对项目源代码进行向量化索引，实现语义级代码检索：

```bash
# 进入交互模式
uv run ahccli run -i

# 索引当前项目代码（默认当前目录）
> /index

# 索引指定目录
> /index src/ahccli

# 语义搜索代码片段
> /search 数据库连接

# 查看某个类/函数的代码关系图谱
> /graph Agent

# 查看某个文件的代码关系
> /graph embedding.py
```

#### RAG 模式切换

```bash
# 开启 RAG 辅助检索模式（Agent 自动使用 search_code 工具）
> /rag on

# 关闭 RAG，改用 glob_files + grep_code + read_file 工具链
> /rag off
```

**智能代码检索策略**：
- **RAG 开启 + 索引已建** → Agent 使用 `search_code` 工具进行语义检索
- **RAG 开启 + 无索引** → Agent 使用 `glob_files` / `grep_code` / `read_file` 工具链
- **RAG 关闭** → Agent 使用 `glob_files` / `grep_code` / `read_file` 工具链

### Multi-Agent 团队编排

AHCCLI 支持以多智能体团队协作模式处理复杂需求，由 Planner→Worker→Reviewer 三段流水线完成：

```bash
# 进入交互模式
uv run ahccli run -i

# 查看 /team 命令用法
> /team

# 以团队模式执行复杂需求（自动拆解 → 并行执行 → 审核验收）
> /team 创建一个 Python 计算器项目，实现加减乘除并编写单元测试
```

#### 团队构成与权限

| 角色 | 数量 | 职责 | 工具权限 |
|------|------|------|----------|
| Planner（规划者） | 1 | 将需求拆解为结构化子任务 | 禁用所有工具 |
| Worker（工作者） | 2 | 并行执行子任务 | 全量工具 |
| Reviewer（审核者） | 1 | 校验执行结果质量 | 仅只读工具 |

#### 编排执行流程

1. **规划（Plan）** — Planner 将需求拆解为子任务列表（JSON 格式）
2. **执行（Execute）** — Worker 按信号量并发控制批量执行子任务
3. **审核（Review）** — Reviewer 校验结果，未通过时携带反馈意见重试对应子任务（默认最多重试 2 次）
4. **汇总（Aggregate）** — 所有子任务通过后聚合为最终答案输出

> 说明：默认仍为单 Agent 模式（输入普通问题即走 ReAct 循环），`/team` 仅在显式输入时触发多智能体编排。团队执行结果同样会记录到记忆系统，可通过 `/memory` 查看。

### 三层安全防线与 HITL 人工审批

AHCCLI 内置三道安全防线，以中间件形式全局拦截所有工具调用（覆盖 ReAct / Plan-and-Execute / Multi-Agent 三种模式）：

```bash
# 进入交互模式
uv run ahccli run -i

# 查看 HITL 当前状态（默认关闭）
> /hitl status

# 开启 HITL 人工审批
> /hitl on

# 此后高危工具调用会弹出确认面板（展示工具名、入参、风险提示）：
# [1]确认执行 [2]拒绝执行 [3]永久放行 [4]本次会话放行

# 关闭 HITL
> /hitl off
```

#### 三道防线

| 防线 | 组件 | 拦截行为 |
|------|------|----------|
| 防线 1：命令拦截 | CommandInterceptor | 危险命令黑名单（rm -rf /、format c:、diskpart、curl\|sh 等）命中直接拒绝 |
| 防线 2：路径守卫 | PathGuard | 文件读写仅限允许目录（默认项目根目录），.ssh/.aws/Windows 等敏感路径拦截 |
| 防线 3：HITL 审批 | HitlApprover | HITL 开启时，高危工具调用强制人工确认，非交互终端自动拒绝 |

#### 审计日志查询

```bash
# 查看最近 50 条审计记录（Rich 表格）
> /audit

# 按事件类型筛选：tool_call / approval / intercept
> /audit intercept

# 按工具名称 + 条数筛选（可组合）
> /audit tool execute_command limit 20

# 查看事件统计概览
> /audit stats
```

审计记录双写 `.AHCCLI/audit.db`（SQLite）与 `.AHCCLI/audit.log`（日志文件）。

#### 配置化管控（security.json）

在项目根目录创建 `security.json` 可自定义安全策略（未配置的字段保留内置默认值）：

```json
{
  "hitl_enabled": false,
  "high_risk_tools": ["execute_command", "write_file"],
  "dangerous_commands": ["rm\\s+(-[a-z]*[rf][a-z]*\\s+)+(/|~|\\*)(\\s|$)"],
  "allowed_directories": ["."],
  "blocked_path_patterns": ["\\.ssh([\\\\/]|$)"]
}
```

> 说明：安全防线默认开启（命令拦截与路径守卫始终生效）；HITL 人工审批默认关闭，可通过 `/hitl on`、`security.json` 的 `hitl_enabled` 或环境变量 `AHCCLI_HITL_ENABLED=on` 开启。

### 多厂商模型切换（Multi-Model Support）

Phase 7 原生集成五大模型厂商，全部通过统一模型接口对接云端 API（不实现本地推理）。切换仅需修改配置文件中 provider 与 model 两个字段，接口地址与密钥按厂商目录自动推导，业务命令零改动：

| 厂商 | provider 标识 | 默认模型 | 最长上下文 | 前缀缓存模式 |
|------|-----------|----------|----------|------------|
| DeepSeek | `deepseek` | deepseek-chat | 64K | 服务端自动（回传命中量） |
| Qwen（通义千问） | `qwen` | qwen-plus | qwen-long 10M | 隐式缓存 |
| 智谱 GLM | `glm`（默认） | glm-4.7 | glm-4.7 200K | cache_control 显式标注 |
| Kimi（月之暗面） | `kimi` | moonshot-v1-128k | 128K | 自动（回传命中量） |
| 阶跃 Step（阶跃星辰） | `step` | step-3 | step-1-256k 256K | 隐式缓存 |

#### 方式 1：配置文件切换（推荐）

仅修改 `.env` 的 provider 与 model 字段即可无缝切换，重启后全链路（ReAct/Plan/Multi-Agent/RAG）自动生效：

```bash
# .env
AHCCLI_PROVIDER=deepseek
AHCCLI_DEEPSEEK_API_KEY=sk-xxx     # 厂商专属密钥，优先于 AHCCLI_API_KEY
AHCCLI_MODEL=deepseek-chat

# 业务命令不变，自动走 DeepSeek API
uv run ahccli run "你好"
```

#### 方式 2：CLI --provider 选项

```bash
# 单次运行时临时指定厂商（未指定密钥时使用对应厂商环境变量）
uv run ahccli run "你好" --provider kimi
uv run ahccli run "你好" --provider qwen --model qwen-long
```

#### 方式 3：交互模式 /model 切换

```bash
uv run ahccli run -i

# 查看当前生效的厂商与模型配置
> /model

# 列出五大厂商全部可用模型（含上下文窗口与缓存模式）
> /models

# 切换到 DeepSeek 推理模型（会话内即时生效，后续所有调用自动使用新模型）
> /model deepseek deepseek-reasoner

# 切换到 Qwen 百万级超长上下文模型
> /model qwen qwen-long
```

#### 上下文状态与用量统计（/context）

```bash
# 查看当前模型上下文窗口、前缀缓存模式，以及会话 token 消耗与平均耗时
> /context

# 清空会话用量统计
> /context clear
```

#### 模型管理 Typer 子命令

```bash
uv run ahccli model list                     # 列出五大厂商全部可用模型
uv run ahccli model current                  # 查看当前生效配置
uv run ahccli model use deepseek             # 校验厂商/模型合法性并预览切换结果
uv run ahccli model use kimi moonshot-v1-128k
```

> 提示：`model use` 在独立进程中执行，持久切换请设置 `AHCCLI_PROVIDER` / `AHCCLI_MODEL` 环境变量，或在 `run -i` 交互模式中使用 `/model` 命令。

### 项目快照（Snapshot）

Phase 8 为项目源码提供增量备份与一键回滚能力。快照统一存放于 `./.AHCCLI/snapshots/`，按「时间戳_任务阶段」命名：每个快照保存全量 SHA-256 文件清单，仅物理存储相对上一快照变更的文件，不污染 Git 版本管理。

**自动快照触发规则**：

| 触发点 | 时机 |
|--------|------|
| Plan 执行前 | 仅执行 Plan 时触发（普通 ReAct 任务不触发），阶段标识 `plan` |
| 修改代码的高危调用成功后 | 高危调用**成功执行且项目确有改动**后触发（ReAct/Plan 全阶段，失败或无改动不触发），阶段标识 `high_risk` |
| Multi-Agent 子阶段 | 团队编排各子阶段独立快照，阶段标识 `team_*` |

#### 方式 1：Typer 子命令

```bash
# 查看全部快照（时间/阶段/任务描述/文件变更统计/存储占用）
uv run ahccli snapshot list

# 手动创建快照（增量保存当前项目文件变更）
uv run ahccli snapshot create "重构前的基线版本"

# 一键回滚到指定快照（触发人工确认审批，回滚前自动创建 pre_rollback 安全快照）
uv run ahccli snapshot rollback 20260819_094118_plan
uv run ahccli snapshot rollback 20260819_094118_plan --yes   # 跳过确认

# 删除指定快照（中间快照的物理副本自动合并，回滚能力不受损）
uv run ahccli snapshot delete 20260819_092759_manual

# 清理过期快照：保留最新 N 个（默认 max_snapshots），从最旧开始删除
uv run ahccli snapshot clean
uv run ahccli snapshot clean --keep 10
```

#### 方式 2：交互模式 /snapshot 命令

```bash
uv run ahccli run -i

# 查看快照列表（Rich 表格渲染）
> /snapshot
> /snapshot list

# 手动创建快照（可附带任务描述）
> /snapshot create
> /snapshot create 修复登录逻辑前的备份

# 一键回滚到指定快照（人工审批，自动 pre_rollback 安全快照）
> /snapshot rollback 20260819_094118_plan

# 删除指定 ID 的快照（人工确认，中间快照副本自动合并）
> /snapshot delete 20260819_092759_manual

# 清理过期快照（可选保留个数，默认 max_snapshots）
> /snapshot clean
> /snapshot clean 10

# 打印快照命令帮助文档
> /snapshot help
```

#### 配置化开关（snapshot.json）

在项目根目录创建 `snapshot.json` 可自定义快照策略（未配置的字段保留内置默认值）：

```json
{
  "enabled": true,
  "auto_snapshot": true,
  "max_snapshots": 20,
  "exclude_dirs": [".AHCCLI", ".git", "__pycache__", ".venv", "node_modules"],
  "exclude_patterns": ["*.pyc", "*.db", "*.sqlite"]
}
```

> 说明：`enabled` 为总开关（关闭后所有快照命令不可用），`auto_snapshot` 控制自动快照钩子；环境变量 `AHCCLI_SNAPSHOT_ENABLED` 可覆盖总开关。快照仅管理本地项目源码文件，SQLite 记忆/索引数据库（.AHCCLI）与 .git 等目录一律排除；快照扫描与回滚受路径守卫管控，回滚操作触发 HITL 人工确认审批。

### 网页搜索与抓取（Web）

Phase 9 为 Agent 补充联网能力：当用户提问缺少本地代码或历史记忆可参考的信息时，Agent 自动调用 `web_search` 联网搜索补充信息，必要时用 `web_fetch` 抓取页面正文注入推理上下文。网络层复用全局 httpx 异步客户端（统一超时/代理 + 请求限流）；URL 黑名单拦截恶意高危网站，高危域名抓取触发 HITL 人工确认，全部网络请求记入审计日志；网页内容仅临时存入短期记忆，不做 RAG 持久化。

#### 方式 1：Typer 子命令

```bash
# 手动网页综合搜索（标题/摘要/链接，-n 限制结果条数）
uv run ahccli web search "Python asyncio 教程"
uv run ahccli web search "httpx 代理配置" -n 3

# 手动抓取网页正文（过滤广告/导航栏，高危域名触发 HITL 确认）
uv run ahccli web fetch https://docs.python.org/3/library/asyncio.html

# 查看网络访问审计日志（web_search/web_fetch 全部记录）
uv run ahccli web audit
uv run ahccli web audit --limit 50
```

#### 方式 2：交互模式 /web 命令

```bash
uv run ahccli run -i

# 网页搜索（-n 可选结果条数）
> /web search Python 异步编程最佳实践
> /web search uv 虚拟环境 -n 3

# 抓取网页正文（黑名单/内网地址自动拦截）
> /web fetch https://www.python.org/about/

# 查看网络访问审计日志（可选条数）
> /web audit
> /web audit 50

# 打印 /web 命令帮助文档
> /web help
```

#### Agent 自动联网（ReAct 模式）

```bash
uv run ahccli run -i

# 提问缺少本地信息时，Agent 自动调用 web_search/web_fetch 补充上下文
> Python 3.13 相比 3.12 有哪些新特性？
```

#### 配置化开关（web.json）

在项目根目录创建 `web.json` 可自定义联网策略（未配置的字段保留内置默认值）：

```json
{
  "enabled": true,
  "timeout_seconds": 15,
  "proxy": "",
  "rate_limit_per_minute": 20,
  "max_search_results": 5,
  "max_content_chars": 8000,
  "search_provider": "auto",
  "url_blacklist": ["malware\\.example\\.com"],
  "high_risk_domains": ["bit.ly", "t.cn", "tinyurl.com"]
}
```

> 说明：`enabled` 为总开关（关闭后 web_search/web_fetch 不注册，Agent 无法联网）；`search_provider` 取值 `auto`（DuckDuckGo → Bing 自动降级）/ `duckduckgo` / `bing`；环境变量 `AHCCLI_WEB_ENABLED` / `AHCCLI_WEB_PROXY` / `AHCCLI_WEB_TIMEOUT` 可覆盖开关/代理/超时。仅支持 http/https 协议与公网地址（内网/本机地址一律拒绝，防 SSRF）；高危域名抓取在 HITL 开启时触发人工确认。

### MCP 外部服务（MCP）

Phase 10 为 Agent 接入 MCP（Model Context Protocol）基础客户端能力：程序启动自动扫描 mcp.json 连接全部配置的 MCP 服务，自动发现其暴露的外部工具并以 `mcp__{server}__{tool}` 命名注册进全局工具池，与本地内置工具统一调度；ReAct/Plan/Multi-Agent/HITL 对 MCP 工具无差别适配，高危 MCP 工具同样触发人工审批，连接日志记入审计模块。仅实现标准 MCP 基础规范（工具调用/资源读取/Prompt 模板拉取），不开发浏览器相关 MCP 扩展。

#### 方式 1：Typer 子命令

```bash
# 查看所有 MCP server 的连接状态
uv run ahccli mcp status

# 重启 / 查看日志 / 禁用 / 启用指定 server
uv run ahccli mcp restart filesystem
uv run ahccli mcp logs filesystem
uv run ahccli mcp logs filesystem --limit 20
uv run ahccli mcp disable filesystem
uv run ahccli mcp enable filesystem
```

#### 方式 2：交互模式 /mcp 命令

```bash
uv run ahccli run -i

> /mcp                     # 查看所有 server 的状态
> /mcp restart <name>      # 重启某个 server
> /mcp logs <name> [N]     # 查看某个 server 的连接日志
> /mcp disable <name>      # 禁用某个 server
> /mcp enable <name>       # 重新启用某个 server
> /mcp help                # 打印 /mcp 命令帮助文档
```

#### 配置化开关（mcp.json）

在项目根目录创建 `mcp.json` 配置 MCP 服务（完整示例见 `mcp.example.json`，未配置的字段保留内置默认值）：

```json
{
  "enabled": true,
  "connect_timeout_seconds": 15,
  "call_timeout_seconds": 30,
  "reconnect_max_attempts": 3,
  "reconnect_backoff_seconds": 1.0,
  "servers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\workspace"],
      "env": {},
      "enabled": true,
      "high_risk_tools": ["write_file", "move_file", "delete_file"]
    },
    "remote": {
      "transport": "http",
      "url": "https://mcp.example.com/sse",
      "headers": {"Authorization": "Bearer your-token-here"},
      "enabled": false,
      "high_risk_tools": []
    }
  }
}
```

> 说明：`enabled` 为总开关（关闭后不连接任何 MCP 服务、不注册外部工具）；`servers` 支持两种传输：`stdio`（command/args/env，必填 command）与 `http`（url/headers，必填 url）；`high_risk_tools` 声明该 server 的高危工具名，注册后以全名 `mcp__{server}__{tool}` 纳入 HITL 人工审批；连接异常按 `reconnect_max_attempts` / `reconnect_backoff_seconds` 退避自动重连；环境变量 `AHCCLI_MCP_ENABLED` / `AHCCLI_MCP_FILE` 可覆盖开关/配置文件路径。

### MCP 高级扩展（v0.11.0）

Phase 11 在基础客户端之上补齐高级调度与增量能力：工具权限隔离、资源/Prompt 本地缓存、批量并行调用、心跳检测与离线降级/崩溃自动重启、每服务高级配置；增量能力含资源双通路/虚拟资源、服务端通知被动路由与事件驱动缓存失效、@提及展开与补全、ESC//cancel 任务取消。约束：不接入 Chrome 浏览器 MCP / CDP / OAuth / Sampling。

#### 单工具调用与批量并行调用

```bash
uv run ahccli run -i

> /mcp call filesystem read_file {"path": "C:\\workspace\\notes.md"}   # 调用单个外部工具（Rich 分栏渲染详情）

# 批量并行调用：一次提交多个工具调用，Semaphore 限流 + gather 并发（上限 batch_max_concurrent）
> /mcp batch [{"server": "filesystem", "tool": "read_file", "arguments": {"path": "a.md"}}, {"server": "fetch", "tool": "fetch", "arguments": {"url": "https://example.com"}}]
```

#### 资源缓存管理

```bash
> /mcp cache stats          # 查看本地 SQLite 缓存统计（条数/TTL/按类型/按服务）
> /mcp cache clear          # 清空全部缓存
> /mcp cache clear filesystem   # 仅清空指定服务的缓存
```

资源读取（read_resource）与 Prompt 拉取（get_prompt）命中缓存后不再发起网络请求；服务端推送资源变更通知（notifications/resources/updated）时被动精准失效对应条目（精确 URI + 父级前缀）；工具调用永不进缓存。

#### 资源与 Prompt 清单（双通路）

```bash
# Typer 子命令与 REPL 命令等价，可选服务名过滤
uv run ahccli mcp resources
uv run ahccli mcp prompts filesystem

> /mcp resources            # 资源清单：本地虚拟通道 + 远程服务通道
> /mcp resources filesystem # 仅看指定服务的远程资源
> /mcp prompts              # Prompt 模板清单（名称/说明/参数）
```

#### @提及快速引用

在 REPL 输入中以 `@服务名:引用` 直接引用 MCP 能力对象，发送前自动展开为实际内容注入查询：

```bash
> 请总结 @filesystem:file://docs/a.md 的要点        # 引用含 :// → 资源，展开为资源正文
> @filesystem:search 支持哪些参数？                 # 匹配已发现工具 → 展开为工具说明
> @zread:summarize 这篇文章                        # 其余 → 按 Prompt 模板展开（失败保留原文）
```

输入 `@` 或 `@服务名:` 可获得补全候选（服务名/工具名/Prompt 名/虚拟资源 URI）；展开内容超长自动截断（上限 4000 字符），未知服务的提及不展开。

#### 任务取消（ESC / /cancel）

ReAct/Plan/Multi-Agent 均在后台线程运行并内置协作式取消安全点：任务运行中按 **ESC**（或输入 `/cancel` + 回车）即可取消，已完成的任务结果保留，未开始的任务标记为“任务已取消”；空闲时输入 `/cancel` 提示当前无运行中任务。

```bash
> 帮我重构整个项目…          # 任务运行中
^ [按下 ESC]                # 输出“任务已取消”，返回 REPL
> /cancel                   # 空闲时：当前没有运行中的任务。
```

#### 高级配置（mcp.json 增量字段）

在 `mcp.json` 中追加以下字段即可启用（完整示例见 `mcp.example.json`）：

```json
{
  "heartbeat_interval_seconds": 60,
  "heartbeat_timeout_seconds": 10,
  "heartbeat_max_failures": 3,
  "cache_enabled": true,
  "cache_ttl_seconds": 300,
  "cache_file": "",
  "batch_max_concurrent": 5,
  "browser_pool_enabled": false,
  "browser_pool_max_sessions": 3,
  "browser_pool_idle_timeout_seconds": 600,
  "browser_pool_keepalive_seconds": 30,
  "browser_pool_acquire_timeout_seconds": 60,
  "browser_pool_memory_limit_mb": 2048,
  "browser_state_file": "",
  "browser_profile_dir": "",
  "browser_login_auto_switch": false,
  "servers": {
    "remote": {
      "transport": "http",
      "url": "https://mcp.example.com/sse",
      "api_key": "your-api-key-here",
      "timeout_seconds": 60,
      "connect_timeout_seconds": 20,
      "proxy": "http://127.0.0.1:7890",
      "snapshot_enabled": false,
      "allowed_tools": ["search", "read"]
    }
  }
}
```

> 说明：`heartbeat_*` 控制周期心跳探测（list_tools），连续失败达阈自动离线降级，后续周期崩溃自动重启；`cache_*` 控制本地 SQLite 缓存（`cache_enabled=false` 完全禁用）；`batch_max_concurrent` 为批量调用并发上限；`browser_pool_*` 控制 CDP 浏览器会话池（默认关闭，见下节）；`browser_state_file` 自定义浏览器状态缓存文件路径；`browser_profile_dir` 指定 Chrome 持久化用户数据目录（空串用 `--isolated` 临时档案；设置后登录态含 HttpOnly Cookie 跨重启保留）；`browser_login_auto_switch` 控制检测到需要登录时是否自动切换共享模式重试（默认关闭，见下节）；服务级 `api_key` 对 http 注入 Authorization 头、对 stdio 注入 `MCP_API_KEY` 环境变量；`timeout_seconds` / `connect_timeout_seconds` / `proxy` 覆盖全局值；`snapshot_enabled` 控制该服务成功后是否自动快照；`allowed_tools` 为服务级工具白名单（注册阶段过滤，`null`/不配置为全部放行，空数组为全部禁用）。

### Chrome 浏览器自动化（v0.12.0）

Phase 12 基于 Phase 10/11 MCP 框架对接标准 **Chrome DevTools MCP** 服务（`chrome-devtools-mcp`，底层标准 CDP），封装页面打开、元素点击、输入文本、页面截图、JS 执行、网络请求捕获等浏览器工具统一适配，ReAct/Multi-Agent 可自动调用完成网页自动化并抓取页面数据补充推理上下文。

#### 服务启停与页面管理

```bash
# Typer 子命令（未配置时自动注入默认 stdio 配置：npx -y chrome-devtools-mcp@latest --isolated）
uv run ahccli chrome-mcp start     # 启动浏览器 MCP 服务（运行时注册 + 连接 + 高危清单同步）
uv run ahccli chrome-mcp status    # 查看连接状态与已发现工具
uv run ahccli chrome-mcp pages     # 查看浏览器页面清单（调用 list_pages，表格渲染）
uv run ahccli chrome-mcp stop      # 停止（断开并禁用）
uv run ahccli chrome-mcp restart   # 重启

# 交互模式等价命令
> /chrome start
> /chrome pages
> /chrome do navigate_page {"url": "https://example.com"}   # 手动执行浏览器操作（强制 HITL 审批）
> /chrome do take_screenshot
> /chrome help
```

#### 安全管控

- **强制 HITL 审批**：浏览器工具全部纳入高危清单，调用强制弹出人工审批面板，即使全局 `/hitl off` 也不豁免（仅安全总开关关闭时整体放行）；
- **URL 黑名单**：浏览器访问 URL 同步经过项目 URL 黑名单校验（与 web 模块同源配置，协议白名单 http/https + 正则黑名单），先于审批拦截；本地开发访问 localhost 不受 SSRF 限制；
- **审计与快照**：浏览器操作记录全量写入审计日志；快照机制不备份浏览器状态（默认 `snapshot_enabled=false`）。

#### 约束

仅对接标准 CDP MCP，不自研浏览器控制逻辑；`--isolated` 模式每个会话使用独立浏览器上下文（会话池多会话隔离基础）；浏览器操作以青色 Rich 面板按操作类别（🌐 页面打开 / 🖱️ 元素点击 / ⌨️ 输入文本 / 📷 页面截图 / ⚡ JS 执行 / 📡 网络捕获）渲染，与本地工具（黄色）、普通 MCP 工具（品红）三色区分。

### CDP 浏览器会话池（v0.13.0）

Phase 13 在 Phase 12 Chrome DevTools MCP 之上提供**常驻 CDP 连接会话池**：会话池管理的是一组彼此独立的 chrome-devtools-mcp 连接（每条连接对应独立浏览器实例与 CDP 会话），复用浏览器实例避免每次自动化操作重启浏览器，大幅提升执行速度；上层 Agent 与工具调用逻辑零改动，底层自动分发请求至池中空闲连接。

#### 启用与会话生命周期

```json
{
  "browser_pool_enabled": true,
  "browser_pool_max_sessions": 3,
  "browser_pool_idle_timeout_seconds": 600,
  "browser_pool_keepalive_seconds": 30,
  "browser_pool_acquire_timeout_seconds": 60,
  "browser_pool_memory_limit_mb": 2048
}
```

- **复用与隔离**：空闲会话按最近使用优先复用；并发调用超过 `browser_pool_max_sessions` 时排队等待，超过 `browser_pool_acquire_timeout_seconds` 报获取超时；每条池连接是独立 `--isolated` 浏览器上下文，多并发互不串扰；
- **保活与回收**：`browser_pool_keepalive_seconds` 周期巡检（空闲会话 list_tools 探测，连续失败自动销毁；使用中会话豁免），空闲超过 `browser_pool_idle_timeout_seconds` 自动回收；
- **异常重建**：调用失败的会话标记 broken 并销毁，下次调用惰性重建；会话创建/销毁均写入审计日志；
- **内存告警**：可选依赖 `psutil` 汇总浏览器进程树内存，超过 `browser_pool_memory_limit_mb` 告警（`<=0` 或未安装 psutil 时静默关闭）。

#### 浏览器状态缓存（登录会话恢复）

可选将站点 Cookie 与 localStorage 快照保存至本地（默认 `.AHCCLI/browser_state.json`，可用 `browser_state_file` 自定义），重启 AHCCLI 后恢复登录会话，避免反复登录。保存时经 `cookieStore` API 捕获 Cookie 的 domain/path/expires 属性，恢复时按原始属性回注（兼容无属性的旧格式条目，按主机名兜底推断根域）并自动刷新页面让服务端基于恢复后的状态重新渲染：

```bash
uv run ahccli chrome-mcp state save https://example.com      # 缓存登录态（Cookie + localStorage）
uv run ahccli chrome-mcp state restore https://example.com   # 恢复至当前浏览器会话
uv run ahccli chrome-mcp state list                          # 查看缓存清单
uv run ahccli chrome-mcp state clear example.com             # 清除指定域名（缺省清空全部）
uv run ahccli chrome-mcp pool                                # 查看会话池状态（活跃/空闲/使用中）
uv run ahccli chrome-mcp pool clear                          # 销毁全部池会话（下次调用自动新建）
```

> 约束：会话池仅优化浏览器会话复用逻辑，不改动原有 MCP、HITL 与网页抓取基础能力；池默认关闭（兼容 v0.12.x 单会话行为）；状态保存/恢复同样经过 URL 黑名单校验并写入审计日志；HttpOnly Cookie 无法经 JS 恢复（尽力而为）——若站点登录态依赖 HttpOnly 会话票据，请在 mcp.json 配置 `browser_profile_dir` 使用持久化用户数据目录，登录一次后全部 Cookie 跨重启保留（持久档案受 Chrome 单实例锁限制，建议同时将会话池上限设为 1）。

### 浏览器共享模式（登录会话复用，v0.13.2）

Phase 13 补齐功能：基于 chrome-devtools-mcp 原生 `--browserUrl`/`--autoConnect` 参数对接已运行的 Chrome 实例，Agent 直接复用浏览器已有登录会话，无需状态缓存中转。浏览器有两种运行模式：

- **isolated（隔离模式，默认）**：独立浏览器实例（`--isolated` 临时档案或 `browser_profile_dir` 持久档案），无本地登录态；
- **shared（共享模式）**：复用本机已启动的远程调试 Chrome 实例，直接继承全部登录会话（含 HttpOnly 会话票据）。

```bash
uv run ahccli browser                    # 查询当前浏览器运行模式（等价 browser status）
uv run ahccli browser connect            # 切换共享模式：autoConnect 自动发现本机可调试 Chrome
uv run ahccli browser connect http://127.0.0.1:9222   # 指定远程调试地址切换共享模式
uv run ahccli browser disconnect         # 切回隔离模式（独立浏览器实例）
```

交互模式等价命令：`/browser`、`/browser status`、`/browser connect [url]`、`/browser disconnect`、`/browser help`。

#### 共享模式的两种接入方式

1. **autoConnect 自动发现**：Chrome 144+ 打开 `chrome://inspect/#remote-debugging` 勾选 *Allow remote debugging for this browser instance* 后，`/browser connect`（不带地址）即可自动连接当前浏览器；
2. **远程调试端口**：以 `chrome --remote-debugging-port=9222` 启动 Chrome（注意：需先完全退出已有 Chrome 进程），再 `/browser connect http://127.0.0.1:9222`。

#### 容错降级与自动切换

- **探测降级**：模式切换后立即以 `list_pages` 探测目标浏览器真实可用性（MCP 进程启动成功不代表浏览器可达）；本机未开启 Chrome 远程调试时连接失败，自动回退隔离模式并输出提示（告知开启远程调试以启用本地登录态复用）；
- **登录自动切换**：mcp.json 设置 `browser_login_auto_switch=true` 后，优先使用隔离模式执行任务；导航结果命中登录页特征时自动尝试切换共享模式并重试一次（切换失败保持隔离模式并在结果中附带提示）；默认关闭，避免误判（如 Agent 有意访问登录页）触发任务中重启；
- **审计**：模式切换（手动/自动、成功/失败）均写入审计日志（目标：`chrome-devtools:share`）。

> 约束：共享模式受限于目标 Chrome 的远程调试能力（需本机进程且未被占用）；切换模式会销毁当前 CDP 会话池会话（下次调用懒创建）；默认关闭自动切换，显式开启后仅对导航类工具（navigate_page/new_page）生效。

### 可扩展 Skill 技能系统（v0.14.0）

Phase 14 为 Agent 提供可扩展的技能（Skill）封装层：一个技能以 `./.AHCCLI/skills/<name>/SKILL.md` 文件存在，元数据头声明绑定的本地工具 / MCP 工具、关键词与执行前置校验规则，正文是该技能的专属 Prompt 模板（`{query}` 占位符运行时渲染）。Agent 根据用户需求语义自动检索匹配技能并懒加载，技能系统作为上层封装，不重构底层 Tool、MCP、浏览器核心代码。

#### SKILL.md 技能规范示例

```markdown
---
description: 代码审查技能：系统性审查代码质量并输出结构化报告
version: 1.0.0
keywords: [代码审查, 代码评审, review, 质量检查]
tools: [read_file, list_dir, glob_files, grep_code, search_code]
pre_check: [dir_exists:src]
---
你是一名资深代码审查工程师，请围绕以下需求完成代码审查：
{query}
```

- **元数据头**：零依赖 YAML 子集（标量/行内列表/破折号列表）或 JSON 双形态；`description` 必填；可选 `tools`（本地工具）、`mcp_tools`（MCP 工具）、`pre_check`（file_exists / dir_exists / env / tool_available 前置校验）、`hitl_required`（加载需 HITL 审批）、`auto_snapshot`（加载前自动快照）；
- **技能隔离**：禁用技能对自动匹配与 `load_skill` 完全不可见；启停状态持久化于技能仓库根目录 `skills.json`，未显式设置的技能默认启用。

#### 技能市场与生命周期命令

```bash
uv run ahccli run -i

> /skill                          # 等价 /skill list：技能市场列表（内置 + 自定义，状态/描述/工具数）
> /skill show code-review         # 查看技能详细配置、前置规则与 Prompt 预览
> /skill off commit-message       # 禁用技能（即时生效，写入 skills.json）
> /skill on commit-message        # 启用技能
> /skill install ./my-skill       # 安装自定义/第三方配套技能（SKILL.md 文件或技能目录，--force 覆盖）
> /skill uninstall my-skill       # 卸载自定义技能（内置技能仅可禁用）
> /skill test code-review         # 测试技能运行（干跑解析/前置校验/正文可读，不调用 LLM）
> /skill reload                   # 热重载技能配置与资源（无需重启）
> /skill help                     # 打印帮助文档
```

Typer 等价子命令：`ahccli skill list|show|on|off|install|uninstall|test|reload`（`ahccli skill` 无参等价 `skill list`）。

#### Agent 自动技能匹配与懒加载

- **启动预缓存**：服务启动仅扫描缓存全部技能元数据（不读 Prompt 正文），`/skill list` 与自动匹配即时响应；
- **自动匹配**：每轮用户请求进入 Agent 前经技能管道——jieba 分词加权评分，评分 ≥0.5 的技能自动懒加载并注入本轮会话上下文（【技能上下文】块），≥0.25 的技能以【匹配到可用技能】提示块推荐，Agent 按需调用 `load_skill` 工具加载；
- **load_skill 工具**：校验技能存在/启用/多 Agent 白名单 → 执行前置校验规则 → （声明时）HITL 审批与自动快照 → 懒加载正文渲染 `{query}` → 返回技能 Prompt 与绑定工具清单并压入 per-session 上下文缓冲，全程写审计日志；
- **会话上下文注入**：SkillContextBuffer 按会话隔离，已加载技能 Prompt 自动注入下一轮用户消息（注入后清空），单会话技能状态连续、多会话互不干扰；
- **多 Agent 白名单**：`RoleConfig.skill_whitelist` 为每个智能体分配独立技能白名单（`None` 不限制 / `[]` 全禁），与工具白名单同构。

> 说明：内置 code-review（代码审查）/ commit-message（Git 提交信息）/ web-research（联网调研）三个示例技能模板；技能执行中间可直接调用既有全局工具池的 RAG（search_code）、记忆（search_memory）与浏览器 MCP（mcp__chrome-devtools__*）能力；技能管道任何异常一律降级返回原查询，绝不阻断主流程。

### Runtime HTTP 开放 API（v0.15.0）

Phase 15 以异步 HTTP 服务形式开放全部 Agent 能力，供外部程序（curl / Python / IDE 插件）调用。服务基于 Starlette + uvicorn 异步栈，完全复用项目内部核心模块（ReAct / Plan / 安全防线 / MCP / 快照 / 技能系统），无重复业务逻辑。完整接口文档见 [`docs/runtime-api.md`](docs/runtime-api.md)。

#### 配置与启动

```bash
# .env 中配置访问密钥（必填，缺失拒绝启动）
AHCCLI_RUNTIME_API_KEY=your-strong-secret-key
# 可选：AHCCLI_RUNTIME_HOST=127.0.0.1 / AHCCLI_RUNTIME_PORT=8780 / AHCCLI_RUNTIME_MAX_CONCURRENT=4

# 模式一：前台独占运行（Ctrl+C 停止）
uv run ahccli runtime start
uv run ahccli runtime status     # 探测服务运行状态

# 模式二：CLI + Runtime API 双运行（进入 REPL 后）
> /runtime start      # 后台线程启动服务，终端继续可用（Rich 实时展示 API 流量）
> /runtime status     # 查看运行状态（会话数/活跃任务数）
> /runtime stop       # 优雅停止
```

#### 接口总览与调用示例

| 分组 | 接口 | 说明 |
|------|------|------|
| 会话 | `/api/sessions`、`/api/sessions/{id}/messages\|stream` | 多轮会话：同步问答（含推理事件轨迹）与 SSE 流式推理输出 |
| 任务 | `/api/tasks` | Plan 任务后台执行：创建（202）/进度轮询/协作终止 |
| 资源 | `/api/memory/*`、`/api/rag/search`、`/api/snapshots/*`、`/api/skills/*` | 记忆检索、RAG 代码查询、快照回滚（HITL 联动）、技能加载 |
| MCP/浏览器 | `/api/mcp/*`、`/api/browser/tool` | MCP 服务管理与工具调用、浏览器自动化（同一安全链路） |
| 系统 | `/health`、`/api/info`、`/api/audit`、`/api/model` | 健康检查（免鉴权）/服务信息/审计查询/模型切换 |

```bash
# 健康检查（免鉴权）
curl http://127.0.0.1:8780/health

# 创建会话并提交问题（返回最终答案 + 完整推理事件轨迹）
curl -X POST http://127.0.0.1:8780/api/sessions \
     -H "Authorization: Bearer your-strong-secret-key"
curl -X POST http://127.0.0.1:8780/api/sessions/<session_id>/messages \
     -H "Authorization: Bearer your-strong-secret-key" \
     -H "Content-Type: application/json" \
     -d '{"query": "当前目录有哪些文件？"}'
```

> 说明：鉴权支持 `Authorization: Bearer <key>` 与 `X-API-Key: <key>` 双请求头（hmac 恒定时间比对），密钥未配置时服务降级拒绝一切业务请求（503）；每个 API 请求写入全局审计日志（`/audit api_call` 可查）；MCP 工具与浏览器自动化调用一律经 SecureToolExecutor 执行（命令拦截/路径守卫/HITL 审批/审计与终端完全同一链路，非交互环境无 TTY 时 HITL 按既有策略自动拒绝高危操作）。

### 内置工具

| 工具名称 | 说明 |
|----------|------|
| `get_current_time` | 获取当前日期和时间 |
| `echo` | 回显输入的消息 |
| `read_file` | 读取文件内容（支持 offset/limit 分段读取） |
| `write_file` | 将内容写入文件（创建/覆盖） |
| `list_dir` | 列出目录下的文件和子目录 |
| `glob_files` | 按文件名 glob 模式搜索候选文件 |
| `grep_code` | 关键字/正则精确搜索代码内容 |
| `execute_command` | 在系统 Shell 中执行命令（OS 感知） |
| `create_project` | 创建标准 Python 项目目录结构 |
| `search_memory` | 搜索历史对话和长期记忆 |
| `save_memory` | 将重要信息保存为长期记忆事实 |
| `search_code` | 搜索项目源代码，获取真实代码片段 |
| `web_search` | 联网综合搜索网页信息（标题/摘要/链接） |
| `web_fetch` | 抓取网页正文纯文本（过滤广告导航，高危域名 HITL 确认） |
| `load_skill` | 按需加载已安装并启用的技能：校验前置规则后返回技能专属 Prompt 与绑定工具清单并注入会话上下文（v0.14.0） |
| `mcp__{server}__{tool}` | MCP 外部工具动态注册（按 mcp.json 配置自动发现，SDK 转发调用，高危工具触发 HITL 审批） |
| `mcp__chrome-devtools__*` | Chrome 浏览器工具（navigate_page/click/fill/take_screenshot/evaluate_script 等，强制 HITL 审批 + URL 黑名单校验，v0.12.0） |

### 配置项说明

| 配置项 | 说明 | `.env` / 环境变量 | 默认值 |
|--------|------|-------------------|--------|
| API Key | LLM API 密钥（通用回退） | `AHCCLI_API_KEY` | （必填） |
| Provider | 模型厂商标识（deepseek/qwen/glm/kimi/step） | `AHCCLI_PROVIDER` | `glm` |
| 厂商专属密钥 | 厂商专属 API 密钥（优先于通用密钥） | `AHCCLI_<PROVIDER>_API_KEY` | （回退到 `AHCCLI_API_KEY`） |
| Base URL | LLM API 地址（仅 glm 厂商生效，其余按目录推导） | `AHCCLI_BASE_URL` | `https://open.bigmodel.cn/api/paas/v4` |
| Model | 模型名称 | `AHCCLI_MODEL` | `glm-4.7` |
| Timeout | 模型请求超时（秒） | `AHCCLI_LLM_TIMEOUT` | `60` |
| Temperature | 采样温度 | `AHCCLI_LLM_TEMPERATURE` | （厂商默认） |
| 上下文上限 | 最大上下文 token 数 | `AHCCLI_MAX_CONTEXT_TOKENS` | （按模型目录推断） |
| Max Iterations | 最大推理轮次 | `AHCCLI_MAX_ITERATIONS` | `10` |
| RAG 启用 | 是否启用 RAG 代码检索模块 | `AHCCLI_RAG_ENABLED` | `true` |
| Embedding API Key | Embedding API 密钥（未设置时回退到 `AHCCLI_API_KEY`） | `AHCCLI_EMBEDDING_API_KEY` | （回退到 `AHCCLI_API_KEY`） |
| Embedding Base URL | Embedding API 地址 | `AHCCLI_EMBEDDING_BASE_URL` | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
| Embedding Model | Embedding 模型名称 | `AHCCLI_EMBEDDING_MODEL` | `text-embedding-v4` |
| Embedding Dim | Embedding 向量维度 | `AHCCLI_EMBEDDING_DIM` | `1024` |
| RAG DB Dir | RAG 数据库目录 | `AHCCLI_RAG_DB_DIR` | `./.AHCCLI` |
| HITL 启用 | 是否开启 HITL 人工审批 | `AHCCLI_HITL_ENABLED` | `false` |
| 安全配置文件 | 安全策略配置文件路径 | `AHCCLI_SECURITY_FILE` | `./security.json` |
| Web 启用 | 联网工具总开关（关闭后 web_search/web_fetch 不注册） | `AHCCLI_WEB_ENABLED` | `true` |
| Web 代理 | 网络请求 HTTP 代理地址 | `AHCCLI_WEB_PROXY` | （空，不使用代理） |
| Web 超时 | 网络请求统一超时（秒） | `AHCCLI_WEB_TIMEOUT` | `15` |
| Web 配置文件 | 联网策略配置文件路径 | `AHCCLI_WEB_FILE` | `./web.json` |
| Runtime Host | Runtime API 监听地址 | `AHCCLI_RUNTIME_HOST` | `127.0.0.1` |
| Runtime Port | Runtime API 监听端口 | `AHCCLI_RUNTIME_PORT` | `8780` |
| Runtime API Key | Runtime API 访问密钥（缺失拒绝启动） | `AHCCLI_RUNTIME_API_KEY` | （必填） |
| Runtime 并发上限 | 后台任务队列最大并发数 | `AHCCLI_RUNTIME_MAX_CONCURRENT` | `4` |

## ReAct 推理流程

```
用户输入
  │
  ▼
┌─────────────────┐
│  LLM 推理判断    │◄──────────────────┐
│  (流式 SSE)      │                   │
└────────┬────────┘                   │
         │                            │
    ┌────┴────┐                       │
    │         │                       │
 有工具调用  无工具调用                 │
    │         │                       │
    ▼         ▼                       │
┌────────┐ ┌──────────┐              │
│执行工具 │ │输出最终   │              │
│& 回填   │ │答案      │              │
│结果     │ └──────────┘              │
└────┬───┘                           │
     │                                │
     └────────────────────────────────┘
          (迭代，直到得出最终答案
           或达到最大轮次)
```

## Plan-and-Execute 流程

```
用户需求
  │
  ▼
┌──────────────────┐
│  LLM 任务分解     │
│  (生成结构化计划)  │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  E/S/C 用户审查   │
│  E=执行 S=补充    │
│  C=取消           │
└────────┬─────────┘
         │
    ┌────┴────┐
    │         │
  执行      取消/补充
    │         │
    ▼         ▼
┌────────┐ ┌──────────┐
│拓扑排序 │ │重新生成   │
│并发执行 │ │或退出     │
└────┬───┘ └──────────┘
     │
     ▼
┌──────────────────┐
│  检查结果         │
│  有失败 → 反馈LLM │
│  全成功 → 完成    │
└──────────────────┘
```

## 自定义工具

继承 `Tool` 基类即可快速创建新工具：

```python
from ahccli.tool import Tool

class MyTool(Tool):
    name = "my_tool"
    description = "我的自定义工具"
    parameters = {
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "查询内容"}
        },
        "required": ["query"],
    }
    is_readonly = True           # 只读标记
    is_concurrency_safe = True   # 并发安全标记

    async def execute(self, query: str = "", **kwargs) -> str:
        return f"查询结果: {query}"
```

## 开发

```bash
# 安装开发依赖
uv sync --all-extras

# 运行单元测试
uv run pytest tests/ -v

# 运行单个测试文件
uv run pytest tests/test_agent.py -v

# 代码检查
uv run python -m py_compile src/ahccli/agent.py
```

## 参与贡献

1. Fork 本仓库
2. 新建 `feat/xxx` 分支
3. 提交代码（确保测试通过）
4. 新建 Pull Request

## 许可证

[MIT License](LICENSE)