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 是否已安装可用，不要重复安装。

mns --version

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

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

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.* 可调）：

情绪	指数范围	风险资产目标权重
极度恐慌	< 30	85%
恐慌	30–45	75%
中性	45–55	60%
贪婪	55–70	45%
极度贪婪	≥ 70	35%

两条 agent 容易误判的规则：

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

---

4. 标准工作流

4.1 每日/每周例行

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

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

4.2 用户已成交，登记入账

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

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

4.3 新增标的建仓

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

4.4 参数调整

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

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

4.5 首次初始化（危险）

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. 快速自检

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

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