diff --git a/.github/AGENTS.md b/.github/AGENTS.md new file mode 100644 index 0000000..f6c8407 --- /dev/null +++ b/.github/AGENTS.md @@ -0,0 +1,16 @@ +# .github/ Agent 指南 + +本目录承载 GitHub 平台自动化与协作配置。 + +## 约束 + +- 修改 `workflows/` 前必须确认对应本地命令或验证方式。 +- 修改 Issue / PR 模板时保持字段简洁、可执行、可审查。 +- 修改安全政策时同步公开联系邮箱口径。 +- 不提交任何密钥、Token、cookie、私有证书或本地账号信息。 + +## 验证 + +```bash +make test +``` diff --git a/.github/ISSUE_TEMPLATE/AGENTS.md b/.github/ISSUE_TEMPLATE/AGENTS.md new file mode 100644 index 0000000..d9580c7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/AGENTS.md @@ -0,0 +1,9 @@ +# .github/ISSUE_TEMPLATE/ Agent 指南 + +本目录维护 GitHub Issue 模板。 + +## 约束 + +- 字段保持简洁，优先收集问题、期望结果、复现路径和相关链接。 +- 不加入无意义的长免责声明。 +- 不要求用户公开敏感信息。 diff --git a/.github/ISSUE_TEMPLATE/README.md b/.github/ISSUE_TEMPLATE/README.md new file mode 100644 index 0000000..7fd9898 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/README.md @@ -0,0 +1,9 @@ +# .github/ISSUE_TEMPLATE + +Issue 模板目录，用于统一反馈、纠错、资料补充和问题报告格式。 + +## 维护规则 + +- 模板字段必须服务于复现、定位和归类。 +- 不要求用户提交隐私信息、密钥或账号凭证。 +- 模板变更后检查 Markdown 格式。 diff --git a/.github/README.md b/.github/README.md new file mode 100644 index 0000000..399e020 --- /dev/null +++ b/.github/README.md @@ -0,0 +1,19 @@ +# .github + +GitHub 平台配置目录，集中管理 CI、Issue 模板、PR 模板、安全政策、赞助配置和 Wiki 说明。 + +## 目录 + +- `workflows/` - GitHub Actions 工作流。 +- `ISSUE_TEMPLATE/` - Issue 表单和模板。 +- `PULL_REQUEST_TEMPLATE.md` - PR 描述模板。 +- `SECURITY.md` - 安全报告入口。 +- `WIKI.md` - Wiki 使用说明。 +- `labeler.yml` - PR 自动标签规则。 +- `lint_config.json` - Markdown lint 配置。 + +## 维护规则 + +- CI 变更必须能用本地命令复现核心检查。 +- 外链检查规则集中放在 `.lychee.toml`。 +- 不在此目录保存密钥、Token 或本地账号信息。 diff --git a/.github/workflows/AGENTS.md b/.github/workflows/AGENTS.md new file mode 100644 index 0000000..26fa784 --- /dev/null +++ b/.github/workflows/AGENTS.md @@ -0,0 +1,10 @@ +# .github/workflows/ Agent 指南 + +本目录只放 GitHub Actions 工作流。 + +## 约束 + +- 不新增无法在本地解释的黑盒步骤。 +- 不在 workflow 中写入密钥明文。 +- 修改 CI 后必须运行 `make test`，并在推送后查看 GitHub Actions 结果。 +- 外链检查配置优先修改仓库根目录 `.lychee.toml`，不要在 workflow 里堆长排除列表。 diff --git a/.github/workflows/README.md b/.github/workflows/README.md new file mode 100644 index 0000000..c1d1a22 --- /dev/null +++ b/.github/workflows/README.md @@ -0,0 +1,13 @@ +# .github/workflows + +GitHub Actions 工作流目录。 + +## 当前工作流 + +- `ci.yml` - Markdown lint、本地链接、docs 结构、目录治理、metadata、AI citation 和外链检查。 + +## 维护规则 + +- 优先复用 `Makefile` 和 `scripts/` 中已有门禁。 +- 外链检查排除规则放在 `.lychee.toml`。 +- action 版本升级后必须观察远端 CI 结果。 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 026e485..9175c6e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -46,22 +46,4 @@ jobs: - name: Link Checker uses: lycheeverse/lychee-action@v2.8.0 with: - args: >- - --verbose - --no-progress - --exclude-path .history - --exclude-path .github/wiki - --exclude-path node_modules - --exclude-path tools/external - --exclude-path tools/chat-vault - --exclude-path tools/prompts-library - --exclude-path skills/claude-official-skills - --exclude-path skills/auto-skill/scripts/Skill_Seekers-development - --exclude-path skills/auto-skill/scripts/skill-seekers-src - --exclude-path skills/auto-skill/scripts/skill-seekers-configs - --exclude 'https://chatgpt.com.*' - --exclude 'https://claude.ai.*' - --exclude 'https://app.augmentcode.com.*' - --exclude 'https://platform.openai.com.*' - --exclude 'https://user-images.githubusercontent.com.*' - './**/*.md' + args: --verbose --no-progress --config .lychee.toml './**/*.md' diff --git a/.gitignore b/.gitignore index 42f131b..4e492ef 100644 --- a/.gitignore +++ b/.gitignore @@ -12,6 +12,8 @@ eggs/ .eggs/ lib/ lib64/ +!scripts/lib/ +!scripts/lib/** parts/ sdist/ var/ diff --git a/.lychee.toml b/.lychee.toml new file mode 100644 index 0000000..a7b3a4d --- /dev/null +++ b/.lychee.toml @@ -0,0 +1,26 @@ +# Lychee link checker configuration for GitHub Actions. +# +# The repository checks first-party Markdown links with scripts/check-local-links.py. +# Lychee is reserved for public external links and first-party Markdown that should +# be visible to readers. Generated tools, external snapshots and login-only pages +# are excluded here instead of being repeated in workflow YAML. + +exclude_path = [ + '^\.history(/|$)', + '^\.github/wiki(/|$)', + '^node_modules(/|$)', + '^tools/external(/|$)', + '^tools/chat-vault(/|$)', + '^tools/prompts-library(/|$)', + '^skills/claude-official-skills(/|$)', + '^skills/auto-skill/scripts/(Skill_Seekers-development|skill-seekers-src|skill-seekers-configs)(/|$)', +] + +exclude = [ + '^https://chatgpt\.com.*', + '^https://claude\.ai.*', + '^https://app\.augmentcode\.com.*', + '^https://platform\.openai\.com.*', + '^https://user-images\.githubusercontent\.com.*', + '^https://notebooklm\.google\.com.*', +] diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 296aef1..04b1c98 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -59,7 +59,7 @@ representative at an online or offline event. Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at -[tukuaiai@example.com](mailto:tukuaiai@example.com). +[tukuai.ai@gmail.com](mailto:tukuai.ai@gmail.com). All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the diff --git a/docs/references/README.md b/docs/references/README.md index dd8bd7c..0f044df 100644 --- a/docs/references/README.md +++ b/docs/references/README.md @@ -2883,6 +2883,8 @@ pip install -r requirements.txt
📦 Node.js 环境相关（点击展开/收起） +> 本节是通用 Web / Node.js 项目的排障示例，不代表本仓根目录需要保留 `package.json`、`package-lock.json` 或 `node_modules/`。本仓根目录当前使用 `npx --yes markdownlint-cli@0.48.0` 执行 Markdown lint，不提交本地 Node 依赖目录。 + ###### 常见问题 diff --git a/scripts/check-ai-citation.py b/scripts/check-ai-citation.py index e3d9bfb..189e849 100644 --- a/scripts/check-ai-citation.py +++ b/scripts/check-ai-citation.py @@ -8,9 +8,9 @@ import sys import urllib.parse from pathlib import Path +from lib.taxonomy import taxonomy_document_paths ROOT = Path(__file__).resolve().parents[1] -TAXONOMY = ROOT / "metadata/taxonomy.yml" AI_ENTRY_FILES = [ Path("llms.txt"), Path("assets/ai-citation/llms-full.txt"), @@ -28,31 +28,6 @@ MARKDOWN_LINK_PATTERN = re.compile(r"!??\[[^\]]*\]\(([^)]+)\)") EXTERNAL_PREFIXES = ("http://", "https://", "mailto:", "tel:", "data:") -def strip_quotes(value: str) -> str: - return value.strip().strip("\"'") - - -def taxonomy_document_paths() -> list[str]: - paths: list[str] = [] - in_documents = False - - for line in TAXONOMY.read_text(encoding="utf-8").splitlines(): - if line == "documents:": - in_documents = True - continue - if in_documents and line and not line.startswith(" "): - break - if not in_documents: - continue - - stripped = line.strip() - if stripped.startswith("- path:"): - _, value = stripped.split(":", 1) - paths.append(strip_quotes(value)) - - return paths - - def github_slug(title: str) -> str: title = re.sub(r"<[^>]+>", "", title.strip().lower()) title = re.sub(r"[`*_~]", "", title) diff --git a/scripts/check-directory-docs.py b/scripts/check-directory-docs.py index a9e4683..b8d8ac2 100644 --- a/scripts/check-directory-docs.py +++ b/scripts/check-directory-docs.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""Check required repository-owned directories have README.md and AGENTS.md.""" +"""Check repository-owned directories have README.md and AGENTS.md.""" from __future__ import annotations @@ -9,6 +9,9 @@ from pathlib import Path ROOT = Path(__file__).resolve().parents[1] REQUIRED_DIRS = [ + Path(".github"), + Path(".github/ISSUE_TEMPLATE"), + Path(".github/workflows"), Path("assets"), Path("assets/ai-citation"), Path("assets/datasets"), @@ -23,24 +26,60 @@ REQUIRED_DIRS = [ Path("metadata"), Path("prompts"), Path("scripts"), + Path("scripts/lib"), Path("skills"), Path("skills/auto-skill"), + Path("skills/auto-skill/assets"), + Path("skills/auto-skill/references"), + Path("skills/auto-skill/scripts"), Path("tools"), Path("tools/chat-vault"), Path("tools/config"), Path("tools/config/.codex"), Path("tools/external"), Path("tools/prompts-library"), + Path("tools/prompts-library/docs"), + Path("tools/prompts-library/scripts"), ] GENERATED_OR_VENDOR_DIRS = [ Path("node_modules"), ] +SKIP_PARTS = {".git", ".history", "node_modules", "__pycache__"} +SKIP_PREFIXES = [ + Path(".github/wiki"), +] +VENDOR_SUBTREES = [ + Path("tools/external"), + Path("tools/chat-vault"), +] + + +def should_skip(directory: Path) -> bool: + rel = directory.relative_to(ROOT) + if any(part in SKIP_PARTS for part in rel.parts): + return True + if directory.is_symlink(): + return True + if any(rel == prefix or prefix in rel.parents for prefix in SKIP_PREFIXES): + return True + return any(vendor in rel.parents for vendor in VENDOR_SUBTREES) + + +def repository_owned_dirs() -> list[Path]: + dirs = set(REQUIRED_DIRS) + for directory in ROOT.rglob("*"): + if not directory.is_dir(): + continue + if should_skip(directory): + continue + dirs.add(directory.relative_to(ROOT)) + return sorted(dirs) def main() -> int: errors: list[str] = [] - for rel_dir in REQUIRED_DIRS: + for rel_dir in repository_owned_dirs(): directory = ROOT / rel_dir if not directory.is_dir(): errors.append(f"{rel_dir}: required directory is missing") @@ -61,7 +100,7 @@ def main() -> int: print(f"TOTAL={len(errors)}") return 1 - print(f"OK directory README/AGENTS pairs checked: {len(REQUIRED_DIRS)} directories") + print(f"OK directory README/AGENTS pairs checked: {len(repository_owned_dirs())} directories") return 0 diff --git a/scripts/check-doc-structure.py b/scripts/check-doc-structure.py index 1d1f60b..242ea2e 100644 --- a/scripts/check-doc-structure.py +++ b/scripts/check-doc-structure.py @@ -7,9 +7,9 @@ import re import sys from pathlib import Path +from lib.taxonomy import doc_readmes_from_taxonomy, taxonomy_sections ROOT = Path(__file__).resolve().parents[1] -TAXONOMY = ROOT / "metadata/taxonomy.yml" SKIP_PARTS = {".git", ".history", "node_modules"} SKIP_PREFIXES = [ Path(".github/wiki"), @@ -19,69 +19,6 @@ ANCHOR_PATTERN = re.compile(r" str: - return value.strip().strip("\"'") - - -def taxonomy_sections() -> dict[str, dict[str, str]]: - sections: dict[str, dict[str, str]] = {} - current: str | None = None - in_sections = False - - for line in TAXONOMY.read_text(encoding="utf-8").splitlines(): - if line == "sections:": - in_sections = True - continue - if in_sections and line and not line.startswith(" "): - break - if not in_sections: - continue - - section_match = re.match(r"^ ([A-Za-z0-9_-]+):\s*$", line) - if section_match: - current = section_match.group(1) - sections[current] = {} - continue - field_match = re.match(r"^ (path|entry|agent_guide):\s*(.+?)\s*$", line) - if current and field_match: - sections[current][field_match.group(1)] = strip_quotes(field_match.group(2)) - - return sections - - -def taxonomy_document_paths() -> list[str]: - paths: list[str] = [] - in_documents = False - - for line in TAXONOMY.read_text(encoding="utf-8").splitlines(): - if line == "documents:": - in_documents = True - continue - if in_documents and line and not line.startswith(" "): - break - if not in_documents: - continue - - stripped = line.strip() - if stripped.startswith("- path:"): - _, value = stripped.split(":", 1) - paths.append(strip_quotes(value)) - - return paths - - -def doc_readmes_from_taxonomy() -> dict[Path, list[str]]: - readmes: dict[Path, list[str]] = {} - - for target in taxonomy_document_paths(): - path_part, _, anchor = target.partition("#") - if not anchor or not path_part.startswith("docs/") or not path_part.endswith("/README.md"): - continue - readmes.setdefault(Path(path_part), []).append(anchor) - - return readmes - - def strip_fenced_code(text: str) -> str: lines: list[str] = [] in_fence = False diff --git a/scripts/lib/AGENTS.md b/scripts/lib/AGENTS.md new file mode 100644 index 0000000..2a04733 --- /dev/null +++ b/scripts/lib/AGENTS.md @@ -0,0 +1,9 @@ +# scripts/lib/ Agent 指南 + +本目录是 `scripts/` 下质量门禁脚本的共享库。 + +## 约束 + +- 公共函数必须保持小而稳定，避免把具体业务规则塞进通用库。 +- 不允许在 import 阶段执行文件写入、网络访问或命令调用。 +- 变更后至少运行 `make test`，确认所有脚本入口仍可直接执行。 diff --git a/scripts/lib/README.md b/scripts/lib/README.md new file mode 100644 index 0000000..b8e4762 --- /dev/null +++ b/scripts/lib/README.md @@ -0,0 +1,13 @@ +# scripts/lib + +共享脚本库，放置多个质量门禁共同使用的解析与校验辅助函数。 + +## 当前模块 + +- `taxonomy.py` - 读取 `metadata/taxonomy.yml`，输出目录分区和文档路径。 + +## 约束 + +- 只放无副作用的纯辅助逻辑。 +- 不在导入时读写仓库文件。 +- 修改公共函数后必须运行 `make test`。 diff --git a/scripts/lib/__init__.py b/scripts/lib/__init__.py new file mode 100644 index 0000000..71a4b9f --- /dev/null +++ b/scripts/lib/__init__.py @@ -0,0 +1 @@ +"""Shared helpers for repository quality gate scripts.""" diff --git a/scripts/lib/taxonomy.py b/scripts/lib/taxonomy.py new file mode 100644 index 0000000..d59acbc --- /dev/null +++ b/scripts/lib/taxonomy.py @@ -0,0 +1,81 @@ +"""Helpers for reading the repository taxonomy file. + +The project intentionally keeps metadata in a small YAML subset so the quality +gate scripts can run without extra Python dependencies. +""" + +from __future__ import annotations + +import re +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[2] +TAXONOMY = ROOT / "metadata/taxonomy.yml" + + +def strip_quotes(value: str) -> str: + """Remove simple surrounding quotes from a taxonomy scalar.""" + return value.strip().strip("\"'") + + +def taxonomy_sections() -> dict[str, dict[str, str]]: + """Return top-level taxonomy sections keyed by section id.""" + sections: dict[str, dict[str, str]] = {} + current: str | None = None + in_sections = False + + for line in TAXONOMY.read_text(encoding="utf-8").splitlines(): + if line == "sections:": + in_sections = True + continue + if in_sections and line and not line.startswith(" "): + break + if not in_sections: + continue + + section_match = re.match(r"^ ([A-Za-z0-9_-]+):\s*$", line) + if section_match: + current = section_match.group(1) + sections[current] = {} + continue + field_match = re.match(r"^ (path|entry|agent_guide):\s*(.+?)\s*$", line) + if current and field_match: + sections[current][field_match.group(1)] = strip_quotes(field_match.group(2)) + + return sections + + +def taxonomy_document_paths() -> list[str]: + """Return document path entries from metadata/taxonomy.yml.""" + paths: list[str] = [] + in_documents = False + + for line in TAXONOMY.read_text(encoding="utf-8").splitlines(): + if line == "documents:": + in_documents = True + continue + if in_documents and line and not line.startswith(" "): + break + if not in_documents: + continue + + stripped = line.strip() + if stripped.startswith("- path:"): + _, value = stripped.split(":", 1) + paths.append(strip_quotes(value)) + + return paths + + +def doc_readmes_from_taxonomy() -> dict[Path, list[str]]: + """Return docs README files and required main anchors from taxonomy.""" + readmes: dict[Path, list[str]] = {} + + for target in taxonomy_document_paths(): + path_part, _, anchor = target.partition("#") + if not anchor or not path_part.startswith("docs/") or not path_part.endswith("/README.md"): + continue + readmes.setdefault(Path(path_part), []).append(anchor) + + return readmes diff --git a/scripts/sync-doc-toc.py b/scripts/sync-doc-toc.py index 2d45b68..5793122 100644 --- a/scripts/sync-doc-toc.py +++ b/scripts/sync-doc-toc.py @@ -7,51 +7,14 @@ import re import sys from pathlib import Path +from lib.taxonomy import doc_readmes_from_taxonomy ROOT = Path(__file__).resolve().parents[1] -TAXONOMY = ROOT / "metadata/taxonomy.yml" SUMMARY_LINE = "完整细粒度目录（点击展开/收起）" ANCHOR_PATTERN = re.compile(r" str: - return value.strip().strip("\"'") - - -def taxonomy_document_paths() -> list[str]: - paths: list[str] = [] - in_documents = False - - for line in TAXONOMY.read_text(encoding="utf-8").splitlines(): - if line == "documents:": - in_documents = True - continue - if in_documents and line and not line.startswith(" "): - break - if not in_documents: - continue - - stripped = line.strip() - if stripped.startswith("- path:"): - _, value = stripped.split(":", 1) - paths.append(strip_quotes(value)) - - return paths - - -def doc_readmes_from_taxonomy() -> dict[Path, list[str]]: - readmes: dict[Path, list[str]] = {} - - for target in taxonomy_document_paths(): - path_part, _, anchor = target.partition("#") - if not anchor or not path_part.startswith("docs/") or not path_part.endswith("/README.md"): - continue - readmes.setdefault(Path(path_part), []).append(anchor) - - return readmes - - def heading_after(lines: list[str], start: int) -> tuple[int, str] | None: for line in lines[start + 1 : start + 8]: stripped = line.strip() diff --git a/skills/auto-skill/assets/AGENTS.md b/skills/auto-skill/assets/AGENTS.md new file mode 100644 index 0000000..219f833 --- /dev/null +++ b/skills/auto-skill/assets/AGENTS.md @@ -0,0 +1,9 @@ +# skills/auto-skill/assets/ Agent 指南 + +本目录保存 `auto-skill` 的可复用资产。 + +## 约束 + +- 不存放临时输出、下载缓存或未整理的原始材料。 +- 资产命名必须能说明用途。 +- 资产被脚本或文档引用时，同步更新对应路径。 diff --git a/skills/auto-skill/assets/README.md b/skills/auto-skill/assets/README.md new file mode 100644 index 0000000..c8f11aa --- /dev/null +++ b/skills/auto-skill/assets/README.md @@ -0,0 +1,9 @@ +# skills/auto-skill/assets + +`auto-skill` 的长期资产目录，用于保存模板、示例、schema 或可复用静态材料。 + +## 维护规则 + +- 只放 `auto-skill` 执行时需要复用的资产。 +- 大文件、生成物和临时抓取结果不得放入本目录。 +- 新增资产后在 `skills/auto-skill/README.md` 或 `SKILL.md` 中补充引用。 diff --git a/skills/auto-skill/references/AGENTS.md b/skills/auto-skill/references/AGENTS.md new file mode 100644 index 0000000..a0475d5 --- /dev/null +++ b/skills/auto-skill/references/AGENTS.md @@ -0,0 +1,9 @@ +# skills/auto-skill/references/ Agent 指南 + +本目录保存 `auto-skill` 的参考资料和操作细则。 + +## 约束 + +- 参考资料应服务于 `SKILL.md` 的渐进式展开，不要把主入口写成超长文档。 +- 外部事实变更时优先更新引用来源和日期。 +- 删除或重命名参考文件时，同步检查 `SKILL.md`、`README.md` 和脚本引用。 diff --git a/skills/auto-skill/scripts/AGENTS.md b/skills/auto-skill/scripts/AGENTS.md new file mode 100644 index 0000000..f1b04a9 --- /dev/null +++ b/skills/auto-skill/scripts/AGENTS.md @@ -0,0 +1,10 @@ +# skills/auto-skill/scripts/ Agent 指南 + +本目录维护 `auto-skill` 的执行脚本和外部工具软链接入口。 + +## 约束 + +- 不把外部仓库源码复制进脚本目录；需要暴露时使用软链接或 submodule。 +- 不在脚本中硬编码本地绝对路径、Token 或账号信息。 +- 修改 shell 脚本后检查可执行位和基本语法。 +- `Skill_Seekers-development` 相关路径视为外部工具入口，主仓门禁不深入检查其内部链接。 diff --git a/skills/auto-skill/scripts/README.md b/skills/auto-skill/scripts/README.md new file mode 100644 index 0000000..4fe4625 --- /dev/null +++ b/skills/auto-skill/scripts/README.md @@ -0,0 +1,16 @@ +# skills/auto-skill/scripts + +`auto-skill` 的辅助脚本目录。 + +## 当前内容 + +- `create-skill.sh` - 创建 skill 骨架。 +- `validate-skill.sh` - 校验 skill 结构。 +- `skill-seekers-*.sh` - Skill Seekers 相关适配脚本。 +- `Skill_Seekers-development`、`skill-seekers-src`、`skill-seekers-configs` - 指向外部仓库内容的软链接入口。 + +## 维护规则 + +- 软链接入口属于外部工具暴露面，不直接修改其目标内容。 +- 脚本应保持可重复执行，并在失败时输出明确原因。 +- 修改脚本后运行对应 `--help`、dry-run 或最小校验命令。 diff --git a/tools/prompts-library/README.md b/tools/prompts-library/README.md index 723af4d..3be25c2 100644 --- a/tools/prompts-library/README.md +++ b/tools/prompts-library/README.md @@ -1,282 +1,92 @@ - -

- - 项目横幅 -

+# prompts-library -
+`tools/prompts-library/` 是本仓内的提示词格式转换工具，用于在 Excel、Markdown 和 JSONL 之间转换提示词资产。 -# Prompt Library +它不是独立仓库首页，也不再引用旧的 `tukuaiai/prompt-library` 仓库口径。当前目录作为 `vibe-coding-cn` 的内部工具维护。 -**一个全面的高质量AI提示词库，支持Excel和Markdown格式之间的双向转换。** +## 功能 ---- +- Excel -> Markdown：把表格提示词导出为 Markdown 文档目录。 +- Markdown -> Excel：把 Markdown 文档目录还原为 Excel 工作簿。 +- Markdown -> JSONL：把 Markdown 提示词转换为 JSONL。 +- JSONL -> Excel：把 JSONL 数据转换为 Excel。 +- Excel(JSONL) -> JSONL：把内部 JSONL 格式的 Excel 按工作表拆成 JSONL 文件。 - -

- 构建状态 - 最新版本 - 许可证 - 主要语言 - 代码大小 -

+## 目录结构 -[✨ 功能特性](#功能特性) • -[🚀 快速开始](#快速开始) • -[⚙️ 架构与工作流程](#architecture-workflow) • -[🤝 参与贡献](#参与贡献) • -[🗺️ 路线图](#roadmap) - -
- - - ---- - -## 🖼️ 概览与演示 - -本词库是一个结构化的、高质量的AI提示词（Prompts）集合，旨在为开发人员、研究人员和内容创作者提供强大而灵活的工具。与许多静态的提示词列表不同，本项目提供了一个双向转换的工作流程，允许用户在易于协作的Excel格式和便于版本控制的Markdown格式之间无缝切换。 - -> **核心理念**: 让高质量的提示词像代码一样被管理、分享和迭代。 - -

- - 项目演示动画 -

- ---- - - - -## ✨ 功能特性 - -- 📊 **双向转换**: 支持Excel ↔️ Markdown格式互转，兼顾易用性与版本控制。 -- 🗂️ **结构化管理**: 包含多个分类，覆盖从软件工程到哲学思辨的广泛领域。 -- 🤖 **多平台兼容**: 提示词设计兼容Claude、GPT、Gemini等主流AI模型。 -- 🛠️ **自动化工具**: 提供命令行工具，支持批量转换和管理。 -- 🎨 **易于扩展**: 可以方便地添加新的提示词、分类和自定义属性。 - ---- - - - -## ⚙️ 架构与工作流程 - -本项目的工作流程围绕“以结构化数据为中心”的思想构建。 - -```mermaid -graph LR - subgraph "Excel-First 工作流" - A[1. 在 Excel 中编辑提示词] --> B{运行转换脚本}; - end - - subgraph "Git-Native 工作流" - D[3. 在 Markdown 文件中编辑] --> E{运行转换脚本}; - end - - subgraph "中央产物" - B --> C[2. 生成结构化的 Markdown 文件]; - E --> F[4. 更新或生成 Excel 文件] - end - - style A fill:#D5E8D4 - style D fill:#DAE8FC - style C fill:#F8CECC - style F fill:#F8CECC +```text +tools/prompts-library/ + README.md + AGENTS.md + main.py + requirements.txt + docs/ + scripts/ ``` -这个流程确保了无论是喜欢电子表格的非技术人员，还是习惯于Git和代码编辑器的开发人员，都可以高效地协作。 ---- - -## 🚀 快速开始 - -### 1. 环境依赖 - -- [Python](https://www.python.org/) >= 3.8 - -### 2. 安装 - -
-从源码构建（点击展开/收起） +## 安装依赖 ```bash -git clone https://github.com/tukuaiai/prompt-library.git -cd prompt-library -pip install -r requirements.txt +cd tools/prompts-library +python3 -m pip install -r requirements.txt ``` -
-### 3. 使用 - -
-Excel → Markdown 转换（点击展开/收起） +部分辅助脚本有单独依赖： + +```bash +python3 -m pip install -r scripts/requirements.txt +``` + +## 常用命令 + +查看入口参数： + +```bash +python3 main.py --help +``` + +交互式转换： ```bash -# 运行交互式转换 python3 main.py ``` -程序将扫描 `prompt_excel` 目录下的 `.xlsx` 文件，并让你选择一个进行转换。结果将输出到 `prompt_docs` 目录下一个带时间戳的文件夹中。 -
-
-Markdown → Excel 转换（点击展开/收起） +指定转换模式： ```bash -# 运行交互式转换 -python3 main.py -``` -程序将扫描 `prompt_docs` 目录，让你选择一个文档集，然后将其转换回 Excel 文件，并输出到 `prompt_excel` 目录下一个带时间戳的文件夹中。 -
- -
-非交互式转换（点击展开/收起） - -```bash -# 指定要转换的 Excel 文件 -python3 main.py --select "prompt_excel/your_file.xlsx" - -# 指定要转换的 Markdown 目录 -python3 main.py --select "prompt_docs/your_docs_folder" -``` - -
- -
-Gemini 无头：Markdown → JSONL 批处理（点击展开/收起） - -```bash -# 将目录中的 .md 提示词批量转为 JSONL（默认输入 2/，输出 2/prompts.jsonl） -python3 scripts/gemini_jsonl_batch.py --input 2 --output 2/prompts.jsonl --model gemini-2.5-flash -``` - -- 脚本内置固定系统提示词，调用 `gemini --allowed-tools '' --output-format text` 确保纯文本 JSONL。 -- 需要本地已登录的 Gemini CLI；如需代理，请自行设置 `http_proxy/https_proxy` 环境变量。 -- 可用 `-v` 查看逐文件处理日志，`--gemini-cmd` 自定义 CLI 可执行路径。 -
- -
-内部 JSONL Excel → JSONL 目录（点击展开/收起） - -```bash -# 将内部 JSONL 格式的 xlsx 按工作表拆分为多个 jsonl 文件 +python3 main.py --select "prompt_excel/example.xlsx" --mode excel2docs +python3 main.py --select "prompt_docs/example" --mode docs2excel +python3 main.py --select "prompt_docs/example" --mode docs2jsonl +python3 main.py --select "prompt_jsonl/example.jsonl" --mode jsonl2excel python3 main.py --select "prompt_excel/prompt_jsonl.xlsx" --mode jsonl_excel2jsonl ``` -- 输出目录格式为 `prompt_jsonl/_/` -- 每个工作表输出一个独立的 `.jsonl` 文件 -- 文件名格式为 `<序号>_.jsonl` -- 若工作表中没有标准 JSON 单元格，会对纯文本单元格做 JSONL 兜底转换 -- 自动忽略名为 `说明` 的工作表 -
+无交互执行： ---- - -
-❓ 常见问题 (FAQ) (可选)（点击展开/收起） - -- **Q: 为什么转换会失败？** - - **A:** 请确保您的Excel文件格式与提供的示例一致，特别是工作表（Sheet）的名称和列的标题。 - -- **Q: 我可以添加自己的转换逻辑吗？** - - **A:** 当然可以。核心逻辑位于 `scripts/` 目录下，您可以自由修改或扩展它们。 - -
- ---- - - - - - -## 🗺️ 路线图 - -```mermaid -gantt - title 项目发展路线图 - dateFormat YYYY-MM - section 核心功能 - 双向转换脚本 :done, 2024-10, 30d - 交互式CLI :done, 2024-11, 20d - section 未来计划 - Web界面 :2025-01, 30d - 更丰富的导出格式 :2025-02, 20d - 云同步功能 : 2025-03, 30d +```bash +python3 main.py --select "prompt_excel/example.xlsx" --mode excel2docs --non-interactive ``` ---- +## 输入输出约定 -## 🤝 参与贡献 +- 默认 Excel 输入目录：`prompt_excel/` +- 默认 Markdown 输入/输出目录：`prompt_docs/` +- 默认 JSONL 输出目录：`prompt_jsonl/` +- `prompt_jsonl/` 是生成物，已在 `.gitignore` 中忽略。 -我们热烈欢迎各种形式的贡献！如果您对本项目有任何想法或建议，请随时开启一个 [Issue](https://github.com/tukuaiai/prompt-library/issues) 或提交一个 [Pull Request](https://github.com/tukuaiai/prompt-library/pulls)。 +## 维护规则 -在您开始之前，请花点时间阅读我们的 [**贡献指南 (CONTRIBUTING.md)**](https://github.com/tukuaiai/prompt-library/blob/main/CONTRIBUTING.md) 和 [**行为准则 (CODE_OF_CONDUCT.md)**](https://github.com/tukuaiai/prompt-library/blob/main/CODE_OF_CONDUCT.md)。 +- 修改转换逻辑时，优先阅读 `main.py` 和 `scripts/` 中对应脚本。 +- 新增依赖必须同步更新 `requirements.txt` 或 `scripts/requirements.txt`。 +- 不提交生成目录、缓存、临时导出或本地凭证。 +- 修改后至少运行： -### ✨ 贡献者们 +```bash +python3 main.py --help +``` -感谢所有为本项目做出贡献的开发者！ +如改动影响仓库文档或链接，还需要在仓库根目录运行： - - - - ---- - -## 🛡️ 安全策略 - -我们非常重视项目的安全性。如果您发现了任何安全漏洞，请不要公开讨论，而是通过电子邮件 `tukuaiai@example.com` 与我们联系。 - ---- - - - -## 📜 许可证 - -本项目采用 [MIT](https://github.com/tukuaiai/prompt-library/blob/main/LICENSE) 许可证。 - ---- - -
- -**如果这个项目对您有帮助，请不要吝啬您的 Star ⭐！** - - - - Star History Chart - - -
- -**Made with ❤️ by tukuaiai** - -[⬆ 回到顶部](#prompt-library) - -
+```bash +make test +``` diff --git a/tools/prompts-library/docs/AGENTS.md b/tools/prompts-library/docs/AGENTS.md new file mode 100644 index 0000000..4ad3306 --- /dev/null +++ b/tools/prompts-library/docs/AGENTS.md @@ -0,0 +1,9 @@ +# tools/prompts-library/docs/ Agent 指南 + +本目录保存 prompts-library 工具文档。 + +## 约束 + +- 文档必须明确区分真实路径、示例路径和占位输入。 +- 不新增失效外链作为事实来源。 +- 修改工具行为说明时同步检查 `tools/prompts-library/README.md`。 diff --git a/tools/prompts-library/docs/README.md b/tools/prompts-library/docs/README.md new file mode 100644 index 0000000..d802344 --- /dev/null +++ b/tools/prompts-library/docs/README.md @@ -0,0 +1,15 @@ +# tools/prompts-library/docs + +提示词转换工具的内部文档目录。 + +## 内容边界 + +- 工具使用说明。 +- Excel / Markdown / JSONL 格式约定。 +- 转换流程、字段规范和开发说明。 + +## 维护规则 + +- 本目录服务于 `tools/prompts-library/`，不是主知识库正文。 +- 示例仓库、示例邮箱和占位链接不得冒充真实项目事实。 +- 修改格式规范后同步检查 `main.py` 和 `scripts/`。 diff --git a/tools/prompts-library/docs/开发文档.md b/tools/prompts-library/docs/开发文档.md index ab998c6..4b9aaa1 100644 --- a/tools/prompts-library/docs/开发文档.md +++ b/tools/prompts-library/docs/开发文档.md @@ -1259,9 +1259,9 @@ pytest tests/ ## 联系与支持 -- 📧 邮箱: your-email@example.com -- 🐛 Issues: https://github.com/username/repo/issues -- 💬 讨论: https://github.com/username/repo/discussions +- 📧 邮箱: tukuai.ai@gmail.com +- 🐛 Issues: https://github.com/tukuaiai/vibe-coding-cn/issues +- 💬 讨论: https://github.com/tukuaiai/vibe-coding-cn/discussions --- diff --git a/tools/prompts-library/scripts/AGENTS.md b/tools/prompts-library/scripts/AGENTS.md new file mode 100644 index 0000000..9235606 --- /dev/null +++ b/tools/prompts-library/scripts/AGENTS.md @@ -0,0 +1,9 @@ +# tools/prompts-library/scripts/ Agent 指南 + +本目录维护提示词转换工具脚本。 + +## 约束 + +- 不猜输入格式，先查看 `docs/` 中的格式规范和现有脚本。 +- 变更转换逻辑后至少运行对应脚本的 `--help` 或最小样例。 +- 脚本中不要硬编码用户本地路径和凭证。 diff --git a/tools/prompts-library/scripts/README.md b/tools/prompts-library/scripts/README.md new file mode 100644 index 0000000..24116db --- /dev/null +++ b/tools/prompts-library/scripts/README.md @@ -0,0 +1,17 @@ +# tools/prompts-library/scripts + +提示词转换工具的辅助脚本目录。 + +## 常见脚本 + +- `excel_to_docs.py` - Excel 转 Markdown。 +- `docs_to_excel.py` - Markdown 转 Excel。 +- `md_to_jsonl.py` - Markdown 转 JSONL。 +- `jsonl_to_excel.py` - JSONL 转 Excel。 +- `gemini_jsonl_batch.py` - 使用 Gemini CLI 批处理 Markdown 到 JSONL。 + +## 维护规则 + +- 新增脚本必须有清晰 CLI 参数和 `--help`。 +- 新增依赖必须更新 `requirements.txt`。 +- 不提交生成数据、缓存或临时导出。