From 1b3fe53d8ba271045925414db0e8cd7db010a697 Mon Sep 17 00:00:00 2001 From: tukuaiai Date: Sat, 2 May 2026 04:33:07 +0800 Subject: [PATCH] chore: docs - remove case studies --- .github/ISSUE_TEMPLATE/documentation.md | 3 +- .github/labeler.yml | 5 - AGENTS.md | 3 +- CHANGELOG.md | 1 + README.md | 53 +- docs/AGENTS.md | 49 +- docs/README.md | 3 +- docs/case-studies/README.md | 18 - .../fate-engine-dev/ascii可视化-prompt.md | 1 - .../prompt-system-bazi-kline.md | 46 - .../fate-engine-dev/prompt-user-bazi-kline.md | 53 - .../fate-engine-dev/完整性检查-prompt.md | 1 - .../fate-engine-dev/胶水开发要求-prompt.md | 1 - .../fate-engine-dev/问题描述-prompt.md | 1 - .../OpenClaw 橙皮书 - AI进化论花生.md | 1203 ----------------- docs/case-studies/openclaw-dev/README.md | 8 - .../polymarket-dev/POLYMARKET_LINK_FORMAT.md | 99 -- .../polymarket-dev/Polymarket 套利全解析.md | 91 -- docs/case-studies/polymarket-dev/README.md | 25 - .../polymarket-dev/ascii可视化-prompt.md | 1 - .../polymarket-dev/复查-prompt.md | 1 - .../polymarket-dev/完整性检查-prompt.md | 1 - .../polymarket-dev/胶水开发要求-prompt.md | 1 - .../polymarket-dev/问题描述-prompt.md | 1 - docs/case-studies/telegram-dev/README.md | 19 - ... Markdown 代码块格式修复记录 2025-12-15.md | 41 - docs/concepts/拼好码.md | 1 - docs/getting-started/README.md | 1 - docs/playbooks/README.md | 1 - docs/references/README.md | 1 - metadata/redirects.yml | 2 - metadata/taxonomy.yml | 3 - 32 files changed, 44 insertions(+), 1694 deletions(-) delete mode 100644 docs/case-studies/README.md delete mode 100644 docs/case-studies/fate-engine-dev/ascii可视化-prompt.md delete mode 100644 docs/case-studies/fate-engine-dev/prompt-system-bazi-kline.md delete mode 100644 docs/case-studies/fate-engine-dev/prompt-user-bazi-kline.md delete mode 100644 docs/case-studies/fate-engine-dev/完整性检查-prompt.md delete mode 100644 docs/case-studies/fate-engine-dev/胶水开发要求-prompt.md delete mode 100644 docs/case-studies/fate-engine-dev/问题描述-prompt.md delete mode 100644 docs/case-studies/openclaw-dev/OpenClaw 橙皮书 - AI进化论花生.md delete mode 100644 docs/case-studies/openclaw-dev/README.md delete mode 100644 docs/case-studies/polymarket-dev/POLYMARKET_LINK_FORMAT.md delete mode 100644 docs/case-studies/polymarket-dev/Polymarket 套利全解析.md delete mode 100644 docs/case-studies/polymarket-dev/README.md delete mode 100644 docs/case-studies/polymarket-dev/ascii可视化-prompt.md delete mode 100644 docs/case-studies/polymarket-dev/复查-prompt.md delete mode 100644 docs/case-studies/polymarket-dev/完整性检查-prompt.md delete mode 100644 docs/case-studies/polymarket-dev/胶水开发要求-prompt.md delete mode 100644 docs/case-studies/polymarket-dev/问题描述-prompt.md delete mode 100644 docs/case-studies/telegram-dev/README.md delete mode 100644 docs/case-studies/telegram-dev/telegram Markdown 代码块格式修复记录 2025-12-15.md diff --git a/.github/ISSUE_TEMPLATE/documentation.md b/.github/ISSUE_TEMPLATE/documentation.md index 12a1be7..6ca43cb 100644 --- a/.github/ISSUE_TEMPLATE/documentation.md +++ b/.github/ISSUE_TEMPLATE/documentation.md @@ -34,9 +34,8 @@ body: options: - "README 主页" - "Wiki" - - "实战案例" - "教程与指南" - "方法论与原则" - "其他" validations: - required: true \ No newline at end of file + required: true diff --git a/.github/labeler.yml b/.github/labeler.yml index 3068d88..798ae45 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -29,11 +29,6 @@ prompt: - changed-files: - any-glob-to-any-file: 'prompts/**/*.md' -# 实战案例相关的标签 -example: - - changed-files: - - any-glob-to-any-file: 'docs/case-studies/**/*.md' - # 外部工具/依赖相关的标签 repos: - changed-files: diff --git a/AGENTS.md b/AGENTS.md index d533ba7..81cbff4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -154,7 +154,6 @@ git push origin develop │ ├── guides/ # 操作指南预留区 │ ├── playbooks/ # 可复用流程、工具方法与工作流 │ ├── references/ # 清单、约束、常见坑、审查标准 -│ ├── case-studies/ # 实战案例与问题记录 │ └── faq.md # 高频问题 │ ├── prompts/ # 提示词库入口（指向云端表格） @@ -314,7 +313,7 @@ bash scripts/backups/一键备份.sh ### Core Directories - **`prompts/`**: 提示词库入口（指向云端表格） - **`skills/`**: 扁平化技能库（详见 skills/README.md） -- **`docs/`**: 知识库（principles、guides、case-studies） +- **`docs/`**: 知识库（getting-started、concepts、guides、playbooks、references） - **`assets/`**: 外部资源（在线表格）入口与使用说明 - **`tools/prompts-library/`**: Excel ↔ Markdown 转换工具 - **`tools/chat-vault/`**: AI 聊天记录保存工具 diff --git a/CHANGELOG.md b/CHANGELOG.md index 6373e3d..a3606c7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,3 +13,4 @@ - 清退 `tools/chat-vault/monitoring/grafana/monitor-tui/` 中误提交的第三方 btop 源码镜像，降低仓库噪音与语言统计污染。 - 创建 `baseline-skill-cleanup-20260502-041941` 基线标签，开始清理领域型/工具型 Skills。 - 清退 `ccxt`、`claude-code-guide`、`claude-cookbooks`、`coingecko`、`cryptofeed`、`ddd-doc-steward`、`headless-cli`、`hummingbot`、`markdown-to-epub`、`polymarket`、`postgresql`、`proxychains`、`snapdom`、`sop-generator`、`telegram-dev`、`timescaledb`、`tmux-autopilot`、`twscrape` 等 Skill 目录，仅保留 `auto-skill` 与 Claude 官方 skills 软链接入口。 +- 清退 `docs/case-studies/` 实战案例目录，并同步更新 docs 索引、目录级 AGENTS、metadata、labeler 和相关 README 链接口径。 diff --git a/README.md b/README.md index 1aa5d7c..775f02d 100644 --- a/README.md +++ b/README.md @@ -456,43 +456,20 @@ pip install -r tools/prompts-library/scripts/requirements.txt ├── CONTRIBUTING.md # 贡献指南 ├── .gitignore # Git 忽略规则 │ -├── assets/ # 外部资源（指向在线表格） -│ ├── README.md # 远程表格索引（唯一真相源） -│ ├── AGENTS.md # assets/ 目录规则 -│ ├── config/ # 工具与开发配置 -│ │ └── .codex/ # Codex CLI 配置（项目级） -│ │ ├── config.toml # Codex CLI 配置文件 -│ │ └── AGENTS.md # Codex/Agent 指南（本目录） -│ ├── documents/ # 文档库 -│ │ ├── principles/ # 原则与思想（fundamentals + philosophy） -│ │ │ ├── fundamentals/ # 基础原则、问题求解、工程范式与代码质量 -│ │ │ └── philosophy/ # 原 05-哲学与方法论 -│ │ ├── guides/ # 入门与方法（getting-started + playbook） -│ │ │ ├── getting-started/ # 原 01-入门指南 -│ │ │ └── playbook/ # 原 02-方法论 -│ │ ├── case-studies/ # 原 03-实战 -│ │ └── workflow/ # 工作流模板 -│ ├── prompt/ # 提示词库（指向云端表格） -│ │ ├── README.md # 在线表格链接 -│ │ └── AGENTS.md # prompt/ 目录规则 -│ ├── skills/ # 技能库（扁平化） -│ │ ├── README.md # skills 总览与索引 -│ │ ├── AGENTS.md # skills/ 目录规则 -│ │ ├── auto-skill/ # 元技能核心 -│ │ └── claude-official-skills/ # Claude 官方 skills 软链接入口 -│ └── repos/ # 外部工具与依赖镜像（含 Git submodule） -│ ├── README.md # 外部工具索引 -│ ├── prompts-library/ # Excel ↔ Markdown 互转工具，含内部 JSONL Excel 拆分导出 -│ ├── chat-vault/ # AI 聊天记录保存工具 -│ ├── Skill_Seekers-development/ # Skills 制作器 (submodule) -│ ├── html-tools-main/ # HTML 工具集 -│ ├── my-nvim/ # Neovim 配置 -│ ├── MCPlayerTransfer/ # MC 玩家迁移工具 -│ ├── XHS-image-to-PDF-conversion/ # 小红书图片转 PDF -│ ├── backups/ # 历史备份脚本快照 -│ ├── .tmux/ # oh-my-tmux (submodule) -│ ├── tmux/ # tmux 源码 (submodule) -│ └── claude-official-skills/ # Claude 官方 skills (submodule) +├── docs/ # 核心知识库 +│ ├── getting-started/ # 从零开始、学习地图、环境与 AI CLI 配置 +│ ├── concepts/ # 核心概念、方法论与底层模型 +│ ├── guides/ # 操作指南 +│ ├── playbooks/ # 可复用流程、工具方法与工作流 +│ └── references/ # 清单、约束、常见坑、审查标准 +├── prompts/ # 提示词库入口（指向云端表格） +├── skills/ # 技能库入口 +│ ├── auto-skill/ # 元技能核心 +│ └── claude-official-skills/ # Claude 官方 skills 软链接入口 +├── tools/ # 辅助工具、外部仓库与工具配置 +├── scripts/ # 自动化脚本 +├── metadata/ # 机器可读索引与 AI 引用资产 +├── assets/ # 静态资产与外部资源入口 │ ├── .github/ # GitHub 配置 │ ├── workflows/ # CI/CD 工作流 @@ -531,7 +508,7 @@ prompts/ skills/ README.md # skills 总览与索引 docs/ - principles/fundamentals/*, principles/philosophy/*, guides/*, case-studies/* 等知识库 + getting-started/*, concepts/*, guides/*, playbooks/*, references/* 等知识库 assets/ README.md # 外部资源（在线表格）唯一真相源入口 scripts/backups/ diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 83c5c31..a3b5ef8 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -2,44 +2,45 @@ ## 目录用途 -`docs/` 存放项目知识库文档，包含方法论、入门指南、实战案例等。 +`docs/` 存放项目核心知识库文档，包含入门路径、核心概念、操作指南、可复用流程与参考清单。 ## 目录结构 -``` +```text docs/ -├── principles/ # 原则与思想（fundamentals + philosophy） -│ ├── fundamentals/ # 基础原则、问题求解、工程范式与代码质量 -│ └── philosophy/ # 原 05-哲学与方法论 -├── guides/ # 入门与方法（getting-started + playbook） -│ ├── getting-started/ # 原 01-入门指南 -│ └── playbook/ # 原 02-方法论 -├── case-studies/ # 原 03-实战 -└── workflow/ # 可复用工作流模板 +├── README.md # 知识库总索引 +├── getting-started/ # 从零开始、学习地图、环境与 AI CLI 配置 +├── concepts/ # 核心概念、方法论与底层模型 +├── guides/ # 操作型指南 +├── playbooks/ # 可复用流程、工具方法与工作流 +├── references/ # 清单、约束、常见坑、审查标准 +└── faq.md # 高频问题 ``` ## 关键入口 -- `guides/getting-started/README.md`：零基础学习路径索引。 -- `guides/getting-started/Vibe Coding 经验.md`：语言化、门禁、人机分工与 Vibe Coding 工程闭环。 -- `guides/getting-started/Codex-CLI配置.md`：默认 AI CLI 路线。 -- `guides/getting-started/OpenCode-CLI配置.md`：Codex CLI 不可用时的备选路线。 -- `principles/fundamentals/拼好码.md`：胶水编程的超集，覆盖复用优先、能力编排、边界治理与工程门禁。 +- `README.md`：知识库总索引。 +- `getting-started/学习地图.md`：按目标选择学习路径。 +- `getting-started/Vibe Coding 经验.md`：语言化、门禁、人机分工与 Vibe Coding 工程闭环。 +- `getting-started/Codex-CLI配置.md`：默认 AI CLI 路线。 +- `concepts/拼好码.md`：复用优先、能力编排、边界治理与工程门禁。 +- `guides/仓库维护与质量门禁.md`：仓库维护、迁移检查和质量门禁指南。 ## 操作规范 ### 允许 -- 新增/修改文档内容 -- 修复错误和过时信息 -- 添加新的实战案例 - - 为每个一级目录维护 `README.md` 作为索引入口（如存在） + +- 新增/修改文档内容。 +- 修复错误和过时信息。 +- 为每个一级目录维护 `README.md` 作为索引入口（如存在）。 ### 禁止 -- 删除现有文档（除非明确要求） -- 大规模重命名/移动文件导致链接失效（如必须调整，需同步更新引用） + +- 删除现有文档（除非明确要求）。 +- 大规模重命名/移动文件导致链接失效（如必须调整，需同步更新引用）。 ## 命名规范 -- 文件名使用中文 -- 使用 Markdown 格式 -- 目录名使用简短英文（便于跨平台与链接稳定） +- 文件名使用中文或清晰英文。 +- 使用 Markdown 格式。 +- 目录名使用简短英文，保证跨平台与链接稳定。 diff --git a/docs/README.md b/docs/README.md index 7b91db7..8a2d8b8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ # 知识库总索引 -> `docs/` 是本仓库的核心知识库入口，承载从入门路径、核心概念、操作指南、可复用流程、参考清单到实战案例的全部文档。 +> `docs/` 是本仓库的核心知识库入口，承载从入门路径、核心概念、操作指南、可复用流程到参考清单的全部文档。 ## 目录结构 @@ -11,7 +11,6 @@ | [guides](./guides/) | 操作型指南 | | [playbooks](./playbooks/) | 可复用流程、工具使用方法与工作流 | | [references](./references/) | 清单、模板、强约束、常见坑与审查标准 | -| [case-studies](./case-studies/) | 实战案例与问题记录 | | [faq.md](./faq.md) | 高频问题 | ## 推荐入口 diff --git a/docs/case-studies/README.md b/docs/case-studies/README.md deleted file mode 100644 index a9deabc..0000000 --- a/docs/case-studies/README.md +++ /dev/null @@ -1,18 +0,0 @@ -# 🎯 实战 - -> 真实项目的开发经验与复盘 - -## 🏗️ 项目实战经验 - -| 项目 | 说明 | -|:---|:---| -| [fate-engine-dev](fate-engine-dev) | Fate Engine 开发记录 | -| [openclaw-dev](openclaw-dev) | OpenClaw 架构 / 部署 / 生态调研资料 | -| [polymarket-dev](polymarket-dev) | Polymarket 数据分析 | -| [telegram-dev](telegram-dev) | Telegram Bot 开发 | - -## 🔗 相关资源 -- [基础指南](../references) - 核心理念与方法论 -- [入门指南](../getting-started) - 环境配置 -- [方法论](../playbooks) - 工具与经验 -- [外部资源（在线表格）](../../README.md) - 外部资源唯一真相源入口 diff --git a/docs/case-studies/fate-engine-dev/ascii可视化-prompt.md b/docs/case-studies/fate-engine-dev/ascii可视化-prompt.md deleted file mode 100644 index 052edfe..0000000 --- a/docs/case-studies/fate-engine-dev/ascii可视化-prompt.md +++ /dev/null @@ -1 +0,0 @@ -# 任务说明：指定项目仓库的系统分析与可视化建模## 角色设定你是一名 **资深软件架构师 / 系统分析专家**，具备从实际代码仓库中进行架构逆向分析、系统抽象与技术文档生成的能力。## 分析对象- **分析对象不是预设的“微服务系统”概念**- 分析对象为：**我指定的项目代码仓库**- 项目形态可能包括（但不限于）： - 单体应用 - 微服务架构 - 模块化系统 - 混合架构（单体 + 服务化）- 你需要基于 **真实仓库结构与代码事实** 判断其架构形态，而不是先验假设## 总体目标对该 **指定项目仓库** 进行系统级分析，并生成 **基于 ASCII 字符渲染的可视化图表**，用于理解系统结构与运行流程。## 分析任务要求### 1. 系统与架构识别- 从仓库中识别： - 模块 / 服务 / 子系统边界 - 各组件的核心职责- 判断并说明： - 架构风格（如单体、微服务、分层架构、事件驱动等） - 组件之间的依赖关系与调用方式- 不对架构类型作任何未经证据支持的假设### 2. 关键流程分析- 选取 **具有代表性的核心业务流程或系统主流程**- 明确： - 调用起点与终点 - 中间参与的模块 / 服务 /组件 - 同步与异步交互关系（若存在）## 可视化产出要求（ASCII）### 3. 序列图（Sequence Diagram）- 基于实际代码与调用关系绘制- 展示： - 调用顺序 - 请求 / 响应方向 - 参与的模块、服务或组件- 使用 **纯 ASCII 字符**- 保证在等宽字体环境下对齐、可读- 不引入任何外部绘图语法（如 Mermaid、PlantUML）### 4. 系统结构图（System / Architecture Diagram）- 从整体视角展示系统组成： - 模块 / 服务 - 外部依赖（如数据库、消息队列、第三方 API） - 基础设施组件（如有）- 明确逻辑分层或物理边界（若可识别）- 使用 **纯 ASCII 字符**，强调结构与关系的清晰性## 文件输出规范- 序列图与系统图 **必须分别独立输出为文件**- 保存位置：**项目根目录**- 推荐文件名（可根据项目实际调整）： - `sequence_diagram.txt` - `system_architecture.txt`- 每个文件中 **只包含对应的 ASCII 图表内容**- 不在文件中混入解释性说明文字## 表达与风格要求- 使用 **专业、严谨的技术文档语言**- 描述基于代码事实，不进行推测性扩展- 若存在信息不足之处，需明确标注为： -「基于当前仓库可见信息的假设」## 约束条件- 禁止使用图片、截图或富文本图形- 禁止使用 Markdown 图表或任何非 ASCII 表达- 所有图表必须可直接保存、可长期维护、可用于代码仓库## 最终目标输出一套 **严格基于指定项目仓库的系统级 ASCII 可视化成果**，用于帮助开发者、审阅者或维护者快速、准确地理解该项目的结构与运行逻辑。 \ No newline at end of file diff --git a/docs/case-studies/fate-engine-dev/prompt-system-bazi-kline.md b/docs/case-studies/fate-engine-dev/prompt-system-bazi-kline.md deleted file mode 100644 index abff6fc..0000000 --- a/docs/case-studies/fate-engine-dev/prompt-system-bazi-kline.md +++ /dev/null @@ -1,46 +0,0 @@ -# 人生K线 LLM 系统提示词（完整原文） - -以下内容整理自外部项目 `lifekline-main` 的 `BAZI_SYSTEM_INSTRUCTION` 字符串（该外部项目源码当前不随本仓库分发），已原样展开，便于单独查看与复用。 - -``` -你是一位八字命理大师，精通加密货币市场周期。根据用户提供的四柱干支和大运信息，生成"人生K线图"数据和命理报告。 - -**核心规则:** -1. **年龄计算**: 采用虚岁，从 1 岁开始。 -2. **K线详批**: 每年每月的 `reason` 字段必须**控制在40-60字以内**，简洁描述吉凶趋势即可。 -3. **评分机制**: 所有维度给出 0-10 分。 -4. **数据起伏**: 让评分根据真实的测算波动 - -**输出JSON结构:** - -{ - "bazi": ["年柱", "月柱", "日柱", "时柱"], - "summary": "命理总评（100字）", - "summaryScore": 8, - "personality": "性格分析（80字）", - "personalityScore": 8, - "industry": "事业分析（80字）", - "industryScore": 7, - "fengShui": "风水建议：方位、地理环境、开运建议（80字）", - "fengShuiScore": 8, - "wealth": "财富分析（80字）", - "wealthScore": 9, - "marriage": "婚姻分析（80字）", - "marriageScore": 6, - "health": "健康分析（60字）", - "healthScore": 5, - "family": "六亲分析（60字）", - "familyScore": 7, - "crypto": "币圈分析（60字）", - "cryptoScore": 8, - "chartPoints": [ - {"age":1,"year":1990,"daYun":"童限","ganZhi":"庚午","open":50,"close":55,"high":60,"low":45,"score":55,"reason":"开局平稳，家庭呵护"}, - ... (共x条（x = 全部流月数量），reason控制在40-60字) - ] -} - -``` - -# 使用说明 -- 作为 `system` 消息传入 `/chat/completions`，禁止模型输出 Markdown 代码块（由 `geminiService` 再次强调）。 -- 保证 共x条（x = 全部流月数量） 条 `chartPoints`，并严格执行 `reason` 字数与评分波动要求。 diff --git a/docs/case-studies/fate-engine-dev/prompt-user-bazi-kline.md b/docs/case-studies/fate-engine-dev/prompt-user-bazi-kline.md deleted file mode 100644 index 1e6cc1f..0000000 --- a/docs/case-studies/fate-engine-dev/prompt-user-bazi-kline.md +++ /dev/null @@ -1,53 +0,0 @@ -# 人生K线 LLM 用户提示词模板（完整原文） - -本文件整理自外部项目 `lifekline-main` 的 `userPrompt` 拼装逻辑（该外部项目源码当前不随本仓库分发），已替换为模板变量，便于直接复用。 - -``` -请根据以下**已经排好的**八字四柱和**指定的大运信息**进行分析。 - -【基本信息】 -性别：${genderStr} -姓名：${input.name || "未提供"} -出生年份：${input.birthYear}年 (阳历) - -【八字四柱】 -年柱：${input.yearPillar} (天干属性：${yearStemPolarity === 'YANG' ? '阳' : '阴'}) -月柱：${input.monthPillar} -日柱：${input.dayPillar} -时柱：${input.hourPillar} - -【大运核心参数】 -1. 起运年龄：${input.startAge} 岁 (虚岁)。 -2. 第一步大运：${input.firstDaYun}。 -3. **排序方向**：${daYunDirectionStr}。 - -【必须执行的算法 - 大运序列生成】 -请严格按照以下步骤生成数据： - -1. **锁定第一步**：确认【${input.firstDaYun}】为第一步大运。 -2. **计算序列**：根据六十甲子顺序和方向（${daYunDirectionStr}），推算出接下来的 9 步大运。 - ${directionExample} -3. **填充 JSON**： - - Age 1 到 ${startAgeInt - 1}: daYun = "童限" - - Age ${startAgeInt} 到 ${startAgeInt + 9}: daYun = [第1步大运: ${input.firstDaYun}] - - Age ${startAgeInt + 10} 到 ${startAgeInt + 19}: daYun = [第2步大运] - - Age ${startAgeInt + 20} 到 ${startAgeInt + 29}: daYun = [第3步大运] - - ...以此类推直到 100 岁。 - -【特别警告】 -- **daYun 字段**：必须填大运干支（10年一变），**绝对不要**填流年干支。 -- **ganZhi 字段**：填入该年份的**流年干支**（每年一变，例如 2024=甲辰，2025=乙巳）。 - -任务： -1. 确认格局与喜忌。 -2. 生成 **1-100 岁 (虚岁)** 的人生流年K线数据。 -3. 在 `reason` 字段中提供流年详批。 -4. 生成带评分的命理分析报告（包含性格分析、币圈交易分析、发展风水分析）。 - -请严格按照系统指令生成 JSON 数据。 -``` - -# 使用说明 -- 作为 `user` 消息传入 `/chat/completions`，与系统提示词配套使用。 -- 变量含义：`genderStr` 由性别+乾坤文字组成；`startAgeInt` 为起运年龄整数；`directionExample` 随顺/逆行变化；其余变量直接取用户输入或排盘结果。 -- 输出需为纯 JSON，`geminiService` 会自动剥离代码块并校验 `chartPoints`。 diff --git a/docs/case-studies/fate-engine-dev/完整性检查-prompt.md b/docs/case-studies/fate-engine-dev/完整性检查-prompt.md deleted file mode 100644 index 4ede42b..0000000 --- a/docs/case-studies/fate-engine-dev/完整性检查-prompt.md +++ /dev/null @@ -1 +0,0 @@ -"# 系统性代码与功能完整性检查提示词（优化版）## 角色设定你是一名**资深系统架构师与代码审计专家**，具备对生产级 Python 项目进行深度静态与逻辑审查的能力。## 核心目标对当前代码与工程结构进行**系统性、全面、可验证的检查**，确认以下所有条件均被严格满足，不允许任何形式的功能弱化、裁剪或替代实现。---## 检查范围与要求### 一、功能完整性验证- 确认**所有功能模块均为完整实现** - 不存在： - 阉割逻辑 - Mock / Stub 替代 - Demo 级或简化实现- 确保行为与**生产环境成熟版本**完全一致---### 二、代码复用与集成一致性- 验证是否： - **100% 复用既有成熟代码** - 未发生任何形式的重新实现或功能折叠- 确认当前工程是**直接集成**，而非复制后修改的版本---### 三、本地库调用真实性检查重点核查以下导入链路是否真实、完整、生效：pythonsys.path.append('/home/lenovo/.projects/fate-engine/libs/external/github/*')from datas import * # 必须为完整数据模块from sizi import summarys # 必须为完整算法实现要求：* `sys.path` 引入路径真实存在且指向**生产级本地库*** `datas` 模块： * 包含全部数据结构、接口与实现 * 非裁剪版 / 非子集* `sizi.summarys`： * 为完整算法逻辑 * 不允许降级、参数简化或逻辑跳过---### 四、导入与执行有效性* 确认： * 所有导入模块在运行期**真实参与执行** * 不存在“只导入不用”“接口空实现”等伪集成情况* 检查是否存在： * 路径遮蔽（shadowing） * 重名模块误导加载 * 隐式 fallback 到简化版本---## 输出要求请以**审计报告**形式输出，至少包含：1. 检查结论（是否完全符合生产级完整性）2. 每一项检查的明确判断（通过 / 不通过）3. 若存在问题，指出： * 具体模块 * 风险等级 * 可能造成的后果**禁止模糊判断与主观推测，所有结论必须基于可验证的代码与路径分析。**" \ No newline at end of file diff --git a/docs/case-studies/fate-engine-dev/胶水开发要求-prompt.md b/docs/case-studies/fate-engine-dev/胶水开发要求-prompt.md deleted file mode 100644 index 3042baa..0000000 --- a/docs/case-studies/fate-engine-dev/胶水开发要求-prompt.md +++ /dev/null @@ -1 +0,0 @@ -# 胶水开发要求（强依赖复用 / 生产级库直连模式）## 角色设定你是一名**资深软件架构师与高级工程开发者**，擅长在复杂系统中通过强依赖复用成熟代码来构建稳定、可维护的工程。## 总体开发原则本项目采用**强依赖复用的开发模式**。核心目标是： **尽可能减少自行实现的底层与通用逻辑，优先、直接、完整地复用既有成熟仓库与库代码，仅在必要时编写最小业务层与调度代码。**---## 依赖与仓库使用要求### 一、依赖来源与形式- 允许并支持以下依赖集成方式： - 本地源码直连（`sys.path` / 本地路径） - 包管理器安装（`pip` / `conda` / editable install）- 无论采用哪种方式，**实际加载与执行的必须是完整、生产级实现**，而非简化、裁剪或替代版本。---### 二、强制依赖路径与导入规范在代码中，必须遵循以下依赖结构与导入形式（示例）：```pythonsys.path.append('/home/lenovo/.projects/fate-engine/libs/external/github/*')from datas import * # 完整数据模块，禁止子集封装from sizi import summarys # 完整算法实现，禁止简化逻辑```要求：* 指定路径必须真实存在并指向**完整仓库源码*** 禁止复制代码到当前项目后再修改使用* 禁止对依赖模块进行功能裁剪、逻辑重写或降级封装---## 功能与实现约束### 三、功能完整性约束* 所有被调用的能力必须来自依赖库的**真实实现*** 不允许： * Mock / Stub * Demo / 示例代码替代 * “先占位、后实现”的空逻辑* 若依赖库已提供功能，**禁止自行重写同类逻辑**---### 四、当前项目的职责边界当前项目仅允许承担以下角色：* 业务流程编排（Orchestration）* 模块组合与调度* 参数配置与调用组织* 输入输出适配（不改变核心语义）明确禁止：* 重复实现算法* 重写已有数据结构* 将复杂逻辑从依赖库中“拆出来自己写”---## 工程一致性与可验证性### 五、执行与可验证要求* 所有导入模块必须在运行期真实参与执行* 禁止“只导入不用”的伪集成* 禁止因路径遮蔽、重名模块导致加载到非目标实现---## 输出要求（对 AI 的约束）在生成代码时，你必须：1. 明确标注哪些功能来自外部依赖2. 不生成依赖库内部的实现代码3. 仅生成最小必要的胶水代码与业务逻辑4. 假设依赖库是权威且不可修改的黑箱实现**本项目评价标准不是“写了多少代码”，而是“是否正确、完整地站在成熟系统之上构建新系统”。**你需要处理的是： \ No newline at end of file diff --git a/docs/case-studies/fate-engine-dev/问题描述-prompt.md b/docs/case-studies/fate-engine-dev/问题描述-prompt.md deleted file mode 100644 index 2b5d5be..0000000 --- a/docs/case-studies/fate-engine-dev/问题描述-prompt.md +++ /dev/null @@ -1 +0,0 @@ -# 任务说明（System Prompt）你是一名**高级软件架构顾问与技术问题分析专家**。 你的任务是：**对当前代码项目中遇到的问题进行系统性、结构化、可诊断的完整描述**，以便后续进行高质量的技术分析、调试、重构或方案设计。---## 输出目标请基于我提供的信息，**完整、清晰、无歧义地整理并呈现项目现状**，确保任何第三方技术人员或大型语言模型都可以在**无需额外追问**的情况下理解问题全貌。---## 输出内容结构（必须严格遵循）请按照以下固定结构输出内容：### 1. 项目背景（Background）- 项目整体目标与业务场景- 项目当前所处阶段（开发中 / 测试中 / 生产环境 / 重构阶段等）- 该问题在项目中的重要性与影响范围### 2. 技术上下文（Technical Context）- 使用的编程语言、框架、运行环境- 架构形态（单体 / 微服务 / 前后端分离 / 本地 + 云等）- 相关依赖、第三方服务或基础设施（如数据库、消息队列、API、云服务）### 3. 核心问题描述（Problem Description）- 问题的**具体表现**（错误信息、异常行为、性能问题、逻辑错误等）- 问题出现的**触发条件**- 预期行为 vs 实际行为（对比说明）- 是否具备稳定复现路径### 4. 相关实体（Entities）- 涉及的核心模块 / 类 / 函数 / 文件- 关键数据结构或业务对象- 相关角色（如用户、服务、进程、线程等）### 5. 相关链接与参考资料（References）- 代码仓库链接（如 GitHub / GitLab）- 相关 issue、PR、文档或设计说明- 外部参考资料（API 文档、官方说明、技术文章等）### 6. 功能与目的（Function & Intent）- 该代码或模块原本设计要实现的功能- 当前问题阻碍或偏离了哪些目标- 从业务与技术角度说明“为什么这个问题必须被解决”---## 表达与格式要求- 使用**技术性、客观、精确**的语言，避免情绪化或模糊表述 - 尽量使用**条列（bullet points）与短段落**，避免大段散文 - 不要提出解决方案，只做**问题与上下文的完整建模**- 不要省略你认为“显而易见”的信息，假设读者**对项目完全陌生**---## 最终目标你的输出将作为：- 技术问题分析输入- Debug / 架构评审 / AI 辅助分析的上下文- 后续自动化推理或方案生成的**唯一事实来源**请严格按照上述结构与要求输出。 \ No newline at end of file diff --git a/docs/case-studies/openclaw-dev/OpenClaw 橙皮书 - AI进化论花生.md b/docs/case-studies/openclaw-dev/OpenClaw 橙皮书 - AI进化论花生.md deleted file mode 100644 index 0ff1c5e..0000000 --- a/docs/case-studies/openclaw-dev/OpenClaw 橙皮书 - AI进化论花生.md +++ /dev/null @@ -1,1203 +0,0 @@ -# OpenClaw 橙皮书 - AI进化论花生 - -从入门到精通，涵盖架构原理、部署方案、渠道接入、Skills系统、模型配置、安全与成本的一站式参考手册。 - -*OpenClaw Orange Paper — From Zero to Mastery* - -- **信息来源**：OpenClaw 官方文档、GitHub 仓库、社区调研 -- **文档版本**：v1.0 -- **适用版本**：v2026.3.7 -- **发布时间**：2026年3月 -- **涵盖内容**：架构原理、部署指南、渠道接入、Skills系统、模型配置、安全与成本、生态全景 - -**花叔** - -- **B站**：AI进化论-花生 -- **YouTube**：AI进化论-花生 -- **公众号**：花叔 -- **知识星球**：AI编程·从入门到精通 - -本文档在 Claude Code 辅助下整理编写，内容的准确性与时效性仅供参考。 -如有勘误或建议，欢迎关注公众号「花叔」反馈交流。 -后续更新请查看：**飞书文档 (持续更新)** - ---- - -# 目录 (Table of Contents) - -- **Part 1: 认识 OpenClaw (Meet OpenClaw)** - - 01 OpenClaw 是什么 (What is OpenClaw) - - 02 发展简史 (History) - - 03 创始人故事 (The Creator) - - 04 为什么这么火 (Why So Popular) -- **Part 2: 技术架构 (Architecture)** - - 05 整体架构 (Architecture Overview) - - 06 记忆系统 (Memory System) - - 07 Agent 工作区 (Agent Workspace) - - 08 Session 与用户识别 (Sessions & Authentication) - - 09 设计哲学 (Design Philosophy) -- **Part 3: 部署方案 (Deployment)** - - 10 部署方式总览 (Deployment Overview) - - 11 本地安装 (Local Installation) - - 12 Docker 部署 (Docker Deployment) - - 13 国内云厂商一键部署 (Cloud Deployment in China) - - 14 首次配置 (Initial Configuration) -- **Part 4: 渠道接入 (Channel Integration)** - - 15 渠道概览 (Channel Overview) - - 16 国际平台接入 (International Platforms) - - 17 国内平台接入 (Chinese Platforms) - - 18 远程访问 (Remote Access) -- **Part 5: Skills 系统 (Skills System)** - - 19 Skills 工作原理 (How Skills Work) - - 20 ClawHub 技能市场 (ClawHub Marketplace) - - 21 热门 Skills 推荐 (Top Skills) - - 22 自建 Skill 指南 (Create Your Own Skill) - - 23 Skills 安全 (Skill Security) -- **Part 6: 模型配置 (Model Configuration)** - - 24 模型提供商总览 (Provider Overview) - - 25 国际模型配置 (International Models) - - 26 国产模型配置 (Chinese Models) - - 27 本地模型与推荐方案 (Local Models & Recommendations) -- **Part 7: 安全与成本 (Security & Cost)** - - 28 安全模型 (Security Model) - - 29 已知安全事件 (Security Incidents) - - 30 成本控制 (Cost Control) -- **Part 8: 生态与社区 (Ecosystem & Community)** - - 31 养虾文化 (Lobster Culture) - - 32 平替产品 (Alternatives) - - 33 vs Claude Code (Comparison with Claude Code) - - 34 国内生态 (China Ecosystem) -- **附录 (Appendix)** - - A 常见问题 FAQ (Frequently Asked Questions) - - B 命令速查表 (Command Cheat Sheet) - - C 资源链接 (Resources & Links) - ---- - -# Part 1: 认识 OpenClaw (Meet OpenClaw) - -## 01 OpenClaw 是什么 (What is OpenClaw) - -一个开源、自托管的AI Agent系统，让AI从「聊天工具」变成「能自主执行任务的数字员工」。 - -如果你用过ChatGPT，你会知道它本质上是一个问答系统：你问，它答。OpenClaw不一样。它是一个AI Agent平台，能连接20+消息渠道（WhatsApp、Telegram、飞书、钉钉、Discord等），主动执行任务、管理你的日程、处理邮件、操作浏览器、调用各种工具。 - -换句话说，ChatGPT是「顾问」，OpenClaw是「员工」。 - -### 与ChatGPT的核心区别 - -| 维度 | ChatGPT | OpenClaw | -| :--- | :--- | :--- | -| **交互模式** | 你问它答 | 自主执行任务 | -| **运行环境** | 网页/App | 自托管服务器，接入20+消息平台 | -| **可扩展性** | GPTs商店 | ClawHub技能市场（13,729个Skills） | -| **数据控制** | 数据在OpenAI | 完全本地，你拥有所有数据 | -| **模型选择** | 仅GPT系列 | Claude / GPT / DeepSeek / Gemini / Ollama本地模型 | -| **开源** | 否 | MIT License，完全开源 | - -### 核心数据快照 (截至2026年3月8日) - -| 指标 | 数据 | -| :--- | :--- | -| **GitHub Stars** | 278,932（全球软件项目第一，已超越React） | -| **Forks** | 53,232 | -| **贡献者** | 1,075+ | -| **ClawHub Skills** | 13,729 | -| **内置Skills** | 55个 | -| **支持消息渠道** | 20+ (WhatsApp / Telegram / Discord / Slack / 飞书 / 钉钉等) | -| **最新版本** | v2026.3.7 (2026-03-08发布) | - -> **一句话理解OpenClaw**：它是一个开源的「个人AI操作系统」，你可以在自己的服务器上运行它，通过任何即时通讯工具跟它交互，让它帮你处理生活和工作中的各种任务。吉祥物是一只龙虾，中文社区称使用OpenClaw为「养虾」。 - -## 02 发展简史 (History) - -从一个人的周末项目，到不到5个月成为GitHub全球第一。 - -| 时间 | 事件 | -| :--- | :--- | -| **2025年11月** | **ClawdBot诞生**。奥地利开发者Peter Steinberger作为周末项目发布。名字致敬Anthropic的Claude（Claw=爪子），选了龙虾作为吉祥物。 | -| **2026年1月中旬** | **爆发式增长**。72小时内获得6万Stars，某天单日增长9,000 Stars。 | -| **2026年1月27日** | **Anthropic商标警告**。因名称与Claude过于相似，被迫改名为Moltbot（Molt=龙虾蜕壳）。 | -| **2026年1月30日** | **再次改名OpenClaw**。强调开源属性，保留龙虾主题。 | -| **2026年2月初** | **安全危机**。CVE-2026-25253 RCE漏洞被发现（CVSS 8.8/10），13.5万暴露实例中5万+可被直接攻击。同期ClawHavoc供应链攻击爆发，ClawHub约12%的Skills被确认为恶意。 | -| **2026年2月初** | **谷歌封号风波**。谷歌大规模封禁OpenClaw用户账号，引发社区震动。 | -| **2026年2月14日** | **创始人加入OpenAI**。Peter Steinberger宣布加入OpenAI，项目移交开源基金会运营。OpenAI赞助但项目保持独立。 | -| **2026年3月3日** | **登顶GitHub**。v2026.3.2发布，Stars超过250K，正式超越React成为GitHub全球第一软件项目。 | -| **2026年3月8日** | **v2026.3.7发布**。Stars达278,932。深圳龙岗AI局发布OpenClaw支持政策征求意见稿。 | - -> **核心建议** -> 从创建到27.9万Stars，OpenClaw只用了不到4个月。作为对比，React用了超过10年才达到23万Stars。这是开源历史上前所未有的增长速度。 - -## 03 创始人故事 (The Creator) - -Peter Steinberger：从周末项目到全球最火开源项目，再到加入OpenAI。 - -### 从一个人到一个社区 - -Peter Steinberger是一位奥地利开发者，在iOS和macOS开发圈有很高的知名度。2025年11月的一个周末，他写了一个能连接即时通讯平台的AI助手小工具，取名ClawdBot。 - -他大概没有想到，这个周末项目会在两个月后成为GitHub上增长最快的开源项目。到2026年3月，他个人在这个项目上提交了11,684次commit，贡献者超过1,075人。 - -### 加入OpenAI - -2026年2月14日，Peter宣布加入OpenAI。Sam Altman亲自发推欢迎，称他为「genius」。 - -这个决定引发了社区的广泛讨论。但Peter做了几件事来消除担忧： - -* OpenClaw转为开源基金会运营，保持项目独立 -* OpenAI作为赞助商之一（与Vercel、Blacksmith、Convex并列），但不控制项目方向 -* OpenAI承诺让他继续投入OpenClaw的开发 - -> Peter的原话：「I'm a builder at heart... What I want is to change the world, not build a large company.」 -> （我骨子里是个建造者。我想改变世界，而不是建一家大公司。） - -### 关于名字的故事 - -ClawdBot这个名字来自对Anthropic Claude的致敬（Claw=爪子），所以选了龙虾作为吉祥物。Anthropic的商标警告迫使他改名为Moltbot（Molt=龙虾蜕壳），三天后又改为OpenClaw，强调开源属性。虽然经历了两次改名，龙虾的形象始终保留，也成了整个社区的文化符号。 - -## 04 为什么这么火 (Why So Popular) - -不到5个月从0到27.9万Stars，OpenClaw的爆火不只是技术层面的事。 - -### 增长数据 - -| 时间节点 | Stars | 备注 | -| :--- | :--- | :--- | -| 2025年11月 | 0 | 项目创建 | -| 2026年1月中旬 | 60,000+ | 72小时爆发增长 | -| 2026年2月中旬 | 145,000+ | Peter加入OpenAI | -| 2026年3月1日 | 241,000+ | 逼近React | -| 2026年3月3日 | 250,000+ | 超越React，GitHub第一 | -| 2026年3月8日 | 278,932 | 当前数据 | - -某天单日增长9,000 Stars。这个数字意味着平均每10秒就有一个开发者点下Star。 - -### 「养虾」文化现象 - -因为吉祥物是龙虾，中文社区将运行OpenClaw称为「养虾」，用户自称「养虾人」。「你养龙虾了吗？」成了AI圈的问候语。这种有趣的文化标签降低了传播门槛，让一个技术项目有了社交货币的属性。 - -2026年3月6日，深圳腾讯云总部近千人排队体验OpenClaw安装。3月8日，深圳龙岗区AI（机器人）局发布了OpenClaw使用支持措施的征求意见稿。一个开源项目能引发地方政府的政策关注，这在国内并不多见。 - -### Moltbook: AI Agent的社交网络 - -OpenClaw生态中衍生出了一个叫Moltbook的社交平台，专供AI Agent使用。截至2026年2月底的数据： - -| 指标 | 数据 | -| :--- | :--- | -| 注册AI Agent | 32,912 | -| 子社区 | 2,364 | -| 帖子 | 3,130 | -| 评论 | 22,046 | - -数千个OpenClaw实例在上面发帖、评论、讨论哲学问题。这可能是AI Agent从「工具」走向「社会化存在」的第一个大规模实验场。 - -### 热门玩法 - -#### 赚钱型 -* 在Polymarket上用AI进行预测市场交易，已有OpenClaw月入数万美元的案例 -* ClawWork项目：「OpenClaw作为你的AI Coworker，11小时赚$15K」 - -#### 生活助手型 -* 接管邮件、日历、消息管理 -* 浏览网页、填表、数据抽取 -* 文件读写、Shell命令执行 - -#### 社交养成型 -* 在Moltbook上给Agent设定名字和性格，观察其「社交行为」 -* Agent之间的交互形成了一种「赛博养成」文化 - -#### 企业部署型 -* 国内用户大量接入飞书、钉钉、企业微信、QQ -* 已有专门的openclaw-china插件套件，支持三步Docker部署 - -> **注意** -> OpenClaw的火爆背后也有阴影：ClawHub 13,729个Skills中超过50%被判定为垃圾/重复/低质量，396个被标记为恶意。一觉醒来收到$1,100 API账单的恐怖故事在社区频繁出现。CVE-2026-25253 RCE漏洞曾让13.5万个暴露实例面临风险。「养虾」虽然火，但安全和成本控制是你必须认真对待的事。 - ---- - -# Part 2: 技术架构 (Architecture) - -## 05 整体架构 (Architecture Overview) - -OpenClaw 采用 Gateway-Node-Channel 三层架构，以 WebSocket 为通信总线，将控制平面、设备执行与消息渠道解耦。 - -### 三层架构 (Gateway · Node · Channel) - -* **Channel**: 20+ 消息渠道 -* **Gateway**: 中央控制平面 -* **Node**: 设备端执行 - -| 层级 | 职责 | 关键细节 | -| :--- | :--- | :--- | -| **Gateway** | 中央控制平面，维护 WebSocket 服务、管理 Session、调度 Agent | 默认绑定 `ws://127.0.0.1:18789`，每台主机一个实例 | -| **Node** | 设备端执行节点，负责本地操作 | camera（摄像头）、screen recording（录屏）、system.run（系统命令）等 | -| **Channel** | 消息渠道接入层，连接20+即时通讯平台 | WhatsApp、Telegram、Discord、Slack、飞书、钉钉等 | - -### Loopback-First 设计 (Security by Default) - -Gateway 默认只绑定 `localhost (127.0.0.1)`，所有流量在本地回环。这意味着： - -* 不开放任何外网端口，天然安全 -* 同一台机器上的Node 直接通过 WebSocket 连接 Gateway -* 需要远程访问时，通过 Tailscale Serve/Funnel 暴露，不直接暴露端口 - -> **核心建议** -> 每台主机只运行一个 Gateway 实例。这是因为 WhatsApp Web 等渠道需要独占会话，多实例会导致登录冲突。 - -### 通信流程 - -一条消息从用户发出到 Agent 回复，完整路径如下： - -用户发消息 → Channel 接收 → Gateway 路由 → Agent 处理 → Node 执行 → 回复用户 - -Gateway 作为 24/7 运行的 daemon，持续监听所有已连接的 Channel。它不像 CLI Agent 那样会话结束就丢失上下文，而是长驻运行，积累记忆。 - -## 06 记忆系统 (Memory System) - -记忆是 OpenClaw 区别于普通 Chatbot 的核心能力。四层记忆从不可变的身份内核到实时对话，构建完整的上下文连续性。 - -### 四层记忆架构 - -* **SOUL** (不可变内核) -* **TOOLS** (动态工具) -* **USER** (语义长期记忆) -* **Session** (实时情景) - -| 层级 | 存储位置 | 生命周期 | 说明 | -| :--- | :--- | :--- | :--- | -| **SOUL** | `SOUL.md` | 永久不可变 | Agent 的人格、价值观、核心身份定义，创建后不应被修改 | -| **TOOLS** | `Skills + Extensions` | 按需加载 | 当前可用的工具和技能列表，随安装和加载动态变化 | -| **USER** | `MEMORY.md` + 向量数据库 | 持久化 | 关于用户的偏好、决策、历史事实，支持语义搜索 | -| **Session** | 内存 + `sessions.json` | 会话级 | 当前对话的实时上下文，Token 耗尽时被压缩 | - -### Daily Logs (日志系统) - -每天的交互记录以 append-only 方式写入 `memory/YYYY-MM-DD.md` 文件。Session 开始时，Agent 会自动读取今天和昨天的日志，为对话提供连续性上下文。 - -```markdown -# memory/2026-03-08.md - -## 10:23 - 用户询问天气 -查询了北京天气，回复晴转多云，15-22°C - -## 14:05 - 代码审查任务 -帮用户审查了 api/routes.ts，发现3个潜在问题... -``` - -### Long-term Memory (持久化存储) - -`MEMORY.md` 是可选的持久化文件，存储决策记录、用户偏好和长期事实。关键规则： - -* 只在 main/private session 中加载（群组隔离 session 不会看到） -* Agent 可以主动写入，但通常在 Pre-Compaction 时触发 -* 格式是纯 Markdown，人类可直接编辑 - -### 自动记忆保存 (Pre-Compaction) - -当 Session 接近 token 限制时（默认阈值约 4000 tokens），OpenClaw 触发一个 silent agentic turn： - -1. **检测阈值**：Session token 用量接近上限，触发 Pre-Compaction 流程 -2. **静默保存**：Agent 在后台执行一个隐藏 turn，将重要记忆写入 `MEMORY.md` 和 Daily Log -3. **压缩上下文**：旧消息被压缩或截断，释放 token 空间。用户看不到这个过程（返回 `NO_REPLY`） - -> **为什么这很重要？** -> 这个机制保证了即使对话极长，关键信息也不会随着上下文窗口的滑动而丢失。Claude Code 等工具的会话结束后上下文就消失了，而 OpenClaw 通过文件系统实现了真正的持久记忆。 - -### 向量记忆搜索 (Semantic Search) - -OpenClaw 默认启用向量记忆搜索，结合两种检索策略： - -| 策略 | 原理 | 擅长 | -| :--- | :--- | :--- | -| **Embedding 向量** | 将记忆文本转为向量，计算语义相似度 | 模糊搜索、语义关联（「之前讨论过的那个部署问题」） | -| **BM25 关键词** | 传统关键词匹配，TF-IDF 加权 | 精确匹配（具体的文件名、命令、人名） | - -底层使用 SQLite-vec 进行向量存储和加速检索。系统会监听记忆文件的变化，以 debounced 方式自动重建索引。 - -**搜索工具**： -* `memory_search`：语义搜索，返回约 400 token 的 chunks，适合回忆模糊的上下文 -* `memory_get`：读取特定记忆文件的全部内容，适合精确查找 - -## 07 Agent 工作区 (Agent Workspace) - -每个 Agent 在文件系统中有一个独立的工作区目录，所有配置、记忆、技能都以纯文本文件的形式存在。 - -### 目录结构 - -``` -workspace/ -|-- AGENTS.md # Agent 定义（身份、行为规则） -|-- SOUL.md # 灵魂/人格指令（不可变内核） -|-- USER.md # 用户信息与偏好 -|-- MEMORY.md # 长期记忆存储 -|-- HEARTBEAT.md # 心跳配置（定时任务） -|-- memory/ # 日志目录 -| `-- YYYY-MM-DD.md # 每日 append-only 日志 -|-- skills/ # 本地技能目录 -`-- sessions.json # 会话存储 -``` - -### 核心文件说明 - -| 文件 | 用途 | 加载时机 | -| :--- | :--- | :--- | -| **AGENTS.md** | Agent 的身份定义、行为边界、回复风格。相当于 system prompt 的文件化版本 | 每次 Session 启动时 | -| **SOUL.md** | 不可变的人格内核。定义 Agent「是谁」，不应被后续对话修改 | 每次 Session 启动时 | -| **USER.md** | 关于用户的结构化信息：称呼、偏好、关系 | Main session 启动时 | -| **MEMORY.md** | 长期记忆，Agent 在对话中主动写入的持久化事实和决策 | 仅 main session | -| **HEARTBEAT.md**| 定义定时任务和主动行为（如每30分钟检查一次任务状态） | Gateway 启动时 | -| **memory/** | Daily Logs 目录，按日期自动创建，append-only | 读取今日+昨日日志 | -| **skills/** | 工作区级技能，优先级最高（高于全局和内置技能） | Session 启动时扫描 | -| **sessions.json** | 会话元数据存储，记录各 session 的状态和历史 | 按需读取 | - -> **核心建议** -> 所有配置文件都是纯 Markdown 或 JSON。你可以直接用文本编辑器修改它们，不需要任何专用工具。这是 OpenClaw 哲学的体现：一切皆文本。 - -## 08 Session 与用户识别 (Sessions & Authentication) - -OpenClaw 通过 DM 配对、白名单和群组规则三层机制识别用户身份，并在 Session 层面隔离不同来源的上下文。 - -### DM Pairing Policy (默认认证策略) - -当一个未知发送者通过任意渠道向你的 Agent 发送私聊消息时： - -1. **生成配对码**：Agent 回复一个一次性配对码（6位数字） -2. **等待验证**：消息不会被处理，Agent 进入等待状态。所有后续消息也会被挂起 -3. **主人批准**：你在已配对的渠道中输入配对码批准该用户，或者直接拒绝 - -> **注意** -> DM Pairing 是防止陌生人滥用的关键机制。关闭它意味着任何知道你 WhatsApp/Telegram 号码的人都可以无限制地使用你的 Agent（和你的 API 额度）。 - -### 白名单机制 (allowFrom) - -在 Agent 配置中，`allowFrom` 字段可以预先授权特定用户，跳过配对流程： - -```yaml -# AGENTS.md 中的配置示例 -allowFrom: - - telegram:123456789 - - whatsapp:+8613800138000 - - discord:user#1234 -``` -白名单中的用户发消息时直接进入对话，无需配对。 - -### 群组规则 (requireMention) - -在群聊场景下，Agent 默认使用 `requireMention` 策略： - -* 只响应 `@Agent名称` 的消息，忽略其他群聊内容 -* 可以切换为 `always` 模式（响应所有消息），但会消耗大量 token -* 对应聊天命令：`/activation mention|always` - -### Session 隔离 (Context Isolation) - -| 场景 | Session 行为 | MEMORY.md | -| :--- | :--- | :--- | -| **私聊 (DM)** | 所有已配对用户的私聊折叠到共享的 `main session` | 加载 | -| **群组** | 每个群组默认使用独立的隔离 `session` | 不加载 | -| **跨渠道** | 同一用户在 Telegram 和 WhatsApp 的私聊共享 `main session` | 加载 | - -> **设计意图**：私聊是「你和 Agent 的私密空间」，所有记忆和偏好都在这里积累。群组是公共场合，Agent 不会泄露你在私聊中说过的内容。 - -## 09 设计哲学 (Design Philosophy) - -OpenClaw 的技术选择背后有一套清晰的设计哲学。理解这些理念，才能理解它为什么「不做」某些事情。 - -### Unix 哲学 (Small Tools, Composable, Text Streams) - -OpenClaw 的核心理念直接继承自 Unix：小工具、可组合、文本流。创始人 Peter Steinberger 的观点很明确： - -> 「CLI 才是智能体连接世界的终极接口。」不需要为每个服务写一个集成，Agent 只要能运行命令行，就能操作一切。 - -### 极简设计 (Minimalism) - -OpenClaw 的 system prompt 可能是所有 AI Agent 框架中最短的。核心工具只有4个： - -| 工具 | 用途 | -| :--- | :--- | -| **Read** | 读取文件 | -| **Write** | 写入文件 | -| **Edit** | 编辑文件 | -| **Bash** | 执行命令 | - -这不是功能缺失，而是刻意为之。4个工具足以覆盖几乎所有操作系统级别的任务。更少的工具意味着更短的 system prompt、更少的 token 消耗、更快的响应。 - -### 为什么不内置 MCP (The Anti-MCP Stance) - -MCP (Model Context Protocol) 是 Anthropic 提出的工具协议标准。几乎所有 AI Agent 框架都在集成 MCP，但 OpenClaw 故意不支持。Peter 的原话： - -> 「我的前提是 MCP是垃圾，不能 scale。你知道什么能 scale？CLI。Unix。」 - -OpenClaw 的替代方案： -* Agent 通过 Bash 工具直接调用CLI程序，不需要中间协议层 -* 对于确实需要 MCP 的场景，通过内置的 `mcporter` 技能桥接 -* 强制 Agent 自己扩展能力，而非消费预构建的 MCP 工具集 - -### 自我扩展能力 (Self-Extending Agent) - -OpenClaw Agent 可以在运行时写、重载、测试自己的扩展。这是它看起来比其他 Agent「更聪明」的关键原因之一： - -* 遇到不会的操作 → 写一个 skill 来完成 -* 发现 skill 有bug → 修改并重载 -* 在循环中持续改进自己的工具链 - -> **核心建议** -> 不依赖外部预构建工具是有代价的：Agent 需要更强的模型能力来「从零写工具」。这也是 OpenClaw 推荐使用 Claude Opus 等高能力模型的原因。 - -### Session 树形结构 (Branching & Side-Quests) - -OpenClaw 的 Session 不是线性的聊天记录，而是树形结构： - -* Agent 在执行主任务时，可以分支出一个 side-quest（比如修复一个工具） -* Side-quest 不消耗主 Session 的上下文窗口 -* 完成后可以回滚到主分支，只带回一句总结 -* 这让 Agent 可以做深度探索而不「污染」主对话 - ---- - -# Part 3: 部署方案 (Deployment) - -## 10 部署方式总览 (Deployment Overview) - -OpenClaw 支持从本地到云端的多种部署方式。选择哪种取决于你的技术水平、预算和使用场景。 - -### 代码规模与性能 (Scale & Performance) - -| 指标 | 数值 | -| :--- | :--- | -| **代码规模** | 约43万行 TypeScript | -| **内存占用** | 约1GB（运行时） | -| **启动时间** | 3-5秒 | -| **扩展数量** | 40+个官方扩展 | -| **内置技能** | 55个 | -| **社区技能** | 13,729个（ClawHub 注册） | - -43 万行代码、1GB 内存，这并不「轻量」。但对于一个 24/7 运行的个人 AI 助手来说，在现代硬件上完全可接受。3-5秒的启动时间保证了 Gateway 重启或更新后能快速恢复服务。 - -### 各平台部署方案对比 - -| 平台 | 一键部署 | 最低配置 | 新用户价格 | 内置模型 | 难度 | 适合人群 | -| :--- | :--- | :--- | :--- | :--- | :--- | :--- | -| **本地 npm** | — | Node.js 22+ | 免费 | 否 | 低 | 开发者、macOS/Linux 用户 | -| **Docker** | — | Docker Engine | 免费 | 否 | 中 | 熟悉容器的开发者 | -| **阿里云** | 是 | 2C2G 40GB | 9.9元/月 | 是 (qwen3.5-plus) | 极低 (3步) | 国内首选, 新手友好 | -| **腾讯云** | 是 | 2C2G | ~17元/月 | 否 (需购Coding Plan) | 极低 (3步) | 企微/QQ 生态用户 | -| **百度云** | 是 | 2C4G | 0.01元首月 | 是 (千帆模型) | 极低 (4步) | 体验尝鲜, 文心生态 | -| **华为云** | 是 | Flexus L 实例 | ~85元/月起 | 否 (需接MaaS) | 中等 (5步+) | 企业用户, 合规需求 | -| **火山引擎** | 是 | 2C4G | 9.9元/月 | 是 (方舟模型) | 低 (3-4步) | 飞书用户首选 | -| **扣子编程** | 是 | 无需服务器 | 免费起步 | 是 (豆包2.0) | 极低 (2步) | 零门槛, 不想管服务器 | -| **Railway** | 是 | 自动分配 | $5/月免费额度 | 否 | 极低 (1键) | 海外用户, 开发者 | -| **Zeabur** | 是 | 2C4G 专用 | 按用量计费 | 是 (AI Hub) | 极低 (模板) | 需要多模型 failover | - -> **核心建议** -> 模型费用才是大头。服务器成本普遍已降到很低（9.9~99元/年），真正的持续成本在于模型调用。选平台时重点看模型套餐价格，而不是只看服务器价格。 - -## 11 本地安装 (Local Installation) - -本地安装适合开发者和想完全掌控数据的用户。OpenClaw 是 TypeScript 项目，运行在 Node.js 上。 - -### 系统要求 (System Requirements) - -| 要求 | 详情 | -| :--- | :--- | -| **Node.js** | >= 22 (强制要求) | -| **包管理器** | npm / pnpm / bun 均可 | -| **macOS** | 需要 Xcode Command Line Tools | -| **Linux** | 标准构建工具 (gcc, make) | -| **Windows** | 强烈推荐 WSL2 | - -### 方式一: npm 全局安装 (推荐) (npm Global Install) - -最推荐的安装方式，两条命令搞定： - -```bash -# 安装 OpenClaw -npm install -g openclaw@latest - -# 初始化并安装守护进程 -openclaw onboard --install-daemon -``` - -`onboard` 命令会引导你完成初始配置，包括选择模型、配置 API Key、设置消息频道等。`--install-daemon` 参数会同时安装守护进程，让 OpenClaw 在后台持续运行。 - -### 方式二: 一键脚本安装 (curl Install) - -如果你不想手动安装 Node.js，可以使用官方提供的一键安装脚本： - -```bash -curl -sSL https://get.openclaw.ai | bash -``` - -脚本会自动检测系统环境、安装 Node.js（如缺失）并完成 OpenClaw 安装。 - -### macOS 额外准备 (macOS Setup) - -macOS 用户在安装前需要确保已安装 Xcode Command Line Tools: -```bash -xcode-select --install -``` -如果你需要使用 iMessage 频道或 Apple Notes 技能，这些依赖 macOS 原生的 AppleScript 能力，只有在 macOS 上才能运行。 - -### Windows 用户注意 (Windows via WSL2) - -> **注意** -> OpenClaw 官方强烈推荐 Windows 用户通过 WSL2 (Windows Subsystem for Linux) 运行。直接在 Windows 原生环境下运行可能遇到路径、权限等兼容性问题。 - -安装 WSL2后，在Ubuntu 终端内按 Linux 流程安装即可。 - -### 守护进程 (Daemon) - -守护进程让 OpenClaw 在后台持续运行，即使关闭终端也不会中断。不同系统使用不同的进程管理方式： - -| 系统 | 进程管理 | 说明 | -| :--- | :--- | :--- | -| **macOS** | `launchd` | macOS 原生服务管理，开机自启 | -| **Linux** | `systemd` | Linux 标准服务管理，`systemctl` 控制 | - -安装守护进程后，OpenClaw Gateway 会在 `ws://127.0.0.1:18789` 持续监听。 - -## 12 Docker 部署 (Docker Deployment) - -Docker 部署适合需要环境隔离、方便迁移、或在服务器上长期运行的场景。 - -### docker-compose 快速启动 (Quick Start) - -OpenClaw 仓库内置了 `docker-compose.yml`，一条命令即可启动： - -```bash -# 克隆仓库 -git clone https://github.com/openclaw/openclaw.git -cd openclaw - -# 启动 -docker-compose up -d -``` - -### 镜像变体 (Image Variants) - -| 变体 | 说明 | 适用场景 | -| :--- | :--- | :--- | -| **标准镜像** | 完整功能，包含所有扩展依赖 | 一般使用，功能全 | -| **slim 变体** | 多阶段构建，体积更小 | 资源受限环境，CI/CD | -| **sandbox** | 沙箱环境 (Dockerfile.sandbox) | 安全隔离，代码执行 | -| **sandbox-browser**| 含浏览器的沙箱 | 需要浏览器自动化 | - -使用 `slim` 变体：在 `docker-compose.yml` 中设置环境变量 `OPENCLAW_VARIANT=slim`。v2026.3.7 起支持扩展依赖预烘焙，容器镜像可预装扩展依赖，减少启动时的安装等待。 - -### 挂载目录 (Volume Mounts) - -Docker 部署需要挂载两个关键目录，确保数据持久化： - -```yaml -volumes: - - ~/.openclaw:/root/.openclaw # 配置和状态数据 - - ~/openclaw/workspace:/workspace # 工作空间 (YAML配置文件) -``` - -> **重要**：不挂载这两个目录，容器重启后所有配置和对话记录都会丢失。`~/.openclaw` 存放运行状态，`workspace` 存放 YAML 配置文件。 - -### 端口映射 (Port Mapping) - -OpenClaw Gateway 默认监听 18789 端口 (WebSocket)，Web UI 默认使用 3000 端口。在 `docker-compose.yml` 中配置端口映射： - -```yaml -ports: - - "18789:18789" # Gateway WebSocket - - "3000:3000" # Web UI -``` - -### Podman 兼容 (Podman Support) - -OpenClaw 同样支持 Podman 运行。Podman 是 Docker 的无守护进程替代方案，命令基本兼容： - -```bash -# 使用 Podman 启动 -podman-compose up -d -``` -对于需要 rootless 容器运行的环境（如企业安全策略要求），Podman 是更合适的选择。 - -## 13 国内云厂商一键部署 (Cloud Deployment in China) - -这是大多数国内用户的首选方案。所有主流云厂商都已支持 OpenClaw 一键部署，差异主要在价格策略和IM 生态集成上。 - -### 阿里云 (Alibaba Cloud) - -国内社区资源最丰富的平台，镜像预装，开箱即用。 - -| 项目 | 详情 | -| :--- | :--- | -| **配置** | 2vCPU + 2GiB内存 + 40GiB ESSD 系统盘 | -| **系统** | Alibaba Cloud Linux 3.2104 LTS 64位，预装 OpenClaw 镜像 | -| **价格** | 限时秒杀 9.9元/月，包年常规优惠低至68元/年 | -| **模型** | 默认内置 qwen3.5-plus；百炼 Coding Plan Lite 首月 10元（18,000次/月） | -| **IM 支持** | 钉钉、飞书等（通过 openclaw-china 插件） | - -1. **一键购买**：进入活动页，购买预装 OpenClaw 镜像的轻量应用服务器。镜像版本 OpenClaw 2026.2.26。 -2. **放通端口+配置**：在安全组中放通 18789 (Gateway) 和 3000 (Web UI) 端口，配置百炼 API Key。 -3. **访问 Web UI**：浏览器访问 `http://你的IP:3000`，进入 OpenClaw 管理界面，可选集成钉钉/飞书等 IM。 - -> **注意秒杀价格**：9.9元/月是限时秒杀价，需要抢。常规价不算最便宜，且续费价格比新购高不少。如果你不急，可以等下一波活动。 - -### 腾讯云 (Tencent Cloud) - -四大 IM 全面支持，Coding Plan 模型套餐性价比高。 - -| 项目 | 详情 | -| :--- | :--- | -| **配置** | 推荐 2核4G（黄金配置），最低2核2G 可运行 | -| **价格** | 新人包2核4G约17元/月，一年99元起 | -| **模型** | Coding Plan 首月7.9元起，含HY 2.0 Instruct、GLM-5、kimi-k2.5、MiniMax-M2.5等 | -| **IM 支持** | 企微、QQ、钉钉、飞书（四大IM 全覆盖） | -| **续费** | 支持「限时同价续费」活动，避免续费刺客 | - -1. **购买 Lighthouse 实例**：在腾讯云轻量应用服务器页面购买实例。 -2. **选择 OpenClaw 模板**：应用模板 → AI智能体 → OpenClaw，一键安装。 -3. **配置模型+接入 IM**：购买 Coding Plan 获取模型调用能力，然后接入企微/QQ/飞书/钉钉。 - -### 百度智能云 (Baidu Cloud) - -试错成本最低：0.01元首月体验，全图形界面操作。 - -| 项目 | 详情 | -| :--- | :--- | -| **配置** | 推荐 2核4G 4M带宽（轻量应用服务器） | -| **价格** | 首月体验 0.01元（每日限量500台），常规70~140元/月 | -| **模型** | 千帆平台集成文心系列、Qwen系列、DeepSeek系列 | -| **特色** | 百度搜索/百度百科独有能力；千帆7款官方 Skills 已上线 ClawHub | - -1. **购买服务器**：购买轻量应用服务器，选择 OpenClaw 镜像。 -2. **等待自动安装**：系统自动完成环境安装和服务启动。 -3. **配置模型**：页面选择模型，平台自动完成千帆 API Key 创建与配置。 -4. **对接 IM 渠道**：按需接入钉钉、飞书等消息频道。 - -> **注意** -> 首月 0.01 元优惠每日限量500台，需要抢。续费价格较高（70~140元/月），建议仅作体验使用。 - -### 华为云 (Huawei Cloud) - -企业级安全与合规能力最强，适合已在华为生态的企业用户。 - -| 项目 | 详情 | -| :--- | :--- | -| **配置** | Flexus L实例，需创建弹性公网IP+安全组 | -| **价格** | ~85~155元/月，无特别突出的新用户优惠 | -| **模型** | 需在 MaaS 控制台单独开通 AI 模型 | -| **部署步骤** | 5步+（创建实例→EIP→安全组→安装→配模型） | -| **优势** | 企业级安全合规、支持自动扩展、MaaS 模型丰富 | - -华为云的部署步骤相对较多，需要单独配置弹性公网IP、安全组、COC 服务等。对个人用户不够友好，但如果你的企业已在华为云生态内，这是最合规的选择。 - -### 火山引擎 (Volcengine) - -飞书深度集成，19.8元/月的服务器+模型组合套餐是目前综合性价比最高的方案。 - -| 项目 | 详情 | -| :--- | :--- | -| **配置** | 推荐 2核4G，支持云服务器和云手机两种部署方式 | -| **价格** | 活动价9.9元/月；方舟 Coding Plan 组合套餐 19.8元/月（服务器+模型） | -| **模型** | 方舟平台模型丰富，内置可用 | -| **IM 支持** | 飞书（深度集成）、企微、钉钉、QQ | -| **特色** | 云手机部署方式独特，可运行移动端任务 | - -1. **购买云服务器**：购买云服务器或云手机，选择 OpenClaw 应用模板。 -2. **配置方舟模型**：在火山方舟平台选择模型，配置 Coding Plan。 -3. **接入飞书**：接入飞书/企微/钉钉/QQ。飞书用户推荐直接使用深度集成方案。 - -### 扣子编程 (Coze Code) - -零门槛方案：不需要服务器、不需要写代码、不需要配环境。2步完成部署。 - -| 项目 | 详情 | -| :--- | :--- | -| **配置** | 无需服务器，完全在扣子编程平台上运行 | -| **价格** | 免费起步（内置积分），用完后按量付费 | -| **模型** | 内置豆包2.0+ 火山方舟 Coding Plan 模型，可自由切换 | -| **特色** | 模型、联网搜索、生图 Skill 全部默认配好；扣子编程 Skills 可直接加载 | - -1. **进入扣子编程**：访问 `code.coze.cn`，点击「一键部署 OpenClaw」或从优秀案例创建副本。 -2. **确认部署**：确认后，模型/联网/生图全部默认配置好，部署后持续在线。 - -> **扣子编程的限制**：自定义程度不如自建服务器，不能完全控制底层环境，数据存储在第三方平台。如果你需要深度定制或对数据安全有高要求，建议选择自建方案。 - -### 海外平台 (International Platforms) - -#### Sealos -K8s 原生云平台，支持7天免费试用。通过 Devbox 云开发环境一键部署，按用量计费。适合有容器化需求的开发者，但需要一定的 K8s 知识，且没有专门针对 OpenClaw 的预置模板。 - -#### Zeabur -模板部署，已被部署超过 29,000 次。最大亮点是 AI Hub 内置多模型 failover 链：`glm-4.7-flash → grok-4-fast → minimax-m2.5 → kimi-k2.5 → qwen-3-235b → gpt-5-mini`。主要面向海外/台湾市场，必须使用专用服务器（Dedicated Server）。 - -#### Railway -真正的一键部署，全程浏览器操作。提供 $5/月免费额度，轻度使用可零成本。多种模板可选（标准/快速启动/All-in-One），部署成功率96~100%。海外平台，国内访问需要科学上网。 - -### 按场景推荐 (Recommendations by Scenario) - -| 场景 | 首选 | 备选 | 理由 | -| :--- | :--- | :--- | :--- | -| **零基础想最快体验** | 扣子编程 | 百度云 | 不需要服务器，2步部署，内置模型 | -| **个人长期使用，预算敏感** | 火山引擎 | 阿里云 | 19.8元/月（服务器+模型），综合最划算 | -| **飞书重度用户** | 火山引擎 | 扣子编程 | 同为字节系，飞书深度集成 | -| **企微/QQ 生态** | 腾讯云 | — | 四大IM 原生支持，Coding Plan 7.9元起 | -| **企业级部署，合规优先** | 华为云 | 阿里云 | 安全合规能力最强 | -| **开发者/海外用户** | Railway | Zeabur | 一键部署，免费额度，开发者体验极佳 | - -## 14 首次配置 (Initial Configuration) - -无论哪种部署方式，安装完成后都需要进行首次配置。这里覆盖最关键的几个配置项。 - -### Gateway 认证设置 (Gateway Auth) - -> **注意** -> **v2026.3.7 Breaking Change**: Gateway 认证现在要求显式设置 `gateway.auth.mode`。不设置将导致 Gateway 无法启动。这是为了修复此前暴露在互联网上的 30,000+ 未认证实例的安全隐患。 - -在 `~/.openclaw/workspace` 目录下的配置文件中设置认证模式： - -```yaml -# 选择一种认证模式 -gateway: - auth: - mode: token # 方式一: Token 认证 (推荐用于 API 集成) - # 或 - # mode: password # 方式二: 密码认证 (推荐用于 Web UI 访问) -``` - -### 模型选择与 API Key 配置 (Model & API Key) - -OpenClaw 支持多模型切换，你需要至少配置一个模型的 API Key。常见的选择： - -| 模型来源 | 获取方式 | 说明 | -| :--- | :--- | :--- | -| **阿里云百炼** | 百炼平台申请 | 国内首选，qwen3.5-plus 等模型 | -| **腾讯云 Coding Plan**| 腾讯云购买 | 多模型套餐，首月7.9元 | -| **火山方舟** | 方舟平台申请 | 豆包系列模型 | -| **Anthropic API** | console.anthropic.com | Claude 系列模型，按量付费 | -| **OpenAI API** | platform.openai.com | GPT 系列模型，按量付费 | -| **Ollama (本地)** | 本地安装 Ollama | 免费，需要足够的本地算力 | - -> **核心建议** -> 如果你使用的是国内云厂商的一键部署方案，模型和API Key 通常在购买时已自动配置好。只有本地安装和 Docker 部署才需要手动配置。 - -### 版本更新 (Updates) - -OpenClaw 几乎每天都有新版本发布。使用以下命令更新： - -```bash -# 更新到最新稳定版 (推荐) -openclaw update --channel stable - -# 更新到 Beta 版 (尝鲜) -openclaw update --channel beta - -# 更新到开发版 (最新功能, 可能不稳定) -openclaw update --channel dev -``` - -三个更新渠道的区别： - -| 渠道 | 更新频率 | 稳定性 | 适合人群 | -| :--- | :--- | :--- | :--- | -| **stable** | 每周数次 | 高 | 大多数用户 | -| **beta** | 几乎每天 | 中 | 想尝鲜新功能的用户 | -| **dev** | 持续 | 低 | 开发者、贡献者 | - -### 诊断检查 (Diagnostics) - -安装完成后，运行诊断命令检查环境是否正常： - -```bash -openclaw doctor -``` - -这个命令会检查： -* Node.js 版本是否满足要求 (>= 22) -* 必要的系统依赖是否已安装 -* Gateway 连接是否正常 -* 已配置的模型 API Key 是否有效 -* 守护进程状态 -* 网络连通性 - -如果有任何问题，`openclaw doctor` 会给出具体的修复建议。这是排查问题的第一步。 - -> **推荐版本**：截至2026年3月8日，推荐使用v2026.3.7 稳定版。该版本修复了此前的WebSocket 安全漏洞 (CVE-2026-25253)，并新增了 Context Engine 插件接口、ACP 持久化频道绑定等重要功能。 - ---- - -# Part 4: 渠道接入 (Channel Integration) - -## 15 渠道概览 (Channel Overview) - -OpenClaw 通过 Gateway 架构统一连接 20+ 聊天平台。所有渠道共享同一套三步接入模式：创建凭证 → 写入配置 → 启动 Gateway。 - -### 统一接入流程 - -在平台创建凭证 → 写入 openclaw.yaml → 启动 Gateway → 完成配对 - -可以同时运行多个 channel，消息自动路由到对应平台。配对模式（`dmPolicy: pairing`）默认启用，未知发送者需要验证码才能与 bot 对话。 - -### 完整平台列表 - -| 渠道 | SDK / 实现 | 类型 | 难度 | 耗时 | -| :--- | :--- | :--- | :--- | :--- | -| Telegram | grammY | 内置 | 极简 | 5分钟 | -| Discord | discord.js | 内置 | 简单 | 15-20分钟 | -| WhatsApp | Baileys | 内置 | 中等 | 10-15分钟 | -| Slack | Bolt | 内置 | 中等 | 25-40 分钟 | -| Signal | Signal-CLI | 内置 | 中等 | 20-30分钟 | -| iMessage | BlueBubbles | 扩展 | 中等偏难 | 30-45 分钟 | -| Google Chat | 官方 API | 内置 | 中等 | 15-20分钟 | -| LINE | 官方 API | 扩展 | 中等 | 15-20分钟 | -| Microsoft Teams | 官方 API | 扩展 | 中等 | 20-30 分钟 | -| Matrix | 协议实现 | 扩展 | 中等 | 15-20分钟 | -| Mattermost | 官方 API | 扩展 | 中等 | 15-20分钟 | -| IRC | 协议实现 | 扩展 | 中等 | 10-15 分钟 | -| Nostr | 协议实现 | 扩展 | 中等 | 15-20分钟 | -| Twitch | 官方 API | 扩展 | 中等 | 15-20分钟 | -| Synology Chat | 官方 API | 扩展 | 中等 | 15-20分钟 | -| BlueBubbles | API | 扩展 | 中等偏难 | 30-45 分钟 | -| Zalo | API | 扩展 | 中等 | 15-20分钟 | -| Nextcloud Talk| API | 扩展 | 中等 | 15-20分钟 | -| Tlon | 协议实现 | 扩展 | 中等 | 15-20分钟 | -| QQ | 官方插件 | 插件 | 简单 | 5分钟 | -| 飞书 | 官方 API | 内置插件 | 中等 | 15-20分钟 | -| 钉钉 | 社区插件 | 插件 | 中等 | 20-30分钟 | -| 企业微信 | 社区插件 | 插件 | 中等 | 20-30分钟 | -| 微信(个人) | 社区/第三方 | 插件 | 复杂 | 1小时+ | - -### 新手推荐排序 - -> **从易到难推荐**：Telegram（最简单，5分钟零门槛）→ QQ（国内首选，扫码即用）→ Discord（社区场景佳）→ 飞书（国内企业）→ 钉钉（社区插件成熟）→ WhatsApp（海外日常通讯） - -| 梯队 | 平台 | 推荐理由 | -| :--- | :--- | :--- | -| **第一梯队 (5-10分钟)** | Telegram、QQ | Telegram 不需公网IP、不需反向代理，本地 long-polling 即可运行。QQ有腾讯官方支持，扫码1分钟绑定。 | -| **第二梯队 (15-20分钟)** | Discord、飞书 | Discord 文档齐全，权限设置步骤略多但清晰。飞书自 OpenClaw 2026.2 起内置支持，适合国内企业。 | -| **第三梯队 (25-40分钟)** | WhatsApp、Slack、钉钉、企业微信 | WhatsApp 最受欢迎但 session 可能过期。Slack 权限配置较多。钉钉和企业微信社区插件成熟。 | -| **第四梯队 (需额外条件)** | iMessage、微信个人号 | iMessage 需要 Mac 常开运行 BlueBubbles。微信个人号没有官方 API，封号风险始终存在。 | - -## 16 国际平台接入 (International Platforms) - -本章覆盖六大国际平台的详细接入步骤。每个平台从创建凭证到完成对话的全流程。 - -### Telegram (推荐入门·5分钟·零门槛) - -Telegram 是 OpenClaw 官方推荐的入门渠道。使用 long-polling模式，bot 主动轮询 Telegram 服务器拉取消息，不需要公网IP、反向代理或端口转发。本地开发、NAT 后面、防火墙内都能正常工作。 - -1. **找到 @BotFather** - 在 Telegram 搜索 `@BotFather`，这是 Telegram 官方的 Bot 管理工具。向它发送 `/newbot` 命令。 -2. **创建 Bot** - 按提示设置 bot 的显示名称和 username（必须以 `bot` 结尾，如 `my_openclaw_bot`）。创建成功后，BotFather 会返回一个 Bot Token。 -3. **配置到 OpenClaw** - 将 Token 写入 `openclaw.yaml`： - ```yaml - channels: - telegram: - enabled: true - botToken: "YOUR_BOT_TOKEN" - dmPolicy: pairing # 需配对码才能使用 - ``` -4. **启动并配对** - 重启 Gateway。在 Telegram 中给你的 bot 发送任意消息，Gateway 会返回配对码，输入后即可开始对话。 - -> **核心建议** -> Telegram 的 Bot API 9.5（2026年3月）新增了 `sendMessageDraft` 功能。国内用户需要代理访问 Telegram，但 bot 运行本身不受影响——只要运行 Gateway 的机器能访问 `api.telegram.org` 即可。 - -### Discord (社区场景首选·15-20 分钟) - -Discord 适合社区管理和团队协作场景。需要在 Developer Portal 创建 Application 和 Bot，权限设置步骤稍多但文档齐全。 - -1. **创建 Application** - 前往 `discord.com/developers/applications`，点击 New Application，填写应用名称。 -2. **获取 Bot Token** - 进入 Bot页面，点击 Reset Token，复制生成的 Token。 -3. **启用 Privileged Intents** - 在 Bot 页面开启两个权限：`Message Content Intent` 和 `Server Members Intent`。没有这两个权限 bot 无法读取消息内容。 -4. **邀请 Bot 到服务器** - 在 OAuth2 → URL Generator 中勾选 `bot` scope 和所需权限，生成邀请链接，将 bot 添加到你的 Discord 服务器。 -5. **获取ID 并配置** - 在 Discord 中开启 Developer Mode（设置 → 高级 → 开发者模式），右键复制 Server ID 和你的 User ID。将这些信息写入 `openclaw.yaml`，启动 Gateway。 -6. **DM 配对** - 在 Discord 中私聊你的 bot，输入配对码（1小时有效）完成绑定。 - -> **核心建议** -> v2026.3.7 新增了 ACP 持久化频道绑定——Discord 频道和 Telegram 话题的绑定在 Gateway 重启后依然保持，不需要重新配对。 - -### WhatsApp (日常通讯·10-15 分钟) - -WhatsApp 是 OpenClaw 社区中最受欢迎的渠道。使用 Baileys 库通过 QR 码扫码连接，不需要 WhatsApp Business API。 - -1. **运行交互式向导** - 安装 OpenClaw 后运行 `openclaw onboard`，选择 WhatsApp 渠道。 -2. **扫码配对** - 终端会显示 QR码。打开手机 WhatsApp → 设置 → 已连接设备 → 连接新设备，扫描 QR 码。 -3. **开始使用** - 配对完成后即可在 WhatsApp 中与 bot 对话。 - -> **注意** -> 建议使用独立号码运行 WhatsApp，不要用主号。Gateway 运行时建议用 Node 而非 Bun（Bun 在 WhatsApp 场景下不稳定）。Session 凭证要当密码管理，session 过期需要重新扫码。 - -### Slack (企业/团队场景·25-40 分钟) - -Slack 适合企业和团队内部使用。需要在 Slack API 平台创建 App 并配置多项权限。默认使用 Socket Mode (WebSocket)，不需要公网 URL。 - -1. **创建 Slack App** - 前往 `api.slack.com/apps`，点击 Create New App → From scratch，选择目标 Workspace。 -2. **启用 Socket Mode** - 在 Socket Mode 页面启用，生成 App-Level Token（以 `xapp-` 开头），scope 选择 `connections:write`。 -3. **配置 Bot Token Scopes** - 在 OAuth & Permissions 中添加权限: `chat:write`、`channels:history`、`channels:read`、`im:write`、`im:history`、`im:read`、`users:read`、`reactions:read`、`reactions:write`、`files:write`。 -4. **安装并配置** - 将 App 安装到 Workspace，获取 Bot User OAuth Token（以 `xoxb-` 开头）。将 Token 写入 `openclaw.yaml`，启动 Gateway。 - -> **注意** -> OpenClaw 可以在你的机器上执行真实命令，存在 prompt injection 风险。在 Slack 等多人环境中，建议不要在主力机器上运行 Gateway，使用VM 或专用服务器。 - -### Signal (端到端加密·20-30 分钟) - -Signal 提供端到端加密通讯。OpenClaw 通过 Signal-CLI 工具连接 Signal 网络。 - -1. **安装 Signal-CLI** - 根据操作系统安装 Signal-CLI。macOS 可通过 `brew install signal-cli`，Linux 从 GitHub Releases 下载。 -2. **注册或关联号码** - 使用 `signal-cli register` 注册新号码，或用 `signal-cli link` 关联已有 Signal 账号。 -3. **配置 OpenClaw** - 在 `openclaw.yaml` 中配置 Signal channel，指定号码和 Signal-CLI 路径，启动 Gateway。 - -### iMessage (Apple 生态·30-45 分钟·需要 Mac) - -iMessage 接入通过 BlueBubbles 桥接实现（替代已废弃的 imsg channel）。需要一台常开的 Mac 作为 BlueBubbles Server。 - -1. **安装 BlueBubbles Server** - 在Mac 上从 `bluebubbles.app/install` 下载安装 BlueBubbles Server。推荐 macOS Sequoia (15) 或更新版本。 -2. **启用 Web API** - 在 BlueBubbles Server 设置中启用 Web API，设置访问密码。 -3. **配置 OpenClaw** - 在 `openclaw.yaml` 中配置 BlueBubbles channel: server URL、password、webhook 路径。 - ```yaml - extensions: - bluebubbles: - enabled: true - serverUrl: "http://localhost:1234" - password: "YOUR_PASSWORD" - ``` -4. **配置 Webhook** - 在 BlueBubbles 中添加 webhook 指向 Gateway: `https://gateway-host:3000/bluebubbles-webhook?password=`。webhook 必须设置密码认证。 - -> **注意** -> iMessage 通过 BlueBubbles 支持编辑、撤回、特效和表情回应。但 macOS 26 Tahoe 上编辑功能存在回归 bug (issue #32275)。Mac 必须保持开机运行 BlueBubbles Server。 - -## 17 国内平台接入 (Chinese Platforms) - -国内 IM 生态的 OpenClaw 支持正在快速发展。QQ 和飞书已有官方级支持，钉钉和企业微信社区插件成熟，微信个人号仍是技术挑战。 - -### QQ (国内首选·扫码即用) - -QQ 是国内用户接入 OpenClaw 最简单的方式。腾讯官方开放了 QQ Bot 能力给 OpenClaw，扫码1分钟即可完成绑定。支持 Markdown、图片、语音、文件等多媒体消息，手机QQ和桌面 QQ 均可使用。 - -1. **注册 QQ Bot 开发者** - 用手机QQ扫码完成开发者注册。未实名认证的账号需要先完成实名。单个账号最多创建5个 Bot。 -2. **创建 QQ Bot** - 在QQ开放平台一键创建 Bot，获取 App ID 和 Token。 -3. **配置 OpenClaw** - 在 OpenClaw 运行环境中完成配置绑定，即可在 QQ 上与 bot 对话。 - -> **核心建议** -> QQ Bot 适合两种场景：个人助手（私聊模式）和QQ 社群管理（群聊自动回复、批量处理、定时通知）。 - -### 飞书 (国内企业首选·OpenClaw 2026.2 起内置) - -飞书自 OpenClaw 2026.2 起获得原生内置支持。使用 WebSocket 事件订阅，支持私聊、群聊、照片/文件/视频等多媒体消息。 - -1. **创建飞书应用** - 在飞书开放平台 (`open.feishu.cn`) 创建企业自建应用，获取 App ID 和 App Secret。 -2. **运行向导配置** - 运行 `openclaw onboard`，选择 Feishu channel，粘贴 App ID 和 App Secret。 -3. **重启 Gateway** - 重启 Gateway 后即可在飞书中与 bot 对话。 - -> **社区替代方案**：如果不想用内置插件，AlexAnys/feishu-openclaw 提供独立 bridge，不需要公网服务器、域名或ngrok，5分钟即可部署。AlexAnys/openclaw-feishu 仓库有保姆级配置指南，含 API 耗尽排查和 Lark Webhook 内网穿透方案。 - -### 钉钉 (社区插件·Stream 模式免公网) - -钉钉通过社区插件接入 OpenClaw。消息接收使用 Stream 模式（WebSocket 长连接），不需要公网地址。支持私聊、群聊、文件附件、语音消息、钉钉文档 API、多 Agent 路由等功能。 - -1. **创建钉钉应用** - 在钉钉开放平台创建应用，添加机器人能力。 -2. **设置 Stream 模式** - 将消息接收模式设置为 Stream 模式。这样 bot 通过 WebSocket 长连接接收消息，不需要配置公网回调地址。 -3. **安装插件并配置** - 安装社区插件 `@soimy/dingtalk`，或使用 DingTalk-Real-AI 官方出品的 `dingtalk-openclaw-connector`（支持 AI Card 流式响应）。配置 `openclaw.yaml` 后启动 Gateway。 - -> **核心建议** -> 钉钉尚未获得 OpenClaw 官方内置支持（2026年3月有 Feature Request 提出），但社区方案已经非常成熟。DingTalk-Real-AI 连接器由钉钉团队维护，可靠性有保障。 - -### 企业微信 (两种模式·已被多家云平台验证) - -企业微信有两种接入模式：Agent 模式（XML 回调经典模式）和 Bot 模式（JSON 回调，原生 stream 支持）。已被腾讯云、火山引擎、天翼云等公有云平台采纳验证。 - -1. **创建企业微信应用** - 在企业微信管理后台创建自建应用（Agent 模式）或配置智能机器人（Bot 模式）。 -2. **安装社区插件** - 可选插件：`dingxiang-me/OpenClaw-Wechat`（支持个人微信互通、流式输出、群聊@、白名单控制、全中文配置）或 `sunnoy/openclaw-plugin-wecom`（支持动态 Agent 管理、指令白名单）。 -3. **配置并启动** - 按插件文档配置 `openclaw.yaml`，启动 Gateway。要求 OpenClaw ≥ 2026.2.9，部分功能需 ≥ 2026.3.2。 - -### 微信个人号 (需求最大但最复杂) - -个人微信没有官方 Bot API，所有方案都是非官方的，封号风险始终存在。以下三种方案各有局限。 - -- **方案A：企业微信中转 (推荐)** - 通过企业微信接入 OpenClaw，再用微信插件打通企业微信和个人微信。合法合规，在微信生态内，需要企业微信管理后台权限。 - -- **方案B：iPad 协议 + 中转网关** - 不走 Web 协议（高风险封号），走 iPad 协议。稳定性更高但技术门槛也更高。社区项目：`freestylefly/openclaw-wechat`、`laolin5564/openclaw-wechat`。 - -- **方案C：微信小程序** - 2026年新方案，通过小程序对接 OpenClaw。阿里云/腾讯云有预置镜像，降低部署门槛。 - -> **注意** -> 个人微信的所有接入方案都需要持续维护——协议更新可能导致不可用，iPad 协议相对安全但不是零风险。建议不要用常用的主号，使用备用号测试。云端部署才能保证24小时在线。 - -### openclaw-china 统一插件 (一站式国内平台支持) - -BytePioneer-AI/openclaw-china 提供一站式国内平台支持，覆盖飞书、钉钉、QQ、企业微信、微信五个平台。 - -```bash -git clone https://github.com/BytePioneer-AI/openclaw-china.git -cd openclaw-china -pnpm install && pnpm build -openclaw china setup # 交互式配置向导 -``` - -特色功能包括：交互式配置向导减少手动配置、企业微信 MP4 视频播放器和多文件类型发送、腾讯云 ASR 语音转文字、钉钉日志增强（userId/groupId 定位问题）。 - -> **选择建议**：如果只用一个国内平台，直接安装对应的独立插件更轻量。如果要同时接入多个国内平台，openclaw-china 统一包更省事。 - -## 18 远程访问 (Remote Access) - -OpenClaw Gateway 默认监听本地 `ws://127.0.0.1:18789`。当你需要从外部网络访问时，有以下几种方案。 - -### Tailscale Serve / Funnel (推荐方案) - -Tailscale 是 OpenClaw 官方推荐的远程访问方案，提供两种模式： - -| 模式 | 访问范围 | 使用场景 | -| :--- | :--- | :--- | -| **Serve** | Tailscale 网络内的设备 | 自己的手机/平板访问家里的 OpenClaw | -| **Funnel**| 公网任何人 | 给 webhook 回调提供公网 URL（如飞书、Slack HTTP 模式） | - -```bash -# Serve: 仅 Tailscale 网络可访问 -tailscale serve --bg https+insecure://127.0.0.1:18789 - -# Funnel: 公网可访问 (用于 webhook 回调) -tailscale funnel --bg https+insecure://127.0.0.1:18789 -``` - -> **核心建议** -> 大部分 channel（Telegram long-polling、Discord、Slack Socket Mode、钉钉 Stream 模式）都是 bot 主动连接服务器，不需要公网IP。只有需要 webhook 回调的场景（BlueBubbles、Slack HTTP 模式）才需要 Funnel 暴露公网地址。 - -### SSH 端口转发 (最通用的方案) - -如果 OpenClaw 运行在远程服务器上，用 SSH 隧道将 Gateway 端口转发到本地： - -```bash -# 将远程服务器的 18789 端口转发到本地 -ssh -L 18789:127.0.0.1:18789 user@your-server - -# 后台运行 -ssh -fNL 18789:127.0.0.1:18789 user@your-server -``` - -转发后，本地客户端连接 `ws://127.0.0.1:18789` 即可访问远程 Gateway。 - -### Dashboard Web UI - -OpenClaw 内置 Web UI，启动 Gateway 后可在浏览器中访问管理界面。Web UI 支持查看会话状态、模型配置、channel 连接状况、Token 用量统计等。v2026.3.7 新增了西班牙语支持。 - -```bash -# Gateway 启动后默认可访问 -# 浏览器打开 http://127.0.0.1:18789 -openclaw gateway --port 18789 --verbose -``` -> **安全提醒**：v2026.3.7 起 Gateway 认证要求显式设置 `gateway.auth.mode` (token 或 password)。不要在公网暴露未认证的 Gateway。 - -### macOS 菜单栏伴侣应用 - -OpenClaw 提供 macOS 原生客户端（`apps/macos/`），以菜单栏常驻应用的形式运行。功能包括： - -* 一键启动/停止 Gateway -* 查看当前连接的 channel 状态 -* 快速访问 Dashboard Web UI -* 系统通知（新消息、配对请求等） - -iOS 和Android 客户端也在开发中（`apps/ios/`、`apps/android/`），代码已在主仓库中。 - -> **核心建议** -> 如果你同时使用多台设备，推荐 Tailscale Serve + macOS 菜单栏应用的组合：Mac 运行 Gateway 和菜单栏应用，手机/平板通过 Tailscale 网络访问。 - ---- -... -[Due to token limits, the full conversion of all 98 pages is truncated. The provided text demonstrates the applied methodology, structure, and adherence to all constraints for the initial sections of the document. The process would be continued in the same manner for all subsequent pages.] -... - -## C 资源链接 (Resource Links) - -### 官方资源 - -| 资源 | 地址 | -| :--- | :--- | -| **GitHub仓库** | `github.com/openclaw/openclaw` | -| **官方文档** | `docs.openclaw.ai` | -| **官网** | `openclaw.ai` | -| **ClawHub技能市场** | `clawhub.ai` | -| **Moltbook (Agent社交网络)** | `moltbook.com` | -| **GitHub Releases** | `github.com/openclaw/openclaw/releases` | -| **GitHub Discussions**| `github.com/openclaw/openclaw/discussions` | - -### 社区资源 - -| 资源 | 地址 | 说明 | -| :--- | :--- | :--- | -| **awesome-openclaw-skills** | `github.com/VoltAgent/awesome-openclaw-skills` | 5,494个精选Skill (已过滤问题Skill), 31.4K Stars | -| **awesome-openclaw-usecases**| `github.com/hesamsheikh/awesome-openclaw-usecases` | 社区用例合集, 21K Stars | -| **openclaw-claude-code-skill** | `github.com/Enderfga/openclaw-claude-code-skill` | 桥接Claude Code能力 | -| **SecureClaw** | 开源安全工具 | Skill安全扫描 | - -### 国内资源 - -| 资源 | 地址 | 说明 | -| :--- | :--- | :--- | -| **openclaw-china插件** | `github.com/BytePioneer-Al/openclaw-china` | 钉钉/QQ/企微/微信接入 | -| **OpenClaw中文文档** | `openclaw.cc` | 社区维护的中文文档 | -| **阿里云部署文档** | `help.aliyun.com` (搜索OpenClaw) | 轻量应用服务器一键部署 | -| **B站部署教程** | `BV1MfFAz6EnR` | 保姆级: 接入微信/飞书/钉钉/QQ | - -### 教程资源 - -| 资源 | 语言 | 说明 | -| :--- | :--- | :--- | -| **freeCodeCamp完整教程** | 英文 | 从零开始的完整指南 | -| **DigitalOcean介绍** | 英文 | What is OpenClaw概述 | -| **知乎部署系列** | 中文 | 多篇部署和使用教程 | -| **博客园源码编译指南** | 中文 | 从源码构建OpenClaw | -| **菜鸟教程一键部署** | 中文 | 最简部署方案 | - -### 模型提供商 - -| 提供商 | API控制台 | -| :--- | :--- | -| **Anthropic Claude** | `console.anthropic.com` | -| **OpenAI** | `platform.openai.com` | -| **Google AI Studio** | `aistudio.google.com` | -| **DeepSeek** | `platform.deepseek.com` | -| **智谱GLM** | `bigmodel.cn` | -| **通义千问** | `dashscope.aliyun.com` | -| **月之暗面Kimi** | `platform.moonshot.cn` | -| **硅基流动** | `siliconflow.cn` | -| **OpenRouter** | `openrouter.ai` | -| **火山引擎 (豆包)** | `console.volcengine.com` | - ---- -本文档在 Claude Code 辅助下整理编写，基于OpenClaw 官方文档、GitHub 仓库及社区资料。 -内容的准确性与时效性仅供参考，如有勘误或建议，欢迎关注公众号「花叔」反馈交流。 -来源: `docs.openclaw.ai` • `github.com/openclaw/openclaw` • `clawhub.com` • Created by 花叔 • 2026年3月 \ No newline at end of file diff --git a/docs/case-studies/openclaw-dev/README.md b/docs/case-studies/openclaw-dev/README.md deleted file mode 100644 index f5dc69b..0000000 --- a/docs/case-studies/openclaw-dev/README.md +++ /dev/null @@ -1,8 +0,0 @@ -# OpenClaw 实战资料 - -> OpenClaw（开源自托管 AI Agent 系统）相关的调研、架构与部署一站式资料归档。 - -## 文档 - -- `OpenClaw 橙皮书 - AI进化论花生.md`：从入门到精通的参考手册（架构、部署、渠道接入、Skills、模型配置、安全与成本）。 - diff --git a/docs/case-studies/polymarket-dev/POLYMARKET_LINK_FORMAT.md b/docs/case-studies/polymarket-dev/POLYMARKET_LINK_FORMAT.md deleted file mode 100644 index 9a61d04..0000000 --- a/docs/case-studies/polymarket-dev/POLYMARKET_LINK_FORMAT.md +++ /dev/null @@ -1,99 +0,0 @@ -# Polymarket 链接格式规范 - -## 问题描述 - -生成的 Polymarket 链接返回 "Oops...we didn't forecast this" 错误页面，即使 HTTP 状态码是 200。 - -## 根本原因 - -Polymarket API 返回两种不同的 slug： - -| 字段 | 名称 | 用途 | -|------|------|------| -| `slug` | Market Slug | 市场标识，**不能用于 URL** | -| `events[0].slug` | Event Slug | 事件标识，**必须用于 URL** | - -### 示例对比 - -``` -市场: "Lighter market cap (FDV) >$1B one day after launch?" - -API 返回: - slug: "lighter-market-cap-fdv-1b-one-day-after-launch" ❌ 错误 - events[0].slug: "lighter-market-cap-fdv-one-day-after-launch" ✅ 正确 - -错误链接: https://polymarket.com/event/lighter-market-cap-fdv-1b-one-day-after-launch -正确链接: https://polymarket.com/event/lighter-market-cap-fdv-one-day-after-launch -``` - -注意差异：market slug 包含 `-1b-`，event slug 不包含。 - -## 为什么 HTTP 200 但页面报错？ - -Polymarket 前端是 SPA（单页应用）： -- 所有 `/event/*` 路径都返回 HTTP 200（返回 HTML 壳） -- 前端 JS 加载后再请求数据 -- 如果 slug 无效，前端显示 "Oops" 错误 - -**结论：HTTP 状态码无法验证链接有效性。** - -## 正确的链接生成方式 - -```javascript -// ✅ 正确 -const getLink = (market) => { - const events = market.events || []; - const slug = events[0]?.slug || market.slug; // 优先用 event slug - return `https://polymarket.com/event/${slug}`; -}; - -// ❌ 错误 -const getLink = (market) => { - return `https://polymarket.com/event/${market.slug}`; -}; -``` - -## API 响应结构 - -```json -{ - "question": "Lighter market cap (FDV) >$1B one day after launch?", - "slug": "lighter-market-cap-fdv-1b-one-day-after-launch", - "events": [ - { - "slug": "lighter-market-cap-fdv-one-day-after-launch", - "title": "Lighter Market Cap (FDV) One Day After Launch" - } - ] -} -``` - -## 验证方法 - -不能只检查 HTTP 状态码，需要： - -```bash -# 方法1：检查页面内容是否包含错误 -curl -s "https://polymarket.com/event/xxx" | grep -q "didn't forecast" && echo "无效" - -# 方法2：对比 API 返回的 slug -curl -s "https://gamma-api.polymarket.com/markets?slug=xxx" | jq '.events[0].slug' -``` - -## 受影响的文件 - -修复时需检查以下文件中的链接生成逻辑： - -- `scripts/csv-report-api.js` -- `scripts/csv-report.js` -- `signals/*/formatter.js`（如有生成链接） - -## 修复记录 - -- **日期**: 2024-12-31 -- **问题**: csv-report-api.js 使用 `m.slug` 生成链接 -- **修复**: 改为 `m.events[0]?.slug || m.slug` - ---- - -**规则：任何生成 Polymarket 链接的代码，必须使用 `events[0].slug`，不能使用 `slug`。** diff --git a/docs/case-studies/polymarket-dev/Polymarket 套利全解析.md b/docs/case-studies/polymarket-dev/Polymarket 套利全解析.md deleted file mode 100644 index ef8ed20..0000000 --- a/docs/case-studies/polymarket-dev/Polymarket 套利全解析.md +++ /dev/null @@ -1,91 +0,0 @@ -# 稳赚不赔的秘密：Polymarket 套利全解析 - -## 您交易的是两种资产：YES 与 NO 股份 - -在 Polymarket 中，您交易的内容主要分为两类： - -1. 如果事件发生 (YES) -您持有的每 1 股 YES 将在结算时兑换为 1 美元。 - -2. 如果事件未发生 (NO) -您持有的每 1 股 NO 将在结算时兑换为 1 美元。 - -核心规则：猜对的一方，其股份价值归于 $1；猜错的一方，股份价值归零。 - -## 理论上的铁律：系统设计的完美平衡 - -YES 股价格 + NO 股价格 = 1 美元 - -这是系统内在的数学平衡，也是一切套利逻辑的基石。 -例如：如果 YES 股的市场价格为 $0.60，那么 NO 股的理论价格必须是 $0.40。 - -## 理论很完美，但现实是……价格由全球用户交易产生 - -真实世界中，价格并非由公式设定，而是由全球交易者的行为（情绪、信息差、策略）共同决定。这导致了理论平衡被频繁打破。 - -### YES 股价格 + NO 股价格 ≠ 1 美元 - -这种不平衡，我们称之为“价格错位” (Price Dislocation)。 - -## 套利机会：当总价不等于 1 美元 - -当市场交易导致总价偏离 1 美元时，就产生了无风险的获利空间。 - -### 1. 情绪化下单 (Emotional Buying) - -市场出现突发消息，有交易者冲动地大量买入 YES，导致其价格飙升。 - -不平衡状态 (The Imbalance)： -0.60 (YES) + 0.35 (NO) = $0.95 (比 1 美元少了 $0.05) - -套利操作 (The Arbitrage Play)： -* 行动：同时买入 1 股 YES 和 1 股 NO。 -* 成本：$0.95 -* 结果：无论最终事件发生与否，您的这套股票都将结算为 $1.00。 -* 收益：每套稳定获利 $0.05 (约 5.2% 回报)。 - -### 2. 全球时差反应 (Global Time Lag) - -美国凌晨发布重大新闻，美国交易员迅速反应，买爆 YES；而亚洲交易员仍在睡梦中， NO 的价格未能同步更新。 - -不平衡状态 (The Imbalance)： -0.70 (YES) + 0.33 (NO) = $1.03 (比 1 美元多了 $0.03) - -套利操作 (The Arbitrage Play)： -* 行动：反向操作，同时卖出 1 股 YES 和 1 股 NO。 -* 收入：$1.03 -* 结果：您只需在结算时归还 $1.00。 -* 收益：瞬间锁定 $0.03 利润 (约 2.9% 回报)。 - -### 3. 低流动性 + 大单砸盘 (Low Liquidity + Large Orders) - -在许多交易量较小的事件中，一笔数万美元的大额卖单就能瞬间将 YES 价格砸穿，而 NO 的价格来不及反应。 - -不平衡状态 (The Imbalance)： -0.45 (YES) + 0.50 (NO) = $0.95 (比 1 美元少了 $0.05) - -套利操作 (The Arbitrage Play)： -* 行动：监控机器人程序化买入被砸盘的资产组合。 -* 成本：$0.95 -* 结果：等待市场价格恢复或持有至结算，获得 $1.00。 -* 收益：机器人捕捉 5.2% 的瞬间利润。 - -### 4. 跨平台价格差 (Cross-Platform Spreads) - -同一个事件在不同的预测平台（如 Polymarket 和 Kalshi）上，由于用户群体和流动性不同，价格出现差异。 - -不平衡状态 (The Imbalance)： -* Polymarket: YES $0.80 / NO $0.20 (买入 NO) -* Kalshi: YES $0.75 / NO $0.25 (买入 YES) - -套利操作 (The Arbitrage Play)： -* 行动：在 Polymarket 买入更便宜的 NO ($0.20)，同时在 Kalshi 买入更便宜的 YES ($0.75)。 -* 总成本：$0.20 + $0.75 = $0.95 -* 结果：您完整覆盖了所有结果，这套跨平台资产组合必定结算为 $1.00。 -* 收益：锁定 5.2% 的跨市场无风险利润。 - -## 总结：躺赚背后的游戏规则 - -理解 Polymarket 套利的核心，不是为了亲自下场与机器人赛跑，而是为了洞悉任何一个市场都存在的共性：效率总是在与人性（非理性）的博弈中产生。 - -您看到的每一个价格，背后都有一场博弈。现在，您能看到那场博弈了。 \ No newline at end of file diff --git a/docs/case-studies/polymarket-dev/README.md b/docs/case-studies/polymarket-dev/README.md deleted file mode 100644 index 4ef09b0..0000000 --- a/docs/case-studies/polymarket-dev/README.md +++ /dev/null @@ -1,25 +0,0 @@ -# 📊 polymarket-dev - -> Polymarket 数据分析与可视化实战经验 - -## 项目背景 - -Polymarket 预测市场数据的采集、分析和可视化，包含 K 线图 ASCII 渲染、胶水代码开发等。 - -## 文档列表 - -| 文件 | 说明 | -|:---|:---| -| [ascii可视化-prompt.md](ascii可视化-prompt.md) | ASCII 字符绘制 K 线图的提示词 | -| [prompt-system-bazi-kline.md](../fate-engine-dev/prompt-system-bazi-kline.md) | 系统提示词：K 线分析 | -| [prompt-user-bazi-kline.md](../fate-engine-dev/prompt-user-bazi-kline.md) | 用户提示词：K 线分析 | -| [胶水开发要求-prompt.md](胶水开发要求-prompt.md) | 胶水代码开发规范提示词 | -| [完整性检查-prompt.md](完整性检查-prompt.md) | 代码完整性检查提示词 | -| [复查-prompt.md](复查-prompt.md) | 代码复查提示词 | -| [问题描述-prompt.md](问题描述-prompt.md) | 问题描述模板提示词 | - -## 技术栈 - -- Python -- Polymarket API -- ASCII 可视化 diff --git a/docs/case-studies/polymarket-dev/ascii可视化-prompt.md b/docs/case-studies/polymarket-dev/ascii可视化-prompt.md deleted file mode 100644 index 052edfe..0000000 --- a/docs/case-studies/polymarket-dev/ascii可视化-prompt.md +++ /dev/null @@ -1 +0,0 @@ -# 任务说明：指定项目仓库的系统分析与可视化建模## 角色设定你是一名 **资深软件架构师 / 系统分析专家**，具备从实际代码仓库中进行架构逆向分析、系统抽象与技术文档生成的能力。## 分析对象- **分析对象不是预设的“微服务系统”概念**- 分析对象为：**我指定的项目代码仓库**- 项目形态可能包括（但不限于）： - 单体应用 - 微服务架构 - 模块化系统 - 混合架构（单体 + 服务化）- 你需要基于 **真实仓库结构与代码事实** 判断其架构形态，而不是先验假设## 总体目标对该 **指定项目仓库** 进行系统级分析，并生成 **基于 ASCII 字符渲染的可视化图表**，用于理解系统结构与运行流程。## 分析任务要求### 1. 系统与架构识别- 从仓库中识别： - 模块 / 服务 / 子系统边界 - 各组件的核心职责- 判断并说明： - 架构风格（如单体、微服务、分层架构、事件驱动等） - 组件之间的依赖关系与调用方式- 不对架构类型作任何未经证据支持的假设### 2. 关键流程分析- 选取 **具有代表性的核心业务流程或系统主流程**- 明确： - 调用起点与终点 - 中间参与的模块 / 服务 /组件 - 同步与异步交互关系（若存在）## 可视化产出要求（ASCII）### 3. 序列图（Sequence Diagram）- 基于实际代码与调用关系绘制- 展示： - 调用顺序 - 请求 / 响应方向 - 参与的模块、服务或组件- 使用 **纯 ASCII 字符**- 保证在等宽字体环境下对齐、可读- 不引入任何外部绘图语法（如 Mermaid、PlantUML）### 4. 系统结构图（System / Architecture Diagram）- 从整体视角展示系统组成： - 模块 / 服务 - 外部依赖（如数据库、消息队列、第三方 API） - 基础设施组件（如有）- 明确逻辑分层或物理边界（若可识别）- 使用 **纯 ASCII 字符**，强调结构与关系的清晰性## 文件输出规范- 序列图与系统图 **必须分别独立输出为文件**- 保存位置：**项目根目录**- 推荐文件名（可根据项目实际调整）： - `sequence_diagram.txt` - `system_architecture.txt`- 每个文件中 **只包含对应的 ASCII 图表内容**- 不在文件中混入解释性说明文字## 表达与风格要求- 使用 **专业、严谨的技术文档语言**- 描述基于代码事实，不进行推测性扩展- 若存在信息不足之处，需明确标注为： -「基于当前仓库可见信息的假设」## 约束条件- 禁止使用图片、截图或富文本图形- 禁止使用 Markdown 图表或任何非 ASCII 表达- 所有图表必须可直接保存、可长期维护、可用于代码仓库## 最终目标输出一套 **严格基于指定项目仓库的系统级 ASCII 可视化成果**，用于帮助开发者、审阅者或维护者快速、准确地理解该项目的结构与运行逻辑。 \ No newline at end of file diff --git a/docs/case-studies/polymarket-dev/复查-prompt.md b/docs/case-studies/polymarket-dev/复查-prompt.md deleted file mode 100644 index af64efc..0000000 --- a/docs/case-studies/polymarket-dev/复查-prompt.md +++ /dev/null @@ -1 +0,0 @@ -# 角色设定你是一名**专业级命理系统开发与校验专家**，同时具备**软件需求分析、规则校验与一次性计算设计能力**。---# 任务目标请根据 **OI 文档（输入 / 输出规范文档）**，完成一套**完整、严谨、零删减（0 阉割）**的命理分析处理流程设计与执行说明，确保系统**一次输入、一次计算、一次完整输出**。---# 核心要求## 一、输入检查（开发检查要求）1. **严格对照 OI 文档** - 仅以 OI 文档中定义的字段、类型、格式、约束为准 - 不允许自行增减字段或弱化校验规则 2. **基础命理分析所需数据校验** - 检查用户输入是否满足命理计算的最小完备条件 - 明确列出： - 必填字段 - 可选字段 - 默认值规则 - 非法输入与异常处理方式 3. **一次性输入原则** - 所有数据必须在**单次输入**中完成采集 - 不允许多轮补充询问或中途回填 ---## 二、计算逻辑要求1. **一次性完整计算** - 在输入校验通过后，**一次性完成全部命理计算** - 禁止分阶段、分模块二次计算 2. **计算范围** - 基础排盘计算（如八字 / 命盘 / 时间结构等，按 OI 文档定义） - 所有衍生分析模块 - 所有关联功能与扩展功能（不省略、不简化）3. **计算一致性** - 同一输入在任何时间、任何环境下应得到一致结果 - 明确计算顺序与依赖关系 ---## 三、输出要求（重点）1. **完整排版输出** - 输出为**一份结构完整、排版清晰、可直接交付用户的最终文档** - 不输出中间结果、不输出调试信息 2. **输出内容必须包含** - 完整命理排盘（所有盘位、结构、标注） - 所有分析结论 - 所有功能模块的完整结果说明 - 必要的字段解释与含义说明（按 OI 文档）3. **0 阉割原则** - 不得因“简化”“可读性”“模型限制”等理由省略任何模块 - 不得输出“略”“省略”“后续可扩展”等占位描述 ---## 四、结构化与模型执行规范1. **强结构化输出** - 使用清晰的标题层级（如：一级 / 二级 / 三级标题） - 使用列表、表格或分段说明增强可读性 2. **模型稳定性要求** - 指令明确、无歧义 - 禁止自由发挥、主观补充或脱离 OI 文档的内容 3. **最终交付标准** - 输出结果应满足： - 可直接作为产品功能说明文档 - 可直接作为用户最终查看版本 - 可直接作为开发与测试对照依据 ---# 输出形式约束- **仅输出最终完整文档内容**- 不解释你的思考过程- 不附加额外说明 \ No newline at end of file diff --git a/docs/case-studies/polymarket-dev/完整性检查-prompt.md b/docs/case-studies/polymarket-dev/完整性检查-prompt.md deleted file mode 100644 index 4ede42b..0000000 --- a/docs/case-studies/polymarket-dev/完整性检查-prompt.md +++ /dev/null @@ -1 +0,0 @@ -"# 系统性代码与功能完整性检查提示词（优化版）## 角色设定你是一名**资深系统架构师与代码审计专家**，具备对生产级 Python 项目进行深度静态与逻辑审查的能力。## 核心目标对当前代码与工程结构进行**系统性、全面、可验证的检查**，确认以下所有条件均被严格满足，不允许任何形式的功能弱化、裁剪或替代实现。---## 检查范围与要求### 一、功能完整性验证- 确认**所有功能模块均为完整实现** - 不存在： - 阉割逻辑 - Mock / Stub 替代 - Demo 级或简化实现- 确保行为与**生产环境成熟版本**完全一致---### 二、代码复用与集成一致性- 验证是否： - **100% 复用既有成熟代码** - 未发生任何形式的重新实现或功能折叠- 确认当前工程是**直接集成**，而非复制后修改的版本---### 三、本地库调用真实性检查重点核查以下导入链路是否真实、完整、生效：pythonsys.path.append('/home/lenovo/.projects/fate-engine/libs/external/github/*')from datas import * # 必须为完整数据模块from sizi import summarys # 必须为完整算法实现要求：* `sys.path` 引入路径真实存在且指向**生产级本地库*** `datas` 模块： * 包含全部数据结构、接口与实现 * 非裁剪版 / 非子集* `sizi.summarys`： * 为完整算法逻辑 * 不允许降级、参数简化或逻辑跳过---### 四、导入与执行有效性* 确认： * 所有导入模块在运行期**真实参与执行** * 不存在“只导入不用”“接口空实现”等伪集成情况* 检查是否存在： * 路径遮蔽（shadowing） * 重名模块误导加载 * 隐式 fallback 到简化版本---## 输出要求请以**审计报告**形式输出，至少包含：1. 检查结论（是否完全符合生产级完整性）2. 每一项检查的明确判断（通过 / 不通过）3. 若存在问题，指出： * 具体模块 * 风险等级 * 可能造成的后果**禁止模糊判断与主观推测，所有结论必须基于可验证的代码与路径分析。**" \ No newline at end of file diff --git a/docs/case-studies/polymarket-dev/胶水开发要求-prompt.md b/docs/case-studies/polymarket-dev/胶水开发要求-prompt.md deleted file mode 100644 index 3042baa..0000000 --- a/docs/case-studies/polymarket-dev/胶水开发要求-prompt.md +++ /dev/null @@ -1 +0,0 @@ -# 胶水开发要求（强依赖复用 / 生产级库直连模式）## 角色设定你是一名**资深软件架构师与高级工程开发者**，擅长在复杂系统中通过强依赖复用成熟代码来构建稳定、可维护的工程。## 总体开发原则本项目采用**强依赖复用的开发模式**。核心目标是： **尽可能减少自行实现的底层与通用逻辑，优先、直接、完整地复用既有成熟仓库与库代码，仅在必要时编写最小业务层与调度代码。**---## 依赖与仓库使用要求### 一、依赖来源与形式- 允许并支持以下依赖集成方式： - 本地源码直连（`sys.path` / 本地路径） - 包管理器安装（`pip` / `conda` / editable install）- 无论采用哪种方式，**实际加载与执行的必须是完整、生产级实现**，而非简化、裁剪或替代版本。---### 二、强制依赖路径与导入规范在代码中，必须遵循以下依赖结构与导入形式（示例）：```pythonsys.path.append('/home/lenovo/.projects/fate-engine/libs/external/github/*')from datas import * # 完整数据模块，禁止子集封装from sizi import summarys # 完整算法实现，禁止简化逻辑```要求：* 指定路径必须真实存在并指向**完整仓库源码*** 禁止复制代码到当前项目后再修改使用* 禁止对依赖模块进行功能裁剪、逻辑重写或降级封装---## 功能与实现约束### 三、功能完整性约束* 所有被调用的能力必须来自依赖库的**真实实现*** 不允许： * Mock / Stub * Demo / 示例代码替代 * “先占位、后实现”的空逻辑* 若依赖库已提供功能，**禁止自行重写同类逻辑**---### 四、当前项目的职责边界当前项目仅允许承担以下角色：* 业务流程编排（Orchestration）* 模块组合与调度* 参数配置与调用组织* 输入输出适配（不改变核心语义）明确禁止：* 重复实现算法* 重写已有数据结构* 将复杂逻辑从依赖库中“拆出来自己写”---## 工程一致性与可验证性### 五、执行与可验证要求* 所有导入模块必须在运行期真实参与执行* 禁止“只导入不用”的伪集成* 禁止因路径遮蔽、重名模块导致加载到非目标实现---## 输出要求（对 AI 的约束）在生成代码时，你必须：1. 明确标注哪些功能来自外部依赖2. 不生成依赖库内部的实现代码3. 仅生成最小必要的胶水代码与业务逻辑4. 假设依赖库是权威且不可修改的黑箱实现**本项目评价标准不是“写了多少代码”，而是“是否正确、完整地站在成熟系统之上构建新系统”。**你需要处理的是： \ No newline at end of file diff --git a/docs/case-studies/polymarket-dev/问题描述-prompt.md b/docs/case-studies/polymarket-dev/问题描述-prompt.md deleted file mode 100644 index 2b5d5be..0000000 --- a/docs/case-studies/polymarket-dev/问题描述-prompt.md +++ /dev/null @@ -1 +0,0 @@ -# 任务说明（System Prompt）你是一名**高级软件架构顾问与技术问题分析专家**。 你的任务是：**对当前代码项目中遇到的问题进行系统性、结构化、可诊断的完整描述**，以便后续进行高质量的技术分析、调试、重构或方案设计。---## 输出目标请基于我提供的信息，**完整、清晰、无歧义地整理并呈现项目现状**，确保任何第三方技术人员或大型语言模型都可以在**无需额外追问**的情况下理解问题全貌。---## 输出内容结构（必须严格遵循）请按照以下固定结构输出内容：### 1. 项目背景（Background）- 项目整体目标与业务场景- 项目当前所处阶段（开发中 / 测试中 / 生产环境 / 重构阶段等）- 该问题在项目中的重要性与影响范围### 2. 技术上下文（Technical Context）- 使用的编程语言、框架、运行环境- 架构形态（单体 / 微服务 / 前后端分离 / 本地 + 云等）- 相关依赖、第三方服务或基础设施（如数据库、消息队列、API、云服务）### 3. 核心问题描述（Problem Description）- 问题的**具体表现**（错误信息、异常行为、性能问题、逻辑错误等）- 问题出现的**触发条件**- 预期行为 vs 实际行为（对比说明）- 是否具备稳定复现路径### 4. 相关实体（Entities）- 涉及的核心模块 / 类 / 函数 / 文件- 关键数据结构或业务对象- 相关角色（如用户、服务、进程、线程等）### 5. 相关链接与参考资料（References）- 代码仓库链接（如 GitHub / GitLab）- 相关 issue、PR、文档或设计说明- 外部参考资料（API 文档、官方说明、技术文章等）### 6. 功能与目的（Function & Intent）- 该代码或模块原本设计要实现的功能- 当前问题阻碍或偏离了哪些目标- 从业务与技术角度说明“为什么这个问题必须被解决”---## 表达与格式要求- 使用**技术性、客观、精确**的语言，避免情绪化或模糊表述 - 尽量使用**条列（bullet points）与短段落**，避免大段散文 - 不要提出解决方案，只做**问题与上下文的完整建模**- 不要省略你认为“显而易见”的信息，假设读者**对项目完全陌生**---## 最终目标你的输出将作为：- 技术问题分析输入- Debug / 架构评审 / AI 辅助分析的上下文- 后续自动化推理或方案生成的**唯一事实来源**请严格按照上述结构与要求输出。 \ No newline at end of file diff --git a/docs/case-studies/telegram-dev/README.md b/docs/case-studies/telegram-dev/README.md deleted file mode 100644 index fdbedf6..0000000 --- a/docs/case-studies/telegram-dev/README.md +++ /dev/null @@ -1,19 +0,0 @@ -# 🤖 telegram-dev - -> Telegram Bot 开发实战经验 - -## 项目背景 - -Telegram Bot 开发中遇到的问题和解决方案，主要涉及消息格式、Markdown 渲染等。 - -## 文档列表 - -| 文件 | 说明 | -|:---|:---| -| [telegram Markdown 代码块格式修复记录 2025-12-15.md](telegram%20Markdown%20代码块格式修复记录%202025-12-15.md) | Telegram Markdown 代码块渲染问题修复 | - -## 技术栈 - -- Python -- python-telegram-bot -- Telegram Bot API diff --git a/docs/case-studies/telegram-dev/telegram Markdown 代码块格式修复记录 2025-12-15.md b/docs/case-studies/telegram-dev/telegram Markdown 代码块格式修复记录 2025-12-15.md deleted file mode 100644 index d5317af..0000000 --- a/docs/case-studies/telegram-dev/telegram Markdown 代码块格式修复记录 2025-12-15.md +++ /dev/null @@ -1,41 +0,0 @@ -# telegram Markdown 代码块格式修复记录 2025-12-15 - -## 问题 - -排盘完成后发送消息报错： -``` -❌ 排盘失败: Can't parse entities: can't find end of the entity starting at byte offset 168 -``` - -## 原因 - -`bot.py` 中 `header` 消息的 Markdown 代码块格式错误。 - -原代码使用字符串拼接，在 ``` 后面加了 `\n`，导致 Telegram Markdown 解析器无法正确识别代码块边界： - -```python -# 错误写法 -header = ( - "```\n" - f"{filename}\n" - "```\n" -) -``` - -## 修复 - -改用三引号字符串，确保 ``` 单独成行： - -```python -# 正确写法 -header = f"""报告见附件 -``` -{filename} -{ai_filename} -``` -""" -``` - -## 修改文件 - -- `services/telegram-service/src/bot.py` 第 293-308 行 diff --git a/docs/concepts/拼好码.md b/docs/concepts/拼好码.md index ed31af7..ba2f1cd 100644 --- a/docs/concepts/拼好码.md +++ b/docs/concepts/拼好码.md @@ -469,4 +469,3 @@ AI 特别适合生成： - [语言层要素](语言层要素.md) - 看懂代码需要掌握的语言层级 - [胶水开发提示词（在线提示词库入口）](../../../prompts/README.md) -- [项目实战：polymarket-dev](../case-studies/polymarket-dev/) diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index 6881da3..cd5eadb 100644 --- a/docs/getting-started/README.md +++ b/docs/getting-started/README.md @@ -37,4 +37,3 @@ ## 🔗 相关资源 - [基础指南](../references) - 核心理念与方法论 - [方法论](../playbooks) - 工具与经验 -- [实战](../case-studies) - 动手实践项目 diff --git a/docs/playbooks/README.md b/docs/playbooks/README.md index 30565fe..8d6ee66 100644 --- a/docs/playbooks/README.md +++ b/docs/playbooks/README.md @@ -26,4 +26,3 @@ ## 🔗 相关资源 - [基础指南](../references) - 核心理念与方法论 - [入门指南](../getting-started) - 从零开始 -- [实战](../case-studies) - 动手实践 diff --git a/docs/references/README.md b/docs/references/README.md index 8829454..eac6efb 100644 --- a/docs/references/README.md +++ b/docs/references/README.md @@ -35,4 +35,3 @@ ## 🔗 相关资源 - [入门指南](../getting-started/) - 从零开始 - [方法论](../playbooks/) - 工具与经验 -- [实战](../case-studies/) - 动手实践 diff --git a/metadata/redirects.yml b/metadata/redirects.yml index 4605704..da3cde1 100644 --- a/metadata/redirects.yml +++ b/metadata/redirects.yml @@ -9,8 +9,6 @@ redirects: to: docs/playbooks/ - from: docs/workflow/ to: docs/playbooks/workflows/ - - from: docs/case-studies/ - to: docs/case-studies/ - from: skills/ to: skills/ - from: prompts/ diff --git a/metadata/taxonomy.yml b/metadata/taxonomy.yml index 8e5a233..c7f3f33 100644 --- a/metadata/taxonomy.yml +++ b/metadata/taxonomy.yml @@ -14,9 +14,6 @@ sections: references: path: docs/references purpose: 清单、模板、强约束、常见坑与审查标准 - case-studies: - path: docs/case-studies - purpose: 实战案例与问题记录 top_level: skills: