diff --git a/docs/README.md b/docs/README.md index cfaa59b1..a5c5a6c0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,79 +1,80 @@ -# MoFin 文档中心 +# MoFin 文档中心（唯一入口） -> 文档驱动开发。每次代码变更必须同步更新对应文档。 -> 最后更新：2026-08-11（文档治理：归档 7 份过时文档 + 57 份研究过程文档，见 doc-audit-20260811.md） +> **任何 session / 任何人说"看文档"，先读本文件。**（2026-08-30 老莫立，dev-spec 红线#11） +> 最后更新：2026-08-30（大更新：知微协作区/决策区/ops 区/系统状态刷新） +> 考古规则：**越靠近现在的文档越接近真实情况**；`archive/` 仅供历史参考，**禁止当现状依据**。 --- -## 阅读指引 +## 0. 文件夹地图 -### 🚀 新手入门（按顺序读） +| 目录 | 用途 | 性质 | +|------|------|------| +| `docs/` 根 | 正式文档（手册/规范/状态说明/审查报告） | **正式** | +| `docs/decisions/` | 架构决策日志（YYYY-MM-DD-标题.md，格式见 decisions/README.md） | **正式** | +| `docs/ops/` | 运维操作单（批量操作/事件处置，含恢复检查单） | **正式** | +| `docs/research/` | 策略研究方法论与日志 | **正式** | +| `docs/archive/` | 历史文档（旧设计/废弃组件/过时报告） | ⚠️ 仅供参考 | +| `docs/research/archive/` | 57 份单次实验过程记录 | ⚠️ 仅供参考 | -| # | 文档 | 内容 | 时间 | -|---|------|------|------| -| 1 | [portfolio-data-model.md](portfolio-data-model.md) | 核心数据模型：表结构、币种规则、常见错误 | 10 min | -| 2 | [DEVELOPMENT_STANDARDS.md](DEVELOPMENT_STANDARDS.md) | 开发规范：代码结构、DB 规范、Prompt 规范、开发流程 | 15 min | -| 3 | [CHANGELOG.md](../CHANGELOG.md) | 变更日志：所有改动的完整记录 | 5 min | +## 1. 🚀 新手入门（按顺序读） -> 系统架构总览已归档（archive/SYSTEM_ARCHITECTURE-root.md）——当前架构以数据模型 + 方法论文档为准。 +| # | 文档 | 内容 | +|---|------|------| +| 1 | [portfolio-data-model.md](portfolio-data-model.md) | 核心数据模型：表结构、币种规则、常见错误 | +| 2 | [DEVELOPMENT_STANDARDS.md](DEVELOPMENT_STANDARDS.md) + [dev-spec.md](dev-spec.md) | 开发规范（含 11 条红线） | +| 3 | [CHANGELOG.md](../CHANGELOG.md) | 变更日志 | -### 🔧 日常开发 +## 2. 🤖 知微协作（position-analyst 必读） -| 文档 | 何时查阅 | -|------|---------| -| [DEVELOPMENT_STANDARDS.md](DEVELOPMENT_STANDARDS.md) | 每次写代码前 | -| [TEST_PLAN.md](TEST_PLAN.md) | 每次改完代码后跑测试 | -| [CHANGELOG.md](../CHANGELOG.md) | 改完后追加变更记录 | +| 文档 | 内容 | 状态 | +|------|------|------| +| [zhiwei-work-manual.md](zhiwei-work-manual.md) | **知微常驻工作手册**（守则/路径/已知问题） | 正式（知微维护） | +| [zhiwei-ops-discipline.md](zhiwei-ops-discipline.md) | 运维纪律（git 白名单/deploy_guard/自愈边界） | 正式（8-30 已更新 cp -u 同步） | +| [xxm-zhiwei-collaboration.md](xxm-zhiwei-collaboration.md) | 知微↔小小莫 kanban 闭环协作协议 | 正式 | +| [zhiwei-reading-guide-20260813.md](zhiwei-reading-guide-20260813.md) | 温区自适应系统交接 | 正式（8-13 系统仍生效） | +| [MoFin系统状态与数据链路说明.md](MoFin系统状态与数据链路说明.md) | RR/淘汰/数据源（8-17 版；v2 增量烂尾已标注） | 正式 | -### 📊 运维参考 +## 3. 🔧 当前状态指针（先看这里，别看旧审查） + +| 主题 | 以哪份为准 | +|------|-----------| +| **Cron 任务现状** | [ops/2026-08-30-cron-disabled-审计恢复.md](ops/2026-08-30-cron-disabled-审计恢复.md)（88 enabled/22 disabled 全有 reason） | +| Cron 架构史 | [cron-architecture-review-20260811.md](cron-architecture-review-20260811.md)（8-11 快照，顶部有指针） | +| **进化体系归档决策** | [evolution-archive-readme.md](evolution-archive-readme.md)（8-21：人驱动闭环，AB路线废弃） | +| 部署守卫/同步机制 | dev-spec 红线 + 8-30 操作单第八节（**deploy↔hermes 为 cp -u 跨设备同步，非硬链接**） | + +## 4. 📊 运维参考 | 文档 | 内容 | |------|------| -| [cron-review-poversold-20260811.md](cron-review-poversold-20260811.md) | **Cron 梳理报告**（对照 p_oversold 部署，停8/保持30/调整8/新增2）| | [QUICKSTART.md](QUICKSTART.md) | 快速操作手册 | -| [DEPLOY.md](DEPLOY.md) | 部署指南（本地→Gitea→246 工作流）| -| [DASHBOARD.md](DASHBOARD.md) | Dashboard API 参考 | -| [HEALTH-PIPELINE.md](HEALTH-PIPELINE.md) | 健康监控管线 | -| [system-audit-20260810.md](system-audit-20260810.md) | **系统彻查报告**（8/10，含处理状态追踪：9修/6待办）| -| [doc-audit-20260811.md](doc-audit-20260811.md) | **文档治理核实报告**（15 份文档对照系统实际）| +| [DEPLOY.md](DEPLOY.md) | 部署指南（本地→Gitea→246） | +| [DASHBOARD.md](DASHBOARD.md) | Dashboard API（**8-28 起 token 鉴权：?token=，见 .mofin_token**） | +| [HEALTH-PIPELINE.md](HEALTH-PIPELINE.md) | 健康监控管线（8-30 新增 cron_disabled_audit 每日 08:20） | -> ⚠️ cron-catalog.md（6/27 版）已归档至 archive/——当前 cron 清单以 cron-review-poversold-20260811.md 为准。 +## 5. 📈 策略研究 -### 📈 策略研究（2026-08 起，小小莫维护） +[research/methodology.md](research/methodology.md)（方法论总纲）/ [research/research-log.md](research/research-log.md) / [research/research-status.md](research/research-status.md) -| 文档 | 内容 | -|------|------| -| [strategy_research_methodology.md](strategy_research_methodology.md) | **研究方法论**：由果及因/12维预测/铁律/支撑压力规范 | -| [predictive_oversold_strategy.md](predictive_oversold_strategy.md) | **预测超跌反弹策略**（年化 18.57% 达标 v5）| -| [deployment-plan-predictive-oversold.md](deployment-plan-predictive-oversold.md) | **部署计划**（策略整合 MoFin 全流程）| -| [research/methodology.md](research/methodology.md) | 方法论总纲（含铁律0-5）| -| [research/research-log.md](research/research-log.md) | 研究日志（08-08 ~ 08-10 完整历程）| -| [research/research-scripts.md](research/research-scripts.md) | 研究脚本清单 | -| [research/research-status.md](research/research-status.md) | 策略现状与待办 | -| [research/2026-08-06-low-drawdown-study.md](research/2026-08-06-low-drawdown-study.md) | 低回撤组合策略研究 | -| [research/2026-08-08-experience-lessons.md](research/2026-08-08-experience-lessons.md) | 研究经验教训 | +## 6. 📦 归档区（仅供参考） -> 研究过程文档（57 份单次实验记录）已归档至 `research/archive/`，结论已汇总进 methodology.md。 -> 研究脚本见 `scripts/research/`（含 README.md 索引）。 - -### 📦 历史文档（archive/） - -旧的设计文档、需求文档、分析报告、已废弃组件文档。仅供参考，不代表当前系统状态。 +`archive/` 下所有文档（含被归档的 SYSTEM_ARCHITECTURE、cron-catalog 6/27 版等）——**读它们前必须意识到：它们不代表当前系统**。 --- -## 文档规范 +## 文档规范（红线#11 摘要） -- 每个 .md 文件顶部标注版本和日期 -- 过时内容追加 `> **已废弃** — 见 XXX 替代` -- 不直接删除旧文档，移到 `archive/` 保留 -- 交叉引用使用相对路径 `[xxx](xxx.md)` +1. 任何结构变化（新增正式文档/归档/目录调整）**必须同步更新本 README** +2. 每个 .md 顶部标注日期；过时内容追加 `> **已废弃** — 见 XXX 替代` +3. 不删旧文档，移 `archive/`；**archive 内容禁止作为现状依据引用** +4. 交叉引用用相对路径 -## 当前系统状态（2026-08-11 核实） +## 当前系统状态（2026-08-30 核实） -- **数据**：纯 SQLite（`/home/hmo/MoFin/data/mofin.db`，47 表）。`web-dashboard` 是 MoFin 软链别名 -- **币种**：港股存 HKD，A 股存 CNY，汇总时转换 -- **JSON**：decisions.json / watchlist.json 已移除；**portfolio.json 仍在用**（update_data.py 写、stock_profile.py 读） -- **服务**：`mofin-dashboard.service`（:8899，API+Dashboard 一体）；无独立 mofin-api 服务 -- **测试**：`scripts/run_all_tests.py` — 33/33 通过 -- **最新**：`CHANGELOG.md` 查看完整变更 \ No newline at end of file +- **数据**：SQLite `/home/hmo/MoFin/data/mofin.db`（61 表，含 stock_daily 1006 万行）；数据/备份在 **data 卷（/mnt/data, 913G）**，代码与 hermes 在系统盘（227G） +- **脚本同步**：deploy/profile-scripts（git 权威）→ hermes scripts 为 **cp -u 副本**（跨设备，硬链接已失效）；改 deploy 后须验证 hermes 侧一致 +- **Cron**：hermes position-analyst profile 110 任务（88 enabled）；每日审计 cron_disabled_audit 08:20 +- **服务**：mofin-dashboard :8899（token 鉴权）/ dsa-server :8001 / guard-monitor / xmpp-mohe/zhiwei / ejabberd(docker) +- **备份**：每日 07:50 gzip → `data/backups/compressed/`（14 天）→ 08:30 Windows M 盘异地同步 +- **Kanban**：~/.hermes/kanban.db + API :9580 + dispatcher 自动派卡（8-30 修复 spawn-crash） diff --git a/docs/dev-spec.md b/docs/dev-spec.md index f3ad8a9b..b72482c8 100644 --- a/docs/dev-spec.md +++ b/docs/dev-spec.md @@ -23,6 +23,7 @@ 8. **备份/遗留物禁止留在生产数据目录** — `.bak`、`decisions_backup_*`、迁移残留 JSON、废弃 DB，必须在迁移/变更完成时移到 `archive/`。生产数据目录（`MoFin/data` = `web-dashboard/data`）只放活文件。监控脚本扫描生产目录时，遗留物就是未来的假警报 9. **文件居住宪法（源头防副本）** — 新文件只允许落在三处 canonical：cron 脚本 → `deploy/profile-scripts/`；被 import 的库 → repo 根目录；独立服务 → `deploy/bot/`。**禁止**在 `scripts/` 下新建 cron 脚本副本或库副本（`scripts/` 只放被系统引用的工具）。一次性诊断/修复脚本 → 用完即归档 `archive/YYYYMMDD-*/` 或放 `temp/`。违者由 L2 卫生审计的**自动收尸**处理：`scripts/` 下的影子副本（deploy 同名）和零引用孤儿（mtime>7天）会被自动 `git mv` 到 `archive/YYYYMM-auto/` 并自动提交——不需要人工清理，也不会再堆积（2026-07-22 起，scripts/ 从 186 个文件收尸到个位数） 10. **死模块必须收尸** — 宣布模块废弃时，必须在同一轮操作中完成收尸六步：①杀进程 ②stop+disable systemd 服务 ③删 cron job ④归档脚本到 `archive/` ⑤归档数据文件 ⑥从期望矩阵/监控中移除。只说"已废弃"不收尸 = 没废弃（小果 bot 以 root 白跑 8 天 2.5GB 的教训） +11. **文档入口宪法（2026-08-30 老莫立）** — `docs/README.md` 是**唯一文档入口**：任何 session 任何人说"看文档"，先读它。入口必须明确记录：**哪些是正式文档、哪些是归档（archive/ 仅供历史参考、禁止当现状依据）、每个文件夹是干嘛的、当前系统状态指针**。改文档结构/新增正式文档/归档旧文档时**必须同步更新入口**——结构变了入口没更新 = 违规。考古规则：**越靠近现在的文档越接近真实情况**；找决策记录先查 docs/ 正式区，不翻 archive/。 10. **监控查"活"不查"在"** — 健康检查必须验证**数据新鲜度**（DB 表 MAX(时间列)）而非"文件存在/进程存在"。文件 mtime、进程存活都不构成健康证据——数据 24h 不更新才是事故。禁止拿遗留文件的 mtime 当管道健康指标（"数据管道停滞14天"假警报的根因） 11. **批量 LLM 调用禁止走 hermes gateway agent 通道** — hermes gateway 的 `/v1/chat/completions` **不是透传**，是完整 agent 运行时：每个请求创建带工具（terminal/websearch/patch）的 agent 会话，可能螺旋几十轮、累积 150k+ token，客户端超时后服务端仍空转，重试会叠加新会话形成自我 DDoS（2026-07-21 603288 事件：单次重评螺旋 35 分钟、44 次 terminal 调用）。所有批量/脚本化 LLM 调用必须经 `llm_client.call_llm()`：**OCG 上游直连为主**（裸 completion，key 运行时从 hermes config.yaml 读取，不落盘），gateway 仅作应急兜底。新增 LLM 调用点一律复用 `llm_client`，禁止手写 HTTP 调用 12. **告警信噪比纪律** — 所有系统 XMPP 告警必须经 `alert_helper.notify()`，禁止直 POST :5805。两级通道：**ACTION**（买入信号/重点推荐/需人工核查）直通不限速、🚨 前缀独立成条，**永不被限速**；**INFO**（部署/卫生/修复/监控报备）同类 30 分钟限 1 条、≤8 行、24h 内容去重（同一问题不重复轰炸）。有意义的信号（重点推荐操作）绝不允许被纯通知淹没；通知型信息零问题 = 零消息（沉默即正常）