197 lines
6.3 KiB
Markdown
197 lines
6.3 KiB
Markdown
# LaodingBot 技术说明文档（2026-02-28 最新实现）
|
||
|
||
> 本文档基于当前代码状态，描述真实可运行架构与能力边界。
|
||
|
||
---
|
||
|
||
## 1. 项目定位
|
||
|
||
LaodingBot 当前已从“单进程工具调用 MVP”演进为：
|
||
- **父进程 Agent 编排**（技能路由 + ReAct + 记忆）
|
||
- **子进程 ToolHost 执行**（JSON-RPC）
|
||
- **workspace 隔离运行空间**（配置与工具权限收敛）
|
||
- **能力缺口闭环**（落库、聚类、自动生成技能并热加载）
|
||
|
||
核心目标：让 Agent 在安全边界内持续补全能力，而不是仅做静态问答。
|
||
|
||
---
|
||
|
||
## 2. 目录与模块
|
||
|
||
- `cmd/bot/main.go`：应用入口、workspace 引导、toolhost 启动、通道分发
|
||
- `internal/config/config.go`：配置加载、workspace 路径解析、安全策略归一化
|
||
- `internal/runtimews/bootstrap.go`：运行时 workspace 准备与种子目录复制
|
||
- `internal/agent/orchestrator.go`：主编排器（技能匹配、ReAct、能力缺口闭环）
|
||
- `internal/toolhost/*`：工具子进程协议、服务端、客户端、远程工具适配
|
||
- `internal/tools/filetool/filetool.go`：文件工具（`read/list/write`）
|
||
- `internal/tools/shelltool/shelltool.go`：命令工具（白名单 + 超时 + 输出限制）
|
||
- `internal/memory/store_sqlite.go`：消息与能力缺口存储、聚类查询
|
||
- `internal/knowledge/loader.go`：skill/soul 加载
|
||
- `internal/knowledge/drafts.go`：能力缺口驱动的 skill 自动生成
|
||
|
||
---
|
||
|
||
## 3. 启动链路（当前）
|
||
|
||
`main()` 执行顺序：
|
||
1. 建立可取消上下文（SIGINT/SIGTERM）。
|
||
2. 调用 `runtimews.PrepareFromEnv()`：
|
||
- 解析 `AGENT_WORKSPACE_DIR`（默认 `./workspace/agent_runtime`）
|
||
- 将 `configs/data/skills/bot_context` 种子复制到 runtime workspace（缺失才复制）
|
||
- 设定 `CONFIG_ENV_FILE=<workspace>/configs/env`
|
||
3. 调用 `config.Load()`，优先读取 workspace env。
|
||
4. 若 `--toolhost` 模式，进入子进程服务。
|
||
5. 正常父进程：初始化日志、SQLite、ToolHost Client、知识、Orchestrator。
|
||
6. 根据 `MESSAGE_CHANNEL` 启动 Telegram 或 Feishu transport。
|
||
|
||
---
|
||
|
||
## 4. 配置加载与优先级（关键变更）
|
||
|
||
`config.Load()` 的 env 读取优先级：
|
||
1. `CONFIG_ENV_FILE`（强覆盖）
|
||
2. `<workspace>/configs/env` 与 `<workspace>/.env`（强覆盖）
|
||
3. 根目录 `configs/env` 与 `.env`（仅兜底，不覆盖已有值）
|
||
|
||
这保证 VS Code Debug 场景下，**workspace 配置优先于根目录配置**。
|
||
|
||
### 关键配置
|
||
- `REACT_MAX_STEPS`：必须来自 env（无代码默认值）
|
||
- `AGENT_WORKSPACE_DIR`：agent 运行空间根目录
|
||
- `ALLOWED_DIRS` / `ALLOWED_COMMANDS` / `WORK_DIR`：工具安全边界
|
||
- `AUTO_SKILL_DIR`：自动生成 skill 的目标目录（默认 workspace/skills）
|
||
- `GAP_DRAFT_TRIGGER_COUNT` / `GAP_CLUSTER_LOOKBACK_HOURS`：缺口聚类触发参数
|
||
|
||
---
|
||
|
||
## 5. workspace 隔离策略
|
||
|
||
当前实现中，Agent 与工具默认都在 workspace 内高权限运行：
|
||
- 相对路径统一按 `AGENT_WORKSPACE_DIR` 解析
|
||
- `ALLOWED_DIRS` 强制补齐：
|
||
- workspace 根
|
||
- `workspace/skills`
|
||
- `workspace/data`
|
||
- `workspace/workspace`
|
||
- `ALLOWED_COMMANDS` 自动补齐：`go`、`curl`、`curl.exe`
|
||
|
||
`filetool` 对相对路径优先按 workspace 根解析，避免写到代码仓库根目录。
|
||
|
||
---
|
||
|
||
## 6. ToolHost 子进程架构
|
||
|
||
当前工具调用已迁移到 JSON-RPC 子进程：
|
||
- 协议方法：`ping`、`tool.list`、`tool.call`
|
||
- 父进程 `Client` 能力：
|
||
- 调用超时
|
||
- 心跳检测
|
||
- 失败重启与重试
|
||
- 并发限制（信号量）
|
||
- 子进程 stdout 仅承载协议数据（避免日志污染 RPC）
|
||
|
||
效果：工具崩溃不会直接拖垮 Agent 主编排逻辑。
|
||
|
||
---
|
||
|
||
## 7. ReAct 与技能路由
|
||
|
||
`Orchestrator` 流程：
|
||
1. 保存用户消息到 SQLite
|
||
2. 读取最近对话并压缩
|
||
3. LLM 进行技能路由（最多命中 2 个）
|
||
4. 若无技能命中：尝试回退到 `创建skill` 技能
|
||
5. 进入 ReAct 多轮决策（`action/final`）
|
||
6. 工具调用观察写入 scratchpad
|
||
7. 保存 assistant 回复
|
||
|
||
工具错误会结构化为：
|
||
- `ERROR_CODE=...; TOOL=...; REASON=...`
|
||
|
||
---
|
||
|
||
## 8. 能力缺口闭环（已落地）
|
||
|
||
当出现“不会做”信号（如无 skill、解析失败、工具失败）时：
|
||
1. 写入 `capability_gaps` 表
|
||
2. 进行意图归一化聚类（按 `intent_key + reason`）
|
||
3. 高频达到阈值后自动生成 skill 文件
|
||
4. 自动调用 `ReloadSkills()` 热加载
|
||
|
||
可通过消息命令查看与控制：
|
||
- `/capability_gaps`：输出当前高频缺口清单
|
||
- `/reload_skills`：手动热加载 skills
|
||
|
||
---
|
||
|
||
## 9. 自动生成 skill 的当前行为
|
||
|
||
自动生成由 `internal/knowledge/drafts.go` 执行：
|
||
- 目标目录：`AUTO_SKILL_DIR`（默认 workspace/skills）
|
||
- 命名：`auto_<intent_key>/skill.md`
|
||
- 仅在文件不存在时创建，避免重复覆盖
|
||
- 模板内包含：触发背景、执行流程、工具建议、测试建议
|
||
|
||
并额外提供基础引导技能：
|
||
- `skills/skill_builder/skill.md`
|
||
|
||
---
|
||
|
||
## 10. file/shell 工具现状
|
||
|
||
### file tool
|
||
支持：
|
||
- `read <path>`
|
||
- `list <path>`
|
||
- `write <path>\n<content>`
|
||
|
||
特性：
|
||
- 白名单路径检查
|
||
- 目录误读防护：`read` 目录返回 `PATH_IS_DIRECTORY`
|
||
- 输出长度限制
|
||
|
||
### shell tool
|
||
特性：
|
||
- 命令白名单（首 token）
|
||
- 超时中断
|
||
- 固定工作目录
|
||
- 输出截断
|
||
- Windows 不可执行命令友好报错
|
||
|
||
---
|
||
|
||
## 11. 数据存储
|
||
|
||
SQLite 表：
|
||
1. `messages`：对话消息
|
||
2. `capability_gaps`：能力缺口事件
|
||
|
||
提供查询：
|
||
- 最近消息
|
||
- 最近缺口事件
|
||
- 高频缺口聚类（含计数与最近出现时间）
|
||
|
||
---
|
||
|
||
## 12. 与最初文档相比的变化
|
||
|
||
当前代码已经完成并替代旧文档中的以下“待实现项”：
|
||
- ToolHost 子进程隔离（已实现）
|
||
- 能力缺口闭环（已实现）
|
||
- 自动 skill 生成与热加载（已实现）
|
||
- workspace 配置优先与运行空间隔离（已实现）
|
||
|
||
仍属于持续演进项：
|
||
- 新工具代码自动注册与生效的全自动化流水线
|
||
- 更细粒度权限域（按 skill/tool 分级）
|
||
- 更强的自动化验收（e2e + 故障注入）
|
||
|
||
---
|
||
|
||
## 13. 下一步建议
|
||
|
||
1. 为 `toolhost client/server` 增加专项故障单测（心跳失败、子进程崩溃、并发压力）。
|
||
2. 增加“自动生成 tool 后自动接线注册”的流水线模块。
|
||
3. 为 skill 自动生成增加结构门禁（frontmatter/章节完整性校验）。
|
||
4. 引入操作审计视图，串联 trace_id 与 capability_gap。
|