仓库协作与目录规范

最后更新：2026-04-18 适用范围：/usr/local/house

目标

这个仓库不再只是 Markdown 资料堆，而是一个同时满足以下需求的长期项目：

1. 买房研究知识库：便于长期追加、跨会话续写
2. Cloudflare 静态站：便于在 https://house.jaychoubaby.cf 浏览
3. 跨机器可恢复：任何环境 git pull 后都能直接继续工作

一级目录职责

/usr/local/house
├─ src/                     # Astro 页面、布局、数据解析逻辑
├─ public/                  # 站点静态资源（如后续需要）
├─ delivery/                # 一次性交付稿/阶段性交付材料
├─ 楼盘调研/                # 单盘深挖，统一按“楼盘目录 + README + 补充文件”维护
├─ 专题研究/               # 历史研究稿、专题分析、阶段性原始材料
├─ .agents/                 # 仓库内可版本化的协作 skill
├─ .claude/                 # 现有协作补充配置（保留并纳入版本管理）
├─ package.json             # 站点脚本
├─ 进度摘要.md              # 会话续接总入口
├─ 看房记录.md              # 看房结论与执行记录
├─ 房屋对比.md / 二手房对比.md
└─ 其他根目录专题文档        # 预算、片区、专项研究

放置原则

放根目录的内容

• 跨项目全局文档
• 当前阶段总览/总对比/总进度
• 会被首页直接引用的核心总表

放 楼盘调研/ 的内容

• 单盘/单小区专项研究
• 某一个盘的样本房源、口碑、现场核验、争议点
• 不适合塞进总表但后续仍会持续追加的材料

放 delivery/ 的内容

• 一次性交付件
• 汇报稿、阶段性总结稿、可归档材料

放 .agents/ 的内容

• 仓库专用协作 skill
• 用户明确要求长期保留、跨环境复用的流程规范

网页信息架构规则

首页功能模块建议固定为：

1. 项目总览
2. 决策分析
3. 房源对比
4. 楼盘调研
5. 看房执行

放置理由：

• “楼盘调研”天然是“房源对比”的下钻层，不宜放在总览前面
• 但它比“看房执行”更偏资料沉淀，适合作为比较与实看之间的中间层
• 用户在网页端通常会先看总览 → 看候选对比 → 点进某个楼盘深挖 → 再回到看房行动

楼盘调研统一结构

后续新建一律采用：

楼盘调研/
  楼盘名/
    README.md
    市场口碑与在售样本-YYYY-MM-DD.md
    看房后复盘-YYYY-MM-DD.md

历史单文件允许保留，但只要继续深挖，就迁移到目录模式。

协作与提交规则

1. 修改 /usr/local/house 前先执行 git pull --ff-only
2. 完成实质更新后，默认提交全部改动
3. 必须包含隐藏文件与 .codex，除非用户明确要求排除
4. 需要同时更新受影响的导航/索引文档，避免站点断链
5. 新增的重要规则，需同步写入仓库 skill，确保后续 agent 可继承

每次完成后的最少检查

1. npm run build
2. 检查首页是否能看到新增模块或入口
3. 检查新增 Markdown 页面是否可打开
4. 检查相对链接是否被正确映射
5. git status 确认无遗漏，再提交推送