docs: 文档入口宪法落地——README重写为唯一入口(文件夹地图/正式vs归档明确/当前状态8-30刷新)+dev-spec红线#11(老莫8-30立)

2026-08-30 19:40:35 +08:00
parent c2cc967514
commit 4c802b87b2
2 changed files with 57 additions and 55 deletions
@@ -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` 查看完整变更
+- **数据**：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）
@@ -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 内容去重（同一问题不重复轰炸）。有意义的信号（重点推荐操作）绝不允许被纯通知淹没；通知型信息零问题 = 零消息（沉默即正常）