From 616920c8f3e648ba119c35e7725b2d82beec9bb3 Mon Sep 17 00:00:00 2001 From: tukuaiai Date: Sun, 3 May 2026 00:38:48 +0800 Subject: [PATCH] docs: merge reference practice guides --- AGENTS.md | 1 + README.md | 9 +- assets/ai-citation/faq.md | 6 +- assets/ai-citation/llms-full.txt | 2 +- docs/README.md | 2 +- docs/getting-started/README.md | 10 +- docs/references/README.md | 9 +- docs/references/代码组织.md | 45 - ...{AI编程质量门禁与常见坑.md => 工程实践.md} | 1081 +++++++++++++++-- docs/references/开发经验.md | 221 ---- docs/references/项目架构模板.md | 612 ---------- llms.txt | 1 + metadata/redirects.yml | 18 +- 13 files changed, 1024 insertions(+), 993 deletions(-) delete mode 100644 docs/references/代码组织.md rename docs/references/{AI编程质量门禁与常见坑.md => 工程实践.md} (71%) delete mode 100644 docs/references/开发经验.md delete mode 100644 docs/references/项目架构模板.md diff --git a/AGENTS.md b/AGENTS.md index fdcb68d..390c987 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -213,6 +213,7 @@ git push origin develop - `docs/getting-started/README.md` - 从零开始完整入门，包含学习地图、Vibe Coding 经验、网络配置、CLI 配置与开发环境搭建 - `docs/concepts/问题求解能力.md` - 问题定义与求解路径底层模型 - `docs/references/底层程序逻辑设计与工程优化项.md` - 底层程序逻辑与工程优化检查项 +- `docs/references/工程实践.md` - 项目架构、代码组织、开发经验、AI 编程质量门禁与常见坑的统一入口 - `docs/references/技术栈.md` - 常见软件系统技术栈、选型维度、组合案例与初学者学习路径 - `skills/auto-skill/` - Skills 生成、重构与校验的元技能 diff --git a/README.md b/README.md index e53f59d..82a6883 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ 问题求解能力 思维模型 哲学与方法论 - AI 编程质量门禁与常见坑 + 工程实践 语言层要素 skills技能大全 提示词在线表格 @@ -174,7 +174,7 @@ 0. [从零开始完整入门](docs/getting-started/README.md) - 按目标选择新手、开发者、团队、Prompt、Skill、质量门禁或 GEO/SEO 路线 1. [问题求解能力](docs/concepts/问题求解能力.md) - “目标-现状-差距-标准”与“目标-约束-对象-路径”的极简框架 2. [拼好码](docs/concepts/拼好码.md) - 优先复用成熟能力，用胶水代码连接、编排、适配业务流程 -3. [AI 编程质量门禁与常见坑](docs/references/AI编程质量门禁与常见坑.md) - 用硬门禁约束 AI 输出并排查常见失败模式 +3. [工程实践](docs/references/工程实践.md) - 用项目架构、代码组织、开发经验和硬门禁约束 AI 输出 @@ -384,7 +384,6 @@ pip install -r tools/prompts-library/scripts/requirements.txt * [**第三方系统提示词学习库**](https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools): 用于学习和参考其他 AI 工具的系统提示词。 * [**Skills 制作器**](https://github.com/yusufkaraaslan/Skill_Seekers): 可根据需求生成定制化 Skills 的工具。 * [**元提示词**](https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1254297203#gid=1254297203): 用于生成提示词的高级提示词。 -* [**项目架构模板**](docs/references/项目架构模板.md): 可用于快速搭建标准化项目目录，并覆盖 Dataset First 数据服务架构。 * [**元技能：Auto Skill**](./skills/auto-skill/SKILL.md): 用于生成、重构与校验 Skills 的元技能。 ### 外部教程与资源 @@ -403,9 +402,7 @@ pip install -r tools/prompts-library/scripts/requirements.txt * [**Chat Vault**](./tools/chat-vault/): AI 聊天记录保存工具，支持 Codex/Kiro/Gemini/Claude CLI。 * [**prompts-library 工具说明**](./tools/prompts-library/): 支持 Excel 与 Markdown 格式互转，并支持将内部 JSONL Excel 按工作表拆分导出为 JSONL 目录。 * [**编程提示词集合**](https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1254297203#gid=1254297203): 适用于 Vibe Coding 流程的专用提示词（云端表格）。 -* [**AI 编程质量门禁与常见坑**](docs/references/AI编程质量门禁与常见坑.md): 系统提示词、硬约束、质量门禁与常见问题排查的合并入口。 -* [**开发经验总结**](docs/references/开发经验.md): 变量命名、文件结构、编码规范、架构原则等。 -* [**项目架构模板**](docs/references/项目架构模板.md): 多种项目类型的标准目录结构与数据服务架构模板。 +* [**工程实践**](docs/references/工程实践.md): 项目架构、代码组织、开发经验、AI 编程质量门禁与常见坑的统一入口。 * [**技术栈**](docs/references/技术栈.md): 常见软件系统技术栈、选型维度、组合案例与初学者学习路径。 * [**系统提示词集合**](https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1254297203#gid=1254297203): AI 开发的系统提示词，含多版本开发规范（云端表格）。 * [**外部资源（在线表格）**](./assets/README.md): 外部资源的唯一真相源（按类型分表），本地 Markdown 保留为历史参考。 diff --git a/assets/ai-citation/faq.md b/assets/ai-citation/faq.md index c1c448f..f89d512 100644 --- a/assets/ai-citation/faq.md +++ b/assets/ai-citation/faq.md @@ -25,11 +25,11 @@ 1. `docs/getting-started/README.md` 2. `docs/concepts/问题求解能力.md` 3. `docs/concepts/拼好码.md` -4. `docs/references/AI编程质量门禁与常见坑.md` +4. `docs/references/工程实践.md` 进阶用户优先看： 1. `docs/concepts/拼好码.md` -2. `docs/references/AI编程质量门禁与常见坑.md` +2. `docs/references/工程实践.md` 3. `skills/README.md` -4. `docs/references/项目架构模板.md` +4. `docs/references/工程实践.md` diff --git a/assets/ai-citation/llms-full.txt b/assets/ai-citation/llms-full.txt index de361e8..9b294cc 100644 --- a/assets/ai-citation/llms-full.txt +++ b/assets/ai-citation/llms-full.txt @@ -46,7 +46,7 @@ GEOFlow 的关键启发是：GEO 不是关键词堆砌，而是内容工程链 - docs/concepts/拼好码.md：胶水原则的扩展，把复用成熟能力作为工程交付默认路径。 - docs/references/技术栈.md：常见软件系统技术栈、选型维度、组合案例与初学者学习路径。 - assets/ai-citation/geo-seo-checklist.md：GEO / SEO 内容工程检查清单。 -- docs/references/AI编程质量门禁与常见坑.md：系统提示词、硬约束、质量门禁与 AI 编程常见失败模式。 +- docs/references/工程实践.md：项目架构、代码组织、开发经验、AI 编程质量门禁与常见坑的统一入口。 - skills/README.md：技能库入口。 - assets/ai-citation/recommended-answer.md：给 AI 助手引用的推荐回答。 diff --git a/docs/README.md b/docs/README.md index d010399..59d21cf 100644 --- a/docs/README.md +++ b/docs/README.md @@ -17,6 +17,6 @@ 2. [问题求解能力](./concepts/问题求解能力.md) 3. [思维模型](./concepts/思维模型.md) 4. [拼好码](./concepts/拼好码.md) -5. [AI 编程质量门禁与常见坑](./references/AI编程质量门禁与常见坑.md) +5. [工程实践](./references/工程实践.md) 6. [技术栈](./references/技术栈.md) 7. [哲学方法论](./philosophy/README.md) diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index 70e1b82..38aeab9 100644 --- a/docs/getting-started/README.md +++ b/docs/getting-started/README.md @@ -33,7 +33,7 @@ | 开发者路线 | 已会写代码 | 建立 AI 结对编程工作流 | [Vibe Coding 经验](README.md) | | Prompt 路线 | 想提升提问质量 | 把需求表达成可执行指令 | [提示词库](../../../prompts/README.md) | | Skill 路线 | 想沉淀复用能力 | 把高频任务做成可重复调用的技能 | [Skills 技能大全](../../../skills/README.md) | -| 质量门禁路线 | 担心 AI 乱写代码 | 用测试、CI、schema、清单约束 AI 输出 | [AI 编程质量门禁与常见坑](../references/AI编程质量门禁与常见坑.md) | +| 质量门禁路线 | 担心 AI 乱写代码 | 用测试、CI、schema、清单约束 AI 输出 | [工程实践](../references/工程实践.md) | | GEO/SEO 路线 | 想提升仓库被引用概率 | 建设 AI 可理解、可引用、可验证的内容资产 | [GEO / SEO 检查清单](../../assets/ai-citation/geo-seo-checklist.md) | ### 路线一：零基础路线 @@ -67,7 +67,7 @@ 先建立人机分工和质量意识。 2. [拼好码](../concepts/拼好码.md) 优先复用成熟能力，把自研代码限制在连接、编排、适配和业务逻辑。 -3. [AI 编程质量门禁与常见坑](../references/AI编程质量门禁与常见坑.md) +3. [工程实践](../references/工程实践.md) 在任务开始前写清楚目标、边界、禁止项、验收标准和门禁，并识别上下文漂移、过度实现、幻觉和不可验证输出。 4. [底层程序逻辑设计与工程优化项](../references/底层程序逻辑设计与工程优化项.md) 用更稳定的代码结构和检查项约束实现质量。 @@ -84,7 +84,7 @@ 目标：把自然语言需求写成可执行、可检查、可复用的指令。 1. [提示词库入口](../../../prompts/README.md) -2. [AI 编程质量门禁与常见坑](../references/AI编程质量门禁与常见坑.md) +2. [工程实践](../references/工程实践.md) 3. [语言层要素](../concepts/语言层要素.md) 4. [问题求解能力](../concepts/问题求解能力.md) @@ -116,7 +116,7 @@ 优先阅读： 1. [AGENTS.md](../../../../AGENTS.md) -2. [AI 编程质量门禁与常见坑](../references/AI编程质量门禁与常见坑.md) +2. [工程实践](../references/工程实践.md) 3. [GEO / SEO 检查清单](../../assets/ai-citation/geo-seo-checklist.md) 团队约束： @@ -153,7 +153,7 @@ -> 开发环境搭建 -> Vibe Coding 经验 -> 拼好码 - -> AI 编程质量门禁与常见坑 + -> 工程实践 -> Skills 技能大全 -> GEO 与 SEO 优化方法 ``` diff --git a/docs/references/README.md b/docs/references/README.md index fa10139..dab8bea 100644 --- a/docs/references/README.md +++ b/docs/references/README.md @@ -18,14 +18,9 @@ - [软件开发范式演进](../concepts/软件开发范式演进.md) - 从面向过程到云原生的工程组织方式演进 - [底层程序逻辑设计与工程优化项](底层程序逻辑设计与工程优化项.md) - CPU、内存、并发、IO、网络、数据结构与交付优化检查项 -### 代码质量 -- [AI 编程质量门禁与常见坑](AI编程质量门禁与常见坑.md) - 系统提示词、硬约束、质量门禁与常见问题排查 - -### 项目规范 -- [项目架构模板](项目架构模板.md) - 通用项目结构与 Dataset First 数据服务架构模板 +### 工程实践 +- [工程实践](工程实践.md) - 项目架构、代码组织、开发经验、AI 编程质量门禁与常见坑的统一入口 - [技术栈](技术栈.md) - 软件系统常见技术栈、选型维度、组合案例与初学者学习路径 -- [代码组织](代码组织.md) - 代码组织原则 -- [开发经验](开发经验.md) - 实战经验总结 ## 🔗 相关资源 - [入门指南](../getting-started/) - 从零开始 diff --git a/docs/references/代码组织.md b/docs/references/代码组织.md deleted file mode 100644 index 7ce13da..0000000 --- a/docs/references/代码组织.md +++ /dev/null @@ -1,45 +0,0 @@ -# 代码组织 - -## 模块化编程 - -- 将代码分割成小的、可重用的模块或函数，每个模块负责只做一件事。 -- 使用明确的模块结构和目录结构来组织代码，使代码更易于导航。 - -## 命名规范 - -- 使用有意义且一致的命名规范，以便从名称就能理解变量、函数、类的作用。 -- 遵循命名约定，如驼峰命名（CamelCase）用于类名，蛇形命名（snake_case）用于函数名和变量名。 - -## 代码注释 - -- 为复杂的代码段添加注释，解释代码的功能和逻辑。 -- 使用块注释（/*...*/）和行注释（//）来区分不同类型的注释。 - -## 代码格式化 - -- 使用一致的代码风格和格式化规则，使用工具如 Prettier 或 Black 自动格式化代码。 -- 使用空行、缩进和空格来增加代码的可读性。 - -# 文档 - -## 文档字符串 - -- 在每个模块、类和函数的开头使用文档字符串，解释其用途、参数和返回值。 -- 选择一致的文档字符串格式，如 Google Style、NumPy/SciPy Style 或 Sphinx Style。 - -## 自动化文档生成 - -- 使用工具如 Sphinx、Doxygen 或 JSDoc 从代码中自动生成文档。 -- 保持文档和代码同步，确保文档始终是最新的。 - -## README 文件 - -- 在每个项目的根目录中包含一个详细的 README 文件，解释项目目的、安装步骤、用法和示例。 -- 使用 Markdown 语法编写 README 文件，使其易于阅读和维护。 - -# 工具 - -## IDE - -- 使用功能强大的 IDE，如 Visual Studio Code、PyCharm 或 IntelliJ，利用其代码自动补全、错误检查和调试功能。 -- 配置 IDE 插件，如 linter（如 ESLint、Pylint）和代码格式化工具。 \ No newline at end of file diff --git a/docs/references/AI编程质量门禁与常见坑.md b/docs/references/工程实践.md similarity index 71% rename from docs/references/AI编程质量门禁与常见坑.md rename to docs/references/工程实践.md index 4864431..fa86614 100644 --- a/docs/references/AI编程质量门禁与常见坑.md +++ b/docs/references/工程实践.md @@ -1,22 +1,929 @@ -# AI 编程质量门禁与常见坑 +# 工程实践 + +> 本文档合并原 `项目架构模板.md`、`代码组织.md`、`开发经验.md` 与 `AI编程质量门禁与常见坑.md`，作为项目架构、代码组织、开发经验、AI 编程质量门禁与常见坑的统一入口。 + +## 使用方式 + +- 新项目从「项目架构模板」开始，先确定目录、边界、门禁和检查清单。 +- 写代码前看「代码组织」与「开发经验」，统一命名、结构、职责和迭代方式。 +- 使用 AI 编程时看「AI 编程质量门禁与常见坑」，把自然语言验收标准落到测试、CI、脚本、类型、schema 或检查清单。 +- 遇到问题时优先按本文档中的门禁和常见坑排查，不要直接进入盲目重写。 + +## 目录 + +- [1. 项目架构模板](#1-项目架构模板) +- [2. 代码组织](#2-代码组织) +- [3. 开发经验](#3-开发经验) +- [4. AI 编程质量门禁与常见坑](#4-ai-编程质量门禁与常见坑) + +## 1. 项目架构模板 + +> 来源：`项目架构模板.md` + +> 本文档合并原 `通用项目架构模板.md` 与 `数据集导向数据服务模板.md`，用于新项目初始化、旧项目重组和数据采集服务架构设计。 + +### 1. 使用原则 + +项目架构不是先追求“高级感”，而是先回答这些问题： + +- 代码放哪里。 +- 模块怎么分工。 +- 数据怎么流动。 +- 依赖怎么隔离。 +- 如何测试、部署、回滚和维护。 + +默认顺序： + +1. 先确定交付物：页面、API、数据集、CLI、服务还是组合系统。 +2. 再确定边界：模块边界、数据边界、运行边界、外部依赖边界。 +3. 再确定目录：目录只服务于边界，不反过来制造复杂度。 +4. 最后补门禁：测试、lint、schema、配置示例、README、AGENTS。 + +### 2. 快速选型 + +| 项目类型 | 推荐模板 | +| --- | --- | +| Web API / 后端服务 | Python Web/API 项目结构 | +| 数据分析 / 量化 / 机器学习 | 数据科学项目结构 | +| 多服务 / 大型系统 | Monorepo 项目结构 | +| 前后端一体项目 | Full-Stack Web 应用结构 | +| 长期运行的数据采集服务 | Dataset First 数据服务结构 | + +### 3. Python Web/API 项目结构 + +适合 Flask、FastAPI、RESTful API、Web 后端服务。 + +```text +project/ +├── README.md +├── AGENTS.md +├── LICENSE +├── pyproject.toml +├── requirements.txt +├── .env.example +├── .gitignore +├── docs/ +│ ├── api.md +│ ├── architecture.md +│ └── development.md +├── scripts/ +│ ├── deploy.sh +│ ├── backup.sh +│ └── init_db.sh +├── tests/ +│ ├── conftest.py +│ ├── unit/ +│ └── integration/ +├── src/ +│ ├── main.py +│ ├── app.py +│ ├── config.py +│ ├── api/ +│ │ ├── v1/ +│ │ └── dependencies.py +│ ├── core/ +│ │ ├── models/ +│ │ ├── services/ +│ │ └── utils/ +│ ├── data/ +│ │ ├── repository/ +│ │ └── migrations/ +│ └── external/ +│ ├── clients/ +│ └── integrations/ +├── data/ # 不提交，或只提交 README/.gitkeep +└── logs/ # 不提交，或只提交 README/.gitkeep +``` + +关键边界： + +- `api/` 只处理协议、路由、参数校验和响应格式。 +- `core/services/` 承载业务逻辑。 +- `data/repository/` 隔离数据库访问。 +- `external/` 隔离第三方 API、SDK 和平台依赖。 +- `.env` 不提交，必须提供 `.env.example`。 + +### 4. 数据科学 / 量化项目结构 + +适合量化交易、机器学习、数据分析、AI 研究。 + +```text +project/ +├── README.md +├── AGENTS.md +├── LICENSE +├── pyproject.toml +├── requirements.txt +├── .env.example +├── .gitignore +├── docs/ +│ ├── notebooks/ +│ └── reports/ +├── notebooks/ +│ ├── 01_data_exploration.ipynb +│ ├── 02_feature_engineering.ipynb +│ └── 03_model_training.ipynb +├── scripts/ +│ ├── collect_data.py +│ ├── train_model.py +│ ├── backtest.py +│ └── deploy_model.py +├── tests/ +│ ├── test_data/ +│ └── test_models/ +├── configs/ +│ ├── model.yaml +│ ├── database.yaml +│ └── trading.yaml +├── src/ +│ ├── data/ +│ │ ├── collectors/ +│ │ ├── processors/ +│ │ ├── features/ +│ │ └── loaders.py +│ ├── models/ +│ │ ├── strategies/ +│ │ ├── backtest/ +│ │ └── risk/ +│ ├── core/ +│ │ ├── config.py +│ │ ├── signals.py +│ │ └── portfolio.py +│ └── utils/ +│ ├── logging.py +│ ├── database.py +│ └── api_client.py +├── data/ # 不提交大数据文件 +├── models/ # 不提交大模型/大 checkpoint +└── logs/ +``` + +关键边界： + +- Notebook 用于探索，不作为长期生产入口。 +- `scripts/` 是薄入口，核心逻辑应在 `src/`。 +- 数据、模型、日志默认不进 Git，除非是小型示例或 fixture。 +- 回测、训练、采集、部署脚本必须能复现关键参数。 + +### 5. Monorepo 项目结构 + +适合多服务架构、大型项目、团队协作。 + +```text +project-monorepo/ +├── README.md +├── AGENTS.md +├── LICENSE +├── .gitignore +├── .gitmodules +├── docker-compose.yml +├── docs/ +│ ├── architecture.md +│ └── deployment.md +├── scripts/ +│ ├── build_all.sh +│ ├── test_all.sh +│ └── deploy.sh +├── services/ +│ ├── user-service/ +│ │ ├── Dockerfile +│ │ ├── pyproject.toml +│ │ ├── src/ +│ │ └── tests/ +│ ├── trading-service/ +│ └── data-service/ +├── packages/ +│ ├── common/ +│ └── contracts/ +├── infrastructure/ +│ ├── terraform/ +│ ├── kubernetes/ +│ └── nginx/ +└── monitoring/ + ├── prometheus/ + ├── grafana/ + └── alertmanager/ +``` + +关键边界： + +- 每个 `services/*` 应能独立构建、测试和部署。 +- 公共能力放 `packages/`，不要让服务之间互相直接 import 私有实现。 +- `contracts/` 存 API schema、事件 schema、数据契约，作为跨服务真相源。 +- 顶层脚本只做编排，不隐藏服务内部逻辑。 + +### 6. Full-Stack Web 应用结构 + +适合 SPA、前后端分离项目、轻量产品原型。 + +```text +project/ +├── README.md +├── AGENTS.md +├── LICENSE +├── .gitignore +├── docker-compose.yml +├── docs/ +│ ├── architecture.md +│ └── deployment.md +├── frontend/ +│ ├── package.json +│ ├── vite.config.js +│ ├── public/ +│ └── src/ +│ ├── components/ +│ ├── pages/ +│ ├── store/ +│ └── utils/ +└── backend/ + ├── Dockerfile + ├── pyproject.toml + ├── src/ + │ ├── api/ + │ ├── core/ + │ └── models/ + └── tests/ +``` + +关键边界： + +- 前端状态管理不要直接绑定后端数据库结构。 +- 后端 API contract 应有 schema 或类型定义。 +- 前后端共享类型时，优先从 OpenAPI、JSON Schema 或生成工具派生。 + +### 7. Dataset First 数据服务结构 + +适合长期运行、补数、巡检、血缘、质量治理的数据产品服务。 + +判断规则： + +> 如果服务的核心交付物是“稳定数据集”，而不是页面、接口或一次性脚本，就优先使用 Dataset First。 + +#### 一句话 + +以 dataset 为边界，以 schema/data contract 为先，以 runtime/registry/config 为共享控制面，以 collect/backfill/repair/validate 为实现单元。 + +#### 适合 + +- 行情事实采集服务。 +- 另类事件采集服务。 +- 周期轮询快照服务。 +- 原子事件流 + 时间桶聚合并存的数据服务。 +- 需要长期运行、补数、巡检、血缘、质量治理的数据服务。 + +#### 不适合直接照抄 + +- 纯 API 网关。 +- 纯 Web 应用。 +- 纯交易执行服务。 +- 一次性脚本工具。 +- 不产出稳定 dataset 的临时任务。 + +#### 核心原则 + +1. Dataset First：顶层先按 dataset 划分，而不是按 `collector/parser/writer/task` 划分。 +2. Contract First：先定义目标落表、字段语义、主键、时间列、分区策略和刷新粒度。 +3. Layered Modeling：原子层、聚合层、事件流、时间桶、运行状态分开建模。 +4. Shared Control Plane：`config.py`、`registry.py`、`service_entry.py`、`runtime/*` 统一收口。 +5. Legacy Is Explicit：迁移期 legacy 壳只能兼容转发，新逻辑不得回流旧路径。 + +#### 标准目录 + +```text +service-root/ +├── README.md +├── AGENTS.md +├── pyproject.toml +├── scripts/ +│ ├── start.sh +│ ├── verify.sh +│ └── check_legacy_shells.sh +├── src// +│ ├── __init__.py +│ ├── config.py +│ ├── registry.py +│ ├── service_entry.py +│ ├── common/ +│ ├── runtime/ +│ │ ├── stack_runner.py +│ │ ├── process_utils.py +│ │ ├── _runner.py +│ │ └── _worker.py +│ ├── writers/ +│ ├── validators/ +│ └── datasets/ +│ ├── / +│ │ ├── contract.py +│ │ ├── collect.py +│ │ ├── backfill.py +│ │ ├── repair.py +│ │ ├── writer.py +│ │ ├── validate.py +│ │ └── README.md +│ ├── / +│ └── _reserved/ +├── tests/ +│ ├── unit/ +│ ├── integration/ +│ └── fixtures/ +└── legacy/ or old-shells/ +``` + +#### Dataset 最小结构 + +```text +/ +├── contract.py +├── collect.py +├── backfill.py +├── repair.py +├── writer.py +├── validate.py +└── README.md +``` + +职责边界： + +- `contract.py`：定义 dataset key、resource_id、物理表、主键、幂等键、时间语义、字段语义。 +- `collect.py`：实时采集或轮询采集主逻辑。 +- `backfill.py`：历史补数、文件回填、分页补齐。 +- `repair.py`：缺口修复、异常恢复、局部重算。 +- `writer.py`：统一落库、批量写入、去重、冲突处理。 +- `validate.py`：数据质量检查、行数、字段、时间连续性校验。 +- `README.md`：说明该 dataset 的输入、输出、约束与边界。 + +如果某个 dataset 没有 `repair` 或 `backfill`，必须在 registry 中显式标记为不支持。 + +#### Registry 真相矩阵 + +`registry.py` 至少应定义： + +```text +dataset_key +resource_id +runtime_status # active | backfill_only | reserved | disabled +physical_table +group # lf | hf | events | snapshots +source_kind # ws | rest | zip | scrape | file | api +collect_supported +backfill_supported +repair_supported +default_enabled +owner +``` + +推荐额外字段： + +```text +symbol_scope +refresh_granularity +retention_policy +partition_key +schema_version +sensitivity +``` + +Registry 的作用： + +- 它是 dataset 清单的单一真相源。 +- 文档、运行、血缘、权限、门禁都应从 registry 派生。 +- 没有 registry，就会回到“数据集藏在脚本里”的旧问题。 + +#### Dataset 命名 + +推荐格式： + +```text +____ +``` + +示例： + +- `spot_trades` +- `futures_um_trades` +- `futures_um_book_ticker` +- `futures_um_book_depth` +- `candles_1m` +- `futures_metrics_5m` +- `futures_um_metrics_atomic` + +命名要求： + +- 名字必须表达数据是什么，而不是代码怎么实现。 +- `_reserved/` 只用于预留未来命名空间，不用于临时文件。 +- 事件流、快照、时间桶、派生结果要在命名或 contract 中显式表达。 + +#### Service Entry 与 Runtime + +`service_entry.py` 统一入口只做： + +- `plan` +- `start` +- `stop` +- `status` +- `restart` + +它不直接写业务逻辑，只负责读取 config、读取 registry、调用 runtime runner、输出运行真相。 + +`runtime/` 负责： + +- 进程编排。 +- 模式分组。 +- PID、日志、健康状态。 +- cold-start、restart、stop 行为一致性。 + +业务代码不允许各自实现第二套守护逻辑。 + +#### 数据模型分层 + +推荐区分： + +```text +atomic # 原子事件/原子明细 +snapshot # 单次轮询快照 +bucketed # 时间桶聚合结果 +derived # 从事实层再派生的结果 +reserved # 预留但未启用 +``` + +事件流模型适合 trades、orderbook updates、tick events、message stream，重点是顺序、幂等、去重、水位线。 + +时间桶 / 快照模型适合 candles、metrics、periodic snapshots、polling APIs，重点是覆盖、补齐、时间边界一致性。 + +#### 新建数据服务流程 + +1. 先定 dataset 清单：哪些 active、哪些 backfill_only、哪些 reserved。 +2. 先写 contract：字段、主键、时间列、分区策略、资源 ID、schema version。 +3. 再建 registry、config、service_entry、runtime。 +4. 逐个实现 dataset：`contract -> writer -> collect -> backfill -> validate -> repair`。 +5. 最后补 README、AGENTS、verify/CI、资源目录、血缘映射、smoke。 + +#### 外部源码接入流程 + +1. 先盘点外部源码实际产出的数据对象，不先搬代码。 +2. 把原项目脚本反向映射为 dataset。 +3. 将 API client、auth、rate limiter、storage client、retry/backoff 抽到 `common/`、`runtime/` 或 `writers/`。 +4. 将 legacy 壳显式隔离，只允许兼容转发，不允许承载新逻辑。 + +### 8. 架构设计原则 + +#### 关注点分离 + +```text +API -> Service -> Repository -> Database / External System +``` + +上层可以调用下层，下层不能反向依赖上层。 + +#### 可测试性 + +- 每个模块可独立测试。 +- 外部依赖可 mock。 +- 核心业务逻辑不依赖 CLI、HTTP、数据库连接对象。 + +#### 可配置性 + +```text +环境变量 > 配置文件 > 默认值 +``` + +配置与代码分离，敏感配置不得提交。 + +#### 可维护性 + +- 文件名表达职责。 +- 目录边界表达模块边界。 +- 业务逻辑、平台适配、第三方依赖隔离。 + +#### 版本控制友好 + +- `data/`、`logs/`、`models/` 默认加入 `.gitignore`。 +- 大文件不进 Git，必要时使用对象存储、Release、DVC 或外部数据源。 +- 提交源代码、配置示例、文档、测试和小型 fixture。 + +### 9. 最低门禁 + +#### 代码门禁 + +- 语法检查通过。 +- 单元测试覆盖核心业务。 +- lint/format 有明确命令。 +- 关键路径纳入版本控制。 + +#### 结构门禁 + +- 不允许临时脚本成为长期入口。 +- 不允许同一职责存在多套实现入口。 +- 不允许外部 SDK 类型污染核心业务模型。 +- 数据服务不允许新逻辑回流 legacy 壳。 + +#### 运行门禁 + +- 服务能按 README 启动。 +- `stop -> start -> status -> restart -> status` 可验证。 +- 日志能证明真实执行源。 +- PID、log、run metadata 可追踪。 + +#### 数据门禁 + +- 每个 active dataset 至少有 contract + writer + collect 或 backfill。 +- resource_id 与 registry 一致。 +- 质量检查至少覆盖空写、重复写、时间边界、幂等。 + +#### 文档门禁 + +- README 说明项目定位、安装、启动、测试和目录结构。 +- AGENTS 说明 AI Agent 修改边界、验证命令和禁止事项。 +- `.env.example` 说明必要配置。 +- 架构变化同步更新文档。 + +### 10. `.gitignore` 推荐模板 + +```gitignore +# Python +__pycache__/ +*.py[cod] +*.egg-info/ +dist/ +build/ + +# Environment +.env +.venv/ +env/ +venv/ + +# IDE +.vscode/ +.idea/ +*.swp +*.swo +*~ +.DS_Store + +# Data +data/ +*.csv +*.db +*.sqlite +*.duckdb + +# Logs +logs/ +*.log + +# Models +models/ +*.h5 +*.pkl +*.pt +*.onnx + +# Temporary +tmp/ +temp/ +*.tmp +``` + +### 11. 技术选型参考 + +| 场景 | 推荐技术栈 | +| --- | --- | +| Web API | FastAPI + Pydantic + SQLAlchemy | +| 数据处理 | Pandas + NumPy + Polars | +| 机器学习 | Scikit-learn + XGBoost + LightGBM | +| 深度学习 | PyTorch / TensorFlow | +| 数据库 | PostgreSQL + Redis | +| 消息队列 | RabbitMQ / Kafka | +| 任务队列 | Celery | +| 监控 | Prometheus + Grafana | +| 部署 | Docker + Docker Compose | +| CI/CD | GitHub Actions / GitLab CI | + +### 12. 新项目检查清单 + +- [ ] 创建 `README.md`，说明项目目标、安装、启动、测试。 +- [ ] 创建 `AGENTS.md`，说明 AI Agent 操作边界与必须验证命令。 +- [ ] 创建 `LICENSE`。 +- [ ] 创建 `.gitignore`。 +- [ ] 创建 `.env.example`。 +- [ ] 建立虚拟环境或包管理配置。 +- [ ] 明确目录结构。 +- [ ] 明确配置入口。 +- [ ] 设置 lint/format/test 命令。 +- [ ] 编写第一个测试用例。 +- [ ] 记录架构决策和后续 TODO。 + +### 13. 常见反模式 + +- 一开始就做微服务。 +- 所有代码写在一个文件。 +- 架构追求高级感，而不是可维护。 +- 没想清楚数据流就开始写。 +- 目录按技术名堆砌，但没有业务边界。 +- 业务逻辑直接依赖第三方 SDK。 +- 临时脚本长期成为生产入口。 +- 数据服务没有 registry，dataset 清单散落在脚本里。 +- 先写采集器，再倒推表结构。 +- 每个 dataset 各自实现 start/status/restart。 + +### 14. 一句话结论 + +项目架构的目标不是把目录做复杂，而是让职责、数据流、依赖和验证路径清楚。普通项目先选通用结构；稳定数据服务优先采用 Dataset First，用 contract、registry、runtime 和质量门禁固定长期演进边界。 + +## 2. 代码组织 + +> 来源：`代码组织.md` + +### 模块化编程 + +- 将代码分割成小的、可重用的模块或函数，每个模块负责只做一件事。 +- 使用明确的模块结构和目录结构来组织代码，使代码更易于导航。 + +### 命名规范 + +- 使用有意义且一致的命名规范，以便从名称就能理解变量、函数、类的作用。 +- 遵循命名约定，如驼峰命名（CamelCase）用于类名，蛇形命名（snake_case）用于函数名和变量名。 + +### 代码注释 + +- 为复杂的代码段添加注释，解释代码的功能和逻辑。 +- 使用块注释（/*...*/）和行注释（//）来区分不同类型的注释。 + +### 代码格式化 + +- 使用一致的代码风格和格式化规则，使用工具如 Prettier 或 Black 自动格式化代码。 +- 使用空行、缩进和空格来增加代码的可读性。 + +## 文档 + +### 文档字符串 + +- 在每个模块、类和函数的开头使用文档字符串，解释其用途、参数和返回值。 +- 选择一致的文档字符串格式，如 Google Style、NumPy/SciPy Style 或 Sphinx Style。 + +### 自动化文档生成 + +- 使用工具如 Sphinx、Doxygen 或 JSDoc 从代码中自动生成文档。 +- 保持文档和代码同步，确保文档始终是最新的。 + +### README 文件 + +- 在每个项目的根目录中包含一个详细的 README 文件，解释项目目的、安装步骤、用法和示例。 +- 使用 Markdown 语法编写 README 文件，使其易于阅读和维护。 + +## 工具 + +### IDE + +- 使用功能强大的 IDE，如 Visual Studio Code、PyCharm 或 IntelliJ，利用其代码自动补全、错误检查和调试功能。 +- 配置 IDE 插件，如 linter（如 ESLint、Pylint）和代码格式化工具。 + +## 3. 开发经验 + +> 来源：`开发经验.md` + +### 目录 + +1. 变量名维护方案 +2. 文件结构与命名规范 +3. 编码规范（Coding Style Guide） +4. 系统架构原则 +5. 程序设计核心思想 +6. 微服务 +7. Redis +8. 消息队列 + +--- + +## **1. 变量名维护方案** + +### 1.1 新建“变量名大全文件” + +建立一个统一的变量索引文件，用于 AI 以及团队整体维护。 + +#### 文件内容包括（格式示例）： + +| 变量名 | 变量注释（描述） | 出现位置（文件路径） | 出现频率（统计） | +| -------- | -------- | -------------------- | -------- | +| user_age | 用户年龄 | /src/user/profile.js | 12 | + +#### 目的 + +* 统一变量命名 +* 方便全局搜索 +* AI 或人工可统一管理、重构 +* 降低命名冲突和语义不清晰带来的风险 + +--- + +## **2. 文件结构与命名规范** + +### 2.1 子文件夹内容 + +每个子目录中需要包含： + +* `agents` —— 负责自动化流程、提示词、代理逻辑 +* `claude.md` —— 存放该文件夹内容的说明文档、设计思路与用途 + +### 2.2 文件命名规则 + +* 使用 **小写英文 + 下划线** 或 **小驼峰**（视语言而定） +* 文件名需体现内容职责 +* 避免缩写与含糊不清的命名 + +示例： + +* `user_service.js` +* `order_processor.py` +* `config_loader.go` + +### 2.3 变量与定义规则及解释 + +* 命名尽可能语义化 +* 遵循英语语法逻辑（名词属性、动词行为） +* 避免 `a, b, c` 此类无意义名称 +* 常量使用大写 + 下划线（如：`MAX_RETRY_COUNT`） + +--- + +## **3. 编码规范** + +#### 3.1 单一职责（Single Responsibility） + +每个文件、每个类、每个函数应只负责一件事。 + +#### 3.2 可复用函数 / 构建（Reusable Components） + +* 提炼公共逻辑 +* 避免重复代码（DRY） +* 模块化、函数化，提高复用价值 + +#### 3.3 消费端 / 生产端 / 状态（变量）/ 变换（函数） + +系统行为应明确划分： + +| 概念 | 说明 | +| ------ | -------------- | +| 消费端 | 接收外部数据或依赖输入的地方 | +| 生产端 | 生成数据、输出结果的地方 | +| 状态（变量） | 存储当前系统信息的变量 | +| 变换（函数） | 处理状态、改变数据的逻辑 | + +明确区分 **输入 → 处理 → 输出**，并独立管理每个环节。 + +#### 3.4 并发（Concurrency） + +* 清晰区分共享资源 +* 避免数据竞争 +* 必要时加锁或使用线程安全结构 +* 区分“并发处理”和“异步处理”的差异 + +--- + +## **4. 系统架构原则** + +#### 4.1 先梳理清楚架构 + +在写代码前先明确： + +* 模块划分 +* 输入输出 +* 数据流向 +* 服务边界 +* 技术栈 +* 依赖关系 + +#### 4.2 理解需求 → 保持简单 → 自动化测试 → 小步迭代 + +严谨开发流程： + +1. 先理解需求 +2. 保持架构与代码简单 +3. 写可维护的自动化测试 +4. 小步迭代，不做大爆炸开发 + +--- + +## **5. 程序设计核心思想** + +### 5.1 从问题开始，而不是从代码开始 + +编程的第一步永远是：**你要解决什么问题？** + +### 5.2 大问题拆小问题（Divide & Conquer） + +复杂问题拆解为可独立完成的小单元。 + +### 5.3 KISS 原则（保持简单） + +减少复杂度、魔法代码、晦涩技巧。 + +### 5.4 DRY 原则（不要重复） + +用函数、类、模块复用逻辑，不要复制粘贴。 + +### 5.5 清晰的命名 + +* `user_age` 比 `a` 清晰 +* `get_user_profile()` 比 `gp()` 清晰 + 命名要体现**用途**和**语义**。 + +### 5.6 单一职责 + +一个函数只处理一个任务。 + +### 5.7 代码可读性优先 + +你写的代码是给别人理解的，不是来炫技的。 + +### 5.8 合理注释 + +注释解释“为什么”，不是“怎么做”。 + +### 5.9 Make it work → Make it right → Make it fast + +先能跑，再让它好看，最后再优化性能。 + +### 5.10 错误是朋友，调试是必修课 + +阅读报错、查日志、逐层定位，是程序员核心技能。 + +### 5.11 Git 版本控制是必备技能 + +永远不要把代码只放本地。 + +### 5.12 测试你的代码 + +未测试的代码迟早会出问题。 + +### 5.13 编程是长期练习 + +所有人都经历过： + +* bug 调不出来 +* 通过时像挖到宝 +* 看着看着能看懂别人代码 + +坚持即是高手。 + +--- + +## **6. 微服务** + +微服务是一种架构模式，将系统拆解为多个 **独立开发、独立部署、独立扩容** 的服务。 + +特点： + +* 每个服务处理一个业务边界（Bounded Context） +* 服务间通过 API 通信（HTTP、RPC、MQ 等） +* 更灵活、更可扩展、容错更高 + +--- + +## **7. Redis（缓存 / 内存数据库）** + +Redis 的作用： + +* 作为缓存极大提升系统“读性能” +* 降低数据库压力 +* 提供计数、锁、队列、Session 等能力 +* 让系统更快、更稳定、更抗压 + +--- + +## **8. 消息队列（Message Queue）** + +消息队列用于服务之间的“异步通信”。 + +作用： + +* 解耦 +* 削峰填谷 +* 异步任务处理 +* 提高系统稳定性与吞吐 + +## 4. AI 编程质量门禁与常见坑 + +> 来源：`AI编程质量门禁与常见坑.md` > 本文档合并原 `系统提示词构建原则.md`、`强前置条件约束.md` 与 `常见坑汇总.md`，用于统一约束 AI 编程行为、质量门禁与常见问题排查。 -## 使用方式 +### 使用方式 - 写系统提示词或 Agent 规则时，先看“系统提示词构建原则”。 - 约束 AI 编码、审查产出、设置硬门禁时，先看“强前置条件约束”。 - 遇到环境、网络、Git、AI 对话和协作问题时，先看“常见坑汇总”。 -## 目录 +### 目录 1. 系统提示词构建原则 2. 强前置条件约束 3. 常见坑汇总 -## 1. 系统提示词构建原则 +### 1. 系统提示词构建原则 -#### 核心身份与行为准则 +##### 核心身份与行为准则 1. 严格遵守项目现有约定，优先分析周围代码和配置 2. 绝不假设库或框架可用，务必先验证项目内是否已使用 @@ -34,7 +941,7 @@ 14. 尊重用户提供的任何上下文信息 15. 始终以专业和负责任的态度行事 -#### 沟通与互动 +##### 沟通与互动 16. 采用专业、直接、简洁的语气 17. 避免对话式填充语 @@ -55,7 +962,7 @@ 32. 仅在需要时进行详细说明 33. 提供足够的信息，但不过载 -#### 任务执行与工作流 +##### 任务执行与工作流 34. 复杂任务必须使用TODO列表进行规划 35. 将复杂任务分解为小的、可验证的步骤 @@ -82,7 +989,7 @@ 56. 在必要时暂停并征求用户反馈 57. 记录关键决策和学习到的经验 -#### 技术与编码规范 +##### 技术与编码规范 58. 优化代码以提高清晰度和可读性 59. 避免使用短变量名，函数名应为动词，变量名应为名词 @@ -114,7 +1021,7 @@ 85. 遵循API设计原则（如RESTful） 86. 代码更改后，进行代码审查 -#### 安全与防护 +##### 安全与防护 87. 执行修改文件系统或系统状态的命令前，必须解释其目的和潜在影响 88. 绝不引入、记录或提交暴露密钥、API密钥或其他敏感信息的代码 @@ -127,7 +1034,7 @@ 95. 遵循隐私保护法规（如GDPR） 96. 定期进行安全审计和漏洞扫描 -#### 工具使用 +##### 工具使用 97. 尽可能并行执行独立的工具调用 98. 使用专用工具而非通用Shell命令进行文件操作 @@ -139,13 +1046,13 @@ 104. 确保工具调用符合当前的操作系统和环境 105. 仅使用明确提供的工具，不自行发明工具 -## 2. 强前置条件约束 +### 2. 强前置条件约束 > 根据你的自由组合 --- -#### 通用开发约束 +##### 通用开发约束 1. 不得采用只解决局部问题的补丁式修改而忽视整体设计与全局优化 2. 不得引入过多用于中间通信的中间状态以免降低可读性并形成循环依赖 @@ -184,7 +1091,7 @@ --- -#### 胶水开发约束 +##### 胶水开发约束 1. 不得自行实现底层或通用逻辑，必须优先、直接、完整复用既有成熟仓库与生产级库 2. 不得为了方便而复制依赖库代码到当前项目中再修改使用 @@ -212,7 +1119,7 @@ --- -#### 系统性代码与功能完整性检查约束 +##### 系统性代码与功能完整性检查约束 24. 不得允许任何形式的功能弱化、裁剪或替代实现通过审计 25. 必须确认所有功能模块均为完整生产级实现 @@ -234,7 +1141,7 @@ 下面是面向 **AI 编码 / 新手 Python 高性能计算** 最容易犯的错误，全部用「禁止」结构整理。它们偏向“看起来能跑，但性能、正确性、可维护性都很危险”的反例。 -### 一、AI 编码常见伪高性能错误 +#### 一、AI 编码常见伪高性能错误 ```text 禁止把“代码更短”误判为“性能更好” @@ -254,7 +1161,7 @@ 禁止把“局部 micro-benchmark 快”误判为“整体系统快” ``` -### 二、AI 容易生成的隐藏低效逻辑 +#### 二、AI 容易生成的隐藏低效逻辑 ```text 禁止为了表达清晰而反复遍历同一数据集 @@ -274,7 +1181,7 @@ 禁止为了“兼容所有情况”让常见路径承担罕见路径成本 ``` -### 三、新手常见复杂度误区 +#### 三、新手常见复杂度误区 ```text 禁止不知道输入规模就选择算法 @@ -292,7 +1199,7 @@ 禁止封装 helper 后忘记其内部复杂度 ``` -### 四、Python 语法糖误用 +#### 四、Python 语法糖误用 ```text 禁止滥用列表推导式生成巨大中间列表 @@ -309,7 +1216,7 @@ 禁止在热路径中频繁创建闭包、lambda、装饰器包装层 ``` -### 五、错误的数据结构直觉 +#### 五、错误的数据结构直觉 ```text 禁止默认用 list 解决所有集合问题 @@ -326,7 +1233,7 @@ 禁止把大量小对象分散在内存中处理密集计算 ``` -### 六、缓存误用 +#### 六、缓存误用 ```text 禁止无脑给函数加 lru_cache @@ -345,7 +1252,7 @@ 禁止为了避免计算而引入更高的内存和一致性成本 ``` -### 七、异步误用 +#### 七、异步误用 ```text 禁止把 CPU 密集计算直接塞进 async 函数 @@ -362,7 +1269,7 @@ 禁止把 async 当成架构补丁掩盖慢查询或慢接口 ``` -### 八、多线程 / 多进程误用 +#### 八、多线程 / 多进程误用 ```text 禁止 CPU 密集任务默认使用 threading @@ -380,7 +1287,7 @@ 禁止为了加速引入死锁、竞态、资源泄漏风险 ``` -### 九、NumPy 新手错误 +#### 九、NumPy 新手错误 ```text 禁止用 np.vectorize 当成真正性能优化 @@ -399,7 +1306,7 @@ 禁止使用过大的临时矩阵完成本可分块计算的问题 ``` -### 十、pandas 新手错误 +#### 十、pandas 新手错误 ```text 禁止在大 DataFrame 上使用 iterrows @@ -419,7 +1326,7 @@ 禁止把 pandas 当作数据库替代品处理超大数据 ``` -### 十一、PyTorch / 深度学习新手错误 +#### 十一、PyTorch / 深度学习新手错误 ```text 禁止推理时忘记 torch.no_grad 或 torch.inference_mode @@ -438,7 +1345,7 @@ 禁止不 profile 就判断瓶颈在模型而不是数据加载 ``` -### 十二、GPU 使用新手错误 +#### 十二、GPU 使用新手错误 ```text 禁止把小规模计算搬到 GPU 后声称一定更快 @@ -453,7 +1360,7 @@ 禁止在 GPU 任务中让 CPU 数据预处理成为瓶颈 ``` -### 十三、JIT / 编译工具误用 +#### 十三、JIT / 编译工具误用 ```text 禁止认为加 Numba 装饰器就一定变快 @@ -468,7 +1375,7 @@ 禁止把编译加速当成算法复杂度错误的补丁 ``` -### 十四、数据库与 ORM 新手错误 +#### 十四、数据库与 ORM 新手错误 ```text 禁止用 ORM 循环访问关系字段造成 N+1 查询 @@ -486,7 +1393,7 @@ 禁止连接池无上限或配置不合理 ``` -### 十五、网络请求新手错误 +#### 十五、网络请求新手错误 ```text 禁止循环中逐个同步请求远程接口而不考虑批量、并发、缓存 @@ -502,7 +1409,7 @@ 禁止把网络延迟问题误判为 Python 循环性能问题 ``` -### 十六、文件与序列化新手错误 +#### 十六、文件与序列化新手错误 ```text 禁止大文件 read() 后再 splitlines() @@ -517,7 +1424,7 @@ 禁止把临时文件无限堆积 ``` -### 十七、日志与观测误用 +#### 十七、日志与观测误用 ```text 禁止热路径中使用 print 调试 @@ -532,7 +1439,7 @@ 禁止没有记录峰值内存就判断内存优化成功 ``` -### 十八、Benchmark 新手错误 +#### 十八、Benchmark 新手错误 ```text 禁止只跑一次计时 @@ -549,7 +1456,7 @@ 禁止 benchmark 中包含打印、文件写入、网络波动等噪声 ``` -### 十九、资源配置新手错误 +#### 十九、资源配置新手错误 ```text 禁止不知道机器 CPU 核数、内存、磁盘、GPU 情况就设并发 @@ -564,7 +1471,7 @@ 禁止缓存、预取、批处理无上限 ``` -### 二十、AI 最容易“自信瞎优化”的错误 +#### 二十、AI 最容易“自信瞎优化”的错误 ```text 禁止没有 profiling 就重写核心逻辑 @@ -584,7 +1491,7 @@ 禁止只修性能，不保留可读性和边界处理 ``` -### 二十一、适合直接放进全局规则的总禁止池 +#### 二十一、适合直接放进全局规则的总禁止池 ```text 禁止把代码短、语法高级、用了 async、用了线程、用了 NumPy、用了 pandas、用了 GPU、用了缓存误判为高性能 @@ -624,7 +1531,7 @@ 如果你的目标是「Python 高性能计算全局禁止池」，还需要补这些。 -### 一、数值计算反例 +#### 一、数值计算反例 ```text 禁止用 Python 原生 for 循环处理大规模数值数组 @@ -641,7 +1548,7 @@ 禁止用 pandas apply 处理本可 NumPy 向量化的数值逻辑 ``` -### 二、内存布局与缓存局部性反例 +#### 二、内存布局与缓存局部性反例 ```text 禁止忽略数组内存连续性 @@ -655,7 +1562,7 @@ 禁止忽略 false sharing 对多线程 / 多进程共享内存性能的影响 ``` -### 三、BLAS / LAPACK / 矩阵计算反例 +#### 三、BLAS / LAPACK / 矩阵计算反例 ```text 禁止手写矩阵乘法、卷积、线性代数核心算子 @@ -670,7 +1577,7 @@ 禁止忽略矩阵尺寸、形状、广播规则对性能和内存的影响 ``` -### 四、JIT / 编译加速反例 +#### 四、JIT / 编译加速反例 ```text 禁止在数值热路径中长期保留纯 Python 循环而不评估 Numba / Cython / Rust / C++ 扩展 @@ -682,7 +1589,7 @@ 禁止引入编译扩展后不提供构建、部署和兼容性说明 ``` -### 五、并行计算反例 +#### 五、并行计算反例 ```text 禁止 CPU 密集任务盲目使用 threading 期待突破 GIL @@ -697,7 +1604,7 @@ 禁止并行化前不确认瓶颈是否可并行 ``` -### 六、共享内存与进程间通信反例 +#### 六、共享内存与进程间通信反例 ```text 禁止多进程之间反复复制大型数组 @@ -710,7 +1617,7 @@ 禁止忽略 NUMA、CPU 亲和性、内存带宽瓶颈 ``` -### 七、GPU / CUDA / 深度学习反例 +#### 七、GPU / CUDA / 深度学习反例 ```text 禁止在 GPU 训练或推理中频繁 CPU-GPU 数据来回拷贝 @@ -728,7 +1635,7 @@ 禁止频繁调用 torch.cuda.empty_cache 作为常规性能手段 ``` -### 八、PyTorch / TensorFlow 反例 +#### 八、PyTorch / TensorFlow 反例 ```text 禁止在训练循环中用 Python list 累积大量 tensor 且保留计算图 @@ -743,7 +1650,7 @@ 禁止未 profile 就盲目修改模型结构声称加速 ``` -### 九、大数据与分布式计算反例 +#### 九、大数据与分布式计算反例 ```text 禁止把超大数据集强行拉到单机内存处理 @@ -758,7 +1665,7 @@ 禁止把分布式系统当作普通 for 循环加速器使用 ``` -### 十、文件格式与数据读取反例 +#### 十、文件格式与数据读取反例 ```text 禁止大规模分析场景默认使用 CSV 而不评估 Parquet / Arrow / Feather / HDF5 @@ -772,7 +1679,7 @@ 禁止把高频读取数据保存在低效序列化格式中 ``` -### 十一、性能测量反例 +#### 十一、性能测量反例 ```text 禁止用 time.time 单次测量判断高性能代码优劣 @@ -787,7 +1694,7 @@ 禁止 benchmark 代码本身污染测量结果 ``` -### 十二、资源控制反例 +#### 十二、资源控制反例 ```text 禁止不限制线程池、进程池、BLAS 线程数、DataLoader worker 数 @@ -800,7 +1707,7 @@ 禁止不设置超时、限流、熔断、重试上限 ``` -### 十三、Python 高性能计算精简总版 +#### 十三、Python 高性能计算精简总版 你可以把这段作为「Python HPC 性能禁止总池」： @@ -833,7 +1740,7 @@ 下面是从这份 XML 里提取出来、适合放进你「vibecoding 全局禁止池」的**禁止项**。我已经去掉了恐吓、人格设定、无效情绪压迫内容，只保留可执行的工程约束。 -### 一、最高优先级禁止 +#### 一、最高优先级禁止 ```text 禁止违反系统消息、开发者消息、工具限制与安全策略 @@ -846,7 +1753,7 @@ 禁止使用未明确提供的工具 ``` -### 二、推理与决策禁止 +#### 二、推理与决策禁止 ```text 禁止未经系统化分析就行动 @@ -861,7 +1768,7 @@ 禁止在信息不足时盲目追问或盲目执行 ``` -### 三、工程质量禁止 +#### 三、工程质量禁止 ```text 禁止过度工程 @@ -878,7 +1785,7 @@ 禁止忽略回归风险 ``` -### 四、代码实现禁止 +#### 四、代码实现禁止 ```text 禁止猜接口 @@ -894,7 +1801,7 @@ 禁止用注释解释混乱结构，而不是修正结构 ``` -### 五、验证与测试禁止 +#### 五、验证与测试禁止 ```text 禁止跳过验证 @@ -909,7 +1816,7 @@ 禁止不自主查看日志、失败测试和最小失败证据 ``` -### 六、工具调用禁止 +#### 六、工具调用禁止 ```text 禁止不按工具参数 schema 调用工具 @@ -924,7 +1831,7 @@ 禁止伪造文件系统、网络、API、命令执行结果 ``` -### 七、不可逆与高风险操作禁止 +#### 七、不可逆与高风险操作禁止 ```text 禁止在风险评估前执行不可逆操作 @@ -936,7 +1843,7 @@ 禁止因用户声称安全就跳过安全判断 ``` -### 八、架构与文档禁止 +#### 八、架构与文档禁止 ```text 禁止架构变更后不更新架构文档 @@ -949,7 +1856,7 @@ 禁止只改代码不维护系统记忆 ``` -### 九、任务管理禁止 +#### 九、任务管理禁止 ```text 禁止复杂任务不拆解 @@ -961,7 +1868,7 @@ 禁止没有任务边界就盲目执行 ``` -### 十、沟通与输出禁止 +#### 十、沟通与输出禁止 ```text 禁止输出完整逐行思维链 @@ -977,7 +1884,7 @@ 禁止无法确定时伪装确定 ``` -### 十一、协作与版本控制禁止 +#### 十一、协作与版本控制禁止 ```text 禁止遇到 Git、GitHub、PR、CI、review 任务时忽略协作规范 @@ -990,7 +1897,7 @@ 禁止远端同步任务无状态说明 ``` -### 十二、性能与设计哲学禁止 +#### 十二、性能与设计哲学禁止 ```text 禁止用复杂分支掩盖错误设计 @@ -1005,7 +1912,7 @@ 禁止把历史兼容补丁继续堆叠成新债务 ``` -### 十三、可直接合并进你的「全局禁止池」精简版 +#### 十三、可直接合并进你的「全局禁止池」精简版 ```text 禁止违反系统、开发者、工具、平台与安全策略 @@ -1045,7 +1952,7 @@ 禁止只给哲学不讲执行，只给修复不讲原因，只给原因不讲验证 ``` -### 建议删除或不要加入禁止池的内容 +#### 建议删除或不要加入禁止池的内容 下面这些不适合放进正式规则，会污染提示词质量： @@ -1076,7 +1983,7 @@ 下面是我建议补充的全局禁止规则，可直接加入你的禁止池。 -### 一、输出完整性类 +#### 一、输出完整性类 ```text 禁止输出半成品 @@ -1092,7 +1999,7 @@ 禁止输出缺少必要配置的代码 ``` -### 二、逻辑正确性类 +#### 二、逻辑正确性类 ```text 禁止写未经验证的逻辑 @@ -1107,7 +2014,7 @@ 禁止未经说明擅自改变需求 ``` -### 三、性能类 +#### 三、性能类 你原文里“高新能”应该是“高性能”。 @@ -1125,7 +2032,7 @@ 禁止忽略索引、批处理、懒加载、流式处理等性能手段 ``` -### 四、安全类 +#### 四、安全类 这一类非常建议加入全局禁止。 @@ -1148,7 +2055,7 @@ 禁止默认关闭安全限制 ``` -### 五、代码质量类 +#### 五、代码质量类 ```text 禁止写不可读代码 @@ -1166,7 +2073,7 @@ 禁止引入与项目技术栈不一致的方案 ``` -### 六、依赖与环境类 +#### 六、依赖与环境类 ```text 禁止随意引入大型依赖 @@ -1180,7 +2087,7 @@ 禁止依赖本地特殊环境才能运行 ``` -### 七、测试与验证类 +#### 七、测试与验证类 ```text 禁止不考虑测试 @@ -1194,7 +2101,7 @@ 禁止只声称“应该可以”而不提供验证方法 ``` -### 八、数据与状态类 +#### 八、数据与状态类 ```text 禁止破坏已有数据 @@ -1209,7 +2116,7 @@ 禁止写可能导致脏数据的逻辑 ``` -### 九、用户体验类 +#### 九、用户体验类 ```text 禁止忽略加载状态 @@ -1223,7 +2130,7 @@ 禁止让用户陷入无反馈状态 ``` -### 十、工程交付类 +#### 十、工程交付类 ```text 禁止只给思路不给落地实现 @@ -1237,7 +2144,7 @@ 禁止忽略向后兼容 ``` -### 十一、AI 编码行为类 +#### 十一、AI 编码行为类 这部分最适合“vibecoding”场景。 @@ -1255,7 +2162,7 @@ 禁止把问题转移给用户“自行处理” ``` -### 十二、推荐你整理成最终版“全局禁止池” +#### 十二、推荐你整理成最终版“全局禁止池” 可以压缩成这版： @@ -1313,7 +2220,7 @@ 所有代码必须以生产级、完整性、正确性、安全性、性能、可维护性、可验证性为最低标准；禁止任何半成品、偷工减料、伪实现、低质量实现或破坏性修改。 ``` -## 3. 常见坑汇总 +### 3. 常见坑汇总 > Vibe Coding 过程中的常见问题和解决方案 @@ -1339,7 +2246,7 @@
🧭 工程决策相关 -#### 先查资料，再写代码 +##### 先查资料，再写代码 一个高频教训是：花很长时间闭门造车，最后才发现已有更成熟、更稳定、更低维护成本的开源方案或官方能力。 @@ -1364,13 +2271,13 @@
🐍 Python 虚拟环境相关 -#### 为什么要用虚拟环境？ +##### 为什么要用虚拟环境？ - 避免不同项目依赖冲突 - 保持系统 Python 干净 - 方便复现和部署 -#### 创建和使用 .venv +##### 创建和使用 .venv ```bash # 创建虚拟环境 @@ -1389,7 +2296,7 @@ pip install -r requirements.txt deactivate ``` -#### 常见问题 +##### 常见问题 | 问题 | 原因 | 解决方案 | |:---|:---|:---| @@ -1401,7 +2308,7 @@ deactivate | pip 版本太旧 | 虚拟环境默认旧版 | `pip install --upgrade pip` | | requirements.txt 缺依赖 | 没导出 | `pip freeze > requirements.txt` | -#### 一键重置环境 +##### 一键重置环境 环境彻底乱了？删掉重来： @@ -1422,7 +2329,7 @@ pip install -r requirements.txt
📦 Node.js 环境相关 -#### 常见问题 +##### 常见问题 | 问题 | 原因 | 解决方案 | |:---|:---|:---| @@ -1432,7 +2339,7 @@ pip install -r requirements.txt | package-lock 冲突 | 多人协作 | 统一用 `npm ci` 而不是 `npm install` | | node_modules 太大 | 正常现象 | 加到 .gitignore，不要提交 | -#### 常用命令 +##### 常用命令 ```bash # 换淘宝源 @@ -1481,7 +2388,7 @@ nvm use 18 | pip/npm 下载慢 | 源在国外 | 换国内镜像源 | | git clone 超时 | 网络限制 | 配置 git 代理或用 SSH | -#### 终端代理配置 +##### 终端代理配置 ```bash # 临时设置（当前终端有效） @@ -1605,7 +2512,7 @@ git config --global https.proxy http://127.0.0.1:7890 |:---|:---|:---| | 代码越写越乱 | 没有架构设计 | 先画架构图，再写代码 | | 改一处坏多处 | 耦合太紧 | 拆分模块，定义清晰接口 | -| 不知道代码放哪 | 目录结构混乱 | 参考 [项目架构模板](项目架构模板.md) | +| 不知道代码放哪 | 目录结构混乱 | 参考本文「项目架构模板」章节 | | 重复代码太多 | 没有抽象 | 提取公共函数/组件 | | 状态管理混乱 | 全局状态滥用 | 用状态管理库，单向数据流 | | 配置散落各处 | 没有统一管理 | 集中到 config 文件或环境变量 | @@ -1628,7 +2535,7 @@ git config --global https.proxy http://127.0.0.1:7890 | 分支太多太乱 | 没有规范 | 用 Git Flow 或 trunk-based | | push 被拒绝 | 远程有新提交 | 先 pull --rebase 再 push | -#### 常用 Git 命令 +##### 常用 Git 命令 ```bash # 撤销工作区修改 @@ -1787,7 +2694,7 @@ git stash pop --- -### 🔥 终极解决方案 +#### 🔥 终极解决方案 实在搞不定？试试这个提示词： @@ -1811,6 +2718,6 @@ git stash pop --- -### 📝 贡献 +#### 📝 贡献 遇到新坑？欢迎 PR 补充！ diff --git a/docs/references/开发经验.md b/docs/references/开发经验.md deleted file mode 100644 index f707656..0000000 --- a/docs/references/开发经验.md +++ /dev/null @@ -1,221 +0,0 @@ -# **开发经验与项目规范整理文档** - -## 目录 - -1. 变量名维护方案 -2. 文件结构与命名规范 -3. 编码规范（Coding Style Guide） -4. 系统架构原则 -5. 程序设计核心思想 -6. 微服务 -7. Redis -8. 消息队列 - ---- - -# **1. 变量名维护方案** - -## 1.1 新建“变量名大全文件” - -建立一个统一的变量索引文件，用于 AI 以及团队整体维护。 - -### 文件内容包括（格式示例）： - -| 变量名 | 变量注释（描述） | 出现位置（文件路径） | 出现频率（统计） | -| -------- | -------- | -------------------- | -------- | -| user_age | 用户年龄 | /src/user/profile.js | 12 | - -### 目的 - -* 统一变量命名 -* 方便全局搜索 -* AI 或人工可统一管理、重构 -* 降低命名冲突和语义不清晰带来的风险 - ---- - -# **2. 文件结构与命名规范** - -## 2.1 子文件夹内容 - -每个子目录中需要包含： - -* `agents` —— 负责自动化流程、提示词、代理逻辑 -* `claude.md` —— 存放该文件夹内容的说明文档、设计思路与用途 - -## 2.2 文件命名规则 - -* 使用 **小写英文 + 下划线** 或 **小驼峰**（视语言而定） -* 文件名需体现内容职责 -* 避免缩写与含糊不清的命名 - -示例： - -* `user_service.js` -* `order_processor.py` -* `config_loader.go` - -## 2.3 变量与定义规则及解释 - -* 命名尽可能语义化 -* 遵循英语语法逻辑（名词属性、动词行为） -* 避免 `a, b, c` 此类无意义名称 -* 常量使用大写 + 下划线（如：`MAX_RETRY_COUNT`） - ---- - -# **3. 编码规范** - -### 3.1 单一职责（Single Responsibility） - -每个文件、每个类、每个函数应只负责一件事。 - -### 3.2 可复用函数 / 构建（Reusable Components） - -* 提炼公共逻辑 -* 避免重复代码（DRY） -* 模块化、函数化，提高复用价值 - -### 3.3 消费端 / 生产端 / 状态（变量）/ 变换（函数） - -系统行为应明确划分： - -| 概念 | 说明 | -| ------ | -------------- | -| 消费端 | 接收外部数据或依赖输入的地方 | -| 生产端 | 生成数据、输出结果的地方 | -| 状态（变量） | 存储当前系统信息的变量 | -| 变换（函数） | 处理状态、改变数据的逻辑 | - -明确区分 **输入 → 处理 → 输出**，并独立管理每个环节。 - -### 3.4 并发（Concurrency） - -* 清晰区分共享资源 -* 避免数据竞争 -* 必要时加锁或使用线程安全结构 -* 区分“并发处理”和“异步处理”的差异 - ---- - -# **4. 系统架构原则** - -### 4.1 先梳理清楚架构 - -在写代码前先明确： - -* 模块划分 -* 输入输出 -* 数据流向 -* 服务边界 -* 技术栈 -* 依赖关系 - -### 4.2 理解需求 → 保持简单 → 自动化测试 → 小步迭代 - -严谨开发流程： - -1. 先理解需求 -2. 保持架构与代码简单 -3. 写可维护的自动化测试 -4. 小步迭代，不做大爆炸开发 - ---- - -# **5. 程序设计核心思想** - -## 5.1 从问题开始，而不是从代码开始 - -编程的第一步永远是：**你要解决什么问题？** - -## 5.2 大问题拆小问题（Divide & Conquer） - -复杂问题拆解为可独立完成的小单元。 - -## 5.3 KISS 原则（保持简单） - -减少复杂度、魔法代码、晦涩技巧。 - -## 5.4 DRY 原则（不要重复） - -用函数、类、模块复用逻辑，不要复制粘贴。 - -## 5.5 清晰的命名 - -* `user_age` 比 `a` 清晰 -* `get_user_profile()` 比 `gp()` 清晰 - 命名要体现**用途**和**语义**。 - -## 5.6 单一职责 - -一个函数只处理一个任务。 - -## 5.7 代码可读性优先 - -你写的代码是给别人理解的，不是来炫技的。 - -## 5.8 合理注释 - -注释解释“为什么”，不是“怎么做”。 - -## 5.9 Make it work → Make it right → Make it fast - -先能跑，再让它好看，最后再优化性能。 - -## 5.10 错误是朋友，调试是必修课 - -阅读报错、查日志、逐层定位，是程序员核心技能。 - -## 5.11 Git 版本控制是必备技能 - -永远不要把代码只放本地。 - -## 5.12 测试你的代码 - -未测试的代码迟早会出问题。 - -## 5.13 编程是长期练习 - -所有人都经历过： - -* bug 调不出来 -* 通过时像挖到宝 -* 看着看着能看懂别人代码 - -坚持即是高手。 - ---- - -# **6. 微服务** - -微服务是一种架构模式，将系统拆解为多个 **独立开发、独立部署、独立扩容** 的服务。 - -特点： - -* 每个服务处理一个业务边界（Bounded Context） -* 服务间通过 API 通信（HTTP、RPC、MQ 等） -* 更灵活、更可扩展、容错更高 - ---- - -# **7. Redis（缓存 / 内存数据库）** - -Redis 的作用： - -* 作为缓存极大提升系统“读性能” -* 降低数据库压力 -* 提供计数、锁、队列、Session 等能力 -* 让系统更快、更稳定、更抗压 - ---- - -# **8. 消息队列（Message Queue）** - -消息队列用于服务之间的“异步通信”。 - -作用： - -* 解耦 -* 削峰填谷 -* 异步任务处理 -* 提高系统稳定性与吞吐 diff --git a/docs/references/项目架构模板.md b/docs/references/项目架构模板.md deleted file mode 100644 index 6eef3ce..0000000 --- a/docs/references/项目架构模板.md +++ /dev/null @@ -1,612 +0,0 @@ -# 项目架构模板 - -> 本文档合并原 `通用项目架构模板.md` 与 `数据集导向数据服务模板.md`，用于新项目初始化、旧项目重组和数据采集服务架构设计。 - -## 1. 使用原则 - -项目架构不是先追求“高级感”，而是先回答这些问题： - -- 代码放哪里。 -- 模块怎么分工。 -- 数据怎么流动。 -- 依赖怎么隔离。 -- 如何测试、部署、回滚和维护。 - -默认顺序： - -1. 先确定交付物：页面、API、数据集、CLI、服务还是组合系统。 -2. 再确定边界：模块边界、数据边界、运行边界、外部依赖边界。 -3. 再确定目录：目录只服务于边界，不反过来制造复杂度。 -4. 最后补门禁：测试、lint、schema、配置示例、README、AGENTS。 - -## 2. 快速选型 - -| 项目类型 | 推荐模板 | -| --- | --- | -| Web API / 后端服务 | Python Web/API 项目结构 | -| 数据分析 / 量化 / 机器学习 | 数据科学项目结构 | -| 多服务 / 大型系统 | Monorepo 项目结构 | -| 前后端一体项目 | Full-Stack Web 应用结构 | -| 长期运行的数据采集服务 | Dataset First 数据服务结构 | - -## 3. Python Web/API 项目结构 - -适合 Flask、FastAPI、RESTful API、Web 后端服务。 - -```text -project/ -├── README.md -├── AGENTS.md -├── LICENSE -├── pyproject.toml -├── requirements.txt -├── .env.example -├── .gitignore -├── docs/ -│ ├── api.md -│ ├── architecture.md -│ └── development.md -├── scripts/ -│ ├── deploy.sh -│ ├── backup.sh -│ └── init_db.sh -├── tests/ -│ ├── conftest.py -│ ├── unit/ -│ └── integration/ -├── src/ -│ ├── main.py -│ ├── app.py -│ ├── config.py -│ ├── api/ -│ │ ├── v1/ -│ │ └── dependencies.py -│ ├── core/ -│ │ ├── models/ -│ │ ├── services/ -│ │ └── utils/ -│ ├── data/ -│ │ ├── repository/ -│ │ └── migrations/ -│ └── external/ -│ ├── clients/ -│ └── integrations/ -├── data/ # 不提交，或只提交 README/.gitkeep -└── logs/ # 不提交，或只提交 README/.gitkeep -``` - -关键边界： - -- `api/` 只处理协议、路由、参数校验和响应格式。 -- `core/services/` 承载业务逻辑。 -- `data/repository/` 隔离数据库访问。 -- `external/` 隔离第三方 API、SDK 和平台依赖。 -- `.env` 不提交，必须提供 `.env.example`。 - -## 4. 数据科学 / 量化项目结构 - -适合量化交易、机器学习、数据分析、AI 研究。 - -```text -project/ -├── README.md -├── AGENTS.md -├── LICENSE -├── pyproject.toml -├── requirements.txt -├── .env.example -├── .gitignore -├── docs/ -│ ├── notebooks/ -│ └── reports/ -├── notebooks/ -│ ├── 01_data_exploration.ipynb -│ ├── 02_feature_engineering.ipynb -│ └── 03_model_training.ipynb -├── scripts/ -│ ├── collect_data.py -│ ├── train_model.py -│ ├── backtest.py -│ └── deploy_model.py -├── tests/ -│ ├── test_data/ -│ └── test_models/ -├── configs/ -│ ├── model.yaml -│ ├── database.yaml -│ └── trading.yaml -├── src/ -│ ├── data/ -│ │ ├── collectors/ -│ │ ├── processors/ -│ │ ├── features/ -│ │ └── loaders.py -│ ├── models/ -│ │ ├── strategies/ -│ │ ├── backtest/ -│ │ └── risk/ -│ ├── core/ -│ │ ├── config.py -│ │ ├── signals.py -│ │ └── portfolio.py -│ └── utils/ -│ ├── logging.py -│ ├── database.py -│ └── api_client.py -├── data/ # 不提交大数据文件 -├── models/ # 不提交大模型/大 checkpoint -└── logs/ -``` - -关键边界： - -- Notebook 用于探索，不作为长期生产入口。 -- `scripts/` 是薄入口，核心逻辑应在 `src/`。 -- 数据、模型、日志默认不进 Git，除非是小型示例或 fixture。 -- 回测、训练、采集、部署脚本必须能复现关键参数。 - -## 5. Monorepo 项目结构 - -适合多服务架构、大型项目、团队协作。 - -```text -project-monorepo/ -├── README.md -├── AGENTS.md -├── LICENSE -├── .gitignore -├── .gitmodules -├── docker-compose.yml -├── docs/ -│ ├── architecture.md -│ └── deployment.md -├── scripts/ -│ ├── build_all.sh -│ ├── test_all.sh -│ └── deploy.sh -├── services/ -│ ├── user-service/ -│ │ ├── Dockerfile -│ │ ├── pyproject.toml -│ │ ├── src/ -│ │ └── tests/ -│ ├── trading-service/ -│ └── data-service/ -├── packages/ -│ ├── common/ -│ └── contracts/ -├── infrastructure/ -│ ├── terraform/ -│ ├── kubernetes/ -│ └── nginx/ -└── monitoring/ - ├── prometheus/ - ├── grafana/ - └── alertmanager/ -``` - -关键边界： - -- 每个 `services/*` 应能独立构建、测试和部署。 -- 公共能力放 `packages/`，不要让服务之间互相直接 import 私有实现。 -- `contracts/` 存 API schema、事件 schema、数据契约，作为跨服务真相源。 -- 顶层脚本只做编排，不隐藏服务内部逻辑。 - -## 6. Full-Stack Web 应用结构 - -适合 SPA、前后端分离项目、轻量产品原型。 - -```text -project/ -├── README.md -├── AGENTS.md -├── LICENSE -├── .gitignore -├── docker-compose.yml -├── docs/ -│ ├── architecture.md -│ └── deployment.md -├── frontend/ -│ ├── package.json -│ ├── vite.config.js -│ ├── public/ -│ └── src/ -│ ├── components/ -│ ├── pages/ -│ ├── store/ -│ └── utils/ -└── backend/ - ├── Dockerfile - ├── pyproject.toml - ├── src/ - │ ├── api/ - │ ├── core/ - │ └── models/ - └── tests/ -``` - -关键边界： - -- 前端状态管理不要直接绑定后端数据库结构。 -- 后端 API contract 应有 schema 或类型定义。 -- 前后端共享类型时，优先从 OpenAPI、JSON Schema 或生成工具派生。 - -## 7. Dataset First 数据服务结构 - -适合长期运行、补数、巡检、血缘、质量治理的数据产品服务。 - -判断规则： - -> 如果服务的核心交付物是“稳定数据集”，而不是页面、接口或一次性脚本，就优先使用 Dataset First。 - -### 一句话 - -以 dataset 为边界，以 schema/data contract 为先，以 runtime/registry/config 为共享控制面，以 collect/backfill/repair/validate 为实现单元。 - -### 适合 - -- 行情事实采集服务。 -- 另类事件采集服务。 -- 周期轮询快照服务。 -- 原子事件流 + 时间桶聚合并存的数据服务。 -- 需要长期运行、补数、巡检、血缘、质量治理的数据服务。 - -### 不适合直接照抄 - -- 纯 API 网关。 -- 纯 Web 应用。 -- 纯交易执行服务。 -- 一次性脚本工具。 -- 不产出稳定 dataset 的临时任务。 - -### 核心原则 - -1. Dataset First：顶层先按 dataset 划分，而不是按 `collector/parser/writer/task` 划分。 -2. Contract First：先定义目标落表、字段语义、主键、时间列、分区策略和刷新粒度。 -3. Layered Modeling：原子层、聚合层、事件流、时间桶、运行状态分开建模。 -4. Shared Control Plane：`config.py`、`registry.py`、`service_entry.py`、`runtime/*` 统一收口。 -5. Legacy Is Explicit：迁移期 legacy 壳只能兼容转发，新逻辑不得回流旧路径。 - -### 标准目录 - -```text -service-root/ -├── README.md -├── AGENTS.md -├── pyproject.toml -├── scripts/ -│ ├── start.sh -│ ├── verify.sh -│ └── check_legacy_shells.sh -├── src// -│ ├── __init__.py -│ ├── config.py -│ ├── registry.py -│ ├── service_entry.py -│ ├── common/ -│ ├── runtime/ -│ │ ├── stack_runner.py -│ │ ├── process_utils.py -│ │ ├── _runner.py -│ │ └── _worker.py -│ ├── writers/ -│ ├── validators/ -│ └── datasets/ -│ ├── / -│ │ ├── contract.py -│ │ ├── collect.py -│ │ ├── backfill.py -│ │ ├── repair.py -│ │ ├── writer.py -│ │ ├── validate.py -│ │ └── README.md -│ ├── / -│ └── _reserved/ -├── tests/ -│ ├── unit/ -│ ├── integration/ -│ └── fixtures/ -└── legacy/ or old-shells/ -``` - -### Dataset 最小结构 - -```text -/ -├── contract.py -├── collect.py -├── backfill.py -├── repair.py -├── writer.py -├── validate.py -└── README.md -``` - -职责边界： - -- `contract.py`：定义 dataset key、resource_id、物理表、主键、幂等键、时间语义、字段语义。 -- `collect.py`：实时采集或轮询采集主逻辑。 -- `backfill.py`：历史补数、文件回填、分页补齐。 -- `repair.py`：缺口修复、异常恢复、局部重算。 -- `writer.py`：统一落库、批量写入、去重、冲突处理。 -- `validate.py`：数据质量检查、行数、字段、时间连续性校验。 -- `README.md`：说明该 dataset 的输入、输出、约束与边界。 - -如果某个 dataset 没有 `repair` 或 `backfill`，必须在 registry 中显式标记为不支持。 - -### Registry 真相矩阵 - -`registry.py` 至少应定义： - -```text -dataset_key -resource_id -runtime_status # active | backfill_only | reserved | disabled -physical_table -group # lf | hf | events | snapshots -source_kind # ws | rest | zip | scrape | file | api -collect_supported -backfill_supported -repair_supported -default_enabled -owner -``` - -推荐额外字段： - -```text -symbol_scope -refresh_granularity -retention_policy -partition_key -schema_version -sensitivity -``` - -Registry 的作用： - -- 它是 dataset 清单的单一真相源。 -- 文档、运行、血缘、权限、门禁都应从 registry 派生。 -- 没有 registry，就会回到“数据集藏在脚本里”的旧问题。 - -### Dataset 命名 - -推荐格式： - -```text -____ -``` - -示例： - -- `spot_trades` -- `futures_um_trades` -- `futures_um_book_ticker` -- `futures_um_book_depth` -- `candles_1m` -- `futures_metrics_5m` -- `futures_um_metrics_atomic` - -命名要求： - -- 名字必须表达数据是什么，而不是代码怎么实现。 -- `_reserved/` 只用于预留未来命名空间，不用于临时文件。 -- 事件流、快照、时间桶、派生结果要在命名或 contract 中显式表达。 - -### Service Entry 与 Runtime - -`service_entry.py` 统一入口只做： - -- `plan` -- `start` -- `stop` -- `status` -- `restart` - -它不直接写业务逻辑，只负责读取 config、读取 registry、调用 runtime runner、输出运行真相。 - -`runtime/` 负责： - -- 进程编排。 -- 模式分组。 -- PID、日志、健康状态。 -- cold-start、restart、stop 行为一致性。 - -业务代码不允许各自实现第二套守护逻辑。 - -### 数据模型分层 - -推荐区分： - -```text -atomic # 原子事件/原子明细 -snapshot # 单次轮询快照 -bucketed # 时间桶聚合结果 -derived # 从事实层再派生的结果 -reserved # 预留但未启用 -``` - -事件流模型适合 trades、orderbook updates、tick events、message stream，重点是顺序、幂等、去重、水位线。 - -时间桶 / 快照模型适合 candles、metrics、periodic snapshots、polling APIs，重点是覆盖、补齐、时间边界一致性。 - -### 新建数据服务流程 - -1. 先定 dataset 清单：哪些 active、哪些 backfill_only、哪些 reserved。 -2. 先写 contract：字段、主键、时间列、分区策略、资源 ID、schema version。 -3. 再建 registry、config、service_entry、runtime。 -4. 逐个实现 dataset：`contract -> writer -> collect -> backfill -> validate -> repair`。 -5. 最后补 README、AGENTS、verify/CI、资源目录、血缘映射、smoke。 - -### 外部源码接入流程 - -1. 先盘点外部源码实际产出的数据对象，不先搬代码。 -2. 把原项目脚本反向映射为 dataset。 -3. 将 API client、auth、rate limiter、storage client、retry/backoff 抽到 `common/`、`runtime/` 或 `writers/`。 -4. 将 legacy 壳显式隔离，只允许兼容转发，不允许承载新逻辑。 - -## 8. 架构设计原则 - -### 关注点分离 - -```text -API -> Service -> Repository -> Database / External System -``` - -上层可以调用下层，下层不能反向依赖上层。 - -### 可测试性 - -- 每个模块可独立测试。 -- 外部依赖可 mock。 -- 核心业务逻辑不依赖 CLI、HTTP、数据库连接对象。 - -### 可配置性 - -```text -环境变量 > 配置文件 > 默认值 -``` - -配置与代码分离，敏感配置不得提交。 - -### 可维护性 - -- 文件名表达职责。 -- 目录边界表达模块边界。 -- 业务逻辑、平台适配、第三方依赖隔离。 - -### 版本控制友好 - -- `data/`、`logs/`、`models/` 默认加入 `.gitignore`。 -- 大文件不进 Git，必要时使用对象存储、Release、DVC 或外部数据源。 -- 提交源代码、配置示例、文档、测试和小型 fixture。 - -## 9. 最低门禁 - -### 代码门禁 - -- 语法检查通过。 -- 单元测试覆盖核心业务。 -- lint/format 有明确命令。 -- 关键路径纳入版本控制。 - -### 结构门禁 - -- 不允许临时脚本成为长期入口。 -- 不允许同一职责存在多套实现入口。 -- 不允许外部 SDK 类型污染核心业务模型。 -- 数据服务不允许新逻辑回流 legacy 壳。 - -### 运行门禁 - -- 服务能按 README 启动。 -- `stop -> start -> status -> restart -> status` 可验证。 -- 日志能证明真实执行源。 -- PID、log、run metadata 可追踪。 - -### 数据门禁 - -- 每个 active dataset 至少有 contract + writer + collect 或 backfill。 -- resource_id 与 registry 一致。 -- 质量检查至少覆盖空写、重复写、时间边界、幂等。 - -### 文档门禁 - -- README 说明项目定位、安装、启动、测试和目录结构。 -- AGENTS 说明 AI Agent 修改边界、验证命令和禁止事项。 -- `.env.example` 说明必要配置。 -- 架构变化同步更新文档。 - -## 10. `.gitignore` 推荐模板 - -```gitignore -# Python -__pycache__/ -*.py[cod] -*.egg-info/ -dist/ -build/ - -# Environment -.env -.venv/ -env/ -venv/ - -# IDE -.vscode/ -.idea/ -*.swp -*.swo -*~ -.DS_Store - -# Data -data/ -*.csv -*.db -*.sqlite -*.duckdb - -# Logs -logs/ -*.log - -# Models -models/ -*.h5 -*.pkl -*.pt -*.onnx - -# Temporary -tmp/ -temp/ -*.tmp -``` - -## 11. 技术选型参考 - -| 场景 | 推荐技术栈 | -| --- | --- | -| Web API | FastAPI + Pydantic + SQLAlchemy | -| 数据处理 | Pandas + NumPy + Polars | -| 机器学习 | Scikit-learn + XGBoost + LightGBM | -| 深度学习 | PyTorch / TensorFlow | -| 数据库 | PostgreSQL + Redis | -| 消息队列 | RabbitMQ / Kafka | -| 任务队列 | Celery | -| 监控 | Prometheus + Grafana | -| 部署 | Docker + Docker Compose | -| CI/CD | GitHub Actions / GitLab CI | - -## 12. 新项目检查清单 - -- [ ] 创建 `README.md`，说明项目目标、安装、启动、测试。 -- [ ] 创建 `AGENTS.md`，说明 AI Agent 操作边界与必须验证命令。 -- [ ] 创建 `LICENSE`。 -- [ ] 创建 `.gitignore`。 -- [ ] 创建 `.env.example`。 -- [ ] 建立虚拟环境或包管理配置。 -- [ ] 明确目录结构。 -- [ ] 明确配置入口。 -- [ ] 设置 lint/format/test 命令。 -- [ ] 编写第一个测试用例。 -- [ ] 记录架构决策和后续 TODO。 - -## 13. 常见反模式 - -- 一开始就做微服务。 -- 所有代码写在一个文件。 -- 架构追求高级感，而不是可维护。 -- 没想清楚数据流就开始写。 -- 目录按技术名堆砌，但没有业务边界。 -- 业务逻辑直接依赖第三方 SDK。 -- 临时脚本长期成为生产入口。 -- 数据服务没有 registry，dataset 清单散落在脚本里。 -- 先写采集器，再倒推表结构。 -- 每个 dataset 各自实现 start/status/restart。 - -## 14. 一句话结论 - -项目架构的目标不是把目录做复杂，而是让职责、数据流、依赖和验证路径清楚。普通项目先选通用结构；稳定数据服务优先采用 Dataset First，用 contract、registry、runtime 和质量门禁固定长期演进边界。 diff --git a/llms.txt b/llms.txt index 343336d..90e2911 100644 --- a/llms.txt +++ b/llms.txt @@ -23,6 +23,7 @@ vibe-coding-cn 是一个中文 Vibe Coding / AI 结对编程系统教程，帮 - docs/getting-started/README.md - docs/concepts/问题求解能力.md - docs/concepts/拼好码.md +- docs/references/工程实践.md - docs/references/技术栈.md - skills/README.md - assets/ai-citation/llms-full.txt diff --git a/metadata/redirects.yml b/metadata/redirects.yml index b1e0f38..774d794 100644 --- a/metadata/redirects.yml +++ b/metadata/redirects.yml @@ -32,15 +32,23 @@ redirects: - from: docs/getting-started/开发环境搭建.md to: docs/getting-started/README.md - from: docs/references/通用项目架构模板.md - to: docs/references/项目架构模板.md + to: docs/references/工程实践.md - from: docs/references/数据集导向数据服务模板.md - to: docs/references/项目架构模板.md + to: docs/references/工程实践.md - from: docs/references/系统提示词构建原则.md - to: docs/references/AI编程质量门禁与常见坑.md + to: docs/references/工程实践.md - from: docs/references/强前置条件约束.md - to: docs/references/AI编程质量门禁与常见坑.md + to: docs/references/工程实践.md - from: docs/references/常见坑汇总.md - to: docs/references/AI编程质量门禁与常见坑.md + to: docs/references/工程实践.md + - from: docs/references/项目架构模板.md + to: docs/references/工程实践.md + - from: docs/references/AI编程质量门禁与常见坑.md + to: docs/references/工程实践.md + - from: docs/references/代码组织.md + to: docs/references/工程实践.md + - from: docs/references/开发经验.md + to: docs/references/工程实践.md - from: skills/ to: skills/ - from: prompts/