From db0f3de851839ffae2d2d73fb15ad16d816c54a4 Mon Sep 17 00:00:00 2001 From: tukuaiai Date: Sat, 2 May 2026 23:30:50 +0800 Subject: [PATCH] docs: remove playbooks section --- AGENTS.md | 2 - README.md | 5 +- assets/ai-citation/llms-full.txt | 2 +- docs/AGENTS.md | 3 +- docs/README.md | 4 +- docs/getting-started/README.md | 6 +- docs/playbooks/GEMINI-HEADLESS.md | 60 - docs/playbooks/GEO与SEO优化方法.md | 182 --- docs/playbooks/ProxyCast配置文档.md | 1128 ------------------- docs/playbooks/README.md | 18 - docs/playbooks/tradecat-sheets-api-usage.md | 167 --- docs/references/README.md | 1 - llms.txt | 1 - metadata/redirects.yml | 12 +- metadata/taxonomy.yml | 3 - 15 files changed, 18 insertions(+), 1576 deletions(-) delete mode 100644 docs/playbooks/GEMINI-HEADLESS.md delete mode 100644 docs/playbooks/GEO与SEO优化方法.md delete mode 100644 docs/playbooks/ProxyCast配置文档.md delete mode 100644 docs/playbooks/README.md delete mode 100644 docs/playbooks/tradecat-sheets-api-usage.md diff --git a/AGENTS.md b/AGENTS.md index f67f313..060d697 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 生成、重构与校验的元技能 diff --git a/README.md b/README.md index c389ce7..bf57fdb 100644 --- a/README.md +++ b/README.md @@ -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/ diff --git a/assets/ai-citation/llms-full.txt b/assets/ai-citation/llms-full.txt index 4d01c61..67343cb 100644 --- a/assets/ai-citation/llms-full.txt +++ b/assets/ai-citation/llms-full.txt @@ -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 助手引用的推荐回答。 diff --git a/docs/AGENTS.md b/docs/AGENTS.md index f1190bf..248fe49 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -2,7 +2,7 @@ ## 目录用途 -`docs/` 存放项目核心知识库文档，包含入门路径、核心概念、工具方法与参考清单。 +`docs/` 存放项目核心知识库文档，包含入门路径、核心概念与参考清单。 ## 目录结构 @@ -11,7 +11,6 @@ docs/ ├── README.md # 知识库总索引 ├── getting-started/ # 从零开始、学习地图、环境与 AI CLI 配置 ├── concepts/ # 核心概念、方法论与底层模型 -├── playbooks/ # 工具方法与专项实践文档 ├── references/ # 清单、约束、常见坑、模板 └── faq.md # 高频问题 ``` diff --git a/docs/README.md b/docs/README.md index 5b251a9..dc131b8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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) diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index 3817cc9..70e1b82 100644 --- a/docs/getting-started/README.md +++ b/docs/getting-started/README.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) diff --git a/docs/playbooks/GEMINI-HEADLESS.md b/docs/playbooks/GEMINI-HEADLESS.md deleted file mode 100644 index b966875..0000000 --- a/docs/playbooks/GEMINI-HEADLESS.md +++ /dev/null @@ -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` 提示词，可直接复用或作为后续增量基线。 diff --git a/docs/playbooks/GEO与SEO优化方法.md b/docs/playbooks/GEO与SEO优化方法.md deleted file mode 100644 index 2467e96..0000000 --- a/docs/playbooks/GEO与SEO优化方法.md +++ /dev/null @@ -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 生成后不审查就发布 diff --git a/docs/playbooks/ProxyCast配置文档.md b/docs/playbooks/ProxyCast配置文档.md deleted file mode 100644 index 4554e4e..0000000 --- a/docs/playbooks/ProxyCast配置文档.md +++ /dev/null @@ -1,1128 +0,0 @@ -# ProxyCast 完整配置文档 - -## 系统原理 - -``` -你的 AI 凭证 ProxyCast 任意 AI 工具 -┌─────────────────┐ ┌─────────────┐ ┌─────────────────────┐ -│ Kiro OAuth │ │ │ │ Claude Code │ -│ Gemini API Keys │ ───▶ │ 本地 API │ ───▶ │ Cherry Studio │ -│ Qwen OAuth │ │ 代理服务 │ │ Cursor / Cline │ -│ OpenRouter │ │ :8999 │ │ 你的 AI Agent │ -└─────────────────┘ └─────────────┘ └─────────────────────┘ -``` - -ProxyCast 把你已有的 AI 凭证转换成标准 OpenAI/Anthropic API，让任何支持这些接口的工具都能用。 - ---- - -## 一、启动 ProxyCast - -```bash -cd /mnt/d/.projects/kiro-account-manager-main.zip/proxycast-main && ./src-tauri/target/release/proxycast & -``` - -服务监听：`http://127.0.0.1:8999` - ---- - -## 二、Claude Code 启动命令 - -### Claude Opus 4.7 (Kiro 凭证，最强) -```bash -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model claude-opus-4-7 -``` - -### Claude Sonnet 4.5 (Kiro 凭证) -```bash -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model claude-sonnet-4-5 -``` - -### DeepSeek R1 (OpenRouter 免费，推理最强) -```bash -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model deepseek/deepseek-r1-0528:free -``` - -### Gemini 2.0 Flash (OpenRouter 免费) -```bash -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model google/gemini-2.0-flash-exp:free -``` - -### Llama 3.1 405B (OpenRouter 免费，综合最强) -```bash -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model meta-llama/llama-3.1-405b-instruct:free -``` - -### Devstral 2 (OpenRouter 免费，代码专精) -```bash -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model mistralai/devstral-2512:free -``` - -### Gemini 3.1 Pro Preview - 最新预览版 -```bash -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model gemini-3.1-pro-preview -``` - -### Gemini 2.5 Pro - Pro 版本 -```bash -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model gemini-2.5-pro -``` - -### Gemini 2.5 Pro Preview -```bash -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model gemini-2.5-pro-preview-06-05 -``` - -### Gemini 2.5 Flash - 快速版本 -```bash -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model gemini-2.5-flash -``` - -### Gemini 2.5 Flash Lite - 轻量版本 -```bash -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model gemini-2.5-flash-lite -``` - ---- - -## 三、API 直接调用 - -### 通用配置 -``` -API Base URL: http://127.0.0.1:8999/v1 -API Key: proxy_cast -``` - -### cURL 示例 -```bash -curl http://127.0.0.1:8999/v1/chat/completions \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer proxy_cast" \ - -d '{ - "model": "claude-opus-4-5", - "messages": [{"role": "user", "content": "Hello"}] - }' -``` - -### 获取可用模型列表 -```bash -curl http://127.0.0.1:8999/v1/models -H "Authorization: Bearer proxy_cast" -``` - ---- - -## 四、可用模型列表 - -### Kiro 凭证 (Claude) -| 模型 | 说明 | -|------|------| -| `claude-opus-4-5` | 最强模型 | -| `claude-sonnet-4-5` | 平衡性能 | -| `claude-sonnet-4-5-20250929` | Sonnet 特定版本 | -| `claude-3-7-sonnet-20250219` | Claude 3.7 | -| `claude-3-5-sonnet-latest` | Claude 3.5 | - -### Gemini API Keys (8个轮询负载均衡) -| 模型 | 说明 | -|------|------| -| `gemini-3-pro-preview` | 最新预览版 | -| `gemini-2.5-pro` | Pro 版本 | -| `gemini-2.5-flash` | 快速版本 | -| `gemini-2.5-flash-lite` | 轻量版本 | - -### Qwen OAuth -| 模型 | 说明 | -|------|------| -| `qwen3-coder-plus` | 代码增强版 | -| `qwen3-coder-flash` | 快速版本 | - -### OpenRouter 免费模型 -| 模型 | 说明 | -|------|------| -| `deepseek/deepseek-r1-0528:free` | 推理最强 | -| `google/gemini-2.0-flash-exp:free` | 翻译首选 | -| `meta-llama/llama-3.1-405b-instruct:free` | 综合最强 | -| `meta-llama/llama-3.3-70b-instruct:free` | 速度快 | -| `mistralai/devstral-2512:free` | 代码专精 123B | -| `nousresearch/hermes-3-llama-3.1-405b:free` | 指令遵循好 | -| `openai/gpt-oss-120b:free` | GPT 开源 120B | -| `openai/gpt-oss-20b:free` | GPT 开源 20B | -| `moonshotai/kimi-k2:free` | Kimi K2.5 月之暗面 | -| `z-ai/glm-4.5-air:free` | 中文原生 | -| `alibaba/tongyi-deepresearch-30b-a3b:free` | 中文研究 | -| `kwaipilot/kat-coder-pro:free` | 代码 Agent | -| `qwen/qwen-2.5-vl-7b-instruct:free` | 视觉理解 | -| `allenai/olmo-3.1-32b-think:free` | 深度推理 | - ---- - -## 五、凭证配置详情 - -### 凭证文件位置 -| Provider | 路径 | -|----------|------| -| Kiro | `~/.aws/sso/cache/kiro-auth-token.json` | -| Gemini | `~/.gemini/oauth_creds.json` | -| Qwen | `~/.qwen/oauth_creds.json` | -| Codex | `~/.codex/auth.json` | - -### ProxyCast 数据目录 -- 配置文件：`~/.config/proxycast/config.json` -- 数据库：`~/.proxycast/proxycast.db` -- 凭证副本：`~/.local/share/proxycast/credentials/` - -### 当前凭证池 -``` -kiro - Kiro OAuth (Claude) -qwen - Qwen OAuth -gemini_api_key - Gemini Key 1-8 (8个轮询) -openai - OpenRouter Free -``` - ---- - -## 六、刷新 Kiro Token - -Kiro Token 过期后，使用以下命令刷新： - -```bash -REFRESH_TOKEN=$(cat ~/.aws/sso/cache/kiro-auth-token.json | jq -r '.refreshToken') - -curl -s -X POST "https://prod.us-east-1.auth.desktop.kiro.dev/refreshToken" \ - -H "Content-Type: application/json" \ - -d "{\"refreshToken\": \"$REFRESH_TOKEN\"}" | jq '.' > /tmp/new_token.json - -# 更新 token 文件 -cat ~/.aws/sso/cache/kiro-auth-token.json | jq --slurpfile new /tmp/new_token.json ' - .accessToken = $new[0].accessToken | - .expiresAt = (now + 3600 | todate) -' > ~/.aws/sso/cache/kiro-auth-token.json.tmp - -mv ~/.aws/sso/cache/kiro-auth-token.json.tmp ~/.aws/sso/cache/kiro-auth-token.json -``` - -或者直接在 ProxyCast 界面点"刷新 Token"按钮。 - ---- - -## 七、配置文件参考 - -### ~/.config/proxycast/config.json -```json -{ - "server": { - "host": "127.0.0.1", - "port": 8999, - "api_key": "proxy_cast" - }, - "providers": { - "kiro": { - "enabled": true, - "credentials_path": "~/.aws/sso/cache/kiro-auth-token.json" - }, - "gemini": { - "enabled": true, - "credentials_path": "~/.gemini/oauth_creds.json" - }, - "qwen": { - "enabled": true, - "credentials_path": "~/.qwen/oauth_creds.json" - } - }, - "default_provider": "kiro" -} -``` - ---- - -## 八、其他工具配置 - -### Cherry Studio / Cursor / Cline -``` -API Base URL: http://127.0.0.1:8999/v1 -API Key: proxy_cast -Model: claude-opus-4-5 -``` - -### Python 代码 -```python -import openai - -client = openai.OpenAI( - base_url="http://127.0.0.1:8999/v1", - api_key="proxy_cast" -) - -response = client.chat.completions.create( - model="claude-opus-4-5", - messages=[{"role": "user", "content": "Hello"}] -) -print(response.choices[0].message.content) -``` - ---- - -## 九、故障排查 - -### ProxyCast 没运行 -```bash -ps aux | grep proxycast -# 如果没有，启动它： -cd /mnt/d/.projects/kiro-account-manager-main.zip/proxycast-main && ./src-tauri/target/release/proxycast & -``` - -### 检查端口 -```bash -ss -tlnp | grep 8999 -``` - -### 测试 API -```bash -curl http://127.0.0.1:8999/v1/models -H "Authorization: Bearer proxy_cast" -``` - -### Token 过期 -在 ProxyCast 界面点"刷新 Token"，或手动刷新（见第六节）。 - ---- - -## 十、Gemini API Keys - -当前配置的 8 个 Key（轮询负载均衡）： -``` -# 请在此处填入你自己的 Gemini API Keys -# 格式：AIzaSy... （每行一个） -# 获取地址：https://aistudio.google.com/app/apikey -``` - -每日限制：每个 Key 20 RPD，8 个 Key = 160 次/天 - ---- - -## 十一、OpenRouter API Key - -``` -# 请在此处填入你自己的 OpenRouter API Key -# 格式：sk-or-v1-... -# 获取地址：https://openrouter.ai/keys -``` - -免费模型无限制使用。 - ---- - -*文档生成时间：2025-12-20 16:38* - - ---- - -## 十二、Claude Code 完整启动命令大全 - -### Kiro 凭证 (Claude 系列) - -```bash -# Claude Opus 4.7 - 最强模型 -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model claude-opus-4-7 - -# Claude Sonnet 4.5 - 平衡性能 -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model claude-sonnet-4-5 - -# Claude Sonnet 4.5 特定版本 -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model claude-sonnet-4-5-20250929 - -# Claude 3.7 Sonnet -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model claude-3-7-sonnet-20250219 - -# Claude 3.5 Sonnet Latest -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model claude-3-5-sonnet-latest -``` - -### Gemini 系列 (8个 API Key 轮询) - -```bash -# Gemini 3.1 Pro Preview - 最新预览版 -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model gemini-3.1-pro-preview - -# Gemini 2.5 Pro - Pro 版本 -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model gemini-2.5-pro - -# Gemini 2.5 Pro Preview -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model gemini-2.5-pro-preview-06-05 - -# Gemini 2.5 Flash - 快速版本 -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model gemini-2.5-flash - -# Gemini 2.5 Flash Lite - 轻量版本 -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model gemini-2.5-flash-lite -``` - -### Qwen 系列 (阿里通义千问) - -```bash -# Qwen3 Coder Plus - 代码增强版 -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model qwen3-coder-plus - -# Qwen3 Coder Flash - 快速版本 -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model qwen3-coder-flash -``` - -### OpenRouter 免费模型 - -```bash -# DeepSeek R1 - 推理最强 -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model deepseek/deepseek-r1-0528:free - -# Gemini 2.0 Flash Exp - 翻译首选 -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model google/gemini-2.0-flash-exp:free - -# Llama 3.1 405B - 综合最强 -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model meta-llama/llama-3.1-405b-instruct:free - -# Llama 3.3 70B - 速度快 -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model meta-llama/llama-3.3-70b-instruct:free - -# Hermes 3 405B - 指令遵循好 -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model nousresearch/hermes-3-llama-3.1-405b:free - -# Devstral 2 - 代码专精 123B -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model mistralai/devstral-2512:free - -# GLM 4.5 Air - 中文原生 -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model z-ai/glm-4.5-air:free - -# 通义深度研究 - 中文研究 -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model alibaba/tongyi-deepresearch-30b-a3b:free - -# KAT-Coder Pro - 代码 Agent -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model kwaipilot/kat-coder-pro:free - -# Qwen 2.5 VL - 视觉理解 -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model qwen/qwen-2.5-vl-7b-instruct:free - -# NVIDIA Nemotron 12B VL - 视觉/文档 -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model nvidia/nemotron-nano-12b-v2-vl:free - -# Olmo 3.1 32B Think - 深度推理 -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model allenai/olmo-3.1-32b-think:free -``` - ---- - -## 十三、快捷别名配置 - -在 `~/.bash_aliases` 或 `~/.bashrc` 中添加： - -```bash -# ProxyCast 启动 -alias proxycast='cd /mnt/d/.projects/kiro-account-manager-main.zip/proxycast-main && ./src-tauri/target/release/proxycast &' - -# Claude Code 快捷命令 -alias cc-opus='CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model claude-opus-4-5' -alias cc-sonnet='CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model claude-sonnet-4-5' -alias cc-gemini='CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model gemini-3-pro-preview' -alias cc-deepseek='CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model deepseek/deepseek-r1-0528:free' -alias cc-qwen='CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model qwen3-coder-plus' -alias cc-llama='CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model meta-llama/llama-3.1-405b-instruct:free' -alias cc-devstral='CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model mistralai/devstral-2512:free' -``` - -添加后执行 `source ~/.bashrc` 生效。 - ---- - -## 十四、模型推荐场景 - -| 场景 | 推荐模型 | 启动命令 | -|------|----------|----------| -| 复杂推理/架构设计 | claude-opus-4-5 | `cc-opus` | -| 日常编码 | claude-sonnet-4-5 | `cc-sonnet` | -| 快速问答 | gemini-2.5-flash | 见上方命令 | -| 深度推理 | deepseek/deepseek-r1-0528:free | `cc-deepseek` | -| 代码专精 | mistralai/devstral-2512:free | `cc-devstral` | -| 中文任务 | qwen3-coder-plus | `cc-qwen` | -| 免费综合 | meta-llama/llama-3.1-405b-instruct:free | `cc-llama` | - ---- - -*文档更新时间：2025-12-20 16:41* - - ---- - -## 十五、从零部署完整教程 - -### 1. 环境要求 - -```bash -# 系统要求 -- Linux / WSL2 / macOS -- Node.js >= 20.0.0 -- Rust >= 1.70 -- pnpm 或 npm - -# 检查环境 -node -v # v20.x.x -rustc -V # rustc 1.70+ -``` - -### 2. 获取源码 - -```bash -# 克隆或下载 ProxyCast -cd /mnt/d/.projects -git clone https://github.com/aiclientproxy/proxycast.git -# 或解压已有的 zip 包 -``` - -### 3. 编译构建 - -```bash -cd proxycast-main - -# 安装前端依赖 -npm install - -# 构建 Tauri 应用 -npm run tauri build - -# 构建产物位置 -# Linux: src-tauri/target/release/proxycast -# macOS: src-tauri/target/release/bundle/dmg/ -# Windows: src-tauri/target/release/bundle/msi/ -``` - -### 4. 准备凭证文件 - -#### Kiro 凭证 -```bash -# 安装 Kiro IDE 并登录，凭证自动生成在： -~/.aws/sso/cache/kiro-auth-token.json -``` - -#### Gemini 凭证 -```bash -# 安装 Gemini CLI 并登录 -pip install gemini-cli -gemini auth login -# 凭证位置：~/.gemini/oauth_creds.json -``` - -#### Qwen 凭证 -```bash -# 安装通义千问 CLI 并登录 -# 凭证位置：~/.qwen/oauth_creds.json -``` - -### 5. 首次启动配置 - -```bash -# 启动 ProxyCast -./src-tauri/target/release/proxycast & - -# 等待 GUI 启动后： -# 1. 进入 "凭证池" 页面 -# 2. 点击 "一键读取凭证" 或手动添加 -# 3. 进入 "Dashboard" 点击 "启动服务器" -``` - -### 6. 手动添加凭证到数据库（无 GUI 方式） - -```bash -# Kiro 凭证 -sqlite3 ~/.proxycast/proxycast.db "INSERT INTO provider_pool_credentials (uuid, provider_type, credential_data, is_healthy, check_health, error_count, is_disabled, name, usage_count, created_at, updated_at, source) VALUES ( - '$(uuidgen)', - 'kiro', - '{\"type\":\"kiro_o_auth\",\"creds_file_path\":\"$HOME/.aws/sso/cache/kiro-auth-token.json\"}', - 1, 1, 0, 0, 'Kiro OAuth', 0, $(date +%s), $(date +%s), 'manual' -);" - -# Gemini OAuth -sqlite3 ~/.proxycast/proxycast.db "INSERT INTO provider_pool_credentials (uuid, provider_type, credential_data, is_healthy, check_health, error_count, is_disabled, name, usage_count, created_at, updated_at, source) VALUES ( - '$(uuidgen)', - 'gemini', - '{\"type\":\"gemini_o_auth\",\"creds_file_path\":\"$HOME/.gemini/oauth_creds.json\",\"project_id\":null}', - 1, 1, 0, 0, 'Gemini OAuth', 0, $(date +%s), $(date +%s), 'manual' -);" - -# Gemini API Key -sqlite3 ~/.proxycast/proxycast.db "INSERT INTO provider_pool_credentials (uuid, provider_type, credential_data, is_healthy, check_health, error_count, is_disabled, name, usage_count, created_at, updated_at, source) VALUES ( - '$(uuidgen)', - 'gemini_api_key', - '{\"type\":\"gemini_api_key\",\"api_key\":\"你的API_KEY\",\"base_url\":null,\"excluded_models\":[]}', - 1, 1, 0, 0, 'Gemini Key 1', 0, $(date +%s), $(date +%s), 'manual' -);" - -# Qwen OAuth -sqlite3 ~/.proxycast/proxycast.db "INSERT INTO provider_pool_credentials (uuid, provider_type, credential_data, is_healthy, check_health, error_count, is_disabled, name, usage_count, created_at, updated_at, source) VALUES ( - '$(uuidgen)', - 'qwen', - '{\"type\":\"qwen_o_auth\",\"creds_file_path\":\"$HOME/.qwen/oauth_creds.json\"}', - 1, 1, 0, 0, 'Qwen OAuth', 0, $(date +%s), $(date +%s), 'manual' -);" - -# OpenRouter (OpenAI 兼容) -sqlite3 ~/.proxycast/proxycast.db "INSERT INTO provider_pool_credentials (uuid, provider_type, credential_data, is_healthy, check_health, error_count, is_disabled, name, usage_count, created_at, updated_at, source) VALUES ( - '$(uuidgen)', - 'openai', - '{\"type\":\"open_a_i_key\",\"api_key\":\"sk-or-v1-xxx你的key\",\"base_url\":\"https://openrouter.ai/api\"}', - 1, 1, 0, 0, 'OpenRouter Free', 0, $(date +%s), $(date +%s), 'manual' -);" -``` - -### 7. 创建配置文件 - -```bash -mkdir -p ~/.config/proxycast - -cat > ~/.config/proxycast/config.json << 'EOF' -{ - "server": { - "host": "127.0.0.1", - "port": 8999, - "api_key": "proxy_cast", - "tls": {"enable": false} - }, - "providers": { - "kiro": {"enabled": true, "credentials_path": "~/.aws/sso/cache/kiro-auth-token.json"}, - "gemini": {"enabled": true, "credentials_path": "~/.gemini/oauth_creds.json"}, - "qwen": {"enabled": true, "credentials_path": "~/.qwen/oauth_creds.json"} - }, - "default_provider": "kiro" -} -EOF -``` - -### 8. 验证部署 - -```bash -# 启动服务 -./src-tauri/target/release/proxycast & - -# 等待几秒后测试 -curl http://127.0.0.1:8999/v1/models -H "Authorization: Bearer proxy_cast" - -# 测试聊天 -curl http://127.0.0.1:8999/v1/chat/completions \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer proxy_cast" \ - -d '{"model":"claude-sonnet-4-5","messages":[{"role":"user","content":"Hi"}]}' -``` - ---- - -## 十六、无头模式（Headless）部署教程 - -适用于服务器、Docker、无 GUI 环境。 - -### 1. 无头启动 - -```bash -# 设置无显示环境 -export DISPLAY= - -# 或使用虚拟显示（如果需要） -Xvfb :99 -screen 0 1024x768x24 & -export DISPLAY=:99 - -# 启动 ProxyCast -./src-tauri/target/release/proxycast & -``` - -### 2. 纯命令行配置（无需 GUI） - -```bash -#!/bin/bash -# headless-setup.sh - 无头模式一键配置脚本 - -PROXYCAST_DIR="/path/to/proxycast-main" -DB_PATH="$HOME/.proxycast/proxycast.db" -CONFIG_PATH="$HOME/.config/proxycast/config.json" - -# 创建目录 -mkdir -p ~/.proxycast ~/.config/proxycast - -# 初始化数据库（首次运行会自动创建） -$PROXYCAST_DIR/src-tauri/target/release/proxycast & -sleep 3 -pkill -f proxycast - -# 添加凭证 -add_credential() { - local type=$1 - local data=$2 - local name=$3 - sqlite3 $DB_PATH "INSERT INTO provider_pool_credentials (uuid, provider_type, credential_data, is_healthy, check_health, error_count, is_disabled, name, usage_count, created_at, updated_at, source) VALUES ('$(uuidgen)', '$type', '$data', 1, 1, 0, 0, '$name', 0, $(date +%s), $(date +%s), 'manual');" -} - -# 添加 Kiro -add_credential "kiro" '{"type":"kiro_o_auth","creds_file_path":"'$HOME'/.aws/sso/cache/kiro-auth-token.json"}' "Kiro OAuth" - -# 添加 Gemini API Keys -GEMINI_KEYS=( - "AIzaSyBt4pIYmLYheuMpXSCj5VLkCA-fhfdEVT4" - "AIzaSyBSllSwrObqvUiXqFG5RUJXB6woZoBSaTk" - # 添加更多 keys... -) -for i in "${!GEMINI_KEYS[@]}"; do - add_credential "gemini_api_key" '{"type":"gemini_api_key","api_key":"'${GEMINI_KEYS[$i]}'","base_url":null,"excluded_models":[]}' "Gemini Key $((i+1))" -done - -# 添加 OpenRouter -add_credential "openai" '{"type":"open_a_i_key","api_key":"sk-or-v1-xxx","base_url":"https://openrouter.ai/api"}' "OpenRouter" - -echo "配置完成！" -``` - -### 3. Systemd 服务（Linux 后台运行） - -```bash -# 创建服务文件 -sudo cat > /etc/systemd/system/proxycast.service << 'EOF' -[Unit] -Description=ProxyCast API Proxy Service -After=network.target - -[Service] -Type=simple -User=lenovo -Environment=DISPLAY= -WorkingDirectory=/mnt/d/.projects/kiro-account-manager-main.zip/proxycast-main -ExecStart=/mnt/d/.projects/kiro-account-manager-main.zip/proxycast-main/src-tauri/target/release/proxycast -Restart=always -RestartSec=10 - -[Install] -WantedBy=multi-user.target -EOF - -# 启用并启动服务 -sudo systemctl daemon-reload -sudo systemctl enable proxycast -sudo systemctl start proxycast - -# 查看状态 -sudo systemctl status proxycast - -# 查看日志 -journalctl -u proxycast -f -``` - -### 4. Docker 部署（可选） - -```dockerfile -# Dockerfile -FROM rust:1.70 as builder -WORKDIR /app -COPY . . -RUN cargo build --release -p proxycast - -FROM debian:bookworm-slim -RUN apt-get update && apt-get install -y libwebkit2gtk-4.1-0 libgtk-3-0 && rm -rf /var/lib/apt/lists/* -COPY --from=builder /app/target/release/proxycast /usr/local/bin/ -EXPOSE 8999 -CMD ["proxycast"] -``` - -```bash -# 构建并运行 -docker build -t proxycast . -docker run -d -p 8999:8999 -v ~/.proxycast:/root/.proxycast -v ~/.config/proxycast:/root/.config/proxycast proxycast -``` - -### 5. 无头模式下刷新 Token - -```bash -#!/bin/bash -# refresh-kiro-token.sh - 自动刷新 Kiro Token - -TOKEN_FILE="$HOME/.aws/sso/cache/kiro-auth-token.json" -REFRESH_TOKEN=$(jq -r '.refreshToken' "$TOKEN_FILE") - -# 调用刷新 API -RESPONSE=$(curl -s -X POST "https://prod.us-east-1.auth.desktop.kiro.dev/refreshToken" \ - -H "Content-Type: application/json" \ - -d "{\"refreshToken\": \"$REFRESH_TOKEN\"}") - -# 检查是否成功 -if echo "$RESPONSE" | jq -e '.accessToken' > /dev/null 2>&1; then - NEW_ACCESS_TOKEN=$(echo "$RESPONSE" | jq -r '.accessToken') - NEW_EXPIRES=$(date -d "+1 hour" --iso-8601=seconds) - - # 更新 token 文件 - jq --arg token "$NEW_ACCESS_TOKEN" --arg exp "$NEW_EXPIRES" \ - '.accessToken = $token | .expiresAt = $exp' "$TOKEN_FILE" > "${TOKEN_FILE}.tmp" - mv "${TOKEN_FILE}.tmp" "$TOKEN_FILE" - - echo "Token 刷新成功！" -else - echo "Token 刷新失败：$RESPONSE" - exit 1 -fi -``` - -```bash -# 添加到 crontab，每 50 分钟刷新一次 -crontab -e -# 添加：*/50 * * * * /path/to/refresh-kiro-token.sh >> /var/log/kiro-refresh.log 2>&1 -``` - -### 6. 健康检查脚本 - -```bash -#!/bin/bash -# health-check.sh - -API_URL="http://127.0.0.1:8999" -API_KEY="proxy_cast" - -# 检查服务是否运行 -if ! curl -s "$API_URL/v1/models" -H "Authorization: Bearer $API_KEY" > /dev/null; then - echo "ProxyCast 服务异常，正在重启..." - pkill -f proxycast - sleep 2 - cd /mnt/d/.projects/kiro-account-manager-main.zip/proxycast-main - ./src-tauri/target/release/proxycast & - sleep 5 - - if curl -s "$API_URL/v1/models" -H "Authorization: Bearer $API_KEY" > /dev/null; then - echo "重启成功！" - else - echo "重启失败，请检查日志" - exit 1 - fi -else - echo "服务正常运行" -fi -``` - -### 7. 远程访问配置 - -```bash -# 修改配置允许外部访问 -sed -i 's/"host": "127.0.0.1"/"host": "0.0.0.0"/' ~/.config/proxycast/config.json - -# 重启服务 -pkill -f proxycast -./src-tauri/target/release/proxycast & - -# 获取 IP -ip addr show | grep "inet " | grep -v 127.0.0.1 - -# 外部访问 -# API Base URL: http://<你的IP>:8999/v1 -# API Key: proxy_cast -``` - ---- - -## 十七、常用运维命令 - -```bash -# 启动 -cd /mnt/d/.projects/kiro-account-manager-main.zip/proxycast-main && ./src-tauri/target/release/proxycast & - -# 停止 -pkill -f proxycast - -# 重启 -pkill -f proxycast; sleep 2; cd /mnt/d/.projects/kiro-account-manager-main.zip/proxycast-main && ./src-tauri/target/release/proxycast & - -# 查看进程 -ps aux | grep proxycast - -# 查看端口 -ss -tlnp | grep 8999 - -# 查看日志 -tail -f ~/.proxycast/logs/*.log - -# 查看凭证池 -sqlite3 ~/.proxycast/proxycast.db "SELECT provider_type, name, is_healthy FROM provider_pool_credentials;" - -# 测试 API -curl http://127.0.0.1:8999/v1/models -H "Authorization: Bearer proxy_cast" | jq - -# 清空凭证池 -sqlite3 ~/.proxycast/proxycast.db "DELETE FROM provider_pool_credentials;" -``` - ---- - -*文档更新时间：2025-12-20 16:42* - - ---- - -## 十八、断线问题修复 - -### 问题原因 - -Claude Code 使用自定义 API endpoint 时，仍会尝试向 Anthropic 发送遥测数据。遥测失败会导致程序异常退出。 - -### 解决方案 - -所有启动命令都需要添加环境变量禁用遥测： - -```bash -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 -``` - -### 完整单行启动命令（无遥测） - -```bash -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model claude-opus-4-5 -``` - ---- - -*文档更新时间：2025-12-20 17:46* - - ---- - -## 十九、Codex (OpenAI) 凭证集成（待实现） - -### 凭证来源 - -Codex 凭证来自 OpenAI 官方 CLI 工具，存储在 `~/.codex/auth.json`： - -```json -{ - "id_token": "eyJhbGciOiJSUzI1NiI...", - "access_token": "eyJhbGciOiJSUzI1NiI...", - "refresh_token": "rt_TK67iD7Pdgg...", - "account_id": "24e8f403-dbdb-42f9-8309-98951fc2862e", - "email": "xxx@gmail.com", - "type": "codex", - "expired": "2025-12-30T08:16:48..." -} -``` - -### 当前状态 - -- ✅ 凭证已添加到 ProxyCast 数据库 -- ✅ `providers/codex.rs` 已实现 OAuth 刷新逻辑 -- ❌ `server.rs` 中 `call_provider_openai` 函数尚未集成 Codex 调用 -- ❌ WSL 编译环境链接器问题，无法编译新版本 - -### 代码修改位置 - -需要在 `src-tauri/src/server.rs` 的 `call_provider_openai` 函数中添加： - -```rust -CredentialData::CodexOAuth { creds_file_path } => { - // 加载凭证、刷新 token、调用 OpenAI API - // 参考 KiroOAuth 的实现模式 -} -``` - -### 支持的模型 - -Codex 凭证支持所有 OpenAI 模型： -- gpt-5.5, gpt-5.4, gpt-5.2 -- gpt-4o, gpt-4o-mini, gpt-4-turbo -- o1, o1-mini, o1-preview -- o3-mini - ---- - -## 二十、Antigravity 凭证分析 - -### 凭证位置 - -Antigravity (Google AI IDE) 的凭证存储在 SQLite 数据库中： - -``` -Windows: %APPDATA%\Antigravity\User\globalStorage\state.vscdb -``` - -### 凭证结构 - -```sql --- 查询凭证 -SELECT value FROM ItemTable WHERE key = 'antigravityAuthStatus'; -``` - -返回 JSON： -```json -{ - "name": "git", - "apiKey": "ya29.a0Aa7pCA-1M5dtt...", // Google OAuth access_token - "email": "xxx@gmail.com", - "userStatusProtoBinaryBase64": "..." // 用户状态 protobuf -} -``` - -### 限制 - -- **只有 access_token**，没有 refresh_token -- access_token 有效期约 1 小时 -- 无法自动刷新，需要通过 Antigravity 应用重新登录 -- refresh_token 可能存储在 Windows Credential Manager（WSL 无法访问） - -### 结论 - -Antigravity 凭证不适合集成到 ProxyCast，因为无法自动刷新。建议使用 Gemini API Key 或 Gemini CLI OAuth 代替。 - ---- - -## 二十一、WSL 编译问题 - -### 问题描述 - -在 WSL 环境下编译 Rust 项目时，链接器报错： - -``` -error: unknown option '-Wl,--no-undefined-version' -error: unknown option '-Wl,--as-needed' -``` - -### 原因 - -Rust 1.90+ 默认使用 `lld` 链接器，但 WSL 的 `lld` 版本不兼容。 - -### 尝试的解决方案 - -1. **使用 gold 链接器**（失败） -```bash -RUSTFLAGS="-C link-arg=-fuse-ld=gold" cargo build --release -``` - -2. **配置 cargo**（失败） -```toml -# ~/.cargo/config.toml -[target.x86_64-unknown-linux-gnu] -linker = "gcc" -rustflags = ["-C", "link-arg=-fuse-ld=gold"] -``` - -### 建议 - -- 在原生 Linux 或 Windows 上编译 -- 使用 Docker 容器编译 -- 使用预编译的 Release 版本 - ---- - -## 二十二、数据库路径差异 - -### WSL vs Windows - -| 环境 | 数据库路径 | -|------|-----------| -| WSL/Linux | `~/.proxycast/proxycast.db` | -| Windows | `%APPDATA%\proxycast\proxycast.db` | -| macOS | `~/Library/Application Support/proxycast/proxycast.db` | - -### 注意事项 - -- WSL 中运行的 ProxyCast 使用 Linux 路径 -- Windows GUI 版本使用 Windows 路径 -- 两者数据库不共享，需要分别配置凭证 - ---- - -## 二十三、本次配置总结 - -### 已配置的凭证池 - -| Provider | 名称 | 状态 | -|----------|------|------| -| kiro | Kiro OAuth | ✅ 正常 | -| qwen | Qwen OAuth | ✅ 正常 | -| gemini_api_key | Gemini Key 1-8 | ✅ 8个轮询 | -| openai | OpenRouter Free | ✅ 正常 | -| codex | Codex OAuth | ⚠️ 待实现 | - -### 可用模型 - -**Claude (Kiro)** -- claude-opus-4-5, claude-sonnet-4-5, claude-3-7-sonnet-20250219 - -**Gemini (API Keys)** -- gemini-3-pro-preview, gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite - -**Qwen** -- qwen3-coder-plus, qwen3-coder-flash - -**OpenRouter Free** -- deepseek/deepseek-r1-0528:free -- meta-llama/llama-3.1-405b-instruct:free -- mistralai/devstral-2512:free -- 等 10+ 免费模型 - -### 快速启动 - -```bash -# 启动 ProxyCast -cd /mnt/d/.projects/kiro-account-manager-main.zip/proxycast-main && ./src-tauri/target/release/proxycast & - -# 使用 Claude Code -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model claude-opus-4-5 -``` - ---- - ---- - -## 二十四、新增 OpenRouter 免费模型（2025-12-21 测试通过） - -### 新增模型列表 - -| 模型 | 说明 | 状态 | -|------|------|------| -| `openai/gpt-oss-120b:free` | GPT 开源 120B | ✅ 已测试 | -| `openai/gpt-oss-20b:free` | GPT 开源 20B | ✅ 已测试 | -| `moonshotai/kimi-k2:free` | Kimi K2.5 | ✅ 已测试 | - -### Claude Code 启动命令 - -```bash -# GPT-OSS 120B - 大参数开源模型 -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model openai/gpt-oss-120b:free - -# GPT-OSS 20B - 轻量开源模型 -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model openai/gpt-oss-20b:free - -# Kimi K2.5 - 月之暗面最新模型 -CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8999 ANTHROPIC_API_KEY=proxy_cast claude --dangerously-skip-permissions --model moonshotai/kimi-k2:free -``` - -### API 测试命令 - -```bash -# 测试 GPT-OSS 120B -curl -s http://127.0.0.1:8999/v1/chat/completions \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer proxy_cast" \ - -d '{"model":"openai/gpt-oss-120b:free","messages":[{"role":"user","content":"Hi"}],"max_tokens":10}' - -# 测试 Kimi K2.5 -curl -s http://127.0.0.1:8999/v1/chat/completions \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer proxy_cast" \ - -d '{"model":"moonshotai/kimi-k2:free","messages":[{"role":"user","content":"Hi"}],"max_tokens":10}' -``` - -### 更新后的 OpenRouter 免费模型完整列表 - -| 模型 | 说明 | 推荐场景 | -|------|------|----------| -| `deepseek/deepseek-r1-0528:free` | 推理最强 | 复杂推理 | -| `meta-llama/llama-3.1-405b-instruct:free` | 综合最强 | 通用任务 | -| `mistralai/devstral-2512:free` | 代码专精 123B | 编程 | -| `openai/gpt-oss-120b:free` | GPT 开源 120B | 通用 | -| `openai/gpt-oss-20b:free` | GPT 开源 20B | 快速响应 | -| `moonshotai/kimi-k2:free` | Kimi K2.5 | 中文任务 | -| `google/gemini-2.0-flash-exp:free` | Gemini 2.0 | 翻译 | -| `meta-llama/llama-3.3-70b-instruct:free` | Llama 3.3 | 速度快 | -| `nousresearch/hermes-3-llama-3.1-405b:free` | Hermes 3 | 指令遵循 | -| `z-ai/glm-4.5-air:free` | GLM 4.5 | 中文原生 | -| `alibaba/tongyi-deepresearch-30b-a3b:free` | 通义深研 | 中文研究 | -| `kwaipilot/kat-coder-pro:free` | KAT-Coder | 代码 Agent | -| `qwen/qwen-2.5-vl-7b-instruct:free` | Qwen VL | 视觉理解 | -| `allenai/olmo-3.1-32b-think:free` | Olmo 3.1 | 深度推理 | - ---- - -*文档更新时间：2025-12-21 17:07* diff --git a/docs/playbooks/README.md b/docs/playbooks/README.md deleted file mode 100644 index 6c87654..0000000 --- a/docs/playbooks/README.md +++ /dev/null @@ -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) - 从零开始 diff --git a/docs/playbooks/tradecat-sheets-api-usage.md b/docs/playbooks/tradecat-sheets-api-usage.md deleted file mode 100644 index 8949723..0000000 --- a/docs/playbooks/tradecat-sheets-api-usage.md +++ /dev/null @@ -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（本表为公开资产，不应包含密钥；但消费方也不应添加敏感头部到公开日志里）。 - diff --git a/docs/references/README.md b/docs/references/README.md index 31011e3..14a4154 100644 --- a/docs/references/README.md +++ b/docs/references/README.md @@ -28,4 +28,3 @@ ## 🔗 相关资源 - [入门指南](../getting-started/) - 从零开始 -- [方法论](../playbooks/) - 工具与经验 diff --git a/llms.txt b/llms.txt index 8bace9c..2b983ea 100644 --- a/llms.txt +++ b/llms.txt @@ -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 diff --git a/metadata/redirects.yml b/metadata/redirects.yml index ed01803..47f43fd 100644 --- a/metadata/redirects.yml +++ b/metadata/redirects.yml @@ -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 diff --git a/metadata/taxonomy.yml b/metadata/taxonomy.yml index 56b4f3f..266d290 100644 --- a/metadata/taxonomy.yml +++ b/metadata/taxonomy.yml @@ -5,9 +5,6 @@ sections: concepts: path: docs/concepts purpose: 核心概念、方法论、问题求解与工程思想 - playbooks: - path: docs/playbooks - purpose: 工具实践与专项方法文档 references: path: docs/references purpose: 清单、模板、强约束与常见坑