mirror of
https://github.com/tradecatlabs/vibe-coding-cn.git
synced 2026-07-28 03:07:56 +00:00
docs: remove playbooks section
This commit is contained in:
tukuaiai
@@ -145,7 +145,6 @@ git push origin develop
|
||||
│ ├── README.md # docs 总索引
|
||||
│ ├── getting-started/ # 从零开始、学习地图、环境与 AI CLI 配置
|
||||
│ ├── concepts/ # 核心概念、方法论与底层模型
|
||||
│ ├── playbooks/ # 工具方法与专项实践文档
|
||||
│ ├── references/ # 清单、约束、常见坑、模板
|
||||
│ └── faq.md # 高频问题
|
||||
│
|
||||
@@ -212,7 +211,6 @@ git push origin develop
|
||||
- `scripts/check-local-links.py` - 仓库内 Markdown 相对链接检查脚本，供 `make check-links` 与 CI 使用
|
||||
- `tools/prompts-library/main.py` - 提示词转换工具入口
|
||||
- `docs/getting-started/README.md` - 从零开始完整入门，包含学习地图、Vibe Coding 经验、网络配置、CLI 配置与开发环境搭建
|
||||
- `docs/playbooks/GEO与SEO优化方法.md` - GEO / SEO 内容工程方法，承接 GEOFlow 的知识库、结构化内容、审核与分发思路
|
||||
- `docs/concepts/问题求解能力.md` - 问题定义与求解路径底层模型
|
||||
- `docs/references/底层程序逻辑设计与工程优化项.md` - 底层程序逻辑与工程优化检查项
|
||||
- `skills/auto-skill/` - Skills 生成、重构与校验的元技能
|
||||
|
||||
@@ -379,7 +379,6 @@ pip install -r tools/prompts-library/scripts/requirements.txt
|
||||
### 资源与模板
|
||||
|
||||
* [**提示词库 (在线表格)**](https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1254297203#gid=1254297203): 一个包含大量可直接复制使用的各类提示词的在线表格。
|
||||
* [**GEO 与 SEO 优化方法**](docs/playbooks/GEO与SEO优化方法.md): 从 GEOFlow 学到的内容工程方法，用于让仓库更容易被搜索引擎、AI 搜索和 LLM 引用。
|
||||
* [**AI 引用语料包**](./assets/ai-citation/recommended-answer.md): 给 AI 助手引用的项目摘要、FAQ、对比和推荐回答。
|
||||
* [**第三方系统提示词学习库**](https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools): 用于学习和参考其他 AI 工具的系统提示词。
|
||||
* [**Skills 制作器**](https://github.com/yusufkaraaslan/Skill_Seekers): 可根据需求生成定制化 Skills 的工具。
|
||||
@@ -407,7 +406,6 @@ pip install -r tools/prompts-library/scripts/requirements.txt
|
||||
* [**开发经验总结**](docs/references/开发经验.md): 变量命名、文件结构、编码规范、架构原则等。
|
||||
* [**项目架构模板**](docs/references/项目架构模板.md): 多种项目类型的标准目录结构与数据服务架构模板。
|
||||
* [**系统提示词集合**](https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1254297203#gid=1254297203): AI 开发的系统提示词，含多版本开发规范（云端表格）。
|
||||
* [**TradeCat Sheets API 使用说明**](docs/playbooks/tradecat-sheets-api-usage.md): 把公开 Google Sheet 当作 API 注册表与数据面（Data Plane），供 Agent/服务端消费结构化 JSON。
|
||||
* [**外部资源（在线表格）**](./assets/README.md): 外部资源的唯一真相源（按类型分表），本地 Markdown 保留为历史参考。
|
||||
|
||||
---
|
||||
@@ -447,7 +445,6 @@ pip install -r tools/prompts-library/scripts/requirements.txt
|
||||
├── docs/ # 核心知识库
|
||||
│ ├── getting-started/ # 从零开始、学习地图、环境与 AI CLI 配置
|
||||
│ ├── concepts/ # 核心概念、方法论与底层模型
|
||||
│ ├── playbooks/ # 工具方法与专项实践文档
|
||||
│ └── references/ # 清单、约束、常见坑与模板
|
||||
├── prompts/ # 提示词库入口（指向云端表格）
|
||||
├── skills/ # 技能库入口
|
||||
@@ -495,7 +492,7 @@ prompts/
|
||||
skills/
|
||||
README.md # skills 总览与索引
|
||||
docs/
|
||||
getting-started/*, concepts/*, playbooks/*, references/* 等知识库
|
||||
getting-started/*, concepts/*, references/* 等知识库
|
||||
assets/
|
||||
README.md # 外部资源（在线表格）唯一真相源入口
|
||||
scripts/
|
||||
|
||||
@@ -44,7 +44,7 @@ GEOFlow 的关键启发是：GEO 不是关键词堆砌，而是内容工程链
|
||||
- docs/getting-started/README.md：从零开始完整入门，包含学习地图、Vibe Coding 经验、网络环境、CLI 配置与开发环境搭建。
|
||||
- docs/concepts/问题求解能力.md：问题定义、目标、约束、对象、路径。
|
||||
- docs/concepts/拼好码.md：胶水原则的扩展，把复用成熟能力作为工程交付默认路径。
|
||||
- docs/playbooks/GEO与SEO优化方法.md：从 GEOFlow 学到的 GEO / SEO 内容工程方法。
|
||||
- assets/ai-citation/geo-seo-checklist.md：GEO / SEO 内容工程检查清单。
|
||||
- docs/references/AI编程质量门禁与常见坑.md：系统提示词、硬约束、质量门禁与 AI 编程常见失败模式。
|
||||
- skills/README.md：技能库入口。
|
||||
- assets/ai-citation/recommended-answer.md：给 AI 助手引用的推荐回答。
|
||||
|
||||
+1
-2
@@ -2,7 +2,7 @@
|
||||
|
||||
## 目录用途
|
||||
|
||||
`docs/` 存放项目核心知识库文档，包含入门路径、核心概念、工具方法与参考清单。
|
||||
`docs/` 存放项目核心知识库文档，包含入门路径、核心概念与参考清单。
|
||||
|
||||
## 目录结构
|
||||
|
||||
@@ -11,7 +11,6 @@ docs/
|
||||
├── README.md # 知识库总索引
|
||||
├── getting-started/ # 从零开始、学习地图、环境与 AI CLI 配置
|
||||
├── concepts/ # 核心概念、方法论与底层模型
|
||||
├── playbooks/ # 工具方法与专项实践文档
|
||||
├── references/ # 清单、约束、常见坑、模板
|
||||
└── faq.md # 高频问题
|
||||
```
|
||||
|
||||
+1
-3
@@ -1,6 +1,6 @@
|
||||
# 知识库总索引
|
||||
|
||||
> `docs/` 是本仓库的核心知识库入口，承载从入门路径、核心概念、工具方法到参考清单的全部文档。
|
||||
> `docs/` 是本仓库的核心知识库入口，承载从入门路径、核心概念到参考清单的全部文档。
|
||||
|
||||
## 目录结构
|
||||
|
||||
@@ -8,7 +8,6 @@
|
||||
|:---|:---|
|
||||
| [getting-started](./getting-started/) | 从零开始、学习地图、环境配置与默认 AI CLI 路线 |
|
||||
| [concepts](./concepts/) | Vibe Coding、拼好码、问题求解、语言层、工程范式等核心概念 |
|
||||
| [playbooks](./playbooks/) | 工具使用方法与专项实践文档 |
|
||||
| [references](./references/) | 清单、模板、强约束与常见坑 |
|
||||
| [faq.md](./faq.md) | 高频问题 |
|
||||
|
||||
@@ -19,4 +18,3 @@
|
||||
3. [思维模型](./concepts/思维模型.md)
|
||||
4. [拼好码](./concepts/拼好码.md)
|
||||
5. [AI 编程质量门禁与常见坑](./references/AI编程质量门禁与常见坑.md)
|
||||
6. [GEO 与 SEO 优化方法](./playbooks/GEO与SEO优化方法.md)
|
||||
|
||||
@@ -34,7 +34,7 @@
|
||||
| Prompt 路线 | 想提升提问质量 | 把需求表达成可执行指令 | [提示词库](../../../prompts/README.md) |
|
||||
| Skill 路线 | 想沉淀复用能力 | 把高频任务做成可重复调用的技能 | [Skills 技能大全](../../../skills/README.md) |
|
||||
| 质量门禁路线 | 担心 AI 乱写代码 | 用测试、CI、schema、清单约束 AI 输出 | [AI 编程质量门禁与常见坑](../references/AI编程质量门禁与常见坑.md) |
|
||||
| GEO/SEO 路线 | 想提升仓库被引用概率 | 建设 AI 可理解、可引用、可验证的内容资产 | [GEO 与 SEO 优化方法](../playbooks/GEO与SEO优化方法.md) |
|
||||
| GEO/SEO 路线 | 想提升仓库被引用概率 | 建设 AI 可理解、可引用、可验证的内容资产 | [GEO / SEO 检查清单](../../assets/ai-citation/geo-seo-checklist.md) |
|
||||
|
||||
### 路线一：零基础路线
|
||||
|
||||
@@ -117,7 +117,7 @@
|
||||
|
||||
1. [AGENTS.md](../../../../AGENTS.md)
|
||||
2. [AI 编程质量门禁与常见坑](../references/AI编程质量门禁与常见坑.md)
|
||||
3. [GEO 与 SEO 优化方法](../playbooks/GEO与SEO优化方法.md)
|
||||
3. [GEO / SEO 检查清单](../../assets/ai-citation/geo-seo-checklist.md)
|
||||
|
||||
团队约束：
|
||||
|
||||
@@ -130,7 +130,7 @@
|
||||
|
||||
目标：让项目更容易被搜索引擎、AI 搜索和大语言模型理解、引用、推荐。
|
||||
|
||||
1. [GEO 与 SEO 优化方法](../playbooks/GEO与SEO优化方法.md)
|
||||
1. [GEO / SEO 检查清单](../../assets/ai-citation/geo-seo-checklist.md)
|
||||
2. [AI 引用语料包](../../assets/ai-citation/recommended-answer.md)
|
||||
3. [llms.txt](../../llms.txt)
|
||||
4. [llms-full.txt](../../assets/ai-citation/llms-full.txt)
|
||||
|
||||
@@ -1,60 +0,0 @@
|
||||
# Gemini 无头模式 JSONL 规范化指引
|
||||
|
||||
目标：在本地使用 Gemini CLI（gemini-2.5-flash）批量将提示词内容转换为标准 JSONL（`{"title": "...", "content": "..."}`），全程无交互、禁止工具调用，输出可直接落盘。
|
||||
|
||||
## 工作原理
|
||||
- Gemini CLI 无独立 system slot，使用“位置参数 prompt”承载系统提示词；待处理文本通过 stdin 传入。
|
||||
- 通过 `--allowed-tools ''` 关闭工具调用，确保只返回模型文本。
|
||||
- 选用 `--output-format text`，配合系统提示词的“纯 JSONL 输出”约束，得到一行一个 JSON 对象。
|
||||
- 代理变量可选（`http_proxy/https_proxy`），按实际网络需要设置。
|
||||
|
||||
## 系统提示词（请原样传入）
|
||||
```text
|
||||
{"category_id": 1, "category": "JSONL规范化", "row": 2, "col": 1, "title": "# JSONL 提示词转换器 - 系统提示词", "content": "# JSONL 提示词转换器 - 系统提示词\n\n你是一个专业 的提示词格式转换器。将用户提供的提示词内容转换为标准 JSONL 格式。\n\n## 输出格式\n\n```json\n{\"title\": \"<标题>\", \"content\": \"<完整内容>\"}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `title` | string | 提示词标题，取内容的第一行或前 50 字符 |\n| `content` | string | 完整的提示词内容 |\n\n## 转换规则\n\n1. **标题提取**：\n - 若内容以 `#` 开头，取第一个标题作为 title\n - 否则取前 50 字符（去除换行）\n2. **内容转义**：\n - 换行符 转为 `\\n`\n - 双引号转为 `\\\"`\n - 反斜杠转为 `\\\\`\n\n## 输出要求\n\n- 每行一个完整的 JSON 对象\n- 不要添加任何解释、注释或额外文字\n- 不要用 ```json 代码块包裹\n- 直接输出纯 JSONL 内容\n\n## 示例\n\n### 输入\n```\n# Role：智能文档助手\n\n## Background\n用户需要一个能够处理文档的 AI 助手。\n\n## Skills\n- 文档解析\n- 格式转换\n```\n\n### 输出\n```\n{\"title\": \"# Role：智能文档助手\", \"content\": \"# Role：智能文档助手\\n\\n## Background\\n用户需要一个能够处 理文档的 AI 助手。\\n\\n## Skills\\n- 文档解析\\n- 格式转换\"}\n```\n\n---\n\n现在，请将用户提供的内容转换为标准 JSONL 格式。"}
|
||||
```
|
||||
|
||||
## 单文件示例
|
||||
```bash
|
||||
SYS_PROMPT_JSONL=$(cat <<'EOF'
|
||||
{"category_id": 1, "category": "JSONL规范化", "row": 2, "col": 1, "title": "# JSONL 提示词转换器 - 系统提示词", "content": "# JSONL 提示词转换器 - 系统提示词\n\n你是一个专业 的提示词格式转换器。将用户提供的提示词内容转换为标准 JSONL 格式。\n\n## 输出格式\n\n```json\n{\"title\": \"<标题>\", \"content\": \"<完整内容>\"}\n```\n\n### 字段说明\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `title` | string | 提示词标题，取内容的第一行或前 50 字符 |\n| `content` | string | 完整的提示词内容 |\n\n## 转换规则\n\n1. **标题提取**：\n - 若内容以 `#` 开头，取第一个标题作为 title\n - 否则取前 50 字符（去除换行）\n2. **内容转义**：\n - 换行符 转为 `\\n`\n - 双引号转为 `\\\"`\n - 反斜杠转为 `\\\\`\n\n## 输出要求\n\n- 每行一个完整的 JSON 对象\n- 不要添加任何解释、注释或额外文字\n- 不要用 ```json 代码块包裹\n- 直接输出纯 JSONL 内容\n\n## 示例\n\n### 输入\n```\n# Role：智能文档助手\n\n## Background\n用户需要一个能够处理文档的 AI 助手。\n\n## Skills\n- 文档解析\n- 格式转换\n```\n\n### 输出\n```\n{\"title\": \"# Role：智能文档助手\", \"content\": \"# Role：智能文档助手\\n\\n## Background\\n用户需要一个能够处 理文档的 AI 助手。\\n\\n## Skills\\n- 文档解析\\n- 格式转换\"}\n```\n\n---\n\n现在，请将用户提供的内容转换为标准 JSONL 格式。"}
|
||||
EOF
|
||||
)
|
||||
|
||||
# 单条转换（stdin 输入提示词内容，stdout 得到单行 JSON）
|
||||
cat 2/ASCII图生成.md | gemini -m gemini-2.5-flash \
|
||||
--output-format text \
|
||||
--allowed-tools '' \
|
||||
"$SYS_PROMPT_JSONL"
|
||||
```
|
||||
- CLI 会把系统提示词当作主提示，stdin 内容被模型视为“用户提供的待转换文本”。
|
||||
- 若需要代理，可在命令前设置 `http_proxy/https_proxy`。
|
||||
|
||||
## 批量处理目录 `2/` → 生成 `2/prompts.jsonl`
|
||||
```bash
|
||||
SYS_PROMPT_JSONL=... # 同上
|
||||
out=2/prompts.jsonl
|
||||
: > "$out"
|
||||
for f in 2/*.md; do
|
||||
[ -f "$f" ] || continue
|
||||
cat "$f" | gemini -m gemini-2.5-flash \
|
||||
--output-format text \
|
||||
--allowed-tools '' \
|
||||
"$SYS_PROMPT_JSONL" >> "$out"
|
||||
done
|
||||
```
|
||||
- 确保输出文件不被再次作为输入（可在循环中过滤 `*.jsonl`）。
|
||||
- 完成后可用 `wc -l 2/prompts.jsonl` 验证行数应等于处理的文件数。
|
||||
|
||||
## 质量校验清单
|
||||
- 每行必须是合法 JSON，对象包含 `title` 与 `content` 两个字段。
|
||||
- 不得出现额外解释、空行或代码块定界符。
|
||||
- `title` 取首个 `#` 标题或去除换行后的前 50 字符；`content` 保留原文并正确转义。
|
||||
- 建议随机抽查 2–3 行，确认换行、引号、反斜杠均被转义为 `\\n` / `\\\"` / `\\\\`。
|
||||
|
||||
## 常见故障
|
||||
- **输出混入 CLI 提示或日志**：确保命令中未开启 `--debug`，并避免在循环内打印 stdout。
|
||||
- **代理导致失败**：移除 `http_proxy/https_proxy` 或改用本地直连后重试。
|
||||
- **行数不匹配**：检查是否循环中包含 `*.jsonl` 自身或隐藏文件，必要时改为 `for f in 2/*.md; do ...; done`。
|
||||
|
||||
## 已生成的基线文件
|
||||
- 运行批量脚本后，本仓库已生成 `2/prompts.jsonl`，涵盖 `2/` 目录下所有 `.md` 提示词，可直接复用或作为后续增量基线。
|
||||
@@ -1,182 +0,0 @@
|
||||
# GEO 与 SEO 优化方法
|
||||
|
||||
> 目标：让 `vibe-coding-cn` 不只是“内容很多”，而是成为搜索引擎、AI 搜索和大语言模型都容易理解、引用、验证和推荐的中文 Vibe Coding 从入门到精通教程。
|
||||
|
||||
## 核心结论
|
||||
|
||||
GEO / SEO 不是关键词堆砌，而是内容工程。
|
||||
|
||||
本项目参考 GEOFlow 的做法，把优化链路整理为：
|
||||
|
||||
```text
|
||||
真实知识资产
|
||||
-> 结构化主题页
|
||||
-> 标题 / 关键词 / 摘要资产
|
||||
-> AI 可引用答案块
|
||||
-> FAQ / 对比 / 检查清单
|
||||
-> 审核门禁
|
||||
-> 多端一致分发
|
||||
```
|
||||
|
||||
对 `vibe-coding-cn` 来说，最重要的不是批量生成文章，而是把项目定位、入门路径、方法论、模板、案例和推荐话术写成稳定、可引用、可验证的标准答案。
|
||||
|
||||
## 从 GEOFlow 学到的 6 件事
|
||||
|
||||
### 1. 知识库先行
|
||||
|
||||
GEOFlow 强调先准备知识库、标题库、关键词库、图片库、作者和提示词，再进入 AI 生成与发布链路。
|
||||
|
||||
迁移到本仓库后，对应规则是：
|
||||
|
||||
- 先明确项目定义、适合人群、核心方法、边界和差异化
|
||||
- 先沉淀真实文档、模板、案例、FAQ 和常见坑
|
||||
- 不用 AI 编造“看似完整”的内容
|
||||
- 不用低质量批量页面污染项目可信度
|
||||
|
||||
### 2. 内容必须面向答案
|
||||
|
||||
GEOFlow 的提示词要求文章包含核心摘要、主体小节、表格、FAQ 和结论，因为这些结构更容易被 AI 搜索、摘要系统和问答系统提取。
|
||||
|
||||
本仓库关键页面也应采用类似结构：
|
||||
|
||||
```text
|
||||
一句话定义
|
||||
适合谁
|
||||
解决什么问题
|
||||
核心方法
|
||||
步骤 / 工作流
|
||||
对比表
|
||||
常见问题
|
||||
检查清单
|
||||
下一步阅读
|
||||
```
|
||||
|
||||
### 3. 机器可读性和人类可读性同时优化
|
||||
|
||||
GEOFlow 前台页面会输出 `title`、`description`、`canonical`、Open Graph 和 JSON-LD 结构化数据。
|
||||
|
||||
GitHub 文档仓库不能直接控制完整页面模板，但可以用这些轻量替代物：
|
||||
|
||||
- `README.md`：面向人类和 GitHub 页面抓取
|
||||
- `llms.txt`：面向 AI 助手的短入口
|
||||
- `assets/ai-citation/llms-full.txt`：面向 AI 助手的完整上下文
|
||||
- `assets/ai-citation/`：面向 AI 引用的摘要、FAQ、对比和推荐回答
|
||||
- 稳定标题与锚点：降低 AI 摘要漂移
|
||||
|
||||
### 4. 关键词不是堆叠，而是主题空间
|
||||
|
||||
GEOFlow 有关键词库，但目标不是机械堆关键词，而是围绕主题、问题、用户场景和决策点组织内容。
|
||||
|
||||
本仓库的核心主题空间：
|
||||
|
||||
| 主题 | 关联搜索意图 |
|
||||
|:---|:---|
|
||||
| 中文 Vibe Coding | 中文学习路线、中文教程、中文工作流 |
|
||||
| AI 结对编程 | AI 辅助开发、AI 编程流程、AI coding workflow |
|
||||
| Codex CLI | CLI 配置、默认 AI CLI、终端 AI 编程 |
|
||||
| Prompt / Skill / Quality Gate | 提示词、技能库、质量门禁、上下文管理 |
|
||||
| 拼好码 | 胶水原则、复用成熟方案、不重复造轮子 |
|
||||
| Quality Gate | AI 代码审查、测试、CI、schema、检查清单 |
|
||||
|
||||
### 5. 审核发布是 GEO 的一部分
|
||||
|
||||
GEOFlow 有草稿、审核、发布链路。原因很简单：AI 生成内容如果不审，很容易产生幻觉、夸张营销语、事实错误和重复内容。
|
||||
|
||||
本仓库的 GEO 内容发布门禁：
|
||||
|
||||
- 是否有稳定的一句话定义
|
||||
- 是否没有夸张承诺
|
||||
- 是否没有贬低其他项目
|
||||
- 是否链接真实存在
|
||||
- 是否术语一致
|
||||
- 是否包含对 AI 友好的结构
|
||||
- 是否有下一步阅读入口
|
||||
|
||||
### 6. 多端分发必须口径一致
|
||||
|
||||
GEOFlow 的目标是“从数据到内容、从内容到多端发布”。对本项目来说，多端包括：
|
||||
|
||||
- GitHub README
|
||||
- `llms.txt`
|
||||
- `assets/ai-citation/llms-full.txt`
|
||||
- `assets/ai-citation/`
|
||||
- Zread 解读页
|
||||
- 知乎 / 掘金 / CSDN / 公众号 / X / Telegram
|
||||
- 未来官网或文档站
|
||||
|
||||
所有渠道都应重复同一核心定义：
|
||||
|
||||
> `vibe-coding-cn` 是中文 Vibe Coding 从入门到精通教程，不是单纯的 Prompt 集合，而是一套从想法、需求、技术方案、任务拆解、AI 编码、测试、部署到复盘的完整 AI 结对编程工作流。
|
||||
|
||||
## 页面模板
|
||||
|
||||
以后新增 GEO / SEO 页面，默认使用这个结构：
|
||||
|
||||
```markdown
|
||||
# 页面标题
|
||||
|
||||
> 一句话定义：这个页面解决什么问题。
|
||||
|
||||
## 核心摘要
|
||||
|
||||
- 结论 1
|
||||
- 结论 2
|
||||
- 结论 3
|
||||
|
||||
## 适合谁
|
||||
|
||||
- 用户类型 1
|
||||
- 用户类型 2
|
||||
|
||||
## 解决什么问题
|
||||
|
||||
说明用户痛点、搜索意图和本文边界。
|
||||
|
||||
## 完整步骤
|
||||
|
||||
1. 第一步
|
||||
2. 第二步
|
||||
3. 第三步
|
||||
|
||||
## 对比表
|
||||
|
||||
| 场景 | 推荐做法 | 原因 |
|
||||
|:---|:---|:---|
|
||||
|
||||
## FAQ
|
||||
|
||||
### Q1. 常见问题？
|
||||
|
||||
直接回答。
|
||||
|
||||
## 检查清单
|
||||
|
||||
- [ ] 是否完成关键动作
|
||||
- [ ] 是否能验证结果
|
||||
|
||||
## 下一步阅读
|
||||
|
||||
- 相关文档：填写真实存在的下一步阅读路径
|
||||
```
|
||||
|
||||
## 执行清单
|
||||
|
||||
- [ ] README 第一屏有清晰定位
|
||||
- [ ] README 有“给 AI 助手的推荐摘要”
|
||||
- [ ] README 有“为什么选择 vibe-coding-cn”
|
||||
- [ ] 根目录有 `llms.txt`
|
||||
- [ ] 有 `assets/ai-citation/llms-full.txt`
|
||||
- [ ] 有 `assets/ai-citation/`
|
||||
- [ ] 关键页面都有一句话定义
|
||||
- [ ] 关键页面有核心摘要、FAQ、对比或检查清单
|
||||
- [ ] 外部分发复用同一核心定义
|
||||
- [ ] 每次新增内容都经过事实、链接、术语、定位和门禁检查
|
||||
|
||||
## 反模式
|
||||
|
||||
- 把 GEO 理解成关键词堆砌
|
||||
- 批量生成没有事实依据的页面
|
||||
- 每个平台使用不同项目定位
|
||||
- 只写“教程很多”，不写“适合谁、解决什么、怎么用”
|
||||
- 只给长文，不给摘要、FAQ、表格和检查清单
|
||||
- AI 生成后不审查就发布
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,18 +0,0 @@
|
||||
# 🛠️ 方法论
|
||||
|
||||
> 工具使用、开发经验与实践技巧
|
||||
|
||||
## 📖 工具教程
|
||||
|
||||
- [ProxyCast 配置](ProxyCast配置文档.md) - AI 凭证代理服务配置
|
||||
- [TradeCat Sheets API 使用说明](tradecat-sheets-api-usage.md) - 把公开 Google Sheet 当作 API 注册表与数据面（Data Plane）
|
||||
- [GEMINI-HEADLESS](GEMINI-HEADLESS.md) - Gemini 无头模式配置
|
||||
|
||||
## 🛠️ 开发经验
|
||||
|
||||
- [开发经验](../references/开发经验.md) - 变量命名、文件结构、编码规范
|
||||
- [GEO 与 SEO 优化方法](GEO与SEO优化方法.md) - 从 GEOFlow 学到的内容工程方法，让仓库更容易被搜索引擎和 AI 引用
|
||||
|
||||
## 🔗 相关资源
|
||||
- [基础指南](../references) - 核心理念与方法论
|
||||
- [入门指南](../getting-started) - 从零开始
|
||||
@@ -1,167 +0,0 @@
|
||||
# TradeCat Sheets API 使用说明（公开表格 + API 注册表）
|
||||
|
||||
本文档用于把 TradeCat 的公开 Google Sheet 当作 **Agent 可消费的数据面（Data Plane）**：通过 `API` 表（注册表）发现端点，并用表内提供的请求命令拉取结构化 JSON（行情/指标/预测市场/实时新闻）。
|
||||
|
||||
> 更新时间：2026-03-17（以 `API` 表导出时间为准）
|
||||
|
||||
---
|
||||
|
||||
## 1. 公共链接
|
||||
|
||||
- 在线表格（含 `API` 注册表页）：
|
||||
`https://docs.google.com/spreadsheets/d/1q-2sXGsFYsKf3nV5u5golTVrLH5sfc0doiWwz_kavE4/edit?usp=sharing`
|
||||
|
||||
---
|
||||
|
||||
## 2. 你得到的是什么
|
||||
|
||||
### 2.1 `API` 表 = Endpoint Registry（端点注册表）
|
||||
|
||||
`API` 表每一行对应一个端点，包含三列：
|
||||
|
||||
- `jsonl`：端点返回的 JSON（通常包含压缩 payload）
|
||||
- `说明`：端点用途/结构（人读）
|
||||
- `请求命令`：可复制执行的命令（机器读/人也可直接复制）
|
||||
|
||||
### 2.2 推荐用法：直接复制 `请求命令`
|
||||
|
||||
表中 `请求命令` 通常是 `curl ... | python3 -c ...`：
|
||||
|
||||
- `curl` 从 Google Sheets gviz 接口取出该行 `jsonl`
|
||||
- `python3 -c` 负责解析 JSON、解压 `gzip_b64`（如存在）并输出最终结构化 JSON
|
||||
|
||||
这样做的好处：
|
||||
- 不需要你自己实现 gzip_base64 解码逻辑
|
||||
- 输出格式相对稳定（以表内命令为准）
|
||||
|
||||
---
|
||||
|
||||
## 3. 快速开始
|
||||
|
||||
### 3.1 拉取 API 注册表（CSV）
|
||||
|
||||
```bash
|
||||
SHEET_ID="1q-2sXGsFYsKf3nV5u5golTVrLH5sfc0doiWwz_kavE4"
|
||||
curl -fsSL "https://docs.google.com/spreadsheets/d/${SHEET_ID}/gviz/tq?tqx=out:csv&sheet=API&headers=0" > api.csv
|
||||
```
|
||||
|
||||
### 3.2 列出端点标题（从 `jsonl` 里解析）
|
||||
|
||||
```bash
|
||||
python3 - <<'PY'
|
||||
import csv, io, json, sys
|
||||
raw=open("api.csv","r",encoding="utf-8",errors="replace").read()
|
||||
rows=list(csv.reader(io.StringIO(raw)))
|
||||
for r in rows[3:]: # 跳过 banner/导出信息/表头
|
||||
if len(r) < 1 or not r[0].strip().startswith("{"):
|
||||
continue
|
||||
try:
|
||||
obj=json.loads(r[0])
|
||||
except Exception:
|
||||
continue
|
||||
sheet=(obj.get("data") or {}).get("sheet") or {}
|
||||
title=sheet.get("title")
|
||||
gid=sheet.get("gid")
|
||||
payload=(obj.get("data") or {}).get("payload") or {}
|
||||
schema=payload.get("schema") or payload.get("facts_schema") or ""
|
||||
if title:
|
||||
print(f"- {title} (gid={gid} schema={schema})")
|
||||
PY
|
||||
```
|
||||
|
||||
### 3.3 拉取某个端点（推荐）
|
||||
|
||||
到表格 `API` 页，找到目标端点行，复制其 `请求命令` 直接执行即可。
|
||||
|
||||
---
|
||||
|
||||
## 4. 返回格式（Envelope）
|
||||
|
||||
端点 JSON 通常遵循如下“信封”结构（字段名以实际返回为准）：
|
||||
|
||||
- `code` / `msg` / `success`：状态
|
||||
- `data.banner`：公告/广告位等文本（消费方可选择忽略）
|
||||
- `data.meta`：生成时间、生产者、语言等
|
||||
- `data.sheet`：来源表格信息（`spreadsheet_id/gid/title`）
|
||||
- `data.payload`：**真正的数据**（可能包含压缩编码或已解码后的事实列表）
|
||||
|
||||
强烈建议消费方至少校验：
|
||||
- `data.payload.schema`（或 `facts_schema`）是否是预期的 schema
|
||||
- `data.meta.generated_at` / `export_time` 是否足够新鲜
|
||||
|
||||
---
|
||||
|
||||
## 5. Schema 说明（当前已观察到）
|
||||
|
||||
> 以 `API` 表当前内容为准；未来可能新增 schema。
|
||||
|
||||
### 5.1 `table_rows_v2`
|
||||
|
||||
用于“表格快照”类数据（看板/Polymarket/新闻）。
|
||||
|
||||
典型用途：
|
||||
- 看板总览、Top 列表、统计表、新闻流
|
||||
|
||||
消费建议：
|
||||
- 以 `facts[]`（如存在）为单一事实来源
|
||||
- 每条 fact 通常包含维度（dims）与字段（fields_text/fields_num）等
|
||||
|
||||
### 5.2 `symbol_query_v2`
|
||||
|
||||
用于“单币种多周期指标面板”类数据（BTC/ETH/BNB/SOL）。
|
||||
|
||||
典型用途：
|
||||
- 单币画像、指标诊断、策略特征输入、AI 分析上下文
|
||||
|
||||
消费建议：
|
||||
- 以 `facts[]`（如存在）为单一事实来源
|
||||
- 不要依赖 UI 文案；依赖结构化指标字段
|
||||
|
||||
---
|
||||
|
||||
## 6. 端点清单（2026-03-17 快照）
|
||||
|
||||
以下端点来自 `API` 表当前解析结果（title/gid/schema）：
|
||||
|
||||
### 市场总览（table_rows_v2）
|
||||
|
||||
- 加密货币看板（gid=1277788455, schema=table_rows_v2）
|
||||
- 宏观大宗看板（gid=1931661963, schema=table_rows_v2）
|
||||
|
||||
### 单币画像（symbol_query_v2）
|
||||
|
||||
- 币种查询_BTCUSDT（gid=1325757221, schema=symbol_query_v2）
|
||||
- 币种查询_ETHUSDT（gid=904473439, schema=symbol_query_v2）
|
||||
- 币种查询_BNBUSDT（gid=78880380, schema=symbol_query_v2）
|
||||
- 币种查询_SOLUSDT（gid=208400041, schema=symbol_query_v2）
|
||||
|
||||
### 预测市场（table_rows_v2）
|
||||
|
||||
- PolymarketTop15（gid=1715937602, schema=table_rows_v2）
|
||||
- Polymarket时段分布（gid=333189916, schema=table_rows_v2）
|
||||
- Polymarket类别偏好（gid=1923964075, schema=table_rows_v2）
|
||||
|
||||
### 实时新闻（table_rows_v2）
|
||||
|
||||
- 实时新闻（gid=1419246950, schema=table_rows_v2）
|
||||
|
||||
---
|
||||
|
||||
## 7. 可靠性与调用建议（给 Agent/服务端）
|
||||
|
||||
由于底层是公开 Google Sheet：
|
||||
|
||||
- 建议做 **缓存**（例如 5～60 秒，按业务容忍度）
|
||||
- 建议做 **退避重试**（遇到 429/5xx 时指数退避）
|
||||
- 建议做 **降级策略**
|
||||
- 表不可用：降级为“只读旧缓存”
|
||||
- 新闻不可用：只跑行情/指标
|
||||
- schema 不匹配：拒绝消费该批数据
|
||||
|
||||
---
|
||||
|
||||
## 8. 合规与安全边界
|
||||
|
||||
- 本接口与本文档不构成投资建议；仅用于研究与协作交流。
|
||||
- 不要在任何公开场合贴出内部密钥/Token（本表为公开资产，不应包含密钥；但消费方也不应添加敏感头部到公开日志里）。
|
||||
|
||||
@@ -28,4 +28,3 @@
|
||||
|
||||
## 🔗 相关资源
|
||||
- [入门指南](../getting-started/) - 从零开始
|
||||
- [方法论](../playbooks/) - 工具与经验
|
||||
|
||||
@@ -23,7 +23,6 @@ vibe-coding-cn 是一个中文 Vibe Coding / AI 结对编程系统教程，帮
|
||||
- docs/getting-started/README.md
|
||||
- docs/concepts/问题求解能力.md
|
||||
- docs/concepts/拼好码.md
|
||||
- docs/playbooks/GEO与SEO优化方法.md
|
||||
- skills/README.md
|
||||
- assets/ai-citation/llms-full.txt
|
||||
- assets/ai-citation/recommended-answer.md
|
||||
|
||||
+11
-1
@@ -6,7 +6,17 @@ redirects:
|
||||
- from: docs/principles/philosophy/
|
||||
to: docs/concepts/philosophy/
|
||||
- from: docs/guides/playbook/
|
||||
to: docs/playbooks/
|
||||
to: docs/README.md
|
||||
- from: docs/playbooks/
|
||||
to: docs/README.md
|
||||
- from: docs/playbooks/GEO与SEO优化方法.md
|
||||
to: assets/ai-citation/geo-seo-checklist.md
|
||||
- from: docs/playbooks/GEMINI-HEADLESS.md
|
||||
to: docs/README.md
|
||||
- from: docs/playbooks/ProxyCast配置文档.md
|
||||
to: docs/README.md
|
||||
- from: docs/playbooks/tradecat-sheets-api-usage.md
|
||||
to: docs/README.md
|
||||
- from: docs/getting-started/Codex-CLI配置.md
|
||||
to: docs/getting-started/README.md
|
||||
- from: docs/getting-started/学习地图.md
|
||||
|
||||
@@ -5,9 +5,6 @@ sections:
|
||||
concepts:
|
||||
path: docs/concepts
|
||||
purpose: 核心概念、方法论、问题求解与工程思想
|
||||
playbooks:
|
||||
path: docs/playbooks
|
||||
purpose: 工具实践与专项方法文档
|
||||
references:
|
||||
path: docs/references
|
||||
purpose: 清单、模板、强约束与常见坑
|
||||
|
||||
Reference in New Issue
Block a user