# FWH ToolBox Agent — Kiro CLI 配置实现方案

> 创建日期：2026-08-04
> 状态：方案设计（未实施）

---

## 目录

1. [概述](#1-概述)
2. [配置文件清单](#2-配置文件清单)
3. [Agent 配置详解](#3-agent-配置详解)
4. [MCP Server 接入](#4-mcp-server-接入)
5. [知识库接入](#5-知识库接入)
6. [权限控制与文件生成策略](#6-权限控制与文件生成策略)
7. [Steering 引导文件](#7-steering-引导文件)
8. [启动与使用方式](#8-启动与使用方式)
9. [注意事项与限制](#9-注意事项与限制)
10. [后续扩展计划](#10-后续扩展计划)

---

## 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 配置结构说明

```jsonc
{
  "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 定义

```jsonc
"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 注意事项

1. **工作目录问题**：MCP Server 启动时的工作目录（cwd）决定了它能否找到 `.env` 配置文件。Kiro CLI 以 stdio 模式启动 MCP 进程时，cwd 默认为 Kiro CLI 的当前目录（即项目根目录），而非 `/var/www/fwh-toolbox/server`。

   **解决方案**（任选其一）：

   - **(推荐)** 在 MCP Server 代码中用绝对路径加载配置，不依赖 cwd
   - 将 `.env` 软链接到项目根目录
   - 使用 wrapper script 先 cd 到目标目录再启动
2. **进程冲突**：如果 MCP Server 已通过 systemd 开机自启在后台运行，Kiro CLI 再启动一个新进程可能导致端口/资源冲突。但由于 MCP Server 使用 stdio 模式（无端口监听），且数据库连接是独立的，所以**可以安全并行运行**。
3. **超时配置**：默认 30 秒超时。若某些查询（如大范围搜索）耗时较长，可适当调大 `timeout` 值。
4. **环境变量传递**：如果 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 工具索引**：

```bash
# 在 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                  # 业务术语表
```

**接入方式**：

```bash
# 数据知识库索引
/knowledge add "FWH-数据知识库" /home/jerry-remote/web/FranklinWH-ToolBox/docs/knowledge
```

### 5.4 知识库配置建议（Workspace Settings）

在 `.kiro/settings/cli.json` 中可配置知识库参数：

```jsonc
{
  "knowledge.defaultIncludePatterns": ["**/*.md"],
  "knowledge.defaultExcludePatterns": [
    "**/node_modules/**",
    "**/.vitepress/**",
    "**/public/**",
    "**/cache/**"
  ],
  "knowledge.indexType": "best",   // 语义搜索（推荐）
  "knowledge.chunkSize": 1000,
  "knowledge.chunkOverlap": 200
}
```

### 5.5 Agent resources 配置

对于始终需要加载的关键知识（如术语表），可通过 `resources` 字段直接引入：

```jsonc
"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` 中加入写入临时目录的命令。

**配置**：

```jsonc
"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`                                                      |

**实现示例（伪代码）**：

```go
// 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 的系统提示词中需要明确告知权限限制：

```markdown
## 权限说明
- 你没有写入项目文件的权限。如果用户要求修改代码，告知没有操作权限。
- 你可以通过 export_report 工具生成数据报告，会返回带过期时间的下载链接。
- 如果 export_report 工具不可用，你可以将内容输出为 Markdown 格式直接展示在对话中。
- 任何需要持久化的操作都应通过 MCP Tools 完成。
```

---

## 7. Steering 引导文件

### 7.1 文件位置

```
.kiro/steering/fwh-toolbox-context.md
```

### 7.2 内容规划

```markdown
# 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`

**内容要点**：

```markdown
# 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. 组织结果，清晰回复

## 回复风格
- 使用中文回复
- 数据展示优先使用表格格式
- 技术解释简洁清晰
- 不确定的信息明确标注
```