跳转至

第 4 章：本地完整验收

目标：在接入聊天平台之前，先在本地完成"人格 + 规则 + Skill"的组合验收，确保 Bot 本身没问题。

4.1 为什么要单独做一次本地验收？

很多人会在接入 Telegram 或 Discord 后遇到"Bot 不回复"或"回复不对"的问题，然后陷入困惑：

1
2
3
4
是 Telegram 没接通？
还是配置文件写错了？
还是 Skill 没触发？
还是 API Key 有问题？

这些问题混在一起很难排查。

更好的做法是：

flowchart LR
    A[第1-3章<br/>单独验证各部分] --> B[第4章<br/>本地完整验收]
    B --> C[第5章<br/>接入聊天平台]

    style B fill:#90EE90

这一章的目标： 在 CLI 中完成一次完整的端到端测试，确认： - ✅ 人格（SOUL.md）生效 - ✅ 规则（AGENTS.md）生效 - ✅ 用户画像（USER.md）生效 - ✅ Skill 能正常触发 - ✅ 工具调用能正常执行

只有这些都验证通过，下一章接平台时才能快速定位问题。

4.2 准备：确认前三章的成果

在开始本地验收前，先确认你已经完成：

检查清单

  • [ ] 第 1 章成果：nanobot agent -m "你好" 能返回正常回复
  • [ ] 第 2 章成果：修改过 SOUL.md 或 AGENTS.md，并看到回复风格变化
  • [ ] 第 3 章成果：至少有一个自定义 Skill（如 exchange-rate）

如果有任何一项还没完成，建议先回到对应章节。

4.3 设计一个完整的 Bot

现在我们把前三章的内容组合起来，做一个个人财务顾问 Bot。

你也可以选择其他主题（个人助理、技术支持等），但第一次建议跟着这个示例走完，确保理解整个流程。

目标场景

做一个能做到以下事情的 Bot： - 📊 财务规划建议（体现人格和规则） - 💱 汇率查询（体现 Skill 集成） - 📈 数据搜索（体现工具调用） - 🎯 个性化回复（体现用户画像）

4.4 配置分层上下文

这里不再使用“四个文件”的旧模型。三个 Bootstrap、Dream 管理的长期 Memory 和按需加载的 Skill 各自承担不同职责。

SOUL.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
# Soul

我是 FinBot，一个专业、谨慎、结构化的个人财务顾问。

## Personality

- 严谨、克制、清晰
- 不夸大收益，不故作确定
- 面对不完整信息时先补充假设

## Values

- 用户的财务安全优先于"听起来厉害"
- 不推荐自己无法解释清楚的产品
- 尊重风险承受能力差异

## Communication Style

- 先总结问题，再分析，再给建议
- 涉及金额时注明币种
- 重要风险单独列出

AGENTS.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
# Agent Instructions

你是一个个人财务顾问 Bot。

## 回答流程

1. **问题理解**：先复述问题，确认理解
2. **关键信息**：列出已知条件和需要补充的假设
3. **分析过程**：逐步推理，不要直接跳结论
4. **具体建议**：可行的下一步行动
5. **风险提示**：潜在风险和注意事项

## 禁止事项

- 不给出具体股票买卖时机建议
- 不承诺收益
- 不把教育性信息说成个性化投资建议
- 涉及复杂金融产品时，提醒用户咨询持牌顾问

## 数据规则

- 外部数据必须注明来源和实际查询时间
- 查询失败时说明失败原因，不用记忆中的旧数值冒充实时数据

## 回复格式

使用以下结构（每部分用 ## 标题分隔）：

## 问题理解
（复述用户问题）

## 关键信息
（列出已知条件和假设）

## 分析
（逐步推理）

## 建议
（具体可行的建议）

## 风险提示
（潜在风险）

USER.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# User Profile

## Basic Information

- **Name**: 小明
- **Language**: 中文
- **Timezone**: UTC+8

## Financial Profile

- 年龄段：30岁左右
- 月收入：约 2 万元
- 风险偏好：稳健型
- 关注领域：储蓄、指数基金、保险
- 投资经验：初级（了解基础概念，但没有实操经验）

## Preferences

- **输出偏好**：喜欢表格和分点说明，不喜欢大段文字
- **默认币种**：人民币（CNY）
- **数据要求**：涉及汇率或市场数据时，说明数据来源和查询时间

## Context

- 目前没有股票或基金投资
- 有一定存款，想开始理财但不知道从哪里入手
- 对风险比较谨慎，不接受可能本金损失的投资

memory/MEMORY.md 的目标状态

1
2
3
4
5
# Long-term Memory

- FinBot 项目的目标是提供个人财务教育信息，不替代持牌顾问。
- 任何市场数据都必须区分查询结果、用户输入和模型假设。
- 当前项目仍处于本地验收阶段，尚未接入聊天 Channel。

这是经过一段使用后，Dream 可能整理出的长期项目事实示意，不是要求你现在手工覆盖 Memory。用户的收入和表达偏好属于 USER.md；查询命令、API URL 和参数属于 Skill；密钥不应进入任何 Memory 文件。

工具策略如何归类

  • “谨慎处理高风险操作、承认不确定性”属于 SOUL.md 的行为护栏；
  • “本项目输出必须注明数据来源和查询时间”属于 AGENTS.md 的验收规则；
  • “如何查询和换算汇率、失败时如何处理”属于下面的 exchange-rate Skill；
  • 文件范围、命令隔离和网络限制属于配置与运行环境，不靠 Markdown 保证。

Skill：exchange-rate

确保你已经创建了 ~/.nanobot/workspace/skills/exchange-rate/SKILL.md（第 3 章的示例）。

如果还没创建，回到 第 3 章 3.4 节 完成。

4.5 三轮验收对话

现在用三轮对话来验证整个系统是否正常工作。

验收原则

每轮对话都有明确的检查点，不要凭感觉判断"差不多可以了"。

建议把实际的输入输出记录下来，方便后续排查问题。

第 1 轮：验证人格和规则

目标： 确认 SOUL.md 和 AGENTS.md 生效

输入： 

1
nanobot agent -m "我每个月能存 5000 元，应该先做什么理财准备？"

检查点：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
## 检查清单

- [ ] **复述问题**：回复开头先复述了用户问题
- [ ] **结构化回复**：有明确的分段（问题理解、关键信息、分析、建议、风险提示）
- [ ] **谨慎语气**：没有"保证收益"、"稳赚不赔"这类表述
- [ ] **补充假设**：如果信息不完整，列出了需要补充的假设
- [ ] **风险提示**：单独列出了潜在风险

## 示例输出（参考）

## 问题理解
您每月可以存下 5000 元，想知道应该优先做哪些理财准备。

## 关键信息
已知：
- 月度可支配资金：5000 元
- 理财经验：初级

需要补充的假设：
- 假设您目前没有紧急备用金
- 假设没有高息负债
- 假设基本保障（社保）已覆盖

## 分析
...（逐步推理）...

## 建议
1. 建立紧急备用金（3-6个月生活费）
2. 配置基础保险
3. ...

## 风险提示
- 不要一次性投入所有资金
- ...

如果没通过： - 没有结构化回复 → 检查 AGENTS.md 是否保存、格式是否正确 - 语气不对 → 检查 SOUL.md 中的 Personality 和 Values - 直接跳结论 → 强化 AGENTS.md 中的"回答流程"

第 2 轮：验证用户画像

目标： 确认 USER.md 生效

输入： 

1
nanobot agent -m "按我的风险偏好和收入水平，你会优先建议哪些投资方向？"

检查点：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
## 检查清单

- [ ] **引用风险偏好**：回复中明确提到"稳健型"或等价表述
- [ ] **引用收入水平**：考虑了"月收入 2 万元"这个背景
- [ ] **默认币种**：涉及金额时默认用人民币
- [ ] **输出格式**：使用了表格或分点说明（符合用户偏好）
- [ ] **考虑投资经验**：没有推荐复杂的金融产品

## 示例输出（参考）

根据您的情况：
- 风险偏好：稳健型
- 月收入：约 2 万元
- 投资经验：初级

建议的投资方向优先级：

| 优先级 | 投资方向 | 月度建议金额 | 风险等级 |
|--------|---------|-------------|---------|
| 1 | 货币基金（紧急备用金） | 2000-3000 元 | 极低 |
| 2 | 宽基指数基金（定投） | 1000-2000 元 | 中低 |
| 3 | 债券基金 | 500-1000 元 | 低 |

注：金额以人民币（CNY）计算

如果没通过： - 没引用用户信息 → 检查 USER.md 是否保存在正确位置 - 币种不对 → 检查 USER.md 中的 Preferences - 输出格式不符 → 强化 USER.md 中的"输出偏好"描述

第 3 轮：验证 Skill 和工具调用

目标： 确认 exchange-rate Skill 能正常触发

输入： 

1
nanobot agent -m "1000 美元大概等于多少人民币？请说明你使用了什么数据来源。"

检查点：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
## 检查清单

- [ ] **终端显示工具调用**：看到了 `[Tool] read_file(...)` 或类似日志
- [ ] **终端显示命令执行**：看到了 `[Tool] exec(command="curl ...")` 或类似日志
- [ ] **给出换算结果**：回复根据本次响应里的动态汇率计算出明确结果
- [ ] **说明数据来源**：提到了 ExchangeRate-API 或类似来源
- [ ] **标注时效性**：提到"当前汇率"、"查询时间"等时间性表述

## 示例输出（参考）

让我查询最新汇率...

[终端会显示工具调用过程]
🔧 Tool: read_file(path="~/.nanobot/workspace/skills/exchange-rate/SKILL.md")
🔧 Tool: exec(command="curl -s 'https://open.er-api.com/v6/latest/USD' | python3 -c ...")

根据查询结果：

1000 美元（USD）≈ 本次查询结果中的人民币金额（CNY）

**数据来源**：ExchangeRate-API (https://open.er-api.com)
**汇率**：使用本次 API 响应中的 USD/CNY 值
**查询时间**：使用实际执行时间

注：汇率实时波动，建议交易时以实际银行汇率为准。

如果没通过：

症状 可能原因 排查方法
没有工具调用日志 Skill 没触发 回到第 3 章的诊断树
curl 命令报错 网络问题或依赖缺失 手动运行命令测试
返回了数字但没说数据来源 项目验收规则或 Skill 描述不清 检查 AGENTS.md 与 Skill 正文
直接给了一个大概值（没查询） 模型选择直接回答 改用更明确的提问方式

4.6 验收记录模板

建议你真的手动记录这三轮对话，不要只凭感觉判断。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
# FinBot 本地验收记录

## 第 1 轮：人格和规则

**输入：**
我每个月能存 5000 元，应该先做什么理财准备？

**输出：**
（粘贴完整回复）

**检查结果：**
- [x] 复述问题
- [x] 结构化回复
- [x] 谨慎语气
- [ ] 补充假设（未体现）
- [x] 风险提示

**备注：**
"补充假设"部分不明显，需要在 AGENTS.md 中强化这一条规则。

---

## 第 2 轮：用户画像

**输入：**
按我的风险偏好和收入水平，你会优先建议哪些投资方向？

**输出：**
（粘贴完整回复）

**检查结果：**
- [x] 引用风险偏好
- [x] 引用收入水平
- [x] 默认币种
- [x] 输出格式（表格）
- [x] 考虑投资经验

---

## 第 3 轮：Skill 和工具

**输入：**
1000 美元大概等于多少人民币？请说明你使用了什么数据来源。

**输出：**
（粘贴完整回复）

**终端日志：**
（粘贴工具调用日志）

**检查结果：**
- [x] 终端显示工具调用
- [x] 终端显示命令执行
- [x] 给出换算结果
- [x] 说明数据来源
- [x] 标注时效性

---

## 总体评价

✅ 全部通过 / ⚠️ 部分通过 / ❌ 未通过

**需要改进的地方：**
1. ...
2. ...

4.7 常见问题排查

问题 1：人格和规则不稳定

症状： 有时候遵守规则，有时候不遵守

可能原因： - 规则写得太抽象或太长 - 不同文件之间有冲突 - 模型能力不足或 temperature 太高

解决方案： 1. 简化规则，用具体的例子而不是抽象描述 2. 检查 SOUL.md、AGENTS.md、USER.md 是否有相互矛盾的内容 3. 降低 temperature（在 config.json 中配置）

问题 2：Skill 触发不稳定

症状： 同样的问题，有时候触发 Skill，有时候不触发

解决方案： 1. 改进 description，包含更多关键词 2. 在提问中明确提到"请使用 XXX skill" 3. 检查是否有其他 Skill 的 description 与之冲突 4. 降低 temperature

问题 3：工具调用失败

症状： Skill 触发了，但工具调用报错

排查步骤： 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
# 1. 手动测试命令
curl -s "https://open.er-api.com/v6/latest/USD" | python3 -c "
import sys, json
data = json.load(sys.stdin)
print(data['rates']['CNY'])
"

# 2. 检查依赖
which curl
which python3

# 3. 检查网络
curl -I https://open.er-api.com

# 4. 在交互模式查看运行日志并复现
nanobot agent --logs

4.8 进阶：多场景测试

如果三轮验收都通过了，可以继续测试更多场景：

场景 A：复杂问题（多轮对话）

1
2
3
第1轮：我想开始定投指数基金，但不知道选哪个
第2轮：那沪深300和中证500有什么区别？
第3轮：按我的情况，你更推荐哪个？

检查： Bot 是否记住了前面的上下文

场景 B：边界情况

1
我有 100 万人民币，想一次性投入股市，你有什么建议？

检查： Bot 是否会警告这违反了它的价值观（"用户财务安全优先"）

场景 C：知识边界

1
你觉得比特币未来会涨到多少？

检查： Bot 是否会拒绝预测，并解释原因

4.9 小结

完成这一章后，你应该确认：

验收项 状态
人格和规则生效 ✅
用户画像生效 ✅
Skill 能触发 ✅
工具调用能执行 ✅
有完整的验收记录 ✅

只有这些都确认通过，才建议进入下一章接入聊天平台。

下一步

✅ 如果全部验收通过 → 继续 第 5 章：部署到 Telegram

⚠️ 如果部分验收失败 → 回到对应章节： - 人格/规则问题 → 第 2 章 - Skill 问题 → 第 3 章 - 基础配置问题 → 第 1 章

❌ 如果不知道问题在哪 → 去 附录：常见坑与排障