Agent 管理
Agent 是 WesCraft 中 AI 助手的配置单元。不同的 Agent 可以拥有不同的认知配置、工具权限和模型选择。
Agent 概念
Agent 是 Cell 内的次级隔离单元：
- 共享 Cell 物理资源（数据库、存储）
- 独立认知配置（系统提示词、工具 ACL、模型选择）
- 命名空间隔离：
agent://X/*（Agent 独有）与cell://*（Cell 共享）
┌── Cell（物理隔离域）──────────────────┐
│ │
│ ┌── Agent A ──┐ ┌── Agent B ──┐ │
│ │ prompt-A │ │ prompt-B │ │
│ │ tools: 全部 │ │ tools: 只读 │ │
│ │ model: 4o │ │ model: mini │ │
│ │ agent://A/* │ │ agent://B/* │ │
│ └─────────────┘ └─────────────┘ │
│ │
│ cell://* (共享记忆、知识库等) │
└───────────────────────────────────────┘
预装 Agent
WesCraft 预装了一组 AI 助手，通过 builtinskills.go 内嵌到应用中：
// builtinskills.go
//go:embed skills
var SkillsFS embed.FS
预装 Agent 在 Cell 首次启动时通过 cell.Skills().Install() 装入：
// 装配路径
seedBuiltinSkills(cell) // 通过 cell.Skills().Install(tarStream)
默认 Agent
| Agent | 用途 | 工具集 |
|---|---|---|
| 通用助手 | 日常对话、写作、问答 | 全部 19 个工具 |
| 文件分析 | 分析本地文件 | 文件智能 5 个 |
| 内容编辑 | 页面编辑和排版 | Block 操作 6 个 |
| 数据管理 | 数据表查询和管理 | db_query / db_insert / db_update |
Agent CRUD
列出所有 Agent
GET /cells/{cellID}/agents
返回当前 Cell 中所有已注册的 Agent 列表。
注册/更新 Agent
POST /cells/{cellID}/agents
{
"id": "my-agent",
"name": "自定义助手",
"system_prompt": "你是一个专业的法律顾问...",
"model": "gpt-4o",
"skills": ["legal-review", "contract-analysis"]
}
获取单个 Agent
GET /cells/{cellID}/agents/my-agent
删除 Agent
DELETE /cells/{cellID}/agents/my-agent
Agent 与 Skill 的关系
Skill 过滤器
AgentConfig.Skills 是一个过滤器，控制 Agent 可以使用哪些 Skill：
| 配置值 | 含义 |
|---|---|
nil（未设置） | 使用全量 Skill |
["skill-a", "skill-b"] | 只使用指定 Skill |
[]（空数组） | 不使用任何 Skill |
双层白名单
Skill 可见性由两层过滤 AND 生效：
Cell 层：DisabledEngineSkills × Agent 层：Skills allowlist
| Cell 层 | Agent 层 | 结果 |
|---|---|---|
| 未禁用 | 包含 | ✅ 可用 |
| 未禁用 | 不包含 | ❌ 不可用 |
| 已禁用 | 包含 | ❌ 不可用 |
| 已禁用 | 不包含 | ❌ 不可用 |
Skill 类型
| 类型 | 来源 | 说明 |
|---|---|---|
| Tier E | wesgine embed | 引擎内置，所有 Agent 默认可见 |
| Tier C | cell.Skills().Install() | 应用自带或用户安装，per-Cell |
WesCraft 的预装 Skill 通过 skills/ 目录 + builtinskills.go embed 装到 Cell（Tier C）。
Agent 与工具的关系
工具体系
Agent 可使用的工具来源：
19 个 wescraft 专属工具（cell.Tools().Register）
+
wesgine 标准工具（read / write / exec / grep 等）
+
MCP 代理工具（cell.MCPs() 注入的外部工具）
=
Agent 的完整工具集
工具装配
所有工具通过 internal/tools/register.go 装到 Cell：
func Register(cell *wesgine.Cell) {
// Block 操作
cell.Tools().Register(readBlockTool)
cell.Tools().Register(writeBlockTool)
cell.Tools().Register(editBlockTool)
// ...
// 文件智能
cell.Tools().Register(searchFilesTool)
cell.Tools().Register(readLocalFileTool)
// ...
// 输出
cell.Tools().Register(exportPdfTool)
// ...
}
CycleDetector 工具分类
WesCraft 的 19 个工具在 CycleDetector 中有明确分类：
| 分类 | 工具 | streak 行为 |
|---|---|---|
| exploration | 10 个只读工具 | 宽松阈值 |
| progressAware | 5 个 Block 写入 | 参数变化时 /= 2 |
| action（默认） | 4 个其他写入 | 标准阈值 |
Agent 切换
在不同 AI 模式中选择 Agent
| AI 模式 | Agent 选择 |
|---|---|
| Ghost Write | 使用默认 Agent |
| Selection Action | 使用默认 Agent |
| Inline Command (Ctrl+K) | 可选择指定 Agent |
| Sidebar Chat (Ctrl+L) | 可切换 Agent |
| 后台 AI | 使用默认 Agent |
切换方式
在 Sidebar Chat 中，通过顶部的 Agent 选择器切换当前使用的 Agent。切换后：
- 系统提示词更新为新 Agent 的配置
- 可用工具集按新 Agent 的权限过滤
- 模型可能切换（如果 Agent 指定了不同模型）
- 对话历史保持不变
最佳实践
- 场景化 Agent：为不同场景创建专用 Agent（写作、数据分析、研究等）
- 最小工具集：给每个 Agent 只分配需要的工具，减少干扰
- 定制提示词：为 Agent 编写清晰的系统提示词，定义角色和行为
- 合理分配模型：简单任务用小模型（省成本），复杂任务用大模型（保质量）
- Skill 按需加载：通过 Skills 过滤器只加载相关 Skill