MNS 操作手册（面向 Agent）#

0. 先读这三条硬约束#

① mns buy / mns sell 是记账，不是下单。 MNS 不连接任何券商。这两个命令的唯一用途是把 用户已经在券商完成的 交易登记进本地账本。

• ✅ 用户说"我刚买了 100 份 QQQ，成交价 450" → mns buy QQQ 100 450
• ❌ mns report 建议买入 ¥2000 → 不要 据此调用 mns buy

记入一笔并未真实发生的交易，会同时污染现金余额、成本价、持有天数、收益率和后续所有调仓建议，且没有撤销命令。 不确定用户是否真的成交过，就先问。

② 建议不是投资建议。 mns report 的输出是规则引擎的机械计算结果。向用户转述时要说明它来自什么规则，不要包装成推荐意见，也不要替用户做买卖决定。用户自己的判断和持牌顾问才是决策来源。

③ 数字只能来自命令输出。 不要凭记忆或推算填写价格、份额、收益率。拿不到数据就说拿不到——不要编。

---

1. 安装与可用性检查#

执行任何操作前，先判断 mns 是否已安装可用，不要重复安装。

bash

mns --version

• 输出正常版本号 → 已安装，直接跳到第 2 节使用即可。
• 报 command not found / 找不到命令 → 执行下方安装步骤。

通过 npm 安装（会按当前系统自动拉取对应平台的预编译二进制，支持 macOS Apple Silicon / Linux x64 / Windows x64）：

bash

npm install -g @never-sleeps/mns-cli

安装完成后重新执行 mns --version 复核。若已执行过安装且 mns --version 仍失败，说明是 PATH 未生效或当前平台/架构暂无预编译包，直接向用户反馈原因即可， 不要 反复重跑安装命令。

---

2. 命令速查（语法已逐条实测）#

命令作用备注mns init初始化配置与数据库会清空既有数据，有确认提示； --force 跳过确认mns cash查看现金余额mns cash set <金额>设为指定余额覆盖式mns cash add <金额>增加现金（注资）金额须为正mns portfolio持仓概览（份额/成本/现价/市值/收益）只读，最常用mns add <代码> <名称> <类别>把标的加入持仓池（份额为0）类别只能是 us_stocks / cn_stocks / counter_cyclical``mns buy <代码> <份额> <价格>登记 已成交买入现金不足会报错；须先 add``mns sell <代码> <份额> <价格>登记 已成交卖出份额超出持有量会报错mns price <代码> [价格]省略价格=查看；带价格=手工更新mns update-prices自动抓取全部持仓现价需要网络；单个失败会跳过并继续mns remove <代码>从持仓池删除标的不可逆，先与用户确认mns sentiment当前恐贪指数需要网络mns report生成今日调仓报告并存盘需要网络；同时写入 reports/YYYY-MM-DD.txt``mns history [条数]交易历史，默认 20 条位置参数，不是 --limit``mns config打印全部配置mns config <键>读单项必须是完整叶子键mns config <键> <值>改单项校验不通过则拒绝写入，原配置不变mns backtest四种策略对比回测纯离线，不碰账本mns backtest validate样本外验证 + 收益分布--iterations / --block 可调mns backtest params列出可调参数及默认值忘记键名时先跑这个mns market / mns market-indices / mns analyze <代码>全球指数 / 个股报价依赖 Yahoo， 部分网络环境不可用，见 §7

数据位置：配置 ~/.mns/config.toml，账本 ~/.mns/mns.db，报告 ./reports/。

---

3. Agent 需要理解的最小策略模型#

不需要了解内部实现，只需理解这一句： 策略回答的是"现在应该持有多少"，而不是"现在该花掉多少钱"。

1. 恐贪指数落入某个情绪区间 → 得出 风险资产目标总权重（越恐慌越高）
2. 该权重按资产配置比例拆到三条腿（美股/A股/逆周期）
3. 每条腿把 实际权重 与 目标权重 比较
4. 偏离超过 偏离带（默认 4 个百分点）才建议动作，且只补到目标为止
5. 偏离在带内 → 不动作，这是正常状态

默认目标权重曲线（ mns config target_weight.* 可调）：

情绪指数范围风险资产目标权重极度恐慌< 3085%恐慌30–4575%中性45–5560%贪婪55–7045%极度贪婪≥ 7035%

两条 agent 容易误判的规则：

• "今日无需调仓"是健康输出，不是故障。 中长线框架下多数月份都不该有动作。不要因为没有建议就反复重跑，也不要去调窄偏离带来"制造"建议。
• 卖出有最短持有天数限制（默认 30 天）。报告可能显示"需减仓但持仓未满 N 天"，这是刻意规避国内基金惩罚性赎回费，不是 bug。

---

4. 标准工作流#

4.1 每日/每周例行#

bash

mns update-prices   # 先刷新价格，否则报告基于过期价格
mns report          # 生成调仓报告

向用户汇报时应包含：当前恐贪指数与区间、风险资产目标 vs 实际权重、每条腿的建议动作（或不动作的原因）、净操作方向。若某腿建议为"不动作"，把原因一并说明。

4.2 用户已成交，登记入账#

bash

# 用户："我在券商买了 300 份 018966，成交价 1.52"
mns buy 018966 300 1.52
mns portfolio            # 复核登记结果

登记前确认三件事：标的是否已 add 过、份额与价格是否为 实际成交值（不是建议值）、现金余额是否够（不够会报错）。

4.3 新增标的建仓#

bash

mns add 518880 "黄金ETF华安" counter_cyclical   # 先入池
mns buy 518880 1000 8.38                        # 再登记已成交买入

4.4 参数调整#

bash

mns backtest params                    # 先查键名与默认值
mns config rebalance.band_pp           # 读当前值
mns config rebalance.band_pp 6         # 改（校验不通过会拒绝）
mns backtest                           # 改完跑回测看影响

改参数前先告知用户当前值和预期影响；参数变化会直接改变后续所有建议。

4.5 首次初始化（危险）#

bash

mns init            # 若已有数据会提示确认
mns cash set 100000

mns init 会 删除既有数据库。只在用户明确要求全新开始时调用，且 永远不要 加 --force，除非用户明确说了"强制覆盖/不用问我"。

---

5. 如何读 mns report 的输出#

报告固定含以下章节，可按 【章节名】 定位：

章节内容agent 用法【市场情绪】恐贪指数 + 前日/周/月/年同比判断情绪所处区间与变化方向【账户概览】现金、持仓市值、总资产、持仓明细表核对账本状态【调仓计划】目标/当前/偏离 + 每腿建议，含标的级分摊核心结论来源【净操作指引】净买入/净卖出/持仓不动一句话总结【目标仓位预案】各情绪区间下的目标权重与对应金额回答"如果继续跌该买多少"【信号口径】当前由哪个信号驱动及其局限转述结论时必须带上的限定

报告已同时写入 reports/YYYY-MM-DD.txt，需要复述历史结论时读文件，不要重跑（重跑会得到不同时点的指数）。

---

6. 转述效果时必须带上的限定#

用户问"这个策略行不行"时，不要只报有利数字。仓库内经修正数据（真实全收益、计入交易成本与赎回费）的回测结论是：

• 买入持有在收益上领先（年化约 14.6% vs 12.8%）。本工具不能宣称提高收益。
• 优势只在 风险调整后 成立：最大回撤约 10.9% vs 14.9%，Calmar 1.17 vs 0.98。
• 恐贪指数的边际贡献接近于零——加入趋势锚后，带情绪倾斜与不带几乎无差别。
• 2000–2002、2008 等长期熊市未被数据覆盖，而"熊市回撤保护"正是该策略的主要卖点，该卖点尚未经检验。
• 回测区间是美股强牛市 + 长期低利率，结论不应外推到其他环境。

跑 mns backtest / mns backtest validate 可复现上述数字。 不要 把回测年化当作对未来收益的预期转述给用户。

---

7. 故障模式与处理#

现象原因处理mns report / sentiment 失败CNN 接口需要网络，且可能反爬返回 418内置重试；仍失败则告知用户拿不到实时情绪， 不要 用旧指数假装是今天的mns market / analyze 全部失败，报 HTTP 403部分网络环境完全拦截 Yahoo Finance属环境限制，非配置问题。告知用户需代理； update-prices 的 国内基金 部分仍可用update-prices 个别标的被跳过该代码在数据源无对应数据（如特殊 QDII）用 mns price <代码> <价格> 手工补Error: 现金余额不足登记买入金额超过账面现金多为漏记注资，先 mns cash add，或核对成交金额Error: 卖出份额超出持有量份额记错，或漏记了此前买入用 mns portfolio / mns history 核对Error: 未知的配置项: buy_ratio只能读写完整叶子键用 mns config buy_ratio.extreme_fear；或 mns config 看全量Error: 情绪阈值必须满足单调递增 / target_weight 必须随情绪升高而单调不增参数值违反策略内在约束校验已拒绝写入，原配置完好。按提示改成合法值中文输出乱码（Windows）PowerShell 默认 GBK切 UTF-8 终端，或重定向到文件再读数据库被锁多进程并发写 SQLite串行调用，不要并发跑多个 mns 命令

错误一律以非零退出码 + Error: <中文原因> 形式返回，原因可直接转述给用户。

---

8. 常见错误用法（明确不要这么做）#

❌ 错误✅ 正确mns history --limit 50``mns history 50（位置参数）mns config buy_ratio``mns config buy_ratio.fear（叶子键）看到建议就 mns buy 落账只登记用户 实际已成交 的交易报告无建议就反复重跑"不动作"是正常结论，直接如实汇报为了产出建议而调窄 band_pp参数调整需用户同意，且要说明影响mns init --force 图省事除用户明确授权外不加 --force并发跑多个 mns 命令串行执行把回测年化当预期收益转述带上 §6 的全部限定

---

9. 快速自检#

不确定环境是否可用时，按序执行（全部只读，不改数据）：

bash

mns --version        # 二进制可用
mns config           # 配置可加载（旧配置缺新字段会自动取默认值）
mns portfolio        # 账本可读
mns sentiment        # 网络与 CNN 接口可用
mns backtest params  # 参数键名参考