kiro-cli-agent-implementation.md 23 KB
FWH ToolBox Agent — Kiro CLI 配置实现方案
创建日期：2026-08-04 状态：方案设计（未实施）
目录
1. 概述
1.1 目标
创建名为 fwh-toolbox-agent 的 Kiro CLI Agent，用于：
- 通过 MCP Server 查询 FranklinWH ToolBox 的业务数据（站点、SIM卡、告警、停机、功率流等）
- 结合产品知识库和数据知识库，提供智能问答与数据分析
- 生成数据统计报告或技术文档（Excel/PDF/Markdown），通过临时目录或 MinIO 提供下载
- 提交问题反馈到 Plane 项目管理系统
1.2 核心约束
| 约束项 | 说明 |
|---|---|
| 不可修改源码 | Agent 完全没有项目源码的写权限 |
| 只读访问 | 可读取项目文件用于理解上下文 |
| 可创建临时文件 | 仅限指定临时目录，用于导出数据/文档 |
| MCP 数据接入 | 通过 stdio 模式的 MCP Server 获取业务数据 |
| 知识库驱动 | 两套知识库：产品知识 + 数据字段解释 |
1.3 技术架构
┌─────────────────────────────────────────────────┐
│ Kiro CLI Chat │
│ (fwh-toolbox-agent) │
├─────────────────────────────────────────────────┤
│ Tools: read, grep, glob, code, knowledge │
│ (无 write / shell 仅限安全命令) │
├──────────┬──────────────┬───────────────────────┤
│ MCP Server│ 知识库(产品) │ 知识库(数据) │
│ (stdio) │ Wiki MD源码 │ docs/knowledge │
└──────────┴──────────────┴───────────────────────┘
2. 配置文件清单
实施时需要创建/修改的文件：
.kiro/
├── agents/
│ └── fwh-toolbox-agent.json # Agent 主配置
├── steering/
│ └── fwh-toolbox-context.md # 业务上下文引导文件
├── settings/
│ └── cli.json # Workspace 级设置（可选）
└── skills/
└── data-export/
└── SKILL.md # 数据导出技能（按需加载）
3. Agent 配置详解
3.1 配置文件位置
.kiro/agents/fwh-toolbox-agent.json
3.2 配置结构说明
{
"name": "fwh-toolbox-agent",
"description": "FranklinWH ToolBox 数据查询与分析助手，可查询站点/SIM卡/告警/停机数据，生成统计报告，提交问题反馈",
"prompt": "file://.kiro/prompts/fwh-toolbox-agent.md",
// === 可用工具 ===
"tools": [
"read", // 读取文件
"grep", // 搜索文件内容
"glob", // 查找文件路径
"code", // 代码智能（AST搜索）
"knowledge", // 知识库检索
"shell", // Shell（严格限制）
"web_search", // 网页搜索（技术文档查找）
"web_fetch" // 网页抓取
],
// === 自动信任的工具（无需用户确认） ===
"allowedTools": [
"read",
"grep",
"glob",
"code",
"knowledge",
"web_search",
"web_fetch",
"@fwh-mcp/*"
],
// === 工具细粒度设置 ===
"toolsSettings": {
"shell": {
"allowedCommands": [
"date",
"cat /tmp/fwh-export/.*",
"ls /tmp/fwh-export/.*",
"wc .*"
],
"deniedCommands": [
"rm .*",
"mv .*",
"cp .*",
"sudo .*",
"chmod .*",
"chown .*",
"git .*",
"npm .*",
"pnpm .*",
"go .*"
],
"denyByDefault": true
},
"web_fetch": {
"trusted": [
".*docs\\.franklinwh\\.com.*",
".*franklinwh\\.com.*"
],
"blocked": [
".*github\\.com.*"
]
}
},
// === 上下文资源 ===
"resources": [
"file://docs/knowledge/**/*.md",
"skill://.kiro/skills/**/SKILL.md"
],
// === MCP Server ===
"mcpServers": {
"fwh-mcp": {
"command": "/var/www/fwh-toolbox/server/fwh-mcp-server",
"args": [],
"env": {},
"timeout": 30000
}
},
// === 欢迎消息 ===
"welcomeMessage": "FWH ToolBox Agent 已就绪。我可以帮你查询站点信息、SIM卡状态、告警/停机统计、功率流数据，也可以生成数据报告或提交问题反馈。请问有什么需要？"
}
3.3 字段说明
| 字段 | 用途 | 备注 |
|---|---|---|
name |
Agent 标识名 | 文件名必须与此一致（不含 .json） |
description |
简短描述 | 用于agent list 展示 |
prompt |
系统提示词 | 引用外部 md 文件，便于维护 |
tools |
可用工具白名单 | 不包含 write，确保无写权限 |
allowedTools |
自动信任列表 | 所有 MCP tools 自动信任 |
toolsSettings |
工具级别权限 | shell 严格限制为安全只读命令 |
resources |
始终加载的上下文 | 数据知识库 + 技能文件 |
mcpServers |
MCP 服务器定义 | stdio 模式本地二进制 |
3.4 关于 write 工具的缺失
设计决策：tools 列表中不包含 write 工具，这意味着 Agent 完全无法创建或修改任何文件。
文件生成替代方案（见第 6 节详述）：
- 通过
shell的白名单命令写入/tmp/fwh-export/目录 - 或扩展 MCP Server 增加文件导出相关 Tool
4. MCP Server 接入
4.1 服务信息
| 项目 | 值 |
|---|---|
| 二进制路径 | /var/www/fwh-toolbox/server/fwh-mcp-server |
| 通信模式 | stdio（标准输入/输出） |
| 协议 | MCP (Model Context Protocol) |
| 依赖 | 数据库(MySQL/PostgreSQL/MongoDB)、Redis、配置文件(.env) |
| 源码位置 | service/cmd/mcp/main.go |
| 部署脚本 | service/cmd/deploy_mcp.sh |
4.2 注册的 Tools 清单
| Tool 名称 | 功能描述 | 必选参数 | 可选参数 |
|---|---|---|---|
query_site_info |
查询单个站点设备详细信息（版本、网络、激活状态、固件、SN 等） | sn (站点序列号) |
— |
search_sites |
搜索站点设备列表，支持分页和关键字 | — | page, size, keyword |
query_power_flow |
查询站点指定日期的功率流数据（PV/Grid/aPower/HomeLoad/Generator） | sn, date (yyyy-MM-dd) |
— |
query_sim_card |
查询单张 SIM 卡详细信息（状态、平台、用量） | giccid (19位) |
— |
search_sim_cards |
搜索 SIM 卡列表，支持状态/平台过滤 | — | page, size, search, status, platform |
query_alarm_statistics |
查询告警统计数据（按日期汇总各类告警数量） | — | date (yyyy-MM-dd，不传则查最新) |
query_shutdown_statistics |
查询停机统计数据（按日期汇总停机站点信息） | — | date (yyyy-MM-dd，不传则查最新) |
create_feedback |
在 Plane 创建 Intake Issue（问题反馈/需求提交） | title, type (bug/feature) |
priority, description, category |
query_feedback_history |
查询 Plane Intake Issue 提交历史 | — | — |
4.3 Agent 配置中的 MCP 定义
"mcpServers": {
"fwh-mcp": {
"command": "/var/www/fwh-toolbox/server/fwh-mcp-server",
"args": [],
"env": {
// 若 MCP Server 需要额外环境变量可在此配置
// 例如："CONFIG_PATH": "/var/www/fwh-toolbox/server/.env"
},
"timeout": 30000
}
}
4.4 注意事项
- 工作目录问题：MCP Server 启动时的工作目录（cwd）决定了它能否找到
.env配置文件。Kiro CLI 以 stdio 模式启动 MCP 进程时，cwd 默认为 Kiro CLI 的当前目录（即项目根目录），而非/var/www/fwh-toolbox/server。
解决方案（任选其一）：
- (推荐) 在 MCP Server 代码中用绝对路径加载配置，不依赖 cwd
- 将
.env软链接到项目根目录 - 使用 wrapper script 先 cd 到目标目录再启动
- 进程冲突：如果 MCP Server 已通过 systemd 开机自启在后台运行，Kiro CLI 再启动一个新进程可能导致端口/资源冲突。但由于 MCP Server 使用 stdio 模式（无端口监听），且数据库连接是独立的，所以可以安全并行运行。
- 超时配置：默认 30 秒超时。若某些查询（如大范围搜索）耗时较长，可适当调大
timeout值。 - 环境变量传递：如果 MCP Server 的
.env依赖GIN_MODE、DB_HOST等环境变量，需要在env字段中显式传递，或确保这些变量在 Kiro CLI 的 shell 环境中已设置。
5. 知识库接入
5.1 两套知识库概览
| 知识库 | 用途 | 源路径 | 格式 |
|---|---|---|---|
| 产品知识库 | FranklinWH 产品硬件/软件/系统知识 | /home/jerry-remote/web/FranklinWH-Wiki/client/docs |
Markdown |
| 数据知识库 | 数据库字段解释、业务数据说明 | /home/jerry-remote/web/FranklinWH-ToolBox/docs/knowledge |
Markdown |
5.2 产品知识库
源路径：/home/jerry-remote/web/FranklinWH-Wiki/client/docs
内容分类：
docs/
├── Hardware/ # 硬件知识
│ ├── Gate/ # aGate 系列（1.0, 1.2, 1.3, MSA_C）
│ ├── Power/ # aPower 系列（1.0, 1.2, 1.3, 2, S）
│ └── Other/ # 其他配件（SplitCT, MeterKit, aPBox 等）
├── Software/ # 软件知识
│ ├── PCS.md # PCS 控制策略
│ ├── EnergyStatistics.md # 能量统计
│ ├── ScriptingForSchedulingConfiguration.md # 调度脚本
│ └── ... # OTA、VPP、黑启动、电池加热等
├── System/ # 系统知识
│ ├── AlarmTable.md # 告警代码表（重要！）
│ ├── EventMessage.md# 事件消息列表
│ ├── SystemConfig.md# 系统配置
│ └── SystemDistribution.md # 系统分布
└── Other/ # 其他
├── HostSideSoftware.md
└── TariffScheduleTemplates.md
接入方式 — Kiro Knowledge 工具索引：
# 在 Kiro CLI 中执行（首次需要手动索引）
/knowledge add "FWH-Wiki-产品知识库" /home/jerry-remote/web/FranklinWH-Wiki/client/docs
排除项（索引时应排除）：
.vitepress/— VitePress 配置和缓存public/— 静态资源（PDF、PPT、图片）index.md— 仅导航页，无实质内容casdoor/— 认证相关，非产品知识
为什么选择 Markdown 源码而非 HTML：
- Markdown 语义清晰，AI 理解效率高
- 文件体积小，索引速度快
- 直接与源码仓库同步，无需构建
- 无 HTML 标签/CSS/JS 噪音
5.3 数据知识库
源路径：/home/jerry-remote/web/FranklinWH-ToolBox/docs/knowledge
当前状态：目录已创建，内容待补充。
规划内容：
- 数据库表字段含义说明
- MCP Tool 返回数据字段解释
- 业务术语表（SN、GICCID、告警码含义等）
- 功率流数据解读指南
- 常见查询场景示例
建议的文件结构：
docs/knowledge/
├── README.md # 知识库说明
├── site-info-fields.md # 站点信息字段解释
├── power-flow-guide.md # 功率流数据解读
├── alarm-codes.md # 告警代码与严重程度
├── sim-card-status.md # SIM卡状态说明
├── shutdown-analysis.md # 停机统计分析指南
└── glossary.md # 业务术语表
接入方式：
# 数据知识库索引
/knowledge add "FWH-数据知识库" /home/jerry-remote/web/FranklinWH-ToolBox/docs/knowledge
5.4 知识库配置建议（Workspace Settings）
在 .kiro/settings/cli.json 中可配置知识库参数：
{
"knowledge.defaultIncludePatterns": ["**/*.md"],
"knowledge.defaultExcludePatterns": [
"**/node_modules/**",
"**/.vitepress/**",
"**/public/**",
"**/cache/**"
],
"knowledge.indexType": "best", // 语义搜索（推荐）
"knowledge.chunkSize": 1000,
"knowledge.chunkOverlap": 200
}
5.5 Agent resources 配置
对于始终需要加载的关键知识（如术语表），可通过 resources 字段直接引入：
"resources": [
"file://docs/knowledge/**/*.md", // 数据知识库全量加载
"skill://.kiro/skills/**/SKILL.md" // 技能按需加载
]
注意：产品知识库文件较多且体积大，不适合通过
resources全量加载到上下文，应通过knowledge工具按需检索。
6. 权限控制与文件生成策略
6.1 权限模型
┌─────────────────────────────────────────────────────────┐
│ 权限控制总览 │
├─────────────────────┬───────────────────────────────────┤
│ 读取项目文件 │ ✅ 允许（read/grep/glob/code） │
│ 修改项目源码 │ ❌ 禁止（不包含 write 工具） │
│ 执行 shell 命令 │ ⚠️ 严格白名单（denyByDefault） │
│ 调用 MCP Tools │ ✅ 允许（自动信任） │
│ 搜索知识库 │ ✅ 允许（自动信任） │
│ 创建临时文件 │ ✅ 仅限 /tmp/fwh-export/ 目录 │
│ 上传到 MinIO │ ✅ 通过扩展 MCP Tool 实现 │
└─────────────────────┴───────────────────────────────────┘
6.2 文件生成方案
由于 Agent 没有 write 工具，不能直接创建文件。需要通过以下两种方案实现文件生成：
方案 A：Shell 白名单 + 临时目录（轻量方案）
原理：在 shell 工具的 allowedCommands 中加入写入临时目录的命令。
配置：
"toolsSettings": {
"shell": {
"allowedCommands": [
"mkdir -p /tmp/fwh-export",
"tee /tmp/fwh-export/.*",
"cat .* > /tmp/fwh-export/.*",
"ls -la /tmp/fwh-export/.*",
"date",
"wc .*"
],
"deniedCommands": [
"rm -rf .*",
"sudo .*",
"chmod .*",
"chown .*"
],
"denyByDefault": true
}
}
限制：
- 只能生成纯文本/Markdown/CSV 文件
- 无法生成 Excel(.xlsx) 或 PDF 二进制文件
- 用户需要通过
scp或 SSH 文件浏览器下载
方案 B：扩展 MCP Server（推荐方案）
原理：在 MCP Server 中新增文件生成相关 Tool，由 Go 后端调用 excelize（Excel）或其他库生成文件，上传到 MinIO 并返回下载链接。
需要新增的 MCP Tools：
| Tool 名称 | 功能 | 参数 |
|---|---|---|
export_report |
生成数据统计报告 | type(excel/pdf/csv), template, data_query, expire_hours |
get_export_url |
获取已生成文件的下载链接 | file_id |
list_exports |
列出已生成的导出文件 | page, size |
实现示例（伪代码）：
// service/cmd/mcp/tools/export.go
func RegisterExportTools(s *server.MCPServer) {
s.AddTool(
mcp.NewTool("export_report",
mcp.WithDescription("生成数据统计报告并上传到 MinIO，返回有时效的下载链接"),
mcp.WithString("type", mcp.Required(), mcp.Description("文件类型：excel, pdf, csv, markdown")),
mcp.WithString("title", mcp.Required(), mcp.Description("报告标题")),
mcp.WithString("content", mcp.Required(), mcp.Description("报告内容（JSON 结构化数据或 Markdown 文本）")),
mcp.WithNumber("expire_hours", mcp.Description("下载链接过期时间（小时），默认 24")),
),
handleExportReport,
)
}
func handleExportReport(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
// 1. 解析参数
// 2. 根据 type 生成文件（excelize / go-pdf / csv / md）
// 3. 上传到 MinIO（设置过期策略）
// 4. 生成预签名下载 URL（带 expire_hours 过期）
// 5. 返回下载 URL 给 Agent
}
MinIO 过期策略：
- 使用 MinIO 的 Presigned URL（
GetPresignedURL），URL 自带过期时间 - 或配置 Bucket Lifecycle Rule，自动清理 N 天前的临时文件
- 建议 Bucket 名：
fwh-export-temp，Lifecycle 设为 7 天自动删除
优势：
- 可生成 Excel/PDF 等二进制格式
- 返回可直接访问的下载链接
- 过期自动清理，不占用长期存储
- Agent 只需描述要导出的数据，后端负责格式化
6.3 推荐实施路径
第一阶段：使用方案 A（shell 白名单写入临时目录）
↓ 验证 Agent 工作流可行
第二阶段：实现方案 B（MCP export_report Tool）
↓ 支持 Excel/PDF 二进制文件生成
第三阶段：前端集成下载入口（可选）
↓ ToolBox Web UI 中展示导出历史和下载链接
6.4 提示词中的权限引导
在 Agent 的系统提示词中需要明确告知权限限制：
## 权限说明
- 你没有写入项目文件的权限。如果用户要求修改代码，告知没有操作权限。
- 你可以通过 export_report 工具生成数据报告，会返回带过期时间的下载链接。
- 如果 export_report 工具不可用，你可以将内容输出为 Markdown 格式直接展示在对话中。
- 任何需要持久化的操作都应通过 MCP Tools 完成。
7. Steering 引导文件
7.1 文件位置
.kiro/steering/fwh-toolbox-context.md
7.2 内容规划
# FWH ToolBox Agent 业务上下文
## 产品背景
FranklinWH 是一家家用储能系统公司，核心产品包括：
- aGate：家庭能源管理网关（1.0/1.2/1.3/MSA_C 系列）
- aPower：储能逆变器（1.0/1.2/1.3/2/S 系列）
- 其他配件：SplitCT、MeterKit、aPBox、Generator Module
## ToolBox 平台说明
FWH ToolBox 是内部运维工具平台，提供：
- 站点设备信息管理与查询
- SIM 卡管理（SmartHub / Acceleronix 平台）
- 告警/停机统计分析
- 功率流数据可视化
- 固件配置管理
- 批量数据下载
- 问题反馈提交（对接 Plane 项目管理）
## 数据查询约定
- 站点通过 SN（序列号）唯一标识
- SIM 卡通过 GICCID（19位）唯一标识
- 日期格式统一为 yyyy-MM-dd
- 分页默认 page=1, size=10
## 回复规范
- 数据查询结果以结构化表格展示
- 告警代码需关联知识库中的 AlarmTable 解释含义
- 功率流数据回复时注明单位（W/kW/kWh）
- 涉及多个站点时优先汇总统计，再按需展开详情
7.3 Prompt 文件
建议创建独立的 prompt 文件，Agent 配置中通过 file:// 引用：
文件位置：.kiro/prompts/fwh-toolbox-agent.md
内容要点：
# FWH ToolBox Agent
你是 FranklinWH ToolBox 平台的数据查询与分析助手。
## 核心能力
1. 通过 MCP Tools 查询站点、SIM卡、告警、停机、功率流等业务数据
2. 结合产品知识库解答 FranklinWH 产品相关技术问题
3. 生成数据统计报告（Excel/PDF/Markdown）
4. 向 Plane 提交问题反馈和功能需求
## 权限约束
- ❌ 不能修改任何项目源码文件
- ❌ 不能执行危险 shell 命令
- ✅ 可以读取项目文件以理解代码逻辑
- ✅ 可以通过 MCP Tools 查询和操作业务数据
- ✅ 可以生成报告到临时目录或 MinIO
## 工作流程
1. 理解用户需求
2. 如需产品知识 → 检索知识库
3. 如需业务数据 → 调用 MCP Tools
4. 如需生成文件 → 调用 export_report 或输出 Markdown
5. 组织结果，清晰回复
## 回复风格
- 使用中文回复
- 数据展示优先使用表格格式
- 技术解释简洁清晰
- 不确定的信息明确标注