| name | money-never-sleep |
| version | 0.6.0 |
| description | MNS (Money Never Sleeps) CLI operations manual for autonomous agents. Tracks an investment
portfolio in a local ledger, reads market sentiment (CNN Fear & Greed Index), and generates
target-weight rebalancing suggestions. Use when the user asks to view holdings, record a
trade they already executed, generate a daily strategy report, inspect or tune strategy
parameters, or run a backtest.
CRITICAL: MNS connects to NO broker and executes NO trades. `mns buy` / `mns sell` are
bookkeeping entries that record trades the human has ALREADY executed elsewhere. Never call
them to "act on" a suggestion — doing so silently corrupts every downstream number.
Triggers: "查看持仓", "记录买入", "记录卖出", "生成策略报告", "调仓建议", "再平衡",
"恐贪指数", "更新价格", "现金余额", "交易历史", "回测策略", "调整策略参数", "MNS"
|
| license | MIT |
| compatibility | Single static binary (Rust). No runtime dependencies. |
| metadata | {"openclaw":{"source":"https://github.com/sopaco/money-never-sleep","homepage":"https://github.com/sopaco/money-never-sleep","author":"Sopaco","os":["darwin","linux","win32"]}} |
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 | 样本外验证 + 收益分布 | / 可调 |
数据位置：配置 ~/.mns/config.toml，账本 ~/.mns/mns.db，报告 ./reports/。
3. Agent 需要理解的最小策略模型
不需要了解内部实现，只需理解这一句：策略回答的是"现在应该持有多少"，而不是"现在该花掉多少钱"。
- 恐贪指数落入某个情绪区间 → 得出风险资产目标总权重（越恐慌越高）
- 该权重按资产配置比例拆到三条腿（美股/A股/逆周期）
- 每条腿把实际权重与目标权重比较
- 偏离超过偏离带（默认 4 个百分点）才建议动作，且只补到目标为止
- 偏离在带内 → 不动作，这是正常状态
默认目标权重曲线（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 用户已成交，登记入账
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%）。本工具不能宣称提高收益。
mns report 实盘走的是"情绪锚"（纯按恐贪指数映射目标仓位），不是 mns backtest 默认展示的
"趋势锚"（价格 vs 12 月均线 + 情绪倾斜）。 二者样本内表现差很多——情绪锚年化 9.79%/Calmar
1.07，趋势锚年化 12.75%/Calmar 1.17——转述回测结论前先确认在说哪一种口径，不要把趋势锚的
数字当成 mns report 会给出的效果转述给用户。- 情绪锚在样本内风险调整后优于买入持有（最大回撤约 9.2% vs 14.9%，Calmar 1.07 vs 0.98），
但
mns backtest validate 的样本外（walk-forward）验证显示这个优势不稳健：样本外买入
持有在收益和 Calmar 上同时反超情绪锚与趋势锚两种配置（买入持有 12.23%/Calmar 1.02，
情绪锚仅 7.91%/Calmar 0.86，趋势锚 10.79%/Calmar 0.94）。bootstrap 分布显示这个差距落在
统计噪声范围内，不具备显著性。
mns backtest validate 还会把 2018、2022（数据集内仅有的两段明显下跌年份）逐年拆开单独展示：
两种锚点在这两年确实比买入持有回撤更小，但这不能替代 2000–2002／2008 这类多年期熊市压力
测试，那类数据当前不可得，而"熊市回撤保护"正是该策略的主要卖点，该卖点仍是未充分验证的
claim。- 回测区间是美股强牛市 + 长期低利率，结论不应外推到其他环境。
跑 mns backtest validate 可自行复现以上全部数字（不要只跑不带 validate 的 mns backtest，
那只展示样本内的趋势锚结果，会漏掉上面最重要的样本外反转结论）。不要把回测年化当作对未来
收益的预期转述给用户。
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
mns backtest params
