From f4d909d5a7b487bc5ecb0635bd352f946b1163b1 Mon Sep 17 00:00:00 2001 From: tukuaiai Date: Sun, 14 Dec 2025 07:50:33 +0800 Subject: [PATCH] Revert "docs: Update file paths and structure in documentation" This reverts commit dd830b3e1b54506eb5eae4d2f3cd917ebc146531. --- AGENTS.md | 38 ++++++++++++++++++++++++ libs/external/CLAUDE.md => CLAUDE.md | 4 +-- GEMINI.md | 3 +- README.md | 44 +++++++++++++++------------- libs/external/AGENTS.md | 2 +- 5 files changed, 67 insertions(+), 24 deletions(-) create mode 100644 AGENTS.md rename libs/external/CLAUDE.md => CLAUDE.md (92%) diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..4ba195a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,38 @@ +# Repository Guidelines + +## Project Structure & Module Organization +- 根目录：`README.md` 给出全貌，`Makefile` 封装日常命令，`CONTRIBUTING.md` 说明贡献流程，`LICENSE` 载明协议。保持根目录扁平，避免巨石文件。 +- 文档库：`documents/` 汇总流程、架构与实践（如 `代码组织.md`、`通用项目架构模板.md`、`开发经验.md`），是理解方法论与协作规则的首选入口。新增流程文档时优先放此处并在 README 链接。 +- 提示词资产：`prompts/` 按角色拆分（system / assistant / coding / user），`prompts/prompts-library/` 提供 Excel ↔ Markdown 互转工具与脚本目录，便于批量维护提示词，适合作为“单一真实来源”。 +- 代码与集成：`libs/` 预留核心实现骨架，`common/`、`database/`、`external/` 分别对应通用模型、存储适配与外部依赖登记；新增模块需保持分层边界与单一职责，避免跨层调用。 +- 备份：`backups/` 内含 `一键备份.sh` 与 `快速备份.py`，用于本地快照或同步，请先在隔离目录试跑，确认输出路径与权限。 + +## Build, Test, and Development Commands +- `make help`：列出所有 Make 目标，是新人快速上手的入口。 +- `make lint`：使用 `markdownlint-cli` 校验全仓库 Markdown，一旦新增文档请先跑通（需本地 Node/npm 环境，可用 `npm install -g markdownlint-cli` 安装）。 +- `make build` / `make test` / `make clean`：目前为占位，落地具体实现后务必更新脚本和说明；建议在 `Makefile` 旁补充注释并保持幂等，避免修改全局状态。 +- 提示词转换：进入 `prompts/prompts-library/` 后执行 `python main.py` 按交互提示进行转换，运行前请确认虚拟环境、依赖与输出目录，并在完成后检查生成 Markdown 是否符合 lint 规则。 + +## Coding Style & Naming Conventions +- 文字层：文档、注释、日志使用中文；代码符号（函数 / 变量 / 模块）统一英文且语义直白，避免晦涩缩写。 +- 缩进与排版：全仓保持空格缩进（2 或 4 空格任选其一但不得混用）；Markdown 列表、代码块与表格对齐清晰，行宽控制在 120 列内。Git diff 可读性优先。 +- 设计品味：优先消除分支与重复；函数力求单一职责且短小；命名遵循小写加中划线或下划线，不使用空格与特殊字符；跨模块接口保持稳定签名。 +- 依赖管理：新增工具或库时记录安装方式、最小版本与来源，必要时在 `documents/工具集.md` 或 README 中补充，并说明为何需要它（性能、兼容、功能）。 + +## Testing Guidelines +- 当前无实测用例；引入代码时请至少提供最小可复现测试。推荐 Python 使用 `pytest`，文件命名 `test_*.py`，夹具精简可读，遵循 red-green-refactor 循环。 +- 文档与提示词改动：提交前运行 `make lint`；如转换脚本涉及数据，附带示例输入 / 输出说明或最小数据样例，确保可重复。 +- 覆盖率基线由模块维护者设定；若暂无标准，确保主流程和边界条件均可被测试验证，必要时在 PR 描述中写明未覆盖的风险，并建议后续补测计划。 + +## Commit & Pull Request Guidelines +- Commit 建议遵循简化 Conventional Commits：`feat|fix|docs|chore|refactor|test: scope – summary`，一句话说明行为与范围；避免笼统的 “update”。 +- PR 必填：变更摘要、动机或关联 Issue、测试与验证步骤（列出运行的命令与结果概览）；涉及文档 / UI 的修改应附对比截图或链接，方便 reviewer 快速复核。 +- 提交前清单：跑通 `make lint`；若新增脚本 / 依赖，更新对应文档与 `Makefile` 目标；确认不携带临时文件或机密数据，并在描述中注明潜在风险或需要 reviewer 特别关注的点。 + +## Security & Configuration Tips +- 运行备份或转换脚本前，确认输出目录不会覆盖私有数据；建议先在临时目录试跑并检查生成文件，必要时使用只读副本。 +- 外部依赖来源记录在 `libs/external/AGENTS.md`，增减依赖时同步维护，保持可追溯；引入第三方脚本需标明许可证与来源。 + +## Architecture Overview & Workflow +- 工作流倡导「规划 → 上下文固定 → 分步实现 → 自测 → 复盘」，对应资产分别存放在 `documents/`、`prompts/`、`libs/` 与备份脚本中。保持单向数据流和清晰责任边界可以避免后期维护成本激增。 +- 设计决策与目录结构更新后，请同步修订本文件与相关文档，确保团队共享同一真相源，减少口头约定与隐式规则。 diff --git a/libs/external/CLAUDE.md b/CLAUDE.md similarity index 92% rename from libs/external/CLAUDE.md rename to CLAUDE.md index 3452bca..e6c7b8f 100644 --- a/libs/external/CLAUDE.md +++ b/CLAUDE.md @@ -11,7 +11,7 @@ This is the **Vibe Coding CN** repository, a workflow, toolset, and knowledge ba ### Prompt Library Management ```bash # Enter the library directory -cd libs/external/prompts-library +cd prompts/prompts-library # Run the interactive conversion tool python3 main.py @@ -33,7 +33,7 @@ bash backups/一键备份.sh - `coding_prompts/`, `system_prompts/`, `user_prompts/` - **`skills/`**: A modular library of skills for the AI, providing domain-specific knowledge for various tools like `ccxt`, `postgresql`, `telegram-dev`, etc. - **`documents/`**: The project's knowledge base, containing methodology, principles, and guides. -- **`libs/external/prompts-library/`**: A Python-based tool for converting prompts between Excel and Markdown formats. +- **`prompts/prompts-library/`**: A Python-based tool for converting prompts between Excel and Markdown formats. - **`backups/`**: Scripts for project backups. - **`libs/`**: Skeleton for shared Python library code. diff --git a/GEMINI.md b/GEMINI.md index ee4dbbf..79b84e6 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -49,6 +49,8 @@ ``` . ├── .gitignore # Git 版本控制忽略文件配置 +├── AGENTS.md # 面向 AI Agent 的贡献与行为准则。 +├── CLAUDE.md # 面向 Claude 模型的上下文与指令。 ├── CODE_OF_CONDUCT.md # 项目行为准则。 ├── CONTRIBUTING.md # 贡献指南。 ├── GEMINI.md # 面向 Gemini 模型的上下文与指令 (本文档)。 @@ -71,7 +73,6 @@ │ ├── database/ # 数据库相关代码。 │ └── external/ # 外部工具、个人配置或实验性代码。 │ ├── AGENTS.md # AI Agent 相关的外部文档。 -│ ├── CLAUDE.md # 面向 Claude 模型的上下文与指令。 │ ├── prompts-library/ # 提示词库管理工具 (Excel-Markdown 互转)。 │ │ ├── main.py # 提示词库管理工具主程序。 │ │ ├── requirements.txt # 工具依赖。 diff --git a/README.md b/README.md index 896223b..728ac22 100644 --- a/README.md +++ b/README.md @@ -139,7 +139,7 @@ PS：下面的经验并非通用，具体实践中要分场景，辩证的看 - [**Skills生成器，把任何资料转agent的Skills（技能）**](https://github.com/yusufkaraaslan/Skill_Seekers) - [**google表格提示词数据库，我系统性收集和制作的几百个适用于各个场景的用户提示词和系统提示词在线表格**](https://docs.google.com/spreadsheets/d/1ngoQOhJqdguwNAilCl1joNwTje7FWWN9WiI2bo5VhpU/edit?gid=2093180351#gid=2093180351&range=A1) - [**系统提示词收集仓库**](https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools) -- [**prompts-library 提示词库xlsx与md文件夹互转工具与使用说明，有几百个适用于各个领域的提示词与元提示词**](./libs/external/prompts-library/) +- [**prompts-library 提示词库xlsx与md文件夹互转工具与使用说明，有几百个适用于各个领域的提示词与元提示词**](./prompts-library/) - [**coding_prompts我收集和制作的几十个vibecoding适用的提示词**](./prompts/coding_prompts/) - [**代码组织.md**](./documents/代码组织.md) - [**关于手机ssh任意位置链接本地计算机，基于frp实现的方法.md**](./documents/关于手机ssh任意位置链接本地计算机，基于frp实现的方法.md) @@ -182,6 +182,8 @@ PS：下面的经验并非通用，具体实践中要分场景，辩证的看 ├── Makefile # 项目自动化脚本，用于代码检查、构建等。 ├── README.md # 项目主文档，包含项目概览、使用指南、资源链接等。 ├── .gitignore # Git 忽略文件。 +├── AGENTS.md # AI 代理相关的文档或配置。 +├── CLAUDE.md # AI 助手的核心行为准则或配置。 │ ├── backups/ # 项目备份脚本。 │ ├── gz/ # 备份文件存放目录。 @@ -198,39 +200,41 @@ PS：下面的经验并非通用，具体实践中要分场景，辩证的看 │ │ ├── models/ # 模型定义。 │ │ │ └── __init__.py │ │ └── utils/ # 工具函数。 -│ │ └── backups/ # 内部备份工具。 +│ │ ├── AGENTS.md # AI 代理相关的文档或配置（utils 内部）。 +│ │ ├── backups/ # 内部备份工具。 +│ │ ├── my-nvim/ # 用户的 Neovim 配置。 +│ │ └── XHS-image-to-PDF-conversion/ # 小红书图片转PDF工具。 │ ├── database/ # 数据库相关模块。 │ │ └── .gitkeep # 占位文件，确保目录被 Git 跟踪。 │ └── external/ # 外部集成模块。 -│ ├── AGENTS.md # AI 代理相关的文档或配置。 -│ ├── CLAUDE.md # AI 助手的核心行为准则或配置。 -│ ├── my-nvim/ # 用户的 Neovim 配置。 -│ ├── prompts-library/ # 提示词库管理工具（Excel-Markdown 转换）。 -│ │ ├── main.py # 提示词库管理工具主入口。 -│ │ ├── scripts/ # 包含 Excel 与 Markdown 互转脚本和配置。 -│ │ ├── prompt_excel/ # 存放 Excel 格式的原始提示词数据。 -│ │ ├── prompt_docs/ # 存放从 Excel 转换而来的 Markdown 提示词文档。 -│ │ └── ... (其他 prompts-library 内部文件) -│ └── XHS-image-to-PDF-conversion/ # 小红书图片转PDF工具。 +│ └── .gitkeep # 占位文件，确保目录被 Git 跟踪。 │ ├── prompts/ # 集中存放所有类型的 AI 提示词。 │ ├── assistant_prompts/ # 辅助类提示词。 │ ├── coding_prompts/ # 专门用于编程和代码生成相关的提示词集合。 -│ │ └── ... (具体编程提示词文件) +│ │ ├── ... (具体编程提示词文件) +│ │ +│ ├── prompts-library/ # 提示词库管理工具（Excel-Markdown 转换） +│ │ ├── main.py # 提示词库管理工具主入口。 +│ │ ├── scripts/ # 包含 Excel 与 Markdown 互转脚本和配置。 +│ │ ├── prompt_excel/ # 存放 Excel 格式的原始提示词数据。 +│ │ ├── prompt_docs/ # 存放从 Excel 转换而来的 Markdown 提示词文档。 +│ │ ├── ... (其他 prompts-library 内部文件) │ │ │ ├── system_prompts/ # AI 系统级提示词，用于设定 AI 行为和框架。 -│ │ └── ... (其他系统提示词) +│ │ ├── CLAUDE.md/ # （注意：此路径下文件和目录同名，可能需用户确认） +│ │ ├── ... (其他系统提示词) │ │ │ └── user_prompts/ # 用户自定义或常用提示词。 │ ├── ASCII图生成.md # ASCII 艺术图生成提示词。 │ ├── 数据管道.md # 数据管道处理提示词。 -│ └── ... (其他用户提示词) +│ ├── ... (其他用户提示词) │ -└── skills/ # 集中存放所有类型的 skills 技能。 - ├── claude-skills # 生成 SKILL 的元 SKILL - │ ├── SKILL.md - │ └── ... (其他) - └── ... (其他 skill) +├── skills/ # 集中存放所有类型的 skills 技能。 +│ ├── claude-skills # 生成 SKILL 的元 SKILL +│ │ ├── SKILL.md +│ │ ├── ... (其他) +│ ├── ... (其他 skill) ``` --- diff --git a/libs/external/AGENTS.md b/libs/external/AGENTS.md index 19408b1..e054a31 100644 --- a/libs/external/AGENTS.md +++ b/libs/external/AGENTS.md @@ -5,4 +5,4 @@ https://github.com/yusufkaraaslan/Skill_Seekers https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools -我的nvim配置（来自https://github.com/LazyVim/LazyVim），./libs/external/my-nvim \ No newline at end of file +我的nvim配置（来自https://github.com/LazyVim/LazyVim），./libs/common/utils/my-nvim \ No newline at end of file